react-native-screen-transitions 3.8.0-beta.0 → 3.8.0-beta.1

package/src/shared/stores/gesture.store.ts

@@ -19,6 +19,30 @@ type GestureRawStoreMap = {
 	rotation: SharedValue<number>;
 };
 
+type GestureSnapshotStoreMap = {
+	x: SharedValue<number>;
+	y: SharedValue<number>;
+	normX: SharedValue<number>;
+	normY: SharedValue<number>;
+	velocity: SharedValue<number>;
+	scale: SharedValue<number>;
+	normScale: SharedValue<number>;
+	focalX: SharedValue<number>;
+	focalY: SharedValue<number>;
+	rotation: SharedValue<number>;
+	raw: GestureRawStoreMap;
+	active: SharedValue<ActiveGesture | null>;
+	direction: SharedValue<ResolvedPanGestureDirection | null>;
+};
+
+type GestureInternalStoreMap = {
+	progressBaseline: SharedValue<number>;
+	progressDeltaX: SharedValue<number>;
+	progressDeltaY: SharedValue<number>;
+	lockedSnapPoint: SharedValue<number | null>;
+	snapshot: GestureSnapshotStoreMap;
+};
+
 export type GestureStoreMap = {
 	x: SharedValue<number>;
 	y: SharedValue<number>;
@@ -31,6 +55,7 @@ export type GestureStoreMap = {
 	focalY: SharedValue<number>;
 	rotation: SharedValue<number>;
 	raw: GestureRawStoreMap;
+	internal: GestureInternalStoreMap;
 	dismissing: SharedValue<number>;
 	dragging: SharedValue<number>;
 	settling: SharedValue<number>;
@@ -57,6 +82,10 @@ export type GestureStoreMap = {
 };
 
 function createGestureBag(): GestureStoreMap {
+	const progressBaseline = makeMutable(0);
+	const progressDeltaX = makeMutable(0);
+	const progressDeltaY = makeMutable(0);
+	const lockedSnapPoint = makeMutable<number | null>(null);
 	const normX = makeMutable(0);
 	const normY = makeMutable(0);
 	const scale = makeMutable(1);
@@ -86,6 +115,35 @@ function createGestureBag(): GestureStoreMap {
 			normScale: makeMutable(0),
 			rotation: makeMutable(0),
 		},
+		internal: {
+			progressBaseline,
+			progressDeltaX,
+			progressDeltaY,
+			lockedSnapPoint,
+			snapshot: {
+				x: makeMutable(0),
+				y: makeMutable(0),
+				normX: makeMutable(0),
+				normY: makeMutable(0),
+				velocity: makeMutable(0),
+				scale: makeMutable(1),
+				normScale: makeMutable(0),
+				focalX: makeMutable(0),
+				focalY: makeMutable(0),
+				rotation: makeMutable(0),
+				raw: {
+					x: makeMutable(0),
+					y: makeMutable(0),
+					normX: makeMutable(0),
+					normY: makeMutable(0),
+					scale: makeMutable(1),
+					normScale: makeMutable(0),
+					rotation: makeMutable(0),
+				},
+				active: makeMutable<ActiveGesture | null>(null),
+				direction: makeMutable<ResolvedPanGestureDirection | null>(null),
+			},
+		},
 		dismissing,
 		dragging,
 		settling,
@@ -127,6 +185,29 @@ export const GestureStore = createStore<GestureStoreMap>({
 		cancelAnimation(bag.raw.scale);
 		cancelAnimation(bag.raw.normScale);
 		cancelAnimation(bag.raw.rotation);
+		cancelAnimation(bag.internal.progressBaseline);
+		cancelAnimation(bag.internal.progressDeltaX);
+		cancelAnimation(bag.internal.progressDeltaY);
+		cancelAnimation(bag.internal.lockedSnapPoint);
+		cancelAnimation(bag.internal.snapshot.x);
+		cancelAnimation(bag.internal.snapshot.y);
+		cancelAnimation(bag.internal.snapshot.normX);
+		cancelAnimation(bag.internal.snapshot.normY);
+		cancelAnimation(bag.internal.snapshot.velocity);
+		cancelAnimation(bag.internal.snapshot.scale);
+		cancelAnimation(bag.internal.snapshot.normScale);
+		cancelAnimation(bag.internal.snapshot.focalX);
+		cancelAnimation(bag.internal.snapshot.focalY);
+		cancelAnimation(bag.internal.snapshot.rotation);
+		cancelAnimation(bag.internal.snapshot.raw.x);
+		cancelAnimation(bag.internal.snapshot.raw.y);
+		cancelAnimation(bag.internal.snapshot.raw.normX);
+		cancelAnimation(bag.internal.snapshot.raw.normY);
+		cancelAnimation(bag.internal.snapshot.raw.scale);
+		cancelAnimation(bag.internal.snapshot.raw.normScale);
+		cancelAnimation(bag.internal.snapshot.raw.rotation);
+		cancelAnimation(bag.internal.snapshot.active);
+		cancelAnimation(bag.internal.snapshot.direction);
 		cancelAnimation(bag.dismissing);
 		cancelAnimation(bag.dragging);
 		cancelAnimation(bag.settling);

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

@@ -48,6 +48,15 @@ export type ScreenTransitionState = {
 	 */
 	progress: number;
 
+	/**
+	 * Transition progress without live gesture contribution.
+	 *
+	 * `progress` is always the visual progress, including live pan or pinch
+	 * movement. Use `transitionProgress` when an interpolator needs the committed
+	 * transition progress as if the current gesture were not active.
+	 */
+	transitionProgress: number;
+
 	/**
 	 * Whether this screen is in the process of being dismissed.
 	 * - `0`: Screen is opening or active

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

@@ -98,11 +98,13 @@ export type BoundsNavigationZoomOptions = {
 	 */
 	velocityDepth?: number;
 	/**
-	 * Whether gesture displacement should drive transition progress or remain as
-	 * freeform gesture values. Zoom defaults to `"freeform"` so drag can move the
-	 * content without owning the whole screen progress.
+	 * Deprecated compatibility option.
 	 *
-	 * @default "freeform"
+	 * 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.
 	 */
 	gestureProgressMode?: GestureProgressMode;
 	/**
@@ -224,11 +226,13 @@ export type BoundsNavigationRevealOptions = {
 	 */
 	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.
+	 * Deprecated compatibility option.
+	 *
+	 * Gesture movement now always contributes to `progress`; use `transitionProgress`
+	 * when a recipe needs transition progress without live gesture contribution.
+	 * The reveal helper no longer reads this option.
 	 *
-	 * @default "freeform"
+	 * @deprecated Use `transitionProgress` from interpolation state instead.
 	 */
 	gestureProgressMode?: GestureProgressMode;
 	/**

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

@@ -134,6 +134,36 @@ export type RawGestureValues = {
 	rotation: number;
 };
 
+/**
+ * Gesture values used when a release hands off into a dismiss animation.
+ *
+ * These match live gesture values while a screen is not dismissing, then read
+ * from the release snapshot while dismissal is in flight.
+ */
+export type GestureHandoffValues = {
+	x: number;
+	y: number;
+	normX: number;
+	normY: number;
+	velocity: number;
+	scale: number;
+	normScale: number;
+	focalX: number;
+	focalY: number;
+	rotation: number;
+	raw: RawGestureValues;
+	/**
+	 * The gesture associated with the handoff values.
+	 */
+	active: ActiveGesture | null;
+	/**
+	 * The pan direction associated with the handoff values.
+	 *
+	 * @deprecated Use `active` instead.
+	 */
+	direction: ResolvedPanGestureDirection | null;
+};
+
 export type GestureValues = {
 	/**
 	 * The live horizontal translation of the gesture.
@@ -154,9 +184,6 @@ export type GestureValues = {
 	/**
 	 * A 0-1 scalar derived from the pan velocity magnitude, normalized against
 	 * a screen-relative full-flick threshold.
-	 *
-	 * This is live while dragging, frozen at release during dismiss animations,
-	 * and reset to 0 while idle or settling from a cancelled gesture.
 	 */
 	velocity: number;
 	/**
@@ -183,6 +210,24 @@ export type GestureValues = {
 	 * Physical gesture values before `gestureSensitivity` is applied.
 	 */
 	raw: RawGestureValues;
+	/**
+	 * The gesture that is currently active.
+	 */
+	active: ActiveGesture | null;
+	/**
+	 * The initial pan direction that activated the gesture.
+	 *
+	 * @deprecated Use `active` instead.
+	 */
+	direction: ResolvedPanGestureDirection | null;
+	/**
+	 * Gesture values latched at the release boundary for animation handoff.
+	 *
+	 * While dragging, these values match the live gesture values. During a
+	 * dismissing release, they read from the release snapshot so live gesture
+	 * values can reset without breaking handoff animations.
+	 */
+	handoff: GestureHandoffValues;
 	/**
 	 * A flag indicating if the screen is in the process of dismissing (0 or 1).
 	 */
@@ -195,17 +240,6 @@ export type GestureValues = {
 	 * 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: ResolvedPanGestureDirection | null;
-
 	/** @deprecated Use `normX` instead. */
 	normalizedX: number;
 	/** @deprecated Use `normY` instead. */

package/src/shared/types/index.ts

@@ -33,9 +33,11 @@ export type {
 	GestureDirectionConfig,
 	GestureDirectionEntry,
 	GestureDirectionOption,
+	GestureHandoffValues,
 	GestureValues,
 	PanGestureDirection,
 	PinchGestureDirection,
+	RawGestureValues,
 	ScrollGestureAxis,
 	ScrollGestureAxisState,
 	ScrollGestureState,

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

@@ -222,11 +222,11 @@ export type ScreenTransitionConfig = {
 	gestureSnapVelocityImpact?: number;
 
 	/**
-	 * Multiplies gesture release velocity used for spring animation energy.
+	 * Multiplies gesture release velocity used for gesture reset/handoff energy.
 	 *
 	 * This does NOT affect dismissal threshold decisions (`gestureVelocityImpact`)
-	 * or snap target selection (`snapVelocityImpact`). It only changes how fast
-	 * the post-release animation feels.
+	 * or snap target selection (`snapVelocityImpact`). It changes the release
+	 * impulse used by gesture values and interpolator handoff values.
 	 *
 	 * @default 1
 	 */
@@ -243,20 +243,37 @@ export type ScreenTransitionConfig = {
 	gestureReleaseVelocityMax?: number;
 
 	/**
-	 * Distance threshold for gesture recognition throughout the screen.
+	 * Deprecated compatibility option.
+	 *
+	 * Overrides the default edge-start distance when `gestureDirection` uses
+	 * `area: "edge"`. Prefer a numeric `area` on each `gestureDirection` entry.
+	 *
+	 * @example
+	 * gestureDirection: { gesture: "horizontal", area: 24 }
+	 *
+	 * @deprecated Use numeric `gestureDirection` entry `area` instead.
 	 */
 	gestureResponseDistance?: number;
 
 	/**
-	 * Controls whether live gesture displacement drives transition progress or
-	 * stays available as freeform gesture values for custom interpolators.
+	 * Deprecated compatibility option.
+	 *
+	 * Gesture movement now always contributes to `progress`. Use `transitionProgress`
+	 * in interpolators when you need transition progress without live gesture
+	 * contribution.
+	 *
+	 * @deprecated Use `transitionProgress` from interpolation state instead.
 	 */
 	gestureProgressMode?: GestureProgressMode;
 
 	/**
-	 * Whether the gesture drives the progress.
+	 * Deprecated compatibility alias for `gestureProgressMode`.
+	 *
+	 * Gesture movement now always contributes to `progress`. Use `transitionProgress`
+	 * in interpolators when you need transition progress without live gesture
+	 * contribution.
 	 *
-	 * @deprecated Use `gestureProgressMode` instead.
+	 * @deprecated Use `transitionProgress` from interpolation state instead.
 	 */
 	gestureDrivesProgress?: boolean;
 

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

@@ -68,7 +68,7 @@ export const animateToProgress = ({
 			: config;
 
 	const {
-		progress,
+		transitionProgress,
 		willAnimate,
 		progressAnimating,
 		progressSettled,
@@ -87,7 +87,7 @@ export const animateToProgress = ({
 		if (!config) {
 			progressAnimating.set(FALSE);
 			progressSettled.set(TRUE);
-			progress.set(value);
+			transitionProgress.set(value);
 			if (shouldClearEnteringOnFinish) {
 				entering.set(FALSE);
 			}
@@ -100,7 +100,7 @@ export const animateToProgress = ({
 
 		progressAnimating.set(TRUE); //<-- Do not move this into the callback
 		progressSettled.set(FALSE);
-		progress.set(
+		transitionProgress.set(
 			animate(value, effectiveConfig, (state) => {
 				"worklet";
 				if (state.settled) {

package/src/shared/utils/bounds/helpers/prepare-bound-styles.ts

@@ -99,7 +99,7 @@ export const prepareBoundStyles = <T extends BoundsOptions>({
 			previous: props.previous,
 			current: props.current,
 			next: props.next,
-			progress: props.progress,
+			progress: resolved.progress ?? props.progress,
 			dimensions: props.layouts.screen,
 		},
 		resolved,

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

@@ -1,6 +1,6 @@
 import { interpolate } from "react-native-reanimated";
 import { NAVIGATION_MASK_ELEMENT_STYLE_ID } from "../../../../constants";
-import { createLinkAccessor } from "../../helpers/create-link-accessor";
+import { createBoundsAccessorCore } from "../../helpers/create-bounds-accessor-core";
 import { getSourceBorderRadius } from "../helpers";
 import {
 	CLOSE_SOURCE_HANDOFF_PROGRESS,
@@ -54,15 +54,16 @@ export function buildRevealStyles({
 
 	const {
 		focused,
-		progress,
 		layouts: { screen: screenLayout },
 	} = props;
+	const transitionProgress =
+		props.current.transitionProgress + (props.next?.transitionProgress ?? 0);
+	const activeTransitionProgress = props.active.transitionProgress;
 	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";
@@ -75,8 +76,11 @@ export function buildRevealStyles({
 			? REVEAL_USES_TRANSFORM_MASK
 			: maskSizingMode === "transform";
 
-	const boundsAccessor = createLinkAccessor(() => props);
-	const link = boundsAccessor.getLink(tag);
+	const bounds = createBoundsAccessorCore({
+		getProps: () => props,
+	});
+	const scopedBounds = bounds({ id: tag });
+	const link = scopedBounds.getLink();
 
 	if (!link?.source?.bounds || !link.destination?.bounds) {
 		return {};
@@ -86,8 +90,9 @@ export function buildRevealStyles({
 
 	/* --------------------------- Gesture / Drag Values ------------------------- */
 
-	const initialGesture =
-		props.active.gesture.active ?? props.active.gesture.direction;
+	const liveGesture = props.active.gesture;
+	const gestureHandoff = liveGesture.handoff;
+	const initialGesture = gestureHandoff.active ?? gestureHandoff.direction;
 
 	const isHorizontalDismiss =
 		initialGesture === "horizontal" || initialGesture === "horizontal-inverted";
@@ -95,31 +100,25 @@ export function buildRevealStyles({
 		initialGesture === "vertical" || initialGesture === "vertical-inverted";
 
 	const rawDrag = isHorizontalDismiss
-		? Math.abs(props.active.gesture.raw.normX)
+		? Math.abs(gestureHandoff.raw.normX)
 		: isVerticalDismiss
-			? Math.abs(props.active.gesture.raw.normY)
+			? Math.abs(gestureHandoff.raw.normY)
 			: 0;
 
-	const dragX = resolveUnitDragTranslation(
-		props.active.gesture.x,
-		screenLayout.width,
-	);
+	const dragX = resolveUnitDragTranslation(liveGesture.x, screenLayout.width);
 
-	const dragY = resolveUnitDragTranslation(
-		props.active.gesture.y,
-		screenLayout.height,
-	);
+	const dragY = resolveUnitDragTranslation(liveGesture.y, screenLayout.height);
 
 	const dragXScale = isHorizontalDismiss
 		? resolveRevealDirectionalDragScale(
-				props.active.gesture.normX,
+				gestureHandoff.normX,
 				initialGesture === "horizontal-inverted",
 			)
 		: IDENTITY_DRAG_SCALE_OUTPUT[0];
 
 	const dragYScale = isVerticalDismiss
 		? resolveRevealDirectionalDragScale(
-				props.active.gesture.normY,
+				gestureHandoff.normY,
 				initialGesture === "vertical-inverted",
 			)
 		: IDENTITY_DRAG_SCALE_OUTPUT[1];
@@ -139,7 +138,8 @@ export function buildRevealStyles({
 			scaleMode: "uniform",
 			method: "content",
 			target: initialDestinationTarget,
-		} as const);
+			progress: transitionProgress,
+		});
 
 		const maskRaw = link.compute({
 			raw: true,
@@ -147,19 +147,20 @@ export function buildRevealStyles({
 			method: "size",
 			space: "absolute",
 			target: "fullscreen",
-		} as const);
+			progress: transitionProgress,
+		});
 
 		const maskBorderRadius = mixUnit(
 			sourceBorderRadius,
 			borderRadius,
-			progress,
+			activeTransitionProgress,
 		);
 		const maskBorderCurve = borderContinuous
 			? ("continuous" as const)
 			: undefined;
 
 		const maskSizeMultiplier = props.active.closing
-			? mixUnit(0.9, 1, props.active.progress)
+			? mixUnit(0.9, 1, activeTransitionProgress)
 			: 1;
 
 		const maskWidth = Math.max(1, maskRaw.width * maskSizeMultiplier);
@@ -181,10 +182,10 @@ export function buildRevealStyles({
 			});
 
 			contentScale = resolveDismissScaleHandoff({
-				progress: props.active.progress,
+				progress: activeTransitionProgress,
 				releaseScale: dragScale,
 				targetScale: sourceContentScale,
-				velocity: props.active.gesture.velocity,
+				velocity: gestureHandoff.velocity,
 				velocityDepth,
 			});
 		}
@@ -194,16 +195,16 @@ export function buildRevealStyles({
 
 		const liveHorizontalDismissDrag =
 			initialGesture === "horizontal-inverted"
-				? -props.active.gesture.normX
-				: props.active.gesture.normX;
+				? -gestureHandoff.normX
+				: gestureHandoff.normX;
 
 		const liveVerticalDismissDrag =
 			initialGesture === "vertical-inverted"
-				? -props.active.gesture.normY
-				: props.active.gesture.normY;
+				? -gestureHandoff.normY
+				: gestureHandoff.normY;
 
 		const dismissProgressDrag = props.active.gesture.dismissing
-			? 1 - props.active.progress
+			? 1 - activeTransitionProgress
 			: 0;
 
 		const maskHeightCollapseDrag =
@@ -308,7 +309,7 @@ export function buildRevealStyles({
 
 		const elementTX = props.active.closing
 			? interpolateClamped(
-					props.active.progress,
+					activeTransitionProgress,
 					CLOSE_SOURCE_HANDOFF_PROGRESS,
 					1,
 					elementOffsetX,
@@ -317,7 +318,7 @@ export function buildRevealStyles({
 			: 0;
 		const elementY = props.active.closing
 			? interpolateClamped(
-					props.active.progress,
+					activeTransitionProgress,
 					CLOSE_SOURCE_HANDOFF_PROGRESS,
 					1,
 					elementOffsetY,
@@ -333,7 +334,6 @@ export function buildRevealStyles({
 
 		return {
 			options: {
-				gestureProgressMode,
 				gestureSensitivity,
 				gestureReleaseVelocityScale,
 			},
@@ -347,7 +347,7 @@ export function buildRevealStyles({
 					shadowColor: "#000",
 					shadowOffset: REVEAL_SHADOW_OFFSET,
 					shadowOpacity: interpolate(
-						props.active.progress,
+						activeTransitionProgress,
 						ZERO_TO_ONE_RANGE,
 						CONTENT_SHADOW_OPACITY_OUTPUT,
 					),
@@ -355,12 +355,12 @@ export function buildRevealStyles({
 					elevation: 5,
 					opacity: props.active.entering
 						? interpolate(
-								props.active.progress,
+								activeTransitionProgress,
 								CONTENT_ENTERING_OPACITY_RANGE,
 								CONTENT_ENTERING_OPACITY_OUTPUT,
 							)
 						: interpolate(
-								props.active.progress,
+								activeTransitionProgress,
 								CONTENT_CLOSING_OPACITY_RANGE,
 								CONTENT_CLOSING_OPACITY_OUTPUT,
 							),
@@ -379,7 +379,7 @@ export function buildRevealStyles({
 
 	/* ---------------------------- Unfocused Screen ---------------------------- */
 
-	const unfocusedScale = mixUnit(1, backgroundScale, props.active.progress);
+	const unfocusedScale = mixUnit(1, backgroundScale, activeTransitionProgress);
 	const unfocusedContentScale =
 		props.active.settled && shouldBackgroundScaleResetOnSettled
 			? 1
@@ -389,7 +389,7 @@ export function buildRevealStyles({
 		initialDestinationTarget ?? link.destination.bounds;
 
 	const trackingContentBaseTransform = resolveRevealContentBaseTransform({
-		progress: props.active.progress,
+		progress: activeTransitionProgress,
 		sourceBounds: link.source.bounds,
 		destinationBounds: trackingContentTarget,
 		screenLayout,
@@ -403,10 +403,10 @@ export function buildRevealStyles({
 			destinationHeight: trackingContentTarget.height,
 		});
 		trackingContentScale = resolveDismissScaleHandoff({
-			progress: props.active.progress,
+			progress: activeTransitionProgress,
 			releaseScale: dragScale,
 			targetScale: trackingTargetScale,
-			velocity: props.active.gesture.velocity,
+			velocity: gestureHandoff.velocity,
 			velocityDepth,
 		});
 	}
@@ -426,9 +426,6 @@ export function buildRevealStyles({
 	});
 
 	return {
-		options: {
-			gestureProgressMode,
-		},
 		content: {
 			style: {
 				transform: [{ scale: unfocusedContentScale }],
@@ -436,7 +433,7 @@ export function buildRevealStyles({
 			props: disablePointerEventsTillElementTransition
 				? {
 						pointerEvents:
-							props.active.progress <= CLOSE_SOURCE_HANDOFF_PROGRESS
+							activeTransitionProgress <= CLOSE_SOURCE_HANDOFF_PROGRESS
 								? "auto"
 								: "none",
 					}
@@ -447,11 +444,10 @@ export function buildRevealStyles({
 				opacity: props.active.closing
 					? 1
 					: interpolate(
-							props.active.progress,
+							activeTransitionProgress,
 							ZERO_TO_ONE_RANGE,
 							UNFOCUSED_ELEMENT_OPACITY_OUTPUT,
 						),
-
 				zIndex: 9999,
 				elevation: 9999,
 				transform: [