@teardown/navigation 2.0.80 → 2.0.82

package/src/route-builder/create-root-layout.ts

@@ -0,0 +1,42 @@
+/**
+ * createRootLayout - Factory for creating the root layout
+ * The root layout is the top-level navigator with no parent
+ */
+
+import { defineLayout, type EnhancedLayoutDefinition, type NavigatorType } from "../primitives/define-layout";
+
+/**
+ * Root layout configuration
+ */
+export interface RootLayoutConfig<TType extends NavigatorType> {
+	/** Navigator type */
+	type: TType;
+	/** Default screen options for children */
+	screenOptions?: object;
+	/** Initial route name */
+	initialRouteName?: string;
+}
+
+/**
+ * Create the root layout (no parent)
+ *
+ * @example
+ * ```tsx
+ * const rootLayout = createRootLayout({ type: 'stack' });
+ *
+ * // Then add children
+ * const routeTree = createRouteTree({
+ *   root: rootLayout.addChildren([homeScreen, settingsScreen]),
+ * });
+ * ```
+ */
+export function createRootLayout<TType extends NavigatorType>(
+	config: RootLayoutConfig<TType>
+): EnhancedLayoutDefinition<TType, "", "/", Record<string, never>, Record<string, never>, unknown> {
+	return defineLayout({
+		type: config.type,
+		path: "",
+		screenOptions: config.screenOptions,
+		initialRouteName: config.initialRouteName,
+	}) as EnhancedLayoutDefinition<TType, "", "/", Record<string, never>, Record<string, never>, unknown>;
+}

package/src/route-builder/create-route-tree.ts

@@ -0,0 +1,128 @@
+/**
+ * createRouteTree - Creates a validated route tree from a root layout
+ * The route tree is used by the router to render the navigation hierarchy
+ */
+
+import type { AnyRouteDefinition, ExtractRouteParams, ExtractRoutePaths } from "../types/route-builder-types";
+
+/**
+ * Route tree structure
+ */
+export interface RouteTree<TRoot extends AnyRouteDefinition> {
+	/** Root layout */
+	root: TRoot;
+	/** All route paths (union type) */
+	routePaths: ExtractRoutePaths<TRoot>;
+	/** Map of path -> params */
+	routeParams: ExtractRouteParams<TRoot>;
+}
+
+/**
+ * Configuration for creating a route tree
+ */
+export interface CreateRouteTreeConfig<TRoot extends AnyRouteDefinition> {
+	/** Root layout with children */
+	root: TRoot;
+}
+
+/**
+ * Create a validated route tree from root layout
+ *
+ * @example
+ * ```tsx
+ * const routeTree = createRouteTree({
+ *   root: rootLayout.addChildren([
+ *     usersLayout.addChildren([userProfile, userPosts]),
+ *     settingsScreen,
+ *   ]),
+ * });
+ * ```
+ */
+export function createRouteTree<TRoot extends AnyRouteDefinition>(
+	config: CreateRouteTreeConfig<TRoot>
+): RouteTree<TRoot> {
+	// Validate tree structure at runtime
+	validateRouteTree(config.root);
+
+	return {
+		root: config.root,
+		routePaths: extractRoutePaths(config.root) as ExtractRoutePaths<TRoot>,
+		routeParams: extractRouteParams(config.root) as ExtractRouteParams<TRoot>,
+	};
+}
+
+/**
+ * Validate route tree structure
+ * Checks for duplicate paths and other issues
+ */
+function validateRouteTree(node: AnyRouteDefinition, seen = new Set<string>()): void {
+	const fullPath = node.fullPath;
+
+	// Skip empty paths (root layout)
+	if (fullPath && fullPath !== "/") {
+		if (seen.has(fullPath)) {
+			throw new Error(`Duplicate route path: ${fullPath}`);
+		}
+		seen.add(fullPath);
+	}
+
+	// Recursively validate children
+	if ("children" in node && Array.isArray(node.children)) {
+		for (const child of node.children) {
+			validateRouteTree(child as AnyRouteDefinition, seen);
+		}
+	}
+}
+
+/**
+ * Extract all route paths from a route tree
+ */
+function extractRoutePaths(node: AnyRouteDefinition): string[] {
+	const paths: string[] = [];
+
+	if (node.fullPath) {
+		paths.push(node.fullPath);
+	}
+
+	if ("children" in node && Array.isArray(node.children)) {
+		for (const child of node.children) {
+			paths.push(...extractRoutePaths(child as AnyRouteDefinition));
+		}
+	}
+
+	return paths;
+}
+
+/**
+ * Extract route params map from a route tree
+ */
+function extractRouteParams(node: AnyRouteDefinition): Record<string, unknown> {
+	const params: Record<string, unknown> = {};
+
+	if (node.fullPath) {
+		params[node.fullPath] = node.allParams;
+	}
+
+	if ("children" in node && Array.isArray(node.children)) {
+		for (const child of node.children) {
+			Object.assign(params, extractRouteParams(child as AnyRouteDefinition));
+		}
+	}
+
+	return params;
+}
+
+/**
+ * Get all route definitions from a route tree as a flat array
+ */
+export function flattenRouteTree(node: AnyRouteDefinition): AnyRouteDefinition[] {
+	const routes: AnyRouteDefinition[] = [node];
+
+	if ("children" in node && Array.isArray(node.children)) {
+		for (const child of node.children) {
+			routes.push(...flattenRouteTree(child as AnyRouteDefinition));
+		}
+	}
+
+	return routes;
+}

