react-native-screen-transitions 3.4.0 → 3.5.0

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

@@ -0,0 +1,160 @@
+/** biome-ignore-all lint/correctness/useHookAtTopLevel: STACK_TYPE is stable per navigator */
+import { useLayoutEffect, useMemo, useRef } from "react";
+import { useAnimatedReaction } from "react-native-reanimated";
+import useStableCallback from "../../../hooks/use-stable-callback";
+import {
+	type BaseDescriptor,
+	useDescriptorDerivations,
+} from "../../../providers/screen/descriptors";
+import { useStackCoreContext } from "../../../providers/stack/core.provider";
+import { useManagedStackContext } from "../../../providers/stack/managed.provider";
+import type { AnimationStoreMap } from "../../../stores/animation.store";
+import { GestureStore } from "../../../stores/gesture.store";
+import {
+	LifecycleTransitionRequestKind,
+	type SystemStoreActions,
+	type SystemStoreMap,
+} from "../../../stores/system.store";
+import { StackType } from "../../../types/stack.types";
+import { resetStoresForScreen } from "./helpers/reset-stores-for-screen";
+
+interface CloseHookParams {
+	current: BaseDescriptor;
+	animations: AnimationStoreMap;
+	requestLifecycleTransition: SystemStoreActions["requestLifecycleTransition"];
+	resetStores: () => void;
+}
+
+/**
+ * Managed close - reacts to closingRouteKeysShared from ManagedStackContext.
+ * Used by blank-stack and component-stack.
+ */
+const useManagedClose = ({
+	current,
+	requestLifecycleTransition,
+	resetStores,
+}: CloseHookParams) => {
+	const { handleCloseRoute, closingRouteKeysShared } = useManagedStackContext();
+	const routeKey = current.route.key;
+
+	const handleManagedCloseEnd = useStableCallback((finished: boolean) => {
+		if (!finished) return;
+		handleCloseRoute({ route: current.route });
+		requestAnimationFrame(() => {
+			resetStores();
+		});
+	});
+
+	useAnimatedReaction(
+		() => {
+			const keys = closingRouteKeysShared.value;
+			return keys?.includes(routeKey) ?? false;
+		},
+		(isClosing, wasClosing) => {
+			if (!isClosing || wasClosing) return;
+
+			requestLifecycleTransition(
+				LifecycleTransitionRequestKind.ManagedClose,
+				0,
+			);
+		},
+	);
+
+	return { handleManagedCloseEnd };
+};
+
+/**
+ * Native stack close - listens to beforeRemove navigation event.
+ */
+const useNativeStackClose = ({
+	current,
+	animations,
+	requestLifecycleTransition,
+	resetStores,
+}: CloseHookParams) => {
+	const { parentScreenKey } = useDescriptorDerivations();
+	const pendingActionRef = useRef<any>(null);
+
+	const nearestAncestorDismissing = useMemo(() => {
+		if (!parentScreenKey) return null;
+
+		return GestureStore.peekBag(parentScreenKey)?.dismissing ?? null;
+	}, [parentScreenKey]);
+
+	const handleNativeCloseEnd = useStableCallback((finished: boolean) => {
+		if (!finished || !pendingActionRef.current) {
+			pendingActionRef.current = null;
+			return;
+		}
+
+		current.navigation.dispatch(pendingActionRef.current);
+		pendingActionRef.current = null;
+		requestAnimationFrame(() => {
+			resetStores();
+		});
+	});
+
+	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 routeIndex = state.routes.findIndex(
+			(route) => route.key === routeKey,
+		);
+		const isFirstScreen = routeIndex <= 0;
+
+		if (!isEnabled || nearestAncestorDismissing?.get() || isFirstScreen) {
+			animations.closing.set(1);
+			resetStores();
+			return;
+		}
+
+		e.preventDefault();
+		pendingActionRef.current = e.data.action;
+		requestLifecycleTransition(LifecycleTransitionRequestKind.NativeClose, 0);
+	});
+
+	// 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,
+	animations: AnimationStoreMap,
+	system: SystemStoreMap,
+): {
+	handleManagedCloseEnd?: (finished: boolean) => void;
+	handleNativeCloseEnd?: (finished: boolean) => void;
+} {
+	const routeKey = current.route.key;
+	const { flags } = useStackCoreContext();
+	const { isBranchScreen, branchNavigatorKey } = useDescriptorDerivations();
+	const isNativeStack = flags.STACK_TYPE === StackType.NATIVE;
+	const { requestLifecycleTransition } = system.actions;
+
+	const resetStores = useStableCallback(() => {
+		resetStoresForScreen(routeKey, isBranchScreen, branchNavigatorKey);
+	});
+
+	const closeParams: CloseHookParams = {
+		current,
+		animations,
+		requestLifecycleTransition,
+		resetStores,
+	};
+
+	if (isNativeStack) {
+		return useNativeStackClose(closeParams);
+	}
+
+	return useManagedClose(closeParams);
+}

