@teardown/navigation 2.0.43

package/package.json

@@ -0,0 +1,79 @@
+{
+	"name": "@teardown/navigation",
+	"version": "2.0.43",
+	"description": "Type-safe file-based navigation for React Native",
+	"private": false,
+	"publishConfig": {
+		"access": "public"
+	},
+	"type": "module",
+	"main": "./src/index.ts",
+	"exports": {
+		".": {
+			"types": "./src/index.ts",
+			"import": "./src/index.ts",
+			"default": "./src/index.ts"
+		},
+		"./hooks": {
+			"types": "./src/hooks/index.ts",
+			"import": "./src/hooks/index.ts",
+			"default": "./src/hooks/index.ts"
+		},
+		"./components": {
+			"types": "./src/components/index.ts",
+			"import": "./src/components/index.ts",
+			"default": "./src/components/index.ts"
+		},
+		"./primitives": {
+			"types": "./src/primitives/index.ts",
+			"import": "./src/primitives/index.ts",
+			"default": "./src/primitives/index.ts"
+		},
+		"./types": {
+			"types": "./src/types/index.ts",
+			"import": "./src/types/index.ts",
+			"default": "./src/types/index.ts"
+		},
+		"./utils": {
+			"types": "./src/utils/index.ts",
+			"import": "./src/utils/index.ts",
+			"default": "./src/utils/index.ts"
+		}
+	},
+	"files": [
+		"src/**/*"
+	],
+	"scripts": {
+		"typecheck": "bun x tsgo --noEmit",
+		"lint": "bun x biome lint --write ./src",
+		"fmt": "bun x biome format --write ./src",
+		"check": "bun x biome check ./src",
+		"test": "bun test"
+	},
+	"peerDependencies": {
+		"@react-navigation/bottom-tabs": ">=7.0.0",
+		"@react-navigation/drawer": ">=7.0.0",
+		"@react-navigation/native": ">=7.0.0",
+		"@react-navigation/native-stack": ">=7.0.0",
+		"react": ">=18.0.0",
+		"react-native": ">=0.72.0",
+		"zod": "4.2.1"
+	},
+	"peerDependenciesMeta": {
+		"@react-navigation/bottom-tabs": {
+			"optional": true
+		},
+		"@react-navigation/drawer": {
+			"optional": true
+		},
+		"zod": {
+			"optional": true
+		}
+	},
+	"devDependencies": {
+		"@biomejs/biome": "2.3.11",
+		"@teardown/tsconfig": "2.0.43",
+		"@types/react": "19.2.7",
+		"typescript": "5.9.3"
+	}
+}

package/src/components/index.ts

@@ -0,0 +1,14 @@
+/**
+ * Components for @teardown/navigation
+ *
+ * Note: These components are placeholders that will work with React Navigation.
+ * Full implementation requires React Navigation to be installed.
+ */
+
+export {};
+
+// Components will be added as the library matures:
+// - NavigationContainer wrapper
+// - TypedLink component
+// - ScreenWrapper
+// - ErrorBoundary

package/src/hooks/index.ts

@@ -0,0 +1,15 @@
+/**
+ * Hooks for @teardown/navigation
+ */
+
+// Navigation hooks
+export {
+	createTypedNavigation,
+	createUseTypedNavigation,
+	type TypedNavigation,
+	useTypedNavigation,
+} from "./use-typed-navigation";
+// Params hooks
+export { createUseTypedParams, useTypedParams } from "./use-typed-params";
+// Route hooks
+export { createTypedRoute, createUseTypedRoute, type TypedRoute, useTypedRoute } from "./use-typed-route";

package/src/hooks/use-typed-navigation.ts

