@teardown/navigation 2.0.43

package/src/primitives/create-param-schema.ts

@@ -0,0 +1,243 @@
+/**
+ * Param schema utilities for @teardown/navigation
+ * Provides helpers for creating Zod schemas for route params
+ */
+
+/**
+ * Basic param schema interface (Zod-like)
+ * This allows the library to work without Zod as a hard dependency
+ */
+export interface ParamSchema<T = unknown> {
+	parse: (value: unknown) => T;
+	safeParse: (value: unknown) => { success: true; data: T } | { success: false; error: unknown };
+}
+
+/**
+ * Shape type for defining param schemas
+ */
+export type ParamSchemaShape = Record<string, ParamSchema>;
+
+/**
+ * Infer the output type from a param schema shape
+ */
+export type InferParamSchemaOutput<T extends ParamSchemaShape> = {
+	[K in keyof T]: T[K] extends ParamSchema<infer U> ? U : unknown;
+};
+
+/**
+ * Creates a param schema object from a shape definition
+ * This is a lightweight wrapper that validates params at runtime
+ *
+ * @example
+ * ```ts
+ * // With Zod (recommended)
+ * import { z } from 'zod';
+ * import { createParamSchema } from '@teardown/navigation/primitives';
+ *
+ * export const paramsSchema = createParamSchema({
+ *   userId: z.string().uuid(),
+ *   tab: z.enum(['posts', 'comments', 'likes']),
+ * });
+ *
+ * // Without Zod (basic validation)
+ * import { createParamSchema, paramValidators } from '@teardown/navigation/primitives';
+ *
+ * export const paramsSchema = createParamSchema({
+ *   userId: paramValidators.uuid(),
+ *   page: paramValidators.numericId(),
+ * });
+ * ```
+ */
+export function createParamSchema<T extends ParamSchemaShape>(
+	shape: T
+): ParamSchema<InferParamSchemaOutput<T>> & { shape: T } {
+	return {
+		shape,
+		parse(value: unknown) {
+			if (typeof value !== "object" || value === null) {
+				throw new Error("Expected object for params");
+			}
+
+			const input = value as Record<string, unknown>;
+			const result: Record<string, unknown> = {};
+
+			for (const [key, schema] of Object.entries(shape)) {
+				result[key] = schema.parse(input[key]);
+			}
+
+			return result as InferParamSchemaOutput<T>;
+		},
+		safeParse(value: unknown) {
+			try {
+				const data = this.parse(value);
+				return { success: true, data };
+			} catch (error) {
+				return { success: false, error };
+			}
+		},
+	};
+}
+
+/**
+ * Common param validators for use without Zod
+ * These provide basic validation for common param patterns
+ */
+export const paramValidators = {
+	/**
+	 * String validator
+	 */
+	string(): ParamSchema<string> {
+		return {
+			parse(value: unknown) {
+				if (typeof value !== "string") {
+					throw new Error(`Expected string, got ${typeof value}`);
+				}
+				return value;
+			},
+			safeParse(value: unknown) {
+				try {
+					const data = this.parse(value);
+					return { success: true, data };
+				} catch (error) {
+					return { success: false, error };
+				}
+			},
+		};
+	},
+
+	/**
+	 * UUID string validator
+	 */
+	uuid(): ParamSchema<string> {
+		const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+		return {
+			parse(value: unknown) {
+				if (typeof value !== "string" || !uuidRegex.test(value)) {
+					throw new Error("Expected valid UUID string");
+				}
+				return value;
+			},
+			safeParse(value: unknown) {
+				try {
+					const data = this.parse(value);
+					return { success: true, data };
+				} catch (error) {
+					return { success: false, error };
+				}
+			},
+		};
+	},
+
+	/**
+	 * Numeric string that parses to integer
+	 */
+	numericId(): ParamSchema<number> {
+		return {
+			parse(value: unknown) {
+				if (typeof value !== "string" || !/^\d+$/.test(value)) {
+					throw new Error("Expected numeric string");
+				}
+				return Number.parseInt(value, 10);
+			},
+			safeParse(value: unknown) {
+				try {
+					const data = this.parse(value);
+					return { success: true, data };
+				} catch (error) {
+					return { success: false, error };
+				}
+			},
+		};
+	},
+
+	/**
+	 * Slug-friendly string (lowercase letters, numbers, hyphens)
+	 */
+	slug(): ParamSchema<string> {
+		return {
+			parse(value: unknown) {
+				if (typeof value !== "string" || !/^[a-z0-9-]+$/.test(value)) {
+					throw new Error("Expected slug string (lowercase alphanumeric with hyphens)");
+				}
+				return value;
+			},
+			safeParse(value: unknown) {
+				try {
+					const data = this.parse(value);
+					return { success: true, data };
+				} catch (error) {
+					return { success: false, error };
+				}
+			},
+		};
+	},
+
+	/**
+	 * Optional string with default
+	 */
+	optionalWithDefault(defaultValue: string): ParamSchema<string> {
+		return {
+			parse(value: unknown) {
+				if (value === undefined || value === null || value === "") {
+					return defaultValue;
+				}
+				if (typeof value !== "string") {
+					throw new Error(`Expected string, got ${typeof value}`);
+				}
+				return value;
+			},
+			safeParse(value: unknown) {
+				try {
+					const data = this.parse(value);
+					return { success: true, data };
+				} catch (error) {
+					return { success: false, error };
+				}
+			},
+		};
+	},
+
+	/**
+	 * Enum-like string (one of specified values)
+	 */
+	oneOf<T extends string>(values: readonly T[]): ParamSchema<T> {
+		return {
+			parse(value: unknown) {
+				if (typeof value !== "string" || !values.includes(value as T)) {
+					throw new Error(`Expected one of: ${values.join(", ")}`);
+				}
+				return value as T;
+			},
+			safeParse(value: unknown) {
+				try {
+					const data = this.parse(value);
+					return { success: true, data };
+				} catch (error) {
+					return { success: false, error };
+				}
+			},
+		};
+	},
+
+	/**
+	 * Array of strings (for catch-all routes)
+	 */
+	stringArray(): ParamSchema<string[]> {
+		return {
+			parse(value: unknown) {
+				if (!Array.isArray(value) || !value.every((v) => typeof v === "string")) {
+					throw new Error("Expected array of strings");
+				}
+				return value as string[];
+			},
+			safeParse(value: unknown) {
+				try {
+					const data = this.parse(value);
+					return { success: true, data };
+				} catch (error) {
+					return { success: false, error };
+				}
+			},
+		};
+	},
+};

