fix(virtual-core): let a user scroll end a non-smooth scrollToIndex before it lands #1310
main fromrefs/pull/1310/head·merged by piecyk Stacked on #1309. This branch contains #1309's commit; review only the last commit,
fix(virtual-core): let a user scroll end a non-smooth scrollToIndex before it lands. I'll rebase and mark it ready once #1309 merges.
🎯 Changes#
The scroll handler treated a scroll event as the user leaving an index scroll only after reconcile had seen the target reached. When the target keeps moving while rows are measured (or, on iOS, when a write is ignored under a finger) the scroll never "reaches" it, so the state stays alive after the user scrolls away, and the next measurement that moves the target writes them back to it. Reproduced on desktop and on iOS in #1307; pinned by two test.fails in #1308.
scroll event that isn't the read-back of our own write
if index scroll
- && hasReachedTarget
+ && (hasReachedTarget || !startedSmooth)
&& offset not ≈ lastTargetOffset and not ≈ fresh target
&& not a clamped compensation read-back
end the index scroll
ScrollState
+ startedSmooth // set when the command starts; `behavior` is switched to
+ // 'auto' by reconcile for the final approach
- Non-smooth: the write lands at once, so any other event is the user's.
- Clamped writes (#1294): a read-back short of what we wrote because the scroll max shrank reports the max, where the fresh target also clamps, so the existing "≈ fresh target" check keeps it reconciling. Clamped compensation writes stay covered by
_clampedAdjustment. - Smooth: unchanged. Animation events look like a user's, so a smooth scroll still yields only after reaching its target. Decided by
startedSmoothrather thanbehavior, because WebKit can deliver animation events after reconcile's switch to'auto'.
Evidence#
| Case | before | after |
|---|---|---|
| #1308 "a drag that never reached the target is not pulled back when the target moves" (iOS, write ignored under a finger) | 2550 (pulled back) | 60 |
| #1308 "a scroll away from a target that moved before landing is not pulled back, non-iOS" | 2600 | 1050 |
Smooth scrollToIndex switched to 'auto' near the end, then a late animation event | kept | kept (new test; fails if the check uses behavior) |
| #1294 clamp: read-back at a shrunken max before the target is reached | kept | kept |
virtual-core: 233 passed + 5 expected failures (remaining #1307 iOS cases). Mutation check: every part of the condition is covered.- react-virtual
cached-measurements,smooth-scroll,smooth-prepend,scrollin Chromium, Firefox and WebKit: all pass. WebKit A/B against the parent, 4 runs each interleaved: 0 vs 0 failures (checkingbehaviorinstead ofstartedSmoothgave 8 failures). - react-virtual e2e 39/39; Marko chat "does NOT follow appends while reading history" 10/10;
pnpm run test:prgreen.
Merge Danger#
Door: two-way. One condition in the scroll handler plus a flag set where scroll commands start.
Blast Radius: non-smooth scrollToIndex / scrollToEnd while they haven't been seen to land. A user scroll (wheel inertia included) now ends them immediately instead of being pulled back by the next measurement, which matches native scrollIntoView. A non-user event in that window that is neither our read-back nor at the target would now end the scroll too; a differential sweep over 98 scenarios (align, lanes, gap, paddings, scroll paddings, scrollMargin, horizontal, window scroller, custom adjust predicate, anchorTo: 'end', rAF-deferred ResizeObserver, iOS) found none.
Known and unchanged: a prepend (anchorTo: 'end') committing before an index write's read-back still loses the scroll (on main it was stranded, then pulled back later). Tracked with the other shared stalls in #1307.
✅ Checklist#
- I have followed the steps in the Contributing guide.
- I have tested this code locally with
pnpm run test:pr.
🚀 Release Impact#
- This change affects published code, and I have generated a changeset.
- This change is docs/CI/dev-only (no release).
🤖 Generated with Claude Code
Summary by CodeRabbit#
- Bug Fixes
- User-initiated scrolling no longer gets pulled back to an outdated
scrollToIndextarget when a non-smooth scroll is interrupted before reaching it. - Improved handling of browser-clamped scroll targets and late scroll events.
- User-initiated scrolling no longer gets pulled back to an outdated
- 1
No actionable comments were generated in the recent review. 🎉
ℹ️ Recent review info
-
⚙️ Run configuration
-
- Configuration used: defaults
- Review profile: CHILL
- Plan: Advanced
- Run ID:
1126db8d-b0ec-40be-b260-b97df1676390
📥 Commits
-
Reviewing files that changed from the base of the PR and between e7a0a92e4bec5ecd0a37659e951c8e8ff72e0207 and f596cb0bfc0633a2d236134b715300372f1073a3.
📒 Files selected for processing (3)
-
.changeset/index-scroll-user-interrupt.mdpackages/virtual-core/src/index.tspackages/virtual-core/tests/index.test.ts
Included review availability: This review used your included allowance. Your plan provides up to 8 included reviews per hour; 5 remain after this review.
-
📝 Walkthrough
-
Walkthrough#
Scroll commands now record whether they began with smooth behavior. Index-scroll reconciliation uses that state to distinguish non-smooth interruptions from smooth-scroll events. Tests cover user scrolling, late events, and writes clamped by a shrinking sizer.
Changes#
Index Scroll Interruption
Layer / File(s) Summary Scroll behavior and reconciliation
packages/virtual-core/src/index.ts,packages/virtual-core/tests/index.test.ts,.changeset/index-scroll-user-interrupt.mdScroll commands record whether they started with smooth behavior. Reconciliation can cancel a non-smooth index scroll before it reaches its target. Tests cover user interruptions, late smooth-scroll events, and a clamped write; the changeset describes the fix. Priority: ⬇️ Low
Estimated code review effort: 2 (Simple) | ~15 minutes
Change: Bug fix
Merge Risk: 🔵 Low · up to
f596cThe user-scroll interruption fix is mergeable with awareness that an unobserved clamped-scroll ordering could leave a requested row off-target.
Pre-merge checks |
5-
✅ Passed checks (5 passed)
-
Check name Status Explanation Title check The title clearly and concisely identifies the main change: allowing user scrolling to end a non-smooth scrollToIndex before it reaches its target. Description check The description includes the required Changes, Checklist, and Release Impact sections. It explains the motivation, implementation, testing evidence, release impact, and known limitations. Both checkli… Docstring Coverage Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 1 functions across 2 files. (1 skipped: 1 … Linked Issues check Check skipped because no linked issues were found for this pull request. Out of Scope Changes check Check skipped because no linked issues were found for this pull request.
-
✨ Finishing Touches
-
🧪 Generate unit tests (beta)
-
- Create a new PR
-
- Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts
Warning
Some tools did not complete. Review the errors below.
🔧 ESLint
-
If the error stems from missing dependencies, add them to the package.json file. For unrecoverable errors (e.g., due to private dependencies), disable the tool in the CodeRabbit configuration.
packages/virtual-core/tests/index.test.ts
-
Parsing error: "parserOptions.project" has been provided for
@typescript-eslint/parser. The file was not found in any of the provided project(s): packages/virtual-core/tests/index.test.ts
-
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.
Comment `@coderabbitai help` to get the list of available commands.-
View your CI Pipeline Execution ↗ for commit e29a0223a9342261b68c543ea15cfd2d46cf43b7
Command Status Duration Result nx affected --targets=test:sherif,test:knip,tes...✅ Succeeded 4m 7s View ↗ nx run-many --target=build --exclude=examples/**✅ Succeeded 14s View ↗
☁️ Nx Cloud last updated this comment at
2026-10-12 10:42:06UTCMore templates
- @tanstack/virtual-example-angular-chat
- @tanstack/virtual-example-angular-dynamic
- @tanstack/virtual-example-angular-fixed
- @tanstack/virtual-example-angular-infinite-scroll
- @tanstack/virtual-example-angular-padding
- @tanstack/virtual-example-angular-smooth-scroll
- @tanstack/virtual-example-angular-sticky
- @tanstack/virtual-example-angular-table
- @tanstack/virtual-example-angular-variable
- @tanstack/virtual-example-angular-window
- tanstack-lit-virtual-example-dynamic
- tanstack-lit-virtual-example-fixed
- tanstack-marko-virtual-example-chat
- tanstack-marko-virtual-example-chat-pretext
- tanstack-marko-virtual-example-dynamic
- tanstack-marko-virtual-example-fixed
- tanstack-marko-virtual-example-grid
- tanstack-marko-virtual-example-infinite-scroll
- tanstack-marko-virtual-example-padding
- tanstack-marko-virtual-example-pretext
- tanstack-marko-virtual-example-scroll-padding
- tanstack-marko-virtual-example-smooth-scroll
- tanstack-marko-virtual-example-ssr
- tanstack-marko-virtual-example-ssr-fetch
- tanstack-marko-virtual-example-ssr-restore
- tanstack-marko-virtual-example-ssr-slice
- tanstack-marko-virtual-example-sticky
- tanstack-marko-virtual-example-table
- tanstack-marko-virtual-example-variable
- tanstack-marko-virtual-example-window
- tanstack-marko-virtual-example-window-ssr-slice
- tanstack-react-virtual-example-chat
- tanstack-react-virtual-example-dynamic
- tanstack-react-virtual-example-fixed
- tanstack-react-virtual-example-infinite-scroll
- tanstack-react-virtual-example-padding
- tanstack-react-virtual-example-pretext
- tanstack-react-virtual-example-scroll-padding
- tanstack-react-virtual-example-smooth-scroll
- tanstack-react-virtual-example-sticky
- tanstack-react-virtual-example-table
- tanstack-react-virtual-example-variable
- tanstack-react-virtual-example-window
- tanstack-svelte-virtual-example-dynamic
- tanstack-svelte-virtual-example-fixed
- tanstack-svelte-virtual-example-infinite-scroll
- tanstack-svelte-virtual-example-smooth-scroll
- tanstack-svelte-virtual-example-sticky
- tanstack-svelte-virtual-example-table
- tanstack-vue-virtual-example-dynamic
- tanstack-vue-virtual-example-fixed
- tanstack-vue-virtual-example-infinite-scroll
- tanstack-vue-virtual-example-padding
- tanstack-vue-virtual-example-scroll-padding
- tanstack-vue-virtual-example-smooth-scroll
- tanstack-vue-virtual-example-sticky
- tanstack-vue-virtual-example-table
- tanstack-vue-virtual-example-variable
@tanstack/angular-virtual
npm i https://pkg.pr.new/@tanstack/angular-virtual@1310@tanstack/lit-virtual
npm i https://pkg.pr.new/@tanstack/lit-virtual@1310@tanstack/marko-virtual
npm i https://pkg.pr.new/@tanstack/marko-virtual@1310@tanstack/react-virtual
npm i https://pkg.pr.new/@tanstack/react-virtual@1310@tanstack/solid-virtual
npm i https://pkg.pr.new/@tanstack/solid-virtual@1310@tanstack/svelte-virtual
npm i https://pkg.pr.new/@tanstack/svelte-virtual@1310@tanstack/virtual-core
npm i https://pkg.pr.new/@tanstack/virtual-core@1310@tanstack/vue-virtual
npm i https://pkg.pr.new/@tanstack/vue-virtual@1310commit:
f596cb0Reviewed the last commit at 2b7ac8b4. The fix works in real browsers, I found no regression, and it also removes a flake in the Chromium chat spec.
The fix, in real browsers. Plain-DOM list on
virtual-core, 1000 rows estimated at 50px and measuring 50–109px.scrollToIndex(500, { align: 'start' }), thenscrollTop -= 300. Same numbers in Chromium, Firefox and WebKit:user scroll one frame later user scroll in the same task main, #1309pulled back, row 500 at the top pulled back, row 500 at the top this PR stays, moved only by the 110px of size corrections stays, moved only by 115px of corrections It fixes the
chat.spec.tsflake. react-virtual e2e, Chromium, 40 repetitions per revision in interleaved blocks of 10,--retries=0:Test main#1309 this PR #1311 keeps visible messages stable when history is prepended 18/40 19/40 40/40 40/40 does not follow appended messages while reading history 29/40 37/40 40/40 40/40 The first one is the
chat.spec.ts:73timeout I reported in #1308.No landing regression. The 34,200 uninterrupted index scrolls from my #1309 comment land identically on #1309 and on this PR. The only difference is that 54 runs that sat off-target until the 5s safety valve on #1309 now retire at the next scroll-rest event, at the same position.
Mutation check. Checking
behaviorinstead ofstartedSmooth, reverting tohasReachedTargetonly, and always yielding each fail the tests you would expect. Dropping thelastTargetOffsetcomparison (not new in this PR) fails nothing.Two questions, neither a blocker as far as I could measure:
A
scrollToFnthat does not land in the same task, like the docs' smooth-scroll example (rAF easing,scrollToIndexwith the default behavior). Its first intermediate scroll event is neither the read-back nor at the target, so the index scroll now ends on the first animation frame instead of living until it lands. With fixed rows the landing is the same (row 500 at 0 on all revisions, Chromium). With dynamic rows that pattern is already broken onmain(row 500 about 20,700px away after 9s, about 22,000px here), so I cannot call it a regression. ButstartedSmoothonly knows aboutbehavior: 'smooth', and a customscrollToFnis the other way a write can travel. Is that a case you want to keep alive, or is it out of scope?A clamped read-back while the fresh target is below the new max. The comment says the read-back at the max "is also where the fresh target clamps". That does not hold if rows above the target shrink in the same window. Simulated: 100 rows of 50px,
scrollToIndex(90, { align: 'start' })writes 4500, rows 0–19 measure at 20px before the read-back, the max drops to 4200 and the target to 3900.mainlands on 3900; this PR stops at 4200 with row 90 300px above the viewport. I could not produce that ordering in a real browser or anywhere in the sweep, so it may be unreachable in practice. Flagging it because the comment reads as if it cannot happen.
WebKit
smooth-scrollandsmooth-prependare flaky on my machine on every revision includingmain, at similar rates (numbers in #1307). I did not reproduce the 0 vs 0 from your A/B, but nothing there points at this PR.@phcorp thanks for review! Regarding clamped read-back below a shrunk target: you're right that the comment overstated it. I reproduced your numbers in core (4200 instead of 3900). It only happens if the re-render that shrinks the sizer runs before the scroll event; without a render the stale target clamps to the read-back and reconciling carries on. Since it has never been seen in a browser, I pinned it with a .fails test and corrected the comment (f596cb0b) rather than adding a special case to the scroll handler. If it shows up for real, that test is the starting point.
piecyk merged this7aa34f6
piecyk closed this
Sign in to join this conversation.
🦋 Changeset detected#
Latest commit: f596cb0bfc0633a2d236134b715300372f1073a3
The changes in this PR will be included in the next version bump.
This PR includes changesets to release 9 packages
Not sure what this means? Click here to learn what changesets are.
Click here if you're a maintainer who wants to add another changeset to this PR