@aiquants/virtualscroll 1.24.0 → 1.25.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiquants/virtualscroll",
-  "version": "1.24.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
@@ -703,6 +722,7 @@ const VirtualScrollInner = <T,>(
         background,
         initialScrollIndex,
         initialScrollOffset,
+        initialScrollAnchor,
         callbackThrottleMs = 5,
         contentInsets,
         onItemFocus,
@@ -726,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.
@@ -756,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 }
     })
 
@@ -777,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)
@@ -1068,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 })
@@ -1078,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
@@ -1322,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.
      *
@@ -1346,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.
      *
@@ -1896,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