@wcstack/state 1.31.0 → 1.33.0

package/README.md

@@ -236,6 +236,8 @@ Multiple state elements can coexist with the `name` attribute. Bindings referenc
 
 Default name is `"default"` (no `@` needed).
 
+> **Deprecated — removed in v2.** The `name` attribute and the `@name` selector are a second axis next to the path (a per-rootNode registry that does not cross shadow boundaries). v2 replaces them with **mounts**: `<wcs-state mount="cart">` grafts the state onto the root tree, and bindings read it as `cart.total`. Nothing changes in 1.x; the linter reports the sites as `wcs/named-state-deprecated` (warning) and the runtime warns only under `config.debug`. Migration table: [docs/state-mount-design.md](../../docs/state-mount-design.md) §9.
+
 ## Updating State
 
 In `@wcstack/state`, every piece of state has a **path** — like `count`, `user.name`, or `items`. To update state reactively, **assign to the path**:
@@ -769,19 +771,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);
@@ -943,6 +946,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 |
@@ -968,6 +972,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:
@@ -1193,6 +1257,47 @@ customElements.define("my-light-component", MyLightComponent);
 - `data-wcs="state.message: user.name"` on the host element binds outer state paths to inner component state properties
 - Changes propagate bidirectionally between the component and the outer state
 
