react-native-screen-transitions 3.5.2 → 3.6.0-alpha.0

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

@@ -11,9 +11,33 @@ import {
 } from "../constants";
 import type { BoundsAccessor } from "./bounds.types";
 import type { GestureValues } from "./gesture.types";
-import type { ScreenLayouts } from "./screen.types";
+import type { ScreenLayouts, ScreenTransitionConfig } from "./screen.types";
 import type { BaseStackRoute } from "./stack.types";
 
+/**
+ * Public screen option values exposed to `screenStyleInterpolator`.
+ *
+ * These are the values we consider useful to change dynamically with
+ * `navigation.setOptions()`. If you need another existing screen option here,
+ * open a request with the use case and why the interpolator needs it.
+ */
+export type ScreenTransitionOptions = Pick<
+	ScreenTransitionConfig,
+	| "gestureEnabled"
+	| "experimental_allowDisabledGestureTracking"
+	| "gestureDirection"
+	| "gestureSensitivity"
+	| "gestureVelocityImpact"
+	| "gestureSnapVelocityImpact"
+	| "gestureReleaseVelocityScale"
+	| "gestureResponseDistance"
+	| "gestureDrivesProgress"
+	| "gestureActivationArea"
+	| "gestureSnapLocked"
+	| "sheetScrollGestureBehavior"
+	| "backdropBehavior"
+>;
+
 export type ScreenTransitionState = {
 	/**
 	 * Animation progress for this screen.
@@ -99,6 +123,15 @@ export type ScreenTransitionState = {
 	 */
 	meta?: Record<string, unknown>;
 
+	/**
+	 * Public screen option values exposed to `screenStyleInterpolator`.
+	 *
+	 * These are the values we consider useful to change dynamically with
+	 * `navigation.setOptions()`. If you need another existing screen option here,
+	 * open a request with the use case and why the interpolator needs it.
+	 */
+	options: ScreenTransitionOptions;
+
 	/**
 	 * The route object for this screen.
 	 */
@@ -110,13 +143,22 @@ export type ScreenTransitionState = {
 	layouts: ScreenLayouts;
 
 	/**
-	 * Animated index of this screen's current snap point.
+	 * Live 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
 	 */
+	animatedSnapIndex: number;
+
+	/**
+	 * Target snap point index for this screen.
+	 *
+	 * Unlike `animatedSnapIndex`, this follows the current target progress rather
+	 * than live gesture progress. It updates when the transition target changes,
+	 * such as initial mount, `snapTo()`, or gesture release.
+	 */
 	snapIndex: number;
 };
 
@@ -138,14 +180,8 @@ export interface ScreenInterpolationProps {
 
 	/**
 	 * Layout measurements for the screen.
-	 *
-	 * @deprecated Use `current.layouts` instead.
 	 */
-	layouts: {
-		screen: ScreenLayouts["screen"];
-		content?: ScreenLayouts["content"];
-		navigationMaskEnabled: ScreenLayouts["navigationMaskEnabled"];
-	};
+	layouts: ScreenLayouts;
 
 	/**
 	 * The safe area insets for the screen.
@@ -175,13 +211,6 @@ export interface ScreenInterpolationProps {
 	 */
 	stackProgress: number;
 
-	/**
-	 * Animated index of the current snap point.
-	 *
-	 * @deprecated Use `current.snapIndex` instead.
-	 */
-	snapIndex: number;
-
 	/**
 	 * Whether the active transition is visually close enough to its target to be
 	 * treated as complete, even if the animation is still physically settling.
@@ -238,7 +267,24 @@ type TransitionSlotDefinition = {
 export type TransitionSlotStyle = AnimatedViewStyle | TransitionSlotDefinition;
 
 /**
- * Internal normalized slot format used after the backward-compat shim.
+ * Runtime options returned by `screenStyleInterpolator`.
+ *
+ * These values are not style slots. They are derived per frame and consumed by
+ * the transition runtime.
+ *
+ * If `gestureSensitivity` is derived from the current gesture, prefer
+ * `active.gesture.raw` so the sensitivity calculation does not feed back into
+ * itself.
+ */
+export type TransitionInterpolatorOptions = ScreenTransitionOptions;
+
+/**
+ * @deprecated Use `TransitionInterpolatorOptions`.
+ */
+export type TransitionInterpolatorConfig = TransitionInterpolatorOptions;
+
+/**
+ * Internal normalized slot format.
  * Always uses the explicit `{ style, props }` shape (with Reanimated's full StyleProps).
  */
 export type NormalizedTransitionSlotStyle = {
@@ -247,7 +293,7 @@ export type NormalizedTransitionSlotStyle = {
 };
 
 /**
- * Normalized interpolated style map used internally after the backward-compat shim.
+ * Normalized interpolated style map used internally.
  * All slots use the explicit `{ style, props }` shape.
  */
 export type NormalizedTransitionInterpolatedStyle = {
@@ -267,9 +313,14 @@ export type NormalizedTransitionInterpolatedStyle = {
 
 /**
  * The return type of `screenStyleInterpolator`.
- * Uses the nested slot format, while still accepting deprecated flat keys.
  */
 export type TransitionInterpolatedStyle = {
+	/**
+	 * Runtime options for the current frame.
+	 *
+	 * This reserved key is stripped before style slot normalization.
+	 */
+	options?: TransitionInterpolatorOptions;
 	/** Animated style and props for the main screen content view. */
 	content?: TransitionSlotStyle;
 	/** Animated style and props for the backdrop layer between screens. */
@@ -281,22 +332,7 @@ export type TransitionInterpolatedStyle = {
 	/** Animated style and props for the navigation mask element layer. */
 	[NAVIGATION_MASK_ELEMENT_STYLE_ID]?: TransitionSlotStyle;
 	/** Custom styles/props by id for Transition.View components. */
-	[id: string]: TransitionSlotStyle | undefined;
-	/**
-	 * @deprecated Use `content` instead.
-	 * This flat format is auto-converted via a backward-compat shim.
-	 */
-	contentStyle?: AnimatedViewStyle;
-	/**
-	 * @deprecated Use `backdrop` instead.
-	 * This flat format is auto-converted via a backward-compat shim.
-	 */
-	backdropStyle?: AnimatedViewStyle;
-	/**
-	 * @deprecated Use `backdrop` instead.
-	 * This flat format is auto-converted via a backward-compat shim.
-	 */
-	overlayStyle?: AnimatedViewStyle;
+	[id: string]: TransitionSlotStyle | TransitionInterpolatorOptions | undefined;
 };
 
 /**

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

@@ -30,10 +30,18 @@ export type BoundEntry = {
 };
 
 export type BoundsLink = {
+	id: string;
 	source: BoundEntry | null;
 	destination: BoundEntry | null;
+	initialSource: BoundEntry | null;
+	initialDestination: BoundEntry | null;
+	compute: <T extends BoundsLinkComputeOptions>(
+		options: T,
+	) => BoundsOptionsResult<T & { id: string }>;
 };
 
+export type BoundsLinkComputeOptions = Omit<BoundsOptions, "id" | "group">;
+
 export type BoundsNavigationZoomOptions = {
 	target?: "bound" | "fullscreen" | MeasuredDimensions;
 	debug?: boolean;
@@ -153,16 +161,35 @@ export type BoundsNavigationZoomStyle = TransitionInterpolatedStyle & {
 	[NAVIGATION_MASK_ELEMENT_STYLE_ID]?: TransitionSlotStyle;
 };
 
+export type BoundsNavigationRevealStyle = BoundsNavigationZoomStyle;
+
 export type BoundsNavigationAccessor = {
 	zoom: (options?: BoundsNavigationZoomOptions) => BoundsNavigationZoomStyle;
+	reveal: () => BoundsNavigationRevealStyle;
 };
 
 type BoundsBoundNavigationAccessor = {
 	navigation: BoundsNavigationAccessor;
 };
 
+export type BoundsScopedAccessors = {
+	getMeasured: (key?: string) => MeasuredEntry | null;
+	/**
+	 * @deprecated Use `getMeasured` instead. `getSnapshot` will be removed in the next major version.
+	 */
+	getSnapshot: (key?: string) => MeasuredEntry | null;
+	getLink: () => BoundsLink | null;
+	interpolateStyle: (property: keyof StyleProps, fallback?: number) => number;
+	interpolateBounds: (
+		property: keyof MeasuredDimensions,
+		fallbackOrTargetKey?: number | string,
+		fallback?: number,
+	) => number;
+};
+
 type BoundsCallResult<T extends BoundsOptions> = BoundsOptionsResult<T> &
-	BoundsBoundNavigationAccessor;
+	BoundsBoundNavigationAccessor &
+	BoundsScopedAccessors;
 
 export type BoundsAccessor = {
 	<T extends BoundsOptions>(options: T): BoundsCallResult<T>;

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

@@ -1,10 +1,54 @@
-export type GestureDirection =
+export type PanGestureDirection =
 	| "horizontal"
 	| "horizontal-inverted"
 	| "vertical"
 	| "vertical-inverted"
 	| "bidirectional";
 
+export type ResolvedPanGestureDirection = Exclude<
+	PanGestureDirection,
+	"bidirectional"
+>;
+
+export type PinchGestureDirection = "pinch-in" | "pinch-out";
+
+export type GestureDirection = PanGestureDirection | PinchGestureDirection;
+
+export type ActiveGesture = ResolvedPanGestureDirection | PinchGestureDirection;
+
+export type SnapPanAxis = "horizontal" | "vertical";
+
+export type ScrollGestureAxis = "vertical" | "horizontal";
+
+export type ScrollGestureAxisState = {
+	offset: number;
+	contentSize: number;
+	layoutSize: number;
+};
+
+export type ScrollGestureState = {
+	vertical: ScrollGestureAxisState;
+	horizontal: ScrollGestureAxisState;
+	isTouched: boolean;
+};
+
+export type SnapPanAxisConfig = {
+	collapse: ResolvedPanGestureDirection;
+	expand: ResolvedPanGestureDirection;
+	inverted: boolean;
+	progressSign: -1 | 1;
+};
+
+export type SnapPanDirectionConfig = Record<
+	SnapPanAxis,
+	SnapPanAxisConfig | null
+>;
+
+export type SnapPinchDirectionConfig = {
+	collapse: PinchGestureDirection;
+	expand: PinchGestureDirection;
+} | null;
+
 export type ActivationArea = "edge" | "screen";
 
 export type SideActivation = {
@@ -14,12 +58,14 @@ export type SideActivation = {
 	bottom?: ActivationArea;
 };
 
-export enum GestureOffsetState {
+export enum GestureActivationState {
 	PENDING,
 	PASSED,
 	FAILED,
 }
 
+export { GestureActivationState as GestureOffsetState };
+
 export type GestureActivationArea = ActivationArea | SideActivation;
 
 /**
@@ -31,7 +77,15 @@ export type GestureDirections = {
 	horizontalInverted: boolean;
 	vertical: boolean;
 	verticalInverted: boolean;
-	snapAxisInverted?: boolean;
+};
+
+export type RawGestureValues = {
+	x: number;
+	y: number;
+	normX: number;
+	normY: number;
+	scale: number;
+	normScale: number;
 };
 
 export type GestureValues = {
@@ -51,6 +105,26 @@ export type GestureValues = {
 	 * The live normalized vertical translation of the gesture (-1 to 1).
 	 */
 	normY: number;
+	/**
+	 * The live pinch scale after `gestureSensitivity` is applied.
+	 */
+	scale: number;
+	/**
+	 * The live normalized pinch scale delta after `gestureSensitivity` is applied.
+	 */
+	normScale: number;
+	/**
+	 * The live pinch focal point x-position in screen coordinates.
+	 */
+	focalX: number;
+	/**
+	 * The live pinch focal point y-position in screen coordinates.
+	 */
+	focalY: number;
+	/**
+	 * Physical gesture values before `gestureSensitivity` is applied.
+	 */
+	raw: RawGestureValues;
 	/**
 	 * A flag indicating if the screen is in the process of dismissing (0 or 1).
 	 */
@@ -60,9 +134,19 @@ export type GestureValues = {
 	 */
 	dragging: number;
 	/**
-	 * The initial direction that activated the gesture.
+	 * A flag indicating if released gesture values are animating back to neutral.
+	 */
+	settling: number;
+	/**
+	 * The gesture that is currently active.
+	 */
+	active: ActiveGesture | null;
+	/**
+	 * The initial pan direction that activated the gesture.
+	 *
+	 * @deprecated Use `active` instead.
 	 */
-	direction: Omit<GestureDirection, "bidirectional"> | null;
+	direction: ResolvedPanGestureDirection | null;
 
 	/** @deprecated Use `normX` instead. */
 	normalizedX: number;

package/src/shared/types/index.ts

@@ -4,8 +4,11 @@ export type {
 	AnimationConfig,
 	ScreenInterpolationProps,
 	ScreenStyleInterpolator,
+	ScreenTransitionOptions,
 	ScreenTransitionState,
 	TransitionInterpolatedStyle,
+	TransitionInterpolatorConfig,
+	TransitionInterpolatorOptions,
 	TransitionSlotStyle,
 	TransitionSpec,
 } from "./animation.types";
@@ -13,6 +16,7 @@ export type {
 	BoundsAccessor,
 	BoundsMethod,
 	BoundsNavigationAccessor,
+	BoundsNavigationRevealStyle,
 	BoundsNavigationZoomOpacityRange,
 	BoundsNavigationZoomOpacityRanges,
 	BoundsNavigationZoomOptions,
@@ -23,6 +27,8 @@ export type {
 	GestureActivationArea,
 	GestureDirection,
 	GestureValues,
+	PanGestureDirection,
+	PinchGestureDirection,
 	SideActivation,
 } from "./gesture.types";
 export type { OverlayProps } from "./overlay.types";

package/src/shared/types/ownership.types.ts

@@ -34,7 +34,7 @@ export const DIRECTIONS: Direction[] = [
 /**
  * Map of which directions a screen claims ownership of.
  * A screen claims a direction when:
- * - gestureEnabled is true AND
+ * - direction claiming is enabled AND
  * - gestureDirection includes that direction
  *
  * For snap points, both directions on the axis are claimed automatically.
@@ -42,7 +42,7 @@ export const DIRECTIONS: Direction[] = [
 export type ClaimedDirections = Record<Direction, boolean>;
 
 /**
- * Empty claims - used when gestureEnabled is false.
+ * Empty claims - used when direction claiming is disabled.
  */
 export const NO_CLAIMS: ClaimedDirections = {
 	vertical: false,

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

@@ -124,11 +124,6 @@ export type ScreenTransitionConfig = {
 	 */
 	navigationMaskEnabled?: boolean;
 
-	/**
-	 * @deprecated Use `navigationMaskEnabled` instead.
-	 */
-	maskEnabled?: boolean;
-
 	/**
 	 * Controls whether swipe-to-dismiss is enabled.
 	 *
@@ -138,10 +133,42 @@ export type ScreenTransitionConfig = {
 	gestureEnabled?: boolean;
 
 	/**
-	 * The direction of the swipe gesture used to dismiss the screen.
+	 * Allows screens with `gestureEnabled={false}` to still activate gestures for
+	 * live gesture values while preventing gesture dismissal.
+	 *
+	 * This is a v3 compatibility bridge for the next gesture behavior. Direction
+	 * ownership/claims participate while this is enabled so nested screens can
+	 * intentionally shadow parent gestures for resistance-style animations.
+	 *
+	 * Screens with `snapPoints` already keep gesture tracking when
+	 * `gestureEnabled={false}`; this flag mainly affects disabled non-snap
+	 * gestures.
+	 *
+	 * @experimental This API may change in future versions.
+	 * @default false
+	 */
+	experimental_allowDisabledGestureTracking?: boolean;
+
+	/**
+	 * The direction(s) of the screen gesture used to dismiss the screen.
+	 *
+	 * Supports pan directions (`horizontal`, `vertical`, etc.) and pinch
+	 * directions (`pinch-in`, `pinch-out`).
 	 */
 	gestureDirection?: GestureDirection | GestureDirection[];
 
+	/**
+	 * Controls how directly live gesture movement maps into transition progress
+	 * and the non-raw gesture values exposed to interpolators.
+	 *
+	 * Lower values feel less sensitive, higher values feel more responsive. If
+	 * an interpolator needs physical gesture input before sensitivity is applied,
+	 * read from `active.gesture.raw`.
+	 *
+	 * @default 1
+	 */
+	gestureSensitivity?: number;
+
 	/**
 	 * How much the gesture's final velocity impacts the dismiss decision.
 	 * @default 0.3
@@ -155,6 +182,14 @@ export type ScreenTransitionConfig = {
 	 */
 	snapVelocityImpact?: number;
 
+	/**
+	 * How much velocity affects snap point targeting. Lower values make snapping
+	 * feel more deliberate (iOS-like), higher values make it more responsive to flicks.
+	 *
+	 * @default 0.1
+	 */
+	gestureSnapVelocityImpact?: number;
+
 	/**
 	 * Multiplies gesture release velocity used for spring animation energy.
 	 *
@@ -173,6 +208,8 @@ export type ScreenTransitionConfig = {
 	 * or snap target selection (`snapVelocityImpact`). It only bounds release
 	 * animation intensity after `gestureReleaseVelocityScale` is applied.
 	 *
+	 * @deprecated v3 compatibility only. This option is removed in the next
+	 * gesture runtime.
 	 * @default 3.2
 	 */
 	gestureReleaseVelocityMax?: number;

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

@@ -17,6 +17,7 @@ interface AnimateToProgressProps {
 	animations: AnimationStoreMap;
 	targetProgress: SharedValue<number>;
 	emitWillAnimate?: boolean;
+	markEntering?: boolean;
 	/** Optional initial velocity for spring-based progress (units: progress/sec). */
 	initialVelocity?: number;
 }
@@ -28,6 +29,7 @@ export const animateToProgress = ({
 	animations,
 	targetProgress,
 	emitWillAnimate = true,
+	markEntering = true,
 	initialVelocity,
 }: AnimateToProgressProps) => {
 	"worklet";
@@ -50,54 +52,71 @@ export const animateToProgress = ({
 
 	const { progress, willAnimate, animating, closing, entering } = animations;
 
-	if (emitWillAnimate) {
-		willAnimate.set(TRUE);
-		requestAnimationFrame(() => {
-			"worklet";
-			willAnimate.set(FALSE);
-		});
-	}
-
-	targetProgress.set(value);
+	const startAnimation = () => {
+		"worklet";
+		targetProgress.set(value);
 
-	if (isClosing) {
-		closing.set(TRUE);
-		entering.set(FALSE);
-	} else {
-		entering.set(TRUE);
-	}
+		const shouldClearEnteringOnFinish =
+			!isClosing && (markEntering || entering.get());
 
-	if (!config) {
-		animating.set(FALSE);
-		progress.set(value);
-		if (!isClosing) {
+		if (isClosing) {
+			closing.set(TRUE);
 			entering.set(FALSE);
+		} else if (markEntering) {
+			entering.set(TRUE);
 		}
 
-		if (onAnimationFinish) {
-			runOnJS(onAnimationFinish)(true);
-		}
-		return;
-	}
-
-	animating.set(TRUE); //<-- Do not move this into the callback
-	progress.set(
-		animate(value, effectiveConfig, (finished) => {
-			"worklet";
-			if (!finished) return;
-
-			if (!isClosing) {
+		if (!config) {
+			animating.set(FALSE);
+			progress.set(value);
+			if (shouldClearEnteringOnFinish) {
 				entering.set(FALSE);
 			}
 
 			if (onAnimationFinish) {
-				runOnJS(onAnimationFinish)(finished);
+				runOnJS(onAnimationFinish)(true);
 			}
+			return;
+		}
+
+		animating.set(TRUE); //<-- Do not move this into the callback
+		progress.set(
+			animate(value, effectiveConfig, (finished) => {
+				"worklet";
+				if (!finished) return;
+
+				if (shouldClearEnteringOnFinish) {
+					entering.set(FALSE);
+				}
+
+				if (onAnimationFinish) {
+					runOnJS(onAnimationFinish)(finished);
+				}
+
+				// Delay setting animating=FALSE by one frame to ensure final frame is painted
+				requestAnimationFrame(() => {
+					animating.set(FALSE);
+				});
+			}),
+		);
+	};
+
+	if (emitWillAnimate) {
+		if (isClosing) {
+			closing.set(TRUE);
+			entering.set(FALSE);
+		} else if (markEntering) {
+			entering.set(TRUE);
+		}
+
+		willAnimate.set(TRUE);
+		requestAnimationFrame(() => {
+			"worklet";
+			willAnimate.set(FALSE);
+			startAnimation();
+		});
+		return;
+	}
 
-			// Delay setting animating=FALSE by one frame to ensure final frame is painted
-			requestAnimationFrame(() => {
-				animating.set(FALSE);
-			});
-		}),
-	);
+	startAnimation();
 };

package/src/shared/utils/animation/emit.ts

@@ -0,0 +1,18 @@
+import type { SharedValue } from "react-native-reanimated";
+
+/**
+ * Emits a one-frame pulse on any shared value, then restores the provided
+ * resting value on the next frame.
+ */
+export const emit = <T>(
+	sharedValue: SharedValue<T>,
+	activeValue: T,
+	restValue: T,
+) => {
+	"worklet";
+	sharedValue.set(activeValue);
+	requestAnimationFrame(() => {
+		"worklet";
+		sharedValue.set(restValue);
+	});
+};

package/src/shared/utils/animation/resolve-snap-transition-spec.ts

@@ -0,0 +1,23 @@
+import { DefaultSnapSpec } from "../../configs/specs";
+import type { TransitionSpec } from "../../types/animation.types";
+
+export type SnapTransitionDirection = "expand" | "collapse";
+
+export const resolveSnapTransitionSpec = (
+	spec: TransitionSpec | undefined,
+	direction: SnapTransitionDirection,
+): TransitionSpec => {
+	"worklet";
+	const config =
+		direction === "collapse"
+			? (spec?.collapse ?? DefaultSnapSpec)
+			: (spec?.expand ?? DefaultSnapSpec);
+
+	// Numeric snap targets are not lifecycle closes. Keep both slots pointed at the
+	// selected snap config so animateToProgress can pick a config without toggling
+	// the route-level closing flag for non-dismiss snap changes.
+	return {
+		open: config,
+		close: config,
+	};
+};

package/src/shared/utils/bounds/helpers/create-bound-tag.ts

@@ -1,6 +1,6 @@
 import type { BoundId } from "../types/options";
 
-export type CreateBoundTagParams = {
+type CreateBoundTagParams = {
 	id?: BoundId;
 	group?: string;
 };