fix(virtual-core): invalidate measurements when gap option changes (#1223)

Author: 2wheeh

.changeset/eighty-ants-slide.md

@@ -0,0 +1,5 @@
+---
+'@tanstack/virtual-core': patch
+---
+
+Made gap option changes invalidate measurements

packages/react-virtual/tests/index.test.tsx

@@ -27,6 +27,7 @@ interface ListProps {
   itemSize?: number
   rangeExtractor?: (range: Range) => number[]
   dynamic?: boolean
+  gap?: number
 }
 
 function List({
@@ -37,6 +38,7 @@ function List({
   itemSize,
   rangeExtractor,
   dynamic,
+  gap,
 }: ListProps) {
   renderer()
 
@@ -57,6 +59,7 @@ function List({
     },
     measureElement: () => itemSize ?? 0,
     rangeExtractor,
+    gap,
   })
 
   React.useEffect(() => {
@@ -160,6 +163,23 @@ test('should handle count change', () => {
   expect(screen.queryByText('Row 5')).not.toBeInTheDocument()
 })
 
+test('should handle gap change', () => {
+  const { rerender } = render(<List count={10} gap={0} />)
+
+  expect(screen.getByTestId('item-1')).toHaveStyle({
+    transform: 'translateY(50px)',
+  })
+
+  rerender(<List count={10} gap={40} />)
+
+  expect(screen.getByTestId('item-1')).toHaveStyle({
+    transform: 'translateY(90px)',
+  })
+  expect(screen.getByTestId('item-2')).toHaveStyle({
+    transform: 'translateY(180px)',
+  })
+})
+
 test('should handle handle height change', () => {
   const { rerender } = render(<List count={0} height={0} />)
 

packages/virtual-core/src/index.ts

@@ -1091,6 +1091,7 @@ export class Virtualizer<
       this.options.enabled,
       this.options.lanes,
       this.options.laneAssignmentMode,
+      this.options.gap,
     ],
     (
       count,
@@ -1100,6 +1101,7 @@ export class Virtualizer<
       enabled,
       lanes,
       laneAssignmentMode,
+      gap,
     ) => {
       const lanesChanged =
         this.prevLanes !== undefined && this.prevLanes !== lanes
@@ -1120,6 +1122,7 @@ export class Virtualizer<
         enabled,
         lanes,
         laneAssignmentMode,
+        gap,
       }
     },
     {
@@ -1138,6 +1141,7 @@ export class Virtualizer<
         enabled,
         lanes,
         laneAssignmentMode,
+        gap,
       },
       _itemSizeCacheVersion,
     ) => {
@@ -1196,7 +1200,6 @@ export class Virtualizer<
       // At n=100k this drops cold-mount cost from ~2.5ms (eager object
       // allocation) to roughly the cost of a single typed-array fill.
       if (lanes === 1) {
-        const gap = this.options.gap
         // Reuse flat backing if large enough; else grow (preserving data
         // before `min` to mirror the slice-and-rebuild contract).
         const need = count * 2
@@ -1276,7 +1279,7 @@ export class Virtualizer<
           const prevInLane =
             prevIndex !== undefined ? measurements[prevIndex] : undefined
           start = prevInLane
-            ? prevInLane.end + this.options.gap
+            ? prevInLane.end + gap
             : paddingStart + scrollMargin
         } else if (filledLanes === lanes) {
           // No cache, every lane seeded: place in the shortest lane.
@@ -1295,7 +1298,7 @@ export class Virtualizer<
             }
           }
           lane = bestLane
-          start = bestEnd + this.options.gap
+          start = bestEnd + gap
 
           if (shouldCacheLane) {
             this.laneAssignments.set(i, lane)

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

@@ -1271,6 +1271,50 @@ test('lazy fast path: respects paddingStart + scrollMargin + gap', () => {
   expect(m[1]!.size).toBe(40)
 })
 
+test('changing gap invalidates cached measurements', () => {
+  const baseOptions = {
+    count: 5,
+    estimateSize: () => 50,
+    getScrollElement: () => null,
+    scrollToFn: vi.fn(),
+    observeElementRect: vi.fn(),
+    observeElementOffset: vi.fn(),
+  }
+  const v = new Virtualizer({ ...baseOptions, gap: 0 })
+  let m = v['getMeasurements']()
+  expect(m[1]!.start).toBe(50)
+  expect(v.getTotalSize()).toBe(250)
+
+  v.setOptions({ ...baseOptions, gap: 40 })
+  m = v['getMeasurements']()
+  // start(i) = i * (size + gap); previously stale starts survived a gap-only
+  // change because gap was missing from the measurement memo dependencies
+  expect(m[1]!.start).toBe(90)
+  expect(m[2]!.start).toBe(180)
+  expect(v.getTotalSize()).toBe(410)
+})
+
+test('changing gap invalidates cached measurements (multi-lane)', () => {
+  const baseOptions = {
+    count: 4,
+    lanes: 2,
+    estimateSize: () => 50,
+    getScrollElement: () => null,
+    scrollToFn: vi.fn(),
+    observeElementRect: vi.fn(),
+    observeElementOffset: vi.fn(),
+  }
+  const v = new Virtualizer({ ...baseOptions, gap: 0 })
+  let m = v['getMeasurements']()
+  expect(m[2]!.start).toBe(50)
+
+  v.setOptions({ ...baseOptions, gap: 40 })
+  m = v['getMeasurements']()
+  // second row in each lane starts at prevInLane.end + gap
+  expect(m[2]!.start).toBe(90)
+  expect(m[3]!.start).toBe(90)
+})
+
 test('lazy fast path: VirtualItem fields are correct', () => {
   const v = new Virtualizer({
     count: 3,