react-native-screen-transitions 3.3.0 → 3.4.0-alpha.0

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

@@ -0,0 +1,147 @@
+import { StackActions } from "@react-navigation/native";
+import { useLayoutEffect, useRef, 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 { syncRoutesWithRemoved } from "../../../../utils/navigation/sync-routes-with-removed";
+import type { ManagedStackProps } from "../../managed.provider";
+import { alignRoutesWithLatest } from "./helpers/align-routes-with-latest";
+import { areDescriptorsEqual } from "./helpers/are-descriptors-equal";
+import { haveSameRouteKeys } from "./helpers/have-same-route-keys";
+import { routesAreIdentical } from "./helpers/routes-are-identical";
+
+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,
+	}));
+	const localStateRef = useRef(localState);
+
+	useLayoutEffect(() => {
+		const nextRoutesSnapshot = props.state.routes;
+		const previousRoutesSnapshot = previousRoutes;
+		const current = localStateRef.current;
+
+		const alreadyAligned =
+			routesAreIdentical(current.routes, nextRoutesSnapshot as TRoute[]) &&
+			areDescriptorsEqual(
+				current.descriptors,
+				props.descriptors as TDescriptorMap,
+			);
+		if (alreadyAligned) {
+			return;
+		}
+
+		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;
+		}
+
+		const nextLocalState = {
+			routes: routesChanged ? derivedRoutes : current.routes,
+			descriptors: descriptorsChanged
+				? derivedDescriptors
+				: current.descriptors,
+		};
+		localStateRef.current = nextLocalState;
+		setLocalState(nextLocalState);
+	}, [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];
+
+				const nextState = {
+					routes: nextRoutes,
+					descriptors: nextDescriptors,
+				};
+				localStateRef.current = nextState;
+				return nextState;
+			});
+		},
+	);
+
+	return {
+		state: localState,
+		handleCloseRoute,
+		closingRouteKeys,
+	};
+};

package/src/shared/providers/stack/helpers/use-processed-routes.ts

@@ -0,0 +1,85 @@
+import { useMemo } from "react";
+import {
+	AnimationStore,
+	type AnimationStoreMap,
+} from "../../../stores/animation.store";
+import type {
+	BaseStackDescriptor,
+	BaseStackScene,
+} from "../../../types/stack.types";
+import { isFloatOverlayVisible } from "../../../utils/overlay/visibility";
+
+export interface ProcessedRoutes<
+	TDescriptor extends BaseStackDescriptor = BaseStackDescriptor,
+> {
+	scenes: BaseStackScene<TDescriptor>[];
+	routeKeys: string[];
+	backdropBehaviors: string[];
+	animationMaps: AnimationStoreMap[];
+	shouldShowFloatOverlay: boolean;
+	activeScreensLimit: number;
+}
+
+/**
+ * Processes raw routes + descriptors into derived arrays needed by the stack.
+ * Single reverse pass computes: scenes, routeKeys, backdropBehaviors,
+ * animationMaps, shouldShowFloatOverlay, and activeScreensLimit.
+ */
+export function useProcessedRoutes<
+	TDescriptor extends BaseStackDescriptor = BaseStackDescriptor,
+>(
+	routes: TDescriptor["route"][],
+	descriptors: Record<string, TDescriptor>,
+): ProcessedRoutes<TDescriptor> {
+	return useMemo(() => {
+		const scenes: BaseStackScene<TDescriptor>[] = [];
+		const routeKeys: string[] = [];
+		const backdropBehaviors: string[] = [];
+		const animationMaps: AnimationStoreMap[] = [];
+
+		let shouldShowFloatOverlay = false;
+		let limit = 1;
+		let stopLimit = false;
+
+		for (let i = routes.length - 1; i >= 0; i--) {
+			const route = routes[i];
+			const descriptor = descriptors[route.key] as TDescriptor;
+			const options = descriptor?.options;
+
+			scenes[i] = { route, descriptor };
+			routeKeys[i] = route.key;
+			backdropBehaviors[i] = options?.backdropBehavior ?? "block";
+			animationMaps[i] = AnimationStore.getRouteAnimations(route.key);
+
+			if (!shouldShowFloatOverlay) {
+				shouldShowFloatOverlay = isFloatOverlayVisible(options);
+			}
+
+			if (!stopLimit) {
+				const shouldKeepPrevious =
+					(options as { detachPreviousScreen?: boolean })
+						?.detachPreviousScreen !== true;
+
+				if (shouldKeepPrevious) {
+					limit += 1;
+				} else {
+					stopLimit = true;
+				}
+			}
+		}
+
+		const activeScreensLimit = Math.min(
+			limit,
+			routes.length === 0 ? 1 : routes.length,
+		);
+
+		return {
+			scenes,
+			routeKeys,
+			backdropBehaviors,
+			animationMaps,
+			shouldShowFloatOverlay,
+			activeScreensLimit,
+		};
+	}, [routes, descriptors]);
+}

