react-native-screen-transitions 3.3.0-rc.3 → 3.4.0-alpha.0

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

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

@@ -0,0 +1,263 @@
+import {
+	type ComponentType,
+	forwardRef,
+	memo,
+	useCallback,
+	useMemo,
+} from "react";
+import { Pressable, View as RNView, type View } from "react-native";
+import Animated, { runOnUI, useAnimatedRef } from "react-native-reanimated";
+import { useAssociatedStyles } from "../../hooks/animation/use-associated-style";
+import { useLayoutAnchorContext } from "../../providers/layout-anchor.provider";
+import { useDescriptorDerivations } from "../../providers/screen/descriptors";
+import { AnimationStore } from "../../stores/animation.store";
+import { BoundStore } from "../../stores/bounds";
+import { prepareStyleForBounds } from "../../utils/bounds/helpers/styles";
+import { useAutoSourceMeasurement } from "./hooks/use-auto-source-measurement";
+import { useBoundaryMeasureAndStore } from "./hooks/use-boundary-measure-and-store";
+import { useBoundaryPresence } from "./hooks/use-boundary-presence";
+import { useGroupActiveMeasurement } from "./hooks/use-group-active-measurement";
+import { useInitialLayoutHandler } from "./hooks/use-initial-layout-handler";
+import { usePendingDestinationMeasurement } from "./hooks/use-pending-destination-measurement";
+import { usePendingDestinationRetryMeasurement } from "./hooks/use-pending-destination-retry-measurement";
+import { useScrollSettledMeasurement } from "./hooks/use-scroll-settled-measurement";
+import type { BoundaryComponentProps, BoundaryConfigProps } from "./types";
+import { buildBoundaryMatchKey } from "./utils/build-boundary-match-key";
+
+const setGroupActiveIdOnUI = (group: string, id: string) => {
+	"worklet";
+	BoundStore.setGroupActiveId(group, id);
+};
+
+export function createBoundaryComponent<P extends object>(
+	Wrapped: ComponentType<P>,
+) {
+	const AnimatedComponent = Animated.createAnimatedComponent(Wrapped);
+
+	const Inner = forwardRef<
+		React.ComponentRef<typeof AnimatedComponent>,
+		BoundaryComponentProps<P>
+	>((props, _ref) => {
+		const {
+			enabled = true,
+			group,
+			id,
+			anchor,
+			scaleMode,
+			target,
+			method,
+			style,
+			onPress,
+			...rest
+		} = props as any;
+
+		const sharedBoundTag = buildBoundaryMatchKey({ group, id });
+		const animatedRef = useAnimatedRef<View>();
+
+		const {
+			previousScreenKey: preferredSourceScreenKey,
+			currentScreenKey,
+			nextScreenKey,
+			ancestorKeys,
+			navigatorKey,
+			ancestorNavigatorKeys,
+			hasConfiguredInterpolator,
+		} = useDescriptorDerivations();
+		const runtimeEnabled = enabled && hasConfiguredInterpolator;
+		const hasNextScreen = !!nextScreenKey;
+		const shouldUpdateDestination = !hasNextScreen;
+		const layoutAnchor = useLayoutAnchorContext();
+		const boundaryConfig = useMemo<BoundaryConfigProps | undefined>(() => {
+			if (
+				anchor === undefined &&
+				scaleMode === undefined &&
+				target === undefined &&
+				method === undefined
+			) {
+				return undefined;
+			}
+
+			return {
+				anchor,
+				scaleMode,
+				target,
+				method,
+			};
+		}, [anchor, scaleMode, target, method]);
+
+		const isAnimating = AnimationStore.getRouteAnimation(
+			currentScreenKey,
+			"animating",
+		);
+		const progress = AnimationStore.getRouteAnimation(
+			currentScreenKey,
+			"progress",
+		);
+
+		const preparedStyles = useMemo(() => prepareStyleForBounds(style), [style]);
+
+		const { associatedStyles } = useAssociatedStyles({
+			id: sharedBoundTag,
+			resetTransformOnUnset: true,
+			waitForFirstResolvedStyle: true,
+		});
+
+		const maybeMeasureAndStore = useBoundaryMeasureAndStore({
+			enabled,
+			sharedBoundTag,
+			preferredSourceScreenKey,
+			currentScreenKey,
+			ancestorKeys,
+			navigatorKey,
+			ancestorNavigatorKeys,
+			isAnimating,
+			preparedStyles,
+			animatedRef,
+			layoutAnchor,
+		});
+
+		const shouldRunDestinationEffects = runtimeEnabled && !hasNextScreen;
+
+		// Register/unregister this boundary in the presence map so source/destination
+		// matching can resolve across screens (including ancestor relationships).
+		useBoundaryPresence({
+			enabled: runtimeEnabled,
+			sharedBoundTag,
+			currentScreenKey,
+			ancestorKeys,
+			navigatorKey,
+			ancestorNavigatorKeys,
+			boundaryConfig,
+		});
+
+		// On the source screen, capture source bounds when a matching destination
+		// appears on the next screen.
+		useAutoSourceMeasurement({
+			enabled: runtimeEnabled,
+			sharedBoundTag,
+			nextScreenKey,
+			maybeMeasureAndStore,
+		});
+
+		// Primary destination capture: once a pending source link exists for this tag,
+		// measure destination bounds and complete the pair.
+		usePendingDestinationMeasurement({
+			sharedBoundTag,
+			enabled: shouldRunDestinationEffects,
+			expectedSourceScreenKey: preferredSourceScreenKey,
+			maybeMeasureAndStore,
+		});
+
+		// Reliability fallback: retry destination capture during transition progress
+		// when the initial pending-destination attempt happens before layout is ready.
+		usePendingDestinationRetryMeasurement({
+			sharedBoundTag,
+			enabled: shouldRunDestinationEffects,
+			currentScreenKey,
+			expectedSourceScreenKey: preferredSourceScreenKey,
+			progress,
+			animating: isAnimating,
+			maybeMeasureAndStore,
+		});
+
+		// Grouped boundaries (e.g. paged/detail UIs): re-measure when this boundary
+		// becomes the active member so destination bounds stay accurate.
+		useGroupActiveMeasurement({
+			enabled: runtimeEnabled,
+			group,
+			id,
+			shouldUpdateDestination,
+			isAnimating,
+			maybeMeasureAndStore,
+		});
+
+		// While idle on source screens, re-measure after scroll settles so a later
+		// close transition starts from up-to-date source geometry.
+		useScrollSettledMeasurement({
+			enabled: runtimeEnabled,
+			group,
+			hasNextScreen,
+			isAnimating,
+			maybeMeasureAndStore,
+		});
+
+		// Destination mount-time capture path: onLayout schedules a one-time UI-thread
+		// initial measurement when transitions are active.
+		useInitialLayoutHandler({
+			enabled: runtimeEnabled,
+			sharedBoundTag,
+			currentScreenKey,
+			ancestorKeys,
+			expectedSourceScreenKey: preferredSourceScreenKey,
+			maybeMeasureAndStore,
+		});
+
+		const handlePress = useCallback(
+			(...args: unknown[]) => {
+				// Press path has priority: capture source before user onPress/navigation.
+				if (group) {
+					runOnUI(setGroupActiveIdOnUI)(group, String(id));
+				}
+				runOnUI(maybeMeasureAndStore)({ shouldSetSource: true });
+
+				if (typeof onPress === "function") {
+					onPress(...args);
+				}
+			},
+			[group, id, maybeMeasureAndStore, onPress],
+		);
+
+		const resolvedOnPress =
+			typeof onPress === "function" ? handlePress : undefined;
+
+		return (
+			<AnimatedComponent
+				{...(rest as any)}
+				ref={animatedRef}
+				style={[style, enabled ? associatedStyles : undefined]}
+				onPress={resolvedOnPress}
+				collapsable={false}
+			/>
+		);
+	});
+
+	return memo(Inner) as unknown as React.MemoExoticComponent<
+		React.ForwardRefExoticComponent<
+			BoundaryComponentProps<P> &
+				React.RefAttributes<React.ComponentRef<typeof Wrapped>>
+		>
+	>;
+}
+
+// Pre-built boundary component variants
+const BoundaryView = createBoundaryComponent(RNView);
+BoundaryView.displayName = "Transition.Boundary.View";
+
+const BoundaryPressable = createBoundaryComponent(Pressable);
+BoundaryPressable.displayName = "Transition.Boundary.Pressable";
+
+/**
+ * Shared-boundary components.
+ *
+ * How measurement works:
+ * 1. Source screen captures bounds for a tag.
+ * 2. Destination screen captures bounds for the same tag.
+ * 3. The link is updated as layout changes (group-active + scroll-settled paths).
+ *
+ * Press behavior:
+ * - When a boundary has `onPress` (typically `Boundary.Pressable`), source
+ *   measurement runs before the user callback. This gives navigation transitions
+ *   fresh source geometry on the first frame.
+ *
+ * Use:
+ * - `Boundary.View` for passive/shared elements.
+ * - `Boundary.Pressable` for tappable elements that start navigation.
+ */
+export const Boundary = {
+	/** Passive boundary wrapper (no built-in press semantics). */
+	View: BoundaryView,
+	/** Pressable boundary wrapper with press-priority source capture. */
+	Pressable: BoundaryPressable,
+	/** Factory for custom boundary wrappers. */
+	createBoundaryComponent,
+};

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

