@tamagui/sheet 2.0.0-rc.9 → 2.1.0

package/src/SheetScrollView.tsx

@@ -10,6 +10,7 @@ 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'
 
 const SHEET_SCROLL_VIEW_NAME = 'SheetScrollView'
 
@@ -29,13 +30,66 @@ 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 && getWebKeyboardHeight() >= 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 }
+
+    // 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.
+    const keyboardFrozenOverride =
+      hasFit && isKeyboardVisible && frozenFrameHeight > 0
+        ? isKeyboardSeeding
+          ? { maxHeight: frozenFrameHeight }
+          : { height: frozenFrameHeight, maxHeight: frozenFrameHeight }
+        : null
+
     const panGestureRef = gestureContext?.panGestureRef
     const { ScrollView: RNGHScrollView } = getGestureHandlerState()
     const useRNGHScrollView = isGestureHandlerEnabled() && RNGHScrollView && panGestureRef
@@ -73,16 +127,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])
@@ -108,6 +164,13 @@ export const SheetScrollView = React.forwardRef<
         }}
       >
         {children}
+        {keyboardOccludedHeight > 0 && (
+          <View
+            data-sheet-keyboard-scroll-pad
+            height={keyboardOccludedHeight}
+            width="100%"
+          />
+        )}
       </View>
     )
 
@@ -117,12 +180,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) => {
@@ -160,6 +223,7 @@ export const SheetScrollView = React.forwardRef<
           keyboardShouldPersistTaps="always"
           keyboardDismissMode="none"
           {...props}
+          {...keyboardFrozenOverride}
         >
           {contentWrapper}
         </RNGHComponent>
@@ -170,11 +234,11 @@ 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}
@@ -187,6 +251,7 @@ export const SheetScrollView = React.forwardRef<
         contentContainerStyle={{ minHeight: '100%' }}
         {...gestureProps}
         {...props}
+        {...keyboardFrozenOverride}
       >
         {contentWrapper}
       </ScrollView>

package/src/keyboardAvoidance.ts

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

package/src/types.tsx

@@ -75,10 +75,16 @@ 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>
+
+    /**
+     * Called when the sheet open/close animation completes.
+     */
+    onAnimationComplete?: (info: { open: boolean }) => void
   },
   'Sheet'
 >
@@ -126,6 +132,15 @@ export type ScrollBridge = {
   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

package/src/useGestureHandlerPan.tsx

@@ -122,7 +122,6 @@ export function useGestureHandlerPan(config: GesturePanConfig): GesturePanResult
 
     // simultaneousHandlers pattern from react-native-actions-sheet
     // both gestures run simultaneously, we use blockPan to decide who handles
-    // console.warn('[RNGH-Pan] CREATING gesture, minY:', minY, 'frameSize:', frameSize)
     const gesture = Gesture.Pan()
       .withRef(panGestureRef)
       // NO manualActivation - let both gestures run via simultaneousHandlers
@@ -148,7 +147,6 @@ export function useGestureHandlerPan(config: GesturePanConfig): GesturePanResult
         const pos = getCurrentPosition()
         const atTop = pos <= minY + AT_TOP_THRESHOLD
         const currentScrollY = scrollBridge.y
-        // console.warn('[RNGH-Pan] onBegin', { pos, minY, atTop, currentScrollY })
         gs.startY = pos
         gs.lastPanTranslationY = 0
         gs.accumulatedOffset = 0
@@ -171,7 +169,6 @@ export function useGestureHandlerPan(config: GesturePanConfig): GesturePanResult
         gs.panStarted = true
         setIsDragging(true)
 
-        // console.warn('[RNGH-Pan] onStart', { startY: gs.startY, minY })
         scrollBridge.initialPosition = gs.startY
         onStart()
       })
@@ -195,8 +192,6 @@ export function useGestureHandlerPan(config: GesturePanConfig): GesturePanResult
         const isCurrentlyAtTop = currentPos <= minY + AT_TOP_THRESHOLD
         const nodeIsScrolling = scrollY > 0
 
-        // console.warn('[RNGH-Pan] onChange', { translationY: translationY.toFixed(1), deltaY: deltaY.toFixed(1), currentPos: currentPos.toFixed(1), minY, isCurrentlyAtTop, isSwipingDown, scrollY, scrollEngaged: gs.scrollEngaged })
-
         // decision matrix (from react-native-actions-sheet pattern)
         // each frame, decide who handles the movement based on current state
         //
@@ -229,7 +224,6 @@ export function useGestureHandlerPan(config: GesturePanConfig): GesturePanResult
             } else if (gs.scrollEngaged && hasScrollableContent) {
               // scroll WAS > 0 but now is 0 -> handoff from scroll to pan
               // pan takes over to drag sheet down
-              // console.warn('[RNGH-Pan] *** HANDOFF FROM SCROLL TO PAN ***')
               panHandles = true
             } else {
               // scroll never engaged OR content not scrollable, just drag sheet down
@@ -249,13 +243,13 @@ export function useGestureHandlerPan(config: GesturePanConfig): GesturePanResult
           }
         }
 
