react-native-screen-transitions 3.3.0-beta.3 → 3.3.0-beta.4

package/src/shared/hooks/gestures/use-build-gestures.tsx

@@ -3,71 +3,115 @@ import { useCallback, useMemo, useRef } from "react";
 import { Gesture, type GestureType } from "react-native-gesture-handler";
 import type { SharedValue } from "react-native-reanimated";
 import type {
+	DirectionClaimMap,
 	GestureContextType,
 	ScrollConfig,
 } from "../../providers/gestures.provider";
 import { useKeys } from "../../providers/screen/keys.provider";
 import { GestureStore, type GestureStoreMap } from "../../stores/gesture.store";
+import type { ClaimedDirections, Direction } from "../../types/ownership.types";
+import { claimsAnyDirection } from "../../utils/gesture/compute-claimed-directions";
+import { resolveOwnership } from "../../utils/gesture/resolve-ownership";
 import { useScreenGestureHandlers } from "./use-screen-gesture-handlers";
 
+const DIRECTIONS: Direction[] = [
+	"vertical",
+	"vertical-inverted",
+	"horizontal",
+	"horizontal-inverted",
+];
+
+/**
+ * Finds ancestor pan gestures that we shadow (claim the same direction).
+ * Used to block ancestors when child claims priority.
+ */
+function findShadowedAncestorPanGestures(
+	selfClaims: ClaimedDirections,
+	ancestorContext: GestureContextType | null | undefined,
+	isIsolated: boolean,
+): GestureType[] {
+	const shadowedGestures: GestureType[] = [];
+	let ancestor = ancestorContext;
+
+	while (ancestor) {
+		if (ancestor.isIsolated !== isIsolated) break;
+
+		const shadowsAncestor = DIRECTIONS.some(
+			(dir) => selfClaims[dir] && ancestor?.claimedDirections?.[dir],
+		);
+
+		if (shadowsAncestor && ancestor.panGesture) {
+			shadowedGestures.push(ancestor.panGesture);
+		}
+
+		ancestor = ancestor.ancestorContext;
+	}
+
+	return shadowedGestures;
+}
+
 interface BuildGesturesHookProps {
 	scrollConfig: SharedValue<ScrollConfig | null>;
 	ancestorContext?: GestureContextType | null;
+	claimedDirections: ClaimedDirections;
+	childDirectionClaims: SharedValue<DirectionClaimMap>;
+	isIsolated: boolean;
 }
 
