react-native-screen-transitions 3.4.0-alpha.0 → 3.4.0-alpha.2

package/src/blank-stack/types.ts

@@ -51,9 +51,38 @@ export type BlankStackNavigationHelpers = NavigationHelpers<
 	BlankStackNavigationEventMap
 >;
 
-type BlankStackNavigationConfig = {
-	DISABLE_NATIVE_SCREENS?: boolean;
-};
+/**
+ * Factory-only options for `createBlankStackNavigator`.
+ *
+ * Use these when you need to change how the blank stack itself is hosted,
+ * not how individual screens transition.
+ */
+export interface BlankStackFactoryOptions {
+	/**
+	 * Creates an isolated navigation tree for embedded flows.
+	 *
+	 * Use this when the blank stack needs to live inside another screen or host
+	 * application without joining the parent React Navigation tree.
+	 *
+	 * When enabled, the navigator:
+	 * - wraps itself in `NavigationIndependentTree` + `NavigationContainer`
+	 * - skips the shared native `ScreenContainer`
+	 *
+	 * Leave this disabled for normal top-level app stacks.
+	 */
+	independent?: boolean;
+	/**
+	 * Enables native screen primitives on supported native platforms.
+	 *
+	 * Use this when you want the embedded blank stack to keep `react-native-screens`
+	 * behavior such as native activity state and freezing.
+	 *
+	 * Set this to `false` when you want the blank stack to render with regular
+	 * views instead of native screen primitives. This is useful for embedded
+	 * flows where plain views are a better fit than native screen layering.
+	 */
+	enableNativeScreens?: boolean;
+}
 
 /**
  * Props passed to overlay components in blank-stack.
@@ -91,8 +120,7 @@ export type BlankStackNavigatorProps = DefaultNavigatorOptions<
 	BlankStackNavigationEventMap,
 	BlankStackNavigationProp<ParamListBase>
 > &
-	StackRouterOptions &
-	BlankStackNavigationConfig;
+	StackRouterOptions;
 
 export type BlankStackDescriptor = Descriptor<
 	BlankStackNavigationOptions,

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

@@ -95,6 +95,14 @@ 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
+ * `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.
+ */
 export function createComponentStackNavigator<
 	const ParamList extends ParamListBase,
 	const NavigatorID extends string | undefined = undefined,

package/src/shared/animation/snap-to.ts