@@ -0,0 +1,195 @@
+/**
+ * useTypedNavigation hook for @teardown/navigation
+ * Provides type-safe navigation functions
+ */
+
+import type { NavigationState, ParamsFor, RegisteredRoutePath } from "../types/route-types";
+import { pathToScreenName } from "../utils/build-url";
+
+/**
+ * Type-safe navigation interface
+ * All methods are fully typed based on the registered route params
+ */
+export interface TypedNavigation {
+	/**
+	 * Navigate to a route
+	 * For routes with params, the params argument is required
+	 * For routes without params, the params argument is optional
+	 */
+	navigate<T extends RegisteredRoutePath>(
+		...args: ParamsFor<T> extends undefined ? [path: T] : [path: T, params: ParamsFor<T>]
+	): void;
+
+	/**
+	 * Push a new screen onto the stack
+	 * Only available in stack navigators
+	 */
+	push<T extends RegisteredRoutePath>(
+		...args: ParamsFor<T> extends undefined ? [path: T] : [path: T, params: ParamsFor<T>]
+	): void;
+
+	/**
+	 * Replace the current screen
+	 * Only available in stack navigators
+	 */
+	replace<T extends RegisteredRoutePath>(
+		...args: ParamsFor<T> extends undefined ? [path: T] : [path: T, params: ParamsFor<T>]
+	): void;
+
+	/**
+	 * Go back to the previous screen
+	 */
+	goBack(): void;
+
+	/**
+	 * Check if there's a screen to go back to
+	 */
+	canGoBack(): boolean;
+
+	/**
+	 * Reset the navigation state
+	 */
+	reset<T extends RegisteredRoutePath>(state: NavigationState<T>): void;
+
+	/**
+	 * Update the params of the current screen
+	 */
+	setParams<T extends RegisteredRoutePath>(params: Partial<ParamsFor<T>>): void;
+
+	/**
+	 * Get the parent navigator (if any)
+	 */
+	getParent(): TypedNavigation | undefined;
+
+	/**
+	 * Check if a route is focused
+	 */
+	isFocused(): boolean;
+}
+
+/**
+ * Creates a typed navigation adapter from a React Navigation instance
+ * This is used internally and should not be called directly in most cases
+ */
+export function createTypedNavigation(navigation: unknown): TypedNavigation {
+	// Cast to any to access React Navigation methods
+	// The type safety comes from our TypedNavigation interface
+	const nav = navigation as {
+		navigate: (name: string, params?: object) => void;
+		push?: (name: string, params?: object) => void;
+		replace?: (name: string, params?: object) => void;
+		goBack: () => void;
+		canGoBack: () => boolean;
+		reset: (state: object) => void;
+		setParams: (params: object) => void;
+		getParent?: () => unknown;
+		isFocused: () => boolean;
+	};
+
+	// Implementation uses runtime types, but TypedNavigation provides compile-time safety
+	const typedNav: TypedNavigation = {
+		navigate(path: string, params?: object) {
+			const screenName = pathToScreenName(path);
+			nav.navigate(screenName, params);
+		},
+
+		push(path: string, params?: object) {
+			const screenName = pathToScreenName(path);
+			if (nav.push) {
+				nav.push(screenName, params);
+			} else {
+				nav.navigate(screenName, params);
+			}
+		},
+
+		replace(path: string, params?: object) {
+			const screenName = pathToScreenName(path);
+			if (nav.replace) {
+				nav.replace(screenName, params);
+			} else {
+				nav.navigate(screenName, params);
+			}
+		},
+
+		goBack() {
+			nav.goBack();
+		},
+
+		canGoBack() {
+			return nav.canGoBack();
+		},
+
+		reset(state: object) {
+			nav.reset(state);
+		},
+
+		setParams(params: object) {
+			nav.setParams(params);
+		},
+
+		getParent() {
+			if (nav.getParent) {
+				const parent = nav.getParent();
+				if (parent) {
+					return createTypedNavigation(parent);
+				}
+			}
+			return undefined;
+		},
+
+		isFocused() {
+			return nav.isFocused();
+		},
+		// Cast to TypedNavigation since the implementation handles the type checking at compile time
+	} as TypedNavigation;
+
+	return typedNav;
+}
+
+/**
+ * Hook to get typed navigation functions
+ * Must be used within a NavigationContainer
+ *
+ * @example
+ * ```tsx
+ * import { useTypedNavigation } from '@teardown/navigation/hooks';
+ *
+ * function MyComponent() {
+ *   const navigation = useTypedNavigation();
+ *
+ *   const handlePress = () => {
+ *     // Fully type-checked!
+ *     navigation.navigate('/users/:userId', { userId: '123' });
+ *   };
+ *
+ *   return <Button onPress={handlePress} title="View User" />;
+ * }
+ * ```
+ */
+export function useTypedNavigation(): TypedNavigation {
+	// This hook needs to be connected to React Navigation's useNavigation
+	// In a real implementation, you would import and use React Navigation's hook:
+	//
+	// import { useNavigation } from '@react-navigation/native';
+	// const navigation = useNavigation();
+	// return createTypedNavigation(navigation);
+	//
+	// For now, we provide the interface and adapter function
+	// The actual hook implementation depends on React Navigation being available
+
+	throw new Error(
+		"useTypedNavigation must be used within a NavigationContainer. " +
+			"Make sure @react-navigation/native is installed and you are within a Navigator."
+	);
+}
+
+/**
+ * Creates a typed navigation hook that can be used with React Navigation
+ * This is a factory function for creating the actual hook
+ */
+export function createUseTypedNavigation(useNavigation: () => unknown): () => TypedNavigation {
+	return function useTypedNavigationImpl(): TypedNavigation {
+		const navigation = useNavigation();
+		return createTypedNavigation(navigation);
+	};
+}

