@teardown/navigation 2.0.70 → 2.0.71

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@teardown/navigation",
-	"version": "2.0.70",
+	"version": "2.0.71",
 	"description": "Type-safe file-based navigation for React Native",
 	"private": false,
 	"publishConfig": {
@@ -72,7 +72,7 @@
 	},
 	"devDependencies": {
 		"@biomejs/biome": "2.3.11",
-		"@teardown/tsconfig": "2.0.70",
+		"@teardown/tsconfig": "2.0.71",
 		"@types/react": "19.2.7",
 		"typescript": "5.9.3"
 	}

package/src/index.ts

@@ -42,6 +42,19 @@ export {
 	isScreenDefinition,
 	paramValidators,
 } from "./primitives";
+// Router
+export type {
+	ExtractRoutePaths,
+	ExtractScreens,
+	FlatRouteTree,
+	FlatRouteTreeEntry,
+	NavigatorNode,
+	RouteTree,
+	RouteTreeEntry,
+	ScreenEntry,
+	TeardownRouterOptions,
+} from "./router";
+export { createTeardownRouter, isFlatRouteTree, isHierarchicalRouteTree } from "./router";
 // Types
 export type {
 	NavigationState,

package/src/router/create-router.tsx

@@ -0,0 +1,282 @@
+/**
+ * createTeardownRouter - Factory function for creating a type-safe router
+ * Supports nested Stack, Tab, and Drawer navigators
+ */
+
+import type { LinkingOptions, Theme } from "@react-navigation/native";
+import { NavigationContainer } from "@react-navigation/native";
+import { createNativeStackNavigator } from "@react-navigation/native-stack";
+import type React from "react";
+import type { ComponentType, ReactNode } from "react";
+import type { FlatRouteTree, NavigatorNode, ScreenEntry } from "./types";
+import { isHierarchicalRouteTree } from "./types";
+
+// Lazy imports for optional navigators
+let createBottomTabNavigator: (() => ReturnType<typeof createNativeStackNavigator>) | null = null;
+let createDrawerNavigator: (() => ReturnType<typeof createNativeStackNavigator>) | null = null;
+
+// Try to load optional dependencies
+try {
+	// eslint-disable-next-line @typescript-eslint/no-require-imports
+	const bottomTabs = require("@react-navigation/bottom-tabs");
+	createBottomTabNavigator = bottomTabs.createBottomTabNavigator;
+} catch {
+	// Bottom tabs not installed
+}
+
+try {
+	// eslint-disable-next-line @typescript-eslint/no-require-imports
+	const drawer = require("@react-navigation/drawer");
+	createDrawerNavigator = drawer.createDrawerNavigator;
+} catch {
+	// Drawer not installed
+}
+
+/**
+ * Options for creating a Teardown router
+ */
+export interface TeardownRouterOptions<T extends NavigatorNode | FlatRouteTree = NavigatorNode> {
+	/**
+	 * The generated route tree from routeTree.generated.ts
+	 * Supports both hierarchical (NavigatorNode) and flat (legacy) formats
+	 */
+	routeTree: T;
+
+	/**
+	 * Initial route name (screen key without leading slash)
+	 * @default first route in routeTree
+	 */
+	initialRouteName?: string;
+
+	/**
+	 * Deep linking configuration
+	 */
+	linking?: LinkingOptions<Record<string, unknown>>;
+
+	/**
+	 * Navigation theme
+	 */
+	theme?: Theme;
+
+	/**
+	 * Fallback component shown when navigating to unknown routes
+	 */
+	notFoundComponent?: ComponentType;
+
+	/**
+	 * Custom navigation container wrapper
+	 */
+	navigationContainerProps?: Omit<React.ComponentProps<typeof NavigationContainer>, "children">;
+}
+
+/**
+ * Creates a navigator component based on type
+ */
+function createNavigator(type: "stack" | "tabs" | "drawer") {
+	switch (type) {
+		case "tabs":
+			if (!createBottomTabNavigator) {
+				console.warn(
+					"[@teardown/navigation] Tab navigator requested but @react-navigation/bottom-tabs is not installed. Falling back to stack."
+				);
+				return createNativeStackNavigator();
+			}
+			return createBottomTabNavigator();
+		case "drawer":
+			if (!createDrawerNavigator) {
+				console.warn(
+					"[@teardown/navigation] Drawer navigator requested but @react-navigation/drawer is not installed. Falling back to stack."
+				);
+				return createNativeStackNavigator();
+			}
+			return createDrawerNavigator();
+		default:
+			return createNativeStackNavigator();
+	}
+}
+
+/**
+ * Gets default screen options based on navigator type
+ */
+function getDefaultScreenOptions(type: "stack" | "tabs" | "drawer") {
+	switch (type) {
+		case "tabs":
+			return {
+				headerShown: false,
+			};
+		case "drawer":
+			return {
+				headerShown: true,
+			};
+		default:
+			return {
+				headerShown: true,
+				animation: "slide_from_right" as const,
+			};
+	}
+}
+
+/**
+ * Renders a navigator node recursively
+ */
+function RenderNavigator({ node }: { node: NavigatorNode }): React.JSX.Element {
+	const Navigator = createNavigator(node.type);
+	const defaultOptions = getDefaultScreenOptions(node.type);
+
+	// Get screen options from layout if available
+	const layoutOptions = node.layout?.screenOptions || {};
+	const initialRouteName = node.layout?.initialRouteName || node.initialRouteName;
+
+	return (
+		<Navigator.Navigator
+			initialRouteName={initialRouteName}
+			screenOptions={{
+				...defaultOptions,
+				...layoutOptions,
+			}}
+		>
+			{/* Render screens */}
+			{Object.entries(node.screens).map(([name, entry]) => {
+				const screenEntry = entry as ScreenEntry;
+				const screenDef = screenEntry.screen;
+
+				return (
+					<Navigator.Screen
+						key={name}
+						name={name}
+						component={screenDef.component}
+						options={typeof screenDef.options === "function" ? screenDef.options : screenDef.options}
+					/>
+				);
+			})}
+
+			{/* Render nested navigators as screens */}
+			{node.navigators &&
+				Object.entries(node.navigators).map(([name, nestedNode]) => {
+					// Create a component that renders the nested navigator
+					const NestedNavigatorComponent = () => <RenderNavigator node={nestedNode} />;
+
+					return (
+						<Navigator.Screen
+							key={name}
+							name={name}
+							component={NestedNavigatorComponent}
+							options={{ headerShown: false }}
+						/>
+					);
+				})}
+		</Navigator.Navigator>
+	);
+}
+
+/**
+ * Creates a Teardown Router component from a generated route tree
+ *
+ * @example
+ * ```tsx
+ * import { createTeardownRouter } from "@teardown/navigation";
+ * import { routeTree } from "../.teardown/routeTree.generated";
+ *
+ * export const Router = createTeardownRouter({
+ *   routeTree,
+ *   initialRouteName: "home",
+ * });
+ * ```
+ */
+export function createTeardownRouter<T extends NavigatorNode | FlatRouteTree>(
+	options: TeardownRouterOptions<T>
+): ComponentType<{ children?: ReactNode }> {
+	const {
+		routeTree,
+		initialRouteName,
+		linking,
+		theme,
+		notFoundComponent: NotFoundComponent,
+		navigationContainerProps,
+	} = options;
+
+	// Check if this is a hierarchical route tree
+	if (isHierarchicalRouteTree(routeTree)) {
+		// Set initial route name if provided
+		const treeWithInitial: NavigatorNode = {
+			...routeTree,
+			initialRouteName: initialRouteName || routeTree.initialRouteName,
+		};
+
+		function TeardownRouter(): React.JSX.Element {
+			return (
+				<NavigationContainer linking={linking} theme={theme} {...navigationContainerProps}>
+					<RenderNavigator node={treeWithInitial} />
+				</NavigationContainer>
+			);
+		}
+
+		return TeardownRouter;
+	}
+
+	// Legacy flat route tree support
+	const flatTree = routeTree as FlatRouteTree;
+	const Stack = createNativeStackNavigator();
+	const routeEntries = Object.entries(flatTree);
+	const firstRoute = routeEntries[0];
+	const initialRoute = initialRouteName || (firstRoute ? pathToRouteName(firstRoute[0]) : "index");
+	const rootLayout = firstRoute?.[1]?.layout;
+	const defaultOptions = rootLayout ? getDefaultScreenOptions(rootLayout.type) : getDefaultScreenOptions("stack");
+
+	function TeardownRouterLegacy(): React.JSX.Element {
+		return (
+			<NavigationContainer linking={linking} theme={theme} {...navigationContainerProps}>
+				<Stack.Navigator
+					initialRouteName={initialRoute}
+					screenOptions={{
+						...defaultOptions,
+						...(rootLayout?.screenOptions || {}),
+					}}
+				>
+					{routeEntries.map(([path, entry]) => {
+						const routeName = pathToRouteName(path);
+						const screenDef = entry.screen;
+
+						return (
+							<Stack.Screen
+								key={path}
+								name={routeName}
+								component={screenDef.component}
+								options={typeof screenDef.options === "function" ? screenDef.options : screenDef.options}
+							/>
+						);
+					})}
+					{NotFoundComponent && (
+						<Stack.Screen name="__notFound__" component={NotFoundComponent} options={{ title: "Not Found" }} />
+					)}
+				</Stack.Navigator>
+			</NavigationContainer>
+		);
+	}
+
+	return TeardownRouterLegacy;
+}
+
+/**
+ * Converts a URL path to a route name for React Navigation
+ * e.g., "/" -> "index", "/users/:userId" -> "users/[userId]"
+ */
+function pathToRouteName(path: string): string {
+	if (path === "/") return "index";
+
+	return path
+		.slice(1) // Remove leading slash
+		.replace(/:([^/]+)\?/g, "[[$1]]") // :param? -> [[param]]
+		.replace(/:([^/]+)/g, "[$1]") // :param -> [param]
+		.replace(/\*/g, "[...catchAll]"); // * -> [...catchAll]
+}
+
+/**
+ * Type helper to extract route paths from a route tree
+ */
+export type ExtractRoutePaths<T extends NavigatorNode> = T extends NavigatorNode ? keyof T["screens"] & string : never;
+
+/**
+ * Type helper to extract screen definitions from a route tree
+ */
+export type ExtractScreens<T extends NavigatorNode> = T extends NavigatorNode ? T["screens"] : never;

package/src/router/index.ts

@@ -0,0 +1,19 @@
+/**
+ * Router module exports
+ */
+
+export type { ExtractRoutePaths, ExtractScreens, TeardownRouterOptions } from "./create-router";
+export { createTeardownRouter } from "./create-router";
+// Legacy type aliases for backwards compatibility
+export type {
+	DrawerScreenOptions,
+	FlatRouteTree,
+	FlatRouteTreeEntry,
+	FlatRouteTreeEntry as RouteTreeEntry,
+	NavigatorNode,
+	NavigatorType,
+	RouteTree,
+	ScreenEntry,
+	TabScreenOptions,
+} from "./types";
+export { isFlatRouteTree, isHierarchicalRouteTree } from "./types";

package/src/router/types.ts

@@ -0,0 +1,107 @@
+/**
+ * Types for hierarchical navigator tree structure
+ * Supports nested Stack, Tab, and Drawer navigators
+ */
+
+import type { LayoutDefinition, ScreenDefinition } from "../primitives";
+
+/**
+ * Navigator types supported by the router
+ */
+export type NavigatorType = "stack" | "tabs" | "drawer";
+
+/**
+ * Screen entry in a navigator
+ */
+export interface ScreenEntry {
+	/** The screen definition from defineScreen */
+	screen: ScreenDefinition;
+	/** Path for this screen (used for linking) */
+	path?: string;
+}
+
+/**
+ * Navigator node representing a Stack, Tab, or Drawer navigator
+ * Can contain screens and nested navigators
+ */
+export interface NavigatorNode {
+	/** Navigator type - determines which navigator component to use */
+	type: NavigatorType;
+
+	/** Layout definition containing screen options and configuration */
+	layout?: LayoutDefinition;
+
+	/** Screen options applied to all screens in this navigator */
+	screenOptions?: Record<string, unknown>;
+
+	/** Initial route name for this navigator */
+	initialRouteName?: string;
+
+	/** Screens contained directly in this navigator */
+	screens: Record<string, ScreenEntry>;
+
+	/** Nested navigators (e.g., tabs inside a stack) */
+	navigators?: Record<string, NavigatorNode>;
+
+	/** Name of this navigator (used as screen name in parent) */
+	name?: string;
+}
+
+/**
+ * Root route tree - the top-level navigator
+ */
+export type RouteTree = NavigatorNode;
+
+/**
+ * Flat route tree entry (legacy format, kept for backwards compatibility)
+ */
+export interface FlatRouteTreeEntry {
+	screen: ScreenDefinition;
+	layout?: LayoutDefinition;
+}
+
+/**
+ * Flat route tree (legacy format)
+ */
+export type FlatRouteTree = Record<string, FlatRouteTreeEntry>;
+
+/**
+ * Type guard to check if a route tree is hierarchical
+ */
+export function isHierarchicalRouteTree(tree: unknown): tree is RouteTree {
+	return (
+		typeof tree === "object" &&
+		tree !== null &&
+		"type" in tree &&
+		"screens" in tree &&
+		typeof (tree as RouteTree).type === "string"
+	);
+}
+
+/**
+ * Type guard to check if a route tree is flat (legacy)
+ */
+export function isFlatRouteTree(tree: unknown): tree is FlatRouteTree {
+	if (typeof tree !== "object" || tree === null) return false;
+	// Flat trees have string keys mapping to {screen, layout?} objects
+	const firstValue = Object.values(tree)[0];
+	return firstValue && "screen" in firstValue && !("type" in tree);
+}
+
+/**
+ * Options for tab navigator screens
+ */
+export interface TabScreenOptions {
+	tabBarLabel?: string;
+	tabBarIcon?: (props: { focused: boolean; color: string; size: number }) => React.ReactNode;
+	tabBarBadge?: string | number;
+	tabBarShowLabel?: boolean;
+}
+
+/**
+ * Options for drawer navigator screens
+ */
+export interface DrawerScreenOptions {
+	drawerLabel?: string;
+	drawerIcon?: (props: { focused: boolean; color: string; size: number }) => React.ReactNode;
+}