react-native-screen-transitions 4.1.0-alpha.0 → 4.1.0-beta.0

package/src/components/screen/container/layers/backdrop.tsx

@@ -0,0 +1,163 @@
+import { type ComponentType, memo, useCallback, useMemo } from "react";
+import { Pressable, StyleSheet } from "react-native";
+import Animated from "react-native-reanimated";
+import { scheduleOnRN, scheduleOnUI } from "react-native-worklets";
+import { DefaultSnapSpec } from "../../../../configs/specs";
+import { useBuilderStore } from "../../../../providers/screen/builder";
+import { useMotionStore } from "../../../../providers/screen/motion";
+import {
+	useSlotProps,
+	useSlotStyles,
+} from "../../../../providers/screen/orchestrator/styles";
+import type {
+	BackdropBehavior,
+	ScreenBackdropComponentProps,
+} from "../../../../types/screen.types";
+import { animateToProgress } from "../../../../utils/animation/animate-to-progress";
+import { findCollapseTarget } from "../helpers/find-collapse-target";
+import { usesLayerRenderProps } from "./render-component";
+
+export const BackdropLayer = memo(function BackdropLayer({
+	backdropBehavior,
+	isBackdropActive,
+	onDismissRequest,
+}: {
+	backdropBehavior: BackdropBehavior;
+	isBackdropActive: boolean;
+	onDismissRequest?: () => void;
+}) {
+	const BackdropComponent = useBuilderStore(
+		(store) => store.options.backdropComponent,
+	);
+	const rawSnapPoints = useBuilderStore((store) => store.options.snapPoints);
+	const isGestureDismissEnabled = useBuilderStore(
+		(store) => store.options.gestureEnabled !== false,
+	);
+	const canDismiss = isGestureDismissEnabled;
+	const transitionSpec = useBuilderStore(
+		(store) => store.options.transitionSpec,
+	);
+	const animations = useMotionStore((store) => store.state);
+	const { targetProgress, animationProgress, resolvedAutoSnapPoint } =
+		animations;
+
+	const AnimatedBackdropComponent = useMemo(
+		() =>
+			BackdropComponent && !usesLayerRenderProps(BackdropComponent)
+				? Animated.createAnimatedComponent(
+						BackdropComponent as ComponentType<any>,
+					)
+				: null,
+		[BackdropComponent],
+	);
+
+	const handleBackdropPress = useCallback(() => {
+		if (backdropBehavior === "dismiss") {
+			onDismissRequest?.();
+			return;
+		}
+
+		if (backdropBehavior === "collapse") {
+			// No snap points → fallback to dismiss
+			if (!rawSnapPoints || rawSnapPoints.length === 0) {
+				onDismissRequest?.();
+				return;
+			}
+
+			const gestures = animations;
+
+			scheduleOnUI(() => {
+				"worklet";
+				const resolvedSnaps: number[] = [];
+
+				for (let i = 0; i < rawSnapPoints.length; i++) {
+					const point = rawSnapPoints[i];
+					const resolvedPoint =
+						typeof point === "string" ? resolvedAutoSnapPoint.get() : point;
+
+					if (typeof resolvedPoint === "number") {
+						resolvedSnaps.push(resolvedPoint);
+					}
+				}
+
+				const { target, shouldDismiss } = findCollapseTarget(
+					animations.transitionProgress.get(),
+					resolvedSnaps,
+					canDismiss,
+				);
+
+				// If already dismissing, skip
+				if (gestures.dismissing.get()) return;
+
+				gestures.dismissing.set(shouldDismiss ? 1 : 0);
+
+				const spec = shouldDismiss
+					? transitionSpec
+					: {
+							open: transitionSpec?.expand ?? DefaultSnapSpec,
+							close: transitionSpec?.collapse ?? DefaultSnapSpec,
+						};
+
+				animateToProgress({
+					target,
+					markEntering: false,
+					spec,
+					animations,
+					targetProgress,
+					animationProgress,
+				});
+
+				if (shouldDismiss) {
+					if (onDismissRequest) scheduleOnRN(onDismissRequest);
+				}
+			});
+		}
+	}, [
+		animations,
+		targetProgress,
+		animationProgress,
+		resolvedAutoSnapPoint,
+		backdropBehavior,
+		rawSnapPoints,
+		canDismiss,
+		transitionSpec,
+		onDismissRequest,
+	]);
+
+	const animatedBackdropStyle = useSlotStyles("backdrop");
+	const animatedBackdropProps = useSlotProps("backdrop");
+	const backdropPointerEvents = isBackdropActive ? "auto" : "none";
+	const backdropStyles = [
+		StyleSheet.absoluteFill,
+		animatedBackdropStyle,
+	] as ScreenBackdropComponentProps["styles"];
+	const backdropProps =
+		animatedBackdropProps as ScreenBackdropComponentProps["props"];
+
+	return (
+		<Pressable
+			style={StyleSheet.absoluteFill}
+			pointerEvents={backdropBehavior === "passthrough" ? "none" : "auto"}
+			onPress={isBackdropActive ? handleBackdropPress : undefined}
+		>
+			{AnimatedBackdropComponent ? (
+				<AnimatedBackdropComponent
+					style={backdropStyles}
+					animatedProps={animatedBackdropProps}
+					pointerEvents={backdropPointerEvents}
+				/>
+			) : BackdropComponent ? (
+				<BackdropComponent
+					styles={backdropStyles}
+					props={backdropProps}
+					pointerEvents={backdropPointerEvents}
+				/>
+			) : (
+				<Animated.View
+					style={backdropStyles}
+					pointerEvents={backdropPointerEvents}
+				/>
+			)}
+		</Pressable>
+	);
+});

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

