@tamagui/sheet 2.0.0-1769200478218 → 2.0.0-1769256574467

package/src/GestureSheetContext.tsx

@@ -0,0 +1,62 @@
+import type React from 'react'
+import { createContext, useContext, type RefObject } from 'react'
+
+export interface GestureSheetContextValue {
+  /**
+   * The sheet's pan gesture object, used for simultaneousHandlers
+   * in ScrollView to coordinate gestures
+   */
+  panGesture: any | null
+  /**
+   * Ref to the pan gesture for simultaneousHandlers prop
+   */
+  panGestureRef: RefObject<any> | null
+  /**
+   * Whether the sheet is currently being dragged by the user
+   */
+  isDragging: boolean
+  /**
+   * Set whether panning should be blocked (e.g., when scrolling)
+   */
+  setBlockPan: (blocked: boolean) => void
+  /**
+   * Whether pan gesture is currently blocked
+   */
+  blockPan: boolean
+}
+
+const GestureSheetContext = createContext<GestureSheetContextValue | null>(null)
+
+export function useGestureSheetContext(): GestureSheetContextValue | null {
+  return useContext(GestureSheetContext)
+}
+
+export interface GestureSheetProviderProps {
+  children: React.ReactNode
+  isDragging: boolean
+  blockPan: boolean
+  setBlockPan: (blocked: boolean) => void
+  panGesture: any | null
+  panGestureRef: RefObject<any> | null
+}
+
+export function GestureSheetProvider({
+  children,
+  isDragging,
+  blockPan,
+  setBlockPan,
+  panGesture,
+  panGestureRef,
+}: GestureSheetProviderProps) {
+  const value: GestureSheetContextValue = {
+    panGesture,
+    panGestureRef,
+    isDragging,
+    blockPan,
+    setBlockPan,
+  }
+
+  return (
+    <GestureSheetContext.Provider value={value}>{children}</GestureSheetContext.Provider>
+  )
+}

package/src/SheetImplementationCustom.tsx

@@ -26,9 +26,12 @@ import type {
 } from 'react-native'
 import { Dimensions, Keyboard, PanResponder, View } from 'react-native'
 import { ParentSheetContext, SheetInsideSheetContext } from './contexts'
+import { GestureDetectorWrapper } from './GestureDetectorWrapper'
+import { GestureSheetProvider } from './GestureSheetContext'
 import { resisted } from './helpers'
 import { SheetProvider } from './SheetContext'
 import type { SheetProps, SnapPointsMode } from './types'
+import { useGestureHandlerPan } from './useGestureHandlerPan'
 import { useSheetOpenState } from './useSheetOpenState'
 import { useSheetProviderProps } from './useSheetProviderProps'
 
@@ -131,18 +134,16 @@ export const SheetImplementationCustom = React.forwardRef<View, SheetProps>(
       }
     }, [open, frameSize])
 
+    // use stableFrameSize when closing to prevent position jumps during exit animation
+    // but when opening, always use the current frameSize so positions update correctly
+    const effectiveFrameSize = open ? frameSize : stableFrameSize.current || frameSize
+
     const positions = React.useMemo(
       () =>
         snapPoints.map((point) =>
-          // FIX: Use stable frameSize when closing to prevent position jumps
-          getYPositions(
-            snapPointsMode,
-            point,
-            screenSize,
-            open ? frameSize : stableFrameSize.current
-          )
+          getYPositions(snapPointsMode, point, screenSize, effectiveFrameSize)
         ),
-      [screenSize, frameSize, snapPoints, snapPointsMode, open]
+      [screenSize, effectiveFrameSize, snapPoints, snapPointsMode]
     )
 
     const { useAnimatedNumber, useAnimatedNumberStyle, useAnimatedNumberReaction } =
