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

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

@@ -0,0 +1,371 @@
+import {
+	getDestinationScreenKeyFromPairKey,
+	getLinkKeyFromTag,
+	getLink as getPairLink,
+	getSourceScreenKeyFromPairKey,
+} from "../../../../stores/bounds/helpers/link-pairs.helpers";
+import type {
+	LinkKey,
+	LinkPairsState,
+	ScreenKey,
+	ScreenPairKey,
+	TagLink,
+} from "../../../../stores/bounds/types";
+
+export type PortalOwnershipSignal =
+	| {
+			hostScreenKey: null;
+			ownerPairKey?: ScreenPairKey;
+			ownerScreenKey: null;
+			status: "clear" | "pending";
+	  }
+	| {
+			hostScreenKey: ScreenKey;
+			ownerPairKey: ScreenPairKey;
+			ownerScreenKey: ScreenKey;
+			status: "complete";
+	  };
+
+const hasSeenScreenKey = (screenKeys: ScreenKey[], screenKey: ScreenKey) => {
+	"worklet";
+	for (let index = 0; index < screenKeys.length; index++) {
+		if (screenKeys[index] === screenKey) {
+			return true;
+		}
+	}
+	return false;
+};
+
+export const usesEscapeClippingHost = (
+	link: TagLink | null | undefined,
+): boolean => {
+	"worklet";
+	return link?.source?.handoff === true && link.source.escapeClipping === true;
+};
+
+const isReturningToPreviousSourceHost = ({
+	hostScreenKey,
+	ownerPairKey,
+	previousOwnerPairKey,
+}: {
+	hostScreenKey: ScreenKey;
+	ownerPairKey: ScreenPairKey;
+	previousOwnerPairKey: ScreenPairKey;
+}) => {
+	"worklet";
+	const previousSourceScreenKey =
+		getSourceScreenKeyFromPairKey(previousOwnerPairKey);
+	const previousDestinationScreenKey =
+		getDestinationScreenKeyFromPairKey(previousOwnerPairKey);
+	const ownerDestinationScreenKey =
+		getDestinationScreenKeyFromPairKey(ownerPairKey);
+
+	return (
+		previousDestinationScreenKey !== "" &&
+		ownerDestinationScreenKey !== "" &&
+		previousDestinationScreenKey !== previousSourceScreenKey &&
+		ownerDestinationScreenKey === previousSourceScreenKey &&
+		hostScreenKey === previousSourceScreenKey
+	);
+};
+
+export const canSwitchBoundaryLocalHandoffImmediately = ({
+	hostScreenKey,
+	ownerPairKey,
+	previousOwnerPairKey,
+}: {
+	hostScreenKey: ScreenKey | null;
+	ownerPairKey?: ScreenPairKey;
+	previousOwnerPairKey?: ScreenPairKey;
+}) => {
+	"worklet";
+	if (!hostScreenKey || !ownerPairKey) {
+		return false;
+	}
+
+	if (hostScreenKey === getSourceScreenKeyFromPairKey(ownerPairKey)) {
+		return true;
+	}
+
+	if (!previousOwnerPairKey) {
+		return false;
+	}
+
+	return isReturningToPreviousSourceHost({
+		hostScreenKey,
+		ownerPairKey,
+		previousOwnerPairKey,
+	});
+};
+
+const isActiveHandoffLink = ({
+	link,
+	linkKey,
+	pairKey,
+	pairsState,
+}: {
+	link: TagLink;
+	linkKey: LinkKey;
+	pairKey: ScreenPairKey;
+	pairsState: LinkPairsState;
+}) => {
+	"worklet";
+	if (!link.group) {
+		return true;
+	}
+
+	const activeId = pairsState[pairKey]?.groups?.[link.group]?.activeId;
+	return !activeId || activeId === linkKey;
+};
+
+const resolveBoundaryLocalStyleOwnerScreenKey = ({
+	hostScreenKey,
+	isSettledHostReady,
+	settledHostScreenKey,
+	sourceScreenKey,
+}: {
+	hostScreenKey: ScreenKey;
+	isSettledHostReady: boolean;
+	settledHostScreenKey?: ScreenKey | null;
+	sourceScreenKey: ScreenKey;
+}): ScreenKey => {
+	"worklet";
+	if (settledHostScreenKey === hostScreenKey && isSettledHostReady) {
+		return hostScreenKey;
+	}
+
+	return sourceScreenKey;
+};
+
+const pendingSignal = (sourcePairKey: ScreenPairKey): PortalOwnershipSignal => {
+	"worklet";
+	return {
+		hostScreenKey: null,
+		ownerPairKey: sourcePairKey,
+		ownerScreenKey: null,
+		status: "pending",
+	};
+};
+
+const clearSignal = (sourcePairKey: ScreenPairKey): PortalOwnershipSignal => {
+	"worklet";
+	return {
+		hostScreenKey: null,
+		ownerPairKey: sourcePairKey,
+		ownerScreenKey: null,
+		status: "clear",
+	};
+};
+
+export const resolveBoundaryPortalOwnership = ({
+	boundaryId,
+	currentScreenKey,
+	escapeClipping,
+	handoff,
+	isSettledHostClosingComplete = false,
+	isSettledHostReady = false,
+	pairsState,
+	settledHostScreenKey = null,
+	sourcePairKey,
+}: {
+	boundaryId: string;
+	currentScreenKey: ScreenKey;
+	escapeClipping: boolean;
+	handoff: boolean;
+	isSettledHostClosingComplete?: boolean;
+	isSettledHostReady?: boolean;
+	pairsState: LinkPairsState;
+	settledHostScreenKey?: ScreenKey | null;
+	sourcePairKey: ScreenPairKey;
+}): PortalOwnershipSignal => {
+	"worklet";
+	const linkKey = getLinkKeyFromTag(boundaryId);
+	const link = getPairLink(pairsState, sourcePairKey, linkKey);
+
+	if (link?.status !== "complete") {
+		return pendingSignal(sourcePairKey);
+	}
+
+	if (
+		!isActiveHandoffLink({
+			link,
+			linkKey,
+			pairKey: sourcePairKey,
+			pairsState,
+		})
+	) {
+		return clearSignal(sourcePairKey);
+	}
+
+	if (!handoff) {
+		return {
+			hostScreenKey: currentScreenKey,
+			ownerPairKey: sourcePairKey,
+			ownerScreenKey: currentScreenKey,
+			status: "complete",
+		};
+	}
+
+	let hostScreenKey = link.destination.screenKey;
+	let ownerPairKey = sourcePairKey;
+	let previousOwnerPairKey: ScreenPairKey | null = null;
+	const seenScreenKeys: ScreenKey[] = [
+		getSourceScreenKeyFromPairKey(sourcePairKey),
+		hostScreenKey,
+	];
+
+	const pairKeys = Object.keys(pairsState);
+
+	for (let hop = 0; hop < pairKeys.length; hop++) {
+		let didAdvance = false;
+		let hasPendingNextHop = false;
+		let didHitVisitedScreen = false;
+
+		for (let index = 0; index < pairKeys.length; index++) {
+			const candidatePairKey = pairKeys[index];
+			if (!candidatePairKey || candidatePairKey === ownerPairKey) {
+				continue;
+			}
+
+			const candidate = getPairLink(pairsState, candidatePairKey, linkKey);
+			if (!candidate?.source || candidate.source.screenKey !== hostScreenKey) {
+				continue;
+			}
+
+			if (!candidate.source.handoff) {
+				continue;
+			}
+
+			if (
+				!isActiveHandoffLink({
+					link: candidate,
+					linkKey,
+					pairKey: candidatePairKey,
+					pairsState,
+				})
+			) {
+				continue;
+			}
+
+			if (candidate.status !== "complete") {
+				hasPendingNextHop = true;
+				continue;
+			}
+
+			const nextHostScreenKey = candidate.destination.screenKey;
+
+			previousOwnerPairKey = ownerPairKey;
+			ownerPairKey = candidatePairKey;
+			hostScreenKey = nextHostScreenKey;
+
+			if (hasSeenScreenKey(seenScreenKeys, nextHostScreenKey)) {
+				didHitVisitedScreen = true;
+				break;
+			}
+
+			seenScreenKeys.push(nextHostScreenKey);
+			didAdvance = true;
+			break;
+		}
+
+		if (didHitVisitedScreen) {
+			break;
+		}
+
+		if (didAdvance) {
+			continue;
+		}
+
+		if (hasPendingNextHop) {
+			return pendingSignal(ownerPairKey);
+		}
+
+		break;
+	}
+
+	const ownerLink = getPairLink(pairsState, ownerPairKey, linkKey);
+	const ownerUsesEscapeClipping =
+		ownerLink?.source?.escapeClipping ?? escapeClipping;
+
+	if (
+		!ownerUsesEscapeClipping &&
+		isSettledHostClosingComplete &&
+		settledHostScreenKey === hostScreenKey &&
+		previousOwnerPairKey
+	) {
+		hostScreenKey = getSourceScreenKeyFromPairKey(ownerPairKey);
+	}
+
+	const ownerScreenKey = ownerUsesEscapeClipping
+		? getSourceScreenKeyFromPairKey(ownerPairKey)
+		: resolveBoundaryLocalStyleOwnerScreenKey({
+				hostScreenKey,
+				isSettledHostReady,
+				settledHostScreenKey,
+				sourceScreenKey: getSourceScreenKeyFromPairKey(ownerPairKey),
+			});
+
+	return {
+		hostScreenKey,
+		ownerPairKey,
+		ownerScreenKey,
+		status: "complete",
+	};
+};
+
+export const hasHandoffEscapeContinuation = ({
+	linkKey,
+	linkState,
+	sourceScreenKey,
+}: {
+	linkKey: string;
+	linkState: LinkPairsState;
+	sourceScreenKey: ScreenKey;
+}) => {
+	"worklet";
+	const pairKeys = Object.keys(linkState);
+	const visitedScreenKeys: ScreenKey[] = [];
+	let cursorScreenKey = sourceScreenKey;
+
+	for (let hop = 0; hop < pairKeys.length; hop++) {
+		if (hasSeenScreenKey(visitedScreenKeys, cursorScreenKey)) {
+			return false;
+		}
+		visitedScreenKeys.push(cursorScreenKey);
+
+		let previousScreenKey: ScreenKey | null = null;
+		for (let index = 0; index < pairKeys.length; index++) {
+			const candidatePairKey = pairKeys[index];
+			const link = candidatePairKey
+				? linkState[candidatePairKey]?.links?.[linkKey]
+				: null;
+
+			if (
+				!link?.source ||
+				!link.destination ||
+				link.destination.screenKey !== cursorScreenKey
+			) {
+				continue;
+			}
+
+			if (usesEscapeClippingHost(link)) {
+				return true;
+			}
+
+			if (!link.source.handoff) {
+				return false;
+			}
+
+			previousScreenKey = link.source.screenKey;
+			break;
+		}
+
+		if (!previousScreenKey) {
+			return false;
+		}
+
+		cursorScreenKey = previousScreenKey;
+	}
+
+	return false;
+};

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

