@tamagui/sheet 2.0.0-1769233344020 → 2.0.0-1769288527117

package/src/useGestureHandlerPan.tsx

@@ -0,0 +1,312 @@
+import { useCallback, useMemo, useRef, type RefObject } from 'react'
+import { getGestureHandlerState, isGestureHandlerEnabled } from './gestureState'
+import type { ScrollBridge } from './types'
+
+// threshold in pixels for considering sheet "at top" position
+// allows for small measurement variations
+const AT_TOP_THRESHOLD = 5
+
+interface GesturePanConfig {
+  positions: number[]
+  frameSize: number
+  setPosition: (pos: number) => void
+  animateTo: (pos: number) => void
+  stopSpring: () => void
+  scrollBridge: ScrollBridge
+  setIsDragging: (val: boolean) => void
+  getCurrentPosition: () => number
+  resisted: (val: number, minY: number) => number
+  disableDrag?: boolean
+  isShowingInnerSheet?: boolean
+  // set the animated position directly (for smooth dragging)
+  setAnimatedPosition: (val: number) => void
+  // ref to scroll gesture for simultaneousWithExternalGesture
+  scrollGestureRef?: RefObject<any> | null
+}
+
+interface GesturePanResult {
+  panGesture: any | null
+  panGestureRef: RefObject<any>
+  gestureHandlerEnabled: boolean
+}
+
+/**
+ * Hook that creates a Gesture.Pan() handler for use with react-native-gesture-handler.
+ * This provides native-quality gesture coordination between Sheet and ScrollView.
+ *
+ * Uses state-based decision pattern (like gorhom/bottom-sheet and react-native-actions-sheet):
+ * - Both pan and scroll gestures run simultaneously
+ * - In onChange, we decide whether to process pan or let scroll handle it
+ * - scrollBridge.setScrollEnabled toggles scroll on/off as needed
+ *
+ * Decision matrix:
+ * 1. Sheet not fully open + swiping up -> pan handles (disable scroll)
+ * 2. Sheet fully open + swiping up -> scroll handles (blockPan)
+ * 3. Sheet not fully open + swiping down -> pan handles (unless scrolled)
+ * 4. Sheet fully open + swiping down + scrollY=0 -> pan handles
+ * 5. Sheet fully open + swiping down + scrollY>0 -> scroll handles (blockPan)
+ *
+ * Returns null for the gesture if RNGH is not available or drag is disabled.
+ */
+export function useGestureHandlerPan(config: GesturePanConfig): GesturePanResult {
+  const {
+    positions,
+    frameSize,
+    setPosition,
+    animateTo,
+    stopSpring,
+    scrollBridge,
+    setIsDragging,
+    getCurrentPosition,
+    resisted,
+    disableDrag,
+    isShowingInnerSheet,
+    setAnimatedPosition,
+    scrollGestureRef,
+  } = config
+
+  const gestureHandlerEnabled = isGestureHandlerEnabled()
+  const panGestureRef = useRef<any>(null)
+
+  // use refs for values that need to persist across gesture lifecycle
+  // (useMemo closure variables get reset when gesture is recreated)
+  const gestureStateRef = useRef({
+    startY: 0,
+    // track last translation when pan was active (for position calculation after handoff)
+    lastPanTranslationY: 0,
+    // accumulated position offset from all pan movements
+    accumulatedOffset: 0,
+    // track previous translation for direction detection (like actions-sheet)
+    prevTranslationY: 0,
+    // track if scroll was engaged (scrollY > 0) at some point
+    scrollEngaged: false,
+  })
+
+  const onStart = useCallback(() => {
+    stopSpring()
+    setIsDragging(true)
+  }, [stopSpring, setIsDragging])
+
+  const onEnd = useCallback(
+    (closestPoint: number) => {
+      setIsDragging(false)
+      scrollBridge.setParentDragging(false)
+      // re-enable scroll when gesture ends
+      scrollBridge.setScrollEnabled?.(true)
+      setPosition(closestPoint)
+      animateTo(closestPoint)
+    },
+    [setIsDragging, scrollBridge, setPosition, animateTo]
+  )
+
+  const panGesture = useMemo(() => {
+    // don't create gesture if disabled or RNGH not available
+    if (!gestureHandlerEnabled || disableDrag || isShowingInnerSheet || !frameSize) {
+      return null
+    }
+
+    const { Gesture } = getGestureHandlerState()
+    if (!Gesture) {
+      return null
+    }
+
+    const minY = positions[0]
+    const gs = gestureStateRef.current // shorthand
+
+    // simultaneousHandlers pattern from react-native-actions-sheet
+    // both gestures run simultaneously, we use blockPan to decide who handles
+    // console.warn('[RNGH-Pan] CREATING gesture, minY:', minY, 'frameSize:', frameSize)
+    const gesture = Gesture.Pan()
+      .withRef(panGestureRef)
+      // NO manualActivation - let both gestures run via simultaneousHandlers
+      .failOffsetX([-20, 20])
+      .shouldCancelWhenOutside(false)
+      .onBegin(() => {
+        // check position at gesture begin - before direction is known
+        const pos = getCurrentPosition()
+        const atTop = pos <= minY + AT_TOP_THRESHOLD
+        const currentScrollY = scrollBridge.y
+        // console.warn('[RNGH-Pan] onBegin', { pos, minY, atTop, currentScrollY })
+        gs.startY = pos
+        gs.lastPanTranslationY = 0
+        gs.accumulatedOffset = 0
+        gs.prevTranslationY = 0
+        gs.scrollEngaged = currentScrollY > 0 // track if scroll is already engaged
+
+        // if sheet not at top, DISABLE SCROLL immediately and lock to 0
+        // this prevents scroll from firing before pan takes over
+        if (!atTop) {
+          scrollBridge.setScrollEnabled?.(false, 0)
+        }
+      })
+      .onStart(() => {
+        // console.warn('[RNGH-Pan] onStart', { startY: gs.startY, minY })
+        scrollBridge.initialPosition = gs.startY
+        onStart()
+      })
+      .onChange((event: { translationY: number; velocityY: number }) => {
+        const { translationY } = event
+
+        // determine direction by comparing translations (like react-native-actions-sheet)
+        // this is more reliable than velocity which can be noisy during direction changes
+        const isSwipingDown = gs.prevTranslationY < translationY
+        const deltaY = translationY - gs.prevTranslationY
+        gs.prevTranslationY = translationY
+
+        const scrollY = scrollBridge.y
+        // track if scroll has been engaged at some point (needed for handoff detection)
+        if (scrollY > 0) {
+          gs.scrollEngaged = true
+        }
+
+        // calculate current sheet position based on accumulated offset
+        const currentPos = gs.startY + gs.accumulatedOffset
+        const isCurrentlyAtTop = currentPos <= minY + AT_TOP_THRESHOLD
+        const nodeIsScrolling = scrollY > 0
+
+        // console.warn('[RNGH-Pan] onChange', { translationY: translationY.toFixed(1), deltaY: deltaY.toFixed(1), currentPos: currentPos.toFixed(1), minY, isCurrentlyAtTop, isSwipingDown, scrollY, scrollEngaged: gs.scrollEngaged })
+
+        // decision matrix (from react-native-actions-sheet pattern)
+        // each frame, decide who handles the movement based on current state
+        //
+        // Key insight: we track accumulated offset separately from translation
+        // This allows seamless handoffs between pan and scroll
+        let panHandles = false
+
+        // BUG #1 FIX: Check if scroll content is actually scrollable
+        // If content doesn't fill the ScrollView, gestures should pass through to sheet
+        const hasScrollableContent = scrollBridge.hasScrollableContent !== false
+
+        if (!isCurrentlyAtTop) {
+          // sheet not at top position
+          if (isSwipingDown) {
+            // swiping down while sheet not at top
+            // BUG #1 FIX: if content not scrollable, pan always handles
+            // only scroll if scrollY > 0 AND content is scrollable, otherwise pan handles
+            panHandles = !nodeIsScrolling || !hasScrollableContent
+          } else {
+            // swiping up while sheet not at top -> pan drags sheet up
+            panHandles = true
+          }
+        } else {
+          // sheet is at top position
+          if (isSwipingDown) {
+            // swiping down at top
+            if (nodeIsScrolling && hasScrollableContent) {
+              // scroll > 0 and content scrollable, let scroll handle (scroll back towards 0)
+              panHandles = false
+            } else if (gs.scrollEngaged && hasScrollableContent) {
+              // scroll WAS > 0 but now is 0 -> handoff from scroll to pan
+              // pan takes over to drag sheet down
+              // console.warn('[RNGH-Pan] *** HANDOFF FROM SCROLL TO PAN ***')
+              panHandles = true
+            } else {
+              // scroll never engaged OR content not scrollable, just drag sheet down
+              panHandles = true
+            }
+          } else {
+            // swiping up at top
+            // if there's scrollable content, let scroll handle so user can scroll into content
+            // resistance only applies when there's NO scrollable content
+            if (hasScrollableContent) {
+              // content is scrollable - let scroll handle (user wants to scroll down into content)
+              panHandles = false
+            } else {
+              // no scrollable content -> pan handles for resistance effect
+              panHandles = true
+            }
+          }
+        }
+
+        // console.warn('[RNGH-Pan] decision', { panHandles, isCurrentlyAtTop, isSwipingDown, nodeIsScrolling, scrollEngaged: gs.scrollEngaged, hasScrollableContent, currentPos: currentPos.toFixed(1), minY })
+
+        if (panHandles) {
+          // pan handles - disable scroll and move sheet
+          // when not at top: lock scroll to 0 (sheet is being dragged)
+          // when at top: lock at current position (handoff from scroll to pan)
+          const lockTo = isCurrentlyAtTop ? undefined : 0
+          scrollBridge.setScrollEnabled?.(false, lockTo)
+
+          // accumulate the delta for position calculation
+          gs.accumulatedOffset += deltaY
+          const newPosition = resisted(gs.startY + gs.accumulatedOffset, minY)
+
+          // update position
+          scrollBridge.paneY = newPosition
+          setAnimatedPosition(newPosition)
+          scrollBridge.setParentDragging(newPosition > minY)
+        } else {
+          // scroll handles - enable scroll so it can move freely
+          scrollBridge.setScrollEnabled?.(true)
+          // don't accumulate offset when scroll is handling
+        }
+      })
+      .onEnd((event: { velocityY: number }) => {
+        const { velocityY } = event
+        const currentPos = gs.startY + gs.accumulatedOffset
+
+        // console.warn('[RNGH-Pan] onEnd', { velocityY, currentPos, accumulatedOffset: gs.accumulatedOffset, scrollY: scrollBridge.y })
+
+        // clear scroll lock
+        scrollBridge.scrollLockY = undefined
+
+        // if sheet is at top and scroll is engaged, just stay at top
+        if (currentPos <= minY + AT_TOP_THRESHOLD && scrollBridge.y > 0) {
+          onEnd(0)
+          return
+        }
+
+        // find closest snap point using current position and velocity
+        const velocity = velocityY / 1000
+        const projectedEnd = currentPos + frameSize * velocity * 0.2
+
+        let closestPoint = 0
+        let minDist = Number.POSITIVE_INFINITY
+
+        for (let i = 0; i < positions.length; i++) {
+          const pos = positions[i]
+          const dist = Math.abs(projectedEnd - pos)
+          if (dist < minDist) {
+            minDist = dist
+            closestPoint = i
+          }
+        }
+
+        onEnd(closestPoint)
+      })
+      .onFinalize(() => {
+        // console.warn('[RNGH-Pan] onFinalize')
+        // clear scroll lock on finalize too (safety)
+        scrollBridge.scrollLockY = undefined
+      })
+      .runOnJS(true)
+
+    // if we have a scroll gesture ref, make pan simultaneous with it
+    // this allows both gestures to run and we decide in onChange who handles it
+    if (scrollGestureRef?.current) {
+      // console.warn('[RNGH-Pan] adding simultaneousWithExternalGesture for scroll')
+      return gesture.simultaneousWithExternalGesture(scrollGestureRef.current)
+    }
+
+    return gesture
+  }, [
+    gestureHandlerEnabled,
+    disableDrag,
+    isShowingInnerSheet,
+    frameSize,
+    positions,
+    scrollBridge,
+    getCurrentPosition,
+    resisted,
+    onStart,
+    onEnd,
+    setIsDragging,
+    setAnimatedPosition,
+  ])
+
+  return {
+    panGesture,
+    panGestureRef,
+    gestureHandlerEnabled,
+  }
+}

