react-native-screen-transitions 3.11.2 → 3.11.3

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,38 +45,62 @@ 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
@@ -117,37 +108,5 @@ const useNativeStackClose = ({
 		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 (isNativeStack) {
-		return useNativeStackClose(closeParams);
-	}
-
-	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);

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

@@ -1,16 +1,23 @@
-import { StackActions } from "@react-navigation/native";
+import {
+	StackActions,
+	usePreventRemoveContext,
+} from "@react-navigation/native";
 import { useCallback } from "react";
 import { useDescriptorsStore } from "../../providers/screen/descriptors";
+import { AnimationStore } from "../../stores/animation.store";
+import {
+	LifecycleTransitionRequestKind,
+	SystemStore,
+} from "../../stores/system.store";
+import { dispatchCloseAction } from "../../utils/navigation/close-action-replay";
 import { useStack } from "./use-stack";
 
 export function useNavigationHelpers() {
 	const route = useDescriptorsStore((store) => store.current.route);
 	const navigation = useDescriptorsStore((store) => store.current.navigation);
 	const requestStackDismiss = useStack((stack) => stack.requestDismiss);
-
-	const requestDismiss = useCallback((): boolean => {
-		return requestStackDismiss?.({ route }) ?? false;
-	}, [route, requestStackDismiss]);
+	const { preventedRoutes } = usePreventRemoveContext();
+	const isRemovePrevented = preventedRoutes[route.key]?.preventRemove === true;
 
 	const dismissScreen = useCallback((): boolean => {
 		const state = navigation.getState();
@@ -20,13 +27,38 @@ export function useNavigationHelpers() {
 		const routeStillPresent = routeIndex !== -1;
 		if (!routeStillPresent || routeIndex === 0) return false;
 
-		navigation.dispatch({
+		const action = {
 			...StackActions.pop(),
 			source: route.key,
 			target: state.key,
+		};
+		dispatchCloseAction(action, (closeAction) => {
+			navigation.dispatch(closeAction);
 		});
 		return true;
 	}, [navigation, route.key]);
 
-	return { dismissScreen, requestDismiss };
+	const requestDismiss = useCallback((): boolean => {
+		if (isRemovePrevented) return false;
+
+		if (requestStackDismiss) {
+			if (!requestStackDismiss({ route })) return false;
+		} else {
+			const state = navigation.getState();
+			const routeIndex = state.routes.findIndex(
+				(stateRoute) => stateRoute.key === route.key,
+			);
+			if (routeIndex <= 0) return false;
+		}
+
+		if (!AnimationStore.getValue(route.key, "closing").get()) {
+			SystemStore.getBag(route.key).actions.requestLifecycleTransition(
+				LifecycleTransitionRequestKind.Close,
+				0,
+			);
+		}
+		return true;
+	}, [isRemovePrevented, navigation, route, requestStackDismiss]);
+
+	return { dismissScreen, isRemovePrevented, requestDismiss };
 }

package/src/shared/providers/helpers/measured-bounds-writes.ts

@@ -67,7 +67,7 @@ export const applyMeasuredBoundsWrites = (
 			measured,
 			preparedStyles,
 			group,
-			{ handoff, escapeClipping },
+			{ handoff },
 		);
 	}
 };

package/src/shared/providers/screen/gestures/hooks/use-screen-gesture-config.ts

@@ -1,3 +1,4 @@
+import { usePreventRemoveContext } from "@react-navigation/native";
 import { useMemo } from "react";
 import { useDescriptorsStore } from "../../descriptors";
 import { useGestureStore } from "../gestures.provider";
@@ -10,6 +11,12 @@ export function useScreenGestureConfig(): ScreenGestureConfig {
 	const isFirstKey = useDescriptorsStore(
 		(store) => store.derivations.isFirstKey,
 	);
+	const currentScreenKey = useDescriptorsStore(
+		(store) => store.derivations.currentScreenKey,
+	);
+	const { preventedRoutes } = usePreventRemoveContext();
+	const isRemovePrevented =
+		preventedRoutes[currentScreenKey]?.preventRemove === true;
 
 	return useMemo(
 		() =>
@@ -17,7 +24,8 @@ export function useScreenGestureConfig(): ScreenGestureConfig {
 				options,
 				isFirstKey,
 				gestureContext,
+				isRemovePrevented,
 			}),
-		[isFirstKey, options, gestureContext],
+		[isFirstKey, options, gestureContext, isRemovePrevented],
 	);
 }

package/src/shared/providers/screen/gestures/pan/behavior/pan-lifecycle.ts

@@ -89,7 +89,6 @@ export const trackPanGesture = (
 export const finalizePanRelease = (
 	release: PanReleaseResult,
 	runtime: PanGestureRuntime,
-	dismissScreen: ((finished: boolean) => void) | undefined,
 	dimensions: GestureDimensions,
 	rawEvent: PanGestureEvent,
 	requestDismiss?: () => void,
@@ -150,13 +149,8 @@ export const finalizePanRelease = (
 		return;
 	}
 
-	if (plan.shouldDismiss && requestDismiss) {
-		runOnJS(requestDismiss)();
-	}
-
 	animateToProgress({
 		target: plan.target,
-		onAnimationFinish: plan.shouldDismiss ? dismissScreen : undefined,
 		spec: plan.transitionSpec,
 		emitWillAnimate: false,
 		markEntering: false,
@@ -165,4 +159,8 @@ export const finalizePanRelease = (
 		animations,
 		initialVelocity: plan.progressVelocity,
 	});
+
+	if (plan.shouldDismiss && requestDismiss) {
+		runOnJS(requestDismiss)();
+	}
 };

package/src/shared/providers/screen/gestures/pan/behavior/use-pan-behavior.ts

@@ -31,7 +31,7 @@ export const usePanBehavior = (
 	gestureCompositionOwner: SharedValue<GestureCompositionOwner>,
 	pendingDirection: SharedValue<Direction | null>,
 ): PanBehavior => {
-	const { dismissScreen, requestDismiss } = useNavigationHelpers();
+	const { requestDismiss } = useNavigationHelpers();
 	const { withSensitivity, resetSensitivity } =
 		usePanGestureSensitivity(screenOptions);
 
@@ -109,7 +109,6 @@ export const usePanBehavior = (
 			finalizePanRelease(
 				release,
 				latestRuntime,
-				dismissScreen,
 				dimensions,
 				rawEvent,
 				requestDismiss,
@@ -124,7 +123,6 @@ export const usePanBehavior = (
 			runtime,
 			screenOptions,
 			dimensions,
-			dismissScreen,
 			requestDismiss,
 			withSensitivity,
 			gestureCompositionOwner,

package/src/shared/providers/screen/gestures/pinch/behavior/pinch-lifecycle.ts

@@ -61,7 +61,6 @@ export const trackPinchGesture = (
 export const finalizePinchRelease = (
 	release: PinchReleaseResult,
 	runtime: PinchGestureRuntime,
-	dismissScreen: ((finished: boolean) => void) | undefined,
 	requestDismiss?: () => void,
 ) => {
 	"worklet";
@@ -91,10 +90,6 @@ export const finalizePinchRelease = (
 		resetValuesImmediately: release.resetValuesImmediately,
 	});
 
-	if (release.shouldDismiss && requestDismiss) {
-		runOnJS(requestDismiss)();
-	}
-
 	if (!release.shouldDismiss && progressAlreadyAtTarget) {
 		system.targetProgress.set(release.target);
 		return;
@@ -102,7 +97,6 @@ export const finalizePinchRelease = (
 
 	animateToProgress({
 		target: release.target,
-		onAnimationFinish: release.shouldDismiss ? dismissScreen : undefined,
 		spec: release.transitionSpec,
 		emitWillAnimate: false,
 		markEntering: false,
@@ -111,4 +105,8 @@ export const finalizePinchRelease = (
 		animationProgress: system.animationProgress,
 		initialVelocity: release.initialVelocity,
 	});
+
+	if (release.shouldDismiss && requestDismiss) {
+		runOnJS(requestDismiss)();
+	}
 };

package/src/shared/providers/screen/gestures/pinch/behavior/use-pinch-behavior.ts

@@ -26,7 +26,7 @@ export const usePinchBehavior = (
 	screenOptions: ScreenOptionsContextValue,
 	gestureCompositionOwner: SharedValue<GestureCompositionOwner>,
 ): PinchBehavior => {
-	const { dismissScreen, requestDismiss } = useNavigationHelpers();
+	const { requestDismiss } = useNavigationHelpers();
 	const { withSensitivity, resetSensitivity } =
 		usePinchGestureSensitivity(screenOptions);
 
@@ -68,18 +68,12 @@ export const usePinchBehavior = (
 				.hasSnapPoints
 				? resolveSnapPinchRelease(event, latestRuntime)
 				: resolvePinchRelease(event, latestRuntime);
-			finalizePinchRelease(
-				release,
-				latestRuntime,
-				dismissScreen,
-				requestDismiss,
-			);
+			finalizePinchRelease(release, latestRuntime, requestDismiss);
 			gestureCompositionOwner.set(null);
 		},
 		[
 			runtime,
 			screenOptions,
-			dismissScreen,
 			requestDismiss,
 			withSensitivity,
 			gestureCompositionOwner,

package/src/shared/providers/screen/gestures/shared/policy.ts

@@ -306,15 +306,19 @@ const resolveGestureParticipation = ({
 	options,
 	isFirstKey,
 	gestureContext,
+	isRemovePrevented,
 }: {
 	options: GesturePolicyOptions;
 	isFirstKey: boolean;
 	gestureContext: GestureContextType | null;
+	isRemovePrevented: boolean;
 }): ScreenGestureParticipation => {
-	const canDismiss = resolveGestureCanDismiss({
-		isFirstKey,
-		gestureEnabled: options.gestureEnabled,
-	});
+	const canDismiss =
+		!isRemovePrevented &&
+		resolveGestureCanDismiss({
+			isFirstKey,
+			gestureEnabled: options.gestureEnabled,
+		});
 	const effectiveSnapPoints = validateSnapPoints({
 		snapPoints: options.snapPoints,
 		canDismiss,
@@ -333,6 +337,7 @@ const resolveGestureParticipation = ({
 
 	return {
 		isFirstKey,
+		isRemovePrevented,
 		canDismiss,
 		canTrackGesture,
 		effectiveSnapPoints,
@@ -345,15 +350,18 @@ export const resolveScreenGestureConfig = ({
 	options,
 	isFirstKey,
 	gestureContext,
+	isRemovePrevented = false,
 }: {
 	options: ScreenTransitionConfig;
 	isFirstKey: boolean;
 	gestureContext: GestureContextType | null;
+	isRemovePrevented?: boolean;
 }): ScreenGestureConfig => {
 	const participation = resolveGestureParticipation({
 		options,
 		isFirstKey,
 		gestureContext,
+		isRemovePrevented,
 	});
 	const hasSnapPoints = participation.effectiveSnapPoints.hasSnapPoints;
 
@@ -365,11 +373,14 @@ export const resolveScreenGestureConfig = ({
 };
 
 function resolveRuntimeCanDismiss(
-	participation: Pick<ScreenGestureParticipation, "isFirstKey" | "canDismiss">,
+	participation: Pick<
+		ScreenGestureParticipation,
+		"isFirstKey" | "isRemovePrevented" | "canDismiss"
+	>,
 	options: GesturePolicyOptions,
 ) {
 	"worklet";
-	if (participation.isFirstKey) {
+	if (participation.isFirstKey || participation.isRemovePrevented) {
 		return false;
 	}
 

package/src/shared/providers/screen/gestures/types.ts

@@ -85,6 +85,8 @@ export interface GestureContextType {
 export interface ScreenGestureParticipation {
 	/** Whether this route is the first route in its stack. First routes never track gestures. */
 	isFirstKey: boolean;
+	/** Whether React Navigation currently blocks removal of this route. */
+	isRemovePrevented: boolean;
 	/** Whether this route can dismiss to progress 0 from a gesture release. */
 	canDismiss: boolean;
 	/** Whether recognizers can activate to expose gesture values to interpolators. */

package/src/shared/providers/stack/blank-stack-state/blank-stack-controller.ts

@@ -5,6 +5,7 @@ import type {
 	BaseStackNavigation,
 	BaseStackRoute,
 } from "../../../types/stack.types";
+import { dispatchCloseAction } from "../../../utils/navigation/close-action-replay";
 import { buildBlankStackState } from "./helpers/build-blank-stack-state";
 import { deriveBlankStackState } from "./helpers/derive-blank-stack-state";
 import type {
@@ -86,10 +87,13 @@ export const createBlankStackController = <
 		const { state, navigation } = props;
 
 		if (state.routes.some((candidate) => candidate.key === route.key)) {
-			navigation.dispatch({
+			const action = {
 				...StackActions.pop(),
 				source: route.key,
 				target: state.key,
+			};
+			dispatchCloseAction(action, (closeAction) => {
+				navigation.dispatch(closeAction);
 			});
 			return;
 		}

package/src/shared/stores/bounds/internals/links.ts

@@ -242,7 +242,7 @@ const writeDestination = (
 
 	writePairLink(state, pairKey, linkKey, link);
 
-	if (link.group) {
+	if (link.group && !state[pairKey]?.groups?.[link.group]) {
 		writeGroup(state, pairKey, link.group, linkKey);
 	}
 };

package/src/shared/stores/system.store.ts

@@ -9,8 +9,7 @@ import { createStore } from "../utils/create-store";
 export enum LifecycleTransitionRequestKind {
 	None = 0,
 	Open = 1,
-	BlankStackClose = 2,
-	NativeClose = 3,
+	Close = 2,
 }
 
 type SystemStoreState = {