package/src/shared/providers/stack/helpers/use-stack-derived.ts

@@ -0,0 +1,43 @@
+import { type DerivedValue, useDerivedValue } from "react-native-reanimated";
+import type { AnimationStoreMap } from "../../../stores/animation.store";
+
+export interface StackDerived {
+	/** Sum of all individual screen progress values. */
+	stackProgress: DerivedValue<number>;
+	/**
+	 * Focused index that accounts for closing screens.
+	 * Counts consecutive closing screens from the top so that
+	 * rapid dismiss chains correctly identify the actual focused screen.
+	 */
+	optimisticFocusedIndex: DerivedValue<number>;
+}
+
+/**
+ * Derives aggregated stack progress and an optimistic focused index
+ * from animation store maps. Shared between managed and direct providers.
+ */
+export function useStackDerived(
+	animationMaps: AnimationStoreMap[],
+): StackDerived {
+	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 lastIndex = animationMaps.length - 1;
+		let closingFromTop = 0;
+		for (let i = lastIndex; i >= 0; i--) {
+			if (animationMaps[i].closing.value > 0) closingFromTop++;
+			else break;
+		}
+		return lastIndex - closingFromTop;
+	});
+
+	return { stackProgress, optimisticFocusedIndex };
+}

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

@@ -1,78 +1,39 @@
 import type { Route } from "@react-navigation/native";
 import * as React from "react";
-import { useEffect, useMemo } from "react";
-import {
-	type DerivedValue,
-	type SharedValue,
-	useDerivedValue,
-} from "react-native-reanimated";
+import { useMemo } from "react";
 import {
 	StackContext,
 	type StackContextValue,
 } from "../../hooks/navigation/use-stack";
-import {
-	AnimationStore,
-	type AnimationStoreMap,
-} from "../../stores/animation.store";
-import { HistoryStore } from "../../stores/history.store";
+import type {
+	ManagedStackContextValue,
+	ManagedStackProps,
+	ManagedStackRenderProps,
+	ManagedStackResult,
+} from "../../types/providers/managed-stack.types";
 import type {
 	BaseStackDescriptor,
 	BaseStackNavigation,
-	BaseStackRoute,
 	BaseStackScene,
-	BaseStackState,
 } from "../../types/stack.types";
-import { isFloatOverlayVisible } from "../../utils/overlay/visibility";
 import { useStackCoreContext } from "./core.provider";
+import { useClosingRouteMap } from "./helpers/use-closing-route-map";
 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>;
-	backdropBehaviors: string[];
-}
+import { useProcessedRoutes } from "./helpers/use-processed-routes";
+import { useStackDerived } from "./helpers/use-stack-derived";
 
 const ManagedStackContext =
 	React.createContext<ManagedStackContextValue | null>(null);
 ManagedStackContext.displayName = "ManagedStack";
 
