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

package/lib/typescript/shared/utils/bounds/types/options.d.ts

@@ -1,12 +1,71 @@
 import type { MeasuredDimensions, StyleProps } from "react-native-reanimated";
 import type { ScreenTransitionState } from "../../../types/animation.types";
-import type { BoundsMethod } from "../../../types/bounds.types";
+import type { BoundsInterpolationProps, BoundsMethod } from "../../../types/bounds.types";
 import type { Layout } from "../../../types/screen.types";
 export type BoundId = string | number;
 export type BoundsAnchor = "topLeading" | "top" | "topTrailing" | "leading" | "center" | "trailing" | "bottomLeading" | "bottom" | "bottomTrailing";
 export type BoundsScaleMode = "match" | "none" | "uniform";
 type BoundsTarget = "bound" | "fullscreen" | MeasuredDimensions;
 type BoundsSpace = "relative" | "absolute";
+/**
+ * Transform values exposed to a bounds motion resolver.
+ *
+ * `x` and `y` map to the generated translate values. `scale` is a uniform scale
+ * view of the generated transform; non-uniform bounds transforms keep their
+ * existing `scaleX`/`scaleY` ratio and apply returned `scale` as a multiplier.
+ *
+ * `rotateX`/`rotateY` are optional 3D tilts in degrees around the element
+ * center. When either is set, a `perspective` entry is prepended to the
+ * transform so the tilt projects in 3D.
+ */
+export type BoundsMotionTransform = {
+    x: number;
+    y: number;
+    scale: number;
+    /** Z-axis spin in degrees. */
+    rotate?: number;
+    rotateX?: number;
+    rotateY?: number;
+    /**
+     * Perspective distance, prepended to the transform when any rotation is
+     * present or when set explicitly.
+     * @default 1000
+     */
+    perspective?: number;
+    /**
+     * Pivot for the ENTIRE transform stack, including the generated
+     * translate/scale. Bounds geometry computes its translations assuming the
+     * default center origin, so non-center origins offset the path — best for
+     * rotation-dominant motion.
+     */
+    transformOrigin?: string | Array<string | number>;
+};
+/**
+ * Frame data passed to a bounds motion resolver: the generated transform
+ * (`current`), the resolved rects it travels between (`start`/`end` — these
+ * include target overrides and are not derivable from `props`), the phase
+ * (`progress`, normalized 0→1 regardless of enter/exit range), and the
+ * invoking interpolator's full `props`.
+ *
+ * `props` is screen-relative: the same motion can run under both the focused
+ * and unfocused screen's interpolators, and values like `props.active.gesture`
+ * differ per invocation. Direction is recoverable as `!props.next`; the raw
+ * un-normalized progress as `props.progress`.
+ */
+export type BoundsMotionFrame = {
+    progress: number;
+    current: BoundsMotionTransform;
+    start: MeasuredDimensions;
+    end: MeasuredDimensions;
+    props: BoundsInterpolationProps;
+};
+/**
+ * Worklet-safe function that can replace the generated bounds transform.
+ *
+ * Use this from `bounds({ motion })` to bend, delay, overshoot, or otherwise
+ * reshape a bounds transform without reimplementing the measurement logic.
+ */
+export type BoundsMotion = (frame: BoundsMotionFrame) => BoundsMotionTransform;
 export type BoundsComputeParams = {
     id?: BoundId;
     previous?: ScreenTransitionState;
@@ -14,32 +73,41 @@ export type BoundsComputeParams = {
     next?: ScreenTransitionState;
     progress: number;
     dimensions: Layout;
+    /** Invoking interpolator's props, surfaced to motion resolvers. */
+    interpolationProps: BoundsInterpolationProps;
 };
-type RawSizeAbsoluteReturn = {
+type RawMotionRotation = {
+    /** Degrees; non-zero only when a motion resolver returned a rotation. */
+    rotate: number;
+    rotateX: number;
+    rotateY: number;
+    transformOrigin?: string | Array<string | number>;
+};
+type RawSizeAbsoluteReturn = RawMotionRotation & {
     width: number;
     height: number;
     translateX: number;
     translateY: number;
 };
-type RawSizeRelativeReturn = {
+type RawSizeRelativeReturn = RawMotionRotation & {
     translateX: number;
     translateY: number;
     width: number;
     height: number;
 };
-type RawTransformAbsoluteReturn = {
+type RawTransformAbsoluteReturn = RawMotionRotation & {
     translateX: number;
     translateY: number;
     scaleX: number;
     scaleY: number;
 };
-type RawTransformRelativeReturn = {
+type RawTransformRelativeReturn = RawMotionRotation & {
     translateX: number;
     translateY: number;
     scaleX: number;
     scaleY: number;
 };
-type RawContentReturn = {
+type RawContentReturn = RawMotionRotation & {
     translateX: number;
     translateY: number;
     scale: number;
@@ -114,11 +182,30 @@ export type BoundsOptions = {
      * @default "center"
      */
     anchor?: BoundsAnchor;
+    /**
+     * Worklet-safe transform resolver for bounds output.
+     *
+     * `motion` receives the generated transform and returns the transform that
+     * should be rendered or returned from raw bounds. For `"size"` methods,
+     * returned `scale` is applied to the generated width and height.
+     */
+    motion?: BoundsMotion;
     /**
      * If true, the raw values will be returned instead of the computed values.
      * @default false
      */
     raw?: boolean;
 };
+export type BoundsIdentity = {
+    id: BoundId;
+    group?: string;
+};
+export type BoundsIdentityInput = BoundId | BoundsIdentity;
+export type BoundsComputeOptions = Omit<BoundsOptions, "group" | "id" | "raw">;
+export type BoundsStyleResult = StyleProps;
+export type BoundsMathResult<T extends BoundsComputeOptions = BoundsComputeOptions> = BoundsOptionsResult<T & {
+    id: BoundId;
+    raw: true;
+}>;
 export {};
 //# sourceMappingURL=options.d.ts.map

package/lib/typescript/shared/utils/bounds/types/options.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"options.d.ts","sourceRoot":"","sources":["../../../../../../src/shared/utils/bounds/types/options.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"options.d.ts","sourceRoot":"","sources":["../../../../../../src/shared/utils/bounds/types/options.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "react-native-screen-transitions",
-	"version": "3.8.0",
+	"version": "3.9.0-alpha.0",
 	"description": "Easy screen transitions for React Native and Expo",
 	"author": "Ed",
 	"license": "MIT",
@@ -84,7 +84,8 @@
 		"react-native-gesture-handler": ">=2.16.1",
 		"react-native-reanimated": ">=3.16.0 || >=4.0.0-",
 		"react-native-safe-area-context": "*",
-		"react-native-screens": ">=4.4.0"
+		"react-native-screens": ">=4.4.0",
+		"react-native-teleport": ">=1.1.0 <2.0.0"
 	},
 	"devDependencies": {
 		"@testing-library/react-native": "13.3.3",

package/src/blank-stack/components/stack-view.tsx

@@ -2,11 +2,12 @@ import {
 	NavigationContext,
 	NavigationRouteContext,
 } from "@react-navigation/native";
-import { Fragment, memo } from "react";
+import { memo } from "react";
 import {
 	ActivityContainer,
 	ActivityScreen,
 } from "../../shared/components/activity";
+import { PortalProvider } from "../../shared/components/boundary/portal";
 import { Overlay } from "../../shared/components/overlay";
 import { ScreenComposer } from "../../shared/providers/screen/screen-composer";
 import { withBlankStack } from "../../shared/providers/stack/blank-stack.provider";
@@ -56,7 +57,7 @@ export const StackView = withStackCore(
 	withBlankStack<BlankStackDescriptor, BlankStackNavigationHelpers>(
 		({ scenes, shouldShowFloatOverlay }) => {
 			return (
-				<Fragment>
+				<PortalProvider>
 					{shouldShowFloatOverlay ? <Overlay.Float /> : null}
 
 					<ActivityContainer>
@@ -73,7 +74,7 @@ export const StackView = withStackCore(
 							);
 						})}
 					</ActivityContainer>
-				</Fragment>
+				</PortalProvider>
 			);
 		},
 	),

package/src/shared/components/{create-boundary-component → boundary}/components/boundary-target.tsx

@@ -3,6 +3,8 @@ import { memo, useLayoutEffect, useMemo } from "react";
 import type { View } from "react-native";
 import Animated, { useAnimatedRef } from "react-native-reanimated";
 import { prepareStyleForBounds } from "../../../utils/bounds/helpers/styles/styles";
+import { logger } from "../../../utils/logger";
+import { Portal } from "../portal/components/portal";
 import {
 	TARGET_OUTSIDE_OWNER_WARNING,
 	useBoundaryOwnerContext,
@@ -15,21 +17,29 @@ export const BoundaryTarget = memo(function BoundaryTarget(
 ) {
 	const { style, ...rest } = props;
 	const targetAnimatedRef = useAnimatedRef<View>();
+	const placeholderAnimatedRef = useAnimatedRef<View>();
 	const ownerContext = useBoundaryOwnerContext();
 	const registerTargetRef = ownerContext?.registerTargetRef;
 	const unregisterTargetRef = ownerContext?.unregisterTargetRef;
 	const isActiveTarget = ownerContext?.activeTargetRef === targetAnimatedRef;
 	const preparedStyles = useMemo(() => prepareStyleForBounds(style), [style]);
+	// Portal'd content can be teleported into another screen's host; measuring
+	// it there would capture its CURRENT (destination) position as the source
+	// bounds. The portal placeholder keeps the layout slot at home, so it is
+	// the truthful measurement surface whenever a portal is configured.
+	const measurementRef = ownerContext?.portal
+		? placeholderAnimatedRef
+		: targetAnimatedRef;
 
 	useLayoutEffect(() => {
 		if (!registerTargetRef || !unregisterTargetRef) {
 			if (__DEV__) {
-				console.warn(TARGET_OUTSIDE_OWNER_WARNING);
+				logger.warn(TARGET_OUTSIDE_OWNER_WARNING);
 			}
 			return;
 		}
 
-		registerTargetRef(targetAnimatedRef, preparedStyles);
+		registerTargetRef(targetAnimatedRef, preparedStyles, measurementRef);
 		return () => {
 			unregisterTargetRef(targetAnimatedRef);
 		};
@@ -38,17 +48,24 @@ export const BoundaryTarget = memo(function BoundaryTarget(
 		unregisterTargetRef,
 		targetAnimatedRef,
 		preparedStyles,
+		measurementRef,
 	]);
 
 	return (
-		<Animated.View
-			{...rest}
-			ref={targetAnimatedRef}
-			style={[
-				style,
-				isActiveTarget ? ownerContext.associatedTargetStyles : undefined,
-			]}
-			collapsable={false}
-		/>
+		<Portal
+			id={ownerContext?.entryTag}
+			mode={ownerContext?.portal}
+			placeholderRef={placeholderAnimatedRef}
+		>
+			<Animated.View
+				{...rest}
+				ref={targetAnimatedRef}
+				style={[
+					style,
+					isActiveTarget ? ownerContext.associatedTargetStyles : undefined,
+				]}
+				collapsable={false}
+			/>
+		</Portal>
 	);
 });

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

@@ -13,7 +13,7 @@ import Animated, {
 	useAnimatedStyle,
 } from "react-native-reanimated";
 import { NO_STYLES } from "../../constants";
-import { useDescriptorDerivations } from "../../providers/screen/descriptors";
+import { useDescriptorsStore } from "../../providers/screen/descriptors";
 import { useScreenStyles } from "../../providers/screen/styles";
 import { createPendingPairKey } from "../../stores/bounds/helpers/link-pairs.helpers";
 import { prepareStyleForBounds } from "../../utils/bounds/helpers/styles/styles";
@@ -57,32 +57,22 @@ export function createBoundaryComponent<P extends object>(
 			method,
 			style,
 			onPress,
+			portal,
 			...rest
 		} = props as any;
 
 		const linkId = String(id);
 		const entryTag = group ? `${group}:${linkId}` : linkId;
 
-		const {
-			previousScreenKey: preferredSourceScreenKey,
-			currentScreenKey,
-			nextScreenKey,
-			ancestorKeys,
-			hasConfiguredInterpolator,
-		} = useDescriptorDerivations();
+		const currentScreenKey = useDescriptorsStore(
+			(s) => s.derivations.currentScreenKey,
+		);
+		const hasConfiguredInterpolator = useDescriptorsStore(
+			(s) => s.derivations.hasConfiguredInterpolator,
+		);
 
 		const runtimeEnabled = enabled && hasConfiguredInterpolator;
-		const hasNextScreen = !!nextScreenKey;
-		const boundaryConfig = useMemo<BoundaryConfigProps | undefined>(() => {
-			if (
-				anchor === undefined &&
-				scaleMode === undefined &&
-				target === undefined &&
-				method === undefined
-			) {
-				return undefined;
-			}
-
+		const boundaryConfig = useMemo<BoundaryConfigProps>(() => {
 			return {
 				anchor,
 				scaleMode,
@@ -119,10 +109,19 @@ export function createBoundaryComponent<P extends object>(
 			useBoundaryOwner({
 				ownerRef,
 				associatedTargetStyles: runtimeEnabled ? associatedStyles : undefined,
+				entryTag,
+				portal,
 			});
 
 		const preparedStyles = targetPreparedStyles ?? ownerPreparedStyles;
 
+		const portalHost =
+			typeof portal === "object"
+				? (portal.attachTo ?? "current-screen")
+				: portal
+					? "current-screen"
+					: undefined;
+
 		const measureBoundary = useMeasurer({
 			enabled,
 			entryTag,
@@ -131,10 +130,9 @@ export function createBoundaryComponent<P extends object>(
 			currentScreenKey,
 			preparedStyles,
 			measuredAnimatedRef: measuredRef,
+			portalHost,
 		});
 
-		const shouldRunDestinationEffects = runtimeEnabled && !hasNextScreen;
-
 		// Register/unregister this boundary in the presence map so source/destination
 		// matching can resolve across concrete screen keys.
 		useBoundaryPresence({
@@ -149,9 +147,7 @@ export function createBoundaryComponent<P extends object>(
 
 		useInitialSourceMeasurement({
 			enabled: runtimeEnabled,
-			nextScreenKey,
 			measureBoundary,
-			currentScreenKey,
 			linkId,
 			group,
 			shouldAutoMeasure: shouldPassivelyMeasureSource,
@@ -159,21 +155,14 @@ export function createBoundaryComponent<P extends object>(
 
 		useInitialDestinationMeasurement({
 			linkId,
-			enabled: shouldRunDestinationEffects,
-			currentScreenKey,
-			preferredSourceScreenKey,
-			ancestorScreenKeys: ancestorKeys,
+			enabled: runtimeEnabled,
 			measureBoundary,
 		});
 
 		useRefreshBoundary({
 			enabled: runtimeEnabled,
-			currentScreenKey,
-			preferredSourceScreenKey,
-			nextScreenKey,
 			linkId,
 			group,
-			ancestorScreenKeys: ancestorKeys,
 			measureBoundary,
 		});
 

package/src/shared/components/boundary/hooks/use-initial-destination-measurement.ts

@@ -0,0 +1,156 @@
+import {
+	cancelAnimation,
+	useAnimatedReaction,
+	useSharedValue,
+	withDelay,
+	withTiming,
+} from "react-native-reanimated";
+import { useDescriptorsStore } from "../../../providers/screen/descriptors";
+import { AnimationStore } from "../../../stores/animation.store";
+import { getDestination } from "../../../stores/bounds/internals/links";
+import { pairs } from "../../../stores/bounds/internals/state";
+import {
+	LifecycleTransitionRequestKind,
+	SystemStore,
+} from "../../../stores/system.store";
+import { logger } from "../../../utils/logger";
+import type { MeasureBoundary } from "../types";
+import { getInitialDestinationMeasurePairKey } from "../utils/destination-signals";
+
+const VIEWPORT_RETRY_DELAY_MS = 16;
+/**
+ * A destination that keeps failing its measurement guards must not hold the
+ * transition gate forever — after this budget the block is released with a
+ * warning so the open proceeds without that boundary.
+ */
+const MAX_VIEWPORT_RETRIES = 20;
+
+interface UseInitialDestinationMeasurementParams {
+	linkId: string;
+	enabled: boolean;
+	measureBoundary: MeasureBoundary;
+}
+
+export const useInitialDestinationMeasurement = ({
+	linkId,
+	enabled,
+	measureBoundary,
+}: UseInitialDestinationMeasurementParams) => {
+	const currentScreenKey = useDescriptorsStore(
+		(s) => s.derivations.currentScreenKey,
+	);
+	const nextScreenKey = useDescriptorsStore((s) => s.derivations.nextScreenKey);
+	const destinationPairKey = useDescriptorsStore(
+		(s) => s.derivations.destinationPairKey,
+	);
+	const ancestorDestinationPairKey = useDescriptorsStore(
+		(s) => s.derivations.ancestorDestinationPairKey,
+	);
+	const destinationEnabled = enabled && !nextScreenKey;
+	const progress = AnimationStore.getValue(
+		currentScreenKey,
+		"transitionProgress",
+	);
+	const system = SystemStore.getBag(currentScreenKey);
+	const { pendingLifecycleRequestKind } = system;
+	const { blockLifecycleStart, unblockLifecycleStart } = system.actions;
+	const isBlockingLifecycleStart = useSharedValue(0);
+	const retryToken = useSharedValue(0);
+	const viewportRetries = useSharedValue(0);
+	const hasGivenUp = useSharedValue(0);
+
+	const releaseLifecycleStartBlock = () => {
+		"worklet";
+		cancelAnimation(retryToken);
+
+		if (!isBlockingLifecycleStart.get()) {
+			return;
+		}
+
+		unblockLifecycleStart();
+		isBlockingLifecycleStart.set(0);
+	};
+
+	useAnimatedReaction(
+		() => {
+			"worklet";
+			const retryTick = retryToken.get();
+
+			const hasPendingOpenRequest =
+				pendingLifecycleRequestKind.get() ===
+				LifecycleTransitionRequestKind.Open;
+
+			const isWaitingForOpenToStart = progress.get() <= 0;
+
+			if (!hasPendingOpenRequest || !isWaitingForOpenToStart) {
+				return [0, retryTick] as const;
+			}
+
+			const measurePairKey = getInitialDestinationMeasurePairKey({
+				enabled: destinationEnabled,
+				destinationPairKey,
+				ancestorDestinationPairKey,
+				linkId,
+				linkState:
+					destinationEnabled &&
+					(destinationPairKey || ancestorDestinationPairKey)
+						? pairs.get()
+						: undefined,
+			});
+
+			return [measurePairKey, retryTick] as const;
+		},
+		([measurePairKey]) => {
+			"worklet";
+			if (!measurePairKey) {
+				releaseLifecycleStartBlock();
+				viewportRetries.set(0);
+				hasGivenUp.set(0);
+				return;
+			}
+
+			if (hasGivenUp.get()) {
+				return;
+			}
+
+			if (!isBlockingLifecycleStart.get()) {
+				blockLifecycleStart();
+				isBlockingLifecycleStart.set(1);
+			}
+
+			measureBoundary({
+				type: "destination",
+				pairKey: measurePairKey,
+			});
+
+			const destinationAttached =
+				getDestination(measurePairKey, linkId) !== null;
+
+			if (destinationAttached) {
+				releaseLifecycleStartBlock();
+				viewportRetries.set(0);
+				return;
+			}
+
+			if (viewportRetries.get() >= MAX_VIEWPORT_RETRIES) {
+				hasGivenUp.set(1);
+				releaseLifecycleStartBlock();
+				logger.warn(
+					`Destination boundary "${linkId}" never produced a valid measurement after ${MAX_VIEWPORT_RETRIES} attempts; releasing the transition gate without it. The boundary is likely off-viewport (e.g. an inactive group member on a paged screen) or unmounted.`,
+				);
+				return;
+			}
+
+			// Destination did not attach (malformed off-screen measurement); retry
+			// on the next tick while the lifecycle stays blocked.
+			viewportRetries.set(viewportRetries.get() + 1);
+			cancelAnimation(retryToken);
+			retryToken.set(
+				withDelay(
+					VIEWPORT_RETRY_DELAY_MS,
+					withTiming(retryToken.get() + 1, { duration: 0 }),
+				),
+			);
+		},
+	);
+};

package/src/shared/components/{create-boundary-component → boundary}/hooks/use-initial-source-measurement.ts

@@ -1,26 +1,18 @@
 import { useAnimatedReaction, useSharedValue } from "react-native-reanimated";
+import { useDescriptorsStore } from "../../../providers/screen/descriptors";
 import { pairs } from "../../../stores/bounds/internals/state";
 import type { MeasureBoundary } from "../types";
 import { getInitialSourceCaptureSignal } from "../utils/source-signals";
 
 export const useInitialSourceMeasurement = (params: {
 	enabled: boolean;
-	nextScreenKey?: string;
-	currentScreenKey?: string;
 	measureBoundary: MeasureBoundary;
 	linkId: string;
 	group?: string;
 	shouldAutoMeasure: boolean;
 }) => {
-	const {
-		enabled,
-		nextScreenKey,
-		measureBoundary,
-		linkId,
-		currentScreenKey,
-		group,
-		shouldAutoMeasure,
-	} = params;
+	const { enabled, measureBoundary, linkId, group, shouldAutoMeasure } = params;
+	const sourcePairKey = useDescriptorsStore((s) => s.derivations.sourcePairKey);
 	const lastSourceCaptureSignal = useSharedValue<string | null>(null);
 
 	useAnimatedReaction(
@@ -28,12 +20,11 @@ export const useInitialSourceMeasurement = (params: {
 			"worklet";
 			return getInitialSourceCaptureSignal({
 				enabled,
-				nextScreenKey,
-				currentScreenKey,
+				sourcePairKey,
 				linkId,
 				group,
 				shouldAutoMeasure,
-				linkState: group ? pairs.get() : undefined,
+				linkState: shouldAutoMeasure && sourcePairKey ? pairs.get() : undefined,
 			});
 		},
 		(captureSignal) => {