@tanstack/virtual-core 3.13.11 → 3.13.13

package/src/index.ts

@@ -359,10 +359,13 @@ export class Virtualizer<
   scrollElement: TScrollElement | null = null
   targetWindow: (Window & typeof globalThis) | null = null
   isScrolling = false
-  private scrollToIndexTimeoutId: number | null = null
   measurementsCache: Array<VirtualItem> = []
   private itemSizeCache = new Map<Key, number>()
+  private laneAssignments = new Map<number, number>() // index → lane cache
   private pendingMeasuredCacheIndexes: Array<number> = []
+  private prevLanes: number | undefined = undefined
+  private lanesChangedFlag = false
+  private lanesSettling = false
   scrollRect: Rect | null = null
   scrollOffset: number | null = null
   scrollDirection: ScrollDirection | null = null
@@ -618,34 +621,72 @@ export class Virtualizer<
       this.options.scrollMargin,
       this.options.getItemKey,
       this.options.enabled,
+      this.options.lanes,
     ],
-    (count, paddingStart, scrollMargin, getItemKey, enabled) => {
+    (count, paddingStart, scrollMargin, getItemKey, enabled, lanes) => {
+      const lanesChanged =
+        this.prevLanes !== undefined && this.prevLanes !== lanes
+
+      if (lanesChanged) {
+        // Set flag for getMeasurements to handle
+        this.lanesChangedFlag = true
+      }
+
+      this.prevLanes = lanes
       this.pendingMeasuredCacheIndexes = []
+
       return {
         count,
         paddingStart,
         scrollMargin,
         getItemKey,
         enabled,
+        lanes,
       }
     },
     {
       key: false,
+      skipInitialOnChange: true,
+      onChange: () => {
+        // Notify when measurement options change as they affect total size
+        this.notify(this.isScrolling)
+      },
     },
   )
 
   private getMeasurements = memo(
     () => [this.getMeasurementOptions(), this.itemSizeCache],
     (
-      { count, paddingStart, scrollMargin, getItemKey, enabled },
+      { count, paddingStart, scrollMargin, getItemKey, enabled, lanes },
       itemSizeCache,
     ) => {
       if (!enabled) {
         this.measurementsCache = []
         this.itemSizeCache.clear()
+        this.laneAssignments.clear()
         return []
       }
 
+      // Clean up stale lane cache entries when count decreases
+      if (this.laneAssignments.size > count) {
+        for (const index of this.laneAssignments.keys()) {
+          if (index >= count) {
+            this.laneAssignments.delete(index)
+          }
+        }
+      }
+
+      // ✅ Force complete recalculation when lanes change
+      if (this.lanesChangedFlag) {
+        this.lanesChangedFlag = false // Reset immediately
+        this.lanesSettling = true // Start settling period
+        this.measurementsCache = []
+        this.itemSizeCache.clear()
+        this.laneAssignments.clear() // Clear lane cache for new lane count
+        // Clear pending indexes to force min = 0
+        this.pendingMeasuredCacheIndexes = []
+      }
+
       if (this.measurementsCache.length === 0) {
         this.measurementsCache = this.options.initialMeasurementsCache
         this.measurementsCache.forEach((item) => {
@@ -653,25 +694,71 @@ export class Virtualizer<
         })
       }
 
-      const min =
-        this.pendingMeasuredCacheIndexes.length > 0
+      // ✅ During lanes settling, ignore pendingMeasuredCacheIndexes to prevent repositioning
+      const min = this.lanesSettling
+        ? 0
+        : this.pendingMeasuredCacheIndexes.length > 0
           ? Math.min(...this.pendingMeasuredCacheIndexes)
           : 0
       this.pendingMeasuredCacheIndexes = []
 
+      // ✅ End settling period when cache is fully built
+      if (this.lanesSettling && this.measurementsCache.length === count) {
+        this.lanesSettling = false
+      }
+
       const measurements = this.measurementsCache.slice(0, min)
 
+      // ✅ Performance: Track last item index per lane for O(1) lookup
+      const laneLastIndex: Array<number | undefined> = new Array(lanes).fill(
+        undefined,
+      )
+
+      // Initialize from existing measurements (before min)
+      for (let m = 0; m < min; m++) {
+        const item = measurements[m]
+        if (item) {
+          laneLastIndex[item.lane] = m
+        }
+      }
+
       for (let i = min; i < count; i++) {
         const key = getItemKey(i)
 
-        const furthestMeasurement =
-          this.options.lanes === 1
-            ? measurements[i - 1]
-            : this.getFurthestMeasurement(measurements, i)
-
-        const start = furthestMeasurement
-          ? furthestMeasurement.end + this.options.gap
-          : paddingStart + scrollMargin
+        // Check for cached lane assignment
+        const cachedLane = this.laneAssignments.get(i)
+        let lane: number
+        let start: number
+
+        if (cachedLane !== undefined && this.options.lanes > 1) {
+          // Use cached lane - O(1) lookup for previous item in same lane
+          lane = cachedLane
+          const prevIndex = laneLastIndex[lane]
+          const prevInLane =
+            prevIndex !== undefined ? measurements[prevIndex] : undefined
+          start = prevInLane
+            ? prevInLane.end + this.options.gap
+            : paddingStart + scrollMargin
+        } else {
+          // No cache - use original logic (find shortest lane)
+          const furthestMeasurement =
+            this.options.lanes === 1
+              ? measurements[i - 1]
+              : this.getFurthestMeasurement(measurements, i)
+
+          start = furthestMeasurement
+            ? furthestMeasurement.end + this.options.gap
+            : paddingStart + scrollMargin
+
+          lane = furthestMeasurement
+            ? furthestMeasurement.lane
+            : i % this.options.lanes
+
+          // Cache the lane assignment
+          if (this.options.lanes > 1) {
+            this.laneAssignments.set(i, lane)
+          }
+        }
 
         const measuredSize = itemSizeCache.get(key)
         const size =
@@ -681,10 +768,6 @@ export class Virtualizer<
 
         const end = start + size
 
-        const lane = furthestMeasurement
-          ? furthestMeasurement.lane
-          : i % this.options.lanes
-
         measurements[i] = {
           index: i,
           start,
@@ -693,6 +776,9 @@ export class Virtualizer<
           key,
           lane,
         }
+
+        // ✅ Performance: Update lane's last item index
+        laneLastIndex[lane] = i
       }
 
       this.measurementsCache = measurements
@@ -904,7 +990,7 @@ export class Virtualizer<
       toOffset -= size
     }
 
-    const maxOffset = this.getTotalSize() - size
+    const maxOffset = this.getTotalSize() + this.options.scrollMargin - size
 
     return Math.max(Math.min(maxOffset, toOffset), 0)
   }
