@aiquants/virtualscroll 3.6.1 → 3.7.1

package/dist/labels.d.cts

@@ -0,0 +1,125 @@
+/**
+ * @module labels
+ * @description Built-in UI chrome label catalog of the package. Covers exactly the seven strings
+ * the components render on their own: the ScrollBar arrow aria-labels, the VirtualScroll
+ * scroll-to-edge pill texts and the empty-state text. Live-region wording stays consumer-owned
+ * (`liveRegion.format` / `liveRegion.buildMessage`) and is not part of this catalog. The default
+ * locale is `"en"`; `"ja"` is the second locale. No language negotiation happens here: hosts map
+ * `navigator.language` (or anything else) to a supported locale themselves.
+ *
+ * @description パッケージ内蔵の UI クローム文言カタログ。コンポーネント自身が描画する 7 文言
+ * (ScrollBar 矢印の aria-label、VirtualScroll の端スクロールピル文言、空状態文言) だけを対象とし、
+ * ライブリージョンの文言は利用側の所有 (`liveRegion.format` / `liveRegion.buildMessage`) で
+ * 本カタログの対象外。既定ロケールは `"en"`、第 2 ロケールは `"ja"`。言語ネゴシエーションは行わず、
+ * `navigator.language` 等から対応ロケールへの対応付けはホスト側の責務。
+ */
+/**
+ * Supported UI chrome locales, in declaration order. The first entry is NOT implicitly the
+ * default — the default lives only in {@link resolveVirtualScrollLocale}.
+ * 対応する UI クロームロケールの一覧 (宣言順)。先頭要素が暗黙の既定値になるわけではなく、
+ * 既定値は {@link resolveVirtualScrollLocale} にのみ存在。
+ */
+export declare const VIRTUAL_SCROLL_LOCALES: readonly ["en", "ja"];
+/**
+ * A supported UI chrome locale (`"en"` | `"ja"`).
+ * 対応 UI クロームロケール (`"en"` | `"ja"`)。
+ */
+export type VirtualScrollLocale = (typeof VIRTUAL_SCROLL_LOCALES)[number];
+/**
+ * The complete set of built-in chrome strings, one value per rendered surface.
+ * 内蔵クローム文言の完全な集合 (描画面ごとに 1 値)。
+ */
+export type VirtualScrollLabels = {
+    /**
+     * aria-label of the vertical ScrollBar start (up) arrow button.
+     * 縦 ScrollBar 始端 (上) 矢印ボタンの aria-label。
+     */
+    readonly scrollUp: string;
+    /**
+     * aria-label of the vertical ScrollBar end (down) arrow button.
+     * 縦 ScrollBar 終端 (下) 矢印ボタンの aria-label。
+     */
+    readonly scrollDown: string;
+    /**
+     * aria-label of the horizontal ScrollBar start (left) arrow button.
+     * 横 ScrollBar 始端 (左) 矢印ボタンの aria-label。
+     */
+    readonly scrollLeft: string;
+    /**
+     * aria-label of the horizontal ScrollBar end (right) arrow button.
+     * 横 ScrollBar 終端 (右) 矢印ボタンの aria-label。
+     */
+    readonly scrollRight: string;
+    /**
+     * Text of the VirtualScroll scroll-to-top pill, shown when
+     * `scrollBarOptions.enableScrollToTopBottomButtons` is on.
+     * `scrollBarOptions.enableScrollToTopBottomButtons` 有効時に表示される VirtualScroll 先頭移動ピルの文言。
+     */
+    readonly scrollToTop: string;
+    /**
+     * Text of the VirtualScroll scroll-to-bottom pill, shown when
+     * `scrollBarOptions.enableScrollToTopBottomButtons` is on.
+     * `scrollBarOptions.enableScrollToTopBottomButtons` 有効時に表示される VirtualScroll 末尾移動ピルの文言。
+     */
+    readonly scrollToBottom: string;
+    /**
+     * VirtualScroll empty-state text shown when `itemCount === 0`. VirtualGrid shows it too, for
+     * 0 rows, an all-frozen row set and degenerate bands (its embedded VirtualScroll gets 0 items).
+     * `itemCount === 0` 時の VirtualScroll 空状態文言。VirtualGrid も 0 行・全行固定・退化帯で表示
+     * (内蔵 VirtualScroll の項目数が 0 になるため)。
+     */
+    readonly noItems: string;
+};
+/**
+ * Partial per-key overrides laid over the catalog of the chosen locale. An `undefined` value keeps
+ * the catalog value; any present value must be a string with non-whitespace content.
+ * 選択ロケールのカタログへ重ねるキー単位の部分上書き。`undefined` 値はカタログ値を維持し、
+ * 値を与える場合は空白以外の文字を含む文字列であることが必須。
+ */
+export type VirtualScrollLabelOverrides = {
+    readonly [K in keyof VirtualScrollLabels]?: VirtualScrollLabels[K];
+};
+/**
+ * Every key of {@link VirtualScrollLabels}, in catalog order. This is the closed key set that
+ * overrides are validated against.
+ * {@link VirtualScrollLabels} の全キー (カタログ順)。上書き検証に用いる閉じたキー集合。
+ */
+export declare const VIRTUAL_SCROLL_LABEL_KEYS: readonly ["scrollUp", "scrollDown", "scrollLeft", "scrollRight", "scrollToTop", "scrollToBottom", "noItems"];
+/**
+ * Frozen built-in catalogs per locale. `en` is the package's historical English wording.
+ * ロケールごとの凍結済み内蔵カタログ。`en` はパッケージ従来の英語文言。
+ */
+export declare const VIRTUAL_SCROLL_LABEL_CATALOGS: Readonly<Record<VirtualScrollLocale, VirtualScrollLabels>>;
+/**
+ * Resolves the UI chrome locale. `undefined` (an absent prop) maps to the default `"en"`; a member
+ * of {@link VIRTUAL_SCROLL_LOCALES} is returned as-is. This is the single place the default lives.
+ * UI クロームロケールの解決。`undefined` (prop 未指定) は既定の `"en"`、
+ * {@link VIRTUAL_SCROLL_LOCALES} の要素はそのまま返却。既定値を持つ唯一の場所。
+ *
+ * @param locale - Requested locale, or `undefined` for the default / 要求ロケール (`undefined` で既定)
+ * @returns The resolved supported locale / 解決済みの対応ロケール
+ * @throws {RangeError} When `locale` is neither `undefined` nor a supported locale (`null`, `""`,
+ * `"EN"`, `"ja-JP"`, `"fr"`, numbers, ...) — no language negotiation /
+ * `undefined` でも対応ロケールでもない場合 (`null`、`""`、`"EN"`、`"ja-JP"`、`"fr"`、数値など)。言語ネゴシエーションなし
+ */
+export declare const resolveVirtualScrollLocale: (locale: VirtualScrollLocale | undefined) => VirtualScrollLocale;
+/**
+ * Resolves the effective labels: the catalog of the resolved locale overlaid by `overrides`.
+ * Returns the frozen catalog itself (same identity) when `overrides` is `undefined`, otherwise a
+ * new frozen object. Inputs are never mutated.
+ * 実効ラベルの解決。解決済みロケールのカタログへ `overrides` を重ねた結果。`overrides` が
+ * `undefined` なら凍結カタログそのもの (同一参照)、それ以外は新しい凍結オブジェクトを返却。入力は不変。
+ *
+ * @param locale - Requested locale, or `undefined` for the default / 要求ロケール (`undefined` で既定)
+ * @param overrides - Per-key overrides, or `undefined` for none / キー単位の上書き (`undefined` で上書きなし)
+ * @returns The resolved, frozen labels / 解決済みの凍結ラベル
+ * @throws {RangeError} When the locale is unsupported, `overrides` is `null` or not an object,
+ * `overrides` is not a plain object (its prototype is neither `Object.prototype` nor `null`, e.g.
+ * an array or a class instance), an own key is not a label key, or a present own value is not a
+ * string with non-whitespace content. Only own properties are read /
+ * ロケールが非対応、`overrides` が `null` または非オブジェクト、`overrides` が素のオブジェクトでない
+ * (プロトタイプが `Object.prototype` でも `null` でもない。配列やクラスインスタンスなど)、自身のキーが
+ * ラベルキー外、または与えられた自身の値が空白以外の文字を含む文字列でない場合。読むのは自身の
+ * プロパティのみ
+ */
+export declare const resolveVirtualScrollLabels: (locale: VirtualScrollLocale | undefined, overrides: VirtualScrollLabelOverrides | undefined) => VirtualScrollLabels;

