react-native-screen-transitions 3.3.0 → 3.4.0-alpha.1

package/src/shared/components/create-boundary-component/hooks/use-auto-source-measurement.ts

@@ -0,0 +1,50 @@
+import { useAnimatedReaction } from "react-native-reanimated";
+import { BoundStore } from "../../../stores/bounds";
+import type { MaybeMeasureAndStoreParams } from "../types";
+
+export const useAutoSourceMeasurement = (params: {
+	enabled: boolean;
+	sharedBoundTag: string;
+	nextScreenKey?: string;
+	maybeMeasureAndStore: (options: MaybeMeasureAndStoreParams) => void;
+}) => {
+	const { enabled, sharedBoundTag, nextScreenKey, maybeMeasureAndStore } =
+		params;
+	const boundaryPresence = BoundStore.getBoundaryPresence();
+
+	useAnimatedReaction(
+		() => {
+			"worklet";
+			if (!enabled) return 0;
+			if (!nextScreenKey) return 0;
+			const tagPresence = boundaryPresence.value[sharedBoundTag];
+			if (!tagPresence) return 0;
+
+			const direct = tagPresence[nextScreenKey];
+			if (direct && direct.count > 0) return nextScreenKey;
+
+			for (const screenKey in tagPresence) {
+				const entry = tagPresence[screenKey];
+				if (entry.ancestorKeys?.includes(nextScreenKey)) {
+					return nextScreenKey;
+				}
+			}
+
+			return 0;
+		},
+		(captureSignal, previousCaptureSignal) => {
+			"worklet";
+			if (!enabled) return;
+			if (!nextScreenKey) return;
+			if (!captureSignal || captureSignal === previousCaptureSignal) return;
+			maybeMeasureAndStore({ shouldSetSource: true });
+		},
+		[
+			enabled,
+			nextScreenKey,
+			sharedBoundTag,
+			boundaryPresence,
+			maybeMeasureAndStore,
+		],
+	);
+};

package/src/shared/components/create-boundary-component/hooks/use-boundary-measure-and-store.ts

