@wcstack/state 1.8.6 → 1.9.0

package/dist/index.esm.js

@@ -59,7 +59,7 @@ function setConfig(partialConfig) {
     }
 }
 
-var version$1 = "1.8.6";
+var version$1 = "1.9.0";
 var pkg = {
 	version: version$1};
 
@@ -187,6 +187,8 @@ const STATE_DISCONNECTED_CALLBACK_NAME = "$disconnectedCallback";
 const STATE_UPDATED_CALLBACK_NAME = "$updatedCallback";
 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 DCC_DEFINITION_ATTRIBUTE = "data-wc-definition";
 
 const _cache$4 = new Map();
@@ -1988,6 +1990,123 @@ function applyChangeToClass(binding, _context, newValue) {
     element.classList.toggle(className, newValue);
 }
 
+// _subscribers は Set のため挿入順を保持する。
+// emit() は subscribe() された順に呼び出され、戻り値配列も同じ順序で返る。
+class CommandToken {
+    _name;
+    _subscribers = new Set();
+    constructor(name) {
+        this._name = name;
+    }
+    get name() {
+        return this._name;
+    }
+    get size() {
+        return this._subscribers.size;
+    }
+    subscribe(fn) {
+        this._subscribers.add(fn);
+        return () => {
+            this._subscribers.delete(fn);
+        };
+    }
+    unsubscribe(fn) {
+        return this._subscribers.delete(fn);
+    }
+    emit(...args) {
+        const results = [];
+        for (const fn of this._subscribers) {
+            results.push(fn(...args));
+        }
+        return results;
+    }
+}
+function isCommandToken(value) {
+    return value instanceof CommandToken;
+}
+
+/**
+ * command.<methodName>: <commandToken-path> バインディングの適用ハンドラ。
+ *
+ * subscribe lifecycle:
+ *   - 同一 binding に同じ token が再評価された場合は no-op。
+ *   - 異なる token が来た場合は古い subscription を解除し、新しい token に subscribe し直す。
+ *     旧解除は新しい binding 妥当性検証（methodName・wcBindable.commands チェック）を
+ *     通過した後に行うため、再評価が validation で失敗しても旧購読は温存される（fail-fast）。
+ *   - element は WeakRef で保持し、subscriber 経由で element を強参照しないようにする。
+ *     これにより、element が DOM から消えた後に subscriber が token._subscribers に
+ *     残っていても element 本体は GC 可能。
+ *   - emit 時に下記いずれかなら自動で subscription を破棄する（lazy purge）:
+ *     - WeakRef.deref() が undefined（element が既に GC 済み）
+ *     - element.isConnected が false（DOM から取り外されている）
+ *
+ * 既知の制約:
+ *   - emit が来なければ stale subscriber は token に残り続ける（要素が GC されても subscriber 関数自体は残る）。
+ *     state インスタンスが disconnect されたタイミングで registry ごとクリアされるため、最終的には解放される。
+ *     element ライフサイクルに直接フックする手段が現状の binding 機構に無いため、能動的な purge は将来課題。
+ */
+const subscribedBindings = new WeakMap();
+function getWcBindable(element) {
+    const customTagName = getCustomElement(element);
+    if (customTagName === null) {
+        return null;
+    }
+    const customClass = customElements.get(customTagName);
+    if (typeof customClass === "undefined") {
+        raiseError(`Custom element <${customTagName}> is not defined for command binding.`);
+    }
+    const bindable = customClass.wcBindable;
+    if (bindable?.protocol === "wc-bindable" && bindable?.version === 1) {
+        return bindable;
+    }
+    return null;
+}
+function applyChangeToCommand(binding, _context, newValue) {
+    if (!isCommandToken(newValue)) {
+        raiseError(`command binding requires a CommandToken value (use $commandToken or $commandTokens declaration).`);
+    }
+    const token = newValue;
+    const existing = subscribedBindings.get(binding);
+    if (existing && existing.token === token) {
+        return;
+    }
+    // 新しい binding 妥当性検証は、旧 subscription を解除する前に通す（fail-fast）。
+    const element = binding.node;
+    const methodName = binding.propSegments[1];
+    if (typeof methodName !== "string" || methodName.length === 0) {
+        raiseError(`command binding requires a method name (e.g., "command.fetch").`);
+    }
+    const bindable = getWcBindable(element);
+    if (bindable === null) {
+        raiseError(`command binding requires a wc-bindable custom element. <${element.tagName.toLowerCase()}> is not wc-bindable.`);
+    }
+    if (!Array.isArray(bindable.commands) || !bindable.commands.includes(methodName)) {
+        raiseError(`Command "${methodName}" is not declared in wcBindable.commands of <${element.tagName.toLowerCase()}>.`);
+    }
+    // ここまで来たら旧解除して新 subscribe に切り替える。
+    if (existing) {
+        existing.unsubscribe();
+        subscribedBindings.delete(binding);
+    }
+    const elementRef = new WeakRef(element);
+    let unsubscribe = null;
+    const subscriber = (...args) => {
+        const el = elementRef.deref();
+        if (!el || !el.isConnected) {
+            unsubscribe?.();
+            subscribedBindings.delete(binding);
+            return undefined;
+        }
+        const method = el[methodName];
+        if (typeof method !== "function") {
+            raiseError(`Method "${methodName}" is not a function on <${el.tagName.toLowerCase()}>.`);
+        }
+        return Reflect.apply(method, el, args);
+    };
+    unsubscribe = token.subscribe(subscriber);
+    subscribedBindings.set(binding, { token, unsubscribe, elementRef });
+}
+
 const _cache$1 = new WeakMap();
 const _cacheNullListIndex = new WeakMap();
 class StateAddress {
@@ -3088,6 +3207,7 @@ const applyChangeByFirstSegment = {
     "class": applyChangeToClass,
     "attr": applyChangeToAttribute,
     "style": applyChangeToStyle,
+    "command": applyChangeToCommand,
 };
 const applyChangeByBindingType = {
     "text": applyChangeToText,
@@ -4821,6 +4941,117 @@ function createLoopContextStack() {
     return new LoopContextStack();
 }
 
+/**
+ * `$commandTokens: ["a", "b", ...]` 配列宣言を解析し、宣言された名前群を Set で返す。
+ *
+ * 注入は行わず、proxy 側で `state.$command.<name>` として token を解決する設計。
+ * （以前の実装は state 直下に各名前の getter を注入していたが、リアクティブ値との
+ * 名前空間衝突を避け識別性を上げるため `$command` ネームスペース集約に切り替え。）
+ *
+ * 対応している宣言形式は **オブジェクトリテラル** のみ。
+ * クラス本体に `static $commandTokens = [...]` を書く形式や、
+ * クラスのプロトタイプ上の同名コマンドの検出は現状サポートしない。
+ */
+function processCommandTokensDeclaration(state) {
+    const names = new Set();
+    const declared = state[STATE_COMMAND_TOKENS_NAME];
+    if (typeof declared === "undefined") {
+        return names;
+    }
+    if (!Array.isArray(declared)) {
+        raiseError(`${STATE_COMMAND_TOKENS_NAME} must be an array of strings.`);
+    }
+    for (const name of declared) {
+        if (typeof name !== "string" || name.length === 0) {
+            raiseError(`${STATE_COMMAND_TOKENS_NAME} entries must be non-empty strings.`);
+        }
+        if (name === STATE_COMMAND_NAMESPACE_NAME) {
+            raiseError(`${STATE_COMMAND_TOKENS_NAME} entry "${name}" conflicts with the reserved namespace name "${STATE_COMMAND_NAMESPACE_NAME}".`);
+        }
+        if (names.has(name)) {
+            raiseError(`${STATE_COMMAND_TOKENS_NAME} entry "${name}" is duplicated.`);
+        }
+        names.add(name);
+    }
+    return names;
+}
+
+const registryByStateElement = new WeakMap();
+function getOrCreateCommandToken(stateElement, name) {
+    let registry = registryByStateElement.get(stateElement);
+    if (typeof registry === "undefined") {
+        registry = new Map();
+        registryByStateElement.set(stateElement, registry);
+    }
+    let token = registry.get(name);
+    if (typeof token === "undefined") {
+        token = new CommandToken(name);
+        registry.set(name, token);
+    }
+    return token;
+}
+function clearCommandTokenRegistry(stateElement) {
+    registryByStateElement.delete(stateElement);
+}
+
+/**
+ * `state.$command` でアクセスされる command token の namespace proxy を提供する。
+ *
+ * - state element 単位で memo 化し、同一 stateElement なら同じ proxy が返る。
+ * - 宣言された名前 (`$commandTokens` に列挙されたもの) のみ token を返す。
+ *   宣言外の名前にアクセスした場合は undefined を返す。
+ *   （`constructor` / `Symbol.toPrimitive` / `then` など内部システムが触るキーで
+ *    例外を投げないため。typo は subsequent な `.emit()` 呼び出しで TypeError として
+ *    間接的に表面化する。）
+ * - token そのものの memo は `getOrCreateCommandToken` 側に集約されており、
+ *   namespace proxy は薄いゲートウェイとして振る舞う。
+ */
+const namespaceProxyByStateElement = new WeakMap();
+function getCommandNamespace(stateElement) {
+    const cached = namespaceProxyByStateElement.get(stateElement);
+    if (typeof cached !== "undefined") {
+        return cached;
+    }
+    const proxy = new Proxy(Object.create(null), {
+        get(_target, prop) {
+            if (typeof prop !== "string") {
+                return undefined;
+            }
+            if (!stateElement.commandTokenNames.has(prop)) {
+                return undefined;
+            }
+            return getOrCreateCommandToken(stateElement, prop);
+        },
+        has(_target, prop) {
+            return typeof prop === "string" && stateElement.commandTokenNames.has(prop);
+        },
+        ownKeys() {
+            return Array.from(stateElement.commandTokenNames);
+        },
+        getOwnPropertyDescriptor(_target, prop) {
+            if (typeof prop === "string" && stateElement.commandTokenNames.has(prop)) {
+                return {
+                    configurable: true,
+                    enumerable: true,
+                    value: getOrCreateCommandToken(stateElement, prop),
+                };
+            }
+            return undefined;
+        },
+        set() {
+            raiseError(`$command namespace is read-only; assigning to it is not allowed.`);
+        },
+        deleteProperty() {
+            raiseError(`$command namespace is read-only; deleting from it is not allowed.`);
+        },
+    });
+    namespaceProxyByStateElement.set(stateElement, proxy);
+    return proxy;
+}
+function clearCommandNamespace(stateElement) {
+    namespaceProxyByStateElement.delete(stateElement);
+}
+
 function getterFn(name) {
     return function () {
         const stateEl = this.stateElement;
@@ -4832,7 +5063,8 @@ function getterFn(name) {
                 value = state[name];
             });
         }
-        catch {
+        catch (e) {
+            console.warn(`[@wcstack/state] DCC getter "${name}" failed:`, e);
             return undefined;
         }
         return value;
@@ -4855,22 +5087,25 @@ function callFn(name, isAsync) {
         return function (...args) {
             const stateEl = this.stateElement;
             if (!stateEl)
-                return;
+                return undefined;
             return stateEl.initializePromise.then(() => {
+                let result;
                 return stateEl.createStateAsync("writable", async (state) => {
-                    await state[name](...args);
-                });
+                    result = await state[name](...args);
+                }).then(() => result);
             });
         };
     }
     return function (...args) {
         const stateEl = this.stateElement;
         if (!stateEl)
-            return;
-        stateEl.initializePromise.then(() => {
+            return undefined;
+        return stateEl.initializePromise.then(() => {
+            let result;
             stateEl.createState("writable", (state) => {
-                state[name](...args);
+                result = state[name](...args);
             });
+            return result;
         });
     };
 }
@@ -4904,7 +5139,8 @@ function defineDCC(hostElement, shadowRoot, state) {
         raiseError(`DCC: "${tagName}" is not a valid custom element name (must contain a hyphen).`);
     }
     if (customElements.get(tagName)) {
-        // 既に登録済みならスキップ
+        // 既に登録済みならスキップ（重複定義の検知のため警告は出す）
+        console.warn(`[@wcstack/state] DCC: "${tagName}" is already registered. Skipping redefinition.`);
         return;
     }
     // ShadowRoot は cloneNode 不可のため、template 経由で内容をクローン
@@ -6025,6 +6261,9 @@ function get(target, prop, receiver, handler) {
                         return trackDependency(target, prop, receiver, handler)(path);
                     };
                 }
+                case STATE_COMMAND_NAMESPACE_NAME: {
+                    return getCommandNamespace(handler.stateElement);
+                }
             }
         }
         else {
@@ -6630,6 +6869,7 @@ class State extends HTMLElement {
     _boundComponent = null;
     _boundComponentStateProp = null;
     _bindableEventMap = {};
+    _commandTokenNames = new Set();
     constructor() {
         super();
         this._initializePromise = new Promise((resolve) => {
@@ -6652,6 +6892,7 @@ class State extends HTMLElement {
         return this.__state;
     }
     set _state(value) {
+        this._commandTokenNames = processCommandTokensDeclaration(value);
         this.__state = value;
         this._listPaths.clear();
         this._elementPaths.clear();
@@ -6864,6 +7105,8 @@ class State extends HTMLElement {
         if (this._rootNode !== null) {
             this._callStateDisconnectedCallback();
             setStateElementByName(this.rootNode, this._name, null);
+            clearCommandTokenRegistry(this);
+            clearCommandNamespace(this);
             this._rootNode = null;
         }
     }
@@ -6909,6 +7152,9 @@ class State extends HTMLElement {
     get bindableEventMap() {
         return this._bindableEventMap;
     }
+    get commandTokenNames() {
+        return this._commandTokenNames;
+    }
     setBindableEventMap(map) {
         this._bindableEventMap = map;
     }