package/src/primitives/define-layout.ts

@@ -0,0 +1,191 @@
+/**
+ * defineLayout primitive for @teardown/navigation
+ * Defines navigator configuration for a route group
+ */
+
+import type { ComponentType } from "react";
+
+/**
+ * Navigator types supported by the library
+ */
+export type NavigatorType = "stack" | "tabs" | "drawer";
+
+/**
+ * Common screen options for all navigator types
+ */
+export interface BaseScreenOptions {
+	headerShown?: boolean;
+	title?: string;
+	[key: string]: unknown;
+}
+
+/**
+ * Stack navigator specific options
+ */
+export interface StackScreenOptions extends BaseScreenOptions {
+	presentation?:
+		| "card"
+		| "modal"
+		| "transparentModal"
+		| "containedModal"
+		| "containedTransparentModal"
+		| "fullScreenModal"
+		| "formSheet";
+	animation?:
+		| "default"
+		| "fade"
+		| "fade_from_bottom"
+		| "flip"
+		| "simple_push"
+		| "slide_from_bottom"
+		| "slide_from_right"
+		| "slide_from_left"
+		| "none";
+	gestureEnabled?: boolean;
+	gestureDirection?: "horizontal" | "vertical";
+	headerBackTitleVisible?: boolean;
+}
+
+/**
+ * Tab navigator specific options
+ */
+export interface TabScreenOptions extends BaseScreenOptions {
+	tabBarActiveTintColor?: string;
+	tabBarInactiveTintColor?: string;
+	tabBarStyle?: object;
+	tabBarLabelStyle?: object;
+	tabBarIconStyle?: object;
+	tabBarShowLabel?: boolean;
+	tabBarHideOnKeyboard?: boolean;
+	lazy?: boolean;
+}
+
+/**
+ * Drawer navigator specific options
+ */
+export interface DrawerScreenOptions extends BaseScreenOptions {
+	drawerActiveTintColor?: string;
+	drawerInactiveTintColor?: string;
+	drawerStyle?: object;
+	drawerLabelStyle?: object;
+	drawerPosition?: "left" | "right";
+	drawerType?: "front" | "back" | "slide" | "permanent";
+	swipeEnabled?: boolean;
+}
+
+/**
+ * Per-screen options that can be specified in the layout
+ */
+export interface PerScreenOptions {
+	tabBarIcon?: (props: { focused: boolean; color: string; size: number }) => React.ReactNode;
+	tabBarLabel?: string;
+	tabBarBadge?: string | number;
+	drawerIcon?: (props: { focused: boolean; color: string; size: number }) => React.ReactNode;
+	drawerLabel?: string;
+	[key: string]: unknown;
+}
+
+/**
+ * Base layout configuration
+ */
+interface BaseLayoutConfig {
+	type: NavigatorType;
+	initialRouteName?: string;
+}
+
+/**
+ * Stack layout configuration
+ */
+export interface StackLayoutConfig extends BaseLayoutConfig {
+	type: "stack";
+	screenOptions?: StackScreenOptions;
+}
+
+/**
+ * Tab layout configuration
+ */
+export interface TabsLayoutConfig extends BaseLayoutConfig {
+	type: "tabs";
+	screenOptions?: TabScreenOptions;
+	tabBar?: ComponentType<{
+		state: unknown;
+		descriptors: unknown;
+		navigation: unknown;
+	}>;
+	screens?: Record<string, Partial<PerScreenOptions>>;
+}
+
+/**
+ * Drawer layout configuration
+ */
+export interface DrawerLayoutConfig extends BaseLayoutConfig {
+	type: "drawer";
+	screenOptions?: DrawerScreenOptions;
+	drawerContent?: ComponentType<{
+		state: unknown;
+		navigation: unknown;
+		descriptors: unknown;
+	}>;
+	screens?: Record<string, Partial<PerScreenOptions>>;
+}
+
+/**
+ * Union of all layout configurations
+ */
+export type LayoutConfig = StackLayoutConfig | TabsLayoutConfig | DrawerLayoutConfig;
+
+/**
+ * Brand type for layout definitions
+ */
+export type LayoutDefinition<T extends LayoutConfig = LayoutConfig> = T & {
+	__brand: "TeardownLayout";
+};
+
+/**
+ * Defines a layout with type-safe configuration
+ *
+ * @example
+ * ```tsx
+ * // Stack layout
+ * import { defineLayout } from '@teardown/navigation/primitives';
+ *
+ * export default defineLayout({
+ *   type: 'stack',
+ *   screenOptions: {
+ *     headerShown: true,
+ *     headerBackTitleVisible: false,
+ *   },
+ * });
+ *
+ * // Tabs layout
+ * export default defineLayout({
+ *   type: 'tabs',
+ *   screenOptions: {
+ *     tabBarActiveTintColor: '#007AFF',
+ *   },
+ *   screens: {
+ *     home: {
+ *       tabBarIcon: ({ color }) => <HomeIcon color={color} />,
+ *       tabBarLabel: 'Home',
+ *     },
+ *     settings: {
+ *       tabBarIcon: ({ color }) => <SettingsIcon color={color} />,
+ *       tabBarLabel: 'Settings',
+ *     },
+ *   },
+ * });
+ * ```
+ */
+export function defineLayout<T extends LayoutConfig>(config: T): LayoutDefinition<T> {
+	return {
+		...config,
+		__brand: "TeardownLayout" as const,
+	};
+}
+
+/**
+ * Type guard to check if a value is a layout definition
+ */
+export function isLayoutDefinition(value: unknown): value is LayoutDefinition {
+	return typeof value === "object" && value !== null && (value as LayoutDefinition).__brand === "TeardownLayout";
+}

