@aiquants/virtualscroll 2.5.0 → 2.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiquants/virtualscroll",
-  "version": "2.5.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
@@ -234,7 +249,16 @@ const toggleListeners = (target: HTMLElement | Window, entries: ListenerEntry[],
 }
 
 export type ScrollPaneHandle = {
-    scrollTo: (newPosition: number | ((prev: number) => number)) => number
+    /**
+     * Jumps to a position, clamped against the last-committed dims (or an explicit override).
+     * 位置へジャンプする。クランプは**最後に commit された寸法** (または明示指定) に対して行う。
+     *
+     * `dimsOverride` は「commit より新しい寸法を知っている呼び出し元」専用の口である
+     * (例: Fenwick 木を同期更新した直後のレイアウトシフト補正は、まだ commit されていない
+     * 木の合計高さでクランプしたい)。通常の呼び出しでは指定しないこと — 指定を誤ると
+     * 画面に出ていない寸法でクランプされ、A-1 の汚染を自分の手で再現することになる。
+     */
+    scrollTo: (newPosition: number | ((prev: number) => number), dimsOverride?: { contentSize: number; viewportSize: number }) => number
     getScrollPosition: () => number
     getContentSize: () => number
     getViewportSize: () => number
@@ -278,6 +302,7 @@ export const ScrollPane = forwardRef<ScrollPaneHandle, ScrollPaneProps>(
             itemCount,
             renderThumbOverlay,
             wheelSpeedMultiplier = 1,
+            overscrollBehavior = "auto",
             onWheelHorizontal,
             contentInsets,
             visibleStartIndex,
@@ -477,12 +502,20 @@ export const ScrollPane = forwardRef<ScrollPaneHandle, ScrollPaneProps>(
         // contentSize と viewportSize を ref として保持
         // const sizeRef = useRef({ contentSize, viewportSize })
 
-        // ❗ render 本体で代入する。layout effect へ移すと、サイズ変更と同じコミット内で走る
-        // 他の layout effect からの scrollTo が 1 コミット古い寸法でクランプされ、タップスクロールの
-        // 走破が短くなる (実機 E2E の等速性テストがサンプル数不足で落ちる形で退行が出る)。
-        // 既知の代償は下の wheelPolicyRef のコメントを参照。
+        // ❗ **render 本体では代入しない (layout effect のみ = 常に「最後に commit された寸法」)。**
+        // render 中に書くと、中断されたトランジションの**コミットされなかった寸法**が残り、
+        // 保留中のホイール/ジャンプが画面に出ていない寸法でクランプされる (実測: 保留中の縮小で
+        // 一覧が先頭へ飛ぶ / ホイールが死ぬ。transitionClamp.spec.tsx が固定)。
+        //
+        // かつて「layout effect 化はタップスクロール E2E を退行させる」と記録されていたが、
+        // 8 回 x 3 系列の A/B/A 対照実験で**反証済み** (失敗は書き込み位置と無関係の
+        // コールドスタート負荷フレークで、両変種とも 6-7/8 で同率に失敗した)。加えて全計 1,893 回の
+        // scrollTo クランプ監査で committed 値と render 新値の食い違いは 0 件 — 同 commit 内で
+        // 新値を要する呼び出し元は存在しない (子 effect は本 effect より先に走るが、その窓に
+        // scrollTo 呼び出し元は無いことを確認済み)。commit より新しい寸法が要る唯一の呼び出し元
+        // (レイアウトシフト補正) は「committed + 今適用した delta」を `dimsOverride` で明示的に
+        // 渡す (木合計は渡さない — 木は破棄された WIP render にも変異される共有物)。
         const sizeRef = useRef({ contentSize, viewportSize })
-        sizeRef.current = { contentSize, viewportSize }
 
         const isScrollable = useMemo(() => contentSize > viewportSize, [contentSize, viewportSize])
 
@@ -520,8 +553,18 @@ export const ScrollPane = forwardRef<ScrollPaneHandle, ScrollPaneProps>(
         // )
 
         const scrollTo = useCallback(
-            (newPosition: number | ((prev: number) => number)) => {
-                const { contentSize: currentContentSize, viewportSize: currentViewportSize } = sizeRef.current
+            (newPosition: number | ((prev: number) => number), dimsOverride?: { contentSize: number; viewportSize: number }) => {
+                // 既定は「最後に commit された寸法」。dimsOverride は commit より新しい寸法を
+                // 知っている呼び出し元 (レイアウトシフト補正) だけが渡す。
+                // ❗ 非有限の override は警告して無視する (position の NaN ガードと同じ姿勢)。
+                // NaN の contentSize は「スクロール不能」判定へ落ち、位置を 0 へ強制 +
+                // onScroll(0) まで発火してしまう
+                let effectiveDims = dimsOverride ?? sizeRef.current
+                if (dimsOverride && !(Number.isFinite(dimsOverride.contentSize) && Number.isFinite(dimsOverride.viewportSize))) {
+                    Logger.warn("[ScrollPane] scrollTo received non-finite dimsOverride; falling back to the committed dims", { dimsOverride })
+                    effectiveDims = sizeRef.current
+                }
+                const { contentSize: currentContentSize, viewportSize: currentViewportSize } = effectiveDims
                 const currentIsScrollable = currentContentSize > currentViewportSize
                 const prevPosition = scrollPositionRef.current
 
@@ -743,18 +786,14 @@ export const ScrollPane = forwardRef<ScrollPaneHandle, ScrollPaneProps>(
 
         // ホイール適用の方針値。保持されたハンドル越しの呼び出しでも凍結させないため ref で持つ。
         //
-        // ❗ **代入のタイミングは `sizeRef` と必ず揃える。** 片方だけを layout effect にすると、
-        // 中断されたトランジション中に `applyWheel` は「スクロール可能」と判断して消費する一方、
-        // `scrollTo` は 1 コミット古い寸法でクランプして 0 を返す、という最悪の組み合わせになる
-        // (実測: 5,000 行の一覧が 1 ノッチで先頭へ飛び、以後 0 に貼り付く)。
-        //
-        // ❗ **既知の限界 (未修正)**: render 本体での ref 書き込みは、中断されたトランジションで
-        // **コミットされなかった値**を残す。その間のホイールは画面に出ていない寸法で判断されるため、
-        // 「スクロール可能な一覧なのにホイールが効かない」状態が保留中だけ起きる。両 ref を
-        // layout effect へ移すのが筋だが、それだけではタップスクロールの走破が 1 コミット遅れて
-        // 短くなる退行が出る (実機 E2E で実証済み)。恒久対応にはクランプ経路の見直しが必要。
-        const wheelPolicyRef = useRef({ isScrollable, viewportSize, wheelSpeedMultiplier })
-        wheelPolicyRef.current = { isScrollable, viewportSize, wheelSpeedMultiplier }
+        // ❗ **代入のタイミングは `sizeRef` と必ず揃える (どちらも layout effect のみ)。**
+        // 片方だけ render 本体に残すと、中断されたトランジション中に `applyWheel` と `scrollTo` が
+        // 別々の世界の寸法で判断する最悪の組み合わせになる。
+        const wheelPolicyRef = useRef({ isScrollable, viewportSize, wheelSpeedMultiplier, overscrollBehavior })
+        useLayoutEffect(() => {
+            // sizeRef と同じ理由で「最後に commit された値」だけを保持する (A-1。sizeRef のコメント参照)
+            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.
@@ -774,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。
@@ -800,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+ホイール等) なので横取りせず常に素通しする。
@@ -838,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 }))
 
@@ -905,9 +963,9 @@ export const ScrollPane = forwardRef<ScrollPaneHandle, ScrollPaneProps>(
         useImperativeHandle(
             ref,
             () => ({
-                scrollTo: (pos) => {
+                scrollTo: (pos, dimsOverride) => {
                     stopInertia()
-                    return scrollTo(pos)
+                    return scrollTo(pos, dimsOverride)
                 },
                 getScrollPosition: () => scrollPositionRef.current,
                 getContentSize: () => contentSize,

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 / ドリフト補正) はこの解決済み値を使う。
@@ -1305,7 +1310,7 @@ const VirtualScrollInner = <T,>(
      * 乖離した場合 (同一同期バッチ内の旧 contentSize によるクランプ) は、新 contentSize
      * コミット後の補正再発行を予約。
      */
-    const issueCompensationScroll = useCallback((targetPosition: number): number => {
+    const issueCompensationScroll = useCallback((targetPosition: number, appliedDelta = 0): number => {
         const pane = scrollPaneRef.current
         if (!pane) {
             return targetPosition
@@ -1313,7 +1318,20 @@ const VirtualScrollInner = <T,>(
         // クランプで位置が変化しない場合 onScroll は発火しない。事前位置と比較して増分を戻すために保持する
         const beforePosition = pane.getScrollPosition()
         isCompensatingRef.current += 1
-        const appliedPosition = pane.scrollTo(targetPosition)
+        // ❗ クランプは **「committed 寸法 + 今適用した delta」**で行う (dimsOverride)。この補正は木を
+        // 同期更新した**直後・commit 前**に走るため、ペインの committed sizeRef は必ず 1 commit 古く、
+        // 既定のままだと旧最大値でクランプされ二段補正 (§8.6) の再発行に頼ることになる。
+        //
+        // ❗ `fenwickTree.getTotal()` ではなく committed + delta を使う。木は**破棄された WIP render
+        // にも変異される共有物** (保留トランジション中は未 commit の行数の合計を返すことを
+        // transitionClamp.spec.tsx の前提アサートで実証済み) であり、木合計でのクランプは
+        // fenwick の並行安全設計の内部タイミングに依存する。committed + delta は定義から
+        // 「この補正が保とうとしている committed 空間 + 今適用した変化」そのものであり、
+        // WIP 変異のタイミングと無関係に正しい (通常時は木合計と同値で、一段目がそのまま
+        // 目標へ届き、二段補正はバックストップとして休眠する)
+        const freshContentSize = pane.getContentSize() + appliedDelta
+        const freshViewportSize = pane.getViewportSize()
+        const appliedPosition = pane.scrollTo(targetPosition, { contentSize: freshContentSize, viewportSize: freshViewportSize })
         if (appliedPosition === beforePosition) {
             // onScroll 不発: 補正カウンタの増分を巻き戻し、次の手動スクロールが補正扱いされるのを防ぐ
             isCompensatingRef.current = Math.max(0, isCompensatingRef.current - 1)
@@ -1507,7 +1525,7 @@ const VirtualScrollInner = <T,>(
                 // 同一同期バッチ内では ScrollPane の sizeRef が旧 contentSize のままのため、scrollTo は
                 // 旧最大値でクランプされ得る。issueCompensationScroll がカウンタのリークを防ぎつつ乖離時の
                 // 再発行を予約し、論理位置 (latestScrollPositionRef) には補正目標を保持して二段目の収束先とする。
-                issueCompensationScroll(newPosition)
+                issueCompensationScroll(newPosition, delta)
                 updateScrollPositionImmediate(newPosition, { immediate: true })
                 Logger.debug("[VirtualScroll] Adjusted scroll for layout shift (manual update)", { from: currentPanePosition, to: newPosition, causedByIndex: safeIndex, delta, activeVisibleStartIndex })
             }
@@ -1746,7 +1764,18 @@ const VirtualScrollInner = <T,>(
 
             // If manual scroll (neither programmatic nor compensating), clear the pending anchor
             // This ensures that manual scrolling immediately detaches from any previous scroll target
-            if (!(isProgrammatic || isCompensating || isResizingRef.current)) {
+            // ❗ isResizingRef は render 本体で立つ (in-commit の §9 クランプ連鎖が読むため必須) が、
+            // 中断されたトランジションの render でも立ってしまい、commit が無いので降りない。
+            // このクロージャの itemCount は **commit を通ってしか届かない** (破棄 render のクロージャは
+            // committed ツリーに残らない) ため、ref と閉じ込め値の照合で「committed な resize か」を
+            // 判別できる。保留中 (ref=新 / クロージャ=旧) は不一致 → 手動スクロール扱いでアンカーが
+            // 正しく外れる。resize の commit 内連鎖 (ref=新 / クロージャ=新) は一致 → 従来どおり。
+            // ❗ 純粋な同数往復 (500→300 保留→500 bailout) は照合が正しく効く (bailout は ref の
+            // 再前進も防ぐため不一致になる)。残存する盲点は「戻りに別 state 変更が同伴して一覧が
+            // 再 render される」形のみ (ref が committed と同値へ前進し、同伴 commit ではリセット
+            // 経路が走らない)。仕様書 §8.4 の既知の盲点を参照
+            const isCommittedResize = isResizingRef.current && prevItemCountRef.current === itemCount
+            if (!(isProgrammatic || isCompensating || isCommittedResize)) {
                 pendingVisibleStartIndexRef.current = null
             }
 
@@ -1775,7 +1804,7 @@ const VirtualScrollInner = <T,>(
                 }
             }
         },
-        [updateScrollPositionImmediate, enableScrollToTopBottomButtons],
+        [updateScrollPositionImmediate, enableScrollToTopBottomButtons, itemCount],
     )
 
     // レンダリング範囲を計算
@@ -2189,7 +2218,7 @@ const VirtualScrollInner = <T,>(
                     const newPosition = panePosition + shiftAmount
                     // updateItemSize と同型: scrollTo は旧 contentSize でクランプされ得るため、
                     // issueCompensationScroll でリークを防ぎつつ、乖離時は contentSize 同期 effect で再発行する。
-                    issueCompensationScroll(newPosition)
+                    issueCompensationScroll(newPosition, shiftAmount)
                     updateScrollPositionImmediate(newPosition, { immediate: true })
                     Logger.debug("[VirtualScroll] Adjusted scroll for layout shift (auto update)", { from: panePosition, to: newPosition, shiftAmount })
                 } else if (panePosition !== latestScrollPositionRef.current) {
@@ -2341,6 +2370,7 @@ const VirtualScrollInner = <T,>(
             background={background}
             tapScrollCircleOptions={tapScrollCircleOptions}
             inertiaOptions={inertiaOptions}
+            overscrollBehavior={overscrollBehavior}
             itemCount={itemCount}
             scrollBarWidth={scrollBarWidth}
             enableThumbDrag={enableThumbDrag}