@wcstack/state 1.11.1 → 1.12.1

package/README.ja.md

@@ -16,7 +16,7 @@
 - selector
 - reactive primitive をコンポーネントへ引き込むための glue code
 
-None of these exist by design.
+これらはどれも、設計上存在しません。
 
 なぜなら、このライブラリでは UI と状態の結合点を JavaScript の中に置かないからです。状態を「取り出して」コンポーネントへ渡すのではなく、HTML 側がパス文字列によって状態を参照します。要素は状態を所有せず、状態も要素を知りません。両者が共有するのはパスだけです。
 
@@ -96,6 +96,8 @@ None of these exist by design.
 - **組み込みフィルタ** — フォーマット、比較、算術、日付など 40 種類
 - **双方向バインディング** — `<input>`, `<select>`, `<textarea>` で自動有効
 - **Web Component バインディング** — Shadow DOM コンポーネントとの双方向状態バインディング
+- **command token** — pub/sub チャネル（`command.<method>: tokenName`）で state から wc-bindable カスタム要素のメソッドを起動
+- **event token** — command token の双対。wc-bindable 要素が dispatch するイベントを `eventToken.<prop>: tokenName` + `$on` マップで state が受信
 - **パス getter** — ドットパスキー getter（`get "users.*.fullName"()`）によるデータツリーの任意の深さへのフラットな仮想プロパティ定義、自動依存追跡・キャッシュ
 - **Mustache 構文** — テキストノードでの `{{ path|filter }}`
 - **複数の状態ソース** — JSON, JS モジュール, インラインスクリプト, API, 属性
