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

package/src/shared/types/bounds.types.ts

@@ -33,4 +33,9 @@ export type BoundsAccessor = {
 		property: keyof StyleProps,
 		fallback?: number,
 	) => number;
+	interpolateBounds: (
+		id: string,
+		property: keyof MeasuredDimensions,
+		fallback?: number,
+	) => number;
 };

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,46 @@
+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 {
+	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,49 @@
+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";
+
+/**
+ * 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>;
+};

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

@@ -4,6 +4,7 @@ import type {
 	TransitionSpec,
 } from "./animation.types";
 import type { GestureActivationArea, GestureDirection } from "./gesture.types";
+import type { OverlayMode, OverlayProps } from "./overlay.types";
 
 export type Layout = {
 	width: number;
@@ -12,8 +13,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 +54,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 +102,37 @@ 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;
+
+	/**
+	 * 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,63 @@
+import type { ScreenTransitionConfig } from "./screen.types";
+
+/**
+ * Base route interface - minimal contract all stacks satisfy.
+ * 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) 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;
+}
+
+export enum StackType {
+	NATIVE = "native",
+	BLANK = "blank",
+}

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

@@ -1,4 +1,4 @@
-import type { MeasuredDimensions } from "react-native-reanimated";
+import { interpolate, type MeasuredDimensions } from "react-native-reanimated";
 import {
 	EMPTY_BOUND_HELPER_RESULT,
 	EMPTY_BOUND_HELPER_RESULT_RAW,
@@ -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;
@@ -235,9 +227,26 @@ export const createBounds = (
 		});
 	};
 
+	const interpolateBounds = (
+		tag: string,
+		property: keyof MeasuredDimensions,
+		fallback?: number,
+	): number => {
+		"worklet";
+		const link = getLink(tag);
+		const entering = !props.next;
+		const range = entering ? ENTER_RANGE : EXIT_RANGE;
+
+		const sourceValue = link?.source?.bounds?.[property] ?? fallback ?? 0;
+		const destValue = link?.destination?.bounds?.[property] ?? fallback ?? 0;
+
+		return interpolate(props.progress, range, [sourceValue, destValue], "clamp");
+	};
+
 	return Object.assign(boundsFunction, {
 		getSnapshot,
 		getLink,
 		interpolateStyle,
+		interpolateBounds,
 	}) as BoundsAccessor;
 };

package/src/shared/utils/bounds/types/builder.ts

@@ -1,7 +1,7 @@
 import type { MeasuredDimensions, StyleProps } from "react-native-reanimated";
 import type { ScreenTransitionState } from "../../../types/animation.types";
 import type { BoundsMethod } from "../../../types/bounds.types";
-import type { Layout } from "../../../types/core.types";
+import type { Layout } from "../../../types/screen.types";
 
 export type BoundsAnchor =
 	| "topLeading"
@@ -16,9 +16,9 @@ export type BoundsAnchor =
 
 export type BoundsScaleMode = "match" | "none" | "uniform";
 
-export type BoundsTarget = "bound" | "fullscreen" | MeasuredDimensions;
+type BoundsTarget = "bound" | "fullscreen" | MeasuredDimensions;
 
-export type BoundsSpace = "relative" | "absolute";
+type BoundsSpace = "relative" | "absolute";
 
 export type BoundsComputeParams = {
 	id?: string;
@@ -29,35 +29,35 @@ export type BoundsComputeParams = {
 	dimensions: Layout;
 };
 
-export type RawSizeAbsoluteReturn = {
+type RawSizeAbsoluteReturn = {
 	width: number;
 	height: number;
 	translateX: number;
 	translateY: number;
 };
 
-export type RawSizeRelativeReturn = {
+type RawSizeRelativeReturn = {
 	translateX: number;
 	translateY: number;
 	width: number;
 	height: number;
 };
 
-export type RawTransformAbsoluteReturn = {
+type RawTransformAbsoluteReturn = {
 	translateX: number;
 	translateY: number;
 	scaleX: number;
 	scaleY: number;
 };
 
-export type RawTransformRelativeReturn = {
+type RawTransformRelativeReturn = {
 	translateX: number;
 	translateY: number;
 	scaleX: number;
 	scaleY: number;
 };
 
-export type RawContentReturn = {
+type RawContentReturn = {
 	translateX: number;
 	translateY: number;
 	scale: number;

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

@@ -1,4 +1,4 @@
-export type GeometryBase = {
+type GeometryBase = {
 	entering: boolean;
 };
 

package/src/shared/utils/create-provider.tsx

@@ -90,25 +90,23 @@ export default function createProvider<
 			return context;
 		};
 
+		/**
+		 * HOC that wraps a component with the provider.
+		 * Uses the Provider component internally to ensure hooks are called correctly.
+		 */
 		const withProvider = (Component: ComponentType<ContextValue>) => {
-			return function WithProviderWrapper(props: ProviderProps) {
-				const { enabled = true, value } = factory(props);
-
-				if (!value) {
-					throw new Error(
-						`${name}Context value must be provided. You likely forgot to return it from the factory function.`,
-					);
-				}
-
-				const memoValue = useMemo(
-					() => (enabled ? value : null),
-					[enabled, value],
-				);
+			// Consumer component that reads context and passes to wrapped component
+			const ContextConsumer = () => {
+				const contextValue = useEnhancedContext();
+				if (!contextValue) return null;
+				return <Component {...contextValue} />;
+			};
 
+			return function WithProviderWrapper(props: ProviderProps) {
 				return (
-					<Context.Provider value={memoValue}>
-						<Component {...value} />
-					</Context.Provider>
+					<Provider {...props}>
+						<ContextConsumer />
+					</Provider>
 				);
 			};
 		};

package/src/shared/utils/gesture/check-gesture-activation.ts

@@ -1,12 +1,12 @@
 import type { GestureStateManagerType } from "react-native-gesture-handler/lib/typescript/handlers/gestures/gestureStateManager";
 import type { SharedValue } from "react-native-reanimated";
-import type { Layout } from "../../types/core.types";
 import {
 	type ActivationArea,
 	type GestureActivationArea,
 	GestureOffsetState,
 	type SideActivation,
 } from "../../types/gesture.types";
+import type { Layout } from "../../types/screen.types";
 
 type Directions = {
 	vertical: boolean;

package/src/shared/utils/navigation/align-routes-with-latest.ts

@@ -0,0 +1,68 @@
+import { composeDescriptors } from "./compose-descriptors";
+
+interface RouteWithKey {
+	key: string;
+}
+
+/**
+ * Aligns current routes with the latest route data while preserving references
+ * when possible for performance optimization
+ */
+export const alignRoutesWithLatest = <
+	Route extends RouteWithKey,
+	DescriptorMap extends Record<string, unknown>,
+>(
+	currentRoutes: Route[],
+	currentDescriptors: DescriptorMap,
+	nextRoutes: Route[],
+	nextDescriptors: DescriptorMap,
+): { routes: Route[]; descriptors: DescriptorMap } => {
+	// Early return for empty current routes
+	if (currentRoutes.length === 0) {
+		return {
+			routes: nextRoutes,
+			descriptors: composeDescriptors(
+				nextRoutes,
+				nextDescriptors,
+				currentDescriptors,
+			),
+		};
+	}
+
+	// Create lookup map for efficient route finding
+	const nextRouteLookup = new Map<string, Route>();
+	for (const route of nextRoutes) {
+		nextRouteLookup.set(route.key, route);
+	}
+
+	// Track if any changes occurred
+	let didChange = currentRoutes.length !== nextRoutes.length;
+
+	// Align routes, updating references where needed
+	const alignedRoutes = currentRoutes.map((route) => {
+		const nextRoute = nextRouteLookup.get(route.key);
+
+		if (!nextRoute) {
+			return route; // Keep current route if not in next
+		}
+
+		if (nextRoute !== route) {
+			didChange = true;
+			return nextRoute; // Update to new route reference
+		}
+
+		return route; // Keep current route reference
+	});
+
+	// Only create new array if changes occurred
+	const routesResult = didChange ? alignedRoutes : currentRoutes;
+
+	return {
+		routes: routesResult,
+		descriptors: composeDescriptors(
+			routesResult,
+			nextDescriptors,
+			currentDescriptors,
+		),
+	};
+};

package/src/{blank-stack/utils/with-stack-navigation/helpers → shared/utils/navigation}/are-descriptors-equal.ts

@@ -1,8 +1,8 @@
-import type { BlankStackDescriptorMap } from "../../../types";
-
-export const areDescriptorsEqual = (
-	a: BlankStackDescriptorMap,
-	b: BlankStackDescriptorMap,
+export const areDescriptorsEqual = <
+	DescriptorMap extends Record<string, unknown>,
+>(
+	a: DescriptorMap,
+	b: DescriptorMap,
 ): boolean => {
 	if (a === b) return true;
 

package/src/shared/utils/navigation/compose-descriptors.ts

@@ -0,0 +1,21 @@
+interface RouteWithKey {
+	key: string;
+}
+
+export const composeDescriptors = <
+	Route extends RouteWithKey,
+	DescriptorMap extends Record<string, unknown>,
+>(
+	routes: Route[],
+	nextDescriptors: DescriptorMap,
+	currentDescriptors: DescriptorMap,
+): DescriptorMap => {
+	const composed = {} as DescriptorMap;
+
+	for (const route of routes) {
+		(composed as Record<string, unknown>)[route.key] =
+			nextDescriptors[route.key] ?? currentDescriptors[route.key];
+	}
+
+	return composed;
+};

package/src/{blank-stack/utils/with-stack-navigation/helpers → shared/utils/navigation}/have-same-route-keys.ts

@@ -1,8 +1,10 @@
-import type { Route } from "@react-navigation/native";
+interface RouteWithKey {
+	key: string;
+}
 
-export const haveSameRouteKeys = (
-	previous: Route<string>[],
-	next: Route<string>[],
+export const haveSameRouteKeys = <Route extends RouteWithKey>(
+	previous: Route[],
+	next: Route[],
 ): boolean => {
 	if (previous.length !== next.length) {
 		return false;

package/src/{blank-stack/utils/with-stack-navigation/helpers → shared/utils/navigation}/routes-are-identical.ts

@@ -1,8 +1,10 @@
-import type { Route } from "@react-navigation/native";
+interface RouteWithKey {
+	key: string;
+}
 
-export const routesAreIdentical = (
-	a: Route<string>[],
-	b: Route<string>[],
+export const routesAreIdentical = <Route extends RouteWithKey>(
+	a: Route[],
+	b: Route[],
 ): boolean => {
 	if (a === b) return true;
 	if (a.length !== b.length) return false;