package/src/shared/components/screen-lifecycle/hooks/{use-open-transition.ts → use-open-transition-intent.ts}

@@ -1,10 +1,14 @@
 import { useLayoutEffect } from "react";
-import type { SharedValue } from "react-native-reanimated";
-import type { BaseDescriptor } from "../../../providers/screen/descriptors";
+import {
+	type BaseDescriptor,
+	useDescriptorDerivations,
+} from "../../../providers/screen/descriptors";
 import type { AnimationStoreMap } from "../../../stores/animation.store";
+import {
+	LifecycleTransitionRequestKind,
+	type SystemStoreMap,
+} from "../../../stores/system.store";
 import type { SnapPoint } from "../../../types/screen.types";
-import { animateToProgress } from "../../../utils/animation/animate-to-progress";
-import { useHighRefreshRate } from "./use-high-refresh-rate";
 
 /**
  * Calculates the initial progress value based on snap points configuration.
@@ -30,17 +34,15 @@ function getInitialProgress({
 }
 
 /**
- * Handles opening animation on mount.
- * Returns activate/deactivate functions for high refresh rate.
+ * Handles opening transition intent on mount.
  */
-export function useOpenTransition(
+export function useOpenTransitionIntent(
 	current: BaseDescriptor,
 	animations: AnimationStoreMap,
-	targetProgressValue: SharedValue<number>,
-	isFirstKey: boolean,
+	system: SystemStoreMap,
 ) {
-	const { activateHighRefreshRate, deactivateHighRefreshRate } =
-		useHighRefreshRate(current);
+	const { isFirstKey } = useDescriptorDerivations();
+	const { requestLifecycleTransition } = system.actions;
 
 	// biome-ignore lint/correctness/useExhaustiveDependencies: Must only run once on mount
 	useLayoutEffect(() => {
@@ -57,11 +59,11 @@ export function useOpenTransition(
 
 		if (isFirstKey && !experimental_animateOnInitialMount) {
 			if (initialProgress === "auto") {
-				targetProgressValue.set(0);
+				system.targetProgress.set(0);
 				animations.progress.set(0);
 			} else {
 				const target = initialProgress ?? 1;
-				targetProgressValue.set(target);
+				system.targetProgress.set(target);
 				animations.progress.set(target);
 			}
 			animations.animating.set(0);
@@ -76,15 +78,9 @@ export function useOpenTransition(
 			return;
 		}
 
-		activateHighRefreshRate();
-		animateToProgress({
-			target: initialProgress ?? "open",
-			spec: current.options.transitionSpec,
-			animations,
-			targetProgress: targetProgressValue,
-			onAnimationFinish: deactivateHighRefreshRate,
-		});
+		requestLifecycleTransition(
+			LifecycleTransitionRequestKind.Open,
+			initialProgress ?? 1,
+		);
 	}, []);
-
-	return { activateHighRefreshRate, deactivateHighRefreshRate };
 }

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

@@ -0,0 +1,71 @@
+import { useAnimatedReaction } from "react-native-reanimated";
+import type { BaseDescriptor } from "../../../providers/screen/descriptors";
+import type { AnimationStoreMap } from "../../../stores/animation.store";
+import {
+	LifecycleTransitionRequestKind,
+	type SystemStoreMap,
+} from "../../../stores/system.store";
+import { animateToProgress } from "../../../utils/animation/animate-to-progress";
+
+export const useTransitionStartController = ({
+	current,
+	animations,
+	system,
+	onManagedCloseFinish,
+	onNativeCloseFinish,
+}: {
+	current: BaseDescriptor;
+	animations: AnimationStoreMap;
+	system: SystemStoreMap;
+	onManagedCloseFinish?: (finished: boolean) => void;
+	onNativeCloseFinish?: (finished: boolean) => void;
+}) => {
+	const {
+		targetProgress,
+		pendingLifecycleRequestKind,
+		pendingLifecycleRequestTarget,
+		pendingLifecycleStartBlockCount,
+	} = system;
+	const { clearLifecycleTransitionRequest } = system.actions;
+	const transitionSpec = current.options.transitionSpec;
+
+	useAnimatedReaction(
+		() => {
+			"worklet";
+			return [
+				pendingLifecycleRequestKind.get(),
+				pendingLifecycleRequestTarget.get(),
+				pendingLifecycleStartBlockCount.get(),
+			] as const;
+		},
+		(next) => {
+			"worklet";
+			const [kind, target, blockCount] = next;
+
+			if (kind === LifecycleTransitionRequestKind.None) {
+				return;
+			}
+
+			if (blockCount > 0) {
+				return;
+			}
+
+			const onAnimationFinish =
+				kind === LifecycleTransitionRequestKind.ManagedClose
+					? onManagedCloseFinish
+					: kind === LifecycleTransitionRequestKind.NativeClose
+						? onNativeCloseFinish
+						: undefined;
+
+			animateToProgress({
+				target,
+				spec: transitionSpec,
+				animations,
+				targetProgress,
+				onAnimationFinish,
+			});
+
+			clearLifecycleTransitionRequest();
+		},
+	);
+};

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

@@ -1,12 +1,10 @@
-import {
-	useDescriptorDerivations,
-	useDescriptors,
-} from "../../providers/screen/descriptors";
+import { useDescriptors } from "../../providers/screen/descriptors";
 import { AnimationStore } from "../../stores/animation.store";
 import { SystemStore } from "../../stores/system.store";
-import { useCloseTransition } from "./hooks/use-close-transition";
-import { useOpenTransition } from "./hooks/use-open-transition";
-import { useScreenEvents } from "./hooks/use-screen-events";
+import { useScreenHistory } from "./hooks/history/use-screen-history";
+import { useCloseTransitionIntent } from "./hooks/use-close-transition-intent";
+import { useOpenTransitionIntent } from "./hooks/use-open-transition-intent";
+import { useTransitionStartController } from "./hooks/use-transition-start-controller";
 
 interface Props {
 	children: React.ReactNode;
@@ -18,22 +16,24 @@ interface Props {
  */
 export const ScreenLifecycle = ({ children }: Props) => {
 	const { current, previous } = useDescriptors();
-	const { isFirstKey } = useDescriptorDerivations();
+
 	const animations = AnimationStore.getBag(current.route.key);
-	const { targetProgress } = SystemStore.getBag(current.route.key);
+	const system = SystemStore.getBag(current.route.key);
+
+	const { handleManagedCloseEnd, handleNativeCloseEnd } =
+		useCloseTransitionIntent(current, animations, system);
 
-	const { activateHighRefreshRate, deactivateHighRefreshRate } =
-		useOpenTransition(current, animations, targetProgress, isFirstKey);
+	useOpenTransitionIntent(current, animations, system);
 
-	useCloseTransition(
+	useTransitionStartController({
 		current,
 		animations,
-		targetProgress,
-		activateHighRefreshRate,
-		deactivateHighRefreshRate,
-	);
+		system,
+		onManagedCloseFinish: handleManagedCloseEnd,
+		onNativeCloseFinish: handleNativeCloseEnd,
+	});
 
-	useScreenEvents(current, previous, animations);
+	useScreenHistory(current, previous, animations);
 
 	return children;
 };

package/src/shared/constants.ts

@@ -25,7 +25,6 @@ export const NAVIGATION_MASK_CONTAINER_STYLE_ID =
  * Styles
  */
 export const NO_STYLES = Object.freeze({});
-export const HIDDEN_STYLE = Object.freeze({ opacity: 0 });
 export const VISIBLE_STYLE = Object.freeze({ opacity: 1 });
 export const NO_PROPS = Object.freeze({});
 
@@ -54,6 +53,7 @@ const DEFAULT_GESTURE_VALUES = {
 export const createScreenTransitionState = (
 	route: BaseStackRoute,
 	meta?: Record<string, unknown>,
+	navigationMaskEnabled = false,
 ): ScreenTransitionState => ({
 	progress: 0,
 	closing: 0,
@@ -70,6 +70,7 @@ export const createScreenTransitionState = (
 			width: 0,
 			height: 0,
 		},
+		navigationMaskEnabled,
 	},
 	snapIndex: -1,
 });
@@ -93,6 +94,7 @@ export const DEFAULT_SCREEN_TRANSITION_STATE: ScreenTransitionState =
 				width: 0,
 				height: 0,
 			},
+			navigationMaskEnabled: false,
 		},
 		snapIndex: -1,
 	});
@@ -100,16 +102,6 @@ export const DEFAULT_SCREEN_TRANSITION_STATE: ScreenTransitionState =
 /**
  * Bounds API Defaults
  */
-export const EMPTY_BOUND_HELPER_RESULT = Object.freeze({});
-export const EMPTY_BOUND_HELPER_RESULT_RAW = Object.freeze({
-	scaleX: 1,
-	scaleY: 1,
-	scale: 1,
-	translateX: 0,
-	translateY: 0,
-	width: 0,
-	height: 0,
-});
 export const TRANSFORM_RESET = Object.freeze({
 	transform: [
 		{ translateX: 0 },

package/src/shared/providers/register-bounds.provider.tsx

@@ -18,7 +18,6 @@ import { BoundStore } from "../stores/bounds";
 import { applyMeasuredBoundsWrites } from "../stores/bounds/helpers/apply-measured-bounds-writes";
 import { prepareStyleForBounds } from "../utils/bounds/helpers/styles/styles";
 import createProvider from "../utils/create-provider";
-import { useLayoutAnchorContext } from "./layout-anchor.provider";
 import { useDescriptorDerivations, useDescriptors } from "./screen/descriptors";
 
 interface MaybeMeasureAndStoreParams {
@@ -246,7 +245,6 @@ const registerBoundsBundle = createProvider("RegisterBounds", {
 			useDescriptorDerivations();
 		const currentScreenKey = current.route.key;
 		const selectedNextRouteId = getRouteParamId(next?.route);
-		const layoutAnchor = useLayoutAnchorContext();
 
 		// Context & signals
 		const parentContext = useRegisterBoundsContext();
@@ -278,7 +276,7 @@ const registerBoundsBundle = createProvider("RegisterBounds", {
 				}
 
 				if (shouldSetSource && isAnimating.get()) {
-					const existing = BoundStore.getSnapshot(
+					const existing = BoundStore.entry.getMeasured(
 						sharedBoundTag,
 						currentScreenKey,
 					);
@@ -299,12 +297,13 @@ const registerBoundsBundle = createProvider("RegisterBounds", {
 					return;
 				}
 
-				const hasPendingLink = BoundStore.hasPendingLink(sharedBoundTag);
-				const hasSourceLink = BoundStore.hasSourceLink(
+				const hasPendingLink =
+					BoundStore.link.getPending(sharedBoundTag) !== null;
+				const hasSourceLink = BoundStore.link.hasSource(
 					sharedBoundTag,
 					currentScreenKey,
 				);
-				const hasDestinationLink = BoundStore.hasDestinationLink(
+				const hasDestinationLink = BoundStore.link.hasDestination(
 					sharedBoundTag,
 					currentScreenKey,
 				);
@@ -338,21 +337,17 @@ const registerBoundsBundle = createProvider("RegisterBounds", {
 					return;
 				}
 
-				const correctedMeasured = layoutAnchor
-					? layoutAnchor.correctMeasurement(measured)
-					: measured;
-
 				emitUpdate();
 
 				applyMeasuredBoundsWrites({
 					sharedBoundTag,
 					currentScreenKey,
-					measured: correctedMeasured,
+					measured,
 					preparedStyles,
 					ancestorKeys,
 					navigatorKey,
 					ancestorNavigatorKeys,
-					shouldRegisterSnapshot: true,
+					shouldWriteEntry: true,
 					shouldSetSource: canSetSource,
 					shouldUpdateSource: canUpdateSource,
 					shouldSetDestination: canSetDestination,

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

@@ -1,7 +1,7 @@
-import { createContext, type ReactNode, useContext, useMemo } from "react";
-import { type DerivedValue, useDerivedValue } from "react-native-reanimated";
-import type { ScreenInterpolationProps } from "../../../types/animation.types";
+import { type ReactNode, useContext } from "react";
+import createProvider from "../../../utils/create-provider";
 import { useScreenAnimationPipeline } from "./helpers/pipeline";
+import type { ScreenAnimationSource } from "./types";
 
 type Props = {
 	children: ReactNode;
@@ -10,15 +10,20 @@ type Props = {
 export type ScreenAnimationContextValue = ReturnType<
 	typeof useScreenAnimationPipeline
 > & {
-	screenAnimation: DerivedValue<ScreenInterpolationProps>;
-	ancestorScreenAnimations: DerivedValue<ScreenInterpolationProps>[];
+	ancestorScreenAnimationSources: ScreenAnimationSource[];
 };
 
-const ScreenAnimationContext =
-	createContext<ScreenAnimationContextValue | null>(null);
-ScreenAnimationContext.displayName = "ScreenAnimation";
+export type ScreenAnimationContextResult = {
+	value: ScreenAnimationContextValue;
+};
 
-function ScreenAnimationProvider({ children }: Props) {
+export const {
+	ScreenAnimationProvider,
+	ScreenAnimationContext,
+	useScreenAnimationContext,
+} = createProvider("ScreenAnimation", {
+	guarded: true,
+})<Props, ScreenAnimationContextValue>((): ScreenAnimationContextResult => {
 	const parentContext = useContext(ScreenAnimationContext);
 
 	const {
@@ -28,66 +33,23 @@ function ScreenAnimationProvider({ children }: Props) {
 		boundsAccessor,
 	} = useScreenAnimationPipeline();
 
-	const screenAnimation = useDerivedValue<ScreenInterpolationProps>(() => {
-		"worklet";
-		const props = screenInterpolatorProps.value;
-		return {
-			...props,
-			bounds: boundsAccessor,
-		};
-	});
-
-	const ancestorScreenAnimations = useMemo(() => {
-		if (!parentContext) {
-			return [];
-		}
-
-		return [
-			parentContext.screenAnimation,
-			...parentContext.ancestorScreenAnimations,
-		];
-	}, [parentContext]);
-
-	const value = useMemo(
-		() => ({
-			screenInterpolatorProps,
-			nextInterpolator,
-			currentInterpolator,
-			boundsAccessor,
-			screenAnimation,
-			ancestorScreenAnimations,
-		}),
-		[
+	const ancestorScreenAnimationSources = parentContext
+		? [
+				{
+					screenInterpolatorProps: parentContext.screenInterpolatorProps,
+					boundsAccessor: parentContext.boundsAccessor,
+				},
+				...parentContext.ancestorScreenAnimationSources,
+			]
+		: [];
+
+	return {
+		value: {
 			screenInterpolatorProps,
 			nextInterpolator,
 			currentInterpolator,
 			boundsAccessor,
-			screenAnimation,
-			ancestorScreenAnimations,
-		],
-	);
-
-	return (
-		<ScreenAnimationContext.Provider value={value}>
-			{children}
-		</ScreenAnimationContext.Provider>
-	);
-}
-
-function useScreenAnimationContext(): ScreenAnimationContextValue {
-	const context = useContext(ScreenAnimationContext);
-
-	if (!context) {
-		throw new Error(
-			"ScreenAnimation context must be used within a ScreenAnimationProvider",
-		);
-	}
-
-	return context;
-}
-
-export {
-	ScreenAnimationContext,
-	ScreenAnimationProvider,
-	useScreenAnimationContext,
-};
+			ancestorScreenAnimationSources,
+		},
+	};
+});