react-native-screen-transitions 4.1.0-beta.0 → 4.1.0-rc.0

package/src/components/boundary/portal/components/portal-overlay.tsx

@@ -0,0 +1,219 @@
+import { memo, useId, useLayoutEffect } from "react";
+import {
+	I18nManager,
+	type StyleProp,
+	StyleSheet,
+	useWindowDimensions,
+	View,
+	type ViewStyle,
+} from "react-native";
+import Animated, {
+	type MeasuredDimensions,
+	type SharedValue,
+	useAnimatedReaction,
+	useAnimatedStyle,
+} from "react-native-reanimated";
+import { NO_STYLES } from "../../../../constants";
+import { useBuilderStore } from "../../../../providers/builder";
+import { composeSlotStyleWithLocalTransform } from "../../../../providers/orchestrator/styles/helpers/compose-slot-style";
+import { resolvePortalOffsetStyle } from "../helpers/offset-style";
+import { useHostMeasurement } from "../hooks/use-host-measurement";
+import { registerHost, unregisterHost } from "../stores/host-registry.store";
+import {
+	type ActivePortalBoundaryHost,
+	useActivePortalBoundaryHosts,
+} from "../stores/portal-boundary-host.store";
+import { PORTAL_POINTER_EVENTS } from "../teleport";
+import { PortalHost } from "./portal-host";
+
+type PortalOverlayProps = {
+	style?: StyleProp<ViewStyle>;
+	fallback?: boolean;
+};
+
+/**
+ * A screen-sized overlay containing the receivers for escaped boundary frames.
+ *
+ * Registers this overlay as an available placement, measures its origin, and
+ * renders one positioned PortalHost per boundary assigned to it. An overlay can
+ * contain many hosts; each host receives one named portal.
+ *
+ * Boundary.Host uses this directly; screens render it with `fallback` for
+ * their automatic overlay. Explicit overlays take priority over the fallback.
+ * Handoff between screens uses receivers inside boundaries, so it does not
+ * need this overlay unless escapeClipping is also enabled.
+ */
+export const PortalOverlay = memo(function PortalOverlay({
+	fallback = false,
+	style,
+}: PortalOverlayProps) {
+	const screenKey = useBuilderStore((s) => s.derivations.currentScreenKey);
+	const id = useId();
+	const hostKey = fallback ? screenKey : `${screenKey}-host-${id}`;
+	const activeBoundaryHosts = useActivePortalBoundaryHosts(hostKey);
+
+	const { height: viewportHeight, width: viewportWidth } =
+		useWindowDimensions();
+
+	const measurement = useHostMeasurement({
+		enabled: activeBoundaryHosts.length > 0,
+		boundaryMeasurements: activeBoundaryHosts.map(
+			(host) => host.localMeasurement,
+		),
+	});
+
+	const boundaryHosts = activeBoundaryHosts.map((host) => (
+		<View
+			key={host.portalHostName}
+			pointerEvents={PORTAL_POINTER_EVENTS}
+			style={[
+				styles.boundaryHostViewport,
+				{ width: viewportWidth, height: viewportHeight },
+			]}
+		>
+			<BoundaryPortalPlacement
+				host={host}
+				hostBounds={measurement.hostBounds}
+			/>
+		</View>
+	));
+
+	useLayoutEffect(() => {
+		registerHost({
+			fallback,
+			hostKey,
+			screenKey,
+		});
+
+		return () => {
+			unregisterHost(screenKey, hostKey);
+		};
+	}, [fallback, hostKey, screenKey]);
+
+	return (
+		<Animated.View
+			ref={measurement.hostRef}
+			pointerEvents={PORTAL_POINTER_EVENTS}
+			style={[
+				styles.host,
+				{ width: viewportWidth, height: viewportHeight },
+				style,
+			]}
+			collapsable={false}
+		>
+			{boundaryHosts}
+		</Animated.View>
+	);
+});
+
+const getCurrentBoundaryBounds = (host: ActivePortalBoundaryHost) => {
+	"worklet";
+	return host.localMeasurement.get()?.bounds ?? null;
+};
+
+type BoundaryPortalPlacementProps = {
+	host: ActivePortalBoundaryHost;
+	hostBounds: SharedValue<MeasuredDimensions | null>;
+};
+
+/** Positions one receiver using captured boundary and overlay measurements. */
+const BoundaryPortalPlacement = memo(function BoundaryPortalPlacement({
+	host,
+	hostBounds,
+}: BoundaryPortalPlacementProps) {
+	useAnimatedReaction(
+		() => {
+			"worklet";
+			return (
+				getCurrentBoundaryBounds(host) !== null && hostBounds.get() !== null
+			);
+		},
+		(ready) => {
+			"worklet";
+			host.portalHostReady.set(ready);
+		},
+	);
+
+	const hostStyle = useAnimatedStyle(() => {
+		"worklet";
+		const boundaryBounds = getCurrentBoundaryBounds(host);
+		if (!boundaryBounds) {
+			return NO_STYLES;
+		}
+
+		return resolvePortalOffsetStyle({
+			bounds: boundaryBounds,
+			hostBounds: hostBounds.get(),
+		});
+	});
+
+	const contentFrameStyle = useAnimatedStyle(() => {
+		"worklet";
+		const boundaryBounds = getCurrentBoundaryBounds(host);
+		if (!boundaryBounds) {
+			return NO_STYLES;
+		}
+
+		return {
+			height: boundaryBounds.height,
+			width: boundaryBounds.width,
+		};
+	});
+
+	const slotStyle = useAnimatedStyle(() => {
+		"worklet";
+		const slot = host.slotsMap.get()[host.boundaryId];
+
+		return composeSlotStyleWithLocalTransform(
+			slot?.style ?? NO_STYLES,
+			undefined,
+			slot?.boundsLocalTransform,
+		);
+	});
+
+	return (
+		<Animated.View
+			pointerEvents={PORTAL_POINTER_EVENTS}
+			style={[StyleSheet.absoluteFill, hostStyle]}
+			collapsable={false}
+		>
+			<PortalHost
+				name={host.portalHostName}
+				style={[styles.content, contentFrameStyle, slotStyle]}
+			/>
+		</Animated.View>
+	);
+});
+
+const styles = StyleSheet.create({
+	// The teleport offset is a physical page delta measured from the screen's
+	// left edge, so the content box must anchor there too. Under native RTL,
+	// `left: 0` swaps to a right-edge anchor; `end: 0` is the physical left edge
+	// in RTL regardless of the swap setting.
+	content: I18nManager.isRTL
+		? {
+				end: 0,
+				position: "absolute",
+				top: 0,
+			}
+		: {
+				left: 0,
+				position: "absolute",
+				top: 0,
+			},
+
+	host: {
+		elevation: 999999,
+		left: 0,
+		overflow: "visible",
+		position: "absolute",
+		top: 0,
+		zIndex: 999999,
+	},
+	boundaryHostViewport: {
+		left: 0,
+		overflow: "visible",
+		position: "absolute",
+		top: 0,
+	},
+});

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

