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

package/src/components/screen-layers/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/builder";
+import { useMotionStore } from "../../../providers/motion";
+import {
+	useSlotProps,
+	useSlotStyles,
+} from "../../../providers/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-layers/layers/surface.tsx

@@ -0,0 +1,50 @@
+import { memo } from "react";
+import { StyleSheet } from "react-native";
+import { useBuilderStore } from "../../../providers/builder";
+import {
+	useSlotProps,
+	useSlotStyles,
+} from "../../../providers/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/controls/helpers/resolve-snap-target.ts

@@ -0,0 +1,53 @@
+import { type HistoryEntry, HistoryStore } from "../../stores/history.store";
+
+const hasSnapPoints = (entry: HistoryEntry): boolean => {
+	const snapPoints = entry.descriptor.options?.snapPoints;
+	return Boolean(snapPoints && snapPoints.length > 0);
+};
+
+const getNavigatorLineage = (entry: HistoryEntry): string[] => {
+	const keys: string[] = [];
+	const visited = new Set<string>();
+
+	let nav: any = entry.descriptor.navigation;
+	while (nav) {
+		const key = nav.getState?.()?.key;
+		if (typeof key === "string" && key.length > 0 && !visited.has(key)) {
+			keys.push(key);
+			visited.add(key);
+		}
+
+		if (typeof nav.getParent !== "function") {
+			break;
+		}
+
+		nav = nav.getParent();
+	}
+
+	if (!visited.has(entry.navigatorKey)) {
+		keys.push(entry.navigatorKey);
+	}
+
+	return keys;
+};
+
+export function resolveSnapTargetEntry(): HistoryEntry | undefined {
+	const anchor = HistoryStore.getMostRecent();
+	if (!anchor) return undefined;
+
+	const lineageKeys = getNavigatorLineage(anchor);
+
+	for (const navigatorKey of lineageKeys) {
+		const match = HistoryStore.getByNavigator(navigatorKey).find(hasSnapPoints);
+		if (match) return match;
+	}
+
+	const all = HistoryStore.toArray();
+	for (let i = all.length - 1; i >= 0; i--) {
+		if (hasSnapPoints(all[i])) {
+			return all[i];
+		}
+	}
+
+	return undefined;
+}

package/src/controls/snap-to.ts

@@ -0,0 +1,96 @@
+import { scheduleOnUI } from "react-native-worklets";
+import { getMotionStore } from "../providers/motion";
+import type { HistoryEntry } from "../stores/history.store";
+import { animateToProgress } from "../utils/animation/animate-to-progress";
+import { resolveSnapTransitionSpec } from "../utils/animation/resolve-snap-transition-spec";
+import { logger } from "../utils/logger";
+import { resolveSnapTargetEntry } from "./helpers/resolve-snap-target";
+
+const getSortedSnapPoints = (
+	descriptor: HistoryEntry["descriptor"],
+): number[] | null => {
+	const snapPoints = descriptor.options?.snapPoints;
+	if (!snapPoints || snapPoints.length === 0) return null;
+
+	// Resolve 'auto' to the measured fraction owned by Motion
+	const autoVal = getMotionStore(
+		descriptor.route.key,
+	).state.resolvedAutoSnapPoint.get();
+
+	const resolved = snapPoints
+		.map((p) => (typeof p === "string" ? autoVal : p))
+		.filter((p): p is number => typeof p === "number" && p > 0);
+
+	return resolved.length > 0 ? resolved.sort((a, b) => a - b) : null;
+};
+
+export function snapDescriptorToIndex(
+	descriptor: HistoryEntry["descriptor"],
+	index: number,
+): boolean {
+	const sorted = getSortedSnapPoints(descriptor);
+	if (!sorted) {
+		logger.warn("snapTo: target screen has no snapPoints");
+		return false;
+	}
+
+	if (index < 0 || index >= sorted.length) {
+		logger.warn(
+			`snapTo: index ${index} out of bounds (0-${sorted.length - 1})`,
+		);
+		return false;
+	}
+
+	const targetProgress = sorted[index];
+	const animations = getMotionStore(descriptor.route.key).state;
+	const {
+		targetProgress: targetProgressValue,
+		animationProgress: animationProgressValue,
+	} = animations;
+
+	scheduleOnUI(() => {
+		"worklet";
+		const currentProgress = animations.transitionProgress.get();
+
+		animateToProgress({
+			target: targetProgress,
+			markEntering: false,
+			animations,
+			targetProgress: targetProgressValue,
+			animationProgress: animationProgressValue,
+			spec: resolveSnapTransitionSpec(
+				descriptor.options.transitionSpec,
+				targetProgress < currentProgress ? "collapse" : "expand",
+			),
+		});
+	});
+
+	return true;
+}
+
+/**
+ * Programmatically snap the currently focused screen to a specific snap point.
+ *
+ * @param index - The index of the snap point to snap to (0-based, sorted ascending)
+ *
+ * @example
+ * ```tsx
+ * import { snapTo } from 'react-native-screen-transitions';
+ *
+ * // Snap to the first (smallest) snap point
+ * snapTo(0);
+ *
+ * // Snap to the last (largest) snap point
+ * snapTo(2); // if there are 3 snap points
+ * ```
+ */
+export function snapTo(index: number): void {
+	const screenWithSnapPoints = resolveSnapTargetEntry();
+
+	if (!screenWithSnapPoints) {
+		logger.warn("snapTo: No screens with snapPoints in history");
+		return;
+	}
+
+	snapDescriptorToIndex(screenWithSnapPoints.descriptor, index);
+}