@@ -943,19 +1029,10 @@ export class Virtualizer<
 
   private isDynamicMode = () => this.elementsCache.size > 0
 
-  private cancelScrollToIndex = () => {
-    if (this.scrollToIndexTimeoutId !== null && this.targetWindow) {
-      this.targetWindow.clearTimeout(this.scrollToIndexTimeoutId)
-      this.scrollToIndexTimeoutId = null
-    }
-  }
-
   scrollToOffset = (
     toOffset: number,
     { align = 'start', behavior }: ScrollToOffsetOptions = {},
   ) => {
-    this.cancelScrollToIndex()
-
     if (behavior === 'smooth' && this.isDynamicMode()) {
       console.warn(
         'The `smooth` scroll behavior is not fully supported with dynamic size.',
@@ -972,50 +1049,62 @@ export class Virtualizer<
     index: number,
     { align: initialAlign = 'auto', behavior }: ScrollToIndexOptions = {},
   ) => {
-    index = Math.max(0, Math.min(index, this.options.count - 1))
-
-    this.cancelScrollToIndex()
-
     if (behavior === 'smooth' && this.isDynamicMode()) {
       console.warn(
         'The `smooth` scroll behavior is not fully supported with dynamic size.',
       )
     }
 
-    const offsetAndAlign = this.getOffsetForIndex(index, initialAlign)
-    if (!offsetAndAlign) return
+    index = Math.max(0, Math.min(index, this.options.count - 1))
 
-    const [offset, align] = offsetAndAlign
+    let attempts = 0
+    const maxAttempts = 10
 
-    this._scrollToOffset(offset, { adjustments: undefined, behavior })
+    const tryScroll = (currentAlign: ScrollAlignment) => {
+      if (!this.targetWindow) return
 
-    if (behavior !== 'smooth' && this.isDynamicMode() && this.targetWindow) {
-      this.scrollToIndexTimeoutId = this.targetWindow.setTimeout(() => {
-        this.scrollToIndexTimeoutId = null
+      const offsetInfo = this.getOffsetForIndex(index, currentAlign)
+      if (!offsetInfo) {
+        console.warn('Failed to get offset for index:', index)
+        return
+      }
+      const [offset, align] = offsetInfo
+      this._scrollToOffset(offset, { adjustments: undefined, behavior })
+
+      this.targetWindow.requestAnimationFrame(() => {
+        const currentOffset = this.getScrollOffset()
+        const afterInfo = this.getOffsetForIndex(index, align)
+        if (!afterInfo) {
+          console.warn('Failed to get offset for index:', index)
+          return
+        }
 
-        const elementInDOM = this.elementsCache.has(
-          this.options.getItemKey(index),
-        )
+        if (!approxEqual(afterInfo[0], currentOffset)) {
+          scheduleRetry(align)
+        }
+      })
+    }
 
-        if (elementInDOM) {
-          const result = this.getOffsetForIndex(index, align)
-          if (!result) return
-          const [latestOffset] = result
+    const scheduleRetry = (align: ScrollAlignment) => {
+      if (!this.targetWindow) return
 
-          const currentScrollOffset = this.getScrollOffset()
-          if (!approxEqual(latestOffset, currentScrollOffset)) {
-            this.scrollToIndex(index, { align, behavior })
-          }
-        } else {
-          this.scrollToIndex(index, { align, behavior })
+      attempts++
+      if (attempts < maxAttempts) {
+        if (process.env.NODE_ENV !== 'production' && this.options.debug) {
+          console.info('Schedule retry', attempts, maxAttempts)
         }
-      })
+        this.targetWindow.requestAnimationFrame(() => tryScroll(align))
+      } else {
+        console.warn(
+          `Failed to scroll to index ${index} after ${maxAttempts} attempts.`,
+        )
+      }
     }
+
+    tryScroll(initialAlign)
   }
 
   scrollBy = (delta: number, { behavior }: ScrollToOffsetOptions = {}) => {
-    this.cancelScrollToIndex()
-
     if (behavior === 'smooth' && this.isDynamicMode()) {
       console.warn(
         'The `smooth` scroll behavior is not fully supported with dynamic size.',
@@ -1075,6 +1164,7 @@ export class Virtualizer<
 
   measure = () => {
     this.itemSizeCache = new Map()
+    this.laneAssignments = new Map() // Clear lane cache for full re-layout
     this.notify(false)
   }
 }

package/src/utils.ts

@@ -10,10 +10,12 @@ export function memo<TDeps extends ReadonlyArray<any>, TResult>(
     debug?: () => boolean
     onChange?: (result: TResult) => void
     initialDeps?: TDeps
+    skipInitialOnChange?: boolean
   },
 ) {
   let deps = opts.initialDeps ?? []
   let result: TResult | undefined
+  let isInitial = true
 
   function memoizedFunction(): TResult {
     let depTime: number
@@ -62,7 +64,11 @@ export function memo<TDeps extends ReadonlyArray<any>, TResult>(
       )
     }
 
-    opts?.onChange?.(result)
+    if (opts?.onChange && !(isInitial && opts.skipInitialOnChange)) {
+      opts.onChange(result)
+    }
+
+    isInitial = false
 
     return result
   }
@@ -83,7 +89,7 @@ export function notUndefined<T>(value: T | undefined, msg?: string): T {
   }
 }
 
-export const approxEqual = (a: number, b: number) => Math.abs(a - b) <= 1
+export const approxEqual = (a: number, b: number) => Math.abs(a - b) < 1.01
 
 export const debounce = (
   targetWindow: Window & typeof globalThis,