From 932bcf8c2bd4152cef819c39f3b6aa9b3871172b Mon Sep 17 00:00:00 2001 From: Gabriel Parelli Francischini Date: Tue, 10 Nov 2026 16:37:54 -0300 Subject: [PATCH 1/2] fix(indicator): keep the thumb at the end when the list overscrolls 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 --- docs/backlog.md | 7 ------- .../FastScrollIndicator.tsx | 17 +++++++-------- .../__tests__/FastScrollIndicator.test.tsx | 21 ++++++++++++++----- 3 files changed, 23 insertions(+), 22 deletions(-) diff --git a/docs/backlog.md b/docs/backlog.md index d1ded7f..d2a2c4e 100644 --- a/docs/backlog.md +++ b/docs/backlog.md @@ -34,13 +34,6 @@ a device yet. Possible fix: scroll once the list has mounted (for example `initialScrollIndex` or an effect on the active section), instead of in `show()`. -### `FastScrollIndicator` drops offsets outside 0..1 instead of clamping them - -[FastScrollIndicator.tsx:243](../src/FastScrollIndicator/FastScrollIndicator.tsx#L243): -`onScrollToOffsetPercentage` returns early for values below 0 or above 1. On an -iOS bounce the list reports those values, so the thumb stays where it was -instead of reaching the top or the bottom. Clamp to 0..1 instead. - ### Sections built from `stickyHeaderIndices` all read "1" [utils.ts:232](../src/utils.ts#L232): `createFullSectionData` gives each section diff --git a/src/FastScrollIndicator/FastScrollIndicator.tsx b/src/FastScrollIndicator/FastScrollIndicator.tsx index 269359c..49ac7b5 100644 --- a/src/FastScrollIndicator/FastScrollIndicator.tsx +++ b/src/FastScrollIndicator/FastScrollIndicator.tsx @@ -81,8 +81,8 @@ export type FastScrollIndicatorHandle = { /** * Call this method when the onScroll of your list changes * You need to calculate the percentage between 0 and 1 - * @param offsetPercentage between 0 and 1 - * @returns + * @param offsetPercentage between 0 and 1. Values outside it, such as the + * ones an iOS list reports while it bounces, keep the thumb at that end. */ onScrollToOffsetPercentage: (offsetPercentage: number) => void; }; @@ -272,20 +272,17 @@ export const FastScrollIndicator = React.forwardRef( forwardedRef, (): FastScrollIndicatorHandle => ({ onScrollToOffsetPercentage(offsetPercentage: number) { - if (offsetPercentage < 0 || offsetPercentage > 1) { - // console.warn( - // `onScrollToOffsetPercentage only allow values between 0 and 1. Received = ${offsetPercentage}` - // ); - return; - } - if (fingerOnTrack.current) { // event is ignored as the scrolling is being done by the thumbs return; } + // A list that bounces past either end (iOS) reports offsets below 0 + // and above 1, and can come to rest just past 1. The thumb stays at + // that end of the track. + const clampedOffset = Math.min(1, Math.max(0, offsetPercentage)); translateY.value = - offsetPercentage * (trackHeight.current - thumbSize.height); + clampedOffset * (trackHeight.current - thumbSize.height); showFastScrollBar(); }, diff --git a/src/FastScrollIndicator/__tests__/FastScrollIndicator.test.tsx b/src/FastScrollIndicator/__tests__/FastScrollIndicator.test.tsx index 62f3e6b..ae90fbb 100644 --- a/src/FastScrollIndicator/__tests__/FastScrollIndicator.test.tsx +++ b/src/FastScrollIndicator/__tests__/FastScrollIndicator.test.tsx @@ -110,14 +110,25 @@ describe('FastScrollIndicator', () => { expect(isScrollBarShown()).toBe(true); }); - it.each([-0.1, 1.1])( - 'ignores a scroll offset of %p outside the 0..1 range', - (offset) => { - const { scrollListTo } = renderIndicator(); + // An iOS list bounces past either end: from the middle, one scroll frame can + // already report an offset beyond the end it is flung to. + it.each([ + [-0.1, 0], + [1.1, 500], + ])( + 'pins the thumb to the end of the track when the list overscrolls to %p', + (offset, thumbPosition) => { + const { scrollListTo } = renderIndicator({ + hideFastScrollIndicatorTimeout: 1000, + }); + scrollListTo(0.5); + act(() => jest.advanceTimersByTime(800)); scrollListTo(offset); - expect(isScrollBarShown()).toBe(false); + expect(getThumbPosition()).toBe(thumbPosition); + act(() => jest.advanceTimersByTime(800)); + expect(isScrollBarShown()).toBe(true); } ); From df05c1875f321be9bd0aae57de7a4e6689abaa32 Mon Sep 17 00:00:00 2001 From: Gabriel Parelli Francischini Date: Tue, 10 Nov 2026 16:37:56 -0300 Subject: [PATCH 2/2] chore(example): add a short list to watch the indicator while it bounces 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 --- example/src/ExamplesScreen.tsx | 1 + example/src/NavigationTree.tsx | 2 + .../src/indicatorBounce/IndicatorBounce.tsx | 127 ++++++++++++++++++ example/src/screens.ts | 1 + 4 files changed, 131 insertions(+) create mode 100644 example/src/indicatorBounce/IndicatorBounce.tsx diff --git a/example/src/ExamplesScreen.tsx b/example/src/ExamplesScreen.tsx index 3bc588f..5e2b1f9 100644 --- a/example/src/ExamplesScreen.tsx +++ b/example/src/ExamplesScreen.tsx @@ -27,6 +27,7 @@ export const ExamplesScreen = () => { { title: 'MemoryLeak', destination: 'MemoryLeak' }, { title: 'ReplaceSections', destination: 'ReplaceSections' }, { title: 'IndicatorCost', destination: 'IndicatorCost' }, + { title: 'IndicatorBounce', destination: 'IndicatorBounce' }, ]; return ( <> diff --git a/example/src/NavigationTree.tsx b/example/src/NavigationTree.tsx index 0646098..fb5da19 100644 --- a/example/src/NavigationTree.tsx +++ b/example/src/NavigationTree.tsx @@ -11,6 +11,7 @@ import DotsLayout from './dotsLayout/DotsLayout'; import MemoryLeak from './memoryLeak/MemoryLeak'; import ReplaceSections from './replaceSections/ReplaceSections'; import IndicatorCost from './indicatorCost/IndicatorCost'; +import IndicatorBounce from './indicatorBounce/IndicatorBounce'; const Stack = createStackNavigator(); @@ -27,6 +28,7 @@ const NavigationTree = () => { + diff --git a/example/src/indicatorBounce/IndicatorBounce.tsx b/example/src/indicatorBounce/IndicatorBounce.tsx new file mode 100644 index 0000000..10fba4d --- /dev/null +++ b/example/src/indicatorBounce/IndicatorBounce.tsx @@ -0,0 +1,127 @@ +import React, { useCallback, useRef, useState } from 'react'; +import { + LayoutChangeEvent, + NativeScrollEvent, + NativeSyntheticEvent, + StyleSheet, + Text, + View, +} from 'react-native'; +import { FlashList } from '@shopify/flash-list'; +import { FastScrollIndicator } from 'react-native-fast-scroll'; + +/** + * A short list under a `FastScrollIndicator`, to watch the thumb while the list + * bounces past either end on iOS. Like the production app, the offset passed + * to `onScrollToOffsetPercentage` is over the scrollable height (content minus + * the list's own height) and is not clamped, so a bounce reports values below + * 0 and above 1. The panel shows the last value reported. + * + * On a short list one frame of a fling moves the thumb a long way, so a thumb + * that ignores the out-of-range frames visibly stops short of the end while + * the list bounces. + */ + +const ROWS = Array.from({ length: 30 }, (_, i) => i); +const ROW_HEIGHT = 44; + +const IndicatorBounce = () => { + const indicatorRef = + useRef>(null); + const listRef = useRef>(null); + const contentHeight = useRef(0); + const listHeight = useRef(0); + const [reported, setReported] = useState(0); + + const scrollableHeight = useCallback( + () => Math.max(0, contentHeight.current - listHeight.current), + [] + ); + + const onContentSizeChange = useCallback((_width: number, height: number) => { + contentHeight.current = height; + }, []); + + const onListLayout = useCallback((event: LayoutChangeEvent) => { + listHeight.current = event.nativeEvent.layout.height; + }, []); + + const onScroll = useCallback( + (event: NativeSyntheticEvent) => { + const scrollable = scrollableHeight(); + const offsetPercentage = + scrollable > 0 ? event.nativeEvent.contentOffset.y / scrollable : 0; + indicatorRef.current?.onScrollToOffsetPercentage(offsetPercentage); + setReported(offsetPercentage); + }, + [scrollableHeight] + ); + + const scrollToOffsetPercentage = useCallback( + (offsetPercentage: number) => { + listRef.current?.scrollToOffset({ + offset: offsetPercentage * scrollableHeight(), + animated: false, + }); + }, + [scrollableHeight] + ); + + const outOfRange = reported < 0 || reported > 1; + + return ( + + + + Offset reported: {reported.toFixed(3)} + + + + ( + + Row {item + 1} + + )} + /> + + + + + + ); +}; + +const styles = StyleSheet.create({ + container: { flex: 1 }, + panel: { padding: 12, backgroundColor: '#1F3A5F' }, + report: { color: 'white', fontSize: 16, fontWeight: '600' }, + reportOutOfRange: { color: '#FFB347' }, + listContainer: { flex: 1 }, + row: { + height: ROW_HEIGHT, + justifyContent: 'center', + paddingHorizontal: 16, + borderBottomWidth: StyleSheet.hairlineWidth, + borderBottomColor: '#ddd', + }, + indicator: { position: 'absolute', top: 0, bottom: 0, right: 1 }, +}); + +export default IndicatorBounce; diff --git a/example/src/screens.ts b/example/src/screens.ts index d5a45ac..5703df2 100644 --- a/example/src/screens.ts +++ b/example/src/screens.ts @@ -8,4 +8,5 @@ export type RootStackParamList = { MemoryLeak: undefined; ReplaceSections: undefined; IndicatorCost: undefined; + IndicatorBounce: undefined; };