react-native-screen-transitions 3.4.0-alpha.5 → 3.4.0-alpha.7

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "react-native-screen-transitions",
-	"version": "3.4.0-alpha.5",
+	"version": "3.4.0-alpha.7",
 	"description": "Easy screen transitions for React Native and Expo",
 	"author": "Ed",
 	"license": "MIT",

package/src/blank-stack/navigators/create-blank-stack-navigator.tsx

@@ -23,7 +23,10 @@ import type {
 	BlankStackNavigatorProps,
 } from "../types";
 
-type BlankStackNavigatorInnerProps = BlankStackNavigatorProps & {
+type BlankStackNavigatorInnerProps = Omit<
+	BlankStackNavigatorProps,
+	keyof BlankStackFactoryOptions
+> & {
 	DISABLE_NATIVE_SCREENS?: boolean;
 	DISABLE_NATIVE_SCREEN_CONTAINER?: boolean;
 };
@@ -77,49 +80,39 @@ function BlankStackNavigatorInner({
 	);
 }
 
-function createBlankStackNavigatorComponent({
-	independent,
-	enableNativeScreens,
-}: Required<BlankStackFactoryOptions>) {
-	function BlankStackNavigator(props: BlankStackNavigatorProps) {
-		const isNested = React.useContext(BlankStackContext);
-
-		const navigator = (
-			<BlankStackNavigatorInner
-				{...props}
-				{...(!enableNativeScreens && {
-					DISABLE_NATIVE_SCREENS: true,
-				})}
-				DISABLE_NATIVE_SCREEN_CONTAINER={independent}
-			/>
-		);
-
-		if (!independent || isNested) {
-			return navigator;
-		}
+function BlankStackNavigator({
+	independent = false,
+	enableNativeScreens = true,
+	...rest
+}: BlankStackNavigatorProps) {
+	const isNested = React.useContext(BlankStackContext);
+
+	const navigator = (
+		<BlankStackNavigatorInner
+			{...rest}
+			{...(!enableNativeScreens && {
+				DISABLE_NATIVE_SCREENS: true,
+			})}
+			DISABLE_NATIVE_SCREEN_CONTAINER={independent}
+		/>
+	);
 
-		return (
-			<NavigationIndependentTree>
-				<NavigationContainer>
-					<BlankStackContext.Provider value={true}>
-						{navigator}
-					</BlankStackContext.Provider>
-				</NavigationContainer>
-			</NavigationIndependentTree>
-		);
+	if (!independent || isNested) {
+		return navigator;
 	}
 
-	BlankStackNavigator.displayName = independent
-		? "IndependentBlankStackNavigator"
-		: "BlankStackNavigator";
-
-	return BlankStackNavigator;
+	return (
+		<NavigationIndependentTree>
+			<NavigationContainer>
+				<BlankStackContext.Provider value={true}>
+					{navigator}
+				</BlankStackContext.Provider>
+			</NavigationContainer>
+		</NavigationIndependentTree>
+	);
 }
 
-const BlankStackNavigator = createBlankStackNavigatorComponent({
-	independent: false,
-	enableNativeScreens: true,
-});
+BlankStackNavigator.displayName = "BlankStackNavigator";
 
 type BlankStackTypeBag<
 	ParamList extends ParamListBase,
@@ -147,14 +140,13 @@ type BlankStackTypeBag<
  * it participates in the current navigation tree and uses native screen
  * primitives on supported native platforms.
  *
- * Pass {@link BlankStackFactoryOptions} when you need embedded-flow behavior:
+ * Blank stack also accepts navigator-specific props for embedded-flow behavior:
  * - `independent: true` creates an isolated navigator for nested flows
  * - `enableNativeScreens: false` renders the stack with regular views instead
  *   of `react-native-screens`
  *
- * These options are factory-only. Use screen options for per-screen transition
- * behavior, and use factory options when you need to change how the navigator
- * itself is hosted.
+ * In the dynamic API, pass these to `<Stack.Navigator />`.
+ * In the static API, pass them in the same config object as `screens`.
  */
 export function createBlankStackNavigator<
 	const ParamList extends ParamListBase,
@@ -163,42 +155,7 @@ export function createBlankStackNavigator<
 		ParamList,
 		NavigatorID
 	>,
->(): TypedNavigator<TypeBag, StaticConfig<TypeBag>>;
-export function createBlankStackNavigator<
-	const ParamList extends ParamListBase,
-	const NavigatorID extends string | undefined = undefined,
-	const TypeBag extends NavigatorTypeBagBase = BlankStackTypeBag<
-		ParamList,
-		NavigatorID
-	>,
->(
-	/**
-	 * Factory-level hosting options for the blank stack.
-	 */
-	options: BlankStackFactoryOptions,
-): TypedNavigator<TypeBag, StaticConfig<TypeBag>>;
-export function createBlankStackNavigator<
-	const ParamList extends ParamListBase,
-	const NavigatorID extends string | undefined = undefined,
-	const TypeBag extends NavigatorTypeBagBase = BlankStackTypeBag<
-		ParamList,
-		NavigatorID
-	>,
-	const Config extends StaticConfig<TypeBag> &
-		BlankStackFactoryOptions = StaticConfig<TypeBag> & BlankStackFactoryOptions,
+	const Config extends StaticConfig<TypeBag> = StaticConfig<TypeBag>,
 >(config?: Config): TypedNavigator<TypeBag, Config> {
-	const {
-		independent = false,
-		enableNativeScreens = true,
-		...staticConfig
-	} = (config ?? {}) as StaticConfig<TypeBag> & BlankStackFactoryOptions;
-
-	const Navigator = createBlankStackNavigatorComponent({
-		independent,
-		enableNativeScreens,
-	});
-
-	return createNavigatorFactory(Navigator)(
-		(config ? (staticConfig as StaticConfig<TypeBag>) : undefined) as Config,
-	);
+	return createNavigatorFactory(BlankStackNavigator)(config);
 }

package/src/blank-stack/types.ts

@@ -52,10 +52,12 @@ export type BlankStackNavigationHelpers = NavigationHelpers<
 >;
 
 /**
- * Factory-only options for `createBlankStackNavigator`.
+ * Additional props accepted by the blank stack navigator.
  *
- * Use these when you need to change how the blank stack itself is hosted,
- * not how individual screens transition.
+ * These can be passed to `<BlankStack.Navigator />` in the dynamic API, and
+ * they are also supported as top-level keys in static navigator config.
+ *
+ * The exported name is kept for backward compatibility.
  */
 export interface BlankStackFactoryOptions {
 	/**
@@ -120,7 +122,8 @@ export type BlankStackNavigatorProps = DefaultNavigatorOptions<
 	BlankStackNavigationEventMap,
 	BlankStackNavigationProp<ParamListBase>
 > &
-	StackRouterOptions;
+	StackRouterOptions &
+	BlankStackFactoryOptions;
 
 export type BlankStackDescriptor = Descriptor<
 	BlankStackNavigationOptions,

package/src/component-stack/navigators/create-component-stack-navigator.tsx

@@ -98,7 +98,7 @@ function IsolatedComponentStackNavigator(props: ComponentStackNavigatorProps) {
 /**
  * @deprecated Component stack was originally introduced for independent,
  * embedded navigation flows. Blank stack now supports that use case directly
- * via `createBlankStackNavigator({ independent: true })`, with
+ * via navigator props such as `<BlankStack.Navigator independent />`, with
  * `enableNativeScreens` available when you need to switch between native
  * screens and regular views. Prefer blank stack for new work; component stack
  * will be removed in a future release.

package/src/shared/components/create-boundary-component/components/boundary-target.tsx

@@ -0,0 +1,45 @@
+import type React from "react";
+import { memo, useLayoutEffect } from "react";
+import type { View } from "react-native";
+import Animated, { useAnimatedRef } from "react-native-reanimated";
+import {
+	TARGET_OUTSIDE_OWNER_WARNING,
+	useBoundaryOwnerContext,
+} from "../providers/boundary-owner.provider";
+
+type BoundaryTargetProps = React.ComponentProps<typeof Animated.View>;
+
+export const BoundaryTarget = memo(function BoundaryTarget(
+	props: BoundaryTargetProps,
+) {
+	const { style, ...rest } = props;
+	const targetAnimatedRef = useAnimatedRef<View>();
+	const ownerContext = useBoundaryOwnerContext();
+	const isActiveTarget = ownerContext?.activeTargetRef === targetAnimatedRef;
+
+	useLayoutEffect(() => {
+		if (!ownerContext) {
+			if (__DEV__) {
+				console.warn(TARGET_OUTSIDE_OWNER_WARNING);
+			}
+			return;
+		}
+
+		ownerContext.registerTargetRef(targetAnimatedRef);
+		return () => {
+			ownerContext.unregisterTargetRef(targetAnimatedRef);
+		};
+	}, [ownerContext, targetAnimatedRef]);
+
+	return (
+		<Animated.View
+			{...rest}
+			ref={targetAnimatedRef}
+			style={[
+				style,
+				isActiveTarget ? ownerContext.associatedTargetStyles : undefined,
+			]}
+			collapsable={false}
+		/>
+	);
+});

package/src/shared/components/create-boundary-component/create-boundary-component.tsx

@@ -0,0 +1,282 @@
+import {
+	type ComponentType,
+	forwardRef,
+	memo,
+	useCallback,
+	useMemo,
+} from "react";
+import type { View } from "react-native";
+import Animated, {
+	runOnUI,
+	useAnimatedRef,
+	useAnimatedStyle,
+} from "react-native-reanimated";
+import { NO_STYLES } from "../../constants";
+import { useDescriptorDerivations } from "../../providers/screen/descriptors";
+import { useScreenStyles } from "../../providers/screen/styles";
+import { AnimationStore } from "../../stores/animation.store";
+import { BoundStore } from "../../stores/bounds";
+import { prepareStyleForBounds } from "../../utils/bounds/helpers/styles";
+import { useAutoSourceMeasurement } from "./hooks/use-auto-source-measurement";
+import { useBoundaryMeasureAndStore } from "./hooks/use-boundary-measure-and-store";
+import { useBoundaryPresence } from "./hooks/use-boundary-presence";
+import { useGroupActiveMeasurement } from "./hooks/use-group-active-measurement";
+import { useGroupActiveSourceMeasurement } from "./hooks/use-group-active-source-measurement";
+import { useInitialLayoutHandler } from "./hooks/use-initial-layout-handler";
+import { usePendingDestinationMeasurement } from "./hooks/use-pending-destination-measurement";
+import { usePendingDestinationRetryMeasurement } from "./hooks/use-pending-destination-retry-measurement";
+import { useScrollSettledMeasurement } from "./hooks/use-scroll-settled-measurement";
+import {
+	BoundaryOwnerProvider,
+	useBoundaryOwner,
+} from "./providers/boundary-owner.provider";
+import type { BoundaryComponentProps, BoundaryConfigProps } from "./types";
+import { buildBoundaryMatchKey } from "./utils/build-boundary-match-key";
+
+interface CreateBoundaryComponentOptions {
+	alreadyAnimated?: boolean;
+}
+
+export function createBoundaryComponent<P extends object>(
+	Wrapped: ComponentType<P>,
+	options: CreateBoundaryComponentOptions = {},
+) {
+	const { alreadyAnimated = false } = options;
+	const AnimatedComponent = alreadyAnimated
+		? Wrapped
+		: Animated.createAnimatedComponent(Wrapped);
+
+	const Inner = forwardRef<
+		React.ComponentRef<typeof AnimatedComponent>,
+		BoundaryComponentProps<P>
+	>((props, _ref) => {
+		const ownerRef = useAnimatedRef<View>();
+		const {
+			enabled = true,
+			group,
+			id,
+			anchor,
+			scaleMode,
+			target,
+			method,
+			style,
+			onPress,
+			...rest
+		} = props as any;
+
+		const sharedBoundTag = buildBoundaryMatchKey({ group, id });
+
+		const {
+			previousScreenKey: preferredSourceScreenKey,
+			currentScreenKey,
+			nextScreenKey,
+			ancestorKeys,
+			navigatorKey,
+			ancestorNavigatorKeys,
+			hasConfiguredInterpolator,
+		} = useDescriptorDerivations();
+
+		const runtimeEnabled = enabled && hasConfiguredInterpolator;
+		const hasNextScreen = !!nextScreenKey;
+		const shouldUpdateDestination = !hasNextScreen;
+		const boundaryConfig = useMemo<BoundaryConfigProps | undefined>(() => {
+			if (
+				anchor === undefined &&
+				scaleMode === undefined &&
+				target === undefined &&
+				method === undefined
+			) {
+				return undefined;
+			}
+
+			return {
+				anchor,
+				scaleMode,
+				target,
+				method,
+			};
+		}, [anchor, scaleMode, target, method]);
+
+		const isAnimating = AnimationStore.getValue(currentScreenKey, "animating");
+
+		const preparedStyles = useMemo(() => prepareStyleForBounds(style), [style]);
+		const { elementStylesMap } = useScreenStyles();
+
+		const associatedStyles = useAnimatedStyle(() => {
+			"worklet";
+
+			const baseStyle =
+				(elementStylesMap.value[sharedBoundTag]?.style as
+					| Record<string, any>
+					| undefined) ?? (NO_STYLES as Record<string, any>);
+
+			if ("opacity" in baseStyle) {
+				return baseStyle;
+			}
+
+			return { ...baseStyle, opacity: 1 };
+		});
+
+		const associatedStackingStyles = useAnimatedStyle(() => {
+			"worklet";
+			const baseStyle =
+				(elementStylesMap.value[sharedBoundTag]?.style as
+					| Record<string, any>
+					| undefined) ?? (NO_STYLES as Record<string, any>);
+
+			return {
+				zIndex: (baseStyle.zIndex as number | undefined) ?? 0,
+				elevation: (baseStyle.elevation as number | undefined) ?? 0,
+			};
+		});
+
+		const { contextValue, measuredRef, hasActiveTarget } = useBoundaryOwner({
+			ownerRef,
+			associatedTargetStyles: enabled ? associatedStyles : undefined,
+		});
+
+		const maybeMeasureAndStore = useBoundaryMeasureAndStore({
+			enabled,
+			sharedBoundTag,
+			preferredSourceScreenKey,
+			currentScreenKey,
+			ancestorKeys,
+			navigatorKey,
+			ancestorNavigatorKeys,
+			isAnimating,
+			preparedStyles,
+			measuredAnimatedRef: measuredRef,
+		});
+
+		const shouldRunDestinationEffects = runtimeEnabled && !hasNextScreen;
+
+		// Register/unregister this boundary in the presence map so source/destination
+		// matching can resolve across screens (including ancestor relationships).
+		useBoundaryPresence({
+			enabled: runtimeEnabled,
+			sharedBoundTag,
+			currentScreenKey,
+			ancestorKeys,
+			navigatorKey,
+			ancestorNavigatorKeys,
+			boundaryConfig,
+		});
+
+		// On the source screen, capture source bounds when a matching destination
+		// appears on the next screen.
+		useAutoSourceMeasurement({
+			enabled: runtimeEnabled,
+			sharedBoundTag,
+			nextScreenKey,
+			maybeMeasureAndStore,
+		});
+
+		// Primary destination capture: once a pending source link exists for this tag,
+		// measure destination bounds and complete the pair.
+		usePendingDestinationMeasurement({
+			sharedBoundTag,
+			enabled: shouldRunDestinationEffects,
+			expectedSourceScreenKey: preferredSourceScreenKey,
+			maybeMeasureAndStore,
+		});
+
+		// Reliability fallback: retry destination capture during transition progress
+		// when the initial pending-destination attempt happens before layout is ready.
+		usePendingDestinationRetryMeasurement({
+			sharedBoundTag,
+			enabled: shouldRunDestinationEffects,
+			currentScreenKey,
+			expectedSourceScreenKey: preferredSourceScreenKey,
+			animating: isAnimating,
+			maybeMeasureAndStore,
+		});
+
+		// Grouped boundaries (e.g. paged/detail UIs): re-measure when this boundary
+		// becomes the active member so destination bounds stay accurate.
+		useGroupActiveMeasurement({
+			enabled: runtimeEnabled,
+			group,
+			id,
+			currentScreenKey,
+			shouldUpdateDestination,
+			maybeMeasureAndStore,
+		});
+
+		// Source-side grouped retargeting: when an unfocused/source boundary
+		// becomes the active member, refresh its snapshot and source link so
+		// close transitions do not use stale pre-scroll geometry.
+		useGroupActiveSourceMeasurement({
+			enabled: runtimeEnabled,
+			group,
+			id,
+			hasNextScreen,
+			isAnimating,
+			maybeMeasureAndStore,
+		});
+
+		// While idle on source screens, re-measure after scroll settles so a later
+		// close transition starts from up-to-date source geometry.
+		useScrollSettledMeasurement({
+			enabled: runtimeEnabled,
+			group,
+			hasNextScreen,
+			isAnimating,
+			maybeMeasureAndStore,
+		});
+
+		// Destination mount-time capture path: onLayout schedules a one-time UI-thread
+		// initial measurement when transitions are active.
+		useInitialLayoutHandler({
+			enabled: runtimeEnabled,
+			sharedBoundTag,
+			currentScreenKey,
+			ancestorKeys,
+			expectedSourceScreenKey: preferredSourceScreenKey,
+			maybeMeasureAndStore,
+		});
+
+		const handlePress = useCallback(
+			(...args: unknown[]) => {
+				// Press path has priority: capture source before user onPress/navigation.
+				if (group) {
+					runOnUI(BoundStore.setGroupActiveId)(group, String(id));
+				}
+				runOnUI(maybeMeasureAndStore)({ intent: "capture-source" });
+
+				if (typeof onPress === "function") {
+					onPress(...args);
+				}
+			},
+			[group, id, maybeMeasureAndStore, onPress],
+		);
+
+		const resolvedOnPress =
+			typeof onPress === "function" ? handlePress : undefined;
+
+		return (
+			<BoundaryOwnerProvider value={contextValue}>
+				<AnimatedComponent
+					{...rest}
+					ref={ownerRef}
+					style={[
+						style,
+						enabled
+							? hasActiveTarget
+								? associatedStackingStyles
+								: associatedStyles
+							: undefined,
+					]}
+					onPress={resolvedOnPress}
+					collapsable={false}
+				/>
+			</BoundaryOwnerProvider>
+		);
+	});
+
+	return memo(Inner) as unknown as React.MemoExoticComponent<
+		React.ForwardRefExoticComponent<
+			BoundaryComponentProps<P> &
+				React.RefAttributes<React.ComponentRef<typeof Wrapped>>
+		>
+	>;
+}

package/src/shared/components/create-boundary-component/hooks/helpers/measurement-rules.ts

@@ -193,14 +193,9 @@ export const resolveInitialLayoutMeasurementIntent = (params: {
 
 	if (!enabled) return null;
 	if (!hasSharedBoundTag || hasMeasuredOnLayout) return null;
+	if (!isAnyAnimating) return null;
 
-	if (!isAnyAnimating) {
-		return "snapshot-only";
-	}
-
-	return hasPendingLinkFromSource
-		? ["snapshot-only", "complete-destination"]
-		: "snapshot-only";
+	return hasPendingLinkFromSource ? "complete-destination" : null;
 };
 
 export const resolveGroupActiveMeasurementAction = (params: {

package/src/shared/components/create-boundary-component/hooks/use-boundary-measure-and-store.ts

@@ -7,6 +7,7 @@ import {
 	type StyleProps,
 } from "react-native-reanimated";
 import useStableCallbackValue from "../../../hooks/use-stable-callback-value";
+import { useLayoutAnchorContext } from "../../../providers/layout-anchor.provider";
 import { BoundStore } from "../../../stores/bounds";
 import { applyMeasuredBoundsWrites } from "../../../stores/bounds/helpers/apply-measured-bounds-writes";
 import { resolvePendingSourceKey } from "../helpers/resolve-pending-source-key";
@@ -16,11 +17,6 @@ import {
 	resolveMeasurementWritePlan,
 } from "./helpers/measurement-rules";
 
-type LayoutAnchor = {
-	correctMeasurement: (measured: MeasuredDimensions) => MeasuredDimensions;
-	isMeasurementInViewport?: (measured: MeasuredDimensions) => boolean;
-} | null;
-
 const SNAPSHOT_EPSILON = 0.5;
 
 const areMeasurementsEqual = (
@@ -49,8 +45,7 @@ export const useBoundaryMeasureAndStore = (params: {
 	ancestorNavigatorKeys?: string[];
 	isAnimating: SharedValue<number>;
 	preparedStyles: StyleProps;
-	animatedRef: AnimatedRef<View>;
-	layoutAnchor: LayoutAnchor;
+	measuredAnimatedRef: AnimatedRef<View>;
 }) => {
 	const {
 		enabled,
@@ -62,10 +57,11 @@ export const useBoundaryMeasureAndStore = (params: {
 		ancestorNavigatorKeys,
 		isAnimating,
 		preparedStyles,
-		animatedRef,
-		layoutAnchor,
+		measuredAnimatedRef,
 	} = params;
 
+	const layoutAnchor = useLayoutAnchorContext();
+
 	return useStableCallbackValue(
 		({ intent }: MaybeMeasureAndStoreParams = {}) => {
 			"worklet";
@@ -127,7 +123,7 @@ export const useBoundaryMeasureAndStore = (params: {
 				return;
 			}
 
-			const measured = measure(animatedRef);
+			const measured = measure(measuredAnimatedRef);
 			if (!measured) return;
 
 			const correctedMeasured = layoutAnchor

package/src/shared/components/create-boundary-component/hooks/use-pending-destination-retry-measurement.ts

@@ -3,6 +3,7 @@ import {
 	useAnimatedReaction,
 	useSharedValue,
 } from "react-native-reanimated";
+import { AnimationStore } from "../../../stores/animation.store";
 import { BoundStore } from "../../../stores/bounds";
 import { resolvePendingSourceKey } from "../helpers/resolve-pending-source-key";
 import type { MaybeMeasureAndStoreParams } from "../types";
@@ -13,7 +14,6 @@ export const usePendingDestinationRetryMeasurement = (params: {
 	enabled: boolean;
 	currentScreenKey: string;
 	expectedSourceScreenKey?: string;
-	progress: SharedValue<number>;
 	animating: SharedValue<number>;
 	maybeMeasureAndStore: (options: MaybeMeasureAndStoreParams) => void;
 }) => {
@@ -22,11 +22,12 @@ export const usePendingDestinationRetryMeasurement = (params: {
 		enabled,
 		currentScreenKey,
 		expectedSourceScreenKey,
-		progress,
 		animating,
 		maybeMeasureAndStore,
 	} = params;
 
+	const progress = AnimationStore.getValue(currentScreenKey, "progress");
+
 	const retryCount = useSharedValue(0);
 	const MAX_RETRIES = 4;
 	const RETRY_PROGRESS_BUCKETS = 8;