package/src/route-builder/index.ts

@@ -0,0 +1,7 @@
+/**
+ * Route builder module for @teardown/navigation
+ * Provides utilities for building type-safe route trees
+ */
+
+export { createRootLayout, type RootLayoutConfig } from "./create-root-layout";
+export { type CreateRouteTreeConfig, createRouteTree, flattenRouteTree, type RouteTree } from "./create-route-tree";

package/src/route-builder/route-builder-d.test.ts

@@ -0,0 +1,100 @@
+/**
+ * Type-level tests for route builder types
+ * These tests verify that the type utilities correctly compute paths and params
+ *
+ * Note: These are compile-time type tests. The runtime assertions are minimal
+ * because the main goal is to verify TypeScript type inference is correct.
+ */
+
+import { describe, expect, it } from "bun:test";
+import type { AccumulateParams, ComputeFullPath, StripRouteGroups } from "../types/route-builder-types";
+
+// Helper type for testing - checks if two types are exactly equal
+type Equals<A, B> = (<T>() => T extends A ? 1 : 2) extends <T>() => T extends B ? 1 : 2 ? true : false;
+
+// Type assertion helper - verifies type at compile time
+function assertType<T>(_value: T): void {}
+
+describe("Route Builder Types - Compile Time", () => {
+	describe("StripRouteGroups", () => {
+		it("strips route group prefix", () => {
+			type Result = StripRouteGroups<"(auth)/login">;
+			const isEqual: Equals<Result, "login"> = true;
+			expect(isEqual).toBe(true);
+		});
+
+		it("strips standalone route group", () => {
+			type Result = StripRouteGroups<"(auth)">;
+			const isEqual: Equals<Result, ""> = true;
+			expect(isEqual).toBe(true);
+		});
+
+		it("preserves paths without route groups", () => {
+			type Result = StripRouteGroups<"users">;
+			const isEqual: Equals<Result, "users"> = true;
+			expect(isEqual).toBe(true);
+		});
+
+		it("strips nested route groups", () => {
+			type Result = StripRouteGroups<"(admin)/(dashboard)/settings">;
+			const isEqual: Equals<Result, "settings"> = true;
+			expect(isEqual).toBe(true);
+		});
+	});
+
+	describe("ComputeFullPath", () => {
+		it("computes root path for empty path with no parent", () => {
+			type Result = ComputeFullPath<"", undefined>;
+			const isEqual: Equals<Result, "/"> = true;
+			expect(isEqual).toBe(true);
+		});
+
+		it("computes full path for simple segment with no parent", () => {
+			type Result = ComputeFullPath<"users", undefined>;
+			const isEqual: Equals<Result, "/users"> = true;
+			expect(isEqual).toBe(true);
+		});
+
+		it("computes full path with parent", () => {
+			type Parent = { fullPath: "/users" };
+			type Result = ComputeFullPath<"[userId]", Parent>;
+			const isEqual: Equals<Result, "/users/[userId]"> = true;
+			expect(isEqual).toBe(true);
+		});
+
+		it("computes full path with root parent", () => {
+			type Parent = { fullPath: "/" };
+			type Result = ComputeFullPath<"users", Parent>;
+			const isEqual: Equals<Result, "/users"> = true;
+			expect(isEqual).toBe(true);
+		});
+
+		it("strips route groups from computed path", () => {
+			type Parent = { fullPath: "/" };
+			type Result = ComputeFullPath<"(auth)/login", Parent>;
+			const isEqual: Equals<Result, "/login"> = true;
+			expect(isEqual).toBe(true);
+		});
+	});
+
+	describe("AccumulateParams", () => {
+		it("extracts params from single segment", () => {
+			type Result = AccumulateParams<"[userId]", undefined>;
+			assertType<Result>({ userId: "123" });
+			expect(true).toBe(true);
+		});
+
+		it("accumulates params from parent", () => {
+			type Parent = { allParams: { userId: string } };
+			type Result = AccumulateParams<"[postId]", Parent>;
+			assertType<Result>({ userId: "123", postId: "456" });
+			expect(true).toBe(true);
+		});
+
+		it("returns empty for static paths", () => {
+			type Result = AccumulateParams<"about", undefined>;
+			const result: Result = {};
+			expect(Object.keys(result).length).toBe(0);
+		});
+	});
+});

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