@@ -0,0 +1,50 @@
+import { logger } from "../../../../utils/logger";
+import { isTeleportAvailable } from "../teleport";
+
+export type BoundaryPortalRuntime = {
+	handoff: boolean;
+	escapeClipping: boolean;
+	enabled: boolean;
+};
+
+type ResolveBoundaryPortalParams = {
+	handoff?: boolean;
+	escapeClipping?: boolean;
+};
+
+export const resolveBoundaryPortal = ({
+	handoff,
+	escapeClipping,
+}: ResolveBoundaryPortalParams): BoundaryPortalRuntime => {
+	const resolvedHandoff = handoff ?? false;
+	const resolvedEscapeClipping = escapeClipping ?? false;
+
+	const enabled = resolvedHandoff || resolvedEscapeClipping;
+
+	if (!enabled) {
+		return {
+			handoff: false,
+			escapeClipping: false,
+			enabled: false,
+		};
+	}
+
+	if (!isTeleportAvailable) {
+		logger.warnOnce(
+			"boundary:teleport-missing",
+			"react-native-teleport is not installed; handoff and escapeClipping boundaries will render inline.",
+		);
+
+		return {
+			handoff: false,
+			escapeClipping: false,
+			enabled: false,
+		};
+	}
+
+	return {
+		handoff: resolvedHandoff,
+		escapeClipping: resolvedEscapeClipping,
+		enabled,
+	};
+};