-function useManagedStackContext<
-	TDescriptor extends BaseStackDescriptor = BaseStackDescriptor,
->(): ManagedStackContextValue<TDescriptor> {
+function useManagedStackContext(): ManagedStackContextValue {
 	const context = React.useContext(ManagedStackContext);
 	if (!context) {
 		throw new Error(
 			"useManagedStackContext must be used within ManagedStackProvider",
 		);
 	}
-	return context as ManagedStackContextValue<TDescriptor>;
+	return context;
 }
 
 function useManagedStackValue<
@@ -80,188 +41,97 @@ function useManagedStackValue<
 	TNavigation extends BaseStackNavigation,
 >(
 	props: ManagedStackProps<TDescriptor, TNavigation>,
-): ManagedStackContextValue<TDescriptor> & {
-	stackContextValue: StackContextValue;
-} {
+): ManagedStackResult<TDescriptor> {
 	const { flags } = useStackCoreContext();
 	const { state, handleCloseRoute, closingRouteKeys } = useLocalRoutes(props);
+	const navigatorKey = props.state.key;
 
-	const {
-		scenes,
-		activeScreensLimit,
-		shouldShowFloatOverlay,
-		routeKeys,
-		backdropBehaviors,
-		animationMaps,
-	} = useMemo(() => {
-		const routes = state.routes;
-		const descriptors = state.descriptors;
-		const scenes: BaseStackScene<TDescriptor>[] = [];
-		const routeKeys: string[] = [];
-		const backdropBehaviors: string[] = [];
-		const animationMaps: AnimationStoreMap[] = [];
-
-		let shouldShowFloatOverlay = false;
-		let limit = 1;
-		let stopLimit = false;
-
-		for (let i = routes.length - 1; i >= 0; i--) {
-			const route = routes[i];
-			const descriptor = descriptors[route.key] as TDescriptor;
-			const options = descriptor?.options;
-
-			scenes[i] = { route, descriptor };
-			routeKeys[i] = route.key;
-			backdropBehaviors[i] = options?.backdropBehavior ?? "block";
-			animationMaps[i] = AnimationStore.getAll(route.key);
-
-			if (!shouldShowFloatOverlay) {
-				shouldShowFloatOverlay = isFloatOverlayVisible(options);
-			}
-
-			if (!stopLimit) {
-				const shouldKeepPrevious =
-					(options as { detachPreviousScreen?: boolean })
-						?.detachPreviousScreen !== true;
-
-				if (shouldKeepPrevious) {
-					limit += 1;
-				} else {
-					stopLimit = true;
-				}
-			}
-		}
-
-		const activeScreensLimit = Math.min(
-			limit,
-			routes.length === 0 ? 1 : routes.length,
-		);
-
-		return {
-			scenes,
-			routeKeys,
-			backdropBehaviors,
-			activeScreensLimit,
-			shouldShowFloatOverlay,
-			animationMaps,
-		};
-	}, [state.routes, state.descriptors]);
-
-	// 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.
-	// Counts consecutive closing screens from the top of the stack so that
-	// rapid dismiss chains (e.g. dismiss C then B while C is still in flight)
-	// correctly identify the actual focused screen for pointer-event gating.
-	const optimisticFocusedIndex = useDerivedValue(() => {
-		"worklet";
-		const lastIndex = animationMaps.length - 1;
-		let closingFromTop = 0;
-		for (let i = lastIndex; i >= 0; i--) {
-			if (animationMaps[i].closing.value > 0) closingFromTop++;
-			else break;
-		}
-		return lastIndex - closingFromTop;
-	});
+	const processed = useProcessedRoutes(state.routes, state.descriptors);
+	const { stackProgress, optimisticFocusedIndex } = useStackDerived(
+		processed.animationMaps,
+	);
+	const closingRouteMap = useClosingRouteMap(
+		processed.routeKeys,
+		processed.animationMaps,
+	);
 
 	const focusedIndex = props.state.index;
 
+	// Common stack context (consumed by useStack())
 	const stackContextValue = useMemo<StackContextValue>(
 		() => ({
 			flags,
-			routeKeys,
+			navigatorKey,
+			routeKeys: processed.routeKeys,
 			routes: state.routes as Route<string>[],
-			descriptors: state.descriptors as Record<string, BaseStackDescriptor>,
-			scenes: scenes as BaseStackScene[],
-			focusedIndex,
+			scenes: processed.scenes as BaseStackScene[],
 			stackProgress,
 			optimisticFocusedIndex,
 		}),
 		[
-			routeKeys,
+			flags,
+			navigatorKey,
+			processed.routeKeys,
 			state.routes,
-			state.descriptors,
-			scenes,
-			focusedIndex,
+			processed.scenes,
 			stackProgress,
 			optimisticFocusedIndex,
-			flags,
 		],
 	);
 
-	// ManagedStack context value
-	const lifecycleValue = useMemo<ManagedStackContextValue<TDescriptor>>(
+	// Managed-specific context (consumed by useManagedStackContext())
+	const managedContextValue = useMemo<ManagedStackContextValue>(
 		() => ({
-			routes: state.routes,
-			focusedIndex,
-			descriptors: state.descriptors,
+			activeScreensLimit: processed.activeScreensLimit,
 			closingRouteKeysShared: closingRouteKeys.shared,
-			activeScreensLimit,
 			handleCloseRoute,
-			scenes,
-			shouldShowFloatOverlay,
-			stackProgress,
-			optimisticFocusedIndex,
-			backdropBehaviors,
+			backdropBehaviors: processed.backdropBehaviors,
 		}),
 		[
-			state.routes,
-			state.descriptors,
-			focusedIndex,
+			processed.activeScreensLimit,
 			closingRouteKeys.shared,
-			activeScreensLimit,
 			handleCloseRoute,
-			scenes,
-			shouldShowFloatOverlay,
-			stackProgress,
-			optimisticFocusedIndex,
-			backdropBehaviors,
+			processed.backdropBehaviors,
 		],
 	);
 
-	return { ...lifecycleValue, stackContextValue };
+	// Combined props for render children (stack-view components)
+	const renderProps = useMemo<ManagedStackRenderProps<TDescriptor>>(
+		() => ({
+			descriptors: state.descriptors,
+			scenes: processed.scenes,
+			focusedIndex,
+			closingRouteMap,
+			shouldShowFloatOverlay: processed.shouldShowFloatOverlay,
+		}),
+		[
+			state.descriptors,
+			processed.scenes,
+			focusedIndex,
+			closingRouteMap,
+			processed.shouldShowFloatOverlay,
+		],
+	);
+
+	return { stackContextValue, managedContextValue, renderProps };
 }
 
-/**
- * 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>>,
+	Component: React.ComponentType<ManagedStackRenderProps<TDescriptor>>,
 ): React.FC<ManagedStackProps<TDescriptor, TNavigation>> {
 	return function ManagedStackProvider(
 		props: ManagedStackProps<TDescriptor, TNavigation>,
 	) {
-		const navigatorKey = props.state.key;
-
-		// Clean up history when navigator unmounts
-		useEffect(() => {
-			return () => {
-				HistoryStore.clearNavigator(navigatorKey);
-			};
-		}, [navigatorKey]);
-
-		const { stackContextValue, ...lifecycleValue } = useManagedStackValue<
-			TDescriptor,
-			TNavigation
-		>(props);
+		const { stackContextValue, managedContextValue, renderProps } =
+			useManagedStackValue<TDescriptor, TNavigation>(props);
 
 		return (
 			<StackContext.Provider value={stackContextValue}>
-				<ManagedStackContext.Provider value={lifecycleValue}>
-					<Component {...lifecycleValue} />
+				<ManagedStackContext.Provider value={managedContextValue}>
+					<Component {...renderProps} />
 				</ManagedStackContext.Provider>
 			</StackContext.Provider>
 		);
@@ -269,3 +139,8 @@ function withManagedStack<
 }
 
 export { useManagedStackContext, withManagedStack };
+export type {
+	ManagedStackContextValue,
+	ManagedStackProps,
+	ManagedStackRenderProps,
+};

package/src/shared/providers/viewport.provider.tsx

@@ -0,0 +1,39 @@
+import type { ReactNode } from "react";
+import { useMemo } from "react";
+import { type ScaledSize, useWindowDimensions } from "react-native";
+import {
+	type EdgeInsets,
+	useSafeAreaInsets,
+} from "react-native-safe-area-context";
+import createProvider from "../utils/create-provider";
+
+export interface ViewportContextValue {
+	dimensions: ScaledSize;
+	insets: EdgeInsets;
+}
+
+interface ViewportProviderProps {
+	children: ReactNode;
+}
+
+const { ViewportProvider, useViewportContext } = createProvider("Viewport", {
+	guarded: true,
+})<ViewportProviderProps, ViewportContextValue>(({ children }) => {
+	const dimensions = useWindowDimensions();
+	const insets = useSafeAreaInsets();
+
+	const value = useMemo(
+		() => ({
+			dimensions,
+			insets,
+		}),
+		[dimensions, insets],
+	);
+
+	return {
+		value,
+		children,
+	};
+});
+
+export { ViewportProvider, useViewportContext };