react-native-screen-transitions 3.4.0-alpha.7 → 3.4.0-beta.0

package/src/shared/components/create-boundary-component/hooks/use-pending-destination-measurement.ts

@@ -1,25 +1,102 @@
-import { useAnimatedReaction } from "react-native-reanimated";
+import { useLayoutEffect } from "react";
+import {
+	runOnUI,
+	type SharedValue,
+	useAnimatedReaction,
+	useSharedValue,
+} from "react-native-reanimated";
+import { AnimationStore } from "../../../stores/animation.store";
 import { BoundStore } from "../../../stores/bounds";
 import { resolvePendingSourceKey } from "../helpers/resolve-pending-source-key";
-import type { MaybeMeasureAndStoreParams } from "../types";
-import { resolvePendingDestinationCaptureSignal } from "./helpers/measurement-rules";
+import type { BoundaryId, MaybeMeasureAndStoreParams } from "../types";
+import {
+	resolvePendingDestinationCaptureSignal,
+	resolvePendingDestinationRetrySignal,
+} from "./helpers/measurement-rules";
 
 export const usePendingDestinationMeasurement = (params: {
 	sharedBoundTag: string;
 	enabled: boolean;
+	id: BoundaryId;
+	group?: string;
+	currentScreenKey: string;
 	expectedSourceScreenKey?: string;
+	animating: SharedValue<number>;
 	maybeMeasureAndStore: (options: MaybeMeasureAndStoreParams) => void;
 }) => {
 	const {
 		sharedBoundTag,
 		enabled,
+		id,
+		group,
+		currentScreenKey,
 		expectedSourceScreenKey,
+		animating,
 		maybeMeasureAndStore,
 	} = params;
 
+	const progress = AnimationStore.getValue(currentScreenKey, "progress");
+	const closing = AnimationStore.getValue(currentScreenKey, "closing");
+
+	const retryCount = useSharedValue(0);
+	const MAX_RETRIES = 4;
+	const RETRY_PROGRESS_BUCKETS = 8;
+	const RETRY_PROGRESS_MAX = 1.05;
+
+	useLayoutEffect(() => {
+		if (!enabled) return;
+
+		runOnUI(() => {
+			"worklet";
+			if (closing.get()) {
+				return;
+			}
+
+			const currentGroupActiveId = group
+				? BoundStore.getGroupActiveId(group)
+				: null;
+			if (group && currentGroupActiveId !== String(id)) {
+				return;
+			}
+
+			const resolvedSourceKey = resolvePendingSourceKey(
+				sharedBoundTag,
+				expectedSourceScreenKey,
+			);
+			const hasAttachableSourceLink = resolvedSourceKey
+				? BoundStore.hasPendingLinkFromSource(
+						sharedBoundTag,
+						resolvedSourceKey,
+					) || BoundStore.hasSourceLink(sharedBoundTag, resolvedSourceKey)
+				: false;
+
+			if (!hasAttachableSourceLink) {
+				return;
+			}
+
+			if (BoundStore.hasDestinationLink(sharedBoundTag, currentScreenKey)) {
+				return;
+			}
+
+			maybeMeasureAndStore({ intent: "complete-destination" });
+		})();
+	}, [
+		enabled,
+		id,
+		group,
+		sharedBoundTag,
+		currentScreenKey,
+		expectedSourceScreenKey,
+		closing,
+		maybeMeasureAndStore,
+	]);
+
 	useAnimatedReaction(
 		() => {
 			"worklet";
+			if (closing.get()) {
+				return 0;
+			}
 			const resolvedSourceKey = resolvePendingSourceKey(
 				sharedBoundTag,
 				expectedSourceScreenKey,
@@ -27,12 +104,16 @@ export const usePendingDestinationMeasurement = (params: {
 			return resolvePendingDestinationCaptureSignal({
 				enabled,
 				resolvedSourceKey,
-				hasPendingLinkFromSource: resolvedSourceKey
+				hasAttachableSourceLink: resolvedSourceKey
 					? BoundStore.hasPendingLinkFromSource(
 							sharedBoundTag,
 							resolvedSourceKey,
-						)
+						) || BoundStore.hasSourceLink(sharedBoundTag, resolvedSourceKey)
 					: false,
+				hasDestinationLink: BoundStore.hasDestinationLink(
+					sharedBoundTag,
+					currentScreenKey,
+				),
 			});
 		},
 		(captureSignal, previousCaptureSignal) => {
@@ -41,9 +122,87 @@ export const usePendingDestinationMeasurement = (params: {
 			if (!captureSignal || captureSignal === previousCaptureSignal) {
 				return;
 			}
+			const currentGroupActiveId = group
+				? BoundStore.getGroupActiveId(group)
+				: null;
+			if (group && currentGroupActiveId !== String(id)) {
+				return;
+			}
+
+			maybeMeasureAndStore({ intent: "complete-destination" });
+		},
+		[
+			enabled,
+			id,
+			group,
+			sharedBoundTag,
+			expectedSourceScreenKey,
+			closing,
+			maybeMeasureAndStore,
+		],
+	);
+
+	useAnimatedReaction(
+		() => {
+			"worklet";
+			if (closing.get()) {
+				return 0;
+			}
+			const resolvedSourceKey = resolvePendingSourceKey(
+				sharedBoundTag,
+				expectedSourceScreenKey,
+			);
+			return resolvePendingDestinationRetrySignal({
+				enabled,
+				retryCount: retryCount.get(),
+				maxRetries: MAX_RETRIES,
+				isAnimating: !!animating.get(),
+				hasDestinationLink: BoundStore.hasDestinationLink(
+					sharedBoundTag,
+					currentScreenKey,
+				),
+				progress: progress.get(),
+				retryProgressMax: RETRY_PROGRESS_MAX,
+				retryProgressBuckets: RETRY_PROGRESS_BUCKETS,
+				resolvedSourceKey,
+				hasAttachableSourceLink: resolvedSourceKey
+					? BoundStore.hasPendingLinkFromSource(
+							sharedBoundTag,
+							resolvedSourceKey,
+						) || BoundStore.hasSourceLink(sharedBoundTag, resolvedSourceKey)
+					: false,
+			});
+		},
+		(captureSignal) => {
+			"worklet";
+			if (!enabled) return;
+			if (!captureSignal) {
+				retryCount.set(0);
+				return;
+			}
+			const currentGroupActiveId = group
+				? BoundStore.getGroupActiveId(group)
+				: null;
+			if (group && currentGroupActiveId !== String(id)) {
+				return;
+			}
 
+			if (retryCount.get() >= MAX_RETRIES) return;
+			retryCount.set(retryCount.get() + 1);
 			maybeMeasureAndStore({ intent: "complete-destination" });
 		},
-		[enabled, sharedBoundTag, expectedSourceScreenKey, maybeMeasureAndStore],
+		[
+			enabled,
+			id,
+			group,
+			sharedBoundTag,
+			currentScreenKey,
+			expectedSourceScreenKey,
+			progress,
+			animating,
+			closing,
+			maybeMeasureAndStore,
+			retryCount,
+		],
 	);
 };

package/src/shared/components/create-boundary-component/hooks/use-prepare-transition-measurement.ts

@@ -0,0 +1,107 @@
+import { useAnimatedReaction } from "react-native-reanimated";
+import { AnimationStore } from "../../../stores/animation.store";
+import { BoundStore } from "../../../stores/bounds";
+import { GestureStore } from "../../../stores/gesture.store";
+import type { BoundaryId, MaybeMeasureAndStoreParams } from "../types";
+import {
+	PREPARE_DESTINATION_MEASUREMENT_INTENT,
+	resolvePrepareSourceMeasurementIntent,
+} from "./helpers/measurement-rules";
+
+export const usePrepareTransitionMeasurement = (params: {
+	enabled: boolean;
+	sharedBoundTag: string;
+	id: BoundaryId;
+	group?: string;
+	currentScreenKey: string;
+	nextScreenKey?: string;
+	hasNextScreen: boolean;
+	maybeMeasureAndStore: (options: MaybeMeasureAndStoreParams) => void;
+}) => {
+	const {
+		enabled,
+		sharedBoundTag,
+		id,
+		group,
+		currentScreenKey,
+		nextScreenKey,
+		hasNextScreen,
+		maybeMeasureAndStore,
+	} = params;
+
+	const currentWillAnimate = AnimationStore.getValue(
+		currentScreenKey,
+		"willAnimate",
+	);
+	const currentAnimating = AnimationStore.getValue(
+		currentScreenKey,
+		"animating",
+	);
+	const currentDragging = GestureStore.getValue(currentScreenKey, "dragging");
+	const nextWillAnimate = nextScreenKey
+		? AnimationStore.getValue(nextScreenKey, "willAnimate")
+		: null;
+	const nextAnimating = nextScreenKey
+		? AnimationStore.getValue(nextScreenKey, "animating")
+		: null;
+	const nextDragging = nextScreenKey
+		? GestureStore.getValue(nextScreenKey, "dragging")
+		: null;
+
+	useAnimatedReaction(
+		() => (hasNextScreen ? (nextWillAnimate?.get() ?? 0) : 0),
+		(nextValue, previousValue) => {
+			"worklet";
+			if (!enabled || !hasNextScreen) return;
+			if (nextValue === 0 || nextValue === previousValue) return;
+
+			const currentGroupActiveId = group
+				? BoundStore.getGroupActiveId(group)
+				: null;
+
+			if (group && currentGroupActiveId !== String(id)) {
+				return;
+			}
+
+			const shouldCancelMeasurement =
+				!!nextAnimating?.get() && !!nextDragging?.get();
+			if (shouldCancelMeasurement) {
+				return;
+			}
+
+			const intent = resolvePrepareSourceMeasurementIntent({
+				hasSourceLink: BoundStore.hasSourceLink(
+					sharedBoundTag,
+					currentScreenKey,
+				),
+			});
+
+			if (!intent) {
+				return;
+			}
+
+			maybeMeasureAndStore({ intent });
+		},
+	);
+
+	useAnimatedReaction(
+		() => (!hasNextScreen ? currentWillAnimate.get() : 0),
+		(nextValue, previousValue) => {
+			"worklet";
+			if (!enabled || hasNextScreen) return;
+			if (nextValue === 0 || nextValue === previousValue) return;
+			const currentGroupActiveId = group
+				? BoundStore.getGroupActiveId(group)
+				: null;
+			if (group && currentGroupActiveId !== String(id)) return;
+
+			const shouldCancelMeasurement =
+				!!currentAnimating.get() && !!currentDragging.get();
+			if (shouldCancelMeasurement) return;
+
+			maybeMeasureAndStore({
+				intent: PREPARE_DESTINATION_MEASUREMENT_INTENT,
+			});
+		},
+	);
+};

package/src/shared/components/create-boundary-component/index.tsx

@@ -1,5 +1,4 @@
-import { View } from "react-native";
-import { Pressable } from "react-native-gesture-handler";
+import { Pressable, View } from "react-native";
 import { BoundaryTarget } from "./components/boundary-target";
 import { createBoundaryComponent } from "./create-boundary-component";
 
@@ -30,10 +29,16 @@ BoundaryTarget.displayName = "Transition.Boundary.Target";
  * - `Boundary.Target` to measure a nested descendant instead of the owner.
  */
 export const Boundary = {
-	/** Passive boundary wrapper (no built-in press semantics). */
+	/**
+	 * Passive boundary wrapper (no built-in press semantics).
+	 */
 	View: BoundaryView,
-	/** Pressable boundary wrapper with press-priority source capture. */
+	/**
+	 * Pressable boundary wrapper with press-priority source capture.
+	 */
 	Trigger: BoundaryTrigger,
-	/** Optional nested measurement override inside a boundary owner. */
+	/**
+	 * Optional nested measurement override inside a boundary owner.
+	 */
 	Target: BoundaryTarget,
 };

package/src/shared/components/create-boundary-component/types.ts

@@ -43,8 +43,7 @@ export type MeasurementIntent =
 	| "capture-source"
 	| "complete-destination"
 	| "refresh-source"
-	| "refresh-destination"
-	| "snapshot-only";
+	| "refresh-destination";
 
 export interface MaybeMeasureAndStoreParams {
 	intent?: MeasurementIntent | readonly MeasurementIntent[];

package/src/shared/components/create-transition-aware-component.tsx

@@ -1,6 +1,6 @@
 /** biome-ignore-all lint/style/noNonNullAssertion: <This helper is usually being used inside a transitionable stack> */
 import type React from "react";
-import { type ComponentType, forwardRef, memo, useCallback } from "react";
+import { type ComponentType, forwardRef, memo } from "react";
 import type { View } from "react-native";
 import { GestureDetector } from "react-native-gesture-handler";
 import Animated, {
@@ -9,13 +9,11 @@ import Animated, {
 	useAnimatedRef,
 	useAnimatedStyle,
 	useComposedEventHandler,
-	useSharedValue,
 } from "react-native-reanimated";
 import { NO_PROPS, NO_STYLES } from "../constants";
 import { useScrollRegistry } from "../hooks/gestures/use-scroll-registry";
 import { RegisterBoundsProvider } from "../providers/register-bounds.provider";
 import { useScreenStyles } from "../providers/screen/styles";
-import { ScrollSettleProvider } from "../providers/scroll-settle.provider";
 import type { TransitionAwareProps } from "../types/screen.types";
 
 interface CreateTransitionAwareComponentOptions {
@@ -45,15 +43,6 @@ export function createTransitionAwareComponent<P extends object>(
 			...scrollableProps
 		} = props;
 
-		const settledSignal = useSharedValue(0);
-
-		const emitScrollSettled = useCallback(() => {
-			runOnUI(() => {
-				"worklet";
-				settledSignal.value = settledSignal.value + 1;
-			})();
-		}, [settledSignal]);
-
 		// Determine scroll direction from the horizontal prop (standard ScrollView API)
 		const scrollDirection = scrollableProps.horizontal
 			? "horizontal"
@@ -72,54 +61,28 @@ export function createTransitionAwareComponent<P extends object>(
 			userOnScroll ?? null,
 		]);
 
-		const handleMomentumScrollEnd = useCallback(
-			(event: unknown) => {
-				userOnMomentumScrollEnd?.(event);
-				emitScrollSettled();
-			},
-			[userOnMomentumScrollEnd, emitScrollSettled],
-		);
-
-		const handleScrollEndDrag = useCallback(
-			(event: any) => {
-				userOnScrollEndDrag?.(event);
-
-				const velocityX = Math.abs(event?.nativeEvent?.velocity?.x ?? 0);
-				const velocityY = Math.abs(event?.nativeEvent?.velocity?.y ?? 0);
-
-				// If there is no momentum, onMomentumScrollEnd may not fire.
-				// Emit settled signal here only when velocity is effectively zero.
-				if (velocityX < 0.01 && velocityY < 0.01) {
-					emitScrollSettled();
-				}
-			},
-			[userOnScrollEndDrag, emitScrollSettled],
-		);
-
 		const scrollableComponent = (
 			<AnimatedComponent
 				{...(scrollableProps as any)}
 				ref={ref}
 				onScroll={composedScrollHandler}
-				onMomentumScrollEnd={handleMomentumScrollEnd}
-				onScrollEndDrag={handleScrollEndDrag}
+				onMomentumScrollEnd={userOnMomentumScrollEnd}
+				onScrollEndDrag={userOnScrollEndDrag}
 				onContentSizeChange={onContentSizeChange}
 				onLayout={onLayout}
 				scrollEventThrottle={scrollableProps.scrollEventThrottle || 16}
 			/>
 		);
 
+		if (!nativeGesture) {
+			return scrollableComponent;
+		}
+
 		// If no gesture owner found for this axis, render without GestureDetector
 		return (
-			<ScrollSettleProvider settledSignal={settledSignal}>
-				{!nativeGesture ? (
-					scrollableComponent
-				) : (
-					<GestureDetector gesture={nativeGesture}>
-						{scrollableComponent}
-					</GestureDetector>
-				)}
-			</ScrollSettleProvider>
+			<GestureDetector gesture={nativeGesture}>
+				{scrollableComponent}
+			</GestureDetector>
 		);
 	});
 

package/src/shared/components/screen-container/hooks/use-content-layout.ts

@@ -15,15 +15,8 @@ export function useContentLayout() {
 	const { height: screenHeight } = useWindowDimensions();
 	const routeKey = current.route.key;
 	const animations = AnimationStore.getBag(routeKey);
-	const targetProgressValue = SystemStore.getValue(routeKey, "targetProgress");
-	const resolvedAutoSnapPointValue = SystemStore.getValue(
-		routeKey,
-		"resolvedAutoSnapPoint",
-	);
-	const measuredContentLayoutValue = SystemStore.getValue(
-		routeKey,
-		"measuredContentLayout",
-	);
+	const { targetProgress, resolvedAutoSnapPoint, measuredContentLayout } =
+		SystemStore.getBag(routeKey);
 	const experimental_animateOnInitialMount =
 		current.options.experimental_animateOnInitialMount;
 	const transitionSpec = current.options.transitionSpec;
@@ -37,13 +30,13 @@ export function useContentLayout() {
 
 			runOnUI((nextWidth: number, nextHeight: number, nextFraction: number) => {
 				"worklet";
-				measuredContentLayoutValue.value = {
+				measuredContentLayout.value = {
 					width: nextWidth,
 					height: nextHeight,
 				};
 
-				const isFirstMeasurement = resolvedAutoSnapPointValue.value <= 0;
-				resolvedAutoSnapPointValue.value = nextFraction;
+				const isFirstMeasurement = resolvedAutoSnapPoint.value <= 0;
+				resolvedAutoSnapPoint.value = nextFraction;
 
 				if (
 					!isFirstMeasurement ||
@@ -54,7 +47,7 @@ export function useContentLayout() {
 				}
 
 				if (isFirstKey && !experimental_animateOnInitialMount) {
-					targetProgressValue.value = nextFraction;
+					targetProgress.value = nextFraction;
 					animations.progress.value = nextFraction;
 					return;
 				}
@@ -63,15 +56,15 @@ export function useContentLayout() {
 					target: nextFraction,
 					spec: transitionSpec,
 					animations,
-					targetProgress: targetProgressValue,
+					targetProgress,
 				});
 			})(width, height, fraction);
 		},
 		[
 			animations,
-			targetProgressValue,
-			resolvedAutoSnapPointValue,
-			measuredContentLayoutValue,
+			targetProgress,
+			resolvedAutoSnapPoint,
+			measuredContentLayout,
 			isFirstKey,
 			screenHeight,
 			experimental_animateOnInitialMount,

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

@@ -31,11 +31,8 @@ export const BackdropLayer = memo(function BackdropLayer({
 	const BackdropComponent = current.options.backdropComponent;
 	const routeKey = current.route.key;
 	const animations = AnimationStore.getBag(routeKey);
-	const targetProgressValue = SystemStore.getValue(routeKey, "targetProgress");
-	const resolvedAutoSnapPointValue = SystemStore.getValue(
-		routeKey,
-		"resolvedAutoSnapPoint",
-	);
+	const { targetProgress, resolvedAutoSnapPoint } =
+		SystemStore.getBag(routeKey);
 
 	const AnimatedBackdropComponent = useMemo(
 		() =>
@@ -68,7 +65,7 @@ export const BackdropLayer = memo(function BackdropLayer({
 				"worklet";
 				const resolvedSnaps = rawSnapPoints
 					.map((point) =>
-						point === "auto" ? resolvedAutoSnapPointValue.value : point,
+						point === "auto" ? resolvedAutoSnapPoint.value : point,
 					)
 					.filter((point): point is number => typeof point === "number");
 
@@ -94,15 +91,15 @@ export const BackdropLayer = memo(function BackdropLayer({
 					target,
 					spec,
 					animations,
-					targetProgress: targetProgressValue,
+					targetProgress,
 					onAnimationFinish: shouldDismiss ? dismissScreen : undefined,
 				});
 			})();
 		}
 	}, [
 		animations,
-		targetProgressValue,
-		resolvedAutoSnapPointValue,
+		targetProgress,
+		resolvedAutoSnapPoint,
 		backdropBehavior,
 		current,
 		dismissScreen,

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

@@ -20,10 +20,7 @@ export const ScreenLifecycle = ({ children }: Props) => {
 	const { current, previous } = useDescriptors();
 	const { isFirstKey } = useDescriptorDerivations();
 	const animations = AnimationStore.getBag(current.route.key);
-	const targetProgress = SystemStore.getValue(
-		current.route.key,
-		"targetProgress",
-	);
+	const { targetProgress } = SystemStore.getBag(current.route.key);
 
 	const { activateHighRefreshRate, deactivateHighRefreshRate } =
 		useOpenTransition(current, animations, targetProgress, isFirstKey);

package/src/shared/constants.ts

@@ -56,6 +56,7 @@ export const createScreenTransitionState = (
 	progress: 0,
 	closing: 0,
 	animating: 0,
+	willAnimate: 0,
 	settled: 1,
 	logicallySettled: 1,
 	entering: 0,
@@ -79,6 +80,7 @@ export const DEFAULT_SCREEN_TRANSITION_STATE: ScreenTransitionState =
 		progress: 0,
 		closing: 0,
 		animating: 0,
+		willAnimate: 0,
 		settled: 1,
 		logicallySettled: 1,
 		entering: 0,
@@ -107,6 +109,15 @@ export const EMPTY_BOUND_HELPER_RESULT_RAW = Object.freeze({
 	height: 0,
 	...HIDDEN_STYLE,
 });
+export const TRANSFORM_RESET = Object.freeze({
+	transform: [
+		{ translateX: 0 },
+		{ translateY: 0 },
+		{ scale: 1 },
+		{ scaleX: 1 },
+		{ scaleY: 1 },
+	],
+});
 export const ENTER_RANGE = [0, 1] as const;
 export const EXIT_RANGE = [1, 2] as const;
 

package/src/shared/hooks/reanimated/use-animated-debounce.ts

@@ -0,0 +1,56 @@
+import {
+	cancelAnimation,
+	useAnimatedReaction,
+	useSharedValue,
+	withDelay,
+	withTiming,
+} from "react-native-reanimated";
+
+const SCROLL_SETTLE_DELAY_MS = 25;
+
+interface AnimatedDebounceControls {
+	trigger: () => void;
+	cancel: () => void;
+}
+
+/**
+ * Debounces a UI-thread callback using Reanimated timing primitives.
+ *
+ * Call `trigger()` from a worklet to reset the debounce window. When no new
+ * trigger arrives within `delayMs`, `onDebounced` fires once on the UI thread.
+ */
+export function useAnimatedDebounce(
+	onDebounced: () => void,
+	delayMs: number = SCROLL_SETTLE_DELAY_MS,
+): AnimatedDebounceControls {
+	const token = useSharedValue(0);
+
+	const trigger = () => {
+		"worklet";
+		cancelAnimation(token);
+		token.value = withDelay(
+			delayMs,
+			withTiming(token.value + 1, { duration: 0 }),
+		);
+	};
+
+	const cancel = () => {
+		"worklet";
+		cancelAnimation(token);
+	};
+
+	useAnimatedReaction(
+		() => token.value,
+		(nextToken, previousToken) => {
+			"worklet";
+			if (nextToken === 0 || nextToken === previousToken) {
+				return;
+			}
+
+			onDebounced();
+		},
+		[delayMs, onDebounced],
+	);
+
+	return { trigger, cancel };
+}

package/src/shared/index.ts

@@ -28,6 +28,7 @@ export { snapTo } from "./animation/snap-to";
 export {
 	NAVIGATION_MASK_CONTAINER_STYLE_ID,
 	NAVIGATION_MASK_ELEMENT_STYLE_ID,
+	TRANSFORM_RESET,
 } from "./constants";
 export {
 	type ScreenGestureTarget,