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

package/src/components/screen/container/hooks/use-content-layout.ts

@@ -0,0 +1,84 @@
+import { useCallback } from "react";
+import { type LayoutChangeEvent, useWindowDimensions } from "react-native";
+import { scheduleOnUI } from "react-native-worklets";
+import { useOptionalBuilderStore } from "../../../../providers/screen/builder";
+import { useOptionalMotionStore } from "../../../../providers/screen/motion";
+import { LifecycleTransitionRequestKind } from "../../../../providers/screen/motion/hooks/use-transition-values";
+
+/** "content" identifies the full content wrapper and is reserved internally. */
+export function useContentLayout(styleId: string | undefined) {
+	const isContent = styleId === "content";
+	const builder = useOptionalBuilderStore((store) =>
+		isContent ||
+		(styleId !== undefined && store?.options.snapPoints?.includes(styleId))
+			? store
+			: null,
+	);
+	const { height: screenHeight } = useWindowDimensions();
+	const animations = useOptionalMotionStore((store) =>
+		builder ? store?.state : undefined,
+	);
+	const isFirstKey = builder?.derivations.isFirstKey;
+	const experimental_animateOnInitialMount =
+		builder?.options.experimental_animateOnInitialMount;
+	const snapPoint = isContent ? "auto" : styleId;
+	const measureSnap =
+		snapPoint !== undefined && builder?.options.snapPoints?.includes(snapPoint);
+
+	const handleLayout = useCallback(
+		(event: LayoutChangeEvent) => {
+			if (!animations) return;
+			const { targetProgress, resolvedAutoSnapPoint, measuredContentLayout } =
+				animations;
+			const { requestLifecycleTransition } = animations.actions;
+			const { width, height } = event.nativeEvent.layout;
+			if (width <= 0 || height <= 0) return;
+
+			const fraction = Math.min(height / screenHeight, 1);
+
+			scheduleOnUI(
+				(nextWidth: number, nextHeight: number, nextFraction: number) => {
+					"worklet";
+					if (isContent) {
+						measuredContentLayout.set({ width: nextWidth, height: nextHeight });
+					}
+					if (!measureSnap) return;
+
+					const isFirstMeasurement = resolvedAutoSnapPoint.get() <= 0;
+					resolvedAutoSnapPoint.set(nextFraction);
+
+					if (
+						!isFirstMeasurement ||
+						animations.transitionProgress.get() !== 0 ||
+						animations.progressAnimating.get() !== 0
+					) {
+						return;
+					}
+
+					if (isFirstKey && !experimental_animateOnInitialMount) {
+						targetProgress.set(nextFraction);
+						animations.transitionProgress.set(nextFraction);
+						return;
+					}
+
+					requestLifecycleTransition(
+						LifecycleTransitionRequestKind.Open,
+						nextFraction,
+					);
+				},
+				width,
+				height,
+				fraction,
+			);
+		},
+		[
+			animations,
+			isContent,
+			measureSnap,
+			isFirstKey,
+			screenHeight,
+			experimental_animateOnInitialMount,
+		],
+	);
+	return isContent || measureSnap ? handleLayout : undefined;
+}

package/src/components/screen/container/index.tsx

@@ -0,0 +1,39 @@
+import { memo } from "react";
+import { StyleSheet, View } from "react-native";
+import { useBackdropPointerEvents } from "./hooks/use-backdrop-pointer-events";
+import { BackdropLayer } from "./layers/backdrop";
+import { ContentLayer } from "./layers/content";
+
+export type ScreenContainerProps = {
+	children: React.ReactNode;
+	onDismissRequest?: () => void;
+};
+
+export const ScreenContainer = memo(
+	({ children, onDismissRequest }: ScreenContainerProps) => {
+		const { pointerEvents, isBackdropActive, backdropBehavior } =
+			useBackdropPointerEvents();
+
+		return (
+			<View style={styles.container} pointerEvents={pointerEvents}>
+				<BackdropLayer
+					onDismissRequest={onDismissRequest}
+					isBackdropActive={isBackdropActive}
+					backdropBehavior={backdropBehavior}
+				/>
+				<ContentLayer
+					pointerEvents={pointerEvents}
+					isBackdropActive={isBackdropActive}
+				>
+					{children}
+				</ContentLayer>
+			</View>
+		);
+	},
+);
+
+const styles = StyleSheet.create({
+	container: {
+		flex: 1,
+	},
+});

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

