@tanstack/virtual-core 3.13.20 → 3.13.22

package/src/index.ts

@@ -8,7 +8,7 @@ type ScrollDirection = 'forward' | 'backward'
 
 type ScrollAlignment = 'start' | 'center' | 'end' | 'auto'
 
-type ScrollBehavior = 'auto' | 'smooth'
+type ScrollBehavior = 'auto' | 'smooth' | 'instant'
 
 export interface ScrollToOptions {
   align?: ScrollAlignment
@@ -348,6 +348,22 @@ export interface VirtualizerOptions<
   useAnimationFrameWithResizeObserver?: boolean
 }
 
+type ScrollState = {
+  // what we want
+  index: number | null
+  align: ScrollAlignment
+  behavior: ScrollBehavior
+
+  // lifecycle
+  startedAt: number
+
+  // target tracking
+  lastTargetOffset: number
+
+  // settling
+  stableFrames: number
+}
+
 export class Virtualizer<
   TScrollElement extends Element | Window,
   TItemElement extends Element,
@@ -357,7 +373,7 @@ export class Virtualizer<
   scrollElement: TScrollElement | null = null
   targetWindow: (Window & typeof globalThis) | null = null
   isScrolling = false
-  private currentScrollToIndex: number | null = null
+  private scrollState: ScrollState | null = null
   measurementsCache: Array<VirtualItem> = []
   private itemSizeCache = new Map<Key, number>()
   private laneAssignments = new Map<number, number>() // index → lane cache
@@ -377,6 +393,7 @@ export class Virtualizer<
         instance: Virtualizer<TScrollElement, TItemElement>,
       ) => boolean)
   elementsCache = new Map<Key, TItemElement>()
