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

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

@@ -1,8 +1,35 @@
-import { memo, type ReactNode } from "react";
+import {
+	type ComponentProps,
+	type ComponentType,
+	memo,
+	type ReactNode,
+} from "react";
 import type { View } from "react-native";
-import type { AnimatedRef } from "react-native-reanimated";
-import { BoundaryPortalSlot } from "./components/portal-slot";
+import Animated, { type AnimatedRef, runOnUI } from "react-native-reanimated";
+import { logger } from "../../../../../utils/logger";
+import {
+	isTeleportAvailable,
+	PORTAL_POINTER_EVENTS,
+	NativePortal as TeleportPortal,
+} from "../../teleport";
 import { useBoundaryPortalAttachment } from "./hooks/use-boundary-portal-attachment";
+import { usePlaceholderStyles } from "./hooks/use-placeholder-styles";
+
+type NullableHostNamePortalProps = Omit<
+	ComponentProps<NonNullable<typeof TeleportPortal>>,
+	"hostName"
+> & {
+	hostName?: string | null;
+};
+
+const AnimatedNativePortal = TeleportPortal
+	? Animated.createAnimatedComponent(
+			TeleportPortal as ComponentType<NullableHostNamePortalProps>,
+		)
+	: null;
+const EnabledNativePortal = AnimatedNativePortal as NonNullable<
+	typeof AnimatedNativePortal
+>;
 
 type BoundaryPortalProps = {
 	boundaryId: string;
@@ -17,19 +44,52 @@ export const BoundaryPortal = memo(function BoundaryPortal({
 	enabled,
 	placeholderRef,
 }: BoundaryPortalProps) {
-	const { teleportProps } = useBoundaryPortalAttachment({
-		boundaryId,
-		enabled,
-	});
+	if (!enabled || !isTeleportAvailable || !AnimatedNativePortal) {
+		return children;
+	}
 
 	return (
-		<BoundaryPortalSlot
-			id={boundaryId}
-			enabled={enabled}
-			animatedProps={teleportProps}
+		<EnabledBoundaryPortal
+			boundaryId={boundaryId}
 			placeholderRef={placeholderRef}
 		>
 			{children}
-		</BoundaryPortalSlot>
+		</EnabledBoundaryPortal>
+	);
+});
+
+const EnabledBoundaryPortal = memo(function EnabledBoundaryPortal({
+	boundaryId,
+	children,
+	placeholderRef,
+}: Omit<BoundaryPortalProps, "enabled">) {
+	if (__DEV__ && !boundaryId) {
+		logger.warnOnce(
+			"portal:missing-id",
+			"A boundary portal was rendered without an id; rendering inline.",
+		);
+	}
+
+	const { teleportProps } = useBoundaryPortalAttachment({ boundaryId });
+	const { handleOnLayout, placeholderStyle } = usePlaceholderStyles();
+
+	return (
+		<Animated.View
+			ref={placeholderRef}
+			onLayout={({ nativeEvent: { layout } }) =>
+				runOnUI(handleOnLayout)(layout)
+			}
+			style={placeholderStyle}
+			pointerEvents={PORTAL_POINTER_EVENTS}
+			collapsable={false}
+		>
+			<EnabledNativePortal
+				animatedProps={teleportProps}
+				name={boundaryId}
+				pointerEvents={PORTAL_POINTER_EVENTS}
+			>
+				{children}
+			</EnabledNativePortal>
+		</Animated.View>
 	);
 });

package/src/shared/components/boundary/portal/components/boundary-portal/stores/host-registry.store.ts

@@ -4,7 +4,6 @@ export type HostRegistration = {
 	hostKey: string;
 	screenKey: string;
 	fallback: boolean;
-	capturesScroll: boolean;
 };
 
 type HostRegistrySnapshot = Record<string, string>;

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

@@ -5,11 +5,11 @@ import type { NormalizedTransitionInterpolatedStyle } from "../../../../../../ty
 
 export type ActivePortalBoundaryHost = {
 	boundaryId: string;
-	escapeClipping: boolean;
 	hostKey: string;
 	localStylesMaps: SharedValue<LocalStyleLayers>;
 	pairKey: string;
 	portalHostName: string;
+	portalHostReady: SharedValue<boolean>;
 	screenKey: string;
 	slotsMap: SharedValue<NormalizedTransitionInterpolatedStyle>;
 };
@@ -55,11 +55,11 @@ const isSameHost = (
 ) => {
 	return (
 		a.boundaryId === b.boundaryId &&
-		a.escapeClipping === b.escapeClipping &&
 		a.hostKey === b.hostKey &&
 		a.localStylesMaps === b.localStylesMaps &&
 		a.pairKey === b.pairKey &&
 		a.portalHostName === b.portalHostName &&
+		a.portalHostReady === b.portalHostReady &&
 		a.screenKey === b.screenKey &&
 		a.slotsMap === b.slotsMap
 	);
@@ -85,43 +85,6 @@ export const unmountPortalBoundaryHostByName = (
 	emit();
 };
 
-/**
- * Post-handoff GC: drop every receiver for this boundary except the one now
- * visible (`keepPortalHostName`). Called once the new host is confirmed on
- * screen so the superseded receivers stop rendering.
- */
-export const dropStalePortalBoundaryHosts = ({
-	boundaryId,
-	keepPortalHostName,
-}: {
-	boundaryId: string;
-	keepPortalHostName: string;
-}) => {
-	if (!activeBoundaryHosts.has(keepPortalHostName)) {
-		return;
-	}
-
-	let didDelete = false;
-
-	for (const [hostEntryKey, host] of activeBoundaryHosts) {
-		if (
-			host.boundaryId !== boundaryId ||
-			host.portalHostName === keepPortalHostName
-		) {
-			continue;
-		}
-
-		activeBoundaryHosts.delete(hostEntryKey);
-		didDelete = true;
-	}
-
-	if (!didDelete) {
-		return;
-	}
-
-	emit();
-};
-
 const subscribe = (listener: () => void) => {
 	listeners.add(listener);
 

package/src/shared/components/boundary/portal/utils/handoff-target.ts

@@ -0,0 +1,48 @@
+import { getLinkKeyFromTag } from "../../../../stores/bounds/helpers/link-pairs.helpers";
+import type {
+	LinkPairsState,
+	ScreenKey,
+	ScreenPairKey,
+} from "../../../../stores/bounds/types";
+
+type ResolveEnteringHandoffTargetParams = {
+	animationProgress: number;
+	boundaryId: string;
+	currentScreenKey: ScreenKey;
+	pairsState: LinkPairsState;
+	sourcePairKey?: ScreenPairKey;
+};
+
+/** Resolve only the immediate A -> B entering handoff. */
+export const resolveEnteringHandoffTarget = ({
+	animationProgress,
+	boundaryId,
+	currentScreenKey,
+	pairsState,
+	sourcePairKey,
+}: ResolveEnteringHandoffTargetParams): ScreenKey | null => {
+	"worklet";
+
+	if (!sourcePairKey || animationProgress <= 0) {
+		return null;
+	}
+
+	const pair = pairsState[sourcePairKey];
+	const linkKey = getLinkKeyFromTag(boundaryId);
+	const link = pair?.links[linkKey];
+
+	if (
+		link?.status !== "complete" ||
+		link.source.screenKey !== currentScreenKey ||
+		!link.source.handoff ||
+		!link.destination.handoff
+	) {
+		return null;
+	}
+
+	if (link.group && pair.groups[link.group]?.activeId !== linkKey) {
+		return null;
+	}
+
+	return link.destination.screenKey;
+};

package/src/shared/components/boundary/portal/utils/resolve-portal.ts

@@ -1,17 +1,33 @@
 import { logger } from "../../../../utils/logger";
 import { isTeleportAvailable } from "../teleport";
 
-export type BoundaryPortalRuntime = {
+export type BoundaryPortalRuntime = Readonly<{
 	handoff: boolean;
 	escapeClipping: boolean;
-	enabled: boolean;
-};
+}>;
 
 type ResolveBoundaryPortalParams = {
 	handoff?: boolean;
 	escapeClipping?: boolean;
 };
 
+const DISABLED_RUNTIME: BoundaryPortalRuntime = {
+	handoff: false,
+	escapeClipping: false,
+};
+const HANDOFF_RUNTIME: BoundaryPortalRuntime = {
+	handoff: true,
+	escapeClipping: false,
+};
+const ESCAPE_CLIPPING_RUNTIME: BoundaryPortalRuntime = {
+	handoff: false,
+	escapeClipping: true,
+};
+const HANDOFF_ESCAPE_CLIPPING_RUNTIME: BoundaryPortalRuntime = {
+	handoff: true,
+	escapeClipping: true,
+};
+
 export const resolveBoundaryPortal = ({
 	handoff,
 	escapeClipping,
@@ -22,11 +38,7 @@ export const resolveBoundaryPortal = ({
 	const enabled = resolvedHandoff || resolvedEscapeClipping;
 
 	if (!enabled) {
-		return {
-			handoff: false,
-			escapeClipping: false,
-			enabled: false,
-		};
+		return DISABLED_RUNTIME;
 	}
 
 	if (!isTeleportAvailable) {
@@ -35,16 +47,12 @@ export const resolveBoundaryPortal = ({
 			"react-native-teleport is not installed; handoff and escapeClipping boundaries will render inline.",
 		);
 
-		return {
-			handoff: false,
-			escapeClipping: false,
-			enabled: false,
-		};
+		return DISABLED_RUNTIME;
 	}
 
-	return {
-		handoff: resolvedHandoff,
-		escapeClipping: resolvedEscapeClipping,
-		enabled,
-	};
+	return resolvedHandoff
+		? resolvedEscapeClipping
+			? HANDOFF_ESCAPE_CLIPPING_RUNTIME
+			: HANDOFF_RUNTIME
+		: ESCAPE_CLIPPING_RUNTIME;
 };

package/src/shared/components/boundary/portal/utils/teleport-control.ts

@@ -11,15 +11,3 @@ export const isTeleportEnabled = (
 
 	return teleport?.enabled !== false;
 };
-
-export const shouldAttachBoundaryPortal = ({
-	enabled,
-	teleport,
-}: {
-	enabled: boolean;
-	teleport?: BoundaryTeleportControl;
-}) => {
-	"worklet";
-
-	return enabled && isTeleportEnabled(teleport);
-};

package/src/shared/components/boundary/providers/boundary-root.provider.tsx

@@ -1,14 +1,13 @@
 import {
 	type ForwardedRef,
 	type ReactNode,
-	useCallback,
 	useImperativeHandle,
+	useLayoutEffect,
 	useMemo,
 	useRef,
-	useState,
 } from "react";
 import type { View } from "react-native";
-import type { AnimatedRef, StyleProps } from "react-native-reanimated";
+import type { AnimatedRef } from "react-native-reanimated";
 import { useAnimatedRef } from "react-native-reanimated";
 import { useDescriptorsStore } from "../../../providers/screen/descriptors";
 import {
@@ -30,28 +29,11 @@ import type {
 	BoundaryOwnProps,
 } from "../types";
 
-interface BoundaryRootContextValue extends BoundaryRootRenderState {
-	registerTargetRef: (
-		targetRef: AnimatedRef<View>,
-		preparedStyles: StyleProps,
-		measurementRef?: AnimatedRef<View>,
-	) => void;
-	unregisterTargetRef: (targetRef: AnimatedRef<View>) => void;
-	activeTargetRef: AnimatedRef<View> | null;
-	boundTag: BoundTag;
-	portalRuntime: BoundaryPortalRuntime;
-}
-
-type BoundaryTargetEntry = {
-	ref: AnimatedRef<View>;
-	/** Surface to measure — the portal placeholder when content can teleport. */
-	measurementRef: AnimatedRef<View>;
-	preparedStyles: StyleProps;
-};
+type BoundaryRootContextValue = BoundaryRootRenderState;
 
 // logger.warn prepends the library prefix.
 const MULTIPLE_TARGETS_WARNING =
-	"Multiple Boundary.Target elements were rendered under the same boundary root. The first registered target will be measured.";
+	"Multiple Boundary.Target elements were rendered under the same boundary root. The first target in render order will be measured.";
 
 export const TARGET_OUTSIDE_ROOT_WARNING =
 	"Boundary.Target must be rendered inside Transition.Boundary or a component created by createBoundaryComponent.";
@@ -61,9 +43,9 @@ export type BoundaryRootRenderState = {
 	boundTag: BoundTag;
 	currentScreenKey: string;
 	handoffEnabled: boolean;
+	measurementRef: AnimatedRef<View>;
 	portalRuntime: BoundaryPortalRuntime;
 	ref: AnimatedRef<View>;
-	rootEscapePlaceholderRef: AnimatedRef<View>;
 	shouldRenderBoundaryRootThroughPortal: boolean;
 	shouldRenderHandoffHost: boolean;
 };
@@ -75,8 +57,11 @@ type BoundaryRootProviderProps = Pick<
 	children: (state: BoundaryRootRenderState) => ReactNode;
 	config: BoundaryConfigProps;
 	forwardedRef?: ForwardedRef<any>;
+	hasTarget: boolean;
 	id: BoundaryId;
 	style?: unknown;
+	targetCount: number;
+	targetStyle?: unknown;
 };
 
 export const {
@@ -95,8 +80,11 @@ export const {
 		forwardedRef,
 		group,
 		handoff,
+		hasTarget,
 		id,
 		style,
+		targetCount,
+		targetStyle,
 	}) => {
 		const requestedBoundTag = useMemo(
 			() => createBoundTag(String(id), group),
@@ -137,51 +125,18 @@ export const {
 		const associatedStyles = useComposedSlotStyles(boundTag.tag, style);
 		const associatedStackingStyles = useSlotStackingStyles(boundTag.tag);
 		const rootRef = useAnimatedRef<View>();
-		const rootEscapePlaceholderRef = useAnimatedRef<View>();
-		const [targetEntry, setTargetEntry] = useState<BoundaryTargetEntry | null>(
-			null,
-		);
-
-		const registerTargetRef = useCallback(
-			(
-				targetRef: AnimatedRef<View>,
-				preparedStyles: StyleProps,
-				measurementRef?: AnimatedRef<View>,
-			) => {
-				setTargetEntry((prev) => {
-					if (prev?.ref === targetRef) {
-						return prev;
-					}
-
-					if (__DEV__ && prev !== null) {
-						logger.warnOnce(
-							"boundary:multiple-targets",
-							MULTIPLE_TARGETS_WARNING,
-						);
-					}
-
-					return (
-						prev ?? {
-							ref: targetRef,
-							measurementRef: measurementRef ?? targetRef,
-							preparedStyles,
-						}
-					);
-				});
-			},
-			[],
-		);
+		const measurementRef = useAnimatedRef<View>();
 
-		const unregisterTargetRef = useCallback((targetRef: AnimatedRef<View>) => {
-			setTargetEntry((prev) => (prev?.ref === targetRef ? null : prev));
-		}, []);
+		useLayoutEffect(() => {
+			if (__DEV__ && targetCount > 1) {
+				logger.warnOnce("boundary:multiple-targets", MULTIPLE_TARGETS_WARNING);
+			}
+		}, [targetCount]);
 
-		const rootMeasurementRef = shouldEscapeBoundaryRootToScreenHost
-			? rootEscapePlaceholderRef
-			: rootRef;
-		const measuredRef = targetEntry?.measurementRef ?? rootMeasurementRef;
-		const hasActiveTarget = targetEntry !== null;
-		const targetPreparedStyles = targetEntry?.preparedStyles;
+		const measuredRef =
+			hasTarget || shouldEscapeBoundaryRootToScreenHost
+				? measurementRef
+				: rootRef;
 
 		useImperativeHandle(forwardedRef, () => rootRef.current as any, [rootRef]);
 
@@ -191,15 +146,14 @@ export const {
 			runtimeEnabled,
 			currentScreenKey,
 			measuredRef,
-			style,
-			targetPreparedStyles,
+			style: hasTarget ? targetStyle : style,
 			handoff: portalRuntime.handoff,
 			escapeClipping: portalRuntime.escapeClipping,
 			config,
 		});
 
 		const shouldRenderBoundaryRootThroughPortal =
-			shouldEscapeBoundaryRootToScreenHost && !hasActiveTarget;
+			shouldEscapeBoundaryRootToScreenHost && !hasTarget;
 		const handoffEnabled = enabled && portalRuntime.handoff;
 		// A nested active target takes the full associated style, so the root keeps
 		// only its stacking context. Root-owned escape-clipping moves the root
@@ -209,7 +163,7 @@ export const {
 		// handoff host is absolute-filled inside this root, so the root is the
 		// visual frame that animates the received payload.
 		const attachedStyle = shouldAttachAssociatedStyles
-			? hasActiveTarget
+			? hasTarget
 				? associatedStackingStyles
 				: shouldRenderBoundaryRootThroughPortal
 					? undefined
@@ -219,31 +173,25 @@ export const {
 		const value = useMemo<BoundaryRootContextValue>(
 			() => ({
 				attachedStyle,
-				activeTargetRef: targetEntry?.ref ?? null,
 				boundTag,
 				currentScreenKey,
 				handoffEnabled,
+				measurementRef,
 				portalRuntime,
-				registerTargetRef,
 				ref: rootRef,
-				rootEscapePlaceholderRef,
 				shouldRenderBoundaryRootThroughPortal,
-				shouldRenderHandoffHost: handoffEnabled && !hasActiveTarget,
-				unregisterTargetRef,
+				shouldRenderHandoffHost: handoffEnabled && !hasTarget,
 			}),
 			[
 				attachedStyle,
 				boundTag,
 				currentScreenKey,
 				handoffEnabled,
-				hasActiveTarget,
+				hasTarget,
+				measurementRef,
 				portalRuntime,
-				registerTargetRef,
 				rootRef,
-				rootEscapePlaceholderRef,
 				shouldRenderBoundaryRootThroughPortal,
-				targetEntry,
-				unregisterTargetRef,
 			],
 		);
 

package/src/shared/components/boundary/utils/refresh-signals.ts

@@ -40,6 +40,7 @@ export const getRefreshBoundarySignal = (params: {
 	entering: boolean;
 	animating: boolean;
 	progress: number;
+	gestureInProgress: boolean;
 	linkState?: LinkPairsState;
 }): RefreshBoundarySignal | null => {
 	"worklet";
@@ -57,11 +58,18 @@ export const getRefreshBoundarySignal = (params: {
 		entering,
 		animating,
 		progress,
+		gestureInProgress,
 		linkState,
 	} = params;
 
 	if (!enabled) return null;
 
+	// This is temporary for a patch fix. However, this architecture should
+	// change: our signals aren't currently doing their intended job, so right
+	// now we'll add one more guard until the shape is much more tested and
+	// bulletproof.
+	if (gestureInProgress) return null;
+
 	const canRefreshPreCloseDestination =
 		shouldRefresh && closing && !entering && !animating && progress >= 1;
 

package/src/shared/components/boundary/utils/resolve-boundary-target.tsx

@@ -0,0 +1,39 @@
+import {
+	Children,
+	cloneElement,
+	Fragment,
+	isValidElement,
+	type ReactElement,
+	type ReactNode,
+} from "react";
+
+type ResolveBoundaryTargetOptions = {
+	isTarget: (element: ReactElement) => boolean;
+	mapTarget?: (element: ReactElement, selected: boolean) => ReactElement;
+};
+
+export const resolveBoundaryTarget = (
+	children: ReactNode,
+	options: ResolveBoundaryTargetOptions,
+): {
+	children: ReactNode;
+	target: ReactElement | null;
+	targetCount: number;
+} => {
+	let target: ReactElement | null = null;
+	let targetCount = 0;
+	const map = (nodes: ReactNode): ReactNode =>
+		Children.map(nodes, (node) => {
+			if (!isValidElement<{ children?: ReactNode }>(node)) return node;
+			if (node.type === Fragment) {
+				return cloneElement(node, undefined, map(node.props.children));
+			}
+			if (!options.isTarget(node)) return node;
+			target ??= node;
+			targetCount += 1;
+			return options.mapTarget?.(node, targetCount === 1) ?? node;
+		});
+
+	const mappedChildren = map(children);
+	return { children: target ? mappedChildren : children, target, targetCount };
+};

package/src/shared/components/masked-view.tsx

@@ -1,4 +1,10 @@
-import { type StyleProp, StyleSheet, View, type ViewStyle } from "react-native";
+import {
+	I18nManager,
+	type StyleProp,
+	StyleSheet,
+	View,
+	type ViewStyle,
+} from "react-native";
 import { CONTAINER_STYLE_ID, MASK_STYLE_ID } from "../constants";
 import { createTransitionAwareComponent } from "./create-transition-aware-component";
 
@@ -49,9 +55,19 @@ const styles = StyleSheet.create({
 	root: {
 		flex: 1,
 	},
-	rootMask: {
-		backgroundColor: "white",
-	},
+	// The mask rect's translate math assumes a physical top-left base. Under
+	// native RTL a fixed-width flex child anchors to the right edge, so pin it
+	// to the physical left (`end` = left edge in RTL).
+	rootMask: I18nManager.isRTL
+		? {
+				backgroundColor: "white",
+				end: 0,
+				position: "absolute",
+				top: 0,
+			}
+		: {
+				backgroundColor: "white",
+			},
 	rootContainer: {
 		flex: 1,
 	},

package/src/shared/components/screen-container/layers/backdrop.tsx

@@ -29,7 +29,7 @@ export const BackdropLayer = memo(function BackdropLayer({
 	const BackdropComponent = current.options.backdropComponent;
 	const routeKey = current.route.key;
 	const animations = AnimationStore.getBag(routeKey);
-	const { targetProgress, resolvedAutoSnapPoint } =
+	const { targetProgress, animationProgress, resolvedAutoSnapPoint } =
 		SystemStore.getBag(routeKey);
 
 	const AnimatedBackdropComponent = useMemo(
@@ -98,6 +98,7 @@ export const BackdropLayer = memo(function BackdropLayer({
 					spec,
 					animations,
 					targetProgress,
+					animationProgress,
 					onAnimationFinish: shouldDismiss ? dismissScreen : undefined,
 				});
 			})();
@@ -105,6 +106,7 @@ export const BackdropLayer = memo(function BackdropLayer({
 	}, [
 		animations,
 		targetProgress,
+		animationProgress,
 		resolvedAutoSnapPoint,
 		backdropBehavior,
 		current,

package/src/shared/components/screen-container/layers/maybe-masked-navigation-container.tsx

@@ -1,5 +1,5 @@
 import { memo, useCallback } from "react";
-import { StyleSheet, View, type ViewProps } from "react-native";
+import { I18nManager, StyleSheet, View, type ViewProps } from "react-native";
 import Animated from "react-native-reanimated";
 import {
 	NAVIGATION_MASK_CONTAINER_STYLE_ID,
@@ -97,7 +97,17 @@ const styles = StyleSheet.create({
 	navigationContainer: {
 		flex: 1,
 	},
-	navigationMaskElement: {
-		backgroundColor: "white",
-	},
+	// The mask rect's translate math assumes a physical top-left base. Under
+	// native RTL a fixed-width flex child anchors to the right edge, so pin it
+	// to the physical left (`end` = left edge in RTL).
+	navigationMaskElement: I18nManager.isRTL
+		? {
+				backgroundColor: "white",
+				end: 0,
+				position: "absolute",
+				top: 0,
+			}
+		: {
+				backgroundColor: "white",
+			},
 });

package/src/shared/components/screen-lifecycle/hooks/use-transition-start-controller.ts

@@ -22,6 +22,7 @@ export const useTransitionStartController = ({
 }) => {
 	const {
 		targetProgress,
+		animationProgress,
 		pendingLifecycleRequestKind,
 		pendingLifecycleRequestTarget,
 		pendingLifecycleStartBlockCount,
@@ -62,6 +63,7 @@ export const useTransitionStartController = ({
 				spec: transitionSpec,
 				animations,
 				targetProgress,
+				animationProgress,
 				onAnimationFinish,
 			});