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

package/src/shared/providers/stack/managed.provider.tsx

@@ -0,0 +1,226 @@
+import type { Route } from "@react-navigation/native";
+import * as React from "react";
+import { useMemo } from "react";
+import {
+	type DerivedValue,
+	type SharedValue,
+	useDerivedValue,
+} from "react-native-reanimated";
+import {
+	StackContext,
+	type StackContextValue,
+} from "../../hooks/navigation/use-stack";
+import { AnimationStore } from "../../stores/animation.store";
+import type {
+	BaseStackDescriptor,
+	BaseStackNavigation,
+	BaseStackRoute,
+	BaseStackScene,
+	BaseStackState,
+} from "../../types/stack.types";
+import { calculateActiveScreensLimit } from "./helpers/active-screens-limit";
+import { useLocalRoutes } from "./helpers/use-local-routes";
+
+/**
+ * Props for managed stack - generic over descriptor and navigation types.
+ * Defaults to base types for backward compatibility.
+ */
+export interface ManagedStackProps<
+	TDescriptor extends BaseStackDescriptor = BaseStackDescriptor,
+	TNavigation extends BaseStackNavigation = BaseStackNavigation,
+> {
+	state: BaseStackState<TDescriptor["route"]>;
+	navigation: TNavigation;
+	descriptors: Record<string, TDescriptor>;
+	describe: (route: TDescriptor["route"], placeholder: boolean) => TDescriptor;
+}
+
+/**
+ * Context value for managed stack - generic over descriptor type.
+ */
+interface ManagedStackContextValue<
+	TDescriptor extends BaseStackDescriptor = BaseStackDescriptor,
+> {
+	routes: TDescriptor["route"][];
+	descriptors: Record<string, TDescriptor>;
+	scenes: BaseStackScene<TDescriptor>[];
+	activeScreensLimit: number;
+	closingRouteKeysShared: SharedValue<string[]>;
+	handleCloseRoute: (payload: { route: BaseStackRoute }) => void;
+	shouldShowFloatOverlay: boolean;
+	focusedIndex: number;
+	stackProgress: DerivedValue<number>;
+	optimisticFocusedIndex: DerivedValue<number>;
+}
+
+const ManagedStackContext =
+	React.createContext<ManagedStackContextValue | null>(null);
+ManagedStackContext.displayName = "ManagedStack";
+
+function useManagedStackContext<
+	TDescriptor extends BaseStackDescriptor = BaseStackDescriptor,
+>(): ManagedStackContextValue<TDescriptor> {
+	const context = React.useContext(ManagedStackContext);
+	if (!context) {
+		throw new Error(
+			"useManagedStackContext must be used within ManagedStackProvider",
+		);
+	}
+	return context as ManagedStackContextValue<TDescriptor>;
+}
+
+function useManagedStackValue<
+	TDescriptor extends BaseStackDescriptor,
+	TNavigation extends BaseStackNavigation,
+>(
+	props: ManagedStackProps<TDescriptor, TNavigation>,
+): ManagedStackContextValue<TDescriptor> & {
+	stackContextValue: StackContextValue;
+} {
+	const { state, handleCloseRoute, closingRouteKeys } = useLocalRoutes(props);
+
+	const { scenes, activeScreensLimit, shouldShowFloatOverlay, routeKeys } =
+		useMemo(() => {
+			const scenes: BaseStackScene<TDescriptor>[] = [];
+			const routeKeys: string[] = [];
+			let shouldShowFloatOverlay = false;
+
+			for (const route of state.routes) {
+				const descriptor = state.descriptors[route.key] as TDescriptor;
+				scenes.push({ route, descriptor });
+				routeKeys.push(route.key);
+
+				if (!shouldShowFloatOverlay) {
+					const options = descriptor?.options;
+					shouldShowFloatOverlay =
+						options?.overlayMode === "float" && options?.overlayShown === true;
+				}
+			}
+
+			return {
+				scenes,
+				routeKeys,
+				activeScreensLimit: calculateActiveScreensLimit(
+					state.routes,
+					state.descriptors,
+				),
+				shouldShowFloatOverlay,
+			};
+		}, [state.routes, state.descriptors]);
+
+	// Get animation store maps for LOCAL routes (including closing routes)
+	const animationMaps = useMemo(
+		() => state.routes.map((route) => AnimationStore.getAll(route.key)),
+		[state.routes],
+	);
+
+	// Aggregated stack progress from LOCAL routes (includes closing routes)
+	const stackProgress = useDerivedValue(() => {
+		"worklet";
+		let total = 0;
+		for (let i = 0; i < animationMaps.length; i++) {
+			total += animationMaps[i].progress.value;
+		}
+		return total;
+	});
+
+	// Optimistic focused index: accounts for closing screens
+	const optimisticFocusedIndex = useDerivedValue(() => {
+		"worklet";
+		const currentIndex = animationMaps.length - 1;
+		let isAnyClosing = false;
+		for (let i = 0; i < animationMaps.length; i++) {
+			if (animationMaps[i].closing.value > 0) {
+				isAnyClosing = true;
+				break;
+			}
+		}
+		return currentIndex - Number(isAnyClosing);
+	});
+
+	const focusedIndex = props.state.index;
+
+	// StackContext value - for overlays via useStack()
+	const stackContextValue = useMemo<StackContextValue>(
+		() => ({
+			flags: { TRANSITIONS_ALWAYS_ON: true },
+			routeKeys,
+			routes: state.routes as Route<string>[],
+			descriptors: state.descriptors as Record<string, BaseStackDescriptor>,
+			scenes: scenes as BaseStackScene[],
+			focusedIndex,
+			stackProgress,
+			optimisticFocusedIndex,
+		}),
+		[
+			routeKeys,
+			state.routes,
+			state.descriptors,
+			scenes,
+			focusedIndex,
+			stackProgress,
+			optimisticFocusedIndex,
+		],
+	);
+
+	// ManagedStack context value
+	const lifecycleValue = useMemo<ManagedStackContextValue<TDescriptor>>(
+		() => ({
+			routes: state.routes,
+			focusedIndex,
+			descriptors: state.descriptors,
+			closingRouteKeysShared: closingRouteKeys.shared,
+			activeScreensLimit,
+			handleCloseRoute,
+			scenes,
+			shouldShowFloatOverlay,
+			stackProgress,
+			optimisticFocusedIndex,
+		}),
+		[
+			state.routes,
+			state.descriptors,
+			focusedIndex,
+			closingRouteKeys.shared,
+			activeScreensLimit,
+			handleCloseRoute,
+			scenes,
+			shouldShowFloatOverlay,
+			stackProgress,
+			optimisticFocusedIndex,
+		],
+	);
+
+	return { ...lifecycleValue, stackContextValue };
+}
+
+/**
+ * HOC that wraps component with ManagedStack provider AND StackContext.
+ * Used by blank-stack and component-stack which manage local route state for closing animations.
+ * Generic over descriptor type - defaults to BaseStackDescriptor.
+ */
+function withManagedStack<
+	TDescriptor extends BaseStackDescriptor = BaseStackDescriptor,
+	TNavigation extends BaseStackNavigation = BaseStackNavigation,
+>(
+	Component: React.ComponentType<ManagedStackContextValue<TDescriptor>>,
+): React.FC<ManagedStackProps<TDescriptor, TNavigation>> {
+	return function ManagedStackProvider(
+		props: ManagedStackProps<TDescriptor, TNavigation>,
+	) {
+		const { stackContextValue, ...lifecycleValue } = useManagedStackValue<
+			TDescriptor,
+			TNavigation
+		>(props);
+
+		return (
+			<StackContext.Provider value={stackContextValue}>
+				<ManagedStackContext.Provider value={lifecycleValue}>
+					<Component {...lifecycleValue} />
+				</ManagedStackContext.Provider>
+			</StackContext.Provider>
+		);
+	};
+}
+
+export { useManagedStackContext, withManagedStack };

