@wcstack/state 1.8.5 → 1.9.0

package/README.ja.md

@@ -1,16 +1,40 @@
 # @wcstack/state
 
-**もしHTMLにリアクティブなデータバインディングがあったら？**
+**これは便利な既存FWの別実装ではありません。フロントエンド開発の前提を組み替える、別系譜の試みです。**
 
-ブラウザが状態をネイティブに理解する未来を想像してみてください。データをインラインで宣言し、属性でDOMにバインドするだけで、すべてが自動で同期します。仮想DOMもコンパイルも不要。ただのHTMLが、そのままリアクティブになる世界です。
+多くのライブラリは、UI・状態・コンポーネントの結合点を JavaScript の中に置きます。`@wcstack/state` はそこを選びません。仮想DOMも、コンパイルも、hook も、selector も前提にせず、HTML とパス文字列だけを契約として UI と状態を結びつけます。
 
-それが `<wcs-state>` と `data-wcs` の目指すアプローチです。CDNからの読み込みだけで動作し、依存パッケージはゼロ、構文はHTMLそのままです。
+それが `<wcs-state>` と `data-wcs` のアプローチです。CDNからの読み込みだけで動作し、依存パッケージはゼロ、構文はHTMLそのままです。CDNのスクリプトはカスタム要素の定義を登録するだけで、ロード時にはそれ以外の処理は走りません。`<wcs-state>` 要素がDOMに接続されたときにはじめて、状態ソースを読み取り、同一ルートノード（`document` または `ShadowRoot`）内の `data-wcs` バインディングを走査してリアクティビティを構築します。初期化プロセスはすべて要素のライフサイクルによって駆動されるため、独自の初期化コードを書く必要はありません。
 
-CDNのスクリプトはカスタム要素の定義を登録するだけで、ロード時にはそれ以外の処理は走りません。`<wcs-state>` 要素がDOMに接続されたときにはじめて、状態ソースを読み取り、同一ルートノード（`document` または `ShadowRoot`）内の `data-wcs` バインディングを走査してリアクティビティを構築します。初期化プロセスはすべて要素のライフサイクルによって駆動されるため、独自の初期化コードを書く必要はありません。
+## ここには存在しないもの
 
-## 設計思想
+以下は未実装ではありません。**設計上、存在しません。**
 
-### パスが唯一の契約
+- 変数を取り出す API
+- 要素ごとに状態を束縛するオブジェクト
+- hook
+- selector
+- reactive primitive をコンポーネントへ引き込むための glue code
+
+None of these exist by design.
+
+なぜなら、このライブラリでは UI と状態の結合点を JavaScript の中に置かないからです。状態を「取り出して」コンポーネントへ渡すのではなく、HTML 側がパス文字列によって状態を参照します。要素は状態を所有せず、状態も要素を知りません。両者が共有するのはパスだけです。
+
+## 既存FWとは比較しません
+
+これは React / Vue / Solid と同じ問題を別の方法で解いているのではありません。**前提自体が違います。**
+
+| 一般的なFWが前提にするもの | `@wcstack/state` が前提にするもの |
+|---|---|
+| コンポーネントが UI と状態の結合点 | パス文字列が UI と状態の結合点 |
+| JavaScript が描画の中心 | HTML と DOM が中心 |
+| state を取り出して component へ流し込む | path を宣言して DOM を状態へ接続する |
+| hook / selector / signal で購読する | 属性とパスで束縛する |
+| フレームワークの実行モデルにアプリ全体を載せる | ブラウザ標準の上に薄い reactive layer を足す |
+
+比較表を作るより先に、この前提差を理解してください。同じ棚に置いても、解いている問題の切り取り方が違います。
+
+## 第一原理: パスが唯一の契約
 
 既存の多くのフレームワークでは、**コンポーネント**がUIと状態の結合点になっています。状態ストアを外部に切り出しても、コンポーネント内にフックやセレクタ、リアクティブプリミティブといった**状態を引き込むためのコード**が必ず必要になります。つまり、UIと状態は常にJavaScriptの中で結びついているのです。
 
@@ -40,6 +64,8 @@ CDNのスクリプトはカスタム要素の定義を登録するだけで、
 
 このパスによる契約は、REST APIのURLと同じ発想です — 両者が合意するシンプルな文字列だけが存在し、そこに共有するコードはありません。これはJavaScriptの上に独自のテンプレート言語を発明するのではなく、HTML本来の宣言的な性質をフルに活かした結果として生まれた設計です。
 
