react-native-screen-transitions 3.1.0 → 3.2.0-beta.1

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

@@ -4,16 +4,12 @@ import {
 	HeaderBackContext,
 	HeaderHeightContext,
 	HeaderShownContext,
-	SafeAreaProviderCompat,
 	useFrameSize,
 } from "@react-navigation/elements";
 import {
 	NavigationContext,
 	NavigationRouteContext,
-	type ParamListBase,
-	type RouteProp,
 	StackActions,
-	type StackNavigationState,
 	usePreventRemoveContext,
 	useTheme,
 } from "@react-navigation/native";
@@ -26,21 +22,21 @@ import {
 	useAnimatedValue,
 	View,
 } from "react-native";
-import { GestureHandlerRootView } from "react-native-gesture-handler";
 import { useSafeAreaInsets } from "react-native-safe-area-context";
 import {
 	type ScreenProps,
 	ScreenStack,
 	ScreenStackItem,
 } from "react-native-screens";
-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,
-	NativeStackDescriptorMap,
-	NativeStackNavigationHelpers,
-} from "../types";
+import { Overlay } from "../../shared/components/overlay";
+import { ScreenComposer } from "../../shared/providers/screen/screen-composer";
+import { withStackCore } from "../../shared/providers/stack/core.provider";
+import {
+	type DirectStackContextValue,
+	withDirectStack,
+} from "../../shared/providers/stack/direct.provider";
+import { NativeStackScreenLifecycleController } from "../controllers/native-stack-lifecycle";
+import type { NativeStackDescriptor } from "../types";
 import { debounce } from "../utils/debounce";
 import { getModalRouteKeys } from "../utils/getModalRoutesKeys";
 import { AnimatedHeaderHeightContext } from "../utils/useAnimatedHeaderHeight";
