@tamagui/sheet 2.7.7 → 3.0.0-beta.1091.1

package/src/SheetImplementationCustom.tsx

@@ -1,27 +1,35 @@
 import { ProvideAdaptContext, useAdaptContext } from '@tamagui/adapt'
 import { AnimatePresence } from '@tamagui/animate-presence'
+// leaf subpath: the grammar itself belongs to the drivers, not to every sheet
+import { getTransitionResolver } from '@tamagui/animation-helpers/transitionResolver'
 import { useComposedRefs } from '@tamagui/compose-refs'
 import { isWeb, useIsomorphicLayoutEffect } from '@tamagui/constants'
 import {
   LayoutMeasurementController,
   View as TamaguiView,
-  useConfiguration,
+  useAnimationDriver,
+  useAnimatedNumber,
+  useAnimatedNumberStyle,
   useDidFinishSSR,
   useEvent,
   useThemeName,
+  createRefComponent,
+  formatDiagnostic,
 } from '@tamagui/core'
 import { needsPortalRepropagation, Portal } from '@tamagui/portal'
 import React, { useState } from 'react'
+import type { PanResponderConfig } from '@tamagui/react-native-pan-responder'
 import type {
-  Animated,
   GestureResponderEvent,
   LayoutChangeEvent,
   PanResponderGestureState,
-} from 'react-native'
-import { Dimensions, PanResponder, View } from 'react-native'
+  View,
+} from '@tamagui/react-native-types'
 import { ParentSheetContext, SheetInsideSheetContext } from './contexts'
-import { GestureDetectorWrapper } from './GestureDetectorWrapper'
+import { SHEET_OVERLAY_MARKER } from './constants'
 import { getGestureHandlerState } from './gestureState'
