@rific/scroll-view 0.8.3 → 0.9.1

package/src/ScrollViewProvider.tsx

@@ -1,13 +1,20 @@
 import { useBlur } from '@rific/auto-paper'
-import { type ReactNode, useCallback, useContext, useEffect, useMemo, useRef, useState } from 'react'
+import { type ReactNode, useCallback, useContext, useEffect, useLayoutEffect, useMemo, useRef, useState } from 'react'
 import { Dimensions, Platform } from 'react-native'
 import { useSharedValue } from 'react-native-reanimated'
 
+import { CHROME_SLACK } from './internal/chrome'
+import { ChromeRegistrar } from './internal/ChromeRegistrar'
+import { ScrollViewChromeHostContext } from './ScrollViewChromeContext'
 import { ScrollViewContext } from './ScrollViewContext'
 import { ScrollViewSettingsContext } from './ScrollViewSettingsContext'
 
 export type ScrollViewProviderProps = {
   blur?: boolean
+  // Opt out of an enclosing ScrollViewChromeProvider. A screen inside a hosted navigator joins the
+  // host by default; a nested provider that is NOT a screen (a picker or form modal - Paper's Portal
+  // can re-parent those above the clearing this provider does for its own children) has to say so.
+  chrome?: boolean
   children: ReactNode
   fixed?: boolean
   footerAboveKeyboard?: boolean
@@ -19,8 +26,14 @@ export type ScrollViewProviderProps = {
   tabBarHeight?: number
 }
 
-export const ScrollViewProvider = ({ blur, children, fixed = false, footerAboveKeyboard = false, footerFixed, headerFixed, snapBack, snapBackFooter, snapBackHeader, tabBarHeight = 0 }: ScrollViewProviderProps) => {
+export const ScrollViewProvider = ({ blur, chrome, children, fixed = false, footerAboveKeyboard = false, footerFixed, headerFixed, snapBack, snapBackFooter, snapBackHeader, tabBarHeight = 0 }: ScrollViewProviderProps) => {
   const { settings } = useContext(ScrollViewSettingsContext)
+  const enclosingHost = useContext(ScrollViewChromeHostContext)
+  const chromeHost = chrome === false ? null : enclosingHost
+  const chromeHosted = chromeHost !== null
+  const chromeFootprint = chromeHost?.footprint ?? 0
+  const chromeOverhang = chromeHost?.overhang ?? 0
+  const chromeSnapBack = chromeHost?.snapBack ?? false
   const effectiveBlur = useBlur(blur)
   const effectiveSnapBack = snapBack ?? settings.snapBack
   const effectiveSnapBackHeader = snapBackHeader ?? settings.snapBackHeader
@@ -35,30 +48,76 @@ export const ScrollViewProvider = ({ blur, children, fixed = false, footerAboveK
   const headerHeightShared = useSharedValue(0)
   const footerHeightShared = useSharedValue(0)
   const headerOffset = useSharedValue(0)
-  const footerOffset = useSharedValue(0)
+  const ownFooterOffset = useSharedValue(0)
+  const ownStackHeight = useSharedValue(0)
+  // A hosted provider writes the host's ONE offset instead of its own, so the persistent bar and this
+  // screen's footer read literally the same SharedValue. Starts unwritable when hosted: the
+  // registrar flips it once this screen actually owns the host, so a mounted-but-unfocused screen
+  // (Tabs and Stacks keep visited screens mounted) can never fight the focused one for it.
+  const footerOffset = chromeHost ? chromeHost.offset : ownFooterOffset
+  const chromeWritable = useSharedValue(!chromeHosted)
+  // Only the registrar ever writes this while hosted. If a provider stops being hosted while it stays
+  // mounted (chrome flipping to false, the host unmounting), the registrar goes away with it and
+  // would leave the last value behind - possibly false, which would silently switch off this
+  // provider's own snap-back footer for good.
+  useEffect(() => {
+    if (!chromeHosted) chromeWritable.value = true
+  }, [chromeHosted, chromeWritable])
+  const revealChrome = chromeHost?.reveal
+  // Unhosted, the hide distance is simply the footer's own height - the SAME SharedValue, not a
+  // copy, so nothing about existing snap-back behavior changes. Hosted, the whole stack (screen
+  // footer + bar + whatever pokes above the bar) has to clear the screen, and the footer's own
+  // measured height already includes the overhang as its bottom padding.
+  const stackHeightShared = chromeHosted ? ownStackHeight : footerHeightShared
   const pullSearchHeightShared = useSharedValue(0)
   const snapBackHeaderShared = useSharedValue(false)
   const snapBackFooterShared = useSharedValue(false)
   useEffect(() => {
     snapBackHeaderShared.value = effectiveSnapBackHeader ?? effectiveSnapBack
-    snapBackFooterShared.value = effectiveSnapBackFooter ?? effectiveSnapBack
-  }, [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
-    },
-    [headerHeight, headerHeightShared]
-  )
+    // Forced on for a hosted footer only: a bar that hides on scroll must be revealable from
+    // anywhere in a list, which the non-snap footer (visible only near the top) is not. The header's
+    // own snap-back is deliberately left to its own setting.
+    snapBackFooterShared.value = chromeHosted ? chromeSnapBack : (effectiveSnapBackFooter ?? effectiveSnapBack)
+  }, [chromeHosted, chromeSnapBack, effectiveSnapBack, effectiveSnapBackFooter, effectiveSnapBackHeader, snapBackFooterShared, snapBackHeaderShared])
+  useEffect(() => {
+    if (!chromeHosted) return
+    ownStackHeight.value = chromeFootprint + Math.max(footerHeight ?? 0, chromeOverhang) + CHROME_SLACK
+  }, [chromeFootprint, chromeHosted, chromeOverhang, footerHeight, ownStackHeight])
+  // The last height each setter below accepted, written synchronously on every call. The 0-guards
+  // read these rather than the rendered headerHeight/footerHeight, because a caller can hold a
+  // setter from before the previous call committed: on web the header's first onLayout and the
+  // fallback below routinely land ~2ms apart in the same frame, and the fallback's closure still
+  // saw headerHeight === null, so its 0 passed the guard and overwrote the real height. The header's
+  // size never changed after that, so onLayout never fired again and the list kept 0 top padding
+  // under the header for good.
+  const headerHeightRef = useRef<number | null>(null)
+  const footerHeightRef = useRef<number | null>(null)
+  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 && headerHeightRef.current) return
+    headerHeightRef.current = h
+    setHeaderHeightState(h)
+  }, [])
+  // Mirrored into the SharedValue in the same commit as the state, never ahead of it. Writing it
+  // straight from onLayout let the header's translate worklet see the new height while the list
+  // still had no top padding and scrollPosition hadn't been moved to its resting -headerHeight
+  // (useScrollInit does that in its own layout effect on this commit) - so for the whole re-render
+  // (~50ms on web) the header computed translateY = -headerHeight and slid off-screen, a visible
+  // flash of a header-less screen with the list's first rows at the very top.
+  useLayoutEffect(() => {
+    headerHeightShared.value = headerHeight ?? 0
+  }, [headerHeight, headerHeightShared])
   const onListUnmount = useCallback(() => {
     listGeneration.value += 1
-  }, [listGeneration])
+    // The owning screen's list going away is the last scroll source for the shared offset: a screen
+    // that swaps its list for non-scrolling content (a spinner, an empty state) while the stack is
+    // hidden would otherwise keep the app's primary navigation hidden with nothing left to bring it back.
+    if (revealChrome && chromeWritable.value) revealChrome()
+  }, [chromeWritable, listGeneration, revealChrome])
   const onJsListUnmount = useCallback(() => {
     jsListGeneration.current += 1
   }, [])
