@aiquants/virtualscroll 1.18.3 → 1.19.0

package/src/ScrollPane.tsx

@@ -0,0 +1,913 @@
+import { forwardRef, useCallback, useEffect, useId, useImperativeHandle, useLayoutEffect, useMemo, useRef } from "react"
+import { twMerge } from "tailwind-merge"
+import { Logger } from "./logger.ts"
+import { ScrollBar, type ScrollBarTapCircleOptions, type ScrollBarThumbOverlayRenderProps, TAP_SCROLL_CANCEL_EVENT } from "./ScrollBar.tsx"
+import { minmax } from "./utils.ts"
+
+/**
+ * Props for the ScrollPane component.
+ *
+ * ScrollPane コンポーネントの Props。
+ */
+export type ScrollPaneContentInsets = {
+    top?: number
+    bottom?: number
+}
+
+export type ScrollPaneProps = {
+    /**
+     * A function that renders the content of the scroll pane.
+     * It receives the current scroll position as an argument.
+     *
+     * スクロールペインのコンテンツをレンダリングする関数です。
+     * 現在のスクロール位置を引数として受け取ります。
+     */
+    children: (scrollPosition: number) => React.ReactNode
+    /** The total size of the content. / コンテンツの総サイズ。 */
+    contentSize: number
+    /** The size of the visible area. / 表示領域のサイズ。 */
+    viewportSize: number
+    /** The width of the scrollbar. / スクロールバーの幅。 */
+    scrollBarWidth?: number
+    /** Whether grabbing the scrollbar thumb is allowed. / スクロールバーのつまみ操作を許可するかどうか。 */
+    enableThumbDrag?: boolean
+    /** A callback function that is called when the scroll position changes. / スクロール位置が変更されたときに呼び出されるコールバック関数。 */
+    onScroll?: (scrollPosition: number, prevPosition: number) => void
+    /** Additional class names for the component. / コンポーネントの追加のクラス名。 */
+    className?: string
+    /** Test id emitted as data-testid on the root element (DOM hooks must use data-* attributes, never class selectors). / ルート要素に data-testid として出力されるテスト ID (DOM フックはクラスセレクタでなく data-* 属性を使う)。 */
+    testId?: string
+    /** Custom styles for the component. / コンポーネントのカスタムスタイル。 */
+    style?: React.CSSProperties
+    /** A background element to be rendered behind the content. / コンテンツの背後にレンダリングされる背景要素。 */
+    background?: React.ReactNode
+    /** Configuration for the tap scroll circle. / タップサークルの設定。 */
+    tapScrollCircleOptions?: ScrollBarTapCircleOptions
+    /** Configuration for inertia scroll behavior. / 慣性スクロールの設定。 */
+    inertiaOptions?: ScrollPaneInertiaOptions
+    /** Total number of scrollable items (optional). / スクロール対象アイテムの総数（任意）。 */
+    itemCount?: number
+    /** Whether clicking the scrollbar track moves the thumb. / スクロールバートラックのクリック操作を許可するかどうか。 */
+    enableTrackClick?: boolean
+    /** Whether arrow buttons control the scroll position. / 矢印ボタンのスクロール操作を許可するかどうか。 */
+    enableArrowButtons?: boolean
+    /** Whether dragging the content area scrolls the pane. / コンテンツ領域のドラッグでスクロールさせるかどうか。 */
+    enablePointerDrag?: boolean
+    /** Optional renderer for thumb overlays. / サム付近に表示するオーバーレイのレンダラー。 */
+    renderThumbOverlay?: (props: ScrollBarThumbOverlayRenderProps) => React.ReactNode
+    /** Multiplier applied to wheel delta for faster or slower scrolling. / スクロール速度を調整するためのホイールデルタの倍率。 */
+    wheelSpeedMultiplier?: number
+    /**
+     * Callback delegating horizontal wheel/trackpad delta to an upstream owner.
+     * When provided, horizontal-dominant (or shift+wheel) gestures are consumed here
+     * (preventDefault + delegate) instead of being ignored; vertical behavior is unchanged.
+     * 横方向ホイール/トラックパッド量を上流へ委譲するコールバック。指定時のみ横成分を処理する。
+     */
+    onWheelHorizontal?: (deltaX: number) => void
+    /** Insets applied to the scrollable content area. / スクロール可能領域に適用するインセット。 */
+    contentInsets?: ScrollPaneContentInsets
+    /** The index of the first visible item. / 最初の可視アイテムのインデックス。 */
+    visibleStartIndex?: number
+    /** The index of the last visible item. / 最後の可視アイテムのインデックス。 */
+    visibleEndIndex?: number
+    /** A function to render an overlay on top of the scroll pane. / スクロールペインの上にオーバーレイをレンダリングする関数。 */
+    renderOverlay?: () => React.ReactNode
+    /** Initial scroll position. / 初期のスクロール位置。 */
+    initialScrollPosition?: number
+}
+
+export type ScrollPaneInertiaOptions = {
+    /** Maximum velocity applied when inertia starts. / 慣性開始時に適用する最大速度。 */
+    maxVelocity?: number
+    /** Minimum velocity threshold to continue inertia. / 慣性を継続するための最小速度しきい値。 */
+    minVelocity?: number
+    /** Deceleration applied on every frame. / 各フレームで適用される減速度。 */
+    deceleration?: number
+    /** Sampling window in milliseconds for pointer velocity calculation. / ポインタの速度計算に用いるミリ秒単位のサンプリング期間。 */
+    velocitySampleWindow?: number
+    /** Minimum velocity required to start inertia. / 慣性を開始するために必要な最小速度。 */
+    startVelocityThreshold?: number
+}
+
+type ResolvedScrollPaneInertiaOptions = Required<ScrollPaneInertiaOptions>
+
+const DEFAULT_INERTIA_OPTIONS: ResolvedScrollPaneInertiaOptions = {
+    maxVelocity: 6,
+    minVelocity: 0.02,
+    deceleration: 0.0025,
+    velocitySampleWindow: 90,
+    startVelocityThreshold: 0.04,
+}
+
+type ListenerEntry = [string, EventListenerOrEventListenerObject, AddEventListenerOptions | boolean | undefined]
+
+type DragSample = {
+    clientY: number
+    time: number
+}
+
+type DragState = {
+    pointerId: number | null
+    startClientY: number
+    startScroll: number
+    isDragging: boolean
+    shouldCancelNextClick: boolean
+    clickResetTimer: number | null
+    velocitySamples: DragSample[]
+}
+
+/**
+ * Toggles event listeners on a given target.
+ *
+ * 指定ターゲットにイベントリスナーを追加または削除。
+ */
+const toggleListeners = (target: HTMLElement | Window, entries: ListenerEntry[], action: "add" | "remove") => {
+    for (const [type, listener, options] of entries) {
+        if (action === "add") {
+            target.addEventListener(type, listener, options)
+        } else {
+            target.removeEventListener(type, listener, options)
+        }
+    }
+}
+
+export type ScrollPaneHandle = {
+    scrollTo: (newPosition: number | ((prev: number) => number)) => number
+    getScrollPosition: () => number
+    getContentSize: () => number
+    getViewportSize: () => number
+}
+
+/**
+ * A component that provides a scrollable view with a custom scrollbar.
+ *
+ * カスタムスクロールバーを備えたスクロール可能なビューを提供するコンポーネントです。
+ */
+export const ScrollPane = forwardRef<ScrollPaneHandle, ScrollPaneProps>(
+    (
+        {
+            children,
+            contentSize,
+            viewportSize,
+            scrollBarWidth = 12,
+            enableThumbDrag = true,
+            enableTrackClick = true,
+            enableArrowButtons = true,
+            enablePointerDrag = true,
+            onScroll,
+            className,
+            testId,
+            style,
+            background,
+            tapScrollCircleOptions,
+            inertiaOptions,
+            itemCount,
+            renderThumbOverlay,
+            wheelSpeedMultiplier = 1,
+            onWheelHorizontal,
+            contentInsets,
+            visibleStartIndex,
+            visibleEndIndex,
+            renderOverlay,
+            initialScrollPosition = 0,
+        },
+        ref,
+    ) => {
+        // 負の initialScrollPosition は下限 0 にクランプして初回描画・ScrollBar への伝播を防ぐ
+        // Clamp negative initialScrollPosition to 0 so the first render / ScrollBar never receives a negative position.
+        const scrollPositionRef = useRef(Number.isFinite(initialScrollPosition) ? Math.max(0, initialScrollPosition) : 0)
+        const scrollContainerRef = useRef<HTMLDivElement>(null)
+        const contentAreaRef = useRef<HTMLDivElement>(null)
+        // 横委譲コールバックは ref 経由で参照し、wheel リスナの再登録を避ける。
+        const onWheelHorizontalRef = useRef(onWheelHorizontal)
+        useEffect(() => {
+            onWheelHorizontalRef.current = onWheelHorizontal
+        }, [onWheelHorizontal])
+        // generation は慣性ループの世代トークン。stopInertia のたびに進み、
+        // step 実行中に同期的な停止指示が入った場合の再アーム (停止の上書き) を防ぐ。
+        const inertiaStateRef = useRef<{ frame: number | null; velocity: number; lastTimestamp: number | null; generation: number }>({
+            frame: null,
+            velocity: 0,
+            lastTimestamp: null,
+            generation: 0,
+        })
+
+        const resolvedInertiaOptions = useMemo<ResolvedScrollPaneInertiaOptions>(
+            () => ({
+                maxVelocity: inertiaOptions?.maxVelocity ?? DEFAULT_INERTIA_OPTIONS.maxVelocity,
+                minVelocity: inertiaOptions?.minVelocity ?? DEFAULT_INERTIA_OPTIONS.minVelocity,
+                deceleration: inertiaOptions?.deceleration ?? DEFAULT_INERTIA_OPTIONS.deceleration,
+                velocitySampleWindow: inertiaOptions?.velocitySampleWindow ?? DEFAULT_INERTIA_OPTIONS.velocitySampleWindow,
+                startVelocityThreshold: inertiaOptions?.startVelocityThreshold ?? DEFAULT_INERTIA_OPTIONS.startVelocityThreshold,
+            }),
+            [inertiaOptions],
+        )
+
+        const resolvedInsets = useMemo<Required<ScrollPaneContentInsets>>(() => {
+            return {
+                top: Math.max(0, contentInsets?.top ?? 0),
+                bottom: Math.max(0, contentInsets?.bottom ?? 0),
+            }
+        }, [contentInsets])
+
+        // ログ引数はサンクで遅延評価し、DEBUG 抑制時のオブジェクト生成コストをゼロにする
+        Logger.debug("[ScrollPane] ScrollPane rendered", () => ({
+            contentSize,
+            viewportSize,
+            scrollBarWidth,
+            className,
+            style,
+            tapScrollCircleOptions,
+            inertiaOptions,
+            enablePointerDrag,
+            contentInsets: resolvedInsets,
+        }))
+
+        // const size = useMemo(() => ({ contentSize, viewportSize }), [contentSize, viewportSize])
+
+        // contentSize と viewportSize を ref として保持
+        // const sizeRef = useRef({ contentSize, viewportSize })
+
+        const sizeRef = useRef({ contentSize, viewportSize })
+        sizeRef.current = { contentSize, viewportSize }
+
+        const isScrollable = useMemo(() => contentSize > viewportSize, [contentSize, viewportSize])
+
+        // useEffect(() => {  // useEffect では contentSize や viewportSize の変更が反映される前にレンダリングされて位置がズレる可能性があるため、useLayoutEffect を使用
+        //     Logger.debug("[ScrollPane] ScrollPane size updated", { contentSize, viewportSize })
+        //     // サイズが変更されたときに ref を更新
+        //     sizeRef.current = { contentSize, viewportSize }
+        //     forceUpdate() // サイズが変更されたときに強制的に再レンダリング
+        // }, [contentSize, viewportSize])
+
+        // const scrollTo = useCallback(
+        //     (newPosition: number | ((prev: number) => number)) => {
+        //         const { contentSize: currentContentSize, viewportSize: currentViewportSize } = sizeRef.current
+        //         const currentIsScrollable = currentContentSize > currentViewportSize
+        //         const prevPosition = scrollPositionRef.current
+
+        //         Logger.debug("[ScrollPane] scrollTo called", { newPosition, currentContentSize, currentViewportSize, currentIsScrollable, prevPosition })
+
+        //         if (!currentIsScrollable) {
+        //             // スクロール不可の場合は常に0に
+        //             if (scrollPositionRef.current !== 0) {
+        //                 scrollPositionRef.current = 0
+        //                 onScroll?.(0, prevPosition)
+        //             }
+        //             return
+        //         }
+        //         const nextPosition = typeof newPosition === "function" ? newPosition(scrollPositionRef.current) : newPosition
+        //         const newScrollPosition = minmax(nextPosition, 0, currentContentSize - currentViewportSize)
+        //         if (scrollPositionRef.current !== newScrollPosition) {
+        //             scrollPositionRef.current = newScrollPosition
+        //             onScroll?.(newScrollPosition, prevPosition)
+        //         }
+        //     },
+        //     [onScroll]
+        // )
+
+        const scrollTo = useCallback(
+            (newPosition: number | ((prev: number) => number)) => {
+                const { contentSize: currentContentSize, viewportSize: currentViewportSize } = sizeRef.current
+                const currentIsScrollable = currentContentSize > currentViewportSize
+                const prevPosition = scrollPositionRef.current
+
+                // ホットパスのためログ引数はサンクで遅延評価する
+                Logger.debug("[ScrollPane] scrollTo called", () => ({ newPosition, contentSize: currentContentSize, viewportSize: currentViewportSize, currentIsScrollable, prevPosition }))
+
+                if (!currentIsScrollable) {
+                    // スクロール不可の場合は常に0に
+                    if (scrollPositionRef.current !== 0) {
+                        scrollPositionRef.current = 0
+                        onScroll?.(0, prevPosition)
+                    }
+                    return scrollPositionRef.current
+                }
+                const nextPosition = typeof newPosition === "function" ? newPosition(scrollPositionRef.current) : newPosition
+                // 非有限値 (NaN/Infinity) は現位置を維持して弾く。NaN は minmax を素通しして
+                // ref/onScroll に伝播し、以後の相対スクロール (prev + delta) を NaN 連鎖させるため。
+                if (!Number.isFinite(nextPosition)) {
+                    Logger.warn("[ScrollPane] scrollTo received a non-finite position; keeping the current position", { nextPosition })
+                    return scrollPositionRef.current
+                }
+                const maxScrollPosition = Math.max(currentContentSize - currentViewportSize, 0)
+                const newScrollPosition = minmax(nextPosition, 0, maxScrollPosition)
+                if (scrollPositionRef.current !== newScrollPosition) {
+                    scrollPositionRef.current = newScrollPosition
+                    onScroll?.(newScrollPosition, prevPosition)
+                }
+                return scrollPositionRef.current
+            },
+            [onScroll],
+        )
+
+        const stopInertia = useCallback(() => {
+            const state = inertiaStateRef.current
+            // 世代を進め、実行中の step (cancelAnimationFrame が効かない同期再入) にも停止を伝える
+            state.generation += 1
+            if (state.frame !== null) {
+                cancelAnimationFrame(state.frame)
+            }
+            state.frame = null
+            state.velocity = 0
+            state.lastTimestamp = null
+        }, [])
+
+        const stopInertiaRef = useRef(stopInertia)
+        useEffect(() => {
+            stopInertiaRef.current = stopInertia
+        }, [stopInertia])
+
+        // アンマウント時に慣性スクロールの RAF ループを停止し、破棄後に onScroll が発火し続けるのを防ぐ
+        // Stop the inertia RAF loop on unmount so onScroll cannot keep firing after the component is destroyed.
+        useEffect(() => {
+            return () => {
+                stopInertiaRef.current()
+            }
+        }, [])
+
+        const startInertia = useCallback(
+            (initialVelocity: number) => {
+                if (!isScrollable) {
+                    return
+                }
+
+                const { maxVelocity, minVelocity, deceleration, startVelocityThreshold } = resolvedInertiaOptions
+
+                const limitedVelocity = minmax(initialVelocity, -maxVelocity, maxVelocity)
+                if (Math.abs(limitedVelocity) < startVelocityThreshold) {
+                    return
+                }
+
+                stopInertia()
+
+                inertiaStateRef.current.velocity = limitedVelocity
+                inertiaStateRef.current.lastTimestamp = null
+                // このループ固有の世代を捕捉する (stopInertia は generation を進めるため、
+                // 以降どこかで stopInertia が呼ばれると不一致になり step が自壊する)
+                const generation = inertiaStateRef.current.generation
+
+                const step = (timestamp: number) => {
+                    const state = inertiaStateRef.current
+                    // 停止指示済みの古い世代の step は何もしない (防御的チェック)
+                    if (state.generation !== generation) {
+                        return
+                    }
+                    if (state.lastTimestamp === null) {
+                        state.lastTimestamp = timestamp
+                        state.frame = requestAnimationFrame(step)
+                        return
+                    }
+
+                    const deltaTime = timestamp - state.lastTimestamp
+                    state.lastTimestamp = timestamp
+
+                    if (deltaTime <= 0) {
+                        state.frame = requestAnimationFrame(step)
+                        return
+                    }
+
+                    const previousVelocity = state.velocity
+                    let nextVelocity = previousVelocity
+                    const decelerationAmount = deceleration * deltaTime
+                    if (previousVelocity > 0) {
+                        nextVelocity = Math.max(0, previousVelocity - decelerationAmount)
+                    } else if (previousVelocity < 0) {
+                        nextVelocity = Math.min(0, previousVelocity + decelerationAmount)
+                    }
+
+                    const averageVelocity = (previousVelocity + nextVelocity) / 2
+                    const distance = averageVelocity * deltaTime
+                    const previousPosition = scrollPositionRef.current
+
+                    if (distance !== 0) {
+                        scrollTo((prevPositionInternal) => prevPositionInternal + distance)
+                    }
+
+                    // scrollTo の onScroll から同期的に stopInertia (handle.scrollTo 等) が呼ばれた場合は
+                    // 停止を尊重し、velocity の上書きも frame の再アームもしない (停止の黙殺を防ぐ)
+                    if (inertiaStateRef.current.generation !== generation) {
+                        return
+                    }
+
+                    const nextPosition = scrollPositionRef.current
+                    const { contentSize: currentContentSize, viewportSize: currentViewportSize } = sizeRef.current
+                    const maxScrollPosition = Math.max(currentContentSize - currentViewportSize, 0)
+
+                    state.velocity = nextVelocity
+
+                    const reachedBoundary = nextPosition === previousPosition || (nextPosition <= 0 && nextVelocity <= 0) || (nextPosition >= maxScrollPosition && nextVelocity >= 0)
+
+                    if (Math.abs(nextVelocity) < minVelocity || reachedBoundary) {
+                        stopInertia()
+                        return
+                    }
+
+                    state.frame = requestAnimationFrame(step)
+                }
+
+                inertiaStateRef.current.frame = requestAnimationFrame(step)
+            },
+            [isScrollable, resolvedInertiaOptions, scrollTo, stopInertia],
+        )
+
+        const startInertiaRef = useRef(startInertia)
+        useEffect(() => {
+            startInertiaRef.current = startInertia
+        }, [startInertia])
+
+        useLayoutEffect(() => {
+            // contentSize と viewportSize の最新値を保持して scrollTo の参照を安定させる
+            sizeRef.current = { contentSize, viewportSize }
+        }, [contentSize, viewportSize])
+
+        // Prevent native scrolling on the content area.
+        // Since the content is positioned absolutely, the container's scrollTop should always be 0.
+        // However, browsers may sometimes automatically scroll the container (e.g., when DevTools is open, or due to focus management).
+        // This effect detects such native scroll events and forces scrollTop back to 0.
+        //
+        // コンテンツ領域のネイティブスクロールを防止します。
+        // コンテンツは絶対配置されているため、コンテナの scrollTop は常に 0 である必要があります。
+        // しかし、ブラウザは時折（例：DevToolsが開いている場合やフォーカス管理などにより）コンテナを自動的にスクロールさせることがあります。
+        // このエフェクトは、そのようなネイティブスクロールイベントを検出し、scrollTop を強制的に 0 にリセットします。
+        useLayoutEffect(() => {
+            const element = contentAreaRef.current
+            if (!element) return
+
+            const handleScroll = () => {
+                if (element.scrollTop !== 0) {
+                    // ホットパスのためログ引数はサンクで遅延評価する
+                    Logger.debug("[ScrollPane] Native scroll detected, resetting to 0", () => ({ scrollTop: element.scrollTop }))
+                    element.scrollTop = 0
+                }
+                if (element.scrollLeft !== 0) {
+                    element.scrollLeft = 0
+                }
+            }
+
+            element.addEventListener("scroll", handleScroll)
+            return () => element.removeEventListener("scroll", handleScroll)
+        }, [])
+
+        // contentSize または viewportSize が変更されたときにスクロール位置を調整します。
+        useLayoutEffect(() => {
+            // useEffect では contentSize や viewportSize の変更が反映される前にレンダリングされて位置がズレる可能性があるため、useLayoutEffect を使用。フリッカー防止も。
+            if (isScrollable) {
+                // ログ引数はサンクで遅延評価し、抑制時のオブジェクト生成を回避する
+                Logger.debug("[ScrollPane] Adjusting scroll position due to content or viewport size change", () => ({ contentSize, viewportSize, scrollPosition: scrollPositionRef.current }))
+                const maxScrollPosition = minmax(contentSize - viewportSize, 0, contentSize)
+                if (scrollPositionRef.current > maxScrollPosition) {
+                    scrollTo(maxScrollPosition)
+                }
+            } else {
+                scrollTo(0)
+            }
+        }, [isScrollable, scrollTo, contentSize, viewportSize])
+
+        useEffect(() => {
+            // ホイールイベントのハンドラ
+            const handleWheel = (event: WheelEvent) => {
+                // 横委譲: ハンドラがある場合のみ、横優勢ジェスチャ (または shift+ホイール) を横として処理する。
+                // ハンドラ未指定時はこのブロックを丸ごとスキップし、既存の縦挙動と完全一致する。
+                // ctrl+wheel はブラウザのズーム (ピンチズーム/ctrl+shift+ホイール等) なので横取りせず常に素通しする。
+                if (onWheelHorizontalRef.current && !event.ctrlKey) {
+                    const usesShiftAxis = event.shiftKey && event.deltaX === 0
+                    const horizontalDelta = usesShiftAxis ? event.deltaY : event.deltaX
+                    const verticalDelta = usesShiftAxis ? 0 : event.deltaY
+                    if (horizontalDelta !== 0 && Math.abs(horizontalDelta) >= Math.abs(verticalDelta)) {
+                        event.preventDefault()
+                        stopInertia()
+                        let deltaX = horizontalDelta
+                        if (event.deltaMode === 1) {
+                            deltaX *= 16 // DOM_DELTA_LINE
+                        } else if (event.deltaMode === 2) {
+                            deltaX *= viewportSize // DOM_DELTA_PAGE
+                        }
+                        onWheelHorizontalRef.current(deltaX)
+                        return
+                    }
+                }
+
+                if (!isScrollable) {
+                    return
+                }
+
+                // ctrl+wheel はブラウザのピンチズームなので横取りしない
+                // ctrl+wheel is browser pinch-zoom, so leave it to the browser.
+                if (event.ctrlKey) {
+                    return
+                }
+
+                // 縦方向の移動が無いホイール（水平スワイプ等）は祖先のスクロールへ委ねる
+                // A wheel event without vertical delta (e.g. horizontal swipe) is left to ancestor scrolling.
+                if (event.deltaY === 0) {
+                    return
+                }
+
+                event.preventDefault()
+
+                stopInertia()
+
+                let deltaY = event.deltaY
+
+                // deltaMode に応じてスクロール量を調整
+                if (event.deltaMode === 1) {
+                    // DOM_DELTA_LINE: 行単位のスクロール
+                    const lineHeight = 16 // 1行のおおよその高さ (ピクセル)
+                    deltaY *= lineHeight
+                } else if (event.deltaMode === 2) {
+                    // DOM_DELTA_PAGE: ページ単位のスクロール
+                    deltaY *= viewportSize // ビューポートの高さを基準にスクロール
+                }
+
+                if (wheelSpeedMultiplier !== 1) {
+                    deltaY *= wheelSpeedMultiplier
+                }
+
+                // ホットパスのためログ引数はサンクで遅延評価し、抑制時は DOM 読み取り (scrollTop) も発生させない
+                Logger.debug("[ScrollPane] wheel event", () => ({ deltaY, scrollPosition: scrollPositionRef.current, wheelSpeedMultiplier, deltaMode: event.deltaMode, scrollTop: contentAreaRef.current?.scrollTop }))
+
+                // スクロール位置を更新
+                scrollTo((prev) => prev + deltaY)
+            }
+
+            const scrollContainer = scrollContainerRef.current
+            if (scrollContainer) {
+                // wheel イベントリスナーを passive: false で登録し、preventDefault を可能にする
+                scrollContainer.addEventListener("wheel", handleWheel, { passive: false })
+            }
+
+            // クリーンアップ関数
+            return () => {
+                if (scrollContainer) {
+                    scrollContainer.removeEventListener("wheel", handleWheel)
+                }
+            }
+        }, [isScrollable, scrollTo, stopInertia, viewportSize, wheelSpeedMultiplier])
+
+        useImperativeHandle(
+            ref,
+            () => ({
+                scrollTo: (pos) => {
+                    stopInertia()
+                    return scrollTo(pos)
+                },
+                getScrollPosition: () => scrollPositionRef.current,
+                getContentSize: () => contentSize,
+                getViewportSize: () => viewportSize,
+            }),
+            [scrollTo, contentSize, viewportSize, stopInertia],
+        )
+
+        const scrollToRef = useRef(scrollTo)
+        useEffect(() => {
+            scrollToRef.current = scrollTo
+        }, [scrollTo])
+
+        const id = useId()
+
+        const dragStateRef = useRef<DragState>({
+            pointerId: null,
+            startClientY: 0,
+            startScroll: 0,
+            isDragging: false,
+            shouldCancelNextClick: false,
+            clickResetTimer: null,
+            velocitySamples: [],
+        })
+
+        const enablePointerDragRef = useRef(enablePointerDrag)
+        useEffect(() => {
+            enablePointerDragRef.current = enablePointerDrag
+        }, [enablePointerDrag])
+
+        const isScrollableRef = useRef(isScrollable)
+        useEffect(() => {
+            isScrollableRef.current = isScrollable
+        }, [isScrollable])
+
+        const inertiaOptionsRef = useRef(resolvedInertiaOptions)
+        useEffect(() => {
+            inertiaOptionsRef.current = resolvedInertiaOptions
+        }, [resolvedInertiaOptions])
+
+        useEffect(() => {
+            if (enablePointerDrag) {
+                return
+            }
+            const element = contentAreaRef.current
+            const state = dragStateRef.current
+            // pointerId=0 (Firefox のマウス) を falsy として弾かないよう !== null で判定する
+            // Compare with null so pointerId=0 (Firefox mouse) is not skipped as falsy.
+            if (state.pointerId !== null && element?.hasPointerCapture(state.pointerId)) {
+                element.releasePointerCapture(state.pointerId)
+            }
+            if (state.clickResetTimer !== null) {
+                window.clearTimeout(state.clickResetTimer)
+                state.clickResetTimer = null
+            }
+            state.pointerId = null
+            state.startClientY = 0
+            state.startScroll = 0
+            state.isDragging = false
+            state.shouldCancelNextClick = false
+            state.velocitySamples = []
+        }, [enablePointerDrag])
+
+        useEffect(() => {
+            const element = contentAreaRef.current
+            if (!element) {
+                return
+            }
+
+            const DRAG_ACTIVATION_THRESHOLD = 6
+            const getTimestamp = () => (typeof performance !== "undefined" && typeof performance.now === "function" ? performance.now() : Date.now())
+
+            const resetDragState = () => {
+                const state = dragStateRef.current
+                state.pointerId = null
+                state.startClientY = 0
+                state.startScroll = 0
+                state.isDragging = false
+                state.velocitySamples = []
+            }
+
+            const clearClickTimer = () => {
+                const state = dragStateRef.current
+                if (state.clickResetTimer !== null) {
+                    window.clearTimeout(state.clickResetTimer)
+                    state.clickResetTimer = null
+                }
+            }
+
+            const pushVelocitySample = (clientY: number) => {
+                const state = dragStateRef.current
+                const timestamp = getTimestamp()
+                state.velocitySamples.push({ clientY, time: timestamp })
+                const windowMs = inertiaOptionsRef.current.velocitySampleWindow
+                state.velocitySamples = state.velocitySamples.filter((sample) => timestamp - sample.time <= windowMs)
+            }
+
+            const shouldIgnoreTarget = (target: EventTarget | null) => target instanceof HTMLElement && target.closest("[data-scrollpane-ignore-drag='true']") !== null
+
+            const handleClickCapture = (event: MouseEvent) => {
+                const state = dragStateRef.current
+                if (!state.shouldCancelNextClick) {
+                    return
+                }
+                event.preventDefault()
+                event.stopPropagation()
+                state.shouldCancelNextClick = false
+            }
+
+            const startDragging = (event: PointerEvent) => {
+                const state = dragStateRef.current
+                if (state.isDragging) {
+                    return
+                }
+                state.isDragging = true
+                state.shouldCancelNextClick = true
+                if (!element.hasPointerCapture(event.pointerId)) {
+                    // 注意: キャプチャは pointerdown 時ではなくドラッグ確定時に取得する。
+                    // pointerdown で即キャプチャすると click がキャプチャ要素へリターゲットされ、
+                    // ペイン内の子要素 (行など) の click ハンドラが一切発火しなくなる (Chromium 実測)。
+                    // ドラッグ確定後は shouldCancelNextClick で click を意図的に抑止するため副作用がない。
+                    try {
+                        element.setPointerCapture(event.pointerId)
+                    } catch {
+                        // ポインタが既に非アクティブだと NotFoundError になり得る。キャプチャ無しでもドラッグは継続可能。
+                    }
+                }
+                pushVelocitySample(event.clientY)
+            }
+
+            // pointerup を受け取れないままドラッグ継続が不可能になったときの共通終了処理。
+            // Shared teardown for cases where the drag can no longer continue without receiving a pointerup.
+            const abortDrag = (pointerId: number) => {
+                const state = dragStateRef.current
+                if (element.hasPointerCapture(pointerId)) {
+                    element.releasePointerCapture(pointerId)
+                }
+                state.shouldCancelNextClick = false
+                clearClickTimer()
+                resetDragState()
+            }
+
+            const handlePointerMove = (event: PointerEvent) => {
+                const state = dragStateRef.current
+                if (state.pointerId !== event.pointerId) {
+                    return
+                }
+                // ボタン非押下の pointermove は pointerup の喪失 (iframe 上での解放・Alt+Tab 等) を意味する。
+                // stale な dragState を破棄し、hover 移動がカーソル追従スクロール化するのを根絶する。
+                if (event.buttons === 0) {
+                    abortDrag(event.pointerId)
+                    return
+                }
+                if (!(enablePointerDragRef.current && isScrollableRef.current)) {
+                    return
+                }
+                if (!state.isDragging) {
+                    const distanceY = Math.abs(event.clientY - state.startClientY)
+                    if (distanceY < DRAG_ACTIVATION_THRESHOLD) {
+                        return
+                    }
+                    startDragging(event)
+                    if (!state.isDragging) {
+                        return
+                    }
+                }
+
+                pushVelocitySample(event.clientY)
+
+                const deltaY = event.clientY - state.startClientY
+                const nextPosition = state.startScroll - deltaY
+                scrollToRef.current(nextPosition)
+
+                if (event.cancelable) {
+                    event.preventDefault()
+                }
+            }
+
+            const handlePointerUp = (event: PointerEvent) => {
+                const state = dragStateRef.current
+                if (state.pointerId !== event.pointerId) {
+                    return
+                }
+
+                if (state.isDragging && state.shouldCancelNextClick && event.cancelable) {
+                    event.preventDefault()
+                    event.stopPropagation()
+                }
+
+                // 解放時刻を基準にサンプルを再枝刈りする。pushVelocitySample の枝刈りは
+                // 「最後の pointermove の時刻」基準のため、ドラッグ後に静止したまま離すと
+                // 古いサンプルが残り、静止前の速度で慣性が誤発火してしまう。
+                // 静止していた場合は解放時のサンプル 1 件だけが残り、下の length >= 2 ガードで慣性が発火しない。
+                if (state.isDragging) {
+                    pushVelocitySample(event.clientY)
+                }
+
+                let inertiaVelocity = 0
+                if (state.isDragging && state.velocitySamples.length >= 2) {
+                    const samples = state.velocitySamples
+                    const windowMs = inertiaOptionsRef.current.velocitySampleWindow
+                    const lastSample = samples[samples.length - 1]
+                    const firstSample = samples.find((sample) => lastSample.time - sample.time <= windowMs) ?? samples[0]
+                    if (lastSample && firstSample && lastSample.time !== firstSample.time) {
+                        const deltaClientY = lastSample.clientY - firstSample.clientY
+                        const deltaTime = lastSample.time - firstSample.time
+                        inertiaVelocity = -(deltaClientY / deltaTime)
+                    }
+                }
+
+                clearClickTimer()
+                if (state.shouldCancelNextClick) {
+                    state.clickResetTimer = window.setTimeout(() => {
+                        const latest = dragStateRef.current
+                        latest.shouldCancelNextClick = false
+                        latest.clickResetTimer = null
+                    }, 0)
+                }
+
+                const threshold = inertiaOptionsRef.current.startVelocityThreshold
+                // resetDragState で pointerId を null にしてからキャプチャを解放する (意図的解放)。
+                // releasePointerCapture が lostpointercapture を同期発火するブラウザでも、
+                // handleLostPointerCapture は pointerId 不一致で無視されるため、abortDrag による
+                // shouldCancelNextClick / clickResetTimer の破棄 (click 抑止の喪失) が起きない。
+                resetDragState()
+                if (element.hasPointerCapture(event.pointerId)) {
+                    element.releasePointerCapture(event.pointerId)
+                }
+
+                if (Math.abs(inertiaVelocity) >= threshold) {
+                    startInertiaRef.current?.(inertiaVelocity)
+                }
+            }
+
+            const handlePointerDown = (event: PointerEvent) => {
+                // アクティブなドラッグ中 (pointerId 保持中) の別ポインタの pointerdown は無視する (先勝ち)。
+                // 上書きを許すと 1 本目のドラッグが乗っ取られ、shouldCancelNextClick のクリアで
+                // 1 本目解放時の click 抑止も失われるため。
+                if (dragStateRef.current.pointerId !== null) {
+                    return
+                }
+                if (!(enablePointerDragRef.current && isScrollableRef.current)) {
+                    return
+                }
+                if (event.button !== 0 && event.pointerType === "mouse") {
+                    return
+                }
+                if (event.ctrlKey || event.metaKey || event.altKey) {
+                    return
+                }
+                if (shouldIgnoreTarget(event.target)) {
+                    return
+                }
+
+                window.dispatchEvent(new CustomEvent(TAP_SCROLL_CANCEL_EVENT, { detail: { paneId: id } }))
+
+                stopInertiaRef.current?.()
+
+                const state = dragStateRef.current
+                clearClickTimer()
+                state.pointerId = event.pointerId
+                state.startClientY = event.clientY
+                state.startScroll = scrollPositionRef.current
+                state.isDragging = false
+                state.shouldCancelNextClick = false
+                state.velocitySamples = []
+            }
+
+            const handlePointerCancel = (event: PointerEvent) => {
+                const state = dragStateRef.current
+                if (state.pointerId !== event.pointerId) {
+                    return
+                }
+                abortDrag(event.pointerId)
+            }
+
+            const handleLostPointerCapture = (event: PointerEvent) => {
+                const state = dragStateRef.current
+                if (state.pointerId !== event.pointerId) {
+                    return
+                }
+                // OS/ブラウザ都合でキャプチャが強制解放されると pointerup/pointercancel が届かないことがある。
+                // capture 喪失=ドラッグ終了に統一し、stale な dragState が残らないようにする。
+                abortDrag(event.pointerId)
+            }
+
+            // pointermove/up/cancel は window のみに登録する。
+            // ポインターキャプチャ取得後はイベントが element にリターゲットされ window までバブリングするため、
+            // element にも登録すると 1 回のイベントを二重処理してしまう。window 側だけでキャプチャ未取得時のペイン外追従もカバーできる。
+            // Register pointermove/up/cancel on window only. After pointer capture, events retarget to the
+            // element and bubble to window, so registering on both would process each event twice.
+            // window alone also covers out-of-pane tracking when capture has not been acquired.
+            const elementEntries: ListenerEntry[] = [
+                ["click", handleClickCapture as EventListenerOrEventListenerObject, true],
+                ["pointerdown", handlePointerDown as EventListenerOrEventListenerObject, { passive: false }],
+                ["lostpointercapture", handleLostPointerCapture as EventListenerOrEventListenerObject, undefined],
+            ]
+            const windowEntries: ListenerEntry[] = [
+                ["pointermove", handlePointerMove as EventListenerOrEventListenerObject, { passive: false }],
+                ["pointerup", handlePointerUp as EventListenerOrEventListenerObject, undefined],
+                ["pointercancel", handlePointerCancel as EventListenerOrEventListenerObject, undefined],
+            ]
+
+            toggleListeners(element, elementEntries, "add")
+            toggleListeners(window, windowEntries, "add")
+
+            return () => {
+                toggleListeners(element, elementEntries, "remove")
+                toggleListeners(window, windowEntries, "remove")
+                const state = dragStateRef.current
+                if (state.pointerId !== null && element.hasPointerCapture(state.pointerId)) {
+                    element.releasePointerCapture(state.pointerId)
+                }
+                clearClickTimer()
+                resetDragState()
+            }
+        }, [id])
+
+        return (
+            <div ref={scrollContainerRef} data-testid={testId} className={twMerge("aqvs-scroll-pane", className)} style={style}>
+                <div
+                    ref={contentAreaRef}
+                    className={twMerge("aqvs-scroll-pane-content")}
+                    style={{
+                        height: viewportSize,
+                        paddingTop: resolvedInsets.top,
+                        paddingBottom: resolvedInsets.bottom,
+                        // スクロール不能時 (contentSize <= viewportSize) は touch-action を通常に戻し、
+                        // 短いリスト上のタッチがページ全体のパンを妨げるデッドゾーン化を防ぐ
+                        ...(enablePointerDrag && isScrollable ? { touchAction: "none" } : {}),
+                    }}
+                    id={id}>
+                    {background}
+                    {children(scrollPositionRef.current)}
+                </div>
+                <ScrollBar
+                    key="scrollbar"
+                    contentSize={contentSize}
+                    viewportSize={viewportSize}
+                    scrollPosition={scrollPositionRef.current}
+                    onScroll={scrollTo}
+                    enableThumbDrag={enableThumbDrag}
+                    enableTrackClick={enableTrackClick}
+                    enableArrowButtons={enableArrowButtons}
+                    scrollBarWidth={scrollBarWidth}
+                    ariaControls={id}
+                    tapScrollCircleOptions={tapScrollCircleOptions}
+                    itemCount={itemCount}
+                    renderThumbOverlay={renderThumbOverlay}
+                    visibleStartIndex={visibleStartIndex}
+                    visibleEndIndex={visibleEndIndex}
+                />
+                {renderOverlay?.()}
+            </div>
+        )
+    },
+)
+
+// TODO: 上からスクロールと下からスクロールで fenwick ツリーの走査方向とスクロールペインの描画位置の基準を変えてパフォーマンスを最適化する
+// TODO: 矢印キーでのスクロールで下スクロールと上スクロールのページ送りの挙動が異なるのを修正またはオプション化する