@@ -0,0 +1,124 @@
+import {
+	type ComponentProps,
+	type ComponentType,
+	memo,
+	type ReactNode,
+} from "react";
+import { StyleSheet, type View } from "react-native";
+import Animated, { type AnimatedRef } from "react-native-reanimated";
+import { scheduleOnUI } from "react-native-worklets";
+import { logger } from "../../../../utils/logger";
+import { usePlaceholderStyles } from "../hooks/use-placeholder-styles";
+import {
+	type PortalMode,
+	usePortalDestination,
+} from "../hooks/use-portal-destination";
+import {
+	isTeleportAvailable,
+	NativePortal,
+	PORTAL_POINTER_EVENTS,
+} from "../teleport";
+import { PortalHost } from "./portal-host";
+
+type NullableHostNamePortalProps = Omit<
+	ComponentProps<NonNullable<typeof NativePortal>>,
+	"hostName"
+> & { hostName?: string | null };
+const AnimatedNativePortal = NativePortal
+	? Animated.createAnimatedComponent(
+			NativePortal as ComponentType<NullableHostNamePortalProps>,
+		)
+	: null;
+const EnabledNativePortal = AnimatedNativePortal as NonNullable<
+	typeof AnimatedNativePortal
+>;
+
+type PortalProps = {
+	boundaryId?: string;
+	children: ReactNode;
+	enabled: boolean;
+	mode: PortalMode;
+	placeholderRef?: AnimatedRef<View>;
+};
+
+/**
+ * Sends its children to a named PortalHost chosen on the UI thread.
+ *
+ * `handoff` moves the boundary's content between screens and creates a local
+ * receiver inside this boundary. `escapeClipping` moves the whole boundary
+ * frame into a PortalOverlay, leaving a sized placeholder at its original spot.
+ * When both are enabled, the handoff portal lives inside the escaped frame.
+ * Disabled portals, or apps without Teleport, render their children inline.
+ */
+export const Portal = memo(function Portal(props: PortalProps) {
+	if (
+		!props.enabled ||
+		props.boundaryId === undefined ||
+		!isTeleportAvailable ||
+		!AnimatedNativePortal
+	) {
+		return props.children;
+	}
+
+	return <EnabledPortal {...props} boundaryId={props.boundaryId} />;
+});
+
+function EnabledPortal({
+	boundaryId,
+	children,
+	mode,
+	placeholderRef,
+}: PortalProps & { boundaryId: string }) {
+	if (__DEV__ && mode === "escapeClipping" && !boundaryId) {
+		logger.warnOnce(
+			"portal:missing-id",
+			"A boundary portal was rendered without an id; rendering inline.",
+		);
+	}
+	const { teleportProps, localHostName } = usePortalDestination(
+		boundaryId,
+		mode,
+	);
+
+	const content = (
+		<EnabledNativePortal
+			animatedProps={teleportProps}
+			name={boundaryId}
+			pointerEvents={PORTAL_POINTER_EVENTS}
+			style={mode === "handoff" ? StyleSheet.absoluteFill : undefined}
+		>
+			{children}
+		</EnabledNativePortal>
+	);
+
+	return mode === "handoff" ? (
+		<>
+			{content}
+			<PortalHost name={localHostName} />
+		</>
+	) : (
+		<PortalPlaceholder placeholderRef={placeholderRef}>
+			{content}
+		</PortalPlaceholder>
+	);
+}
+
+function PortalPlaceholder({
+	children,
+	placeholderRef,
+}: Pick<PortalProps, "children" | "placeholderRef">) {
+	const { handleOnLayout, placeholderStyle } = usePlaceholderStyles();
+	return (
+		<Animated.View
+			ref={placeholderRef}
+			onLayout={({ nativeEvent: { layout } }) =>
+				scheduleOnUI(handleOnLayout, layout)
+			}
+			style={placeholderStyle}
+			pointerEvents={PORTAL_POINTER_EVENTS}
+			collapsable={false}
+		>
+			{children}
+		</Animated.View>
+	);
+}

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

