sv-router 0.14.0 → 0.15.0

package/README.md

@@ -6,6 +6,7 @@
 
 [![npm](https://badgen.net/npm/v/sv-router)](https://www.npmjs.com/package/sv-router)
 [![install size](https://packagephobia.com/badge?p=sv-router)](https://packagephobia.com/result?p=sv-router)
+[![codecov](https://codecov.io/github/colinlienard/sv-router/graph/badge.svg?token=C9RBSEFO9S)](https://codecov.io/github/colinlienard/sv-router)
 
 A feature-rich yet intuitive routing library for Svelte single-page apps.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sv-router",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "description": "Modern Svelte Routing",
   "keywords": [
     "svelte",
@@ -36,29 +36,30 @@
     "esm-env": "^1.2.2"
   },
   "devDependencies": {
-    "@changesets/cli": "^2.29.8",
+    "@changesets/cli": "^2.30.0",
     "@eslint/js": "^10.0.1",
-    "@sveltejs/vite-plugin-svelte": "^6.2.4",
+    "@sveltejs/vite-plugin-svelte": "^7.0.0",
     "@testing-library/jest-dom": "^6.9.1",
     "@testing-library/svelte": "^5.3.1",
     "@testing-library/user-event": "^14.6.1",
-    "@types/node": "^24.10.13",
-    "eslint": "^10.0.0",
+    "@types/node": "^24.12.0",
+    "@vitest/coverage-v8": "^4.1.0",
+    "eslint": "^10.0.3",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-simple-import-sort": "^12.1.1",
-    "eslint-plugin-svelte": "^3.15.0",
-    "eslint-plugin-unicorn": "^63.0.0",
-    "globals": "^17.3.0",
-    "happy-dom": "^20.6.0",
+    "eslint-plugin-svelte": "^3.15.2",
+    "eslint-plugin-unicorn": "^64.0.0",
+    "globals": "^17.4.0",
+    "happy-dom": "^20.8.4",
     "prettier": "^3.8.1",
     "prettier-plugin-jsdoc": "^1.8.0",
-    "prettier-plugin-svelte": "^3.4.1",
-    "svelte-check": "^4.3.6",
+    "prettier-plugin-svelte": "^3.5.1",
+    "svelte-check": "^4.4.5",
     "type-testing": "^0.2.0",
-    "typescript": "^5.9.3",
-    "typescript-eslint": "^8.55.0",
-    "vite": "^7.3.1",
-    "vitest": "^4.0.18"
+    "typescript": "^6.0.2",
+    "typescript-eslint": "^8.57.1",
+    "vite": "^8.0.0",
+    "vitest": "^4.1.0"
   },
   "peerDependencies": {
     "svelte": "^5"
@@ -70,6 +71,7 @@
     "docs:build": "pnpm --filter docs build",
     "docs:preview": "pnpm --filter docs preview",
     "test": "vitest",
+    "test:coverage": "vitest run --coverage",
     "check": "svelte-check && pnpm -r check",
     "lint": "eslint . --max-warnings 0",
     "lint:fix": "eslint . --fix",

package/src/Router.svelte

@@ -1,6 +1,12 @@
 <script>
 	import { on } from 'svelte/events';
-	import { componentTree, init, onGlobalClick, onNavigate } from './create-router.svelte.js';
+	import {
+		componentTree,
+		init,
+		onBeforeUnload,
+		onGlobalClick,
+		onNavigate,
+	} from './create-router.svelte.js';
 	import RecursiveComponentTree from './RecursiveComponentTree.svelte';
 
 	/** @type {{ base?: string }} */
@@ -11,12 +17,16 @@
 	onNavigate();
 
 	$effect(() => {
-		const off1 = on(globalThis, 'popstate', () => onNavigate());
-		const off2 = on(globalThis, 'click', onGlobalClick);
+		const cleanup = [
+			on(globalThis, 'popstate', () => onNavigate()),
+			on(globalThis, 'beforeunload', onBeforeUnload),
+			on(globalThis, 'click', onGlobalClick),
+		];
 
 		return () => {
-			off1();
-			off2();
+			for (const clean of cleanup) {
+				clean();
+			}
 		};
 	});
 </script>

package/src/create-router.svelte.js

@@ -43,8 +43,17 @@ let params = $state({ value: {} });
 
 let meta = $state({ value: {} });
 
-/** @type {(() => boolean) | null} */
-let navigationBlocker = null;
+/**
+ * @type {Map<
+ * 	number,
+ * 	| (() => boolean | Promise<boolean>)
+ * 	| { beforeUnload?(): boolean; onNavigate(): boolean | Promise<boolean> }
+ * >}
+ */
+const navigationBlockers = new Map();
+
+let historyIndex = 0;
+let skipNextPopstate = false;
 
 /** @type {AbortController | null} */
 let currentNavigationController = null;
@@ -61,16 +70,33 @@ export function init(basename) {
 			base.name = '#';
 			if (!globalThis.location.href.includes('#')) {
 				url.hash = '/';
-				history.replaceState(history.state || {}, '', url.toString());
+				history.replaceState(
+					{ _routerIndex: historyIndex, _userState: history.state ?? null },
+					'',
+					url.toString(),
+				);
 			}
 		} else {
 			base.name = (basename.startsWith('/') ? '' : '/') + basename;
 			if (!url.pathname.startsWith(base.name)) {
 				url.pathname = join(base.name, url.pathname);
-				history.replaceState(history.state || {}, '', url.toString());
+				history.replaceState(
+					{ _routerIndex: historyIndex, _userState: history.state ?? null },
+					'',
+					url.toString(),
+				);
 			}
 		}
 	}
+	if (history.state?._routerIndex === undefined) {
+		history.replaceState(
+			{ _routerIndex: historyIndex, _userState: history.state ?? null },
+			'',
+			globalThis.location.href,
+		);
+	} else {
+		historyIndex = history.state._routerIndex;
+	}
 	Object.assign(location, updatedLocation());
 }
 
@@ -151,6 +177,16 @@ async function navigate(path, options = {}) {
 	return new Navigation(`${path}${serializeSearch(options?.search ?? '')}${options?.hash ?? ''}`);
 }
 
+/** @param {BeforeUnloadEvent} event */
+export function onBeforeUnload(event) {
+	for (const blocker of navigationBlockers.values()) {
+		if (typeof blocker !== 'object' || !blocker.beforeUnload) continue;
+		if (!blocker.beforeUnload()) {
+			event.preventDefault();
+		}
+	}
+}
+
 /**
  * @param {string} [path]
  * @param {import('./index.d.ts').NavigateOptions} options
@@ -160,20 +196,26 @@ export async function onNavigate(path, options = {}) {
 		throw new Error('Router not initialized: `createRouter` was not called.');
 	}
 
-	if (navigationBlocker) {
-		if (!navigationBlocker()) {
-			const url = new URL(globalThis.location.toString());
-			url.search = location.search;
-			url.hash = location.hash;
-			if (base.name === '#') {
-				url.hash = location.pathname;
-			} else {
-				url.pathname = location.pathname;
+	if (!path && skipNextPopstate) {
+		skipNextPopstate = false;
+		return;
+	}
+
+	if (navigationBlockers.size > 0) {
+		const popstateDelta = path ? 0 : historyIndex - (history.state?._routerIndex ?? 0);
+		for (const blocker of navigationBlockers.values()) {
+			const shouldNavigate = typeof blocker === 'object' ? blocker.onNavigate : blocker;
+			if (!(await shouldNavigate())) {
+				if (!path && popstateDelta !== 0) {
+					skipNextPopstate = true;
+					history.go(popstateDelta);
+				}
+				return;
 			}
-			globalThis.history.replaceState($state.snapshot(location.state) || {}, '', url.toString());
-			return;
 		}
-		navigationBlocker = null;
+		if (!path) {
+			historyIndex = history.state?._routerIndex ?? historyIndex;
+		}
 	}
 
 	if (pendingController && pendingController !== currentNavigationController) {
@@ -233,7 +275,12 @@ export async function onNavigate(path, options = {}) {
 			url.pathname = path;
 		}
 		const historyMethod = options.replace ? 'replaceState' : 'pushState';
-		globalThis.history[historyMethod](options.state || {}, '', url.toString());
+		if (historyMethod === 'pushState') historyIndex++;
+		globalThis.history[historyMethod](
+			{ _routerIndex: historyIndex, _userState: options.state ?? null },
+			'',
+			url.toString(),
+		);
 		syncSearchParams(search);
 	} else {
 		syncSearchParams(globalThis.location.search);
@@ -320,7 +367,16 @@ export function onGlobalClick(event) {
 	});
 }
 
-/** @param {() => boolean} callback */
+let navigationBlockId = 0;
+/**
+ * @param {(() => boolean | Promise<boolean>)
+ * 	| { beforeUnload?(): boolean; onNavigate(): boolean | Promise<boolean> }} callback
+ * @returns {() => void}
+ */
 export function blockNavigation(callback) {
-	navigationBlocker = callback;
+	const id = navigationBlockId++;
+	navigationBlockers.set(id, callback);
+	return () => {
+		navigationBlockers.delete(id);
+	};
 }

package/src/helpers/match-route.js

@@ -8,135 +8,206 @@
  * @typedef {import('../index.d.ts').Routes} Routes
  *
  * @typedef {import('../index.d.ts').RouteMeta} RouteMeta
- */
-
-/**
- * @param {string} pathname
- * @param {Routes} routes
- * @returns {{
+ *
+ * @typedef {{
  * 	match: RouteComponent | undefined;
  * 	layouts: LayoutComponent[];
  * 	hooks: Hooks[];
  * 	meta: RouteMeta;
  * 	params: Record<string, string>;
  * 	breakFromLayouts: boolean;
- * }}
+ * 	isCatchAll: boolean;
+ * }} MatchResult
+ */
+
+/**
+ * @param {string} pathname
+ * @param {Routes} routes
+ * @returns {MatchResult}
  */
 export function matchRoute(pathname, routes) {
-	// Remove trailing slash
 	if (pathname.length > 1 && pathname.endsWith('/')) {
 		pathname = pathname.slice(0, -1);
 	}
-	const pathParts = pathname.split('/').slice(1);
-	const allRoutes = sortRoutes(Object.keys(routes));
-
-	/** @type {RouteComponent | undefined} */
-	let match;
-
-	/** @type {LayoutComponent[]} */
-	let layouts = [];
-
-	/** @type {Hooks[]} */
-	let hooks = [];
 
-	/** @type {Record<string, string>} */
-	let params = {};
+	const pathParts = pathname.split('/').slice(1);
+	const sortedRoutes = sortRoutes(Object.keys(routes));
 
 	/** @type {RouteMeta} */
-	let meta = {};
-
+	let baseMeta = {};
 	const rootRoute = routes['/'];
 	if (rootRoute && typeof rootRoute === 'object' && 'meta' in rootRoute && rootRoute.meta) {
-		meta = { ...meta, ...rootRoute.meta };
+		baseMeta = { ...rootRoute.meta };
 	}
 
-	let breakFromLayouts = false;
+	/** @type {MatchResult | undefined} */
+	let catchAllFallback;
 
-	outer: for (const route of allRoutes) {
-		const routeParts = route.split('/');
-		if (routeParts[0] === '') routeParts.shift();
+	for (const route of sortedRoutes) {
+		const attempt = tryMatch(route, pathParts, pathname, routes, baseMeta);
+		if (!attempt) continue;
 
-		for (let [index, routePart] of routeParts.entries()) {
-			breakFromLayouts = routePart.startsWith('(') && routePart.endsWith(')');
-			if (breakFromLayouts) {
-				routePart = routePart.slice(1, -1);
-			}
+		if (attempt.fallback) {
+			if (!catchAllFallback) catchAllFallback = attempt.result;
+			continue;
+		}
 
-			const pathPart = pathParts[index];
-			if (routePart.startsWith(':')) {
-				params[routePart.slice(1)] = decodeURIComponent(pathPart);
-			} else if (routePart.startsWith('*')) {
-				const param = routePart.slice(1);
-				if (param) {
-					params[param] = pathParts.slice(index).map(decodeURIComponent).join('/');
-				}
-				if (breakFromLayouts) {
-					layouts = [];
-				} else if ('layout' in routes && routes.layout) {
-					layouts.push(routes.layout);
-				}
-				const resolvedPath = /** @type {keyof Routes} */ (
-					(index ? '/' : '') + routeParts.join('/')
-				);
-				match = /** @type {RouteComponent} */ (routes[resolvedPath]);
-				break outer;
-			} else if (routePart.toLowerCase() !== pathPart?.toLowerCase()) {
-				break;
-			}
+		return attempt.result;
+	}
 
-			if (index !== routeParts.length - 1) {
-				continue;
-			}
+	return (
+		catchAllFallback || {
+			match: undefined,
+			layouts: [],
+			hooks: [],
+			params: {},
+			meta: baseMeta,
+			breakFromLayouts: false,
+			isCatchAll: false,
+		}
+	);
+}
+
+/**
+ * Try to match a single route key against the path. Returns null if the route doesn't match.
+ *
+ * @param {string} route
+ * @param {string[]} pathParts
+ * @param {string} pathname
+ * @param {Routes} routes
+ * @param {RouteMeta} baseMeta
+ * @returns {{ result: MatchResult; fallback: boolean } | null}
+ */
+function tryMatch(route, pathParts, pathname, routes, baseMeta) {
+	const routeParts = route.split('/');
+	if (routeParts[0] === '') routeParts.shift();
 
-			const routeMatch = /** @type {RouteComponent} */ (
-				routes[/** @type {keyof Routes} */ ('/' + routeParts.join('/'))]
-			);
+	/** @type {Record<string, string>} */
+	const params = {};
+	/** @type {boolean} */
+	let breakFromLayouts;
+
+	for (let [index, routePart] of routeParts.entries()) {
+		breakFromLayouts = routePart.startsWith('(') && routePart.endsWith(')');
+		if (breakFromLayouts) {
+			routePart = routePart.slice(1, -1);
+		}
 
-			if (typeof routeMatch === 'function' && routeParts.length !== pathParts.length) {
-				continue;
-			}
+		const pathPart = pathParts[index];
+		const isLayoutGroup = routePart === '' && typeof routes['/'] !== 'function';
 
-			if (!breakFromLayouts && 'layout' in routes && routes.layout) {
-				layouts.push(routes.layout);
+		// Dynamic segment
+		if (routePart.startsWith(':')) {
+			params[routePart.slice(1)] = decodeURIComponent(pathPart);
+		}
+		// Catch-all segment
+		else if (routePart.startsWith('*')) {
+			const param = routePart.slice(1);
+			if (param) {
+				params[param] = pathParts.slice(index).map(decodeURIComponent).join('/');
 			}
+			const context = collectContext(routes, breakFromLayouts, baseMeta);
+			const resolvedPath = /** @type {keyof Routes} */ ((index ? '/' : '') + routeParts.join('/'));
+			return {
+				result: {
+					match: /** @type {RouteComponent} */ (routes[resolvedPath]),
+					...context,
+					params,
+					breakFromLayouts,
+					isCatchAll: true,
+				},
+				fallback: false,
+			};
+		}
+		// Static segment mismatch
+		else if (routePart.toLowerCase() !== pathPart?.toLowerCase() && !isLayoutGroup) {
+			return null;
+		}
 
-			if ('hooks' in routes && routes.hooks) {
-				hooks.push(routes.hooks);
-			}
+		// Continue matching next segment
+		if (index !== routeParts.length - 1) continue;
 
-			if ('meta' in routes && routes.meta) {
-				meta = { ...meta, ...routes.meta };
-			}
+		// Last segment — resolve the route value
+		const routeKey = /** @type {keyof Routes} */ ('/' + routeParts.join('/'));
+		const routeMatch = /** @type {RouteComponent} */ (routes[routeKey]);
 
-			if (typeof routeMatch === 'function') {
-				if (routeParts.length === pathParts.length) {
-					match = routeMatch;
-					break outer;
-				}
-				continue;
-			}
+		if (typeof routeMatch === 'function' && routeParts.length !== pathParts.length) {
+			return null;
+		}
 
-			const nestedPathname = '/' + pathParts.slice(index + 1).join('/');
-			const result = matchRoute(nestedPathname, routeMatch);
-			if (result.match) {
-				match = result.match;
-				params = { ...params, ...result.params };
-				hooks.push(...result.hooks);
-				meta = { ...meta, ...result.meta };
-				if (result.breakFromLayouts) {
-					layouts = [];
-					breakFromLayouts = true;
-				} else {
-					layouts.push(...result.layouts);
-				}
-			} else {
-				continue;
-			}
-			break outer;
+		const context = collectContext(routes, breakFromLayouts, baseMeta);
+
+		// Leaf route (component function)
+		if (typeof routeMatch === 'function') {
+			if (routeParts.length !== pathParts.length) return null;
+			return {
+				result: { match: routeMatch, ...context, params, breakFromLayouts, isCatchAll: false },
+				fallback: false,
+			};
 		}
+
+		// Nested routes — recurse
+		const nestedPathname = isLayoutGroup ? pathname : '/' + pathParts.slice(index + 1).join('/');
+		const nested = matchRoute(nestedPathname, routeMatch);
+		if (!nested.match) return null;
+
+		return {
+			result: mergeWithNested(context, nested, params, breakFromLayouts),
+			fallback: isLayoutGroup && nested.isCatchAll,
+		};
 	}
 
-	return { match, layouts, hooks, params, meta, breakFromLayouts };
+	return null;
+}
+
+/**
+ * Collect layouts, hooks, and meta from the current route level.
+ *
+ * @param {Routes} routes
+ * @param {boolean} breakFromLayouts
+ * @param {RouteMeta} baseMeta
+ * @returns {{ layouts: LayoutComponent[]; hooks: Hooks[]; meta: RouteMeta }}
+ */
+function collectContext(routes, breakFromLayouts, baseMeta) {
+	/** @type {LayoutComponent[]} */
+	const layouts = [];
+	/** @type {Hooks[]} */
+	const hooks = [];
+	let meta = { ...baseMeta };
+
+	if (!breakFromLayouts && 'layout' in routes && routes.layout) {
+		layouts.push(routes.layout);
+	}
+	if ('hooks' in routes && routes.hooks) {
+		hooks.push(routes.hooks);
+	}
+	if ('meta' in routes && routes.meta) {
+		meta = { ...meta, ...routes.meta };
+	}
+
+	return { layouts, hooks, meta };
+}
+
+/**
+ * Merge current level context with a nested match result.
+ *
+ * @param {{ layouts: LayoutComponent[]; hooks: Hooks[]; meta: RouteMeta }} context
+ * @param {MatchResult} nested
+ * @param {Record<string, string>} params
+ * @param {boolean} breakFromLayouts
+ * @returns {MatchResult}
+ */
+function mergeWithNested(context, nested, params, breakFromLayouts) {
+	const shouldBreak = nested.breakFromLayouts;
+	return {
+		match: nested.match,
+		layouts: shouldBreak ? [] : [...context.layouts, ...nested.layouts],
+		hooks: [...context.hooks, ...nested.hooks],
+		params: { ...params, ...nested.params },
+		meta: { ...context.meta, ...nested.meta },
+		breakFromLayouts: shouldBreak || breakFromLayouts,
+		isCatchAll: nested.isCatchAll,
+	};
 }
 
 /**

package/src/helpers/preload.js

@@ -157,6 +157,7 @@ export function preloadOnHover(routes) {
 
 			switch (link.dataset.preload) {
 				case '':
+				case 'true':
 				case 'hover': {
 					link.addEventListener('mouseenter', function callback() {
 						link.removeEventListener('mouseenter', callback);

package/src/helpers/utils.js

@@ -103,6 +103,14 @@ export function stripBase(pathname) {
 	return pathname;
 }
 
+/** @param {any} state */
+function getUserState(state) {
+	if (state && '_userState' in state) {
+		return state._userState;
+	}
+	return state;
+}
+
 export function updatedLocation() {
 	const pathname =
 		base.name === '#' ? globalThis.location.hash.slice(1) : globalThis.location.pathname;
@@ -110,7 +118,7 @@ export function updatedLocation() {
 	return {
 		pathname,
 		search: globalThis.location.search,
-		state: history.state,
+		state: getUserState(history.state),
 		hash,
 	};
 }

package/src/index.d.ts

@@ -43,13 +43,41 @@ export function serializeSearch(search: Search): string | undefined;
 export function createRouter<T extends Routes>(r: T): RouterApi<T>;
 
 /**
- * Block navigation until the callback returns `false`.
+ * Blocks navigation as long as the callback returns `false`.
+ *
+ * Returns a function that clears the navigation block.
+ *
+ * ```js
+ * $effect(() => blockNavigation(() => confirm('Are you sure you want to leave?')));
+ * ```
+ *
+ * The callback can also be async:
  *
  * ```js
- * blockNavigation(() => confirm('Are you sure you want to leave?'));
+ * $effect(() => blockNavigation(async () => await showConfirmModal()));
+ * ```
+ *
+ * If you also need to block tab close, use the object form to handle blocking for navigation and
+ * site unloading separately (site unloading cannot be blocked asynchronously):
+ *
+ * ```js
+ * $effect(() =>
+ * 	blockNavigation({
+ * 		beforeUnload() {
+ * 			return false;
+ * 		},
+ * 		async onNavigate() {
+ * 			return await askInModal();
+ * 		},
+ * 	}),
+ * );
  * ```
  */
-export function blockNavigation(callback: () => boolean): void;
+export function blockNavigation(
+	callback:
+		| (() => boolean | Promise<boolean>)
+		| { beforeUnload?(): boolean; onNavigate(): boolean | Promise<boolean> },
+): () => void;
 
 /**
  * The component that will render the current route. You can pass a `base` prop to set the base path
@@ -324,6 +352,10 @@ type StripNonRoutes<T extends Routes> = {
 						: K]: T[K] extends Routes ? StripNonRoutes<T[K]> : T[K];
 };
 
+type NormalizeSlashes<T extends string> = T extends `${infer A}//${infer B}`
+	? NormalizeSlashes<`${A}/${B}`>
+	: T;
+
 type RecursiveKeys<
 	T extends Routes,
 	Prefix extends string = '',
@@ -333,10 +365,10 @@ type RecursiveKeys<
 		? T[K] extends Routes
 			? RecursiveKeys<
 					T[K],
-					`${Prefix}${AnyParam extends true ? ReplaceParamWithString<K> : K}`,
+					NormalizeSlashes<`${Prefix}${AnyParam extends true ? ReplaceParamWithString<K> : K}`>,
 					AnyParam
 				>
-			: `${Prefix}${AnyParam extends true ? ReplaceParamWithString<K> : K}`
+			: NormalizeSlashes<`${Prefix}${AnyParam extends true ? ReplaceParamWithString<K> : K}`>
 		: never;
 }[keyof T];