haori 0.59.5 → 0.60.0

package/README.ja.md

@@ -2,7 +2,7 @@
 
 Haori.js は、HTML 属性を中心にして動的な UI を実現する軽量なライブラリです。JavaScript をほとんど書かずに、データバインディング、条件分岐、繰り返し処理、フォームの双方向バインディング、サーバー通信などを HTML 属性で宣言できます。
 
-バージョン: 0.59.5
+バージョン: 0.60.0
 
 ---
 
@@ -99,7 +99,7 @@ Haori.mount(document.body, {items: [{name: 'りんご'}, {name: 'みかん'}]});
 - `data-if` — 条件に応じて要素を表示 / 非表示
 - `data-each` — 配列を繰り返し表示（`data-each-key`, `data-each-arg`, `data-each-index` など）
 - `data-attr-xxx` — ブラウザが先に解釈する属性を安全に更新（`src`, `value` など）
-- `data-value-type` — 入力欄の収集値の型を宣言します（`boolean` / `number` / `string`）。`input` の値は常に文字列のため、真偽値を `type="hidden"` に載せると `"true"` という文字列で送られます。型を宣言すると、収集値・バインドデータ・送信ボディが API の期待する型になります（判定できない値は `null` になるため、未入力を `false` として送りません）。利用者に見せないだけの項目を、真偽値のために「表示しないチェックボックス」で代用する必要がなくなります。`checkbox` / `radio` / `file` と複数選択の `<select>` では無視します（開発モードで警告）。
+- `data-value-type` — 入力欄の収集値の型を宣言します（`boolean` / `number` / `string` / `lines`）。`input` の値は常に文字列のため、真偽値を `type="hidden"` に載せると `"true"` という文字列で送られます。型を宣言すると、収集値・バインドデータ・送信ボディが API の期待する型になります（判定できない値は `null` になるため、未入力を `false` として送りません）。利用者に見せないだけの項目を、真偽値のために「表示しないチェックボックス」で代用する必要がなくなります。`checkbox` / `radio` / `file` と複数選択の `<select>` では無視します（開発モードで警告）。`lines` は `<textarea>` だけで使え、改行で分けた行の配列で収集します（各行の前後の空白を除き、空の行は捨てます）。GET のクエリでは同じ名前のキーの繰り返しで送るため、1 欄に書いた複数の値を配列を受ける API へ送れます。
 - `data-fetch` — サーバーからデータを取得してバインド
 - `data-fetch-download` / `data-{event}-fetch-download` — 応答本文をファイルとして保存します（CSV エクスポート・PDF ダウンロード）。画面個別の JavaScript が要りません。ファイル名は応答の `Content-Disposition`（RFC 5987 の `filename*` を優先）→ 属性値 → URL 末尾の順で決まります。保存するのは 2xx だけで、それ以外は通常のフェッチと同じエラー振り分けに載るため、**ダウンロードの失敗が画面に出ます**。送信の組み立ては通常のフェッチと同じ（`data-{event}-form` / `-data` / `-fetch-method` / `-fetch-headers`）で、進行状況は `data-{event}-fetch-state` で参照できます。応答はバインドしません（本文は 1 度しか読めないため）。別オリジンでファイル名を使うにはサーバー側で `Access-Control-Expose-Headers: Content-Disposition` が必要です。
 - `data-import` — 外部 HTML を読み込んで挿入