+import { SheetDragSurface } from './SheetDragSurface'
+import { getStableViewportHeight } from './stableViewportHeight'
 import { GestureSheetProvider } from './GestureSheetContext'
 import { resisted } from './helpers'
 import {
@@ -32,12 +40,20 @@ import {
 import {
   getWebKeyboardResizeHeight,
   getMaxViewportHeight,
-  getStableLayoutViewportHeight,
   getWebVisualViewportOffsetTop,
   MIN_KEYBOARD_HEIGHT,
 } from './webViewport'
-import { SheetProvider } from './SheetContext'
-import type { SheetProps, SnapPointsMode } from './types'
+import {
+  SheetAnimatedPositionContext,
+  SheetOverlayLayerContext,
+  SheetProvider,
+} from './SheetContext'
+import type {
+  SheetProps,
+  SheetTransitionCause,
+  SheetTransitionEvent,
+  SnapPointsMode,
+} from './types'
 import { useGestureHandlerPan } from './useGestureHandlerPan'
 import { useKeyboardControllerSheet } from './useKeyboardControllerSheet'
 import { SafeAreaInsetsContext, useSafeAreaInsets } from './useSafeAreaInsets'
@@ -56,23 +72,12 @@ const rnghRootStyleClosed = { width: '100%', height: 0 } as const
 
 let sheetHiddenStyleSheet: HTMLStyleElement | null = null
 
-// on web we are always relative to window, on to screen
-const relativeDimensionTo = isWeb ? 'window' : 'screen'
-
-// height of the viewport the sheet positions against. on web this MUST be the
-// stable layout viewport and NOT Dimensions.get('window') — react-native-web's
-// Dimensions tracks visualViewport, which shrinks by the soft keyboard. capping
-// frameSize / maxContentSize against that shrinking value corrupts the fit-mode
-// math (translateY = screenSize - frameSize), detaching the sheet's bottom from
-// the screen edge when the keyboard opens. NOTE: window.innerHeight is NOT
-// stable on real iOS Safari (it shrinks with the keyboard too), so we use the
-// self-correcting baseline from webViewport instead. see getStableLayoutViewportHeight.
-function getStableViewportHeight(): number {
-  if (isWeb && typeof window !== 'undefined') return getStableLayoutViewportHeight()
-  return Dimensions.get(relativeDimensionTo).height
-}
+// stack of open modal sheets on web so escape only closes the top-most one.
+// pushed on open (child sheets mount their effect after the parent, so the
+// deepest sheet sits last), popped on close/unmount.
+const sheetEscapeLayers: object[] = []
 
-export const SheetImplementationCustom = React.forwardRef<View, SheetProps>(
+export const SheetImplementationCustom = createRefComponent<View, SheetProps>(
   function SheetImplementationCustom(props, forwardedRef) {
     const parentSheet = React.useContext(ParentSheetContext)
 
@@ -93,18 +98,15 @@ export const SheetImplementationCustom = React.forwardRef<View, SheetProps>(
       zIndex = parentSheet.zIndex + 1,
       moveOnKeyboardChange = false,
       unmountChildrenWhenHidden = false,
-      disableTransparencyHide = false,
+      disableHideWhenClosed = false,
       portalProps,
       containerComponent: ContainerComponent = React.Fragment,
-      onAnimationComplete,
+      onTransition,
     } = props
 
     const state = useSheetOpenState(props)
-    const [overlayComponent, setOverlayComponent] = React.useState<React.ReactNode>(null)
 
-    const providerProps = useSheetProviderProps(props, state, {
-      onOverlayComponent: setOverlayComponent,
-    })
+    const providerProps = useSheetProviderProps(props, state)
     const {
       frameSize,
       setFrameSize,
@@ -126,12 +128,7 @@ export const SheetImplementationCustom = React.forwardRef<View, SheetProps>(
     const sheetRef = React.useRef<View>(undefined as unknown as View)
     const ref = useComposedRefs(forwardedRef, sheetRef, providerProps.contentRef as any)
 
-    // TODO this can be extracted into a helper getAnimationConfig(animationProp as array | string)
-    const { animationDriver } = useConfiguration()
-
-    if (!animationDriver) {
-      throw new Error(`Sheet requires an animation driver to be set`)
-    }
+    const animationDriver = useAnimationDriver()
 
     const transitionConfig = (() => {
       // explicit transitionConfig prop always takes precedence
@@ -139,21 +136,32 @@ export const SheetImplementationCustom = React.forwardRef<View, SheetProps>(
         return transitionConfigProp
       }
 
-      const [animationProp, animationPropConfig] = !transition
-        ? []
-        : Array.isArray(transition)
-          ? transition
-          : ([transition] as const)
-
-      // look up named animation config from driver if available
-      if (animationProp && animationDriver.animations?.[animationProp as string]) {
-        return {
-          ...animationDriver.animations[animationProp as string],
-          ...animationPropConfig,
-        }
+      // the sheet drives its position through an animated number rather than a
+      // style prop, so it resolves the authored transition itself. it goes
+      // through the same grammar every driver and the compiler use, so a config
+      // entry never means one thing here and another in a style prop. the raw
+      // config is the wrong thing to spread: presets are authored as
+      // `{ duration, bounce }` in milliseconds, and motion reads `duration` in
+      // seconds.
+      const resolved = transition
+        ? getTransitionResolver()?.resolve(transition, {
+            animations: animationDriver.animations,
+          })
+        : null
+      const timing = resolved?.all?.timing
+      if (!timing) return null
+      if (timing.kind === 'timing') {
+        return { type: 'timing', duration: timing.durationMs }
+      }
+      // stiffness/damping/mass is the spelling every spring driver takes, and
+      // the resolver derives it from `{ duration, bounce }` when that is what
+      // the config was written in
+      return {
+        type: 'spring',
+        stiffness: timing.stiffness,
+        damping: timing.damping,
+        mass: timing.mass,
       }
-
-      return null
     })()
 
     /**
@@ -334,8 +342,7 @@ export const SheetImplementationCustom = React.forwardRef<View, SheetProps>(
           ? preKeyboardFrameSize.current
           : 0
 
-    const { useAnimatedNumber, useAnimatedNumberStyle } = animationDriver
-    const AnimatedView = (animationDriver.View ?? TamaguiView) as typeof Animated.View
+    const AnimatedView = (animationDriver.View ?? TamaguiView) as React.ComponentType<any>
 
     useIsomorphicLayoutEffect(() => {
       if (!(sheetInsideSheet && open)) return
@@ -367,8 +374,31 @@ export const SheetImplementationCustom = React.forwardRef<View, SheetProps>(
 
     const hasScrollView = React.useRef(false)
 
-    // safety fallback timer for sheet close opacity
-    const opacityFallbackTimer = React.useRef<ReturnType<typeof setTimeout> | null>(null)
+    // snap index of the last animated move, so a transition can be classified
+    // as open (from closed), snap (between snap points), or close.
+    const lastPositionIndexRef = React.useRef(-1)
+    // the in-flight transition, so a superseding move reports it interrupted.
+    const pendingTransitionRef = React.useRef<{
+      cause: SheetTransitionCause
+      position: number
+    } | null>(null)
+
+    const emitTransition = useEvent(
+      (
+        phase: 'start' | 'end',
+        event: { cause: SheetTransitionCause; position: number },
+        finished?: boolean
+      ) => {
+        const e: SheetTransitionEvent = {
+          phase,
+          cause: event.cause,
+          position: event.position,
+        }
+        if (phase === 'end') e.finished = finished
+        onTransition?.(e)
+        controller?.onTransition?.(e)
+      }
+    )
 
     const syncAnimatedPosition = useEvent((value: number) => {
       at.current = value
@@ -440,21 +470,54 @@ export const SheetImplementationCustom = React.forwardRef<View, SheetProps>(
       const closeTarget = isWeb
         ? Math.max(effScreenSize, getMaxViewportHeight())
         : effScreenSize
-      let toValue = isHidden || position === -1 ? closeTarget : activePositions[position]
-
-      if (at.current === toValue) return
+      // dismissOnSnapToBottom appends an offscreen snap point. Gesture release
+      // calls setPosition(dismissIndex) and animateTo(dismissIndex) in the same
+      // event, before React commits open=false and turns the provider position
+      // into -1. Treat that synthetic snap as close here so its in-flight
+      // callback owns display-none hiding and the Adapt presence handoff.
+      const isDismissPosition =
+        dismissOnSnapToBottom && position === activePositions.length - 1
+      const isOpenAnimation = position !== -1 && !isHidden && !isDismissPosition
+      const toValue = isOpenAnimation ? activePositions[position] : closeTarget
+
+      if (at.current === toValue) {
+        // a drag can land exactly on the synthetic dismiss point. there is no
+        // remaining distance to animate, but it is still a completed close and
+        // must release the same lifecycle consumers as an animated dismissal.
+        if (isDismissPosition) {
+          if (pendingTransitionRef.current) {
+            emitTransition('end', pendingTransitionRef.current, false)
+            pendingTransitionRef.current = null
+          }
+          stopSpring()
+          const event = { cause: 'close' as const, position: toValue }
+          lastPositionIndexRef.current = -1
+          emitTransition('start', event)
+          syncAnimatedPosition(toValue)
+          setIsFullyClosed(true)
+          emitTransition('end', event, true)
+        }
+        return
+      }
 
       at.current = toValue
-      stopSpring()
-
-      const isOpenAnimation = position !== -1 && !isHidden
 
-      // clear any pending fallback timer
-      if (opacityFallbackTimer.current) {
-        clearTimeout(opacityFallbackTimer.current)
-        opacityFallbackTimer.current = null
+      const cause: SheetTransitionCause = !isOpenAnimation
+        ? 'close'
+        : lastPositionIndexRef.current < 0
+          ? 'open'
+          : 'snap'
+      lastPositionIndexRef.current = isOpenAnimation ? position : -1
+      const event = { cause, position: toValue }
+
+      // a new move supersedes any in-flight one: report it interrupted
+      if (pendingTransitionRef.current) {
+        emitTransition('end', pendingTransitionRef.current, false)
+        pendingTransitionRef.current = null
       }
 
+      stopSpring()
+
       const animationCompleteCallback = () => {
         // a newer animateTo supersedes this one: drivers still fire the owed
         // completion callback when a new setValue replaces an in-flight one.
@@ -462,34 +525,22 @@ export const SheetImplementationCustom = React.forwardRef<View, SheetProps>(
         // this stale toValue would make the next animateTo to this position
         // no-op (at === toValue) while the dom sits somewhere else — on web
         // that leaves a reopened sheet parked offscreen at its close target.
+        // it would also null out the superseding move's pending transition
+        // and double-emit a completed end for an already-interrupted event.
         if (at.current !== toValue) return
         syncAnimatedPosition(toValue)
-        if (opacityFallbackTimer.current) {
-          clearTimeout(opacityFallbackTimer.current)
-          opacityFallbackTimer.current = null
-        }
-        // use openRef (live) not open (stale closure) — if the sheet
-        // was reopened before this callback fires (e.g. cancelled close
-        // animation), we must not hide it
+        pendingTransitionRef.current = null
+        // use openRef (live) not open (stale closure) — if the sheet was
+        // reopened before this callback fires (e.g. cancelled close animation),
+        // we must not hide it
         if (!isOpenAnimation && !openRef.current) {
-          setOpacity(0)
+          setIsFullyClosed(true)
         }
-        onAnimationComplete?.({ open: isOpenAnimation })
-        // also notify the SheetController so a parent (e.g. Dialog adapt)
-        // can hold the sheet's children mounted until the slide-out is done
-        controller?.onAnimationComplete?.({ open: isOpenAnimation })
+        emitTransition('end', event, true)
       }
 
-      // safety fallback: if animation callback never fires, still hide the sheet
-      if (!isOpenAnimation) {
-        opacityFallbackTimer.current = setTimeout(() => {
-          opacityFallbackTimer.current = null
-          // check live open state via ref — sheet may have reopened (e.g. adapt handoff)
-          if (!openRef.current) {
-            setOpacity(0)
-          }
-        }, 1000)
-      }
+      pendingTransitionRef.current = event
+      emitTransition('start', event)
 
       // skip animation when adapting from dialog to sheet
       if (skipAdaptAnimation.current) {
@@ -502,14 +553,32 @@ export const SheetImplementationCustom = React.forwardRef<View, SheetProps>(
         return
       }
 
-      animatedNumber.setValue(
-        toValue,
-        animationOverride || {
-          type: 'spring',
-          ...transitionConfig,
-        },
-        animationCompleteCallback
-      )
+      const resolvedConfig = animationOverride || {
+        type: 'spring',
+        ...transitionConfig,
+      }
+
+      // the sheet position spring moves hundreds of px. the spring drivers'
+      // default rest detection is tuned for tiny values (react-native Animated:
+      // 0.001px thresholds; reanimated 4: relative energyThreshold 6e-9), so for
+      // a sheet-sized move completion would fire 1.4-1.7s after the animation is
+      // visually done. these px-sized rest thresholds make close-complete prompt
+      // (~0.5-0.8s), which is what now drives display:none hiding and the Adapt
+      // presence release (no timers). user config still wins via spread order;
+      // each driver ignores the other driver's keys.
+      const springConfig =
+        !resolvedConfig.type || resolvedConfig.type === 'spring'
+          ? {
+              // react-native Animated (absolute px)
+              restDisplacementThreshold: 1,
+              restSpeedThreshold: 10,
+              // reanimated 4 (relative energy): ~0.3% of travel amplitude
+              energyThreshold: 1e-5,
+              ...resolvedConfig,
+            }
+          : resolvedConfig
+
+      animatedNumber.setValue(toValue, springConfig, animationCompleteCallback)
     })
 
     useIsomorphicLayoutEffect(() => {
@@ -587,10 +656,12 @@ export const SheetImplementationCustom = React.forwardRef<View, SheetProps>(
     const themeName = useThemeName()
     const [blockPan, setBlockPan] = React.useState(false)
 
-    const panResponder = React.useMemo(() => {
-      if (disableDrag) return
-      if (!frameSize) return
-      if (isShowingInnerSheet) return
+    // the drag surface turns this into a PanResponder. it is built here because
+    // the handlers close over the sheet's live drag state and the scroll bridge.
+    const panConfig = React.useMemo((): PanResponderConfig | null => {
+      if (disableDrag) return null
+      if (!frameSize) return null
+      if (isShowingInnerSheet) return null
 
       // use keyboard-adjusted positions (matches the RNGH path): when the
       // keyboard is open the sheet sits at activePositions[0], so clamping drags
@@ -674,7 +745,7 @@ export const SheetImplementationCustom = React.forwardRef<View, SheetProps>(
           // touch is on the ScrollView node — the web scroll-view gesture hook
           // owns it and drives drag/release through scrollBridge directly (it
           // re-baselines via scrollBridge.startPanDrag on each pan handoff). if
-          // we also granted here, RNW's PanResponder would set the animated
+          // we also granted here, the PanResponder would set the animated
           // position from a second, differently-based offset every move and the
           // sheet would jitter/jump. defer entirely to the hook.
           if (scrollBridge.scrollNodeTouched) {
@@ -757,7 +828,7 @@ export const SheetImplementationCustom = React.forwardRef<View, SheetProps>(
         animateTo(positionIndex)
       }
 
-      return PanResponder.create({
+      return {
         onMoveShouldSetPanResponder: onMoveShouldSet,
         // once we own the drag, don't yield it to another responder
         // (re-renders during the drag were cooperatively terminating it under
@@ -781,7 +852,7 @@ export const SheetImplementationCustom = React.forwardRef<View, SheetProps>(
         onPanResponderEnd: finish,
         onPanResponderTerminate: finish,
         onPanResponderRelease: finish,
-      })
+      }
     }, [
       disableDrag,
       isShowingInnerSheet,
@@ -833,6 +904,32 @@ export const SheetImplementationCustom = React.forwardRef<View, SheetProps>(
       }
     }, [open])
 
+    React.useEffect(() => {
+      if (!isWeb || !modal || !open || shouldHideParentSheet) return
+
+      const layer = {}
+      sheetEscapeLayers.push(layer)
+
+      const onKeyDown = (event: KeyboardEvent) => {
+        if (event.key === 'Escape') {
+          // only the top-most open modal sheet responds so a nested sheet
+          // doesn't take its parent down with it
+          if (sheetEscapeLayers[sheetEscapeLayers.length - 1] === layer) {
+            state.setOpen(false)
+          }
+        }
+      }
+
+      document.addEventListener('keydown', onKeyDown)
+      return () => {
+        const index = sheetEscapeLayers.indexOf(layer)
+        if (index > -1) {
+          sheetEscapeLayers.splice(index, 1)
+        }
+        document.removeEventListener('keydown', onKeyDown)
+      }
+    }, [modal, open, shouldHideParentSheet, state.setOpen])
+
     // gesture handler hook for RNGH-based gesture coordination
     const { panGesture, panGestureRef, gestureHandlerEnabled } = useGestureHandlerPan({
       positions: activePositions,
@@ -923,17 +1020,32 @@ export const SheetImplementationCustom = React.forwardRef<View, SheetProps>(
 
     const animatedStyle = useAnimatedNumberStyle(animatedNumber, getAnimatedNumberStyle)
 
-    // we need to set this *after* fully closed to 0, to avoid it overlapping
-    // the page when resizing quickly on web for example
-    const [opacity, setOpacity] = React.useState(open ? 1 : 0)
-    if (open && opacity === 0) {
-      setOpacity(1)
-      // cancel any pending close fallback — sheet is reopening
-      if (opacityFallbackTimer.current) {
-        clearTimeout(opacityFallbackTimer.current)
-        opacityFallbackTimer.current = null
-      }
+    // a fully-closed sheet is hidden with display:none (set from the
+    // close-complete transition event) so it never overlaps the page when
+    // resizing quickly on web. it starts NOT hidden — the frame must be laid
+    // out to measure its size (display:none has no layout box, so hiding before
+    // the first measurement would leave frameSize/screenSize at 0). it un-hides
+    // synchronously in render on re-open, before layout, keeping the retained
+    // frame size. the closed-but-never-opened frame stays off screen via its
+    // translateY, so leaving it laid out is not visible.
+    const [isFullyClosed, setIsFullyClosed] = React.useState(false)
+    if (open && isFullyClosed) {
+      setIsFullyClosed(false)
+    }
+    // whether the sheet is visually active: open, or still animating out.
+    // isFullyClosed only flips true from the close-animation-complete callback,
+    // so it stays false for a mounted-but-never-opened sheet - track first open
+    // separately so a closed sheet is inactive from mount. drives the portal
+    // host's visibility (see Portal.tsx on why closed hosts must be hidden).
+    const hasEverOpened = React.useRef(open)
+    if (open) {
+      hasEverOpened.current = true
     }
+    const isVisuallyActive = open || (hasEverOpened.current && !isFullyClosed)
+    // shouldHideParentSheet (a nested sheet on native gorhom) hides the parent
+    // immediately; disableHideWhenClosed opts the closed wrapper out of hiding
+    // but never overrides the nested-sheet hide.
+    const applyHidden = shouldHideParentSheet || (isFullyClosed && !disableHideWhenClosed)
 
     const forcedContentHeight = hasFit
       ? undefined
@@ -945,12 +1057,25 @@ export const SheetImplementationCustom = React.forwardRef<View, SheetProps>(
     const setHasScrollView = React.useCallback((val: boolean) => {
       hasScrollView.current = val
     }, [])
-    // const id = useId()
-    // const { AdaptProvider, when, children } = useAdaptParent({
-    //   scope: `${id}Sheet`,
-    //   portal: true,
-    // })
 
+    // publish the live animated position so user code can build drag-linked
+    // effects (e.g. an overlay fade) via Sheet.useAnimatedPosition(). positions
+    // are the resolved px offsets matching snapPoints order; minY is topmost.
+    const animatedPositionValue = React.useMemo(
+      () => ({
+        value: animatedNumber,
+        screenSize: effScreenSize,
+        frameSize,
+        snapOffsets: activePositions,
+        minY: activePositions[0] ?? 0,
+      }),
+      [animatedNumber, effScreenSize, frameSize, activePositions]
+    )
+
+    const { overlayChildren, animatedChildren } = React.useMemo(
+      () => partitionSheetChildren(props.children),
+      [props.children]
+    )
     let contents = (
       <LayoutMeasurementController disable={!open}>
         <ParentSheetContext.Provider value={nextParentContext}>
@@ -968,66 +1093,55 @@ export const SheetImplementationCustom = React.forwardRef<View, SheetProps>(
               panGesture={panGesture}
               panGestureRef={panGestureRef}
             >
-              <AnimatePresence custom={{ open }}>
-                {shouldHideParentSheet || !open ? null : overlayComponent}
-              </AnimatePresence>
-
-              {snapPointsMode !== 'percent' && (
-                <View
-                  style={{
-                    opacity: 0,
-                    position: 'absolute',
-                    top: 0,
-                    left: 0,
-                    right: 0,
-                    bottom: 0,
-                    pointerEvents: 'none',
-                  }}
-                  onLayout={handleMaxContentViewLayout}
-                />
-              )}
-
-              <AnimatedView
-                ref={ref}
-                onLayout={handleAnimationViewLayout}
-                // @ts-ignore for CSS driver this is necessary to attach the transition
-                // also motion driver at least though i suspect all drivers?
-                transition={isDragging || disableAnimation ? null : transition}
-                // @ts-ignore
-                disableClassName
-                style={[
-                  {
-                    position: 'absolute',
-                    zIndex,
-                    width: '100%',
-                    height: forcedContentHeight,
-                    minHeight: forcedContentHeight,
-                    opacity: shouldHideParentSheet
-                      ? 0
-                      : disableTransparencyHide
-                        ? 1
-                        : opacity,
-                    ...((shouldHideParentSheet || !open) && {
-                      pointerEvents: 'none',
-                    }),
-                  },
-                  animatedStyle,
-                ]}
-              >
-                {/* wrap children with plain RN View for panResponder - tamagui views no longer handle responder events on web */}
-                {gestureHandlerEnabled && panGesture ? (
-                  <GestureDetectorWrapper gesture={panGesture} style={{ flex: 1 }}>
-                    {props.children}
-                  </GestureDetectorWrapper>
-                ) : (
-                  <View
-                    {...panResponder?.panHandlers}
-                    style={{ flex: 1, width: '100%', height: '100%' }}
-                  >
-                    {props.children}
-                  </View>
+              <SheetAnimatedPositionContext.Provider value={animatedPositionValue}>
+                <SheetOverlayLayerContext.Provider value>
+                  <AnimatePresence custom={{ open }}>
+                    {shouldHideParentSheet || !open ? null : overlayChildren}
+                  </AnimatePresence>
+                </SheetOverlayLayerContext.Provider>
+
+                {snapPointsMode !== 'percent' && (
+                  <TamaguiView
+                    opacity={0}
+                    position="absolute"
+                    inset={0}
+                    pointerEvents="none"
+                    onLayout={handleMaxContentViewLayout}
+                  />
                 )}
-              </AnimatedView>
+
+                <AnimatedView
+                  ref={ref}
+                  onLayout={handleAnimationViewLayout}
+                  // @ts-ignore for CSS driver this is necessary to attach the transition
+                  // also motion driver at least though i suspect all drivers?
+                  transition={isDragging || disableAnimation ? null : transition}
+                  // @ts-ignore
+                  disableClassName
+                  style={[
+                    {
+                      position: 'absolute',
+                      zIndex,
+                      width: '100%',
+                      height: forcedContentHeight,
+                      minHeight: forcedContentHeight,
+                      ...(applyHidden && { display: 'none' }),
+                      ...((shouldHideParentSheet || !open) && {
+                        pointerEvents: 'none',
+                      }),
+                    },
+                    animatedStyle,
+                  ]}
+                >
+                  <SheetDragSurface
+                    gestureHandlerEnabled={gestureHandlerEnabled}
+                    panGesture={panGesture}
+                    panConfig={panConfig}
+                  >
+                    {animatedChildren}
+                  </SheetDragSurface>
+                </AnimatedView>
+              </SheetAnimatedPositionContext.Provider>
             </GestureSheetProvider>
           </SheetProvider>
         </ParentSheetContext.Provider>
@@ -1035,7 +1149,6 @@ export const SheetImplementationCustom = React.forwardRef<View, SheetProps>(
     )
 
     if (process.env.TAMAGUI_TARGET === 'native' && needsPortalRepropagation()) {
-      // TODO alongside sheet scope="" need to pass scope here
       const adaptContext = useAdaptContext()
       contents = (
         <ProvideAdaptContext {...adaptContext}>
@@ -1051,7 +1164,7 @@ export const SheetImplementationCustom = React.forwardRef<View, SheetProps>(
     }
 
     // start mounted so we get an accurate measurement the first time
-    const shouldMountChildren = unmountChildrenWhenHidden ? !!opacity : true
+    const shouldMountChildren = unmountChildrenWhenHidden ? !isFullyClosed : true
 
     if (modal) {
       // a modal sheet is teleported through <Portal> to the root portal host.
@@ -1071,7 +1184,7 @@ export const SheetImplementationCustom = React.forwardRef<View, SheetProps>(
         <ContainerComponent>{contents}</ContainerComponent>
       ) : null
       const modalContents = (
-        <Portal stackZIndex={zIndex} {...portalProps}>
+        <Portal stackZIndex={zIndex} hidden={!isVisuallyActive} {...portalProps}>
           {mountedContents && RNGHRoot ? (
             <RNGHRoot style={open ? rnghRootStyleOpen : rnghRootStyleClosed}>
               {mountedContents}
@@ -1098,6 +1211,49 @@ export const SheetImplementationCustom = React.forwardRef<View, SheetProps>(
   }
 )
 
+type SheetPartStaticConfig = {
+  [SHEET_OVERLAY_MARKER]?: boolean
+  parentStaticConfig?: SheetPartStaticConfig
+}
+
+export function isSheetOverlayComponent(type: unknown) {
+  let staticConfig = (type as { staticConfig?: SheetPartStaticConfig } | null)
+    ?.staticConfig
+
+  while (staticConfig) {
+    if (staticConfig[SHEET_OVERLAY_MARKER]) {
+      return true
+    }
+    staticConfig = staticConfig.parentStaticConfig
+  }
+
+  return false
+}
+
+function partitionSheetChildren(children: React.ReactNode) {
+  const overlayChildren: React.ReactNode[] = []
+  const animatedChildren: React.ReactNode[] = []
+
+  React.Children.forEach(children, (child) => {
+    if (!React.isValidElement(child)) {
+      animatedChildren.push(child)
+      return
+    }
+
+    if (isSheetOverlayComponent(child.type)) {
+      overlayChildren.push(child)
+      return
+    }
+
+    animatedChildren.push(child)
+  })
+
+  return {
+    overlayChildren,
+    animatedChildren,
+  }
+}
+
 function getYPositions(
   mode: SnapPointsMode,
   point: string | number,
@@ -1118,12 +1274,30 @@ function getYPositions(
     if (point.endsWith('%')) {
       const pct = Math.min(100, Math.max(0, Number(point.slice(0, -1)))) / 100
       if (Number.isNaN(pct)) {
-        console.warn('Invalid snapPoint percentage string')
+        console.warn(
+          formatDiagnostic(
+            'TAMAGUI_SHEET_SNAP_POINT',
+            'Sheet',
+            'snapPoints contains an invalid percentage string',
+            'Use "fit", a pixel number, or a percentage such as "50%"',
+            'snapPoint',
+            point
+          )
+        )
         return 0
       }
       return Math.round(screenSize - pct * screenSize)
     }
-    console.warn('Invalid snapPoint unknown value')
+    console.warn(
+      formatDiagnostic(
+        'TAMAGUI_SHEET_SNAP_POINT',
+        'Sheet',
+        'snapPoints contains an unsupported mixed-mode value',
+        'Use "fit", a pixel number, or a percentage such as "50%"',
+        'snapPoint',
+        point
+      )
+    )
     return 0
   }
 
@@ -1138,7 +1312,16 @@ function getYPositions(
 
   const pct = Math.min(100, Math.max(0, Number(point))) / 100
   if (Number.isNaN(pct)) {
-    console.warn('Invalid snapPoint percentage')
+    console.warn(
+      formatDiagnostic(
+        'TAMAGUI_SHEET_SNAP_POINT',
+        'Sheet',
+        'snapPoints contains a value that cannot be converted to a percentage',
+        'Use a numeric percentage such as 50',
+        'snapPoint',
+        point
+      )
+    )
     return 0
   }