@wcstack/state 1.10.4 → 1.11.0

package/README.ja.md

@@ -380,6 +380,55 @@ property[#modifier]: path[@state][|filter[|filter(args)...]]
 
 内部的にはコメントベースのバインディング（`<!--@@:expression-->`）に変換されます。
 
+### Spread バインディング (`...`)
+
+`wc-bindable` プロトコルを宣言したカスタム要素に対して、`...: target` を使うと要素の **properties + inputs を 1 行で一括配線**できます：
+
+```html
+<wcs-fetch data-wcs="...: usersFetch"></wcs-fetch>
+```
+
+```js
+export default {
+  usersFetch: {
+    url: "/api/users",
+    method: "GET",
+    value: null,
+    loading: false,
+    error: null,
+    status: null,
+  }
+}
+```
+
+ランタイムが `customClass.wcBindable.properties + inputs` を読み取り、各 name を個別バインディング（`usersFetch.value`、`usersFetch.url`、...）に展開します。
+
+**対象範囲**：spread は *データサーフェス*（properties + inputs）のみを対象とします。`commands` や event token は **対象外** — pub/sub の発火点が HTML から読めるように、明示配線を維持してください。
+
+**for ループ内**：`...: items.*`（推奨）または dot ショートカット `...: .` を使います：
+
+```html
+<template data-wcs="for: storesFetches">
+  <wcs-fetch data-wcs="...: storesFetches.*"></wcs-fetch>
+</template>
+```
+
+**後勝ち上書き** — spread の後ろに同名 prop を書くと、明示側が優先されます：
+
+```html
+<wcs-fetch data-wcs="...: usersFetch; status: alternateStatus"></wcs-fetch>
+```
+
+**制約事項**：
+
+- spread 右辺へのフィルタ（`...: target|filter`）はエラー
+- 右辺パスの途中に `*` を含めても OK（例：`...: stores.*.fetch`）
+- `@stateName` 修飾子は各展開エントリへ伝播（`...: fetchX@store`）
+- カスタム要素クラスが未登録の場合、`customElements.whenDefined(tag)` 解決時に遅延展開される（autoloader による遅延ロードに対応）
+- `wcBindable` 宣言**のない**要素はエラー（明示配線で書いてください）。spread は何を展開すべきかを契約から読み取るため
+
+**Composite shell**（wc-bindable Composition Profile）はそのままサポートされます：composite shell は標準の `target.constructor.wcBindable` を通じて synthesized declaration を露出するため、`"s3.progress"` のような composed name はフラットな要素メンバーキーとして扱われます。state を composed 構造に合わせて (`{ s3: { progress: 0 } }`) 持てば、`...: pipeline` が自動的に nested state path へ展開されます。
+
 ## 構造ディレクティブ
 
 構造ディレクティブは `<template>` 要素で使用します：

package/README.md

@@ -381,6 +381,55 @@ When `enableMustache` is `true` (default), `{{ expression }}` in text nodes is s
 
 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:
+
+```html
+<wcs-fetch data-wcs="...: usersFetch"></wcs-fetch>
+```
+
+```js
+export default {
+  usersFetch: {
+    url: "/api/users",
+    method: "GET",
+    value: null,
+    loading: false,
+    error: null,
+    status: null,
+  }
+}
+```
+
+Runtime reads `customClass.wcBindable.properties + inputs` and expands each name into an individual binding (`usersFetch.value`, `usersFetch.url`, ...).
+
+**Scope**: spread covers the *data surfaces* (properties + inputs). `commands` and event tokens are intentionally **not** included — wire them explicitly so the pub/sub points remain visible in HTML.
+
+**Inside a for loop**: use `...: items.*` (recommended) or the dot shortcut `...: .`:
+
+```html
+<template data-wcs="for: storesFetches">
+  <wcs-fetch data-wcs="...: storesFetches.*"></wcs-fetch>
+</template>
+```
+
+**Last-wins override** — explicit binding after `...` overrides the spread:
+
+```html
+<wcs-fetch data-wcs="...: usersFetch; status: alternateStatus"></wcs-fetch>
+```
+
+**Constraints**:
+
+- Filters on the spread target (`...: target|filter`) are rejected.
+- The right-hand path may contain `*` anywhere (e.g. `...: stores.*.fetch`).
+- `@stateName` propagates to every expanded entry (`...: fetchX@store`).
+- If the custom element class is not yet registered, expansion is deferred until `customElements.whenDefined(tag)` resolves — autoloader-style late registration is supported.
+- Elements **without** a `wcBindable` declaration are rejected (write bindings explicitly). Spread requires the contract to know what to expand.
+
+**Composite shells** (wc-bindable Composition Profile) are supported transparently: a composite shell exposes its synthesized declaration through the standard `target.constructor.wcBindable` surface, and composed names like `"s3.progress"` are kept as flat element member keys. Mirror the composed structure in state (`{ s3: { progress: 0 } }`) and `...: pipeline` expands into nested state paths automatically.
+
 ## Structural Directives
 
 Structural directives use `<template>` elements:

package/dist/index.esm.js

@@ -59,7 +59,7 @@ function setConfig(partialConfig) {
     }
 }
 