package/dist/labels.d.ts

@@ -0,0 +1,126 @@
+/**
+ * @module labels
+ * @description Built-in UI chrome label catalog of the package. Covers exactly the seven strings
+ * the components render on their own: the ScrollBar arrow aria-labels, the VirtualScroll
+ * scroll-to-edge pill texts and the empty-state text. Live-region wording stays consumer-owned
+ * (`liveRegion.format` / `liveRegion.buildMessage`) and is not part of this catalog. The default
+ * locale is `"en"`; `"ja"` is the second locale. No language negotiation happens here: hosts map
+ * `navigator.language` (or anything else) to a supported locale themselves.
+ *
+ * @description パッケージ内蔵の UI クローム文言カタログ。コンポーネント自身が描画する 7 文言
+ * (ScrollBar 矢印の aria-label、VirtualScroll の端スクロールピル文言、空状態文言) だけを対象とし、
+ * ライブリージョンの文言は利用側の所有 (`liveRegion.format` / `liveRegion.buildMessage`) で
+ * 本カタログの対象外。既定ロケールは `"en"`、第 2 ロケールは `"ja"`。言語ネゴシエーションは行わず、
+ * `navigator.language` 等から対応ロケールへの対応付けはホスト側の責務。
+ */
+/**
+ * Supported UI chrome locales, in declaration order. The first entry is NOT implicitly the
+ * default — the default lives only in {@link resolveVirtualScrollLocale}.
+ * 対応する UI クロームロケールの一覧 (宣言順)。先頭要素が暗黙の既定値になるわけではなく、
+ * 既定値は {@link resolveVirtualScrollLocale} にのみ存在。
+ */
+export declare const VIRTUAL_SCROLL_LOCALES: readonly ["en", "ja"];
+/**
+ * A supported UI chrome locale (`"en"` | `"ja"`).
+ * 対応 UI クロームロケール (`"en"` | `"ja"`)。
+ */
+export type VirtualScrollLocale = (typeof VIRTUAL_SCROLL_LOCALES)[number];
+/**
+ * The complete set of built-in chrome strings, one value per rendered surface.
+ * 内蔵クローム文言の完全な集合 (描画面ごとに 1 値)。
+ */
+export type VirtualScrollLabels = {
+    /**
+     * aria-label of the vertical ScrollBar start (up) arrow button.
+     * 縦 ScrollBar 始端 (上) 矢印ボタンの aria-label。
+     */
+    readonly scrollUp: string;
+    /**
+     * aria-label of the vertical ScrollBar end (down) arrow button.
+     * 縦 ScrollBar 終端 (下) 矢印ボタンの aria-label。
+     */
+    readonly scrollDown: string;
+    /**
+     * aria-label of the horizontal ScrollBar start (left) arrow button.
+     * 横 ScrollBar 始端 (左) 矢印ボタンの aria-label。
+     */
+    readonly scrollLeft: string;
+    /**
+     * aria-label of the horizontal ScrollBar end (right) arrow button.
+     * 横 ScrollBar 終端 (右) 矢印ボタンの aria-label。
+     */
+    readonly scrollRight: string;
+    /**
+     * Text of the VirtualScroll scroll-to-top pill, shown when
+     * `scrollBarOptions.enableScrollToTopBottomButtons` is on.
+     * `scrollBarOptions.enableScrollToTopBottomButtons` 有効時に表示される VirtualScroll 先頭移動ピルの文言。
+     */
+    readonly scrollToTop: string;
+    /**
+     * Text of the VirtualScroll scroll-to-bottom pill, shown when
+     * `scrollBarOptions.enableScrollToTopBottomButtons` is on.
+     * `scrollBarOptions.enableScrollToTopBottomButtons` 有効時に表示される VirtualScroll 末尾移動ピルの文言。
+     */
+    readonly scrollToBottom: string;
+    /**
+     * VirtualScroll empty-state text shown when `itemCount === 0`. VirtualGrid shows it too, for
+     * 0 rows, an all-frozen row set and degenerate bands (its embedded VirtualScroll gets 0 items).
+     * `itemCount === 0` 時の VirtualScroll 空状態文言。VirtualGrid も 0 行・全行固定・退化帯で表示
+     * (内蔵 VirtualScroll の項目数が 0 になるため)。
+     */
+    readonly noItems: string;
+};
+/**
+ * Partial per-key overrides laid over the catalog of the chosen locale. An `undefined` value keeps
+ * the catalog value; any present value must be a string with non-whitespace content.
+ * 選択ロケールのカタログへ重ねるキー単位の部分上書き。`undefined` 値はカタログ値を維持し、
+ * 値を与える場合は空白以外の文字を含む文字列であることが必須。
+ */
+export type VirtualScrollLabelOverrides = {
+    readonly [K in keyof VirtualScrollLabels]?: VirtualScrollLabels[K];
+};
+/**
+ * Every key of {@link VirtualScrollLabels}, in catalog order. This is the closed key set that
+ * overrides are validated against.
+ * {@link VirtualScrollLabels} の全キー (カタログ順)。上書き検証に用いる閉じたキー集合。
+ */
+export declare const VIRTUAL_SCROLL_LABEL_KEYS: readonly ["scrollUp", "scrollDown", "scrollLeft", "scrollRight", "scrollToTop", "scrollToBottom", "noItems"];
+/**
+ * Frozen built-in catalogs per locale. `en` is the package's historical English wording.
+ * ロケールごとの凍結済み内蔵カタログ。`en` はパッケージ従来の英語文言。
+ */
+export declare const VIRTUAL_SCROLL_LABEL_CATALOGS: Readonly<Record<VirtualScrollLocale, VirtualScrollLabels>>;
+/**
+ * Resolves the UI chrome locale. `undefined` (an absent prop) maps to the default `"en"`; a member
+ * of {@link VIRTUAL_SCROLL_LOCALES} is returned as-is. This is the single place the default lives.
+ * UI クロームロケールの解決。`undefined` (prop 未指定) は既定の `"en"`、
+ * {@link VIRTUAL_SCROLL_LOCALES} の要素はそのまま返却。既定値を持つ唯一の場所。
+ *
+ * @param locale - Requested locale, or `undefined` for the default / 要求ロケール (`undefined` で既定)
+ * @returns The resolved supported locale / 解決済みの対応ロケール
+ * @throws {RangeError} When `locale` is neither `undefined` nor a supported locale (`null`, `""`,
+ * `"EN"`, `"ja-JP"`, `"fr"`, numbers, ...) — no language negotiation /
+ * `undefined` でも対応ロケールでもない場合 (`null`、`""`、`"EN"`、`"ja-JP"`、`"fr"`、数値など)。言語ネゴシエーションなし
+ */
+export declare const resolveVirtualScrollLocale: (locale: VirtualScrollLocale | undefined) => VirtualScrollLocale;
+/**
+ * Resolves the effective labels: the catalog of the resolved locale overlaid by `overrides`.
+ * Returns the frozen catalog itself (same identity) when `overrides` is `undefined`, otherwise a
+ * new frozen object. Inputs are never mutated.
+ * 実効ラベルの解決。解決済みロケールのカタログへ `overrides` を重ねた結果。`overrides` が
+ * `undefined` なら凍結カタログそのもの (同一参照)、それ以外は新しい凍結オブジェクトを返却。入力は不変。
+ *
+ * @param locale - Requested locale, or `undefined` for the default / 要求ロケール (`undefined` で既定)
+ * @param overrides - Per-key overrides, or `undefined` for none / キー単位の上書き (`undefined` で上書きなし)
+ * @returns The resolved, frozen labels / 解決済みの凍結ラベル
+ * @throws {RangeError} When the locale is unsupported, `overrides` is `null` or not an object,
+ * `overrides` is not a plain object (its prototype is neither `Object.prototype` nor `null`, e.g.
+ * an array or a class instance), an own key is not a label key, or a present own value is not a
+ * string with non-whitespace content. Only own properties are read /
+ * ロケールが非対応、`overrides` が `null` または非オブジェクト、`overrides` が素のオブジェクトでない
+ * (プロトタイプが `Object.prototype` でも `null` でもない。配列やクラスインスタンスなど)、自身のキーが
+ * ラベルキー外、または与えられた自身の値が空白以外の文字を含む文字列でない場合。読むのは自身の
+ * プロパティのみ
+ */
+export declare const resolveVirtualScrollLabels: (locale: VirtualScrollLocale | undefined, overrides: VirtualScrollLabelOverrides | undefined) => VirtualScrollLabels;
+//# sourceMappingURL=labels.d.ts.map

