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

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

@@ -2,18 +2,22 @@ import {
 	type ComponentType,
 	forwardRef,
 	memo,
+	type ReactNode,
 	useImperativeHandle,
 	useMemo,
 } from "react";
-import Animated from "react-native-reanimated";
+import type { View } from "react-native";
+import Animated, { useAnimatedRef } from "react-native-reanimated";
 import { useDescriptorsStore } from "../../providers/screen/descriptors";
 import {
+	useComposedSlotStyles,
 	useSlotStackingStyles,
-	useSlotStyles,
 } from "../../providers/screen/styles";
 import { createBoundTag } from "../../stores/bounds/helpers/link-pairs.helpers";
 import { useBoundaryMeasurement } from "./hooks/use-boundary-measurement";
-import { resolveBoundaryPortal } from "./portal/resolve-portal";
+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,
@@ -22,14 +26,29 @@ 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);
@@ -48,7 +67,9 @@ export function createBoundaryComponent<P extends object>(
 			method,
 			style,
 			onPress,
-			portal: portalProp,
+			handoff,
+			escapeClipping,
+			children,
 			...rest
 		} = props as any;
 
@@ -56,7 +77,10 @@ export function createBoundaryComponent<P extends object>(
 			() => createBoundTag(String(id), group),
 			[id, group],
 		);
-		const portal = resolveBoundaryPortal(portalProp);
+		const portalRuntime = resolveBoundaryPortal({
+			handoff,
+			escapeClipping,
+		});
 
 		const currentScreenKey = useDescriptorsStore(
 			(s) => s.derivations.currentScreenKey,
@@ -68,9 +92,12 @@ export function createBoundaryComponent<P extends object>(
 		// 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 = useSlotStyles(boundTag.tag);
+		const associatedStyles = useComposedSlotStyles(boundTag.tag, style);
 		const associatedStackingStyles = useSlotStackingStyles(boundTag.tag);
+		const rootPlaceholderRef = useAnimatedRef<View>();
 
 		const {
 			ref,
@@ -80,13 +107,11 @@ export function createBoundaryComponent<P extends object>(
 			targetPreparedStyles,
 		} = useBoundaryRootState({
 			boundTag,
-			portal,
-			associatedTargetStyles: shouldAttachAssociatedStyles
-				? associatedStyles
-				: undefined,
+			portalRuntime,
+			rootMeasurementRef: canPortalRoot ? rootPlaceholderRef : undefined,
 		});
 
-		const { onPress: resolvedOnPress } = useBoundaryMeasurement({
+		useBoundaryMeasurement({
 			boundTag,
 			enabled,
 			runtimeEnabled,
@@ -94,40 +119,79 @@ export function createBoundaryComponent<P extends object>(
 			measuredRef,
 			style,
 			targetPreparedStyles,
-			portal,
-			shouldAutoMeasure,
+			handoff: portalRuntime.handoff,
+			escapeClipping: portalRuntime.escapeClipping,
 			config: { anchor, scaleMode, target, method },
-			onPress,
 		});
 
 		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; otherwise the root wears the full style.
+		// 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
-				: associatedStyles
+				: 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,
+		);
 
 		return (
 			<BoundaryRootProvider value={contextValue}>
-				<AnimatedComponent
-					{...rest}
-					ref={ref}
-					style={[style, attachedStyle]}
-					onPress={resolvedOnPress}
-					collapsable={false}
-				/>
+				{shouldPortalRoot ? (
+					<Portal
+						id={boundTag.tag}
+						handoff={portalRuntime.handoff}
+						escapeClipping={portalRuntime.escapeClipping}
+						placeholderRef={rootPlaceholderRef}
+						placeholderChildren={
+							portalRuntime.handoff ? localPortalHost : undefined
+						}
+					>
+						{boundaryRoot}
+					</Portal>
+				) : (
+					boundaryRoot
+				)}
 			</BoundaryRootProvider>
 		);
 	});
 
 	// The HOC's runtime identity (animated + memoized forwardRef) is not
 	// expressible against the public boundary props, so assert it here.
-	return memo(
-		Animated.createAnimatedComponent(Inner),
-	) as unknown as React.MemoExoticComponent<
+	return memo(Inner) as unknown as React.MemoExoticComponent<
 		React.ForwardRefExoticComponent<
 			BoundaryComponentProps<P> &
 				React.RefAttributes<React.ComponentRef<typeof Wrapped>>

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

@@ -3,17 +3,26 @@ 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";
+} 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 } = params;
+	const {
+		enabled,
+		boundTag,
+		currentScreenKey,
+		boundaryConfig,
+		handoff,
+		escapeClipping,
+	} = params;
 	const { tag } = boundTag;
 
 	useLayoutEffect(() => {
@@ -21,10 +30,12 @@ export const useBoundaryPresence = (params: {
 
 		runOnUI(setEntry)(tag, currentScreenKey, {
 			boundaryConfig,
+			handoff: handoff ? true : null,
+			escapeClipping: escapeClipping ? true : null,
 		});
 
 		return () => {
 			runOnUI(removeEntry)(tag, currentScreenKey);
 		};
-	}, [enabled, tag, currentScreenKey, boundaryConfig]);
+	}, [enabled, tag, currentScreenKey, boundaryConfig, handoff, escapeClipping]);
 };

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

