react-native-screen-transitions 3.1.0 → 3.2.0-beta.0

package/src/component-stack/controllers/component-stack-lifecycle.tsx

@@ -0,0 +1,80 @@
+import { useLayoutEffect } from "react";
+import { runOnJS, useAnimatedReaction } from "react-native-reanimated";
+import { useHighRefreshRate } from "../../shared/hooks/animation/use-high-refresh-rate";
+import useStableCallback from "../../shared/hooks/use-stable-callback";
+import { useKeys } from "../../shared/providers/screen/keys.provider";
+import { useManagedStackContext } from "../../shared/providers/stack/managed.provider";
+import { AnimationStore } from "../../shared/stores/animation.store";
+import { startScreenTransition } from "../../shared/utils/animation/start-screen-transition";
+import { resetStoresForScreen } from "../../shared/utils/reset-stores-for-screen";
+import type { ComponentStackDescriptor } from "../types";
+
+interface Props {
+	children: React.ReactNode;
+}
+
+/**
+ * Lifecycle controller built out for Component Stack implementation.
+ * Uses the shared ManagedStackContext for closing route handling.
+ */
+export const ComponentStackScreenLifecycleController = ({
+	children,
+}: Props) => {
+	const { current } = useKeys<ComponentStackDescriptor>();
+	const { handleCloseRoute, closingRouteKeysShared } = useManagedStackContext();
+
+	const animations = AnimationStore.getAll(current.route.key);
+
+	const { deactivateHighRefreshRate, activateHighRefreshRate } =
+		useHighRefreshRate(current);
+
+	const handleInitialize = useStableCallback(() => {
+		activateHighRefreshRate();
+		startScreenTransition({
+			target: "open",
+			spec: current.options.transitionSpec,
+			animations,
+			onAnimationFinish: deactivateHighRefreshRate,
+		});
+	});
+
+	const handleCleanup = useStableCallback(() => {
+		resetStoresForScreen(current);
+	});
+
+	const handleCloseEnd = useStableCallback((finished: boolean) => {
+		deactivateHighRefreshRate();
+		if (!finished) {
+			return;
+		}
+		handleCloseRoute({ route: current.route });
+	});
+
+	useAnimatedReaction(
+		() => ({
+			keys: closingRouteKeysShared.value,
+		}),
+		({ keys }) => {
+			if (!keys.includes(current.route.key)) {
+				return;
+			}
+
+			runOnJS(activateHighRefreshRate)();
+			startScreenTransition({
+				target: "close",
+				spec: current.options.transitionSpec,
+				animations,
+				onAnimationFinish: handleCloseEnd,
+			});
+		},
+	);
+
+	useLayoutEffect(() => {
+		handleInitialize();
+		return () => {
+			handleCleanup();
+		};
+	}, [handleInitialize, handleCleanup]);
+
+	return children;
+};

package/src/component-stack/hooks/use-component-navigation-builder.tsx