package/src/shared/components/boundary/portal/utils/shallow-equal.ts

@@ -0,0 +1,25 @@
+/**
+ * Shallow equality for the flat signal objects produced by the portal
+ * `useAnimatedReaction` blocks. Both sides always carry the same fixed key set,
+ * so iterating one side's keys is sufficient. A `null`/`undefined` operand
+ * (the first reaction run) is treated as not-equal so the reaction proceeds.
+ */
+export const shallowEqual = (
+	a: Record<string, unknown> | null | undefined,
+	b: Record<string, unknown> | null | undefined,
+) => {
+	"worklet";
+	if (!a || !b) {
+		return false;
+	}
+
+	const keys = Object.keys(a);
+	for (let index = 0; index < keys.length; index++) {
+		const key = keys[index];
+		if (a[key] !== b[key]) {
+			return false;
+		}
+	}
+
+	return true;
+};

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

@@ -11,3 +11,15 @@ export const isTeleportEnabled = (
 
 	return teleport?.enabled !== false;
 };
+
+export const shouldAttachBoundaryPortal = ({
+	enabled,
+	teleport,
+}: {
+	enabled: boolean;
+	teleport?: BoundaryTeleportControl;
+}) => {
+	"worklet";
+
+	return enabled && isTeleportEnabled(teleport);
+};

