@buzola/router 0.0.1

package/src/engine/types.ts

@@ -0,0 +1,203 @@
+import type { ComponentType, LazyExoticComponent } from 'react'
+
+// ─── Module augmentation interface ──────────────────────────────────────────
+
+/**
+ * Module augmentation point for type-safe page-centric routing.
+ * Vite plugin generates declarations that extend this interface.
+ * Maps page IDs to their params types.
+ */
+// biome-ignore lint/suspicious/noEmptyInterface: declaration merging
+export interface BuzolaPageMap {}
+
+/**
+ * Module augmentation point for persistent parameters.
+ * Vite plugin generates declarations that extend this interface.
+ * Keys listed here are automatically carried over between navigations.
+ */
+// biome-ignore lint/suspicious/noEmptyInterface: declaration merging
+export interface BuzolaPersistentParams {}
+
+/**
+ * Registered page IDs from BuzolaPageMap.
+ */
+export type RegisteredPage = keyof BuzolaPageMap & string
+
+/**
+ * Get the params type for a registered page.
+ */
+export type PageParams<P extends keyof BuzolaPageMap> = BuzolaPageMap[P]
+
+/**
+ * Effective params for a page — persistent params become optional.
+ * When BuzolaPersistentParams is empty (default), collapses to BuzolaPageMap[P].
+ */
+export type EffectivePageParams<P extends keyof BuzolaPageMap> =
+	& Omit<BuzolaPageMap[P], keyof BuzolaPersistentParams & string>
+	& Partial<Pick<BuzolaPageMap[P], keyof BuzolaPersistentParams & string & keyof BuzolaPageMap[P]>>
+
+// ─── Route configuration ────────────────────────────────────────────────────
+
+/**
+ * Standard Schema compatible interface (Zod 4, Valibot, ArkType).
+ * See: https://github.com/standard-schema/standard-schema
+ */
+export interface StandardSchema<T = unknown> {
+	'~standard': {
+		version: 1
+		vendor: string
+		validate: (value: unknown) => { value: T } | { issues: readonly { message: string }[] }
+	}
+}
+
+/** Result returned by a route guard to redirect navigation. */
+export interface GuardRedirect {
+	redirect: string
+}
+
+/** Context passed to route guards. */
+export interface GuardContext {
+	signal: AbortSignal
+}
+
+/** Guard function — return false to block, a GuardRedirect to redirect, or true/void to allow. */
+export type RouteGuardResult = boolean | void | GuardRedirect
+export type RouteGuard = (match: RouteMatch, context: GuardContext) => RouteGuardResult | Promise<RouteGuardResult>
+
+/** Route component — either a regular component or a lazy-loaded one. */
+export type RouteComponent = ComponentType<Record<string, never>> | LazyExoticComponent<ComponentType<Record<string, never>>>
+
+/** Configuration for a single route. */
+export interface RouteConfig {
+	/** The path segment for this route. */
+	path: string
+	/** Component to render for this route. */
+	component?: RouteComponent
+	/** Schema for validating search params (Standard Schema compatible). */
+	searchSchema?: StandardSchema
+	/** Guard function called before entering this route. */
+	beforeEnter?: RouteGuard
+	/** Child routes. */
+	children?: RouteConfig[]
+	/** Whether this is a layout route (has outlet but no own path segment). */
+	isLayout?: boolean
+	/** Whether this is an index route (renders at parent's exact path). */
+	isIndex?: boolean
+	/** Whether this is a pathless group (e.g., (auth) — no URL segment). */
+	isPathlessGroup?: boolean
+}
+
+// ─── Route matching ─────────────────────────────────────────────────────────
+
+/** A matched route with extracted params. */
+export interface RouteMatch {
+	/** The route node that matched. */
+	node: RouteNode
+	/** Extracted path parameters. */
+	params: Record<string, string>
+	/** The full URL pathname that was matched. */
+	pathname: string
+}
+
+// ─── Route tree ─────────────────────────────────────────────────────────────
+
+/** A node in the route tree. */
+export interface RouteNode {
+	/** Unique ID for this node. */
+	id: string
+	/** The path segment pattern (e.g., "/users/:userId"). */
+	path: string
+	/** Full path from root (e.g., "/users/:userId"). */
+	fullPath: string
+	/** Compiled URLPattern for matching (leaf/index routes). */
+	pattern?: URLPattern
+	/** Compiled prefix URLPattern for param extraction (layout routes). */
+	prefixPattern?: URLPattern
+	/** Component to render. */
+	component?: RouteComponent
+	/** Search params schema. */
+	searchSchema?: StandardSchema
+	/** Route guard. */
+	beforeEnter?: RouteGuard
+	/** Child nodes. */
+	children: RouteNode[]
+	/** Parent node reference. */
+	parent?: RouteNode
+	/** Whether this is a layout node (renders children via Outlet). */
+	isLayout: boolean
+	/** Whether this is an index route. */
+	isIndex: boolean
+}
+
+// ─── Router state ───────────────────────────────────────────────────────────
+
+/** The current state of the router. */
+export interface RouterState {
+	/** Current URL location. */
+	location: URL
+	/** Array of matched routes from root to leaf. */
+	matches: RouteMatch[]
+	/** Whether a navigation is in progress. */
+	isPending: boolean
+	/** Navigation state from Navigation API. */
+	navigationState?: unknown
+}
+
+// ─── Navigation adapter ─────────────────────────────────────────────────────
+
+/** Options for programmatic navigation. */
+export interface NavigateOptions {
+	/** Replace the current history entry instead of pushing. */
+	replace?: boolean
+	/** State to associate with the navigation entry. */
+	state?: unknown
+	/** Use View Transitions API for the navigation. */
+	viewTransition?: boolean
+	/**
+	 * Whether to reset scroll position after navigation.
+	 * Default is `true` (browser handles it: scroll to top on push, restore on traverse).
+	 * Set to `false` to preserve current scroll position.
+	 */
+	resetScroll?: boolean
+}
+
+/**
+ * Blocker function registered with the router.
+ * Called when a navigation is about to happen.
+ * Must return a Promise that resolves to `true` to allow navigation, `false` to block.
+ */
+export type BlockerFn = () => Promise<boolean>
+
+/** Navigate event from the Navigation API (simplified). */
+export interface BuzolaNavigateEvent {
+	/** The destination URL. */
+	destination: { url: string }
+	/** Whether the navigation can be intercepted. */
+	canIntercept: boolean
+	/** The type of navigation. */
+	navigationType: 'push' | 'replace' | 'reload' | 'traverse'
+	/** Whether the user initiated the navigation (e.g., clicking a link). */
+	userInitiated: boolean
+	/** Whether this navigation should use View Transitions API. */
+	viewTransition?: boolean
+	/** Intercept the navigation and handle it client-side. */
+	intercept(options: { handler: () => Promise<void>; scroll?: 'after-transition' | 'manual' }): void
+}
+
+/** Abstraction over the Navigation API for testability. */
+export interface NavigationAdapter {
+	/** Get the current URL. */
+	getCurrentURL(): URL
+	/** Navigate to a URL. */
+	navigate(url: string, options?: NavigateOptions): void
+	/** Go back. */
+	back(): void
+	/** Go forward. */
+	forward(): void
+	/** Add a navigate event listener. */
+	addEventListener(type: 'navigate', handler: (event: BuzolaNavigateEvent) => void): void
+	/** Remove a navigate event listener. */
+	removeEventListener(type: 'navigate', handler: (event: BuzolaNavigateEvent) => void): void
+	/** Get the current navigation state. */
+	getState(): unknown
+}

