haori 0.40.0 → 0.41.0

package/dist/index.d.ts

@@ -90,6 +90,11 @@ export declare class Core {
      * 描画確定ごとに同じ警告を出し続けないために使用します。
      */
     private static readonly EACH_RENDERED_CHANGE_WARNED;
+    /**
+     * `data-each-key` の重複を警告済みの項目名。
+     * 描画のたびに同じ警告を出し続けないために使用します。
+     */
+    private static readonly WARNED_DUPLICATE_EACH_KEYS;
     /**
      * 遅延属性かどうか（完全名で判定）を判定します。
      *
@@ -285,7 +290,7 @@ export declare class Core {
      * `options.kind` に `'nonSupply'` を渡します。
      *
      * 解除の範囲は呼び出し側が選びません。**供給はその操作の通番までの編集を解除し、
-     * それより後の編集は残します**（仕様 1928 行）。飛行中の通信の応答が、送出後に
+     * それより後の編集は残します**（仕様「ユーザー編集と宣言バインドの権威」）。飛行中の通信の応答が、送出後に
      * 行われた編集を消さないのはこの規則によるものです。
      *
      * @param element 対象要素
@@ -362,6 +367,12 @@ export declare class Core {
      * 置き換えます。`data-each-arg` が無い構成では要素データのキーがそのまま行スコープ
      * へ広がるため、上位の宣言を接頭に付けます。
      *
+     * **`null` を返す 3 つの分岐は、振る舞いとしては観測できません。** 空の宣言や前置の
+     * 不一致では、`null` を返さずに組み立てを続けても `rows.` や `.items` のような経路に
+     * ならない文字列ができるだけで、呼び出し側の照合はどちらでも一致しません。意図を
+     * 明示するために残していますが、**これらを対象にした回帰テストは書けません**
+     * （`docs/ja/testing.md` の規則 2 に照らして、落ちないテストは足さない）。
+     *
      * @param element `data-each` を持つ要素
      * @param root 起点の要素（経路の基準）
      * @returns 絶対経路。式が空、または経路として扱えない場合は null
@@ -815,6 +826,18 @@ export declare class Core {
      * @param newList 新しいリスト
      */
     private static updateDiff;
+    /**
+     * `data-each-key` の値が重複していることを開発モードで警告します。
+     *
+     * 仕様「`data-each`」は `data-each-key` を一意なキーの項目名と定めています。
+     * 重複しても行は出現順で対応付けるため描画は崩れませんが、キーによる行の識別
+     * （差分更新での再利用、`data-form-list` の行の対応付け、行イベントのキー）は
+     * 意図した働きをしません。指定漏れに気づけるよう、項目名ごとに一度だけ知らせます。
+     *
+     * @param keyArg `data-each-key` に指定された項目名
+     * @returns 戻り値はありません。
+     */
+    private static warnDuplicateEachKey;
     /**
      * 再利用した `data-each` の行を、新しい並び順の位置へ移動します。
      *
@@ -843,6 +866,12 @@ export declare class Core {
      * 挿入すると以降の行は別の要素データを担当することになるため、変化した再利用行への
      * 適用は必要です（これを省くと挿入位置以降の入力値が前の行のまま残ります）。
      *
+     * 取得元（`data-each`）と収集先（`data-form-list`）が**別の配列**を指す構成では
+     * 反映しません。要素データが権威なのは「行の入力欄が集まって配列要素になる」
+     * 場合だけで、別の配列を繰り返している行では、要素データは入力欄を表しません。
+     * 反映すると、要素データに無い `name` の欄（選択のチェックボックスなど）が
+     * 空になります（`Form.isCollectedListFromEachSource()`）。
+     *
      * @param parent `data-each` コンテナのフラグメント
      * @param row 行のフラグメント
      * @param item 行の要素データ
@@ -938,7 +967,7 @@ declare class ElementFragment extends Fragment {
     /**
      * このフラグメントへ最後に適用された明示的な値の供給の通番（未適用は 0）。
      *
-     * 供給同士は後勝ちです（仕様 1927 行）。古い供給が後から届いた供給を上書きしない
+     * 供給同士は後勝ちです（仕様「反映待ちの間に起きた変化」）。古い供給が後から届いた供給を上書きしない
      * よう、供給を起こした操作の通番と比べて判定します。初期化も 1 つの供給として
      * 同じ列で数えます（`isSupplyStale()`）。
      */
@@ -1001,7 +1030,7 @@ declare class ElementFragment extends Fragment {
      * ミラーできず、属性と in-memory が食い違って残る不具合になっていました）。
      *
      * 値は書き込みの完了 Promise です。**同じ属性へ内部から届いた書き込みは捨てず**、
-     * この Promise を待ってから改めて反映します（後勝ち、仕様 1941 行）。捨てるのは
+     * この Promise を待ってから改めて反映します（後勝ち、仕様「反映待ちの間に起きた変化」）。捨てるのは
      * オブザーバー由来の書き戻し（＝自分の書き込みのエコー。ここがループの断ち口）と
      * 削除だけです。
      */
@@ -1232,7 +1261,7 @@ declare class ElementFragment extends Fragment {
      * 指定した通番の供給がすでに古くなっているかを返します。
      *
      * 真の場合、その供給より後の供給がこの宛先へ適用済みです。古い供給を載せると
-     * 「最後に供給された値が残る」（仕様 1927 行）が崩れるため、適用してはいけません。
+     * 「最後に供給された値が残る」（仕様「反映待ちの間に起きた変化」）が崩れるため、適用してはいけません。
      *
      * @param sequence 判定したい供給の通番
      * @returns より新しい供給が適用済みなら true
@@ -2446,15 +2475,38 @@ export declare class Form {
      * 未編集の欄まで編集の権威を得てしまいます。編集された経路だけを示すために使います
      * （`ValueChangeOrigin.editedPaths`）。
      *
+     * `data-if` が偽の分岐で収集から**除外された**キーの経路も含めます。除外は
+     * 「その入力欄がフォームから外れた」ことを意味するため、以前その欄で行われた編集が
+     * その経路の権威を持ち続けてはいけません。含めないと、非供給更新は「編集が確定した
+     * 宛先へは適用しない」規則（仕様「ユーザー編集と宣言バインドの権威」）で棄却され、
+     * 除外したキーが土台の値のまま
+     * 残ります（表示条件から外れた項目が保存値・送信データに残る）。除外を引き起こした
+     * のは利用者の編集（分岐の条件を変える操作）そのものです。
+     *
      * 配列（`data-form-list` の行）は対象外です。行と配列要素の対応はリストキーで
      * 決まり、収集値からは同じ規則で経路を組み立てられません。行の編集は応答の反映側
      * （`Procedure` の `reconcileRowUserEdits()`）で保護します。
      *
      * @param form 対象のフォームフラグメント
      * @param prefix 経路の接頭辞（`data-form-arg` のキーなど。無い場合は空文字）
+     * @param collected この更新が運ぶ収集値。除外されたキーの判定に使います。
+     *     **重ね合わせへ渡すものと同じオブジェクトを渡してください**（明示的に与えた
+     *     値が収集値へ重なっている場合、そのキーは除外の対象外になります）。省略時は
+     *     ここで収集し直します
      * @returns 編集された経路の集合
      */
-    static collectEditedPaths(form: ElementFragment, prefix?: string): ReadonlySet<string>;
+    static collectEditedPaths(form: ElementFragment, prefix?: string, collected?: Record<string, unknown> | null): ReadonlySet<string>;
+    /**
+     * 収集値をたどって、除外されたキーの経路を集めます。
+     *
+     * 除外は階層ごとに控えてあります（`COLLECTED_EXCLUDED_KEYS`）。表示中の分岐にも
+     * 同じキーがある場合は収集値に現れるため、経路には加えません。
+     *
+     * @param value たどる値
+     * @param path ここまでの経路
+     * @param paths 集める先
+     */
+    private static walkExcludedPaths;
     /**
      * 収集した編集値をたどって葉の経路を集めます。
      *
@@ -2471,6 +2523,8 @@ export declare class Form {
      * @param values オブジェクトに追加する値のオブジェクト
      * @param minUserEditSequence 指定した場合、この通し番号より後にユーザーが編集した
      *     入力欄だけを収集する（`data-form-list` の行位置は空オブジェクトで保持する）
+     * @param excluded この階層で `data-if-false` により除外されたキーを集める先。
+     *     null の場合は集めない（編集分だけの収集では使わない）
      * @returns values と同じオブジェクト
      */
     private static getPartValues;
@@ -2598,6 +2652,16 @@ export declare class Form {
      * @returns 宣言されている最上位のキー名
      */
     static collectDeclaredFieldKeys(root: ElementFragment): Set<string>;
+    /**
+     * フラグメントの配下で収集対象として**宣言されている**最上位のキー名を列挙します。
+     *
+     * `collectDeclaredFieldKeys()` の実体です。収集で除外した部分木が宣言している
+     * キーを知るために、除外側（`getPartValues()`）からも呼びます。
+     *
+     * @param root 走査の起点フラグメント
+     * @returns 宣言されている最上位のキー名
+     */
+    private static collectDeclaredKeysInFragment;
     /**
      * `data-validity` の条件を評価し、`setCustomValidity()` へ反映します。
      *
@@ -2666,6 +2730,15 @@ export declare class Form {
      * 配列そのものを鍵にして控えます。参照が失われた場合は出現順の対応へ退きます。
      */
     private static readonly COLLECTED_ROW_IDENTITY;
+    /**
+     * 収集値の各階層で、`data-if-false` により収集から除外されたキー。
+     *
+     * 収集値は素のオブジェクトなので、それ単体では「収集されなかったキー」と
+     * 「そもそも宣言が無いキー」を区別できません。重ね合わせは前者を落とし後者を
+     * 土台から引き継ぐ必要があるため、収集の時点でしか分からない除外を、階層ごとの
+     * オブジェクトそのものを鍵にして控えます。
+     */
+    private static readonly COLLECTED_EXCLUDED_KEYS;
     /** 出現順への退避を知らせた理由（同じ理由を繰り返さないため） */
     private static readonly warnedPositionalRowFallbacks;
     /**
@@ -2674,16 +2747,25 @@ export declare class Form {
      * @param rows 収集した行配列
      * @param keyArg `data-each-key` の指定（無ければ null）
      * @param keys 行ごとのリストキー（`rows` と同じ並び）
+     * @param identifiesItems リストキーで収集先の配列要素を識別できるかどうか
      */
     private static registerCollectedRowIdentity;
     /**
-     * 収集した行配列の識別情報を、複製した配列へ引き継ぎます。
+     * 収集値の階層に、除外されたキーの集合を結び付けます。
      *
-     * 収集値をたどって作り直す処理（`File` の正規化など）は配列を複製するため、
-     * 引き継がないと重ね合わせが出現順の対応へ退いてしまいます。
+     * @param values その階層の収集値
+     * @param keys 除外されたキー
+     */
+    private static registerCollectedExcludedKeys;
+    /**
+     * 収集値に控えた情報を、複製した値へ引き継ぎます。
      *
-     * @param from 元の配列
-     * @param to 複製した配列
+     * 収集値をたどって作り直す処理（`File` の正規化など）は配列やオブジェクトを
+     * 複製するため、引き継がないと重ね合わせが出現順の対応へ退いたり、非表示分岐で
+     * 除外したキーが土台から復活したりします。
+     *
+     * @param from 元の値
+     * @param to 複製した値
      */
     static carryCollectedRowIdentity(from: object, to: object): void;
     /**
@@ -2710,6 +2792,14 @@ export declare class Form {
      * ない場合は**出現順**の対応へ退きます。要素数はこの対応付けの結果に従うため、
      * 行の追加・削除はそのまま反映されます。
      *
+     * **`data-if` が偽の分岐で収集から除外されたキーは、土台からも落とします。**
+     * 除外は「表示中の分岐の入力値だけが直列化され、非表示分岐の値との競合は発生
+     * しません」（仕様の `data-if-false` 分岐とフォーム送信）を保証するためのもので、
+     * 土台の値が残るとこの保証が崩れ、表示条件から外れた項目が保存値・送信データに
+     * 残ります。引き継ぐのは**宣言の無いキー**だけです（`id` や表示専用のラベル
+     * など、そもそもどの入力欄も表さないキー）。この区別は条件式の評価スコープ
+     * （`buildConditionScope()`）が使うものと同じです。
+     *
      * プロトタイプ汚染につながるキー（`__proto__` など）は読み飛ばします。式評価は
      * これらをバインドキーとして受け付けないため、載せても参照できず、`__proto__` に
      * 至っては代入でオブジェクトのプロトタイプが差し替わってしまいます。
@@ -2727,6 +2817,54 @@ export declare class Form {
      * @returns 重ね合わせた値
      */
     private static overlayCollectedValue;
+    /**
+     * 式の先頭にある素の経路を切り出す正規表現。
+     *
+     * 1 つめの捕獲が経路、2 つめが残りです。`data-each` は式なので、経路として読める
+     * ものだけを経路として扱います。
+     */
+    private static readonly LEADING_PATH_PATTERN;
+    /**
+     * 式の先頭にある素の経路を返します。
+     *
+     * `rows` や `candidates.content` のような素の経路と、既定値を添えただけの
+     * `rows || []` / `rows ?? []` を経路として扱います。それ以外（関数呼び出しや
+     * 添字など）は経路として読めないものとして null を返します。
+     *
+     * `null` を返す 2 つの分岐は、呼び出し側から見て同じ結論（判定できないので従来
+     * どおりリストキーを使う）になるため、**振る舞いとしては区別できません**。回帰
+     * テストで押さえられるのは「`|| []` を経路として読む」側だけです
+     * （`tests/each-source-differs-from-form-list.test.ts`）。
+     *
+     * @param expression 対象の式
+     * @returns 先頭の経路。経路として読めない場合は null
+     */
+    private static resolveLeadingPath;
+    /**
+     * `data-each` の取得元が `data-form-list` の収集先と同じ配列かを判定します。
+     *
+     * 行のリストキーは `data-each` の**取得元**の要素から作ります（`data-each-key` は
+     * 取得元の項目名です）。そのキーで収集先の配列を引けるのは、取得元と収集先が同じ
+     * 配列のときだけです。別の配列を指す構成（候補一覧を繰り返して、選択結果を別の
+     * キーへ集める）では、どの行のキーも収集先には無いため、リストキーによる対応付け
+     * は全滅します。収集では全行が「配列から消えた行」と判定されて収集値が空配列に
+     * なり、書き戻しでは全行が「対応する要素なし」になります。同じ前提は要素データを
+     * 行の入力欄へ反映する経路（`Core.applyRowFormValues()`）にもあり、取得元の要素
+     * データで行の入力欄を上書きするため、取得元に無い `name` の欄が空になります。
+     *
+     * 判定は宣言だけで行います（実行時の値に依らせると、配列が一時的に空のときに
+     * 判定が揺れます）。`data-each` の式の先頭の経路の**末尾の区間**を `data-form-list`
+     * の名前と比べます。収集先の名前は収集構造の 1 区間なので、同じ配列であれば
+     * 取得元の経路の末尾もその名前になります（`items` / `dialog.items` / `r.items`）。
+     *
+     * 経路として読めない式（関数呼び出しなど）は判定できないため true を返し、
+     * 従来どおりリストキーで対応付けます。判定できないことを理由に対応付けを緩めると、
+     * 行の挿入・削除で値がずれる問題（0.39.2 で修正）が戻ってしまいます。
+     *
+     * @param container `data-form-list` を持つコンテナのフラグメント
+     * @returns 同じ配列を指す場合、または判定できない場合は true
+     */
+    static isCollectedListFromEachSource(container: ElementFragment): boolean;
     /**
      * 配列要素のリストキーと、その要素の位置の対応表を作ります。
      *
@@ -2889,9 +3027,9 @@ export declare class Form {
      * 対象フラグメントとその子孫要素の値を初期化します。
      * 値の初期化とメッセージのクリアを行います。
      *
-     * 初期化は「初期 `data-bind` 宣言の値を供給する 1 つの操作」です（仕様 3705 行）。
+     * 初期化は「初期 `data-bind` 宣言の値を供給する 1 つの操作」です（仕様「`data-{event}-reset`」）。
      * したがって他の供給と同じ後勝ちの規則に従い、**この初期化より後に供給された値が
-     * すでに載っている宛先へは書き込みません**（仕様 1927 行）。
+     * すでに載っている宛先へは書き込みません**（仕様「反映待ちの間に起きた変化」）。
      *
      * @param fragment 対象フラグメント
      * @param operationSequence 初期化を要求した操作の通番。**操作が起きた時点**
@@ -3703,7 +3841,7 @@ declare interface ValueChangeOrigin {
  * リリース時に `package.json` と揃えて更新します（`tests/version.test.ts` が
  * 一致を検査します）。
  */
-export declare const version = "0.40.0";
+export declare const version = "0.41.0";
 
 /**
  * すべてのレンダリングタスク（追従投入分を含む）の完了を待ちます。

package/package.json

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