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

package/src/shared/stores/system.store.ts

@@ -0,0 +1,44 @@
+import {
+	cancelAnimation,
+	makeMutable,
+	type SharedValue,
+} from "react-native-reanimated";
+import type { Layout } from "../types/screen.types";
+import { createStore } from "../utils/create-store";
+
+export type SystemStoreMap = {
+	targetProgress: SharedValue<number>;
+
+	/**
+	 * Resolved fraction (contentHeight / screenHeight) for the 'auto' snap point. -1 = not yet measured.
+	 */
+	resolvedAutoSnapPoint: SharedValue<number>;
+
+	/**
+	 * Intrinsic measured content layout from the screen container wrapper.
+	 */
+	measuredContentLayout: SharedValue<Layout | null>;
+};
+
+function createSystemBag(): SystemStoreMap {
+	return {
+		targetProgress: makeMutable(1),
+		resolvedAutoSnapPoint: makeMutable(-1),
+		measuredContentLayout: makeMutable<Layout | null>(null),
+	};
+}
+
+/**
+ * Route-keyed internal engine state that should not be treated as public screen
+ * animation data. These values support runtime measurement and orchestration,
+ * such as resolved auto snap points, measured content layout, and the current
+ * animation target progress. This could possibly grow in the future.
+ */
+export const SystemStore = createStore<SystemStoreMap>({
+	createBag: createSystemBag,
+	disposeBag: (bag) => {
+		cancelAnimation(bag.targetProgress);
+		cancelAnimation(bag.resolvedAutoSnapPoint);
+		cancelAnimation(bag.measuredContentLayout);
+	},
+});

package/src/shared/types/animation.types.ts