@@ -0,0 +1,177 @@
+import type { View } from "react-native";
+import {
+	type AnimatedRef,
+	type MeasuredDimensions,
+	measure,
+	type StyleProps,
+} from "react-native-reanimated";
+import useStableCallbackValue from "../../../hooks/use-stable-callback-value";
+import type { AnimationStore } from "../../../stores/animation.store";
+import { BoundStore } from "../../../stores/bounds";
+import { applyMeasuredBoundsWrites } from "../../../stores/bounds/helpers/apply-measured-bounds-writes";
+import { resolvePendingSourceKey } from "../helpers/resolve-pending-source-key";
+import type { MaybeMeasureAndStoreParams } from "../types";
+
+type LayoutAnchor = {
+	correctMeasurement: (measured: MeasuredDimensions) => MeasuredDimensions;
+	isMeasurementInViewport?: (measured: MeasuredDimensions) => boolean;
+} | null;
+
+const SNAPSHOT_EPSILON = 0.5;
+
+const areMeasurementsEqual = (
+	a: MeasuredDimensions,
+	b: MeasuredDimensions,
+): boolean => {
+	"worklet";
+
+	return (
+		Math.abs(a.x - b.x) <= SNAPSHOT_EPSILON &&
+		Math.abs(a.y - b.y) <= SNAPSHOT_EPSILON &&
+		Math.abs(a.pageX - b.pageX) <= SNAPSHOT_EPSILON &&
+		Math.abs(a.pageY - b.pageY) <= SNAPSHOT_EPSILON &&
+		Math.abs(a.width - b.width) <= SNAPSHOT_EPSILON &&
+		Math.abs(a.height - b.height) <= SNAPSHOT_EPSILON
+	);
+};
+
+export const useBoundaryMeasureAndStore = (params: {
+	enabled: boolean;
+	sharedBoundTag: string;
+	preferredSourceScreenKey?: string;
+	currentScreenKey: string;
+	ancestorKeys: string[];
+	navigatorKey?: string;
+	ancestorNavigatorKeys?: string[];
+	isAnimating: ReturnType<typeof AnimationStore.getRouteAnimation>;
+	preparedStyles: StyleProps;
+	animatedRef: AnimatedRef<View>;
+	layoutAnchor: LayoutAnchor;
+}) => {
+	const {
+		enabled,
+		sharedBoundTag,
+		preferredSourceScreenKey,
+		currentScreenKey,
+		ancestorKeys,
+		navigatorKey,
+		ancestorNavigatorKeys,
+		isAnimating,
+		preparedStyles,
+		animatedRef,
+		layoutAnchor,
+	} = params;
+
+	return useStableCallbackValue(
+		({
+			shouldSetSource,
+			shouldSetDestination,
+			shouldUpdateSource,
+			shouldUpdateDestination,
+		}: MaybeMeasureAndStoreParams = {}) => {
+			"worklet";
+			if (!enabled) return;
+
+			const expectedSourceScreenKey: string | undefined =
+				resolvePendingSourceKey(sharedBoundTag, preferredSourceScreenKey) ||
+				undefined;
+
+			if (shouldSetSource && isAnimating.get()) {
+				const existing = BoundStore.getSnapshot(
+					sharedBoundTag,
+					currentScreenKey,
+				);
+				if (existing) {
+					applyMeasuredBoundsWrites({
+						sharedBoundTag,
+						ancestorKeys,
+						navigatorKey,
+						ancestorNavigatorKeys,
+						currentScreenKey,
+						measured: existing.bounds,
+						preparedStyles,
+						shouldSetSource: true,
+					});
+					return;
+				}
+
+				// No cached snapshot while animating.
+				// Fall through to a live measurement so rapid retargeting still
+				// captures a valid source link.
+			}
+
+			const hasPendingLink = expectedSourceScreenKey
+				? BoundStore.hasPendingLinkFromSource(
+						sharedBoundTag,
+						expectedSourceScreenKey,
+					)
+				: BoundStore.hasPendingLink(sharedBoundTag);
+			const hasSourceLink = BoundStore.hasSourceLink(
+				sharedBoundTag,
+				currentScreenKey,
+			);
+			const hasDestinationLink = BoundStore.hasDestinationLink(
+				sharedBoundTag,
+				currentScreenKey,
+			);
+
+			const canSetSource = !!shouldSetSource;
+			const canSetDestination = !!shouldSetDestination && hasPendingLink;
+			const canUpdateSource = !!shouldUpdateSource && hasSourceLink;
+			const canUpdateDestination =
+				!!shouldUpdateDestination && (hasDestinationLink || hasPendingLink);
+
+			if (
+				!canSetSource &&
+				!canSetDestination &&
+				!canUpdateSource &&
+				!canUpdateDestination
+			) {
+				return;
+			}
+
+			const measured = measure(animatedRef);
+			if (!measured) return;
+
+			const correctedMeasured = layoutAnchor
+				? layoutAnchor.correctMeasurement(measured)
+				: measured;
+
+			const wantsDestinationWrite = canSetDestination || canUpdateDestination;
+			const destinationInViewport =
+				!wantsDestinationWrite ||
+				!layoutAnchor ||
+				!layoutAnchor.isMeasurementInViewport ||
+				layoutAnchor.isMeasurementInViewport(correctedMeasured);
+
+			if (!destinationInViewport && !canSetSource && !canUpdateSource) {
+				return;
+			}
+
+			const existingSnapshot = BoundStore.getSnapshot(
+				sharedBoundTag,
+				currentScreenKey,
+			);
+			const hasSnapshotChanged =
+				!existingSnapshot ||
+				!areMeasurementsEqual(existingSnapshot.bounds, correctedMeasured);
+
+			applyMeasuredBoundsWrites({
+				sharedBoundTag,
+				currentScreenKey,
+				measured: correctedMeasured,
+				preparedStyles,
+				ancestorKeys,
+				navigatorKey,
+				ancestorNavigatorKeys,
+				expectedSourceScreenKey,
+				shouldRegisterSnapshot: hasSnapshotChanged,
+				shouldSetSource: canSetSource,
+				shouldUpdateSource: canUpdateSource && hasSnapshotChanged,
+				shouldUpdateDestination:
+					canUpdateDestination && destinationInViewport && hasSnapshotChanged,
+				shouldSetDestination: canSetDestination && destinationInViewport,
+			});
+		},
+	);
+};

package/src/shared/components/create-boundary-component/hooks/use-boundary-presence.ts

