Skip to content

fix(dots): start the thumb on the current section when the bar reappears - #12

Merged
gfrancischini merged 4 commits into
mainfrom
fix/dots-thumb-on-reappear
Nov 9, 2026
Merged

gfrancischini merged 4 commits into
mainfrom
fix/dots-thumb-on-reappear

Conversation

@gfrancischini

@gfrancischini gfrancischini commented Nov 9, 2026 •

Copy link
Copy Markdown
Owner

Summary

The dots bar unmounts while hidden. Each time it showed again, its thumb started above the first dot, and onViewableIndexChanged calls made while it was hidden were dropped. Apps show the bar from onScroll but often report the first visible item only once the list stops (the production catalog list debounces it 500 ms), so during a scroll the thumb pointed above the first section.

 FastScrollSectionDots
+  activeSectionIndexRef        // last section reported or dragged to
   onViewableIndexChanged(index)
-    if the bar is mounted: move its thumb
+    remember the section; if the bar is mounted: move its thumb
   onSectionChange (drag)
+    remember the section
   <FastScrollSectionDotsBar
+    initialSectionIndex={activeSectionIndexRef.current}

 FastScrollSectionDotsBar
-  thumb starts at y = 0 (above the first dot)
+  thumb starts on the dot of initialSectionIndex

A second commit makes the example's categories screen report the first visible item after a 500 ms debounce, like the production list. Without it the example reported every viewability change at once, which hid the bug.

The backlog item is removed from docs/backlog.md. "The dots bar remounts every time it shows" stays: this fix does not stop the remount, it only makes the thumb independent of it.

Evidence

Unit tests. The it.todo for this case is replaced by three tests. All three fail on main, with the thumb at 0, and pass with the fix.

report item 7, let the dots hide, scroll again       -> thumb on Vegetables (39)   (main: 0)
report item 250 while hidden, scroll                 -> thumb on Dairy (61)        (main: 0)
drag to Dairy, let list and dots hide, scroll again  -> thumb on Dairy (61)        (main: 0)

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

On a device. Android emulator (API 36), example app, categories screen with the 500 ms debounce. Steps: scroll down a few sections, wait for the dots to hide, then fling once.

  • Before: while the list moves, the thumb sits above the first dot. It reaches the right dot only after the list stops and the debounce fires, about 1.2 s later.
  • After: the thumb is on the dot of the last reported section as soon as the bar shows. It then moves to the new section when the debounced report arrives.

The dots bar 0.4 s into the fling, cropped from the recordings. Both runs start with the list in the fifth section, Bracelets / Rose Gold. Left is before (thumb above the first dot), right is after (thumb on the fifth dot):

Before (main) After (this branch)
The thumb is above the first dot while the list moves into the sixth section, and reaches the sixth dot once the debounced report arrives. The thumb shows on the fifth dot, where the list was, and stays there: this fling ends inside the fifth section.

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

Only the thumb's starting position changes. A revert brings back the old start position.

Blast Radius: dots thumb

The only new prop is internal to FastScrollSectionDotsBar; the public props and handle are unchanged. The example change only affects the example app.

🤖 Generated with Claude Code

gfrancischini added a commit that referenced this pull request Nov 9, 2026
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@gfrancischini
gfrancischini requested a balanced review from Copilot November 9, 2026 19:18

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

The cached section ordinal is not clamped when sections change, allowing the thumb to appear past the last dot after the section list shrinks.

1 open issue
What changed in this PR

This PR preserves the dots thumb’s last known section when the bar remounts, supporting apps that delay viewability updates until scrolling settles without changing the public API.

Changes:

  • Remember sections reported while hidden or selected by dragging, and use them to initialize the thumb.
  • Add three regression tests and debounce the example’s viewability updates by 500 ms.
  • Remove the resolved backlog item while retaining the separate remounting concern.
File Description
src/​FastScrollSectionDots/​FastScrollSectionDotsBar.tsx Initialize the thumb from an internal section-index prop.
src/​FastScrollSectionDots/​FastScrollSectionDots.tsx Cache the active section across bar remounts.
src/​FastScrollSectionDots/​__tests__/​FastScrollSectionDots.test.tsx Cover remembered, hidden-update, and dragged-section positions.
example/​src/​category/​Categories.tsx Debounce viewability reports and clean up the timer.
docs/​backlog.md Remove the thumb-reset issue and clarify the remaining remount concern.

Review effort: Balanced

dotColor={dotColor}
scrollBarColor={scrollBarColor}
onSectionChange={onSectionChange}
initialSectionIndex={activeSectionIndexRef.current}

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in 4f983b9, though not by clamping. The dots now remember the list index (the first visible item, or the header of the dragged section) instead of the section ordinal. When the bar mounts, findNearestActiveSection matches that index against the current sections. The thumb therefore always lands on a dot that exists. It also lands on the right section when sections are reordered or shifted, where a clamped ordinal would point at the wrong one.

Test. shows the thumb on a dot of the current sections when the app replaced them while the dots were hidden: report item 250 (Dairy, the third of three sections), replace the sections with the first two, scroll. On 52ad29d the thumb is at y = 61, where the removed third dot was. With the fix it is on Vegetables (39).

On a device. Android emulator (API 36). ebb2931 adds an example screen, ReplaceSections: 12 sections, viewability reported after a 500 ms debounce like production, and a button that keeps only sections 1–4. Steps: scroll to section 7/8, let the dots hide, tap "Only 1–4", scroll right away (before the debounced report).

The dots bar on the first frame it shows after the filter. Left is before (no thumb: it sits below the last dot and is clipped), right is after (thumb on the fourth dot):

Before (52ad29d) After (4f983b9)
The bar shows four dots and no thumb. The thumb appears on the third dot once the debounced report arrives. The thumb shows on the fourth dot, the last one left, then moves to the third when the report arrives.

Full-resolution recordings: replaced-before.mp4, replaced-after.mp4.

gfrancischini added a commit that referenced this pull request Nov 9, 2026
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
gfrancischini and others added 4 commits November 9, 2026 17:57
The dots bar unmounts while hidden, so each time it showed again its
thumb started above the first dot, and onViewableIndexChanged calls made
while it was hidden were dropped. Apps show the bar from onScroll but
often report the first visible item only once the list stops, so the
thumb pointed at the first section until then.

The dots now keep the last section reported or dragged to, and the bar
starts its thumb on it when it mounts.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Like the production catalog list, the categories screen now calls
onViewableIndexChanged only once the list has settled for 500 ms. With
every viewability change reported right away, the dots' thumb was fixed
before anyone could see where it started.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The dots remembered the section ordinal, so an app that replaced its
sections while the bar was hidden could get the thumb past the last dot
when the bar showed again. They now remember the list index and find its
section when the bar mounts.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A filter keeps only the first four of twelve sections. Showing the dots
right after it, before the debounced viewability report, shows where the
thumb starts when the sections changed while the dots were hidden.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@gfrancischini
gfrancischini force-pushed the fix/dots-thumb-on-reappear branch from 076f43d to 2cfd81d Compare November 9, 2026 20:58
@gfrancischini
gfrancischini merged commit 9cfd3b7 into main Nov 9, 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.

2 participants