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

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

@@ -0,0 +1,278 @@
+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 { Portal as NativePortal } from "react-native-teleport";
+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 {
+	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<typeof NativePortal>,
+	"hostName"
+> & {
+	hostName?: string | null;
+};
+
+const TransitionAwareTeleport = createTransitionAwareComponent(
+	NativePortal as ComponentType<NullableHostNamePortalProps>,
+);
+
+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) {
+	const isPortalEnabled = !!mode;
+	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) {
+		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;
+});

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

@@ -0,0 +1,102 @@
+import { useLayoutEffect, useState } from "react";
+import type { View } from "react-native";
+import {
+	measure,
+	runOnJS,
+	runOnUI,
+	useAnimatedReaction,
+	useAnimatedRef,
+	useSharedValue,
+} from "react-native-reanimated";
+import { useOriginContext } from "../../../../providers/screen/origin.provider";
+import { ScrollStore } from "../../../../stores/scroll.store";
+import {
+	adjustedMeasuredBoundsForOverscrollDeltas,
+	normalizeMeasuredBoundsToOrigin,
+} from "../../utils/measured-bounds";
+import {
+	clearPortalHostBounds,
+	setPortalHostBounds,
+} from "../stores/host-bounds.store";
+
+type UseHostMeasurementParams = {
+	capturesScroll: boolean;
+	enabled: boolean;
+	hostKey: string;
+	screenKey: string;
+};
+
+export const useHostMeasurement = ({
+	capturesScroll,
+	enabled,
+	hostKey,
+	screenKey,
+}: UseHostMeasurementParams) => {
+	const hostRef = useAnimatedRef<View>();
+	const scrollMetadata = ScrollStore.getValue(screenKey, "metadata");
+	const [canRenderHosts, setCanRenderHosts] = useState<boolean>(false);
+	const { originRef } = useOriginContext();
+	const hasMeasuredHost = useSharedValue(false);
+
+	useAnimatedReaction(
+		() => {
+			"worklet";
+			if (!enabled) {
+				return null;
+			}
+
+			return hasMeasuredHost.get();
+		},
+		(hasAlreadyMeasured) => {
+			"worklet";
+			if (!enabled || hasAlreadyMeasured) {
+				return;
+			}
+
+			const measured = measure(hostRef);
+			const measuredOrigin = measure(originRef);
+
+			if (!measured || !measuredOrigin) {
+				return;
+			}
+
+			hasMeasuredHost.set(true);
+
+			// A measurement taken mid rubber-band would bake the transient
+			// overscroll displacement into the host frame. Store the at-rest
+			// position instead; clamped scroll deltas share that basis.
+			const currentScroll = scrollMetadata.get();
+			const overscrollNormalized = capturesScroll
+				? adjustedMeasuredBoundsForOverscrollDeltas(measured, currentScroll)
+				: measured;
+
+			const normalizedMeasured = normalizeMeasuredBoundsToOrigin(
+				overscrollNormalized,
+				measuredOrigin,
+			);
+
+			setPortalHostBounds(hostKey, {
+				x: normalizedMeasured.x,
+				y: normalizedMeasured.y,
+				width: normalizedMeasured.width,
+				height: normalizedMeasured.height,
+				pageX: normalizedMeasured.pageX,
+				pageY: normalizedMeasured.pageY,
+				scroll: capturesScroll ? currentScroll : null,
+			});
+
+			runOnJS(setCanRenderHosts)(true);
+		},
+	);
+
+	useLayoutEffect(() => {
+		return () => {
+			runOnUI(clearPortalHostBounds)(hostKey);
+		};
+	}, [hostKey]);
+
+	return {
+		canRenderHosts,
+		hostRef,
+	};
+};

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

@@ -0,0 +1,3 @@
+export { Host } from "./components/host";
+export { Portal } from "./components/portal";
+export { PortalProvider } from "./components/portal-provider";

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

@@ -0,0 +1,45 @@
+import { type MeasuredDimensions, makeMutable } from "react-native-reanimated";
+import { cloneScrollMetadataState } from "../../../../stores/scroll.store";
+import type { ScrollMetadataState } from "../../../../types/gesture.types";
+
+export type PortalHostBounds = MeasuredDimensions & {
+	scroll?: ScrollMetadataState | null;
+};
+
+type PortalHostBoundsState = Record<string, PortalHostBounds | null>;
+
+const portalHostBounds = makeMutable<PortalHostBoundsState>({});
+
+export const getPortalHostBounds = (hostKey: string) => {
+	"worklet";
+	return portalHostBounds.get()[hostKey] ?? null;
+};
+
+export const setPortalHostBounds = (
+	hostKey: string,
+	bounds: PortalHostBounds,
+) => {
+	"worklet";
+	const nextBounds: PortalHostBounds = {
+		...bounds,
+		scroll: cloneScrollMetadataState(bounds.scroll),
+	};
+
+	portalHostBounds.set((state) => {
+		"worklet";
+		return {
+			...state,
+			[hostKey]: nextBounds,
+		};
+	});
+};
+
+export const clearPortalHostBounds = (hostKey: string) => {
+	"worklet";
+	portalHostBounds.set((state) => {
+		"worklet";
+		const nextState: PortalHostBoundsState = { ...state };
+		delete nextState[hostKey];
+		return nextState;
+	});
+};

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