@@ -182,8 +183,25 @@ export const SheetImplementationCustom = React.forwardRef<View, SheetProps>(
         (value) => {
           at.current = value
           scrollBridge.paneY = value
+          // update isAtTop for scroll enable/disable
+          // positions[0] is the top snap point (minY)
+          const minY = positions[0]
+          const wasAtTop = scrollBridge.isAtTop
+          const nowAtTop = value <= minY + 5
+          if (wasAtTop !== nowAtTop) {
+            scrollBridge.isAtTop = nowAtTop
+            // when reaching top, enable scroll; when leaving top, disable scroll
+            // this preemptively sets scroll state before any gestures start
+            if (nowAtTop) {
+              scrollBridge.scrollLockY = undefined
+              scrollBridge.setScrollEnabled?.(true)
+            } else {
+              scrollBridge.scrollLockY = 0
+              scrollBridge.setScrollEnabled?.(false)
+            }
+          }
         },
-        [animationDriver]
+        [animationDriver, positions]
       )
     )
 
@@ -251,11 +269,26 @@ export const SheetImplementationCustom = React.forwardRef<View, SheetProps>(
         scrollBridge.scrollLock = false
         scrollBridge.scrollStartY = -1
       }
+
+      // set initial isAtTop state when sheet opens
+      // position 0 = top snap point, so isAtTop = true
+      if (open && position >= 0) {
+        const isTopPosition = position === 0
+        scrollBridge.isAtTop = isTopPosition
+        if (isTopPosition) {
+          scrollBridge.scrollLockY = undefined
+          scrollBridge.setScrollEnabled?.(true)
+        } else {
+          scrollBridge.scrollLockY = 0
+          scrollBridge.setScrollEnabled?.(false)
+        }
+      }
     }, [hasntMeasured, disableAnimation, isHidden, frameSize, screenSize, open, position])
 
     const disableDrag = props.disableDrag ?? controller?.disableDrag
     const themeName = useThemeName()
     const [isDragging, setIsDragging] = React.useState(false)
+    const [blockPan, setBlockPan] = React.useState(false)
 
     const panResponder = React.useMemo(() => {
       if (disableDrag) return
@@ -414,6 +447,26 @@ export const SheetImplementationCustom = React.forwardRef<View, SheetProps>(
       })
     }, [disableDrag, isShowingInnerSheet, animateTo, frameSize, positions, setPosition])
 
+    // gesture handler hook for RNGH-based gesture coordination
+    const { panGesture, panGestureRef, gestureHandlerEnabled } = useGestureHandlerPan({
+      positions,
+      frameSize,
+      setPosition,
+      animateTo,
+      stopSpring,
+      scrollBridge,
+      setIsDragging,
+      getCurrentPosition: () => at.current,
+      resisted,
+      disableDrag,
+      isShowingInnerSheet,
+      setAnimatedPosition: (val: number) => {
+        // directly set the animated value for smooth dragging
+        // console.warn('[RNGH-Sheet] setAnimatedPosition:', val.toFixed(1))
+        animatedNumber.setValue(val, { type: 'direct' })
+      },
+    })
+
     const handleAnimationViewLayout = React.useCallback(
       (e: LayoutChangeEvent) => {
         // FIX: Don't update frameSize during exit animation to prevent position jumps
@@ -523,52 +576,65 @@ export const SheetImplementationCustom = React.forwardRef<View, SheetProps>(
       <LayoutMeasurementController disable={!open}>
         <ParentSheetContext.Provider value={nextParentContext}>
           <SheetProvider {...providerProps} setHasScrollView={setHasScrollView}>
-            <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}
-              {...panResponder?.panHandlers}
-              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 ? opacity : 0,
-                  ...((shouldHideParentSheet || !open) && {
-                    pointerEvents: 'none',
-                  }),
-                },
-                animatedStyle,
-              ]}
+            <GestureSheetProvider
+              isDragging={isDragging}
+              blockPan={blockPan}
+              setBlockPan={setBlockPan}
+              panGesture={panGesture}
+              panGestureRef={panGestureRef}
             >
-              {/* <AdaptProvider>{props.children}</AdaptProvider> */}
-              {props.children}
-            </AnimatedView>
+              <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}
+                {...(!gestureHandlerEnabled && panResponder?.panHandlers)}
+                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 ? opacity : 0,
+                    ...((shouldHideParentSheet || !open) && {
+                      pointerEvents: 'none',
+                    }),
+                  },
+                  animatedStyle,
+                ]}
+              >
+                {gestureHandlerEnabled && panGesture ? (
+                  <GestureDetectorWrapper gesture={panGesture} style={{ flex: 1 }}>
+                    {props.children}
+                  </GestureDetectorWrapper>
+                ) : (
+                  props.children
+                )}
+              </AnimatedView>
+            </GestureSheetProvider>
           </SheetProvider>
         </ParentSheetContext.Provider>
       </LayoutMeasurementController>
