haori 0.47.2 → 0.47.4

package/dist/index.d.ts

@@ -315,6 +315,19 @@ export declare class Core {
      * 経路が存在しないことを表す番兵。`undefined` を値として持つ経路と区別します。
      */
     private static readonly ABSENT_PATH;
+    /**
+     * 宣言データとして外へ出すデータから予約キーを取り除きます。
+     *
+     * `_fetch` / `_poll` は内部バインディングデータにのみ持つ実行時の値で、宣言
+     * データとしては外へ出しません（仕様「`data-bind`」）。内部データ側は予約キーを
+     * 引き継ぐため（`ElementFragment.setBindingData()`）、出口の側で取り除かないと、
+     * `data-bind` 属性が数秒ごとの状態遷移で書き換わり続け、`data-{event}-copy` は
+     * 別の要素のフェッチ状態をコピー先へ運びます。
+     *
+     * @param data 外へ出すバインドデータ
+     * @returns 予約キーを除いたデータ
+     */
+    static withoutReservedBindingKeys(data: Record<string, unknown>): Record<string, unknown>;
     /**
      * 変化した経路ごとに適用可否を判定し、棄却した経路を前の値のまま残したデータを
      * 返します。
@@ -1315,9 +1328,35 @@ declare class ElementFragment extends Fragment {
     /**
      * バインドデータを設定します。
      *
+     * 予約キー（`_` 始まりのエンジン管理変数）は、新しいデータが同じキーを持たない
+     * 限り引き継ぎます（仕様「`data-bind`」）。予約キーは `data-bind` 属性へ書き出さ
+     * ないため、宣言を取り込む側も外部から属性を書き換える側もこの値を運べません。
+     * 引き継がないと、`data-if` が真になったときの子の初期化や外部からの書き換えの
+     * たびに `_fetch` / `_poll` が消え、注入した状態が「まだ何も起きていない」状態と
+     * 区別できなくなります。明示的に落とす場合はキー自体を持たせてください
+     * （`{_fetch: undefined}`）。
+     *
      * @param data バインドデータ
      */
     setBindingData(data: Record<string, unknown>): void;
+    /**
+     * 新しいバインドデータへ、現在の予約キーのうち引き継ぐものを足します。
+     *
+     * @param data 新しいバインドデータ
+     * @returns 予約キーを引き継いだバインドデータ
+     */
+    private withRetainedReservedKeys;
+    /**
+     * 予約キー（エンジン管理変数）かどうかを判定します。
+     *
+     * `_fetch` / `_poll` など、Haori が実行時に注入し、`data-bind` 属性へ書き出さない
+     * 値が対象です（仕様「`data-bind`」）。`data-bind` 属性へのミラー
+     * （`Core.setBindingData()`）も同じ判定で対象から外します。
+     *
+     * @param key 判定対象のキー
+     * @returns 予約キーなら true
+     */
+    static isReservedBindingKey(key: string): boolean;
     /**
      * バインドデータ更新に伴う DOM 反映・再評価を、同一フラグメントでは呼出順
      * （FIFO）で直列実行します。並行呼出による適用順の逆転（古いデータが後から
@@ -2938,16 +2977,34 @@ export declare class Form {
      */
     static resolveSyncValues(form: ElementFragment, data: Record<string, unknown>): Record<string, unknown>;
     /**
-     * `data-form-arg` のキーを所有する祖先を解決します。
+     * キーを所有する祖先を、値の型を問わず解決します。
      *
      * 対象はフォームより外側の要素の**生バインドデータ**（`data-bind` で宣言・更新
      * された値）だけです。`data-derive` の派生データと `data-each` の行データは対象外
      * とします。どちらも描画のたびに作り直される仮想スコープで、行単位の書き戻しは
      * `data-form-list` が担うため、ここで扱うと反映が行生成と競合します。
      *
-     * 最も近い所有者だけを見ます。その値がオブジェクトでない場合、または所有者が
-     * `data-each` の行である場合は、より外側は探しません（近い方が権威という
-     * シャドーの規則に従うため）。
+     * 最も近い所有者だけを見ます。所有者が `data-each` の行である場合は、より外側は
+     * 探しません（近い方が権威というシャドーの規則に従うため）。
+     *
+     * 値の型を問わないのは、収集キーの土台を解決する用途があるためです
+     * （仕様「祖先が所有する値の反映（`data-form-arg` なし）」の「土台に使う値の型は
+     * 問いません」）。`data-form-list` の収集キーは配列になるので、レコード限定に
+     * すると土台が解決できません。`data-form-arg` のキーはレコードに限るため、
+     * そちらは `resolveAncestorArgOwner()` が絞り込みます。
+     *
+     * @param form フォームのElementFragment
+     * @param key キー名
+     * @returns 所有する祖先フラグメントとその値。見つからない場合は null
+     */
+    private static resolveAncestorKeyOwner;
+    /**
+     * `data-form-arg` のキーを所有する祖先を解決します。
+     *
+     * `data-form-arg` はフォームの入力欄が**そのキーの配下**に対応することを宣言する
+     * ため、値はレコードに限ります。レコードでない値を所有している場合は所有者なしと
+     * して扱い、開発モードで警告します。黙って退くと収集値がそのままそのキーへ入り、
+     * 配列を宣言していた場合は**型がオブジェクトへ変わります**（一覧を描く式が壊れる）。
      *
      * @param form フォームのElementFragment
      * @param key `data-form-arg` で指定されたキー名
@@ -2957,6 +3014,32 @@ export declare class Form {
         owner: ElementFragment;
         value: Record<string, unknown>;
     } | null;
+    /**
+     * 収集キーの土台を祖先から解決する関数を返します。
+     *
+     * `data-form-arg` を宣言しないフォームでも、収集キーを祖先が所有する構成では
+     * その値が土台になります（仕様「祖先が所有する値の反映（`data-form-arg` なし）」の
+     * 「コミット時は**収集したキーごとに、最も近い所有者の値を土台に収集値を
+     * 重ねます**」）。`Form.mergeCollectedValues()` へ渡して使います。
+     *
+     * @param form フォームのElementFragment
+     * @returns キーを受け取り、祖先が所有する値を返す関数（所有者が無ければ undefined）
+     */
+    static ancestorBaseResolver(form: ElementFragment): (key: string) => unknown;
+    /**
+     * `data-form-arg` のキーをレコード以外で所有している構成を、開発モードで知らせます。
+     *
+     * @param form フォームのElementFragment
+     * @param key `data-form-arg` で指定されたキー名
+     * @param value 祖先が所有している値
+     */
+    private static warnArgOwnerIsNotRecord;
+    /**
+     * `data-form-arg` の所有者がレコードでないことを警告済みのキー。
+     *
+     * 同じ構成で毎回の収集ごとに警告しないよう、要素とキーの組で控えます。
+     */
+    private static readonly warnedArgOwnerNotRecord;
     /**
      * 条件式（`data-validity` / `data-{event}-if`）の評価スコープを作ります。
      *
@@ -3192,11 +3275,20 @@ export declare class Form {
      * これらをバインドキーとして受け付けないため、載せても参照できず、`__proto__` に
      * 至っては代入でオブジェクトのプロトタイプが差し替わってしまいます。
      *
+     * **土台に無いキーは `resolveBase` で解決します。** フォーム自身が収集キーを
+     * 持たず祖先が持っている構成では、土台がここに無いためです（仕様「双方向
+     * バインディングの自動更新」の「土台はフォーム自身のバインドデータに限りません」）。
+     * 呼び出し側で土台を組み立ててから渡す形にしないのは、上のプロトタイプ汚染の
+     * ガードを迂回させないためです（解決した値の代入もこのループの中で行います）。
+     * 入れ子のレコードへ再帰する際は渡しません（解決するのはトップレベルの収集キー
+     * だけで、入れ子のキーはバインドキーではないため）。
+     *
      * @param previous 直前のバインドデータ（無い場合は null）
      * @param collected 収集値
+     * @param resolveBase 土台に無いキーの土台を返す関数。省略時は解決しない
      * @returns 収集値を重ねたバインドデータ
      */
-    static mergeCollectedValues(previous: Record<string, unknown> | null, collected: Record<string, unknown>): Record<string, unknown>;
+    static mergeCollectedValues(previous: Record<string, unknown> | null, collected: Record<string, unknown>, resolveBase?: ((key: string) => unknown) | null): Record<string, unknown>;
     /**
      * 収集値の 1 項目を、直前の値へ重ねます。
      *
@@ -3314,10 +3406,20 @@ export declare class Form {
      */
     private static overlayIdentifiedRows;
     /**
-     * 祖先のバインドデータ更新を、配下の `data-form-arg` フォームの入力欄へ反映します。
+     * 祖先のバインドデータ更新を、配下のフォームへ反映します。
+     *
+     * `data-form-arg` を宣言したフォームへは入力欄まで流し込みます。対象は「当該キーを
+     * 所有するのが更新された祖先自身」であるフォームだけです。間に同名キーを持つ要素が
+     * あればそちらが権威なので対象外とします。
      *
-     * 対象は「当該キーを所有するのが更新された祖先自身」であるフォームだけです。
-     * 間に同名キーを持つ要素があればそちらが権威なので対象外とします。
+     * `data-form-arg` の無い収集単位（`<form>` と `data-form` コンテナ）には、双方向
+     * コミットが作ったコピーの解除だけを行います（仕様「祖先が所有する値の反映
+     * （`data-form-arg` なし）」の「祖先が当該キーを更新したときに解除するため、以降の
+     * 更新が届かなくなることはありません」）。解除しないと、一度でも入力した収集単位は
+     * 以降どの再取得も受け付けません。入力欄へ流し込まないのは、どのキーが対応するかを
+     * 宣言していないためです（同節の「入力欄への流し込みは `data-form-arg` を宣言した
+     * 場合だけです」）。行の入力欄は解除後の再評価で `data-each` の行単位の反映が
+     * 拾います。
      *
      * 更新が始まった後に初期化されたフォームも対象外です。祖先の更新は初期化前の
      * 状態を運んでいるため、流し込むとクリアしたはずの値が復活します。
@@ -3325,9 +3427,44 @@ export declare class Form {
      * @param fragment 更新された祖先のフラグメント
      * @param resetSequence 更新が始まった時点の初期化の通番
      * @param origin 値の由来（通番と種別）。渡すと入力欄ごとに適用可否を判定します
+     * @param previous 更新前の祖先の生バインドデータ。渡すと値が変わったキーだけ解除する
+     * @returns 反映完了の Promise
+     */
+    static syncAncestorArgForms(fragment: ElementFragment, resetSequence: number, origin?: ValueChangeOrigin | null, previous?: Record<string, unknown> | null): Promise<void>;
+    /**
+     * 配下の収集単位のうち、祖先のキーをコピーでシャドーしているものを列挙します。
+     *
+     * 収集単位は `<form>` と `data-form` コンテナの両方です（`Form.getFormFragment()`
+     * が対象にする範囲と揃えます）。どちらも双方向コミットの書き込み先になるため、
+     * どちらもコピーを作って祖先をシャドーしえます。仕様「祖先が所有するレコードの
+     * 反映（`data-form-arg`）」が `data-form` を対象外とするのは**入力欄への流し込み**
+     * についてで、シャドーの解除には当てはまりません。
+     *
+     * `data-form-arg` を宣言した `<form>` は除きます。そちらは `collectArgForms()` が
+     * 扱い、`pushAncestorArgValue()` が入力欄への流し込みまで行います。
+     *
+     * 列挙するキーは、収集単位自身の生バインドデータが持ち、かつ**初期 `data-bind`
+     * 宣言に無い**キーに限ります。宣言のあるキーは双方向コミットが作ったコピーでは
+     * なく自身の宣言なので、祖先が同名のキーを更新しても落としてはなりません。
+     *
+     * @param root 走査の起点フラグメント（更新された祖先）
+     * @returns 収集単位のフラグメントと、それが `root` のキーをシャドーしているキー名の
+     *     一覧。シャドーしているキーが無い収集単位は含みません
+     */
+    private static collectShadowingContainers;
+    /**
+     * 双方向コミットが作ったコピーを、フォーム自身のバインドデータから取り除きます。
+     *
+     * 取り除くと、フォーム内の式とフラグメントの継承は祖先の値を見るようになります。
+     * 入力欄へは触りません（`data-each` の行は解除後の再評価で描き直され、行単位の
+     * 反映が値を入れます）。
+     *
+     * @param form フォームのElementFragment
+     * @param keys 取り除くキー名の一覧
+     * @param origin 値の由来（通番と種別）。祖先の更新を起こした操作のものを引き継ぐ
      * @returns 反映完了の Promise
      */
-    static syncAncestorArgForms(fragment: ElementFragment, resetSequence: number, origin?: ValueChangeOrigin | null): Promise<void>;
+    private static releaseOwnCopy;
     /**
      * 指定要素の配下にある `data-form-arg` 付きフォームを列挙します。
      *
@@ -3528,6 +3665,17 @@ export declare class Form {
      * @returns すべての初期化処理が完了するPromise
      */
     static reset(fragment: ElementFragment, operationSequence?: number): Promise<void>;
+    /**
+     * 祖先が所有するキーを、リセットの書き込み対象から落とします。
+     *
+     * 落とすのは初期 `data-bind` 宣言に無いキーだけです。宣言のあるキーはフォーム
+     * 自身が持つべき値で、祖先が同名のキーを持っていてもフォームの宣言が権威です。
+     *
+     * @param form フォームのElementFragment
+     * @param initial 初期 `data-bind` 宣言（無い場合は null）
+     * @param target リセットで書き込むバインドデータ（この場で書き換えます）
+     */
+    private static deleteAncestorOwnedKeys;
     /**
      * data-bind 属性で宣言された初期バインドデータを取得します。
      *
@@ -4364,7 +4512,7 @@ declare interface ValueChangeOrigin {
  * リリース時に `package.json` と揃えて更新します（`tests/version.test.ts` が
  * 一致を検査します）。
  */
-export declare const version = "0.47.2";
+export declare const version = "0.47.4";
 
 /**
  * すべてのレンダリングタスク（追従投入分を含む）の完了を待ちます。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "haori",
-  "version": "0.47.2",
+  "version": "0.47.4",
   "description": "A lightweight HTML-first UI engine powered by declarative data bindings and expressions.",
   "scripts": {
     "dev": "vite",