@wcstack/state 1.9.0 → 1.10.0

package/README.md

@@ -1051,7 +1051,7 @@ customElements.define("my-component", MyComponent);
 
 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:
 
-- The element subscribes via `command.<methodName>: <tokenPath>`
+- The element subscribes via `command.<methodName>: $command.<tokenName>`
 - State emits via `this.$command.<tokenName>.emit(...args)`
 - Arguments passed to `emit` are forwarded to the element's method
 - One token can fan out to multiple elements; the subscriber order is preserved
@@ -1077,8 +1077,8 @@ This keeps the path contract intact: state never holds a reference to the elemen
 </wcs-state>
 
 <!-- Subscribers — must be wc-bindable custom elements -->
-<wcs-fetch data-wcs="command.fetch: fetchUsers"></wcs-fetch>
-<wcs-fetch data-wcs="command.fetch: refreshOrders"></wcs-fetch>
+<wcs-fetch data-wcs="command.fetch: $command.fetchUsers"></wcs-fetch>
+<wcs-fetch data-wcs="command.fetch: $command.refreshOrders"></wcs-fetch>
 
 <button data-wcs="onclick: onClickFetch">Fetch users</button>
 <button data-wcs="onclick: onClickRefresh">Refresh orders</button>
@@ -1104,25 +1104,46 @@ export default {
 - Duplicate entries throw an error at initialization
 - The reserved name `$command` itself cannot appear in the array
 - Tokens are gathered under `$command` so they do not pollute the top-level state namespace; reactive properties with the same name as a token can coexist
-- Accessing an undeclared name on `$command` (e.g. `this.$command.typo`) throws — typos are caught at access time
+- Accessing an undeclared name on `$command` (e.g. `this.$command.typo`) returns `undefined`. The typo then surfaces as a `TypeError` on the subsequent `.emit()` call, or — when used as a binding right-hand side — as a "requires a CommandToken value" error at binding time
 
 ### `command.<methodName>:` Binding
 
 ```html
-<wcs-fetch data-wcs="command.fetch: fetchUsers"></wcs-fetch>
+<wcs-fetch data-wcs="command.fetch: $command.fetchUsers"></wcs-fetch>
 ```
 
 | Part | Description |
 |---|---|
 | `command.` | Fixed prefix |
-| `<methodName>` | The element's method to invoke. Must be listed in `static wcBindable.commands` |
-| `<tokenPath>` | A path that resolves to a `CommandToken` (typically a name from `$commandTokens`) |
+| `<methodName>` | The element's method to invoke. The name must appear as `{ name: "<methodName>" }` in `static wcBindable.commands` |
+| `$command.<tokenName>` | Explicit namespace path that resolves to a `CommandToken`. `<tokenName>` must be a name declared in `$commandTokens` |
+
+The right-hand side must be written as `$command.<tokenName>` — the bare-name shorthand (`fetchUsers`) is not supported. Going through the `$command.` namespace makes the binding's intent explicit in the HTML and keeps the top-level state namespace free of token names.
+
+`wcBindable.commands` follows the wc-bindable v1 spec shape — an array of `{ name: string; async?: boolean }`:
+
+```javascript
+class MyFetcher extends HTMLElement {
+  static wcBindable = {
+    protocol: "wc-bindable", version: 1,
+    properties: [],
+    commands: [
+      { name: "fetch", async: true },
+      { name: "reset" },
+    ],
+  };
+  fetch(url) { /* ... */ }
+  reset()    { /* ... */ }
+}
+```
+
+> **Breaking change since v1.9.1**: the `commands` field is now an array of `{ name, async? }` objects. The earlier `commands: ["fetch"]` plain-string form is no longer accepted — bindings against such declarations throw `Command "<name>" is not declared in wcBindable.commands`. There is no legacy fallback; update the declaration to the object form.
 
 Validation rules (enforced at binding time):
 
 - The element must be a custom element exposing `static wcBindable` with `protocol: "wc-bindable"` and `version: 1`
-- `methodName` must be present in `wcBindable.commands`
-- The bound value must be a `CommandToken` (assigning a non-token value throws)
+- `methodName` must appear (by `name`) in `wcBindable.commands`
+- The bound value must be a `CommandToken` (assigning a non-token value throws — for example, an undeclared name like `$command.typo` resolves to `undefined` and is rejected here)
 
 ### Token API
 
@@ -1151,6 +1172,50 @@ this.$command.fetchUsers.emit(url, options);
 // → element.fetch(url, options) on every subscriber
 ```
 
+## 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.
+
+```javascript
+class MyChip extends HTMLElement {
+  static wcBindable = {
+    protocol: "wc-bindable", version: 1,
+    properties: [],
+    inputs: [
+      { name: "data", attribute: "data" },        // property name === attribute name
+      { name: "labelText", attribute: "label-text" }, // kebab-case mirror
+      { name: "internal" },                       // no mirror, property-only
+    ],
+  };
+}
+```
+
+```html
+<my-chip data-wcs="data: chip.payload; labelText: chip.title"></my-chip>
+```
+
+When state updates the value, both the property and the attribute are written:
+
+```text
+chip.payload = { id: 1 }    → element.data = { id: 1 } and setAttribute("data", '{"id":1}')
+chip.title   = "新着"        → element.labelText = "新着" and setAttribute("label-text", "新着")
+chip.payload = null          → element.data = null and removeAttribute("data")
+```
+
+Attribute value encoding:
+
+| Value type | Mirrored attribute |
+|---|---|
+| `string` / `number` / `boolean` / `bigint` | `String(value)` |
+| `null` / `undefined` | attribute removed |
+| `object` / `array` | `JSON.stringify(value)` (falls back to `String(value)` on circular references) |
+
+Notes:
+
+- `inputs` entries **without** `attribute` are property-only — the value is written to the property but no attribute is touched
+- 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`
+
 ## 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.

package/dist/index.esm.js

@@ -59,7 +59,7 @@ function setConfig(partialConfig) {
     }
 }
 
