@tamagui/sheet 2.7.7 → 3.0.0-beta.1091.1

package/src/Sheet.tsx

@@ -1,59 +1,78 @@
-import { styled } from '@tamagui/core'
+import { AdaptCapabilities, useAdaptContext, useAdaptIsActive } from '@tamagui/adapt'
+import { useComposedRefs } from '@tamagui/compose-refs'
+import { isWeb } from '@tamagui/constants'
+import {
+  createRefComponent,
+  createStyledHOC,
+  styled,
+  View,
+  type TamaguiElement,
+  type ViewProps,
+} from '@tamagui/core'
+import { composeEventHandlers, withStaticProperties } from '@tamagui/helpers'
+import { resolveViewZIndex } from '@tamagui/portal'
+import { RemoveScroll } from '@tamagui/remove-scroll'
 import { XStack, YStack } from '@tamagui/stacks'
+import { useDidFinishSSR } from '@tamagui/use-did-finish-ssr'
+import { StackZIndexContext } from '@tamagui/z-index-stack'
+import type { FunctionComponent, Ref } from 'react'
+import { useContext, useEffect, useMemo, useRef } from 'react'
+import type { View as RNView } from '@tamagui/react-native-types'
+import {
+  SHEET_BACKGROUND_NAME,
+  SHEET_CONTAINER_NAME,
+  SHEET_HANDLE_NAME,
+  SHEET_OVERLAY_MARKER,
+  SHEET_OVERLAY_NAME,
+} from './constants'
+import { getNativeSheet } from './nativeSheet'
+import {
+  SheetOverlayLayerContext,
+  useAnimatedPosition,
+  useSheetContext,
+} from './SheetContext'
+import { SheetImplementationCustom } from './SheetImplementationCustom'
+import { SheetScrollView } from './SheetScrollView'
+import type { SheetProps, SheetScopedProps } from './types'
+import { useSheetController } from './useSheetController'
+import { useSheetOffscreenSize } from './useSheetOffscreenSize'
+import { getMaxViewportHeight } from './webViewport'
 
-import { SHEET_HANDLE_NAME, SHEET_NAME, SHEET_OVERLAY_NAME } from './constants'
-import { createSheet } from './createSheet'
-
-export { createSheetScope } from './SheetContext'
 export * from './types'
 
-/* -------------------------------------------------------------------------------------------------
- * SheetHandle
- * -----------------------------------------------------------------------------------------------*/
+type SheetStyleShorthandProps = {
+  h?: ViewProps['height']
+  o?: ViewProps['opacity']
+  pos?: ViewProps['position']
+}
+
+type SheetViewProps<ExtraProps extends object = {}> = SheetScopedProps<
+  ViewProps & SheetStyleShorthandProps & ExtraProps
+>
 
