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

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

@@ -0,0 +1,133 @@
+/** biome-ignore-all lint/style/noNonNullAssertion: <Screen gesture is under the gesture context, so this will always exist.> */
+import { memo, useEffect } from "react";
+import { StyleSheet, View } from "react-native";
+import { GestureDetector } from "react-native-gesture-handler";
+import Animated, {
+	useAnimatedProps,
+	useAnimatedStyle,
+} from "react-native-reanimated";
+import {
+	NAVIGATION_CONTAINER_STYLE_ID,
+	NAVIGATION_MASK_STYLE_ID,
+	NO_PROPS,
+	NO_STYLES,
+} from "../../../constants";
+import { useGestureContext } from "../../../providers/gestures";
+import { useDescriptors } from "../../../providers/screen/descriptors";
+import { useScreenStyles } from "../../../providers/screen/styles.provider";
+import { logger } from "../../../utils/logger";
+import { useBackdropPointerEvents } from "../hooks/use-backdrop-pointer-events";
+import { SurfaceContainer } from "./surface-container";
+
+type Props = {
+	children: React.ReactNode;
+};
+
+let LazyMaskedView = View;
+
+try {
+	LazyMaskedView = require("@react-native-masked-view/masked-view").default;
+} catch (_) {
+	// optional peer dependency
+}
+
+let hasWarnedMissingMaskedView = false;
+
+export const ContentLayer = memo(({ children }: Props) => {
+	const { stylesMap } = useScreenStyles();
+	const { current } = useDescriptors();
+	const { pointerEvents, isBackdropActive } = useBackdropPointerEvents();
+	const gestureContext = useGestureContext();
+	const isNavigationMaskEnabled = !!current.options.maskEnabled;
+	const contentPointerEvents = isBackdropActive ? "box-none" : pointerEvents;
+
+	// ── Content ──
+	const animatedContentStyle = useAnimatedStyle(() => {
+		"worklet";
+		return stylesMap.value.content?.style || NO_STYLES;
+	});
+
+	const animatedContentProps = useAnimatedProps(() => {
+		"worklet";
+		return stylesMap.value.content?.props ?? NO_PROPS;
+	});
+
+	// ── Navigation mask / container ──
+	const animatedNavigationContainerStyle = useAnimatedStyle(() => {
+		"worklet";
+		return stylesMap.value[NAVIGATION_CONTAINER_STYLE_ID]?.style || NO_STYLES;
+	});
+
+	const animatedNavigationMaskStyle = useAnimatedStyle(() => {
+		"worklet";
+		return stylesMap.value[NAVIGATION_MASK_STYLE_ID]?.style || NO_STYLES;
+	});
+
+	useEffect(() => {
+		if (!isNavigationMaskEnabled) return;
+		if (LazyMaskedView !== View) return;
+		if (hasWarnedMissingMaskedView) return;
+
+		hasWarnedMissingMaskedView = true;
+		logger.warn(
+			"maskEnabled requires @react-native-masked-view/masked-view. Install it to enable navigation bounds masking.",
+		);
+	}, [isNavigationMaskEnabled]);
+
+	const contentChildren = isNavigationMaskEnabled ? (
+		LazyMaskedView !== View ? (
+			<LazyMaskedView
+				style={styles.navigationMaskedRoot}
+				// @ts-expect-error masked-view package types are too strict here
+				maskElement={
+					<Animated.View
+						style={[styles.navigationMaskElement, animatedNavigationMaskStyle]}
+					/>
+				}
+			>
+				<Animated.View
+					style={[styles.navigationContainer, animatedNavigationContainerStyle]}
+				>
+					{children}
+				</Animated.View>
+			</LazyMaskedView>
+		) : (
+			<Animated.View
+				style={[styles.navigationContainer, animatedNavigationContainerStyle]}
+			>
+				{children}
+			</Animated.View>
+		)
+	) : (
+		children
+	);
+
+	return (
+		<GestureDetector gesture={gestureContext!.panGesture}>
+			<Animated.View
+				style={[styles.content, animatedContentStyle]}
+				animatedProps={animatedContentProps}
+				pointerEvents={contentPointerEvents}
+			>
+				<SurfaceContainer pointerEvents={contentPointerEvents}>
+					{contentChildren}
+				</SurfaceContainer>
+			</Animated.View>
+		</GestureDetector>
+	);
+});
+
+const styles = StyleSheet.create({
+	content: {
+		flex: 1,
+	},
+	navigationMaskedRoot: {
+		flex: 1,
+	},
+	navigationMaskElement: {
+		backgroundColor: "white",
+	},
+	navigationContainer: {
+		flex: 1,
+	},
+});

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,25 +38,29 @@ 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(
-		() => closingRouteKeysShared.value,
-		(keys) => {
-			if (!keys?.includes(routeKey)) return;
+		() => {
+			const keys = closingRouteKeysShared.value;
+			return keys?.includes(routeKey) ?? false;
+		},
+		(isClosing, wasClosing) => {
+			if (!isClosing || wasClosing) return;
 
 			runOnJS(activate)();
 			animateToProgress({
@@ -70,6 +81,7 @@ const useNativeStackClose = ({
 	animations,
 	activate,
 	deactivate,
+	resetStores,
 }: CloseHookParams) => {
 	const gestureCtx = useGestureContext();
 
@@ -77,8 +89,8 @@ const useNativeStackClose = ({
 		useDerivedValue(() => {
 			"worklet";
 			return (
-				gestureCtx?.ancestorContext?.gestureAnimationValues.isDismissing
-					?.value ?? false
+				gestureCtx?.ancestorContext?.gestureAnimationValues.dismissing?.value ??
+				false
 			);
 		}),
 	);
@@ -87,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;
 		}
 
@@ -108,7 +125,7 @@ const useNativeStackClose = ({
 				if (finished) {
 					navigation.dispatch(e.data.action);
 					requestAnimationFrame(() => {
-						resetStoresForScreen(current);
+						resetStores();
 					});
 				}
 			},
@@ -130,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 = {