package/src/shared/components/boundary/portal/utils/visible-host.ts

@@ -0,0 +1,24 @@
+export const resolveNextVisiblePortalHostName = ({
+	canSwitchImmediately,
+	isInterpolatorReady,
+	requestedName,
+	shouldTeleport,
+	visibleName,
+}: {
+	canSwitchImmediately?: boolean;
+	isInterpolatorReady: boolean;
+	requestedName: string | null;
+	shouldTeleport: boolean;
+	visibleName: string | null;
+}) => {
+	"worklet";
+	if (!shouldTeleport) {
+		return null;
+	}
+
+	if (requestedName && (canSwitchImmediately || isInterpolatorReady)) {
+		return requestedName;
+	}
+
+	return visibleName;
+};

package/src/shared/components/boundary/providers/{boundary-owner.provider.tsx → boundary-root.provider.tsx}

@@ -1,18 +1,13 @@
-import type React from "react";
-import { type ReactNode, useCallback, useMemo, useRef, useState } from "react";
+import { type ReactNode, useCallback, useMemo, useState } from "react";
 import type { View } from "react-native";
-import type Animated from "react-native-reanimated";
 import type { AnimatedRef, StyleProps } from "react-native-reanimated";
+import { useAnimatedRef } from "react-native-reanimated";
+import type { BoundTag } from "../../../stores/bounds/types";
 import createProvider from "../../../utils/create-provider";
 import { logger } from "../../../utils/logger";
-import type { BoundaryPortal } from "../types";
+import type { BoundaryPortalRuntime } from "../portal/utils/resolve-portal";
 