@@ -0,0 +1,55 @@
+import { useLayoutEffect } from "react";
+import { runOnUI } from "react-native-reanimated";
+import { BoundStore } from "../../../stores/bounds";
+import type { BoundaryConfigProps } from "../types";
+
+export const useBoundaryPresence = (params: {
+	enabled: boolean;
+	sharedBoundTag: string;
+	currentScreenKey: string;
+	ancestorKeys: string[];
+	navigatorKey?: string;
+	ancestorNavigatorKeys?: string[];
+	boundaryConfig?: BoundaryConfigProps;
+}) => {
+	const {
+		enabled,
+		sharedBoundTag,
+		currentScreenKey,
+		ancestorKeys,
+		navigatorKey,
+		ancestorNavigatorKeys,
+		boundaryConfig,
+	} = params;
+	const ancestorKeysSignature = ancestorKeys.join("|");
+	const ancestorNavigatorKeysSignature = ancestorNavigatorKeys?.join("|");
+
+	// biome-ignore lint/correctness/useExhaustiveDependencies: <Depend on the ancestory keys signature>
+	useLayoutEffect(() => {
+		if (!enabled) return;
+
+		runOnUI(BoundStore.registerBoundaryPresence)(
+			sharedBoundTag,
+			currentScreenKey,
+			ancestorKeys,
+			boundaryConfig,
+			navigatorKey,
+			ancestorNavigatorKeys,
+		);
+
+		return () => {
+			runOnUI(BoundStore.unregisterBoundaryPresence)(
+				sharedBoundTag,
+				currentScreenKey,
+			);
+		};
+	}, [
+		enabled,
+		sharedBoundTag,
+		currentScreenKey,
+		ancestorKeysSignature,
+		navigatorKey,
+		ancestorNavigatorKeysSignature,
+		boundaryConfig,
+	]);
+};

package/src/shared/components/create-boundary-component/hooks/use-group-active-measurement.ts

@@ -0,0 +1,59 @@
+import { useAnimatedReaction } from "react-native-reanimated";
+import type { AnimationStore } from "../../../stores/animation.store";
+import { BoundStore } from "../../../stores/bounds";
+import type { BoundaryId, MaybeMeasureAndStoreParams } from "../types";
+
+/**
+ * Watches the group's active id in the BoundStore.
+ * When this boundary becomes the active member of its group,
+ * re-measures itself and updates the link destination with fresh bounds.
+ * This handles the case where a boundary scrolled into view after initial mount
+ * (e.g., paging ScrollView in a detail screen).
+ */
+export const useGroupActiveMeasurement = (params: {
+	enabled: boolean;
+	group: string | undefined;
+	id: BoundaryId;
+	shouldUpdateDestination: boolean;
+	isAnimating: ReturnType<typeof AnimationStore.getRouteAnimation>;
+	maybeMeasureAndStore: (options: MaybeMeasureAndStoreParams) => void;
+}) => {
+	const {
+		enabled,
+		group,
+		id,
+		shouldUpdateDestination,
+		isAnimating,
+		maybeMeasureAndStore,
+	} = params;
+	const idStr = String(id);
+
+	const allGroups = BoundStore.getGroups();
+
+	useAnimatedReaction(
+		() => {
+			"worklet";
+			if (!enabled) return null;
+			if (!group) return null;
+			return allGroups.value[group]?.activeId ?? null;
+		},
+		(activeId, previousActiveId) => {
+			"worklet";
+			if (!enabled) return;
+			if (!group || !shouldUpdateDestination) return;
+			if (isAnimating.value) return;
+
+			if (activeId === idStr && activeId !== previousActiveId) {
+				maybeMeasureAndStore({ shouldUpdateDestination: true });
+			}
+		},
+		[
+			enabled,
+			group,
+			idStr,
+			shouldUpdateDestination,
+			isAnimating,
+			maybeMeasureAndStore,
+		],
+	);
+};

package/src/shared/components/create-boundary-component/hooks/use-initial-layout-handler.ts

