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

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

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

@@ -0,0 +1,175 @@
+import type {
+	LinkPairsState,
+	ScreenPairKey,
+} from "../../../stores/bounds/types";
+import type { MeasureTarget } from "../types";
+
+const SOURCE_SIGNAL_PREFIX = "source|";
+const DESTINATION_SIGNAL_PREFIX = "destination|";
+
+type RefreshBoundarySignal = MeasureTarget & {
+	signal: string;
+};
+
+const buildRefreshSignal = (
+	type: MeasureTarget["type"],
+	pairKey: ScreenPairKey,
+	key: string,
+): RefreshBoundarySignal => {
+	"worklet";
+	const prefix =
+		type === "source" ? SOURCE_SIGNAL_PREFIX : DESTINATION_SIGNAL_PREFIX;
+	return {
+		type,
+		pairKey,
+		signal: `${prefix}${pairKey}|${key}`,
+	};
+};
+
+const isMatchedScreenPortalDestinationRefresh = (
+	linkState: LinkPairsState | undefined,
+	pairKey: ScreenPairKey,
+	linkId: string,
+) => {
+	"worklet";
+
+	return (
+		linkState?.[pairKey]?.links?.[linkId]?.source?.portalAttachTarget ===
+		"matched-screen"
+	);
+};
+
+export const getRefreshBoundarySignal = (params: {
+	enabled: boolean;
+	currentScreenKey: string;
+	sourcePairKey?: ScreenPairKey;
+	destinationPairKey?: ScreenPairKey;
+	ancestorDestinationPairKey?: ScreenPairKey;
+	nextScreenKey?: string;
+	linkId: string;
+	group?: string;
+	shouldRefresh: boolean;
+	closing: boolean;
+	entering: boolean;
+	animating: boolean;
+	progress: number;
+	linkState?: LinkPairsState;
+}): RefreshBoundarySignal | null => {
+	"worklet";
+	const {
+		enabled,
+		currentScreenKey,
+		sourcePairKey,
+		destinationPairKey,
+		ancestorDestinationPairKey,
+		nextScreenKey,
+		linkId,
+		group,
+		shouldRefresh,
+		closing,
+		entering,
+		animating,
+		progress,
+		linkState,
+	} = params;
+
+	if (!enabled) return null;
+
+	const canRefreshPreCloseDestination =
+		shouldRefresh && closing && !entering && !animating && progress >= 1;
+
+	const canRefreshSettledDestination = shouldRefresh && !closing && !entering;
+
+	// Guards:
+	// 1) A user may dismiss via back button, in this case, we should remeasure.
+	// 2) If a user drags during entering/closing animations we should NOT remeasure.
+	if (!canRefreshPreCloseDestination && !canRefreshSettledDestination) {
+		return null;
+	}
+
+	// Non group:
+	// Since in typical group flows we would need to know the src, we don't need to do that for
+	// single a->b flows. So we just trigger the destination refresh.
+	if (!group) {
+		const refreshDestinationPairKey =
+			destinationPairKey ??
+			(nextScreenKey ? undefined : ancestorDestinationPairKey);
+
+		if (!refreshDestinationPairKey) {
+			return null;
+		}
+
+		// NOTE:
+		// Matched-screen portals use the destination as the initial host/anchor.
+		// Once attached, the teleported source is the thing being animated, so a
+		// fresh destination measure would mix in a second coordinate basis. Signals were introduced for scroll view cases + group
+		// cases, but I can't find a case for where a live component ( matched-screen ) would need this complexity. I would just assume
+		// you would want this for a->b | b->a transitions.
+		if (
+			isMatchedScreenPortalDestinationRefresh(
+				linkState,
+				refreshDestinationPairKey,
+				linkId,
+			)
+		) {
+			return null;
+		}
+
+		return buildRefreshSignal(
+			"destination",
+			refreshDestinationPairKey,
+			[currentScreenKey, closing ? "closing" : "settled"].join("|"),
+		);
+	}
+
+	// Source side:
+	// When the activeId changes, trigger a refresh to ensure the source bounds are captured.
+	if (sourcePairKey) {
+		const activeId = linkState?.[sourcePairKey]?.groups?.[group]?.activeId;
+
+		if (activeId !== linkId) {
+			return null;
+		}
+
+		return buildRefreshSignal(
+			"source",
+			sourcePairKey,
+			[group, linkId, closing ? "closing" : "settled"].join("|"),
+		);
+	}
+
+	const refreshDestinationPairKey =
+		destinationPairKey ??
+		(nextScreenKey ? undefined : ancestorDestinationPairKey);
+
+	if (!refreshDestinationPairKey) return null;
+
+	// Destination side:
+	// When the activeId changes, trigger a refresh to ensure the destination bounds are captured.
+	const activeId =
+		linkState?.[refreshDestinationPairKey]?.groups?.[group]?.activeId;
+
+	// Destination retargeting should only measure a concrete member that already
+	// participates in the pair. Missing members fall back to initialId at resolve.
+	if (activeId !== linkId) {
+		return null;
+	}
+
+	// NOTE:
+	// see above for explanation
+	if (
+		isMatchedScreenPortalDestinationRefresh(
+			linkState,
+			refreshDestinationPairKey,
+			linkId,
+		)
+	) {
+		return null;
+	}
+
+	return buildRefreshSignal(
+		"destination",
+		refreshDestinationPairKey,
+		[group, linkId, closing ? "closing" : "settled"].join("|"),
+	);
+};

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

