react-native-screen-transitions 2.4.2-beta.2 → 3.0.0-beta.0

package/src/blank-stack/utils/with-stack-navigation/_hooks/use-stack-navigation-state.tsx

@@ -0,0 +1,267 @@
+import { type Route, StackActions } from "@react-navigation/native";
+import { useLayoutEffect, useState } from "react";
+import useStableCallback from "../../../../shared/hooks/use-stable-callback";
+import type { BlankStackDescriptorMap } from "../../../types";
+import type { StackNavigationContextProps } from "../_types";
+import { areDescriptorsEqual } from "../_utils/are-descriptors-equal";
+import { composeDescriptors } from "../_utils/compose-descriptors";
+import { haveSameRouteKeys } from "../_utils/have-same-route-keys";
+import { routesAreIdentical } from "../_utils/routes-are-identical";
+import { useClosingRouteKeys } from "./use-closing-route-keys";
+import { usePrevious } from "./use-previous";
+
+type SyncRoutesWithRemovedParams = {
+	prevRoutes: Route<string>[];
+	prevDescriptors: BlankStackDescriptorMap;
+	nextRoutes: Route<string>[];
+	nextDescriptors: BlankStackDescriptorMap;
+	closingRouteKeys: ReturnType<typeof useClosingRouteKeys>;
+};
+
+/**
+ * Aligns current routes with the latest route data while preserving references
+ * when possible for performance optimization
+ */
+const alignRoutesWithLatest = (
+	currentRoutes: Route<string>[],
+	currentDescriptors: BlankStackDescriptorMap,
+	nextRoutes: Route<string>[],
+	nextDescriptors: BlankStackDescriptorMap,
+) => {
+	// 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<string>>();
+	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,
+		),
+	};
+};
+
+/**
+ * Synchronizes routes while handling removed routes that may still be animating out.
+ * This manages the complex logic of keeping closing routes visible during transitions.
+ */
+const syncRoutesWithRemoved = ({
+	prevRoutes,
+	prevDescriptors,
+	nextRoutes,
+	nextDescriptors,
+	closingRouteKeys,
+}: SyncRoutesWithRemovedParams) => {
+	if (nextRoutes.length === 0) {
+		closingRouteKeys.clear();
+		return {
+			routes: nextRoutes,
+			descriptors: {},
+		};
+	}
+
+	// Start with next routes, will mutate if needed
+	const derivedRoutes: Route<string>[] = nextRoutes.slice();
+
+	// Get focused (last) routes for comparison
+	const previousFocusedRoute = prevRoutes[prevRoutes.length - 1];
+	const nextFocusedRoute = nextRoutes[nextRoutes.length - 1];
+
+	// Handle focus changes between routes
+	if (
+		previousFocusedRoute &&
+		nextFocusedRoute &&
+		previousFocusedRoute.key !== nextFocusedRoute.key
+	) {
+		const nextRouteWasPresent = prevRoutes.some(
+			(route) => route.key === nextFocusedRoute.key,
+		);
+		const previousRouteStillPresent = nextRoutes.some(
+			(route) => route.key === previousFocusedRoute.key,
+		);
+
+		if (nextRouteWasPresent && !previousRouteStillPresent) {
+			// Previous route was removed, mark as closing
+			closingRouteKeys.add(previousFocusedRoute.key);
+
+			derivedRoutes.push(previousFocusedRoute);
+		} else {
+			// Next route is now active, not closing
+			closingRouteKeys.remove(nextFocusedRoute.key);
+
+			if (!previousRouteStillPresent) {
+				// Previous route needs to be inserted for transition
+				closingRouteKeys.remove(previousFocusedRoute.key);
+
+				const insertIndex = Math.max(derivedRoutes.length - 1, 0);
+				derivedRoutes.splice(insertIndex, 0, previousFocusedRoute);
+			}
+		}
+	} else if (nextFocusedRoute) {
+		// Same focused route, ensure it's not marked as closing
+		closingRouteKeys.remove(nextFocusedRoute.key);
+	}
+
+	// Clean up closing keys that are no longer in the route list
+	const activeKeys = new Set(derivedRoutes.map((route) => route.key));
+	for (const key of Array.from(closingRouteKeys.ref.current)) {
+		if (!activeKeys.has(key)) {
+			closingRouteKeys.remove(key);
+		}
+	}
+
+	return {
+		routes: derivedRoutes,
+		descriptors: composeDescriptors(
+			derivedRoutes,
+			nextDescriptors,
+			prevDescriptors,
+		),
+	};
+};
+
+export const useStackNavigationState = (props: StackNavigationContextProps) => {
+	const previousRoutes = usePrevious(props.state.routes) ?? [];
+	const closingRouteKeys = useClosingRouteKeys();
+
+	const [localState, setLocalState] = useState(() => ({
+		routes: props.state.routes,
+		descriptors: props.descriptors,
+	}));
+
+	useLayoutEffect(() => {
+		const nextRoutesSnapshot = props.state.routes;
+		const previousRoutesSnapshot = previousRoutes;
+
+		setLocalState((current) => {
+			const routeKeysUnchanged = haveSameRouteKeys(
+				previousRoutesSnapshot,
+				nextRoutesSnapshot,
+			);
+
+			let derivedRoutes: Route<string>[];
+			let derivedDescriptors: BlankStackDescriptorMap;
+
+			if (routeKeysUnchanged) {
+				const result = alignRoutesWithLatest(
+					current.routes,
+					current.descriptors,
+					nextRoutesSnapshot,
+					props.descriptors,
+				);
+
+				derivedRoutes = result.routes;
+				derivedDescriptors = result.descriptors;
+			} 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;
+				derivedDescriptors = result.descriptors;
+			}
+
+			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: Route<string> }) => {
+			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/blank-stack/utils/with-stack-navigation/_types.ts

@@ -0,0 +1,35 @@
+import type {
+	NavigationRoute,
+	ParamListBase,
+	Route,
+	RouteProp,
+	StackNavigationState,
+} from "@react-navigation/native";
+import type { SharedValue } from "react-native-reanimated";
+import type {
+	BlankStackDescriptor,
+	BlankStackDescriptorMap,
+	BlankStackNavigationHelpers,
+	BlankStackScene,
+} from "../../types";
+
+export interface StackNavigationContextValue {
+	routes: NavigationRoute<ParamListBase, string>[];
+	descriptors: BlankStackDescriptorMap;
+	scenes: BlankStackScene[];
+	activeScreensLimit: number;
+	closingRouteKeysShared: SharedValue<string[]>;
+	handleCloseRoute: (payload: { route: Route<string> }) => void;
+	shouldShowFloatOverlay: boolean;
+	focusedIndex: number;
+}
+
+export interface StackNavigationContextProps {
+	state: StackNavigationState<ParamListBase>;
+	navigation: BlankStackNavigationHelpers;
+	descriptors: BlankStackDescriptorMap;
+	describe: (
+		route: RouteProp<ParamListBase>,
+		placeholder: boolean,
+	) => BlankStackDescriptor;
+}

package/src/blank-stack/utils/with-stack-navigation/_utils/are-descriptors-equal.ts

@@ -0,0 +1,15 @@
+import type { BlankStackDescriptorMap } from "../../../types";
+
+export const areDescriptorsEqual = (
+	a: BlankStackDescriptorMap,
+	b: BlankStackDescriptorMap,
+): boolean => {
+	if (a === b) return true;
+
+	const aKeys = Object.keys(a);
+	const bKeys = Object.keys(b);
+
+	if (aKeys.length !== bKeys.length) return false;
+
+	return aKeys.every((key) => a[key] === b[key]);
+};

package/src/blank-stack/utils/with-stack-navigation/_utils/calculate-active-screens-limit.ts

@@ -0,0 +1,29 @@
+import type { NavigationRoute, ParamListBase } from "@react-navigation/native";
+import type { BlankStackDescriptorMap } from "../../../types";
+
+export function calculateActiveScreensLimit(
+	routes: NavigationRoute<ParamListBase, string>[],
+	descriptors: BlankStackDescriptorMap,
+): number {
+	if (routes.length === 0) {
+		return 1;
+	}
+
+	let limit = 1;
+
+	for (let i = routes.length - 1; i >= 0; i--) {
+		const route = routes[i];
+
+		const shouldKeepPrevious =
+			descriptors?.[route.key]?.options?.detachPreviousScreen !== true;
+
+		if (shouldKeepPrevious) {
+			limit++;
+			continue;
+		}
+
+		break;
+	}
+
+	return Math.min(limit, routes.length);
+}

package/src/blank-stack/utils/with-stack-navigation/_utils/compose-descriptors.ts

@@ -0,0 +1,24 @@
+import type { Route } from "@react-navigation/native";
+import type { BlankStackDescriptorMap } from "../../../types";
+
+export const composeDescriptors = (
+	routes: Route<string>[],
+	nextDescriptors: BlankStackDescriptorMap,
+	currentDescriptors: BlankStackDescriptorMap,
+): BlankStackDescriptorMap => {
+	const composed: BlankStackDescriptorMap = {};
+
+	for (const route of routes) {
+		const adjusted =
+			nextDescriptors[route.key] ?? currentDescriptors[route.key];
+
+		// useScreenAnimation depends on this, however with blank-stack, this should be enabled by default
+		const withEnableTransitions = {
+			...adjusted,
+			options: { ...adjusted.options, enableTransitions: true },
+		};
+		composed[route.key] = withEnableTransitions;
+	}
+
+	return composed;
+};

package/src/blank-stack/utils/with-stack-navigation/index.tsx

@@ -0,0 +1,80 @@
+import { type ComponentType, createContext, useContext, useMemo } from "react";
+import type { BlankStackScene } from "../../types";
+import { useStackNavigationState } from "./_hooks/use-stack-navigation-state";
+import type {
+	StackNavigationContextProps,
+	StackNavigationContextValue,
+} from "./_types";
+import { calculateActiveScreensLimit } from "./_utils/calculate-active-screens-limit";
+
+export const StackNavigationContext =
+	createContext<StackNavigationContextValue | null>(null);
+
+export function withStackNavigationProvider(
+	Component: ComponentType<StackNavigationContextValue>,
+) {
+	return function StackNavigationWrapper(props: StackNavigationContextProps) {
+		const { state, handleCloseRoute, closingRouteKeys } =
+			useStackNavigationState(props);
+
+		const scenes = useMemo(() => {
+			return state.routes.reduce((acc, route) => {
+				acc.push({
+					route,
+					descriptor: state.descriptors[route.key],
+				});
+				return acc;
+			}, [] as BlankStackScene[]);
+		}, [state.routes, state.descriptors]);
+
+		const activeScreensLimit = useMemo(() => {
+			return calculateActiveScreensLimit(state.routes, state.descriptors);
+		}, [state.routes, state.descriptors]);
+
+		const shouldShowFloatOverlay = useMemo(() => {
+			return state.routes.some((route) => {
+				const options = state.descriptors[route.key]?.options;
+				return options?.overlayMode === "float" && options?.overlayShown;
+			});
+		}, [state.routes, state.descriptors]);
+
+		const contextValue = useMemo<StackNavigationContextValue>(() => {
+			return {
+				routes: state.routes,
+				focusedIndex: props.state.index,
+				descriptors: state.descriptors,
+				closingRouteKeysShared: closingRouteKeys.shared,
+				activeScreensLimit,
+				handleCloseRoute,
+				scenes,
+				shouldShowFloatOverlay,
+			};
+		}, [
+			state,
+			scenes,
+			activeScreensLimit,
+			closingRouteKeys,
+			handleCloseRoute,
+			props.state.index,
+			shouldShowFloatOverlay,
+		]);
+
+		return (
+			<StackNavigationContext.Provider value={contextValue}>
+				<Component {...contextValue} />
+			</StackNavigationContext.Provider>
+		);
+	};
+}
+
+export const useStackNavigationContext = () => {
+	const context = useContext(StackNavigationContext);
+
+	if (!context) {
+		throw new Error(
+			"StackNavigationContext.Provider is missing in the component tree.",
+		);
+	}
+
+	return context;
+};

package/src/native-stack/index.ts

@@ -0,0 +1,12 @@
+export { createNativeStackNavigator } from "./navigators/createNativeStackNavigator";
+export type {
+	NativeStackHeaderLeftProps,
+	NativeStackHeaderProps,
+	NativeStackHeaderRightProps,
+	NativeStackNavigationEventMap,
+	NativeStackNavigationOptions,
+	NativeStackNavigationProp,
+	NativeStackNavigatorProps,
+	NativeStackOptionsArgs,
+	NativeStackScreenProps,
+} from "./types";

package/src/native-stack/navigators/createNativeStackNavigator.tsx

@@ -0,0 +1,112 @@
+import {
+	createNavigatorFactory,
+	type EventArg,
+	type NavigatorTypeBagBase,
+	type ParamListBase,
+	type StackActionHelpers,
+	StackActions,
+	type StackNavigationState,
+	StackRouter,
+	type StackRouterOptions,
+	type StaticConfig,
+	type TypedNavigator,
+	useNavigationBuilder,
+} from "@react-navigation/native";
+import * as React from "react";
+
+import type {
+	NativeStackNavigationEventMap,
+	NativeStackNavigationOptions,
+	NativeStackNavigationProp,
+	NativeStackNavigatorProps,
+} from "../types";
+import { NativeStackView } from "../views/NativeStackView";
+
+function NativeStackNavigator({
+	id,
+	initialRouteName,
+	children,
+	layout,
+	screenListeners,
+	screenOptions,
+	screenLayout,
+	...rest
+}: NativeStackNavigatorProps) {
+	const { state, describe, descriptors, navigation, NavigationContent } =
+		useNavigationBuilder<
+			StackNavigationState<ParamListBase>,
+			StackRouterOptions,
+			StackActionHelpers<ParamListBase>,
+			NativeStackNavigationOptions,
+			NativeStackNavigationEventMap
+		>(StackRouter, {
+			id,
+			initialRouteName,
+			children,
+			layout,
+			screenListeners,
+			screenOptions,
+			screenLayout,
+		});
+
+	React.useEffect(
+		() =>
+			// @ts-expect-error: there may not be a tab navigator in parent
+			navigation?.addListener?.("tabPress", (e: any) => {
+				const isFocused = navigation.isFocused();
+
+				// Run the operation in the next frame so we're sure all listeners have been run
+				// This is necessary to know if preventDefault() has been called
+				requestAnimationFrame(() => {
+					if (
+						state.index > 0 &&
+						isFocused &&
+						!(e as EventArg<"tabPress", true>).defaultPrevented
+					) {
+						// When user taps on already focused tab and we're inside the tab,
+						// reset the stack to replicate native behaviour
+						navigation.dispatch({
+							...StackActions.popToTop(),
+							target: state.key,
+						});
+					}
+				});
+			}),
+		[navigation, state.index, state.key],
+	);
+
+	return (
+		<NavigationContent>
+			<NativeStackView
+				{...rest}
+				state={state}
+				navigation={navigation}
+				descriptors={descriptors}
+				describe={describe}
+			/>
+		</NavigationContent>
+	);
+}
+
+export function createNativeStackNavigator<
+	const ParamList extends ParamListBase,
+	const NavigatorID extends string | undefined = undefined,
+	const TypeBag extends NavigatorTypeBagBase = {
+		ParamList: ParamList;
+		NavigatorID: NavigatorID;
+		State: StackNavigationState<ParamList>;
+		ScreenOptions: NativeStackNavigationOptions;
+		EventMap: NativeStackNavigationEventMap;
+		NavigationList: {
+			[RouteName in keyof ParamList]: NativeStackNavigationProp<
+				ParamList,
+				RouteName,
+				NavigatorID
+			>;
+		};
+		Navigator: typeof NativeStackNavigator;
+	},
+	const Config extends StaticConfig<TypeBag> = StaticConfig<TypeBag>,
+>(config?: Config): TypedNavigator<TypeBag, Config> {
+	return createNavigatorFactory(NativeStackNavigator)(config);
+}