@@ -0,0 +1,83 @@
+import { useCallback, useLayoutEffect } from "react";
+import { runOnUI, 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";
+
+export const useInitialLayoutHandler = (params: {
+	enabled: boolean;
+	sharedBoundTag: string;
+	currentScreenKey: string;
+	ancestorKeys: string[];
+	expectedSourceScreenKey?: string;
+	maybeMeasureAndStore: (options: MaybeMeasureAndStoreParams) => void;
+}) => {
+	const {
+		enabled,
+		sharedBoundTag,
+		currentScreenKey,
+		ancestorKeys,
+		expectedSourceScreenKey,
+		maybeMeasureAndStore,
+	} = params;
+
+	const isAnimating = AnimationStore.getRouteAnimation(
+		currentScreenKey,
+		"animating",
+	);
+
+	const ancestorAnimations = ancestorKeys.map((key) =>
+		AnimationStore.getRouteAnimation(key, "animating"),
+	);
+
+	const hasMeasuredOnLayout = useSharedValue(false);
+
+	const handleInitialLayout = useCallback(() => {
+		"worklet";
+		if (!enabled) return;
+		if (!sharedBoundTag || hasMeasuredOnLayout.get()) return;
+
+		let isAnyAnimating = isAnimating.get();
+		for (let i = 0; i < ancestorAnimations.length; i++) {
+			if (ancestorAnimations[i].get()) {
+				isAnyAnimating = 1;
+				break;
+			}
+		}
+
+		if (!isAnyAnimating) return;
+		const resolvedSourceKey = resolvePendingSourceKey(
+			sharedBoundTag,
+			expectedSourceScreenKey,
+		);
+		if (!resolvedSourceKey) return;
+		if (
+			!BoundStore.hasPendingLinkFromSource(sharedBoundTag, resolvedSourceKey)
+		) {
+			return;
+		}
+
+		maybeMeasureAndStore({
+			shouldSetSource: false,
+			shouldSetDestination: true,
+		});
+
+		hasMeasuredOnLayout.set(true);
+	}, [
+		enabled,
+		sharedBoundTag,
+		hasMeasuredOnLayout,
+		isAnimating,
+		ancestorAnimations,
+		maybeMeasureAndStore,
+		expectedSourceScreenKey,
+	]);
+
+	// Try to capture destination bounds during layout phase as soon as the
+	// boundary mounts; guards in handleInitialLayout keep this idempotent.
+	useLayoutEffect(() => {
+		if (!enabled) return;
+		runOnUI(handleInitialLayout)();
+	}, [enabled, handleInitialLayout]);
+};

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

@@ -0,0 +1,47 @@
+import { useAnimatedReaction } from "react-native-reanimated";
+import { BoundStore } from "../../../stores/bounds";
+import { resolvePendingSourceKey } from "../helpers/resolve-pending-source-key";
+import type { MaybeMeasureAndStoreParams } from "../types";
+
+export const usePendingDestinationMeasurement = (params: {
+	sharedBoundTag: string;
+	enabled: boolean;
+	expectedSourceScreenKey?: string;
+	maybeMeasureAndStore: (options: MaybeMeasureAndStoreParams) => void;
+}) => {
+	const {
+		sharedBoundTag,
+		enabled,
+		expectedSourceScreenKey,
+		maybeMeasureAndStore,
+	} = params;
+
+	useAnimatedReaction(
+		() => {
+			"worklet";
+			if (!enabled) return 0;
+			const resolvedSourceKey = resolvePendingSourceKey(
+				sharedBoundTag,
+				expectedSourceScreenKey,
+			);
+			if (!resolvedSourceKey) return 0;
+
+			return BoundStore.hasPendingLinkFromSource(
+				sharedBoundTag,
+				resolvedSourceKey,
+			)
+				? resolvedSourceKey
+				: 0;
+		},
+		(captureSignal, previousCaptureSignal) => {
+			"worklet";
+			if (!enabled) return;
+			if (!captureSignal || captureSignal === previousCaptureSignal) {
+				return;
+			}
+
+			maybeMeasureAndStore({ shouldSetDestination: true });
+		},
+		[enabled, sharedBoundTag, expectedSourceScreenKey, maybeMeasureAndStore],
+	);
+};

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

@@ -0,0 +1,83 @@
+import { useAnimatedReaction, useSharedValue } from "react-native-reanimated";
+import type { AnimationStore } from "../../../stores/animation.store";
+import { BoundStore } from "../../../stores/bounds";
+import { resolvePendingSourceKey } from "../helpers/resolve-pending-source-key";
+import type { MaybeMeasureAndStoreParams } from "../types";
+
+export const usePendingDestinationRetryMeasurement = (params: {
+	sharedBoundTag: string;
+	enabled: boolean;
+	currentScreenKey: string;
+	expectedSourceScreenKey?: string;
+	progress: ReturnType<typeof AnimationStore.getRouteAnimation>;
+	animating: ReturnType<typeof AnimationStore.getRouteAnimation>;
+	maybeMeasureAndStore: (options: MaybeMeasureAndStoreParams) => void;
+}) => {
+	const {
+		sharedBoundTag,
+		enabled,
+		currentScreenKey,
+		expectedSourceScreenKey,
+		progress,
+		animating,
+		maybeMeasureAndStore,
+	} = params;
+
+	const retryCount = useSharedValue(0);
+	const MAX_RETRIES = 4;
+	const RETRY_PROGRESS_BUCKETS = 8;
+	const RETRY_PROGRESS_MAX = 1.05;
+
+	useAnimatedReaction(
+		() => {
+			"worklet";
+			if (!enabled) return 0;
+			if (retryCount.get() >= MAX_RETRIES) return 0;
+			if (!animating.get()) return 0;
+			if (BoundStore.hasDestinationLink(sharedBoundTag, currentScreenKey))
+				return 0;
+
+			const currentProgress = progress.get();
+			if (currentProgress <= 0 || currentProgress >= RETRY_PROGRESS_MAX) {
+				return 0;
+			}
+
+			const resolvedSourceKey = resolvePendingSourceKey(
+				sharedBoundTag,
+				expectedSourceScreenKey,
+			);
+
+			if (!resolvedSourceKey) return 0;
+			if (
+				!BoundStore.hasPendingLinkFromSource(sharedBoundTag, resolvedSourceKey)
+			) {
+				return 0;
+			}
+
+			const bucket = Math.floor(currentProgress * RETRY_PROGRESS_BUCKETS) + 1;
+			return bucket;
+		},
+		(captureSignal) => {
+			"worklet";
+			if (!enabled) return;
+			if (!captureSignal) {
+				retryCount.set(0);
+				return;
+			}
+
+			if (retryCount.get() >= MAX_RETRIES) return;
+			retryCount.set(retryCount.get() + 1);
+			maybeMeasureAndStore({ shouldSetDestination: true });
+		},
+		[
+			enabled,
+			sharedBoundTag,
+			currentScreenKey,
+			expectedSourceScreenKey,
+			progress,
+			animating,
+			maybeMeasureAndStore,
+			retryCount,
+		],
+	);
+};

package/src/shared/components/create-boundary-component/hooks/use-scroll-settled-measurement.ts

@@ -0,0 +1,40 @@
+import { useAnimatedReaction } from "react-native-reanimated";
+import { useScrollSettleContext } from "../../../providers/scroll-settle.provider";
+import type { AnimationStore } from "../../../stores/animation.store";
+import type { MaybeMeasureAndStoreParams } from "../types";
+
+export const useScrollSettledMeasurement = (params: {
+	enabled: boolean;
+	group: string | undefined;
+	hasNextScreen: boolean;
+	isAnimating: ReturnType<typeof AnimationStore.getRouteAnimation>;
+	maybeMeasureAndStore: (options: MaybeMeasureAndStoreParams) => void;
+}) => {
+	const { enabled, group, hasNextScreen, isAnimating, maybeMeasureAndStore } =
+		params;
+	const scrollSettle = useScrollSettleContext();
+	const settledSignal = scrollSettle?.settledSignal;
+
+	useAnimatedReaction(
+		() => settledSignal?.value ?? 0,
+		(signal, previousSignal) => {
+			"worklet";
+			if (!enabled) return;
+			if (!group || !hasNextScreen || !settledSignal) return;
+			if (signal === 0 || signal === previousSignal) return;
+			if (isAnimating.value) return;
+
+			// Re-measure source bounds after scroll settles while idle.
+			// This captures post-scroll positions before close transition starts.
+			maybeMeasureAndStore({ shouldUpdateSource: true });
+		},
+		[
+			enabled,
+			group,
+			hasNextScreen,
+			settledSignal,
+			isAnimating,
+			maybeMeasureAndStore,
+		],
+	);
+};