react-native-screen-transitions 3.6.0-alpha.2 → 3.6.0-alpha.3

package/src/shared/providers/screen/animation/helpers/selected-interpolator-options.ts

@@ -59,6 +59,7 @@ const areInterpolatorOptionsEqual = (
 	if (!left || !right) return false;
 
 	return (
+		left.navigationMaskEnabled === right.navigationMaskEnabled &&
 		left.gestureEnabled === right.gestureEnabled &&
 		left.experimental_allowDisabledGestureTracking ===
 			right.experimental_allowDisabledGestureTracking &&

package/src/shared/providers/screen/animation/helpers/use-build-transition-state.ts

@@ -27,7 +27,7 @@ type BuiltState = {
 	route: BaseStackRoute;
 	meta?: Record<string, unknown>;
 	options: ScreenTransitionOptions;
-	navigationMaskEnabled: boolean;
+	optionsSlot: ScreenTransitionOptions;
 	targetProgress: SharedValue<number>;
 	logicalSettleFrameCount: SharedValue<number>;
 	resolvedAutoSnapPoint: SharedValue<number>;
@@ -44,7 +44,6 @@ export const useBuildTransitionState = (
 	const key = descriptor?.route?.key;
 	const meta = descriptor?.options?.meta;
 	const route = descriptor?.route;
-	const navigationMaskEnabled = !!descriptor?.options?.navigationMaskEnabled;
 	const snapPoints = descriptor?.options?.snapPoints;
 
 	return useMemo(() => {
@@ -81,20 +80,12 @@ export const useBuildTransitionState = (
 			route: plainRoute,
 			meta: plainMeta,
 			options: transitionOptions,
-			navigationMaskEnabled,
+			optionsSlot: {},
 			unwrapped: createScreenTransitionState(
 				plainRoute,
 				plainMeta,
-				navigationMaskEnabled,
 				transitionOptions,
 			),
 		};
-	}, [
-		key,
-		meta,
-		route,
-		snapPoints,
-		navigationMaskEnabled,
-		descriptor?.options,
-	]);
+	}, [key, meta, route, snapPoints, descriptor?.options]);
 };

package/src/shared/providers/screen/options/helpers.ts

@@ -206,6 +206,7 @@ const areScreenOptionsEqual = (
 ) => {
 	"worklet";
 	return (
+		left.navigationMaskEnabled === right.navigationMaskEnabled &&
 		left.gestureEnabled === right.gestureEnabled &&
 		left.experimental_allowDisabledGestureTracking ===
 			right.experimental_allowDisabledGestureTracking &&
@@ -238,6 +239,10 @@ export const resolveBaseScreenOptions = (
 	);
 
 	return {
+		navigationMaskEnabled: resolveBooleanOption(
+			options.navigationMaskEnabled,
+			undefined,
+		),
 		gestureEnabled: resolveBooleanOption(options.gestureEnabled, undefined),
 		experimental_allowDisabledGestureTracking: resolveBooleanOption(
 			options.experimental_allowDisabledGestureTracking,
@@ -322,6 +327,10 @@ export const syncScreenOptionsOverrides = (
 	);
 
 	const next: ScreenOptionsState = {
+		navigationMaskEnabled: resolveBooleanOption(
+			options?.navigationMaskEnabled,
+			base.navigationMaskEnabled,
+		),
 		gestureEnabled: resolveBooleanOption(
 			options?.gestureEnabled,
 			base.gestureEnabled,

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

@@ -9,6 +9,7 @@ export type OptionalScreenOption<K extends keyof ScreenTransitionOptions> =
 	ScreenTransitionOptions[K];
 
 export type ScreenOptionsSnapshot = {
+	navigationMaskEnabled: OptionalScreenOption<"navigationMaskEnabled">;
 	gestureEnabled: OptionalScreenOption<"gestureEnabled">;
 	experimental_allowDisabledGestureTracking: RequiredScreenOption<"experimental_allowDisabledGestureTracking">;
 	gestureDirection: RequiredScreenOption<"gestureDirection">;

package/src/shared/providers/stack/direct.provider.tsx

@@ -142,5 +142,5 @@ function withDirectStack<TProps extends DirectStackProps>(
 	};
 }
 
-export { withDirectStack };
 export type { DirectStackContextValue, DirectStackProps, DirectStackScene };
+export { withDirectStack };

package/src/shared/providers/stack/managed.provider.tsx

@@ -138,9 +138,9 @@ function withManagedStack<
 	};
 }
 
-export { useManagedStackContext, withManagedStack };
 export type {
 	ManagedStackContextValue,
 	ManagedStackProps,
 	ManagedStackRenderProps,
 };
+export { useManagedStackContext, withManagedStack };

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

@@ -23,6 +23,7 @@ import type { BaseStackRoute } from "./stack.types";
  */
 export type ScreenTransitionOptions = Pick<
 	ScreenTransitionConfig,
+	| "navigationMaskEnabled"
 	| "gestureEnabled"
 	| "experimental_allowDisabledGestureTracking"
 	| "gestureDirection"
@@ -227,6 +228,9 @@ export interface ScreenInterpolationProps {
 	/**
 	 * Whether the active transition is visually close enough to its target to be
 	 * treated as complete, even if the animation is still physically settling.
+	 *
+	 * @deprecated Use `active.logicallySettled` instead. Screen settlement state
+	 * belongs on the screen state object.
 	 */
 	logicallySettled: number;
 

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

@@ -14,6 +14,7 @@ import type {
 	TransitionInterpolatedStyle,
 	TransitionSlotStyle,
 } from "./animation.types";
+import type { GestureProgressMode } from "./gesture.types";
 
 /**
  * Target style computation.
@@ -161,11 +162,81 @@ export type BoundsNavigationZoomStyle = TransitionInterpolatedStyle & {
 	[NAVIGATION_MASK_ELEMENT_STYLE_ID]?: TransitionSlotStyle;
 };
 
+export type BoundsNavigationRevealOptions = {
+	/**
+	 * Destination mask border radius.
+	 *
+	 * Reveal interpolates from the measured source border radius to this value.
+	 *
+	 * @default Platform-specific reveal radius
+	 */
+	borderRadius?: number;
+	/**
+	 * Whether the reveal mask should use React Native's continuous border curve.
+	 *
+	 * @default true
+	 */
+	borderContinuous?: boolean;
+	/**
+	 * Maximum dynamic gesture sensitivity applied by reveal.
+	 *
+	 * Reveal lowers gesture sensitivity as the drag gets deeper so the masked
+	 * container can keep its source-to-destination handoff stable. This value
+	 * controls the starting/highest sensitivity in that curve.
+	 *
+	 * @default 0.8
+	 */
+	maxSensitivity?: number;
+	/**
+	 * Velocity-driven depth applied to the dismiss scale handoff.
+	 *
+	 * Higher values make fast releases orbit farther around the final source
+	 * scale. Set to `0` to remove the velocity depth effect.
+	 *
+	 * @default 0.5
+	 */
+	velocityDepth?: number;
+	/**
+	 * Whether gesture displacement should drive transition progress or remain as
+	 * freeform gesture values. Reveal defaults to `"freeform"` so drag can move
+	 * the masked container without owning the whole screen progress.
+	 *
+	 * @default "freeform"
+	 */
+	gestureProgressMode?: GestureProgressMode;
+	/**
+	 * Temporarily blocks pointer-event pass-through on the inactive content until
+	 * the source element transition handoff reaches progress `0.25`.
+	 *
+	 * This is intentional and most users cannot react fast enough to swipe during
+	 * that brief handoff. If it becomes an issue, set this to `false` to disable
+	 * the guard and keep the default behavior that allows pointer events to pass
+	 * through.
+	 *
+	 * @default true
+	 */
+	disablePointerEventsTillElementTransition?: boolean;
+	/**
+	 * How reveal should resize the navigation mask element.
+	 *
+	 * `"auto"` uses the platform default. Android defaults to transform-based
+	 * resizing to avoid masked-size animation cost, while other platforms animate
+	 * width and height. Transform-based resizing can make large border radii look
+	 * less natural on Android; use `"size"` to force width/height animation when
+	 * radius quality is more important than that optimization.
+	 *
+	 * @default "auto"
+	 */
+	maskSizingMode?: "auto" | "transform" | "size";
+};
+
 export type BoundsNavigationRevealStyle = BoundsNavigationZoomStyle;
 
 export type BoundsNavigationAccessor = {
 	zoom: (options?: BoundsNavigationZoomOptions) => BoundsNavigationZoomStyle;
-	reveal: () => BoundsNavigationRevealStyle;
+	reveal: (
+		options?: BoundsNavigationRevealOptions,
+	) => BoundsNavigationRevealStyle;
 };
 
 type BoundsBoundNavigationAccessor = {

package/src/shared/types/index.ts

@@ -15,6 +15,7 @@ export type {
 	BoundsAccessor,
 	BoundsMethod,
 	BoundsNavigationAccessor,
+	BoundsNavigationRevealOptions,
 	BoundsNavigationRevealStyle,
 	BoundsNavigationZoomOpacityRange,
 	BoundsNavigationZoomOpacityRanges,

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

@@ -27,13 +27,6 @@ export type ScreenLayouts = {
 	 * auto snap-point sizing. It is undefined until a real measurement exists.
 	 */
 	content?: Layout;
-	/**
-	 * Whether navigation bounds masking is enabled for this screen.
-	 *
-	 * When enabled, navigation zoom helpers target the masked container path
-	 * instead of the plain content slot.
-	 */
-	navigationMaskEnabled: boolean;
 };
 
 export type ScreenKey = string;
@@ -206,15 +199,12 @@ export type ScreenTransitionConfig = {
 	gestureReleaseVelocityScale?: number;
 
 	/**
-	 * Caps the absolute post-scale release velocity used by spring animations.
+	 * Deprecated compatibility option.
 	 *
-	 * This does NOT affect dismissal threshold decisions (`gestureVelocityImpact`)
-	 * or snap target selection (`snapVelocityImpact`). It only bounds release
-	 * animation intensity after `gestureReleaseVelocityScale` is applied.
+	 * This option is no longer read by the runtime transition options. Use
+	 * `gestureReleaseVelocityScale` to tune post-release spring energy.
 	 *
-	 * @deprecated v3 compatibility only. This option is removed in the next
-	 * gesture runtime.
-	 * @default 3.2
+	 * @deprecated v3 compatibility only.
 	 */
 	gestureReleaseVelocityMax?: number;
 

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

@@ -1,6 +1,7 @@
 import type {
 	BoundsAccessor,
 	BoundsInterpolationProps,
+	BoundsNavigationRevealOptions,
 	BoundsNavigationZoomOptions,
 } from "../../types/bounds.types";
 import { createBoundsAccessorCore } from "./helpers/create-bounds-accessor-core";
@@ -26,11 +27,12 @@ export const createBoundsAccessor = (
 							zoomOptions,
 						});
 					},
-					reveal: () => {
+					reveal: (revealOptions?: BoundsNavigationRevealOptions) => {
 						"worklet";
 						return buildRevealStyles({
 							props,
 							tag,
+							revealOptions,
 						});
 					},
 				},

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

@@ -9,6 +9,7 @@ import {
 	CONTENT_ENTERING_OPACITY_OUTPUT,
 	CONTENT_ENTERING_OPACITY_RANGE,
 	CONTENT_SHADOW_OPACITY_OUTPUT,
+	DISMISS_SCALE_ORBIT_DEPTH,
 	DRAG_MASK_HEIGHT_COLLAPSE_END,
 	HORIZONTAL_DRAG_MASK_COLLAPSE_SCALE,
 	IDENTITY_DRAG_SCALE_OUTPUT,
@@ -21,6 +22,7 @@ import {
 import {
 	interpolateClamped,
 	mixUnit,
+	resolveAspectRatioMaskHeight,
 	resolveDismissScaleHandoff,
 	resolveRevealContentBaseTransform,
 	resolveRevealDirectionalDragScale,
@@ -39,6 +41,7 @@ import type { BuildRevealStylesParams, RevealInterpolatedStyle } from "./types";
 export function buildRevealStyles({
 	tag,
 	props,
+	revealOptions,
 }: BuildRevealStylesParams): RevealInterpolatedStyle {
 	"worklet";
 
@@ -53,6 +56,19 @@ export function buildRevealStyles({
 		progress,
 		layouts: { screen: screenLayout },
 	} = props;
+	const borderRadius = revealOptions?.borderRadius ?? REVEAL_BORDER_RADIUS;
+	const borderContinuous = revealOptions?.borderContinuous ?? true;
+	const maxSensitivity = revealOptions?.maxSensitivity ?? 0.8;
+	const velocityDepth =
+		revealOptions?.velocityDepth ?? DISMISS_SCALE_ORBIT_DEPTH;
+	const gestureProgressMode = revealOptions?.gestureProgressMode ?? "freeform";
+	const disablePointerEventsTillElementTransition =
+		revealOptions?.disablePointerEventsTillElementTransition ?? true;
+	const maskSizingMode = revealOptions?.maskSizingMode ?? "auto";
+	const usesTransformMask =
+		maskSizingMode === "auto"
+			? REVEAL_USES_TRANSFORM_MASK
+			: maskSizingMode === "transform";
 
 	const boundsAccessor = createLinkAccessor(() => props);
 	const link = boundsAccessor.getLink(tag);
@@ -79,15 +95,15 @@ export function buildRevealStyles({
 			? Math.abs(props.active.gesture.raw.normY)
 			: 0;
 
-	const dragX =
-		props.active.gesture.x === 0
-			? 0
-			: resolveUnitDragTranslation(props.active.gesture.x, screenLayout.width);
+	const dragX = resolveUnitDragTranslation(
+		props.active.gesture.x,
+		screenLayout.width,
+	);
 
-	const dragY =
-		props.active.gesture.y === 0
-			? 0
-			: resolveUnitDragTranslation(props.active.gesture.y, screenLayout.height);
+	const dragY = resolveUnitDragTranslation(
+		props.active.gesture.y,
+		screenLayout.height,
+	);
 
 	const dragXScale = isHorizontalDismiss
 		? resolveRevealDirectionalDragScale(
@@ -130,9 +146,12 @@ export function buildRevealStyles({
 
 		const maskBorderRadius = mixUnit(
 			sourceBorderRadius,
-			REVEAL_BORDER_RADIUS,
+			borderRadius,
 			progress,
 		);
+		const maskBorderCurve = borderContinuous
+			? ("continuous" as const)
+			: undefined;
 
 		const maskSizeMultiplier = props.active.closing
 			? mixUnit(0.9, 1, props.active.progress)
@@ -148,19 +167,23 @@ export function buildRevealStyles({
 		if (props.active.gesture.dismissing) {
 			const contentTargetBounds =
 				initialDestinationTarget ?? link.destination.bounds;
+
 			const sourceContentScale = resolveUniformScale({
 				sourceWidth: link.source.bounds.width,
 				sourceHeight: link.source.bounds.height,
 				destinationWidth: contentTargetBounds.width,
 				destinationHeight: contentTargetBounds.height,
 			});
+
 			contentScale = resolveDismissScaleHandoff({
 				progress: props.active.progress,
 				releaseScale: dragScale,
 				targetScale: sourceContentScale,
 				velocity: props.active.gesture.velocity,
+				velocityDepth,
 			});
 		}
+
 		const contentTranslateX = contentRaw.translateX + dragX;
 		const contentTranslateY = contentRaw.translateY + dragY;
 
@@ -190,10 +213,13 @@ export function buildRevealStyles({
 					)
 				: 0;
 
-		const minMaskHeight = Math.min(
+		const maskAspectBounds = link.initialSource?.bounds ?? link.source.bounds;
+		const minMaskHeight = resolveAspectRatioMaskHeight({
+			maskWidth,
 			maskHeight,
-			Math.max(maskWidth, link.source.bounds.height),
-		);
+			targetWidth: maskAspectBounds.width,
+			targetHeight: maskAspectBounds.height,
+		});
 
 		const renderedMaskHeight = interpolateClamped(
 			maskHeightCollapseDrag,
@@ -242,12 +268,12 @@ export function buildRevealStyles({
 			compensatedMaskTranslateX + (maskWidth - maskBaseWidth) / 2;
 		const transformMaskTranslateY =
 			compensatedMaskTranslateY + (renderedMaskHeight - maskBaseHeight) / 2;
-		const maskElementStyle = REVEAL_USES_TRANSFORM_MASK
+		const maskElementStyle = usesTransformMask
 			? {
 					width: maskBaseWidth,
 					height: maskBaseHeight,
 					borderRadius: props.active.settled ? 0 : maskBorderRadius,
-					borderCurve: "continuous" as const,
+					borderCurve: maskBorderCurve,
 					transform: [
 						{ translateX: transformMaskTranslateX },
 						{ translateY: transformMaskTranslateY },
@@ -259,7 +285,7 @@ export function buildRevealStyles({
 					width: maskWidth,
 					height: renderedMaskHeight,
 					borderRadius: props.active.settled ? 0 : maskBorderRadius,
-					borderCurve: "continuous" as const,
+					borderCurve: maskBorderCurve,
 					transform: [
 						{ translateX: compensatedMaskTranslateX },
 						{ translateY: compensatedMaskTranslateY },
@@ -295,11 +321,15 @@ export function buildRevealStyles({
 			: 0;
 
 		const { gestureSensitivity, gestureReleaseVelocityScale } =
-			resolveRevealGestureHandoff(rawDrag);
+			resolveRevealGestureHandoff({
+				rawDrag,
+				maxSensitivity,
+			});
 
 		return {
 			options: {
-				gestureProgressMode: "freeform",
+				navigationMaskEnabled: true,
+				gestureProgressMode,
 				gestureSensitivity,
 				gestureReleaseVelocityScale,
 			},
@@ -374,6 +404,7 @@ export function buildRevealStyles({
 			releaseScale: dragScale,
 			targetScale: trackingTargetScale,
 			velocity: props.active.gesture.velocity,
+			velocityDepth,
 		});
 	}
 	const trackingContentTranslateX =
@@ -393,18 +424,21 @@ export function buildRevealStyles({
 
 	return {
 		options: {
-			gestureProgressMode: "freeform",
+			navigationMaskEnabled: true,
+			gestureProgressMode,
 		},
 		content: {
 			style: {
 				transform: [{ scale: unfocusedContentScale }],
 			},
-			props: {
-				pointerEvents:
-					props.active.progress <= CLOSE_SOURCE_HANDOFF_PROGRESS
-						? "auto"
-						: "none",
-			},
+			props: disablePointerEventsTillElementTransition
+				? {
+						pointerEvents:
+							props.active.progress <= CLOSE_SOURCE_HANDOFF_PROGRESS
+								? "auto"
+								: "none",
+					}
+				: undefined,
 		},
 		[link.id]: {
 			style: {

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

@@ -3,7 +3,6 @@ import { EPSILON } from "../../../../constants";
 import type { Layout } from "../../../../types/screen.types";
 import { computeContentTransformGeometry } from "../../helpers/geometry";
 import {
-	DISMISS_SCALE_ORBIT_DEPTH,
 	DRAG_DIRECTIONAL_SCALE_EXPONENT,
 	DRAG_DIRECTIONAL_SCALE_MAX,
 	DRAG_DIRECTIONAL_SCALE_MIN,
@@ -98,11 +97,17 @@ export function resolveUniformScale({
 	return aspectDifference < 0.1 ? Math.max(sx, sy) : Math.min(sx, sy);
 }
 
-export function resolveRevealGestureHandoff(rawDrag: number) {
+export function resolveRevealGestureHandoff({
+	rawDrag,
+	maxSensitivity,
+}: {
+	rawDrag: number;
+	maxSensitivity: number;
+}) {
 	"worklet";
 
 	const clampedRawDrag = clampUnit(rawDrag);
-	const gestureSensitivity = mixUnit(0.8, 0.1, clampedRawDrag);
+	const gestureSensitivity = mixUnit(maxSensitivity, 0.1, clampedRawDrag);
 
 	const releaseBoost = mixUnit(1, 1.1, clampedRawDrag);
 
@@ -125,11 +130,13 @@ export function resolveDismissScaleHandoff({
 	releaseScale,
 	targetScale,
 	velocity,
+	velocityDepth,
 }: {
 	progress: number;
 	releaseScale: number;
 	targetScale: number;
 	velocity: number;
+	velocityDepth: number;
 }) {
 	"worklet";
 
@@ -137,12 +144,35 @@ export function resolveDismissScaleHandoff({
 	const scaleProgress = Math.sin((Math.PI / 2) * closeProgress);
 	const baseScale = releaseScale + (targetScale - releaseScale) * scaleProgress;
 
-	const orbitDepth = DISMISS_SCALE_ORBIT_DEPTH * velocity;
+	const orbitDepth = velocityDepth * velocity;
 	const orbitScale = 1 - orbitDepth * Math.sin(Math.PI * closeProgress);
 
 	return baseScale * orbitScale;
 }
 
+export function resolveAspectRatioMaskHeight({
+	maskWidth,
+	maskHeight,
+	targetWidth,
+	targetHeight,
+}: {
+	maskWidth: number;
+	maskHeight: number;
+	targetWidth: number;
+	targetHeight: number;
+}) {
+	"worklet";
+
+	const safeMaskWidth = Math.max(1, Math.abs(maskWidth));
+	const safeMaskHeight = Math.max(1, Math.abs(maskHeight));
+	const safeTargetWidth = Math.max(Math.abs(targetWidth), EPSILON);
+	const safeTargetHeight = Math.max(Math.abs(targetHeight), EPSILON);
+	const targetAspectHeight =
+		safeMaskWidth * (safeTargetHeight / safeTargetWidth);
+
+	return Math.min(safeMaskHeight, Math.max(1, targetAspectHeight));
+}
+
 function getBoundsCenterX(bounds: MeasuredDimensions) {
 	"worklet";
 	return bounds.pageX + bounds.width / 2;

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

@@ -4,6 +4,7 @@ import {
 } from "../../../../constants";
 import type {
 	BoundsInterpolationProps,
+	BoundsNavigationRevealOptions,
 	BoundsNavigationRevealStyle,
 } from "../../../../types/bounds.types";
 
@@ -15,4 +16,5 @@ export type RevealInterpolatedStyle = BoundsNavigationRevealStyle & {
 export type BuildRevealStylesParams = {
 	tag?: string;
 	props: BoundsInterpolationProps;
+	revealOptions?: BoundsNavigationRevealOptions;
 };

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

@@ -168,7 +168,7 @@ export function buildZoomStyles({
 			style: VISIBLE_STYLE,
 		},
 	} satisfies TransitionInterpolatedStyle;
-	const focusedContentSlot = props.current.layouts.navigationMaskEnabled
+	const focusedContentSlot = props.current.options.navigationMaskEnabled
 		? NAVIGATION_MASK_CONTAINER_STYLE_ID
 		: "content";
 
@@ -325,7 +325,7 @@ export function buildZoomStyles({
 			...sourceVisibilityStyle,
 		};
 
-		if (props.current.layouts.navigationMaskEnabled) {
+		if (props.current.options.navigationMaskEnabled) {
 			focusedStyles[NAVIGATION_MASK_ELEMENT_STYLE_ID] = {
 				style: {
 					width: maskWidth,