@aiquants/virtualscroll 3.7.0 → 3.8.0

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/dist/useGridTapScroll.d.cts

@@ -2,7 +2,7 @@ import { TapScrollAxisSpeedParams } from './computeTapScrollVelocity.cjs';
 import { TapScrollCircleDragState, TapScrollCircleHandle } from './TapScrollCircle.cjs';
 /**
  * Default corner-relative offset (px) for BOTH grid tap-circle axes — the reachability arm (R)
- * of the three-arm placement law (plan §5). Derivation: full speed needs
+ * of the three-arm placement law. Derivation: full speed needs
  * `maxVisualDistance = 240 px` of advancing pull toward the far screen edge, which is a hard
  * stop on touch (`touch-action: none`). With `off = −200` the disc center sits
  * `sbw − off − size/2 = 12 + 200 − 20 = 192 px` inboard of each far root edge, giving a
@@ -12,11 +12,11 @@ import { TapScrollCircleDragState, TapScrollCircleHandle } from './TapScrollCirc
  * nav-zone envelope ≥ ~2/3. Deliberately a LITERAL: it must NOT track a consumer-supplied
  * `maxVisualDistance` (coupling two knobs would make one silently move the other), and
  * shrinking `maxVisualDistance` instead is forbidden (it changes the speed law's `maxDistance`
- * input and breaks the T1 identity anchor).
+ * input, so a pure-axis drag would no longer reproduce the bar's own speed law).
  * グリッドタップサークル両軸のコーナー相対既定オフセット (px) — 3 アーム配置則の到達性アーム
  * (R)。導出: 全速には前進方向へ 240 px の引きが要り、タッチではスクリーン端がハードストップ。
  * −200 で中心は各遠端から 192 px 内側 = 最悪ケース引き分率 0.80 (ナビ帯込み 0.66)。意図的な
- * リテラル — 消費側 `maxVisualDistance` へ連動させない (ノブ連動の登記済み禁止)。
+ * リテラル — 消費側 `maxVisualDistance` へ連動させない (2 つのノブを連動させると一方が他方を黙って動かす)。
  */
 export declare const GRID_TAP_CIRCLE_DEFAULT_OFFSET = -200;
 /** Parameters for `useGridTapScroll` (read live through a params ref — identity-stability is not required of callers). / `useGridTapScroll` のパラメータ (params ref 経由で毎フレーム最新を読む — 呼出し側に identity 安定を要求しない)。 */
