@wcstack/state 2.6.0 → 2.6.1

package/README.ja.md

@@ -369,6 +369,8 @@ property[#modifier]: path[|filter[|filter(args)...]]
 | `checkbox` | チェックボックスグループの配列バインディング（双方向） |
 | `onclick`, `on*` | イベントハンドラバインディング |
 
+`undefined` は書き込みをスキップします。要素は表示していたものを保ち、再利用されたリスト行では**前の行の**テキストが残ります。「値なし」は `""` か `null` を返してください（3.0 は表示のプロパティへの `undefined` を空にします — [3.0 への準備](#30-への準備wcsv3-migration)）。
+
 ### 修飾子
 
 | 修飾子 | 説明 |
@@ -1021,6 +1023,13 @@ export default {
 
 規則: 3 つの呼び出しが購読を張るのはリスト行の getter の中で評価されたときだけで、それ以外では比較結果を返すだけです。行の購読はリスト差分がその行を外した時点で落ちます。鍵の比較は `Object.is` ですが、Map の意味論により `+0` と `-0`、`NaN` 同士は同じ鍵になります。`$eqPath` は鍵を依存なしで読むので、行の鍵がその場で書き換わっても行は再評価されません — 変わらない同一性（id）に使い、鍵自体が動く場合は追跡付きの読みと `$eq` を組み合わせてください。
 
+行に届くもの:
+
+- **`path` への書き込み** — オブジェクトを含むどんな値でも（`$eq("selected", this["items.*"])` に対する `this.selected = row`）: 選ばれていた行と、新たに選ばれる行。
+- **`path` より上のオブジェクトへの書き込み** — `$eq("sel.id", …)` に対する `this.sel = { id: 2 }`: 同じく 2 行。旧いオブジェクトの下と新しいオブジェクトの下で `path` が持つ値を鍵にします。
+- **`path` が getter か getter の配下**（`get current()` に対する `$eq("current.id", …)`）: 値が書き込みなしに変わるので、依存を張る普通の読み取りに戻ります。選択は正しく保たれますが、変化のたびに全行が再評価されます（鍵付きの形を使わないのと同じ）。2 行で済ませるには、`path` を書き込まれる state（`selectedId`）に向けてください。
+- **型変換はしません:** `"2"` は id `2` に一致しません。`<input>` や `<select>` は文字列を書くので、入口で変換する（`value|number: selectedId`）か、id を文字列で持ってください。
+
 ### ループインデックス変数（`$1`, `$2`, ...）
 
 getter やイベントハンドラ内で、`this.$1`、`this.$2` などで現在のループイテレーションのインデックスを取得できます（0始まりの値、1始まりの命名）：
@@ -1413,6 +1422,8 @@ export default {
 | `gt(n)` | より大きい | `count\|gt(0)` |
 | `ge(n)` | 以上 | `count\|ge(0)` |
 
+`eq` / `ne` は数値の値を数値として、それ以外を引数の**文字列**と比べます。そのため 2.x では真偽値が `eq(true)` に一致することはなく、`done|eq(true)` は常に `false` です。真偽値そのものをバインドする（`class.done: .done`）か `not` を使ってください。3.0 は引用符の無い `true` / `false` / `null` を型付きの値として読みます（[3.0 への準備](#30-への準備wcsv3-migration)）。
+
 ### 算術
 
 | フィルタ | 説明 | 例 |

package/README.md

@@ -369,6 +369,8 @@ Multiple bindings separated by `;`:
 | `checkbox` | Checkbox group binding to array (two-way) |
 | `onclick`, `on*` | Event handler binding |
 
+`undefined` skips the write: the element keeps what it showed, and in a reused list row that is the **previous row's** text. Return `""` or `null` for "no value" (3.0 empties display properties on `undefined` — [Preparing for 3.0](#preparing-for-30-wcsv3-migration)).
+
 ### Modifiers
 
 | Modifier | Description |
@@ -1021,6 +1023,13 @@ export default {
 
 Rules: the three calls only subscribe when evaluated inside a getter under a list row (elsewhere they just return the comparison); a row's subscription is dropped when the list diff removes the row; keys compare with `Object.is` except that Map semantics treat `+0`/`-0` and `NaN`/`NaN` as equal. `$eqPath` reads the key without a dependency, so a row whose key changes in place is not re-evaluated by that change — use it for identities that do not change (ids), and `$eq` with a tracked read when the key itself is live.
 
+What reaches the rows:
+
+- **A write to `path`** — of any value, objects included (`this.selected = row` with `$eq("selected", this["items.*"])`): the row that was selected and the row that becomes selected.
+- **A write to an object above `path`** — `this.sel = { id: 2 }` for `$eq("sel.id", …)`: the same two rows, keyed by the value `path` had under the old object and has under the new one.
+- **A `path` that is a getter, or sits under one** (`$eq("current.id", …)` with `get current()`): its value changes without a write to it, so the calls fall back to an ordinary tracked read. The selection stays correct, but a change re-evaluates every row, as without the keyed form. Point `path` at the written state (`selectedId`) to keep the two-row cost.
+- **No type conversion:** `"2"` does not match the id `2`. An `<input>` or `<select>` writes strings, so convert on the way in (`value|number: selectedId`) or keep the ids as strings.
+
 ### Loop Index Variables (`$1`, `$2`, ...)
 
 Inside getters and event handlers, `this.$1`, `this.$2`, etc. provide the current loop iteration index (0-based value, 1-based naming):
@@ -1414,6 +1423,8 @@ export default {
 | `gt(n)` | Greater than | `count\|gt(0)` |
 | `ge(n)` | Greater than or equal | `count\|ge(0)` |
 
+`eq` / `ne` compare a number value numerically and anything else with the argument **as text**, so a boolean never equals `eq(true)` in 2.x: `done|eq(true)` is always `false`. Bind the boolean itself (`class.done: .done`) or use `not`. 3.0 reads an unquoted `true` / `false` / `null` as the typed value ([Preparing for 3.0](#preparing-for-30-wcsv3-migration)).
+
 ### Arithmetic
 
 | Filter | Description | Example |