react-native-screen-transitions 3.9.0-alpha.2 → 3.9.0-beta.0

package/src/shared/components/boundary/portal/components/portal.tsx

@@ -11,37 +11,39 @@ import type { View } from "react-native";
 import Animated, {
 	type AnimatedRef,
 	runOnJS,
+	runOnUI,
 	useAnimatedProps,
 	useAnimatedReaction,
-	useAnimatedStyle,
 	useSharedValue,
 } from "react-native-reanimated";
+import { EPSILON } from "../../../../constants";
 import { useDescriptorsStore } from "../../../../providers/screen/descriptors";
 import { useScreenSlots } from "../../../../providers/screen/styles";
+import { useRegisteredScreenSlots } from "../../../../providers/screen/styles/stores/slot-references.store";
 import { AnimationStore } from "../../../../stores/animation.store";
-import { getLinkKeyFromTag } from "../../../../stores/bounds/helpers/link-pairs.helpers";
-import { getLink } from "../../../../stores/bounds/internals/links";
 import { pairs } from "../../../../stores/bounds/internals/state";
-import { createTransitionAwareComponent } from "../../../create-transition-aware-component";
-import type { BoundaryPortal, BoundaryPortalAttachTarget } from "../../types";
-import {
-	getHostCapturesScroll,
-	useActiveHostKey,
-} from "../stores/host-registry.store";
+import { logger } from "../../../../utils/logger";
+import { usePlaceholderStyles } from "../hooks/use-placeholder-styles";
+import { useActiveHostKey } from "../stores/host-registry.store";
 import {
+	dropStalePortalBoundaryHosts,
 	mountPortalBoundaryHost,
 	unmountPortalBoundaryHost,
 } from "../stores/portal-boundary-host.store";
 import { isTeleportAvailable, NativePortal } from "../teleport";
 import {
-	type PortalAttachment,
-	resolvePortalAttachmentTargets,
-} from "../utils/attachment";
-import {
+	createBoundaryLocalPortalHostName,
 	createPortalBoundaryHostName,
 	PORTAL_HOST_NAME_RESET_VALUE,
 } from "../utils/naming";
-import { isTeleportEnabled } from "../utils/teleport-control";
+import {
+	canSwitchBoundaryLocalHandoffImmediately,
+	type PortalOwnershipSignal,
+	resolveBoundaryPortalOwnership,
+} from "../utils/ownership";
+import { shallowEqual } from "../utils/shallow-equal";
+import { shouldAttachBoundaryPortal } from "../utils/teleport-control";
+import { resolveNextVisiblePortalHostName } from "../utils/visible-host";
 
 type NullableHostNamePortalProps = Omit<
 	ComponentProps<NonNullable<typeof NativePortal>>,
@@ -50,8 +52,8 @@ type NullableHostNamePortalProps = Omit<
 	hostName?: string | null;
 };
 
