@aiquants/virtualscroll 2.4.0 → 2.5.0

package/CHANGELOG.md

@@ -2,6 +2,124 @@
 
 All notable changes to `@aiquants/virtualscroll` are documented here.
 
+## 2.5.0 (2026-08-20)
+
+**ペイン外入力の橋渡し。** ホイールリスナーは `.aqvs-scroll-pane` にしか付かないため、消費側がペインの
+外に置いた要素 (列ヘッダー帯・固定フッター・横スクロールバー行など) はホイールの死角になっていました。
+明細表では列ヘッダーを仮想スクロールの外に固定するのが定石なので、この死角は必ず生じます。
+
+### Added
+
+- **`VirtualScrollHandle.scrollBy(delta)`** — ペイン自身のホイールと**同一の意味**でデルタ分スクロールする。
+  float のまま相対加算し、スクロールアンカーを張らない (手動スクロール扱いなので既存の保留アンカーは
+  むしろ解除される)。適用後の**論理**位置を返す。
+- **`VirtualScrollHandle.applyWheel(event)` / `ScrollPaneHandle.applyWheel(event)`** — ペイン自身の規則で
+  1 つのホイールを適用し、消費したかを返す。**ホイールの適用規則 (軸分解・ズーム素通し・横成分の委譲先・
+  スクロール可否・慣性停止・速度倍率) はこの 1 つの関数に閉じており**、ペイン根のリスナーもこれを通る。
+- **`useWheelBridge(target, options?)` / `WheelBridgeTarget`** — ペイン外の要素へペインと同じホイール
+  意味論を与える公開フック。返す ref を対象要素へ渡すだけでよい。**ホイールの意味論に影響する設定は
+  受け取らない** (すべて `applyWheel` の向こう側にあるため、ペイン内と帯の上で挙動が食い違うことが
+  表現できない)。オプションは橋渡しの ON/OFF (`WheelBridgeOptions.enableBridge`、既定 `true`) のみ。引数は
+  `{ applyWheel }` を要求する構造的な型なので、`VirtualScroll` / `ScrollPane` のどちらのハンドルでも使える。
+  React 19 の `onWheel` は passive で `preventDefault()` が効かないため、フックが `{ passive: false }` で登録する。
+  自前 ref との合成に対して冪等 (**要素ごと**の台帳を持ち、既に張ってある要素へは張り直さない)。
+  台帳を単一スロットにすると、ある要素の ref が呼び直されただけで別の要素のリスナーが剥がれ、
+  ヘッダー帯とフッター帯で同じフックを使ったときに生きている帯が入れ替わる。
+- **`horizontalKeyInputs`** (`readonly ("arrow" | "shift-arrow")[]`、既定 `[]`) と **`horizontalKeyStep`**
+  (既定 40px) — 行にフォーカスがあるとき `←/→` や `Shift + ←/→` を `onWheelHorizontal` へ横スクロール量
+  として流す。段階的な文字列ではなく**種別の配列**なのは、「素の矢印だけ横スクロール、`Shift + ←/→` は
+  消費側の範囲選択に残す」という実在の要求が段階的な union では表現できないため (`behaviorOptions.pointerDragInputs`
+  と同じ作法)。既定が空なのは、行キーハンドラが capture フェーズに付くため、既定で `←/→` を消費すると
+  ツリーの展開/折りたたみ等を奪ってしまうから。消費するのは `preventDefault()` のみで
+  **伝播は止めない** (縦の矢印キーと同じ契約。`stopPropagation()` は `document` / `window` の bubble
+  リスナーごとイベントを消し、ホットキーライブラリ (`document.addEventListener("keydown", …)` 形式) や
+  キー入力のテレメトリ、消費側が一覧を囲む要素へ張った bubble ハンドラまで巻き添えにする)。
+  **行そのものにフォーカスがあるときだけ**働く (行の中の自作スライダー相当などから矢印を奪わない)。
+  テキスト選択中の `Shift + ←/→` は選択範囲の伸縮として消費側に残す (判定は `Range.intersectsNode` で
+  行い、`Ctrl+A` のような行を跨ぐ選択も検出する)。`enableKeyboardNavigation: false` との併用は
+  機能が丸ごと無効になるため `Logger.warn` で警告する。`horizontalKeyStep` は**有限かつ正**のみを受け付け、不正値は
+  `Logger.warn` のうえキーを消費しない (既定への暗黙の読み替えをしない)。
+- ❗ `onWheelHorizontal` は**キーボード由来の横量も**受け取るようになった。名前は 2.x で公開済みのため
+  据え置き、docstring と仕様書で意味を「横軸が N px 動いた」と明記した。
+
+### Fixed
+
+- **`scrollTo` で連続入力を橋渡しすると 2 つの非対称が出る問題を、専用 API の追加と文書化で解消** —
+  `scrollTo` は行解決のため絶対位置を `Math.floor` するので 1px 未満のデルタが毎回消え (精密トラックパッドで
+  一切動かない)、`scrollToIndex` 経由でアンカーを張るので以後のサイズ変化のたびに一覧が過去の位置へ
+  戻っていた。アンカーを張ること自体はジャンプ API として正しい仕様なので、`scrollTo` の挙動は変えず
+  デルタ用の `scrollBy` を追加し、docstring と仕様書に使い分けと `-1` 番兵の落とし穴を明記した。
+- **README の `tabIndex={-1}` の説明が誤っていた点を訂正** — `tabindex="-1"` はタブ順に**入れません**。
+  実際の問題は「フォーカス可能になり VirtualScroll が実 DOM フォーカスを行へ移すこと」です。
+
+### Changed
+
+- `ScrollPane` のホイール処理を `applyWheel` として切り出し、命令ハンドルへ公開した。挙動は 1 点だけ
+  意図的に変わる: 「縦成分が無い」の判定を生の `deltaY` ではなく **px 換算後**の値で行う。
+  `deltaMode: DOM_DELTA_PAGE` かつ帯が 0 のとき (自己計測の初回コミット等) 換算後は 0 になり、
+  従来は `preventDefault()` だけして 1px も動かず**祖先のスクロールも奪って**いた。適用できる量が
+  無いイベントは消費しない、に揃えた。それ以外は不変 (既存の wheel 系テスト全件で回帰なしを確認)。
+- 内部の軸分解 `resolveWheelAxes` は **ctrl 押下でもデルタを 0 に潰さなくなった** (事実だけを返す解決器へ)。
+  「ズームは横取りしない」という判断は適用側が持つ。従来は解決器が 0 を詰めていたため適用側の ctrl 判定が
+  到達不能な飾りになっており、「ctrl+shift+ホイールを横スクロールとして食う」退行を検出できなかった。
+- コールバック参照の同期を `useEffect` から `useLayoutEffect` へ変更 (差し替え直後の入力が 1 フレーム古い
+  コールバックを読む窓を閉じる)。
+
+- **`ScrollPane.applyWheel` は方針値を ref から読む** — lexical に閉じ込めると、消費側が保持したハンドルが
+  その時点の方針を凍結する (実測: 一覧が絞り込みでスクロール不能になった後も、保持済みハンドルは
+  `preventDefault` し続けてページのスクロールを殺す)。`VirtualScrollHandle.applyWheel` は毎回 ref を辿るため
+  元から凍結せず、両者の非対称を解消した。
+
+- **ペインの入れ子でホイールが 2 回適用される問題を修正** — 内側のペインが消費したホイールが
+  バブリングで外側のペインにも届き、1 ノッチで内外の一覧が両方動いていた (実測: どちらも 100px)。
+  `applyWheel` の内側に「**本パッケージが**消費した」印 (`WeakSet<WheelEvent>`) を持たせ、
+  呼び出し元がどれでも二重適用を弾くようにした。❗ `event.defaultPrevented` では代用できない
+  (「誰かが止めた」と区別が付かず、ページ全体のスクロールロック中に一覧がまったく
+  スクロールできなくなる)。
+- **行の中の要素にフォーカスがあるとき矢印キーを奪わないようにした** (縦横・PageUp/PageDown すべて)。
+  従来は `role` で実装したスライダー相当などが keydown を**どちらのフェーズでも受け取れず**、
+  さらに縦矢印ではフォーカスが隣の行へ飛んでいた。❗ **これは縦キー操作の挙動変更である。**
+  行の中の要素にフォーカスがある状態での `↑↓` / `PageUp` / `PageDown` は、行の走査ではなく
+  その要素へ届くようになった。
+- **`useWheelBridge` の対象を差し替えても古い一覧を掴み続けないようにした** — ref コールバックの
+  identity を固定し、対象ハンドルを ref 越しに読む。クリーンアップを捨てる合成 ref では台帳が
+  「既に張ってある」と判断して張り直さないため、差し替え後の一覧が永久に動かなかった。
+- **警告の網羅と抑制** — `horizontalKeyInputs` を指定しつつ `onWheelHorizontal` が無い組み合わせも
+  警告するようにした (`@aiquants/directory-tree` のように `onWheelHorizontal` を `Omit` で封じる
+  ラッパーで踏みやすい)。`horizontalKeyStep` の検証警告は keydown 毎ではなく prop 変化時に出す
+  (キーリピート中にコンソールが溢れるため)。
+
+### Notes
+
+- `resolveWheelAxes` / `ResolvedWheelAxes` は**公開していません** (内部実装)。公開すると `16px` 行高・
+  同値の扱い・4 フィールドの形が恒久的に凍結されます。消費側が必要とするのは「ペインと同じ意味論で
+  ホイールを流し込むこと」であり、それは `useWheelBridge` が満たします。
+- 行は依然としてタブ順に入りません (`tabIndex={-1}`)。キーボードのみで横スクロールへ到達させたい消費側は
+  `handle.focusItemAtIndex(0)` などでフォーカスの入口を用意してください (ロービングタブインデックスの
+  導入は全消費側のタブ順を変えるため見送り)。デモ (`/horizontal`) にその実演ボタンを追加しました。
+- 既知の限界 (いずれも仕様書 §11.4 に記載): 行内でドラッグ選択/ダブルクリックすると選択が残り、それを
+  畳むキーボード手段が無いため `Shift + ←/→` が効かないままになる / Shadow DOM 内の選択は検出できない /
+  横スクロールは支援技術へ何も伝わらない / 縦スクロールでフォーカス行が仮想化で消えるとフォーカスが
+  `<body>` へ落ちる / 位置を量子化する消費側では `horizontalKeyStep` が量子未満だと 1px も動かない /
+  連続スクロール速度は OS のキーリピート設定に依存する (環境で最大 2.8 倍程度の差)。
+- **橋渡しはペインの外の要素にだけ張ってください。** 内側の要素はペイン自身のリスナーが既に拾っています
+  (二重適用は消費印が弾きますが、意味のない登録です)。
+- **既知の限界 (未修正・既存)**: 中断されたトランジション。`sizeRef` / `wheelPolicyRef` は render 本体で
+  代入するため、`startTransition` 内の絞り込みが Suspense で中断されると**コミットされなかった**
+  `contentSize` が残り、保留中は「スクロール可能な一覧なのにホイールが効かない」状態になります。
+  両 ref を layout effect へ移すのが筋ですが、それだけではタップスクロールの走破が 1 コミット遅れて
+  短くなる退行が実機 E2E で出ることを確認したため、本リリースでは見送りました (恒久対応には
+  クランプ経路の見直しが必要)。❗ 2 つの ref は**必ず同じタイミングで代入すること** — 片方だけを
+  layout effect にすると「消費はするがクランプは古い寸法」で一覧が先頭へ飛びます。
+- **既知の限界 (未修正)**: ペインは端に達してもホイールを消費するため、ページへスクロールが連鎖しません
+  (いわゆるスクロールトラップ)。ネイティブのスクロール領域と異なる挙動で、修正には端判定の追加が必要です。
+  本リリースの範囲外としました。
+- 行の中の要素へフォーカスが入ると、キーボードだけで行へ戻る手段がありません (行はタブ順に入らないため)。
+  消費側で `Escape` などの復帰口を用意してください。
+- `Omit<VirtualScrollProps, "onWheelHorizontal">` で横軸を封じているラッパーは、`horizontalKeyInputs` と
+  `horizontalKeyStep` も同じ `Omit` に加えてください。この 2 つがトップレベルにあるのは、1 箇所の `Omit` で
+  横軸のシーム全体を封じられるようにするためです。
+
 ## 2.4.0 (2026-08-19)
 
 **帯の自己計測 (`viewportSize` の optional 化)。** 自分の高さを自分で測れるコンポーネントが消費側に

