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

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

@@ -0,0 +1,175 @@
+import type {
+	LinkPairsState,
+	ScreenPairKey,
+} from "../../../stores/bounds/types";
+import type { MeasureTarget } from "../types";
+
+const SOURCE_SIGNAL_PREFIX = "source|";
+const DESTINATION_SIGNAL_PREFIX = "destination|";
+
+type RefreshBoundarySignal = MeasureTarget & {
+	signal: string;
+};
+
+const buildRefreshSignal = (
+	type: MeasureTarget["type"],
+	pairKey: ScreenPairKey,
+	key: string,
+): RefreshBoundarySignal => {
+	"worklet";
+	const prefix =
+		type === "source" ? SOURCE_SIGNAL_PREFIX : DESTINATION_SIGNAL_PREFIX;
+	return {
+		type,
+		pairKey,
+		signal: `${prefix}${pairKey}|${key}`,
+	};
+};
+
+const isMatchedScreenPortalDestinationRefresh = (
+	linkState: LinkPairsState | undefined,
+	pairKey: ScreenPairKey,
+	linkId: string,
+) => {
+	"worklet";
+
+	return (
+		linkState?.[pairKey]?.links?.[linkId]?.source?.portalAttachTarget ===
+		"matched-screen"
+	);
+};
+
+export const getRefreshBoundarySignal = (params: {
+	enabled: boolean;
+	currentScreenKey: string;
+	sourcePairKey?: ScreenPairKey;
+	destinationPairKey?: ScreenPairKey;
+	ancestorDestinationPairKey?: ScreenPairKey;
+	nextScreenKey?: string;
+	linkId: string;
+	group?: string;
+	shouldRefresh: boolean;
+	closing: boolean;
+	entering: boolean;
+	animating: boolean;
+	progress: number;
+	linkState?: LinkPairsState;
+}): RefreshBoundarySignal | null => {
+	"worklet";
+	const {
+		enabled,
+		currentScreenKey,
+		sourcePairKey,
+		destinationPairKey,
+		ancestorDestinationPairKey,
+		nextScreenKey,
+		linkId,
+		group,
+		shouldRefresh,
+		closing,
+		entering,
+		animating,
+		progress,
+		linkState,
+	} = params;
+
+	if (!enabled) return null;
+
+	const canRefreshPreCloseDestination =
+		shouldRefresh && closing && !entering && !animating && progress >= 1;
+
+	const canRefreshSettledDestination = shouldRefresh && !closing && !entering;
+
+	// Guards:
+	// 1) A user may dismiss via back button, in this case, we should remeasure.
+	// 2) If a user drags during entering/closing animations we should NOT remeasure.
+	if (!canRefreshPreCloseDestination && !canRefreshSettledDestination) {
+		return null;
+	}
+
+	// Non group:
+	// Since in typical group flows we would need to know the src, we don't need to do that for
+	// single a->b flows. So we just trigger the destination refresh.
+	if (!group) {
+		const refreshDestinationPairKey =
+			destinationPairKey ??
+			(nextScreenKey ? undefined : ancestorDestinationPairKey);
+
+		if (!refreshDestinationPairKey) {
+			return null;
+		}
+
+		// NOTE:
+		// Matched-screen portals use the destination as the initial host/anchor.
+		// Once attached, the teleported source is the thing being animated, so a
+		// fresh destination measure would mix in a second coordinate basis. Signals were introduced for scroll view cases + group
+		// cases, but I can't find a case for where a live component ( matched-screen ) would need this complexity. I would just assume
+		// you would want this for a->b | b->a transitions.
+		if (
+			isMatchedScreenPortalDestinationRefresh(
+				linkState,
+				refreshDestinationPairKey,
+				linkId,
+			)
+		) {
+			return null;
+		}
+
+		return buildRefreshSignal(
+			"destination",
+			refreshDestinationPairKey,
+			[currentScreenKey, closing ? "closing" : "settled"].join("|"),
+		);
+	}
+
+	// Source side:
+	// When the activeId changes, trigger a refresh to ensure the source bounds are captured.
+	if (sourcePairKey) {
+		const activeId = linkState?.[sourcePairKey]?.groups?.[group]?.activeId;
+
+		if (activeId !== linkId) {
+			return null;
+		}
+
+		return buildRefreshSignal(
+			"source",
+			sourcePairKey,
+			[group, linkId, closing ? "closing" : "settled"].join("|"),
+		);
+	}
+
+	const refreshDestinationPairKey =
+		destinationPairKey ??
+		(nextScreenKey ? undefined : ancestorDestinationPairKey);
+
+	if (!refreshDestinationPairKey) return null;
+
+	// Destination side:
+	// When the activeId changes, trigger a refresh to ensure the destination bounds are captured.
+	const activeId =
+		linkState?.[refreshDestinationPairKey]?.groups?.[group]?.activeId;
+
+	// Destination retargeting should only measure a concrete member that already
+	// participates in the pair. Missing members fall back to initialId at resolve.
+	if (activeId !== linkId) {
+		return null;
+	}
+
+	// NOTE:
+	// see above for explanation
+	if (
+		isMatchedScreenPortalDestinationRefresh(
+			linkState,
+			refreshDestinationPairKey,
+			linkId,
+		)
+	) {
+		return null;
+	}
+
+	return buildRefreshSignal(
+		"destination",
+		refreshDestinationPairKey,
+		[group, linkId, closing ? "closing" : "settled"].join("|"),
+	);
+};

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