@@ -132,6 +132,8 @@ Haori.mount(document.body, {items: [{name: 'りんご'}, {name: 'みかん'}]});
 - `data-click-no-disabled` / `data-click-defer` — 他ライブラリとの併用補助です。`no-disabled` はクリック手続き実行中に `disabled` 属性を付与せず実行します（Bootstrap collapse など disabled 要素を無視するライブラリ・CSS が動作し続けます。多重実行は内部マーカーで防止）。`defer` はクリック手続きを次フレーム（`requestAnimationFrame`／`setTimeout(0)`）で実行し、他ライブラリの同期 click ハンドラを先に完了させます。遅延後は `preventDefault()` できないため、`<a href>` や `type="submit"` への `defer` 併用は避けてください。
 - `data-{event}-click-await` — `data-{event}-click` が起動した手続きの完了を待ってから次の対象をクリックします。複数の更新を**宣言した順に直列で**送り（`#b, #a` のようにカンマで区切った対象は、文書の並びによらず書いた順に押します）、**いずれかが失敗した時点で後続を止めます**（HTTP エラー・通信の例外・検証エラー・確認ダイアログのキャンセル）。表示順を 2 件更新する並べ替えが JavaScript なしで書けます。止めた場合は呼び出し元の後続アクション（ダイアログ・トースト・リダイレクト）も実行しません。`data-{event}-if` が偽でスキップされた対象は失敗として扱いません。手続きが同期に起動しない対象（`data-click-defer`、クリックが発火しない `disabled` 要素）は待てず、その旨を記録します。
 - `data-{event}-error-click` / `-error-click-await` / `-error-close` / `-error-toast` / `-error-toast-level` / `-error-status` / `-error-no-message` / `-error-bind` — 取得が失敗したとき（2xx 以外の応答と通信の例外。認証ガードで遷移する 401 / 403 を除く）にだけ、別要素のクリック・ダイアログを閉じる・トーストをこの順に実行します。「取り直しが 404 なら、ダイアログを閉じて検索し直す」が JavaScript なしで書けます。`-error-status="404&410"` で対象のステータスを絞れます（宣言すると通信の例外は対象外）。実行しても手続きは失敗のままで、エラー表示も今までどおり行います（`-error-no-message` で止められます）。`-error-bind` を宣言すると、応答本文を表示する代わりに `data-{event}-bind` と同じ規則でバインドします（400 で返る検証結果を表に出すなど）。応答本文のサーバのメッセージは `_fetch.responseMessage` で参照でき、`data-click-error-toast="{{_fetch.responseMessage}}"` でトーストに出せます。`data-click-error-404-close` のようにステータスを付けた組（`-click` / `-click-await` / `-close` / `-toast` / `-toast-level` / `-no-message` / `-bind`）は、そのステータスの失敗でだけ、ステータスの付かない属性の代わりに使います。`-toast-level` と `-error-toast-level` には式を書けます（例: `{{_fetch.statusCode === 409 ? 'warning' : 'error'}}`）。`data-poll-*` と非イベントの `data-fetch` では、応答本文の表示を止める宣言（`data-fetch-error-no-message` / `data-poll-error-no-message` と、その `-error-status`・`-error-{ステータス}-no-message`）だけを使えます。
+- `data-{event}-clear-messages` — 取得が成功したときに、前回の失敗の表示を消します（範囲は失敗の表示と同じ）。値・バインドデータには触れないため、検索の条件を残したまま、前回の失敗の文言だけを消せます。ダウンロード（`-fetch-download`）では保存に成功した後に消します。
+- `data-{event}-scroll-error` — 失敗の表示の後に、最初のエラーへスクロールします。スクロール先は `data-message-level="error"` を持つ要素です。haori-bootstrap など表示を差し替えるライブラリは、表示した要素にこの属性を付けます。
 - `data-{event}-prevent`（例: `data-click-prevent`）— そのイベントでブラウザのネイティブなデフォルト動作（`type="submit"` ボタンのフォーム送信、`<a href>` の遷移など）を抑止します。`preventDefault()` はクリックの同期区間で呼ぶため `data-click-defer` と併用しても確実に抑止でき、`stopPropagation()` は呼ばないので他ライブラリのイベント伝播には影響しません。これにより `type="submit"` のまま `data-click-fetch` 等を付けても、ページ再読込なしに動作します。
 - `data-{event}-run`（例: `data-click-run`・`data-change-run`）— フェッチを伴わず任意の JavaScript をイベント時に実行します。属性値は `new Function` で実 JS として実行され（`-before-run`/`-after-run` と同方式）、`{{...}}` はレンダリング時に展開、`event` が引数で渡されます。本体が `false` を返すと `event.preventDefault()` を呼びます（`onclick="return false"` の慣習）。**セキュリティ**: 展開後の `{{...}}` は実行コードへ結合されるため、信頼できる値（数値 index・自前採番 ID 等）のみを入れてください。API レスポンスやユーザー入力などの信頼できない文字列を入れると任意コード実行（XSS）になり得ます。信頼できない値は `data-bind` 経由で渡し、呼び出す関数の内部で参照してください。
 

