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

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

@@ -1,57 +1,33 @@
-import type { StackContextValue } from "../../hooks/navigation/use-stack";
+import type {
+	BlankStackDescriptor,
+	BlankStackNavigationHelpers,
+} from "../blank-stack.types";
 import type {
 	BaseStackDescriptor,
-	BaseStackNavigation,
 	BaseStackRoute,
 	BaseStackScene,
 	BaseStackState,
-	StackDescriptorSource,
 } from "../stack.types";
 
-/**
- * Props for blank stack - generic over descriptor and navigation types.
- * Defaults to base types for backward compatibility.
- */
-export interface BlankStackProviderProps<
-	TDescriptor extends BaseStackDescriptor = BaseStackDescriptor,
-	TNavigation extends BaseStackNavigation = BaseStackNavigation,
-> {
-	state: BaseStackState<TDescriptor["route"]>;
-	navigation: TNavigation;
-	descriptors: Record<string, StackDescriptorSource<TDescriptor>>;
+export interface BlankStackProviderProps {
+	state: BaseStackState<BlankStackDescriptor["route"]>;
+	navigation: BlankStackNavigationHelpers;
+	descriptors: Record<string, BlankStackDescriptor>;
 	describe: (
-		route: TDescriptor["route"],
+		route: BlankStackDescriptor["route"],
 		placeholder: boolean,
-	) => StackDescriptorSource<TDescriptor>;
-}
-
-/**
- * Context value for blank stack — only fields unique to blank stack lifecycle.
- * Shared fields (routes, scenes, etc.) live in StackContext.
- */
-export interface BlankStackProviderContextValue {
-	handleCloseRoute: (payload: { route: BaseStackRoute }) => void;
+	) => BlankStackDescriptor;
 }
 
