react-native-screen-transitions 3.3.0 → 3.4.0-alpha.0

package/src/shared/components/screen-container/layers/surface-container.tsx

@@ -0,0 +1,55 @@
+import { type ComponentType, memo, useMemo } from "react";
+import { StyleSheet, type ViewProps } from "react-native";
+import Animated, {
+	useAnimatedProps,
+	useAnimatedStyle,
+} from "react-native-reanimated";
+import { NO_PROPS, NO_STYLES } from "../../../constants";
+import { useDescriptors } from "../../../providers/screen/descriptors";
+import { useScreenStyles } from "../../../providers/screen/styles.provider";
+
+type Props = {
+	children: React.ReactNode;
+	pointerEvents: ViewProps["pointerEvents"];
+};
+
+export const SurfaceContainer = memo(({ children, pointerEvents }: Props) => {
+	const { stylesMap } = useScreenStyles();
+	const { current } = useDescriptors();
+
+	const SurfaceComponent = current.options.surfaceComponent;
+
+	const AnimatedSurfaceComponent = useMemo<ComponentType<any> | null>(() => {
+		return SurfaceComponent
+			? Animated.createAnimatedComponent(SurfaceComponent)
+			: null;
+	}, [SurfaceComponent]);
+
+	const animatedSurfaceStyle = useAnimatedStyle(() => {
+		"worklet";
+		return stylesMap.value.surface?.style ?? NO_STYLES;
+	});
+
+	const animatedSurfaceProps = useAnimatedProps(() => {
+		"worklet";
+		return stylesMap.value.surface?.props ?? NO_PROPS;
+	});
+
+	if (!AnimatedSurfaceComponent) return children;
+
+	return (
+		<AnimatedSurfaceComponent
+			style={[styles.surface, animatedSurfaceStyle]}
+			animatedProps={animatedSurfaceProps}
+			pointerEvents={pointerEvents}
+		>
+			{children}
+		</AnimatedSurfaceComponent>
+	);
+});
+
+const styles = StyleSheet.create({
+	surface: {
+		flex: 1,
+	},
+});

package/src/shared/components/screen-lifecycle/hooks/use-close-transition/helpers/navigator-route-registry.ts

@@ -0,0 +1,46 @@
+const mountedRoutesByNavigator = new Map<string, Set<string>>();
+
+export function registerMountedRoute(
+	navigatorKey: string,
+	routeKey: string,
+): void {
+	if (!navigatorKey || !routeKey) return;
+
+	let routes = mountedRoutesByNavigator.get(navigatorKey);
+	if (!routes) {
+		routes = new Set();
+		mountedRoutesByNavigator.set(navigatorKey, routes);
+	}
+
+	routes.add(routeKey);
+}
+
+/**
+ * Removes the route from its navigator set.
+ * Returns true when the navigator has no mounted routes left.
+ */
+export function unregisterMountedRoute(
+	navigatorKey: string,
+	routeKey: string,
+): boolean {
+	if (!navigatorKey || !routeKey) return false;
+
+	const routes = mountedRoutesByNavigator.get(navigatorKey);
+	if (!routes) return false;
+
+	routes.delete(routeKey);
+
+	if (routes.size > 0) {
+		return false;
+	}
+
+	mountedRoutesByNavigator.delete(navigatorKey);
+	return true;
+}
+
+/**
+ * @internal test helper
+ */
+export function _resetNavigatorRouteRegistry(): void {
+	mountedRoutesByNavigator.clear();
+}

package/src/shared/components/screen-lifecycle/hooks/use-close-transition/helpers/reset-stores-for-screen.ts

@@ -0,0 +1,27 @@
+import { runOnUI } from "react-native-reanimated";
+import { AnimationStore } from "../../../../../stores/animation.store";
+import { BoundStore } from "../../../../../stores/bounds";
+import { GestureStore } from "../../../../../stores/gesture.store";
+
+export const resetStoresForScreen = (
+	routeKey: string,
+	isBranchScreen: boolean,
+	branchNavigatorKey?: string,
+) => {
+	AnimationStore.clear(routeKey);
+	GestureStore.clear(routeKey);
+
+	runOnUI(() => {
+		"worklet";
+		if (!isBranchScreen) return;
+
+		BoundStore.clear(routeKey);
+
+		if (branchNavigatorKey) {
+			BoundStore.clearByBranch(branchNavigatorKey);
+			return;
+		}
+
+		BoundStore.clearByAncestor(routeKey);
+	})();
+};