package/types/GestureDetectorWrapper.d.ts

@@ -0,0 +1,14 @@
+import type React from 'react';
+import { type ViewStyle } from 'react-native';
+interface GestureDetectorWrapperProps {
+    gesture: any;
+    children: React.ReactNode;
+    style?: ViewStyle;
+}
+/**
+ * Conditionally wraps children with GestureDetector when RNGH is available.
+ * Uses a plain View wrapper that GestureDetector can attach gesture handlers to.
+ */
+export declare function GestureDetectorWrapper({ gesture, children, style, }: GestureDetectorWrapperProps): import("react/jsx-runtime").JSX.Element;
+export {};
+//# sourceMappingURL=GestureDetectorWrapper.d.ts.map

package/types/GestureDetectorWrapper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GestureDetectorWrapper.d.ts","sourceRoot":"","sources":["../src/GestureDetectorWrapper.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAC9B,OAAO,EAAQ,KAAK,SAAS,EAAE,MAAM,cAAc,CAAA;AAGnD,UAAU,2BAA2B;IACnC,OAAO,EAAE,GAAG,CAAA;IACZ,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAA;IACzB,KAAK,CAAC,EAAE,SAAS,CAAA;CAClB;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,EACrC,OAAO,EACP,QAAQ,EACR,KAAK,GACN,EAAE,2BAA2B,2CAsB7B"}

