@tamagui/sheet 2.7.7 → 3.0.0-beta.1093.1

package/src/SheetScrollView.tsx

@@ -1,10 +1,9 @@
 import { composeRefs } from '@tamagui/compose-refs'
-import { isWeb, View, type GetRef } from '@tamagui/core'
-import type { ScrollViewProps } from '@tamagui/scroll-view'
+import { createStyledHOC, isWeb, style, View, type GetProps } from '@tamagui/core'
+import type { ScrollViewRef } from '@tamagui/scroll-view'
 import { ScrollView } from '@tamagui/scroll-view'
 import { useControllableState } from '@tamagui/use-controllable-state'
 import React, { useEffect, useRef, useState } from 'react'
-import type { ScrollView as RNScrollView } from 'react-native'
 import { useGestureSheetContext } from './GestureSheetContext'
 import { getGestureHandlerState, isGestureHandlerEnabled } from './gestureState'
 import { useSheetContext } from './SheetContext'
@@ -19,22 +18,32 @@ import {
 } from './webViewport'
 
 const SHEET_SCROLL_VIEW_NAME = 'SheetScrollView'
+const sheetContentStyle = style({ minHeight: '100%' })
 
-export const SheetScrollView = React.forwardRef<
-  GetRef<typeof ScrollView>,
-  ScrollViewProps
->(
+type SheetScrollViewBaseProps = GetProps<typeof ScrollView>
+
+type SheetScrollViewProps = SheetScopedProps<
+  SheetScrollViewBaseProps & {
+    h?: SheetScrollViewBaseProps['height']
+    o?: SheetScrollViewBaseProps['opacity']
+    pos?: SheetScrollViewBaseProps['position']
+  }
+>
+
+export const SheetScrollView = createStyledHOC(
+  ScrollView,
   (
     {
-      __scopeSheet,
+      scope,
       children,
       onScroll,
       scrollEnabled: scrollEnabledProp,
+      style,
       ...props
-    }: SheetScopedProps<ScrollViewProps>,
+    }: SheetScrollViewProps,
     ref
   ) => {
-    const context = useSheetContext(SHEET_SCROLL_VIEW_NAME, __scopeSheet)
+    const context = useSheetContext(scope)
     const gestureContext = useGestureSheetContext()
     const { scrollBridge, setHasScrollView, hasFit, screenSize } = context
     const keyboardOccludedHeight = Math.max(0, context.keyboardOccludedHeight || 0)
@@ -50,7 +59,7 @@ export const SheetScrollView = React.forwardRef<
       prop: scrollEnabledProp,
       defaultProp: true,
     })
-    const scrollRef = React.useRef<RNScrollView | null>(null)
+    const scrollRef = React.useRef<ScrollViewRef | null>(null)
 
     const [hasScrollableContent, setHasScrollableContent] = useState(true)
     const parentHeight = useRef(0)
@@ -61,29 +70,33 @@ export const SheetScrollView = React.forwardRef<
     // 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
+    // with snapPointsMode="fit", Container 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 Container
     // 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
+    const fitSizingProps = hasFit
       ? {
           flex: undefined as undefined,
           height: undefined as undefined,
           maxHeight: screenSize || undefined,
         }
       : { flex: 1 }
-    const contentContainerStyle = hasFit ? undefined : { minHeight: '100%' as const }
+    const contentContainerStyle = hasFit ? undefined : sheetContentStyle
 
     // 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.
+    // last in the ordered style array so it wins.
     const keyboardFrozenOverride =
       hasFit && isKeyboardVisible && frozenFrameHeight > 0
         ? { height: frozenFrameHeight, maxHeight: frozenFrameHeight }
         : null
+    const scrollViewStyle = [
+      ...(Array.isArray(style) ? style : [style]),
+      keyboardFrozenOverride,
+    ]
 
     const panGestureRef = gestureContext?.panGestureRef
     const { ScrollView: RNGHScrollView } = getGestureHandlerState()
