@aiquants/virtualscroll 3.9.2 → 3.11.0

package/src/ScrollBar.tsx

@@ -7,11 +7,11 @@ import type { CSSProperties, ReactNode } from "react"
 import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState } from "react"
 import { twMerge } from "tailwind-merge"
 import { snapToDevicePixelGrid, usePaintingDevicePixelRatio } from "./devicePixelGrid.ts"
-import { resolveVirtualScrollLabels, type VirtualScrollLabelOverrides, type VirtualScrollLocale } from "./labels.ts"
+import { resolveVirtualScrollLabels, resolveVirtualScrollLocale, type VirtualScrollLabelOverrides, type VirtualScrollLabels, type VirtualScrollLocale } from "./labels.ts"
 import { Logger } from "./logger.ts"
 import { capturePointer, releaseCapturedPointer } from "./pointerCapture.ts"
 import { TapScrollCircle, type TapScrollCircleDragState, type TapScrollCircleHandle, type TapScrollCircleRenderProps } from "./TapScrollCircle.tsx"
-import { getAxisScale, minmax } from "./utils.ts"
+import { getAxisScale, keepFocusOnPress, minmax } from "./utils.ts"
 
 /**
  * Configuration for scrollbar orientation (vertical or horizontal).
@@ -40,6 +40,13 @@ type ArrowAutoRepeatOptions = {
     canUseArrowButtons: boolean
     /** Whether arrow buttons are enabled in configuration / 設定で矢印ボタンが有効化されているか */
     enableArrowButtons: boolean
+    /**
+     * Whether a focused arrow takes Enter / Space: `false` under the pointer-only signal (`enableArrowButtonTabStops: false`),
+     * where the bar is hidden from assistive technology and its arrows answer the pointer only, even when a script focuses one.
+     * フォーカスした矢印が Enter / Space を受けるか。ポインタ専用の合図 (`enableArrowButtonTabStops: false`) の下では `false` で、
+     * バーは支援技術から隠れ、矢印はスクリプトがフォーカスしてもポインタにだけ応える。
+     */
+    keyboardOperable: boolean
     /** Function to reset tap scroll state / タップスクロール状態をリセットする関数 */
     resetTapScroll: () => void
     /** Function to scroll by a step / ステップ単位でスクロールする関数 */