package/types/GestureDetectorWrapper.native.d.ts

@@ -0,0 +1,14 @@
+import React from 'react';
+interface GestureDetectorWrapperProps {
+    gesture: any;
+    children: React.ReactNode;
+}
+/**
+ * Conditionally wraps children with GestureDetector when RNGH is available.
+ * Falls back to just rendering children when RNGH is not set up.
+ *
+ * @platform native
+ */
+export declare function GestureDetectorWrapper({ gesture, children, }: GestureDetectorWrapperProps): import("react/jsx-runtime").JSX.Element;
+export {};
+//# sourceMappingURL=GestureDetectorWrapper.native.d.ts.map

package/types/GestureSheetContext.d.ts

@@ -0,0 +1,36 @@
+import type React from 'react';
+import { 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;
+}
+export declare function useGestureSheetContext(): GestureSheetContextValue | null;
+export interface GestureSheetProviderProps {
+    children: React.ReactNode;
+    isDragging: boolean;
+    blockPan: boolean;
+    setBlockPan: (blocked: boolean) => void;
+    panGesture: any | null;
+    panGestureRef: RefObject<any> | null;
+}
+export declare function GestureSheetProvider({ children, isDragging, blockPan, setBlockPan, panGesture, panGestureRef, }: GestureSheetProviderProps): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=GestureSheetContext.d.ts.map

