@buzola/router 0.0.4 → 0.0.6

package/src/engine/types.ts

@@ -63,6 +63,8 @@ export interface RouteConfig {
 	component?: RouteComponent
 	/** Schema for validating search params (Standard Schema compatible). */
 	searchSchema?: StandardSchema
+	/** Preload function — triggers lazy component import ahead of navigation. */
+	preload?: () => void
 	/** Child routes. */
 	children?: RouteConfig[]
 	/** Whether this is a layout route (has outlet but no own path segment). */
@@ -103,6 +105,8 @@ export interface RouteNode {
 	component?: RouteComponent
 	/** Search params schema. */
 	searchSchema?: StandardSchema
+	/** Preload function — triggers lazy component import ahead of navigation. */
+	preload?: () => void
 	/** Child nodes. */
 	children: RouteNode[]
 	/** Parent node reference. */
@@ -123,6 +127,8 @@ export interface RouterState {
 	matches: RouteMatch[]
 	/** Whether a navigation is in progress. */
 	isPending: boolean
+	/** The target URL during a pending navigation. Undefined when not navigating. */
+	pendingLocation?: URL
 	/** Navigation state from Navigation API. */
 	navigationState?: unknown
 }

package/src/react/hooks.ts

@@ -115,9 +115,13 @@ export function useRoute() {
 		depth,
 		/** Whether a navigation is pending. */
 		isPending: state.isPending,
+		/** The target URL during a pending navigation (with base path stripped). Undefined when not navigating. */
+		pendingLocation: state.pendingLocation
+			? router.stripBasePath(state.pendingLocation.pathname)
+			: undefined,
 		/** Current pathname (with base path stripped). */
 		pathname: router.stripBasePath(state.location.pathname),
-	}), [params, matches, depth, state.isPending, state.location.pathname, router])
+	}), [params, matches, depth, state.isPending, state.pendingLocation, state.location.pathname, router])
 }
 
 /**

package/src/react/link.tsx

@@ -1,4 +1,4 @@
-import React, { useCallback } from 'react'
+import React, { useCallback, useEffect, useRef } from 'react'
 import type { EffectivePageParams, NavigateOptions, RegisteredPage } from '../engine/types.js'
 import { useRouter, useRouterState } from './hooks.js'
 
@@ -27,6 +27,13 @@ type LinkPropsBase = Omit<React.AnchorHTMLAttributes<HTMLAnchorElement>, 'href'>
 	 * When `true`, clones the single child element and merges `href`, `onClick`, and `data-active` props into it.
 	 */
 	asChild?: boolean
+	/**
+	 * Prefetch strategy for lazy-loaded route code.
+	 * - `'intent'` — preload on mouseEnter/focus (default)
+	 * - `'render'` — preload as soon as the Link renders
+	 * - `'none'` — disable prefetching
+	 */
+	prefetch?: 'intent' | 'render' | 'none'
 }
 
 export type LinkProps<P extends RegisteredPage = RegisteredPage> = [keyof EffectivePageParams<P>] extends [never]
@@ -53,13 +60,17 @@ export function Link<P extends RegisteredPage>(props: LinkProps<P>): React.React
 		resetScroll,
 		activeExact = true,
 		asChild,
+		prefetch = 'intent',
 		onClick,
+		onMouseEnter,
+		onFocus,
 		children,
 		...rest
 	} = props as LinkPropsBase & { to: string; params?: Record<string, string> }
 
 	const router = useRouter()
 	const routerState = useRouterState()
+	const preloadedRef = useRef(false)
 
 	const href = router.buildPagePath(to, params)
 	const needsProgrammaticNav = state !== undefined || replace || viewTransition || resetScroll === false
@@ -71,6 +82,33 @@ export function Link<P extends RegisteredPage>(props: LinkProps<P>): React.React
 	const isPrefix = targetPath !== '/' && currentPath.startsWith(targetPath + '/')
 	const isActive = isExact || (!activeExact && isPrefix)
 
+	const doPreload = useCallback(() => {
+		if (preloadedRef.current) return
+		preloadedRef.current = true
+		router.preload(to, params)
+	}, [router, to, params])
+
+	// Prefetch on render
+	useEffect(() => {
+		if (prefetch === 'render') doPreload()
+	}, [prefetch, doPreload])
+
+	const handleMouseEnter = useCallback(
+		(e: React.MouseEvent<HTMLAnchorElement>) => {
+			onMouseEnter?.(e)
+			if (prefetch === 'intent') doPreload()
+		},
+		[onMouseEnter, prefetch, doPreload],
+	)
+
+	const handleFocus = useCallback(
+		(e: React.FocusEvent<HTMLAnchorElement>) => {
+			onFocus?.(e)
+			if (prefetch === 'intent') doPreload()
+		},
+		[onFocus, prefetch, doPreload],
+	)
+
 	const handleClick = useCallback(
 		(e: React.MouseEvent<HTMLAnchorElement>) => {
 			onClick?.(e)
@@ -91,18 +129,24 @@ export function Link<P extends RegisteredPage>(props: LinkProps<P>): React.React
 		[onClick, needsProgrammaticNav, router, to, params, replace, state, viewTransition, resetScroll],
 	)
 
+	const commonProps = {
+		href,
+		onClick: handleClick,
+		onMouseEnter: handleMouseEnter,
+		onFocus: handleFocus,
+		'data-active': isActive ? '' : undefined,
+	}
+
 	if (asChild) {
 		const child = React.Children.only(children) as React.ReactElement<any>
 		return React.cloneElement(child, {
-			href,
-			onClick: handleClick,
-			'data-active': isActive ? '' : undefined,
+			...commonProps,
 			...rest,
 		})
 	}
 
 	return (
-		<a href={href} onClick={handleClick} data-active={isActive ? '' : undefined} {...rest}>
+		<a {...commonProps} {...rest}>
 			{children}
 		</a>
 	)