@@ -154,8 +161,8 @@ export type ScrollBarProps = {
     viewportSize: number
     /** The current scroll position. / 現在のスクロール位置。 */
     scrollPosition: number
-    /** A callback function invoked to adjust scroll position. Accepts next position or updater. / スクロール位置を調整するためのコールバック。次位置または更新関数を受け取る。 */
-    onScroll?: (scrollPosition: number | ((prevPosition: number) => number), prevPosition?: number) => number | undefined
+    /** A callback function invoked to adjust scroll position. Accepts next position or updater, and always receives the position the bar resolved the request from. / スクロール位置を調整するためのコールバック。次位置または更新関数と、バーが要求を解いた元の位置 (必ず渡す) を受け取る。 */
+    onScroll?: (scrollPosition: number | ((prevPosition: number) => number), prevPosition: number) => number | undefined
     /** Whether grabbing the scrollbar thumb is allowed. / スクロールバーのつまみ操作を許可するかどうか。 */
     enableThumbDrag?: boolean
     /** Whether clicking on the track moves the scrollbar. / スクロールバーのトラッククリック操作を許可するかどうか。 */
@@ -163,37 +170,41 @@ export type ScrollBarProps = {
     /** Whether arrow buttons control the scroll position. / 矢印ボタンによるスクロール操作を許可するかどうか。 */
     enableArrowButtons?: boolean
     /**
-     * Whether the two arrow buttons are Tab stops (default `true`).
+     * Whether the bar is the keyboard user's scrolling control (default `true`), or a pointer-only control because the host
+     * scrolls this viewport by keyboard itself (`false`).
+     *
+     * `true`: the bar is exposed to assistive technology as a named `role="scrollbar"` (`labels.verticalScrollBar` /
+     * `labels.horizontalScrollBar`) holding a named `role="slider"` thumb (`labels.verticalScrollThumb` /
+     * `labels.horizontalScrollThumb`), and its two arrow buttons are Tab stops: `ScrollPane` / `VirtualScroll` move their
+     * content by transform, so there is no native scroller the browser could make focusable, and their rows are not Tab
+     * stops — without a host keyboard model the arrows are the only scrolling control Tab reaches. Focus an arrow and
+     * Enter / Space scrolls one step.
+     *
+     * `false` declares that the host owns keyboard scrolling of this viewport (roving row focus with Arrow / Page / Home /
+     * End, a grid keyboard model), so the bar only duplicates that path. The bar then becomes what a native scrollbar is:
+     * a pointer-only control. The bar carries `aria-hidden="true"`; its arrows get `tabIndex={-1}`, and the bar root and
+     * the thumb wrapper are not focusable; a press anywhere on the bar cancels its default action, so it never moves
+     * focus — neither onto a part of the bar (an arrow, also a disabled one) nor away from where the host put it — while
+     * the press itself still reaches the part. Pointer scrolling is unchanged: the arrows (with press-and-hold repeat),
+     * the track, the thumb and the tap circle work exactly as with `true`. The same signal reaches the scroll-to-edge pills
+     * of `VirtualScroll` (`VirtualScrollScrollBarOptions["enableArrowButtonTabStops"]`).
      *
-     * `false` renders both with `tabIndex={-1}`, which takes them out of the sequential focus order
-     * and changes nothing else: pointer presses and press-and-hold repeat, the accessible names and
-     * Enter / Space on an arrow focused from script all keep working. The arrows are descendants of
-     * the `role="scrollbar"` root, whose children ARIA 1.2 makes presentational, so whether assistive
-     * technology lists them as buttons of their own is the browser's choice (Chromium does); this
-     * option changes nothing about that. Set it to `false` when the host already owns keyboard
-     * scrolling of this viewport (roving row focus with Arrow / Page / Home / End, a grid keyboard
-     * model): the arrows then duplicate that path and cost every keyboard user two extra Tab presses
-     * per bar — native scrollbars are never Tab stops either. The default stays `true` because
-     * without such a host model the arrows are the only scrolling control a keyboard user can reach
-     * with Tab: `ScrollPane` / `VirtualScroll` move their content by transform, so there is no native
-     * scroller the browser could make focusable, and their rows are not Tab stops. No effect while
-     * the arrows are disabled (`enableArrowButtons: false`, or nothing to scroll) — a disabled button
-     * is never focusable.
+     * バーがキーボード利用者のスクロール操作部品か (既定 `true`)、ホストがこのビューポートのキーボードスクロールを自分で
+     * 持つためポインタ専用の部品か (`false`) の指定。
      *
-     * 矢印ボタン 2 個を Tab の止まり先にするかどうか (既定 `true`)。
+     * `true`: バーは名前付きの `role="scrollbar"` (`labels.verticalScrollBar` / `labels.horizontalScrollBar`) として
+     * 支援技術へ見え、名前付きの `role="slider"` のつまみ (`labels.verticalScrollThumb` / `labels.horizontalScrollThumb`) を
+     * 持ち、矢印ボタン 2 個は Tab の止まり先。`ScrollPane` / `VirtualScroll` はコンテンツを transform で動かすため、
+     * ブラウザがフォーカス可能にできるネイティブのスクロール領域が無く、行も Tab の止まり先ではない — ホストのキーボード
+     * モデルが無ければ、矢印が Tab で届く唯一のスクロール操作部品。矢印にフォーカスして Enter / Space で 1 ステップ移動。
      *
-     * `false` は両方を `tabIndex={-1}` で描画し、順次フォーカス移動の順序から外すだけの指定。
-     * ポインタ押下と長押しリピート、アクセシブルネーム、スクリプトからフォーカスした矢印での
-     * Enter / Space はすべて維持。矢印は `role="scrollbar"` のルートの子孫で、ARIA 1.2 はその子を
-     * presentational とするため、支援技術が矢印を独立したボタンとして示すかどうかはブラウザの選択
-     * (Chromium は示す) であり、本オプションはそこに関与しない。ホストがこのビューポートのキーボード
-     * スクロールを既に持つ場合 (行のロービングフォーカスと矢印 / Page / Home / End、グリッドのキーボードモデル) に
-     * `false` を指定 — 矢印はその経路の重複となり、キーボード利用者にバー 1 本あたり 2 回の余分な Tab を
-     * 課すため (ネイティブのスクロールバーも Tab の止まり先にならない)。既定を `true` に据え置く理由は、
-     * ホスト側のモデルが無ければ矢印がキーボード利用者の Tab で届く唯一のスクロール操作部品であること
-     * (`ScrollPane` / `VirtualScroll` はコンテンツを transform で動かすため、ブラウザがフォーカス可能に
-     * できるネイティブのスクロール領域が無く、行も Tab の止まり先ではない)。矢印が無効な間
-     * (`enableArrowButtons: false` またはスクロール不要) は効果なし — disabled のボタンはそもそもフォーカス不能。
+     * `false` は、ホストがこのビューポートのキーボードスクロールを持つ (行のロービングフォーカスと矢印 / Page / Home / End、
+     * グリッドのキーボードモデル) ことの宣言で、バーはその経路の重複にすぎない。バーはネイティブのスクロールバーと同じく
+     * ポインタ専用の部品になる。バーは `aria-hidden="true"` を持ち、矢印は `tabIndex={-1}`、バーのルートとつまみの器は
+     * フォーカス不能。バーのどこを押しても押下の既定動作を取り消すので、押下はフォーカスを動かさない — バーの部品
+     * (矢印。無効の矢印も) へも、ホストが置いた場所の外へも — が、押下そのものは部品へ届く。ポインタのスクロールは
+     * 変わらない: 矢印 (長押しの連続を含む)・トラック・つまみ・タップのサークルは `true` と同じに動く。同じ合図は
+     * `VirtualScroll` の端へ戻るピルにも届く (`VirtualScrollScrollBarOptions["enableArrowButtonTabStops"]`)。
      */
     enableArrowButtonTabStops?: boolean
     /** Whether the scrollbar is horizontal. / スクロールバーが水平かどうか。 */
@@ -231,18 +242,21 @@ export type ScrollBarProps = {
     /** The index of the last visible item. / 最後の可視アイテムのインデックス。 */
     visibleEndIndex?: number
     /**
-     * UI chrome locale of the built-in arrow aria-labels (default `"en"`). An unsupported value
-     * throws a RangeError at render; no language negotiation happens.
-     * 内蔵矢印 aria-label の UI クロームロケール (既定 `"en"`)。非対応値は描画時に RangeError、
-     * 言語ネゴシエーションなし。
+     * UI chrome locale of the built-in accessible names of the bar, its thumb and its arrows, and of the percentage the bar
+     * and the thumb announce as their value text (default `"en"`). An unsupported value throws a RangeError at render; no
+     * language negotiation happens.
+     * バー・つまみ・矢印の内蔵アクセシブルネームと、バーとつまみが値の文字として知らせる百分率の UI クロームロケール (既定
+     * `"en"`)。非対応値は描画時に RangeError、言語ネゴシエーションなし。
      */
     locale?: VirtualScrollLocale
     /**
-     * Per-key overrides laid over the catalog of `locale`. This bar reads `scrollUp` / `scrollDown`
-     * (vertical) or `scrollLeft` / `scrollRight` (horizontal); unknown keys and blank values throw a
+     * Per-key overrides laid over the catalog of `locale`. A vertical bar reads `verticalScrollBar`,
+     * `verticalScrollThumb`, `scrollUp` and `scrollDown`; a horizontal bar reads `horizontalScrollBar`,
+     * `horizontalScrollThumb`, `scrollLeft` and `scrollRight`. Unknown keys and blank values throw a
      * RangeError at render.
-     * `locale` のカタログへ重ねるキー単位の上書き。本バーが読むのは縦なら `scrollUp` / `scrollDown`、
-     * 横なら `scrollLeft` / `scrollRight`。未知キーと空白値は描画時に RangeError。
+     * `locale` のカタログへ重ねるキー単位の上書き。縦のバーが読むのは `verticalScrollBar`・`verticalScrollThumb`・
+     * `scrollUp`・`scrollDown`、横のバーは `horizontalScrollBar`・`horizontalScrollThumb`・`scrollLeft`・`scrollRight`。
+     * 未知キーと空白値は描画時に RangeError。
      */
     labels?: VirtualScrollLabelOverrides
 }
@@ -294,6 +308,33 @@ export const DEFAULT_TAP_SCROLL_CIRCLE_OPTIONS: ResolvedTapScrollCircleOptions =
     maxSpeedCurve: undefined,
 }
 
+/**
+ * The accessible names one bar renders: the bar (`role="scrollbar"`), its thumb (`role="slider"`) and its two arrows
+ * (start, end).
+ *
+ * バー 1 本が描くアクセシブルネーム (バー `role="scrollbar"`・つまみ `role="slider"`・始端と終端の矢印)。
+ */
+type ScrollBarNames = {
+    /** Name of the bar / バーの名前 */
+    readonly bar: string
+    /** Name of the thumb / つまみの名前 */
+    readonly thumb: string
+    /** Names of the start and the end arrow / 始端と終端の矢印の名前 */
+    readonly arrows: readonly [string, string]
+}
+
+/**
+ * Picks the names of one bar from the resolved labels by its orientation.
+ *
+ * 解決済みのラベルから、向きに応じてバー 1 本の名前を選ぶ処理。
+ *
+ * @param labels - Resolved labels / 解決済みのラベル
+ * @param horizontal - Whether the bar is horizontal / 横のバーか
+ * @returns The bar's names / バーの名前
+ */
+const pickScrollBarNames = (labels: VirtualScrollLabels, horizontal: boolean): ScrollBarNames =>
+    horizontal ? { bar: labels.horizontalScrollBar, thumb: labels.horizontalScrollThumb, arrows: [labels.scrollLeft, labels.scrollRight] } : { bar: labels.verticalScrollBar, thumb: labels.verticalScrollThumb, arrows: [labels.scrollUp, labels.scrollDown] }
+
 /**
  * Creates the orientation dependent configuration for the scrollbar.
  *
@@ -374,7 +415,7 @@ const useThumbVisualFeedback = ({ isDragging, isThumbHovered, enableThumbDrag }:
  *
  * スクロールバー矢印の自動リピート操作向けハンドラーを提供。
  */
-const useArrowAutoRepeat = ({ canUseArrowButtons, enableArrowButtons, resetTapScroll, scrollByStep }: ArrowAutoRepeatOptions): ArrowAutoRepeatHandlers => {
+const useArrowAutoRepeat = ({ canUseArrowButtons, enableArrowButtons, keyboardOperable, resetTapScroll, scrollByStep }: ArrowAutoRepeatOptions): ArrowAutoRepeatHandlers => {
     const arrowHoldIntervalRef = useRef<number | null>(null)
     const arrowHoldTimeoutRef = useRef<number | null>(null)
     // 長押し中に張るグローバル解除リスナ (disabled 化やウィンドウ blur でボタンに pointerup が届かない保険)。
@@ -430,7 +471,9 @@ const useArrowAutoRepeat = ({ canUseArrowButtons, enableArrowButtons, resetTapSc
 
     const handleArrowKeyDown = useCallback(
         (direction: 1 | -1) => (event: React.KeyboardEvent<HTMLButtonElement>) => {
-            if (!enableArrowButtons) {
+            // ポインタ専用のバーは支援技術から隠れていて、キーボードのスクロールはホストが持つ。スクリプトがフォーカスした矢印でも
+            // キーを受けると、隠れた部品がホストのキー操作と重なって一覧を動かす
+            if (!(enableArrowButtons && keyboardOperable)) {
                 return
             }
             if (event.key === "Enter" || event.key === " " || event.key === "Spacebar") {
@@ -438,7 +481,7 @@ const useArrowAutoRepeat = ({ canUseArrowButtons, enableArrowButtons, resetTapSc
                 scrollByStep(direction)
             }
         },
-        [enableArrowButtons, scrollByStep],
+        [enableArrowButtons, keyboardOperable, scrollByStep],
     )
 
     // 矢印ボタンが操作不能 (canUseArrowButtons=false) になったら進行中のリピートを即停止する。
@@ -695,7 +738,11 @@ export const ScrollBar = ({
     const resolvedTapScrollOptions = useMemo<ResolvedTapScrollCircleOptions>(() => resolveTapScrollCircleOptions(tapScrollCircleOptions, itemCount), [itemCount, tapScrollCircleOptions])
     const orientationConfig = useMemo(() => createOrientationConfig(horizontal), [horizontal])
     const resolvedLabels = useMemo(() => resolveVirtualScrollLabels(locale, labels), [locale, labels])
-    const arrowLabels = horizontal ? ([resolvedLabels.scrollLeft, resolvedLabels.scrollRight] as const) : ([resolvedLabels.scrollUp, resolvedLabels.scrollDown] as const)
+    const names = pickScrollBarNames(resolvedLabels, horizontal)
+    // 値の文字はスクロールの割合。px の値 (aria-valuenow) は長い一覧で数千万になり、読み上げても位置が分からない
+    const valueTextFormat = useMemo(() => new Intl.NumberFormat(resolveVirtualScrollLocale(locale), { style: "percent", maximumFractionDigits: 0 }), [locale])
+    // ホストがキーボードのスクロールを持つと、バーはその経路の重複になる。支援技術にもキーボードにも同じ操作を 2 度見せない
+    const pointerOnly = !enableArrowButtonTabStops
     const {
         enabled: tapCircleEnabled,
         size: tapCircleSize,
@@ -733,6 +780,9 @@ export const ScrollBar = ({
     // 負値が aria-valuemax へ露出して ARIA 違反 (valuemax < valuemin) になる。644 行の
     // getScrollBarMetrics と同一のクランプ規約)
     const maxScrollPosition = Math.max(contentSize - viewportSize, 0)
+    // ポインタ専用のバーは支援技術から隠れるので値の文字を持たない。スクロールできないバーは 0 %、中身が縮んで一時的に最大位置を
+    // 越えた位置は 100 %
+    const valueText = pointerOnly ? undefined : valueTextFormat.format(maxScrollPosition > 0 ? minmax(scrollPosition / maxScrollPosition, 0, 1) : 0)
     const effectiveTrackLength = Math.max(trackLength - thumbSize, 0)
     // scrollPosition が範囲外 (コンテンツ縮小直後の未クランプ 1 フレームや iOS バウンス値) でも
     // サムがトラック外へはみ出さないよう、レンダー時に [0, effectiveTrackLength] へクランプする。
@@ -1268,6 +1318,7 @@ export const ScrollBar = ({
     const { handleArrowPointerDown, handleArrowPointerUp, handleArrowKeyDown } = useArrowAutoRepeat({
         canUseArrowButtons,
         enableArrowButtons,
+        keyboardOperable: !pointerOnly,
         resetTapScroll,
         scrollByStep,
     })
@@ -1484,13 +1535,14 @@ export const ScrollBar = ({
     }, [tapCircleOffsetX, tapCircleOffsetY, tapCircleSize])
 
     /**
-     * Renders one arrow button of the bar. It is a Tab stop (`tabIndex=0`) unless the host opted out
-     * with `enableArrowButtonTabStops={false}` (`tabIndex=-1`); either way it stays focusable from
-     * script, pointer-operable and named, and Enter / Space scrolls one step while it has focus.
+     * Renders one arrow button of the bar: a named Tab stop (`tabIndex=0`) on which Enter / Space scrolls one step, or,
+     * on a pointer-only bar (`enableArrowButtonTabStops={false}`), a pointer target out of the Tab order (`tabIndex=-1`)
+     * inside the bar's `aria-hidden` subtree, whose presses never move focus. Pointer presses and press-and-hold repeat
+     * work the same either way.
      *
-     * バーの矢印ボタン 1 個の描画。ホストが `enableArrowButtonTabStops={false}` で外さない限り Tab の
-     * 止まり先 (`tabIndex=0`)、外した場合は `tabIndex=-1`。いずれの場合もスクリプトからのフォーカス・
-     * ポインタ操作・アクセシブルネームは維持し、フォーカス中の Enter / Space で 1 ステップ移動。
+     * バーの矢印ボタン 1 個の描画。名前付きの Tab の止まり先 (`tabIndex=0`) で Enter / Space により 1 ステップ移動するか、
+     * ポインタ専用のバー (`enableArrowButtonTabStops={false}`) では Tab 順の外のポインタの的 (`tabIndex=-1`) で、
+     * バーの `aria-hidden` の部分木の中にあり押下はフォーカスを動かさない。ポインタの押下と長押しの連続はどちらも同じ。
      *
      * @param direction - Step direction (-1 = toward the start, 1 = toward the end) / ステップ方向 (-1 = 始端側、1 = 終端側)
      * @param label - Accessible name / アクセシブルネーム
@@ -1502,7 +1554,7 @@ export const ScrollBar = ({
         <button
             key={key}
             type="button"
-            tabIndex={enableArrowButtonTabStops ? 0 : -1}
+            tabIndex={pointerOnly ? -1 : 0}
             className="aqvs-scrollbar-arrow-button"
             style={{
                 [mainSizeKey]: scrollBarWidth,
@@ -1552,11 +1604,17 @@ export const ScrollBar = ({
             // components-only アーティファクトには同梱されず、ホストのビルド内容任せになる
             data-visible={scrollBarVisible ? "true" : "false"}
             role="scrollbar"
-            tabIndex={-1}
+            aria-label={names.bar}
+            aria-hidden={pointerOnly ? true : undefined}
+            // ポインタ専用のバーはフォーカスを受ける部品を持たない。押下の既定動作も取り消す: Chromium は無効の矢印の押下でも
+            // pointerdown を届けたうえで、最も近いフォーカス可能な祖先へフォーカスを移す (取り消すとどこへも移さない)
+            tabIndex={pointerOnly ? undefined : -1}
+            onPointerDown={pointerOnly ? keepFocusOnPress : undefined}
             aria-controls={ariaControls}
             aria-valuenow={scrollPosition}
             aria-valuemin={0}
             aria-valuemax={maxScrollPosition}
+            aria-valuetext={valueText}
             aria-orientation={horizontal ? "horizontal" : "vertical"}>
             {(!horizontal || enableHorizontalTapCircle) && scrollBarVisible && tapCircleEnabled && (
                 <TapScrollCircle
@@ -1572,7 +1630,7 @@ export const ScrollBar = ({
                     onDragChange={handleTapCircleDragChange}
                 />
             )}
-            {renderArrowButton(-1, arrowLabels[0], arrowIcons[0], "arrow-start")}
+            {renderArrowButton(-1, names.arrows[0], arrowIcons[0], "arrow-start")}
             <div
                 key="track"
                 className="aqvs-scrollbar-track"
@@ -1607,12 +1665,14 @@ export const ScrollBar = ({
                     data-visible={scrollBarVisible || isDragging ? "true" : "false"}
                     onPointerDown={handlePointerDownOnThumb}
                     role="slider"
+                    aria-label={names.thumb}
                     aria-orientation={horizontal ? "horizontal" : "vertical"}
                     aria-valuenow={scrollPosition}
                     aria-valuemin={0}
                     aria-valuemax={maxScrollPosition}
+                    aria-valuetext={valueText}
                     aria-disabled={!enableThumbDrag}
-                    tabIndex={-1}>
+                    tabIndex={pointerOnly ? undefined : -1}>
                     {/* スクロールバーのつまみ（可視部分） */}
                     {/* biome-ignore lint/a11y/noStaticElementInteractions: スクロールバーのつまみは必要なインタラクションです */}
                     <div
@@ -1639,7 +1699,7 @@ export const ScrollBar = ({
                     />
                 </div>
             </div>
-            {renderArrowButton(1, arrowLabels[1], arrowIcons[1], "arrow-end")}
+            {renderArrowButton(1, names.arrows[1], arrowIcons[1], "arrow-end")}
         </div>
     )
 }

package/src/ScrollPane.tsx

@@ -80,18 +80,16 @@ export type ScrollPaneProps = {
     /** Whether arrow buttons control the scroll position. / 矢印ボタンのスクロール操作を許可するかどうか。 */
     enableArrowButtons?: boolean
     /**
-     * Whether the scrollbar's two arrow buttons are Tab stops (default `true`), forwarded to the
-     * pane's ScrollBar. Set it to `false` when the host already provides keyboard scrolling for this
-     * pane: the arrows then only add two redundant Tab stops (native scrollbars are never Tab stops
-     * either). `false` changes `tabIndex` alone — the arrows stay pointer-operable and named. The
-     * default stays `true` because otherwise they are the pane's only scrolling control that Tab
-     * reaches. Full contract: `ScrollBarProps["enableArrowButtonTabStops"]`.
-     * スクロールバーの矢印ボタン 2 個を Tab の止まり先にするかどうか (既定 `true`)。ペインの ScrollBar へ
-     * 転送。ホストがこのペインのキーボードスクロールを既に提供する場合に `false` — 矢印は冗長な Tab の
-     * 止まり先を 2 つ足すだけになるため (ネイティブのスクロールバーも Tab の止まり先にならない)。`false` が
-     * 変えるのは `tabIndex` だけで、ポインタ操作とアクセシブルネームは維持。
-     * 既定が `true` なのは、それ以外ではペインで Tab の届く唯一のスクロール操作部品だから。契約の全文は
-     * `ScrollBarProps["enableArrowButtonTabStops"]`。
+     * Whether the pane's scrollbar is the keyboard user's scrolling control (default `true`) or a pointer-only control
+     * because the host scrolls this pane by keyboard itself (`false`), forwarded to the pane's ScrollBar. With `false`
+     * the bar carries `aria-hidden="true"`, has no Tab stop and no focusable part, and a press on it never moves focus;
+     * pointer scrolling is unchanged. The default stays `true` because otherwise the arrows are the pane's only scrolling
+     * control that Tab reaches. Full contract: `ScrollBarProps["enableArrowButtonTabStops"]`.
+     * ペインのスクロールバーがキーボード利用者のスクロール操作部品か (既定 `true`)、ホストがこのペインのキーボード
+     * スクロールを自分で持つためポインタ専用の部品か (`false`) の指定。ペインの ScrollBar へ転送。`false` ではバーが
+     * `aria-hidden="true"` を持ち、Tab の止まり先もフォーカス可能な部品も無く、押下はフォーカスを動かさない。ポインタの
+     * スクロールは変わらない。既定が `true` なのは、それ以外ではペインで Tab の届く唯一のスクロール操作部品だから。
+     * 契約の全文は `ScrollBarProps["enableArrowButtonTabStops"]`。
      */
     enableArrowButtonTabStops?: boolean
     /** Whether dragging the content area scrolls the pane. / コンテンツ領域のドラッグでスクロールさせるかどうか。 */
@@ -185,9 +183,9 @@ export type ScrollPaneProps = {
      */
     contentProps?: React.AriaAttributes & { id?: string; role?: React.AriaRole }
     /**
-     * UI chrome locale forwarded to the pane's ScrollBar (arrow aria-labels; default `"en"`).
+     * UI chrome locale forwarded to the pane's ScrollBar (the names of the bar, its thumb and its arrows; default `"en"`).
      * An unsupported value throws a RangeError at render.
-     * ペインの ScrollBar へ転送する UI クロームロケール (矢印の aria-label、既定 `"en"`)。
+     * ペインの ScrollBar へ転送する UI クロームロケール (バー・つまみ・矢印の名前、既定 `"en"`)。
      * 非対応値は描画時に RangeError。
      */
     locale?: VirtualScrollLocale

package/src/VirtualGrid.tsx

@@ -229,7 +229,7 @@ export type VirtualGridRange = {
     totalHeight: number
 }
 
-/** Live-region options: the consumer owns announcement wording/locale; the built-in catalog (`locale` / `labels`) covers only the seven chrome strings (arrows, pills, empty state) — row-parity. / liveRegion オプション: 読み上げの文言とロケールは消費側所有。内蔵カタログ (`locale` / `labels`) はクローム 7 文言 (矢印・ピル・空状態) のみ対象 — 行側と同一方針。 */
+/** Live-region options: the consumer owns announcement wording/locale; the built-in catalog (`locale` / `labels`) covers only the eleven chrome strings (the scrollbar names, pills, empty state) — row-parity. / liveRegion オプション: 読み上げの文言とロケールは消費側所有。内蔵カタログ (`locale` / `labels`) はクローム 11 文言 (スクロールバーの名前・ピル・空状態) のみ対象 — 行側と同一方針。 */
 export type VirtualGridLiveRegionOptions = {
     /** Builds the announcement (same string = no re-announce, "" clears). / 読み上げ文言の組み立て (同一文字列 = 再読み上げなし、"" でクリア)。 */
     buildMessage: (range: VirtualGridRange) => string
@@ -419,11 +419,11 @@ export type VirtualGridProps<T> = {
     scrollBarOptions?: VirtualScrollScrollBarOptions
     liveRegion?: VirtualGridLiveRegionOptions
     /**
-     * UI chrome locale (default `"en"`), forwarded to the embedded vertical VirtualScroll (its
-     * arrows and the 0-row / all-frozen / degenerate-band empty state) and the horizontal bar
-     * arrows. An unsupported value throws a RangeError at render.
-     * UI クロームロケール (既定 `"en"`)。内蔵の縦 VirtualScroll (矢印と 0 行・全行固定・退化帯の
-     * 空状態) と横バーの矢印へ転送。非対応値は描画時に RangeError。
+     * UI chrome locale (default `"en"`), forwarded to the embedded vertical VirtualScroll (its bar's
+     * names and the 0-row / all-frozen / degenerate-band empty state) and the horizontal bar (the
+     * names of the bar, its thumb and its arrows). An unsupported value throws a RangeError at render.
+     * UI クロームロケール (既定 `"en"`)。内蔵の縦 VirtualScroll (バーの名前と 0 行・全行固定・退化帯の
+     * 空状態) と横バー (バー・つまみ・矢印の名前) へ転送。非対応値は描画時に RangeError。
      */
     locale?: VirtualScrollLocale
     /**
@@ -605,9 +605,7 @@ const EMPTY_PLACED_COLUMNS: PlacedColumn[] = []
 const collectVisibleColumns = (startCol: number, endCol: number, getColWidth: (col: number) => number, colTree: ReturnType<typeof useFenwickMapTree>, maxColumns: number): { columns: PlacedColumn[]; widthUpdates: Array<{ index: number; value: number }>; truncated: number } => {
     const columns: PlacedColumn[] = []
     const widthUpdates: Array<{ index: number; value: number }> = []
-    if (endCol < startCol) {
-        return { columns, widthUpdates, truncated: 0 }
-    }
+    // 呼び出し元は空窓 (start > end) を先に除くので、ここへ来る窓は 1 列以上
     const startPrefix = colTree.prefixSum(startCol, { materializeOption: { materialize: false } })
     // 窓先頭の絶対 left から幅を積む O(k) 走査 (列ごとの prefixSum O(k·log n) を回避 — 行 memo と同型)
     let runningLeft = startPrefix.cumulative - startPrefix.currentValue
@@ -850,8 +848,8 @@ const VirtualGridInner = <T,>(
     const colTree = useFenwickMapTree(colCount, validatedGetColWidth, colTreeOptions)
 
     // ---- 幅エポック (木の内容バージョン): updateColSize / self-heal 適用で繰上げ、窓キー不変でも
-    //      配置 memo と列窓再計算を失効させる。行側は総高 (contentSize) を反応辺にするが、相殺
-    //      バッチリサイズ (総和不変) も拾えるようエポックはその厳密上位互換 ----
+    //      配置 memo と列窓再計算を失効させる。総幅は相殺バッチリサイズ (総和不変) で変わらないため
+    //      合図にならない (行側は VirtualScroll の木の版数が同じ役目を持つ) ----
     const [widthEpoch, setWidthEpoch] = useState(0)
 
     // ---- 凍結帯 (設計 §8) — 形状検証は fail-fast、colCount 超過だけは動的クランプ (シート
@@ -982,7 +980,7 @@ const VirtualGridInner = <T,>(
     /** Anchor the DOM currently shows (updated post-commit in the layout effect). / DOM が現在表示中のアンカー (commit 後の layout effect で更新)。 */
     const committedAnchorRef = useRef(0)
 
-    const [totalWidth, setTotalWidth] = useState(() => colTree.getTotal() ?? 0)
+    const [totalWidth, setTotalWidth] = useState(() => colTree.getTotal())
     const totalWidthRef = useRef(totalWidth)
     totalWidthRef.current = totalWidth
     /** Mirrors the tree total into state+ref immediately (same tick — drag loops clamp fresh). / 木総幅を state + ref へ即時反映 (同 tick — ドラッグループが新鮮にクランプ)。 */
@@ -1715,11 +1713,14 @@ const VirtualGridInner = <T,>(
     // ---- liveRegion (2D — 文言は消費側所有、静定デバウンス) ----
     const [liveMessage, setLiveMessage] = useState("")
     const liveTimerRef = useRef<number | null>(null)
+    // 埋め込みの一覧はアンマウントで待っていた範囲の通知を同期で配る (取りこぼさないため)。それはグリッド自身の後始末の後に
+    // 届くので、アンマウントの後は読み上げを予約しない (予約すると消費側の buildMessage がアンマウントの後に走る)
+    const isLiveRegionClosedRef = useRef(false)
     const liveRegionRef = useRef(liveRegion)
     liveRegionRef.current = liveRegion
     const scheduleLiveMessage = useCallback(() => {
         const options = liveRegionRef.current
-        if (options === undefined) {
+        if (options === undefined || isLiveRegionClosedRef.current) {
             return
         }
         // 不正な debounceMs は黙って既定へ読み替えず読み上げを無効化する (警告は下の effect が 1 回だけ出す)
@@ -1734,10 +1735,8 @@ const VirtualGridInner = <T,>(
             liveTimerRef.current = null
             const range = buildRange()
             if (range !== null) {
-                setLiveMessage((prev) => {
-                    const next = options.buildMessage(range)
-                    return next === prev ? prev : next
-                })
+                // 同じ文言の再設定は React が Object.is で捨てる (再描画しない) ので、比べずに書く (行側のライブリージョンと同じ)
+                setLiveMessage(options.buildMessage(range))
             }
         }, debounce)
     }, [buildRange])
@@ -1750,14 +1749,16 @@ const VirtualGridInner = <T,>(
             Logger.warn(`[VirtualGrid] liveRegion.debounceMs must be a finite number >= 0, received ${liveDebounceMs}. Announcements are disabled.`)
         }
     }, [hasLiveRegion, liveDebounceValid, liveDebounceMs])
-    useEffect(
-        () => () => {
+    useEffect(() => {
+        // StrictMode の二重マウント (後始末の後に再び effect) でも読み上げを再開できるよう、本体で開き直す
+        isLiveRegionClosedRef.current = false
+        return () => {
+            isLiveRegionClosedRef.current = true
             if (liveTimerRef.current !== null) {
                 window.clearTimeout(liveTimerRef.current)
             }
-        },
-        [],
-    )
+        }
+    }, [])
     useEffect(() => {
         scheduleLiveMessage()
     }, [columnWindow, scheduleLiveMessage])
@@ -1849,9 +1850,10 @@ const VirtualGridInner = <T,>(
                 if (found.cumulative === bandStart) {
                     return { row: rowAnchor.index + effectiveFrozenRows, col: minmax(found.index + 1, 0, colCount - 1), offsetX: 0, offsetY: rowAnchor.offsetPx }
                 }
+                // 見つけた列の左端は木から読み直す (探索の結果の型は列が無い場合の undefined を含むため)
+                const column = colTree.prefixSum(found.index, { materializeOption: { materialize: false } })
                 // 行はシフト空間 → フル行空間へ +R 翻訳 (行凍結設計 §3 — 復元側は −R で往復恒等)
-                const colLeft = (found.cumulative ?? 0) - (found.currentValue ?? 0)
-                return { row: rowAnchor.index + effectiveFrozenRows, col: found.index, offsetX: Math.max(0, bandStart - colLeft), offsetY: rowAnchor.offsetPx }
+                return { row: rowAnchor.index + effectiveFrozenRows, col: found.index, offsetX: Math.max(0, bandStart - (column.cumulative - column.currentValue)), offsetY: rowAnchor.offsetPx }
             },
             getViewportSize: () => ({ width: viewportRef.current.width, height: viewportRef.current.height }),
             // 縦はインセット込みの行側 getContentSize を単一情報源にする (range.totalHeight は木総高のみ)。
@@ -2003,7 +2005,7 @@ const VirtualGridInner = <T,>(
                     onScroll={(request, previous) => {
                         // バー操作は手動横入力 — 列アンカーの張りを解除する
                         pendingColAnchorRef.current = null
-                        return applyHxRef.current(typeof request === "function" ? request(previous ?? hxRef.current) : request)
+                        return applyHxRef.current(typeof request === "function" ? request(previous) : request)
                     }}
                     // バー固有の設定は縦バー (内包 VirtualScroll へ scrollBarOptions を全量透過) と同じ値を
                     // 横バーへも渡す — 片方のバーにだけ効く設定面を作らない