@wcstack/state 4.0.0-rc.4 → 4.0.0-rc.5

package/README.ja.md

@@ -191,9 +191,9 @@
 <script type="importmap">
 {
   "imports": {
-    "@wcstack/state/core": "https://cdn.jsdelivr.net/npm/@wcstack/state@4.0.0-rc.4/dist/split/core.js",
-    "@wcstack/state/features/temporal": "https://cdn.jsdelivr.net/npm/@wcstack/state@4.0.0-rc.4/dist/split/features/temporal.js",
-    "@wcstack/state/features/scopes": "https://cdn.jsdelivr.net/npm/@wcstack/state@4.0.0-rc.4/dist/split/features/scopes.js"
+    "@wcstack/state/core": "https://cdn.jsdelivr.net/npm/@wcstack/state@4.0.0-rc.5/dist/split/core.js",
+    "@wcstack/state/features/temporal": "https://cdn.jsdelivr.net/npm/@wcstack/state@4.0.0-rc.5/dist/split/features/temporal.js",
+    "@wcstack/state/features/scopes": "https://cdn.jsdelivr.net/npm/@wcstack/state@4.0.0-rc.5/dist/split/features/scopes.js"
   }
 }
 </script>
@@ -229,6 +229,7 @@
 | `@wcstack/state/core` | バインディングの本体: `data-wcs`・`{{ }}` とコメントバインディング・`for` / `if`・パス getter・イベント・`$command` / `$on`・条件の 10 個のフィルタ（`eq` `ne` `not` `lt` `le` `gt` `ge` `truthy` `falsy` `boolean`）・`bootstrapState`・`installFeatures` |
 | `@wcstack/state/features/temporal` | `$watch`・`$stream` |
 | `@wcstack/state/features/list-keys` | `$listKeys` |
