@aiquants/virtualscroll 3.0.0 → 3.1.1

package/CHANGELOG.md

@@ -2,6 +2,53 @@
 
 All notable changes to `@aiquants/virtualscroll` are documented here.
 
+## 3.1.1 (未リリース)
+
+### Fixed
+
+- **タッチ / ペンパンの祖先 transform scale 補正 (÷scale)**: ScrollPane のポインタパンとフリック
+  慣性速度が視覚 px のまま論理スクロールへ入っていたため、祖先に `transform: scale(z)` がある
+  ホスト (例: `@aiquants/spreadsheet` v0.3 のパッケージズーム) で**コンテンツが指速の z 倍**で
+  動き、慣性走行距離も同率で歪んでいた。押下時に採取する視覚 / レイアウト比で move delta と
+  慣性初速を除算する (ScrollBar のサム / トラックドラッグが既に持つ press キャッシュ規約と
+  同一)。スケール算出は `getAxisScale` として `utils.ts` へ共有化 (ScrollBar は委譲 — 挙動
+  不変を既存スケール補正テストが封印)。発動閾値 6px は指の物理移動量の判別のため視覚 px の
+  まま (意図的非対称)。ホイールは補正しない — WheelEvent の delta はスクロール量であり
+  transform の影響を受けない (ネイティブスクローラーと同挙動、`wheelSpeedMultiplier` で調整可)。
+  ゲート: scale 0.5 のパン 2 倍換算・小数寸法 scale 1 の厳密同値・視覚速度閾値未満 / 論理速度
+  閾値以上の慣性判別 (変異 3 種 red 実測)。付随の lint 衛生 1 件: 既存の意図的観測プローブ
+  (`sameCountRoundtripDetach.spec.tsx` の console.log) へ根拠つき biome-ignore を付与 (コメント
+  のみ・挙動不変)。
+
+## 3.1.0 (2026-08-20)
+
+**A-5 のアクセシビリティ / 入力ユーティリティ 3 点。すべて opt-in で、未使用時の挙動・DOM 形状は
+一切変わりません。**
+
+- **Escape 行復帰** (`behaviorOptions.enableEscapeRowReturn`、既定 `false`): 行内のリンクや
+  ウィジェットにフォーカスがある状態で `Escape` を押すと行ラッパーへフォーカスを戻します
+  (行はタブ順に入らないため、既定ではキーボードで行へ戻る手段が無かった)。`Escape` は最多重負荷の
+  キーのため、**bubble フェーズ**で聞き (行内ウィジェットの `stopPropagation` / `preventDefault` が
+  常に勝つ)、IME 合成中 (`isComposing`)・**編集可能なターゲット (input / textarea / select /
+  contentEditable — ネイティブの Escape 既定動作は `defaultPrevented` に現れず検査で守れない)**・
+  行自身フォーカス時は何もしません。作用時は `preventDefault()` のみで伝播は止めません
+  (矢印キーと同じ契約)。
+- **ライブリージョン** (`liveRegion` prop): 可視範囲を支援技術へ読み上げる `role="status"`
+  (polite / atomic) の隠し要素をペインの兄弟として描画します。文言は消費側の `format` が組み立て
+  (パッケージは文字列を内蔵しない)、範囲静定後の trailing デバウンス (`debounceMs`、既定 400) で
+  1 回だけ更新します。不正な `debounceMs` は警告して無効化 (黙って既定へ読み替えない)。実行時に
+  prop を外すと残留文言もクリアします (再有効化時に古い範囲を読み上げさせない)。
+- **`createResidualQuantizer`**: 位置を行/列単位へスナップする消費側向けの残差持ち越し型デルタ
+  量子化器。高解像度トラックパッドの量子未満デルタが都度 0 に丸められて「ゆっくり撫でると動かない」
+  問題を、残差蓄積 + 量子単位の放出で解消します。方向反転で残差を破棄 (既定、幽霊スクロール防止)、
+  非有限デルタと `Number.MAX_SAFE_INTEGER` 超のデルタは蓄積を汚さず 0 (2^53 超では放出が量子の
+  正確な倍数でなくなるため)、不正な量子は生成時に throw (Fail Fast)。時間起点の破棄は意図的に
+  内蔵せず、消費側の `reset()` に委ねます。
+
+A-5 のうち**固定リピートタイマは実装を見送り**ました: 長押しの連続スクロール速度は OS のキー
+リピート設定に委ねます (運動障害等でリピートを意図的に遅くした利用者の設定とパッケージ内タイマが
+戦うため。需要が実証された場合に opt-in で再検討)。
+
 ## 3.0.0 (2026-08-20)
 
 **💥 BREAKING: `horizontalKeyInputs` から `"shift-arrow"` を撤去。** `Shift + ←/→` による横キーボード

