@rific/scroll-view 0.4.3 → 0.5.0

package/src/ScrollViewProvider.tsx

@@ -10,6 +10,7 @@ export type ScrollViewProviderProps = {
   blur?: boolean
   children: ReactNode
   fixed?: boolean
+  footerAboveKeyboard?: boolean
   footerFixed?: boolean
   headerFixed?: boolean
   snapBack?: boolean
@@ -18,7 +19,7 @@ export type ScrollViewProviderProps = {
   tabBarHeight?: number
 }
 
-export const ScrollViewProvider = ({ blur, children, fixed = false, footerFixed, headerFixed, snapBack, snapBackFooter, snapBackHeader, tabBarHeight = 60 }: ScrollViewProviderProps) => {
+export const ScrollViewProvider = ({ blur, children, fixed = false, footerAboveKeyboard = false, footerFixed, headerFixed, snapBack, snapBackFooter, snapBackHeader, tabBarHeight = 0 }: ScrollViewProviderProps) => {
   const { settings } = useContext(ScrollViewSettingsContext)
   const effectiveBlur = useBlur(blur)
   const effectiveSnapBack = snapBack ?? settings.snapBack
@@ -44,10 +45,16 @@ export const ScrollViewProvider = ({ blur, children, fixed = false, footerFixed,
   }, [effectiveSnapBack, effectiveSnapBackFooter, effectiveSnapBackHeader, snapBackFooterShared, snapBackHeaderShared])
   const setHeaderHeight = useCallback(
     (h: number | null) => {
+      // react-native-screens' web shim hides an inactive screen via display:none on an
+      // ancestor instead of unmounting it, so the header's ResizeObserver-backed onLayout
+      // keeps firing while hidden and reports a spurious 0 (no layout box), then again once
+      // revealed. Never let a spurious 0 clobber a real height — only a true remount
+      // (headerHeight reset to null) should ever legitimately shrink it back to 0.
+      if (h === 0 && headerHeight) return
       setHeaderHeightState(h)
       headerHeightShared.value = h ?? 0
     },
-    [headerHeightShared]
+    [headerHeight, headerHeightShared]
   )
   const onListUnmount = useCallback(() => {
     listGeneration.value += 1
@@ -73,6 +80,6 @@ export const ScrollViewProvider = ({ blur, children, fixed = false, footerFixed,
   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, 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])
+  const value = useMemo(() => ({ blur: effectiveBlur, footerAboveKeyboard, 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, footerAboveKeyboard, 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/SectionList.tsx

@@ -1,5 +1,5 @@
 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 { Dimensions, type NativeScrollEvent, type NativeSyntheticEvent, Platform, SectionList as RNSectionList, type SectionListProps as RNSectionListProps, View } from 'react-native'
 import { Gesture, GestureDetector, type GestureType } from 'react-native-gesture-handler'
 import Animated, { runOnUI, useSharedValue } from 'react-native-reanimated'
 
@@ -34,7 +34,7 @@ const SectionListInner = <ItemT, SectionT extends { data: ReadonlyArray<ItemT> }
 
   const { stickySectionHeadersEnabled = true, renderSectionHeader, ...passThroughProps } = props as RNSectionListProps<ItemT, SectionT>
 
-  const { chipHidden, chipStyle, containerStyle, contentInset, contentOffset, contentPadding, footerFixed, headerFixed, headerHeight } = useScrollList({ footerFixed: footerFixedProp, headerFixed: headerFixedProp, keyboardAware, pullSearchHeight, style })
+  const { chipHidden, chipStyle, containerStyle, contentInset, contentOffset, contentPadding, footerFixed, headerFixed, headerHeight } = useScrollList({ footerFixed: footerFixedProp, headerFixed: headerFixedProp, hideUntilMeasured: true, 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.
@@ -51,8 +51,16 @@ const SectionListInner = <ItemT, SectionT extends { data: ReadonlyArray<ItemT> }
   // 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.
+  //
+  // Web has no such thread split, though — see ScrollView.tsx's own doc comment on this same
+  // pattern for why runOnUI's deferred-to-next-frame behavior there leaves a real gap, and why a
+  // synchronous assignment is the correct fix rather than a workaround.
   useLayoutEffect(() => {
     const generation = listGeneration.value
+    if (Platform.OS === 'web') {
+      capturedGeneration.value = generation
+      return
+    }
     runOnUI((gen: number) => {
       'worklet'
       capturedGeneration.value = gen

package/src/internal/HorizontalDots.tsx

@@ -29,6 +29,11 @@ type DotProps = {
 }
 
 const Dot = ({ activeColor, index, inactiveColor, pageWidth, scrollPosition }: DotProps) => {
+  // Explicit array required on web even though nothing here looks platform-specific: without
+  // reanimated's Babel plugin active for the web bundle, useAnimatedStyle has no way to
+  // auto-extract dependencies and throws outright rather than silently under-tracking — omitting
+  // this array isn't a lesser version of the header/footer bug elsewhere in this package, it's a
+  // hard crash (confirmed live on the horizontal-pager demo).
   const circleStyle = useAnimatedStyle(() => {
     const page = scrollPosition.value / pageWidth
     const distance = Math.abs(index - page)
@@ -36,7 +41,7 @@ const Dot = ({ activeColor, index, inactiveColor, pageWidth, scrollPosition }: D
     const size = DOT_FULL + (DOT_SMALL - DOT_FULL) * t
     const backgroundColor = interpolateColor(t, [0, 1], [activeColor, inactiveColor])
     return { backgroundColor, borderRadius: size / 2, height: size, width: size }
-  })
+  }, [scrollPosition, pageWidth, index, activeColor, inactiveColor])
   return (
     <View style={styles.dotContainer}>
       <Animated.View style={circleStyle} />
@@ -56,16 +61,19 @@ export const HorizontalDots = ({ total }: Props) => {
   const activeColor = theme.colors.primary
   const inactiveColor = theme.colors.outlineVariant
 
-  const pillContainerStyle = useAnimatedStyle(() => ({
-    bottom: Math.max(footerHeightShared.value, insetsBottom) + 8
-  }))
+  const pillContainerStyle = useAnimatedStyle(
+    () => ({
+      bottom: Math.max(footerHeightShared.value, insetsBottom) + 8
+    }),
+    [footerHeightShared, insetsBottom]
+  )
 
   const rowStyle = useAnimatedStyle(() => {
     const page = scrollPosition.value / width
     const maxOffset = Math.max(0, (total - CLIP_COUNT) * DOT_STEP)
     const offset = Math.max(0, Math.min((page - (CLIP_COUNT - 1) / 2) * DOT_STEP, maxOffset))
     return { transform: [{ translateX: -offset }] }
-  })
+  }, [scrollPosition, width, total])
 
   return (
     <Animated.View pointerEvents='none' style={[styles.pillContainer, pillContainerStyle]}>

package/src/internal/useScrollList.ts

@@ -15,16 +15,17 @@ const CHIP_SLIDE = 48
 export type UseScrollListOptions = {
   footerFixed?: boolean
   headerFixed?: boolean
+  hideUntilMeasured?: boolean
   isHorizontal?: boolean
   keyboardAware?: boolean
   pullSearchHeight?: number
   style?: StyleProp<ViewStyle>
 }
 
-export function useScrollList({ footerFixed: footerFixedProp, headerFixed: headerFixedProp, isHorizontal, keyboardAware, pullSearchHeight, style }: UseScrollListOptions = {}) {
+export function useScrollList({ footerFixed: footerFixedProp, headerFixed: headerFixedProp, hideUntilMeasured, isHorizontal, keyboardAware, pullSearchHeight, style }: UseScrollListOptions = {}) {
   const insets = useSafeAreaInsets()
   const keyboardHeight = useKeyboardInset()
-  const { footerHeight, footerFixed: contextFooterFixed, headerHeight, headerFixed: contextHeaderFixed, headerOffset, pullSearchHeightShared, scrollPosition, snapBackHeaderShared } = useContext(ScrollViewContext)
+  const { footerAboveKeyboard, footerHeight, footerFixed: contextFooterFixed, headerHeight, headerFixed: contextHeaderFixed, headerOffset, pullSearchHeightShared, scrollPosition, snapBackHeaderShared, tabBarHeight } = useContext(ScrollViewContext)
 
   const headerFixed = isHorizontal ? true : (headerFixedProp ?? contextHeaderFixed)
   const footerFixed = isHorizontal ? true : (footerFixedProp ?? contextFooterFixed)
@@ -33,12 +34,36 @@ export function useScrollList({ footerFixed: footerFixedProp, headerFixed: heade
     pullSearchHeightShared.value = usesContentInset ? (pullSearchHeight ?? 0) : 0
   }, [pullSearchHeight, pullSearchHeightShared])
 
-  // 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])
+  // First render (headerHeight===null): flex:1, sitting naturally below the in-flow header —
+  // same visual position content ends up in after the swap below (absoluteFill + paddingTop
+  // matching the now-measured headerHeight), so no hiding is needed for this transition on its
+  // own. hideUntilMeasured is only for SectionList: its key={headerHeight>0?1:0} forces a real
+  // remount of the underlying native list on this exact transition, and that remount is what
+  // needs hiding, not this container swap itself — ScrollView/FlatList/CustomList never remount
+  // here, so unconditionally hiding this container regressed a real "flash of blank" on every
+  // fresh mount for them (2026-08-03).
+  const containerStyle = useMemo(() => (headerHeight === null ? [{ flex: 1, opacity: hideUntilMeasured ? 0 : 1 }, style] : [StyleSheet.absoluteFill, style]), [headerHeight, hideUntilMeasured, style])
 
-  const insetGeometry = useMemo(() => ({ bottom: (footerFixed ? footerHeight || insets.bottom : insets.bottom) + (keyboardAware ? keyboardHeight : 0), top: headerHeight ?? 0 }), [footerFixed, footerHeight, insets.bottom, headerHeight, keyboardAware, keyboardHeight])
+  // tabBarHeight reserves space for a consuming app's own persistent tab bar - a fixture outside
+  // this package's header/footer concepts entirely, so it's added on top of whichever base the
+  // footerFixed branch below resolves to (footerHeight already bakes in insets.bottom itself; see
+  // ScrollViewFooter's own paddingBottom).
+  //
+  // When footerAboveKeyboard opts the (fixed) footer into floating above the keyboard instead of
+  // sitting behind it, footerHeight ALREADY includes the current keyboardHeight — ScrollViewFooter
+  // grows its own container by keyboardHeight to float (see its containerPaddingBottom), rather
+  // than translating a fixed-height bar, so onLayout reports the combined height. Adding
+  // keyboardHeight again here would double-count it. Otherwise (not floating) ScrollViewFooter pins
+  // itself with plain `position: 'absolute', bottom: 0` with no keyboard-awareness of its own, so
+  // an open keyboard simply covers it rather than stacking above it - reserving
+  // footerReserve + keyboardHeight in that case would leave a gap the size of the now-hidden footer
+  // between the focused input and the keyboard, so max() reserves only whichever bottom obstruction
+  // is actually taller right now.
+  const insetGeometry = useMemo(() => {
+    const footerReserve = footerFixed ? footerHeight || insets.bottom : insets.bottom
+    const bottom = (!keyboardAware || (footerFixed && footerAboveKeyboard) ? footerReserve : Math.max(footerReserve, keyboardHeight)) + tabBarHeight
+    return { bottom, top: headerHeight ?? 0 }
+  }, [footerAboveKeyboard, footerFixed, footerHeight, insets.bottom, tabBarHeight, headerHeight, keyboardAware, keyboardHeight])
   // Outside inset mode the same geometry is applied as content padding instead; contentInset is
   // zeroed (not omitted) so consumers' offset math — scroll-to-top targets, minHeight — stays
   // correct in the raw 0-based coordinate space those platforms actually scroll in.
@@ -54,6 +79,10 @@ export function useScrollList({ footerFixed: footerFixedProp, headerFixed: heade
   const contentOffset = usesContentInset ? insetContentOffset : ZERO_OFFSET
 
   const chipHidden = useSharedValue(1)
+  // chipHidden/snapBackHeaderShared/headerOffset/scrollPosition/pullSearchHeightShared all need to
+  // be listed here too, not just read — see ScrollViewHeader's translateStyle for why (web-only
+  // reanimated reactivity gap: a SharedValue's mutations don't retrigger useAnimatedStyle unless
+  // the value itself is in this array).
   const chipStyle = useAnimatedStyle(() => {
     const pointerEvents = chipHidden.value ? ('none' as const) : ('box-none' as const)
     if (isHorizontal) {
@@ -73,7 +102,7 @@ export function useScrollList({ footerFixed: footerFixedProp, headerFixed: heade
       top,
       transform: [{ translateY: chipHidden.value ? withTiming(-CHIP_SLIDE) : withTiming(0) }]
     }
-  }, [isHorizontal, headerFixed, headerHeight, insets.top])
+  }, [isHorizontal, headerFixed, headerHeight, insets.top, chipHidden, snapBackHeaderShared, headerOffset, scrollPosition, pullSearchHeightShared])
 
   return { chipHidden, chipStyle, containerStyle, contentInset, contentOffset, contentPadding, footerFixed, headerFixed, headerHeight, insets, isHorizontal: isHorizontal ?? false }
 }

package/src/internal/useStickyHeaders.ts

@@ -62,11 +62,21 @@ export function useStickyHeaders(headerFixed: boolean, enabled: boolean): Sticky
     (curr, prev) => {
       if (curr !== prev) runOnJS(setActiveIndex)(curr)
     },
-    [enabled, headerFixed, insetsTop]
+    // Same web-only reanimated gap as useAnimatedStyle elsewhere in this file: this "prepare"
+    // function's own SharedValue reads (sectionYPositions, headerHeightShared, scrollPosition,
+    // snapBackHeaderShared, headerOffset, pullSearchHeightShared) need to be listed explicitly too
+    // — confirmed empirically that without them, useAnimatedReaction re-evaluates once on mount and
+    // then never again on web, permanently freezing activeIndex/the active sticky section.
+    [enabled, headerFixed, insetsTop, sectionYPositions, headerHeightShared, scrollPosition, snapBackHeaderShared, headerOffset, pullSearchHeightShared]
   )
 
   // Positions the clip container at stickyTop so overflow:hidden hides the outgoing
   // header as it slides above the sticky line during a push transition.
+  // Every SharedValue read below (headerHeightShared, scrollPosition, snapBackHeaderShared,
+  // headerOffset, pullSearchHeightShared, and for overlayStyle also contentIndexShared/
+  // sectionYPositions/sectionHeights) has to be listed in the array too — see
+  // ScrollViewHeader's translateStyle for why: on web, reanimated doesn't treat mutations to a
+  // SharedValue as a reactive trigger for useAnimatedStyle unless it's in this array.
   const clipStyle = useAnimatedStyle(() => {
     const hHeight = headerHeightShared.value
     const scrollPos = scrollPosition.value
@@ -80,7 +90,7 @@ export function useStickyHeaders(headerFixed: boolean, enabled: boolean): Sticky
       stickyTop = effective <= 0 ? hHeight : Math.max(insetsTop, hHeight - effective)
     }
     return { top: stickyTop }
-  }, [enabled, headerFixed, insetsTop])
+  }, [enabled, headerFixed, insetsTop, headerHeightShared, scrollPosition, snapBackHeaderShared, headerOffset, pullSearchHeightShared])
 
   // overlayStyle positions the header at top:0 relative to the clip container.
   // The push animation uses 1:1 speed with pushThreshold = stickyTop + currentHeight
@@ -118,7 +128,7 @@ export function useStickyHeaders(headerFixed: boolean, enabled: boolean): Sticky
     }
 
     return { opacity: 1, top: 0, transform: [{ translateY }] }
-  }, [enabled, headerFixed, insetsTop])
+  }, [enabled, headerFixed, insetsTop, contentIndexShared, sectionYPositions, headerHeightShared, scrollPosition, snapBackHeaderShared, headerOffset, pullSearchHeightShared, sectionHeights])
 
   // pageY is the view's window-coordinate Y from view.measure().
   // contentY = pageY + contentOffset.y, since screenY = contentY - contentOffset.y.

package/src/useScrollInit.ts

@@ -160,6 +160,7 @@ export function useScrollInit({ listHeaderComponent, onMomentumScrollEnd: extern
     return () => clearTimeout(fallback)
     // Intentionally runs once per mount only, using whatever remountTarget was captured at
     // construction — not a dep that should retrigger this effect.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [])
 
   // Transition to 'ready' once both measurements are available