package/src/primitives/define-screen.ts

@@ -0,0 +1,123 @@
+/**
+ * defineScreen primitive for @teardown/navigation
+ * Defines a screen component with type-safe configuration
+ */
+
+import type { ComponentType } from "react";
+
+/**
+ * Screen options that can be passed to React Navigation
+ */
+export interface ScreenOptions {
+	title?: string;
+	headerShown?: boolean;
+	headerTitle?: string | (() => React.ReactNode);
+	headerLeft?: () => React.ReactNode;
+	headerRight?: () => React.ReactNode;
+	headerStyle?: object;
+	headerTitleStyle?: object;
+	headerBackTitle?: string;
+	headerBackTitleVisible?: boolean;
+	presentation?:
+		| "card"
+		| "modal"
+		| "transparentModal"
+		| "containedModal"
+		| "containedTransparentModal"
+		| "fullScreenModal"
+		| "formSheet";
+	animation?:
+		| "default"
+		| "fade"
+		| "fade_from_bottom"
+		| "flip"
+		| "simple_push"
+		| "slide_from_bottom"
+		| "slide_from_right"
+		| "slide_from_left"
+		| "none";
+	gestureEnabled?: boolean;
+	gestureDirection?: "horizontal" | "vertical";
+	animationDuration?: number;
+	// Tab bar options
+	tabBarLabel?: string;
+	tabBarIcon?: (props: { focused: boolean; color: string; size: number }) => React.ReactNode;
+	tabBarBadge?: string | number;
+	tabBarButton?: (props: object) => React.ReactNode;
+	// Drawer options
+	drawerLabel?: string;
+	drawerIcon?: (props: { focused: boolean; color: string; size: number }) => React.ReactNode;
+	// Allow additional custom options
+	[key: string]: unknown;
+}
+
+/**
+ * Screen configuration
+ */
+export interface ScreenConfig<TParams = unknown> {
+	/**
+	 * The React component to render for this screen
+	 */
+	component: ComponentType;
+
+	/**
+	 * Navigation options for this screen
+	 */
+	options?: ScreenOptions | ((props: { route: { params?: TParams }; navigation: unknown }) => ScreenOptions);
+
+	/**
+	 * Optional param schema for runtime validation
+	 * Should be a Zod schema
+	 */
+	params?: TParams;
+
+	/**
+	 * Listeners for navigation events
+	 */
+	listeners?: {
+		focus?: () => void;
+		blur?: () => void;
+		beforeRemove?: (e: { preventDefault: () => void }) => void;
+	};
+}
+
+/**
+ * Brand type for screen definitions
+ */
+export interface ScreenDefinition<TParams = unknown> extends ScreenConfig<TParams> {
+	__brand: "TeardownScreen";
+}
+
+/**
+ * Defines a screen with type-safe configuration
+ *
+ * @example
+ * ```tsx
+ * import { defineScreen } from '@teardown/navigation/primitives';
+ *
+ * function UserProfileScreen() {
+ *   return <View><Text>User Profile</Text></View>;
+ * }
+ *
+ * export default defineScreen({
+ *   component: UserProfileScreen,
+ *   options: {
+ *     title: 'User Profile',
+ *     headerShown: true,
+ *   },
+ * });
+ * ```
+ */
+export function defineScreen<TParams = unknown>(config: ScreenConfig<TParams>): ScreenDefinition<TParams> {
+	return {
+		...config,
+		__brand: "TeardownScreen" as const,
+	};
+}
+
+/**
+ * Type guard to check if a value is a screen definition
+ */
+export function isScreenDefinition(value: unknown): value is ScreenDefinition {
+	return typeof value === "object" && value !== null && (value as ScreenDefinition).__brand === "TeardownScreen";
+}

