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

package/src/components/boundary/helpers/presentation.ts

@@ -0,0 +1,88 @@
+import type { DerivedValue } from "react-native-reanimated";
+import { getLinkKeyFromTag } from "../../../stores/bounds/helpers/link-pairs.helpers";
+import type {
+	boundaryRegistry,
+	pairs,
+} from "../../../stores/bounds/internals/state";
+import type { BoundaryHandoffTarget } from "../../../types/animation.types";
+
+export type { BoundaryPairPresentation } from "../../../providers/screen/orchestrator/helpers/use-pair-presentation";
+
+import type { BoundaryPairPresentation } from "../../../providers/screen/orchestrator/helpers/use-pair-presentation";
+
+export type BoundaryPresentationState = {
+	presentations: readonly (
+		| DerivedValue<BoundaryPairPresentation | undefined>
+		| null
+		| undefined
+	)[];
+	pairs: ReturnType<typeof pairs.get>;
+	entries: ReturnType<typeof boundaryRegistry.get>;
+};
+
+export function resolveBoundaryPresentation(
+	screenKey: string,
+	boundaryId: string,
+	state: BoundaryPresentationState,
+) {
+	"worklet";
+	const linkKey = getLinkKeyFromTag(boundaryId);
+	let result: BoundaryPairPresentation | undefined;
+	for (const value of state.presentations) {
+		const presentation = value?.get();
+		if (!presentation) continue;
+		const pair = state.pairs[presentation.pairKey];
+		const link = pair?.links[linkKey];
+		if (!link || (link.group && pair.groups[link.group]?.activeId !== linkKey))
+			continue;
+		const sourceKey = link.source?.screenKey ?? presentation.sourceKey;
+		const destinationKey =
+			link.destination?.screenKey ?? presentation.destinationKey;
+		if (sourceKey !== screenKey && destinationKey !== screenKey) continue;
+		// A preparing or completed pair cannot displace a live presentation.
+		if (result && !presentation.ready) continue;
+		result = { ...presentation, sourceKey, destinationKey };
+	}
+	return result;
+}
+
+export function resolveBoundaryReceiver(
+	presentation: BoundaryPairPresentation | undefined,
+	target: BoundaryHandoffTarget | undefined,
+	screenKey: string,
+) {
+	"worklet";
+	if (!presentation) return screenKey;
+	return presentation.ready && target !== "source"
+		? presentation.destinationKey
+		: presentation.sourceKey;
+}
+
+export function resolveBoundaryHandoff(
+	screenKey: string,
+	boundaryId: string,
+	state: BoundaryPresentationState,
+) {
+	"worklet";
+	let receiver = screenKey;
+	const visited: Record<string, true> = {};
+	while (!visited[receiver]) {
+		visited[receiver] = true;
+		const p = resolveBoundaryPresentation(receiver, boundaryId, state);
+		if (!p) break;
+		const slot = (p.sourceKey === receiver ? p.source : p.destination)[
+			boundaryId
+		];
+		const next = resolveBoundaryReceiver(
+			p,
+			slot?.props?.handoffTarget ??
+				p.destination[boundaryId]?.props?.handoffTarget ??
+				p.source[boundaryId]?.props?.handoffTarget,
+			receiver,
+		);
+		if (next === receiver || !state.entries[boundaryId]?.screens[next]?.handoff)
+			break;
+		receiver = next;
+	}
+	return receiver;
+}

package/src/components/boundary/hooks/use-boundary-presentation.ts

