@wcstack/state 1.25.0 → 1.27.0

package/README.md

@@ -95,7 +95,7 @@ That's it. No build, no bootstrap code, no framework.
 - **Declarative data binding** — `data-wcs` attribute for property / text / event / structural binding
 - **Reactive Proxy** — ES Proxy-based automatic DOM updates with dependency tracking
 - **Structural directives** — `for`, `if` / `elseif` / `else` via `<template>` elements
-- **Built-in filters** — 40 filters for formatting, comparison, arithmetic, date, and more
+- **Built-in filters** — 46 filters for formatting, comparison, arithmetic, date, and more
 - **Two-way binding** — automatic for `<input>`, `<select>`, `<textarea>`
 - **Web Component binding** — bidirectional state binding with Shadow DOM components
 - **Command tokens** — invoke methods on wc-bindable custom elements from state via a pub/sub channel (`command.<method>: tokenName`)
@@ -220,6 +220,8 @@ That's it. No build, no bootstrap code, no framework.
 
 Resolution order: `state` → `src` (.json / .js) → `json` → inner `<script>` → wait for `setInitialState()`.
 
+> **Under a Content-Security-Policy:** form 5 (inline `<script type="module">`) is evaluated through a `blob:` URL and therefore requires `script-src blob:`. A page nonce does not cover it. If you enforce a strict CSP, use form 4 (`src="./state.js"`) instead — it needs no extra directive. See [docs/csp.md](../../docs/csp.md).
+
 ### Named State
 
 Multiple state elements can coexist with the `name` attribute. Bindings reference them with `@name`:
@@ -441,7 +443,7 @@ Internally converted to comment-based bindings (`<!--@@:expression-->`).
 
 ### Spread Binding (`...`)
 
