@aiquants/virtualscroll 3.7.0 → 3.8.0

package/src/ScrollPane.tsx

@@ -2,6 +2,7 @@ import { forwardRef, useCallback, useEffect, useId, useImperativeHandle, useLayo
 import { twMerge } from "tailwind-merge"
 import type { VirtualScrollLabelOverrides, VirtualScrollLocale } from "./labels.ts"
 import { Logger } from "./logger.ts"
+import { capturePointer, isPointerCaptured, releaseCapturedPointer } from "./pointerCapture.ts"
 import { ScrollBar, type ScrollBarTapCircleOptions, type ScrollBarThumbOverlayRenderProps, TAP_SCROLL_CANCEL_EVENT } from "./ScrollBar.tsx"
 import { getAxisScale, minmax } from "./utils.ts"
 import { resolveWheelAxes } from "./wheelAxes.ts"
@@ -78,6 +79,21 @@ export type ScrollPaneProps = {
     enableTrackClick?: boolean
     /** Whether arrow buttons control the scroll position. / 矢印ボタンのスクロール操作を許可するかどうか。 */
     enableArrowButtons?: boolean
+    /**
+     * Whether the scrollbar's two arrow buttons are Tab stops (default `true`), forwarded to the
+     * pane's ScrollBar. Set it to `false` when the host already provides keyboard scrolling for this
+     * pane: the arrows then only add two redundant Tab stops (native scrollbars are never Tab stops
+     * either). `false` changes `tabIndex` alone — the arrows stay pointer-operable and named. The
+     * default stays `true` because otherwise they are the pane's only scrolling control that Tab
+     * reaches. Full contract: `ScrollBarProps["enableArrowButtonTabStops"]`.
+     * スクロールバーの矢印ボタン 2 個を Tab の止まり先にするかどうか (既定 `true`)。ペインの ScrollBar へ
+     * 転送。ホストがこのペインのキーボードスクロールを既に提供する場合に `false` — 矢印は冗長な Tab の
+     * 止まり先を 2 つ足すだけになるため (ネイティブのスクロールバーも Tab の止まり先にならない)。`false` が
+     * 変えるのは `tabIndex` だけで、ポインタ操作とアクセシブルネームは維持。
+     * 既定が `true` なのは、それ以外ではペインで Tab の届く唯一のスクロール操作部品だから。契約の全文は
+     * `ScrollBarProps["enableArrowButtonTabStops"]`。
+     */
+    enableArrowButtonTabStops?: boolean
     /** Whether dragging the content area scrolls the pane. / コンテンツ領域のドラッグでスクロールさせるかどうか。 */
     enablePointerDrag?: boolean
     /**
@@ -326,6 +342,7 @@ export const ScrollPane = forwardRef<ScrollPaneHandle, ScrollPaneProps>(
             enableThumbDrag = true,
             enableTrackClick = true,
             enableArrowButtons = true,
+            enableArrowButtonTabStops = true,
             enablePointerDrag = true,
             pointerDragInputs = DEFAULT_POINTER_DRAG_INPUTS,
             onScroll,
@@ -1133,11 +1150,22 @@ export const ScrollPane = forwardRef<ScrollPaneHandle, ScrollPaneProps>(
             state.velocitySamples = []
             state.scale = 1
             // 状態を確定させてから解放する (同期 lostpointercapture に引き継ぎを壊させない)
-            if (element?.hasPointerCapture(releasedPointerId)) {
-                element.releasePointerCapture(releasedPointerId)
+            if (element !== null) {
+                releaseCapturedPointer(element, releasedPointerId)
             }
         }, [enablePointerDrag, pointerDragInputs, isScrollable])
 
+        /**
+         * Wires the pointer drag-scroll of the content area and tears it down on unmount.
+         * コンテンツ領域のポインタドラッグスクロールを結線し、アンマウント時に解除する処理。
+         *
+         * キャプチャの取得・解放・保持確認はすべて `pointerCapture.ts` の能力判定を通す。
+         * Pointer Capture API の無い環境 (jsdom 等) でもドラッグは `window` のリスナーで追従し、例外は投げない。
+         *
+         * 目的: ドラッグ・慣性・click 抑止のリスナーをコンテンツ要素と `window` へ登録する。
+         * 依存関係: [id]
+         * クリーンアップ: リスナーを外し、保持中のキャプチャを解放してドラッグ状態を初期化する。
+         */
         useEffect(() => {
             const element = contentAreaRef.current
             if (!element) {
@@ -1186,6 +1214,16 @@ export const ScrollPane = forwardRef<ScrollPaneHandle, ScrollPaneProps>(
                 state.shouldCancelNextClick = false
             }
 
+            /**
+             * Confirms the drag once the activation threshold is crossed and moves the capture onto the content area.
+             * 発動閾値を跨いだ時点でドラッグを確定し、キャプチャをコンテンツ領域へ移す処理。
+             *
+             * キャプチャを取れない場合 (非アクティブなポインタ・Pointer Capture API の非対応環境) も
+             * ドラッグは確定させる。追従は `window` の `pointermove` が受け持つため、キャプチャが無くても止まらない。
+             *
+             * @param event The pointer move that crossed the threshold. 閾値を跨いだ pointermove。
+             * @returns Nothing. なし。
+             */
             const startDragging = (event: PointerEvent) => {
                 const state = dragStateRef.current
                 if (state.isDragging) {
@@ -1193,16 +1231,13 @@ export const ScrollPane = forwardRef<ScrollPaneHandle, ScrollPaneProps>(
                 }
                 state.isDragging = true
                 state.shouldCancelNextClick = true
-                if (!element.hasPointerCapture(event.pointerId)) {
+                if (!isPointerCaptured(element, event.pointerId)) {
                     // 注意: キャプチャは pointerdown 時ではなくドラッグ確定時に取得する。
                     // pointerdown で即キャプチャすると click がキャプチャ要素へリターゲットされ、
                     // ペイン内の子要素 (行など) の click ハンドラが一切発火しなくなる (Chromium 実測)。
                     // ドラッグ確定後は shouldCancelNextClick で click を意図的に抑止するため副作用がない。
-                    try {
-                        element.setPointerCapture(event.pointerId)
-                    } catch {
-                        // ポインタが既に非アクティブだと NotFoundError になり得る。キャプチャ無しでもドラッグは継続可能。
-                    }
+                    // 取得に失敗してもキャプチャ無しでドラッグは継続できるため、結果は見ない。
+                    capturePointer(element, event.pointerId)
                 }
                 pushVelocitySample(event.clientY)
             }
@@ -1244,13 +1279,16 @@ export const ScrollPane = forwardRef<ScrollPaneHandle, ScrollPaneProps>(
              */
             const isAuthoritativeForDrag = (event: PointerEvent) => event.isTrusted || event.target === element
 
-            // pointerup を受け取れないままドラッグ継続が不可能になったときの共通終了処理。
-            // Shared teardown for cases where the drag can no longer continue without receiving a pointerup.
+            /**
+             * Shared teardown for cases where the drag can no longer continue without receiving a pointerup.
+             * pointerup を受け取れないままドラッグ継続が不可能になったときの共通終了処理。
+             *
+             * @param pointerId The pointer whose drag is aborted. ドラッグを打ち切るポインタ ID。
+             * @returns Nothing. なし。
+             */
             const abortDrag = (pointerId: number) => {
                 const state = dragStateRef.current
-                if (element.hasPointerCapture(pointerId)) {
-                    element.releasePointerCapture(pointerId)
-                }
+                releaseCapturedPointer(element, pointerId)
                 state.shouldCancelNextClick = false
                 clearClickTimer()
                 resetDragState()
@@ -1337,6 +1375,13 @@ export const ScrollPane = forwardRef<ScrollPaneHandle, ScrollPaneProps>(
                 return true
             }
 
+            /**
+             * Ends the drag on pointerup, arms the click suppression and hands the fling velocity to inertia.
+             * pointerup でドラッグを終え、click 抑止を張り、フリック速度を慣性へ渡す処理。
+             *
+             * @param event The terminal pointerup. 終端の pointerup。
+             * @returns Nothing. なし。
+             */
             const handlePointerUp = (event: PointerEvent) => {
                 const state = dragStateRef.current
                 if (state.pointerId !== event.pointerId) {
@@ -1394,9 +1439,7 @@ export const ScrollPane = forwardRef<ScrollPaneHandle, ScrollPaneProps>(
                 // handleLostPointerCapture は pointerId 不一致で無視されるため、abortDrag による
                 // shouldCancelNextClick / clickResetTimer の破棄 (click 抑止の喪失) が起きない。
                 resetDragState()
-                if (element.hasPointerCapture(event.pointerId)) {
-                    element.releasePointerCapture(event.pointerId)
-                }
+                releaseCapturedPointer(element, event.pointerId)
 
                 if (Math.abs(inertiaVelocity) >= threshold) {
                     startInertiaRef.current?.(inertiaVelocity)
@@ -1558,8 +1601,8 @@ export const ScrollPane = forwardRef<ScrollPaneHandle, ScrollPaneProps>(
                 toggleListeners(element, elementEntries, "remove")
                 toggleListeners(window, windowEntries, "remove")
                 const state = dragStateRef.current
-                if (state.pointerId !== null && element.hasPointerCapture(state.pointerId)) {
-                    element.releasePointerCapture(state.pointerId)
+                if (state.pointerId !== null) {
+                    releaseCapturedPointer(element, state.pointerId)
                 }
                 clearClickTimer()
                 resetDragState()
@@ -1648,6 +1691,7 @@ export const ScrollPane = forwardRef<ScrollPaneHandle, ScrollPaneProps>(
                     enableThumbDrag={enableThumbDrag}
                     enableTrackClick={enableTrackClick}
                     enableArrowButtons={enableArrowButtons}
+                    enableArrowButtonTabStops={enableArrowButtonTabStops}
                     scrollBarWidth={scrollBarWidth}
                     ariaControls={contentId}
                     tapScrollCircleOptions={tapScrollCircleOptions}

package/src/TapScrollCircle.tsx

@@ -6,6 +6,7 @@
 import type { CSSProperties, ReactNode, PointerEvent as ReactPointerEvent } from "react"
 import { forwardRef, memo, useCallback, useImperativeHandle, useRef, useState } from "react"
 import { twMerge } from "tailwind-merge"
+import { capturePointer, releaseCapturedPointer } from "./pointerCapture.ts"
 
 export type TapScrollCircleDragState = {
     /** Whether the pointer is actively dragging. / ポインターがドラッグ中かどうか。 */
@@ -205,13 +206,20 @@ export const TapScrollCircle = memo(
             [applyDragState, axis],
         )
 
+        /**
+         * Releases the root's capture of the pointer when it holds one.
+         * ルートが指定ポインタのキャプチャを保持していれば解放する処理。
+         *
+         * @param pointerId The pointer to release, or null when no pointer is tracked. 解放するポインタ ID。追跡中のポインタが無ければ null。
+         * @returns Nothing. なし。
+         */
         const releasePointerCapture = useCallback((pointerId: number | null) => {
             if (pointerId === null) {
                 return
             }
             const element = rootRef.current
-            if (element?.hasPointerCapture(pointerId)) {
-                element.releasePointerCapture(pointerId)
+            if (element !== null) {
+                releaseCapturedPointer(element, pointerId)
             }
         }, [])
 
@@ -228,6 +236,15 @@ export const TapScrollCircle = memo(
             [applyDragState, releasePointerCapture],
         )
 
+        /**
+         * Starts a circle drag, or records a second pointer as the hand-off candidate during a drag.
+         * サークルのドラッグを開始する処理。ドラッグ中に押された別ポインタはハンドオフ候補として記録する。
+         *
+         * キャプチャを取得できなくても (非アクティブなポインタ・Pointer Capture API の非対応環境) ドラッグは開始する。
+         *
+         * @param event The pointerdown on the circle. サークル上の pointerdown。
+         * @returns Nothing. なし。
+         */
         const handlePointerDown = useCallback(
             (event: ReactPointerEvent<HTMLDivElement>) => {
                 // ドラッグ中に発生した別ポインター (2 本目のタッチ) は待機候補として記録し、
@@ -246,14 +263,9 @@ export const TapScrollCircle = memo(
                 const { left, top, width, height } = element.getBoundingClientRect()
                 centerRef.current = { x: left + width / 2, y: top + height / 2 }
                 pointerIdRef.current = event.pointerId
-                try {
-                    element.setPointerCapture(event.pointerId)
-                } catch {
-                    // ポインタが既に非アクティブ (ウインドウ外へ出た等) だと setPointerCapture は
-                    // NotFoundError を投げ得る。キャプチャ無しでもドラッグ処理は継続できるため握り潰す。
-                    // setPointerCapture can throw NotFoundError if the pointer is already inactive
-                    // (e.g. moved outside the browser window); dragging still works without capture.
-                }
+                // ポインタが既に非アクティブ (ウインドウ外へ出た等) でも API 非対応でも、
+                // キャプチャ無しでドラッグ処理は継続できるため結果は見ない。
+                capturePointer(element, event.pointerId)
                 updateDragState(event.clientX, event.clientY, true)
             },
             [updateDragState],
@@ -274,6 +286,16 @@ export const TapScrollCircle = memo(
             [updateDragState],
         )
 
+        /**
+         * Ends the circle drag on pointerup, handing control to a live pending pointer when one exists.
+         * pointerup でサークルのドラッグを終える処理。生きている待機候補ポインタがあれば制御を移譲する。
+         *
+         * 候補の生死は `capturePointer` の結果で判定する。`"inactive-pointer"` だけを死とみなし、
+         * API 非対応・それ以外の拒否は生死不明として移譲を続ける。
+         *
+         * @param event The pointerup or pointercancel on the circle. サークル上の pointerup / pointercancel。
+         * @returns Nothing. なし。
+         */
         const handlePointerUp = useCallback(
             (event: ReactPointerEvent<HTMLDivElement>) => {
                 if (pointerIdRef.current !== event.pointerId) {
@@ -296,21 +318,9 @@ export const TapScrollCircle = memo(
                     // pointers, so a dead candidate resets the state instead of getting promoted.
                     releasePointerCapture(event.pointerId)
                     const element = rootRef.current
-                    let candidateAlive = true
-                    if (element !== null && typeof element.setPointerCapture === "function") {
-                        try {
-                            element.setPointerCapture(pending.pointerId)
-                        } catch (error) {
-                            // NotFoundError = 候補ポインタが既に非アクティブ (サークル外で解放済み等)。
-                            // クロスレルム (iframe への portal 等) では DOMException の instanceof が
-                            // false になるため、name ベースで判定する (DOMException も name を持つので包含)。
-                            // それ以外 (キャプチャ未実装環境等) は生死不明のため移譲を継続する。
-                            const errorName = typeof error === "object" && error !== null && "name" in error ? (error as { name?: unknown }).name : undefined
-                            if (errorName === "NotFoundError") {
-                                candidateAlive = false
-                            }
-                        }
-                    }
+                    // NotFoundError (= サークル外で解放済み等) だけが死の証拠。API 非対応やそれ以外の拒否は
+                    // 生死不明のため移譲を継続する (候補を捨てると 2 本目の指が効かなくなる)。
+                    const candidateAlive = element === null || capturePointer(element, pending.pointerId) !== "inactive-pointer"
                     if (candidateAlive) {
                         pointerIdRef.current = pending.pointerId
                         updateDragState(pending.clientX, pending.clientY, true)