@@ -0,0 +1,113 @@
+import { type ComponentType, memo, useMemo } from "react";
+import { StyleSheet, View } from "react-native";
+import { GestureDetector } from "react-native-gesture-handler";
+import Animated from "react-native-reanimated";
+import { useBuilderStore } from "../../../../providers/screen/builder";
+import { useMotionStore } from "../../../../providers/screen/motion";
+import {
+	useSlotProps,
+	useSlotStyles,
+} from "../../../../providers/screen/orchestrator/styles";
+import type { ScreenContentComponentProps } from "../../../../types";
+import { ScreenFallbackHost } from "../../../boundary/portal/components/boundary-portal/components/host";
+import { useContentLayout } from "../hooks/use-content-layout";
+import { MaybeMaskedNavigationContainer } from "./maybe-masked-navigation-container";
+import { usesLayerRenderProps } from "./render-component";
+import { SurfaceLayer } from "./surface";
+
+type Props = {
+	children: React.ReactNode;
+	pointerEvents: "box-none" | undefined;
+	isBackdropActive: boolean;
+};
+
+export const ContentLayer = memo(
+	({ children, pointerEvents, isBackdropActive }: Props) => {
+		const gestureContext = useMotionStore((store) => store.gestures);
+		const ContentComponent = useBuilderStore(
+			(store) => store.options.contentComponent,
+		);
+		const isNavigationMaskEnabled = useBuilderStore(
+			(store) => !!store.options.navigationMaskEnabled,
+		);
+		const hasAutoSnapPoint = useBuilderStore(
+			(store) => store.options.snapPoints?.includes("auto") ?? false,
+		);
+		const contentPointerEvents = isBackdropActive ? "box-none" : pointerEvents;
+
+		const AnimatedContentComponent = useMemo(() => {
+			return ContentComponent && !usesLayerRenderProps(ContentComponent)
+				? Animated.createAnimatedComponent(
+						ContentComponent as ComponentType<any>,
+					)
+				: null;
+		}, [ContentComponent]);
+
+		const handleContentLayout = useContentLayout("content");
+
+		const animatedContentStyle = useSlotStyles("content");
+		const animatedContentProps = useSlotProps("content");
+		const contentStyles = [
+			styles.content,
+			animatedContentStyle,
+		] as ScreenContentComponentProps["styles"];
+		const contentProps =
+			animatedContentProps as ScreenContentComponentProps["props"];
+
+		const screenChildren = hasAutoSnapPoint ? (
+			<View collapsable={false} onLayout={handleContentLayout}>
+				{children}
+			</View>
+		) : (
+			children
+		);
+
+		const contentChildren = (
+			<MaybeMaskedNavigationContainer
+				pointerEvents={contentPointerEvents}
+				enabled={isNavigationMaskEnabled}
+			>
+				<SurfaceLayer pointerEvents={contentPointerEvents}>
+					{screenChildren}
+				</SurfaceLayer>
+				<ScreenFallbackHost />
+			</MaybeMaskedNavigationContainer>
+		);
+
+		return (
+			<GestureDetector gesture={gestureContext.detectorGesture}>
+				{AnimatedContentComponent ? (
+					<AnimatedContentComponent
+						style={contentStyles}
+						animatedProps={animatedContentProps}
+						pointerEvents={contentPointerEvents}
+					>
+						{contentChildren}
+					</AnimatedContentComponent>
+				) : ContentComponent ? (
+					<ContentComponent
+						styles={contentStyles}
+						props={contentProps}
+						pointerEvents={contentPointerEvents}
+					>
+						{contentChildren}
+					</ContentComponent>
+				) : (
+					<Animated.View
+						style={contentStyles}
+						animatedProps={animatedContentProps}
+						pointerEvents={contentPointerEvents}
+					>
+						{contentChildren}
+					</Animated.View>
+				)}
+			</GestureDetector>
+		);
+	},
+);
+
+const styles = StyleSheet.create({
+	content: {
+		flex: 1,
+	},
+});

