haori 0.43.0 → 0.44.0

package/dist/index.d.ts

@@ -950,6 +950,10 @@ declare class ElementFragment extends Fragment {
      * 真とする」）。
      */
     private static readonly NUMBER_INPUT_PATTERN;
+    /** `data-value-type` で宣言できる収集値の型（仕様「`data-value-type`」） */
+    private static readonly VALUE_TYPE_NAMES;
+    /** `data-value-type` の宣言について警告済みのキー（同じ宣言で繰り返さない） */
+    private static readonly loggedValueTypeDeclarations;
     /** HTML 真偽属性名のセット */
     private static readonly BOOLEAN_ATTRIBUTES;
     /** inputイベントを発生させるタイプ */
@@ -1604,6 +1608,15 @@ declare class ElementFragment extends Fragment {
      * `<select>` の候補が揃ってから載せ直す）。二度目を弾くと供給された値が画面に
      * 載りません。
      *
+     * **双方向コミットが運ぶ値は、この入力欄が自身の編集より後に初期化されていれば
+     * 適用しません。** コミット（`change` / `input`）はフォーム全体の収集値を運びますが、
+     * その値を読んだのは編集の時点です。`change` はフォーカスを外した時点で発火する
+     * ため、読んだ後・書き戻す前に初期化が挟まることがあります。呼び出しの時点だけで
+     * 比べると「初期化より後に始まった更新」と見なされ、クリアした値が復活します
+     * （仕様「`data-{event}-reset`」の「進行中のバインドデータ更新は書き戻しません」）。
+     * 初期化より後に行われた編集（`userEditSequence` の方が新しい欄）は対象外なので、
+     * クリアの途中に打った文字はそのまま残ります。
+     *
      * @param origin 適用しようとしている値の由来
      * @returns 適用してよい場合は true
      */
@@ -1667,6 +1680,29 @@ declare class ElementFragment extends Fragment {
      * @returns 発番した編集の通番
      */
     markUserEdit(): number;
+    /**
+     * 直前の `change` による編集の記録で使った通番。
+     *
+     * その後に打鍵（`input`）があったかどうかを `markUserEditOnChange()` で判定します。
+     */
+    private lastChangeSequence;
+    /**
+     * `change` によるユーザー編集を記録します。
+     *
+     * **`change` の発火そのものは編集の時点になりません。** 編集の時点は値が変わった
+     * 時点で、打鍵なら `input` が記録しています（仕様「ユーザー編集と宣言バインドの
+     * 権威」の「印は打鍵ごと（`input`）に付きます」）。`change` はフォーカスを外した
+     * 時点でしか発火しないため、そこで打ち直すと、打鍵の後・`change` の前に要求された
+     * 供給（`data-{event}-reset` など）よりも新しい編集に見え、その供給が「要求より後の
+     * 編集」として棄却されてしまいます（仕様「反映待ちの間に起きた変化」）。
+     *
+     * したがって直前の `change` より後に打鍵があれば、**その打鍵の時点**を編集の時点
+     * とします。打鍵が無い場合（外部ライブラリが `<select>` の値を差し替えたときなど）
+     * は、値が変わったことをここで初めて知るため、この時点を編集として記録します。
+     *
+     * @returns この編集の通番
+     */
+    markUserEditOnChange(): number;
     /**
      * この入力欄を最後にユーザーが編集したときの通し番号を返します。
      *
@@ -1735,19 +1771,82 @@ declare class ElementFragment extends Fragment {
      */
     clearValue(): void;
     /**
-     * 入力要素の種別に応じて値を正規化します。
+     * 入力要素の種別と `data-value-type` の宣言に応じて値を正規化します。
      *
      * `type="number"` の input では、文字列の入力値・バインド値を数値へ変換します
      * （DTO が数値型を期待する場合に文字列で送られるのを防ぐため）。数値として採用
      * するのは、ブラウザが `<input type="number">` の値として受け付ける文字列だけで
      * す（`NUMBER_INPUT_PATTERN`）。空文字・`null`・受け付けない文字列・有限でない数値
-     * は `null` を返します。それ以外の要素では値をそのまま返します。
+     * は `null` を返します。
+     *
+     * `data-value-type` を宣言した入力欄では、宣言した型へ正規化します（仕様
+     * 「`data-value-type`」）。宣言は `type` より優先するため、`type="number"` へ
+     * `string` を宣言した場合は文字列になります。それ以外の要素では値をそのまま
+     * 返します。
      *
      * @param element 対象の入力要素
      * @param value 正規化する値
-     * @returns 正規化後の値（`type="number"` なら数値または null）
+     * @returns 正規化後の値（宣言または `type="number"` に従う）
      */
     private normalizeValueForElement;
+    /**
+     * 値を数値へ正規化します。
+     *
+     * 数値として採用するのは、ブラウザが `<input type="number">` の値として受け付ける
+     * 文字列だけです（`NUMBER_INPUT_PATTERN`）。空文字・`null`・受け付けない文字列・
+     * 有限でない数値は `null` になります（仕様「収集は DOM を真とする」）。
+     *
+     * @param value 正規化する値
+     * @returns 数値。数値として採用できない場合は null
+     */
+    private static normalizeNumberValue;
+    /**
+     * 値を真偽値へ正規化します。
+     *
+     * `"true"` / `"false"` を大文字小文字の区別なく判定します。空文字・`null`・それ以外
+     * の文字列（`"1"` / `"on"` など）は `null` です。未入力を `false` として送らない
+     * ため、また画面に出ていない値を送らないためで、真偽値がそのまま渡された場合は
+     * その値を使います（仕様「`data-value-type`」）。
+     *
+     * @param value 正規化する値
+     * @returns 真偽値。判定できない場合は null
+     */
+    private static normalizeBooleanValue;
+    /**
+     * 入力欄に宣言された収集値の型（`data-value-type`）を解決します。
+     *
+     * 宣言は静的なものとして扱い、DOM の属性から直接読みます。宣言できるのは
+     * `boolean` / `number` / `string` で、対象は値を持つ入力（`<input>` のうち
+     * `checkbox` / `radio` / `file` を除くもの、`<textarea>`、単一選択の `<select>`）
+     * です。対象外の要素や未知の型は宣言が無いものとして扱い、開発モードで警告します
+     * （仕様「`data-value-type`」）。
+     *
+     * @param element 対象の要素
+     * @returns 宣言された型。宣言が無い場合と無視する場合は null
+     */
+    private static resolveDeclaredValueType;
+    /**
+     * `data-value-type` の宣言を受け付ける要素かどうかを判定します。
+     *
+     * チェック状態を収集する `checkbox` / `radio`、ファイルを収集する `file`、値を配列
+     * で収集する複数選択の `<select>` は、宣言した型へ正規化する対象になりません
+     * （仕様「`data-value-type`」）。
+     *
+     * @param element 対象の要素
+     * @returns 受け付ける場合は true
+     */
+    private static acceptsDeclaredValueType;
+    /**
+     * `data-value-type` の宣言を無視したことを開発モードで警告します。
+     *
+     * 値の読み取りごとに解決するため、同じ宣言では一度だけ報告します。
+     *
+     * @param element 宣言した要素
+     * @param declared 宣言された値
+     * @param reason 無視した理由
+     * @returns 戻り値はありません。
+     */
+    private static warnValueTypeDeclaration;
     /**
      * `value` の宣言バインド（テンプレート式・`data-attr-value`）で DOM プロパティと
      * 内部値を同期する対象要素かどうかを判定します。
@@ -2432,6 +2531,31 @@ export declare class Form {
      * @returns 宣言バインドで値または状態が決まる場合 true
      */
     private static isDeclarativeStateBound;
+    /**
+     * 対象の部分木にある入力欄を、ネイティブのフォームリセットと同じ既定値へ戻します。
+     *
+     * `<form>` でない要素を初期化する場合に使います。`form.reset()` は「フォームに属する
+     * 入力欄」しか戻せないため、以前は対象の要素を一時的な `<form>` へ移して呼び出して
+     * いましたが、**要素を DOM から外すとフラグメントと実行時のバインドデータが破棄され**、
+     * 同じ操作の後段の書き込みが空のバインドデータを土台にしてしまいます
+     * （`data-fetch-bind` で寄せたキーが消える。仕様「`data-{event}-reset`」）。
+     * そこで DOM の構造は変えず、HTML 仕様のリセットアルゴリズムと同じ既定値
+     * （`defaultValue` / `defaultChecked` / `defaultSelected`）へ戻します。
+     *
+     * @param root 対象の要素（自身と配下すべてが対象）
+     * @return 戻り値はありません。
+     */
+    private static restoreDefaultValues;
+    /**
+     * `<select>` の選択状態を既定の選択（`defaultSelected`）へ戻します。
+     *
+     * 既定の選択が無い単一選択では、ブラウザのリセットと同じく先頭の選択できる
+     * `<option>` を選びます（HTML 仕様のリセットアルゴリズム）。
+     *
+     * @param select 対象の select エレメント
+     * @return 戻り値はありません。
+     */
+    private static restoreDefaultSelection;
     /**
      * 宣言バインドで値・状態が決まる入力について、DOM 側の値を空へ揃えます。
      *
@@ -2504,15 +2628,41 @@ export declare class Form {
      * 決まり、収集値からは同じ規則で経路を組み立てられません。行の編集は応答の反映側
      * （`Procedure` の `reconcileRowUserEdits()`）で保護します。
      *
+     * 経路には**その編集が起きた時点**の通番を持たせます。コミットの通番で主張すると、
+     * 編集の後・コミットの前に要求された供給（`data-{event}-reset` など）が「編集の方が
+     * 新しい」と判定されて棄却されます（`ValueChangeOrigin.editedPaths`）。
+     *
+     * 走査は「編集の通番の種類数」だけ繰り返します（＝編集された欄の数が上限）。経路の
+     * 組み立ては収集値の形に合わせる必要があり、収集は基準の通番で絞り込めるためこの形
+     * にしています。呼び出しは `change` / `input` の確定ごとで、走査 1 回はフォーム配下の
+     * 走査に相当します。
+     *
      * @param form 対象のフォームフラグメント
+     * @param updateSequence この更新（双方向コミット）の通番。編集そのものではなく
+     *     「この更新が引き起こした」経路（非表示分岐で除外されたキー）に使います
      * @param prefix 経路の接頭辞（`data-form-arg` のキーなど。無い場合は空文字）
      * @param collected この更新が運ぶ収集値。除外されたキーの判定に使います。
      *     **重ね合わせへ渡すものと同じオブジェクトを渡してください**（明示的に与えた
      *     値が収集値へ重なっている場合、そのキーは除外の対象外になります）。省略時は
      *     ここで収集し直します
-     * @returns 編集された経路の集合
+     * @returns 編集された経路と、その編集が起きた時点の通番
+     */
+    static collectEditedPaths(form: ElementFragment, updateSequence: number, prefix?: string, collected?: Record<string, unknown> | null): ReadonlyMap<string, number>;
+    /**
+     * 部分木の入力欄が持つユーザー編集の通番を、大きい順の重複なしで返します。
+     *
+     * @param fragment 対象フラグメント（配下も辿る）
+     * @returns 編集の通番の配列（降順）
      */
-    static collectEditedPaths(form: ElementFragment, prefix?: string, collected?: Record<string, unknown> | null): ReadonlySet<string>;
+    private static collectUserEditSequences;
+    /**
+     * 部分木をたどってユーザー編集の通番を集めます。
+     *
+     * @param fragment 対象フラグメント
+     * @param sequences 集める先
+     * @returns 戻り値はありません。
+     */
+    private static walkUserEditSequences;
     /**
      * 収集値をたどって、除外されたキーの経路を集めます。
      *
@@ -3859,12 +4009,14 @@ declare interface SetBindingDataOptions {
      */
     readonly sequence?: number;
     /**
-     * この更新のうち、利用者が実際に編集したバインドデータの経路。
+     * この更新のうち、利用者が実際に編集したバインドデータの経路と、その編集が起きた
+     * 時点の通番。
      *
      * フォーム全体の収集値を運ぶ双方向コミットが、未編集の欄まで編集の権威を得ない
-     * ようにするために渡します（`Form.collectEditedPaths()`）。
+     * ようにするために渡します（`Form.collectEditedPaths()`）。経路ごとに通番を持つ
+     * 理由は `ValueChangeOrigin.editedPaths` を参照してください。
      */
-    readonly editedPaths?: ReadonlySet<string>;
+    readonly editedPaths?: ReadonlyMap<string, number>;
     /**
      * 供給でユーザー編集の印を解除するか（既定は供給なら解除する）。
      *
@@ -3967,13 +4119,22 @@ declare interface ValueChangeOrigin {
     /** 変化の種別 */
     readonly kind: ValueChangeKind;
     /**
-     * この更新のうち、**実際に利用者が編集した**バインドデータの経路。
+     * この更新のうち、**実際に利用者が編集した**バインドデータの経路と、**その編集が
+     * 起きた時点**の通番。
      *
      * `change` / `input` の双方向コミットはフォーム全体の収集値を運ぶため、更新全体を
      * 「編集」として扱うと未編集の欄まで編集の権威を得てしまいます。編集された経路だけ
      * をここで示し、残りは `kind` の種別として判定します。
+     *
+     * 経路ごとに通番を持つのは、**コミットが起きた時点ではなく編集が起きた時点**で
+     * 判定するためです。`change` はフォーカスを外した時点で発火するため、編集より
+     * ずっと後になります。コミットの通番で主張すると、編集の後・コミットの前に要求
+     * された供給（`data-{event}-reset` など）が「編集の方が新しい」と判定されて棄却
+     * され、供給が無かったことになります（仕様「ユーザー編集と宣言バインドの権威」の
+     * 「供給は、その供給を起こした操作が起きた時点までの編集を解除し、それより後の
+     * 編集は残します」）。
      */
-    readonly editedPaths?: ReadonlySet<string>;
+    readonly editedPaths?: ReadonlyMap<string, number>;
 }
 
 /**
@@ -3982,7 +4143,7 @@ declare interface ValueChangeOrigin {
  * リリース時に `package.json` と揃えて更新します（`tests/version.test.ts` が
  * 一致を検査します）。
  */
-export declare const version = "0.43.0";
+export declare const version = "0.44.0";
 
 /**
  * すべてのレンダリングタスク（追従投入分を含む）の完了を待ちます。

package/package.json

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