haori 0.26.2 → 0.27.0

package/dist/index.d.ts

@@ -582,6 +582,40 @@ 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 行の要素データ
+     * @param index 行のインデックス
+     * @returns 反映完了の Promise
+     */
+    private static applyRowFormValues;
     /**
      * リスト比較用のキーを生成します。
      *
@@ -642,7 +676,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;
     /** 属性名に対する属性情報のマップ */
@@ -995,6 +1029,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 +1075,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 +1094,7 @@ declare class ElementFragment extends Fragment {
      * @param targetName 反映先の属性名
      * @param value 生の属性値
      * @param syncValueProperty value 属性更新時に DOM property も同期するかどうか
+     * @param fromObserver MutationObserver 経由の書き戻しかどうか
      * @returns 属性更新の Promise
      */
     private setAttributeInternal;
@@ -1162,6 +1213,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 +1263,14 @@ export declare class Env {
  * 入力要素の値をフォームにバインドし、フォームのバインド値を入力要素に反映します。
  */
 export declare class Form {
+    /**
+     * 初期 `data-bind` からの入力欄復元を適用済みのフォーム要素。
+     *
+     * 復元は「そのフォームを初めてスキャンしたとき」の一度だけ行います。再スキャン
+     * （`data-if` の表示切替など）で繰り返すと、利用者が編集した入力欄を初期値へ
+     * 巻き戻してしまうためです。
+     */
+    private static readonly INITIAL_RESTORED_FORMS;
     /**
      * フォーム内にある入力エレメントの値をオブジェクトとして取得します。
      * data-form-object属性があると、そのエレメント内の値はオブジェクトとして処理されます。
@@ -1226,6 +1302,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]` かどうかを判定します。
      *
@@ -1262,6 +1430,49 @@ 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 行に設定する値のオブジェクト
+     * @param index 行のインデックス
+     * @returns 反映完了の Promise
+     */
+    static syncRowValues(row: ElementFragment, values: Record<string, unknown>, index: number): 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 型でない
      * チェックボックス、またはラジオボタン）かどうかを判定します。
@@ -1293,6 +1504,8 @@ export declare class Form {
      * @param values フラグメントに設定する値のオブジェクト
      * @param index 配列の場合のインデックス
      * @param force data-form-detach属性があるエレメントにも値を反映するかどうか
+     * @param emitEvents input/change イベントを発火するかどうか
+     * @param clearMissing values に無いキーの入力欄を空にするかどうか
      * @returns Promise（DOMの更新が完了したら解決される）
      */
     private static setPartValues;
@@ -1927,7 +2140,7 @@ declare class TextFragment extends Fragment {
     evaluate(): Promise<void>;
 }
 
-export declare const version = "0.26.2";
+export declare const version = "0.27.0";
 
 /**
  * すべてのレンダリングタスク（追従投入分を含む）の完了を待ちます。

package/package.json

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