@wcstack/state 1.3.13 → 1.3.15

package/README.ja.md

@@ -1,7 +1,12 @@
 # @wcstack/state
 
-Web Components のための宣言的リアクティブ状態管理。  
-`<wcs-state>` カスタム要素と `data-wcs` 属性バインディング — ランタイム依存ゼロ。
+**もしHTMLにリアクティブなデータバインディングがあったら？**
+
+ブラウザが状態をネイティブに理解する未来を妄想してみる。データをインラインで宣言し、属性でDOMにバインドすれば、すべてが自動で同期する。仮想DOMもコンパイルも不要。ただのHTMLが、勝手にリアクティブになる。
+
+それが `<wcs-state>` と `data-wcs` の探求するもの。CDN一発、依存ゼロ、構文はHTML。
+
+CDNスクリプトはカスタム要素の定義を登録するだけ — ロード時にはそれ以外何も起きない。`<wcs-state>` 要素がDOMに接続されたとき、状態ソースを読み取り、兄弟要素の `data-wcs` バインディングを走査し、リアクティビティを構築する。すべての初期化は要素のライフサイクルが駆動する。あなたのコードではなく。
 
 ## 特徴
 
@@ -300,6 +305,8 @@ property[#modifier]: path[@state][|filter[|filter(args)...]]
 </template>
 ```
 
+`for:` ディレクティブは**値ベースの差分アルゴリズム**を使用します。配列の各要素の値そのものが識別キーとして機能するため、React の `key` や Vue の `:key` のような明示的なキー属性は不要です。配列が再代入されると、差分アルゴリズムが新旧の要素を値で照合し、変更のない要素の DOM ノードを再利用しつつ、追加・削除・並び替えを効率的に処理します。
+
 #### ドット省略記法
 
 `for` ループ内では、`.` で始まるパスがループの配列パスを基準に展開されます：
@@ -827,6 +834,15 @@ export default {
 
 `@wcstack/state` は Shadow DOM または Light DOM を使用したカスタム要素との双方向状態バインディングに対応しています。
 
+多くのフレームワークは状態をコンポーネントに密結合させるため、ツリーをまたぐデータ共有には props バケツリレー、Context Provider、外部ストア（Redux, Pinia）といったパターンを強いられます。`@wcstack/state` では、親子コンポーネントは**パスの契約**で接続されます。親は `data-wcs` で外部の状態パスを子コンポーネントのプロパティにバインドし、子は自身の状態を通常どおり読み書きするだけです：
+
+1. 子コンポーネントは自身の状態プロキシを通じて親の状態を参照・更新します — props もイベントも親の存在を意識する必要もありません。
+2. 親の状態が変更されると、Proxy の `set` トラップが影響するパスを参照している子のバインディングへ自動的に通知します。
+3. 結合点は**パス名のみ**であるため、双方とも疎結合を保ち、独立してテスト可能です。
+4. コストはパス解決（初回アクセス後はキャッシュにより O(1)）と依存グラフを通じた変更伝播のみです。
+
+これは、他のフレームワークがますます複雑な抽象化で回避してきたコンポーネント間状態管理の問題に対する具体的な解法です。
+
 ### コンポーネント定義（Shadow DOM）
 
 ```javascript
@@ -982,6 +998,8 @@ customElements.define("my-component", MyComponent);
 | `$disconnectedCallback` | 要素が DOM から削除された時 | 不可（同期のみ） |
 | `$updatedCallback(paths, indexesListByPath)` | 状態変更が適用された後に呼び出し | 戻り値は未使用（待機されない） |
 
+リアクティブ Proxy は全てのプロパティ代入を変更として検知するため、標準の `async/await` とプロパティへの直接代入だけで非同期処理は完結します。ローディングフラグ、取得データ、エラーメッセージの更新は全てプロパティ代入です。React の Suspense や専用のローディング状態プリミティブのような抽象化は不要です。
+
 - フック内の `this` は読み書き可能な状態プロキシです
 - `$connectedCallback` は要素が接続される**たびに**呼ばれます（削除後の再接続を含む）。再確立が必要なセットアップ処理に適しています
 - `$disconnectedCallback` は同期的に呼び出されます — タイマーのクリア、イベントリスナーの削除、リソースの解放などのクリーンアップに使用します

package/README.md

@@ -1,7 +1,12 @@
 # @wcstack/state
 
-Declarative reactive state management for Web Components.  
-`<wcs-state>` custom element and `data-wcs` attribute binding — zero runtime dependencies.
+**What if HTML had reactive data binding?**
+
+Imagine a future where the browser natively understands state — you declare data inline, bind it to the DOM with attributes, and everything stays in sync. No virtual DOM, no compilation, no framework. Just HTML that reacts.
+
+That's what `<wcs-state>` and `data-wcs` explore. One CDN import, zero dependencies, pure HTML syntax.
+
+The CDN script only registers the custom element definition — nothing else happens at load time. When a `<wcs-state>` element connects to the DOM, it reads its state source, scans sibling elements for `data-wcs` bindings, and wires up reactivity. All initialization is driven by the element's lifecycle, not by your code.
 
 ## Features
 
@@ -300,6 +305,8 @@ Structural directives use `<template>` elements:
 </template>
 ```
 
+The `for:` directive uses a **value-based diff algorithm** — each array element's value itself serves as the identity key. There is no need for an explicit `key` attribute (like React's `key` or Vue's `:key`). When the array is reassigned, the differ matches old and new elements by value, reusing existing DOM nodes for unchanged items and efficiently adding, removing, or reordering the rest.
+
 #### Dot Shorthand
 
 Inside a `for` loop, paths starting with `.` are expanded relative to the loop's array path:
@@ -827,6 +834,15 @@ Filters can be chained with `|`:
 
 `@wcstack/state` supports bidirectional state binding with custom elements using Shadow DOM or Light DOM.
 
+Most frameworks tightly couple state to components, forcing patterns like prop drilling, context providers, or external stores (Redux, Pinia) just to share data across the tree. In `@wcstack/state`, parent and child components are connected through **path contracts** — the parent binds an outer state path to an inner component property via `data-wcs`, and the child simply reads and writes its own state as usual:
+
+1. The child references and updates the parent's state through its own state proxy — no props, no events, no awareness of the parent.
+2. When the parent's state changes, the Proxy `set` trap automatically notifies any child bindings that reference the affected path.
+3. Because the only coupling is the **path name**, both sides remain loosely coupled and independently testable.
+4. The cost is path resolution (cached at O(1) after first access) plus change propagation through the dependency graph.
+
+This provides a concrete solution to cross-component state management that other frameworks have been working around with increasingly complex abstractions.
+
 ### Component Definition (Shadow DOM)
 
 ```javascript
@@ -982,6 +998,8 @@ State objects can define `$connectedCallback`, `$disconnectedCallback`, and `$up
 | `$disconnectedCallback` | When the element is removed from the DOM | No (sync only) |
 | `$updatedCallback(paths, indexesListByPath)` | After state updates are applied | Return value is ignored (not awaited) |
 
+Since the reactive proxy detects every property assignment as a change, standard `async/await` with direct property updates is sufficient for asynchronous operations — loading flags, fetched data, and error messages are all just property assignments. There is no need for abstractions like React Suspense or dedicated loading-state primitives.
+
 - `this` inside hooks is the state proxy with full read/write access
 - `$connectedCallback` is called **every time** the element is connected (including re-insertion after removal), making it suitable for setup that should be re-established
 - `$disconnectedCallback` is called synchronously — use it for cleanup such as clearing timers, removing event listeners, or releasing resources

package/dist/index.esm.js

@@ -1465,7 +1465,7 @@ function getParseBindTextResults(node) {
 }
 
 /**
- * data-bind-state 属性または埋め込みノード<!--{{}}-->を持つノードをすべて取得する
+ * data-wcs 属性または埋め込みノード<!--{{}}-->を持つノードをすべて取得する
  * @param root
  * @returns
  */
@@ -2937,6 +2937,16 @@ function _applyChange(binding, context) {
             }
         }
     }
+    if (fn === applyChangeToProperty) {
+        const element = binding.node;
+        if (element.tagName === 'SELECT') {
+            const propName = binding.propSegments[0];
+            if (propName === 'value' || propName === 'selectedIndex') {
+                context.deferredSelectBindings.push({ binding, value: filteredValue });
+                return;
+            }
+        }
+    }
     fn(binding, context, filteredValue);
 }
 function applyChange(binding, context) {
@@ -2985,6 +2995,7 @@ function applyChange(binding, context) {
                 appliedBindingSet: context.appliedBindingSet,
                 newListValueByAbsAddress: context.newListValueByAbsAddress,
                 updatedAbsAddressSetByStateElement: context.updatedAbsAddressSetByStateElement,
+                deferredSelectBindings: context.deferredSelectBindings,
             };
             _applyChange(binding, newContext);
         });
@@ -2997,6 +3008,10 @@ function applyChange(binding, context) {
 /**
  * バインディング情報の配列を処理し、各バインディングに対して状態の変更を適用する。
  *
+ * 2フェーズで処理:
+ * Phase 1: 構造的更新(for/if) + 値更新(select以外) — select.value/selectedIndex は遅延収集
+ * Phase 2: 遅延されたselect.value/selectedIndex を適用（option要素の生成後）
+ *
  * 最適化のため、以下のグループ化を行う:
  * 同じ stateNameとrootNode を持つバインディングをグループ化 → createState の呼び出しを削減
  */
@@ -3005,7 +3020,8 @@ function applyChangeFromBindings(bindings) {
     const appliedBindingSet = new Set();
     const newListValueByAbsAddress = new Map();
     const updatedAbsAddressSetByStateElement = new Map();
-    // 外側ループ: stateName ごとにグループ化
+    const deferredSelectBindings = [];
+    // Phase 1: 構造的更新 + 値更新（select.value/selectedIndex は遅延）
     while (bindingIndex < bindings.length) {
         let binding = bindings[bindingIndex];
         const stateName = binding.stateName;
@@ -3037,6 +3053,7 @@ function applyChangeFromBindings(bindings) {
                 appliedBindingSet: appliedBindingSet,
                 newListValueByAbsAddress: newListValueByAbsAddress,
                 updatedAbsAddressSetByStateElement: updatedAbsAddressSetByStateElement,
+                deferredSelectBindings: deferredSelectBindings,
             };
             do {
                 applyChange(binding, context);
@@ -3051,6 +3068,11 @@ function applyChangeFromBindings(bindings) {
             } while (true); // eslint-disable-line no-constant-condition
         });
     }
+    // Phase 2: 遅延されたselect.value/selectedIndex を適用
+    // applyChangeToProperty は context を参照しないため null を渡す
+    for (const { binding, value } of deferredSelectBindings) {
+        applyChangeToProperty(binding, null, value);
+    }
     for (const [absAddress, newListValue] of newListValueByAbsAddress.entries()) {
         setLastListValueByAbsoluteStateAddress(absAddress, newListValue);
     }