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

package/src/shared/components/boundary/providers/boundary-root.provider.tsx

@@ -1,13 +1,35 @@
-import { type ReactNode, useCallback, useMemo, useState } from "react";
+import {
+	type ForwardedRef,
+	type ReactNode,
+	useCallback,
+	useImperativeHandle,
+	useMemo,
+	useState,
+} from "react";
 import type { View } from "react-native";
 import type { AnimatedRef, StyleProps } from "react-native-reanimated";
 import { useAnimatedRef } from "react-native-reanimated";
+import { useDescriptorsStore } from "../../../providers/screen/descriptors";
+import {
+	useComposedSlotStyles,
+	useSlotStackingStyles,
+} from "../../../providers/screen/styles";
+import { createBoundTag } from "../../../stores/bounds/helpers/link-pairs.helpers";
 import type { BoundTag } from "../../../stores/bounds/types";
 import createProvider from "../../../utils/create-provider";
 import { logger } from "../../../utils/logger";
-import type { BoundaryPortalRuntime } from "../portal/utils/resolve-portal";
+import { useBoundaryMeasurement } from "../hooks/use-boundary-measurement";
+import {
+	type BoundaryPortalRuntime,
+	resolveBoundaryPortal,
+} from "../portal/utils/resolve-portal";
+import type {
+	BoundaryConfigProps,
+	BoundaryId,
+	BoundaryOwnProps,
+} from "../types";
 