-type BoundaryAssociatedStyle = React.ComponentProps<
-	typeof Animated.View
->["style"];
-
-interface BoundaryOwnerContextValue {
-	ownerRef: AnimatedRef<View>;
+interface BoundaryRootContextValue {
 	registerTargetRef: (
 		targetRef: AnimatedRef<View>,
 		preparedStyles: StyleProps,
@@ -20,9 +15,8 @@ interface BoundaryOwnerContextValue {
 	) => void;
 	unregisterTargetRef: (targetRef: AnimatedRef<View>) => void;
 	activeTargetRef: AnimatedRef<View> | null;
-	associatedTargetStyles?: BoundaryAssociatedStyle;
-	entryTag: string;
-	portal?: BoundaryPortal;
+	boundTag: BoundTag;
+	portalRuntime: BoundaryPortalRuntime;
 }
 
 type BoundaryTargetEntry = {
@@ -34,30 +28,28 @@ type BoundaryTargetEntry = {
 
 // logger.warn prepends the library prefix.
 const MULTIPLE_TARGETS_WARNING =
-	"Multiple Boundary.Target elements were rendered under the same boundary owner. The first registered target will be measured.";
+	"Multiple Boundary.Target elements were rendered under the same boundary root. The first registered target will be measured.";
 
-export const TARGET_OUTSIDE_OWNER_WARNING =
-	"Boundary.Target must be rendered inside a Boundary owner (Boundary.View, Boundary.Trigger, or a component created by createBoundaryComponent).";
+export const TARGET_OUTSIDE_ROOT_WARNING =
+	"Boundary.Target must be rendered inside Transition.Boundary or a component created by createBoundaryComponent.";
 
-interface BoundaryOwnerProps {
-	value: BoundaryOwnerContextValue;
+interface BoundaryRootProps {
+	value: BoundaryRootContextValue;
 	children: ReactNode;
 }
 
-export const { BoundaryOwnerProvider, useBoundaryOwnerContext } =
-	createProvider("BoundaryOwner", { guarded: false })<
-		BoundaryOwnerProps,
-		BoundaryOwnerContextValue
-	>((props) => props);
+export const { BoundaryRootProvider, useBoundaryRootContext } = createProvider(
+	"BoundaryRoot",
+	{ guarded: false },
+)<BoundaryRootProps, BoundaryRootContextValue>((props) => props);
 
-export const useBoundaryOwner = (params: {
-	ownerRef: AnimatedRef<View>;
-	associatedTargetStyles?: BoundaryAssociatedStyle;
-	entryTag: string;
-	portal?: BoundaryPortal;
+export const useBoundaryRootState = (params: {
+	boundTag: BoundTag;
+	portalRuntime: BoundaryPortalRuntime;
+	rootMeasurementRef?: AnimatedRef<View>;
 }) => {
-	const { ownerRef, associatedTargetStyles, entryTag, portal } = params;
-	const warnedAboutMultipleTargetsRef = useRef(false);
+	const { boundTag, portalRuntime, rootMeasurementRef } = params;
+	const rootRef = useAnimatedRef<View>();
 	const [targetEntry, setTargetEntry] = useState<BoundaryTargetEntry | null>(
 		null,
 	);
@@ -73,13 +65,11 @@ export const useBoundaryOwner = (params: {
 					return prev;
 				}
 
-				if (
-					__DEV__ &&
-					prev !== null &&
-					!warnedAboutMultipleTargetsRef.current
-				) {
-					warnedAboutMultipleTargetsRef.current = true;
-					logger.warn(MULTIPLE_TARGETS_WARNING);
+				if (__DEV__ && prev !== null) {
+					logger.warnOnce(
+						"boundary:multiple-targets",
+						MULTIPLE_TARGETS_WARNING,
+					);
 				}
 
 				return (
@@ -100,30 +90,26 @@ export const useBoundaryOwner = (params: {
 
 	const contextValue = useMemo(
 		() => ({
-			ownerRef,
 			registerTargetRef,
 			unregisterTargetRef,
 			activeTargetRef: targetEntry?.ref ?? null,
-			associatedTargetStyles,
-			entryTag,
-			portal,
+			boundTag,
+			portalRuntime,
 		}),
 		[
-			ownerRef,
 			registerTargetRef,
 			unregisterTargetRef,
 			targetEntry,
-			associatedTargetStyles,
-			entryTag,
-			portal,
+			boundTag,
+			portalRuntime,
 		],
 	);
 
 	return {
+		ref: rootRef,
 		contextValue,
 		hasActiveTarget: targetEntry !== null,
-		measuredRef: targetEntry?.measurementRef ?? ownerRef,
+		measuredRef: targetEntry?.measurementRef ?? rootMeasurementRef ?? rootRef,
 		targetPreparedStyles: targetEntry?.preparedStyles,
-		portal,
 	};
 };

package/src/shared/components/boundary/types.ts

@@ -3,35 +3,6 @@ import type { BoundsOptions } from "../../utils/bounds/types/options";
 
 export type BoundaryId = string | number;
 
-export type BoundaryPortalAttachTarget = "current-screen" | "matched-screen";
-
-/**
- * Configures automatic portal attachment for a boundary target.
- *
- * `attachTo` selects where the portal physically renders. Independently of
- * that choice, `Transition.Boundary.Host` marks the screen-local coordinate
- * space the portal should render within.
- *
- * - `current-screen`: the portal attaches to this screen's active host — for a
- *   scroll-hosted screen, place `Transition.Boundary.Host` inside that
- *   ScrollView to make the content ride with it.
- * - `matched-screen`: the portal attaches to the matched screen's active host
- *   for the whole transition (open and close), which avoids re-parenting
- *   flicker while keeping the source placeholder measured at home.
- */
-export type BoundaryPortalOptions = {
-	/**
-	 * `current-screen` keeps the portal on this boundary's screen.
-	 * `matched-screen` moves it to the matched screen once the
-	 * source/destination link completes.
-	 *
-	 * @default "current-screen"
-	 */
-	attachTo?: BoundaryPortalAttachTarget;
-};
-
-export type BoundaryPortal = boolean | BoundaryPortalOptions;
-
 export type BoundaryConfigProps = Pick<
 	BoundsOptions,
 	"anchor" | "scaleMode" | "target" | "method"
@@ -55,20 +26,19 @@ export interface BoundaryOwnProps extends BoundaryConfigProps {
 	 */
 	enabled?: boolean;
 	/**
-	 * Renders this boundary target through a layout-preserving portal when
-	 * `react-native-teleport` is installed.
-	 *
-	 * The target keeps its measured layout space in the original tree. Once the
-	 * active source/destination link for this boundary is complete, the screen
-	 * portal layer can render a boundary-specific host and attach this target to
-	 * it so the active matched target escapes local clipping.
+	 * Teleports this boundary's live payload to the next matching boundary while
+	 * a transition is active.
 	 *
-	 * Use `true` to attach to the current screen host. Use
-	 * `{ attachTo: "matched-screen" }` to attach to the matched screen host.
+	 * @default false
+	 */
+	handoff?: boolean;
+	/**
+	 * Renders this boundary through the current screen's portal host while a
+	 * transition is active so the payload can escape clipping/layout constraints.
 	 *
 	 * @default false
 	 */
-	portal?: BoundaryPortal;
+	escapeClipping?: boolean;
 	id: BoundaryId;
 }