@tamagui/sheet 2.1.0 → 2.2.0

package/src/SheetScrollView.tsx

@@ -10,7 +10,13 @@ import { getGestureHandlerState, isGestureHandlerEnabled } from './gestureState'
 import { useSheetContext } from './SheetContext'
 import type { SheetScopedProps } from './types'
 import { useSheetScrollViewGestures } from './useSheetScrollViewGestures'
-import { getWebKeyboardHeight, MIN_KEYBOARD_HEIGHT } from './webViewport'
+import {
+  getStableLayoutViewportHeight,
+  getWebKeyboardBottomInset,
+  getWebKeyboardResizeHeight,
+  isEditableElement,
+  MIN_KEYBOARD_HEIGHT,
+} from './webViewport'
 
 const SHEET_SCROLL_VIEW_NAME = 'SheetScrollView'
 
@@ -39,7 +45,7 @@ export const SheetScrollView = React.forwardRef<
     // height freeze engages on the same render that would otherwise collapse it.
     const isKeyboardVisible =
       context.isKeyboardVisible === true ||
-      (isWeb && getWebKeyboardHeight() >= MIN_KEYBOARD_HEIGHT)
+      (isWeb && getWebKeyboardResizeHeight() >= MIN_KEYBOARD_HEIGHT)
     const [scrollEnabled] = useControllableState({
       prop: scrollEnabledProp,
       defaultProp: true,
@@ -67,27 +73,15 @@ export const SheetScrollView = React.forwardRef<
         }
       : { flex: 1 }
 
-    // AUTOFOCUS-ON-OPEN seed (web): the sheet is still reconstructing its
-    // pre-keyboard frame baseline and needs THIS scroll view to size to its
-    // content so it can measure the true content height. so we apply the stable
-    // screen only as a maxHeight cap (UNCLIP from the shrunk consumer maxHeight)
-    // and leave height undefined so it stays content-sized.
-    const isKeyboardSeeding = context.isKeyboardSeeding === true
-
-    // when the keyboard is open the sheet stays ANCHORED at the bottom and keeps
-    // its full pre-keyboard height — the keyboard overlays its lower part and the
-    // keyboardOccludedHeight tail padding (added to the scroll content below) +
-    // browser scroll-into-view lift the focused input above the keyboard. so we
-    // pin the height to the sheet's authoritative frozenFrameHeight, overriding
-    // any consumer maxHeight (on web that's often tied to useWindowDimensions,
-    // which SHRINKS when the keyboard opens and would otherwise collapse the
-    // sheet). holding the height constant means nothing animates on keyboard
-    // open/close — no jump/teleport. applied AFTER {...props} so it wins.
+    // when the keyboard is open, pin the scroll view to the sheet's pre-keyboard
+    // frame height (frozenFrameHeight), overriding any consumer maxHeight. on web
+    // that maxHeight is often tied to useWindowDimensions, which SHRINKS when the
+    // keyboard opens and would otherwise collapse the sheet. holding the height
+    // constant means the web frame can translate without resizing. applied
+    // AFTER {...props} so it wins.
     const keyboardFrozenOverride =
       hasFit && isKeyboardVisible && frozenFrameHeight > 0
-        ? isKeyboardSeeding
-          ? { maxHeight: frozenFrameHeight }
-          : { height: frozenFrameHeight, maxHeight: frozenFrameHeight }
+        ? { height: frozenFrameHeight, maxHeight: frozenFrameHeight }
         : null
 
     const panGestureRef = gestureContext?.panGestureRef
@@ -97,6 +91,7 @@ export const SheetScrollView = React.forwardRef<
     // RNGH scroll locking state
     const currentScrollOffset = useRef(0)
     const lockedScrollY = useRef(0)
+    const focusedInputScrollFrame = useRef(0)
 
     const setScrollEnabled = (next: boolean, lockTo?: number) => {
       if (!next) {
@@ -114,6 +109,67 @@ export const SheetScrollView = React.forwardRef<
       scrollRef.current?.scrollTo?.({ x: 0, y, animated: false })
     }
 
+    const scrollFocusedInputClearOfKeyboard = React.useCallback(() => {
+      if (!isWeb || !hasFit || !isKeyboardVisible || keyboardOccludedHeight <= 0) {
+        return
+      }
+      const node = scrollRef.current?.getScrollableNode() as HTMLElement | undefined
+      const active = document.activeElement as HTMLElement | null
+      if (!node || !active || !isEditableElement(active) || !node.contains(active)) {
+        return
+      }
+
+      const keyboardHeight = Math.max(keyboardOccludedHeight, getWebKeyboardBottomInset())
+      if (keyboardHeight <= 0) return
+
+      const activeRect = active.getBoundingClientRect()
+      const nodeRect = node.getBoundingClientRect()
+      const margin = 12
+      const keyboardTop = getStableLayoutViewportHeight() - keyboardHeight
+      const visibleTop = nodeRect.top + margin
+      const visibleBottom = Math.min(nodeRect.bottom, keyboardTop) - margin
+      let nextScrollTop = node.scrollTop
+
+      if (activeRect.bottom > visibleBottom) {
+        nextScrollTop += Math.ceil(activeRect.bottom - visibleBottom)
+      } else if (activeRect.top < visibleTop) {
+        nextScrollTop -= Math.ceil(visibleTop - activeRect.top)
+      }
+
+      const maxScrollTop = Math.max(0, node.scrollHeight - node.clientHeight)
+      nextScrollTop = Math.max(0, Math.min(maxScrollTop, nextScrollTop))
+      if (nextScrollTop === node.scrollTop) return
+
+      node.scrollTop = nextScrollTop
+      currentScrollOffset.current = nextScrollTop
+      scrollBridge.y = nextScrollTop
+      if (nextScrollTop > 0) scrollBridge.scrollStartY = -1
+    }, [hasFit, isKeyboardVisible, keyboardOccludedHeight, scrollBridge])
+
+    const scheduleFocusedInputScroll = React.useCallback(() => {
+      if (!isWeb || !hasFit) return
+      cancelAnimationFrame(focusedInputScrollFrame.current)
+      focusedInputScrollFrame.current = requestAnimationFrame(() => {
+        scrollFocusedInputClearOfKeyboard()
+        focusedInputScrollFrame.current = requestAnimationFrame(
+          scrollFocusedInputClearOfKeyboard
+        )
+      })
+    }, [hasFit, scrollFocusedInputClearOfKeyboard])
+
+    useEffect(() => {
+      if (!isWeb || !hasFit) return
+      scheduleFocusedInputScroll()
+      window.addEventListener('focusin', scheduleFocusedInputScroll)
+      window.visualViewport?.addEventListener('resize', scheduleFocusedInputScroll)
+
+      return () => {
+        cancelAnimationFrame(focusedInputScrollFrame.current)
+        window.removeEventListener('focusin', scheduleFocusedInputScroll)
+        window.visualViewport?.removeEventListener('resize', scheduleFocusedInputScroll)
+      }
+    }, [hasFit, scheduleFocusedInputScroll])
+
     useEffect(() => {
       setHasScrollView(true)
       if (isGestureHandlerEnabled()) {
@@ -160,6 +216,9 @@ export const SheetScrollView = React.forwardRef<
           if (height !== contentHeight.current) {
             contentHeight.current = height
             updateScrollable()
+            if (keyboardOccludedHeight > 0) {
+              scheduleFocusedInputScroll()
+            }
           }
         }}
       >
@@ -244,6 +303,7 @@ export const SheetScrollView = React.forwardRef<
         scrollEnabled={scrollEnabled}
         onScroll={(e) => {
           const { y } = e.nativeEvent.contentOffset
+          currentScrollOffset.current = y
           scrollBridge.y = y
           if (y > 0) scrollBridge.scrollStartY = -1
           onScroll?.(e)

package/src/createSheet.tsx

@@ -1,5 +1,5 @@
 import { useComposedRefs } from '@tamagui/compose-refs'
-import { useIsomorphicLayoutEffect } from '@tamagui/constants'
+import { isWeb, useIsomorphicLayoutEffect } from '@tamagui/constants'
 import type {
   GetProps,
   ViewProps,
@@ -25,6 +25,7 @@ import { SheetScrollView } from './SheetScrollView'
 import type { SheetProps, SheetScopedProps } from './types'
 import { useSheetController } from './useSheetController'
 import { useSheetOffscreenSize } from './useSheetOffscreenSize'
+import { getMaxViewportHeight } from './webViewport'
 
 type SharedSheetProps = {
   open?: boolean
@@ -136,9 +137,9 @@ export function createSheet<
 
   type ExtraFrameProps = {
     /**
-     * By default the sheet adds a view below its bottom that extends down another 50%,
-     * this is useful if your Sheet has a spring animation that bounces "past" the top when
-     * opening, preventing it from showing the content underneath.
+     * by default the sheet adds a view below its bottom that extends past the
+     * largest visible viewport height. this covers spring overshoot when opening
+     * so page content never shows through below the sheet.
      */
     disableHideBottomOverflow?: boolean
 
@@ -225,14 +226,25 @@ export function createSheet<
             <Frame
               {...props}
               componentName="SheetCover"
+              data-sheet-cover=""
               children={null}
               // Don't inherit testID - this is a visual helper element
               testID={undefined}
               id={undefined}
               position="absolute"
-              bottom="-100%"
+              // anchor the cover's top at the sheet's bottom edge (top: 100% of the
+              // container), then extend it downward. on web extend it past the
+              // largest viewport safari can reveal as its chrome retracts, so the
+              // sheet background covers the bottom instead of revealing the page.
+              // native keeps frameSize.
+              top="100%"
               zIndex={-1}
-              height={context.frameSize}
+              height={
+                isWeb
+                  ? Math.max(context.frameSize, getMaxViewportHeight())
+                  : context.frameSize
+              }
+              maxHeight={isWeb ? 'none' : undefined}
               left={0}
               right={0}
               borderWidth={0}

package/src/keyboardAvoidance.ts

@@ -1,3 +1,94 @@
+export function getKeyboardAdjustedSheetY({
+  sheetY,
+  screenSize,
+  isKeyboardVisible,
+  keyboardHeight,
+  shouldTranslate,
+  safeAreaTop,
+}: {
+  sheetY: number
+  screenSize: number
+  isKeyboardVisible: boolean
+  keyboardHeight: number
+  shouldTranslate: boolean
+  safeAreaTop: number
+}) {
+  if (
+    !shouldTranslate ||
+    !isKeyboardVisible ||
+    keyboardHeight <= 0 ||
+    screenSize <= 0 ||
+    sheetY >= screenSize
+  ) {
+    return sheetY
+  }
+
+  return Math.max(safeAreaTop, sheetY - keyboardHeight)
+}
+
+export function getSheetReleasePosition({
+  positions,
+  projectedEnd,
+  currentPosition,
+  frameSize,
+  dismissOnSnapToBottom,
+  snapPointsMode,
+  isKeyboardVisible,
+  isWeb,
+}: {
+  positions: number[]
+  projectedEnd: number
+  currentPosition: number
+  frameSize: number
+  dismissOnSnapToBottom: boolean
+  snapPointsMode: 'percent' | 'constant' | 'fit' | 'mixed'
+  isKeyboardVisible: boolean
+  isWeb: boolean
+}) {
+  let closestPoint = 0
+  let dist = Number.POSITIVE_INFINITY
+
+  for (let i = 0; i < positions.length; i++) {
+    const position = positions[i]
+    const curDist = Math.abs(projectedEnd - position)
+    if (curDist < dist) {
+      dist = curDist
+      closestPoint = i
+    }
+  }
+
+  // the keyboard-open dismiss threshold is a WEB keyboard-handoff fix
+  // (75de9c9694). on native the keyboard is opaque and the sheet snaps purely by
+  // projected position (the pre-rework behavior), so gate it to web only —
+  // otherwise a native fit+dismiss sheet snaps to the wrong point with the
+  // keyboard up.
+  const dismissPoint = positions.length - 1
+  const isKeyboardFitDismiss =
+    isWeb &&
+    dismissOnSnapToBottom &&
+    isKeyboardVisible &&
+    snapPointsMode === 'fit' &&
+    positions.length === 2 &&
+    closestPoint === dismissPoint
+
+  if (!isKeyboardFitDismiss) {
+    return closestPoint
+  }
+
+  const openPosition = positions[0]
+  const dismissPosition = positions[dismissPoint]
+  const dismissDistance = dismissPosition - openPosition
+  if (dismissDistance <= 0 || frameSize <= 0) {
+    return closestPoint
+  }
+
+  const draggedDistance = Math.max(0, currentPosition - openPosition)
+  const thresholdBase = Math.min(frameSize, dismissDistance)
+  const dismissThreshold = Math.max(120, thresholdBase * 0.35)
+
+  return draggedDistance >= dismissThreshold ? closestPoint : 0
+}
+
 export function getKeyboardOccludedHeight({
   frameSize,
   isKeyboardVisible,

package/src/nativeSheet.tsx

@@ -64,7 +64,6 @@ export function setupNativeSheet(
             keyboardOccludedHeight={0}
             isKeyboardVisible={false}
             keyboardStableFrameHeight={0}
-            isKeyboardSeeding={false}
             {...providerProps}
             onlyShowFrame
           >

package/src/useGestureHandlerPan.tsx

@@ -1,6 +1,8 @@
+import { isWeb } from '@tamagui/constants'
 import { useCallback, useMemo, useRef, type RefObject } from 'react'
 import { getGestureHandlerState, isGestureHandlerEnabled } from './gestureState'
-import type { ScrollBridge } from './types'
+import { getSheetReleasePosition } from './keyboardAvoidance'
+import type { ScrollBridge, SnapPointsMode } from './types'
 
 // threshold in pixels for considering sheet "at top" position
 // allows for small measurement variations
@@ -18,6 +20,9 @@ interface GesturePanConfig {
   resisted: (val: number, minY: number) => number
   disableDrag?: boolean
   isShowingInnerSheet?: boolean
+  dismissOnSnapToBottom?: boolean
+  snapPointsMode?: SnapPointsMode
+  isKeyboardVisible?: boolean
   // set the animated position directly (for smooth dragging)
   setAnimatedPosition: (val: number) => void
   // ref to scroll gesture for simultaneousWithExternalGesture
@@ -69,6 +74,16 @@ export function useGestureHandlerPan(config: GesturePanConfig): GesturePanResult
 
   const gestureHandlerEnabled = isGestureHandlerEnabled()
   const panGestureRef = useRef<any>(null)
+  const releaseConfigRef = useRef({
+    dismissOnSnapToBottom: config.dismissOnSnapToBottom === true,
+    snapPointsMode: config.snapPointsMode ?? 'percent',
+    isKeyboardVisible: config.isKeyboardVisible === true,
+  })
+  releaseConfigRef.current = {
+    dismissOnSnapToBottom: config.dismissOnSnapToBottom === true,
+    snapPointsMode: config.snapPointsMode ?? 'percent',
+    isKeyboardVisible: config.isKeyboardVisible === true,
+  }
 
   // use refs for values that need to persist across gesture lifecycle
   // (useMemo closure variables get reset when gesture is recreated)
@@ -86,6 +101,7 @@ export function useGestureHandlerPan(config: GesturePanConfig): GesturePanResult
     // causing positions to revert. Frozen positions ensure stable snap calculation.
     frozenPositions: [] as number[],
     frozenMinY: 0,
+    frozenIsKeyboardVisible: false,
     // whether pan gesture actually started (vs just a tap in onBegin)
     panStarted: false,
   })
@@ -156,6 +172,7 @@ export function useGestureHandlerPan(config: GesturePanConfig): GesturePanResult
         // doesn't change snap targets mid-gesture
         gs.frozenPositions = [...positions]
         gs.frozenMinY = minY
+        gs.frozenIsKeyboardVisible = releaseConfigRef.current.isKeyboardVisible
 
         // if sheet not at top, DISABLE SCROLL immediately and lock to 0
         // this prevents scroll from firing before pan takes over
@@ -292,17 +309,17 @@ export function useGestureHandlerPan(config: GesturePanConfig): GesturePanResult
         const velocity = velocityY / 1000
         const projectedEnd = currentPos + frameSize * velocity * 0.2
 
-        let closestPoint = 0
-        let minDist = Number.POSITIVE_INFINITY
-
-        for (let i = 0; i < snapPositions.length; i++) {
-          const pos = snapPositions[i]
-          const dist = Math.abs(projectedEnd - pos)
-          if (dist < minDist) {
-            minDist = dist
-            closestPoint = i
-          }
-        }
+        const releaseConfig = releaseConfigRef.current
+        const closestPoint = getSheetReleasePosition({
+          positions: snapPositions,
+          projectedEnd,
+          currentPosition: currentPos,
+          frameSize,
+          dismissOnSnapToBottom: releaseConfig.dismissOnSnapToBottom,
+          snapPointsMode: releaseConfig.snapPointsMode,
+          isKeyboardVisible: gs.frozenIsKeyboardVisible,
+          isWeb,
+        })
 
         onEnd(closestPoint)
       })

package/src/useKeyboardControllerSheet.ts

@@ -2,11 +2,11 @@
  * Web implementation of the keyboard controller sheet hook.
  *
  * Mobile browsers don't expose a keyboard API, but they do resize the
- * VisualViewport when the soft keyboard opens. We derive the keyboard height as
- * `getStableLayoutViewportHeight() - visualViewport.height` (see webViewport —
- * the stable baseline is document.documentElement.clientHeight, NOT innerHeight,
- * which itself shrinks with the keyboard on real iOS Safari) and feed it into the
- * keyboardOccludedHeight scroll padding in SheetImplementationCustom.
+ * VisualViewport when the soft keyboard opens. We use the viewport shrink
+ * (`clientHeight - visualViewport.height`) to detect the keyboard, then feed the
+ * bottom layout inset (`clientHeight - (offsetTop + height)`) into
+ * SheetImplementationCustom. The bottom inset accounts for iOS Safari panning
+ * the visual viewport during focus, so the sheet doesn't over-lift.
  *
  * Without this, a bottom sheet on mobile web stays pinned behind the keyboard:
  * react-native-web's Dimensions tracks the (shrinking) VisualViewport, so any
@@ -21,7 +21,8 @@ import type {
   KeyboardControllerSheetResult,
 } from './types'
 import {
-  getWebKeyboardHeight,
+  getWebKeyboardBottomInset,
+  getWebKeyboardResizeHeight,
   isEditableElement,
   MIN_KEYBOARD_HEIGHT,
 } from './webViewport'
@@ -31,8 +32,26 @@ export function useKeyboardControllerSheet(
 ): KeyboardControllerSheetResult {
   const { enabled } = options
 
-  const [keyboardHeight, setKeyboardHeight] = useState(0)
-  const [isKeyboardVisible, setIsKeyboardVisible] = useState(false)
+  // initialize from the CURRENT viewport, not blindly from 0/false. when the
+  // sheet opens with the soft keyboard already up (e.g. it was raised by a field
+  // on the page behind, or by an autofocus whose keyboard wins the race against
+  // the first layout), a false initial value makes the sheet's very first render
+  // believe the keyboard is down — it captures a keyboard-free baseline from a
+  // keyboard-shrunk layout and the anchor/seed machinery has to recover. reading
+  // the viewport synchronously here removes that first-render race: the sheet
+  // knows the keyboard is up on render 1 and takes the seed path deterministically.
+  const [keyboardHeight, setKeyboardHeight] = useState(() =>
+    isWeb && enabled && typeof window !== 'undefined' && window.visualViewport
+      ? (() => {
+          const resizeHeight = getWebKeyboardResizeHeight()
+          return resizeHeight >= MIN_KEYBOARD_HEIGHT &&
+            isEditableElement(document.activeElement)
+            ? getWebKeyboardBottomInset()
+            : 0
+        })()
+      : 0
+  )
+  const [isKeyboardVisible, setIsKeyboardVisible] = useState(() => keyboardHeight > 0)
 
   // action-sheet pattern: pause keyboard hide events during drag so the sheet
   // position doesn't revert mid-gesture when a TextInput blurs.
@@ -66,8 +85,9 @@ export function useKeyboardControllerSheet(
     if (!vv) return
 
     const update = () => {
-      const height = getWebKeyboardHeight()
-      const tall = height >= MIN_KEYBOARD_HEIGHT
+      const resizeHeight = getWebKeyboardResizeHeight()
+      const height = getWebKeyboardBottomInset()
+      const tall = resizeHeight >= MIN_KEYBOARD_HEIGHT
       // require an editable element focused to *show* — this rules out URL-bar
       // collapse and other viewport changes that aren't a keyboard. but stay
       // visible while the viewport remains shrunk even if focus momentarily
@@ -93,11 +113,11 @@ export function useKeyboardControllerSheet(
       setKeyboardHeight((prev) => (prev === height ? prev : height))
     }
 
-    // only react to resize (keyboard height changes). we intentionally do NOT
-    // listen to visualViewport 'scroll' — that fires continuously while the
-    // sheet content scrolls and would re-derive the keyboard height from a
-    // shifting viewport, making the sheet jump.
+    // resize tracks keyboard open/close. scroll tracks iOS Safari's focus pan:
+    // visualViewport.offsetTop can change after the height has settled, and the
+    // sheet cap must move in that same layout coordinate space.
     vv.addEventListener('resize', update)
+    vv.addEventListener('scroll', update)
     // focus changes flip editable state without necessarily resizing the viewport
     window.addEventListener('focusin', update)
     window.addEventListener('focusout', update)
@@ -106,6 +126,7 @@ export function useKeyboardControllerSheet(
 
     return () => {
       vv.removeEventListener('resize', update)
+      vv.removeEventListener('scroll', update)
       window.removeEventListener('focusin', update)
       window.removeEventListener('focusout', update)
     }

package/src/useSafeAreaInsets.native.ts

@@ -0,0 +1,29 @@
+import * as React from 'react'
+import { SafeAreaInsetsContext as RNSafeAreaInsetsContext } from 'react-native-safe-area-context'
+
+import type { SafeAreaInsets } from './useSafeAreaInsets'
+
+// the real react-native-safe-area-context insets context, re-typed to the local
+// shape so consumers don't depend on the package's types. exported so the Sheet
+// can re-propagate it across the portal.
+export const SafeAreaInsetsContext =
+  RNSafeAreaInsetsContext as unknown as React.Context<SafeAreaInsets | null>
+
+/**
+ * Live safe-area insets (notch / status bar / home indicator) read from the
+ * context the app's SafeAreaProvider provides.
+ *
+ * Read this in a component BODY that renders inside the provider. The Sheet does
+ * exactly that — only its modal CONTENT is teleported out through the portal, so
+ * the body still sees the real insets. This is the one read that works in real
+ * native bundles:
+ *  - `getSafeArea()` (the @tamagui/native abstraction) is frequently NOT enabled
+ *    against the instance a component reads, so it returns 0.
+ *  - a dynamic `require('react-native-safe-area-context')` throws "Unknown named
+ *    module" in metro/rolldown bundles where the package isn't in the importing
+ *    module's graph.
+ * A static import + context read avoids both.
+ */
+export function useSafeAreaInsets(): SafeAreaInsets | null {
+  return React.useContext(SafeAreaInsetsContext)
+}

package/src/useSafeAreaInsets.ts

@@ -0,0 +1,19 @@
+import * as React from 'react'
+
+export interface SafeAreaInsets {
+  top: number
+  right: number
+  bottom: number
+  left: number
+}
+
+// web uses CSS env(safe-area-inset-*) for safe areas, so there is no native
+// safe-area context to read here — the keyboard-avoidance path uses the visual
+// viewport offset instead. this stub keeps the import resolvable on web (where
+// react-native-safe-area-context isn't a dependency) and is the canonical type
+// source for both platform variants.
+export const SafeAreaInsetsContext = React.createContext<SafeAreaInsets | null>(null)
+
+export function useSafeAreaInsets(): SafeAreaInsets | null {
+  return null
+}

package/src/useSheetProviderProps.tsx

@@ -14,17 +14,11 @@ export type SheetContextValue = ReturnType<typeof useSheetProviderProps> & {
   // the fit-mode height freeze must persist for the whole time the keyboard is
   // open, not just while occluded, or it releases and the sheet collapses.
   isKeyboardVisible: boolean
-  // the sheet's authoritative pre-keyboard frame height (web). SheetScrollView
-  // pins its height to this while the keyboard is open so the frame stays its
-  // full size (anchored to the screen bottom) instead of collapsing to a
-  // consumer maxHeight that shrank with the viewport. 0 when not applicable.
+  // the sheet's pre-keyboard frame height (web). SheetScrollView pins its height
+  // to this while the keyboard is open so the frame translates at full size
+  // instead of collapsing to a consumer maxHeight that shrank with the viewport.
+  // 0 when not applicable.
   keyboardStableFrameHeight: number
-  // AUTOFOCUS-ON-OPEN seed phase (web). while reconstructing the pre-keyboard
-  // baseline, SheetScrollView must UNCLIP (apply keyboardStableFrameHeight as
-  // maxHeight only, not a fixed height) so it sizes to its content and the sheet
-  // can measure the true content height. once settled the fixed-height pin
-  // applies. false outside the seed window.
-  isKeyboardSeeding: boolean
   setHasScrollView: (val: boolean) => void
 }
 

package/src/useSheetScrollViewGestures.native.ts

@@ -131,6 +131,10 @@ export function useSheetScrollViewGestures({
     } else {
       panHandles = !hasScrollableContent
       if (!panHandles) {
+        s.handoffOccurred = false
+        s.handoffDragOffset = 0
+        s.scrollEngaged = currentScrollY > 0
+        s.prevScrollY = currentScrollY
         s.isScrolling = true
         scrollBridge.scrollLock = true
         setScrollEnabled(true)

package/src/useSheetScrollViewGestures.ts

@@ -8,6 +8,7 @@ interface GestureState {
   startY: number
   lastY: number
   owner: GestureOwner
+  hadPanOwner: boolean
   panDragOffset: number
   dys: number[]
   scrollYAtGestureStart: number
@@ -30,6 +31,7 @@ export function useSheetScrollViewGestures({
     startY: 0,
     lastY: 0,
     owner: 'none',
+    hadPanOwner: false,
     panDragOffset: 0,
     dys: [],
     scrollYAtGestureStart: 0,
@@ -69,6 +71,7 @@ export function useSheetScrollViewGestures({
         startY: touch.pageY,
         lastY: touch.pageY,
         owner: 'none',
+        hadPanOwner: false,
         panDragOffset: 0,
         dys: [],
         scrollYAtGestureStart: currentScrollY,
@@ -117,6 +120,7 @@ export function useSheetScrollViewGestures({
       // handle transitions
       if (newOwner !== s.owner) {
         if (newOwner === 'pan') {
+          s.hadPanOwner = true
           s.panDragOffset = 0
           s.dys = []
           // re-baseline the pan origin to the sheet's CURRENT position so the
@@ -128,7 +132,11 @@ export function useSheetScrollViewGestures({
         } else {
           scrollBridge.setParentDragging(false)
           scrollBridge.scrollLock = false
-          enableScroll()
+          if (s.hadPanOwner) {
+            disableScroll()
+          } else {
+            enableScroll()
+          }
         }
         s.owner = newOwner
       }
@@ -141,19 +149,21 @@ export function useSheetScrollViewGestures({
 
         s.dys.push(dy)
         if (s.dys.length > 100) s.dys = s.dys.slice(-10)
-      } else if (s.owner === 'scroll' && !e.isTrusted) {
-        // SYNTHETIC events only (tests): dispatched TouchEvents don't trigger the
-        // browser's native overflow scroll, so we move scrollTop ourselves. for a
-        // REAL touch (e.isTrusted) the browser already scrolls the overflow
-        // container natively — doing it again here double-applies the delta and
-        // makes scrollTop jitter / snap around. so for real touches we let native
-        // scrolling own it and only track the offset via the ScrollView onScroll.
+      } else if (s.owner === 'scroll' && (!e.isTrusted || s.hadPanOwner)) {
+        // synthetic events don't trigger native overflow scroll, so tests need us
+        // to move scrollTop directly. real mixed gestures need the same direct
+        // path after pan ownership: ios safari may not resume native scrolling
+        // mid-touch after an earlier prevented touchmove. pure real scrolls still
+        // use native scrolling; mixed pan↔scroll gestures keep overflow hidden
+        // and are driven here until touchend.
+        if (e.cancelable) e.preventDefault()
         const scrollDelta = -dy
         const maxScrollY = node.scrollHeight - node.clientHeight
         const newScrollY = Math.max(0, Math.min(maxScrollY, currentScrollY + scrollDelta))
         if (newScrollY !== currentScrollY) {
           node.scrollTop = newScrollY
           scrollBridge.y = newScrollY
+          if (newScrollY > 0) scrollBridge.scrollStartY = -1
         }
       }
     }
@@ -183,6 +193,7 @@ export function useSheetScrollViewGestures({
 
       enableScroll()
       s.owner = 'none'
+      s.hadPanOwner = false
       s.panDragOffset = 0
       s.dys = []
       scrollBridge.scrollNodeTouched = false