@@ -623,7 +689,9 @@ function getYPositions(
   screenSize?: number,
   frameSize?: number
 ) {
-  if (!screenSize || !frameSize) return 0
+  if (!screenSize || !frameSize) {
+    return 0
+  }
 
   if (mode === 'mixed') {
     if (typeof point === 'number') {
@@ -638,8 +706,7 @@ function getYPositions(
         console.warn('Invalid snapPoint percentage string')
         return 0
       }
-      const next = Math.round(screenSize - pct * screenSize)
-      return next
+      return Math.round(screenSize - pct * screenSize)
     }
     console.warn('Invalid snapPoint unknown value')
     return 0

package/src/SheetScrollView.tsx

@@ -5,10 +5,12 @@ 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'
 import type { SheetScopedProps } from './types'
 
-// TODO ideally would replicate https://github.com/ammarahm-ed/react-native-actions-sheet/blob/master/src/index.tsx
+// uses react-native-gesture-handler's simultaneousWithExternalGesture for native-quality coordination
 
 /* -------------------------------------------------------------------------------------------------
  * SheetScrollView
@@ -33,6 +35,7 @@ export const SheetScrollView = React.forwardRef<
     ref
   ) => {
     const context = useSheetContext(SHEET_SCROLL_VIEW_NAME, __scopeSheet)
+    const gestureContext = useGestureSheetContext()
     const { scrollBridge, setHasScrollView } = context
     const [scrollEnabled, setScrollEnabled_] = useControllableState({
       prop: scrollEnabledProp,
@@ -40,16 +43,71 @@ export const SheetScrollView = React.forwardRef<
     })
     const scrollRef = React.useRef<RNScrollView | null>(null)
 
+    // get the pan gesture ref for simultaneousHandlers
+    // react-native-actions-sheet pattern: pass panGestureRef to ScrollView's simultaneousHandlers
+    const panGestureRef = gestureContext?.panGestureRef
+
+    // get RNGH ScrollView from gestureState (passed via setupGestureHandler to avoid double registration)
+    const { ScrollView: RNGHScrollView } = getGestureHandlerState()
+
+    // determine which ScrollView component to use - need RNGH ScrollView for simultaneousHandlers
+    const useRNGHScrollView = isGestureHandlerEnabled() && RNGHScrollView && panGestureRef
+
+    // console.warn('[RNGH-Scroll] Setup:', {
+    //   enabled: isGestureHandlerEnabled(),
+    //   hasRNGHScrollView: !!RNGHScrollView,
+    //   hasPanRef: !!panGestureRef,
+    //   useRNGHScrollView
+    // })
+
     // could make it so it has negative bottom margin and then pads the bottom content
     // to avoid clipping effect when resizing smaller
     // or more ideally could use context to register if it has a scrollview and change behavior
     // const offscreenSize = useSheetOffscreenSize(context)
 
-    const setScrollEnabled = (next: boolean) => {
-      scrollRef.current?.setNativeProps?.({
-        scrollEnabled: next,
+    // actions-sheet pattern: track scroll offset continuously via ref
+    // this is updated on EVERY scroll event so it's always current
+    const currentScrollOffset = useRef(0)
+    // the position to lock at when scroll is disabled
+    const lockedScrollY = useRef(0)
+
+    const setScrollEnabled = (next: boolean, lockTo?: number) => {
+      // console.warn('[RNGH-Scroll] setScrollEnabled', next, 'currentOffset:', currentScrollOffset.current, 'lockTo:', lockTo)
+      if (!next) {
+        // locking scroll - freeze at specified position or CURRENT position
+        // if lockTo is provided (e.g., 0), use that; otherwise freeze at current
+        // key insight: we use currentScrollOffset which is updated every onScroll
+        // this ensures we freeze at the actual position, not a stale value
+        const lockY = lockTo ?? currentScrollOffset.current
+        lockedScrollY.current = lockY
+        scrollBridge.scrollLockY = lockY
+        // console.warn('[RNGH-Scroll] LOCKING at', lockY)
+        // immediately scroll to lock position
+        scrollRef.current?.scrollTo?.({
+          x: 0,
+          y: lockY,
+          animated: false,
+        })
+      } else {
+        // unlocking - save current position before clearing lock
+        lockedScrollY.current = currentScrollOffset.current
+        scrollBridge.scrollLockY = undefined
+        // console.warn('[RNGH-Scroll] UNLOCKING at', lockedScrollY.current)
+      }
+      // NOTE: intentionally NOT using setNativeProps or scrollEnabled state
+      // because that kills the RNGH scroll gesture mid-touch, breaking handoff.
+      // This is the react-native-actions-sheet pattern: both gestures run,
+      // we use scrollLockY + scrollTo to "freeze" scroll position during pan.
+    }
+
+    // force scroll to specific position (called from pan gesture to compensate for async props)
+    const forceScrollTo = (y: number) => {
+      // console.warn('[RNGH-Scroll] forceScrollTo:', y)
+      scrollRef.current?.scrollTo?.({
+        x: 0,
+        y,
+        animated: false,
       })
-      setScrollEnabled_(next)
     }
 
     const state = React.useRef({
@@ -62,8 +120,21 @@ export const SheetScrollView = React.forwardRef<
 
     useEffect(() => {
       setHasScrollView(true)
+
+      // register setScrollEnabled on scrollBridge for RNGH coordination
+      if (isGestureHandlerEnabled()) {
+        scrollBridge.setScrollEnabled = setScrollEnabled
+        scrollBridge.forceScrollTo = forceScrollTo
+      }
+
       return () => {
         setHasScrollView(false)
+        if (scrollBridge.setScrollEnabled) {
+          scrollBridge.setScrollEnabled = undefined
+        }
+        if (scrollBridge.forceScrollTo) {
+          scrollBridge.forceScrollTo = undefined
+        }
       }
     }, [])
 
@@ -149,7 +220,84 @@ export const SheetScrollView = React.forwardRef<
       scrollBridge.hasScrollableContent = hasScrollableContent
     }, [hasScrollableContent])
 
-    return (
+    // Use RNGH ScrollView with simultaneousHandlers for native-quality gesture coordination
+    // Pattern from react-native-actions-sheet: pass panGestureRef to simultaneousHandlers
+    if (useRNGHScrollView && RNGHScrollView && panGestureRef) {
+      const RNGHComponent = RNGHScrollView as any
+      // console.warn('[RNGH-Scroll] RENDER with simultaneousHandlers')
+      return (
+        <RNGHComponent
+          ref={composeRefs(scrollRef as any, ref)}
+          style={{ flex: 1 }}
+          scrollEventThrottle={1}
+          scrollEnabled={scrollable}
+          simultaneousHandlers={[panGestureRef]}
+          onLayout={(e: any) => {
+            parentHeight.current = Math.ceil(e.nativeEvent.layout.height)
+            setIsScrollable()
+          }}
+          onScroll={(e: any) => {
+            const { y } = e.nativeEvent.contentOffset
+
+            // actions-sheet pattern: ALWAYS track current offset
+            // this ensures setScrollEnabled knows the exact current position
+            currentScrollOffset.current = y
+
+            // if scroll is locked, force it back to lock position
+            if (scrollBridge.scrollLockY !== undefined) {
+              if (y !== scrollBridge.scrollLockY) {
+                scrollRef.current?.scrollTo?.({
+                  x: 0,
+                  y: scrollBridge.scrollLockY,
+                  animated: false,
+                })
+              }
+              // still update bridge y to the lock position for consistency
+              scrollBridge.y = scrollBridge.scrollLockY
+              // fire callback but with locked position (for UI updates)
+              const lockedEvent = {
+                ...e,
+                nativeEvent: {
+                  ...e.nativeEvent,
+                  contentOffset: {
+                    ...e.nativeEvent.contentOffset,
+                    y: scrollBridge.scrollLockY,
+                  },
+                },
+              }
+              onScroll?.(lockedEvent)
+              return
+            }
+
+            // console.warn('[RNGH-Scroll] y:', y)
+            scrollBridge.y = y
+            if (y > 0) {
+              scrollBridge.scrollStartY = -1
+            }
+            onScroll?.(e)
+          }}
+          contentContainerStyle={{ minHeight: '100%' }}
+          bounces={false}
+          {...props}
+        >
+          {/* content height measurer */}
+          <View
+            position="absolute"
+            inset={0}
+            pointerEvents="none"
+            zIndex={-1}
+            onLayout={(e) => {
+              contentHeight.current = Math.floor(e.nativeEvent.layout.height)
+              setIsScrollable()
+            }}
+          />
+          {children}
+        </RNGHComponent>
+      )
+    }
+
+    // Fallback: regular Tamagui ScrollView for web or when RNGH not available
+    const content = (
       <ScrollView
         onLayout={(e) => {
           parentHeight.current = Math.ceil(e.nativeEvent.layout.height)
@@ -157,7 +305,7 @@ export const SheetScrollView = React.forwardRef<
         }}
         ref={composeRefs(scrollRef as any, ref)}
         flex={1}
-        scrollEventThrottle={8}
+        scrollEventThrottle={1}
         onResponderRelease={release}
         className="_ovs-contain"
         scrollEnabled={scrollable}
@@ -175,7 +323,6 @@ export const SheetScrollView = React.forwardRef<
             scrollBridge.scrollStartY = -1
           }
 
