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

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,15 @@
 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.current.route);
-	const navigation = useDescriptorsStore((store) => store.current.navigation);
+	const route = useBuilderStore((store) => store.descriptors.current.route);
+	const navigation = useBuilderStore(
+		(store) => store.descriptors.current.navigation,
+	);
 	const requestStackDismiss = useBlankStackStore(
 		(stack) => stack.requestDismiss,
 	);
@@ -46,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.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,
@@ -75,7 +88,6 @@ export type {
 	ScreenStyleInterpolator,
 	ScreenSurfaceComponent,
 	ScreenSurfaceComponentProps,
-	ScreenTransitionAccessor,
 	ScreenTransitionConfig,
 	ScreenTransitionDepthTarget,
 	ScreenTransitionTarget,

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/helpers/create-screen-topology.ts

@@ -0,0 +1,243 @@
+import type {
+	ActiveScreenRegistration,
+	ScreenRelationships,
+	ScreenTopology,
+	ScreenTopologyRegistration,
+} from "../types";
+
+type ScreenNode = {
+	registered: boolean;
+	navigatorKey: string | null;
+	parentScreenKey: string | null;
+	activeChildScreenKeys: string[];
+	transitionKey: string | null;
+};
+
+const EMPTY_RELATIONSHIPS: ScreenRelationships = {
+	parentScreenKey: null,
+	activeChildScreenKey: null,
+	activeChildNavigatorKey: null,
+};
+
+const areRelationshipsEqual = (
+	left: ScreenRelationships,
+	right: ScreenRelationships,
+) =>
+	left.parentScreenKey === right.parentScreenKey &&
+	left.activeChildScreenKey === right.activeChildScreenKey &&
+	left.activeChildNavigatorKey === right.activeChildNavigatorKey;
+
+export const createScreenTopology = (): ScreenTopology => {
+	const nodes = new Map<string, ScreenNode>();
+	const screenKeyByTransitionKey = new Map<string, string>();
+	const listenersByScreenKey = new Map<string, Set<() => void>>();
+	const resolutionListeners = new Set<() => void>();
+	const relationshipCache = new Map<string, ScreenRelationships>();
+
+	const getNode = (screenKey: string) => nodes.get(screenKey);
+	const ensureNode = (screenKey: string) => {
+		const existing = getNode(screenKey);
+		if (existing) return existing;
+
+		const node: ScreenNode = {
+			registered: false,
+			navigatorKey: null,
+			parentScreenKey: null,
+			activeChildScreenKeys: [],
+			transitionKey: null,
+		};
+		nodes.set(screenKey, node);
+		return node;
+	};
+
+	const removeNodeIfEmpty = (screenKey: string) => {
+		const node = getNode(screenKey);
+		if (
+			node &&
+			!node.registered &&
+			!node.parentScreenKey &&
+			node.activeChildScreenKeys.length === 0
+		) {
+			nodes.delete(screenKey);
+		}
+	};
+
+	const getParent = (screenKey: string) =>
+		getNode(screenKey)?.parentScreenKey ?? null;
+	const getActiveChild = (screenKey: string) => {
+		const children = getNode(screenKey)?.activeChildScreenKeys;
+		return children?.[children.length - 1] ?? null;
+	};
+
+	const materializeRelationships = (screenKey: string): ScreenRelationships => {
+		const parentScreenKey = getParent(screenKey);
+		const activeChildScreenKey = getActiveChild(screenKey);
+		const activeChildNavigatorKey = activeChildScreenKey
+			? (getNode(activeChildScreenKey)?.navigatorKey ?? null)
+			: null;
+
+		if (!parentScreenKey && !activeChildScreenKey) return EMPTY_RELATIONSHIPS;
+
+		return {
+			parentScreenKey,
+			activeChildScreenKey,
+			activeChildNavigatorKey,
+		};
+	};
+
+	const getRelationships = (screenKey: string) => {
+		const cached = relationshipCache.get(screenKey);
+		if (cached) return cached;
+		const relationships = materializeRelationships(screenKey);
+		relationshipCache.set(screenKey, relationships);
+		return relationships;
+	};
+
+	const mutate = (affectedScreenKeys: Set<string>, mutation: () => void) => {
+		const previousRelationships = new Map<string, ScreenRelationships>();
+		for (const screenKey of affectedScreenKeys) {
+			if (listenersByScreenKey.has(screenKey)) {
+				previousRelationships.set(screenKey, getRelationships(screenKey));
+			}
+		}
+
+		mutation();
+		for (const screenKey of affectedScreenKeys) {
+			relationshipCache.delete(screenKey);
+		}
+
+		for (const [screenKey, previous] of previousRelationships) {
+			const next = getRelationships(screenKey);
+			if (areRelationshipsEqual(previous, next)) {
+				relationshipCache.set(screenKey, previous);
+				continue;
+			}
+			for (const listener of listenersByScreenKey.get(screenKey) ?? []) {
+				listener();
+			}
+		}
+
+		for (const listener of resolutionListeners) listener();
+	};
+
+	const register = ({
+		screenKey,
+		navigatorKey,
+		parentScreenKey,
+		transitionKey,
+	}: ScreenTopologyRegistration) => {
+		const transitionKeyOwner = transitionKey
+			? screenKeyByTransitionKey.get(transitionKey)
+			: undefined;
+		if (transitionKeyOwner && transitionKeyOwner !== screenKey) {
+			throw new Error(
+				`Transition key "${transitionKey}" is already registered by screen "${transitionKeyOwner}".`,
+			);
+		}
+
+		mutate(new Set([screenKey]), () => {
+			const node = ensureNode(screenKey);
+			if (
+				node.transitionKey &&
+				node.transitionKey !== transitionKey &&
+				screenKeyByTransitionKey.get(node.transitionKey) === screenKey
+			) {
+				screenKeyByTransitionKey.delete(node.transitionKey);
+			}
+
+			node.registered = true;
+			node.navigatorKey = navigatorKey ?? null;
+			node.parentScreenKey = parentScreenKey ?? null;
+			node.transitionKey = transitionKey ?? null;
+			if (transitionKey) screenKeyByTransitionKey.set(transitionKey, screenKey);
+		});
+	};
+
+	const unregister = (screenKey: string) => {
+		const node = getNode(screenKey);
+		if (!node) return;
+		const affectedScreenKeys = new Set([screenKey]);
+		if (node.parentScreenKey) affectedScreenKeys.add(node.parentScreenKey);
+
+		mutate(affectedScreenKeys, () => {
+			if (
+				node.transitionKey &&
+				screenKeyByTransitionKey.get(node.transitionKey) === screenKey
+			) {
+				screenKeyByTransitionKey.delete(node.transitionKey);
+			}
+
+			if (node.parentScreenKey) {
+				const parent = getNode(node.parentScreenKey);
+				if (parent) {
+					parent.activeChildScreenKeys = parent.activeChildScreenKeys.filter(
+						(childScreenKey) => childScreenKey !== screenKey,
+					);
+				}
+				removeNodeIfEmpty(node.parentScreenKey);
+			}
+			nodes.delete(screenKey);
+		});
+	};
+
+	const activate = ({
+		screenKey,
+		parentScreenKey,
+	}: ActiveScreenRegistration) => {
+		if (getParent(screenKey) !== parentScreenKey) {
+			throw new Error(
+				"Screen topology can only activate a direct containment child.",
+			);
+		}
+
+		mutate(new Set([parentScreenKey]), () => {
+			const parent = ensureNode(parentScreenKey);
+			// A closing screen remains the active owner until it unmounts.
+			if (parent.activeChildScreenKeys.includes(screenKey)) return;
+			parent.activeChildScreenKeys.push(screenKey);
+		});
+	};
+
+	const resolve = (screenKey: string, depth: number) => {
+		if (!Number.isInteger(depth)) return null;
+
+		let resolvedScreenKey: string | null = screenKey;
+		for (let step = 0; step < Math.abs(depth); step += 1) {
+			resolvedScreenKey =
+				depth < 0
+					? getParent(resolvedScreenKey)
+					: getActiveChild(resolvedScreenKey);
+			if (!resolvedScreenKey) return null;
+		}
+
+		return getNode(resolvedScreenKey)?.registered ? resolvedScreenKey : null;
+	};
+
+	return {
+		register,
+		unregister,
+		activate,
+		getRelationships,
+		resolve,
+		resolveTransitionKey: (key) => {
+			const screenKey = screenKeyByTransitionKey.get(key) ?? key;
+			return getNode(screenKey)?.registered ? screenKey : null;
+		},
+		subscribe: (screenKey, listener) => {
+			const listeners =
+				listenersByScreenKey.get(screenKey) ?? new Set<() => void>();
+			listeners.add(listener);
+			listenersByScreenKey.set(screenKey, listeners);
+			return () => {
+				listeners.delete(listener);
+				if (listeners.size === 0) listenersByScreenKey.delete(screenKey);
+			};
+		},
+		subscribeResolution: (listener) => {
+			resolutionListeners.add(listener);
+			return () => resolutionListeners.delete(listener);
+		},
+	};
+};
+
+export const screenTopology = createScreenTopology();

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

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

@@ -0,0 +1,21 @@
+import { useCallback, useSyncExternalStore } from "react";
+import { useBuilderStore } from "../..";
+import { screenTopology } from "../helpers/create-screen-topology";
+
+export const useScreenRelationships = (routeKey?: string) => {
+	const currentScreenKey = useBuilderStore(
+		(store) => store.derivations.currentScreenKey,
+	);
+	const screenKey = routeKey ?? currentScreenKey;
+
+	const subscribe = useCallback(
+		(listener: () => void) => screenTopology.subscribe(screenKey, listener),
+		[screenKey],
+	);
+	const getSnapshot = useCallback(
+		() => screenTopology.getRelationships(screenKey),
+		[screenKey],
+	);
+
+	return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+};