package/src/shared/stores/animation.store.ts

@@ -3,7 +3,7 @@ import {
 	makeMutable,
 	type SharedValue,
 } from "react-native-reanimated";
-import type { ScreenKey } from "../types/core.types";
+import type { ScreenKey } from "../types/screen.types";
 
 export type AnimationStoreMap = {
 	progress: SharedValue<number>;

package/src/shared/stores/bounds.store.ts

@@ -3,7 +3,6 @@ import {
 	makeMutable,
 	type StyleProps,
 } from "react-native-reanimated";
-import type { Any } from "../types/utils.types";
 
 type TagID = string;
 type ScreenKey = string;
@@ -38,7 +37,7 @@ function registerSnapshot(
 	ancestorKeys?: ScreenKey[],
 ) {
 	"worklet";
-	registry.modify((state: Any) => {
+	registry.modify((state: any) => {
 		"worklet";
 		if (!state[tag]) {
 			state[tag] = { snapshots: {}, linkStack: [] };
@@ -56,7 +55,7 @@ function setLinkSource(
 	ancestorKeys?: ScreenKey[],
 ) {
 	"worklet";
-	registry.modify((state: Any) => {
+	registry.modify((state: any) => {
 		"worklet";
 		if (!state[tag]) state[tag] = { snapshots: {}, linkStack: [] };
 
@@ -76,7 +75,7 @@ function setLinkDestination(
 	ancestorKeys?: ScreenKey[],
 ) {
 	"worklet";
-	registry.modify((state: Any) => {
+	registry.modify((state: any) => {
 		"worklet";
 		const stack = state[tag]?.linkStack;
 		if (!stack || stack.length === 0) return state;
@@ -173,7 +172,7 @@ function getActiveLink(tag: TagID, screenKey?: ScreenKey): TagLink | null {
  */
 function clear(screenKey: ScreenKey) {
 	"worklet";
-	registry.modify((state: Any) => {
+	registry.modify((state: any) => {
 		"worklet";
 		for (const tag in state) {
 			// Remove snapshot

package/src/shared/stores/gesture.store.ts

@@ -3,10 +3,10 @@ import {
 	makeMutable,
 	type SharedValue,
 } from "react-native-reanimated";
-import type { ScreenKey } from "../types/core.types";
 import type { GestureDirection } from "../types/gesture.types";
+import type { ScreenKey } from "../types/screen.types";
 
-export type GestureKey =
+type GestureKey =
 	| "x"
 	| "y"
 	| "normalizedX"

package/src/shared/types/animation.types.ts

@@ -1,13 +1,13 @@
-import type { ParamListBase, RouteProp } from "@react-navigation/native";
 import type {
 	StyleProps,
 	WithSpringConfig,
 	WithTimingConfig,
 } from "react-native-reanimated";
 import type { EdgeInsets } from "react-native-safe-area-context";
+import type { BaseRoute } from "../providers/screen/keys.provider";
 import type { BoundsAccessor } from "./bounds.types";
-import type { Layout } from "./core.types";
 import type { GestureValues } from "./gesture.types";
+import type { Layout } from "./screen.types";
 
 export interface OverlayInterpolationProps {
 	progress: number;
@@ -74,7 +74,7 @@ export type ScreenTransitionState = {
 	 * Pass route params via options: `options={({ route }) => ({ meta: { id: route.params.id } })}`
 	 * This field may be removed in a future version.
 	 */
-	route: RouteProp<ParamListBase>;
+	route: BaseRoute;
 };
 
 export interface ScreenInterpolationProps {
@@ -147,13 +147,21 @@ export interface ScreenInterpolationProps {
 	 */
 	active: ScreenTransitionState;
 
+	/**
+	 * The screen state that is NOT driving the transition.
+	 * When focused, this is the previous screen. When not focused, this is the current screen.
+	 */
+	inactive: ScreenTransitionState | undefined;
+
 	/**
 	 * Whether the active screen is currently transitioning (either being dragged or animating).
+	 * @deprecated Use `active.animating` instead.
 	 */
 	isActiveTransitioning: boolean;
 
 	/**
 	 * Whether the active screen is in the process of being dismissed/closed.
+	 * @deprecated Use `active.closing` instead.
 	 */
 	isDismissing: boolean;
 }

package/src/shared/types/gesture.types.ts

@@ -20,8 +20,6 @@ export enum GestureOffsetState {
 	FAILED,
 }
 
-export type AxisActivation = ActivationArea | SideActivation;
-
 export type GestureActivationArea = ActivationArea | SideActivation;
 
 export type GestureValues = {

package/src/shared/types/index.ts

@@ -0,0 +1,47 @@
+export type {
+	AnimationConfig,
+	OverlayInterpolationProps,
+	ScreenInterpolationProps,
+	ScreenStyleInterpolator,
+	ScreenTransitionState,
+	TransitionInterpolatedStyle,
+	TransitionSpec,
+} from "./animation.types";
+
+export type {
+	BoundEntry,
+	BoundsAccessor,
+	BoundsLink,
+	BoundsMethod,
+} from "./bounds.types";
+
+export type {
+	ActivationArea,
+	GestureActivationArea,
+	GestureDirection,
+	GestureValues,
+	SideActivation,
+} from "./gesture.types";
+
+export type {
+	ContainerOverlayProps,
+	OverlayMode,
+	OverlayProps,
+} from "./overlay.types";
+
+export type {
+	Layout,
+	ScreenKey,
+	ScreenTransitionConfig,
+	TransitionAwareProps,
+} from "./screen.types";
+
+export type {
+	BaseStackDescriptor,
+	BaseStackNavigation,
+	BaseStackRoute,
+	BaseStackScene,
+	BaseStackState,
+} from "./stack.types";
+
+export { FALSE, TRUE } from "./state.types";

package/src/shared/types/overlay.types.ts

@@ -0,0 +1,62 @@
+import type { Route } from "@react-navigation/native";
+import type { DerivedValue } from "react-native-reanimated";
+import type {
+	OverlayInterpolationProps,
+	ScreenInterpolationProps,
+} from "./animation.types";
+
+export type OverlayMode = "float" | "screen" | "container";
+
+/**
+ * Props passed to overlay components.
+ * Generic over the navigation type since different stacks have different navigation props.
+ */
+export type OverlayProps<TNavigation = unknown> = {
+	/**
+	 * Route of the currently focused screen in the stack.
+	 */
+	focusedRoute: Route<string>;
+
+	/**
+	 * Index of the focused route in the stack.
+	 */
+	focusedIndex: number;
+
+	/**
+	 * All routes currently in the stack.
+	 */
+	routes: Route<string>[];
+
+	/**
+	 * Custom metadata from the focused screen's options.
+	 */
+	meta?: Record<string, unknown>;
+
+	/**
+	 * Navigation prop for the overlay.
+	 */
+	navigation: TNavigation;
+
+	/**
+	 * Animation values for the overlay.
+	 */
+	overlayAnimation: DerivedValue<OverlayInterpolationProps>;
+
+	/**
+	 * Animation values for the screen.
+	 */
+	screenAnimation: DerivedValue<ScreenInterpolationProps>;
+};
+
+/**
+ * Props passed to container overlay components.
+ * Extends OverlayProps with children - the screen content to wrap.
+ */
+export type ContainerOverlayProps<TNavigation = unknown> =
+	OverlayProps<TNavigation> & {
+		/**
+		 * The screen content to be wrapped by the container overlay.
+		 * This allows the overlay to act as a wrapper (e.g., MaskedView) around screens.
+		 */
+		children: React.ReactNode;
+	};

package/src/shared/types/{core.types.ts → screen.types.ts}

@@ -4,6 +4,11 @@ import type {
 	TransitionSpec,
 } from "./animation.types";
 import type { GestureActivationArea, GestureDirection } from "./gesture.types";
+import type {
+	ContainerOverlayProps,
+	OverlayMode,
+	OverlayProps,
+} from "./overlay.types";
 
 export type Layout = {
 	width: number;
@@ -12,8 +17,6 @@ export type Layout = {
 
 export type ScreenKey = string;
 
-export type ScreenPhase = "previous" | "current" | "next";
-
 export type TransitionAwareProps<T extends object> = AnimatedProps<T> & {
 	/**
 	 * Connects this component to custom animated styles defined in screenStyleInterpolator.
@@ -55,11 +58,6 @@ export type TransitionAwareProps<T extends object> = AnimatedProps<T> & {
 	sharedBoundTag?: string;
 };
 
-export type TransitionConfig = {
-	open: TransitionSpec;
-	close: TransitionSpec;
-};
-
 export type ScreenTransitionConfig = {
 	/**
 	 * The user-provided function to calculate styles based on animation progress.
@@ -108,4 +106,39 @@ export type ScreenTransitionConfig = {
 	 * options={{ meta: { scalesOthers: true } }}
 	 */
 	meta?: Record<string, unknown>;
+
+	/**
+	 * Function that returns a React Element to display as an overlay.
+	 * For container overlays (overlayMode: 'container'), use ContainerOverlayProps which includes children.
+	 */
+	overlay?:
+		| ((props: OverlayProps) => React.ReactNode)
+		| ((props: ContainerOverlayProps) => React.ReactNode);
+
+	/**
+	 * How the overlay is positioned relative to screens.
+	 * - 'float': Single persistent overlay above all screens (like iOS tab bar)
+	 * - 'screen': Per-screen overlay that transitions with content
+	 * - 'container': Wraps all screen content, receives children prop (for MaskedView, custom containers)
+	 * @default 'screen'
+	 */
+	overlayMode?: OverlayMode;
+
+	/**
+	 * Whether to show the overlay. The overlay is shown by default when `overlay` is provided.
+	 * Setting this to `false` hides the overlay.
+	 */
+	overlayShown?: boolean;
+
+	/**
+	 * Forces the display to run at its maximum refresh rate during screen transitions.
+	 * Prevents iOS/Android from throttling to 60fps for battery savings.
+	 *
+	 * Useful for smoother animations on high refresh rate displays (90/120/144Hz).
+	 * Note: Increases battery usage while active.
+	 *
+	 * @experimental This API may change in future versions.
+	 * @default false
+	 */
+	experimental_enableHighRefreshRate?: boolean;
 };

package/src/shared/types/stack.types.ts

@@ -0,0 +1,59 @@
+import type { ScreenTransitionConfig } from "./screen.types";
+
+/**
+ * Base route interface - minimal contract all stacks satisfy.
+ * React Navigation routes and ComponentStack routes both extend this.
+ * Uses `object` for params to be compatible with React Navigation's `Readonly<object | undefined>`.
+ */
+export interface BaseStackRoute {
+	key: string;
+	name: string;
+	params?: object;
+}
+
+/**
+ * Base navigation interface - minimal contract for gesture handling.
+ * Both React Navigation helpers and ComponentNavigation satisfy this.
+ */
+export interface BaseStackNavigation {
+	getState: () => { routes: Array<{ key: string }>; key: string };
+	dispatch: (action: any) => void;
+}
+
+/**
+ * Base descriptor interface - generic over route, navigation, and options.
+ * All stack descriptors (BlankStack, NativeStack, ComponentStack) extend this.
+ */
+export interface BaseStackDescriptor<
+	TRoute extends BaseStackRoute = BaseStackRoute,
+	TNavigation extends BaseStackNavigation = BaseStackNavigation,
+	TOptions extends ScreenTransitionConfig = ScreenTransitionConfig,
+> {
+	route: TRoute;
+	navigation: TNavigation;
+	options: TOptions;
+	render?: () => React.JSX.Element | null;
+}
+
+/**
+ * Base scene interface - route + descriptor pair.
+ * Used by all stack views to iterate over screens.
+ */
+export interface BaseStackScene<
+	TDescriptor extends BaseStackDescriptor = BaseStackDescriptor,
+> {
+	route: TDescriptor["route"];
+	descriptor: TDescriptor;
+}
+
+/**
+ * Base state interface - routes array with index.
+ * Common structure across all navigation states.
+ */
+export interface BaseStackState<
+	TRoute extends BaseStackRoute = BaseStackRoute,
+> {
+	routes: TRoute[];
+	index: number;
+	key: string;
+}

package/src/shared/utils/animation/derivations.ts

@@ -1,6 +1,7 @@
 import type { ScreenTransitionState } from "../../types/animation.types";
 
 interface DerivationsParams {
+	previous?: ScreenTransitionState;
 	current: ScreenTransitionState;
 	next?: ScreenTransitionState;
 }
@@ -8,7 +9,7 @@ interface DerivationsParams {
 /**
  * Additional values to help make defining animations easier.
  */
-export const derivations = ({ current, next }: DerivationsParams) => {
+export const derivations = ({ previous, current, next }: DerivationsParams) => {
 	"worklet";
 
 	// The combined progress (current + next, 0-2 range)
@@ -17,7 +18,12 @@ export const derivations = ({ current, next }: DerivationsParams) => {
 	// Whether the current screen is focused
 	const focused = !next;
 
+	// The screen driving the transition
 	const active = focused ? current : (next ?? current);
+
+	// The screen NOT driving the transition
+	const inactive = focused ? previous : current;
+
 	const isActiveTransitioning = !!(
 		active.gesture.isDragging || active.animating
 	);
@@ -28,6 +34,7 @@ export const derivations = ({ current, next }: DerivationsParams) => {
 		progress,
 		focused,
 		active,
+		inactive,
 		isActiveTransitioning,
 		isDismissing,
 	};

package/src/shared/utils/bounds/helpers/geometry.ts

@@ -1,5 +1,5 @@
 import type { MeasuredDimensions } from "react-native-reanimated";
-import type { Layout } from "../../../types/core.types";
+import type { Layout } from "../../../types/screen.types";
 import type { BoundsAnchor, BoundsScaleMode } from "../types/builder";
 import type {
 	ContentTransformGeometry,

package/src/shared/utils/bounds/helpers/style-composers.ts

@@ -30,7 +30,7 @@ export type ElementComposeParams = {
  * - geometry: precomputed screen-level tx/ty/sx/sy plus ranges/entering
  * - interp: function to interpolate between numbers using the correct progress range
  */
-export type ContentComposeParams = {
+type ContentComposeParams = {
 	start: MeasuredDimensions;
 	end: MeasuredDimensions;
 	geometry: ContentTransformGeometry;

package/src/shared/utils/bounds/helpers/styles.ts

@@ -1,10 +1,9 @@
 import type { ImageStyle, StyleProp, TextStyle, ViewStyle } from "react-native";
 import { isSharedValue } from "react-native-reanimated";
-import type { Any } from "../../../types/utils.types";
 
 type AnyStyle = ViewStyle | TextStyle | ImageStyle;
 type StyleValue = StyleProp<AnyStyle>;
-type PlainStyleObject = Record<string, Any>;
+type PlainStyleObject = Record<string, any>;
 
 function mergeStyleArrays<T extends StyleValue>(style: T): T {
 	"worklet";

package/src/shared/utils/bounds/index.ts

@@ -12,7 +12,7 @@ import type {
 	ScreenTransitionState,
 } from "../../types/animation.types";
 import type { BoundsAccessor, BoundsLink } from "../../types/bounds.types";
-import type { Layout } from "../../types/core.types";
+import type { Layout } from "../../types/screen.types";
 import {
 	computeContentTransformGeometry,
 	computeRelativeGeometry,
@@ -31,14 +31,6 @@ import type {
 	BoundsComputeParams,
 } from "./types/builder";
 
-export interface BuildBoundsAccessorParams {
-	current: ScreenTransitionState;
-	previous?: ScreenTransitionState;
-	next?: ScreenTransitionState;
-	progress: number;
-	dimensions: Layout;
-}
-
 const resolveBounds = (props: {
 	id: string;
 	previous?: ScreenTransitionState;