@@ -66,14 +125,14 @@ export const ScrollViewProvider = ({ blur, children, fixed = false, footerAboveK
     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.')
+      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])
   // Web-only recovery for a real race: a header's ResizeObserver-backed onLayout can simply never
-  // fire on the very first mount through Expo Router (observed in practice, not just theorized —
+  // fire on the very first mount through Expo Router (observed in practice, not just theorized -
   // content stuck at opacity: 0 indefinitely, with no error, only escaping via an unrelated resize
-  // forcing a fresh layout pass). Native RN doesn't have this race — onLayout is reliable there, and
+  // forcing a fresh layout pass). Native RN doesn't have this race - onLayout is reliable there, and
   // a persistently-null headerHeight really does mean "no header was ever rendered," which the
   // warning above should keep flagging. On web, give a real first layout two frames to arrive before
   // assuming there isn't one; setHeaderHeight(0) is exactly what a genuinely header-less screen would
@@ -95,17 +154,31 @@ export const ScrollViewProvider = ({ blur, children, fixed = false, footerAboveK
       // shim (and a footer's own unmount cleanup below, which now passes null instead of 0 for
       // exactly this reason) can report/force a spurious 0 while a real footer is effectively
       // still on screen (e.g. a wizard cycling through several <ScrollViewFooter> instances).
-      // Never let that clobber a known height — only an explicit null (genuinely no footer
+      // Never let that clobber a known height - only an explicit null (genuinely no footer
       // mounted) may reset it.
-      if (h === 0 && footerHeight) return
+      if (h === 0 && footerHeightRef.current) return
+      footerHeightRef.current = h
       setFooterHeightState(h)
       footerHeightShared.value = h ?? 0
     },
-    [footerHeight, footerHeightShared]
+    [footerHeightShared]
   )
   const scrollHeight = useMemo(() => Dimensions.get('window').height - (headerHeight ?? 0) - (footerHeight ?? 0), [headerHeight, footerHeight])
   const effectiveHeaderFixed = fixed || (headerFixed ?? settings.headerFixed)
   const effectiveFooterFixed = fixed || (footerFixed ?? settings.footerFixed)
