react-native-screen-transitions 3.9.0-alpha.1 → 3.9.0-alpha.3

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

@@ -2,45 +2,53 @@ import {
 	type ComponentType,
 	forwardRef,
 	memo,
-	useCallback,
+	type ReactNode,
 	useImperativeHandle,
 	useMemo,
-	useRef,
 } from "react";
 import type { View } from "react-native";
-import Animated, {
-	runOnUI,
-	useAnimatedRef,
-	useAnimatedStyle,
-} from "react-native-reanimated";
-import { NO_STYLES } from "../../constants";
+import Animated, { useAnimatedRef } from "react-native-reanimated";
 import { useDescriptorsStore } from "../../providers/screen/descriptors";
-import { useScreenStyles } from "../../providers/screen/styles";
-import { createPendingPairKey } from "../../stores/bounds/helpers/link-pairs.helpers";
-import { prepareStyleForBounds } from "../../utils/bounds/helpers/styles/styles";
-import { logger } from "../../utils/logger";
-import { useBoundaryPresence } from "./hooks/use-boundary-presence";
-import { useInitialDestinationMeasurement } from "./hooks/use-initial-destination-measurement";
-import { useInitialSourceMeasurement } from "./hooks/use-initial-source-measurement";
-import { useMeasurer } from "./hooks/use-measurer";
-import { useRefreshBoundary } from "./hooks/use-refresh-boundary";
-import { isTeleportAvailable } from "./portal/teleport";
 import {
-	BoundaryOwnerProvider,
-	useBoundaryOwner,
-} from "./providers/boundary-owner.provider";
-import type { BoundaryComponentProps, BoundaryConfigProps } from "./types";
+	useComposedSlotStyles,
+	useSlotStackingStyles,
+} from "../../providers/screen/styles";
+import { createBoundTag } from "../../stores/bounds/helpers/link-pairs.helpers";
+import { useBoundaryMeasurement } from "./hooks/use-boundary-measurement";
+import { BoundaryLocalPortalHost } from "./portal/components/boundary-local-portal-host";
+import { Portal } from "./portal/components/portal";
+import { resolveBoundaryPortal } from "./portal/utils/resolve-portal";
+import {
+	BoundaryRootProvider,
+	useBoundaryRootState,
+} from "./providers/boundary-root.provider";
+import type { BoundaryComponentProps } from "./types";
 
 interface CreateBoundaryComponentOptions {
 	alreadyAnimated?: boolean;
-	shouldAutoMeasure?: boolean;
 }
 