@@ -0,0 +1,82 @@
+import { useMemo } from "react";
+import { useDerivedValue, useSharedValue } from "react-native-reanimated";
+import { NO_PROPS, NO_STYLES } from "../../../constants";
+import { useBuilderStore } from "../../../providers/screen/builder";
+import { useScreenRelationships } from "../../../providers/screen/builder/topology";
+import {
+	useOptionalOrchestratorStore,
+	useOrchestratorStore,
+} from "../../../providers/screen/orchestrator";
+import {
+	areResettableStatesBySlotEqual,
+	type ResettableStyleStatesBySlot,
+	resolveSlotStyles,
+} from "../../../providers/screen/orchestrator/styles/helpers/resolve-slot-styles";
+import { useOptionalBlankStackStore } from "../../../providers/stack/blank-stack.provider";
+import {
+	boundaryRegistry,
+	pairs,
+} from "../../../stores/bounds/internals/state";
+import {
+	type BoundaryPresentationState,
+	resolveBoundaryHandoff,
+	resolveBoundaryPresentation,
+} from "../helpers/presentation";
+
+// Screens are discovered through existing providers. React only wires subscriptions;
+// their live UI values decide ownership, including retained closing screens.
+export function useBoundaryPresentation(boundaryId: string, enabled = true) {
+	const screenKey = useBuilderStore((s) => s.derivations.currentScreenKey);
+	const scenes = useOptionalBlankStackStore((s) => s?.scenes);
+	const keys = useMemo(
+		() => (enabled ? (scenes?.map((s) => s.route.key) ?? [screenKey]) : []),
+		[scenes, screenKey, enabled],
+	);
+	const pairPresentations = useOptionalOrchestratorStore(
+		keys,
+		(s) => s.pairPresentation,
+	);
+	const localSlots = useOrchestratorStore((s) => s.slotsMap);
+	const { parentScreenKey } = useScreenRelationships();
+	const ancestorSlots = useOptionalOrchestratorStore(
+		parentScreenKey,
+		(s) => s.slotsMap,
+	);
+	const previous = useSharedValue<ResettableStyleStatesBySlot>(NO_PROPS);
+
+	const presentation = useDerivedValue(() => {
+		const state: BoundaryPresentationState = {
+			presentations: pairPresentations,
+			pairs: pairs.get(),
+			entries: boundaryRegistry.get(),
+		};
+		const owner = resolveBoundaryPresentation(screenKey, boundaryId, state);
+		const receiver = resolveBoundaryHandoff(screenKey, boundaryId, state);
+		const ownedSlot = owner?.ready
+			? (owner.sourceKey === screenKey ? owner.source : owner.destination)[
+					boundaryId
+				]
+			: undefined;
+
+		const fallback = localSlots.get()[boundaryId];
+		const { resolvedStylesMap, nextPreviousStyleStatesBySlot } =
+			resolveSlotStyles({
+				localStylesMaps: [{ [boundaryId]: ownedSlot ?? fallback ?? {} }],
+				ancestorStylesMap: ownedSlot
+					? (ancestorSlots?.get() ?? NO_STYLES)
+					: NO_STYLES,
+				previousStyleStatesBySlot: previous.get(),
+			});
+		if (
+			!areResettableStatesBySlotEqual(
+				previous.get(),
+				nextPreviousStyleStatesBySlot,
+			)
+		) {
+			previous.set(nextPreviousStyleStatesBySlot);
+		}
+		return { owner, receiver, slots: resolvedStylesMap };
+	});
+	const slotsMap = useDerivedValue(() => presentation.get().slots);
+	return { presentation, slotsMap };
+}

package/src/components/boundary/hooks/use-composed-boundary-style.ts

@@ -0,0 +1,58 @@
+import { useMemo } from "react";
+import {
+	type SharedValue,
+	type StyleProps,
+	useAnimatedStyle,
+} from "react-native-reanimated";
+import { NO_STYLES } from "../../../constants";
+import {
+	composeSlotStyleWithLocalTransform,
+	getLocalTransformForSlotComposition,
+} from "../../../providers/screen/orchestrator/styles/helpers/compose-slot-style";
+import type { NormalizedTransitionInterpolatedStyle } from "../../../types/animation.types";
+
+export function useComposedBoundaryStyle(
+	slots: SharedValue<NormalizedTransitionInterpolatedStyle> | undefined,
+	id: string | undefined,
+	style?: unknown,
+	kind: "full" | "stacking" | "layout" = "full",
+) {
+	const local = useMemo(
+		() => getLocalTransformForSlotComposition(style),
+		[style],
+	);
+
+	return useAnimatedStyle(() => {
+		const slot = id ? slots?.get()[id] : undefined;
+		const value: StyleProps = slot?.style ?? NO_STYLES;
+		if (kind === "stacking")
+			return { zIndex: value.zIndex ?? 0, elevation: value.elevation ?? 0 };
+
+		if (kind === "layout") {
+			const {
+				width,
+				height,
+				minWidth,
+				minHeight,
+				maxWidth,
+				maxHeight,
+				aspectRatio,
+			} = value;
+
+			return {
+				width,
+				height,
+				minWidth,
+				minHeight,
+				maxWidth,
+				maxHeight,
+				aspectRatio,
+			};
+		}
+		return composeSlotStyleWithLocalTransform(
+			value,
+			local,
+			slot?.boundsLocalTransform,
+		);
+	});
+}

