@aiquants/virtualscroll 3.6.1 → 3.7.1

package/src/labels.ts

@@ -0,0 +1,236 @@
+/**
+ * @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 const VIRTUAL_SCROLL_LOCALES = ["en", "ja"] as const
+
+/**
+ * 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 const VIRTUAL_SCROLL_LABEL_KEYS = ["scrollUp", "scrollDown", "scrollLeft", "scrollRight", "scrollToTop", "scrollToBottom", "noItems"] as const satisfies readonly (keyof VirtualScrollLabels)[]
+
+// satisfies は部分集合しか保証しないため、キー追加時の登録漏れを型で検出する
+const keysCoverEveryLabel: [Exclude<keyof VirtualScrollLabels, (typeof VIRTUAL_SCROLL_LABEL_KEYS)[number]>] extends [never] ? true : never = true
+void keysCoverEveryLabel
+
+/**
+ * Frozen built-in catalogs per locale. `en` is the package's historical English wording.
+ * ロケールごとの凍結済み内蔵カタログ。`en` はパッケージ従来の英語文言。
+ */
+export const VIRTUAL_SCROLL_LABEL_CATALOGS: Readonly<Record<VirtualScrollLocale, VirtualScrollLabels>> = Object.freeze({
+    en: Object.freeze({
+        scrollUp: "Scroll up",
+        scrollDown: "Scroll down",
+        scrollLeft: "Scroll left",
+        scrollRight: "Scroll right",
+        scrollToTop: "Top",
+        scrollToBottom: "Bottom",
+        noItems: "No items",
+    }),
+    ja: Object.freeze({
+        scrollUp: "上へスクロール",
+        scrollDown: "下へスクロール",
+        scrollLeft: "左へスクロール",
+        scrollRight: "右へスクロール",
+        scrollToTop: "先頭へ",
+        scrollToBottom: "末尾へ",
+        noItems: "項目がありません",
+    }),
+})
+
+/**
+ * Type guard: whether `value` is a member of {@link VIRTUAL_SCROLL_LOCALES}.
+ * `value` が {@link VIRTUAL_SCROLL_LOCALES} の要素かどうかの型ガード。
+ *
+ * @param value - Candidate value / 判定対象の値
+ * @returns `true` when `value` is a supported locale / 対応ロケールなら `true`
+ */
+const isVirtualScrollLocale = (value: unknown): value is VirtualScrollLocale => (VIRTUAL_SCROLL_LOCALES as readonly unknown[]).includes(value)
+
+/**
+ * Describes a rejected input for an error message without ever throwing: JSON for strings,
+ * `"null"` for `null`, otherwise the `typeof` tag. Never calls `String()` / `JSON.stringify` on
+ * arbitrary values, so BigInt, Symbol and null-prototype inputs still produce the documented
+ * RangeError with an accurate description.
+ * 拒否した入力をエラーメッセージ用に説明 (例外を投げない)。文字列は JSON 表記、`null` は `"null"`、
+ * それ以外は `typeof` のタグ。任意値へ `String()` / `JSON.stringify` を適用しないため、BigInt・Symbol・
+ * null プロトタイプの入力でも文書どおりの RangeError と正確な説明を維持。
+ *
+ * @param value - Rejected input / 拒否した入力
+ * @returns A short, non-throwing description of `value` / `value` の短い説明 (例外なし)
+ */
+const describeRejectedValue = (value: unknown): string => {
+    if (typeof value === "string") {
+        return JSON.stringify(value)
+    }
+    if (value === null) {
+        return "null"
+    }
+    return typeof value
+}
+
+/**
+ * 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 const resolveVirtualScrollLocale = (locale: VirtualScrollLocale | undefined): VirtualScrollLocale => {
+    if (locale === undefined) {
+        return "en"
+    }
+    if (isVirtualScrollLocale(locale)) {
+        return locale
+    }
+    const allowed = VIRTUAL_SCROLL_LOCALES.map((candidate) => JSON.stringify(candidate)).join(", ")
+    throw new RangeError(`[virtualscroll] locale must be one of ${allowed}; got ${describeRejectedValue(locale)}`)
+}
+
+/**
+ * Type guard: whether `key` is a member of {@link VIRTUAL_SCROLL_LABEL_KEYS}.
+ * `key` が {@link VIRTUAL_SCROLL_LABEL_KEYS} の要素かどうかの型ガード。
+ *
+ * @param key - Candidate own key of an overrides object / 上書きオブジェクトの自身のキー候補
+ * @returns `true` when `key` is a label key / ラベルキーなら `true`
+ */
+const isVirtualScrollLabelKey = (key: string): key is keyof VirtualScrollLabels => (VIRTUAL_SCROLL_LABEL_KEYS as readonly string[]).includes(key)
+
+/**
+ * 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 const resolveVirtualScrollLabels = (locale: VirtualScrollLocale | undefined, overrides: VirtualScrollLabelOverrides | undefined): VirtualScrollLabels => {
+    const catalog = VIRTUAL_SCROLL_LABEL_CATALOGS[resolveVirtualScrollLocale(locale)]
+    if (overrides === undefined) {
+        return catalog
+    }
+    if (overrides === null || typeof overrides !== "object") {
+        throw new RangeError(`[virtualscroll] labels must be an object; got ${describeRejectedValue(overrides)}`)
+    }
+    // 既知キー検査は自身のキーしか見ないため、継承経路を持つ入力 (配列・クラスインスタンス・
+    // 他オブジェクト継承) を許すと継承側の綴り誤りが無言で無視される
+    const prototype: unknown = Object.getPrototypeOf(overrides)
+    if (prototype !== Object.prototype && prototype !== null) {
+        throw new RangeError(`[virtualscroll] labels must be a plain object (prototype Object.prototype or null); got ${Array.isArray(overrides) ? "an array" : "an object with a non-plain prototype"}`)
+    }
+    const ownKeys = new Set(Object.keys(overrides))
+    for (const key of ownKeys) {
+        if (!isVirtualScrollLabelKey(key)) {
+            throw new RangeError(`[virtualscroll] labels.${key} is not a known label key; expected one of ${VIRTUAL_SCROLL_LABEL_KEYS.join(", ")}`)
+        }
+    }
+    const resolved: Record<keyof VirtualScrollLabels, string> = { ...catalog }
+    for (const key of VIRTUAL_SCROLL_LABEL_KEYS) {
+        // 検査したのと同じ自身のキー集合だけを読み、Object.prototype 汚染で継承されたラベルキーを拾わない
+        const value: unknown = ownKeys.has(key) ? overrides[key] : undefined
+        if (value === undefined) {
+            continue
+        }
+        if (typeof value !== "string" || value.trim() === "") {
+            throw new RangeError(`[virtualscroll] labels.${key} must be a non-blank string; got ${describeRejectedValue(value)}`)
+        }
+        resolved[key] = value
+    }
+    return Object.freeze(resolved)
+}

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)
+    }
+}