-const TransitionAwareTeleport = NativePortal
-	? createTransitionAwareComponent(
+const AnimatedNativePortal = NativePortal
+	? Animated.createAnimatedComponent(
 			NativePortal as ComponentType<NullableHostNamePortalProps>,
 		)
 	: null;
@@ -59,7 +61,8 @@ const TransitionAwareTeleport = NativePortal
 interface PortalProps {
 	id?: string;
 	children: ReactNode;
-	mode?: BoundaryPortal;
+	handoff?: boolean;
+	escapeClipping?: boolean;
 	/**
 	 * Ref to the layout-preserving placeholder wrapper. Boundaries measure
 	 * this instead of teleported content — the placeholder keeps the source
@@ -67,214 +70,340 @@ interface PortalProps {
 	 * host.
 	 */
 	placeholderRef?: AnimatedRef<View>;
+	placeholderChildren?: ReactNode;
 }
 
 export const Portal = memo(function Portal({
-	id = "my-id",
+	id,
 	children,
-	mode = false,
+	handoff = false,
+	escapeClipping = false,
 	placeholderRef,
+	placeholderChildren,
 }: PortalProps) {
-	// Teleporting requires the optional `react-native-teleport` peer. Without it,
-	// a portal-enabled boundary degrades to inline rendering (the `return
-	// children` path below).
-	const isPortalEnabled = !!mode && isTeleportAvailable;
-	const portalAttachTarget: BoundaryPortalAttachTarget =
-		!mode || mode === true
-			? "current-screen"
-			: (mode.attachTo ?? "current-screen");
-	const { slotsMap } = useScreenSlots();
+	// Teleporting requires the optional `react-native-teleport` peer and a stable
+	// `id` to name the boundary host. Missing either degrades to inline rendering
+	// (the `return children` path below).
+	const isPortalEnabled =
+		(handoff || escapeClipping) && isTeleportAvailable && id !== undefined;
+
+	if (__DEV__ && (handoff || escapeClipping) && id === undefined) {
+		logger.warnOnce(
+			"portal:missing-id",
+			"A handoff or escapeClipping boundary was rendered without an id; rendering inline.",
+		);
+	}
+	const boundaryId = id ?? "";
+	const ownScreenSlots = useScreenSlots();
 	const sourcePairKey = useDescriptorsStore((s) => s.derivations.sourcePairKey);
 	const currentScreenKey = useDescriptorsStore(
 		(s) => s.derivations.currentScreenKey,
 	);
 
-	const nextScreenKey = useDescriptorsStore((s) => s.derivations.nextScreenKey);
+	const [ownership, setOwnership] = useState<Extract<
+		PortalOwnershipSignal,
+		{ status: "complete" }
+	> | null>(null);
 
-	const [attachment, setAttachment] = useState<PortalAttachment | null>(
-		PORTAL_HOST_NAME_RESET_VALUE,
+	const styleOwnerScreenKey = ownership?.ownerScreenKey ?? currentScreenKey;
+	const ownerScreenSlots = useRegisteredScreenSlots(styleOwnerScreenKey);
+	const activeScreenSlots = ownerScreenSlots ?? ownScreenSlots;
+	const {
+		localStylesMaps: activeLocalStylesMaps,
+		nextInterpolatorReady: activeNextInterpolatorReady,
+		slotsMap: activeSlotsMap,
+	} = activeScreenSlots;
+	const requestedPortalHostName = useSharedValue<string | null>(null);
+	const visiblePortalHostName = useSharedValue<string | null>(null);
+	const canSwitchPortalHostImmediately = useSharedValue(0);
+
+	const targetScreenKey = ownership ? ownership.hostScreenKey : null;
+	const settledHostScreenKey = ownership?.hostScreenKey ?? null;
+	const settledHostProgress = AnimationStore.getValue(
+		settledHostScreenKey ?? currentScreenKey,
+		"progressSettled",
 	);
-	const attachedHostName = useSharedValue<string | null>(
-		PORTAL_HOST_NAME_RESET_VALUE,
+	const settledHostAnimating = AnimationStore.getValue(
+		settledHostScreenKey ?? currentScreenKey,
+		"progressAnimating",
 	);
-	const placeholderWidth = useSharedValue(0);
-	const placeholderHeight = useSharedValue(0);
-
-	const { progressScreenKey, targetScreenKey } = resolvePortalAttachmentTargets(
-		{
-			attachment,
-			currentScreenKey,
-			nextScreenKey,
-			portalAttachTarget,
-			sourcePairKey,
-		},
+	const settledHostClosing = AnimationStore.getValue(
+		settledHostScreenKey ?? currentScreenKey,
+		"closing",
+	);
+	const settledHostVisualProgress = AnimationStore.getValue(
+		settledHostScreenKey ?? currentScreenKey,
+		"visualProgress",
 	);
-	const activeHostKey = useActiveHostKey(targetScreenKey);
-	const activeHostCapturesScroll = activeHostKey
-		? getHostCapturesScroll(activeHostKey)
-		: false;
-	const progress = AnimationStore.getValue(
-		progressScreenKey ?? "",
-		"transitionProgress",
+
+	const activeHostKey = useActiveHostKey(
+		escapeClipping ? targetScreenKey : null,
 	);
-	const closing = AnimationStore.getValue(progressScreenKey ?? "", "closing");
+	const boundaryLocalHostName =
+		handoff && !escapeClipping && targetScreenKey
+			? createBoundaryLocalPortalHostName(targetScreenKey, boundaryId)
+			: null;
 
-	const updatePortalAttachment = useCallback(
-		(matchedScreenKey: string | null, pairKey?: string) => {
-			if (matchedScreenKey && pairKey) {
-				setAttachment((current) => {
+	const updatePortalOwnership = useCallback(
+		(
+			hostScreenKey: string | null,
+			ownerPairKey?: string,
+			ownerScreenKey?: string,
+		) => {
+			if (hostScreenKey && ownerPairKey && ownerScreenKey) {
+				setOwnership((current) => {
 					if (
-						current?.matchedScreenKey === matchedScreenKey &&
-						current.pairKey === pairKey
+						current?.hostScreenKey === hostScreenKey &&
+						current.ownerPairKey === ownerPairKey &&
+						current.ownerScreenKey === ownerScreenKey
 					) {
 						return current;
 					}
 
 					return {
-						matchedScreenKey,
-						pairKey,
+						hostScreenKey,
+						ownerPairKey,
+						ownerScreenKey,
+						status: "complete",
 					};
 				});
 				return;
 			}
 
-			setAttachment((current) => (current ? null : current));
+			setOwnership((current) => (current ? null : current));
 		},
 		[],
 	);
 
 	useLayoutEffect(() => {
-		if (!isPortalEnabled || !attachment || !activeHostKey || !targetScreenKey) {
-			attachedHostName.set(PORTAL_HOST_NAME_RESET_VALUE);
+		if (!isPortalEnabled || !ownership || !targetScreenKey) {
+			requestedPortalHostName.set(null);
+			visiblePortalHostName.set(null);
+			unmountPortalBoundaryHost(boundaryId);
 			return;
 		}
 
+		if (boundaryLocalHostName) {
+			requestedPortalHostName.set(boundaryLocalHostName);
+			unmountPortalBoundaryHost(boundaryId);
+			return;
+		}
+
+		if (!escapeClipping || !activeHostKey) {
+			requestedPortalHostName.set(null);
+			visiblePortalHostName.set(null);
+			unmountPortalBoundaryHost(boundaryId);
+			return;
+		}
+
+		const portalHostName = createPortalBoundaryHostName(
+			activeHostKey,
+			boundaryId,
+			ownership.ownerPairKey,
+		);
+
 		mountPortalBoundaryHost({
-			boundaryId: id,
-			capturesScroll: activeHostCapturesScroll,
+			boundaryId,
+			escapeClipping,
 			hostKey: activeHostKey,
-			pairKey: attachment.pairKey,
+			localStylesMaps: activeLocalStylesMaps,
+			pairKey: ownership.ownerPairKey,
+			portalHostName,
 			screenKey: targetScreenKey,
+			slotsMap: activeSlotsMap,
 		});
 
-		// The native registry parks portals whose host has not registered yet and
-		// re-parents the moment it does, so the host name can be handed over
-		// immediately — ordering belongs to the registry, not to frame counting.
-		// hostName rides animated props, so the handover needs no React commit.
-		attachedHostName.set(createPortalBoundaryHostName(activeHostKey, id));
+		// Request the new receiver immediately, but keep the currently visible
+		// receiver until the new interpolator is ready. This avoids a no-host gap
+		// during A -> B(closing) -> C(opening) spam retargets.
+		requestedPortalHostName.set(portalHostName);
 	}, [
 		activeHostKey,
-		activeHostCapturesScroll,
-		attachedHostName,
-		attachment,
-		id,
+		boundaryId,
+		escapeClipping,
 		isPortalEnabled,
+		activeLocalStylesMaps,
+		activeSlotsMap,
+		ownership,
+		boundaryLocalHostName,
+		requestedPortalHostName,
 		targetScreenKey,
+		visiblePortalHostName,
 	]);
 
 	useLayoutEffect(() => {
 		return () => {
-			attachedHostName.set(PORTAL_HOST_NAME_RESET_VALUE);
-			unmountPortalBoundaryHost(id);
+			requestedPortalHostName.set(null);
+			visiblePortalHostName.set(null);
+			unmountPortalBoundaryHost(boundaryId);
 		};
-	}, [attachedHostName, id]);
+	}, [boundaryId, requestedPortalHostName, visiblePortalHostName]);
 
 	useAnimatedReaction(
 		() => {
 			"worklet";
 			if (!isPortalEnabled || !sourcePairKey) {
-				return null;
+				return {
+					hostScreenKey: null,
+					ownerPairKey: sourcePairKey,
+					ownerScreenKey: null,
+					status: "clear",
+				};
 			}
 
-			pairs.get();
-			// Strict per-member lookup: getResolvedLink's group fallback borrows
-			// the initial member's link for style resolution, which would make
-			// every inactive group member's portal see a "complete" link and
-			// attach. A portal may only teleport on its OWN member's link.
-			const link = getLink(sourcePairKey, id);
-
-			if (link?.status !== "complete") {
-				return null;
+			return resolveBoundaryPortalOwnership({
+				boundaryId,
+				currentScreenKey,
+				escapeClipping,
+				handoff,
+				isSettledHostClosingComplete:
+					!!settledHostClosing.get() &&
+					settledHostVisualProgress.get() <= EPSILON,
+				isSettledHostReady:
+					settledHostProgress.get() === 1 && settledHostAnimating.get() === 0,
+				pairsState: pairs.get(),
+				settledHostScreenKey,
+				sourcePairKey,
+			});
+		},
+		(signal, previousSignal) => {
+			"worklet";
+			if (shallowEqual(previousSignal, signal)) {
+				return;
 			}
 
-			// Grouped portals teleport only while their member is the group's
-			// active id — retargeting detaches the previous member (its content
-			// returns home) and attaches the new one. Exactly one grouped member
-			// is teleported at a time.
-			if (link.group) {
-				const activeId =
-					pairs.get()[sourcePairKey]?.groups?.[link.group]?.activeId;
+			if (!handoff || escapeClipping) {
+				canSwitchPortalHostImmediately.set(0);
+			} else if (signal.status === "pending") {
+				canSwitchPortalHostImmediately.set(0);
+				return;
+			} else {
+				const hostScreenKey =
+					signal.status === "complete" ? signal.hostScreenKey : null;
+				let previousOwnerPairKey: string | undefined;
 
-				if (activeId && activeId !== getLinkKeyFromTag(id)) {
-					return null;
+				if (previousSignal?.status === "complete") {
+					previousOwnerPairKey = previousSignal.ownerPairKey ?? undefined;
+				}
+				const canSwitchImmediately = canSwitchBoundaryLocalHandoffImmediately({
+					hostScreenKey,
+					ownerPairKey:
+						signal.status === "complete" ? signal.ownerPairKey : undefined,
+					previousOwnerPairKey,
+				});
+
+				canSwitchPortalHostImmediately.set(canSwitchImmediately ? 1 : 0);
+
+				if (canSwitchImmediately && hostScreenKey) {
+					const hostName = createBoundaryLocalPortalHostName(
+						hostScreenKey,
+						boundaryId,
+					);
+					requestedPortalHostName.set(hostName);
+					visiblePortalHostName.set(hostName);
 				}
 			}
 
-			return link.destination.screenKey;
+			runOnJS(updatePortalOwnership)(
+				signal.hostScreenKey,
+				signal.ownerPairKey,
+				signal.ownerScreenKey ?? undefined,
+			);
+		},
+	);
+
+	useAnimatedReaction(
+		() => {
+			"worklet";
+			const slot = activeSlotsMap.get()[boundaryId];
+			const teleport = slot?.props?.teleport;
+			const shouldTeleport = shouldAttachBoundaryPortal({
+				enabled: isPortalEnabled,
+				teleport,
+			});
+			const requestedName = requestedPortalHostName.get();
+			const visibleName = visiblePortalHostName.get();
+			const isInterpolatorReady = activeNextInterpolatorReady.get();
+			const nextVisibleName = resolveNextVisiblePortalHostName({
+				canSwitchImmediately: canSwitchPortalHostImmediately.get() === 1,
+				isInterpolatorReady: isInterpolatorReady === 1,
+				requestedName,
+				shouldTeleport,
+				visibleName,
+			});
+
+			return {
+				isInterpolatorReady,
+				nextVisibleName,
+				requestedName,
+				shouldTeleport,
+				teleport,
+				visibleName,
+			};
 		},
-		(matchedScreenKey, previousMatchedScreenKey) => {
+		(state, previousState) => {
 			"worklet";
-			if (matchedScreenKey === previousMatchedScreenKey) {
+			if (shallowEqual(previousState, state)) {
 				return;
 			}
 
-			runOnJS(updatePortalAttachment)(matchedScreenKey, sourcePairKey);
+			if (state.nextVisibleName !== state.visibleName) {
+				visiblePortalHostName.set(state.nextVisibleName);
+				return;
+			}
+
+			// Visible receiver has caught up to the request: GC the superseded hosts.
+			if (state.visibleName && state.visibleName === state.requestedName) {
+				runOnJS(dropStalePortalBoundaryHosts)({
+					boundaryId,
+					keepPortalHostName: state.visibleName,
+				});
+			}
 		},
 	);
 
 	const teleportProps = useAnimatedProps(() => {
 		"worklet";
 
-		// Opening waits for the destination transition to start so content is not
-		// re-parented before the host is visually ready. Closing stays attached
-		// through progress 0 so the final frame can land in the matched host.
-		const attachThreshold = closing.get() === 1 ? 0 : 0.001;
-		const { teleport, ...slotProps } = slotsMap.get()[id]?.props ?? {};
-		const shouldTeleport = isTeleportEnabled(teleport);
+		const slot = activeSlotsMap.get()[boundaryId];
+		const { teleport, ...slotProps } = slot?.props ?? {};
+		const shouldTeleport = shouldAttachBoundaryPortal({
+			enabled: isPortalEnabled,
+			teleport,
+		});
+		const visibleName = visiblePortalHostName.get();
 
 		return {
 			// Preserve portal slot props from the interpolator while keeping
-			// hostName owned by the attachment gate below.
+			// hostName owned by the attachment gate below. Handoff
+			// waits until the receiving interpolator owns styles for the same host;
+			// after that, it stays attached until teleport is disabled or retargeted.
 			...slotProps,
 			hostName:
-				shouldTeleport && progress.get() >= attachThreshold
-					? attachedHostName.get()
+				shouldTeleport && visibleName
+					? visibleName
 					: PORTAL_HOST_NAME_RESET_VALUE,
 		};
 	});
 
-	// Pin the placeholder to its measured size while content lives in the host,
-	// in the same UI frame the host name flips — no commit in between. Until the
-	// first layout lands (dims 0) sizing stays natural so an instant attach
-	// cannot collapse the slot.
-	const placeholderStyle = useAnimatedStyle(() => {
-		"worklet";
-		const hostName = attachedHostName.get();
-		const isAttached = hostName !== null;
-		const width = placeholderWidth.get();
-		const height = placeholderHeight.get();
-
-		if (!isAttached || width === 0) {
-			return { width: "auto", height: "auto" } as const;
-		}
-
-		return { width, height };
+	const { handleOnLayout, placeholderStyle } = usePlaceholderStyles({
+		visiblePortalHostName,
 	});
 
-	if (isPortalEnabled && TransitionAwareTeleport) {
+	if (isPortalEnabled && AnimatedNativePortal) {
 		return (
 			<Animated.View
 				ref={placeholderRef}
-				onLayout={(event) => {
-					placeholderWidth.set(event.nativeEvent.layout.width);
-					placeholderHeight.set(event.nativeEvent.layout.height);
-				}}
+				onLayout={({ nativeEvent: { layout } }) =>
+					runOnUI(handleOnLayout)(layout)
+				}
 				style={placeholderStyle}
 				collapsable={false}
 			>
-				<TransitionAwareTeleport animatedProps={teleportProps} name={id}>
-					<Animated.View style={placeholderStyle}>{children}</Animated.View>
-				</TransitionAwareTeleport>
+				{placeholderChildren}
+				<AnimatedNativePortal animatedProps={teleportProps} name={boundaryId}>
+					{children}
+				</AnimatedNativePortal>
 			</Animated.View>
 		);
 	}

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

@@ -1,12 +1,15 @@
 import { useLayoutEffect, useState } from "react";
 import type { View } from "react-native";
 import {
+	cancelAnimation,
 	measure,
 	runOnJS,
 	runOnUI,
 	useAnimatedReaction,
 	useAnimatedRef,
 	useSharedValue,
+	withDelay,
+	withTiming,
 } from "react-native-reanimated";
 import { useOriginContext } from "../../../../providers/screen/origin.provider";
 import { ScrollStore } from "../../../../stores/scroll.store";
@@ -19,6 +22,8 @@ import {
 	setPortalHostBounds,
 } from "../stores/host-bounds.store";
 
+const HOST_MEASUREMENT_RETRY_DELAY_MS = 16;
+
 type UseHostMeasurementParams = {
 	capturesScroll: boolean;
 	enabled: boolean;
@@ -37,6 +42,7 @@ export const useHostMeasurement = ({
 	const [canRenderHosts, setCanRenderHosts] = useState<boolean>(false);
 	const { originRef } = useOriginContext();
 	const hasMeasuredHost = useSharedValue(false);
+	const retryToken = useSharedValue(0);
 
 	useAnimatedReaction(
 		() => {
@@ -45,10 +51,17 @@ export const useHostMeasurement = ({
 				return null;
 			}
 
-			return hasMeasuredHost.get();
+			return [hasMeasuredHost.get(), retryToken.get()] as const;
 		},
-		(hasAlreadyMeasured) => {
+		(state) => {
 			"worklet";
+			if (!state) {
+				cancelAnimation(retryToken);
+				return;
+			}
+
+			const [hasAlreadyMeasured] = state;
+
 			if (!enabled || hasAlreadyMeasured) {
 				return;
 			}
@@ -57,9 +70,17 @@ export const useHostMeasurement = ({
 			const measuredOrigin = measure(originRef);
 
 			if (!measured || !measuredOrigin) {
+				cancelAnimation(retryToken);
+				retryToken.set(
+					withDelay(
+						HOST_MEASUREMENT_RETRY_DELAY_MS,
+						withTiming(retryToken.get() + 1, { duration: 0 }),
+					),
+				);
 				return;
 			}
 
+			cancelAnimation(retryToken);
 			hasMeasuredHost.set(true);
 
 			// A measurement taken mid rubber-band would bake the transient

package/src/shared/components/boundary/portal/hooks/use-placeholder-styles.ts

@@ -0,0 +1,55 @@
+import { useCallback } from "react";
+import type { LayoutRectangle } from "react-native";
+import {
+	type SharedValue,
+	useAnimatedStyle,
+	useSharedValue,
+} from "react-native-reanimated";
+
+interface UsePlaceholderProps {
+	visiblePortalHostName: SharedValue<string | null>;
+}
+
+export const usePlaceholderStyles = ({
+	visiblePortalHostName,
+}: UsePlaceholderProps) => {
+	const placeholderWidth = useSharedValue(0);
+	const placeholderHeight = useSharedValue(0);
+	// Pin the placeholder to its measured size while content lives in the host,
+	// in the same UI frame the host name flips — no commit in between. Until the
+	// first layout lands (dims 0) sizing stays natural so an instant attach
+	// cannot collapse the slot.
+	const placeholderStyle = useAnimatedStyle(() => {
+		"worklet";
+		const isAttached = visiblePortalHostName.get() !== null;
+		const width = placeholderWidth.get();
+		const height = placeholderHeight.get();
+
+		if (!isAttached || width === 0) {
+			return { width: "auto", height: "auto" } as const;
+		}
+
+		return { width, height };
+	});
+
+	const handleOnLayout = useCallback(
+		(layout: LayoutRectangle) => {
+			"worklet";
+			const { width, height } = layout;
+			if (width === 0 || height === 0) {
+				return;
+			}
+
+			const hasValidDimensions =
+				placeholderHeight.get() !== 0 && placeholderWidth.get() !== 0;
+
+			if (!hasValidDimensions) {
+				placeholderWidth.set(width);
+				placeholderHeight.set(height);
+			}
+		},
+		[placeholderHeight, placeholderWidth],
+	);
+
+	return { placeholderStyle, handleOnLayout };
+};