fix(virtual-core): reconcile index scrolls after pending measurements (#1294)

Author: minwookshin

.changeset/tidy-scroll-measurements.md

@@ -0,0 +1,5 @@
+---
+'@tanstack/virtual-core': patch
+---
+
+Keep scrollToIndex reconciliation active until pending ResizeObserver measurements can update its target, including when useAnimationFrameWithResizeObserver is enabled. Respect an external scroll away from a reached target during this settling period.

packages/react-virtual/e2e/app/cached-measurements/main.tsx

@@ -1,5 +1,6 @@
 import React from 'react'
 import ReactDOM from 'react-dom/client'
+import { flushSync } from 'react-dom'
 import { useVirtualizer } from '@tanstack/react-virtual'
 
 const items = Array.from({ length: 20 }, (_, i) => ({
@@ -11,21 +12,44 @@ const items = Array.from({ length: 20 }, (_, i) => ({
 const App = () => {
   const parentRef = React.useRef<HTMLDivElement>(null)
   const [hidden, setHidden] = React.useState(false)
+  const [expanded, setExpanded] = React.useState(false)
 
   const rowVirtualizer = useVirtualizer({
     count: items.length,
     getScrollElement: () => parentRef.current,
-    estimateSize: (i) => items[i].height,
+    estimateSize: (i) => items[i].height - 10,
     getItemKey: (i) => items[i].id,
     useCachedMeasurements: hidden,
     directDomUpdates: true,
+    overscan: items.length,
+    useAnimationFrameWithResizeObserver: new URLSearchParams(
+      location.search,
+    ).has('raf'),
   })
 
   return (
     <div>
       <button data-testid="toggle" onClick={() => setHidden((h) => !h)}>
         {hidden ? 'Show' : 'Hide'}
       </button>
+      <button
+        onClick={() =>
+          rowVirtualizer.scrollToIndex(items.length - 1, { align: 'end' })
+        }
+      >
+        Scroll to end
+      </button>
+      <button
+        onClick={() => {
+          flushSync(() => setExpanded(true))
+          rowVirtualizer.scrollToIndex(items.length - 1, { align: 'end' })
+        }}
+      >
+        Grow and pin
+      </button>
+      <div data-testid="scrolling">
+        {rowVirtualizer.isScrolling ? 'scrolling' : 'idle'}
+      </div>
       <div
         data-testid="list-wrapper"
         style={{ display: hidden ? 'none' : 'block' }}
@@ -52,7 +76,7 @@ const App = () => {
                     top: 0,
                     left: 0,
                     width: '100%',
-                    height: item.height,
+                    height: item.height + (expanded && v.index === 18 ? 30 : 0),
                   }}
                 >
                   {item.label}

packages/react-virtual/e2e/app/test/cached-measurements.spec.ts

@@ -1,5 +1,33 @@
 import { expect, test } from '@playwright/test'
 
+for (const deferred of [false, true]) {
+  test(`re-pins after a cached row grows (deferred observer: ${deferred})`, async ({
+    page,
+  }) => {
+    await page.goto(`/cached-measurements/${deferred ? '?raf' : ''}`)
+    const scroller = page.locator('#scroll-container')
+    await expect
+      .poll(() => scroller.evaluate((el) => el.scrollHeight))
+      .toBe(980)
+    await page.getByRole('button', { name: 'Scroll to end' }).click()
+    await expect.poll(() => scroller.evaluate((el) => el.scrollTop)).toBe(780)
+    await expect(page.getByTestId('scrolling')).toHaveText('idle')
+
+    await page.getByRole('button', { name: 'Grow and pin' }).click()
+
+    await expect
+      .poll(() => scroller.evaluate((el) => el.scrollHeight))
+      .toBe(1010)
+    await expect
+      .poll(() =>
+        scroller.evaluate(
+          (el) => el.scrollHeight - el.scrollTop - el.clientHeight,
+        ),
+      )
+      .toBe(0)
+  })
+}
+
 test('preserves item sizes when list is hidden with useCachedMeasurements', async ({
   page,
 }) => {

packages/virtual-core/src/index.ts

@@ -394,6 +394,8 @@ type ScrollState = {
 
   // settling
   stableFrames: number
+  // Keep arrival across measurement-driven retargets so external scrolls can cancel.
+  hasReachedTarget: boolean
 }
 
 type PendingScrollAnchor = [
@@ -926,6 +928,18 @@ export class Virtualizer<
             Math.abs(offset - this._intendedScrollOffset) < 1.5
           ) {
             offset = this._intendedScrollOffset
+          } else if (
+            this.scrollState?.index != null &&
+            this.scrollState.hasReachedTarget &&
+            !approxEqual(offset, this.scrollState.lastTargetOffset) &&
+            !approxEqual(offset, this.getScrollStateTarget(this.scrollState)) &&
+            (this._clampedAdjustment === null ||
+              Math.abs(offset - this._clampedAdjustment.maxAtWrite) >= 1.5)
+          ) {
+            // The index scroll reached its target, but an external scroll moved
+            // away while we waited for measurements. Our own measurement updates
+            // (including clamped writes) still need to reconcile.
+            this.scrollState = null
           }
           this._intendedScrollOffset = null
 
@@ -1157,6 +1171,14 @@ export class Virtualizer<
       this.reconcileScroll()
     })
   }
+  private getScrollStateTarget(state: ScrollState) {
+    const offsetInfo = state.toEnd
+      ? ([Math.max(this.getMaxScrollOffset(), 0)] as const)
+      : state.index != null
+        ? this.getOffsetForIndex(state.index, state.align)
+        : undefined
+    return offsetInfo ? offsetInfo[0] : state.lastTargetOffset
+  }
   private reconcileScroll() {
     if (!this.scrollState) return
 
@@ -1170,23 +1192,23 @@ export class Virtualizer<
       return
     }
 
-    const offsetInfo = this.scrollState.toEnd
-      ? ([Math.max(this.getMaxScrollOffset(), 0)] as const)
-      : this.scrollState.index != null
-        ? this.getOffsetForIndex(this.scrollState.index, this.scrollState.align)
-        : undefined
-    const targetOffset = offsetInfo
-      ? offsetInfo[0]
-      : this.scrollState.lastTargetOffset
+    const targetOffset = this.getScrollStateTarget(this.scrollState)
 
-    // 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
+    // Index targets can still depend on cached sizes during the first rAF,
+    // which runs before ResizeObserver delivers pending measurements. Wait
+    // another frame (two when measurements are themselves deferred to rAF)
+    // before retiring an index scroll. Absolute offsets don't need this wait.
+    const STABLE_FRAMES =
+      this.scrollState.index == null
+        ? 1
+        : this.options.useAnimationFrameWithResizeObserver
+          ? 3
+          : 2
 
     const targetChanged = targetOffset !== this.scrollState.lastTargetOffset
 
     if (!targetChanged && approxEqual(targetOffset, this.getScrollOffset())) {
+      this.scrollState.hasReachedTarget = true
       this.scrollState.stableFrames++
       if (this.scrollState.stableFrames >= STABLE_FRAMES) {
         // Final-pass exact landing. The reconcile-stable check uses a 1.01px
@@ -1221,7 +1243,11 @@ export class Virtualizer<
           this.scrollState.behavior === 'smooth' && distance > viewport
 
         this.scrollState.lastTargetOffset = targetOffset
-        if (!keepSmooth) {
+        if (keepSmooth) {
+          // A smooth retarget travels again, so its intermediate scroll
+          // events must not read as an external scroll away from the target.
+          this.scrollState.hasReachedTarget = false
+        } else {
           this.scrollState.behavior = 'auto'
         }
 
@@ -1955,6 +1981,7 @@ export class Virtualizer<
       startedAt: now,
       lastTargetOffset: offset,
       stableFrames: 0,
+      hasReachedTarget: false,
     }
 
     this._scrollToOffset(offset, { adjustments: undefined, behavior })
@@ -1989,6 +2016,7 @@ export class Virtualizer<
       startedAt: now,
       lastTargetOffset: offset,
       stableFrames: 0,
+      hasReachedTarget: approxEqual(offset, this.getScrollOffset()),
     }
 
     this._scrollToOffset(offset, { adjustments: undefined, behavior })
@@ -2010,6 +2038,7 @@ export class Virtualizer<
       startedAt: now,
       lastTargetOffset: offset,
       stableFrames: 0,
+      hasReachedTarget: false,
     }
 
     this._scrollToOffset(offset, { adjustments: undefined, behavior })
@@ -2033,6 +2062,7 @@ export class Virtualizer<
         startedAt: this.now(),
         lastTargetOffset: offset,
         stableFrames: 0,
+        hasReachedTarget: approxEqual(offset, this.getScrollOffset()),
       }
 
       this._scrollToOffset(offset, { adjustments: undefined, behavior })