@@ -0,0 +1,140 @@
+import { memo, useCallback } from "react";
+import { Pressable, StyleSheet } from "react-native";
+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 { LayerComponent } from "../helpers/layer-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 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}
+		>
+			<LayerComponent
+				component={BackdropComponent}
+				styles={backdropStyles}
+				props={BackdropComponent ? backdropProps : undefined}
+				pointerEvents={backdropPointerEvents}
+			/>
+		</Pressable>
+	);
+});

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

@@ -0,0 +1,124 @@
+import { memo, useCallback } from "react";
+import {
+	I18nManager,
+	type LayoutChangeEvent,
+	StyleSheet,
+	View,
+	type ViewProps,
+	type ViewStyle,
+} from "react-native";
+import Animated, {
+	useAnimatedStyle,
+	useDerivedValue,
+	useSharedValue,
+} from "react-native-reanimated";
+import { useOrchestratorStore } from "../../../../providers/screen/orchestrator/orchestrator.provider";
+import type { Layout } from "../../../../types/screen.types";
+
+/** Stable layout host: changing the viewport must never resize the screen. */
+export const Clip = memo(
+	({
+		children,
+		pointerEvents,
+	}: {
+		children: React.ReactNode;
+		pointerEvents: ViewProps["pointerEvents"];
+	}) => {
+		const slotsMap = useOrchestratorStore((store) => store.slotsMap);
+		const screenInterpolatorProps = useOrchestratorStore(
+			(store) => store.screenInterpolatorProps,
+		);
+		const layout = useSharedValue<Layout | null>(null);
+
+		const onLayout = useCallback(
+			(event: LayoutChangeEvent) => {
+				const { width, height } = event.nativeEvent.layout;
+				layout.set({ width, height });
+			},
+			[layout],
+		);
+
+		const clippingStyles = useDerivedValue(() => {
+			const clipStyle = slotsMap.get().clip?.style;
+			// Reset-only slots have no rectangle dimensions.
+			const clip =
+				clipStyle?.width !== undefined && clipStyle.height !== undefined
+					? clipStyle
+					: undefined;
+			// Keep content independent of the viewport, even before onLayout.
+			const contentLayout =
+				layout.get() ?? screenInterpolatorProps.get().layouts.screen;
+			const x = clip?.x ?? 0;
+			const y = clip?.y ?? 0;
+
+			return {
+				viewport: {
+					width: clip ? clip.width : "100%",
+					height: clip ? clip.height : "100%",
+					overflow: clip ? "hidden" : "visible",
+					borderRadius: clip?.borderRadius,
+					borderTopLeftRadius: clip?.borderTopLeftRadius,
+					borderTopRightRadius: clip?.borderTopRightRadius,
+					borderBottomLeftRadius: clip?.borderBottomLeftRadius,
+					borderBottomRightRadius: clip?.borderBottomRightRadius,
+					borderTopStartRadius: clip?.borderTopStartRadius,
+					borderTopEndRadius: clip?.borderTopEndRadius,
+					borderBottomStartRadius: clip?.borderBottomStartRadius,
+					borderBottomEndRadius: clip?.borderBottomEndRadius,
+					borderStartStartRadius: clip?.borderStartStartRadius,
+					borderStartEndRadius: clip?.borderStartEndRadius,
+					borderEndStartRadius: clip?.borderEndStartRadius,
+					borderEndEndRadius: clip?.borderEndEndRadius,
+					borderCurve: clip?.borderCurve,
+					transform: [{ translateX: x }, { translateY: y }],
+				} satisfies ViewStyle,
+				content: {
+					width: contentLayout.width,
+					height: contentLayout.height,
+					transform: [{ translateX: -x }, { translateY: -y }],
+				},
+			};
+		});
+
+		const viewportStyle = useAnimatedStyle(() => clippingStyles.get().viewport);
+		const innerStyle = useAnimatedStyle(() => clippingStyles.get().content);
+
+		return (
+			<View
+				style={styles.host}
+				onLayout={onLayout}
+				pointerEvents={pointerEvents}
+				collapsable={false}
+			>
+				<Animated.View
+					style={[styles.viewport, viewportStyle]}
+					pointerEvents={pointerEvents}
+					collapsable={false}
+				>
+					<Animated.View
+						style={[styles.inner, innerStyle]}
+						pointerEvents={pointerEvents}
+						collapsable={false}
+					>
+						{children}
+					</Animated.View>
+				</Animated.View>
+			</View>
+		);
+	},
+);
+
+const styles = StyleSheet.create({
+	host: { flex: 1 },
+	// Pin to the physical left under both native layout directions.
+	viewport: {
+		position: "absolute",
+		top: 0,
+		...(I18nManager.isRTL ? { end: 0 } : { left: 0 }),
+	},
+	inner: {
+		...(I18nManager.isRTL
+			? { alignSelf: "flex-end" as const }
+			: { alignSelf: "flex-start" as const }),
+	},
+});

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

