@rific/scroll-view 0.1.1 → 0.3.0

package/src/__tests__/useScrollInit.test.ts

@@ -0,0 +1,251 @@
+import { act, renderHook } from '@testing-library/react'
+import React from 'react'
+
+import { ScrollViewContext, type ScrollViewContextType } from '../ScrollViewContext'
+import { useScrollInit } from '../useScrollInit'
+
+const HEADER_HEIGHT = 80
+const PULL_SEARCH_HEIGHT = 40
+const REMOUNT_SYNC_MAX_ATTEMPTS = 8
+const SNAP_VERIFY_MAX_ATTEMPTS = 5
+const SNAP_VERIFY_INITIAL_DELAY_MS = 400
+const SNAP_VERIFY_RETRY_DELAY_MS = 150
+
+const buildContextValue = (headerHeight: number | null): ScrollViewContextType =>
+  ({
+    blur: true,
+    footerHeight: 0,
+    footerHeightShared: { value: 0 },
+    footerFixed: false,
+    footerOffset: { value: 0 },
+    headerHeight,
+    headerHeightShared: { value: headerHeight ?? 0 },
+    headerFixed: false,
+    headerOffset: { value: 0 },
+    listGeneration: { value: 0 },
+    onListUnmount: jest.fn(),
+    progress: null,
+    progressing: false,
+    pullSearchHeightShared: { value: 0 },
+    scrollHeight: 0,
+    scrollPosition: { value: 0 },
+    setFooterHeight: jest.fn(),
+    setHeaderHeight: jest.fn(),
+    setProgress: jest.fn(),
+    setProgressing: jest.fn(),
+    snapBackFooterShared: { value: false },
+    snapBackHeaderShared: { value: false },
+    tabBarHeight: 60
+  }) as unknown as ScrollViewContextType
+
+const renderInit = (headerHeight: number | null, pullSearchHeight?: number) => {
+  const contextValue = buildContextValue(headerHeight)
+  const scrollTo = jest.fn()
+  const wrapper = ({ children }: { children: React.ReactNode }) => React.createElement(ScrollViewContext.Provider, { value: contextValue }, children)
+  const rendered = renderHook(() => useScrollInit({ pullSearchHeight, scrollTo }), { wrapper })
+  return { ...rendered, contextValue, scrollTo }
+}
+
+describe('useScrollInit remount sync', () => {
+  it('true first mount (headerHeight null) skips remount-sync and starts ready', () => {
+    const { result, unmount } = renderInit(null)
+    expect(result.current.scrollReady).toBe(true)
+    expect(result.current.remountSyncTarget.value).toBeNull()
+    unmount()
+  })
+
+  it('remount (headerHeight already known at mount) hides the list and targets showY', () => {
+    const { result, scrollTo, unmount } = renderInit(HEADER_HEIGHT)
+    expect(result.current.scrollReady).toBe(false)
+    expect(result.current.remountSyncTarget.value).toBe(-HEADER_HEIGHT)
+    // Primes a corrective scrollTo immediately, rather than assuming native honored the initial contentOffset.
+    expect(scrollTo).toHaveBeenCalledWith(-HEADER_HEIGHT, false)
+    unmount()
+  })
+
+  it('remount with pullSearchHeight targets hideY directly (skips the 2-phase first-mount dance)', () => {
+    const { result, unmount } = renderInit(HEADER_HEIGHT, 40)
+    expect(result.current.remountSyncTarget.value).toBe(-HEADER_HEIGHT + 40)
+    unmount()
+  })
+
+  it('retries the corrective scrollTo when an onScroll event reports the wrong position, and stays hidden', () => {
+    const { result, scrollTo, unmount } = renderInit(HEADER_HEIGHT)
+    scrollTo.mockClear()
+    act(() => {
+      result.current.onRemountSyncRetry(0) // a spurious post-remount event reporting y=0
+    })
+    expect(scrollTo).toHaveBeenCalledWith(-HEADER_HEIGHT, false)
+    expect(result.current.scrollReady).toBe(false)
+    unmount()
+  })
+
+  it('reveals once a confirmed on-target event arrives', () => {
+    const { result, contextValue, unmount } = renderInit(HEADER_HEIGHT)
+    act(() => {
+      result.current.onRemountSynced(-HEADER_HEIGHT)
+    })
+    expect(result.current.scrollReady).toBe(true)
+    expect(contextValue.scrollPosition.value).toBe(-HEADER_HEIGHT)
+    unmount()
+  })
+
+  it('gives up and reveals anyway after exceeding the max retry attempts, rather than hiding forever', () => {
+    const { result, unmount } = renderInit(HEADER_HEIGHT)
+    act(() => {
+      for (let i = 0; i < REMOUNT_SYNC_MAX_ATTEMPTS + 2; i += 1) result.current.onRemountSyncRetry(0)
+    })
+    expect(result.current.scrollReady).toBe(true)
+    expect(result.current.remountSyncTarget.value).toBeNull()
+    unmount()
+  })
+})
+
+const dragEvent = (y: number) => ({ nativeEvent: { contentOffset: { y } } }) as never
+
+// A true first mount (not a remount): headerHeight starts null, then a rerender simulates the
+// header's async measurement landing, mirroring the real production flow. Using a non-null
+// headerHeight from the start (like the remount-sync tests above) would make useScrollInit treat
+// this as a remount and pull in unrelated machinery — the priming scrollTo, the 40-frame RAF
+// oscillation, and the REMOUNT_SYNC_FALLBACK_MS timer — none of which is relevant to the pull-search
+// snap logic under test here.
+const renderPullSearchInit = (pullSearchHeight: number) => {
+  const scrollTo = jest.fn()
+  let contextValue = buildContextValue(null)
+  const wrapper = ({ children }: { children: React.ReactNode }) => React.createElement(ScrollViewContext.Provider, { value: contextValue }, children)
+  const rendered = renderHook(() => useScrollInit({ pullSearchHeight, scrollTo }), { wrapper })
+  act(() => {
+    contextValue = buildContextValue(HEADER_HEIGHT)
+    rendered.rerender()
+  })
+  scrollTo.mockClear() // drop Effect A's insurance call and Effect B's showY->hideY push
+  return { ...rendered, contextValue, scrollTo }
+}
+
+describe('useScrollInit pull-search snap', () => {
+  const showY = -HEADER_HEIGHT
+  const hideY = -HEADER_HEIGHT + PULL_SEARCH_HEIGHT
+
+  beforeEach(() => jest.useFakeTimers())
+  afterEach(() => jest.useRealTimers())
+
+  it('opens toward showY when dragged down past half the pull-search height', () => {
+    const { result, scrollTo, unmount } = renderPullSearchInit(PULL_SEARCH_HEIGHT)
+    act(() => {
+      result.current.handleScrollBeginDrag(dragEvent(hideY))
+      result.current.handleScrollEndDrag(dragEvent(showY))
+    })
+    expect(scrollTo).toHaveBeenCalledWith(showY, true)
+    unmount()
+  })
+
+  it('closes toward hideY when released without pulling past the half threshold', () => {
+    const { result, scrollTo, unmount } = renderPullSearchInit(PULL_SEARCH_HEIGHT)
+    act(() => {
+      result.current.handleScrollBeginDrag(dragEvent(hideY))
+      result.current.handleScrollEndDrag(dragEvent(hideY - 10))
+    })
+    expect(scrollTo).toHaveBeenCalledWith(hideY, true)
+    unmount()
+  })
+
+  it('does nothing when the release lands outside the pull-search zone entirely', () => {
+    const { result, scrollTo, unmount } = renderPullSearchInit(PULL_SEARCH_HEIGHT)
+    act(() => {
+      result.current.handleScrollBeginDrag(dragEvent(0))
+      result.current.handleScrollEndDrag(dragEvent(0))
+    })
+    expect(scrollTo).not.toHaveBeenCalled()
+    unmount()
+  })
+
+  it('keeps retrying (non-animated) until scrollPosition actually confirms the target, then stops', () => {
+    const { result, scrollTo, contextValue, unmount } = renderPullSearchInit(PULL_SEARCH_HEIGHT)
+    contextValue.scrollPosition.value = hideY
+    act(() => {
+      result.current.handleScrollBeginDrag(dragEvent(hideY))
+      result.current.handleScrollEndDrag(dragEvent(showY))
+    })
+    expect(scrollTo).toHaveBeenCalledTimes(1) // the initial animated call
+
+    act(() => {
+      jest.advanceTimersByTime(SNAP_VERIFY_INITIAL_DELAY_MS)
+    })
+    expect(scrollTo).toHaveBeenLastCalledWith(showY, false) // first non-animated retry, still short of target
+
+    // The retry "lands" — simulate onScroll confirming the real position.
+    contextValue.scrollPosition.value = showY
+    act(() => {
+      jest.advanceTimersByTime(SNAP_VERIFY_RETRY_DELAY_MS)
+    })
+    scrollTo.mockClear()
+    act(() => {
+      jest.advanceTimersByTime(SNAP_VERIFY_RETRY_DELAY_MS * 5)
+    })
+    expect(scrollTo).not.toHaveBeenCalled() // verification stopped once confirmed
+    unmount()
+  })
+
+  it('gives up after exceeding the max retry attempts rather than retrying forever', () => {
+    const { result, scrollTo, contextValue, unmount } = renderPullSearchInit(PULL_SEARCH_HEIGHT)
+    contextValue.scrollPosition.value = hideY // never reaches showY, no matter how many retries
+    act(() => {
+      result.current.handleScrollBeginDrag(dragEvent(hideY))
+      result.current.handleScrollEndDrag(dragEvent(showY))
+    })
+    act(() => {
+      jest.advanceTimersByTime(SNAP_VERIFY_INITIAL_DELAY_MS + SNAP_VERIFY_RETRY_DELAY_MS * (SNAP_VERIFY_MAX_ATTEMPTS + 1))
+    })
+    // 1 initial animated call + SNAP_VERIFY_MAX_ATTEMPTS non-animated retries, then it gives up.
+    expect(scrollTo).toHaveBeenCalledTimes(1 + SNAP_VERIFY_MAX_ATTEMPTS)
+
+    scrollTo.mockClear()
+    act(() => {
+      jest.advanceTimersByTime(SNAP_VERIFY_RETRY_DELAY_MS * 3)
+    })
+    expect(scrollTo).not.toHaveBeenCalled()
+    unmount()
+  })
+
+  it('cancels a pending verification when a new drag begins', () => {
+    const { result, scrollTo, contextValue, unmount } = renderPullSearchInit(PULL_SEARCH_HEIGHT)
+    contextValue.scrollPosition.value = hideY
+    act(() => {
+      result.current.handleScrollBeginDrag(dragEvent(hideY))
+      result.current.handleScrollEndDrag(dragEvent(showY))
+    })
+    scrollTo.mockClear()
+    act(() => {
+      result.current.handleScrollBeginDrag(dragEvent(showY))
+    })
+    act(() => {
+      jest.advanceTimersByTime(SNAP_VERIFY_INITIAL_DELAY_MS * 3)
+    })
+    expect(scrollTo).not.toHaveBeenCalled()
+    unmount()
+  })
+
+  it('handleMomentumScrollEnd auto-closes when momentum alone carried it into the zone with no drag-committed target', () => {
+    const { result, scrollTo, unmount } = renderPullSearchInit(PULL_SEARCH_HEIGHT)
+    act(() => {
+      result.current.handleMomentumScrollEnd(dragEvent(hideY - 10))
+    })
+    expect(scrollTo).toHaveBeenCalledWith(hideY, true)
+    unmount()
+  })
+
+  it('handleMomentumScrollEnd defers to an already-pending drag-committed target instead of double-correcting', () => {
+    const { result, scrollTo, contextValue, unmount } = renderPullSearchInit(PULL_SEARCH_HEIGHT)
+    contextValue.scrollPosition.value = hideY
+    act(() => {
+      result.current.handleScrollBeginDrag(dragEvent(hideY))
+      result.current.handleScrollEndDrag(dragEvent(showY))
+    })
+    scrollTo.mockClear()
+    act(() => {
+      result.current.handleMomentumScrollEnd(dragEvent(hideY - 10))
+    })
+    expect(scrollTo).not.toHaveBeenCalled()
+    unmount()
+  })
+})

