haori 0.20.1 → 0.22.0

package/README.ja.md

@@ -2,7 +2,7 @@
 
 Haori.js は、HTML 属性を中心にして動的な UI を実現する軽量なライブラリです。JavaScript をほとんど書かずに、データバインディング、条件分岐、繰り返し処理、フォームの双方向バインディング、サーバー通信などを HTML 属性で宣言できます。
 
-バージョン: 0.20.1
+バージョン: 0.22.0
 
 ---
 
@@ -93,7 +93,7 @@ Haori.mount(document.body, {items: [{name: 'りんご'}, {name: 'みかん'}]});
 
 ## よく使う属性（概要）
 
-- `data-bind` — 要素にバインディングデータを設定（JSON またはパラメータ形式）
+- `data-bind` — 要素にバインディングデータを設定（JSON またはパラメータ形式）。**トップレベルキーの予約名**: グローバルと衝突するデータ／ナビゲーション／ストレージ系の名前（`location`・`history`・`document`・`navigator`・`localStorage`・`sessionStorage`）は**トップレベルキーとして利用でき**、式中ではバインド値が同名グローバルを遮蔽します（例 `{"history":[…]}` を `data-each="history"` で利用可）。実行系・プロトタイプ脱出名（`window`・`self`・`globalThis`・`Object`・`Function`・`eval`・`constructor`・`__proto__`・`prototype`・`setTimeout` など）は**使えません**。その場合、該当キーだけが無視され（式中では `undefined`）、残りのキーは通常どおり描画され、無視したキー名が `error` ログに出力されます。ネストしたオブジェクト／配列要素のプロパティ名には制約はありません。
 - `{{ ... }}` — テンプレート式（式評価により挿入）
 - `data-if` — 条件に応じて要素を表示 / 非表示
 - `data-each` — 配列を繰り返し表示（`data-each-key`, `data-each-arg`, `data-each-index` など）
@@ -125,7 +125,7 @@ Haori.mount(document.body, {items: [{name: 'りんご'}, {name: 'みかん'}]});
 - `haori:bindcomplete` — `data-*-bind` / `data-*-bind-arg` によるバインドと、対象要素配下の再評価が完了した後に対象要素で発火します（`detail.bindArg`）。
 - `haori:show` / `haori:hide` — `data-if` 要素の表示・非表示時に発火します。
 
-式中では予約名前空間 `haori` の組み込みヘルパーを利用できます。`haori.date(value, format?)` は ISO 文字列・エポックミリ秒・`Date` を整形し（既定 `yyyy/MM/dd HH:mm`、ローカル時刻）、`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`）。これにより番号ページネーション（`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` は予約名のため、同名の `data-bind` キーを与えても式中では組み込みが優先されます。
+式中では予約名前空間 `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` キーを与えても式中では組み込みが優先されます。
 
 JS からバインドデータを読むには `Haori.Core.getBindingData(element, {resolved?})` を使います。既定では要素自身の生バインドデータ（無ければ `null`）、`resolved: true` で継承を解決済みのスコープを返します（`setBindingData` の対となる読み取り API）。
 

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.20.1
+Version: 0.22.0
 
 ---
 
@@ -93,7 +93,7 @@ Haori.mount(document.body, {items: [{name: 'apple'}, {name: 'orange'}]});
 
 ## Common attributes (summary)
 
-- `data-bind` — set binding data for an element (JSON or parameter format)
+- `data-bind` — set binding data for an element (JSON or parameter format). **Reserved top-level keys:** data/navigation/storage names that collide with globals (`location`, `history`, `document`, `navigator`, `localStorage`, `sessionStorage`) **can** be used as top-level keys and shadow the global inside expressions (e.g. `{"history":[…]}` works with `data-each="history"`). Execution/prototype-escape names (`window`, `self`, `globalThis`, `Object`, `Function`, `eval`, `constructor`, `__proto__`, `prototype`, `setTimeout`, …) **cannot**: such a key is ignored (it resolves to `undefined` in expressions) while the other keys still render, and an `error` is logged naming the ignored key. Nested object/array property names are unrestricted.
 - `{{ ... }}` — template expressions (evaluated and inserted)
 - `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`)
@@ -125,7 +125,7 @@ Lifecycle events:
 - `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.
 
-Built-in helpers are available in expressions under the reserved namespace `haori`: `haori.date(value, format?)` formats an ISO string / epoch ms / `Date` (default `yyyy/MM/dd HH:mm`, local time), `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`). 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` is reserved: a `data-bind` key of the same name does not shadow the built-ins inside expressions.
+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.
 
 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`).