@@ -0,0 +1,276 @@
+/**
+ * Runtime tests for route builder
+ */
+
+import { describe, expect, it } from "bun:test";
+import { defineLayout, defineScreen } from "../primitives";
+import { createRootLayout } from "./create-root-layout";
+import { createRouteTree, flattenRouteTree } from "./create-route-tree";
+
+// Dummy component for tests
+const DummyComponent = () => null;
+
+describe("Route Builder Runtime", () => {
+	describe("createRootLayout", () => {
+		it("creates a root layout with fullPath /", () => {
+			const root = createRootLayout({ type: "stack" });
+
+			expect(root.path).toBe("");
+			expect(root.fullPath).toBe("/");
+			expect(root.__brand).toBe("TeardownLayout");
+		});
+
+		it("supports different navigator types", () => {
+			const stack = createRootLayout({ type: "stack" });
+			const tabs = createRootLayout({ type: "tabs" });
+			const drawer = createRootLayout({ type: "drawer" });
+
+			expect(stack.type).toBe("stack");
+			expect(tabs.type).toBe("tabs");
+			expect(drawer.type).toBe("drawer");
+		});
+
+		it("passes through screen options", () => {
+			const root = createRootLayout({
+				type: "stack",
+				screenOptions: { headerShown: false },
+			});
+
+			expect(root.screenOptions).toEqual({ headerShown: false });
+		});
+	});
+
+	describe("defineLayout with path", () => {
+		it("computes fullPath correctly", () => {
+			const root = createRootLayout({ type: "stack" });
+			const users = defineLayout({
+				type: "stack",
+				path: "users",
+				getParentRoute: () => root,
+			});
+
+			expect(users.fullPath).toBe("/users");
+		});
+
+		it("strips route groups from fullPath", () => {
+			const root = createRootLayout({ type: "stack" });
+			const auth = defineLayout({
+				type: "stack",
+				path: "(auth)",
+				getParentRoute: () => root,
+			});
+			const login = defineScreen({
+				path: "login",
+				getParentRoute: () => auth,
+				component: DummyComponent,
+			});
+
+			expect(login.fullPath).toBe("/login");
+		});
+
+		it("chains nested layouts correctly", () => {
+			const root = createRootLayout({ type: "stack" });
+			const users = defineLayout({
+				type: "stack",
+				path: "users",
+				getParentRoute: () => root,
+			});
+			const settings = defineLayout({
+				type: "tabs",
+				path: "settings",
+				getParentRoute: () => users,
+			});
+
+			expect(settings.fullPath).toBe("/users/settings");
+		});
+	});
+
+	describe("defineScreen with path", () => {
+		it("computes fullPath from parent chain", () => {
+			const root = createRootLayout({ type: "stack" });
+			const users = defineLayout({
+				type: "stack",
+				path: "users",
+				getParentRoute: () => root,
+			});
+			const profile = defineScreen({
+				path: "[userId]",
+				getParentRoute: () => users,
+				component: DummyComponent,
+			});
+
+			expect(profile.fullPath).toBe("/users/[userId]");
+		});
+
+		it("creates screen without parent at root", () => {
+			const home = defineScreen({
+				path: "home",
+				component: DummyComponent,
+			});
+
+			expect(home.fullPath).toBe("/home");
+		});
+
+		it("handles nested params correctly", () => {
+			const root = createRootLayout({ type: "stack" });
+			const users = defineLayout({
+				type: "stack",
+				path: "users/[userId]",
+				getParentRoute: () => root,
+			});
+			const posts = defineScreen({
+				path: "posts/[postId]",
+				getParentRoute: () => users,
+				component: DummyComponent,
+			});
+
+			expect(posts.fullPath).toBe("/users/[userId]/posts/[postId]");
+		});
+	});
+
+	describe("addChildren", () => {
+		it("returns new layout with children", () => {
+			const root = createRootLayout({ type: "stack" });
+			const screen1 = defineScreen({ path: "a", component: DummyComponent });
+			const screen2 = defineScreen({ path: "b", component: DummyComponent });
+
+			const withChildren = root.addChildren([screen1, screen2]);
+
+			expect(withChildren.children).toHaveLength(2);
+			expect(withChildren.children[0].path).toBe("a");
+			expect(withChildren.children[1].path).toBe("b");
+		});
+
+		it("preserves original layout properties", () => {
+			const root = createRootLayout({
+				type: "tabs",
+				screenOptions: { headerShown: false },
+			});
+			const screen = defineScreen({ path: "home", component: DummyComponent });
+
+			const withChildren = root.addChildren([screen]);
+
+			expect(withChildren.type).toBe("tabs");
+			expect(withChildren.screenOptions).toEqual({ headerShown: false });
+		});
+
+		it("supports nested addChildren", () => {
+			const root = createRootLayout({ type: "stack" });
+			const usersLayout = defineLayout({
+				type: "stack",
+				path: "users",
+				getParentRoute: () => root,
+			});
+			const profile = defineScreen({
+				path: "[userId]",
+				getParentRoute: () => usersLayout,
+				component: DummyComponent,
+			});
+
+			const tree = root.addChildren([usersLayout.addChildren([profile])]);
+
+			expect(tree.children).toHaveLength(1);
+			expect((tree.children[0] as typeof usersLayout).children).toHaveLength(1);
+		});
+	});
+
+	describe("createRouteTree", () => {
+		it("creates a route tree from root", () => {
+			const root = createRootLayout({ type: "stack" });
+			const home = defineScreen({ path: "home", component: DummyComponent });
+
+			const tree = createRouteTree({
+				root: root.addChildren([home]),
+			});
+
+			expect(tree.root).toBeDefined();
+			expect(Array.isArray(tree.routePaths)).toBe(true);
+		});
+
+		it("validates no duplicate paths", () => {
+			const root = createRootLayout({ type: "stack" });
+			const screen1 = defineScreen({ path: "same", component: DummyComponent });
+			const screen2 = defineScreen({ path: "same", component: DummyComponent });
+
+			expect(() => {
+				createRouteTree({ root: root.addChildren([screen1, screen2]) });
+			}).toThrow("Duplicate route path");
+		});
+
+		it("extracts all route paths", () => {
+			const root = createRootLayout({ type: "stack" });
+			const home = defineScreen({ path: "home", component: DummyComponent });
+			const about = defineScreen({ path: "about", component: DummyComponent });
+
+			const tree = createRouteTree({
+				root: root.addChildren([home, about]),
+			});
+
+			const paths = tree.routePaths as string[];
+			expect(paths).toContain("/");
+			expect(paths).toContain("/home");
+			expect(paths).toContain("/about");
+		});
+	});
+
+	describe("flattenRouteTree", () => {
+		it("flattens nested route tree", () => {
+			const root = createRootLayout({ type: "stack" });
+			const usersLayout = defineLayout({
+				type: "stack",
+				path: "users",
+				getParentRoute: () => root,
+			});
+			const profile = defineScreen({
+				path: "[userId]",
+				getParentRoute: () => usersLayout,
+				component: DummyComponent,
+			});
+
+			const tree = root.addChildren([usersLayout.addChildren([profile])]);
+			const flat = flattenRouteTree(tree);
+
+			expect(flat.length).toBe(3); // root, usersLayout, profile
+		});
+	});
+
+	describe("scoped hooks", () => {
+		it("provides useParams hook on screen", () => {
+			const screen = defineScreen({
+				path: "[userId]",
+				component: DummyComponent,
+			});
+
+			expect(typeof screen.useParams).toBe("function");
+		});
+
+		it("provides useNavigate hook on screen", () => {
+			const screen = defineScreen({
+				path: "home",
+				component: DummyComponent,
+			});
+
+			expect(typeof screen.useNavigate).toBe("function");
+		});
+
+		it("provides useRouteContext hook on screen", () => {
+			const screen = defineScreen({
+				path: "home",
+				component: DummyComponent,
+			});
+
+			expect(typeof screen.useRouteContext).toBe("function");
+		});
+
+		it("provides hooks on layout", () => {
+			const layout = defineLayout({
+				type: "stack",
+				path: "users",
+			});
+
+			expect(typeof layout.useParams).toBe("function");
+			expect(typeof layout.useNavigate).toBe("function");
+			expect(typeof layout.useRouteContext).toBe("function");
+		});
+	});
+});

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";
 
@@ -121,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
  */
@@ -335,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,
+	};
+}