@wcstack/state 1.27.0 → 1.29.0

package/dist/manifest.d.ts

@@ -57,6 +57,41 @@ interface IWcsManifest {
         };
         /** 構造ディレクティブ（`<template data-wcs="for: ...">` 等） */
         structuralDirectives: readonly string[];
+        /**
+         * 修飾子（`#` 後）の語彙。flags は値を取らない形（`#prevent`）、keyValue は
+         * `=` で値を取る形（`#init=element`）、eventNamePrefix は `on` + イベント名の形
+         * （`#onchange` — two-way / radio / checkbox のイベント名上書き。README「Modifiers」）。
+         * define.ts の定数が単一正本で、ランタイムの消費箇所も同じ定数に分岐する。
+         */
+        modifiers: {
+            flags: readonly string[];
+            keyValue: readonly string[];
+            eventNamePrefix: string;
+        };
+        /** リストインデックス参照名（`$1`..`$N`）。prefix + 1 始まり連番、maxDepth まで。 */
+        indexParam: {
+            prefix: string;
+            maxDepth: number;
+        };
+        /**
+         * bindingType 判別の語彙（parseBindTextsForElement の分岐と同一の定数から導出）。
+         * 判別順: else → spread → 構造ディレクティブ/radio/checkbox → eventToken・`on*`
+         * （event）→ prop。propNamespaces は左辺先頭セグメントの特殊 namespace で、
+         * apply 層のディスパッチキー集合との一致はテストが強制する。
+         * 既知の未収載: `radio` / `checkbox`（BindingType union のみが正本）。
+         */
+        bindingTypes: {
+            elseKeyword: string;
+            spread: string;
+            eventPropertyPrefix: string;
+            propNamespaces: {
+                eventToken: string;
+                command: string;
+                class: string;
+                attr: string;
+                style: string;
+            };
+        };
     };
     /** 組み込みフィルタ名（builtinFilters から自動導出＝実装が正本） */
     filters: string[];

package/dist/manifest.esm.js

@@ -1001,6 +1001,38 @@ const PROP_VALUE_SEPARATOR = ':'; // 左辺(prop)と右辺(path)の区切り
 const MODIFIER_SEPARATOR = '#'; // prop と修飾子の区切り
 const STATE_NAME_SEPARATOR = '@'; // path と @stateName の区切り
 const FILTER_SEPARATOR = '|'; // フィルタパイプの区切り
+// 修飾子（`#` 後）の語彙（単一正本）。manifest.syntax.modifiers で公開される。
+// フラグ形（`#prevent` — 値を取らない）とキー値形（`#init=element` — `=` で値を取る）。
+// 消費箇所（event/handler・BindingSession・twowayHandler・bindings/initialSync）は
+// この定数を参照する — 文字列リテラルの散在は tooling への収載漏れの温床だった
+// （docs/static-wiring-dx-design.md §2-2）。
+const MODIFIER_PREVENT = 'prevent';
+const MODIFIER_STOP = 'stop';
+const MODIFIER_READONLY = 'ro';
+const MODIFIER_FLAGS = Object.freeze([
+    MODIFIER_PREVENT, MODIFIER_STOP, MODIFIER_READONLY,
+]);
+const MODIFIER_KEY_INIT = 'init';
+const MODIFIER_KEY_SYNC = 'sync';
+const MODIFIER_KEYS = Object.freeze([
+    MODIFIER_KEY_INIT, MODIFIER_KEY_SYNC,
+]);
+// bindingType 判別と左辺 namespace の語彙（単一正本）。manifest.syntax.bindingTypes で
+// 公開される。パーサ（parseBindTextsForElement）とイベント層はこの定数に分岐する。
+// apply 層のディスパッチマップ（apply/applyChange.ts の applyChangeByFirstSegment）の
+// キー集合との一致は __tests__/manifest.test.ts の drift テストが強制する —
+// manifest エントリ（DOM 非依存）から apply 層を import しないための分離。
+const ELSE_KEYWORD = 'else';
+const SPREAD_PROP = '...';
+const EVENT_PROP_PREFIX = 'on';
+const EVENT_TOKEN_NAMESPACE = 'eventToken';
+const COMMAND_NAMESPACE = 'command';
+const CLASS_NAMESPACE = 'class';
+const ATTR_NAMESPACE = 'attr';
+const STYLE_NAMESPACE = 'style';
+// リストインデックス参照名（`$1`..`$N`）の接頭辞（単一正本）。
+// manifest.syntax.indexParam で公開される。
+const INDEX_PARAM_PREFIX = '$';
 /**
  * stackIndexByIndexName
  * インデックス名からスタックインデックスへのマッピング
@@ -1012,7 +1044,7 @@ const FILTER_SEPARATOR = '|'; // フィルタパイプの区切り
  */
 const tmpIndexByIndexName = {};
 for (let i = 0; i < MAX_WILDCARD_DEPTH; i++) {
-    tmpIndexByIndexName[`$${i + 1}`] = i;
+    tmpIndexByIndexName[`${INDEX_PARAM_PREFIX}${i + 1}`] = i;
 }
 Object.freeze(tmpIndexByIndexName);
 const STATE_CONNECTED_CALLBACK_NAME = "$connectedCallback";