-var version$1 = "1.9.0";
+var version$1 = "1.10.0";
 var pkg = {
 	version: version$1};
 
@@ -2063,7 +2063,7 @@ function getWcBindable(element) {
 }
 function applyChangeToCommand(binding, _context, newValue) {
     if (!isCommandToken(newValue)) {
-        raiseError(`command binding requires a CommandToken value (use $commandToken or $commandTokens declaration).`);
+        raiseError(`command binding requires a CommandToken value (use $command.<tokenName> with a name declared in $commandTokens).`);
     }
     const token = newValue;
     const existing = subscribedBindings.get(binding);
@@ -2080,7 +2080,7 @@ function applyChangeToCommand(binding, _context, newValue) {
     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)) {
+    if (!Array.isArray(bindable.commands) || !bindable.commands.some((c) => c.name === methodName)) {
         raiseError(`Command "${methodName}" is not declared in wcBindable.commands of <${element.tagName.toLowerCase()}>.`);
     }
     // ここまで来たら旧解除して新 subscribe に切り替える。
@@ -2975,6 +2975,65 @@ function applyChangeToIf(bindingInfo, context, rawNewValue) {
     }
 }
 
+/**
+ * 要素 `element` の `propName` プロパティ書き込みに対して、
+ * wc-bindable inputs の `attribute` ミラー先属性名を返す。
+ *
+ * - wc-bindable でないネイティブ要素や、inputs 未宣言、attribute フィールド無しは null
+ * - inputs に同名宣言があっても `attribute` を持たないものはミラー対象外
+ *
+ * 戻り値の string がそのまま `setAttribute(name, value)` の name となる。
+ */
+function getInputAttributeMirror(element, propName) {
+    const customTagName = getCustomElement(element);
+    if (customTagName === null) {
+        return null;
+    }
+    const customClass = customElements.get(customTagName);
+    if (typeof customClass === "undefined") {
+        return null;
+    }
+    const bindable = customClass.wcBindable;
+    if (bindable?.protocol !== "wc-bindable" || bindable?.version !== 1) {
+        return null;
+    }
+    const inputs = bindable.inputs;
+    if (!Array.isArray(inputs)) {
+        return null;
+    }
+    for (const input of inputs) {
+        if (input.name === propName && typeof input.attribute === "string" && input.attribute.length > 0) {
+            return input.attribute;
+        }
+    }
+    return null;
+}
+/**
+ * mirror 属性値の表現を決める。
+ * - null / undefined → 属性削除
+ * - object / array → JSON.stringify (失敗時は String(value))
+ * - その他 (string / number / boolean / bigint) → String(value)
+ */
+function applyMirrorAttribute(element, attributeName, value) {
+    if (value === null || typeof value === "undefined") {
+        element.removeAttribute(attributeName);
+        return;
+    }
+    let formatted;
+    if (typeof value === "object") {
+        try {
+            formatted = JSON.stringify(value);
+        }
+        catch {
+            formatted = String(value);
+        }
+    }
+    else {
+        formatted = String(value);
+    }
+    element.setAttribute(attributeName, formatted);
+}
+
 /**
  * SSR 時に HTML 属性で表現できないプロパティバインディングを蓄積するストア。
  * ハイドレーション時にクライアント側で復元する。
@@ -3057,8 +3116,10 @@ function applyChangeToProperty(binding, _context, newValue) {
     if (propSegments.length === 1) {
         const firstSegment = propSegments[0];
         if (element[firstSegment] !== newValue) {
+            let propertyWriteSucceeded = false;
             try {
                 element[firstSegment] = newValue;
+                propertyWriteSucceeded = true;
             }
             catch (error) {
                 if (config.debug) {
@@ -3069,6 +3130,27 @@ function applyChangeToProperty(binding, _context, newValue) {
                     });
                 }
             }
+            // wc-bindable inputs[].attribute ミラー。プロパティ書き込みが成功したときだけ
+            // 属性へ反映する。setter が値を拒否した場合に属性だけ進んでしまうと
+            // property と attribute が乖離し、attributeChangedCallback や CSS セレクタが
+            // 実際のプロパティ値と矛盾した状態で発火するため、ここでガードする。
+            if (propertyWriteSucceeded) {
+                const mirrorAttr = getInputAttributeMirror(element, firstSegment);
+                if (mirrorAttr !== null) {
+                    try {
+                        applyMirrorAttribute(element, mirrorAttr, newValue);
+                    }
+                    catch (error) {
+                        if (config.debug) {
+                            console.warn(`Failed to mirror attribute '${mirrorAttr}' on element.`, {
+                                element,
+                                newValue,
+                                error
+                            });
+                        }
+                    }
+                }
+            }
         }
         if (inSsr()) {
             const attrHandler = SSR_ATTR_PROPS[firstSegment];
@@ -5411,6 +5493,19 @@ function checkDependency(handler, address) {
  * - finallyでキャッシュへの格納を保証
  */
 function _getByAddress(target, address, receiver, handler, stateElement) {
+    if (address.pathInfo.segments[0] === STATE_COMMAND_NAMESPACE_NAME) {
+        // $command 名前空間配下のパスは raw state を持たないため、proxy の get トラップと
+        // 同じ namespace を辿る。1セグメント目は namespace 本体、2セグメント目以降は
+        // namespace 上のキー (= 宣言済み command token 名) を順に走査する。
+        let value = getCommandNamespace(stateElement);
+        for (let i = 1; i < address.pathInfo.segments.length; i++) {
+            if (value == null) {
+                return undefined;
+            }
+            value = Reflect.get(value, address.pathInfo.segments[i]);
+        }
+        return value;
+    }
     if (address.pathInfo.path in target) {
         // getterの中で参照の可能性があるので、addressをプッシュする
         if (stateElement.getterPaths.has(address.pathInfo.path)) {