@@ -0,0 +1,47 @@
+import type { ViewProps } from "react-native";
+import type { BoundsOptions } from "../../utils/bounds/types/options";
+
+export type BoundaryId = string | number;
+
+export type BoundaryConfigProps = Pick<
+	BoundsOptions,
+	"anchor" | "scaleMode" | "target" | "method"
+>;
+
+/**
+ * Boundary-specific props shared across all boundary component variants.
+ * These are the props that `createBoundaryComponent` extracts and handles
+ * internally, regardless of the underlying wrapped component.
+ */
+export interface BoundaryOwnProps extends BoundaryConfigProps {
+	/**
+	 * Optional group name for collection/list scenarios.
+	 * When provided, boundaries are tracked as a group and the active member
+	 * re-measures automatically when focus changes within the group.
+	 * The internal tag becomes `group:id`.
+	 */
+	group?: string;
+	/**
+	 * Whether this boundary should participate in matching and measurement.
+	 * @default true
+	 */
+	enabled?: boolean;
+	id: BoundaryId;
+}
+
+/**
+ * Full props for a boundary component wrapping a component with props `P`.
+ * Omits `id` from the wrapped component's props (since boundary uses its own `id`).
+ */
+export type BoundaryComponentProps<P extends object> = Omit<P, "id"> &
+	BoundaryOwnProps;
+
+/** Convenience alias for a View-based boundary (the most common case). */
+export type BoundaryProps = BoundaryComponentProps<ViewProps>;
+
+export interface MaybeMeasureAndStoreParams {
+	shouldSetSource?: boolean;
+	shouldSetDestination?: boolean;
+	shouldUpdateSource?: boolean;
+	shouldUpdateDestination?: boolean;
+}

package/src/shared/components/create-boundary-component/utils/build-boundary-match-key.ts

@@ -0,0 +1,29 @@
+import type { BoundaryId } from "../types";
+
+type BuildBoundaryMatchKeyParams = {
+	group?: string;
+	id: BoundaryId;
+};
+
+export function buildBoundaryMatchKey(
+	params: BuildBoundaryMatchKeyParams,
+): string;
+export function buildBoundaryMatchKey(
+	group: string | undefined,
+	id: BoundaryId,
+): string;
+export function buildBoundaryMatchKey(
+	paramsOrGroup: BuildBoundaryMatchKeyParams | string | undefined,
+	legacyId?: BoundaryId,
+): string {
+	"worklet";
+
+	if (typeof paramsOrGroup === "object" && paramsOrGroup !== null) {
+		const { group, id } = paramsOrGroup;
+		return group ? `${group}:${id}` : String(id);
+	}
+
+	const group = paramsOrGroup;
+	const id = legacyId;
+	return group ? `${group}:${id}` : String(id);
+}