@hanzogui/sheet 7.3.0 → 8.0.0

package/src/SheetScrollView.tsx

@@ -10,6 +10,13 @@ import { getGestureHandlerState, isGestureHandlerEnabled } from './gestureState'
 import { useSheetContext } from './SheetContext'
 import type { SheetScopedProps } from './types'
 import { useSheetScrollViewGestures } from './useSheetScrollViewGestures'
+import {
+  getStableLayoutViewportHeight,
+  getWebKeyboardBottomInset,
+  getWebKeyboardResizeHeight,
+  isEditableElement,
+  MIN_KEYBOARD_HEIGHT,
+} from './webViewport'
 
 const SHEET_SCROLL_VIEW_NAME = 'SheetScrollView'
 
@@ -29,28 +36,83 @@ export const SheetScrollView = React.forwardRef<
   ) => {
     const context = useSheetContext(SHEET_SCROLL_VIEW_NAME, __scopeSheet)
     const gestureContext = useGestureSheetContext()
-    const { scrollBridge, setHasScrollView } = context
+    const { scrollBridge, setHasScrollView, hasFit, screenSize } = context
+    const keyboardOccludedHeight = Math.max(0, context.keyboardOccludedHeight || 0)
+    // OR a LIVE DOM check: context.isKeyboardVisible (React state) lags the
+    // viewport resize, so on the open-transition render this component can re-run
+    // with the shrunk consumer maxHeight BEFORE the context flag flips. reading
+    // the keyboard height straight from visualViewport closes that race so the
+    // height freeze engages on the same render that would otherwise collapse it.
+    const isKeyboardVisible =
+      context.isKeyboardVisible === true ||
+      (isWeb && getWebKeyboardResizeHeight() >= MIN_KEYBOARD_HEIGHT)
     const [scrollEnabled] = useControllableState({
       prop: scrollEnabledProp,
       defaultProp: true,
     })
     const scrollRef = React.useRef<RNScrollView | null>(null)
 
+    const [hasScrollableContent, setHasScrollableContent] = useState(true)
+    const parentHeight = useRef(0)
+    const contentHeight = useRef(0)
+    // the sheet's authoritative pre-keyboard frame height (see SheetImpl). a
+    // scroll-view-local high-water mark used to live here, but it was unreliable
+    // (the ref could read 0 if the view remounted on focus / never laid out while
+    // closed), so the height now comes from the sheet, which doesn't remount.
+    const frozenFrameHeight = Math.max(0, context.keyboardStableFrameHeight || 0)
+
+    // with snapPointsMode="fit", Frame is content-sized (flex: 0, flex-basis: auto, height: undefined).
+    // a flex: 1 child can't grow inside a content-sized parent, so the ScrollView (and the Frame
+    // around it) collapse to 0 height. instead, let the ScrollView size to its content and cap it
+    // at the available viewport (screenSize / maxContentSize) so scrolling kicks in for tall content.
+    const fitSizingStyle = hasFit
+      ? {
+          flex: undefined as undefined,
+          height: undefined as undefined,
+          maxHeight: screenSize || undefined,
+        }
+      : { flex: 1 }
+    const contentContainerStyle = hasFit ? undefined : { minHeight: '100%' as const }
+
+    // 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
+        ? { height: frozenFrameHeight, maxHeight: frozenFrameHeight }
+        : null
+
     const panGestureRef = gestureContext?.panGestureRef
     const { ScrollView: RNGHScrollView } = getGestureHandlerState()
     const useRNGHScrollView = isGestureHandlerEnabled() && RNGHScrollView && panGestureRef
 
     // RNGH scroll locking state
     const currentScrollOffset = useRef(0)
+    const lastEmittedScrollOffset = useRef(0)
     const lockedScrollY = useRef(0)
+    const focusedInputScrollFrame = useRef(0)
 
     const setScrollEnabled = (next: boolean, lockTo?: number) => {
       if (!next) {
-        const lockY = lockTo ?? currentScrollOffset.current
+        const lockY = lockTo ?? scrollBridge.scrollLockY ?? currentScrollOffset.current
+        if (scrollBridge.enabled === false && scrollBridge.scrollLockY === lockY) {
+          return
+        }
+        scrollBridge.enabled = false
         lockedScrollY.current = lockY
         scrollBridge.scrollLockY = lockY
-        scrollRef.current?.scrollTo?.({ x: 0, y: lockY, animated: false })
+        if (currentScrollOffset.current !== lockY) {
+          scrollRef.current?.scrollTo?.({ x: 0, y: lockY, animated: false })
+          currentScrollOffset.current = lockY
+        }
       } else {
+        if (scrollBridge.enabled === true && scrollBridge.scrollLockY === undefined) {
+          return
+        }
+        scrollBridge.enabled = true
         lockedScrollY.current = currentScrollOffset.current
         scrollBridge.scrollLockY = undefined
       }
@@ -58,8 +120,97 @@ export const SheetScrollView = React.forwardRef<
 
     const forceScrollTo = (y: number) => {
       scrollRef.current?.scrollTo?.({ x: 0, y, animated: false })
+      currentScrollOffset.current = y
     }
 
+    const emitManualScroll = React.useCallback(
+      (node: HTMLElement, y: number) => {
+        currentScrollOffset.current = y
+        scrollBridge.y = y
+        if (y > 0) scrollBridge.scrollStartY = -1
+        lastEmittedScrollOffset.current = y
+        onScroll?.({
+          nativeEvent: {
+            contentOffset: {
+              x: node.scrollLeft,
+              y,
+            },
+            contentSize: {
+              height: node.scrollHeight,
+              width: node.scrollWidth,
+            },
+            layoutMeasurement: {
+              height: node.offsetHeight,
+              width: node.offsetWidth,
+            },
+          },
+          timeStamp: Date.now(),
+        } as any)
+      },
+      [onScroll, scrollBridge]
+    )
+
+    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()) {
@@ -73,16 +224,18 @@ export const SheetScrollView = React.forwardRef<
       }
     }, [])
 