@@ -468,14 +464,14 @@ const SceneView = ({
 								value={isParentHeaderShown || headerShown !== false}
 							>
 								<HeaderBackContext.Provider value={headerBack}>
-									<ScreenTransitionProvider
+									<ScreenComposer
 										previous={previousDescriptor}
 										current={descriptor}
 										next={nextDescriptor}
 										LifecycleController={NativeStackScreenLifecycleController}
 									>
 										{render()}
-									</ScreenTransitionProvider>
+									</ScreenComposer>
 								</HeaderBackContext.Provider>
 							</HeaderShownContext.Provider>
 						</HeaderHeightContext.Provider>
@@ -486,158 +482,133 @@ const SceneView = ({
 	);
 };
 
-type Props = {
-	state: StackNavigationState<ParamListBase>;
-	navigation: NativeStackNavigationHelpers;
-	descriptors: NativeStackDescriptorMap;
-	describe: (
-		route: RouteProp<ParamListBase>,
-		placeholder: boolean,
-	) => NativeStackDescriptor;
-};
-
-export function NativeStackView({
-	state,
-	navigation,
-	descriptors,
-	describe,
-}: Props) {
-	const { setNextDismissedKey } = useDismissedRouteError(state);
-
-	useInvalidPreventRemoveError(descriptors);
-
-	const modalRouteKeys = getModalRouteKeys(state.routes, descriptors);
-
-	const preloadedDescriptors =
-		state.preloadedRoutes.reduce<NativeStackDescriptorMap>((acc, route) => {
-			acc[route.key] = acc[route.key] || describe(route, true);
-			return acc;
-		}, {});
-
-	const routes = state.routes.concat(state.preloadedRoutes);
-
-	// Memoize route keys array for RoutesProvider
-	const routeKeys = React.useMemo(
-		() => routes.map((route) => route.key),
-		[routes],
-	);
-
-	return (
-		<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>
-	);
-}
+export const NativeStackView = withStackCore(
+	{ TRANSITIONS_ALWAYS_ON: false },
+	withDirectStack(function NativeStackViewContent({
+		state,
+		navigation,
+		descriptors,
+		scenes,
+		focusedIndex,
+		shouldShowFloatOverlay,
+	}: DirectStackContextValue) {
+		const { setNextDismissedKey } = useDismissedRouteError(state);
+
+		useInvalidPreventRemoveError(descriptors);
+
+		const modalRouteKeys = getModalRouteKeys(state.routes, descriptors);
+
+		return (
+			<>
+				{shouldShowFloatOverlay ? <Overlay.Float /> : null}
+				<ScreenStack style={styles.container}>
+					{scenes.map((scene, index) => {
+						const { route, descriptor, isPreloaded } = scene;
+						const isFocused = focusedIndex === index;
+						const isBelowFocused = focusedIndex - 1 === index;
+
+						// Get previous/next descriptors from state.routes (not scenes) for proper navigation
+						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);
+
+						// 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>
+			</>
+		);
+	}),
+);
 
 const styles = StyleSheet.create({
 	container: {

package/src/shared/__tests__/sync-routes-with-removed.test.ts

@@ -0,0 +1,137 @@
+import { beforeEach, describe, expect, it } from "bun:test";
+import { AnimationStore } from "../stores/animation.store";
+import { GestureStore } from "../stores/gesture.store";
+import { syncRoutesWithRemoved } from "../utils/navigation/sync-routes-with-removed";
+
+const createRoute = (key: string) => ({ key });
+
+const createClosingRouteKeys = () => {
+	const keys = new Set<string>();
+	const sharedValue: string[] = [];
+	return {
+		ref: { current: keys } as React.RefObject<Set<string>>,
+		shared: {
+			value: sharedValue,
+			get: () => sharedValue,
+			set: (v: string[]) => {
+				sharedValue.length = 0;
+				sharedValue.push(...v);
+			},
+			addListener: () => () => {},
+			removeListener: () => {},
+			modify: (fn?: (v: string[]) => string[], _forceUpdate?: boolean) => {
+				if (fn) {
+					const result = fn(sharedValue);
+					sharedValue.length = 0;
+					sharedValue.push(...result);
+				}
+			},
+		},
+		add: (key: string) => {
+			keys.add(key);
+		},
+		remove: (key: string) => {
+			keys.delete(key);
+		},
+		clear: () => keys.clear(),
+	};
+};
+
+// Helper to set up a route's animation state
+const setRouteState = (
+	routeKey: string,
+	state: {
+		progress?: number;
+		closing?: number;
+		isDragging?: number;
+		isDismissing?: number;
+	},
+) => {
+	const animations = AnimationStore.getAll(routeKey);
+	const gestures = GestureStore.getRouteGestures(routeKey);
+
+	if (state.progress !== undefined) animations.progress.value = state.progress;
+	if (state.closing !== undefined) animations.closing.value = state.closing;
+	if (state.isDragging !== undefined)
+		gestures.isDragging.value = state.isDragging;
+	if (state.isDismissing !== undefined)
+		gestures.isDismissing.value = state.isDismissing;
+};
+
+// Reset stores before each test
+beforeEach(() => {
+	globalThis.resetMutableRegistry();
+});
+
+describe("syncRoutesWithRemoved", () => {
+	describe("basic routing", () => {
+		it("returns empty routes when nextRoutes is empty", () => {
+			const closingRouteKeys = createClosingRouteKeys();
+			const result = syncRoutesWithRemoved({
+				prevRoutes: [createRoute("a")],
+				prevDescriptors: {},
+				nextRoutes: [],
+				nextDescriptors: {},
+				closingRouteKeys,
+			});
+			expect(result.routes).toEqual([]);
+		});
+
+		it("returns nextRoutes unchanged for normal push (A -> B)", () => {
+			const closingRouteKeys = createClosingRouteKeys();
+
+			// Both routes fully visible
+			setRouteState("a", { progress: 1 });
+			setRouteState("b", { progress: 1 });
+
+			const result = syncRoutesWithRemoved({
+				prevRoutes: [createRoute("a")],
+				prevDescriptors: { a: {} },
+				nextRoutes: [createRoute("a"), createRoute("b")],
+				nextDescriptors: { a: {}, b: {} },
+				closingRouteKeys,
+			});
+			expect(result.routes.map((r) => r.key)).toEqual(["a", "b"]);
+		});
+
+		it("returns nextRoutes unchanged for normal stack (A -> B -> C)", () => {
+			const closingRouteKeys = createClosingRouteKeys();
+
+			setRouteState("a", { progress: 1 });
+			setRouteState("b", { progress: 1 });
+			setRouteState("c", { progress: 1 });
+
+			const result = syncRoutesWithRemoved({
+				prevRoutes: [createRoute("a"), createRoute("b")],
+				prevDescriptors: { a: {}, b: {} },
+				nextRoutes: [createRoute("a"), createRoute("b"), createRoute("c")],
+				nextDescriptors: { a: {}, b: {}, c: {} },
+				closingRouteKeys,
+			});
+			expect(result.routes.map((r) => r.key)).toEqual(["a", "b", "c"]);
+		});
+	});
+
+
+	describe("normal back navigation", () => {
+		it("keeps closing route at end for normal back (C -> B)", () => {
+			const closingRouteKeys = createClosingRouteKeys();
+
+			setRouteState("a", { progress: 1 });
+			setRouteState("b", { progress: 1 });
+			setRouteState("c", { progress: 1 });
+
+			const result = syncRoutesWithRemoved({
+				prevRoutes: [createRoute("a"), createRoute("b"), createRoute("c")],
+				prevDescriptors: { a: {}, b: {}, c: {} },
+				nextRoutes: [createRoute("a"), createRoute("b")],
+				nextDescriptors: { a: {}, b: {} },
+				closingRouteKeys,
+			});
+
+			// c should be added to end for close animation
+			expect(result.routes.map((r) => r.key)).toEqual(["a", "b", "c"]);
+			expect(closingRouteKeys.ref.current.has("c")).toBe(true);
+		});
+	});
+});

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

@@ -8,8 +8,7 @@ import { useAssociatedStyles } from "../hooks/animation/use-associated-style";
 import { useScrollRegistry } from "../hooks/gestures/use-scroll-registry";
 import { useGestureContext } from "../providers/gestures.provider";
 import { RegisterBoundsProvider } from "../providers/register-bounds.provider";
-import type { TransitionAwareProps } from "../types/core.types";
-import type { Any } from "../types/utils.types";
+import type { TransitionAwareProps } from "../types/screen.types";
 
 interface CreateTransitionAwareComponentOptions {
 	isScrollable?: boolean;
@@ -26,7 +25,7 @@ export function createTransitionAwareComponent<P extends object>(
 	const ScrollableInner = forwardRef<
 		React.ComponentRef<typeof Wrapped>,
 		TransitionAwareProps<P>
-	>((props: Any, ref) => {
+	>((props: any, ref) => {
 		const { nativeGesture } = useGestureContext()!;
 		const { scrollHandler, onContentSizeChange, onLayout } = useScrollRegistry({
 			onScroll: props.onScroll,
@@ -37,7 +36,7 @@ export function createTransitionAwareComponent<P extends object>(
 		return (
 			<GestureDetector gesture={nativeGesture}>
 				<AnimatedComponent
-					{...(props as Any)}
+					{...(props as any)}
 					ref={ref}
 					onScroll={scrollHandler}
 					onContentSizeChange={onContentSizeChange}
@@ -53,7 +52,7 @@ export function createTransitionAwareComponent<P extends object>(
 		TransitionAwareProps<P>
 	>((props, _) => {
 		const { children, style, sharedBoundTag, styleId, onPress, ...rest } =
-			props as Any;
+			props as any;
 
 		const animatedRef = useAnimatedRef<View>();
 
@@ -71,7 +70,7 @@ export function createTransitionAwareComponent<P extends object>(
 			>
 				{({ captureActiveOnPress, handleInitialLayout }) => (
 					<AnimatedComponent
-						{...(rest as Any)}
+						{...(rest as any)}
 						ref={animatedRef}
 						style={[style, associatedStyles]}
 						onPress={captureActiveOnPress}

package/src/shared/components/overlay/helpers/get-active-overlay.ts

@@ -0,0 +1,38 @@
+import type { StackScene } from "../../../hooks/navigation/use-stack";
+
+/**
+ * Find the active float overlay from scenes.
+ * Scans from the top of the stack downward to find the first screen
+ * with overlayMode="float" and overlayShown=true.
+ */
+export function getActiveFloatOverlay(
+	scenes: StackScene[],
+	index: number,
+	transitionsAlwaysOn: boolean,
+): { scene: StackScene; overlayIndex: number } | null {
+	if (scenes.length === 0) {
+		return null;
+	}
+
+	// When navigating back, closing scenes are kept at the top of the local stack
+	// while the focused index already points to the destination screen. We need to
+	// start scanning from the actual top of the stack so the overlay can animate
+	// out together with its closing screen instead of disappearing immediately.
+	const startIndex = Math.max(index, scenes.length - 1);
+
+	for (let i = startIndex; i >= 0; i--) {
+		const scene = scenes[i];
+		const options = scene?.descriptor?.options;
+
+		// Skip screens without enableTransitions (native-stack only)
+		if (!transitionsAlwaysOn && !options?.enableTransitions) {
+			continue;
+		}
+
+		if (options?.overlayMode === "float" && options?.overlayShown) {
+			return { scene, overlayIndex: i };
+		}
+	}
+
+	return null;
+}

package/src/shared/components/overlay/index.ts

@@ -0,0 +1,7 @@
+import { FloatOverlay } from "./variations/float-overlay";
+import { ScreenOverlay } from "./variations/screen-overlay";
+
+export const Overlay = {
+	Float: FloatOverlay,
+	Screen: ScreenOverlay,
+};

package/src/shared/components/overlay/variations/float-overlay.tsx

@@ -0,0 +1,44 @@
+import { useMemo } from "react";
+import { useStack } from "../../../hooks/navigation/use-stack";
+import { KeysProvider } from "../../../providers/screen/keys.provider";
+import { ScreenStylesProvider } from "../../../providers/screen/styles.provider";
+import { getActiveFloatOverlay } from "../helpers/get-active-overlay";
+import { OverlayHost } from "./overlay-host";
+
+/**
+ * Float overlay component that renders above all screens.
+ * Gets routes and descriptors from stack context.
+ */
+export function FloatOverlay() {
+	const { routes, scenes, focusedIndex, flags } = useStack();
+
+	const activeOverlay = useMemo(
+		() =>
+			getActiveFloatOverlay(scenes, focusedIndex, flags.TRANSITIONS_ALWAYS_ON),
+		[scenes, focusedIndex, flags.TRANSITIONS_ALWAYS_ON],
+	);
+
+	if (!activeOverlay) {
+		return null;
+	}
+
+	const { scene, overlayIndex } = activeOverlay;
+
+	const previous = scenes[overlayIndex - 1]?.descriptor;
+	const current = scene.descriptor;
+	const next = scenes[overlayIndex + 1]?.descriptor;
+
+	return (
+		<KeysProvider current={current} previous={previous} next={next}>
+			<ScreenStylesProvider>
+				<OverlayHost
+					scene={scene}
+					scenes={scenes}
+					routes={routes}
+					overlayIndex={overlayIndex}
+					isFloating
+				/>
+			</ScreenStylesProvider>
+		</KeysProvider>
+	);
+}