package/dist/labels.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"labels.d.ts","sourceRoot":"","sources":["../src/labels.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,uBAAwB,CAAA;AAE3D;;;GAGG;AACH,MAAM,MAAM,mBAAmB,GAAG,CAAC,OAAO,sBAAsB,CAAC,CAAC,MAAM,CAAC,CAAA;AAEzE;;;GAGG;AACH,MAAM,MAAM,mBAAmB,GAAG;IAC9B;;;OAGG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB;;;OAGG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B;;;OAGG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B;;;OAGG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B;;;;OAIG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B;;;;OAIG;IACH,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAA;IAC/B;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAC3B,CAAA;AAED;;;;;GAKG;AACH,MAAM,MAAM,2BAA2B,GAAG;IAAE,QAAQ,EAAE,CAAC,IAAI,MAAM,mBAAmB,CAAC,CAAC,EAAE,mBAAmB,CAAC,CAAC,CAAC;CAAE,CAAA;AAEhH;;;;GAIG;AACH,eAAO,MAAM,yBAAyB,8GAAgK,CAAA;AAMtM;;;GAGG;AACH,eAAO,MAAM,6BAA6B,EAAE,QAAQ,CAAC,MAAM,CAAC,mBAAmB,EAAE,mBAAmB,CAAC,CAmBnG,CAAA;AAiCF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,0BAA0B,GAAI,QAAQ,mBAAmB,GAAG,SAAS,KAAG,mBASpF,CAAA;AAWD;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,0BAA0B,GAAI,QAAQ,mBAAmB,GAAG,SAAS,EAAE,WAAW,2BAA2B,GAAG,SAAS,KAAG,mBAiCxI,CAAA"}

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.6.1",
+  "version": "3.7.1",
   "description": "High-performance virtual scrolling component for React with variable item heights",
   "sideEffects": [
     "**/*.css"

package/src/ScrollBar.tsx

@@ -6,7 +6,9 @@
 import type { CSSProperties, ReactNode } from "react"
 import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState } from "react"
 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"
 