+const hasRenderableChildren = (children: ReactNode): boolean => {
+	if (
+		children === null ||
+		children === undefined ||
+		typeof children === "boolean"
+	) {
+		return false;
+	}
+
+	if (Array.isArray(children)) {
+		return children.some(hasRenderableChildren);
+	}
+
+	return true;
+};
+
 export function createBoundaryComponent<P extends object>(
 	Wrapped: ComponentType<P>,
 	options: CreateBoundaryComponentOptions = {},
 ) {
-	const { alreadyAnimated = false, shouldAutoMeasure = false } = options;
+	const { alreadyAnimated = false } = options;
 	const AnimatedComponent = alreadyAnimated
 		? Wrapped
 		: Animated.createAnimatedComponent(Wrapped);
@@ -49,7 +57,6 @@ export function createBoundaryComponent<P extends object>(
 		React.ComponentRef<typeof AnimatedComponent>,
 		BoundaryComponentProps<P>
 	>((props, forwardedRef) => {
-		const ownerRef = useAnimatedRef<View>();
 		const {
 			enabled = true,
 			group,
@@ -60,12 +67,20 @@ export function createBoundaryComponent<P extends object>(
 			method,
 			style,
 			onPress,
-			portal,
+			handoff,
+			escapeClipping,
+			children,
 			...rest
 		} = props as any;
 
-		const linkId = String(id);
-		const entryTag = group ? `${group}:${linkId}` : linkId;
+		const boundTag = useMemo(
+			() => createBoundTag(String(id), group),
+			[id, group],
+		);
+		const portalRuntime = resolveBoundaryPortal({
+			handoff,
+			escapeClipping,
+		});
 
 		const currentScreenKey = useDescriptorsStore(
 			(s) => s.derivations.currentScreenKey,
@@ -73,157 +88,110 @@ export function createBoundaryComponent<P extends object>(
 		const hasConfiguredInterpolator = useDescriptorsStore(
 			(s) => s.derivations.hasConfiguredInterpolator,
 		);
-
 		const runtimeEnabled = enabled && hasConfiguredInterpolator;
-		const boundaryConfig = useMemo<BoundaryConfigProps>(() => {
-			return {
-				anchor,
-				scaleMode,
-				target,
-				method,
-			};
-		}, [anchor, scaleMode, target, method]);
-
-		const ownerPreparedStyles = useMemo(
-			() => prepareStyleForBounds(style),
-			[style],
-		);
-		const { stylesMap } = useScreenStyles();
+		// Associated slot styles attach whenever the boundary is enabled,
+		// independent of whether an interpolator is configured for this transition.
+		const shouldAttachAssociatedStyles = enabled;
+		const canPortalRoot =
+			portalRuntime.enabled && hasRenderableChildren(children);
 
-		const associatedStyles = useAnimatedStyle(() => {
-			"worklet";
-			return stylesMap.get()[entryTag]?.style ?? NO_STYLES;
-		});
-
-		const associatedStackingStyles = useAnimatedStyle(() => {
-			"worklet";
-			const baseStyle = stylesMap.get()[entryTag]?.style;
-			const zIndex = baseStyle?.zIndex ?? 0;
-			const elevation = baseStyle?.elevation ?? 0;
+		const associatedStyles = useComposedSlotStyles(boundTag.tag, style);
+		const associatedStackingStyles = useSlotStackingStyles(boundTag.tag);
+		const rootPlaceholderRef = useAnimatedRef<View>();
 
-			if (zIndex === 0 && elevation === 0) {
-				return NO_STYLES;
-			}
-
-			return { zIndex, elevation };
+		const {
+			ref,
+			contextValue,
+			measuredRef,
+			hasActiveTarget,
+			targetPreparedStyles,
+		} = useBoundaryRootState({
+			boundTag,
+			portalRuntime,
+			rootMeasurementRef: canPortalRoot ? rootPlaceholderRef : undefined,
 		});
 
-		const hasWarned = useRef(false);
-		const adjustedPortal = isTeleportAvailable ? portal : undefined;
-
-		if (!hasWarned.current && !isTeleportAvailable && portal) {
-			logger.warn(
-				"react-native-teleport is not installed and will fallback to default behavior.",
-			);
-			hasWarned.current = true;
-		}
-
-		const { contextValue, measuredRef, hasActiveTarget, targetPreparedStyles } =
-			useBoundaryOwner({
-				ownerRef,
-				associatedTargetStyles: runtimeEnabled ? associatedStyles : undefined,
-				entryTag,
-				portal: adjustedPortal,
-			});
-
-		const preparedStyles = targetPreparedStyles ?? ownerPreparedStyles;
-
-		const portalHost =
-			typeof adjustedPortal === "object"
-				? (adjustedPortal.attachTo ?? "current-screen")
-				: adjustedPortal
-					? "current-screen"
-					: undefined;
-
-		const measureBoundary = useMeasurer({
+		useBoundaryMeasurement({
+			boundTag,
 			enabled,
-			entryTag,
-			linkId,
-			group,
-			currentScreenKey,
-			preparedStyles,
-			measuredAnimatedRef: measuredRef,
-			portalHost,
-		});
-
-		// Register/unregister this boundary in the presence map so source/destination
-		// matching can resolve across concrete screen keys.
-		useBoundaryPresence({
-			enabled: runtimeEnabled,
-			entryTag,
+			runtimeEnabled,
 			currentScreenKey,
-			boundaryConfig,
-		});
-
-		const shouldPassivelyMeasureSource =
-			shouldAutoMeasure && typeof onPress !== "function";
-
-		useInitialSourceMeasurement({
-			enabled: runtimeEnabled,
-			measureBoundary,
-			linkId,
-			group,
-			shouldAutoMeasure: shouldPassivelyMeasureSource,
-		});
-
-		useInitialDestinationMeasurement({
-			linkId,
-			enabled: runtimeEnabled,
-			measureBoundary,
-		});
-
-		useRefreshBoundary({
-			enabled: runtimeEnabled,
-			linkId,
-			group,
-			measureBoundary,
+			measuredRef,
+			style,
+			targetPreparedStyles,
+			handoff: portalRuntime.handoff,
+			escapeClipping: portalRuntime.escapeClipping,
+			config: { anchor, scaleMode, target, method },
 		});
 
-		const handlePress = useCallback(
-			(...args: unknown[]) => {
-				// Press path has priority: capture source before user onPress/navigation.
-				runOnUI(measureBoundary)({
-					type: "source",
-					pairKey: createPendingPairKey(currentScreenKey),
-				});
-
-				if (typeof onPress === "function") {
-					onPress(...args);
-				}
-			},
-			[measureBoundary, onPress, currentScreenKey],
+		useImperativeHandle(forwardedRef, () => ref.current as any, [ref]);
+
+		const shouldPortalRoot = canPortalRoot && !hasActiveTarget;
+		// A nested active target takes the full associated style, so the root keeps
+		// only its stacking context. Without a nested target, a portal'd root is the
+		// target, so its associated style is applied through the portal host instead
+		// of inline on the teleported element.
+		// Host-only handoff receivers still need the associated style: their local
+		// portal host is absolute-filled inside this root, so the root is the visual
+		// frame that animates the received payload.
+		const attachedStyle = shouldAttachAssociatedStyles
+			? hasActiveTarget
+				? associatedStackingStyles
+				: shouldPortalRoot
+					? undefined
+					: associatedStyles
+			: undefined;
+		const pressProps = typeof onPress === "function" ? { onPress } : undefined;
+
+		const localPortalHost = (
+			<BoundaryLocalPortalHost
+				boundaryId={boundTag.tag}
+				enabled={enabled && portalRuntime.handoff}
+				screenKey={currentScreenKey}
+			/>
+		);
+		const canInjectLocalPortalHost = typeof children !== "function";
+
+		const renderBoundaryRoot = (extraChildren?: ReactNode) => (
+			<AnimatedComponent
+				{...rest}
+				{...pressProps}
+				ref={ref}
+				style={[style, attachedStyle]}
+				collapsable={false}
+			>
+				{children}
+				{canInjectLocalPortalHost ? extraChildren : null}
+			</AnimatedComponent>
+		);
+		const boundaryRoot = renderBoundaryRoot(
+			shouldPortalRoot ? undefined : localPortalHost,
 		);
-
-		const resolvedOnPress =
-			typeof onPress === "function" ? handlePress : undefined;
-
-		useImperativeHandle(forwardedRef, () => ownerRef.current as any, [
-			ownerRef,
-		]);
 
 		return (
-			<BoundaryOwnerProvider value={contextValue}>
-				<AnimatedComponent
-					{...rest}
-					ref={ownerRef}
-					style={[
-						style,
-						runtimeEnabled
-							? hasActiveTarget
-								? associatedStackingStyles
-								: associatedStyles
-							: undefined,
-					]}
-					onPress={resolvedOnPress}
-					collapsable={false}
-				/>
-			</BoundaryOwnerProvider>
+			<BoundaryRootProvider value={contextValue}>
+				{shouldPortalRoot ? (
+					<Portal
+						id={boundTag.tag}
+						handoff={portalRuntime.handoff}
+						escapeClipping={portalRuntime.escapeClipping}
+						placeholderRef={rootPlaceholderRef}
+						placeholderChildren={
+							portalRuntime.handoff ? localPortalHost : undefined
+						}
+					>
+						{boundaryRoot}
+					</Portal>
+				) : (
+					boundaryRoot
+				)}
+			</BoundaryRootProvider>
 		);
 	});
 
-	return memo(
-		Animated.createAnimatedComponent(Inner),
-	) as unknown as React.MemoExoticComponent<
+	// The HOC's runtime identity (animated + memoized forwardRef) is not
+	// expressible against the public boundary props, so assert it here.
+	return memo(Inner) as unknown as React.MemoExoticComponent<
 		React.ForwardRefExoticComponent<
 			BoundaryComponentProps<P> &
 				React.RefAttributes<React.ComponentRef<typeof Wrapped>>

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

@@ -0,0 +1,41 @@
+import { useLayoutEffect } from "react";
+import { runOnUI } from "react-native-reanimated";
+import {
+	removeEntry,
+	setEntry,
+} from "../../../../stores/bounds/internals/entries";
+import type { BoundTag } from "../../../../stores/bounds/types";
+import type { BoundaryConfigProps } from "../../types";
+
+export const useBoundaryPresence = (params: {
+	enabled: boolean;
+	boundTag: BoundTag;
+	currentScreenKey: string;
+	boundaryConfig?: BoundaryConfigProps;
+	handoff?: boolean;
+	escapeClipping?: boolean;
+}) => {
+	const {
+		enabled,
+		boundTag,
+		currentScreenKey,
+		boundaryConfig,
+		handoff,
+		escapeClipping,
+	} = params;
+	const { tag } = boundTag;
+
+	useLayoutEffect(() => {
+		if (!enabled) return;
+
+		runOnUI(setEntry)(tag, currentScreenKey, {
+			boundaryConfig,
+			handoff: handoff ? true : null,
+			escapeClipping: escapeClipping ? true : null,
+		});
+
+		return () => {
+			runOnUI(removeEntry)(tag, currentScreenKey);
+		};
+	}, [enabled, tag, currentScreenKey, boundaryConfig, handoff, escapeClipping]);
+};

package/src/shared/components/boundary/hooks/{use-initial-destination-measurement.ts → lifecycles/use-initial-destination-measurement.ts}

@@ -5,19 +5,29 @@ import {
 	withDelay,
 	withTiming,
 } from "react-native-reanimated";
-import { useDescriptorsStore } from "../../../providers/screen/descriptors";
-import { AnimationStore } from "../../../stores/animation.store";
-import { getDestination } from "../../../stores/bounds/internals/links";
-import { pairs } from "../../../stores/bounds/internals/state";
+import { useDescriptorsStore } from "../../../../providers/screen/descriptors";
+import { AnimationStore } from "../../../../stores/animation.store";
+import { getSourceScreenKeyFromPairKey } from "../../../../stores/bounds/helpers/link-pairs.helpers";
+import { getEntry } from "../../../../stores/bounds/internals/entries";
+import {
+	getDestination,
+	getLink,
+} from "../../../../stores/bounds/internals/links";
+import { pairs } from "../../../../stores/bounds/internals/state";
+import type { BoundTag } from "../../../../stores/bounds/types";
 import {
 	LifecycleTransitionRequestKind,
 	SystemStore,
-} from "../../../stores/system.store";
-import { logger } from "../../../utils/logger";
-import type { MeasureBoundary } from "../types";
-import { getInitialDestinationMeasurePairKey } from "../utils/destination-signals";
+} from "../../../../stores/system.store";
+import { logger } from "../../../../utils/logger";
+import {
+	hasHandoffEscapeContinuation,
+	usesEscapeClippingHost,
+} from "../../portal/utils/ownership";
+import type { MeasureBoundary } from "../../types";
+import { getInitialDestinationMeasurePairKey } from "../../utils/destination-signals";
 
-const VIEWPORT_RETRY_DELAY_MS = 16;
+const VIEWPORT_RETRY_DELAY_MS = 100;
 /**
  * A destination that keeps failing its measurement guards must not hold the
  * transition gate forever — after this budget the block is released with a
@@ -26,16 +36,17 @@ const VIEWPORT_RETRY_DELAY_MS = 16;
 const MAX_VIEWPORT_RETRIES = 20;
 
 interface UseInitialDestinationMeasurementParams {
-	linkId: string;
+	boundTag: BoundTag;
 	enabled: boolean;
 	measureBoundary: MeasureBoundary;
 }
 
 export const useInitialDestinationMeasurement = ({
-	linkId,
+	boundTag,
 	enabled,
 	measureBoundary,
 }: UseInitialDestinationMeasurementParams) => {
+	const { tag, linkKey, group } = boundTag;
 	const currentScreenKey = useDescriptorsStore(
 		(s) => s.derivations.currentScreenKey,
 	);
@@ -51,9 +62,12 @@ export const useInitialDestinationMeasurement = ({
 		currentScreenKey,
 		"transitionProgress",
 	);
-	const system = SystemStore.getBag(currentScreenKey);
-	const { pendingLifecycleRequestKind } = system;
-	const { blockLifecycleStart, unblockLifecycleStart } = system.actions;
+
+	const {
+		pendingLifecycleRequestKind,
+		actions: { blockLifecycleStart, unblockLifecycleStart },
+	} = SystemStore.getBag(currentScreenKey);
+
 	const isBlockingLifecycleStart = useSharedValue(0);
 	const retryToken = useSharedValue(0);
 	const viewportRetries = useSharedValue(0);
@@ -90,7 +104,8 @@ export const useInitialDestinationMeasurement = ({
 				enabled: destinationEnabled,
 				destinationPairKey,
 				ancestorDestinationPairKey,
-				linkId,
+				linkId: linkKey,
+				group,
 				linkState:
 					destinationEnabled &&
 					(destinationPairKey || ancestorDestinationPairKey)
@@ -100,12 +115,19 @@ export const useInitialDestinationMeasurement = ({
 
 			return [measurePairKey, retryTick] as const;
 		},
-		([measurePairKey]) => {
+		([measurePairKey, retryTick], previous) => {
 			"worklet";
 			if (!measurePairKey) {
-				releaseLifecycleStartBlock();
-				viewportRetries.set(0);
-				hasGivenUp.set(0);
+				return;
+			}
+
+			const previousMeasurePairKey = previous?.[0];
+			const previousRetryTick = previous?.[1];
+			const shouldAttemptMeasure =
+				measurePairKey !== previousMeasurePairKey ||
+				retryTick !== previousRetryTick;
+
+			if (!shouldAttemptMeasure) {
 				return;
 			}
 
@@ -124,9 +146,30 @@ export const useInitialDestinationMeasurement = ({
 			});
 
 			const destinationAttached =
-				getDestination(measurePairKey, linkId) !== null;
+				getDestination(measurePairKey, linkKey) !== null;
 
 			if (destinationAttached) {
+				const linkState = pairs.get();
+				const link = getLink(measurePairKey, linkKey);
+				const sourceScreenKey = getSourceScreenKeyFromPairKey(measurePairKey);
+				const sourceEntry = getEntry(tag, sourceScreenKey);
+				const sourceEntryUsesDestinationEscapeHost =
+					sourceEntry?.handoff === true && sourceEntry.escapeClipping === true;
+				const shouldWaitForEscapeClippingHost =
+					usesEscapeClippingHost(link) ||
+					sourceEntryUsesDestinationEscapeHost ||
+					hasHandoffEscapeContinuation({
+						linkKey,
+						linkState,
+						sourceScreenKey,
+					});
+
+				if (shouldWaitForEscapeClippingHost) {
+					// Screen-level escape has a second readiness phase after destination
+					// measurement: the host must commit before the transition starts, or
+					// the payload can disappear for a frame.
+					return;
+				}
 				releaseLifecycleStartBlock();
 				viewportRetries.set(0);
 				return;
@@ -136,13 +179,13 @@ export const useInitialDestinationMeasurement = ({
 				hasGivenUp.set(1);
 				releaseLifecycleStartBlock();
 				logger.warn(
-					`Destination boundary "${linkId}" never produced a valid measurement after ${MAX_VIEWPORT_RETRIES} attempts; releasing the transition gate without it. The boundary is likely off-viewport (e.g. an inactive group member on a paged screen) or unmounted.`,
+					`Destination boundary "${linkKey}" never produced a valid measurement after ${MAX_VIEWPORT_RETRIES} attempts; releasing the transition gate without it. The boundary is likely off-viewport (e.g. an inactive group member on a paged screen) or unmounted.`,
 				);
 				return;
 			}
 
 			// Destination did not attach (malformed off-screen measurement); retry
-			// on the next tick while the lifecycle stays blocked.
+			// after the retry token advances while the lifecycle stays blocked.
 			viewportRetries.set(viewportRetries.get() + 1);
 			cancelAnimation(retryToken);
 			retryToken.set(

package/src/shared/components/boundary/hooks/{use-initial-source-measurement.ts → lifecycles/use-initial-source-measurement.ts}

@@ -1,17 +1,16 @@
 import { useAnimatedReaction, useSharedValue } from "react-native-reanimated";
-import { useDescriptorsStore } from "../../../providers/screen/descriptors";
-import { pairs } from "../../../stores/bounds/internals/state";
-import type { MeasureBoundary } from "../types";
-import { getInitialSourceCaptureSignal } from "../utils/source-signals";
+import { useDescriptorsStore } from "../../../../providers/screen/descriptors";
+import { pairs } from "../../../../stores/bounds/internals/state";
+import type { BoundTag } from "../../../../stores/bounds/types";
+import type { MeasureBoundary } from "../../types";
+import { getInitialSourceCaptureSignal } from "../../utils/source-signals";
 
 export const useInitialSourceMeasurement = (params: {
 	enabled: boolean;
 	measureBoundary: MeasureBoundary;
-	linkId: string;
-	group?: string;
-	shouldAutoMeasure: boolean;
+	boundTag: BoundTag;
 }) => {
-	const { enabled, measureBoundary, linkId, group, shouldAutoMeasure } = params;
+	const { enabled, measureBoundary, boundTag } = params;
 	const sourcePairKey = useDescriptorsStore((s) => s.derivations.sourcePairKey);
 	const lastSourceCaptureSignal = useSharedValue<string | null>(null);
 
@@ -21,10 +20,9 @@ export const useInitialSourceMeasurement = (params: {
 			return getInitialSourceCaptureSignal({
 				enabled,
 				sourcePairKey,
-				linkId,
-				group,
-				shouldAutoMeasure,
-				linkState: shouldAutoMeasure && sourcePairKey ? pairs.get() : undefined,
+				linkId: boundTag.linkKey,
+				group: boundTag.group,
+				linkState: sourcePairKey ? pairs.get() : undefined,
 			});
 		},
 		(captureSignal) => {

package/src/shared/components/boundary/hooks/{use-refresh-boundary.ts → lifecycles/use-refresh-boundary.ts}

@@ -1,23 +1,23 @@
 import { useAnimatedReaction } from "react-native-reanimated";
-import { useDescriptorsStore } from "../../../providers/screen/descriptors";
-import { AnimationStore } from "../../../stores/animation.store";
-import { pairs } from "../../../stores/bounds/internals/state";
-import type { MeasureBoundary } from "../types";
-import { getRefreshBoundarySignal } from "../utils/refresh-signals";
+import { useDescriptorsStore } from "../../../../providers/screen/descriptors";
+import { AnimationStore } from "../../../../stores/animation.store";
+import { pairs } from "../../../../stores/bounds/internals/state";
+import type { BoundTag } from "../../../../stores/bounds/types";
+import type { MeasureBoundary } from "../../types";
+import { getRefreshBoundarySignal } from "../../utils/refresh-signals";
 
 interface UseRefreshBoundaryParams {
 	enabled: boolean;
-	linkId: string;
-	group?: string;
+	boundTag: BoundTag;
 	measureBoundary: MeasureBoundary;
 }
 
 export const useRefreshBoundary = ({
 	enabled,
-	linkId,
-	group,
+	boundTag,
 	measureBoundary,
 }: UseRefreshBoundaryParams) => {
+	const { linkKey, group } = boundTag;
 	const currentScreenKey = useDescriptorsStore(
 		(s) => s.derivations.currentScreenKey,
 	);
@@ -57,7 +57,7 @@ export const useRefreshBoundary = ({
 				destinationPairKey,
 				ancestorDestinationPairKey,
 				nextScreenKey,
-				linkId,
+				linkId: linkKey,
 				group,
 				shouldRefresh: !!refreshWillAnimate.get(),
 				closing: !!refreshClosing.get(),