@aiquants/virtualscroll 1.18.5 → 1.19.1

package/src/ScrollBar.tsx

@@ -0,0 +1,1397 @@
+/**
+ * Provides a customizable virtual scrollbar component with auxiliary tap scrolling features.
+ *
+ * カスタマイズ可能な仮想スクロールバーと補助的なタップスクロール機能を提供。
+ */
+import type { CSSProperties, ReactNode } from "react"
+import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState } from "react"
+import { twMerge } from "tailwind-merge"
+import { Logger } from "./logger.ts"
+import { TapScrollCircle, type TapScrollCircleDragState, type TapScrollCircleHandle, type TapScrollCircleRenderProps } from "./TapScrollCircle.tsx"
+import { minmax } from "./utils.ts"
+
+/**
+ * Configuration for scrollbar orientation (vertical or horizontal).
+ *
+ * スクロールバーの向き（垂直または水平）に関する設定。
+ */
+type OrientationConfig = {
+    mainSizeKey: "width" | "height"
+    crossSizeKey: "width" | "height"
+    positionKey: "left" | "top"
+    selectDelta: (deltaX: number, deltaY: number) => number
+    getPointerCoordinate: (point: { clientX: number; clientY: number }) => number
+    arrowLabels: [string, string]
+    arrowIcons: [string, string]
+    directionClass: string
+    orientation: "vertical" | "horizontal"
+}
+
+/**
+ * Options for arrow button auto-repeat behavior.
+ *
+ * 矢印ボタンの自動リピート動作に関するオプション。
+ */
+type ArrowAutoRepeatOptions = {
+    /** Whether arrow buttons interaction is allowed / 矢印ボタンの使用が許可されているか */
+    canUseArrowButtons: boolean
+    /** Whether arrow buttons are enabled in configuration / 設定で矢印ボタンが有効化されているか */
+    enableArrowButtons: boolean
+    /** Function to reset tap scroll state / タップスクロール状態をリセットする関数 */
+    resetTapScroll: () => void
+    /** Function to scroll by a step / ステップ単位でスクロールする関数 */
+    scrollByStep: (direction: 1 | -1) => void
+}
+
+/**
+ * Handlers for arrow button interactions.
+ *
+ * 矢印ボタンのインタラクション用ハンドラー。
+ */
+type ArrowAutoRepeatHandlers = {
+    handleArrowPointerDown: (direction: 1 | -1) => (event: React.PointerEvent<HTMLButtonElement>) => void
+    handleArrowPointerUp: () => void
+    handleArrowKeyDown: (direction: 1 | -1) => (event: React.KeyboardEvent<HTMLButtonElement>) => void
+}
+
+/**
+ * Options for visual feedback on the scroll thumb.
+ *
+ * スクロールつまみの視覚的フィードバックに関するオプション。
+ */
+type ThumbVisualFeedbackOptions = {
+    isDragging: boolean
+    isThumbHovered: boolean
+    enableThumbDrag: boolean
+}
+
+/**
+ * The state of the scroll thumb for styling purposes.
+ *
+ * スタイリング目的のスクロールつまみの状態。
+ */
+type ScrollBarThumbState = "disabled" | "idle" | "hover" | "dragging"
+
+/**
+ * Options to customize the auxiliary tap scroll circle.
+ *
+ * タップスクロール用サークルをカスタマイズするためのオプション。
+ */
+export type ScrollBarTapCircleOptions = {
+    /** Enable or disable the tap scroll circle. / タップサークルを有効化または無効化。 */
+    enabled?: boolean
+    /** Circle diameter in pixels. / サークルの直径 (ピクセル)。 */
+    size?: number
+    /** Horizontal offset in pixels. / 水平方向オフセット (ピクセル)。 */
+    offsetX?: number
+    /** Vertical offset in pixels. / 垂直方向オフセット (ピクセル)。 */
+    offsetY?: number
+    /** Additional class names for the circle. / サークルの追加クラス名。 */
+    className?: string
+    /** Maximum drag distance used for visual feedback. / ビジュアルフィードバックに利用する最大ドラッグ距離。 */
+    maxVisualDistance?: number
+    /** Maximum speed multiplier relative to viewport size. / ビューポートサイズに対する最大速度倍率。 */
+    maxSpeedMultiplier?: number
+    /** Minimum speed multiplier relative to viewport size. / ビューポートサイズに対する最小速度倍率。 */
+    minSpeedMultiplier?: number
+    /** Base opacity multiplier for the circle visuals. / サークル表示の基準透明度倍率。 */
+    opacity?: number
+    /** Custom visual renderer for the tap circle. / タップサークルのカスタムビジュアルのレンダラー。 */
+    renderVisual?: (props: TapScrollCircleRenderProps) => ReactNode
+    /** Optional exponential cap configuration for max speed. / 最大速度に指数関数的な上限を設定するためのオプション設定。 */
+    maxSpeedCurve?: {
+        /** Steepness factor for the exponential curve. / 指数関数の急峻さを決定する要素。 */
+        exponentialSteepness: number
+        /** Scale factor for the exponential curve. / 指数関数のスケールファクター。 */
+        exponentialScale?: number
+        /** Additional eased offset to apply to the curve. / 曲線に適用する追加のイーズドオフセット。 */
+        easedOffset?: number
+    }
+}
+
+type ResolvedTapScrollCircleOptions = Required<Omit<ScrollBarTapCircleOptions, "className" | "maxVisualDistance" | "renderVisual" | "maxSpeedCurve">> & {
+    className?: string
+    maxVisualDistance: number
+    renderVisual?: ScrollBarTapCircleOptions["renderVisual"]
+    maxSpeedCurve?: ScrollBarTapCircleOptions["maxSpeedCurve"]
+}
+
+type TapScrollCancelEventDetail = {
+    paneId?: string
+}
+
+/** Custom event name emitted when external interactions should cancel tap scrolling. / 外部操作によってタップスクロールをキャンセルすべき際に発行されるカスタムイベント名。 */
+export const TAP_SCROLL_CANCEL_EVENT = "virtualscroll:tap-scroll-cancel"
+
+/**
+ * Props for the ScrollBar component.
+ *
+ * ScrollBar コンポーネントの Props。
+ */
+export type ScrollBarThumbOverlayRenderProps = {
+    orientation: "vertical" | "horizontal"
+    scrollPosition: number
+    maxScrollPosition: number
+    contentSize: number
+    viewportSize: number
+    thumbSize: number
+    thumbPosition: number
+    thumbCenter: number
+    trackSize: number
+    isDragging: boolean
+    isTapScrollActive: boolean
+    visibleStartIndex?: number
+    visibleEndIndex?: number
+}
+
+export type ScrollBarProps = {
+    /** The total size of the content. / コンテンツの総サイズ。 */
+    contentSize: number
+    /** The size of the visible area. / 表示領域のサイズ。 */
+    viewportSize: number
+    /** The current scroll position. / 現在のスクロール位置。 */
+    scrollPosition: number
+    /** A callback function invoked to adjust scroll position. Accepts next position or updater. / スクロール位置を調整するためのコールバック。次位置または更新関数を受け取る。 */
+    onScroll?: (scrollPosition: number | ((prevPosition: number) => number), prevPosition?: number) => number | undefined
+    /** Whether grabbing the scrollbar thumb is allowed. / スクロールバーのつまみ操作を許可するかどうか。 */
+    enableThumbDrag?: boolean
+    /** Whether clicking on the track moves the scrollbar. / スクロールバーのトラッククリック操作を許可するかどうか。 */
+    enableTrackClick?: boolean
+    /** Whether arrow buttons control the scroll position. / 矢印ボタンによるスクロール操作を許可するかどうか。 */
+    enableArrowButtons?: boolean
+    /** Whether the scrollbar is horizontal. / スクロールバーが水平かどうか。 */
+    horizontal?: boolean
+    /** The width of the scrollbar. / スクロールバーの幅。 */
+    scrollBarWidth?: number
+    /** Additional class names for the component. / コンポーネントの追加のクラス名。 */
+    className?: string
+    /** The ID of the element that the scrollbar controls. / スクロールバーが制御する要素の ID。 */
+    ariaControls?: string
+    /** Configuration for the tap scroll circle. / タップサークルの設定。 */
+    tapScrollCircleOptions?: ScrollBarTapCircleOptions
+    /** Total number of scrollable items (optional). / スクロール対象アイテムの総数（任意）。 */
+    itemCount?: number
+    /** Optional renderer for thumb-adjacent overlays. / サム付近に重ねるオーバーレイのレンダラー。 */
+    renderThumbOverlay?: (props: ScrollBarThumbOverlayRenderProps) => ReactNode
+    /** The index of the first visible item. / 最初の可視アイテムのインデックス。 */
+    visibleStartIndex?: number
+    /** The index of the last visible item. / 最後の可視アイテムのインデックス。 */
+    visibleEndIndex?: number
+}
+
+/** The minimum size of the scrollbar thumb. / スクロールバーのつまみの最小サイズ。 */
+const MIN_THUMB_SIZE = 20
+const ARROW_HOLD_DELAY = 250
+const ARROW_HOLD_INTERVAL = 60
+const MIN_ARROW_STEP = 20
+const ARROW_STEP_DIVISOR = 20
+const TAP_SCROLL_MAX_DISTANCE = 240
+const TAP_SCROLL_INITIAL_STATE: TapScrollCircleDragState = { active: false, offsetX: 0, offsetY: 0, distance: 0, direction: 0, pointerId: null }
+
+const TAP_SCROLL_AUTO_SPEED_BASE_MULTIPLIER = 2.2
+const TAP_SCROLL_AUTO_SPEED_PER_ORDER = 8
+const TAP_SCROLL_AUTO_SPEED_MAX_MULTIPLIER = 120
+// Cap the per-frame integration step so a backgrounded tab (paused rAF) does not
+// teleport on resume, while still letting realistic low frame rates (down to ~10fps)
+// advance at the configured px/second speed instead of being throttled to 60fps.
+// バックグラウンド復帰時の飛びを防ぎつつ、低フレームレート環境でも設定速度(px/秒)を維持するための上限。
+const TAP_SCROLL_MAX_FRAME_DELTA_SECONDS = 1 / 10
+
+const DEFAULT_TAP_SCROLL_CIRCLE_OPTIONS: ResolvedTapScrollCircleOptions = {
+    enabled: true,
+    size: 40,
+    offsetX: -80,
+    offsetY: 0,
+    className: undefined,
+    maxVisualDistance: TAP_SCROLL_MAX_DISTANCE,
+    maxSpeedMultiplier: TAP_SCROLL_AUTO_SPEED_BASE_MULTIPLIER,
+    minSpeedMultiplier: 0.2,
+    opacity: 0.9,
+    renderVisual: undefined,
+    maxSpeedCurve: undefined,
+}
+
+/**
+ * Creates the orientation dependent configuration for the scrollbar.
+ *
+ * スクロールバーの向きに応じた設定を生成。
+ */
+const createOrientationConfig = (horizontal: boolean): OrientationConfig => {
+    if (horizontal) {
+        return {
+            mainSizeKey: "width",
+            crossSizeKey: "height",
+            positionKey: "left",
+            selectDelta: (deltaX: number, _deltaY: number) => deltaX,
+            getPointerCoordinate: ({ clientX }) => clientX,
+            arrowLabels: ["Scroll left", "Scroll right"],
+            arrowIcons: ["◀", "▶"],
+            directionClass: "aqvs-scrollbar-horizontal",
+            orientation: "horizontal",
+        }
+    }
+
+    return {
+        mainSizeKey: "height",
+        crossSizeKey: "width",
+        positionKey: "top",
+        selectDelta: (_deltaX: number, deltaY: number) => deltaY,
+        getPointerCoordinate: ({ clientY }) => clientY,
+        arrowLabels: ["Scroll up", "Scroll down"],
+        arrowIcons: ["▲", "▼"],
+        directionClass: "aqvs-scrollbar-vertical",
+        orientation: "vertical",
+    }
+}
+
+/**
+ * Resolves user supplied tap scroll circle options with internal defaults.
+ *
+ * ユーザー指定のタップスクロールサークル設定を内部デフォルトで補完。
+ */
+const resolveTapScrollCircleOptions = (options: ScrollBarTapCircleOptions | undefined, itemCount?: number): ResolvedTapScrollCircleOptions => {
+    const manualMaxSpeedMultiplier = options?.maxSpeedMultiplier
+    const maxSpeedMultiplier = typeof manualMaxSpeedMultiplier === "number" ? manualMaxSpeedMultiplier : computeAutoTapScrollMaxSpeedMultiplier(itemCount)
+
+    return {
+        enabled: options?.enabled ?? DEFAULT_TAP_SCROLL_CIRCLE_OPTIONS.enabled,
+        size: options?.size ?? DEFAULT_TAP_SCROLL_CIRCLE_OPTIONS.size,
+        offsetX: options?.offsetX ?? DEFAULT_TAP_SCROLL_CIRCLE_OPTIONS.offsetX,
+        offsetY: options?.offsetY ?? DEFAULT_TAP_SCROLL_CIRCLE_OPTIONS.offsetY,
+        className: options?.className ?? DEFAULT_TAP_SCROLL_CIRCLE_OPTIONS.className,
+        maxVisualDistance: options?.maxVisualDistance ?? DEFAULT_TAP_SCROLL_CIRCLE_OPTIONS.maxVisualDistance,
+        maxSpeedMultiplier,
+        minSpeedMultiplier: Math.max(options?.minSpeedMultiplier ?? DEFAULT_TAP_SCROLL_CIRCLE_OPTIONS.minSpeedMultiplier, 0),
+        opacity: minmax(options?.opacity ?? DEFAULT_TAP_SCROLL_CIRCLE_OPTIONS.opacity, 0, 1),
+        renderVisual: options?.renderVisual ?? DEFAULT_TAP_SCROLL_CIRCLE_OPTIONS.renderVisual,
+        maxSpeedCurve: options?.maxSpeedCurve ?? DEFAULT_TAP_SCROLL_CIRCLE_OPTIONS.maxSpeedCurve,
+    }
+}
+
+/**
+ * Applies hover and drag visual feedback to the scrollbar thumb.
+ *
+ * スクロールバーつまみのホバーとドラッグ時の見た目を適用。
+ */
+const useThumbVisualFeedback = ({ isDragging, isThumbHovered, enableThumbDrag }: ThumbVisualFeedbackOptions): ScrollBarThumbState => {
+    return useMemo<ScrollBarThumbState>(() => {
+        if (!enableThumbDrag) {
+            return "disabled"
+        }
+        if (isDragging) {
+            return "dragging"
+        }
+        if (isThumbHovered) {
+            return "hover"
+        }
+        return "idle"
+    }, [enableThumbDrag, isDragging, isThumbHovered])
+}
+
+/**
+ * Provides handlers for scrollbar arrow auto-repeat interactions.
+ *
+ * スクロールバー矢印の自動リピート操作向けハンドラーを提供。
+ */
+const useArrowAutoRepeat = ({ canUseArrowButtons, enableArrowButtons, resetTapScroll, scrollByStep }: ArrowAutoRepeatOptions): ArrowAutoRepeatHandlers => {
+    const arrowHoldIntervalRef = useRef<number | null>(null)
+    const arrowHoldTimeoutRef = useRef<number | null>(null)
+    // 長押し中に張るグローバル解除リスナ (disabled 化やウィンドウ blur でボタンに pointerup が届かない保険)。
+    const globalReleaseRef = useRef<((event: Event) => void) | null>(null)
+
+    const clearArrowTimers = useCallback(() => {
+        if (arrowHoldIntervalRef.current !== null) {
+            window.clearInterval(arrowHoldIntervalRef.current)
+            arrowHoldIntervalRef.current = null
+        }
+        if (arrowHoldTimeoutRef.current !== null) {
+            window.clearTimeout(arrowHoldTimeoutRef.current)
+            arrowHoldTimeoutRef.current = null
+        }
+        if (globalReleaseRef.current !== null) {
+            window.removeEventListener("pointerup", globalReleaseRef.current)
+            window.removeEventListener("pointercancel", globalReleaseRef.current)
+            window.removeEventListener("blur", globalReleaseRef.current)
+            globalReleaseRef.current = null
+        }
+    }, [])
+
+    const handleArrowPointerUp = useCallback(() => {
+        clearArrowTimers()
+    }, [clearArrowTimers])
+
+    const handleArrowPointerDown = useCallback(
+        (direction: 1 | -1) => (event: React.PointerEvent<HTMLButtonElement>) => {
+            if (!canUseArrowButtons) {
+                return
+            }
+            if (event.cancelable) {
+                event.preventDefault()
+            }
+            event.stopPropagation()
+            resetTapScroll()
+            clearArrowTimers()
+            scrollByStep(direction)
+            arrowHoldTimeoutRef.current = window.setTimeout(() => {
+                arrowHoldIntervalRef.current = window.setInterval(() => {
+                    scrollByStep(direction)
+                }, ARROW_HOLD_INTERVAL)
+            }, ARROW_HOLD_DELAY)
+            // ボタンが disabled 化 / ウィンドウ blur で pointerup を取りこぼしてもリピートを確実に止める保険。
+            const release = () => clearArrowTimers()
+            globalReleaseRef.current = release
+            window.addEventListener("pointerup", release)
+            window.addEventListener("pointercancel", release)
+            window.addEventListener("blur", release)
+        },
+        [canUseArrowButtons, clearArrowTimers, resetTapScroll, scrollByStep],
+    )
+
+    const handleArrowKeyDown = useCallback(
+        (direction: 1 | -1) => (event: React.KeyboardEvent<HTMLButtonElement>) => {
+            if (!enableArrowButtons) {
+                return
+            }
+            if (event.key === "Enter" || event.key === " " || event.key === "Spacebar") {
+                event.preventDefault()
+                scrollByStep(direction)
+            }
+        },
+        [enableArrowButtons, scrollByStep],
+    )
+
+    // 矢印ボタンが操作不能 (canUseArrowButtons=false) になったら進行中のリピートを即停止する。
+    // disabled なボタンには pointerup/pointerleave が配送されないため、この保険が無いとタイマーが残留する。
+    useEffect(() => {
+        if (!canUseArrowButtons) {
+            clearArrowTimers()
+        }
+    }, [canUseArrowButtons, clearArrowTimers])
+
+    useEffect(() => {
+        return () => {
+            clearArrowTimers()
+        }
+    }, [clearArrowTimers])
+
+    return { handleArrowPointerDown, handleArrowPointerUp, handleArrowKeyDown }
+}
+
+/**
+ * Computes the auto-scroll speed multiplier based on item count.
+ *
+ * アイテム数に応じた自動スクロール速度倍率を算出。
+ */
+const computeAutoTapScrollMaxSpeedMultiplier = (itemCount?: number) => {
+    if (!itemCount || itemCount <= 0) {
+        return TAP_SCROLL_AUTO_SPEED_BASE_MULTIPLIER
+    }
+
+    const clampedCount = Math.max(1, itemCount)
+    const ordersOfMagnitude = Math.log10(clampedCount)
+    const multiplier = TAP_SCROLL_AUTO_SPEED_BASE_MULTIPLIER + ordersOfMagnitude * TAP_SCROLL_AUTO_SPEED_PER_ORDER
+    return minmax(multiplier, TAP_SCROLL_AUTO_SPEED_BASE_MULTIPLIER, TAP_SCROLL_AUTO_SPEED_MAX_MULTIPLIER)
+}
+
+/**
+ * A custom scrollbar component.
+ *
+ * カスタムスクロールバーコンポーネント。
+ */
+export const ScrollBar = ({
+    contentSize,
+    viewportSize,
+    scrollPosition,
+    onScroll,
+    enableThumbDrag = true,
+    enableTrackClick = true,
+    enableArrowButtons = true,
+    horizontal = false,
+    scrollBarWidth = 12,
+    className,
+    ariaControls,
+    tapScrollCircleOptions,
+    itemCount,
+    renderThumbOverlay,
+    visibleStartIndex,
+    visibleEndIndex,
+}: ScrollBarProps) => {
+    const [isDragging, setIsDragging] = useState(false)
+    const [isThumbHovered, setIsThumbHovered] = useState(false)
+    const [isTapActive, setIsTapActive] = useState(false)
+    const thumbRef = useRef<HTMLDivElement>(null)
+    const thumbDragStateRef = useRef<{ pointerId: number | null; startThumbPosition: number; startClientX: number; startClientY: number; scale: number; captureTarget: HTMLElement | null }>({
+        pointerId: null,
+        startThumbPosition: 0,
+        startClientX: 0,
+        startClientY: 0,
+        scale: 1,
+        captureTarget: null,
+    })
+    const trackDragStateRef = useRef<{ pointerId: number | null; startThumbPosition: number; startClientX: number; startClientY: number; scale: number }>({ pointerId: null, startThumbPosition: 0, startClientX: 0, startClientY: 0, scale: 1 })
+    const latestScrollPositionRef = useRef(scrollPosition)
+    const onScrollRef = useRef(onScroll)
+    const tapDragStateRef = useRef<TapScrollCircleDragState>(TAP_SCROLL_INITIAL_STATE)
+    const tapCircleHandleRef = useRef<TapScrollCircleHandle | null>(null)
+    const autoScrollFrameRef = useRef<number | null>(null)
+    const lastAutoScrollTimestampRef = useRef<number | null>(null)
+    // 親が位置を量子化 (行スナップ等) して返す場合でも、1フレームあたりのサブピクセル移動が
+    // 丸めで消えて自動スクロールが止まらないよう、未消化の要求量を持ち越すための残差アキュムレータ。
+    const autoScrollResidualRef = useRef(0)
+    // 直前の自動スクロール方向。方向転換時に逆向きの残差を持ち越さないための記録。
+    const autoScrollDirectionRef = useRef<0 | 1 | -1>(0)
+    const resolvedTapScrollOptions = useMemo<ResolvedTapScrollCircleOptions>(() => resolveTapScrollCircleOptions(tapScrollCircleOptions, itemCount), [itemCount, tapScrollCircleOptions])
+    const orientationConfig = useMemo(() => createOrientationConfig(horizontal), [horizontal])
+    const {
+        enabled: tapCircleEnabled,
+        size: tapCircleSize,
+        offsetX: tapCircleOffsetX,
+        offsetY: tapCircleOffsetY,
+        className: tapCircleClassName,
+        maxVisualDistance: tapCircleMaxDistance,
+        maxSpeedMultiplier: tapCircleMaxSpeedMultiplier,
+        minSpeedMultiplier: tapCircleMinSpeedMultiplier,
+        opacity: tapCircleOpacity,
+        renderVisual: tapCircleRenderVisual,
+        maxSpeedCurve: tapCircleMaxSpeedCurve,
+    } = resolvedTapScrollOptions
+    const latestMetricsRef = useRef({
+        viewportSize,
+        maxScrollPosition: Math.max(contentSize - viewportSize, 0),
+        scrollBarVisible: contentSize > viewportSize,
+        effectiveTapMaxDistance: Math.max(tapCircleMaxDistance, 1),
+        tapCircleMaxSpeedMultiplier,
+        tapCircleMinSpeedMultiplier,
+        tapCircleMaxSpeedCurve,
+        tapScrollCircleOptions,
+        effectiveTrackLength: 0,
+        onScroll,
+        scrollPosition,
+    })
+    const { mainSizeKey, crossSizeKey, positionKey, selectDelta, getPointerCoordinate, arrowLabels, arrowIcons, directionClass, orientation } = orientationConfig
+    const effectiveTapMaxDistance = Math.max(tapCircleMaxDistance, 1)
+    // 表示領域に対するコンテンツの比率
+    const scrollRatio = viewportSize / contentSize
+    const trackLength = Math.max(viewportSize - scrollBarWidth * 2, 0)
+    const rawThumbSize = scrollRatio * trackLength
+    const thumbSize = Math.min(Math.max(MIN_THUMB_SIZE, rawThumbSize || 0), trackLength || MIN_THUMB_SIZE)
+    // 最大スクロール位置
+    const maxScrollPosition = contentSize - viewportSize
+    const effectiveTrackLength = Math.max(trackLength - thumbSize, 0)
+    // scrollPosition が範囲外 (コンテンツ縮小直後の未クランプ 1 フレームや iOS バウンス値) でも
+    // サムがトラック外へはみ出さないよう、レンダー時に [0, effectiveTrackLength] へクランプする。
+    const thumbPosition = maxScrollPosition <= 0 || effectiveTrackLength <= 0 ? 0 : minmax((scrollPosition / maxScrollPosition) * effectiveTrackLength, 0, effectiveTrackLength)
+    const thumbCenter = thumbPosition + thumbSize / 2
+
+    // スクロールバーが表示されるかどうか
+    const scrollBarVisible = contentSize > viewportSize || isDragging
+    const canUseArrowButtons = scrollBarVisible && enableArrowButtons
+
+    useLayoutEffect(() => {
+        latestMetricsRef.current = {
+            viewportSize,
+            maxScrollPosition,
+            scrollBarVisible,
+            effectiveTapMaxDistance,
+            tapCircleMaxSpeedMultiplier,
+            tapCircleMinSpeedMultiplier,
+            tapCircleMaxSpeedCurve,
+            tapScrollCircleOptions,
+            effectiveTrackLength,
+            onScroll,
+            scrollPosition,
+        }
+    })
+
+    /**
+     * Synchronizes the latest scroll position to a ref.
+     *
+     * 最新のスクロール位置を Ref に同期します。
+     * 依存関係: [scrollPosition] - スクロール位置が変更されるたびに更新。
+     */
+    useLayoutEffect(() => {
+        latestScrollPositionRef.current = scrollPosition
+    }, [scrollPosition])
+
+    useLayoutEffect(() => {
+        onScrollRef.current = onScroll
+    }, [onScroll])
+
+    /**
+     * Resets thumb hover state when drag logic is disabled.
+     *
+     * つまみドラッグが無効化された際に、ホバー状態をリセットします。
+     * 依存関係: [enableThumbDrag] - ドラッグ設定が変更された時のみ実行。
+     */
+    useEffect(() => {
+        if (!enableThumbDrag) {
+            setIsThumbHovered(false)
+        }
+    }, [enableThumbDrag])
+
+    const thumbVisualState = useThumbVisualFeedback({ isDragging, isThumbHovered, enableThumbDrag })
+
+    const resolveScrollRequest = useCallback((next: number | ((prev: number) => number), previousOverride?: number) => {
+        const metrics = latestMetricsRef.current
+        const previous = previousOverride ?? latestScrollPositionRef.current
+        if (onScrollRef.current) {
+            const result = onScrollRef.current(next, previous)
+            if (typeof result === "number" && Number.isFinite(result)) {
+                latestScrollPositionRef.current = result
+                return result
+            }
+        }
+        const candidate = typeof next === "function" ? next(previous) : next
+        const maxPosition = Math.max(metrics.maxScrollPosition, 0)
+        const clamped = metrics.scrollBarVisible ? minmax(candidate, 0, maxPosition) : 0
+        latestScrollPositionRef.current = clamped
+        return clamped
+    }, [])
+
+    const applyScrollDelta = useCallback(
+        (delta: number) => {
+            const metrics = latestMetricsRef.current
+            const previousPosition = latestScrollPositionRef.current
+            if (!metrics.scrollBarVisible || metrics.maxScrollPosition <= 0) {
+                const nextPosition = resolveScrollRequest(0, previousPosition)
+                const actualDelta = nextPosition - previousPosition
+                return { nextPosition, actualDelta, reachedBoundary: true }
+            }
+
+            if (delta === 0) {
+                return { nextPosition: previousPosition, actualDelta: 0, reachedBoundary: false }
+            }
+
+            const updater = (prev: number) => minmax(prev + delta, 0, metrics.maxScrollPosition)
+            const nextPosition = resolveScrollRequest(updater, previousPosition)
+            const actualDelta = nextPosition - previousPosition
+            // actualDelta===0 単独では境界到達と同一視しない。位置を量子化して返す親では低速時に
+            // 丸めで actualDelta=0 になり得るが、それは境界ではなく「まだ動かせていない」状態。
+            // ただし「クランプ前の要求候補が端に達しているのに位置が変わらない」場合は境界とみなす。
+            // floor 量子化する親では到達可能最大が maxScrollPosition の手前で頭打ちになり、
+            // 実位置は端値ちょうどに届かないため、この補強が無いと境界判定が永久に偽のままになる。
+            const candidateAtMin = delta < 0 && previousPosition + delta <= 0
+            const candidateAtMax = delta > 0 && previousPosition + delta >= metrics.maxScrollPosition
+            const reachedBoundary = (delta < 0 && (nextPosition <= 0 || (candidateAtMin && actualDelta === 0))) || (delta > 0 && (nextPosition >= metrics.maxScrollPosition || (candidateAtMax && actualDelta === 0)))
+
+            return { nextPosition, actualDelta, reachedBoundary }
+        },
+        [resolveScrollRequest],
+    )
+
+    /**
+     * Applies a scroll delta through a residual accumulator so quantizing parents can still advance.
+     *
+     * 残差アキュムレータ経由でスクロール差分を適用し、量子化する親でも前進できるようにする処理。
+     *
+     * @param residualRef Accumulator ref holding the unconsumed scroll amount. / 未消化のスクロール量を保持するアキュムレータ ref。
+     * @param delta Requested scroll delta. / 要求するスクロール差分。
+     * @returns The result of applyScrollDelta. / applyScrollDelta の結果。
+     */
+    const applyScrollDeltaWithResidual = useCallback(
+        (residualRef: { current: number }, delta: number) => {
+            // 要求量を残差に足し込み、実際に消化された分だけ差し引く。量子化する親でも
+            // 残差が次の量子に達すれば前進でき、真の境界到達時は残差を破棄する。
+            residualRef.current += delta
+            // 残差の暴走防止: 全スクロール範囲を超える残差は意味を持たないため上限を設ける。
+            // 位置を独自クランプする親などで境界判定が成立しないケースでも無制限成長を防ぐ保険。
+            const residualCap = Math.max(latestMetricsRef.current.maxScrollPosition, 0)
+            if (residualCap > 0) {
+                residualRef.current = minmax(residualRef.current, -residualCap, residualCap)
+            }
+            const result = applyScrollDelta(residualRef.current)
+            residualRef.current -= result.actualDelta
+            if (result.reachedBoundary) {
+                residualRef.current = 0
+            }
+            return result
+        },
+        [applyScrollDelta],
+    )
+
+    /**
+     * Stops the tap circle auto-scroll animation.
+     *
+     * タップサークルによる自動スクロールを停止。
+     */
+    const stopAutoScroll = useCallback(() => {
+        if (autoScrollFrameRef.current !== null) {
+            window.cancelAnimationFrame(autoScrollFrameRef.current)
+            autoScrollFrameRef.current = null
+        }
+        lastAutoScrollTimestampRef.current = null
+        autoScrollResidualRef.current = 0
+        autoScrollDirectionRef.current = 0
+    }, [])
+
+    /**
+     * Resets tap circle state and related motion.
+     *
+     * タップサークルの状態と動作を初期化。
+     */
+    const resetTapScroll = useCallback(() => {
+        tapDragStateRef.current = { ...TAP_SCROLL_INITIAL_STATE }
+        setIsTapActive(false)
+        tapCircleHandleRef.current?.reset()
+        stopAutoScroll()
+    }, [stopAutoScroll])
+
+    /**
+     * Advances tap circle auto-scroll by animation frame.
+     * Calculates speed based on pull distance, viewport size, and optional easing curves.
+     *
+     * タップサークルの自動スクロールをフレームごとに進行させます。
+     * 引っ張り距離、ビューポートサイズ、およびオプションのイージングカーブに基づいてスクロール速度を計算します。
+     *
+     * @param timestamp Current high-resolution timestamp / 現在の高精度タイムスタンプ
+     */
+    const stepAutoScroll = useCallback(
+        (timestamp: number) => {
+            const state = tapDragStateRef.current
+            const metrics = latestMetricsRef.current
+            if (!state.active || state.direction === 0) {
+                stopAutoScroll()
+                return
+            }
+            if (!metrics.scrollBarVisible || metrics.maxScrollPosition <= 0) {
+                stopAutoScroll()
+                return
+            }
+
+            const lastTimestamp = lastAutoScrollTimestampRef.current ?? timestamp
+            const deltaSecondsRaw = Math.max((timestamp - lastTimestamp) / 1000, 0)
+            const deltaSeconds = Math.min(deltaSecondsRaw, TAP_SCROLL_MAX_FRAME_DELTA_SECONDS)
+            lastAutoScrollTimestampRef.current = timestamp
+
+            if (deltaSeconds <= 0) {
+                autoScrollFrameRef.current = window.requestAnimationFrame(stepAutoScroll)
+                return
+            }
+
+            // Calculate normalized distance (0.0 to 1.0)
+            // 正規化された距離を計算 (0.0 から 1.0)
+            const normalized = Math.min(state.distance, metrics.effectiveTapMaxDistance) / metrics.effectiveTapMaxDistance
+            // Apply base non-linear easing
+            // 基準の非線形イージングを適用
+            const eased = normalized ** 1.1
+            const hasCustomMaxSpeedMultiplier = typeof metrics.tapScrollCircleOptions?.maxSpeedMultiplier === "number"
+            const minSpeed = Math.max(metrics.viewportSize * metrics.tapCircleMinSpeedMultiplier, 40)
+            const maxSpeedFloor = hasCustomMaxSpeedMultiplier ? minSpeed : 1200
+            const linearMaxSpeed = Math.max(metrics.viewportSize * metrics.tapCircleMaxSpeedMultiplier, maxSpeedFloor)
+
+            let cappedMaxSpeed = linearMaxSpeed
+            const curve = metrics.tapCircleMaxSpeedCurve
+
+            // Apply exponential curve scaling if configured
+            // 設定されている場合、指数関数曲線スケーリングを適用します
+            if (curve) {
+                const steepness = Math.max(curve.exponentialSteepness, 0)
+                const scale = Math.max(curve.exponentialScale ?? metrics.tapCircleMaxSpeedMultiplier, 0)
+                const expNumerator = steepness === 0 ? normalized : Math.expm1(steepness * normalized)
+                const expDenominator = steepness === 0 ? 1 : Math.expm1(steepness) || 1
+                const exponentialRatio = expDenominator === 0 ? normalized : Math.min(Math.max(expNumerator / expDenominator, 0), 1)
+                const exponentialMaxSpeed = metrics.viewportSize * scale * exponentialRatio
+                cappedMaxSpeed = Math.min(cappedMaxSpeed, Math.max(exponentialMaxSpeed, minSpeed))
+            }
+
+            const maxSpeed = Math.max(cappedMaxSpeed, minSpeed)
+            const easedOffset = Math.max(curve?.easedOffset ?? 0, 0)
+            const effectiveEased = Math.min(1, eased + easedOffset)
+            const speed = minSpeed + (maxSpeed - minSpeed) * effectiveEased
+
+            // 方向が転換したら逆向きの残差を破棄する。持ち越すと逆向き残差を燃焼し切るまで
+            // スクロール反転が固着する (タップサークルはヒステリシス幅を超える 1 イベントで +1→-1 に反転し得る)。
+            if (autoScrollDirectionRef.current !== state.direction) {
+                autoScrollDirectionRef.current = state.direction
+                autoScrollResidualRef.current = 0
+            }
+
+            // 残差アキュムレータ経由で適用し、量子化する親でも前進できるようにする。
+            // 真の境界到達時のみループを止める。
+            const { reachedBoundary } = applyScrollDeltaWithResidual(autoScrollResidualRef, state.direction * speed * deltaSeconds)
+
+            if (reachedBoundary) {
+                stopAutoScroll()
+                return
+            }
+
+            autoScrollFrameRef.current = window.requestAnimationFrame(stepAutoScroll)
+        },
+        [applyScrollDeltaWithResidual, stopAutoScroll],
+    )
+
+    /**
+     * Starts tap circle auto-scroll loop.
+     *
+     * タップサークルによる自動スクロールを開始。
+     */
+    const startAutoScroll = useCallback(() => {
+        if (autoScrollFrameRef.current === null) {
+            lastAutoScrollTimestampRef.current = null
+            autoScrollResidualRef.current = 0
+            autoScrollFrameRef.current = window.requestAnimationFrame(stepAutoScroll)
+        }
+    }, [stepAutoScroll])
+
+    /**
+     * Cleanup auto-scroll on unmount.
+     *
+     * アンマウント時に自動スクロールをクリーンアップします。
+     * 依存関係: [stopAutoScroll]
+     */
+    useEffect(() => {
+        return () => {
+            stopAutoScroll()
+        }
+    }, [stopAutoScroll])
+
+    /**
+     * Handles tap circle drag state changes.
+     *
+     * タップサークルのドラッグ状態変化を処理。
+     */
+    const handleTapCircleDragChange = useCallback(
+        (state: TapScrollCircleDragState) => {
+            tapDragStateRef.current = state
+            setIsTapActive(state.active)
+            if (state.active && state.direction !== 0) {
+                startAutoScroll()
+            } else {
+                stopAutoScroll()
+            }
+        },
+        [startAutoScroll, stopAutoScroll],
+    )
+
+    /**
+     * Resets tap scroll when disabled configuration changes.
+     *
+     * 設定で無効化された際にタップスクロールをリセットします。
+     * 依存関係: [resetTapScroll, tapCircleEnabled]
+     */
+    useEffect(() => {
+        if (!tapCircleEnabled) {
+            resetTapScroll()
+        }
+    }, [resetTapScroll, tapCircleEnabled])
+
+    /**
+     * Subscribes to custom cancel events for tap gestures.
+     * Often used to stop scrolling when interacting with other UI elements.
+     *
+     * タップジェスチャーのカスタムキャンセルイベントを購読します。
+     * 他の UI 要素とのインタラクション時にスクロールを停止するためによく使用されます。
+     * 依存関係: [ariaControls, resetTapScroll]
+     */
+    useEffect(() => {
+        const handleTapScrollCancel = (event: Event) => {
+            const customEvent = event as CustomEvent<TapScrollCancelEventDetail>
+            const targetPaneId = customEvent.detail?.paneId
+            if (targetPaneId && ariaControls && targetPaneId !== ariaControls) {
+                return
+            }
+            resetTapScroll()
+        }
+
+        window.addEventListener(TAP_SCROLL_CANCEL_EVENT, handleTapScrollCancel as EventListener)
+        return () => {
+            window.removeEventListener(TAP_SCROLL_CANCEL_EVENT, handleTapScrollCancel as EventListener)
+        }
+    }, [ariaControls, resetTapScroll])
+
+    /**
+     * Global pointer listener to cancel tap scroll on outside clicks.
+     *
+     * 外部クリック時にタップスクロールをキャンセルするためのグローバルポインタリステナ。
+     * 依存関係: [resetTapScroll, tapCircleEnabled]
+     */
+    useEffect(() => {
+        if (!tapCircleEnabled) {
+            return
+        }
+        const handlePointerDown = (event: PointerEvent) => {
+            if (!tapDragStateRef.current.active) {
+                return
+            }
+            // ドラッグ中のポインターと同じポインターによるイベントは無視する
+            // (通常はキャプチャされているためここには来ないはずだが、念のため)
+            if (tapDragStateRef.current.pointerId === event.pointerId) {
+                return
+            }
+
+            const targetNode = event.target
+            if (!(targetNode instanceof Node)) {
+                resetTapScroll()
+                return
+            }
+            const element = tapCircleHandleRef.current?.getElement()
+            if (element?.contains(targetNode)) {
+                return
+            }
+            resetTapScroll()
+        }
+        document.addEventListener("pointerdown", handlePointerDown, true)
+        return () => {
+            document.removeEventListener("pointerdown", handlePointerDown, true)
+        }
+    }, [resetTapScroll, tapCircleEnabled])
+
+    /**
+     * Translates the thumb position to a scroll position.
+     *
+     * つまみの位置をスクロール位置に変換。
+     *
+     * @param thumbPositionValue The position of the thumb. / つまみの位置。
+     * @returns The scroll position. / スクロール位置。
+     */
+    const translateToScrollPosition = (thumbPositionValue: number) => {
+        if (!scrollBarVisible || effectiveTrackLength <= 0 || maxScrollPosition <= 0) {
+            return 0
+        }
+        const clampedThumbPosition = minmax(thumbPositionValue, 0, effectiveTrackLength)
+        return minmax((clampedThumbPosition / effectiveTrackLength) * maxScrollPosition, 0, maxScrollPosition)
+    }
+
+    /**
+     * Calculates the scroll position based on thumb position using latest metrics.
+     *
+     * 最新のメトリクスを使用して、つまみの位置に基づきスクロール位置を計算します。
+     *
+     * @param thumbPos Finger drag position relative to start. / 開始位置に関連する指のドラッグ位置。
+     */
+    const calculateScrollPositionFromThumb = useCallback((thumbPos: number) => {
+        const { scrollBarVisible: _visible, effectiveTrackLength: trackLen, maxScrollPosition: maxScroll } = latestMetricsRef.current
+        Logger.debug("[ScrollBar] calculateScrollPositionFromThumb", () => ({ thumbPos, trackLen, maxScroll }))
+        if (trackLen <= 0 || maxScroll <= 0) {
+            return null
+        }
+        const clamped = minmax(thumbPos, 0, trackLen)
+        return minmax((clamped / trackLen) * maxScroll, 0, maxScroll)
+    }, [])
+
+    /**
+     * Computes the main-axis CSS transform scale of an element (visual px / layout px).
+     *
+     * 要素の主軸方向 CSS transform スケール (視覚px / レイアウトpx) を算出。
+     * 祖先に transform: scale(...) があると client 座標 (視覚px) がレイアウトpx とズレるため、
+     * その比率でドラッグ量・クリック座標を補正する。分母には整数丸めされる offsetWidth/offsetHeight
+     * ではなく、transform の影響を受けず小数精度を持つ getComputedStyle のレイアウト寸法
+     * (content + padding + border) を優先して使い、transform なしなら厳密に 1 を返す。
+     * 取得不能時 (jsdom 等) は offset 寸法へフォールバックし、それも 0 なら 1 を返す。
+     */
+    const getMainAxisScale = useCallback(
+        (element: HTMLElement) => {
+            const rect = element.getBoundingClientRect()
+            const visualSize = horizontal ? rect.width : rect.height
+            // computed style の値 (px 文字列) を数値化する。解釈不能なら 0 とみなす。
+            const parseSize = (value: string) => {
+                const parsed = Number.parseFloat(value)
+                return Number.isFinite(parsed) ? parsed : 0
+            }
+            const computed = window.getComputedStyle(element)
+            const contentSize = parseSize(horizontal ? computed.width : computed.height)
+            // rect (border-box) と同系になるよう content + padding + border を合成する。
+            const computedLayoutSize =
+                contentSize > 0
+                    ? contentSize +
+                      parseSize(horizontal ? computed.paddingLeft : computed.paddingTop) +
+                      parseSize(horizontal ? computed.paddingRight : computed.paddingBottom) +
+                      parseSize(horizontal ? computed.borderLeftWidth : computed.borderTopWidth) +
+                      parseSize(horizontal ? computed.borderRightWidth : computed.borderBottomWidth)
+                    : 0
+            // computed が取れない環境 (jsdom 等) では従来の offset 寸法へフォールバックする。
+            const layoutSize = computedLayoutSize > 0 ? computedLayoutSize : horizontal ? element.offsetWidth : element.offsetHeight
+            if (layoutSize <= 0 || visualSize <= 0) {
+                return 1
+            }
+            return visualSize / layoutSize
+        },
+        [horizontal],
+    )
+
+    /**
+     * Pointer move handler for thumb dragging.
+     * Calculates new scroll position based on drag delta.
+     *
+     * つまみドラッグ用のポインタ移動ハンドラー。
+     * ドラッグの差分に基づいて新しいスクロール位置を計算します。
+     */
+    const handleThumbPointerMove = useCallback(
+        (event: PointerEvent) => {
+            const state = thumbDragStateRef.current
+            if (state.pointerId !== event.pointerId) {
+                return
+            }
+
+            const deltaX = event.clientX - state.startClientX
+            const deltaY = event.clientY - state.startClientY
+            // client 座標差分 (視覚px) を transform scale で割ってレイアウトpx に戻す。
+            const delta = selectDelta(deltaX, deltaY) / (state.scale || 1)
+            Logger.debug("[ScrollBar] handleThumbPointerMove", () => ({
+                delta,
+                startThumbPosition: state.startThumbPosition,
+                clientY: event.clientY,
+                startClientY: state.startClientY,
+                metrics: latestMetricsRef.current,
+            }))
+            const nextPosition = calculateScrollPositionFromThumb(state.startThumbPosition + delta)
+
+            if (nextPosition !== null) {
+                resolveScrollRequest(nextPosition)
+            }
+
+            if (event.cancelable) {
+                event.preventDefault()
+            }
+        },
+        [selectDelta, calculateScrollPositionFromThumb, resolveScrollRequest],
+    )
+
+    /**
+     * Pointer up handler for thumb dragging.
+     * Cleans up drag state and visual feedback.
+     *
+     * つまみドラッグ用のポインタ上げハンドラー。
+     * ドラッグ状態と視覚的フィードバックをクリーンアップします。
+     */
+    const handleThumbPointerUp = useCallback(
+        (event: PointerEvent) => {
+            const state = thumbDragStateRef.current
+            if (state.pointerId !== event.pointerId) {
+                return
+            }
+
+            document.removeEventListener("pointermove", handleThumbPointerMove)
+            document.removeEventListener("pointerup", handleThumbPointerUp)
+            document.removeEventListener("pointercancel", handleThumbPointerUp)
+
+            const captureTarget = state.captureTarget
+            if (captureTarget?.hasPointerCapture?.(event.pointerId)) {
+                captureTarget.releasePointerCapture(event.pointerId)
+            }
+
+            thumbDragStateRef.current = { pointerId: null, startThumbPosition: 0, startClientX: 0, startClientY: 0, scale: 1, captureTarget: null }
+
+            setIsDragging(false)
+            if (thumbRef.current) {
+                const rect = thumbRef.current.getBoundingClientRect()
+                const isOver = event.clientX >= rect.left && event.clientX <= rect.right && event.clientY >= rect.top && event.clientY <= rect.bottom
+                if (!isOver) {
+                    setIsThumbHovered(false)
+                }
+            } else {
+                setIsThumbHovered(false)
+            }
+        },
+        [handleThumbPointerMove],
+    )
+
+    /**
+     * Removes any lingering thumb-drag document listeners on unmount.
+     *
+     * アンマウント時にサムドラッグ用の document リスナを確実に解除します。
+     * ドラッグ中にアンマウントされても pointermove/pointerup/pointercancel が残留せず、
+     * 破棄済みコンポーネントの onScroll が呼ばれ続けるのを防ぎます。
+     * 依存関係: [handleThumbPointerMove, handleThumbPointerUp]
+     */
+    useEffect(() => {
+        return () => {
+            document.removeEventListener("pointermove", handleThumbPointerMove)
+            document.removeEventListener("pointerup", handleThumbPointerUp)
+            document.removeEventListener("pointercancel", handleThumbPointerUp)
+        }
+    }, [handleThumbPointerMove, handleThumbPointerUp])
+
+    // 矢印ボタン/キーボードのステップ操作用の残差アキュムレータ。位置を量子化 (行スナップ等) して
+    // 返す親では 1 ステップが量子未満だと丸めで消えるため、複数ステップ分を蓄積して前進させる。
+    const arrowScrollResidualRef = useRef(0)
+    // 直前のステップ方向。方向転換時に逆向きの残差を持ち越さないための記録。
+    const arrowScrollDirectionRef = useRef<0 | 1 | -1>(0)
+
+    /**
+     * Moves scroll position by a fixed step using arrow controls.
+     * Accumulates residual amounts so quantizing parents still advance across repeated steps.
+     *
+     * 矢印操作で一定ステップ分スクロールする処理。量子化する親でも連続ステップで前進できるよう残差を蓄積。
+     * 長押しリピートの setInterval クロージャが pointerdown 時点の関数を掴み続けても
+     * 最新のビューポートに基づくステップ量を使えるよう、参照は props ではなく latestMetricsRef
+     * 経由とし、関数自体も安定した useCallback にする。
+     */
+    const scrollByStep = useCallback(
+        (direction: 1 | -1) => {
+            const step = Math.max(Math.round(latestMetricsRef.current.viewportSize / ARROW_STEP_DIVISOR), MIN_ARROW_STEP)
+            // 方向が変わったら逆向きの残差を破棄する。
+            if (arrowScrollDirectionRef.current !== direction) {
+                arrowScrollDirectionRef.current = direction
+                arrowScrollResidualRef.current = 0
+            }
+            applyScrollDeltaWithResidual(arrowScrollResidualRef, direction * step)
+        },
+        [applyScrollDeltaWithResidual],
+    )
+
+    const { handleArrowPointerDown, handleArrowPointerUp, handleArrowKeyDown } = useArrowAutoRepeat({
+        canUseArrowButtons,
+        enableArrowButtons,
+        resetTapScroll,
+        scrollByStep,
+    })
+
+    // スクロールバーのつまみをポインタイベントで処理
+    /**
+     * Handles pointer down interaction on the thumb.
+     *
+     * つまみ押下時のインタラクションを処理。
+     */
+    const handlePointerDownOnThumb = (event: React.PointerEvent<HTMLDivElement>) => {
+        if (!scrollBarVisible) {
+            return
+        }
+        if (!enableThumbDrag) {
+            event.preventDefault()
+            event.stopPropagation()
+            return
+        }
+        if ((event.pointerType === "mouse" && event.button !== 0) || event.ctrlKey) {
+            return
+        }
+
+        resetTapScroll()
+
+        // ポインターキャプチャを取得し、iframe/ウィンドウ外での pointerup 取りこぼしによる
+        // ドラッグ固着を防ぐ。キャプチャ後もイベントは document までバブリングするため既存の
+        // document リスナはそのまま機能する。取得不能なポインターでは例外を握り潰す。
+        const element = event.currentTarget
+        const scale = getMainAxisScale(element)
+        let captureTarget: HTMLElement | null = null
+        if (element.setPointerCapture) {
+            try {
+                element.setPointerCapture(event.pointerId)
+                captureTarget = element
+            } catch {
+                captureTarget = null
+            }
+        }
+
+        thumbDragStateRef.current = {
+            pointerId: event.pointerId,
+            startThumbPosition: thumbPosition,
+            startClientX: event.clientX,
+            startClientY: event.clientY,
+            scale,
+            captureTarget,
+        }
+
+        document.addEventListener("pointermove", handleThumbPointerMove)
+        document.addEventListener("pointerup", handleThumbPointerUp)
+        document.addEventListener("pointercancel", handleThumbPointerUp)
+
+        setIsDragging(true)
+        setIsThumbHovered(true)
+
+        event.preventDefault()
+        event.stopPropagation()
+    }
+
+    /**
+     * Handles pointer down interaction on the track.
+     *
+     * トラック押下時のインタラクションを処理。
+     */
+    const handlePointerDownOnTrack = (event: React.PointerEvent<HTMLDivElement>) => {
+        if (!scrollBarVisible) {
+            return
+        }
+        if (!enableTrackClick) {
+            event.preventDefault()
+            event.stopPropagation()
+            return
+        }
+        if ((event.pointerType === "mouse" && event.button !== 0) || event.ctrlKey) {
+            return
+        }
+
+        const element = event.currentTarget
+        const rect = element.getBoundingClientRect()
+        const pointerCoordinate = getPointerCoordinate(event)
+        // getBoundingClientRect は視覚px。transform scale で割ってレイアウトpx (thumbSize/trackLength と同系) に揃える。
+        const scale = getMainAxisScale(element)
+        const clickPositionInTrack = (pointerCoordinate - (horizontal ? rect.left : rect.top)) / scale
+
+        resetTapScroll()
+
+        const startThumbPosition = clickPositionInTrack - thumbSize / 2
+        const initialPosition = translateToScrollPosition(startThumbPosition)
+        resolveScrollRequest(initialPosition)
+
+        // サム側と同様、取得不能なポインター (非アクティブ pointerId 等) では例外を握り潰し、
+        // キャプチャなしのフォールバックでドラッグ状態の設定と preventDefault を継続する。
+        if (element.setPointerCapture) {
+            try {
+                element.setPointerCapture(event.pointerId)
+            } catch {
+                // キャプチャ取得失敗時はキャプチャなしで続行 (要素上の pointermove では追従する)。
+            }
+        }
+
+        trackDragStateRef.current = {
+            pointerId: event.pointerId,
+            startThumbPosition,
+            startClientX: event.clientX,
+            startClientY: event.clientY,
+            scale,
+        }
+
+        event.preventDefault()
+        event.stopPropagation()
+    }
+
+    /**
+     * Resets the track drag state to its idle values.
+     *
+     * トラックドラッグ状態を待機値へリセットする処理。
+     */
+    const resetTrackDragState = () => {
+        trackDragStateRef.current = { pointerId: null, startThumbPosition: 0, startClientX: 0, startClientY: 0, scale: 1 }
+    }
+
+    /**
+     * Handles pointer move interaction on the track.
+     *
+     * トラックドラッグ中の移動を処理。
+     */
+    const handlePointerMoveOnTrack = (event: React.PointerEvent<HTMLDivElement>) => {
+        const state = trackDragStateRef.current
+        if (state.pointerId !== event.pointerId) {
+            return
+        }
+
+        // キャプチャ取得失敗時などに pointerup を取りこぼした stale ドラッグの自己回復。
+        // マウスはボタン非押下ならドラッグではないため、状態を破棄してホバー移動での誤スクロールを防ぐ。
+        if (event.pointerType === "mouse" && event.buttons === 0) {
+            resetTrackDragState()
+            return
+        }
+
+        const deltaX = event.clientX - state.startClientX
+        const deltaY = event.clientY - state.startClientY
+        // client 座標差分 (視覚px) を transform scale で割ってレイアウトpx に戻す。
+        const delta = selectDelta(deltaX, deltaY) / (state.scale || 1)
+        const nextPosition = translateToScrollPosition(state.startThumbPosition + delta)
+        resolveScrollRequest(nextPosition)
+
+        if (event.cancelable) {
+            event.preventDefault()
+        }
+    }
+
+    /**
+     * Handles pointer up interaction on the track.
+     *
+     * トラックドラッグ終了時の処理。
+     */
+    const handlePointerUpOnTrack = (event: React.PointerEvent<HTMLDivElement>) => {
+        if (trackDragStateRef.current.pointerId !== event.pointerId) {
+            return
+        }
+
+        // hasPointerCapture は API 非実装環境 (jsdom 等) を考慮してサム側と同様に存在ガード付きで呼ぶ。
+        const element = event.currentTarget
+        if (element.hasPointerCapture?.(event.pointerId)) {
+            element.releasePointerCapture(event.pointerId)
+        }
+
+        resetTrackDragState()
+
+        event.preventDefault()
+        event.stopPropagation()
+    }
+
+    /**
+     * Handles pointer cancel interaction on the track.
+     *
+     * トラックドラッグキャンセル時の処理。
+     */
+    const handlePointerCancelOnTrack = (event: React.PointerEvent<HTMLDivElement>) => {
+        if (trackDragStateRef.current.pointerId !== event.pointerId) {
+            return
+        }
+
+        // hasPointerCapture は API 非実装環境 (jsdom 等) を考慮してサム側と同様に存在ガード付きで呼ぶ。
+        const element = event.currentTarget
+        if (element.hasPointerCapture?.(event.pointerId)) {
+            element.releasePointerCapture(event.pointerId)
+        }
+
+        resetTrackDragState()
+    }
+
+    /**
+     * Handles loss of pointer capture during a track drag.
+     *
+     * トラックドラッグ中のポインターキャプチャ喪失を処理。
+     * ブラウザ都合 (要素削除・OS 割り込み等) でキャプチャを失った場合に
+     * pointerup を待たずにドラッグ状態を破棄し、stale な pointerId の残留を防ぐ。
+     */
+    const handleLostPointerCaptureOnTrack = (event: React.PointerEvent<HTMLDivElement>) => {
+        if (trackDragStateRef.current.pointerId !== event.pointerId) {
+            return
+        }
+
+        resetTrackDragState()
+    }
+
+    const tapCircleOpacityValue = useMemo(() => {
+        const baseOpacity = isTapActive ? 1 : 0.8
+        return minmax(baseOpacity * tapCircleOpacity, 0, 1)
+    }, [isTapActive, tapCircleOpacity])
+
+    const tapCircleStyle = useMemo<CSSProperties>(() => {
+        const diameter = tapCircleSize
+        const baseTop = `calc(50% - ${diameter / 2}px + ${tapCircleOffsetY}px)`
+        return {
+            left: tapCircleOffsetX,
+            top: baseTop,
+        }
+    }, [tapCircleOffsetX, tapCircleOffsetY, tapCircleSize])
+
+    /**
+     * Renders an arrow button for scrollbar controls.
+     * The buttons stay in the tab order (tabIndex=0) so keyboard users can reach
+     * the Enter/Space handlers, which are the only keyboard scrolling entry point.
+     *
+     * スクロールバー制御用矢印ボタンを描画。キーボードで Enter/Space ハンドラへ
+     * 到達できるよう tabIndex=0 でタブ順序に残す。
+     */
+    const renderArrowButton = (direction: 1 | -1, label: string, icon: string, key: string) => (
+        <button
+            key={key}
+            type="button"
+            tabIndex={0}
+            className="aqvs-scrollbar-arrow-button"
+            style={{
+                [mainSizeKey]: scrollBarWidth,
+                [crossSizeKey]: scrollBarWidth,
+            }}
+            aria-label={label}
+            onPointerDown={handleArrowPointerDown(direction)}
+            onPointerUp={handleArrowPointerUp}
+            onPointerLeave={handleArrowPointerUp}
+            onPointerCancel={handleArrowPointerUp}
+            onKeyDown={handleArrowKeyDown(direction)}
+            aria-disabled={!enableArrowButtons}
+            disabled={!canUseArrowButtons}>
+            <span aria-hidden="true">{icon}</span>
+        </button>
+    )
+
+    const overlayProps: ScrollBarThumbOverlayRenderProps | null =
+        renderThumbOverlay && scrollBarVisible
+            ? {
+                  orientation,
+                  scrollPosition,
+                  maxScrollPosition,
+                  contentSize,
+                  viewportSize,
+                  thumbSize,
+                  thumbPosition,
+                  thumbCenter,
+                  trackSize: trackLength,
+                  isDragging,
+                  isTapScrollActive: isTapActive,
+                  visibleStartIndex,
+                  visibleEndIndex,
+              }
+            : null
+
+    return (
+        <div
+            className={twMerge("aqvs-scrollbar", directionClass, !scrollBarVisible && "pointer-events-none opacity-0", className)}
+            style={{
+                [mainSizeKey]: viewportSize,
+                [crossSizeKey]: scrollBarWidth,
+            }}
+            role="scrollbar"
+            tabIndex={-1}
+            aria-controls={ariaControls}
+            aria-valuenow={scrollPosition}
+            aria-valuemin={0}
+            aria-valuemax={maxScrollPosition}
+            aria-orientation={horizontal ? "horizontal" : "vertical"}>
+            {!horizontal && scrollBarVisible && tapCircleEnabled && (
+                <TapScrollCircle
+                    key="tap-circle"
+                    ref={tapCircleHandleRef}
+                    className={twMerge("aqvs-scrollbar-tap-circle-wrapper", tapCircleClassName)}
+                    size={tapCircleSize}
+                    maxVisualDistance={effectiveTapMaxDistance}
+                    style={tapCircleStyle}
+                    opacity={tapCircleOpacityValue}
+                    renderVisual={tapCircleRenderVisual}
+                    onDragChange={handleTapCircleDragChange}
+                />
+            )}
+            {renderArrowButton(-1, arrowLabels[0], arrowIcons[0], "arrow-start")}
+            <div
+                key="track"
+                className="aqvs-scrollbar-track"
+                style={{
+                    borderRadius: scrollBarWidth / 2,
+                }}
+                onPointerDown={handlePointerDownOnTrack}
+                onPointerMove={handlePointerMoveOnTrack}
+                onPointerUp={handlePointerUpOnTrack}
+                onPointerCancel={handlePointerCancelOnTrack}
+                onLostPointerCapture={handleLostPointerCaptureOnTrack}
+                aria-disabled={!enableTrackClick}>
+                {overlayProps && (
+                    <div key="overlay" className="aqvs-scrollbar-overlay" aria-hidden>
+                        {renderThumbOverlay?.(overlayProps)}
+                    </div>
+                )}
+                {/* コンテンツがビューポートより大きい場合、またはドラッグ中の場合にのみつまみを表示 */}
+                {/* DOMの再生成を防ぐため、常にレンダリングしてスタイルで表示制御を行う */}
+                <div
+                    key="thumb-wrapper"
+                    className={twMerge("aqvs-scrollbar-thumb-wrapper", !(scrollBarVisible || isDragging) && "pointer-events-none opacity-0")}
+                    style={{
+                        [mainSizeKey]: thumbSize,
+                        [positionKey]: thumbPosition,
+                        ...(horizontal ? { top: 0, bottom: 0 } : { left: 0, right: 0 }),
+                    }}
+                    onPointerDown={handlePointerDownOnThumb}
+                    role="slider"
+                    aria-orientation={horizontal ? "horizontal" : "vertical"}
+                    aria-valuenow={scrollPosition}
+                    aria-valuemin={0}
+                    aria-valuemax={maxScrollPosition}
+                    aria-disabled={!enableThumbDrag}
+                    tabIndex={-1}>
+                    {/* スクロールバーのつまみ（可視部分） */}
+                    {/* biome-ignore lint/a11y/noStaticElementInteractions: スクロールバーのつまみは必要なインタラクションです */}
+                    <div
+                        key="thumb"
+                        ref={thumbRef}
+                        className={twMerge("aqvs-scrollbar-thumb", horizontal ? "aqvs-scrollbar-thumb-horizontal" : "aqvs-scrollbar-thumb-vertical")}
+                        data-thumb-state={thumbVisualState}
+                        style={{
+                            borderRadius: scrollBarWidth - 1,
+                            cursor: enableThumbDrag ? "pointer" : "default",
+                        }}
+                        onMouseEnter={() => {
+                            if (enableThumbDrag) {
+                                setIsThumbHovered(true)
+                            }
+                        }}
+                        onMouseLeave={() => {
+                            if (enableThumbDrag) {
+                                setIsThumbHovered(false)
+                            }
+                        }}
+                    />
+                </div>
+            </div>
+            {renderArrowButton(1, arrowLabels[1], arrowIcons[1], "arrow-end")}
+        </div>
+    )
+}