@@ -0,0 +1,388 @@
+import * as React from "react";
+import { useCallback, useMemo, useReducer, useRef } from "react";
+import type {
+	ComponentNavigation,
+	ComponentRoute,
+	ComponentScreenConfig,
+	ComponentScreenProps,
+	ComponentStackDescriptor,
+	ComponentStackDescriptorMap,
+	ComponentStackNavigationOptions,
+	ComponentStackState,
+} from "../types";
+
+// Generate unique keys for routes
+let keyCounter = 0;
+const generateKey = () => `component-route-${++keyCounter}`;
+
+// Generate unique key for stack instance
+const generateStackKey = () => `component-stack-${Date.now()}`;
+
+type NavigationAction =
+	| { type: "PUSH"; name: string; params?: Record<string, unknown> }
+	| { type: "POP" }
+	| { type: "POP_BY_KEY"; key: string }
+	| { type: "NAVIGATE"; name: string; params?: Record<string, unknown> }
+	| { type: "RESET"; name?: string; params?: Record<string, unknown> };
+
+interface ScreenRegistry {
+	[name: string]: ComponentScreenConfig;
+}
+
+function createRoute(
+	name: string,
+	params?: Record<string, unknown>,
+): ComponentRoute {
+	return {
+		key: generateKey(),
+		name,
+		params,
+	};
+}
+
+function navigationReducer(
+	state: ComponentStackState,
+	action: NavigationAction & {
+		screens: ScreenRegistry;
+		initialRouteName: string;
+	},
+): ComponentStackState {
+	switch (action.type) {
+		case "PUSH": {
+			if (!action.screens[action.name]) {
+				console.warn(
+					`[ComponentStack] Screen "${action.name}" not found in navigator`,
+				);
+				return state;
+			}
+			const newRoute = createRoute(action.name, action.params);
+			return {
+				...state,
+				routes: [...state.routes, newRoute],
+				index: state.routes.length,
+			};
+		}
+
+		case "POP": {
+			if (state.routes.length <= 1) {
+				return state;
+			}
+			return {
+				...state,
+				routes: state.routes.slice(0, -1),
+				index: state.index - 1,
+			};
+		}
+
+		case "POP_BY_KEY": {
+			const routeIndex = state.routes.findIndex(
+				(route) => route.key === action.key,
+			);
+			if (routeIndex === -1) {
+				// Route not found, nothing to do
+				return state;
+			}
+			if (state.routes.length <= 1) {
+				// Can't pop the last route
+				return state;
+			}
+			const nextRoutes = state.routes.filter(
+				(route) => route.key !== action.key,
+			);
+			return {
+				...state,
+				routes: nextRoutes,
+				index: Math.min(state.index, nextRoutes.length - 1),
+			};
+		}
+
+		case "NAVIGATE": {
+			if (!action.screens[action.name]) {
+				console.warn(
+					`[ComponentStack] Screen "${action.name}" not found in navigator`,
+				);
+				return state;
+			}
+			// Check if screen already exists in stack
+			const existingIndex = state.routes.findIndex(
+				(route) => route.name === action.name,
+			);
+			if (existingIndex !== -1) {
+				// Navigate to existing screen (pop to it)
+				return {
+					...state,
+					routes: state.routes.slice(0, existingIndex + 1),
+					index: existingIndex,
+				};
+			}
+			// Push new screen
+			const newRoute = createRoute(action.name, action.params);
+			return {
+				...state,
+				routes: [...state.routes, newRoute],
+				index: state.routes.length,
+			};
+		}
+
+		case "RESET": {
+			const targetName = action.name || action.initialRouteName;
+			if (!action.screens[targetName]) {
+				console.warn(
+					`[ComponentStack] Screen "${targetName}" not found in navigator`,
+				);
+				return state;
+			}
+			const newRoute = createRoute(targetName, action.params);
+			return {
+				...state,
+				routes: [newRoute],
+				index: 0,
+			};
+		}
+
+		default:
+			return state;
+	}
+}
+
+interface UseComponentNavigationBuilderOptions {
+	children: React.ReactNode;
+	initialRouteName?: string;
+	screenOptions?: ComponentStackNavigationOptions;
+}
+
+interface ComponentNavigationBuilderResult {
+	state: ComponentStackState;
+	navigation: ComponentNavigation;
+	describe: (
+		route: ComponentRoute,
+		placeholder: boolean,
+	) => ComponentStackDescriptor;
+	descriptors: ComponentStackDescriptorMap;
+	NavigationContent: React.FC<{ children: React.ReactNode }>;
+}
+
+/**
+ * Parse children to extract screen configurations.
+ * Expects children to be ComponentScreen elements.
+ */
+function parseScreens(children: React.ReactNode): ScreenRegistry {
+	const screens: ScreenRegistry = {};
+
+	React.Children.forEach(children, (child) => {
+		if (!React.isValidElement(child)) {
+			return;
+		}
+
+		const props = child.props as ComponentScreenProps;
+		if (props.name && props.component) {
+			screens[props.name] = {
+				name: props.name,
+				component: props.component,
+				options: props.options,
+			};
+		}
+	});
+
+	return screens;
+}
+
+export function useComponentNavigationBuilder({
+	children,
+	initialRouteName,
+	screenOptions,
+}: UseComponentNavigationBuilderOptions): ComponentNavigationBuilderResult {
+	// Parse screen configs from children
+	const screens = useMemo(() => parseScreens(children), [children]);
+
+	// Determine initial route
+	const screenNames = Object.keys(screens);
+	const initialRoute = initialRouteName || screenNames[0];
+
+	if (!initialRoute) {
+		throw new Error(
+			"[ComponentStack] No screens defined. Add at least one ComponentStack.Screen child.",
+		);
+	}
+
+	// Stable stack key
+	const stackKeyRef = useRef(generateStackKey());
+
+	// Navigation state reducer
+	const [state, internalDispatch] = useReducer(
+		(state: ComponentStackState, action: NavigationAction) =>
+			navigationReducer(state, {
+				...action,
+				screens,
+				initialRouteName: initialRoute,
+			}),
+		{
+			routes: [createRoute(initialRoute)],
+			index: 0,
+			key: stackKeyRef.current,
+		},
+	);
+
+	// Dispatch method that handles both internal actions and StackActions format
+	const dispatch = useCallback(
+		(
+			action:
+				| NavigationAction
+				| { type: string; source?: string; target?: string; payload?: unknown },
+		) => {
+			// Handle StackActions.pop() format from useLocalRoutes: { type: 'POP', source: routeKey }
+			if (
+				action.type === "POP" &&
+				"source" in action &&
+				typeof action.source === "string"
+			) {
+				internalDispatch({ type: "POP_BY_KEY", key: action.source });
+				return;
+			}
+
+			// Handle standard internal actions
+			switch (action.type) {
+				case "PUSH":
+					if ("name" in action && typeof action.name === "string") {
+						internalDispatch({
+							type: "PUSH",
+							name: action.name,
+							params: action.params as Record<string, unknown> | undefined,
+						});
+					}
+					break;
+				case "POP":
+					internalDispatch({ type: "POP" });
+					break;
+				case "NAVIGATE":
+					if ("name" in action && typeof action.name === "string") {
+						internalDispatch({
+							type: "NAVIGATE",
+							name: action.name,
+							params: action.params as Record<string, unknown> | undefined,
+						});
+					}
+					break;
+				case "RESET":
+					internalDispatch({
+						type: "RESET",
+						name:
+							"name" in action
+								? (action.name as string | undefined)
+								: undefined,
+						params:
+							"params" in action
+								? (action.params as Record<string, unknown> | undefined)
+								: undefined,
+					});
+					break;
+				case "POP_BY_KEY":
+					if ("key" in action && typeof action.key === "string") {
+						internalDispatch({ type: "POP_BY_KEY", key: action.key });
+					}
+					break;
+			}
+		},
+		[],
+	);
+
+	// Ref for getState to always return latest state
+	const stateRef = useRef(state);
+	stateRef.current = state;
+
+	// Navigation object
+	const navigation: ComponentNavigation = useMemo(() => {
+		return {
+			push: (name: string, params?: Record<string, unknown>) => {
+				internalDispatch({ type: "PUSH", name, params });
+			},
+			pop: () => {
+				internalDispatch({ type: "POP" });
+			},
+			goBack: () => {
+				internalDispatch({ type: "POP" });
+			},
+			navigate: (name: string, params?: Record<string, unknown>) => {
+				internalDispatch({ type: "NAVIGATE", name, params });
+			},
+			canGoBack: () => stateRef.current.routes.length > 1,
+			reset: (name?: string, params?: Record<string, unknown>) => {
+				internalDispatch({ type: "RESET", name, params });
+			},
+			dispatch,
+			getState: () => stateRef.current,
+			index: state.index,
+		};
+	}, [state.index, dispatch]);
+
+	// Build descriptors for each route
+	const descriptors = useMemo(() => {
+		const result: ComponentStackDescriptorMap = {};
+
+		for (const route of state.routes) {
+			const screenConfig = screens[route.name];
+			if (!screenConfig) {
+				continue;
+			}
+
+			const Component = screenConfig.component;
+			const mergedOptions: ComponentStackNavigationOptions = {
+				...screenOptions,
+				...screenConfig.options,
+			};
+
+			const descriptor: ComponentStackDescriptor = {
+				route,
+				navigation,
+				options: mergedOptions,
+				render: (): React.JSX.Element => (
+					<Component navigation={navigation} route={route} />
+				),
+			};
+
+			result[route.key] = descriptor;
+		}
+
+		return result;
+	}, [state.routes, screens, screenOptions, navigation]);
+
+	// Describe function: creates a descriptor for a route (used for placeholder screens)
+	const describe = useCallback(
+		(route: ComponentRoute, placeholder: boolean): ComponentStackDescriptor => {
+			const screenConfig = screens[route.name];
+			const mergedOptions: ComponentStackNavigationOptions = {
+				...screenOptions,
+				...screenConfig?.options,
+			};
+
+			const Component = screenConfig?.component;
+
+			return {
+				route,
+				navigation,
+				options: mergedOptions,
+				render: (): React.JSX.Element | null =>
+					placeholder || !Component ? null : (
+						<Component navigation={navigation} route={route} />
+					),
+			};
+		},
+		[screens, screenOptions, navigation],
+	);
+
+	// NavigationContent wrapper (simple pass-through for component-stack)
+	const NavigationContent = useCallback(
+		({ children }: { children: React.ReactNode }) => {
+			return <>{children}</>;
+		},
+		[],
+	);
+
+	return {
+		state,
+		navigation,
+		describe,
+		descriptors,
+		NavigationContent,
+	};
+}

