react-native-screen-transitions 3.4.0 → 3.5.0-beta.0

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

package/src/shared/providers/screen/animation/helpers/hydrate-transition-state.ts

@@ -46,10 +46,6 @@ const computeSettled = (params: {
 	return animating || dismissing || closing ? FALSE : TRUE;
 };
 
-/**
- * Computes the animated snap index based on progress and snap points.
- * Returns -1 if no snap points, otherwise interpolates between indices.
- */
 const computeSnapIndex = (progress: number, snapPoints: number[]): number => {
 	"worklet";
 	if (snapPoints.length === 0) return -1;
@@ -67,14 +63,6 @@ const computeSnapIndex = (progress: number, snapPoints: number[]): number => {
 	return snapPoints.length - 1;
 };
 
-/**
- * Determines whether the screen transition is logically settled.
- *
- * A transition is considered logically settled when:
- * - The `settled` flag is explicitly set, OR
- * - The screen is not being dragged AND the progress is within
- *   {@link ANIMATION_SNAP_THRESHOLD} of the target progress.
- */
 export const computeLogicallySettled = ({
 	progress,
 	targetProgress,
@@ -102,26 +90,25 @@ export const hydrateTransitionState = (
 ): ScreenTransitionState => {
 	"worklet";
 	const out = s.unwrapped;
-	out.progress = s.progress.value;
-	out.willAnimate = s.willAnimate.value;
-	out.closing = s.closing.value;
-	out.entering = s.entering.value;
-	out.gesture.x = s.gesture.x.value;
-	out.gesture.y = s.gesture.y.value;
-	out.gesture.normX = s.gesture.normX.value;
-	out.gesture.normY = s.gesture.normY.value;
-	out.gesture.dismissing = s.gesture.dismissing.value;
-	out.gesture.dragging = s.gesture.dragging.value;
-	out.gesture.direction = s.gesture.direction.value;
+	out.progress = s.progress.get();
+	out.willAnimate = s.willAnimate.get();
+	out.closing = s.closing.get();
+	out.entering = s.entering.get();
+	out.gesture.x = s.gesture.x.get();
+	out.gesture.y = s.gesture.y.get();
+	out.gesture.normX = s.gesture.normX.get();
+	out.gesture.normY = s.gesture.normY.get();
+	out.gesture.dismissing = s.gesture.dismissing.get();
+	out.gesture.dragging = s.gesture.dragging.get();
+	out.gesture.direction = s.gesture.direction.get();
 
 	const isGestureSettling =
 		Math.abs(out.gesture.normX) > EPSILON ||
 		Math.abs(out.gesture.normY) > EPSILON;
 
 	out.animating =
-		s.animating.value || out.gesture.dragging || isGestureSettling ? 1 : 0;
+		s.animating.get() || out.gesture.dragging || isGestureSettling ? 1 : 0;
 
-	// Deprecated aliases (kept for backwards compatibility)
 	out.gesture.normalizedX = out.gesture.normX;
 	out.gesture.normalizedY = out.gesture.normY;
 	out.gesture.isDismissing = out.gesture.dismissing;
@@ -134,24 +121,24 @@ export const hydrateTransitionState = (
 	});
 	out.logicallySettled = computeLogicallySettled({
 		progress: out.progress,
-		targetProgress: s.targetProgress.value,
+		targetProgress: s.targetProgress.get(),
 		settled: out.settled,
 		dragging: out.gesture.dragging,
 	});
 
-	if (s.settled.value !== out.settled) {
-		s.settled.value = out.settled;
+	if (s.settled.get() !== out.settled) {
+		s.settled.set(out.settled);
 	}
 
-	if (s.logicallySettled.value !== out.logicallySettled) {
-		s.logicallySettled.value = out.logicallySettled;
+	if (s.logicallySettled.get() !== out.logicallySettled) {
+		s.logicallySettled.set(out.logicallySettled);
 	}
 
 	out.meta = s.meta;
 	out.layouts.screen.width = dimensions.width;
 	out.layouts.screen.height = dimensions.height;
 
-	const content = s.measuredContentLayout.value;
+	const content = s.measuredContentLayout.get();
 	if (content) {
 		if (!out.layouts.content) {
 			out.layouts.content = {
@@ -167,8 +154,8 @@ export const hydrateTransitionState = (
 	}
 
 	const resolvedAutoSnap =
-		s.hasAutoSnapPoint && s.resolvedAutoSnapPoint.value > 0
-			? s.resolvedAutoSnapPoint.value
+		s.hasAutoSnapPoint && s.resolvedAutoSnapPoint.get() > 0
+			? s.resolvedAutoSnapPoint.get()
 			: null;
 
 	const resolvedSnapPoints =