@wcstack/state 4.0.0-rc.8 → 4.0.0

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.8/dist/split/core.js",
-    "@wcstack/state/features/temporal": "https://cdn.jsdelivr.net/npm/@wcstack/state@4.0.0-rc.8/dist/split/features/temporal.js",
-    "@wcstack/state/features/scopes": "https://cdn.jsdelivr.net/npm/@wcstack/state@4.0.0-rc.8/dist/split/features/scopes.js"
+    "@wcstack/state/core": "https://cdn.jsdelivr.net/npm/@wcstack/state@4.0.0/dist/split/core.js",
+    "@wcstack/state/features/temporal": "https://cdn.jsdelivr.net/npm/@wcstack/state@4.0.0/dist/split/features/temporal.js",
+    "@wcstack/state/features/scopes": "https://cdn.jsdelivr.net/npm/@wcstack/state@4.0.0/dist/split/features/scopes.js"
   }
 }
 </script>
@@ -253,7 +253,7 @@
 ページが名指したアドオンを、同じビルドから読み込みます。
 
 ```html
-<script type="module" src="https://cdn.jsdelivr.net/npm/@wcstack/state@4.0.0-rc.8/dist/split/auto.js"></script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/@wcstack/state@4.0.0/dist/split/auto.js"></script>
 <wcs-state features="scopes diagnostics">
   <script type="module">
     export default {
@@ -739,7 +739,7 @@ export default {
 <wcs-fetch data-wcs="...: usersFetch; status: alternateStatus"></wcs-fetch>
 ```
 
-**`undefined` は「無意見」** — 展開された state パスが `undefined` に解決される場合（slot オブジェクトでその input を初期化していない場合など）、プロパティ書き込みは**スキップ**され、要素側の既定値がそのまま生きます。実際に使うパスだけ初期化すれば十分で、`<wcs-fetch>` が `method` / `manual` / `body` を宣言していても `usersFetch: { value: null, loading: false }` だけで動きます。明示的にクリアしたい場合は `null` を代入してください（`null` は常に書き込まれます）。（このスキップは spread に限らず、要素の input に値を渡すすべてのプロパティバインディングに適用されます。）**表示の表面は別です:** `textContent` / `innerText` / `innerHTML`・mustache やコメントバインディングのテキスト・`attr.*`・`style.*`・`class.*` には生かすべき要素側の既定値が無いので、`undefined` も `null` も「値が無い」— テキストは空になり、属性やスタイルは削除され、クラスは外れます。`class.*` だけは範囲が狭く、「値が無い」扱いになるのは `undefined` と `null` だけです — **それ以外の非 boolean は今も throw します**。クラスの束縛は真偽の切り替えなので、truthy な文字列は意図というより書き間違いである方がずっと多いためです。「truthy として扱う」つもりなら `class.on: flag|truthy` と書いてください。
+**`undefined` は「無意見」** — 展開された state パスが `undefined` に解決される場合（slot オブジェクトでその input を初期化していない場合など）、プロパティ書き込みは**スキップ**され、要素側の既定値がそのまま生きます。実際に使うパスだけ初期化すれば十分で、`<wcs-fetch>` が `method` / `manual` / `body` を宣言していても `usersFetch: { value: null, loading: false }` だけで動きます。明示的にクリアしたい場合は `null` を代入してください（`null` は常に書き込まれます）。（このスキップは spread に限らず、要素の input に値を渡すすべてのプロパティバインディングに適用されます。前にそのパスが値を持っていても同じで、要素には状態が最後に書いた値が残ります。これは wc-bindable の applier プロファイル（0.10.0 の A2）より厳しい規則で、A2 は値の後の `undefined` を書いて要素を初期状態に戻させます。状態はこのプロファイルを宣言しません。ほかの書き手 — React 19 や直接の代入 — は `undefined` を届けるので、wcstack の I/O ノードは `undefined` を「値が無い」として扱います。）**表示の表面は別です:** `textContent` / `innerText` / `innerHTML`・mustache やコメントバインディングのテキスト・`attr.*`・`style.*`・`class.*` には生かすべき要素側の既定値が無いので、`undefined` も `null` も「値が無い」— テキストは空になり、属性やスタイルは削除され、クラスは外れます。`class.*` だけは範囲が狭く、「値が無い」扱いになるのは `undefined` と `null` だけです — **それ以外の非 boolean は今も throw します**。クラスの束縛は真偽の切り替えなので、truthy な文字列は意図というより書き間違いである方がずっと多いためです。「truthy として扱う」つもりなら `class.on: flag|truthy` と書いてください。
 
 **フィルタを挟んでも契約は保たれます。** 空値の判定はフィルタ**後**の値に対して行われるため、`String(value)` で結果を組み立てるフィルタは、値が無いときに `"undefined"` という**文字**を作ってしまいかねません。書式の族（`upper` / `lower` / `capitalize` / `trim` / `slice` / `padStart` / `padEnd` / `repeat` / `reverse` / `truncate` / `unit`）は代わりに `undefined` / `null` を素通しするので、`attr.title: x|trim` はフィルタの無い `attr.title: x` と同じく属性を消します。次の 3 群は**意図的に素通ししません**: 空値そのものが入力として意味を持つフィルタ（`defaults` / `coalesce` / `nullIfEmpty` / `boolean` / `truthy` / `falsy` / `not` / `eq` / `ne`）、変換が仕事のフィルタ（`int` / `float` / `number` / `string` — `undefined|string` は今も `"undefined"`）、値の型を検査するフィルタ（数値・日付・配列の族。`toFixed` / `date` / `join` など）。最後の群は throw しますが、それは束縛 1 本に閉じ込められ `$errorCallback` に報告されます。値が無いことが正当にありうるなら前に `coalesce` を置いてください（`price|coalesce(0)|toFixed(2)`）。
 