@@ -0,0 +1,52 @@
+import { useLayoutEffect } from "react";
+import type { SharedValue } from "react-native-reanimated";
+import type { NormalizedTransitionInterpolatedStyle } from "../../../../types/animation.types";
+import type { BoundaryLocalMeasurementValue } from "../../types";
+import {
+	mountPortalBoundaryHost,
+	unmountPortalBoundaryHostByName,
+} from "../stores/portal-boundary-host.store";
+import { createBoundaryPortalHostName } from "../utils/naming";
+
+// Hosts belong to mounted boundaries, not animation phases. React prepares
+// them once; attachment and release are entirely UI-thread decisions.
+export const useActivePortalBoundaryHost = ({
+	boundaryId,
+	escapeHostKey,
+	localMeasurement,
+	portalHostReady,
+	slotsMap,
+}: {
+	boundaryId: string;
+	escapeHostKey?: string;
+	localMeasurement: BoundaryLocalMeasurementValue;
+	portalHostReady: SharedValue<boolean>;
+	slotsMap: SharedValue<NormalizedTransitionInterpolatedStyle>;
+}) => {
+	const portalHostName = escapeHostKey
+		? createBoundaryPortalHostName(escapeHostKey, boundaryId)
+		: null;
+
+	useLayoutEffect(() => {
+		if (!escapeHostKey || !portalHostName) return;
+
+		mountPortalBoundaryHost({
+			boundaryId,
+			hostKey: escapeHostKey,
+			localMeasurement,
+			portalHostName,
+			portalHostReady,
+			slotsMap,
+		});
+
+		return () => unmountPortalBoundaryHostByName(portalHostName);
+	}, [
+		boundaryId,
+		escapeHostKey,
+		localMeasurement,
+		portalHostName,
+		portalHostReady,
+		slotsMap,
+	]);
+	return portalHostName;
+};

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

