react-native-screen-transitions 3.1.0 → 3.2.0-beta.0

package/src/shared/components/overlay/variations/screen-overlay.tsx

@@ -0,0 +1,51 @@
+import { useMemo } from "react";
+import {
+	type StackDescriptor,
+	type StackScene,
+	useStack,
+} from "../../../hooks/navigation/use-stack";
+import { useKeys } from "../../../providers/screen/keys.provider";
+import { OverlayHost } from "./overlay-host";
+
+/**
+ * Screen overlay component that renders per-screen.
+ * Gets current descriptor from keys context.
+ */
+export function ScreenOverlay() {
+	const { current } = useKeys<StackDescriptor>();
+	const { routeKeys, flags } = useStack();
+
+	const options = current.options;
+
+	const scene = useMemo<StackScene>(
+		() => ({
+			descriptor: current,
+			route: current.route,
+		}),
+		[current],
+	);
+
+	// Find the index of this screen in the stack
+	const overlayIndex = useMemo(
+		() => routeKeys.indexOf(current.route.key),
+		[routeKeys, current.route.key],
+	);
+
+	// Skip screens without enableTransitions (native-stack only)
+	if (!flags.TRANSITIONS_ALWAYS_ON && !options.enableTransitions) {
+		return null;
+	}
+
+	if (!options.overlayShown || options.overlayMode !== "screen") {
+		return null;
+	}
+
+	return (
+		<OverlayHost
+			scene={scene}
+			scenes={[scene]}
+			routes={[]}
+			overlayIndex={overlayIndex}
+		/>
+	);
+}

package/src/shared/components/root-transition-aware.tsx

@@ -2,14 +2,14 @@ import { memo } from "react";
 import { StyleSheet, View } from "react-native";
 import Animated, { useAnimatedStyle } from "react-native-reanimated";
 import { NO_STYLES } from "../constants";