package/src/hooks/use-typed-params.ts

@@ -0,0 +1,46 @@
+/**
+ * useTypedParams hook for @teardown/navigation
+ * Provides type-safe access to route params
+ */
+
+import type { ParamsFor, RegisteredRoutePath } from "../types/route-types";
+
+/**
+ * Hook to get just the route params, typed for the current route
+ *
+ * @example
+ * ```tsx
+ * import { useTypedParams } from '@teardown/navigation/hooks';
+ *
+ * function UserProfileScreen() {
+ *   // Specify the route path for type inference
+ *   const params = useTypedParams<'/users/:userId'>();
+ *
+ *   // params.userId is typed as string
+ *   return <Text>User ID: {params.userId}</Text>;
+ * }
+ * ```
+ */
+export function useTypedParams<T extends RegisteredRoutePath>(): ParamsFor<T> {
+	// This hook needs to be connected to React Navigation's useRoute
+	// In a real implementation:
+	//
+	// import { useRoute } from '@react-navigation/native';
+	// const route = useRoute();
+	// return (route.params ?? {}) as ParamsFor<T>;
+
+	throw new Error(
+		"useTypedParams must be used within a Navigator screen. " +
+			"Make sure @react-navigation/native is installed and you are within a Navigator."
+	);
+}
+
+/**
+ * Creates a typed params hook that can be used with React Navigation
+ */
+export function createUseTypedParams(useRoute: () => unknown): <T extends RegisteredRoutePath>() => ParamsFor<T> {
+	return function useTypedParamsImpl<T extends RegisteredRoutePath>(): ParamsFor<T> {
+		const route = useRoute() as { params?: object };
+		return (route.params ?? {}) as ParamsFor<T>;
+	};
+}

package/src/hooks/use-typed-route.ts