+以下の機能はすべて、この原理の帰結です。機能が先にあり、その説明として哲学を後付けしているのではありません。
+
 ## わずか4ステップで動作
 
 ```html
@@ -62,7 +88,7 @@ CDNのスクリプトはカスタム要素の定義を登録するだけで、
 
 これだけです。ビルドツールも、初期化コードも、重いフレームワークも必要ありません。
 
-## 特徴
+## この原理から導かれる機能
 
 - **宣言的データバインディング** — `data-wcs` 属性によるプロパティ / テキスト / イベント / 構造バインディング
 - **リアクティブ Proxy** — ES Proxy による依存追跡付き自動 DOM 更新
@@ -216,7 +242,9 @@ this["user.name"] = "Bob";     // パス "user.name"
 
 ### なぜ `this.user.name = "Bob"` ではDOMが更新されないのか
 
-通常のプロパティアクセスの書き方だと、まず `this.user` でプレーンな `user` オブジェクトを読み取り（パスの読み取り）、取得したオブジェクトの `.name` を直接書き換える挙動になります。これは「パスに対するプロパティ代入」というフックを経由していないため、システム側で変更を検知できません：
+これは単なる制約ではなく、**契約境界が見えている箇所**です。
+
+通常のプロパティアクセスの書き方だと、まず `this.user` でプレーンな `user` オブジェクトを読み取り（パスの読み取り）、取得したオブジェクトの `.name` を直接書き換える挙動になります。これは「パスに対するプロパティ代入」という契約を通っていません。そのため、システム側は変更を検知しません：
 
 ```javascript
 // ✅ パスへの代入 — 変更が検知される
@@ -226,6 +254,8 @@ this["user.name"] = "Bob";
 this.user.name = "Bob";
 ```
 
+`this.user.name = "Bob"` も動くようにすると、一見便利にはなります。しかしその瞬間に「UI と状態はパスだけで結ばれる」という原理が崩れます。どこで依存を追跡し、どこで更新を確定するかが曖昧になり、契約境界が失われます。
+
 ### 配列
 
 配列についても全く同じルールが適用されます。常に**パスに対して新しい配列を代入**してください。`push` や `splice`、`sort` などの破壊的な配列メソッドは、パスへの代入を介さずに状態をその場で（in-placeに）書き換えてしまうため、変更が検知されません。代わりに、新しい配列を返す非破壊的なメソッドを使用します：

package/README.md

@@ -1,16 +1,40 @@
 # @wcstack/state
 
-**What if HTML had reactive data binding?**
+**This is not another convenient frontend framework. It is a different lineage that rearranges the premises of frontend development.**
 
-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.
+Most libraries place the coupling point between UI, state, and components inside JavaScript. `@wcstack/state` does not. It assumes no virtual DOM, no compilation step, no hooks, no selectors. UI and state are connected by HTML and path strings alone.
 
-That's what `<wcs-state>` and `data-wcs` explore. One CDN import, zero dependencies, pure HTML syntax.
+That is 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 all `data-wcs` bindings within the same root node (`document` or `ShadowRoot`), and wires up reactivity. All initialization is driven by the element's lifecycle, not by your code.
 
-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 all `data-wcs` bindings within the same root node (`document` or `ShadowRoot`), and wires up reactivity. All initialization is driven by the element's lifecycle, not by your code.
+## What Does Not Exist Here
 
-## Design Philosophy
+The following are not missing features. **They do not exist by design.**
 
-### Path as the Universal Contract
+- APIs for pulling variables out of state into components
+- Per-element binding objects that mediate state access
+- hooks
+- selectors
+- glue code that imports reactive primitives into component code
+
+None of these exist by design.
+
+Why: this library does not put the UI-state coupling point inside JavaScript. State is not pulled into components. HTML refers to state through path strings. Elements do not own state, and state does not know elements. The only shared contract is the path.
+
+## Do Not Compare This to Existing Frameworks
+
+This is not solving the same problem as React / Vue / Solid with a different syntax. **The premises are different.**
+
+| What mainstream frameworks assume | What `@wcstack/state` assumes |
+|---|---|
+| Components are the coupling point between UI and state | Path strings are the coupling point between UI and state |
+| JavaScript is the center of rendering | HTML and the DOM are the center |
+| State is pulled into components | Paths are declared and the DOM connects to state |
+| hooks / selectors / signals express subscriptions | Attributes and paths express bindings |
+| The whole app runs inside a framework execution model | A thin reactive layer is added on top of web standards |
+
+Before making a comparison chart, understand this difference in premises. These tools may live in the same ecosystem, but they cut the problem space very differently.
+
+## First Principle: Path as the Universal Contract
 
 In every existing framework, the **component** is the coupling point between UI and state. Components import state hooks, selectors, or reactive primitives, and the binding happens inside JavaScript. No matter how cleanly you separate your state store, there is always glue code in the component that pulls state in.
 
@@ -40,6 +64,8 @@ This is complete separation of UI and state with **no JavaScript intermediary**.
 
 The path contract works like a URL in a REST API — a simple string that both sides agree on, with no shared code between them. It's the natural result of building on HTML's declarative nature rather than inventing a template language on top of JavaScript.
 
+Every feature below is a consequence of this principle. The principle comes first; the features follow from it.
+
 ## 4 Steps to Reactive HTML
 
 ```html
