react-native-screen-transitions 3.2.0-beta.2 → 3.2.0

package/src/shared/hooks/navigation/use-screen-state.tsx

@@ -0,0 +1,99 @@
+import type { Route } from "@react-navigation/native";
+import { useMemo } from "react";
+import { useDerivedValue } from "react-native-reanimated";
+import {
+	type BaseDescriptor,
+	useKeys,
+} from "../../providers/screen/keys.provider";
+import type { ScreenTransitionConfig } from "../../types/screen.types";
+import type { BaseStackNavigation } from "../../types/stack.types";
+import { useSharedValueState } from "../reanimated/use-shared-value-state";
+import { type StackContextValue, useStack } from "./use-stack";
+
+export interface ScreenState<
+	TNavigation extends BaseStackNavigation = BaseStackNavigation,
+> {
+	/**
+	 * The index of this screen in the stack.
+	 */
+	index: number;
+
+	/**
+	 * Screen options for the currently focused screen.
+	 */
+	options: ScreenTransitionConfig;
+
+	/**
+	 * All routes currently in the stack.
+	 */
+	routes: Route<string>[];
+
+	/**
+	 * Route of the currently focused screen in the stack.
+	 */
+	focusedRoute: Route<string>;
+
+	/**
+	 * Index of the focused route in the stack.
+	 */
+	focusedIndex: number;
+
+	/**
+	 * Custom metadata from the focused screen's options.
+	 */
+	meta?: Record<string, unknown>;
+
+	/**
+	 * Navigation object for this screen.
+	 */
+	navigation: TNavigation;
+}
+
+/**
+ * Hook to access screen state information.
+ *
+ * Use this hook to get navigation state and screen information.
+ */
+export function useScreenState<
+	TNavigation extends BaseStackNavigation = BaseStackNavigation,
+>(): ScreenState<TNavigation> {
+	const { routes, scenes, routeKeys, optimisticFocusedIndex } =
+		useStack<StackContextValue>();
+	const { current } = useKeys<BaseDescriptor>();
+
+	const index = useMemo(
+		() => routeKeys.indexOf(current.route.key),
+		[routeKeys, current.route.key],
+	);
+
+	const focusedIndex = useSharedValueState(
+		useDerivedValue(() => {
+			const globalIndex = optimisticFocusedIndex.get();
+			return Math.max(0, Math.min(globalIndex, routeKeys.length - 1));
+		}),
+	);
+
+	const focusedScene = useMemo(() => {
+		return scenes[focusedIndex] ?? scenes[scenes.length - 1];
+	}, [scenes, focusedIndex]);
+
+	return useMemo(
+		() => ({
+			index,
+			options: focusedScene?.descriptor?.options ?? {},
+			routes,
+			focusedRoute: focusedScene?.route ?? current.route,
+			focusedIndex,
+			meta: focusedScene?.descriptor?.options?.meta,
+			navigation: current.navigation as TNavigation,
+		}),
+		[
+			index,
+			focusedScene,
+			routes,
+			focusedIndex,
+			current.navigation,
+			current.route,
+		],
+	);
+}

package/src/shared/hooks/use-stable-callback-value.ts

@@ -10,7 +10,6 @@ import {
 	runOnJS,
 } from "react-native-reanimated";
 