package/types/GestureSheetContext.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GestureSheetContext.d.ts","sourceRoot":"","sources":["../src/GestureSheetContext.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAC9B,OAAO,EAA6B,KAAK,SAAS,EAAE,MAAM,OAAO,CAAA;AAEjE,MAAM,WAAW,wBAAwB;IACvC;;;OAGG;IACH,UAAU,EAAE,GAAG,GAAG,IAAI,CAAA;IACtB;;OAEG;IACH,aAAa,EAAE,SAAS,CAAC,GAAG,CAAC,GAAG,IAAI,CAAA;IACpC;;OAEG;IACH,UAAU,EAAE,OAAO,CAAA;IACnB;;OAEG;IACH,WAAW,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,CAAA;IACvC;;OAEG;IACH,QAAQ,EAAE,OAAO,CAAA;CAClB;AAID,wBAAgB,sBAAsB,IAAI,wBAAwB,GAAG,IAAI,CAExE;AAED,MAAM,WAAW,yBAAyB;IACxC,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAA;IACzB,UAAU,EAAE,OAAO,CAAA;IACnB,QAAQ,EAAE,OAAO,CAAA;IACjB,WAAW,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,CAAA;IACvC,UAAU,EAAE,GAAG,GAAG,IAAI,CAAA;IACtB,aAAa,EAAE,SAAS,CAAC,GAAG,CAAC,GAAG,IAAI,CAAA;CACrC;AAED,wBAAgB,oBAAoB,CAAC,EACnC,QAAQ,EACR,UAAU,EACV,QAAQ,EACR,WAAW,EACX,UAAU,EACV,aAAa,GACd,EAAE,yBAAyB,2CAY3B"}