+  private now = () => this.targetWindow?.performance?.now?.() ?? Date.now()
   private observer = (() => {
     let _ro: ResizeObserver | null = null
 
@@ -392,7 +409,21 @@ export class Virtualizer<
       return (_ro = new this.targetWindow.ResizeObserver((entries) => {
         entries.forEach((entry) => {
           const run = () => {
-            this._measureElement(entry.target as TItemElement, entry)
+            const node = entry.target as TItemElement
+            const index = this.indexFromElement(node)
+
+            if (!node.isConnected) {
+              this.observer.unobserve(node)
+              this.elementsCache.delete(this.options.getItemKey(index))
+              return
+            }
+
+            if (this.shouldMeasureDuringScroll(index)) {
+              this.resizeItem(
+                index,
+                this.options.measureElement(node, entry, this),
+              )
+            }
           }
           this.options.useAnimationFrameWithResizeObserver
             ? requestAnimationFrame(run)
@@ -482,6 +513,11 @@ export class Virtualizer<
     this.unsubs.filter(Boolean).forEach((d) => d!())
     this.unsubs = []
     this.observer.disconnect()
+    if (this.rafId != null && this.targetWindow) {
+      this.targetWindow.cancelAnimationFrame(this.rafId)
+      this.rafId = null
+    }
+    this.scrollState = null
     this.scrollElement = null
     this.targetWindow = null
   }
@@ -535,6 +571,9 @@ export class Virtualizer<
           this.scrollOffset = offset
           this.isScrolling = isScrolling
 
+          if (this.scrollState) {
+            this.scheduleScrollReconcile()
+          }
           this.maybeNotify()
         }),
       )
@@ -546,6 +585,74 @@ export class Virtualizer<
     }
   }
 
+  private rafId: number | null = null
+  private scheduleScrollReconcile() {
+    if (!this.targetWindow) {
+      this.scrollState = null
+      return
+    }
+    if (this.rafId != null) return
+    this.rafId = this.targetWindow.requestAnimationFrame(() => {
+      this.rafId = null
+      this.reconcileScroll()
+    })
+  }
+  private reconcileScroll() {
+    if (!this.scrollState) return
+
+    const el = this.scrollElement
+    if (!el) return
+
+    // Safety valve: bail out if reconciliation has been running too long
+    const MAX_RECONCILE_MS = 5000
+    if (this.now() - this.scrollState.startedAt > MAX_RECONCILE_MS) {
+      this.scrollState = null
+      return
+    }
+
+    const offsetInfo =
+      this.scrollState.index != null
+        ? this.getOffsetForIndex(this.scrollState.index, this.scrollState.align)
+        : undefined
+    const targetOffset = offsetInfo
+      ? offsetInfo[0]
+      : this.scrollState.lastTargetOffset
+
+    // Require one stable frame where target matches scroll offset.
+    // approxEqual() already tolerates minor fluctuations, so one frame is sufficient
+    // to confirm scroll has reached its target without premature cleanup.
+    const STABLE_FRAMES = 1
+
+    const targetChanged = targetOffset !== this.scrollState.lastTargetOffset
+
+    if (!targetChanged && approxEqual(targetOffset, this.getScrollOffset())) {
+      this.scrollState.stableFrames++
+      if (this.scrollState.stableFrames >= STABLE_FRAMES) {
+        this.scrollState = null
+        return
+      }
+    } else {
+      this.scrollState.stableFrames = 0
+
+      if (targetChanged) {
+        this.scrollState.lastTargetOffset = targetOffset
+        // Switch to 'auto' behavior once measurements cause target to change
+        // We want to jump directly to the correct position, not smoothly animate to it
+        this.scrollState.behavior = 'auto'
+
+        this._scrollToOffset(targetOffset, {
+          adjustments: undefined,
+          behavior: 'auto',
+        })
+      }
+    }
+
+    // Always reschedule while scrollState is active to guarantee
+    // the safety valve timeout runs even if no scroll events fire
+    // (e.g. no-op scrollToFn, detached element)
+    this.scheduleScrollReconcile()
+  }
+
   private getSize = () => {
     if (!this.options.enabled) {
       this.scrollRect = null
@@ -859,21 +966,51 @@ export class Virtualizer<
     return parseInt(indexStr, 10)
   }
 
-  private _measureElement = (
-    node: TItemElement,
-    entry: ResizeObserverEntry | undefined,
-  ) => {
-    if (!node.isConnected) {
-      this.observer.unobserve(node)
-      return
+  /**
+   * Determines if an item at the given index should be measured during smooth scroll.
+   * During smooth scroll, only items within a buffer range around the target are measured
+   * to prevent items far from the target from pushing it away.
+   */
+  private shouldMeasureDuringScroll = (index: number): boolean => {
+    // No scroll state or not smooth scroll - always allow measurements
+    if (!this.scrollState || this.scrollState.behavior !== 'smooth') {
+      return true
     }
 
-    const index = this.indexFromElement(node)
-    const item = this.measurementsCache[index]
-    if (!item) {
+    const scrollIndex =
+      this.scrollState.index ??
+      this.getVirtualItemForOffset(this.scrollState.lastTargetOffset)?.index
+
+    if (scrollIndex !== undefined && this.range) {
+      // Allow measurements within a buffer range around the scroll target
+      const bufferSize = Math.max(
+        this.options.overscan,
+        Math.ceil((this.range.endIndex - this.range.startIndex) / 2),
+      )
+      const minIndex = Math.max(0, scrollIndex - bufferSize)
+      const maxIndex = Math.min(
+        this.options.count - 1,
+        scrollIndex + bufferSize,
+      )
+      return index >= minIndex && index <= maxIndex
+    }
+
+    return true
+  }
+
+  measureElement = (node: TItemElement | null) => {
+    if (!node) {
+      this.elementsCache.forEach((cached, key) => {
+        if (!cached.isConnected) {
+          this.observer.unobserve(cached)
+          this.elementsCache.delete(key)
+        }
+      })
       return
     }
-    const key = item.key
+
+    const index = this.indexFromElement(node)
+    const key = this.options.getItemKey(index)
     const prevNode = this.elementsCache.get(key)
 
     if (prevNode !== node) {
@@ -884,27 +1021,34 @@ export class Virtualizer<
       this.elementsCache.set(key, node)
     }
 
-    this.resizeItem(index, this.options.measureElement(node, entry, this))
+    // Sync-measure when idle (initial render) or during programmatic scrolling
+    // (scrollToIndex/scrollToOffset) where reconcileScroll needs sizes in the same frame.
+    // During normal user scrolling, skip sync measurement — the RO callback handles it async.
+    if (
+      (!this.isScrolling || this.scrollState) &&
+      this.shouldMeasureDuringScroll(index)
+    ) {
+      this.resizeItem(index, this.options.measureElement(node, undefined, this))
+    }
   }
 
   resizeItem = (index: number, size: number) => {
     const item = this.measurementsCache[index]
-    if (!item) {
-      return
-    }
+    if (!item) return
+
     const itemSize = this.itemSizeCache.get(item.key) ?? item.size
     const delta = size - itemSize
 
     if (delta !== 0) {
       if (
-        this.shouldAdjustScrollPositionOnItemSizeChange !== undefined
+        this.scrollState?.behavior !== 'smooth' &&
+        (this.shouldAdjustScrollPositionOnItemSizeChange !== undefined
           ? this.shouldAdjustScrollPositionOnItemSizeChange(item, delta, this)
-          : item.start < this.getScrollOffset() + this.scrollAdjustments
+          : item.start < this.getScrollOffset() + this.scrollAdjustments)
       ) {
         if (process.env.NODE_ENV !== 'production' && this.options.debug) {
           console.info('correction', delta)
         }
-
         this._scrollToOffset(this.getScrollOffset(), {
           adjustments: (this.scrollAdjustments += delta),
           behavior: undefined,
@@ -918,20 +1062,6 @@ export class Virtualizer<
     }
   }
 
-  measureElement = (node: TItemElement | null | undefined) => {
-    if (!node) {
-      this.elementsCache.forEach((cached, key) => {
-        if (!cached.isConnected) {
-          this.observer.unobserve(cached)
-          this.elementsCache.delete(key)
-        }
-      })
-      return
-    }
-
-    this._measureElement(node, undefined)
-  }
-
   getVirtualItems = memo(
     () => [this.getVirtualIndexes(), this.getMeasurements()],
     (indexes, measurements) => {
@@ -1016,14 +1146,12 @@ export class Virtualizer<
   getOffsetForIndex = (index: number, align: ScrollAlignment = 'auto') => {
     index = Math.max(0, Math.min(index, this.options.count - 1))
 
-    const item = this.measurementsCache[index]
-    if (!item) {
-      return undefined
-    }
-
     const size = this.getSize()
     const scrollOffset = this.getScrollOffset()
 
+    const item = this.measurementsCache[index]
+    if (!item) return
+
     if (align === 'auto') {
       if (item.end >= scrollOffset + size - this.options.scrollPaddingEnd) {
         align = 'end'
@@ -1051,112 +1179,76 @@ export class Virtualizer<
     ] as const
   }
 
-  private isDynamicMode = () => this.elementsCache.size > 0
-
   scrollToOffset = (
     toOffset: number,
-    { align = 'start', behavior }: ScrollToOffsetOptions = {},
+    { align = 'start', behavior = 'auto' }: ScrollToOffsetOptions = {},
   ) => {
-    if (behavior === 'smooth' && this.isDynamicMode()) {
-      console.warn(
-        'The `smooth` scroll behavior is not fully supported with dynamic size.',
-      )
-    }
+    const offset = this.getOffsetForAlignment(toOffset, align)
 
-    this._scrollToOffset(this.getOffsetForAlignment(toOffset, align), {
-      adjustments: undefined,
+    const now = this.now()
+    this.scrollState = {
+      index: null,
+      align,
       behavior,
-    })
+      startedAt: now,
+      lastTargetOffset: offset,
+      stableFrames: 0,
+    }
+
+    this._scrollToOffset(offset, { adjustments: undefined, behavior })
+
+    this.scheduleScrollReconcile()
   }
 
   scrollToIndex = (
     index: number,
-    { align: initialAlign = 'auto', behavior }: ScrollToIndexOptions = {},
+    {
+      align: initialAlign = 'auto',
+      behavior = 'auto',
+    }: ScrollToIndexOptions = {},
   ) => {
-    if (behavior === 'smooth' && this.isDynamicMode()) {
-      console.warn(
-        'The `smooth` scroll behavior is not fully supported with dynamic size.',
-      )
-    }
-
     index = Math.max(0, Math.min(index, this.options.count - 1))
-    this.currentScrollToIndex = index
-
-    let attempts = 0
-    const maxAttempts = 10
-
-    const tryScroll = (currentAlign: ScrollAlignment) => {
-      if (!this.targetWindow) return
-
-      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(() => {
-        if (!this.targetWindow) return
-
-        const verify = () => {
-          // Abort if a new scrollToIndex was called with a different index
-          if (this.currentScrollToIndex !== index) return
-
-          const currentOffset = this.getScrollOffset()
-          const afterInfo = this.getOffsetForIndex(index, align)
-          if (!afterInfo) {
-            console.warn('Failed to get offset for index:', index)
-            return
-          }
-
-          if (!approxEqual(afterInfo[0], currentOffset)) {
-            scheduleRetry(align)
-          }
-        }
 
-        // In dynamic mode, wait an extra frame for ResizeObserver to measure newly visible elements
-        if (this.isDynamicMode()) {
-          this.targetWindow.requestAnimationFrame(verify)
-        } else {
-          verify()
-        }
-      })
+    const offsetInfo = this.getOffsetForIndex(index, initialAlign)
+    if (!offsetInfo) {
+      return
     }
+    const [offset, align] = offsetInfo
 
-    const scheduleRetry = (align: ScrollAlignment) => {
-      if (!this.targetWindow) return
-
-      // Abort if a new scrollToIndex was called with a different index
-      if (this.currentScrollToIndex !== index) return
-
-      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.`,
-        )
-      }
+    const now = this.now()
+    this.scrollState = {
+      index,
+      align,
+      behavior,
+      startedAt: now,
+      lastTargetOffset: offset,
+      stableFrames: 0,
     }
 
-    tryScroll(initialAlign)
+    this._scrollToOffset(offset, { adjustments: undefined, behavior })
+
+    this.scheduleScrollReconcile()
   }
 
-  scrollBy = (delta: number, { behavior }: ScrollToOffsetOptions = {}) => {
-    if (behavior === 'smooth' && this.isDynamicMode()) {
-      console.warn(
-        'The `smooth` scroll behavior is not fully supported with dynamic size.',
-      )
-    }
+  scrollBy = (
+    delta: number,
+    { behavior = 'auto' }: ScrollToOffsetOptions = {},
+  ) => {
+    const offset = this.getScrollOffset() + delta
+    const now = this.now()
 
-    this._scrollToOffset(this.getScrollOffset() + delta, {
-      adjustments: undefined,
+    this.scrollState = {
+      index: null,
+      align: 'start',
       behavior,
-    })
+      startedAt: now,
+      lastTargetOffset: offset,
+      stableFrames: 0,
+    }
+
+    this._scrollToOffset(offset, { adjustments: undefined, behavior })
+
+    this.scheduleScrollReconcile()
   }
 
   getTotalSize = () => {