-// biome-ignore lint/suspicious/noExplicitAny: <Does not matter>
 type AnyFunction = (...args: Array<any>) => any;
 
 function useMutableValue<T>(initialValue: T) {

package/src/shared/index.ts

@@ -20,6 +20,11 @@ export default {
 
 export { useScreenAnimation } from "./hooks/animation/use-screen-animation";
 export { useScreenGesture } from "./hooks/gestures/use-screen-gesture";
+export { useHistory } from "./hooks/navigation/use-history";
+export {
+	type ScreenState,
+	useScreenState,
+} from "./hooks/navigation/use-screen-state";
 
 export type {
 	AnimationConfig,

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

@@ -1,20 +1,5 @@
-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 };
+import type { BaseStackDescriptor } from "../../types/stack.types";
 
 /**
  * Base descriptor interface - minimal contract for all stack types.
@@ -23,15 +8,6 @@ export type { BaseStackRoute as BaseRoute };
  */
 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;

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

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

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

@@ -113,7 +113,7 @@ export function useScreenStyles() {
 	const ctx = useContext(ScreenStylesContext);
 	if (!ctx) {
 		throw new Error(
-			"useTransitionStyles must be used within a TransitionStylesProvider",
+			"useScreenStyles must be used within a ScreenStylesProvider",
 		);
 	}
 	return ctx;

package/src/shared/providers/stack/direct.provider.tsx

@@ -4,7 +4,7 @@ import type {
 	StackNavigationState,
 } from "@react-navigation/native";
 import * as React from "react";
-import { useMemo } from "react";
+import { useEffect, useMemo } from "react";
 import { type DerivedValue, useDerivedValue } from "react-native-reanimated";
 import type {
 	NativeStackDescriptor,
@@ -16,6 +16,7 @@ import {
 	type StackContextValue,
 } from "../../hooks/navigation/use-stack";
 import { AnimationStore } from "../../stores/animation.store";
+import { HistoryStore } from "../../stores/history.store";
 import { useStackCoreContext } from "./core.provider";
 
 export interface DirectStackScene {
@@ -216,6 +217,15 @@ function withDirectStack<TProps extends DirectStackProps>(
 	Component: React.ComponentType<DirectStackContextValue>,
 ): React.FC<TProps> {
 	return function DirectStackProvider(props: TProps) {
+		const navigatorKey = props.state.key;
+
+		// Clean up history when navigator unmounts
+		useEffect(() => {
+			return () => {
+				HistoryStore.clearNavigator(navigatorKey);
+			};
+		}, [navigatorKey]);
+
 		const { stackContextValue, ...lifecycleValue } = useDirectStackValue(props);
 
 		return (

package/src/shared/providers/stack/managed.provider.tsx

@@ -1,6 +1,6 @@
 import type { Route } from "@react-navigation/native";
 import * as React from "react";
-import { useMemo } from "react";
+import { useEffect, useMemo } from "react";
 import {
 	type DerivedValue,
 	type SharedValue,
@@ -11,6 +11,7 @@ import {
 	type StackContextValue,
 } from "../../hooks/navigation/use-stack";
 import { AnimationStore } from "../../stores/animation.store";
+import { HistoryStore } from "../../stores/history.store";
 import type {
 	BaseStackDescriptor,
 	BaseStackNavigation,
@@ -211,6 +212,15 @@ function withManagedStack<
 	return function ManagedStackProvider(
 		props: ManagedStackProps<TDescriptor, TNavigation>,
 	) {
+		const navigatorKey = props.state.key;
+
+		// Clean up history when navigator unmounts
+		useEffect(() => {
+			return () => {
+				HistoryStore.clearNavigator(navigatorKey);
+			};
+		}, [navigatorKey]);
+
 		const { stackContextValue, ...lifecycleValue } = useManagedStackValue<
 			TDescriptor,
 			TNavigation

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

@@ -1,14 +1,11 @@
-import {
-	cancelAnimation,
-	makeMutable,
-	type SharedValue,
-} from "react-native-reanimated";
+import { makeMutable, type SharedValue } from "react-native-reanimated";
 import type { ScreenKey } from "../types/screen.types";
 
 export type AnimationStoreMap = {
 	progress: SharedValue<number>;
-	closing: SharedValue<number>;
 	animating: SharedValue<number>;
+	closing: SharedValue<number>;
+	entering: SharedValue<number>;
 };
 
 const store: Record<ScreenKey, AnimationStoreMap> = {};
@@ -20,7 +17,8 @@ const ensure = (key: ScreenKey) => {
 			progress: makeMutable(0),
 			closing: makeMutable(0),
 			animating: makeMutable(0),
-		};
+			entering: makeMutable(1),
+		} satisfies AnimationStoreMap;
 		store[key] = bag;
 	}
 	return bag;
@@ -28,7 +26,7 @@ const ensure = (key: ScreenKey) => {
 
 function getAnimation(
 	key: ScreenKey,
-	type: "progress" | "closing" | "animating",
+	type: keyof AnimationStoreMap,
 ): SharedValue<number> {
 	return ensure(key)[type];
 }
@@ -39,23 +37,11 @@ function getAll(key: ScreenKey) {
 
 function clear(routeKey: ScreenKey) {
 	"worklet";
-	const bag = store[routeKey];
-	if (bag) {
-		cancelAnimation(bag.progress);
-		cancelAnimation(bag.closing);
-		cancelAnimation(bag.animating);
-	}
 	delete store[routeKey];
 }
 
-function debugStoreSize() {
-	console.log("[AnimationStore] Size:", Object.keys(store).length);
-	console.log("[AnimationStore] Keys:", Object.keys(store));
-}
-
 export const AnimationStore = {
 	getAnimation,
 	clear,
 	getAll,
-	debugStoreSize,
 };

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

@@ -0,0 +1,201 @@
+import type { ScreenKey } from "../types/screen.types";
+import type { BaseStackDescriptor } from "../types/stack.types";
+
+const HISTORY_LIMIT = 100;
+
+interface HistoryEntry {
+	descriptor: BaseStackDescriptor;
+	navigatorKey: string;
+	timestamp: number;
+}
+
+// Map preserves insertion order - index 0 = oldest, last = most recent
+const history = new Map<ScreenKey, HistoryEntry>();
+const listeners = new Set<() => void>();
+
+// Cached snapshot for useSyncExternalStore
+let cachedSnapshot: ReadonlyMap<ScreenKey, HistoryEntry> = history;
+
+function updateSnapshot(): void {
+	cachedSnapshot = new Map(history);
+}
+
+function notifyListeners(): void {
+	updateSnapshot();
+	listeners.forEach((listener) => {
+		listener();
+	});
+}
+
+/**
+ * Subscribe for useSyncExternalStore compatibility
+ */
+function subscribe(listener: () => void): () => void {
+	listeners.add(listener);
+	return () => listeners.delete(listener);
+}
+
+/**
+ * Get current snapshot for useSyncExternalStore
+ */
+function getSnapshot(): ReadonlyMap<ScreenKey, HistoryEntry> {
+	return cachedSnapshot;
+}
+
+/**
+ * Add or move screen to top (most recent).
+ * LRU behavior: if exists, delete and re-add to move to end.
+ * @param descriptor - The screen descriptor
+ * @param navigatorKey - The navigator's key (for cleanup on unmount)
+ * @param historyKey - Optional custom key (defaults to navigatorKey:routeName)
+ */
+function focus(
+	descriptor: BaseStackDescriptor,
+	navigatorKey: string,
+	historyKey?: ScreenKey,
+): void {
+	const key = historyKey ?? `${navigatorKey}:${descriptor.route.name}`;
+
+	// Delete first (if exists) to reset position - this is the LRU "move to top"
+	history.delete(key);
+
+	// Add to end (most recent)
+	history.set(key, {
+		descriptor,
+		navigatorKey,
+		timestamp: Date.now(),
+	});
+
+	// Evict oldest if over limit
+	while (history.size > HISTORY_LIMIT) {
+		const oldestKey = history.keys().next().value;
+		if (oldestKey) {
+			history.delete(oldestKey);
+		}
+	}
+
+	notifyListeners();
+}
+
+/**
+ * Get most recent entry (for forward nav).
+ */
+function getMostRecent(): HistoryEntry | undefined {
+	const entries = Array.from(history.values());
+	return entries[entries.length - 1];
+}
+
+/**
+ * Get N most recent entries (most recent first).
+ */
+function getRecent(n: number): HistoryEntry[] {
+	const entries = Array.from(history.values());
+	return entries.slice(-n).reverse();
+}
+
+/**
+ * Get entry by key.
+ */
+function get(key: ScreenKey): HistoryEntry | undefined {
+	return history.get(key);
+}
+
+/**
+ * Check if key exists.
+ */
+function has(key: ScreenKey): boolean {
+	return history.has(key);
+}
+
+/**
+ * Get all entries for a navigator (in recency order, most recent first).
+ */
+function getByNavigator(navigatorKey: string): HistoryEntry[] {
+	const entries: HistoryEntry[] = [];
+	for (const entry of history.values()) {
+		if (entry.navigatorKey === navigatorKey) {
+			entries.push(entry);
+		}
+	}
+	return entries.reverse();
+}
+
+/**
+ * Get path between two screens (for multi-waypoint interpolation).
+ * Returns keys in order from 'from' to 'to'.
+ */
+function getPath(fromKey: ScreenKey, toKey: ScreenKey): ScreenKey[] {
+	const keys = Array.from(history.keys());
+	const fromIndex = keys.indexOf(fromKey);
+	const toIndex = keys.indexOf(toKey);
+
+	if (fromIndex < 0 || toIndex < 0) return [];
+
+	const start = Math.min(fromIndex, toIndex);
+	const end = Math.max(fromIndex, toIndex);
+	const path = keys.slice(start, end + 1);
+
+	// Return in correct direction
+	return fromIndex > toIndex ? path.reverse() : path;
+}
+
+/**
+ * Clear all entries for a navigator (on unmount).
+ */
+function clearNavigator(navigatorKey: string): void {
+	const keysToRemove: ScreenKey[] = [];
+	for (const [key, entry] of history.entries()) {
+		if (entry.navigatorKey === navigatorKey) {
+			keysToRemove.push(key);
+		}
+	}
+
+	if (keysToRemove.length > 0) {
+		for (const key of keysToRemove) {
+			history.delete(key);
+		}
+		notifyListeners();
+	}
+}
+
+/**
+ * Get current size of history.
+ */
+function size(): number {
+	return history.size;
+}
+
+/**
+ * Convert to array (in recency order, oldest first).
+ */
+function toArray(): HistoryEntry[] {
+	return Array.from(history.values());
+}
+
+/**
+ * Clear all history entries (for testing).
+ * @internal
+ */
+function _reset(): void {
+	history.clear();
+	listeners.clear();
+	cachedSnapshot = new Map();
+}
+
+export const HistoryStore = {
+	focus,
+	getMostRecent,
+	getRecent,
+	get,
+	has,
+	getByNavigator,
+	getPath,
+	clearNavigator,
+	size,
+	toArray,
+	subscribe,
+	getSnapshot,
+	_reset,
+};
+
+export type { HistoryEntry };

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

@@ -4,10 +4,10 @@ import type {
 	WithTimingConfig,
 } from "react-native-reanimated";
 import type { EdgeInsets } from "react-native-safe-area-context";
-import type { BaseRoute } from "../providers/screen/keys.provider";
 import type { BoundsAccessor } from "./bounds.types";
 import type { GestureValues } from "./gesture.types";
 import type { Layout } from "./screen.types";
+import type { BaseStackRoute } from "./stack.types";
 
 export interface OverlayInterpolationProps {
 	progress: number;
@@ -40,6 +40,15 @@ export type ScreenTransitionState = {
 	 */
 	closing: number;
 
+	/**
+	 * Whether this screen is in the process of entering.
+	 * - `0`: Screen is closing or inactive
+	 * - `1`: Screen is opening/entering
+	 *
+	 * Use this to trigger different animations when navigating back vs forward.
+	 */
+	entering: number;
+
 	/**
 	 * Whether this screen is currently animating.
 	 * - `0`: No animation in progress
@@ -69,12 +78,8 @@ export type ScreenTransitionState = {
 
 	/**
 	 * The route object for this screen.
-	 *
-	 * @deprecated Use `meta` instead for conditional animation logic.
-	 * Pass route params via options: `options={({ route }) => ({ meta: { id: route.params.id } })}`
-	 * This field may be removed in a future version.
 	 */
-	route: BaseRoute;
+	route: BaseStackRoute;
 };
 
 export interface ScreenInterpolationProps {

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

@@ -36,6 +36,7 @@ export type BoundsAccessor = {
 	interpolateBounds: (
 		id: string,
 		property: keyof MeasuredDimensions,
+		fallbackOrTargetKey?: number | string,
 		fallback?: number,
 	) => number;
 };

package/src/shared/types/index.ts

@@ -1,3 +1,4 @@
+export { FALSE, TRUE } from "../constants";
 export type {
 	AnimationConfig,
 	OverlayInterpolationProps,
@@ -7,14 +8,12 @@ export type {
 	TransitionInterpolatedStyle,
 	TransitionSpec,
 } from "./animation.types";
-
 export type {
 	BoundEntry,
 	BoundsAccessor,
 	BoundsLink,
 	BoundsMethod,
 } from "./bounds.types";
-
 export type {
 	ActivationArea,
 	GestureActivationArea,
@@ -22,25 +21,21 @@ export type {
 	GestureValues,
 	SideActivation,
 } from "./gesture.types";
-
 export type {
 	OverlayMode,
 	OverlayProps,
 } from "./overlay.types";
-
 export type {
 	Layout,
 	ScreenKey,
 	ScreenTransitionConfig,
 	TransitionAwareProps,
 } from "./screen.types";
-
 export type {
 	BaseStackDescriptor,
 	BaseStackNavigation,
 	BaseStackRoute,
 	BaseStackScene,
 	BaseStackState,
+	DescriptorMap,
 } from "./stack.types";
-
-export { FALSE, TRUE } from "./state.types";

package/src/shared/types/overlay.types.ts

@@ -4,7 +4,13 @@ import type {
 	OverlayInterpolationProps,
 	ScreenInterpolationProps,
 } from "./animation.types";
+import type { ScreenTransitionConfig } from "./screen.types";
 
+/**
+ * @deprecated Overlay mode is no longer needed. Overlays now always render as "float" mode.
+ * For per-screen overlays, render an absolute-positioned view directly in your screen component
+ * and use `useScreenAnimation()` to access animation values.
+ */
 export type OverlayMode = "float" | "screen";
 
 /**
@@ -37,13 +43,30 @@ export type OverlayProps<TNavigation = unknown> = {
 	 */
 	navigation: TNavigation;
 
+	/**
+	 * Screen options for the currently focused screen.
+	 */
+	options: ScreenTransitionConfig;
+
+	/**
+	 * Stack progress relative to the overlay's position.
+	 * This is equivalent to `useScreenAnimation().stackProgress`.
+	 */
+	progress: DerivedValue<number>;
+
 	/**
 	 * Animation values for the overlay.
+	 *
+	 * @deprecated Use `progress` prop or `useScreenAnimation()` instead.
+	 * This prop will be removed in a future version.
 	 */
 	overlayAnimation: DerivedValue<OverlayInterpolationProps>;
 
 	/**
 	 * Animation values for the screen.
+	 *
+	 * @deprecated Use `useScreenAnimation()` hook directly instead.
+	 * This prop will be removed in a future version.
 	 */
 	screenAnimation: DerivedValue<ScreenInterpolationProps>;
 };

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

@@ -111,10 +111,11 @@ export type ScreenTransitionConfig = {
 
 	/**
 	 * How the overlay is positioned relative to screens.
-	 * - 'float': Single persistent overlay above all screens (like iOS tab bar)
-	 * - 'screen': Per-screen overlay that transitions with content
-	 * - 'container': Wraps all screen content, receives children prop (for MaskedView, custom containers)
-	 * @default 'screen'
+	 *
+	 * @deprecated This option is no longer needed. Overlays now always render as "float" mode
+	 * (single persistent overlay above all screens). For per-screen overlays, render an
+	 * absolute-positioned view directly in your screen component and use `useScreenAnimation()`
+	 * to access animation values.
 	 */
 	overlayMode?: OverlayMode;