+### Whole-object Mount (`state: path`)
+
+Instead of wiring the component's state property by property, the host can mount a **whole subtree** of its state as the component's root. Inside the component every path is then relative to the mount point:
+
+```html
+<!-- Host -->
+<wcs-state json='{"user":{"name":"Alice","email":"alice@example.com"},"theme":{"mode":"light"}}'></wcs-state>
+<user-card data-wcs="state: user"></user-card>
+```
+
+```javascript
+// Component (Shadow DOM)
+class UserCard extends HTMLElement {
+  state = {
+    // a getter computed over the mount — `this.name` is the tree's `user.name`
+    get display() { return `${this.name} <${this.email}>`; },
+  };
+  constructor() {
+    super();
+    this.attachShadow({ mode: "open" });
+  }
+  connectedCallback() {
+    this.shadowRoot.innerHTML = `
+      <wcs-state bind-component="state"></wcs-state>
+      <span data-wcs="textContent: name"></span>
+      <span data-wcs="textContent: display"></span>
+      <input data-wcs="value: name">
+    `;
+  }
+}
+customElements.define("user-card", UserCard);
+```
+
+- `state: user` mounts the component's root at the tree path `user`: `name` inside the component **is** `user.name`. Reads, writes (`value: name`, `this.state.name = ...`), getters and `for:` all resolve against the tree; the host's `this.user = {...}` replacement and `this["user.name"] = ...` writes both reach the component.
+- A partial mount can sit next to it: `state: user; state.theme: theme` mounts `theme` as a second entry point (longest prefix wins, so `theme.mode` inside the component reads the tree's `theme.mode`).
+- In a loop, mount **the row itself**: `<template data-wcs="for: users"><user-row data-wcs="state: ."></user-row></template>`. Inside the row component `name` is `users.*.name`, and its own `for: tags` runs over `users.*.tags.*`.
+- **Own keys are private** (rule R1 in [docs/state-mount-design.md](../../docs/state-mount-design.md) §4-3): a data key the component declares itself (`state = { mode: "view" }`) belongs to that element and is never written to the tree. If it hides a key that exists at the mount point (`state = { name: "" }` mounted over `user.name`), the runtime warns once (`wcs/mount-own-key-shadow`) — remove the default to read the tree, or rename it to keep it private.
+- Mounting an array as the root (`state: rows` with `for` over it inside) is not supported in 1.x; mount the row (`state: .`) or the object that holds the array (`state: group` with `for: children` inside). Both forms are contract-tested and carry over unchanged to v2, where mounts become the only way to extend the tree.
+
+> The per-property form (`state.message: user.name`) keeps working. A component that declares a default for a mapped key (`state = { message: "" }` together with `state.message: ...`) gets a one-time warning in 1.x: today the host value wins, in v2 the own key becomes private and would hide it — drop the default.
+
 ### Standalone Web Component Injection (`__e2e__/single-component`)
 
 Even when a component is independent from outer host state, you can inject reactive state with `bind-component`.
@@ -1240,6 +1345,11 @@ customElements.define("my-component", MyComponent);
 <template data-wcs="for: users">
   <my-component data-wcs="state.message: .name"></my-component>
 </template>
+
+<!-- or mount the row itself: inside the component, `name` is `users.*.name` -->
+<template data-wcs="for: users">
+  <user-row data-wcs="state: ."></user-row>
+</template>
 ```
 
 ### Rendering a List Inside the Component
@@ -1755,6 +1865,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.
@@ -2016,6 +2128,31 @@ 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
@@ -2050,7 +2187,7 @@ Anything that follows mechanically from the path string is reported at runtime a
 
 | Diagnostic | What it checks | Fix |
 |---|---|---|
-| `wcs/index-arity` | `$resolve(path, indexes)` must match the `*` count **exactly**; `$getAll(path, indexes)` has it as an **upper bound** (fewer is a legitimate prefix meaning "expand the rest") | Match the count |
+| `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 |
 
@@ -2107,13 +2244,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
@@ -2127,6 +2294,122 @@ All options with defaults:
 > `analyzeContract()` API reports drift between a live `static wcBindable` surface and
 > a sidecar manifest for dev-time diagnostics.
 
+## Testing Your Page
+
+A page built on `<wcs-state>` is plain DOM, so it can be tested headlessly with [happy-dom](https://github.com/capricorn86/happy-dom) — no browser, no build step, no test-only API. Three recipes follow; every one of them runs as written (recipe 1 is pinned by [`__tests__/readme.testingRecipe.test.ts`](__tests__/readme.testingRecipe.test.ts), which executes the same lines).
+
+Want it as one import? [`@wcstack/testing`](../testing/README.md) packages recipe 1 as `mount()` / `settle()` / `fire()` (and waits for `<wcs-router>` too). The bare recipes below stay valid without it.
+
+### 1. vitest + happy-dom
+
+`vitest.config.ts`:
+
+```ts
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: { environment: "happy-dom", setupFiles: ["./tests/setup.ts"] },
+});
+```
+
+`tests/setup.ts` — register the elements once, and route inline `<script type="module">` state through the `data:` URL loader (Node cannot import `blob:` URLs; without this line an inline-script state never finishes loading):
+
+```ts
+import { bootstrapState } from "@wcstack/state";
+
+bootstrapState();
+URL.createObjectURL = undefined as any;
+```
+
+A test:
+
+```ts
+import { expect, it } from "vitest";
+import { getBindingsReady } from "@wcstack/state";
+
+const settle = () => new Promise<void>((r) => setTimeout(r, 0));
+
+it("renders, re-renders, and runs handlers", async () => {
+  // 1. Mount the fragment under test
+  document.body.innerHTML = `
+    <wcs-state json='{"count": 1, "items": ["apple", "banana"]}'></wcs-state>
+    <p id="count" data-wcs="textContent: count"></p>
+    <ul id="items">
+      <template data-wcs="for: items">
+        <li data-wcs="textContent: items.*"></li>
+      </template>
+    </ul>
+  `;
+
+  // 2. Wait for the state element, then for every binding under `document`
+  const stateEl = document.querySelector("wcs-state") as any;
+  await stateEl.connectedCallbackPromise;
+  await getBindingsReady(document);
+
+  // 3. Assert the initial render
+  expect(document.querySelector("#count")!.textContent).toBe("1");
+  expect(document.querySelectorAll("#items li").length).toBe(2);
+
+  // 4. Write through a writable proxy — exactly what a handler does
+  await stateEl.createStateAsync("writable", async (state: any) => {
+    state.count = 42;
+    state.items = [...state.items, "cherry"];
+  });
+  await settle();
+
+  // 5. Assert the re-render
+  expect(document.querySelector("#count")!.textContent).toBe("42");
+  expect(document.querySelectorAll("#items li").length).toBe(3);
+});
+```
+
+To drive the page the way a user does, keep the state inline (methods included) and dispatch DOM events; a `data-wcs="onclick: up"` handler runs on `button.click()`, and the DOM reflects the write after one `settle()`.
+
+- `getBindingsReady(root)` resolves once every binding under `root` (a `document` or a shadow root) is built, and rejects if binding initialization fails (v1.26+).
+- Updates settle on the microtask queue; a single `setTimeout(0)` after a write is enough.
+- `state.items = [...state.items, "cherry"]` is the reactive form — `state.items.push()` is not observed (same rule as in handlers).
+- Under happy-dom, `customElements.define` upgrades existing nodes by **replacing** them; "a value reaches the same node after a late define" cannot be asserted headlessly. Event timing differences between happy-dom and real browsers are the other blind spot — keep one browser e2e (Playwright) for those.
+- happy-dom's `textContent` setter turns a numeric `0` into an empty string (browsers render `"0"`), so a `textContent: count` binding reads `""` at zero in this recipe. Assert on the state value, or use `@wcstack/testing`, whose `mount()` shims the setter.
+
+### 2. Bare Node (no vitest)
+
+`@wcstack/server` already exports the globals swap it uses for SSR; reuse it. **Import `@wcstack/state` dynamically after `installGlobals`** — the element classes pick their base class when the module is evaluated, so a static import at the top of the file registers elements that happy-dom cannot construct:
+
+```js
+import { Window } from "happy-dom";
+import { installGlobals } from "@wcstack/server";
+
+const window = new Window({ url: "http://localhost/" });
+const restore = installGlobals(window);   // document, customElements, HTMLElement, ... (GLOBALS_KEYS)
+try {
+  const { bootstrapState, getBindingsReady } = await import("@wcstack/state");
+  bootstrapState();
+  // ... the same mount / await / assert steps as recipe 1
+} finally {
+  restore();
+  await window.happyDOM.close();
+}
+```
+
+`installGlobals` also disables `URL.createObjectURL` for you, so inline-script state loads the same way as in recipe 1.
+
+### 3. Snapshot the rendered HTML
+
+[`renderToString()`](../server/README.md) from `@wcstack/server` returns the fully rendered markup as a string; compare it against a stored snapshot:
+
+```ts
+import { expect, it } from "vitest";
+import { renderToString } from "@wcstack/server";
+
+it("matches the rendered snapshot", async () => {
+  const html = await renderToString(`
+    <wcs-state json='{"items": ["apple", "banana"]}' enable-ssr></wcs-state>
+    <ul><template data-wcs="for: items"><li data-wcs="textContent: items.*"></li></template></ul>
+  `);
+  expect(html).toMatchSnapshot();
+});
+```
+
 ## TypeScript Support
 
 `defineState()` wraps your state object and provides type-safe `this` inside methods and getters — with zero runtime cost (identity function).