-        // console.warn('[RNGH-Pan] decision', { panHandles, isCurrentlyAtTop, isSwipingDown, nodeIsScrolling, scrollEngaged: gs.scrollEngaged, hasScrollableContent, currentPos: currentPos.toFixed(1), minY })
-
         if (panHandles) {
           // pan handles - disable scroll and move sheet
-          // when not at top: lock scroll to 0 (sheet is being dragged)
-          // when at top: lock at current position (handoff from scroll to pan)
-          const lockTo = isCurrentlyAtTop ? undefined : 0
+          // when swiping down at top after scroll was engaged: lock at current scroll position
+          //   (handoff from scroll to pan — preserve scroll offset)
+          // otherwise: always lock scroll to 0 (prevents scroll from firing during sheet drag)
+          const lockTo =
+            isCurrentlyAtTop && isSwipingDown && gs.scrollEngaged ? undefined : 0
           scrollBridge.setScrollEnabled?.(false, lockTo)
 
           // accumulate the delta for position calculation
@@ -276,8 +270,6 @@ export function useGestureHandlerPan(config: GesturePanConfig): GesturePanResult
         const { velocityY } = event
         const currentPos = gs.startY + gs.accumulatedOffset
 
-        // console.warn('[RNGH-Pan] onEnd', { velocityY, currentPos, accumulatedOffset: gs.accumulatedOffset, scrollY: scrollBridge.y })
-
         // clear scroll lock
         scrollBridge.scrollLockY = undefined
 
@@ -315,7 +307,6 @@ export function useGestureHandlerPan(config: GesturePanConfig): GesturePanResult
         onEnd(closestPoint)
       })
       .onFinalize(() => {
-        // console.warn('[RNGH-Pan] onFinalize', { panStarted: gs.panStarted })
         // clear scroll lock on finalize too (safety)
         scrollBridge.scrollLockY = undefined
         if (gs.panStarted) {
@@ -334,7 +325,6 @@ export function useGestureHandlerPan(config: GesturePanConfig): GesturePanResult
     // if we have a scroll gesture ref, make pan simultaneous with it
     // this allows both gestures to run and we decide in onChange who handles it
     if (scrollGestureRef?.current) {
-      // console.warn('[RNGH-Pan] adding simultaneousWithExternalGesture for scroll')
       return gesture.simultaneousWithExternalGesture(scrollGestureRef.current)
     }
 

package/src/useKeyboardControllerSheet.ts

@@ -1,26 +1,122 @@
 /**
- * Web stub for keyboard controller sheet hook.
- * Returns no-op values since keyboard-controller is native-only.
+ * 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.
+ *
+ * Without this, a bottom sheet on mobile web stays pinned behind the keyboard:
+ * react-native-web's Dimensions tracks the (shrinking) VisualViewport, so any
+ * content sized off window dimensions collapses while the sheet's bottom stays
+ * occluded. See SheetImplementationCustom's activePositions / keyboardOccludedHeight.
  */
 
-import { useRef } from 'react'
+import { useCallback, useEffect, useRef, useState } from 'react'
+import { isWeb } from '@tamagui/constants'
 import type {
   KeyboardControllerSheetOptions,
   KeyboardControllerSheetResult,
 } from './types'
-
-const noop = () => {}
+import {
+  getWebKeyboardHeight,
+  isEditableElement,
+  MIN_KEYBOARD_HEIGHT,
+} from './webViewport'
 
 export function useKeyboardControllerSheet(
-  _options: KeyboardControllerSheetOptions
+  options: KeyboardControllerSheetOptions
 ): KeyboardControllerSheetResult {
+  const { enabled } = options
+
+  const [keyboardHeight, setKeyboardHeight] = useState(0)
+  const [isKeyboardVisible, setIsKeyboardVisible] = useState(false)
+
+  // action-sheet pattern: pause keyboard hide events during drag so the sheet
+  // position doesn't revert mid-gesture when a TextInput blurs.
   const pauseKeyboardHandler = useRef(false)
+  const pendingHide = useRef(false)
+  // live mirror of isKeyboardVisible so the listener can read it without
+  // re-subscribing on every toggle.
+  const isVisibleRef = useRef(false)
+  isVisibleRef.current = isKeyboardVisible
+
+  const dismissKeyboard = useCallback(() => {
+    if (typeof document === 'undefined') return
+    const active = document.activeElement as HTMLElement | null
+    if (isEditableElement(active)) {
+      active?.blur?.()
+    }
+  }, [])
+
+  const flushPendingHide = useCallback(() => {
+    if (pendingHide.current) {
+      pendingHide.current = false
+      setIsKeyboardVisible(false)
+      setKeyboardHeight(0)
+    }
+  }, [])
+
+  useEffect(() => {
+    if (!isWeb || !enabled) return
+    if (typeof window === 'undefined') return
+    const vv = window.visualViewport
+    if (!vv) return
+
+    const update = () => {
+      const height = getWebKeyboardHeight()
+      const tall = height >= 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
+      // moves to a non-editable element (e.g. tapping between two inputs fires
+      // focusout→focusin), so the sheet doesn't flicker mid-transition.
+      const editableFocused = isEditableElement(document.activeElement)
+      const visible = tall && (editableFocused || isVisibleRef.current)
+
+      if (!visible) {
+        // suppress hide during an active drag so positions stay frozen; the
+        // drag-end flush reconciles the real state.
+        if (pauseKeyboardHandler.current && isVisibleRef.current) {
+          pendingHide.current = true
+          return
+        }
+        setIsKeyboardVisible(false)
+        setKeyboardHeight(0)
+        return
+      }
+
+      pendingHide.current = false
+      setIsKeyboardVisible(true)
+      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.
+    vv.addEventListener('resize', update)
+    // focus changes flip editable state without necessarily resizing the viewport
+    window.addEventListener('focusin', update)
+    window.addEventListener('focusout', update)
+
+    update()
+
+    return () => {
+      vv.removeEventListener('resize', update)
+      window.removeEventListener('focusin', update)
+      window.removeEventListener('focusout', update)
+    }
+  }, [enabled])
+
   return {
     keyboardControllerEnabled: false,
-    keyboardHeight: 0,
-    isKeyboardVisible: false,
-    dismissKeyboard: noop,
+    keyboardHeight,
+    isKeyboardVisible,
+    dismissKeyboard,
     pauseKeyboardHandler,
-    flushPendingHide: noop,
+    flushPendingHide,
   }
 }

package/src/useSheetController.tsx

@@ -22,6 +22,10 @@ export type SheetControllerContextValue = {
   // hide without "closing" to prevent re-animation when shown again
   hidden?: boolean
   onOpenChange?: React.Dispatch<React.SetStateAction<boolean>> | ((val: boolean) => void)
+  // fired by the sheet after its open/close animation finishes. used by
+  // Dialog adapt to know when it's safe to tear down adapted children
+  // without cutting off the slide-out mid-animation.
+  onAnimationComplete?: (state: { open: boolean }) => void
   // when true, the sheet should skip its open animation (used for adapt handoff)
   skipNextAnimation?: boolean
 }

package/src/useSheetProviderProps.tsx

@@ -8,6 +8,23 @@ import type { ScrollBridge, SheetProps } from './types'
 import type { SheetOpenState } from './useSheetOpenState'
 
 export type SheetContextValue = ReturnType<typeof useSheetProviderProps> & {
+  keyboardOccludedHeight: number
+  // whether the soft keyboard is currently open. distinct from
+  // keyboardOccludedHeight (which is 0 once the sheet fits above the keyboard):
+  // 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.
+  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.ts

@@ -75,6 +75,10 @@ export function useSheetScrollViewGestures({
       }
 
       scrollBridge.scrollStartY = touch.pageY
+      // claim this touch for the scroll-view gesture hook so the PanResponder
+      // (which also negotiates this touch via RNW's responder system) defers
+      // and doesn't double-drive the sheet position. cleared on touchend.
+      scrollBridge.scrollNodeTouched = true
     }
 
     const handleTouchMove = (e: TouchEvent) => {
@@ -115,6 +119,10 @@ export function useSheetScrollViewGestures({
         if (newOwner === 'pan') {
           s.panDragOffset = 0
           s.dys = []
+          // re-baseline the pan origin to the sheet's CURRENT position so the
+          // offset (reset to 0 here) maps to where it actually is — required for
+          // a correct scroll→pan handoff now that the PanResponder defers to us.
+          scrollBridge.startPanDrag?.()
           scrollBridge.setParentDragging(true)
           disableScroll()
         } else {
@@ -133,8 +141,13 @@ export function useSheetScrollViewGestures({
 
         s.dys.push(dy)
         if (s.dys.length > 100) s.dys = s.dys.slice(-10)
-      } else if (s.owner === 'scroll') {
-        // programmatic scroll for synthetic events
+      } 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.
         const scrollDelta = -dy
         const maxScrollY = node.scrollHeight - node.clientHeight
         const newScrollY = Math.max(0, Math.min(maxScrollY, currentScrollY + scrollDelta))
@@ -159,12 +172,20 @@ export function useSheetScrollViewGestures({
         }
 
         scrollBridge.release({ dragAt: s.panDragOffset, vy })
+      } else if (s.owner === 'scroll') {
+        // gesture ended while scrolling. a pan→scroll handoff only happens once
+        // the pane reached the top, so commit the top snap (index 0) and clear
+        // the dragging state HERE, on touchend — never mid-gesture (that would
+        // fight the live gesture). this replaces the PanResponder's release,
+        // which used to fire on touchend before it deferred to this hook.
+        scrollBridge.snapToPosition?.(0)
       }
 
       enableScroll()
       s.owner = 'none'
       s.panDragOffset = 0
       s.dys = []
+      scrollBridge.scrollNodeTouched = false
     }
 
     node.addEventListener('touchstart', handleTouchStart, {

package/src/webViewport.ts

@@ -0,0 +1,52 @@
+/**
+ * Web (mobile-browser) viewport helpers for the Sheet's keyboard handling.
+ *
+ * On real iOS Safari (verified on-device, iOS 26) the soft keyboard shrinks
+ * BOTH `window.visualViewport.height` AND `window.innerHeight` — neither is the
+ * stable layout viewport. Measured during a keyboard open: visualViewport
+ * 714 -> 404, innerHeight 714 -> 561 (it wobbles), but
+ * `document.documentElement.clientHeight` holds rock-steady at 714 the whole
+ * time (open, mid-keyboard, and close). So clientHeight IS the stable layout
+ * viewport, and we derive everything from it:
+ *   - soft-keyboard height = clientHeight - visualViewport.height (stays correct
+ *     even as innerHeight drifts), so the scroll padding clears the input.
+ *   - the sheet's fit-mode anchor cap (translateY = screenSize - frameSize) reads
+ *     clientHeight, so it never re-measures against a shrunk value and the frame
+ *     stays anchored at the bottom.
+ */
+
+// ignore small viewport changes (URL bar collapse, accessory bars) so they
+// don't read as a full keyboard. a real soft keyboard is well above this.
+export const MIN_KEYBOARD_HEIGHT = 80
+
+export function isEditableElement(el: Element | null): boolean {
+  if (!el) return false
+  const tag = el.tagName
+  if (tag === 'INPUT' || tag === 'TEXTAREA' || tag === 'SELECT') return true
+  if ((el as HTMLElement).isContentEditable) return true
+  return false
+}
+
+/**
+ * The stable layout-viewport height. document.documentElement.clientHeight is
+ * unaffected by the soft keyboard on iOS Safari (unlike innerHeight /
+ * visualViewport), so it stays constant while the keyboard animates in/out.
+ */
+export function getStableLayoutViewportHeight(): number {
+  if (typeof window === 'undefined') return 0
+  const ch = typeof document !== 'undefined' ? document.documentElement?.clientHeight : 0
+  if (ch && ch > 0) return ch
+  // fallback when clientHeight is unavailable (SSR / detached): best effort
+  return Math.max(window.innerHeight || 0, window.visualViewport?.height || 0)
+}
+
+/**
+ * Soft-keyboard height = the occluded region between the (stable) layout
+ * viewport bottom and the visual viewport bottom.
+ */
+export function getWebKeyboardHeight(): number {
+  if (typeof window === 'undefined') return 0
+  const vv = window.visualViewport
+  if (!vv) return 0
+  return Math.max(0, Math.round(getStableLayoutViewportHeight() - vv.height))
+}

package/test/keyboardAvoidance.test.ts

@@ -0,0 +1,53 @@
+import { describe, expect, test } from 'vitest'
+
+import { getKeyboardOccludedHeight } from '../src/keyboardAvoidance'
+
+describe('getKeyboardOccludedHeight', () => {
+  const base = {
+    frameSize: 700,
+    isKeyboardVisible: true,
+    keyboardHeight: 300,
+    screenSize: 844,
+    sheetY: 59,
+  }
+
+  test('returns overflow below the keyboard top after the sheet is clamped', () => {
+    expect(getKeyboardOccludedHeight(base)).toBe(215)
+  })
+
+  test('returns zero when the keyboard-adjusted sheet clears the keyboard', () => {
+    expect(
+      getKeyboardOccludedHeight({
+        ...base,
+        frameSize: 400,
+        sheetY: 144,
+      })
+    ).toBe(0)
+  })
+
+  test('ignores hidden keyboard and offscreen sheet positions', () => {
+    expect(
+      getKeyboardOccludedHeight({
+        ...base,
+        isKeyboardVisible: false,
+      })
+    ).toBe(0)
+    expect(
+      getKeyboardOccludedHeight({
+        ...base,
+        sheetY: base.screenSize,
+      })
+    ).toBe(0)
+  })
+
+  test('clamps occlusion to the frame height', () => {
+    expect(
+      getKeyboardOccludedHeight({
+        ...base,
+        frameSize: 120,
+        keyboardHeight: 1000,
+        sheetY: 0,
+      })
+    ).toBe(120)
+  })
+})