react-native-screen-transitions 4.1.0-alpha.0 → 4.1.0-beta.1

package/src/components/boundary/hooks/lifecycles/use-refresh-boundary.ts

@@ -1,6 +1,6 @@
 import { useAnimatedReaction } from "react-native-reanimated";
-import { useDescriptorsStore } from "../../../../providers/screen/descriptors";
-import { AnimationStore } from "../../../../stores/animation.store";
+import { useBuilderStore } from "../../../../providers/screen/builder";
+import { useOptionalMotionStore } from "../../../../providers/screen/motion";
 import {
 	getPairKeyForDestination,
 	getPairKeyForSource,
@@ -22,31 +22,34 @@ export const useRefreshBoundary = ({
 	measureBoundary,
 }: UseRefreshBoundaryParams) => {
 	const { linkKey, group } = boundTag;
-	const currentScreenKey = useDescriptorsStore(
+	const currentScreenKey = useBuilderStore(
 		(s) => s.derivations.currentScreenKey,
 	);
-	const nextScreenKey = useDescriptorsStore((s) => s.derivations.nextScreenKey);
+	const nextScreenKey = useBuilderStore((s) => s.derivations.nextScreenKey);
 	// Source-side boundaries refresh from the next screen's lifecycle pulse.
 	// Destination-side boundaries have no next screen, so they refresh from self.
 	const refreshScreenKey = nextScreenKey ?? currentScreenKey;
-	const refreshWillAnimate = AnimationStore.getValue(
+	const willAnimate = useOptionalMotionStore(
 		refreshScreenKey,
-		"willAnimate",
+		(store) => store.state.willAnimate,
 	);
-	const refreshSettled = AnimationStore.getValue(
+	const progressSettled = useOptionalMotionStore(
 		refreshScreenKey,
-		"progressSettled",
+		(store) => store.state.progressSettled,
+	);
+	const closing = useOptionalMotionStore(
+		refreshScreenKey,
+		(store) => store.state.closing,
 	);
-	const refreshClosing = AnimationStore.getValue(refreshScreenKey, "closing");
 
 	useAnimatedReaction(
 		() => {
 			"worklet";
 
-			if (!enabled) return null;
+			if (!enabled || !willAnimate || !progressSettled || !closing) return null;
 
-			const shouldRefresh = !!refreshWillAnimate.get();
-			const settled = !!refreshSettled.get();
+			const shouldRefresh = !!willAnimate.get();
+			const settled = !!progressSettled.get();
 			// A group's active member can change while the transition is settled
 			// (for example, paging a destination gallery). Let that member publish
 			// fresh bounds even though there is no willAnimate lifecycle pulse yet.
@@ -67,7 +70,7 @@ export const useRefreshBoundary = ({
 				group,
 				shouldRefresh,
 				settled,
-				closing: !!refreshClosing.get(),
+				closing: !!closing.get(),
 				linkState: pairs.get(),
 			});
 		},

package/src/components/boundary/hooks/use-boundary-presentation.ts

@@ -0,0 +1,82 @@
+import { useMemo } from "react";
+import { useDerivedValue, useSharedValue } from "react-native-reanimated";
+import { NO_PROPS, NO_STYLES } from "../../../constants";
+import { useBuilderStore } from "../../../providers/screen/builder";
+import { useScreenRelationships } from "../../../providers/screen/builder/topology";
+import {
+	useOptionalOrchestratorStore,
+	useOrchestratorStore,
+} from "../../../providers/screen/orchestrator";
+import {
+	areResettableStatesBySlotEqual,
+	type ResettableStyleStatesBySlot,
+	resolveSlotStyles,
+} from "../../../providers/screen/orchestrator/styles/helpers/resolve-slot-styles";
+import { useOptionalBlankStackStore } from "../../../providers/stack/blank-stack.provider";
+import {
+	boundaryRegistry,
+	pairs,
+} from "../../../stores/bounds/internals/state";
+import {
+	type BoundaryPresentationState,
+	resolveBoundaryHandoff,
+	resolveBoundaryPresentation,
+} from "../helpers/presentation";
+
+// Screens are discovered through existing providers. React only wires subscriptions;
+// their live UI values decide ownership, including retained closing screens.
+export function useBoundaryPresentation(boundaryId: string, enabled = true) {
+	const screenKey = useBuilderStore((s) => s.derivations.currentScreenKey);
+	const scenes = useOptionalBlankStackStore((s) => s?.scenes);
+	const keys = useMemo(
+		() => (enabled ? (scenes?.map((s) => s.route.key) ?? [screenKey]) : []),
+		[scenes, screenKey, enabled],
+	);
+	const pairPresentations = useOptionalOrchestratorStore(
+		keys,
+		(s) => s.pairPresentation,
+	);
+	const localSlots = useOrchestratorStore((s) => s.slotsMap);
+	const { parentScreenKey } = useScreenRelationships();
+	const ancestorSlots = useOptionalOrchestratorStore(
+		parentScreenKey,
+		(s) => s.slotsMap,
+	);
+	const previous = useSharedValue<ResettableStyleStatesBySlot>(NO_PROPS);
+
+	const presentation = useDerivedValue(() => {
+		const state: BoundaryPresentationState = {
+			presentations: pairPresentations,
+			pairs: pairs.get(),
+			entries: boundaryRegistry.get(),
+		};
+		const owner = resolveBoundaryPresentation(screenKey, boundaryId, state);
+		const receiver = resolveBoundaryHandoff(screenKey, boundaryId, state);
+		const ownedSlot = owner?.ready
+			? (owner.sourceKey === screenKey ? owner.source : owner.destination)[
+					boundaryId
+				]
+			: undefined;
+
+		const fallback = localSlots.get()[boundaryId];
+		const { resolvedStylesMap, nextPreviousStyleStatesBySlot } =
+			resolveSlotStyles({
+				localStylesMaps: [{ [boundaryId]: ownedSlot ?? fallback ?? {} }],
+				ancestorStylesMap: ownedSlot
+					? (ancestorSlots?.get() ?? NO_STYLES)
+					: NO_STYLES,
+				previousStyleStatesBySlot: previous.get(),
+			});
+		if (
+			!areResettableStatesBySlotEqual(
+				previous.get(),
+				nextPreviousStyleStatesBySlot,
+			)
+		) {
+			previous.set(nextPreviousStyleStatesBySlot);
+		}
+		return { owner, receiver, slots: resolvedStylesMap };
+	});
+	const slotsMap = useDerivedValue(() => presentation.get().slots);
+	return { presentation, slotsMap };
+}

package/src/components/boundary/hooks/use-composed-boundary-style.ts

@@ -0,0 +1,58 @@
+import { useMemo } from "react";
+import {
+	type SharedValue,
+	type StyleProps,
+	useAnimatedStyle,
+} from "react-native-reanimated";
+import { NO_STYLES } from "../../../constants";
+import {
+	composeSlotStyleWithLocalTransform,
+	getLocalTransformForSlotComposition,
+} from "../../../providers/screen/orchestrator/styles/helpers/compose-slot-style";
+import type { NormalizedTransitionInterpolatedStyle } from "../../../types/animation.types";
+
+export function useComposedBoundaryStyle(
+	slots: SharedValue<NormalizedTransitionInterpolatedStyle> | undefined,
+	id: string | undefined,
+	style?: unknown,
+	kind: "full" | "stacking" | "layout" = "full",
+) {
+	const local = useMemo(
+		() => getLocalTransformForSlotComposition(style),
+		[style],
+	);
+
+	return useAnimatedStyle(() => {
+		const slot = id ? slots?.get()[id] : undefined;
+		const value: StyleProps = slot?.style ?? NO_STYLES;
+		if (kind === "stacking")
+			return { zIndex: value.zIndex ?? 0, elevation: value.elevation ?? 0 };
+
+		if (kind === "layout") {
+			const {
+				width,
+				height,
+				minWidth,
+				minHeight,
+				maxWidth,
+				maxHeight,
+				aspectRatio,
+			} = value;
+
+			return {
+				width,
+				height,
+				minWidth,
+				minHeight,
+				maxWidth,
+				maxHeight,
+				aspectRatio,
+			};
+		}
+		return composeSlotStyleWithLocalTransform(
+			value,
+			local,
+			slot?.boundsLocalTransform,
+		);
+	});
+}

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

@@ -2,11 +2,14 @@ import { useCallback } from "react";
 import type { View } from "react-native";
 import { useWindowDimensions } from "react-native";
 import type { AnimatedRef, StyleProps } from "react-native-reanimated";
-import { applyMeasuredBoundsWrites } from "../../../providers/helpers/measured-bounds-writes";
-import { useScreenSlotStore } from "../../../providers/screen/styles";
+import { useMotionStore } from "../../../providers/screen/motion";
+import { setEntry } from "../../../stores/bounds/internals/entries";
+import {
+	setDestination,
+	setSource,
+} from "../../../stores/bounds/internals/links";
 import type { BoundTag } from "../../../stores/bounds/types";
 import { ScrollStore } from "../../../stores/scroll.store";
-import { SystemStore } from "../../../stores/system.store";
 import { getVisibilityBlockOffset } from "../../../utils/visibility-block-offset";
 import type { BoundaryLocalMeasurementValue, MeasureBoundary } from "../types";
 import {
@@ -42,13 +45,10 @@ export const useMeasurer = ({
 
 	const scrollState = ScrollStore.getValue(currentScreenKey, "coordination");
 	const scrollMetadata = ScrollStore.getValue(currentScreenKey, "metadata");
-	const pendingLifecycleStartBlockCount = SystemStore.getValue(
-		currentScreenKey,
-		"pendingLifecycleStartBlockCount",
-	);
-	const visibilityBlocked = useScreenSlotStore(
-		(store) => store.visibilityBlocked,
+	const pendingLifecycleStartBlockCount = useMotionStore(
+		(store) => store.state.pendingLifecycleStartBlockCount,
 	);
+	const isScreenReady = useMotionStore((store) => store.isScreenReady);
 
 	return useCallback(
 		(target) => {
@@ -64,7 +64,7 @@ export const useMeasurer = ({
 
 			const correctedMeasured = correctMeasuredBoundsForVisibilityGate({
 				measured,
-				visibilityBlocked: visibilityBlocked.get(),
+				isScreenReady: isScreenReady.get(),
 				visibilityBlockOffset: getVisibilityBlockOffset(viewportHeight),
 				viewportWidth,
 				viewportHeight,
@@ -103,17 +103,32 @@ export const useMeasurer = ({
 				scrollMetadata.get(),
 			);
 
-			applyMeasuredBoundsWrites({
-				entryTag: boundTag.tag,
-				linkId: boundTag.linkKey,
-				group: boundTag.group,
-				currentScreenKey,
-				measured: measuredWithScroll,
-				preparedStyles,
-				linkWrite: target,
-				handoff,
-				escapeClipping,
-			});
+			// Refresh the public bounds entry on every accepted measurement.
+			setEntry(boundTag.tag, currentScreenKey, { bounds: measuredWithScroll });
+
+			if (target.type === "source") {
+				setSource(
+					target.pairKey,
+					boundTag.linkKey,
+					currentScreenKey,
+					measuredWithScroll,
+					preparedStyles,
+					boundTag.group,
+					{ handoff, escapeClipping },
+				);
+			}
+
+			if (target.type === "destination") {
+				setDestination(
+					target.pairKey,
+					boundTag.linkKey,
+					currentScreenKey,
+					measuredWithScroll,
+					preparedStyles,
+					boundTag.group,
+					{ handoff },
+				);
+			}
 		},
 		[
 			enabled,
@@ -129,7 +144,7 @@ export const useMeasurer = ({
 			scrollState,
 			scrollMetadata,
 			pendingLifecycleStartBlockCount,
-			visibilityBlocked,
+			isScreenReady,
 		],
 	);
 };

package/src/components/boundary/index.tsx

@@ -1,9 +1,13 @@
-import { forwardRef } from "react";
+import {
+	type ComponentProps,
+	forwardRef,
+	type NamedExoticComponent,
+} from "react";
 import { View, type ViewProps } from "react-native";
 import { Pressable, type PressableProps } from "react-native-gesture-handler";
 import { BoundaryTarget } from "./components/boundary-target";
 import { createBoundaryComponent } from "./create-boundary-component";
-import { Host } from "./portal";
+import { PortalOverlay } from "./portal/components/portal-overlay";
 import type { BoundaryComponentProps } from "./types";
 
 export { createBoundaryComponent };
@@ -26,7 +30,6 @@ BoundaryPrimitive.displayName = "Transition.Boundary.Primitive";
 const BoundaryRoot = createBoundaryComponent(BoundaryPrimitive);
 BoundaryRoot.displayName = "Transition.Boundary";
 BoundaryTarget.displayName = "Transition.Boundary.Target";
-Host.displayName = "Transition.Boundary.Host";
 
 type BoundaryRootComponent = typeof BoundaryRoot;
 
@@ -55,12 +58,14 @@ export interface BoundaryComponent extends BoundaryRootComponent {
 	/**
 	 * Explicit host for clipping-escape placement.
 	 */
-	Host: typeof Host;
+	Host: NamedExoticComponent<
+		Omit<ComponentProps<typeof PortalOverlay>, "fallback">
+	>;
 }
 
 export type BoundaryProps = BoundaryComponentProps<BoundaryPrimitiveProps>;
 
 export const Boundary = Object.assign(BoundaryRoot, {
 	Target: BoundaryTarget,
-	Host,
+	Host: PortalOverlay,
 }) as BoundaryComponent;

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

@@ -0,0 +1,36 @@
+import { type ComponentProps, memo } from "react";
+import { StyleSheet } from "react-native";
+import Animated from "react-native-reanimated";
+import { NativePortalHost, PORTAL_POINTER_EVENTS } from "../teleport";
+
+const AnimatedHost = NativePortalHost
+	? Animated.createAnimatedComponent(NativePortalHost)
+	: null;
+
+/**
+ * The native receiving point for a Portal whose destination matches `name`.
+ *
+ * Handoff places this inside a boundary, filling its local frame. Escape-clipping
+ * places it inside a PortalOverlay, which supplies
+ * the boundary's size, offset, and animated styles. This component only renders
+ * the receiver; destination selection and measurement belong to its callers.
+ */
+export const PortalHost = memo(function PortalHost({
+	name,
+	style = styles.inline,
+}: {
+	name: string;
+	style?: ComponentProps<typeof Animated.View>["style"];
+}) {
+	return AnimatedHost ? (
+		<AnimatedHost
+			name={name}
+			pointerEvents={PORTAL_POINTER_EVENTS}
+			style={style}
+		/>
+	) : null;
+});
+
+const styles = StyleSheet.create({
+	inline: { ...StyleSheet.absoluteFill, overflow: "visible" },
+});

package/src/components/boundary/portal/components/portal-overlay.tsx

@@ -0,0 +1,223 @@
+import { memo, useId, useLayoutEffect } from "react";
+import {
+	I18nManager,
+	type StyleProp,
+	StyleSheet,
+	useWindowDimensions,
+	View,
+	type ViewStyle,
+} from "react-native";
+import Animated, {
+	type MeasuredDimensions,
+	type SharedValue,
+	useAnimatedReaction,
+	useAnimatedStyle,
+} from "react-native-reanimated";
+import { NO_STYLES } from "../../../../constants";
+import { useBuilderStore } from "../../../../providers/screen/builder";
+import { composeSlotStyleWithLocalTransform } from "../../../../providers/screen/orchestrator/styles/helpers/compose-slot-style";
+import { resolvePortalOffsetStyle } from "../helpers/offset-style";
+import { useHostMeasurement } from "../hooks/use-host-measurement";
+import { registerHost, unregisterHost } from "../stores/host-registry.store";
+import {
+	type ActivePortalBoundaryHost,
+	useActivePortalBoundaryHosts,
+} from "../stores/portal-boundary-host.store";
+import { PORTAL_POINTER_EVENTS } from "../teleport";
+import { PortalHost } from "./portal-host";
+
+type PortalOverlayProps = {
+	style?: StyleProp<ViewStyle>;
+	fallback?: boolean;
+};
+
+/**
+ * A screen-sized overlay containing the receivers for escaped boundary frames.
+ *
+ * Registers this overlay as an available placement, measures its origin, and
+ * renders one positioned PortalHost per boundary assigned to it. An overlay can
+ * contain many hosts; each host receives one named portal.
+ *
+ * Boundary.Host uses this directly; screens render it with `fallback` for
+ * their automatic overlay. Explicit overlays take priority over the fallback.
+ * Handoff between screens uses receivers inside boundaries, so it does not
+ * need this overlay unless escapeClipping is also enabled.
+ */
+export const PortalOverlay = memo(function PortalOverlay({
+	fallback = false,
+	style,
+}: PortalOverlayProps) {
+	const screenKey = useBuilderStore((s) => s.derivations.currentScreenKey);
+	const id = useId();
+	const hostKey = fallback ? screenKey : `${screenKey}-host-${id}`;
+	const activeBoundaryHosts = useActivePortalBoundaryHosts(hostKey);
+
+	const { height: viewportHeight, width: viewportWidth } =
+		useWindowDimensions();
+
+	const measurementKey = activeBoundaryHosts.length
+		? activeBoundaryHosts.map((host) => host.portalHostName).join("|")
+		: null;
+
+	const measurement = useHostMeasurement({
+		measurementKey,
+		boundaryMeasurements: activeBoundaryHosts.map(
+			(host) => host.localMeasurement,
+		),
+	});
+
+	const boundaryHosts = activeBoundaryHosts.map((host) => (
+		<View
+			key={host.portalHostName}
+			pointerEvents={PORTAL_POINTER_EVENTS}
+			style={[
+				styles.boundaryHostViewport,
+				{ width: viewportWidth, height: viewportHeight },
+			]}
+		>
+			<BoundaryPortalPlacement
+				host={host}
+				hostBounds={measurement.hostBounds}
+			/>
+		</View>
+	));
+
+	useLayoutEffect(() => {
+		registerHost({
+			fallback,
+			hostKey,
+			screenKey,
+		});
+
+		return () => {
+			unregisterHost(screenKey, hostKey);
+		};
+	}, [fallback, hostKey, screenKey]);
+
+	return (
+		<Animated.View
+			ref={measurement.hostRef}
+			pointerEvents={PORTAL_POINTER_EVENTS}
+			style={[
+				styles.host,
+				{ width: viewportWidth, height: viewportHeight },
+				style,
+			]}
+			collapsable={false}
+		>
+			{boundaryHosts}
+		</Animated.View>
+	);
+});
+
+const getCurrentBoundaryBounds = (host: ActivePortalBoundaryHost) => {
+	"worklet";
+	return host.localMeasurement.get()?.bounds ?? null;
+};
+
+type BoundaryPortalPlacementProps = {
+	host: ActivePortalBoundaryHost;
+	hostBounds: SharedValue<MeasuredDimensions | null>;
+};
+
+/** Positions one receiver using captured boundary and overlay measurements. */
+const BoundaryPortalPlacement = memo(function BoundaryPortalPlacement({
+	host,
+	hostBounds,
+}: BoundaryPortalPlacementProps) {
+	useAnimatedReaction(
+		() => {
+			"worklet";
+			return (
+				getCurrentBoundaryBounds(host) !== null && hostBounds.get() !== null
+			);
+		},
+		(ready) => {
+			"worklet";
+			host.portalHostReady.set(ready);
+		},
+	);
+
+	const hostStyle = useAnimatedStyle(() => {
+		"worklet";
+		const boundaryBounds = getCurrentBoundaryBounds(host);
+		if (!boundaryBounds) {
+			return NO_STYLES;
+		}
+
+		return resolvePortalOffsetStyle({
+			bounds: boundaryBounds,
+			hostBounds: hostBounds.get(),
+		});
+	});
+
+	const contentFrameStyle = useAnimatedStyle(() => {
+		"worklet";
+		const boundaryBounds = getCurrentBoundaryBounds(host);
+		if (!boundaryBounds) {
+			return NO_STYLES;
+		}
+
+		return {
+			height: boundaryBounds.height,
+			width: boundaryBounds.width,
+		};
+	});
+
+	const slotStyle = useAnimatedStyle(() => {
+		"worklet";
+		const slot = host.slotsMap.get()[host.boundaryId];
+
+		return composeSlotStyleWithLocalTransform(
+			slot?.style ?? NO_STYLES,
+			undefined,
+			slot?.boundsLocalTransform,
+		);
+	});
+
+	return (
+		<Animated.View
+			pointerEvents={PORTAL_POINTER_EVENTS}
+			style={[StyleSheet.absoluteFill, hostStyle]}
+			collapsable={false}
+		>
+			<PortalHost
+				name={host.portalHostName}
+				style={[styles.content, contentFrameStyle, slotStyle]}
+			/>
+		</Animated.View>
+	);
+});
+
+const styles = StyleSheet.create({
+	// The teleport offset is a physical page delta measured from the screen's
+	// left edge, so the content box must anchor there too. Under native RTL,
+	// `left: 0` swaps to a right-edge anchor; `end: 0` is the physical left edge
+	// in RTL regardless of the swap setting.
+	content: I18nManager.isRTL
+		? {
+				end: 0,
+				position: "absolute",
+				top: 0,
+			}
+		: {
+				left: 0,
+				position: "absolute",
+				top: 0,
+			},
+
+	host: {
+		elevation: 999999,
+		left: 0,
+		overflow: "visible",
+		position: "absolute",
+		top: 0,
+		zIndex: 999999,
+	},
+	boundaryHostViewport: {
+		left: 0,
+		overflow: "visible",
+		position: "absolute",
+		top: 0,
+	},
+});