haori 0.37.1 → 0.38.0

package/README.ja.md

@@ -2,7 +2,7 @@
 
 Haori.js は、HTML 属性を中心にして動的な UI を実現する軽量なライブラリです。JavaScript をほとんど書かずに、データバインディング、条件分岐、繰り返し処理、フォームの双方向バインディング、サーバー通信などを HTML 属性で宣言できます。
 
-バージョン: 0.37.1
+バージョン: 0.38.0
 
 ---
 
@@ -134,9 +134,13 @@ Haori.mount(document.body, {items: [{name: 'りんご'}, {name: 'みかん'}]});
 - `haori:eachupdate` — `data-each` のリスト差分完了時に `data-each` 要素で発火します。発火時点で追加・削除・並べ替えされた全行が DOM に反映され、各行の内容（`{{...}}`）も描画済みのため、描画完了の検知に利用できます（`detail`: `added`・`removed`・`order`・`total`）。
 - `haori:bindcomplete` — `data-*-bind` / `data-*-bind-arg` によるバインドと、対象要素配下の再評価が完了した後に対象要素で発火します（`detail.bindArg`）。
 - `haori:show` / `haori:hide` — `data-if` 要素の表示・非表示時に発火します。
+- `haori:rowadd` / `haori:rowremove` / `haori:rowmove` — `data-each` の差分更新で行ごとに行要素で発火します（`detail`: `key`・`index`・`item` / `key`・`index` / `key`・`from`・`to`）。伝播するためコンテナや `document` でも購読できます。`rowadd` は行内容の描画後、`rowremove` は行が DOM から外れる**前**に発火します。
+- `haori:ready` — 初期化完了時に `document` で発火します（`detail.version`）。購読はライブラリの読み込みより前に登録してください。
 
 式中では予約名前空間 `haori` の組み込みヘルパーを利用できます。`haori.date(value, format?, timeZone?)` は ISO 文字列・エポックミリ秒・`Date` を整形し（既定 `yyyy/MM/dd HH:mm`。`timeZone` 省略時はローカル時刻、`'Asia/Tokyo'` 等の IANA タイムゾーン名を渡すとその地域の時刻）、`haori.number(value, decimals?)` は桁区切り付きで数値を整形、`haori.range(start, end?, step?)` は整数配列を生成し（終端排他）、`haori.pages(totalPages, current, {window?, boundary?})` は省略記号付きの番号ページ列を生成します（`current` は 0 始まり。各要素は `{page, label, active, ellipsis}` を持ち `label` は `page + 1`）。月別 UI 向けに、`haori.monthAdd(value, delta)` は `YYYY-MM` 形式の年月へ月数を加算し（`Date` を介さない整数演算でタイムゾーン非依存。不正な入力は空文字）、`haori.monthRange(count, base?)` は基準月から降順に `count + 1` 個の `{targetMonth, label}` を返します（`base` 省略時は現在月）。ページ件数表示向けに、`haori.pageSummary(page, visibleCount?)` は Spring の `Page` 相当（`number`・`size`・`totalElements`／`totalCount`）から `{start, end, total, empty}` を計算します。`haori.findBy(array, key, value)` は配列から `item[key]` が `value` に一致する最初の要素（文字列化比較）を返し、無ければ `null` を返します。`haori.sum(array, key?)` は配列の数値合計を返します（`key` 省略時は要素自体、指定時は `item[key]`、数値化できない値は無視、非配列は `0`）。`haori.distinct(array, key?)` は重複を取り除いた配列を返し（`key` 省略時は要素自体、指定時は `item[key]` で判定。文字列化比較で最初の出現を保持）、`haori.groupBy(array, key)` は `item[key]` ごとに `{key, items}` の配列へ分けます（出現順）。明細を 1 件 1 行へまとめたり、入れ子の `data-each` でグループ表示したりするのに使えます。これにより番号ページネーション（`data-each="haori.pages(totalPages, number, {window: 2})"`）・値の整形（`{{ haori.date(lastUpdatedAt, 'yyyy/MM/dd HH:mm') }}`）・集計行（`{{ haori.number(haori.sum(rows, 'total')) }}`）を宣言的に書けます。同じ関数は `Haori.date` / `Haori.number` / `Haori.range` / `Haori.pages` / `Haori.monthAdd` / `Haori.monthRange` / `Haori.pageSummary` / `Haori.findBy` / `Haori.sum` / `Haori.distinct` / `Haori.groupBy` としても公開されています。`haori` は予約名のため、同名の `data-bind` キーを与えても式中では組み込みが優先されます。
 
+`<script src>`（iife）で読み込んだときのグローバル `Haori` は `Haori` クラスそのものです。`Haori.addErrorMessage(...)` のようにクラス API を直接呼び出せ、`Core` や `Env` などは `Haori.Core` / `Haori.Env` として参照します（`Haori.Haori` は自己参照のため、0.37.1 以前の書き方も動作します）。
+
 JS からバインドデータを読むには `Haori.Core.getBindingData(element, {resolved?})` を使います。既定では要素自身の生バインドデータ（無ければ `null`）、`resolved: true` で継承を解決済みのスコープを返します（`setBindingData` の対となる読み取り API）。
 
 テンプレート式では、プロパティアクセス、動的インデックスを含むブラケットアクセス、optional chaining、三項演算子、配列 `map` / `filter` のアロー関数、spread を伴う呼び出しなどの安全な構文を利用できます。一方で、グローバルオブジェクト、`eval` や `arguments`、`constructor`、`__proto__`、`prototype`、`Reflect`、`Object` などの脱出経路は使用できません。`Object` がブロックされるため、`Object.assign` の代わりにスプレッド構文 `{...a, ...b}` を使ってください。ブロックされた識別子を式で参照すると、コンソールに `blocked identifier(s): …` という警告が出力されます。

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.37.1
+Version: 0.38.0
 
 ---
 
