@aiquants/virtualscroll 3.7.0 → 3.7.1

package/dist/pointerCapture.d.cts

@@ -0,0 +1,68 @@
+/**
+ * @module pointerCapture
+ * @description The single capability rule for the Pointer Capture API, shared by every pointer interaction in this package.
+ *
+ * @description 本パッケージのすべてのポインタ操作が共有する、Pointer Capture API の唯一の能力判定モジュール。
+ *
+ * `ScrollPane` (コンテンツのドラッグスクロール)・`ScrollBar` (サム / トラックのドラッグ)・
+ * `TapScrollCircle` (タップスクロールサークル) は、キャプチャの取得・解放・保持確認を
+ * 必ずここを通して行う。要素の `setPointerCapture` / `releasePointerCapture` /
+ * `hasPointerCapture` を直接呼んではならない。
+ *
+ * ❗ **3 つのメソッドが揃っている要素だけを「対応」とみなす。** jsdom (React のテストの既定環境) は
+ * このどれも実装しないため、直接呼ぶと利用側の `user.click` 1 回で `TypeError` になる。
+ * 一部だけを実装する環境で「取得はしたが解放も確認もできない」状態を作らないよう、判定は 1 本にしてある。
+ *
+ * 非対応の要素ではキャプチャ無しで操作を続ける (縮退)。コンテンツ領域とサムのドラッグは
+ * `window` / `document` のリスナーが追従を受け持つため動き続け、トラックとタップサークルは
+ * ポインタが要素上にある間だけ追従する。失われるのは、ウインドウ外や iframe 上で離したときの
+ * 終端イベントの受信と、`lostpointercapture` による強制解放の検知である。
+ */
+/**
+ * Outcome of a pointer capture request.
+ * ポインタキャプチャ要求の結果。
+ *
+ * - `"captured"`: The element now holds the capture. / 要素がキャプチャを保持した。
+ * - `"unsupported"`: The element does not implement the Pointer Capture API; nothing was attempted. / 要素が API を実装しておらず、要求自体を行っていない。
+ * - `"inactive-pointer"`: The UA rejected the pointer as inactive (`NotFoundError`). / ポインタが非アクティブとして拒否された (`NotFoundError`)。
+ * - `"rejected"`: The UA rejected the request for any other reason. / それ以外の理由で拒否された。
+ */
+export type PointerCaptureResult = "captured" | "unsupported" | "inactive-pointer" | "rejected";
+/**
+ * Reports whether the element implements the whole Pointer Capture API.
+ * 要素が Pointer Capture API (取得・解放・保持確認の 3 メソッド) をすべて実装しているかの判定処理。
+ *
+ * @param element The element to inspect. 判定対象の要素。
+ * @returns True when set / release / has are all callable. 3 メソッドがすべて呼び出し可能な場合に true。
+ */
+export declare const supportsPointerCapture: (element: Element) => boolean;
+/**
+ * Reports whether the element holds (or has a pending) capture of the pointer.
+ * 要素が指定ポインタのキャプチャを保持 (または保留) しているかの判定処理。
+ *
+ * @param element The element to inspect. 判定対象の要素。
+ * @param pointerId The pointer to look up. 対象のポインタ ID。
+ * @returns True when the capture is held; always false when the API is unsupported. 保持している場合に true。API 非対応の要素では常に false。
+ */
+export declare const isPointerCaptured: (element: Element, pointerId: number) => boolean;
+/**
+ * Requests capture of the pointer for the element and classifies the outcome without throwing.
+ * 要素へ指定ポインタのキャプチャを要求し、例外を投げずに結果を分類する処理。
+ *
+ * @param element The element that should receive the capture. キャプチャを受け取る要素。
+ * @param pointerId The pointer to capture. キャプチャするポインタ ID。
+ * @returns The classified outcome of the request. 要求結果の分類。
+ */
+export declare const capturePointer: (element: Element, pointerId: number) => PointerCaptureResult;
+/**
+ * Releases the element's capture of the pointer when it holds one; does nothing otherwise.
+ * 要素が指定ポインタのキャプチャを保持していれば解放し、保持していなければ何もしない処理。
+ *
+ * 呼び出し側が状態を確定させてから呼ぶこと。`lostpointercapture` を同期発火するブラウザでは、
+ * この呼び出しの最中に喪失ハンドラーが走る。
+ *
+ * @param element The element that may hold the capture. キャプチャを保持している可能性のある要素。
+ * @param pointerId The pointer to release. 解放するポインタ ID。
+ * @returns Nothing. なし。
+ */
+export declare const releaseCapturedPointer: (element: Element, pointerId: number) => void;