package/src/engine/utils.ts

@@ -0,0 +1,16 @@
+/**
+ * Extract parameter names from a route pattern.
+ * "/users/:userId/posts/:postId" → ["userId", "postId"]
+ * "/:lang/users/:userId+" → ["lang", "userId"]
+ */
+export function extractParamNames(pattern: string): string[] {
+	const names: string[] = []
+	for (const segment of pattern.split('/')) {
+		if (segment.startsWith(':')) {
+			// Strip catch-all suffix (+)
+			const name = segment.endsWith('+') ? segment.slice(1, -1) : segment.slice(1)
+			names.push(name)
+		}
+	}
+	return names
+}

package/src/env.d.ts

@@ -0,0 +1,120 @@
+// Type declarations for Navigation API and URLPattern
+// These are Baseline Newly Available (Jan 2026) but not yet in TypeScript's lib.
+
+interface URLPatternInit {
+	protocol?: string
+	username?: string
+	password?: string
+	hostname?: string
+	port?: string
+	pathname?: string
+	search?: string
+	hash?: string
+	baseURL?: string
+}
+
+interface URLPatternComponentResult {
+	input: string
+	groups: Record<string, string | undefined>
+}
+
+interface URLPatternResult {
+	inputs: [URLPatternInit] | [URLPatternInit, string]
+	protocol: URLPatternComponentResult
+	username: URLPatternComponentResult
+	password: URLPatternComponentResult
+	hostname: URLPatternComponentResult
+	port: URLPatternComponentResult
+	pathname: URLPatternComponentResult
+	search: URLPatternComponentResult
+	hash: URLPatternComponentResult
+}
+
+declare class URLPattern {
+	constructor(init: URLPatternInit)
+	constructor(pattern: string, baseURL?: string)
+	test(input?: URLPatternInit | string): boolean
+	exec(input?: URLPatternInit | string): URLPatternResult | null
+	readonly protocol: string
+	readonly username: string
+	readonly password: string
+	readonly hostname: string
+	readonly port: string
+	readonly pathname: string
+	readonly search: string
+	readonly hash: string
+}
+
+interface NavigationDestination {
+	url: string
+	key: string
+	id: string
+	index: number
+	sameDocument: boolean
+	getState(): unknown
+}
+
+interface NavigationHistoryEntry {
+	url: string | null
+	key: string
+	id: string
+	index: number
+	sameDocument: boolean
+	getState(): unknown
+}
+
+interface NavigateEvent extends Event {
+	navigationType: 'push' | 'replace' | 'reload' | 'traverse'
+	destination: NavigationDestination
+	canIntercept: boolean
+	userInitiated: boolean
+	hashChange: boolean
+	signal: AbortSignal
+	formData: FormData | null
+	downloadRequest: string | null
+	info: unknown
+	intercept(options?: {
+		handler?: () => Promise<void>
+		focusReset?: 'after-transition' | 'manual'
+		scroll?: 'after-transition' | 'manual'
+	}): void
+	scroll(): void
+}
+
+interface NavigationNavigateOptions {
+	state?: unknown
+	info?: unknown
+	history?: 'auto' | 'push' | 'replace'
+}
+
+interface NavigationResult {
+	committed: Promise<NavigationHistoryEntry>
+	finished: Promise<NavigationHistoryEntry>
+}
+
+interface Navigation extends EventTarget {
+	entries(): NavigationHistoryEntry[]
+	readonly currentEntry: NavigationHistoryEntry | null
+	readonly transition: NavigationTransition | null
+	readonly canGoBack: boolean
+	readonly canGoForward: boolean
+	navigate(url: string, options?: NavigationNavigateOptions): NavigationResult
+	reload(options?: { state?: unknown; info?: unknown }): NavigationResult
+	traverseTo(key: string, options?: { info?: unknown }): NavigationResult
+	back(options?: { info?: unknown }): NavigationResult
+	forward(options?: { info?: unknown }): NavigationResult
+	addEventListener(type: 'navigate', listener: (event: NavigateEvent) => void): void
+	addEventListener(type: string, listener: EventListener): void
+	removeEventListener(type: 'navigate', listener: (event: NavigateEvent) => void): void
+	removeEventListener(type: string, listener: EventListener): void
+}
+
+interface NavigationTransition {
+	navigationType: 'push' | 'replace' | 'reload' | 'traverse'
+	from: NavigationHistoryEntry
+	finished: Promise<void>
+}
+
+interface Window {
+	navigation: Navigation
+}

