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

package/src/components/overlay/helpers/create-overlay-interpolator-frame.ts

@@ -1,5 +1,5 @@
-import { updateDerivations } from "../../../providers/screen/orchestrator/helpers/derivations";
-import type { ScreenInterpolatorFrame } from "../../../providers/screen/orchestrator/helpers/pipeline";
+import { updateDerivations } from "../../../providers/orchestrator/helpers/derivations";
+import type { ScreenInterpolatorFrame } from "../../../providers/orchestrator/helpers/pipeline";
 
 export const shouldUseOverlayGestureDriver = (
 	overlayFrame: ScreenInterpolatorFrame,

package/src/components/overlay/helpers/retain-ready-overlay-resources.ts

@@ -1,5 +1,5 @@
 import type { SharedValue } from "react-native-reanimated";
-import type { OrchestratorState } from "../../../providers/screen/orchestrator/orchestrator.provider";
+import type { OrchestratorState } from "../../../providers/orchestrator/orchestrator.provider";
 import type { FloatOverlayEntry } from "./get-active-overlay";
 
 export type ReadyOverlayResources = {

package/src/components/overlay/helpers/run-overlay-slot-interpolator.ts

@@ -1,7 +1,7 @@
-import type { ScreenInterpolatorFrame } from "../../../providers/screen/orchestrator/helpers/pipeline";
-import { createInterpolatorScope } from "../../../providers/screen/orchestrator/styles/helpers/create-interpolator-scope";
-import { normalizeSlots } from "../../../providers/screen/orchestrator/styles/helpers/normalize-slots";
-import { selectInterpolatorFrame } from "../../../providers/screen/orchestrator/styles/helpers/select-interpolator-frame";
+import type { ScreenInterpolatorFrame } from "../../../providers/orchestrator/helpers/pipeline";
+import { createInterpolatorScope } from "../../../providers/orchestrator/styles/helpers/create-interpolator-scope";
+import { normalizeSlots } from "../../../providers/orchestrator/styles/helpers/normalize-slots";
+import { selectInterpolatorFrame } from "../../../providers/orchestrator/styles/helpers/select-interpolator-frame";
 import type {
 	NormalizedTransitionSlotStyle,
 	ScreenStyleInterpolator,

package/src/components/overlay/hooks/use-overlay-slot.ts

@@ -6,7 +6,7 @@ import {
 	useDerivedValue,
 } from "react-native-reanimated";
 import { NO_PROPS, NO_STYLES } from "../../../constants";
-import type { OrchestratorState } from "../../../providers/screen/orchestrator/orchestrator.provider";
+import type { OrchestratorState } from "../../../providers/orchestrator/orchestrator.provider";
 import type {
 	NormalizedTransitionSlotStyle,
 	ScreenStyleInterpolator,

package/src/components/overlay/index.tsx

@@ -0,0 +1,33 @@
+import { useBlankStackStore } from "../../navigators/blank-stack/state/blank-stack.provider";
+
+import {
+	getFloatOverlayStack,
+	getFloatOverlayTransitions,
+} from "./helpers/get-active-overlay";
+import { OverlayHost } from "./variations/overlay-host";
+
+/**
+ * Overlay component that renders above all screens.
+ * Gets routes and descriptors from stack context.
+ */
+export function Overlay() {
+	const scenes = useBlankStackStore((store) => store.scenes);
+
+	const overlayStack = getFloatOverlayStack(scenes);
+
+	if (overlayStack.length === 0) {
+		return null;
+	}
+
+	const overlayTransitions = getFloatOverlayTransitions(overlayStack, scenes);
+
+	return overlayTransitions.map(({ scene, driverScene }, layerIndex) => (
+		<OverlayHost
+			key={scene.route.key}
+			scene={scene}
+			driverScene={driverScene}
+			previousOverlayScene={overlayTransitions[layerIndex - 1]?.scene}
+			layerIndex={layerIndex}
+		/>
+	));
+}

package/src/components/overlay/variations/overlay-host.tsx

@@ -4,14 +4,14 @@ import Animated, {
 	type SharedValue,
 	useDerivedValue,
 } from "react-native-reanimated";
-import { snapDescriptorToIndex } from "../../../animation/snap-to";
-import { useOptionalMotionStore } from "../../../providers/screen/motion";
-import { useOptionalOrchestratorStore } from "../../../providers/screen/orchestrator";
+import { snapDescriptorToIndex } from "../../../controls/snap-to";
+import { useBlankStackStore } from "../../../navigators/blank-stack/state/blank-stack.provider";
+import { useOptionalMotionStore } from "../../../providers/motion";
+import { useOptionalOrchestratorStore } from "../../../providers/orchestrator";
 import {
 	OrchestratorProvider,
 	type OrchestratorState,
-} from "../../../providers/screen/orchestrator/orchestrator.provider";
-import { useBlankStackStore } from "../../../providers/stack/blank-stack.provider";
+} from "../../../providers/orchestrator/orchestrator.provider";
 import type { OverlayProps } from "../../../types/overlay.types";
 import type { FloatOverlayEntry } from "../helpers/get-active-overlay";
 import {

package/src/components/screen-layers/helpers/find-collapse-target.ts

@@ -0,0 +1,62 @@
+import { EPSILON } from "../../../constants";
+import { sanitizeSnapPoints } from "../../../providers/motion/gestures/shared/snap-points";
+
+interface FindCollapseTargetResult {
+	target: number;
+	shouldDismiss: boolean;
+}
+
+/**
+ * Finds the next lower snap point for backdrop collapse behavior.
+ *
+ * - If above min snap: returns next lower snap point
+ * - If at or below min snap: returns 0 (dismiss) if canDismiss, else stays at min
+ *
+ * @param currentProgress - Current animation progress
+ * @param snapPoints - Array of snap points
+ * @param canDismiss - Whether dismissing is allowed
+ */
+export function findCollapseTarget(
+	currentProgress: number,
+	snapPoints: number[],
+	canDismiss: boolean,
+): FindCollapseTargetResult {
+	"worklet";
+
+	const normalized = sanitizeSnapPoints(snapPoints, canDismiss);
+
+	if (normalized.length === 0) {
+		return canDismiss
+			? { target: 0, shouldDismiss: true }
+			: { target: currentProgress, shouldDismiss: false };
+	}
+
+	let minSnap = normalized[0];
+	let nextLowerSnap: number | null = null;
+
+	for (let i = 0; i < normalized.length; i++) {
+		const snap = normalized[i];
+		if (snap < minSnap) {
+			minSnap = snap;
+		}
+
+		if (
+			snap < currentProgress - EPSILON &&
+			(nextLowerSnap === null || snap > nextLowerSnap)
+		) {
+			nextLowerSnap = snap;
+		}
+	}
+
+	if (nextLowerSnap !== null) {
+		return { target: nextLowerSnap, shouldDismiss: false };
+	}
+
+	// At or below min snap → dismiss if allowed
+	if (canDismiss) {
+		return { target: 0, shouldDismiss: true };
+	}
+
+	// Can't dismiss, stay at min
+	return { target: minSnap, shouldDismiss: false };
+}

package/src/components/screen-layers/helpers/layer-component.tsx

@@ -0,0 +1,38 @@
+import { type ComponentType, type ReactNode, useMemo } from "react";
+import type { ViewProps } from "react-native";
+import Animated from "react-native-reanimated";
+import type { ScreenLayerComponentProps } from "../../../types";
+import { usesLayerRenderProps } from "./uses-layer-render-props";
+
+/** Adapts the two supported custom layer APIs without changing component identity. */
+export function LayerComponent({
+	component,
+	styles,
+	props,
+	pointerEvents,
+	children,
+	collapsable,
+}: ScreenLayerComponentProps & {
+	component?: ComponentType<any>;
+	children?: ReactNode;
+	collapsable?: ViewProps["collapsable"];
+}) {
+	const renderProps = component && usesLayerRenderProps(component);
+	const Component = useMemo<ComponentType<any>>(() => {
+		if (!component) return Animated.View;
+		return usesLayerRenderProps(component)
+			? component
+			: Animated.createAnimatedComponent(component);
+	}, [component]);
+	return (
+		<Component
+			{...(renderProps
+				? { styles, props }
+				: { style: styles, animatedProps: props })}
+			pointerEvents={pointerEvents}
+			collapsable={collapsable}
+		>
+			{children}
+		</Component>
+	);
+}

package/src/components/screen-layers/hooks/use-backdrop-pointer-events.ts

@@ -0,0 +1,51 @@
+import { useState } from "react";
+import { useAnimatedReaction } from "react-native-reanimated";
+import { scheduleOnRN } from "react-native-worklets";
+import { useBuilderStore } from "../../../providers/builder";
+import { useMotionStore } from "../../../providers/motion";
+import type { BackdropBehavior } from "../../../types/screen.types";
+
+interface BackdropPointerEventsResult {
+	pointerEvents: "box-none" | undefined;
+	backdropBehavior: BackdropBehavior;
+	isBackdropActive: boolean;
+}
+
+/**
+ * Returns pointer events and backdrop behavior based on screen options.
+ *
+ * - Runtime interpolator `backdropBehavior` takes precedence
+ * - Explicit descriptor `backdropBehavior` option is next
+ * - Otherwise defaults to 'block' (undefined = normal touch handling)
+ */
+export function useBackdropPointerEvents(): BackdropPointerEventsResult {
+	const screenOptions = useMotionStore((store) => store.options);
+	const descriptorBackdropBehavior = useBuilderStore(
+		(store) => store.options.backdropBehavior,
+	);
+	const [runtimeBackdropBehavior, setRuntimeBackdropBehavior] = useState<
+		BackdropBehavior | undefined
+	>(undefined);
+
+	useAnimatedReaction(
+		() => screenOptions.get().backdropBehavior,
+		(next, previous) => {
+			"worklet";
+			if (next !== previous) {
+				scheduleOnRN(setRuntimeBackdropBehavior, next);
+			}
+		},
+		[screenOptions],
+	);
+
+	const backdropBehavior: BackdropBehavior =
+		runtimeBackdropBehavior ?? descriptorBackdropBehavior ?? "block";
+
+	const pointerEvents =
+		backdropBehavior === "passthrough" ? "box-none" : undefined;
+
+	const isBackdropActive =
+		backdropBehavior === "dismiss" || backdropBehavior === "collapse";
+
+	return { pointerEvents, backdropBehavior, isBackdropActive };
+}

package/src/components/screen-layers/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/builder";
+import { useOptionalMotionStore } from "../../../providers/motion";
+import { LifecycleTransitionRequestKind } from "../../../providers/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-layers/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 ScreenLayersProps = {
+	children: React.ReactNode;
+	onDismissRequest?: () => void;
+};
+
+export const ScreenLayers = memo(
+	({ children, onDismissRequest }: ScreenLayersProps) => {
+		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-layers/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/builder";
+import { useMotionStore } from "../../../providers/motion";
+import {
+	useSlotProps,
+	useSlotStyles,
+} from "../../../providers/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-layers/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/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 }),
+	},
+});