-  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>
+  // Hosted, the persistent bar's footprint replaces the consumer's static tabBarHeight guess: it is
+  // the same "reserve this much at the bottom" number, just now known exactly.
+  const effectiveTabBarHeight = chromeHosted ? chromeFootprint : tabBarHeight
+  const value = useMemo(
+    () => ({ blur: effectiveBlur, chromeHosted, chromeOverhang, chromeWritable, 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, stackHeightShared, tabBarHeight: effectiveTabBarHeight }),
+    [effectiveBlur, chromeHosted, chromeOverhang, chromeWritable, footerAboveKeyboard, effectiveFooterFixed, effectiveHeaderFixed, footerHeight, footerHeightShared, footerOffset, headerHeight, headerHeightShared, headerOffset, jsListGeneration, listGeneration, onJsListUnmount, onListUnmount, progress, pullSearchHeightShared, progressing, scrollHeight, scrollPosition, setFooterHeight, setHeaderHeight, snapBackFooterShared, snapBackHeaderShared, stackHeightShared, effectiveTabBarHeight]
+  )
+  return (
+    <ScrollViewContext.Provider value={value}>
+      <ScrollViewChromeHostContext.Provider value={null}>
+        {children}
+        {chromeHost ? <ChromeRegistrar footerFixed={effectiveFooterFixed} host={chromeHost} writable={chromeWritable} /> : null}
+      </ScrollViewChromeHostContext.Provider>
+    </ScrollViewContext.Provider>
+  )
 }

package/src/SectionList.tsx

@@ -36,13 +36,13 @@ const SectionListInner = <ItemT, SectionT extends { data: ReadonlyArray<ItemT> }
 
   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
+  // -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
+  // 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
@@ -52,7 +52,7 @@ const SectionListInner = <ItemT, SectionT extends { data: ReadonlyArray<ItemT> }
   // 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
+  // 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(() => {
@@ -71,7 +71,7 @@ const SectionListInner = <ItemT, SectionT extends { data: ReadonlyArray<ItemT> }
   const { activeIndex, clipStyle, measureHeader, overlayStyle, resetPositions } = useStickyHeaders(headerFixed, usesCustomSticky)
 
   // useLayoutEffect (not useEffect) so the reset runs before native layout fires onLayout
-  // for the newly mounted section headers — otherwise the reset would clear correct positions.
+  // for the newly mounted section headers - otherwise the reset would clear correct positions.
   useLayoutEffect(() => {
     if (usesCustomSticky) resetPositions(sections.length)
   }, [sections, usesCustomSticky, resetPositions, headerHeight])

package/src/index.ts

@@ -8,6 +8,8 @@ export { PullSearch } from './PullSearch'
 export { scrollViewActions, scrollViewReducer } from './redux/scrollViewSlice'
 export type { ScrollViewProps } from './ScrollView'
 export { ScrollView } from './ScrollView'
+export type { ScrollViewChromeProviderProps } from './ScrollViewChromeProvider'
+export { ScrollViewChromeProvider } from './ScrollViewChromeProvider'
 export type { ScrollViewContextType } from './ScrollViewContext'
 export { ScrollViewContext } from './ScrollViewContext'
 export type { ScrollViewFooterProps } from './ScrollViewFooter'