@@ -419,6 +421,8 @@ export default {
 <wcs-fetch data-wcs="...: usersFetch; status: alternateStatus"></wcs-fetch>
 ```
 
+**`undefined` は「無意見」** — 展開された state パスが `undefined` に解決される場合（slot オブジェクトでその input を初期化していない場合など）、プロパティ書き込みは**スキップ**され、要素側の既定値がそのまま生きます。実際に使うパスだけ初期化すれば十分で、`<wcs-fetch>` が `method` / `manual` / `body` を宣言していても `usersFetch: { value: null, loading: false }` だけで動きます。明示的にクリアしたい場合は `null` を代入してください（`null` は常に書き込まれます）。このスキップは spread に限らずすべてのプロパティバインディングに適用され、`config.debug` 時はスキップごとに `console.debug` でログが出ます。
+
 **制約事項**：
 
 - spread 右辺へのフィルタ（`...: target|filter`）はエラー
@@ -1245,6 +1249,150 @@ command token は state コードから emit する必要はありません。DO
 <my-list  data-wcs="command.reset: $command.reset"></my-list>
 ```
 
+## Event Token（イベントバインディング）
+
+command token はコンポーネントへ *押し込み* ます（state がメソッドを起動）。**event token** はその正確な双対 —— コンポーネントから *引き出し* ます（要素がイベントを dispatch し、state が受信）。両者で要素 ↔ state 境界の双方向をカバーし、どちらの側も相手への参照を一切持ちません。共有されるのは token のみです。
+
+| Token | 方向 | 購読者 | emit する側 |
+|---|---|---|---|
+| **command token** | state → 要素 | 要素（`command.<method>:`） | state（`$command.<name>.emit`） |
+| **event token** | 要素 → state | state（`$on`） | 要素（DOM イベントリスナー） |
+
+- 要素側は wc-bindable カスタム要素に `eventToken.<property>: <tokenName>` を配線する
+- state 側は `$eventTokens` でチャネルを宣言し、`$on` マップで受信する
+- 購読者は `(state, event, ...listIndexes)` で呼び出される —— command token の emit 規約と対称
+
+### 基本的な使い方
+
+```html
+<wcs-state>
+  <script type="module">
+    export default {
+      users: [],
+      error: null,
+
+      $eventTokens: ["userCreated", "createFailed"],
+      $on: {
+        userCreated(state, event) {
+          state.users = state.users.concat(event.detail);
+        },
+        createFailed(state, event) {
+          state.error = event.detail;
+        }
+      }
+    };
+  </script>
+</wcs-state>
+
+<!-- emitter — wc-bindable なカスタム要素であること -->
+<my-form data-wcs="eventToken.created: userCreated; eventToken.error: createFailed"></my-form>
+```
+
+`<my-form>` が自身の `created` プロパティに対応する DOM イベントを dispatch すると、`userCreated` token が発火し、`$on.userCreated` ハンドラが `(state, event)` で実行されます。
+
+### `$eventTokens` 宣言
+
+`$eventTokens` 配列は、`eventToken.<prop>:` バインディングと `$on` キーが参照できるチャネル名を宣言します。宣言された名前のみが有効です（typo 耐性）。
+
+```javascript
+export default {
+  $eventTokens: ["userCreated", "createFailed"],
+};
+```
+
+- エントリは空でない文字列であること
+- 重複するエントリは初期化時にエラーになる
+- ここで宣言されたが `$on` に無い token は購読者ゼロ —— emit しても no-op
+
+### `$on` —— state 側での受信
+
+`$on` は各 event-token 名をハンドラに対応づけます。state は **第1引数** として渡される（`this` ではない）ため、ハンドラはメソッド省略記法でもアロー関数でも書けます —— `this` を束縛しない点は command token の emit 規約と同じです：
+
+```javascript
+$on: {
+  // どちらの形式でも可 —— state は常に第1引数
+  userCreated: (state, event) => { state.lastId = event.detail.id; },
+  rowFailed(state, event, ...listIndexes) {
+    const [i] = listIndexes;          // `for` 内から発火した場合のループインデックス
+    state.failedRows = state.failedRows.concat(i);
+  }
+}
+```
+
+- `$on` のすべてのキーは `$eventTokens` で宣言済みであること（さもなくば初期化時に throw）
+- 各値は関数であること
+- シグネチャは `(state, event, ...listIndexes)` —— まず DOM の `Event`、続いて内包するループインデックス
+
+### `eventToken.<property>:` バインディング
+
+```html
+<my-target data-wcs="eventToken.error: createFailed"></my-target>
+```
+
+| 部位 | 説明 |
+|---|---|
+| `eventToken.` | 固定の prefix |
+| `<property>` | **wcBindable プロパティ名** —— 生の DOM イベント名ではない。実イベント名は `wcBindable.properties[].event` から解決される |
+| `<tokenName>` | `$eventTokens` で宣言されたベアな event-token 名（command token と違い `$` 名前空間 prefix は付けない） |
+
+キーを生イベント名ではなくプロパティ名にすることで、command バインディングと同じ `wcBindable` 契約を経由でき、namespaced なイベント名（`ns:evt`）がバインディングの `:` 区切りと衝突しません。フレームワークは `properties[].event` を引いてその実イベントのリスナーを attach します：
+
+```javascript
+class MyTarget extends HTMLElement {
+  static wcBindable = {
+    protocol: "wc-bindable", version: 1,
+    properties: [
+      { name: "error",   event: "thing-error" },     // eventToken.error → "thing-error" を listen
+      { name: "created", event: "thing-created" },
+    ],
+  };
+}
+```
+
+検証ルール：
+
+- 要素は wc-bindable なカスタム要素であること（`static wcBindable`・`protocol: "wc-bindable"`・`version: 1`）。非 wc-bindable 要素は attach 時に拒否される。
+- `<property>` は `wcBindable.properties` に現れること —— **attach 時** に検証（fail-fast。クラス参照のみで足り、DOM 接続に非依存）。
+- `<tokenName>` は `$eventTokens` で宣言されていること —— **発火時** に検証。state はイベント発火時に要素の live root から解決されるため、attach 時にノードが detached になりうる `for` / `if` ブロック内や SSR ハイドレーション後でも機能する。
+- 修飾子 `#prevent` / `#stop` は通常のイベントバインディングと同様に機能する: `eventToken.error#prevent: createFailed`。
+
+### ループ内での使用
+
+emitter が `for` ブロック内にある場合、`on*` ハンドラと同じく、内包するループインデックスがイベントの後ろに付与されます：
+
+```html
+<template data-wcs="for: rows">
+  <my-row data-wcs="eventToken.failed: rowFailed"></my-row>
+</template>
+```
+
+```javascript
+$on: {
+  rowFailed(state, event, ...listIndexes) {
+    const [i] = listIndexes;          // 発火した行のインデックス
+    state.failedRows = state.failedRows.concat(i);
+  }
+}
+```
+
+### ファンインとチェイン
+
+複数の要素が同じ token を配線できます（`eventToken.x: shared`）—— すべての dispatch が1つの `$on` ハンドラに届き、command token のファンアウトと対称です。さらに `$on` ハンドラは `state` を受け取るため、そこから command token を再 emit して 要素 → state → 要素 のチェインを組めます：
+
+```javascript
+$commandTokens: ["doRefresh"],
+$eventTokens: ["completed"],
+$on: {
+  completed(state) {
+    state.$command.doRefresh.emit();  // event in → command out
+  }
+}
+```
+
+### Token API
+
+event token は command token と同じ `Token` pub/sub プリミティブを共有します —— `name` / `size` / `subscribe` / `unsubscribe` / `emit`、subscribe 順の保持つき（[Token API](#token-api) 参照）。token はイベントごとに registry から解決されるため、`setInitialState()` による再構築後も最新の `$on` 購読者に届きます。所有する `<wcs-state>` が disconnect されると、event-token registry はクリアされます。
+
 ## Inputs と属性ミラー
 
 `wcBindable.inputs` は一方向のプロパティ入力（state → 要素）を宣言します。エントリに `attribute` を設定すると、フレームワークはプロパティを書き込むたびにその値を当該 HTML 属性へも書き込むため、`attributeChangedCallback`・CSS の属性セレクタ・DevTools がすべてプロパティ値と同期し続けます。
@@ -1600,7 +1748,7 @@ const html = await renderToString(template, {
 });
 ```
 
-これだけです。クライアント側の `@wcstack/state` は `<wcs-ssr>` 要素を自動検出し、JSON スナップショットから状態を復元し��再レンダリングなしでリアクティビティを再開します。
+これだけです。クライアント側の `@wcstack/state` は `<wcs-ssr>` 要素を自動検出し、JSON スナップショットから状態を復元し、再レンダリングなしでリアクティビティを再開します。
 
 ### 仕組み
 
@@ -1608,14 +1756,14 @@ const html = await renderToString(template, {
 |---------|------|
 | **サーバー** | `renderToString()` が happy-dom でテンプレートを実行、`$connectedCallback`（`fetch()` 含む）を実行し、全バインディングを適用、ハイドレーションデータを含む `<wcs-ssr>` 要素付きのレンダリング済み HTML を出力 |
 | **クライアント** | `<wcs-state enable-ssr>` が `<wcs-ssr>` の JSON から状態をロード、`$connectedCallback` をスキップ、`hydrateBindings()` が既存の DOM にリアクティビティを接続 |
-| **フォールバック** | ���ーバー/クライアントのバージョン不一致時、SSR DOM をクリーンアップして `buildBindings()` でフルクライアントサイドレンダリングを実行 |
+| **フォールバック** | サーバー/クライアントのバージョン不一致時、SSR DOM をクリーンアップして `buildBindings()` でフルクライアントサイドレンダリングを実行 |
 
 ### `enable-ssr` の動作
 
 | コンテキスト | 動作 |
 |------------|------|
 | **サーバー**（`renderToString`） | 状態 JSON、テンプレートフラグメント、プロパティデータを含む `<wcs-ssr>` を生成 |
-| **クラ��アント**（ハイドレーション） | `<wcs-ssr>` を読み取り、状態を復元、`$connectedCallback` をスキップ、既存 DOM のバイン���ィングをハイドレート |
+| **クライアント**（ハイドレーション） | `<wcs-ssr>` を読み取り、状態を復元、`$connectedCallback` をスキップ、既存 DOM のバインディングをハイドレート |
 
 API の詳細は [`@wcstack/server` README](../server/README.ja.md) を参照してください。
 

package/README.md

@@ -97,6 +97,7 @@ That's it. No build, no bootstrap code, no framework.
 - **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`)
+- **Event tokens** — the dual of command tokens: receive a wc-bindable element's dispatched events in state via `eventToken.<prop>: tokenName` + the `$on` map
 - **Path getters** — dot-path key getters (`get "users.*.fullName"()`) for virtual properties at any depth in a data tree, all defined flat in one place with automatic dependency tracking and caching
 - **Mustache syntax** — `{{ path|filter }}` in text nodes
 - **Multiple state sources** — JSON, JS module, inline script, API, attribute
@@ -420,6 +421,8 @@ Runtime reads `customClass.wcBindable.properties + inputs` and expands each name
 <wcs-fetch data-wcs="...: usersFetch; status: alternateStatus"></wcs-fetch>
 ```
 
+**`undefined` is "no opinion"** — when an expanded state path resolves to `undefined` (e.g. the slot object doesn't initialize that input), the property write is **skipped** and the element keeps its own default. You only need to initialize the paths you actually use; `usersFetch: { value: null, loading: false }` is enough even though `<wcs-fetch>` also declares `method` / `manual` / `body`. To explicitly clear a value, assign `null` — `null` is always written. (This skip applies to every property binding, not just spread; with `config.debug` each skipped write is logged via `console.debug`.)
+
 **Constraints**:
 
 - Filters on the spread target (`...: target|filter`) are rejected.
@@ -1247,6 +1250,150 @@ This is pure wiring: the event endpoint is connected to a command-token endpoint
 <my-list  data-wcs="command.reset: $command.reset"></my-list>
 ```
 
+## Event Token (Event Binding)
+
+Command tokens push *into* a component (state invokes a method). **Event tokens** are the exact dual — they pull *out* of a component (an element dispatches an event, state receives it). Together they cover both directions of the element ↔ state boundary, and neither side ever holds a reference to the other — the token is the only shared object.
+
+| Token | Direction | Subscribes | Emits |
+|---|---|---|---|
+| **Command token** | state → element | element (`command.<method>:`) | state (`$command.<name>.emit`) |
+| **Event token** | element → state | state (`$on`) | element (DOM event listener) |
+
+- The element wires `eventToken.<property>: <tokenName>` on a wc-bindable custom element.
+- State declares channels with `$eventTokens` and receives them with the `$on` map.
+- Subscribers are called as `(state, event, ...listIndexes)` — symmetric with the command-token emit convention.
+
+### Basic Usage
+
+```html
+<wcs-state>
+  <script type="module">
+    export default {
+      users: [],
+      error: null,
+
+      $eventTokens: ["userCreated", "createFailed"],
+      $on: {
+        userCreated(state, event) {
+          state.users = state.users.concat(event.detail);
+        },
+        createFailed(state, event) {
+          state.error = event.detail;
+        }
+      }
+    };
+  </script>
+</wcs-state>
+
+<!-- Emitters — must be wc-bindable custom elements -->
+<my-form data-wcs="eventToken.created: userCreated; eventToken.error: createFailed"></my-form>
+```
+
+When `<my-form>` dispatches the DOM event mapped to its `created` property, the `userCreated` token fires and the `$on.userCreated` handler runs with `(state, event)`.
+
+### `$eventTokens` Declaration
+
+The `$eventTokens` array declares the channel names that `eventToken.<prop>:` bindings and `$on` keys may reference. Only declared names are valid (typo resistance).
+
+```javascript
+export default {
+  $eventTokens: ["userCreated", "createFailed"],
+};
+```
+
+- Entries must be non-empty strings
+- Duplicate entries throw an error at initialization
+- A token declared here but absent from `$on` simply has no subscriber — emitting it is a no-op
+
+### `$on` — Receiving on the State Side
+
+`$on` maps each event-token name to a handler. Because state is passed as the **first argument** (not via `this`), handlers can be written as either method shorthand or arrow functions — this mirrors the command-token emit convention, where `this` is likewise not bound:
+
+```javascript
+$on: {
+  // both forms work — state is always the first parameter
+  userCreated: (state, event) => { state.lastId = event.detail.id; },
+  rowFailed(state, event, ...listIndexes) {
+    const [i] = listIndexes;          // loop index when fired from inside a `for`
+    state.failedRows = state.failedRows.concat(i);
+  }
+}
+```
+
+- Every `$on` key must be declared in `$eventTokens` (otherwise an error is thrown at initialization)
+- Each value must be a function
+- The signature is `(state, event, ...listIndexes)` — the DOM `Event` first, then any enclosing loop indexes
+
+### `eventToken.<property>:` Binding
+
+```html
+<my-target data-wcs="eventToken.error: createFailed"></my-target>
+```
+
+| Part | Description |
+|---|---|
+| `eventToken.` | Fixed prefix |
+| `<property>` | A **wcBindable property name** — not a raw DOM event name. The real event name is resolved from `wcBindable.properties[].event` |
+| `<tokenName>` | A bare event-token name declared in `$eventTokens` (no `$`-namespace prefix, unlike command tokens) |
+
+The key is a property name rather than a raw event name so the binding goes through the same `wcBindable` contract that command bindings use — and so a namespaced event name (`ns:evt`) cannot collide with the binding's `:` separator. The framework looks up `properties[].event` and attaches a listener for that real event:
+
+```javascript
+class MyTarget extends HTMLElement {
+  static wcBindable = {
+    protocol: "wc-bindable", version: 1,
+    properties: [
+      { name: "error",   event: "thing-error" },     // eventToken.error → listens for "thing-error"
+      { name: "created", event: "thing-created" },
+    ],
+  };
+}
+```
+
+Validation rules:
+
+- The element must be a wc-bindable custom element (`static wcBindable`, `protocol: "wc-bindable"`, `version: 1`). A non-wc-bindable element is rejected at attach time.
+- `<property>` must appear in `wcBindable.properties` — checked at **attach time** (fail-fast; needs only the class, not DOM connection).
+- `<tokenName>` must be declared in `$eventTokens` — checked at **fire time**. State is resolved from the element's live root node when the event fires, so the binding also works inside `for` / `if` blocks and after SSR hydration, where the node may still be detached at attach time.
+- Modifiers `#prevent` / `#stop` work as on any event binding: `eventToken.error#prevent: createFailed`.
+
+### Inside a Loop
+
+When the emitter sits inside a `for` block, the enclosing loop indexes are appended after the event, exactly like an `on*` handler:
+
+```html
+<template data-wcs="for: rows">
+  <my-row data-wcs="eventToken.failed: rowFailed"></my-row>
+</template>
+```
+
+```javascript
+$on: {
+  rowFailed(state, event, ...listIndexes) {
+    const [i] = listIndexes;          // index of the row that fired
+    state.failedRows = state.failedRows.concat(i);
+  }
+}
+```
+
+### Fan-in and Chaining
+
+Multiple elements can wire the same token (`eventToken.x: shared`) — every dispatch reaches the one `$on` handler, mirroring command-token fan-out. And because an `$on` handler receives `state`, it can re-emit a command token, chaining element → state → element:
+
+```javascript
+$commandTokens: ["doRefresh"],
+$eventTokens: ["completed"],
+$on: {
+  completed(state) {
+    state.$command.doRefresh.emit();  // event in → command out
+  }
+}
+```
+
+### Token API
+
+Event tokens share the same `Token` pub/sub primitive as command tokens — `name` / `size` / `subscribe` / `unsubscribe` / `emit`, with subscribe-order preservation (see [Token API](#token-api)). The token is resolved from the registry on every event so a re-`setInitialState()` rebuild still reaches the latest `$on` subscribers. When the owning `<wcs-state>` is disconnected, the event-token registry is cleared.
+
 ## 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.