@buzola/router 0.0.17 → 0.0.19

package/src/engine/router.ts

@@ -1,7 +1,7 @@
 import { LoaderCache } from './loader-cache.js'
 import { matchRoutes } from './matcher.js'
-import type { BlockerFn, BuzolaNavigateEvent, NavigateOptions, NavigationAdapter, RouterState, RouteTree } from './types.js'
-import { extractParamNames, isSamePath, parseParamSegment } from './utils.js'
+import type { BlockerFn, BuzolaNavigateEvent, NavigateOptions, NavigationAdapter, RouterState, RouteTree, ShouldInterceptFn } from './types.js'
+import { extractParamNames, isFragmentNavigation, isSamePath, parseParamSegment } from './utils.js'
 
 /**
  * Thrown when a route guard prevents navigation.
@@ -45,6 +45,16 @@ export interface RouterOptions {
 	 * Set to 0 to always re-fetch on URL change (default).
 	 */
 	loaderCacheSize?: number
+	/**
+	 * Decides, per navigation, whether the router handles it in the current document.
+	 * Return `false` to have the browser load the destination as a new document instead,
+	 * e.g. to pick up a newly deployed build on the next in-app navigation.
+	 *
+	 * Offered every push, replace and traverse the router would otherwise intercept, except
+	 * fragment navigations. Defaults to intercepting everything. See the README for how
+	 * traversals and blockers are handled.
+	 */
+	shouldIntercept?: ShouldInterceptFn
 }
 
 /**
@@ -58,6 +68,7 @@ export class Router {
 	private readonly _basePath: string
 	private readonly persistentParamsFn?: () => Record<string, string>
 	private readonly pageRegistry: Record<string, string>
+	private readonly shouldIntercept: ShouldInterceptFn | undefined
 	private subscribers = new Set<RouterSubscriber>()
 	private invalidationListeners = new Set<() => void>()
 	private state: RouterState
@@ -77,6 +88,7 @@ export class Router {
 		this._basePath = options.basePath ? options.basePath.replace(/\/$/, '') : ''
 		this.persistentParamsFn = options.persistentParams
 		this.pageRegistry = options.pageRegistry ?? {}
+		this.shouldIntercept = options.shouldIntercept
 		this._loaderCache = options.loaderCacheSize ? new LoaderCache(options.loaderCacheSize) : undefined
 
 		// Initialize state from current URL
@@ -134,7 +146,7 @@ export class Router {
 	 */
 	start(): () => void {
 		const handler = (event: BuzolaNavigateEvent) => {
-			// Consume the pending options before any early return — they belong to the
+			// Consume the pending options before any early return: they belong to the
 			// navigation that armed them and must not leak into the next one.
 			const scrollBehavior = this.pendingScrollBehavior
 			const explicitFocusReset = this.pendingFocusReset
@@ -163,9 +175,24 @@ export class Router {
 				return
 			}
 
+			// The browser decides a fragment navigation against the committed entry, which runs ahead of the
+			// page on screen while a navigation is pending (e.g. a blocker dialog is open).
+			if (this.shouldIntercept && !isFragmentNavigation(this.adapter.getCurrentURL(), url)) {
+				const intercept = this.shouldIntercept({
+					destination: url,
+					from: this.state.location,
+					navigationType: event.navigationType,
+					userInitiated: event.userInitiated,
+				})
+				if (!intercept) {
+					this.handleDeclined(event)
+					return
+				}
+			}
+
 			const currentNavId = ++this.navigationId
 			const useViewTransition = event.viewTransition || this.viewTransitions
-			// Query-only navigations stay on the same page — keep focus where the user left it
+			// Query-only navigations stay on the same page, so keep focus where the user left it
 			// (search boxes, filters, pagination). Path changes keep the browser's focus reset,
 			// and so do fragment changes, which must move focus to the targeted section.
 			const focusReset = explicitFocusReset
@@ -191,7 +218,7 @@ export class Router {
 						pendingLocation: url,
 					})
 
-					// A newer navigation has started — abandon this one
+					// A newer navigation has started, so abandon this one
 					if (this.navigationId !== currentNavId) return
 
 					// Perform the DOM update
@@ -204,7 +231,7 @@ export class Router {
 							pendingLocation: undefined,
 							navigationState: this.adapter.getState(),
 						})