-    const [hasScrollableContent, setHasScrollableContent] = useState(true)
-    const parentHeight = useRef(0)
-    const contentHeight = useRef(0)
-
     const updateScrollable = () => {
       if (parentHeight.current && contentHeight.current) {
         setHasScrollableContent(contentHeight.current > parentHeight.current)
       }
     }
 
+    // track the fit height for the scrollable-content check. the keyboard-freeze
+    // height is supplied by the sheet (frozenFrameHeight), not derived here.
+    const recordFitHeight = (height: number) => {
+      parentHeight.current = height
+    }
+
     useEffect(() => {
       scrollBridge.hasScrollableContent = hasScrollableContent
     }, [hasScrollableContent])
@@ -94,6 +247,7 @@ export const SheetScrollView = React.forwardRef<
       hasScrollableContent,
       scrollEnabled,
       setScrollEnabled,
+      onManualScroll: emitManualScroll,
     })
 
     // content wrapper for measuring height
@@ -104,10 +258,20 @@ export const SheetScrollView = React.forwardRef<
           if (height !== contentHeight.current) {
             contentHeight.current = height
             updateScrollable()
+            if (keyboardOccludedHeight > 0) {
+              scheduleFocusedInputScroll()
+            }
           }
         }}
       >
         {children}
+        {keyboardOccludedHeight > 0 && (
+          <View
+            data-sheet-keyboard-scroll-pad
+            height={keyboardOccludedHeight}
+            width="100%"
+          />
+        )}
       </View>
     )
 
@@ -117,12 +281,12 @@ export const SheetScrollView = React.forwardRef<
       return (
         <RNGHComponent
           ref={composeRefs(scrollRef as any, ref)}
-          style={{ flex: 1 }}
+          style={fitSizingStyle}
           scrollEventThrottle={1}
           scrollEnabled={scrollEnabled}
           simultaneousHandlers={[panGestureRef]}
           onLayout={(e: any) => {
-            parentHeight.current = Math.ceil(e.nativeEvent.layout.height)
+            recordFitHeight(Math.ceil(e.nativeEvent.layout.height))
             updateScrollable()
           }}
           onScroll={(e: any) => {
@@ -137,29 +301,35 @@ export const SheetScrollView = React.forwardRef<
                   animated: false,
                 })
               }
+              currentScrollOffset.current = scrollBridge.scrollLockY
               scrollBridge.y = scrollBridge.scrollLockY
-              onScroll?.({
-                ...e,
-                nativeEvent: {
-                  ...e.nativeEvent,
-                  contentOffset: {
-                    ...e.nativeEvent.contentOffset,
-                    y: scrollBridge.scrollLockY,
+              if (lastEmittedScrollOffset.current !== scrollBridge.scrollLockY) {
+                lastEmittedScrollOffset.current = scrollBridge.scrollLockY
+                onScroll?.({
+                  ...e,
+                  nativeEvent: {
+                    ...e.nativeEvent,
+                    contentOffset: {
+                      ...e.nativeEvent.contentOffset,
+                      y: scrollBridge.scrollLockY,
+                    },
                   },
-                },
-              })
+                })
+              }
               return
             }
 
             scrollBridge.y = y
             if (y > 0) scrollBridge.scrollStartY = -1
+            lastEmittedScrollOffset.current = y
             onScroll?.(e)
           }}