-interface BoundaryRootContextValue {
+interface BoundaryRootContextValue extends BoundaryRootRenderState {
 	registerTargetRef: (
 		targetRef: AnimatedRef<View>,
 		preparedStyles: StyleProps,
@@ -33,83 +55,181 @@ const MULTIPLE_TARGETS_WARNING =
 export const TARGET_OUTSIDE_ROOT_WARNING =
 	"Boundary.Target must be rendered inside Transition.Boundary or a component created by createBoundaryComponent.";
 
-interface BoundaryRootProps {
-	value: BoundaryRootContextValue;
-	children: ReactNode;
-}
-
-export const { BoundaryRootProvider, useBoundaryRootContext } = createProvider(
-	"BoundaryRoot",
-	{ guarded: false },
-)<BoundaryRootProps, BoundaryRootContextValue>((props) => props);
-
-export const useBoundaryRootState = (params: {
+export type BoundaryRootRenderState = {
+	attachedStyle: unknown;
 	boundTag: BoundTag;
+	currentScreenKey: string;
 	portalRuntime: BoundaryPortalRuntime;
-	rootMeasurementRef?: AnimatedRef<View>;
-}) => {
-	const { boundTag, portalRuntime, rootMeasurementRef } = params;
-	const rootRef = useAnimatedRef<View>();
-	const [targetEntry, setTargetEntry] = useState<BoundaryTargetEntry | null>(
-		null,
-	);
-
-	const registerTargetRef = useCallback(
-		(
-			targetRef: AnimatedRef<View>,
-			preparedStyles: StyleProps,
-			measurementRef?: AnimatedRef<View>,
-		) => {
-			setTargetEntry((prev) => {
-				if (prev?.ref === targetRef) {
-					return prev;
-				}
-
-				if (__DEV__ && prev !== null) {
-					logger.warnOnce(
-						"boundary:multiple-targets",
-						MULTIPLE_TARGETS_WARNING,
-					);
-				}
+	ref: AnimatedRef<View>;
+	rootEscapePlaceholderRef: AnimatedRef<View>;
+	shouldRenderBoundaryRootThroughPortal: boolean;
+	shouldRenderHandoffHost: boolean;
+};
 
-				return (
-					prev ?? {
-						ref: targetRef,
-						measurementRef: measurementRef ?? targetRef,
-						preparedStyles,
+type BoundaryRootProviderProps = Pick<
+	BoundaryOwnProps,
+	"enabled" | "escapeClipping" | "group" | "handoff"
+> & {
+	children: (state: BoundaryRootRenderState) => ReactNode;
+	config: BoundaryConfigProps;
+	forwardedRef?: ForwardedRef<any>;
+	id: BoundaryId;
+	style?: unknown;
+};
+
+export const {
+	BoundaryRootProvider,
+	useBoundaryRootContext,
+	useBoundaryRootStore,
+} = createProvider("BoundaryRoot", { guarded: false })<
+	BoundaryRootProviderProps,
+	BoundaryRootContextValue
+>(
+	({
+		children,
+		config,
+		enabled = true,
+		escapeClipping,
+		forwardedRef,
+		group,
+		handoff,
+		id,
+		style,
+	}) => {
+		const boundTag = useMemo(
+			() => createBoundTag(String(id), group),
+			[id, group],
+		);
+		const portalRuntime = resolveBoundaryPortal({
+			handoff,
+			escapeClipping,
+		});
+
+		const currentScreenKey = useDescriptorsStore(
+			(s) => s.derivations.currentScreenKey,
+		);
+		const hasConfiguredInterpolator = useDescriptorsStore(
+			(s) => s.derivations.hasConfiguredInterpolator,
+		);
+		const runtimeEnabled = enabled && hasConfiguredInterpolator;
+		// Associated slot styles attach whenever the boundary is enabled,
+		// independent of whether an interpolator is configured for this transition.
+		const shouldAttachAssociatedStyles = enabled;
+		const shouldEscapeBoundaryRootToScreenHost = portalRuntime.escapeClipping;
+
+		const associatedStyles = useComposedSlotStyles(boundTag.tag, style);
+		const associatedStackingStyles = useSlotStackingStyles(boundTag.tag);
+		const rootRef = useAnimatedRef<View>();
+		const rootEscapePlaceholderRef = useAnimatedRef<View>();
+		const [targetEntry, setTargetEntry] = useState<BoundaryTargetEntry | null>(
+			null,
+		);
+
+		const registerTargetRef = useCallback(
+			(
+				targetRef: AnimatedRef<View>,
+				preparedStyles: StyleProps,
+				measurementRef?: AnimatedRef<View>,
+			) => {
+				setTargetEntry((prev) => {
+					if (prev?.ref === targetRef) {
+						return prev;
 					}
-				);
-			});
-		},
-		[],
-	);
-
-	const unregisterTargetRef = useCallback((targetRef: AnimatedRef<View>) => {
-		setTargetEntry((prev) => (prev?.ref === targetRef ? null : prev));
-	}, []);
-
-	const contextValue = useMemo(
-		() => ({
-			registerTargetRef,
-			unregisterTargetRef,
-			activeTargetRef: targetEntry?.ref ?? null,
-			boundTag,
-			portalRuntime,
-		}),
-		[
-			registerTargetRef,
-			unregisterTargetRef,
-			targetEntry,
+
+					if (__DEV__ && prev !== null) {
+						logger.warnOnce(
+							"boundary:multiple-targets",
+							MULTIPLE_TARGETS_WARNING,
+						);
+					}
+
+					return (
+						prev ?? {
+							ref: targetRef,
+							measurementRef: measurementRef ?? targetRef,
+							preparedStyles,
+						}
+					);
+				});
+			},
+			[],
+		);
+
+		const unregisterTargetRef = useCallback((targetRef: AnimatedRef<View>) => {
+			setTargetEntry((prev) => (prev?.ref === targetRef ? null : prev));
+		}, []);
+
+		const rootMeasurementRef = shouldEscapeBoundaryRootToScreenHost
+			? rootEscapePlaceholderRef
+			: rootRef;
+		const measuredRef = targetEntry?.measurementRef ?? rootMeasurementRef;
+		const hasActiveTarget = targetEntry !== null;
+		const targetPreparedStyles = targetEntry?.preparedStyles;
+
+		useImperativeHandle(forwardedRef, () => rootRef.current as any, [rootRef]);
+
+		useBoundaryMeasurement({
 			boundTag,
-			portalRuntime,
-		],
-	);
-
-	return {
-		ref: rootRef,
-		contextValue,
-		hasActiveTarget: targetEntry !== null,
-		measuredRef: targetEntry?.measurementRef ?? rootMeasurementRef ?? rootRef,
-		targetPreparedStyles: targetEntry?.preparedStyles,
-	};
-};
+			enabled,
+			runtimeEnabled,
+			currentScreenKey,
+			measuredRef,
+			style,
+			targetPreparedStyles,
+			handoff: portalRuntime.handoff,
+			escapeClipping: portalRuntime.escapeClipping,
+			config,
+		});
+
+		const shouldRenderBoundaryRootThroughPortal =
+			shouldEscapeBoundaryRootToScreenHost && !hasActiveTarget;
+		// A nested active target takes the full associated style, so the root keeps
+		// only its stacking context. Root-owned escape-clipping moves the root
+		// through a screen host, so its associated style is applied through the
+		// host instead of inline on the escaped element.
+		// Host-only handoff receivers still need the associated style: their
+		// handoff host is absolute-filled inside this root, so the root is the
+		// visual frame that animates the received payload.
+		const attachedStyle = shouldAttachAssociatedStyles
+			? hasActiveTarget
+				? associatedStackingStyles
+				: shouldRenderBoundaryRootThroughPortal
+					? undefined
+					: associatedStyles
+			: undefined;
+
+		const value = useMemo<BoundaryRootContextValue>(
+			() => ({
+				attachedStyle,
+				activeTargetRef: targetEntry?.ref ?? null,
+				boundTag,
+				currentScreenKey,
+				portalRuntime,
+				registerTargetRef,
+				ref: rootRef,
+				rootEscapePlaceholderRef,
+				shouldRenderBoundaryRootThroughPortal,
+				shouldRenderHandoffHost: enabled && portalRuntime.handoff,
+				unregisterTargetRef,
+			}),
+			[
+				attachedStyle,
+				boundTag,
+				currentScreenKey,
+				enabled,
+				portalRuntime,
+				registerTargetRef,
+				rootRef,
+				rootEscapePlaceholderRef,
+				shouldRenderBoundaryRootThroughPortal,
+				targetEntry,
+				unregisterTargetRef,
+			],
+		);
+
+		return {
+			value,
+			children: children(value),
+		};
+	},
+);

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

@@ -7,14 +7,27 @@ import type {
 	ScreenPairKey,
 } from "../../../stores/bounds/types";
 
-export const getInitialDestinationMeasurePairKey = (params: {
+export type InitialDestinationMeasurementAction =
+	| "wait"
+	| "release"
+	| "measure"
+	| "complete";
+
+export type InitialDestinationMeasurementSignal = {
+	pairKey: ScreenPairKey;
+	action: InitialDestinationMeasurementAction;
+};
+
+export const getInitialDestinationMeasurementSignal = (params: {
 	enabled: boolean;
 	destinationPairKey?: ScreenPairKey;
 	ancestorDestinationPairKey?: ScreenPairKey;
 	linkId: string;
 	group?: string;
+	destinationPresent: boolean;
+	sourcePresent: boolean;
 	linkState?: LinkPairsState;
-}): ScreenPairKey | null => {
+}): InitialDestinationMeasurementSignal | null => {
 	"worklet";
 	const {
 		enabled,
@@ -22,30 +35,41 @@ export const getInitialDestinationMeasurePairKey = (params: {
 		ancestorDestinationPairKey,
 		linkId,
 		group,
+		destinationPresent,
+		sourcePresent,
 		linkState,
 	} = params;
-	const measurePairKey = destinationPairKey ?? ancestorDestinationPairKey;
+	const pairKey = destinationPairKey ?? ancestorDestinationPairKey;
 
-	if (!enabled || !measurePairKey) {
+	if (!enabled || !pairKey) {
 		return null;
 	}
 
-	const linkKey = getLinkKeyFromTag(linkId);
-	const hasDestination =
-		linkState?.[measurePairKey]?.links?.[linkKey]?.destination;
+	if (!destinationPresent) {
+		return { pairKey, action: "wait" };
+	}
 
-	if (hasDestination) {
-		return null;
+	if (!sourcePresent) {
+		return { pairKey, action: "release" };
 	}
 
+	const linkKey = getLinkKeyFromTag(linkId);
 	const activeGroupId =
-		group && linkState
-			? getActiveGroupId(linkState, measurePairKey, group)
-			: null;
+		group && linkState ? getActiveGroupId(linkState, pairKey, group) : null;
 
 	if (activeGroupId && activeGroupId !== linkKey) {
-		return null;
+		return { pairKey, action: "release" };
+	}
+
+	const link = linkState?.[pairKey]?.links?.[linkKey];
+
+	if (!link?.destination) {
+		return { pairKey, action: "measure" };
+	}
+
+	if (!link.source) {
+		return { pairKey, action: "wait" };
 	}
 
-	return measurePairKey;
+	return { pairKey, action: "complete" };
 };

package/src/shared/components/boundary/utils/measured-bounds.ts

@@ -96,6 +96,54 @@ export const isMeasurementInViewport = (
 	);
 };
 
+export const normalizeMeasuredBoundsWithVisibilityGate = ({
+	measured,
+	origin,
+	visibilityBlocked,
+	visibilityBlockOffset,
+	viewportWidth,
+	viewportHeight,
+}: {
+	measured: MeasuredDimensions;
+	origin: MeasuredDimensions;
+	visibilityBlocked: boolean;
+	visibilityBlockOffset: number;
+	viewportWidth: number;
+	viewportHeight: number;
+}): MeasuredDimensions => {
+	"worklet";
+	const normalized = normalizeMeasuredBoundsToOrigin(measured, origin);
+
+	if (
+		!visibilityBlocked ||
+		visibilityBlockOffset <= 0 ||
+		isMeasurementInViewport(normalized, viewportWidth, viewportHeight)
+	) {
+		return normalized;
+	}
+
+	// Fabric can expose the visibility transform to one native measurement one
+	// frame before the other. Prefer normal origin-relative coordinates, then
+	// test either side of that known frame skew while the gate is active.
+	const measuredAhead = {
+		...normalized,
+		pageY: normalized.pageY - visibilityBlockOffset,
+	};
+	if (isMeasurementInViewport(measuredAhead, viewportWidth, viewportHeight)) {
+		return measuredAhead;
+	}
+
+	const originAhead = {
+		...normalized,
+		pageY: normalized.pageY + visibilityBlockOffset,
+	};
+	if (isMeasurementInViewport(originAhead, viewportWidth, viewportHeight)) {
+		return originAhead;
+	}
+
+	return normalized;
+};
+
 export const measureWithOverscrollAwareness = (
 	ref: AnimatedRef<View>,
 	scrollState: ScrollGestureState | null,

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

@@ -8,7 +8,7 @@ import { useGestureContext } from "../../../providers/screen/gestures";
 import { OriginProvider } from "../../../providers/screen/origin.provider";
 import { useSlotProps, useSlotStyles } from "../../../providers/screen/styles";
 import type { ScreenContentComponentProps } from "../../../types";
-import { ScreenFallbackHost } from "../../boundary/portal/components/host";
+import { ScreenFallbackHost } from "../../boundary/portal/components/boundary-portal/components/host";
 import { useContentLayout } from "../hooks/use-content-layout";
 import { MaybeMaskedNavigationContainer } from "./maybe-masked-navigation-container";
 import { usesLayerRenderProps } from "./render-component";

package/src/shared/configs/presets.ts

@@ -434,7 +434,7 @@ export const SharedAppleMusic = ({
 			const dragXScale = interpolate(normX, [0, 1], xScaleOuput);
 			const dragYScale = interpolate(normY, [0, 1], yScaleOuput);
 
-			const boundValues = bounds({ id: sharedBoundTag }).math({
+			const boundValues = bounds({ id: sharedBoundTag }).values({
 				method: focused ? "content" : "transform",
 				anchor: "top",
 				scaleMode: "uniform",
@@ -453,7 +453,7 @@ export const SharedAppleMusic = ({
 			 * ===============================
 			 */
 			if (focused) {
-				const maskedValues = bounds({ id: sharedBoundTag }).math({
+				const maskedValues = bounds({ id: sharedBoundTag }).values({
 					space: "absolute",
 					method: "size",
 					target: "fullscreen",

package/src/shared/index.ts

@@ -30,6 +30,10 @@ export default {
 export type { NativeStackAdapterOptions } from "./adapters/with-screen-transitions";
 export { withScreenTransitions } from "./adapters/with-screen-transitions";
 export { snapTo } from "./animation/snap-to";
+export {
+	blockTransition,
+	unblockTransition,
+} from "./animation/transition-blocking";
 export {
 	NAVIGATION_MASK_CONTAINER_STYLE_ID,
 	NAVIGATION_MASK_ELEMENT_STYLE_ID,

package/src/shared/providers/screen/animation/helpers/read-screen-animation-revisions.ts

@@ -1,13 +1,17 @@
+import type { SharedValue } from "react-native-reanimated";
 import type {
 	ScreenAnimationDescendantSources,
 	ScreenAnimationSource,
 	ScreenInterpolatorPropsRevision,
 } from "../types";
 
+type ScreenInterpolatorExternalDeps = Pick<SharedValue<unknown>, "get">[];
+
 export const readScreenAnimationRevisions = (
 	screenInterpolatorPropsRevision: ScreenInterpolatorPropsRevision,
 	ancestorScreenAnimationSources: ScreenAnimationSource[],
 	descendantScreenAnimationSources: ScreenAnimationDescendantSources,
+	screenInterpolatorExternalDeps?: ScreenInterpolatorExternalDeps,
 ) => {
 	"worklet";
 	screenInterpolatorPropsRevision.get();
@@ -22,4 +26,14 @@ export const readScreenAnimationRevisions = (
 	for (let index = 0; index < descendantSources.length; index++) {
 		descendantSources[index]?.source.screenInterpolatorPropsRevision.get();
 	}
+
+	if (screenInterpolatorExternalDeps) {
+		for (
+			let index = 0;
+			index < screenInterpolatorExternalDeps.length;
+			index++
+		) {
+			screenInterpolatorExternalDeps[index]?.get();
+		}
+	}
 };

package/src/shared/providers/screen/styles/helpers/collect-interpolator-shared-values.ts

@@ -0,0 +1,75 @@
+import type { SharedValue } from "react-native-reanimated";
+import type { ScreenStyleInterpolator } from "../../../../types/animation.types";
+
+type WorkletClosure = Record<string, unknown>;
+
+type ClosureCarrier = {
+	__closure?: WorkletClosure;
+};
+
+type SharedValueLike = SharedValue<unknown> & {
+	_isReanimatedSharedValue: true;
+};
+
+const isSharedValueLike = (value: unknown): value is SharedValueLike =>
+	(value as Partial<SharedValueLike> | null)?._isReanimatedSharedValue === true;
+
+const getWorkletClosure = (value: unknown): WorkletClosure | undefined => {
+	if (
+		value === null ||
+		(typeof value !== "object" && typeof value !== "function")
+	) {
+		return undefined;
+	}
+
+	const closure = (value as Partial<ClosureCarrier>).__closure;
+	return closure && typeof closure === "object" ? closure : undefined;
+};
+
+const isPlainObject = (value: unknown): value is Record<string, unknown> =>
+	value !== null &&
+	typeof value === "object" &&
+	Object.getPrototypeOf(value) === Object.prototype;
+
+export const collectInterpolatorSharedValues = (
+	interpolators: Array<ScreenStyleInterpolator | undefined>,
+): SharedValue<unknown>[] => {
+	const sharedValues: SharedValue<unknown>[] = [];
+	const seen = new Set<unknown>();
+
+	const visit = (value: unknown) => {
+		if (value === null || value === undefined || seen.has(value)) {
+			return;
+		}
+		seen.add(value);
+
+		if (isSharedValueLike(value)) {
+			sharedValues.push(value);
+			return;
+		}
+
+		if (typeof value === "function") {
+			visit(getWorkletClosure(value));
+			return;
+		}
+
+		if (Array.isArray(value)) {
+			for (let index = 0; index < value.length; index++) {
+				visit(value[index]);
+			}
+			return;
+		}
+
+		if (isPlainObject(value)) {
+			for (const item of Object.values(value)) {
+				visit(item);
+			}
+		}
+	};
+
+	for (let index = 0; index < interpolators.length; index++) {
+		visit(getWorkletClosure(interpolators[index]));
+	}
+
+	return sharedValues;
+};

package/src/shared/providers/screen/styles/hooks/use-interpolated-style-maps.tsx

@@ -1,3 +1,4 @@
+import { useMemo } from "react";
 import { useDerivedValue, useSharedValue } from "react-native-reanimated";
 import { NO_STYLES } from "../../../../constants";
 import { AnimationStore } from "../../../../stores/animation.store";
@@ -22,6 +23,7 @@ import {
 	syncScreenOptionsOverrides,
 	useScreenOptionsContext,
 } from "../../options";
+import { collectInterpolatorSharedValues } from "../helpers/collect-interpolator-shared-values";
 import { normalizeSlots } from "../helpers/normalize-slots";
 import { isOpeningBeforeStart } from "../helpers/opening-phase";
 import type { LocalStyleLayers } from "../helpers/resolve-slot-styles";
@@ -146,6 +148,14 @@ export const useInterpolatedStylesMap = () => {
 	const transition = useBuildTransitionAccessor();
 	const nextInterpolatorReady = useSharedValue(0);
 
+	// In some cases, a user may want to use external shared values to drive animations in the interpoaltor.
+	// We can now support this by collecting those shared values and reading them here to trigger an update.
+	const interpolatorSharedValues = useMemo(
+		() =>
+			collectInterpolatorSharedValues([currentInterpolator, nextInterpolator]),
+		[currentInterpolator, nextInterpolator],
+	);
+
 	const activeScreenKey = nextScreenKey ?? currentScreenKey;
 	const {
 		entering: activeEntering,
@@ -162,6 +172,7 @@ export const useInterpolatedStylesMap = () => {
 			screenInterpolatorPropsRevision,
 			ancestorScreenAnimationSources,
 			descendantScreenAnimationSources,
+			interpolatorSharedValues,
 		);
 		const props = screenInterpolatorProps.get();
 

package/src/shared/providers/screen/styles/hooks/use-maybe-block-visibility.tsx

@@ -71,5 +71,6 @@ export const useMaybeBlockVisibility = (isFloatingOverlay?: boolean) => {
 	return {
 		animatedStyle,
 		animatedProps,
+		shouldBlockVisibility,
 	};
 };

package/src/shared/providers/screen/styles/slot.provider.tsx

@@ -34,6 +34,7 @@ export type ScreenSlotContextValue = {
 	localStylesMaps: SharedValue<LocalStyleLayers>;
 	nextInterpolatorReady: SharedValue<number>;
 	slotsMap: SharedValue<NormalizedTransitionInterpolatedStyle>;
+	visibilityBlocked: SharedValue<boolean>;
 };
 
 export const {
@@ -54,15 +55,16 @@ export const {
 		localStylesMaps,
 		ancestorStylesMap: parentContext?.slotsMap,
 	});
-	const { animatedStyle, animatedProps } =
+	const { animatedStyle, animatedProps, shouldBlockVisibility } =
 		useMaybeBlockVisibility(isFloatingOverlay);
 	const value = useMemo(
 		() => ({
 			localStylesMaps,
 			nextInterpolatorReady,
 			slotsMap,
+			visibilityBlocked: shouldBlockVisibility,
 		}),
-		[localStylesMaps, nextInterpolatorReady, slotsMap],
+		[localStylesMaps, nextInterpolatorReady, shouldBlockVisibility, slotsMap],
 	);
 
 	useLayoutEffect(() => {

package/src/shared/providers/screen/styles/stores/slot-references.store.ts

@@ -33,7 +33,8 @@ export const registerScreenSlots = (
 	if (
 		previous?.localStylesMaps === slots.localStylesMaps &&
 		previous.nextInterpolatorReady === slots.nextInterpolatorReady &&
-		previous.slotsMap === slots.slotsMap
+		previous.slotsMap === slots.slotsMap &&
+		previous.visibilityBlocked === slots.visibilityBlocked
 	) {
 		return;
 	}