@@ -0,0 +1,63 @@
+import type {
+	LinkPairsState,
+	ScreenPairKey,
+} from "../../../stores/bounds/types";
+
+const SOURCE_SIGNAL_PREFIX = "source|";
+
+type SourceCaptureSignal = {
+	pairKey: ScreenPairKey;
+	signal: string;
+};
+
+export const getInitialSourceCaptureSignal = (params: {
+	enabled: boolean;
+	sourcePairKey?: ScreenPairKey;
+	linkId: string;
+	group?: string;
+	shouldAutoMeasure: boolean;
+	linkState?: LinkPairsState;
+}): SourceCaptureSignal | null => {
+	"worklet";
+	const {
+		enabled,
+		sourcePairKey,
+		linkId,
+		group,
+		shouldAutoMeasure,
+		linkState,
+	} = params;
+
+	if (!enabled || !sourcePairKey) {
+		return null;
+	}
+
+	// Trigger components capture on press. Passive Boundary.View sources wait for
+	// their destination side to attach, then capture into the same assigned pair.
+	if (!shouldAutoMeasure) {
+		return null;
+	}
+
+	const link = linkState?.[sourcePairKey]?.links?.[linkId];
+
+	if (!link?.destination || link.source) {
+		return null;
+	}
+
+	if (group) {
+		const activeId = linkState?.[sourcePairKey]?.groups?.[group]?.activeId;
+
+		// Passive grouped sources should not measure every mounted item. Once a
+		// group has an active id, only that concrete member can auto-capture.
+		if (activeId && activeId !== linkId) {
+			return null;
+		}
+	}
+
+	const signalParts = group ? [group, linkId] : [linkId];
+
+	return {
+		pairKey: sourcePairKey,
+		signal: `${SOURCE_SIGNAL_PREFIX}${sourcePairKey}|${signalParts.join("|")}`,
+	};
+};

package/src/shared/components/create-transition-aware-component.tsx

@@ -43,6 +43,8 @@ export function createTransitionAwareComponent<P extends object>(
 			onScroll: userOnScroll,
 			onMomentumScrollEnd: userOnMomentumScrollEnd,
 			onScrollEndDrag: userOnScrollEndDrag,
+			children,
+			contentContainerStyle,
 			...scrollableProps
 		} = props;
 
