react-native-screen-transitions 3.6.0-beta.0 → 3.7.0-alpha.0

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

@@ -1,72 +1,78 @@
-import { Fragment } from "react";
-import { NativeScreen } from "../../shared/components/native-screen";
-import { NativeScreenContainer } from "../../shared/components/native-screen-container";
+import {
+	NavigationContext,
+	NavigationRouteContext,
+} from "@react-navigation/native";
+import { Fragment, memo } from "react";
+import {
+	ActivityContainer,
+	ActivityScreen,
+} from "../../shared/components/activity";
 import { Overlay } from "../../shared/components/overlay";
-import { SceneView } from "../../shared/components/scene-view";
 import { ScreenComposer } from "../../shared/providers/screen/screen-composer";
 import { withStackCore } from "../../shared/providers/stack/core.provider";
 import { withManagedStack } from "../../shared/providers/stack/managed.provider";
-import { resolveSceneNeighbors } from "../../shared/utils/navigation/resolve-scene-neighbors";
-import { isFabric } from "../../shared/utils/platform";
+import type { BaseStackScene } from "../../shared/types/stack.types";
 import type {
 	BlankStackDescriptor,
 	BlankStackNavigationHelpers,
 } from "../types";
 
+interface BlankSceneRowProps {
+	scene: BaseStackScene<BlankStackDescriptor>;
+	paintDriverRouteKey?: string;
+}
+
+const BlankSceneRow = memo(function BlankSceneRow({
+	scene,
+	paintDriverRouteKey,
+}: BlankSceneRowProps) {
+	const descriptor = scene.descriptor;
+	const route = scene.route;
+
+	return (
+		<NavigationContext.Provider value={descriptor.navigation}>
+			<NavigationRouteContext.Provider value={route}>
+				<ActivityScreen
+					activity={descriptor.activity}
+					inactiveBehavior={descriptor.options.inactiveBehavior}
+					paintDriverRouteKey={paintDriverRouteKey}
+					hasNestedState={"state" in route}
+				>
+					<ScreenComposer
+						previous={scene.previousDescriptor}
+						current={descriptor}
+						next={scene.nextDescriptor}
+					>
+						{descriptor.render?.()}
+					</ScreenComposer>
+				</ActivityScreen>
+			</NavigationRouteContext.Provider>
+		</NavigationContext.Provider>
+	);
+});
+
 export const StackView = withStackCore(
-	{ TRANSITIONS_ALWAYS_ON: true, DISABLE_NATIVE_SCREENS: true },
+	{ TRANSITIONS_ALWAYS_ON: true, DISABLE_NATIVE_SCREENS: false },
 	withManagedStack<BlankStackDescriptor, BlankStackNavigationHelpers>(
-		({
-			descriptors,
-			focusedIndex,
-			scenes,
-			shouldShowFloatOverlay,
-			closingRouteMap,
-		}) => {
-			const isRouteClosing = (routeKey: string) =>
-				Boolean(closingRouteMap.current[routeKey]);
-
+		({ scenes, shouldShowFloatOverlay }) => {
 			return (
 				<Fragment>
 					{shouldShowFloatOverlay ? <Overlay.Float /> : null}
 
-					<NativeScreenContainer>
-						{scenes.map((scene, sceneIndex) => {
-							const descriptor = scene.descriptor;
+					<ActivityContainer>
+						{scenes.map((scene, index) => {
 							const route = scene.route;
-							const isFocused = focusedIndex === sceneIndex;
-							const isBelowFocused = focusedIndex - 1 === sceneIndex;
-
-							const { previousDescriptor, nextDescriptor } =
-								resolveSceneNeighbors(scenes, sceneIndex, isRouteClosing);
-
-							const isPreloaded = descriptors[route.key] === undefined;
+							const paintDriverRouteKey = scenes[index + 2]?.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 (
-								<NativeScreen
+								<BlankSceneRow
 									key={route.key}
-									isPreloaded={isPreloaded}
-									index={sceneIndex}
-									routeKey={route.key}
-									shouldFreeze={shouldFreeze}
-									freezeOnBlur={descriptor.options.freezeOnBlur}
-								>
-									<ScreenComposer
-										previous={previousDescriptor}
-										current={descriptor}
-										next={nextDescriptor}
-									>
-										<SceneView key={route.key} descriptor={descriptor} />
-									</ScreenComposer>
-								</NativeScreen>
+									scene={scene}
+									paintDriverRouteKey={paintDriverRouteKey}
+								/>
 							);
 						})}
-					</NativeScreenContainer>
+					</ActivityContainer>
 				</Fragment>
 			);
 		},

package/src/blank-stack/index.ts

@@ -8,4 +8,5 @@ export type {
 	BlankStackOptionsArgs,
 	BlankStackOverlayProps,
 	BlankStackScreenProps,
+	InactiveBehavior,
 } from "../blank-stack/types";

package/src/blank-stack/navigators/create-blank-stack-navigator.tsx

@@ -28,7 +28,6 @@ type BlankStackNavigatorInnerProps = Omit<
 	keyof BlankStackFactoryOptions
 > & {
 	DISABLE_NATIVE_SCREENS?: boolean;
-	DISABLE_NATIVE_SCREEN_CONTAINER?: boolean;
 };
 
 const BlankStackContext = React.createContext<boolean>(false);
@@ -42,8 +41,6 @@ function BlankStackNavigatorInner({
 	screenListeners,
 	screenOptions,
 	screenLayout,
-	DISABLE_NATIVE_SCREENS,
-	DISABLE_NATIVE_SCREEN_CONTAINER,
 	...rest
 }: BlankStackNavigatorInnerProps) {
 	const { state, describe, descriptors, navigation, NavigationContent } =
@@ -69,8 +66,6 @@ function BlankStackNavigatorInner({
 		<NavigationContent>
 			<StackView
 				{...rest}
-				DISABLE_NATIVE_SCREENS={DISABLE_NATIVE_SCREENS}
-				DISABLE_NATIVE_SCREEN_CONTAINER={DISABLE_NATIVE_SCREEN_CONTAINER}
 				state={state}
 				navigation={navigation}
 				descriptors={descriptors}
@@ -81,19 +76,18 @@ function BlankStackNavigatorInner({
 }
 
 function BlankStackNavigator({
+	enableNativeScreens,
 	independent = false,
-	enableNativeScreens = true,
+	nativeScreens,
 	...rest
 }: BlankStackNavigatorProps) {
 	const isNested = React.useContext(BlankStackContext);
+	const nativeScreensEnabled = nativeScreens ?? enableNativeScreens ?? true;
 
 	const navigator = (
 		<BlankStackNavigatorInner
 			{...rest}
-			{...(!enableNativeScreens && {
-				DISABLE_NATIVE_SCREENS: true,
-			})}
-			DISABLE_NATIVE_SCREEN_CONTAINER={independent}
+			DISABLE_NATIVE_SCREENS={!nativeScreensEnabled}
 		/>
 	);
 
@@ -137,14 +131,12 @@ type BlankStackTypeBag<
  * Creates a blank stack navigator with gesture-driven transitions.
  *
  * By default, blank stack behaves like the existing top-level blank stack:
- * it participates in the current navigation tree and uses native screen
- * primitives on supported native platforms.
+ * it participates in the current navigation tree and renders screens with
+ * react-native-screens.
  *
  * Blank stack also accepts navigator-specific props for embedded-flow behavior:
+ * - `nativeScreens: false` renders blank-stack screens as regular React Native views
  * - `independent: true` creates an isolated navigator for nested flows
- * - `enableNativeScreens: false` renders the stack with regular views instead
- *   of `react-native-screens`
- *
  * In the dynamic API, pass these to `<Stack.Navigator />`.
  * In the static API, pass them in the same config object as `screens`.
  */

package/src/blank-stack/types.ts

@@ -10,8 +10,11 @@ import type {
 	StackRouterOptions,
 	Theme,
 } from "@react-navigation/native";
-import type { ScreenTransitionConfig } from "../shared";
+import type { InactiveBehavior, ScreenTransitionConfig } from "../shared";
 import type { OverlayProps } from "../shared/types/overlay.types";
+import type { StackSceneActivity } from "../shared/types/stack.types";
+
+export type { InactiveBehavior } from "../shared";
 
 export type BlankStackNavigationEventMap = {};
 
@@ -60,6 +63,24 @@ export type BlankStackNavigationHelpers = NavigationHelpers<
  * The exported name is kept for backward compatibility.
  */
 export interface BlankStackFactoryOptions {
+	/**
+	 * Controls whether blank-stack screens are rendered with react-native-screens.
+	 *
+	 * When enabled, inactive presentation state is backed by
+	 * `ScreenContainer`/`Screen.activityState`. Set this to `false` to render
+	 * screens as regular React Native views.
+	 *
+	 * @default true
+	 */
+	nativeScreens?: boolean;
+
+	/**
+	 * Enables react-native-screens for blank-stack screen retention.
+	 *
+	 * @deprecated Use `nativeScreens` instead.
+	 */
+	enableNativeScreens?: boolean;
+
 	/**
 	 * Creates an isolated navigation tree for embedded flows.
 	 *
@@ -68,22 +89,10 @@ export interface BlankStackFactoryOptions {
 	 *
 	 * When enabled, the navigator:
 	 * - wraps itself in `NavigationIndependentTree` + `NavigationContainer`
-	 * - skips the shared native `ScreenContainer`
 	 *
 	 * Leave this disabled for normal top-level app stacks.
 	 */
 	independent?: boolean;
-	/**
-	 * Enables native screen primitives on supported native platforms.
-	 *
-	 * Use this when you want the embedded blank stack to keep `react-native-screens`
-	 * behavior such as native activity state and freezing.
-	 *
-	 * Set this to `false` when you want the blank stack to render with regular
-	 * views instead of native screen primitives. This is useful for embedded
-	 * flows where plain views are a better fit than native screen layering.
-	 */
-	enableNativeScreens?: boolean;
 }
 
 /**
@@ -94,24 +103,28 @@ export type BlankStackOverlayProps = OverlayProps<
 	BlankStackNavigationProp<ParamListBase>
 >;
 
-type BlankStackScreenTransitionConfig = ScreenTransitionConfig & {
-	/**
-	 * Whether to detach the previous screen from the view hierarchy to save memory.
-	 * Set it to `false` if you need the previous screen to be seen through the active screen.
-	 * Only applicable if `detachInactiveScreens` isn't set to `false`.
-	 */
-	detachPreviousScreen?: boolean;
-};
-
-export type BlankStackNavigationOptions = BlankStackScreenTransitionConfig & {
+export type BlankStackNavigationOptions = ScreenTransitionConfig & {
 	/**
-	 * 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.
-	 * Requires `react-native-screens` version >=3.16.0.
+	 * Controls how inactive blank-stack screens are retained after they are no
+	 * longer active.
+	 *
+	 * For a stack shaped as A(inactive), B(inert), C(active):
+	 *
+	 * - `keep`: keeps A mounted, attached, visible, and non-interactive.
+	 * - `freeze`: keeps A's last painted UI visible and asks the platform to
+	 *   stop or suspend inactive work where possible.
+	 * - `detach`: removes A from native/view presentation after the screen that
+	 *   exposes it has safely painted.
+	 * - `unmount`: removes A's React subtree after safe paint when the route has
+	 *   no nested navigation state.
 	 *
-	 * Only supported on iOS and Android.
+	 * On web, or when native screens are disabled, `keep`, `freeze`, and
+	 * `detach` currently have no meaningful retention effect. This will change
+	 * once the implementation can use React 19.2's Activity component.
+	 *
+	 * @default "detach" on native, "unmount" on web
 	 */
-	freezeOnBlur?: boolean;
+	inactiveBehavior?: InactiveBehavior;
 };
 
 export type BlankStackNavigatorProps = DefaultNavigatorOptions<
@@ -129,4 +142,6 @@ export type BlankStackDescriptor = Descriptor<
 	BlankStackNavigationOptions,
 	BlankStackNavigationProp<ParamListBase>,
 	RouteProp<ParamListBase>
->;
+> & {
+	activity: StackSceneActivity;
+};

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

@@ -5,7 +5,6 @@ import { ScreenComposer } from "../../shared/providers/screen/screen-composer";
 import { withStackCore } from "../../shared/providers/stack/core.provider";
 import { withManagedStack } from "../../shared/providers/stack/managed.provider";
 import { StackType } from "../../shared/types/stack.types";
-import { resolveSceneNeighbors } from "../../shared/utils/navigation/resolve-scene-neighbors";
 import type {
 	ComponentStackDescriptor,
 	ComponentStackNavigationHelpers,
@@ -15,27 +14,21 @@ import { ComponentScreen } from "./component-screen";
 export const StackView = withStackCore(
 	{ TRANSITIONS_ALWAYS_ON: true, STACK_TYPE: StackType.COMPONENT },
 	withManagedStack<ComponentStackDescriptor, ComponentStackNavigationHelpers>(
-		({ scenes, shouldShowFloatOverlay, closingRouteMap }) => {
-			const isRouteClosing = (routeKey: string) =>
-				Boolean(closingRouteMap.current[routeKey]);
-
+		({ scenes, shouldShowFloatOverlay }) => {
 			return (
 				<Fragment>
 					{shouldShowFloatOverlay ? <Overlay.Float /> : null}
 
-					{scenes.map((scene, sceneIndex) => {
+					{scenes.map((scene) => {
 						const descriptor = scene.descriptor;
 						const route = scene.route;
 
-						const { previousDescriptor, nextDescriptor } =
-							resolveSceneNeighbors(scenes, sceneIndex, isRouteClosing);
-
 						return (
 							<ComponentScreen key={route.key} routeKey={route.key}>
 								<ScreenComposer
-									previous={previousDescriptor}
+									previous={scene.previousDescriptor}
 									current={descriptor}
-									next={nextDescriptor}
+									next={scene.nextDescriptor}
 								>
 									<SceneView key={route.key} descriptor={descriptor} />
 								</ScreenComposer>

package/src/component-stack/navigators/create-component-stack-navigator.tsx

@@ -99,7 +99,7 @@ function IsolatedComponentStackNavigator(props: ComponentStackNavigatorProps) {
  * @deprecated Component stack was originally introduced for independent,
  * embedded navigation flows. Blank stack now supports that use case directly
  * via navigator props such as `<BlankStack.Navigator independent />`, with
- * `enableNativeScreens` available when you need to switch between native
+ * `nativeScreens` available when you need to switch between native
  * screens and regular views. Prefer blank stack for new work; component stack
  * will be removed in a future release.
  */

package/src/native-stack/navigators/createNativeStackNavigator.tsx

@@ -62,6 +62,11 @@ function NativeStackNavigator({
 	);
 }
 
+/**
+ * @deprecated The bundled native-stack integration is deprecated and will be removed in a future major release.
+ * Use `@react-navigation/native-stack` or Expo Router's native stack with
+ * `withScreenTransitions` from `react-native-screen-transitions` instead.
+ */
 export function createNativeStackNavigator<
 	const ParamList extends ParamListBase,
 	const NavigatorID extends string | undefined = undefined,

package/src/native-stack/types.ts

@@ -50,6 +50,11 @@ export type NativeStackNavigationEventMap = {
 	sheetDetentChange: { data: { index: number; stable: boolean } };
 };
 
+/**
+ * @deprecated The bundled native-stack integration is deprecated and will be removed in a future major release.
+ * Use `@react-navigation/native-stack` or Expo Router's native stack with
+ * `withScreenTransitions` from `react-native-screen-transitions` instead.
+ */
 export type NativeStackNavigationProp<
 	ParamList extends ParamListBase,
 	RouteName extends keyof ParamList = string,
@@ -64,6 +69,11 @@ export type NativeStackNavigationProp<
 > &
 	StackActionHelpers<ParamList>;
 
+/**
+ * @deprecated The bundled native-stack integration is deprecated and will be removed in a future major release.
+ * Use `@react-navigation/native-stack` or Expo Router's native stack with
+ * `withScreenTransitions` from `react-native-screen-transitions` instead.
+ */
 export type NativeStackScreenProps<
 	ParamList extends ParamListBase,
 	RouteName extends keyof ParamList = string,
@@ -148,6 +158,11 @@ export type NativeStackOverlayProps = OverlayProps<
 	NativeStackNavigationProp<ParamListBase>
 >;
 
+/**
+ * @deprecated The bundled native-stack integration is deprecated and will be removed in a future major release.
+ * Use `NativeStackAdapterOptions` with `withScreenTransitions` from
+ * `react-native-screen-transitions` instead.
+ */
 export type NativeStackScreenTransitionConfig = ScreenTransitionConfig & {
 	/**
 	 * Whether to enable transitions. It sets the presentation to containedTransparentModal, animation none, and headerShown to false.
@@ -155,6 +170,11 @@ export type NativeStackScreenTransitionConfig = ScreenTransitionConfig & {
 	enableTransitions?: boolean;
 };
 
+/**
+ * @deprecated The bundled native-stack integration is deprecated and will be removed in a future major release.
+ * Use `NativeStackAdapterOptions<NativeStackNavigationOptions>` with
+ * `@react-navigation/native-stack` and `withScreenTransitions` instead.
+ */
 export type NativeStackNavigationOptions = NativeStackScreenTransitionConfig & {
 	/**
 	 * String that can be displayed in the header as a fallback for `headerTitle`.
@@ -701,6 +721,11 @@ export type NativeStackNavigationOptions = NativeStackScreenTransitionConfig & {
 	unstable_sheetFooter?: () => React.ReactNode;
 };
 
+/**
+ * @deprecated The bundled native-stack integration is deprecated and will be removed in a future major release.
+ * Use `@react-navigation/native-stack` or Expo Router's native stack with
+ * `withScreenTransitions` from `react-native-screen-transitions` instead.
+ */
 export type NativeStackNavigatorProps = DefaultNavigatorOptions<
 	ParamListBase,
 	string | undefined,

package/src/shared/adapters/with-screen-transitions/context.tsx

@@ -0,0 +1,42 @@
+import { createContext, useContext } from "react";
+import type { BaseStackDescriptor, BaseStackScene } from "../../types";
+
+export type ScreenTransitionsAdapterScene =
+	BaseStackScene<BaseStackDescriptor> & {
+		previousDescriptor?: BaseStackDescriptor;
+		nextDescriptor?: BaseStackDescriptor;
+	};
+
+export interface ScreenTransitionsAdapterContextValue {
+	routeIndexByKey: ReadonlyMap<string, number>;
+	scenes: ScreenTransitionsAdapterScene[];
+}
+
+const ScreenTransitionsAdapterContext =
+	createContext<ScreenTransitionsAdapterContextValue | null>(null);
+
+ScreenTransitionsAdapterContext.displayName = "ScreenTransitionsAdapter";
+
+export function ScreenTransitionsAdapterProvider({
+	children,
+	value,
+}: {
+	children: React.ReactNode;
+	value: ScreenTransitionsAdapterContextValue;
+}) {
+	return (
+		<ScreenTransitionsAdapterContext.Provider value={value}>
+			{children}
+		</ScreenTransitionsAdapterContext.Provider>
+	);
+}
+
+export function useScreenTransitionsAdapterContext() {
+	const context = useContext(ScreenTransitionsAdapterContext);
+	if (!context) {
+		throw new Error(
+			"useScreenTransitionsAdapterContext must be used within withScreenTransitions",
+		);
+	}
+	return context;
+}

package/src/shared/adapters/with-screen-transitions/index.tsx

@@ -0,0 +1,155 @@
+import type {
+	NavigatorTypeBagBase,
+	TypedNavigator,
+} from "@react-navigation/native";
+import type { ComponentType, ReactNode } from "react";
+import {
+	Children,
+	cloneElement,
+	forwardRef,
+	isValidElement,
+	useCallback,
+	useMemo,
+} from "react";
+import type {
+	NativeStackAdapterOptionInput,
+	NativeStackAdapterOptions,
+} from "./options";
+import { adaptNativeStackTransitionOptions } from "./options";
+import {
+	ScreenTransitionsScreenLayout,
+	ScreenTransitionsStackLayout,
+} from "./stack-layout";
+import type {
+	NavigatorLayout,
+	NavigatorLayoutArgs,
+	NavigatorWithScreenTransitions,
+	ScreenLayout,
+	ScreenLayoutArgs,
+} from "./types";
+
+export type {
+	NativeStackAdapterOptions,
+	NativeStackNativeGestureOptions,
+	ScreenTransitionDescriptorOptions,
+} from "./options";
+export { resolveScreenTransitionOptions } from "./options";
+
+type ScreenTransitionsNavigatorProps = {
+	layout?: NavigatorLayout;
+	screenLayout?: ScreenLayout;
+	[key: string]: any;
+};
+
+type ScreenTransitionsNavigatorTypeBag<TBag extends NavigatorTypeBagBase> =
+	Omit<TBag, "ScreenOptions"> & {
+		ScreenOptions: NativeStackAdapterOptions<TBag["ScreenOptions"]>;
+	};
+
+function adaptNavigatorChildren(children: ReactNode): ReactNode {
+	return Children.map(children, (child) => {
+		if (!isValidElement(child)) {
+			return child;
+		}
+
+		const props = child.props as Record<string, unknown>;
+		const nextProps: Record<string, unknown> = {};
+		let changed = false;
+
+		if ("options" in props) {
+			nextProps.options = adaptNativeStackTransitionOptions(
+				props.options as NativeStackAdapterOptionInput | undefined,
+			);
+			changed = true;
+		}
+
+		if ("screenOptions" in props) {
+			nextProps.screenOptions = adaptNativeStackTransitionOptions(
+				props.screenOptions as NativeStackAdapterOptionInput | undefined,
+			);
+			changed = true;
+		}
+
+		if (props.children !== undefined && typeof props.children !== "function") {
+			nextProps.children = adaptNavigatorChildren(props.children as ReactNode);
+			changed = true;
+		}
+
+		if (!changed) {
+			return child;
+		}
+
+		return cloneElement(child, nextProps);
+	});
+}
+
+export function withScreenTransitions<
+	TBag extends NavigatorTypeBagBase,
+	TConfig,
+>(
+	navigator: TypedNavigator<TBag, TConfig>,
+): TypedNavigator<ScreenTransitionsNavigatorTypeBag<TBag>, TConfig>;
+export function withScreenTransitions<
+	TNavigator extends NavigatorWithScreenTransitions,
+>(navigator: TNavigator): TNavigator;
+export function withScreenTransitions(
+	navigator: NavigatorWithScreenTransitions,
+): any {
+	const BaseNavigator = navigator.Navigator as ComponentType<any>;
+
+	const Navigator = forwardRef<unknown, ScreenTransitionsNavigatorProps>(
+		function ScreenTransitionsNavigator(
+			{ layout, screenLayout, ...props },
+			ref,
+		) {
+			const transitionLayout = useCallback(
+				(layoutArgs: NavigatorLayoutArgs) => (
+					<ScreenTransitionsStackLayout
+						layout={layout}
+						layoutArgs={layoutArgs}
+					/>
+				),
+				[layout],
+			);
+
+			const transitionScreenLayout = useCallback(
+				(screenLayoutArgs: ScreenLayoutArgs) => (
+					<ScreenTransitionsScreenLayout
+						screenLayout={screenLayout}
+						screenLayoutArgs={screenLayoutArgs}
+					/>
+				),
+				[screenLayout],
+			);
+			const screenOptions = useMemo(
+				() => adaptNativeStackTransitionOptions(props.screenOptions),
+				[props.screenOptions],
+			);
+			const children = useMemo(
+				() => adaptNavigatorChildren(props.children),
+				[props.children],
+			);
+
+			return (
+				<BaseNavigator
+					{...props}
+					screenOptions={screenOptions}
+					ref={ref as never}
+					layout={transitionLayout}
+					screenLayout={transitionScreenLayout}
+				>
+					{children}
+				</BaseNavigator>
+			);
+		},
+	);
+
+	Navigator.displayName = `withScreenTransitions(${
+		BaseNavigator.displayName ?? BaseNavigator.name ?? "Navigator"
+	})`;
+
+	return {
+		...navigator,
+		Navigator,
+	};
+}