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

package/src/native-stack/views/NativeStackView.native.tsx

@@ -33,7 +33,8 @@ import {
 	ScreenStack,
 	ScreenStackItem,
 } from "react-native-screens";
-import { NativeStackScreenLifecycleController } from "../../shared/components/controllers/screen-lifecycle";
+import { NativeStackScreenLifecycleController } from "../../shared/components/controllers/native-stack-lifecycle";
+import { RoutesProvider } from "../../shared/providers/routes.provider";
 import { ScreenTransitionProvider } from "../../shared/providers/screen-transition.provider";
 import type {
 	NativeStackDescriptor,
@@ -515,118 +516,126 @@ export function NativeStackView({
 
 	const routes = state.routes.concat(state.preloadedRoutes);
 
+	// Memoize route keys array for RoutesProvider
+	const routeKeys = React.useMemo(
+		() => routes.map((route) => route.key),
+		[routes],
+	);
+
 	return (
-		<GestureHandlerRootView>
-			<SafeAreaProviderCompat>
-				<ScreenStack style={styles.container}>
-					{routes.map((route, index) => {
-						const descriptor =
-							descriptors[route.key] ?? preloadedDescriptors[route.key];
-						const isFocused = state.index === index;
-						const isBelowFocused = state.index - 1 === index;
-						const previousKey = state.routes[index - 1]?.key;
-						const nextKey = state.routes[index + 1]?.key;
-						const previousDescriptor = previousKey
-							? descriptors[previousKey]
-							: undefined;
-						const nextDescriptor = nextKey ? descriptors[nextKey] : undefined;
-
-						const isModal = modalRouteKeys.includes(route.key);
-
-						const isPreloaded =
-							preloadedDescriptors[route.key] !== undefined &&
-							descriptors[route.key] === undefined;
-
-						// On Fabric, when screen is frozen, animated and reanimated values are not updated
-						// due to component being unmounted. To avoid this, we don't freeze the previous screen there
-						const shouldFreeze = isFabric()
-							? !isPreloaded && !isFocused && !isBelowFocused
-							: !isPreloaded && !isFocused;
-
-						return (
-							<SceneView
-								key={route.key}
-								index={index}
-								focused={isFocused}
-								shouldFreeze={shouldFreeze}
-								descriptor={descriptor}
-								previousDescriptor={previousDescriptor}
-								nextDescriptor={nextDescriptor}
-								isPresentationModal={isModal}
-								isPreloaded={isPreloaded}
-								onWillDisappear={() => {
-									navigation.emit({
-										type: "transitionStart",
-										data: { closing: true },
-										target: route.key,
-									});
-								}}
-								onWillAppear={() => {
-									navigation.emit({
-										type: "transitionStart",
-										data: { closing: false },
-										target: route.key,
-									});
-								}}
-								onAppear={() => {
-									navigation.emit({
-										type: "transitionEnd",
-										data: { closing: false },
-										target: route.key,
-									});
-								}}
-								onDisappear={() => {
-									navigation.emit({
-										type: "transitionEnd",
-										data: { closing: true },
-										target: route.key,
-									});
-								}}
-								onDismissed={(event) => {
-									navigation.dispatch({
-										...StackActions.pop(event.nativeEvent.dismissCount),
-										source: route.key,
-										target: state.key,
-									});
-
-									setNextDismissedKey(route.key);
-								}}
-								onHeaderBackButtonClicked={() => {
-									navigation.dispatch({
-										...StackActions.pop(),
-										source: route.key,
-										target: state.key,
-									});
-								}}
-								onNativeDismissCancelled={(event) => {
-									navigation.dispatch({
-										...StackActions.pop(event.nativeEvent.dismissCount),
-										source: route.key,
-										target: state.key,
-									});
-								}}
-								onGestureCancel={() => {
-									navigation.emit({
-										type: "gestureCancel",
-										target: route.key,
-									});
-								}}
-								onSheetDetentChanged={(event) => {
-									navigation.emit({
-										type: "sheetDetentChange",
-										target: route.key,
-										data: {
-											index: event.nativeEvent.index,
-											stable: event.nativeEvent.isStable,
-										},
-									});
-								}}
-							/>
-						);
-					})}
-				</ScreenStack>
-			</SafeAreaProviderCompat>
-		</GestureHandlerRootView>
+		<RoutesProvider routeKeys={routeKeys}>
+			<GestureHandlerRootView>
+				<SafeAreaProviderCompat>
+					<ScreenStack style={styles.container}>
+						{routes.map((route, index) => {
+							const descriptor =
+								descriptors[route.key] ?? preloadedDescriptors[route.key];
+							const isFocused = state.index === index;
+							const isBelowFocused = state.index - 1 === index;
+							const previousKey = state.routes[index - 1]?.key;
+							const nextKey = state.routes[index + 1]?.key;
+							const previousDescriptor = previousKey
+								? descriptors[previousKey]
+								: undefined;
+							const nextDescriptor = nextKey ? descriptors[nextKey] : undefined;
+
+							const isModal = modalRouteKeys.includes(route.key);
+
+							const isPreloaded =
+								preloadedDescriptors[route.key] !== undefined &&
+								descriptors[route.key] === undefined;
+
+							// On Fabric, when screen is frozen, animated and reanimated values are not updated
+							// due to component being unmounted. To avoid this, we don't freeze the previous screen there
+							const shouldFreeze = isFabric()
+								? !isPreloaded && !isFocused && !isBelowFocused
+								: !isPreloaded && !isFocused;
+
+							return (
+								<SceneView
+									key={route.key}
+									index={index}
+									focused={isFocused}
+									shouldFreeze={shouldFreeze}
+									descriptor={descriptor}
+									previousDescriptor={previousDescriptor}
+									nextDescriptor={nextDescriptor}
+									isPresentationModal={isModal}
+									isPreloaded={isPreloaded}
+									onWillDisappear={() => {
+										navigation.emit({
+											type: "transitionStart",
+											data: { closing: true },
+											target: route.key,
+										});
+									}}
+									onWillAppear={() => {
+										navigation.emit({
+											type: "transitionStart",
+											data: { closing: false },
+											target: route.key,
+										});
+									}}
+									onAppear={() => {
+										navigation.emit({
+											type: "transitionEnd",
+											data: { closing: false },
+											target: route.key,
+										});
+									}}
+									onDisappear={() => {
+										navigation.emit({
+											type: "transitionEnd",
+											data: { closing: true },
+											target: route.key,
+										});
+									}}
+									onDismissed={(event) => {
+										navigation.dispatch({
+											...StackActions.pop(event.nativeEvent.dismissCount),
+											source: route.key,
+											target: state.key,
+										});
+
+										setNextDismissedKey(route.key);
+									}}
+									onHeaderBackButtonClicked={() => {
+										navigation.dispatch({
+											...StackActions.pop(),
+											source: route.key,
+											target: state.key,
+										});
+									}}
+									onNativeDismissCancelled={(event) => {
+										navigation.dispatch({
+											...StackActions.pop(event.nativeEvent.dismissCount),
+											source: route.key,
+											target: state.key,
+										});
+									}}
+									onGestureCancel={() => {
+										navigation.emit({
+											type: "gestureCancel",
+											target: route.key,
+										});
+									}}
+									onSheetDetentChanged={(event) => {
+										navigation.emit({
+											type: "sheetDetentChange",
+											target: route.key,
+											data: {
+												index: event.nativeEvent.index,
+												stable: event.nativeEvent.isStable,
+											},
+										});
+									}}
+								/>
+							);
+						})}
+					</ScreenStack>
+				</SafeAreaProviderCompat>
+			</GestureHandlerRootView>
+		</RoutesProvider>
 	);
 }
 

package/src/shared/__tests__/bounds.store.test.ts

@@ -45,12 +45,8 @@ describe("BoundStore.registerSnapshot", () => {
 		BoundStore.registerSnapshot("card", "screen-a", boundsA);
 		BoundStore.registerSnapshot("card", "screen-b", boundsB);
 
-		expect(BoundStore.getSnapshot("card", "screen-a")?.bounds).toEqual(
-			boundsA,
-		);
-		expect(BoundStore.getSnapshot("card", "screen-b")?.bounds).toEqual(
-			boundsB,
-		);
+		expect(BoundStore.getSnapshot("card", "screen-a")?.bounds).toEqual(boundsA);
+		expect(BoundStore.getSnapshot("card", "screen-b")?.bounds).toEqual(boundsB);
 	});
 
 	it("stores ancestorKeys correctly", () => {
@@ -192,13 +188,9 @@ describe("BoundStore.getSnapshot", () => {
 		const ancestorBounds = createBounds(200, 200, 50, 50);
 
 		// Register with ancestor that matches another screen's key
-		BoundStore.registerSnapshot(
-			"card",
-			"screen-a",
-			ancestorBounds,
-			{},
-			["stack-a"],
-		);
+		BoundStore.registerSnapshot("card", "screen-a", ancestorBounds, {}, [
+			"stack-a",
+		]);
 		BoundStore.registerSnapshot("card", "stack-a", directBounds);
 
 		// Direct match should win
@@ -242,32 +234,23 @@ describe("BoundStore.getActiveLink", () => {
 
 		// Query from source screen = closing (going back)
 		const linkFromSource = BoundStore.getActiveLink("card", "screen-a");
-		expect(linkFromSource?.isClosing).toBe(true);
 		expect(linkFromSource?.source.screenKey).toBe("screen-a");
 
 		// Query from destination screen = opening
 		const linkFromDest = BoundStore.getActiveLink("card", "screen-b");
-		expect(linkFromDest?.isClosing).toBe(false);
 		expect(linkFromDest?.destination?.screenKey).toBe("screen-b");
 	});
 
 	it("ancestor matching works in link lookup", () => {
 		const ancestors = ["stack-a"];
 
-		BoundStore.setLinkSource(
-			"card",
-			"screen-a",
-			createBounds(),
-			{},
-			ancestors,
-		);
+		BoundStore.setLinkSource("card", "screen-a", createBounds(), {}, ancestors);
 		BoundStore.setLinkDestination("card", "screen-b", createBounds());
 
 		// Query by ancestor key (matches source)
 		const link = BoundStore.getActiveLink("card", "stack-a");
 		expect(link).not.toBeNull();
 		expect(link?.source.screenKey).toBe("screen-a");
-		expect(link?.isClosing).toBe(true); // Ancestor of source = closing
 	});
 
 	it("returns null when screenKey does not match any link", () => {
@@ -296,13 +279,11 @@ describe("Scenario: Simple push/pop navigation", () => {
 
 		// Verify link is complete - query from destination (opening)
 		const openingLink = BoundStore.getActiveLink("card", "screen-b");
-		expect(openingLink?.isClosing).toBe(false);
 		expect(openingLink?.source.bounds).toEqual(srcBounds);
 		expect(openingLink?.destination?.bounds).toEqual(dstBounds);
 
 		// 3. Query from source (closing - going back)
 		const closingLink = BoundStore.getActiveLink("card", "screen-a");
-		expect(closingLink?.isClosing).toBe(true);
 		expect(closingLink?.source.screenKey).toBe("screen-a");
 		expect(closingLink?.destination?.screenKey).toBe("screen-b");
 	});
@@ -355,19 +336,14 @@ describe("Scenario: Nested navigator with ancestor keys", () => {
 
 	it("getActiveLink respects ancestor chain", () => {
 		// Navigation from Stack A to detail screen
-		BoundStore.setLinkSource(
-			"profile",
-			"a1",
-			createBounds(10, 10),
-			{},
-			["stack-a"],
-		);
+		BoundStore.setLinkSource("profile", "a1", createBounds(10, 10), {}, [
+			"stack-a",
+		]);
 		BoundStore.setLinkDestination("profile", "detail", createBounds(0, 0));
 
 		// Query by ancestor should find the link
 		const link = BoundStore.getActiveLink("profile", "stack-a");
 		expect(link?.source.screenKey).toBe("a1");
-		expect(link?.isClosing).toBe(true); // Ancestor matches source = closing
 	});
 });
 
@@ -388,12 +364,10 @@ describe("Scenario: Rapid navigation A → B → C → pop → pop", () => {
 
 		// Query from C (destination of B→C) = opening
 		const fromC = BoundStore.getActiveLink("card", "screen-c");
-		expect(fromC?.isClosing).toBe(false);
 		expect(fromC?.destination?.screenKey).toBe("screen-c");
 
 		// Query from B - B is source of B→C link, so isClosing=true
 		const fromB = BoundStore.getActiveLink("card", "screen-b");
-		expect(fromB?.isClosing).toBe(true);
 		expect(fromB?.source.screenKey).toBe("screen-b");
 	});
 });
@@ -401,7 +375,11 @@ describe("Scenario: Rapid navigation A → B → C → pop → pop", () => {
 describe("Scenario: Global bounds (fullscreen target)", () => {
 	it("getActiveLink with no screenKey returns most recent for fullscreen", () => {
 		// Source exists, destination will be fullscreen (no specific screenKey needed)
-		BoundStore.setLinkSource("image", "gallery", createBounds(50, 50, 100, 100));
+		BoundStore.setLinkSource(
+			"image",
+			"gallery",
+			createBounds(50, 50, 100, 100),
+		);
 		BoundStore.setLinkDestination(
 			"image",
 			"fullscreen-viewer",

package/src/shared/components/controllers/blank-stack-lifecycle.tsx

@@ -0,0 +1,70 @@
+import { useLayoutEffect } from "react";
+import { useAnimatedReaction } from "react-native-reanimated";
+import type { BlankStackDescriptor } from "../../../blank-stack/types";
+import { useStackNavigationContext } from "../../../blank-stack/utils/with-stack-navigation";
+import useStableCallback from "../../hooks/use-stable-callback";
+import { useKeys } from "../../providers/keys.provider";
+import { AnimationStore } from "../../stores/animation.store";
+import { startScreenTransition } from "../../utils/animation/start-screen-transition";
+import { resetStoresForScreen } from "../../utils/reset-stores-for-screen";
+
+export interface Props {
+	children: React.ReactNode;
+}
+
+/**
+ * Lifecycle controller built out for Blank Stack implementation.
+ */
+export const BlankStackScreenLifecycleController = ({ children }: Props) => {
+	const { current } = useKeys<BlankStackDescriptor>();
+	const { handleCloseRoute, closingRouteKeysShared } =
+		useStackNavigationContext();
+
+	const animations = AnimationStore.getAll(current.route.key);
+
+	const handleInitialize = useStableCallback(() => {
+		startScreenTransition({
+			target: "open",
+			spec: current.options.transitionSpec,
+			animations,
+		});
+	});
+
+	const handleCleanup = useStableCallback(() => {
+		resetStoresForScreen(current);
+	});
+
+	const handleCloseEnd = useStableCallback((finished: boolean) => {
+		if (!finished) {
+			return;
+		}
+		handleCloseRoute({ route: current.route });
+	});
+
+	useAnimatedReaction(
+		() => ({
+			keys: closingRouteKeysShared.value,
+		}),
+		({ keys }) => {
+			if (!keys.includes(current.route.key)) {
+				return;
+			}
+
+			startScreenTransition({
+				target: "close",
+				spec: current.options.transitionSpec,
+				animations,
+				onAnimationFinish: handleCloseEnd,
+			});
+		},
+	);
+
+	useLayoutEffect(() => {
+		handleInitialize();
+		return () => {
+			handleCleanup();
+		};
+	}, [handleInitialize, handleCleanup]);
+
+	return children;
+};

package/src/shared/components/controllers/native-stack-lifecycle.tsx

@@ -0,0 +1,89 @@
+/** 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";
+import { useSharedValueState } from "../../hooks/reanimated/use-shared-value-state";
+import useStableCallback from "../../hooks/use-stable-callback";
+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";
+
+export interface Props {
+	children: React.ReactNode;
+}
+
+/**
+ * Lifecycle controller built out for Native Stack implementation.
+ */
+export const NativeStackScreenLifecycleController = ({ children }: Props) => {
+	const { current } = useKeys<NativeStackDescriptor>();
+	const { ancestorContext } = useGestureContext()!;
+
+	const isAncestorDismissingViaGesture = useSharedValueState(
+		useDerivedValue(() => {
+			"worklet";
+			return (
+				ancestorContext?.gestureAnimationValues.isDismissing?.value ?? false
+			);
+		}),
+	);
+
+	const animations = AnimationStore.getAll(current.route.key);
+
+	const handleBeforeRemove = useStableCallback((e: Any) => {
+		const isEnabled = current.options.enableTransitions;
+
+		const isFirstScreen = current.navigation.getState().index === 0;
+
+		// If transitions are disabled, or an ancestor is dismissing via gesture, or this is the first screen of the stack, reset the stores
+		if (!isEnabled || isAncestorDismissingViaGesture || isFirstScreen) {
+			animations.closing.set(TRUE);
+			resetStoresForScreen(current);
+			return;
+		}
+
+		e.preventDefault();
+		const onAnimationFinish = (finished: boolean) => {
+			if (finished) {
+				current.navigation.dispatch(e.data.action);
+
+				// we'll ensure the dispatch is complete before resetting stores
+				requestAnimationFrame(() => {
+					resetStoresForScreen(current);
+				});
+			}
+		};
+
+		startScreenTransition({
+			target: "close",
+			spec: current.options.transitionSpec,
+			onAnimationFinish,
+			animations,
+		});
+	});
+
+	const handleInitialize = useStableCallback(() => {
+		startScreenTransition({
+			target: "open",
+			spec: current.options.transitionSpec,
+			animations,
+		});
+	});
+
+	useEffect(() => {
+		const unsubscribe = current.navigation.addListener(
+			"beforeRemove",
+			handleBeforeRemove,
+		);
+
+		return unsubscribe;
+	}, [current.navigation, handleBeforeRemove]);
+
+	useLayoutEffect(handleInitialize, []);
+
+	return children;
+};

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

@@ -10,6 +10,7 @@ import {
 	type TransitionDescriptor,
 	useKeys,
 } from "../../providers/keys.provider";
+import { useStackAnimationValues } from "../../providers/routes.provider";
 import { AnimationStore } from "../../stores/animation.store";
 import { GestureStore, type GestureStoreMap } from "../../stores/gesture.store";
 import type {
@@ -17,7 +18,7 @@ import type {
 	ScreenTransitionState,
 } from "../../types/animation.types";
 import type { ScreenTransitionConfig } from "../../types/core.types";
-import type { GestureDirection } from "../../types/gesture.types";
+import { computeStackProgress } from "../../utils/animation/compute-stack-progress";
 import { derivations } from "../../utils/animation/derivations";
 import { createBounds } from "../../utils/bounds";
 
@@ -60,10 +61,7 @@ const unwrapInto = (s: BuiltState): ScreenTransitionState => {
 	out.gesture.normalizedY = s.gesture.normalizedY.value;
 	out.gesture.isDismissing = s.gesture.isDismissing.value;
 	out.gesture.isDragging = s.gesture.isDragging.value;
-	out.gesture.direction = s.gesture.direction.value as Omit<
-		GestureDirection,
-		"bidirectional"
-	> | null;
+	out.gesture.direction = s.gesture.direction.value;
 
 	return out;
 };
@@ -112,6 +110,9 @@ export function _useScreenAnimation() {
 	const nextAnimation = useBuildScreenTransitionState(nextDescriptor);
 	const prevAnimation = useBuildScreenTransitionState(previousDescriptor);
 
+	const currentRouteKey = currentDescriptor?.route?.key;
+	const stackAnimationValues = useStackAnimationValues(currentRouteKey);
+
 	const screenInterpolatorProps = useDerivedValue<
 		Omit<ScreenInterpolationProps, "bounds">
 	>(() => {
@@ -129,17 +130,21 @@ export function _useScreenAnimation() {
 			? unwrapInto(currentAnimation)
 			: DEFAULT_SCREEN_TRANSITION_STATE;
 
-		const helpers = derivations({
+		const { progress, ...helpers } = derivations({
 			current,
 			next,
 		});
 
+		const stackProgress = computeStackProgress(stackAnimationValues, progress);
+
 		return {
 			layouts: { screen: dimensions },
 			insets,
 			previous,
 			current,
 			next,
+			progress,
+			stackProgress,
 			...helpers,
 		};
 	});

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

@@ -40,12 +40,12 @@ import useStableCallbackValue from "../use-stable-callback-value";
 
 interface BuildGesturesHookProps {
 	scrollConfig: SharedValue<ScrollConfig | null>;
-	parentContext?: GestureContextType | null;
+	ancestorContext?: GestureContextType | null;
 }
 
 export const useBuildGestures = ({
 	scrollConfig,
-	parentContext,
+	ancestorContext,
 }: BuildGesturesHookProps): {
 	panGesture: GestureType;
 	nativeGesture: GestureType;
@@ -96,8 +96,8 @@ export const useBuildGestures = ({
 
 	const handleDismiss = useCallback(() => {
 		// If an ancestor navigator is already dismissing, skip this dismiss to
-		// avoid racing with the parent
-		if (parentContext?.gestureAnimationValues.isDismissing?.value) {
+		// avoid racing with the ancestor
+		if (ancestorContext?.gestureAnimationValues.isDismissing?.value) {
 			return;
 		}
 
@@ -116,7 +116,7 @@ export const useBuildGestures = ({
 			source: current.route.key,
 			target: state.key,
 		});
-	}, [current, parentContext]);
+	}, [current, ancestorContext]);
 
 	const onTouchesDown = useStableCallbackValue((e: GestureTouchEvent) => {
 		"worklet";
@@ -130,7 +130,7 @@ export const useBuildGestures = ({
 			"worklet";
 
 			// If an ancestor navigator is already dismissing via gesture, block new gestures here.
-			if (parentContext?.gestureAnimationValues.isDismissing?.value) {
+			if (ancestorContext?.gestureAnimationValues.isDismissing?.value) {
 				gestureOffsetState.value = GestureOffsetState.FAILED;
 				manager.fail();
 				return;
@@ -338,6 +338,11 @@ export const useBuildGestures = ({
 			.onEnd(onEnd)
 			.blocksExternalGesture(nativeGesture);
 
+		// Allow ancestors to block child native gestures
+		if (ancestorContext?.panGesture && nativeGesture) {
+			ancestorContext.panGesture.blocksExternalGesture(nativeGesture);
+		}
+
 		return {
 			panGesture,
 			nativeGesture,
@@ -351,5 +356,6 @@ export const useBuildGestures = ({
 		onUpdate,
 		onEnd,
 		gestureAnimationValues,
+		ancestorContext,
 	]);
 };