package/dist/pointerCapture.d.ts

@@ -0,0 +1,69 @@
+/**
+ * @module pointerCapture
+ * @description The single capability rule for the Pointer Capture API, shared by every pointer interaction in this package.
+ *
+ * @description 本パッケージのすべてのポインタ操作が共有する、Pointer Capture API の唯一の能力判定モジュール。
+ *
+ * `ScrollPane` (コンテンツのドラッグスクロール)・`ScrollBar` (サム / トラックのドラッグ)・
+ * `TapScrollCircle` (タップスクロールサークル) は、キャプチャの取得・解放・保持確認を
+ * 必ずここを通して行う。要素の `setPointerCapture` / `releasePointerCapture` /
+ * `hasPointerCapture` を直接呼んではならない。
+ *
+ * ❗ **3 つのメソッドが揃っている要素だけを「対応」とみなす。** jsdom (React のテストの既定環境) は
+ * このどれも実装しないため、直接呼ぶと利用側の `user.click` 1 回で `TypeError` になる。
+ * 一部だけを実装する環境で「取得はしたが解放も確認もできない」状態を作らないよう、判定は 1 本にしてある。
+ *
+ * 非対応の要素ではキャプチャ無しで操作を続ける (縮退)。コンテンツ領域とサムのドラッグは
+ * `window` / `document` のリスナーが追従を受け持つため動き続け、トラックとタップサークルは
+ * ポインタが要素上にある間だけ追従する。失われるのは、ウインドウ外や iframe 上で離したときの
+ * 終端イベントの受信と、`lostpointercapture` による強制解放の検知である。
+ */
+/**
+ * Outcome of a pointer capture request.
+ * ポインタキャプチャ要求の結果。
+ *
+ * - `"captured"`: The element now holds the capture. / 要素がキャプチャを保持した。
+ * - `"unsupported"`: The element does not implement the Pointer Capture API; nothing was attempted. / 要素が API を実装しておらず、要求自体を行っていない。
+ * - `"inactive-pointer"`: The UA rejected the pointer as inactive (`NotFoundError`). / ポインタが非アクティブとして拒否された (`NotFoundError`)。
+ * - `"rejected"`: The UA rejected the request for any other reason. / それ以外の理由で拒否された。
+ */
+export type PointerCaptureResult = "captured" | "unsupported" | "inactive-pointer" | "rejected";
+/**
+ * Reports whether the element implements the whole Pointer Capture API.
+ * 要素が Pointer Capture API (取得・解放・保持確認の 3 メソッド) をすべて実装しているかの判定処理。
+ *
+ * @param element The element to inspect. 判定対象の要素。
+ * @returns True when set / release / has are all callable. 3 メソッドがすべて呼び出し可能な場合に true。
+ */
+export declare const supportsPointerCapture: (element: Element) => boolean;
+/**
+ * Reports whether the element holds (or has a pending) capture of the pointer.
+ * 要素が指定ポインタのキャプチャを保持 (または保留) しているかの判定処理。
+ *
+ * @param element The element to inspect. 判定対象の要素。
+ * @param pointerId The pointer to look up. 対象のポインタ ID。
+ * @returns True when the capture is held; always false when the API is unsupported. 保持している場合に true。API 非対応の要素では常に false。
+ */
+export declare const isPointerCaptured: (element: Element, pointerId: number) => boolean;
+/**
+ * Requests capture of the pointer for the element and classifies the outcome without throwing.
+ * 要素へ指定ポインタのキャプチャを要求し、例外を投げずに結果を分類する処理。
+ *
+ * @param element The element that should receive the capture. キャプチャを受け取る要素。
+ * @param pointerId The pointer to capture. キャプチャするポインタ ID。
+ * @returns The classified outcome of the request. 要求結果の分類。
+ */
+export declare const capturePointer: (element: Element, pointerId: number) => PointerCaptureResult;
+/**
+ * Releases the element's capture of the pointer when it holds one; does nothing otherwise.
+ * 要素が指定ポインタのキャプチャを保持していれば解放し、保持していなければ何もしない処理。
+ *
+ * 呼び出し側が状態を確定させてから呼ぶこと。`lostpointercapture` を同期発火するブラウザでは、
+ * この呼び出しの最中に喪失ハンドラーが走る。
+ *
+ * @param element The element that may hold the capture. キャプチャを保持している可能性のある要素。
+ * @param pointerId The pointer to release. 解放するポインタ ID。
+ * @returns Nothing. なし。
+ */
+export declare const releaseCapturedPointer: (element: Element, pointerId: number) => void;
+//# sourceMappingURL=pointerCapture.d.ts.map

