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

package/src/shared/components/overlay/variations/overlay-host.tsx

@@ -1,131 +1,65 @@
 import {
 	NavigationContext,
 	NavigationRouteContext,
-	type Route,
 } from "@react-navigation/native";
 import { memo, useMemo } from "react";
 import { Animated, StyleSheet, useWindowDimensions, View } from "react-native";
 import { useDerivedValue } from "react-native-reanimated";
 import { useSafeAreaInsets } from "react-native-safe-area-context";
 import { useScreenAnimation } from "../../../hooks/animation/use-screen-animation";
-import { type StackScene, useStack } from "../../../hooks/navigation/use-stack";
-import { useSharedValueState } from "../../../hooks/reanimated/use-shared-value-state";
+import { useScreenState } from "../../../hooks/navigation/use-screen-state";
+import type { StackScene } from "../../../hooks/navigation/use-stack";
+import type { BaseDescriptor } from "../../../providers/screen/keys.provider";
 import type { OverlayInterpolationProps } from "../../../types/animation.types";
 import type { OverlayProps } from "../../../types/overlay.types";
 
 type OverlayHostProps = {
 	scene: StackScene;
-	scenes: StackScene[];
-	routes: Route<string>[];
-	overlayIndex: number;
-	isFloating?: boolean;
 };
 
 export const OverlayHost = memo(function OverlayHost({
 	scene,
-	scenes,
-	routes,
-	overlayIndex,
-	isFloating,
 }: OverlayHostProps) {
 	const OverlayComponent = scene.descriptor.options.overlay;
 	const screen = useWindowDimensions();
-
-	const { stackProgress, optimisticFocusedIndex, routeKeys } = useStack();
 	const insets = useSafeAreaInsets();
 
+	const screenAnimation = useScreenAnimation();
+	const screenState = useScreenState();
 	const relativeProgress = useDerivedValue(() => {
 		"worklet";
-		return stackProgress.value - overlayIndex;
+		return screenAnimation.value.stackProgress;
 	});
 
-	// For float overlays: global focused index (can be any screen in the stack)
-	// For screen overlays: relative to overlay position (only screens at or after)
-	const optimisticActiveIndex = useSharedValueState(
-		useDerivedValue(() => {
-			"worklet";
-			if (isFloating) {
-				// For float overlays, use global optimistic focused index directly
-				const globalIndex = optimisticFocusedIndex.get();
-				const clampedIndex = Math.max(
-					0,
-					Math.min(globalIndex, routeKeys.length - 1),
-				);
-				return clampedIndex;
-			}
-
-			// For screen overlays, compute relative to overlay position
-			const screensAbove = routeKeys.length - 1 - overlayIndex;
-			const relativeOptimistic = optimisticFocusedIndex.value - overlayIndex;
-			const result = Math.max(0, Math.min(relativeOptimistic, screensAbove));
-
-			return result;
-		}),
-	);
-
 	const overlayAnimation = useDerivedValue<OverlayInterpolationProps>(() => ({
 		progress: relativeProgress.value,
 		layouts: { screen },
 		insets,
 	}));
 
-	const focusedScene = useMemo(() => {
-		if (overlayIndex === -1) {
-			return scene;
-		}
-
-		if (isFloating) {
-			// For float overlays, optimisticActiveIndex is the global focused index
-			return scenes[optimisticActiveIndex] ?? scene;
-		}
-
-		// For screen overlays, optimisticActiveIndex is relative to overlayIndex
-		const maxOffset = Math.max(scenes.length - overlayIndex - 1, 0);
-		const normalizedIndex = Math.min(
-			Math.max(optimisticActiveIndex, 0),
-			maxOffset,
-		);
-
-		return scenes[overlayIndex + normalizedIndex] ?? scene;
-	}, [overlayIndex, optimisticActiveIndex, scenes, scene, isFloating]);
-
-	const screenAnimation = useScreenAnimation();
+	const overlayProps: OverlayProps<BaseDescriptor["navigation"]> = useMemo(
+		() => ({
+			...screenState,
+			progress: relativeProgress,
+			overlayAnimation, //Deprecated
+			screenAnimation, //Deprecated
+		}),
+		[relativeProgress, overlayAnimation, screenAnimation, screenState],
+	);
 
 	if (!OverlayComponent) {
 		return null;
 	}
 
-	const overlayProps: OverlayProps<typeof scene.descriptor.navigation> = {
-		routes,
-		overlayAnimation,
-		screenAnimation,
-		focusedRoute: focusedScene.route,
-		focusedIndex: optimisticActiveIndex,
-		meta: focusedScene.descriptor.options.meta,
-		navigation: scene.descriptor.navigation,
-	};
-
-	// Cast to OverlayProps function - container overlays are handled by ContainerOverlay component
-	const renderOverlay = OverlayComponent as (
-		props: OverlayProps,
-	) => React.ReactNode;
-
 	return (
 		<Animated.View
 			pointerEvents="box-none"
-			style={[
-				styles.container,
-				isFloating ? styles.floating : { zIndex: 1 },
-				styles.absolute,
-			]}
+			style={[styles.container, styles.floating, styles.absolute]}
 		>
-			<NavigationContext.Provider
-				// biome-ignore lint/suspicious/noExplicitAny: navigation type varies by stack
-				value={scene.descriptor.navigation as any}
-			>
+			<NavigationContext.Provider value={scene.descriptor.navigation as any}>
 				<NavigationRouteContext.Provider value={scene.route}>
 					<View pointerEvents="box-none" style={styles.overlay}>
-						{renderOverlay(overlayProps)}
+						<OverlayComponent {...overlayProps} />
 					</View>
 				</NavigationRouteContext.Provider>
 			</NavigationContext.Provider>

package/src/shared/components/overlay/variations/screen-overlay.tsx

@@ -10,10 +10,14 @@ import { OverlayHost } from "./overlay-host";
 /**
  * Screen overlay component that renders per-screen.
  * Gets current descriptor from keys context.
+ *
+ * @deprecated Screen overlays are deprecated. For per-screen overlays, render an
+ * absolute-positioned view directly in your screen component and use `useScreenAnimation()`
+ * to access animation values. This component will be removed in a future version.
  */
 export function ScreenOverlay() {
 	const { current } = useKeys<StackDescriptor>();
-	const { routeKeys, flags } = useStack();
+	const { flags } = useStack();
 
 	const options = current.options;
 
@@ -25,12 +29,6 @@ export function ScreenOverlay() {
 		[current],
 	);
 
-	// Find the index of this screen in the stack
-	const overlayIndex = useMemo(
-		() => routeKeys.indexOf(current.route.key),
-		[routeKeys, current.route.key],
-	);
-
 	// Skip screens without enableTransitions (native-stack only)
 	if (!flags.TRANSITIONS_ALWAYS_ON && !options.enableTransitions) {
 		return null;
@@ -40,12 +38,5 @@ export function ScreenOverlay() {
 		return null;
 	}
 
-	return (
-		<OverlayHost
-			scene={scene}
-			scenes={[scene]}
-			routes={[]}
-			overlayIndex={overlayIndex}
-		/>
-	);
+	return <OverlayHost scene={scene} />;
 }

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

@@ -0,0 +1,32 @@
+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";
+
+interface Props {
+	children: React.ReactNode;
+	current: BaseDescriptor;
+	previous?: BaseDescriptor;
+}
+
+/**
+ * Unified lifecycle controller for all stack types.
+ */
+export const ScreenLifecycle = ({ children, current, previous }: Props) => {
+	const animations = AnimationStore.getAll(current.route.key);
+
+	const { activateHighRefreshRate, deactivateHighRefreshRate } =
+		useOpenTransition(current, animations);
+
+	useCloseTransition(
+		current,
+		animations,
+		activateHighRefreshRate,
+		deactivateHighRefreshRate,
+	);
+
+	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,
@@ -71,8 +72,10 @@ export const FULLSCREEN_DIMENSIONS = (
  */
 export const GESTURE_VELOCITY_IMPACT = 0.3;
 export const DEFAULT_GESTURE_DIRECTION = "horizontal";
-export const DEFAULT_GESTURE_ENABLED = false;
 export const DEFAULT_GESTURE_DRIVES_PROGRESS = true;
 export const DEFAULT_GESTURE_ACTIVATION_AREA: ActivationArea = "screen";
 
 export const IS_WEB = Platform.OS === "web";
+
+export const TRUE = 1;
+export const FALSE = 0;

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

@@ -6,7 +6,6 @@ import type { NativeStackScreenTransitionConfig } from "../../../native-stack/ty
 import { DEFAULT_SCREEN_TRANSITION_STATE } from "../../constants";
 import {
 	type BaseDescriptor,
-	type BaseRoute,
 	useKeys,
 } from "../../providers/screen/keys.provider";
 import { AnimationStore } from "../../stores/animation.store";
@@ -16,6 +15,7 @@ import type {
 	ScreenTransitionState,
 } from "../../types/animation.types";
 import type { ScreenTransitionConfig } from "../../types/screen.types";
+import type { BaseStackRoute } from "../../types/stack.types";
 import { derivations } from "../../utils/animation/derivations";
 import { createBounds } from "../../utils/bounds";
 import { useStack } from "../navigation/use-stack";
@@ -24,19 +24,21 @@ type BuiltState = {
 	progress: SharedValue<number>;
 	closing: SharedValue<number>;
 	animating: SharedValue<number>;
+	entering: SharedValue<number>;
 	gesture: GestureStoreMap;
-	route: BaseRoute;
+	route: BaseStackRoute;
 	meta?: Record<string, unknown>;
 	unwrapped: ScreenTransitionState;
 };
 
 const createScreenTransitionState = (
-	route: BaseRoute,
+	route: BaseStackRoute,
 	meta?: Record<string, unknown>,
 ): ScreenTransitionState => ({
 	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/gestures/use-build-gestures.tsx

@@ -15,7 +15,6 @@ import {
 	DEFAULT_GESTURE_ACTIVATION_AREA,
 	DEFAULT_GESTURE_DIRECTION,
 	DEFAULT_GESTURE_DRIVES_PROGRESS,
-	DEFAULT_GESTURE_ENABLED,
 	GESTURE_VELOCITY_IMPACT,
 } from "../../constants";
 import type {
@@ -35,7 +34,6 @@ import { determineDismissal } from "../../utils/gesture/determine-dismissal";
 import { mapGestureToProgress } from "../../utils/gesture/map-gesture-to-progress";
 import { resetGestureValues } from "../../utils/gesture/reset-gesture-values";
 import { velocity } from "../../utils/gesture/velocity";
-import { useStack } from "../navigation/use-stack";
 import useStableCallbackValue from "../use-stable-callback-value";
 
 interface BuildGesturesHookProps {

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],
+	);
+}