package/src/primitives/index.ts

@@ -0,0 +1,37 @@
+/**
+ * Primitives for @teardown/navigation
+ */
+
+// Param schema utilities
+export {
+	createParamSchema,
+	type InferParamSchemaOutput,
+	type ParamSchema,
+	type ParamSchemaShape,
+	paramValidators,
+} from "./create-param-schema";
+
+// Layout definitions
+export {
+	type BaseScreenOptions,
+	type DrawerLayoutConfig,
+	type DrawerScreenOptions,
+	defineLayout,
+	isLayoutDefinition,
+	type LayoutConfig,
+	type LayoutDefinition,
+	type NavigatorType,
+	type PerScreenOptions,
+	type StackLayoutConfig,
+	type StackScreenOptions,
+	type TabScreenOptions,
+	type TabsLayoutConfig,
+} from "./define-layout";
+// Screen definitions
+export {
+	defineScreen,
+	isScreenDefinition,
+	type ScreenConfig,
+	type ScreenDefinition,
+	type ScreenOptions,
+} from "./define-screen";

package/src/types/index.ts

@@ -0,0 +1,28 @@
+/**
+ * Type utilities and definitions for @teardown/navigation
+ */
+
+// Route type definitions
+export type {
+	NavigationState,
+	NavigatorType,
+	ParamsFor,
+	Register,
+	RegisteredRouteParams,
+	RegisteredRoutePath,
+	RouteConfig,
+	RouteWithParams,
+} from "./route-types";
+// Type utilities for parameter extraction
+export type {
+	ExtractAllParams,
+	ExtractParam,
+	ExtractParamName,
+	HasRequiredParams,
+	InferParams,
+	IsCatchAllSegment,
+	IsDynamicSegment,
+	IsOptionalSegment,
+	NavigateArgs,
+	Simplify,
+} from "./type-utils";

