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

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 };
+}

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

@@ -0,0 +1,112 @@
+import { useLayoutEffect } from "react";
+import { useAnimatedReaction } from "react-native-reanimated";
+import { scheduleOnRN } from "react-native-worklets";
+import { AnimationProgress } from "../../../../constants";
+import useStableCallback from "../../../../hooks/use-stable-callback";
+import {
+	type BaseDescriptor,
+	useBuilderStore,
+} from "../../../../providers/screen/builder";
+import {
+	LifecycleTransitionRequestKind,
+	type MotionTransitionValues,
+} from "../../../../providers/screen/motion/hooks/use-transition-values";
+import type { MotionAnimationValues } from "../../../../providers/screen/motion/types";
+import type { SnapPoint } from "../../../../types/screen.types";
+
+/**
+ * Calculates the initial progress value based on snap points configuration.
+ * Returns `'auto'` if the initial snap point is the `'auto'` keyword
+ * (meaning the animation must be deferred until content is measured).
+ */
+function getInitialProgress({
+	snapPoints,
+	initialSnapIndex,
+}: {
+	snapPoints?: SnapPoint[];
+	initialSnapIndex: number;
+}): SnapPoint | undefined {
+	if (!snapPoints) {
+		return undefined;
+	}
+
+	const clampedIndex = Math.min(
+		Math.max(0, initialSnapIndex),
+		snapPoints.length - 1,
+	);
+	return snapPoints[clampedIndex];
+}
+
+/**
+ * Handles opening transition intent on mount.
+ */
+export function useOpenTransitionIntent(
+	current: BaseDescriptor,
+	animations: MotionAnimationValues,
+	system: MotionTransitionValues,
+	onComplete?: () => void,
+) {
+	const isFirstKey = useBuilderStore((store) => store.derivations.isFirstKey);
+	const { requestLifecycleTransition } = system.actions;
+	const completeOpen = useStableCallback(() => {
+		onComplete?.();
+	});
+	const { animationProgress } = system;
+	const { closing } = animations;
+
+	useAnimatedReaction(
+		() => {
+			"worklet";
+			return (
+				!closing.get() && animationProgress.get() === AnimationProgress.Visible
+			);
+		},
+		(complete, previouslyComplete) => {
+			"worklet";
+			if (complete && !previouslyComplete) {
+				scheduleOnRN(completeOpen);
+			}
+		},
+	);
+
+	// biome-ignore lint/correctness/useExhaustiveDependencies: Must only run once on mount
+	useLayoutEffect(() => {
+		const {
+			snapPoints,
+			initialSnapIndex = 0,
+			experimental_animateOnInitialMount,
+		} = current.options;
+
+		const initialProgress = getInitialProgress({
+			snapPoints,
+			initialSnapIndex,
+		});
+
+		if (isFirstKey && !experimental_animateOnInitialMount) {
+			if (typeof initialProgress === "string") {
+				system.targetProgress.set(0);
+				animations.transitionProgress.set(0);
+			} else {
+				const target = initialProgress ?? AnimationProgress.Visible;
+				system.targetProgress.set(target);
+				animations.transitionProgress.set(target);
+			}
+			animations.progressAnimating.set(0);
+			animations.closing.set(0);
+			animations.entering.set(0);
+			return;
+		}
+
+		// When the initial snap point is 'auto', defer the opening animation until
+		// ScreenContainer has measured the content and set resolvedAutoSnapPoint.
+		if (typeof initialProgress === "string") {
+			return;
+		}
+
+		animations.entering.set(1);
+		requestLifecycleTransition(
+			LifecycleTransitionRequestKind.Open,
+			initialProgress ?? AnimationProgress.Visible,
+		);
+	}, []);
+}

package/src/components/screen/lifecycle/hooks/use-transition-start-controller.ts

