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

package/src/component-stack/types.ts

@@ -0,0 +1,209 @@
+import type { DerivedValue } from "react-native-reanimated";
+import type { ScreenTransitionConfig } from "../shared";
+import type {
+	OverlayInterpolationProps,
+	ScreenInterpolationProps,
+} from "../shared/types/animation.types";
+import type { OverlayMode } from "../shared/types/overlay.types";
+
+/**
+ * A synthetic route object for component navigation.
+ * Mimics React Navigation's Route type but without the navigation dependency.
+ */
+export interface ComponentRoute<Params = Record<string, unknown>> {
+	/** Unique identifier for this route instance */
+	key: string;
+	/** Name identifier for the screen */
+	name: string;
+	/** Optional parameters passed to the screen */
+	params?: Params;
+}
+
+/**
+ * Navigation action for dispatch method.
+ */
+type ComponentNavigationAction =
+	| { type: "PUSH"; name: string; params?: Record<string, unknown> }
+	| { type: "POP" }
+	| { type: "POP_BY_KEY"; key: string }
+	| { type: "NAVIGATE"; name: string; params?: Record<string, unknown> }
+	| { type: "RESET"; name?: string; params?: Record<string, unknown> }
+	| { type: string; source?: string; target?: string; payload?: unknown };
+
+/**
+ * Navigation object provided to screens and available via useComponentNavigation hook.
+ */
+export interface ComponentNavigation {
+	/** Push a new screen by name */
+	push: (name: string, params?: Record<string, unknown>) => void;
+	/** Pop the current screen */
+	pop: () => void;
+	/** Navigate back (alias for pop) */
+	goBack: () => void;
+	/** Navigate to a specific screen by name, reusing existing if present */
+	navigate: (name: string, params?: Record<string, unknown>) => void;
+	/** Check if we can go back */
+	canGoBack: () => boolean;
+	/** Reset to a specific screen or initial state */
+	reset: (name?: string, params?: Record<string, unknown>) => void;
+	/** Dispatch a navigation action (compatible with React Navigation's StackActions) */
+	dispatch: (action: ComponentNavigationAction) => void;
+	/** Get current navigation state (for gesture handling compatibility) */
+	getState: () => ComponentStackState;
+	/** Current index in the stack */
+	index: number;
+}
+
+/**
+ * Screen options for component stack, extending the base transition config.
+ */
+export type ComponentStackScreenTransitionConfig = 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.
+	 */
+	detachPreviousScreen?: boolean;
+};
+
+/**
+ * Props passed to overlay components.
+ */
+export type ComponentStackOverlayProps = {
+	/** Route of the currently focused screen in the stack. */
+	focusedRoute: ComponentRoute;
+	/** Index of the focused route in the stack. */
+	focusedIndex: number;
+	/** All routes currently in the stack. */
+	routes: ComponentRoute[];
+	/** Custom metadata from the focused screen's options. */
+	meta?: Record<string, unknown>;
+	/** Navigation object for the overlay. */
+	navigation: ComponentNavigation;
+	/** Animation values for the overlay. */
+	overlayAnimation: DerivedValue<OverlayInterpolationProps>;
+	/** Animation values for the screen. */
+	screenAnimation: DerivedValue<ScreenInterpolationProps>;
+};
+
+/**
+ * Props passed to container overlay components.
+ * Extends overlay props with children to wrap screen content.
+ */
+export type ComponentStackContainerOverlayProps = ComponentStackOverlayProps & {
+	/** The screen content to be wrapped by the container overlay. */
+	children: React.ReactNode;
+};
+
+/**
+ * Full navigation options for a component stack screen.
+ */
+export type ComponentStackNavigationOptions =
+	ComponentStackScreenTransitionConfig & {
+		/** Function that returns a React Element to display as overlay. */
+		overlay?:
+			| ((props: ComponentStackOverlayProps) => React.ReactNode)
+			| ((props: ComponentStackContainerOverlayProps) => React.ReactNode);
+		/**
+		 * Layout: How the Overlay is positioned
+		 * - 'float': Single persistent overlay above all screens (like iOS)
+		 * - 'screen': Per-screen overlay that transitions with content
+		 * - 'container': Wraps all screen content (for MaskedView, custom containers)
+		 * @default 'screen'
+		 */
+		overlayMode?: OverlayMode;
+		/** Whether to show the overlay. Defaults to true when overlay is provided. */
+		overlayShown?: boolean;
+		/**
+		 * Whether inactive screens should be suspended from re-rendering.
+		 * Defaults to `true` when `enableFreeze()` is run at the top of the application.
+		 */
+		freezeOnBlur?: boolean;
+	};
+
+/**
+ * Descriptor for a component stack screen.
+ * Similar to React Navigation's Descriptor but simplified.
+ */
+export interface ComponentStackDescriptor {
+	/** The route object for this screen */
+	route: ComponentRoute;
+	/** Navigation object */
+	navigation: ComponentNavigation;
+	/** Render function for the screen content */
+	render: () => React.JSX.Element | null;
+	/** Screen options/configuration */
+	options: ComponentStackNavigationOptions;
+}
+
+/**
+ * A scene in the component stack (route + descriptor pair).
+ */
+export interface ComponentStackScene {
+	route: ComponentRoute;
+	descriptor: ComponentStackDescriptor;
+}
+
+/**
+ * Map of route keys to descriptors.
+ */
+export type ComponentStackDescriptorMap = {
+	[key: string]: ComponentStackDescriptor;
+};
+
+/**
+ * Props passed to screen components.
+ */
+export interface ComponentStackScreenProps<Params = Record<string, unknown>> {
+	/** Navigation object for controlling the stack */
+	navigation: ComponentNavigation;
+	/** Route object with params */
+	route: ComponentRoute<Params>;
+}
+
+/**
+ * State of the component navigation stack.
+ */
+export interface ComponentStackState {
+	/** All routes in the stack */
+	routes: ComponentRoute[];
+	/** Index of the currently focused route */
+	index: number;
+	/** Unique key for this stack instance */
+	key: string;
+}
+
+/**
+ * Screen definition for the component navigator.
+ */
+export interface ComponentScreenConfig {
+	/** Unique name for this screen */
+	name: string;
+	/** Component to render for this screen */
+	component: React.ComponentType<ComponentStackScreenProps<any>>;
+	/** Screen-specific options */
+	options?: ComponentStackNavigationOptions;
+}
+
+/**
+ * Props for the ComponentNavigator component.
+ */
+export interface ComponentNavigatorProps {
+	/** Screen definitions */
+	children: React.ReactNode;
+	/** Initial screen name to display */
+	initialRouteName?: string;
+	/** Default options applied to all screens */
+	screenOptions?: ComponentStackNavigationOptions;
+}
+
+/**
+ * Props for the ComponentScreen component.
+ */
+export interface ComponentScreenProps {
+	/** Unique name for this screen */
+	name: string;
+	/** Component to render */
+	component: React.ComponentType<ComponentStackScreenProps<any>>;
+	/** Screen-specific options */
+	options?: ComponentStackNavigationOptions;
+}

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

