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

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

@@ -0,0 +1,97 @@
+import { useMemo } from "react";
+import type { View } from "react-native";
+import type { AnimatedRef, StyleProps } from "react-native-reanimated";
+import type { BoundTag } from "../../../stores/bounds/types";
+import { prepareStyleForBounds } from "../../../utils/bounds/helpers/styles/styles";
+import type { BoundaryConfigProps } from "../types";
+import { useBoundaryPresence } from "./lifecycles/use-boundary-presence";
+import { useInitialDestinationMeasurement } from "./lifecycles/use-initial-destination-measurement";
+import { useInitialSourceMeasurement } from "./lifecycles/use-initial-source-measurement";
+import { useRefreshBoundary } from "./lifecycles/use-refresh-boundary";
+import { useMeasurer } from "./use-measurer";
+
+interface UseBoundaryMeasurementParams {
+	boundTag: BoundTag;
+	/** Raw `enabled` prop — drives the measurer and the passive-source gate. */
+	enabled: boolean;
+	/** `enabled && hasConfiguredInterpolator` — gates presence + lifecycle. */
+	runtimeEnabled: boolean;
+	currentScreenKey: string;
+	/** Surface to measure: a nested target's placeholder, else the root. */
+	measuredRef: AnimatedRef<View>;
+	/** Root's own style; ignored when a nested target supplies its own. */
+	style?: unknown;
+	targetPreparedStyles?: StyleProps;
+	handoff: boolean;
+	escapeClipping: boolean;
+	config: BoundaryConfigProps;
+}
+
+/**
+ * Owns the full measurement lifecycle for a boundary: builds the measurer,
+ * registers presence, runs the initial source/destination + refresh reactions,
+ * and keeps the component itself away from the measurer.
+ */
+export const useBoundaryMeasurement = ({
+	boundTag,
+	enabled,
+	runtimeEnabled,
+	currentScreenKey,
+	measuredRef,
+	style,
+	targetPreparedStyles,
+	handoff,
+	escapeClipping,
+	config,
+}: UseBoundaryMeasurementParams) => {
+	const { anchor, scaleMode, target, method } = config;
+	const boundaryConfig = useMemo<BoundaryConfigProps>(
+		() => ({ anchor, scaleMode, target, method }),
+		[anchor, scaleMode, target, method],
+	);
+
+	const rootPreparedStyles = useMemo(
+		() => prepareStyleForBounds(style),
+		[style],
+	);
+	const preparedStyles = targetPreparedStyles ?? rootPreparedStyles;
+
+	const measureBoundary = useMeasurer({
+		enabled,
+		boundTag,
+		currentScreenKey,
+		preparedStyles,
+		measuredAnimatedRef: measuredRef,
+		handoff,
+		escapeClipping,
+	});
+
+	// Register/unregister this boundary in the presence map so source/destination
+	// matching can resolve across concrete screen keys.
+	useBoundaryPresence({
+		enabled: runtimeEnabled,
+		boundTag,
+		currentScreenKey,
+		boundaryConfig,
+		handoff,
+		escapeClipping,
+	});
+
+	useInitialSourceMeasurement({
+		enabled: runtimeEnabled,
+		measureBoundary,
+		boundTag,
+	});
+
+	useInitialDestinationMeasurement({
+		boundTag,
+		enabled: runtimeEnabled,
+		measureBoundary,
+	});
+
+	useRefreshBoundary({
+		enabled: runtimeEnabled,
+		boundTag,
+		measureBoundary,
+	});
+};

package/src/shared/components/boundary/hooks/use-measurer.ts

@@ -8,10 +8,9 @@ import {
 } from "react-native-reanimated";
 import { applyMeasuredBoundsWrites } from "../../../providers/helpers/measured-bounds-writes";
 import { useOriginContext } from "../../../providers/screen/origin.provider";
-import type { BoundsPortalAttachTarget } from "../../../stores/bounds/types";
+import type { BoundTag } from "../../../stores/bounds/types";
 import { ScrollStore } from "../../../stores/scroll.store";
 import { SystemStore } from "../../../stores/system.store";
