react-native-screen-transitions 3.11.2 → 3.12.0

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

@@ -2,53 +2,160 @@ import {
 	NavigationContext,
 	NavigationRouteContext,
 } from "@react-navigation/native";
-import { memo, useMemo } from "react";
-import { Animated, StyleSheet, View } from "react-native";
-import { useDerivedValue } from "react-native-reanimated";
-import type { StackScene } from "../../../hooks/navigation/use-stack";
-import { useScreenAnimation } from "../../../providers/screen/animation";
-import type { BaseDescriptor } from "../../../providers/screen/descriptors";
+import { memo, useMemo, useRef } from "react";
+import { StyleSheet, View } from "react-native";
+import Animated, { useDerivedValue } from "react-native-reanimated";
+import { snapDescriptorToIndex } from "../../../animation/snap-to";
+import { useStack } from "../../../hooks/navigation/use-stack";
+import { useScreenAnimationStore } from "../../../providers/screen/animation";
+import type { ScreenAnimationContextValue } from "../../../providers/screen/animation/animation.provider";
+import {
+	type ScreenSlotContextValue,
+	useScreenSlots,
+} from "../../../providers/screen/styles/slot.provider";
+import type { OverlayProps } from "../../../types/overlay.types";
 import type {
-	OverlayProps,
-	OverlayScreenState,
-} from "../../../types/overlay.types";
+	FloatOverlayActivity,
+	FloatOverlayEntry,
+} from "../helpers/get-active-overlay";
+import {
+	type ReadyOverlayResources,
+	retainReadyOverlayResources,
+} from "../helpers/retain-ready-overlay-resources";
+import { useOverlaySlot } from "../hooks/use-overlay-slot";
 
 type OverlayHostProps = {
-	scene: StackScene;
-	overlayScreenState: OverlayScreenState<BaseDescriptor["navigation"]>;
+	scene: FloatOverlayEntry["scene"];
+	driverScene: FloatOverlayEntry["scene"];
+	previousOverlayScene?: FloatOverlayEntry["scene"];
+	activity: FloatOverlayActivity;
+	layerIndex: number;
 };
 
 export const OverlayHost = memo(function OverlayHost({
 	scene,
-	overlayScreenState,
+	driverScene,
+	previousOverlayScene,
+	activity,
+	layerIndex,
 }: OverlayHostProps) {
-	const OverlayComponent = scene.descriptor.options.overlay;
+	const overlayAnimationStore = useScreenAnimationStore(scene.route.key);
+	const driverAnimationStore = useScreenAnimationStore(driverScene.route.key);
+	const previousOverlayAnimationStore = useScreenAnimationStore(
+		previousOverlayScene?.route.key ?? scene.route.key,
+	);
+	const driverSlots = useScreenSlots(driverScene.route.key);
+	const overlayComponentRef = useRef(scene.descriptor.options.overlay);
+	const OverlayComponent = overlayComponentRef.current;
+	const readyResourcesRef = useRef<ReadyOverlayResources | null>(null);
+	readyResourcesRef.current = retainReadyOverlayResources(
+		readyResourcesRef.current,
+		overlayAnimationStore,
+		driverScene,
+		driverAnimationStore,
+		driverSlots,
+	);
+	const readyResources = readyResourcesRef.current;
+
+	if (!OverlayComponent || !readyResources) {
+		return null;
+	}
+
+	return (
+		<ReadyOverlayHost
+			scene={scene}
+			driverScene={readyResources.driverScene}
+			activity={activity}
+			layerIndex={layerIndex}
+			overlayAnimationStore={readyResources.overlayAnimationStore}
+			driverAnimationStore={readyResources.driverAnimationStore}
+			previousOverlayAnimationStore={
+				previousOverlayScene ? previousOverlayAnimationStore : undefined
+			}
+			driverSlots={readyResources.driverSlots}
+			OverlayComponent={OverlayComponent}
+		/>
+	);
+});
+
+type ReadyOverlayHostProps = OverlayHostProps & {
+	overlayAnimationStore: ScreenAnimationContextValue;
+	driverAnimationStore: ScreenAnimationContextValue;
+	previousOverlayAnimationStore?: ScreenAnimationContextValue | null;
+	driverSlots: ScreenSlotContextValue;
+	OverlayComponent: NonNullable<
+		FloatOverlayEntry["scene"]["descriptor"]["options"]["overlay"]
+	>;
+};
 
