@wcstack/state 3.1.0 → 3.2.0

package/README.ja.md

@@ -186,9 +186,9 @@
 <script type="importmap">
 {
   "imports": {
-    "@wcstack/state/core": "https://cdn.jsdelivr.net/npm/@wcstack/state@3.1.0/dist/split/core.js",
-    "@wcstack/state/features/temporal": "https://cdn.jsdelivr.net/npm/@wcstack/state@3.1.0/dist/split/features/temporal.js",
-    "@wcstack/state/features/scopes": "https://cdn.jsdelivr.net/npm/@wcstack/state@3.1.0/dist/split/features/scopes.js"
+    "@wcstack/state/core": "https://cdn.jsdelivr.net/npm/@wcstack/state@3.2.0/dist/split/core.js",
+    "@wcstack/state/features/temporal": "https://cdn.jsdelivr.net/npm/@wcstack/state@3.2.0/dist/split/features/temporal.js",
+    "@wcstack/state/features/scopes": "https://cdn.jsdelivr.net/npm/@wcstack/state@3.2.0/dist/split/features/scopes.js"
   }
 }
 </script>
@@ -1165,8 +1165,8 @@ export default {
 | `this.$setAll(path, indexes, value, options?)` | ワイルドカードパスにマッチする全アドレスへ一括書き込み |
 | `this.$resolve(path, indexes, value?)` | ワイルドカードパスを特定のインデックスで解決 |
 | `this.$postUpdate(path)` | 指定パスの更新通知を手動で発行 |
-| `this.$trackDependency(path)` | キャッシュ無効化のための依存関係を手動で登録 |
-| `this.$untrackDependency(fn)` | fn 実行中の依存追跡を抑止して値を読む（`$trackDependency` と対称） |
+| `this.$dependOn(path)`（3.2。旧名 `$trackDependency`） | キャッシュ無効化のための依存関係を手動で登録 |
+| `this.$untracked(fn)`（3.2。旧名 `$untrackDependency`） | fn 実行中の依存追跡を抑止して値を読む |
 | `this.$eq(path, key)` / `$eqPath(path, keyPath)` / `$eqIndex(path, level?)` | 鍵付き購読: 「`path` の値はこの行の鍵か」（[鍵付き選択](#鍵付き選択eq--eqpath--eqindex)） |
 | `this.$stateElement` | `IStateElement` インスタンスへのアクセス |
 | `this.$1`, `this.$2`, ... | 現在のループインデックス（1始まりの命名、0始まりの値） |
@@ -1499,7 +1499,9 @@ export default {
 
 ## フィルタ
 
-46 種類の組み込みフィルタが入力（DOM → 状態）と出力（状態 → DOM）の両方向で利用できます。
+48 種類の組み込みフィルタが入力（DOM → 状態）と出力（状態 → DOM）の両方向で利用できます。
+
+**3.2 で一部の名前を改めました**（要件 B12）。表は正式名で、括弧の中が旧名です。旧名は 3.x の間は同じに動き、4.0 で外れます。lint と VS Code 拡張は、旧名に正式名を提案する info（`wcs/name-alias`）を出します。3.1 以前を使うページでは旧名で書いてください。
 
 ### 比較
 
@@ -1517,8 +1519,8 @@ export default {
 
 | フィルタ | 説明 | 例 |
 |---|---|---|
-| `inc(n)` | 加算 | `count\|inc(1)` |
-| `dec(n)` | 減算 | `count\|dec(1)` |
+| `add(n)`（`inc`） | 加算 | `count\|add(1)` |
+| `sub(n)`（`dec`） | 減算 | `count\|sub(1)` |
 | `mul(n)` | 乗算 | `price\|mul(1.1)` |
 | `div(n)` | 除算 | `total\|div(100)` |
 | `mod(n)` | 剰余 | `index\|mod(2)` |
@@ -1529,7 +1531,7 @@ export default {
 
 | フィルタ | 説明 | 例 |
 |---|---|---|
-| `fix(n)` | 固定小数点桁数 | `price\|fix(2)` → `"100.00"` |
+| `toFixed(n)`（`fix`） | 固定小数点桁数 | `price\|toFixed(2)` → `"100.00"` |
 | `round(n?)` | 四捨五入 | `value\|round(2)` |
 | `floor(n?)` | 切り捨て | `value\|floor` |
 | `ceil(n?)` | 切り上げ | `value\|ceil` |
@@ -1541,15 +1543,16 @@ export default {
 
 | フィルタ | 説明 | 例 |
 |---|---|---|
-| `uc` | 大文字変換 | `name\|uc` |
-| `lc` | 小文字変換 | `name\|lc` |
-| `cap` | 先頭大文字 | `name\|cap` |
+| `upper`（`uc`） | 大文字変換 | `name\|upper` |
+| `lower`（`lc`） | 小文字変換 | `name\|lower` |
+| `capitalize`（`cap`） | 先頭大文字 | `name\|capitalize` |
 | `trim` | 空白除去 | `text\|trim` |
 | `slice(n)` | 文字列スライス | `text\|slice(5)` |
 | `substr(start, length)` | 部分文字列 | `text\|substr(0,10)` |
-| `pad(n, char?)` | 先頭パディング | `id\|pad(5,0)` → `"00001"` |
-| `rep(n)` | 繰り返し | `text\|rep(3)` |
-| `rev` | 反転 | `text\|rev` |
+| `padStart(n, char?)`（`pad`） | 先頭を埋める（既定 `0`） | `id\|padStart(5,0)` → `"00001"` |
+| `padEnd(n, char?)` | 末尾を埋める（既定は空白。3.2） | `code\|padEnd(8)` |
+| `repeat(n)`（`rep`） | 繰り返し | `text\|repeat(3)` |
+| `reverse`（`rev`） | 反転 | `text\|reverse` |
 | `truncate(n, suffix?)` | 切り詰めて省略記号を付加 | `title\|truncate(20)` → `"…"` 付き |
 | `join(sep?)` | 配列を連結（既定 `", "`） | `tags\|join` / `tags\|join(/)` |
 
@@ -1562,7 +1565,7 @@ export default {
 | `boolean` | 真偽値に変換 | `value\|boolean` |
 | `number` | 数値に変換 | `value\|number` |
 | `string` | 文字列に変換 | `value\|string` |
-| `null` | null に変換 | `value\|null` |
+| `nullIfEmpty`（`null`） | 空文字を `null` にする（それ以外はそのまま） | `value\|nullIfEmpty` |
 
 ### 日付 / 時刻
 
@@ -1580,7 +1583,8 @@ export default {
 |---|---|---|
 | `truthy` | truthy チェック — JavaScript の真偽判定そのもので `boolean` と同じ（3.0 から `0n` は偽） | `value\|truthy` |
 | `falsy` | falsy チェック（JavaScript の真偽判定。`defaults` も同じ判定を使う） | `value\|falsy` |
-| `defaults(v)` | フォールバック値 | `name\|defaults(Anonymous)` |
+| `defaults(v)` | 偽値（`0`・`false`・`""` を含む）のときのフォールバック値 | `name\|defaults(Anonymous)` |
+| `coalesce(v)` | `null` / `undefined` のときだけのフォールバック値（`0`・`false`・`""` は残す。3.2） | `count\|coalesce(0)` |
 
 ### フィルタチェーン
 
@@ -2149,6 +2153,8 @@ event token は command token と同じ `Token` pub/sub プリミティブを共
 
 ## Stream（`$streams`）
 
+> **3.2 から宣言キーの正式名は `$stream` です**（要件 B12 — `$watch` / `$scan` と単数で揃えた）。旧名 `$streams` は 3.x の間は同じに動き、4.0 で外れます。両方を宣言すると `[wcs/declaration-alias]` で落ちます。`$streamStatus` / `$streamError` の名前空間は変わりません。3.1 以前では `$streams` と書いてください。
+
 command token / event token が運ぶのは離散的なやり取りです。**`$streams`** は残る形 —— 連続的なフローをカバーします。非同期 producer（async iterable / async generator / `ReadableStream`）を宣言すると、フレームワークがそれを **fold して単一の reactive プロパティに畳み込みます** —— 各チャンクは通常のパス代入を通るため、バインディング・パス getter・`$updatedCallback` は自分で値を代入した場合とまったく同じように反応します。`args` 関数が読んだ state パスが変化すると、実行中の producer は abort され、新しい引数で source が張り直されます（switchMap 型の依存駆動 restart）。stream は `$connectedCallback` 完了後に eager に起動し、要素の disconnect で abort されます。
 
 `$updatedCallback` は引き続き binding 駆動です。stream 宣言だけでは headless な購読にならず、その value/status/error の live DOM binding が実際に適用されたときだけ callback の path に現れます。描画せずに stream の値へ反応したい場合は、そのパスに [`$watch`](#watchwatch) を宣言してください。観測契約は [stream リファレンス](docs/streams.md) を参照してください。
@@ -2618,6 +2624,8 @@ export default {
 
 状態オブジェクトに `$connectedCallback` / `$disconnectedCallback` / `$updatedCallback` / `$errorCallback` を定義すると、初期化・クリーンアップ・更新時・バインディング失敗時のフックとして利用できます。
 
+> **3.2 から `$updatedCallback` の正式名は `$renderedCallback` です**（要件 B12）。このフックが受けるのは**適用されたバインディング**の更新で、state の更新全体ではない（それには `$watch`）ことを名前で言うためです。旧名は 3.x の間は同じに動き、4.0 で外れます。両方を宣言すると `[wcs/declaration-alias]` で落ちます。3.1 以前では `$updatedCallback` と書いてください。
+
 ```html
 <wcs-state>
   <script type="module">

package/README.md

@@ -187,9 +187,9 @@ leaves features out, it can compose them instead:
 <script type="importmap">
 {
   "imports": {
-    "@wcstack/state/core": "https://cdn.jsdelivr.net/npm/@wcstack/state@3.1.0/dist/split/core.js",
-    "@wcstack/state/features/temporal": "https://cdn.jsdelivr.net/npm/@wcstack/state@3.1.0/dist/split/features/temporal.js",
-    "@wcstack/state/features/scopes": "https://cdn.jsdelivr.net/npm/@wcstack/state@3.1.0/dist/split/features/scopes.js"
+    "@wcstack/state/core": "https://cdn.jsdelivr.net/npm/@wcstack/state@3.2.0/dist/split/core.js",
+    "@wcstack/state/features/temporal": "https://cdn.jsdelivr.net/npm/@wcstack/state@3.2.0/dist/split/features/temporal.js",
+    "@wcstack/state/features/scopes": "https://cdn.jsdelivr.net/npm/@wcstack/state@3.2.0/dist/split/features/scopes.js"
   }
 }
 </script>
@@ -1166,8 +1166,8 @@ Inside state objects (getters / methods), the following APIs are available via `
 | `this.$setAll(path, indexes, value, options?)` | Write to every address matching a wildcard path |
 | `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.$untrackDependency(fn)` | Read values inside fn without registering dependencies (symmetric to `$trackDependency`) |
+| `this.$dependOn(path)` (3.2; old name `$trackDependency`) | Manually register a dependency for cache invalidation |
+| `this.$untracked(fn)` (3.2; old name `$untrackDependency`) | Read values inside fn without registering dependencies |
 | `this.$eq(path, key)` / `$eqPath(path, keyPath)` / `$eqIndex(path, level?)` | Keyed subscription for "is this row's key the value of `path`?" (see [Keyed selection](#keyed-selection-eq--eqpath--eqindex)) |
 | `this.$command.<name>` | Access a `CommandToken` declared in `$commandTokens` (see [Command Token](#command-token-method-binding)) |
 | `this.$stateElement` | Access to the `IStateElement` instance |
@@ -1501,7 +1501,9 @@ export default {
 
 ## Filters
 
-46 built-in filters are available for both input (DOM → state) and output (state → DOM) directions.
+48 built-in filters are available for both input (DOM → state) and output (state → DOM) directions.
+
+**3.2 renamed some filters** (requirement B12). The tables show the canonical names, with the old name in parentheses. The old names work the same through 3.x and are removed in 4.0. Lint and the VS Code extension flag an old name with an info diagnostic (`wcs/name-alias`) that suggests the canonical one. On a page that uses 3.1 or earlier, write the old names.
 
 ### Comparison
 
@@ -1519,8 +1521,8 @@ export default {
 
 | Filter | Description | Example |
 |---|---|---|
-| `inc(n)` | Add | `count\|inc(1)` |
-| `dec(n)` | Subtract | `count\|dec(1)` |
+| `add(n)` (`inc`) | Add | `count\|add(1)` |
+| `sub(n)` (`dec`) | Subtract | `count\|sub(1)` |
 | `mul(n)` | Multiply | `price\|mul(1.1)` |
 | `div(n)` | Divide | `total\|div(100)` |
 | `mod(n)` | Modulo | `index\|mod(2)` |
@@ -1531,7 +1533,7 @@ export default {
 
 | Filter | Description | Example |
 |---|---|---|
-| `fix(n)` | Fixed decimal places | `price\|fix(2)` → `"100.00"` |
+| `toFixed(n)` (`fix`) | Fixed decimal places | `price\|toFixed(2)` → `"100.00"` |
 | `round(n?)` | Round | `value\|round(2)` |
 | `floor(n?)` | Floor | `value\|floor` |
 | `ceil(n?)` | Ceiling | `value\|ceil` |
@@ -1543,15 +1545,16 @@ export default {
 
 | Filter | Description | Example |
 |---|---|---|
-| `uc` | Upper case | `name\|uc` |
-| `lc` | Lower case | `name\|lc` |
-| `cap` | Capitalize | `name\|cap` |
+| `upper` (`uc`) | Upper case | `name\|upper` |
+| `lower` (`lc`) | Lower case | `name\|lower` |
+| `capitalize` (`cap`) | Capitalize | `name\|capitalize` |
 | `trim` | Trim whitespace | `text\|trim` |
 | `slice(n)` | Slice string | `text\|slice(5)` |
 | `substr(start, length)` | Substring | `text\|substr(0,10)` |
-| `pad(n, char?)` | Pad start | `id\|pad(5,0)` → `"00001"` |
-| `rep(n)` | Repeat | `text\|rep(3)` |
-| `rev` | Reverse | `text\|rev` |
+| `padStart(n, char?)` (`pad`) | Pad the start (default `0`) | `id\|padStart(5,0)` → `"00001"` |
+| `padEnd(n, char?)` | Pad the end (default a space; 3.2) | `code\|padEnd(8)` |
+| `repeat(n)` (`rep`) | Repeat | `text\|repeat(3)` |
+| `reverse` (`rev`) | Reverse | `text\|reverse` |
 | `truncate(n, suffix?)` | Shorten and append an ellipsis | `title\|truncate(20)` |
 | `join(sep?)` | Join an array (default `", "`) | `tags\|join` / `tags\|join(/)` |
 
@@ -1564,7 +1567,7 @@ export default {
 | `boolean` | To boolean | `value\|boolean` |
 | `number` | To number | `value\|number` |
 | `string` | To string | `value\|string` |
-| `null` | To null | `value\|null` |
+| `nullIfEmpty` (`null`) | Turn an empty string into `null` (anything else passes through) | `value\|nullIfEmpty` |
 
 ### Date / Time
 
@@ -1582,7 +1585,8 @@ export default {
 |---|---|---|
 | `truthy` | Truthy check — JavaScript's own truthiness, the same as `boolean` (so `0n` is falsy since 3.0) | `value\|truthy` |
 | `falsy` | Falsy check (JavaScript's truthiness; `defaults` uses the same test) | `value\|falsy` |
-| `defaults(v)` | Fallback value | `name\|defaults(Anonymous)` |
+| `defaults(v)` | Fallback for any falsy value (`0`, `false` and `""` included) | `name\|defaults(Anonymous)` |
+| `coalesce(v)` | Fallback for `null` / `undefined` only (`0`, `false` and `""` stay; 3.2) | `count\|coalesce(0)` |
 
 ### Filter Chaining
 
@@ -2155,6 +2159,8 @@ Two rules cut most of the confusion:
 
 ## Streams (`$streams`)
 
+> **As of 3.2 the canonical declaration key is `$stream`** (requirement B12), singular like `$watch` and `$scan`. The old `$streams` works the same through 3.x and is removed in 4.0. Declaring both fails with `[wcs/declaration-alias]`. The `$streamStatus` / `$streamError` namespaces do not change. On 3.1 or earlier, write `$streams`.
+
 Command tokens and event tokens carry discrete interactions. **`$streams`** covers the remaining shape: a continuous flow. Declare an async producer (async iterable / async generator / `ReadableStream`) and the framework **folds it into a single reactive property** — each chunk goes through normal path assignment, so bindings, path getters, and `$updatedCallback` react exactly as if you had assigned the value yourself. When a state path read by the `args` function changes, the running producer is aborted and the source is restarted with the new arguments (switchMap-style dependency-driven restart). Streams start eagerly after `$connectedCallback` completes and are aborted when the element disconnects.
 
 `$updatedCallback` remains binding-driven: a stream declaration alone is not a headless subscription. Its path appears in the callback only when a live DOM binding for that value/status/error is actually applied. To react to a stream's value without rendering it, declare [`$watch`](#watch-watch) on that path; see the [stream reference](docs/streams.md) for the observation contract.
@@ -2624,6 +2630,8 @@ All bindings work inside `<svg>` elements. Use `attr.*` for SVG attributes:
 
 State objects can define `$connectedCallback`, `$disconnectedCallback`, `$updatedCallback`, and `$errorCallback` for initialization, cleanup, update, and binding-failure handling.
 
+> **As of 3.2 the canonical name of `$updatedCallback` is `$renderedCallback`** (requirement B12). The hook receives updates of **applied bindings**, not every state update (use `$watch` for those), and the new name says so. The old name works the same through 3.x and is removed in 4.0. Declaring both fails with `[wcs/declaration-alias]`. On 3.1 or earlier, write `$updatedCallback`.
+
 ```html
 <wcs-state>
   <script type="module">