@@ -134,9 +134,13 @@ Lifecycle events:
 - `haori:eachupdate` — fired on the `data-each` element after a list diff completes; all added/removed/reordered rows are in the DOM and their content (`{{...}}`) is rendered by the time it fires, so it can be used to detect render completion (`detail`: `added`, `removed`, `order`, `total`).
 - `haori:bindcomplete` — fired on the target element after a `data-*-bind` / `data-*-bind-arg` bind and the subsequent re-evaluation of its subtree complete (`detail.bindArg`).
 - `haori:show` / `haori:hide` — fired when a `data-if` element becomes shown or hidden.
+- `haori:rowadd` / `haori:rowremove` / `haori:rowmove` — fired on each row element during a `data-each` list diff (`detail`: `key`, `index`, `item` / `key`, `index` / `key`, `from`, `to`). They bubble, so the container or `document` can subscribe. `rowadd` fires after the row's content is rendered; `rowremove` fires **before** the row leaves the DOM.
+- `haori:ready` — fired on `document` once initialization completes (`detail.version`). Register the listener before the library script so it is not missed.
 
 Built-in helpers are available in expressions under the reserved namespace `haori`: `haori.date(value, format?, timeZone?)` formats an ISO string / epoch ms / `Date` (default `yyyy/MM/dd HH:mm`; local time, or a given IANA time zone such as `'Asia/Tokyo'` when `timeZone` is passed), `haori.number(value, decimals?)` formats numbers with grouping, `haori.range(start, end?, step?)` builds an integer array (end-exclusive), and `haori.pages(totalPages, current, {window?, boundary?})` builds an ellipsis-aware page list (`current` is 0-based; each item exposes `{page, label, active, ellipsis}` with `label` = `page + 1`). For month-based UIs, `haori.monthAdd(value, delta)` adds months to a `YYYY-MM` string (timezone-safe integer math; invalid input returns `''`) and `haori.monthRange(count, base?)` builds a descending list of `count + 1` `{targetMonth, label}` items (`base` defaults to the current month). For pagination summaries, `haori.pageSummary(page, visibleCount?)` turns a Spring-style `Page` (`number`, `size`, `totalElements` / `totalCount`) into `{start, end, total, empty}`. `haori.findBy(array, key, value)` returns the first array element whose `item[key]` matches `value` (stringified comparison), or `null` when none match. `haori.sum(array, key?)` returns the numeric total of an array (the elements themselves when `key` is omitted, or `item[key]`; non-numeric values are ignored; non-arrays yield `0`). `haori.distinct(array, key?)` removes duplicates (by the element itself, or by `item[key]`; stringified comparison, first occurrence kept) and `haori.groupBy(array, key)` groups into `{key, items}` entries (first-seen order) — handy for collapsing detail rows into one row per key or rendering grouped lists with nested `data-each`. These let you build number pagination (`data-each="haori.pages(totalPages, number, {window: 2})"`), format values (`{{ haori.date(lastUpdatedAt, 'yyyy/MM/dd HH:mm') }}`), and total rows (`{{ haori.number(haori.sum(rows, 'total')) }}`) declaratively. The same functions are exposed as `Haori.date` / `Haori.number` / `Haori.range` / `Haori.pages` / `Haori.monthAdd` / `Haori.monthRange` / `Haori.pageSummary` / `Haori.findBy` / `Haori.sum` / `Haori.distinct` / `Haori.groupBy`. `haori` is reserved: a `data-bind` key of the same name does not shadow the built-ins inside expressions.
 
+When loaded via `<script src>` (iife), the global `Haori` **is** the `Haori` class: call class APIs directly (`Haori.addErrorMessage(...)`) and reach the other classes as `Haori.Core` / `Haori.Env`. `Haori.Haori` is a self-reference, so code written for 0.37.1 and earlier keeps working.
+
 To read binding data from JS, use `Haori.Core.getBindingData(element, {resolved?})` — by default it returns the element's own raw binding data (or `null`), and with `resolved: true` it returns the scope with inheritance resolved (the read counterpart to `setBindingData`).
 
 Template expressions support safe JavaScript-like syntax such as property access, bracket access with dynamic indexes, optional chaining, ternary expressions, and method chains including array `map`/`filter` with arrow functions and spread calls. Access to global objects, `eval` or `arguments`, and prototype escape paths such as `constructor`, `__proto__`, `prototype`, `Reflect`, or `Object` is blocked. Because `Object` is blocked, use spread syntax `{...a, ...b}` instead of `Object.assign`; when a blocked identifier is referenced in an expression, a `blocked identifier(s): …` warning is logged to the console.