@@ -1281,6 +1281,8 @@ export default {
 
 ネストループでは、`$1` が外側のインデックス、`$2` が内側のインデックスです。
 
+段はテンプレートの入れ子ではなくパスで決まります。行の中でトップレベルの一覧を回す `for:`（`for: groups` の中の `for: tags` で、どの行にも同じタグを並べる形）が描くのは、深さ 1 の一覧 `tags` の行です。そこでは `$1` がタグのインデックスで、`$2` は（エラーなしで）空になり、イベントハンドラにもタグのインデックスだけが渡ります。内側の行から外側の行が要るときは、行 getter で外側の行ごとに一覧を持たせ、それを回してください —— `get "groups.*.tagsHere"() { return this.tags; }` と `for: .tagsHere` にすると、`$1` がグループ、`$2` がタグになります。
+
 テンプレート内でループインデックスを直接表示することもできます：
 
 ```html
@@ -1408,7 +1410,7 @@ export default {
 };
 ```
 
-**同じオブジェクトが 2 つの位置にあるとき。** 1 つのリストの 2 つの位置に同じオブジェクトがあると（`items: [o, o, …]`）、片方の行の下のキーへの書き込み（`this["items.0.name"] = "z"`）でオブジェクトは変わりますが、もう片方の行のバインディングと行 getter は古い値を表示し続けます: 1 つのリストの中では、書き込みはそれを通した行にしか届かないためです。素の読み取り・ルートの getter・`$getAll` には新しい値が見えます。普通のキーの 2 つの配列が同じオブジェクトを持つ場合（`backup = items; items = items.filter(…)` で両方を描画する形）も同じです。こうした書き込みの後に `$postUpdate("items")` を呼ぶと、そのリストのすべての行がオブジェクトを表示し直します。これはこのバージョンの既知の制約です。getter が配列を結び付ける場合 —— TodoMVC 風の絞り込み（`todos` を絞り込んだコピーを返す `get shown()` を `for: shown` で描画する形）、並べ替え、切り出し —— は、どちら側から書いても、オブジェクトを持つすべての行と `todos.*` を読むものに届き、そのオブジェクトを配列に持つ getter は評価し直されます（チェックした行は未完了の絞り込みから抜け、名前を変えた行は並べ替えた表示で動きます）。書いたオブジェクトを配列に持たない getter は評価し直しません: 配列を読んだのであって、オブジェクトは読んでいないためです —— どの行にも追従させるには、その中で `$getAll("todos.*.done")` を読んでください。
+**同じオブジェクトが 2 つの位置にあるとき。** 1 つのリストの 2 つの位置に同じオブジェクトがあると（`items: [o, o, …]`）、片方の行の下のキーへの書き込み（`this["items.0.name"] = "z"`）でオブジェクトは変わりますが、もう片方の行のバインディングと行 getter は古い値を表示し続けます: 1 つのリストの中では、書き込みはそれを通した行にしか届かないためです。素の読み取り・ルートの getter・`$getAll` には新しい値が見えます。普通のキーの 2 つの配列が同じオブジェクトを持つ場合（`backup = items; items = items.filter(…)` で両方を描画する形）も同じです。こうした書き込みの後に `$postUpdate("items")` を呼ぶと、そのリストのすべての行がオブジェクトを表示し直します。外側の 2 つの行が、同じオブジェクトを持つ別々の配列を持つ場合（`groups: [{ items: a }, { items: [...a] }]`）も同じで、もう片方の一覧（`"groups.1.items"`）か外側の一覧（`"groups"`）の `$postUpdate` を呼んでください。これはこのバージョンの既知の制約です。getter が配列を結び付ける場合 —— TodoMVC 風の絞り込み（`todos` を絞り込んだコピーを返す `get shown()` を `for: shown` で描画する形）、並べ替え、切り出し —— は、どちら側から書いても、オブジェクトを持つすべての行と `todos.*` を読むものに届き、そのオブジェクトを配列に持つ getter は評価し直されます（チェックした行は未完了の絞り込みから抜け、名前を変えた行は並べ替えた表示で動きます）。書いたオブジェクトを配列に持たない getter は評価し直しません: 配列を読んだのであって、オブジェクトは読んでいないためです —— どの行にも追従させるには、その中で `$getAll("todos.*.done")` を読んでください。
 
 ## 再帰パス（`$recursion`）
 
@@ -2604,7 +2606,7 @@ $renderedCallback(paths) {
 
 `wcBindable.inputs` は、状態が書いてよいメンバー（state → 要素）を宣言します。方向認識初期同期（既定 ON）の下では、メンバが **state から settable であること**を示すのが `inputs` です。settable なのに `properties` にしか宣言されていないメンバは output-only 扱いになり、state からの書き込みが抑止されます — [バインディング authority](#バインディング-authority-init--sync) を参照してください。
 
-状態が書くのは入力の**プロパティ**だけです。エントリの省略できる `attribute` は、マークアップでそのプロパティに対応する HTML 属性の名前（`<my-chip label-text="…">`）です。wc-bindable プロトコルの定めるとおりツールのための宣言で、状態はこの属性を書きません。プロパティを属性に反映する（`attributeChangedCallback`・CSS の属性セレクタ・DevTools のため）のは要素の仕事で、setter の中で、要素だけが知っている書き方で行います（boolean は属性の有無、`"on"` / `"off"`、JSON など）:
+状態が書くのは入力の**プロパティ**だけです。エントリの省略できる `attribute` は、マークアップでそのプロパティに対応する HTML 属性の名前（`<my-chip label-text="…">`）です。wc-bindable プロトコルの定めるとおりツールのための宣言で、状態はこの属性を書きません（wc-bindable 0.10.0 の applier プロファイル A1: applier はプロパティを書き、ヒントの属性は書かない。要素が upgrade される前に属性へ逃げることもしない — 状態は定義を待ちます）。プロパティを属性に反映する（`attributeChangedCallback`・CSS の属性セレクタ・DevTools のため）のは要素の仕事で、setter の中で、要素だけが知っている書き方で行います（boolean は属性の有無、`"on"` / `"off"`、JSON など）:
 
 ```javascript
 class MyChip extends HTMLElement {

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.8/dist/split/core.js",
-    "@wcstack/state/features/temporal": "https://cdn.jsdelivr.net/npm/@wcstack/state@4.0.0-rc.8/dist/split/features/temporal.js",
-    "@wcstack/state/features/scopes": "https://cdn.jsdelivr.net/npm/@wcstack/state@4.0.0-rc.8/dist/split/features/scopes.js"
+    "@wcstack/state/core": "https://cdn.jsdelivr.net/npm/@wcstack/state@4.0.0/dist/split/core.js",
+    "@wcstack/state/features/temporal": "https://cdn.jsdelivr.net/npm/@wcstack/state@4.0.0/dist/split/features/temporal.js",
+    "@wcstack/state/features/scopes": "https://cdn.jsdelivr.net/npm/@wcstack/state@4.0.0/dist/split/features/scopes.js"
   }
 }
 </script>
@@ -254,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.8/dist/split/auto.js"></script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/@wcstack/state@4.0.0/dist/split/auto.js"></script>
 <wcs-state features="scopes diagnostics">
   <script type="module">
     export default {
@@ -745,7 +745,7 @@ Runtime reads `customClass.wcBindable.properties + inputs` and expands each name
 <wcs-fetch data-wcs="...: usersFetch; status: alternateStatus"></wcs-fetch>
 ```
 
-**`undefined` is "no opinion"** — when an expanded state path resolves to `undefined` (e.g. the slot object doesn't initialize that input), the property write is **skipped** and the element keeps its own default. You only need to initialize the paths you actually use; `usersFetch: { value: null, loading: false }` is enough even though `<wcs-fetch>` also declares `method` / `manual` / `body`. To explicitly clear a value, assign `null` — `null` is always written. (This skip applies to every property binding that feeds an element input, not just spread.) **Display surfaces are different:** `textContent` / `innerText` / `innerHTML`, mustache and comment-binding text, `attr.*`, `style.*` and `class.*` have no element default worth keeping, so `undefined` and `null` both mean "no value" there — the text becomes empty, the attribute or style is removed, and the class is taken off. `class.*` is the narrow case: only `undefined` and `null` mean "no value"; **any other non-boolean still throws**, because a class binding is a boolean toggle and a truthy string is far more likely a mistake than an intent. Write `class.on: flag|truthy` when you mean "treat it as truthy".
+**`undefined` is "no opinion"** — when an expanded state path resolves to `undefined` (e.g. the slot object doesn't initialize that input), the property write is **skipped** and the element keeps its own default. You only need to initialize the paths you actually use; `usersFetch: { value: null, loading: false }` is enough even though `<wcs-fetch>` also declares `method` / `manual` / `body`. To explicitly clear a value, assign `null` — `null` is always written. (This skip applies to every property binding that feeds an element input, not just spread, and also when the path held a value before: the element keeps the last value state wrote. That is stricter than the wc-bindable applier profile (0.10.0, A2), which writes `undefined` after a value so the element returns to its initial state; state does not claim that profile. Other writers — React 19, a direct assignment — do deliver `undefined`, and the wcstack I/O nodes treat it as "no value supplied".) **Display surfaces are different:** `textContent` / `innerText` / `innerHTML`, mustache and comment-binding text, `attr.*`, `style.*` and `class.*` have no element default worth keeping, so `undefined` and `null` both mean "no value" there — the text becomes empty, the attribute or style is removed, and the class is taken off. `class.*` is the narrow case: only `undefined` and `null` mean "no value"; **any other non-boolean still throws**, because a class binding is a boolean toggle and a truthy string is far more likely a mistake than an intent. Write `class.on: flag|truthy` when you mean "treat it as truthy".
 
 **Filters keep the contract.** The emptiness test runs on the value *after* the filters, so a filter that built its result with `String(value)` would turn an absent value back into the characters `"undefined"`. The formatting family (`upper`, `lower`, `capitalize`, `trim`, `slice`, `padStart`, `padEnd`, `repeat`, `reverse`, `truncate`, `unit`) passes `undefined` / `null` straight through instead, so `attr.title: x|trim` removes the attribute just as `attr.title: x` does. Three groups deliberately do **not**: the filters for which an absent value *is* the input (`defaults`, `coalesce`, `nullIfEmpty`, `boolean`, `truthy`, `falsy`, `not`, `eq`, `ne`), the conversions whose whole job is to convert (`int`, `float`, `number`, `string` — `undefined|string` is still `"undefined"`), and the filters that check the value's type (the number, date and array families, e.g. `toFixed` / `date` / `join`). Those last ones throw, which is confined to the one binding and reported through `$errorCallback` — put a `coalesce` in front when the value can legitimately be absent (`price|coalesce(0)|toFixed(2)`).
 
@@ -1287,6 +1287,8 @@ export default {
 
 For nested loops, `$1` is the outer index and `$2` is the inner index.
 
+The levels follow the paths, not the template nesting. A `for:` inside a row that loops over a top-level list (`for: tags` inside `for: groups`, each row showing the same tags) renders rows of `tags`, a list of depth 1: there `$1` is the tag's index, `$2` is empty (no error), and event handlers receive the tag's index only. When the inner rows need the outer row, give each outer row the list through a row getter and loop over that — `get "groups.*.tagsHere"() { return this.tags; }` with `for: .tagsHere` — so that `$1` is the group and `$2` the tag.
+
 You can also display the loop index directly in templates:
 
 ```html
@@ -1414,7 +1416,7 @@ export default {
 };
 ```
 
-**One object at two positions.** When the same object sits at two positions of one list (`items: [o, o, …]`), a write to a key below one of those rows (`this["items.0.name"] = "z"`) changes the object, but the other row's bindings and row getters keep showing the old value: within one list, a write reaches only the row it was made through. Plain reads, root getters and `$getAll` see the new value. The same holds for two arrays at plain keys that share an object (`backup = items; items = items.filter(…)`, both rendered). Call `$postUpdate("items")` after such a write, and every row of that list shows the object again. This is a known limitation of this version. When a getter relates the arrays — a TodoMVC-style filter (`get shown()` returning a filtered copy of `todos`, rendered with `for: shown`), a sort, a slice — a write from either side reaches every row holding the object and the `todos.*` readers, and the getters whose array holds it are evaluated again (a checked row leaves an "active" filter, a renamed row moves in a sorted view). A getter whose array does not hold the written object is not evaluated again: it read the array, not the object — read `$getAll("todos.*.done")` in it to follow every row.
+**One object at two positions.** When the same object sits at two positions of one list (`items: [o, o, …]`), a write to a key below one of those rows (`this["items.0.name"] = "z"`) changes the object, but the other row's bindings and row getters keep showing the old value: within one list, a write reaches only the row it was made through. Plain reads, root getters and `$getAll` see the new value. The same holds for two arrays at plain keys that share an object (`backup = items; items = items.filter(…)`, both rendered). Call `$postUpdate("items")` after such a write, and every row of that list shows the object again. So do two outer rows holding different arrays that share an object (`groups: [{ items: a }, { items: [...a] }]`): call `$postUpdate` on the other list (`"groups.1.items"`) or on the outer one (`"groups"`). This is a known limitation of this version. When a getter relates the arrays — a TodoMVC-style filter (`get shown()` returning a filtered copy of `todos`, rendered with `for: shown`), a sort, a slice — a write from either side reaches every row holding the object and the `todos.*` readers, and the getters whose array holds it are evaluated again (a checked row leaves an "active" filter, a renamed row moves in a sorted view). A getter whose array does not hold the written object is not evaluated again: it read the array, not the object — read `$getAll("todos.*.done")` in it to follow every row.
 
 ## Recursive Paths (`$recursion`)
 
@@ -2614,7 +2616,7 @@ Key rules:
 
 `wcBindable.inputs` declares the members state may set (state → element). Under directional initial sync (default on), it is what marks a member as **settable from state**: a member declared only in `properties` becomes output-only and state writes to it are suppressed — see [Binding Authority](#binding-authority-init--sync).
 
-State writes an input's **property**, and only the property. An entry's optional `attribute` names the HTML attribute that corresponds to the property in markup (`<my-chip label-text="…">`); it is a declaration for tooling, as the wc-bindable protocol defines it, and state does not write it. Reflecting a property to its attribute — for `attributeChangedCallback`, CSS attribute selectors or DevTools — is the element's job, in its setter, with the encoding only the element knows (a boolean as a present / absent attribute, `"on"` / `"off"`, JSON …):
+State writes an input's **property**, and only the property. An entry's optional `attribute` names the HTML attribute that corresponds to the property in markup (`<my-chip label-text="…">`); it is a declaration for tooling, as the wc-bindable protocol defines it, and state does not write it (wc-bindable 0.10.0's applier profile, A1: an applier writes the property, never the hinted attribute, and does not fall back to it before the element is upgraded — state waits for the definition). Reflecting a property to its attribute — for `attributeChangedCallback`, CSS attribute selectors or DevTools — is the element's job, in its setter, with the encoding only the element knows (a boolean as a present / absent attribute, `"on"` / `"off"`, JSON …):
 
 ```javascript
 class MyChip extends HTMLElement {