@@ -77,6 +77,33 @@ export type ScreenTransitionState = {
 	 * The route object for this screen.
 	 */
 	route: BaseStackRoute;
+
+	/**
+	 * Layout measurements for this specific screen.
+	 */
+	layouts: {
+		/**
+		 * The `width` and `height` of the screen container.
+		 */
+		screen: Layout;
+		/**
+		 * The intrinsic measured content wrapper layout when available.
+		 *
+		 * This is currently populated for the measured screen-container path used by
+		 * auto snap-point sizing. It is undefined until a real measurement exists.
+		 */
+		content?: Layout;
+	};
+
+	/**
+	 * Animated index of this screen's current snap point.
+	 * Interpolates between indices during gestures/animations.
+	 * - Returns -1 if no snap points are defined
+	 * - Returns 0 when at or below first snap point
+	 * - Returns fractional values between snap points (e.g., 1.5 = halfway between snap 1 and 2)
+	 * - Returns length-1 when at or above last snap point
+	 */
+	snapIndex: number;
 };
 
 export interface ScreenInterpolationProps {
@@ -97,6 +124,8 @@ export interface ScreenInterpolationProps {
 
 	/**
 	 * Layout measurements for the screen.
+	 *
+	 * @deprecated Use `current.layouts` instead.
 	 */
 	layouts: {
 		/**
@@ -142,11 +171,8 @@ export interface ScreenInterpolationProps {
 
 	/**
 	 * Animated index of the current snap point.
-	 * Interpolates between indices during gestures/animations.
-	 * - Returns -1 if no snap points are defined
-	 * - Returns 0 when at or below first snap point
-	 * - Returns fractional values between snap points (e.g., 1.5 = halfway between snap 1 and 2)
-	 * - Returns length-1 when at or above last snap point
+	 *
+	 * @deprecated Use `current.snapIndex` instead.
 	 */
 	snapIndex: number;
 
@@ -168,13 +194,19 @@ export interface ScreenInterpolationProps {
 }
 
 /**
- * Returning `null` explicitly defers rendering of the screen's visual subtree
- * for the current frame. Returning an object applies transition styles
- * immediately.
+ * Explicit signal for hiding a screen's visual subtree until the interpolator
+ * becomes ready for the current transition frame.
+ */
+export type DeferredScreenStyleSignal = "defer";
+
+/**
+ * Returning `'defer'` explicitly hides the screen's visual subtree until the
+ * transition is ready. Returning `null`, `undefined`, or `{}` applies no
+ * transition styles for the current frame.
  */
 export type ScreenStyleInterpolator = (
 	props: ScreenInterpolationProps,
-) => TransitionInterpolatedStyle | null;
+) => TransitionInterpolatedStyle | DeferredScreenStyleSignal | null | undefined;
 
 /**
  * Animated style properties with full autocomplete.

package/src/shared/types/bounds.types.ts

@@ -1,13 +1,19 @@
 import type { MeasuredDimensions, StyleProps } from "react-native-reanimated";
+import {
+	NAVIGATION_MASK_CONTAINER_STYLE_ID,
+	NAVIGATION_MASK_ELEMENT_STYLE_ID,
+} from "../constants";
 import type { Snapshot } from "../stores/bounds";
 import type {
 	BoundId,
-	BoundsAnchor,
 	BoundsOptions,
 	BoundsOptionsResult,
-	BoundsScaleMode,
 } from "../utils/bounds/types/options";
-import type { TransitionInterpolatedStyle } from "./animation.types";
+import type {
+	ScreenInterpolationProps,
+	TransitionInterpolatedStyle,
+	TransitionSlotStyle,
+} from "./animation.types";
 
 /**
  * Target style computation.
@@ -29,32 +35,19 @@ export type BoundsLink = {
 };
 
 export type BoundsNavigationZoomOptions = {
-	anchor?: BoundsAnchor;
-	scaleMode?: BoundsScaleMode;
 	target?: "bound" | "fullscreen" | MeasuredDimensions;
-	mask?: {
-		borderRadius?: number | "auto" | { from?: number; to?: number };
-		borderTopLeftRadius?: number | "auto" | { from?: number; to?: number };
-		borderTopRightRadius?: number | "auto" | { from?: number; to?: number };
-		borderBottomLeftRadius?: number | "auto" | { from?: number; to?: number };
-		borderBottomRightRadius?: number | "auto" | { from?: number; to?: number };
-		borderCurve?: "circular" | "continuous";
-		outset?:
-			| number
-			| { top?: number; right?: number; bottom?: number; left?: number };
-	};
-	motion?: {
-		dragResistance?: number;
-		dragDirectionalScaleMin?: number;
-	};
-	/**
-	 * @deprecated Use `mask.borderRadius` instead.
-	 */
-	maskBorderRadius?: number;
+	DEBUG?: boolean;
+	borderRadius?: number;
+};
+
+export type BoundsNavigationZoomStyle = TransitionInterpolatedStyle & {
+	content?: TransitionSlotStyle;
+	[NAVIGATION_MASK_CONTAINER_STYLE_ID]?: TransitionSlotStyle;
+	[NAVIGATION_MASK_ELEMENT_STYLE_ID]?: TransitionSlotStyle;
 };
 
 export type BoundsNavigationAccessor = {
-	zoom: (options?: BoundsNavigationZoomOptions) => TransitionInterpolatedStyle;
+	zoom: (options?: BoundsNavigationZoomOptions) => BoundsNavigationZoomStyle;
 };
 
 type BoundsBoundNavigationAccessor = {
@@ -80,3 +73,10 @@ export type BoundsAccessor = {
 		fallback?: number,
 	) => number;
 };
+
+export type BoundsInterpolationProps = Omit<
+	ScreenInterpolationProps,
+	"bounds"
+> & {
+	navigationMaskEnabled?: boolean;
+};

package/src/shared/types/index.ts

@@ -2,6 +2,7 @@ export { FALSE, TRUE } from "../constants";
 export type {
 	AnimatedViewStyle,
 	AnimationConfig,
+	DeferredScreenStyleSignal,
 	ScreenInterpolationProps,
 	ScreenStyleInterpolator,
 	ScreenTransitionState,
@@ -14,6 +15,7 @@ export type {
 	BoundsMethod,
 	BoundsNavigationAccessor,
 	BoundsNavigationZoomOptions,
+	BoundsNavigationZoomStyle,
 } from "./bounds.types";
 export type {
 	ActivationArea,

package/src/shared/types/screen.types.ts

@@ -202,6 +202,18 @@ export type ScreenTransitionConfig = {
 	 */
 	experimental_enableHighRefreshRate?: boolean;
 
+	/**
+	 * Animates the first screen in a navigator from its closed state on initial mount
+	 * instead of snapping directly to its settled progress.
+	 *
+	 * Useful for launch/onboarding flows where the initial screen should participate
+	 * in the same transition system as pushed screens.
+	 *
+	 * @experimental This API may change in future versions.
+	 * @default false
+	 */
+	experimental_animateOnInitialMount?: boolean;
+
 	/**
 	 * Describes heights where a screen can rest, as fractions of screen height,
 	 * or `'auto'` to snap to the intrinsic height of the screen content.

package/src/shared/utils/animation/animate-to-progress.ts

@@ -1,4 +1,4 @@
-import { runOnJS } from "react-native-reanimated";
+import { runOnJS, type SharedValue } from "react-native-reanimated";
 import { FALSE, TRUE } from "../../constants";
 import type { AnimationStoreMap } from "../../stores/animation.store";
 import type { TransitionSpec } from "../../types/animation.types";
@@ -15,6 +15,7 @@ interface AnimateToProgressProps {
 	spec?: TransitionSpec;
 	onAnimationFinish?: (finished: boolean) => void;
 	animations: AnimationStoreMap;
+	targetProgress: SharedValue<number>;
 	/** Optional initial velocity for spring-based progress (units: progress/sec). */
 	initialVelocity?: number;
 }
@@ -24,6 +25,7 @@ export const animateToProgress = ({
 	spec,
 	onAnimationFinish,
 	animations,
+	targetProgress,
 	initialVelocity,
 }: AnimateToProgressProps) => {
 	"worklet";
@@ -44,7 +46,7 @@ export const animateToProgress = ({
 			? { ...config, velocity: initialVelocity }
 			: config;
 
-	const { progress, animating, closing, entering, targetProgress } = animations;
+	const { progress, animating, closing, entering } = animations;
 
 	targetProgress.set(value);
 

package/src/shared/utils/bounds/helpers/compute-bounds-styles.ts

@@ -1,6 +1,5 @@
 import type { MeasuredDimensions } from "react-native-reanimated";
 import {
-	EMPTY_BOUND_HELPER_RESULT,
 	EMPTY_BOUND_HELPER_RESULT_RAW,
 	ENTER_RANGE,
 	EXIT_RANGE,

package/src/shared/utils/bounds/index.ts

@@ -1,14 +1,17 @@
 import { BoundStore, type ResolvedTransitionPair } from "../../stores/bounds";
 import type { ScreenInterpolationProps } from "../../types/animation.types";
-import type { BoundsAccessor } from "../../types/bounds.types";
+import type {
+	BoundsAccessor,
+	BoundsInterpolationProps,
+	BoundsNavigationZoomOptions,
+} from "../../types/bounds.types";
 import { buildBoundsOptions } from "./helpers/build-bounds-options";
 import { computeBoundStyles } from "./helpers/compute-bounds-styles";
 import { createInterpolators } from "./helpers/interpolators";
 import { createLinkAccessor } from "./helpers/link-accessor";
 import { resolveBoundTag } from "./helpers/resolve-bound-tag";
-import type { BoundsFrameProps } from "./types/frame-props";
 import type { BoundsOptions } from "./types/options";
-import { createZoomAccessor } from "./zoom";
+import { buildZoomStyles } from "./zoom/build";
 
 const syncGroupActiveMember = (group?: string, id?: string | number) => {
 	"worklet";
@@ -22,7 +25,7 @@ const syncGroupActiveMember = (group?: string, id?: string | number) => {
 };
 
 export const createBoundsAccessor = (
-	getProps: () => BoundsFrameProps,
+	getProps: () => BoundsInterpolationProps,
 ): BoundsAccessor => {
 	"worklet";
 
@@ -49,90 +52,38 @@ export const createBoundsAccessor = (
 	const computeElementBoundsStyles = (params?: BoundsOptions) => {
 		"worklet";
 		const props = getProps();
-		syncGroupActiveMember(params?.group, params?.id);
+		const id = params?.id;
+		const group = params?.group;
+		syncGroupActiveMember(group, id);
 
 		const resolved = buildBoundsOptions({
 			props,
-			id: params?.id,
-			group: params?.group,
+			id,
+			group,
 			overrides: params,
 			mode: "style",
 			resolveBoundTag,
 		});
 
 		const computed = computeForResolvedOptions(resolved, props);
-
-		const zoomBaseOptions = {
-			anchor: params?.anchor,
-			scaleMode: params?.scaleMode,
-			target: params?.target,
-		};
-		let cachedNavigationPairProps: BoundsFrameProps | undefined;
-		let cachedNavigationPairTag = "";
-		let cachedNavigationPair: ResolvedTransitionPair | undefined;
-
-		const resolveNavigationPair = (
-			tag: string,
-			frameProps: BoundsFrameProps,
-		): ResolvedTransitionPair | undefined => {
-			"worklet";
-			if (!tag) return undefined;
-
-			if (
-				cachedNavigationPairProps === frameProps &&
-				cachedNavigationPairTag === tag
-			) {
-				return cachedNavigationPair;
-			}
-
-			const nextPair = BoundStore.resolveTransitionPair(tag, {
-				currentScreenKey: frameProps.current?.route.key,
-				previousScreenKey: frameProps.previous?.route.key,
-				nextScreenKey: frameProps.next?.route.key,
-				entering: !frameProps.next,
-			});
-
-			cachedNavigationPairProps = frameProps;
-			cachedNavigationPairTag = tag;
-			cachedNavigationPair = nextPair;
-
-			return nextPair;
-		};
-
-		const navigation = createZoomAccessor({
-			id: params?.id,
-			group: params?.group,
-			getProps,
-			resolveBoundTag,
-			zoomBaseOptions,
-			computeRaw: (overrides, frameProps) =>
-				(() => {
-					const currentProps = frameProps ?? getProps();
-					const resolvedNavigationOptions = buildBoundsOptions({
-						props: currentProps,
-						id: params?.id,
-						group: params?.group,
-						overrides,
-						mode: "navigation",
-						resolveBoundTag,
-					});
-					const resolvedPair = resolveNavigationPair(
-						String(resolvedNavigationOptions.id),
-						currentProps,
-					);
-
-					return computeForResolvedOptions(
-						resolvedNavigationOptions,
-						currentProps,
-						resolvedPair,
-					) as Record<string, unknown>;
-				})(),
-		});
+		// Navigation helpers are intentionally opinionated. Only the resolved
+		// tag from `id`/`group` is allowed to flow into `navigation.zoom()`;
+		// base bounds overrides like `target`, `anchor`, or `scaleMode` must not.
+		const navigationTag = resolveBoundTag({ id, group });
 
 		const target = Object.isExtensible(computed) ? computed : { ...computed };
 
 		Object.defineProperty(target, "navigation", {
-			value: navigation,
+			value: {
+				zoom: (options?: BoundsNavigationZoomOptions) => {
+					"worklet";
+					return buildZoomStyles({
+						props: getProps(),
+						resolvedTag: navigationTag,
+						zoomOptions: options,
+					});
+				},
+			},
 			enumerable: false,
 			configurable: true,
 		});