@@ -69,11 +71,11 @@ export function createTransitionAwareComponent<P extends object>(
 			scrollHandler,
 			userOnScroll ?? null,
 		]);
-
 		const scrollableComponent = (
 			<AnimatedComponent
 				{...(scrollableProps as any)}
 				ref={ref}
+				contentContainerStyle={contentContainerStyle}
 				/**
 				 * Keep the scroll listener detached while the owning gesture screen is
 				 * closing. On iOS, a bounced ScrollView can keep sending native scroll
@@ -90,7 +92,9 @@ export function createTransitionAwareComponent<P extends object>(
 						? scrollableProps.scrollEventThrottle || 16
 						: undefined
 				}
-			/>
+			>
+				{children}
+			</AnimatedComponent>
 		);
 
 		const coordinatedScrollableComponent = nativeGesture ? (
@@ -119,6 +123,7 @@ export function createTransitionAwareComponent<P extends object>(
 			styleId,
 			onPress,
 			remeasureOnFocus,
+			animatedProps: userAnimatedProps,
 			...rest
 		} = props as any;
 
@@ -159,7 +164,7 @@ export function createTransitionAwareComponent<P extends object>(
 						{...(rest as any)}
 						ref={animatedRef}
 						style={[style, associatedStyles]}
-						animatedProps={associatedProps}
+						animatedProps={userAnimatedProps ?? associatedProps}
 						onPress={captureActiveOnPress}
 						onLayout={runOnUI(handleInitialLayout)}
 						collapsable={!sharedBoundTag}

package/src/shared/components/{integrations/masked-view.tsx → masked-view.tsx}

@@ -1,6 +1,6 @@
 import { type StyleProp, StyleSheet, View, type ViewStyle } from "react-native";
-import { CONTAINER_STYLE_ID, MASK_STYLE_ID } from "../../constants";
-import { createTransitionAwareComponent } from "../create-transition-aware-component";
+import { CONTAINER_STYLE_ID, MASK_STYLE_ID } from "../constants";
+import { createTransitionAwareComponent } from "./create-transition-aware-component";
 
 const TransitionView = createTransitionAwareComponent(View);
 

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

@@ -9,7 +9,9 @@ import Animated, {
 import { NO_PROPS, NO_STYLES } from "../../../constants";
 import { useDescriptors } from "../../../providers/screen/descriptors";
 import { useGestureContext } from "../../../providers/screen/gestures";
+import { OriginProvider } from "../../../providers/screen/origin.provider";
 import { useScreenStyles } from "../../../providers/screen/styles";
+import { ScreenFallbackHost } from "../../boundary/portal/components/host";
 import { useContentLayout } from "../hooks/use-content-layout";
 import { MaybeMaskedNavigationContainer } from "./maybe-masked-navigation-container";
 import { SurfaceContainer } from "./surface-container";
@@ -56,13 +58,16 @@ export const ContentLayer = memo(
 						enabled={isNavigationMaskEnabled}
 					>
 						<SurfaceContainer pointerEvents={contentPointerEvents}>
-							{hasAutoSnapPoint ? (
-								<View collapsable={false} onLayout={handleContentLayout}>
-									{children}
-								</View>
-							) : (
-								children
-							)}
+							<OriginProvider>
+								{hasAutoSnapPoint ? (
+									<View collapsable={false} onLayout={handleContentLayout}>
+										{children}
+									</View>
+								) : (
+									children
+								)}
+								<ScreenFallbackHost />
+							</OriginProvider>
 						</SurfaceContainer>
 					</MaybeMaskedNavigationContainer>
 				</Animated.View>

package/src/shared/configs/presets.ts

@@ -434,12 +434,10 @@ export const SharedAppleMusic = ({
 			const dragXScale = interpolate(normX, [0, 1], xScaleOuput);
 			const dragYScale = interpolate(normY, [0, 1], yScaleOuput);
 
-			const boundValues = bounds({
-				id: sharedBoundTag,
+			const boundValues = bounds({ id: sharedBoundTag }).math({
 				method: focused ? "content" : "transform",
 				anchor: "top",
 				scaleMode: "uniform",
-				raw: true,
 			});
 
 			const opacity = interpolate(
@@ -455,12 +453,10 @@ export const SharedAppleMusic = ({
 			 * ===============================
 			 */
 			if (focused) {
-				const maskedValues = bounds({
-					id: sharedBoundTag,
+				const maskedValues = bounds({ id: sharedBoundTag }).math({
 					space: "absolute",
 					method: "size",
 					target: "fullscreen",
-					raw: true,
 				});
 
 				// Apple Music style drop shadow that increases with drag magnitude

package/src/shared/index.ts

@@ -1,11 +1,8 @@
 import { FlatList, Pressable, ScrollView, View } from "react-native";
 import { withScreenTransitions } from "./adapters/with-screen-transitions";
-import {
-	Boundary,
-	createBoundaryComponent,
-} from "./components/create-boundary-component";
+import { Boundary, createBoundaryComponent } from "./components/boundary";
 import { createTransitionAwareComponent } from "./components/create-transition-aware-component";
-import MaskedView from "./components/integrations/masked-view";
+import MaskedView from "./components/masked-view";
 import { Presets, Specs } from "./configs";
 
 export default {
@@ -29,6 +26,11 @@ export default {
 export type { NativeStackAdapterOptions } from "./adapters/with-screen-transitions";
 export { withScreenTransitions } from "./adapters/with-screen-transitions";
 export { snapTo } from "./animation/snap-to";
+export type {
+	BoundaryPortal,
+	BoundaryPortalAttachTarget,
+	BoundaryPortalOptions,
+} from "./components/boundary";
 export {
 	NAVIGATION_MASK_CONTAINER_STYLE_ID,
 	NAVIGATION_MASK_ELEMENT_STYLE_ID,
@@ -51,7 +53,12 @@ export {
 export type {
 	AnimatedViewStyle,
 	AnimationConfig,
+	BoundaryTeleportControl,
+	BoundsMotion,
+	BoundsMotionFrame,
+	BoundsMotionTransform,
 	BoundsNavigationAccessor,
+	BoundsNavigationRevealOptions,
 	BoundsNavigationRevealStyle,
 	BoundsNavigationZoomOpacityRange,
 	BoundsNavigationZoomOpacityRanges,
@@ -72,6 +79,7 @@ export type {
 	ScrollGestureState,
 	ScrollMetadataState,
 	TransitionInterpolatedStyle,
+	TransitionSlotProps,
 	TransitionSlotStyle,
 	TransitionSpec,
 } from "./types";

package/src/shared/providers/helpers/measured-bounds-writes.ts

@@ -1,7 +1,11 @@
 import type { MeasuredDimensions, StyleProps } from "react-native-reanimated";
 import { setEntry } from "../../stores/bounds/internals/entries";
 import { setDestination, setSource } from "../../stores/bounds/internals/links";
-import type { ScreenPairKey } from "../../stores/bounds/types";
+import type {
+	BoundsPortalAttachTarget,
+	ScreenPairKey,
+	SourceHostRef,
+} from "../../stores/bounds/types";
 
 type LinkWrite =
 	| {
@@ -21,6 +25,8 @@ type ApplyMeasuredBoundsWritesParams = {
 	measured: MeasuredDimensions;
 	preparedStyles: StyleProps;
 	linkWrite?: LinkWrite;
+	portalHost?: BoundsPortalAttachTarget;
+	sourceHost?: SourceHostRef;
 };
 
 export const applyMeasuredBoundsWrites = (
@@ -35,6 +41,8 @@ export const applyMeasuredBoundsWrites = (
 		measured,
 		preparedStyles,
 		linkWrite,
+		portalHost,
+		sourceHost,
 	} = params;
 
 	// Set the bounds entry on every measure to avoid any stale measurements
@@ -51,6 +59,8 @@ export const applyMeasuredBoundsWrites = (
 			measured,
 			preparedStyles,
 			group,
+			portalHost,
+			sourceHost,
 		);
 	}
 

package/src/shared/providers/screen/descriptors/descriptors.provider.tsx

@@ -4,7 +4,7 @@ import type { BaseStackDescriptor } from "../../../types/stack.types";
 import createProvider from "../../../utils/create-provider";
 import type { DescriptorDerivations } from "./helpers/derive-descriptor-derivations";
 import { deriveDescriptorDerivations } from "./helpers/derive-descriptor-derivations";
-import { getAncestorKeys } from "./helpers/get-ancestor-keys";
+import { getAncestorKeyState } from "./helpers/get-ancestor-keys";
 
 /**
  * Base descriptor interface - minimal contract for all stack types.
@@ -49,7 +49,10 @@ const {
 		[previous, current, next],
 	);
 
-	const ancestorKeys = useMemo(() => getAncestorKeys(current), [current]);
+	const { ancestorKeys, ancestorDestinationPairKey } = useMemo(
+		() => getAncestorKeyState(current),
+		[current],
+	);
 
 	const derivations = useMemo(
 		() =>
@@ -58,8 +61,9 @@ const {
 				current,
 				next,
 				ancestorKeys,
+				ancestorDestinationPairKey,
 			}),
-		[previous, current, next, ancestorKeys],
+		[previous, current, next, ancestorKeys, ancestorDestinationPairKey],
 	);
 
 	const value = useMemo(

package/src/shared/providers/screen/descriptors/helpers/derive-descriptor-derivations.ts

@@ -1,9 +1,14 @@
+import { createScreenPairKey } from "../../../../stores/bounds/helpers/link-pairs.helpers";
+import type { ScreenPairKey } from "../../../../stores/bounds/types";
 import type { BaseStackDescriptor } from "../../../../types/stack.types";
 
 export interface DescriptorDerivations {
 	previousScreenKey?: string;
 	currentScreenKey: string;
 	nextScreenKey?: string;
+	sourcePairKey?: ScreenPairKey;
+	destinationPairKey?: ScreenPairKey;
+	ancestorDestinationPairKey?: ScreenPairKey;
 	parentScreenKey?: string;
 	isFirstKey: boolean;
 	isTopMostScreen: boolean;
@@ -16,6 +21,7 @@ interface Params {
 	current: BaseStackDescriptor;
 	next?: BaseStackDescriptor;
 	ancestorKeys: string[];
+	ancestorDestinationPairKey?: ScreenPairKey;
 }
 
 export function deriveDescriptorDerivations({
@@ -23,10 +29,17 @@ export function deriveDescriptorDerivations({
 	current,
 	next,
 	ancestorKeys,
+	ancestorDestinationPairKey,
 }: Params): DescriptorDerivations {
 	const previousScreenKey = previous?.route.key;
 	const currentScreenKey = current.route.key;
 	const nextScreenKey = next?.route.key;
+	const sourcePairKey = nextScreenKey
+		? createScreenPairKey(currentScreenKey, nextScreenKey)
+		: undefined;
+	const destinationPairKey = previousScreenKey
+		? createScreenPairKey(previousScreenKey, currentScreenKey)
+		: undefined;
 
 	const navigationState = current.navigation.getState();
 	const routes = navigationState?.routes ?? [];
@@ -41,6 +54,9 @@ export function deriveDescriptorDerivations({
 		previousScreenKey,
 		currentScreenKey,
 		nextScreenKey,
+		sourcePairKey,
+		destinationPairKey,
+		ancestorDestinationPairKey,
 		parentScreenKey: ancestorKeys[0],
 		isFirstKey,
 		isTopMostScreen,

package/src/shared/providers/screen/descriptors/helpers/get-ancestor-keys.ts

@@ -1,16 +1,26 @@
+import { createScreenPairKey } from "../../../../stores/bounds/helpers/link-pairs.helpers";
+import type { ScreenPairKey } from "../../../../stores/bounds/types";
 import type { BaseStackDescriptor } from "../../../../types/stack.types";
 
+export interface AncestorKeyState {
+	ancestorKeys: string[];
+	ancestorDestinationPairKey?: ScreenPairKey;
+}
+
 /**
- * Builds the full ancestor key chain for nested navigators.
- * Returns an array of screen keys from immediate parent to root.
- * [parentKey, grandparentKey, greatGrandparentKey, ...]
+ * Builds nested navigator ancestor keys from immediate parent to root.
+ * The nearest ancestor destination pair lets child routes attach measurements
+ * to the transition owned by the parent stack.
  */
-export function getAncestorKeys(current: BaseStackDescriptor): string[] {
+export function getAncestorKeyState(
+	current: BaseStackDescriptor,
+): AncestorKeyState {
 	const ancestors: string[] = [];
+	let ancestorDestinationPairKey: ScreenPairKey | undefined;
 	const nav = current.navigation as any;
 
 	if (typeof nav?.getParent !== "function") {
-		return ancestors;
+		return { ancestorKeys: ancestors };
 	}
 
 	let parent = nav.getParent();
@@ -21,10 +31,25 @@ export function getAncestorKeys(current: BaseStackDescriptor): string[] {
 			const focusedRoute = state.routes[state.index];
 			if (focusedRoute?.key) {
 				ancestors.push(focusedRoute.key);
+
+				const previousRoute = state.routes[state.index - 1];
+				if (!ancestorDestinationPairKey && previousRoute?.key) {
+					ancestorDestinationPairKey = createScreenPairKey(
+						previousRoute.key,
+						focusedRoute.key,
+					);
+				}
 			}
 		}
 		parent = parent.getParent();
 	}
 
-	return ancestors;
+	return {
+		ancestorKeys: ancestors,
+		ancestorDestinationPairKey,
+	};
+}
+
+export function getAncestorKeys(current: BaseStackDescriptor): string[] {
+	return getAncestorKeyState(current).ancestorKeys;
 }

package/src/shared/providers/screen/origin.provider.tsx

@@ -0,0 +1,38 @@
+import { StyleSheet, type View } from "react-native";
+import Animated, {
+	type AnimatedRef,
+	useAnimatedRef,
+} from "react-native-reanimated";
+import createProvider from "../../utils/create-provider";
+
+interface Props {
+	children: React.ReactNode;
+}
+interface ContextValue {
+	originRef: AnimatedRef<View>;
+}
+
+export const { OriginProvider, useOriginContext } = createProvider("Origin", {
+	guarded: true,
+})<Props, ContextValue>(({ children }) => {
+	const originRef = useAnimatedRef<View>();
+
+	return {
+		value: {
+			originRef,
+		},
+		children: (
+			<Animated.View
+				style={styles.container}
+				collapsable={false}
+				ref={originRef}
+			>
+				{children}
+			</Animated.View>
+		),
+	};
+});
+
+const styles = StyleSheet.create({
+	container: { flex: 1 },
+});

package/src/shared/providers/screen/styles/constants.ts

@@ -1,3 +1,4 @@
+import { PORTAL_HOST_NAME_RESET_VALUE } from "../../../components/boundary/portal/utils/naming";
 import {
 	NAVIGATION_MASK_CONTAINER_STYLE_ID,
 	NAVIGATION_MASK_ELEMENT_STYLE_ID,
@@ -59,6 +60,7 @@ export const STYLE_RESET_VALUES: Record<string, unknown> = {
 };
 
 export const PROP_RESET_VALUES: Record<string, unknown> = {
+	hostName: PORTAL_HOST_NAME_RESET_VALUE,
 	pointerEvents: "auto",
 };