-/**
- * Props passed to the render child of `withBlankStack`.
- * Only the fields that stack-view components actually consume.
- */
-export interface BlankStackProviderRenderProps<
-	TDescriptor extends BaseStackDescriptor = BaseStackDescriptor,
-> {
-	scenes: BaseStackScene<TDescriptor>[];
+export interface BlankStackStoreValue {
+	navigatorKey: string;
+	routeKeys: string[];
+	routes: BaseStackRoute[];
+	scenes: BaseStackScene<BaseStackDescriptor>[];
+	scenesByKey: Record<string, BaseStackScene<BaseStackDescriptor>>;
+	paintDriverRouteKeyByRouteKey: ReadonlyMap<string, string>;
 	focusedIndex: number;
+	requestDismiss?: (payload: { route: BaseStackRoute }) => boolean;
 	shouldShowFloatOverlay: boolean;
-}
-
-/**
- * Internal result shape returned by useBlankStackProviderValue.
- */
-export interface BlankStackProviderResult<
-	TDescriptor extends BaseStackDescriptor = BaseStackDescriptor,
-> {
-	stackContextValue: StackContextValue;
-	blankStackProviderContextValue: BlankStackProviderContextValue;
-	renderProps: BlankStackProviderRenderProps<TDescriptor>;
+	handleCloseRoute?: (payload: { route: BaseStackRoute }) => void;
 }

package/src/types/screen.types.ts

@@ -6,12 +6,10 @@ import type {
 	TransitionSpec,
 } from "./animation.types";
 import type {
-	GestureActivationArea,
 	GestureDirectionOption,
-	GestureProgressMode,
 	ScrollMetadataState,
 } from "./gesture.types";
-import type { OverlayProps } from "./overlay.types";
+import type { OverlayComponent } from "./overlay.types";
 
 export type Layout = {
 	width: number;
@@ -43,6 +41,16 @@ export type ScreenKey = string;
 export type SheetScrollGestureBehavior =
 	| "expand-and-collapse"
 	| "collapse-only";
+
+/**
+ * Controls how a drag moves between configured {@linkcode ScreenTransitionConfig.snapPoints}.
+ *
+ * - `"continuous"` maps physical movement directly to global screen progress.
+ * - `"step"` maps each drag across one adjacent snap interval.
+ *
+ * @see {@linkcode ScreenTransitionConfig.sheetSnapBehavior}
+ */
+export type SheetSnapBehavior = "continuous" | "step";
 export type GestureTracking = "auto" | "never" | "always";
 
 /**
@@ -92,6 +100,17 @@ export type ScreenContentComponentProps = ScreenLayerComponentProps & {
 	children: ReactNode;
 };
 
+/**
+ * Props passed to {@linkcode ScreenTransitionConfig.surfaceComponent} when it
+ * is provided as a render-style component.
+ */
+export type ScreenSurfaceComponentProps = ScreenLayerComponentProps & {
+	/**
+	 * The screen subtree rendered inside the visual surface layer.
+	 */
+	children: ReactNode;
+};
+
 /**
  * Custom renderer for the backdrop layer.
  *
@@ -118,6 +137,20 @@ export type ScreenContentComponent =
 	| ComponentType<any>
 	| ComponentType<ScreenContentComponentProps>;
 
+/**
+ * Custom renderer for the screen's visual surface layer.
+ *
+ * The surface is nested inside the content layer and does not contain the
+ * shared-element fallback host. Use it for visual effects such as filters,
+ * clipping, backgrounds, and corner treatments without changing navigation
+ * geometry.
+ *
+ * @see {@linkcode ScreenTransitionConfig.surfaceComponent}
+ */
+export type ScreenSurfaceComponent =
+	| ComponentType<any>
+	| ComponentType<ScreenSurfaceComponentProps>;
+
 /**
  * Controls how an inactive screen is retained after it is no longer active.
  *
@@ -169,38 +202,6 @@ export type TransitionAwareProps<T extends object> = AnimatedProps<T> & {
 	 * }
 	 */
 	styleId?: string;
-
-	/**
-	 * Marks this component for measurement to enable shared element transitions.
-	 * Components with the same tag across different screens will animate between each other.
-	 *
-	 * @example
-	 * // Screen A:
-	 * <Transition.View sharedBoundTag="profile-avatar">
-	 *   <Avatar size="small" />
-	 * </Transition.View>
-	 *
-	 * // Screen B:
-	 * <Transition.View sharedBoundTag="profile-avatar">
-	 *   <Avatar size="large" />
-	 * </Transition.View>
-	 *
-	 * @deprecated Use `Transition.Boundary` with `id` instead.
-	 */
-	sharedBoundTag?: string;
-
-	/**
-	 * Re-measures this component when the screen regains focus and updates
-	 * any matching shared-bound source link in place.
-	 *
-	 * Useful when layout can change while unfocused (for example, programmatic
-	 * ScrollView/FlatList scrolling triggered from another screen).
-	 *
-	 * @deprecated Legacy `sharedBoundTag` refresh option. The boundary
-	 * measurement pipeline refreshes layout through `Transition.Boundary`.
-	 * @default false
-	 */
-	remeasureOnFocus?: boolean;
 };
 
 export type ScreenTransitionConfig = {
@@ -277,15 +278,6 @@ export type ScreenTransitionConfig = {
 	 */
 	gestureVelocityImpact?: 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.
-	 *
-	 * @deprecated Use `gestureSnapVelocityImpact` instead.
-	 * @default 0.1
-	 */
-	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.
@@ -298,65 +290,13 @@ export type ScreenTransitionConfig = {
 	 * Multiplies gesture release velocity used for gesture reset/handoff energy.
 	 *
 	 * This does NOT affect dismissal threshold decisions (`gestureVelocityImpact`)
-	 * or snap target selection (`snapVelocityImpact`). It changes the release
+	 * or snap target selection (`gestureSnapVelocityImpact`). It changes the release
 	 * impulse used by gesture values and interpolator handoff values.
 	 *
 	 * @default 1
 	 */
 	gestureReleaseVelocityScale?: number;
 
-	/**
-	 * Deprecated compatibility option.
-	 *
-	 * This option is no longer read by the runtime transition options. Use
-	 * `gestureReleaseVelocityScale` to tune post-release spring energy.
-	 *
-	 * @deprecated v3 compatibility only.
-	 */
-	gestureReleaseVelocityMax?: number;
-
-	/**
-	 * 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;
-
-	/**
-	 * 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;
-
-	/**
-	 * 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 `transitionProgress` from interpolation state instead.
-	 */
-	gestureDrivesProgress?: boolean;
-
-	/**
-	 * The area of the screen where the gesture is activated.
-	 *
-	 * @deprecated Use `gestureDirection` entries with per-direction `area`.
-	 */
-	gestureActivationArea?: GestureActivationArea;
-
 	/**
 	 * Custom metadata passed through to animation props.
 	 *
@@ -368,7 +308,7 @@ export type ScreenTransitionConfig = {
 	/**
 	 * Function that returns a React Element to display as an overlay.
 	 */
-	overlay?: (props: OverlayProps) => React.ReactNode;
+	overlay?: OverlayComponent;
 
 	/**
 	 * Whether to show the overlay. The overlay is shown by default when `overlay` is provided.
@@ -439,13 +379,15 @@ export type ScreenTransitionConfig = {
 	sheetScrollGestureBehavior?: SheetScrollGestureBehavior;
 
 	/**
-	 * @deprecated Use `sheetScrollGestureBehavior` instead.
+	 * Controls how gesture movement maps between adjacent snap points.
+	 *
+	 * `"continuous"` preserves direct global progress and permits one gesture to
+	 * cross multiple snap points. `"step"` gives every adjacent interval a full
+	 * normalized drag range and limits the gesture to one snap-point step.
 	 *
-	 * Mapping:
-	 * - `true` -> `"expand-and-collapse"`
-	 * - `false` -> `"collapse-only"`
+	 * @default "continuous"
 	 */
-	expandViaScrollView?: boolean;
+	sheetSnapBehavior?: SheetSnapBehavior;
 
 	/**
 	 * Locks gesture-based snap movement to the current snap point.
@@ -510,8 +452,6 @@ export type ScreenTransitionConfig = {
 	 * a function component can receive `{ styles, props, pointerEvents, children }`
 	 * and decide how to render the layer.
 	 *
-	 * `contentComponent` replaces `surfaceComponent` for custom screen shells.
-	 *
 	 * @example
 	 * contentComponent: ({ styles, props, pointerEvents, children }) => (
 	 *   <AnimatedSquircleView
@@ -528,28 +468,13 @@ export type ScreenTransitionConfig = {
 	contentComponent?: ScreenContentComponent;
 
 	/**
-	 * Custom component to render as the screen's surface layer.
-	 *
-	 * Renders inside the content animation scope (moves with the screen) as an
-	 * absolutely-positioned layer behind the screen's children.
+	 * Custom component to render as the screen's visual surface layer.
 	 *
-	 * The library wraps this component with `Animated.createAnimatedComponent` internally.
-	 * Animated styles and props are driven by the `surface` slot in the interpolator return value.
-	 *
-	 * @example
-	 * surfaceComponent: SquircleView,
-	 * screenStyleInterpolator: ({ progress }) => {
-	 *   "worklet";
-	 *   return {
-	 *     surface: {
-	 *       style: { opacity: interpolate(progress, [0, 1], [0, 1]) },
-	 *       props: { cornerRadius: 24, cornerSmoothing: 0.7 },
-	 *     },
-	 *   };
-	 * }
+	 * The component receives the `surface` slot's animated styles and props. It
+	 * is nested inside the content layer while shared-element fallback content
+	 * remains outside it.
 	 *
 	 * @default undefined
-	 * @deprecated Use `contentComponent` instead.
 	 */
-	surfaceComponent?: React.ComponentType<any>;
+	surfaceComponent?: ScreenSurfaceComponent;
 };

package/src/types/stack.types.ts

@@ -1,5 +1,9 @@
 import type { ScreenTransitionConfig } from "./screen.types";
 
+export type StackTransitionOptions = ScreenTransitionConfig & {
+	enableTransitions?: boolean;
+};
+
 /**
  * Minimal route shape for navigation utilities.
  * Used as a generic constraint across route comparison functions.
@@ -9,7 +13,7 @@ export interface RouteWithKey {
 }
 
 /**
- * Base route interface - minimal contract all stacks satisfy.
+ * Minimal route contract shared by BlankStack and the native-stack adapter.
  * Uses `object` for params to be compatible with React Navigation's `Readonly<object | undefined>`.
  */
 export interface BaseStackRoute {
@@ -21,8 +25,7 @@ export interface BaseStackRoute {
 export type StackSceneActivity = "active" | "inert" | "inactive" | "closing";
 
 /**
- * Base navigation interface - minimal contract for gesture handling.
- * Both React Navigation helpers and ComponentNavigation satisfy this.
+ * Minimal navigation contract used by transition lifecycle code.
  */
 export interface BaseStackNavigation {
 	getState: () => {
@@ -36,34 +39,25 @@ export interface BaseStackNavigation {
 }
 
 /**
- * Base descriptor interface - generic over route, navigation, and options.
- * All stack descriptors (BlankStack, NativeStack) extend this.
+ * Descriptor contract consumed by the shared transition renderer.
  */
 export interface BaseStackDescriptor<
 	TRoute extends BaseStackRoute = BaseStackRoute,
 	TNavigation extends BaseStackNavigation = BaseStackNavigation,
-	TOptions extends ScreenTransitionConfig = ScreenTransitionConfig,
 > {
 	route: TRoute;
 	navigation: TNavigation;
-	options: TOptions;
-	activity?: StackSceneActivity;
+	options: StackTransitionOptions;
 	render?: () => React.JSX.Element | null;
 }
 
-export type StackDescriptorSource<
-	TDescriptor extends BaseStackDescriptor = BaseStackDescriptor,
-> = Omit<TDescriptor, "activity"> & {
-	activity?: StackSceneActivity;
-};
-
 /**
- * Base scene interface - route + descriptor pair.
- * Used by all stack views to iterate over screens.
+ * Route and descriptor pair consumed by the shared transition renderer.
  */
 export interface BaseStackScene<
 	TDescriptor extends BaseStackDescriptor = BaseStackDescriptor,
 > {
+	activity: StackSceneActivity;
 	route: TDescriptor["route"];
 	descriptor: TDescriptor;
 	previousDescriptor?: TDescriptor;
@@ -71,8 +65,7 @@ export interface BaseStackScene<
 }
 
 /**
- * Base state interface - routes array with index.
- * Common structure across all navigation states.
+ * Minimal navigation state accepted by BlankStack.
  */
 export interface BaseStackState<
 	TRoute extends BaseStackRoute = BaseStackRoute,
@@ -81,19 +74,3 @@ export interface BaseStackState<
 	index: number;
 	key: string;
 }
-
-/**
- * Generic descriptor map - keyed by route key.
- * Use this instead of defining stack-specific DescriptorMap types.
- */
-export type DescriptorMap<
-	TDescriptor extends BaseStackDescriptor = BaseStackDescriptor,
-> = {
-	[key: string]: TDescriptor;
-};
-
-export enum StackType {
-	NATIVE = "native",
-	BLANK = "blank",
-	COMPONENT = "component",
-}

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

@@ -1,7 +1,9 @@
 import type { SharedValue } from "react-native-reanimated";
-import { scheduleOnRN } from "react-native-worklets";
 import { FALSE, TRUE } from "../../constants";
-import type { AnimationStoreMap } from "../../stores/animation.store";
+import {
+	type AnimationStoreMap,
+	emitMotionStart,
+} from "../../stores/animation.store";
 import type { TransitionSpec } from "../../types/animation.types";
 import { animate, isSpringAnimationConfig } from "./animate";
 
@@ -14,13 +16,14 @@ interface AnimateToProgressProps {
 	 */
 	target: "open" | "close" | number;
 	spec?: TransitionSpec;
-	onAnimationFinish?: (finished: boolean) => void;
 	animations: AnimationStoreMap;
 	targetProgress: SharedValue<number>;
+	animationProgress: SharedValue<number>;
 	emitWillAnimate?: boolean;
 	markEntering?: boolean;
 	/** Optional initial velocity for spring-based progress (units: progress/sec). */
 	initialVelocity?: number;
+	isDragging?: SharedValue<number>;
 }
 
 const setTransitionLifecycleFlags = (
@@ -36,20 +39,34 @@ const setTransitionLifecycleFlags = (
 		return;
 	}
 
+	animations.closing.set(FALSE);
+
 	if (markEntering) {
 		animations.entering.set(TRUE);
 	}
 };
 
+export const resolveAnimationProgressRange = (
+	currentProgress: number,
+	targetProgress: number,
+) => {
+	"worklet";
+	return {
+		from: Math.min(1, Math.max(0, currentProgress)),
+		to: targetProgress,
+	};
+};
+
 export const animateToProgress = ({
 	target,
 	spec,
-	onAnimationFinish,
 	animations,
 	targetProgress,
+	animationProgress,
 	emitWillAnimate = true,
 	markEntering = true,
 	initialVelocity,
+	isDragging,
 }: AnimateToProgressProps) => {
 	"worklet";
 
@@ -68,17 +85,16 @@ export const animateToProgress = ({
 			? { ...config, velocity: initialVelocity }
 			: config;
 
-	const {
-		transitionProgress,
-		willAnimate,
-		progressAnimating,
-		progressSettled,
-		entering,
-	} = animations;
+	const { transitionProgress, progressAnimating, progressSettled, entering } =
+		animations;
 
-	const startAnimation = () => {
+	const startAnimation = (activateMotion: boolean) => {
 		"worklet";
+		const { from: animationProgressFrom, to: animationProgressTo } =
+			resolveAnimationProgressRange(transitionProgress.get(), value);
+
 		targetProgress.set(value);
+		animationProgress.set(animationProgressFrom);
 
 		const shouldClearEnteringOnFinish =
 			!isClosing && (markEntering || entering.get());
@@ -89,70 +105,62 @@ export const animateToProgress = ({
 			progressAnimating.set(FALSE);
 			progressSettled.set(TRUE);
 			transitionProgress.set(value);
+			animationProgress.set(animationProgressTo);
 			if (shouldClearEnteringOnFinish) {
 				entering.set(FALSE);
 			}
-
-			if (onAnimationFinish) {
-				scheduleOnRN(onAnimationFinish, true);
-			}
 			return;
 		}
 
-		progressAnimating.set(TRUE); //<-- Do not move this into the callback
+		if (activateMotion) {
+			progressAnimating.set(TRUE);
+		}
 		progressSettled.set(FALSE);
 		transitionProgress.set(
-			animate(value, effectiveConfig, (state) => {
-				"worklet";
-				if (state.settled) {
-					progressSettled.set(TRUE);
-				}
+			animate(
+				value,
+				effectiveConfig,
+				(state) => {
+					"worklet";
+					if (!state.finished) return;
+					if (isDragging?.get()) return;
 
-				if (!state.finished) return;
+					progressSettled.set(TRUE);
 
-				if (shouldClearEnteringOnFinish) {
-					entering.set(FALSE);
-				}
+					animationProgress.set(animationProgressTo);
 
-				if (isClosing) {
-					progressAnimating.set(FALSE);
+					if (shouldClearEnteringOnFinish) {
+						entering.set(FALSE);
+					}
 
-					if (onAnimationFinish) {
-						// Paint the terminal UI-thread host/style state before React
-						// removes the closing route and its native portal host.
+					if (isClosing) {
+						progressAnimating.set(FALSE);
+					} else {
+						// Delay clearing progress animation by one frame to ensure final frame is painted
 						requestAnimationFrame(() => {
-							"worklet";
-							requestAnimationFrame(() => {
-								"worklet";
-								scheduleOnRN(onAnimationFinish, state.finished);
-							});
+							progressAnimating.set(FALSE);
 						});
 					}
-				} else {
-					if (onAnimationFinish) {
-						scheduleOnRN(onAnimationFinish, state.finished);
-					}
-
-					// Delay clearing progress animation by one frame to ensure final frame is painted
-					requestAnimationFrame(() => {
-						progressAnimating.set(FALSE);
-					});
-				}
-			}),
+				},
+				{
+					value: animationProgress,
+					from: animationProgressFrom,
+					to: animationProgressTo,
+				},
+			),
 		);
 	};
 
 	if (emitWillAnimate) {
 		setTransitionLifecycleFlags(animations, isClosing, markEntering);
 
-		willAnimate.set(TRUE);
+		emitMotionStart(animations);
 		requestAnimationFrame(() => {
 			"worklet";
-			willAnimate.set(FALSE);
-			startAnimation();
+			startAnimation(false);
 		});
 		return;
 	}
 
-	startAnimation();
+	startAnimation(true);
 };

package/src/utils/animation/animate.ts

@@ -1,7 +1,7 @@
 import type { WithTimingConfig } from "react-native-reanimated";
 import { withTiming } from "react-native-reanimated";
 import { type SpringConfig, withInternalSpring } from "./spring";
-import type { AnimationStateCallback } from "./state";
+import type { AnimationProgressDriver, AnimationStateCallback } from "./state";
 
 export type TimingAnimationConfig = WithTimingConfig;
 export type SpringAnimationConfig = SpringConfig;
@@ -9,6 +9,11 @@ export type ScreenAnimationConfig =
 	| SpringAnimationConfig
 	| TimingAnimationConfig;
 
+const linearEasing = (progress: number) => {
+	"worklet";
+	return progress;
+};
+
 export const isSpringAnimationConfig = (
 	config: ScreenAnimationConfig | undefined,
 ): config is SpringAnimationConfig => {
@@ -33,10 +38,21 @@ export const animate = (
 	toValue: number,
 	config?: ScreenAnimationConfig,
 	callback?: AnimationStateCallback,
+	animationProgress?: AnimationProgressDriver,
 ) => {
 	"worklet";
 
 	if (!isSpringAnimationConfig(config)) {
+		if (animationProgress) {
+			animationProgress.value.set(animationProgress.from);
+			animationProgress.value.set(
+				withTiming(animationProgress.to, {
+					...config,
+					easing: linearEasing,
+				}),
+			);
+		}
+
 		return withTiming(toValue, config, (finished) => {
 			"worklet";
 			const didFinish = finished === true;
@@ -47,5 +63,5 @@ export const animate = (
 		});
 	}
 
-	return withInternalSpring(toValue, config, callback);
+	return withInternalSpring(toValue, config, callback, animationProgress);
 };