+/**
+ * Builds the Pan gesture for screen dismissal.
+ *
+ * Handles shadowing: when child claims same direction as ancestor,
+ * child's pan blocks ancestor's pan via `blocksExternalGesture()`.
+ *
+ * ScrollView coordination is handled separately by useScrollRegistry,
+ * which creates its own Native gesture per ScrollView.
+ */
 export const useBuildGestures = ({
 	scrollConfig,
 	ancestorContext,
+	claimedDirections,
+	childDirectionClaims,
+	isIsolated,
 }: BuildGesturesHookProps): {
 	panGesture: GestureType;
 	panGestureRef: React.MutableRefObject<GestureType | undefined>;
-	nativeGesture: GestureType;
 	gestureAnimationValues: GestureStoreMap;
 } => {
 	const { current } = useKeys();
-
 	const navState = current.navigation.getState();
 
 	const isFirstScreen = useMemo(() => {
 		return navState.routes.findIndex((r) => r.key === current.route.key) === 0;
 	}, [navState.routes, current.route.key]);
 
-	// Ref for external gesture coordination (e.g., swipeable lists)
 	const panGestureRef = useRef<GestureType | undefined>(undefined);
-
 	const gestureAnimationValues = GestureStore.getRouteGestures(
 		current.route.key,
 	);
 
 	const { snapPoints } = current.options;
-
-	// Dismiss gesture is controlled by gestureEnabled (disabled for first screen)
 	const canDismiss = Boolean(
 		isFirstScreen ? false : current.options.gestureEnabled,
 	);
-
-	// Snap navigation works independently - enabled when snap points exist
-	// This matches iOS native sheet behavior where gestureEnabled: false
-	// disables dismiss but you can still drag between detents
 	const hasSnapPoints = Array.isArray(snapPoints) && snapPoints.length > 0;
 	const gestureEnabled = canDismiss || hasSnapPoints;
 
+	const ownershipStatus = useMemo(
+		() => resolveOwnership(claimedDirections, ancestorContext ?? null),
+		[claimedDirections, ancestorContext],
+	);
+
+	const selfClaimsAny = claimsAnyDirection(claimedDirections);
+
 	const handleDismiss = useCallback(() => {
-		// If an ancestor navigator is already dismissing, skip this dismiss to
-		// avoid racing with the ancestor
-		if (ancestorContext?.gestureAnimationValues.isDismissing?.value) {
-			return;
-		}
+		if (ancestorContext?.gestureAnimationValues.isDismissing?.value) return;
 
 		const state = current.navigation.getState();
-
 		const routeStillPresent = state.routes.some(
 			(route) => route.key === current.route.key,
 		);
-
-		if (!routeStillPresent) {
-			return;
-		}
+		if (!routeStillPresent) return;
 
 		current.navigation.dispatch({
 			...StackActions.pop(),
@@ -81,8 +125,12 @@ export const useBuildGestures = ({
 			scrollConfig,
 			canDismiss,
 			handleDismiss,
+			ownershipStatus,
 			ancestorIsDismissing:
 				ancestorContext?.gestureAnimationValues.isDismissing,
+			claimedDirections,
+			ancestorContext,
+			childDirectionClaims,
 		});
 
 	return useMemo(() => {
@@ -96,40 +144,27 @@ export const useBuildGestures = ({
 			.onUpdate(onUpdate)
 			.onEnd(onEnd);
 
-		// Native gesture setup depends on whether this screen has gestures
-		let nativeGesture: GestureType;
-
-		if (gestureEnabled) {
-			// This screen has gestures - set up normal pan/native relationship
-			nativeGesture = Gesture.Native().requireExternalGestureToFail(panGesture);
-			panGesture.blocksExternalGesture(nativeGesture);
-		} else {
-			// This screen has no gestures
-			// Find nearest ancestor with gestureEnabled=true (attached pan)
-			let activePanAncestor = ancestorContext;
-			while (activePanAncestor && !activePanAncestor.gestureEnabled) {
-				activePanAncestor = activePanAncestor.ancestorContext;
-			}
-
-			if (activePanAncestor?.panGesture) {
-				// Found an ancestor with enabled pan - wait for it
-				nativeGesture = Gesture.Native().requireExternalGestureToFail(
-					activePanAncestor.panGesture,
-				);
-			} else {
-				// No ancestor with enabled pan - plain native
-				nativeGesture = Gesture.Native();
+		// Block shadowed ancestor pan gestures when we claim same directions
+		if (selfClaimsAny) {
+			const shadowedAncestorGestures = findShadowedAncestorPanGestures(
+				claimedDirections,
+				ancestorContext,
+				isIsolated,
+			);
+			for (const ancestorPan of shadowedAncestorGestures) {
+				panGesture.blocksExternalGesture(ancestorPan);
 			}
 		}
 
 		return {
 			panGesture,
 			panGestureRef,
-			nativeGesture,
 			gestureAnimationValues,
 		};
 	}, [
 		gestureEnabled,
+		selfClaimsAny,
+		claimedDirections,
 		onTouchesDown,
 		onTouchesMove,
 		onStart,
@@ -137,5 +172,6 @@ export const useBuildGestures = ({
 		onEnd,
 		gestureAnimationValues,
 		ancestorContext,
+		isIsolated,
 	]);
 };

package/src/shared/hooks/gestures/use-screen-gesture-handlers.ts

@@ -16,17 +16,27 @@ import {
 	EPSILON,
 	FALSE,
 	GESTURE_VELOCITY_IMPACT,
+	SNAP_VELOCITY_IMPACT,
 	TRUE,
 } from "../../constants";
-import type { ScrollConfig } from "../../providers/gestures.provider";
+import type {
+	DirectionClaimMap,
+	GestureContextType,
+	ScrollConfig,
+} from "../../providers/gestures.provider";
 import { useKeys } from "../../providers/screen/keys.provider";
 import { AnimationStore } from "../../stores/animation.store";
 import { GestureStore } from "../../stores/gesture.store";
 import { GestureOffsetState } from "../../types/gesture.types";
+import type {
+	ClaimedDirections,
+	Direction,
+	DirectionOwnership,
+} from "../../types/ownership.types";
 import { animateToProgress } from "../../utils/animation/animate-to-progress";
 import {
 	applyOffsetRules,
-	checkScrollAwareActivation,
+	checkScrollBoundary,
 } from "../../utils/gesture/check-gesture-activation";
 import { determineDismissal } from "../../utils/gesture/determine-dismissal";
 import { determineSnapTarget } from "../../utils/gesture/determine-snap-target";
@@ -42,13 +52,66 @@ interface UseScreenGestureHandlersProps {
 	ancestorIsDismissing?: SharedValue<number> | null;
 	canDismiss: boolean;
 	handleDismiss: () => void;
+	ownershipStatus: DirectionOwnership;
+	claimedDirections: ClaimedDirections;
+	ancestorContext: GestureContextType | null | undefined;
+	childDirectionClaims: SharedValue<DirectionClaimMap>;
 }
 
+/**
+ * Gesture Handlers for Screen Dismissal and Snap Navigation
+ *
+ * ## Mental Model
+ *
+ * This hook implements the touch handling logic for the gesture ownership system.
+ * Each screen has a pan gesture handler that runs through this decision flow:
+ *
+ * ```
+ * onTouchesMove (for each touch move event):
+ *   1. ANCESTOR CHECK: If ancestor is dismissing → fail (avoid racing)
+ *   2. DIRECTION DETECTION: Determine swipe direction from touch delta
+ *   3. OWNERSHIP CHECK: Do we own this direction? (ownershipStatus)
+ *      - "self" → continue
+ *      - "ancestor" or null → fail (let it bubble up)
+ *   4. CHILD CLAIM CHECK: Has a child pre-registered a claim for this direction?
+ *      - Yes → fail immediately (child shadows us, no delay)
+ *      - No → continue
+ *   5. OFFSET THRESHOLD: Wait for sufficient touch movement
+ *   6. SCROLLVIEW CHECK: If touch is on ScrollView, is it at boundary?
+ *   7. EXPAND CHECK (snap sheets): If expanding via ScrollView, is expandViaScrollView enabled?
+ *   8. ACTIVATE!
+ * ```
+ *
+ * ## Key Concepts
+ *
+ * **Ownership**: Pre-computed at render time. "self" means this screen handles
+ * the direction, "ancestor" means bubble up, null means no handler exists.
+ *
+ * **Child Claims**: Registered at mount time via useEffect in gestures.provider.tsx.
+ * When a child shadows our direction, it pre-registers a claim so we know to defer.
+ * IMPORTANT: This check happens BEFORE offset threshold to ensure the parent fails
+ * immediately when shadowed, avoiding any perceptible delay.
+ * ALSO: Claims from dismissing children are ignored, allowing the parent to handle
+ * new gestures while the child is animating out.
+ *
+ * **ScrollView Boundaries**: Per spec, a ScrollView must be at its boundary before
+ * yielding to gestures. The boundary depends on sheet type:
+ * - Bottom sheet (vertical): scrollY = 0 (top)
+ * - Top sheet (vertical-inverted): scrollY >= maxY (bottom)
+ *
+ * **Snap Points**: Sheets with snapPoints claim BOTH directions on their axis
+ * (e.g., vertical sheet claims vertical AND vertical-inverted). This allows
+ * expand (drag up) and collapse/dismiss (drag down) gestures.
+ */
 export const useScreenGestureHandlers = ({
 	scrollConfig,
 	ancestorIsDismissing,
 	canDismiss,
 	handleDismiss,
+	ownershipStatus,
+	claimedDirections,
+	ancestorContext,
+	childDirectionClaims,
 }: UseScreenGestureHandlersProps) => {
 	const dimensions = useWindowDimensions();
 	const { current } = useKeys();
@@ -62,10 +125,12 @@ export const useScreenGestureHandlers = ({
 		gestureDirection = DEFAULT_GESTURE_DIRECTION,
 		gestureDrivesProgress = DEFAULT_GESTURE_DRIVES_PROGRESS,
 		gestureVelocityImpact = GESTURE_VELOCITY_IMPACT,
+		snapVelocityImpact = SNAP_VELOCITY_IMPACT,
 		gestureActivationArea = DEFAULT_GESTURE_ACTIVATION_AREA,
 		gestureResponseDistance,
 		transitionSpec,
 		snapPoints: rawSnapPoints,
+		expandViaScrollView = true,
 	} = current.options;
 
 	const { hasSnapPoints, snapPoints, minSnapPoint, maxSnapPoint } = useMemo(
@@ -147,11 +212,13 @@ export const useScreenGestureHandlers = ({
 		gestureOffsetState.value = GestureOffsetState.PENDING;
 	});
 
+	const routeKey = current.route.key;
+
 	const onTouchesMove = useStableCallbackValue(
 		(e: GestureTouchEvent, manager: GestureStateManagerType) => {
 			"worklet";
 
-			// If an ancestor navigator is already dismissing via gesture, block new gestures here.
+			// Step 1: Ancestor dismissing check
 			if (ancestorIsDismissing?.value) {
 				gestureOffsetState.value = GestureOffsetState.FAILED;
 				manager.fail();
@@ -177,79 +244,97 @@ export const useScreenGestureHandlers = ({
 				return;
 			}
 
-			// Keep pending until thresholds are met; no eager activation.
 			if (gestureAnimationValues.isDragging?.value) {
 				manager.activate();
 				return;
 			}
 
-			const recognizedDirection =
-				isSwipingDown || isSwipingUp || isSwipingRight || isSwipingLeft;
-
-			const scrollCfg = scrollConfig.value;
-			const isTouchingScrollView = scrollCfg?.isTouched ?? false;
-
-			if (!isTouchingScrollView) {
-				// Early return if gesture hasn't met activation criteria
-				const canActivate =
-					recognizedDirection &&
-					gestureOffsetState.value === GestureOffsetState.PASSED &&
-					!gestureAnimationValues.isDismissing?.value;
-
-				if (!canActivate) {
-					return;
-				}
-
-				if (isSwipingDown) {
-					gestureAnimationValues.direction.value = "vertical";
-				} else if (isSwipingUp) {
-					gestureAnimationValues.direction.value = "vertical-inverted";
-				} else if (isSwipingRight) {
-					gestureAnimationValues.direction.value = "horizontal";
-				} else if (isSwipingLeft) {
-					gestureAnimationValues.direction.value = "horizontal-inverted";
-				}
+			// Step 2: Direction detection
+			let swipeDirection: Direction | null = null;
+			if (isSwipingDown) swipeDirection = "vertical";
+			else if (isSwipingUp) swipeDirection = "vertical-inverted";
+			else if (isSwipingRight) swipeDirection = "horizontal";
+			else if (isSwipingLeft) swipeDirection = "horizontal-inverted";
 
-				manager.activate();
+			if (!swipeDirection) {
 				return;
 			}
 
-			// Touch IS on ScrollView - apply scroll-aware rules
-			// Snap mode: determine if sheet can still expand
-			// Also check targetProgress - if we're already animating toward max, scroll should win
-			const canExpandMore =
-				hasSnapPoints &&
-				animations.progress.value < maxSnapPoint - EPSILON &&
-				animations.targetProgress.value < maxSnapPoint - EPSILON;
-
-			const { shouldActivate, direction: activatedDirection } =
-				checkScrollAwareActivation({
-					swipeInfo: {
-						isSwipingDown,
-						isSwipingUp,
-						isSwipingRight,
-						isSwipingLeft,
-					},
-					directions,
-					scrollConfig: scrollCfg,
-					hasSnapPoints,
-					canExpandMore,
-				});
-
-			if (recognizedDirection && !shouldActivate) {
+			// Step 3: Ownership check - fail if we don't own this direction
+			const ownership = ownershipStatus[swipeDirection];
+			if (ownership !== "self") {
 				manager.fail();
 				return;
 			}
 
+			// Step 4: Child claim check - fail EARLY if a child shadows this direction
+			// This MUST happen before offset threshold to avoid delay when shadowing
+			// ALSO: Ignore claims from children that are currently dismissing
+			const childClaim = childDirectionClaims.value[swipeDirection];
 			if (
-				shouldActivate &&
-				gestureOffsetState.value === GestureOffsetState.PASSED &&
-				!gestureAnimationValues.isDismissing?.value
+				childClaim &&
+				childClaim.routeKey !== routeKey &&
+				!childClaim.isDismissing.value
 			) {
-				gestureAnimationValues.direction.value = activatedDirection;
-				manager.activate();
+				manager.fail();
+				return;
+			}
+
+			if (gestureOffsetState.value !== GestureOffsetState.PASSED) {
 				return;
 			}
+
+			// Snap sheets can interrupt their own animation; non-snap cannot
+			if (!hasSnapPoints && gestureAnimationValues.isDismissing?.value) {
+				return;
+			}
+
+			// Step 6: ScrollView boundary check
+			const scrollCfg = scrollConfig.value;
+			const isTouchingScrollView = scrollCfg?.isTouched ?? false;
+
+			if (isTouchingScrollView) {
+				const atBoundary = checkScrollBoundary(
+					scrollCfg,
+					swipeDirection,
+					hasSnapPoints ? directions.snapAxisInverted : undefined,
+				);
+
+				if (!atBoundary) {
+					manager.fail();
+					return;
+				}
+
+				// Step 7: Expand check for snap sheets
+				if (hasSnapPoints) {
+					const isExpandGesture =
+						(directions.snapAxisInverted && swipeDirection === "vertical") ||
+						(!directions.snapAxisInverted &&
+							swipeDirection === "vertical-inverted") ||
+						(directions.snapAxisInverted && swipeDirection === "horizontal") ||
+						(!directions.snapAxisInverted &&
+							swipeDirection === "horizontal-inverted");
+
+					if (isExpandGesture) {
+						if (!expandViaScrollView) {
+							manager.fail();
+							return;
+						}
+
+						const canExpandMore =
+							animations.progress.value < maxSnapPoint - EPSILON &&
+							animations.targetProgress.value < maxSnapPoint - EPSILON;
+
+						if (!canExpandMore) {
+							manager.fail();
+							return;
+						}
+					}
+				}
+			}
+
+			gestureAnimationValues.direction.value = swipeDirection;
+			manager.activate();
 		},
 	);
 
@@ -284,15 +369,11 @@ export const useScreenGestureHandlers = ({
 				const translation = isHorizontal ? translationX : translationY;
 				const dimension = isHorizontal ? width : height;
 
-				// Map translation to progress delta:
-				// - Positive translation (down/right) = decrease progress (dismiss)
-				// - Negative translation (up/left) = increase progress (expand)
-				// Inverted directions flip this behavior
+				// Map translation to progress: positive = dismiss, negative = expand
 				const baseSign = -1;
 				const sign = directions.snapAxisInverted ? -baseSign : baseSign;
 				const progressDelta = (sign * translation) / dimension;
 
-				// Use pre-computed bounds (minSnapPoint already accounts for canDismiss)
 				animations.progress.value = Math.max(
 					minSnapPoint,
 					Math.min(maxSnapPoint, gestureStartProgress.value + progressDelta),
@@ -343,9 +424,7 @@ export const useScreenGestureHandlers = ({
 					? dimensions.width
 					: dimensions.height;
 
-				// determineSnapTarget expects positive velocity = toward dismiss (decreasing progress)
-				// Positive velocity (down/right) = dismiss for non-inverted
-				// Inverted directions need velocity flipped
+				// Normalize velocity: positive = toward dismiss
 				const snapVelocity = directions.snapAxisInverted
 					? -axisVelocity
 					: axisVelocity;
@@ -355,6 +434,7 @@ export const useScreenGestureHandlers = ({
 					snapPoints,
 					velocity: snapVelocity,
 					dimension: axisDimension,
+					velocityFactor: snapVelocityImpact,
 					canDismiss: canDismiss,
 				});
 
@@ -381,9 +461,6 @@ export const useScreenGestureHandlers = ({
 					dimensions,
 				});
 
-				// For snap transitions, velocity should match gesture direction
-				// Positive gesture velocity (down/right) = collapsing (negative progress velocity)
-				// Inverted directions flip this
 				const velocitySign = directions.snapAxisInverted ? 1 : -1;
 				const initialVelocity =
 					velocitySign * velocity.normalize(axisVelocity, axisDimension);
@@ -404,7 +481,6 @@ export const useScreenGestureHandlers = ({
 				});
 
 				const shouldDismiss = result.shouldDismiss;
-				// Without snap points, always animate to fully visible (1) when not dismissing
 				const targetProgress = shouldDismiss ? 0 : 1;
 
 				resetGestureValues({