@aiquants/virtualscroll 2.6.0 → 2.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiquants/virtualscroll",
-  "version": "2.6.0",
+  "version": "2.7.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
@@ -914,7 +919,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 / ドリフト補正) はこの解決済み値を使う。
@@ -2365,6 +2370,7 @@ const VirtualScrollInner = <T,>(
             background={background}
             tapScrollCircleOptions={tapScrollCircleOptions}
             inertiaOptions={inertiaOptions}
+            overscrollBehavior={overscrollBehavior}
             itemCount={itemCount}
             scrollBarWidth={scrollBarWidth}
             enableThumbDrag={enableThumbDrag}