@@ -1064,6 +1096,27 @@ function getWcsManifest() {
             },
             // 正本 STRUCTURAL_BINDING_TYPE_SET から導出（手書きの二重定義を排除）。
             structuralDirectives: Array.from(STRUCTURAL_BINDING_TYPE_SET),
+            modifiers: {
+                flags: MODIFIER_FLAGS,
+                keyValue: MODIFIER_KEYS,
+                eventNamePrefix: EVENT_PROP_PREFIX,
+            },
+            indexParam: {
+                prefix: INDEX_PARAM_PREFIX,
+                maxDepth: MAX_WILDCARD_DEPTH,
+            },
+            bindingTypes: {
+                elseKeyword: ELSE_KEYWORD,
+                spread: SPREAD_PROP,
+                eventPropertyPrefix: EVENT_PROP_PREFIX,
+                propNamespaces: {
+                    eventToken: EVENT_TOKEN_NAMESPACE,
+                    command: COMMAND_NAMESPACE,
+                    class: CLASS_NAMESPACE,
+                    attr: ATTR_NAMESPACE,
+                    style: STYLE_NAMESPACE,
+                },
+            },
         },
         // 実装（Record のキー）から自動導出。手リストを持たない＝ドリフトの構造的排除。
         filters: Object.keys(outputBuiltinFilters),

package/dist/parser.d.ts