package/src/types/route-types.ts

@@ -0,0 +1,75 @@
+/**
+ * Route type definitions for @teardown/navigation
+ * These types are augmented by the generated types from @teardown/navigation-metro
+ */
+
+/**
+ * Register interface - augmented by generated types
+ * This allows the hooks to infer types without explicit generics
+ *
+ * @example
+ * // In .teardown/register.d.ts (auto-generated)
+ * declare module '@teardown/navigation' {
+ *   interface Register {
+ *     routeParams: RouteParams;
+ *     routePath: RoutePath;
+ *   }
+ * }
+ */
+export interface Register {
+	// These will be augmented by the generated .teardown/register.d.ts
+	routeParams: Record<string, unknown>;
+	routePath: string;
+}
+
+/**
+ * Get the RouteParams from the Register interface
+ */
+export type RegisteredRouteParams = Register["routeParams"];
+
+/**
+ * Get the RoutePath from the Register interface
+ */
+export type RegisteredRoutePath = Register["routePath"];
+
+/**
+ * Get params for a specific route path
+ */
+export type ParamsFor<T extends RegisteredRoutePath> = T extends keyof RegisteredRouteParams
+	? RegisteredRouteParams[T]
+	: undefined;
+
+/**
+ * Union type representing all routes with their params
+ * Useful for creating type-safe route objects
+ */
+export type RouteWithParams = {
+	[K in RegisteredRoutePath]: ParamsFor<K> extends undefined ? { path: K } : { path: K; params: ParamsFor<K> };
+}[RegisteredRoutePath];
+
+/**
+ * Navigator types supported by the library
+ */
+export type NavigatorType = "stack" | "tabs" | "drawer";
+
+/**
+ * Configuration for a single route
+ */
+export interface RouteConfig {
+	path: RegisteredRoutePath;
+	component: React.ComponentType;
+	navigator: NavigatorType;
+	parent?: RegisteredRoutePath;
+}
+
+/**
+ * Navigation state type
+ */
+export interface NavigationState<T extends RegisteredRoutePath = RegisteredRoutePath> {
+	index: number;
+	routes: Array<{
+		name: T;
+		key: string;
+		params?: ParamsFor<T>;
+	}>;
+}