package/dist/pointerCapture.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pointerCapture.d.ts","sourceRoot":"","sources":["../src/pointerCapture.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH;;;;;;;;GAQG;AACH,MAAM,MAAM,oBAAoB,GAAG,UAAU,GAAG,aAAa,GAAG,kBAAkB,GAAG,UAAU,CAAA;AAE/F;;;;;;GAMG;AACH,eAAO,MAAM,sBAAsB,GAAI,SAAS,OAAO,KAAG,OAAoK,CAAA;AAE9N;;;;;;;GAOG;AACH,eAAO,MAAM,iBAAiB,GAAI,SAAS,OAAO,EAAE,WAAW,MAAM,KAAG,OAAkF,CAAA;AAE1J;;;;;;;GAOG;AACH,eAAO,MAAM,cAAc,GAAI,SAAS,OAAO,EAAE,WAAW,MAAM,KAAG,oBAYpE,CAAA;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,sBAAsB,GAAI,SAAS,OAAO,EAAE,WAAW,MAAM,KAAG,IAI5E,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiquants/virtualscroll",
-  "version": "3.7.0",
+  "version": "3.7.1",
   "description": "High-performance virtual scrolling component for React with variable item heights",
   "sideEffects": [
     "**/*.css"

package/src/ScrollBar.tsx

@@ -8,6 +8,7 @@ import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState } fr
 import { twMerge } from "tailwind-merge"
 import { resolveVirtualScrollLabels, type VirtualScrollLabelOverrides, type VirtualScrollLocale } from "./labels.ts"
 import { Logger } from "./logger.ts"
+import { capturePointer, releaseCapturedPointer } from "./pointerCapture.ts"
 import { TapScrollCircle, type TapScrollCircleDragState, type TapScrollCircleHandle, type TapScrollCircleRenderProps } from "./TapScrollCircle.tsx"
 import { getAxisScale, minmax } from "./utils.ts"
 