-          contentContainerStyle={{ minHeight: '100%' }}
+          contentContainerStyle={contentContainerStyle}
           bounces={false}
           keyboardShouldPersistTaps="always"
           keyboardDismissMode="none"
           {...props}
+          {...keyboardFrozenOverride}
         >
           {contentWrapper}
         </RNGHComponent>
@@ -170,23 +340,26 @@ export const SheetScrollView = React.forwardRef<
     return (
       <ScrollView
         onLayout={(e) => {
-          parentHeight.current = Math.ceil(e.nativeEvent.layout.height)
+          recordFitHeight(Math.ceil(e.nativeEvent.layout.height))
           updateScrollable()
         }}
         ref={composeRefs(scrollRef as any, ref)}
-        flex={1}
+        {...fitSizingStyle}
         scrollEventThrottle={1}
         className="_ovs-contain"
         scrollEnabled={scrollEnabled}
         onScroll={(e) => {
           const { y } = e.nativeEvent.contentOffset
+          currentScrollOffset.current = y
           scrollBridge.y = y
           if (y > 0) scrollBridge.scrollStartY = -1
+          lastEmittedScrollOffset.current = y
           onScroll?.(e)
         }}
-        contentContainerStyle={{ minHeight: '100%' }}
+        contentContainerStyle={contentContainerStyle}
         {...gestureProps}
         {...props}
+        {...keyboardFrozenOverride}
       >
         {contentWrapper}
       </ScrollView>

package/src/createSheet.tsx

@@ -1,5 +1,5 @@
 import { useComposedRefs } from '@hanzogui/compose-refs'
-import { useIsomorphicLayoutEffect } from '@hanzogui/constants'
+import { isWeb, useIsomorphicLayoutEffect } from '@hanzogui/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
@@ -107,6 +108,7 @@ export function createSheet<
         // @ts-ignore
         <Overlay
           {...props}
+          ref={ref}
           onPress={composeEventHandlers(
             props.onPress,
             context.dismissOnOverlayPress
@@ -117,7 +119,7 @@ export function createSheet<
           )}
         />
       )
-    }, [props.onPress, props.opacity, context.dismissOnOverlayPress])
+    }, [props, ref, context.dismissOnOverlayPress, context.setOpen])
 
     useIsomorphicLayoutEffect(() => {
       context.onOverlayComponent?.(element)
@@ -136,9 +138,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 +227,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/gestureState.ts

@@ -7,16 +7,36 @@ import { getGestureHandler, type GestureState } from '@hanzogui/native'
 
 export type { GestureState as GestureHandlerState } from '@hanzogui/native'
 
+const SHEET_GESTURE_STATE_KEY = '__hanzogui_sheet_gesture_state__'
+
+function getSheetGestureHandlerState(): GestureState {
+  const g = globalThis as typeof globalThis & {
+    [SHEET_GESTURE_STATE_KEY]?: GestureState
+  }
+
+  return g[SHEET_GESTURE_STATE_KEY] ?? getGestureHandler().state
+}
+
 // backward compat helpers
 export function isGestureHandlerEnabled(): boolean {
-  return getGestureHandler().isEnabled
+  return getSheetGestureHandlerState().enabled
 }
 
 export function getGestureHandlerState(): GestureState {
-  return getGestureHandler().state
+  return getSheetGestureHandlerState()
 }
 
 export function setGestureHandlerState(updates: Partial<GestureState>): void {
+  const g = globalThis as typeof globalThis & {
+    [SHEET_GESTURE_STATE_KEY]?: GestureState
+  }
+
+  const sheetState = g[SHEET_GESTURE_STATE_KEY]
+  if (sheetState) {
+    Object.assign(sheetState, updates)
+    return
+  }
+
   getGestureHandler().set(updates)
 }
 

package/src/index.ts

@@ -9,3 +9,7 @@ export * from './SheetScrollView'
 export * from './nativeSheet'
 export * from './types'
 export * from './contexts'
+export {
+  getGestureHandlerState as unstable_getSheetGestureHandlerState,
+  isGestureHandlerEnabled as unstable_isSheetGestureHandlerEnabled,
+} from './gestureState'

package/src/keyboardAvoidance.ts

@@ -0,0 +1,121 @@
+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,
+  keyboardHeight,
+  screenSize,
+  sheetY,
+}: {
+  frameSize: number
+  isKeyboardVisible: boolean
+  keyboardHeight: number
+  screenSize: number
+  sheetY: number | undefined
+}) {
+  if (
+    !isKeyboardVisible ||
+    keyboardHeight <= 0 ||
+    screenSize <= 0 ||
+    frameSize <= 0 ||
+    sheetY === undefined ||
+    sheetY >= screenSize
+  ) {
+    return 0
+  }
+
+  const keyboardTop = screenSize - keyboardHeight
+  const sheetBottom = sheetY + frameSize
+  const occludedHeight = Math.ceil(sheetBottom - keyboardTop)
+
+  return Math.min(frameSize, Math.max(0, occludedHeight))
+}