@@ -62,7 +88,7 @@ The path contract works like a URL in a REST API — a simple string that both s
 
 That's it. No build, no bootstrap code, no framework.
 
-## Features
+## Features Derived from This Principle
 
 - **Declarative data binding** — `data-wcs` attribute for property / text / event / structural binding
 - **Reactive Proxy** — ES Proxy-based automatic DOM updates with dependency tracking
@@ -70,6 +96,7 @@ That's it. No build, no bootstrap code, no framework.
 - **Built-in filters** — 40 filters for formatting, comparison, arithmetic, date, and more
 - **Two-way binding** — automatic for `<input>`, `<select>`, `<textarea>`
 - **Web Component binding** — bidirectional state binding with Shadow DOM components
+- **Command tokens** — invoke methods on wc-bindable custom elements from state via a pub/sub channel (`command.<method>: tokenName`)
 - **Path getters** — dot-path key getters (`get "users.*.fullName"()`) for virtual properties at any depth in a data tree, all defined flat in one place with automatic dependency tracking and caching
 - **Mustache syntax** — `{{ path|filter }}` in text nodes
 - **Multiple state sources** — JSON, JS module, inline script, API, attribute
@@ -216,7 +243,9 @@ That's the one rule: **assign to the path, and the DOM updates automatically.**
 
 ### Why `this.user.name = "Bob"` Doesn't Work
 
-`this.user.name` first reads the `user` object via `this.user` (a path read), then sets `.name` on that plain object — this is not a path assignment, so the change is not detected:
+This is not just a limitation. It is where the contract boundary becomes visible.
+
+`this.user.name` first reads the `user` object via `this.user` (a path read), then sets `.name` on that plain object — this does not go through the contract of path assignment, so the change is not detected:
 
 ```javascript
 // ✅ Path assignment — change detected
@@ -226,6 +255,8 @@ this["user.name"] = "Bob";
 this.user.name = "Bob";
 ```
 
+It may seem more convenient to make `this.user.name = "Bob"` reactive too. But doing that would break the principle that UI and state are connected only through paths. Dependency tracking and update boundaries would become implicit and ambiguous. The visible contract boundary is the point.
+
 ### Arrays
 
 The same rule applies: assign a new array to the path. Mutating methods (`push`, `splice`, `sort`, ...) modify the array in place without path assignment, so use non-destructive alternatives:
@@ -739,6 +770,7 @@ Inside state objects (getters / methods), the following APIs are available via `
 | `this.$resolve(path, indexes, value?)` | Resolve a wildcard path with specific indexes |
 | `this.$postUpdate(path)` | Manually trigger update notification for a path |
 | `this.$trackDependency(path)` | Manually register a dependency for cache invalidation |
+| `this.$command.<name>` | Access a `CommandToken` declared in `$commandTokens` (see [Command Token](#command-token-method-binding)) |
 | `this.$stateElement` | Access to the `IStateElement` instance |
 | `this.$1`, `this.$2`, ... | Current loop index (1-based naming, 0-based value) |
 
@@ -1015,6 +1047,110 @@ customElements.define("my-component", MyComponent);
 </template>
 ```
 