@@ -0,0 +1,67 @@
+import { useAnimatedReaction } from "react-native-reanimated";
+import type { BaseDescriptor } from "../../../../providers/screen/builder";
+import { useMotionStore } from "../../../../providers/screen/motion";
+import {
+	LifecycleTransitionRequestKind,
+	type MotionTransitionValues,
+} from "../../../../providers/screen/motion/hooks/use-transition-values";
+import type { MotionAnimationValues } from "../../../../providers/screen/motion/types";
+import { animateToProgress } from "../../../../utils/animation/animate-to-progress";
+
+export const useTransitionStartController = ({
+	current,
+	animations,
+	system,
+}: {
+	current: BaseDescriptor;
+	animations: MotionAnimationValues;
+	system: MotionTransitionValues;
+}) => {
+	const {
+		targetProgress,
+		animationProgress,
+		pendingLifecycleRequestKind,
+		pendingLifecycleRequestTarget,
+		pendingLifecycleStartBlockCount,
+	} = system;
+	const { clearLifecycleTransitionRequest } = system.actions;
+	const transitionSpec = current.options.transitionSpec;
+	const isDragging = useMotionStore((store) => store.state.dragging);
+
+	useAnimatedReaction(
+		() => {
+			"worklet";
+			return [
+				pendingLifecycleRequestKind.get(),
+				pendingLifecycleRequestTarget.get(),
+				pendingLifecycleStartBlockCount.get(),
+			] as const;
+		},
+		(next) => {
+			"worklet";
+			const [kind, target, blockCount] = next;
+
+			if (kind === LifecycleTransitionRequestKind.None) {
+				return;
+			}
+
+			if (blockCount > 0) {
+				return;
+			}
+
+			animateToProgress({
+				target,
+				spec: transitionSpec,
+				emitWillAnimate:
+					kind !== LifecycleTransitionRequestKind.Open ||
+					!animations.entering.get(),
+				animations,
+				targetProgress,
+				animationProgress,
+				isDragging,
+			});
+
+			clearLifecycleTransitionRequest();
+		},
+	);
+};

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

@@ -0,0 +1,36 @@
+import { useBuilderStore } from "../../../providers/screen/builder";
+import { useMotionStore } from "../../../providers/screen/motion";
+import { useScreenHistory } from "./hooks/history/use-screen-history";
+import { useCloseCompletion } from "./hooks/use-close-completion";
+import { useOpenTransitionIntent } from "./hooks/use-open-transition-intent";
+import { useTransitionStartController } from "./hooks/use-transition-start-controller";
+
+export function useScreenLifecycle({
+	completeClose,
+	completeOpen,
+}: {
+	completeClose: () => void;
+	completeOpen?: () => void;
+}) {
+	const current = useBuilderStore((store) => store.descriptors.current);
+	const previous = useBuilderStore((store) => store.descriptors.previous);
+
+	const animations = useMotionStore((store) => store.state);
+	const system = animations;
+
+	useOpenTransitionIntent(current, animations, system, completeOpen);
+
+	useTransitionStartController({
+		current,
+		animations,
+		system,
+	});
+
+	useCloseCompletion({
+		closing: animations.closing,
+		animationProgress: system.animationProgress,
+		onComplete: completeClose,
+	});
+
+	useScreenHistory(current, previous, animations);
+}

package/src/components/screen/screen.tsx

@@ -0,0 +1,52 @@
+import { type ComponentType, memo, type ReactNode, useMemo } from "react";
+import { useNavigationHelpers } from "../../hooks/navigation/use-navigation-helpers";
+import { BuilderProvider } from "../../providers/screen/builder";
+import { MotionProvider } from "../../providers/screen/motion";
+import { OrchestratorProvider } from "../../providers/screen/orchestrator";
+import { useBlankStackStore } from "../../providers/stack/blank-stack.provider";
+import { ScreenContainer } from "./container";
+
+const SceneMotion = ({
+	children,
+	lifecycle: Lifecycle,
+}: {
+	children: ReactNode;
+	lifecycle: ComponentType;
+}) => {
+	const { requestDismiss } = useNavigationHelpers();
+	return (
+		<MotionProvider onDismissRequest={requestDismiss}>
+			<OrchestratorProvider>
+				<ScreenContainer onDismissRequest={requestDismiss}>
+					{children}
+				</ScreenContainer>
+			</OrchestratorProvider>
+			<Lifecycle />
+		</MotionProvider>
+	);
+};
+
+export const Screen = memo(function Screen({
+	routeKey,
+	children,
+	lifecycle,
+}: {
+	routeKey: string;
+	children: ReactNode;
+	lifecycle: ComponentType;
+}) {
+	const scene = useBlankStackStore((store) => store.scenesByKey[routeKey]);
+	const descriptors = useMemo(
+		() => ({
+			current: scene.descriptor,
+			previous: scene.previousDescriptor,
+			next: scene.nextDescriptor,
+		}),
+		[scene.descriptor, scene.previousDescriptor, scene.nextDescriptor],
+	);
+	return (
+		<BuilderProvider routeKey={routeKey} descriptors={descriptors}>
+			<SceneMotion lifecycle={lifecycle}>{children}</SceneMotion>
+		</BuilderProvider>
+	);
+});