@@ -5,18 +5,27 @@ 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 type { BoundTag } from "../../../stores/bounds/types";
+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 = 100;
 /**
@@ -37,7 +46,7 @@ export const useInitialDestinationMeasurement = ({
 	enabled,
 	measureBoundary,
 }: UseInitialDestinationMeasurementParams) => {
-	const { linkKey, group } = boundTag;
+	const { tag, linkKey, group } = boundTag;
 	const currentScreenKey = useDescriptorsStore(
 		(s) => s.derivations.currentScreenKey,
 	);
@@ -109,9 +118,6 @@ export const useInitialDestinationMeasurement = ({
 		([measurePairKey, retryTick], previous) => {
 			"worklet";
 			if (!measurePairKey) {
-				releaseLifecycleStartBlock();
-				viewportRetries.set(0);
-				hasGivenUp.set(0);
 				return;
 			}
 
@@ -143,6 +149,27 @@ export const useInitialDestinationMeasurement = ({
 				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;

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 { BoundTag } from "../../../stores/bounds/types";
-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;
 	boundTag: BoundTag;
-	shouldAutoMeasure: boolean;
 }) => {
-	const { enabled, measureBoundary, boundTag, shouldAutoMeasure } = params;
+	const { enabled, measureBoundary, boundTag } = params;
 	const sourcePairKey = useDescriptorsStore((s) => s.derivations.sourcePairKey);
 	const lastSourceCaptureSignal = useSharedValue<string | null>(null);
 
@@ -23,8 +22,7 @@ export const useInitialSourceMeasurement = (params: {
 				sourcePairKey,
 				linkId: boundTag.linkKey,
 				group: boundTag.group,
-				shouldAutoMeasure,
-				linkState: shouldAutoMeasure && sourcePairKey ? pairs.get() : undefined,
+				linkState: sourcePairKey ? pairs.get() : undefined,
 			});
 		},
 		(captureSignal) => {

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

@@ -1,10 +1,10 @@
 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 { BoundTag } from "../../../stores/bounds/types";
-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;

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

@@ -1,17 +1,14 @@
-import { useCallback, useMemo } from "react";
+import { useMemo } from "react";
 import type { View } from "react-native";
 import type { AnimatedRef, StyleProps } from "react-native-reanimated";
-import { runOnUI } from "react-native-reanimated";
-import { createPendingPairKey } from "../../../stores/bounds/helpers/link-pairs.helpers";
 import type { BoundTag } from "../../../stores/bounds/types";
 import { prepareStyleForBounds } from "../../../utils/bounds/helpers/styles/styles";
-import { resolvePortalHost } from "../portal/resolve-portal";
-import type { BoundaryConfigProps, BoundaryPortal } from "../types";
-import { useBoundaryPresence } from "./use-boundary-presence";
-import { useInitialDestinationMeasurement } from "./use-initial-destination-measurement";
-import { useInitialSourceMeasurement } from "./use-initial-source-measurement";
+import type { BoundaryConfigProps } 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";
+import { useRefreshBoundary } from "./lifecycles/use-refresh-boundary";
 import { useMeasurer } from "./use-measurer";
-import { useRefreshBoundary } from "./use-refresh-boundary";
 
 interface UseBoundaryMeasurementParams {
 	boundTag: BoundTag;
@@ -25,17 +22,15 @@ interface UseBoundaryMeasurementParams {
 	/** Root's own style; ignored when a nested target supplies its own. */
 	style?: unknown;
 	targetPreparedStyles?: StyleProps;
-	portal?: BoundaryPortal;
-	shouldAutoMeasure: boolean;
+	handoff: boolean;
+	escapeClipping: boolean;
 	config: BoundaryConfigProps;
