@wcstack/state 1.11.1 → 1.12.0

package/README.ja.md

@@ -16,7 +16,7 @@
 - selector
 - reactive primitive をコンポーネントへ引き込むための glue code
 
-None of these exist by design.
+これらはどれも、設計上存在しません。
 
 なぜなら、このライブラリでは UI と状態の結合点を JavaScript の中に置かないからです。状態を「取り出して」コンポーネントへ渡すのではなく、HTML 側がパス文字列によって状態を参照します。要素は状態を所有せず、状態も要素を知りません。両者が共有するのはパスだけです。
 
@@ -1600,7 +1600,7 @@ const html = await renderToString(template, {
 });
 ```
 
-これだけです。クライアント側の `@wcstack/state` は `<wcs-ssr>` 要素を自動検出し、JSON スナップショットから状態を復元し��再レンダリングなしでリアクティビティを再開します。
+これだけです。クライアント側の `@wcstack/state` は `<wcs-ssr>` 要素を自動検出し、JSON スナップショットから状態を復元し、再レンダリングなしでリアクティビティを再開します。
 
 ### 仕組み
 
@@ -1608,14 +1608,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/dist/index.esm.js

@@ -59,7 +59,7 @@ function setConfig(partialConfig) {
     }
 }
 
-var version$1 = "1.11.1";
+var version$1 = "1.12.0";
 var pkg = {
 	version: version$1};
 
@@ -137,6 +137,8 @@ const WEBCOMPONENT_STATE_READY_CALLBACK_NAME = "$stateReadyCallback";
 const STATE_BINDABLES_NAME = "$bindables";
 const STATE_COMMAND_TOKENS_NAME = "$commandTokens";
 const STATE_COMMAND_NAMESPACE_NAME = "$command";
+const STATE_EVENT_TOKENS_NAME = "$eventTokens";
+const STATE_ON_NAME = "$on";
 const DCC_DEFINITION_ATTRIBUTE = "data-wc-definition";
 
 const _cache$4 = new Map();
@@ -1485,6 +1487,15 @@ function parseBindTextsForElement(bindText) {
         else {
             const stateResult = parseStatePart(statePart);
             const propResult = parsePropPart(propPart);
+            // eventToken.<prop>: <name> は要素 dispatch を state へ流す pub/sub 配線。
+            // 値適用ではないため bindingType 'event' として listener attach 経路に乗せる。
+            if (propResult.propSegments[0] === 'eventToken') {
+                return {
+                    ...propResult,
+                    ...stateResult,
+                    bindingType: 'event',
+                };
+            }
             if (propResult.propSegments[0].startsWith('on')) {
                 return {
                     ...propResult,
@@ -1748,9 +1759,14 @@ function createStateAddress(pathInfo, listIndex) {
     }
 }
 
+// command-token / event-token が共有する pub/sub プリミティブ。
 // _subscribers は Set のため挿入順を保持する。
 // emit() は subscribe() された順に呼び出され、戻り値配列も同じ順序で返る。
-class CommandToken {
+//
+// 「誰が subscribe し誰が emit するか」だけが command / event の違い:
+//   - command-token: element が subscribe / state が emit
+//   - event-token:   state(`$on`) が subscribe / element(listener) が emit
+class Token {
     _name;
     _subscribers = new Set();
     constructor(name) {
@@ -1779,6 +1795,11 @@ class CommandToken {
         return results;
     }
 }
+
+// CommandToken は共有 pub/sub プリミティブ Token の薄い特化。
+// instanceof による型判別を成立させるため独立クラスとして維持する。
+class CommandToken extends Token {
+}
 function isCommandToken(value) {
     return value instanceof CommandToken;
 }
@@ -1877,6 +1898,129 @@ function attachEventHandler(binding) {
     return true;
 }
 
+// EventToken は共有 pub/sub プリミティブ Token の薄い特化（element→state 方向）。
+// instanceof による型判別を成立させるため独立クラスとして維持する。
+class EventToken extends Token {
+}
+
+const registryByStateElement$1 = new WeakMap();
+function getOrCreateEventToken(stateElement, name) {
+    let registry = registryByStateElement$1.get(stateElement);
+    if (typeof registry === "undefined") {
+        registry = new Map();
+        registryByStateElement$1.set(stateElement, registry);
+    }
+    let token = registry.get(name);
+    if (typeof token === "undefined") {
+        token = new EventToken(name);
+        registry.set(name, token);
+    }
+    return token;
+}
+function clearEventTokenRegistry(stateElement) {
+    registryByStateElement$1.delete(stateElement);
+}
+
+/**
+ * eventToken.<propertyName>: <eventTokenName> バインディングの attach ハンドラ。
+ *
+ * command-token の双対（element→state）。要素が dispatch する CustomEvent を受けて
+ * event-token を emit し、state 側の `$on` ハンドラ群へ pub/sub で配送する。
+ *
+ * 設計（MVP スコープ: wc-bindable カスタム要素のみ）:
+ *   - キーは生イベント名ではなく **wcBindable property 名**。実 DOM イベント名は
+ *     wcBindable.properties[].event から解決する（command-token が wcBindable.commands で
+ *     検証するのと対称。コロンを含む namespaced event 名と binding 構文の `:` 衝突も回避）。
+ *   - <prop> が wcBindable.properties に宣言されていることは attach 時に検証する
+ *     （要素クラス参照のみで DOM 接続に非依存。fail-fast / typo 耐性）。
+ *   - <eventTokenName> が $eventTokens に宣言されていることは **発火時** に検証する
+ *     （state 解決が必要なため。詳細は下記の fire-time 解決の注記を参照）。
+ *   - subscriber 引数規約は `(state, event, ...listIndexes)`。
+ *   - modifier `#prevent` / `#stop` は既存イベント binding と同等にサポート。
+ *
+ * token はイベント発火ごとに registry から解決する（getOrCreateEventToken）。これにより
+ * state の再 set で registry が作り直されても最新の subscriber 群へ配送できる。
+ *
+ * state element の解決と `$eventTokens` 検証は **発火時** に行う（attach 時ではない）。
+ * 構造ブロック（for/if）や SSR hydration では、binding 初期化時にノードが detached な
+ * DocumentFragment / wrapper 上にあり、その時点では element.getRootNode() から state を
+ * 解決できないため。onclick / two-way ハンドラと同じく fire-time 解決に揃えている。
+ */
+const listenerByBinding = new WeakMap();
+function getWcBindable$1(element) {
+    const customTagName = getCustomElement(element);
+    if (customTagName === null) {
+        return null;
+    }
+    // attach 側で未定義要素は whenDefined 後に再試行するため、ここに来る時点で customClass は定義済み。
+    const customClass = customElements.get(customTagName);
+    const bindable = customClass?.wcBindable;
+    if (bindable?.protocol === "wc-bindable" && bindable?.version === 1) {
+        return bindable;
+    }
+    return null;
+}
+function attachEventTokenHandler(binding) {
+    if (binding.propSegments[0] !== "eventToken") {
+        return false;
+    }
+    const element = binding.node;
+    // カスタム要素が未定義なら定義後に再試行（wcBindable が必要なため）。
+    const customTagName = getCustomElement(element);
+    if (customTagName !== null && customElements.get(customTagName) === undefined) {
+        customElements.whenDefined(customTagName).then(() => {
+            attachEventTokenHandler(binding);
+        });
+        return true;
+    }
+    // 再評価で二重 attach しない。
+    if (listenerByBinding.has(binding)) {
+        return true;
+    }
+    const propertyName = binding.propSegments[1];
+    if (typeof propertyName !== "string" || propertyName.length === 0) {
+        raiseError(`eventToken binding requires a property name (e.g., "eventToken.error").`);
+    }
+    const bindable = getWcBindable$1(element);
+    if (bindable === null) {
+        raiseError(`eventToken binding requires a wc-bindable custom element. <${element.tagName.toLowerCase()}> is not wc-bindable.`);
+    }
+    const propDesc = bindable.properties.find((p) => p.name === propertyName);
+    if (typeof propDesc === "undefined") {
+        raiseError(`Property "${propertyName}" is not declared in wcBindable.properties of <${element.tagName.toLowerCase()}>.`);
+    }
+    const eventName = propDesc.event;
+    const tokenName = binding.statePathName;
+    const stateName = binding.stateName;
+    const modifiers = binding.propModifiers;
+    const handler = (event) => {
+        if (modifiers.includes("prevent"))
+            event.preventDefault();
+        if (modifiers.includes("stop"))
+            event.stopPropagation();
+        // state は発火時の live root から解決する（attach 時は detached の可能性があるため）。
+        const rootNode = element.getRootNode();
+        const stateElement = getStateElementByName(rootNode, stateName);
+        if (stateElement === null) {
+            raiseError(`State element with name "${stateName}" not found for eventToken handler.`);
+        }
+        if (!stateElement.eventTokenNames.has(tokenName)) {
+            raiseError(`eventToken "${tokenName}" is not declared in $eventTokens of state "${stateName}".`);
+        }
+        const loopContext = getLoopContextByNode(element);
+        stateElement.createStateAsync("writable", async (state) => {
+            state[setLoopContextSymbol](loopContext, () => {
+                const indexes = loopContext?.listIndex.indexes ?? [];
+                const token = getOrCreateEventToken(stateElement, tokenName);
+                return token.emit(state, event, ...indexes);
+            });
+        });
+    };
+    element.addEventListener(eventName, handler);
+    listenerByBinding.set(binding, { eventName, handler });
+    return true;
+}
+
 const CHECK_TYPES = new Set(['radio', 'checkbox']);
 const DEFAULT_VALUE_PROP_NAMES = new Set(['value', 'valueAsNumber', 'valueAsDate']);
 function isPossibleTwoWay(node, propName) {
@@ -3871,6 +4015,10 @@ function _initializeBindings(allBindings) {
         if (attachEventHandler(binding)) {
             continue;
         }
+        // event token (element → state)
+        if (attachEventTokenHandler(binding)) {
+            continue;
+        }
         // two-way binding
         attachTwowayEventHandler(binding);
         // radio binding
@@ -4398,6 +4546,8 @@ function collectBindingsFromLiveNodes(nodes) {
         replaceToReplaceNode(binding);
         if (attachEventHandler(binding))
             continue;
+        if (attachEventTokenHandler(binding))
+            continue;
         attachTwowayEventHandler(binding);
         attachRadioEventHandler(binding);
         attachCheckboxEventHandler(binding);
@@ -4637,6 +4787,9 @@ async function hydrateBindings(root) {
         if (attachEventHandler(binding)) {
             continue;
         }
+        if (attachEventTokenHandler(binding)) {
+            continue;
+        }
         attachTwowayEventHandler(binding);
         attachRadioEventHandler(binding);
         attachCheckboxEventHandler(binding);
@@ -5368,6 +5521,67 @@ function clearCommandNamespace(stateElement) {
     namespaceProxyByStateElement.delete(stateElement);
 }
 
+/**
+ * `$eventTokens: ["a", "b", ...]` 配列宣言を解析し、宣言された名前群を Set で返す。
+ *
+ * event-token は command-token の双対（element→state 方向）。要素が dispatch する
+ * イベントを `eventToken.<prop>: <name>` で token に流し、state 側は `$on` マップで受ける。
+ * ここで宣言された名前のみが `eventToken.X` / `$on` の有効なチャネル名になる（typo 耐性）。
+ *
+ * 対応している宣言形式は **オブジェクトリテラル** のみ。
+ */
+function processEventTokensDeclaration(state) {
+    const names = new Set();
+    const declared = state[STATE_EVENT_TOKENS_NAME];
+    if (typeof declared === "undefined") {
+        return names;
+    }
+    if (!Array.isArray(declared)) {
+        raiseError(`${STATE_EVENT_TOKENS_NAME} must be an array of strings.`);
+    }
+    for (const name of declared) {
+        if (typeof name !== "string" || name.length === 0) {
+            raiseError(`${STATE_EVENT_TOKENS_NAME} entries must be non-empty strings.`);
+        }
+        if (names.has(name)) {
+            raiseError(`${STATE_EVENT_TOKENS_NAME} entry "${name}" is duplicated.`);
+        }
+        names.add(name);
+    }
+    return names;
+}
+
+/**
+ * `$on: { <name>: (state, event, ...listIndexes) => {...} }` マップを解析し、
+ * 各ハンドラを対応する event-token に subscribe する（state 側の受信配線）。
+ *
+ * - `$on` のキーは `$eventTokens` で宣言済みでなければならない（typo 耐性）。
+ * - 各値は関数でなければならない。
+ * - 引数規約は `(state, event, ...listIndexes)`。`this` 束縛は行わず引数で state を渡すため
+ *   アロー関数で書ける（command-token の emit 規約と対称）。
+ *
+ * `$eventTokens` で宣言されたが `$on` に対応が無い token は subscriber ゼロ（emit は no-op）。
+ */
+function processOnDeclaration(stateElement, state, eventTokenNames) {
+    const declared = state[STATE_ON_NAME];
+    if (typeof declared === "undefined") {
+        return;
+    }
+    if (typeof declared !== "object" || declared === null) {
+        raiseError(`${STATE_ON_NAME} must be an object mapping event-token names to handler functions.`);
+    }
+    for (const [name, handler] of Object.entries(declared)) {
+        if (!eventTokenNames.has(name)) {
+            raiseError(`${STATE_ON_NAME} entry "${name}" is not declared in $eventTokens.`);
+        }
+        if (typeof handler !== "function") {
+            raiseError(`${STATE_ON_NAME} entry "${name}" must be a function.`);
+        }
+        const token = getOrCreateEventToken(stateElement, name);
+        token.subscribe(handler);
+    }
+}
+
 function getterFn(name) {
     return function () {
         const stateEl = this.stateElement;
@@ -7199,6 +7413,7 @@ class State extends HTMLElement {
     _boundComponentStateProp = null;
     _bindableEventMap = {};
     _commandTokenNames = new Set();
+    _eventTokenNames = new Set();
     constructor() {
         super();
         this._initializePromise = new Promise((resolve) => {
@@ -7222,7 +7437,11 @@ class State extends HTMLElement {
     }
     set _state(value) {
         this._commandTokenNames = processCommandTokensDeclaration(value);
+        this._eventTokenNames = processEventTokensDeclaration(value);
         this.__state = value;
+        // 再 set 時に二重 subscribe しないよう registry をクリアしてから $on を配線し直す。
+        clearEventTokenRegistry(this);
+        processOnDeclaration(this, value, this._eventTokenNames);
         this._listPaths.clear();
         this._elementPaths.clear();
         this._getterPaths.clear();
@@ -7436,6 +7655,7 @@ class State extends HTMLElement {
             setStateElementByName(this.rootNode, this._name, null);
             clearCommandTokenRegistry(this);
             clearCommandNamespace(this);
+            clearEventTokenRegistry(this);
             this._rootNode = null;
         }
     }
@@ -7484,6 +7704,9 @@ class State extends HTMLElement {
     get commandTokenNames() {
         return this._commandTokenNames;
     }
+    get eventTokenNames() {
+        return this._eventTokenNames;
+    }
     setBindableEventMap(map) {
         this._bindableEventMap = map;
     }