package/README.md

@@ -2,7 +2,7 @@
 
 Haori.js is a lightweight, HTML-first UI library that enables dynamic user interfaces primarily through HTML attributes. It lets you declare data bindings, conditional rendering, list rendering, form two-way binding, server fetches, and HTML imports without writing much JavaScript.
 
-Version: 0.59.5
+Version: 0.60.0
 
 ---
 
@@ -99,7 +99,7 @@ Haori.mount(document.body, {items: [{name: 'apple'}, {name: 'orange'}]});
 - `data-if` — show/hide an element based on a condition
 - `data-each` — repeat an element for items in an array (`data-each-key`, `data-each-arg`, `data-each-index`)
 - `data-attr-xxx` — safely update browser-interpreted attributes such as `src` and `value`
-- `data-value-type` — declare the collected type of an input (`boolean` / `number` / `string`). `input.value` is always a string, so a `type="hidden"` field carrying a boolean would otherwise be sent as `"true"`; declaring the type keeps the collected value, the binding data and the request body in the shape the API expects (a value that cannot be judged becomes `null`, so a blank field is never sent as `false`). Values you do not show the user no longer need a hidden checkbox to carry a boolean. Ignored (with a development-mode warning) on `checkbox` / `radio` / `file` and multi-select `<select>`, where the collected value is not a single scalar read from `value`.
+- `data-value-type` — declare the collected type of an input (`boolean` / `number` / `string` / `lines`). `input.value` is always a string, so a `type="hidden"` field carrying a boolean would otherwise be sent as `"true"`; declaring the type keeps the collected value, the binding data and the request body in the shape the API expects (a value that cannot be judged becomes `null`, so a blank field is never sent as `false`). Values you do not show the user no longer need a hidden checkbox to carry a boolean. Ignored (with a development-mode warning) on `checkbox` / `radio` / `file` and multi-select `<select>`, where the collected value is not a single scalar read from `value`. `lines` is for `<textarea>` only and collects an array of lines (each line trimmed, blank lines dropped); a GET query repeats the key for each line, so several values typed into one field reach an API that takes an array.
 - `data-fetch` — fetch data from a server and bind the result
 - `data-fetch-download` / `data-{event}-fetch-download` — save the response body as a file (CSV export, PDF download) with a declaration instead of screen-specific JavaScript. The filename comes from the response's `Content-Disposition` (RFC 5987 `filename*` wins), then the attribute value, then the last URL segment. Only 2xx responses are saved; anything else goes through Haori's normal error routing, so a failed download is visible on screen. The request is built exactly like a normal fetch (`data-{event}-form` / `-data` / `-fetch-method` / `-fetch-headers`) and progress is observable through `data-{event}-fetch-state`. The response is not bound (a body can only be read once). Cross-origin responses need `Access-Control-Expose-Headers: Content-Disposition` for the filename.
 - `data-import` — load external HTML and insert it
