react-native-screen-transitions 3.2.0-beta.3 → 3.2.0

package/src/shared/components/screen-lifecycle.tsx

@@ -1,168 +1,32 @@
-import { useLayoutEffect } from "react";
-import {
-	runOnJS,
-	useAnimatedReaction,
-	useDerivedValue,
-} from "react-native-reanimated";
-import { useHighRefreshRate } from "../hooks/animation/use-high-refresh-rate";
-import { useSharedValueState } from "../hooks/reanimated/use-shared-value-state";
-import useStableCallback from "../hooks/use-stable-callback";
-import { useGestureContext } from "../providers/gestures.provider";
-import {
-	type BaseDescriptor,
-	useKeys,
-} from "../providers/screen/keys.provider";
-import { useStackCoreContext } from "../providers/stack/core.provider";
-import { useManagedStackContext } from "../providers/stack/managed.provider";
+import { useCloseTransition } from "../hooks/lifecycle/use-close-transition";
+import { useOpenTransition } from "../hooks/lifecycle/use-open-transition";
+import { useScreenEvents } from "../hooks/lifecycle/use-screen-events";
+import type { BaseDescriptor } from "../providers/screen/keys.provider";
 import { AnimationStore } from "../stores/animation.store";
-import { StackType } from "../types/stack.types";
-import { startScreenTransition } from "../utils/animation/start-screen-transition";
-import { resetStoresForScreen } from "../utils/reset-stores-for-screen";
 
 interface Props {
 	children: React.ReactNode;
-}
-
-interface CloseHookParams {
 	current: BaseDescriptor;
-	animations: ReturnType<typeof AnimationStore.getAll>;
-	activate: () => void;
-	deactivate: () => void;
+	previous?: BaseDescriptor;
 }
 
-/**
- * Managed close - reacts to closingRouteKeysShared from ManagedStackContext.
- * Used by blank-stack and component-stack.
- */
-const useManagedClose = ({
-	current,
-	animations,
-	activate,
-	deactivate,
-}: CloseHookParams) => {
-	const { handleCloseRoute, closingRouteKeysShared } = useManagedStackContext();
-
-	const handleCloseEnd = useStableCallback((finished: boolean) => {
-		if (!finished) return;
-		handleCloseRoute({ route: current.route });
-		requestAnimationFrame(() => {
-			deactivate();
-			resetStoresForScreen(current);
-		});
-	});
-
-	useAnimatedReaction(
-		() => closingRouteKeysShared.value,
-		(keys) => {
-			if (!keys?.includes(current.route.key)) return;
-
-			runOnJS(activate)();
-			startScreenTransition({
-				target: "close",
-				spec: current.options.transitionSpec,
-				animations,
-				onAnimationFinish: handleCloseEnd,
-			});
-		},
-	);
-};
-
-/**
- * Native stack close - listens to beforeRemove navigation event.
- */
-const useNativeStackClose = ({
-	current,
-	animations,
-	activate,
-	deactivate,
-}: CloseHookParams) => {
-	const gestureCtx = useGestureContext();
-
-	const isAncestorDismissingViaGesture = useSharedValueState(
-		useDerivedValue(() => {
-			"worklet";
-			return (
-				gestureCtx?.ancestorContext?.gestureAnimationValues.isDismissing
-					?.value ?? false
-			);
-		}),
-	);
-
-	const handleBeforeRemove = useStableCallback((e: any) => {
-		const options = current.options as { enableTransitions?: boolean };
-		const isEnabled = options.enableTransitions;
-		const navigation = current.navigation;
-		const isFirstScreen = navigation.getState().index === 0;
-
-		// If transitions are disabled, ancestor is dismissing, or first screen - let native handle it
-		if (!isEnabled || isAncestorDismissingViaGesture || isFirstScreen) {
-			animations.closing.set(1);
-			resetStoresForScreen(current);
-			return;
-		}
-
-		e.preventDefault();
-		activate();
-
-		startScreenTransition({
-			target: "close",
-			spec: current.options.transitionSpec,
-			animations,
-			onAnimationFinish: (finished: boolean) => {
-				deactivate();
-				if (finished) {
-					navigation.dispatch(e.data.action);
-					requestAnimationFrame(() => {
-						resetStoresForScreen(current);
-					});
-				}
-			},
-		});
-	});
-
-	// biome-ignore lint/correctness/useExhaustiveDependencies: Only re-subscribe when navigation changes
-	useLayoutEffect(() => {
-		return current.navigation.addListener?.("beforeRemove", handleBeforeRemove);
-	}, [current.navigation]);
-};
-
 /**
  * Unified lifecycle controller for all stack types.
  */