@@ -11,7 +11,18 @@ const getSortedSnapPoints = (
 ): number[] | null => {
 	const snapPoints = descriptor.options?.snapPoints;
 	if (!snapPoints || snapPoints.length === 0) return null;
-	return [...snapPoints].sort((a, b) => a - b);
+
+	// Resolve 'auto' to the measured fraction stored in AnimationStore
+	const autoVal = AnimationStore.getAnimation(
+		descriptor.route.key,
+		"autoSnapPoint",
+	).value;
+
+	const resolved = snapPoints
+		.map((p) => (p === "auto" ? autoVal : p))
+		.filter((p): p is number => typeof p === "number" && p > 0);
+
+	return resolved.length > 0 ? resolved.sort((a, b) => a - b) : null;
 };
 
 export function snapDescriptorToIndex(

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

@@ -0,0 +1,258 @@
+import type { MeasurementIntent } from "../../types";
+
+type PresenceLikeEntry = {
+	count: number;
+	ancestorKeys?: string[];
+};
+
+export type MeasurementIntentFlags = {
+	captureSource: boolean;
+	completeDestination: boolean;
+	refreshSource: boolean;
+	refreshDestination: boolean;
+	snapshotOnly: boolean;
+};
+
+export type MeasurementWritePlan = {
+	captureSource: boolean;
+	completeDestination: boolean;
+	refreshSource: boolean;
+	refreshDestination: boolean;
+	registerSnapshot: boolean;
+	writesAny: boolean;
+	wantsDestinationWrite: boolean;
+};
+
+export type DeferredMeasurementAction =
+	| "clear-pending"
+	| "queue-or-flush"
+	| "noop";
+
+export const getMeasurementIntentFlags = (
+	intent?: MeasurementIntent | readonly MeasurementIntent[],
+): MeasurementIntentFlags => {
+	"worklet";
+	const flags: MeasurementIntentFlags = {
+		captureSource: false,
+		completeDestination: false,
+		refreshSource: false,
+		refreshDestination: false,
+		snapshotOnly: false,
+	};
+
+	if (!intent) {
+		return flags;
+	}
+
+	const intents = Array.isArray(intent) ? intent : [intent];
+
+	for (let i = 0; i < intents.length; i++) {
+		switch (intents[i]) {
+			case "capture-source":
+				flags.captureSource = true;
+				break;
+			case "complete-destination":
+				flags.completeDestination = true;
+				break;
+			case "refresh-source":
+				flags.refreshSource = true;
+				break;
+			case "refresh-destination":
+				flags.refreshDestination = true;
+				break;
+			case "snapshot-only":
+				flags.snapshotOnly = true;
+				break;
+		}
+	}
+
+	return flags;
+};
+
+export const resolveMeasurementWritePlan = (params: {
+	intents: MeasurementIntentFlags;
+	hasPendingLink: boolean;
+	hasSourceLink: boolean;
+	hasDestinationLink: boolean;
+}): MeasurementWritePlan => {
+	"worklet";
+	const { intents, hasPendingLink, hasSourceLink, hasDestinationLink } = params;
+
+	const captureSource = intents.captureSource;
+	const completeDestination = intents.completeDestination && hasPendingLink;
+	const refreshSource = intents.refreshSource && hasSourceLink;
+	const refreshDestination =
+		intents.refreshDestination && (hasDestinationLink || hasPendingLink);
+	const registerSnapshot = intents.snapshotOnly;
+	const writesAny =
+		registerSnapshot ||
+		captureSource ||
+		completeDestination ||
+		refreshSource ||
+		refreshDestination;
+
+	return {
+		captureSource,
+		completeDestination,
+		refreshSource,
+		refreshDestination,
+		registerSnapshot,
+		writesAny,
+		wantsDestinationWrite: completeDestination || refreshDestination,
+	};
+};
+
+export const resolveAutoSourceCaptureSignal = (params: {
+	enabled: boolean;
+	nextScreenKey?: string;
+	tagPresence?: Record<string, PresenceLikeEntry>;
+}): string | 0 => {
+	"worklet";
+	const { enabled, nextScreenKey, tagPresence } = params;
+	if (!enabled) return 0;
+	if (!nextScreenKey) return 0;
+	if (!tagPresence) return 0;
+
+	const direct = tagPresence[nextScreenKey];
+	if (direct && direct.count > 0) return nextScreenKey;
+
+	for (const screenKey in tagPresence) {
+		const entry = tagPresence[screenKey];
+		if (entry.ancestorKeys?.includes(nextScreenKey)) {
+			return nextScreenKey;
+		}
+	}
+
+	return 0;
+};
+
+export const resolvePendingDestinationCaptureSignal = (params: {
+	enabled: boolean;
+	resolvedSourceKey?: string | null;
+	hasPendingLinkFromSource: boolean;
+}): string | 0 => {
+	"worklet";
+	const { enabled, resolvedSourceKey, hasPendingLinkFromSource } = params;
+	if (!enabled) return 0;
+	if (!resolvedSourceKey) return 0;
+	return hasPendingLinkFromSource ? resolvedSourceKey : 0;
+};
+
+export const resolvePendingDestinationRetrySignal = (params: {
+	enabled: boolean;
+	retryCount: number;
+	maxRetries: number;
+	isAnimating: boolean;
+	hasDestinationLink: boolean;
+	progress: number;
+	retryProgressMax: number;
+	retryProgressBuckets: number;
+	resolvedSourceKey?: string | null;
+	hasPendingLinkFromSource: boolean;
+}): number => {
+	"worklet";
+	const {
+		enabled,
+		retryCount,
+		maxRetries,
+		isAnimating,
+		hasDestinationLink,
+		progress,
+		retryProgressMax,
+		retryProgressBuckets,
+		resolvedSourceKey,
+		hasPendingLinkFromSource,
+	} = params;
+
+	if (!enabled) return 0;
+	if (retryCount >= maxRetries) return 0;
+	if (!isAnimating) return 0;
+	if (hasDestinationLink) return 0;
+	if (progress <= 0 || progress >= retryProgressMax) return 0;
+	if (!resolvedSourceKey) return 0;
+	if (!hasPendingLinkFromSource) return 0;
+
+	return Math.floor(progress * retryProgressBuckets) + 1;
+};
+
+export const resolveInitialLayoutMeasurementIntent = (params: {
+	enabled: boolean;
+	hasSharedBoundTag: boolean;
+	hasMeasuredOnLayout: boolean;
+	isAnyAnimating: boolean;
+	hasPendingLinkFromSource: boolean;
+}): MeasurementIntent | readonly MeasurementIntent[] | null => {
+	"worklet";
+	const {
+		enabled,
+		hasSharedBoundTag,
+		hasMeasuredOnLayout,
+		isAnyAnimating,
+		hasPendingLinkFromSource,
+	} = params;
+
+	if (!enabled) return null;
+	if (!hasSharedBoundTag || hasMeasuredOnLayout) return null;
+
+	if (!isAnyAnimating) {
+		return "snapshot-only";
+	}
+
+	return hasPendingLinkFromSource
+		? ["snapshot-only", "complete-destination"]
+		: "snapshot-only";
+};
+
+export const resolveGroupActiveMeasurementAction = (params: {
+	enabled: boolean;
+	isEligible: boolean;
+	memberId: string;
+	activeId: string | null;
+	previousActiveId: string | null;
+}): DeferredMeasurementAction => {
+	"worklet";
+	const { enabled, isEligible, memberId, activeId, previousActiveId } = params;
+
+	if (!enabled || !isEligible) return "noop";
+	if (activeId !== memberId) return "clear-pending";
+	if (activeId === memberId && activeId !== previousActiveId) {
+		return "queue-or-flush";
+	}
+	return "noop";
+};
+
+export const canFlushGroupActiveMeasurement = (params: {
+	enabled: boolean;
+	isEligible: boolean;
+	memberId: string;
+	activeId: string | null;
+}): boolean => {
+	"worklet";
+	const { enabled, isEligible, memberId, activeId } = params;
+	if (!enabled || !isEligible) return false;
+	return activeId === memberId;
+};
+
+export const shouldTriggerScrollSettledRefresh = (params: {
+	enabled: boolean;
+	group: string | undefined;
+	hasNextScreen: boolean;
+	hasSettledSignal: boolean;
+	signal: number;
+	previousSignal: number | null;
+}): boolean => {
+	"worklet";
+	const {
+		enabled,
+		group,
+		hasNextScreen,
+		hasSettledSignal,
+		signal,
+		previousSignal,
+	} = params;
+
+	if (!enabled) return false;
+	if (!group || !hasNextScreen || !hasSettledSignal) return false;
+	if (signal === 0 || signal === previousSignal) return false;
+	return true;
+};

package/src/shared/components/create-boundary-component/hooks/use-auto-source-measurement.ts

@@ -1,6 +1,7 @@
 import { useAnimatedReaction } from "react-native-reanimated";
 import { BoundStore } from "../../../stores/bounds";
 import type { MaybeMeasureAndStoreParams } from "../types";
+import { resolveAutoSourceCaptureSignal } from "./helpers/measurement-rules";
 
 export const useAutoSourceMeasurement = (params: {
 	enabled: boolean;
@@ -15,29 +16,18 @@ export const useAutoSourceMeasurement = (params: {
 	useAnimatedReaction(
 		() => {
 			"worklet";
-			if (!enabled) return 0;
-			if (!nextScreenKey) return 0;
-			const tagPresence = boundaryPresence.value[sharedBoundTag];
-			if (!tagPresence) return 0;
-
-			const direct = tagPresence[nextScreenKey];
-			if (direct && direct.count > 0) return nextScreenKey;
-
-			for (const screenKey in tagPresence) {
-				const entry = tagPresence[screenKey];
-				if (entry.ancestorKeys?.includes(nextScreenKey)) {
-					return nextScreenKey;
-				}
-			}
-
-			return 0;
+			return resolveAutoSourceCaptureSignal({
+				enabled,
+				nextScreenKey,
+				tagPresence: boundaryPresence.value[sharedBoundTag],
+			});
 		},
 		(captureSignal, previousCaptureSignal) => {
 			"worklet";
 			if (!enabled) return;
 			if (!nextScreenKey) return;
 			if (!captureSignal || captureSignal === previousCaptureSignal) return;
-			maybeMeasureAndStore({ shouldSetSource: true });
+			maybeMeasureAndStore({ intent: "capture-source" });
 		},
 		[
 			enabled,

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

@@ -3,14 +3,18 @@ import {
 	type AnimatedRef,
 	type MeasuredDimensions,
 	measure,
+	type SharedValue,
 	type StyleProps,
 } from "react-native-reanimated";
 import useStableCallbackValue from "../../../hooks/use-stable-callback-value";
-import type { AnimationStore } from "../../../stores/animation.store";
 import { BoundStore } from "../../../stores/bounds";
 import { applyMeasuredBoundsWrites } from "../../../stores/bounds/helpers/apply-measured-bounds-writes";
 import { resolvePendingSourceKey } from "../helpers/resolve-pending-source-key";
 import type { MaybeMeasureAndStoreParams } from "../types";
+import {
+	getMeasurementIntentFlags,
+	resolveMeasurementWritePlan,
+} from "./helpers/measurement-rules";
 
 type LayoutAnchor = {
 	correctMeasurement: (measured: MeasuredDimensions) => MeasuredDimensions;
@@ -43,7 +47,7 @@ export const useBoundaryMeasureAndStore = (params: {
 	ancestorKeys: string[];
 	navigatorKey?: string;
 	ancestorNavigatorKeys?: string[];
-	isAnimating: ReturnType<typeof AnimationStore.getRouteAnimation>;
+	isAnimating: SharedValue<number>;
 	preparedStyles: StyleProps;
 	animatedRef: AnimatedRef<View>;
 	layoutAnchor: LayoutAnchor;
@@ -63,20 +67,17 @@ export const useBoundaryMeasureAndStore = (params: {
 	} = params;
 
 	return useStableCallbackValue(
-		({
-			shouldSetSource,
-			shouldSetDestination,
-			shouldUpdateSource,
-			shouldUpdateDestination,
-		}: MaybeMeasureAndStoreParams = {}) => {
+		({ intent }: MaybeMeasureAndStoreParams = {}) => {
 			"worklet";
 			if (!enabled) return;
 
+			const intents = getMeasurementIntentFlags(intent);
+
 			const expectedSourceScreenKey: string | undefined =
 				resolvePendingSourceKey(sharedBoundTag, preferredSourceScreenKey) ||
 				undefined;
 
-			if (shouldSetSource && isAnimating.get()) {
+			if (intents.captureSource && isAnimating.get()) {
 				const existing = BoundStore.getSnapshot(
 					sharedBoundTag,
 					currentScreenKey,
@@ -115,18 +116,14 @@ export const useBoundaryMeasureAndStore = (params: {
 				currentScreenKey,
 			);
 
-			const canSetSource = !!shouldSetSource;
-			const canSetDestination = !!shouldSetDestination && hasPendingLink;
-			const canUpdateSource = !!shouldUpdateSource && hasSourceLink;
-			const canUpdateDestination =
-				!!shouldUpdateDestination && (hasDestinationLink || hasPendingLink);
+			const writePlan = resolveMeasurementWritePlan({
+				intents,
+				hasPendingLink,
+				hasSourceLink,
+				hasDestinationLink,
+			});
 
-			if (
-				!canSetSource &&
-				!canSetDestination &&
-				!canUpdateSource &&
-				!canUpdateDestination
-			) {
+			if (!writePlan.writesAny) {
 				return;
 			}
 
@@ -137,14 +134,17 @@ export const useBoundaryMeasureAndStore = (params: {
 				? layoutAnchor.correctMeasurement(measured)
 				: measured;
 
-			const wantsDestinationWrite = canSetDestination || canUpdateDestination;
 			const destinationInViewport =
-				!wantsDestinationWrite ||
+				!writePlan.wantsDestinationWrite ||
 				!layoutAnchor ||
 				!layoutAnchor.isMeasurementInViewport ||
 				layoutAnchor.isMeasurementInViewport(correctedMeasured);
 
-			if (!destinationInViewport && !canSetSource && !canUpdateSource) {
+			if (
+				!destinationInViewport &&
+				!writePlan.captureSource &&
+				!writePlan.refreshSource
+			) {
 				return;
 			}
 
@@ -155,6 +155,13 @@ export const useBoundaryMeasureAndStore = (params: {
 			const hasSnapshotChanged =
 				!existingSnapshot ||
 				!areMeasurementsEqual(existingSnapshot.bounds, correctedMeasured);
+			const shouldWriteSnapshot =
+				hasSnapshotChanged &&
+				(writePlan.registerSnapshot ||
+					writePlan.captureSource ||
+					writePlan.completeDestination ||
+					writePlan.refreshSource ||
+					writePlan.refreshDestination);
 
 			applyMeasuredBoundsWrites({
 				sharedBoundTag,
@@ -165,12 +172,15 @@ export const useBoundaryMeasureAndStore = (params: {
 				navigatorKey,
 				ancestorNavigatorKeys,
 				expectedSourceScreenKey,
-				shouldRegisterSnapshot: hasSnapshotChanged,
-				shouldSetSource: canSetSource,
-				shouldUpdateSource: canUpdateSource && hasSnapshotChanged,
+				shouldRegisterSnapshot: shouldWriteSnapshot,
+				shouldSetSource: writePlan.captureSource,
+				shouldUpdateSource: writePlan.refreshSource && hasSnapshotChanged,
 				shouldUpdateDestination:
-					canUpdateDestination && destinationInViewport && hasSnapshotChanged,
-				shouldSetDestination: canSetDestination && destinationInViewport,
+					writePlan.refreshDestination &&
+					destinationInViewport &&
+					hasSnapshotChanged,
+				shouldSetDestination:
+					writePlan.completeDestination && destinationInViewport,
 			});
 		},
 	);

package/src/shared/components/create-boundary-component/hooks/use-deferred-measurement-trigger.ts

@@ -0,0 +1,58 @@
+import { useCallback } from "react";
+import {
+	type SharedValue,
+	useAnimatedReaction,
+	useSharedValue,
+} from "react-native-reanimated";
+
+export const useDeferredMeasurementTrigger = (params: {
+	enabled: boolean;
+	isAnimating: SharedValue<number>;
+	canFlush?: () => boolean;
+	onFlush: () => void;
+}) => {
+	const { enabled, isAnimating, canFlush, onFlush } = params;
+	const hasPendingMeasurement = useSharedValue(false);
+
+	const clearPendingMeasurement = useCallback(() => {
+		"worklet";
+		hasPendingMeasurement.value = false;
+	}, [hasPendingMeasurement]);
+
+	const queueOrFlushMeasurement = useCallback(() => {
+		"worklet";
+		if (!enabled) return;
+
+		if (isAnimating.value) {
+			hasPendingMeasurement.value = true;
+			return;
+		}
+
+		hasPendingMeasurement.value = false;
+		onFlush();
+	}, [enabled, isAnimating, hasPendingMeasurement, onFlush]);
+
+	useAnimatedReaction(
+		() => {
+			"worklet";
+			if (!enabled) return false;
+			if (!hasPendingMeasurement.value) return false;
+			if (isAnimating.value) return false;
+			return canFlush ? canFlush() : true;
+		},
+		(shouldFlush, previousShouldFlush) => {
+			"worklet";
+			if (!enabled) return;
+			if (!shouldFlush || shouldFlush === previousShouldFlush) return;
+
+			hasPendingMeasurement.value = false;
+			onFlush();
+		},
+		[enabled, isAnimating, hasPendingMeasurement, canFlush, onFlush],
+	);
+
+	return {
+		clearPendingMeasurement,
+		queueOrFlushMeasurement,
+	};
+};

package/src/shared/components/create-boundary-component/hooks/use-group-active-measurement.ts

@@ -1,7 +1,11 @@
-import { useAnimatedReaction } from "react-native-reanimated";
-import type { AnimationStore } from "../../../stores/animation.store";
+import { type SharedValue, useAnimatedReaction } from "react-native-reanimated";
 import { BoundStore } from "../../../stores/bounds";
 import type { BoundaryId, MaybeMeasureAndStoreParams } from "../types";
+import {
+	canFlushGroupActiveMeasurement,
+	resolveGroupActiveMeasurementAction,
+} from "./helpers/measurement-rules";
+import { useDeferredMeasurementTrigger } from "./use-deferred-measurement-trigger";
 
 /**
  * Watches the group's active id in the BoundStore.
@@ -15,7 +19,7 @@ export const useGroupActiveMeasurement = (params: {
 	group: string | undefined;
 	id: BoundaryId;
 	shouldUpdateDestination: boolean;
-	isAnimating: ReturnType<typeof AnimationStore.getRouteAnimation>;
+	isAnimating: SharedValue<number>;
 	maybeMeasureAndStore: (options: MaybeMeasureAndStoreParams) => void;
 }) => {
 	const {
@@ -29,6 +33,24 @@ export const useGroupActiveMeasurement = (params: {
 	const idStr = String(id);
 
 	const allGroups = BoundStore.getGroups();
+	const { clearPendingMeasurement, queueOrFlushMeasurement } =
+		useDeferredMeasurementTrigger({
+			enabled,
+			isAnimating,
+			canFlush: () => {
+				"worklet";
+				return canFlushGroupActiveMeasurement({
+					enabled,
+					isEligible: !!group && shouldUpdateDestination,
+					memberId: idStr,
+					activeId: group ? (allGroups.value[group]?.activeId ?? null) : null,
+				});
+			},
+			onFlush: () => {
+				"worklet";
+				maybeMeasureAndStore({ intent: "refresh-destination" });
+			},
+		});
 
 	useAnimatedReaction(
 		() => {
@@ -39,12 +61,21 @@ export const useGroupActiveMeasurement = (params: {
 		},
 		(activeId, previousActiveId) => {
 			"worklet";
-			if (!enabled) return;
-			if (!group || !shouldUpdateDestination) return;
-			if (isAnimating.value) return;
+			const action = resolveGroupActiveMeasurementAction({
+				enabled,
+				isEligible: !!group && shouldUpdateDestination,
+				memberId: idStr,
+				activeId,
+				previousActiveId,
+			});
 
-			if (activeId === idStr && activeId !== previousActiveId) {
-				maybeMeasureAndStore({ shouldUpdateDestination: true });
+			if (action === "clear-pending") {
+				clearPendingMeasurement();
+				return;
+			}
+
+			if (action === "queue-or-flush") {
+				queueOrFlushMeasurement();
 			}
 		},
 		[
@@ -52,8 +83,8 @@ export const useGroupActiveMeasurement = (params: {
 			group,
 			idStr,
 			shouldUpdateDestination,
-			isAnimating,
-			maybeMeasureAndStore,
+			clearPendingMeasurement,
+			queueOrFlushMeasurement,
 		],
 	);
 };