react-native-screen-transitions 4.0.0-alpha.0 → 4.0.0-alpha.10

package/src/stores/bounds/internals/resolver.ts

@@ -1,35 +1,21 @@
-import { createScreenPairKey } from "../helpers/link-pairs.helpers";
 import type {
 	ResolvedTransitionPair,
 	ResolveTransitionContext,
-	ScreenPairKey,
 	TagID,
 } from "../types";
-import { getResolvedLink } from "./links";
-
-function resolvePairKey(
-	context: ResolveTransitionContext,
-): ScreenPairKey | null {
-	"worklet";
-
-	if (context.entering) {
-		if (!context.previousScreenKey || !context.currentScreenKey) return null;
-		return createScreenPairKey(
-			context.previousScreenKey,
-			context.currentScreenKey,
-		);
-	}
-
-	if (!context.currentScreenKey || !context.nextScreenKey) return null;
-	return createScreenPairKey(context.currentScreenKey, context.nextScreenKey);
-}
+import { getPairKeyForDestination, getResolvedLink } from "./links";
 
 function resolveTransitionPair(
 	tag: TagID,
 	context: ResolveTransitionContext,
 ): ResolvedTransitionPair {
 	"worklet";
-	const pairKey = resolvePairKey(context);
+	const destinationScreenKey = context.entering
+		? context.currentScreenKey
+		: context.nextScreenKey;
+	const pairKey = destinationScreenKey
+		? getPairKeyForDestination(tag, destinationScreenKey)
+		: null;
 	const matchedLink = pairKey ? getResolvedLink(pairKey, tag).link : null;
 
 	return {

package/src/stores/gesture.store.ts

@@ -3,10 +3,7 @@ import {
 	makeMutable,
 	type SharedValue,
 } from "react-native-reanimated";
-import type {
-	ActiveGesture,
-	ResolvedPanGestureDirection,
-} from "../types/gesture.types";
+import type { ActiveGesture } from "../types/gesture.types";
 import { createStore } from "../utils/create-store";
 
 type GestureRawStoreMap = {
@@ -34,7 +31,6 @@ type GestureSnapshotStoreMap = {
 	rotation: SharedValue<number>;
 	raw: GestureRawStoreMap;
 	active: SharedValue<ActiveGesture | null>;
-	direction: SharedValue<ResolvedPanGestureDirection | null>;
 };
 
 type GestureInternalStoreMap = {
@@ -63,26 +59,7 @@ export type GestureStoreMap = {
 	dismissing: SharedValue<number>;
 	dragging: SharedValue<number>;
 	settling: SharedValue<number>;
-	active: SharedValue<ActiveGesture | null>;
-	/** @deprecated Use `active` instead. */
-	direction: SharedValue<ResolvedPanGestureDirection | null>;
-
-	/**
-	 * @deprecated Use `normX` instead.
-	 */
-	normalizedX: SharedValue<number>;
-	/**
-	 * @deprecated Use `normY` instead.
-	 */
-	normalizedY: SharedValue<number>;
-	/**
-	 * @deprecated Use `dismissing` instead.
-	 */
-	isDismissing: SharedValue<number>;
-	/**
-	 * @deprecated Use `dragging` instead.
-	 */
-	isDragging: SharedValue<number>;
+	initiator: SharedValue<ActiveGesture | null>;
 };
 
 function createGestureBag(): GestureStoreMap {
@@ -97,7 +74,7 @@ function createGestureBag(): GestureStoreMap {
 	const dismissing = makeMutable(0);
 	const dragging = makeMutable(0);
 	const settling = makeMutable(0);
-	const active = makeMutable<ActiveGesture | null>(null);
+	const initiator = makeMutable<ActiveGesture | null>(null);
 
 	return {
 		x: makeMutable(0),
@@ -149,20 +126,12 @@ function createGestureBag(): GestureStoreMap {
 					rotation: makeMutable(0),
 				},
 				active: makeMutable<ActiveGesture | null>(null),
-				direction: makeMutable<ResolvedPanGestureDirection | null>(null),
 			},
 		},
 		dismissing,
 		dragging,
 		settling,
-		active,
-		direction: makeMutable<ResolvedPanGestureDirection | null>(null),
-
-		// Deprecated aliases (same underlying SharedValue)
-		normalizedX: normX,
-		normalizedY: normY,
-		isDismissing: dismissing,
-		isDragging: dragging,
+		initiator,
 	};
 }
 
@@ -219,11 +188,9 @@ export const GestureStore = createStore<GestureStoreMap>({
 		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);
-		cancelAnimation(bag.active);
-		cancelAnimation(bag.direction);
+		cancelAnimation(bag.initiator);
 	},
 });

package/src/stores/scroll.store.ts

@@ -137,6 +137,29 @@ export const getClampedScrollAxisDelta = (
 	return currentOffset - capturedOffset;
 };
 
+/**
+ * Visual scroll travel from a bounds snapshot normalized to its at-rest
+ * position. The captured side is clamped because measurement removes transient
+ * rubber-band displacement; the current side stays raw so consumers can follow
+ * the position that is actually visible on iOS.
+ */
+export const getVisualScrollAxisDelta = (
+	current: ScrollMetadataState | null | undefined,
+	captured: ScrollMetadataState | null | undefined,
+	axis: ScrollGestureAxis,
+): number => {
+	"worklet";
+
+	const currentAxisState = current?.[axis];
+	const capturedOffset = clampScrollAxisOffset(captured?.[axis]);
+
+	if (!currentAxisState || capturedOffset === null) {
+		return 0;
+	}
+
+	return currentAxisState.offset - capturedOffset;
+};
+
 /**
  * Route-keyed scroll geometry used by gesture activation and bounds measurement.
  * Coordination tracks gesture-owner scoped ScrollView offsets and dimensions;

package/src/stores/system.store.ts

@@ -9,13 +9,18 @@ import { createStore } from "../utils/create-store";
 export enum LifecycleTransitionRequestKind {
 	None = 0,
 	Open = 1,
-	BlankStackClose = 2,
-	NativeClose = 3,
+	Close = 2,
 }
 
 type SystemStoreState = {
 	targetProgress: SharedValue<number>;
 
+	/**
+	 * Directional linear clock for the active progress animation. Increasing
+	 * animations run 0 -> 1; decreasing animations run 1 -> 0.
+	 */
+	animationProgress: SharedValue<number>;
+
 	/**
 	 * Resolved fraction (contentHeight / screenHeight) for the 'auto' snap point. -1 = not yet measured.
 	 */
@@ -67,6 +72,7 @@ export type SystemStoreMap = SystemStoreState & {
 export const SystemStore = createStore<SystemStoreState, SystemStoreActions>({
 	createBag: () => ({
 		targetProgress: makeMutable(1),
+		animationProgress: makeMutable(0),
 		resolvedAutoSnapPoint: makeMutable(-1),
 		measuredContentLayout: makeMutable<Layout | null>(null),
 		pendingLifecycleRequestKind: makeMutable<LifecycleTransitionRequestKind>(
@@ -77,6 +83,7 @@ export const SystemStore = createStore<SystemStoreState, SystemStoreActions>({
 	}),
 	disposeBag: (bag) => {
 		cancelAnimation(bag.targetProgress);
+		cancelAnimation(bag.animationProgress);
 		cancelAnimation(bag.resolvedAutoSnapPoint);
 		cancelAnimation(bag.measuredContentLayout);
 		cancelAnimation(bag.pendingLifecycleRequestKind);

package/src/types/animation.types.ts

@@ -28,11 +28,8 @@ export type ScreenTransitionOptions = Pick<
 	| "gestureVelocityImpact"
 	| "gestureSnapVelocityImpact"
 	| "gestureReleaseVelocityScale"
-	| "gestureResponseDistance"
-	| "gestureProgressMode"
-	| "gestureDrivesProgress"
-	| "gestureActivationArea"
 	| "gestureSnapLocked"
+	| "sheetSnapBehavior"
 	| "sheetScrollGestureBehavior"
 	| "backdropBehavior"
 >;
@@ -105,13 +102,6 @@ export type ScreenTransitionState = {
 	 */
 	settled: number;
 
-	/**
-	 * Deprecated alias for `settled`.
-	 *
-	 * @deprecated Use `settled` instead.
-	 */
-	logicallySettled: number;
-
 	/**
 	 * Live gesture values for this screen.
 	 * Contains translation (x, y), normalized values (-1 to 1),
@@ -242,15 +232,6 @@ export interface ScreenInterpolationProps {
 	 */
 	stackProgress: 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.
-	 *
-	 * @deprecated Use `active.settled` instead. Screen settlement state
-	 * belongs on the screen state object.
-	 */
-	logicallySettled: number;
-
 	/**
 	 * Function that provides access to bounds helpers for shared screen transitions.
 	 */
@@ -364,8 +345,6 @@ export type NormalizedTransitionInterpolatedStyle = {
 	content?: NormalizedTransitionSlotStyle;
 	/** Animated style and props for the backdrop layer between screens. */
 	backdrop?: NormalizedTransitionSlotStyle;
-	/** Animated style and props for the surface component layer within the screen. */
-	surface?: NormalizedTransitionSlotStyle;
 	/** Animated style and props for the navigation mask container layer. */
 	[NAVIGATION_MASK_CONTAINER_STYLE_ID]?: NormalizedTransitionSlotStyle;
 	/** Animated style and props for the navigation mask element layer. */
@@ -384,12 +363,18 @@ export type TransitionInterpolatedStyle = {
 	 * This reserved key is stripped before style slot normalization.
 	 */
 	options?: TransitionInterpolatorOptions;
+	/**
+	 * Animated style and props for the route-owned floating overlay.
+	 *
+	 * Visible overlays form their own adjacency chain. A route that returns this
+	 * slot controls the previous visible overlay and, when it owns an overlay,
+	 * its entering overlay.
+	 */
+	overlay?: TransitionSlotStyle;
 	/** Animated style and props for the main screen content view. */
 	content?: TransitionSlotStyle;
 	/** Animated style and props for the backdrop layer between screens. */
 	backdrop?: TransitionSlotStyle;
-	/** Animated style and props for the surface component layer within the screen. */
-	surface?: TransitionSlotStyle;
 	/** Animated style and props for the navigation mask container layer. */
 	[NAVIGATION_MASK_CONTAINER_STYLE_ID]?: TransitionSlotStyle;
 	/** Animated style and props for the navigation mask element layer. */

package/src/types/blank-stack.types.ts

@@ -12,7 +12,6 @@ import type {
 } from "@react-navigation/native";
 import type { OverlayProps } from "./overlay.types";
 import type { InactiveBehavior, ScreenTransitionConfig } from "./screen.types";
-import type { StackSceneActivity } from "./stack.types";
 
 export type { InactiveBehavior } from "./screen.types";
 
@@ -61,24 +60,6 @@ export type BlankStackNavigationHelpers = NavigationHelpers<
  * they are also supported as top-level keys in static navigator config.
  */
 export interface BlankStackFactoryOptions {
-	/**
-	 * Controls whether blank-stack screens are rendered with react-native-screens.
-	 *
-	 * When enabled, inactive presentation state is backed by
-	 * `ScreenContainer`/`Screen.activityState`. Set this to `false` to render
-	 * screens as regular React Native views.
-	 *
-	 * @default true
-	 */
-	nativeScreens?: boolean;
-
-	/**
-	 * Enables react-native-screens for blank-stack screen retention.
-	 *
-	 * @deprecated Use `nativeScreens` instead.
-	 */
-	enableNativeScreens?: boolean;
-
 	/**
 	 * Creates an isolated navigation tree for embedded flows.
 	 *
@@ -97,8 +78,14 @@ export interface BlankStackFactoryOptions {
  * Props passed to overlay components in blank-stack.
  * Uses the shared OverlayProps type with blank-stack's navigation type.
  */
-export type BlankStackOverlayProps = OverlayProps<
-	BlankStackNavigationProp<ParamListBase>
+export type BlankStackOverlayProps<
+	ParamList extends ParamListBase = ParamListBase,
+	RouteName extends keyof ParamList = keyof ParamList,
+	NavigatorID extends string | undefined = undefined,
+> = OverlayProps<
+	BlankStackNavigationProp<ParamList, RouteName, NavigatorID>,
+	ParamList,
+	RouteName
 >;
 
 export type BlankStackNavigationOptions = ScreenTransitionConfig & {
@@ -141,6 +128,4 @@ export type BlankStackDescriptor = Descriptor<
 	BlankStackNavigationOptions,
 	BlankStackNavigationProp<ParamListBase>,
 	RouteProp<ParamListBase>
-> & {
-	activity: StackSceneActivity;
-};
+>;

package/src/types/bounds.types.ts

@@ -18,7 +18,6 @@ import type {
 	TransitionInterpolatedStyle,
 	TransitionSlotStyle,
 } from "./animation.types";
-import type { GestureProgressMode } from "./gesture.types";
 
 export type { BoundsLink, BoundsLinkStatus } from "../stores/bounds/types";
 
@@ -65,28 +64,6 @@ export type BoundsNavigationZoomDragOptions = {
 	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 = {
 	/**
 	 * Geometry that the zoomed content should resolve against.
@@ -139,67 +116,6 @@ export type BoundsNavigationZoomOptions = {
 	 * 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 Ignored. Gesture movement always contributes to `progress`.
-	 */
-	gestureProgressMode?: GestureProgressMode;
-	/**
-	 * @deprecated Ignored. Use `drag.scale.horizontal` to adjust response
-	 * intensity without replacing the native curve.
-	 */
-	horizontalDragScale?: readonly [
-		shrinkMin: number,
-		growMax: number,
-		exponent?: number,
-	];
-	/**
-	 * @deprecated Ignored. Use `drag.scale.vertical` to adjust response intensity
-	 * without replacing the native curve.
-	 */
-	verticalDragScale?: readonly [
-		shrinkMin: number,
-		growMax: number,
-		exponent?: number,
-	];
-	/**
-	 * @deprecated Ignored. Use `drag.translation.horizontal` to adjust response
-	 * intensity without replacing the native curve.
-	 */
-	horizontalDragTranslation?: readonly [
-		negativeMax: number,
-		positiveMax: number,
-		exponent?: number,
-	];
-	/**
-	 * @deprecated Ignored. Use `drag.translation.vertical` to adjust response
-	 * intensity without replacing the native curve.
-	 */
-	verticalDragTranslation?: readonly [
-		negativeMax: number,
-		positiveMax: number,
-		exponent?: number,
-	];
 };
 
 export type BoundsNavigationZoomStyle = TransitionInterpolatedStyle & {
@@ -242,16 +158,6 @@ export type BoundsNavigationRevealOptions = {
 	 * @default 0.5
 	 */
 	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 reveal helper no longer reads this option.
-	 *
-	 * @deprecated Use `transitionProgress` from interpolation state instead.
-	 */
-	gestureProgressMode?: GestureProgressMode;
 	/**
 	 * Scale applied to the unfocused background content while the reveal runs
 	 * above it.
@@ -316,12 +222,6 @@ export type BoundsScopedAccessor = BoundsBoundNavigationAccessor & {
 	values: <T extends BoundsComputeOptions = BoundsComputeOptions>(
 		options?: T,
 	) => BoundsValuesResult<T>;
-	/**
-	 * @deprecated Use {@linkcode values}.
-	 */
-	math: <T extends BoundsComputeOptions = BoundsComputeOptions>(
-		options?: T,
-	) => BoundsValuesResult<T>;
 	link: (id?: BoundsIdentityInput) => BoundsLink | null;
 };
 

package/src/types/gesture.types.ts

@@ -16,8 +16,6 @@ export type GestureDirection = PanGestureDirection | PinchGestureDirection;
 
 export type ActiveGesture = ResolvedPanGestureDirection | PinchGestureDirection;
 
-export type GestureProgressMode = "progress-driven" | "freeform";
-
 export type SnapPanAxis = "horizontal" | "vertical";
 
 /**
@@ -158,12 +156,6 @@ export type GestureHandoffValues = {
 	 * 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 = {
@@ -221,15 +213,9 @@ export type GestureValues = {
 	 */
 	raw: RawGestureValues;
 	/**
-	 * The gesture that is currently active.
+	 * The accepted activation identity for the current gesture attempt.
 	 */
-	active: ActiveGesture | null;
-	/**
-	 * The initial pan direction that activated the gesture.
-	 *
-	 * @deprecated Use `active` instead.
-	 */
-	direction: ResolvedPanGestureDirection | null;
+	initiator: ActiveGesture | "none";
 	/**
 	 * Gesture values latched at the release boundary for animation handoff.
 	 *
@@ -239,7 +225,10 @@ export type GestureValues = {
 	 */
 	handoff: GestureHandoffValues;
 	/**
-	 * A flag indicating if the screen is in the process of dismissing (0 or 1).
+	 * Whether a released gesture is completing a dismissal (0 or 1).
+	 *
+	 * Use `closing` for screen lifecycle state. This value specifically describes
+	 * the gesture release handoff.
 	 */
 	dismissing: number;
 	/**
@@ -247,15 +236,7 @@ export type GestureValues = {
 	 */
 	dragging: number;
 	/**
-	 * A flag indicating if released gesture values are animating back to neutral.
+	 * Whether released gesture values are animating back to neutral (0 or 1).
 	 */
 	settling: number;
-	/** @deprecated Use `normX` instead. */
-	normalizedX: number;
-	/** @deprecated Use `normY` instead. */
-	normalizedY: number;
-	/** @deprecated Use `dismissing` instead. */
-	isDismissing: number;
-	/** @deprecated Use `dragging` instead. */
-	isDragging: number;
 };

package/src/types/index.ts

@@ -27,8 +27,6 @@ export type {
 	BoundsNavigationRevealStyle,
 	BoundsNavigationZoomAxisResponse,
 	BoundsNavigationZoomDragOptions,
-	BoundsNavigationZoomOpacityRange,
-	BoundsNavigationZoomOpacityRanges,
 	BoundsNavigationZoomOptions,
 	BoundsNavigationZoomStyle,
 } from "./bounds.types";
@@ -51,7 +49,7 @@ export type {
 	ScrollMetadataState,
 	SideActivation,
 } from "./gesture.types";
-export type { OverlayProps } from "./overlay.types";
+export type { OverlayComponent, OverlayProps } from "./overlay.types";
 export type {
 	GestureTracking,
 	InactiveBehavior,
@@ -62,7 +60,10 @@ export type {
 	ScreenContentComponentProps,
 	ScreenKey,
 	ScreenLayerComponentProps,
+	ScreenSurfaceComponent,
+	ScreenSurfaceComponentProps,
 	ScreenTransitionConfig,
+	SheetSnapBehavior,
 	TransitionAwareProps,
 } from "./screen.types";
 export type {
@@ -71,7 +72,6 @@ export type {
 	BaseStackRoute,
 	BaseStackScene,
 	BaseStackState,
-	DescriptorMap,
-	StackDescriptorSource,
 	StackSceneActivity,
+	StackTransitionOptions,
 } from "./stack.types";

package/src/types/overlay.types.ts

@@ -1,28 +1,44 @@
-import type { Route } from "@react-navigation/native";
+import type {
+	ParamListBase,
+	ParamListRoute,
+	RouteProp,
+} from "@react-navigation/native";
+import type { ReactNode } from "react";
 import type { DerivedValue } from "react-native-reanimated";
 import type { ScreenTransitionConfig } from "./screen.types";
 
 /**
- * Props passed to overlay components.
- * Generic over the navigation type since different stacks have different navigation props.
+ * Overlay state without the animated progress value.
  */
+export type OverlayScreenState<
+	TNavigation = unknown,
+	TParamList extends ParamListBase = ParamListBase,
+	TOwnerRouteName extends keyof TParamList = keyof TParamList,
+> = Omit<OverlayProps<TNavigation, TParamList, TOwnerRouteName>, "progress"> & {
+	snapTo: (index: number) => void;
+};
+
 /**
- * Overlay screen state passed to overlay host for rendering.
- * Generic over navigation type — defaults to `unknown` for flexibility.
+ * Props passed to a floating overlay component.
+ *
+ * `route` and `index` identify the screen that owns the overlay. Focused
+ * values may describe a later screen while that overlay remains visible.
  */
-export type OverlayScreenState<TNavigation = unknown> = Omit<
-	OverlayProps<TNavigation>,
-	"progress"
-> & {
+export type OverlayProps<
+	TNavigation = unknown,
+	TParamList extends ParamListBase = ParamListBase,
+	TOwnerRouteName extends keyof TParamList = keyof TParamList,
+> = {
+	/** Route that declared this overlay. */
+	route: RouteProp<TParamList, TOwnerRouteName>;
+
+	/** Index of the route that declared this overlay. */
 	index: number;
-	snapTo: (index: number) => void;
-};
 
-export type OverlayProps<TNavigation = unknown> = {
 	/**
 	 * Route of the currently focused screen in the stack.
 	 */
-	focusedRoute: Route<string>;
+	focusedRoute: ParamListRoute<TParamList>;
 
 	/**
 	 * Index of the focused route in the stack.
@@ -32,7 +48,7 @@ export type OverlayProps<TNavigation = unknown> = {
 	/**
 	 * All routes currently in the stack.
 	 */
-	routes: Route<string>[];
+	routes: ParamListRoute<TParamList>[];
 
 	/**
 	 * Custom metadata from the focused screen's options.
@@ -55,3 +71,14 @@ export type OverlayProps<TNavigation = unknown> = {
 	 */
 	progress: DerivedValue<number>;
 };
+
+/**
+ * Component rendered for a floating screen overlay.
+ *
+ * The callback is bivariant because React Navigation stores overlay components
+ * in navigator-wide screen options while applications annotate them for one
+ * specific route.
+ */
+export type OverlayComponent = {
+	bivarianceHack(props: OverlayProps): ReactNode;
+}["bivarianceHack"];