@@ -24,4 +26,5 @@ export type { SectionListProps } from './SectionList'
 export { SectionList } from './SectionList'
 export { useKeyboardInset } from './useKeyboardInset'
 export { useScrollView } from './useScrollView'
+export { useScrollViewChromePin, useScrollViewChromeReveal, useScrollViewChromeStyle } from './useScrollViewChrome'
 export { useScrollViewSettings } from './useScrollViewSettings'

package/src/internal/ChromeRegistrar.tsx

@@ -0,0 +1,37 @@
+import { useEffect, useId } from 'react'
+import type { SharedValue } from 'react-native-reanimated'
+
+import type { ScrollViewChromeHost } from '../ScrollViewChromeContext'
+
+type ChromeRegistrarProps = {
+  footerFixed: boolean
+  host: ScrollViewChromeHost
+  writable: SharedValue<boolean>
+}
+
+// Rendered by a hosted ScrollViewProvider as a sibling of its children. It is a component rather
+// than a hook call inside the provider because host.useIsActive is itself a hook, and a provider
+// only sometimes has a host - mounting this only when hosted keeps the hook order stable.
+//
+// While its screen is active it claims the host; the provider's scroll handlers only write the
+// shared offset (`writable`) while this provider is the claim's owner and nothing has pinned the
+// bar. Footer Lock turning on while the stack is hidden reveals it, since the handlers stop writing
+// the moment it does and nothing else would ever bring it back.
+export const ChromeRegistrar = ({ footerFixed, host, writable }: ChromeRegistrarProps) => {
+  const id = useId()
+  const active = host.useIsActive()
+  const { activeId, claim, pinned, release, reveal } = host
+  useEffect(() => {
+    if (!active) return undefined
+    claim(id)
+    return () => release(id)
+  }, [active, claim, id, release])
+  const owner = activeId === id
+  useEffect(() => {
+    writable.value = owner && !pinned
+  }, [owner, pinned, writable])
+  useEffect(() => {
+    if (owner && footerFixed) reveal()
+  }, [footerFixed, owner, reveal])
+  return null
+}

package/src/internal/HorizontalDots.tsx

@@ -31,7 +31,7 @@ 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
+  // 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(() => {

package/src/internal/ScrollViewChip.tsx

@@ -4,11 +4,11 @@ import { StyleSheet, type ViewStyle } from 'react-native'
 import { Icon, useTheme } from 'react-native-paper'
 import Animated, { type AnimatedStyle } from 'react-native-reanimated'
 
-// 'children' omitted alongside the rest — this chip's own text always comes from `label` (or the
+// 'children' omitted alongside the rest - this chip's own text always comes from `label` (or the
 // isHorizontal-driven 'Start'/'Top' default below), passed as the real JSX children the underlying
 // Chip renders with, which is what actually wins: React always takes the children an element is
 // given between its tags over one merely passed as a "children" prop via spread. A `children` in