@@ -0,0 +1,182 @@
+import { useSyncExternalStore } from "react";
+import { makeMutable } from "react-native-reanimated";
+import type { SourceHostRef } from "../../../../stores/bounds/types";
+
+export type HostRegistration = {
+	hostKey: string;
+	screenKey: string;
+	fallback: boolean;
+	capturesScroll: boolean;
+};
+
+type HostRegistrySnapshot = Record<string, string>;
+
+const EMPTY_SNAPSHOT: HostRegistrySnapshot = {};
+
+const listeners = new Set<() => void>();
+const hostStacks = new Map<string, HostRegistration[]>();
+
+let snapshot: HostRegistrySnapshot = EMPTY_SNAPSHOT;
+
+/**
+ * UI-readable mirror of each screen's active host, kept only for hosts that
+ * capture scroll. Measurement worklets read it to record which scroll-scoped
+ * host a source boundary originated from — at measure time, without any React
+ * subscription on the boundary itself.
+ */
+const activeScrollHosts = makeMutable<Record<string, SourceHostRef>>({});
+
+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 buildSnapshot = (): HostRegistrySnapshot => {
+	const nextSnapshot: HostRegistrySnapshot = {};
+
+	for (const [screenKey, stack] of hostStacks) {
+		nextSnapshot[screenKey] = getActiveHostFromStack(screenKey, stack);
+	}
+
+	return nextSnapshot;
+};
+
+const buildScrollHostSnapshot = (): Record<string, SourceHostRef> => {
+	const nextSnapshot: Record<string, SourceHostRef> = {};
+
+	for (const [screenKey, stack] of hostStacks) {
+		const activeHostKey = getActiveHostFromStack(screenKey, stack);
+		const activeHost = stack.find((host) => host.hostKey === activeHostKey);
+
+		if (activeHost?.capturesScroll) {
+			nextSnapshot[screenKey] = {
+				hostKey: activeHost.hostKey,
+				capturesScroll: true,
+			};
+		}
+	}
+
+	return nextSnapshot;
+};
+
+const emit = () => {
+	snapshot = buildSnapshot();
+	activeScrollHosts.set(buildScrollHostSnapshot());
+
+	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 snapshot[screenKey] ?? screenKey;
+};
+
+/**
+ * The screen's active host, if it captures scroll. Worklet-safe: measurement
+ * code calls this on the UI thread while writing source bounds.
+ */
+export const getActiveScrollHost = (
+	screenKey: string,
+): SourceHostRef | null => {
+	"worklet";
+	return activeScrollHosts.get()[screenKey] ?? null;
+};
+
+export const getHostCapturesScroll = (hostKey: string) => {
+	for (const stack of hostStacks.values()) {
+		const host = stack.find((registration) => registration.hostKey === hostKey);
+
+		if (host) {
+			return host.capturesScroll;
+		}
+	}
+
+	return false;
+};
+
+export const useActiveHostKey = (screenKey?: string | null) => {
+	return useSyncExternalStore(
+		subscribe,
+		() => (screenKey ? getActiveHostKey(screenKey) : undefined),
+		() => undefined,
+	);
+};
+
+export const resetHostRegistry = () => {
+	hostStacks.clear();
+	snapshot = EMPTY_SNAPSHOT;
+	activeScrollHosts.set({});
+	emit();
+};

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

@@ -0,0 +1,91 @@
+import { useSyncExternalStore } from "react";
+
+export type ActivePortalBoundaryHost = {
+	boundaryId: string;
+	capturesScroll: boolean;
+	hostKey: string;
+	pairKey: string;
+	screenKey: string;
+};
+
+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: {},
+};
+
+const buildSnapshot = (): PortalSnapshot => {
+	const hostsByScope: Record<string, ActivePortalBoundaryHost[]> = {};
+
+	for (const host of activeBoundaryHosts.values()) {
+		const hosts = hostsByScope[host.hostKey] ?? [];
+		hosts.push(host);
+		hostsByScope[host.hostKey] = hosts;
+	}
+
+	return {
+		hostsByScope,
+	};
+};
+
+const emit = () => {
+	snapshot = buildSnapshot();
+
+	for (const listener of listeners) {
+		listener();
+	}
+};
+
+const isSameHost = (
+	a: ActivePortalBoundaryHost,
+	b: ActivePortalBoundaryHost,
+) => {
+	return (
+		a.boundaryId === b.boundaryId &&
+		a.capturesScroll === b.capturesScroll &&
+		a.hostKey === b.hostKey &&
+		a.pairKey === b.pairKey &&
+		a.screenKey === b.screenKey
+	);
+};
+
+export const mountPortalBoundaryHost = (host: ActivePortalBoundaryHost) => {
+	const previous = activeBoundaryHosts.get(host.boundaryId);
+	if (previous && isSameHost(previous, host)) {
+		return;
+	}
+
+	activeBoundaryHosts.set(host.boundaryId, host);
+	emit();
+};
+
+export const unmountPortalBoundaryHost = (boundaryId: string) => {
+	if (!activeBoundaryHosts.delete(boundaryId)) {
+		return;
+	}
+
+	emit();
+};
+
+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,
+	);
+};