package/src/components/screen/container/layers/maybe-masked-navigation-container.tsx

@@ -0,0 +1,113 @@
+import { memo, useCallback } from "react";
+import { I18nManager, StyleSheet, View, type ViewProps } from "react-native";
+import Animated from "react-native-reanimated";
+import {
+	NAVIGATION_MASK_CONTAINER_STYLE_ID,
+	NAVIGATION_MASK_ELEMENT_STYLE_ID,
+} from "../../../../constants";
+import { useSlotStyles } from "../../../../providers/screen/orchestrator/styles";
+import { logger } from "../../../../utils/logger";
+
+type Props = {
+	enabled: boolean;
+	children: React.ReactNode;
+	pointerEvents: ViewProps["pointerEvents"];
+};
+
+let LazyMaskedView = View;
+
+try {
+	LazyMaskedView = require("@react-native-masked-view/masked-view").default;
+} catch (_) {
+	// optional peer dependency
+}
+
+let hasWarnedMissingMaskedView = false;
+
+export const MaybeMaskedNavigationContainer = memo(
+	({ enabled, children, pointerEvents }: Props) => {
+		if (!enabled || LazyMaskedView === View) {
+			return children;
+		}
+
+		return (
+			<MaskedNavigationContainer pointerEvents={pointerEvents}>
+				{children}
+			</MaskedNavigationContainer>
+		);
+	},
+);
+
+const MaskedNavigationContainer = memo(
+	({
+		children,
+		pointerEvents,
+	}: {
+		children: React.ReactNode;
+		pointerEvents: ViewProps["pointerEvents"];
+	}) => {
+		const maybeLogWarning = useCallback(() => {
+			if (LazyMaskedView !== View) return;
+			if (hasWarnedMissingMaskedView) return;
+
+			hasWarnedMissingMaskedView = true;
+			logger.warn(
+				"navigationMaskEnabled requires @react-native-masked-view/masked-view. Install it to enable navigation bounds masking.",
+			);
+		}, []);
+
+		const animatedNavigationMaskStyle = useSlotStyles(
+			NAVIGATION_MASK_ELEMENT_STYLE_ID,
+		);
+		const animatedNavigationMaskContainerStyle = useSlotStyles(
+			NAVIGATION_MASK_CONTAINER_STYLE_ID,
+		);
+
+		return (
+			<LazyMaskedView
+				style={styles.navigationMaskedRoot}
+				// @ts-expect-error masked-view package types are too strict here
+				maskElement={
+					<Animated.View
+						style={[styles.navigationMaskElement, animatedNavigationMaskStyle]}
+						pointerEvents="none"
+					/>
+				}
+				pointerEvents={pointerEvents}
+				onLayout={maybeLogWarning}
+			>
+				<Animated.View
+					style={[
+						styles.navigationContainer,
+						animatedNavigationMaskContainerStyle,
+					]}
+					collapsable={false}
+				>
+					{children}
+				</Animated.View>
+			</LazyMaskedView>
+		);
+	},
+);
+
+const styles = StyleSheet.create({
+	navigationMaskedRoot: {
+		flex: 1,
+	},
+	navigationContainer: {
+		flex: 1,
+	},
+	// The mask rect's translate math assumes a physical top-left base. Under
+	// native RTL a fixed-width flex child anchors to the right edge, so pin it
+	// to the physical left (`end` = left edge in RTL).
+	navigationMaskElement: I18nManager.isRTL
+		? {
+				backgroundColor: "white",
+				end: 0,
+				position: "absolute",
+				top: 0,
+			}
+		: {
+				backgroundColor: "white",
+			},
+});

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