-var version$1 = "1.10.4";
+var version$1 = "1.11.0";
 var pkg = {
 	version: version$1};
 
@@ -110,58 +110,6 @@ function replaceToReplaceNode(bindingInfo) {
     node.parentNode.replaceChild(replaceNode, node);
 }
 
-function resolveNodePath(root, path) {
-    let currentNode = root;
-    if (path.length === 0)
-        return currentNode;
-    // path.reduce()だと途中でnullになる可能性があるので、
-    for (let i = 0; i < path.length; i++) {
-        currentNode = currentNode?.childNodes[path[i]] ?? null;
-        if (currentNode === null)
-            break;
-    }
-    return currentNode;
-}
-
-function getBindingInfos(node, parseBindingTextResults) {
-    const bindingInfos = [];
-    for (const parseBindingTextResult of parseBindingTextResults) {
-        if (parseBindingTextResult.bindingType !== 'text') {
-            bindingInfos.push({
-                ...parseBindingTextResult,
-                node: node,
-                replaceNode: node,
-            });
-        }
-        else {
-            const replaceNode = document.createTextNode('');
-            bindingInfos.push({
-                ...parseBindingTextResult,
-                node: node,
-                replaceNode: replaceNode,
-            });
-        }
-    }
-    return bindingInfos;
-}
-
-const bindingsByNode = new WeakMap();
-function getBindingsByNode(node) {
-    return bindingsByNode.get(node) || null;
-}
-function setBindingsByNode(node, bindings) {
-    bindingsByNode.set(node, bindings);
-}
-function addBindingByNode(node, binding) {
-    const bindings = getBindingsByNode(node);
-    if (bindings === null) {
-        setBindingsByNode(node, [binding]);
-    }
-    else {
-        bindings.push(binding);
-    }
-}
-
 const DELIMITER = '.';
 const WILDCARD = '*';
 const MAX_WILDCARD_DEPTH = 128;
@@ -294,6 +242,237 @@ class PathInfo {
     }
 }
 