+## Command Token (Method Binding)
+
+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>`
+- 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
+
+This keeps the path contract intact: state never holds a reference to the element, and the element never imports anything from state. The token is the only shared object.
+
+### Basic Usage
+
+```html
+<wcs-state>
+  <script type="module">
+    export default {
+      $commandTokens: ["fetchUsers", "refreshOrders"],
+
+      onClickFetch() {
+        this.$command.fetchUsers.emit("/api/users", { method: "GET" });
+      },
+      onClickRefresh() {
+        this.$command.refreshOrders.emit();
+      }
+    };
+  </script>
+</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>
+
+<button data-wcs="onclick: onClickFetch">Fetch users</button>
+<button data-wcs="onclick: onClickRefresh">Refresh orders</button>
+```
+
+When `onClickFetch` runs, every element subscribed to the `fetchUsers` token has its `fetch(...)` method called with the forwarded arguments.
+
+### `$commandTokens` Declaration
+
+The `$commandTokens` array declares the channels exposed under the `$command` namespace on state. Tokens are accessed as `this.$command.<name>` and are memoized — the same name always returns the same token instance.
+
+```javascript
+export default {
+  $commandTokens: ["fetchUsers", "refreshOrders"],
+
+  click() {
+    this.$command.fetchUsers.emit("/api/users");
+  }
+};
+```
+
+- Entries must be non-empty strings
+- 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
+
+### `command.<methodName>:` Binding
+
+```html
+<wcs-fetch data-wcs="command.fetch: 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`) |
+
+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)
+
+### Token API
+
+```typescript
+interface CommandToken {
+  readonly name: string;
+  readonly size: number;                            // current subscriber count
+  subscribe(fn: (...args) => unknown): () => void;  // returns unsubscribe
+  unsubscribe(fn: (...args) => unknown): boolean;
+  emit(...args: unknown[]): unknown[];              // returns subscriber results in subscribe order
+}
+```
+
+`emit` returns an array of return values from each subscriber (in subscribe order). For `Promise`-returning methods, wrap with `Promise.all(token.emit(...))` to await all of them.
+
+### Subscription Lifecycle
+
+- The subscriber holds the element via `WeakRef`, so a removed element can still be garbage collected even while it remains in the token's subscriber set
+- On `emit`, if the WeakRef has been collected or the element is no longer connected (`isConnected === false`), the subscription is purged automatically (lazy purge)
+- When the owning `<wcs-state>` is disconnected, the entire token registry is cleared
+
+The element's method is invoked with the arguments from `emit`:
+
+```javascript
+this.$command.fetchUsers.emit(url, options);
+// → element.fetch(url, options) on every subscriber
+```
+
 ## 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.d.ts

@@ -133,14 +133,14 @@ type IsAny<T> = 0 extends (1 & T) ? true : false;
  * T がドットパス再帰の対象となる「プレーンなデータオブジェクト」かどうかを判定する。
  * プリミティブ、組み込みオブジェクト (Date, Map 等)、関数、配列、any は除外。
  */
-type IsPlainObject<T> = IsAny<T> extends true ? false : T extends string | number | boolean | null | undefined | symbol | bigint | Function | Date | RegExp | Error | Map<any, any> | Set<any> | WeakMap<any, any> | WeakSet<any> | Promise<any> | readonly any[] ? false : T extends Record<string, any> ? true : false;
+type IsPlainObject<T> = IsAny<T> extends true ? false : T extends string | number | boolean | null | undefined | symbol | bigint | ((...args: any[]) => any) | Date | RegExp | Error | Map<any, any> | Set<any> | WeakMap<any, any> | WeakSet<any> | Promise<any> | readonly any[] ? false : T extends Record<string, any> ? true : false;
 /**
  * T のキーのうち、関数でないもの（データプロパティ・computed getter）を抽出する。
  * メソッド（イベントハンドラ等）はドットパスの対象外。
  * any 型のプロパティは除外せず保持する。
  */
 type DataKeys<T> = {
-    [K in keyof T & string]: IsAny<T[K]> extends true ? K : T[K] extends Function ? never : K;
+    [K in keyof T & string]: IsAny<T[K]> extends true ? K : T[K] extends (...args: any[]) => any ? never : K;
 }[keyof T & string];
 /**
  * 型 T から生成される全てのドットパスの union。