@aiquants/virtualscroll 1.20.0 → 1.22.0

package/src/ScrollPane.tsx

@@ -53,6 +53,22 @@ export type ScrollPaneProps = {
     enableArrowButtons?: boolean
     /** Whether dragging the content area scrolls the pane. / コンテンツ領域のドラッグでスクロールさせるかどうか。 */
     enablePointerDrag?: boolean
+    /**
+     * Pointer types allowed to drag-scroll the content area.
+     * コンテンツ領域のドラッグスクロールを許可するポインタ種別。
+     *
+     * 既定は全種別 (`["mouse", "pen", "touch"]`)。
+     *
+     * ❗ **`enablePointerDrag` を丸ごと切ってはならない。** このペインはコンテンツを transform で
+     * 動かしておりネイティブのスクロール領域を持たない (`.aqvs-scroll-pane-content` は
+     * `overflow: hidden`)。ドラッグを無効にするとタッチ端末からスクロール手段が消える。
+     * マウスドラッグだけが困る (テキスト選択やクリック判定と競合する) 場合は、
+     * ここを `["pen", "touch"]` にして**入力種別ごとに**切ること。
+     *
+     * `touch-action: none` は `"touch"` が含まれるときだけ付与する。マウス専用に絞った場合に
+     * タッチのパンまで奪うと、スクロール手段が無いのに操作も奪う最悪の状態になるため。
+     */
+    pointerDragInputs?: readonly ("mouse" | "pen" | "touch")[]
     /** Optional renderer for thumb overlays. / サム付近に表示するオーバーレイのレンダラー。 */
     renderThumbOverlay?: (props: ScrollBarThumbOverlayRenderProps) => React.ReactNode
     /** Multiplier applied to wheel delta for faster or slower scrolling. / スクロール速度を調整するためのホイールデルタの倍率。 */
@@ -93,6 +109,26 @@ export type ScrollPaneInertiaOptions = {
 
 type ResolvedScrollPaneInertiaOptions = Required<ScrollPaneInertiaOptions>
 
+/** ドラッグスクロールを許可する既定のポインタ種別 (全種別)。 */
+const DEFAULT_POINTER_DRAG_INPUTS: readonly ("mouse" | "pen" | "touch")[] = ["mouse", "pen", "touch"]
+
+/**
+ * Reports whether a pointer event may start or continue a content drag.
+ * ポインタイベントがコンテンツドラッグを開始・継続してよいかを判定する処理。
+ *
+ * ❗ **未知の種別は拒否しない。** `PointerEvent.pointerType` は仕様上任意の文字列を取り得
+ * (空文字や合成イベントもある)、拒否すると**ネイティブのスクロール領域を持たないペインが
+ * 完全に操作不能**になる。既知の 3 種別に一致した場合だけ allow-list を適用する。
+ *
+ * @param pointerType The event's pointer type. イベントのポインタ種別。
+ * @param allowed Allowed pointer types. 許可するポインタ種別。
+ * @returns True when the drag may proceed. ドラッグを進めてよい場合に true。
+ */
+const isPointerDragAllowed = (pointerType: string, allowed: readonly ("mouse" | "pen" | "touch")[]): boolean => {
+    const known = pointerType === "mouse" || pointerType === "pen" || pointerType === "touch"
+    return !known || allowed.includes(pointerType)
+}
+
 const DEFAULT_INERTIA_OPTIONS: ResolvedScrollPaneInertiaOptions = {
     maxVelocity: 6,
     minVelocity: 0.02,
@@ -109,6 +145,8 @@ type DragSample = {
 }
 
 type DragState = {
+    /** 進行中ドラッグを開始したポインタの種別。許可集合の変化を検知するために保持する。 */
+    pointerType: string
     pointerId: number | null
     startClientY: number
     startScroll: number
@@ -156,6 +194,7 @@ export const ScrollPane = forwardRef<ScrollPaneHandle, ScrollPaneProps>(
             enableTrackClick = true,
             enableArrowButtons = true,
             enablePointerDrag = true,
+            pointerDragInputs = DEFAULT_POINTER_DRAG_INPUTS,
             onScroll,
             className,
             testId,
@@ -303,6 +342,28 @@ export const ScrollPane = forwardRef<ScrollPaneHandle, ScrollPaneProps>(
             [onScroll],
         )
 
+        /**
+         * Keeps the latest scroll seam reachable from long-lived loops.
+         * 長寿命のループから最新のスクロール口へ届くようにする ref。
+         *
+         * ❗ 慣性 RAF ループとポインタドラッグはどちらも**張り直されない**。
+         * `scrollTo` を字句束縛で捕まえると、`onScroll` prop が差し替わった後も
+         * 古いコールバックへ通知し続ける (慣性は指を離してから数秒走る)。
+         */
+        const scrollToRef = useRef(scrollTo)
+
+        /**
+         * Refreshes the scroll seam reference.
+         * スクロール口の参照を最新に保つ副作用。
+         *
+         * 目的: `onScroll` 差し替え後も進行中のループが最新の口へ通知するようにする。
+         * 依存関係: [scrollTo]
+         * クリーンアップ: 不要。
+         */
+        useEffect(() => {
+            scrollToRef.current = scrollTo
+        }, [scrollTo])
+
         const stopInertia = useCallback(() => {
             const state = inertiaStateRef.current
             // 世代を進め、実行中の step (cancelAnimationFrame が効かない同期再入) にも停止を伝える
@@ -383,7 +444,9 @@ export const ScrollPane = forwardRef<ScrollPaneHandle, ScrollPaneProps>(
                     const previousPosition = scrollPositionRef.current
 
                     if (distance !== 0) {
-                        scrollTo((prevPositionInternal) => prevPositionInternal + distance)
+                        // ❗ 字句束縛の `scrollTo` ではなく ref を読む。ループは自身を
+                        // 再アームし続けるため、束縛すると解放時点の `onScroll` へ数秒間通知し続ける
+                        scrollToRef.current((prevPositionInternal) => prevPositionInternal + distance)
                     }
 
                     // scrollTo の onScroll から同期的に stopInertia (handle.scrollTo 等) が呼ばれた場合は
@@ -410,7 +473,7 @@ export const ScrollPane = forwardRef<ScrollPaneHandle, ScrollPaneProps>(
 
                 inertiaStateRef.current.frame = requestAnimationFrame(step)
             },
-            [isScrollable, resolvedInertiaOptions, scrollTo, stopInertia],
+            [isScrollable, resolvedInertiaOptions, stopInertia],
         )
 
         const startInertiaRef = useRef(startInertia)
@@ -535,16 +598,35 @@ export const ScrollPane = forwardRef<ScrollPaneHandle, ScrollPaneProps>(
                 scrollTo((prev) => prev + deltaY)
             }
 
+            /**
+             * Cancels inertia as soon as the user touches anywhere in the pane.
+             * ペイン内のどこかに触れた時点で慣性を止めるハンドラー。
+             *
+             * ❗ スクロールバー (タップスクロールサークルを含む) はコンテンツ領域の**兄弟**であり、
+             * コンテンツ側の pointerdown は届かない。慣性走行中にサークルを掴むと
+             * **慣性ループと自動スクロールループが同じスクロール位置を奪い合い**、
+             * 残差アキュムレータの影響で正味移動量が脈打って引き量と速度が一致しなくなる。
+             * ペイン根で capture フェーズに 1 本張り、`enablePointerDrag` のガードの外側で必ず止める。
+             *
+             * これは「触れた時点で止める」側の防衛線。逆順 (自動スクロール中に慣性が始まる) は
+             * ここでは救えないため、`handleScrollBarScroll` が二重に受け持つ。
+             */
+            const handlePaneInteraction = () => {
+                stopInertia()
+            }
+
             const scrollContainer = scrollContainerRef.current
             if (scrollContainer) {
                 // wheel イベントリスナーを passive: false で登録し、preventDefault を可能にする
                 scrollContainer.addEventListener("wheel", handleWheel, { passive: false })
+                scrollContainer.addEventListener("pointerdown", handlePaneInteraction, { capture: true, passive: true })
             }
 
             // クリーンアップ関数
             return () => {
                 if (scrollContainer) {
                     scrollContainer.removeEventListener("wheel", handleWheel)
+                    scrollContainer.removeEventListener("pointerdown", handlePaneInteraction, { capture: true })
                 }
             }
         }, [isScrollable, scrollTo, stopInertia, viewportSize, wheelSpeedMultiplier])
@@ -563,14 +645,10 @@ export const ScrollPane = forwardRef<ScrollPaneHandle, ScrollPaneProps>(
             [scrollTo, contentSize, viewportSize, stopInertia],
         )
 
-        const scrollToRef = useRef(scrollTo)
-        useEffect(() => {
-            scrollToRef.current = scrollTo
-        }, [scrollTo])
-
         const id = useId()
 
         const dragStateRef = useRef<DragState>({
+            pointerType: "",
             pointerId: null,
             startClientY: 0,
             startScroll: 0,
@@ -581,10 +659,23 @@ export const ScrollPane = forwardRef<ScrollPaneHandle, ScrollPaneProps>(
         })
 
         const enablePointerDragRef = useRef(enablePointerDrag)
+        const pointerDragInputsRef = useRef(pointerDragInputs)
         useEffect(() => {
             enablePointerDragRef.current = enablePointerDrag
         }, [enablePointerDrag])
 
+        /**
+         * Keeps the allowed pointer types fresh for the listener closures.
+         * リスナークロージャが参照する許可ポインタ種別を最新に保つ副作用。
+         *
+         * 目的: リスナーは 1 度だけ張るため、設定変更を ref 経由で伝える。
+         * 依存関係: [pointerDragInputs]
+         * クリーンアップ: 不要。
+         */
+        useEffect(() => {
+            pointerDragInputsRef.current = pointerDragInputs
+        }, [pointerDragInputs])
+
         const isScrollableRef = useRef(isScrollable)
         useEffect(() => {
             isScrollableRef.current = isScrollable
@@ -595,28 +686,76 @@ export const ScrollPane = forwardRef<ScrollPaneHandle, ScrollPaneProps>(
             inertiaOptionsRef.current = resolvedInertiaOptions
         }, [resolvedInertiaOptions])
 
+        /**
+         * Tears down an in-flight drag once it is no longer permitted.
+         * 進行中のドラッグが許可されなくなったら後始末する副作用。
+         *
+         * ❗ 判定は `handlePointerMove` が見ている**継続条件と完全に同じ 3 つ**
+         * (`enablePointerDrag` / `pointerDragInputs` / `isScrollable`) を見ること。
+         * どれか 1 つでも落とすと、その条件が偽になったときに `pointermove` だけが
+         * 早期 return して `pointerId` とポインタキャプチャが居座り、
+         * (1) 指を置いたまま追従が止まる、(2) 先勝ちガードで新規ドラッグを開始できない、
+         * (3) 解放時に `handlePointerUp` が追従しなかった移動分の速度で慣性を起動する、
+         * という 3 つの症状が出る。
+         * `isScrollable` に至っては 4 つ目の症状もある: `startClientY` / `startScroll` が
+         * 基準として残るため、スクロール可能へ戻った瞬間に**取りこぼした移動量が 1 フレームで
+         * まとめて適用される**(実測: 190px の空走が 0 → 210 の瞬間移動として再生された)。
+         *
+         * ❗ **クリック抑止は引き継ぐ。** 既に 6px を超えて `isDragging` が立っていた場合、
+         * ブラウザはこのジェスチャの終わりに click を合成する。ここで
+         * `shouldCancelNextClick` を落とすと、スクロールしただけなのに指の下の行が
+         * 選択・展開される。
+         *
+         * ❗ **ここで 0ms タイマーを張ってはならない。** このエフェクトが走るのは
+         * **指がまだ触れている最中**であり、click が合成されるのは指を離した後 (数百 ms 後の
+         * 別マクロタスク) である。`handlePointerUp` の 0ms タイマーは「pointerup → click が
+         * 同一タスク列で連続する」から正当なのであって、ここへ流用すると click が届く前に
+         * 抑止が解けて**修正が実機で 1 度も効かない**。抑止の解除は
+         * (1) `handleClickCapture` が 1 回消費する、(2) ジェスチャ終端の `pointerup` /
+         * `pointercancel` が 0ms タイマーを張る、(3) 次の `pointerdown` が捨てる、
+         * の 3 経路が受け持つ。
+         *
+         * ❗ **`pointerId` を null にしてからキャプチャを解放すること。**
+         * `releasePointerCapture` が `lostpointercapture` を同期発火するブラウザでは、
+         * 順序を誤ると `handleLostPointerCapture` → `abortDrag` が先に走って
+         * `shouldCancelNextClick` を落とし、引き継ぎが**この行に到達する前に死ぬ**。
+         * `handlePointerUp` が同じ順序を採っているのもこの理由による。
+         *
+         * 目的: ドラッグ継続条件が偽になった時点で状態とキャプチャを解放する。
+         * 依存関係: [enablePointerDrag, pointerDragInputs, isScrollable]
+         * クリーンアップ: 不要。
+         */
         useEffect(() => {
-            if (enablePointerDrag) {
+            const state = dragStateRef.current
+            // 進行中のドラッグが今も許可されているなら何もしない
+            if (enablePointerDrag && isScrollable && (state.pointerId === null || isPointerDragAllowed(state.pointerType, pointerDragInputs))) {
                 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.pointerId === null) {
+                return
             }
+            const element = contentAreaRef.current
             if (state.clickResetTimer !== null) {
                 window.clearTimeout(state.clickResetTimer)
                 state.clickResetTimer = null
             }
+            // ドラッグが確定していたなら、このジェスチャ終端で合成される click を握り潰す
+            const shouldKeepClickSuppression = state.isDragging && state.shouldCancelNextClick
+            // pointerId=0 (Firefox のマウス) を falsy として弾かないよう !== null で判定する
+            // Compare with null so pointerId=0 (Firefox mouse) is not skipped as falsy.
+            const releasedPointerId = state.pointerId
             state.pointerId = null
+            state.pointerType = ""
             state.startClientY = 0
             state.startScroll = 0
             state.isDragging = false
-            state.shouldCancelNextClick = false
+            state.shouldCancelNextClick = shouldKeepClickSuppression
             state.velocitySamples = []
-        }, [enablePointerDrag])
+            // 状態を確定させてから解放する (同期 lostpointercapture に引き継ぎを壊させない)
+            if (element?.hasPointerCapture(releasedPointerId)) {
+                element.releasePointerCapture(releasedPointerId)
+            }
+        }, [enablePointerDrag, pointerDragInputs, isScrollable])
 
         useEffect(() => {
             const element = contentAreaRef.current
@@ -630,6 +769,7 @@ export const ScrollPane = forwardRef<ScrollPaneHandle, ScrollPaneProps>(
             const resetDragState = () => {
                 const state = dragStateRef.current
                 state.pointerId = null
+                state.pointerType = ""
                 state.startClientY = 0
                 state.startScroll = 0
                 state.isDragging = false
@@ -711,6 +851,9 @@ export const ScrollPane = forwardRef<ScrollPaneHandle, ScrollPaneProps>(
                 if (!(enablePointerDragRef.current && isScrollableRef.current)) {
                     return
                 }
+                if (!isPointerDragAllowed(event.pointerType, pointerDragInputsRef.current)) {
+                    return
+                }
                 if (!state.isDragging) {
                     const distanceY = Math.abs(event.clientY - state.startClientY)
                     if (distanceY < DRAG_ACTIVATION_THRESHOLD) {
@@ -733,9 +876,34 @@ export const ScrollPane = forwardRef<ScrollPaneHandle, ScrollPaneProps>(
                 }
             }
 
+            /**
+             * Arms the one-shot click suppression left behind by the teardown effect.
+             * 後始末エフェクトが残したクリック抑止を、ジェスチャ終端で 1 回限りに落とす処理。
+             *
+             * 後始末はドラッグ枠を空にするため、以降の `pointerup` / `pointercancel` は
+             * pointerId 不一致で素通りしてしまう。ここで拾って `handlePointerUp` と同じ
+             * 0ms タイマーを張り、直後に合成される click を 1 回だけ握り潰したうえで解除する。
+             *
+             * @returns True when the orphaned suppression was handled. 残骸を処理したなら true。
+             */
+            const armOrphanedClickSuppression = () => {
+                const state = dragStateRef.current
+                if (state.pointerId !== null || !state.shouldCancelNextClick) {
+                    return false
+                }
+                clearClickTimer()
+                state.clickResetTimer = window.setTimeout(() => {
+                    const latest = dragStateRef.current
+                    latest.shouldCancelNextClick = false
+                    latest.clickResetTimer = null
+                }, 0)
+                return true
+            }
+
             const handlePointerUp = (event: PointerEvent) => {
                 const state = dragStateRef.current
                 if (state.pointerId !== event.pointerId) {
+                    armOrphanedClickSuppression()
                     return
                 }
 
@@ -796,9 +964,19 @@ export const ScrollPane = forwardRef<ScrollPaneHandle, ScrollPaneProps>(
                 if (dragStateRef.current.pointerId !== null) {
                     return
                 }
+                // 進行中ドラッグが無いのに抑止が残っているなら、click が来なかった前ジェスチャの残骸。
+                // 新しいジェスチャへ持ち越すと無関係なクリックを飲み込むのでここで捨てる
+                if (dragStateRef.current.shouldCancelNextClick) {
+                    clearClickTimer()
+                    dragStateRef.current.shouldCancelNextClick = false
+                }
                 if (!(enablePointerDragRef.current && isScrollableRef.current)) {
                     return
                 }
+                // 入力種別ごとの許可。マウスだけ外してもタッチのスクロール手段は残る
+                if (!isPointerDragAllowed(event.pointerType, pointerDragInputsRef.current)) {
+                    return
+                }
                 if (event.button !== 0 && event.pointerType === "mouse") {
                     return
                 }
@@ -816,6 +994,7 @@ export const ScrollPane = forwardRef<ScrollPaneHandle, ScrollPaneProps>(
                 const state = dragStateRef.current
                 clearClickTimer()
                 state.pointerId = event.pointerId
+                state.pointerType = event.pointerType
                 state.startClientY = event.clientY
                 state.startScroll = scrollPositionRef.current
                 state.isDragging = false
@@ -826,6 +1005,7 @@ export const ScrollPane = forwardRef<ScrollPaneHandle, ScrollPaneProps>(
             const handlePointerCancel = (event: PointerEvent) => {
                 const state = dragStateRef.current
                 if (state.pointerId !== event.pointerId) {
+                    armOrphanedClickSuppression()
                     return
                 }
                 abortDrag(event.pointerId)
@@ -873,18 +1053,51 @@ export const ScrollPane = forwardRef<ScrollPaneHandle, ScrollPaneProps>(
             }
         }, [id])
 
+        /**
+         * Scroll seam handed to the scrollbar, which always cancels inertia first.
+         * スクロールバーへ渡すスクロール口。必ず先に慣性を止める。
+         *
+         * ❗ ペイン根の `pointerdown` で止めるだけでは足りない。あちらが救えるのは
+         * 「慣性が先、スクロールバー操作が後」の順序だけで、**逆順が抜ける**。
+         * サークルを掴んで自動スクロールを始めた後にコンテンツを弾いて慣性を起動すると、
+         * 慣性ループと自動スクロールループが同じスクロール位置を奪い合い、位置が往復する
+         * (実測: 140 → 100 → 30 → 184 と脈打つ)。矢印ボタンのキー操作のように
+         * pointerdown を伴わない経路も同様に抜ける。
+         * スクロールバー由来のスクロールが届いた時点で毎回止めれば、順序と経路に依らず排他になる。
+         *
+         * ❗ **`scrollTo` の戻り値は必ず返すこと。** `ScrollBar` の `resolveScrollRequest` は、
+         * 戻り値が有限数のときだけそれを自分の位置追跡 (`latestScrollPositionRef`) に採用し、
+         * 無ければ**自前の (古い) 基準から次位置を再計算**する。`ScrollPane` はステートレスで
+         * ホイールやドラッグで動いても `ScrollBar` を再描画しないため、その基準は簡単に陳腐化する。
+         * 戻り値を落とすと `ScrollBar` は「実際は末端に居るのに境界と判定できない」状態になり、
+         * タップ自動スクロールのループが止まらなくなる。
+         */
+        const handleScrollBarScroll = useCallback(
+            (position: number | ((prev: number) => number)) => {
+                stopInertia()
+                return scrollTo(position)
+            },
+            [scrollTo, stopInertia],
+        )
+
         return (
             <div ref={scrollContainerRef} data-testid={testId} className={twMerge("aqvs-scroll-pane", className)} style={style}>
                 <div
                     ref={contentAreaRef}
                     className={twMerge("aqvs-scroll-pane-content")}
+                    // 常時出力する固定の DOM フック。DOM フックはクラスセレクタでなく data-* 属性を使う
+                    // (AGENTS.md 準拠)。ルート要素は `testId` prop で利用側が名前を決められるが、
+                    // コンテンツ領域には prop が無いため、パッケージ側で固定値を出す
+                    data-testid="aqvs-scroll-pane-content"
                     style={{
                         height: viewportSize,
                         paddingTop: resolvedInsets.top,
                         paddingBottom: resolvedInsets.bottom,
                         // スクロール不能時 (contentSize <= viewportSize) は touch-action を通常に戻し、
-                        // 短いリスト上のタッチがページ全体のパンを妨げるデッドゾーン化を防ぐ
-                        ...(enablePointerDrag && isScrollable ? { touchAction: "none" } : {}),
+                        // 短いリスト上のタッチがページ全体のパンを妨げるデッドゾーン化を防ぐ。
+                        // 直接操作 (指・ペン) のドラッグを許可していない場合も付けない。
+                        // touch-action はペン入力にも効くため、判定は touch と pen の論理和にする
+                        ...(enablePointerDrag && isScrollable && pointerDragInputs.some((type) => type === "touch" || type === "pen") ? { touchAction: "none" } : {}),
                     }}
                     id={id}>
                     {background}
@@ -895,7 +1108,7 @@ export const ScrollPane = forwardRef<ScrollPaneHandle, ScrollPaneProps>(
                     contentSize={contentSize}
                     viewportSize={viewportSize}
                     scrollPosition={scrollPositionRef.current}
-                    onScroll={scrollTo}
+                    onScroll={handleScrollBarScroll}
                     enableThumbDrag={enableThumbDrag}
                     enableTrackClick={enableTrackClick}
                     enableArrowButtons={enableArrowButtons}

package/src/VirtualScroll.tsx

@@ -65,6 +65,15 @@ export type VirtualScrollScrollBarOptions = {
 
 export type VirtualScrollBehaviorOptions = {
     enablePointerDrag?: boolean
+    /**
+     * Pointer types allowed to drag-scroll the content area (default: all).
+     * コンテンツ領域のドラッグスクロールを許可するポインタ種別 (既定: 全種別)。
+     *
+     * マウスドラッグだけが困る場合に `["pen", "touch"]` を指定する。
+     * `enablePointerDrag` を丸ごと切るとタッチ端末からスクロール手段が消えるため、
+     * 種別で絞れるならこちらを使うこと (`ScrollPaneProps["pointerDragInputs"]` 参照)。
+     */
+    pointerDragInputs?: ScrollPaneProps["pointerDragInputs"]
     enableKeyboardNavigation?: boolean
     wheelSpeedMultiplier?: number
     inertiaOptions?: ScrollPaneProps["inertiaOptions"]
@@ -663,7 +672,7 @@ const VirtualScrollInner = <T,>(
 ) => {
     const { width: scrollBarWidth, enableThumbDrag, enableTrackClick, enableArrowButtons, enableScrollToTopBottomButtons, renderThumbOverlay, tapScrollCircleOptions } = scrollBarOptions ?? {}
 
-    const { enablePointerDrag, enableKeyboardNavigation = true, wheelSpeedMultiplier, inertiaOptions, clipItemHeight = false, resetOnGetItemHeightChange = false } = behaviorOptions ?? {}
+    const { enablePointerDrag, pointerDragInputs, enableKeyboardNavigation = true, wheelSpeedMultiplier, inertiaOptions, clipItemHeight = false, resetOnGetItemHeightChange = false } = behaviorOptions ?? {}
 
     const scrollPaneRef = useRef<VirtualScrollHandle>(null)
     const currentRangeRef = useRef<VirtualScrollRange>({
@@ -1868,6 +1877,7 @@ const VirtualScrollInner = <T,>(
             enableTrackClick={enableTrackClick}
             enableArrowButtons={enableArrowButtons}
             enablePointerDrag={enablePointerDrag}
+            pointerDragInputs={pointerDragInputs}
             renderThumbOverlay={renderThumbOverlay}
             wheelSpeedMultiplier={wheelSpeedMultiplier}
             onWheelHorizontal={onWheelHorizontal}

package/src/index.ts

@@ -5,7 +5,7 @@
  * 可変なアイテム高さに対応したReact用の高性能仮想スクロールコンポーネント。
  */
 
-export { ScrollBar, type ScrollBarProps, type ScrollBarTapCircleOptions, type ScrollBarThumbOverlayRenderProps } from "./ScrollBar.tsx"
+export { computeAutoTapScrollMaxSpeedMultiplier, computeTapScrollSpeed, ScrollBar, type ScrollBarProps, type ScrollBarTapCircleOptions, type ScrollBarThumbOverlayRenderProps, TAP_SCROLL_SPEED_DEFAULTS, type TapScrollSpeedInput } from "./ScrollBar.tsx"
 export { ScrollPane, type ScrollPaneContentInsets, type ScrollPaneHandle, type ScrollPaneInertiaOptions, type ScrollPaneProps } from "./ScrollPane.tsx"
 export type { TapScrollCircleRenderProps } from "./TapScrollCircle.tsx"
 export { tapScrollCircleSampleVisual } from "./tapScrollCircleSampleVisual.tsx"

package/src/styles/virtualscroll.css

@@ -46,7 +46,7 @@
   border-radius: 9999px;
 }
 
-.aqvs-sample-visual-rod {
+.aqvs-sample-visual-pupil {
   position: absolute;
   top: 50%;
   left: 50%;
@@ -56,7 +56,7 @@
   background-color: rgba(255, 255, 255, 0.85);
 }
 
-.aqvs-sample-visual-pupil {
+.aqvs-sample-visual-highlight {
   position: absolute;
   top: 50%;
   left: 50%;
@@ -64,7 +64,7 @@
   background-color: rgba(255, 255, 255, 0.8);
 }
 
-.aqvs-sample-visual-highlight {
+.aqvs-sample-visual-rod {
   position: absolute;
   top: 50%;
   left: 50%;

package/src/tapScrollCircleSampleVisual.tsx

@@ -1,6 +1,23 @@
 /**
- * Provides the sample tap scroll circle visual used for demos.
- * デモ用に使用されるサンプルのタップスクロールビジュアルを提供するモジュール。
+ * Provides an opt-in tap scroll circle visual (an eye-like sphere with a direction rod).
+ * タップスクロールサークル用の、明示的に選択して使うビジュアル (方向ロッド付きの目玉状) を提供するモジュール。
+ *
+ * ❗ **これは既定ではない。** `renderVisual` を省略した場合に描かれるのは
+ * `TapScrollCircle` 内部の `defaultRenderVisual` であり、この関数は
+ * `tapScrollCircleOptions.renderVisual` へ明示的に渡した消費側だけが目にする。
+ *
+ * ❗ **一方で「デモ専用」でもない。** 本リポジトリでは日報の 2 つの一覧、
+ * コンタクトマップの 2 ビュー、`ExplorerTreePanel` が本番でこれを選んでいる。
+ * `aqvs-sample-visual-*` というクラス名は歴史的経緯で「サンプル」を名乗っているだけなので、
+ * **本番 UI の一部として扱うこと**。
+ *
+ * 3 つの要素とクラス名の対応 (役割と名前が一致していること):
+ *
+ * | 要素 | クラス | 寸法・位置を決める値 |
+ * | --- | --- | --- |
+ * | 瞳 | `aqvs-sample-visual-pupil` | `coreSize` / `pupilScale` / `pupilX,Y` |
+ * | ハイライト | `aqvs-sample-visual-highlight` | `highlightSize` / `highlightOpacity` |
+ * | 尾 (ロッド) | `aqvs-sample-visual-rod` | `rodWidth` / `rodHeight` / `rodTranslate` |
  */
 
 import type { TapScrollCircleProps, TapScrollCircleRenderProps } from "./TapScrollCircle.tsx"
@@ -40,7 +57,7 @@ export const tapScrollCircleSampleVisual: NonNullable<TapScrollCircleProps["rend
                 }}
             />
             <div
-                className="aqvs-sample-visual-rod"
+                className="aqvs-sample-visual-pupil"
                 style={{
                     width: coreSize,
                     height: coreSize,
@@ -49,7 +66,7 @@ export const tapScrollCircleSampleVisual: NonNullable<TapScrollCircleProps["rend
                 }}
             />
             <div
-                className="aqvs-sample-visual-pupil"
+                className="aqvs-sample-visual-highlight"
                 style={{
                     width: highlightSize,
                     height: highlightSize,
@@ -60,7 +77,7 @@ export const tapScrollCircleSampleVisual: NonNullable<TapScrollCircleProps["rend
                 }}
             />
             <div
-                className="aqvs-sample-visual-highlight"
+                className="aqvs-sample-visual-rod"
                 style={{
                     width: rodWidth,
                     height: rodHeight,