@@ -25,9 +25,9 @@ export type UseGridTapScrollParams = {
     enabled: boolean;
     /** Shared pull range (= `max(maxVisualDistance, 1)`). / 共有引き範囲 (= `max(maxVisualDistance, 1)`)。 */
     maxDistance: number;
-    /** Horizontal speed parameters (§4.1 Pₓ). / 横軸速度パラメータ (§4.1 Pₓ)。 */
+    /** Horizontal speed parameters (Pₓ, built from the scroll-band width and the column count). / 横軸速度パラメータ (Pₓ。スクロール帯幅と列数から構成)。 */
     xSpeedParams: TapScrollAxisSpeedParams;
-    /** Vertical speed parameters (§4.1 P_y). / 縦軸速度パラメータ (§4.1 P_y)。 */
+    /** Vertical speed parameters (P_y, built from the embedded pane height and the scroll-row count). / 縦軸速度パラメータ (P_y。埋め込みペイン高とスクロール行数から構成)。 */
     ySpeedParams: TapScrollAxisSpeedParams;
     /** The grid's x apply seam (absolute position in, clamped applied position out). / グリッドの x 適用シーム (絶対位置 → クランプ後位置)。 */
     applyHxRef: {
@@ -35,21 +35,21 @@ export type UseGridTapScrollParams = {
     };
     /** Synchronous-fresh hx read. / hx の同期・最新読み。 */
     getHx: () => number;
-    /** The ONE extracted x clamp law (`getMaxHx` SSOT — §3.5-7). / 唯一抽出の x クランプ則 (`getMaxHx` SSOT — §3.5-7)。 */
+    /** The ONE extracted x clamp law (`getMaxHx` SSOT — never re-derived from the grid's tree). / 唯一抽出の x クランプ則 (`getMaxHx` SSOT — グリッドの木から再導出しない)。 */
     getMaxHx: () => number;
-    /** y apply seam: wraps `scrollBy(delta)` AND syncs `vyRef.current = applied` before returning (§3.5-8 — NOT a bare handle passthrough). / y 適用シーム: `scrollBy(delta)` をラップし `vyRef.current = applied` を同期してから返す (§3.5-8 — 素のハンドル素通しではない)。 */
+    /** y apply seam: wraps `scrollBy(delta)` AND syncs `vyRef.current = applied` before returning (NOT a bare handle passthrough — without the sync, x-frame notifications during a diagonal drag carry a stale y). / y 適用シーム: `scrollBy(delta)` をラップし `vyRef.current = applied` を同期してから返す (素のハンドル素通しではない — 同期が無いと対角ドラッグ中の x フレーム通知が stale な y を運ぶ)。 */
     applyVy: (delta: number) => number;
     /** Synchronous-fresh vy read — MUST read the same authority `applyVy` resolves against (the embedded pane's position), never a notification mirror with a second writer (v3.6.1 — a lagging mirror base overstates `actualDelta` and drives the residual negative = yo-yo). / vy の同期・最新読み — `applyVy` が解決するのと同一権威 (埋め込みペイン位置) を読むこと。第 2 の書き手を持つ通知鏡像は禁止 (v3.6.1 — 遅延鏡像基準は `actualDelta` を過大化し残差を負へ落とすヨーヨー)。 */
     getVy: () => number;
     /** y extent read through the embedded handle's freshness channel (never re-derived). / 埋め込みハンドルの鮮度チャネル経由の y 延長 (再導出禁止)。 */
     getMaxVy: () => number;
-    /** Pending column anchor — cleared ONLY on frames whose APPLIED hx delta ≠ 0 (§3.5-5). / 保留列アンカー — 適用済み hx デルタ ≠ 0 のフレームのみ解除 (§3.5-5)。 */
+    /** Pending column anchor — cleared ONLY on frames whose APPLIED hx delta ≠ 0 (a request the clamp swallows keeps it). / 保留列アンカー — 適用済み hx デルタ ≠ 0 のフレームのみ解除 (クランプに吸収された要求では残す)。 */
     pendingColAnchorRef: {
         current: unknown;
     };
-    /** x extent-growth freshness key (columnWindow / total width — §3.5-3). / x 延長成長の鮮度キー (columnWindow / 総幅 — §3.5-3)。 */
+    /** x extent-growth freshness key (columnWindow / total width — a change re-arms a loop parked at the edge). / x 延長成長の鮮度キー (columnWindow / 総幅 — 変化で端に止まったループを再武装)。 */
     xExtentFreshness: unknown;
-    /** y extent-growth freshness key (the vertical range state — §3.5-3). / y 延長成長の鮮度キー (縦レンジ state — §3.5-3)。 */
+    /** y extent-growth freshness key (the vertical range state — a change re-arms a loop parked at the edge). / y 延長成長の鮮度キー (縦レンジ state — 変化で端に止まったループを再武装)。 */
     yExtentFreshness: unknown;
 };
 /** Result of `useGridTapScroll`. / `useGridTapScroll` の返り値。 */
@@ -65,7 +65,7 @@ export type UseGridTapScrollResult = {
  * Owns the unified tap circle's drag state and the two-axis rAF integration loop.
  * 統合タップサークルのドラッグ状態と 2 軸 rAF 積分ループを所有するフック。
  *
- * Per-frame semantics (plan §8.3 — implemented verbatim):
+ * Per-frame semantics:
  *
  * ```text
  * dt = min(max((t − last)/1000, 0), TAP_SCROLL_MAX_FRAME_DELTA_SECONDS); skip if dt ≤ 0

package/dist/useGridTapScroll.d.ts

@@ -2,7 +2,7 @@ import { TapScrollAxisSpeedParams } from './computeTapScrollVelocity.ts';
 import { TapScrollCircleDragState, TapScrollCircleHandle } from './TapScrollCircle.tsx';
 /**
  * Default corner-relative offset (px) for BOTH grid tap-circle axes — the reachability arm (R)
- * of the three-arm placement law (plan §5). Derivation: full speed needs
+ * of the three-arm placement law. Derivation: full speed needs
  * `maxVisualDistance = 240 px` of advancing pull toward the far screen edge, which is a hard
  * stop on touch (`touch-action: none`). With `off = −200` the disc center sits
  * `sbw − off − size/2 = 12 + 200 − 20 = 192 px` inboard of each far root edge, giving a
@@ -12,11 +12,11 @@ import { TapScrollCircleDragState, TapScrollCircleHandle } from './TapScrollCirc
  * nav-zone envelope ≥ ~2/3. Deliberately a LITERAL: it must NOT track a consumer-supplied
  * `maxVisualDistance` (coupling two knobs would make one silently move the other), and
  * shrinking `maxVisualDistance` instead is forbidden (it changes the speed law's `maxDistance`
- * input and breaks the T1 identity anchor).
+ * input, so a pure-axis drag would no longer reproduce the bar's own speed law).
  * グリッドタップサークル両軸のコーナー相対既定オフセット (px) — 3 アーム配置則の到達性アーム
  * (R)。導出: 全速には前進方向へ 240 px の引きが要り、タッチではスクリーン端がハードストップ。
  * −200 で中心は各遠端から 192 px 内側 = 最悪ケース引き分率 0.80 (ナビ帯込み 0.66)。意図的な
- * リテラル — 消費側 `maxVisualDistance` へ連動させない (ノブ連動の登記済み禁止)。
+ * リテラル — 消費側 `maxVisualDistance` へ連動させない (2 つのノブを連動させると一方が他方を黙って動かす)。
  */
 export declare const GRID_TAP_CIRCLE_DEFAULT_OFFSET = -200;
 /** Parameters for `useGridTapScroll` (read live through a params ref — identity-stability is not required of callers). / `useGridTapScroll` のパラメータ (params ref 経由で毎フレーム最新を読む — 呼出し側に identity 安定を要求しない)。 */
@@ -25,9 +25,9 @@ export type UseGridTapScrollParams = {
     enabled: boolean;
     /** Shared pull range (= `max(maxVisualDistance, 1)`). / 共有引き範囲 (= `max(maxVisualDistance, 1)`)。 */
     maxDistance: number;
-    /** Horizontal speed parameters (§4.1 Pₓ). / 横軸速度パラメータ (§4.1 Pₓ)。 */
+    /** Horizontal speed parameters (Pₓ, built from the scroll-band width and the column count). / 横軸速度パラメータ (Pₓ。スクロール帯幅と列数から構成)。 */
     xSpeedParams: TapScrollAxisSpeedParams;
-    /** Vertical speed parameters (§4.1 P_y). / 縦軸速度パラメータ (§4.1 P_y)。 */
+    /** Vertical speed parameters (P_y, built from the embedded pane height and the scroll-row count). / 縦軸速度パラメータ (P_y。埋め込みペイン高とスクロール行数から構成)。 */
     ySpeedParams: TapScrollAxisSpeedParams;
     /** The grid's x apply seam (absolute position in, clamped applied position out). / グリッドの x 適用シーム (絶対位置 → クランプ後位置)。 */
     applyHxRef: {
@@ -35,21 +35,21 @@ export type UseGridTapScrollParams = {
     };
     /** Synchronous-fresh hx read. / hx の同期・最新読み。 */
     getHx: () => number;
-    /** The ONE extracted x clamp law (`getMaxHx` SSOT — §3.5-7). / 唯一抽出の x クランプ則 (`getMaxHx` SSOT — §3.5-7)。 */
+    /** The ONE extracted x clamp law (`getMaxHx` SSOT — never re-derived from the grid's tree). / 唯一抽出の x クランプ則 (`getMaxHx` SSOT — グリッドの木から再導出しない)。 */
     getMaxHx: () => number;
-    /** y apply seam: wraps `scrollBy(delta)` AND syncs `vyRef.current = applied` before returning (§3.5-8 — NOT a bare handle passthrough). / y 適用シーム: `scrollBy(delta)` をラップし `vyRef.current = applied` を同期してから返す (§3.5-8 — 素のハンドル素通しではない)。 */
+    /** y apply seam: wraps `scrollBy(delta)` AND syncs `vyRef.current = applied` before returning (NOT a bare handle passthrough — without the sync, x-frame notifications during a diagonal drag carry a stale y). / y 適用シーム: `scrollBy(delta)` をラップし `vyRef.current = applied` を同期してから返す (素のハンドル素通しではない — 同期が無いと対角ドラッグ中の x フレーム通知が stale な y を運ぶ)。 */
     applyVy: (delta: number) => number;
     /** Synchronous-fresh vy read — MUST read the same authority `applyVy` resolves against (the embedded pane's position), never a notification mirror with a second writer (v3.6.1 — a lagging mirror base overstates `actualDelta` and drives the residual negative = yo-yo). / vy の同期・最新読み — `applyVy` が解決するのと同一権威 (埋め込みペイン位置) を読むこと。第 2 の書き手を持つ通知鏡像は禁止 (v3.6.1 — 遅延鏡像基準は `actualDelta` を過大化し残差を負へ落とすヨーヨー)。 */
     getVy: () => number;
     /** y extent read through the embedded handle's freshness channel (never re-derived). / 埋め込みハンドルの鮮度チャネル経由の y 延長 (再導出禁止)。 */
     getMaxVy: () => number;
-    /** Pending column anchor — cleared ONLY on frames whose APPLIED hx delta ≠ 0 (§3.5-5). / 保留列アンカー — 適用済み hx デルタ ≠ 0 のフレームのみ解除 (§3.5-5)。 */
+    /** Pending column anchor — cleared ONLY on frames whose APPLIED hx delta ≠ 0 (a request the clamp swallows keeps it). / 保留列アンカー — 適用済み hx デルタ ≠ 0 のフレームのみ解除 (クランプに吸収された要求では残す)。 */
     pendingColAnchorRef: {
         current: unknown;
     };
-    /** x extent-growth freshness key (columnWindow / total width — §3.5-3). / x 延長成長の鮮度キー (columnWindow / 総幅 — §3.5-3)。 */
+    /** x extent-growth freshness key (columnWindow / total width — a change re-arms a loop parked at the edge). / x 延長成長の鮮度キー (columnWindow / 総幅 — 変化で端に止まったループを再武装)。 */
     xExtentFreshness: unknown;
-    /** y extent-growth freshness key (the vertical range state — §3.5-3). / y 延長成長の鮮度キー (縦レンジ state — §3.5-3)。 */
+    /** y extent-growth freshness key (the vertical range state — a change re-arms a loop parked at the edge). / y 延長成長の鮮度キー (縦レンジ state — 変化で端に止まったループを再武装)。 */
     yExtentFreshness: unknown;
 };
 /** Result of `useGridTapScroll`. / `useGridTapScroll` の返り値。 */
@@ -65,7 +65,7 @@ export type UseGridTapScrollResult = {
  * Owns the unified tap circle's drag state and the two-axis rAF integration loop.
  * 統合タップサークルのドラッグ状態と 2 軸 rAF 積分ループを所有するフック。
  *
- * Per-frame semantics (plan §8.3 — implemented verbatim):
+ * Per-frame semantics:
  *
  * ```text
  * dt = min(max((t − last)/1000, 0), TAP_SCROLL_MAX_FRAME_DELTA_SECONDS); skip if dt ≤ 0

package/dist/useGridTapScroll.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useGridTapScroll.d.ts","sourceRoot":"","sources":["../src/useGridTapScroll.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,EAA4B,KAAK,wBAAwB,EAAE,MAAM,+BAA+B,CAAA;AAEvG,OAAO,KAAK,EAAE,wBAAwB,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAA;AAG5F;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,8BAA8B,OAAO,CAAA;AAalD,4MAA4M;AAC5M,MAAM,MAAM,sBAAsB,GAAG;IACjC,uIAAuI;IACvI,OAAO,EAAE,OAAO,CAAA;IAChB,mGAAmG;IACnG,WAAW,EAAE,MAAM,CAAA;IACnB,oEAAoE;IACpE,YAAY,EAAE,wBAAwB,CAAA;IACtC,oEAAoE;IACpE,YAAY,EAAE,wBAAwB,CAAA;IACtC,sHAAsH;IACtH,UAAU,EAAE;QAAE,QAAQ,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAA;KAAE,CAAA;IAC1D,gDAAgD;IAChD,KAAK,EAAE,MAAM,MAAM,CAAA;IACnB,4GAA4G;IAC5G,QAAQ,EAAE,MAAM,MAAM,CAAA;IACtB,4OAA4O;IAC5O,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAA;IAClC,8YAA8Y;IAC9Y,KAAK,EAAE,MAAM,MAAM,CAAA;IACnB,2HAA2H;IAC3H,QAAQ,EAAE,MAAM,MAAM,CAAA;IACtB,0IAA0I;IAC1I,mBAAmB,EAAE;QAAE,OAAO,EAAE,OAAO,CAAA;KAAE,CAAA;IACzC,uHAAuH;IACvH,gBAAgB,EAAE,OAAO,CAAA;IACzB,8GAA8G;IAC9G,gBAAgB,EAAE,OAAO,CAAA;CAC5B,CAAA;AAED,+DAA+D;AAC/D,MAAM,MAAM,sBAAsB,GAAG;IACjC,4FAA4F;IAC5F,WAAW,EAAE,OAAO,CAAA;IACpB,qGAAqG;IACrG,yBAAyB,EAAE,CAAC,KAAK,EAAE,wBAAwB,KAAK,IAAI,CAAA;IACpE,4HAA4H;IAC5H,kBAAkB,EAAE,KAAK,CAAC,SAAS,CAAC,qBAAqB,GAAG,IAAI,CAAC,CAAA;CACpE,CAAA;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,gBAAgB,GAAI,QAAQ,sBAAsB,KAAG,sBAuQjE,CAAA"}
+{"version":3,"file":"useGridTapScroll.d.ts","sourceRoot":"","sources":["../src/useGridTapScroll.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,EAA4B,KAAK,wBAAwB,EAAE,MAAM,+BAA+B,CAAA;AAEvG,OAAO,KAAK,EAAE,wBAAwB,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAA;AAG5F;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,8BAA8B,OAAO,CAAA;AAalD,4MAA4M;AAC5M,MAAM,MAAM,sBAAsB,GAAG;IACjC,uIAAuI;IACvI,OAAO,EAAE,OAAO,CAAA;IAChB,mGAAmG;IACnG,WAAW,EAAE,MAAM,CAAA;IACnB,gIAAgI;IAChI,YAAY,EAAE,wBAAwB,CAAA;IACtC,6IAA6I;IAC7I,YAAY,EAAE,wBAAwB,CAAA;IACtC,sHAAsH;IACtH,UAAU,EAAE;QAAE,QAAQ,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAA;KAAE,CAAA;IAC1D,gDAAgD;IAChD,KAAK,EAAE,MAAM,MAAM,CAAA;IACnB,mJAAmJ;IACnJ,QAAQ,EAAE,MAAM,MAAM,CAAA;IACtB,oVAAoV;IACpV,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAA;IAClC,8YAA8Y;IAC9Y,KAAK,EAAE,MAAM,MAAM,CAAA;IACnB,2HAA2H;IAC3H,QAAQ,EAAE,MAAM,MAAM,CAAA;IACtB,mLAAmL;IACnL,mBAAmB,EAAE;QAAE,OAAO,EAAE,OAAO,CAAA;KAAE,CAAA;IACzC,qKAAqK;IACrK,gBAAgB,EAAE,OAAO,CAAA;IACzB,4JAA4J;IAC5J,gBAAgB,EAAE,OAAO,CAAA;CAC5B,CAAA;AAED,+DAA+D;AAC/D,MAAM,MAAM,sBAAsB,GAAG;IACjC,4FAA4F;IAC5F,WAAW,EAAE,OAAO,CAAA;IACpB,qGAAqG;IACrG,yBAAyB,EAAE,CAAC,KAAK,EAAE,wBAAwB,KAAK,IAAI,CAAA;IACpE,4HAA4H;IAC5H,kBAAkB,EAAE,KAAK,CAAC,SAAS,CAAC,qBAAqB,GAAG,IAAI,CAAC,CAAA;CACpE,CAAA;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,gBAAgB,GAAI,QAAQ,sBAAsB,KAAG,sBAuQjE,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiquants/virtualscroll",
-  "version": "3.7.0",
+  "version": "3.8.0",
   "description": "High-performance virtual scrolling component for React with variable item heights",
   "sideEffects": [
     "**/*.css"
@@ -107,8 +107,8 @@
     "license-check": "pnpm dlx license-checker --production --onlyAllow \"MIT;Apache-2.0;BSD-2-Clause;BSD-3-Clause;ISC;Unlicense\"",
     "license-check:json": "pnpm dlx license-checker --production --onlyAllow \"MIT;Apache-2.0;BSD-2-Clause;BSD-3-Clause;ISC;Unlicense\" --json",
     "clean": "rimraf dist",
-    "publish:patch": "pnpm run typecheck && pnpm run --if-present test && pnpm version patch --no-git-tag-version --no-git-checks && pnpm publish --no-git-checks",
-    "publish:minor": "pnpm run typecheck && pnpm run --if-present test && pnpm version minor --no-git-tag-version --no-git-checks && pnpm publish --no-git-checks",
-    "publish:major": "pnpm run typecheck && pnpm run --if-present test && pnpm version major --no-git-tag-version --no-git-checks && pnpm publish --no-git-checks"
+    "publish:patch": "pnpm run typecheck && pnpm run --if-present test && node ../../.config/scripts/check-publish-leaks.mjs && pnpm version patch --no-git-tag-version --no-git-checks && pnpm publish --no-git-checks",
+    "publish:minor": "pnpm run typecheck && pnpm run --if-present test && node ../../.config/scripts/check-publish-leaks.mjs && pnpm version minor --no-git-tag-version --no-git-checks && pnpm publish --no-git-checks",
+    "publish:major": "pnpm run typecheck && pnpm run --if-present test && node ../../.config/scripts/check-publish-leaks.mjs && pnpm version major --no-git-tag-version --no-git-checks && pnpm publish --no-git-checks"
   }
 }

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"
 
@@ -159,6 +160,40 @@ export type ScrollBarProps = {
     enableTrackClick?: boolean
     /** Whether arrow buttons control the scroll position. / 矢印ボタンによるスクロール操作を許可するかどうか。 */
     enableArrowButtons?: boolean
+    /**
+     * Whether the two arrow buttons are Tab stops (default `true`).
+     *
+     * `false` renders both with `tabIndex={-1}`, which takes them out of the sequential focus order
+     * and changes nothing else: pointer presses and press-and-hold repeat, the accessible names and
+     * Enter / Space on an arrow focused from script all keep working. The arrows are descendants of
+     * the `role="scrollbar"` root, whose children ARIA 1.2 makes presentational, so whether assistive
+     * technology lists them as buttons of their own is the browser's choice (Chromium does); this
+     * option changes nothing about that. Set it to `false` when the host already owns keyboard
+     * scrolling of this viewport (roving row focus with Arrow / Page / Home / End, a grid keyboard
+     * model): the arrows then duplicate that path and cost every keyboard user two extra Tab presses
+     * per bar — native scrollbars are never Tab stops either. The default stays `true` because
+     * without such a host model the arrows are the only scrolling control a keyboard user can reach
+     * with Tab: `ScrollPane` / `VirtualScroll` move their content by transform, so there is no native
+     * scroller the browser could make focusable, and their rows are not Tab stops. No effect while
+     * the arrows are disabled (`enableArrowButtons: false`, or nothing to scroll) — a disabled button
+     * is never focusable.
+     *
+     * 矢印ボタン 2 個を Tab の止まり先にするかどうか (既定 `true`)。
+     *
+     * `false` は両方を `tabIndex={-1}` で描画し、順次フォーカス移動の順序から外すだけの指定。
+     * ポインタ押下と長押しリピート、アクセシブルネーム、スクリプトからフォーカスした矢印での
+     * Enter / Space はすべて維持。矢印は `role="scrollbar"` のルートの子孫で、ARIA 1.2 はその子を
+     * presentational とするため、支援技術が矢印を独立したボタンとして示すかどうかはブラウザの選択
+     * (Chromium は示す) であり、本オプションはそこに関与しない。ホストがこのビューポートのキーボード
+     * スクロールを既に持つ場合 (行のロービングフォーカスと矢印 / Page / Home / End、グリッドのキーボードモデル) に
+     * `false` を指定 — 矢印はその経路の重複となり、キーボード利用者にバー 1 本あたり 2 回の余分な Tab を
+     * 課すため (ネイティブのスクロールバーも Tab の止まり先にならない)。既定を `true` に据え置く理由は、
+     * ホスト側のモデルが無ければ矢印がキーボード利用者の Tab で届く唯一のスクロール操作部品であること
+     * (`ScrollPane` / `VirtualScroll` はコンテンツを transform で動かすため、ブラウザがフォーカス可能に
+     * できるネイティブのスクロール領域が無く、行も Tab の止まり先ではない)。矢印が無効な間
+     * (`enableArrowButtons: false` またはスクロール不要) は効果なし — disabled のボタンはそもそもフォーカス不能。
+     */
+    enableArrowButtonTabStops?: boolean
     /** Whether the scrollbar is horizontal. / スクロールバーが水平かどうか。 */
     horizontal?: boolean
     /**
@@ -610,6 +645,7 @@ export const ScrollBar = ({
     enableThumbDrag = true,
     enableTrackClick = true,
     enableArrowButtons = true,
+    enableArrowButtonTabStops = true,
     horizontal = false,
     enableHorizontalTapCircle = false,
     stretchMainSize = false,
@@ -859,7 +895,7 @@ export const ScrollBar = ({
      */
     const stepAutoScroll = useCallback(
         (timestamp: number) => {
-            // この rAF ループ意味論は useGridTapScroll (グリッド 2 軸ドライバ) と双子 — 片方を直したらもう片方も直すこと (ADR-27)
+            // この rAF ループ意味論は useGridTapScroll (グリッド 2 軸ドライバ) と双子 — 片方を直したらもう片方も直すこと
             const state = tapDragStateRef.current
             const metrics = latestMetricsRef.current
             if (!state.active || state.direction === 0) {
@@ -1136,10 +1172,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 +1188,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 +1262,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 +1284,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 +1311,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 +1342,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 +1399,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 +1419,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()
     }
@@ -1450,18 +1471,25 @@ export const ScrollBar = ({
     }, [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.
+     * Renders one arrow button of the bar. It is a Tab stop (`tabIndex=0`) unless the host opted out
+     * with `enableArrowButtonTabStops={false}` (`tabIndex=-1`); either way it stays focusable from
+     * script, pointer-operable and named, and Enter / Space scrolls one step while it has focus.
+     *
+     * バーの矢印ボタン 1 個の描画。ホストが `enableArrowButtonTabStops={false}` で外さない限り Tab の
+     * 止まり先 (`tabIndex=0`)、外した場合は `tabIndex=-1`。いずれの場合もスクリプトからのフォーカス・
+     * ポインタ操作・アクセシブルネームは維持し、フォーカス中の Enter / Space で 1 ステップ移動。
      *
-     * スクロールバー制御用矢印ボタンを描画。キーボードで Enter/Space ハンドラへ
-     * 到達できるよう tabIndex=0 でタブ順序に残す。
+     * @param direction - Step direction (-1 = toward the start, 1 = toward the end) / ステップ方向 (-1 = 始端側、1 = 終端側)
+     * @param label - Accessible name / アクセシブルネーム
+     * @param icon - Decorative glyph, hidden from assistive technology / 支援技術から隠す装飾グリフ
+     * @param key - React key / React キー
+     * @returns The arrow button element / 矢印ボタン要素
      */
     const renderArrowButton = (direction: 1 | -1, label: string, icon: string, key: string) => (
         <button
             key={key}
             type="button"
-            tabIndex={0}
+            tabIndex={enableArrowButtonTabStops ? 0 : -1}
             className="aqvs-scrollbar-arrow-button"
             style={{
                 [mainSizeKey]: scrollBarWidth,