@aiquants/virtualscroll 2.4.0 → 2.5.0

package/src/VirtualScroll.tsx

@@ -1,4 +1,4 @@
-import React, { forwardRef, type ReactNode, useCallback, useEffect, useImperativeHandle, useMemo, useRef, useState } from "react"
+import React, { forwardRef, type ReactNode, useCallback, useEffect, useImperativeHandle, useLayoutEffect, useMemo, useRef, useState } from "react"
 import { Logger } from "./logger.ts"
 import { ScrollPane, type ScrollPaneContentInsets, type ScrollPaneHandle, type ScrollPaneProps } from "./ScrollPane.tsx"
 import { useFenwickMapTree } from "./useFenwickMapTree.ts"
@@ -40,11 +40,54 @@ export type VirtualScrollRange = {
  */
 export type VirtualScrollHandle = {
     /**
-     * Scrolls to a LOGICAL position (updater form receives the current logical position).
+     * Jumps to a LOGICAL position (updater form receives the current logical position).
      * Returns the applied (clamped) LOGICAL position.
-     * 論理位置へスクロール (updater は現在の論理位置を受け取る)。適用後 (クランプ後) の論理位置を返す。
+     * 論理位置へ**ジャンプ**する (updater は現在の論理位置を受け取る)。適用後 (クランプ後) の論理位置を返す。
+     *
+     * ❗ **連続的なスクロール入力 (ホイール等) の橋渡しには使わないこと。`scrollBy` を使う。**
+     * これは「行を狙って飛ぶ」ための API であり、ペイン自身のホイール処理とは意味が 2 点異なる:
+     *
+     * 1. **絶対位置を `Math.floor` する** (行解決のため)。デルタを足して渡すと 1px 未満の移動が
+     *    毎回消えるため、精密トラックパッドでは**一切動かない**。
+     * 2. **スクロールアンカーを張る** (`scrollToIndex` 経由)。狙った行に留まり続けるための仕様だが、
+     *    以後 `contentSize` / `itemCount` / `viewportSize` / インセットが変わるたびにドリフト補正が
+     *    その行へ**再ピン留め**するため、絞り込みなどで一覧が過去の位置へ戻って見える。
+     *
+     * ❗ `scrollTo(handle.getScrollPosition() + delta)` と書かないこと。ペイン未接続時の
+     * `getScrollPosition()` は番兵 `-1` を返すため `-1 + delta` が混入する。相対移動は `scrollBy`
+     * (推奨) か updater 形式 `scrollTo(prev => prev + delta)` を使う (updater の `prev` は内部の
+     * 最新位置から取るため番兵が混入しない)。
      */
     scrollTo: (position: number | ((prev: number) => number)) => number
+    /**
+     * Scrolls by a delta using the exact semantics of the pane's own wheel handling.
+     * ペイン自身のホイール処理と**同一の意味**でデルタ分スクロールする。
+     *
+     * ペインの外に置いた要素 (列ヘッダー帯・固定フッター・横スクロールバー行など) の上での
+     * ホイールを一覧へ橋渡しするための API。ホイールリスナーは `.aqvs-scroll-pane` にしか付かないため、
+     * ペイン外はホイールの死角になる。この口はその死角を埋める。
+     *
+     * `scrollTo` との違い (どちらもペイン自身のホイールと同じ扱いにするための選択):
+     *
+     * - **float のまま相対加算する** (丸めない)。1px 未満のデルタも積み上がって動く。
+     * - **アンカーを張らない**。手動スクロールとして扱われるため、保留アンカーはむしろ**解除される**
+     *   (ペイン上でホイールを回したときと同じ)。以後のサイズ変化で位置が巻き戻ることがない。
+     * - 慣性は停止する (ペイン上のホイールと同じ)。
+     *
+     * @param delta - Signed pixels to scroll (positive scrolls down) / 符号付きの移動量 (正で下方向)
+     * @returns The applied (clamped) LOGICAL position / 適用後 (クランプ後) の論理位置
+     */
+    scrollBy: (delta: number) => number
+    /**
+     * Applies one wheel event with the pane's own rules; returns whether it was consumed.
+     * ペイン自身の規則で 1 つのホイールイベントを適用し、消費したかどうかを返す。
+     *
+     * 一覧の**外**に置いた要素 (列ヘッダー帯・固定フッター・空表示など) のホイールを、ペイン内と
+     * 寸分違わぬ意味論で流し込むための唯一の口。軸分解・速度倍率・スクロール可否・横成分の委譲先・
+     * 慣性停止のすべてがペイン側の 1 箇所で決まるため、消費側が規則を書き直したり食い違わせたりできない。
+     * 直接呼ぶより `useWheelBridge` (passive:false 登録と後始末込み) を使うこと。
+     */
+    applyWheel: (event: WheelEvent) => boolean
     /**
      * Current LOGICAL scroll position. -1 when the pane is not connected.
      * 現在の論理スクロール位置。ペイン未接続時は -1。
@@ -194,8 +237,71 @@ export type VirtualScrollProps<T> = {
     onItemFocus?: (index: number) => void
     scrollBarOptions?: VirtualScrollScrollBarOptions
     behaviorOptions?: VirtualScrollBehaviorOptions
-    /** Delegates horizontal wheel/trackpad delta to an upstream owner (e.g. a frozen-column grid). / 横ホイール量を上流へ委譲する。 */
+    /** Delegates horizontal wheel/trackpad delta to an upstream owner (e.g. a frozen-column grid). / 横ホイール量を上流へ委譲する。
+     *
+     * ❗ **ホイール由来だけの口ではない。** `horizontalKeyInputs` を指定すると**キーボード由来の横量**も
+     * ここへ流れる。名前は 2.x で公開済みのため据え置くが、意味は「横軸が N px 動いた。横軸はあなたの所有物である」。
+     */
     onWheelHorizontal?: (deltaX: number) => void
+    /**
+     * Keyboard gestures that emit a horizontal scroll delta through `onWheelHorizontal` (default: none).
+     * `onWheelHorizontal` へ横スクロール量を流すキーボード操作の種別 (既定: 無効)。
+     *
+     * - `[]` / 未指定 (既定): 横キーボードスクロールを行わない。
+     * - `["shift-arrow"]`: `Shift + ←/→` のみ。木の展開/折りたたみ (`←/→`) やグリッドのセル移動と
+     *   衝突しないため、既存の行 UI を持つ消費側でも安全に有効化できる。
+     * - `["arrow"]`: 素の `←/→` のみ。`Shift + ←/→` を選択範囲の拡張に使うグリッド向け。
+     * - `["arrow", "shift-arrow"]`: 両方。
+     *
+     * ❗ **配列なのは 4 状態が独立に必要だからである。** `"none" | "shift-arrows" | "arrows"` のような
+     * 段階的な文字列にすると `"arrows"` が `"shift-arrows"` を含んでしまい、「素の矢印だけ横スクロール、
+     * `Shift + ←/→` は消費側の範囲選択に残す」(Excel / データグリッドの標準) が**表現できない**。
+     * 同じ理由で種別配列を採るのが `pointerDragInputs` であり、本パッケージの既存の作法に揃えてある。
+     *
+     * ❗ **既定が無効なのは、行ハンドラを奪わないためである。** 本パッケージの行キーハンドラは
+     * capture フェーズに付くため、消費側の行 (bubble) より先に走る。既定で `←/→` を消費すると
+     * ツリーの展開/折りたたみのような既存操作を奪ってしまう。消費するのは `preventDefault()` のみで
+     * **伝播は止めない** (縦の矢印キーと同じ契約)。`stopPropagation()` は行ハンドラだけでなく
+     * `document` / `window` の bubble リスナーごとイベントを消し、ホットキーライブラリや
+     * キー入力のテレメトリまで巻き添えにするため採らない。消費側が二重動作を避ける手段は
+     * `defaultPrevented` の確認である。
+     *
+     * 前提: 横軸を所有するのは消費側なので、`onWheelHorizontal` が未指定なら何も起きない
+     * (キーイベントも消費しない)。行にフォーカスがあるときだけ働くため
+     * `behaviorOptions.enableKeyboardNavigation` も必要。
+     *
+     * ❗ **符号は物理キー基準** (`→` が正、`←` が負) である。横軸の向きを知っているのは消費側だけなので、
+     * RTL (`direction: rtl`) の一覧では消費側が受け取った値を反転すること。パッケージ側で
+     * `direction` を推測すると、横スクロールの実体 (CSS 変数・`scrollLeft`・transform) がどの要素の
+     * どの座標系かを知らないまま符号を決めることになり、当たらない前提を増やすだけになる。
+     *
+     * ❗ **働くのは行そのものにフォーカスがあるときだけである** (`event.target === event.currentTarget`)。
+     * 行の**中**の要素 (自作のタブ・ラジオ相当・スライダー相当など `role` だけで矢印キー操作を実装した
+     * ウィジェット、リンク、ネイティブの横スクロール領域) にフォーカスがある間は奪わない。
+     * 入力要素の allowlist だけでは `role` 実装のウィジェットを守れないため、対象そのもので判定する。
+     *
+     * 長押しの連続スクロールは **OS のキーリピート**に委ねる (`keydown` が繰り返し届く)。スクロールバーの
+     * 矢印ボタンが明示的なリピートタイマーを持つ (`ARROW_HOLD_DELAY` / `ARROW_HOLD_INTERVAL`) のは
+     * ポインタ押下にリピートが存在しないためで、キーボードとの非対称は入力機構の差に由来する。
+     *
+     * ❗ **`onWheelHorizontal` と同じ「横軸のシーム」に属するため、意図的にトップレベルに置いてある。**
+     * `behaviorOptions` の中へ入れると、横軸を自前で所有するラッパー (例: `@aiquants/directory-tree` は
+     * `Omit<VirtualScrollProps, "onWheelHorizontal">` で横軸を封じている) が `behaviorOptions` を
+     * そのまま素通しするため、封じたはずのシームへ横から到達できてしまう。
+     */
+    horizontalKeyInputs?: readonly ("arrow" | "shift-arrow")[]
+    /**
+     * Pixels emitted per horizontal arrow key press (default: 40, matching browser arrow scrolling).
+     * 横矢印キー 1 回あたりの移動量 (px。既定 40 = ブラウザの矢印スクロール相当)。
+     *
+     * ❗ **有限かつ正の値のみを受け付ける。** `0` / 負値 / `NaN` / `Infinity` を渡すと
+     * **キーを消費しない** (既定値へ黙って読み替えることはしない)。0 を既定へ差し替えると
+     * 呼び出し側の明示的な指定を握り潰し、0 のまま通すと「キーを食うのに 1px も動かない」
+     * 死んだ操作になる。
+     * 警告は `keydown` ではなく **prop の変化時に 1 回だけ**出す (キーリピート中に
+     * コンソールが溢れるため)。
+     */
+    horizontalKeyStep?: number
     /**
      * ARIA / identity attributes applied to the scrollable CONTENT element — the element that
      * directly owns the rendered rows and excludes the scrollbar and overlay chrome.
@@ -272,6 +378,39 @@ const MAX_RENDERED_ITEMS = 2000
  */
 const ANCHOR_REBASE_DISTANCE = 1_048_576 // 2^20 px
 
+/**
+ * Pixels emitted per horizontal arrow key press. Matches the ~40px browsers scroll for an arrow key.
+ *
+ * 横矢印キー 1 回あたりの移動量。ブラウザが矢印キーでスクロールする約 40px に合わせた既定値。
+ */
+const DEFAULT_HORIZONTAL_KEY_STEP = 40
+
+/**
+ * Reports whether a non-collapsed text selection currently sits inside the given element.
+ * 指定要素の中に折り畳まれていないテキスト選択が存在するかを返す処理。
+ *
+ * `Shift + ←/→` はブラウザ標準では選択範囲の伸縮である。行の中でテキストを選んでいる最中に
+ * 横スクロールへ横取りすると、**選び直す手段がキーボードから消える**。選択が空 (キャレットだけ) の
+ * ときは伸縮の起点が無いため横取りしてよい。
+ *
+ * @param element - Element to test the selection against / 選択範囲の所在を調べる要素
+ * @returns True when a non-collapsed selection is inside the element / 折り畳まれていない選択が内側にある場合に true
+ */
+const hasTextSelectionWithin = (element: HTMLElement): boolean => {
+    const selection = element.ownerDocument.defaultView?.getSelection()
+    if (!selection || selection.isCollapsed || selection.rangeCount === 0) {
+        return false
+    }
+    // ❗ 起点 (anchorNode) の包含では不十分。`Ctrl+A` のようにページ全体を選ぶと起点は行の外に落ち、
+    // 「行の上に見えている選択」を取りこぼす (実ブラウザで実測)。範囲が行と**交差**するかで判定する。
+    for (let index = 0; index < selection.rangeCount; index += 1) {
+        if (selection.getRangeAt(index).intersectsNode(element)) {
+            return true
+        }
+    }
+    return false
+}
+
 /**
  * Converts a numeric size into a non-negative bigint for large collection handling.
  *
@@ -767,6 +906,8 @@ const VirtualScrollInner = <T,>(
         scrollBarOptions,
         behaviorOptions,
         onWheelHorizontal,
+        horizontalKeyInputs,
+        horizontalKeyStep = DEFAULT_HORIZONTAL_KEY_STEP,
         contentProps,
     }: VirtualScrollProps<T>,
     ref: React.Ref<VirtualScrollHandle>,
@@ -901,6 +1042,32 @@ const VirtualScrollInner = <T,>(
     const previousTopInsetRef = useRef(resolvedInsets.top)
     const onScrollRef = useRef<OnScrollCallback | undefined>(onScroll ?? undefined)
     const onRangeChangeRef = useRef<OnRangeChangeCallback | undefined>(onRangeChange ?? undefined)
+    // 横委譲コールバックを ref 経由で読む。行キーハンドラ (handleItemKeyDown) は全行の React.memo が
+    // 依存する安定参照でなければならず、コールバックの差し替えで identity を変えられないため。
+    const onWheelHorizontalRef = useRef<((deltaX: number) => void) | undefined>(onWheelHorizontal)
+
+    // ❗ 恒久的に機能しない組み合わせは黙って無視しない。1 回の無効なキーが警告を出すのに
+    // 「機能まるごと死んでいる」が無言なのは筋が通らない (README のリストボックス指南は
+    // enableKeyboardNavigation: false を勧めるため、実際に踏まれる)
+    const hasHorizontalKeyInputs = (horizontalKeyInputs?.length ?? 0) > 0
+    const hasOnWheelHorizontal = Boolean(onWheelHorizontal)
+    useEffect(() => {
+        if (!hasHorizontalKeyInputs) {
+            return
+        }
+        if (!enableKeyboardNavigation) {
+            Logger.warn("[VirtualScroll] horizontalKeyInputs is set but behaviorOptions.enableKeyboardNavigation is false; horizontal keyboard scrolling is disabled because the row key handler is not mounted.")
+        }
+        if (!hasOnWheelHorizontal) {
+            Logger.warn("[VirtualScroll] horizontalKeyInputs is set but onWheelHorizontal is missing; horizontal keyboard scrolling is disabled because the package does not own the horizontal axis.")
+        }
+        // ❗ 移動量の検証もここで行う。keydown 側で警告するとキーリピート中に毎フレーム出力される
+        // (Logger の既定水準は WARN なので本番でも出る)
+        if (!(Number.isFinite(horizontalKeyStep) && horizontalKeyStep > 0)) {
+            Logger.warn(`[VirtualScroll] horizontalKeyStep must be a finite positive number, received ${horizontalKeyStep}. Horizontal arrow keys are left untouched.`)
+        }
+    }, [hasHorizontalKeyInputs, hasOnWheelHorizontal, enableKeyboardNavigation, horizontalKeyStep])
+
     const itemRefs = useRef<Map<number, HTMLDivElement>>(new Map())
     const pendingFocusIndexRef = useRef<number | null>(null)
     const lastFocusedIndexRef = useRef<number | null>(null)
@@ -921,12 +1088,15 @@ const VirtualScrollInner = <T,>(
         isResizingRef.current = true
     }
 
-    useEffect(() => {
+    // ❗ useEffect ではなく useLayoutEffect である。差し替え直後の keydown / wheel が
+    // **1 フレーム古いコールバック**を読む窓を消すため (通常の effect はペイントを跨いで遅延しうる)
+    useLayoutEffect(() => {
         // 目的: 外部から渡されたコールバックの参照を最新状態に保つ。
-        // 依存関係: onRangeChange, onScroll
+        // 依存関係: onRangeChange, onScroll, onWheelHorizontal
         onScrollRef.current = onScroll ?? undefined
         onRangeChangeRef.current = onRangeChange ?? undefined
-    }, [onRangeChange, onScroll])
+        onWheelHorizontalRef.current = onWheelHorizontal
+    }, [onRangeChange, onScroll, onWheelHorizontal])
 
     const tryFocusElement = useCallback(
         (element: HTMLElement | null) => {
@@ -1518,6 +1688,43 @@ const VirtualScrollInner = <T,>(
         [resolvedInsets.top, scrollTo, updateScrollPositionImmediate],
     )
 
+    /**
+     * Applies a delta through the pane's own wheel seam (float accumulation, no anchor).
+     *
+     * ペイン自身のホイールと同じ口 (float 相対加算・アンカー不変) でデルタを適用する処理。
+     *
+     * ❗ **`scrollTo` を経由してはならない。** あちらは行解決のため絶対位置を `Math.floor` し、
+     * `scrollToIndex` 経由で保留アンカーを張る。デルタの橋渡しに使うと (1) 1px 未満の移動が毎回
+     * 消えて精密トラックパッドで動かず、(2) 以後のサイズ変化のたびにドリフト補正が過去の行へ
+     * 再ピン留めして一覧が勝手に戻る。ここでは `ScrollPaneHandle.scrollTo` の updater 形式へ
+     * そのまま流し、ペイン内のホイール (`scrollTo(prev => prev + deltaY)`) と**同一の経路**を通す。
+     *
+     * 位置の反映は `onScroll` → `handleScroll` が行う (ペイン上のホイールと完全に同じ)。ここで
+     * 追加の `updateScrollPositionImmediate` を呼ばないのは、経路を 1 本に保つためである。
+     * 非有限デルタのガードとクランプは `ScrollPane.scrollTo` が単一の防波堤として担う。
+     */
+    const scrollBy = useCallback((delta: number): number => {
+        const pane = scrollPaneRef.current
+        if (!pane) {
+            // ペイン未接続時は動かしようがない。番兵 (-1) は返さず現在の論理位置をそのまま返す
+            return toLogicalPositionWithInset(latestScrollPositionRef.current, resolvedInsetsTopRef.current)
+        }
+        const appliedPanePosition = pane.scrollTo((previous) => previous + delta)
+        return toLogicalPositionWithInset(appliedPanePosition, resolvedInsetsTopRef.current)
+    }, [])
+
+    /**
+     * Applies one wheel event with the pane's own rules; returns whether it was consumed.
+     * ペイン自身の規則で 1 つのホイールイベントを適用し、消費したかどうかを返す処理。
+     *
+     * ペイン (`ScrollPane`) が持つ 1 つの適用関数へそのまま委譲する。ここで規則を書き直さないことが
+     * 「ペイン内と帯の上で挙動が食い違わない」ことの根拠である。
+     *
+     * @param event - The wheel event to apply / 適用するホイールイベント
+     * @returns True when the event was consumed / 消費した場合に true
+     */
+    const applyWheel = useCallback((event: WheelEvent): boolean => scrollPaneRef.current?.applyWheel(event) ?? false, [])
+
     /**
      * Handles scroll events from the pane.
      *
@@ -1653,15 +1860,50 @@ const VirtualScrollInner = <T,>(
             if (event.altKey || event.metaKey || event.ctrlKey) {
                 return
             }
-            const target = event.target as HTMLElement | null
-            if (target) {
-                const tagName = target.tagName
-                if (tagName === "INPUT" || tagName === "TEXTAREA" || tagName === "SELECT") {
+            // ❗ **行そのものにフォーカスがあるときだけ働く。** ハンドラは capture フェーズに付くため、
+            // 行の中の要素にフォーカスがある状態で消費すると、その要素へ keydown が
+            // **どちらのフェーズでも一切届かなくなる** (実ブラウザで実測)。入力要素の allowlist だけでは
+            // `role` で実装したスライダー相当・タブ相当や、ネイティブの縦横スクロール領域を守れない。
+            //
+            // ❗ 縦横の**両方**に適用する。横だけに掛けると、同じウィジェットが `←→` は受け取れるのに
+            // `↑↓` は奪われたうえフォーカスまで隣の行へ飛ばされる、という一貫性の無い状態になる。
+            if (event.target !== event.currentTarget) {
+                return
+            }
+            // ❗ 行ラッパー自身が編集可能な文脈にある場合はキーを奪わない。上の判定で
+            // `target === currentTarget` (常に本パッケージの `div`) が確定しているため、
+            // `INPUT` / `TEXTAREA` / `SELECT` のタグ判定はここでは**到達不能**であり撤去した
+            // (それらは行の中の要素であり、上の判定で既に見送られる)。
+            // 一方 `isContentEditable` は**祖先からの継承**で true になりうるため残す
+            // (消費側が一覧を編集可能な領域で囲むケース)。
+            if (event.currentTarget.isContentEditable) {
+                return
+            }
+            if (event.key === "ArrowLeft" || event.key === "ArrowRight") {
+                // 横軸を所有するのは消費側なので、委譲先が無ければキーイベントを消費しない
+                // (ツリーの展開/折りたたみなど行側の操作をそのまま通す)。
+                const emitHorizontal = onWheelHorizontalRef.current
+                if (!emitHorizontal) {
                     return
                 }
-                if (target.isContentEditable) {
+                // 押されたジェスチャが許可種別に含まれるかを確認する
+                const gesture = event.shiftKey ? "shift-arrow" : "arrow"
+                if (!horizontalKeyInputs?.includes(gesture)) {
                     return
                 }
+                // ❗ テキスト選択中の Shift+←/→ は選択範囲の伸縮であり、横スクロールで奪ってはならない
+                // (実ブラウザで実測: 奪うと行内のテキストを選び直せなくなる)
+                if (event.shiftKey && hasTextSelectionWithin(event.currentTarget)) {
+                    return
+                }
+                // ❗ 不正な移動量は既定へ黙って読み替えず、消費もしない (Strict No-Fallback)。
+                // 警告は上の effect が prop 変化のたびに 1 回だけ出す (キーリピートで溢れさせない)
+                if (!(Number.isFinite(horizontalKeyStep) && horizontalKeyStep > 0)) {
+                    return
+                }
+                event.preventDefault()
+                emitHorizontal(event.key === "ArrowLeft" ? -horizontalKeyStep : horizontalKeyStep)
+                return
             }
             if (event.key === "ArrowDown") {
                 if (index < itemCount - 1) {
@@ -1702,7 +1944,7 @@ const VirtualScrollInner = <T,>(
                 }
             }
         },
-        [enableKeyboardNavigation, itemCount, focusItemAtIndex],
+        [enableKeyboardNavigation, itemCount, focusItemAtIndex, horizontalKeyInputs, horizontalKeyStep],
     )
 
     const handleItemFocus = useCallback(
@@ -2072,6 +2314,8 @@ const VirtualScrollInner = <T,>(
             getContentSize: () => scrollPaneRef.current?.getContentSize() ?? -1,
             getViewportSize: () => scrollPaneRef.current?.getViewportSize() ?? -1,
             scrollTo: scrollToHandle,
+            scrollBy,
+            applyWheel,
             scrollToIndex,
             getFenwickTreeTotalHeight: () => fenwickTree.getTotal(),
             getFenwickSize: () => fenwickTree.getSize(),
@@ -2080,7 +2324,7 @@ const VirtualScrollInner = <T,>(
             getScrollAnchor,
             updateItemSize,
         }),
-        [scrollToHandle, scrollToIndex, fenwickTree, focusItemAtIndex, getScrollAnchor, updateItemSize],
+        [scrollToHandle, scrollBy, applyWheel, scrollToIndex, fenwickTree, focusItemAtIndex, getScrollAnchor, updateItemSize],
     )
 
     const totalContentHeight = fenwickTree.getTotal() + resolvedInsets.top + resolvedInsets.bottom

package/src/index.ts

@@ -12,6 +12,7 @@ export { tapScrollCircleSampleVisual } from "./tapScrollCircleSampleVisual.tsx"
 export { FenwickMapTree, useFenwickMapTree } from "./useFenwickMapTree.ts"
 export { useHeightCache } from "./useHeightCache.ts"
 export { useLruCache } from "./useLruCache.ts"
+export { useWheelBridge, type WheelBridgeOptions, type WheelBridgeTarget } from "./useWheelBridge.ts"
 export { minmax } from "./utils.ts"
 export {
     VirtualScroll,

package/src/useWheelBridge.ts

@@ -0,0 +1,141 @@
+/**
+ * @module useWheelBridge
+ * @description Gives elements placed OUTSIDE the scroll pane the pane's own wheel semantics.
+ *
+ * @description スクロールペインの**外**に置いた要素へ、ペイン自身のホイール意味論を与えるフック。
+ *
+ * ペインのホイールリスナーは `.aqvs-scroll-pane` にしか付かないため、その外に置いた要素
+ * (列ヘッダー帯・固定フッター・横スクロールバー行・空表示など) はホイールの死角になる。明細表では
+ * 列ヘッダーを仮想スクロールの外に固定するのが定石なので、この死角は必ず生じる。
+ */
+
+import { type RefCallback, type RefObject, useCallback, useLayoutEffect, useRef } from "react"
+
+/**
+ * Anything that can apply a wheel event with the pane's own rules.
+ * ペイン自身の規則でホイールイベントを適用できるもの。
+ *
+ * `VirtualScrollHandle` と `ScrollPaneHandle` の両方が構造的にこれを満たすため、どちらのハンドルでも
+ * 同じフックが使える (`ScrollPane` を直接使う消費側が橋渡しを自作せずに済む)。
+ */
+export type WheelBridgeTarget = {
+    applyWheel: (event: WheelEvent) => boolean
+}
+
+/**
+ * Options for {@link useWheelBridge}.
+ * {@link useWheelBridge} のオプション。
+ */
+export type WheelBridgeOptions = {
+    /**
+     * Set to `false` to detach the bridge without unmounting the element.
+     * 要素をアンマウントせずに橋渡しを止めたいとき `false` にする。既定 `true`。
+     */
+    enableBridge?: boolean
+}
+
+/**
+ * Bridges wheel events from an element outside the pane into the list, with the pane's own semantics.
+ * ペイン外の要素のホイールを、ペイン自身と同じ意味論で一覧へ橋渡しするフック。
+ *
+ * 返り値を対象要素の `ref` に渡すだけでよい。
+ *
+ * ```tsx
+ * const listRef = useRef<VirtualScrollHandle>(null)
+ * const headerRef = useWheelBridge(listRef)
+ *
+ * <div ref={headerRef}>列ヘッダー (ペインの外)</div>
+ * <VirtualScroll ref={listRef} onWheelHorizontal={setScrollX} ... />
+ * ```
+ *
+ * ❗ **ホイールの意味論に影響する設定は一切受け取らないのが意図的な設計である。** 速度倍率・
+ * 横成分の委譲先・スクロール可否・慣性停止・軸分解のすべては、ハンドルの向こう側 (`applyWheel`) が
+ * 持つ。橋渡し側にも同じ設定口を用意すると同じグリッドなのに「ヘッダー帯の上だけスクロールが遅い」
+ * 「帯の上でだけ横に動かない」といった食い違いが静かに生まれる (橋渡し側にも設定口を置いた
+ * 実装途中の版で実測: `wheelSpeedMultiplier: 3` のとき同じ 1 ノッチがペイン上 30px / 帯の上 10px)。
+ * 唯一のオプション {@link WheelBridgeOptions.enableBridge} は意味論ではなく**橋渡し自体の ON/OFF** である。
+ * このフックの責務は **`{ passive: false }` での登録・後始末・その ON/OFF だけ**である。
+ *
+ * ❗ **`onWheel` プロップでは代用できない。** React 19 は `onWheel` を passive リスナーとして登録するため
+ * `preventDefault()` が効かず、ページ全体がスクロールしてしまう。
+ *
+ * ❗ **`handle.scrollTo` で自前に橋渡ししてはならない。** あれはジャンプ用 API で、絶対位置を丸めるため
+ * 1px 未満のデルタが消え、さらにスクロールアンカーを張るためサイズ変化のたびに一覧が過去の位置へ戻る。
+ *
+ * 自前の ref も必要なら合成してよい (多重登録に対して安全に作ってある)。
+ * ❗ **戻り値をそのまま `return` すること。** React 19 はこれをクリーンアップとして実行する。
+ * 返さない場合も動作は正しいままだが、`null` 呼び出しでは何も外さない設計のため、リスナーは
+ * 要素ごと GC されるまで残る。
+ *
+ * ```tsx
+ * <div ref={(node) => { myRef.current = node; return headerRef(node) }} />
+ * ```
+ *
+ * @param target - Ref to the list's imperative handle (`VirtualScrollHandle` / `ScrollPaneHandle`) / 一覧の命令ハンドルへの ref
+ * @param options - Bridge options / 橋渡しのオプション
+ * @returns A ref callback to attach to the source element / 発生元の要素へ渡す ref コールバック
+ */
+export const useWheelBridge = (target: RefObject<WheelBridgeTarget | null>, options?: WheelBridgeOptions): RefCallback<HTMLElement> => {
+    // オプションは ref 経由で読む。ref コールバックの identity を安定させ、
+    // 設定の差し替えのたびにリスナーを張り直さないため。
+    const optionsRef = useRef(options)
+    // ❗ 対象ハンドルも ref 越しに読む。`target` を依存に置くと、消費側が別の一覧へ差し替えたときに
+    // ref コールバックの identity が変わり、React が `null` → `node` と呼び直す。台帳は要素単位で
+    // 「既に張ってある」と判断して**張り直さない**ため、古い listener が古い一覧を掴んだままになる
+    // (実測: 差し替え後の一覧が一切動かない)。identity を固定すれば張り直し自体が不要になる。
+    const targetRef = useRef(target)
+    useLayoutEffect(() => {
+        optionsRef.current = options
+        targetRef.current = target
+    }, [options, target])
+
+    // リスナーを張った要素の台帳。**要素ごと**に持つ。単一スロットにすると、ある要素の
+    // ref が呼び直されただけで**別の要素**のリスナーを剥がしてしまう (実測: ヘッダー帯と
+    // フッター帯で同じフックを使い回すと、最初の再レンダーで生きている帯が入れ替わる)。
+    // WeakMap なので、外し損ねた要素があっても要素ごと GC される。
+    const attachedRef = useRef<WeakMap<HTMLElement, (event: WheelEvent) => void>>(new WeakMap())
+
+    return useCallback((node: HTMLElement | null) => {
+        // ❗ null 呼び出しでは何も外さない。どの要素の話か分からないため、ここで外すと
+        // 無関係の要素を巻き添えにする。解除は下のクリーンアップ (要素を知っている) が行う。
+        if (!node) {
+            return
+        }
+        // ❗ 既に張ってあれば何もしない。React 19 のクリーンアップを**受け取らない**合成 ref
+        // (`ref={(n) => { myRef.current = n; headerRef(n) }}`) では React は毎レンダーで
+        // null → node と呼び直すため、冪等でないとリスナーが積み上がる (再レンダー 4 回で 5 本)。
+        // ❗ 直ちに N 倍スクロールするわけではない (`applyWheel` 内の「消費済み印」が 2 本目以降を
+        // 弾く)。実害はリスナーの増殖そのもの ＝ ホイールのたびに N 個のハンドラが起動する
+        // ホットパスの劣化であり、位置の比較では検出できない。だから本数で固定してある。
+        if (attachedRef.current.has(node)) {
+            return
+        }
+
+        const listener = (event: WheelEvent) => {
+            if (optionsRef.current?.enableBridge === false) {
+                return
+            }
+            // ❗ 二重適用の防止は `applyWheel` の内側が持つ (「自分が消費した印」を見る)。
+            // ここで `defaultPrevented` を見てはならない。ペイン本体はそれを見ないため、
+            // ページ全体のスクロールロック中に「ペインは動くのに帯の上だけ死ぬ」という
+            // 食い違いが生まれる (実測)。
+            targetRef.current.current?.applyWheel(event)
+        }
+
+        // ❗ passive: false でなければ preventDefault が効かない (React の onWheel は passive)
+        node.addEventListener("wheel", listener, { passive: false })
+        attachedRef.current.set(node, listener)
+
+        // React 19 はこのクリーンアップを受け取ると `null` 呼び出しの代わりに実行する。
+        // ❗ listener の一致判定は**意図的な防御**である。ref コールバックの identity は固定
+        // (依存配列が空) なので、要素がマウントされている限り React は張り直さず、現状この分岐が
+        // 偽になる経路は無い。依存配列を増やした瞬間に「古いクリーンアップが新しい登録を消す」
+        // 事故が起きるため、ブラックボックステストで踏めなくても残す。
+        return () => {
+            if (attachedRef.current.get(node) === listener) {
+                node.removeEventListener("wheel", listener)
+                attachedRef.current.delete(node)
+            }
+        }
+    }, [])
+}

package/src/wheelAxes.ts

@@ -0,0 +1,90 @@
+/**
+ * @module wheelAxes
+ * @description Single source of truth for how a wheel event is split into scroll axes.
+ * Used only by `ScrollPane.applyWheel`, which is itself the single seam every wheel caller goes
+ * through, so the rules cannot drift between the pane and elements outside it.
+ *
+ * @description ホイールイベントをスクロール軸へ分解する規則の単一の真実。呼び出し元は
+ * `ScrollPane.applyWheel` **だけ**であり、その `applyWheel` がすべてのホイール呼び出し元
+ * (ペイン根のリスナー / `useWheelBridge` / 消費側の直接呼び出し) の唯一のシームなので、
+ * ペイン内外で規則が食い違わない。
+ *
+ * ❗ **公開 API ではない** (`index.ts` から export しない)。公開すると `LINE_HEIGHT_PX = 16`・
+ * 同値時の横倒し・4 フィールドの形が恒久的に凍結される。
+ */
+
+/** Line height (px) assumed for `DOM_DELTA_LINE`. / `DOM_DELTA_LINE` で仮定する 1 行の高さ (px)。 */
+const LINE_HEIGHT_PX = 16
+
+/**
+ * Wheel axes resolved from a raw wheel event.
+ * 生のホイールイベントから解決した軸情報。
+ */
+export type ResolvedWheelAxes = {
+    /** True when ctrl is held, i.e. the browser treats it as zoom. Deltas are still reported as-is. / ctrl 押下 (ブラウザがズームとして扱う) の場合に true。デルタはそのまま報告する。 */
+    isZoomGesture: boolean
+    /** True when the horizontal component dominates (includes shift+wheel). / 横成分が優勢な場合に true (shift+ホイールを含む)。 */
+    isHorizontalDominant: boolean
+    /** Horizontal delta in px (deltaMode already converted). / px 単位の横方向デルタ (deltaMode 変換済み)。 */
+    horizontalDelta: number
+    /** Vertical delta in px (deltaMode already converted). / px 単位の縦方向デルタ (deltaMode 変換済み)。 */
+    verticalDelta: number
+}
+
+/**
+ * Converts a raw delta to pixels according to the event's `deltaMode`.
+ * イベントの `deltaMode` に従って生のデルタを px へ変換する処理。
+ *
+ * @param delta - Raw delta from the event / イベントの生デルタ
+ * @param deltaMode - `WheelEvent.deltaMode` / `WheelEvent.deltaMode`
+ * @param viewportSize - Viewport length used for `DOM_DELTA_PAGE` / `DOM_DELTA_PAGE` で使うビューポート長
+ * @returns The delta in pixels / px 単位のデルタ
+ */
+const toPixelDelta = (delta: number, deltaMode: number, viewportSize: number): number => {
+    if (deltaMode === 1) {
+        // DOM_DELTA_LINE: 行単位
+        return delta * LINE_HEIGHT_PX
+    }
+    if (deltaMode === 2) {
+        // DOM_DELTA_PAGE: ページ単位
+        return delta * viewportSize
+    }
+    return delta
+}
+
+/**
+ * Splits a wheel event into scroll axes, in pixels, applying the package's gesture rules.
+ * ホイールイベントを px 単位の軸へ分解し、本パッケージのジェスチャ規則を適用する処理。
+ *
+ * 規則 (判定順序そのものが仕様):
+ *
+ * 1. **shift+ホイール**は `deltaX === 0` のとき縦量を横として読む (Windows 系の慣習)。ブラウザが既に
+ *    `deltaX` へマップ済みなら通常の軸のまま扱う。
+ * 2. **横優勢判定**は横成分と縦成分の絶対値比較。等しい場合 (`|h| === |v|`) は横に倒す。ただし
+ *    **両軸とも 0 のときは横優勢としない** — 慣性の惰性通知で毎 tick 送られる 0/0 を横として
+ *    消費すると、ページ側のスクロールを無言で飲み込む。
+ *
+ * ❗ **これは解決器であって方針ではない。** `isZoomGesture` (ctrl 押下) が true でもデルタは
+ * そのまま返す。「ズームは横取りしない」という**方針**は適用側 (`ScrollPane.applyWheel`) が持つ。
+ *
+ * @param event - The wheel event / ホイールイベント
+ * @param viewportSize - Viewport length for `DOM_DELTA_PAGE` conversion / `DOM_DELTA_PAGE` 変換に使うビューポート長
+ * @returns The resolved axes / 解決した軸情報
+ */
+export const resolveWheelAxes = (event: WheelEvent, viewportSize: number): ResolvedWheelAxes => {
+    const usesShiftAxis = event.shiftKey && event.deltaX === 0
+    const rawHorizontal = usesShiftAxis ? event.deltaY : event.deltaX
+    const rawVertical = usesShiftAxis ? 0 : event.deltaY
+    const isHorizontalDominant = rawHorizontal !== 0 && Math.abs(rawHorizontal) >= Math.abs(rawVertical)
+
+    return {
+        // ❗ ズームでもデルタは潰さない。ここは**事実だけ**を報告し、「横取りしない」という
+        // 判断は適用側 (applyWheel) が下す。ここで 0 を詰めると適用側の ctrl 判定が
+        // 到達不能な飾りになり、`ctrl+shift+ホイール` を横スクロールとして食う退行を
+        // どのテストも検出できなくなる (変異解析で実証済み)。
+        isZoomGesture: event.ctrlKey,
+        isHorizontalDominant,
+        horizontalDelta: toPixelDelta(rawHorizontal, event.deltaMode, viewportSize),
+        verticalDelta: toPixelDelta(rawVertical, event.deltaMode, viewportSize),
+    }
+}

package/src/wheelConsumption.ts

@@ -0,0 +1,36 @@
+/**
+ * @module wheelConsumption
+ * @description Tracks which wheel events this package has already applied.
+ *
+ * @description 本パッケージが既に適用したホイールイベントを記録するモジュール。
+ *
+ * ❗ **`event.defaultPrevented` では代用できない。** あれは「誰かがこのイベントを止めた」であって
+ * 「**我々が**消費した」ではない。両者を混同すると、ページ全体のスクロールロック
+ * (`document` に capture + `preventDefault` を張る定番の実装) を掛けただけで一覧が
+ * まったくスクロールできなくなる。逆に印が無いと、ペインの入れ子や祖先に張った `useWheelBridge` で
+ * **同じデルタが 2 回適用**される (実測: 内側と外側の一覧が 1 ノッチで両方 100px 動く)。
+ *
+ * `WeakSet` なのでイベントオブジェクトの寿命を延ばさない。
+ */
+
+/** Wheel events already applied by a pane in this page. / このページのペインが適用済みのホイールイベント。 */
+const consumedWheelEvents = new WeakSet<WheelEvent>()
+
+/**
+ * Marks a wheel event as applied by this package.
+ * ホイールイベントを「本パッケージが適用済み」として記録する処理。
+ *
+ * @param event - The wheel event that was applied / 適用したホイールイベント
+ */
+export const markWheelConsumed = (event: WheelEvent): void => {
+    consumedWheelEvents.add(event)
+}
+
+/**
+ * Reports whether this package already applied the given wheel event.
+ * 指定のホイールイベントを本パッケージが既に適用済みかどうかを返す処理。
+ *
+ * @param event - The wheel event to test / 判定するホイールイベント
+ * @returns True when it was already applied / 既に適用済みの場合に true
+ */
+export const wasWheelConsumed = (event: WheelEvent): boolean => consumedWheelEvents.has(event)