@aiquants/virtualscroll 3.11.2 → 3.11.3

package/package.json

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

package/src/VirtualScroll.tsx

@@ -241,7 +241,12 @@ export type VirtualScrollScrollBarOptions = {
     enableArrowButtonTabStops?: boolean
     /**
      * Whether to show the auto-hiding Top / Bottom pills (default `false`; texts from `labels.scrollToTop` / `labels.scrollToBottom`).
+     * A user scroll shows the pill of the edge it moves toward, or the other edge's pill once the pane rests at that edge; a pill
+     * shows only while the pane can still scroll toward its edge, so it hides as soon as the pane comes to rest there, and a pane
+     * that cannot scroll shows neither.
      * 自動で隠れる Top / Bottom ピルを表示するかどうか (既定 `false`。文言は `labels.scrollToTop` / `labels.scrollToBottom`)。
+     * 利用者のスクロールは向かう端のピルを出し、ペインがその端に着いていれば反対の端のピルを出す。ピルはペインがまだその端の方へ
+     * スクロールできる間だけ見えるので、ペインがその端に着くとすぐ隠れ、スクロールできないペインはどちらも出さない。
      */
     enableScrollToTopBottomButtons?: boolean
     /** Renderer for UI anchored near the thumb. / つまみ付近に重ねる UI のレンダラー。 */
@@ -722,6 +727,54 @@ const edgeOfAlignment = (align: "top" | "bottom" | "center" | undefined): Aligne
  */
 const canonicalAlignedEdge = (alignment: AlignedEdge | null): AlignedEdge | null => (alignment !== null && alignment.panePosition <= 0 ? null : alignment)
 
+/**
+ * The edge a scroll-to-edge pill scrolls to: `"top"` (the Top pill, to the first row) or `"bottom"` (the Bottom pill, to the
+ * last row).
+ *
+ * 端へ戻るピルが送る先の端。`"top"` (Top ピル。最初の行へ) か `"bottom"` (Bottom ピル。最後の行へ)。
+ */
+type EdgePill = "top" | "bottom"
+
+/** How long a pill stays after the user scroll that showed it, unless the pane comes to rest at its edge first (ms) / ピルを出した利用者のスクロールからピルが消えるまでの時間 (ms。先にペインがその端に着けばそこで消える) */
+const EDGE_PILL_HIDE_DELAY_MS = 2000
+
+/**
+ * Whether the pane can still scroll toward an edge: toward the top while its position exceeds 0, toward the bottom while
+ * its position stays under the max scroll position, each by more than `EDGE_POSITION_TOLERANCE` (closer counts as resting
+ * at that edge). A pane that cannot scroll (max scroll position 0) can scroll toward neither edge.
+ *
+ * ペインがまだその端の方へスクロールできるかの判定。上端へは位置が 0 を上回り、下端へは位置が最大位置を下回り、どちらも
+ * `EDGE_POSITION_TOLERANCE` を超えて離れている間だけ (それより近ければその端に着いている)。スクロールできないペイン
+ * (最大位置 0) はどちらの端へもスクロールできない。
+ *
+ * @param edge - The edge / 端
+ * @param panePosition - Pane position (px) / ペイン位置 (px)
+ * @param maxScrollPosition - The pane's max scroll position (px) / ペインの最大位置 (px)
+ * @returns True while the pane can scroll toward the edge / その端の方へスクロールできる間は true
+ */
+const canScrollTowardEdge = (edge: EdgePill, panePosition: number, maxScrollPosition: number): boolean => (edge === "top" ? panePosition > EDGE_POSITION_TOLERANCE : panePosition < maxScrollPosition - EDGE_POSITION_TOLERANCE)
+
+/**
+ * Picks the pill a user scroll shows: the pill of the edge the scroll moves toward while the pane can still scroll toward
+ * that edge; once the pane rests at that edge, the pill of the other edge; and no pill when the pane can scroll toward
+ * neither edge.
+ *
+ * 利用者のスクロールが出すピルを選ぶ処理。スクロールが向かう端の方へまだスクロールできる間はその端のピル、ペインがその端に
+ * 着いたら反対の端のピル、どちらの端へもスクロールできなければピル無し。
+ *
+ * @param toward - The edge the scroll moves toward / スクロールが向かう端
+ * @param panePosition - Pane position after the scroll (px) / スクロール後のペイン位置 (px)
+ * @param maxScrollPosition - The pane's max scroll position (px) / ペインの最大位置 (px)
+ * @returns The pill to show, or `null` for none / 出すピル (無ければ `null`)
+ */
+const pickEdgePill = (toward: EdgePill, panePosition: number, maxScrollPosition: number): EdgePill | null => {
+    if (canScrollTowardEdge(toward, panePosition, maxScrollPosition)) {
+        return toward
+    }
+    const opposite: EdgePill = toward === "top" ? "bottom" : "top"
+    return canScrollTowardEdge(opposite, panePosition, maxScrollPosition) ? opposite : null
+}
+
 /**
  * The parts of the viewport that something drawn over the rows covers — the visible scroll-to-edge pill — as px from each
  * edge to the far side of what covers it. Module-level export (NOT in the package barrel), the parameter type of
@@ -1727,9 +1780,51 @@ const VirtualScrollInner = <T,>(
     const pendingFocusIndexRef = useRef<number | null>(null)
     const lastFocusedIndexRef = useRef<number | null>(null)
 
-    const [scrollDirection, setScrollDirection] = useState<"up" | "down" | null>(null)
+    // スクロールの向きではなくピルそのものを持つ。端に着いたスクロールは反対の端のピルを出すので、向きからピルは決まらない。
+    // 隠れた後も同じピルを描き続けるのは、隠れるフェードをそのピルのまま見せるため
+    const [edgePill, setEdgePill] = useState<EdgePill | null>(null)
     const [showScrollButtons, setShowScrollButtons] = useState(false)
+    // 見えているピルの同期の写し (隠れている間は null)。スクロールの処理は状態を閉じ込めずに要否を決め、隠れているピルへ同じ値を
+    // 書いて確定を足さない
+    const shownEdgePillRef = useRef<EdgePill | null>(null)
     const scrollButtonTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null)
+
+    /**
+     * Hides the visible scroll-to-edge pill and cancels its auto-hide timer; writes no state while no pill shows.
+     *
+     * 見えている端へ戻るピルを隠し、自動非表示のタイマーを止める処理。ピルが見えていない間は状態を書かない。
+     */
+    const hideEdgePill = useCallback((): void => {
+        if (scrollButtonTimerRef.current !== null) {
+            clearTimeout(scrollButtonTimerRef.current)
+            scrollButtonTimerRef.current = null
+        }
+        if (shownEdgePillRef.current === null) {
+            return
+        }
+        shownEdgePillRef.current = null
+        setShowScrollButtons(false)
+    }, [])
+
+    /**
+     * Shows a scroll-to-edge pill and (re)starts its auto-hide timer (`EDGE_PILL_HIDE_DELAY_MS`).
+     *
+     * 端へ戻るピルを出し、自動非表示のタイマー (`EDGE_PILL_HIDE_DELAY_MS`) を掛け直す処理。
+     *
+     * @param pill - The pill to show / 出すピル
+     */
+    const showEdgePill = useCallback(
+        (pill: EdgePill): void => {
+            shownEdgePillRef.current = pill
+            setEdgePill(pill)
+            setShowScrollButtons(true)
+            if (scrollButtonTimerRef.current !== null) {
+                clearTimeout(scrollButtonTimerRef.current)
+            }
+            scrollButtonTimerRef.current = setTimeout(hideEdgePill, EDGE_PILL_HIDE_DELAY_MS)
+        },
+        [hideEdgePill],
+    )
     // 見せる操作は、画面に出ているピルを表示域 (行ラッパーの境界の箱の上端が表示域の上端) に対して測る
     const edgeOverlayRef = useRef<HTMLDivElement>(null)
     const edgePillRef = useRef<HTMLButtonElement>(null)
@@ -2534,9 +2629,17 @@ const VirtualScrollInner = <T,>(
     const applyWheel = useCallback((event: WheelEvent): boolean => scrollPaneRef.current?.applyWheel(event) ?? false, [])
 
     /**
-     * Handles scroll events from the pane.
+     * Handles scroll events from the pane. With the scroll-to-edge pills on, a scroll of any kind (user, programmatic or
+     * compensating) that leaves the pane resting at the visible pill's edge hides that pill at once (`canScrollTowardEdge`),
+     * and a user scroll of more than 1 px shows the pill `pickEdgePill` picks for its direction (none when the pane can
+     * scroll toward neither edge) and restarts the auto-hide timer.
+     *
+     * ペインのスクロールイベントを処理。端へ戻るピルが有効なら、ペインを見えているピルの端に止めたスクロール (利用者・プログラム・
+     * 補正のどれでも) はそのピルをすぐ隠し (`canScrollTowardEdge`)、1px を超える利用者のスクロールは向きから `pickEdgePill` が
+     * 選ぶピルを出して (どちらの端へもスクロールできなければ出さない) 自動非表示のタイマーを掛け直す。
      *
-     * ペインのスクロールイベントを処理。
+     * @param newPosition - Pane position after the scroll (px) / スクロール後のペイン位置 (px)
+     * @param prevPosition - Pane position before the scroll (px) / スクロール前のペイン位置 (px)
      */
     const handleScroll = useCallback(
         (newPosition: number, prevPosition: number) => {
@@ -2572,30 +2675,31 @@ const VirtualScrollInner = <T,>(
 
             updateScrollPositionImmediate(newPosition)
 
-            if (enableScrollToTopBottomButtons) {
-                if (isProgrammatic || isCompensating) {
-                    return
-                }
-
-                const diff = newPosition - prevPosition
-                Logger.debug("[VirtualScroll] Scroll diff:", diff, "New:", newPosition, "Prev:", prevPosition)
-                if (Math.abs(diff) > 1) {
-                    const direction = diff > 0 ? "down" : "up"
-                    setScrollDirection(direction)
-                    setShowScrollButtons(true)
-                    Logger.debug("[VirtualScroll] Showing scroll buttons. Direction:", direction)
+            if (!enableScrollToTopBottomButtons) {
+                return
+            }
+            // 最大位置は確定済みの寸法でなく今の木から測る。補正のスクロールは確定前の新しい寸法でクランプされるため
+            const maxScrollPosition = Math.max(0, fenwickTree.getTotal() + resolvedInsets.top + resolvedInsets.bottom - viewportSize)
+            const shownPill = shownEdgePillRef.current
+            // 端に着いたピルはもう何も動かさず、焦点を受けた端の行を覆うだけなので、着いた経路を問わず自動非表示を待たずに隠す
+            if (shownPill !== null && !canScrollTowardEdge(shownPill, newPosition, maxScrollPosition)) {
+                hideEdgePill()
+            }
+            if (isProgrammatic || isCompensating) {
+                return
+            }
 
-                    if (scrollButtonTimerRef.current) {
-                        clearTimeout(scrollButtonTimerRef.current)
-                    }
-                    scrollButtonTimerRef.current = setTimeout(() => {
-                        setShowScrollButtons(false)
-                        Logger.debug("[VirtualScroll] Hiding scroll buttons")
-                    }, 2000)
+            const diff = newPosition - prevPosition
+            Logger.debug("[VirtualScroll] Scroll diff:", diff, "New:", newPosition, "Prev:", prevPosition)
+            if (Math.abs(diff) > 1) {
+                const pill = pickEdgePill(diff > 0 ? "bottom" : "top", newPosition, maxScrollPosition)
+                if (pill !== null) {
+                    showEdgePill(pill)
+                    Logger.debug("[VirtualScroll] Showing scroll-to-edge pill:", pill)
                 }
             }
         },
-        [updateScrollPositionImmediate, forgetAlignedEdge, enableScrollToTopBottomButtons, itemCount],
+        [updateScrollPositionImmediate, forgetAlignedEdge, enableScrollToTopBottomButtons, itemCount, fenwickTree, resolvedInsets.top, resolvedInsets.bottom, viewportSize, hideEdgePill, showEdgePill],
     )
 
     // レンダリング範囲を計算
@@ -2840,10 +2944,14 @@ const VirtualScrollInner = <T,>(
 
     /**
      * Renders the auto-hiding top/bottom pill overlay (texts from the resolved `scrollToTop` /
-     * `scrollToBottom` labels), neutralized while hidden.
+     * `scrollToBottom` labels), neutralized while hidden. It draws one pill — the one the last user
+     * scroll picked (`edgePill`; the Bottom pill before any) — which shows only while the pane can
+     * still scroll toward that pill's edge (`handleScroll` and the size check hide it at the edge).
      *
      * 自動非表示の先頭/末尾ピルのオーバーレイ (文言は解決済みラベルの `scrollToTop` /
-     * `scrollToBottom`) を描画し、非表示中は無効化する処理。
+     * `scrollToBottom`) を描画し、非表示中は無効化する処理。描くピルは 1 つで、最後の利用者の
+     * スクロールが選んだもの (`edgePill`。スクロールの前は Bottom ピル)。ペインがまだそのピルの端の
+     * 方へスクロールできる間だけ見える (端に着くと `handleScroll` と大きさの照合が隠す)。
      *
      * ❗ 非表示は `opacity: 0` で表現するため、要素は DOM に残り続ける (フェードのために
      * アンマウントしない)。`opacity` はフォーカス可能性に影響せず、CSS の `pointer-events: none`
@@ -2874,8 +2982,8 @@ const VirtualScrollInner = <T,>(
             return null
         }
 
-        const isVisible = showScrollButtons && scrollDirection !== null
-        const isTop = scrollDirection === "up"
+        const isVisible = showScrollButtons
+        const isTop = edgePill === "top"
         const pillTabIndex = isVisible && !scrollChromeIsPointerOnly ? 0 : -1
 
         return (
@@ -2892,7 +3000,7 @@ const VirtualScrollInner = <T,>(
                                 e.stopPropagation()
                                 isProgrammaticScrollRef.current = true
                                 scrollToIndex(0)
-                                setShowScrollButtons(false)
+                                hideEdgePill()
                             }}>
                             {resolvedLabels.scrollToTop}
                         </button>
@@ -2909,7 +3017,7 @@ const VirtualScrollInner = <T,>(
                                 e.stopPropagation()
                                 isProgrammaticScrollRef.current = true
                                 scrollToIndex(itemCount - 1)
-                                setShowScrollButtons(false)
+                                hideEdgePill()
                             }}>
                             {resolvedLabels.scrollToBottom}
                         </button>
@@ -2917,7 +3025,7 @@ const VirtualScrollInner = <T,>(
                 )}
             </div>
         )
-    }, [enableScrollToTopBottomButtons, scrollChromeIsPointerOnly, showScrollButtons, scrollDirection, scrollToIndex, itemCount, resolvedLabels])
+    }, [enableScrollToTopBottomButtons, scrollChromeIsPointerOnly, showScrollButtons, edgePill, scrollToIndex, hideEdgePill, itemCount, resolvedLabels])
 
     // 量子化アンカー (fix: LayoutUnit/f32 精度対策)。行 top はコンテンツ絶対座標そのままではなく
     // 「絶対座標 - アンカー」で描画し、ラッパー側 translateY にアンカーを足し戻す。
@@ -3288,6 +3396,18 @@ const VirtualScrollInner = <T,>(
     )
 
     const totalContentHeight = fenwickTree.getTotal() + resolvedInsets.top + resolvedInsets.bottom
+    const paneMaxScrollPosition = Math.max(0, totalContentHeight - viewportSize)
+
+    useLayoutEffect(() => {
+        // 目的: 中身や表示域の大きさが変わると、位置が動かなくても最大位置が動いてペインが端に着く (中身が表示域に収まれば両端)。
+        // スクロールの知らせが来ないこの着き方でも、見えているピルを描画の前に隠す。端から離れても出し直さないのは、ピルを出すのが
+        // 利用者のスクロールだけだから (下に行が足されても、Bottom ピルは次の利用者のスクロールで出る)
+        // 依存関係: paneMaxScrollPosition, hideEdgePill
+        const shownPill = shownEdgePillRef.current
+        if (shownPill !== null && !canScrollTowardEdge(shownPill, latestScrollPositionRef.current, paneMaxScrollPosition)) {
+            hideEdgePill()
+        }
+    }, [paneMaxScrollPosition, hideEdgePill])
 
     // ライブリージョン無効時はペインをそのまま根要素として返す (既存消費者の DOM 形状を変えない)
     const pane = (