package/src/shared/components/screen-lifecycle/hooks/use-close-transition/helpers/use-navigator-history-registry.ts

@@ -0,0 +1,58 @@
+import { useEffect } from "react";
+import { HistoryStore } from "../../../../../stores/history.store";
+
+const mountedRoutesByNavigator = new Map<string, Set<string>>();
+
+function registerMountedRoute(navigatorKey: string, routeKey: string): void {
+	if (!navigatorKey || !routeKey) return;
+
+	let routes = mountedRoutesByNavigator.get(navigatorKey);
+	if (!routes) {
+		routes = new Set();
+		mountedRoutesByNavigator.set(navigatorKey, routes);
+	}
+
+	routes.add(routeKey);
+}
+
+/**
+ * Removes the route from its navigator set.
+ * Returns true when the navigator has no mounted routes left.
+ */
+function unregisterMountedRoute(
+	navigatorKey: string,
+	routeKey: string,
+): boolean {
+	if (!navigatorKey || !routeKey) return false;
+
+	const routes = mountedRoutesByNavigator.get(navigatorKey);
+	if (!routes) return false;
+
+	routes.delete(routeKey);
+
+	if (routes.size > 0) {
+		return false;
+	}
+
+	mountedRoutesByNavigator.delete(navigatorKey);
+	return true;
+}
+
+export const useNavigatorHistoryRegistry = (
+	navigatorKey: string,
+	routeKey: string,
+) => {
+	useEffect(() => {
+		registerMountedRoute(navigatorKey, routeKey);
+
+		return () => {
+			const shouldClearNavigator = unregisterMountedRoute(
+				navigatorKey,
+				routeKey,
+			);
+			if (shouldClearNavigator) {
+				HistoryStore.clearNavigator(navigatorKey);
+			}
+		};
+	}, [navigatorKey, routeKey]);
+};

package/src/shared/{hooks/lifecycle/use-close-transition.ts → components/screen-lifecycle/hooks/use-close-transition/index.ts}

@@ -1,25 +1,32 @@
-import { useLayoutEffect } from "react";
+import { useEffect, useLayoutEffect } from "react";
 import {
 	runOnJS,
+	runOnUI,
 	useAnimatedReaction,
 	useDerivedValue,
 } from "react-native-reanimated";