@@ -1136,10 +1137,10 @@ export const ScrollBar = ({
 
     /**
      * Pointer up handler for thumb dragging.
-     * Cleans up drag state and visual feedback.
+     * Cleans up drag state and visual feedback, releasing the capture only when the press acquired one.
      *
      * つまみドラッグ用のポインタ上げハンドラー。
-     * ドラッグ状態と視覚的フィードバックをクリーンアップします。
+     * ドラッグ状態と視覚的フィードバックをクリーンアップし、押下時にキャプチャを取得できていた場合だけ解放します。
      */
     const handleThumbPointerUp = useCallback(
         (event: PointerEvent) => {
@@ -1152,9 +1153,8 @@ export const ScrollBar = ({
             document.removeEventListener("pointerup", handleThumbPointerUp)
             document.removeEventListener("pointercancel", handleThumbPointerUp)
 
-            const captureTarget = state.captureTarget
-            if (captureTarget?.hasPointerCapture?.(event.pointerId)) {
-                captureTarget.releasePointerCapture(event.pointerId)
+            if (state.captureTarget !== null) {
+                releaseCapturedPointer(state.captureTarget, event.pointerId)
             }
 
             thumbDragStateRef.current = { pointerId: null, startThumbPosition: 0, startClientX: 0, startClientY: 0, scale: 1, captureTarget: null }
@@ -1227,8 +1227,10 @@ export const ScrollBar = ({
     // スクロールバーのつまみをポインタイベントで処理
     /**
      * Handles pointer down interaction on the thumb.
+     * Captures the pointer when the element supports it; otherwise the drag continues on the document listeners alone.
      *
      * つまみ押下時のインタラクションを処理。
+     * 要素がキャプチャに対応していれば取得し、取得できなければ document のリスナーだけでドラッグを続ける。
      */
     const handlePointerDownOnThumb = (event: React.PointerEvent<HTMLDivElement>) => {
         if (!scrollBarVisible) {
@@ -1247,18 +1249,10 @@ export const ScrollBar = ({
 
         // ポインターキャプチャを取得し、iframe/ウィンドウ外での pointerup 取りこぼしによる
         // ドラッグ固着を防ぐ。キャプチャ後もイベントは document までバブリングするため既存の
-        // 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
-            }
-        }
+        const captureTarget = capturePointer(element, event.pointerId) === "captured" ? element : null
 
         thumbDragStateRef.current = {
             pointerId: event.pointerId,
@@ -1282,8 +1276,10 @@ export const ScrollBar = ({
 
     /**
      * Handles pointer down interaction on the track.
+     * Jumps to the pressed position and captures the pointer when the element supports it.
      *
      * トラック押下時のインタラクションを処理。
+     * 押下位置へ移動し、要素がキャプチャに対応していれば取得する。
      */
     const handlePointerDownOnTrack = (event: React.PointerEvent<HTMLDivElement>) => {
         if (!scrollBarVisible) {
@@ -1311,15 +1307,9 @@ export const ScrollBar = ({
         const initialPosition = translateToScrollPosition(startThumbPosition)
         resolveScrollRequest(initialPosition)
 
-        // サム側と同様、取得不能なポインター (非アクティブ pointerId 等) では例外を握り潰し、
-        // キャプチャなしのフォールバックでドラッグ状態の設定と preventDefault を継続する。
-        if (element.setPointerCapture) {
-            try {
-                element.setPointerCapture(event.pointerId)
-            } catch {
-                // キャプチャ取得失敗時はキャプチャなしで続行 (要素上の pointermove では追従する)。
-            }
-        }
+        // 取得できなくても (非アクティブ pointerId・API 非対応) ドラッグ状態の設定と preventDefault は続ける。
+        // キャプチャ無しでも要素上の pointermove では追従する。
+        capturePointer(element, event.pointerId)
 
         trackDragStateRef.current = {
             pointerId: event.pointerId,
@@ -1374,19 +1364,17 @@ export const ScrollBar = ({
 
     /**
      * Handles pointer up interaction on the track.
+     * Releases the capture when held and ends the track drag.
      *
      * トラックドラッグ終了時の処理。
+     * キャプチャを保持していれば解放し、トラックドラッグを終える。
      */
     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)
-        }
+        releaseCapturedPointer(event.currentTarget, event.pointerId)
 
         resetTrackDragState()
 
@@ -1396,19 +1384,17 @@ export const ScrollBar = ({
 
     /**
      * Handles pointer cancel interaction on the track.
+     * Releases the capture when held and discards the track drag.
      *
      * トラックドラッグキャンセル時の処理。
+     * キャプチャを保持していれば解放し、トラックドラッグを破棄する。
      */
     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)
-        }
+        releaseCapturedPointer(event.currentTarget, event.pointerId)
 
         resetTrackDragState()
     }

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"
@@ -1133,11 +1134,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 +1198,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 +1215,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 +1263,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 +1359,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 +1423,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 +1585,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()

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)

package/src/pointerCapture.ts

@@ -0,0 +1,89 @@
+/**
+ * @module pointerCapture
+ * @description The single capability rule for the Pointer Capture API, shared by every pointer interaction in this package.
+ *
+ * @description 本パッケージのすべてのポインタ操作が共有する、Pointer Capture API の唯一の能力判定モジュール。
+ *
+ * `ScrollPane` (コンテンツのドラッグスクロール)・`ScrollBar` (サム / トラックのドラッグ)・
+ * `TapScrollCircle` (タップスクロールサークル) は、キャプチャの取得・解放・保持確認を
+ * 必ずここを通して行う。要素の `setPointerCapture` / `releasePointerCapture` /
+ * `hasPointerCapture` を直接呼んではならない。
+ *
+ * ❗ **3 つのメソッドが揃っている要素だけを「対応」とみなす。** jsdom (React のテストの既定環境) は
+ * このどれも実装しないため、直接呼ぶと利用側の `user.click` 1 回で `TypeError` になる。
+ * 一部だけを実装する環境で「取得はしたが解放も確認もできない」状態を作らないよう、判定は 1 本にしてある。
+ *
+ * 非対応の要素ではキャプチャ無しで操作を続ける (縮退)。コンテンツ領域とサムのドラッグは
+ * `window` / `document` のリスナーが追従を受け持つため動き続け、トラックとタップサークルは
+ * ポインタが要素上にある間だけ追従する。失われるのは、ウインドウ外や iframe 上で離したときの
+ * 終端イベントの受信と、`lostpointercapture` による強制解放の検知である。
+ */
+
+/**
+ * Outcome of a pointer capture request.
+ * ポインタキャプチャ要求の結果。
+ *
+ * - `"captured"`: The element now holds the capture. / 要素がキャプチャを保持した。
+ * - `"unsupported"`: The element does not implement the Pointer Capture API; nothing was attempted. / 要素が API を実装しておらず、要求自体を行っていない。
+ * - `"inactive-pointer"`: The UA rejected the pointer as inactive (`NotFoundError`). / ポインタが非アクティブとして拒否された (`NotFoundError`)。
+ * - `"rejected"`: The UA rejected the request for any other reason. / それ以外の理由で拒否された。
+ */
+export type PointerCaptureResult = "captured" | "unsupported" | "inactive-pointer" | "rejected"
+
+/**
+ * Reports whether the element implements the whole Pointer Capture API.
+ * 要素が Pointer Capture API (取得・解放・保持確認の 3 メソッド) をすべて実装しているかの判定処理。
+ *
+ * @param element The element to inspect. 判定対象の要素。
+ * @returns True when set / release / has are all callable. 3 メソッドがすべて呼び出し可能な場合に true。
+ */
+export const supportsPointerCapture = (element: Element): boolean => typeof element.setPointerCapture === "function" && typeof element.releasePointerCapture === "function" && typeof element.hasPointerCapture === "function"
+
+/**
+ * Reports whether the element holds (or has a pending) capture of the pointer.
+ * 要素が指定ポインタのキャプチャを保持 (または保留) しているかの判定処理。
+ *
+ * @param element The element to inspect. 判定対象の要素。
+ * @param pointerId The pointer to look up. 対象のポインタ ID。
+ * @returns True when the capture is held; always false when the API is unsupported. 保持している場合に true。API 非対応の要素では常に false。
+ */
+export const isPointerCaptured = (element: Element, pointerId: number): boolean => supportsPointerCapture(element) && element.hasPointerCapture(pointerId)
+
+/**
+ * Requests capture of the pointer for the element and classifies the outcome without throwing.
+ * 要素へ指定ポインタのキャプチャを要求し、例外を投げずに結果を分類する処理。
+ *
+ * @param element The element that should receive the capture. キャプチャを受け取る要素。
+ * @param pointerId The pointer to capture. キャプチャするポインタ ID。
+ * @returns The classified outcome of the request. 要求結果の分類。
+ */
+export const capturePointer = (element: Element, pointerId: number): PointerCaptureResult => {
+    if (!supportsPointerCapture(element)) {
+        return "unsupported"
+    }
+    try {
+        element.setPointerCapture(pointerId)
+        return "captured"
+    } catch (error) {
+        // クロスレルム (iframe への portal 等) では DOMException の instanceof が false になるため name で判定する
+        const errorName = typeof error === "object" && error !== null && "name" in error ? (error as { name?: unknown }).name : undefined
+        return errorName === "NotFoundError" ? "inactive-pointer" : "rejected"
+    }
+}
+
+/**
+ * Releases the element's capture of the pointer when it holds one; does nothing otherwise.
+ * 要素が指定ポインタのキャプチャを保持していれば解放し、保持していなければ何もしない処理。
+ *
+ * 呼び出し側が状態を確定させてから呼ぶこと。`lostpointercapture` を同期発火するブラウザでは、
+ * この呼び出しの最中に喪失ハンドラーが走る。
+ *
+ * @param element The element that may hold the capture. キャプチャを保持している可能性のある要素。
+ * @param pointerId The pointer to release. 解放するポインタ ID。
+ * @returns Nothing. なし。
+ */
+export const releaseCapturedPointer = (element: Element, pointerId: number): void => {
+    if (isPointerCaptured(element, pointerId)) {
+        element.releasePointerCapture(pointerId)
+    }
+}