react-native-screen-transitions 3.9.0-alpha.2 → 3.9.0-beta.0

package/src/shared/stores/bounds/internals/links.ts

@@ -1,26 +1,23 @@
 import type { MeasuredDimensions, StyleProps } from "react-native-reanimated";
 import {
 	createGroupTag,
-	createPendingPairKey,
 	ensurePairGroups,
 	ensurePairLinks,
+	ensurePairSourceRequests,
 	getGroupKeyFromTag,
 	getLinkKeyFromTag,
 	getActiveGroupId as getPairActiveGroupId,
 	getDestination as getPairDestination,
 	getLink as getPairLink,
 	getSource as getPairSource,
-	getSourceScreenKeyFromPairKey,
-	removePairLink,
 } from "../helpers/link-pairs.helpers";
 import type {
-	BoundsPortalAttachTarget,
+	BoundaryRuntimeFlags,
 	GroupKey,
 	LinkKey,
 	LinkPairsState,
 	ScreenKey,
 	ScreenPairKey,
-	SourceHostRef,
 	SourceTagLinkSide,
 	TagID,
 	TagLink,
@@ -36,16 +33,151 @@ const syncLinkStatus = (link: TagLink) => {
 		: "source-incomplete";
 };
 
+type SharedValueLike = {
+	_isReanimatedSharedValue: true;
+	get?: () => unknown;
+	value?: unknown;
+};
+
+const isSharedValueLike = (value: unknown): value is SharedValueLike => {
+	"worklet";
+	return (
+		(value as Partial<SharedValueLike> | null)?._isReanimatedSharedValue ===
+		true
+	);
+};
+
+const snapshotSharedValue = (value: SharedValueLike): unknown => {
+	"worklet";
+	return value.value;
+};
+
+const snapshotTransformArrayValue = (
+	value: unknown[],
+): unknown[] | undefined => {
+	"worklet";
+	const snapshot: unknown[] = [];
+
+	for (let index = 0; index < value.length; index++) {
+		const snapshotValue = snapshotTransformEntryValue(value[index]);
+		if (snapshotValue !== undefined) {
+			snapshot.push(snapshotValue);
+		}
+	}
+
+	return snapshot;
+};
+
+const snapshotTransformEntryValue = (value: unknown): unknown => {
+	"worklet";
+	if (isSharedValueLike(value)) {
+		return snapshotSharedValue(value);
+	}
+
+	if (Array.isArray(value)) {
+		return snapshotTransformArrayValue(value);
+	}
+
+	if (typeof value === "function") {
+		return undefined;
+	}
+
+	return value === null || typeof value !== "object" ? value : undefined;
+};
+
+const snapshotTransformItem = (value: unknown): unknown => {
+	"worklet";
+	if (!value || typeof value !== "object" || Array.isArray(value)) {
+		return snapshotTransformEntryValue(value);
+	}
+
+	const snapshot: Record<string, unknown> = {};
+	const source = value as Record<string, unknown>;
+	let hasValue = false;
+
+	for (const key in source) {
+		const snapshotValue = snapshotTransformEntryValue(source[key]);
+		if (snapshotValue !== undefined) {
+			snapshot[key] = snapshotValue;
+			hasValue = true;
+		}
+	}
+
+	return hasValue ? snapshot : undefined;
+};
+
+const snapshotTransform = (value: unknown): unknown => {
+	"worklet";
+	if (!Array.isArray(value)) {
+		return undefined;
+	}
+
+	const snapshot: unknown[] = [];
+
+	for (let index = 0; index < value.length; index++) {
+		const snapshotValue = snapshotTransformItem(value[index]);
+		if (snapshotValue !== undefined) {
+			snapshot.push(snapshotValue);
+		}
+	}
+
+	return snapshot;
+};
+
+/**
+ * Link styles are measurement metadata, not a general style serializer.
+ * Snapshot only the fields bounds currently consume: primitives, top-level
+ * shared values, and transform entries. Object-valued non-transform styles are
+ * intentionally omitted to avoid retaining opaque/native style objects.
+ */
+const snapshotStyles = (styles: StyleProps): StyleProps => {
+	"worklet";
+	if (!styles || typeof styles !== "object" || Array.isArray(styles)) {
+		return {};
+	}
+
+	const snapshot: Record<string, unknown> = {};
+	const source = styles as Record<string, unknown>;
+
+	for (const key in source) {
+		const value = source[key];
+
+		if (key === "transform") {
+			const transform = snapshotTransform(value);
+
+			if (transform !== undefined) {
+				snapshot.transform = transform;
+			}
+
+			continue;
+		}
+
+		if (isSharedValueLike(value)) {
+			snapshot[key] = snapshotSharedValue(value);
+			continue;
+		}
+
+		if (value === null || typeof value !== "object") {
+			snapshot[key] = value;
+		}
+	}
+
+	return snapshot as StyleProps;
+};
+
 const createLinkSide = (
 	screenKey: ScreenKey,
 	bounds: MeasuredDimensions,
 	styles: StyleProps,
+	runtimeFlags: BoundaryRuntimeFlags = {},
 ) => {
 	"worklet";
 	return {
 		screenKey,
 		bounds,
-		styles,
+		styles: snapshotStyles(styles),
+		handoff: runtimeFlags.handoff ? true : undefined,
+		escapeClipping: runtimeFlags.escapeClipping ? true : undefined,
 	};
 };
 
@@ -100,7 +232,9 @@ const writeDestination = (
 
 	link.group = group ?? link.group;
 	link.destination = destination;
-	link.initialDestination ??= destination;
+	if (!link.initialDestination) {
+		link.initialDestination = destination;
+	}
 	syncLinkStatus(link);
 
 	writePairLink(state, pairKey, linkKey, link);
@@ -110,41 +244,6 @@ const writeDestination = (
 	}
 };
 
-const promotePendingSource = (
-	state: LinkPairsState,
-	pairKey: ScreenPairKey,
-	linkKey: LinkKey,
-) => {
-	"worklet";
-	if (getPairLink(state, pairKey, linkKey)) return;
-
-	const sourceScreenKey = getSourceScreenKeyFromPairKey(pairKey);
-	const pendingPairKey = createPendingPairKey(sourceScreenKey);
-	if (pendingPairKey === pairKey) return;
-
-	const pendingLink = getPairLink(state, pendingPairKey, linkKey);
-	if (!pendingLink) return;
-
-	writePairLink(state, pairKey, linkKey, pendingLink);
-
-	if (pendingLink.group) {
-		const pendingGroupState =
-			state[pendingPairKey]?.groups?.[pendingLink.group];
-
-		if (pendingGroupState) {
-			writeGroup(
-				state,
-				pairKey,
-				pendingLink.group,
-				pendingGroupState.activeId,
-				pendingGroupState.initialId,
-			);
-		}
-	}
-
-	removePairLink(state, pendingPairKey, linkKey);
-};
-
 function setSource(
 	pairKey: ScreenPairKey,
 	tag: TagID,
@@ -152,8 +251,7 @@ function setSource(
 	bounds: MeasuredDimensions,
 	styles: StyleProps = {},
 	group?: GroupKey,
-	portalAttachTarget?: BoundsPortalAttachTarget,
-	sourceHost?: SourceHostRef,
+	runtimeFlags: BoundaryRuntimeFlags = {},
 ) {
 	"worklet";
 	pairs.modify(<T extends LinkPairsState>(state: T): T => {
@@ -164,13 +262,8 @@ function setSource(
 
 		const existingLink = pairLinks[linkKey];
 
-		// Refresh paths may re-measure the source without portal context;
-		// keep the previously recorded host in that case.
 		const source: SourceTagLinkSide = {
-			...createLinkSide(screenKey, bounds, styles),
-			portalAttachTarget:
-				portalAttachTarget ?? existingLink?.source?.portalAttachTarget,
-			sourceHost: sourceHost ?? existingLink?.source?.sourceHost,
+			...createLinkSide(screenKey, bounds, styles, runtimeFlags),
 		};
 		const link =
 			existingLink ??
@@ -184,15 +277,13 @@ function setSource(
 
 		link.group = group ?? link.group;
 		link.source = source;
-		link.initialSource ??= source;
+		if (!link.initialSource) {
+			link.initialSource = source;
+		}
 		syncLinkStatus(link);
 
 		pairLinks[linkKey] = link;
-
-		const pendingPairKey = createPendingPairKey(screenKey);
-		if (pendingPairKey !== pairKey) {
-			removePairLink(state, pendingPairKey, linkKey);
-		}
+		delete state[pairKey]?.sourceRequests?.[linkKey];
 
 		return state;
 	});
@@ -210,7 +301,6 @@ function setDestination(
 	pairs.modify(<T extends LinkPairsState>(state: T): T => {
 		"worklet";
 		const linkKey = getLinkKeyFromTag(tag);
-		promotePendingSource(state, pairKey, linkKey);
 		writeDestination(state, pairKey, linkKey, screenKey, bounds, styles, group);
 
 		return state;
@@ -226,6 +316,23 @@ function setActiveGroupId(pairKey: ScreenPairKey, group: GroupKey, tag: TagID) {
 	});
 }
 
+function requestSourceMeasure(pairKey: ScreenPairKey, tag: TagID) {
+	"worklet";
+	pairs.modify(<T extends LinkPairsState>(state: T): T => {
+		"worklet";
+		const linkKey = getLinkKeyFromTag(tag);
+		const link = getPairLink(state, pairKey, linkKey);
+
+		if (link?.source || state[pairKey]?.sourceRequests?.[linkKey]) {
+			return state;
+		}
+
+		ensurePairSourceRequests(state, pairKey)[linkKey] = true;
+
+		return state;
+	});
+}
+
 function getActiveGroupId(
 	pairKey: ScreenPairKey,
 	group: GroupKey,
@@ -246,20 +353,6 @@ const hasSourceLink = (
 	return !!link?.source;
 };
 
-const getPendingSourceLink = (
-	state: LinkPairsState,
-	pairKey: ScreenPairKey,
-	linkKey: LinkKey,
-): TagLink | null => {
-	"worklet";
-	const sourceScreenKey = getSourceScreenKeyFromPairKey(pairKey);
-	const pendingPairKey = createPendingPairKey(sourceScreenKey);
-
-	if (pendingPairKey === pairKey) return null;
-
-	return getPairLink(state, pendingPairKey, linkKey);
-};
-
 function getResolvedLink(
 	pairKey: ScreenPairKey,
 	tag: TagID,
@@ -268,17 +361,7 @@ function getResolvedLink(
 	const state = pairs.get();
 	const linkKey = getLinkKeyFromTag(tag);
 	const group = getGroupKeyFromTag(tag);
-	const requestedLink = getPairLink(state, pairKey, linkKey);
-
-	// Press-triggered zoom captures the source before navigation under a pending
-	// source<> pair. If the destination screen has no Boundary.View, nothing
-	// promotes that source into source<>destination, but zoom can still animate to
-	// its default top target from the pending source bounds.
-	const fallbackPendingLink = requestedLink
-		? null
-		: getPendingSourceLink(state, pairKey, linkKey);
-
-	const link = requestedLink ?? fallbackPendingLink;
+	const link = getPairLink(state, pairKey, linkKey);
 
 	// Group active ids can update before the new member has a full source/destination
 	// link. As soon as the requested member has source bounds, prefer it; only
@@ -292,9 +375,7 @@ function getResolvedLink(
 
 	const initialId = state[pairKey]?.groups?.[group]?.initialId;
 	if (initialId) {
-		const initialLink =
-			getPairLink(state, pairKey, initialId) ??
-			getPendingSourceLink(state, pairKey, initialId);
+		const initialLink = getPairLink(state, pairKey, initialId);
 
 		if (hasSourceLink(initialLink)) {
 			return {
@@ -332,6 +413,7 @@ export {
 	getLink,
 	getResolvedLink,
 	getSource,
+	requestSourceMeasure,
 	setActiveGroupId,
 	setDestination,
 	setSource,

package/src/shared/stores/bounds/internals/resolver.ts

@@ -39,8 +39,6 @@ function resolveTransitionPair(
 		destinationStyles: matchedLink?.destination?.styles ?? null,
 		sourceScreenKey: matchedLink?.source?.screenKey ?? null,
 		destinationScreenKey: matchedLink?.destination?.screenKey ?? null,
-		sourcePortalAttachTarget: matchedLink?.source?.portalAttachTarget,
-		sourceHost: matchedLink?.source?.sourceHost,
 	};
 }
 

package/src/shared/stores/bounds/types.ts

@@ -24,9 +24,13 @@ export interface BoundTag {
 	linkKey: LinkKey;
 	group?: GroupKey;
 }
-export type BoundsPortalAttachTarget = "current-screen" | "matched-screen";
 export type { ScreenKey } from "../../types/screen.types";
 
+export type BoundaryRuntimeFlags = {
+	handoff?: boolean;
+	escapeClipping?: boolean;
+};
+
 type BoundaryConfig = {
 	anchor?: BoundsAnchor;
 	scaleMode?: BoundsScaleMode;
@@ -38,7 +42,7 @@ export type Entry = {
 	bounds: MeasuredDimensions | null;
 	styles: StyleProps;
 	boundaryConfig?: BoundaryConfig;
-};
+} & BoundaryRuntimeFlags;
 
 export type MeasuredEntry = Entry & {
 	bounds: MeasuredDimensions;
@@ -48,6 +52,8 @@ export type EntryPatch = {
 	bounds?: MeasuredDimensions | null;
 	styles?: StyleProps | null;
 	boundaryConfig?: BoundaryConfig | null;
+	handoff?: boolean | null;
+	escapeClipping?: boolean | null;
 };
 
 export type ScreenIdentifier = {
@@ -60,24 +66,7 @@ export type BoundsLinkStatus =
 	| "complete";
 
 export type TagLinkSide = ScreenIdentifier & MeasuredEntry;
-
-/**
- * The source screen's active portal host at measure time. Recorded only when
- * that host captures scroll (a Transition.ScrollView scope) — matched-screen
- * placement uses it as a coordinate space to express the source rect in the
- * source ScrollView's live frame. The portal never attaches here.
- */
-export type SourceHostRef = {
-	hostKey: string;
-	capturesScroll: boolean;
-};
-
-export type SourceTagLinkSide = TagLinkSide & {
-	/** Where this boundary's portal content renders during the transition. */
-	portalAttachTarget?: BoundsPortalAttachTarget;
-	/** Scroll-scoped host the source originated from, if any. */
-	sourceHost?: SourceHostRef;
-};
+export type SourceTagLinkSide = TagLinkSide;
 
 type TagLinkBase = {
 	group?: GroupKey;
@@ -128,8 +117,6 @@ export type ResolvedTransitionPair = {
 	destinationStyles: StyleProps | null;
 	sourceScreenKey: ScreenKey | null;
 	destinationScreenKey: ScreenKey | null;
-	sourcePortalAttachTarget?: BoundsPortalAttachTarget;
-	sourceHost?: SourceHostRef;
 };
 
 export type LinkGroupState = {
@@ -140,6 +127,7 @@ export type LinkGroupState = {
 export type LinkPairState = {
 	links: Record<LinkKey, TagLink>;
 	groups: Record<GroupKey, LinkGroupState>;
+	sourceRequests?: Record<LinkKey, true>;
 };
 
 export type LinkPairsState = Record<ScreenPairKey, LinkPairState>;

package/src/shared/stores/system.store.ts

@@ -51,6 +51,7 @@ export interface SystemStoreActions {
 	clearLifecycleTransitionRequest(): void;
 	blockLifecycleStart(): void;
 	unblockLifecycleStart(): void;
+	drainLifecycleStartBlocks(): void;
 }
 
 export type SystemStoreMap = SystemStoreState & {
@@ -108,5 +109,10 @@ export const SystemStore = createStore<SystemStoreState, SystemStoreActions>({
 				Math.max(0, bag.pendingLifecycleStartBlockCount.get() - 1),
 			);
 		},
+
+		drainLifecycleStartBlocks() {
+			"worklet";
+			bag.pendingLifecycleStartBlockCount.set(0);
+		},
 	}),
 });

package/src/shared/types/animation.types.ts

@@ -1,5 +1,5 @@
 import type { TextStyle, ViewStyle } from "react-native";
-import type { StyleProps } from "react-native-reanimated";
+import type { StyleProps, TransformArrayItem } from "react-native-reanimated";
 import type { EdgeInsets } from "react-native-safe-area-context";
 import {
 	NAVIGATION_MASK_CONTAINER_STYLE_ID,
@@ -223,6 +223,12 @@ export interface ScreenInterpolationProps {
 	 */
 	progress: number;
 
+	/**
+	 * Combined transition progress of current and next screens, without live
+	 * gesture contribution.
+	 */
+	transitionProgress: number;
+
 	/**
 	 * Accumulated progress from the current screen's position onwards in the stack.
 	 * Unlike `progress` (0-2), this ranges from 0-N where N is the number of screens
@@ -346,6 +352,7 @@ export type TransitionInterpolatorOptions = Omit<
 export type NormalizedTransitionSlotStyle = {
 	style?: StyleProps;
 	props?: TransitionSlotProps;
+	boundsLocalTransform?: TransformArrayItem[];
 };
 
 /**

package/src/shared/types/index.ts

@@ -54,7 +54,12 @@ export type {
 	GestureTracking,
 	InactiveBehavior,
 	Layout,
+	ScreenBackdropComponent,
+	ScreenBackdropComponentProps,
+	ScreenContentComponent,
+	ScreenContentComponentProps,
 	ScreenKey,
+	ScreenLayerComponentProps,
 	ScreenTransitionConfig,
 	TransitionAwareProps,
 } from "./screen.types";

package/src/shared/types/screen.types.ts

@@ -1,3 +1,5 @@
+import type { ComponentType, ReactNode } from "react";
+import type { ViewProps } from "react-native";
 import type { AnimatedProps } from "react-native-reanimated";
 import type {
 	ScreenStyleInterpolator,
@@ -51,6 +53,71 @@ export type SnapPoint = number | "auto";
 
 export type BackdropBehavior = "block" | "passthrough" | "dismiss" | "collapse";
 
+/**
+ * Props passed to custom screen layer component renderers such as
+ * {@linkcode ScreenTransitionConfig.backdropComponent}.
+ */
+export type ScreenLayerComponentProps = {
+	/**
+	 * Animated styles for the target layer, including the library-owned base
+	 * layout style for that layer.
+	 */
+	styles: AnimatedProps<ViewProps>["style"];
+
+	/**
+	 * Animated props resolved from the matching `screenStyleInterpolator` slot.
+	 */
+	props: AnimatedProps<Record<string, unknown>>["animatedProps"];
+
+	/**
+	 * Pointer-event behavior resolved for the current layer state.
+	 */
+	pointerEvents: ViewProps["pointerEvents"];
+};
+
+/**
+ * Props passed to {@linkcode ScreenTransitionConfig.backdropComponent} when it
+ * is provided as a render-style component.
+ */
+export type ScreenBackdropComponentProps = ScreenLayerComponentProps;
+
+/**
+ * Props passed to {@linkcode ScreenTransitionConfig.contentComponent} when it
+ * is provided as a render-style component.
+ */
+export type ScreenContentComponentProps = ScreenLayerComponentProps & {
+	/**
+	 * The screen subtree rendered inside the content layer.
+	 */
+	children: ReactNode;
+};
+
+/**
+ * Custom renderer for the backdrop layer.
+ *
+ * Component types such as `BlurView` are still accepted for compatibility.
+ * Function components can also receive {@linkcode ScreenBackdropComponentProps}
+ * to render the animated styles and props manually.
+ *
+ * @see {@linkcode ScreenTransitionConfig.backdropComponent}
+ */
+export type ScreenBackdropComponent =
+	| ComponentType<any>
+	| ComponentType<ScreenBackdropComponentProps>;
+
+/**
+ * Custom renderer for the screen content layer.
+ *
+ * Component types such as a custom native view are accepted directly. Function
+ * components can also receive {@linkcode ScreenContentComponentProps} to render
+ * the animated styles, props, pointer-events, and children manually.
+ *
+ * @see {@linkcode ScreenTransitionConfig.contentComponent}
+ */
+export type ScreenContentComponent =
+	| ComponentType<any>
+	| ComponentType<ScreenContentComponentProps>;
+
 /**
  * Controls how an inactive screen is retained after it is no longer active.
  *
@@ -117,6 +184,8 @@ export type TransitionAwareProps<T extends object> = AnimatedProps<T> & {
 	 * <Transition.View sharedBoundTag="profile-avatar">
 	 *   <Avatar size="large" />
 	 * </Transition.View>
+	 *
+	 * @deprecated Use `Transition.Boundary` with `id` instead.
 	 */
 	sharedBoundTag?: string;
 
@@ -127,6 +196,8 @@ export type TransitionAwareProps<T extends object> = AnimatedProps<T> & {
 	 * Useful when layout can change while unfocused (for example, programmatic
 	 * ScrollView/FlatList scrolling triggered from another screen).
 	 *
+	 * @deprecated Legacy `sharedBoundTag` refresh option. The boundary
+	 * measurement pipeline refreshes layout through `Transition.Boundary`.
 	 * @default false
 	 */
 	remeasureOnFocus?: boolean;
@@ -209,6 +280,8 @@ export type ScreenTransitionConfig = {
 	/**
 	 * How much velocity affects snap point targeting. Lower values make snapping
 	 * feel more deliberate (iOS-like), higher values make it more responsive to flicks.
+	 *
+	 * @deprecated Use `gestureSnapVelocityImpact` instead.
 	 * @default 0.1
 	 */
 	snapVelocityImpact?: number;
@@ -400,13 +473,21 @@ export type ScreenTransitionConfig = {
 	/**
 	 * Custom component to render as the backdrop layer (between screens).
 	 *
-	 * The library wraps this component with `Animated.createAnimatedComponent` internally.
-	 * Animated styles and props are driven by the `backdrop` slot in the interpolator return value.
+	 * Direct component types are wrapped with `Animated.createAnimatedComponent`
+	 * internally. Function components can receive `{ styles, props, pointerEvents }`
+	 * and decide how to render the layer. Animated styles and props are driven by
+	 * the `backdrop` slot in the interpolator return value.
 	 *
 	 * `backdropBehavior` still controls the wrapping Pressable for dismiss/collapse handling.
 	 *
 	 * @example
-	 * backdropComponent: BlurView,
+	 * backdropComponent: ({ styles, props, pointerEvents }) => (
+	 *   <AnimatedBlurView
+	 *     style={styles}
+	 *     animatedProps={props}
+	 *     pointerEvents={pointerEvents}
+	 *   />
+	 * ),
 	 * screenStyleInterpolator: ({ progress }) => {
 	 *   "worklet";
 	 *   return {
@@ -419,7 +500,32 @@ export type ScreenTransitionConfig = {
 	 *
 	 * @default undefined
 	 */
-	backdropComponent?: React.ComponentType<any>;
+	backdropComponent?: ScreenBackdropComponent;
+
+	/**
+	 * Custom component to render as the screen's content layer.
+	 *
+	 * The component receives the `content` slot's animated styles and props. A
+	 * direct component type is wrapped with `Animated.createAnimatedComponent`;
+	 * a function component can receive `{ styles, props, pointerEvents, children }`
+	 * and decide how to render the layer.
+	 *
+	 * `contentComponent` replaces `surfaceComponent` for custom screen shells.
+	 *
+	 * @example
+	 * contentComponent: ({ styles, props, pointerEvents, children }) => (
+	 *   <AnimatedSquircleView
+	 *     style={styles}
+	 *     animatedProps={props}
+	 *     pointerEvents={pointerEvents}
+	 *   >
+	 *     {children}
+	 *   </AnimatedSquircleView>
+	 * )
+	 *
+	 * @default undefined
+	 */
+	contentComponent?: ScreenContentComponent;
 
 	/**
 	 * Custom component to render as the screen's surface layer.
@@ -443,6 +549,7 @@ export type ScreenTransitionConfig = {
 	 * }
 	 *
 	 * @default undefined
+	 * @deprecated Use `contentComponent` instead.
 	 */
 	surfaceComponent?: React.ComponentType<any>;
 };