react-native-screen-transitions 4.1.0-alpha.0 → 4.1.0-beta.1

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,101 @@
+import type { View } from "react-native";
+import {
+	cancelAnimation,
+	type MeasuredDimensions,
+	measure,
+	useAnimatedReaction,
+	useAnimatedRef,
+	useDerivedValue,
+	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 = {
+	measurementKey: string | null;
+	boundaryMeasurements: BoundaryLocalMeasurementValue[];
+};
+
+export const useHostMeasurement = ({
+	measurementKey,
+	boundaryMeasurements,
+}: UseHostMeasurementParams) => {
+	const hostRef = useAnimatedRef<View>();
+	const measurement = useSharedValue<{
+		key: string;
+		bounds: MeasuredDimensions;
+	} | null>(null);
+	const hostBounds = useDerivedValue(() => {
+		const captured = measurement.get();
+		return captured?.key === measurementKey ? captured.bounds : null;
+	});
+	const retryToken = useSharedValue(0);
+	const attempts = useSharedValue({ key: measurementKey, count: 0 });
+
+	useAnimatedReaction(
+		() => {
+			"worklet";
+			if (!measurementKey) {
+				return null;
+			}
+
+			// Hosts mount before their screen is visible. Wait for source capture
+			// rather than caching the screen's initial offscreen position.
+			let hasSource = false;
+			for (const measurement of boundaryMeasurements) {
+				if (measurement.get()) {
+					hasSource = true;
+					break;
+				}
+			}
+			if (!hasSource) return null;
+			return [
+				measurementKey,
+				measurement.get()?.key ?? null,
+				retryToken.get(),
+			] as const;
+		},
+		(state) => {
+			"worklet";
+			if (!state) {
+				cancelAnimation(retryToken);
+				return;
+			}
+
+			const [requestedKey, completedKey] = state;
+			if (requestedKey === completedKey) {
+				return;
+			}
+
+			cancelAnimation(retryToken);
+			const count =
+				attempts.get().key === requestedKey ? attempts.get().count : 0;
+			if (count >= MAX_HOST_MEASUREMENT_ATTEMPTS) return;
+			attempts.set({ key: requestedKey, count: count + 1 });
+
+			const measured = measure(hostRef);
+			if (!measured || measured.width <= 0 || measured.height <= 0) {
+				if (count + 1 < MAX_HOST_MEASUREMENT_ATTEMPTS) {
+					retryToken.set(
+						withDelay(
+							HOST_MEASUREMENT_RETRY_DELAY_MS,
+							withTiming(retryToken.get() + 1, { duration: 0 }),
+						),
+					);
+				}
+				return;
+			}
+
+			measurement.set({ key: requestedKey, bounds: { ...measured } });
+		},
+	);
+	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();
+};

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

@@ -0,0 +1,93 @@
+import { useSyncExternalStore } from "react";
+import type { SharedValue } from "react-native-reanimated";
+import type { NormalizedTransitionInterpolatedStyle } from "../../../../types/animation.types";
+import type { BoundaryLocalMeasurementValue } from "../../types";
+
+export type ActivePortalBoundaryHost = {
+	boundaryId: string;
+	hostKey: string;
+	localMeasurement: BoundaryLocalMeasurementValue;
+	portalHostName: string;
+	portalHostReady: SharedValue<boolean>;
+	slotsMap: SharedValue<NormalizedTransitionInterpolatedStyle>;
+};
+
+type PortalSnapshot = {
+	hostsByScope: Record<string, ActivePortalBoundaryHost[]>;
+};
+
+const EMPTY_HOSTS: ActivePortalBoundaryHost[] = [];
+
+const listeners = new Set<() => void>();
+const activeBoundaryHosts = new Map<string, ActivePortalBoundaryHost>();
+
+let snapshot: PortalSnapshot = {
+	hostsByScope: {},
+};
+
+// Preserve other overlays' snapshots so a registration only rerenders its owners.
+const emit = (...hostKeys: string[]) => {
+	const hostsByScope = { ...snapshot.hostsByScope };
+	for (const hostKey of new Set(hostKeys)) {
+		hostsByScope[hostKey] = Array.from(activeBoundaryHosts.values()).filter(
+			(host) => host.hostKey === hostKey,
+		);
+		if (!hostsByScope[hostKey].length) delete hostsByScope[hostKey];
+	}
+	snapshot = { hostsByScope };
+	for (const listener of listeners) listener();
+};
+
+const isSameHost = (
+	a: ActivePortalBoundaryHost,
+	b: ActivePortalBoundaryHost,
+) => {
+	return (
+		a.boundaryId === b.boundaryId &&
+		a.hostKey === b.hostKey &&
+		a.localMeasurement === b.localMeasurement &&
+		a.portalHostName === b.portalHostName &&
+		a.portalHostReady === b.portalHostReady &&
+		a.slotsMap === b.slotsMap
+	);
+};
+
+export const mountPortalBoundaryHost = (host: ActivePortalBoundaryHost) => {
+	const previous = activeBoundaryHosts.get(host.portalHostName);
+	if (previous && isSameHost(previous, host)) {
+		return;
+	}
+
+	activeBoundaryHosts.set(host.portalHostName, host);
+	emit(host.hostKey, previous?.hostKey ?? host.hostKey);
+};
+
+export const unmountPortalBoundaryHostByName = (
+	portalHostName: string | null | undefined,
+) => {
+	const host = portalHostName
+		? activeBoundaryHosts.get(portalHostName)
+		: undefined;
+	if (!host) {
+		return;
+	}
+
+	activeBoundaryHosts.delete(host.portalHostName);
+	emit(host.hostKey);
+};
+
+const subscribe = (listener: () => void) => {
+	listeners.add(listener);
+
+	return () => {
+		listeners.delete(listener);
+	};
+};
+
+export const useActivePortalBoundaryHosts = (hostKey: string) => {
+	return useSyncExternalStore(
+		subscribe,
+		() => snapshot.hostsByScope[hostKey] ?? EMPTY_HOSTS,
+		() => EMPTY_HOSTS,
+	);
+};

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

@@ -10,3 +10,13 @@ export const createBoundaryPortalHostName = (
 };
 
 export const PORTAL_HOST_NAME_RESET_VALUE = null;
+
+const BOUNDARY_CONTENT_PORTAL_HOST_NAME_SUFFIX = "-content-portal-host";
+
+export const createHandoffHostName = (
+	screenKey: string,
+	boundaryId: string,
+) => {
+	"worklet";
+	return `${screenKey}-${boundaryId}${BOUNDARY_CONTENT_PORTAL_HOST_NAME_SUFFIX}`;
+};

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

@@ -1,58 +1,19 @@
+import type { BoundaryRuntimeFlags } from "../../../../stores/bounds/types";
 import { logger } from "../../../../utils/logger";
 import { isTeleportAvailable } from "../teleport";
 
-export type BoundaryPortalRuntime = Readonly<{
-	handoff: boolean;
-	escapeClipping: 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,
-}: ResolveBoundaryPortalParams): BoundaryPortalRuntime => {
-	const resolvedHandoff = handoff ?? false;
-	const resolvedEscapeClipping = escapeClipping ?? false;
-
-	const enabled = resolvedHandoff || resolvedEscapeClipping;
-
-	if (!enabled) {
-		return DISABLED_RUNTIME;
-	}
-
-	if (!isTeleportAvailable) {
+	handoff = false,
+	escapeClipping = false,
+}: BoundaryRuntimeFlags) => {
+	if (!isTeleportAvailable && (handoff || escapeClipping)) {
 		logger.warnOnce(
 			"boundary:teleport-missing",
 			"react-native-teleport is not installed; handoff and escapeClipping boundaries will render inline.",
 		);
-
-		return DISABLED_RUNTIME;
 	}
-
-	return resolvedHandoff
-		? resolvedEscapeClipping
-			? HANDOFF_ESCAPE_CLIPPING_RUNTIME
-			: HANDOFF_RUNTIME
-		: ESCAPE_CLIPPING_RUNTIME;
+	return {
+		handoff: isTeleportAvailable && handoff,
+		escapeClipping: isTeleportAvailable && escapeClipping,
+	};
 };