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

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,
+	);
+};

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

@@ -0,0 +1,21 @@
+import type { ComponentType } from "react";
+
+/**
+ * `react-native-teleport` is an optional peer dependency. The require sits in a
+ * try/catch so Metro treats it as an optional dependency — an absent module no
+ * longer fails the bundle, it throws at runtime and the catch swallows it.
+ *
+ * When teleport is missing, `portal`-enabled boundaries degrade to inline
+ * rendering; everything else keeps working.
+ */
+let mod: any = null;
+try {
+	mod = require("react-native-teleport");
+} catch {}
+
+export const isTeleportAvailable = mod !== null;
+export const NativePortal: ComponentType<any> | null = mod?.Portal ?? null;
+export const NativePortalProvider: ComponentType<any> | null =
+	mod?.PortalProvider ?? null;
+export const NativePortalHost: ComponentType<any> | null =
+	mod?.PortalHost ?? null;

package/src/shared/components/boundary/portal/utils/attachment.ts

@@ -0,0 +1,48 @@
+import type { BoundaryPortalAttachTarget } from "../../types";
+
+export type PortalAttachment = {
+	matchedScreenKey: string;
+	pairKey: string;
+};
+
+type ResolvePortalAttachmentTargetsParams = {
+	attachment: PortalAttachment | null;
+	currentScreenKey: string;
+	nextScreenKey?: string;
+	portalAttachTarget: BoundaryPortalAttachTarget;
+	sourcePairKey?: string;
+};
+
+export const resolvePortalAttachmentTargets = ({
+	attachment,
+	currentScreenKey,
+	nextScreenKey,
+	portalAttachTarget,
+	sourcePairKey,
+}: ResolvePortalAttachmentTargetsParams) => {
+	const hasCurrentAttachment = attachment?.pairKey === sourcePairKey;
+
+	if (!hasCurrentAttachment || !attachment) {
+		return {
+			progressScreenKey: null,
+			targetScreenKey: null,
+		};
+	}
+
+	// Matched-screen portals physically live in the matched destination host. If a
+	// closing destination is skipped by descriptor resolution, its own progress
+	// still owns the attach gate until this attachment is replaced or cleared.
+	if (portalAttachTarget === "matched-screen") {
+		return {
+			progressScreenKey: attachment.matchedScreenKey,
+			targetScreenKey: attachment.matchedScreenKey,
+		};
+	}
+
+	// Current-screen portals stay mounted in this screen's host, but the visual
+	// handoff is still paced by the adjacent destination transition.
+	return {
+		progressScreenKey: nextScreenKey ?? null,
+		targetScreenKey: currentScreenKey,
+	};
+};

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

@@ -0,0 +1,10 @@
+export const PORTAL_HOST_NAME_RESET_VALUE = null;
+const PORTAL_HOST_NAME_SUFFIX = "-portal-host";
+
+export const createPortalBoundaryHostName = (
+	hostKey: string,
+	boundaryId: string,
+) => {
+	"worklet";
+	return `${hostKey}-${boundaryId}${PORTAL_HOST_NAME_SUFFIX}`;
+};

package/src/shared/components/boundary/portal/utils/offset-style.ts