package/types/SheetImplementationCustom.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SheetImplementationCustom.d.ts","sourceRoot":"","sources":["../src/SheetImplementationCustom.tsx"],"names":[],"mappings":"AAmBA,OAAO,KAAmB,MAAM,OAAO,CAAA;AAOvC,OAAO,EAAsC,IAAI,EAAE,MAAM,cAAc,CAAA;AAIvE,OAAO,KAAK,EAAc,cAAc,EAAE,MAAM,SAAS,CAAA;AAWzD,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;;;;;;;;;;;;;;;8BAgkBrC,CAAA"}
+{"version":3,"file":"SheetImplementationCustom.d.ts","sourceRoot":"","sources":["../src/SheetImplementationCustom.tsx"],"names":[],"mappings":"AAmBA,OAAO,KAAmB,MAAM,OAAO,CAAA;AAOvC,OAAO,EAAsC,IAAI,EAAE,MAAM,cAAc,CAAA;AAMvE,OAAO,KAAK,EAAc,cAAc,EAAE,MAAM,SAAS,CAAA;AAYzD,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;;;;;;;;;;;;;;;8BA+nBrC,CAAA"}

package/types/SheetScrollView.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SheetScrollView.d.ts","sourceRoot":"","sources":["../src/SheetScrollView.tsx"],"names":[],"mappings":"AAKA,OAAO,KAAsC,MAAM,OAAO,CAAA;AAC1D,OAAO,KAAK,EAAE,UAAU,IAAI,YAAY,EAAE,MAAM,cAAc,CAAA;AAY9D,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;wCAiQ3B,CAAA"}
+{"version":3,"file":"SheetScrollView.d.ts","sourceRoot":"","sources":["../src/SheetScrollView.tsx"],"names":[],"mappings":"AAKA,OAAO,KAAsC,MAAM,OAAO,CAAA;AAC1D,OAAO,KAAK,EAAE,UAAU,IAAI,YAAY,EAAE,MAAM,cAAc,CAAA;AAc9D,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;wCAoZ3B,CAAA"}

package/types/gestureState.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Re-export gesture state from @tamagui/native.
+ * Sheet uses this for backward compatibility with existing code.
+ */
+import { type GestureState } from '@tamagui/native';
+export type { GestureState as GestureHandlerState } from '@tamagui/native';
+export declare function isGestureHandlerEnabled(): boolean;
+export declare function getGestureHandlerState(): GestureState;
+export declare function setGestureHandlerState(updates: Partial<GestureState>): void;
+export declare const setGestureState: typeof setGestureHandlerState;
+//# sourceMappingURL=gestureState.d.ts.map

package/types/gestureState.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gestureState.d.ts","sourceRoot":"","sources":["../src/gestureState.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAqB,KAAK,YAAY,EAAE,MAAM,iBAAiB,CAAA;AAEtE,YAAY,EAAE,YAAY,IAAI,mBAAmB,EAAE,MAAM,iBAAiB,CAAA;AAG1E,wBAAgB,uBAAuB,IAAI,OAAO,CAEjD;AAED,wBAAgB,sBAAsB,IAAI,YAAY,CAErD;AAED,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,OAAO,CAAC,YAAY,CAAC,GAAG,IAAI,CAE3E;AAGD,eAAO,MAAM,eAAe,+BAAyB,CAAA"}

package/types/gestureState.native.d.ts

@@ -0,0 +1,12 @@
+import type { PanGesture } from 'react-native-gesture-handler';
+export type GestureHandlerState = {
+    enabled: boolean;
+    GestureDetector: any | null;
+    Gesture: any | null;
+};
+export declare function setGestureHandlerState(newState: GestureHandlerState): void;
+export declare function getGestureHandlerState(): GestureHandlerState;
+export declare function isGestureHandlerEnabled(): boolean;
+export declare function createPanGesture(): PanGesture | null;
+export declare function getGestureDetector(): any | null;
+//# sourceMappingURL=gestureState.native.d.ts.map