-import { useTransitionStyles } from "../providers/transition-styles.provider";
+import { useScreenStyles } from "../providers/screen/styles.provider";
 
 type Props = {
 	children: React.ReactNode;
 };
 
 export const RootTransitionAware = memo(({ children }: Props) => {
-	const { stylesMap } = useTransitionStyles();
+	const { stylesMap } = useScreenStyles();
 
 	const animatedContentStyle = useAnimatedStyle(() => {
 		"worklet";

package/src/shared/configs/presets.ts

@@ -4,7 +4,7 @@ import {
 	interpolate,
 	interpolateColor,
 } from "react-native-reanimated";
-import type { ScreenTransitionConfig } from "../types/core.types";
+import type { ScreenTransitionConfig } from "../types/screen.types";
 import { DefaultSpec } from "./specs";
 
 const platform = Platform.OS;

package/src/shared/constants.ts

@@ -1,11 +1,8 @@
 import type { ParamListBase, RouteProp } from "@react-navigation/native";
 import type { MeasuredDimensions } from "react-native-reanimated";
 import type { ScreenTransitionState } from "./types/animation.types";
-import type { BoundEntry } from "./types/bounds.types";
-import type { Layout } from "./types/core.types";
 import type { ActivationArea } from "./types/gesture.types";
-import type { Complete } from "./types/utils.types";
-import type { BoundsBuilderOptions } from "./utils/bounds/types/builder";
+import type { Layout } from "./types/screen.types";
 
 /**
  * Masked view integration
@@ -41,7 +38,6 @@ export const DEFAULT_SCREEN_TRANSITION_STATE: ScreenTransitionState =
 /**
  * Bounds API Defaults
  */
-export const NO_BOUNDS_MAP: Record<string, BoundEntry> = Object.freeze({});
 export const EMPTY_BOUND_HELPER_RESULT = Object.freeze({});
 export const EMPTY_BOUND_HELPER_RESULT_RAW = Object.freeze({
 	scaleX: 1,
@@ -69,23 +65,6 @@ export const FULLSCREEN_DIMENSIONS = (
 	};
 };
 
-export const DEFAULT_BUILDER_OPTIONS: Complete<
-	Omit<BoundsBuilderOptions, "id">
-> = Object.freeze({
-	gestures: { x: 0, y: 0 },
-	toFullscreen: false,
-	absolute: false,
-	relative: true,
-	method: "transform",
-	contentScaleMode: "auto",
-	//
-	space: "relative",
-	target: "bound",
-	scaleMode: "match",
-	anchor: "center",
-	raw: false,
-} as const);
-
 /**
  * Default gesture config
  */
@@ -94,14 +73,3 @@ export const DEFAULT_GESTURE_DIRECTION = "horizontal";
 export const DEFAULT_GESTURE_ENABLED = false;
 export const DEFAULT_GESTURE_DRIVES_PROGRESS = true;
 export const DEFAULT_GESTURE_ACTIVATION_AREA: ActivationArea = "screen";
-
-/**
- * Default gesture offset
- */
-export const GESTURE_ACTIVATION_THRESHOLD_X = 10;
-export const GESTURE_ACTIVATION_THRESHOLD_Y = 10;
-export const GESTURE_FAIL_TOLERANCE_X = 15;
-export const GESTURE_FAIL_TOLERANCE_Y = 20;
-export const DEFAULT_EDGE_DISTANCE_HORIZONTAL = 50;
-export const DEFAULT_EDGE_DISTANCE_VERTICAL = 135;
-export const DEFAULT_ACTIVATION_AREA = "screen" as const;

package/src/shared/hooks/animation/use-associated-style.tsx

@@ -5,7 +5,7 @@ import {
 	useSharedValue,
 } from "react-native-reanimated";
 import { NO_STYLES } from "../../constants";
-import { useTransitionStyles } from "../../providers/transition-styles.provider";
+import { useScreenStyles } from "../../providers/screen/styles.provider";
 
 type Props = {
 	id?: string;
@@ -16,7 +16,7 @@ type Props = {
  * This hook is used to get the associated styles for a given styleId / boundTag.
  */
 export const useAssociatedStyles = ({ id }: Props = {}) => {
-	const { stylesMap, ancestorStylesMaps } = useTransitionStyles();
+	const { stylesMap, ancestorStylesMaps } = useScreenStyles();
 	const showAfterFirstFrame = useSharedValue(false);
 
 	useDerivedValue(() => {

package/src/shared/hooks/animation/use-high-refresh-rate.tsx

@@ -0,0 +1,28 @@
+import { useFrameCallback } from "react-native-reanimated";
+import type { BaseDescriptor } from "../../providers/screen/keys.provider";
+import useStableCallback from "../use-stable-callback";
+
+export const useHighRefreshRate = (current: BaseDescriptor) => {
+	// Force display to run at max refresh rate during transitions only
+	const enableHighRefreshRate =
+		current.options.experimental_enableHighRefreshRate ?? false;
+
+	const frameCallback = useFrameCallback(() => {}, false);
+
+	const activateHighRefreshRate = useStableCallback(() => {
+		if (enableHighRefreshRate) {
+			frameCallback.setActive(true);
+		}
+	});
+
+	const deactivateHighRefreshRate = useStableCallback(() => {
+		if (enableHighRefreshRate) {
+			frameCallback.setActive(false);
+		}
+	});
+
+	return {
+		activateHighRefreshRate,
+		deactivateHighRefreshRate,
+	};
+};

package/src/shared/hooks/animation/use-screen-animation.tsx

@@ -1,39 +1,37 @@
-import type { ParamListBase, RouteProp } from "@react-navigation/native";
 import { useMemo } from "react";
 import { useWindowDimensions } from "react-native";
 import { type SharedValue, useDerivedValue } from "react-native-reanimated";
 import { useSafeAreaInsets } from "react-native-safe-area-context";
 import type { NativeStackScreenTransitionConfig } from "../../../native-stack/types";
 import { DEFAULT_SCREEN_TRANSITION_STATE } from "../../constants";
-import { useFlagsContext } from "../../providers/flags.provider";
 import {
-	type TransitionDescriptor,
+	type BaseDescriptor,
+	type BaseRoute,
 	useKeys,
-} from "../../providers/keys.provider";
-import { useStackAnimationValues } from "../../providers/routes.provider";
+} from "../../providers/screen/keys.provider";
 import { AnimationStore } from "../../stores/animation.store";
 import { GestureStore, type GestureStoreMap } from "../../stores/gesture.store";
 import type {
 	ScreenInterpolationProps,
 	ScreenTransitionState,
 } from "../../types/animation.types";
-import type { ScreenTransitionConfig } from "../../types/core.types";
-import { computeStackProgress } from "../../utils/animation/compute-stack-progress";
+import type { ScreenTransitionConfig } from "../../types/screen.types";
 import { derivations } from "../../utils/animation/derivations";
 import { createBounds } from "../../utils/bounds";
+import { useStack } from "../navigation/use-stack";
 
 type BuiltState = {
 	progress: SharedValue<number>;
 	closing: SharedValue<number>;
 	animating: SharedValue<number>;
 	gesture: GestureStoreMap;
-	route: RouteProp<ParamListBase>;
+	route: BaseRoute;
 	meta?: Record<string, unknown>;
 	unwrapped: ScreenTransitionState;
 };
 
 const createScreenTransitionState = (
-	route: RouteProp<ParamListBase>,
+	route: BaseRoute,
 	meta?: Record<string, unknown>,
 ): ScreenTransitionState => ({
 	progress: 0,
@@ -71,7 +69,7 @@ const unwrapInto = (s: BuiltState): ScreenTransitionState => {
 };
 
 const useBuildScreenTransitionState = (
-	descriptor: TransitionDescriptor | undefined,
+	descriptor: BaseDescriptor | undefined,
 ): BuiltState | undefined => {
 	const key = descriptor?.route.key;
 	const meta = descriptor?.options?.meta;
@@ -101,10 +99,12 @@ const hasTransitionsEnabled = (
 };
 
 export function _useScreenAnimation() {
-	const dimensions = useWindowDimensions();
+	const windowDimensions = useWindowDimensions();
+	const dimensions = windowDimensions;
+
 	const insets = useSafeAreaInsets();
-	const flags = useFlagsContext();
-	const transitionsAlwaysOn = flags?.TRANSITIONS_ALWAYS_ON ?? false;
+	const { flags, stackProgress: rootStackProgress, routeKeys } = useStack();
+	const transitionsAlwaysOn = flags.TRANSITIONS_ALWAYS_ON;
 
 	const {
 		current: currentDescriptor,
@@ -117,7 +117,7 @@ export function _useScreenAnimation() {
 	const prevAnimation = useBuildScreenTransitionState(previousDescriptor);
 
 	const currentRouteKey = currentDescriptor?.route?.key;
-	const stackAnimationValues = useStackAnimationValues(currentRouteKey);
+	const currentIndex = routeKeys.indexOf(currentRouteKey);
 
 	const screenInterpolatorProps = useDerivedValue<
 		Omit<ScreenInterpolationProps, "bounds">
@@ -142,7 +142,11 @@ export function _useScreenAnimation() {
 			next,
 		});
 
-		const stackProgress = computeStackProgress(stackAnimationValues, progress);
+		// Compute relative stack progress: total - currentIndex
+		// This gives us the sum of progress values from current screen onwards
+		// Falls back to current progress if index is invalid
+		const stackProgress =
+			currentIndex >= 0 ? rootStackProgress.value - currentIndex : progress;
 
 		return {
 			layouts: { screen: dimensions },

package/src/shared/hooks/gestures/use-build-gestures.tsx

@@ -22,10 +22,9 @@ import type {
 	GestureContextType,
 	ScrollConfig,
 } from "../../providers/gestures.provider";
-import { useKeys } from "../../providers/keys.provider";
+import { useKeys } from "../../providers/screen/keys.provider";
 import { AnimationStore } from "../../stores/animation.store";
 import { GestureStore, type GestureStoreMap } from "../../stores/gesture.store";
-
 import {
 	type GestureDirection,
 	GestureOffsetState,

package/src/shared/hooks/gestures/use-scroll-registry.tsx

@@ -5,7 +5,6 @@ import type { LayoutChangeEvent } from "react-native";
 import { useAnimatedScrollHandler } from "react-native-reanimated";
 import type { ReanimatedScrollEvent } from "react-native-reanimated/lib/typescript/hook/commonTypes";
 import { useGestureContext } from "../../providers/gestures.provider";
-import type { Any } from "../../types/utils.types";
 import useStableCallback from "../use-stable-callback";
 
 interface ScrollProgressHookProps {
@@ -34,7 +33,7 @@ export const useScrollRegistry = (props: ScrollProgressHookProps) => {
 		onScroll: (event) => {
 			props.onScroll?.(event);
 
-			const updateScrollPosition = (v: Any) => {
+			const updateScrollPosition = (v: any) => {
 				"worklet";
 				if (v === null) {
 					return {
@@ -64,7 +63,7 @@ export const useScrollRegistry = (props: ScrollProgressHookProps) => {
 		(width: number, height: number) => {
 			props.onContentSizeChange?.(width, height);
 
-			const updateContentSize = (v: Any) => {
+			const updateContentSize = (v: any) => {
 				"worklet";
 				if (v === null) {
 					return {
@@ -93,7 +92,7 @@ export const useScrollRegistry = (props: ScrollProgressHookProps) => {
 		props.onLayout?.(event);
 		const { width, height } = event.nativeEvent.layout;
 
-		const updateLayout = (v: Any) => {
+		const updateLayout = (v: any) => {
 			"worklet";
 			if (v === null) {
 				return {

package/src/{blank-stack/utils/with-stack-navigation/hooks → shared/hooks/navigation}/use-closing-route-keys.tsx

@@ -1,6 +1,6 @@
 import { useMemo, useRef } from "react";
 import { useSharedValue } from "react-native-reanimated";
-import useStableCallback from "../../../../shared/hooks/use-stable-callback";
+import useStableCallback from "../use-stable-callback";
 
 export const useClosingRouteKeys = () => {
 	const keysRef = useRef<Set<string>>(new Set());

package/src/shared/hooks/navigation/use-stack.tsx

@@ -0,0 +1,100 @@
+import type { Route } from "@react-navigation/native";
+import { createContext, useContext } from "react";
+import type { DerivedValue } from "react-native-reanimated";
+import type {
+	ContainerOverlayProps,
+	OverlayMode,
+	OverlayProps,
+} from "../../types/overlay.types";
+import type {
+	BaseStackDescriptor,
+	BaseStackNavigation,
+	BaseStackRoute,
+	BaseStackScene,
+} from "../../types/stack.types";
+
+/**
+ * Stack descriptor with overlay options.
+ * Extends BaseStackDescriptor with overlay-specific options.
+ */
+export interface StackDescriptor<
+	TRoute extends BaseStackRoute = Route<string>,
+	TNavigation extends BaseStackNavigation = BaseStackNavigation,
+> extends BaseStackDescriptor<TRoute, TNavigation> {
+	options: BaseStackDescriptor["options"] & {
+		overlay?:
+			| ((props: OverlayProps) => React.ReactNode)
+			| ((props: ContainerOverlayProps) => React.ReactNode);
+		overlayMode?: OverlayMode;
+		overlayShown?: boolean;
+		meta?: Record<string, unknown>;
+		enableTransitions?: boolean;
+	};
+}
+
+/**
+ * Scene type for stack context (route + descriptor pair).
+ */
+export type StackScene<TDescriptor extends StackDescriptor = StackDescriptor> =
+	BaseStackScene<TDescriptor>;
+
+/**
+ * Common stack context value that both managed and direct stack providers populate.
+ * Used by overlays and shared components that need stack progress info.
+ */
+export interface StackContextValue {
+	/**
+	 * Stack flags.
+	 */
+	flags: {
+		TRANSITIONS_ALWAYS_ON: boolean;
+	};
+	/**
+	 * Route keys for all routes in the stack.
+	 */
+	routeKeys: string[];
+	/**
+	 * All routes in the stack.
+	 */
+	routes: Route<string>[];
+	/**
+	 * Descriptor map for all routes.
+	 */
+	descriptors: Record<string, StackDescriptor>;
+	/**
+	 * Pre-computed scenes (route + descriptor pairs).
+	 */
+	scenes: StackScene[];
+	/**
+	 * The current focused index from navigation state.
+	 */
+	focusedIndex: number;
+	/**
+	 * Aggregated stack progress across all routes.
+	 * Sum of all individual screen progress values.
+	 * When 4 screens are fully visible, stackProgress = 4.
+	 */
+	stackProgress: DerivedValue<number>;
+	/**
+	 * Focused index that accounts for closing screens.
+	 * Returns currentIndex - 1 if any screen is closing, otherwise currentIndex.
+	 */
+	optimisticFocusedIndex: DerivedValue<number>;
+}
+
+export const StackContext = createContext<StackContextValue | null>(null);
+StackContext.displayName = "Stack";
+
+/**
+ * Hook to access common stack context values.
+ * Works in both blank-stack and native-stack navigators.
+ */
+export function useStack<T extends StackContextValue = StackContextValue>(): T {
+	const context = useContext(StackContext);
+
+	if (context === null) {
+		throw new Error("useStack must be used within a Stack provider");
+	}
+
+	return context as T;
+}

package/src/shared/index.ts

@@ -23,9 +23,13 @@ export { useScreenGesture } from "./hooks/gestures/use-screen-gesture";
 
 export type {
 	AnimationConfig,
+	BoundEntry,
+	BoundsLink,
+	ContainerOverlayProps,
 	OverlayInterpolationProps,
+	OverlayMode,
+	OverlayProps,
 	ScreenInterpolationProps,
 	ScreenStyleInterpolator,
-} from "./types/animation.types";
-export type { BoundEntry, BoundsLink } from "./types/bounds.types";
-export type { ScreenTransitionConfig } from "./types/core.types";
+	ScreenTransitionConfig,
+} from "./types";

package/src/shared/providers/gestures.provider.tsx

@@ -8,7 +8,7 @@ import { useSharedValue } from "react-native-reanimated";
 import { useBuildGestures } from "../hooks/gestures/use-build-gestures";
 import type { GestureStoreMap } from "../stores/gesture.store";
 import createProvider from "../utils/create-provider";
-import { useKeys } from "./keys.provider";
+import { useKeys } from "./screen/keys.provider";
 
 export type ScrollConfig = {
 	x: number;
@@ -29,11 +29,15 @@ export interface GestureContextType {
 	gestureEnabled: boolean;
 }
 
+interface ScreenGestureProviderProps {
+	children: React.ReactNode;
+}
+
 export const {
 	ScreenGestureProvider,
 	useScreenGestureContext: useGestureContext,
 } = createProvider("ScreenGesture", { guarded: false })<
-	{ children: React.ReactNode },
+	ScreenGestureProviderProps,
 	GestureContextType
 >(({ children }) => {
 	const { current } = useKeys();

package/src/shared/providers/register-bounds.provider.tsx

@@ -17,7 +17,7 @@ import { AnimationStore } from "../stores/animation.store";
 import { BoundStore } from "../stores/bounds.store";
 import { prepareStyleForBounds } from "../utils/bounds/helpers/styles";
 import createProvider from "../utils/create-provider";
-import { type TransitionDescriptor, useKeys } from "./keys.provider";
+import { type BaseDescriptor, useKeys } from "./screen/keys.provider";
 
 interface MaybeMeasureAndStoreParams {
 	onPress?: ((...args: unknown[]) => void) | undefined;
@@ -47,19 +47,26 @@ interface RegisterBoundsContextValue {
  * Returns an array of screen keys from immediate parent to root.
  * [parentKey, grandparentKey, greatGrandparentKey, ...]
  */
-const getAncestorKeys = (current: TransitionDescriptor): string[] => {
+const getAncestorKeys = (current: BaseDescriptor): string[] => {
 	const ancestors: string[] = [];
-	let nav = current.navigation.getParent();
+	const nav = current.navigation as any;
 
-	while (nav) {
-		const state = nav.getState();
+	// Safety check for component-stack which doesn't have getParent
+	if (typeof nav?.getParent !== "function") {
+		return ancestors;
+	}
+
+	let parent = nav.getParent();
+
+	while (parent) {
+		const state = parent.getState();
 		if (state?.routes && state.index !== undefined) {
 			const focusedRoute = state.routes[state.index];
 			if (focusedRoute?.key) {
 				ancestors.push(focusedRoute.key);
 			}
 		}
-		nav = nav.getParent();
+		parent = parent.getParent();
 	}
 
 	return ancestors;

package/src/shared/providers/screen/keys.provider.tsx

@@ -0,0 +1,72 @@
+import type {
+	Descriptor,
+	NavigationProp,
+	ParamListBase,
+	RouteProp,
+} from "@react-navigation/native";
+import { createContext, useContext, useMemo } from "react";
+import type { ScreenTransitionConfig } from "../../types/screen.types";
+import type {
+	BaseStackDescriptor,
+	BaseStackNavigation,
+	BaseStackRoute,
+} from "../../types/stack.types";
+
+// Re-export for backward compatibility
+export type { BaseStackNavigation as BaseNavigation };
+export type { BaseStackRoute as BaseRoute };
+
+/**
+ * Base descriptor interface - minimal contract for all stack types.
+ * This allows component-stack, blank-stack, and native-stack to all
+ * work with the shared providers without tight coupling to React Navigation.
+ */
+export type BaseDescriptor = BaseStackDescriptor;
+
+/**
+ * React Navigation specific descriptor - extends base with full typing
+ */
+export type TransitionDescriptor = Descriptor<
+	ScreenTransitionConfig,
+	NavigationProp<ParamListBase>,
+	RouteProp<ParamListBase>
+>;
+
+interface KeysContextType<TDescriptor extends BaseDescriptor = BaseDescriptor> {
+	previous?: TDescriptor;
+	current: TDescriptor;
+	next?: TDescriptor;
+}
+
+const KeysContext = createContext<KeysContextType | undefined>(undefined);
+
+interface KeysProviderProps<TDescriptor extends BaseDescriptor> {
+	children: React.ReactNode;
+	previous?: TDescriptor;
+	current: TDescriptor;
+	next?: TDescriptor;
+}
+
+export function KeysProvider<TDescriptor extends BaseDescriptor>({
+	children,
+	previous,
+	current,
+	next,
+}: KeysProviderProps<TDescriptor>) {
+	const value = useMemo<KeysContextType<TDescriptor>>(
+		() => ({ previous, current, next }),
+		[previous, current, next],
+	);
+
+	return <KeysContext.Provider value={value}>{children}</KeysContext.Provider>;
+}
+
+export function useKeys<
+	TDescriptor extends BaseDescriptor = BaseDescriptor,
+>(): KeysContextType<TDescriptor> {
+	const context = useContext(KeysContext);
+	if (context === undefined) {
+		throw new Error("useKeys must be used within a KeysProvider");
+	}
+	return context as KeysContextType<TDescriptor>;
+}

package/src/shared/providers/screen/screen-composer.tsx

@@ -0,0 +1,38 @@
+import type React from "react";
+import type { ComponentType } from "react";
+import { RootTransitionAware } from "../../components/root-transition-aware";
+import { ScreenGestureProvider } from "../gestures.provider";
+import { type BaseDescriptor, KeysProvider } from "./keys.provider";
+import { ScreenStylesProvider } from "./styles.provider";
+
+type Props<TDescriptor extends BaseDescriptor> = {
+	previous?: TDescriptor;
+	current: TDescriptor;
+	next?: TDescriptor;
+	children: React.ReactNode;
+	LifecycleController: ComponentType<any>;
+};
+
+export function ScreenComposer<TDescriptor extends BaseDescriptor>({
+	previous,
+	current,
+	next,
+	children,
+	LifecycleController,
+}: Props<TDescriptor>) {
+	return (
+		<KeysProvider<TDescriptor>
+			previous={previous}
+			current={current}
+			next={next}
+		>
+			<ScreenGestureProvider>
+				<LifecycleController>
+					<ScreenStylesProvider>
+						<RootTransitionAware>{children}</RootTransitionAware>
+					</ScreenStylesProvider>
+				</LifecycleController>
+			</ScreenGestureProvider>
+		</KeysProvider>
+	);
+}