package/README.md

@@ -13,6 +13,7 @@ High-performance virtual scrolling component for React with variable item height
 - ↔️ **Horizontal Delegation**: Opt-in `onWheelHorizontal` hands horizontal wheel / trackpad (and shift+wheel) gestures to the parent — build frozen-column data grids
 - 🎨 **Customizable**: Flexible styling and theming options
 - 🌀 **Ultrafast Tap Scroll**: Adaptive tap scroll circle that scales speed up to 120× for massive datasets
+- ♿ **Accessibility opt-ins**: Escape row-return (`enableEscapeRowReturn`) and a screen-reader live region (`liveRegion`) announcing the visible range with your own wording
 - 🔧 **TypeScript**: Full TypeScript support with comprehensive type definitions
 
 ## Installation
@@ -303,6 +304,71 @@ focus, so if you want keyboard-only users to reach it, give them an entry point
 that same `Omit`. They sit at the top level, next to `onWheelHorizontal`, precisely so one `Omit` closes
 the whole horizontal seam.
 
+## Escape row-return
+
+Rows are not in the tab order (`tabIndex={-1}`), so once focus enters a link or widget inside a
+row there is by default no keyboard way back to the row — the anchor for arrow-key navigation.
+`behaviorOptions.enableEscapeRowReturn` (default: `false`) makes `Escape` return focus to the row
+wrapper (scrolling it into view if needed).
+
+It is off by default because `Escape` is the most overloaded key on the page (closing modals and
+dropdowns, cancelling IME composition, clearing selection). The feature therefore listens in the
+**bubble** phase — a dropdown opened inside a cell handles its own `Escape` first and can keep it
+with `stopPropagation()` or `preventDefault()` — skips IME composition (`isComposing`), leaves
+**editable targets** (`input` / `textarea` / `select` / `contentEditable`) entirely alone (their
+native `Escape` default actions, like Blink/WebKit clearing an `<input type="search">`, never show
+up in `defaultPrevented` and would otherwise be silently suppressed), and never acts while the row
+itself has focus (an `Escape` on the row means whatever *you* decide — e.g. deselect). When it
+does act it calls `preventDefault()` only and does not stop propagation, the same contract as the
+arrow keys.
+
+## Screen-reader live region
+
+Virtualization removes off-screen rows from the DOM, so a screen-reader user scrolling the list
+gets no feedback about where they are. The opt-in `liveRegion` prop renders a visually hidden
+`role="status"` element (polite, atomic) next to the pane and updates it after the visible range
+settles:
+
+```tsx
+<VirtualScroll
+    liveRegion={{
+        format: ({ visibleStartIndex, visibleEndIndex, itemCount }) => `rows ${visibleStartIndex + 1}-${visibleEndIndex + 1} of ${itemCount}`,
+        debounceMs: 400, // default; trailing — announces once after the last range change
+    }}
+    ...
+/>
+```
+
+The package ships **no built-in strings** — wording and language are yours (`format` returning the
+same string leaves the DOM untouched; `""` clears the region). An invalid `debounceMs` (negative /
+non-finite) logs a warning and disables announcements instead of silently substituting the
+default. ⚠️ If your app already maintains its own live region for the list, keep using
+`onRangeChange` instead — two regions double-announce.
+
+## Residual quantizer for snapping consumers
+
+Consumers that snap positions to a fixed quantum (row height, column width) lose sub-quantum
+deltas: a high-resolution trackpad emits many small deltas, each rounds to zero rows, and a slow
+swipe never moves. `createResidualQuantizer` carries the remainder across events:
+
+```tsx
+import { createResidualQuantizer } from "@aiquants/virtualscroll"
+
+const quantizer = createResidualQuantizer({ quantum: ROW_HEIGHT })
+const onWheelVertical = (deltaY: number) => {
+    const emitted = quantizer.push(deltaY) // always a multiple of the quantum (possibly 0)
+    if (emitted !== 0) snapScrollBy(emitted)
+}
+```
+
+By default the residue is dropped on direction reversal (so a stale forward remainder cannot delay
+the first backward step); call `reset()` from your own idle timer or when the snapped layout
+changes. `quantum` must be finite and positive (anything else throws — fail fast). Non-finite
+deltas and deltas beyond `Number.MAX_SAFE_INTEGER` emit 0 without poisoning the accumulator —
+past 2^53 the float product stops being an *exact* multiple of the quantum, the very property a
+snapping consumer relies on. The quantizer is deliberately time-free: idle expiry policies differ
+per UI, so they stay on your side of the seam.
+
 ## Suspended transitions (React 18/19 `startTransition` + `Suspense`)
 
 Scroll state is judged against the **last committed** dimensions, never against a render that got
