@aiquants/virtualscroll 3.9.1 → 3.10.0

package/src/labels.ts

@@ -1,14 +1,16 @@
 /**
  * @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
+ * @description Built-in UI chrome label catalog of the package. Covers exactly the eleven strings
+ * the components render on their own: the ScrollBar accessible names (per orientation, the two
+ * arrows, the `role="scrollbar"` bar and its `role="slider"` thumb), 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 の端スクロールピル文言、空状態文言) だけを対象とし、
+ * @description パッケージ内蔵の UI クローム文言カタログ。コンポーネント自身が描画する 11 文言
+ * (向きごとの ScrollBar のアクセシブルネーム — 矢印 2 個・`role="scrollbar"` のバー・その `role="slider"` の
+ * つまみ —、VirtualScroll の端スクロールピル文言、空状態文言) だけを対象とし、
  * ライブリージョンの文言は利用側の所有 (`liveRegion.format` / `liveRegion.buildMessage`) で
  * 本カタログの対象外。既定ロケールは `"en"`、第 2 ロケールは `"ja"`。言語ネゴシエーションは行わず、
  * `navigator.language` 等から対応ロケールへの対応付けはホスト側の責務。
@@ -53,6 +55,30 @@ export type VirtualScrollLabels = {
      * 横 ScrollBar 終端 (右) 矢印ボタンの aria-label。
      */
     readonly scrollRight: string
