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

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

package/src/components/screen/view.tsx

@@ -0,0 +1,74 @@
+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/configs/presets.ts

@@ -10,8 +10,6 @@ export const SlideFromTop = (
 	config: Partial<ScreenTransitionConfig> = {},
 ): ScreenTransitionConfig => {
 	return {
-		//@ts-expect-error - Should not lead to any issues
-		enableTransitions: true,
 		gestureEnabled: true,
 		gestureDirection: "vertical-inverted",
 		screenStyleInterpolator: ({
@@ -45,8 +43,6 @@ export const ZoomIn = (
 	config: Partial<ScreenTransitionConfig> = {},
 ): ScreenTransitionConfig => {
 	return {
-		//@ts-expect-error - Should not lead to any issues
-		enableTransitions: true,
 		gestureEnabled: false,
 		screenStyleInterpolator: ({ progress }) => {
 			"worklet";
@@ -86,8 +82,6 @@ export const SlideFromBottom = (
 	config: Partial<ScreenTransitionConfig> = {},
 ): ScreenTransitionConfig => {
 	return {
-		//@ts-expect-error - Should not lead to any issues
-		enableTransitions: true,
 		gestureEnabled: true,
 		gestureDirection: "vertical",
 		screenStyleInterpolator: ({
@@ -120,8 +114,6 @@ export const DraggableCard = (
 	config: Partial<ScreenTransitionConfig> = {},
 ): ScreenTransitionConfig => {
 	return {
-		//@ts-expect-error - Should not lead to any issues
-		enableTransitions: true,
 		gestureEnabled: true,
 		gestureDirection: ["horizontal", "vertical"],
 		screenStyleInterpolator: ({ current, progress, layouts: { screen } }) => {
@@ -166,8 +158,6 @@ export const ElasticCard = (
 	} = { elasticFactor: 0.5 },
 ): ScreenTransitionConfig => {
 	return {
-		//@ts-expect-error - Should not lead to any issues
-		enableTransitions: true,
 		gestureEnabled: true,
 		gestureDirection: "bidirectional",
 		screenStyleInterpolator: ({

package/src/constants.ts

@@ -178,6 +178,11 @@ export const IS_WEB = Platform.OS === "web";
 export const TRUE = 1;
 export const FALSE = 0;
 
+export const AnimationProgress = {
+	Hidden: 0,
+	Visible: 1,
+} as const;
+
 /**
  * Small value for floating-point comparisons to handle animation/interpolation imprecision
  */

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

@@ -1,16 +1,13 @@
 import { useCallback } from "react";
-import { useDescriptorsStore } from "../../providers/screen/descriptors";
+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 { AnimationStore } from "../../stores/animation.store";
-import {
-	LifecycleTransitionRequestKind,
-	SystemStore,
-} from "../../stores/system.store";
 import { dispatchCloseAction } from "../../utils/navigation/close-action-replay";
 
 export function useNavigationHelpers() {
-	const route = useDescriptorsStore((store) => store.descriptors.current.route);
-	const navigation = useDescriptorsStore(
+	const route = useBuilderStore((store) => store.descriptors.current.route);
+	const navigation = useBuilderStore(
 		(store) => store.descriptors.current.navigation,
 	);
 	const requestStackDismiss = useBlankStackStore(
@@ -48,8 +45,9 @@ export function useNavigationHelpers() {
 			if (routeIndex <= 0) return false;
 		}
 
-		if (!AnimationStore.getValue(route.key, "closing").get()) {
-			SystemStore.getBag(route.key).actions.requestLifecycleTransition(
+		const motion = getMotionStore(route.key).state;
+		if (!motion.closing.get()) {
+			motion.actions.requestLifecycleTransition(
 				LifecycleTransitionRequestKind.Close,
 				0,
 			);

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

@@ -1,7 +1,7 @@
 import type { Route } from "@react-navigation/native";
 import { useCallback, useMemo } from "react";
 import { snapDescriptorToIndex } from "../../animation/snap-to";
-import { useDescriptorsStore } from "../../providers/screen/descriptors";
+import { useBuilderStore } from "../../providers/screen/builder";
 import { useBlankStackStore } from "../../providers/stack/blank-stack.provider";
 import type { ScreenTransitionConfig } from "../../types/screen.types";
 import type { BaseStackNavigation } from "../../types/stack.types";
@@ -61,7 +61,7 @@ export function useScreenState<
 	TNavigation extends BaseStackNavigation = BaseStackNavigation,
 >(): ScreenState<TNavigation> {
 	const { routes, scenes, routeKeys, focusedIndex } = useBlankStackStore();
-	const current = useDescriptorsStore((store) => store.descriptors.current);
+	const current = useBuilderStore((store) => store.descriptors.current);
 
 	const index = useMemo(
 		() => routeKeys.indexOf(current.route.key),

package/src/index.ts

@@ -38,14 +38,27 @@ export {
 	type ScreenState,
 	useScreenState,
 } from "./hooks/navigation/use-screen-state";
+export {
+	BuilderProvider,
+	type BuilderProviderProps,
+} from "./providers/screen/builder";
 export {
 	type ScreenAnimationTarget,
 	useScreenAnimation,
-} from "./providers/screen/animation";
+} from "./providers/screen/motion/animation";
 export {
 	type ScreenGestureTarget,
 	useScreenGesture,
-} from "./providers/screen/gestures/hooks/use-screen-gesture";
+} from "./providers/screen/motion/gestures/ownership/hooks/use-screen-gesture";
+export {
+	MotionProvider,
+	type MotionProviderProps,
+	useMotionStore,
+} from "./providers/screen/motion/motion.provider";
+export {
+	OrchestratorProvider,
+	type OrchestratorProviderProps,
+} from "./providers/screen/orchestrator/orchestrator.provider";
 
 export type {
 	AnimatedViewStyle,

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

@@ -1,5 +1,5 @@
 import { createStandardNavigator } from "standard-navigation";
-import { StackView } from "../components/stack-view";
+import { BlankStackView } from "../components/screen/view";
 import type { BlankStackNavigationOptions } from "../types/blank-stack.types";
 import type {
 	BaseStackNavigation,
@@ -26,7 +26,7 @@ export const BlankStackNavigator = createStandardNavigator<
 	}
 
 	return (
-		<StackView
+		<BlankStackView
 			state={navigationState}
 			navigation={navigation}
 			descriptors={descriptors}

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

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

package/src/providers/screen/builder/hooks/use-screen-topology.ts

@@ -0,0 +1,52 @@
+import { useLayoutEffect } from "react";
+import { useOptionalBlankStackStore } from "../../../stack/blank-stack.provider";
+import { useOptionalBuilderStore } from "../builder.provider";
+import { screenTopology } from "../topology/helpers/create-screen-topology";
+
+export function useScreenTopology(screenKey: string) {
+	const parentScreenKey = useOptionalBuilderStore(
+		(store) => store?.derivations.currentScreenKey,
+	);
+
+	const transitionKey = useOptionalBlankStackStore(
+		(store) => store?.scenesByKey[screenKey]?.descriptor.options.transitionKey,
+	);
+
+	const navigatorKey = useOptionalBlankStackStore((store) =>
+		store?.scenesByKey[screenKey] ? store.navigatorKey : undefined,
+	);
+
+	const isActiveScreen = useOptionalBlankStackStore((store) => {
+		const focusedScene = store?.scenes[store.focusedIndex];
+		return (
+			focusedScene?.route.key === screenKey &&
+			focusedScene.activity === "active"
+		);
+	});
+
+	const enabled = navigatorKey !== undefined;
+
+	useLayoutEffect(() => {
+		if (!enabled) return;
+		screenTopology.register({
+			screenKey,
+			navigatorKey,
+			parentScreenKey,
+			transitionKey,
+		});
+	}, [enabled, screenKey, navigatorKey, parentScreenKey, transitionKey]);
+
+	useLayoutEffect(() => {
+		if (!enabled || !isActiveScreen || !parentScreenKey) return;
+
+		screenTopology.activate({
+			screenKey,
+			parentScreenKey,
+		});
+	}, [enabled, isActiveScreen, parentScreenKey, screenKey]);
+
+	useLayoutEffect(() => {
+		if (!enabled) return;
+		return () => screenTopology.unregister(screenKey);
+	}, [enabled, screenKey]);
+}

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

@@ -0,0 +1,9 @@
+export {
+	type BaseDescriptor,
+	BuilderProvider,
+	type BuilderProviderProps,
+	type DescriptorsContextValue,
+	getBuilderStore,
+	useBuilderStore,
+	useOptionalBuilderStore,
+} from "./builder.provider";

package/src/providers/screen/builder/topology/hooks/use-resolved-transition-key.ts

@@ -0,0 +1,29 @@
+import { useCallback, useSyncExternalStore } from "react";
+import type { ScreenTransitionTarget } from "../../../../../types/animation.types";
+import { screenTopology } from "../helpers/create-screen-topology";
+
+export const useResolvedTransitionKey = (
+	screenKey: string | null,
+	target?: ScreenTransitionTarget,
+) => {
+	const depth = typeof target === "string" ? null : (target?.depth ?? 0);
+	const requiresResolution = typeof target === "string" || depth !== 0;
+	const subscribe = useCallback(
+		(listener: () => void) =>
+			requiresResolution
+				? screenTopology.subscribeResolution(listener)
+				: () => {},
+		[requiresResolution],
+	);
+	const getSnapshot = useCallback(
+		() =>
+			typeof target === "string"
+				? screenTopology.resolveTransitionKey(target)
+				: requiresResolution && screenKey
+					? screenTopology.resolve(screenKey, depth ?? 0)
+					: screenKey,
+		[depth, requiresResolution, screenKey, target],
+	);
+
+	return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+};