-          // Process the "onScroll" prop here if any
           onScroll?.(e)
 
           // This assures that we do not skip the "scrollBridge" values processing
@@ -272,5 +419,7 @@ export const SheetScrollView = React.forwardRef<
         {children}
       </ScrollView>
     )
+
+    return content
   }
 )

package/src/gestureState.ts

@@ -0,0 +1,17 @@
+/**
+ * Re-export gesture state from @tamagui/native.
+ * Sheet uses this for backward compatibility with existing code.
+ */
+
+export {
+  isGestureHandlerEnabled,
+  getGestureHandlerState,
+} from '@tamagui/native'
+
+export type { GestureState as GestureHandlerState } from '@tamagui/native'
+
+// re-export setGestureHandlerState for backward compat with setupGestureHandler
+export { setGestureHandlerState } from '@tamagui/native'
+
+// alias for backward compatibility
+export { setGestureHandlerState as setGestureState } from '@tamagui/native'

package/src/setupGestureHandler.ts

@@ -0,0 +1,32 @@
+/**
+ * Legacy setup - prefer `import '@tamagui/native/setup-gesture-handler'` instead.
+ */
+
+import { setGestureHandlerState, isGestureHandlerEnabled } from '@tamagui/native'
+
+export { isGestureHandlerEnabled }
+
+export interface SetupGestureHandlerConfig {
+  Gesture: any
+  GestureDetector: any
+  ScrollView?: any
+}
+
+export function setupGestureHandler(config: SetupGestureHandlerConfig): void {
+  const g = globalThis as any
+  if (g.__tamagui_sheet_gesture_handler_setup) {
+    return
+  }
+  g.__tamagui_sheet_gesture_handler_setup = true
+
+  const { Gesture, GestureDetector, ScrollView } = config
+
+  if (Gesture && GestureDetector) {
+    setGestureHandlerState({
+      enabled: true,
+      Gesture,
+      GestureDetector,
+      ScrollView: ScrollView || null,
+    })
+  }
+}

package/src/types.tsx

@@ -109,4 +109,19 @@ export type ScrollBridge = {
   onParentDragging: (props: (val: boolean) => void) => () => void
   setParentDragging: (val: boolean) => void
   onFinishAnimate?: () => void
+  // gesture handler state for RNGH integration
+  blockPan?: boolean
+  initialPosition?: number
+  isScrollablePositionLocked?: boolean
+  // control scroll enabled state for RNGH coordination
+  // lockTo parameter: when disabling, lock scroll to this position (undefined = current position)
+  setScrollEnabled?: (enabled: boolean, lockTo?: number) => void
+  // track touch position for direction detection in RNGH
+  _lastTouchY?: number
+  // scroll lock position for forcing scroll back when pan handles
+  scrollLockY?: number
+  // force scroll to position (compensates for async setNativeProps)
+  forceScrollTo?: (y: number) => void
+  // whether sheet is at top position (for scroll enable/disable)
+  isAtTop?: boolean
 }