react-native-screen-transitions 3.9.0-beta.1 → 3.9.0-beta.2

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

@@ -0,0 +1,250 @@
+import { useCallback, useLayoutEffect, useRef, useState } from "react";
+import {
+	runOnJS,
+	useAnimatedProps,
+	useAnimatedReaction,
+	useSharedValue,
+} from "react-native-reanimated";
+import { useDescriptorsStore } from "../../../../../../providers/screen/descriptors";
+import { useScreenSlots } from "../../../../../../providers/screen/styles";
+import { pairs } from "../../../../../../stores/bounds/internals/state";
+import { PORTAL_HOST_NAME_RESET_VALUE } from "../../../utils/naming";
+import {
+	type PortalOwnershipSignal,
+	resolveBoundaryPortalOwnership,
+} from "../../../utils/ownership";
+import { shallowEqual } from "../../../utils/shallow-equal";
+import { shouldAttachBoundaryPortal } from "../../../utils/teleport-control";
+import { resolveNextVisiblePortalHostName } from "../../../utils/visible-host";
+import { createBoundaryPortalHostName } from "../helpers/host-name";
+import { useActiveHostKey } from "../stores/host-registry.store";
+import {
+	dropStalePortalBoundaryHosts,
+	mountPortalBoundaryHost,
+	unmountPortalBoundaryHostByName,
+} from "../stores/portal-boundary-host.store";
+
+interface UseBoundaryPortalAttachmentParams {
+	boundaryId: string;
+	enabled: boolean;
+}
+
+export const useBoundaryPortalAttachment = ({
+	boundaryId,
+	enabled,
+}: UseBoundaryPortalAttachmentParams) => {
+	const sourcePairKey = useDescriptorsStore((s) => s.derivations.sourcePairKey);
+	const currentScreenKey = useDescriptorsStore(
+		(s) => s.derivations.currentScreenKey,
+	);
+	const { localStylesMaps, nextInterpolatorReady, slotsMap } = useScreenSlots();
+	const [ownership, setOwnership] = useState<Extract<
+		PortalOwnershipSignal,
+		{ status: "complete" }
+	> | null>(null);
+	const requestedPortalHostName = useSharedValue<string | null>(null);
+	const visiblePortalHostName = useSharedValue<string | null>(null);
+	const mountedPortalBoundaryHostNamesRef = useRef(new Set<string>());
+	const escapeHostKey = useActiveHostKey(enabled ? currentScreenKey : null);
+
+	const updatePortalOwnership = useCallback(
+		(
+			hostScreenKey: string | null,
+			ownerPairKey?: string,
+			ownerScreenKey?: string,
+		) => {
+			if (hostScreenKey && ownerPairKey && ownerScreenKey) {
+				setOwnership((current) => {
+					if (
+						current?.hostScreenKey === hostScreenKey &&
+						current.ownerPairKey === ownerPairKey &&
+						current.ownerScreenKey === ownerScreenKey
+					) {
+						return current;
+					}
+
+					return {
+						hostScreenKey,
+						ownerPairKey,
+						ownerScreenKey,
+						status: "complete",
+					};
+				});
+				return;
+			}
+
+			setOwnership((current) => (current ? null : current));
+		},
+		[],
+	);
+
+	const unmountOwnedPortalBoundaryHosts = useCallback(() => {
+		for (const portalHostName of mountedPortalBoundaryHostNamesRef.current) {
+			unmountPortalBoundaryHostByName(portalHostName);
+		}
+
+		mountedPortalBoundaryHostNamesRef.current.clear();
+	}, []);
+
+	useLayoutEffect(() => {
+		if (!enabled || !ownership || !escapeHostKey) {
+			requestedPortalHostName.set(null);
+			visiblePortalHostName.set(null);
+			unmountOwnedPortalBoundaryHosts();
+			return;
+		}
+
+		const portalHostName = createBoundaryPortalHostName(
+			escapeHostKey,
+			boundaryId,
+			ownership.ownerPairKey,
+		);
+
+		mountPortalBoundaryHost({
+			boundaryId,
+			escapeClipping: true,
+			hostKey: escapeHostKey,
+			localStylesMaps,
+			pairKey: ownership.ownerPairKey,
+			portalHostName,
+			screenKey: currentScreenKey,
+			slotsMap,
+		});
+		mountedPortalBoundaryHostNamesRef.current.add(portalHostName);
+
+		// Request the new receiver immediately, but keep the currently visible
+		// receiver until the new interpolator is ready. This avoids a no-host gap
+		// during rapid close/open retargets.
+		requestedPortalHostName.set(portalHostName);
+	}, [
+		boundaryId,
+		currentScreenKey,
+		enabled,
+		escapeHostKey,
+		localStylesMaps,
+		ownership,
+		requestedPortalHostName,
+		slotsMap,
+		unmountOwnedPortalBoundaryHosts,
+		visiblePortalHostName,
+	]);
+
+	useLayoutEffect(() => {
+		return () => {
+			requestedPortalHostName.set(null);
+			visiblePortalHostName.set(null);
+			unmountOwnedPortalBoundaryHosts();
+		};
+	}, [
+		requestedPortalHostName,
+		unmountOwnedPortalBoundaryHosts,
+		visiblePortalHostName,
+	]);
+
+	useAnimatedReaction(
+		() => {
+			"worklet";
+			if (!enabled || !sourcePairKey) {
+				return {
+					hostScreenKey: null,
+					ownerPairKey: sourcePairKey,
+					ownerScreenKey: null,
+					status: "clear",
+				};
+			}
+
+			return resolveBoundaryPortalOwnership({
+				boundaryId,
+				currentScreenKey,
+				handoff: false,
+				pairsState: pairs.get(),
+				sourcePairKey,
+			});
+		},
+		(signal, previousSignal) => {
+			"worklet";
+			if (shallowEqual(previousSignal, signal)) {
+				return;
+			}
+
+			runOnJS(updatePortalOwnership)(
+				signal.hostScreenKey,
+				signal.ownerPairKey,
+				signal.ownerScreenKey ?? undefined,
+			);
+		},
+	);
+
+	useAnimatedReaction(
+		() => {
+			"worklet";
+			const slot = slotsMap.get()[boundaryId];
+			const teleport = slot?.props?.teleport;
+			const shouldTeleport = shouldAttachBoundaryPortal({
+				enabled,
+				teleport,
+			});
+			const requestedName = requestedPortalHostName.get();
+			const visibleName = visiblePortalHostName.get();
+			const isInterpolatorReady = nextInterpolatorReady.get();
+			const nextVisibleName = resolveNextVisiblePortalHostName({
+				isInterpolatorReady: isInterpolatorReady === 1,
+				requestedName,
+				shouldTeleport,
+				visibleName,
+			});
+
+			return {
+				isInterpolatorReady,
+				nextVisibleName,
+				requestedName,
+				shouldTeleport,
+				teleport,
+				visibleName,
+			};
+		},
+		(state, previousState) => {
+			"worklet";
+			if (shallowEqual(previousState, state)) {
+				return;
+			}
+
+			if (state.nextVisibleName !== state.visibleName) {
+				visiblePortalHostName.set(state.nextVisibleName);
+				return;
+			}
+
+			if (state.visibleName && state.visibleName === state.requestedName) {
+				runOnJS(dropStalePortalBoundaryHosts)({
+					boundaryId,
+					keepPortalHostName: state.visibleName,
+				});
+			}
+		},
+	);
+
+	const teleportProps = useAnimatedProps(() => {
+		"worklet";
+
+		const slot = slotsMap.get()[boundaryId];
+		const { teleport, ...slotProps } = slot?.props ?? {};
+		const shouldTeleport = shouldAttachBoundaryPortal({
+			enabled,
+			teleport,
+		});
+		const visibleName = visiblePortalHostName.get();
+
+		return {
+			...slotProps,
+			hostName:
+				shouldTeleport && visibleName
+					? visibleName
+					: PORTAL_HOST_NAME_RESET_VALUE,
+		};
+	});
+
+	return {
+		teleportProps,
+		visiblePortalHostName,
+	};
+};

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

