react-native-screen-transitions 3.9.0-beta.1 → 3.9.0-beta.3

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

@@ -1,4 +1,4 @@
-import type { MeasuredDimensions } from "react-native-reanimated";
+import type { ColorValue } from "react-native";
 import {
 	NAVIGATION_MASK_CONTAINER_STYLE_ID,
 	NAVIGATION_MASK_ELEMENT_STYLE_ID,
@@ -7,11 +7,11 @@ import type { BoundsLink } from "../stores/bounds/types";
 import type {
 	BoundsComputeOptions,
 	BoundsIdentityInput,
-	BoundsMathResult,
 	BoundsMotion,
 	BoundsMotionFrame,
 	BoundsMotionTransform,
 	BoundsStyleResult,
+	BoundsValuesResult,
 } from "../utils/bounds/types/options";
 import type {
 	ScreenInterpolationProps,
@@ -31,78 +31,142 @@ export type { BoundsLink, BoundsLinkStatus } from "../stores/bounds/types";
  */
 export type BoundsMethod = "transform" | "size" | "content";
 
+/**
+ * Axis-specific response intensity used by {@linkcode BoundsNavigationZoomDragOptions}.
+ *
+ * `0` disables the response on an axis, `1` preserves the native zoom preset,
+ * and values above `1` exaggerate it.
+ */
+export type BoundsNavigationZoomAxisResponse = {
+	/** Horizontal gesture response multiplier. @default 1 */
+	horizontal?: number;
+	/** Vertical gesture response multiplier. @default 1 */
+	vertical?: number;
+};
+
+/**
+ * Adjusts the intensity of zoom's native drag behavior without replacing its
+ * built-in curves.
+ *
+ * @see {@linkcode BoundsNavigationZoomOptions.drag}
+ */
+export type BoundsNavigationZoomDragOptions = {
+	/**
+	 * Multiplies the native rendered translation.
+	 *
+	 * @default { horizontal: 1, vertical: 1 }
+	 */
+	translation?: BoundsNavigationZoomAxisResponse;
+	/**
+	 * Multiplies the native scale displacement from `1`.
+	 *
+	 * @default { horizontal: 1, vertical: 1 }
+	 */
+	scale?: BoundsNavigationZoomAxisResponse;
+};
+
+/**
+ * Legacy zoom opacity interpolation tuple.
+ *
+ * @deprecated Zoom opacity ownership now follows the native preset.
+ */
+export type BoundsNavigationZoomOpacityRange = readonly [
+	inputStart: number,
+	inputEnd: number,
+	outputStart?: number,
+	outputEnd?: number,
+];
+
+/**
+ * Legacy opening and closing zoom opacity ranges.
+ *
+ * @deprecated Zoom opacity ownership now follows the native preset.
+ */
+export type BoundsNavigationZoomOpacityRanges = {
+	open?: BoundsNavigationZoomOpacityRange;
+	close?: BoundsNavigationZoomOpacityRange;
+};
+
 export type BoundsNavigationZoomOptions = {
-	target?: "bound" | "fullscreen" | MeasuredDimensions;
-	debug?: boolean;
-	borderRadius?: number;
 	/**
-	 * Focused-screen element opacity curve.
+	 * Geometry that the zoomed content should resolve against.
+	 *
+	 * `"bound"` uses the paired destination boundary. `"fullscreen"` uses the
+	 * screen, and measured dimensions provide an explicit target rectangle.
+	 * When omitted, zoom keeps its native full-width aspect-ratio target.
+	 */
+	target?: BoundsComputeOptions["target"];
+	/**
+	 * Keeps the focused screen content visible throughout the zoom.
 	 *
-	 * `open` is used while presenting the destination screen.
-	 * `close` is used while returning to the source screen.
+	 * Enable this for handed-off or live content that should not use zoom's
+	 * built-in focused-content opacity fade.
 	 *
-	 * Tuple order:
-	 * - `inputStart`: transition progress start
-	 * - `inputEnd`: transition progress end
-	 * - `outputStart`: opacity at `inputStart` (defaults to built-in preset)
-	 * - `outputEnd`: opacity at `inputEnd` (defaults to built-in preset)
+	 * @default false
 	 */
-	focusedElementOpacity?: BoundsNavigationZoomOpacityRanges;
+	keepFocusedVisible?: boolean;
 	/**
-	 * Unfocused-screen matched element opacity curve.
+	 * Expanded transition clipping radius.
 	 *
-	 * `open` is used while the previous screen animates out during present.
-	 * `close` is used while the previous screen animates back in during dismiss.
+	 * Zoom interpolates from the measured source radius to this value while the
+	 * screen is animating. This controls the visible clipping result regardless
+	 * of whether a navigation mask is enabled.
 	 *
-	 * Tuple order:
-	 * - `inputStart`: transition progress start
-	 * - `inputEnd`: transition progress end
-	 * - `outputStart`: opacity at `inputStart` (defaults to built-in preset)
-	 * - `outputEnd`: opacity at `inputEnd` (defaults to built-in preset)
+	 * @default 64
 	 */
-	unfocusedElementOpacity?: BoundsNavigationZoomOpacityRanges;
+	borderRadius?: number;
 	/**
-	 * Scale applied to the unfocused background content while the focused bound
-	 * animates above it.
+	 * Scale applied to the unfocused screen while the zoom runs above it.
+	 *
+	 * @default 0.9375
 	 */
 	backgroundScale?: number;
 	/**
-	 * Maximum dynamic gesture sensitivity applied by zoom.
-	 *
-	 * Zoom lowers gesture sensitivity as the drag gets deeper so the content
-	 * handoff stays stable. This value controls the starting/highest sensitivity
-	 * in that curve.
+	 * Color rendered behind the focused zoom content.
 	 *
-	 * @default 0.8
+	 * @default "black"
 	 */
-	maxSensitivity?: number;
+	backdropColor?: ColorValue;
 	/**
-	 * Velocity-driven depth applied to the dismiss scale handoff.
+	 * Maximum opacity reached by the zoom backdrop.
 	 *
-	 * Higher values make fast releases orbit farther around the final scale. Set
-	 * to `0` to remove the velocity depth effect.
+	 * Values are clamped between `0` and `1`.
 	 *
-	 * @default 0.5
+	 * @default 0.45
+	 */
+	backdropOpacity?: number;
+	/**
+	 * Native drag-response intensity controls.
+	 */
+	drag?: BoundsNavigationZoomDragOptions;
+	/**
+	 * @deprecated Ignored. Zoom no longer exposes a transition-specific debug
+	 * overlay.
+	 */
+	debug?: boolean;
+	/**
+	 * @deprecated Ignored. Zoom opacity ownership now follows the native preset.
+	 */
+	focusedElementOpacity?: BoundsNavigationZoomOpacityRanges;
+	/**
+	 * @deprecated Ignored. Zoom opacity ownership now follows the native preset.
+	 */
+	unfocusedElementOpacity?: BoundsNavigationZoomOpacityRanges;
+	/**
+	 * @deprecated Ignored. Zoom now owns its gesture sensitivity curve.
+	 */
+	maxSensitivity?: number;
+	/**
+	 * @deprecated Ignored. Zoom now owns its velocity-depth behavior.
 	 */
 	velocityDepth?: number;
 	/**
-	 * Deprecated compatibility option.
-	 *
-	 * Gesture movement now always contributes to `progress`; use `transitionProgress`
-	 * when a recipe needs transition progress without live gesture contribution.
-	 * The zoom helper no longer reads this option.
-	 *
-	 * @deprecated Use `transitionProgress` from interpolation state instead.
+	 * @deprecated Ignored. Gesture movement always contributes to `progress`.
 	 */
 	gestureProgressMode?: GestureProgressMode;
 	/**
-	 * Horizontal gesture drag scaling curve, applied when the active dismiss
-	 * direction is horizontal.
-	 *
-	 * Tuple order:
-	 * - `shrinkMin`: minimum scale when dragging toward dismissal
-	 * - `growMax`: maximum scale when dragging opposite dismissal
-	 * - `exponent`: curve exponent controlling how quickly scaling ramps
+	 * @deprecated Ignored. Use `drag.scale.horizontal` to adjust response
+	 * intensity without replacing the native curve.
 	 */
 	horizontalDragScale?: readonly [
 		shrinkMin: number,
@@ -110,13 +174,8 @@ export type BoundsNavigationZoomOptions = {
 		exponent?: number,
 	];
 	/**
-	 * Vertical gesture drag scaling curve, applied when the active dismiss
-	 * direction is vertical.
-	 *
-	 * Tuple order:
-	 * - `shrinkMin`: minimum scale when dragging toward dismissal
-	 * - `growMax`: maximum scale when dragging opposite dismissal
-	 * - `exponent`: curve exponent controlling how quickly scaling ramps
+	 * @deprecated Ignored. Use `drag.scale.vertical` to adjust response intensity
+	 * without replacing the native curve.
 	 */
 	verticalDragScale?: readonly [
 		shrinkMin: number,
@@ -124,17 +183,8 @@ export type BoundsNavigationZoomOptions = {
 		exponent?: number,
 	];
 	/**
-	 * Horizontal gesture drag translation curve.
-	 *
-	 * Tuple order:
-	 * - `negativeMax`: multiplier when dragging left / negative
-	 * - `positiveMax`: multiplier when dragging right / positive
-	 * - `exponent`: curve exponent controlling how quickly translation ramps
-	 *
-	 * Examples:
-	 * - `[0, 0]` disables horizontal drag translation
-	 * - `[0.5, 0.5]` halves horizontal drag travel
-	 * - `[1.2, 1.2]` amplifies horizontal drag travel
+	 * @deprecated Ignored. Use `drag.translation.horizontal` to adjust response
+	 * intensity without replacing the native curve.
 	 */
 	horizontalDragTranslation?: readonly [
 		negativeMax: number,
@@ -142,17 +192,8 @@ export type BoundsNavigationZoomOptions = {
 		exponent?: number,
 	];
 	/**
-	 * Vertical gesture drag translation curve.
-	 *
-	 * Tuple order:
-	 * - `negativeMax`: multiplier when dragging up / negative
-	 * - `positiveMax`: multiplier when dragging down / positive
-	 * - `exponent`: curve exponent controlling how quickly translation ramps
-	 *
-	 * Examples:
-	 * - `[0, 0]` disables vertical drag translation
-	 * - `[0.5, 0.5]` halves vertical drag travel
-	 * - `[1.2, 1.2]` amplifies vertical drag travel
+	 * @deprecated Ignored. Use `drag.translation.vertical` to adjust response
+	 * intensity without replacing the native curve.
 	 */
 	verticalDragTranslation?: readonly [
 		negativeMax: number,
@@ -161,18 +202,6 @@ export type BoundsNavigationZoomOptions = {
 	];
 };
 
-export type BoundsNavigationZoomOpacityRange = readonly [
-	inputStart: number,
-	inputEnd: number,
-	outputStart?: number,
-	outputEnd?: number,
-];
-
-export type BoundsNavigationZoomOpacityRanges = {
-	open?: BoundsNavigationZoomOpacityRange;
-	close?: BoundsNavigationZoomOpacityRange;
-};
-
 export type BoundsNavigationZoomStyle = TransitionInterpolatedStyle & {
 	content?: TransitionSlotStyle;
 	[NAVIGATION_MASK_CONTAINER_STYLE_ID]?: TransitionSlotStyle;
@@ -283,9 +312,16 @@ type BoundsBoundNavigationAccessor = {
 
 export type BoundsScopedAccessor = BoundsBoundNavigationAccessor & {
 	styles: (options?: BoundsComputeOptions) => BoundsStyleResult;
+	/** Returns numeric bounds values for custom style composition. */
+	values: <T extends BoundsComputeOptions = BoundsComputeOptions>(
+		options?: T,
+	) => BoundsValuesResult<T>;
+	/**
+	 * @deprecated Use {@linkcode values}.
+	 */
 	math: <T extends BoundsComputeOptions = BoundsComputeOptions>(
 		options?: T,
-	) => BoundsMathResult<T>;
+	) => BoundsValuesResult<T>;
 	link: (id?: BoundsIdentityInput) => BoundsLink | null;
 };
 

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

@@ -150,6 +150,8 @@ export type GestureHandoffValues = {
 	normScale: number;
 	focalX: number;
 	focalY: number;
+	pinchOriginX: number;
+	pinchOriginY: number;
 	rotation: number;
 	raw: RawGestureValues;
 	/**
@@ -202,6 +204,14 @@ export type GestureValues = {
 	 * The live pinch focal point y-position in screen coordinates.
 	 */
 	focalY: number;
+	/**
+	 * The pinch focal point x-position captured when the gesture activated.
+	 */
+	pinchOriginX: number;
+	/**
+	 * The pinch focal point y-position captured when the gesture activated.
+	 */
+	pinchOriginY: number;
 	/**
 	 * The live two-finger rotation in radians.
 	 */

package/src/shared/types/index.ts

@@ -25,6 +25,8 @@ export type {
 	BoundsNavigationAccessor,
 	BoundsNavigationRevealOptions,
 	BoundsNavigationRevealStyle,
+	BoundsNavigationZoomAxisResponse,
+	BoundsNavigationZoomDragOptions,
 	BoundsNavigationZoomOpacityRange,
 	BoundsNavigationZoomOpacityRanges,
 	BoundsNavigationZoomOptions,

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

@@ -113,14 +113,30 @@ export const animateToProgress = ({
 					entering.set(FALSE);
 				}
 
-				if (onAnimationFinish) {
-					runOnJS(onAnimationFinish)(state.finished);
-				}
-
-				// Delay clearing progress animation by one frame to ensure final frame is painted
-				requestAnimationFrame(() => {
+				if (isClosing) {
 					progressAnimating.set(FALSE);
-				});
+
+					if (onAnimationFinish) {
+						// Paint the terminal UI-thread host/style state before React
+						// removes the closing route and its native portal host.
+						requestAnimationFrame(() => {
+							"worklet";
+							requestAnimationFrame(() => {
+								"worklet";
+								runOnJS(onAnimationFinish)(state.finished);
+							});
+						});
+					}
+				} else {
+					if (onAnimationFinish) {
+						runOnJS(onAnimationFinish)(state.finished);
+					}
+
+					// Delay clearing progress animation by one frame to ensure final frame is painted
+					requestAnimationFrame(() => {
+						progressAnimating.set(FALSE);
+					});
+				}
 			}),
 		);
 	};

package/src/shared/utils/bounds/helpers/create-bounds-accessor-core.ts

@@ -7,8 +7,8 @@ import type {
 	BoundsComputeOptions,
 	BoundsIdentity,
 	BoundsIdentityInput,
-	BoundsMathResult,
 	BoundsStyleResult,
+	BoundsValuesResult,
 } from "../types/options";
 import { createBoundTag, normalizeBoundIdentity } from "./create-bound-tag";
 import { createLinkAccessor } from "./create-link-accessor";
@@ -46,6 +46,20 @@ const createBoundsAccessorParts = ({
 			id: normalizedIdentity.id,
 			group: normalizedIdentity.group,
 		});
+		const getValues = <T extends BoundsComputeOptions = BoundsComputeOptions>(
+			options?: T,
+		): BoundsValuesResult<T> => {
+			"worklet";
+			return prepareBoundStyles({
+				props,
+				options: {
+					...options,
+					id: normalizedIdentity.id,
+					group: normalizedIdentity.group,
+					raw: true,
+				},
+			}) as BoundsValuesResult<T>;
+		};
 
 		const scoped: BoundsScopedAccessor = {
 			styles: (options?: BoundsComputeOptions): BoundsStyleResult => {
@@ -59,19 +73,12 @@ const createBoundsAccessorParts = ({
 					},
 				}) as BoundsStyleResult;
 			},
+			values: getValues,
 			math: <T extends BoundsComputeOptions = BoundsComputeOptions>(
 				options?: T,
-			): BoundsMathResult<T> => {
+			) => {
 				"worklet";
-				return prepareBoundStyles({
-					props,
-					options: {
-						...options,
-						id: normalizedIdentity.id,
-						group: normalizedIdentity.group,
-						raw: true,
-					},
-				}) as BoundsMathResult<T>;
+				return getValues(options);
 			},
 			link: (id?: BoundsIdentityInput) => {
 				"worklet";

package/src/shared/utils/bounds/navigation/reveal/build.ts

@@ -133,14 +133,14 @@ export function buildRevealStyles({
 	/* ----------------------------- Focused Screen ----------------------------- */
 
 	if (focused) {
-		const contentRaw = scopedBounds.math({
+		const contentRaw = scopedBounds.values({
 			scaleMode: "uniform",
 			method: "content",
 			target: initialDestinationTarget,
 			progress: transitionProgress,
 		});
 
-		const maskRaw = scopedBounds.math({
+		const maskRaw = scopedBounds.values({
 			scaleMode: "uniform",
 			method: "size",
 			space: "absolute",

package/src/shared/utils/bounds/navigation/reveal/math.ts

@@ -141,7 +141,8 @@ export function resolveDismissScaleHandoff({
 	"worklet";
 
 	const closeProgress = 1 - progress;
-	const scaleProgress = Math.sin((Math.PI / 2) * closeProgress);
+	const easeIn = 1 - Math.cos((Math.PI / 2) * closeProgress);
+	const scaleProgress = easeIn ** 2;
 	const baseScale = releaseScale + (targetScale - releaseScale) * scaleProgress;
 
 	const orbitDepth = velocityDepth * velocity;