@aiquants/virtualscroll 3.0.0 → 3.1.1

package/src/VirtualScroll.tsx

@@ -148,6 +148,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"]
     /**
@@ -175,6 +203,50 @@ 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.
  *
@@ -220,6 +292,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
@@ -822,6 +912,15 @@ type VirtualScrollItemProps<T> = {
     clipItemHeight: boolean
     enableKeyboardNavigation: boolean
     onKeyDown: (event: React.KeyboardEvent<HTMLDivElement>, index: number) => void
+    /**
+     * Bubble-phase Escape handler for the row-return feature (undefined when disabled).
+     * 行復帰機能用の bubble フェーズ Escape ハンドラ (機能無効時は undefined)。
+     *
+     * ❗ 矢印キー (`onKeyDown` = capture) と**逆のフェーズ**なのが本質: capture で聞くと行内で
+     * 開いたドロップダウン等より先に Escape を奪ってしまう。bubble なら行内ウィジェットが
+     * `stopPropagation()` / `preventDefault()` で先約を主張できる。
+     */
+    onEscapeKeyDown?: (event: React.KeyboardEvent<HTMLDivElement>, index: number) => void
     onFocus: (index: number) => void
     registerItemRef: (index: number, node: HTMLDivElement | null) => void
 }
@@ -835,15 +934,20 @@ type VirtualScrollItemProps<T> = {
  * ユーザーが提供したアイテムコンポーネントを、配置スタイルとイベントハンドラでラップします。
  * Props が変更されていない場合の不要な再レンダリングを防ぐためにメモ化されています。
  */
-const VirtualScrollItem = React.memo(<T,>({ index, top, height, item, children, clipItemHeight, enableKeyboardNavigation, onKeyDown, onFocus, registerItemRef }: VirtualScrollItemProps<T>) => {
+const VirtualScrollItem = React.memo(<T,>({ index, top, height, item, children, clipItemHeight, enableKeyboardNavigation, onKeyDown, onEscapeKeyDown, onFocus, registerItemRef }: VirtualScrollItemProps<T>) => {
     const handleRef = useCallback((node: HTMLDivElement | null) => registerItemRef(index, node), [index, registerItemRef])
     const handleKeyDown = useCallback((e: React.KeyboardEvent<HTMLDivElement>) => onKeyDown(e, index), [index, onKeyDown])
+    const handleEscapeKeyDown = useCallback((e: React.KeyboardEvent<HTMLDivElement>) => onEscapeKeyDown?.(e, index), [index, onEscapeKeyDown])
     const handleFocus = useCallback(() => onFocus(index), [index, onFocus])
     const handlePointerDown = useCallback((e: React.PointerEvent<HTMLDivElement>) => {
         e.currentTarget.focus({ preventScroll: true })
     }, [])
 
     return (
+        // 行ラッパーの role は消費側の複合ウィジェット契約 (listbox / tree / grid — README「Composite widget
+        // roles」) の所有物で、パッケージが既定 role を課すと衝突する。キー/フォーカス結線は
+        // enableKeyboardNavigation の行ナビゲーション機構そのもの。
+        // biome-ignore lint/a11y/noStaticElementInteractions: role は消費側の複合ウィジェット契約の所有物 (上記)
         <div
             ref={handleRef}
             data-index={index}
@@ -857,6 +961,7 @@ const VirtualScrollItem = React.memo(<T,>({ index, top, height, item, children,
             tabIndex={enableKeyboardNavigation ? -1 : undefined}
             onPointerDown={enableKeyboardNavigation ? handlePointerDown : undefined}
             onKeyDownCapture={enableKeyboardNavigation ? handleKeyDown : undefined}
+            onKeyDown={enableKeyboardNavigation && onEscapeKeyDown ? handleEscapeKeyDown : undefined}
             onFocusCapture={enableKeyboardNavigation ? handleFocus : undefined}>
             {children(item, index)}
         </div>
@@ -894,12 +999,13 @@ const VirtualScrollInner = <T,>(
         horizontalKeyInputs,
         horizontalKeyStep = DEFAULT_HORIZONTAL_KEY_STEP,
         contentProps,
+        liveRegion,
     }: VirtualScrollProps<T>,
     ref: React.Ref<VirtualScrollHandle>,
 ) => {
     const { width: scrollBarWidth, enableThumbDrag, enableTrackClick, enableArrowButtons, enableScrollToTopBottomButtons, renderThumbOverlay, tapScrollCircleOptions } = scrollBarOptions ?? {}
 
-    const { enablePointerDrag, pointerDragInputs, enableKeyboardNavigation = true, wheelSpeedMultiplier, inertiaOptions, overscrollBehavior, clipItemHeight = false, resetOnGetItemHeightChange = false } = behaviorOptions ?? {}
+    const { enablePointerDrag, pointerDragInputs, enableKeyboardNavigation = true, enableEscapeRowReturn = false, wheelSpeedMultiplier, inertiaOptions, overscrollBehavior, clipItemHeight = false, resetOnGetItemHeightChange = false } = behaviorOptions ?? {}
 
     // viewportSize 未指定のときは ScrollPane が自分の帯を計測し、その値をこのコールバックで通知する。
     // 描画枚数 (computeRenderingRanges) とアライン計算 (scrollToIndex / ドリフト補正) はこの解決済み値を使う。
@@ -1956,6 +2062,47 @@ const VirtualScrollInner = <T,>(
         [enableKeyboardNavigation, itemCount, focusItemAtIndex, horizontalKeyInputs, horizontalKeyStep],
     )
 
+    const handleItemEscapeReturn = useCallback(
+        /**
+         * Returns focus from an element inside the row back to the row wrapper on Escape.
+         * 行内要素の Escape で行ラッパーへフォーカスを戻す処理。
+         *
+         * @param event - Keyboard event (bubble phase on the row wrapper) / 行ラッパー bubble フェーズのキーイベント
+         * @param index - Row index / 行インデックス
+         */
+        (event: React.KeyboardEvent<HTMLDivElement>, index: number) => {
+            if (event.key !== "Escape") {
+                return
+            }
+            // 行内ウィジェット (ドロップダウン等) が先に消費した Escape は尊重する。
+            // bubble フェーズなのでウィジェット側の preventDefault はここで必ず観測できる
+            // (stopPropagation されていればそもそもこのハンドラに届かない)
+            if (event.defaultPrevented) {
+                return
+            }
+            // IME 合成中の Escape は確定取消であり、フォーカス移動で奪ってはならない
+            if (event.nativeEvent.isComposing) {
+                return
+            }
+            // 行そのものにフォーカスがあるときの Escape の意味 (選択解除など) は消費側の所有物
+            if (event.target === event.currentTarget) {
+                return
+            }
+            // ❗ 編集可能なターゲット (input / textarea / select / contentEditable) の Escape は奪わない。
+            // ネイティブの既定動作 (例: Blink/WebKit は <input type="search"> を Escape でクリアする) は
+            // defaultPrevented に**現れない**ため、上のスクリプト先約の検査では守れない — ここで
+            // preventDefault すると検索欄のクリアを黙殺したうえ編集途中のフォーカスまで奪う (実 Chromium で実証)
+            const target = event.target as HTMLElement
+            if (target instanceof HTMLInputElement || target instanceof HTMLTextAreaElement || target instanceof HTMLSelectElement || target.isContentEditable) {
+                return
+            }
+            // 消費の作法は矢印キーと同じ: preventDefault のみで伝播は止めない
+            event.preventDefault()
+            focusItemAtIndex(index)
+        },
+        [focusItemAtIndex],
+    )
+
     const handleItemFocus = useCallback(
         (index: number) => {
             if (!enableKeyboardNavigation) {
@@ -2157,6 +2304,7 @@ const VirtualScrollInner = <T,>(
                     clipItemHeight={clipItemHeight}
                     enableKeyboardNavigation={enableKeyboardNavigation}
                     onKeyDown={handleItemKeyDown}
+                    onEscapeKeyDown={enableEscapeRowReturn ? handleItemEscapeReturn : undefined}
                     onFocus={handleItemFocus}
                     registerItemRef={registerItemRef}>
                     {children}
@@ -2220,6 +2368,8 @@ const VirtualScrollInner = <T,>(
         getItemHeight,
         handleItemFocus,
         handleItemKeyDown,
+        enableEscapeRowReturn,
+        handleItemEscapeReturn,
         issueCompensationScroll,
         registerItemRef,
         renderingEndIndex,
@@ -2311,6 +2461,53 @@ const VirtualScrollInner = <T,>(
         currentRangeRef.current = currentRange
     }, [currentRange])
 
+    // ライブリージョンの読み上げ文言。liveRegion 未指定なら常に空のまま (リージョン自体を描画しない)
+    const [liveAnnouncement, setLiveAnnouncement] = useState("")
+    // format は消費側がインラインで渡すのが普通なので ref 越しに読む (identity 変化でデバウンスを
+    // 巻き戻さない — 巻き戻すと親の毎レンダーでタイマーが再スタートし、永遠に読み上げない)
+    const liveRegionRef = useRef(liveRegion)
+    useLayoutEffect(() => {
+        liveRegionRef.current = liveRegion
+    }, [liveRegion])
+    const liveRegionDebounceMs = liveRegion?.debounceMs ?? 400
+    const isLiveRegionDebounceValid = Number.isFinite(liveRegionDebounceMs) && liveRegionDebounceMs >= 0
+    const hasLiveRegion = liveRegion !== undefined
+
+    useEffect(() => {
+        // 目的: 不正な debounceMs を黙って既定へ読み替えず、機能を無効化したうえで 1 回だけ警告する。
+        // 依存関係: hasLiveRegion, isLiveRegionDebounceValid, liveRegionDebounceMs
+        if (hasLiveRegion && !isLiveRegionDebounceValid) {
+            Logger.warn(`[VirtualScroll] liveRegion.debounceMs must be a finite number >= 0, received ${liveRegionDebounceMs}. Announcements are disabled.`)
+        }
+    }, [hasLiveRegion, isLiveRegionDebounceValid, liveRegionDebounceMs])
+
+    useEffect(() => {
+        // 目的: 可視範囲の静定後にライブリージョンの文言を更新する (trailing デバウンス)。
+        // 範囲が動くたびにこの effect が張り直され、タイマーが再スタートする = 最後の変化から
+        // debounceMs 後に 1 回だけ発火する。
+        // 依存関係: hasLiveRegion, isLiveRegionDebounceValid, liveRegionDebounceMs,
+        //           visibleStartIndex, visibleEndIndex, itemCount
+        if (!(hasLiveRegion && isLiveRegionDebounceValid)) {
+            // ❗ 無効化時は残留文言を消す。消さないと、prop を外して再度付けたとき (実行時トグル) に
+            // 古い範囲の文言が role="status" 要素ごと同期的に再挿入され、新規挿入されたライブ
+            // リージョンを内容ごと読み上げる AT が**過去の位置**を読む。同値なら React が bail out
+            // するため、通常レンダーでのコストは無い
+            setLiveAnnouncement("")
+            return
+        }
+        const timerId = setTimeout(() => {
+            const format = liveRegionRef.current?.format
+            if (!format) {
+                return
+            }
+            const text = format({ visibleStartIndex, visibleEndIndex, itemCount })
+            // 同一文言の再 set は React 自身が bail out する (Object.is 一致で再レンダーしない) ため、
+            // ここで比較ガードを持つ必要は無い — 持っても等価変異になり検証不能な飾りになるだけ
+            setLiveAnnouncement(text)
+        }, liveRegionDebounceMs)
+        return () => clearTimeout(timerId)
+    }, [hasLiveRegion, isLiveRegionDebounceValid, liveRegionDebounceMs, visibleStartIndex, visibleEndIndex, itemCount])
+
     useImperativeHandle(
         ref,
         () => ({
@@ -2338,7 +2535,8 @@ const VirtualScrollInner = <T,>(
 
     const totalContentHeight = fenwickTree.getTotal() + resolvedInsets.top + resolvedInsets.bottom
 
-    return (
+    // ライブリージョン無効時はペインをそのまま根要素として返す (既存消費者の DOM 形状を変えない)
+    const pane = (
         <ScrollPane
             ref={scrollPaneRef}
             contentSize={totalContentHeight}
@@ -2370,6 +2568,21 @@ const VirtualScrollInner = <T,>(
             {renderVisibleItems}
         </ScrollPane>
     )
+
+    if (!hasLiveRegion) {
+        return pane
+    }
+    return (
+        <>
+            {pane}
+            {/* ペインの**兄弟**として描画する: ペイン内部 (スクロール座標系) に置くと transform 配下の
+                aria-live を無視する AT があり、ペインの子構成 (行 / 背景 / オーバーレイ) の契約も汚す。
+                視覚的には .aqvs-live-region (絶対配置 1px クリップ) で完全に隠れ、レイアウトに影響しない */}
+            <div className="aqvs-live-region" role="status" aria-live="polite" aria-atomic="true" data-aqvs-live-region="">
+                {liveAnnouncement}
+            </div>
+        </>
+    )
 }
 
 /**

package/src/index.ts

@@ -5,6 +5,7 @@
  * 可変なアイテム高さに対応したReact用の高性能仮想スクロールコンポーネント。
  */
 
+export { createResidualQuantizer, type ResidualQuantizer, type ResidualQuantizerOptions } from "./residualQuantizer.ts"
 export { computeAutoTapScrollMaxSpeedMultiplier, computeTapScrollSpeed, ScrollBar, type ScrollBarProps, type ScrollBarTapCircleOptions, type ScrollBarThumbOverlayRenderProps, TAP_SCROLL_SPEED_DEFAULTS, type TapScrollSpeedInput } from "./ScrollBar.tsx"
 export { ScrollPane, type ScrollPaneContentInsets, type ScrollPaneHandle, type ScrollPaneInertiaOptions, type ScrollPaneProps } from "./ScrollPane.tsx"
 export type { TapScrollCircleRenderProps } from "./TapScrollCircle.tsx"
@@ -18,6 +19,8 @@ export {
     VirtualScroll,
     type VirtualScrollBehaviorOptions,
     type VirtualScrollHandle,
+    type VirtualScrollLiveRegionOptions,
+    type VirtualScrollLiveRegionRange,
     type VirtualScrollProps,
     type VirtualScrollRange,
     type VirtualScrollScrollBarOptions,

package/src/residualQuantizer.ts

@@ -0,0 +1,133 @@
+/**
+ * @module residualQuantizer
+ * @description Residual-carrying delta quantizer for consumers that snap scroll positions to a
+ * fixed quantum (row height, column width). High-resolution trackpads emit many sub-quantum
+ * deltas; a consumer that rounds each delta independently rounds every one of them to zero and
+ * the list never moves. This accumulator carries the sub-quantum remainder across events and
+ * emits whole quanta as soon as they accumulate.
+ *
+ * @description スクロール位置を固定の量子 (行高・列幅) へスナップする消費側のための、
+ * 残差持ち越し型のデルタ量子化器。高解像度トラックパッドは 1 量子未満のデルタを大量に発行するため、
+ * イベントごとに独立して丸める消費側では**すべてが 0 に丸められ、ゆっくり撫でると 1px も動かない**。
+ * 本量子化器は量子未満の余りをイベントを跨いで持ち越し、貯まった分だけ量子単位で放出する。
+ *
+ * ❗ **時間は扱わない (意図的)。** アイドルタイムアウトでの残差破棄は「いつ捨てるか」の方針が
+ * 消費側の UI ごとに異なり、内蔵すると幽霊スクロール (古い残差が後から発火) か不感帯のどちらかを
+ * パッケージが押し付けることになる。時間起点の破棄が要る消費側は、自前のタイマーから
+ * {@link ResidualQuantizer.reset} を呼ぶこと。既定の防御は**方向反転での残差破棄**のみで、
+ * これは時間に依存せず「逆へ動かし始めたのに古い残差が先に順方向へ発火する」事故だけを塞ぐ。
+ */
+
+/**
+ * Options for {@link createResidualQuantizer}.
+ * {@link createResidualQuantizer} のオプション。
+ */
+export type ResidualQuantizerOptions = {
+    /**
+     * Quantum (px) each emission is a multiple of. Must be finite and positive — anything else
+     * throws at creation time (fail fast; a silent default would hide the caller's bug).
+     * 放出量の単位となる量子 (px)。有限かつ正であること — それ以外は生成時に throw する
+     * (Fail Fast。既定値へ黙って読み替えると呼び出し側のバグを隠す)。
+     */
+    quantum: number
+    /**
+     * Drop the carried residue when the incoming delta's direction opposes it (default: `true`).
+     * Without this, scrolling +20px (quantum 24, nothing emitted) and then reversing emits the
+     * first reverse quantum "late" — the stale forward residue eats part of the reverse motion.
+     * 入力デルタの向きが持ち越し残差と逆のとき残差を捨てる (既定 `true`)。捨てないと、
+     * +20px (量子 24 で未放出) の後に反転したとき、古い順方向残差が逆方向の動きを食い、
+     * 最初の逆方向量子の発火が「遅れて」体感される。
+     */
+    resetOnDirectionChange?: boolean
+}
+
+/**
+ * A quantizer instance. One instance per quantized axis — sharing one across axes mixes residues.
+ * 量子化器インスタンス。量子化する軸ごとに 1 つ持つこと — 軸間で共有すると残差が混線する。
+ */
+export type ResidualQuantizer = {
+    /**
+     * Accumulates `delta` and returns the emission: a multiple of the quantum (possibly 0),
+     * signed toward the accumulated direction. Non-finite deltas AND deltas whose magnitude
+     * exceeds `Number.MAX_SAFE_INTEGER` emit 0 and leave the residue untouched — beyond 2^53
+     * the float product stops being an EXACT multiple of the quantum, which is precisely the
+     * property a grid-snapping consumer relies on.
+     * `delta` を蓄積し、放出量 (量子の倍数。0 のこともある) を蓄積方向の符号で返す。
+     * 非有限のデルタ、および絶対値が `Number.MAX_SAFE_INTEGER` を超えるデルタは 0 を返し
+     * 残差を汚さない — 2^53 超では浮動小数点積が量子の**正確な**倍数でなくなり、グリッド
+     * スナップ消費側が依拠する性質そのものが壊れるため。
+     *
+     * @param delta - Incoming delta (px) / 入力デルタ (px)
+     * @returns Emitted amount (multiple of the quantum) / 放出量 (量子の倍数)
+     */
+    push: (delta: number) => number
+    /**
+     * Returns the carried residue without mutating it (|residue| < quantum).
+     * 持ち越し中の残差を変更せずに返す (|残差| < 量子)。
+     *
+     * @returns Current residue (px) / 現在の残差 (px)
+     */
+    peekResidue: () => number
+    /**
+     * Clears the residue. Call from consumer-side idle timers, on pointer leave, or when the
+     * quantized target (row/column layout) changes under the accumulator.
+     * 残差を破棄する。消費側のアイドルタイマー・ポインタ離脱・量子化対象 (行/列レイアウト) の
+     * 変更時に呼ぶ。
+     */
+    reset: () => void
+}
+
+/**
+ * Creates a residual-carrying delta quantizer.
+ * 残差持ち越し型のデルタ量子化器を生成する処理。
+ *
+ * ```ts
+ * const quantizer = createResidualQuantizer({ quantum: rowHeight })
+ * const handleWheelVertical = (deltaY: number) => {
+ *     const emitted = quantizer.push(deltaY)
+ *     if (emitted !== 0) {
+ *         snapScrollBy(emitted) // 常に量子の倍数
+ *     }
+ * }
+ * ```
+ *
+ * @param options - Quantizer options / 量子化器のオプション
+ * @returns A new quantizer instance / 新しい量子化器インスタンス
+ * @throws {TypeError} When `quantum` is not a finite positive number / `quantum` が有限の正数でない場合
+ */
+export const createResidualQuantizer = (options: ResidualQuantizerOptions): ResidualQuantizer => {
+    const { quantum, resetOnDirectionChange = true } = options
+    // Fail Fast: 不正な量子は生成時に拒否する (押すたび NaN を配る量子化器を作らせない)
+    if (!(Number.isFinite(quantum) && quantum > 0)) {
+        throw new TypeError(`[createResidualQuantizer] quantum must be a finite positive number, received ${quantum}`)
+    }
+
+    let residue = 0
+
+    return {
+        push: (delta: number): number => {
+            // 非有限デルタは残差を汚さず 0 を返す (蓄積器に NaN が入ると以後全放出が死ぬ)。
+            // ❗ |delta| > Number.MAX_SAFE_INTEGER も同じ契約で見送る: 2^53 超では
+            // trunc(residue / quantum) * quantum が浮動小数点丸めで「量子の正確な倍数」で
+            // なくなり、グリッドスナップ消費側へ桁ずれした放出を渡してしまう (実測:
+            // quantum 3 に対し 1e17 % 3 === 1)。残差は常に |残差| < 量子で汚染されない
+            if (!Number.isFinite(delta) || Math.abs(delta) > Number.MAX_SAFE_INTEGER) {
+                return 0
+            }
+            // 方向反転で古い残差を捨てる (逆方向の動き出しを古い順方向残差に食わせない)
+            if (resetOnDirectionChange && residue !== 0 && delta !== 0 && Math.sign(delta) !== Math.sign(residue)) {
+                residue = 0
+            }
+            residue += delta
+            // trunc は 0 方向への切り捨てなので、正負どちらの蓄積でも「量子に満たない分」が残差に残る。
+            // ❗ 末尾の + 0 は -0 の正規化 (負方向の空放出は -0 になり、Object.is 比較や表示を汚す)
+            const emitted = Math.trunc(residue / quantum) * quantum + 0
+            residue -= emitted
+            return emitted
+        },
+        peekResidue: () => residue,
+        reset: () => {
+            residue = 0
+        },
+    }
+}

package/src/styles/virtualscroll.css

@@ -333,3 +333,18 @@
   position: absolute;
   width: 100%;
 }
+
+/* 支援技術専用ライブリージョン (liveRegion prop)。標準の visually-hidden パターン:
+   絶対配置 + 1px クリップで視覚とレイアウトから完全に消しつつ、AT からは読める。
+   display:none / visibility:hidden にすると aria-live ごと無効化されるため使えない */
+.aqvs-live-region {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  margin: -1px;
+  padding: 0;
+  border: 0;
+  overflow: hidden;
+  clip-path: inset(50%);
+  white-space: nowrap;
+}

package/src/utils.ts

@@ -14,3 +14,45 @@
 export const minmax = (value: number, min: number, max: number): number => {
     return Math.max(min, Math.min(max, value))
 }
+
+/**
+ * Computes an element's CSS transform scale along one axis (visual px / layout px).
+ *
+ * 要素の指定軸方向 CSS transform スケール (視覚px / レイアウトpx) を算出。
+ * 祖先に transform: scale(...) があると client 座標 (視覚px) がレイアウトpx とズレるため、
+ * その比率でドラッグ量・クリック座標を補正する。分母には整数丸めされる offsetWidth/offsetHeight
+ * ではなく、transform の影響を受けず小数精度を持つ getComputedStyle のレイアウト寸法
+ * (content + padding + border) を優先して使い、transform なしなら厳密に 1 を返す。
+ * 取得不能時 (jsdom 等) は offset 寸法へフォールバックし、それも 0 なら 1 を返す。
+ *
+ * @param element The element to measure. / 計測対象要素。
+ * @param axis The axis to measure along ("x" = width, "y" = height). / 計測軸。
+ * @returns The visual/layout scale ratio (1 when unmeasurable). / 視覚/レイアウト比 (計測不能時 1)。
+ */
+export const getAxisScale = (element: HTMLElement, axis: "x" | "y"): number => {
+    const isX = axis === "x"
+    const rect = element.getBoundingClientRect()
+    const visualSize = isX ? rect.width : rect.height
+    // computed style の値 (px 文字列) を数値化する。解釈不能なら 0 とみなす。
+    const parseSize = (value: string) => {
+        const parsed = Number.parseFloat(value)
+        return Number.isFinite(parsed) ? parsed : 0
+    }
+    const computed = window.getComputedStyle(element)
+    const contentSize = parseSize(isX ? computed.width : computed.height)
+    // rect (border-box) と同系になるよう content + padding + border を合成する。
+    const computedLayoutSize =
+        contentSize > 0
+            ? contentSize +
+              parseSize(isX ? computed.paddingLeft : computed.paddingTop) +
+              parseSize(isX ? computed.paddingRight : computed.paddingBottom) +
+              parseSize(isX ? computed.borderLeftWidth : computed.borderTopWidth) +
+              parseSize(isX ? computed.borderRightWidth : computed.borderBottomWidth)
+            : 0
+    // computed が取れない環境 (jsdom 等) では従来の offset 寸法へフォールバックする。
+    const layoutSize = computedLayoutSize > 0 ? computedLayoutSize : isX ? element.offsetWidth : element.offsetHeight
+    if (layoutSize <= 0 || visualSize <= 0) {
+        return 1
+    }
+    return visualSize / layoutSize
+}