@aiquants/virtualscroll 2.2.0 → 2.3.0

package/package.json

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

package/src/VirtualScroll.tsx

@@ -1723,9 +1723,27 @@ const VirtualScrollInner = <T,>(
     }, [contentSize, renderingEndIndex, renderingStartIndex, resolvedInsets.top, scheduleRangeEffect, scrollPosition, visibleEndIndex, visibleStartIndex])
 
     /**
-     * Produces visible item nodes and schedules height reconciliation.
+     * Renders the auto-hiding Top/Bottom pill overlay, neutralized while hidden.
      *
-     * 可視アイテムを描画しつつ高さとの差分更新を手配。
+     * 自動非表示の Top/Bottom ピルのオーバーレイを描画し、非表示中は無効化する処理。
+     *
+     * ❗ 非表示は `opacity: 0` で表現するため、要素は DOM に残り続ける (フェードのために
+     * アンマウントしない)。`opacity` はフォーカス可能性に影響せず、CSS の `pointer-events: none`
+     * はポインタ操作しか止めないため、無効化しないと**キーボード操作者は一覧を通過するたびに
+     * 「何も見えないのにフォーカスが止まる」箇所を必ず 1 つ踏む**。しかもフォーカスリング
+     * (`:focus-visible`) は `opacity: 0` の要素に描かれるため見えず、そこで Enter/Space を押すと
+     * 一覧が先頭または末尾へ飛ぶ (`pointer-events: none` はキーボードからの活性化を素通しする)。
+     *
+     * 無効化は焦点・支援技術・ポインタの 3 軸を 2 層で塞ぐ:
+     *
+     * 1. オーバーレイの `inert`: 焦点・ヒットテスト・アクセシビリティツリー露出を一括で外す
+     *    (この 1 属性が本質的な修正。React 19 は真偽値プロップとして扱い、false では属性を出さない)。
+     * 2. ピルの `tabIndex`: `inert` 未実装のブラウザ (Firefox 112 未満など) でもタブ順から外れる
+     *    ようにする下限。`inert` と同じ `isVisible` から導出するため両者が食い違うことはない。
+     *
+     * ポインタ軸の下限は CSS 側の `.aqvs-scroll-to-edge-overlay[data-visible="false"]
+     * .aqvs-scroll-to-edge-button { pointer-events: none }` が担う (配布 CSS 未読込のホストでは
+     * `inert` が、`inert` 未実装のブラウザでは CSS が、互いの穴を埋める)。
      */
     const renderOverlay = useCallback(() => {
         if (!enableScrollToTopBottomButtons) {
@@ -1736,12 +1754,14 @@ const VirtualScrollInner = <T,>(
         const isTop = scrollDirection === "up"
 
         return (
-            <div className="aqvs-scroll-to-edge-overlay" data-visible={isVisible}>
+            <div className="aqvs-scroll-to-edge-overlay" data-visible={isVisible} inert={!isVisible}>
                 {isTop ? (
                     <div className="aqvs-scroll-to-edge-button-container aqvs-scroll-to-edge-button-container-top">
                         <button
                             type="button"
                             className="aqvs-scroll-to-edge-button"
+                            // 非表示中はタブ順から外す (inert 未実装ブラウザ向けの下限)
+                            tabIndex={isVisible ? 0 : -1}
                             onClick={(e) => {
                                 e.stopPropagation()
                                 isProgrammaticScrollRef.current = true
@@ -1756,6 +1776,8 @@ const VirtualScrollInner = <T,>(
                         <button
                             type="button"
                             className="aqvs-scroll-to-edge-button"
+                            // 非表示中はタブ順から外す (inert 未実装ブラウザ向けの下限)
+                            tabIndex={isVisible ? 0 : -1}
                             onClick={(e) => {
                                 e.stopPropagation()
                                 isProgrammaticScrollRef.current = true