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

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

@@ -1,17 +1,16 @@
 import { memo, useMemo, useRef } from "react";
 import { StyleSheet, View } from "react-native";
-import Animated, { useDerivedValue } from "react-native-reanimated";
+import Animated, {
+	type SharedValue,
+	useDerivedValue,
+} from "react-native-reanimated";
 import { snapDescriptorToIndex } from "../../../animation/snap-to";
-import { useOptionalScreenAnimationStore } from "../../../providers/screen/animation";
+import { useOptionalMotionStore } from "../../../providers/screen/motion";
+import { useOptionalOrchestratorStore } from "../../../providers/screen/orchestrator";
 import {
-	type ScreenAnimationContextValue,
-	ScreenAnimationStoreProvider,
-} from "../../../providers/screen/animation/animation.provider";
-import {
-	type ScreenSlotContextValue,
-	ScreenSlotStoreProvider,
-	useOptionalScreenSlotStore,
-} from "../../../providers/screen/styles/slot.provider";
+	OrchestratorProvider,
+	type OrchestratorState,
+} from "../../../providers/screen/orchestrator/orchestrator.provider";
 import { useBlankStackStore } from "../../../providers/stack/blank-stack.provider";
 import type { OverlayProps } from "../../../types/overlay.types";
 import type { FloatOverlayEntry } from "../helpers/get-active-overlay";
@@ -34,27 +33,26 @@ export const OverlayHost = memo(function OverlayHost({
 	previousOverlayScene,
 	layerIndex,
 }: OverlayHostProps) {
-	const overlayAnimationStore = useOptionalScreenAnimationStore(
-		scene.route.key,
-	);
-	const driverAnimationStore = useOptionalScreenAnimationStore(
+	const overlayAnimationStore = useOptionalOrchestratorStore(scene.route.key);
+	const driverAnimationStore = useOptionalOrchestratorStore(
 		driverScene.route.key,
 	);
-	const previousOverlayAnimationStore = useOptionalScreenAnimationStore(
+	const previousOverlayAnimationStore = useOptionalOrchestratorStore(
 		previousOverlayScene?.route.key ?? scene.route.key,
 	);
-	const overlaySlots = useOptionalScreenSlotStore(scene.route.key);
-	const driverSlots = useOptionalScreenSlotStore(driverScene.route.key);
+	const driverIsScreenReady = useOptionalMotionStore(
+		driverScene.route.key,
+		(store) => store.isScreenReady,
+	);
 	const overlayComponentRef = useRef(scene.descriptor.options.overlay);
 	const OverlayComponent = overlayComponentRef.current;
 	const readyResourcesRef = useRef<ReadyOverlayResources | null>(null);
 	readyResourcesRef.current = retainReadyOverlayResources(
 		readyResourcesRef.current,
 		overlayAnimationStore,
-		overlaySlots,
 		driverScene,
 		driverAnimationStore,
-		driverSlots,
+		driverIsScreenReady,
 	);
 	const readyResources = readyResourcesRef.current;
 
@@ -68,23 +66,21 @@ export const OverlayHost = memo(function OverlayHost({
 			driverScene={readyResources.driverScene}
 			layerIndex={layerIndex}
 			overlayAnimationStore={readyResources.overlayAnimationStore}
-			overlaySlots={readyResources.overlaySlots}
 			driverAnimationStore={readyResources.driverAnimationStore}
 			previousOverlayAnimationStore={
 				previousOverlayScene ? previousOverlayAnimationStore : undefined
 			}
-			driverSlots={readyResources.driverSlots}
+			driverIsScreenReady={readyResources.driverIsScreenReady}
 			OverlayComponent={OverlayComponent}
 		/>
 	);
 });
 
 type ReadyOverlayHostProps = OverlayHostProps & {
-	overlayAnimationStore: ScreenAnimationContextValue;
-	overlaySlots: ScreenSlotContextValue;
-	driverAnimationStore: ScreenAnimationContextValue;
-	previousOverlayAnimationStore?: ScreenAnimationContextValue | null;
-	driverSlots: ScreenSlotContextValue;
+	overlayAnimationStore: OrchestratorState;
+	driverAnimationStore: OrchestratorState;
+	previousOverlayAnimationStore?: OrchestratorState | null;
+	driverIsScreenReady: SharedValue<boolean>;
 	OverlayComponent: NonNullable<
 		FloatOverlayEntry["scene"]["descriptor"]["options"]["overlay"]
 	>;
@@ -95,27 +91,29 @@ function ReadyOverlayHost({
 	driverScene,
 	layerIndex,
 	overlayAnimationStore,
-	overlaySlots,
 	driverAnimationStore,
 	previousOverlayAnimationStore,
-	driverSlots,
+	driverIsScreenReady,
 	OverlayComponent,
 }: ReadyOverlayHostProps) {
 	const { scenes, focusedIndex, routeKeys, routes } = useBlankStackStore();
 	const focusedScene = scenes[focusedIndex] ?? scenes[scenes.length - 1];
 	const focusedDescriptor = focusedScene?.descriptor;
+	const ancestorIsScreenReady = useOptionalMotionStore(
+		(store) => store?.isScreenReady ?? null,
+	);
 	const { animatedProps, animatedStyle } = useOverlaySlot({
 		overlayAnimationStore,
 		overlayInterpolator: scene.descriptor.options.screenStyleInterpolator,
 		driverAnimationStore,
 		previousOverlayAnimationStore: previousOverlayAnimationStore ?? undefined,
 		driverInterpolator: driverScene.descriptor.options.screenStyleInterpolator,
-		interpolatorReady: driverSlots.interpolatorReady,
+		isScreenReady: driverIsScreenReady,
+		ancestorIsScreenReady,
 		isIncoming: scene.route.key === driverScene.route.key,
 	});
 	const relativeProgress = useDerivedValue(() => {
 		"worklet";
-		overlayAnimationStore.screenInterpolatorPropsRevision.get();
 		return overlayAnimationStore.screenInterpolatorProps.get().stackProgress;
 	});
 
@@ -156,19 +154,14 @@ function ReadyOverlayHost({
 				animatedStyle,
 			]}
 		>
-			<ScreenAnimationStoreProvider
-				registerGlobally={false}
-				value={overlayAnimationStore}
-			>
-				<ScreenSlotStoreProvider registerGlobally={false} value={overlaySlots}>
-					<View
-						pointerEvents="box-none"
-						style={[StyleSheet.absoluteFill, styles.overlay]}
-					>
-						<OverlayComponent {...overlayProps} />
-					</View>
-				</ScreenSlotStoreProvider>
-			</ScreenAnimationStoreProvider>
+			<OrchestratorProvider screenKey={scene.route.key}>
+				<View
+					pointerEvents="box-none"
+					style={[StyleSheet.absoluteFill, styles.overlay]}
+				>
+					<OverlayComponent {...overlayProps} />
+				</View>
+			</OrchestratorProvider>
 		</Animated.View>
 	);
 }

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

@@ -0,0 +1,62 @@
+import { EPSILON } from "../../../../constants";
+import { sanitizeSnapPoints } from "../../../../providers/screen/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/container/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/screen/builder";
+import { useMotionStore } from "../../../../providers/screen/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/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,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,
+	},
+});