package/README.md

@@ -183,6 +183,123 @@ function Grid() {
 A runnable version lives in the demo at **`/horizontal`** (`pnpm demo:dev`), and
 [`@aiquants/directory-tree`](../directory-tree)'s TreeGrid mode uses this exact pattern in production.
 
+## Bridging input from outside the pane
+
+The wheel listener lives on `.aqvs-scroll-pane` only, so anything you render **outside** it — a frozen
+column header, a sticky footer, the horizontal scrollbar row, an empty-state panel — is a wheel dead
+zone. Data tables pin the header outside the virtual list by convention, so this gap is the norm, not
+an edge case.
+
+Use `useWheelBridge`: it gives that element the pane's own wheel semantics.
+
+```tsx
+import { useRef } from 'react'
+import { useWheelBridge, VirtualScroll, type VirtualScrollHandle } from '@aiquants/virtualscroll'
+
+const listRef = useRef<VirtualScrollHandle>(null)
+const headerRef = useWheelBridge(listRef)
+
+<div ref={headerRef}>frozen header — outside the pane</div>
+<VirtualScroll ref={listRef} onWheelHorizontal={setScrollX} ...>{renderRow}</VirtualScroll>
+```
+
+**The hook takes no configuration that affects wheel semantics, and that is the point.** Wheel speed, the horizontal sink, whether
+the list can scroll, inertia and axis resolution all live behind the handle, in one function
+(`applyWheel`) that the pane's own listener goes through too. Give the bridge its own settings and the
+same grid ends up scrolling at one speed over the rows and another over the header — we measured exactly that
+— 30px vs 10px for one wheel tick at `wheelSpeedMultiplier: 3` — in a work-in-progress build that did give
+the bridge its own settings. With a single home for the rules, that
+mismatch is not expressible. The hook's job is `{ passive: false }` registration, teardown, and the
+`enableBridge` on/off switch — nothing else. Deciding whether an event was already applied belongs to
+`applyWheel`, which tracks the events **this package** consumed (see below).
+
+Its one option is `enableBridge` (default `true`) — a plain on/off switch, not a semantic knob. Pass
+`{ enableBridge: false }` to stop bridging without unmounting the element:
+
+```tsx
+const headerRef = useWheelBridge(listRef, { enableBridge: !isEditing })
+```
+
+It works with `ScrollPane` directly too: the parameter is typed against `WheelBridgeTarget`
+(`{ applyWheel }`), which both `VirtualScrollHandle` and `ScrollPaneHandle` satisfy.
+
+Composing with your own ref is safe — the hook keeps a per-element ledger and skips re-attaching to an
+element it already holds, so the common inline merge cannot pile up listeners (without it, four
+re-renders leave five live wheel listeners on one element). Return the hook's value so React 19 can run
+its cleanup on unmount:
+
+```tsx
+<div ref={(node) => { myRef.current = node; return headerRef(node) }} />
+```
+
+Dropping that `return` still works — the ledger keeps it correct — but the listener then stays on the
+element until the element itself is garbage-collected.
+
+The ledger is keyed **per element**, so one hook can serve several bands (a header and a footer) without
+them fighting over a single slot.
+
+⚠️ **The pane does not chain scrolling to the page at its edges.** It consumes the wheel even when
+already at position 0 or at the maximum, so a user wheeling down a long page has to move the pointer off
+the list to continue. This differs from a native scroll container and is a known limitation.
+
+⚠️ **`onWheel` cannot do this.** React 19 registers `onWheel` as a passive listener, so `preventDefault()`
+is ignored and the page scrolls instead. The hook attaches a `{ passive: false }` listener itself.
+
+⚠️ **Only bridge elements OUTSIDE the pane.** Anything inside the pane is already covered by the pane's
+own listener, so bridging it is a redundant registration — the consumed-event mark keeps it from being
+applied twice, but the extra listener is pure overhead on the wheel hot path.
+
+⚠️ **Do not bridge with `scrollTo`.** It is a *jump* API: it floors the absolute position (sub-pixel
+trackpad deltas vanish entirely) and pins a scroll anchor (every later size change re-pins the list to
+that row, so filtering a list makes it jump back to where it used to be). `scrollBy` is the delta API and
+takes the pane's own path. Also never write `scrollTo(handle.getScrollPosition() + delta)` — the getter
+returns the `-1` sentinel while the pane is unconnected.
+
+### Horizontal scrolling from the keyboard
+
+With `onWheelHorizontal` wired **and `behaviorOptions.enableKeyboardNavigation` left on** (the default),
+`horizontalKeyInputs` lets a focused row emit horizontal deltas too:
+
+| Value | Keys | Use it when |
+| --- | --- | --- |
+| `[]` (default) | — | Never steal the row's own arrow handling |
+| `["shift-arrow"]` | `Shift + ←/→` | Safe alongside tree expand/collapse and grid cell navigation |
+| `["arrow"]` | `←/→` | Grids that bind `Shift + ←/→` to range selection |
+| `["arrow", "shift-arrow"]` | both | Rows that use no arrow keys at all |
+
+It is an array rather than a graduated string because `["arrow"]` — plain arrows scroll, `Shift + ←/→`
+stays with your range selection — is a real requirement that `"none" | "shift-arrows" | "arrows"`
+cannot express, since `"arrows"` subsumes `"shift-arrows"`. `behaviorOptions.pointerDragInputs` takes a
+type array for the same reason.
+
+The default is empty on purpose: the package's row key handler runs in the **capture** phase, ahead of
+your row's own handler. When it consumes a key it calls `preventDefault()` only and deliberately does
+**not** stop propagation — `stopPropagation()` would delete the event from `document` and `window`
+bubble listeners too, breaking global hotkey libraries and keydown telemetry. Check `defaultPrevented`
+in your own handler, exactly as you would for the vertical arrows.
+
+It also fires only when the row **itself** is the event target. Focus sitting on something inside the
+row — a `role="slider"` cell, a link, a nested `overflow-x:auto` region — is never hijacked, so you do
+not have to avoid `["arrow"]` just because your rows contain arrow-key widgets.
+
+`Shift + ←/→` is left alone while a non-collapsed text selection sits inside the row, so keyboard users
+can still extend a selection. `horizontalKeyStep` (default 40) must be finite and positive; anything
+else logs a warning and leaves the key untouched rather than silently substituting the default.
+
+⚠️ **This does nothing when `enableKeyboardNavigation` is `false`** — the row key handler is what reads
+these keys, and turning navigation off removes it. The package emits a `Logger.warn` when it sees that
+combination. Note the next section tells `listbox` / `tree` / `grid` authors to turn navigation off; if
+you follow both, your arrow keys are dead. Pick one.
+
+⚠️ **Rows are not in the page tab sequence** (`tabIndex={-1}`). This feature fires only while a row has
+focus, so if you want keyboard-only users to reach it, give them an entry point — for example call
+`handle.focusItemAtIndex(0)` when the list receives focus.
+
+⚠️ **Wrappers that own the horizontal axis should seal these too.** If you re-export VirtualScroll with
+`Omit<VirtualScrollProps, 'onWheelHorizontal'>`, add `horizontalKeyInputs` and `horizontalKeyStep` to
+that same `Omit`. They sit at the top level, next to `onWheelHorizontal`, precisely so one `Omit` closes
+the whole horizontal seam.
+
 ## Composite widget roles (listbox / tree / grid)
 
 Building a `listbox`, `tree` or `grid` on top of VirtualScroll? Put the role on **`contentProps`**,
@@ -195,8 +312,10 @@ not on a wrapper around `<VirtualScroll>`:
   getItemHeight={() => 36}
   viewportSize={300}
   contentProps={{ id: listboxId, role: "listbox", "aria-label": "Warehouses" }}
-  // Required: with keyboard navigation ON, every row wrapper gets tabIndex={-1}, which puts the
-  // popup in the page tab sequence AND makes the wrappers opaque to the owned-element relationship.
+  // Required: with keyboard navigation ON, every row wrapper gets tabIndex={-1}. That does not add a
+  // tab stop, but it makes the wrappers focusable — VirtualScroll then moves real DOM focus onto a row
+  // — and it makes them opaque to the owned-element relationship.
+  // ⚠️ This also disables `horizontalKeyInputs` — the row key handler goes away with it.
   behaviorOptions={{ enableKeyboardNavigation: false }}>
   {(option) => <div role="option" aria-selected={false}>{option.label}</div>}
 </VirtualScroll>
@@ -235,7 +354,9 @@ exists in the DOM.
 | `testId` | `string` | ❌ | Emitted as `data-testid` on the scroll root. DOM hooks should use `data-*`, never class selectors |
 | `onScroll` | `(position: number, totalHeight: number) => void` | ❌ | Scroll event handler |
 | `onRangeChange` | `(range: VirtualScrollRange) => void` | ❌ | Range change handler |
-| `onWheelHorizontal` | `(deltaX: number) => void` | ❌ | Opt-in horizontal wheel delegation. When set, horizontal-dominant wheel / trackpad gestures (and shift+wheel) are delegated to this handler so the parent can implement horizontal scrolling. When omitted, horizontal gestures and shift+wheel bypass vertical scrolling so parent native scrolling works. See [Horizontal Scrolling](#horizontal-scrolling). |
+| `onWheelHorizontal` | `(deltaX: number) => void` | ❌ | Opt-in horizontal delegation. Horizontal-dominant wheel / trackpad gestures (and shift+wheel) are delegated to this handler so the parent can implement horizontal scrolling. ⚠️ **Keyboard deltas arrive here too** when `horizontalKeyInputs` is set. When omitted, horizontal gestures bypass vertical scrolling so parent native scrolling works. See [Horizontal Scrolling](#horizontal-scrolling). |
+| `horizontalKeyInputs` | `readonly ("arrow" \| "shift-arrow")[]` | ❌ | Keyboard gestures that emit a horizontal delta through `onWheelHorizontal` (default: `[]`, so row-level arrow handling is never stolen). Fires only when the row itself is the event target. ⚠️ Requires `behaviorOptions.enableKeyboardNavigation` (default `true`) — with it off the rows have no key handler at all and this prop does nothing (the package warns) |
+| `horizontalKeyStep` | `number` | ❌ | Pixels per horizontal arrow press (default: 40). Must be finite and positive; anything else warns and leaves the key untouched |
 | `background` | `ReactNode` | ❌ | Background element |
 | `initialScrollIndex` | `number` | ❌ | Initial scroll index |
 | `initialScrollOffset` | `number` | ❌ | Initial scroll offset (**logical** px). Not suitable for restoring positions of variable-height lists across remounts — use `initialScrollAnchor` |
@@ -265,7 +386,7 @@ exists in the DOM.
 | --- | --- | --- |
 | `enablePointerDrag` | `boolean` | Enable dragging the content area to scroll (default: true). ⚠️ Setting this to `false` removes the only way to scroll on touch devices — the pane is transform-based and has no native scroller. Use `pointerDragInputs` to exclude a single pointer type instead. |
 | `pointerDragInputs` | `readonly ("mouse" \| "pen" \| "touch")[]` | Pointer types allowed to drag-scroll the content area (default: all three). `touch-action: none` is applied only when `"touch"` or `"pen"` is included. |
-| `enableKeyboardNavigation` | `boolean` | Enable keyboard navigation (default: true) |
+| `enableKeyboardNavigation` | `boolean` | Enable keyboard navigation (default: true). Arrow / Page keys move row focus. ⚠️ They fire **only when the row wrapper itself is the event target** — focus inside a row (a `role="slider"` cell, a link, a nested scroll region) keeps its own keys |
 | `wheelSpeedMultiplier` | `number` | Multiplier for mouse wheel scrolling speed (default: 1) |
 | `inertiaOptions` | `ScrollPaneInertiaOptions` | Physics tuning for drag inertia |
 | `clipItemHeight` | `boolean` | Whether to clip item height (default: false) |
@@ -275,11 +396,13 @@ exists in the DOM.
 
 | Method | Type | Description |
 | --- | --- | --- |
-| `scrollTo` | `(position: number \| ((prev: number) => number)) => number` | Scroll to a **logical** position (updater receives the current logical position). Returns the applied **logical** position (2.0.0) |
+| `scrollTo` | `(position: number \| ((prev: number) => number)) => number` | **Jump** to a **logical** position (updater receives the current logical position). Returns the applied **logical** position (2.0.0). ⚠️ Not for bridging continuous input — see [Bridging input from outside the pane](#bridging-input-from-outside-the-pane) |
+| `scrollBy` | `(delta: number) => number` | Scroll **by a delta** with the pane's own wheel semantics (float accumulation, no anchor). Use this — not `scrollTo` — to bridge continuous input from outside the pane. Returns the applied **logical** position |
+| `applyWheel` | `(event: WheelEvent) => boolean` | Apply one wheel event with the pane's own rules; returns whether it was consumed. The single entry point for wheel input originating outside the pane — normally reached through `useWheelBridge` |
 | `scrollToIndex` | `(index: number, options?: { align?: "top" \| "bottom" \| "center"; offset?: number }) => void` | Scroll to specific item index with optional alignment and offset |
 | `getScrollPosition` | `() => number` | Get current **logical** scroll position (2.0.0; `-1` when the pane is not connected) |
-| `getContentSize` | `() => number` | Get total content size (insets included) |
-| `getViewportSize` | `() => number` | Get viewport size |
+| `getContentSize` | `() => number` | Get total content size (insets included). Returns the `-1` sentinel while the pane is unconnected |
+| `getViewportSize` | `() => number` | Get viewport size. Returns the `-1` sentinel while the pane is unconnected |
 | `focusItemAtIndex` | `(index: number, options?: { ensureVisible?: boolean }) => void` | Focus item at specific index |
 | `getRange` | `() => VirtualScrollRange` | Get current range information (updated one render behind) |
 | `getScrollAnchor` | `() => { index: number; offsetPx: number } \| null` | Capture the current top visible row anchor for exact restore via `initialScrollAnchor` (`null` when `itemCount` is 0) |

package/dist/ScrollPane.d.cts

@@ -152,6 +152,16 @@ export type ScrollPaneHandle = {
     getScrollPosition: () => number;
     getContentSize: () => number;
     getViewportSize: () => 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;
 };
 /**
  * A component that provides a scrollable view with a custom scrollbar.

package/dist/ScrollPane.d.ts

@@ -152,6 +152,16 @@ export type ScrollPaneHandle = {
     getScrollPosition: () => number;
     getContentSize: () => number;
     getViewportSize: () => 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;
 };
 /**
  * A component that provides a scrollable view with a custom scrollbar.

package/dist/ScrollPane.d.ts.map

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

package/dist/VirtualScroll.d.cts

@@ -36,11 +36,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。
@@ -198,8 +241,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.

package/dist/VirtualScroll.d.ts

@@ -36,11 +36,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。
@@ -198,8 +241,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.