package/src/index.ts

@@ -2,6 +2,7 @@ export type { CustomListProps } from './CustomList'
 export { CustomList } from './CustomList'
 export type { FlatListProps } from './FlatList'
 export { FlatList } from './FlatList'
+export type { ChipProps } from './internal/ScrollViewChip'
 export type { PullSearchHandle, PullSearchProps } from './PullSearch'
 export { PullSearch } from './PullSearch'
 export { scrollViewActions, scrollViewReducer } from './redux/scrollViewSlice'

package/src/internal/ScrollViewChip.tsx

@@ -1,20 +1,36 @@
+import { Chip, type ChipProps as AutoPaperChipProps } from '@rific/auto-paper'
+import { type ReactNode } from 'react'
 import { StyleSheet, type ViewStyle } from 'react-native'
-import { Chip } from 'react-native-paper'
 import Animated, { type AnimatedStyle } from 'react-native-reanimated'
 
+export type ChipProps = Omit<AutoPaperChipProps, 'compact' | 'icon' | 'onPress'> & {
+  label?: ReactNode
+}
+
 type Props = {
+  chipProps?: ChipProps
   isHorizontal?: boolean
+  onChipPress?: () => void
   onPress: () => void
   style: AnimatedStyle<ViewStyle>
 }
 
-export const ScrollViewChip = ({ isHorizontal, onPress, style }: Props) => (
-  <Animated.View style={[styles.chip, style]}>
-    <Chip compact icon={isHorizontal ? 'chevron-left' : 'chevron-up'} onPress={onPress} style={styles.chipInner}>
-      {isHorizontal ? 'Start' : 'Top'}
-    </Chip>
-  </Animated.View>
-)
+export const ScrollViewChip = ({ chipProps, isHorizontal, onChipPress, onPress, style }: Props) => {
+  const { label, style: chipStyle, ...restChipProps } = (chipProps ?? {}) as Partial<ChipProps>
+  const handlePress = onChipPress
+    ? () => {
+        onPress()
+        onChipPress()
+      }
+    : onPress
+  return (
+    <Animated.View style={[styles.chip, style]}>
+      <Chip compact {...restChipProps} icon={isHorizontal ? 'chevron-left' : 'chevron-up'} onPress={handlePress} style={[styles.chipInner, chipStyle]}>
+        {label ?? (isHorizontal ? 'Start' : 'Top')}
+      </Chip>
+    </Animated.View>
+  )
+}
 
 const styles = StyleSheet.create({
   chip: { alignItems: 'center', left: 0, position: 'absolute', right: 0, zIndex: 3 },

package/src/internal/useScrollHandler.ts

@@ -3,34 +3,49 @@ import type { SharedValue } from 'react-native-reanimated'
 import { runOnJS, useAnimatedScrollHandler, useSharedValue, withTiming } from 'react-native-reanimated'
 
 import { ScrollViewContext } from '../ScrollViewContext'
+import { REMOUNT_SYNC_TOLERANCE } from '../useScrollInit'
 
 type UseScrollHandlerOptions = {
+  capturedGeneration: SharedValue<number>
   chipHidden: SharedValue<number>
+  chipThreshold?: number
   footerFixed: boolean
   headerFixed: boolean
   isHorizontal?: boolean
-  onPullSearchZoneEnter?: () => void
+  listGeneration: SharedValue<number>
+  onRemountSyncRetry?: (currentY: number) => void
+  onRemountSynced?: (y: number) => void
+  remountSyncTarget?: SharedValue<number | null>
 }
 
-export function useScrollHandler({ chipHidden, footerFixed, headerFixed, isHorizontal, onPullSearchZoneEnter }: UseScrollHandlerOptions) {
+export function useScrollHandler({ capturedGeneration, chipHidden, chipThreshold = 100, footerFixed, headerFixed, isHorizontal, listGeneration, onRemountSyncRetry, onRemountSynced, remountSyncTarget }: UseScrollHandlerOptions) {
   const { footerHeightShared, footerOffset, headerHeightShared, headerOffset, pullSearchHeightShared, scrollPosition, snapBackFooterShared, snapBackHeaderShared } = useContext(ScrollViewContext)
   const snapUpAccum = useSharedValue(0)
   const fromBottomBounce = useSharedValue(false)
-  const isMomentum = useSharedValue(false)
-  const momentumPullSearchFired = useSharedValue(false)
 
   return useAnimatedScrollHandler(
     {
       onScroll: ({ contentOffset: { x, y }, contentSize: { height: contentHeight }, layoutMeasurement: { height: layoutHeight } }) => {
         'worklet'
+        if (remountSyncTarget && remountSyncTarget.value !== null) {
+          const target = remountSyncTarget.value
+          if (Math.abs(y - target) < REMOUNT_SYNC_TOLERANCE) {
+            remountSyncTarget.value = null
+            if (onRemountSynced) runOnJS(onRemountSynced)(y)
+          } else if (onRemountSyncRetry) {
+            runOnJS(onRemountSyncRetry)(y)
+          }
+          return
+        }
+        if (listGeneration.value !== capturedGeneration.value) return
         if (isHorizontal) {
           scrollPosition.value = x
-          chipHidden.value = x < 100 ? 1 : 0
+          chipHidden.value = x < chipThreshold ? 1 : 0
           return
         }
         const delta = y - scrollPosition.value
         scrollPosition.value = y
-        chipHidden.value = y < 100 ? 1 : 0
+        chipHidden.value = y < chipThreshold ? 1 : 0
         const maxScroll = contentHeight - layoutHeight
         if (maxScroll > 0 && y >= maxScroll) {
           fromBottomBounce.value = true
@@ -38,13 +53,6 @@ export function useScrollHandler({ chipHidden, footerFixed, headerFixed, isHoriz
         } else if (fromBottomBounce.value) {
           fromBottomBounce.value = false
         }
-        if (isMomentum.value && pullSearchHeightShared.value > 0 && !momentumPullSearchFired.value) {
-          const hideY = -headerHeightShared.value + pullSearchHeightShared.value
-          if (y < hideY) {
-            momentumPullSearchFired.value = true
-            if (onPullSearchZoneEnter) runOnJS(onPullSearchZoneEnter)()
-          }
-        }
         const snapHeader = snapBackHeaderShared.value && !headerFixed
         const snapFooter = snapBackFooterShared.value && !footerFixed
         if (snapHeader || snapFooter) {
@@ -70,16 +78,9 @@ export function useScrollHandler({ chipHidden, footerFixed, headerFixed, isHoriz
       },
       onBeginDrag: () => {
         'worklet'
-        isMomentum.value = false
-        momentumPullSearchFired.value = false
         fromBottomBounce.value = false
         snapUpAccum.value = 0
       },
-      onMomentumBegin: () => {
-        'worklet'
-        isMomentum.value = true
-        momentumPullSearchFired.value = false
-      },
       onEndDrag: ({ contentOffset: { y }, contentSize: { height: contentHeight }, layoutMeasurement: { height: layoutHeight } }) => {
         'worklet'
         if (isHorizontal) return
@@ -90,12 +91,10 @@ export function useScrollHandler({ chipHidden, footerFixed, headerFixed, isHoriz
       },
       onMomentumEnd: () => {
         'worklet'
-        isMomentum.value = false
-        momentumPullSearchFired.value = false
         fromBottomBounce.value = false
         snapUpAccum.value = 0
       }
     },
-    [headerFixed, footerFixed, isHorizontal, onPullSearchZoneEnter]
+    [capturedGeneration, headerFixed, footerFixed, isHorizontal, chipThreshold, listGeneration, onRemountSyncRetry, onRemountSynced, remountSyncTarget]
   )
 }

package/src/internal/useScrollHandlerJS.ts

@@ -0,0 +1,141 @@
+import { type RefObject, useCallback, useContext, useRef } from 'react'
+import type { NativeScrollEvent, NativeSyntheticEvent } from 'react-native'
+import type { SharedValue } from 'react-native-reanimated'
+import { withTiming } from 'react-native-reanimated'
+
+import { ScrollViewContext } from '../ScrollViewContext'
+
+const REMOUNT_RETRY_TOLERANCE = 1
+const REMOUNT_RETRY_MAX_ATTEMPTS = 8
+
+type UseScrollHandlerJSOptions = {
+  capturedGeneration: RefObject<number>
+  chipHidden: SharedValue<number>
+  chipThreshold?: number
+  footerFixed: boolean
+  headerFixed: boolean
+  isHorizontal?: boolean
+  jsListGeneration: RefObject<number>
+  remountTarget?: number | null
+  scrollTo?: (offset: number, animated: boolean) => void
+}
+
+export type ScrollHandlerJS = {
+  onMomentumScrollBegin: (e: NativeSyntheticEvent<NativeScrollEvent>) => void
+  onMomentumScrollEnd: (e: NativeSyntheticEvent<NativeScrollEvent>) => void
+  onScroll: (e: NativeSyntheticEvent<NativeScrollEvent>) => void
+  onScrollBeginDrag: (e: NativeSyntheticEvent<NativeScrollEvent>) => void
+  onScrollEndDrag: (e: NativeSyntheticEvent<NativeScrollEvent>) => void
+}
+
+// Plain JS-thread scroll handler for a non-Animated scrollable. Reanimated shared values are
+// readable/writable from any thread, so driving them via a regular onScroll callback (rather than
+// a useAnimatedScrollHandler worklet, which requires an Animated-wrapped component to attach to at
+// the native level) works fine here — the header/footer animations just pick up the change on
+// their next UI-thread frame. This trades a small amount of latency for a plain scrollable that
+// reliably honors the initial `contentOffset` prop on (re)mount, which Animated.FlatList does not.
+export function useScrollHandlerJS({ capturedGeneration, chipHidden, chipThreshold = 100, footerFixed, headerFixed, isHorizontal, jsListGeneration, remountTarget = null, scrollTo }: UseScrollHandlerJSOptions): ScrollHandlerJS {
+  const { footerHeightShared, footerOffset, headerHeightShared, headerOffset, pullSearchHeightShared, scrollPosition, snapBackFooterShared, snapBackHeaderShared } = useContext(ScrollViewContext)
+  const snapUpAccum = useRef(0)
+  const fromBottomBounce = useRef(false)
+  // On a remount, the very first native position after mount isn't reliable — Fabric can skip
+  // reapplying `contentOffset` when the target is numerically unchanged from before, and native
+  // scroll settling can overshoot or undershoot it. Rather than trust either the declarative prop
+  // or a single imperative scrollTo call, keep correcting (without hiding anything — content stays
+  // visible throughout) until an onScroll event actually confirms the intended resting position.
+  const pendingRemountTarget = useRef(remountTarget)
+  const remountAttempts = useRef(0)
+
+  const onScroll = useCallback(
+    (event: NativeSyntheticEvent<NativeScrollEvent>) => {
+      if (jsListGeneration.current !== capturedGeneration.current) return
+      const {
+        contentOffset: { x, y },
+        contentSize: { height: contentHeight },
+        layoutMeasurement: { height: layoutHeight }
+      } = event.nativeEvent
+      if (pendingRemountTarget.current !== null) {
+        const target = pendingRemountTarget.current
+        if (Math.abs(y - target) < REMOUNT_RETRY_TOLERANCE) {
+          pendingRemountTarget.current = null
+        } else {
+          remountAttempts.current += 1
+          if (remountAttempts.current > REMOUNT_RETRY_MAX_ATTEMPTS) {
+            pendingRemountTarget.current = null
+          } else {
+            scrollTo?.(target, false)
+            return
+          }
+        }
+      }
+      if (isHorizontal) {
+        scrollPosition.value = x
+        chipHidden.value = x < chipThreshold ? 1 : 0
+        return
+      }
+      const delta = y - scrollPosition.value
+      scrollPosition.value = y
+      chipHidden.value = y < chipThreshold ? 1 : 0
+      const maxScroll = contentHeight - layoutHeight
+      if (maxScroll > 0 && y >= maxScroll) {
+        fromBottomBounce.current = true
+        snapUpAccum.current = 0
+      } else if (fromBottomBounce.current) {
+        fromBottomBounce.current = false
+      }
+      const snapHeader = snapBackHeaderShared.value && !headerFixed
+      const snapFooter = snapBackFooterShared.value && !footerFixed
+      if (snapHeader || snapFooter) {
+        if (y <= -headerHeightShared.value) {
+          snapUpAccum.current = 0
+          if (snapHeader) headerOffset.value = 0
+          if (snapFooter) footerOffset.value = 0
+        } else if (delta > 0) {
+          snapUpAccum.current = 0
+          if (y >= -headerHeightShared.value + pullSearchHeightShared.value) {
+            if (snapHeader) headerOffset.value = Math.max(-headerHeightShared.value, Math.min(0, headerOffset.value - delta))
+            if (snapFooter) footerOffset.value = Math.max(0, Math.min(footerHeightShared.value, footerOffset.value + delta))
+          }
+        } else if (delta < 0 && !fromBottomBounce.current) {
+          if (y >= -headerHeightShared.value + pullSearchHeightShared.value) snapUpAccum.current -= delta
+          if (snapUpAccum.current >= 10) {
+            snapUpAccum.current = 999
+            if (snapHeader) headerOffset.value = withTiming(0, { duration: 200 })
+            if (snapFooter) footerOffset.value = withTiming(0, { duration: 200 })
+          }
+        }
+      }
+    },
+    [capturedGeneration, chipHidden, chipThreshold, footerFixed, footerHeightShared, footerOffset, headerFixed, headerHeightShared, headerOffset, isHorizontal, jsListGeneration, pullSearchHeightShared, scrollPosition, scrollTo, snapBackFooterShared, snapBackHeaderShared]
+  )
+
+  const onScrollBeginDrag = useCallback(() => {
+    fromBottomBounce.current = false
+    snapUpAccum.current = 0
+  }, [])
+
+  const onMomentumScrollBegin = useCallback(() => {}, [])
+
+  const onScrollEndDrag = useCallback(
+    (event: NativeSyntheticEvent<NativeScrollEvent>) => {
+      if (isHorizontal) return
+      const {
+        contentOffset: { y },
+        contentSize: { height: contentHeight },
+        layoutMeasurement: { height: layoutHeight }
+      } = event.nativeEvent
+      if (y >= contentHeight - layoutHeight - 10) {
+        fromBottomBounce.current = true
+        snapUpAccum.current = 0
+      }
+    },
+    [isHorizontal]
+  )
+
+  const onMomentumScrollEnd = useCallback(() => {
+    fromBottomBounce.current = false
+    snapUpAccum.current = 0
+  }, [])
+
+  return { onMomentumScrollBegin, onMomentumScrollEnd, onScroll, onScrollBeginDrag, onScrollEndDrag }
+}

package/src/internal/useScrollList.ts

@@ -1,4 +1,4 @@
-import { useContext, useEffect, useMemo } from 'react'
+import { useContext, useEffect, useMemo, useState } from 'react'
 import { type StyleProp, StyleSheet, type ViewStyle } from 'react-native'
 import { useAnimatedStyle, useSharedValue, withTiming } from 'react-native-reanimated'
 import { useSafeAreaInsets } from 'react-native-safe-area-context'
@@ -29,15 +29,19 @@ export function useScrollList({ footerFixed: footerFixedProp, headerFixed: heade
     pullSearchHeightShared.value = pullSearchHeight ?? 0
   }, [pullSearchHeight, pullSearchHeightShared])
 
-  // First render (headerHeight===0): flex:1 so the list sits naturally below the in-flow header.
-  // After header measures: absoluteFill with contentOffset to match the same visual position.
-  const containerStyle = useMemo(() => (headerHeight === 0 ? [{ flex: 1 }, style] : [StyleSheet.absoluteFill, style]), [headerHeight, style])
+  // First render (headerHeight===0): flex:1, hidden until header measures so the key=0→1
+  // transition (and contentOffset change) never appears as a visible jump.
+  // After header measures: absoluteFill with correct contentOffset — then reveal.
+  const containerStyle = useMemo(() => (headerHeight === null ? [{ flex: 1, opacity: 0 }, style] : [StyleSheet.absoluteFill, style]), [headerHeight, style])
 
-  const contentInset = useMemo(() => ({ bottom: (footerFixed ? footerHeight || insets.bottom : insets.bottom) + (keyboardAware ? keyboardHeight : 0), top: headerHeight }), [footerFixed, footerHeight, insets.bottom, headerHeight, keyboardAware, keyboardHeight])
+  const contentInset = useMemo(() => ({ bottom: (footerFixed ? footerHeight || insets.bottom : insets.bottom) + (keyboardAware ? keyboardHeight : 0), top: headerHeight ?? 0 }), [footerFixed, footerHeight, insets.bottom, headerHeight, keyboardAware, keyboardHeight])
 
-  // Synchronously positions the scroll view to match the in-flow layout from the first render.
-  // Fabric applies this atomically with the containerStyle switch, so there is no visible jump.
-  const contentOffset = useMemo(() => ({ x: 0, y: -contentInset.top }), [contentInset.top])
+  // Use hideY offset only when this component mounted with headerHeight already known (mode switch).
+  // On initial load, headerHeight is null at mount so we start at showY and let useScrollInit
+  // call scrollTo after the phase transition. On mode switch, headerHeight is already set so we
+  // can position the FlatList at hideY atomically via contentOffset — no scrollTo needed.
+  const [startedWithHeader] = useState(headerHeight !== null)
+  const contentOffset = useMemo(() => ({ x: 0, y: headerHeight !== null ? -headerHeight + (startedWithHeader && !isHorizontal && pullSearchHeight ? pullSearchHeight : 0) : 0 }), [headerHeight, isHorizontal, pullSearchHeight, startedWithHeader])
 
   const chipHidden = useSharedValue(1)
   const chipStyle = useAnimatedStyle(() => {
@@ -46,12 +50,13 @@ export function useScrollList({ footerFixed: footerFixedProp, headerFixed: heade
       return {
         opacity: chipHidden.value ? withTiming(0) : withTiming(1),
         pointerEvents,
-        top: Math.max(headerHeight, insets.top) + 4,
+        top: Math.max(headerHeight ?? 0, insets.top) + 4,
         transform: [{ translateX: chipHidden.value ? withTiming(-CHIP_SLIDE) : withTiming(0) }]
       }
     }
-    const slide = headerFixed ? 0 : snapBackHeaderShared.value ? -headerOffset.value : Math.max(0, scrollPosition.value + headerHeight - pullSearchHeightShared.value)
-    const top = Math.max(headerHeight - slide, insets.top) + 4
+    const h = headerHeight ?? 0
+    const slide = headerFixed ? 0 : snapBackHeaderShared.value ? -headerOffset.value : Math.max(0, scrollPosition.value + h - pullSearchHeightShared.value)
+    const top = Math.max(h - slide, insets.top) + 4
     return {
       opacity: chipHidden.value ? withTiming(0) : withTiming(1),
       pointerEvents,