@buzola/router 0.0.1

package/src/react/index.ts

@@ -0,0 +1,16 @@
+export { BuzolaProvider } from './provider'
+export type { BuzolaProviderProps } from './provider'
+
+export { Outlet } from './outlet'
+export type { OutletProps } from './outlet'
+
+export { Link } from './link'
+export type { LinkProps } from './link'
+
+export { ErrorBoundary } from './error-boundary'
+
+export { useBlocker, useInvalidate, useNavigate, useNavigationState, useParams, useRoute, useRouter, useRouterState, useSearchParams } from './hooks'
+export type { BlockerState } from './hooks'
+
+export { RouteContext, RouterContext } from './context'
+export type { RouteContextValue } from './context'

package/src/react/link.tsx

@@ -0,0 +1,93 @@
+import React, { useCallback } from 'react'
+import type { EffectivePageParams, NavigateOptions, RegisteredPage } from '../engine/types.js'
+import { useRouter, useRouterState } from './hooks.js'
+
+// ─── Link props type — always type-safe via page ID ──────────────────────────
+
+type LinkPropsBase = Omit<React.AnchorHTMLAttributes<HTMLAnchorElement>, 'href'> & {
+	/** Replace the current history entry instead of pushing. */
+	replace?: boolean
+	/** State to associate with the navigation entry. */
+	state?: unknown
+	/** Use View Transitions API for this navigation. */
+	viewTransition?: boolean
+	/**
+	 * Whether to reset scroll position after navigation.
+	 * Default is `true`. Set to `false` to preserve current scroll position.
+	 */
+	resetScroll?: boolean
+	/**
+	 * Use exact matching for active detection.
+	 * When `true` (default), `data-active` is set only when the current path equals the link target.
+	 * When `false`, `data-active` is also set when the current path starts with the link target.
+	 */
+	activeExact?: boolean
+}
+
+export type LinkProps<P extends RegisteredPage = RegisteredPage> = [keyof EffectivePageParams<P>] extends [never]
+	? LinkPropsBase & { to: P; params?: never }
+	// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+	: {} extends EffectivePageParams<P> ? LinkPropsBase & { to: P; params?: EffectivePageParams<P> }
+	: LinkPropsBase & { to: P; params: EffectivePageParams<P> }
+
+/**
+ * Type-safe link component.
+ * Uses page IDs for navigation — the router looks up the route pattern from the page registry.
+ * For simple navigations, renders a native <a> and lets the Navigation API handle it.
+ * Uses programmatic navigation when state, replace, resetScroll, or viewTransition is needed.
+ *
+ * Sets `data-active` attribute when the link target matches the current URL.
+ */
+export function Link<P extends RegisteredPage>(props: LinkProps<P>): React.ReactElement {
+	const {
+		to,
+		params,
+		replace,
+		state,
+		viewTransition,
+		resetScroll,
+		activeExact = true,
+		onClick,
+		children,
+		...rest
+	} = props as LinkPropsBase & { to: string; params?: Record<string, string> }
+
+	const router = useRouter()
+	const routerState = useRouterState()
+
+	const href = router.buildPagePath(to, params)
+	const needsProgrammaticNav = state !== undefined || replace || viewTransition || resetScroll === false
+
+	// Active detection: compare route paths (without basePath)
+	const currentPath = router.stripBasePath(routerState.location.pathname)
+	const targetPath = router.stripBasePath(href.split('?')[0])
+	const isExact = currentPath === targetPath
+	const isPrefix = targetPath !== '/' && currentPath.startsWith(targetPath + '/')
+	const isActive = isExact || (!activeExact && isPrefix)
+
+	const handleClick = useCallback(
+		(e: React.MouseEvent<HTMLAnchorElement>) => {
+			onClick?.(e)
+			if (e.defaultPrevented) return
+
+			// Only handle left clicks without modifier keys
+			if (e.button !== 0 || e.metaKey || e.altKey || e.ctrlKey || e.shiftKey) return
+
+			if (needsProgrammaticNav) {
+				e.preventDefault()
+				router.navigateToPage(
+					to,
+					params,
+					{ replace, state, viewTransition, resetScroll } as NavigateOptions,
+				)
+			}
+		},
+		[onClick, needsProgrammaticNav, router, to, params, replace, state, viewTransition, resetScroll],
+	)
+
+	return (
+		<a href={href} onClick={handleClick} data-active={isActive ? '' : undefined} {...rest}>
+			{children}
+		</a>
+	)
+}