package/src/index.ts

@@ -0,0 +1,61 @@
+// ─── Engine ─────────────────────────────────────────────────────────────────
+export { NavigationAbortedError, Router } from './engine/router'
+export type { RouterOptions, RouterSubscriber } from './engine/router'
+
+export { buildRouteTree, createRouteNode } from './engine/route-tree'
+export type { CreateRouteNodeOptions } from './engine/route-tree'
+
+export { matchRoutes } from './engine/matcher'
+
+export { createBrowserNavigationAdapter, createMemoryNavigationAdapter } from './engine/navigation-adapter'
+export type { MemoryNavigationAdapterOptions } from './engine/navigation-adapter'
+
+// ─── Types ──────────────────────────────────────────────────────────────────
+export type {
+	BlockerFn,
+	BuzolaNavigateEvent,
+	BuzolaPageMap,
+	BuzolaPersistentParams,
+	EffectivePageParams,
+	GuardContext,
+	GuardRedirect,
+	NavigateOptions,
+	NavigationAdapter,
+	PageParams,
+	RegisteredPage,
+	RouteComponent,
+	RouteConfig,
+	RouteGuard,
+	RouteGuardResult,
+	RouteMatch,
+	RouteNode,
+	RouterState,
+	StandardSchema,
+} from './engine/types'
+
+// ─── Schema ──────────────────────────────────────────────────────────────────
+export { s } from './engine/schema'
+
+// ─── Route definition ───────────────────────────────────────────────────────
+export { createPage } from './define/create-page'
+export type { CatchContext, PageDefinition, PageProps } from './define/create-page'
+
+// ─── React (re-export from subpath) ─────────────────────────────────────────
+export {
+	BuzolaProvider,
+	ErrorBoundary,
+	Link,
+	Outlet,
+	RouteContext,
+	RouterContext,
+	useBlocker,
+	useInvalidate,
+	useNavigate,
+	useNavigationState,
+	useParams,
+	useRoute,
+	useRouter,
+	useRouterState,
+	useSearchParams,
+} from './react/index'
+export type { BlockerState, BuzolaProviderProps, LinkProps, OutletProps, RouteContextValue } from './react/index'