@@ -0,0 +1,68 @@
+import { type ComponentType, memo, useMemo } from "react";
+import { StyleSheet } from "react-native";
+import Animated from "react-native-reanimated";
+import { useBuilderStore } from "../../../../providers/screen/builder";
+import {
+	useSlotProps,
+	useSlotStyles,
+} from "../../../../providers/screen/orchestrator/styles";
+import type { ScreenSurfaceComponentProps } from "../../../../types";
+import { usesLayerRenderProps } from "./render-component";
+
+type Props = {
+	children: React.ReactNode;
+	pointerEvents: "box-none" | undefined;
+};
+
+export const SurfaceLayer = memo(({ children, pointerEvents }: Props) => {
+	const SurfaceComponent = useBuilderStore(
+		(store) => store.options.surfaceComponent,
+	);
+
+	const AnimatedSurfaceComponent = useMemo(() => {
+		return SurfaceComponent && !usesLayerRenderProps(SurfaceComponent)
+			? Animated.createAnimatedComponent(SurfaceComponent as ComponentType<any>)
+			: null;
+	}, [SurfaceComponent]);
+
+	const animatedSurfaceStyle = useSlotStyles("surface");
+	const animatedSurfaceProps = useSlotProps("surface");
+	const surfaceStyles = [
+		styles.surface,
+		animatedSurfaceStyle,
+	] as ScreenSurfaceComponentProps["styles"];
+	const surfaceProps =
+		animatedSurfaceProps as ScreenSurfaceComponentProps["props"];
+
+	if (!SurfaceComponent) {
+		return children;
+	}
+
+	if (AnimatedSurfaceComponent) {
+		return (
+			<AnimatedSurfaceComponent
+				style={surfaceStyles}
+				animatedProps={animatedSurfaceProps}
+				pointerEvents={pointerEvents}
+			>
+				{children}
+			</AnimatedSurfaceComponent>
+		);
+	}
+
+	return (
+		<SurfaceComponent
+			styles={surfaceStyles}
+			props={surfaceProps}
+			pointerEvents={pointerEvents}
+		>
+			{children}
+		</SurfaceComponent>
+	);
+});
+
+const styles = StyleSheet.create({
+	surface: {
+		flex: 1,
+	},
+});

package/src/components/screen/lifecycle/blank-stack.tsx

@@ -0,0 +1,18 @@
+import { useBuilderStore } from "../../../providers/screen/builder";
+import { useBlankStackStore } from "../../../providers/stack/blank-stack.provider";
+import { useCloseTransitionIntent } from "./hooks/use-close-transition-intent";
+import { useScreenLifecycle } from "./use-screen-lifecycle";
+
+export function BlankStackLifecycle() {
+	const current = useBuilderStore((store) => store.descriptors.current);
+	const handleOpenRoute = useBlankStackStore((store) => store.handleOpenRoute);
+
+	const { completeClose } = useCloseTransitionIntent(current);
+
+	useScreenLifecycle({
+		completeClose,
+		completeOpen: () => handleOpenRoute?.({ route: current.route }),
+	});
+
+	return null;
+}

package/src/components/screen/lifecycle/hooks/helpers/reset-stores-for-screen.ts

@@ -0,0 +1,9 @@
+import { scheduleOnUI } from "react-native-worklets";
+import { clear } from "../../../../../stores/bounds/internals/clear";
+import { ScrollStore } from "../../../../../stores/scroll.store";
+
+export function resetStoresForScreen(routeKey: string) {
+	ScrollStore.clearBag(routeKey);
+
+	scheduleOnUI(clear, routeKey);
+}

package/src/components/screen/lifecycle/hooks/history/use-screen-history.ts