@@ -281,7 +294,7 @@ export const SheetScrollView = React.forwardRef<
       return (
         <RNGHComponent
           ref={composeRefs(scrollRef as any, ref)}
-          style={fitSizingStyle}
+          style={[fitSizingProps, ...scrollViewStyle]}
           scrollEventThrottle={1}
           scrollEnabled={scrollEnabled}
           simultaneousHandlers={[panGestureRef]}
@@ -329,7 +342,6 @@ export const SheetScrollView = React.forwardRef<
           keyboardShouldPersistTaps="always"
           keyboardDismissMode="none"
           {...props}
-          {...keyboardFrozenOverride}
         >
           {contentWrapper}
         </RNGHComponent>
@@ -339,12 +351,12 @@ export const SheetScrollView = React.forwardRef<
     // fallback ScrollView with platform-specific gesture props
     return (
       <ScrollView
+        {...fitSizingProps}
         onLayout={(e) => {
           recordFitHeight(Math.ceil(e.nativeEvent.layout.height))
           updateScrollable()
         }}
         ref={composeRefs(scrollRef as any, ref)}
-        {...fitSizingStyle}
         scrollEventThrottle={1}
         className="_ovs-contain"
         scrollEnabled={scrollEnabled}
@@ -359,10 +371,14 @@ export const SheetScrollView = React.forwardRef<
         contentContainerStyle={contentContainerStyle}
         {...gestureProps}
         {...props}
-        {...keyboardFrozenOverride}
+        style={scrollViewStyle}
       >
         {contentWrapper}
       </ScrollView>
     )
+  },
+  {
+    disableTheme: true,
+    displayName: SHEET_SCROLL_VIEW_NAME,
   }
 )

package/src/constants.tsx

@@ -1,5 +1,5 @@
-export const constants = {}
-
-export const SHEET_NAME = 'Sheet'
+export const SHEET_CONTAINER_NAME = 'SheetContainer'
+export const SHEET_BACKGROUND_NAME = 'SheetBackground'
 export const SHEET_HANDLE_NAME = 'SheetHandle'
 export const SHEET_OVERLAY_NAME = 'SheetOverlay'
+export const SHEET_OVERLAY_MARKER = Symbol('SheetOverlay')

package/src/helpers.tsx

@@ -15,17 +15,3 @@ export function resisted(y: number, minY: number, maxOverflow = 25) {
   // Return the position with resistance applied
   return minY - resistedDistance
 }
-
-// // set all the way off screen
-// // + 0.1 ensures this is unique - see hasntMeasured ref
-
-// let hiddenSize: number
-
-// export function getHiddenSize() {
-//   if (hiddenSize == undefined) {
-//     // this trigger reflow on web avoid doing on startup
-//     const screen = Dimensions.get('screen')
-//     hiddenSize = Math.max(screen.height, screen.width) + 0.1
-//   }
-//   return hiddenSize
-// }

package/src/index.ts

@@ -1,6 +1,7 @@
 export * from './Sheet'
-export * from './useSheet'
-export * from './createSheet'
+// public so copied skins can forward the open state into their own styled parts
+// (e.g. the Handle's open-driven opacity variant).
+export { useSheetContext } from './SheetContext'
 export * from './SheetController'
 export * from './useSheetController'
 export * from './useSheetOpenState'
@@ -9,7 +10,3 @@ 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/{nativeSheet.tsx → nativeSheet.native.tsx}

@@ -1,27 +1,24 @@
 import { YStack } from '@tamagui/stacks'
 import type { FunctionComponent } from 'react'
 import { useEffect, useRef } from 'react'
-import { View } from 'react-native'
-import { SheetProvider } from './SheetContext'
-import type { SheetProps } from './types'
+import { Platform, View } from 'react-native'
+import { SheetNativeSystemContext, SheetProvider } from './SheetContext'
+import type { SheetNativeModal, SheetNativePlatforms, SheetProps } from './types'
 import { useSheetOpenState } from './useSheetOpenState'
 import { useSheetProviderProps } from './useSheetProviderProps'
 
