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

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

@@ -1,90 +0,0 @@
-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

@@ -1,28 +0,0 @@
-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

@@ -1,29 +0,0 @@
-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

@@ -1,112 +0,0 @@
-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

@@ -1,67 +0,0 @@
-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

@@ -1,36 +0,0 @@
-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

@@ -1,52 +0,0 @@
-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>
-	);
-});

package/src/components/screen/view.tsx

@@ -1,74 +0,0 @@
-import { memo } from "react";
-import { StyleSheet } from "react-native";
-import { GestureHandlerRootView } from "react-native-gesture-handler";
-import { SafeAreaProvider } from "react-native-safe-area-context";
-import {
-	BlankStackProvider,
-	useBlankStackStore,
-} from "../../providers/stack/blank-stack.provider";
-import type { BlankStackProviderProps } from "../../types/providers/blank-stack-provider.types";
-import { ActivityContainer, ActivityScreen } from "../activity";
-import { PortalProvider } from "../boundary/portal";
-import { Overlay } from "../overlay";
-import { BlankStackLifecycle } from "./lifecycle/blank-stack";
-import { Screen } from "./screen";
-
-interface RouteKeyProps {
-	routeKey: string;
-}
-
-// Keep the render subscription inside the activity boundary so it can be paused.
-const BlankSceneContent = memo(function BlankSceneContent({
-	routeKey,
-}: RouteKeyProps) {
-	const render = useBlankStackStore(
-		(store) => store?.scenesByKey[routeKey]?.descriptor.render,
-	);
-	return render?.();
-});
-
-const BlankSceneRow = memo(function BlankSceneRow({ routeKey }: RouteKeyProps) {
-	return (
-		<ActivityScreen routeKey={routeKey}>
-			<Screen routeKey={routeKey} lifecycle={BlankStackLifecycle}>
-				<BlankSceneContent routeKey={routeKey} />
-			</Screen>
-		</ActivityScreen>
-	);
-});
-
-const StackViewContent = memo(function StackViewContent() {
-	const routeKeys = useBlankStackStore((store) => store?.routeKeys);
-	return (
-		<PortalProvider>
-			<Overlay.Float />
-			<ActivityContainer>
-				{routeKeys.map((routeKey) => (
-					<BlankSceneRow key={routeKey} routeKey={routeKey} />
-				))}
-			</ActivityContainer>
-		</PortalProvider>
-	);
-});
-
-export const BlankStackView = memo(function BlankStackView({
-	state,
-	navigation,
-	descriptors,
-}: BlankStackProviderProps) {
-	return (
-		<GestureHandlerRootView style={styles.container}>
-			<SafeAreaProvider>
-				<BlankStackProvider
-					state={state}
-					navigation={navigation}
-					descriptors={descriptors}
-				>
-					<StackViewContent />
-				</BlankStackProvider>
-			</SafeAreaProvider>
-		</GestureHandlerRootView>
-	);
-});
-
-const styles = StyleSheet.create({ container: { flex: 1 } });

package/src/hooks/navigation/use-navigation-helpers.ts

@@ -1,59 +0,0 @@
-import { useCallback } from "react";
-import { useBuilderStore } from "../../providers/screen/builder";
-import { getMotionStore } from "../../providers/screen/motion";
-import { LifecycleTransitionRequestKind } from "../../providers/screen/motion/hooks/use-transition-values";
-import { useBlankStackStore } from "../../providers/stack/blank-stack.provider";
-import { dispatchCloseAction } from "../../utils/navigation/close-action-replay";
-
-export function useNavigationHelpers() {
-	const route = useBuilderStore((store) => store.descriptors.current.route);
-	const navigation = useBuilderStore(
-		(store) => store.descriptors.current.navigation,
-	);
-	const requestStackDismiss = useBlankStackStore(
-		(stack) => stack.requestDismiss,
-	);
-
-	const dismissScreen = useCallback((): boolean => {
-		const state = navigation.getState();
-		const routeIndex = state.routes.findIndex(
-			(stateRoute) => stateRoute.key === route.key,
-		);
-		const routeStillPresent = routeIndex !== -1;
-		if (!routeStillPresent || routeIndex === 0) return false;
-
-		const action = {
-			type: "POP",
-			payload: { count: 1 },
-			source: route.key,
-			target: state.key,
-		};
-		dispatchCloseAction(action, (closeAction) => {
-			navigation.dispatch(closeAction);
-		});
-		return true;
-	}, [navigation, route.key]);
-
-	const requestDismiss = useCallback((): boolean => {
-		if (requestStackDismiss) {
-			if (!requestStackDismiss({ route })) return false;
-		} else {
-			const state = navigation.getState();
-			const routeIndex = state.routes.findIndex(
-				(stateRoute) => stateRoute.key === route.key,
-			);
-			if (routeIndex <= 0) return false;
-		}
-
-		const motion = getMotionStore(route.key).state;
-		if (!motion.closing.get()) {
-			motion.actions.requestLifecycleTransition(
-				LifecycleTransitionRequestKind.Close,
-				0,
-			);
-		}
-		return true;
-	}, [navigation, route, requestStackDismiss]);
-
-	return { dismissScreen, requestDismiss };
-}