@@ -0,0 +1,115 @@
+interface IPathInfo {
+    readonly id: number;
+    readonly path: string;
+    readonly segments: string[];
+    readonly lastSegment: string;
+    readonly cumulativePaths: string[];
+    readonly cumulativePathSet: Set<string>;
+    readonly cumulativePathInfos: IPathInfo[];
+    readonly cumulativePathInfoSet: Set<IPathInfo>;
+    readonly parentPath: string | null;
+    readonly parentPathInfo: IPathInfo | null;
+    readonly wildcardPaths: string[];
+    readonly wildcardPathSet: Set<string>;
+    readonly indexByWildcardPath: Record<string, number>;
+    readonly wildcardPathInfos: IPathInfo[];
+    readonly wildcardPathInfoSet: Set<IPathInfo>;
+    readonly wildcardParentPaths: string[];
+    readonly wildcardParentPathSet: Set<string>;
+    readonly wildcardParentPathInfos: IPathInfo[];
+    readonly wildcardParentPathInfoSet: Set<IPathInfo>;
+    readonly wildcardPositions: number[];
+    readonly lastWildcardPath: string | null;
+    readonly lastWildcardInfo: IPathInfo | null;
+    readonly wildcardCount: number;
+}
+
+/**
+ * Filter/types.ts
+ *
+ * Type definition file for filter functions.
+ *
+ * Main responsibilities:
+ * - Defines types for filter functions (FilterFn) and filter functions with options (FilterWithOptionsFn)
+ * - Type-safe management of filter name-to-function mappings (FilterWithOptions) and filter function arrays (Filters)
+ * - Defines types for retrieving filter functions from built-in filter collections
+ *
+ * Design points:
+ * - Type design enabling flexible filter design and extension
+ * - Supports filters with options and combinations of multiple filters
+ */
+type FilterFn<T = unknown> = (value: unknown) => T;
+
+type BindingType = 'text' | 'prop' | 'event' | 'for' | 'if' | 'elseif' | 'else' | 'radio' | 'checkbox' | 'spread';
+interface IFilterInfo {
+    readonly filterName: string;
+    readonly args: string[];
+    readonly filterFn: FilterFn;
+}
+/**
+ * バインディング式のパース結果（DOM 非依存の部分）。`@wcstack/state/parser` の
+ * ParseBindTextResult がこれをそのまま公開するため、Node 等の DOM lib 型を
+ * ここに足してはならない（足すなら IBindingInfo 側へ）。
+ */
+interface IParsedBinding {
+    readonly propName: string;
+    readonly propSegments: string[];
+    readonly propModifiers: string[];
+    readonly statePathName: string;
+    readonly statePathInfo: IPathInfo;
+    readonly stateName: string;
+    readonly inFilters: IFilterInfo[];
+    readonly outFilters: IFilterInfo[];
+    readonly bindingType: BindingType;
+    readonly uuid?: string | null;
+}
+
+type ParseBindTextResult = IParsedBinding;
+
+declare function parseBindTextsForElement(bindText: string): ParseBindTextResult[];
+
+declare function parseBindTextForEmbeddedNode(bindText: string): ParseBindTextResult;
+
+declare function getPathInfo(path: string): IPathInfo;
+
+/**
+ * parser.ts — `data-wcs` バインディング構文の正本パーサを tooling 向けに公開する
+ * サブパスエントリ（`@wcstack/state/parser`）。
+ *
+ * `./manifest` と同じ「実装が唯一の正本」パターン（docs/static-wiring-dx-design.md D2）。
+ * vscode-wcs の正規表現パーサ・devtools の declaredScan 簡易パーサという複製実装を
+ * 段階的にこの正本へ寄せるための土台。
+ *
+ * 契約:
+ * - DOM 非依存・純関数（bindText 文字列 → ParseBindTextResult[]）。Node でそのまま動く
+ *   （__tests__/parser.test.ts が node 環境で検証する）。
+ * - **位置情報は持たず、不正構文は raiseError で throw する**。エラー耐性と診断 range の
+ *   生成は消費側（vscode-wcs の positional ラッパー）の責務（同 D3）— ランタイムの
+ *   サイズと責務をここで増やさない。
+ * - `getPathInfo` はパス文字列の解析済みビュー（セグメント・ワイルドカード位置・親パス
+ *   チェーン）を返す純関数。静的依存グラフの親チェーン展開はこの情報から機械的に再現できる。
+ *   同一パス → 同一インスタンスの保証は**このエントリのモジュールインスタンス内**でのみ
+ *   成立する（`.` エントリは別バンドル＝別キャッシュ。ランタイムの PathInfo と identity
+ *   比較してはならない）。キャッシュは無制限（evict なし）— 言語サーバー等の長時間
+ *   プロセスでは入力パス種数に単調比例してメモリが増える点に留意。
+ * - `ParseBindTextResult.uuid` はランタイム内部（構造テンプレートのハイドレーション台帳）
+ *   用のフィールドで、このパーサの戻り値では常に undefined。
+ *
+ * 公開面は意図的に最小（公開＝恒久契約）。`expandSpread` は live Element と
+ * CustomElementRegistry を要するためここには含めない — ブラウザ内の消費者
+ * （devtools の declared 正本化）は state 自身が pull API で答える。
+ */
+
+/**
+ * このエントリの内部キャッシュ（PathInfo intern・フィルタ列パース結果）を全て捨てる。
+ *
+ * 言語サーバー等の**長時間プロセス専用**。編集中の中間パス（`user.n` 等）が
+ * 無制限キャッシュに恒久 intern されてメモリが単調増加するため、ドキュメント
+ * クローズ等の区切りで呼ぶ。クリア後の getPathInfo は同一パスに**新しい**
+ * インスタンスを返す — 「同一パス → 同一参照」の保証はクリアを跨がない。
+ * ランタイム（`.` エントリ）にはこの API は無く、呼ばれることもない。
+ */
+declare function clearParserCaches(): void;
+
+export { clearParserCaches, getPathInfo, parseBindTextForEmbeddedNode, parseBindTextsForElement };
+export type { BindingType, IFilterInfo, IPathInfo, ParseBindTextResult };