package/src/component-stack/hooks/use-component-navigation.tsx

@@ -0,0 +1,22 @@
+import { useComponentNavigationContext } from "../navigators/create-component-navigator";
+
+/**
+ * Hook to access the component navigation object from within a screen.
+ *
+ * @example
+ * ```tsx
+ * function MyScreen() {
+ *   const navigation = useComponentNavigation();
+ *
+ *   return (
+ *     <Button
+ *       title="Go to Details"
+ *       onPress={() => navigation.push('Details')}
+ *     />
+ *   );
+ * }
+ * ```
+ */
+export function useComponentNavigation() {
+	return useComponentNavigationContext();
+}

package/src/component-stack/index.ts

@@ -0,0 +1,16 @@
+export { useComponentNavigation } from "./hooks/use-component-navigation";
+export { createComponentNavigator } from "./navigators/create-component-navigator";
+export type {
+	ComponentNavigation,
+	ComponentNavigatorProps,
+	ComponentRoute,
+	ComponentScreenConfig,
+	ComponentScreenProps,
+	ComponentStackDescriptor,
+	ComponentStackNavigationOptions,
+	ComponentStackOverlayProps,
+	ComponentStackScene,
+	ComponentStackScreenProps,
+	ComponentStackScreenTransitionConfig,
+	ComponentStackState,
+} from "./types";

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