-export const ScreenLifecycle = ({ children }: Props) => {
-	const { flags } = useStackCoreContext();
-	const { current } = useKeys();
+export const ScreenLifecycle = ({ children, current, previous }: Props) => {
 	const animations = AnimationStore.getAll(current.route.key);
-	const { activateHighRefreshRate, deactivateHighRefreshRate } =
-		useHighRefreshRate(current);
 
-	const isNativeStack = flags.STACK_TYPE === StackType.NATIVE;
-
-	// biome-ignore lint/correctness/useExhaustiveDependencies: Must only run once on mount
-	useLayoutEffect(() => {
-		activateHighRefreshRate();
-		startScreenTransition({
-			target: "open",
-			spec: current.options.transitionSpec,
-			animations,
-			onAnimationFinish: deactivateHighRefreshRate,
-		});
-	}, []);
+	const { activateHighRefreshRate, deactivateHighRefreshRate } =
+		useOpenTransition(current, animations);
 
-	const closeParams: CloseHookParams = {
+	useCloseTransition(
 		current,
 		animations,
-		activate: activateHighRefreshRate,
-		deactivate: deactivateHighRefreshRate,
-	};
+		activateHighRefreshRate,
+		deactivateHighRefreshRate,
+	);
 
-	if (isNativeStack) {
-		// biome-ignore lint/correctness/useHookAtTopLevel: STACK_TYPE is stable per screen instance
-		useNativeStackClose(closeParams);
-	} else {
-		// biome-ignore lint/correctness/useHookAtTopLevel: STACK_TYPE is stable per screen instance
-		useManagedClose(closeParams);
-	}
+	useScreenEvents(current, previous, animations);
 
 	return children;
 };

package/src/shared/constants.ts

@@ -24,6 +24,7 @@ export const DEFAULT_SCREEN_TRANSITION_STATE: ScreenTransitionState =
 		progress: 0,
 		closing: 0,
 		animating: 0,
+		entering: 1,
 		gesture: {
 			x: 0,
 			y: 0,

package/src/shared/hooks/animation/use-screen-animation.tsx

@@ -24,6 +24,7 @@ type BuiltState = {
 	progress: SharedValue<number>;
 	closing: SharedValue<number>;
 	animating: SharedValue<number>;
+	entering: SharedValue<number>;
 	gesture: GestureStoreMap;
 	route: BaseStackRoute;
 	meta?: Record<string, unknown>;
@@ -37,6 +38,7 @@ const createScreenTransitionState = (
 	progress: 0,
 	closing: 0,
 	animating: 0,
+	entering: 1,
 	gesture: {
 		x: 0,
 		y: 0,
@@ -55,6 +57,7 @@ const unwrapInto = (s: BuiltState): ScreenTransitionState => {
 	const out = s.unwrapped;
 	out.progress = s.progress.value;
 	out.closing = s.closing.value;
+	out.entering = s.entering.value;
 	out.animating = s.animating.value;
 	out.gesture.x = s.gesture.x.value;
 	out.gesture.y = s.gesture.y.value;
@@ -80,6 +83,7 @@ const useBuildScreenTransitionState = (
 		return {
 			progress: AnimationStore.getAnimation(key, "progress"),
 			closing: AnimationStore.getAnimation(key, "closing"),
+			entering: AnimationStore.getAnimation(key, "entering"),
 			animating: AnimationStore.getAnimation(key, "animating"),
 			gesture: GestureStore.getRouteGestures(key),
 			route: descriptor.route,

package/src/shared/hooks/lifecycle/use-close-transition.ts

@@ -0,0 +1,147 @@
+import { useLayoutEffect } from "react";
+import {
+	runOnJS,
+	useAnimatedReaction,
+	useDerivedValue,
+} from "react-native-reanimated";
+import { useGestureContext } from "../../providers/gestures.provider";
+import type { BaseDescriptor } from "../../providers/screen/keys.provider";
+import { useStackCoreContext } from "../../providers/stack/core.provider";
+import { useManagedStackContext } from "../../providers/stack/managed.provider";
+import type { AnimationStoreMap } from "../../stores/animation.store";
+import { StackType } from "../../types/stack.types";
+import { startScreenTransition } from "../../utils/animation/start-screen-transition";
+import { resetStoresForScreen } from "../../utils/reset-stores-for-screen";
+import { useSharedValueState } from "../reanimated/use-shared-value-state";
+import useStableCallback from "../use-stable-callback";
+
+export interface CloseHookParams {
+	current: BaseDescriptor;
+	animations: AnimationStoreMap;
+	activate: () => void;
+	deactivate: () => void;
+}
+
+/**
+ * Managed close - reacts to closingRouteKeysShared from ManagedStackContext.
+ * Used by blank-stack and component-stack.
+ */
+const useManagedClose = ({
+	current,
+	animations,
+	activate,
+	deactivate,
+}: CloseHookParams) => {
+	const { handleCloseRoute, closingRouteKeysShared } = useManagedStackContext();
+
+	const handleCloseEnd = useStableCallback((finished: boolean) => {
+		if (!finished) return;
+		handleCloseRoute({ route: current.route });
+		requestAnimationFrame(() => {
+			deactivate();
+			resetStoresForScreen(current);
+		});
+	});
+
+	useAnimatedReaction(
+		() => closingRouteKeysShared.value,
+		(keys) => {
+			if (!keys?.includes(current.route.key)) return;
+
+			runOnJS(activate)();
+			startScreenTransition({
+				target: "close",
+				spec: current.options.transitionSpec,
+				animations,
+				onAnimationFinish: handleCloseEnd,
+			});
+		},
+	);
+};
+
+/**
+ * Native stack close - listens to beforeRemove navigation event.
+ */
+const useNativeStackClose = ({
+	current,
+	animations,
+	activate,
+	deactivate,
+}: CloseHookParams) => {
+	const gestureCtx = useGestureContext();
+
+	const isAncestorDismissingViaGesture = useSharedValueState(
+		useDerivedValue(() => {
+			"worklet";
+			return (
+				gestureCtx?.ancestorContext?.gestureAnimationValues.isDismissing
+					?.value ?? false
+			);
+		}),
+	);
+
+	const handleBeforeRemove = useStableCallback((e: any) => {
+		const options = current.options as { enableTransitions?: boolean };
+		const isEnabled = options.enableTransitions;
+		const navigation = current.navigation;
+		const isFirstScreen = navigation.getState().index === 0;
+
+		// If transitions are disabled, ancestor is dismissing, or first screen - let native handle it
+		if (!isEnabled || isAncestorDismissingViaGesture || isFirstScreen) {
+			animations.closing.set(1);
+			resetStoresForScreen(current);
+			return;
+		}
+
+		e.preventDefault();
+		activate();
+
+		startScreenTransition({
+			target: "close",
+			spec: current.options.transitionSpec,
+			animations,
+			onAnimationFinish: (finished: boolean) => {
+				deactivate();
+				if (finished) {
+					navigation.dispatch(e.data.action);
+					requestAnimationFrame(() => {
+						resetStoresForScreen(current);
+					});
+				}
+			},
+		});
+	});
+
+	// biome-ignore lint/correctness/useExhaustiveDependencies: Only re-subscribe when navigation changes
+	useLayoutEffect(() => {
+		return current.navigation.addListener?.("beforeRemove", handleBeforeRemove);
+	}, [current.navigation]);
+};
+
+/**
+ * Unified close handler that branches on stack type.
+ */
+export function useCloseTransition(
+	current: BaseDescriptor,
+	animations: AnimationStoreMap,
+	activate: () => void,
+	deactivate: () => void,
+) {
+	const { flags } = useStackCoreContext();
+	const isNativeStack = flags.STACK_TYPE === StackType.NATIVE;
+
+	const closeParams: CloseHookParams = {
+		current,
+		animations,
+		activate,
+		deactivate,
+	};
+
+	if (isNativeStack) {
+		// biome-ignore lint/correctness/useHookAtTopLevel: STACK_TYPE is stable per screen instance
+		useNativeStackClose(closeParams);
+	} else {
+		// biome-ignore lint/correctness/useHookAtTopLevel: STACK_TYPE is stable per screen instance
+		useManagedClose(closeParams);
+	}
+}

package/src/shared/hooks/lifecycle/use-open-transition.ts

@@ -0,0 +1,30 @@
+import { useLayoutEffect } from "react";
+import type { BaseDescriptor } from "../../providers/screen/keys.provider";
+import type { AnimationStoreMap } from "../../stores/animation.store";
+import { startScreenTransition } from "../../utils/animation/start-screen-transition";
+import { useHighRefreshRate } from "../animation/use-high-refresh-rate";
+
+/**
+ * Handles opening animation on mount.
+ * Returns activate/deactivate functions for high refresh rate.
+ */
+export function useOpenTransition(
+	current: BaseDescriptor,
+	animations: AnimationStoreMap,
+) {
+	const { activateHighRefreshRate, deactivateHighRefreshRate } =
+		useHighRefreshRate(current);
+
+	// biome-ignore lint/correctness/useExhaustiveDependencies: Must only run once on mount
+	useLayoutEffect(() => {
+		activateHighRefreshRate();
+		startScreenTransition({
+			target: "open",
+			spec: current.options.transitionSpec,
+			animations,
+			onAnimationFinish: deactivateHighRefreshRate,
+		});
+	}, []);
+
+	return { activateHighRefreshRate, deactivateHighRefreshRate };
+}

package/src/shared/hooks/lifecycle/use-screen-events.ts

@@ -0,0 +1,62 @@
+import { useEffect } from "react";
+import { runOnJS, useAnimatedReaction } from "react-native-reanimated";
+import type { BaseDescriptor } from "../../providers/screen/keys.provider";
+import type { AnimationStoreMap } from "../../stores/animation.store";
+import { HistoryStore } from "../../stores/history.store";
+import useStableCallback from "../use-stable-callback";
+
+/**
+ * Check if a screen is a leaf (renders visible content) vs a navigator container.
+ * Navigator containers have nested state with routes.
+ */
+function isLeafScreen(navigation: BaseDescriptor["navigation"]): boolean {
+	const state = navigation.getState();
+	const currentRoute = state.routes[state.index];
+	return !("state" in currentRoute);
+}
+
+/**
+ * Updates the HistoryStore for navigation history tracking.
+ */
+export function useScreenEvents(
+	current: BaseDescriptor,
+	previous: BaseDescriptor | undefined,
+	animations: AnimationStoreMap,
+) {
+	const navigatorKey = current.navigation.getState()?.key ?? "";
+
+	// Track history via focus listener - waits for nested navigators to initialize
+	// biome-ignore lint/correctness/useExhaustiveDependencies: Must only run once on mount
+	useEffect(() => {
+		// Check on mount (after paint, nested navs initialized)
+		if (isLeafScreen(current.navigation)) {
+			HistoryStore.focus(current, navigatorKey);
+		}
+
+		// Also listen for focus events
+		const unsubscribe = current.navigation.addListener?.("focus", () => {
+			if (isLeafScreen(current.navigation)) {
+				HistoryStore.focus(current, navigatorKey);
+			}
+		});
+
+		return () => unsubscribe?.();
+	}, []);
+
+	// When closing starts, focus previous in history
+	const handleBlur = useStableCallback(() => {
+		if (previous && isLeafScreen(previous.navigation)) {
+			const prevNavigatorKey = previous.navigation.getState()?.key ?? "";
+			HistoryStore.focus(previous, prevNavigatorKey);
+		}
+	});
+
+	useAnimatedReaction(
+		() => animations.closing.get(),
+		(closing, prevClosing) => {
+			if (closing && !prevClosing) {
+				runOnJS(handleBlur)();
+			}
+		},
+	);
+}

package/src/shared/hooks/navigation/use-history.ts

@@ -0,0 +1,63 @@
+import { useMemo, useSyncExternalStore } from "react";
+import { type HistoryEntry, HistoryStore } from "../../stores/history.store";
+import type { ScreenKey } from "../../types/screen.types";
+
+export interface UseHistoryReturn {
+	/**
+	 * The full history map.
+	 */
+	history: ReadonlyMap<ScreenKey, HistoryEntry>;
+
+	/**
+	 * Get N most recent history entries.
+	 * Most recent first.
+	 */
+	getRecent: (n: number) => HistoryEntry[];
+
+	/**
+	 * Get history entries for a specific navigator.
+	 * Most recent first.
+	 */
+	getByNavigator: (navigatorKey: string) => HistoryEntry[];
+
+	/**
+	 * Get the path between two screens (for multi-waypoint interpolation).
+	 * Returns screen keys in order from 'from' to 'to'.
+	 */
+	getPath: (fromKey: ScreenKey, toKey: ScreenKey) => ScreenKey[];
+
+	/**
+	 * Get a specific history entry by screen key.
+	 */
+	get: (screenKey: ScreenKey) => HistoryEntry | undefined;
+
+	/**
+	 * Get the most recent history entry (for forward navigation).
+	 */
+	getMostRecent: () => HistoryEntry | undefined;
+}
+
+/**
+ * Subscribe to history store changes.
+ * Returns the full history map and helper methods.
+ */
+export function useHistory(): UseHistoryReturn {
+	const history = useSyncExternalStore(
+		HistoryStore.subscribe,
+		HistoryStore.getSnapshot,
+	);
+
+	return useMemo(
+		() => ({
+			history,
+			getRecent: (n: number) => HistoryStore.getRecent(n),
+			getByNavigator: (navigatorKey: string) =>
+				HistoryStore.getByNavigator(navigatorKey),
+			getPath: (fromKey: ScreenKey, toKey: ScreenKey) =>
+				HistoryStore.getPath(fromKey, toKey),
+			get: (screenKey: ScreenKey) => HistoryStore.get(screenKey),
+			getMostRecent: () => HistoryStore.getMostRecent(),
+		}),
+		[history],
+	);
+}

package/src/shared/index.ts

@@ -20,6 +20,7 @@ export default {
 
 export { useScreenAnimation } from "./hooks/animation/use-screen-animation";
 export { useScreenGesture } from "./hooks/gestures/use-screen-gesture";
+export { useHistory } from "./hooks/navigation/use-history";
 export {
 	type ScreenState,
 	useScreenState,

package/src/shared/providers/screen/keys.provider.tsx

@@ -1,11 +1,4 @@
-import type {
-	Descriptor,
-	NavigationProp,
-	ParamListBase,
-	RouteProp,
-} from "@react-navigation/native";
 import { createContext, useContext, useMemo } from "react";
-import type { ScreenTransitionConfig } from "../../types/screen.types";
 import type { BaseStackDescriptor } from "../../types/stack.types";
 
 /**
@@ -15,15 +8,6 @@ import type { BaseStackDescriptor } from "../../types/stack.types";
  */
 export type BaseDescriptor = BaseStackDescriptor;
 
-/**
- * React Navigation specific descriptor - extends base with full typing
- */
-export type TransitionDescriptor = Descriptor<
-	ScreenTransitionConfig,
-	NavigationProp<ParamListBase>,
-	RouteProp<ParamListBase>
->;
-
 interface KeysContextType<TDescriptor extends BaseDescriptor = BaseDescriptor> {
 	previous?: TDescriptor;
 	current: TDescriptor;

package/src/shared/providers/screen/screen-composer.tsx

@@ -19,18 +19,14 @@ export function ScreenComposer<TDescriptor extends BaseDescriptor>({
 	children,
 }: Props<TDescriptor>) {
 	return (
-		<KeysProvider<TDescriptor>
-			previous={previous}
-			current={current}
-			next={next}
-		>
-			<ScreenGestureProvider>
-				<ScreenLifecycle>
+		<ScreenLifecycle current={current} previous={previous}>
+			<KeysProvider previous={previous} current={current} next={next}>
+				<ScreenGestureProvider>
 					<ScreenStylesProvider>
 						<RootTransitionAware>{children}</RootTransitionAware>
 					</ScreenStylesProvider>
-				</ScreenLifecycle>
-			</ScreenGestureProvider>
-		</KeysProvider>
+				</ScreenGestureProvider>
+			</KeysProvider>
+		</ScreenLifecycle>
 	);
 }

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

@@ -4,7 +4,7 @@ import type {
 	StackNavigationState,
 } from "@react-navigation/native";
 import * as React from "react";
-import { useMemo } from "react";
+import { useEffect, useMemo } from "react";
 import { type DerivedValue, useDerivedValue } from "react-native-reanimated";
 import type {
 	NativeStackDescriptor,
@@ -16,6 +16,7 @@ import {
 	type StackContextValue,
 } from "../../hooks/navigation/use-stack";
 import { AnimationStore } from "../../stores/animation.store";
+import { HistoryStore } from "../../stores/history.store";
 import { useStackCoreContext } from "./core.provider";
 
 export interface DirectStackScene {
@@ -216,6 +217,15 @@ function withDirectStack<TProps extends DirectStackProps>(
 	Component: React.ComponentType<DirectStackContextValue>,
 ): React.FC<TProps> {
 	return function DirectStackProvider(props: TProps) {
+		const navigatorKey = props.state.key;
+
+		// Clean up history when navigator unmounts
+		useEffect(() => {
+			return () => {
+				HistoryStore.clearNavigator(navigatorKey);
+			};
+		}, [navigatorKey]);
+
 		const { stackContextValue, ...lifecycleValue } = useDirectStackValue(props);
 
 		return (

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

@@ -1,6 +1,6 @@
 import type { Route } from "@react-navigation/native";
 import * as React from "react";
-import { useMemo } from "react";
+import { useEffect, useMemo } from "react";
 import {
 	type DerivedValue,
 	type SharedValue,
@@ -11,6 +11,7 @@ import {
 	type StackContextValue,
 } from "../../hooks/navigation/use-stack";
 import { AnimationStore } from "../../stores/animation.store";
+import { HistoryStore } from "../../stores/history.store";
 import type {
 	BaseStackDescriptor,
 	BaseStackNavigation,
@@ -211,6 +212,15 @@ function withManagedStack<
 	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