@@ -382,6 +448,7 @@ exists in the DOM.
 | `onItemFocus` | `(index: number) => void` | ❌ | Callback when an item is focused |
 | `scrollBarOptions` | `VirtualScrollScrollBarOptions` | ❌ | Options for the scrollbar |
 | `behaviorOptions` | `VirtualScrollBehaviorOptions` | ❌ | Options for scrolling behavior |
+| `liveRegion` | `VirtualScrollLiveRegionOptions` | ❌ | Opt-in screen-reader live region announcing the visible range (nothing rendered when omitted). See [Screen-reader live region](#screen-reader-live-region) |
 | `contentProps` | `React.AriaAttributes & { id?: string; role?: React.AriaRole }` | ❌ | ARIA / identity attributes for the scrollable **content** element — the correct host for a composite widget role. See [Composite widget roles](#composite-widget-roles-listbox--tree--grid). |
 
 ### VirtualScrollScrollBarOptions
@@ -403,6 +470,7 @@ exists in the DOM.
 | `enablePointerDrag` | `boolean` | Enable dragging the content area to scroll (default: true). ⚠️ Setting this to `false` removes the only way to scroll on touch devices — the pane is transform-based and has no native scroller. Use `pointerDragInputs` to exclude a single pointer type instead. |
 | `pointerDragInputs` | `readonly ("mouse" \| "pen" \| "touch")[]` | Pointer types allowed to drag-scroll the content area (default: all three). `touch-action: none` is applied only when `"touch"` or `"pen"` is included. |
 | `enableKeyboardNavigation` | `boolean` | Enable keyboard navigation (default: true). Arrow / Page keys move row focus. ⚠️ They fire **only when the row wrapper itself is the event target** — focus inside a row (a `role="slider"` cell, a link, a nested scroll region) keeps its own keys |
+| `enableEscapeRowReturn` | `boolean` | Opt-in (default: false): pressing `Escape` while focus sits on an element **inside** a row returns focus to the row wrapper. Listens in the bubble phase and respects `preventDefault` / `stopPropagation` / IME composition, so widgets inside the row keep first claim on their own `Escape`. Requires `enableKeyboardNavigation` |
 | `wheelSpeedMultiplier` | `number` | Multiplier for mouse wheel scrolling speed (default: 1) |
 | `inertiaOptions` | `ScrollPaneInertiaOptions` | Physics tuning for drag inertia |
 | `overscrollBehavior` | `"auto" \| "contain"` | Wheel behavior at the edges (default `"auto"` = chain to ancestors like a native scroller; `"contain"` = keep consuming, pre-2.7.0 trapping) |

package/dist/ScrollBar.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ScrollBar.d.ts","sourceRoot":"","sources":["../src/ScrollBar.tsx"],"names":[],"mappings":"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"}
+{"version":3,"file":"ScrollBar.d.ts","sourceRoot":"","sources":["../src/ScrollBar.tsx"],"names":[],"mappings":"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"}

package/dist/ScrollPane.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ScrollPane.d.ts","sourceRoot":"","sources":["../src/ScrollPane.tsx"],"names":[],"mappings":"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"}
+{"version":3,"file":"ScrollPane.d.ts","sourceRoot":"","sources":["../src/ScrollPane.tsx"],"names":[],"mappings":"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"}

package/dist/VirtualScroll.d.cts

@@ -150,6 +150,34 @@ export type VirtualScrollBehaviorOptions = {
      */
     pointerDragInputs?: ScrollPaneProps["pointerDragInputs"];
     enableKeyboardNavigation?: boolean;
+    /**
+     * When `true`, pressing `Escape` while focus sits on an element INSIDE a row returns focus to
+     * the row wrapper (default: `false`).
+     * `true` のとき、行の**中**の要素にフォーカスがある状態で `Escape` を押すと行ラッパーへ
+     * フォーカスを戻す (既定 `false`)。
+     *
+     * 行はタブ順に入らない (`tabIndex={-1}`) ため、行内のリンクやウィジェットへ入った後、
+     * キーボードだけで行 (縦横矢印ナビゲーションの起点) へ戻る手段が既定では存在しない。
+     * このオプションはその復帰口をパッケージ側で提供する。
+     *
+     * ❗ **既定 OFF なのは `Escape` が最も多重負荷のキーだからである** (モーダルやドロップダウンを
+     * 閉じる・IME 確定取消・選択解除)。次の防御で行内ウィジェットの `Escape` を奪わない:
+     *
+     * - **bubble フェーズで聞く** (矢印キーの capture とは逆)。行内で開いたドロップダウン等が
+     *   自分の `Escape` を先に処理でき、`stopPropagation()` すれば本機能には届かない。
+     * - `event.defaultPrevented` 済みなら何もしない (preventDefault だけの消費側も尊重)。
+     * - IME 合成中 (`isComposing`) は何もしない (確定取消を奪わない)。
+     * - **編集可能なターゲット (input / textarea / select / contentEditable) では何もしない。**
+     *   ネイティブの既定動作 (Blink / WebKit の `<input type="search">` は Escape でクリアされる) は
+     *   `defaultPrevented` に現れないため、スクリプト先約の検査では守れない。
+     * - 行そのものにフォーカスがあるときは何もしない (行上の `Escape` の意味 — 選択解除など — は
+     *   消費側の所有物)。
+     *
+     * 作用時は `preventDefault()` のみで伝播は止めない (矢印キーと同じ契約)。復帰は
+     * `focusItemAtIndex` 経由なので、行が画面外なら同時にスクロールで可視化される。
+     * `behaviorOptions.enableKeyboardNavigation` が前提 (行ハンドラ自体が付かないため)。
+     */
+    enableEscapeRowReturn?: boolean;
     wheelSpeedMultiplier?: number;
     inertiaOptions?: ScrollPaneProps["inertiaOptions"];
     /**
@@ -176,6 +204,48 @@ export type VirtualScrollBehaviorOptions = {
      */
     resetOnGetItemHeightChange?: boolean;
 };
+/**
+ * Range info handed to {@link VirtualScrollLiveRegionOptions.format}.
+ * {@link VirtualScrollLiveRegionOptions.format} へ渡す範囲情報。
+ */
+export type VirtualScrollLiveRegionRange = {
+    /** Index of the first visible item / 可視先頭アイテムのインデックス */
+    visibleStartIndex: number;
+    /** Index of the last visible item / 可視末尾アイテムのインデックス */
+    visibleEndIndex: number;
+    /** Total item count / 総アイテム数 */
+    itemCount: number;
+};
+/**
+ * Opt-in screen-reader live region announcing the visible range (see the `liveRegion` prop).
+ * 可視範囲を読み上げる opt-in のスクリーンリーダー用ライブリージョン (`liveRegion` prop 参照)。
+ */
+export type VirtualScrollLiveRegionOptions = {
+    /**
+     * Formats the announcement text. Called after the visible range settles; returning the same
+     * string as last time leaves the DOM untouched (no re-announcement), returning `""` clears
+     * the region. The package ships NO built-in strings — wording and language are the
+     * consumer's (a generic package must not hardcode a locale).
+     * 読み上げ文言を組み立てる。可視範囲が静定した後に呼ばれ、前回と同じ文字列なら DOM を
+     * 触らない (再読み上げしない)。`""` を返すとリージョンを空にする。パッケージは文言を
+     * 一切内蔵しない — 言語と文面は消費側の所有物 (汎用パッケージはロケールをハードコード
+     * できない)。
+     *
+     * @param range - The settled visible range / 静定した可視範囲
+     * @returns Announcement text / 読み上げ文言
+     */
+    format: (range: VirtualScrollLiveRegionRange) => string;
+    /**
+     * Debounce (ms) after the last range change before announcing (default: 400). Must be a
+     * finite number ≥ 0 — anything else logs a warning and disables announcements (no silent
+     * substitution). Announcing every wheel tick makes the reader chatter over the content;
+     * announcing too late reads a stale position. 0 announces on the next effect flush.
+     * 最後の範囲変化から読み上げまでのデバウンス (ms、既定 400)。有限かつ 0 以上であること —
+     * それ以外は警告して読み上げを無効化する (黙って既定へ読み替えない)。ホイール 1 ノッチ
+     * ごとに読むと内容の読み上げに被り、遅すぎると古い位置を読む。0 は次の effect で即時。
+     */
+    debounceMs?: number;
+};
 /**
  * Props for the VirtualScroll component.
  *
@@ -221,6 +291,24 @@ export type VirtualScrollProps<T> = {
     testId?: string;
     onScroll?: (scrollPosition: number, totalHeight: number) => void;
     onRangeChange?: (range: VirtualScrollRange) => void;
+    /**
+     * Opt-in `aria-live` region announcing the visible range to assistive technology (default:
+     * none rendered). Virtualization removes off-screen rows from the DOM, so a screen-reader
+     * user scrolling the list otherwise gets no feedback about where they are. Provide a
+     * {@link VirtualScrollLiveRegionOptions.format} to opt in; the region is a visually hidden
+     * `role="status"` element (polite, atomic) rendered as a sibling of the pane, updated after
+     * the range settles ({@link VirtualScrollLiveRegionOptions.debounceMs}).
+     *
+     * 可視範囲を支援技術へ読み上げる opt-in の `aria-live` リージョン (既定: 描画しない)。
+     * 仮想化は画面外の行を DOM から取り除くため、スクリーンリーダーの利用者はスクロールしても
+     * 現在位置の手掛かりを得られない。{@link VirtualScrollLiveRegionOptions.format} を渡すと、
+     * 視覚的に隠した `role="status"` 要素 (polite・atomic) をペインの兄弟として描画し、範囲が
+     * 静定した後に更新する。
+     *
+     * ❗ **ホスト側に既存のライブリージョンがある場合は併用しないこと** (二重読み上げになる)。
+     * その場合は `onRangeChange` から自前のリージョンを更新する従来手段を使う。
+     */
+    liveRegion?: VirtualScrollLiveRegionOptions;
     background?: ReactNode;
     children: (item: T, index: number) => ReactNode;
     initialScrollIndex?: number;

package/dist/VirtualScroll.d.ts

@@ -150,6 +150,34 @@ export type VirtualScrollBehaviorOptions = {
      */
     pointerDragInputs?: ScrollPaneProps["pointerDragInputs"];
     enableKeyboardNavigation?: boolean;
+    /**
+     * When `true`, pressing `Escape` while focus sits on an element INSIDE a row returns focus to
+     * the row wrapper (default: `false`).
+     * `true` のとき、行の**中**の要素にフォーカスがある状態で `Escape` を押すと行ラッパーへ
+     * フォーカスを戻す (既定 `false`)。
+     *
+     * 行はタブ順に入らない (`tabIndex={-1}`) ため、行内のリンクやウィジェットへ入った後、
+     * キーボードだけで行 (縦横矢印ナビゲーションの起点) へ戻る手段が既定では存在しない。
+     * このオプションはその復帰口をパッケージ側で提供する。
+     *
+     * ❗ **既定 OFF なのは `Escape` が最も多重負荷のキーだからである** (モーダルやドロップダウンを
+     * 閉じる・IME 確定取消・選択解除)。次の防御で行内ウィジェットの `Escape` を奪わない:
+     *
+     * - **bubble フェーズで聞く** (矢印キーの capture とは逆)。行内で開いたドロップダウン等が
+     *   自分の `Escape` を先に処理でき、`stopPropagation()` すれば本機能には届かない。
+     * - `event.defaultPrevented` 済みなら何もしない (preventDefault だけの消費側も尊重)。
+     * - IME 合成中 (`isComposing`) は何もしない (確定取消を奪わない)。
+     * - **編集可能なターゲット (input / textarea / select / contentEditable) では何もしない。**
+     *   ネイティブの既定動作 (Blink / WebKit の `<input type="search">` は Escape でクリアされる) は
+     *   `defaultPrevented` に現れないため、スクリプト先約の検査では守れない。
+     * - 行そのものにフォーカスがあるときは何もしない (行上の `Escape` の意味 — 選択解除など — は
+     *   消費側の所有物)。
+     *
+     * 作用時は `preventDefault()` のみで伝播は止めない (矢印キーと同じ契約)。復帰は
+     * `focusItemAtIndex` 経由なので、行が画面外なら同時にスクロールで可視化される。
+     * `behaviorOptions.enableKeyboardNavigation` が前提 (行ハンドラ自体が付かないため)。
+     */
+    enableEscapeRowReturn?: boolean;
     wheelSpeedMultiplier?: number;
     inertiaOptions?: ScrollPaneProps["inertiaOptions"];
     /**
@@ -176,6 +204,48 @@ export type VirtualScrollBehaviorOptions = {
      */
     resetOnGetItemHeightChange?: boolean;
 };
+/**
+ * Range info handed to {@link VirtualScrollLiveRegionOptions.format}.
+ * {@link VirtualScrollLiveRegionOptions.format} へ渡す範囲情報。
+ */
+export type VirtualScrollLiveRegionRange = {
+    /** Index of the first visible item / 可視先頭アイテムのインデックス */
+    visibleStartIndex: number;
+    /** Index of the last visible item / 可視末尾アイテムのインデックス */
+    visibleEndIndex: number;
+    /** Total item count / 総アイテム数 */
+    itemCount: number;
+};
+/**
+ * Opt-in screen-reader live region announcing the visible range (see the `liveRegion` prop).
+ * 可視範囲を読み上げる opt-in のスクリーンリーダー用ライブリージョン (`liveRegion` prop 参照)。
+ */
+export type VirtualScrollLiveRegionOptions = {
+    /**
+     * Formats the announcement text. Called after the visible range settles; returning the same
+     * string as last time leaves the DOM untouched (no re-announcement), returning `""` clears
+     * the region. The package ships NO built-in strings — wording and language are the
+     * consumer's (a generic package must not hardcode a locale).
+     * 読み上げ文言を組み立てる。可視範囲が静定した後に呼ばれ、前回と同じ文字列なら DOM を
+     * 触らない (再読み上げしない)。`""` を返すとリージョンを空にする。パッケージは文言を
+     * 一切内蔵しない — 言語と文面は消費側の所有物 (汎用パッケージはロケールをハードコード
+     * できない)。
+     *
+     * @param range - The settled visible range / 静定した可視範囲
+     * @returns Announcement text / 読み上げ文言
+     */
+    format: (range: VirtualScrollLiveRegionRange) => string;
+    /**
+     * Debounce (ms) after the last range change before announcing (default: 400). Must be a
+     * finite number ≥ 0 — anything else logs a warning and disables announcements (no silent
+     * substitution). Announcing every wheel tick makes the reader chatter over the content;
+     * announcing too late reads a stale position. 0 announces on the next effect flush.
+     * 最後の範囲変化から読み上げまでのデバウンス (ms、既定 400)。有限かつ 0 以上であること —
+     * それ以外は警告して読み上げを無効化する (黙って既定へ読み替えない)。ホイール 1 ノッチ
+     * ごとに読むと内容の読み上げに被り、遅すぎると古い位置を読む。0 は次の effect で即時。
+     */
+    debounceMs?: number;
+};
 /**
  * Props for the VirtualScroll component.
  *
@@ -221,6 +291,24 @@ export type VirtualScrollProps<T> = {
     testId?: string;
     onScroll?: (scrollPosition: number, totalHeight: number) => void;
     onRangeChange?: (range: VirtualScrollRange) => void;
+    /**
+     * Opt-in `aria-live` region announcing the visible range to assistive technology (default:
+     * none rendered). Virtualization removes off-screen rows from the DOM, so a screen-reader
+     * user scrolling the list otherwise gets no feedback about where they are. Provide a
+     * {@link VirtualScrollLiveRegionOptions.format} to opt in; the region is a visually hidden
+     * `role="status"` element (polite, atomic) rendered as a sibling of the pane, updated after
+     * the range settles ({@link VirtualScrollLiveRegionOptions.debounceMs}).
+     *
+     * 可視範囲を支援技術へ読み上げる opt-in の `aria-live` リージョン (既定: 描画しない)。
+     * 仮想化は画面外の行を DOM から取り除くため、スクリーンリーダーの利用者はスクロールしても
+     * 現在位置の手掛かりを得られない。{@link VirtualScrollLiveRegionOptions.format} を渡すと、
+     * 視覚的に隠した `role="status"` 要素 (polite・atomic) をペインの兄弟として描画し、範囲が
+     * 静定した後に更新する。
+     *
+     * ❗ **ホスト側に既存のライブリージョンがある場合は併用しないこと** (二重読み上げになる)。
+     * その場合は `onRangeChange` から自前のリージョンを更新する従来手段を使う。
+     */
+    liveRegion?: VirtualScrollLiveRegionOptions;
     background?: ReactNode;
     children: (item: T, index: number) => ReactNode;
     initialScrollIndex?: number;

package/dist/VirtualScroll.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"VirtualScroll.d.ts","sourceRoot":"","sources":["../src/VirtualScroll.tsx"],"names":[],"mappings":"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"}
+{"version":3,"file":"VirtualScroll.d.ts","sourceRoot":"","sources":["../src/VirtualScroll.tsx"],"names":[],"mappings":"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"}