@@ -0,0 +1,82 @@
+import type { View } from "react-native";
+import {
+	cancelAnimation,
+	type MeasuredDimensions,
+	measure,
+	useAnimatedReaction,
+	useAnimatedRef,
+	useSharedValue,
+	withDelay,
+	withTiming,
+} from "react-native-reanimated";
+import type { BoundaryLocalMeasurementValue } from "../../types";
+
+const HOST_MEASUREMENT_RETRY_DELAY_MS = 16;
+const MAX_HOST_MEASUREMENT_ATTEMPTS = 20;
+
+type UseHostMeasurementParams = {
+	enabled: boolean;
+	boundaryMeasurements: BoundaryLocalMeasurementValue[];
+};
+
+export const useHostMeasurement = ({
+	enabled,
+	boundaryMeasurements,
+}: UseHostMeasurementParams) => {
+	const hostRef = useAnimatedRef<View>();
+	const hostBounds = useSharedValue<MeasuredDimensions | null>(null);
+	const retryToken = useSharedValue(0);
+	const attempts = useSharedValue(0);
+
+	const measureHost = () => {
+		"worklet";
+		const count = attempts.get() + 1;
+		attempts.set(count);
+		const measured = measure(hostRef);
+		if (measured && measured.width > 0 && measured.height > 0) {
+			hostBounds.set({ ...measured });
+		} else if (count < MAX_HOST_MEASUREMENT_ATTEMPTS) {
+			retryToken.set(
+				withDelay(
+					HOST_MEASUREMENT_RETRY_DELAY_MS,
+					withTiming(count, { duration: 0 }),
+				),
+			);
+		}
+	};
+
+	useAnimatedReaction(
+		() => {
+			"worklet";
+			if (!enabled) return null;
+			const captures = [];
+			let hasSource = false;
+			for (const value of boundaryMeasurements) {
+				const capture = value.get();
+				captures.push(capture);
+				if (capture) hasSource = true;
+			}
+			return hasSource ? captures : null;
+		},
+		(captures) => {
+			"worklet";
+			cancelAnimation(retryToken);
+			retryToken.set(0);
+			attempts.set(0);
+			hostBounds.set(null);
+			// Measure anew on every source capture, even for the same portal/pair.
+			// Hold only this transition's position; never reuse an earlier capture.
+			if (captures) measureHost();
+		},
+	);
+
+	useAnimatedReaction(
+		() => retryToken.get(),
+		(token) => {
+			"worklet";
+			if (token > 0) measureHost();
+		},
+	);
+
+	return { hostBounds, hostRef };
+};

package/src/components/boundary/portal/hooks/use-portal-destination.ts

@@ -0,0 +1,53 @@
+import { useAnimatedProps, useSharedValue } from "react-native-reanimated";
+import { useBoundaryRootStore } from "../../providers/boundary-root.provider";
+import { useActiveHostKey } from "../stores/host-registry.store";
+import {
+	createHandoffHostName,
+	PORTAL_HOST_NAME_RESET_VALUE,
+} from "../utils/naming";
+import { useActivePortalBoundaryHost } from "./use-active-portal-boundary-host";
+
+export type PortalMode = "handoff" | "escapeClipping";
+
+export function usePortalDestination(boundaryId: string, mode: PortalMode) {
+	const { currentScreenKey, localMeasurement, slotsMap, boundaryPresentation } =
+		useBoundaryRootStore((s) => s);
+	const portalHostReady = useSharedValue(false);
+	const escapeHostKey = useActiveHostKey(
+		mode === "escapeClipping" ? currentScreenKey : null,
+	);
+	const portalHostName = useActivePortalBoundaryHost({
+		boundaryId,
+		escapeHostKey,
+		localMeasurement,
+		portalHostReady,
+		slotsMap,
+	});
+	const teleportProps = useAnimatedProps(() => {
+		"worklet";
+		const { owner, receiver, slots } = boundaryPresentation.get();
+		const slot = slots[boundaryId];
+		const {
+			pointerEvents: _pointerEvents,
+			handoffTarget: _handoffTarget,
+			...props
+		} = slot?.props ?? {};
+		let hostName: string | null = PORTAL_HOST_NAME_RESET_VALUE;
+		if (mode === "handoff") {
+			hostName = createHandoffHostName(receiver, boundaryId);
+		} else if (
+			owner?.ready &&
+			localMeasurement.get()?.pairKey === owner.pairKey &&
+			slot !== undefined &&
+			portalHostReady.get()
+		) {
+			hostName = portalHostName;
+		}
+
+		return { ...props, hostName };
+	});
+	return {
+		teleportProps,
+		localHostName: createHandoffHostName(currentScreenKey, boundaryId),
+	};
+}

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

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

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

