@rific/scroll-view 0.1.1 → 0.3.0

package/src/ScrollViewProvider.tsx

@@ -1,5 +1,5 @@
 import { useBlur } from '@rific/auto-paper'
-import { type ReactNode, useCallback, useContext, useEffect, useMemo, useState } from 'react'
+import { type ReactNode, useCallback, useContext, useEffect, useMemo, useRef, useState } from 'react'
 import { Dimensions } from 'react-native'
 import { useSharedValue } from 'react-native-reanimated'
 
@@ -24,11 +24,13 @@ export const ScrollViewProvider = ({ blur, children, fixed = false, footerFixed,
   const effectiveSnapBack = snapBack ?? settings.snapBack
   const effectiveSnapBackHeader = snapBackHeader ?? settings.snapBackHeader
   const effectiveSnapBackFooter = snapBackFooter ?? settings.snapBackFooter
-  const [headerHeight, setHeaderHeightState] = useState(0)
+  const [headerHeight, setHeaderHeightState] = useState<number | null>(null)
   const [footerHeight, setFooterHeightState] = useState(0)
   const [progress, setProgress] = useState<number | null>(null)
   const [progressing, setProgressing] = useState(false)
   const scrollPosition = useSharedValue(0)
+  const listGeneration = useSharedValue(0)
+  const jsListGeneration = useRef(0)
   const headerHeightShared = useSharedValue(0)
   const footerHeightShared = useSharedValue(0)
   const headerOffset = useSharedValue(0)
@@ -41,12 +43,26 @@ export const ScrollViewProvider = ({ blur, children, fixed = false, footerFixed,
     snapBackFooterShared.value = effectiveSnapBackFooter ?? effectiveSnapBack
   }, [effectiveSnapBack, effectiveSnapBackFooter, effectiveSnapBackHeader, snapBackFooterShared, snapBackHeaderShared])
   const setHeaderHeight = useCallback(
-    (h: number) => {
+    (h: number | null) => {
       setHeaderHeightState(h)
-      headerHeightShared.value = h
+      headerHeightShared.value = h ?? 0
     },
     [headerHeightShared]
   )
+  const onListUnmount = useCallback(() => {
+    listGeneration.value += 1
+  }, [listGeneration])
+  const onJsListUnmount = useCallback(() => {
+    jsListGeneration.current += 1
+  }, [])
+  useEffect(() => {
+    if (!__DEV__ || headerHeight !== null) return
+    const timeout = setTimeout(() => {
+      // eslint-disable-next-line no-console
+      console.warn('[scroll-view] No ScrollViewHeader ever measured inside this ScrollViewProvider — scroll content stays hidden (opacity: 0) until one does. Render a <ScrollViewHeader> (it can be empty / zero height) inside this provider.')
+    }, 3000)
+    return () => clearTimeout(timeout)
+  }, [headerHeight])
   const setFooterHeight = useCallback(
     (h: number) => {
       setFooterHeightState(h)
@@ -54,9 +70,9 @@ export const ScrollViewProvider = ({ blur, children, fixed = false, footerFixed,
     },
     [footerHeightShared]
   )
-  const scrollHeight = useMemo(() => Dimensions.get('window').height - headerHeight - footerHeight, [headerHeight, footerHeight])
+  const scrollHeight = useMemo(() => Dimensions.get('window').height - (headerHeight ?? 0) - footerHeight, [headerHeight, footerHeight])
   const effectiveHeaderFixed = fixed || (headerFixed ?? settings.headerFixed)
   const effectiveFooterFixed = fixed || (footerFixed ?? settings.footerFixed)
-  const value = useMemo(() => ({ blur: effectiveBlur, footerHeight, footerHeightShared, footerFixed: effectiveFooterFixed, footerOffset, headerHeight, headerHeightShared, headerFixed: effectiveHeaderFixed, headerOffset, progress, pullSearchHeightShared, progressing, scrollHeight, scrollPosition, setFooterHeight, setHeaderHeight, setProgress, setProgressing, snapBackFooterShared, snapBackHeaderShared, tabBarHeight }), [effectiveBlur, effectiveFooterFixed, effectiveHeaderFixed, footerHeight, footerHeightShared, footerOffset, headerHeight, headerHeightShared, headerOffset, progress, pullSearchHeightShared, progressing, scrollHeight, scrollPosition, setFooterHeight, setHeaderHeight, snapBackFooterShared, snapBackHeaderShared, tabBarHeight])
+  const value = useMemo(() => ({ blur: effectiveBlur, footerHeight, footerHeightShared, footerFixed: effectiveFooterFixed, footerOffset, headerHeight, headerHeightShared, headerFixed: effectiveHeaderFixed, headerOffset, jsListGeneration, listGeneration, onJsListUnmount, onListUnmount, progress, pullSearchHeightShared, progressing, scrollHeight, scrollPosition, setFooterHeight, setHeaderHeight, setProgress, setProgressing, snapBackFooterShared, snapBackHeaderShared, tabBarHeight }), [effectiveBlur, effectiveFooterFixed, effectiveHeaderFixed, footerHeight, footerHeightShared, footerOffset, headerHeight, headerHeightShared, headerOffset, jsListGeneration, listGeneration, onJsListUnmount, onListUnmount, progress, pullSearchHeightShared, progressing, scrollHeight, scrollPosition, setFooterHeight, setHeaderHeight, snapBackFooterShared, snapBackHeaderShared, tabBarHeight])
   return <ScrollViewContext.Provider value={value}>{children}</ScrollViewContext.Provider>
 }

package/src/ScrollViewSettingsProvider.tsx

@@ -5,13 +5,13 @@ import { defaultScrollViewSettings, type ScrollViewSettings, ScrollViewSettingsC
 export type ScrollViewSettingsProviderProps = {
   children: ReactNode
   onChange?: (settings: ScrollViewSettings) => void
-  value?: Partial<ScrollViewSettings>
+  initialValue?: Partial<ScrollViewSettings>
 }
 
-export const ScrollViewSettingsProvider = ({ children, onChange, value }: ScrollViewSettingsProviderProps) => {
+export const ScrollViewSettingsProvider = ({ children, onChange, initialValue }: ScrollViewSettingsProviderProps) => {
   const [settings, setSettings] = useState<ScrollViewSettings>(() => ({
     ...defaultScrollViewSettings,
-    ...value
+    ...initialValue
   }))
 
   const set = useCallback(

package/src/SectionList.tsx

@@ -1,23 +1,27 @@
-import { memo, type ReactNode, type RefObject, useCallback, useEffect, useLayoutEffect, useMemo, useRef } from 'react'
+import { memo, type ReactNode, type RefObject, useCallback, useContext, useEffect, useLayoutEffect, useMemo, useRef } from 'react'
 import { Dimensions, type NativeScrollEvent, type NativeSyntheticEvent, SectionList as RNSectionList, type SectionListProps as RNSectionListProps, View } from 'react-native'
 import { Gesture, GestureDetector, type GestureType } from 'react-native-gesture-handler'
-import Animated, { createAnimatedComponent } from 'react-native-reanimated'
+import Animated, { runOnUI, useSharedValue } from 'react-native-reanimated'
 
 import { RefreshControl } from './internal/RefreshControl'
-import { ScrollViewChip } from './internal/ScrollViewChip'
+import { type ChipProps, ScrollViewChip } from './internal/ScrollViewChip'
 import { useScrollHandler } from './internal/useScrollHandler'
 import { useScrollList } from './internal/useScrollList'
 import { useStickyHeaders } from './internal/useStickyHeaders'
+import { ScrollViewContext } from './ScrollViewContext'
 import { useScrollInit } from './useScrollInit'
 
-const AnimatedSectionList = createAnimatedComponent(RNSectionList) as unknown as typeof RNSectionList
+const AnimatedSectionList = Animated.createAnimatedComponent(RNSectionList) as unknown as typeof RNSectionList
 
 export type SectionListProps<ItemT, SectionT extends { data: ReadonlyArray<ItemT> } = { data: ReadonlyArray<ItemT> }> = Omit<RNSectionListProps<ItemT, SectionT>, 'horizontal'> & {
+  chipProps?: ChipProps
+  chipThreshold?: number
   renderFilters?: ReactNode
   footerFixed?: boolean
   gesture?: GestureType
   headerFixed?: boolean
   keyboardAware?: boolean
+  onChipPress?: () => void
   onMomentumScrollEnd?: (e: NativeSyntheticEvent<NativeScrollEvent>) => void
   onScrollBeginDrag?: (e: NativeSyntheticEvent<NativeScrollEvent>) => void
   onScrollEndDrag?: (e: NativeSyntheticEvent<NativeScrollEvent>) => void
@@ -25,12 +29,35 @@ export type SectionListProps<ItemT, SectionT extends { data: ReadonlyArray<ItemT
   ref?: RefObject<RNSectionList<ItemT, SectionT> | null>
 }
 
-const SectionListInner = <ItemT, SectionT extends { data: ReadonlyArray<ItemT> } = { data: ReadonlyArray<ItemT> }>({ contentContainerStyle: externalContentContainerStyle, initialNumToRender = 20, maxToRenderPerBatch = 50, renderFilters, footerFixed: footerFixedProp, gesture, headerFixed: headerFixedProp, keyboardAware, ListHeaderComponent: externalListHeaderComponent, onMomentumScrollEnd: externalMomentumScrollEnd, onRefresh, onContentSizeChange, onScrollBeginDrag: externalScrollBeginDrag, onScrollEndDrag: externalScrollEndDrag, pullSearchHeight, refreshing, removeClippedSubviews = false, sections, showsVerticalScrollIndicator, style, ref: externalRef, windowSize = 100, ...props }: SectionListProps<ItemT, SectionT>) => {
+const SectionListInner = <ItemT, SectionT extends { data: ReadonlyArray<ItemT> } = { data: ReadonlyArray<ItemT> }>({ chipProps, chipThreshold, contentContainerStyle: externalContentContainerStyle, initialNumToRender = 20, maxToRenderPerBatch = 50, renderFilters, footerFixed: footerFixedProp, gesture, headerFixed: headerFixedProp, keyboardAware, ListHeaderComponent: externalListHeaderComponent, onChipPress, onMomentumScrollEnd: externalMomentumScrollEnd, onRefresh, onContentSizeChange, onScrollBeginDrag: externalScrollBeginDrag, onScrollEndDrag: externalScrollEndDrag, pullSearchHeight, refreshing, removeClippedSubviews = false, sections, showsVerticalScrollIndicator, style, ref: externalRef, windowSize = 100, ...props }: SectionListProps<ItemT, SectionT>) => {
   const scrollView = useRef<RNSectionList<ItemT, SectionT>>(null)
 
   const { stickySectionHeadersEnabled = true, renderSectionHeader, ...passThroughProps } = props as RNSectionListProps<ItemT, SectionT>
 
   const { chipHidden, chipStyle, containerStyle, contentInset, contentOffset, footerFixed, headerFixed, headerHeight } = useScrollList({ footerFixed: footerFixedProp, headerFixed: headerFixedProp, keyboardAware, pullSearchHeight, style })
+  const { listGeneration, onListUnmount } = useContext(ScrollViewContext)
+  // -1 never matches a real generation (starts at 0, only increments) — the runOnUI call below
+  // corrects it before any scroll event could observe the placeholder.
+  const capturedGeneration = useSharedValue(-1)
+  // Layout effect (not passive effect): React guarantees all layout-effect cleanups for fibers
+  // removed in a commit run before any layout-effect setups for fibers added in that same commit,
+  // but gives no such ordering guarantee for passive effects. On a key-forced remount, the outgoing
+  // instance's unmount and the incoming instance's mount land in the same commit — with passive
+  // effects, the incoming instance's sync could run before the outgoing instance's bump, permanently
+  // capturing a stale generation and silently disabling this instance's onScroll handling forever.
+  // Correct ordering alone isn't sufficient, though: the onScroll worklet reads capturedGeneration
+  // on the UI thread, and a plain JS-thread write to a SharedValue is not guaranteed to be visible
+  // there before a scroll event the UI thread schedules shortly after (e.g. useScrollInit's mount-time
+  // imperative scrollTo calls). Routing the write itself through runOnUI puts it on the UI thread's
+  // own serial queue, so it's guaranteed to run before any onScroll worklet invocation that could
+  // only be queued after this component finishes mounting.
+  useLayoutEffect(() => {
+    const generation = listGeneration.value
+    runOnUI((gen: number) => {
+      'worklet'
+      capturedGeneration.value = gen
+    })(generation)
+  }, [capturedGeneration, listGeneration])
 
   const usesCustomSticky = stickySectionHeadersEnabled && renderSectionHeader != null
   const { activeIndex, clipStyle, measureHeader, overlayStyle, resetPositions } = useStickyHeaders(headerFixed, usesCustomSticky)
@@ -67,6 +94,8 @@ const SectionListInner = <ItemT, SectionT extends { data: ReadonlyArray<ItemT> }
     }
   }, [usesCustomSticky, renderSectionHeader, sections, measureHeader])
 
+  useLayoutEffect(() => () => onListUnmount(), [onListUnmount])
+
   const scrollTo = useCallback((offset: number, animated: boolean) => {
     scrollView.current?.getScrollResponder()?.scrollTo({ y: offset, animated })
   }, [])
@@ -117,12 +146,7 @@ const SectionListInner = <ItemT, SectionT extends { data: ReadonlyArray<ItemT> }
 
   const contentContainerStyle = useMemo(() => [{ minHeight: Dimensions.get('window').height - contentInset.top - contentInset.bottom + pullSearchMinHeight }, externalContentContainerStyle], [contentInset.bottom, contentInset.top, externalContentContainerStyle, pullSearchMinHeight])
 
-  const onPullSearchZoneEnter = useCallback(() => {
-    if (!pullSearchHeight) return
-    scrollTo(-contentInset.top + pullSearchHeight, true)
-  }, [contentInset.top, pullSearchHeight, scrollTo])
-
-  const handleScroll = useScrollHandler({ chipHidden, footerFixed, headerFixed, onPullSearchZoneEnter: pullSearchHeight ? onPullSearchZoneEnter : undefined })
+  const handleScroll = useScrollHandler({ capturedGeneration, chipHidden, chipThreshold, footerFixed, headerFixed, listGeneration })
 
   const handleScrollToTop = useCallback(() => {
     const offset = pullSearchHeight ? -contentInset.top + pullSearchHeight : -contentInset.top
@@ -144,7 +168,7 @@ const SectionListInner = <ItemT, SectionT extends { data: ReadonlyArray<ItemT> }
   const content = (
     <View style={containerStyle}>
       <AnimatedSectionList
-        key={headerHeight > 0 ? 1 : 0}
+        key={headerHeight !== null && headerHeight > 0 ? 1 : 0}
         {...passThroughProps}
         contentContainerStyle={contentContainerStyle}
         contentInset={contentInset}
@@ -175,7 +199,7 @@ const SectionListInner = <ItemT, SectionT extends { data: ReadonlyArray<ItemT> }
           {hiddenHeader}
         </View>
       )}
-      <ScrollViewChip onPress={handleScrollToTop} style={chipStyle} />
+      <ScrollViewChip chipProps={chipProps} onChipPress={onChipPress} onPress={handleScrollToTop} style={chipStyle} />
       {usesCustomSticky && (
         <Animated.View pointerEvents='none' style={[styles.stickyClip, clipStyle]}>
           {activeIndex >= 0 && activeIndex < sections.length && <Animated.View style={[styles.stickyOverlay, overlayStyle]}>{renderSectionHeader({ section: sections[activeIndex] })}</Animated.View>}

package/src/__mocks__/auto-paper.ts

@@ -3,6 +3,7 @@ import React from 'react'
 const stub = ({ children }: { children?: React.ReactNode }) => children ?? null
 
 export const BlurView = jest.fn(stub)
+export const Chip = jest.fn(stub)
 export const FAB = jest.fn(stub)
 export const usePaperDefaults = () => ({ FAB: {} })
 export const useBlur = (blur?: boolean) => blur ?? false

package/src/__mocks__/react-native-reanimated.ts

@@ -2,7 +2,34 @@ import React from 'react'
 
 const stub = ({ children }: { children?: React.ReactNode }) => children ?? null
 
-export const useSharedValue = (init: number) => ({ value: init })
+// Real Reanimated shared values persist their `.value` across re-renders (like useRef) — the
+// `init` argument is only honored on the first call. A naive `{ value: init }` per render would
+// silently discard mutations made during a previous render every time the owning component re-renders.
+export const useSharedValue = <T,>(init: T) => {
+  const ref = React.useRef<{ value: T } | null>(null)
+  if (!ref.current) ref.current = { value: init }
+  return ref.current
+}
+
+// Reanimated's useAnimatedRef returns a stable callable that also exposes `.current`, so
+// consumers can either pass it directly as a `ref` prop or read/assign `.current` imperatively.
+export const useAnimatedRef = <T,>() => {
+  const holder = React.useRef<((node: T | null) => void) & { current: T | null }>(undefined as unknown as ((node: T | null) => void) & { current: T | null })
+  if (!holder.current) {
+    let current: T | null = null
+    const fn = ((node: T | null) => {
+      current = node
+    }) as ((node: T | null) => void) & { current: T | null }
+    Object.defineProperty(fn, 'current', {
+      get: () => current,
+      set: (node: T | null) => {
+        current = node
+      }
+    })
+    holder.current = fn
+  }
+  return holder.current
+}
 export const useAnimatedStyle = (_factory: () => object) => ({})
 export const useAnimatedProps = (_factory: () => object) => ({})
 export const useAnimatedScrollHandler = (_handler: unknown) => jest.fn()
@@ -14,6 +41,10 @@ export const runOnJS =
   <T extends (...args: unknown[]) => unknown>(fn: T) =>
   (...args: Parameters<T>) =>
     fn(...args)
+export const runOnUI =
+  <T extends (...args: unknown[]) => unknown>(fn: T) =>
+  (...args: Parameters<T>) =>
+    fn(...args)
 
 export const createAnimatedComponent = (C: React.ComponentType) => C
 

package/src/__tests__/FlatList.test.tsx

@@ -1,11 +1,25 @@
 import { render } from '@testing-library/react'
 import React from 'react'
+import { FlatList as RNFlatList } from 'react-native'
 
 import { FlatList } from '../FlatList'
 import { ScrollViewProvider } from '../ScrollViewProvider'
 
 const wrapper = ({ children }: { children: React.ReactNode }) => <ScrollViewProvider>{children}</ScrollViewProvider>
 
+type MockFlatListProps = {
+  data?: unknown
+  keyExtractor?: (item: never, index: number) => string
+  numColumns?: number
+  renderItem?: (info: unknown) => React.ReactNode
+  [key: string]: unknown
+}
+
+const lastCallProps = () => {
+  const calls = (RNFlatList as unknown as jest.Mock).mock.calls
+  return calls[calls.length - 1]?.[0] as MockFlatListProps | undefined
+}
+
 describe('FlatList', () => {
   it('renders without crashing', () => {
     render(<FlatList data={[]} renderItem={() => null} />, { wrapper })
@@ -50,3 +64,72 @@ describe('FlatList', () => {
     render(<FlatList data={[]} renderItem={() => null} keyboardAware />, { wrapper })
   })
 })
+
+describe('FlatList numColumns row-chunking', () => {
+  beforeEach(() => (RNFlatList as unknown as jest.Mock).mockClear())
+
+  it('passes data through unchanged when numColumns is omitted', () => {
+    const data = ['a', 'b', 'c']
+    render(<FlatList data={data} renderItem={() => null} keyExtractor={(item) => item} />, { wrapper })
+    expect(lastCallProps()?.data).toBe(data)
+  })
+
+  it('passes data through unchanged when numColumns is 1', () => {
+    const data = ['a', 'b', 'c']
+    render(<FlatList data={data} renderItem={() => null} keyExtractor={(item) => item} numColumns={1} />, { wrapper })
+    expect(lastCallProps()?.data).toBe(data)
+  })
+
+  it('never forwards the numColumns prop itself to the underlying RNFlatList', () => {
+    render(<FlatList data={['a', 'b', 'c']} renderItem={() => null} keyExtractor={(item) => item} numColumns={3} />, { wrapper })
+    expect(lastCallProps()?.numColumns).toBeUndefined()
+  })
+
+  it('chunks data into rows of numColumns, with a partial last row', () => {
+    render(<FlatList data={['a', 'b', 'c', 'd', 'e']} renderItem={() => null} keyExtractor={(item) => item} numColumns={2} />, { wrapper })
+    expect(lastCallProps()?.data).toEqual([['a', 'b'], ['c', 'd'], ['e']])
+  })
+
+  it('row keyExtractor joins per-item keys with a colon', () => {
+    render(<FlatList data={['a', 'b', 'c', 'd']} renderItem={() => null} keyExtractor={(item) => item} numColumns={2} />, { wrapper })
+    const rowKeyExtractor = lastCallProps()?.keyExtractor
+    expect(rowKeyExtractor?.(['a', 'b'] as never, 0)).toBe('a:b')
+    expect(rowKeyExtractor?.(['c', 'd'] as never, 1)).toBe('c:d')
+  })
+
+  it('row renderItem renders every item in the row via the original renderItem', () => {
+    render(
+      <FlatList
+        data={['fig', 'kiwi', 'plum']}
+        renderItem={({ item }) => <>{item}</>}
+        keyExtractor={(item) => item}
+        numColumns={2}
+      />,
+      { wrapper }
+    )
+    const rowRenderItem = lastCallProps()?.renderItem
+    const { container } = render(rowRenderItem?.({ index: 0, item: ['fig', 'kiwi'], separators: {} as never }) as React.ReactElement)
+    expect(container.textContent).toContain('fig')
+    expect(container.textContent).toContain('kiwi')
+    expect(container.textContent).not.toContain('plum')
+  })
+
+  it('renderItem indexes items by their position across the whole flattened list, not just within the row', () => {
+    const indices: number[] = []
+    render(
+      <FlatList
+        data={['a', 'b', 'c', 'd', 'e']}
+        renderItem={({ index }) => {
+          indices.push(index)
+          return null
+        }}
+        keyExtractor={(item) => item}
+        numColumns={2}
+      />,
+      { wrapper }
+    )
+    const rowRenderItem = lastCallProps()?.renderItem
+    render(rowRenderItem?.({ index: 2, item: ['e'], separators: {} as never }) as React.ReactElement)
+    expect(indices).toEqual([4]) // row index 2 * numColumns 2 + column 0
+  })
+})

package/src/__tests__/ScrollViewProvider.test.tsx

@@ -1,4 +1,4 @@
-import { render } from '@testing-library/react'
+import { act, render } from '@testing-library/react'
 import React, { useContext } from 'react'
 
 import { ScrollViewContext } from '../ScrollViewContext'
@@ -54,7 +54,7 @@ describe('ScrollViewProvider', () => {
         <ContextReader onRead={(v) => { capturedValue = v }} />
       </ScrollViewProvider>
     )
-    capturedValue?.setProgress(0.5)
+    act(() => { capturedValue?.setProgress(0.5) })
     rerender(
       <ScrollViewProvider>
         <ContextReader onRead={(v) => { capturedValue = v }} />

package/src/__tests__/useScrollHandlerJS.test.ts

@@ -0,0 +1,119 @@
+import { renderHook } from '@testing-library/react'
+import React from 'react'
+import type { SharedValue } from 'react-native-reanimated'
+
+import { useScrollHandlerJS } from '../internal/useScrollHandlerJS'
+import { ScrollViewContext, type ScrollViewContextType } from '../ScrollViewContext'
+
+const REMOUNT_RETRY_MAX_ATTEMPTS = 8
+
+const buildContextValue = (): ScrollViewContextType =>
+  ({
+    footerHeightShared: { value: 0 },
+    footerOffset: { value: 0 },
+    headerHeightShared: { value: 0 },
+    headerOffset: { value: 0 },
+    pullSearchHeightShared: { value: 0 },
+    scrollPosition: { value: 0 },
+    snapBackFooterShared: { value: false },
+    snapBackHeaderShared: { value: false }
+  }) as unknown as ScrollViewContextType
+
+const scrollEvent = (y: number) =>
+  ({
+    nativeEvent: {
+      contentOffset: { x: 0, y },
+      contentSize: { height: 1000, width: 0 },
+      layoutMeasurement: { height: 500, width: 0 }
+    }
+  }) as never
+
+const renderScrollHandlerJS = (overrides: Partial<Parameters<typeof useScrollHandlerJS>[0]> = {}) => {
+  const contextValue = buildContextValue()
+  const chipHidden = { value: 0 } as unknown as SharedValue<number>
+  const capturedGeneration = { current: 0 }
+  const jsListGeneration = { current: 0 }
+  const scrollTo = jest.fn()
+  const wrapper = ({ children }: { children: React.ReactNode }) => React.createElement(ScrollViewContext.Provider, { value: contextValue }, children)
+  const rendered = renderHook(
+    () =>
+      useScrollHandlerJS({
+        capturedGeneration,
+        chipHidden,
+        footerFixed: false,
+        headerFixed: false,
+        jsListGeneration,
+        scrollTo,
+        ...overrides
+      }),
+    { wrapper }
+  )
+  return { ...rendered, capturedGeneration, chipHidden, contextValue, jsListGeneration, scrollTo }
+}
+
+describe('useScrollHandlerJS generation guard', () => {
+  it('processes onScroll and updates scrollPosition/chipHidden when the generation matches', () => {
+    const { result, contextValue, chipHidden } = renderScrollHandlerJS({ chipThreshold: 100 })
+    result.current.onScroll(scrollEvent(50))
+    expect(contextValue.scrollPosition.value).toBe(50)
+    expect(chipHidden.value).toBe(1) // below threshold
+
+    result.current.onScroll(scrollEvent(150))
+    expect(contextValue.scrollPosition.value).toBe(150)
+    expect(chipHidden.value).toBe(0) // at/above threshold
+  })
+
+  it('drops onScroll from a zombie handler once jsListGeneration no longer matches its capturedGeneration', () => {
+    const { result, contextValue, capturedGeneration, jsListGeneration } = renderScrollHandlerJS()
+    result.current.onScroll(scrollEvent(10))
+    expect(contextValue.scrollPosition.value).toBe(10)
+
+    // Another list instance mounted/unmounted elsewhere and bumped the shared generation counter —
+    // this handler's own capturedGeneration (frozen at mount) is now stale.
+    jsListGeneration.current = 1
+    expect(capturedGeneration.current).toBe(0)
+
+    result.current.onScroll(scrollEvent(999))
+    expect(contextValue.scrollPosition.value).toBe(10) // unchanged — the stale event was ignored
+  })
+
+  it('lets a fresh instance keep working even while a stale sibling is guarded out', () => {
+    const jsListGeneration = { current: 1 }
+    const { result, contextValue } = renderScrollHandlerJS({ capturedGeneration: { current: 1 }, jsListGeneration })
+    result.current.onScroll(scrollEvent(42))
+    expect(contextValue.scrollPosition.value).toBe(42)
+  })
+})
+
+describe('useScrollHandlerJS remount retry', () => {
+  it('retries with a non-animated scrollTo until an onScroll event confirms the target position', () => {
+    const { result, scrollTo, contextValue } = renderScrollHandlerJS({ remountTarget: -40 })
+    result.current.onScroll(scrollEvent(0)) // native reports the wrong position
+    expect(scrollTo).toHaveBeenCalledWith(-40, false)
+    expect(contextValue.scrollPosition.value).toBe(0) // not yet treated as a real scroll position
+
+    scrollTo.mockClear()
+    result.current.onScroll(scrollEvent(-40)) // confirmed
+    expect(scrollTo).not.toHaveBeenCalled()
+    expect(contextValue.scrollPosition.value).toBe(-40) // now processed normally
+  })
+
+  it('gives up after REMOUNT_RETRY_MAX_ATTEMPTS and falls through to normal processing rather than blocking forever', () => {
+    const { result, scrollTo, contextValue } = renderScrollHandlerJS({ remountTarget: -40 })
+    for (let i = 0; i < REMOUNT_RETRY_MAX_ATTEMPTS; i += 1) result.current.onScroll(scrollEvent(0))
+    expect(scrollTo).toHaveBeenCalledTimes(REMOUNT_RETRY_MAX_ATTEMPTS)
+
+    scrollTo.mockClear()
+    result.current.onScroll(scrollEvent(0)) // one more, past the max — gives up
+    expect(scrollTo).not.toHaveBeenCalled()
+    expect(contextValue.scrollPosition.value).toBe(0) // accepted as-is instead of retrying forever
+  })
+
+  it('the generation guard takes precedence over an in-progress remount retry', () => {
+    const { result, scrollTo, contextValue, jsListGeneration } = renderScrollHandlerJS({ remountTarget: -40 })
+    jsListGeneration.current = 1 // stale before the remount retry ever gets a chance to run
+    result.current.onScroll(scrollEvent(0))
+    expect(scrollTo).not.toHaveBeenCalled()
+    expect(contextValue.scrollPosition.value).toBe(0) // untouched — onScroll bailed out immediately
+  })
+})