+| `@wcstack/state/features/native-commands` | ネイティブ要素の `command.<method>:`（`<dialog>` の `showModal()`・`<input>` の `focus()`・`<video>` の `play()` など）—— [ネイティブ要素のコマンド](#ネイティブ要素のコマンド) |
 | `@wcstack/state/features/scopes` | `bind-component`・`mount=` のボリューム・オーバーレイの公開 getter・DCC（`data-wc-definition`） |
 | `@wcstack/state/features/recursion` | `$recursion` と `**` パス |
 | `@wcstack/state/features/ssr` | `enable-ssr`: サーバー描画とハイドレーション |
@@ -252,7 +253,7 @@
 ページが名指したアドオンを、同じビルドから読み込みます。
 
 ```html
-<script type="module" src="https://cdn.jsdelivr.net/npm/@wcstack/state@4.0.0-rc.4/dist/split/auto.js"></script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/@wcstack/state@4.0.0-rc.5/dist/split/auto.js"></script>
 <wcs-state features="scopes diagnostics">
   <script type="module">
     export default {
@@ -274,7 +275,7 @@
 | 何のためか | どの `<wcs-state>` が動き出すよりも前に揃っているべきもの — `mount=` / `bind-component` / DCC の要素が何であるかを決める `scopes` — と、ページの開発補助（`diagnostics`・`devtools`） | その state が必要とするアドオン（`$watch` のための `temporal`、フィルタのための `formats`） |
 | 誰が読むか | 分割版の auto エントリだけ | すべてのエントリ: 分割版の auto エントリは足りないアドオンを読み込み、それ以外のエントリは入っているかを確かめ、入っていなければその state を `[wcs/feature-not-installed]` で失敗させる |
 
-名前は `formats`・`diagnostics`・`temporal`・`list-keys`・`scopes`・`recursion`・`ssr`・`devtools` です。
+名前は `formats`・`diagnostics`・`temporal`・`list-keys`・`scopes`・`recursion`・`ssr`・`devtools`・`native-commands` です。
 `features=` にそれ以外の名前があると、分割版の auto エントリは `<wcs-state>` を定義する前に
 `[wcs/feature-unknown]` で失敗します。`$features` にあれば、その state が失敗します（分割版の auto
 エントリでは `[wcs/feature-unknown]`、それ以外では `[wcs/feature-not-installed]`）。配列でない
@@ -2104,7 +2105,7 @@ export default {
 | 部位 | 説明 |
 |---|---|
 | `command.` | 固定の prefix |
-| `<methodName>` | 起動する要素のメソッド。名前は `static wcBindable.commands` に `{ name: "<methodName>" }` として現れること |
+| `<methodName>` | 起動する要素のメソッド。名前は `static wcBindable.commands` に `{ name: "<methodName>" }` として現れること —— ネイティブ要素では [ネイティブ要素のコマンド](#ネイティブ要素のコマンド) の表にあること |
 | `$command.<tokenName>` | `CommandToken` に解決される明示的な名前空間パス。`<tokenName>` は `$commandTokens` で宣言された名前であること |
 
 右辺は `$command.<tokenName>` と書く必要があります —— ベア名の省略形（`fetchUsers`）は非対応です。`$command.` 名前空間を経由することでバインディングの意図が HTML 上で明示され、トップレベルの state 名前空間を token 名で汚さずに済みます。
@@ -2130,11 +2131,11 @@ class MyFetcher extends HTMLElement {
 
 検証ルール（バインディング時に強制）：
 
-- 要素は `protocol: "wc-bindable"` かつ整数 `version` が `1` 以上（現行プロトコルは `1`。1 以上のすべてのバージョンが core 互換）の `static wcBindable` を公開するカスタム要素であること
-- `methodName` は `wcBindable.commands` に（`name` で）現れること
+- 要素は `protocol: "wc-bindable"` かつ整数 `version` が `1` 以上（現行プロトコルは `1`。1 以上のすべてのバージョンが core 互換）の `static wcBindable` を公開するカスタム要素であること —— または、`native-commands` アドオンがあればネイティブ要素（[ネイティブ要素のコマンド](#ネイティブ要素のコマンド)）
+- `methodName` は `wcBindable.commands` に（`name` で）現れること（ネイティブ要素では [ネイティブ要素のコマンド](#ネイティブ要素のコマンド) の表にあること）
 - `<tokenName>` は `$commandTokens` で宣言されていること（`$command.typo` は `[wcs/token-undeclared]` を throw する）
 
-カスタム要素はクラスが定義された時点で検査され、ネイティブ要素はその場で拒否されます（`[wcs/token-misconfigured]`）。ページのバインド中に見つかった違反は `<wcs-state>` の初期化を失敗させます。`for:` / `if:` の行の中で見つかった違反や、ページのバインド後にクラスが定義されて見つかった違反は、そのバインディング 1 本の失敗として `$errorCallback` に届き、行はそのまま構築されます（[初期化の失敗](#初期化の失敗)）。
+カスタム要素はクラスが定義された時点で検査され、ネイティブ要素はその場で検査されます —— アドオンが入っていれば（`@wcstack/state` と `/auto` には含まれています）[native-commands](#ネイティブ要素のコマンド) の表と照合し、入っていなければ拒否します（`[wcs/token-misconfigured]` `#1202`）。ページのバインド中に見つかった違反は `<wcs-state>` の初期化を失敗させます。`for:` / `if:` の行の中で見つかった違反や、ページのバインド後にクラスが定義されて見つかった違反は、そのバインディング 1 本の失敗として `$errorCallback` に届き、行はそのまま構築されます（[初期化の失敗](#初期化の失敗)）。
 
 ### Token API
 
@@ -2192,6 +2193,64 @@ command token は state コードから emit する必要はありません。DO
 <my-list  data-wcs="command.reset: $command.reset"></my-list>
 ```
 
+### ネイティブ要素のコマンド
+
+`native-commands` アドオン（`@wcstack/state` と `/auto` には含まれています。`/core` のページは `@wcstack/state/features/native-commands` を入れます）があると、`command.<method>:` は**ネイティブ**要素のメソッドも購読します。ダイアログを開く・入力欄にフォーカスする・動画を再生するといった操作が「state が emit する token」になり、state のコードは要素に手を伸ばしません：
+
+```html
+<button data-wcs="onclick: $command.openEditor">編集</button>
+<dialog data-wcs="command.showModal: $command.openEditor; command.close: $command.closeEditor">
+  <input data-wcs="value: title">
+  <button data-wcs="onclick: save">保存</button>
+</dialog>
+```
+
+```javascript
+export default {
+  title: "",
+  $commandTokens: ["openEditor", "closeEditor"],
+  async save() {
+    await saveTitle(this.title);
+    this.$command.closeEditor.emit("saved");   // → dialog.close("saved")
+  },
+};
+```
+
+ネイティブ要素が呼べるのは次の表のメソッドだけです。それ以外のメソッドは、カスタム要素の宣言に無いコマンドと同じく、バインディングの取り付け時に `[wcs/token-misconfigured]`（`#1205`。その要素が呼べるメソッドを列挙する）を throw します：
+
+| 要素 | メソッド |
+|---|---|
+| すべての要素 | `focus` `blur` `click` `scrollIntoView` `showPopover` `hidePopover` `togglePopover` |
+| `<dialog>` | `show` `showModal` `close` `requestClose` |
+| `<form>` | `requestSubmit` `checkValidity` `reportValidity` |
+| `<input>` | `select` `setSelectionRange` `showPicker` `setCustomValidity` `checkValidity` `reportValidity` |
+| `<textarea>` | `select` `setSelectionRange` `setCustomValidity` `checkValidity` `reportValidity` |
+| `<select>` | `showPicker` `setCustomValidity` `checkValidity` `reportValidity` |
+| `<audio>` `<video>` | `play` `pause` `load` |
+
+意図して入れていないもの: HTML・属性・木を書き換えるメソッド（`insertAdjacentHTML`・`setAttribute`・`remove` など —— `html:` / `attr.` で束縛してください）、`input` イベント無しでコントロールの値を変えるため state が変化を知らないもの（`form.reset()`・`stepUp()`・`stepDown()`・`setRangeText()` —— state を書き換えてください）、入力検証と `submit` イベントを飛ばす `form.submit()`（`requestSubmit` はどちらも飛ばしません）、そして状態の出力も持つ `@wcstack/fullscreen`・`@wcstack/pointer-lock`・`@wcstack/picture-in-picture` が扱うフルスクリーン / ポインタロック / ピクチャーインピクチャーの要求です。
+
+- **引数。** ネイティブのメソッドは `emit` の引数を受け取ります。ただし第 1 引数が `Event` なら引数なしで呼びます。`on…: $command.x` のバインディングは `(event, ...listIndexes)` を emit しますが、これを受け取るネイティブメソッドはありません —— `close(event)` は dialog の `returnValue` を `"[object PointerEvent]"` にし、`requestSubmit(event)` は throw します。state からの `emit("saved")`・`emit({ preventScroll: true })`・`emit({ block: "center" })` はそのまま渡ります。カスタム要素のメソッドは従来どおりすべてを受け取ります。
+- **決めるのは表で、ブラウザではありません。** 表にあるメソッドはどのブラウザでも（サーバーでも）束縛できます。そのメソッドを持たないブラウザ（古いブラウザの `requestClose` など）では、token が emit されたときに呼び出しが失敗し、throw した購読者と同じく報告されます。
+- **戻り値と例外**はカスタム要素と同じです: `emit` は `checkValidity()` の真偽値や `play()` の `Promise` を返します。throw したメソッド（非モーダルで開いている dialog への `showModal()`、`popover` の無い要素への `showPopover()`）は `console.error` で報告され、ほかの購読者には届きます。reject した `Promise` は捕捉しません: 自動再生の拒否を扱うには、state から `await Promise.all(this.$command.play.emit())` してください。
+- **描画は後から走ります。** 書き込みはマイクロタスクで描画されるので、`this.editing = true; this.$command.focusTitle.emit();` の emit は、まだ表示されていない入力欄に —— `if:` の中なら、まだ作られていない入力欄に —— 届きます。描かれてから `$renderedCallback` で emit してください：
+
+  ```html
+  <template data-wcs="if: editing">
+    <input data-wcs="value: title; command.focus: $command.focusTitle">
+  </template>
+  ```
+
+  ```javascript
+  $renderedCallback(paths) {
+    if (paths.includes("editing") && this.editing) this.$command.focusTitle.emit();
+  },
+  ```
+
+- **ユーザー操作。** `showPicker()` と音声つきの `play()` は直前のユーザー操作を必要とします。`on…: $command.x` はイベントの処理の中でメソッドを呼びますが、`await` の後の `emit` では間に合わないことがあります。
+- **カスタム要素は変わりません**: コマンドは `wcBindable` で宣言し、宣言の無いものは従来どおり `#1202` を throw します。カスタマイズ済み組み込み要素（`<button is="…">`）はネイティブ要素です。
+- **ボタンだけで開閉が済むなら**、プラットフォームの invoker commands は state を必要としません: `<button commandfor="dlg" command="show-modal">`。state が決めるとき（fetch の後、検証の後）や、invoker commands に無い操作（`focus`・`play`・`scrollIntoView`）に `command.` を使ってください。
+
 ## Event Token（イベントバインディング）
 
 command token はコンポーネントへ *押し込み* ます（state がメソッドを起動）。**event token** はその正確な双対 —— コンポーネントから *引き出し* ます（要素がイベントを dispatch し、state が受信）。両者で要素 ↔ state 境界の双方向をカバーし、どちらの側も相手への参照を一切持ちません。共有されるのは token のみです。

package/README.md

@@ -192,9 +192,9 @@ leaves features out, it can compose them instead:
 <script type="importmap">
 {
   "imports": {
-    "@wcstack/state/core": "https://cdn.jsdelivr.net/npm/@wcstack/state@4.0.0-rc.4/dist/split/core.js",
-    "@wcstack/state/features/temporal": "https://cdn.jsdelivr.net/npm/@wcstack/state@4.0.0-rc.4/dist/split/features/temporal.js",
-    "@wcstack/state/features/scopes": "https://cdn.jsdelivr.net/npm/@wcstack/state@4.0.0-rc.4/dist/split/features/scopes.js"
+    "@wcstack/state/core": "https://cdn.jsdelivr.net/npm/@wcstack/state@4.0.0-rc.5/dist/split/core.js",
+    "@wcstack/state/features/temporal": "https://cdn.jsdelivr.net/npm/@wcstack/state@4.0.0-rc.5/dist/split/features/temporal.js",
+    "@wcstack/state/features/scopes": "https://cdn.jsdelivr.net/npm/@wcstack/state@4.0.0-rc.5/dist/split/features/scopes.js"
   }
 }
 </script>
@@ -230,6 +230,7 @@ The file names under `dist/split/chunks/` carry a content hash: if you list chun
 | `@wcstack/state/core` | The binding engine: `data-wcs`, `{{ }}` and comment bindings, `for` / `if`, path getters, events, `$command` / `$on`, the 10 condition filters (`eq` `ne` `not` `lt` `le` `gt` `ge` `truthy` `falsy` `boolean`), `bootstrapState`, `installFeatures` |
 | `@wcstack/state/features/temporal` | `$watch`, `$stream` |
 | `@wcstack/state/features/list-keys` | `$listKeys` |
+| `@wcstack/state/features/native-commands` | `command.<method>:` on native elements (`<dialog>`.`showModal()`, `<input>`.`focus()`, `<video>`.`play()`, …) — [Native Element Commands](#native-element-commands) |
 | `@wcstack/state/features/scopes` | `bind-component`, `mount=` volumes, overlay exports, DCC (`data-wc-definition`) |
 | `@wcstack/state/features/recursion` | `$recursion` and `**` paths |
 | `@wcstack/state/features/ssr` | `enable-ssr`: server rendering and hydration |
@@ -253,7 +254,7 @@ receptacle the owning add-on fills on install).
 core, and the add-ons the page names from the same build.
 
 ```html
-<script type="module" src="https://cdn.jsdelivr.net/npm/@wcstack/state@4.0.0-rc.4/dist/split/auto.js"></script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/@wcstack/state@4.0.0-rc.5/dist/split/auto.js"></script>
 <wcs-state features="scopes diagnostics">
   <script type="module">
     export default {
@@ -275,8 +276,8 @@ The add-ons are named in two places, for two different reasons:
 | What it is for | What must be there before any `<wcs-state>` starts — `scopes`, which decides what a `mount=` / `bind-component` / DCC element is — and the page's development aids (`diagnostics`, `devtools`) | The add-ons that state needs (`temporal` for its `$watch`, `formats` for its filters) |
 | Who reads it | Only the split auto entry | Every entry: the split auto entry loads the missing add-ons; the other entries check that they are installed and fail the state with `[wcs/feature-not-installed]` otherwise |
 
-The names are `formats`, `diagnostics`, `temporal`, `list-keys`, `scopes`, `recursion`, `ssr` and
-`devtools`. Any other name in `features=` makes the split auto entry fail with `[wcs/feature-unknown]`
+The names are `formats`, `diagnostics`, `temporal`, `list-keys`, `scopes`, `recursion`, `ssr`,
+`devtools` and `native-commands`. Any other name in `features=` makes the split auto entry fail with `[wcs/feature-unknown]`
 before it defines `<wcs-state>`; in `$features` it fails that state (`[wcs/feature-unknown]` on the
 split auto entry, `[wcs/feature-not-installed]` elsewhere). A `$features` that is not an array throws
 `#46`, and a volume may not declare one.
@@ -2114,7 +2115,7 @@ export default {
 | Part | Description |
 |---|---|
 | `command.` | Fixed prefix |
-| `<methodName>` | The element's method to invoke. The name must appear as `{ name: "<methodName>" }` in `static wcBindable.commands` |
+| `<methodName>` | The element's method to invoke. The name must appear as `{ name: "<methodName>" }` in `static wcBindable.commands` — on a native element, in the table of [Native Element Commands](#native-element-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.
@@ -2140,11 +2141,11 @@ class MyFetcher extends HTMLElement {
 
 Validation rules (enforced at binding time):
 
-- The element must be a custom element exposing `static wcBindable` with `protocol: "wc-bindable"` and an integer `version` of `1` or later (the current protocol version is `1`; all versions ≥ 1 are core-compatible)
-- `methodName` must appear (by `name`) in `wcBindable.commands`
+- The element must be a custom element exposing `static wcBindable` with `protocol: "wc-bindable"` and an integer `version` of `1` or later (the current protocol version is `1`; all versions ≥ 1 are core-compatible) — or a native element, with the `native-commands` add-on ([Native Element Commands](#native-element-commands))
+- `methodName` must appear (by `name`) in `wcBindable.commands` (on a native element: in the table of [Native Element Commands](#native-element-commands))
 - `<tokenName>` must be declared in `$commandTokens` (`$command.typo` throws `[wcs/token-undeclared]`)
 
-A custom element is checked once its class is defined; a native element is refused at once (`[wcs/token-misconfigured]`). A violation found while the page is bound fails the `<wcs-state>`'s initialization; one found inside a `for:` / `if:` row, or when a class is defined after the page was bound, fails that one binding, which goes to `$errorCallback`, and the row is still built ([Initialization failures](#initialization-failures)).
+A custom element is checked once its class is defined; a native element at once — against the [native-commands](#native-element-commands) table where the add-on is installed (`@wcstack/state` and `/auto` include it), and refused otherwise (`[wcs/token-misconfigured]` `#1202`). A violation found while the page is bound fails the `<wcs-state>`'s initialization; one found inside a `for:` / `if:` row, or when a class is defined after the page was bound, fails that one binding, which goes to `$errorCallback`, and the row is still built ([Initialization failures](#initialization-failures)).
 
 ### Token API
 
@@ -2202,6 +2203,64 @@ This is pure wiring: the event endpoint is connected to a command-token endpoint
 <my-list  data-wcs="command.reset: $command.reset"></my-list>
 ```
 
+### Native Element Commands
+
+With the `native-commands` add-on (`@wcstack/state` and `/auto` include it; a `/core` page installs `@wcstack/state/features/native-commands`), `command.<method>:` also subscribes a **native** element's method. Opening a dialog, focusing an input or playing a video becomes a token the state emits — the state code never reaches for the element:
+
+```html
+<button data-wcs="onclick: $command.openEditor">Edit</button>
+<dialog data-wcs="command.showModal: $command.openEditor; command.close: $command.closeEditor">
+  <input data-wcs="value: title">
+  <button data-wcs="onclick: save">Save</button>
+</dialog>
+```
+
+```javascript
+export default {
+  title: "",
+  $commandTokens: ["openEditor", "closeEditor"],
+  async save() {
+    await saveTitle(this.title);
+    this.$command.closeEditor.emit("saved");   // → dialog.close("saved")
+  },
+};
+```
+
+A native element may run only the methods of this table. Any other method throws `[wcs/token-misconfigured]` (`#1205`, naming the methods that element may run) when the binding is attached — like an undeclared command of a custom element:
+
+| Element | Methods |
+|---|---|
+| any element | `focus` `blur` `click` `scrollIntoView` `showPopover` `hidePopover` `togglePopover` |
+| `<dialog>` | `show` `showModal` `close` `requestClose` |
+| `<form>` | `requestSubmit` `checkValidity` `reportValidity` |
+| `<input>` | `select` `setSelectionRange` `showPicker` `setCustomValidity` `checkValidity` `reportValidity` |
+| `<textarea>` | `select` `setSelectionRange` `setCustomValidity` `checkValidity` `reportValidity` |
+| `<select>` | `showPicker` `setCustomValidity` `checkValidity` `reportValidity` |
+| `<audio>` `<video>` | `play` `pause` `load` |
+
+Left out on purpose: the methods that write HTML, an attribute or the tree (`insertAdjacentHTML`, `setAttribute`, `remove`, … — bind `html:` / `attr.` instead); those that change a control's value without an `input` event, so the state would not see it (`form.reset()`, `stepUp()`, `stepDown()`, `setRangeText()` — write the state instead); `form.submit()`, which skips validation and the `submit` event (`requestSubmit` does neither); and the fullscreen / pointer-lock / picture-in-picture requests, which `@wcstack/fullscreen`, `@wcstack/pointer-lock` and `@wcstack/picture-in-picture` cover along with their state.
+
+- **Arguments.** A native method receives the `emit` arguments unless the first one is an `Event`. An `on…: $command.x` binding emits `(event, ...listIndexes)`, which no native method takes — `close(event)` would set the dialog's `returnValue` to `"[object PointerEvent]"`, `requestSubmit(event)` would throw — so it is called with none. From the state, `emit("saved")`, `emit({ preventScroll: true })` or `emit({ block: "center" })` pass through. A custom element's method still receives everything.
+- **The table decides, not the browser.** A method in the table binds in every browser (and on the server). Where a browser lacks it (`requestClose` in an older one), the call fails when the token is emitted and is reported like any subscriber that throws.
+- **Return values and errors** follow the custom elements': `emit` returns `checkValidity()`'s boolean or `play()`'s `Promise`. A method that throws (`showModal()` on a dialog already open non-modally, `showPopover()` on an element without `popover`) is reported with `console.error`, and the other subscribers still run. A rejected `Promise` is not caught: `await Promise.all(this.$command.play.emit())` from the state to handle an autoplay refusal.
+- **Rendering comes later.** Writes render in a microtask, so `this.editing = true; this.$command.focusTitle.emit();` reaches an input that is still hidden — or, inside `if:`, not built yet. Emit once it is drawn, from `$renderedCallback`:
+
+  ```html
+  <template data-wcs="if: editing">
+    <input data-wcs="value: title; command.focus: $command.focusTitle">
+  </template>
+  ```
+
+  ```javascript
+  $renderedCallback(paths) {
+    if (paths.includes("editing") && this.editing) this.$command.focusTitle.emit();
+  },
+  ```
+
+- **User activation.** `showPicker()` and `play()` with sound need a recent user gesture. `on…: $command.x` calls the method inside the event; an `emit` after an `await` may come too late.
+- **Custom elements are unchanged**: they declare their commands in `wcBindable`, and one without a declaration still throws `#1202`. A customized built-in (`<button is="…">`) is a native element.
+- **When a button alone opens or closes it**, the platform's invoker commands need no state at all: `<button commandfor="dlg" command="show-modal">`. Use `command.` when the state decides (after a fetch, after validation), or for what invoker commands do not cover (`focus`, `play`, `scrollIntoView`).
+
 ## Event Token (Event Binding)
 
 Command tokens push *into* a component (state invokes a method). **Event tokens** are the exact dual — they pull *out* of a component (an element dispatches an event, state receives it). Together they cover both directions of the element ↔ state boundary, and neither side ever holds a reference to the other — the token is the only shared object.