react-native-screen-transitions 4.0.0-alpha.0 → 4.0.0-alpha.10

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

@@ -1,9 +1,23 @@
-import { type ComponentType, forwardRef, memo } from "react";
+import {
+	type ComponentType,
+	cloneElement,
+	forwardRef,
+	memo,
+	useMemo,
+} from "react";
 import Animated from "react-native-reanimated";
-import { BoundaryContentPortalHost } from "./portal/components/boundary-content-portal";
+import {
+	BOUNDARY_TARGET_ACTIVE_PROP,
+	BoundaryTarget,
+} from "./components/boundary-target";
+import {
+	BoundaryContentPortal,
+	BoundaryContentPortalHost,
+} from "./portal/components/boundary-content-portal";
 import { BoundaryPortal } from "./portal/components/boundary-portal";
 import { BoundaryRootProvider } from "./providers/boundary-root.provider";
 import type { BoundaryComponentProps } from "./types";
+import { resolveBoundaryTarget } from "./utils/resolve-boundary-target";
 
 interface CreateBoundaryComponentOptions {
 	alreadyAnimated?: boolean;
@@ -36,6 +50,18 @@ export function createBoundaryComponent<P extends object>(
 			children,
 			...rest
 		} = props as any;
+		const targetResolution = useMemo(() => {
+			return resolveBoundaryTarget(children, {
+				isTarget: (element) => element.type === BoundaryTarget,
+				mapTarget: (element, selected) =>
+					cloneElement(element, {
+						[BOUNDARY_TARGET_ACTIVE_PROP]: selected,
+					} as any),
+			});
+		}, [children]);
+		const targetStyle = (
+			targetResolution.target?.props as { style?: unknown } | undefined
+		)?.style;
 
 		return (
 			<BoundaryRootProvider
@@ -45,14 +71,17 @@ export function createBoundaryComponent<P extends object>(
 				forwardedRef={forwardedRef}
 				group={group}
 				handoff={handoff}
+				hasTarget={targetResolution.target !== null}
 				id={id}
 				style={style}
+				targetCount={targetResolution.targetCount}
+				targetStyle={targetStyle}
 			>
 				{(root) => (
 					<BoundaryPortal
 						boundaryId={root.boundTag.tag}
 						enabled={root.shouldRenderBoundaryRootThroughPortal}
-						placeholderRef={root.rootEscapePlaceholderRef}
+						placeholderRef={root.measurementRef}
 					>
 						<AnimatedComponent
 							{...rest}
@@ -65,7 +94,12 @@ export function createBoundaryComponent<P extends object>(
 								enabled={root.shouldRenderHandoffHost}
 								screenKey={root.currentScreenKey}
 							>
-								{children}
+								<BoundaryContentPortal
+									boundaryId={root.boundTag.tag}
+									enabled={root.shouldRenderHandoffHost}
+								>
+									{targetResolution.children}
+								</BoundaryContentPortal>
 							</BoundaryContentPortalHost>
 						</AnimatedComponent>
 					</BoundaryPortal>

package/src/components/boundary/hooks/lifecycles/use-initial-destination-measurement.ts

@@ -1,4 +1,4 @@
-import { useCallback, useLayoutEffect } from "react";
+import { useCallback, useLayoutEffect, useMemo } from "react";
 import {
 	cancelAnimation,
 	useAnimatedReaction,
@@ -8,9 +8,16 @@ import {
 } from "react-native-reanimated";
 import { scheduleOnUI } from "react-native-worklets";
 import { useDescriptorsStore } from "../../../../providers/screen/descriptors";
+import { useBlankStackStore } from "../../../../providers/stack/blank-stack.provider";
 import { AnimationStore } from "../../../../stores/animation.store";
-import { getSourceScreenKeyFromPairKey } from "../../../../stores/bounds/helpers/link-pairs.helpers";
-import { getEntry } from "../../../../stores/bounds/internals/entries";
+import {
+	createScreenPairKey,
+	getSourceScreenKeyFromPairKey,
+} from "../../../../stores/bounds/helpers/link-pairs.helpers";
+import {
+	getEntry,
+	getMatchingSourceScreenKey,
+} from "../../../../stores/bounds/internals/entries";
 import { getLink } from "../../../../stores/bounds/internals/links";
 import { pairs } from "../../../../stores/bounds/internals/state";
 import type { BoundTag } from "../../../../stores/bounds/types";
@@ -19,7 +26,9 @@ import { logger } from "../../../../utils/logger";
 import type { MeasureBoundary } from "../../types";
 import { getInitialDestinationMeasurementSignal } from "../../utils/destination-signals";
 
-const HANDSHAKE_RETRY_DELAY_MS = 100;
+// A missed layout should be retried on the next frame. The previous 100 ms
+// interval made each ordinary Android layout miss visibly delay navigation.
+const HANDSHAKE_RETRY_DELAY_MS = 16;
 /**
  * A destination whose initial handshake never completes must not hold the
  * transition gate forever. After this budget, release the block with a warning
@@ -30,14 +39,12 @@ const MAX_HANDSHAKE_RETRIES = 20;
 interface UseInitialDestinationMeasurementParams {
 	boundTag: BoundTag;
 	enabled: boolean;
-	escapeClipping: boolean;
 	measureBoundary: MeasureBoundary;
 }
 
 export const useInitialDestinationMeasurement = ({
 	boundTag,
 	enabled,
-	escapeClipping,
 	measureBoundary,
 }: UseInitialDestinationMeasurementParams) => {
 	const { tag, linkKey, group } = boundTag;
@@ -48,12 +55,21 @@ export const useInitialDestinationMeasurement = ({
 	const destinationPairKey = useDescriptorsStore(
 		(s) => s.derivations.destinationPairKey,
 	);
-	const ancestorDestinationPairKey = useDescriptorsStore(
-		(s) => s.derivations.ancestorDestinationPairKey,
-	);
 	const destinationEnabled = enabled && !nextScreenKey;
-	const initialDestinationPairKey =
-		destinationPairKey ?? ancestorDestinationPairKey;
+	const canReceiveDestination = destinationEnabled && !!destinationPairKey;
+	const preferredSourceScreenKey = destinationPairKey
+		? getSourceScreenKeyFromPairKey(destinationPairKey)
+		: undefined;
+	const stackScenes = useBlankStackStore((store) => store.scenes);
+	// A retained closing screen can still have registered boundaries, but it
+	// cannot own a new transition link.
+	const closingSourceScreenKeys = useMemo(
+		() =>
+			stackScenes
+				.filter((scene) => scene.activity === "closing")
+				.map((scene) => scene.route.key),
+		[stackScenes],
+	);
 	const progress = AnimationStore.getValue(
 		currentScreenKey,
 		"transitionProgress",
@@ -67,6 +83,7 @@ export const useInitialDestinationMeasurement = ({
 	const retryToken = useSharedValue(0);
 	const handshakeRetries = useSharedValue(0);
 	const hasGivenUp = useSharedValue(0);
+	const hasFinishedInitialMeasurement = useSharedValue(0);
 
 	const releaseLifecycleStartBlock = useCallback(() => {
 		"worklet";
@@ -76,12 +93,25 @@ export const useInitialDestinationMeasurement = ({
 			return;
 		}
 
+		hasFinishedInitialMeasurement.set(1);
 		isBlockingLifecycleStart.set(0);
 		unblockLifecycleStart();
-	}, [isBlockingLifecycleStart, retryToken, unblockLifecycleStart]);
+	}, [
+		hasFinishedInitialMeasurement,
+		isBlockingLifecycleStart,
+		retryToken,
+		unblockLifecycleStart,
+	]);
 
 	const claimLifecycleStartBlock = useCallback(() => {
 		"worklet";
+		if (
+			!canReceiveDestination ||
+			hasFinishedInitialMeasurement.get() ||
+			!getMatchingSourceScreenKey(tag, currentScreenKey)
+		) {
+			return;
+		}
 
 		// The progress check and block claim must share one UI-thread operation.
 		// Otherwise a JS-thread layout effect can observe zero, enqueue the block,
@@ -92,55 +122,68 @@ export const useInitialDestinationMeasurement = ({
 
 		blockLifecycleStart();
 		isBlockingLifecycleStart.set(1);
-	}, [blockLifecycleStart, isBlockingLifecycleStart, progress]);
+	}, [
+		blockLifecycleStart,
+		canReceiveDestination,
+		currentScreenKey,
+		hasFinishedInitialMeasurement,
+		isBlockingLifecycleStart,
+		progress,
+		tag,
+	]);
 
 	useLayoutEffect(() => {
-		if (!destinationEnabled || !initialDestinationPairKey) {
+		if (!canReceiveDestination) {
 			return;
 		}
 
 		scheduleOnUI(claimLifecycleStartBlock);
 
 		return () => {
-			if (escapeClipping) {
-				// The portal host owns the release after this boundary hands off.
-				return;
-			}
-
 			// This is an abandonment fallback, not a second release. Run it on the UI
 			// runtime so it serializes with the handshake's guarded release.
 			scheduleOnUI(releaseLifecycleStartBlock);
 		};
 	}, [
 		claimLifecycleStartBlock,
-		destinationEnabled,
-		escapeClipping,
-		initialDestinationPairKey,
+		canReceiveDestination,
 		releaseLifecycleStartBlock,
 	]);
 
 	useAnimatedReaction(
 		() => {
 			"worklet";
+
+			if (
+				!canReceiveDestination ||
+				hasFinishedInitialMeasurement.get() ||
+				isBlockingLifecycleStart.get() <= 0
+			) {
+				return null;
+			}
+
+			if (progress.get() > 0) {
+				return null;
+			}
+
 			const retryTick = retryToken.get();
-			const isWaitingForOpenToStart = progress.get() <= 0;
-			const sourceScreenKey = initialDestinationPairKey
-				? getSourceScreenKeyFromPairKey(initialDestinationPairKey)
+			const sourceScreenKey = getMatchingSourceScreenKey(
+				tag,
+				currentScreenKey,
+				preferredSourceScreenKey,
+				closingSourceScreenKeys,
+			);
+			const pairKey = sourceScreenKey
+				? createScreenPairKey(sourceScreenKey, currentScreenKey)
 				: undefined;
 			const signal = getInitialDestinationMeasurementSignal({
-				enabled:
-					destinationEnabled &&
-					isWaitingForOpenToStart &&
-					isBlockingLifecycleStart.get() > 0,
-				destinationPairKey,
-				ancestorDestinationPairKey,
+				enabled: destinationEnabled,
+				pairKey,
 				linkId: linkKey,
 				group,
 				destinationPresent: getEntry(tag, currentScreenKey) !== null,
-				sourcePresent:
-					sourceScreenKey !== undefined &&
-					getEntry(tag, sourceScreenKey) !== null,
-				linkState: initialDestinationPairKey ? pairs.get() : undefined,
+				sourcePresent: sourceScreenKey !== null,
+				linkState: pairs.get(),
 			});
 
 			return [
@@ -149,9 +192,14 @@ export const useInitialDestinationMeasurement = ({
 				retryTick,
 			] as const;
 		},
-		([measurePairKey, action, retryTick], previous) => {
+		(next, previous) => {
 			"worklet";
-			if (!measurePairKey || !action) {
+			if (!next || hasFinishedInitialMeasurement.get()) {
+				return;
+			}
+
+			const [measurePairKey, action, retryTick] = next;
+			if (!action) {
 				return;
 			}
 
@@ -177,25 +225,20 @@ export const useInitialDestinationMeasurement = ({
 				return;
 			}
 
-			if (action === "measure") {
+			if (action === "measure" && measurePairKey) {
 				measureBoundary({
 					type: "destination",
 					pairKey: measurePairKey,
 				});
 			}
 
-			const link = getLink(measurePairKey, linkKey);
+			const link = measurePairKey ? getLink(measurePairKey, linkKey) : null;
 			const linkComplete = !!link?.source && !!link.destination;
 
 			if (linkComplete || action === "complete") {
 				cancelAnimation(retryToken);
 				handshakeRetries.set(0);
-				if (escapeClipping) {
-					// Screen-level escape has a second readiness phase after destination
-					// matching: the host must commit before the transition starts, or
-					// the payload can disappear for a frame.
-					return;
-				}
+				hasFinishedInitialMeasurement.set(1);
 				releaseLifecycleStartBlock();
 				return;
 			}

package/src/components/boundary/hooks/lifecycles/use-initial-source-measurement.ts

@@ -1,5 +1,6 @@
 import { useAnimatedReaction, useSharedValue } from "react-native-reanimated";
 import { useDescriptorsStore } from "../../../../providers/screen/descriptors";
+import { getPairKeyForSource } from "../../../../stores/bounds/internals/links";
 import { pairs } from "../../../../stores/bounds/internals/state";
 import type { BoundTag } from "../../../../stores/bounds/types";
 import type { MeasureBoundary } from "../../types";
@@ -11,12 +12,16 @@ export const useInitialSourceMeasurement = (params: {
 	boundTag: BoundTag;
 }) => {
 	const { enabled, measureBoundary, boundTag } = params;
-	const sourcePairKey = useDescriptorsStore((s) => s.derivations.sourcePairKey);
+	const currentScreenKey = useDescriptorsStore(
+		(s) => s.derivations.currentScreenKey,
+	);
 	const lastSourceCaptureSignal = useSharedValue<string | null>(null);
 
 	useAnimatedReaction(
 		() => {
 			"worklet";
+			const sourcePairKey =
+				getPairKeyForSource(boundTag.tag, currentScreenKey) ?? undefined;
 			return getInitialSourceCaptureSignal({
 				enabled,
 				sourcePairKey,

package/src/components/boundary/hooks/lifecycles/use-refresh-boundary.ts

@@ -1,6 +1,10 @@
 import { useAnimatedReaction } from "react-native-reanimated";
 import { useDescriptorsStore } from "../../../../providers/screen/descriptors";
 import { AnimationStore } from "../../../../stores/animation.store";
+import {
+	getPairKeyForDestination,
+	getPairKeyForSource,
+} from "../../../../stores/bounds/internals/links";
 import { pairs } from "../../../../stores/bounds/internals/state";
 import type { BoundTag } from "../../../../stores/bounds/types";
 import type { MeasureBoundary } from "../../types";
@@ -22,13 +26,6 @@ export const useRefreshBoundary = ({
 		(s) => s.derivations.currentScreenKey,
 	);
 	const nextScreenKey = useDescriptorsStore((s) => s.derivations.nextScreenKey);
-	const sourcePairKey = useDescriptorsStore((s) => s.derivations.sourcePairKey);
-	const destinationPairKey = useDescriptorsStore(
-		(s) => s.derivations.destinationPairKey,
-	);
-	const ancestorDestinationPairKey = useDescriptorsStore(
-		(s) => s.derivations.ancestorDestinationPairKey,
-	);
 	// Source-side boundaries refresh from the next screen's lifecycle pulse.
 	// Destination-side boundaries have no next screen, so they refresh from self.
 	const refreshScreenKey = nextScreenKey ?? currentScreenKey;
@@ -36,34 +33,41 @@ export const useRefreshBoundary = ({
 		refreshScreenKey,
 		"willAnimate",
 	);
-	const refreshClosing = AnimationStore.getValue(refreshScreenKey, "closing");
-	const refreshEntering = AnimationStore.getValue(refreshScreenKey, "entering");
-	const refreshAnimating = AnimationStore.getValue(
-		refreshScreenKey,
-		"progressAnimating",
-	);
-	const refreshProgress = AnimationStore.getValue(
+	const refreshSettled = AnimationStore.getValue(
 		refreshScreenKey,
-		"transitionProgress",
+		"progressSettled",
 	);
+	const refreshClosing = AnimationStore.getValue(refreshScreenKey, "closing");
 
 	useAnimatedReaction(
 		() => {
 			"worklet";
+
+			if (!enabled) return null;
+
+			const shouldRefresh = !!refreshWillAnimate.get();
+			const settled = !!refreshSettled.get();
+			// A group's active member can change while the transition is settled
+			// (for example, paging a destination gallery). Let that member publish
+			// fresh bounds even though there is no willAnimate lifecycle pulse yet.
+			if (!shouldRefresh && (!group || !settled)) {
+				return null;
+			}
+			const sourcePairKey =
+				getPairKeyForSource(boundTag.tag, currentScreenKey) ?? undefined;
+			const destinationPairKey =
+				getPairKeyForDestination(boundTag.tag, currentScreenKey) ?? undefined;
+
 			return getRefreshBoundarySignal({
 				enabled,
 				currentScreenKey,
 				sourcePairKey,
 				destinationPairKey,
-				ancestorDestinationPairKey,
-				nextScreenKey,
 				linkId: linkKey,
 				group,
-				shouldRefresh: !!refreshWillAnimate.get(),
+				shouldRefresh,
+				settled,
 				closing: !!refreshClosing.get(),
-				entering: !!refreshEntering.get(),
-				animating: !!refreshAnimating.get(),
-				progress: refreshProgress.get(),
 				linkState: pairs.get(),
 			});
 		},

package/src/components/boundary/hooks/use-boundary-measurement.ts

@@ -1,9 +1,12 @@
 import { useMemo } from "react";
 import type { View } from "react-native";
-import type { AnimatedRef, StyleProps } from "react-native-reanimated";
+import type { AnimatedRef } from "react-native-reanimated";
 import type { BoundTag } from "../../../stores/bounds/types";
 import { prepareStyleForBounds } from "../../../utils/bounds/helpers/styles/styles";
-import type { BoundaryConfigProps } from "../types";
+import type {
+	BoundaryConfigProps,
+	BoundaryLocalMeasurementValue,
+} from "../types";
 import { useBoundaryPresence } from "./lifecycles/use-boundary-presence";
 import { useInitialDestinationMeasurement } from "./lifecycles/use-initial-destination-measurement";
 import { useInitialSourceMeasurement } from "./lifecycles/use-initial-source-measurement";
@@ -19,11 +22,11 @@ interface UseBoundaryMeasurementParams {
 	currentScreenKey: string;
 	/** Surface to measure: a nested target's placeholder, else the root. */
 	measuredRef: AnimatedRef<View>;
-	/** Root's own style; ignored when a nested target supplies its own. */
+	/** Style belonging to the selected measurement surface. */
 	style?: unknown;
-	targetPreparedStyles?: StyleProps;
 	handoff: boolean;
 	escapeClipping: boolean;
+	localMeasurement: BoundaryLocalMeasurementValue;
 	config: BoundaryConfigProps;
 }
 
@@ -39,9 +42,9 @@ export const useBoundaryMeasurement = ({
 	currentScreenKey,
 	measuredRef,
 	style,
-	targetPreparedStyles,
 	handoff,
 	escapeClipping,
+	localMeasurement,
 	config,
 }: UseBoundaryMeasurementParams) => {
 	const { anchor, scaleMode, target, method } = config;
@@ -50,11 +53,7 @@ export const useBoundaryMeasurement = ({
 		[anchor, scaleMode, target, method],
 	);
 
-	const rootPreparedStyles = useMemo(
-		() => prepareStyleForBounds(style),
-		[style],
-	);
-	const preparedStyles = targetPreparedStyles ?? rootPreparedStyles;
+	const preparedStyles = useMemo(() => prepareStyleForBounds(style), [style]);
 
 	const measureBoundary = useMeasurer({
 		enabled,
@@ -64,12 +63,14 @@ export const useBoundaryMeasurement = ({
 		measuredAnimatedRef: measuredRef,
 		handoff,
 		escapeClipping,
+		localMeasurement,
 	});
 
-	// Register/unregister this boundary in the presence map so source/destination
-	// matching can resolve across concrete screen keys.
+	// Presence and source capture must not depend on this screen owning an
+	// interpolator: a nested source can participate in a transition owned by a
+	// different navigator.
 	useBoundaryPresence({
-		enabled: runtimeEnabled,
+		enabled,
 		boundTag,
 		currentScreenKey,
 		boundaryConfig,
@@ -78,7 +79,7 @@ export const useBoundaryMeasurement = ({
 	});
 
 	useInitialSourceMeasurement({
-		enabled: runtimeEnabled,
+		enabled,
 		measureBoundary,
 		boundTag,
 	});
@@ -86,7 +87,6 @@ export const useBoundaryMeasurement = ({
 	useInitialDestinationMeasurement({
 		boundTag,
 		enabled: runtimeEnabled,
-		escapeClipping,
 		measureBoundary,
 	});
 

package/src/components/boundary/hooks/use-measurer.ts

@@ -1,24 +1,19 @@
 import { useCallback } from "react";
 import type { View } from "react-native";
 import { useWindowDimensions } from "react-native";
-import {
-	type AnimatedRef,
-	measure,
-	type StyleProps,
-} from "react-native-reanimated";
+import type { AnimatedRef, StyleProps } from "react-native-reanimated";
 import { applyMeasuredBoundsWrites } from "../../../providers/helpers/measured-bounds-writes";
-import { useOriginContext } from "../../../providers/screen/origin.provider";
-import { useScreenSlots } from "../../../providers/screen/styles";
+import { useScreenSlotStore } from "../../../providers/screen/styles";
 import type { BoundTag } from "../../../stores/bounds/types";
 import { ScrollStore } from "../../../stores/scroll.store";
 import { SystemStore } from "../../../stores/system.store";
 import { getVisibilityBlockOffset } from "../../../utils/visibility-block-offset";
-import type { MeasureBoundary } from "../types";
+import type { BoundaryLocalMeasurementValue, MeasureBoundary } from "../types";
 import {
 	attachScrollSnapshotToMeasuredBounds,
+	correctMeasuredBoundsForVisibilityGate,
 	isMeasurementInViewport,
 	measureWithOverscrollAwareness,
-	normalizeMeasuredBoundsWithVisibilityGate,
 } from "../utils/measured-bounds";
 
 interface UseMeasurerParams {
@@ -29,6 +24,7 @@ interface UseMeasurerParams {
 	measuredAnimatedRef: AnimatedRef<View>;
 	handoff: boolean;
 	escapeClipping: boolean;
+	localMeasurement: BoundaryLocalMeasurementValue;
 }
 
 export const useMeasurer = ({
@@ -39,6 +35,7 @@ export const useMeasurer = ({
 	measuredAnimatedRef,
 	handoff,
 	escapeClipping,
+	localMeasurement,
 }: UseMeasurerParams): MeasureBoundary => {
 	const { width: viewportWidth, height: viewportHeight } =
 		useWindowDimensions();
@@ -49,8 +46,9 @@ export const useMeasurer = ({
 		currentScreenKey,
 		"pendingLifecycleStartBlockCount",
 	);
-	const { originRef } = useOriginContext();
-	const { visibilityBlocked } = useScreenSlots();
+	const visibilityBlocked = useScreenSlotStore(
+		(store) => store.visibilityBlocked,
+	);
 
 	return useCallback(
 		(target) => {
@@ -61,19 +59,24 @@ export const useMeasurer = ({
 				measuredAnimatedRef,
 				scrollState.get(),
 			);
-			const measuredOrigin = measure(originRef);
 
-			if (!measured || !measuredOrigin) return;
+			if (!measured) return;
 
-			const normalizedMeasured = normalizeMeasuredBoundsWithVisibilityGate({
+			const correctedMeasured = correctMeasuredBoundsForVisibilityGate({
 				measured,
-				origin: measuredOrigin,
-				visibilityBlocked: escapeClipping && visibilityBlocked.get(),
+				visibilityBlocked: visibilityBlocked.get(),
 				visibilityBlockOffset: getVisibilityBlockOffset(viewportHeight),
 				viewportWidth,
 				viewportHeight,
 			});
 
+			if (escapeClipping && target.type === "source") {
+				localMeasurement.set({
+					bounds: measured,
+					pairKey: target.pairKey,
+				});
+			}
+
 			/**
 			 * - Destination Pass -
 			 * Be strict while lifecycle start is blocked for destination capture.
@@ -88,7 +91,7 @@ export const useMeasurer = ({
 				target.type !== "destination" ||
 				!shouldGuardDestinationViewport ||
 				isMeasurementInViewport(
-					normalizedMeasured,
+					correctedMeasured,
 					viewportWidth,
 					viewportHeight,
 				);
@@ -96,7 +99,7 @@ export const useMeasurer = ({
 			if (!viewportAllowsDestinationWrite) return;
 
 			const measuredWithScroll = attachScrollSnapshotToMeasuredBounds(
-				normalizedMeasured,
+				correctedMeasured,
 				scrollMetadata.get(),
 			);
 
@@ -120,12 +123,12 @@ export const useMeasurer = ({
 			measuredAnimatedRef,
 			handoff,
 			escapeClipping,
+			localMeasurement,
 			viewportWidth,
 			viewportHeight,
 			scrollState,
 			scrollMetadata,
 			pendingLifecycleStartBlockCount,
-			originRef,
 			visibilityBlocked,
 		],
 	);