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

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

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

@@ -1,16 +1,11 @@
 import type React from "react";
-import {
-	createContext,
-	type ReactNode,
-	useCallback,
-	useContext,
-	useMemo,
-	useRef,
-	useState,
-} from "react";
+import { type ReactNode, useCallback, useMemo, useRef, 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 createProvider from "../../../utils/create-provider";
+import { logger } from "../../../utils/logger";
+import type { BoundaryPortal } from "../types";
 
 type BoundaryAssociatedStyle = React.ComponentProps<
 	typeof Animated.View
@@ -21,56 +16,58 @@ interface BoundaryOwnerContextValue {
 	registerTargetRef: (
 		targetRef: AnimatedRef<View>,
 		preparedStyles: StyleProps,
+		measurementRef?: AnimatedRef<View>,
 	) => void;
 	unregisterTargetRef: (targetRef: AnimatedRef<View>) => void;
 	activeTargetRef: AnimatedRef<View> | null;
 	associatedTargetStyles?: BoundaryAssociatedStyle;
+	entryTag: string;
+	portal?: BoundaryPortal;
 }
 
 type BoundaryTargetEntry = {
 	ref: AnimatedRef<View>;
+	/** Surface to measure — the portal placeholder when content can teleport. */
+	measurementRef: AnimatedRef<View>;
 	preparedStyles: StyleProps;
 };
 
-const BoundaryOwnerContext = createContext<BoundaryOwnerContextValue | null>(
-	null,
-);
-
+// logger.warn prepends the library prefix.
 const MULTIPLE_TARGETS_WARNING =
-	"[react-native-screen-transitions] 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 owner. The first registered target will be measured.";
 
 export const TARGET_OUTSIDE_OWNER_WARNING =
-	"[react-native-screen-transitions] Boundary.Target must be rendered inside a Boundary owner (Boundary.View, Boundary.Trigger, or a component created by createBoundaryComponent).";
+	"Boundary.Target must be rendered inside a Boundary owner (Boundary.View, Boundary.Trigger, or a component created by createBoundaryComponent).";
 
-export const BoundaryOwnerProvider = (props: {
+interface BoundaryOwnerProps {
 	value: BoundaryOwnerContextValue;
 	children: ReactNode;
-}) => {
-	const { value, children } = props;
-
-	return (
-		<BoundaryOwnerContext.Provider value={value}>
-			{children}
-		</BoundaryOwnerContext.Provider>
-	);
-};
+}
 
-export const useBoundaryOwnerContext = () => {
-	return useContext(BoundaryOwnerContext);
-};
+export const { BoundaryOwnerProvider, useBoundaryOwnerContext } =
+	createProvider("BoundaryOwner", { guarded: false })<
+		BoundaryOwnerProps,
+		BoundaryOwnerContextValue
+	>((props) => props);
 
 export const useBoundaryOwner = (params: {
 	ownerRef: AnimatedRef<View>;
 	associatedTargetStyles?: BoundaryAssociatedStyle;
+	entryTag: string;
+	portal?: BoundaryPortal;
 }) => {
-	const { ownerRef, associatedTargetStyles } = params;
+	const { ownerRef, associatedTargetStyles, entryTag, portal } = params;
 	const warnedAboutMultipleTargetsRef = useRef(false);
 	const [targetEntry, setTargetEntry] = useState<BoundaryTargetEntry | null>(
 		null,
 	);
 
 	const registerTargetRef = useCallback(
-		(targetRef: AnimatedRef<View>, preparedStyles: StyleProps) => {
+		(
+			targetRef: AnimatedRef<View>,
+			preparedStyles: StyleProps,
+			measurementRef?: AnimatedRef<View>,
+		) => {
 			setTargetEntry((prev) => {
 				if (prev?.ref === targetRef) {
 					return prev;
@@ -82,10 +79,16 @@ export const useBoundaryOwner = (params: {
 					!warnedAboutMultipleTargetsRef.current
 				) {
 					warnedAboutMultipleTargetsRef.current = true;
-					console.warn(MULTIPLE_TARGETS_WARNING);
+					logger.warn(MULTIPLE_TARGETS_WARNING);
 				}
 
-				return prev ?? { ref: targetRef, preparedStyles };
+				return (
+					prev ?? {
+						ref: targetRef,
+						measurementRef: measurementRef ?? targetRef,
+						preparedStyles,
+					}
+				);
 			});
 		},
 		[],
@@ -102,6 +105,8 @@ export const useBoundaryOwner = (params: {
 			unregisterTargetRef,
 			activeTargetRef: targetEntry?.ref ?? null,
 			associatedTargetStyles,
+			entryTag,
+			portal,
 		}),
 		[
 			ownerRef,
@@ -109,13 +114,16 @@ export const useBoundaryOwner = (params: {
 			unregisterTargetRef,
 			targetEntry,
 			associatedTargetStyles,
+			entryTag,
+			portal,
 		],
 	);
 
 	return {
 		contextValue,
 		hasActiveTarget: targetEntry !== null,
-		measuredRef: targetEntry?.ref ?? ownerRef,
+		measuredRef: targetEntry?.measurementRef ?? ownerRef,
 		targetPreparedStyles: targetEntry?.preparedStyles,
+		portal,
 	};
 };

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

@@ -0,0 +1,92 @@
+import type { ScreenPairKey } from "../../stores/bounds/types";
+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"
+>;
+
+/**
+ * Boundary-specific props shared across all boundary component variants.
+ * These are the props that `createBoundaryComponent` extracts and handles
+ * internally, regardless of the underlying wrapped component.
+ */
+export interface BoundaryOwnProps extends BoundaryConfigProps {
+	/**
+	 * Optional group name for collection/list scenarios.
+	 * When provided, concrete boundary entries use `group:id`, while transition
+	 * links stay keyed by the member `id` inside the active screen pair.
+	 */
+	group?: string;
+	/**
+	 * Whether this boundary should participate in matching and measurement.
+	 * @default true
+	 */
+	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.
+	 *
+	 * Use `true` to attach to the current screen host. Use
+	 * `{ attachTo: "matched-screen" }` to attach to the matched screen host.
+	 *
+	 * @default false
+	 */
+	portal?: BoundaryPortal;
+	id: BoundaryId;
+}
+
+/**
+ * Full props for a boundary component wrapping a component with props `P`.
+ * Omits `id` from the wrapped component's props (since boundary uses its own `id`).
+ */
+export type BoundaryComponentProps<P extends object> = Omit<P, "id"> &
+	BoundaryOwnProps;
+
+export type MeasureTarget =
+	| {
+			type: "source";
+			pairKey: ScreenPairKey;
+	  }
+	| {
+			type: "destination";
+			pairKey: ScreenPairKey;
+	  };
+
+export type MeasureBoundary = (target: MeasureTarget) => void;

package/src/shared/components/boundary/utils/destination-signals.ts

@@ -0,0 +1,31 @@
+import type {
+	LinkPairsState,
+	ScreenPairKey,
+} from "../../../stores/bounds/types";
+
+export const getInitialDestinationMeasurePairKey = (params: {
+	enabled: boolean;
+	destinationPairKey?: ScreenPairKey;
+	ancestorDestinationPairKey?: ScreenPairKey;
+	linkId: string;
+	linkState?: LinkPairsState;
+}): ScreenPairKey | null => {
+	"worklet";
+	const {
+		enabled,
+		destinationPairKey,
+		ancestorDestinationPairKey,
+		linkId,
+		linkState,
+	} = params;
+	const measurePairKey = destinationPairKey ?? ancestorDestinationPairKey;
+
+	if (!enabled || !measurePairKey) {
+		return null;
+	}
+
+	const hasDestination =
+		linkState?.[measurePairKey]?.links?.[linkId]?.destination;
+
+	return hasDestination ? null : measurePairKey;
+};

package/src/shared/components/{create-boundary-component → boundary}/utils/measured-bounds.ts

@@ -4,17 +4,31 @@ import {
 	type MeasuredDimensions,
 	measure,
 } from "react-native-reanimated";
+import {
+	clampScrollAxisOffset,
+	cloneScrollMetadataState,
+} from "../../../stores/scroll.store";
 import type {
 	ScrollGestureAxisState,
 	ScrollGestureState,
+	ScrollMetadataState,
 } from "../../../types/gesture.types";
 
 const SCROLL_MEASUREMENT_EPSILON = 1;
 
-const getOverscrollDelta = (axisState: ScrollGestureAxisState): number => {
+export type ScrollMeasuredDimensions = MeasuredDimensions & {
+	scroll?: ScrollMetadataState | null;
+};
+
+const getOverscrollDelta = (
+	axisState: ScrollGestureAxisState | null | undefined,
+): number => {
 	"worklet";
-	const maxOffset = Math.max(0, axisState.contentSize - axisState.layoutSize);
-	const clampedOffset = Math.min(Math.max(axisState.offset, 0), maxOffset);
+	const clampedOffset = clampScrollAxisOffset(axisState);
+	if (!axisState || clampedOffset === null) {
+		return 0;
+	}
+
 	const delta = axisState.offset - clampedOffset;
 
 	return Math.abs(delta) > SCROLL_MEASUREMENT_EPSILON ? delta : 0;
@@ -22,7 +36,7 @@ const getOverscrollDelta = (axisState: ScrollGestureAxisState): number => {
 
 export const adjustedMeasuredBoundsForOverscrollDeltas = (
 	measured: MeasuredDimensions,
-	scrollState: ScrollGestureState | null,
+	scrollState: ScrollGestureState | ScrollMetadataState | null,
 ): MeasuredDimensions => {
 	"worklet";
 
@@ -46,18 +60,15 @@ export const adjustedMeasuredBoundsForOverscrollDeltas = (
 	};
 };
 
-export const applyVisibilityBlockOffset = (
+export const normalizeMeasuredBoundsToOrigin = (
 	measured: MeasuredDimensions,
-	offset: number,
+	origin: MeasuredDimensions,
 ): MeasuredDimensions => {
 	"worklet";
-	if (offset === 0) {
-		return measured;
-	}
-
 	return {
 		...measured,
-		pageY: measured.pageY - offset,
+		pageX: measured.pageX - origin.pageX,
+		pageY: measured.pageY - origin.pageY,
 	};
 };
 
@@ -95,3 +106,15 @@ export const measureWithOverscrollAwareness = (
 
 	return adjustedMeasuredBoundsForOverscrollDeltas(measured, scrollState);
 };
+
+export const attachScrollSnapshotToMeasuredBounds = (
+	measured: MeasuredDimensions,
+	scroll: ScrollMetadataState | null | undefined,
+): ScrollMeasuredDimensions => {
+	"worklet";
+
+	return {
+		...measured,
+		scroll: cloneScrollMetadataState(scroll),
+	};
+};