-export const Handle = styled(XStack, {
-  name: SHEET_HANDLE_NAME,
+const SheetHandleFrame = styled(XStack, {
+  displayName: SHEET_HANDLE_NAME,
 
+  // the behavior Handle ships no opacity rules; open/close aesthetics (fade in
+  // when open, dim when idle) live in the copied skin. see the canonical skin.
   variants: {
     open: {
       true: {
-        opacity: 1,
         pointerEvents: 'auto',
       },
       false: {
-        opacity: 0,
         pointerEvents: 'none',
       },
     },
-
-    unstyled: {
-      false: {
-        height: 10,
-        borderRadius: 100,
-        backgroundColor: '$background',
-        zIndex: 10,
-        marginHorizontal: '35%',
-        marginBottom: '$2',
-        opacity: 0.5,
-
-        hoverStyle: {
-          opacity: 0.7,
-        },
-      },
-    },
   } as const,
-
-  defaultVariants: {
-    unstyled: process.env.TAMAGUI_HEADLESS === '1',
-  },
 })
 
-/* -------------------------------------------------------------------------------------------------
- * SheetOverlay
- * -----------------------------------------------------------------------------------------------*/
-
-export const Overlay = styled(YStack, {
-  name: SHEET_OVERLAY_NAME,
+const SheetOverlayFrame = styled(YStack, {
+  displayName: SHEET_OVERLAY_NAME,
+  inset: 0,
+  position: 'absolute',
+  zIndex: 100_000 - 1,
+  pointerEvents: 'auto',
 
   variants: {
     open: {
@@ -64,51 +83,269 @@ export const Overlay = styled(YStack, {
         pointerEvents: 'none',
       },
     },
-
-    unstyled: {
-      false: {
-        fullscreen: true,
-        position: 'absolute',
-        backgroundColor: '$background',
-        zIndex: 100_000 - 1,
-        pointerEvents: 'auto',
-      },
-    },
   } as const,
+})
+
+Object.assign(SheetOverlayFrame.staticConfig, { [SHEET_OVERLAY_MARKER]: true })
 
-  defaultVariants: {
-    unstyled: process.env.TAMAGUI_HEADLESS === '1',
-  },
+const SheetContainerFrame = styled(YStack, {
+  displayName: SHEET_CONTAINER_NAME,
+  flex: 1,
+  position: 'relative',
+  zIndex: 0,
+  width: '100%',
+  maxHeight: '100%',
 })
 
-/* -------------------------------------------------------------------------------------------------
- * Sheet
- * -----------------------------------------------------------------------------------------------*/
+const SheetBackgroundFrame = styled(YStack, {
+  displayName: SHEET_BACKGROUND_NAME,
+  position: 'absolute',
+  top: 0,
+  left: 0,
+  right: 0,
+  zIndex: -1,
+  pointerEvents: 'none',
+})
 
-export const Frame = styled(YStack, {
-  name: SHEET_NAME,
+export const SheetHandle = createStyledHOC(
+  SheetHandleFrame,
+  ({ scope, ...props }: SheetViewProps, forwardedRef) => {
+    const context = useSheetContext(scope)
+    const composedRef = useComposedRefs<TamaguiElement>(context.handleRef, forwardedRef)
+    const wasDraggingRef = useRef(false)
 
-  variants: {
-    unstyled: {
-      false: {
-        flex: 1,
-        backgroundColor: '$background',
-        borderTopLeftRadius: '$true',
-        borderTopRightRadius: '$true',
-        width: '100%',
-        maxHeight: '100%',
-        overflow: 'hidden',
-      },
-    },
-  } as const,
+    useEffect(() => {
+      if (!context.scrollBridge) return
+      return context.scrollBridge.onParentDragging((isDragging: boolean) => {
+        if (isDragging) {
+          wasDraggingRef.current = true
+        }
+      })
+    }, [context.scrollBridge])
 
-  defaultVariants: {
-    unstyled: process.env.TAMAGUI_HEADLESS === '1',
-  },
-})
+    if (context.onlyShowContainer) {
+      return null
+    }
+
+    return (
+      <SheetHandleFrame
+        ref={composedRef}
+        onPressIn={() => {
+          wasDraggingRef.current = false
+        }}
+        onPress={() => {
+          if (wasDraggingRef.current) {
+            wasDraggingRef.current = false
+            return
+          }
+          const max = context.snapPoints.length + (context.dismissOnSnapToBottom ? -1 : 0)
+          const nextPos = (context.position + 1) % max
+          context.setPosition(nextPos)
+        }}
+        open={context.open}
+        {...props}
+      />
+    )
+  }
+)
+
+export const SheetOverlay = createStyledHOC(
+  SheetOverlayFrame,
+  (propsIn: SheetViewProps, ref) => {
+    const { scope, ...props } = propsIn
+    const context = useSheetContext(scope)
+    const isInOverlayLayer = useContext(SheetOverlayLayerContext)
+    const didWarn = useRef(false)
+
+    if (context.onlyShowContainer) {
+      return null
+    }
+
+    if (!isInOverlayLayer) {
+      if (process.env.NODE_ENV === 'development' && !didWarn.current) {
+        didWarn.current = true
+        console.error(
+          'Sheet.Overlay must be a direct child of Sheet. Move it next to Sheet.Handle and Sheet.Container.'
+        )
+      }
+
+      return null
+    }
+
+    return (
+      <SheetOverlayFrame
+        {...props}
+        ref={ref}
+        onPress={composeEventHandlers(
+          props.onPress,
+          context.dismissOnOverlayPress
+            ? () => {
+                context.setOpen(false)
+              }
+            : undefined
+        )}
+      />
+    )
+  }
+)
+
+type ExtraContainerProps = {
+  /**
+   * Adds padding accounting for the currently offscreen content, so if you put a flex element inside
+   * the sheet, it will always flex to the height of the visible amount of the sheet. If this is not
+   * turned on, the inner content is always set to the max height of the sheet.
+   */
+  adjustPaddingForOffscreenContent?: boolean
+}
+
+export const SheetContainer = createStyledHOC(
+  SheetContainerFrame,
+  (
+    {
+      scope,
+      adjustPaddingForOffscreenContent,
+      children,
+      ...props
+    }: SheetViewProps<ExtraContainerProps>,
+    forwardedRef
+  ) => {
+    const context = useSheetContext(scope)
+    const { hasFit, disableRemoveScroll, frameSize, contentRef, open } = context
+    const composedContentRef = useComposedRefs(forwardedRef, contentRef)
+    const offscreenSize = useSheetOffscreenSize(context)
+    const stableFrameSize = useRef(frameSize)
+
+    useEffect(() => {
+      if (open && frameSize) {
+        stableFrameSize.current = frameSize
+      }
+    }, [open, frameSize])
+
+    const sheetContents = useMemo(() => {
+      const shouldUseFixedHeight = hasFit && !open && stableFrameSize.current
+
+      return (
+        <SheetContainerFrame
+          ref={composedContentRef}
+          flex={hasFit && open ? 0 : 1}
+          flexBasis={hasFit ? 'auto' : undefined}
+          height={
+            shouldUseFixedHeight
+              ? stableFrameSize.current
+              : hasFit
+                ? undefined
+                : frameSize
+          }
+          pointerEvents={open ? 'auto' : 'none'}
+          data-state={open ? 'open' : 'closed'}
+          {...props}
+        >
+          <StackZIndexContext zIndex={resolveViewZIndex(props.zIndex)}>
+            {children}
+          </StackZIndexContext>
+
+          {adjustPaddingForOffscreenContent && (
+            <View data-sheet-offscreen-pad height={offscreenSize} width="100%" />
+          )}
+        </SheetContainerFrame>
+      )
+    }, [open, props, frameSize, offscreenSize, adjustPaddingForOffscreenContent, hasFit])
+
+    return (
+      <RemoveScroll enabled={!disableRemoveScroll && context.open}>
+        {sheetContents}
+      </RemoveScroll>
+    )
+  }
+)
+
+type ExtraBackgroundProps = {
+  /**
+   * Disables the default background extension below the sheet. Leave this off
+   * when a spring can overshoot on open so page content never shows through.
+   */
+  disableHideBottomOverflow?: boolean
+}
+
+export const SheetBackground = createStyledHOC(
+  SheetBackgroundFrame,
+  (
+    { scope, disableHideBottomOverflow, ...props }: SheetViewProps<ExtraBackgroundProps>,
+    forwardedRef
+  ) => {
+    const context = useSheetContext(scope)
+    const bottomOverflow = isWeb
+      ? Math.max(context.frameSize, getMaxViewportHeight())
+      : context.frameSize
+
+    return (
+      <SheetBackgroundFrame
+        ref={forwardedRef}
+        data-sheet-background=""
+        bottom={disableHideBottomOverflow ? 0 : -bottomOverflow}
+        {...props}
+      />
+    )
+  }
+)
+
+export const SheetRoot = createRefComponent<RNView, SheetProps>(
+  function SheetRoot(props, ref) {
+    const hydrated = useDidFinishSSR()
+    const isAdapted = useAdaptIsActive()
+    const adaptContext = useAdaptContext()
+    const { isShowingNonSheet } = useSheetController(props.scope)
+    const shouldUseAdapt = Boolean(
+      adaptContext.open !== undefined || adaptContext.onOpenChange
+    )
+    const isShowingAdaptNonSheet =
+      shouldUseAdapt && !adaptContext.active && adaptContext.open
+
+    let SheetImplementation = SheetImplementationCustom
+
+    if (props.native) {
+      // null unless this is ios and the app registered a native sheet
+      const impl = getNativeSheet('ios')
+      if (impl) {
+        // @ts-expect-error accepting external sheet implementation
+        SheetImplementation = impl
+      }
+    }
+
+    if (isShowingAdaptNonSheet || isShowingNonSheet || !hydrated) {
+      return null
+    }
+
+    const implementation = <SheetImplementation ref={ref} {...props} />
+
+    return isAdapted ? (
+      <AdaptCapabilities scroll overlay dismiss>
+        {implementation}
+      </AdaptCapabilities>
+    ) : (
+      implementation
+    )
+  }
+)
+
+const sheetParts = {
+  Container: SheetContainer,
+  Background: SheetBackground,
+  Overlay: SheetOverlay,
+  Handle: SheetHandle,
+  ScrollView: SheetScrollView,
+}
+
+export const SheetControlled = withStaticProperties(
+  SheetRoot as unknown as FunctionComponent<
+    Omit<SheetProps, 'open' | 'onOpenChange'> & { ref?: Ref<RNView> }
+  >,
+  sheetParts
+)
 
-export const Sheet = createSheet({
-  Frame,
-  Handle,
-  Overlay,
+export const Sheet = withStaticProperties(SheetRoot, {
+  Root: SheetRoot,
+  Controlled: SheetControlled,
+  useAnimatedPosition,
+  ...sheetParts,
 })

package/src/SheetContext.tsx

@@ -1,11 +1,61 @@
-import { createContextScope } from '@tamagui/create-context'
+import { createStyledContext, type UniversalAnimatedNumber } from '@tamagui/core'
+import React from 'react'
 
-import { SHEET_NAME } from './constants'
 import type { SheetContextValue } from './useSheetProviderProps'
 
-export const [createSheetContext, createSheetScope] = createContextScope(SHEET_NAME)
+export const SheetContext = createStyledContext<SheetContextValue>({}, 'Sheet__')
 
-export const [SheetProvider, useSheetContext] = createSheetContext<SheetContextValue>(
-  SHEET_NAME,
-  {} as any
-)
+export const { Provider: SheetProvider, useStyledContext: useSheetContext } = SheetContext
+
+export const SheetOverlayLayerContext = React.createContext(false)
+
+// the UIKit system sheet does not expose the continuous position that powers
+// Sheet.useAnimatedPosition. mark that implementation separately so the hook
+// can explain how to opt back into the custom Sheet instead of claiming the
+// caller is outside Sheet entirely.
+export const SheetNativeSystemContext = React.createContext(false)
+
+export type SheetAnimatedPositionContextValue = {
+  // the exact animated number driving the frame's translateY (px from screen
+  // top). drive drag-linked effects off this via useAnimatedNumberStyle.
+  value: UniversalAnimatedNumber<any>
+  // height of the viewport the sheet positions against
+  screenSize: number
+  // measured height of the sheet frame
+  frameSize: number
+  // resolved px positions (translateY) matching snapPoints order
+  snapOffsets: number[]
+  // the top-most (fully open) position
+  minY: number
+}
+
+export const SheetAnimatedPositionContext =
+  React.createContext<SheetAnimatedPositionContextValue | null>(null)
+
+/**
+ * Read the sheet's live animated position. Call inside a `Sheet` to build
+ * drag-linked effects (e.g. an overlay fade) on the public animation hooks:
+ *
+ * ```tsx
+ * const { value, screenSize } = Sheet.useAnimatedPosition()
+ * const style = useAnimatedNumberStyle(value, (y) => {
+ *   'worklet'
+ *   return { opacity: Math.max(0, 0.5 * (1 - y / screenSize)) }
+ * })
+ * ```
+ */
+export function useAnimatedPosition(): SheetAnimatedPositionContextValue {
+  const context = React.useContext(SheetAnimatedPositionContext)
+  const isNativeSystemSheet = React.useContext(SheetNativeSystemContext)
+  if (!context) {
+    if (isNativeSystemSheet) {
+      throw new Error(
+        "Sheet.useAnimatedPosition() is unavailable when Sheet uses the native iOS system sheet because UIKit does not expose its continuous position. Remove the `native` prop to use Tamagui's custom Sheet and animated position hooks."
+      )
+    }
+    throw new Error(
+      'Sheet.useAnimatedPosition() must be used inside a <Sheet>. Render the component that calls it as a child of Sheet.'
+    )
+  }
+  return context
+}

package/src/SheetController.tsx

@@ -8,13 +8,14 @@ import { SheetControllerContext } from './useSheetController'
 export const SheetController = ({
   children,
   onOpenChange: onOpenChangeProp,
-  onAnimationComplete: onAnimationCompleteProp,
+  onTransition: onTransitionProp,
   open,
   hidden,
   disableDrag,
-}: Partial<SheetControllerContextValue> & { children?: ReactNode }) => {
+  scope = '',
+}: Partial<SheetControllerContextValue> & { children?: ReactNode; scope?: string }) => {
   const onOpenChange = useEvent(onOpenChangeProp)
-  const onAnimationComplete = useEvent(onAnimationCompleteProp)
+  const onTransition = useEvent(onTransitionProp)
   const id = useId()
 
   // track hidden transitions to signal adapt handoff
@@ -33,14 +34,14 @@ export const SheetController = ({
       hidden,
       disableDrag,
       onOpenChange,
-      onAnimationComplete,
+      onTransition,
       skipNextAnimation,
     }),
-    [id, onOpenChange, onAnimationComplete, open, hidden, disableDrag, skipNextAnimation]
+    [id, onOpenChange, onTransition, open, hidden, disableDrag, skipNextAnimation]
   )
 
   return (
-    <SheetControllerContext.Provider value={memoValue}>
+    <SheetControllerContext.Provider scope={scope} {...memoValue}>
       {children}
     </SheetControllerContext.Provider>
   )

package/src/SheetDragSurface.native.tsx

@@ -0,0 +1,42 @@
+import * as React from 'react'
+import { PanResponder, View } from 'react-native'
+
+import { getGestureHandlerState } from './gestureState'
+import type { SheetDragSurfaceProps } from './types'
+
+/**
+ * The surface the sheet is dragged by.
+ *
+ * With react-native-gesture-handler set up the drag is a `Gesture.Pan`, which
+ * needs a native View of its own to attach to. Without it the drag runs on
+ * PanResponder, the same as web.
+ */
+export function SheetDragSurface({
+  gestureHandlerEnabled,
+  panGesture,
+  panConfig,
+  children,
+}: SheetDragSurfaceProps) {
+  const { GestureDetector } = getGestureHandlerState()
+
+  const panHandlers = React.useMemo(
+    () => (panConfig ? PanResponder.create(panConfig).panHandlers : undefined),
+    [panConfig]
+  )
+
+  if (gestureHandlerEnabled && panGesture && GestureDetector) {
+    return (
+      <GestureDetector gesture={panGesture}>
+        <View style={{ flex: 1 }} collapsable={false}>
+          {children}
+        </View>
+      </GestureDetector>
+    )
+  }
+
+  return (
+    <View {...panHandlers} style={{ flex: 1, width: '100%', height: '100%' }}>
+      {children}
+    </View>
+  )
+}

package/src/SheetDragSurface.tsx

@@ -0,0 +1,40 @@
+import type { TamaguiElement } from '@tamagui/core'
+import { View } from '@tamagui/core'
+import { PanResponder } from '@tamagui/react-native-pan-responder'
+import { useResponderEvents } from '@tamagui/react-native-use-responder-events'
+import * as React from 'react'
+
+import type { SheetDragSurfaceProps } from './types'
+
+/**
+ * The surface the sheet is dragged by.
+ *
+ * Web runs the same PanResponder react-native does, over the same responder
+ * system, so the drag behaves as it did when this was a react-native `View`.
+ * `gestureHandler` is native-only, so the props for it are ignored here.
+ */
+export function SheetDragSurface({ panConfig, children }: SheetDragSurfaceProps) {
+  const ref = React.useRef<TamaguiElement>(null)
+
+  const panHandlers = React.useMemo(
+    () => (panConfig ? PanResponder.create(panConfig).panHandlers : undefined),
+    [panConfig]
+  )
+
+  const { onClickCapture, ...responderHandlers } = panHandlers ?? {}
+  useResponderEvents(ref, responderHandlers)
+
+  // onClickCapture is a DOM prop: tamagui forwards it to the element untouched
+  // but only types react-native's prop surface
+  const domProps = { onClickCapture } as Record<string, unknown>
+
+  return (
+    // flexBasis auto, like the container frame: under the web style compat
+    // `flex={1}` means a basis of 0, which collapses this surface inside the
+    // animated wrapper (that wrapper has no height of its own in fit mode), and
+    // a collapsed surface leaves the frame unmeasured and parked off-screen
+    <View ref={ref} {...domProps} flex={1} flexBasis="auto" width="100%" height="100%">
+      {children}
+    </View>
+  )
+}