react-native-screen-transitions 3.8.0 → 3.9.0-alpha.1

package/src/shared/components/{create-boundary-component → boundary}/hooks/use-refresh-boundary.ts

@@ -1,4 +1,5 @@
 import { useAnimatedReaction } from "react-native-reanimated";
+import { useDescriptorsStore } from "../../../providers/screen/descriptors";
 import { AnimationStore } from "../../../stores/animation.store";
 import { pairs } from "../../../stores/bounds/internals/state";
 import type { MeasureBoundary } from "../types";
@@ -6,25 +7,28 @@ import { getRefreshBoundarySignal } from "../utils/refresh-signals";
 
 interface UseRefreshBoundaryParams {
 	enabled: boolean;
-	currentScreenKey: string;
-	preferredSourceScreenKey?: string;
-	nextScreenKey?: string;
 	linkId: string;
 	group?: string;
-	ancestorScreenKeys: string[];
 	measureBoundary: MeasureBoundary;
 }
 
 export const useRefreshBoundary = ({
 	enabled,
-	currentScreenKey,
-	preferredSourceScreenKey,
-	nextScreenKey,
 	linkId,
 	group,
-	ancestorScreenKeys,
 	measureBoundary,
 }: UseRefreshBoundaryParams) => {
+	const currentScreenKey = useDescriptorsStore(
+		(s) => s.derivations.currentScreenKey,
+	);
+	const nextScreenKey = useDescriptorsStore((s) => s.derivations.nextScreenKey);
+	const sourcePairKey = useDescriptorsStore((s) => s.derivations.sourcePairKey);
+	const destinationPairKey = useDescriptorsStore(
+		(s) => s.derivations.destinationPairKey,
+	);
+	const ancestorDestinationPairKey = useDescriptorsStore(
+		(s) => s.derivations.ancestorDestinationPairKey,
+	);
 	// Source-side boundaries refresh from the next screen's lifecycle pulse.
 	// Destination-side boundaries have no next screen, so they refresh from self.
 	const refreshScreenKey = nextScreenKey ?? currentScreenKey;
@@ -49,17 +53,18 @@ export const useRefreshBoundary = ({
 			return getRefreshBoundarySignal({
 				enabled,
 				currentScreenKey,
-				preferredSourceScreenKey,
+				sourcePairKey,
+				destinationPairKey,
+				ancestorDestinationPairKey,
 				nextScreenKey,
 				linkId,
 				group,
-				ancestorScreenKeys,
 				shouldRefresh: !!refreshWillAnimate.get(),
 				closing: !!refreshClosing.get(),
 				entering: !!refreshEntering.get(),
 				animating: !!refreshAnimating.get(),
 				progress: refreshProgress.get(),
-				linkState: group || ancestorScreenKeys.length ? pairs.get() : undefined,
+				linkState: pairs.get(),
 			});
 		},
 		(refreshSignal, prevRefreshSignal) => {

package/src/shared/components/{create-boundary-component → boundary}/index.tsx

@@ -1,7 +1,13 @@
 import { Pressable, View } from "react-native";
 import { BoundaryTarget } from "./components/boundary-target";
 import { createBoundaryComponent } from "./create-boundary-component";
+import { Host } from "./portal";
 
+export type {
+	BoundaryPortal,
+	BoundaryPortalAttachTarget,
+	BoundaryPortalOptions,
+} from "./types";
 export { createBoundaryComponent };
 
 const BoundaryView = createBoundaryComponent(View, {
@@ -11,6 +17,7 @@ const BoundaryTrigger = createBoundaryComponent(Pressable);
 BoundaryView.displayName = "Transition.Boundary.View";
 BoundaryTrigger.displayName = "Transition.Boundary.Trigger";
 BoundaryTarget.displayName = "Transition.Boundary.Target";
+Host.displayName = "Transition.Boundary.Host";
 
 /**
  * Shared-boundary components.
@@ -29,6 +36,7 @@ BoundaryTarget.displayName = "Transition.Boundary.Target";
  * - `Boundary.View` for passive/shared elements.
  * - `Boundary.Trigger` for tappable elements that start navigation.
  * - `Boundary.Target` to measure a nested descendant instead of the owner.
+ * - `Boundary.Host` to make nested portal placement explicit.
  */
 export const Boundary = {
 	/**
@@ -43,4 +51,8 @@ export const Boundary = {
 	 * Optional nested measurement override inside a boundary owner.
 	 */
 	Target: BoundaryTarget,
+	/**
+	 * Explicit portal host for scrollable or otherwise clipped coordinate spaces.
+	 */
+	Host: Host,
 };

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

@@ -0,0 +1,114 @@
+import { memo, useLayoutEffect, useRef } from "react";
+import {
+	type StyleProp,
+	StyleSheet,
+	useWindowDimensions,
+	View,
+	type ViewStyle,
+} from "react-native";
+import Animated from "react-native-reanimated";
+import { useDescriptorsStore } from "../../../../providers/screen/descriptors";
+import { useHostMeasurement } from "../hooks/use-host-measurement";
+import { registerHost, unregisterHost } from "../stores/host-registry.store";
+import { useActivePortalBoundaryHosts } from "../stores/portal-boundary-host.store";
+import { PortalBoundaryHost } from "./portal-boundary-host";
+
+let nextHostId = 0;
+
+export type PublicHostProps = {
+	style?: StyleProp<ViewStyle>;
+};
+
+type HostImplProps = PublicHostProps & {
+	fallback?: boolean;
+};
+
+function HostImpl({ fallback = false, style }: HostImplProps) {
+	const screenKey = useDescriptorsStore((s) => s.derivations.currentScreenKey);
+	const generatedHostKeyRef = useRef<string | null>(null);
+
+	if (generatedHostKeyRef.current === null) {
+		generatedHostKeyRef.current = `${screenKey}-host-${nextHostId++}`;
+	}
+
+	const hostKey = fallback ? screenKey : generatedHostKeyRef.current;
+	const capturesScroll = !fallback;
+	const activeBoundaryHosts = useActivePortalBoundaryHosts(hostKey);
+	const { height: viewportHeight, width: viewportWidth } =
+		useWindowDimensions();
+
+	const measurement = useHostMeasurement({
+		capturesScroll,
+		enabled: activeBoundaryHosts.length > 0,
+		hostKey,
+		screenKey,
+	});
+
+	useLayoutEffect(() => {
+		registerHost({
+			capturesScroll,
+			fallback,
+			hostKey,
+			screenKey,
+		});
+
+		return () => {
+			unregisterHost(screenKey, hostKey);
+		};
+	}, [capturesScroll, fallback, hostKey, screenKey]);
+
+	const boundaryHosts = measurement.canRenderHosts
+		? activeBoundaryHosts.map((host) => (
+				<View
+					key={host.boundaryId}
+					pointerEvents="box-none"
+					style={[
+						styles.boundaryHostViewport,
+						{ width: viewportWidth, height: viewportHeight },
+					]}
+				>
+					<PortalBoundaryHost host={host} style={StyleSheet.absoluteFill} />
+				</View>
+			))
+		: null;
+
+	return (
+		<Animated.View
+			ref={measurement.hostRef}
+			pointerEvents="box-none"
+			style={[
+				styles.host,
+				{ width: viewportWidth, height: viewportHeight },
+				style,
+			]}
+			collapsable={false}
+		>
+			{boundaryHosts}
+		</Animated.View>
+	);
+}
+
+export const Host = memo(function Host(props: PublicHostProps) {
+	return <HostImpl {...props} />;
+});
+
+export const ScreenFallbackHost = memo(function ScreenFallbackHost() {
+	return <HostImpl fallback />;
+});
+
+const styles = StyleSheet.create({
+	host: {
+		elevation: 999999,
+		left: 0,
+		overflow: "visible",
+		position: "absolute",
+		top: 0,
+		zIndex: 999999,
+	},
+	boundaryHostViewport: {
+		left: 0,
+		overflow: "visible",
+		position: "absolute",
+		top: 0,
+	},
+});

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

@@ -0,0 +1,97 @@
+import { memo } from "react";
+import type { StyleProp, ViewStyle } from "react-native";
+import Animated, { useAnimatedStyle } from "react-native-reanimated";
+import { NO_STYLES } from "../../../../constants";
+import { AnimationStore } from "../../../../stores/animation.store";
+import { getSourceScreenKeyFromPairKey } from "../../../../stores/bounds/helpers/link-pairs.helpers";
+import { getLink } from "../../../../stores/bounds/internals/links";
+import { GestureStore } from "../../../../stores/gesture.store";
+import { ScrollStore } from "../../../../stores/scroll.store";
+import type { ActivePortalBoundaryHost } from "../stores/portal-boundary-host.store";
+import { NativePortalHost } from "../teleport";
+import { createPortalBoundaryHostName } from "../utils/naming";
+import {
+	type PortalOffsetPlacement,
+	resolvePortalOffsetStyle,
+} from "../utils/offset-style";
+
+const AnimatedPortalBoundaryHost = NativePortalHost
+	? Animated.createAnimatedComponent(NativePortalHost)
+	: null;
+
+type PortalBoundaryHostProps = {
+	host: ActivePortalBoundaryHost;
+	style?: StyleProp<ViewStyle>;
+};
+
+export const PortalBoundaryHost = memo(function PortalBoundaryHost({
+	host,
+	style,
+}: PortalBoundaryHostProps) {
+	const hostName = createPortalBoundaryHostName(host.hostKey, host.boundaryId);
+	const hostClosing = AnimationStore.getValue(host.screenKey, "closing");
+	const hostProgress = AnimationStore.getValue(
+		host.screenKey,
+		"transitionProgress",
+	);
+	const hostGestureDismissing = GestureStore.getValue(
+		host.screenKey,
+		"dismissing",
+	);
+	const hostScrollMetadata = ScrollStore.getValue(host.screenKey, "metadata");
+	const sourceScrollMetadata = ScrollStore.getValue(
+		getSourceScreenKeyFromPairKey(host.pairKey),
+		"metadata",
+	);
+	const hostStyle = useAnimatedStyle(() => {
+		"worklet";
+		// Strict per-member lookup — a fallback member's source rect would
+		// misplace this host's teleported content.
+		const link = getLink(host.pairKey, host.boundaryId);
+		if (!link?.source || !link.destination) {
+			return NO_STYLES;
+		}
+
+		// Make the coordinate case explicit before resolving the host offset.
+		// The resolver owns the math; this component decides which screen/scroll
+		// relationship the active portal is in.
+		const isCrossScreenPortal = link.source.screenKey !== host.screenKey;
+		const isHostClosing =
+			hostClosing.get() === 1 || hostGestureDismissing.get() === 1;
+		const placement: PortalOffsetPlacement = !isCrossScreenPortal
+			? "same-screen"
+			: isHostClosing
+				? "cross-screen-close"
+				: "cross-screen-open";
+
+		// A source that originated inside its own scroll host moves with that
+		// ScrollView while this portal stays attached over here. Shifting the
+		// source rect by the clamped source scroll travel keeps the return
+		// landing point on the live placeholder, so the close detach is seamless.
+		const trackSourceScroll =
+			isCrossScreenPortal && link.source.sourceHost?.capturesScroll === true;
+
+		return resolvePortalOffsetStyle({
+			bounds: link.source.bounds,
+			hostCurrentScroll:
+				placement === "cross-screen-close" ? hostScrollMetadata.get() : null,
+			hostKey: host.hostKey,
+			placement,
+			sourceCurrentScroll: trackSourceScroll
+				? sourceScrollMetadata.get()
+				: null,
+			hostProgress: hostProgress.get(),
+			trackSourceScroll,
+		});
+	});
+
+	// Without `react-native-teleport` no portal ever mounts a boundary host, so
+	// this never renders — the guard just narrows the nullable animated host.
+	if (!AnimatedPortalBoundaryHost) {
+		return null;
+	}
+
+	return (
+		<AnimatedPortalBoundaryHost name={hostName} style={[style, hostStyle]} />
+	);
+});

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

@@ -0,0 +1,14 @@
+import { memo } from "react";
+import { NativePortalProvider } from "../teleport";
+
+export const PortalProvider = memo(function PortalProvider({
+	children,
+}: {
+	children: React.ReactNode;
+}) {
+	if (!NativePortalProvider) {
+		return children;
+	}
+
+	return <NativePortalProvider>{children}</NativePortalProvider>;
+});

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

@@ -0,0 +1,283 @@
+import {
+	type ComponentProps,
+	type ComponentType,
+	memo,
+	type ReactNode,
+	useCallback,
+	useLayoutEffect,
+	useState,
+} from "react";
+import type { View } from "react-native";
+import Animated, {
+	type AnimatedRef,
+	runOnJS,
+	useAnimatedProps,
+	useAnimatedReaction,
+	useAnimatedStyle,
+	useSharedValue,
+} from "react-native-reanimated";
+import { useDescriptorsStore } from "../../../../providers/screen/descriptors";
+import { useScreenStyles } from "../../../../providers/screen/styles";
+import { AnimationStore } from "../../../../stores/animation.store";
+import { getLinkKeyFromTag } from "../../../../stores/bounds/helpers/link-pairs.helpers";
+import { getLink } from "../../../../stores/bounds/internals/links";
+import { pairs } from "../../../../stores/bounds/internals/state";
+import { createTransitionAwareComponent } from "../../../create-transition-aware-component";
+import type { BoundaryPortal, BoundaryPortalAttachTarget } from "../../types";
+import {
+	getHostCapturesScroll,
+	useActiveHostKey,
+} from "../stores/host-registry.store";
+import {
+	mountPortalBoundaryHost,
+	unmountPortalBoundaryHost,
+} from "../stores/portal-boundary-host.store";
+import { isTeleportAvailable, NativePortal } from "../teleport";
+import {
+	type PortalAttachment,
+	resolvePortalAttachmentTargets,
+} from "../utils/attachment";
+import {
+	createPortalBoundaryHostName,
+	PORTAL_HOST_NAME_RESET_VALUE,
+} from "../utils/naming";
+import { isTeleportEnabled } from "../utils/teleport-control";
+
+type NullableHostNamePortalProps = Omit<
+	ComponentProps<NonNullable<typeof NativePortal>>,
+	"hostName"
+> & {
+	hostName?: string | null;
+};
+
+const TransitionAwareTeleport = NativePortal
+	? createTransitionAwareComponent(
+			NativePortal as ComponentType<NullableHostNamePortalProps>,
+		)
+	: null;
+
+interface PortalProps {
+	id?: string;
+	children: ReactNode;
+	mode?: BoundaryPortal;
+	/**
+	 * Ref to the layout-preserving placeholder wrapper. Boundaries measure
+	 * this instead of teleported content — the placeholder keeps the source
+	 * slot at home while the content may physically live in another screen's
+	 * host.
+	 */
+	placeholderRef?: AnimatedRef<View>;
+}
+
+export const Portal = memo(function Portal({
+	id = "my-id",
+	children,
+	mode = false,
+	placeholderRef,
+}: PortalProps) {
+	// Teleporting requires the optional `react-native-teleport` peer. Without it,
+	// a portal-enabled boundary degrades to inline rendering (the `return
+	// children` path below).
+	const isPortalEnabled = !!mode && isTeleportAvailable;
+	const portalAttachTarget: BoundaryPortalAttachTarget =
+		!mode || mode === true
+			? "current-screen"
+			: (mode.attachTo ?? "current-screen");
+	const { stylesMap } = useScreenStyles();
+	const sourcePairKey = useDescriptorsStore((s) => s.derivations.sourcePairKey);
+	const currentScreenKey = useDescriptorsStore(
+		(s) => s.derivations.currentScreenKey,
+	);
+
+	const nextScreenKey = useDescriptorsStore((s) => s.derivations.nextScreenKey);
+
+	const [attachment, setAttachment] = useState<PortalAttachment | null>(
+		PORTAL_HOST_NAME_RESET_VALUE,
+	);
+	const attachedHostName = useSharedValue<string | null>(
+		PORTAL_HOST_NAME_RESET_VALUE,
+	);
+	const placeholderWidth = useSharedValue(0);
+	const placeholderHeight = useSharedValue(0);
+
+	const { progressScreenKey, targetScreenKey } = resolvePortalAttachmentTargets(
+		{
+			attachment,
+			currentScreenKey,
+			nextScreenKey,
+			portalAttachTarget,
+			sourcePairKey,
+		},
+	);
+	const activeHostKey = useActiveHostKey(targetScreenKey);
+	const activeHostCapturesScroll = activeHostKey
+		? getHostCapturesScroll(activeHostKey)
+		: false;
+	const progress = AnimationStore.getValue(
+		progressScreenKey ?? "",
+		"transitionProgress",
+	);
+	const closing = AnimationStore.getValue(progressScreenKey ?? "", "closing");
+
+	const updatePortalAttachment = useCallback(
+		(matchedScreenKey: string | null, pairKey?: string) => {
+			if (matchedScreenKey && pairKey) {
+				setAttachment((current) => {
+					if (
+						current?.matchedScreenKey === matchedScreenKey &&
+						current.pairKey === pairKey
+					) {
+						return current;
+					}
+
+					return {
+						matchedScreenKey,
+						pairKey,
+					};
+				});
+				return;
+			}
+
+			setAttachment((current) => (current ? null : current));
+		},
+		[],
+	);
+
+	useLayoutEffect(() => {
+		if (!isPortalEnabled || !attachment || !activeHostKey || !targetScreenKey) {
+			attachedHostName.set(PORTAL_HOST_NAME_RESET_VALUE);
+			return;
+		}
+
+		mountPortalBoundaryHost({
+			boundaryId: id,
+			capturesScroll: activeHostCapturesScroll,
+			hostKey: activeHostKey,
+			pairKey: attachment.pairKey,
+			screenKey: targetScreenKey,
+		});
+
+		// The native registry parks portals whose host has not registered yet and
+		// re-parents the moment it does, so the host name can be handed over
+		// immediately — ordering belongs to the registry, not to frame counting.
+		// hostName rides animated props, so the handover needs no React commit.
+		attachedHostName.set(createPortalBoundaryHostName(activeHostKey, id));
+	}, [
+		activeHostKey,
+		activeHostCapturesScroll,
+		attachedHostName,
+		attachment,
+		id,
+		isPortalEnabled,
+		targetScreenKey,
+	]);
+
+	useLayoutEffect(() => {
+		return () => {
+			attachedHostName.set(PORTAL_HOST_NAME_RESET_VALUE);
+			unmountPortalBoundaryHost(id);
+		};
+	}, [attachedHostName, id]);
+
+	useAnimatedReaction(
+		() => {
+			"worklet";
+			if (!isPortalEnabled || !sourcePairKey) {
+				return null;
+			}
+
+			pairs.get();
+			// Strict per-member lookup: getResolvedLink's group fallback borrows
+			// the initial member's link for style resolution, which would make
+			// every inactive group member's portal see a "complete" link and
+			// attach. A portal may only teleport on its OWN member's link.
+			const link = getLink(sourcePairKey, id);
+
+			if (link?.status !== "complete") {
+				return null;
+			}
+
+			// Grouped portals teleport only while their member is the group's
+			// active id — retargeting detaches the previous member (its content
+			// returns home) and attaches the new one. Exactly one grouped member
+			// is teleported at a time.
+			if (link.group) {
+				const activeId =
+					pairs.get()[sourcePairKey]?.groups?.[link.group]?.activeId;
+
+				if (activeId && activeId !== getLinkKeyFromTag(id)) {
+					return null;
+				}
+			}
+
+			return link.destination.screenKey;
+		},
+		(matchedScreenKey, previousMatchedScreenKey) => {
+			"worklet";
+			if (matchedScreenKey === previousMatchedScreenKey) {
+				return;
+			}
+
+			runOnJS(updatePortalAttachment)(matchedScreenKey, sourcePairKey);
+		},
+	);
+
+	const teleportProps = useAnimatedProps(() => {
+		"worklet";
+
+		// Opening waits for the destination transition to start so content is not
+		// re-parented before the host is visually ready. Closing stays attached
+		// through progress 0 so the final frame can land in the matched host.
+		const attachThreshold = closing.get() === 1 ? 0 : 0.001;
+		const { teleport, ...slotProps } = stylesMap.get()[id]?.props ?? {};
+		const shouldTeleport = isTeleportEnabled(teleport);
+
+		return {
+			// Preserve portal slot props from the interpolator while keeping
+			// hostName owned by the attachment gate below.
+			...slotProps,
+			hostName:
+				shouldTeleport && progress.get() >= attachThreshold
+					? attachedHostName.get()
+					: PORTAL_HOST_NAME_RESET_VALUE,
+		};
+	});
+
+	// Pin the placeholder to its measured size while content lives in the host,
+	// in the same UI frame the host name flips — no commit in between. Until the
+	// first layout lands (dims 0) sizing stays natural so an instant attach
+	// cannot collapse the slot.
+	const placeholderStyle = useAnimatedStyle(() => {
+		"worklet";
+		const hostName = attachedHostName.get();
+		const isAttached = hostName !== null;
+		const width = placeholderWidth.get();
+		const height = placeholderHeight.get();
+
+		if (!isAttached || width === 0) {
+			return { width: "auto", height: "auto" } as const;
+		}
+
+		return { width, height };
+	});
+
+	if (isPortalEnabled && TransitionAwareTeleport) {
+		return (
+			<Animated.View
+				ref={placeholderRef}
+				onLayout={(event) => {
+					placeholderWidth.set(event.nativeEvent.layout.width);
+					placeholderHeight.set(event.nativeEvent.layout.height);
+				}}
+				style={placeholderStyle}
+				collapsable={false}
+			>
+				<TransitionAwareTeleport animatedProps={teleportProps} name={id}>
+					<Animated.View style={placeholderStyle}>{children}</Animated.View>
+				</TransitionAwareTeleport>
+			</Animated.View>
+		);
+	}
+
+	return children;
+});