package/src/react/context.ts

@@ -0,0 +1,24 @@
+import { createContext } from 'react'
+import type { Router } from '../engine/router'
+import type { RouteMatch, RouterState } from '../engine/types'
+
+/**
+ * Context providing the Router instance.
+ */
+export const RouterContext = createContext<Router | null>(null)
+
+/**
+ * Context for the current route matching state.
+ */
+export interface RouteContextValue {
+	/** Current router state. */
+	state: RouterState
+	/** Current depth in the route match chain. */
+	depth: number
+	/** All matches from root to leaf. */
+	matches: RouteMatch[]
+	/** Merged params from root to current depth. */
+	params: Record<string, string>
+}
+
+export const RouteContext = createContext<RouteContextValue | null>(null)

package/src/react/error-boundary.tsx

@@ -0,0 +1,56 @@
+import React, { Component } from 'react'
+
+interface ErrorBoundaryProps {
+	fallback?: React.ReactNode | ((error: Error) => React.ReactNode)
+	/** When this key changes, the error state is reset. */
+	resetKey?: string
+	children: React.ReactNode
+}
+
+interface ErrorBoundaryState {
+	error: Error | null
+	prevResetKey: string | undefined
+}
+
+/**
+ * Error boundary for catching rendering errors in route components.
+ * Resets automatically when `resetKey` changes (e.g., on navigation to a different route).
+ */
+export class ErrorBoundary extends Component<ErrorBoundaryProps, ErrorBoundaryState> {
+	state: ErrorBoundaryState = { error: null, prevResetKey: undefined }
+
+	static getDerivedStateFromError(error: Error): Partial<ErrorBoundaryState> {
+		return { error }
+	}
+
+	static getDerivedStateFromProps(
+		props: ErrorBoundaryProps,
+		state: ErrorBoundaryState,
+	): Partial<ErrorBoundaryState> | null {
+		// Reset error state when resetKey changes (i.e., route changed)
+		if (state.error && props.resetKey !== state.prevResetKey) {
+			return { error: null, prevResetKey: props.resetKey }
+		}
+		if (props.resetKey !== state.prevResetKey) {
+			return { prevResetKey: props.resetKey }
+		}
+		return null
+	}
+
+	componentDidCatch(error: Error, info: React.ErrorInfo): void {
+		console.error('Buzola route error:', error, info)
+	}
+
+	render(): React.ReactNode {
+		if (this.state.error) {
+			if (typeof this.props.fallback === 'function') {
+				return this.props.fallback(this.state.error)
+			}
+			if (this.props.fallback) {
+				return this.props.fallback
+			}
+			return React.createElement('div', { style: { color: 'red' } }, `Route error: ${this.state.error.message}`)
+		}
+		return this.props.children
+	}
+}