@@ -0,0 +1,104 @@
+import * as React from "react";
+import type { ManagedStackProps } from "../../shared/providers/stack/managed.provider";
+import { ComponentView } from "../components/component-view";
+import { useComponentNavigationBuilder } from "../hooks/use-component-navigation-builder";
+import type {
+	ComponentNavigation,
+	ComponentNavigatorProps,
+	ComponentScreenProps,
+	ComponentStackDescriptor,
+} from "../types";
+
+// Context for component navigation
+const ComponentNavigationContext =
+	React.createContext<ComponentNavigation | null>(null);
+
+export function useComponentNavigationContext(): ComponentNavigation {
+	const context = React.useContext(ComponentNavigationContext);
+	if (!context) {
+		throw new Error(
+			"useComponentNavigation must be used within a ComponentStack.Navigator",
+		);
+	}
+	return context;
+}
+
+/**
+ * Screen component for defining screens in a ComponentNavigator.
+ * This is a configuration component - it doesn't render anything itself.
+ */
+function ComponentScreen(_props: ComponentScreenProps): null {
+	return null;
+}
+
+/**
+ * Navigator component that manages internal component navigation.
+ * Does not affect React Navigation or Expo Router routes.
+ */
+function ComponentNavigator({
+	children,
+	initialRouteName,
+	screenOptions,
+}: ComponentNavigatorProps) {
+	const { state, navigation, describe, descriptors, NavigationContent } =
+		useComponentNavigationBuilder({
+			children,
+			initialRouteName,
+			screenOptions,
+		});
+
+	const managedStackProps: ManagedStackProps<
+		ComponentStackDescriptor,
+		ComponentNavigation
+	> = {
+		state,
+		navigation,
+		describe,
+		descriptors,
+	};
+
+	return (
+		<ComponentNavigationContext.Provider value={navigation}>
+			<NavigationContent>
+				<ComponentView {...managedStackProps} />
+			</NavigationContent>
+		</ComponentNavigationContext.Provider>
+	);
+}
+
+interface ComponentStack {
+	Navigator: React.FC<ComponentNavigatorProps>;
+	Screen: React.FC<ComponentScreenProps>;
+}
+
+/**
+ * Creates a component navigation stack.
+ *
+ * @example
+ * ```tsx
+ * const Stack = createComponentNavigator();
+ *
+ * function MyComponent() {
+ *   return (
+ *     <Stack.Navigator initialRouteName="Home">
+ *       <Stack.Screen
+ *         name="Home"
+ *         component={HomeScreen}
+ *         options={{ ...SlideFromBottom() }}
+ *       />
+ *       <Stack.Screen
+ *         name="Details"
+ *         component={DetailsScreen}
+ *         options={{ ...SlideFromBottom() }}
+ *       />
+ *     </Stack.Navigator>
+ *   );
+ * }
+ * ```
+ */
+export function createComponentNavigator(): ComponentStack {
+	return {
+		Navigator: ComponentNavigator,
+		Screen: ComponentScreen,
+	};
+}