package/types/setupGestureHandler.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Legacy setup - prefer `import '@tamagui/native/setup-gesture-handler'` instead.
+ */
+export declare function isGestureHandlerEnabled(): boolean;
+export interface SetupGestureHandlerConfig {
+    Gesture: any;
+    GestureDetector: any;
+    ScrollView?: any;
+}
+export declare function setupGestureHandler(config: SetupGestureHandlerConfig): void;
+//# sourceMappingURL=setupGestureHandler.d.ts.map

package/types/setupGestureHandler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"setupGestureHandler.d.ts","sourceRoot":"","sources":["../src/setupGestureHandler.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,wBAAgB,uBAAuB,IAAI,OAAO,CAEjD;AAED,MAAM,WAAW,yBAAyB;IACxC,OAAO,EAAE,GAAG,CAAA;IACZ,eAAe,EAAE,GAAG,CAAA;IACpB,UAAU,CAAC,EAAE,GAAG,CAAA;CACjB;AAED,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,yBAAyB,GAAG,IAAI,CAiB3E"}

package/types/setupGestureHandler.native.d.ts

@@ -0,0 +1,41 @@
+export interface GestureHandlerConfig {
+    /**
+     * The Gesture object from react-native-gesture-handler
+     * Used to create Pan, Native, and other gesture types
+     */
+    Gesture: any;
+    /**
+     * The GestureDetector component from react-native-gesture-handler
+     * Used to wrap components that should respond to gestures
+     */
+    GestureDetector: any;
+}
+/**
+ * Sets up native gesture handler support for Sheet.
+ * Call this function early in your app (e.g., in index.js) to enable smooth
+ * gesture coordination between Sheet and ScrollView on iOS.
+ *
+ * When enabled, Sheet uses react-native-gesture-handler's simultaneousHandlers
+ * for native-quality gesture coordination. Without this setup, Sheet falls back
+ * to React Native's PanResponder which has minor limitations on iOS.
+ *
+ * @example
+ * ```tsx
+ * import { setupGestureHandler } from '@tamagui/sheet/setup-gesture-handler'
+ * import { Gesture, GestureDetector, GestureHandlerRootView } from 'react-native-gesture-handler'
+ *
+ * // Call once at app startup
+ * setupGestureHandler({ Gesture, GestureDetector })
+ *
+ * // Wrap your app with GestureHandlerRootView
+ * export default function App() {
+ *   return (
+ *     <GestureHandlerRootView style={{ flex: 1 }}>
+ *       <YourApp />
+ *     </GestureHandlerRootView>
+ *   )
+ * }
+ * ```
+ */
+export declare function setupGestureHandler(config: GestureHandlerConfig): void;
+//# sourceMappingURL=setupGestureHandler.native.d.ts.map

package/types/types.d.ts

@@ -89,6 +89,14 @@ export type ScrollBridge = {
     onParentDragging: (props: (val: boolean) => void) => () => void;
     setParentDragging: (val: boolean) => void;
     onFinishAnimate?: () => void;
+    blockPan?: boolean;
+    initialPosition?: number;
+    isScrollablePositionLocked?: boolean;
+    setScrollEnabled?: (enabled: boolean, lockTo?: number) => void;
+    _lastTouchY?: number;
+    scrollLockY?: number;
+    forceScrollTo?: (y: number) => void;
+    isAtTop?: boolean;
 };
 export {};
 //# sourceMappingURL=types.d.ts.map

package/types/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.tsx"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.tsx"],"names":[],"mappings":"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"}

package/types/useGestureHandlerPan.d.ts

