fix(virtual-core): stop viewport-spanning item growth from drifting scroll (#1236)

Author: piecyk

.changeset/fix-spanning-item-scroll-drift.md

@@ -0,0 +1,5 @@
+---
+'@tanstack/virtual-core': patch
+---
+
+Stop the default scroll-adjustment heuristic from drifting the viewport when a viewport-spanning item grows. Previously any item whose top sat above the fold (`itemStart < scrollOffset`) had its size delta compensated on every re-measure — including a streaming chat message that spans the fold and grows at its bottom, dragging `scrollTop` downward token by token (#1218). Re-measurements now only compensate items that are _entirely_ above the fold (`itemStart + itemSize <= scrollOffset`); growth below the anchor point leaves the scroll position untouched. First measurements (estimate→actual) still compensate any above-fold item, and a custom `shouldAdjustScrollPositionOnItemSizeChange` still overrides the default.

packages/virtual-core/src/index.ts

@@ -1555,6 +1555,25 @@ export class Virtualizer<
         this.scrollState?.behavior !== 'smooth' &&
         this.getVirtualDistanceFromEnd() <= this.options.scrollEndThreshold
       const prevTotalSize = wasAtEnd ? this.getTotalSize() : 0
+      // Default anchoring predicate (used unless the consumer supplies a
+      // custom shouldAdjustScrollPositionOnItemSizeChange).
+      const scrollOffsetWithAdj =
+        this.getScrollOffset() + this.scrollAdjustments
+      const isFirstMeasure = !this.itemSizeCache.has(key)
+      const defaultShouldAdjust = isFirstMeasure
+        ? // First measurement: compensate any item whose top sits above the
+          // fold — the estimate→actual delta must be corrected regardless of
+          // scroll direction, since the whole estimated block was above it.
+          itemStart < scrollOffsetWithAdj
+        : // Re-measurement: only compensate an item that is ENTIRELY above the
+          // fold. An item that merely *spans* the fold (top above, bottom
+          // below — e.g. a streaming chat message growing at its bottom)
+          // changes size *below* the anchor point, so shifting scrollTop by the
+          // delta would drag the viewport downward on every growth (#1218).
+          // Also skip during backward scroll to avoid the "items jump while
+          // scrolling up" cascade.
+          itemStart + itemSize <= scrollOffsetWithAdj &&
+          this.scrollDirection !== 'backward'
       const shouldAdjustScroll =
         this.scrollState?.behavior !== 'smooth' &&
         (this.shouldAdjustScrollPositionOnItemSizeChange !== undefined
@@ -1572,15 +1591,7 @@ export class Virtualizer<
               delta,
               this,
             )
-          : // Default: adjust when the resize is an above-viewport item.
-            // First measurement (!has(key)): always adjust — the item
-            // has never been sized, so the estimate→actual delta must
-            // be compensated regardless of scroll direction.
-            // Re-measurement (has(key)): skip during backward scroll
-            // to avoid the "items jump while scrolling up" cascade.
-            itemStart < this.getScrollOffset() + this.scrollAdjustments &&
-            (!this.itemSizeCache.has(key) ||
-              this.scrollDirection !== 'backward'))
+          : defaultShouldAdjust)
 
       if (this.pendingMin === null || index < this.pendingMin) {
         this.pendingMin = index

packages/virtual-core/tests/index.test.ts

@@ -3415,3 +3415,81 @@ test('anchorTo end: setOptions re-anchor clamps tracked scrollOffset at 0 (#1229
 
   expect(virtualizer.scrollOffset).toBe(0)
 })
+
+// ─── #1218: viewport-spanning item growth must not drift the viewport ─────────
+// A streaming chat message whose top is scrolled above the fold but whose
+// bottom extends below it grows at its bottom. That growth happens *below* the
+// anchor point (the fold), so scrollTop must stay put. Only an item that is
+// ENTIRELY above the fold should shift scrollTop on re-measure.
+function makeAdjustmentVirtualizer(scrollTop: number) {
+  const scrollToFn = vi.fn(elementScroll)
+  let scrollCallback: ((offset: number, isScrolling: boolean) => void) | null =
+    null
+  const el = {
+    scrollTop,
+    scrollLeft: 0,
+    scrollHeight: 100000,
+    clientHeight: 200,
+    offsetHeight: 200,
+    scrollTo: vi.fn(({ top }: { top: number }) => {
+      el.scrollTop = top
+    }),
+    addEventListener: () => {},
+    removeEventListener: () => {},
+  }
+  const v = new Virtualizer<any, any>({
+    count: 50,
+    estimateSize: () => 50,
+    getScrollElement: () => el as any,
+    scrollToFn,
+    observeElementRect: (_i, cb) => {
+      cb({ width: 300, height: 200 })
+    },
+    observeElementOffset: (_i, cb) => {
+      scrollCallback = cb
+      cb(scrollTop, false) // settled, not scrolling
+      return () => {}
+    },
+  })
+  v._willUpdate()
+  v['getMeasurements']()
+  return { v, scrollToFn }
+}
+
+test('#1218: re-measuring a viewport-spanning item does not drift scroll', () => {
+  // Viewport 175..375, items 50px by estimate. Item 3: start=150, end=200 —
+  // spans the fold at 175.
+  const { v, scrollToFn } = makeAdjustmentVirtualizer(175)
+  v.resizeItem(3, 60) // seed the size cache (item still spans the fold)
+  scrollToFn.mockClear()
+
+  const before = v.scrollOffset
+  v.resizeItem(3, 160) // stream: grow at the bottom by 100 (below the fold)
+
+  expect(v.scrollOffset).toBe(before)
+  expect(scrollToFn).not.toHaveBeenCalled()
+})
+
+test('#1218: re-measuring an entirely-above item still anchors (no regression)', () => {
+  // Item 1: start=50, end=100 — fully above the fold at 175.
+  const { v } = makeAdjustmentVirtualizer(175)
+  v.resizeItem(1, 60)
+  const before = v.scrollOffset!
+
+  v.resizeItem(1, 160) // grows by 100 entirely above the fold
+
+  // scrollTop shifts by the delta so content below the fold stays put.
+  expect(v.scrollOffset).toBe(before + 100)
+})
+
+test('#1218: first measurement of a spanning item still compensates', () => {
+  // First measurement (estimate→actual) always compensates an above-fold top,
+  // regardless of spanning — the estimated block sat above the fold. Item 3
+  // starts at 150 (above fold 175) and has never been measured.
+  const { v } = makeAdjustmentVirtualizer(175)
+  const before = v.scrollOffset!
+
+  v.resizeItem(3, 120) // first measure: 50 -> 120, delta +70
+
+  expect(v.scrollOffset).toBe(before + 70)
+})