@@ -132,6 +132,8 @@ Event-driven actions:
 - `data-click-no-disabled` / `data-click-defer` — coexistence helpers for other libraries. `no-disabled` runs the click procedure without adding the `disabled` attribute (so libraries/CSS that ignore disabled elements, e.g. Bootstrap collapse, keep working; double execution is still prevented internally). `defer` runs the click procedure on the next frame (`requestAnimationFrame`/`setTimeout(0)`) so other libraries' synchronous click handlers complete first. Avoid `defer` on `<a href>` / `type="submit"` because the deferred procedure cannot `preventDefault()` the default action.
 - `data-{event}-click-await` — wait for the procedure started by `data-{event}-click` before clicking the next target, so several updates are sent **serially in declaration order** (comma-separated targets such as `#b, #a` are clicked in the written order, regardless of document order) and **the rest is stopped as soon as one fails** (HTTP error, network exception, validation error, or a cancelled confirmation). Row reordering that has to persist two display orders no longer needs JavaScript. When it stops, the calling procedure also skips its remaining actions (dialog, toast, redirect). A target skipped by a false `data-{event}-if` is not a failure. Targets whose procedure does not start synchronously (`data-click-defer`, or a `disabled` element that fires no click) cannot be waited for; that is logged.
 - `data-{event}-error-click` / `-error-click-await` / `-error-close` / `-error-toast` / `-error-toast-level` / `-error-status` / `-error-no-message` / `-error-bind` — run a click on another element, a dialog close and a toast, in that order, only when the fetch fails (a non-2xx response or a network exception, except 401 / 403 handled by the auth guard redirect). "If the reload returns 404, close the dialog and search again" no longer needs JavaScript. `-error-status="404&410"` narrows the statuses (once declared, network exceptions are excluded). The procedure still ends as a failure and the error display works as before, unless `-error-no-message` turns it off. `-error-bind` binds the response body by the same rules as `data-{event}-bind` instead of showing it (for example, a validation result returned with 400). The server's message in the response body is available as `_fetch.responseMessage`, so `data-click-error-toast="{{_fetch.responseMessage}}"` shows it in a toast. A group with a status in its name, such as `data-click-error-404-close` (`-click` / `-click-await` / `-close` / `-toast` / `-toast-level` / `-no-message` / `-bind`), replaces the attributes without a status only for failures with that status. `-toast-level` and `-error-toast-level` accept expressions (for example `{{_fetch.statusCode === 409 ? 'warning' : 'error'}}`). On `data-poll-*` and the non-event `data-fetch`, only the declarations that turn off the error display are read (`data-fetch-error-no-message` / `data-poll-error-no-message`, with their `-error-status` and `-error-{status}-no-message`).
+- `data-{event}-clear-messages` — on a successful fetch, clear the messages left by the previous failure (in the same scope the failure was shown in). Input values and binding data are untouched, so a search form keeps its conditions while the stale error disappears. With `-fetch-download` it clears after the file is saved.
+- `data-{event}-scroll-error` — after the error display, scroll to the first error: the first element with `data-message-level="error"`. Libraries that replace the display, such as haori-bootstrap, put this attribute on what they render.
 - `data-{event}-prevent` (e.g. `data-click-prevent`) — suppress the browser's native default action for the event (form submission for a `type="submit"` button, navigation for `<a href>`). `preventDefault()` is called synchronously during the click, so it works even together with `data-click-defer`, and `stopPropagation()` is never called (other libraries' event propagation is unaffected). This lets you keep `type="submit"` and still attach `data-click-fetch` etc. without the page reloading.
 - `data-{event}-run` (e.g. `data-click-run`, `data-change-run`) — run arbitrary JavaScript on the event without a fetch. The value is executed as real JS via `new Function` (like `-before-run`/`-after-run`), with `{{...}}` expanded at render time and `event` passed as an argument. Returning `false` calls `event.preventDefault()` (the `onclick="return false"` convention). **Security:** the expanded `{{...}}` is concatenated into executable code, so only interpolate trusted values (numeric indexes, IDs you control) — never untrusted strings (API/user input), which would run as code (XSS). Pass untrusted values via `data-bind` and read them inside the called function instead.