@aiquants/virtualscroll 1.25.0 → 2.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiquants/virtualscroll",
-  "version": "1.25.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 で管理されている総高さを取得 */
@@ -737,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,
@@ -1214,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 })
@@ -1453,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],
     )
@@ -1981,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,