@@ -1,16 +1,16 @@
 /** 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";
+import { useHighRefreshRate } from "../../shared/hooks/animation/use-high-refresh-rate";
+import { useSharedValueState } from "../../shared/hooks/reanimated/use-shared-value-state";
+import useStableCallback from "../../shared/hooks/use-stable-callback";
+import { useGestureContext } from "../../shared/providers/gestures.provider";
+import { useKeys } from "../../shared/providers/screen/keys.provider";
+import { AnimationStore } from "../../shared/stores/animation.store";
+import { TRUE } from "../../shared/types/state.types";
+import { startScreenTransition } from "../../shared/utils/animation/start-screen-transition";
+import { resetStoresForScreen } from "../../shared/utils/reset-stores-for-screen";
+import type { NativeStackDescriptor } from "../types";
 
 export interface Props {
 	children: React.ReactNode;
@@ -34,7 +34,10 @@ export const NativeStackScreenLifecycleController = ({ children }: Props) => {
 
 	const animations = AnimationStore.getAll(current.route.key);
 
-	const handleBeforeRemove = useStableCallback((e: Any) => {
+	const { deactivateHighRefreshRate, activateHighRefreshRate } =
+		useHighRefreshRate(current);
+
+	const handleBeforeRemove = useStableCallback((e: any) => {
 		const isEnabled = current.options.enableTransitions;
 
 		const isFirstScreen = current.navigation.getState().index === 0;
@@ -47,7 +50,9 @@ export const NativeStackScreenLifecycleController = ({ children }: Props) => {
 		}
 
 		e.preventDefault();
+		activateHighRefreshRate();
 		const onAnimationFinish = (finished: boolean) => {
+			deactivateHighRefreshRate();
 			if (finished) {
 				current.navigation.dispatch(e.data.action);
 
@@ -67,10 +72,12 @@ export const NativeStackScreenLifecycleController = ({ children }: Props) => {
 	});
 
 	const handleInitialize = useStableCallback(() => {
+		activateHighRefreshRate();
 		startScreenTransition({
 			target: "open",
 			spec: current.options.transitionSpec,
 			animations,
+			onAnimationFinish: deactivateHighRefreshRate,
 		});
 	});
 

package/src/native-stack/index.ts

@@ -8,5 +8,6 @@ export type {
 	NativeStackNavigationProp,
 	NativeStackNavigatorProps,
 	NativeStackOptionsArgs,
+	NativeStackOverlayProps,
 	NativeStackScreenProps,
 } from "./types";

package/src/native-stack/types.ts

@@ -22,12 +22,8 @@ import type {
 	ScreenStackHeaderConfigProps,
 	SearchBarProps,
 } from "react-native-screens";
-import type { ScreenTransitionConfig } from "../shared/types/core.types";
-
-export type Layout = {
-	width: number;
-	height: number;
-};
+import type { OverlayProps } from "../shared/types/overlay.types";
+import type { ScreenTransitionConfig } from "../shared/types/screen.types";
 
 export type NativeStackNavigationEventMap = {
 	/**
@@ -90,7 +86,7 @@ export type NativeStackNavigationHelpers = NavigationHelpers<
 >;
 
 // We want it to be an empty object because navigator does not have any additional props
-export type NativeStackNavigationConfig = {};
+type NativeStackNavigationConfig = {};
 
 export type NativeStackHeaderProps = {
 	/**
@@ -143,6 +139,14 @@ export type NativeStackHeaderLeftProps = NativeStackHeaderRightProps & {
 	href?: string;
 };
 
+/**
+ * Props passed to overlay components in native-stack.
+ * Uses the shared OverlayProps type with native-stack's navigation type.
+ */
+export type NativeStackOverlayProps = OverlayProps<
+	NativeStackNavigationProp<ParamListBase>
+>;
+
 export type NativeStackScreenTransitionConfig = ScreenTransitionConfig & {
 	/**
 	 * Whether to enable transitions. It sets the presentation to containedTransparentModal, animation none, and headerShown to false.

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,52 +482,33 @@ 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>
+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}
+				<Overlay.Container>
 					<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;
+						{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
@@ -541,10 +518,6 @@ export function NativeStackView({
 
 							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()
@@ -633,11 +606,11 @@ export function NativeStackView({
 							);
 						})}
 					</ScreenStack>
-				</SafeAreaProviderCompat>
-			</GestureHandlerRootView>
-		</RoutesProvider>
-	);
-}
+				</Overlay.Container>
+			</>
+		);
+	}),
+);
 
 const styles = StyleSheet.create({
 	container: {