@@ -0,0 +1,72 @@
+import { memo } from "react";
+import { StyleSheet, View } from "react-native";
+import { GestureDetector } from "react-native-gesture-handler";
+import { useBuilderStore } from "../../../../providers/screen/builder";
+import { useMotionStore } from "../../../../providers/screen/motion";
+import {
+	useSlotProps,
+	useSlotStyles,
+} from "../../../../providers/screen/orchestrator/styles";
+import { PortalOverlay } from "../../../boundary/portal/components/portal-overlay";
+import { LayerComponent } from "../helpers/layer-component";
+import { useContentLayout } from "../hooks/use-content-layout";
+import { Clip } from "./clip";
+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 hasAutoSnapPoint = useBuilderStore(
+			(store) => store.options.snapPoints?.includes("auto") ?? false,
+		);
+		const contentPointerEvents = isBackdropActive ? "box-none" : pointerEvents;
+
+		const handleContentLayout = useContentLayout("content");
+
+		const contentStyle = useSlotStyles("content");
+		const contentProps = useSlotProps("content");
+
+		const contentStyles = [styles.content, contentStyle];
+
+		const screenChildren = hasAutoSnapPoint ? (
+			<View collapsable={false} onLayout={handleContentLayout}>
+				{children}
+			</View>
+		) : (
+			children
+		);
+
+		return (
+			<GestureDetector gesture={gestureContext.detectorGesture}>
+				<LayerComponent
+					component={ContentComponent}
+					styles={contentStyles}
+					props={contentProps}
+					pointerEvents={contentPointerEvents}
+				>
+					<Clip pointerEvents={contentPointerEvents}>
+						<SurfaceLayer pointerEvents={contentPointerEvents}>
+							{screenChildren}
+						</SurfaceLayer>
+						<PortalOverlay fallback />
+					</Clip>
+				</LayerComponent>
+			</GestureDetector>
+		);
+	},
+);
+
+const styles = StyleSheet.create({
+	content: {
+		flex: 1,
+	},
+});

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

@@ -0,0 +1,50 @@
+import { memo } from "react";
+import { StyleSheet } from "react-native";
+import { useBuilderStore } from "../../../../providers/screen/builder";
+import {
+	useSlotProps,
+	useSlotStyles,
+} from "../../../../providers/screen/orchestrator/styles";
+import type { ScreenSurfaceComponentProps } from "../../../../types";
+import { LayerComponent } from "../helpers/layer-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 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;
+	}
+
+	return (
+		<LayerComponent
+			component={SurfaceComponent}
+			styles={surfaceStyles}
+			props={surfaceProps}
+			pointerEvents={pointerEvents}
+		>
+			{children}
+		</LayerComponent>
+	);
+});
+
+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 };
+}