package/src/controls/transition-blocking.ts

@@ -0,0 +1,79 @@
+import { getMotionStore } from "../providers/motion";
+import { HistoryStore } from "../stores/history.store";
+import type { ScreenKey } from "../types/screen.types";
+import { logger } from "../utils/logger";
+
+const resolveTransitionRouteKey = (
+	routeKey: ScreenKey | undefined,
+	actionName: "blockTransition" | "unblockTransition",
+): ScreenKey | undefined => {
+	if (routeKey !== undefined) {
+		if (routeKey.length === 0) {
+			logger.warn(`${actionName}: routeKey must not be empty`);
+			return undefined;
+		}
+
+		return routeKey;
+	}
+
+	const entry = HistoryStore.getMostRecent();
+	if (!entry) {
+		logger.warn(`${actionName}: No screens in history`);
+		return undefined;
+	}
+
+	return entry.descriptor.route.key;
+};
+
+/**
+ * Prevents a screen's pending lifecycle transition from starting.
+ *
+ * Calls are reference-counted. Every call must be paired with one
+ * {@linkcode unblockTransition} call for the same route. When `routeKey` is
+ * omitted, the most recently focused screen in navigation history is used.
+ *
+ * @param routeKey - Route key of the screen to block.
+ *
+ * @example
+ * ```tsx
+ * blockTransition(route.key);
+ * // Render or prepare the destination screen.
+ * unblockTransition(route.key);
+ * ```
+ *
+ * @see {@linkcode unblockTransition}
+ */
+export function blockTransition(routeKey?: ScreenKey): void {
+	const resolvedRouteKey = resolveTransitionRouteKey(
+		routeKey,
+		"blockTransition",
+	);
+	if (!resolvedRouteKey) {
+		return;
+	}
+
+	getMotionStore(resolvedRouteKey).state.actions.blockLifecycleStart();
+}
+
+/**
+ * Releases one lifecycle transition block for a screen.
+ *
+ * The pending transition can start when the screen's final block is released.
+ * Extra calls are safe and leave the block count at zero. When `routeKey` is
+ * omitted, the most recently focused screen in navigation history is used.
+ *
+ * @param routeKey - Route key of the screen to unblock.
+ *
+ * @see {@linkcode blockTransition}
+ */
+export function unblockTransition(routeKey?: ScreenKey): void {
+	const resolvedRouteKey = resolveTransitionRouteKey(
+		routeKey,
+		"unblockTransition",
+	);
+	if (!resolvedRouteKey) {
+		return;
+	}
+
+	getMotionStore(resolvedRouteKey).state.actions.unblockLifecycleStart();
+}

