fix(virtual-core): reset iOS gesture/deferral state on cleanup (#1220)

Author: basnijholt

.changeset/reset-ios-deferral-state-on-cleanup.md

@@ -0,0 +1,5 @@
+---
+'@tanstack/virtual-core': patch
+---
+
+Reset iOS gesture/deferral state in `cleanup()` so it no longer leaks across scroll element swaps.

packages/virtual-core/src/index.ts

@@ -741,6 +741,19 @@ export class Virtualizer<
       this.rafId = null
     }
     this.scrollState = null
+    // The iOS gesture/deferral state is scoped to the current scroll
+    // element: the touch listeners that maintain it were just removed, and
+    // an in-flight touch keeps targeting the old element (implicit touch
+    // capture), so the new element never reports it. Carrying the state
+    // over would replay a stale deferred delta on the new element's first
+    // flush, and a cleanup that lands mid-touch or inside the post-touchend
+    // grace window would strand _iosTouching / _iosJustTouchEnded as true
+    // (the listener unsub clears the grace timer, and with it the only
+    // pending reset of the flag), deferring every adjustment on the new
+    // element until its next touch cycle.
+    this._iosDeferredAdjustment = 0
+    this._iosTouching = false
+    this._iosJustTouchEnded = false
     this.scrollElement = null
     this.targetWindow = null
   }

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

@@ -1810,6 +1810,134 @@ test('iOS Phase 1: new touchstart during grace window cancels pending flush time
   })
 })
 
+// Helper for the element-swap tests below: like makeIOSVirtualizerWithRealEl
+// but getScrollElement reads a mutable holder, so tests can swap the scroll
+// element and re-run _willUpdate (which triggers cleanup + re-attach).
+function makeIOSVirtualizerWithSwappableEl(
+  scrollToFn: ReturnType<typeof vi.fn>,
+  mockWindow: any,
+  { startScrolling = false }: { startScrolling?: boolean } = {},
+) {
+  const makeEl = () =>
+    makeMockScrollElement({
+      scrollTop: 100,
+      scrollLeft: 0,
+      scrollHeight: 500,
+      clientHeight: 200,
+      offsetHeight: 200,
+      ownerDocument: { defaultView: mockWindow },
+    })
+  const holder = { el: makeEl() }
+  let scrollCallback: ((offset: number, isScrolling: boolean) => void) | null =
+    null
+  const v = new Virtualizer({
+    count: 10,
+    estimateSize: () => 50,
+    getScrollElement: () => holder.el as any,
+    scrollToFn,
+    observeElementRect: () => {},
+    observeElementOffset: (_inst, cb) => {
+      scrollCallback = cb
+      cb(100, startScrolling)
+      return () => {}
+    },
+  })
+  v._willUpdate()
+  v['getMeasurements']()
+  return {
+    v,
+    holder,
+    makeEl,
+    getScrollCallback: () => scrollCallback!,
+  }
+}
+
+test('iOS Phase 1: scroll-element swap does not replay a stale deferred adjustment', () => {
+  withFakeIOSUserAgent(() => {
+    const scrollToFn = vi.fn()
+    const mockWindow = {
+      setTimeout: globalThis.setTimeout.bind(globalThis),
+      clearTimeout: globalThis.clearTimeout.bind(globalThis),
+    }
+    const { v, holder, makeEl, getScrollCallback } =
+      makeIOSVirtualizerWithSwappableEl(scrollToFn, mockWindow, {
+        startScrolling: true,
+      })
+    scrollToFn.mockClear()
+
+    // A resize above the viewport during the live scroll defers its
+    // adjustment instead of writing scrollTop.
+    v.resizeItem(0, 100)
+    expect(scrollToFn).not.toHaveBeenCalled()
+    expect(v['_iosDeferredAdjustment']).toBe(50)
+
+    // The scroll element is swapped while the deferral is pending — the
+    // delta was computed against the old element's content and must not
+    // survive into the new element.
+    holder.el = makeEl()
+    v._willUpdate()
+    expect(v['_iosDeferredAdjustment']).toBe(0)
+
+    // The new element's first quiescence must not write the stale delta.
+    scrollToFn.mockClear()
+    getScrollCallback()(100, false)
+    expect(scrollToFn).not.toHaveBeenCalled()
+  })
+})
+
+test('iOS Phase 1: scroll-element swap mid-touch does not strand _iosTouching', () => {
+  withFakeIOSUserAgent(() => {
+    const mockWindow = {
+      setTimeout: globalThis.setTimeout.bind(globalThis),
+      clearTimeout: globalThis.clearTimeout.bind(globalThis),
+    }
+    const { v, holder, makeEl } = makeIOSVirtualizerWithSwappableEl(
+      vi.fn(),
+      mockWindow,
+    )
+    dispatchTouchEvent(holder.el, 'touchstart')
+    expect(v['_iosTouching']).toBe(true)
+
+    // The in-flight touch keeps targeting the old element (implicit touch
+    // capture), so the new element will never deliver its touchend. Without
+    // a reset, every adjustment on the new element would be deferred and
+    // the flush blocked until the user's next full touch cycle.
+    holder.el = makeEl()
+    v._willUpdate()
+    expect(v['_iosTouching']).toBe(false)
+  })
+})
+
+test('iOS Phase 1: scroll-element swap during grace window does not strand _iosJustTouchEnded', () => {
+  withFakeIOSUserAgent(() => {
+    let timerId = 0
+    const timers = new Map<number, () => void>()
+    const mockWindow = {
+      setTimeout: (fn: () => void, _ms: number) => {
+        const id = ++timerId
+        timers.set(id, fn)
+        return id
+      },
+      clearTimeout: (id: number) => timers.delete(id),
+    }
+    const { v, holder, makeEl } = makeIOSVirtualizerWithSwappableEl(
+      vi.fn(),
+      mockWindow,
+    )
+    dispatchTouchEvent(holder.el, 'touchstart')
+    dispatchTouchEvent(holder.el, 'touchend')
+    expect(v['_iosJustTouchEnded']).toBe(true)
+
+    // Swapping inside the grace window removes the listeners and clears the
+    // grace timer — which was the only pending reset of the flag. Without
+    // the cleanup reset the flag would stay true indefinitely.
+    holder.el = makeEl()
+    v._willUpdate()
+    expect(v['_iosJustTouchEnded']).toBe(false)
+    expect(timers.size).toBe(0)
+  })
+})
+
 // ─── Phase 2a: subpixel scrollTop reconciliation ─────────────────────────────
 
 test('Phase 2a: browser-rounded scrollTop after self-write is reconciled to intended value', () => {