package/src/navigators/create-blank-stack-navigator.tsx

@@ -1,35 +0,0 @@
-import { createStandardNavigator } from "standard-navigation";
-import { BlankStackView } from "../components/screen/view";
-import type { BlankStackNavigationOptions } from "../types/blank-stack.types";
-import type {
-	BaseStackNavigation,
-	BaseStackRoute,
-	BaseStackState,
-} from "../types/stack.types";
-
-export type BlankStackStandardEventMap = {};
-
-export type BlankStackStandardNavigatorProps = {
-	navigationState?: BaseStackState<BaseStackRoute>;
-	navigation?: BaseStackNavigation;
-};
-
-export const BlankStackNavigator = createStandardNavigator<
-	BlankStackNavigationOptions,
-	BlankStackStandardEventMap,
-	BlankStackStandardNavigatorProps
->(({ descriptors, navigation, navigationState }) => {
-	if (!navigationState || !navigation) {
-		throw new Error(
-			"BlankStack requires navigation state and helpers from its integration.",
-		);
-	}
-
-	return (
-		<BlankStackView
-			state={navigationState}
-			navigation={navigation}
-			descriptors={descriptors}
-		/>
-	);
-});

package/src/providers/screen/builder/builder.provider.tsx

@@ -1,86 +0,0 @@
-import type { ReactNode } from "react";
-import { useMemo } from "react";
-import type { BaseStackDescriptor } from "../../../types/stack.types";
-import createProvider from "../../../utils/create-provider";
-import type { DescriptorDerivations } from "./helpers/derive-descriptor-derivations";
-import { deriveDescriptorDerivations } from "./helpers/derive-descriptor-derivations";
-
-import { useScreenTopology } from "./hooks/use-screen-topology";
-
-export type BaseDescriptor = BaseStackDescriptor;
-
-export interface DescriptorsContextValue {
-	previous?: BaseDescriptor;
-	current: BaseDescriptor;
-	next?: BaseDescriptor;
-}
-
-export type DescriptorDerivationsContextValue = DescriptorDerivations;
-
-interface BuilderStoreValue {
-	descriptors: DescriptorsContextValue;
-	derivations: DescriptorDerivationsContextValue;
-	options: BaseDescriptor["options"];
-}
-
-export type BuilderProviderProps = {
-	children: ReactNode;
-	routeKey: string;
-	descriptors: DescriptorsContextValue;
-};
-
-const createBuilderProvider = createProvider("Builder", {
-	global: true,
-})<BuilderProviderProps, BuilderStoreValue>;
-
-const {
-	StoreProvider: BuilderStoreProvider,
-	getBuilderStore,
-	BuilderProvider,
-	useBuilderStore,
-	useOptionalBuilderStore,
-}: ReturnType<typeof createBuilderProvider> = createBuilderProvider(
-	({ routeKey, children, descriptors: inputDescriptors }) => {
-		const currentDescriptor = inputDescriptors.current;
-		const previousDescriptor = inputDescriptors.previous;
-		const nextDescriptor = inputDescriptors.next;
-		const options = currentDescriptor.options;
-
-		const descriptors = useMemo(() => {
-			return {
-				previous: previousDescriptor,
-				current: currentDescriptor,
-				next: nextDescriptor,
-			};
-		}, [previousDescriptor, currentDescriptor, nextDescriptor]);
-
-		const derivations = useMemo(() => {
-			return deriveDescriptorDerivations({
-				previous: previousDescriptor,
-				current: currentDescriptor,
-				next: nextDescriptor,
-			});
-		}, [previousDescriptor, currentDescriptor, nextDescriptor]);
-
-		useScreenTopology(routeKey);
-
-		const value = useMemo(
-			() => ({ descriptors, derivations, options }),
-			[descriptors, derivations, options],
-		);
-
-		return {
-			key: routeKey,
-			value,
-			children,
-		};
-	},
-);
-
-export {
-	BuilderProvider,
-	BuilderStoreProvider,
-	getBuilderStore,
-	useBuilderStore,
-	useOptionalBuilderStore,
-};