package/src/react/hooks.ts

@@ -0,0 +1,211 @@
+import { use, useCallback, useEffect, useMemo, useRef, useState } from 'react'
+import type { Router } from '../engine/router'
+import type { EffectivePageParams, NavigateOptions, RegisteredPage, RouterState, StandardSchema } from '../engine/types'
+import { RouteContext, RouterContext } from './context'
+
+/**
+ * Get the Router instance.
+ */
+export function useRouter(): Router {
+	const router = use(RouterContext)
+	if (!router) {
+		throw new Error('useRouter must be used within a <BuzolaProvider>')
+	}
+	return router
+}
+
+/**
+ * Get the current route context.
+ */
+function useRouteContext() {
+	const context = use(RouteContext)
+	if (!context) {
+		throw new Error('Route hooks must be used within a <BuzolaProvider>')
+	}
+	return context
+}
+
+/**
+ * Type-safe navigation function.
+ * Uses page IDs instead of URL patterns.
+ * Persistent params are optional — resolved from current URL or fallback.
+ */
+type NavigateFn = <P extends RegisteredPage>(
+	to: P,
+	...args: [keyof EffectivePageParams<P>] extends [never] ? [options?: NavigateOptions]
+		// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+		: {} extends EffectivePageParams<P> ? [options?: NavigateOptions & { params?: EffectivePageParams<P> }]
+		: [options: NavigateOptions & { params: EffectivePageParams<P> }]
+) => void
+
+/**
+ * Hook to get a type-safe navigate function.
+ * Navigates using page IDs — the router looks up the route pattern from the page registry.
+ */
+export function useNavigate(): NavigateFn {
+	const router = useRouter()
+
+	return useCallback(
+		(to: string, options?: NavigateOptions & { params?: Record<string, string> }) => {
+			router.navigateToPage(to, options?.params, options)
+		},
+		[router],
+	) as NavigateFn
+}
+
+/**
+ * Hook to get typed route params.
+ * Params are merged from all matched routes (root to current depth).
+ */
+export function useParams<T extends Record<string, string> = Record<string, string>>(): T {
+	const context = useRouteContext()
+	return context.params as T
+}
+
+/**
+ * Hook to get and validate search params.
+ * Optionally validates with a Standard Schema compatible schema.
+ */
+export function useSearchParams<T = Record<string, string>>(
+	schema?: StandardSchema<T>,
+): T {
+	const context = useRouteContext()
+
+	return useMemo(() => {
+		const searchParams = context.state.location.searchParams
+		const raw: Record<string, string[]> = {}
+		searchParams.forEach((value, key) => {
+			const existing = raw[key]
+			if (existing) {
+				existing.push(value)
+			} else {
+				raw[key] = [value]
+			}
+		})
+
+		if (schema) {
+			const result = schema['~standard'].validate(raw)
+			if ('issues' in result) {
+				throw new Error(
+					`Search params validation failed: ${result.issues.map(i => i.message).join(', ')}`,
+				)
+			}
+			return result.value
+		}
+
+		return raw as T
+	}, [context.state.location.searchParams, schema])
+}
+
+/**
+ * Hook to get information about the current route.
+ */
+export function useRoute() {
+	const context = useRouteContext()
+	const router = useRouter()
+	const { state, matches, params, depth } = context
+
+	return useMemo(() => ({
+		/** Current route's params. */
+		params,
+		/** All route matches from root to leaf. */
+		matches,
+		/** Current match depth. */
+		depth,
+		/** Whether a navigation is pending. */
+		isPending: state.isPending,
+		/** Current pathname (with base path stripped). */
+		pathname: router.stripBasePath(state.location.pathname),
+	}), [params, matches, depth, state.isPending, state.location.pathname, router])
+}
+
+/**
+ * Hook to get the Navigation API state for the current entry.
+ */
+export function useNavigationState<T = unknown>(): T | undefined {
+	const context = useRouteContext()
+	return context.state.navigationState as T | undefined
+}
+
+/**
+ * Hook to get the current RouterState.
+ */
+export function useRouterState(): RouterState {
+	const context = useRouteContext()
+	return context.state
+}
+
+/**
+ * Hook to get a function that invalidates all page loaders.
+ * Loaders re-run in the background while stale data is still shown.
+ */
+export function useInvalidate(): () => void {
+	const router = useRouter()
+	return useCallback(() => router.invalidateAll(), [router])
+}
+
+// ─── Blocker ─────────────────────────────────────────────────────────────────
+
+export interface BlockerState {
+	/** Whether a navigation is currently blocked. */
+	state: 'idle' | 'blocked'
+	/** Allow the blocked navigation to proceed. */
+	proceed: () => void
+	/** Cancel the blocked navigation and stay on the current page. */
+	reset: () => void
+}
+
+/**
+ * Hook to block navigations (e.g., to warn about unsaved changes).
+ *
+ * @param when - Whether blocking is active. Pass `true` to block, `false` to allow.
+ * @returns An object with the blocker state and proceed/reset functions.
+ *
+ * @example
+ * ```tsx
+ * const blocker = useBlocker(formIsDirty);
+ *
+ * if (blocker.state === 'blocked') {
+ *   return <Dialog onConfirm={blocker.proceed} onCancel={blocker.reset} />;
+ * }
+ * ```
+ */
+export function useBlocker(when: boolean): BlockerState {
+	const router = useRouter()
+	const [state, setState] = useState<'idle' | 'blocked'>('idle')
+	const resolverRef = useRef<((proceed: boolean) => void) | null>(null)
+
+	const blockerFn = useCallback((): Promise<boolean> => {
+		return new Promise((resolve) => {
+			resolverRef.current = resolve
+			setState('blocked')
+		})
+	}, [])
+
+	useEffect(() => {
+		if (!when) return
+		const cleanup = router.addBlocker(blockerFn)
+		return () => {
+			cleanup()
+			// If there's a pending blocker when unmounting, auto-proceed
+			if (resolverRef.current) {
+				resolverRef.current(true)
+				resolverRef.current = null
+			}
+		}
+	}, [router, when, blockerFn])
+
+	const proceed = useCallback(() => {
+		resolverRef.current?.(true)
+		resolverRef.current = null
+		setState('idle')
+	}, [])
+
+	const reset = useCallback(() => {
+		resolverRef.current?.(false)
+		resolverRef.current = null
+		setState('idle')
+	}, [])
+
+	return { state, proceed, reset }
+}