-	const screenAnimation = useScreenAnimation();
+function ReadyOverlayHost({
+	scene,
+	driverScene,
+	activity,
+	layerIndex,
+	overlayAnimationStore,
+	driverAnimationStore,
+	previousOverlayAnimationStore,
+	driverSlots,
+	OverlayComponent,
+}: ReadyOverlayHostProps) {
+	const { scenes, focusedIndex, routeKeys, routes } = useStack();
+	const descriptor = scene.descriptor;
+	const focusedScene = scenes[focusedIndex] ?? scenes[scenes.length - 1];
+	const focusedDescriptor = focusedScene?.descriptor;
+	const { animatedProps, animatedStyle } = useOverlaySlot({
+		overlayAnimationStore,
+		driverAnimationStore,
+		previousOverlayAnimationStore: previousOverlayAnimationStore ?? undefined,
+		driverInterpolator: driverScene.descriptor.options.screenStyleInterpolator,
+		interpolatorReady: driverSlots.interpolatorReady,
+		isIncoming: scene.route.key === driverScene.route.key,
+	});
 	const relativeProgress = useDerivedValue(() => {
 		"worklet";
-		return screenAnimation.get().stackProgress;
+		overlayAnimationStore.screenInterpolatorPropsRevision.get();
+		return overlayAnimationStore.screenInterpolatorProps.get().stackProgress;
 	});
 
-	const overlayProps: OverlayProps<BaseDescriptor["navigation"]> = useMemo(
+	const overlayProps: OverlayProps = useMemo(
 		() => ({
-			...overlayScreenState,
+			route: scene.route,
+			index: routeKeys.indexOf(scene.route.key),
+			options: focusedDescriptor?.options ?? {},
+			routes,
+			focusedRoute: focusedScene?.route ?? scene.route,
+			focusedIndex,
+			meta: focusedDescriptor?.options?.meta,
+			navigation: scene.descriptor.navigation,
+			snapTo: (index: number) => {
+				snapDescriptorToIndex(scene.descriptor, index);
+			},
 			progress: relativeProgress,
 		}),
-		[relativeProgress, overlayScreenState],
+		[
+			scene,
+			focusedDescriptor?.options,
+			focusedIndex,
+			focusedScene?.route,
+			relativeProgress,
+			routeKeys,
+			routes,
+		],
 	);
-
-	if (!OverlayComponent) {
-		return null;
-	}
-
 	return (
 		<Animated.View
-			pointerEvents="box-none"
-			style={[styles.container, styles.floating, StyleSheet.absoluteFill]}
+			animatedProps={animatedProps}
+			pointerEvents={activity === "active" ? "box-none" : "none"}
+			style={[
+				styles.container,
+				styles.floating,
+				StyleSheet.absoluteFill,
+				{ zIndex: 1000 + layerIndex },
+				animatedStyle,
+			]}
 		>
-			<NavigationContext.Provider value={scene.descriptor.navigation as any}>
-				<NavigationRouteContext.Provider value={scene.route}>
+			<NavigationContext.Provider value={descriptor.navigation as any}>
+				<NavigationRouteContext.Provider value={descriptor.route}>
 					<View
 						pointerEvents="box-none"
 						style={[StyleSheet.absoluteFill, styles.overlay]}
@@ -59,7 +166,7 @@ export const OverlayHost = memo(function OverlayHost({
 			</NavigationContext.Provider>
 		</Animated.View>
 	);
-});
+}
 
 const styles = StyleSheet.create({
 	overlay: {

package/src/shared/components/screen-container/layers/backdrop.tsx

@@ -1,6 +1,6 @@
 import { type ComponentType, memo, useCallback, useMemo } from "react";
 import { Pressable, StyleSheet } from "react-native";
-import Animated, { runOnUI } from "react-native-reanimated";
+import Animated, { runOnJS, runOnUI } from "react-native-reanimated";
 import { DefaultSnapSpec } from "../../../configs/specs";
 import { useNavigationHelpers } from "../../../hooks/navigation/use-navigation-helpers";
 import { useDescriptorsStore } from "../../../providers/screen/descriptors";
@@ -23,7 +23,7 @@ export const BackdropLayer = memo(function BackdropLayer({
 	backdropBehavior: BackdropBehavior;
 	isBackdropActive: boolean;
 }) {
-	const { dismissScreen } = useNavigationHelpers();
+	const { isRemovePrevented, requestDismiss } = useNavigationHelpers();
 
 	const routeKey = useDescriptorsStore(
 		(store) => store.derivations.currentScreenKey,
@@ -34,9 +34,10 @@ export const BackdropLayer = memo(function BackdropLayer({
 	const rawSnapPoints = useDescriptorsStore(
 		(store) => store.options.snapPoints,
 	);
-	const canDismiss = useDescriptorsStore(
+	const isGestureDismissEnabled = useDescriptorsStore(
 		(store) => store.options.gestureEnabled !== false,
 	);
+	const canDismiss = isGestureDismissEnabled && !isRemovePrevented;
 	const transitionSpec = useDescriptorsStore(
 		(store) => store.options.transitionSpec,
 	);
@@ -56,14 +57,14 @@ export const BackdropLayer = memo(function BackdropLayer({
 
 	const handleBackdropPress = useCallback(() => {
 		if (backdropBehavior === "dismiss") {
-			dismissScreen();
+			requestDismiss();
 			return;
 		}
 
 		if (backdropBehavior === "collapse") {
 			// No snap points → fallback to dismiss
 			if (!rawSnapPoints || rawSnapPoints.length === 0) {
-				dismissScreen();
+				requestDismiss();
 				return;
 			}
 
@@ -108,8 +109,11 @@ export const BackdropLayer = memo(function BackdropLayer({
 					animations,
 					targetProgress,
 					animationProgress,
-					onAnimationFinish: shouldDismiss ? dismissScreen : undefined,
 				});
+
+				if (shouldDismiss) {
+					runOnJS(requestDismiss)();
+				}
 			})();
 		}
 	}, [
@@ -121,7 +125,7 @@ export const BackdropLayer = memo(function BackdropLayer({
 		rawSnapPoints,
 		canDismiss,
 		transitionSpec,
-		dismissScreen,
+		requestDismiss,
 		routeKey,
 	]);
 

package/src/shared/components/screen-lifecycle/hooks/helpers/close-interception-rules.ts

@@ -0,0 +1,64 @@
+interface CloseInterceptionState {
+	enabled: boolean;
+	ownsAction: boolean;
+	ancestorDismissing: boolean;
+	routeIndex: number;
+	focusedIndex: number;
+}
+
+interface NavigationRouteLike {
+	key: string;
+	state?: NavigationStateLike;
+}
+
+interface NavigationStateLike {
+	key?: string;
+	routes: NavigationRouteLike[];
+}
+
+interface NavigationActionLike {
+	source?: unknown;
+	target?: unknown;
+}
+
+const containsRouteKey = (
+	routes: NavigationRouteLike[],
+	routeKey: string,
+): boolean =>
+	routes.some(
+		(route) =>
+			route.key === routeKey ||
+			(route.state ? containsRouteKey(route.state.routes, routeKey) : false),
+	);
+
+export const doesNavigatorOwnCloseAction = ({
+	state,
+	action,
+}: {
+	state: NavigationStateLike;
+	action: NavigationActionLike;
+}): boolean => {
+	if (typeof action.target === "string") {
+		return action.target === state.key;
+	}
+
+	if (typeof action.source === "string") {
+		return containsRouteKey(state.routes, action.source);
+	}
+
+	return true;
+};
+
+/** Only the focused removable route owns a stack close transition. */
+export const shouldInterceptClose = ({
+	enabled,
+	ownsAction,
+	ancestorDismissing,
+	routeIndex,
+	focusedIndex,
+}: CloseInterceptionState) =>
+	enabled &&
+	ownsAction &&
+	!ancestorDismissing &&
+	routeIndex > 0 &&
+	routeIndex === focusedIndex;

package/src/shared/components/screen-lifecycle/hooks/use-close-completion.ts

@@ -0,0 +1,28 @@
+import {
+	runOnJS,
+	type SharedValue,
+	useAnimatedReaction,
+} from "react-native-reanimated";
+
+export const useCloseCompletion = ({
+	closing,
+	animationProgress,
+	onComplete,
+}: {
+	closing: SharedValue<number>;
+	animationProgress: SharedValue<number>;
+	onComplete: () => void;
+}) => {
+	useAnimatedReaction(
+		() => {
+			"worklet";
+			return !!closing.get() && animationProgress.get() <= 0;
+		},
+		(complete, previouslyComplete) => {
+			"worklet";
+			if (complete && !previouslyComplete) {
+				runOnJS(onComplete)();
+			}
+		},
+	);
+};

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

@@ -1,6 +1,7 @@
-/** biome-ignore-all lint/correctness/useHookAtTopLevel: STACK_TYPE is stable per navigator */
 import { useLayoutEffect, useMemo, useRef } from "react";
+import { useNavigationHelpers } from "../../../hooks/navigation/use-navigation-helpers";
 import useStableCallback from "../../../hooks/use-stable-callback";
+import { hasTransitionsEnabled } from "../../../providers/screen/animation/helpers/has-transitions-enabled";
 import {
 	type BaseDescriptor,
 	useDescriptorsStore,
@@ -8,68 +9,34 @@ import {
 import { useBlankStackStore } from "../../../providers/stack/blank-stack.provider";
 import { useStackCoreStore } from "../../../providers/stack/core.provider";
 import { GestureStore } from "../../../stores/gesture.store";
-import {
-	LifecycleTransitionRequestKind,
-	type SystemStoreActions,
-	type SystemStoreMap,
-} from "../../../stores/system.store";
 import { StackType } from "../../../types/stack.types";
+import {
+	dispatchCloseAction,
+	isCloseActionReplay,
+} from "../../../utils/navigation/close-action-replay";
+import {
+	doesNavigatorOwnCloseAction,
+	shouldInterceptClose,
+} from "./helpers/close-interception-rules";
 import { resetStoresForScreen } from "./helpers/reset-stores-for-screen";
 
-interface CloseHookParams {
-	current: BaseDescriptor;
-	requestLifecycleTransition: SystemStoreActions["requestLifecycleTransition"];
-	resetStores: () => void;
-}
-
-const useBlankStackClose = ({
-	current,
-	requestLifecycleTransition,
-	resetStores,
-}: CloseHookParams) => {
+export function useCloseTransitionIntent(current: BaseDescriptor): {
+	completeClose: () => void;
+} {
+	const routeKey = current.route.key;
+	const { STACK_TYPE: stackType, TRANSITIONS_ALWAYS_ON: transitionsAlwaysOn } =
+		useStackCoreStore((store) => store.flags);
 	const handleCloseRoute = useBlankStackStore(
 		(store) => store?.handleCloseRoute,
 	);
-	const isClosing = useBlankStackStore(
-		(store) => store?.scenesByKey[current.route.key]?.activity === "closing",
+	const isBlankStackClosing = useBlankStackStore(
+		(store) => store?.scenesByKey[routeKey]?.activity === "closing",
 	);
-
-	useLayoutEffect(() => {
-		if (!isClosing) {
-			return;
-		}
-
-		requestLifecycleTransition(
-			LifecycleTransitionRequestKind.BlankStackClose,
-			0,
-		);
-	}, [isClosing, requestLifecycleTransition]);
-
-	const handleBlankStackCloseEnd = useStableCallback((finished: boolean) => {
-		if (!finished) return;
-		if (!handleCloseRoute) {
-			throw new Error("Blank stack close handler was not found.");
-		}
-		handleCloseRoute({ route: current.route });
-		requestAnimationFrame(() => {
-			resetStores();
-		});
-	});
-
-	return { handleBlankStackCloseEnd };
-};
-
-/**
- * Native stack close - listens to beforeRemove navigation event.
- */
-const useNativeStackClose = ({
-	current,
-	requestLifecycleTransition,
-	resetStores,
-}: CloseHookParams) => {
-	const parentScreenKey = useDescriptorsStore(
-		(store) => store.derivations.parentScreenKey,
+	const ancestorKeys = useDescriptorsStore(
+		(store) => store.derivations.ancestorKeys,
 	);
+	const parentScreenKey = ancestorKeys[0];
+	const { dismissScreen, requestDismiss } = useNavigationHelpers();
 	const pendingActionRef = useRef<any>(null);
 
 	const nearestAncestorDismissing = useMemo(() => {
@@ -78,76 +45,72 @@ const useNativeStackClose = ({
 		return GestureStore.peekBag(parentScreenKey)?.dismissing ?? null;
 	}, [parentScreenKey]);
 
-	const handleNativeCloseEnd = useStableCallback((finished: boolean) => {
-		if (!finished || !pendingActionRef.current) {
-			pendingActionRef.current = null;
-			return;
+	useLayoutEffect(() => {
+		if (isBlankStackClosing) {
+			requestDismiss();
 		}
+	}, [isBlankStackClosing, requestDismiss]);
 
-		current.navigation.dispatch(pendingActionRef.current);
+	const completeClose = useStableCallback(() => {
+		const pendingAction = pendingActionRef.current;
 		pendingActionRef.current = null;
-		requestAnimationFrame(() => {
-			resetStores();
-		});
+
+		if (pendingAction) {
+			dispatchCloseAction(pendingAction, (action) => {
+				current.navigation.dispatch(action);
+			});
+		} else if (stackType !== StackType.NATIVE && handleCloseRoute) {
+			handleCloseRoute({ route: current.route });
+		} else {
+			dismissScreen();
+		}
+
+		resetStoresForScreen(routeKey);
 	});
 
-	const handleBeforeRemove = useStableCallback((e: any) => {
-		const options = current.options as { enableTransitions?: boolean };
-		const isEnabled = options.enableTransitions;
-		const navigation = current.navigation;
-		const routeKey = current.route.key;
-		const state = navigation.getState();
+	const handleBeforeRemove = useStableCallback((event: any) => {
+		if (isCloseActionReplay(event.data.action)) {
+			return;
+		}
+
+		const state = current.navigation.getState();
 		const routeIndex = state.routes.findIndex(
 			(route) => route.key === routeKey,
 		);
-		const isFirstScreen = routeIndex <= 0;
+		const action = event.data.action;
+		const ownsAction = doesNavigatorOwnCloseAction({
+			state,
+			action,
+		});
+		const shouldIntercept = shouldInterceptClose({
+			enabled: hasTransitionsEnabled(current.options, transitionsAlwaysOn),
+			ownsAction,
+			ancestorDismissing: !!nearestAncestorDismissing?.get(),
+			routeIndex,
+			focusedIndex: state.index,
+		});
+
+		if (!shouldIntercept) {
+			return;
+		}
 
-		if (!isEnabled || nearestAncestorDismissing?.get() || isFirstScreen) {
-			resetStores();
+		pendingActionRef.current ??= event.data.action;
+		if (!requestDismiss()) {
+			pendingActionRef.current = null;
 			return;
 		}
 
-		e.preventDefault();
-		pendingActionRef.current = e.data.action;
-		requestLifecycleTransition(LifecycleTransitionRequestKind.NativeClose, 0);
+		event.preventDefault();
 	});
 
 	// biome-ignore lint/correctness/useExhaustiveDependencies: navigation listener should only rebind when the navigator instance changes
 	useLayoutEffect(() => {
-		return current.navigation.addListener?.("beforeRemove", handleBeforeRemove);
-	}, [current.navigation]);
-
-	return { handleNativeCloseEnd };
-};
-
-/**
- * Handles close transition intent and returns finish callbacks for cleanup.
- */
-export function useCloseTransitionIntent(
-	current: BaseDescriptor,
-	system: SystemStoreMap,
-): {
-	handleBlankStackCloseEnd?: (finished: boolean) => void;
-	handleNativeCloseEnd?: (finished: boolean) => void;
-} {
-	const routeKey = current.route.key;
-	const stackType = useStackCoreStore((store) => store.flags.STACK_TYPE);
-	const isNativeStack = stackType === StackType.NATIVE;
-	const { requestLifecycleTransition } = system.actions;
-
-	const resetStores = useStableCallback(() => {
-		resetStoresForScreen(routeKey);
-	});
-
-	const closeParams: CloseHookParams = {
-		current,
-		requestLifecycleTransition,
-		resetStores,
-	};
+		if (stackType !== StackType.NATIVE) {
+			return;
+		}
 
-	if (isNativeStack) {
-		return useNativeStackClose(closeParams);
-	}
+		return current.navigation.addListener?.("beforeRemove", handleBeforeRemove);
+	}, [current.navigation, stackType]);
 
-	return useBlankStackClose(closeParams);
+	return { completeClose };
 }

package/src/shared/components/screen-lifecycle/hooks/use-transition-start-controller.ts

@@ -12,14 +12,10 @@ export const useTransitionStartController = ({
 	current,
 	animations,
 	system,
-	onBlankStackCloseFinish,
-	onNativeCloseFinish,
 }: {
 	current: BaseDescriptor;
 	animations: AnimationStoreMap;
 	system: SystemStoreMap;
-	onBlankStackCloseFinish?: (finished: boolean) => void;
-	onNativeCloseFinish?: (finished: boolean) => void;
 }) => {
 	const {
 		targetProgress,
@@ -53,13 +49,6 @@ export const useTransitionStartController = ({
 				return;
 			}
 
-			const onAnimationFinish =
-				kind === LifecycleTransitionRequestKind.BlankStackClose
-					? onBlankStackCloseFinish
-					: kind === LifecycleTransitionRequestKind.NativeClose
-						? onNativeCloseFinish
-						: undefined;
-
 			animateToProgress({
 				target,
 				spec: transitionSpec,
@@ -69,7 +58,6 @@ export const useTransitionStartController = ({
 				animations,
 				targetProgress,
 				animationProgress,
-				onAnimationFinish,
 				isDragging,
 			});
 

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

@@ -2,6 +2,7 @@ import { useDescriptorsStore } from "../../providers/screen/descriptors";
 import { AnimationStore } from "../../stores/animation.store";
 import { SystemStore } from "../../stores/system.store";
 import { useScreenHistory } from "./hooks/history/use-screen-history";
+import { useCloseCompletion } from "./hooks/use-close-completion";
 import { useCloseTransitionIntent } from "./hooks/use-close-transition-intent";
 import { useOpenTransitionIntent } from "./hooks/use-open-transition-intent";
 import { useTransitionStartController } from "./hooks/use-transition-start-controller";
@@ -21,8 +22,7 @@ export const ScreenLifecycle = ({ children }: Props) => {
 	const animations = AnimationStore.getBag(current.route.key);
 	const system = SystemStore.getBag(current.route.key);
 
-	const { handleBlankStackCloseEnd, handleNativeCloseEnd } =
-		useCloseTransitionIntent(current, system);
+	const { completeClose } = useCloseTransitionIntent(current);
 
 	useOpenTransitionIntent(current, animations, system);
 
@@ -30,8 +30,12 @@ export const ScreenLifecycle = ({ children }: Props) => {
 		current,
 		animations,
 		system,
-		onBlankStackCloseFinish: handleBlankStackCloseEnd,
-		onNativeCloseFinish: handleNativeCloseEnd,
+	});
+
+	useCloseCompletion({
+		closing: animations.closing,
+		animationProgress: system.animationProgress,
+		onComplete: completeClose,
 	});
 
 	useScreenHistory(current, previous, animations);