@aiquants/virtualscroll 1.23.0 → 1.25.0

package/package.json

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

package/src/VirtualScroll.tsx

@@ -40,6 +40,12 @@ export type VirtualScrollHandle = ScrollPaneHandle & {
     focusItemAtIndex: (index: number, options?: { ensureVisible?: boolean }) => void
     /** Gets the current scroll range information / 現在のスクロール範囲情報を取得 */
     getRange: () => VirtualScrollRange
+    /**
+     * Captures the current top-row anchor ({index, offsetPx}) for exact restore via initialScrollAnchor.
+     * initialScrollAnchor での厳密復元用に、現在の先頭可視行アンカー ({index, offsetPx}) を取得。
+     * itemCount 0 のときは null。offsetPx は先頭可視行の上端がビューポート上端より上に隠れている px (論理座標)。
+     */
+    getScrollAnchor: () => { index: number; offsetPx: number } | null
     /**
      * Manually updates the size of a specific item. Contract: after calling this,
      * `getItemHeight(index)` must return the same `size`; `getItemHeight` is the source of truth,
@@ -132,6 +138,19 @@ export type VirtualScrollProps<T> = {
     children: (item: T, index: number) => ReactNode
     initialScrollIndex?: number
     initialScrollOffset?: number
+    /**
+     * Anchor-based initial position: starts with row `index` scrolled `offsetPx` px past the viewport top.
+     * アンカー基準の初期位置。行 index の上端がビューポート上端より offsetPx px 分だけ上に隠れた位置で開始する。
+     *
+     * 可変高さ一覧の「位置キープ」はこれを使うこと。initialScrollOffset の生 px 復元は、実測高さが
+     * 具現化されていない再マウント空間では px→行変換が推定値で行われ、別の行に着地する
+     * (実測: 深い復元で 21 行漂着)。アンカーは行の同一性で位置決めするため空間差に不変。
+     * 保存側は VirtualScrollHandle.getScrollAnchor() で取得した値をそのまま渡す。
+     * 優先順位: initialScrollAnchor > initialScrollIndex > initialScrollOffset。
+     * マウント時に itemCount > 0 なら初回コミットから厳密。itemCount 0 でマウントした場合は
+     * 最初のデータ到着 (0 → N) 時に scrollToIndex 経由で遅延適用される (近似 → 自己修復)。
+     */
+    initialScrollAnchor?: { index: number; offsetPx?: number }
     callbackThrottleMs?: number
     contentInsets?: ScrollPaneProps["contentInsets"]
     onItemFocus?: (index: number) => void
@@ -180,7 +199,12 @@ const normalizeInsets = (insets?: ScrollPaneContentInsets): Required<ScrollPaneC
 
 const toLogicalPositionWithInset = (pane: number, top: number) => (pane <= top ? 0 : pane - top)
 
-const toPanePositionWithInset = (logical: number, top: number) => (logical <= 0 ? top : logical + top)
+// 論理 0 は「本当の先頭」= ペイン 0 (上インセットが見えている状態) へ写像する。
+// ❗ `logical <= 0 ? top` (インセットを隠して先頭行を上端密着にする端点) へ戻さないこと:
+// マウント既定 (initialScroll 未指定 = ペイン 0) や ScrollPane のクランプ休止点 (ペイン 0) と
+// 端点が食い違い、「保存した論理 0 を復元すると数 px スクロールされて見える」実害バグになる
+// (toLogical はペイン [0..top] を論理 0 へ潰す不可逆写像のため、逆写像の端点選択がここで確定する)
+const toPanePositionWithInset = (logical: number, top: number) => (logical <= 0 ? 0 : logical + top)
 
 /**
  * Maximum run length of consecutive zero-height rows scanned linearly before attempting an
@@ -572,15 +596,27 @@ const useThrottledInvoker = <Callback, Payload>(callbackRef: React.MutableRefObj
     // last: 最終実行時刻, id: RAF ID, arg: 待機中の引数
     const state = useRef({ last: 0, id: null as number | null, arg: null as Payload | null }).current
 
-    // クリーンアップ: アンマウント時にRAFをキャンセル
+    // クリーンアップ: アンマウント時に RAF をキャンセルし、待機中のペイロードは**破棄せず同期配信**する。
+    // ❗ 破棄すると、フリング中のタブ切替などで確定済みの待機通知まで消費側へ届かず、
+    // 「スクロールのたびに書き戻す」型の位置保存が取りこぼす。なおこの flush が救えるのは
+    // 「キューに載った最後のペイロード」まで: 最後の render-loop tick 以後の移動 (最大 1 フレーム分、
+    // 慣性で概ね 100px 未満) は残余として許容する (読中でないフリング途中の位置のため実害は軽微)
     useEffect(
         () => () => {
             if (state.id !== null) {
                 cancelAnimationFrame(state.id)
                 state.id = null
             }
+            if (state.arg !== null && callbackRef.current) {
+                try {
+                    invoke(callbackRef.current, state.arg)
+                } catch (e) {
+                    console.error("[useThrottledInvoker] Error flushing pending callback on unmount", e)
+                }
+                state.arg = null
+            }
         },
-        [state],
+        [state, callbackRef, invoke],
     )
 
     return useCallback(
@@ -686,6 +722,7 @@ const VirtualScrollInner = <T,>(
         background,
         initialScrollIndex,
         initialScrollOffset,
+        initialScrollAnchor,
         callbackThrottleMs = 5,
         contentInsets,
         onItemFocus,
@@ -709,18 +746,32 @@ const VirtualScrollInner = <T,>(
         scrollPosition: 0,
         totalHeight: 0,
     })
+    // アンカー付きマウントは保留アンカーを最初から種まきする: マウント後の実測反映 (contentSize
+    // コミット) のたびにドリフト補正 effect が同じ行へ再ピン留めし、自己修復する。ユーザーの
+    // 手動スクロールで解除される (handleScroll 参照)。offset は scrollToIndex と同じ「減算」規約の
+    // ため符号を反転して持つ (offsetPx = 行上端がビューポート上端より上に隠れる px、正の値)
     const pendingVisibleStartIndexRef = useRef<{
         index: number
         align?: "top" | "bottom" | "center"
         offset?: number
-    } | null>(null)
+    } | null>(initialScrollAnchor && itemCount > 0 ? { index: minmax(Math.trunc(initialScrollAnchor.index), 0, itemCount - 1), align: "top", offset: -Math.max(0, initialScrollAnchor.offsetPx ?? 0) } : null)
     // 「アンマウント済みか」を追跡する (初期 false)。「マウント済みか」の正ガードだと、初回レンダー中に
     // 予約された高さ照合マイクロタスクが passive effect (マウントフラグ設定) より先に実行されて破棄される。
     const isUnmountedRef = useRef(false)
 
+    // 初回実行スキップ用 (マウント時に走る effect 本体が、直前で種まきした初期アンカーを消さないため)
+    const isFirstGetItemHeightRunRef = useRef(true)
     useEffect(() => {
         // 目的: アイテムの高さ取得ロジックがリセットされた場合に、古いインデックスへのアンカーを解除する。
         // 依存関係: resetOnGetItemHeightChange, getItemHeight
+        // ❗ 初回 (マウント) は解除しない: このフラグの意味は「getItemHeight の**変更**時に解除」で
+        // あり、マウント時の実行で解除すると initialScrollAnchor が種まきした保留アンカー
+        // (実測反映ごとの自己修復再ピン留め) が resetOnGetItemHeightChange: true の消費者で
+        // 無言に無効化されてしまう
+        if (isFirstGetItemHeightRunRef.current) {
+            isFirstGetItemHeightRunRef.current = false
+            return
+        }
         if (resetOnGetItemHeightChange) {
             // When configured to reset on logic change, we drop the scroll anchor
             // to avoid sticking to an index that may no longer be relevant contextually.
@@ -739,7 +790,9 @@ const VirtualScrollInner = <T,>(
     // (sampleRangeChanged) が破壊的な tree.reset を発火し、実測済みの全行高さが破棄されてしまう。
     const [initialSampleRange] = useState(() => {
         const SAMPLE_HALF_WINDOW = 50
-        const anchor = typeof initialScrollIndex === "number" && Number.isFinite(initialScrollIndex) ? Math.max(0, Math.trunc(initialScrollIndex)) : 0
+        // アンカー復元はアンカー行を、index 復元はその行を窓の中心にする (どちらも「最初に見る領域」)
+        const anchorSource = initialScrollAnchor?.index ?? initialScrollIndex
+        const anchor = typeof anchorSource === "number" && Number.isFinite(anchorSource) ? Math.max(0, Math.trunc(anchorSource)) : 0
         return { from: Math.max(0, anchor - SAMPLE_HALF_WINDOW), to: anchor + SAMPLE_HALF_WINDOW }
     })
 
@@ -760,7 +813,20 @@ const VirtualScrollInner = <T,>(
     const [initialValues] = useState(() => {
         let position = 0
         let total = 0
-        if (typeof initialScrollIndex === "number") {
+        if (initialScrollAnchor && itemCount > 0) {
+            // アンカー復元: アンカー行の周辺を具現化し、その行の上端 + offsetPx を初期位置にする。
+            // 初回描画のレンジ計算も同じツリー状態から導かれるため、推定誤差の量に関係なく
+            // 「アンカー行がちょうど offsetPx 分だけ上に隠れた」画で最初のフレームから出る
+            const safeIndex = minmax(Math.trunc(initialScrollAnchor.index), 0, itemCount - 1)
+            const anchorOffsetPx = Math.max(0, initialScrollAnchor.offsetPx ?? 0)
+            const safeIndexFrom = minmax(safeIndex - overscanCount * 2, 0, itemCount - 1)
+            const safeIndexTo = minmax(safeIndex + overscanCount * 2, 0, itemCount - 1)
+            const options = safeIndex > 0 || anchorOffsetPx > 0 ? { materializeOption: { materialize: true, ranges: [{ from: safeIndexFrom, to: safeIndexTo }] } } : undefined
+            const { cumulative, total: materializedTotal, currentValue } = fenwickTree.prefixSum(safeIndex, options)
+            const logicalOffset = Math.max(cumulative - currentValue + anchorOffsetPx, 0)
+            position = toPanePositionWithInset(logicalOffset, resolvedInsets.top)
+            total = materializedTotal ?? fenwickTree.getTotal()
+        } else if (typeof initialScrollIndex === "number") {
             const safeIndex = minmax(initialScrollIndex, 0, itemCount - 1)
             const safeIndexFrom = minmax(safeIndex - overscanCount * 2, 0, itemCount - 1)
             const safeIndexTo = minmax(safeIndex + overscanCount * 2, 0, itemCount - 1)
@@ -1051,7 +1117,10 @@ const VirtualScrollInner = <T,>(
         didApplyInitialOffsetRef.current = true
         // 目的: 初期オフセットを一度だけ適用し (同期処理)、ペインと論理位置を同期させる。
         // 依存関係: initialScrollOffset (初回のみ実行されるガード節あり)
-        if (typeof initialScrollOffset === "number") {
+        // ❗ initialScrollOffset の適用はそれが「最優先の初期位置指定」である場合のみ。
+        // アンカー/インデックス指定と併用されたとき、この passive effect (描画後) が offset で
+        // 上書きすると「初回描画は index 位置 → 1 コミット後に offset 位置へ跳ぶ」踏み潰しになる
+        if (initialScrollAnchor == null && typeof initialScrollIndex !== "number" && typeof initialScrollOffset === "number") {
             const paneOffset = toPanePositionWithInset(Math.max(initialScrollOffset, 0), resolvedInsets.top)
             const needsPaneSync = Math.abs(paneOffset - latestScrollPositionRef.current) > 0.5
             updateScrollPositionImmediate(paneOffset, { immediate: true })
@@ -1061,7 +1130,7 @@ const VirtualScrollInner = <T,>(
         } else {
             updateScrollPositionImmediate(latestScrollPositionRef.current, { immediate: true })
         }
-    }, [initialScrollOffset, resolvedInsets.top, updateScrollPositionImmediate])
+    }, [initialScrollAnchor, initialScrollIndex, initialScrollOffset, resolvedInsets.top, updateScrollPositionImmediate])
 
     useEffect(() => {
         // itemCount triggers recalculation of contentSize
@@ -1305,6 +1374,21 @@ const VirtualScrollInner = <T,>(
         [fenwickTree, overscanCount, itemCount, resolvedInsets.top, resolvedInsets.bottom, viewportSize, updateScrollPositionImmediate],
     )
 
+    // アンカー付きマウントが itemCount 0 で始まった場合の遅延適用 (一度きり)。
+    // 初期値経路 (useState) はマウント時データが前提のため、データ後着の消費者では
+    // アンカーが無言に落ちる。最初の 0 → N 遷移で scrollToIndex 経由で適用する
+    // (アンカー近傍の具現化 + 保留アンカー設定を再利用。初回コミット厳密性はデータが
+    // ある状態でのマウントのみで保証され、遅延適用は近似 → ドリフト補正で自己修復)
+    const deferredInitialAnchorRef = useRef(initialScrollAnchor && itemCount === 0 ? initialScrollAnchor : null)
+    useEffect(() => {
+        const deferred = deferredInitialAnchorRef.current
+        if (!deferred || itemCount === 0) {
+            return
+        }
+        deferredInitialAnchorRef.current = null
+        scrollToIndex(minmax(Math.trunc(deferred.index), 0, itemCount - 1), { align: "top", offset: -Math.max(0, deferred.offsetPx ?? 0) })
+    }, [itemCount, scrollToIndex])
+
     /**
      * Scrolls to a raw offset while resolving to an index.
      *
@@ -1329,6 +1413,33 @@ const VirtualScrollInner = <T,>(
         [fenwickTree, itemCount, scrollToIndex],
     )
 
+    /**
+     * Captures the current top-row anchor for exact position restore across remounts.
+     * 再マウント越しの厳密な位置復元のために、現在の先頭可視行アンカーを取得する処理。
+     *
+     * offsetPx は「先頭可視行の上端がビューポート上端より上に隠れている px」(正の値、論理座標)。
+     * 復元は initialScrollAnchor へそのまま渡す。可視ウィンドウの行高さは描画のたびに実測が
+     * ツリーへ照合されるため、保存時点のアンカーは常に正確で、生 px と違い再マウント後の
+     * 推定空間の違いに対して不変 (px 復元は深い位置で別の行に着地する)。
+     */
+    const getScrollAnchor = useCallback((): { index: number; offsetPx: number } | null => {
+        if (itemCount === 0) {
+            return null
+        }
+        const logical = toLogicalPositionWithInset(latestScrollPositionRef.current, resolvedInsets.top)
+        const { index, cumulative, currentValue } = fenwickTree.findIndexAtOrAfter(logical, { materializeOption: { materialize: false } })
+        if (index === -1) {
+            // 末尾越え (推定総高さより深い位置) は最終行アンカーへ丸める
+            return { index: itemCount - 1, offsetPx: 0 }
+        }
+        if (cumulative === logical) {
+            // 行の下端がちょうどビューポート上端 = 可視先頭は次の行 (可視域計算と同じ境界規約)
+            return { index: minmax(index + 1, 0, itemCount - 1), offsetPx: 0 }
+        }
+        const itemTop = (cumulative ?? 0) - (currentValue ?? 0)
+        return { index, offsetPx: Math.max(0, logical - itemTop) }
+    }, [fenwickTree, itemCount, resolvedInsets.top])
+
     /**
      * Imperative scroll entry supporting updater functions.
      *
@@ -1879,9 +1990,10 @@ const VirtualScrollInner = <T,>(
             getFenwickSize: () => fenwickTree.getSize(),
             focusItemAtIndex,
             getRange: () => currentRangeRef.current,
+            getScrollAnchor,
             updateItemSize,
         }),
-        [scrollToHandle, scrollToIndex, fenwickTree, focusItemAtIndex, updateItemSize],
+        [scrollToHandle, scrollToIndex, fenwickTree, focusItemAtIndex, getScrollAnchor, updateItemSize],
     )
 
     const totalContentHeight = fenwickTree.getTotal() + resolvedInsets.top + resolvedInsets.bottom