@aiquants/virtualscroll 2.6.0 → 3.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiquants/virtualscroll",
-  "version": "2.6.0",
+  "version": "3.0.0",
   "description": "High-performance virtual scrolling component for React with variable item heights",
   "sideEffects": [
     "**/*.css"

package/src/ScrollPane.tsx

@@ -99,6 +99,21 @@ export type ScrollPaneProps = {
     renderThumbOverlay?: (props: ScrollBarThumbOverlayRenderProps) => React.ReactNode
     /** Multiplier applied to wheel delta for faster or slower scrolling. / スクロール速度を調整するためのホイールデルタの倍率。 */
     wheelSpeedMultiplier?: number
+    /**
+     * How wheel input behaves at the pane's edges (default: "auto").
+     * ペインの端でホイールがどう振る舞うか (既定: "auto")。
+     *
+     * - `"auto"` (既定): その向きへ**もう動けない**縦ホイールは消費せず、祖先 (ページ) の
+     *   スクロールへ連鎖させる。ネイティブのスクロール領域と同じ挙動
+     *   (CSS `overscroll-behavior: auto` 相当)。端に**達する**ノッチは部分消費して端で止まり、
+     *   **次の**ノッチから連鎖する (ネイティブと同じ段付き)。
+     * - `"contain"`: 端でも消費し続け、ページへ連鎖させない (2.6.0 以前の挙動)。
+     *   モーダル内の一覧など「背後を絶対に動かしたくない」消費側向け。
+     *
+     * ❗ 対象は**縦ホイールのみ**。横成分は `onWheelHorizontal` の所有者 (消費側) の責務であり、
+     * ポインタドラッグ / タッチの連鎖はネイティブ相当の慣性譲渡が別問題のため対象外。
+     */
+    overscrollBehavior?: "auto" | "contain"
     /**
      * Callback delegating horizontal wheel/trackpad delta to an upstream owner.
      * When provided, horizontal-dominant (or shift+wheel) gestures are consumed here
@@ -287,6 +302,7 @@ export const ScrollPane = forwardRef<ScrollPaneHandle, ScrollPaneProps>(
             itemCount,
             renderThumbOverlay,
             wheelSpeedMultiplier = 1,
+            overscrollBehavior = "auto",
             onWheelHorizontal,
             contentInsets,
             visibleStartIndex,
@@ -773,11 +789,11 @@ export const ScrollPane = forwardRef<ScrollPaneHandle, ScrollPaneProps>(
         // ❗ **代入のタイミングは `sizeRef` と必ず揃える (どちらも layout effect のみ)。**
         // 片方だけ render 本体に残すと、中断されたトランジション中に `applyWheel` と `scrollTo` が
         // 別々の世界の寸法で判断する最悪の組み合わせになる。
-        const wheelPolicyRef = useRef({ isScrollable, viewportSize, wheelSpeedMultiplier })
+        const wheelPolicyRef = useRef({ isScrollable, viewportSize, wheelSpeedMultiplier, overscrollBehavior })
         useLayoutEffect(() => {
             // sizeRef と同じ理由で「最後に commit された値」だけを保持する (A-1。sizeRef のコメント参照)
-            wheelPolicyRef.current = { isScrollable, viewportSize, wheelSpeedMultiplier }
-        }, [isScrollable, viewportSize, wheelSpeedMultiplier])
+            wheelPolicyRef.current = { isScrollable, viewportSize, wheelSpeedMultiplier, overscrollBehavior }
+        }, [isScrollable, viewportSize, wheelSpeedMultiplier, overscrollBehavior])
 
         /**
          * Applies one wheel event with the pane's own rules and reports whether it was consumed.
@@ -797,7 +813,11 @@ export const ScrollPane = forwardRef<ScrollPaneHandle, ScrollPaneProps>(
          * 2. 横優勢 (shift+ホイールを含む) は `onWheelHorizontal` へ委譲。未指定なら消費せず祖先へ委ねる
          * 3. スクロール不能なら消費しない
          * 4. px 換算後の縦成分が 0 なら消費しない (適用できる量が無いのに祖先のスクロールを奪わない)
-         * 5. 消費済みの印 + `preventDefault()` + 慣性停止 + 速度倍率を掛けて相対スクロール
+         * 5. 実効 delta の確定 (速度倍率を先に適用)
+         * 6. `overscrollBehavior` が "contain" でなければ端判定: その向きへもう動けなければ
+         *    消費せず祖先へ連鎖 (2.7.0)
+         * 7. 消費済みの印 + `preventDefault()` + 慣性停止
+         * 8. 相対スクロール
          *
          * @param event - The wheel event to apply / 適用するホイールイベント
          * @returns True when this pane applied the event / このペインが適用した場合に true。
@@ -823,7 +843,7 @@ export const ScrollPane = forwardRef<ScrollPaneHandle, ScrollPaneProps>(
                 // 保持済みハンドルは preventDefault し続け、ページのスクロールを殺す)。
                 // `VirtualScrollHandle.applyWheel` は毎回 ref を辿るため凍結しない。両者の
                 // 非対称は `WheelBridgeTarget` が両方を等価に扱う設計と噛み合わない。
-                const { isScrollable: currentIsScrollable, viewportSize: currentViewportSize, wheelSpeedMultiplier: currentWheelSpeedMultiplier } = wheelPolicyRef.current
+                const { isScrollable: currentIsScrollable, viewportSize: currentViewportSize, wheelSpeedMultiplier: currentWheelSpeedMultiplier, overscrollBehavior: currentOverscrollBehavior } = wheelPolicyRef.current
                 const axes = resolveWheelAxes(event, currentViewportSize)
 
                 // ❗ ctrl+wheel はブラウザのズーム (ピンチズーム/ctrl+shift+ホイール等) なので横取りせず常に素通しする。
@@ -861,15 +881,30 @@ export const ScrollPane = forwardRef<ScrollPaneHandle, ScrollPaneProps>(
                     return false
                 }
 
-                markWheelConsumed(event)
-                event.preventDefault()
-                stopInertia()
-
                 let deltaY = axes.verticalDelta
                 if (currentWheelSpeedMultiplier !== 1) {
                     deltaY *= currentWheelSpeedMultiplier
                 }
 
+                // ❗ 端の連鎖 (A-2): その向きへ**もう動けない**ホイールは消費せず祖先へ委ねる
+                // (ネイティブの `overscroll-behavior: auto` 相当)。判定は倍率適用後の実効 delta の
+                // 向き × committed 位置で行う。端に**達する**ノッチはここを素通りして部分消費され
+                // (クランプが端で止める)、次のノッチからこの分岐で連鎖する — ネイティブと同じ段付き。
+                // `"contain"` は 2.6.0 以前のトラップ挙動 (モーダル内の一覧など背後を動かしたくない
+                // 消費側向け) を明示的に維持する。
+                if (currentOverscrollBehavior !== "contain") {
+                    const currentPosition = scrollPositionRef.current
+                    // contentSize は sizeRef (committed。wheelPolicyRef と同じ layout effect 同期) から読む
+                    const maxScrollPosition = Math.max(sizeRef.current.contentSize - currentViewportSize, 0)
+                    if ((deltaY > 0 && currentPosition >= maxScrollPosition) || (deltaY < 0 && currentPosition <= 0)) {
+                        return false
+                    }
+                }
+
+                markWheelConsumed(event)
+                event.preventDefault()
+                stopInertia()
+
                 // ホットパスのためログ引数はサンクで遅延評価し、抑制時は DOM 読み取り (scrollTop) も発生させない
                 Logger.debug("[ScrollPane] wheel event", () => ({ deltaY, scrollPosition: scrollPositionRef.current, wheelSpeedMultiplier: currentWheelSpeedMultiplier, deltaMode: event.deltaMode, scrollTop: contentAreaRef.current?.scrollTop }))
 

package/src/VirtualScroll.tsx

@@ -150,6 +150,11 @@ export type VirtualScrollBehaviorOptions = {
     enableKeyboardNavigation?: boolean
     wheelSpeedMultiplier?: number
     inertiaOptions?: ScrollPaneProps["inertiaOptions"]
+    /**
+     * How wheel input behaves at the list's edges (default: "auto" = chain to ancestors).
+     * 一覧の端でホイールがどう振る舞うか (既定: "auto" = 祖先へ連鎖)。`ScrollPaneProps["overscrollBehavior"]` 参照。
+     */
+    overscrollBehavior?: ScrollPaneProps["overscrollBehavior"]
     clipItemHeight?: boolean
     /**
      * When `true`, the underlying Fenwick tree fully re-samples on every `getItemHeight` change
@@ -248,15 +253,21 @@ export type VirtualScrollProps<T> = {
      * `onWheelHorizontal` へ横スクロール量を流すキーボード操作の種別 (既定: 無効)。
      *
      * - `[]` / 未指定 (既定): 横キーボードスクロールを行わない。
-     * - `["shift-arrow"]`: `Shift + ←/→` のみ。木の展開/折りたたみ (`←/→`) やグリッドのセル移動と
-     *   衝突しないため、既存の行 UI を持つ消費側でも安全に有効化できる。
-     * - `["arrow"]`: 素の `←/→` のみ。`Shift + ←/→` を選択範囲の拡張に使うグリッド向け。
-     * - `["arrow", "shift-arrow"]`: 両方。
+     * - `["arrow"]`: 素の `←/→` のみ。
      *
-     * ❗ **配列なのは 4 状態が独立に必要だからである。** `"none" | "shift-arrows" | "arrows"` のような
-     * 段階的な文字列にすると `"arrows"` が `"shift-arrows"` を含んでしまい、「素の矢印だけ横スクロール、
-     * `Shift + ←/→` は消費側の範囲選択に残す」(Excel / データグリッドの標準) が**表現できない**。
-     * 同じ理由で種別配列を採るのが `pointerDragInputs` であり、本パッケージの既存の作法に揃えてある。
+     * ❗ **`Shift + ←/→` は常に消費しない (3.0.0 で `"shift-arrow"` 入力を撤去)。** ブラウザ標準では
+     * Shift+矢印は選択範囲の伸縮であり、横取りすると行内テキストを選び直す手段がキーボードから消える。
+     * 2.x では「選択があるときだけ譲る」検出 (`getSelection` の交差判定) で共存させていたが、
+     * (a) Shadow DOM 内では選択が可搬に検出できない (Chromium の `window.getSelection()` は shadow root
+     * 内部を見せず、内部選択は非標準 API でしか取れない)、(b) `Ctrl+A` の全選択では全行が選択と交差して
+     * 横キーボードスクロールが選択解除まで全面ロックアウトする、という構造的欠陥が残った。検出の
+     * 精度を上げる案はどれも別の正しいユーザー意図を誤判定するため、機能ごと撤去して Shift 側を
+     * 無条件でブラウザへ返す。横スクロールの Shift 系入力が必要なら `shift+ホイール` が引き続き使える
+     * (`resolveWheelAxes` の軸規則。こちらは選択と衝突しない)。
+     *
+     * ❗ **語彙が 1 つでも配列なのは意図的である。** 種別配列は `pointerDragInputs` と同じ本パッケージの
+     * 作法であり、将来の入力種別追加が型の破壊なしにできる。boolean へ畳むと prop 名が変わり、横軸を
+     * `Omit<>` で封じているラッパー (例: `@aiquants/directory-tree`) の封印リストまで連鎖破壊する。
      *
      * ❗ **既定が無効なのは、行ハンドラを奪わないためである。** 本パッケージの行キーハンドラは
      * capture フェーズに付くため、消費側の行 (bubble) より先に走る。既定で `←/→` を消費すると
@@ -289,7 +300,7 @@ export type VirtualScrollProps<T> = {
      * `Omit<VirtualScrollProps, "onWheelHorizontal">` で横軸を封じている) が `behaviorOptions` を
      * そのまま素通しするため、封じたはずのシームへ横から到達できてしまう。
      */
-    horizontalKeyInputs?: readonly ("arrow" | "shift-arrow")[]
+    horizontalKeyInputs?: readonly "arrow"[]
     /**
      * Pixels emitted per horizontal arrow key press (default: 40, matching browser arrow scrolling).
      * 横矢印キー 1 回あたりの移動量 (px。既定 40 = ブラウザの矢印スクロール相当)。
@@ -385,32 +396,6 @@ const ANCHOR_REBASE_DISTANCE = 1_048_576 // 2^20 px
  */
 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.
  *
@@ -914,7 +899,7 @@ const VirtualScrollInner = <T,>(
 ) => {
     const { width: scrollBarWidth, enableThumbDrag, enableTrackClick, enableArrowButtons, enableScrollToTopBottomButtons, renderThumbOverlay, tapScrollCircleOptions } = scrollBarOptions ?? {}
 
-    const { enablePointerDrag, pointerDragInputs, enableKeyboardNavigation = true, wheelSpeedMultiplier, inertiaOptions, clipItemHeight = false, resetOnGetItemHeightChange = false } = behaviorOptions ?? {}
+    const { enablePointerDrag, pointerDragInputs, enableKeyboardNavigation = true, wheelSpeedMultiplier, inertiaOptions, overscrollBehavior, clipItemHeight = false, resetOnGetItemHeightChange = false } = behaviorOptions ?? {}
 
     // viewportSize 未指定のときは ScrollPane が自分の帯を計測し、その値をこのコールバックで通知する。
     // 描画枚数 (computeRenderingRanges) とアライン計算 (scrollToIndex / ドリフト補正) はこの解決済み値を使う。
@@ -1910,14 +1895,14 @@ const VirtualScrollInner = <T,>(
                 if (!emitHorizontal) {
                     return
                 }
-                // 押されたジェスチャが許可種別に含まれるかを確認する
-                const gesture = event.shiftKey ? "shift-arrow" : "arrow"
-                if (!horizontalKeyInputs?.includes(gesture)) {
+                // ❗ Shift 併用は無条件で消費しない (3.0.0 で "shift-arrow" 入力を撤去)。ブラウザ標準では
+                // 選択範囲の伸縮であり、選択の有無での条件分岐はしない — 選択検出は Shadow DOM で
+                // 可搬に成立せず、Ctrl+A 全選択では全行が交差して解除まで全面ロックアウトするため
+                if (event.shiftKey) {
                     return
                 }
-                // ❗ テキスト選択中の Shift+←/→ は選択範囲の伸縮であり、横スクロールで奪ってはならない
-                // (実ブラウザで実測: 奪うと行内のテキストを選び直せなくなる)
-                if (event.shiftKey && hasTextSelectionWithin(event.currentTarget)) {
+                // 押されたジェスチャが許可種別に含まれるかを確認する
+                if (!horizontalKeyInputs?.includes("arrow")) {
                     return
                 }
                 // ❗ 不正な移動量は既定へ黙って読み替えず、消費もしない (Strict No-Fallback)。
@@ -2365,6 +2350,7 @@ const VirtualScrollInner = <T,>(
             background={background}
             tapScrollCircleOptions={tapScrollCircleOptions}
             inertiaOptions={inertiaOptions}
+            overscrollBehavior={overscrollBehavior}
             itemCount={itemCount}
             scrollBarWidth={scrollBarWidth}
             enableThumbDrag={enableThumbDrag}