@@ -0,0 +1,115 @@
+import { useSyncExternalStore } from "react";
+
+export type HostRegistration = {
+	hostKey: string;
+	screenKey: string;
+	fallback: boolean;
+};
+
+const listeners = new Set<() => void>();
+const hostStacks = new Map<string, HostRegistration[]>();
+
+/**
+ * The active host for a screen. Stack ordering is the load-bearing invariant:
+ * `registerHost` unshifts fallback hosts to the front and pushes real hosts to
+ * the back, so the active host is the last real (non-fallback) host, falling
+ * back to the first entry and finally to the screen's own key.
+ */
+const getActiveHostFromStack = (
+	screenKey: string,
+	stack: HostRegistration[] | undefined,
+) => {
+	if (!stack || stack.length === 0) {
+		return screenKey;
+	}
+
+	for (let index = stack.length - 1; index >= 0; index--) {
+		const host = stack[index];
+		if (!host.fallback) {
+			return host.hostKey;
+		}
+	}
+
+	return stack[0]?.hostKey ?? screenKey;
+};
+
+const emit = () => {
+	for (const listener of listeners) {
+		listener();
+	}
+};
+
+const subscribe = (listener: () => void) => {
+	listeners.add(listener);
+
+	return () => {
+		listeners.delete(listener);
+	};
+};
+
+export const registerHost = (registration: HostRegistration) => {
+	const stack = hostStacks.get(registration.screenKey) ?? [];
+	const previousActiveHostKey = getActiveHostFromStack(
+		registration.screenKey,
+		stack,
+	);
+	const nextStack = stack.filter(
+		(host) => host.hostKey !== registration.hostKey,
+	);
+
+	if (registration.fallback) {
+		nextStack.unshift(registration);
+	} else {
+		nextStack.push(registration);
+	}
+
+	hostStacks.set(registration.screenKey, nextStack);
+
+	if (
+		previousActiveHostKey ===
+		getActiveHostFromStack(registration.screenKey, nextStack)
+	) {
+		return;
+	}
+
+	emit();
+};
+
+export const unregisterHost = (screenKey: string, hostKey: string) => {
+	const stack = hostStacks.get(screenKey);
+	if (!stack) {
+		return;
+	}
+
+	const previousActiveHostKey = getActiveHostFromStack(screenKey, stack);
+	const nextStack = stack.filter((host) => host.hostKey !== hostKey);
+
+	if (nextStack.length === 0) {
+		hostStacks.delete(screenKey);
+	} else {
+		hostStacks.set(screenKey, nextStack);
+	}
+
+	if (previousActiveHostKey === getActiveHostFromStack(screenKey, nextStack)) {
+		return;
+	}
+
+	emit();
+};
+
+export const getActiveHostKey = (screenKey: string) => {
+	return getActiveHostFromStack(screenKey, hostStacks.get(screenKey));
+};
+
+export const useActiveHostKey = (screenKey?: string | null) => {
+	return useSyncExternalStore(
+		subscribe,
+		() => (screenKey ? getActiveHostKey(screenKey) : undefined),
+		() => undefined,
+	);
+};
+
+export const resetHostRegistry = () => {
+	hostStacks.clear();
+	emit();
+};