@aiquants/virtualscroll 3.9.2 → 3.10.0

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
     /**

package/src/VirtualScroll.tsx

@@ -4,7 +4,7 @@ import { resolveVirtualScrollLabels, type VirtualScrollLabelOverrides, type Virt
 import { Logger } from "./logger.ts"
 import { ScrollPane, type ScrollPaneContentInsets, type ScrollPaneHandle, type ScrollPaneProps } from "./ScrollPane.tsx"
 import { useFenwickMapTree } from "./useFenwickMapTree.ts"
-import { minmax } from "./utils.ts"
+import { keepFocusOnPress, minmax } from "./utils.ts"
 
 /**
  * Represents the current state of the rendered range and scroll metrics.
@@ -196,21 +196,23 @@ export type VirtualScrollScrollBarOptions = {
     /** Whether the arrow buttons scroll (default `true`). / 矢印ボタンによるスクロールを許可するかどうか (既定 `true`)。 */
     enableArrowButtons?: boolean
     /**
-     * Whether the scrollbar's arrow buttons are Tab stops (default `true`). Set it to `false` when
-     * the host already provides keyboard scrolling (roving row focus with Arrow / Page / Home / End):
-     * the arrows then only add two redundant Tab stops per bar — native scrollbars are never Tab
-     * stops either. `false` changes `tabIndex` alone (`-1`): the arrows stay pointer-operable and
-     * named, and Enter / Space still scroll when one is focused from script.
-     * The default stays `true` because the rows are not Tab stops, so without a host keyboard model
-     * the arrows are the only scrolling control a keyboard user can reach with Tab. Full contract:
+     * Whether the scroll chrome is the keyboard user's scrolling control (default `true`), or pointer-only because the
+     * host scrolls the list by keyboard itself (`false`: roving row focus with Arrow / Page / Home / End).
+     * `true`: the scrollbar is a named `role="scrollbar"` with a named `role="slider"` thumb, and its arrows (and the
+     * visible scroll-to-edge pills) are Tab stops — the rows are not Tab stops, so without a host keyboard model they are
+     * the only scrolling controls a keyboard user can reach with Tab.
+     * `false`: the scrollbar and the scroll-to-edge pills become pointer-only, like a native scrollbar: both carry
+     * `aria-hidden="true"`, nothing in them is a Tab stop, and a press on them never moves focus (neither onto them nor
+     * away from where the host put it); pointer scrolling and the pills' clicks are unchanged. Full contract:
      * `ScrollBarProps["enableArrowButtonTabStops"]`.
-     * スクロールバーの矢印ボタンを Tab の止まり先にするかどうか (既定 `true`)。ホストがキーボード
-     * スクロールを既に提供する場合 (行のロービングフォーカスと矢印 / Page / Home / End) に `false` —
-     * 矢印はバー 1 本あたり冗長な Tab の止まり先を 2 つ足すだけになるため (ネイティブのスクロールバーも
-     * Tab の止まり先にならない)。`false` が変えるのは `tabIndex` (`-1`) だけで、ポインタ操作・
-     * アクセシブルネームと、スクリプトからフォーカスした矢印の Enter / Space は維持。既定が `true`
-     * なのは、行が Tab の止まり先ではないため、ホストのキーボードモデルが無ければ矢印がキーボード
-     * 利用者の Tab で届く唯一のスクロール操作部品だから。契約の全文は
+     * スクロールの部品がキーボード利用者のスクロール操作部品か (既定 `true`)、ホストが一覧のキーボードスクロールを
+     * 自分で持つためポインタ専用か (`false`: 行のロービングフォーカスと矢印 / Page / Home / End) の指定。
+     * `true`: スクロールバーは名前付きの `role="scrollbar"` で名前付きの `role="slider"` のつまみを持ち、矢印 (と見えている
+     * 端へ戻るピル) は Tab の止まり先 — 行は Tab の止まり先ではないため、ホストのキーボードモデルが無ければ Tab で届く
+     * 唯一のスクロール操作部品。
+     * `false`: スクロールバーと端へ戻るピルはネイティブのスクロールバーと同じくポインタ専用になる。どちらも
+     * `aria-hidden="true"` を持ち、中に Tab の止まり先は無く、押下はフォーカスを動かさない (部品へも、ホストが置いた
+     * 場所の外へも)。ポインタのスクロールとピルの click は変わらない。契約の全文は
      * `ScrollBarProps["enableArrowButtonTabStops"]`。
      */
     enableArrowButtonTabStops?: boolean
@@ -314,12 +316,12 @@ 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 live-region wording and its language are consumer-owned: the package's
-     * built-in catalog (`locale` / `labels`) covers only the seven chrome strings (scrollbar arrow
-     * aria-labels, the scroll-to-edge pills and the empty state), never announcements.
+     * built-in catalog (`locale` / `labels`) covers only the eleven chrome strings (the scrollbar's
+     * accessible names, the scroll-to-edge pills and the empty state), never announcements.
      * 読み上げ文言を組み立てる。可視範囲が静定した後に呼ばれ、前回と同じ文字列なら DOM を
      * 触らない (再読み上げしない)。`""` を返すとリージョンを空にする。読み上げの文面と言語は