-import { useGestureContext } from "../../providers/gestures.provider";
-import type { BaseDescriptor } from "../../providers/screen/keys.provider";
-import { useStackCoreContext } from "../../providers/stack/core.provider";
-import { useManagedStackContext } from "../../providers/stack/managed.provider";
-import type { AnimationStoreMap } from "../../stores/animation.store";
-import { StackType } from "../../types/stack.types";
-import { animateToProgress } from "../../utils/animation/animate-to-progress";
-import { resetStoresForScreen } from "../../utils/reset-stores-for-screen";
-import { useSharedValueState } from "../reanimated/use-shared-value-state";
-import useStableCallback from "../use-stable-callback";
-
-export interface CloseHookParams {
+import { useStack } from "../../../../hooks/navigation/use-stack";
+import { useSharedValueState } from "../../../../hooks/reanimated/use-shared-value-state";
+import useStableCallback from "../../../../hooks/use-stable-callback";
+import { useGestureContext } from "../../../../providers/gestures";
+import {
+	type BaseDescriptor,
+	useDescriptorDerivations,
+} from "../../../../providers/screen/descriptors";
+import { useStackCoreContext } from "../../../../providers/stack/core.provider";
+import { useManagedStackContext } from "../../../../providers/stack/managed.provider";
+import type { AnimationStoreMap } from "../../../../stores/animation.store";
+import { StackType } from "../../../../types/stack.types";
+import { animateToProgress } from "../../../../utils/animation/animate-to-progress";
+import { resetStoresForScreen } from "./helpers/reset-stores-for-screen";
+import { useNavigatorHistoryRegistry } from "./helpers/use-navigator-history-registry";
+
+interface CloseHookParams {
 	current: BaseDescriptor;
 	animations: AnimationStoreMap;
 	activate: () => void;
 	deactivate: () => void;
+	resetStores: () => void;
 }
 
 /**
@@ -31,19 +38,20 @@ const useManagedClose = ({
 	animations,
 	activate,
 	deactivate,
+	resetStores,
 }: CloseHookParams) => {
 	const { handleCloseRoute, closingRouteKeysShared } = useManagedStackContext();
+	const routeKey = current.route.key;
 
 	const handleCloseEnd = useStableCallback((finished: boolean) => {
 		if (!finished) return;
 		handleCloseRoute({ route: current.route });
 		requestAnimationFrame(() => {
 			deactivate();
-			resetStoresForScreen(current);
+			resetStores();
 		});
 	});
 
-	const routeKey = current.route.key;
 	const transitionSpec = current.options.transitionSpec;
 
 	useAnimatedReaction(
@@ -73,6 +81,7 @@ const useNativeStackClose = ({
 	animations,
 	activate,
 	deactivate,
+	resetStores,
 }: CloseHookParams) => {
 	const gestureCtx = useGestureContext();
 
@@ -80,8 +89,8 @@ const useNativeStackClose = ({
 		useDerivedValue(() => {
 			"worklet";
 			return (
-				gestureCtx?.ancestorContext?.gestureAnimationValues.isDismissing
-					?.value ?? false
+				gestureCtx?.ancestorContext?.gestureAnimationValues.dismissing?.value ??
+				false
 			);
 		}),
 	);
@@ -90,12 +99,17 @@ const useNativeStackClose = ({
 		const options = current.options as { enableTransitions?: boolean };
 		const isEnabled = options.enableTransitions;
 		const navigation = current.navigation;
-		const isFirstScreen = navigation.getState().index === 0;
+		const routeKey = current.route.key;
+		const state = navigation.getState();
+		const routeIndex = state.routes.findIndex(
+			(route) => route.key === routeKey,
+		);
+		const isFirstScreen = routeIndex <= 0;
 
 		// If transitions are disabled, ancestor is dismissing, or first screen - let native handle it
 		if (!isEnabled || isAncestorDismissingViaGesture || isFirstScreen) {
 			animations.closing.set(1);
-			resetStoresForScreen(current);
+			resetStores();
 			return;
 		}
 
@@ -111,7 +125,7 @@ const useNativeStackClose = ({
 				if (finished) {
 					navigation.dispatch(e.data.action);
 					requestAnimationFrame(() => {
-						resetStoresForScreen(current);
+						resetStores();
 					});
 				}
 			},
@@ -133,16 +147,25 @@ export function useCloseTransition(
 	activate: () => void,
 	deactivate: () => void,
 ) {
+	const routeKey = current.route.key;
+	const { navigatorKey } = useStack();
 	const { flags } = useStackCoreContext();
+	const { isBranchScreen, branchNavigatorKey } = useDescriptorDerivations();
 	const isNativeStack = flags.STACK_TYPE === StackType.NATIVE;
 
+	const resetStores = useStableCallback(() => {
+		resetStoresForScreen(routeKey, isBranchScreen, branchNavigatorKey);
+	});
+
 	const closeParams: CloseHookParams = {
 		current,
 		animations,
 		activate,
 		deactivate,
+		resetStores,
 	};
 
+	useNavigatorHistoryRegistry(navigatorKey, routeKey);
 	if (isNativeStack) {
 		// biome-ignore lint/correctness/useHookAtTopLevel: STACK_TYPE is stable per screen instance
 		useNativeStackClose(closeParams);

package/src/shared/{hooks/animation/use-high-refresh-rate.tsx → components/screen-lifecycle/hooks/use-high-refresh-rate.ts}

@@ -1,6 +1,6 @@
 import { useFrameCallback } from "react-native-reanimated";
-import type { BaseDescriptor } from "../../providers/screen/keys.provider";
-import useStableCallback from "../use-stable-callback";
+import useStableCallback from "../../../hooks/use-stable-callback";
+import type { BaseDescriptor } from "../../../providers/screen/descriptors";
 
 /**
  * Maintainer Notes:

package/src/shared/{hooks/lifecycle → components/screen-lifecycle/hooks}/use-open-transition.ts

@@ -1,8 +1,8 @@
 import { useLayoutEffect } from "react";
-import type { BaseDescriptor } from "../../providers/screen/keys.provider";
-import type { AnimationStoreMap } from "../../stores/animation.store";
-import { animateToProgress } from "../../utils/animation/animate-to-progress";
-import { useHighRefreshRate } from "../animation/use-high-refresh-rate";
+import type { BaseDescriptor } from "../../../providers/screen/descriptors";
+import type { AnimationStoreMap } from "../../../stores/animation.store";
+import { animateToProgress } from "../../../utils/animation/animate-to-progress";
+import { useHighRefreshRate } from "./use-high-refresh-rate";
 
 /**
  * Calculates the initial progress value based on snap points configuration.
@@ -32,6 +32,7 @@ function getInitialProgress({
 export function useOpenTransition(
 	current: BaseDescriptor,
 	animations: AnimationStoreMap,
+	isFirstKey: boolean,
 ) {
 	const { activateHighRefreshRate, deactivateHighRefreshRate } =
 		useHighRefreshRate(current);
@@ -40,6 +41,16 @@ export function useOpenTransition(
 	useLayoutEffect(() => {
 		const { snapPoints, initialSnapIndex = 0 } = current.options;
 		const targetProgress = getInitialProgress({ snapPoints, initialSnapIndex });
+		const target = targetProgress ?? 1;
+
+		if (isFirstKey) {
+			animations.targetProgress.set(target);
+			animations.progress.set(target);
+			animations.animating.set(0);
+			animations.closing.set(0);
+			animations.entering.set(1);
+			return;
+		}
 
 		activateHighRefreshRate();
 		animateToProgress({

package/src/shared/{hooks/lifecycle → components/screen-lifecycle/hooks}/use-screen-events.ts

@@ -1,9 +1,9 @@
 import { useEffect } from "react";
 import { runOnJS, useAnimatedReaction } from "react-native-reanimated";
-import type { BaseDescriptor } from "../../providers/screen/keys.provider";
-import type { AnimationStoreMap } from "../../stores/animation.store";
-import { HistoryStore } from "../../stores/history.store";
-import useStableCallback from "../use-stable-callback";
+import useStableCallback from "../../../hooks/use-stable-callback";
+import type { BaseDescriptor } from "../../../providers/screen/descriptors";
+import type { AnimationStoreMap } from "../../../stores/animation.store";
+import { HistoryStore } from "../../../stores/history.store";
 
 function hasSnapPoints(descriptor: BaseDescriptor): boolean {
 	const snapPoints = descriptor.options?.snapPoints;

package/src/shared/components/screen-lifecycle/index.tsx

@@ -0,0 +1,36 @@
+import {
+	useDescriptorDerivations,
+	useDescriptors,
+} from "../../providers/screen/descriptors";
+import { AnimationStore } from "../../stores/animation.store";
+import { useCloseTransition } from "./hooks/use-close-transition";
+import { useOpenTransition } from "./hooks/use-open-transition";
+import { useScreenEvents } from "./hooks/use-screen-events";
+
+interface Props {
+	children: React.ReactNode;
+}
+
+/**
+ * Unified lifecycle controller for all stack types.
+ * Reads current/previous descriptors from DescriptorsProvider context.
+ */
+export const ScreenLifecycle = ({ children }: Props) => {
+	const { current, previous } = useDescriptors();
+	const { isFirstKey } = useDescriptorDerivations();
+	const animations = AnimationStore.getRouteAnimations(current.route.key);
+
+	const { activateHighRefreshRate, deactivateHighRefreshRate } =
+		useOpenTransition(current, animations, isFirstKey);
+
+	useCloseTransition(
+		current,
+		animations,
+		activateHighRefreshRate,
+		deactivateHighRefreshRate,
+	);
+
+	useScreenEvents(current, previous, animations);
+
+	return children;
+};

package/src/shared/configs/index.ts

@@ -8,10 +8,12 @@ import {
 	SlideFromTop,
 	ZoomIn,
 } from "./presets";
-import { DefaultSpec } from "./specs";
+import { DefaultSnapSpec, DefaultSpec, FlingSpec } from "./specs";
 
 export const Specs = {
 	DefaultSpec,
+	DefaultSnapSpec,
+	FlingSpec,
 };
 
 export const Presets = {