-	onPress?: (...args: unknown[]) => void;
 }
 
 /**
  * Owns the full measurement lifecycle for a boundary: builds the measurer,
  * registers presence, runs the initial source/destination + refresh reactions,
- * and returns the press-priority `onPress`. The component never touches the
- * measurer itself.
+ * and keeps the component itself away from the measurer.
  */
 export const useBoundaryMeasurement = ({
 	boundTag,
@@ -45,10 +40,9 @@ export const useBoundaryMeasurement = ({
 	measuredRef,
 	style,
 	targetPreparedStyles,
-	portal,
-	shouldAutoMeasure,
+	handoff,
+	escapeClipping,
 	config,
-	onPress,
 }: UseBoundaryMeasurementParams) => {
 	const { anchor, scaleMode, target, method } = config;
 	const boundaryConfig = useMemo<BoundaryConfigProps>(
@@ -62,15 +56,14 @@ export const useBoundaryMeasurement = ({
 	);
 	const preparedStyles = targetPreparedStyles ?? rootPreparedStyles;
 
-	const portalHost = resolvePortalHost(portal);
-
 	const measureBoundary = useMeasurer({
 		enabled,
 		boundTag,
 		currentScreenKey,
 		preparedStyles,
 		measuredAnimatedRef: measuredRef,
-		portalHost,
+		handoff,
+		escapeClipping,
 	});
 
 	// Register/unregister this boundary in the presence map so source/destination
@@ -80,18 +73,14 @@ export const useBoundaryMeasurement = ({
 		boundTag,
 		currentScreenKey,
 		boundaryConfig,
+		handoff,
+		escapeClipping,
 	});
 
-	// Passive auto-measurement only applies to non-pressable boundaries; pressable
-	// ones capture their source on press (see handlePress below).
-	const shouldPassivelyMeasureSource =
-		shouldAutoMeasure && typeof onPress !== "function";
-
 	useInitialSourceMeasurement({
 		enabled: runtimeEnabled,
 		measureBoundary,
 		boundTag,
-		shouldAutoMeasure: shouldPassivelyMeasureSource,
 	});
 
 	useInitialDestinationMeasurement({
@@ -105,23 +94,4 @@ export const useBoundaryMeasurement = ({
 		boundTag,
 		measureBoundary,
 	});
-
-	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],
-	);
-
-	return {
-		onPress: typeof onPress === "function" ? handlePress : undefined,
-	};
 };

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

@@ -8,13 +8,9 @@ import {
 } from "react-native-reanimated";
 import { applyMeasuredBoundsWrites } from "../../../providers/helpers/measured-bounds-writes";
 import { useOriginContext } from "../../../providers/screen/origin.provider";
-import type {
-	BoundsPortalAttachTarget,
-	BoundTag,
-} from "../../../stores/bounds/types";
+import type { BoundTag } from "../../../stores/bounds/types";
 import { ScrollStore } from "../../../stores/scroll.store";
 import { SystemStore } from "../../../stores/system.store";
-import { getActiveScrollHost } from "../portal/stores/host-registry.store";
 import type { MeasureBoundary } from "../types";
 import {
 	attachScrollSnapshotToMeasuredBounds,
@@ -29,7 +25,8 @@ interface UseMeasurerParams {
 	currentScreenKey: string;
 	preparedStyles: StyleProps;
 	measuredAnimatedRef: AnimatedRef<View>;
-	portalHost?: BoundsPortalAttachTarget;
+	handoff: boolean;
+	escapeClipping: boolean;
 }
 
 export const useMeasurer = ({
@@ -38,7 +35,8 @@ export const useMeasurer = ({
 	currentScreenKey,
 	preparedStyles,
 	measuredAnimatedRef,
-	portalHost,
+	handoff,
+	escapeClipping,
 }: UseMeasurerParams): MeasureBoundary => {
 	const { width: viewportWidth, height: viewportHeight } =
 		useWindowDimensions();
@@ -94,10 +92,6 @@ export const useMeasurer = ({
 				normalizedMeasured,
 				scrollMetadata.get(),
 			);
-			const sourceHost =
-				target.type === "source"
-					? (getActiveScrollHost(currentScreenKey) ?? undefined)
-					: undefined;
 
 			applyMeasuredBoundsWrites({
 				entryTag: boundTag.tag,
@@ -107,8 +101,8 @@ export const useMeasurer = ({
 				measured: measuredWithScroll,
 				preparedStyles,
 				linkWrite: target,
-				portalHost,
-				sourceHost,
+				handoff,
+				escapeClipping,
 			});
 		},
 		[
@@ -117,7 +111,8 @@ export const useMeasurer = ({
 			currentScreenKey,
 			preparedStyles,
 			measuredAnimatedRef,
-			portalHost,
+			handoff,
+			escapeClipping,
 			viewportWidth,
 			viewportHeight,
 			scrollState,