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

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

@@ -11,9 +11,34 @@ 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"
+	| "gestureProgressMode"
+	| "gestureDrivesProgress"
+	| "gestureActivationArea"
+	| "gestureSnapLocked"
+	| "sheetScrollGestureBehavior"
+	| "backdropBehavior"
+>;
+
 export type ScreenTransitionState = {
 	/**
 	 * Animation progress for this screen.
@@ -99,6 +124,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,16 +144,41 @@ 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;
 };
 
+export type ScreenTransitionDepthTarget = {
+	/**
+	 * Relative transition depth.
+	 *
+	 * `0` resolves the current transition, negative values resolve ancestors, and
+	 * positive values resolve descendants.
+	 */
+	depth: number;
+};
+
+export type ScreenTransitionTarget = ScreenTransitionDepthTarget;
+
+export type ScreenTransitionAccessor = (
+	target?: ScreenTransitionTarget,
+) => ScreenInterpolationProps | null;
+
 export interface ScreenInterpolationProps {
 	/**
 	 * Values for the screen that came before the current one in the navigation stack.
@@ -138,14 +197,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 +228,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.
@@ -193,6 +239,20 @@ export interface ScreenInterpolationProps {
 	 */
 	bounds: BoundsAccessor;
 
+	/**
+	 * Resolves interpolation props for this screen's transition timeline or an
+	 * ancestor transition timeline.
+	 *
+	 * Calling without a target returns the current transition.
+	 * `transition({ depth: -1 })` returns the immediate parent transition.
+	 * `transition({ depth: 1 })` returns the immediate child transition.
+	 * `transition({ depth: 0 })` returns the current transition.
+	 *
+	 * When called from a returned transition scope, targets are resolved relative
+	 * to that scope.
+	 */
+	transition: ScreenTransitionAccessor;
+
 	/**
 	 * The screen state that is currently driving the transition (either current or next, whichever is focused).
 	 */
@@ -238,7 +298,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 +324,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 +344,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 +363,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>;
@@ -185,4 +212,7 @@ export type BoundsAccessor = {
 	) => number;
 };
 
-export type BoundsInterpolationProps = Omit<ScreenInterpolationProps, "bounds">;
+export type BoundsInterpolationProps = Omit<
+	ScreenInterpolationProps,
+	"bounds" | "transition"
+>;

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

@@ -1,10 +1,56 @@
-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 GestureProgressMode = "progress-driven" | "freeform";
+
+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 +60,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 +79,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 +107,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 +136,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,14 @@ export type {
 	AnimationConfig,
 	ScreenInterpolationProps,
 	ScreenStyleInterpolator,
+	ScreenTransitionAccessor,
+	ScreenTransitionDepthTarget,
+	ScreenTransitionOptions,
 	ScreenTransitionState,
+	ScreenTransitionTarget,
 	TransitionInterpolatedStyle,
+	TransitionInterpolatorConfig,
+	TransitionInterpolatorOptions,
 	TransitionSlotStyle,
 	TransitionSpec,
 } from "./animation.types";
@@ -13,6 +19,7 @@ export type {
 	BoundsAccessor,
 	BoundsMethod,
 	BoundsNavigationAccessor,
+	BoundsNavigationRevealStyle,
 	BoundsNavigationZoomOpacityRange,
 	BoundsNavigationZoomOpacityRanges,
 	BoundsNavigationZoomOptions,
@@ -23,6 +30,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

@@ -3,7 +3,11 @@ import type {
 	ScreenStyleInterpolator,
 	TransitionSpec,
 } from "./animation.types";
-import type { GestureActivationArea, GestureDirection } from "./gesture.types";
+import type {
+	GestureActivationArea,
+	GestureDirection,
+	GestureProgressMode,
+} from "./gesture.types";
 import type { OverlayProps } from "./overlay.types";
 
 export type Layout = {
@@ -124,11 +128,6 @@ export type ScreenTransitionConfig = {
 	 */
 	navigationMaskEnabled?: boolean;
 
-	/**
-	 * @deprecated Use `navigationMaskEnabled` instead.
-	 */
-	maskEnabled?: boolean;
-
 	/**
 	 * Controls whether swipe-to-dismiss is enabled.
 	 *
@@ -138,10 +137,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 +186,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 +212,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;
@@ -182,8 +223,16 @@ export type ScreenTransitionConfig = {
 	 */
 	gestureResponseDistance?: number;
 
+	/**
+	 * Controls whether live gesture displacement drives transition progress or
+	 * stays available as freeform gesture values for custom interpolators.
+	 */
+	gestureProgressMode?: GestureProgressMode;
+
 	/**
 	 * Whether the gesture drives the progress.
+	 *
+	 * @deprecated Use `gestureProgressMode` instead.
 	 */
 	gestureDrivesProgress?: boolean;