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

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

@@ -8,15 +8,17 @@ import {
 } 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 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 {
 	attachScrollSnapshotToMeasuredBounds,
 	isMeasurementInViewport,
 	measureWithOverscrollAwareness,
-	normalizeMeasuredBoundsToOrigin,
+	normalizeMeasuredBoundsWithVisibilityGate,
 } from "../utils/measured-bounds";
 
 interface UseMeasurerParams {
@@ -48,6 +50,7 @@ export const useMeasurer = ({
 		"pendingLifecycleStartBlockCount",
 	);
 	const { originRef } = useOriginContext();
+	const { visibilityBlocked } = useScreenSlots();
 
 	return useCallback(
 		(target) => {
@@ -62,10 +65,14 @@ export const useMeasurer = ({
 
 			if (!measured || !measuredOrigin) return;
 
-			const normalizedMeasured = normalizeMeasuredBoundsToOrigin(
+			const normalizedMeasured = normalizeMeasuredBoundsWithVisibilityGate({
 				measured,
-				measuredOrigin,
-			);
+				origin: measuredOrigin,
+				visibilityBlocked: escapeClipping && visibilityBlocked.get(),
+				visibilityBlockOffset: getVisibilityBlockOffset(viewportHeight),
+				viewportWidth,
+				viewportHeight,
+			});
 
 			/**
 			 * - Destination Pass -
@@ -119,6 +126,7 @@ export const useMeasurer = ({
 			scrollMetadata,
 			pendingLifecycleStartBlockCount,
 			originRef,
+			visibilityBlocked,
 		],
 	);
 };

package/src/shared/components/boundary/hooks/use-register-target.ts

@@ -0,0 +1,43 @@
+import { useLayoutEffect } from "react";
+import type { View } from "react-native";
+import type { AnimatedRef } from "react-native-reanimated";
+import { logger } from "../../../utils/logger";
+import {
+	TARGET_OUTSIDE_ROOT_WARNING,
+	useBoundaryRootContext,
+} from "../providers/boundary-root.provider";
+
+interface RegisterTargetProps {
+	targetAnimatedRef: AnimatedRef<View>;
+	preparedStyles: Record<string, any>;
+	measurementRef: AnimatedRef<View>;
+}
+
+export const useRegisterTarget = ({
+	targetAnimatedRef,
+	preparedStyles,
+	measurementRef,
+}: RegisterTargetProps) => {
+	const rootContext = useBoundaryRootContext();
+	const registerTargetRef = rootContext?.registerTargetRef;
+	const unregisterTargetRef = rootContext?.unregisterTargetRef;
+	useLayoutEffect(() => {
+		if (!registerTargetRef || !unregisterTargetRef) {
+			if (__DEV__) {
+				logger.warn(TARGET_OUTSIDE_ROOT_WARNING);
+			}
+			return;
+		}
+
+		registerTargetRef(targetAnimatedRef, preparedStyles, measurementRef);
+		return () => {
+			unregisterTargetRef(targetAnimatedRef);
+		};
+	}, [
+		registerTargetRef,
+		unregisterTargetRef,
+		targetAnimatedRef,
+		preparedStyles,
+		measurementRef,
+	]);
+};

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

@@ -53,7 +53,7 @@ type BoundaryRootComponent = typeof BoundaryRoot;
  * Use:
  * - `Boundary` for passive and pressable shared elements.
  * - `Boundary.Target` to measure a nested descendant instead of the root.
- * - `Boundary.Host` to make nested portal placement explicit.
+ * - `Boundary.Host` to make clipping-escape host placement explicit.
  */
 export interface BoundaryComponent extends BoundaryRootComponent {
 	/**
@@ -61,7 +61,7 @@ export interface BoundaryComponent extends BoundaryRootComponent {
 	 */
 	Target: typeof BoundaryTarget;
 	/**
-	 * Explicit portal host for scrollable or otherwise clipped coordinate spaces.
+	 * Explicit host for clipping-escape placement.
 	 */
 	Host: typeof Host;
 	/**

package/src/shared/components/boundary/portal/components/boundary-content-portal/components/host.tsx

@@ -0,0 +1,52 @@
+import { memo, type ReactNode } from "react";
+import { StyleSheet } from "react-native";
+import Animated from "react-native-reanimated";
+import { NativePortalHost, PORTAL_POINTER_EVENTS } from "../../../teleport";
+import { createBoundaryContentPortalHostName } from "../helpers/host-name";
+
+const AnimatedPortalHost = NativePortalHost
+	? Animated.createAnimatedComponent(NativePortalHost)
+	: null;
+
+type BoundaryContentPortalHostProps = {
+	boundaryId: string;
+	children: ReactNode;
+	enabled: boolean;
+	screenKey: string;
+};
+
+export const BoundaryContentPortalHost = memo(
+	function BoundaryContentPortalHost({
+		boundaryId,
+		children,
+		enabled,
+		screenKey,
+	}: BoundaryContentPortalHostProps) {
+		if (!enabled || !AnimatedPortalHost) {
+			return <>{children}</>;
+		}
+
+		const portalHostName = createBoundaryContentPortalHostName(
+			screenKey,
+			boundaryId,
+		);
+
+		return (
+			<>
+				{children}
+				<AnimatedPortalHost
+					name={portalHostName}
+					pointerEvents={PORTAL_POINTER_EVENTS}
+					style={styles.host}
+				/>
+			</>
+		);
+	},
+);
+
+const styles = StyleSheet.create({
+	host: {
+		...StyleSheet.absoluteFillObject,
+		overflow: "visible",
+	},
+});

package/src/shared/components/boundary/portal/components/boundary-content-portal/helpers/host-name.ts

@@ -0,0 +1,9 @@
+const BOUNDARY_CONTENT_PORTAL_HOST_NAME_SUFFIX = "-content-portal-host";
+
+export const createBoundaryContentPortalHostName = (
+	screenKey: string,
+	boundaryId: string,
+) => {
+	"worklet";
+	return `${screenKey}-${boundaryId}${BOUNDARY_CONTENT_PORTAL_HOST_NAME_SUFFIX}`;
+};

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

@@ -0,0 +1,317 @@
+import { useCallback, useLayoutEffect, 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 { useRegisteredScreenSlots } from "../../../../../../providers/screen/styles/stores/slot-references.store";
+import { AnimationStore } from "../../../../../../stores/animation.store";
+import { getSourceScreenKeyFromPairKey } from "../../../../../../stores/bounds/helpers/link-pairs.helpers";
+import { pairs } from "../../../../../../stores/bounds/internals/state";
+import { PORTAL_HOST_NAME_RESET_VALUE } from "../../../utils/naming";
+import {
+	canSwitchHandoffHostImmediately,
+	isHandoffHostClosingComplete,
+	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 { createBoundaryContentPortalHostName } from "../helpers/host-name";
+
+interface UseBoundaryContentPortalAttachmentParams {
+	boundaryId: string;
+	enabled: boolean;
+}
+
+export const useBoundaryContentPortalAttachment = ({
+	boundaryId,
+	enabled,
+}: UseBoundaryContentPortalAttachmentParams) => {
+	const ownScreenSlots = useScreenSlots();
+	const sourcePairKey = useDescriptorsStore((s) => s.derivations.sourcePairKey);
+	const currentScreenKey = useDescriptorsStore(
+		(s) => s.derivations.currentScreenKey,
+	);
+	const [ownership, setOwnership] = useState<Extract<
+		PortalOwnershipSignal,
+		{ status: "complete" }
+	> | null>(null);
+
+	const styleOwnerScreenKey = ownership?.ownerScreenKey ?? currentScreenKey;
+	const ownerScreenSlots = useRegisteredScreenSlots(styleOwnerScreenKey);
+	const activeScreenSlots = ownerScreenSlots ?? ownScreenSlots;
+	const {
+		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 settledHostAnimating = AnimationStore.getValue(
+		settledHostScreenKey ?? currentScreenKey,
+		"progressAnimating",
+	);
+	const settledHostWillAnimate = AnimationStore.getValue(
+		settledHostScreenKey ?? currentScreenKey,
+		"willAnimate",
+	);
+	const settledHostClosing = AnimationStore.getValue(
+		settledHostScreenKey ?? currentScreenKey,
+		"closing",
+	);
+	const handoffHostName =
+		targetScreenKey !== null
+			? createBoundaryContentPortalHostName(targetScreenKey, boundaryId)
+			: 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));
+		},
+		[],
+	);
+
+	useLayoutEffect(() => {
+		if (!enabled || !ownership || !handoffHostName) {
+			requestedPortalHostName.set(null);
+			visiblePortalHostName.set(null);
+			return;
+		}
+
+		requestedPortalHostName.set(handoffHostName);
+	}, [
+		enabled,
+		handoffHostName,
+		ownership,
+		requestedPortalHostName,
+		visiblePortalHostName,
+	]);
+
+	useLayoutEffect(() => {
+		return () => {
+			requestedPortalHostName.set(null);
+			visiblePortalHostName.set(null);
+		};
+	}, [requestedPortalHostName, visiblePortalHostName]);
+
+	useAnimatedReaction(
+		() => {
+			"worklet";
+			if (!enabled) {
+				return {
+					hostScreenKey: null,
+					ownerPairKey: sourcePairKey,
+					ownerScreenKey: null,
+					status: "clear",
+				};
+			}
+
+			const progressAnimating = settledHostAnimating.get();
+			const progressSettled = settledHostProgress.get();
+			const willAnimate = settledHostWillAnimate.get();
+			const closing = settledHostClosing.get();
+			const isOwnedHostClosing =
+				!!closing &&
+				!!ownership &&
+				settledHostScreenKey === ownership.hostScreenKey;
+
+			if (isOwnedHostClosing && ownership) {
+				const isClosingComplete = isHandoffHostClosingComplete({
+					closing,
+					progressAnimating,
+					progressSettled,
+					willAnimate,
+				});
+
+				if (!isClosingComplete) {
+					return ownership;
+				}
+
+				const sourceScreenKey = getSourceScreenKeyFromPairKey(
+					ownership.ownerPairKey,
+				);
+
+				return {
+					hostScreenKey: sourceScreenKey,
+					ownerPairKey: ownership.ownerPairKey,
+					ownerScreenKey: sourceScreenKey,
+					status: "complete",
+				};
+			}
+
+			if (!sourcePairKey) {
+				return {
+					hostScreenKey: null,
+					ownerPairKey: sourcePairKey,
+					ownerScreenKey: null,
+					status: "clear",
+				};
+			}
+
+			return resolveBoundaryPortalOwnership({
+				boundaryId,
+				currentScreenKey,
+				handoff: true,
+				isSettledHostClosingComplete: isHandoffHostClosingComplete({
+					closing,
+					progressAnimating,
+					progressSettled,
+					willAnimate,
+				}),
+				isSettledHostReady: progressSettled === 1 && progressAnimating === 0,
+				pairsState: pairs.get(),
+				settledHostScreenKey,
+				sourcePairKey,
+			});
+		},
+		(signal, previousSignal) => {
+			"worklet";
+			if (shallowEqual(previousSignal, signal)) {
+				return;
+			}
+
+			if (signal.status === "pending") {
+				canSwitchPortalHostImmediately.set(0);
+				return;
+			}
+
+			const hostScreenKey =
+				signal.status === "complete" ? signal.hostScreenKey : null;
+			let previousOwnerPairKey: string | undefined;
+
+			if (previousSignal?.status === "complete") {
+				previousOwnerPairKey = previousSignal.ownerPairKey ?? undefined;
+			}
+
+			const canSwitchImmediately = canSwitchHandoffHostImmediately({
+				hostScreenKey,
+				ownerPairKey:
+					signal.status === "complete" ? signal.ownerPairKey : undefined,
+				previousOwnerPairKey,
+			});
+
+			canSwitchPortalHostImmediately.set(canSwitchImmediately ? 1 : 0);
+
+			if (canSwitchImmediately && hostScreenKey) {
+				const hostName = createBoundaryContentPortalHostName(
+					hostScreenKey,
+					boundaryId,
+				);
+				requestedPortalHostName.set(hostName);
+				visiblePortalHostName.set(hostName);
+			}
+
+			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,
+				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,
+			};
+		},
+		(state, previousState) => {
+			"worklet";
+			if (shallowEqual(previousState, state)) {
+				return;
+			}
+
+			if (state.nextVisibleName !== state.visibleName) {
+				visiblePortalHostName.set(state.nextVisibleName);
+			}
+		},
+	);
+
+	const teleportProps = useAnimatedProps(() => {
+		"worklet";
+
+		const slot = activeSlotsMap.get()[boundaryId];
+		const {
+			pointerEvents: _pointerEvents,
+			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/components/boundary-content-portal/index.tsx

@@ -0,0 +1,62 @@
+import {
+	type ComponentProps,
+	type ComponentType,
+	memo,
+	type ReactNode,
+} from "react";
+import { StyleSheet } from "react-native";
+import Animated from "react-native-reanimated";
+import {
+	isTeleportAvailable,
+	NativePortal,
+	PORTAL_POINTER_EVENTS,
+} from "../../teleport";
+import { useBoundaryContentPortalAttachment } from "./hooks/use-boundary-content-portal-attachment";
+
+export { BoundaryContentPortalHost } from "./components/host";
+
+type BoundaryContentPortalProps = {
+	boundaryId?: string;
+	children: ReactNode;
+	enabled: boolean;
+};
+
+type NullableHostNamePortalProps = Omit<
+	ComponentProps<NonNullable<typeof NativePortal>>,
+	"hostName"
+> & {
+	hostName?: string | null;
+};
+
+const AnimatedNativePortal = NativePortal
+	? Animated.createAnimatedComponent(
+			NativePortal as ComponentType<NullableHostNamePortalProps>,
+		)
+	: null;
+
+export const BoundaryContentPortal = memo(function BoundaryContentPortal({
+	boundaryId,
+	children,
+	enabled,
+}: BoundaryContentPortalProps) {
+	const shouldEnablePortal = enabled && boundaryId !== undefined;
+	const { teleportProps } = useBoundaryContentPortalAttachment({
+		boundaryId: boundaryId ?? "",
+		enabled: shouldEnablePortal,
+	});
+
+	if (shouldEnablePortal && isTeleportAvailable && AnimatedNativePortal) {
+		return (
+			<AnimatedNativePortal
+				animatedProps={teleportProps}
+				name={boundaryId}
+				pointerEvents={PORTAL_POINTER_EVENTS}
+				style={StyleSheet.absoluteFill}
+			>
+				{children}
+			</AnimatedNativePortal>
+		);
+	}
+
+	return children;
+});

package/src/shared/components/boundary/portal/components/{host.tsx → boundary-portal/components/host.tsx}

@@ -7,8 +7,10 @@ import {
 	type ViewStyle,
 } from "react-native";
 import Animated from "react-native-reanimated";
-import { useDescriptorsStore } from "../../../../providers/screen/descriptors";
-import { SystemStore } from "../../../../stores/system.store";
+import { useDescriptorsStore } from "../../../../../../providers/screen/descriptors";
+import { useScreenSlots } from "../../../../../../providers/screen/styles";
+import { SystemStore } from "../../../../../../stores/system.store";
+import { PORTAL_POINTER_EVENTS } from "../../../teleport";
 import { useHostMeasurement } from "../hooks/use-host-measurement";
 import { registerHost, unregisterHost } from "../stores/host-registry.store";
 import { useActivePortalBoundaryHosts } from "../stores/portal-boundary-host.store";
@@ -26,7 +28,7 @@ type HostImplProps = PublicHostProps & {
 
 function HostImpl({ fallback = false, style }: HostImplProps) {
 	const screenKey = useDescriptorsStore((s) => s.derivations.currentScreenKey);
-	const { drainLifecycleStartBlocks } = SystemStore.getBag(screenKey).actions;
+	const { unblockLifecycleStart } = SystemStore.getBag(screenKey).actions;
 	const generatedHostKeyRef = useRef<string | null>(null);
 
 	if (generatedHostKeyRef.current === null) {
@@ -36,6 +38,7 @@ function HostImpl({ fallback = false, style }: HostImplProps) {
 	const hostKey = fallback ? screenKey : generatedHostKeyRef.current;
 	const capturesScroll = !fallback;
 	const activeBoundaryHosts = useActivePortalBoundaryHosts(hostKey);
+	const { visibilityBlocked } = useScreenSlots();
 	const { height: viewportHeight, width: viewportWidth } =
 		useWindowDimensions();
 
@@ -44,6 +47,9 @@ function HostImpl({ fallback = false, style }: HostImplProps) {
 		enabled: activeBoundaryHosts.length > 0,
 		hostKey,
 		screenKey,
+		visibilityBlocked,
+		viewportHeight,
+		viewportWidth,
 	});
 
 	useLayoutEffect(() => {
@@ -60,27 +66,21 @@ function HostImpl({ fallback = false, style }: HostImplProps) {
 	}, [capturesScroll, fallback, hostKey, screenKey]);
 
 	const handleUnblocking = useCallback(() => {
-		// Screen-level escape keeps the open transition gated until portal hosts
-		// have committed layout. A screen may render more than one portal boundary
-		// host for the same lifecycle request, so the final host layout drains the
-		// outstanding start blocks for this screen.
-		drainLifecycleStartBlocks();
-	}, [drainLifecycleStartBlocks]);
+		// Each destination boundary contributes one lifecycle start block. Release
+		// only this host's block so unrelated boundary and user blocks stay intact.
+		unblockLifecycleStart();
+	}, [unblockLifecycleStart]);
 
 	const boundaryHosts = measurement.canRenderHosts
-		? activeBoundaryHosts.map((host, idx, list) => (
+		? activeBoundaryHosts.map((host) => (
 				<View
 					key={host.portalHostName}
-					pointerEvents="none"
+					pointerEvents={PORTAL_POINTER_EVENTS}
 					style={[
 						styles.boundaryHostViewport,
 						{ width: viewportWidth, height: viewportHeight },
 					]}
-					onLayout={() => {
-						if (list.length - 1 === idx) {
-							handleUnblocking();
-						}
-					}}
+					onLayout={handleUnblocking}
 				>
 					<PortalBoundaryHost host={host} style={StyleSheet.absoluteFill} />
 				</View>
@@ -90,7 +90,7 @@ function HostImpl({ fallback = false, style }: HostImplProps) {
 	return (
 		<Animated.View
 			ref={measurement.hostRef}
-			pointerEvents="none"
+			pointerEvents={PORTAL_POINTER_EVENTS}
 			style={[
 				styles.host,
 				{ width: viewportWidth, height: viewportHeight },