@@ -0,0 +1,63 @@
+import type {
+	LinkPairsState,
+	ScreenPairKey,
+} from "../../../stores/bounds/types";
+
+const SOURCE_SIGNAL_PREFIX = "source|";
+
+type SourceCaptureSignal = {
+	pairKey: ScreenPairKey;
+	signal: string;
+};
+
+export const getInitialSourceCaptureSignal = (params: {
+	enabled: boolean;
+	sourcePairKey?: ScreenPairKey;
+	linkId: string;
+	group?: string;
+	shouldAutoMeasure: boolean;
+	linkState?: LinkPairsState;
+}): SourceCaptureSignal | null => {
+	"worklet";
+	const {
+		enabled,
+		sourcePairKey,
+		linkId,
+		group,
+		shouldAutoMeasure,
+		linkState,
+	} = params;
+
+	if (!enabled || !sourcePairKey) {
+		return null;
+	}
+
+	// Trigger components capture on press. Passive Boundary.View sources wait for
+	// their destination side to attach, then capture into the same assigned pair.
+	if (!shouldAutoMeasure) {
+		return null;
+	}
+
+	const link = linkState?.[sourcePairKey]?.links?.[linkId];
+
+	if (!link?.destination || link.source) {
+		return null;
+	}
+
+	if (group) {
+		const activeId = linkState?.[sourcePairKey]?.groups?.[group]?.activeId;
+
+		// Passive grouped sources should not measure every mounted item. Once a
+		// group has an active id, only that concrete member can auto-capture.
+		if (activeId && activeId !== linkId) {
+			return null;
+		}
+	}
+
+	const signalParts = group ? [group, linkId] : [linkId];
+
+	return {
+		pairKey: sourcePairKey,
+		signal: `${SOURCE_SIGNAL_PREFIX}${sourcePairKey}|${signalParts.join("|")}`,
+	};
+};

package/src/shared/components/create-transition-aware-component.tsx

@@ -43,6 +43,8 @@ export function createTransitionAwareComponent<P extends object>(
 			onScroll: userOnScroll,
 			onMomentumScrollEnd: userOnMomentumScrollEnd,
 			onScrollEndDrag: userOnScrollEndDrag,
+			children,
+			contentContainerStyle,
 			...scrollableProps
 		} = props;
 
@@ -69,11 +71,11 @@ export function createTransitionAwareComponent<P extends object>(
 			scrollHandler,
 			userOnScroll ?? null,
 		]);
-
 		const scrollableComponent = (
 			<AnimatedComponent
 				{...(scrollableProps as any)}
 				ref={ref}
+				contentContainerStyle={contentContainerStyle}
 				/**
 				 * Keep the scroll listener detached while the owning gesture screen is
 				 * closing. On iOS, a bounced ScrollView can keep sending native scroll
@@ -90,7 +92,9 @@ export function createTransitionAwareComponent<P extends object>(
 						? scrollableProps.scrollEventThrottle || 16
 						: undefined
 				}
-			/>
+			>
+				{children}
+			</AnimatedComponent>
 		);
 
 		const coordinatedScrollableComponent = nativeGesture ? (
@@ -119,6 +123,7 @@ export function createTransitionAwareComponent<P extends object>(
 			styleId,
 			onPress,
 			remeasureOnFocus,
+			animatedProps: userAnimatedProps,
 			...rest
 		} = props as any;
 
@@ -159,7 +164,7 @@ export function createTransitionAwareComponent<P extends object>(
 						{...(rest as any)}
 						ref={animatedRef}
 						style={[style, associatedStyles]}
-						animatedProps={associatedProps}
+						animatedProps={userAnimatedProps ?? associatedProps}
 						onPress={captureActiveOnPress}
 						onLayout={runOnUI(handleInitialLayout)}
 						collapsable={!sharedBoundTag}

package/src/shared/components/{integrations/masked-view.tsx → masked-view.tsx}

@@ -1,6 +1,6 @@
 import { type StyleProp, StyleSheet, View, type ViewStyle } from "react-native";
-import { CONTAINER_STYLE_ID, MASK_STYLE_ID } from "../../constants";
-import { createTransitionAwareComponent } from "../create-transition-aware-component";
+import { CONTAINER_STYLE_ID, MASK_STYLE_ID } from "../constants";
+import { createTransitionAwareComponent } from "./create-transition-aware-component";
 
 const TransitionView = createTransitionAwareComponent(View);
 

package/src/shared/components/screen-container/layers/content.tsx

@@ -9,7 +9,9 @@ import Animated, {
 import { NO_PROPS, NO_STYLES } from "../../../constants";
 import { useDescriptors } from "../../../providers/screen/descriptors";
 import { useGestureContext } from "../../../providers/screen/gestures";
+import { OriginProvider } from "../../../providers/screen/origin.provider";
 import { useScreenStyles } from "../../../providers/screen/styles";
+import { ScreenFallbackHost } from "../../boundary/portal/components/host";
 import { useContentLayout } from "../hooks/use-content-layout";
 import { MaybeMaskedNavigationContainer } from "./maybe-masked-navigation-container";
 import { SurfaceContainer } from "./surface-container";
@@ -56,13 +58,16 @@ export const ContentLayer = memo(
 						enabled={isNavigationMaskEnabled}
 					>
 						<SurfaceContainer pointerEvents={contentPointerEvents}>
-							{hasAutoSnapPoint ? (
-								<View collapsable={false} onLayout={handleContentLayout}>
-									{children}
-								</View>
-							) : (
-								children
-							)}
+							<OriginProvider>
+								{hasAutoSnapPoint ? (
+									<View collapsable={false} onLayout={handleContentLayout}>
+										{children}
+									</View>
+								) : (
+									children
+								)}
+								<ScreenFallbackHost />
+							</OriginProvider>
 						</SurfaceContainer>
 					</MaybeMaskedNavigationContainer>
 				</Animated.View>