react-native-screen-transitions 3.7.0-beta.2 → 3.8.0-alpha.0

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

@@ -1,14 +1,11 @@
 import type { TextStyle, ViewStyle } from "react-native";
-import type {
-	StyleProps,
-	WithSpringConfig,
-	WithTimingConfig,
-} from "react-native-reanimated";
+import type { StyleProps } from "react-native-reanimated";
 import type { EdgeInsets } from "react-native-safe-area-context";
 import {
 	NAVIGATION_MASK_CONTAINER_STYLE_ID,
 	NAVIGATION_MASK_ELEMENT_STYLE_ID,
 } from "../constants";
+import type { ScreenAnimationConfig } from "../utils/animation/animate";
 import type { BoundsAccessor } from "./bounds.types";
 import type { GestureValues } from "./gesture.types";
 import type { ScreenLayouts, ScreenTransitionConfig } from "./screen.types";
@@ -90,18 +87,19 @@ export type ScreenTransitionState = {
 	animating: number;
 
 	/**
-	 * Whether this screen is fully settled (not transitioning and not dismissing).
-	 * - `0`: Transition/gesture is active or dismissing
-	 * - `1`: Screen is fully settled/idle
+	 * Whether this screen is visually settled for choreography purposes.
+	 * - `0`: The screen is still meaningfully away from its animation target
+	 * - `1`: The screen is close enough to its target to be treated as done
+	 *
+	 * This may become `1` while `animating` is still `1`, since the animation
+	 * driver can keep physically settling after the transition is visually done.
 	 */
 	settled: number;
 
 	/**
-	 * Whether this screen is logically complete for choreography purposes.
-	 * - `0`: The screen is still meaningfully away from its animation target
-	 * - `1`: The screen is visually close enough to its target to be treated as done
+	 * Deprecated alias for `settled`.
 	 *
-	 * Unlike `settled`, this may become `1` before the underlying spring fully stops.
+	 * @deprecated Use `settled` instead.
 	 */
 	logicallySettled: number;
 
@@ -233,7 +231,7 @@ 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
+	 * @deprecated Use `active.settled` instead. Screen settlement state
 	 * belongs on the screen state object.
 	 */
 	logicallySettled: number;
@@ -372,7 +370,7 @@ export type TransitionInterpolatedStyle = {
 /**
  * A Reanimated animation configuration object.
  */
-export type AnimationConfig = WithSpringConfig | WithTimingConfig;
+export type AnimationConfig = ScreenAnimationConfig;
 
 /**
  * Defines separate animation configurations for screen transitions and snap point changes.

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

@@ -240,7 +240,7 @@ export type BoundsNavigationRevealOptions = {
 	backgroundScale?: number;
 	/**
 	 * Whether reveal should reset the unfocused background content scale once the
-	 * transition is logically settled.
+	 * transition is visually settled.
 	 *
 	 * By default, reveal restores the background to scale `1` after settle so the
 	 * next drag or programmatic dismiss starts from a fresh, unmodified layout

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

@@ -60,12 +60,40 @@ export type SideActivation = {
 	bottom?: ActivationArea;
 };
 
+export type GestureDirectionActivationArea = ActivationArea | number;
+
+export type GestureDirectionConfig = {
+	gesture: GestureDirection;
+	/**
+	 * Pan-only activation area for this gesture direction. Pinch directions
+	 * ignore this field.
+	 *
+	 * A number means an edge distance in points.
+	 */
+	area?: GestureDirectionActivationArea;
+};
+
+export type GestureDirectionEntry = GestureDirection | GestureDirectionConfig;
+
+export type GestureDirectionOption =
+	| GestureDirectionEntry
+	| GestureDirectionEntry[];
+
 export enum GestureActivationState {
 	PENDING,
 	PASSED,
 	FAILED,
 }
 
+export type ResolvedGestureActivationArea =
+	| GestureDirectionActivationArea
+	| {
+			left?: GestureDirectionActivationArea;
+			right?: GestureDirectionActivationArea;
+			top?: GestureDirectionActivationArea;
+			bottom?: GestureDirectionActivationArea;
+	  };
+
 export type GestureActivationArea = ActivationArea | SideActivation;
 
 /**
@@ -86,6 +114,7 @@ export type RawGestureValues = {
 	normY: number;
 	scale: number;
 	normScale: number;
+	rotation: number;
 };
 
 export type GestureValues = {
@@ -129,6 +158,10 @@ export type GestureValues = {
 	 * The live pinch focal point y-position in screen coordinates.
 	 */
 	focalY: number;
+	/**
+	 * The live two-finger rotation in radians.
+	 */
+	rotation: number;
 	/**
 	 * Physical gesture values before `gestureSensitivity` is applied.
 	 */

package/src/shared/types/index.ts

@@ -29,6 +29,10 @@ export type {
 	ActivationArea,
 	GestureActivationArea,
 	GestureDirection,
+	GestureDirectionActivationArea,
+	GestureDirectionConfig,
+	GestureDirectionEntry,
+	GestureDirectionOption,
 	GestureValues,
 	PanGestureDirection,
 	PinchGestureDirection,

package/src/shared/types/providers/{managed-stack.types.ts → blank-stack-provider.types.ts}

@@ -9,10 +9,10 @@ import type {
 } from "../stack.types";
 
 /**
- * Props for managed stack - generic over descriptor and navigation types.
+ * Props for blank stack - generic over descriptor and navigation types.
  * Defaults to base types for backward compatibility.
  */
-export interface ManagedStackProps<
+export interface BlankStackProviderProps<
 	TDescriptor extends BaseStackDescriptor = BaseStackDescriptor,
 	TNavigation extends BaseStackNavigation = BaseStackNavigation,
 > {
@@ -26,18 +26,18 @@ export interface ManagedStackProps<
 }
 
 /**
- * Context value for managed stack — only fields unique to managed lifecycle.
+ * Context value for blank stack — only fields unique to blank stack lifecycle.
  * Shared fields (routes, scenes, etc.) live in StackContext.
  */
-export interface ManagedStackContextValue {
+export interface BlankStackProviderContextValue {
 	handleCloseRoute: (payload: { route: BaseStackRoute }) => void;
 }
 
 /**
- * Props passed to the render child of `withManagedStack`.
+ * Props passed to the render child of `withBlankStack`.
  * Only the fields that stack-view components actually consume.
  */
-export interface ManagedStackRenderProps<
+export interface BlankStackProviderRenderProps<
 	TDescriptor extends BaseStackDescriptor = BaseStackDescriptor,
 > {
 	scenes: BaseStackScene<TDescriptor>[];
@@ -46,12 +46,12 @@ export interface ManagedStackRenderProps<
 }
 
 /**
- * Internal result shape returned by useManagedStackValue.
+ * Internal result shape returned by useBlankStackProviderValue.
  */
-export interface ManagedStackResult<
+export interface BlankStackProviderResult<
 	TDescriptor extends BaseStackDescriptor = BaseStackDescriptor,
 > {
 	stackContextValue: StackContextValue;
-	managedContextValue: ManagedStackContextValue;
-	renderProps: ManagedStackRenderProps<TDescriptor>;
+	blankStackProviderContextValue: BlankStackProviderContextValue;
+	renderProps: BlankStackProviderRenderProps<TDescriptor>;
 }

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

@@ -5,7 +5,7 @@ import type {
 } from "./animation.types";
 import type {
 	GestureActivationArea,
-	GestureDirection,
+	GestureDirectionOption,
 	GestureProgressMode,
 } from "./gesture.types";
 import type { OverlayProps } from "./overlay.types";
@@ -174,8 +174,11 @@ export type ScreenTransitionConfig = {
 	 *
 	 * Supports pan directions (`horizontal`, `vertical`, etc.) and pinch
 	 * directions (`pinch-in`, `pinch-out`).
+	 *
+	 * Pan directions may be configured with an activation area:
+	 * `[{ gesture: "vertical", area: "edge" }]`.
 	 */
-	gestureDirection?: GestureDirection | GestureDirection[];
+	gestureDirection?: GestureDirectionOption;
 
 	/**
 	 * Controls how directly live gesture movement maps into transition progress
@@ -251,6 +254,8 @@ export type ScreenTransitionConfig = {
 
 	/**
 	 * The area of the screen where the gesture is activated.
+	 *
+	 * @deprecated Use `gestureDirection` entries with per-direction `area`.
 	 */
 	gestureActivationArea?: GestureActivationArea;
 

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

@@ -2,7 +2,7 @@ import { runOnJS, type SharedValue } from "react-native-reanimated";
 import { FALSE, TRUE } from "../../constants";
 import type { AnimationStoreMap } from "../../stores/animation.store";
 import type { TransitionSpec } from "../../types/animation.types";
-import { animate } from "./animate";
+import { animate, isSpringAnimationConfig } from "./animate";
 
 interface AnimateToProgressProps {
 	/**
@@ -60,15 +60,20 @@ export const animateToProgress = ({
 	// Select spec based on direction (closing uses close spec, otherwise open)
 	const config = isClosing ? spec?.close : spec?.open;
 
-	const isSpringConfig =
-		!!config && !("duration" in config) && !("easing" in config);
+	const isSpringConfig = isSpringAnimationConfig(config);
 
 	const effectiveConfig =
 		isSpringConfig && typeof initialVelocity === "number"
 			? { ...config, velocity: initialVelocity }
 			: config;
 
-	const { progress, willAnimate, progressAnimating, entering } = animations;
+	const {
+		progress,
+		willAnimate,
+		progressAnimating,
+		progressSettled,
+		entering,
+	} = animations;
 
 	const startAnimation = () => {
 		"worklet";
@@ -81,6 +86,7 @@ export const animateToProgress = ({
 
 		if (!config) {
 			progressAnimating.set(FALSE);
+			progressSettled.set(TRUE);
 			progress.set(value);
 			if (shouldClearEnteringOnFinish) {
 				entering.set(FALSE);
@@ -93,17 +99,22 @@ export const animateToProgress = ({
 		}
 
 		progressAnimating.set(TRUE); //<-- Do not move this into the callback
+		progressSettled.set(FALSE);
 		progress.set(
-			animate(value, effectiveConfig, (finished) => {
+			animate(value, effectiveConfig, (state) => {
 				"worklet";
-				if (!finished) return;
+				if (state.settled) {
+					progressSettled.set(TRUE);
+				}
+
+				if (!state.finished) return;
 
 				if (shouldClearEnteringOnFinish) {
 					entering.set(FALSE);
 				}
 
 				if (onAnimationFinish) {
-					runOnJS(onAnimationFinish)(finished);
+					runOnJS(onAnimationFinish)(state.finished);
 				}
 
 				// Delay clearing progress animation by one frame to ensure final frame is painted

package/src/shared/utils/animation/animate.ts

@@ -1,28 +1,51 @@
-import {
-	type WithSpringConfig,
-	type WithTimingConfig,
-	withSpring,
-	withTiming,
-} from "react-native-reanimated";
-import type {
-	AnimatableValue,
-	AnimationCallback,
-} from "react-native-reanimated/lib/typescript/commonTypes";
+import type { WithTimingConfig } from "react-native-reanimated";
+import { withTiming } from "react-native-reanimated";
+import { type SpringConfig, withInternalSpring } from "./spring";
+import type { AnimationStateCallback } from "./state";
 
-export const animate = <T extends AnimatableValue>(
-	toValue: T,
-	config?: WithSpringConfig | WithTimingConfig,
-	callback?: AnimationCallback,
+export type TimingAnimationConfig = WithTimingConfig;
+export type SpringAnimationConfig = SpringConfig;
+export type ScreenAnimationConfig =
+	| SpringAnimationConfig
+	| TimingAnimationConfig;
+
+export const isSpringAnimationConfig = (
+	config: ScreenAnimationConfig | undefined,
+): config is SpringAnimationConfig => {
+	"worklet";
+	if (typeof config !== "object" || config === null) {
+		return false;
+	}
+
+	return (
+		"stiffness" in config ||
+		"damping" in config ||
+		"mass" in config ||
+		"velocity" in config ||
+		"overshootClamping" in config ||
+		"energyThreshold" in config ||
+		"dampingRatio" in config ||
+		"clamp" in config
+	);
+};
+
+export const animate = (
+	toValue: number,
+	config?: ScreenAnimationConfig,
+	callback?: AnimationStateCallback,
 ) => {
 	"worklet";
-	const isSpring =
-		typeof config === "object" &&
-		!("duration" in config) &&
-		!("easing" in config);
 
-	if (!isSpring) {
-		return withTiming(toValue, config, callback);
+	if (!isSpringAnimationConfig(config)) {
+		return withTiming(toValue, config, (finished) => {
+			"worklet";
+			const didFinish = finished === true;
+			callback?.({
+				finished: didFinish,
+				settled: didFinish,
+			});
+		});
 	}
 
-	return withSpring(toValue, config, callback);
+	return withInternalSpring(toValue, config, callback);
 };

package/src/shared/utils/animation/spring/index.ts

@@ -0,0 +1,2 @@
+export { withInternalSpring } from "./spring";
+export type { SpringConfig } from "./springConfigs";