merging fork back to main

.claude/skills/rust-code-style/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: rust-code-style
+description: Project conventions for this Yew/WASM frontend — Rust coding style grounded in programmer-cognition research (Felienne Hermans' "The Programmer's Brain") plus Yew 0.23 framework best practices. Use when writing, reviewing, or refactoring code in this project to keep names descriptive, functions short and single-purpose, error handling explicit, Rust idioms (iterators, `?`, exhaustive matching, newtypes) applied consistently, AND Yew components correct (pure `view`, side effects driven by messages not `changed()`, keyed lists, no panics in WASM, deliberate cloning).
+---
+
+# Rust + Yew Code Style
+
+Conventions for writing and reviewing this project's code. It is a **Yew 0.23** WASM single-page app
+(struct components, `yew-router`, `ybc`/Bulma, `gloo-*`, `reqwasm`), so the rules cover both general
+Rust style **and** Yew framework usage. The guiding rule: **write code for the human brain, not the computer.** Code is read far more often than written, so every decision should reduce the reader's cognitive load.
+
+## Core Principles
+
+1. **Optimize for reading, not writing** — code is read ~10x more than written.
+2. **Reduce cognitive load** — working memory holds ~7 items; don't waste slots on cryptic names.
+3. **Make intent explicit** — names reveal purpose without forcing the reader to hold context in their head.
+4. **Favor clear beacons** — readers scan for recognizable patterns; descriptive names beat single letters.
+
+These cash out into four defaults: full names over abbreviations, explicit over implicit, simple over clever, readable over writeable.
+
+## The non-negotiable rule
+
+**Never use single-letter variable names**, except in three narrow cases: tiny (1–2 line) closures with obvious context, math formulas matching standard domain notation (`dx`, `dy`), and generic type parameters (`T`, `U`). When in doubt, use a full name.
+
+## Reference guides
+
+Load the relevant guide when working in that area — each contains DON'T/DO examples:
+
+- **[references/naming.md](references/naming.md)** — variable, loop, iterator, boolean, function, and domain naming; abbreviations; pronounceability.
+- **[references/functions.md](references/functions.md)** — function length (≤25 lines), single responsibility, parameter limits (≤3), nesting depth (≤2), guard clauses.
+- **[references/rust-idioms.md](references/rust-idioms.md)** — explicit signatures, type aliases, newtypes, enums for state, avoiding `unwrap()`/`expect()`, error context, exhaustive matching, `#[must_use]`, iterators, `?`, `let-else`, `LazyLock`/`OnceLock`, `NonZero<T>`, `#[non_exhaustive]`.
+- **[references/organization-and-quality.md](references/organization-and-quality.md)** — module structure, file size limits, comments (why not what), public-API docs, error design, testing conventions, anti-patterns (god objects, magic numbers, clever code).
+- **[references/yew-best-practices.md](references/yew-best-practices.md)** — Yew 0.23 component conventions: pure `view`, side effects from messages (not `changed()`), keyed lists, no panics in WASM (`SessionStorage`/header/JSON `unwrap`), deliberate cloning + `Rc`, `Properties` design, initial-load placement, callbacks, shared context, `yew-router`, and when to use function components + hooks. **Load this whenever touching anything under `src/components/`, `src/pages/`, or `lib.rs`.**
+
+## Code review checklist
+
+Tooling (run first — catches most mechanical issues automatically):
+- [ ] `cargo fmt` applied
+- [ ] `cargo clippy -- -D warnings` passes
+
+Naming and structure:
+- [ ] No single-letter variable names (except the limited exceptions above)
+- [ ] All names are clear and descriptive
+- [ ] Functions are short and focused (<25 lines)
+- [ ] Nesting depth is minimal (≤2 levels) — use `let-else` for destructuring guards
+
+Error handling:
+- [ ] No `unwrap()` or `expect()` in production code
+- [ ] Error handling is explicit with context
+- [ ] String formatting uses capture syntax: `"{val}"` not `"{}"` + val
+
+API design:
+- [ ] Public APIs have documentation
+- [ ] Public enums in library code are `#[non_exhaustive]` if they may grow
+- [ ] Types make invalid states unrepresentable where possible
+
+Yew components (see [references/yew-best-practices.md](references/yew-best-practices.md) for details):
+- [ ] `view` is pure — no I/O, storage writes, `unwrap()`/panics, or heavy computation
+- [ ] No side effects in `changed()` — only prop→state reconciliation (a user action → `Msg` → effect)
+- [ ] Every `.map()`-rendered list element has a stable `key` (uuid/id, not the array index)
+- [ ] No `unwrap()`/`expect()` on `SessionStorage`, response headers, or JSON — route to `Msg::Error`/`Logoff` (WASM panics blank the page)
+- [ ] `.clone()` limited to values moved into closures/`async move`; large shared data uses `Rc<T>`
+- [ ] `Properties` derive `PartialEq`, stay small, pass `Callback`s/ids (or `Rc<…>`) not big owned collections
+- [ ] Initial data loads in `create`/`rendered(first_render)`, never in `view`
+- [ ] In-app navigation uses `yew-router` (`Navigator`/`Link`), not `window.location`
+
+General:
+- [ ] File is ≤500 lines — split by responsibility if over; target is 200–300
+- [ ] Tests are comprehensive with descriptive names
+- [ ] No commented-out code
+- [ ] No magic numbers — all constants are named
+- [ ] Code follows existing patterns in the codebase (struct components stay struct components)
+- [ ] Rust idioms are used (iterators, `?`, `let-else`, pattern matching)

.claude/skills/rust-code-style/references/functions.md

@@ -0,0 +1,125 @@
+# Function Design
+
+## Contents
+- [Keep functions short](#keep-functions-short)
+- [Single Responsibility Principle](#single-responsibility-principle)
+- [Limit function parameters](#limit-function-parameters)
+- [No deep nesting](#no-deep-nesting)
+
+## Keep functions short
+
+**Target:** 5–15 lines. **Maximum:** 25 lines. If longer, extract smaller functions with descriptive names.
+
+## Single Responsibility Principle
+
+Each function does one thing well.
+
+**DON'T:**
+```rust
+fn process_user(id: i32) -> Result<()> {
+    let user = db.fetch(id)?;
+    if user.email.is_empty() { return Err(Error::Invalid); }
+    let perms = calc_perms(&user)?;
+    db.update_perms(user.id, perms)?;
+    email::send(&user.email, "Welcome")?;
+    log::info("User processed: {}", user.id);
+    cache.invalidate(user.id);
+    Ok(())
+}
+```
+
+**DO:**
+```rust
+fn process_user(id: i32) -> Result<()> {
+    let user = fetch_and_validate_user(id)?;
+    grant_user_permissions(&user)?;
+    notify_user_by_email(&user)?;
+    log_user_activity(&user)?;
+    invalidate_user_cache(&user)?;
+    Ok(())
+}
+```
+
+## Limit function parameters
+
+**Maximum:** 3 parameters. If more are needed, use a struct/config object.
+
+**DON'T:**
+```rust
+fn create_user(
+    name: String,
+    email: String,
+    age: i32,
+    role: String,
+    dept: String,
+    manager: String,
+    location: String
+) -> User
+```
+
+**DO:**
+```rust
+struct CreateUserRequest {
+    name: String,
+    email: String,
+    age: i32,
+    role: String,
+    department: String,
+    manager: String,
+    location: String,
+}
+
+fn create_user(request: CreateUserRequest) -> User
+```
+
+## No deep nesting
+
+**Maximum nesting level:** 2. Use early returns, guard clauses, and `let-else` for destructuring guards (stable since 1.65).
+
+**DON'T:**
+```rust
+fn process(data: Option<Data>) -> Result<()> {
+    if let Some(d) = data {
+        if d.is_valid() {
+            if d.has_permission() {
+                if d.is_ready() {
+                    // deeply nested work
+                }
+            }
+        }
+    }
+    Ok(())
+}
+```
+
+**DO:**
+```rust
+fn process(data: Option<Data>) -> Result<()> {
+    let data = data.ok_or(Error::NoData)?;
+
+    if !data.is_valid() {
+        return Err(Error::Invalid);
+    }
+    if !data.has_permission() {
+        return Err(Error::Forbidden);
+    }
+    if !data.is_ready() {
+        return Err(Error::NotReady);
+    }
+
+    // work at top level
+    Ok(())
+}
+```
+
+When the guard involves destructuring, prefer `let-else` over `if let` + nesting:
+
+```rust
+fn process(event: Option<Event>) -> Result<()> {
+    let Some(event) = event else {
+        return Ok(());
+    };
+    // event is in scope here, no extra nesting
+    handle(event)
+}
+```