Skip to content

fix(indicator): keep the thumb at the end when the list overscrolls - #18

Merged
gfrancischini merged 2 commits into
mainfrom
fix/indicator-clamp-offset
Nov 10, 2026
Merged

gfrancischini merged 2 commits into
mainfrom
fix/indicator-clamp-offset

Conversation

@gfrancischini

Copy link
Copy Markdown
Owner

Summary

An iOS list reports offsets below 0 and above 1 while it bounces past either end. onScrollToOffsetPercentage dropped those frames, so the thumb stayed wherever the last in-range frame left it:

  • Top: short of the top until the bounce settled back to exactly 0.
  • Bottom: short of the bottom for good when the list came to rest at an offset just above 1.

On a long list one frame is a pixel or two on the track. On a short list one frame of a fling covers a lot of the track, and the generic list wrapper puts an indicator on every list, short ones included.

 onScrollToOffsetPercentage(offset)
-  if offset < 0 or offset > 1
-    return                                  // thumb and hide timer untouched
   if a finger is on the track
     return
-  thumb.y = offset * (track - thumb)
+  thumb.y = clamp(offset, 0, 1) * (track - thumb)
   show the bar, restart the hide timer

The example gets an IndicatorBounce screen: 30 rows (about two screens) under a FastScrollIndicator, offsets over the scrollable height and not clamped, as the production app passes them, and a readout of the last offset reported (orange when outside 0..1). The backlog item is removed from docs/backlog.md.

Evidence

Unit test. It replaces the test that asserted the old behavior ("ignores a scroll offset outside the 0..1 range"). It fails on main and passes here:

list at 0.5, 800 ms later it overscrolls to -0.1  -> thumb at 0    (main: 250), bar still shown 800 ms later
list at 0.5, 800 ms later it overscrolls to 1.1   -> thumb at 500  (main: 250), bar still shown 800 ms later

yarn test (101 passed, 1 todo), yarn typecheck and yarn lint pass.

On a device. iPhone 17 Pro Max simulator (iOS 26.5), example app on Expo SDK 52 (Reanimated 3.16, New Architecture), IndicatorBounce screen. The same two flings each time: one to the bottom, then one back to the top.

Before (main) After (this branch)

Thumb position read from every frame of the recordings (30 fps, bottom edge of the thumb in screen pixels; the list spans 447 to 2868):

Before After
Fling to the bottom, at rest 2804, 64 px (21 pt) short of the end, until the next scroll 2866, on the first frame of the bounce
Fling to the top, during the bounce 665, 70 px short of the top, for 0.83 s, then snaps to 595 595 one frame after the fling

At rest at the bottom the readout stays orange at "1.000": the offset is just above 1, so main never moves the thumb to the end.

Bottom-right corner at rest after the fling to the bottom (left: before, right: after):

Top-right corner 0.3 s into the fling back to the top (left: before, right: after):

Full-resolution recordings: before.mp4, after.mp4. They are on the pr-assets branch, which only holds PR media and is not meant to be merged.

Merge Danger

Door: two-way

One clamp in the indicator's handle. Reverting it restores the old behavior.

Blast Radius: indicator thumb

  • Offsets outside 0..1 now also show the bar and restart its hide timer, as in-range ones do. During a bounce the bar stays on screen instead of hiding 2 s after the last in-range frame.
  • Android does not overscroll past the ends, so it only changes there for an app that passes values outside 0..1 for some other reason. Those values used to be ignored and now pin the thumb to an end.
  • The handle's name and signature are unchanged. FastScrollSectionDots.onScrollToOffsetPercentage already accepted any value and is untouched.

🤖 Generated with Claude Code

gfrancischini and others added 2 commits November 10, 2026 16:37
onScrollToOffsetPercentage dropped offsets below 0 and above 1. An iOS list
reports them while it bounces past either end, so the thumb stopped where the
last in-range frame left it: short of the top until the bounce settled, and
short of the bottom for good when the list came to rest just past 1. On a
short list one frame of a fling is a long way on the track.

The handle now clamps the offset to 0..1, so the thumb sits at that end and
the bar stays on screen while the list bounces.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The IndicatorBounce screen passes the indicator unclamped offsets over the
scrollable height, as the production app does, and shows the last one it
reported, so an iOS bounce past either end can be watched on the thumb.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@gfrancischini
gfrancischini merged commit 49c7b72 into main Nov 10, 2026
3 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant