@teardown/navigation 2.0.79 → 2.0.82

package/src/router/create-router.tsx

@@ -8,6 +8,10 @@ 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 { useEffect } from "react";
+import { initializeScopedHooks } from "../hooks/scoped-hooks";
+import type { RouteTree } from "../route-builder";
+import type { AnyRouteDefinition } from "../types/route-builder-types";
 import type { FlatRouteTree, NavigatorNode, ScreenEntry } from "./types";
 import { isHierarchicalRouteTree } from "./types";
 
@@ -15,11 +19,16 @@ import { isHierarchicalRouteTree } from "./types";
 let createBottomTabNavigator: (() => ReturnType<typeof createNativeStackNavigator>) | null = null;
 let createDrawerNavigator: (() => ReturnType<typeof createNativeStackNavigator>) | null = null;
 
+// Track which navigators are available
+let bottomTabsAvailable = false;
+let drawerAvailable = false;
+
 // 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;
+	bottomTabsAvailable = true;
 } catch {
 	// Bottom tabs not installed
 }
@@ -28,10 +37,57 @@ try {
 	// eslint-disable-next-line @typescript-eslint/no-require-imports
 	const drawer = require("@react-navigation/drawer");
 	createDrawerNavigator = drawer.createDrawerNavigator;
+	drawerAvailable = true;
 } catch {
 	// Drawer not installed
 }
 
+/**
+ * Recursively checks a navigator node tree for required navigator types
+ */
+function collectRequiredNavigatorTypes(node: NavigatorNode, types: Set<"tabs" | "drawer">): void {
+	if (node.type === "tabs") {
+		types.add("tabs");
+	} else if (node.type === "drawer") {
+		types.add("drawer");
+	}
+
+	// Check nested navigators
+	if (node.navigators) {
+		for (const nestedNode of Object.values(node.navigators)) {
+			collectRequiredNavigatorTypes(nestedNode, types);
+		}
+	}
+}
+
+/**
+ * Validates that required navigator dependencies are installed and throws if not
+ */
+function validateNavigatorDependencies(routeTree: NavigatorNode): void {
+	const requiredTypes = new Set<"tabs" | "drawer">();
+	collectRequiredNavigatorTypes(routeTree, requiredTypes);
+
+	const missingDeps: string[] = [];
+
+	if (requiredTypes.has("tabs") && !bottomTabsAvailable) {
+		missingDeps.push(
+			"Your route tree uses tabs navigation but @react-navigation/bottom-tabs is not installed.\n" +
+				"  Install it with: npm install @react-navigation/bottom-tabs"
+		);
+	}
+
+	if (requiredTypes.has("drawer") && !drawerAvailable) {
+		missingDeps.push(
+			"Your route tree uses drawer navigation but @react-navigation/drawer is not installed.\n" +
+				"  Install it with: npm install @react-navigation/drawer react-native-gesture-handler react-native-reanimated"
+		);
+	}
+
+	if (missingDeps.length > 0) {
+		throw new Error(`[@teardown/navigation] Missing required navigation dependencies:\n\n${missingDeps.join("\n\n")}`);
+	}
+}
+
 /**
  * Options for creating a Teardown router
  */
@@ -69,6 +125,31 @@ export interface TeardownRouterOptions<T extends NavigatorNode | FlatRouteTree =
 	navigationContainerProps?: Omit<React.ComponentProps<typeof NavigationContainer>, "children">;
 }
 
+/**
+ * Options for creating a Teardown router from a RouteTree
+ */
+export interface RouteTreeRouterOptions<TRoot extends AnyRouteDefinition> {
+	/**
+	 * The route tree created with createRouteTree()
+	 */
+	routeTree: RouteTree<TRoot>;
+
+	/**
+	 * Deep linking configuration
+	 */
+	linking?: LinkingOptions<Record<string, unknown>>;
+
+	/**
+	 * Navigation theme
+	 */
+	theme?: Theme;
+
+	/**
+	 * Custom navigation container wrapper
+	 */
+	navigationContainerProps?: Omit<React.ComponentProps<typeof NavigationContainer>, "children">;
+}
+
 /**
  * Creates a navigator component based on type
  */