@@ -0,0 +1,171 @@
+import {
+	interpolate,
+	type MeasuredDimensions,
+	type StyleProps,
+} from "react-native-reanimated";
+import { getClampedScrollAxisDelta } from "../../../../stores/scroll.store";
+import type { ScrollMetadataState } from "../../../../types/gesture.types";
+import { getPortalHostBounds } from "../stores/host-bounds.store";
+
+export type PortalOffsetPlacement =
+	| "same-screen"
+	| "cross-screen-open"
+	| "cross-screen-close";
+
+type ResolvePortalOffsetStyleParams = {
+	alignHostToBoundsScroll?: boolean;
+	bounds: MeasuredDimensions;
+	boundsCurrentScroll?: ScrollMetadataState | null;
+	/**
+	 * Express the source rect in its scroll host's live frame: the rect is
+	 * shifted by the clamped travel of `sourceCurrentScroll` since the scroll
+	 * snapshot stored on `bounds`. Independent of the host scroll fallback
+	 * chain below — that chain compensates the attached host's own scrolling.
+	 */
+	compensateSourceScroll?: boolean;
+	currentScroll?: ScrollMetadataState | null;
+	hostCurrentScroll?: ScrollMetadataState | null;
+	hostKey: string;
+	hostProgress?: number;
+	includeScrollOffsets?: boolean;
+	/**
+	 * The three portal coordinate cases we support:
+	 *
+	 * - same-screen: source and host are on the same screen; align the stored
+	 *   host frame to the source measurement's scroll snapshot once.
+	 * - cross-screen-open: source and host are on different screens; host
+	 *   placement is static during the open/idle portion.
+	 * - cross-screen-close: source and host are on different screens; the
+	 *   dismissal needs the host's live scroll frame until the portal detaches.
+	 */
+	placement?: PortalOffsetPlacement;
+	position?: "absolute" | "relative";
+	sourceCurrentScroll?: ScrollMetadataState | null;
+	trackSourceScroll?: boolean;
+};
+
+export const resolvePortalOffsetStyle = ({
+	alignHostToBoundsScroll = false,
+	bounds,
+	boundsCurrentScroll,
+	compensateSourceScroll = false,
+	currentScroll,
+	hostCurrentScroll,
+	hostKey,
+	hostProgress = 0,
+	includeScrollOffsets = true,
+	placement,
+	position = "relative",
+	sourceCurrentScroll,
+	trackSourceScroll = false,
+}: ResolvePortalOffsetStyleParams): StyleProps => {
+	"worklet";
+	const hostBounds = getPortalHostBounds(hostKey);
+	const shouldAlignHostToBoundsScroll = placement
+		? placement === "same-screen"
+		: alignHostToBoundsScroll;
+	const shouldCompensateSourceScroll =
+		trackSourceScroll || compensateSourceScroll;
+	const shouldIncludeHostScrollOffsets = placement
+		? placement === "cross-screen-close"
+		: includeScrollOffsets;
+	const boundsScrollSnapshot =
+		(bounds as { scroll?: ScrollMetadataState | null }).scroll ?? null;
+	const sourceScrollSnapshot = shouldCompensateSourceScroll
+		? boundsScrollSnapshot
+		: null;
+	const sourceScrollDeltaX = shouldCompensateSourceScroll
+		? getClampedScrollAxisDelta(
+				sourceCurrentScroll ?? null,
+				sourceScrollSnapshot,
+				"horizontal",
+			)
+		: 0;
+	const sourceScrollDeltaY = shouldCompensateSourceScroll
+		? getClampedScrollAxisDelta(
+				sourceCurrentScroll ?? null,
+				sourceScrollSnapshot,
+				"vertical",
+			)
+		: 0;
+	const sourcePageX = bounds.pageX - sourceScrollDeltaX;
+	const sourcePageY = bounds.pageY - sourceScrollDeltaY;
+	const boundsScroll = shouldIncludeHostScrollOffsets
+		? (boundsScrollSnapshot ?? boundsCurrentScroll ?? currentScroll ?? null)
+		: null;
+	const hostBoundsScrollSnapshot = hostBounds?.scroll ?? null;
+	const hostBoundsScroll = shouldIncludeHostScrollOffsets
+		? hostBoundsScrollSnapshot
+		: null;
+	const resolvedHostCurrentScroll =
+		hostCurrentScroll ?? boundsScroll ?? hostBoundsScroll ?? null;
+	const hostSnapshotDeltaX =
+		shouldAlignHostToBoundsScroll && !shouldIncludeHostScrollOffsets
+			? getClampedScrollAxisDelta(
+					boundsScrollSnapshot,
+					hostBoundsScrollSnapshot,
+					"horizontal",
+				)
+			: 0;
+	const hostSnapshotDeltaY =
+		shouldAlignHostToBoundsScroll && !shouldIncludeHostScrollOffsets
+			? getClampedScrollAxisDelta(
+					boundsScrollSnapshot,
+					hostBoundsScrollSnapshot,
+					"vertical",
+				)
+			: 0;
+	// Deltas are clamped to the layout range: iOS rubber-band offsets are
+	// outside the real scroll range and must not become coordinate-space deltas.
+	const hostScrollDeltaX = getClampedScrollAxisDelta(
+		resolvedHostCurrentScroll,
+		hostBoundsScroll,
+		"horizontal",
+	);
+	const hostScrollDeltaY = getClampedScrollAxisDelta(
+		resolvedHostCurrentScroll,
+		hostBoundsScroll,
+		"vertical",
+	);
+
+	const adjustedHostPageX = hostBounds
+		? hostBounds.pageX -
+			hostSnapshotDeltaX -
+			interpolate(hostProgress, [0, 1], [hostScrollDeltaX, 0])
+		: 0;
+	const adjustedHostPageY = hostBounds
+		? hostBounds.pageY -
+			hostSnapshotDeltaY -
+			interpolate(hostProgress, [0, 1], [hostScrollDeltaY, 0])
+		: 0;
+	const boundsScrollDeltaX = shouldIncludeHostScrollOffsets
+		? getClampedScrollAxisDelta(
+				currentScroll ?? null,
+				boundsScroll,
+				"horizontal",
+			)
+		: 0;
+	const boundsScrollDeltaY = shouldIncludeHostScrollOffsets
+		? getClampedScrollAxisDelta(currentScroll ?? null, boundsScroll, "vertical")
+		: 0;
+	const offsetX = hostBounds
+		? sourcePageX - adjustedHostPageX
+		: sourcePageX - boundsScrollDeltaX;
+	const offsetY = hostBounds
+		? sourcePageY - adjustedHostPageY
+		: sourcePageY - boundsScrollDeltaY;
+	const transform = [{ translateY: offsetY }, { translateX: offsetX }];
+
+	if (position === "absolute") {
+		return {
+			left: 0,
+			position: "absolute",
+			top: 0,
+			transform,
+		};
+	}
+
+	return {
+		transform,
+	};
+};

package/src/shared/components/boundary/portal/utils/teleport-control.ts

@@ -0,0 +1,13 @@
+import type { BoundaryTeleportControl } from "../../../../types/animation.types";
+
+export const isTeleportEnabled = (
+	teleport: BoundaryTeleportControl | undefined,
+) => {
+	"worklet";
+
+	if (typeof teleport === "boolean") {
+		return teleport;
+	}
+
+	return teleport?.enabled !== false;
+};