From 95075068573ec45ac07bbfa99f2b04e0f230d03f Mon Sep 17 00:00:00 2001 From: Gabriel Parelli Francischini Date: Mon, 9 Nov 2026 15:20:25 -0300 Subject: [PATCH 1/4] fix(dots): start the thumb on the current section when the bar reappears 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 --- docs/backlog.md | 20 +-------- .../FastScrollSectionDots.tsx | 11 ++++- .../FastScrollSectionDotsBar.tsx | 29 ++++++++++--- .../__tests__/FastScrollSectionDots.test.tsx | 43 +++++++++++++++++-- 4 files changed, 75 insertions(+), 28 deletions(-) diff --git a/docs/backlog.md b/docs/backlog.md index 12cd9e4..ff8bb28 100644 --- a/docs/backlog.md +++ b/docs/backlog.md @@ -49,22 +49,6 @@ instead of reaching the top or the bottom. Clamp to 0..1 instead. or an empty string would be better. Whatever changes, `createFullSectionData` must keep spreading unknown fields of `stickyHeaderIndicesWithData` through. -### The dots' thumb goes back to the first dot each time the bar shows - -[FastScrollSectionDots.tsx:230](../src/FastScrollSectionDots/FastScrollSectionDots.tsx#L230): -the bar is unmounted while hidden (`{visible && ...}`), so: - -- `onViewableIndexChanged` is dropped while the bar is hidden, because - `fastScrollSectionDotsBarRef.current` is `null` - ([line 149](../src/FastScrollSectionDots/FastScrollSectionDots.tsx#L149)). -- When the bar mounts again, `pointStylePositionY` starts at 0, so the thumb - sits on the first dot. - -Apps show the bar from `onScroll` but usually debounce `onViewableIndexChanged` -until the list stops, so during a fling the thumb may point at the first section -the whole time. Not confirmed on a device yet. The fix is the one in "The dots -bar remounts every time it shows" below. - ## Performance None of these grows memory over time: they cost CPU and short-lived garbage. @@ -139,8 +123,8 @@ per dot, and a `measure` call. Meanwhile `useHideFlatBar` springs hide, but nothing reads it. Possible fix: keep the bar mounted and slide it with `translateFastScrollBarX` -(or drop that shared value). This also fixes "The dots' thumb goes back to the -first dot each time the bar shows" above. +(or drop that shared value). The thumb no longer depends on it: the dots keep +the last active section and the bar starts on it when it mounts. ### Unstable props rebuild the gestures diff --git a/src/FastScrollSectionDots/FastScrollSectionDots.tsx b/src/FastScrollSectionDots/FastScrollSectionDots.tsx index 61f34e8..e847ac7 100644 --- a/src/FastScrollSectionDots/FastScrollSectionDots.tsx +++ b/src/FastScrollSectionDots/FastScrollSectionDots.tsx @@ -137,6 +137,12 @@ const FastScrollSectionDots = React.forwardRef( }); }, [stickyHeaderIndices, stickyHeaderIndicesWithData]); + // The bar unmounts while hidden, and apps show it from onScroll but usually + // report the first visible item only once the list stops. The last section + // reported or dragged to is kept here so the thumb starts on it each time + // the bar mounts again. + const activeSectionIndexRef = useRef(undefined); + React.useImperativeHandle( forwardedRef, (): FastScrollSectionDotsHandle => ({ @@ -146,7 +152,8 @@ const FastScrollSectionDots = React.forwardRef( onViewableIndexChanged(index: number) { const section = findNearestActiveSection(sections, index); - if (section && fastScrollSectionDotsBarRef.current) { + if (section) { + activeSectionIndexRef.current = section.sectionIndex; fastScrollSectionDotsBarRef.current?.onSectionChange(section); } }, @@ -205,6 +212,7 @@ const FastScrollSectionDots = React.forwardRef( const onSectionChange = useCallback( (section: SectionFullData) => { debouncedScrollToIndexRef.current(section.index); + activeSectionIndexRef.current = section.sectionIndex; if (section) { // locing the panel as we are opening the full list @@ -255,6 +263,7 @@ const FastScrollSectionDots = React.forwardRef( onSectionChange={onSectionChange} onFingerDown={holdSectionList} onFingerUp={releaseSectionList} + initialSectionIndex={activeSectionIndexRef.current} /> )} diff --git a/src/FastScrollSectionDots/FastScrollSectionDotsBar.tsx b/src/FastScrollSectionDots/FastScrollSectionDotsBar.tsx index dc83989..6e474ee 100644 --- a/src/FastScrollSectionDots/FastScrollSectionDotsBar.tsx +++ b/src/FastScrollSectionDots/FastScrollSectionDotsBar.tsx @@ -73,8 +73,21 @@ export type Props = { onFingerUp: () => void; sections: SectionFullData[]; + + /** + * The section the thumb starts on. The bar mounts each time it shows, so + * without it the thumb would start above the first dot. + */ + initialSectionIndex?: number; }; +/** Where the thumb sits when it rests on the dot of `sectionIndex`: its middle. */ +const thumbYOnDot = ( + sectionIndex: number, + dotSize: number, + dotMargin: number +) => dotMargin * (sectionIndex + 1) + dotSize * sectionIndex + dotSize / 2; + export type FastScrollSectionDotsBarHandle = { /** * Call this method when viewable indicies changes @@ -95,12 +108,17 @@ const FastScrollSectionDotsBar = React.forwardRef( onSectionChange, onFingerDown, onFingerUp, + initialSectionIndex, ...props }: Props, forwardedRef: React.ForwardedRef ) => { const scale = useSharedValue(1); - const pointStylePositionY = useSharedValue(0); + const pointStylePositionY = useSharedValue( + initialSectionIndex === undefined + ? 0 + : thumbYOnDot(initialSectionIndex, dotSize, dotMargin) + ); const containerYOnPointStylePositionY = useSharedValue(0); const sections = useMemo((): SectionDataWithDimensions[] => { @@ -301,10 +319,11 @@ const FastScrollSectionDotsBar = React.forwardRef( (): FastScrollSectionDotsBarHandle => ({ onSectionChange: (section: SectionFullData) => { if (enableExternalScrollEvents.value) { - pointStylePositionY.value = - dotMargin * (section.sectionIndex + 1) + - dotSize * section.sectionIndex + - dotSize / 2; + pointStylePositionY.value = thumbYOnDot( + section.sectionIndex, + dotSize, + dotMargin + ); containerYOnPointStylePositionY.value = containerScrollY.value; } }, diff --git a/src/FastScrollSectionDots/__tests__/FastScrollSectionDots.test.tsx b/src/FastScrollSectionDots/__tests__/FastScrollSectionDots.test.tsx index 6da3d98..8c7786c 100644 --- a/src/FastScrollSectionDots/__tests__/FastScrollSectionDots.test.tsx +++ b/src/FastScrollSectionDots/__tests__/FastScrollSectionDots.test.tsx @@ -328,10 +328,45 @@ describe('FastScrollSectionDots', () => { expect(getDotsScrollOffset()).toBe(0); }); - // Today the dots remount when they reappear and the thumb starts at the top - // of the bar (above the first dot) until the next onViewableIndexChanged. - // Calls made while the dots are hidden are dropped as well. - it.todo('shows the thumb on the current section when the dots reappear'); + // Apps show the dots from onScroll but usually report the first visible item + // only once the list stops, so the dots reappear before the next report. + it('shows the thumb on the current section when the dots reappear', () => { + const { scrollList, showListItem } = renderDots({ + hideFastScrollIndicatorTimeout: 1000, + }); + scrollList(); + showListItem(7); + act(() => jest.advanceTimersByTime(1000)); + expect(isAnythingShown()).toBe(false); + + scrollList(); + + expect(getThumbPosition()).toBe(THUMB_ON.vegetables); + }); + + it('shows the thumb on the section the list reached while the dots were hidden', () => { + const { scrollList, showListItem } = renderDots({ + hideFastScrollIndicatorTimeout: 1000, + }); + + showListItem(250); + scrollList(); + + expect(getThumbPosition()).toBe(THUMB_ON.dairy); + }); + + it('shows the thumb on the dragged section when the dots reappear', () => { + const { scrollList } = renderDots({ hideFastScrollIndicatorTimeout: 1000 }); + scrollList(); + drag([FINGER_ON.fruits, FINGER_ON.dairy]); + // The section list closes after 3 s, then the dots after their 1 s. + act(() => jest.advanceTimersByTime(4000)); + expect(isAnythingShown()).toBe(false); + + scrollList(); + + expect(getThumbPosition()).toBe(THUMB_ON.dairy); + }); it('opens the section list with the dragged section marked active', () => { renderDots({ From e7f3bae46d13a5bba877c5fdb491e32581095db3 Mon Sep 17 00:00:00 2001 From: Gabriel Parelli Francischini Date: Mon, 9 Nov 2026 15:52:21 -0300 Subject: [PATCH 2/4] chore(example): report the first visible item after the list settles 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 --- example/src/category/Categories.tsx | 19 +++++++++++++------ 1 file changed, 13 insertions(+), 6 deletions(-) diff --git a/example/src/category/Categories.tsx b/example/src/category/Categories.tsx index 4270a2e..36f7254 100644 --- a/example/src/category/Categories.tsx +++ b/example/src/category/Categories.tsx @@ -1,4 +1,4 @@ -import React, { useCallback, useRef } from 'react'; +import React, { useCallback, useEffect, useRef } from 'react'; import { CategoryItemData, data, Header, Product } from './data/categories'; import { @@ -129,15 +129,22 @@ const Categories = () => { }); }, []); + // Like the production app, report the first visible item to the dots only + // once the list has settled for 500 ms. + const viewableIndexDebounce = useRef>(); + useEffect(() => () => clearTimeout(viewableIndexDebounce.current), []); const onViewableItemsChanged = (info: { viewableItems: ViewToken[]; changed: ViewToken[]; }) => { - if (info.viewableItems[0]?.index != null) { - fastScrollSectionDotsRef.current?.onViewableIndexChanged( - info.viewableItems[0].index - ); - } + clearTimeout(viewableIndexDebounce.current); + viewableIndexDebounce.current = setTimeout(() => { + if (info.viewableItems[0]?.index != null) { + fastScrollSectionDotsRef.current?.onViewableIndexChanged( + info.viewableItems[0].index + ); + } + }, 500); }; const onScrollToIndex = (index: number) => { From e09e98b85d8a466e54212ec2998fe323c8491e32 Mon Sep 17 00:00:00 2001 From: Gabriel Parelli Francischini Date: Mon, 9 Nov 2026 17:13:47 -0300 Subject: [PATCH 3/4] fix(dots): match the remembered position against the current sections 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 --- .../FastScrollSectionDots.tsx | 19 ++++++++++---- .../__tests__/FastScrollSectionDots.test.tsx | 26 ++++++++++++++++++- 2 files changed, 39 insertions(+), 6 deletions(-) diff --git a/src/FastScrollSectionDots/FastScrollSectionDots.tsx b/src/FastScrollSectionDots/FastScrollSectionDots.tsx index e847ac7..eca1774 100644 --- a/src/FastScrollSectionDots/FastScrollSectionDots.tsx +++ b/src/FastScrollSectionDots/FastScrollSectionDots.tsx @@ -140,8 +140,11 @@ const FastScrollSectionDots = React.forwardRef( // The bar unmounts while hidden, and apps show it from onScroll but usually // report the first visible item only once the list stops. The last section // reported or dragged to is kept here so the thumb starts on it each time - // the bar mounts again. - const activeSectionIndexRef = useRef(undefined); + // the bar mounts again. It holds a list index, not the section's ordinal, + // and is matched against the sections when the bar mounts: the app may + // replace the sections meanwhile, and an old ordinal could then point past + // the last dot. + const activeListIndexRef = useRef(undefined); React.useImperativeHandle( forwardedRef, @@ -151,9 +154,9 @@ const FastScrollSectionDots = React.forwardRef( }, onViewableIndexChanged(index: number) { + activeListIndexRef.current = index; const section = findNearestActiveSection(sections, index); if (section) { - activeSectionIndexRef.current = section.sectionIndex; fastScrollSectionDotsBarRef.current?.onSectionChange(section); } }, @@ -212,7 +215,7 @@ const FastScrollSectionDots = React.forwardRef( const onSectionChange = useCallback( (section: SectionFullData) => { debouncedScrollToIndexRef.current(section.index); - activeSectionIndexRef.current = section.sectionIndex; + activeListIndexRef.current = section.index; if (section) { // locing the panel as we are opening the full list @@ -243,6 +246,12 @@ const FastScrollSectionDots = React.forwardRef( return null; } + const initialSectionIndex = + activeListIndexRef.current === undefined + ? undefined + : findNearestActiveSection(sections, activeListIndexRef.current) + ?.sectionIndex; + return ( {visible && ( @@ -263,7 +272,7 @@ const FastScrollSectionDots = React.forwardRef( onSectionChange={onSectionChange} onFingerDown={holdSectionList} onFingerUp={releaseSectionList} - initialSectionIndex={activeSectionIndexRef.current} + initialSectionIndex={initialSectionIndex} /> )} diff --git a/src/FastScrollSectionDots/__tests__/FastScrollSectionDots.test.tsx b/src/FastScrollSectionDots/__tests__/FastScrollSectionDots.test.tsx index 8c7786c..803eac7 100644 --- a/src/FastScrollSectionDots/__tests__/FastScrollSectionDots.test.tsx +++ b/src/FastScrollSectionDots/__tests__/FastScrollSectionDots.test.tsx @@ -67,7 +67,18 @@ const renderDots = ({ const showListItem = (index: number) => act(() => ref.current?.onViewableIndexChanged(index)); - return { onScrollToIndex, scrollList, showListItem }; + /** The app renders the dots again with other sections. */ + const replaceSections = (newSections: Section[]) => + screen.rerender( + + ); + + return { onScrollToIndex, scrollList, showListItem, replaceSections }; }; /** @@ -368,6 +379,19 @@ describe('FastScrollSectionDots', () => { expect(getThumbPosition()).toBe(THUMB_ON.dairy); }); + it('shows the thumb on a dot of the current sections when the app replaced them while the dots were hidden', () => { + const { scrollList, showListItem, replaceSections } = renderDots({ + hideFastScrollIndicatorTimeout: 1000, + }); + showListItem(250); + + // Dairy, the third section, is gone; item 250 now falls under Vegetables. + replaceSections(SECTIONS.slice(0, 2)); + scrollList(); + + expect(getThumbPosition()).toBe(THUMB_ON.vegetables); + }); + it('opens the section list with the dragged section marked active', () => { renderDots({ hideFastScrollIndicatorTimeout: 0, From 2cfd81d53c03a1b7385a5eea4654b9de2d319624 Mon Sep 17 00:00:00 2001 From: Gabriel Parelli Francischini Date: Mon, 9 Nov 2026 17:37:16 -0300 Subject: [PATCH 4/4] chore(example): add a screen that replaces the dots' sections 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 --- example/src/ExamplesScreen.tsx | 1 + example/src/NavigationTree.tsx | 2 + .../src/replaceSections/ReplaceSections.tsx | 192 ++++++++++++++++++ example/src/screens.ts | 1 + 4 files changed, 196 insertions(+) create mode 100644 example/src/replaceSections/ReplaceSections.tsx diff --git a/example/src/ExamplesScreen.tsx b/example/src/ExamplesScreen.tsx index ab69a0b..fdda281 100644 --- a/example/src/ExamplesScreen.tsx +++ b/example/src/ExamplesScreen.tsx @@ -25,6 +25,7 @@ export const ExamplesScreen = () => { { title: 'StaleCallback', destination: 'StaleCallback' }, { title: 'DotsLayout', destination: 'DotsLayout' }, { title: 'MemoryLeak', destination: 'MemoryLeak' }, + { title: 'ReplaceSections', destination: 'ReplaceSections' }, ]; return ( <> diff --git a/example/src/NavigationTree.tsx b/example/src/NavigationTree.tsx index ac60dc8..f618b24 100644 --- a/example/src/NavigationTree.tsx +++ b/example/src/NavigationTree.tsx @@ -9,6 +9,7 @@ import Performance from './performance/Performance'; import StaleCallback from './staleCallback/StaleCallback'; import DotsLayout from './dotsLayout/DotsLayout'; import MemoryLeak from './memoryLeak/MemoryLeak'; +import ReplaceSections from './replaceSections/ReplaceSections'; const Stack = createStackNavigator(); @@ -23,6 +24,7 @@ const NavigationTree = () => { + diff --git a/example/src/replaceSections/ReplaceSections.tsx b/example/src/replaceSections/ReplaceSections.tsx new file mode 100644 index 0000000..cad2221 --- /dev/null +++ b/example/src/replaceSections/ReplaceSections.tsx @@ -0,0 +1,192 @@ +import React, { + useCallback, + useEffect, + useMemo, + useRef, + useState, +} from 'react'; +import { + NativeScrollEvent, + NativeSyntheticEvent, + Pressable, + StyleSheet, + Text, + View, +} from 'react-native'; +import { FlashList, ViewToken } from '@shopify/flash-list'; +import { FastScrollSectionDots, Section } from 'react-native-fast-scroll'; + +/** + * The app replaces the dots' sections while the dots are hidden: a filter + * keeps only the first sections. When the dots show again, before the list + * reports its first visible item (debounced 500 ms, like production), the + * thumb must sit on one of the dots that are left. + */ + +const SECTION_COUNT = 12; +const FILTERED_SECTION_COUNT = 4; +const ROWS_PER_SECTION = 10; +const HEADER_HEIGHT = 64; + +type Row = { type: 'header' | 'row'; title: string }; + +const buildList = (sectionCount: number) => { + const data: Row[] = []; + const sections: Section[] = []; + for (let s = 1; s <= sectionCount; s++) { + sections.push({ index: data.length, text: `Section ${s}` }); + data.push({ type: 'header', title: `Section ${s}` }); + for (let r = 1; r <= ROWS_PER_SECTION; r++) { + data.push({ type: 'row', title: `Product ${s}.${r}` }); + } + } + return { data, sections }; +}; + +const ALL = buildList(SECTION_COUNT); +const FILTERED = buildList(FILTERED_SECTION_COUNT); + +const ReplaceSections = () => { + const [filtered, setFiltered] = useState(false); + const { data, sections } = filtered ? FILTERED : ALL; + + const flashListRef = useRef | null>(null); + const dotsRef = useRef | null>( + null + ); + + const onScroll = useCallback( + (_event: NativeSyntheticEvent) => { + dotsRef.current?.onScrollToOffsetPercentage(0); + }, + [] + ); + + // Like the production app, report the first visible item to the dots only + // once the list has settled for 500 ms. + const viewableIndexDebounce = useRef>(); + useEffect(() => () => clearTimeout(viewableIndexDebounce.current), []); + const onViewableItemsChanged = useCallback( + (info: { viewableItems: ViewToken[] }) => { + clearTimeout(viewableIndexDebounce.current); + viewableIndexDebounce.current = setTimeout(() => { + const first = info.viewableItems[0]?.index; + if (first != null) { + dotsRef.current?.onViewableIndexChanged(first); + } + }, 500); + }, + [] + ); + + const onScrollToIndex = useCallback((index: number) => { + flashListRef.current?.scrollToIndex({ index, animated: true }); + }, []); + + const contentContainerStyle = useMemo( + () => ({ paddingTop: HEADER_HEIGHT }), + [] + ); + + return ( + + { + layout.size = item.type === 'header' ? 40 : 56; + }} + getItemType={(item) => item.type} + contentContainerStyle={contentContainerStyle} + onScroll={onScroll} + onViewableItemsChanged={onViewableItemsChanged} + viewabilityConfig={{ itemVisiblePercentThreshold: 20 }} + renderItem={({ item }) => + item.type === 'header' ? ( + + {item.title} + + ) : ( + + {item.title} + + ) + } + /> + + + + Sections: {sections.length} of {SECTION_COUNT} + + setFiltered((f) => !f)} + testID="toggle-filter" + > + + {filtered ? 'Show all' : `Only 1–${FILTERED_SECTION_COUNT}`} + + + + + + + + + ); +}; + +const styles = StyleSheet.create({ + container: { flex: 1, backgroundColor: 'white' }, + header: { + position: 'absolute', + top: 0, + left: 0, + right: 0, + height: HEADER_HEIGHT, + flexDirection: 'row', + alignItems: 'center', + justifyContent: 'space-between', + paddingHorizontal: 12, + backgroundColor: '#1F3A5F', + }, + headerTitle: { color: 'white', fontSize: 16, fontWeight: '700' }, + button: { + backgroundColor: 'white', + borderRadius: 6, + paddingHorizontal: 10, + paddingVertical: 6, + }, + buttonText: { color: '#1F3A5F', fontWeight: '700' }, + sectionHeader: { + height: 40, + justifyContent: 'center', + paddingLeft: 60, + backgroundColor: 'darkred', + }, + sectionHeaderText: { color: 'white', fontSize: 18, fontWeight: '700' }, + row: { + height: 56, + justifyContent: 'center', + paddingLeft: 60, + borderBottomWidth: StyleSheet.hairlineWidth, + borderBottomColor: '#DDD', + }, + rowText: { fontSize: 16 }, + dots: { + position: 'absolute', + top: HEADER_HEIGHT + 20, + bottom: 20, + left: 0, + right: 0, + }, +}); + +export default ReplaceSections; diff --git a/example/src/screens.ts b/example/src/screens.ts index 0b86ab6..06cad8e 100644 --- a/example/src/screens.ts +++ b/example/src/screens.ts @@ -6,4 +6,5 @@ export type RootStackParamList = { StaleCallback: undefined; DotsLayout: undefined; MemoryLeak: undefined; + ReplaceSections: undefined; };