@aiquants/virtualscroll 1.24.0 → 2.0.0

package/package.json

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

package/src/VirtualScroll.tsx

@@ -25,11 +25,35 @@ export type VirtualScrollRange = {
 }
 
 /**
- * Handle interface for controlling the VirtualScroll component externally.
+ * Imperative handle of VirtualScroll. Every position it accepts or returns is in the
+ * LOGICAL coordinate space (content px, insets excluded) — the same space as onScroll /
+ * onRangeChange / initialScrollOffset / getScrollAnchor.
+ * VirtualScroll の命令ハンドル。受け取る位置・返す位置は**すべて論理座標** (inset 抜きの
+ * コンテンツ px) で、onScroll / onRangeChange / initialScrollOffset / getScrollAnchor と同一空間。
  *
- * 外部から VirtualScroll コンポーネントを制御するためのハンドルインターフェース。
+ * ❗ ペイン座標 (inset 込み) は内部実装詳細であり、このハンドルからは一切露出しない。
+ * 2.0.0 以前は getScrollPosition と scrollTo の返値だけがペイン座標という非対称があり、
+ * 消費者側の換算コードが 2 度の実害バグ (daily-report 初期 6px ずれ / directory-tree の
+ * inset 二重適用) を生んだ。座標系の混在を消費者から構造的に不能にするための統一である。
+ * ScrollPane 自身のハンドル (ScrollPaneHandle) はペインそのものなのでペイン座標のままであり、
+ * その境界はこの型が引き受ける。
  */
-export type VirtualScrollHandle = ScrollPaneHandle & {
+export type VirtualScrollHandle = {
+    /**
+     * Scrolls to a LOGICAL position (updater form receives the current logical position).
+     * Returns the applied (clamped) LOGICAL position.
+     * 論理位置へスクロール (updater は現在の論理位置を受け取る)。適用後 (クランプ後) の論理位置を返す。
+     */
+    scrollTo: (position: number | ((prev: number) => number)) => number
+    /**
+     * Current LOGICAL scroll position. -1 when the pane is not connected.
+     * 現在の論理スクロール位置。ペイン未接続時は -1。
+     */
+    getScrollPosition: () => number
+    /** Total pane content size including insets (a size, not a position) / インセット込みのコンテンツ総高さ (位置ではなくサイズ)。未接続時は -1 */
+    getContentSize: () => number
+    /** Viewport size / ビューポートの高さ。未接続時は -1 */
+    getViewportSize: () => number
     /** Scrolls to a specific item index / 指定したアイテムインデックスへスクロール */
     scrollToIndex: (index: number, options?: { align?: "top" | "bottom" | "center"; offset?: number }) => void
     /** Gets the total height managed by the Fenwick Tree / Fenwick Tree で管理されている総高さを取得 */
@@ -40,6 +64,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 +162,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 +746,7 @@ const VirtualScrollInner = <T,>(
         background,
         initialScrollIndex,
         initialScrollOffset,
+        initialScrollAnchor,
         callbackThrottleMs = 5,
         contentInsets,
         onItemFocus,
@@ -717,7 +761,9 @@ const VirtualScrollInner = <T,>(
 
     const { enablePointerDrag, pointerDragInputs, enableKeyboardNavigation = true, wheelSpeedMultiplier, inertiaOptions, clipItemHeight = false, resetOnGetItemHeightChange = false } = behaviorOptions ?? {}
 
-    const scrollPaneRef = useRef<VirtualScrollHandle>(null)
+    // ❗ 内部ペイン ref の型は ScrollPaneHandle (ペイン座標)。VirtualScrollHandle と誤記すると
+    // 2.0.0 以降は型ドキュメントが「論理座標を返す」と嘘をつく (構造的互換で型検査は通ってしまう)
+    const scrollPaneRef = useRef<ScrollPaneHandle>(null)
     const currentRangeRef = useRef<VirtualScrollRange>({
         renderingStartIndex: 0,
         renderingEndIndex: 0,
@@ -726,18 +772,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 +816,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 +839,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 +1143,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 +1156,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
@@ -1162,10 +1240,18 @@ const VirtualScrollInner = <T,>(
         // 依存関係: resolvedInsets.top
         const previousTop = previousTopInsetRef.current
         if (previousTop === resolvedInsets.top) return
+        previousTopInsetRef.current = resolvedInsets.top
+
+        // ❗ 保留アンカー (scrollToIndex / initialScrollAnchor 由来) が居る間は位置決めをドリフト補正
+        // effect へ委譲する。ここでも相対シフトすると、アンカー基準の絶対位置決め (新 top で再計算済み)
+        // と二重適用になり、論理位置が inset 差分ぶんズレる (2.0.0 の「論理位置は inset 非依存」契約の
+        // 破れとして動的 inset ピンが検知した実バグ。previousTopInsetRef の更新だけ行う)
+        if (pendingVisibleStartIndexRef.current) {
+            return
+        }
 
         const logicalPosition = toLogicalPositionWithInset(latestScrollPositionRef.current, previousTop)
         const panePosition = toPanePositionWithInset(logicalPosition, resolvedInsets.top)
-        previousTopInsetRef.current = resolvedInsets.top
         latestScrollPositionRef.current = panePosition
         scrollPaneRef.current?.scrollTo(panePosition)
         updateScrollPositionImmediate(panePosition, { immediate: true })
@@ -1322,6 +1408,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 +1447,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.
      *
@@ -1359,7 +1487,9 @@ const VirtualScrollInner = <T,>(
             const panePosition = scrollPaneRef.current?.getScrollPosition()
             const effectivePosition = typeof panePosition === "number" ? panePosition : latestScrollPositionRef.current
             updateScrollPositionImmediate(effectivePosition)
-            return effectivePosition
+            // ❗ 返値も論理座標 (2.0.0)。ペイン座標を返すと「入力は論理・返値はペイン」の非対称が
+            // 復活し、返値をミラーへ書き戻す消費者が inset 分ずれる
+            return toLogicalPositionWithInset(effectivePosition, resolvedInsetsTopRef.current)
         },
         [resolvedInsets.top, scrollTo, updateScrollPositionImmediate],
     )
@@ -1887,7 +2017,12 @@ const VirtualScrollInner = <T,>(
     useImperativeHandle(
         ref,
         () => ({
-            getScrollPosition: () => scrollPaneRef.current?.getScrollPosition() ?? -1,
+            getScrollPosition: () => {
+                // ❗ 論理座標で返す (2.0.0)。ペイン座標を返す実装へ戻さないこと: 消費者の換算コードが
+                // 座標混在バグの温床になる (この統一が本質修正)。inset は走行中も最新を ref から読む
+                const panePosition = scrollPaneRef.current?.getScrollPosition()
+                return typeof panePosition === "number" ? toLogicalPositionWithInset(panePosition, resolvedInsetsTopRef.current) : -1
+            },
             getContentSize: () => scrollPaneRef.current?.getContentSize() ?? -1,
             getViewportSize: () => scrollPaneRef.current?.getViewportSize() ?? -1,
             scrollTo: scrollToHandle,
@@ -1896,9 +2031,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