@@ -0,0 +1,43 @@
+import { type RefObject } from 'react';
+import type { ScrollBridge } from './types';
+interface GesturePanConfig {
+    positions: number[];
+    frameSize: number;
+    setPosition: (pos: number) => void;
+    animateTo: (pos: number) => void;
+    stopSpring: () => void;
+    scrollBridge: ScrollBridge;
+    setIsDragging: (val: boolean) => void;
+    getCurrentPosition: () => number;
+    resisted: (val: number, minY: number) => number;
+    disableDrag?: boolean;
+    isShowingInnerSheet?: boolean;
+    setAnimatedPosition: (val: number) => void;
+    scrollGestureRef?: RefObject<any> | null;
+}
+interface GesturePanResult {
+    panGesture: any | null;
+    panGestureRef: RefObject<any>;
+    gestureHandlerEnabled: boolean;
+}
+/**
+ * Hook that creates a Gesture.Pan() handler for use with react-native-gesture-handler.
+ * This provides native-quality gesture coordination between Sheet and ScrollView.
+ *
+ * Uses state-based decision pattern (like gorhom/bottom-sheet and react-native-actions-sheet):
+ * - Both pan and scroll gestures run simultaneously
+ * - In onChange, we decide whether to process pan or let scroll handle it
+ * - scrollBridge.setScrollEnabled toggles scroll on/off as needed
+ *
+ * Decision matrix:
+ * 1. Sheet not fully open + swiping up -> pan handles (disable scroll)
+ * 2. Sheet fully open + swiping up -> scroll handles (blockPan)
+ * 3. Sheet not fully open + swiping down -> pan handles (unless scrolled)
+ * 4. Sheet fully open + swiping down + scrollY=0 -> pan handles
+ * 5. Sheet fully open + swiping down + scrollY>0 -> scroll handles (blockPan)
+ *
+ * Returns null for the gesture if RNGH is not available or drag is disabled.
+ */
+export declare function useGestureHandlerPan(config: GesturePanConfig): GesturePanResult;
+export {};
+//# sourceMappingURL=useGestureHandlerPan.d.ts.map

package/types/useGestureHandlerPan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useGestureHandlerPan.d.ts","sourceRoot":"","sources":["../src/useGestureHandlerPan.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAgC,KAAK,SAAS,EAAE,MAAM,OAAO,CAAA;AAEpE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA;AAM3C,UAAU,gBAAgB;IACxB,SAAS,EAAE,MAAM,EAAE,CAAA;IACnB,SAAS,EAAE,MAAM,CAAA;IACjB,WAAW,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAA;IAClC,SAAS,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAA;IAChC,UAAU,EAAE,MAAM,IAAI,CAAA;IACtB,YAAY,EAAE,YAAY,CAAA;IAC1B,aAAa,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,IAAI,CAAA;IACrC,kBAAkB,EAAE,MAAM,MAAM,CAAA;IAChC,QAAQ,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,MAAM,CAAA;IAC/C,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB,mBAAmB,CAAC,EAAE,OAAO,CAAA;IAE7B,mBAAmB,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAA;IAE1C,gBAAgB,CAAC,EAAE,SAAS,CAAC,GAAG,CAAC,GAAG,IAAI,CAAA;CACzC;AAED,UAAU,gBAAgB;IACxB,UAAU,EAAE,GAAG,GAAG,IAAI,CAAA;IACtB,aAAa,EAAE,SAAS,CAAC,GAAG,CAAC,CAAA;IAC7B,qBAAqB,EAAE,OAAO,CAAA;CAC/B;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,gBAAgB,GAAG,gBAAgB,CAqQ/E"}

package/types/useGestureHandlerPan.native.d.ts

@@ -0,0 +1,33 @@
+import type { PanGesture } from 'react-native-gesture-handler';
+import type { ScrollBridge } from './types';
+interface GesturePanConfig {
+    positions: number[];
+    frameSize: number;
+    setPosition: (pos: number) => void;
+    animateTo: (pos: number) => void;
+    stopSpring: () => void;
+    scrollBridge: ScrollBridge;
+    setIsDragging: (val: boolean) => void;
+    getCurrentPosition: () => number;
+    resisted: (val: number, minY: number) => number;
+    hasScrollView: boolean;
+    disableDrag?: boolean;
+    isShowingInnerSheet?: boolean;
+}
+interface GesturePanResult {
+    panGesture: PanGesture | null;
+    panGestureRef: React.RefObject<PanGesture | null>;
+    gestureHandlerEnabled: boolean;
+}
+/**
+ * Hook that creates a Gesture.Pan() handler for use with react-native-gesture-handler.
+ * This provides native-quality gesture coordination between Sheet and ScrollView.
+ *
+ * Based on patterns from react-native-actions-sheet and gorhom/bottom-sheet.
+ *
+ * @platform native - This hook only returns a gesture on native platforms.
+ * On web, it returns null for the gesture.
+ */
+export declare function useGestureHandlerPan(config: GesturePanConfig): GesturePanResult;
+export {};
+//# sourceMappingURL=useGestureHandlerPan.native.d.ts.map