package/src/components/boundary/index.tsx

@@ -1,9 +1,13 @@
-import { forwardRef } from "react";
+import {
+	type ComponentProps,
+	forwardRef,
+	type NamedExoticComponent,
+} from "react";
 import { View, type ViewProps } from "react-native";
 import { Pressable, type PressableProps } from "react-native-gesture-handler";
 import { BoundaryTarget } from "./components/boundary-target";
 import { createBoundaryComponent } from "./create-boundary-component";
-import { Host } from "./portal";
+import { PortalOverlay } from "./portal/components/portal-overlay";
 import type { BoundaryComponentProps } from "./types";
 
 export { createBoundaryComponent };
@@ -26,7 +30,6 @@ BoundaryPrimitive.displayName = "Transition.Boundary.Primitive";
 const BoundaryRoot = createBoundaryComponent(BoundaryPrimitive);
 BoundaryRoot.displayName = "Transition.Boundary";
 BoundaryTarget.displayName = "Transition.Boundary.Target";
-Host.displayName = "Transition.Boundary.Host";
 
 type BoundaryRootComponent = typeof BoundaryRoot;
 
@@ -55,12 +58,14 @@ export interface BoundaryComponent extends BoundaryRootComponent {
 	/**
 	 * Explicit host for clipping-escape placement.
 	 */
-	Host: typeof Host;
+	Host: NamedExoticComponent<
+		Omit<ComponentProps<typeof PortalOverlay>, "fallback">
+	>;
 }
 
 export type BoundaryProps = BoundaryComponentProps<BoundaryPrimitiveProps>;
 
 export const Boundary = Object.assign(BoundaryRoot, {
 	Target: BoundaryTarget,
-	Host,
+	Host: PortalOverlay,
 }) as BoundaryComponent;

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

@@ -0,0 +1,36 @@
+import { type ComponentProps, memo } from "react";
+import { StyleSheet } from "react-native";
+import Animated from "react-native-reanimated";
+import { NativePortalHost, PORTAL_POINTER_EVENTS } from "../teleport";
+
+const AnimatedHost = NativePortalHost
+	? Animated.createAnimatedComponent(NativePortalHost)
+	: null;
+
+/**
+ * The native receiving point for a Portal whose destination matches `name`.
+ *
+ * Handoff places this inside a boundary, filling its local frame. Escape-clipping
+ * places it inside a PortalOverlay, which supplies
+ * the boundary's size, offset, and animated styles. This component only renders
+ * the receiver; destination selection and measurement belong to its callers.
+ */
+export const PortalHost = memo(function PortalHost({
+	name,
+	style = styles.inline,
+}: {
+	name: string;
+	style?: ComponentProps<typeof Animated.View>["style"];
+}) {
+	return AnimatedHost ? (
+		<AnimatedHost
+			name={name}
+			pointerEvents={PORTAL_POINTER_EVENTS}
+			style={style}
+		/>
+	) : null;
+});
+
+const styles = StyleSheet.create({
+	inline: { ...StyleSheet.absoluteFill, overflow: "visible" },
+});

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

@@ -0,0 +1,223 @@
+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/screen/builder";
+import { composeSlotStyleWithLocalTransform } from "../../../../providers/screen/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 measurementKey = activeBoundaryHosts.length
+		? activeBoundaryHosts.map((host) => host.portalHostName).join("|")
+		: null;
+
+	const measurement = useHostMeasurement({
+		measurementKey,
+		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;
+};