@@ -21,7 +23,6 @@ type OrientationConfig = {
     positionKey: "left" | "top"
     selectDelta: (deltaX: number, deltaY: number) => number
     getPointerCoordinate: (point: { clientX: number; clientY: number }) => number
-    arrowLabels: [string, string]
     arrowIcons: [string, string]
     directionClass: string
     orientation: "vertical" | "horizontal"
@@ -193,6 +194,21 @@ export type ScrollBarProps = {
     visibleStartIndex?: number
     /** The index of the last visible item. / 最後の可視アイテムのインデックス。 */
     visibleEndIndex?: number
+    /**
+     * UI chrome locale of the built-in arrow aria-labels (default `"en"`). An unsupported value
+     * throws a RangeError at render; no language negotiation happens.
+     * 内蔵矢印 aria-label の UI クロームロケール (既定 `"en"`)。非対応値は描画時に RangeError、
+     * 言語ネゴシエーションなし。
+     */
+    locale?: VirtualScrollLocale
+    /**
+     * Per-key overrides laid over the catalog of `locale`. This bar reads `scrollUp` / `scrollDown`
+     * (vertical) or `scrollLeft` / `scrollRight` (horizontal); unknown keys and blank values throw a
+     * RangeError at render.
+     * `locale` のカタログへ重ねるキー単位の上書き。本バーが読むのは縦なら `scrollUp` / `scrollDown`、
+     * 横なら `scrollLeft` / `scrollRight`。未知キーと空白値は描画時に RangeError。
+     */
+    labels?: VirtualScrollLabelOverrides
 }
 
 /** The minimum size of the scrollbar thumb. / スクロールバーのつまみの最小サイズ。 */
@@ -255,7 +271,6 @@ const createOrientationConfig = (horizontal: boolean): OrientationConfig => {
             positionKey: "left",
             selectDelta: (deltaX: number, _deltaY: number) => deltaX,
             getPointerCoordinate: ({ clientX }) => clientX,
-            arrowLabels: ["Scroll left", "Scroll right"],
             arrowIcons: ["◀", "▶"],
             directionClass: "aqvs-scrollbar-horizontal",
             orientation: "horizontal",
@@ -268,7 +283,6 @@ const createOrientationConfig = (horizontal: boolean): OrientationConfig => {
         positionKey: "top",
         selectDelta: (_deltaX: number, deltaY: number) => deltaY,
         getPointerCoordinate: ({ clientY }) => clientY,
-        arrowLabels: ["Scroll up", "Scroll down"],
         arrowIcons: ["▲", "▼"],
         directionClass: "aqvs-scrollbar-vertical",
         orientation: "vertical",
@@ -608,6 +622,8 @@ export const ScrollBar = ({
     renderThumbOverlay,
     visibleStartIndex,
     visibleEndIndex,
+    locale,
+    labels,
 }: ScrollBarProps) => {
     const [isDragging, setIsDragging] = useState(false)
     const [isThumbHovered, setIsThumbHovered] = useState(false)
@@ -635,6 +651,8 @@ export const ScrollBar = ({
     const autoScrollDirectionRef = useRef<0 | 1 | -1>(0)
     const resolvedTapScrollOptions = useMemo<ResolvedTapScrollCircleOptions>(() => resolveTapScrollCircleOptions(tapScrollCircleOptions, itemCount), [itemCount, tapScrollCircleOptions])
     const orientationConfig = useMemo(() => createOrientationConfig(horizontal), [horizontal])
+    const resolvedLabels = useMemo(() => resolveVirtualScrollLabels(locale, labels), [locale, labels])
+    const arrowLabels = horizontal ? ([resolvedLabels.scrollLeft, resolvedLabels.scrollRight] as const) : ([resolvedLabels.scrollUp, resolvedLabels.scrollDown] as const)
     const {
         enabled: tapCircleEnabled,
         size: tapCircleSize,
@@ -661,7 +679,7 @@ export const ScrollBar = ({
         onScroll,
         scrollPosition,
     })
-    const { mainSizeKey, crossSizeKey, positionKey, selectDelta, getPointerCoordinate, arrowLabels, arrowIcons, directionClass, orientation } = orientationConfig
+    const { mainSizeKey, crossSizeKey, positionKey, selectDelta, getPointerCoordinate, arrowIcons, directionClass, orientation } = orientationConfig
     const effectiveTapMaxDistance = Math.max(tapCircleMaxDistance, 1)
     // 表示領域に対するコンテンツの比率
     const scrollRatio = viewportSize / contentSize
@@ -1119,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) => {
@@ -1135,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 }
@@ -1210,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) {
@@ -1230,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,
@@ -1265,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) {
@@ -1294,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,
@@ -1357,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()
 
@@ -1379,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()
     }