-For custom elements that declare the [`wc-bindable` protocol](#wcbindable-protocol), `...: target` wires all of the element's **properties + inputs** to a single state object in one line:
+For custom elements that declare the [`wc-bindable` protocol](#bindables--commands-and-the-wc-bindable-protocol), `...: target` wires all of the element's **properties + inputs** to a single state object in one line:
 
 ```html
 <wcs-fetch data-wcs="...: usersFetch"></wcs-fetch>
@@ -507,7 +509,42 @@ Structural directives use `<template>` elements:
 </template>
 ```
 
-The `for:` directive uses a **value-based diff algorithm** — each array element's value itself serves as the identity key. There is no need for an explicit `key` attribute (like React's `key` or Vue's `:key`). When the array is reassigned, the differ matches old and new elements by value, reusing existing DOM nodes for unchanged items and efficiently adding, removing, or reordering the rest.
+The `for:` directive uses a **value-based diff algorithm** — each array element's value itself serves as the identity key. When the array is reassigned, the differ matches old and new elements by value, reusing existing DOM nodes for unchanged items and efficiently adding, removing, or reordering the rest.
+
+This means **no explicit `key` attribute is needed for adding, removing, or reordering rows** (like React's `key` or Vue's `:key`) — as long as row objects keep their references. Non-destructive array methods (`toSorted`, `toReversed`, `filter`, `with`, `toSpliced`) all preserve element references, so sorting and filtering are keyed by construction, and the whole class of "wrong key" bugs cannot occur.
+
+The exception is data that arrives as **freshly created objects** — `fetch(...).json()`, `JSON.parse` from storage, a WebSocket/SSE full snapshot, or a Worker `postMessage`. Those rows never match by reference, so every row is torn down and rebuilt. See [`$listKeys`](#listkeys--identity-for-refetched-rows) below.
+
+#### `$listKeys` — identity for refetched rows
+
+When rows carry DOM state the bindings do not own — focus, an in-flight IME composition, `<details>` open state, inner scroll position, `<canvas>` contents, `<video>` playback — rebuilding the rows loses it. Declare a key so the framework can recognize rows across a refresh:
+
+```js
+{
+  items: [],
+  $listKeys: {
+    "items": "id",                        // field name
+    "items.*.children": (row) => row.uid, // or a function, for composite keys
+  },
+}
+```
+
+With a key declared, assigning a new array **keeps the existing row objects** and writes only the fields that actually changed into them. The row's DOM is reused rather than rebuilt:
+
+```js
+// Every row object is new, but rows are matched by id — DOM, focus and
+// <details> state survive, and only the fields that differ are written.
+this.items = await (await fetch("/api/items")).json();
+```
+
+Notes:
+
+- **Opt-in and per-path.** Lists without a declaration behave exactly as before, at no cost.
+- **Nesting is opt-in too.** Only declared paths are matched by key; undeclared nested arrays are replaced by reference as usual. This lets you adopt it one list at a time.
+- **A no-op refresh is free.** If nothing changed, no field is written and no DOM work happens at all.
+- **Rows must be plain objects**, and keys must be present and unique. Duplicate keys, missing keys, and class instances raise an error immediately rather than degrading silently.
+- **Fields dropped from a row are cleared with `null`**, which is this package's vocabulary for an explicit clear (`undefined` means "the state has no opinion" and skips the write).
+- The stored array is rebuilt from matched row objects, so `this.items !== theArrayYouAssigned` afterwards.
 
 #### Dot Shorthand
 
@@ -949,7 +986,7 @@ export default {
 
 ## Filters
 
-40 built-in filters are available for both input (DOM → state) and output (state → DOM) directions.
+46 built-in filters are available for both input (DOM → state) and output (state → DOM) directions.
 
 ### Comparison
 
@@ -972,6 +1009,8 @@ export default {
 | `mul(n)` | Multiply | `price\|mul(1.1)` |
 | `div(n)` | Divide | `total\|div(100)` |
 | `mod(n)` | Modulo | `index\|mod(2)` |
+| `abs` | Absolute value | `delta\|abs` |
+| `clamp(min, max)` | Constrain to a range | `ratio\|clamp(0,100)` |
 
 ### Number Formatting
 
@@ -983,6 +1022,7 @@ export default {
 | `ceil(n?)` | Ceiling | `value\|ceil` |
 | `locale(loc?)` | Locale number format | `count\|locale` / `count\|locale(ja-JP)` |
 | `percent(n?)` | Percentage format | `ratio\|percent(1)` |
+| `unit(u)` | Append a unit (any suffix) | `width\|unit(px)` → `"40px"` |
 
 ### String
 
@@ -997,6 +1037,8 @@ export default {
 | `pad(n, char?)` | Pad start | `id\|pad(5,0)` → `"00001"` |
 | `rep(n)` | Repeat | `text\|rep(3)` |
 | `rev` | Reverse | `text\|rev` |
+| `truncate(n, suffix?)` | Shorten and append an ellipsis | `title\|truncate(20)` |
+| `join(sep?)` | Join an array (default `", "`) | `tags\|join` / `tags\|join(/)` |
 
 ### Type Conversion
 
@@ -1017,6 +1059,7 @@ export default {
 | `time(loc?)` | Time format | `timestamp\|time` |
 | `datetime(loc?)` | Date + Time | `timestamp\|datetime(en-US)` |
 | `ymd(sep?)` | YYYY-MM-DD | `timestamp\|ymd` / `timestamp\|ymd(/)` |
+| `hms(sep?)` | HH:MM:SS | `timestamp\|hms` / `timestamp\|hms(-)` |
 
 ### Boolean / Default
 
@@ -1089,6 +1132,18 @@ customElements.define("my-light-component", MyLightComponent);
 - Bindings must explicitly reference the state name with `@my-light`
 - `<wcs-state>` must be a direct child of the component element
 
+- Binding from the host (`<my-light-component data-wcs="state.message: user.name">`) works just as it
+  does for Shadow DOM. The component's subtree is treated as an **independent binding scope** and is
+  wired once the component's own state has registered its name
+
+> **Note**: Light DOM shares its namespace with the parent scope, so **two instances carrying the same
+> `name` cannot live in one scope**. Use Shadow DOM for shapes that place a component on every row of
+> a list.
+>
+> Also, `State.getBindingsReady(root)` does not cover the component's scope — the same as the Shadow
+> DOM form, where the child lives in a different rootNode. Await the component's own `<wcs-state>`
+> initialization when you need to wait for its contents to render.
+
 ### Host Usage
 
 ```html
@@ -1157,6 +1212,50 @@ customElements.define("my-component", MyComponent);
 </template>
 ```
 
+### Rendering a List Inside the Component
+
+An array can be bound into a component and iterated with `for:` **inside** it. The outer state
+stays the source of truth; row additions, removals, reordering and row-field writes flow both ways.
+
+```html
+<!-- Host -->
+<wcs-state json='{"rows":[{"name":"Alice"},{"name":"Bob"}]}'></wcs-state>
+<my-list data-wcs="state.items: rows"></my-list>
+```
+
+```javascript
+// Component (Shadow DOM)
+this.shadowRoot.innerHTML = `
+  <wcs-state bind-component="state"></wcs-state>
+  <ul>
+    <template data-wcs="for: items">
+      <li data-wcs="textContent: .name"></li>
+    </template>
+  </ul>
+`;
+```
+
+- Replacing `rows` or writing a single row field (`rows.0.name`) both reach the rows inside the component
+- Writing `items.*.name` from inside the component reaches the host's `rows`
+
+#### Nesting and stacking scopes
+
+A component that sits inside a host `for:` *and* runs its own `for:` over the array it was handed
+is supported. The framework keeps the outer row and the inner row related:
+
+```html
+<template data-wcs="for: groups">
+  <my-list data-wcs="state.items: groups.*.children"></my-list>
+</template>
+```
+
+Components can also be placed inside components, **stacking scopes**. An intermediate component
+that only passes the array through — running no `for:` of its own — still lets a row-field write
+from the owning scope reach the rows at the bottom.
+
+A component's author never has to know how deeply it is placed. `$1`, event-handler indexes,
+`$updatedCallback` and `$getAll` all report positions **within the component's own scope**.
+
 ## Command Token (Method Binding)
 
 Property binding (`state.message: user.name`) covers data flowing into a component, but it does not cover **invoking a method on a component from state** — `<wcs-fetch>.fetch()`, `<wcs-dialog>.open()`, and so on. **Command tokens** fill that gap with a typed pub/sub channel:
@@ -1456,6 +1555,8 @@ Event tokens share the same `Token` pub/sub primitive as command tokens — `nam
 
 Command tokens and event tokens carry discrete interactions. **`$streams`** covers the remaining shape: a continuous flow. Declare an async producer (async iterable / async generator / `ReadableStream`) and the framework **folds it into a single reactive property** — each chunk goes through normal path assignment, so bindings, path getters, and `$updatedCallback` react exactly as if you had assigned the value yourself. When a state path read by the `args` function changes, the running producer is aborted and the source is restarted with the new arguments (switchMap-style dependency-driven restart). Streams start eagerly after `$connectedCallback` completes and are aborted when the element disconnects.
 
+`$updatedCallback` remains binding-driven: a stream declaration alone is not a headless subscription. Its path appears in the callback only when a live DOM binding for that value/status/error is actually applied. To react to a stream's value without rendering it, declare [`$watch`](#watch-watch) on that path; see the [stream reference](docs/streams.md) for the observation contract.
+
 ```html
 <wcs-state>
   <script type="module">
@@ -1531,6 +1632,68 @@ 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.
 
+## 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.)
+
+```html
+<wcs-state>
+  <script type="module">
+    export default {
+      isLoading: false,
+      items: [],
+      startedAt: 0,
+
+      $watch: {
+        // rising-edge detection: you compare cur/prev yourself
+        isLoading(cur, prev) {
+          if (cur === true && prev === false) { this.startedAt = Date.now(); }
+        },
+
+        // wildcard paths fire once per changed row
+        // (needs the list rendered with `for`, or `$listKeys` declared — see below)
+        "items.*.price"(cur, prev, index) {
+          this.lastPriceChange = `#${index}: ${prev} → ${cur}`;
+        },
+      },
+    };
+  </script>
+</wcs-state>
+```
+
+The handler runs with `this` bound to a **writable** state proxy, so it can write back; those writes land in the next update batch. The return value is ignored and never awaited.
+
+| Argument | Contract |
+|---|---|
+| `cur` | The value at drain time (the settled value for the batch) |
+| `prev` | The value at the **start of the batch** (first-write-wins). Meaningful **for scalars only** — see below |
+| `...indexes` | Only for wildcard paths: this scope's own loop indexes, same convention as `$1`, `$2` |
+
+**`prev` is scalar-only.** It reuses the old value the same-value guard already reads, so watch costs no extra read — and it is `undefined` for reference types (an in-place mutation would give you the same reference anyway), for `$postUpdate`, and when `config.sameValueGuard` is off.
+
+**Watch adds no firing condition of its own.** It fires for whatever landed in the update batch. That falls out well: an equal primitive write is already dropped before it is enqueued (so you effectively get change-only firing), while an occurrence write — a `semantics: "event"` property — is deliberately *not* dropped, and still fires with `cur === prev`. If you need edge detection, compare `cur` and `prev` in the handler.
+
+**Watching a getter makes it eager.** A computed getter is normally lazy, and its dependencies are only recorded when it is evaluated — so an unrendered getter would never fire at all. Declaring one in `$watch` evaluates it once at connect and again at the end of every batch that touches its dependencies. Its `prev` is the previous evaluation. Watch a heavy computed and you pay that evaluation on every batch; exceptions inside it surface through the watch instead of staying dormant. Wildcard getters (`items.*.tax`) are **not** made eager — priming one would sweep the whole list — so that form fires only when it is also bound to the DOM, and its `prev` is always `undefined` (no per-row evaluation is remembered).
+
+Firing order is defined in three layers, and only the middle one is yours to steer:
+
+| Layer | Order | Your control |
+|---|---|---|
+| Mechanisms | `$updatedCallback` → `$watch` → `$streams` restart | fixed |
+| Between handlers | declaration order in `$watch` | **reorder the declarations** |
+| Between rows of one path | ascending `indexes` | fixed |
+
+Key rules:
+
+- **Only its own state** — a path may not carry `@stateName`; watching another state element is rejected at declaration time.
+- **Intermediate values are not observable** — a batch that goes `a → b → c` fires once with `cur = c`, `prev = a`, the same contract as binding updates.
+- **Row-level diffs want `$listKeys`** — without it, assigning a whole array fires the row watch for *every* row with `prev === undefined`, because no row went through a path write. With `$listKeys` declared, the key match decomposes the assignment into per-field writes, so only changed rows fire and `prev` is a real scalar.
+- **A headless row watch requires `$listKeys`** — this is the one place `$watch` is *not* headless on its own. Expanding `items` into `items.*.price` is driven by the list's `for` binding, and declaring a watch deliberately does not register the path as a list. So with neither a `for` binding nor `$listKeys`, assigning the array fires the row watch **zero** times. Add `$listKeys` (the key match writes each field by path, bypassing the expansion) or render the list. Scalar paths — including nested ones like `user.name` — are headless with no such condition.
+- **Handler exceptions are isolated** — a throw is reported to the console and the remaining watches (and stream restarts) still run. This differs from `$connectedCallback` / `$updatedCallback`, which fail loudly.
+- **Write chains are bounded** — a handler's writes form a new batch, so mutually-writing watches would loop forever; the chain is cut off after 32 links with a console error. Values and DOM are not rolled back.
+- **Not available on a mapped `bind-component` child** — its state is wrapped in a proxy that blanks out every `$`-prefixed property, so the declaration never arrives. This applies to `$streams` too. A plain (unmapped) child can declare it.
+- **SSR does not run watches** — handler side effects would otherwise execute on both server and client.
+
 ## Inputs and Attribute Mirror
 
 `wcBindable.inputs` declares one-way property inputs (state → element). When an entry sets `attribute`, the framework writes the value to that HTML attribute every time it writes the property, so `attributeChangedCallback`, CSS attribute selectors, and DevTools all stay in sync with the property value.
@@ -1577,6 +1740,24 @@ Notes:
 - Mirror is best-effort: a `setAttribute` failure is swallowed (with a `debug` warning) and does not block the property write
 - Native HTML elements ignore `inputs` entirely — the mirror only activates for custom elements that expose `static wcBindable`
 
+## Choosing a Component Mechanism
+
+Two mechanisms give a custom element its own state, and they are **mutually exclusive** — pick one per component:
+
+| | [DCC](#declarative-custom-components-dcc) | [`bind-component`](#web-component-binding) |
+|---|---|---|
+| How the element is defined | HTML only (`data-wc-definition` + Declarative Shadow DOM) | A JavaScript `class extends HTMLElement` you write |
+| Where the state lives | An inline `<script type="module">` in the template, loaded per instance | A property on the component instance (`this.state`) |
+| `static wcBindable` | Generated from `$bindables` / `$commands` | **None** — the element is not a wc-bindable producer |
+| Parent binds a value | `count: parentCount` (two-way, change events) | `state.msg: user.name` (path mapping) |
+| Parent invokes a method | `command.bumpBy: $command.bump` | Not available — expose it on the class and call it yourself |
+| Spread (`...: obj`) | Available | Not available (requires a `wcBindable` declaration) |
+| Component reads/writes its own state | `this.count` on the element | `this.state.msg` |
+
+The rule of thumb: **if the component has no JavaScript class, use DCC; if you are already writing a class, use `bind-component`.** Combining them raises — a `<wcs-state bind-component>` inside a `data-wc-definition` host is a configuration error, because DCC state belongs to the template and is loaded per instance.
+
+`bind-component` components deliberately stay outside the wc-bindable protocol: they are wired by **path**, not by a declared property surface. That is why spread and command tokens, both of which need a `wcBindable` declaration, do not apply to them.
+
 ## Declarative Custom Components (DCC)
 
 Define custom elements **entirely in HTML** — no JavaScript class definition needed. Using `data-wc-definition` and Declarative Shadow DOM (`<template shadowrootmode>`), you can declare reusable components with reactive state inline.
@@ -1621,23 +1802,55 @@ The definition element is hidden; each instance clones the template into its own
 [data-wc-definition] { display: none; }
 ```
 
-### `$bindables` and wc-bindable Protocol
+### `$bindables` / `$commands` and the wc-bindable Protocol
 
-The `$bindables` array declares which state properties are exposed as component properties with change events, following the [wc-bindable protocol](https://github.com/nicenemo/nicenemo/blob/main/docs/wc-bindable-protocol.md):
+`$bindables` declares which state **properties** are exposed as component properties with change events. `$commands` declares which state **methods** are exposed as invocable commands. Together they build the [wc-bindable protocol](https://github.com/wc-bindable-protocol/wc-bindable-protocol/blob/main/README.md) declaration:
 
 ```javascript
 export default {
   count: 0,
-  increment() { this.count++; },
-  $bindables: ["count"]
+  bumpBy(step) { this.count += step; },
+  $bindables: ["count"],
+  $commands: ["bumpBy"]
 };
 ```
 
 This generates:
 
-- `static wcBindable` on the class — protocol metadata for framework adapters. Each `$bindables` member is declared in both `properties` and `inputs` (two-way), so parent-state → DCC writes keep working under directional initial sync — see [Binding Authority](#binding-authority-init--sync)
-- Getter/setter on the prototype — reads/writes go through the reactive proxy
-- `CustomEvent` dispatch — `my-counter:count-changed` fires on every mutation
+- `static wcBindable` on the class — protocol metadata for framework adapters. Each `$bindables` member is declared in both `properties` and `inputs` (two-way), so parent-state → DCC writes keep working under directional initial sync — see [Binding Authority](#binding-authority-init--sync). Each `$commands` member becomes a `commands` entry
+- Getter/setter on the prototype for `$bindables`, a method for `$commands` — both go through the reactive proxy
+- `CustomEvent` dispatch — `my-counter:count-changed` fires on every mutation of a `$bindables` member
+
+`commands` entries are always declared `async: true`. A DCC method chains on the inner `<wcs-state>`'s initialization, so it returns a Promise whether or not the state method itself was written `async`.
+
+Both declarations are validated when the component is defined, with the same strictness as `$commandTokens`. Each of the following raises:
+
+- not an array
+- an entry that is not a non-empty string
+- an entry starting with `$` (internal properties are never exposed on the component prototype)
+- a duplicated entry — this one used to fail silently: a duplicate name makes the whole `wcBindable` declaration unreadable, so the element would quietly stop being two-way bindable
+- an entry that does not exist on the state (own properties and the prototype chain are both searched; `$streams` names count as existing since their value properties are materialized per instance)
+- a method listed in `$bindables`, or a value property listed in `$commands`
+
+### Driving a DCC Method
+
+A `$commands` member can be invoked from the parent state with a [command token](#command-token-method-binding), exactly like an I/O node:
+
+```html
+<wcs-state>
+  <script type="module">
+    export default {
+      $commandTokens: ["bump"],
+      fire() { this.$command.bump.emit(3); }
+    };
+  </script>
+</wcs-state>
+
+<button data-wcs="onclick: fire">bump</button>
+<my-counter data-wcs="command.bumpBy: $command.bump"></my-counter>
+```
+
+Positional arguments pass through verbatim, so `emit(3)` calls `bumpBy(3)` on the component's state.
 
 ### Binding to DCC Properties
 
@@ -1673,6 +1886,7 @@ Properties prefixed with `$` are internal and not exposed on the component proto
 | Property | Purpose |
 |----------|---------|
 | `$bindables` | Declares observable properties |
+| `$commands` | Declares invocable methods |
 | `$connectedCallback` | Lifecycle hook (runs on each instance) |
 | `$disconnectedCallback` | Cleanup hook |
 | `$updatedCallback` | Called after state mutations |
@@ -1720,14 +1934,14 @@ State objects can define `$connectedCallback`, `$disconnectedCallback`, and `$up
 |---|---|---|
 | `$connectedCallback` | After state initialization on first connect; on every reconnect thereafter | Yes (awaited) |
 | `$disconnectedCallback` | When the element is removed from the DOM | No (sync only) |
-| `$updatedCallback(paths, indexesListByPath)` | After state updates are applied | Yes (not awaited) |
+| `$updatedCallback(paths, indexesListByPath)` | After updates are applied to live bindings | Yes (not awaited) |
 
 All hooks except `$disconnectedCallback` support `async` — you can use `async/await` in any of them. Since the reactive proxy detects every property assignment as a change, standard `async/await` with direct property updates is sufficient for asynchronous operations — loading flags, fetched data, and error messages are all just property assignments, without requiring additional abstractions for async state management.
 
 - `this` inside hooks is the state proxy with full read/write access
 - `$connectedCallback` is called **every time** the element is connected (including re-insertion after removal), making it suitable for setup that should be re-established
 - `$disconnectedCallback` is called synchronously — use it for cleanup such as clearing timers, removing event listeners, or releasing resources
-- `$updatedCallback(paths, indexesListByPath)` receives the updated path list. For wildcard updates, `indexesListByPath` contains the updated index sets. Can be `async`, but the return value is not awaited
+- `$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`
 
 ## Configuration