-// import { useSheetSnapPoints } from './useSheetSnapPoints'
-
-type SheetNativePlatforms = 'ios'
-
 const nativeSheets: Record<SheetNativePlatforms, FunctionComponent<SheetProps> | null> = {
   ios: null,
 }
 
 export function getNativeSheet(platform: SheetNativePlatforms) {
+  if (Platform.OS !== platform) return null
   return nativeSheets[platform]
 }
 
 export function setupNativeSheet(
   platform: SheetNativePlatforms,
-  RNIOSModal: { ModalSheetView: any; ModalSheetViewMainContent: any }
+  RNIOSModal: SheetNativeModal
 ) {
   const { ModalSheetView, ModalSheetViewMainContent } = RNIOSModal
 
@@ -29,8 +26,6 @@ export function setupNativeSheet(
     nativeSheets[platform] = (props: SheetProps) => {
       const state = useSheetOpenState(props)
       const providerProps = useSheetProviderProps(props, state)
-      // const { position } = providerProps
-      // const { positions } = useSheetSnapPoints(providerProps)
 
       const { open, setOpen } = state
       const ref = useRef<{
@@ -51,21 +46,15 @@ export function setupNativeSheet(
         setOpen(next)
       }
 
-      // modalContentPreferredContentSize={{
-      //   mode: 'percent',
-      //   percentWidth: '100%',
-      //   percentHeight:
-      // }}
-
       return (
-        <>
+        <SheetNativeSystemContext.Provider value>
           <SheetProvider
             setHasScrollView={emptyFn}
             keyboardOccludedHeight={0}
             isKeyboardVisible={false}
             keyboardStableFrameHeight={0}
             {...providerProps}
-            onlyShowFrame
+            onlyShowContainer
           >
             <ModalSheetView ref={ref} onModalDidDismiss={() => setOpenInternal(false)}>
               <ModalSheetViewMainContent>
@@ -77,7 +66,7 @@ export function setupNativeSheet(
             {/* so just hiding it here for now... not great... */}
             <YStack
               position="absolute"
-              opacity={0}
+              display="none"
               pointerEvents="none"
               width={0}
               height={0}
@@ -85,7 +74,7 @@ export function setupNativeSheet(
               {props.children}
             </YStack>
           </SheetProvider>
-        </>
+        </SheetNativeSystemContext.Provider>
       )
     }
   }

package/src/nativeSheet.ts

@@ -0,0 +1,19 @@
+import type { FunctionComponent } from 'react'
+
+import type { SheetNativeModal, SheetNativePlatforms, SheetProps } from './types'
+
+/**
+ * `native` asks for the platform's own sheet, which is a UIKit modal, so there
+ * is nothing to register or hand back on web and the sheet always falls through
+ * to its own implementation. The native sibling holds the real registry.
+ */
+export function getNativeSheet(
+  _platform: SheetNativePlatforms
+): FunctionComponent<SheetProps> | null {
+  return null
+}
+
+export function setupNativeSheet(
+  _platform: SheetNativePlatforms,
+  _RNIOSModal: SheetNativeModal
+) {}

package/src/stableViewportHeight.native.ts

@@ -0,0 +1,9 @@
+import { Dimensions } from 'react-native'
+
+/**
+ * Height of the viewport the sheet positions against. Native measures against
+ * the screen rather than the window, so it does not move with the keyboard.
+ */
+export function getStableViewportHeight(): number {
+  return Dimensions.get('screen').height
+}

package/src/stableViewportHeight.ts

@@ -0,0 +1,15 @@
+import { getStableLayoutViewportHeight } from './webViewport'
+
+/**
+ * Height of the viewport the sheet positions against.
+ *
+ * This MUST be the stable layout viewport: the visual viewport shrinks by the
+ * soft keyboard, and capping frameSize / maxContentSize against a 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), hence the self-correcting baseline in webViewport.
+ */
+export function getStableViewportHeight(): number {
+  return getStableLayoutViewportHeight()
+}

package/src/types.tsx

@@ -1,99 +1,114 @@
 import type { AnimatedNumberStrategy, TransitionProp } from '@tamagui/core'
-import type { ScopedProps } from '@tamagui/create-context'
 import type { PortalProps } from '@tamagui/portal'
+import type { PanResponderConfig } from '@tamagui/react-native-pan-responder'
 import type { RemoveScroll } from '@tamagui/remove-scroll'
 import type { ReactNode } from 'react'
 import type React from 'react'
 
-export type SheetProps = ScopedProps<
-  {
-    open?: boolean
-    defaultOpen?: boolean
-    onOpenChange?: OpenChangeHandler
-
-    /**
-     * Control the index of the position in the `snapPoints` array
-     */
-    position?: number
-
-    /**
-     * Initial position from the `snapPoints` array
-     */
-    defaultPosition?: number
-
-    /**
-     * Array of pixels or percents the Sheet will attempt to move to when dragged.
-     * The first is the topmost and default when first opened via open prop.
-     */
-    snapPoints?: (string | number)[]
-
-    snapPointsMode?: SnapPointsMode
-    onPositionChange?: PositionChangeHandler
-    children?: ReactNode
-    dismissOnOverlayPress?: boolean
-    dismissOnSnapToBottom?: boolean
-
-    /**
-     * Disables the RemoveScroll behavior that prevents body scrolling while sheet is open.
-     * By default, RemoveScroll is enabled when the sheet is open and modal.
-     */
-    disableRemoveScroll?: boolean
-
-    /**
-     * @deprecated Use `disableRemoveScroll` instead. This prop will be removed in a future version.
-     * Note: `disableRemoveScroll={true}` is equivalent to `forceRemoveScrollEnabled={false}`
-     */
-    forceRemoveScrollEnabled?: boolean
-
-    transitionConfig?: AnimatedNumberStrategy
-
-    /**
-     * By default Sheet will prefer the open prop over a parent component that is
-     * controlling it via Adapt. In general if you want to Adapt to a sheet, you'd
-     * leave the open prop undefined. If you'd like to have the parent override the
-     * prop you've set manually on Sheet, set this to true.
-     */
-    preferAdaptParentOpenState?: boolean
-
-    /**
-     * (experimental) Remove the children while hidden (to save some performance, but can cause issues with animations)
-     */
-    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)
-     */
-    native?: 'ios'[] | boolean
-
-    /**
-     * Pass if you're using the CSS animation driver
-     */
-    transition?: TransitionProp
-    handleDisableScroll?: boolean
-    disableDrag?: boolean
-    modal?: boolean
-    zIndex?: number
-    portalProps?: PortalProps
-    /**
-     * 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'
->
+export type SheetScopes = string
+
+export type SheetScopedProps<P> = Omit<P, 'scope'> & {
+  scope?: SheetScopes
+}
+
+export type SheetProps = SheetScopedProps<{
+  open?: boolean
+  defaultOpen?: boolean
+  onOpenChange?: OpenChangeHandler
+
+  /**
+   * Control the index of the position in the `snapPoints` array
+   */
+  position?: number
+
+  /**
+   * Initial position from the `snapPoints` array
+   */
+  defaultPosition?: number
+
+  /**
+   * Array of pixels or percents the Sheet will attempt to move to when dragged.
+   * The first is the topmost and default when first opened via open prop.
+   */
+  snapPoints?: (string | number)[]
+
+  snapPointsMode?: SnapPointsMode
+  onPositionChange?: PositionChangeHandler
+  children?: ReactNode
+  dismissOnOverlayPress?: boolean
+  dismissOnSnapToBottom?: boolean
+
+  /**
+   * Disables the RemoveScroll behavior that prevents body scrolling while sheet is open.
+   * By default, RemoveScroll is enabled when the sheet is open and modal.
+   */
+  disableRemoveScroll?: boolean
+
+  transitionConfig?: AnimatedNumberStrategy
+
+  /**
+   * By default Sheet will prefer the open prop over a parent component that is
+   * controlling it via Adapt. In general if you want to Adapt to a sheet, you'd
+   * leave the open prop undefined. If you'd like to have the parent override the
+   * prop you've set manually on Sheet, set this to true.
+   */
+  preferAdaptParentOpenState?: boolean
+
+  /**
+   * (experimental) Remove the children while hidden (to save some performance, but can cause issues with animations)
+   */
+  unmountChildrenWhenHidden?: boolean
+
+  /**
+   * By default a fully-closed sheet wrapper is hidden with `display: 'none'`.
+   * Set this to keep the closed wrapper laid out (e.g. for native visual effects
+   * that cannot initialize below a hidden ancestor). `pointerEvents` still gates
+   * interaction while closed.
+   */
+  disableHideWhenClosed?: boolean
+
+  /**
+   * Adapts the sheet to use native sheet on the given platform (if available)
+   * The iOS system sheet does not expose continuous position, so
+   * `Sheet.useAnimatedPosition` and `onTransition` are unavailable in this mode.
+   */
+  native?: 'ios'[] | boolean
+
+  /**
+   * Pass if you're using the CSS animation driver
+   */
+  transition?: TransitionProp
+  handleDisableScroll?: boolean
+  disableDrag?: boolean
+  modal?: boolean
+  zIndex?: number
+  portalProps?: PortalProps
+  /**
+   * 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>
+
+  /**
+   * Fires at the start and end of the sheet's position transition. `cause` is
+   * `open` when moving from closed, `close` when moving off screen, and `snap`
+   * when moving between snap points while open. On the `end` phase, `finished`
+   * is `false` when the transition was interrupted (e.g. a close canceled by a
+   * re-open). `position` is the resolved translateY (px from screen top) target.
+   * Available on Tamagui's custom Sheet, not the native iOS system sheet.
+   */
+  onTransition?: (e: SheetTransitionEvent) => void
+}>
+
+export type SheetTransitionCause = 'open' | 'close' | 'snap'
+
+export type SheetTransitionEvent = {
+  phase: 'start' | 'end'
+  cause: SheetTransitionCause
+  position: number
+  finished?: boolean
+}
 
 export type PositionChangeHandler = (position: number) => void
 
@@ -105,8 +120,6 @@ export type RemoveScrollProps = React.ComponentProps<typeof RemoveScroll>
 
 export type SnapPointsMode = 'percent' | 'constant' | 'fit' | 'mixed'
 
-export type SheetScopedProps<A> = ScopedProps<A, 'Sheet'>
-
 export type ScrollBridge = {
   enabled: boolean
   y: number
@@ -198,3 +211,20 @@ export interface KeyboardControllerSheetResult {
    */
   flushPendingHide: () => void
 }
+
+export type SheetDragSurfaceProps = {
+  /** react-native-gesture-handler is set up and owns the drag (native only) */
+  gestureHandlerEnabled: boolean
+  /** the `Gesture.Pan` to attach when gesture handler owns the drag */
+  panGesture: any
+  /** the PanResponder config to drive the drag with otherwise, null when dragging is off */
+  panConfig: PanResponderConfig | null
+  children?: ReactNode
+}
+
+export type SheetNativePlatforms = 'ios'
+
+export type SheetNativeModal = {
+  ModalSheetView: any
+  ModalSheetViewMainContent: any
+}

package/src/useKeyboardControllerSheet.native.ts

@@ -1,12 +1,12 @@
 /**
- * Native implementation of keyboard controller sheet hook.
+ * native implementation of keyboard controller sheet hook.
  *
- * Simplified to just track keyboard state (height, visibility).
- * Position animation is handled by SheetImplementationCustom via
- * keyboard-adjusted positions — matching the react-native-actions-sheet pattern.
+ * simplified to just track keyboard state (height, visibility).
+ * position animation is handled by SheetImplementationCustom via
+ * keyboard-adjusted positions, matching the react-native-actions-sheet pattern.
  *
- * Uses react-native-keyboard-controller events when available,
- * falls back to basic Keyboard API otherwise.
+ * uses React Native keyboard events for state. The optional keyboard-controller
+ * integration is only used for imperative dismissal.
  */
 
 import { useCallback, useEffect, useRef, useState } from 'react'
@@ -67,40 +67,11 @@ export function useKeyboardControllerSheet(
     }
   }, [])
 
-  // keyboard-controller event listeners (preferred when available)
-  useEffect(() => {
-    if (!enabled || !keyboardControllerEnabled) return
-
-    const { KeyboardEvents } = getKeyboardControllerState()
-    if (!KeyboardEvents?.addListener) return
-
-    const showSub = KeyboardEvents.addListener('keyboardWillShow', (e: any) => {
-      const height = e?.height ?? 0
-      if (height > 0) {
-        setKeyboardHeight(height)
-      }
-      setIsKeyboardVisible(true)
-    })
-
-    const hideSub = KeyboardEvents.addListener('keyboardWillHide', () => {
-      if (pauseKeyboardHandler.current) {
-        pendingHide.current = true
-        return
-      }
-      setIsKeyboardVisible(false)
-      setKeyboardHeight(0)
-    })
-
-    return () => {
-      showSub?.remove?.()
-      hideSub?.remove?.()
-    }
-  }, [enabled, keyboardControllerEnabled])
-
-  // fallback to basic Keyboard API when keyboard-controller not available
+  // module availability does not prove that KeyboardProvider is mounted. Its
+  // event emitter is silent without the provider, while React Native's keyboard
+  // notifications are available in both configurations.
   useEffect(() => {
     if (!enabled) return
-    if (keyboardControllerEnabled) return
 
     const showEvent = Platform.OS === 'ios' ? 'keyboardWillShow' : 'keyboardDidShow'
     const hideEvent = Platform.OS === 'ios' ? 'keyboardWillHide' : 'keyboardDidHide'
@@ -123,7 +94,7 @@ export function useKeyboardControllerSheet(
       showListener.remove()
       hideListener.remove()
     }
-  }, [enabled, keyboardControllerEnabled])
+  }, [enabled])
 
   return {
     keyboardControllerEnabled,