react-native-screen-transitions 3.0.0-rc.5 → 3.1.0

package/src/shared/__tests__/gesture-activation.test.ts

@@ -0,0 +1,251 @@
+import { describe, expect, it } from "bun:test";
+import {
+	normalizeSides,
+	computeEdgeConstraints,
+	calculateSwipeDirs,
+	shouldActivateOrFail,
+} from "../utils/gesture/check-gesture-activation";
+
+describe("normalizeSides", () => {
+	it("returns all sides as 'screen' when no area provided", () => {
+		const result = normalizeSides();
+		expect(result).toEqual({
+			left: "screen",
+			right: "screen",
+			top: "screen",
+			bottom: "screen",
+		});
+	});
+
+	it("normalizes string input to all sides", () => {
+		const result = normalizeSides("edge");
+		expect(result).toEqual({
+			left: "edge",
+			right: "edge",
+			top: "edge",
+			bottom: "edge",
+		});
+	});
+
+	it("handles per-side object input", () => {
+		const result = normalizeSides({
+			left: "edge",
+			right: "screen",
+			top: "edge",
+		});
+		expect(result).toEqual({
+			left: "edge",
+			right: "screen",
+			top: "edge",
+			bottom: "screen", // defaults to screen
+		});
+	});
+
+	it("defaults missing sides to screen", () => {
+		const result = normalizeSides({ left: "edge" });
+		expect(result.left).toBe("edge");
+		expect(result.right).toBe("screen");
+		expect(result.top).toBe("screen");
+		expect(result.bottom).toBe("screen");
+	});
+});
+
+describe("computeEdgeConstraints", () => {
+	const dimensions = { width: 375, height: 812 };
+	const allScreen = { left: "screen", right: "screen", top: "screen", bottom: "screen" } as const;
+	const allEdge = { left: "edge", right: "edge", top: "edge", bottom: "edge" } as const;
+
+	it("allows all directions when all sides are 'screen'", () => {
+		const result = computeEdgeConstraints({ x: 200, y: 400 }, dimensions, allScreen);
+		expect(result.horizontalRight).toBe(true);
+		expect(result.horizontalLeft).toBe(true);
+		expect(result.verticalDown).toBe(true);
+		expect(result.verticalUp).toBe(true);
+	});
+
+	it("restricts to left edge for horizontal-right when edge mode", () => {
+		// Touch at x=200 (center) should NOT allow right swipe with edge activation
+		const center = computeEdgeConstraints({ x: 200, y: 400 }, dimensions, allEdge);
+		expect(center.horizontalRight).toBe(false);
+
+		// Touch at x=30 (within 50px edge) should allow right swipe
+		const edge = computeEdgeConstraints({ x: 30, y: 400 }, dimensions, allEdge);
+		expect(edge.horizontalRight).toBe(true);
+	});
+
+	it("restricts to right edge for horizontal-left when edge mode", () => {
+		// Touch at x=200 (center) should NOT allow left swipe
+		const center = computeEdgeConstraints({ x: 200, y: 400 }, dimensions, allEdge);
+		expect(center.horizontalLeft).toBe(false);
+
+		// Touch at x=350 (within 50px of right edge) should allow left swipe
+		const edge = computeEdgeConstraints({ x: 350, y: 400 }, dimensions, allEdge);
+		expect(edge.horizontalLeft).toBe(true);
+	});
+
+	it("restricts to top edge for vertical-down when edge mode", () => {
+		// Touch at y=400 (center) should NOT allow down swipe
+		const center = computeEdgeConstraints({ x: 200, y: 400 }, dimensions, allEdge);
+		expect(center.verticalDown).toBe(false);
+
+		// Touch at y=100 (within 135px edge) should allow down swipe
+		const edge = computeEdgeConstraints({ x: 200, y: 100 }, dimensions, allEdge);
+		expect(edge.verticalDown).toBe(true);
+	});
+
+	it("uses custom responseDistance", () => {
+		// With custom distance of 100px
+		const result = computeEdgeConstraints({ x: 80, y: 400 }, dimensions, allEdge, 100);
+		expect(result.horizontalRight).toBe(true); // 80 < 100
+	});
+});
+
+describe("calculateSwipeDirs", () => {
+	it("detects horizontal swipe right", () => {
+		const result = calculateSwipeDirs(50, 10);
+		expect(result.isHorizontalSwipe).toBe(true);
+		expect(result.isVerticalSwipe).toBe(false);
+		expect(result.isSwipingRight).toBe(true);
+		expect(result.isSwipingLeft).toBe(false);
+	});
+
+	it("detects horizontal swipe left", () => {
+		const result = calculateSwipeDirs(-50, 10);
+		expect(result.isHorizontalSwipe).toBe(true);
+		expect(result.isSwipingLeft).toBe(true);
+		expect(result.isSwipingRight).toBe(false);
+	});
+
+	it("detects vertical swipe down", () => {
+		const result = calculateSwipeDirs(10, 50);
+		expect(result.isVerticalSwipe).toBe(true);
+		expect(result.isHorizontalSwipe).toBe(false);
+		expect(result.isSwipingDown).toBe(true);
+		expect(result.isSwipingUp).toBe(false);
+	});
+
+	it("detects vertical swipe up", () => {
+		const result = calculateSwipeDirs(10, -50);
+		expect(result.isVerticalSwipe).toBe(true);
+		expect(result.isSwipingUp).toBe(true);
+		expect(result.isSwipingDown).toBe(false);
+	});
+
+	it("horizontal wins when equal deltas", () => {
+		// When deltaX === deltaY, neither wins (both false)
+		const result = calculateSwipeDirs(50, 50);
+		expect(result.isHorizontalSwipe).toBe(false);
+		expect(result.isVerticalSwipe).toBe(false);
+	});
+});
+
+describe("shouldActivateOrFail", () => {
+	const baseParams = {
+		deltaX: 0,
+		deltaY: 0,
+		hasHorizontal: true,
+		hasVertical: true,
+		isHorizontalSwipe: false,
+		isVerticalSwipe: false,
+		allowedRight: true,
+		allowedLeft: true,
+		allowedUp: true,
+		allowedDown: true,
+		horizontalGateRight: true,
+		horizontalGateLeft: true,
+		verticalGateUp: true,
+		verticalGateDown: true,
+		isSwipingRight: false,
+		isSwipingLeft: false,
+		isSwipingUp: false,
+		isSwipingDown: false,
+	};
+
+	it("activates on valid horizontal right swipe", () => {
+		const result = shouldActivateOrFail({
+			...baseParams,
+			deltaX: 15, // above threshold (10)
+			deltaY: 5, // within tolerance (15)
+			isHorizontalSwipe: true,
+			isSwipingRight: true,
+		});
+		expect(result.shouldActivate).toBe(true);
+		expect(result.shouldFail).toBe(false);
+	});
+
+	it("activates on valid vertical down swipe", () => {
+		const result = shouldActivateOrFail({
+			...baseParams,
+			deltaX: 5, // within tolerance (20)
+			deltaY: 15, // above threshold (10)
+			isVerticalSwipe: true,
+			isSwipingDown: true,
+		});
+		expect(result.shouldActivate).toBe(true);
+		expect(result.shouldFail).toBe(false);
+	});
+
+	it("fails when swiping in disallowed direction", () => {
+		const result = shouldActivateOrFail({
+			...baseParams,
+			deltaX: 15,
+			deltaY: 5,
+			isHorizontalSwipe: true,
+			isSwipingRight: true,
+			allowedRight: false, // direction not allowed
+		});
+		expect(result.shouldActivate).toBe(false);
+		expect(result.shouldFail).toBe(true);
+	});
+
+	it("fails when edge gate blocks the swipe", () => {
+		const result = shouldActivateOrFail({
+			...baseParams,
+			deltaX: 15,
+			deltaY: 5,
+			isHorizontalSwipe: true,
+			isSwipingRight: true,
+			horizontalGateRight: false, // edge gate blocks
+		});
+		expect(result.shouldActivate).toBe(false);
+		expect(result.shouldFail).toBe(true);
+	});
+
+	it("fails when vertical deviation exceeds tolerance during horizontal swipe", () => {
+		const result = shouldActivateOrFail({
+			...baseParams,
+			deltaX: 15,
+			deltaY: 20, // exceeds GESTURE_FAIL_TOLERANCE_X (15)
+			isHorizontalSwipe: true,
+			isSwipingRight: true,
+		});
+		expect(result.shouldActivate).toBe(false);
+		expect(result.shouldFail).toBe(true);
+	});
+
+	it("does not activate when movement is below threshold", () => {
+		const result = shouldActivateOrFail({
+			...baseParams,
+			deltaX: 5, // below threshold (10)
+			deltaY: 2,
+			isHorizontalSwipe: true,
+			isSwipingRight: true,
+		});
+		expect(result.shouldActivate).toBe(false);
+		expect(result.shouldFail).toBe(false);
+	});
+
+	it("handles bidirectional gesture activation", () => {
+		// Both horizontal and vertical allowed, vertical swipe detected
+		const result = shouldActivateOrFail({
+			...baseParams,
+			hasHorizontal: true,
+			hasVertical: true,
+			deltaX: 5,
+			deltaY: 15,
+			isVerticalSwipe: true,
+			isSwipingDown: true,
+		});
+		expect(result.shouldActivate).toBe(true);
+	});
+});