-						// Going to the URL we are already on is still a navigation — a browser
+						// Going to the URL we are already on is still a navigation: a browser
 						// re-requests the document for it. Loader data is keyed by href, so it
 						// would silently keep serving stale data without an explicit invalidation.
 						if (previousHref === url.href) {
@@ -240,7 +267,28 @@ export class Router {
 	 */
 	private handleReload(event: BuzolaNavigateEvent): void {
 		if (this.blockers.size === 0) return
+		this.reloadAfterBlockers(event)
+	}
 
+	/**
+	 * `shouldIntercept` declined this navigation, so the destination must load as a new document.
+	 *
+	 * A push or replace is simply not intercepted, and the browser performs the document navigation itself.
+	 * That does not work for a traversal, which the browser completes within the document, nor while
+	 * blockers are registered, since they are async. Those are intercepted, which commits the destination
+	 * entry, and that entry is reloaded once the blockers allow it.
+	 */
+	private handleDeclined(event: BuzolaNavigateEvent): void {
+		if (event.navigationType !== 'traverse' && this.blockers.size === 0) return
+		this.reloadAfterBlockers(event)
+	}
+
+	/**
+	 * Hold the navigation while the blockers run and, if they allow it, reload the current entry,
+	 * which is already the navigation's destination, because an intercepted navigation commits before
+	 * its handler runs.
+	 */
+	private reloadAfterBlockers(event: BuzolaNavigateEvent): void {
 		const currentNavId = ++this.navigationId
 		event.intercept({
 			scroll: 'manual',
@@ -261,7 +309,7 @@ export class Router {
 	}
 
 	/**
-	 * Hand one navigation to the browser instead of intercepting it, for a URL the SERVER owns —
+	 * Hand one navigation to the browser instead of intercepting it, for a URL the SERVER owns:
 	 * an auth handoff, a file download, a server-rendered page that happens to share this origin.
 	 *
 	 * The Navigation API offers no way for a caller to mark a navigation un-interceptable:
@@ -271,7 +319,7 @@ export class Router {
 	 *
 	 * The release is recorded BEFORE the navigation is requested and is keyed to the resolved URL, so
 	 * it cannot race the event or release some other navigation. Unlike `navigate`, the URL is passed
-	 * to the browser as given — no base path is prepended, because the target is outside the app.
+	 * to the browser as given: no base path is prepended, because the target is outside the app.
 	 */
 	leaveApp(url: string): void {
 		this.releasedURL = new URL(url, this.adapter.getCurrentURL()).href
@@ -280,7 +328,7 @@ export class Router {
 
 	/**
 	 * Navigate programmatically.
-	 * The `to` path should not include the base path — it is prepended automatically.
+	 * The `to` path should not include the base path. It is prepended automatically.
 	 */
 	navigate(to: string, options?: NavigateOptions): void {
 		if (options?.resetScroll === false) {
@@ -361,7 +409,7 @@ export class Router {
 					missing.push(paramName)
 				} else {
 					if (isCatchAll) {
-						// Catch-all values may contain slashes — insert raw
+						// Catch-all values may contain slashes: insert raw
 						result.push(value)
 					} else {
 						result.push(encodeURIComponent(value))
@@ -485,7 +533,7 @@ export class Router {
 	}
 
 	/**
-	 * Dispose the router — clear all subscribers and reset state.
+	 * Dispose the router: clear all subscribers and reset state.
 	 */
 	dispose(): void {
 		this.stopFn?.()

package/src/engine/types.ts

@@ -29,7 +29,7 @@ export type RegisteredPage = keyof BuzolaPageMap & string
 export type PageParams<P extends keyof BuzolaPageMap> = BuzolaPageMap[P]
 
 /**
- * Effective params for a page — persistent params become optional.
+ * 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> =
@@ -50,7 +50,7 @@ export interface StandardSchema<T = unknown> {
 	}
 }
 
-/** Route component — either a regular component or a lazy-loaded one. */
+/** 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. */
@@ -63,7 +63,7 @@ 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 function: triggers lazy component import ahead of navigation. */
 	preload?: () => void
 	/** Child routes. */
 	children?: RouteConfig[]
@@ -71,7 +71,7 @@ export interface RouteConfig {
 	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). */
+	/** Whether this is a pathless group (e.g., (auth), with no URL segment). */
 	isPathlessGroup?: boolean
 }
 
@@ -101,7 +101,7 @@ export interface RouteNode {
 	component?: RouteComponent
 	/** Search params schema. */
 	searchSchema?: StandardSchema
-	/** Preload function — triggers lazy component import ahead of navigation. */
+	/** Preload function: triggers lazy component import ahead of navigation. */
 	preload?: () => void
 	/** Whether this is a layout node (renders children via Outlet). */
 	isLayout: boolean
@@ -113,7 +113,7 @@ export interface RouteNode {
 
 /** A node in the segment trie used for URL matching. */
 export interface TrieNode {
-	/** Static children — exact segment match via Map lookup (O(1)). */
+	/** Static children: exact segment match via Map lookup (O(1)). */
 	staticChildren: Map<string, TrieNode>
 	/**
 	 * Dynamic child: matches any single segment. It carries no param name, because routes sharing this
@@ -174,8 +174,8 @@ export interface NavigateOptions {
 	resetScroll?: boolean
 	/**
 	 * Whether the browser moves focus after navigation.
-	 * Defaults to `manual` when only the search string changes — so search boxes, filters and
-	 * pagination controls keep the caret — and to `after-transition` when the path or the hash
+	 * Defaults to `manual` when only the search string changes (so search boxes, filters and
+	 * pagination controls keep the caret), and to `after-transition` when the path or the hash
 	 * changes, so fragment links move focus to the section they target.
 	 */
 	focusReset?: 'after-transition' | 'manual'
@@ -188,6 +188,28 @@ export interface NavigateOptions {
  */
 export type BlockerFn = () => Promise<boolean>
 
+/** A navigation the router is about to intercept, as offered to `shouldIntercept`. */
+export interface InterceptInfo {
+	/** Where the navigation goes. */
+	destination: URL
+	/**
+	 * The location the router currently shows. While a navigation is pending, this can differ from
+	 * `navigation.currentEntry`, which has already moved to that navigation's destination.
+	 */
+	from: URL
+	/** How the navigation moves through history. Reloads always go to the browser and are never offered. */
+	navigationType: 'push' | 'replace' | 'traverse'
+	/** Whether the user initiated the navigation (e.g., clicking a link). */
+	userInitiated: boolean
+}
+
+/**
+ * Decides whether the router handles a navigation in the current document.
+ * Return `false` to have the browser load the destination as a new document instead.
+ * Called synchronously from the `navigate` event, so it cannot await anything.
+ */
+export type ShouldInterceptFn = (info: InterceptInfo) => boolean
+
 /** Navigate event from the Navigation API (simplified). */
 export interface BuzolaNavigateEvent {
 	/** The destination URL. */

package/src/engine/utils.ts

@@ -24,15 +24,28 @@ export function extractParamNames(pattern: string): string[] {
 }
 
 /**
- * Whether two URLs address the same page — i.e. only search/hash differ.
+ * Whether two URLs address the same page, i.e. only search/hash differ.
  * Same-path navigations (filters, sorting, pagination, search) keep the page
  * on screen and keep its loader data as stale; path changes do not.
  *
- * Note this ignores the hash. Callers that care about fragment changes — focus
- * handling, for one — have to compare `hash` themselves.
+ * Note this ignores the hash. Callers that care about fragment changes (focus
+ * handling, for one) have to compare `hash` themselves.
  */
 export function isSamePath(a: string | URL, b: string | URL): boolean {
 	const urlA = typeof a === 'string' ? new URL(a) : a
 	const urlB = typeof b === 'string' ? new URL(b) : b
 	return urlA.origin === urlB.origin && urlA.pathname === urlB.pathname
 }
+
+/**
+ * Whether going from `from` to `to` is a fragment navigation: the URLs differ at most in the hash and `to`
+ * has one. Browsers always perform those within the current document, whether intercepted or not.
+ */
+export function isFragmentNavigation(from: URL, to: URL): boolean {
+	if (to.hash === '') return false
+	const fromWithoutHash = new URL(from)
+	fromWithoutHash.hash = ''
+	const toWithoutHash = new URL(to)
+	toWithoutHash.hash = ''
+	return fromWithoutHash.href === toWithoutHash.href
+}

package/src/index.ts

@@ -19,6 +19,7 @@ export type {
 	BuzolaPageMap,
 	BuzolaPersistentParams,
 	EffectivePageParams,
+	InterceptInfo,
 	NavigateOptions,
 	NavigationAdapter,
 	PageParams,
@@ -29,6 +30,7 @@ export type {
 	RouteNode,
 	RouterState,
 	RouteTree,
+	ShouldInterceptFn,
 	StandardSchema,
 } from './engine/types.js'
 

package/src/react/hooks.ts

@@ -29,7 +29,7 @@ function useRouteContext() {
 /**
  * Type-safe navigation function.
  * Uses page IDs instead of URL patterns.
- * Persistent params are optional — resolved from current URL or fallback.
+ * Persistent params are optional: resolved from current URL or fallback.
  */
 type NavigateFn = <P extends RegisteredPage>(
 	to: P,
@@ -41,7 +41,7 @@ type NavigateFn = <P extends RegisteredPage>(
 
 /**
  * Hook to get a type-safe navigate function.
- * Navigates using page IDs — the router looks up the route pattern from the page registry.
+ * Navigates using page IDs: the router looks up the route pattern from the page registry.
  */
 export function useNavigate(): NavigateFn {
 	const router = useRouter()

package/src/react/link.tsx

@@ -2,7 +2,7 @@ import React, { useCallback, useEffect, useRef } 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 ──────────────────────────
+// ─── Link props type: always type-safe via page ID ───────────────────────────
 
 type LinkPropsBase = Omit<React.AnchorHTMLAttributes<HTMLAnchorElement>, 'href'> & {
 	/** Replace the current history entry instead of pushing. */
@@ -29,9 +29,9 @@ type LinkPropsBase = Omit<React.AnchorHTMLAttributes<HTMLAnchorElement>, 'href'>
 	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
+	 * - `'intent'`: preload on mouseEnter/focus (default)
+	 * - `'render'`: preload as soon as the Link renders
+	 * - `'none'`: disable prefetching
 	 */
 	prefetch?: 'intent' | 'render' | 'none'
 }
@@ -44,7 +44,7 @@ export type LinkProps<P extends RegisteredPage = RegisteredPage> = [keyof Effect
 
 /**
  * Type-safe link component.
- * Uses page IDs for navigation — the router looks up the route pattern from the page registry.
+ * 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.
  *

package/src/react/outlet.tsx

@@ -12,7 +12,7 @@ function DefaultNotFound(): React.ReactElement {
 		},
 		isDev
 			? [
-				React.createElement('h1', { key: 'h' }, '404 — Page Not Found'),
+				React.createElement('h1', { key: 'h' }, '404: Page Not Found'),
 				React.createElement('p', { key: 'p1' }, `No route matches "${typeof window !== 'undefined' ? window.location.pathname : ''}".`),
 				React.createElement('p', {
 					key: 'p2',
@@ -74,7 +74,7 @@ export function Outlet({ fallback, errorFallback, notFound }: OutletProps): Reac
 	}, [state, depth, effectiveDepth, matches, match, routeContext.params])
 
 	if (!match) {
-		// At root depth with no matches — show 404
+		// At root depth with no matches: show 404
 		if (depth === 0 && matches.length === 0) {
 			if (notFound === null) return null
 			return (notFound ?? React.createElement(DefaultNotFound, null)) as React.ReactElement

package/src/react/provider.tsx

@@ -1,7 +1,7 @@
 import React, { useCallback, useLayoutEffect, useMemo, useRef, useSyncExternalStore } from 'react'
 import { createBrowserNavigationAdapter } from '../engine/navigation-adapter.js'
 import { Router } from '../engine/router.js'
-import type { RouteMatch, RouteTree } from '../engine/types.js'
+import type { RouteMatch, RouteTree, ShouldInterceptFn } from '../engine/types.js'
 import { RouteContext, type RouteContextValue, RouterContext } from './context.js'
 import { Outlet } from './outlet.js'
 
@@ -25,12 +25,14 @@ export type BuzolaProviderProps =
 		middleware?: MiddlewareComponent
 	}
 	& (
-		| { router: Router; routes?: never; persistentParams?: never; pageRegistry?: never }
+		| { router: Router; routes?: never; persistentParams?: never; pageRegistry?: never; shouldIntercept?: never }
 		| {
 			router?: never
 			routes: RouteTree
 			persistentParams?: () => Record<string, string>
 			pageRegistry?: Record<string, string>
+			/** Decides per navigation whether the router handles it; see `RouterOptions.shouldIntercept`. */
+			shouldIntercept?: ShouldInterceptFn
 		}
 	)
 
@@ -39,6 +41,11 @@ export type BuzolaProviderProps =
  * Subscribes to router state and provides context to the React tree.
  */
 export function BuzolaProvider({ routes, children, middleware: Middleware, ...props }: BuzolaProviderProps): React.ReactElement {
+	// The router is created once, so it reads the latest prop through a ref rather than the first render's closure.
+	const shouldInterceptRef = useRef(props.shouldIntercept)
+	useLayoutEffect(() => {
+		shouldInterceptRef.current = props.shouldIntercept
+	})
 	const routerRef = useRef<Router | undefined>(props.router)
 	if (!routerRef.current) {
 		routerRef.current = new Router({
@@ -46,6 +53,7 @@ export function BuzolaProvider({ routes, children, middleware: Middleware, ...pr
 			adapter: createBrowserNavigationAdapter(),
 			persistentParams: props.persistentParams,
 			pageRegistry: props.pageRegistry,
+			shouldIntercept: info => shouldInterceptRef.current?.(info) ?? true,
 		})
 	}
 	const router = routerRef.current