@wcstack/state 1.30.0 → 1.32.0

package/dist/index.d.ts

@@ -42,6 +42,35 @@ interface ILoopContextStack {
     createLoopContext(elementStateAddress: IStateAddress, callback: (loopContext: ILoopContext) => void | Promise<void>): void | Promise<void>;
 }
 
+/**
+ * pathDiagnostics.ts — バインド / `$watch` 対象パスの存在検査（silent failure の可視化）。
+ *
+ * なぜ必要か:
+ * `getByAddress` は「親が null / undefined のパスの読み」を undefined で返し、
+ * undefined はプロパティ書き込みがスキップされる値なので、`user.nmae` のような
+ * 打ち間違いは**エラーも警告も出さずに DOM が更新されない**だけになる。一方で
+ * トップレベルの打ち間違い（`cout`）は parentAddress を辿れず raiseError で落ちる。
+ * 同じ「パスを打ち間違えた」という 1 つの失敗が、パスの深さで silent / loud に
+ * 割れており、書き手からは区別がつかない。ここはその silent 側を埋める。
+ *
+ * 精度方針（過小近似）:
+ * 「確実に存在しない」と言い切れる場合にだけ報告する。getter の戻り値の先・
+ * 空配列・null 親・mapped な `bind-component` など、静的に決められない形はすべて
+ * `"unknown"` に倒して黙る（偽陽性ゼロ優先。docs/static-wiring-dx-design.md D7 /
+ * [ADR-06](../../docs/architecture-hardening/06-path-type-safety.md) の精度哲学）。
+ *
+ * 診断 code はコンソール → lint → IDE の三面で共有する（errorGuidance.ts の規約）。
+ */
+
+/** `setPathInfo` の呼び出し元の種別。診断 code と適用範囲がこれで変わる */
+type PathInfoSource = 
+/** data-wcs / mustache / コメントバインディング */
+"binding"
+/** `$watch` の宣言キー */
+ | "watch"
+/** ランタイム内部のパス翻訳（mapped な bind-component の外向き伝播）。検査しない */
+ | "internal";
+
 declare const setLoopContextSymbol: unique symbol;
 declare const getByAddressSymbol: unique symbol;
 declare const hasByAddressSymbol: unique symbol;
@@ -151,8 +180,11 @@ interface IStateElement {
      * パスを依存グラフへ登録する。DOM バインディング登録（BindingSession）のほか、
      * `$watch` 宣言（processWatchDeclaration）からも呼ばれる — 静的依存グラフに
      * 載るのがバインド済みパスだけだと headless 購読が成立しないため（設計書 §8）。
+     *
+     * `source` は存在検査の診断 code と適用範囲を決める（pathDiagnostics.ts）。
+     * 省略時は `"binding"`（テスト用モック互換のため optional）。
      */
-    setPathInfo(path: string, bindingType: BindingType): void;
+    setPathInfo(path: string, bindingType: BindingType, source?: PathInfoSource): void;
     addStaticDependency(parentPath: string, childPath: string): boolean;
     addDynamicDependency(fromPath: string, toPath: string): boolean;
     createStateAsync(mutability: Mutability, callback: (state: IStateProxy) => Promise<void>): Promise<void>;
@@ -315,7 +347,7 @@ interface IWritableConfig {
     sameValueGuard?: boolean;
 }
 
-declare function bootstrapState(config?: IWritableConfig): void;
+declare function bootstrapState(config?: IWritableConfig, registry?: CustomElementRegistry): void;
 
 declare function getConfig(): IConfig;
 
@@ -489,7 +521,10 @@ interface WcsStateApi {
      * ワイルドカードを含むパスにマッチする全要素を配列で取得する。
      *
      * @param path - ワイルドカードを含むパス
-     * @param indexes - 各ワイルドカード階層のインデックス（省略時はループコンテキストから解決）
+     * @param indexes - 各ワイルドカード階層のインデックス（前方一致の接頭辞。`[]` は全階層を展開）。
+     *   省略時はループ文脈の添字（`[$1..$n]` 相当）のうち path と共有するワイルドカード連鎖の
+     *   分が接頭辞として敷かれる（文脈が path より深い分は切り詰め）。共有が無いのに文脈が
+     *   添字を持つ場合は throw する — 異なる文脈の添字は流用しない。
      *
      * @example
      * ```ts
@@ -499,6 +534,34 @@ interface WcsStateApi {
      * ```
      */
     $getAll<V = any>(path: string, indexes?: number[]): V[];
+    /**
+     * ワイルドカードを含むパスにマッチする**全アドレスへ一括で書き込む**（`$getAll` の対称形）。
+     *
+     * 配列を作り直さずに一括更新するための API。`this.users = this.users.map(...)` は
+     * ListIndex・行 getter キャッシュ・差分描画をまとめて作り直すが、`$setAll` は
+     * in-place な個別書き込みに分解するのでリストの同一性が保たれる。
+     *
+     * - `indexes` は `$getAll` と同じ**前方一致の接頭辞**（`[]` で全階層を展開）。省略は不可。
+     * - 関数を渡すと **mapper**（`(current, ...indexes) => next`）として要素ごとに評価される。
+     * - 配列は既定でブロードキャストされる。1 件ずつ配るには `{ spread: true }` を明示する。
+     * - `undefined` を書こうとした要素はスキップされる（クリアは `null`）。
+     *
+     * @returns 実際に書き込んだ件数（`undefined` でスキップした分を含まない）
+     *
+     * @example
+     * ```ts
+     * toggleAll(e: Event) {
+     *   this.$setAll("users.*.selected", [], (e.target as HTMLInputElement).checked);
+     * }
+     * invertAll() {
+     *   this.$setAll("users.*.selected", [], cur => !cur);
+     * }
+     * ```
+     */
+    $setAll<V = any>(path: string, indexes: number[], value: V | ((current: V, ...indexes: number[]) => V | undefined)): number;
+    $setAll<V = any>(path: string, indexes: number[], values: readonly V[], options: {
+        spread: true;
+    }): number;
     /**
      * 指定パスの更新を手動でトリガーする。
      * Proxy の set トラップを経由せずに内部状態を変更した場合に使用。
@@ -812,6 +875,22 @@ type DevtoolsEvent = {
     readonly stateName: string;
     /** `$watch` の宣言キー（ワイルドカードを含む生のパス） */
     readonly path: string;
+} | {
+    readonly type: "state:path-unresolved";
+    /** 書き手が書いた面。診断 code が binding / watch で変わる */
+    readonly source: "binding" | "watch";
+    readonly stateName: string;
+    /** 宣言されたパス（ワイルドカードを含む生の文字列） */
+    readonly path: string;
+    /** 解決に失敗したセグメント */
+    readonly missingSegment: string;
+} | {
+    readonly type: "state:binding-apply-error";
+    readonly stateName: string;
+    /** バインディングの state パス（ワイルドカードを含む生の文字列） */
+    readonly path: string;
+    readonly bindingType: string;
+    readonly error: unknown;
 } | {
     readonly type: "propagation:suppressed";
     readonly reason: "confirmation" | "visited-edge";