@aiquants/virtualscroll 3.6.0 → 3.7.0

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

@@ -39,7 +39,7 @@ export type UseGridTapScrollParams = {
     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 — 素のハンドル素通しではない)。 */
     applyVy: (delta: number) => number;
-    /** Synchronous-fresh vy read. / vy の同期・最新読み。 */
+    /** 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;

package/dist/useGridTapScroll.d.ts

@@ -39,7 +39,7 @@ export type UseGridTapScrollParams = {
     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 — 素のハンドル素通しではない)。 */
     applyVy: (delta: number) => number;
-    /** Synchronous-fresh vy read. / vy の同期・最新読み。 */
+    /** 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;

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,gDAAgD;IAChD,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,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"}

package/package.json

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

package/src/ScrollBar.tsx

@@ -6,6 +6,7 @@
 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 { TapScrollCircle, type TapScrollCircleDragState, type TapScrollCircleHandle, type TapScrollCircleRenderProps } from "./TapScrollCircle.tsx"
 import { getAxisScale, minmax } from "./utils.ts"
@@ -21,7 +22,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 +193,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 +270,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 +282,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 +621,8 @@ export const ScrollBar = ({
     renderThumbOverlay,
     visibleStartIndex,
     visibleEndIndex,
+    locale,
+    labels,
 }: ScrollBarProps) => {
     const [isDragging, setIsDragging] = useState(false)
     const [isThumbHovered, setIsThumbHovered] = useState(false)
@@ -635,6 +650,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 +678,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

package/src/ScrollPane.tsx

@@ -1,5 +1,6 @@
 import { forwardRef, useCallback, useEffect, useId, useImperativeHandle, useLayoutEffect, useMemo, useRef, useState } from "react"
 import { twMerge } from "tailwind-merge"
+import type { VirtualScrollLabelOverrides, VirtualScrollLocale } from "./labels.ts"
 import { Logger } from "./logger.ts"
 import { ScrollBar, type ScrollBarTapCircleOptions, type ScrollBarThumbOverlayRenderProps, TAP_SCROLL_CANCEL_EVENT } from "./ScrollBar.tsx"
 import { getAxisScale, minmax } from "./utils.ts"
@@ -167,6 +168,20 @@ export type ScrollPaneProps = {
      * `className` / `style` / `ref` を表現できない型にしてあり、この口からレイアウトを壊せない。
      */
     contentProps?: React.AriaAttributes & { id?: string; role?: React.AriaRole }