package/src/shared/components/create-transition-aware-component.tsx

@@ -1,3 +1,4 @@
+/** biome-ignore-all lint/style/noNonNullAssertion: <This helper is usually being used inside a transitionable stack> */
 import type React from "react";
 import { type ComponentType, forwardRef, memo } from "react";
 import type { View } from "react-native";
@@ -26,7 +27,7 @@ export function createTransitionAwareComponent<P extends object>(
 		React.ComponentRef<typeof Wrapped>,
 		TransitionAwareProps<P>
 	>((props: Any, ref) => {
-		const { nativeGesture } = useGestureContext();
+		const { nativeGesture } = useGestureContext()!;
 		const { scrollHandler, onContentSizeChange, onLayout } = useScrollRegistry({
 			onScroll: props.onScroll,
 			onContentSizeChange: props.onContentSizeChange,

package/src/shared/hooks/animation/use-screen-animation.tsx

@@ -28,11 +28,13 @@ type BuiltState = {
 	animating: SharedValue<number>;
 	gesture: GestureStoreMap;
 	route: RouteProp<ParamListBase>;
+	meta?: Record<string, unknown>;
 	unwrapped: ScreenTransitionState;
 };
 
 const createScreenTransitionState = (
 	route: RouteProp<ParamListBase>,
+	meta?: Record<string, unknown>,
 ): ScreenTransitionState => ({
 	progress: 0,
 	closing: 0,
@@ -47,6 +49,7 @@ const createScreenTransitionState = (
 		direction: null,
 	},
 	route,
+	meta,
 });
 
 const unwrapInto = (s: BuiltState): ScreenTransitionState => {
@@ -62,6 +65,7 @@ const unwrapInto = (s: BuiltState): ScreenTransitionState => {
 	out.gesture.isDismissing = s.gesture.isDismissing.value;
 	out.gesture.isDragging = s.gesture.isDragging.value;
 	out.gesture.direction = s.gesture.direction.value;
+	out.meta = s.meta;
 
 	return out;
 };
@@ -70,6 +74,7 @@ const useBuildScreenTransitionState = (
 	descriptor: TransitionDescriptor | undefined,
 ): BuiltState | undefined => {
 	const key = descriptor?.route.key;
+	const meta = descriptor?.options?.meta;
 
 	return useMemo(() => {
 		if (!key) return undefined;
@@ -80,9 +85,10 @@ const useBuildScreenTransitionState = (
 			animating: AnimationStore.getAnimation(key, "animating"),
 			gesture: GestureStore.getRouteGestures(key),
 			route: descriptor.route,
-			unwrapped: createScreenTransitionState(descriptor.route),
+			meta,
+			unwrapped: createScreenTransitionState(descriptor.route, meta),
 		};
-	}, [key, descriptor?.route]);
+	}, [key, descriptor?.route, meta]);
 };
 
 const hasTransitionsEnabled = (
@@ -131,6 +137,7 @@ export function _useScreenAnimation() {
 			: DEFAULT_SCREEN_TRANSITION_STATE;
 
 		const { progress, ...helpers } = derivations({
+			previous,
 			current,
 			next,
 		});

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

@@ -1,5 +1,5 @@
 import { StackActions } from "@react-navigation/native";
-import { useCallback, useMemo } from "react";
+import { useCallback, useMemo, useRef } from "react";
 import { useWindowDimensions } from "react-native";
 import {
 	Gesture,
@@ -48,6 +48,7 @@ export const useBuildGestures = ({
 	ancestorContext,
 }: BuildGesturesHookProps): {
 	panGesture: GestureType;
+	panGestureRef: React.MutableRefObject<GestureType | undefined>;
 	nativeGesture: GestureType;
 	gestureAnimationValues: GestureStoreMap;
 } => {
@@ -63,6 +64,9 @@ export const useBuildGestures = ({
 		GestureOffsetState.PENDING,
 	);
 
+	// Ref for external gesture coordination (e.g., swipeable lists)
+	const panGestureRef = useRef<GestureType | undefined>(undefined);
+
 	const gestureAnimationValues = GestureStore.getRouteGestures(
 		current.route.key,
 	);
@@ -325,26 +329,49 @@ export const useBuildGestures = ({
 		},
 	);
 
+	// Memoize gestures to keep stable references - critical for RNGH
+	// Child gestures reference ancestor's pan via requireExternalGestureToFail,
+	// so the pan gesture MUST be stable or children will reference stale objects
 	return useMemo(() => {
-		const nativeGesture = Gesture.Native();
-
 		const panGesture = Gesture.Pan()
+			.withRef(panGestureRef)
 			.enabled(gestureEnabled)
 			.manualActivation(true)
 			.onTouchesDown(onTouchesDown)
 			.onTouchesMove(onTouchesMove)
 			.onStart(onStart)
 			.onUpdate(onUpdate)
-			.onEnd(onEnd)
-			.blocksExternalGesture(nativeGesture);
+			.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;
+			}
 
-		// Allow ancestors to block child native gestures
-		if (ancestorContext?.panGesture && nativeGesture) {
-			ancestorContext.panGesture.blocksExternalGesture(nativeGesture);
+			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();
+			}
 		}
 
 		return {
 			panGesture,
+			panGestureRef,
 			nativeGesture,
 			gestureAnimationValues,
 		};

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

@@ -0,0 +1,19 @@
+import { useGestureContext } from "../../providers/gestures.provider";
+
+/**
+ * Returns a ref to the screen's navigation pan gesture.
+ * Use this to coordinate child gestures with the navigation gesture.
+ *
+ * @example
+ * ```tsx
+ * const screenGesture = useScreenGesture();
+ *
+ * const myPanGesture = Gesture.Pan()
+ *   .waitFor(screenGesture) // Wait for navigation gesture to fail first
+ *   .onUpdate(...);
+ * ```
+ */
+export const useScreenGesture = () => {
+	const ctx = useGestureContext();
+	return ctx?.panGestureRef ?? null;
+};

package/src/shared/hooks/gestures/use-scroll-registry.tsx

@@ -1,3 +1,6 @@
+/** biome-ignore-all lint/style/noNonNullAssertion: <Will always consume context from GestureProvider> */
+
+import { useMemo } from "react";
 import type { LayoutChangeEvent } from "react-native";
 import { useAnimatedScrollHandler } from "react-native-reanimated";
 import type { ReanimatedScrollEvent } from "react-native-reanimated/lib/typescript/hook/commonTypes";
@@ -12,13 +15,26 @@ interface ScrollProgressHookProps {
 }
 
 export const useScrollRegistry = (props: ScrollProgressHookProps) => {
-	const { scrollConfig, ancestorContext } = useGestureContext();
+	const context = useGestureContext()!;
+	const { scrollConfig, ancestorContext } = context;
+
+	const ancestorScrollConfigs = useMemo(() => {
+		const configs: (typeof scrollConfig)[] = [];
+		let current = ancestorContext;
+		while (current) {
+			if (current.scrollConfig) {
+				configs.push(current.scrollConfig);
+			}
+			current = current.ancestorContext;
+		}
+		return configs;
+	}, [ancestorContext]);
 
 	const scrollHandler = useAnimatedScrollHandler({
 		onScroll: (event) => {
 			props.onScroll?.(event);
 
-			scrollConfig.modify((v: Any) => {
+			const updateScrollPosition = (v: Any) => {
 				"worklet";
 				if (v === null) {
 					return {
@@ -33,25 +49,13 @@ export const useScrollRegistry = (props: ScrollProgressHookProps) => {
 				v.x = event.contentOffset.x;
 				v.y = event.contentOffset.y;
 				return v;
-			});
-
-			if (ancestorContext?.scrollConfig) {
-				ancestorContext.scrollConfig.modify((v: Any) => {
-					"worklet";
-					if (v === null) {
-						return {
-							x: event.contentOffset.x,
-							y: event.contentOffset.y,
-							contentHeight: 0,
-							contentWidth: 0,
-							layoutHeight: 0,
-							layoutWidth: 0,
-						};
-					}
-					v.x = event.contentOffset.x;
-					v.y = event.contentOffset.y;
-					return v;
-				});
+			};
+
+			scrollConfig.modify(updateScrollPosition);
+
+			// Sync to ALL ancestors, not just immediate parent
+			for (const ancestorConfig of ancestorScrollConfigs) {
+				ancestorConfig.modify(updateScrollPosition);
 			}
 		},
 	});
@@ -60,7 +64,7 @@ export const useScrollRegistry = (props: ScrollProgressHookProps) => {
 		(width: number, height: number) => {
 			props.onContentSizeChange?.(width, height);
 
-			scrollConfig.modify((v: Any) => {
+			const updateContentSize = (v: Any) => {
 				"worklet";
 				if (v === null) {
 					return {
@@ -75,24 +79,12 @@ export const useScrollRegistry = (props: ScrollProgressHookProps) => {
 				v.contentWidth = width;
 				v.contentHeight = height;
 				return v;
-			});
-			if (ancestorContext?.scrollConfig) {
-				ancestorContext.scrollConfig.modify((v: Any) => {
-					"worklet";
-					if (v === null) {
-						return {
-							x: 0,
-							y: 0,
-							layoutHeight: 0,
-							layoutWidth: 0,
-							contentWidth: width,
-							contentHeight: height,
-						};
-					}
-					v.contentWidth = width;
-					v.contentHeight = height;
-					return v;
-				});
+			};
+
+			scrollConfig.modify(updateContentSize);
+
+			for (const ancestorConfig of ancestorScrollConfigs) {
+				ancestorConfig.modify(updateContentSize);
 			}
 		},
 	);
@@ -101,7 +93,7 @@ export const useScrollRegistry = (props: ScrollProgressHookProps) => {
 		props.onLayout?.(event);
 		const { width, height } = event.nativeEvent.layout;
 
-		scrollConfig.modify((v: Any) => {
+		const updateLayout = (v: Any) => {
 			"worklet";
 			if (v === null) {
 				return {
@@ -116,24 +108,12 @@ export const useScrollRegistry = (props: ScrollProgressHookProps) => {
 			v.layoutHeight = height;
 			v.layoutWidth = width;
 			return v;
-		});
-		if (ancestorContext?.scrollConfig) {
-			ancestorContext.scrollConfig.modify((v: Any) => {
-				"worklet";
-				if (v === null) {
-					return {
-						x: 0,
-						y: 0,
-						contentHeight: 0,
-						contentWidth: 0,
-						layoutHeight: height,
-						layoutWidth: width,
-					};
-				}
-				v.layoutHeight = height;
-				v.layoutWidth = width;
-				return v;
-			});
+		};
+
+		scrollConfig.modify(updateLayout);
+
+		for (const ancestorConfig of ancestorScrollConfigs) {
+			ancestorConfig.modify(updateLayout);
 		}
 	});
 

package/src/shared/index.ts

@@ -19,6 +19,7 @@ export default {
 };
 
 export { useScreenAnimation } from "./hooks/animation/use-screen-animation";
+export { useScreenGesture } from "./hooks/gestures/use-screen-gesture";
 
 export type {
 	AnimationConfig,
@@ -26,4 +27,5 @@ export type {
 	ScreenInterpolationProps,
 	ScreenStyleInterpolator,
 } from "./types/animation.types";
+export type { BoundEntry, BoundsLink } from "./types/bounds.types";
 export type { ScreenTransitionConfig } from "./types/core.types";

package/src/shared/providers/gestures.provider.tsx

@@ -1,7 +1,5 @@
-import { useMemo } from "react";
 import { StyleSheet, View } from "react-native";
 import {
-	Gesture,
 	GestureDetector,
 	type GestureType,
 } from "react-native-gesture-handler";
@@ -23,18 +21,14 @@ export type ScrollConfig = {
 
 export interface GestureContextType {
 	panGesture: GestureType;
+	panGestureRef: React.MutableRefObject<GestureType | undefined>;
 	nativeGesture: GestureType;
 	scrollConfig: SharedValue<ScrollConfig | null>;
 	gestureAnimationValues: GestureStoreMap;
 	ancestorContext: GestureContextType | null;
+	gestureEnabled: boolean;
 }
 
-/**
- * Provider that creates gesture handling for a screen.
- * If the current screen doesn't have gestures enabled but an ancestor does,
- * we pass through the ancestor's context so scrollable children can coordinate
- * with the ancestor's gestures.
- */
 export const {
 	ScreenGestureProvider,
 	useScreenGestureContext: useGestureContext,
@@ -42,38 +36,32 @@ export const {
 	{ children: React.ReactNode },
 	GestureContextType
 >(({ children }) => {
-	const ancestorContext = useGestureContext();
 	const { current } = useKeys();
+	const ancestorContext = useGestureContext();
 	const scrollConfig = useSharedValue<ScrollConfig | null>(null);
 
-	const hasOwnGestures = current.options.gestureEnabled === true;
-	const shouldPassthrough = !hasOwnGestures && !!ancestorContext;
+	const hasGestures = current.options.gestureEnabled === true;
 
-	const { panGesture, nativeGesture, gestureAnimationValues } =
+	const { panGesture, panGestureRef, nativeGesture, gestureAnimationValues } =
 		useBuildGestures({
 			scrollConfig,
 			ancestorContext,
 		});
 
-	const value: GestureContextType = shouldPassthrough
-		? ancestorContext
-		: {
-				panGesture,
-				scrollConfig,
-				nativeGesture,
-				gestureAnimationValues,
-				ancestorContext,
-			};
-
-	// When passing through, use a no-op gesture to avoid conflicts.
-	// Attaching the same gesture to multiple GestureDetectors causes issues.
-	const noOpGesture = useMemo(() => Gesture.Pan().enabled(false), []);
-	const activeGesture = shouldPassthrough ? noOpGesture : panGesture;
+	const value: GestureContextType = {
+		panGesture,
+		panGestureRef,
+		scrollConfig,
+		nativeGesture,
+		gestureAnimationValues,
+		ancestorContext,
+		gestureEnabled: hasGestures,
+	};
 
 	return {
 		value,
 		children: (
-			<GestureDetector gesture={activeGesture}>
+			<GestureDetector gesture={panGesture}>
 				<View style={styles.container}>{children}</View>
 			</GestureDetector>
 		),