feat(virtual-core): Optimize scroll adjustments with batching and add backward scroll option

Author: 전예진(양파유닛)

.changeset/itchy-moons-push.md

@@ -0,0 +1,5 @@
+---
+'@tanstack/virtual-core': minor
+---
+
+Optimize scroll adjustments with batching and add backward scroll option

packages/virtual-core/src/index.ts

@@ -348,6 +348,7 @@ export interface VirtualizerOptions<
   enabled?: boolean
   isRtl?: boolean
   useAnimationFrameWithResizeObserver?: boolean
+  disableScrollAdjustmentOnBackwardScroll?: boolean
 }
 
 export class Virtualizer<
@@ -370,6 +371,8 @@ export class Virtualizer<
   scrollOffset: number | null = null
   scrollDirection: ScrollDirection | null = null
   private scrollAdjustments = 0
+  private pendingAdjustmentDeltas: Array<number> = []
+  private adjustmentBatchTimer: number | null = null
   shouldAdjustScrollPositionOnItemSizeChange:
     | undefined
     | ((
@@ -447,6 +450,7 @@ export class Virtualizer<
       isRtl: false,
       useScrollendEvent: false,
       useAnimationFrameWithResizeObserver: false,
+      disableScrollAdjustmentOnBackwardScroll: false,
       ...opts,
     }
   }
@@ -483,6 +487,14 @@ export class Virtualizer<
     this.unsubs.filter(Boolean).forEach((d) => d!())
     this.unsubs = []
     this.observer.disconnect()
+    
+    // Clear adjustment batch timer
+    if (this.adjustmentBatchTimer !== null && this.targetWindow) {
+      this.targetWindow.cancelAnimationFrame(this.adjustmentBatchTimer)
+      this.adjustmentBatchTimer = null
+    }
+    this.pendingAdjustmentDeltas = []
+    
     this.scrollElement = null
     this.targetWindow = null
   }
@@ -879,6 +891,21 @@ export class Virtualizer<
     }
 
     if (node.isConnected) {
+      // Check if we should skip remeasuring during backward scroll
+      if (
+        this.options.disableScrollAdjustmentOnBackwardScroll &&
+        this.scrollDirection === 'backward' &&
+        this.isScrolling
+       ) {
+        const isAlreadyMeasured = this.itemSizeCache.has(key)
+        if (isAlreadyMeasured) {
+          // Skip remeasuring to prevent stuttering during backward scroll
+          // Use cached measurement instead
+          return
+        }
+      }
+
+      // Measure and update size
       this.resizeItem(index, this.options.measureElement(node, entry, this))
     }
   }
@@ -892,19 +919,19 @@ export class Virtualizer<
     const delta = size - itemSize
 
     if (delta !== 0) {
-      if (
+      const shouldAdjust =
         this.shouldAdjustScrollPositionOnItemSizeChange !== undefined
           ? this.shouldAdjustScrollPositionOnItemSizeChange(item, delta, this)
           : item.start < this.getScrollOffset() + this.scrollAdjustments
-      ) {
+
+      if (shouldAdjust) {
         if (process.env.NODE_ENV !== 'production' && this.options.debug) {
           console.info('correction', delta)
         }
 
-        this._scrollToOffset(this.getScrollOffset(), {
-          adjustments: (this.scrollAdjustments += delta),
-          behavior: undefined,
-        })
+        // Add to batch instead of immediate adjustment
+        this.pendingAdjustmentDeltas.push(delta)
+        this.scheduleAdjustmentBatch()
       }
 
       this.pendingMeasuredCacheIndexes.push(item.index)
@@ -914,6 +941,45 @@ export class Virtualizer<
     }
   }
 
+  private scheduleAdjustmentBatch = () => {
+    if (!this.targetWindow) return
+
+    // Cancel existing timer if any
+    if (this.adjustmentBatchTimer !== null) {
+      this.targetWindow.cancelAnimationFrame(this.adjustmentBatchTimer)
+    }
+
+    // Schedule batch flush on next animation frame
+    this.adjustmentBatchTimer = this.targetWindow.requestAnimationFrame(() => {
+      this.flushAdjustments()
+    })
+  }
+
+  private flushAdjustments = () => {
+    if (this.pendingAdjustmentDeltas.length === 0) {
+      this.adjustmentBatchTimer = null
+      return
+    }
+
+    // Sum all pending deltas
+    const totalDelta = this.pendingAdjustmentDeltas.reduce(
+      (sum, delta) => sum + delta,
+      0,
+    )
+
+    // Clear batch
+    this.pendingAdjustmentDeltas = []
+    this.adjustmentBatchTimer = null
+
+    // Apply single adjustment for all batched changes
+    if (totalDelta !== 0) {
+      this._scrollToOffset(this.getScrollOffset(), {
+        adjustments: (this.scrollAdjustments += totalDelta),
+        behavior: undefined,
+      })
+    }
+  }
+
   measureElement = (node: TItemElement | null | undefined) => {
     if (!node) {
       this.elementsCache.forEach((cached, key) => {