-     * 消費側の所有物 — パッケージの内蔵カタログ (`locale` / `labels`) が扱うのはクローム 7 文言
-     * (スクロールバー矢印の aria-label、端スクロールピル、空状態) だけで、読み上げは対象外。
+     * 消費側の所有物 — パッケージの内蔵カタログ (`locale` / `labels`) が扱うのはクローム 11 文言
+     * (スクロールバーのアクセシブルネーム、端スクロールピル、空状態) だけで、読み上げは対象外。
      *
      * @param range - The settled visible range / 静定した可視範囲
      * @returns Announcement text / 読み上げ文言
@@ -428,11 +430,11 @@ export type VirtualScrollProps<T> = {
      */
     liveRegion?: VirtualScrollLiveRegionOptions
     /**
-     * UI chrome locale of the built-in strings (default `"en"`): the scrollbar arrow aria-labels,
-     * the scroll-to-edge pills and the empty-state text. Live-region wording is not affected (see
+     * UI chrome locale of the built-in strings (default `"en"`): the scrollbar's accessible names
+     * (the bar, its thumb and its arrows), the scroll-to-edge pills and the empty-state text. Live-region wording is not affected (see
      * {@link VirtualScrollLiveRegionOptions.format}). An unsupported value throws a RangeError at
      * render; no language negotiation happens.
-     * 内蔵文言 (スクロールバー矢印の aria-label、端スクロールピル、空状態文言) の UI クロームロケール
+     * 内蔵文言 (スクロールバーのアクセシブルネーム — バー・つまみ・矢印 —、端スクロールピル、空状態文言) の UI クロームロケール
      * (既定 `"en"`)。ライブリージョンの文言には影響しない ({@link VirtualScrollLiveRegionOptions.format}
      * 参照)。非対応値は描画時に RangeError、言語ネゴシエーションなし。
      */
@@ -765,14 +767,25 @@ type ItemsWrapperProps = {
  * render anchor is a whole number of device px — for example when every row height is a multiple of a lattice L with
  * L × ratio a whole number (L = 4 px at ratios in quarter steps).
  *
+ * The wrapper sits in `.aqvs-items-boundary`, its containing block and a relayout boundary: a positioned box with size and
+ * layout containment that is neither a flex nor a grid item, attached to the top, left and right padding edges of the pane
+ * content (so the wrapper keeps its position and width) with a height of 0. A step that mounts or unmounts rows therefore
+ * lays out from that box instead of from the document root. The rows overflow it unclipped, as ink overflow that is not
+ * part of the pane content's scrollable area, and the box takes no hit test of its own.
+ *
  * 行ラッパー。`translateY` で動かす合成層 (`will-change: transform`) で、平行移動は描くウィンドウの装置の画素の格子へ
  * `snapEdge` の側で揃える (`snapToDevicePixelGrid`。比は `usePaintingDevicePixelRatio` が描画の中で読むので、自分の
  * ウィンドウの文書に描いた一覧は最初の確定から揃う)。揃えるのは層の平行移動だけ。層の中の行は厳密なレイアウトの位置に
  * 描かれ、角の丸い枠線・輪・輪郭はそこで滲む。行が装置の画素の整数から始まるのは、描画のアンカーからの行の位置が装置 px の
  * 整数のときだけ (例: どの行の高さも、L × 比が整数になる格子 L の倍数のとき。比が 4 分の 1 刻みなら L = 4px)。
  *
+ * ラッパーは包含ブロックで配置の境界の `.aqvs-items-boundary` の中に置く。位置指定され、大きさと配置を封じ込め、flex の子でも
+ * grid の子でもない箱で、ペインの中身のパディングの上・左・右の辺に付き (ラッパーの位置と幅は変わらない)、高さは 0。行を足し引き
+ * する 1 段の配置は、文書の根ではなくこの箱から始まる。行は箱から切り取られずにはみ出し (ペインの中身のスクロールできる範囲に
+ * 数えないインクのはみ出し)、箱自身は当たり判定を取らない。
+ *
  * @param props - The exact translate, the edge it keeps and the wrapped rows / 厳密な平行移動・守る端・包む行
- * @returns The wrapper element / ラッパーの要素
+ * @returns The boundary box holding the wrapper element / ラッパーの要素を包む境界の箱
  * @throws {Error} When the wrapper attaches to a document without a window (see `usePaintingDevicePixelRatio`) / ウィンドウを持たない文書へ取り付いたとき (`usePaintingDevicePixelRatio` を参照)
  * @throws {RangeError} When the painting window reports a ratio that is not a finite number > 0 (see `snapToDevicePixelGrid`) / 描くウィンドウの比が 0 より大きい有限数でないとき (`snapToDevicePixelGrid` を参照)
  */
@@ -785,9 +798,13 @@ const ItemsWrapper = ({ translateY, snapEdge, children }: ItemsWrapperProps) =>
     // ❗ 層の様式は will-change: transform だけ。perspective や 3D の変換を足すと Chromium は描画の切り取り (cull rect) を
     // 外して描くが、行を非 2D の変換の下で合成するので画素比によっては層ごと再標本化する (実測: 比 1.25 の明色で選択の輪と
     // フォーカスの輪の間の帯が混ざる)。窓をずらす 1 段がはみ出しを切る中身の行を描き直す費用は、その代わりに受け入れる
+    // ❗ ペインの中身は flex の子で配置の境界になれない。境界の箱を挟まないと、行を足し引きする 1 段の配置が毎回文書の根から
+    // 始まる (実測: 4 倍の CPU で 1 段の配置の時間のすべてが文書の根から)
     return (
-        <div ref={attach} className="aqvs-items-wrapper" style={{ top: 0, transform: `translateY(${wrapperTranslateY}px)`, willChange: "transform" }}>
-            {children}
+        <div className="aqvs-items-boundary">
+            <div ref={attach} className="aqvs-items-wrapper" style={{ top: 0, transform: `translateY(${wrapperTranslateY}px)`, willChange: "transform" }}>
+                {children}
+            </div>
         </div>
     )
 }
@@ -1000,9 +1017,72 @@ const computeRenderingRangesHuge = (effectiveScrollPosition: number, viewportSiz
  * 高精度タイムスタンプを可能なら取得。
  */
 /**
- * Calculates rendering boundaries from current scroll metrics.
+ * The first visible row at a logical scroll position (`resolveVisibleStartRow`).
+ *
+ * 論理スクロール位置での先頭の可視行 (`resolveVisibleStartRow`)。
+ */
+export type VisibleStartRow = {
+    /** Index of the first visible row / 先頭の可視行の index */
+    readonly index: number
+    /** Logical top of that row (px); `position - top` is the part hidden above the viewport top / その行の論理上端 (px)。`position - top` がビューポートの上端より上に隠れた量 */
+    readonly top: number
+}
+
+/**
+ * The part of the Fenwick tree `resolveVisibleStartRow` reads.
+ *
+ * `resolveVisibleStartRow` が読む Fenwick 木の部分。
+ */
+type VisibleStartRowTree = Pick<ReturnType<typeof useFenwickMapTree>, "findIndexAtOrAfter" | "prefixSum">
+
+/** Tree reads that only look the rows up, never materialising them / 行を引くだけで具現化しない木の読み方 */
+const LOOKUP_ONLY = { materializeOption: { materialize: false } } as const
+
+/**
+ * Resolves the first visible row at a logical scroll position by the visible-start boundary rule — the one rule that
+ * `scrollTo` pins, `getScrollAnchor` reports, `updateItemSize` compensates above and `computeRenderingRanges` renders from:
+ *
+ * - the row whose span contains the position: `top <= position < top + height`;
+ * - a row whose bottom equals the position lies entirely above the viewport, so the next row starts exactly there and is the
+ *   first visible row, at offset 0;
+ * - at the end, the last row stays the first visible row (the end clamp): when the position equals its bottom, and when the
+ *   position lies past the end of the content (a transient after the list shrinks, before the pane clamps).
+ *
+ * Module-level export (NOT in the package barrel).
+ *
+ * 先頭の可視行を、可視の先頭の境界の規則で論理スクロール位置から解決する処理。`scrollTo` が留め、`getScrollAnchor` が知らせ、
+ * `updateItemSize` がその上の変化を補正し、`computeRenderingRanges` が描き始める、ただ 1 つの規則。
+ *
+ * - 位置を含む行 (`上端 <= 位置 < 上端 + 高さ`)。
+ * - 下端が位置に一致する行は丸ごとビューポートの上にあるので、ちょうどそこから始まる次の行がオフセット 0 で先頭の可視行。
+ * - 末尾では最後の行が先頭の可視行のまま (末尾のクランプ)。位置がその下端に一致するときと、位置が中身の末尾を越えるとき
+ *   (一覧が縮んでからペインがクランプするまでの過渡状態)。
+ *
+ * モジュールレベル export (バレル非公開)。
  *
- * 現在のスクロール情報から描画範囲を算出。
+ * @param fenwickTree - The row-height tree / 行の高さの木
+ * @param position - Logical scroll position (px, 0 or more) / 論理スクロール位置 (px。0 以上)
+ * @param itemCount - Number of rows, 1 or more / 行の数 (1 以上)
+ * @returns The first visible row and its logical top / 先頭の可視行とその論理上端
+ */
+export const resolveVisibleStartRow = (fenwickTree: VisibleStartRowTree, position: number, itemCount: number): VisibleStartRow => {
+    const lastIndex = itemCount - 1
+    const found = fenwickTree.findIndexAtOrAfter(position, LOOKUP_ONLY)
+    if (found.index === -1 || found.index > lastIndex || found.cumulative === undefined || found.currentValue === undefined) {
+        const last = fenwickTree.prefixSum(lastIndex, LOOKUP_ONLY)
+        return { index: lastIndex, top: last.cumulative - last.currentValue }
+    }
+    if (found.cumulative === position && found.index < lastIndex) {
+        return { index: found.index + 1, top: found.cumulative }
+    }
+    return { index: found.index, top: found.cumulative - found.currentValue }
+}
+
+/**
+ * Calculates rendering boundaries from current scroll metrics. The visible rows start at the row `resolveVisibleStartRow`
+ * resolves.
+ *
+ * 現在のスクロール情報から描画範囲を算出。可視の行は `resolveVisibleStartRow` が解決する行から始まる。
  */
 export const computeRenderingRanges = (scrollPosition: number, viewportSize: number, overscanCount: number, itemSize: number, getItemHeight: (index: number) => number, fenwickTree: ReturnType<typeof useFenwickMapTree>, totalHeight: number) => {
     if (itemSize === 0) {
@@ -1013,31 +1093,9 @@ export const computeRenderingRanges = (scrollPosition: number, viewportSize: num
     if (itemSize >= Number.MAX_SAFE_INTEGER) {
         return computeRenderingRangesHuge(effectiveScrollPosition, viewportSize, overscanCount, itemSize, getItemHeight, fenwickTree, totalHeight, hasFiniteTotal)
     }
-    const { index: rawStartIndex, cumulative, currentValue } = fenwickTree.findIndexAtOrAfter(effectiveScrollPosition, { materializeOption: { materialize: false } })
-    const startIndex =
-        rawStartIndex === -1
-            ? (() => {
-                  // Fenwick がインデックスを返さない場合は末尾に合わせて開始位置を再計算
-                  if (viewportSize <= 0) {
-                      return itemSize - 1
-                  }
-                  return (cumulative ?? 0) < effectiveScrollPosition + (currentValue ?? 0) ? itemSize - 1 : 0
-              })()
-            : rawStartIndex
-    let visibleStartIndex = sanitizeIndex(startIndex, itemSize)
-
-    let visibleHeight = 0
-    if (rawStartIndex !== -1 && cumulative === effectiveScrollPosition) {
-        visibleStartIndex = sanitizeIndex(rawStartIndex + 1, itemSize)
-        visibleHeight = 0
-    } else if (visibleStartIndex === rawStartIndex && cumulative !== undefined && currentValue !== undefined) {
-        const itemTop = cumulative - currentValue
-        visibleHeight = itemTop - effectiveScrollPosition
-    } else {
-        const { cumulative: startCumulative, currentValue: startHeight } = fenwickTree.prefixSum(visibleStartIndex, { materializeOption: { materialize: false } })
-        const itemTop = (startCumulative ?? 0) - (startHeight ?? 0)
-        visibleHeight = itemTop - effectiveScrollPosition
-    }
+    const startRow = resolveVisibleStartRow(fenwickTree, effectiveScrollPosition, itemSize)
+    let visibleStartIndex = startRow.index
+    let visibleHeight = startRow.top - effectiveScrollPosition
 
     const initialOffset = visibleHeight
 
@@ -1321,6 +1379,8 @@ const VirtualScrollInner = <T,>(
     ref: React.Ref<VirtualScrollHandle>,
 ) => {
     const { width: scrollBarWidth, enableThumbDrag, enableTrackClick, enableArrowButtons, enableArrowButtonTabStops, enableScrollToTopBottomButtons, renderThumbOverlay, tapScrollCircleOptions } = scrollBarOptions ?? {}
+    // 合図はスクロールバーと同じ 1 つ (既定 true)。端へ戻るピルもバーと同じくポインタ専用になる
+    const scrollChromeIsPointerOnly = enableArrowButtonTabStops === false
     const resolvedLabels = useMemo(() => resolveVirtualScrollLabels(locale, labels), [locale, labels])
 
     const { enablePointerDrag, pointerDragInputs, enableKeyboardNavigation = true, enableEscapeRowReturn = false, wheelSpeedMultiplier, inertiaOptions, overscrollBehavior, clipItemHeight = false, resetOnGetItemHeightChange = false } = behaviorOptions ?? {}
@@ -1871,9 +1931,9 @@ const VirtualScrollInner = <T,>(
     const didApplyInitialOffsetRef = useRef(false)
 
     /**
-     * Flushes queued onScroll notifications.
+     * Applies `initialScrollOffset` once, as the highest-priority initial position, synchronising the pane and the logical position.
      *
-     * キューされた onScroll 通知を実行。
+     * `initialScrollOffset` を最優先の初期位置として一度だけ適用し、ペインと論理位置を同期させる effect。
      */
     useEffect(() => {
         if (didApplyInitialOffsetRef.current) return
@@ -2006,13 +2066,15 @@ const VirtualScrollInner = <T,>(
      * Updates the size of a specific item. Contract: after this call, `getItemHeight(index)` must
      * return the same `size`; `getItemHeight` is the source of truth, so rows inside the current
      * rendering window (including overscan) are otherwise reverted to the `getItemHeight` value by
-     * height reconciliation on the next render. A change above the first visible row moves the scroll
+     * height reconciliation on the next render. A change above the first visible row (the row of the pending
+     * alignment while one is pending, otherwise the row `resolveVisibleStartRow` resolves) moves the scroll
      * position by the same delta (layout-shift compensation), carries the remembered alignment along and
      * is reported through `onScrollAdjust` (`"item-resize"`) before this returns.
      *
      * 指定されたアイテムのサイズを更新。契約: 呼び出し後は `getItemHeight(index)` も同じ値を返すこと。
      * `getItemHeight` が正であるため、そうでない場合は描画ウィンドウ (オーバースキャン含む) 内の行が
-     * 次レンダーの高さ照合で `getItemHeight` の値へ巻き戻る。先頭の可視行より上の変化はスクロール位置を
+     * 次レンダーの高さ照合で `getItemHeight` の値へ巻き戻る。先頭の可視行 (保留中の揃えがあればその行、
+     * 無ければ `resolveVisibleStartRow` が解決する行) より上の変化はスクロール位置を
      * 同じ差だけ動かし (レイアウトシフトの補正)、覚えた揃えも一緒に動かして、戻る前に `onScrollAdjust`
      * (`"item-resize"`) で知らせる。
      *
@@ -2045,18 +2107,12 @@ const VirtualScrollInner = <T,>(
                 const currentScrollTop = latestScrollPositionRef.current
                 const insetsTop = normalizeInsets(contentInsets).top
                 const logicalScrollTop = toLogicalPositionWithInset(currentScrollTop, insetsTop)
-                // Use materialize: false for performance, we just need the index
-                const { index, cumulative } = fenwickTree.findIndexAtOrAfter(logicalScrollTop, { materializeOption: { materialize: false } })
-                // findIndexAtOrAfter は「下端(cumulative) >= scrollTop の最小 index」を返すため、
-                // アイテム index の下端がちょうど scrollTop に一致する場合、その行は完全にビューポート上方にある。
-                // computeRenderingRanges (cumulative === effectiveScrollPosition の特例) と同じく可視先頭を index+1 に補正する。
-                activeVisibleStartIndex = cumulative !== undefined && cumulative === logicalScrollTop ? index + 1 : index
+                activeVisibleStartIndex = resolveVisibleStartRow(fenwickTree, logicalScrollTop, itemCount).index
             }
 
-            // Allow for a small buffer in case of slight misalignments or stale refs
             // If the item is strictly above the visible start, it pushes content down.
-            // アイテムが（ほぼ）確実に可視領域より上にある場合、コンテンツ全体を押し下げます
-            if (activeVisibleStartIndex !== -1 && safeIndex < activeVisibleStartIndex && delta !== 0) {
+            // アイテムが可視領域より上にある場合、コンテンツ全体を押し下げます
+            if (safeIndex < activeVisibleStartIndex && delta !== 0) {
                 // Use latestScrollPositionRef as the source of truth for the current position
                 // to avoid reading stale DOM values during batched updates (e.g. multiple items resizing at once).
                 const currentPanePosition = latestScrollPositionRef.current
@@ -2203,9 +2259,15 @@ const VirtualScrollInner = <T,>(
     }, [itemCount, scrollToIndex])
 
     /**
-     * Scrolls to a raw offset while resolving to an index.
+     * Scrolls to a raw logical offset by pinning the first visible row there (`resolveVisibleStartRow`) with the offset of
+     * its top, so the pending alignment is the row `getScrollAnchor` reports: a position on a row boundary pins the row that
+     * starts there at offset 0, never the hidden row above it.
      *
-     * オフセットをインデックスに変換しつつスクロール。
+     * 論理オフセットへのスクロール。その位置の先頭の可視行 (`resolveVisibleStartRow`) を、その上端からのオフセットで留めるので、
+     * 保留中の揃えは `getScrollAnchor` が知らせる行になる。行の境界の位置では、そこから始まる行をオフセット 0 で留め、上に
+     * 隠れた行は留めない。
+     *
+     * @param newPosition - Logical position in px (floored, then clamped to the content) / 論理位置 (px。切り捨ててから中身の範囲へクランプ)
      */
     const scrollTo = useCallback(
         (newPosition: number) => {
@@ -2214,43 +2276,33 @@ const VirtualScrollInner = <T,>(
             }
             const total = fenwickTree.getTotal()
             const safePosition = minmax(Math.floor(newPosition), 0, total)
-            const { index, cumulative, currentValue } = fenwickTree.findIndexAtOrAfter(safePosition, { materializeOption: { materialize: false } })
-
-            // Calculate offset relative to item top to ensure precise positioning
-            // itemTop = cumulative - currentValue
-            const itemTop = (cumulative ?? 0) - (currentValue ?? 0)
-            const offset = itemTop - safePosition
-
-            scrollToIndex(index, { offset })
+            const startRow = resolveVisibleStartRow(fenwickTree, safePosition, itemCount)
+            scrollToIndex(startRow.index, { offset: startRow.top - safePosition })
         },
         [fenwickTree, itemCount, scrollToIndex],
     )
 
     /**
-     * Captures the current top-row anchor for exact position restore across remounts.
-     * 再マウント越しの厳密な位置復元のために、現在の先頭可視行アンカーを取得する処理。
+     * Captures the current top-row anchor for exact position restore across remounts: the first visible row that
+     * `resolveVisibleStartRow` resolves (the same row `scrollTo` pins) and the px its top is hidden above the viewport top.
+     * Returns `null` while the list is empty.
+     * 再マウント越しの厳密な位置復元のために、現在の先頭可視行アンカーを取得する処理。行は `resolveVisibleStartRow` が解決する
+     * 先頭の可視行 (`scrollTo` が留める行と同じ) で、空の一覧では `null`。
      *
      * offsetPx は「先頭可視行の上端がビューポート上端より上に隠れている px」(正の値、論理座標)。
      * 復元は initialScrollAnchor へそのまま渡す。可視ウィンドウの行高さは描画のたびに実測が
      * ツリーへ照合されるため、保存時点のアンカーは常に正確で、生 px と違い再マウント後の
      * 推定空間の違いに対して不変 (px 復元は深い位置で別の行に着地する)。
+     *
+     * @returns The anchor, or `null` without rows / アンカー (行が無ければ `null`)
      */
     const getScrollAnchor = useCallback((): { index: number; offsetPx: number } | null => {
         if (itemCount === 0) {
             return null
         }
         const logical = toLogicalPositionWithInset(latestScrollPositionRef.current, resolvedInsets.top)
-        const { index, cumulative, currentValue } = fenwickTree.findIndexAtOrAfter(logical, { materializeOption: { materialize: false } })
-        if (index === -1) {
-            // 末尾越え (推定総高さより深い位置) は最終行アンカーへ丸める
-            return { index: itemCount - 1, offsetPx: 0 }
-        }
-        if (cumulative === logical) {
-            // 行の下端がちょうどビューポート上端 = 可視先頭は次の行 (可視域計算と同じ境界規約)
-            return { index: minmax(index + 1, 0, itemCount - 1), offsetPx: 0 }
-        }
-        const itemTop = (cumulative ?? 0) - (currentValue ?? 0)
-        return { index, offsetPx: Math.max(0, logical - itemTop) }
+        const startRow = resolveVisibleStartRow(fenwickTree, logical, itemCount)
+        return { index: startRow.index, offsetPx: Math.max(0, logical - startRow.top) }
     }, [fenwickTree, itemCount, resolvedInsets.top])
 
     /**
@@ -2650,6 +2702,12 @@ const VirtualScrollInner = <T,>(
      * ポインタ軸の下限は CSS 側の `.aqvs-scroll-to-edge-overlay[data-visible="false"]
      * .aqvs-scroll-to-edge-button { pointer-events: none }` が担う (配布 CSS 未読込のホストでは
      * `inert` が、`inert` 未実装のブラウザでは CSS が、互いの穴を埋める)。
+     *
+     * ホストがキーボードのスクロールを持つ (`scrollBarOptions.enableArrowButtonTabStops: false`) と、ピルはスクロールバーと
+     * 同じくポインタ専用になる。オーバーレイは見えている間も `aria-hidden="true"` で、ピルは Tab 順に入らず、オーバーレイ
+     * が押下の既定動作を取り消すのでピルの押下はフォーカスを動かさない (click は届く)。
+     *
+     * @returns The overlay, or `null` without the pills / オーバーレイ (ピルを出さないなら `null`)
      */
     const renderOverlay = useCallback(() => {
         if (!enableScrollToTopBottomButtons) {
@@ -2658,16 +2716,17 @@ const VirtualScrollInner = <T,>(
 
         const isVisible = showScrollButtons && scrollDirection !== null
         const isTop = scrollDirection === "up"
+        const pillTabIndex = isVisible && !scrollChromeIsPointerOnly ? 0 : -1
 
         return (
-            <div className="aqvs-scroll-to-edge-overlay" data-visible={isVisible} inert={!isVisible}>
+            <div className="aqvs-scroll-to-edge-overlay" data-visible={isVisible} inert={!isVisible} aria-hidden={scrollChromeIsPointerOnly ? true : undefined} onPointerDown={scrollChromeIsPointerOnly ? keepFocusOnPress : undefined}>
                 {isTop ? (
                     <div className="aqvs-scroll-to-edge-button-container aqvs-scroll-to-edge-button-container-top">
                         <button
                             type="button"
                             className="aqvs-scroll-to-edge-button"
                             // 非表示中はタブ順から外す (inert 未実装ブラウザ向けの下限)
-                            tabIndex={isVisible ? 0 : -1}
+                            tabIndex={pillTabIndex}
                             onClick={(e) => {
                                 e.stopPropagation()
                                 isProgrammaticScrollRef.current = true
@@ -2683,7 +2742,7 @@ const VirtualScrollInner = <T,>(
                             type="button"
                             className="aqvs-scroll-to-edge-button"
                             // 非表示中はタブ順から外す (inert 未実装ブラウザ向けの下限)
-                            tabIndex={isVisible ? 0 : -1}
+                            tabIndex={pillTabIndex}
                             onClick={(e) => {
                                 e.stopPropagation()
                                 isProgrammaticScrollRef.current = true
@@ -2696,7 +2755,7 @@ const VirtualScrollInner = <T,>(
                 )}
             </div>
         )
-    }, [enableScrollToTopBottomButtons, showScrollButtons, scrollDirection, scrollToIndex, itemCount, resolvedLabels])
+    }, [enableScrollToTopBottomButtons, scrollChromeIsPointerOnly, showScrollButtons, scrollDirection, scrollToIndex, itemCount, resolvedLabels])
 
     // 量子化アンカー (fix: LayoutUnit/f32 精度対策)。行 top はコンテンツ絶対座標そのままではなく
     // 「絶対座標 - アンカー」で描画し、ラッパー側 translateY にアンカーを足し戻す。

package/src/labels.ts

@@ -1,14 +1,16 @@
 /**
  * @module labels
- * @description Built-in UI chrome label catalog of the package. Covers exactly the seven strings
- * the components render on their own: the ScrollBar arrow aria-labels, the VirtualScroll
+ * @description Built-in UI chrome label catalog of the package. Covers exactly the eleven strings
+ * the components render on their own: the ScrollBar accessible names (per orientation, the two
+ * arrows, the `role="scrollbar"` bar and its `role="slider"` thumb), the VirtualScroll
  * scroll-to-edge pill texts and the empty-state text. Live-region wording stays consumer-owned
  * (`liveRegion.format` / `liveRegion.buildMessage`) and is not part of this catalog. The default
  * locale is `"en"`; `"ja"` is the second locale. No language negotiation happens here: hosts map
  * `navigator.language` (or anything else) to a supported locale themselves.
  *
- * @description パッケージ内蔵の UI クローム文言カタログ。コンポーネント自身が描画する 7 文言
- * (ScrollBar 矢印の aria-label、VirtualScroll の端スクロールピル文言、空状態文言) だけを対象とし、
+ * @description パッケージ内蔵の UI クローム文言カタログ。コンポーネント自身が描画する 11 文言
+ * (向きごとの ScrollBar のアクセシブルネーム — 矢印 2 個・`role="scrollbar"` のバー・その `role="slider"` の
+ * つまみ —、VirtualScroll の端スクロールピル文言、空状態文言) だけを対象とし、
  * ライブリージョンの文言は利用側の所有 (`liveRegion.format` / `liveRegion.buildMessage`) で
  * 本カタログの対象外。既定ロケールは `"en"`、第 2 ロケールは `"ja"`。言語ネゴシエーションは行わず、
  * `navigator.language` 等から対応ロケールへの対応付けはホスト側の責務。
@@ -53,6 +55,30 @@ export type VirtualScrollLabels = {
      * 横 ScrollBar 終端 (右) 矢印ボタンの aria-label。
      */
     readonly scrollRight: string
+    /**
+     * aria-label of the vertical ScrollBar root (`role="scrollbar"`). Assistive technology appends
+     * the role ("scroll bar") itself, so the name carries only what tells the two bars apart.
+     * 縦 ScrollBar のルート (`role="scrollbar"`) の aria-label。ロール名 (スクロールバー) は支援技術が
+     * 付け足すため、名前は 2 本のバーを区別する情報のみ。
+     */
+    readonly verticalScrollBar: string
+    /**
+     * aria-label of the horizontal ScrollBar root (`role="scrollbar"`).
+     * 横 ScrollBar のルート (`role="scrollbar"`) の aria-label。
+     */
+    readonly horizontalScrollBar: string
+    /**
+     * aria-label of the vertical ScrollBar thumb (`role="slider"`), whose value is the scroll
+     * position.
+     * 縦 ScrollBar のつまみ (`role="slider"`) の aria-label。値はスクロール位置。
+     */
+    readonly verticalScrollThumb: string
+    /**
+     * aria-label of the horizontal ScrollBar thumb (`role="slider"`), whose value is the scroll
+     * position.
+     * 横 ScrollBar のつまみ (`role="slider"`) の aria-label。値はスクロール位置。
+     */
+    readonly horizontalScrollThumb: string
     /**
      * Text of the VirtualScroll scroll-to-top pill, shown when
      * `scrollBarOptions.enableScrollToTopBottomButtons` is on.
@@ -87,15 +113,32 @@ export type VirtualScrollLabelOverrides = { readonly [K in keyof VirtualScrollLa
  * overrides are validated against.
  * {@link VirtualScrollLabels} の全キー (カタログ順)。上書き検証に用いる閉じたキー集合。
  */
-export const VIRTUAL_SCROLL_LABEL_KEYS = ["scrollUp", "scrollDown", "scrollLeft", "scrollRight", "scrollToTop", "scrollToBottom", "noItems"] as const satisfies readonly (keyof VirtualScrollLabels)[]
+export const VIRTUAL_SCROLL_LABEL_KEYS = [
+    "scrollUp",
+    "scrollDown",
+    "scrollLeft",
+    "scrollRight",
+    "verticalScrollBar",
+    "horizontalScrollBar",
+    "verticalScrollThumb",
+    "horizontalScrollThumb",
+    "scrollToTop",
+    "scrollToBottom",
+    "noItems",
+] as const satisfies readonly (keyof VirtualScrollLabels)[]
 
 // satisfies は部分集合しか保証しないため、キー追加時の登録漏れを型で検出する
 const keysCoverEveryLabel: [Exclude<keyof VirtualScrollLabels, (typeof VIRTUAL_SCROLL_LABEL_KEYS)[number]>] extends [never] ? true : never = true
 void keysCoverEveryLabel
 
 /**
- * Frozen built-in catalogs per locale. `en` is the package's historical English wording.
- * ロケールごとの凍結済み内蔵カタログ。`en` はパッケージ従来の英語文言。
+ * Frozen built-in catalogs per locale. The arrow, pill and empty-state values of `en` are the
+ * package's historical English wording. The bar names state only the orientation, because
+ * assistive technology already reads the role as "scroll bar"; the thumb names state what the
+ * value measures.
+ * ロケールごとの凍結済み内蔵カタログ。`en` の矢印・ピル・空状態の値はパッケージ従来の英語文言。
+ * バーの名前は向きのみ (支援技術がロールを既に「スクロールバー」と読むため)、つまみの名前は値が
+ * 表すもの。
  */
 export const VIRTUAL_SCROLL_LABEL_CATALOGS: Readonly<Record<VirtualScrollLocale, VirtualScrollLabels>> = Object.freeze({
     en: Object.freeze({
@@ -103,6 +146,10 @@ export const VIRTUAL_SCROLL_LABEL_CATALOGS: Readonly<Record<VirtualScrollLocale,
         scrollDown: "Scroll down",
         scrollLeft: "Scroll left",
         scrollRight: "Scroll right",
+        verticalScrollBar: "Vertical",
+        horizontalScrollBar: "Horizontal",
+        verticalScrollThumb: "Vertical scroll position",
+        horizontalScrollThumb: "Horizontal scroll position",
         scrollToTop: "Top",
         scrollToBottom: "Bottom",
         noItems: "No items",
@@ -112,6 +159,10 @@ export const VIRTUAL_SCROLL_LABEL_CATALOGS: Readonly<Record<VirtualScrollLocale,
         scrollDown: "下へスクロール",
         scrollLeft: "左へスクロール",
         scrollRight: "右へスクロール",
+        verticalScrollBar: "縦方向",
+        horizontalScrollBar: "横方向",
+        verticalScrollThumb: "縦スクロール位置",
+        horizontalScrollThumb: "横スクロール位置",
         scrollToTop: "先頭へ",
         scrollToBottom: "末尾へ",
         noItems: "項目がありません",

package/src/styles/virtualscroll.css

@@ -329,6 +329,22 @@
   width: 100%;
 }
 
+/* 行ラッパーの包含ブロックで、配置の境界 (Chromium の relayout boundary)。窓をずらす 1 段が行を足し引きしても、配置はこの箱から
+ * 始まって箱の中で終わり、文書の根まで遡らない。境界になるには flex の子でも grid の子でもないことが要る (ペインの中身は flex の子
+ * なので、ラッパーの包含ブロックにしても境界にならない)。この箱は位置指定と、大きさと配置の封じ込めで境界になる。
+ * 箱はペインの中身のパディングの辺に付いて幅を合わせ、高さは 0 に固定する: 行は箱の外へはみ出して描かれ (描画は封じ込めないので、
+ * 切り取りはペインの中身の overflow: hidden のまま)、箱は当たり判定で背景 (background) の前に立たない。行のはみ出しは封じ込めで
+ * インクのはみ出しになるので、ペインの中身のスクロールできる範囲にも数えない。そのため、ブラウザが自分で行を見せるスクロール
+ * (オーバースキャンの行の中への Tab・ページ内検索) はペインの中身を動かせず、行の箱が外側のスクローラーの外にあればそちらを動かす */
+.aqvs-items-boundary {
+  position: absolute;
+  top: 0;
+  right: 0;
+  left: 0;
+  height: 0;
+  contain: size layout style;
+}
+
 .aqvs-items-wrapper {
   position: absolute;
   width: 100%;
@@ -547,15 +563,47 @@
   transition-timing-function: cubic-bezier(0.4, 0, 0.2, 1);
 }
 
-/* パッケージ全域・単一所有者 — 本 CSS 初の forced-colors 規則: グラデーション視覚は
- * forced-colors で平坦化され、輪郭なしではサークルが不可視になる (描画モード修正 —
- * 単体サークルにも輪郭が付くのは登記済みの挙動非変更デルタ)。 */
+/* 強制配色 (forced-colors: active) では、ブラウザがシステム色でない地色をどれも Canvas に置き換える (透明度は残す)。地色だけで
+ * 描く部品 (文字色も枠線も輪郭も持たない部品) は周りと区別できなくなるので、どれもここでシステム色の描き方を持つ
+ * (forcedColors.spec.tsx がこのファイルから地色だけで描く部品を導いて照合する)。
+ * - タップスクロールサークル: グラデーションの視覚は平坦になるので、輪郭で形を残す。
+ * - バーとトラック: 縁を GrayText の輪郭で描く (バーは矢印とトラックの下地、トラックはつまみが動く範囲)。
+ * - つまみ: ネイティブのスクロールバーと同じくシステム色で塗る。状態の規則 (ホバー・ドラッグ・無効) は同じ選択子でここに
+ *   言い直す: 詳細度が同じなので、後に置いたこちらが勝つ。forced-color-adjust: none はホストが塗ったシステム色でない地色を
+ *   Canvas へ消させない (つまみが溝と同じ色になって消えない)。
+ * - サンプルのビジュアルの光と棒: 引いた向きと量を示すので CanvasText で塗る。 */
 @media (forced-colors: active) {
   .aqvs-tap-scroll-circle {
     outline: 1px solid CanvasText;
     outline-offset: -1px;
     border-radius: 50%;
   }
+
+  .aqvs-scrollbar,
+  .aqvs-scrollbar-track {
+    outline: 1px solid GrayText;
+    outline-offset: -1px;
+  }
+
+  .aqvs-scrollbar-thumb {
+    forced-color-adjust: none;
+    background-color: CanvasText;
+  }
+
+  .aqvs-scrollbar-thumb[data-thumb-state="hover"],
+  .aqvs-scrollbar-thumb[data-thumb-state="dragging"] {
+    background-color: Highlight;
+  }
+
+  .aqvs-scrollbar-thumb[data-thumb-state="disabled"] {
+    background-color: GrayText;
+  }
+
+  .aqvs-sample-visual-highlight,
+  .aqvs-sample-visual-rod {
+    forced-color-adjust: none;
+    background-color: CanvasText;
+  }
 }
 
 /* 動きを減らす設定 (prefers-reduced-motion: reduce) では、パッケージが動かす部品はどれも遷移もアニメーションも持たず、