+    /**
+     * UI chrome locale forwarded to the pane's ScrollBar (arrow aria-labels; default `"en"`).
+     * An unsupported value throws a RangeError at render.
+     * ペインの ScrollBar へ転送する UI クロームロケール (矢印の aria-label、既定 `"en"`)。
+     * 非対応値は描画時に RangeError。
+     */
+    locale?: VirtualScrollLocale
+    /**
+     * Per-key label overrides forwarded to the pane's ScrollBar, laid over the catalog of `locale`.
+     * Unknown keys and blank values throw a RangeError at render.
+     * ペインの ScrollBar へ転送するキー単位のラベル上書き (`locale` のカタログへ重ねる)。
+     * 未知キーと空白値は描画時に RangeError。
+     */
+    labels?: VirtualScrollLabelOverrides
 }
 
 export type ScrollPaneInertiaOptions = {
@@ -332,6 +347,8 @@ export const ScrollPane = forwardRef<ScrollPaneHandle, ScrollPaneProps>(
             renderOverlay,
             initialScrollPosition = 0,
             contentProps,
+            locale,
+            labels,
         },
         ref,
     ) => {
@@ -1638,6 +1655,8 @@ export const ScrollPane = forwardRef<ScrollPaneHandle, ScrollPaneProps>(
                     renderThumbOverlay={renderThumbOverlay}
                     visibleStartIndex={visibleStartIndex}
                     visibleEndIndex={visibleEndIndex}
+                    locale={locale}
+                    labels={labels}
                 />
                 {renderOverlay?.()}
             </div>

package/src/VirtualGrid.tsx

@@ -24,6 +24,7 @@
 import { type CSSProperties, forwardRef, type HTMLAttributes, type ReactNode, useCallback, useEffect, useImperativeHandle, useLayoutEffect, useMemo, useRef, useState } from "react"
 import { twMerge } from "tailwind-merge"
 import type { TapScrollAxisSpeedParams } from "./computeTapScrollVelocity.ts"
+import type { VirtualScrollLabelOverrides, VirtualScrollLocale } from "./labels.ts"
 import { Logger } from "./logger.ts"
 import { resolveTapScrollCircleOptions, ScrollBar, type ScrollBarTapCircleOptions } from "./ScrollBar.tsx"
 import type { ScrollPaneProps } from "./ScrollPane.tsx"
@@ -216,7 +217,7 @@ export type VirtualGridRange = {
     totalHeight: number
 }
 
-/** Live-region options: the consumer owns wording/locale (no built-in strings — row-parity). / liveRegion オプション: 文言とロケールは消費側所有 (内蔵文字列なし — 行側と同一方針)。 */
+/** Live-region options: the consumer owns announcement wording/locale; the built-in catalog (`locale` / `labels`) covers only the seven chrome strings (arrows, pills, empty state) — row-parity. / liveRegion オプション: 読み上げの文言とロケールは消費側所有。内蔵カタログ (`locale` / `labels`) はクローム 7 文言 (矢印・ピル・空状態) のみ対象 — 行側と同一方針。 */
 export type VirtualGridLiveRegionOptions = {
     /** Builds the announcement (same string = no re-announce, "" clears). / 読み上げ文言の組み立て (同一文字列 = 再読み上げなし、"" でクリア)。 */
     buildMessage: (range: VirtualGridRange) => string
@@ -392,6 +393,21 @@ export type VirtualGridProps<T> = {
     behaviorOptions?: VirtualGridBehaviorOptions
     scrollBarOptions?: VirtualScrollScrollBarOptions
     liveRegion?: VirtualGridLiveRegionOptions
+    /**
+     * UI chrome locale (default `"en"`), forwarded to the embedded vertical VirtualScroll (its
+     * arrows and the 0-row / all-frozen / degenerate-band empty state) and the horizontal bar
+     * arrows. An unsupported value throws a RangeError at render.
+     * UI クロームロケール (既定 `"en"`)。内蔵の縦 VirtualScroll (矢印と 0 行・全行固定・退化帯の
+     * 空状態) と横バーの矢印へ転送。非対応値は描画時に RangeError。
+     */
+    locale?: VirtualScrollLocale
+    /**
+     * Per-key label overrides laid over the catalog of `locale`, forwarded to the same two
+     * surfaces as `locale`. Unknown keys and blank values throw a RangeError at render.
+     * `locale` のカタログへ重ねるキー単位のラベル上書き (`locale` と同じ 2 面へ転送)。
+     * 未知キーと空白値は描画時に RangeError。
+     */
+    labels?: VirtualScrollLabelOverrides
     className?: string
     testId?: string
 }
@@ -749,6 +765,8 @@ const VirtualGridInner = <T,>(
         behaviorOptions,
         scrollBarOptions,
         liveRegion,
+        locale,
+        labels,
         className,
         testId,
     }: VirtualGridProps<T>,
@@ -1349,7 +1367,33 @@ const VirtualGridInner = <T,>(
         curve: resolvedTapY.maxSpeedCurve,
     }
     const getHx = useCallback(() => hxRef.current, [])
-    const getVy = useCallback(() => vyRef.current, [])
+    /**
+     * Fresh y position through the embedded handle — the SAME authority `applyVy`'s `scrollBy`
+     * resolves its updater against (the pane's internal position ref), symmetric with
+     * `getMaxVy`'s freshness channel and with the x side, where `getHx` reads the very cell
+     * `applyHx` writes. NEVER read `vyRef` here: that mirror has a second writer — the
+     * throttled `onScroll` relay (`handleVerticalScroll`) — which regresses it by up to the
+     * `callbackThrottleMs` window mid-drive; a driver base read from the mirror overstates
+     * `actualDelta` by the staleness gap, drives the axis residual negative, and the driver
+     * then issues REAL backward `scrollBy` writes (the 3.6.0 y-axis tap yo-yo — v3.6.1).
+     * 埋め込みハンドル経由の鮮度 y 位置 — `applyVy` の `scrollBy` が updater を解決するのと
+     * **同一の権威** (ペイン内部 ref)。`getMaxVy` の鮮度チャネル、および「`getHx` が `applyHx`
+     * の書き先セルそのものを読む」x 側と対称。ここで `vyRef` を読んではならない: あの鏡像には
+     * 第 2 の書き手 (スロットル済み `onScroll` 中継 = `handleVerticalScroll`) が居て、駆動中に
+     * 最大 `callbackThrottleMs` 窓ぶん巻き戻す。鏡像基準の `actualDelta` は staleness ギャップ
+     * ぶん過大になり、軸残差が負へ落ちて、ドライバ自身が**実後退**の `scrollBy` を発行する
+     * (3.6.0 の y 軸タップヨーヨー — v3.6.1)。
+     */
+    const getVy = useCallback(() => {
+        const inner = scrollHandleRef.current
+        if (inner === null) {
+            // ハンドル未接続時は applyVy と同じ「動かない」姿勢 — 同じ座標 (vyRef) を基準に返す
+            return vyRef.current
+        }
+        const position = inner.getScrollPosition()
+        // ペイン未接続の番兵 (-1) も applyVy の不動姿勢と同じ座標へ落とす (負位置は実在しない)
+        return position < 0 ? vyRef.current : position
+    }, [])
     /**
      * Fresh y extent through the embedded handle — the same freshness channel the vertical bar
      * uses (`contentSize − viewportSize` floored at 0). Never re-derived from grid-side trees.
@@ -1884,6 +1928,8 @@ const VirtualGridInner = <T,>(
                     onRangeChange={handleRangeChangeWithLive}
                     onWheelHorizontal={consumeHorizontalDelta}
                     onPanHorizontal={consumeHorizontalDelta}
+                    locale={locale}
+                    labels={labels}
                     testId={testId ? `${testId}-rows` : undefined}>
                     {renderRow}
                 </VirtualScroll>
@@ -1925,6 +1971,8 @@ const VirtualGridInner = <T,>(
                         return applyHxRef.current(typeof request === "function" ? request(previous ?? hxRef.current) : request)
                     }}
                     scrollBarWidth={scrollBarWidth}
+                    locale={locale}
+                    labels={labels}
                 />
             </div>
             {tapCircleEnabled && gridScrollable && (