package/src/hooks/navigation/use-screen-state.ts

@@ -1,8 +1,8 @@
 import type { Route } from "@react-navigation/native";
 import { useCallback, useMemo } from "react";
-import { snapDescriptorToIndex } from "../../animation/snap-to";
-import { useBuilderStore } from "../../providers/screen/builder";
-import { useBlankStackStore } from "../../providers/stack/blank-stack.provider";
+import { snapDescriptorToIndex } from "../../controls/snap-to";
+import { useBlankStackStore } from "../../navigators/blank-stack/state/blank-stack.provider";
+import { useBuilderStore } from "../../providers/builder";
 import type { ScreenTransitionConfig } from "../../types/screen.types";
 import type { BaseStackNavigation } from "../../types/stack.types";
 

package/src/index.ts

@@ -23,43 +23,49 @@ export default {
 
 export type { NativeStackAdapterOptions } from "./adapters/with-screen-transitions";
 export { withScreenTransitions } from "./adapters/with-screen-transitions";
-export { snapTo } from "./animation/snap-to";
-export {
-	blockTransition,
-	unblockTransition,
-} from "./animation/transition-blocking";
 export {
 	NAVIGATION_MASK_CONTAINER_STYLE_ID,
 	NAVIGATION_MASK_ELEMENT_STYLE_ID,
 	TRANSFORM_RESET,
 } from "./constants";
+export { snapTo } from "./controls/snap-to";
+export {
+	blockTransition,
+	unblockTransition,
+} from "./controls/transition-blocking";
 export { useHistory } from "./hooks/navigation/use-history";
 export {
 	type ScreenState,
 	useScreenState,
 } from "./hooks/navigation/use-screen-state";
+export { BlankStackView } from "./navigators/blank-stack/components/stack-view";
+export {
+	BlankStackProvider,
+	type BlankStackProviderProps,
+	type BlankStackStoreValue,
+	useBlankStackStore,
+} from "./navigators/blank-stack/state/blank-stack.provider";
 export {
 	BuilderProvider,
 	type BuilderProviderProps,
-} from "./providers/screen/builder";
+} from "./providers/builder";
 export {
 	type ScreenAnimationTarget,
 	useScreenAnimation,
-} from "./providers/screen/motion/animation";
+} from "./providers/motion/animation";
 export {
 	type ScreenGestureTarget,
 	useScreenGesture,
-} from "./providers/screen/motion/gestures/ownership/hooks/use-screen-gesture";
+} from "./providers/motion/gestures/ownership/hooks/use-screen-gesture";
 export {
 	MotionProvider,
 	type MotionProviderProps,
 	useMotionStore,
-} from "./providers/screen/motion/motion.provider";
+} from "./providers/motion/motion.provider";
 export {
 	OrchestratorProvider,
 	type OrchestratorProviderProps,
-} from "./providers/screen/orchestrator/orchestrator.provider";
-
+} from "./providers/orchestrator/orchestrator.provider";
 export type {
 	AnimatedViewStyle,
 	AnimationConfig,
@@ -102,3 +108,4 @@ export type {
 	TransitionSlotStyle,
 	TransitionSpec,
 } from "./types";
+export type { SnapPoint } from "./types/screen.types";

package/src/navigators/blank-stack/components/activity/activity-screen.tsx

@@ -0,0 +1,107 @@
+import type * as React from "react";
+import { memo } from "react";
+import { StyleSheet, View, type ViewProps } from "react-native";
+import { useDerivedValue } from "react-native-reanimated";
+import {
+	ActivityView,
+	type ActivityViewMode,
+} from "../../../../components/activity/activity-view";
+import { IS_WEB } from "../../../../constants";
+import { useSharedValueState } from "../../../../hooks/reanimated/use-shared-value-state";
+import { useOptionalMotionStore } from "../../../../providers/motion";
+import type { InactiveBehavior } from "../../../../types/screen.types";
+import type { StackSceneActivity } from "../../../../types/stack.types";
+import { useBlankStackStore } from "../../state/blank-stack.provider";
+
+const DEFAULT_INACTIVE_BEHAVIOR: InactiveBehavior = IS_WEB ? "unmount" : "hide";
+
+// Let the content and backdrop layers decide whether to capture touches.
+const PointerEventsByActivity = {
+	active: "box-none",
+	inert: "box-none",
+	inactive: "none",
+	closing: "none",
+} satisfies Record<StackSceneActivity, ViewProps["pointerEvents"]>;
+
+interface ActivityScreenProps {
+	children: React.ReactNode;
+	routeKey: string;
+}
+
+export const ActivityScreen = memo(function ActivityScreen({
+	children,
+	routeKey,
+}: ActivityScreenProps) {
+	const scene = useBlankStackStore((store) => store.scenesByKey[routeKey]);
+	const paintDriverRouteKey = useBlankStackStore((store) =>
+		store.paintDriverRouteKeyByRouteKey.get(routeKey),
+	);
+
+	const inactiveBehavior =
+		(scene.descriptor.options as { inactiveBehavior?: InactiveBehavior })
+			.inactiveBehavior ?? DEFAULT_INACTIVE_BEHAVIOR;
+
+	const hasNestedState = "state" in scene.route;
+
+	const paintDriverProgress = useOptionalMotionStore(
+		paintDriverRouteKey ?? null,
+		(store) => store.state.transitionProgress,
+	);
+
+	/**
+	 * Avoid hiding inactive content until the screen that exposes it has settled.
+	 *
+	 * For A(inactive), B(inert), C(active), A's paint depends on C finishing its
+	 * transition. Watching B can still leave a brief blank frame, so we wait for
+	 * C's progress to reach its settled value of 1 before hiding A.
+	 */
+	const isPaintDriverSettled = useDerivedValue(() => {
+		"worklet";
+
+		if (!paintDriverProgress) {
+			return false;
+		}
+
+		return paintDriverProgress.get() >= 1;
+	});
+
+	const isPaintDriverSettledOnJS = useSharedValueState(isPaintDriverSettled);
+
+	let activityViewMode: ActivityViewMode =
+		scene.activity === "active" ? "normal" : "inert";
+	let visible = scene.activity !== "inactive";
+
+	if (scene.activity === "inactive") {
+		if (inactiveBehavior === "keep" || !isPaintDriverSettledOnJS) {
+			visible = true;
+		} else if (inactiveBehavior === "pause") {
+			activityViewMode = "paused";
+			visible = true;
+		} else {
+			activityViewMode = "paused";
+			visible = false;
+		}
+	}
+
+	const shouldUnmount =
+		inactiveBehavior === "unmount" &&
+		scene.activity === "inactive" &&
+		!hasNestedState &&
+		isPaintDriverSettledOnJS;
+
+	if (shouldUnmount) {
+		return null;
+	}
+
+	return (
+		<View
+			style={StyleSheet.absoluteFill}
+			pointerEvents={PointerEventsByActivity[scene.activity]}
+			collapsable={false}
+		>
+			<ActivityView mode={activityViewMode} visible={visible}>
+				{children}
+			</ActivityView>
+		</View>
+	);
+});

package/src/navigators/blank-stack/components/activity/index.tsx

@@ -0,0 +1,2 @@
+export { ActivityContainer } from "./activity-container";
+export { ActivityScreen } from "./activity-screen";

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

@@ -0,0 +1,18 @@
+import { useBuilderStore } from "../../../../providers/builder";
+import { useBlankStackStore } from "../../state/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/navigators/blank-stack/components/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/navigators/blank-stack/components/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/builder";
+import type { MotionAnimationValues } from "../../../../../../providers/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/navigators/blank-stack/components/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);
+			}
+		},
+	);
+};