package/src/react/outlet.tsx

@@ -0,0 +1,67 @@
+import React, { Suspense, use, useMemo } from 'react'
+import { RouteContext, type RouteContextValue } from './context.js'
+import { ErrorBoundary } from './error-boundary.js'
+
+export interface OutletProps {
+	/** Fallback to show while lazy components load. */
+	fallback?: React.ReactNode
+	/** Fallback to show when a route component throws an error. */
+	errorFallback?: React.ReactNode | ((error: Error) => React.ReactNode)
+}
+
+/**
+ * Renders the component for the current depth in the route match chain.
+ * Each Outlet increments the depth and renders the next matched route's component.
+ */
+export function Outlet({ fallback, errorFallback }: OutletProps): React.ReactElement | null {
+	const routeContext = use(RouteContext)
+	if (!routeContext) {
+		throw new Error('<Outlet /> must be used within a <BuzolaProvider>')
+	}
+
+	const { state, depth, matches } = routeContext
+
+	// Find the next match that has a component, skipping componentless nodes
+	// (e.g. directory layout nodes without a layout.tsx file).
+	let effectiveDepth = depth
+	let match = matches[effectiveDepth]
+	while (match && !match.node.component) {
+		effectiveDepth++
+		match = matches[effectiveDepth]
+	}
+
+	const nextContext = useMemo<RouteContextValue | null>(() => {
+		if (!match) return null
+		// Merge params from all skipped matches and the effective match
+		let mergedParams = { ...routeContext.params }
+		for (let i = depth; i <= effectiveDepth; i++) {
+			if (matches[i]) {
+				mergedParams = { ...mergedParams, ...matches[i].params }
+			}
+		}
+		return {
+			state,
+			depth: effectiveDepth + 1,
+			matches,
+			params: mergedParams,
+		}
+	}, [state, depth, effectiveDepth, matches, match, routeContext.params])
+
+	if (!match) {
+		return null
+	}
+
+	const Component = match.node.component!
+
+	return (
+		<ErrorBoundary fallback={errorFallback} resetKey={match.node.id}>
+			<Suspense fallback={fallback ?? null}>
+				{nextContext && (
+					<RouteContext value={nextContext}>
+						<Component />
+					</RouteContext>
+				)}
+			</Suspense>
+		</ErrorBoundary>
+	)
+}

package/src/react/provider.tsx

@@ -0,0 +1,60 @@
+import React, { useCallback, useEffect, useMemo, useRef, useSyncExternalStore } from 'react'
+import { createBrowserNavigationAdapter } from '../engine/navigation-adapter.js'
+import { Router } from '../engine/router.js'
+import type { RouteNode } from '../engine/types.js'
+import { RouteContext, type RouteContextValue, RouterContext } from './context.js'
+import { Outlet } from './outlet.js'
+
+export type BuzolaProviderProps =
+	& {
+		children?: React.ReactNode
+	}
+	& (
+		| { router: Router; routes?: never; persistentParams?: never; pageRegistry?: never }
+		| {
+			router?: never
+			routes: RouteNode[]
+			persistentParams?: () => Record<string, string>
+			pageRegistry?: Record<string, string>
+		}
+	)
+
+/**
+ * Root provider for Buzola router.
+ * Subscribes to router state and provides context to the React tree.
+ */
+export function BuzolaProvider({ routes, children, ...props }: BuzolaProviderProps): React.ReactElement {
+	const routerRef = useRef<Router | undefined>(props.router)
+	if (!routerRef.current) {
+		routerRef.current = new Router({
+			routes: routes!,
+			adapter: createBrowserNavigationAdapter(),
+			persistentParams: props.persistentParams,
+			pageRegistry: props.pageRegistry,
+		})
+	}
+	const router = routerRef.current
+	const subscribe = useCallback((cb: () => void) => router.subscribe(cb), [router])
+	const getSnapshot = useCallback(() => router.getState(), [router])
+	const state = useSyncExternalStore(subscribe, getSnapshot, getSnapshot)
+
+	// Start navigation interception
+	useEffect(() => {
+		return router.start()
+	}, [router])
+
+	const routeContextValue = useMemo<RouteContextValue>(() => ({
+		state,
+		depth: 0,
+		matches: state.matches,
+		params: {},
+	}), [state])
+
+	return (
+		<RouterContext value={router}>
+			<RouteContext value={routeContextValue}>
+				{children ?? <Outlet />}
+			</RouteContext>
+		</RouterContext>
+	)
+}