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

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

@@ -1,9 +1,10 @@
 import type { MeasuredDimensions, StyleProps } from "react-native-reanimated";
-import type { Snapshot } from "../stores/bounds.store";
+import type { Snapshot } from "../stores/bounds";
 import type {
-	BoundsBuilderOptions,
-	BoundsReturnType,
-} from "../utils/bounds/types/builder";
+	BoundsOptions,
+	BoundsOptionsResult,
+} from "../utils/bounds/types/options";
+import type { TransitionInterpolatedStyle } from "./animation.types";
 
 /**
  * Target style computation.
@@ -24,8 +25,27 @@ export type BoundsLink = {
 	destination: BoundEntry | null;
 };
 
+export type BoundsStyleOptions = Omit<BoundsOptions, "id" | "group">;
+
+export type BoundsNavigationPreset = "zoom";
+
+export type BoundsNavigationOptions = BoundsStyleOptions & {
+	maskBorderRadius?: number;
+};
+
+export type BoundsNavigationAccessor = {
+	zoom: () => TransitionInterpolatedStyle;
+};
+
+type BoundsBoundNavigationAccessor = {
+	navigation: BoundsNavigationAccessor;
+};
+
+type BoundsCallResult<T extends BoundsOptions> = BoundsOptionsResult<T> &
+	BoundsBoundNavigationAccessor;
+
 export type BoundsAccessor = {
-	<T extends BoundsBuilderOptions>(options: T): BoundsReturnType<T>;
+	<T extends BoundsOptions>(options: T): BoundsCallResult<T>;
 	getSnapshot: (id: string, key?: string) => Snapshot | null;
 	getLink: (id: string) => BoundsLink | null;
 	interpolateStyle: (

package/src/shared/types/gesture.types.ts

@@ -22,11 +22,19 @@ export enum GestureOffsetState {
 
 export type GestureActivationArea = ActivationArea | SideActivation;
 
+/**
+ * Resolved boolean flags for which directions a gesture is active in.
+ * Shared across gesture activation, velocity, and dismissal logic.
+ */
+export type GestureDirections = {
+	horizontal: boolean;
+	horizontalInverted: boolean;
+	vertical: boolean;
+	verticalInverted: boolean;
+	snapAxisInverted?: boolean;
+};
+
 export type GestureValues = {
-	/**
-	 * A `SharedValue` indicating if the user's finger is on the screen (0 or 1).
-	 */
-	isDragging: number;
 	/**
 	 * The live horizontal translation of the gesture.
 	 */
@@ -38,17 +46,30 @@ export type GestureValues = {
 	/**
 	 * The live normalized horizontal translation of the gesture (-1 to 1).
 	 */
-	normalizedX: number;
+	normX: number;
 	/**
 	 * The live normalized vertical translation of the gesture (-1 to 1).
 	 */
-	normalizedY: number;
+	normY: number;
 	/**
-	 * A flag indicating if the screen is in the process of dismissing.
+	 * A flag indicating if the screen is in the process of dismissing (0 or 1).
 	 */
-	isDismissing: number;
+	dismissing: number;
+	/**
+	 * A flag indicating if the user's finger is on the screen (0 or 1).
+	 */
+	dragging: number;
 	/**
 	 * The initial direction that activated the gesture.
 	 */
 	direction: Omit<GestureDirection, "bidirectional"> | null;
+
+	/** @deprecated Use `normX` instead. */
+	normalizedX: number;
+	/** @deprecated Use `normY` instead. */
+	normalizedY: number;
+	/** @deprecated Use `dismissing` instead. */
+	isDismissing: number;
+	/** @deprecated Use `dragging` instead. */
+	isDragging: number;
 };

package/src/shared/types/index.ts

@@ -1,11 +1,18 @@
 export { FALSE, TRUE } from "../constants";
 export type {
+	AnimatedViewStyle,
 	AnimationConfig,
+	LegacyTransitionInterpolatedStyle,
+	NewTransitionInterpolatedStyle,
+	NormalizedTransitionInterpolatedStyle,
+	NormalizedTransitionSlotStyle,
 	OverlayInterpolationProps,
 	ScreenInterpolationProps,
 	ScreenStyleInterpolator,
 	ScreenTransitionState,
 	TransitionInterpolatedStyle,
+	TransitionSlotExplicit,
+	TransitionSlotStyle,
 	TransitionSpec,
 } from "./animation.types";
 export type {
@@ -13,6 +20,10 @@ export type {
 	BoundsAccessor,
 	BoundsLink,
 	BoundsMethod,
+	BoundsNavigationAccessor,
+	BoundsNavigationOptions,
+	BoundsNavigationPreset,
+	BoundsStyleOptions,
 } from "./bounds.types";
 export type {
 	ActivationArea,

package/src/shared/types/overlay.types.ts

@@ -17,6 +17,18 @@ export type OverlayMode = "float" | "screen";
  * Props passed to overlay components.
  * Generic over the navigation type since different stacks have different navigation props.
  */
+/**
+ * Overlay screen state passed to overlay host for rendering.
+ * Generic over navigation type — defaults to `unknown` for flexibility.
+ */
+export type OverlayScreenState<TNavigation = unknown> = Omit<
+	OverlayProps<TNavigation>,
+	"progress" | "overlayAnimation" | "screenAnimation"
+> & {
+	index: number;
+	snapTo: (index: number) => void;
+};
+
 export type OverlayProps<TNavigation = unknown> = {
 	/**
 	 * Route of the currently focused screen in the stack.

package/src/shared/types/providers/direct-stack.types.ts

@@ -0,0 +1,35 @@
+import type {
+	ParamListBase,
+	RouteProp,
+	StackNavigationState,
+} from "@react-navigation/native";
+import type {
+	NativeStackDescriptor,
+	NativeStackDescriptorMap,
+	NativeStackNavigationHelpers,
+} from "../../../native-stack/types";
+
+export interface DirectStackScene {
+	route: StackNavigationState<ParamListBase>["routes"][number];
+	descriptor: NativeStackDescriptor;
+	isPreloaded: boolean;
+}
+
+export interface DirectStackProps {
+	state: StackNavigationState<ParamListBase>;
+	navigation: NativeStackNavigationHelpers;
+	descriptors: NativeStackDescriptorMap;
+	describe: (
+		route: RouteProp<ParamListBase>,
+		placeholder: boolean,
+	) => NativeStackDescriptor;
+}
+
+export interface DirectStackContextValue {
+	state: StackNavigationState<ParamListBase>;
+	navigation: NativeStackNavigationHelpers;
+	descriptors: NativeStackDescriptorMap;
+	scenes: DirectStackScene[];
+	focusedIndex: number;
+	shouldShowFloatOverlay: boolean;
+}

package/src/shared/types/providers/managed-stack.types.ts

@@ -0,0 +1,59 @@
+import type { SharedValue } from "react-native-reanimated";
+import type { StackContextValue } from "../../hooks/navigation/use-stack";
+import type {
+	BaseStackDescriptor,
+	BaseStackNavigation,
+	BaseStackRoute,
+	BaseStackScene,
+	BaseStackState,
+} from "../stack.types";
+
+/**
+ * Props for managed stack - generic over descriptor and navigation types.
+ * Defaults to base types for backward compatibility.
+ */
+export interface ManagedStackProps<
+	TDescriptor extends BaseStackDescriptor = BaseStackDescriptor,
+	TNavigation extends BaseStackNavigation = BaseStackNavigation,
+> {
+	state: BaseStackState<TDescriptor["route"]>;
+	navigation: TNavigation;
+	descriptors: Record<string, TDescriptor>;
+	describe: (route: TDescriptor["route"], placeholder: boolean) => TDescriptor;
+}
+
+/**
+ * Context value for managed stack — only fields unique to managed lifecycle.
+ * Shared fields (routes, scenes, etc.) live in StackContext.
+ */
+export interface ManagedStackContextValue {
+	activeScreensLimit: number;
+	closingRouteKeysShared: SharedValue<string[]>;
+	handleCloseRoute: (payload: { route: BaseStackRoute }) => void;
+	backdropBehaviors: string[];
+}
+
+/**
+ * Props passed to the render child of `withManagedStack`.
+ * Only the fields that stack-view components actually consume.
+ */
+export interface ManagedStackRenderProps<
+	TDescriptor extends BaseStackDescriptor = BaseStackDescriptor,
+> {
+	descriptors: Record<string, TDescriptor>;
+	scenes: BaseStackScene<TDescriptor>[];
+	focusedIndex: number;
+	closingRouteMap: React.RefObject<Readonly<Record<string, true>>>;
+	shouldShowFloatOverlay: boolean;
+}
+
+/**
+ * Internal result shape returned by useManagedStackValue.
+ */
+export interface ManagedStackResult<
+	TDescriptor extends BaseStackDescriptor = BaseStackDescriptor,
+> {
+	stackContextValue: StackContextValue;
+	managedContextValue: ManagedStackContextValue;
+	renderProps: ManagedStackRenderProps<TDescriptor>;
+}

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

@@ -76,6 +76,14 @@ export type ScreenTransitionConfig = {
 	 */
 	transitionSpec?: TransitionSpec;
 
+	/**
+	 * Pre-mounts the masked view wrapper so navigation bounds masking
+	 * (e.g. `bounds().navigation.zoom()`) is ready from the first frame.
+	 *
+	 * Requires `@react-native-masked-view/masked-view` to be installed.
+	 */
+	maskEnabled?: boolean;
+
 	/**
 	 * Controls whether swipe-to-dismiss is enabled.
 	 *
@@ -102,6 +110,28 @@ export type ScreenTransitionConfig = {
 	 */
 	snapVelocityImpact?: number;
 
+	/**
+	 * Multiplies gesture release velocity used for spring animation energy.
+	 *
+	 * This does NOT affect dismissal threshold decisions (`gestureVelocityImpact`)
+	 * or snap target selection (`snapVelocityImpact`). It only changes how fast
+	 * the post-release animation feels.
+	 *
+	 * @default 1
+	 */
+	gestureReleaseVelocityScale?: number;
+
+	/**
+	 * Caps the absolute post-scale release velocity used by spring animations.
+	 *
+	 * This does NOT affect dismissal threshold decisions (`gestureVelocityImpact`)
+	 * or snap target selection (`snapVelocityImpact`). It only bounds release
+	 * animation intensity after `gestureReleaseVelocityScale` is applied.
+	 *
+	 * @default 3.2
+	 */
+	gestureReleaseVelocityMax?: number;
+
 	/**
 	 * Distance threshold for gesture recognition throughout the screen.
 	 */
@@ -215,15 +245,45 @@ export type ScreenTransitionConfig = {
 	backdropBehavior?: "block" | "passthrough" | "dismiss" | "collapse";
 
 	/**
-	 * Custom component to render as the backdrop layer.
-	 * When provided, replaces the default backdrop entirely — including press handling.
+	 * Custom component to render as the backdrop layer (between screens).
+	 *
+	 * The library wraps this component with `Animated.createAnimatedComponent` internally.
+	 * Animated styles and props are driven by the `backdrop` slot in the interpolator return value.
+	 *
+	 * `backdropBehavior` still controls the wrapping Pressable for dismiss/collapse handling.
+	 *
+	 * @example
+	 * backdropComponent: BlurView,
+	 * screenStyleInterpolator: ({ progress }) => ({
+	 *   backdrop: {
+	 *     style: { opacity: interpolate(progress, [0, 1], [0, 1]) },
+	 *     props: { intensity: interpolate(progress, [0, 1], [0, 80]) },
+	 *   },
+	 * })
+	 *
+	 * @default undefined
+	 */
+	backdropComponent?: React.ComponentType<any>;
+
+	/**
+	 * Custom component to render as the screen's surface layer.
+	 *
+	 * Renders inside the content animation scope (moves with the screen) as an
+	 * absolutely-positioned layer behind the screen's children.
 	 *
-	 * Use `useScreenAnimation()` inside the component to access animation values.
-	 * Use your navigation method of choice (e.g. `router.back()`) to handle dismissal.
+	 * The library wraps this component with `Animated.createAnimatedComponent` internally.
+	 * Animated styles and props are driven by the `surface` slot in the interpolator return value.
 	 *
-	 * `backdropBehavior` still controls container-level pointer events when this is set.
+	 * @example
+	 * surfaceComponent: SquircleView,
+	 * screenStyleInterpolator: ({ progress }) => ({
+	 *   surface: {
+	 *     style: { opacity: interpolate(progress, [0, 1], [0, 1]) },
+	 *     props: { cornerRadius: 24, cornerSmoothing: 0.7 },
+	 *   },
+	 * })
 	 *
 	 * @default undefined
 	 */
-	backdropComponent?: React.FC;
+	surfaceComponent?: React.ComponentType<any>;
 };

package/src/shared/types/stack.types.ts

@@ -1,5 +1,13 @@
 import type { ScreenTransitionConfig } from "./screen.types";
 
+/**
+ * Minimal route shape for navigation utilities.
+ * Used as a generic constraint across route comparison functions.
+ */
+export interface RouteWithKey {
+	key: string;
+}
+
 /**
  * Base route interface - minimal contract all stacks satisfy.
  * Uses `object` for params to be compatible with React Navigation's `Readonly<object | undefined>`.

package/src/shared/utils/animation/animate-many.ts

@@ -0,0 +1,40 @@
+import type {
+	SharedValue,
+	WithSpringConfig,
+	WithTimingConfig,
+} from "react-native-reanimated";
+import { animate } from "./animate";
+
+export type AnimateManyItem = {
+	value: SharedValue<number>;
+	toValue: number;
+	config?: WithSpringConfig | WithTimingConfig;
+};
+
+interface AnimateManyProps {
+	items: AnimateManyItem[];
+	onAllFinished?: () => void;
+}
+
+export const animateMany = ({ items, onAllFinished }: AnimateManyProps) => {
+	"worklet";
+
+	if (items.length === 0) {
+		onAllFinished?.();
+		return;
+	}
+
+	let remaining = items.length;
+
+	for (const item of items) {
+		item.value.value = animate(item.toValue, item.config, (finished) => {
+			"worklet";
+			if (!finished) return;
+
+			remaining -= 1;
+			if (remaining === 0) {
+				onAllFinished?.();
+			}
+		});
+	}
+};

package/src/shared/utils/bounds/helpers/build-bounds-options.ts

@@ -0,0 +1,48 @@
+import { BoundStore } from "../../../stores/bounds";
+import type { ScreenInterpolationProps } from "../../../types/animation.types";
+import type { BoundsOptions } from "../types/options";
+import { DEFAULT_BOUNDS_OPTIONS } from "./constants";
+import type { ResolveBoundTagParams } from "./resolve-bound-tag";
+
+type BuildBoundsOptionsParams = {
+	props: Omit<ScreenInterpolationProps, "bounds">;
+	id?: string;
+	group?: string;
+	overrides?: Partial<BoundsOptions>;
+	mode?: "style" | "navigation";
+	resolveBoundTag: (params: ResolveBoundTagParams) => string | undefined;
+};
+
+export const buildBoundsOptions = ({
+	props,
+	id,
+	group,
+	overrides,
+	mode = "style",
+	resolveBoundTag,
+}: BuildBoundsOptionsParams): BoundsOptions => {
+	"worklet";
+
+	const tag = resolveBoundTag({ id, group });
+	const currentScreenKey = props.current?.route.key;
+	const boundaryConfig =
+		tag && currentScreenKey
+			? BoundStore.getBoundaryConfig(tag, currentScreenKey)
+			: null;
+
+	const resolved = {
+		...DEFAULT_BOUNDS_OPTIONS,
+		...(boundaryConfig ?? {}),
+		...(overrides ?? {}),
+		id: tag ?? "",
+		group,
+	};
+
+	// Element-level bounds style composition always uses relative space.
+	// Absolute space is reserved for internal navigation helpers (masking).
+	if (mode === "style") {
+		resolved.space = "relative";
+	}
+
+	return resolved;
+};

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

@@ -0,0 +1,180 @@
+import type { MeasuredDimensions } from "react-native-reanimated";
+import {
+	EMPTY_BOUND_HELPER_RESULT,
+	EMPTY_BOUND_HELPER_RESULT_RAW,
+	ENTER_RANGE,
+	EXIT_RANGE,
+	FULLSCREEN_DIMENSIONS,
+} from "../../../constants";
+import {
+	BoundStore,
+	type ResolvedTransitionPair,
+} from "../../../stores/bounds";
+import type { ScreenTransitionState } from "../../../types/animation.types";
+import type { Layout } from "../../../types/screen.types";
+import type { BoundsComputeParams, BoundsOptions } from "../types/options";
+import {
+	computeContentTransformGeometry,
+	computeRelativeGeometry,
+} from "./geometry";
+import {
+	composeContentStyle,
+	composeSizeAbsolute,
+	composeSizeRelative,
+	composeTransformAbsolute,
+	composeTransformRelative,
+	type ElementComposeParams,
+} from "./style-composers";
+
+const resolveBounds = (params: {
+	id: string;
+	previous?: ScreenTransitionState;
+	current?: ScreenTransitionState;
+	next?: ScreenTransitionState;
+	toRect?: Partial<MeasuredDimensions>;
+	dimensions: Layout;
+	computeOptions: BoundsOptions;
+	resolvedPair?: ResolvedTransitionPair;
+}) => {
+	"worklet";
+
+	const entering = !params.next;
+	const fullscreen = FULLSCREEN_DIMENSIONS(params.dimensions);
+
+	const isFullscreenTarget = params.computeOptions.target === "fullscreen";
+	const hasCustomTarget = typeof params.computeOptions.target === "object";
+	const hasTargetOverride = isFullscreenTarget || hasCustomTarget;
+
+	const currentScreenKey = params.current?.route.key;
+	const previousScreenKey = params.previous?.route.key;
+	const nextScreenKey = params.next?.route.key;
+
+	const resolvedPair =
+		params.resolvedPair ??
+		BoundStore.resolveTransitionPair(params.id, {
+			currentScreenKey,
+			previousScreenKey,
+			nextScreenKey,
+			entering,
+		});
+
+	const sourceBounds = resolvedPair.sourceBounds;
+	const destinationBounds = resolvedPair.destinationBounds;
+
+	if (!sourceBounds) {
+		return {
+			start: null,
+			end: null,
+			entering,
+		};
+	}
+
+	// When target is overridden, destination element is not required
+	if (!hasTargetOverride && !destinationBounds) {
+		return {
+			start: null,
+			end: null,
+			entering,
+		};
+	}
+
+	const start = sourceBounds;
+	let end = destinationBounds ?? fullscreen;
+
+	if (isFullscreenTarget) {
+		end = fullscreen;
+	}
+
+	const customTarget = params.computeOptions.target;
+	if (typeof customTarget === "object") {
+		end = customTarget;
+	}
+
+	return {
+		start,
+		end,
+		entering,
+	};
+};
+
+export const computeBoundStyles = (
+	{ id, previous, current, next, progress, dimensions }: BoundsComputeParams,
+	computeOptions: BoundsOptions = { id: "bound-id" },
+	resolvedPair?: ResolvedTransitionPair,
+) => {
+	"worklet";
+
+	if (!id) {
+		if (computeOptions.raw) {
+			return EMPTY_BOUND_HELPER_RESULT_RAW;
+		}
+		return EMPTY_BOUND_HELPER_RESULT;
+	}
+
+	const { start, end, entering } = resolveBounds({
+		id,
+		previous,
+		current,
+		next,
+		computeOptions,
+		dimensions,
+		resolvedPair,
+	});
+
+	if (!start || !end) {
+		if (computeOptions.raw) {
+			return EMPTY_BOUND_HELPER_RESULT_RAW;
+		}
+		return EMPTY_BOUND_HELPER_RESULT;
+	}
+
+	const ranges: readonly [number, number] = entering ? ENTER_RANGE : EXIT_RANGE;
+
+	if (computeOptions.method === "content") {
+		const geometry = computeContentTransformGeometry({
+			start,
+			end,
+			entering,
+			dimensions,
+			anchor: computeOptions.anchor,
+			scaleMode: computeOptions.scaleMode,
+		});
+
+		return composeContentStyle({
+			start,
+			progress,
+			ranges,
+			end,
+			geometry,
+			computeOptions,
+		});
+	}
+
+	const geometry = computeRelativeGeometry({
+		start,
+		end,
+		entering,
+		anchor: computeOptions.anchor,
+		scaleMode: computeOptions.scaleMode,
+	});
+
+	const common: ElementComposeParams = {
+		start,
+		end,
+		progress,
+		ranges,
+		geometry,
+		computeOptions,
+	};
+
+	const isSize = computeOptions.method === "size";
+	const isAbsolute = computeOptions.space === "absolute";
+
+	return isSize
+		? isAbsolute
+			? composeSizeAbsolute(common)
+			: composeSizeRelative(common)
+		: isAbsolute
+			? composeTransformAbsolute(common)
+			: composeTransformRelative(common);
+};

package/src/shared/utils/bounds/helpers/constants.ts

@@ -0,0 +1,10 @@
+import type { BoundsOptions } from "../types/options";
+
+export const DEFAULT_BOUNDS_OPTIONS = {
+	target: "bound",
+	method: "transform",
+	space: "relative",
+	scaleMode: "match",
+	anchor: "center",
+	raw: false,
+} as const satisfies Omit<BoundsOptions, "id" | "group" | "gestures">;

package/src/shared/utils/bounds/helpers/geometry.ts

@@ -1,10 +1,10 @@
 import type { MeasuredDimensions } from "react-native-reanimated";
 import type { Layout } from "../../../types/screen.types";
-import type { BoundsAnchor, BoundsScaleMode } from "../types/builder";
 import type {
 	ContentTransformGeometry,
 	RelativeGeometry,
 } from "../types/geometry";
+import type { BoundsAnchor, BoundsScaleMode } from "../types/options";
 
 /**
  * Get the anchor point coordinates for a given bound
@@ -131,10 +131,11 @@ export function computeContentTransformGeometry({
 
 		s = aspectDifference < 0.1 ? Math.max(sx, sy) : Math.min(sx, sy);
 	} else {
-		// For "match" mode on full screen, we need uniform scale
+		// "match" mode: use a cover strategy so the scaled content always
+		// fills the mask area. max() ensures no gaps inside the mask clip.
 		const sx = start.width / end.width;
 		const sy = start.height / end.height;
-		s = (sx + sy) / 2;
+		s = Math.max(sx, sy);
 	}
 
 	// Get anchor points

package/src/shared/utils/bounds/helpers/interpolate-style.ts

@@ -1,6 +1,6 @@
-import { interpolate } from "react-native-reanimated";
 import { ENTER_RANGE, EXIT_RANGE } from "../../../constants";
 import type { BoundsLink } from "../../../types/bounds.types";
+import { interpolateClamped } from "./interpolate";
 
 type InterpolateStyleOptions = {
 	fallback?: number;
@@ -34,5 +34,5 @@ export function interpolateLinkStyle(
 
 	const range = entering ? ENTER_RANGE : EXIT_RANGE;
 
-	return interpolate(progress, range, [sourceValue, destValue], "clamp");
+	return interpolateClamped(progress, range, [sourceValue, destValue]);
 }