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

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

@@ -0,0 +1,231 @@
+import type {
+	ParamListBase,
+	RouteProp,
+	StackNavigationState,
+} from "@react-navigation/native";
+import * as React from "react";
+import { useMemo } from "react";
+import { type DerivedValue, useDerivedValue } from "react-native-reanimated";
+import type {
+	NativeStackDescriptor,
+	NativeStackDescriptorMap,
+	NativeStackNavigationHelpers,
+} from "../../../native-stack/types";
+import {
+	StackContext,
+	type StackContextValue,
+} from "../../hooks/navigation/use-stack";
+import { AnimationStore } from "../../stores/animation.store";
+import { useStackCoreContext } from "./core.provider";
+
+export interface DirectStackScene {
+	route: StackNavigationState<ParamListBase>["routes"][number];
+	descriptor: NativeStackDescriptor;
+	isPreloaded: boolean;
+}
+
+export interface DirectStackProps {
+	state: StackNavigationState<ParamListBase>;
+	navigation: NativeStackNavigationHelpers;
+	descriptors: NativeStackDescriptorMap;
+	describe: (
+		route: RouteProp<ParamListBase>,
+		placeholder: boolean,
+	) => NativeStackDescriptor;
+}
+
+export interface DirectStackContextValue {
+	state: StackNavigationState<ParamListBase>;
+	navigation: NativeStackNavigationHelpers;
+	descriptors: NativeStackDescriptorMap;
+	preloadedDescriptors: NativeStackDescriptorMap;
+	scenes: DirectStackScene[];
+	focusedIndex: number;
+	shouldShowFloatOverlay: boolean;
+	stackProgress: DerivedValue<number>;
+	optimisticFocusedIndex: DerivedValue<number>;
+}
+
+const DirectStackContext = React.createContext<DirectStackContextValue | null>(
+	null,
+);
+DirectStackContext.displayName = "DirectStack";
+
+function useDirectStackContext(): DirectStackContextValue {
+	const context = React.useContext(DirectStackContext);
+	if (!context) {
+		throw new Error(
+			"useDirectStackContext must be used within DirectStackProvider",
+		);
+	}
+	return context;
+}
+
+/**
+ * Internal hook that computes all lifecycle values.
+ */
+function useDirectStackValue(
+	props: DirectStackProps,
+): DirectStackContextValue & { stackContextValue: StackContextValue } {
+	const { state, navigation, descriptors, describe } = props;
+	const { flags } = useStackCoreContext();
+
+	const preloadedDescriptors = useMemo(() => {
+		return state.preloadedRoutes.reduce<NativeStackDescriptorMap>(
+			(acc, route) => {
+				acc[route.key] = acc[route.key] || describe(route, true);
+				return acc;
+			},
+			{},
+		);
+	}, [state.preloadedRoutes, describe]);
+
+	const {
+		scenes,
+		shouldShowFloatOverlay,
+		routeKeys,
+		allRoutes,
+		allDescriptors,
+	} = useMemo(() => {
+		const allRoutes = state.routes.concat(state.preloadedRoutes);
+		const scenes: DirectStackScene[] = [];
+		const routeKeys: string[] = [];
+		const allDescriptors: NativeStackDescriptorMap = {
+			...preloadedDescriptors,
+			...descriptors,
+		};
+		let shouldShowFloatOverlay = false;
+
+		for (const route of allRoutes) {
+			const descriptor = allDescriptors[route.key];
+			const isPreloaded =
+				preloadedDescriptors[route.key] !== undefined &&
+				descriptors[route.key] === undefined;
+
+			scenes.push({ route, descriptor, isPreloaded });
+			routeKeys.push(route.key);
+
+			if (!shouldShowFloatOverlay && descriptor) {
+				const options = descriptor.options;
+				if (
+					options?.enableTransitions === true &&
+					options?.overlayMode === "float" &&
+					options?.overlayShown === true
+				) {
+					shouldShowFloatOverlay = true;
+				}
+			}
+		}
+
+		return {
+			scenes,
+			shouldShowFloatOverlay,
+			routeKeys,
+			allRoutes,
+			allDescriptors,
+		};
+	}, [state.routes, state.preloadedRoutes, descriptors, preloadedDescriptors]);
+
+	// Get animation store maps for all routes
+	const animationMaps = useMemo(
+		() => allRoutes.map((route) => AnimationStore.getAll(route.key)),
+		[allRoutes],
+	);
+
+	const stackProgress = useDerivedValue(() => {
+		"worklet";
+		let total = 0;
+		for (let i = 0; i < animationMaps.length; i++) {
+			total += animationMaps[i].progress.value;
+		}
+		return total;
+	});
+
+	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 - (isAnyClosing ? 1 : 0);
+	});
+
+	const focusedIndex = state.index;
+
+	const stackContextValue = useMemo<StackContextValue>(
+		() => ({
+			flags,
+			routeKeys,
+			routes: allRoutes,
+			descriptors: allDescriptors,
+			scenes,
+			focusedIndex,
+			stackProgress,
+			optimisticFocusedIndex,
+		}),
+		[
+			routeKeys,
+			allRoutes,
+			allDescriptors,
+			scenes,
+			focusedIndex,
+			stackProgress,
+			optimisticFocusedIndex,
+			flags,
+		],
+	);
+
+	// DirectStack context value
+	const lifecycleValue = useMemo<DirectStackContextValue>(
+		() => ({
+			state,
+			navigation,
+			descriptors,
+			preloadedDescriptors,
+			scenes,
+			focusedIndex,
+			shouldShowFloatOverlay,
+			stackProgress,
+			optimisticFocusedIndex,
+		}),
+		[
+			state,
+			navigation,
+			descriptors,
+			preloadedDescriptors,
+			scenes,
+			focusedIndex,
+			shouldShowFloatOverlay,
+			stackProgress,
+			optimisticFocusedIndex,
+		],
+	);
+
+	return { ...lifecycleValue, stackContextValue };
+}
+
+/**
+ * HOC that wraps component with DirectStack provider AND StackContext.
+ * Used by native-stack which uses navigation state directly (no local route management).
+ */
+function withDirectStack<TProps extends DirectStackProps>(
+	Component: React.ComponentType<DirectStackContextValue>,
+): React.FC<TProps> {
+	return function DirectStackProvider(props: TProps) {
+		const { stackContextValue, ...lifecycleValue } = useDirectStackValue(props);
+
+		return (
+			<StackContext.Provider value={stackContextValue}>
+				<DirectStackContext.Provider value={lifecycleValue}>
+					<Component {...lifecycleValue} />
+				</DirectStackContext.Provider>
+			</StackContext.Provider>
+		);
+	};
+}
+
+export { useDirectStackContext, withDirectStack };