package/src/nativeSheet.tsx

@@ -59,7 +59,14 @@ export function setupNativeSheet(
 
       return (
         <>
-          <SheetProvider setHasScrollView={emptyFn} {...providerProps} onlyShowFrame>
+          <SheetProvider
+            setHasScrollView={emptyFn}
+            keyboardOccludedHeight={0}
+            isKeyboardVisible={false}
+            keyboardStableFrameHeight={0}
+            {...providerProps}
+            onlyShowFrame
+          >
             <ModalSheetView ref={ref} onModalDidDismiss={() => setOpenInternal(false)}>
               <ModalSheetViewMainContent>
                 <View style={{ flex: 1 }}>{props.children}</View>

package/src/setupGestureHandler.ts

@@ -4,8 +4,16 @@
 
 import { getGestureHandler } from '@hanzogui/native'
 
+import type { GestureState } from '@hanzogui/native'
+
+const SHEET_GESTURE_STATE_KEY = '__hanzogui_sheet_gesture_state__'
+
 export function isGestureHandlerEnabled(): boolean {
-  return getGestureHandler().isEnabled
+  const g = globalThis as typeof globalThis & {
+    [SHEET_GESTURE_STATE_KEY]?: GestureState
+  }
+
+  return g[SHEET_GESTURE_STATE_KEY]?.enabled ?? getGestureHandler().isEnabled
 }
 
 export interface SetupGestureHandlerConfig {
@@ -16,19 +24,20 @@ export interface SetupGestureHandlerConfig {
 
 export function setupGestureHandler(config: SetupGestureHandlerConfig): void {
   const g = globalThis as any
-  if (g.__gui_sheet_gesture_handler_setup) {
+  if (g.__hanzogui_sheet_gesture_handler_setup) {
     return
   }
-  g.__gui_sheet_gesture_handler_setup = true
+  g.__hanzogui_sheet_gesture_handler_setup = true
 
   const { Gesture, GestureDetector, ScrollView } = config
 
   if (Gesture && GestureDetector) {
-    getGestureHandler().set({
+    g[SHEET_GESTURE_STATE_KEY] = {
       enabled: true,
       Gesture,
       GestureDetector,
       ScrollView: ScrollView || null,
-    })
+      RootView: null,
+    } satisfies GestureState
   }
 }

package/src/types.tsx

@@ -60,6 +60,12 @@ export type SheetProps = ScopedProps<
      */
     unmountChildrenWhenHidden?: boolean
 
+    /**
+     * Keep the sheet content wrapper opaque while the sheet is hidden.
+     * Useful for native visual effects that cannot initialize below a transparent ancestor.
+     */
+    disableTransparencyHide?: boolean
+
     /**
      * Adapts the sheet to use native sheet on the given platform (if available)
      */
@@ -75,7 +81,8 @@ export type SheetProps = ScopedProps<
     zIndex?: number
     portalProps?: PortalProps
     /**
-     * Native-only flag that will make the sheet move up when the mobile keyboard opens so the focused input remains visible
+     * Makes the sheet move up when the mobile keyboard opens so the focused input remains visible.
+     * Works on native (via keyboard events) and on mobile web (via the VisualViewport API).
      */
     moveOnKeyboardChange?: boolean
     containerComponent?: React.ComponentType<any>
@@ -125,12 +132,24 @@ export type ScrollBridge = {
   _lastTouchY?: number
   // scroll lock position for forcing scroll back when pan handles
   scrollLockY?: number
+  // keep scroll locked while a drag that started below the top snap is still
+  // deciding whether to hand off into content scrolling.
+  lockScrollAtTop?: boolean
   // force scroll to position (compensates for async setNativeProps)
   forceScrollTo?: (y: number) => void
   // whether sheet is at top position (for scroll enable/disable)
   isAtTop?: boolean
   // snap sheet to a specific position (for handoff UP)
   snapToPosition?: (positionIndex: number) => void
+  // re-baseline the pan drag origin to the current animated position. the web
+  // scroll-view hook calls this on each transition into pan ownership so a
+  // scroll→pan handoff resumes from where the sheet is, not a stale origin.
+  startPanDrag?: () => void
+  // web only: true while a touch is active on the ScrollView node. The web
+  // scroll-view gesture hook owns drag detection for those touches (it calls
+  // drag/release on this bridge), so the PanResponder must NOT also grant for
+  // them — otherwise two systems drive the animated position and it jitters.
+  scrollNodeTouched?: boolean
 }
 
 // keyboard controller sheet types