@teardown/navigation 2.0.80 → 2.0.82

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@teardown/navigation",
-	"version": "2.0.80",
+	"version": "2.0.82",
 	"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.80",
+		"@teardown/tsconfig": "2.0.82",
 		"@types/react": "19.2.7",
 		"typescript": "5.9.3"
 	}

package/src/hooks/index.ts

@@ -2,6 +2,20 @@
  * Hooks for @teardown/navigation
  */
 
+// Scoped hooks (for route-builder pattern)
+export {
+	areScopedHooksInitialized,
+	clearRouteContext,
+	createScopedUseContext,
+	createScopedUseNavigate,
+	createScopedUseParams,
+	getRouteContext,
+	getUseNavigation,
+	getUseRoute,
+	initializeScopedHooks,
+	resetScopedHooks,
+	setRouteContext,
+} from "./scoped-hooks";
 // Navigation hooks
 export {
 	createTypedNavigation,

package/src/hooks/scoped-hooks.ts

@@ -0,0 +1,125 @@
+/**
+ * Scoped hook factories for @teardown/navigation
+ * Creates hooks that capture route context at definition time
+ */
+
+import type { TypedNavigation } from "./use-typed-navigation";
+
+// React Native global for dev mode check
+declare const __DEV__: boolean;
+
+// Will be injected by createTeardownRouter
+let _useRoute: (() => { params?: object; name?: string }) | null = null;
+let _useNavigation: (() => unknown) | null = null;
+const _routeContextMap: Map<string, unknown> = new Map();
+
+/**
+ * Initialize scoped hooks with React Navigation hooks
+ * Called by createTeardownRouter during setup
+ */
+export function initializeScopedHooks(
+	useRoute: () => { params?: object; name?: string },
+	useNavigation: () => unknown
+): void {
+	_useRoute = useRoute;
+	_useNavigation = useNavigation;
+}
+
+/**
+ * Reset scoped hooks (for testing)
+ */
+export function resetScopedHooks(): void {
+	_useRoute = null;
+	_useNavigation = null;
+	_routeContextMap.clear();
+}
+
+/**
+ * Set route context (called by loader/beforeLoad)
+ */
+export function setRouteContext(fullPath: string, context: unknown): void {
+	_routeContextMap.set(fullPath, context);
+}
+
+/**
+ * Get route context
+ */
+export function getRouteContext<T>(fullPath: string): T {
+	return _routeContextMap.get(fullPath) as T;
+}
+
+/**
+ * Clear route context (called when navigating away)
+ */
+export function clearRouteContext(fullPath: string): void {
+	_routeContextMap.delete(fullPath);
+}
+
+/**
+ * Check if scoped hooks are initialized
+ */
+export function areScopedHooksInitialized(): boolean {
+	return _useRoute !== null && _useNavigation !== null;
+}
+
+/**
+ * Creates a scoped useParams hook that captures fullPath at definition time
+ * Returns params typed for this specific route
+ */
+export function createScopedUseParams<TParams>(fullPath: string): () => TParams {
+	return function useScopedParams(): TParams {
+		if (!_useRoute) {
+			throw new Error("Scoped hooks not initialized. Wrap your app in TeardownRouter or call initializeScopedHooks.");
+		}
+		const route = _useRoute();
+
+		// DEV mode: validate we're on the correct route
+		if (__DEV__ && route.name) {
+			// Could add route name validation here if needed
+			// For now, we trust the type system
+		}
+
+		return (route.params ?? {}) as TParams;
+	};
+}
+
+/**
+ * Creates a scoped useRouteContext hook
+ * Returns context set by this route's loader/beforeLoad
+ */
+export function createScopedUseContext<TContext>(fullPath: string): () => TContext {
+	return function useScopedContext(): TContext {
+		return getRouteContext<TContext>(fullPath);
+	};
+}
+
+/**
+ * Creates a scoped useNavigate hook
+ * Returns typed navigation relative to this route
+ */
+export function createScopedUseNavigate(fullPath: string): () => TypedNavigation {
+	return function useScopedNavigate(): TypedNavigation {
+		if (!_useNavigation) {
+			throw new Error("Scoped hooks not initialized. Wrap your app in TeardownRouter or call initializeScopedHooks.");
+		}
+		const navigation = _useNavigation();
+		// Import dynamically to avoid circular deps
+		// eslint-disable-next-line @typescript-eslint/no-require-imports
+		const { createTypedNavigation } = require("./use-typed-navigation");
+		return createTypedNavigation(navigation, fullPath);
+	};
+}
+
+/**
+ * Get the internal useRoute hook (for advanced usage)
+ */
+export function getUseRoute(): (() => { params?: object; name?: string }) | null {
+	return _useRoute;
+}
+
+/**
+ * Get the internal useNavigation hook (for advanced usage)
+ */
+export function getUseNavigation(): (() => unknown) | null {
+	return _useNavigation;
+}

package/src/index.ts

@@ -6,11 +6,16 @@
 export type { TypedNavigation, TypedRoute } from "./hooks";
 // Hooks
 export {
+	areScopedHooksInitialized,
+	createScopedUseContext,
+	createScopedUseNavigate,
+	createScopedUseParams,
 	createTypedNavigation,
 	createTypedRoute,
 	createUseTypedNavigation,
 	createUseTypedParams,
 	createUseTypedRoute,
+	initializeScopedHooks,
 	useTypedNavigation,
 	useTypedParams,
 	useTypedRoute,
@@ -19,6 +24,10 @@ export type {
 	BaseScreenOptions,
 	DrawerLayoutConfig,
 	DrawerScreenOptions,
+	EnhancedLayoutConfig,
+	EnhancedLayoutDefinition,
+	EnhancedScreenConfig,
+	EnhancedScreenDefinition,
 	InferParamSchemaOutput,
 	LayoutConfig,
 	LayoutDefinition,
@@ -38,10 +47,15 @@ export {
 	createParamSchema,
 	defineLayout,
 	defineScreen,
+	isEnhancedLayoutDefinition,
+	isEnhancedScreenDefinition,
 	isLayoutDefinition,
 	isScreenDefinition,
 	paramValidators,
 } from "./primitives";
+export type { CreateRouteTreeConfig, RootLayoutConfig, RouteTree as BuilderRouteTree } from "./route-builder";
+// Route Builder
+export { createRootLayout, createRouteTree, flattenRouteTree } from "./route-builder";
 // Router
 export type {
 	ExtractRoutePaths,
@@ -51,10 +65,28 @@ export type {
 	NavigatorNode,
 	RouteTree,
 	RouteTreeEntry,
+	RouteTreeRouterOptions,
 	ScreenEntry,
 	TeardownRouterOptions,
 } from "./router";
-export { createTeardownRouter, isFlatRouteTree, isHierarchicalRouteTree } from "./router";
+export {
+	createTeardownRouter,
+	createTeardownRouterFromTree,
+	isFlatRouteTree,
+	isHierarchicalRouteTree,
+} from "./router";
+// Route builder types
+export type {
+	AccumulateParams,
+	AnyRouteDefinition,
+	ComputeFullPath,
+	ExtractRouteParams,
+	ExtractRoutePaths as ExtractRoutePathsFromTree,
+	MergeRouteParams,
+	ParamsForPath,
+	RouteDefinitionBase,
+	StripRouteGroups,
+} from "./types/route-builder-types";
 // Types
 export type {
 	NavigationState,
@@ -74,9 +106,11 @@ export type {
 	InferParams,
 	IsCatchAllSegment,
 	IsDynamicSegment,
+	IsEmptyParams,
 	IsOptionalSegment,
 	NavigateArgs,
 	Simplify,
+	ToReactNavigationPath,
 } from "./types/type-utils";
 export type { MatchResult, ParsedPath } from "./utils";
 // Utils

package/src/primitives/define-layout.ts

@@ -4,6 +4,15 @@
  */
 
 import type { ComponentType } from "react";
+import { createScopedUseContext, createScopedUseNavigate, createScopedUseParams } from "../hooks/scoped-hooks";
+import type { TypedNavigation } from "../hooks/use-typed-navigation";
+import type {
+	AccumulateParams,
+	AnyRouteDefinition,
+	ComputeFullPath,
+	RouteDefinitionBase,
+} from "../types/route-builder-types";
+import type { InferParams } from "../types/type-utils";
 
 /**
  * Navigator types supported by the library
@@ -135,14 +144,86 @@ export interface DrawerLayoutConfig extends BaseLayoutConfig {
 export type LayoutConfig = StackLayoutConfig | TabsLayoutConfig | DrawerLayoutConfig;
 
 /**
- * Brand type for layout definitions
+ * Brand type for layout definitions (legacy)
  */
 export type LayoutDefinition<T extends LayoutConfig = LayoutConfig> = T & {
 	__brand: "TeardownLayout";
 };
 
 /**
- * Defines a layout with type-safe configuration
+ * Enhanced layout configuration with path and parent
+ */
+export interface EnhancedLayoutConfig<
+	TType extends NavigatorType,
+	TPath extends string,
+	TParent extends RouteDefinitionBase | undefined,
+	TContext,
+> {
+	/** Navigator type */
+	type: TType;
+	/** This route segment */
+	path: TPath;
+	/** Links to parent route */
+	getParentRoute?: () => TParent;
+	/** Default screen options for children */
+	screenOptions?: object;
+	/** Initial route name */
+	initialRouteName?: string;
+	/** Async loader */
+	loader?: () => TContext | Promise<TContext>;
+	/** Custom tab bar (tabs only) */
+	tabBar?: ComponentType;
+	/** Custom drawer content (drawer only) */
+	drawerContent?: ComponentType;
+}
+
+/**
+ * Enhanced layout definition with addChildren
+ */
+export interface EnhancedLayoutDefinition<
+	TType extends NavigatorType,
+	TPath extends string,
+	TFullPath extends string,
+	TParams,
+	TAllParams,
+	TContext,
+	TChildren extends readonly AnyRouteDefinition[] = readonly [],
+> extends RouteDefinitionBase<TPath, TFullPath, TParams, TAllParams, TContext> {
+	__brand: "TeardownLayout";
+	type: TType;
+	screenOptions?: object;
+	initialRouteName?: string;
+	loader?: () => TContext | Promise<TContext>;
+	children: TChildren;
+
+	/** Add children routes - returns new layout with updated type */
+	addChildren<TNewChildren extends readonly AnyRouteDefinition[]>(
+		children: TNewChildren
+	): EnhancedLayoutDefinition<TType, TPath, TFullPath, TParams, TAllParams, TContext, TNewChildren>;
+
+	/** Scoped hooks */
+	useParams: () => TAllParams;
+	useRouteContext: () => TContext;
+	useNavigate: () => TypedNavigation;
+}
+
+/**
+ * Runtime full path computation
+ */
+function computeFullPathRuntime<TPath extends string, TParent>(path: TPath, parent?: TParent): string {
+	const cleanPath = path.replace(/\(([^)]+)\)\/?/g, "");
+
+	if (!parent || !(parent as Record<string, unknown>).fullPath) {
+		return cleanPath ? `/${cleanPath}` : "/";
+	}
+
+	const parentPath = (parent as Record<string, unknown>).fullPath as string;
+	if (!cleanPath) return parentPath;
+	return parentPath === "/" ? `/${cleanPath}` : `${parentPath}/${cleanPath}`;
+}
+
+/**
+ * Defines a layout with type-safe configuration (legacy API)
  *
  * @example
  * ```tsx
@@ -176,11 +257,90 @@ export type LayoutDefinition<T extends LayoutConfig = LayoutConfig> = T & {
  * });
  * ```
  */
-export function defineLayout<T extends LayoutConfig>(config: T): LayoutDefinition<T> {
+export function defineLayout<T extends LayoutConfig>(config: T): LayoutDefinition<T>;
+
+/**
+ * Defines a layout with enhanced type-safe configuration
+ *
+ * @example
+ * ```tsx
+ * const usersLayout = defineLayout({
+ *   type: 'stack',
+ *   path: 'users',
+ *   getParentRoute: () => rootLayout,
+ * });
+ *
+ * // Use addChildren to add screens
+ * const routeTree = usersLayout.addChildren([userProfile, userSettings]);
+ * ```
+ */
+export function defineLayout<
+	TType extends NavigatorType,
+	TPath extends string,
+	TParent extends RouteDefinitionBase | undefined = undefined,
+	TContext = unknown,
+>(
+	config: EnhancedLayoutConfig<TType, TPath, TParent, TContext>
+): EnhancedLayoutDefinition<
+	TType,
+	TPath,
+	ComputeFullPath<TPath, TParent>,
+	InferParams<TPath>,
+	AccumulateParams<TPath, TParent>,
+	TContext
+>;
+
+// Implementation
+export function defineLayout<
+	T extends LayoutConfig = LayoutConfig,
+	TType extends NavigatorType = NavigatorType,
+	TPath extends string = string,
+	TParent extends RouteDefinitionBase | undefined = undefined,
+	TContext = unknown,
+>(
+	config: T | EnhancedLayoutConfig<TType, TPath, TParent, TContext>
+): LayoutDefinition<T> | EnhancedLayoutDefinition<TType, TPath, string, unknown, unknown, TContext> {
+	// Check if this is an enhanced config (has 'path' property)
+	if ("path" in config && typeof config.path === "string") {
+		const enhancedConfig = config as EnhancedLayoutConfig<TType, TPath, TParent, TContext>;
+		const parent = enhancedConfig.getParentRoute?.();
+		const fullPath = computeFullPathRuntime(enhancedConfig.path, parent);
+
+		const layout: EnhancedLayoutDefinition<TType, TPath, string, unknown, unknown, TContext> = {
+			__brand: "TeardownLayout" as const,
+			type: enhancedConfig.type,
+			path: enhancedConfig.path,
+			fullPath: fullPath,
+			params: {} as InferParams<TPath>,
+			allParams: {} as AccumulateParams<TPath, TParent>,
+			context: {} as TContext,
+			screenOptions: enhancedConfig.screenOptions,
+			initialRouteName: enhancedConfig.initialRouteName,
+			loader: enhancedConfig.loader,
+			children: [] as const,
+
+			// addChildren returns new layout with children attached
+			addChildren(children) {
+				return {
+					...this,
+					children,
+				} as EnhancedLayoutDefinition<TType, TPath, string, unknown, unknown, TContext, typeof children>;
+			},
+
+			// Scoped hooks
+			useParams: createScopedUseParams(fullPath),
+			useRouteContext: createScopedUseContext(fullPath),
+			useNavigate: createScopedUseNavigate(fullPath),
+		};
+
+		return layout;
+	}
+
+	// Legacy API
 	return {
-		...config,
+		...(config as T),
 		__brand: "TeardownLayout" as const,
-	};
+	} as LayoutDefinition<T>;
 }
 
 /**
@@ -189,3 +349,17 @@ export function defineLayout<T extends LayoutConfig>(config: T): LayoutDefinitio
 export function isLayoutDefinition(value: unknown): value is LayoutDefinition {
 	return typeof value === "object" && value !== null && (value as LayoutDefinition).__brand === "TeardownLayout";
 }
+
+/**
+ * Type guard to check if a value is an enhanced layout definition
+ */
+export function isEnhancedLayoutDefinition(
+	value: unknown
+): value is EnhancedLayoutDefinition<NavigatorType, string, string, unknown, unknown, unknown> {
+	return (
+		isLayoutDefinition(value) &&
+		"fullPath" in value &&
+		"addChildren" in value &&
+		typeof (value as Record<string, unknown>).addChildren === "function"
+	);
+}

package/src/primitives/define-screen.ts

@@ -4,6 +4,10 @@
  */
 
 import type { ComponentType } from "react";
+import { createScopedUseContext, createScopedUseNavigate, createScopedUseParams } from "../hooks/scoped-hooks";
+import type { TypedNavigation } from "../hooks/use-typed-navigation";
+import type { AccumulateParams, ComputeFullPath, RouteDefinitionBase } from "../types/route-builder-types";
+import type { InferParams } from "../types/type-utils";
 
 /**
  * Screen options that can be passed to React Navigation
@@ -52,7 +56,7 @@ export interface ScreenOptions {
 }
 
 /**
- * Screen configuration
+ * Screen configuration (legacy)
  */
 export interface ScreenConfig<TParams = unknown> {
 	/**
@@ -82,14 +86,69 @@ export interface ScreenConfig<TParams = unknown> {
 }
 
 /**
- * Brand type for screen definitions
+ * Brand type for screen definitions (legacy)
  */
 export interface ScreenDefinition<TParams = unknown> extends ScreenConfig<TParams> {
 	__brand: "TeardownScreen";
 }
 
 /**
- * Defines a screen with type-safe configuration
+ * Enhanced screen configuration with path and parent
+ */
+export interface EnhancedScreenConfig<TPath extends string, TParent extends RouteDefinitionBase | undefined, TContext> {
+	/** This route segment (e.g., "[userId]") */
+	path: TPath;
+	/** Links to parent route for path computation */
+	getParentRoute?: () => TParent;
+	/** Component to render */
+	component: ComponentType;
+	/** Navigation options */
+	options?: ScreenOptions | ((props: { route: unknown; navigation: unknown }) => ScreenOptions);
+	/** Async loader - returns context for this route */
+	loader?: () => TContext | Promise<TContext>;
+	/** Navigation event listeners */
+	listeners?: {
+		focus?: () => void;
+		blur?: () => void;
+		beforeRemove?: (e: { preventDefault: () => void }) => void;
+	};
+}
+
+/**
+ * Enhanced screen definition with scoped hooks
+ */
+export interface EnhancedScreenDefinition<TPath extends string, TFullPath extends string, TParams, TAllParams, TContext>
+	extends RouteDefinitionBase<TPath, TFullPath, TParams, TAllParams, TContext> {
+	__brand: "TeardownScreen";
+	component: ComponentType;
+	options?: ScreenOptions | ((props: unknown) => ScreenOptions);
+	loader?: () => TContext | Promise<TContext>;
+	listeners?: object;
+
+	/** Scoped hooks - auto-infer types! */
+	useParams: () => TAllParams;
+	useRouteContext: () => TContext;
+	useNavigate: () => TypedNavigation;
+}
+
+/**
+ * Runtime full path computation
+ */
+function computeFullPathRuntime<TPath extends string, TParent>(path: TPath, parent?: TParent): string {
+	// Strip route groups
+	const cleanPath = path.replace(/\(([^)]+)\)\/?/g, "");
+
+	if (!parent || !(parent as Record<string, unknown>).fullPath) {
+		return cleanPath ? `/${cleanPath}` : "/";
+	}
+
+	const parentPath = (parent as Record<string, unknown>).fullPath as string;
+	if (!cleanPath) return parentPath;
+	return parentPath === "/" ? `/${cleanPath}` : `${parentPath}/${cleanPath}`;
+}
+
+/**
+ * Defines a screen with type-safe configuration (legacy API)
  *
  * @example
  * ```tsx
@@ -108,9 +167,75 @@ export interface ScreenDefinition<TParams = unknown> extends ScreenConfig<TParam
  * });
  * ```
  */
-export function defineScreen<TParams = unknown>(config: ScreenConfig<TParams>): ScreenDefinition<TParams> {
+export function defineScreen<TParams = unknown>(config: ScreenConfig<TParams>): ScreenDefinition<TParams>;
+
+/**
+ * Defines a screen with enhanced type-safe configuration
+ *
+ * @example
+ * ```tsx
+ * const userProfile = defineScreen({
+ *   path: '[userId]',
+ *   getParentRoute: () => usersLayout,
+ *   component: UserProfile,
+ * });
+ *
+ * // In component:
+ * const { userId } = userProfile.useParams(); // Typed!
+ * ```
+ */
+export function defineScreen<
+	TPath extends string,
+	TParent extends RouteDefinitionBase | undefined = undefined,
+	TContext = unknown,
+>(
+	config: EnhancedScreenConfig<TPath, TParent, TContext>
+): EnhancedScreenDefinition<
+	TPath,
+	ComputeFullPath<TPath, TParent>,
+	InferParams<TPath>,
+	AccumulateParams<TPath, TParent>,
+	TContext
+>;
+
+// Implementation
+export function defineScreen<
+	TPath extends string = string,
+	TParent extends RouteDefinitionBase | undefined = undefined,
+	TContext = unknown,
+	TParams = unknown,
+>(
+	config: ScreenConfig<TParams> | EnhancedScreenConfig<TPath, TParent, TContext>
+): ScreenDefinition<TParams> | EnhancedScreenDefinition<TPath, string, unknown, unknown, TContext> {
+	// Check if this is an enhanced config (has 'path' property)
+	if ("path" in config && typeof config.path === "string") {
+		const enhancedConfig = config as EnhancedScreenConfig<TPath, TParent, TContext>;
+		const parent = enhancedConfig.getParentRoute?.();
+		const fullPath = computeFullPathRuntime(enhancedConfig.path, parent);
+
+		return {
+			__brand: "TeardownScreen" as const,
+			path: enhancedConfig.path,
+			fullPath: fullPath as ComputeFullPath<TPath, TParent>,
+			params: {} as InferParams<TPath>,
+			allParams: {} as AccumulateParams<TPath, TParent>,
+			context: {} as TContext,
+			component: enhancedConfig.component,
+			options: enhancedConfig.options,
+			loader: enhancedConfig.loader,
+			listeners: enhancedConfig.listeners,
+
+			// Scoped hooks
+			useParams: createScopedUseParams<AccumulateParams<TPath, TParent>>(fullPath),
+			useRouteContext: createScopedUseContext<TContext>(fullPath),
+			useNavigate: createScopedUseNavigate(fullPath),
+		} as EnhancedScreenDefinition<TPath, string, unknown, unknown, TContext>;
+	}
+
+	// Legacy API
+	const legacyConfig = config as ScreenConfig<TParams>;
 	return {
-		...config,
+		...legacyConfig,
 		__brand: "TeardownScreen" as const,
 	};
 }
@@ -121,3 +246,17 @@ export function defineScreen<TParams = unknown>(config: ScreenConfig<TParams>):
 export function isScreenDefinition(value: unknown): value is ScreenDefinition {
 	return typeof value === "object" && value !== null && (value as ScreenDefinition).__brand === "TeardownScreen";
 }
+
+/**
+ * Type guard to check if a value is an enhanced screen definition
+ */
+export function isEnhancedScreenDefinition(
+	value: unknown
+): value is EnhancedScreenDefinition<string, string, unknown, unknown, unknown> {
+	return (
+		isScreenDefinition(value) &&
+		"fullPath" in value &&
+		"useParams" in value &&
+		typeof (value as Record<string, unknown>).useParams === "function"
+	);
+}

package/src/primitives/index.ts

@@ -17,6 +17,9 @@ export {
 	type DrawerLayoutConfig,
 	type DrawerScreenOptions,
 	defineLayout,
+	type EnhancedLayoutConfig,
+	type EnhancedLayoutDefinition,
+	isEnhancedLayoutDefinition,
 	isLayoutDefinition,
 	type LayoutConfig,
 	type LayoutDefinition,
@@ -30,6 +33,9 @@ export {
 // Screen definitions
 export {
 	defineScreen,
+	type EnhancedScreenConfig,
+	type EnhancedScreenDefinition,
+	isEnhancedScreenDefinition,
 	isScreenDefinition,
 	type ScreenConfig,
 	type ScreenDefinition,