haori 0.26.2 → 0.28.0

package/dist/index.d.ts

@@ -60,6 +60,16 @@ export declare class Core {
     private static readonly EVALUATE_ALL_EXCLUDED_ATTRIBUTE_SUFFIXES;
     /** 属性内プレースホルダ検出用の正規表現 */
     private static readonly ATTRIBUTE_PLACEHOLDER_REGEX;
+    /**
+     * 行スコープ判定で「属性値そのものが式」とみなす `data-*` 属性のサフィックス。
+     * `{{...}}` を伴わずに式を書く属性だけを列挙する。
+     */
+    private static readonly ROW_LOCAL_EXPRESSION_ATTRIBUTES;
+    /**
+     * 行スコープ判定で「属性値が式ではない」とみなす `data-*` 属性のサフィックス。
+     * ここに無い `data-*` 属性は、行の外を参照し得るものとして安全側に扱う。
+     */
+    private static readonly ROW_LOCAL_STATIC_ATTRIBUTES;
     /** data-fetch の自動再評価状態 */
     private static readonly REACTIVE_FETCH_STATES;
     /** data-import の自動再評価状態 */
@@ -473,6 +483,16 @@ export declare class Core {
      * @return 差分更新完了の Promise
      */
     private static performEachUpdate;
+    /**
+     * 差分更新が不要な `data-each` の既存行について、子孫の再評価だけを行います。
+     *
+     * 行スコープの値だけで描画が決まるテンプレートでは、行の要素データが同値である
+     * 限り描画結果も変わらないため何もしません。
+     *
+     * @param fragment `data-each` コンテナのフラグメント
+     * @returns 再評価完了の Promise
+     */
+    private static reevaluateEachRows;
     /**
      * data-each 属性値を仕様に従って配列へ正規化します。
      *
@@ -488,6 +508,51 @@ export declare class Core {
      * @returns 省略可能なら true
      */
     private static canSkipUnchangedNestedEach;
+    /**
+     * `data-each` のテンプレートが行スコープの値だけで描画できるかどうかを返します。
+     *
+     * 行スコープとは `data-each-arg` と `data-each-index` で公開される名前です。
+     * テンプレート内の式がこの名前だけを参照している場合、要素データが同値なら
+     * 描画結果も変わらないため、行の子孫の再評価を省略できます。逆に行の外にある
+     * 名前（別の一覧や親スコープの値）を参照している場合は、要素データが同値でも
+     * 再評価が必要です。
+     *
+     * 判定できない場合はすべて「行スコープ外」（= 再評価が必要）へ倒します。
+     * 具体的には、テンプレート未確定、`data-each-arg` の無い構成（要素データのキーが
+     * 行スコープへ直接展開されるため参照名を静的に決められない）、解析できない式、
+     * 既知でない `data-*` 属性が該当します。
+     *
+     * 判定結果はテンプレート単位で不変なのでフラグメントへ保存して再利用します。
+     *
+     * @param fragment `data-each` コンテナのフラグメント
+     * @returns 行スコープの値だけで描画できるなら true
+     */
+    private static isRowLocalEachTemplate;
+    /**
+     * フラグメントとその子孫の式が、指定した名前だけを参照しているかを判定します。
+     *
+     * @param fragment 判定対象フラグメント
+     * @param scopeNames 参照してよい名前の集合
+     * @returns 指定した名前だけを参照しているなら true
+     */
+    private static isRowLocalSubtree;
+    /**
+     * 式の集合が、指定した名前だけを参照しているかを判定します。
+     *
+     * 参照名を取り出せなかった式は安全側（= 指定外を参照している）として扱います。
+     *
+     * @param expressions 判定対象の式
+     * @param scopeNames 参照してよい名前の集合
+     * @returns 指定した名前だけを参照しているなら true
+     */
+    private static areExpressionsRowLocal;
+    /**
+     * 文字列から `{{式}}` の中身を取り出します。
+     *
+     * @param raw 評価前の文字列
+     * @returns 式の一覧（出現順）
+     */
+    private static extractInterpolations;
     /**
      * data-derive subtree の入力が同値で、保守条件も満たす場合に
      * 子走査を省略できるかどうかを返します。
@@ -532,6 +597,19 @@ export declare class Core {
      * @returns プロファイル
      */
     private static getOrCreateDerivedSubtreeProfile;
+    /**
+     * 要素の `id` 属性を安全に取得します。
+     *
+     * `<form>` は配下の入力要素の `name` が同名の組み込みプロパティを上書きします
+     * （HTML 仕様の named access）。そのため `<input name="id">` を含むフォームでは
+     * `form.id` が文字列ではなく input 要素を返し、文字列として扱うと
+     * `[object HTMLInputElement]` になったり `.trim()` で TypeError になります。
+     * 属性から直接読み取ってこの上書きを避けます。
+     *
+     * @param element 対象要素
+     * @returns `id` 属性の値。指定が無ければ空文字
+     */
+    private static resolveElementId;
     /**
      * data-derive subtree host の識別子を作成します。
      *
@@ -582,6 +660,39 @@ export declare class Core {
      * @param newList 新しいリスト
      */
     private static updateDiff;
+    /**
+     * 再利用した `data-each` の行を、新しい並び順の位置へ移動します。
+     *
+     * `insertTargets` は現在の子並びを表す作業用配列で、移動に合わせて更新します。
+     * すでに目的の位置にある場合は何もしません。
+     *
+     * @param parent `data-each` コンテナのフラグメント
+     * @param row 移動対象の行フラグメント
+     * @param insertTargets 現在の子並び（この呼び出しで更新される）
+     * @param targetIndex 移動先のインデックス
+     * @returns 移動完了の Promise
+     */
+    private static repositionEachRow;
+    /**
+     * `data-each` の行の入力欄へ、その行の要素データを反映します。
+     *
+     * `data-each` と `data-form-list` を同一要素へ指定した「編集可能な繰り返し行」では、
+     * 行内の入力欄は要素データのキーと `name` で対応します。`Core.setBindingData()` の
+     * 逆方向同期（`Form.syncValues`）は `Core.evaluateAll`（= 行生成）より**前**に走る
+     * ため、その更新で生成・更新された行には値が入りません。ここで行単位に補います。
+     *
+     * 呼び出すのは「新規生成した行」と「要素データが変化した再利用行」だけです。
+     * 変化していない行へ再適用すると、描画の待ち時間中に利用者が編集した入力欄を
+     * 古い値で巻き戻す競合になります（0.26.1 で修正した問題と同種）。行の途中へ要素を
+     * 挿入すると以降の行は別の要素データを担当することになるため、変化した再利用行への
+     * 適用は必要です（これを省くと挿入位置以降の入力値が前の行のまま残ります）。
+     *
+     * @param parent `data-each` コンテナのフラグメント
+     * @param row 行のフラグメント
+     * @param item 行の要素データ
+     * @returns 反映完了の Promise
+     */
+    private static applyRowFormValues;
     /**
      * リスト比較用のキーを生成します。
      *
@@ -642,7 +753,7 @@ declare class ElementFragment extends Fragment {
     /** HTML 真偽属性名のセット */
     private static readonly BOOLEAN_ATTRIBUTES;
     /** inputイベントを発生させるタイプ */
-    private readonly INPUT_EVENT_TYPES;
+    private static readonly INPUT_EVENT_TYPES;
     /** 子フラグメントのリスト */
     private readonly children;
     /** 属性名に対する属性情報のマップ */
@@ -679,6 +790,11 @@ declare class ElementFragment extends Fragment {
     private displayPriority;
     /** each用のテンプレート */
     private template;
+    /**
+     * each テンプレートが行スコープの値だけで描画できるかどうか（未判定は null）。
+     * テンプレートは差し替えられるまで不変なので、判定結果を保持して再利用する。
+     */
+    private rowLocalTemplate;
     /** each比較用のキー */
     private listKey;
     /** 直近に描画した each 行の入力署名 */
@@ -697,6 +813,13 @@ declare class ElementFragment extends Fragment {
     private skipMutationAttributes;
     /** 値変更スキップフラグ（更新イベントによる無限ループ対応） */
     private skipChangeValue;
+    /** ユーザー編集の通し番号の発番元（全フラグメント共通、単調増加）。 */
+    private static userEditCounter;
+    /**
+     * この入力欄を最後にユーザーが編集したときの通し番号（未編集は 0）。
+     * 「ある時点より後に編集されたか」を比較するために使う。
+     */
+    private userEditSequence;
     /**
      * エレメントフラグメントのコンストラクタ。
      * アトリビュートや子フラグメントの作成も行います。
@@ -873,6 +996,18 @@ declare class ElementFragment extends Fragment {
      * @param template フラグメントのテンプレート
      */
     setTemplate(template: ElementFragment | null): void;
+    /**
+     * `data-each` テンプレートが行スコープの値だけで描画できるかの判定結果を返します。
+     *
+     * @returns 判定済みなら真偽値、未判定なら null
+     */
+    getRowLocalTemplate(): boolean | null;
+    /**
+     * `data-each` テンプレートが行スコープの値だけで描画できるかの判定結果を保存します。
+     *
+     * @param rowLocal 行スコープだけで描画できるなら true
+     */
+    setRowLocalTemplate(rowLocal: boolean | null): void;
     /**
      * 比較用リストキーを設定します。
      *
@@ -979,6 +1114,31 @@ declare class ElementFragment extends Fragment {
      * @returns 入力エレメントの値
      */
     getValue(): string | number | boolean | string[] | null;
+    /**
+     * 現在のユーザー編集の通し番号を返します。
+     *
+     * 通信を開始した時点の番号を控えておき、応答が届いたときに各入力欄の
+     * `getUserEditSequence()` と比べることで「リクエスト送出後に編集されたか」を
+     * 判定できます。
+     *
+     * @returns 直近に発番したユーザー編集の通し番号（未発番なら 0）
+     */
+    static currentUserEditSequence(): number;
+    /**
+     * この入力欄がユーザーに編集されたことを記録します。
+     *
+     * `change` / `input` の委譲で内部値を DOM から同期した直後に呼び出します。
+     * プログラムからの値反映（バインド由来の書き戻しなど）では呼び出しません。
+     *
+     * @returns 戻り値はありません。
+     */
+    markUserEdit(): void;
+    /**
+     * この入力欄を最後にユーザーが編集したときの通し番号を返します。
+     *
+     * @returns ユーザー編集の通し番号（未編集なら 0）
+     */
+    getUserEditSequence(): number;
     /**
      * 内部の値をクリアします。エレメントのvalue値は変化しません。
      */
@@ -995,6 +1155,21 @@ declare class ElementFragment extends Fragment {
      * @returns 正規化後の値（`type="number"` なら数値または null）
      */
     private normalizeValueForElement;
+    /**
+     * `value` の宣言バインド（テンプレート式・`data-attr-value`）で DOM プロパティと
+     * 内部値を同期する対象要素かどうかを判定します。
+     *
+     * `value` 属性の反映だけでは `element.value` や内部値（値収集や式評価が参照する値）が
+     * 更新されないため、これらの要素では属性に加えてプロパティも揃えます。
+     * `type="hidden"` は利用者が編集できず送信される値を持つため対象に含めます
+     * （`INPUT_EVENT_TYPES` は `input` イベント発火の可否を決める別目的の一覧なので、
+     * そちらへは追加しません）。checkbox / radio の `value` は送信値であってチェック
+     * 状態ではないため対象外です（状態は `checked` の同期で扱います）。
+     *
+     * @param element 判定対象のエレメント
+     * @returns 同期対象の場合true
+     */
+    static isValuePropertyTarget(element: Element): element is HTMLInputElement | HTMLTextAreaElement | HTMLSelectElement;
     /**
      * 内部の値をDOMの値と同期します。
      * changeイベント時など、DOM値が変更された後に呼び出されます。
@@ -1026,6 +1201,7 @@ declare class ElementFragment extends Fragment {
      * @param rawName 生の属性名
      * @param targetName 反映先の属性名
      * @param value 生の属性値
+     * @param fromObserver MutationObserver 経由の書き戻しかどうか
      * @returns 属性更新の Promise
      */
     setAliasedAttribute(rawName: string, targetName: string, value: string | null, fromObserver?: boolean): Promise<void>;
@@ -1044,6 +1220,7 @@ declare class ElementFragment extends Fragment {
      * @param targetName 反映先の属性名
      * @param value 生の属性値
      * @param syncValueProperty value 属性更新時に DOM property も同期するかどうか
+     * @param fromObserver MutationObserver 経由の書き戻しかどうか
      * @returns 属性更新の Promise
      */
     private setAttributeInternal;
@@ -1162,6 +1339,23 @@ declare class ElementFragment extends Fragment {
 export declare class Env {
     private static _prefix;
     private static _runtime;
+    private static _strictBind;
+    /**
+     * 厳格バインドモードが有効かどうかを取得します。
+     *
+     * 有効な場合、バインドに無いキーの参照を検出した時点で `error` ログを出力します。
+     * 無効（既定）の場合は正常系として扱い、開発モードで集約警告のみを出します。
+     *
+     * @returns 厳格バインドモードなら true。
+     */
+    static get strictBind(): boolean;
+    /**
+     * 厳格バインドモードを設定します。
+     *
+     * @param enabled 有効にする場合は true。
+     * @return 戻り値はありません。
+     */
+    static setStrictBind(enabled: boolean): void;
     /**
      * 実行モードを取得します。
      *
@@ -1195,6 +1389,14 @@ export declare class Env {
  * 入力要素の値をフォームにバインドし、フォームのバインド値を入力要素に反映します。
  */
 export declare class Form {
+    /**
+     * 初期 `data-bind` からの入力欄復元を適用済みのフォーム要素。
+     *
+     * 復元は「そのフォームを初めてスキャンしたとき」の一度だけ行います。再スキャン
+     * （`data-if` の表示切替など）で繰り返すと、利用者が編集した入力欄を初期値へ
+     * 巻き戻してしまうためです。
+     */
+    private static readonly INITIAL_RESTORED_FORMS;
     /**
      * フォーム内にある入力エレメントの値をオブジェクトとして取得します。
      * data-form-object属性があると、そのエレメント内の値はオブジェクトとして処理されます。
@@ -1226,6 +1428,98 @@ export declare class Form {
      * @returns boolean チェックボックスの場合 true
      */
     private static isBooleanCheckbox;
+    /** ラジオグループのスコープへ割り当てた識別番号 */
+    private static readonly GROUP_SCOPE_IDS;
+    /** ラジオグループのスコープ識別番号の連番 */
+    private static groupScopeSequence;
+    /**
+     * 入力要素の収集キーを解決します。
+     *
+     * `data-form-name` があればそれを収集キーとし、無ければ `name` 属性を使います。
+     * ラジオボタンのように DOM の `name` がグループ化の意味を持つ場合に、収集キーと
+     * DOM の `name` を分けるために使います。
+     *
+     * @param fragment 対象フラグメント
+     * @returns 収集キー。どちらも無い場合は null
+     */
+    static resolveFieldName(fragment: ElementFragment): unknown;
+    /**
+     * `data-form-name` の初期化を行います。
+     *
+     * 収集キーが空になる指定を開発モードで警告し、ラジオボタンにはグループ用の
+     * DOM `name` を生成します。
+     *
+     * HTML のラジオグループは「同じフォームオーナー内の同名要素」で構成されるため、
+     * `data-form-list` の行内で同じ `name` を使うと行をまたいで排他になり、1 行しか
+     * 選択を保持できません。収集キーを `data-form-name` で宣言した場合は、DOM の
+     * `name` を行ごとにユニークな値へ生成してグループを行単位に分けます。
+     *
+     * 作者が `name` を書いている場合は尊重して生成しません（行をまたぐグループを
+     * 意図している場合があるため）。自動生成した `name` は内部マーカーで区別し、
+     * 行の複製で引き継がれたものは作り直します。
+     *
+     * 処理が不要な場合は Promise を返しません。要素初期化の共通経路から呼ばれるため、
+     * 対象外の要素で Promise を挟むと初期化の非同期段数が全要素で増えてしまいます。
+     *
+     * @param fragment 対象フラグメント
+     * @returns 属性設定の Promise。処理が不要な場合は undefined
+     */
+    static prepareFormName(fragment: ElementFragment): Promise<void> | void;
+    /**
+     * ラジオグループのスコープとなるフラグメントを解決します。
+     *
+     * `data-form-list` のコンテナ直下の要素（= 行）が祖先にあればその行を、無ければ
+     * 最近傍のフォーム（`<form>` または `data-form`）をスコープとします。行の外では
+     * 通常の HTML と同じくフォーム単位のグループになります。
+     *
+     * @param fragment 対象フラグメント
+     * @returns スコープとなるフラグメント
+     */
+    private static resolveGroupScope;
+    /**
+     * ラジオグループのスコープへ識別番号を割り当てます。
+     *
+     * @param scope スコープとなるフラグメント
+     * @returns スコープの識別番号
+     */
+    private static resolveGroupScopeId;
+    /**
+     * 値または状態が宣言バインドで決まる入力かどうかを判定します。
+     *
+     * 属性にテンプレート式を書いた場合、または対応する `data-attr-*` を持つ場合は、
+     * その値・状態の権威はバインドの評価結果にあります。値収集側から空で上書きして
+     * はいけません。
+     *
+     * 判定する属性は要素の種類で変わります。checkbox / radio の `value` は送信値で
+     * あってチェック状態ではないため、`value` ではなく `checked` を見ます（`value` で
+     * 判定すると、送信値をテンプレート式で決めているだけのチェックボックスが解除
+     * されなくなり、前の行のチェック状態が残る）。`<select>` は自身の `value` に加えて、
+     * 配下の `<option>` が `selected` を宣言している場合も対象とします。
+     *
+     * @param fragment 対象フラグメント
+     * @returns 宣言バインドで値または状態が決まる場合 true
+     */
+    private static isDeclarativeStateBound;
+    /**
+     * 指定した属性が宣言バインド（テンプレート式または `data-attr-*`）かどうかを
+     * 判定します。
+     *
+     * @param fragment 対象フラグメント
+     * @param name 属性名
+     * @returns 宣言バインドの場合 true
+     */
+    private static hasDeclarativeBinding;
+    /**
+     * `<select>` 配下の `<option>` が選択状態を宣言バインドしているかどうかを
+     * 判定します。
+     *
+     * `name` を持つ select の選択状態を `data-attr-selected` などで宣言している場合、
+     * 選択の権威は option 側の式にあります。
+     *
+     * @param element 対象の select エレメント
+     * @returns いずれかの option が selected を宣言している場合 true
+     */
+    private static hasDeclarativeSelectedOption;
     /**
      * `input[type=file]` かどうかを判定します。
      *
@@ -1233,12 +1527,29 @@ export declare class Form {
      * @returns `input[type=file]` の場合 true
      */
     private static isFileInput;
+    /**
+     * 指定した基準より後にユーザーが編集した入力欄の値だけを収集します。
+     *
+     * 収集結果は `getValues()` と同じ入れ子構造になりますが、編集されていない
+     * 入力欄のキーは含みません。`data-form-list` の行は位置がずれないよう、編集の
+     * 無い行も空オブジェクトで場所を確保します。
+     *
+     * 飛行中の通信の応答をバインドする直前に、その通信を開始した後の編集だけを
+     * 上書きし直す用途で使います。
+     *
+     * @param fragment 対象のElementFragment
+     * @param baseline ユーザー編集の通し番号の基準（これより大きいものが対象）
+     * @returns 編集された入力欄だけを含む値のオブジェクト
+     */
+    static getValuesEditedAfter(fragment: ElementFragment, baseline: number): Record<string, unknown>;
     /**
      * フォーム内の各入力エレメントから値を取得し、オブジェクトとして返します。
      * 入力エレメントのname属性、data-form-object属性、data-form-list属性に基づいて値を整理します。
      *
      * @param fragment 対象のElementFragment
      * @param values オブジェクトに追加する値のオブジェクト
+     * @param minUserEditSequence 指定した場合、この通し番号より後にユーザーが編集した
+     *     入力欄だけを収集する（`data-form-list` の行位置は空オブジェクトで保持する）
      * @returns values と同じオブジェクト
      */
     private static getPartValues;
@@ -1262,6 +1573,48 @@ export declare class Form {
      * @returns Promise（DOMの更新が完了したら解決される）
      */
     static syncValues(form: ElementFragment, values: Record<string, unknown>, force?: boolean): Promise<void>;
+    /**
+     * `data-form-list` の 1 行分の入力欄へ、その行の値をイベントなしで反映します。
+     *
+     * `data-each` が新しく生成した行に対して呼び出します。フォーム全体への逆方向同期
+     * （`syncValues()`）は `Core.setBindingData()` の中で `data-each` の行生成より**前**に
+     * 走るため、その更新で生成された行には値が入りません。行単位でここを補います。
+     *
+     * @param row 行のElementFragment
+     * @param values 行に設定する値のオブジェクト
+     * @returns 反映完了の Promise
+     */
+    static syncRowValues(row: ElementFragment, values: Record<string, unknown>): Promise<void>;
+    /**
+     * バインディングデータから、入力欄へ書き戻す対象の値を切り出します。
+     *
+     * `data-form-arg` が指定されている場合はそのキー配下だけを対象とし、キーが
+     * オブジェクトでなければ空オブジェクトを返します（フォーム外のキーを入力欄へ
+     * 書き戻さないため）。指定が無ければバインディングデータ全体が対象です。
+     *
+     * @param form フォームのElementFragment
+     * @param data 対象のバインディングデータ
+     * @returns 入力欄へ書き戻す値
+     */
+    static resolveSyncValues(form: ElementFragment, data: Record<string, unknown>): Record<string, unknown>;
+    /**
+     * 初期 `data-bind` の値を配下の入力欄へ反映します。
+     *
+     * `Core.setBindingData()` 経由の逆方向同期は `data-bind` 属性を**更新した**ときに
+     * だけ走るため、初期スキャンで読み込んだ `data-bind` は入力欄へ反映されません。
+     * その結果、`name` に対応する値を持つ `<select>` やチェックボックスが未選択のまま
+     * 残り、最初の `change` で全項目を収集した際に空値として確定して他項目の値を失う
+     * 問題がありました。本メソッドは初回スキャン時に一度だけ逆方向同期を適用します。
+     *
+     * 対象は `<form>` 要素のうち `data-bind` を持つものだけです（`Core.setBindingData()`
+     * の逆方向同期と同じ範囲）。`data-bind` に含まれないキーの入力欄は
+     * `setPartValues()` の規則により既存値が維持されるため、HTML の `value` 属性で
+     * 与えた初期値は保たれます。
+     *
+     * @param root 走査の起点要素
+     * @returns 反映完了の Promise
+     */
+    static restoreInitialValues(root: HTMLElement): Promise<void>;
     /**
      * 値による上書きをグループ単位で扱うべき入力要素（boolean 型でない
      * チェックボックス、またはラジオボタン）かどうかを判定します。
@@ -1291,8 +1644,11 @@ export declare class Form {
      *
      * @param fragment 対象フラグメント
      * @param values フラグメントに設定する値のオブジェクト
-     * @param index 配列の場合のインデックス
      * @param force data-form-detach属性があるエレメントにも値を反映するかどうか
+     * @param emitEvents input/change イベントを発火するかどうか
+     * @param clearMissing values に無いキーの入力欄を空にするかどうか
+     * @param listCursors 同名リストの出現位置。同じ `values` を共有する範囲で
+     *     収集キーごとに何件目かを数え、配列の対応する要素を配るために使う
      * @returns Promise（DOMの更新が完了したら解決される）
      */
     private static setPartValues;
@@ -1912,6 +2268,15 @@ declare class TextFragment extends Fragment {
      * @returns 評価式を含むなら true
      */
     hasDynamicContent(): boolean;
+    /**
+     * 評価前の生のテキストを返します。
+     *
+     * `{{式}}` を展開する前の宣言そのものです。テンプレートが参照している識別子を
+     * 静的に調べる用途で使います。
+     *
+     * @returns 評価前のテキスト
+     */
+    getRawText(): string;
     /**
      * コンテンツを更新します。
      *
@@ -1927,7 +2292,7 @@ declare class TextFragment extends Fragment {
     evaluate(): Promise<void>;
 }
 
-export declare const version = "0.26.2";
+export declare const version = "0.28.0";
 
 /**
  * すべてのレンダリングタスク（追従投入分を含む）の完了を待ちます。

package/package.json

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