@wcstack/state 1.30.0 → 1.32.0

package/README.md

@@ -769,19 +769,20 @@ export default {
          + this["regions.*.prefectures.*.cities.*.name"];
   },
 
-  // Prefecture level — aggregate from cities
+  // Prefecture level — aggregate from cities. `indexes` omitted: it defaults to
+  // the loop context ([$1, $2]), so only this prefecture's cities are summed
   get "regions.*.prefectures.*.totalPopulation"() {
-    return this.$getAll("regions.*.prefectures.*.cities.*.population", [])
+    return this.$getAll("regions.*.prefectures.*.cities.*.population")
       .reduce((a, b) => a + b, 0);
   },
 
-  // Region level — aggregate from prefectures
+  // Region level — aggregate from prefectures (context [$1] narrows to this region)
   get "regions.*.totalPopulation"() {
-    return this.$getAll("regions.*.prefectures.*.totalPopulation", [])
+    return this.$getAll("regions.*.prefectures.*.totalPopulation")
       .reduce((a, b) => a + b, 0);
   },
 
-  // Top level — aggregate from regions
+  // Top level — no loop context; [] means "every match"
   get totalPopulation() {
     return this.$getAll("regions.*.totalPopulation", [])
       .reduce((a, b) => a + b, 0);
@@ -872,6 +873,36 @@ Two-way binding works with path setters — editing the input calls the setter,
 
 4. **Direct index access** — You can also access specific elements by numeric index: `this["users.0.name"]` resolves as `users[0].name` without needing loop context.
 
+### Getters must be pure with respect to state
+
+A getter's cache is invalidated **only** through the dependency graph, and the graph only records what the getter read **through `this`**. Anything else a getter reads is invisible to invalidation, so the first value computed is the value you keep:
+
+```javascript
+// ❌ Never recomputes — nothing in the dependency graph ever changes
+get stamp() { return `${this.label} @ ${Date.now()}`; }   // Date.now() is untracked
+get theme() { return document.body.dataset.theme; }        // the DOM is untracked
+get total() { return this.price * exchangeRate; }          // a module variable is untracked
+```
+
+The rule: **read only through `this`, and don't write state or touch the DOM from a getter.** For the cases where an untracked input genuinely has to participate, put the input into state and assign to it (the normal path-assignment contract), or use the escape hatches:
+
+| API | Use it for |
+|---|---|
+| `this.$trackDependency(path)` | Register an extra dependency so this getter is dirtied when that path changes |
+| `this.$postUpdate(path)` | Announce that an untracked input changed, from outside the getter |
+| `this.$untrackDependency(fn)` | Read a path *without* registering it as a dependency (the inverse) |
+
+```javascript
+// ✅ The clock ticks in state; the getter stays pure
+export default {
+  now: Date.now(),
+  get stamp() { return `${this.label} @ ${this.now}`; },
+  $connectedCallback() { setInterval(() => { this.now = Date.now(); }, 1000); },
+};
+```
+
+Getters that throw are not swallowed: the exception surfaces where the getter was evaluated (a binding apply, a `$watch` evaluation, or your own read).
+
 ### Loop Index Variables (`$1`, `$2`, ...)
 
 Inside getters and event handlers, `this.$1`, `this.$2`, etc. provide the current loop iteration index (0-based value, 1-based naming):
@@ -913,6 +944,7 @@ Inside state objects (getters / methods), the following APIs are available via `
 | API | Description |
 |---|---|
 | `this.$getAll(path, indexes?)` | Get all values matching a wildcard path |
+| `this.$setAll(path, indexes, value, options?)` | Write to every address matching a wildcard path |
 | `this.$resolve(path, indexes, value?)` | Resolve a wildcard path with specific indexes |
 | `this.$postUpdate(path)` | Manually trigger update notification for a path |
 | `this.$trackDependency(path)` | Manually register a dependency for cache invalidation |
@@ -938,6 +970,66 @@ export default {
 };
 ```
 
+`indexes` is a **prefix** over the path's wildcards: missing levels expand fully, and `[]` always means "every match". When `indexes` is **omitted**, it defaults to the enclosing loop context (`[$1, $2, ...]`), applied to the wildcard levels the path shares with that context:
+
+```javascript
+export default {
+  regions: [ /* { prefectures: [ { population: … }, … ] } */ ],
+  // Loop context [$1] — omission narrows to the current region
+  get "regions.*.total"() {
+    return this.$getAll("regions.*.prefectures.*.population").reduce((a, b) => a + b, 0);
+  },
+  // No loop context — omission expands everything (same as [])
+  get grandTotal() {
+    return this.$getAll("regions.*.total").reduce((a, b) => a + b, 0);
+  }
+};
+```
+
+Context levels deeper than the path needs are dropped (a `[$1, $2]` context narrows a one-wildcard path by `[$1]`). But if the path shares **no** wildcard level with a context that does hold loop indexes — say `$getAll("users.*.name")` inside a `regions.*` getter — `$getAll` **throws** instead of silently reading every user: the context indexes belong to a different list, and neither reusing nor ignoring them is what the author meant. Pass indexes explicitly there (`[]` for every match).
+
+#### `$setAll` — Update Every Array Element In Place
+
+`$setAll` is the write-side counterpart of `$getAll`: it writes to every address a wildcard path matches. The point is not brevity but **keeping the array itself**. Rebuilding it (`this.users = this.users.map(...)`) throws away the list indexes, the per-row getter caches, and the render diff; `$setAll` decomposes into in-place per-row writes instead, so the list identity survives.
+
+```javascript
+export default {
+  users: [{ selected: false }, { selected: false }],
+
+  toggleAll(e) {
+    this.$setAll("users.*.selected", [], e.target.checked);   // broadcast
+  },
+  invertAll() {
+    this.$setAll("users.*.selected", [], cur => !cur);        // mapper
+  },
+  rankTopThree() {
+    // `undefined` skips that address — "leave this row alone"
+    this.$setAll("users.*.score", [], (cur, i) => i < 3 ? cur * 2 : undefined);
+  }
+};
+```
+
+Three forms, and the third one has to be asked for explicitly:
+
+| Third argument | Meaning |
+|---|---|
+| a function | **mapper** — called as `(current, ...indexes)` per matched address |
+| anything else | **broadcast** — the same value is written everywhere, arrays included |
+| an array **plus** `{ spread: true }` | **spread** — one entry handed to each matched address, in match order |
+
+Arrays broadcast by default because the target property may itself be array-valued — `$setAll("users.*.tags", [], ["admin"])` would otherwise be ambiguous. Opting into `{ spread: true }` removes the guesswork, and a length that does not equal the match count throws rather than silently misaligning.
+
+`indexes` works exactly as in `$getAll` — a **prefix**, where missing levels mean "expand all of them" — but it is **required**. Writes get no implicit loop context, so inside a `for` template `this.$setAll("users.*.selected", [], true)` still means *every* user, never the current row.
+
+```javascript
+this.$setAll("matrix.*.*", [0], 0);        // row 0 only, every column
+this.$setAll("users.*", [], rows, { spread: true });   // replace each row, keep the array
+```
+
+`undefined` is never written — it means "skip this address" in all three forms, which keeps a mapper that forgets to `return` from wiping every row. Use `null` to clear. The return value is the number of addresses actually written.
+
+One thing `$setAll` is not: a shortcut for the dependency walk. Rendering still coalesces into a single batch, but each write is enqueued individually, so the cost matches the hand-written loop it replaces. What it buys you is the preserved list, not fewer cycles.
+
 #### `$resolve` — Access by Explicit Index
 
 `$resolve` reads or writes a value at a specific wildcard index:
@@ -1632,6 +1724,48 @@ Key rules:
 
 See [docs/streams.md](docs/streams.md) for the full contract — lifecycle and ownership, restart semantics, flush granularity, and the out-of-scope list.
 
+## Demand roots — what makes a getter run
+
+Path getters are **lazy**. One that nobody reads is never evaluated. So "does this getter run?" is not answerable from the getter itself — it depends on **where the demand comes from**.
+
+There are exactly **three** demand roots:
+
+| Root | Lives in | Depends on rendering |
+|---|---|---|
+| **A live DOM binding** | `data-wcs` / mustache / comment bindings | **Yes** — remove the element and the demand goes with it |
+| **A `$watch` declaration** | the state | No (headless) |
+| **A `$streams` `args` function** | the state | No (evaluated on start and on every restart) |
+
+**`$updatedCallback` is not a root.** It reports what the bindings did; it does not create demand.
+
+### Rendering can change program semantics
+
+Because the first root lives in the DOM, **an element you think of as display-only can be the actual subscription**. This one was hit for real, in [`examples/state-intersect-scroll`](../../examples/state-intersect-scroll):
+
+```html
+<!-- Meant as display. It was the only demand root. -->
+<b data-wcs="textContent: $streamStatus.pageResult"></b>
+```
+
+```javascript
+// $updatedCallback is binding-driven — delete that <b> and the path stops
+// appearing in `paths`, so the feed silently stops committing.
+$updatedCallback(paths) {
+  if (!paths.includes("$streamStatus.pageResult")) return;
+  this.items = this.items.concat(this.pageResult.items);
+}
+```
+
+**The rule:** logic that must not depend on what is rendered belongs on a `$watch` (or a `$streams` `args`). Keep `$updatedCallback` for "follow what was drawn".
+
+That example now uses `$watch`, and the `<b>` is display-only again. This shape — `$updatedCallback` testing a path that is not bound anywhere — is detected statically as **`wcs/updated-callback-unbound`**.
+
+### The limitation that remains
+
+Demand still comes from three separate places. **To know whether a getter is evaluated you have to inspect all three — every binding on the page, every `$watch`, and every `$streams` `args` — and reading the getter's definition will not tell you.** The linter and the DevTools wiring-coverage view exist to make a machine do that cross-check.
+
+Note that a scalar getter named in `$watch` becomes **eager** (evaluated once at connect, then at the end of every batch touching its dependencies). Wildcard row getters do not become eager, because the first evaluation would walk the whole list.
+
 ## Watch (`$watch`)
 
 `$updatedCallback` is **binding-driven**: it reports the paths whose live DOM bindings were actually applied in that update, so a value you never render is invisible to it. **`$watch`** is the headless counterpart — it fires on state changes whether or not anything on the page is bound to the path. (One exception, spelled out below: a *wildcard* row path needs `$listKeys` to work headlessly.)
@@ -1683,6 +1817,8 @@ Firing order is defined in three layers, and only the middle one is yours to ste
 | Between handlers | declaration order in `$watch` | **reorder the declarations** |
 | Between rows of one path | ascending `indexes` | fixed |
 
+**The one thing that moves the mechanism layer** is a `<wcs-view-transition>` that accepts the `state` participant. Binding application — and with it `$updatedCallback` — then lands on a frame, while `$watch` and the `$streams` restart stay on the microtask the drain was queued on, because they consume state addresses and not the DOM. For as long as the tag is present the order is `$watch` → `$streams` restart → `$updatedCallback`. Nothing else on the page reorders this layer; see [docs/timing-and-firing-contract.md](https://github.com/wcstack/wcstack/blob/main/docs/timing-and-firing-contract.md) §4.3.
+
 Key rules:
 
 - **Only its own state** — a path may not carry `@stateName`; watching another state element is rejected at declaration time.
@@ -1944,6 +2080,101 @@ All hooks except `$disconnectedCallback` support `async` — you can use `async/
 - `$updatedCallback(paths, indexesListByPath)` receives the paths whose live bindings were applied in that drain. Unbound state writes do not invoke it or appear in `paths`. For wildcard updates, `indexesListByPath` contains the updated index sets. Can be `async`, but the return value is not awaited
 - In Web Components, define `async $stateReadyCallback(stateProp)` to receive a hook when the bound state becomes available via `bind-component`
 
+## Transition animations
+
+Enter animations need nothing from this package — a new `for` row and a mounting `if` branch are newly inserted elements, so plain CSS covers them:
+
+```css
+li {
+  transition: opacity 0.2s, transform 0.2s;
+  @starting-style { opacity: 0; transform: translateY(-4px); }
+}
+```
+
+**Leaving** and **moving** cannot be reached that way: removed rows are detached synchronously, and a reorder has no intermediate state. Adding [`@wcstack/view-transition`](https://github.com/wcstack/wcstack/tree/main/packages/view-transition) makes the drain apply its DOM changes inside a View Transition, where the browser snapshots the old state for you:
+
+```html
+<script type="module" src="https://esm.run/@wcstack/view-transition/auto"></script>
+<wcs-view-transition naming="auto"></wcs-view-transition>
+```
+
+Two consequences to know while that tag accepts the `state` participant:
+
+- The drain lands on a frame instead of a microtask, so code that writes state and then reads the DOM after `await Promise.resolve()` must wait for the transition. `$updatedCallback` still fires immediately after the bindings are applied — its *position* is unchanged, but it moves a frame later along with them.
+- Because `$watch` and the `$streams` restart stay on the original microtask, they now run **before** `$updatedCallback` instead of after it.
+
+Only a batch that actually has bindings to apply is handed to the tag, so a write to a headless path never starts a transition. Without the tag the drain is exactly what it was. See [docs/timing-and-firing-contract.md](https://github.com/wcstack/wcstack/blob/main/docs/timing-and-firing-contract.md) §4.3.
+
+## Diagnostics and failure handling
+
+### Wiring to a path that does not exist is reported
+
+When a wired path provably does not resolve against the state, you get one warning at binding time (at declaration time for `$watch`). The diagnostic codes are shared by the console, `@wcstack/lint`, and the VS Code extension:
+
+```
+[@wcstack/state] [wcs/binding-path-missing] Bound path "user.nmae" does not resolve on state "default":
+"nmae" is not declared. Did you mean "name"? Updates to this path will be silently
+dropped. Validate statically: npx @wcstack/lint <file>.
+```
+
+| Situation | Behavior |
+|---|---|
+| Typo in a nested path (`user.nmae`) | `console.warn` (`wcs/binding-path-missing`). Updates still never arrive — you fix it |
+| Typo in a top-level path (`cout`) | Throws on read, with the same wording and did-you-mean |
+| Typo in a `$watch` key | `console.warn` (`wcs/watch-path-missing`), reported even for a single segment |
+
+The check **under-approximates**: it stays silent for anything it cannot decide statically, because a false alarm costs more than a missed one. None of these warn:
+
+- A `null` / `undefined` parent (the "seed as `null`, assign later" shape)
+- Row fields of a list that starts empty (the row shape is unknown)
+- Sub-properties of an intermediate getter's return value
+- Mapped `bind-component` child scopes (the parent owns the path)
+- Reserved `$` namespaces (`$command.*` and friends)
+
+So **no warning is not a proof of correctness.** For exhaustive checking, run `npx @wcstack/lint <file>`.
+
+### Index arity, wildcard rank, and getter cycles are checked too
+
+Anything that follows mechanically from the path string is reported at runtime and by the linter under the same diagnostic code.
+
+| Diagnostic | What it checks | Fix |
+|---|---|---|
+| `wcs/index-arity` | `$resolve(path, indexes)` must match the `*` count **exactly**; `$getAll(path, indexes)` / `$setAll(path, indexes, …)` have it as an **upper bound** (fewer is a legitimate prefix meaning "expand the rest") | Match the count |
+| `wcs/wildcard-rank` | The path's `*` count (and the N in `$N`) must not exceed the enclosing `for` nesting | Add a `for`, or name the row with `$resolve(path, indexes)` |
+| `wcs/getter-cycle` | Path getters must not form a dependency cycle | Break the cycle |
+
+Previously **extra indexes were silently discarded** by both APIs, so a mixed-up call returned a plausible-looking wrong value. Both now throw:
+
+```javascript
+// ❌ Only one "*" in the path, two indexes given — used to return items[0]'s value
+this.$resolve("items.*.price", [row, col]);
+
+// ✅ Two levels, two indexes
+this.$resolve("matrix.*.*", [row, col]);
+// ✅ Fewer is fine for $getAll — it means "expand the remaining levels"
+this.$getAll("matrix.*.*", [row]);
+```
+
+### One failing binding is confined to that binding
+
+If applying a binding throws, the rest of that batch, `$updatedCallback`, `$watch`, and `$streams` restarts all still run. The failure is not swallowed — it goes to `console.error` and to DevTools (`state:binding-apply-error`):
+
+```
+[@wcstack/state] binding "text: items.*.label" failed to apply; the rest of this batch continues.
+```
+
+Without that confinement, a single throw left "new values, half-updated DOM" behind, and silently dropped every `$watch` handler and stream restart for the batch — quietly breaking the firing-order contract documented above.
+
+### Values and the DOM are never rolled back
+
+Every failure mode reports and continues; nothing already applied is reverted:
+
+| Mechanism | Limit | On exceeding |
+|---|---|---|
+| Propagation hops | 32 | Quarantine the transaction's remaining records |
+| `$watch` write chain | 32 | Skip watch firing for that batch |
+| Binding apply failure | — | Skip that one binding |
+
 ## Configuration
 
 Pass a partial configuration object to `bootstrapState()`:
@@ -1965,13 +2196,43 @@ All options with defaults:
 |---|---|---|
 | `bindAttributeName` | `'data-wcs'` | Binding attribute name |
 | `tagNames.state` | `'wcs-state'` | State element tag name |
-| `locale` | `'en'` | Default locale for filters |
+| `locale` | `<html lang>`, else `'en'` | Locale for the locale-dependent filters (`locale` / `date` / `time` / `datetime`) — see [Locale](#locale) |
 | `debug` | `false` | Debug mode |
 | `enableMustache` | `true` | Enable `{{ }}` syntax |
 | `enableDirectionalInitialSync` | `true` | Direction-aware binding authority (`#init=` / `#sync=` binding modifiers) — see [Binding Authority](#binding-authority-init--sync). Default on; set `false` to opt out |
 | `enablePropagationContext` | `true` | Causal propagation tracking across bindings (echo/diamond loop prevention). Default on; set `false` to opt out |
 | `enableContractAnalyzer` | `false` | Opt-in dev-time contract analyzer (exposes `analyzeContract`) |
 
+### Locale
+
+Four filters format by locale — `locale`, `date`, `time`, `datetime`. They read
+`config.locale`, which **defaults to `<html lang>`**:
+
+```html
+<html lang="ja-JP">
+  <script type="module" src="https://esm.run/@wcstack/state/auto"></script>
+```
+
+Nothing else is needed; `<html lang>` is the standard place to record a page's
+language, and making it the default keeps one source of truth. It also means the
+CDN one-liner can set the locale at all — `auto` calls `bootstrapState()` with no
+arguments, so before this there was no way in. An explicit
+`bootstrapState({ locale })` still wins, and an invalid BCP-47 tag is reported
+and ignored rather than left to throw inside `Intl`.
+
+**Changing `config.locale` later does not re-render anything.** It is a global
+setting, not state, so it is not part of the dependency graph. The filters do
+read it on every application rather than capturing it when the binding is built,
+which means a binding that re-renders for its own reasons will pick up the new
+value — enough to recover from a mis-ordered startup, not enough to switch a
+page's language. Set the language before the page renders: writing `<html lang>`
+in the markup, or from a synchronous `<head>` script, does that structurally.
+
+Per-call overrides stay available and are fixed at bind time, since they are part
+of the binding expression: `price|locale(fr-FR)`. For a page that switches
+language without reloading, see [docs/i18n-design.md](../../docs/i18n-design.md) —
+the short answer is that translations belong on a path, not in a filter.
+
 > These three are **architecture-hardening** features; their normative reference is
 > `docs/architecture-hardening/`. `enablePropagationContext` defaults **on** — its
 > write-path cost is near-zero for one-way bindings (only echo-capable two-way