sv-router 0.0.7 → 0.1.0

package/README.md

@@ -1,3 +1,40 @@
+<div align="center">
+
+<img src="./docs/public/logo.svg" alt="" height="128px">
+
 # sv-router
 
-https://www.npmjs.com/package/sv-router
+[![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)
+
+A feature-rich yet intuitive routing library for Svelte single-page apps.
+
+[Documentation](https://sv-router.vercel.app/) • [Getting Started](https://sv-router.vercel.app/guide/getting-started) • [Reference](https://sv-router.vercel.app/reference)
+
+</div>
+
+---
+
+## Features
+
+- 🔒 **Typesafe navigation**: Get autocomplete and type checking for your routes.
+- 🔄 **Flexibility**: Choose between code-based or file-based routing approaches.
+- 🌿 **Nested routes**: Create complex layouts with ease.
+- 🔍 **Reactive search params**: For simpler state management in the URL.
+- 🛡️ **Hooks**: For navigation guards, data loading, or analytics tracking.
+- ⚡ **Performance**: Optimized for speed with built-in code splitting and preloading.
+- 🧩 **Familiar API**: Follows established conventions from popular meta frameworks.
+- 🪶 **Lightweight**: Minimal impact on your bundle size.
+- 🚀 **Made for Svelte 5**: True Svelte 5 implementation with the latest features.
+
+## Installation
+
+Add it to an existing Svelte project:
+
+```bash
+npm install sv-router
+```
+
+## License
+
+[MIT](./LICENSE) © Colin Lienard

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sv-router",
-  "version": "0.0.7",
+  "version": "0.1.0",
   "description": "Modern Svelte Routing",
   "keywords": [
     "svelte",

package/src/actions.svelte.js

@@ -1,14 +1,14 @@
 import { location } from './create-router.svelte.js';
 
 /** @type {import('./index.d.ts').IsActiveLink} */
-export function isActiveLink(node, { className = 'is-active' } = {}) {
+export function isActiveLink(node, { className = 'is-active', startsWith = false } = {}) {
 	if (node.tagName !== 'A') {
 		throw new Error('isActiveLink can only be used on <a> elements');
 	}
 
 	$effect(() => {
 		const pathname = new URL(node.href).pathname;
-		if (pathname === location.pathname) {
+		if (startsWith ? location.pathname.startsWith(pathname) : location.pathname === pathname) {
 			node.classList.add(className);
 		} else {
 			node.classList.remove(className);

package/src/create-router.svelte.js

@@ -113,6 +113,10 @@ export async function onNavigate(path, options = {}) {
 	syncSearchParams();
 	Object.assign(location, updatedLocation());
 
+	if (options.scrollToTop !== false) {
+		window.scrollTo({ top: 0, left: 0, behavior: options.scrollToTop });
+	}
+
 	for (const { afterLoad } of hooks) {
 		afterLoad?.();
 	}
@@ -130,12 +134,13 @@ export function onGlobalClick(event) {
 	if (url.origin !== currentOrigin) return;
 
 	event.preventDefault();
-	const { replace, state } = anchor.dataset;
+	const { replace, state, scrollToTop } = anchor.dataset;
 	onNavigate(url.pathname, {
 		replace: replace === '' || replace === 'true',
 		search: url.search,
 		state,
 		hash: url.hash,
+		scrollToTop: scrollToTop === 'false' ? false : /** @type ScrollBehavior */ (scrollToTop),
 	});
 }
 

package/src/gen/generate-router-code.js

@@ -9,18 +9,24 @@ import path from 'node:path';
  * }} GeneratedRoutes
  */
 
-const PARAM_FILENAME_REGEX = /\[(.*)\](\.lazy)?\.svelte$/; // [any].svelte, [any].lazy.svelte
-const CATCH_ALL_FILENAME_REGEX = /\[\.\.\.(.*)\](\.lazy)?\.svelte$/; // [...any].svelte, [...any].lazy.svelte
-const HOOKS_FILENAME_REGEX = /(hooks)(\.svelte)?\.(js|ts)$/; // hooks.js, hooks.svelte.js, hooks.ts, hooks.svelte.ts
+const FILENAME_REGEX = /(?<=[/.]|^)\(?([\w-]+)\)?(\.lazy)?\.svelte$/; // any.svelte, any.lazy.svelte, (any).svelte
+const PARAM_FILENAME_REGEX = /(?<=[/.]|^)\(?\[([\w-]+)\]\)?(\.lazy)?\.svelte$/; // [any].svelte, [any].lazy.svelte, ([any]).svelte
+const CATCH_ALL_FILENAME_REGEX = /(?<=[/.]|^)\(?\[\.\.\.([\w-]+)\]\)?(\.lazy)?\.svelte$/; // [...any].svelte, [...any].lazy.svelte, ([...any]).svelte
+const OUT_OF_LAYOUT_FILENAME_REGEX = /(?<=[/.]|^)\(\[\.?\.?\.?([\w-]+)\]\)(\.lazy)?\.svelte$/; // ([any]).svelte, ([...any]).lazy.svelte
+const HOOKS_FILENAME_REGEX = /(?<=[/.]|^)(hooks)(\.svelte)?\.(js|ts)$/; // hooks.js, hooks.svelte.js, hooks.ts, hooks.svelte.ts
 
 /**
  * @param {string} routesPath
  * @returns {string}
  */
 export function generateRouterCode(routesPath) {
-	const fileTree = buildFileTree(path.join(process.cwd(), routesPath));
+	const absoluteRoutesPath = path.join(process.cwd(), routesPath);
+	if (!fs.existsSync(absoluteRoutesPath)) {
+		throw new Error(`Routes directory not found at \`${routesPath}\``);
+	}
+	const fileTree = buildFileTree(absoluteRoutesPath);
 	const routeMap = createRouteMap(fileTree);
-	return createRouterCode(routeMap, path.join('..', routesPath));
+	return createRouterCode(routeMap, path.posix.join('..', routesPath));
 }
 
 /**
@@ -74,15 +80,20 @@ export function createRouteMap(fileTree, prefix = '') {
 				continue;
 			}
 
-			const catchAll = CATCH_ALL_FILENAME_REGEX.exec(entry);
-			if (catchAll) {
-				result['*' + catchAll[1]] = prefix + entry;
+			if (CATCH_ALL_FILENAME_REGEX.test(entry)) {
+				const replacement = OUT_OF_LAYOUT_FILENAME_REGEX.test(entry) ? '(*$1)' : '*$1';
+				let key = filePathToRoute(entry.replace(CATCH_ALL_FILENAME_REGEX, replacement));
+				if (!key.startsWith('*') && !key.startsWith('(*')) {
+					key = '/' + key;
+				}
+				result[key] = prefix + entry;
 				continue;
 			}
 
-			// Match [id].svelte
 			if (PARAM_FILENAME_REGEX.test(entry)) {
-				result['/' + filePathToRoute(entry.replace(PARAM_FILENAME_REGEX, ':$1'))] = prefix + entry;
+				const replacement = OUT_OF_LAYOUT_FILENAME_REGEX.test(entry) ? '(:$1)' : ':$1';
+				const key = '/' + filePathToRoute(entry.replace(PARAM_FILENAME_REGEX, replacement));
+				result[key] = prefix + entry;
 				continue;
 			}
 
@@ -176,7 +187,7 @@ export function pathToCorrectCasing(value) {
 		extractLastPart(CATCH_ALL_FILENAME_REGEX) ||
 		extractLastPart(PARAM_FILENAME_REGEX) ||
 		extractLastPart(HOOKS_FILENAME_REGEX) ||
-		extractLastPart(/([\w-]+)(\.lazy)?\.svelte$/);
+		extractLastPart(FILENAME_REGEX);
 	if (!lastPart) {
 		throw new Error(`Invalid filename: ${value}`);
 	}

package/src/gen/write-router-code.js

@@ -9,10 +9,6 @@ export function writeRouterCode() {
 			fs.mkdirSync(genConfig.genCodeDirPath);
 		}
 
-		// Write `.router/router.ts` file
-		const routerCode = generateRouterCode(genConfig.routesPath);
-		writeFileIfDifferent(genConfig.routerPath, routerCode);
-
 		// Write `.router/tsconfig.json` file
 		const tsConfig = {
 			compilerOptions: {
@@ -35,9 +31,20 @@ export function writeRouterCode() {
 		};
 		writeFileIfDifferent(genConfig.tsconfigPath, JSON.stringify(tsConfig, undefined, 2));
 
-		console.log('✅️ Routes generated');
+		// Write `.router/router.ts` file
+		const routerCode = generateRouterCode(genConfig.routesPath);
+		const written = writeFileIfDifferent(genConfig.routerPath, routerCode);
+
+		if (written) {
+			console.log('✅️ Routes generated');
+		} else {
+			console.log('✅️ Routes already up to date');
+		}
 	} catch (error) {
-		console.error('Error during routes generation:', error);
+		console.error(
+			'Error during routes generation:',
+			error instanceof Error ? error.message : String(error),
+		);
 	}
 }
 
@@ -48,5 +55,6 @@ export function writeRouterCode() {
 function writeFileIfDifferent(filePath, content) {
 	if (!fs.existsSync(filePath) || fs.readFileSync(filePath, 'utf8') !== content) {
 		fs.writeFileSync(filePath, content);
+		return true;
 	}
 }

package/src/helpers/is-active.js

@@ -7,25 +7,41 @@ import { constructPath } from './utils.js';
  * @returns {boolean}
  */
 export function isActive(pathname, params) {
+	return compare((a, b) => a === b, pathname, params);
+}
+
+/**
+ * @param {string} pathname
+ * @param {Record<string, string>} [params]
+ * @returns {boolean}
+ */
+isActive.startsWith = (pathname, params) => {
+	return compare((a, b) => a.startsWith(b), pathname, params);
+};
+
+/**
+ * @param {function(string, string): boolean} compareFn
+ * @param {string} pathname
+ * @param {Record<string, string>} [params]
+ * @returns {boolean}
+ */
+function compare(compareFn, pathname, params) {
 	if (!pathname.includes(':')) {
-		return pathname === location.pathname;
+		return compareFn(location.pathname, pathname);
 	}
 
 	if (params) {
-		return constructPath(pathname, params) === location.pathname;
+		return compareFn(location.pathname, constructPath(pathname, params));
 	}
 
 	const pathParts = pathname.split('/').slice(1);
 	const routeParts = location.pathname.split('/').slice(1);
-	if (pathParts.length !== routeParts.length) {
-		return false;
-	}
 	for (const [index, pathPart] of pathParts.entries()) {
 		const routePart = routeParts[index];
 		if (routePart.startsWith(':')) {
 			continue;
 		}
-		return pathPart === routePart;
+		return compareFn(pathPart, routePart);
 	}
 	return false;
 }

package/src/helpers/match-route.js

@@ -59,6 +59,9 @@ export function matchRoute(pathname, routes) {
 				if (param) {
 					params[param] = pathParts.slice(index).join('/');
 				}
+				if (breakFromLayouts) {
+					routePart = `(${routePart})`;
+				}
 				const resolvedPath = /** @type {keyof Routes} */ (
 					(index ? '/' : '') + routeParts.join('/')
 				);

package/src/index.d.ts

@@ -29,7 +29,7 @@ export const Router: Component;
  * The reactive search params of the URL. It is just a wrapper around `SvelteURLSearchParam` that
  * will update the url on change.
  */
-export const searchParams: URLSearchParams;
+export const searchParams: SearchParams;
 
 // eslint-disable-next-line @typescript-eslint/no-empty-object-type
 type BaseProps = {};
@@ -63,12 +63,15 @@ export type Hooks = {
 
 export type Routes = {
 	[_: `/${string}`]: RouteComponent | Routes;
-	[_: `*${string}`]: RouteComponent | undefined;
+	[_: `*${string}` | `(*${string})`]: RouteComponent | undefined;
 	layout?: LayoutComponent;
 	hooks?: Hooks;
 };
 
-export type IsActiveLink = Action<HTMLAnchorElement, { className?: string } | undefined>;
+export type IsActiveLink = Action<
+	HTMLAnchorElement,
+	{ className?: string; startsWith?: boolean } | undefined
+>;
 
 export type RouterApi<T extends Routes> = {
 	/**
@@ -114,7 +117,10 @@ export type RouterApi<T extends Routes> = {
 	 * @param path The route to check.
 	 * @param params The optional parameters to replace in the route.
 	 */
-	isActive<U extends Path<T>>(...args: IsActiveArgs<U>): boolean;
+	isActive: {
+		<U extends Path<T>>(...args: IsActiveArgs<U>): boolean;
+		startsWith<U extends Path<T>>(...args: IsActiveArgs<U>): boolean;
+	};
 	route: {
 		/**
 		 * An object containing the parameters of the current route.
@@ -156,9 +162,17 @@ export type NavigateOptions =
 			search?: string;
 			state?: string;
 			hash?: string;
+			scrollToTop?: ScrollBehavior | false;
 	  }
 	| undefined;
 
+export type SearchParams = URLSearchParams & {
+	append: (name: string, value: string, options?: { replace?: boolean }) => void;
+	delete: (name: string, value?: string, options?: { replace?: boolean }) => void;
+	set: (name: string, value: string, options?: { replace?: boolean }) => void;
+	sort: (options?: { replace?: boolean }) => void;
+};
+
 type NavigateArgs<T extends string> =
 	| (PathParams<T> extends never
 			? [T] | [T, NavigateOptions]
@@ -168,11 +182,13 @@ type NavigateArgs<T extends string> =
 type StripNonRoutes<T extends Routes> = {
 	[K in keyof T as K extends `*${string}`
 		? never
-		: K extends 'layout'
+		: K extends `(*${string})`
 			? never
-			: K extends 'hooks'
+			: K extends 'layout'
 				? never
-				: K]: T[K] extends Routes ? StripNonRoutes<T[K]> : T[K];
+				: K extends 'hooks'
+					? never
+					: K]: T[K] extends Routes ? StripNonRoutes<T[K]> : T[K];
 };
 
 type RecursiveKeys<T extends Routes, Prefix extends string = ''> = {
@@ -191,10 +207,14 @@ type RemoveParenthesis<T extends string> = T extends `${infer A}(${infer B})${in
 
 type ExtractParams<T extends string> = T extends `${string}:${infer Param}/${infer Rest}`
 	? Param | ExtractParams<`/${Rest}`>
-	: T extends `${string}:${infer Param}`
+	: T extends `${string}(:${infer Param})`
 		? Param
-		: T extends `${string}*${infer Param}`
-			? Param extends ''
-				? never
-				: Param
-			: never;
+		: T extends `${string}:${infer Param}`
+			? Param
+			: T extends `${string}(*${infer Param})`
+				? Param
+				: T extends `${string}*${infer Param}`
+					? Param extends ''
+						? never
+						: Param
+					: never;

package/src/search-params.svelte.js

@@ -2,15 +2,15 @@ import { SvelteURLSearchParams } from 'svelte/reactivity';
 
 let searchParams = new SvelteURLSearchParams(globalThis.location.search);
 
-/** @type {URLSearchParams} */
+/** @type {import('./index.js').SearchParams} */
 const shell = {
-	append(...args) {
-		searchParams.append(...args);
-		updateUrlSearchParams();
+	append(name, value, options) {
+		searchParams.append(name, value);
+		updateUrlSearchParams(options);
 	},
-	delete(...args) {
-		searchParams.delete(...args);
-		updateUrlSearchParams();
+	delete(name, value, options) {
+		searchParams.delete(name, value);
+		updateUrlSearchParams(options);
 	},
 	entries() {
 		return searchParams.entries();
@@ -31,13 +31,13 @@ const shell = {
 	keys() {
 		return searchParams.keys();
 	},
-	set(...args) {
-		searchParams.set(...args);
-		updateUrlSearchParams();
+	set(name, value, options) {
+		searchParams.set(name, value);
+		updateUrlSearchParams(options);
 	},
-	sort() {
+	sort(options) {
 		searchParams.sort();
-		updateUrlSearchParams();
+		updateUrlSearchParams(options);
 	},
 	toString() {
 		return searchParams.toString();
@@ -60,19 +60,17 @@ export function syncSearchParams() {
 	if (searchParams.toString() === newSearchParams.toString()) {
 		return;
 	}
-
-	for (const key of searchParams.keys()) {
-		searchParams.delete(key);
-	}
+	searchParams = new SvelteURLSearchParams();
 	for (const [key, value] of newSearchParams.entries()) {
 		searchParams.append(key, value);
 	}
 }
 
-function updateUrlSearchParams() {
+/** @param {{ replace?: boolean }} [options] */
+function updateUrlSearchParams(options) {
 	let url = globalThis.location.origin + globalThis.location.pathname;
 	if (searchParams.size > 0) {
 		url += '?' + searchParams.toString();
 	}
-	globalThis.history.pushState({}, '', url);
+	globalThis.history[options?.replace ? 'replaceState' : 'pushState']({}, '', url);
 }