package/src/{blank-stack/utils/with-stack-navigation/helpers/calculate-active-screens-limit.ts → shared/providers/stack/helpers/active-screens-limit.ts}

@@ -1,9 +1,15 @@
-import type { NavigationRoute, ParamListBase } from "@react-navigation/native";
-import type { BlankStackDescriptorMap } from "../../../types";
+import type {
+	BaseStackDescriptor,
+	BaseStackRoute,
+} from "../../../types/stack.types";
+
+type DescriptorWithDetach = BaseStackDescriptor & {
+	options: { detachPreviousScreen?: boolean };
+};
 
 export function calculateActiveScreensLimit(
-	routes: NavigationRoute<ParamListBase, string>[],
-	descriptors: BlankStackDescriptorMap,
+	routes: BaseStackRoute[],
+	descriptors: Record<string, DescriptorWithDetach>,
 ): number {
 	if (routes.length === 0) {
 		return 1;

package/src/shared/providers/stack/helpers/use-local-routes.tsx

@@ -0,0 +1,133 @@
+import { StackActions } from "@react-navigation/native";
+import { useLayoutEffect, useState } from "react";
+import { useClosingRouteKeys } from "../../../hooks/navigation/use-closing-route-keys";
+import { usePrevious } from "../../../hooks/navigation/use-previous";
+import useStableCallback from "../../../hooks/use-stable-callback";
+import type {
+	BaseStackDescriptor,
+	BaseStackNavigation,
+	BaseStackRoute,
+} from "../../../types/stack.types";
+import { alignRoutesWithLatest } from "../../../utils/navigation/align-routes-with-latest";
+import { areDescriptorsEqual } from "../../../utils/navigation/are-descriptors-equal";
+import { haveSameRouteKeys } from "../../../utils/navigation/have-same-route-keys";
+import { routesAreIdentical } from "../../../utils/navigation/routes-are-identical";
+import { syncRoutesWithRemoved } from "../../../utils/navigation/sync-routes-with-removed";
+import type { ManagedStackProps } from "../managed.provider";
+
+export const useLocalRoutes = <
+	TDescriptor extends BaseStackDescriptor,
+	TNavigation extends BaseStackNavigation,
+>(
+	props: ManagedStackProps<TDescriptor, TNavigation>,
+) => {
+	type TRoute = TDescriptor["route"];
+	type TDescriptorMap = Record<string, TDescriptor>;
+
+	const previousRoutes = usePrevious(props.state.routes) ?? [];
+	const closingRouteKeys = useClosingRouteKeys();
+
+	const [localState, setLocalState] = useState(() => ({
+		routes: props.state.routes as TRoute[],
+		descriptors: props.descriptors as TDescriptorMap,
+	}));
+
+	useLayoutEffect(() => {
+		const nextRoutesSnapshot = props.state.routes;
+		const previousRoutesSnapshot = previousRoutes;
+
+		setLocalState((current) => {
+			const routeKeysUnchanged = haveSameRouteKeys(
+				previousRoutesSnapshot,
+				nextRoutesSnapshot,
+			);
+
+			let derivedRoutes: TRoute[];
+			let derivedDescriptors: TDescriptorMap;
+
+			if (routeKeysUnchanged) {
+				const result = alignRoutesWithLatest(
+					current.routes,
+					current.descriptors,
+					nextRoutesSnapshot,
+					props.descriptors,
+				);
+
+				derivedRoutes = result.routes as TRoute[];
+				derivedDescriptors = result.descriptors as TDescriptorMap;
+			} else {
+				const fallbackRoutes =
+					previousRoutesSnapshot.length > 0
+						? previousRoutesSnapshot
+						: current.routes;
+
+				const result = syncRoutesWithRemoved({
+					prevRoutes: fallbackRoutes,
+					prevDescriptors: current.descriptors,
+					nextRoutes: nextRoutesSnapshot,
+					nextDescriptors: props.descriptors,
+					closingRouteKeys,
+				});
+
+				derivedRoutes = result.routes as TRoute[];
+				derivedDescriptors = result.descriptors as TDescriptorMap;
+			}
+
+			const routesChanged = !routesAreIdentical(current.routes, derivedRoutes);
+			const descriptorsChanged = !areDescriptorsEqual(
+				current.descriptors,
+				derivedDescriptors,
+			);
+
+			if (!routesChanged && !descriptorsChanged) {
+				return current;
+			}
+
+			return {
+				routes: routesChanged ? derivedRoutes : current.routes,
+				descriptors: descriptorsChanged
+					? derivedDescriptors
+					: current.descriptors,
+			};
+		});
+	}, [props.state.routes, props.descriptors, previousRoutes, closingRouteKeys]);
+
+	const handleCloseRoute = useStableCallback(
+		({ route }: { route: BaseStackRoute }) => {
+			if (props.state.routes.some((r) => r.key === route.key)) {
+				props.navigation.dispatch({
+					...StackActions.pop(),
+					source: route.key,
+					target: props.state.key,
+				});
+				return;
+			}
+
+			closingRouteKeys.remove(route.key);
+
+			setLocalState((current) => {
+				if (!current.routes.some((candidate) => candidate.key === route.key)) {
+					return current;
+				}
+
+				const nextRoutes = current.routes.filter(
+					(candidate) => candidate.key !== route.key,
+				);
+
+				const nextDescriptors = { ...current.descriptors };
+				delete nextDescriptors[route.key];
+
+				return {
+					routes: nextRoutes,
+					descriptors: nextDescriptors,
+				};
+			});
+		},
+	);
+
+	return {
+		state: localState,
+		handleCloseRoute,
+		closingRouteKeys,
+	};
+};

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

@@ -0,0 +1,229 @@
+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 { useStackCoreContext } from "./core.provider";
+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 { flags } = useStackCoreContext();
+	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,
+			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,
+			flags,
+		],
+	);
+
+	// 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 which manages 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 {