react-native-screen-transitions 3.0.0-rc.4 → 3.0.0

package/src/blank-stack/components/screens.tsx

@@ -8,16 +8,15 @@ import Animated, {
 } from "react-native-reanimated";
 import { Screen as RNSScreen } from "react-native-screens";
 import { AnimationStore } from "../../shared/stores/animation.store";
+import { useStackNavigationContext } from "../utils/with-stack-navigation";
 
 interface ScreenProps {
 	routeKey: string;
 	index: number;
-	routesLength: number;
 	isPreloaded: boolean;
 	children: React.ReactNode;
 	freezeOnBlur?: boolean;
 	shouldFreeze?: boolean;
-	activeScreensLimit: number;
 }
 enum ScreenActivity {
 	INACTIVE = 0,
@@ -32,13 +31,14 @@ const AnimatedScreen = Animated.createAnimatedComponent(RNSScreen);
 export const Screen = ({
 	routeKey,
 	index,
-	routesLength,
 	isPreloaded,
-	activeScreensLimit,
 	children,
 	freezeOnBlur,
 	shouldFreeze,
 }: ScreenProps) => {
+	const { activeScreensLimit, routes } = useStackNavigationContext();
+	const routesLength = routes.length;
+
 	const sceneProgress = AnimationStore.getAnimation(routeKey, "progress");
 	const sceneClosing = AnimationStore.getAnimation(routeKey, "closing");
 	const screenActivity = useSharedValue<ScreenActivity>(

package/src/blank-stack/components/stack-view.tsx

@@ -24,7 +24,9 @@ type SceneViewProps = {
 	descriptor: BlankStackDescriptor;
 };
 
-const SceneView = React.memo(({ descriptor }: SceneViewProps) => {
+const SceneView = React.memo(function SceneView({
+	descriptor,
+}: SceneViewProps) {
 	const { route, navigation, render } = descriptor;
 
 	return (
@@ -38,14 +40,7 @@ const SceneView = React.memo(({ descriptor }: SceneViewProps) => {
 });
 
 export const StackView = withStackNavigationProvider(
-	({
-		activeScreensLimit,
-		descriptors,
-		focusedIndex,
-		routes,
-		scenes,
-		shouldShowFloatOverlay,
-	}) => {
+	({ descriptors, focusedIndex, routes, scenes, shouldShowFloatOverlay }) => {
 		// Memoize route keys array for ScenesProvider
 		const routeKeys = React.useMemo(
 			() => routes.map((route) => route.key),
@@ -82,9 +77,7 @@ export const StackView = withStackNavigationProvider(
 											key={route.key}
 											isPreloaded={isPreloaded}
 											index={sceneIndex}
-											activeScreensLimit={activeScreensLimit}
 											routeKey={route.key}
-											routesLength={routes.length}
 											shouldFreeze={shouldFreeze}
 											freezeOnBlur={descriptor.options.freezeOnBlur}
 										>

package/src/blank-stack/types.ts

@@ -81,13 +81,9 @@ export type BlankStackOverlayProps = {
 	routes: Route<string>[];
 
 	/**
-	 * Options passed to the overlay component.
+	 * Custom metadata from the focused screen's options.
 	 */
-	overlayOptions?: {
-		title?: string;
-		subtitle?: string;
-		[key: string]: unknown;
-	};
+	meta?: Record<string, unknown>;
 
 	/**
 	 * Navigation prop for the overlay.
@@ -134,15 +130,6 @@ export type BlankStackNavigationOptions = BlankStackScreenTransitionConfig & {
 	 */
 	overlayShown?: boolean;
 
-	/**
-	 * Options passed to the overlay component.
-	 */
-	overlayOptions?: {
-		title?: string;
-		subtitle?: string;
-		[key: string]: unknown;
-	};
-
 	/**
 	 * Whether inactive screens should be suspended from re-rendering. Defaults to `false`.
 	 * Defaults to `true` when `enableFreeze()` is run at the top of the application.

package/src/blank-stack/utils/with-stack-navigation/index.tsx

@@ -43,8 +43,8 @@ const { withStackNavigationProvider, useStackNavigationContext } =
 				};
 			}, [state.routes, state.descriptors]);
 
-		return {
-			value: {
+		const value = useMemo(
+			() => ({
 				routes: state.routes,
 				focusedIndex: props.state.index,
 				descriptors: state.descriptors,
@@ -53,7 +53,21 @@ const { withStackNavigationProvider, useStackNavigationContext } =
 				handleCloseRoute,
 				scenes,
 				shouldShowFloatOverlay,
-			},
+			}),
+			[
+				state.routes,
+				state.descriptors,
+				props.state.index,
+				closingRouteKeys.shared,
+				activeScreensLimit,
+				handleCloseRoute,
+				scenes,
+				shouldShowFloatOverlay,
+			],
+		);
+
+		return {
+			value,
 		};
 	});
 

package/src/shared/__tests__/derivations.test.ts

@@ -0,0 +1,155 @@
+import { describe, expect, it } from "bun:test";
+import type { ScreenTransitionState } from "../types/animation.types";
+import { derivations } from "../utils/animation/derivations";
+
+const createMockState = (
+	overrides: Partial<ScreenTransitionState> = {},
+): ScreenTransitionState => ({
+	progress: 1,
+	closing: 0,
+	animating: 0,
+	gesture: {
+		isDragging: 0,
+		x: 0,
+		y: 0,
+		normalizedX: 0,
+		normalizedY: 0,
+		isDismissing: 0,
+		direction: null,
+	},
+	route: { key: "test-route", name: "TestScreen" } as any,
+	...overrides,
+});
+
+describe("derivations", () => {
+	describe("progress", () => {
+		it("returns current progress when no next screen", () => {
+			const result = derivations({
+				current: createMockState({ progress: 0.5 }),
+			});
+			expect(result.progress).toBe(0.5);
+		});
+
+		it("combines current + next progress (0-2 range)", () => {
+			const result = derivations({
+				current: createMockState({ progress: 1 }),
+				next: createMockState({ progress: 0.5 }),
+			});
+			expect(result.progress).toBe(1.5);
+		});
+
+		it("returns 2 when both screens fully transitioned", () => {
+			const result = derivations({
+				current: createMockState({ progress: 1 }),
+				next: createMockState({ progress: 1 }),
+			});
+			expect(result.progress).toBe(2);
+		});
+	});
+
+	describe("focused", () => {
+		it("returns true when no next screen", () => {
+			const result = derivations({
+				current: createMockState(),
+			});
+			expect(result.focused).toBe(true);
+		});
+
+		it("returns false when next screen exists", () => {
+			const result = derivations({
+				current: createMockState(),
+				next: createMockState(),
+			});
+			expect(result.focused).toBe(false);
+		});
+	});
+
+	describe("active", () => {
+		it("returns current when focused (no next)", () => {
+			const current = createMockState({ progress: 0.3 });
+			const result = derivations({ current });
+			expect(result.active).toBe(current);
+		});
+
+		it("returns next when not focused", () => {
+			const current = createMockState({ progress: 1 });
+			const next = createMockState({ progress: 0.5 });
+			const result = derivations({ current, next });
+			expect(result.active).toBe(next);
+		});
+	});
+
+	describe("isActiveTransitioning", () => {
+		it("returns true when active screen is dragging", () => {
+			const result = derivations({
+				current: createMockState({
+					gesture: {
+						isDragging: 1,
+						x: 0,
+						y: 0,
+						normalizedX: 0,
+						normalizedY: 0,
+						isDismissing: 0,
+						direction: null,
+					},
+				}),
+			});
+			expect(result.isActiveTransitioning).toBe(true);
+		});
+
+		it("returns true when active screen is animating", () => {
+			const result = derivations({
+				current: createMockState({ animating: 1 }),
+			});
+			expect(result.isActiveTransitioning).toBe(true);
+		});
+
+		it("returns false when not dragging or animating", () => {
+			const result = derivations({
+				current: createMockState({ animating: 0 }),
+			});
+			expect(result.isActiveTransitioning).toBe(false);
+		});
+	});
+
+	describe("isDismissing", () => {
+		it("returns true when gesture isDismissing", () => {
+			const result = derivations({
+				current: createMockState({
+					gesture: {
+						isDragging: 0,
+						x: 0,
+						y: 0,
+						normalizedX: 0,
+						normalizedY: 0,
+						isDismissing: 1,
+						direction: null,
+					},
+				}),
+			});
+			expect(result.isDismissing).toBe(true);
+		});
+
+		it("returns true when closing flag is set", () => {
+			const result = derivations({
+				current: createMockState({ closing: 1 }),
+			});
+			expect(result.isDismissing).toBe(true);
+		});
+
+		it("returns false when not dismissing or closing", () => {
+			const result = derivations({
+				current: createMockState(),
+			});
+			expect(result.isDismissing).toBe(false);
+		});
+
+		it("checks active screen (next) for dismissing state", () => {
+			const result = derivations({
+				current: createMockState(),
+				next: createMockState({ closing: 1 }),
+			});
+			expect(result.isDismissing).toBe(true);
+		});
+	});
+});

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/controllers/native-stack-lifecycle.tsx

@@ -1,3 +1,4 @@
+/** biome-ignore-all lint/style/noNonNullAssertion: <Lifecycles are rendered right under the gesture provider> */
 import { useEffect, useLayoutEffect } from "react";
 import { useDerivedValue } from "react-native-reanimated";
 import type { NativeStackDescriptor } from "../../../native-stack/types";
@@ -7,6 +8,7 @@ import { useGestureContext } from "../../providers/gestures.provider";
 import { useKeys } from "../../providers/keys.provider";
 import { AnimationStore } from "../../stores/animation.store";
 import { TRUE } from "../../types/state.types";
+import type { Any } from "../../types/utils.types";
 import { startScreenTransition } from "../../utils/animation/start-screen-transition";
 import { resetStoresForScreen } from "../../utils/reset-stores-for-screen";
 
@@ -19,7 +21,7 @@ export interface Props {
  */
 export const NativeStackScreenLifecycleController = ({ children }: Props) => {
 	const { current } = useKeys<NativeStackDescriptor>();
-	const { ancestorContext } = useGestureContext();
+	const { ancestorContext } = useGestureContext()!;
 
 	const isAncestorDismissingViaGesture = useSharedValueState(
 		useDerivedValue(() => {
@@ -32,7 +34,7 @@ export const NativeStackScreenLifecycleController = ({ children }: Props) => {
 
 	const animations = AnimationStore.getAll(current.route.key);
 
-	const handleBeforeRemove = useStableCallback((e: any) => {
+	const handleBeforeRemove = useStableCallback((e: Any) => {
 		const isEnabled = current.options.enableTransitions;
 
 		const isFirstScreen = current.navigation.getState().index === 0;

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 = (