+const cache = new WeakMap();
+function getCustomElement(node) {
+    const cached = cache.get(node);
+    if (cached !== undefined) {
+        return cached;
+    }
+    let value = null;
+    try {
+        if (node.nodeType !== Node.ELEMENT_NODE) {
+            return value;
+        }
+        const element = node;
+        const tagName = element.tagName.toLowerCase();
+        if (tagName.includes("-")) {
+            return value = tagName;
+        }
+        if (element.hasAttribute("is")) {
+            const is = element.getAttribute("is");
+            if (is.includes("-")) {
+                return value = is;
+            }
+        }
+        return value;
+    }
+    finally {
+        cache.set(node, value);
+    }
+}
+
+function isValidWcBindable(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const v = value;
+    return v.protocol === "wc-bindable"
+        && v.version === 1
+        && Array.isArray(v.properties);
+}
+function makeExpandedEntry(name, base, stateName) {
+    // Dot-relative spread keeps the loop item root (`.`) without producing `..foo`.
+    const expandedPath = base === "." ? `.${name}` : `${base}.${name}`;
+    return {
+        propName: name,
+        propSegments: [name],
+        propModifiers: [],
+        statePathName: expandedPath,
+        statePathInfo: getPathInfo(expandedPath),
+        stateName,
+        inFilters: [],
+        outFilters: [],
+        bindingType: 'prop',
+    };
+}
+function dedupKey(r) {
+    switch (r.bindingType) {
+        case 'prop':
+        case 'event':
+        case 'radio':
+        case 'checkbox':
+            return `${r.bindingType}::${r.propName}`;
+        case 'spread':
+            return null;
+        default:
+            return null;
+    }
+}
+/**
+ * Expand spread bind-text entries (`...: target`) into per-prop entries
+ * by enumerating wcBindable.properties + inputs of the element's class.
+ *
+ * Behavior:
+ * - With `allowDeferred: true` (default): if class is not yet defined, the
+ *   spread entry stays so the caller can wait via customElements.whenDefined.
+ * - With `allowDeferred: false`: raises if class is not defined.
+ * - Duplicate propName: last-wins (explicit binding overrides spread).
+ * - When config.debug, console.debug logs each override.
+ * - Mid-`*` in target path is allowed (e.g. `...: stores.*.fetch`).
+ *
+ * Composite Profile (COMPOSITE.md / SPEC-extensions § 4) support:
+ * - A composite shell exposes its synthesized declaration via the standard
+ *   `target.constructor.wcBindable` surface (§ 1 Discovery), so this function
+ *   handles it without any composite-specific code path.
+ * - Composed property names use the `<sourceId>.<sourceName>` pattern
+ *   (e.g. "s3.progress"); we keep the dotted name as a single segment so
+ *   element member access stays flat (element["s3.progress"], not nested).
+ * - The expanded state path becomes `targetBase.s3.progress`, which resolves
+ *   as nested state access — author state as `{ s3: { progress: 0 } }` to
+ *   mirror the composed structure.
+ * - Tier claim (Symbol.for("wc-bindable.composite.tiers")) is not read here;
+ *   spread covers observation (T1) and writable inputs (T2) transparently
+ *   through normal property assignment, and commands stay out of spread by
+ *   design regardless of tier.
+ */
+function expandSpread(node, results, options = {}) {
+    const allowDeferred = options.allowDeferred ?? true;
+    if (!results.some(r => r.bindingType === 'spread')) {
+        return results;
+    }
+    const expanded = [];
+    const spreadOrigin = new WeakSet();
+    for (const result of results) {
+        if (result.bindingType !== 'spread') {
+            expanded.push(result);
+            continue;
+        }
+        if (node.nodeType !== Node.ELEMENT_NODE) {
+            raiseError(`Spread binding requires an element node.`);
+        }
+        const element = node;
+        const tagName = getCustomElement(element);
+        if (tagName === null) {
+            raiseError(`Spread binding "${result.statePathName}" requires a custom element with wcBindable, but <${element.tagName.toLowerCase()}> is not a custom element.`);
+        }
+        const customClass = customElements.get(tagName);
+        if (typeof customClass === "undefined") {
+            if (!allowDeferred) {
+                raiseError(`Spread binding "${result.statePathName}" requires <${tagName}> to be registered. Define the custom element before initializing this binding.`);
+            }
+            // Deferred: keep spread entry intact; caller retries via whenDefined.
+            expanded.push(result);
+            continue;
+        }
+        const bindable = customClass.wcBindable;
+        if (!isValidWcBindable(bindable)) {
+            raiseError(`Spread binding "${result.statePathName}" requires <${tagName}> to declare wcBindable (protocol="wc-bindable", version=1).`);
+        }
+        const targetBase = result.statePathName;
+        const stateName = result.stateName;
+        const seen = new Set();
+        for (const prop of bindable.properties) {
+            if (seen.has(prop.name))
+                continue;
+            seen.add(prop.name);
+            const entry = makeExpandedEntry(prop.name, targetBase, stateName);
+            spreadOrigin.add(entry);
+            expanded.push(entry);
+        }
+        // properties win over inputs when the name overlaps because they carry the
+        // full property contract (for example change events).
+        for (const input of (bindable.inputs ?? [])) {
+            if (seen.has(input.name))
+                continue;
+            seen.add(input.name);
+            const entry = makeExpandedEntry(input.name, targetBase, stateName);
+            spreadOrigin.add(entry);
+            expanded.push(entry);
+        }
+    }
+    // Last-wins de-duplication
+    const lastIndexByKey = new Map();
+    for (let i = 0; i < expanded.length; i++) {
+        const key = dedupKey(expanded[i]);
+        if (key !== null) {
+            lastIndexByKey.set(key, i);
+        }
+    }
+    const final = [];
+    for (let i = 0; i < expanded.length; i++) {
+        const key = dedupKey(expanded[i]);
+        if (key === null) {
+            final.push(expanded[i]);
+            continue;
+        }
+        if (lastIndexByKey.get(key) === i) {
+            final.push(expanded[i]);
+        }
+        else if (config.debug && spreadOrigin.has(expanded[i])) {
+            const overrider = expanded[lastIndexByKey.get(key)];
+            const tagText = node.nodeType === Node.ELEMENT_NODE
+                ? `<${node.tagName.toLowerCase()}>`
+                : 'node';
+            console.debug(`[@wcstack/state] spread: prop "${expanded[i].propName}" of ${tagText} overridden by explicit binding (statePath: "${overrider.statePathName}").`);
+        }
+    }
+    return final;
+}
+function hasUnresolvedSpread(results) {
+    return results.some(r => r.bindingType === 'spread');
+}
+
+function resolveNodePath(root, path) {
+    let currentNode = root;
+    if (path.length === 0)
+        return currentNode;
+    // path.reduce()だと途中でnullになる可能性があるので、
+    for (let i = 0; i < path.length; i++) {
+        currentNode = currentNode?.childNodes[path[i]] ?? null;
+        if (currentNode === null)
+            break;
+    }
+    return currentNode;
+}
+
+function getBindingInfos(node, parseBindingTextResults) {
+    const bindingInfos = [];
+    for (const parseBindingTextResult of parseBindingTextResults) {
+        if (parseBindingTextResult.bindingType !== 'text') {
+            bindingInfos.push({
+                ...parseBindingTextResult,
+                node: node,
+                replaceNode: node,
+            });
+        }
+        else {
+            const replaceNode = document.createTextNode('');
+            bindingInfos.push({
+                ...parseBindingTextResult,
+                node: node,
+                replaceNode: replaceNode,
+            });
+        }
+    }
+    return bindingInfos;
+}
+
+const bindingsByNode = new WeakMap();
+function getBindingsByNode(node) {
+    return bindingsByNode.get(node) || null;
+}
+function setBindingsByNode(node, bindings) {
+    bindingsByNode.set(node, bindings);
+}
+function addBindingByNode(node, binding) {
+    const bindings = getBindingsByNode(node);
+    if (bindings === null) {
+        setBindingsByNode(node, [binding]);
+    }
+    else {
+        bindings.push(binding);
+    }
+}
+
 const STRUCTURAL_BINDING_TYPE_SET = new Set([
     "if",
     "elseif",
@@ -1247,6 +1426,7 @@ function parseStatePart(statePart) {
 //   elseif: statePart only (single binding for conditional rendering)
 //   for: statePart only (single binding for loop rendering)
 //   onclick: statePart, onchange: statePart etc. (event listeners)
+//   ...: statePart (spread — expand wcBindable properties+inputs of target object)
 function parseBindTextsForElement(bindText) {
     const [...bindTexts] = bindText.split(';').map(trimFn).filter(s => s.length > 0);
     const results = bindTexts.map((bindText) => {
@@ -1270,6 +1450,23 @@ function parseBindTextsForElement(bindText) {
                 bindingType: 'else',
             };
         }
+        else if (propPart === '...') {
+            const stateResult = parseStatePart(statePart);
+            if (stateResult.outFilters.length > 0) {
+                raiseError(`Invalid spread binding "${bindText}": filters are not allowed on spread targets.`);
+            }
+            if (stateResult.statePathName.length === 0) {
+                raiseError(`Invalid spread binding "${bindText}": spread target path is required.`);
+            }
+            return {
+                propName: '...',
+                propSegments: ['...'],
+                propModifiers: [],
+                inFilters: [],
+                ...stateResult,
+                bindingType: 'spread',
+            };
+        }
         else if (propPart === 'if'
             || propPart === 'elseif'
             || propPart === 'for'
@@ -1430,20 +1627,39 @@ function getSubscriberNodes(root) {
 }
 
 const registeredNodeSet = new WeakSet();
+function processParseResultsForNode(node, parseResults, options) {
+    const expanded = expandSpread(node, parseResults, { allowDeferred: options.allowDeferred });
+    if (hasUnresolvedSpread(expanded)) {
+        const tagName = node.nodeType === Node.ELEMENT_NODE
+            ? getCustomElement(node)
+            : null;
+        if (tagName === null) {
+            raiseError(`Spread binding deferred but element is not a custom element.`);
+        }
+        return { bindings: [], deferred: { node, tagName, parseResults } };
+    }
+    registeredNodeSet.add(node);
+    const bindings = getBindingInfos(node, expanded);
+    setBindingsByNode(node, bindings);
+    resolveInitializedBinding(node);
+    return { bindings, deferred: null };
+}
 function collectNodesAndBindingInfos(root) {
     const subscriberNodes = getSubscriberNodes(root);
     const allBindings = [];
+    const deferredSpreads = [];
     for (const node of subscriberNodes) {
-        if (!registeredNodeSet.has(node)) {
-            registeredNodeSet.add(node);
-            const parseBindingTextResults = getParseBindTextResults(node);
-            const bindings = getBindingInfos(node, parseBindingTextResults);
-            setBindingsByNode(node, bindings);
-            resolveInitializedBinding(node);
-            allBindings.push(...bindings);
+        if (registeredNodeSet.has(node))
+            continue;
+        const parseResults = getParseBindTextResults(node);
+        const result = processParseResultsForNode(node, parseResults, { allowDeferred: true });
+        if (result.deferred !== null) {
+            deferredSpreads.push(result.deferred);
+            continue;
         }
+        allBindings.push(...result.bindings);
     }
-    return [subscriberNodes, allBindings];
+    return [subscriberNodes, allBindings, deferredSpreads];
 }
 function collectNodesAndBindingInfosByFragment(root, nodeInfos) {
     const nodes = [];
@@ -1453,17 +1669,29 @@ function collectNodesAndBindingInfosByFragment(root, nodeInfos) {
         if (node === null) {
             raiseError(`Node not found by path [${nodeInfo.nodePath.join(', ')}] in fragment.`);
         }
-        if (!registeredNodeSet.has(node)) {
-            registeredNodeSet.add(node);
-            const bindings = getBindingInfos(node, nodeInfo.parseBindTextResults);
-            setBindingsByNode(node, bindings);
-            resolveInitializedBinding(node);
-            allBindings.push(...bindings);
-            nodes.push(node);
-        }
+        if (registeredNodeSet.has(node))
+            continue;
+        const result = processParseResultsForNode(node, nodeInfo.parseBindTextResults, { allowDeferred: false });
+        // deferred is impossible when allowDeferred=false (expandSpread raises instead)
+        allBindings.push(...result.bindings);
+        nodes.push(node);
     }
     return [nodes, allBindings];
 }
+function unregisterNode(node) {
+    registeredNodeSet.delete(node);
+}
+/**
+ * Re-process a deferred spread entry once the custom element class is
+ * registered. Expands the captured parseResults, installs bindings, and
+ * returns them so the caller can attach handlers and apply state values.
+ */
+function processDeferredNode(entry) {
+    const { node, parseResults } = entry;
+    unregisterNode(node);
+    const result = processParseResultsForNode(node, parseResults, { allowDeferred: false });
+    return result.bindings;
+}
 
 const loopContextByNode = new WeakMap();
 function getLoopContextByNode(node) {
@@ -1544,35 +1772,6 @@ function attachEventHandler(binding) {
     return true;
 }
 
-const cache = new WeakMap();
-function getCustomElement(node) {
-    const cached = cache.get(node);
-    if (cached !== undefined) {
-        return cached;
-    }
-    let value = null;
-    try {
-        if (node.nodeType !== Node.ELEMENT_NODE) {
-            return value;
-        }
-        const element = node;
-        const tagName = element.tagName.toLowerCase();
-        if (tagName.includes("-")) {
-            return value = tagName;
-        }
-        if (element.hasAttribute("is")) {
-            const is = element.getAttribute("is");
-            if (is.includes("-")) {
-                return value = is;
-            }
-        }
-        return value;
-    }
-    finally {
-        cache.set(node, value);
-    }
-}
-
 const CHECK_TYPES = new Set(['radio', 'checkbox']);
 const DEFAULT_VALUE_PROP_NAMES = new Set(['value', 'valueAsNumber', 'valueAsDate']);
 function isPossibleTwoWay(node, propName) {
@@ -3665,13 +3864,7 @@ function _initializeBindings(allBindings) {
         attachCheckboxEventHandler(binding);
     }
 }
-function initializeBindings(root, parentLoopContext) {
-    const [subscriberNodes, allBindings] = collectNodesAndBindingInfos(root);
-    for (const node of subscriberNodes) {
-        setLoopContextByNode(node, parentLoopContext);
-    }
-    _initializeBindings(allBindings);
-    // create absolute state address and register binding infos
+function _registerAbsoluteAddresses(allBindings) {
     for (const binding of allBindings) {
         const absoluteStateAddress = getAbsoluteStateAddressByBinding(binding);
         addBindingByAbsoluteStateAddress(absoluteStateAddress, binding);
@@ -3684,8 +3877,34 @@ function initializeBindings(root, parentLoopContext) {
             stateElement.setPathInfo(binding.statePathName, binding.bindingType);
         }
     }
+}
+function _scheduleDeferredSpreads(deferredSpreads, parentLoopContext) {
+    for (const entry of deferredSpreads) {
+        customElements.whenDefined(entry.tagName).then(() => {
+            if (!entry.node.isConnected)
+                return; // node was removed before class became ready
+            const bindings = processDeferredNode(entry);
+            if (bindings.length === 0)
+                return;
+            setLoopContextByNode(entry.node, parentLoopContext);
+            _initializeBindings(bindings);
+            _registerAbsoluteAddresses(bindings);
+            applyChangeFromBindings(bindings);
+        }).catch((error) => {
+            console.error(`[@wcstack/state] deferred spread failed for <${entry.tagName}>.`, error);
+        });
+    }
+}
+function initializeBindings(root, parentLoopContext) {
+    const [subscriberNodes, allBindings, deferredSpreads] = collectNodesAndBindingInfos(root);
+    for (const node of subscriberNodes) {
+        setLoopContextByNode(node, parentLoopContext);
+    }
+    _initializeBindings(allBindings);
+    _registerAbsoluteAddresses(allBindings);
     // apply all at once
     applyChangeFromBindings(allBindings);
+    _scheduleDeferredSpreads(deferredSpreads, parentLoopContext);
 }
 function initializeBindingsByFragment(root, nodeInfos) {
     const [subscriberNodes, allBindings] = collectNodesAndBindingInfosByFragment(root, nodeInfos);