-// chipProps would therefore type-check but silently do nothing at runtime — omitting it here means
+// chipProps would therefore type-check but silently do nothing at runtime - omitting it here means
 // TypeScript catches that mismatch instead of a caller finding out the hard way.
 export type ChipProps = Omit<AutoPaperChipProps, 'compact' | 'icon' | 'onPress' | 'children'> & {
   label?: ReactNode
@@ -34,7 +34,7 @@ export const ScrollViewChip = ({ chipProps, isHorizontal, onChipPress, onPress,
   // Rendered via `avatar`, not Chip's own `icon` prop: react-native-paper's MD3 Chip hardcodes
   // `icon`'s color to theme.colors.primary and ignores `selectedColor` entirely (its own doc
   // comment: "With theme version 3 selectedColor doesn't apply to the icon. If you want [a]
-  // custom color for the icon, render your own Icon component") — a chip whose own background
+  // custom color for the icon, render your own Icon component") - a chip whose own background
   // IS theme.colors.primary (this library's callers all set that; see Hangman's own vivid-chip
   // convention) renders that icon invisible against itself. `avatar` has no such override; it
   // clones whatever element/color it's given. Falls back to the same default Paper itself would

package/src/internal/chrome.ts

@@ -0,0 +1,19 @@
+import { usesContentInset } from './insetMode'
+
+// Extra distance past the geometrically-required hide distance, so a soft shadow (a FAB's) that
+// bleeds past the bar's box doesn't leave a sliver at the screen edge once fully hidden.
+export const CHROME_SLACK = 2
+
+// How far a list can actually be scrolled from its resting position. In inset mode the resting
+// position sits at -headerHeight and raw contentOffset spans [-headerHeight, maxScroll]; in padding
+// mode the header is part of the content and raw spans [0, maxScroll].
+export const chromeTravel = (maxScroll: number, headerHeight: number) => {
+  'worklet'
+  return usesContentInset ? maxScroll + headerHeight : maxScroll
+}
+
+// Where a half-hidden stack should come to rest once scrolling stops: whichever end is nearer.
+export const chromeSettleTarget = (offset: number, stackHeight: number) => {
+  'worklet'
+  return offset > stackHeight / 2 ? stackHeight : 0
+}

package/src/internal/useScrollHandler.ts

@@ -4,6 +4,7 @@ import { runOnJS, useAnimatedScrollHandler, useSharedValue, withTiming } from 'r
 
 import { ScrollViewContext } from '../ScrollViewContext'
 import { REMOUNT_SYNC_TOLERANCE } from '../useScrollInit'
+import { chromeSettleTarget, chromeTravel } from './chrome'
 import { usesContentInset } from './insetMode'
 
 type UseScrollHandlerOptions = {
@@ -20,7 +21,7 @@ type 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 { chromeHosted, chromeWritable, footerOffset, headerHeightShared, headerOffset, pullSearchHeightShared, scrollPosition, snapBackFooterShared, snapBackHeaderShared, stackHeightShared } = useContext(ScrollViewContext)
   const snapUpAccum = useSharedValue(0)
   const fromBottomBounce = useSharedValue(false)
 
@@ -58,7 +59,12 @@ export function useScrollHandler({ capturedGeneration, chipHidden, chipThreshold
           fromBottomBounce.value = false
         }
         const snapHeader = snapBackHeaderShared.value && !headerFixed
-        const snapFooter = snapBackFooterShared.value && !footerFixed
+        // A hosted footer is one half of a stack that has to slide its full hide distance to clear
+        // the screen; a list that can't scroll that far (short content) would strand the stack half
+        // hidden with no way to finish the job, so it never starts hiding in the first place.
+        const hideable = !chromeHosted || chromeTravel(maxScroll, headerHeightShared.value) >= stackHeightShared.value
+        if (chromeHosted && !hideable && chromeWritable.value && footerOffset.value !== 0) footerOffset.value = 0
+        const snapFooter = snapBackFooterShared.value && !footerFixed && chromeWritable.value && hideable
         if (snapHeader || snapFooter) {
           if (yn <= -headerHeightShared.value) {
             snapUpAccum.value = 0
@@ -68,7 +74,7 @@ export function useScrollHandler({ capturedGeneration, chipHidden, chipThreshold
             snapUpAccum.value = 0
             if (yn >= -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))
+              if (snapFooter) footerOffset.value = Math.max(0, Math.min(stackHeightShared.value, footerOffset.value + delta))
             }
           } else if (delta < 0 && !fromBottomBounce.value) {
             if (yn >= -headerHeightShared.value + pullSearchHeightShared.value) snapUpAccum.value -= delta
@@ -85,20 +91,35 @@ export function useScrollHandler({ capturedGeneration, chipHidden, chipThreshold
         fromBottomBounce.value = false
         snapUpAccum.value = 0
       },
-      onEndDrag: ({ contentOffset: { y }, contentSize: { height: contentHeight }, layoutMeasurement: { height: layoutHeight } }) => {
+      onEndDrag: ({ contentOffset: { y }, contentSize: { height: contentHeight }, layoutMeasurement: { height: layoutHeight }, velocity }) => {
         'worklet'
         if (isHorizontal) return
+        // The 10pt scroll-up latch (snapUpAccum >= 10) has already started animating the footer offset
+        // back to 0; read it before anything below resets it, because settling on the in-flight value
+        // instead could pick "hidden" and reverse a deliberate reveal.
+        const revealing = snapUpAccum.value >= 10
         if (y >= contentHeight - layoutHeight - 10) {
           fromBottomBounce.value = true
           snapUpAccum.value = 0
         }
+        // A drag that released with momentum still to come keeps writing the offset through it, and
+        // settles when that ends; only a release that will genuinely stop here settles now.
+        if (chromeHosted && !footerFixed && chromeWritable.value && (velocity === undefined || Math.abs(velocity.y) < 0.1)) {
+          footerOffset.value = withTiming(revealing ? 0 : chromeSettleTarget(footerOffset.value, stackHeightShared.value), { duration: 200 })
+        }
       },
       onMomentumEnd: () => {
         'worklet'
+        const revealing = snapUpAccum.value >= 10
         fromBottomBounce.value = false
         snapUpAccum.value = 0
+        // Hosted: scroll tracks 1:1, so it can stop with the stack half hidden. The bar is the app's
+        // primary navigation, so it comes to rest fully shown or fully hidden, never cut off.
+        if (chromeHosted && !isHorizontal && !footerFixed && chromeWritable.value) {
+          footerOffset.value = withTiming(revealing ? 0 : chromeSettleTarget(footerOffset.value, stackHeightShared.value), { duration: 200 })
+        }
       }
     },
-    [capturedGeneration, headerFixed, footerFixed, isHorizontal, chipThreshold, listGeneration, onRemountSyncRetry, onRemountSynced, remountSyncTarget]
+    [capturedGeneration, chromeHosted, headerFixed, footerFixed, isHorizontal, chipThreshold, listGeneration, onRemountSyncRetry, onRemountSynced, remountSyncTarget]
   )
 }

package/src/internal/useScrollHandlerJS.ts

@@ -4,6 +4,7 @@ import type { SharedValue } from 'react-native-reanimated'
 import { withTiming } from 'react-native-reanimated'
 
 import { ScrollViewContext } from '../ScrollViewContext'
+import { chromeSettleTarget, chromeTravel } from './chrome'
 import { usesContentInset } from './insetMode'
 
 const REMOUNT_RETRY_TOLERANCE = 1
@@ -32,17 +33,17 @@ export type ScrollHandlerJS = {
 // 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
+// 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 { chromeHosted, chromeWritable, footerOffset, headerHeightShared, headerOffset, pullSearchHeightShared, scrollPosition, snapBackFooterShared, snapBackHeaderShared, stackHeightShared } = 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
+  // 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
+  // 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)
@@ -88,7 +89,11 @@ export function useScrollHandlerJS({ capturedGeneration, chipHidden, chipThresho
         fromBottomBounce.current = false
       }
       const snapHeader = snapBackHeaderShared.value && !headerFixed
-      const snapFooter = snapBackFooterShared.value && !footerFixed
+      // See useScrollHandler: a hosted stack that this list can't scroll far enough to fully hide
+      // never starts hiding.
+      const hideable = !chromeHosted || chromeTravel(maxScroll, headerHeightShared.value) >= stackHeightShared.value
+      if (chromeHosted && !hideable && chromeWritable.value && footerOffset.value !== 0) footerOffset.value = 0
+      const snapFooter = snapBackFooterShared.value && !footerFixed && chromeWritable.value && hideable
       if (snapHeader || snapFooter) {
         if (yn <= -headerHeightShared.value) {
           snapUpAccum.current = 0
@@ -98,7 +103,7 @@ export function useScrollHandlerJS({ capturedGeneration, chipHidden, chipThresho
           snapUpAccum.current = 0
           if (yn >= -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))
+            if (snapFooter) footerOffset.value = Math.max(0, Math.min(stackHeightShared.value, footerOffset.value + delta))
           }
         } else if (delta < 0 && !fromBottomBounce.current) {
           if (yn >= -headerHeightShared.value + pullSearchHeightShared.value) snapUpAccum.current -= delta
@@ -110,7 +115,7 @@ export function useScrollHandlerJS({ capturedGeneration, chipHidden, chipThresho
         }
       }
     },
-    [capturedGeneration, chipHidden, chipThreshold, footerFixed, footerHeightShared, footerOffset, headerFixed, headerHeightShared, headerOffset, isHorizontal, jsListGeneration, pullSearchHeightShared, scrollPosition, scrollTo, snapBackFooterShared, snapBackHeaderShared]
+    [capturedGeneration, chipHidden, chipThreshold, chromeHosted, chromeWritable, footerFixed, footerOffset, headerFixed, headerHeightShared, headerOffset, isHorizontal, jsListGeneration, pullSearchHeightShared, scrollPosition, scrollTo, snapBackFooterShared, snapBackHeaderShared, stackHeightShared]
   )
 
   const onScrollBeginDrag = useCallback(() => {
@@ -120,26 +125,45 @@ export function useScrollHandlerJS({ capturedGeneration, chipHidden, chipThresho
 
   const onMomentumScrollBegin = useCallback(() => {}, [])
 
+  // Hosted: scroll tracks 1:1, so it can stop with the stack half hidden; it settles to fully shown
+  // or fully hidden instead, since the bar is the app's primary navigation. `revealing` is whether
+  // the 10pt scroll-up latch has already started animating the offset back to 0 - settling on the
+  // in-flight value instead could pick "hidden" and reverse a deliberate reveal.
+  const settle = useCallback(
+    (revealing: boolean) => {
+      if (!chromeHosted || footerFixed || !chromeWritable.value) return
+      footerOffset.value = withTiming(revealing ? 0 : chromeSettleTarget(footerOffset.value, stackHeightShared.value), { duration: 200 })
+    },
+    [chromeHosted, chromeWritable, footerFixed, footerOffset, stackHeightShared]
+  )
+
   const onScrollEndDrag = useCallback(
     (event: NativeSyntheticEvent<NativeScrollEvent>) => {
       if (isHorizontal) return
       const {
         contentOffset: { y },
         contentSize: { height: contentHeight },
-        layoutMeasurement: { height: layoutHeight }
+        layoutMeasurement: { height: layoutHeight },
+        velocity
       } = event.nativeEvent
+      const revealing = snapUpAccum.current >= 10
       if (y >= contentHeight - layoutHeight - 10) {
         fromBottomBounce.current = true
         snapUpAccum.current = 0
       }
+      // A release with momentum still to come keeps writing the offset through it and settles when
+      // that ends; only one that will genuinely stop here settles now.
+      if (velocity === undefined || Math.abs(velocity.y) < 0.1) settle(revealing)
     },
-    [isHorizontal]
+    [isHorizontal, settle]
   )
 
   const onMomentumScrollEnd = useCallback(() => {
+    const revealing = snapUpAccum.current >= 10
     fromBottomBounce.current = false
     snapUpAccum.current = 0
-  }, [])
+    if (!isHorizontal) settle(revealing)
+  }, [isHorizontal, settle])
 
   return { onMomentumScrollBegin, onMomentumScrollEnd, onScroll, onScrollBeginDrag, onScrollEndDrag }
 }

package/src/internal/useScrollList.ts

@@ -25,21 +25,24 @@ export type UseScrollListOptions = {
 export function useScrollList({ footerFixed: footerFixedProp, headerFixed: headerFixedProp, hideUntilMeasured, isHorizontal, keyboardAware, pullSearchHeight, style }: UseScrollListOptions = {}) {
   const insets = useSafeAreaInsets()
   const keyboardHeight = useKeyboardInset()
-  const { footerAboveKeyboard, footerHeight, footerFixed: contextFooterFixed, headerHeight, headerHeightShared, headerFixed: contextHeaderFixed, headerOffset, pullSearchHeightShared, scrollPosition, snapBackHeaderShared, tabBarHeight } = useContext(ScrollViewContext)
+  const { chromeHosted, chromeOverhang, footerAboveKeyboard, footerHeight, footerFixed: contextFooterFixed, headerHeight, headerHeightShared, headerFixed: contextHeaderFixed, headerOffset, pullSearchHeightShared, scrollPosition, snapBackHeaderShared, tabBarHeight } = useContext(ScrollViewContext)
 
   const headerFixed = isHorizontal ? true : (headerFixedProp ?? contextHeaderFixed)
-  const footerFixed = isHorizontal ? true : (footerFixedProp ?? contextFooterFixed)
+  // Hosted, the footer and the bar share ONE offset that the provider's registrar reveals when Footer
+  // Lock turns on - and the registrar only sees the provider-level flag. A per-list override that
+  // turned the handlers off on its own would leave the stack stuck wherever it was hidden.
+  const footerFixed = isHorizontal ? true : chromeHosted ? contextFooterFixed : (footerFixedProp ?? contextFooterFixed)
 
   useEffect(() => {
     pullSearchHeightShared.value = usesContentInset ? (pullSearchHeight ?? 0) : 0
   }, [pullSearchHeight, pullSearchHeightShared])
 
-  // First render (headerHeight===null): flex:1, sitting naturally below the in-flow header —
+  // 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
+  // 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])
@@ -50,7 +53,7 @@ export function useScrollList({ footerFixed: footerFixedProp, headerFixed: heade
   // 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
+  // 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
@@ -59,13 +62,27 @@ export function useScrollList({ footerFixed: footerFixedProp, headerFixed: heade
   // 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.
+  //
+  // Hosted, tabBarHeight is the bar's footprint and it already contains the safe-area inset, so the
+  // base reserve is only what pokes above the bar (chromeOverhang) - not insets.bottom a second
+  // time. Hosted also reserves the screen footer's own height whether or not it is fixed: unlike an
+  // unhosted footer (whose position is a function of scroll, so scrolling to the end always hides
+  // it), a hosted stack settles wherever the last gesture left it, so a revealed footer at the end
+  // of a list would otherwise cover the last rows with no way to scroll them clear. This reserve
+  // stays constant even while the stack is hidden: contentInset can't animate, so the space stays
+  // reserved at the end of the list rather than the list growing as the bar slides away.
+  //
+  // A hosted, keyboard-floating footer pins itself at max(footprint - keyboardHeight, 0) instead of
+  // the full footprint (see ScrollViewFooter), so the bar reserve shrinks the same way.
   const insetGeometry = useMemo(() => {
-    const footerReserve = footerFixed ? footerHeight || insets.bottom : insets.bottom
-    const bottom = (!keyboardAware || (footerFixed && footerAboveKeyboard) ? footerReserve : Math.max(footerReserve, keyboardHeight)) + tabBarHeight
+    const baseReserve = chromeHosted ? chromeOverhang : insets.bottom
+    const footerReserve = chromeHosted ? Math.max(footerHeight ?? 0, baseReserve) : footerFixed ? footerHeight || baseReserve : baseReserve
+    const barReserve = chromeHosted && footerFixed && footerAboveKeyboard ? Math.max(tabBarHeight - keyboardHeight, 0) : tabBarHeight
+    const bottom = (!keyboardAware || (footerFixed && footerAboveKeyboard) ? footerReserve : Math.max(footerReserve, keyboardHeight)) + barReserve
     return { bottom, top: headerHeight ?? 0 }
-  }, [footerAboveKeyboard, footerFixed, footerHeight, insets.bottom, tabBarHeight, headerHeight, keyboardAware, keyboardHeight])
+  }, [chromeHosted, chromeOverhang, 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
+  // 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.
   const contentInset = usesContentInset ? insetGeometry : ZERO_INSET
   const contentPadding = useMemo(() => (usesContentInset || isHorizontal ? null : { paddingBottom: insetGeometry.bottom, paddingTop: insetGeometry.top }), [insetGeometry, isHorizontal])
@@ -73,19 +90,19 @@ export function useScrollList({ footerFixed: footerFixedProp, headerFixed: heade
   // 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.
+  // can position the FlatList at hideY atomically via contentOffset - no scrollTo needed.
   const [startedWithHeader] = useState(headerHeight !== null)
   const insetContentOffset = useMemo(() => ({ x: 0, y: headerHeight !== null ? -headerHeight + (startedWithHeader && !isHorizontal && pullSearchHeight ? pullSearchHeight : 0) : 0 }), [headerHeight, isHorizontal, pullSearchHeight, startedWithHeader])
   const contentOffset = usesContentInset ? insetContentOffset : ZERO_OFFSET
 
   const chipHidden = useSharedValue(1)
   // chipHidden/snapBackHeaderShared/headerOffset/scrollPosition/pullSearchHeightShared/
-  // headerHeightShared all need to be listed here too, not just read — see ScrollViewHeader's
+  // headerHeightShared 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). headerHeightShared is
   // used here rather than the plain `headerHeight` context value specifically because the latter
   // changes identity (null -> a real number) shortly after mount, which forces Reanimated to
-  // recreate this worklet — a crash on react-native-worklets 0.10.1, not just a perf concern. See
+  // recreate this worklet - a crash on react-native-worklets 0.10.1, not just a perf concern. See
   // ScrollViewHeader's translateStyle/blurStyle/progressStyle for the full explanation.
   const chipStyle = useAnimatedStyle(() => {
     const pointerEvents = chipHidden.value ? ('none' as const) : ('box-none' as const)