+    /**
+     * aria-label of the vertical ScrollBar root (`role="scrollbar"`). Assistive technology appends
+     * the role ("scroll bar") itself, so the name carries only what tells the two bars apart.
+     * 縦 ScrollBar のルート (`role="scrollbar"`) の aria-label。ロール名 (スクロールバー) は支援技術が
+     * 付け足すため、名前は 2 本のバーを区別する情報のみ。
+     */
+    readonly verticalScrollBar: string
+    /**
+     * aria-label of the horizontal ScrollBar root (`role="scrollbar"`).
+     * 横 ScrollBar のルート (`role="scrollbar"`) の aria-label。
+     */
+    readonly horizontalScrollBar: string
+    /**
+     * aria-label of the vertical ScrollBar thumb (`role="slider"`), whose value is the scroll
+     * position.
+     * 縦 ScrollBar のつまみ (`role="slider"`) の aria-label。値はスクロール位置。
+     */
+    readonly verticalScrollThumb: string
+    /**
+     * aria-label of the horizontal ScrollBar thumb (`role="slider"`), whose value is the scroll
+     * position.
+     * 横 ScrollBar のつまみ (`role="slider"`) の aria-label。値はスクロール位置。
+     */
+    readonly horizontalScrollThumb: string
     /**
      * Text of the VirtualScroll scroll-to-top pill, shown when
      * `scrollBarOptions.enableScrollToTopBottomButtons` is on.
@@ -87,15 +113,32 @@ export type VirtualScrollLabelOverrides = { readonly [K in keyof VirtualScrollLa
  * 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)[]
+export const VIRTUAL_SCROLL_LABEL_KEYS = [
+    "scrollUp",
+    "scrollDown",
+    "scrollLeft",
+    "scrollRight",
+    "verticalScrollBar",
+    "horizontalScrollBar",
+    "verticalScrollThumb",
+    "horizontalScrollThumb",
+    "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` はパッケージ従来の英語文言。
+ * Frozen built-in catalogs per locale. The arrow, pill and empty-state values of `en` are the
+ * package's historical English wording. The bar names state only the orientation, because
+ * assistive technology already reads the role as "scroll bar"; the thumb names state what the
+ * value measures.
+ * ロケールごとの凍結済み内蔵カタログ。`en` の矢印・ピル・空状態の値はパッケージ従来の英語文言。
+ * バーの名前は向きのみ (支援技術がロールを既に「スクロールバー」と読むため)、つまみの名前は値が
+ * 表すもの。
  */
 export const VIRTUAL_SCROLL_LABEL_CATALOGS: Readonly<Record<VirtualScrollLocale, VirtualScrollLabels>> = Object.freeze({
     en: Object.freeze({
@@ -103,6 +146,10 @@ export const VIRTUAL_SCROLL_LABEL_CATALOGS: Readonly<Record<VirtualScrollLocale,
         scrollDown: "Scroll down",
         scrollLeft: "Scroll left",
         scrollRight: "Scroll right",
+        verticalScrollBar: "Vertical",
+        horizontalScrollBar: "Horizontal",
+        verticalScrollThumb: "Vertical scroll position",
+        horizontalScrollThumb: "Horizontal scroll position",
         scrollToTop: "Top",
         scrollToBottom: "Bottom",
         noItems: "No items",
@@ -112,6 +159,10 @@ export const VIRTUAL_SCROLL_LABEL_CATALOGS: Readonly<Record<VirtualScrollLocale,
         scrollDown: "下へスクロール",
         scrollLeft: "左へスクロール",
         scrollRight: "右へスクロール",
+        verticalScrollBar: "縦方向",
+        horizontalScrollBar: "横方向",
+        verticalScrollThumb: "縦スクロール位置",
+        horizontalScrollThumb: "横スクロール位置",
         scrollToTop: "先頭へ",
         scrollToBottom: "末尾へ",
         noItems: "項目がありません",

package/src/styles/virtualscroll.css

@@ -329,6 +329,22 @@
   width: 100%;
 }
 
+/* 行ラッパーの包含ブロックで、配置の境界 (Chromium の relayout boundary)。窓をずらす 1 段が行を足し引きしても、配置はこの箱から
+ * 始まって箱の中で終わり、文書の根まで遡らない。境界になるには flex の子でも grid の子でもないことが要る (ペインの中身は flex の子
+ * なので、ラッパーの包含ブロックにしても境界にならない)。この箱は位置指定と、大きさと配置の封じ込めで境界になる。
+ * 箱はペインの中身のパディングの辺に付いて幅を合わせ、高さは 0 に固定する: 行は箱の外へはみ出して描かれ (描画は封じ込めないので、
+ * 切り取りはペインの中身の overflow: hidden のまま)、箱は当たり判定で背景 (background) の前に立たない。行のはみ出しは封じ込めで
+ * インクのはみ出しになるので、ペインの中身のスクロールできる範囲にも数えない。そのため、ブラウザが自分で行を見せるスクロール
+ * (オーバースキャンの行の中への Tab・ページ内検索) はペインの中身を動かせず、行の箱が外側のスクローラーの外にあればそちらを動かす */
+.aqvs-items-boundary {
+  position: absolute;
+  top: 0;
+  right: 0;
+  left: 0;
+  height: 0;
+  contain: size layout style;
+}
+
 .aqvs-items-wrapper {
   position: absolute;
   width: 100%;
@@ -547,15 +563,47 @@
   transition-timing-function: cubic-bezier(0.4, 0, 0.2, 1);
 }
 
-/* パッケージ全域・単一所有者 — 本 CSS 初の forced-colors 規則: グラデーション視覚は
- * forced-colors で平坦化され、輪郭なしではサークルが不可視になる (描画モード修正 —
- * 単体サークルにも輪郭が付くのは登記済みの挙動非変更デルタ)。 */
+/* 強制配色 (forced-colors: active) では、ブラウザがシステム色でない地色をどれも Canvas に置き換える (透明度は残す)。地色だけで
+ * 描く部品 (文字色も枠線も輪郭も持たない部品) は周りと区別できなくなるので、どれもここでシステム色の描き方を持つ
+ * (forcedColors.spec.tsx がこのファイルから地色だけで描く部品を導いて照合する)。
+ * - タップスクロールサークル: グラデーションの視覚は平坦になるので、輪郭で形を残す。
+ * - バーとトラック: 縁を GrayText の輪郭で描く (バーは矢印とトラックの下地、トラックはつまみが動く範囲)。
+ * - つまみ: ネイティブのスクロールバーと同じくシステム色で塗る。状態の規則 (ホバー・ドラッグ・無効) は同じ選択子でここに
+ *   言い直す: 詳細度が同じなので、後に置いたこちらが勝つ。forced-color-adjust: none はホストが塗ったシステム色でない地色を
+ *   Canvas へ消させない (つまみが溝と同じ色になって消えない)。
+ * - サンプルのビジュアルの光と棒: 引いた向きと量を示すので CanvasText で塗る。 */
 @media (forced-colors: active) {
   .aqvs-tap-scroll-circle {
     outline: 1px solid CanvasText;
     outline-offset: -1px;
     border-radius: 50%;
   }
+
+  .aqvs-scrollbar,
+  .aqvs-scrollbar-track {
+    outline: 1px solid GrayText;
+    outline-offset: -1px;
+  }
+
+  .aqvs-scrollbar-thumb {
+    forced-color-adjust: none;
+    background-color: CanvasText;
+  }
+
+  .aqvs-scrollbar-thumb[data-thumb-state="hover"],
+  .aqvs-scrollbar-thumb[data-thumb-state="dragging"] {
+    background-color: Highlight;
+  }
+
+  .aqvs-scrollbar-thumb[data-thumb-state="disabled"] {
+    background-color: GrayText;
+  }
+
+  .aqvs-sample-visual-highlight,
+  .aqvs-sample-visual-rod {
+    forced-color-adjust: none;
+    background-color: CanvasText;
+  }
 }
 
 /* 動きを減らす設定 (prefers-reduced-motion: reduce) では、パッケージが動かす部品はどれも遷移もアニメーションも持たず、

package/src/utils.ts

@@ -56,3 +56,18 @@ export const getAxisScale = (element: HTMLElement, axis: "x" | "y"): number => {
     }
     return visualSize / layoutSize
 }
+
+/**
+ * Pointer-down handler of pointer-only scroll chrome (the scrollbar and the scroll-to-edge pills of a host that scrolls by
+ * keyboard itself): cancels the press's default action, so the press never moves focus — neither onto a part of the chrome
+ * nor away from where the host put it — while the press itself, its pointer events and its click still reach the part.
+ *
+ * ポインタ専用のスクロールの部品 (キーボードのスクロールを自分で持つホストのスクロールバーと端へ戻るピル) の pointerdown の
+ * 処理。押下の既定動作を取り消すので、押下はフォーカスを動かさない — 部品の上へも、ホストが置いた場所の外へも — が、押下
+ * そのもの (ポインタのイベントと click) は部品へ届く。
+ *
+ * @param event - The pointer-down event (only its default action is read) / pointerdown のイベント (既定動作だけを扱う)
+ */
+export const keepFocusOnPress = (event: { readonly preventDefault: () => void }): void => {
+    event.preventDefault()
+}