@@ -76,18 +157,18 @@ 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."
+				throw new Error(
+					"[@teardown/navigation] Tab navigator requested but @react-navigation/bottom-tabs is not installed.\n" +
+						"Install it with: npm install @react-navigation/bottom-tabs"
 				);
-				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."
+				throw new Error(
+					"[@teardown/navigation] Drawer navigator requested but @react-navigation/drawer is not installed.\n" +
+						"Install it with: npm install @react-navigation/drawer react-native-gesture-handler react-native-reanimated"
 				);
-				return createNativeStackNavigator();
 			}
 			return createDrawerNavigator();
 		default:
@@ -197,6 +278,9 @@ export function createTeardownRouter<T extends NavigatorNode | FlatRouteTree>(
 
 	// Check if this is a hierarchical route tree
 	if (isHierarchicalRouteTree(routeTree)) {
+		// Validate that required navigator dependencies are installed (warns early)
+		validateNavigatorDependencies(routeTree);
+
 		// Set initial route name if provided
 		const treeWithInitial: NavigatorNode = {
 			...routeTree,
@@ -280,3 +364,108 @@ export type ExtractRoutePaths<T extends NavigatorNode> = T extends NavigatorNode
  * Type helper to extract screen definitions from a route tree
  */
 export type ExtractScreens<T extends NavigatorNode> = T extends NavigatorNode ? T["screens"] : never;
+
+/**
+ * Creates a Teardown Router from a RouteTree (enhanced API)
+ *
+ * This is the new API that uses the route builder pattern with
+ * createRootLayout, defineLayout, and defineScreen.
+ *
+ * @example
+ * ```tsx
+ * import { createTeardownRouterFromTree, createRouteTree, createRootLayout, defineScreen } from "@teardown/navigation";
+ *
+ * const root = createRootLayout({ type: 'stack' });
+ * const home = defineScreen({ path: 'home', component: HomeScreen, getParentRoute: () => root });
+ *
+ * const routeTree = createRouteTree({
+ *   root: root.addChildren([home]),
+ * });
+ *
+ * export const Router = createTeardownRouterFromTree({ routeTree });
+ * ```
+ */
+export function createTeardownRouterFromTree<TRoot extends AnyRouteDefinition>(
+	options: RouteTreeRouterOptions<TRoot>
+): ComponentType<{ children?: ReactNode }> {
+	const { routeTree, linking, theme, navigationContainerProps } = options;
+
+	function TeardownRouterFromTree(): React.JSX.Element {
+		// Initialize scoped hooks with React Navigation
+		useEffect(() => {
+			try {
+				// eslint-disable-next-line @typescript-eslint/no-require-imports
+				const { useRoute, useNavigation } = require("@react-navigation/native");
+				initializeScopedHooks(useRoute, useNavigation);
+			} catch {
+				console.warn("[@teardown/navigation] @react-navigation/native not found");
+			}
+		}, []);
+
+		// Build navigator tree from route tree
+		const navigatorNode = buildNavigatorFromRouteTree(routeTree.root);
+
+		return (
+			<NavigationContainer linking={linking} theme={theme} {...navigationContainerProps}>
+				<RenderNavigator node={navigatorNode} />
+			</NavigationContainer>
+		);
+	}
+
+	return TeardownRouterFromTree;
+}
+
+/**
+ * Builds a NavigatorNode from a RouteTree root
+ */
+function buildNavigatorFromRouteTree(root: AnyRouteDefinition): NavigatorNode {
+	const isLayout = "__brand" in root && root.__brand === "TeardownLayout";
+
+	if (!isLayout) {
+		// Single screen, wrap in a stack
+		return {
+			type: "stack",
+			screens: {
+				[(root as { path?: string }).path || "index"]: {
+					screen: root as unknown as ScreenEntry["screen"],
+					path: (root as { fullPath?: string }).fullPath || "/",
+				},
+			},
+		};
+	}
+
+	const layout = root as unknown as {
+		type: "stack" | "tabs" | "drawer";
+		screenOptions?: object;
+		initialRouteName?: string;
+		children: AnyRouteDefinition[];
+	};
+
+	const screens: Record<string, ScreenEntry> = {};
+	const navigators: Record<string, NavigatorNode> = {};
+
+	for (const child of layout.children || []) {
+		const childBrand = "__brand" in child ? child.__brand : undefined;
+		const childPath = (child as { path?: string }).path || "index";
+		const childFullPath = (child as { fullPath?: string }).fullPath || "/";
+
+		if (childBrand === "TeardownLayout") {
+			// Nested navigator
+			navigators[childPath] = buildNavigatorFromRouteTree(child);
+		} else {
+			// Screen
+			screens[childPath] = {
+				screen: child as unknown as ScreenEntry["screen"],
+				path: childFullPath,
+			};
+		}
+	}
+
+	return {
+		type: layout.type,
+		screens,
+		navigators: Object.keys(navigators).length > 0 ? navigators : undefined,
+		screenOptions: layout.screenOptions as Record<string, unknown> | undefined,
+		initialRouteName: layout.initialRouteName,
+	};
+}

package/src/router/index.ts

@@ -2,8 +2,13 @@
  * Router module exports
  */
 
-export type { ExtractRoutePaths, ExtractScreens, TeardownRouterOptions } from "./create-router";
-export { createTeardownRouter } from "./create-router";
+export type {
+	ExtractRoutePaths,
+	ExtractScreens,
+	RouteTreeRouterOptions,
+	TeardownRouterOptions,
+} from "./create-router";
+export { createTeardownRouter, createTeardownRouterFromTree } from "./create-router";
 // Legacy type aliases for backwards compatibility
 export type {
 	DrawerScreenOptions,

package/src/types/index.ts

@@ -2,6 +2,18 @@
  * Type utilities and definitions for @teardown/navigation
  */
 
+// Route builder types
+export type {
+	AccumulateParams,
+	AnyRouteDefinition,
+	ComputeFullPath,
+	ExtractRouteParams,
+	ExtractRoutePaths,
+	MergeRouteParams,
+	ParamsForPath,
+	RouteDefinitionBase,
+	StripRouteGroups,
+} from "./route-builder-types";
 // Route type definitions
 export type {
 	NavigationState,
@@ -22,7 +34,9 @@ export type {
 	InferParams,
 	IsCatchAllSegment,
 	IsDynamicSegment,
+	IsEmptyParams,
 	IsOptionalSegment,
 	NavigateArgs,
 	Simplify,
+	ToReactNavigationPath,
 } from "./type-utils";

package/src/types/route-builder-types.ts

@@ -0,0 +1,103 @@
+/**
+ * Route builder type utilities for @teardown/navigation
+ * Enables compile-time path computation and param accumulation
+ */
+
+import type { InferParams, Simplify } from "./type-utils";
+
+/**
+ * Compute full path from parent chain
+ * Handles route groups by stripping (groupName) segments
+ */
+export type ComputeFullPath<TPath extends string, TParent> = TParent extends {
+	fullPath: infer P extends string;
+}
+	? P extends "/"
+		? `/${StripRouteGroups<TPath>}`
+		: StripRouteGroups<TPath> extends ""
+			? P
+			: `${P}/${StripRouteGroups<TPath>}`
+	: StripRouteGroups<TPath> extends ""
+		? "/"
+		: `/${StripRouteGroups<TPath>}`;
+
+/**
+ * Strip route group segments from path
+ * (auth)/login -> login
+ * (auth) -> ""
+ */
+export type StripRouteGroups<TPath extends string> = TPath extends `(${string})/${infer Rest}`
+	? StripRouteGroups<Rest>
+	: TPath extends `(${string})`
+		? ""
+		: TPath;
+
+/**
+ * Accumulate params from parent chain + this route
+ */
+export type AccumulateParams<TPath extends string, TParent> = Simplify<
+	InferParams<TPath> & (TParent extends { allParams: infer P } ? P : {})
+>;
+
+/**
+ * Base interface for all route definitions (screens and layouts)
+ */
+export interface RouteDefinitionBase<
+	TPath extends string = string,
+	TFullPath extends string = string,
+	TParams = unknown,
+	TAllParams = unknown,
+	TContext = unknown,
+> {
+	/** This route segment path */
+	readonly path: TPath;
+	/** Full path from root */
+	readonly fullPath: TFullPath;
+	/** Params from this route only */
+	readonly params: TParams;
+	/** Accumulated params from parent chain */
+	readonly allParams: TAllParams;
+	/** Loader context type */
+	readonly context: TContext;
+}
+
+/**
+ * Type for any route definition (screen or layout)
+ */
+export type AnyRouteDefinition = RouteDefinitionBase<string, string, unknown, unknown, unknown>;
+
+/**
+ * Extract all route paths from a route tree
+ */
+export type ExtractRoutePaths<T> = T extends { fullPath: infer P extends string }
+	?
+			| P
+			| (T extends { children: infer C }
+					? C extends readonly (infer Child)[]
+						? ExtractRoutePaths<Child>
+						: never
+					: never)
+	: never;
+
+/**
+ * Extract route params map from a route tree
+ */
+export type ExtractRouteParams<T> = T extends { fullPath: infer P extends string; allParams: infer Params }
+	? { [K in P]: Params } & (T extends { children: infer C }
+			? C extends readonly (infer Child)[]
+				? ExtractRouteParams<Child>
+				: {}
+			: {})
+	: {};
+
+/**
+ * Merge two route param maps
+ */
+export type MergeRouteParams<A, B> = Simplify<A & B>;
+
+/**
+ * Get params for a specific path from a route tree
+ */
+export type ParamsForPath<TTree, TPath extends string> = TPath extends keyof ExtractRouteParams<TTree>
+	? ExtractRouteParams<TTree>[TPath]
+	: never;

package/src/types/type-utils.ts

@@ -11,19 +11,46 @@ export type Simplify<T> = { [K in keyof T]: T[K] } & {};
 
 /**
  * Extracts parameter from a single path segment
+ * Supports both [param] and :param syntax
  *
- * - [userId] -> { userId: string }
- * - [...slug] -> { slug: string[] }
- * - [section]? -> { section?: string }
+ * - [userId] or :userId -> { userId: string }
+ * - [...slug] or *slug -> { slug: string[] }
+ * - [section]? or :section? -> { section?: string }
  * - about -> Record<string, never>
  */
-export type ExtractParam<Segment extends string> = Segment extends `[...${infer Rest}]`
-	? { [K in Rest]: string[] }
-	: Segment extends `[${infer Param}]?`
-		? { [K in Param]?: string }
-		: Segment extends `[${infer Param}]`
-			? { [K in Param]: string }
-			: Record<string, never>;
+export type ExtractParam<Segment extends string> =
+	// Catch-all: [...slug] or *slug
+	Segment extends `[...${infer Rest}]`
+		? { [K in Rest]: string[] }
+		: Segment extends `*${infer Rest}`
+			? { [K in Rest]: string[] }
+			: // Optional: [param]? or :param?
+				Segment extends `[${infer Param}]?`
+				? { [K in Param]?: string }
+				: Segment extends `:${infer Param}?`
+					? { [K in Param]?: string }
+					: // Required: [param] or :param
+						Segment extends `[${infer Param}]`
+						? { [K in Param]: string }
+						: Segment extends `:${infer Param}`
+							? { [K in Param]: string }
+							: // Static segment
+								Record<string, never>;
+
+/**
+ * Check if params object is empty (no required params)
+ */
+export type IsEmptyParams<T> = keyof T extends never ? true : false;
+
+/**
+ * Convert [param] syntax to :param syntax for React Navigation
+ */
+export type ToReactNavigationPath<TPath extends string> =
+	TPath extends `${infer Before}[...${infer Param}]${infer After}`
+		? ToReactNavigationPath<`${Before}*${Param}${After}`>
+		: TPath extends `${infer Before}[${infer Param}]${infer After}`
+			? ToReactNavigationPath<`${Before}:${Param}${After}`>
+			: TPath;
 
 /**
  * Recursively extracts all params from a path