@@ -0,0 +1,90 @@
+import { useEffect } from "react";
+import { useAnimatedReaction } from "react-native-reanimated";
+import { scheduleOnRN } from "react-native-worklets";
+import useStableCallback from "../../../../../hooks/use-stable-callback";
+import type { BaseDescriptor } from "../../../../../providers/screen/builder";
+import type { MotionAnimationValues } from "../../../../../providers/screen/motion/types";
+import { HistoryStore } from "../../../../../stores/history.store";
+import {
+	registerMountedRoute,
+	unregisterMountedRoute,
+} from "./navigator-route-registry";
+
+function hasSnapPoints(descriptor: BaseDescriptor): boolean {
+	const snapPoints = descriptor.options?.snapPoints;
+	return Boolean(snapPoints && snapPoints.length > 0);
+}
+
+/**
+ * Check if a screen is a leaf (renders visible content) vs a navigator container.
+ * Navigator containers have nested state with routes.
+ */
+function isLeafScreen(navigation: BaseDescriptor["navigation"]): boolean {
+	const state = navigation.getState();
+	const index = state?.index ?? -1;
+	const currentRoute = state?.routes?.[index];
+	if (!currentRoute) return false;
+	return !("state" in currentRoute);
+}
+
+function shouldTrackInHistory(descriptor: BaseDescriptor): boolean {
+	return hasSnapPoints(descriptor) || isLeafScreen(descriptor.navigation);
+}
+
+/**
+ * Keeps navigator route registration and screen history in sync.
+ */
+export function useScreenHistory(
+	current: BaseDescriptor,
+	previous: BaseDescriptor | undefined,
+	animations: MotionAnimationValues,
+) {
+	const navigatorKey = current.navigation.getState()?.key ?? "";
+	const routeKey = current.route.key;
+
+	useEffect(() => {
+		registerMountedRoute(navigatorKey, routeKey);
+
+		return () => {
+			const shouldClearNavigator = unregisterMountedRoute(
+				navigatorKey,
+				routeKey,
+			);
+			if (shouldClearNavigator) {
+				HistoryStore.clearNavigator(navigatorKey);
+			}
+		};
+	}, [navigatorKey, routeKey]);
+
+	// Track history via focus listener - waits for nested navigators to initialize
+	// biome-ignore lint/correctness/useExhaustiveDependencies: Must only run once on mount
+	useEffect(() => {
+		if (shouldTrackInHistory(current)) {
+			HistoryStore.focus(current, navigatorKey);
+		}
+
+		const unsubscribe = current.navigation.addListener?.("focus", () => {
+			if (shouldTrackInHistory(current)) {
+				HistoryStore.focus(current, navigatorKey);
+			}
+		});
+
+		return () => unsubscribe?.();
+	}, []);
+
+	const handleBlur = useStableCallback(() => {
+		if (previous && shouldTrackInHistory(previous)) {
+			const prevNavigatorKey = previous.navigation.getState()?.key ?? "";
+			HistoryStore.focus(previous, prevNavigatorKey);
+		}
+	});
+
+	useAnimatedReaction(
+		() => animations.closing.get(),
+		(closing, prevClosing) => {
+			if (closing && !prevClosing) {
+				scheduleOnRN(handleBlur);
+			}
+		},
+	);
+}

package/src/components/screen/lifecycle/hooks/use-close-completion.ts

@@ -0,0 +1,28 @@
+import { type SharedValue, useAnimatedReaction } from "react-native-reanimated";
+import { scheduleOnRN } from "react-native-worklets";
+import { AnimationProgress } from "../../../../constants";
+
+export const useCloseCompletion = ({
+	closing,
+	animationProgress,
+	onComplete,
+}: {
+	closing: SharedValue<number>;
+	animationProgress: SharedValue<number>;
+	onComplete: () => void;
+}) => {
+	useAnimatedReaction(
+		() => {
+			"worklet";
+			return (
+				!!closing.get() && animationProgress.get() <= AnimationProgress.Hidden
+			);
+		},
+		(complete, previouslyComplete) => {
+			"worklet";
+			if (complete && !previouslyComplete) {
+				scheduleOnRN(onComplete);
+			}
+		},
+	);
+};

package/src/components/screen/lifecycle/hooks/use-close-transition-intent.ts

@@ -0,0 +1,29 @@
+import { useLayoutEffect } from "react";
+import { useNavigationHelpers } from "../../../../hooks/navigation/use-navigation-helpers";
+import useStableCallback from "../../../../hooks/use-stable-callback";
+import type { BaseDescriptor } from "../../../../providers/screen/builder";
+import { useBlankStackStore } from "../../../../providers/stack/blank-stack.provider";
+import { resetStoresForScreen } from "./helpers/reset-stores-for-screen";
+
+export function useCloseTransitionIntent(current: BaseDescriptor) {
+	const handleCloseRoute = useBlankStackStore(
+		(store) => store.handleCloseRoute,
+	);
+
+	const closing = useBlankStackStore(
+		(store) => store.scenesByKey[current.route.key]?.activity === "closing",
+	);
+
+	const { requestDismiss } = useNavigationHelpers();
+
+	const completeClose = useStableCallback(() => {
+		handleCloseRoute?.({ route: current.route });
+		resetStoresForScreen(current.route.key);
+	});
+
+	useLayoutEffect(() => {
+		if (closing) requestDismiss();
+	}, [closing, requestDismiss]);
+
+	return { completeClose };
+}