-import { getActiveScrollHost } from "../portal/stores/host-registry.store";
 import type { MeasureBoundary } from "../types";
 import {
 	attachScrollSnapshotToMeasuredBounds,
@@ -22,24 +21,22 @@ import {
 
 interface UseMeasurerParams {
 	enabled: boolean;
-	entryTag: string;
-	linkId: string;
-	group?: string;
+	boundTag: BoundTag;
 	currentScreenKey: string;
 	preparedStyles: StyleProps;
 	measuredAnimatedRef: AnimatedRef<View>;
-	portalHost?: BoundsPortalAttachTarget;
+	handoff: boolean;
+	escapeClipping: boolean;
 }
 
 export const useMeasurer = ({
 	enabled,
-	entryTag,
-	linkId,
-	group,
+	boundTag,
 	currentScreenKey,
 	preparedStyles,
 	measuredAnimatedRef,
-	portalHost,
+	handoff,
+	escapeClipping,
 }: UseMeasurerParams): MeasureBoundary => {
 	const { width: viewportWidth, height: viewportHeight } =
 		useWindowDimensions();
@@ -78,7 +75,7 @@ export const useMeasurer = ({
 			 * lifecycle blocked until a valid retry lands.
 			 */
 			const shouldGuardDestinationViewport =
-				pendingLifecycleStartBlockCount.get() > 0 || !!group;
+				pendingLifecycleStartBlockCount.get() > 0 || !!boundTag.group;
 
 			const viewportAllowsDestinationWrite =
 				target.type !== "destination" ||
@@ -95,32 +92,27 @@ export const useMeasurer = ({
 				normalizedMeasured,
 				scrollMetadata.get(),
 			);
-			const sourceHost =
-				target.type === "source"
-					? (getActiveScrollHost(currentScreenKey) ?? undefined)
-					: undefined;
 
 			applyMeasuredBoundsWrites({
-				entryTag,
-				linkId,
-				group,
+				entryTag: boundTag.tag,
+				linkId: boundTag.linkKey,
+				group: boundTag.group,
 				currentScreenKey,
 				measured: measuredWithScroll,
 				preparedStyles,
 				linkWrite: target,
-				portalHost,
-				sourceHost,
+				handoff,
+				escapeClipping,
 			});
 		},
 		[
 			enabled,
-			entryTag,
-			linkId,
-			group,
+			boundTag,
 			currentScreenKey,
 			preparedStyles,
 			measuredAnimatedRef,
-			portalHost,
+			handoff,
+			escapeClipping,
 			viewportWidth,
 			viewportHeight,
 			scrollState,

package/src/shared/components/boundary/index.tsx

@@ -1,58 +1,84 @@
-import { Pressable, View } from "react-native";
+import { forwardRef } from "react";
+import {
+	Pressable,
+	type PressableProps,
+	View,
+	type ViewProps,
+} from "react-native";
 import { BoundaryTarget } from "./components/boundary-target";
 import { createBoundaryComponent } from "./create-boundary-component";
 import { Host } from "./portal";
+import type { BoundaryComponentProps } from "./types";
 
-export type {
-	BoundaryPortal,
-	BoundaryPortalAttachTarget,
-	BoundaryPortalOptions,
-} from "./types";
 export { createBoundaryComponent };
 
-const BoundaryView = createBoundaryComponent(View, {
-	shouldAutoMeasure: true,
-});
+type BoundaryPrimitiveProps = Omit<ViewProps, "id" | "style"> &
+	Omit<PressableProps, "id" | "style"> & {
+		style?: ViewProps["style"] | PressableProps["style"];
+	};
+
+const BoundaryPrimitive = forwardRef<View, BoundaryPrimitiveProps>(
+	(props, ref) => {
+		const Component = "onPress" in props ? Pressable : View;
+
+		return <Component {...(props as any)} ref={ref as any} />;
+	},
+);
+
+BoundaryPrimitive.displayName = "Transition.Boundary.Primitive";
+
+const BoundaryRoot = createBoundaryComponent(BoundaryPrimitive);
+const BoundaryView = createBoundaryComponent(View);
 const BoundaryTrigger = createBoundaryComponent(Pressable);
+BoundaryRoot.displayName = "Transition.Boundary";
 BoundaryView.displayName = "Transition.Boundary.View";
 BoundaryTrigger.displayName = "Transition.Boundary.Trigger";
 BoundaryTarget.displayName = "Transition.Boundary.Target";
 Host.displayName = "Transition.Boundary.Host";
 
+type BoundaryRootComponent = typeof BoundaryRoot;
+
 /**
- * Shared-boundary components.
+ * Shared-boundary component with static helpers.
  *
  * How measurement works:
- * 1. Source screen captures bounds for a tag.
- * 2. Destination screen captures bounds for the same tag.
- * 3. The link is updated as layout changes (group-active + scroll-settled paths).
+ * 1. Destination screen captures bounds for a tag.
+ * 2. Source screen captures bounds for the same concrete pair.
+ * 3. The link is updated as layout changes.
  *
- * Trigger behavior:
- * - When a boundary has `onPress` (typically `Boundary.Trigger`), source
- *   measurement runs before the user callback. This gives navigation transitions
- *   fresh source geometry on the first frame.
+ * Runtime primitive:
+ * - With an `onPress` handler, the root renders as a Pressable.
+ * - Without an `onPress` handler, the root renders as a View.
  *
  * Use:
- * - `Boundary.View` for passive/shared elements.
- * - `Boundary.Trigger` for tappable elements that start navigation.
- * - `Boundary.Target` to measure a nested descendant instead of the owner.
+ * - `Boundary` for passive and pressable shared elements.
+ * - `Boundary.Target` to measure a nested descendant instead of the root.
  * - `Boundary.Host` to make nested portal placement explicit.
  */
-export const Boundary = {
+export interface BoundaryComponent extends BoundaryRootComponent {
 	/**
-	 * Passive boundary wrapper (no built-in press semantics).
+	 * Optional nested measurement override inside a boundary root.
 	 */
-	View: BoundaryView,
+	Target: typeof BoundaryTarget;
 	/**
-	 * Pressable boundary wrapper with press-priority source capture.
+	 * Explicit portal host for scrollable or otherwise clipped coordinate spaces.
 	 */
-	Trigger: BoundaryTrigger,
+	Host: typeof Host;
 	/**
-	 * Optional nested measurement override inside a boundary owner.
+	 * @deprecated Use `Transition.Boundary` without `onPress`.
 	 */
-	Target: BoundaryTarget,
+	View: typeof BoundaryView;
 	/**
-	 * Explicit portal host for scrollable or otherwise clipped coordinate spaces.
+	 * @deprecated Use `Transition.Boundary` with `onPress`.
 	 */
-	Host: Host,
-};
+	Trigger: typeof BoundaryTrigger;
+}
+
+export type BoundaryProps = BoundaryComponentProps<BoundaryPrimitiveProps>;
+
+export const Boundary = Object.assign(BoundaryRoot, {
+	Target: BoundaryTarget,
+	Host,
+	View: BoundaryView,
+	Trigger: BoundaryTrigger,
+}) as BoundaryComponent;

package/src/shared/components/boundary/portal/components/boundary-local-portal-host.tsx

@@ -0,0 +1,66 @@
+import { memo, useCallback, useLayoutEffect } from "react";
+import { StyleSheet, View } from "react-native";
+import Animated from "react-native-reanimated";
+import { SystemStore } from "../../../../stores/system.store";
+import { NativePortalHost } from "../teleport";
+import { createBoundaryLocalPortalHostName } from "../utils/naming";
+
+const AnimatedPortalHost = NativePortalHost
+	? Animated.createAnimatedComponent(NativePortalHost)
+	: null;
+
+type BoundaryLocalPortalHostProps = {
+	boundaryId: string;
+	enabled: boolean;
+	screenKey: string;
+};
+
+export const BoundaryLocalPortalHost = memo(function BoundaryLocalPortalHost({
+	boundaryId,
+	enabled,
+	screenKey,
+}: BoundaryLocalPortalHostProps) {
+	const { drainLifecycleStartBlocks } = SystemStore.getBag(screenKey).actions;
+	const handleLayout = useCallback(() => {
+		drainLifecycleStartBlocks();
+	}, [drainLifecycleStartBlocks]);
+
+	useLayoutEffect(() => {
+		if (!enabled || !AnimatedPortalHost) {
+			return;
+		}
+
+		drainLifecycleStartBlocks();
+	}, [enabled, drainLifecycleStartBlocks]);
+
+	if (!enabled || !AnimatedPortalHost) {
+		return null;
+	}
+
+	const portalHostName = createBoundaryLocalPortalHostName(
+		screenKey,
+		boundaryId,
+	);
+
+	return (
+		<View
+			pointerEvents="none"
+			style={styles.hostWrapper}
+			onLayout={handleLayout}
+			collapsable={false}
+		>
+			<AnimatedPortalHost name={portalHostName} style={styles.host} />
+		</View>
+	);
+});
+
+const styles = StyleSheet.create({
+	host: {
+		...StyleSheet.absoluteFillObject,
+		overflow: "visible",
+	},
+	hostWrapper: {
+		...StyleSheet.absoluteFillObject,
+		overflow: "visible",
+	},
+});

package/src/shared/components/boundary/portal/components/host.tsx

@@ -1,4 +1,4 @@
-import { memo, useLayoutEffect, useRef } from "react";
+import { memo, useCallback, useLayoutEffect, useRef } from "react";
 import {
 	type StyleProp,
 	StyleSheet,
@@ -8,6 +8,7 @@ import {
 } from "react-native";
 import Animated from "react-native-reanimated";
 import { useDescriptorsStore } from "../../../../providers/screen/descriptors";
+import { SystemStore } from "../../../../stores/system.store";
 import { useHostMeasurement } from "../hooks/use-host-measurement";
 import { registerHost, unregisterHost } from "../stores/host-registry.store";
 import { useActivePortalBoundaryHosts } from "../stores/portal-boundary-host.store";
@@ -25,6 +26,7 @@ type HostImplProps = PublicHostProps & {
 
 function HostImpl({ fallback = false, style }: HostImplProps) {
 	const screenKey = useDescriptorsStore((s) => s.derivations.currentScreenKey);
+	const { drainLifecycleStartBlocks } = SystemStore.getBag(screenKey).actions;
 	const generatedHostKeyRef = useRef<string | null>(null);
 
 	if (generatedHostKeyRef.current === null) {
@@ -57,15 +59,28 @@ function HostImpl({ fallback = false, style }: HostImplProps) {
 		};
 	}, [capturesScroll, fallback, hostKey, screenKey]);
 
+	const handleUnblocking = useCallback(() => {
+		// Screen-level escape keeps the open transition gated until portal hosts
+		// have committed layout. A screen may render more than one portal boundary
+		// host for the same lifecycle request, so the final host layout drains the
+		// outstanding start blocks for this screen.
+		drainLifecycleStartBlocks();
+	}, [drainLifecycleStartBlocks]);
+
 	const boundaryHosts = measurement.canRenderHosts
-		? activeBoundaryHosts.map((host) => (
+		? activeBoundaryHosts.map((host, idx, list) => (
 				<View
-					key={host.boundaryId}
-					pointerEvents="box-none"
+					key={host.portalHostName}
+					pointerEvents="none"
 					style={[
 						styles.boundaryHostViewport,
 						{ width: viewportWidth, height: viewportHeight },
 					]}
+					onLayout={() => {
+						if (list.length - 1 === idx) {
+							handleUnblocking();
+						}
+					}}
 				>
 					<PortalBoundaryHost host={host} style={StyleSheet.absoluteFill} />
 				</View>
@@ -75,7 +90,7 @@ function HostImpl({ fallback = false, style }: HostImplProps) {
 	return (
 		<Animated.View
 			ref={measurement.hostRef}
-			pointerEvents="box-none"
+			pointerEvents="none"
 			style={[
 				styles.host,
 				{ width: viewportWidth, height: viewportHeight },

package/src/shared/components/boundary/portal/components/portal-boundary-host.tsx

@@ -1,19 +1,14 @@
 import { memo } from "react";
-import type { StyleProp, ViewStyle } from "react-native";
+import { type StyleProp, StyleSheet, type ViewStyle } from "react-native";
 import Animated, { useAnimatedStyle } from "react-native-reanimated";
 import { NO_STYLES } from "../../../../constants";
-import { AnimationStore } from "../../../../stores/animation.store";
-import { getSourceScreenKeyFromPairKey } from "../../../../stores/bounds/helpers/link-pairs.helpers";
+import { composeSlotStyleWithLocalTransform } from "../../../../providers/screen/styles/helpers/compose-slot-style";
 import { getLink } from "../../../../stores/bounds/internals/links";
-import { GestureStore } from "../../../../stores/gesture.store";
-import { ScrollStore } from "../../../../stores/scroll.store";
+import type { ScrollMeasuredDimensions } from "../../utils/measured-bounds";
 import type { ActivePortalBoundaryHost } from "../stores/portal-boundary-host.store";
 import { NativePortalHost } from "../teleport";
-import { createPortalBoundaryHostName } from "../utils/naming";
-import {
-	type PortalOffsetPlacement,
-	resolvePortalOffsetStyle,
-} from "../utils/offset-style";
+import { hasLocalSlot } from "../utils/has-local-slot";
+import { resolvePortalOffsetStyle } from "../utils/offset-style";
 
 const AnimatedPortalBoundaryHost = NativePortalHost
 	? Animated.createAnimatedComponent(NativePortalHost)
@@ -28,21 +23,6 @@ export const PortalBoundaryHost = memo(function PortalBoundaryHost({
 	host,
 	style,
 }: PortalBoundaryHostProps) {
-	const hostName = createPortalBoundaryHostName(host.hostKey, host.boundaryId);
-	const hostClosing = AnimationStore.getValue(host.screenKey, "closing");
-	const hostProgress = AnimationStore.getValue(
-		host.screenKey,
-		"transitionProgress",
-	);
-	const hostGestureDismissing = GestureStore.getValue(
-		host.screenKey,
-		"dismissing",
-	);
-	const hostScrollMetadata = ScrollStore.getValue(host.screenKey, "metadata");
-	const sourceScrollMetadata = ScrollStore.getValue(
-		getSourceScreenKeyFromPairKey(host.pairKey),
-		"metadata",
-	);
 	const hostStyle = useAnimatedStyle(() => {
 		"worklet";
 		// Strict per-member lookup — a fallback member's source rect would
@@ -52,38 +32,56 @@ export const PortalBoundaryHost = memo(function PortalBoundaryHost({
 			return NO_STYLES;
 		}
 
-		// Make the coordinate case explicit before resolving the host offset.
-		// The resolver owns the math; this component decides which screen/scroll
-		// relationship the active portal is in.
+		const sourceBounds = link.source.bounds as ScrollMeasuredDimensions;
 		const isCrossScreenPortal = link.source.screenKey !== host.screenKey;
-		const isHostClosing =
-			hostClosing.get() === 1 || hostGestureDismissing.get() === 1;
-		const placement: PortalOffsetPlacement = !isCrossScreenPortal
-			? "same-screen"
-			: isHostClosing
-				? "cross-screen-close"
-				: "cross-screen-open";
-
-		// A source that originated inside its own scroll host moves with that
-		// ScrollView while this portal stays attached over here. Shifting the
-		// source rect by the clamped source scroll travel keeps the return
-		// landing point on the live placeholder, so the close detach is seamless.
-		const trackSourceScroll =
-			isCrossScreenPortal && link.source.sourceHost?.capturesScroll === true;
 
 		return resolvePortalOffsetStyle({
-			bounds: link.source.bounds,
-			hostCurrentScroll:
-				placement === "cross-screen-close" ? hostScrollMetadata.get() : null,
+			bounds: sourceBounds,
 			hostKey: host.hostKey,
-			placement,
-			sourceCurrentScroll: trackSourceScroll
-				? sourceScrollMetadata.get()
-				: null,
-			hostProgress: hostProgress.get(),
-			trackSourceScroll,
+			placement: isCrossScreenPortal ? "cross-screen" : "same-screen",
 		});
 	});
+	const contentFrameStyle = useAnimatedStyle(() => {
+		"worklet";
+		const link = getLink(host.pairKey, host.boundaryId);
+		if (!link?.source || !link.destination) {
+			return NO_STYLES;
+		}
+
+		const sourceBounds = link.source.bounds as ScrollMeasuredDimensions;
+
+		return {
+			height: sourceBounds.height,
+			width: sourceBounds.width,
+		};
+	});
+	const slotStyle = useAnimatedStyle(() => {
+		"worklet";
+		// `slotsMap` is the resolved map: it may contain real interpolator output,
+		// inherited styles, or resolver-created reset patches for slots that just
+		// disappeared. Normal components need those reset patches so stale styles
+		// clear correctly.
+		//
+		// A screen-level portal host is different. It is only the temporary visual
+		// receiver for teleported content, not the original component that needs a
+		// cleanup frame. If the current local interpolator layers did not emit this
+		// boundary id, any resolved style here is cleanup/stale residue and should
+		// not be drawn by the host.
+		if (
+			host.escapeClipping &&
+			!hasLocalSlot(host.localStylesMaps.get(), host.boundaryId)
+		) {
+			return NO_STYLES;
+		}
+
+		const slot = host.slotsMap.get()[host.boundaryId];
+
+		return composeSlotStyleWithLocalTransform(
+			slot?.style ?? NO_STYLES,
+			undefined,
+			slot?.boundsLocalTransform,
+		);
+	});
 
 	// Without `react-native-teleport` no portal ever mounts a boundary host, so
 	// this never renders — the guard just narrows the nullable animated host.
@@ -92,6 +90,23 @@ export const PortalBoundaryHost = memo(function PortalBoundaryHost({
 	}
 
 	return (
-		<AnimatedPortalBoundaryHost name={hostName} style={[style, hostStyle]} />
+		<Animated.View
+			pointerEvents="none"
+			style={[style, hostStyle]}
+			collapsable={false}
+		>
+			<AnimatedPortalBoundaryHost
+				name={host.portalHostName}
+				style={[styles.content, contentFrameStyle, slotStyle]}
+			/>
+		</Animated.View>
 	);
 });
+
+const styles = StyleSheet.create({
+	content: {
+		left: 0,
+		position: "absolute",
+		top: 0,
+	},
+});