@@ -5,18 +5,21 @@ import {
 	measure,
 	runOnJS,
 	runOnUI,
+	type SharedValue,
 	useAnimatedReaction,
 	useAnimatedRef,
 	useSharedValue,
 	withDelay,
 	withTiming,
 } from "react-native-reanimated";
-import { useOriginContext } from "../../../../providers/screen/origin.provider";
-import { ScrollStore } from "../../../../stores/scroll.store";
+import { useOriginContext } from "../../../../../../providers/screen/origin.provider";
+import { ScrollStore } from "../../../../../../stores/scroll.store";
+import { getVisibilityBlockOffset } from "../../../../../../utils/visibility-block-offset";
 import {
 	adjustedMeasuredBoundsForOverscrollDeltas,
-	normalizeMeasuredBoundsToOrigin,
-} from "../../utils/measured-bounds";
+	isMeasurementInViewport,
+	normalizeMeasuredBoundsWithVisibilityGate,
+} from "../../../../utils/measured-bounds";
 import {
 	clearPortalHostBounds,
 	setPortalHostBounds,
@@ -29,6 +32,9 @@ type UseHostMeasurementParams = {
 	enabled: boolean;
 	hostKey: string;
 	screenKey: string;
+	visibilityBlocked: SharedValue<boolean>;
+	viewportHeight: number;
+	viewportWidth: number;
 };
 
 export const useHostMeasurement = ({
@@ -36,6 +42,9 @@ export const useHostMeasurement = ({
 	enabled,
 	hostKey,
 	screenKey,
+	visibilityBlocked,
+	viewportHeight,
+	viewportWidth,
 }: UseHostMeasurementParams) => {
 	const hostRef = useAnimatedRef<View>();
 	const scrollMetadata = ScrollStore.getValue(screenKey, "metadata");
@@ -91,10 +100,31 @@ export const useHostMeasurement = ({
 				? adjustedMeasuredBoundsForOverscrollDeltas(measured, currentScroll)
 				: measured;
 
-			const normalizedMeasured = normalizeMeasuredBoundsToOrigin(
-				overscrollNormalized,
-				measuredOrigin,
-			);
+			const normalizedMeasured = normalizeMeasuredBoundsWithVisibilityGate({
+				measured: overscrollNormalized,
+				origin: measuredOrigin,
+				visibilityBlocked: visibilityBlocked.get(),
+				visibilityBlockOffset: getVisibilityBlockOffset(viewportHeight),
+				viewportWidth,
+				viewportHeight,
+			});
+
+			if (
+				!isMeasurementInViewport(
+					normalizedMeasured,
+					viewportWidth,
+					viewportHeight,
+				)
+			) {
+				cancelAnimation(retryToken);
+				retryToken.set(
+					withDelay(
+						HOST_MEASUREMENT_RETRY_DELAY_MS,
+						withTiming(retryToken.get() + 1, { duration: 0 }),
+					),
+				);
+				return;
+			}
 
 			setPortalHostBounds(hostKey, {
 				x: normalizedMeasured.x,

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

@@ -1,31 +1,20 @@
 import { useCallback } from "react";
 import type { LayoutRectangle } from "react-native";
-import {
-	type SharedValue,
-	useAnimatedStyle,
-	useSharedValue,
-} from "react-native-reanimated";
+import { useAnimatedStyle, useSharedValue } from "react-native-reanimated";
 
-interface UsePlaceholderProps {
-	visiblePortalHostName: SharedValue<string | null>;
-}
-
-export const usePlaceholderStyles = ({
-	visiblePortalHostName,
-}: UsePlaceholderProps) => {
+export const usePlaceholderStyles = () => {
 	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
+	// 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) {
+		if (width === 0) {
 			return { width: "auto", height: "auto" } as const;
 		}
 

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

@@ -0,0 +1,38 @@
+import { memo, type ReactNode } from "react";
+import type { View, ViewProps } from "react-native";
+import type { AnimatedRef } from "react-native-reanimated";
+import { BoundaryPortalSlot } from "./components/portal-slot";
+import { useBoundaryPortalAttachment } from "./hooks/use-boundary-portal-attachment";
+
+type BoundaryPortalProps = {
+	boundaryId: string;
+	children: ReactNode;
+	enabled: boolean;
+	placeholderRef?: AnimatedRef<View>;
+	pointerEvents?: ViewProps["pointerEvents"];
+};
+
+export const BoundaryPortal = memo(function BoundaryPortal({
+	boundaryId,
+	children,
+	enabled,
+	placeholderRef,
+	pointerEvents,
+}: BoundaryPortalProps) {
+	const { teleportProps } = useBoundaryPortalAttachment({
+		boundaryId,
+		enabled,
+	});
+
+	return (
+		<BoundaryPortalSlot
+			id={boundaryId}
+			enabled={enabled}
+			animatedProps={teleportProps}
+			placeholderRef={placeholderRef}
+			pointerEvents={pointerEvents}
+		>
+			{children}
+		</BoundaryPortalSlot>
+	);
+});

package/src/shared/components/boundary/portal/{stores → components/boundary-portal/stores}/host-bounds.store.ts

@@ -1,6 +1,6 @@
 import { type MeasuredDimensions, makeMutable } from "react-native-reanimated";
-import { cloneScrollMetadataState } from "../../../../stores/scroll.store";
-import type { ScrollMetadataState } from "../../../../types/gesture.types";
+import { cloneScrollMetadataState } from "../../../../../../stores/scroll.store";
+import type { ScrollMetadataState } from "../../../../../../types/gesture.types";
 
 export type PortalHostBounds = MeasuredDimensions & {
 	scroll?: ScrollMetadataState | null;

package/src/shared/components/boundary/portal/{stores → components/boundary-portal/stores}/portal-boundary-host.store.ts

@@ -1,7 +1,7 @@
 import { useSyncExternalStore } from "react";
 import type { SharedValue } from "react-native-reanimated";
-import type { LocalStyleLayers } from "../../../../providers/screen/styles/helpers/resolve-slot-styles";
-import type { NormalizedTransitionInterpolatedStyle } from "../../../../types/animation.types";
+import type { LocalStyleLayers } from "../../../../../../providers/screen/styles/helpers/resolve-slot-styles";
+import type { NormalizedTransitionInterpolatedStyle } from "../../../../../../types/animation.types";
 
 export type ActivePortalBoundaryHost = {
 	boundaryId: string;
@@ -75,19 +75,10 @@ export const mountPortalBoundaryHost = (host: ActivePortalBoundaryHost) => {
 	emit();
 };
 
-export const unmountPortalBoundaryHost = (boundaryId: string) => {
-	let didDelete = false;
-
-	for (const [hostEntryKey, host] of activeBoundaryHosts) {
-		if (host.boundaryId !== boundaryId) {
-			continue;
-		}
-
-		activeBoundaryHosts.delete(hostEntryKey);
-		didDelete = true;
-	}
-
-	if (!didDelete) {
+export const unmountPortalBoundaryHostByName = (
+	portalHostName: string | null | undefined,
+) => {
+	if (!portalHostName || !activeBoundaryHosts.delete(portalHostName)) {
 		return;
 	}
 
@@ -106,6 +97,10 @@ export const dropStalePortalBoundaryHosts = ({
 	boundaryId: string;
 	keepPortalHostName: string;
 }) => {
+	if (!activeBoundaryHosts.has(keepPortalHostName)) {
+		return;
+	}
+
 	let didDelete = false;
 
 	for (const [hostEntryKey, host] of activeBoundaryHosts) {

package/src/shared/components/boundary/portal/index.ts

@@ -1,3 +1,2 @@
-export { Host } from "./components/host";
-export { Portal } from "./components/portal";
+export { Host } from "./components/boundary-portal/components/host";
 export { PortalProvider } from "./components/portal-provider";

package/src/shared/components/boundary/portal/teleport.ts

@@ -5,8 +5,8 @@ import { type ComponentType, createElement, type ReactNode } from "react";
  * try/catch so Metro treats it as an optional dependency — an absent module no
  * longer fails the bundle, it throws at runtime and the catch swallows it.
  *
- * When teleport is missing, `portal`-enabled boundaries degrade to inline
- * rendering; everything else keeps working.
+ * When teleport is missing, handoff and escapeClipping boundaries degrade to
+ * inline rendering; everything else keeps working.
  */
 let mod: any = null;
 let managerMod: any = null;

package/src/shared/components/boundary/portal/utils/naming.ts

@@ -1,20 +1 @@
 export const PORTAL_HOST_NAME_RESET_VALUE = null;
-const PORTAL_HOST_NAME_SUFFIX = "-portal-host";
-const BOUNDARY_LOCAL_PORTAL_HOST_NAME_SUFFIX = "-boundary-local-portal-host";
-
-export const createPortalBoundaryHostName = (
-	hostKey: string,
-	boundaryId: string,
-	pairKey?: string | null,
-) => {
-	"worklet";
-	return `${hostKey}-${pairKey ? `${pairKey}-` : ""}${boundaryId}${PORTAL_HOST_NAME_SUFFIX}`;
-};
-
-export const createBoundaryLocalPortalHostName = (
-	screenKey: string,
-	boundaryId: string,
-) => {
-	"worklet";
-	return `${screenKey}-${boundaryId}${BOUNDARY_LOCAL_PORTAL_HOST_NAME_SUFFIX}`;
-};

package/src/shared/components/boundary/portal/utils/ownership.ts

@@ -26,6 +26,29 @@ export type PortalOwnershipSignal =
 			status: "complete";
 	  };
 
+export const isHandoffHostClosingComplete = ({
+	closing,
+	progressAnimating,
+	progressSettled,
+	willAnimate,
+}: {
+	closing: number;
+	progressAnimating: number;
+	progressSettled: number;
+	willAnimate: number;
+}) => {
+	"worklet";
+
+	// A close request marks `closing` before its animation starts. Springs can
+	// also enter their settle-distance threshold before their final frame.
+	return (
+		!!closing &&
+		willAnimate === 0 &&
+		progressSettled === 1 &&
+		progressAnimating === 0
+	);
+};
+
 const hasSeenScreenKey = (screenKeys: ScreenKey[], screenKey: ScreenKey) => {
 	"worklet";
 	for (let index = 0; index < screenKeys.length; index++) {
@@ -36,13 +59,6 @@ const hasSeenScreenKey = (screenKeys: ScreenKey[], screenKey: ScreenKey) => {
 	return false;
 };
 
-export const usesEscapeClippingHost = (
-	link: TagLink | null | undefined,
-): boolean => {
-	"worklet";
-	return link?.source?.handoff === true && link.source.escapeClipping === true;
-};
-
 const isReturningToPreviousSourceHost = ({
 	hostScreenKey,
 	ownerPairKey,
@@ -69,7 +85,7 @@ const isReturningToPreviousSourceHost = ({
 	);
 };
 
-export const canSwitchBoundaryLocalHandoffImmediately = ({
+export const canSwitchHandoffHostImmediately = ({
 	hostScreenKey,
 	ownerPairKey,
 	previousOwnerPairKey,
@@ -118,7 +134,7 @@ const isActiveHandoffLink = ({
 	return !activeId || activeId === linkKey;
 };
 
-const resolveBoundaryLocalStyleOwnerScreenKey = ({
+const resolveHandoffStyleOwnerScreenKey = ({
 	hostScreenKey,
 	isSettledHostReady,
 	settledHostScreenKey,
@@ -160,7 +176,6 @@ const clearSignal = (sourcePairKey: ScreenPairKey): PortalOwnershipSignal => {
 export const resolveBoundaryPortalOwnership = ({
 	boundaryId,
 	currentScreenKey,
-	escapeClipping,
 	handoff,
 	isSettledHostClosingComplete = false,
 	isSettledHostReady = false,
@@ -170,7 +185,6 @@ export const resolveBoundaryPortalOwnership = ({
 }: {
 	boundaryId: string;
 	currentScreenKey: ScreenKey;
-	escapeClipping: boolean;
 	handoff: boolean;
 	isSettledHostClosingComplete?: boolean;
 	isSettledHostReady?: boolean;
@@ -208,7 +222,6 @@ export const resolveBoundaryPortalOwnership = ({
 
 	let hostScreenKey = link.destination.screenKey;
 	let ownerPairKey = sourcePairKey;
-	let previousOwnerPairKey: ScreenPairKey | null = null;
 	const seenScreenKeys: ScreenKey[] = [
 		getSourceScreenKeyFromPairKey(sourcePairKey),
 		hostScreenKey,
@@ -254,7 +267,6 @@ export const resolveBoundaryPortalOwnership = ({
 
 			const nextHostScreenKey = candidate.destination.screenKey;
 
-			previousOwnerPairKey = ownerPairKey;
 			ownerPairKey = candidatePairKey;
 			hostScreenKey = nextHostScreenKey;
 
@@ -283,27 +295,16 @@ export const resolveBoundaryPortalOwnership = ({
 		break;
 	}
 
-	const ownerLink = getPairLink(pairsState, ownerPairKey, linkKey);
-	const ownerUsesEscapeClipping =
-		ownerLink?.source?.escapeClipping ?? escapeClipping;
-
-	if (
-		!ownerUsesEscapeClipping &&
-		isSettledHostClosingComplete &&
-		settledHostScreenKey === hostScreenKey &&
-		previousOwnerPairKey
-	) {
+	if (isSettledHostClosingComplete && settledHostScreenKey === hostScreenKey) {
 		hostScreenKey = getSourceScreenKeyFromPairKey(ownerPairKey);
 	}
 
-	const ownerScreenKey = ownerUsesEscapeClipping
-		? getSourceScreenKeyFromPairKey(ownerPairKey)
-		: resolveBoundaryLocalStyleOwnerScreenKey({
-				hostScreenKey,
-				isSettledHostReady,
-				settledHostScreenKey,
-				sourceScreenKey: getSourceScreenKeyFromPairKey(ownerPairKey),
-			});
+	const ownerScreenKey = resolveHandoffStyleOwnerScreenKey({
+		hostScreenKey,
+		isSettledHostReady,
+		settledHostScreenKey,
+		sourceScreenKey: getSourceScreenKeyFromPairKey(ownerPairKey),
+	});
 
 	return {
 		hostScreenKey,
@@ -312,60 +313,3 @@ export const resolveBoundaryPortalOwnership = ({
 		status: "complete",
 	};
 };
-
-export const hasHandoffEscapeContinuation = ({
-	linkKey,
-	linkState,
-	sourceScreenKey,
-}: {
-	linkKey: string;
-	linkState: LinkPairsState;
-	sourceScreenKey: ScreenKey;
-}) => {
-	"worklet";
-	const pairKeys = Object.keys(linkState);
-	const visitedScreenKeys: ScreenKey[] = [];
-	let cursorScreenKey = sourceScreenKey;
-
-	for (let hop = 0; hop < pairKeys.length; hop++) {
-		if (hasSeenScreenKey(visitedScreenKeys, cursorScreenKey)) {
-			return false;
-		}
-		visitedScreenKeys.push(cursorScreenKey);
-
-		let previousScreenKey: ScreenKey | null = null;
-		for (let index = 0; index < pairKeys.length; index++) {
-			const candidatePairKey = pairKeys[index];
-			const link = candidatePairKey
-				? linkState[candidatePairKey]?.links?.[linkKey]
-				: null;
-
-			if (
-				!link?.source ||
-				!link.destination ||
-				link.destination.screenKey !== cursorScreenKey
-			) {
-				continue;
-			}
-
-			if (usesEscapeClippingHost(link)) {
-				return true;
-			}
-
-			if (!link.source.handoff) {
-				return false;
-			}
-
-			previousScreenKey = link.source.screenKey;
-			break;
-		}
-
-		if (!previousScreenKey) {
-			return false;
-		}
-
-		cursorScreenKey = previousScreenKey;
-	}
-
-	return false;
-};