@@ -0,0 +1,83 @@
+/**
+ * useTypedRoute hook for @teardown/navigation
+ * Provides type-safe access to the current route
+ */
+
+import type { ParamsFor, RegisteredRoutePath } from "../types/route-types";
+
+/**
+ * Type-safe route interface
+ */
+export interface TypedRoute<T extends RegisteredRoutePath = RegisteredRoutePath> {
+	/**
+	 * The route path/name
+	 */
+	name: T;
+
+	/**
+	 * The route params (typed based on the route)
+	 */
+	params: ParamsFor<T>;
+
+	/**
+	 * Unique key for this route instance
+	 */
+	key: string;
+}
+
+/**
+ * Creates a typed route object from a React Navigation route
+ */
+export function createTypedRoute<T extends RegisteredRoutePath>(route: unknown): TypedRoute<T> {
+	const r = route as {
+		name: string;
+		params?: object;
+		key: string;
+	};
+
+	return {
+		name: r.name as T,
+		params: (r.params ?? {}) as ParamsFor<T>,
+		key: r.key,
+	};
+}
+
+/**
+ * Hook to get the current route with type-safe params
+ *
+ * @example
+ * ```tsx
+ * import { useTypedRoute } from '@teardown/navigation/hooks';
+ *
+ * function UserProfileScreen() {
+ *   // Specify the route path for type inference
+ *   const route = useTypedRoute<'/users/:userId'>();
+ *
+ *   // params.userId is typed as string
+ *   return <Text>User ID: {route.params.userId}</Text>;
+ * }
+ * ```
+ */
+export function useTypedRoute<T extends RegisteredRoutePath>(): TypedRoute<T> {
+	// This hook needs to be connected to React Navigation's useRoute
+	// In a real implementation:
+	//
+	// import { useRoute } from '@react-navigation/native';
+	// const route = useRoute();
+	// return createTypedRoute<T>(route);
+
+	throw new Error(
+		"useTypedRoute must be used within a Navigator screen. " +
+			"Make sure @react-navigation/native is installed and you are within a Navigator."
+	);
+}
+
+/**
+ * Creates a typed route hook that can be used with React Navigation
+ */
+export function createUseTypedRoute(useRoute: () => unknown): <T extends RegisteredRoutePath>() => TypedRoute<T> {
+	return function useTypedRouteImpl<T extends RegisteredRoutePath>(): TypedRoute<T> {
+		const route = useRoute();
+		return createTypedRoute<T>(route);
+	};
+}

package/src/index.ts

@@ -0,0 +1,70 @@
+/**
+ * @teardown/navigation
+ * Type-safe file-based navigation for React Native
+ */
+
+export type { TypedNavigation, TypedRoute } from "./hooks";
+// Hooks
+export {
+	createTypedNavigation,
+	createTypedRoute,
+	createUseTypedNavigation,
+	createUseTypedParams,
+	createUseTypedRoute,
+	useTypedNavigation,
+	useTypedParams,
+	useTypedRoute,
+} from "./hooks";
+export type {
+	BaseScreenOptions,
+	DrawerLayoutConfig,
+	DrawerScreenOptions,
+	InferParamSchemaOutput,
+	LayoutConfig,
+	LayoutDefinition,
+	ParamSchema,
+	ParamSchemaShape,
+	PerScreenOptions,
+	ScreenConfig,
+	ScreenDefinition,
+	ScreenOptions,
+	StackLayoutConfig,
+	StackScreenOptions,
+	TabScreenOptions,
+	TabsLayoutConfig,
+} from "./primitives";
+// Primitives
+export {
+	createParamSchema,
+	defineLayout,
+	defineScreen,
+	isLayoutDefinition,
+	isScreenDefinition,
+	paramValidators,
+} from "./primitives";
+// Types
+export type {
+	NavigationState,
+	NavigatorType,
+	ParamsFor,
+	Register,
+	RegisteredRouteParams,
+	RegisteredRoutePath,
+	RouteConfig,
+	RouteWithParams,
+} from "./types/route-types";
+export type {
+	ExtractAllParams,
+	ExtractParam,
+	ExtractParamName,
+	HasRequiredParams,
+	InferParams,
+	IsCatchAllSegment,
+	IsDynamicSegment,
+	IsOptionalSegment,
+	NavigateArgs,
+	Simplify,
+} from "./types/type-utils";
+export type { MatchResult, ParsedPath } from "./utils";
+// Utils
+export { buildUrl, matchPath, parsePath, pathToScreenName } from "./utils";