svelte-navigator-lite 1.1.5 → 2.1.0

package/README.md

@@ -1,6 +1,6 @@
 # svelte-navigator-lite
 
-A lightweight, label-based router for Svelte 5. Define named routes that map to URL patterns, then use `router.route` reactively — not just to show components, but for any logic that depends on where you are.
+A lightweight, pattern-based router for Svelte 5. Routes are defined with familiar URL patterns, guards are reusable named functions, and the reactive `router` singleton integrates directly with Svelte runes.
 
 ## Installation
 
@@ -8,261 +8,190 @@ A lightweight, label-based router for Svelte 5. Define named routes that map to
 npm install svelte-navigator-lite
 ```
 
-## Setup
+## Quick start
 
-Call `createRouter` once at your app's entry point (e.g. `App.svelte`):
-
-```ts
-import { createRouter, router } from 'svelte-navigator-lite';
-import type { RouteList } from 'svelte-navigator-lite';
-
-const routes: RouteList = {
-    'login': {
-        rootPath: 'login',
-        segments: [],
-    },
-    'dashboard': {
-        rootPath: 'dashboard',
-        segments: [],
-    },
-};
-
-createRouter(routes, 'dashboard'); // second argument is the default/fallback route
-```
-
-Then use `router.route` anywhere in your Svelte components — it's a reactive Svelte 5 `$state` value:
+Define your routes and guards, then call `createRouter` on mount.
 
 ```svelte
-{#if router.is('login')}
-    <Login />
-{:else if router.is('dashboard')}
-    <Dashboard />
+<!-- App.svelte -->
+<script lang="ts">
+    import { onMount } from 'svelte';
+    import { createRouter, router } from 'svelte-navigator-lite';
+    import { auth } from '$stores/auth.svelte';
+    import AppShell from '$lib/components/AppShell.svelte';
+    import { overlayMap } from '$lib/routes';
+
+    let currentOverlay = $derived(overlayMap[router.route] ?? null);
+
+    onMount(() => {
+        createRouter({
+            routes: [
+                { name: 'cal',      pattern: '/cal'                                   },
+                { name: 'cal-date', pattern: '/cal/:mm/:dd/:yyyy'                     },
+                { name: 'event',    pattern: '/event/:eventId',   overlay: true       },
+                { name: 'edit',     pattern: '/event/:eventId/edit', overlay: true    },
+                { name: 'login',    pattern: '/login',  guards: ['unauth'], overlay: true },
+                { name: 'signup',   pattern: '/signup', guards: ['unauth'], overlay: true },
+            ],
+            guards: {
+                auth:   { condition: () => !auth.isValid(), redirectTo: 'login' },
+                unauth: { condition: () =>  auth.isValid(), redirectTo: 'cal'   },
+            },
+            fallback: 'cal',
+        });
+    });
+</script>
+
+<AppShell />
+{#if router.overlay}
+    <svelte:component this={currentOverlay} />
 {/if}
 ```
 
----
-
-## Defining Routes
-
-Every route has a `rootPath` — the first URL segment — and an array of `segments` for everything after it.
+## Route patterns
 
-### Static routes
+Patterns follow standard URL conventions.
 
-```ts
-'login': {
-    rootPath: 'login',  // matches /login
-    segments: [],
-}
-```
-
-### Dynamic params
+| Pattern | Example URL | Params |
+|---|---|---|
+| `/cal` | `/cal` | `{}` |
+| `/event/:eventId` | `/event/abc-123` | `{ eventId: 'abc-123' }` |
+| `/event/:eventId/edit` | `/event/abc-123/edit` | `{ eventId: 'abc-123' }` |
+| `/cal/:mm/:dd/:yyyy` | `/cal/05/13/2026` | `{ mm: '05', dd: '13', yyyy: '2026' }` |
+| `/settings/:page?` | `/settings` or `/settings/account` | `{}` or `{ page: 'account' }` |
 
-Use `name` to capture a URL segment into `router.params`:
+Append `?` to a param name to make it optional. Optional params must come at the end of the pattern.
 
-```ts
-'event': {
-    rootPath: 'event',
-    segments: [{ name: 'eventId' }],  // matches /event/123
-}
-// router.params.eventId === '123'
-```
+## Navigating
 
-### Enforced static segments
+```typescript
+import { router } from 'svelte-navigator-lite';
 
-Use `enforceVal` to require a literal string at that position:
+// Static route
+router.navigate('login');
 
-```ts
-'create-calendar': {
-    rootPath: 'calendar',
-    segments: [{ enforceVal: 'create' }],  // matches /calendar/create only
-}
-```
-
-### Mixed segments
-
-`enforceVal` and `name` segments can be combined in any order:
+// With path params
+router.navigate('event', { eventId: '123' });
 
-```ts
-'edit-event': {
-    rootPath: 'event',
-    segments: [
-        { name: 'eventId' },        // matches /event/:eventId/edit
-        { enforceVal: 'edit' },
-    ],
-}
+// With path params + search params
+router.navigate('edit', { eventId: '123' }, { from: 'calendar' });
 ```
 
-### Optional segments
+`navigate` returns a `Promise<void>`. Guards are evaluated before navigation — if a guard fires, the router redirects instead and original params are not forwarded.
 
-Add `optional: true` to make a trailing segment optional. Optional segments must come after all required segments.
+## Reading state
 
-```ts
-'event': {
-    rootPath: 'event',
-    segments: [
-        { name: 'eventId' },
-        { enforceVal: 'edit', optional: true },  // matches /event/123 AND /event/123/edit
-    ],
-}
-```
-
----
+```typescript
+import { router } from 'svelte-navigator-lite';
 
-## Search Params
+router.route        // current route name: string
+router.params       // path params: Record<string, string>
+router.searchParams // query params: Record<string, string>
+router.overlay      // true if the current route has overlay: true
+router.notFound     // true if the URL matched no route and the fallback was used
 
-Search params are automatically captured into `router.searchParams` when present in the URL. No configuration is needed — they never affect whether a route matches.
-
-```ts
-// /password-reset?token=abc  →  router.searchParams.token === 'abc'
-// /password-reset            →  router.searchParams === {}
+router.is('cal')                 // true if current route === 'cal'
+router.matches(['cal', 'event']) // true if current route is in the list
 ```
 
----
-
-## Navigating
-
-### `router.navigate(route, params?, searchParams?)`
+All properties are reactive — use them in Svelte templates or `$effect` blocks and they update automatically on navigation.
 
-Navigate to a named route. Path params fill dynamic segments; pass search params separately as the third argument.
-
-```ts
-router.navigate('event', { eventId: '123' });
-// → /event/123
+## Overlays
 
-router.navigate('password-reset', undefined, { token: 'abc123' });
-// → /password-reset?token=abc123
+Mark a route with `overlay: true` to indicate it renders on top of the base layout rather than replacing it. The router exposes `router.overlay` so your root component can conditionally render the overlay without any separate bookkeeping.
 
-router.navigate('event', { eventId: '123' }, { tab: 'details' });
-// → /event/123?tab=details
+```typescript
+routes: [
+    { name: 'cal',   pattern: '/cal'                                },
+    { name: 'event', pattern: '/event/:eventId', overlay: true      },
+    { name: 'edit',  pattern: '/event/:eventId/edit', overlay: true },
+]
 ```
 
-Throws if a required param is missing.
-
-### `goto(path)`
-
-Lower-level navigation to a raw path. Accepts an optional `{ replaceState: true }` option to replace instead of push.
-
-```ts
-import { goto } from 'svelte-navigator-lite';
+```svelte
+<!-- The base layout always renders -->
+<AppShell />
 
-goto('/login');
-goto('/login', { replaceState: true });
+<!-- Overlay components mount on top when their route is active -->
+{#if router.overlay}
+    <svelte:component this={overlayMap[router.route]} />
+{/if}
 ```
 
----
-
-## Route Guards
+`overlay` is purely a metadata flag — the router does not render anything itself. How overlays are displayed (modal, drawer, fullscreen panel, etc.) is entirely up to your components.
 
-Guards run before navigation and redirect if their condition is met. `fn` returning `true` triggers the redirect.
+## Guards
 
-```ts
-import type { RouteGuard } from 'svelte-navigator-lite';
+Guards are defined once in `createRouter` and referenced by name in route definitions.
 
-const guards = {
-    authenticated: {
-        fn: () => !auth.isValid(),   // redirect if NOT authenticated
-        redirectTo: 'login',
-    } satisfies RouteGuard,
-    unauthenticated: {
-        fn: () => auth.isValid(),    // redirect if already authenticated
-        redirectTo: 'dashboard',
-    } satisfies RouteGuard,
-};
-
-const routes: RouteList = {
-    'login': {
-        rootPath: 'login',
-        segments: [],
-        routeGuards: [guards.unauthenticated],
-    },
-    'dashboard': {
-        rootPath: 'dashboard',
-        segments: [],
-        routeGuards: [guards.authenticated],
+```typescript
+createRouter({
+    routes: [
+        { name: 'cal',          pattern: '/cal',          guards: ['auth']              },
+        { name: 'login',        pattern: '/login',        guards: ['unauth']            },
+        { name: 'verify-email', pattern: '/verify-email', guards: ['unauth']            },
+        { name: 'login-check',  pattern: '/login',        guards: ['unauth', 'emailCheck'] },
+    ],
+    guards: {
+        auth: {
+            condition: () => !auth.isValid(),
+            redirectTo: 'login',
+        },
+        unauth: {
+            condition: () => auth.isValid(),
+            redirectTo: 'cal',
+        },
+        emailCheck: {
+            condition: () => auth.containsCreds() && !auth.user?.verified,
+            redirectTo: 'verify-email',
+        },
     },
-};
+    fallback: 'cal',
+});
 ```
 
-Guards run in order and stop at the first redirect.
-
----
-
-## API Reference
-
-### `createRouter(routes, defaultRoute)`
-
-Registers all routes and sets the fallback route. Parses the current URL immediately. Must be called once before using `router`.
-
-### `router.route`
-
-The label of the currently matched route. Falls back to `defaultRoute` if no route matches.
-
-### `router.params`
+**`condition`** — called before entering the route. Return `true` to trigger the redirect.
 
-An object containing the captured path param values for the current route.
+**`redirectTo`** — route name to navigate to instead.
 
-### `router.searchParams`
+Multiple guards on a route are checked in order; the first one that fires wins. Guard redirects are also checked for guards (recursively), with cycle detection to prevent infinite loops.
 
-An object containing the search params present in the current URL. Empty object when none are present.
+## `page` store
 
-### `router.notFound`
+A Svelte readable store that emits `{ url: URL }` on every navigation. Compatible with SvelteKit's `$app/stores` page store shape.
 
-`true` when the current URL did not match any defined route and the router fell back to `defaultRoute`. Use this to render a 404 state without needing a dedicated catch-all route.
+```typescript
+import { page } from 'svelte-navigator-lite';
 
-```svelte
-{#if router.notFound}
-    <NotFound />
-{:else if router.is('dashboard')}
-    <Dashboard />
-{/if}
+page.subscribe(({ url }) => {
+    console.log(url.pathname);
+});
 ```
 
-### `router.navigate(route, params?, searchParams?)`
-
-Navigate to a named route, applying guards and building the URL from the route definition.
-
-### `router.is(route)`
+## `goto`
 
-Returns `true` if `router.route === route`. Useful for active link styling.
+Low-level path navigation. Prefer `router.navigate` for named routes.
 
-```ts
-class:active={router.is('dashboard')}
-```
-
-### `router.matches(routes)`
-
-Returns `true` if `router.route` is any of the provided route names.
+```typescript
+import { goto } from 'svelte-navigator-lite';
 
-```ts
-class:active={router.matches(['dashboard', 'settings'])}
+await goto('/some/path');
+await goto('/some/path', { replaceState: true }); // replace instead of push
 ```
 
-### `router.registerRoute(name, route)`
+## Migrating from v1
 
-Register a new route.
-```ts
-registerRoute('settings', {
-    rootPath: 'settings',
-    segments: [],
-    routeGuards: [guards.authenticated],
-})
+The `rootPath` + `segments` route definition is replaced by a single `pattern` string, `routeGuards` inline on each route are replaced by named guards defined once, and the new `overlay` flag replaces any separate modal-route maps you maintained manually.
 
-### `page`
-
-A readable Svelte store that emits `{ url: URL }` and updates on every navigation. Useful when you need the raw URL.
-
-```ts
-import { page } from 'svelte-navigator-lite';
+```typescript
+// v1
+'edit': {
+    rootPath: 'event',
+    segments: [{ name: 'eventId' }, { enforceVal: 'edit' }],
+    routeGuards: [{ fn: () => !auth.isValid(), redirectTo: 'login' }],
+}
 
-$page.url.pathname;
+// v2
+{ name: 'edit', pattern: '/event/:eventId/edit', guards: ['auth'], overlay: true }
+// guard defined once: auth: { condition: () => !auth.isValid(), redirectTo: 'login' }
 ```
-
----
-
-## Matching Rules
-
-- Routes are matched in the order they are defined — first match wins.
-- `rootPath` is always required and must match the first URL segment exactly.
-- Segment count must be between `required segments + 1` and `total segments + 1` (the `+1` accounts for `rootPath`).
-- A route with no segments only matches its `rootPath` with nothing after it (e.g. `/login` not `/login/extra`).
-- Unmatched URLs fall back to the `defaultRoute`.

package/dist/index.d.ts

@@ -1,2 +1,2 @@
-export { createRouter, router, page, goto } from './router.svelte';
-export type { Route, RouteList, Router, RouteGuard } from './router.svelte';
+export { createRouter, router, page, goto, _createRouter } from './router.svelte.js';
+export type { RouteDefinition, Guard, RouterConfig } from './types.js';

package/dist/index.js

@@ -1,2 +1 @@
-// svelte-navigator-lite
-export { createRouter, router, page, goto } from './router.svelte';
+export { createRouter, router, page, goto, _createRouter } from './router.svelte.js';

package/dist/match.d.ts

@@ -0,0 +1,17 @@
+import type { RouteDefinition } from './types.js';
+type CompiledRoute = {
+    name: string;
+    pattern: string;
+    regex: RegExp;
+    paramNames: string[];
+    guards: string[];
+    overlay: boolean;
+};
+export type RouteMatch = {
+    name: string;
+    params: Record<string, string>;
+};
+export declare function compileRoutes(routes: RouteDefinition[]): CompiledRoute[];
+export declare function matchPath(compiled: CompiledRoute[], pathname: string): RouteMatch | null;
+export declare function buildPath(pattern: string, params?: Record<string, string>): string;
+export {};

package/dist/match.js

@@ -0,0 +1,55 @@
+export function compileRoutes(routes) {
+    return routes.map(route => {
+        const paramNames = [];
+        const regexStr = route.pattern
+            // Escape regex special chars (except : and /)
+            .replace(/[.+^${}()|[\]\\]/g, '\\$&')
+            // Optional params /:name? — make the whole slash+segment optional together
+            .replace(/\/:([a-zA-Z_][a-zA-Z0-9_]*)\?/g, (_, name) => {
+            paramNames.push(name);
+            return '(?:/([^/]*))?';
+        })
+            // Required params :name
+            .replace(/:([a-zA-Z_][a-zA-Z0-9_]*)/g, (_, name) => {
+            paramNames.push(name);
+            return '([^/]+)';
+        });
+        return {
+            name: route.name,
+            pattern: route.pattern,
+            regex: new RegExp(`^${regexStr}/?$`),
+            paramNames,
+            guards: route.guards ?? [],
+            overlay: route.overlay ?? false,
+        };
+    });
+}
+export function matchPath(compiled, pathname) {
+    for (const route of compiled) {
+        const m = pathname.match(route.regex);
+        if (!m)
+            continue;
+        const params = {};
+        route.paramNames.forEach((name, i) => {
+            const val = m[i + 1];
+            if (val)
+                params[name] = decodeURIComponent(val);
+        });
+        return { name: route.name, params };
+    }
+    return null;
+}
+// Build a URL path from a pattern and params.
+// Optional params omitted from params are dropped cleanly.
+export function buildPath(pattern, params = {}) {
+    const path = pattern
+        .replace(/:([a-zA-Z_][a-zA-Z0-9_]*)\?/g, (_, name) => name in params ? encodeURIComponent(params[name]) : '')
+        .replace(/:([a-zA-Z_][a-zA-Z0-9_]*)/g, (_, name) => {
+        if (!(name in params))
+            throw new Error(`[router] missing required param "${name}" for pattern "${pattern}"`);
+        return encodeURIComponent(params[name]);
+    })
+        .replace(/\/+/g, '/') // collapse double slashes left by dropped optional params
+        .replace(/\/$/, ''); // strip trailing slash
+    return path || '/';
+}

package/dist/match.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/match.test.js

@@ -0,0 +1,120 @@
+import { describe, it, expect } from 'vitest';
+import { compileRoutes, matchPath, buildPath } from './match';
+// ─── matchPath ────────────────────────────────────────────────────────────────
+describe('matchPath — static routes', () => {
+    it('matches an exact path', () => {
+        const compiled = compileRoutes([{ name: 'login', pattern: '/login' }]);
+        expect(matchPath(compiled, '/login')).toEqual({ name: 'login', params: {} });
+    });
+    it('does not match a different path', () => {
+        const compiled = compileRoutes([{ name: 'login', pattern: '/login' }]);
+        expect(matchPath(compiled, '/signup')).toBeNull();
+    });
+    it('returns null when no routes match', () => {
+        const compiled = compileRoutes([{ name: 'login', pattern: '/login' }]);
+        expect(matchPath(compiled, '/unknown/path')).toBeNull();
+    });
+    it('returns the first matching route', () => {
+        const compiled = compileRoutes([
+            { name: 'first', pattern: '/cal' },
+            { name: 'second', pattern: '/cal' },
+        ]);
+        expect(matchPath(compiled, '/cal')?.name).toBe('first');
+    });
+});
+describe('matchPath — required params', () => {
+    it('captures a single param', () => {
+        const compiled = compileRoutes([{ name: 'event', pattern: '/event/:eventId' }]);
+        expect(matchPath(compiled, '/event/abc-123')).toEqual({
+            name: 'event',
+            params: { eventId: 'abc-123' },
+        });
+    });
+    it('does not match when a required param is absent', () => {
+        const compiled = compileRoutes([{ name: 'event', pattern: '/event/:eventId' }]);
+        expect(matchPath(compiled, '/event')).toBeNull();
+    });
+    it('captures multiple params', () => {
+        const compiled = compileRoutes([{ name: 'cal-date', pattern: '/cal/:mm/:dd/:yyyy' }]);
+        expect(matchPath(compiled, '/cal/05/13/2026')).toEqual({
+            name: 'cal-date',
+            params: { mm: '05', dd: '13', yyyy: '2026' },
+        });
+    });
+    it('captures params mixed with literal segments', () => {
+        const compiled = compileRoutes([{ name: 'edit', pattern: '/event/:eventId/edit' }]);
+        expect(matchPath(compiled, '/event/99/edit')).toEqual({
+            name: 'edit',
+            params: { eventId: '99' },
+        });
+    });
+    it('does not match when a literal segment differs', () => {
+        const compiled = compileRoutes([{ name: 'edit', pattern: '/event/:eventId/edit' }]);
+        expect(matchPath(compiled, '/event/99/delete')).toBeNull();
+    });
+    it('does not match when there are extra segments', () => {
+        const compiled = compileRoutes([{ name: 'event', pattern: '/event/:eventId' }]);
+        expect(matchPath(compiled, '/event/99/unexpected')).toBeNull();
+    });
+    it('differentiates routes with the same prefix by segment count', () => {
+        const compiled = compileRoutes([
+            { name: 'event', pattern: '/event/:eventId' },
+            { name: 'edit', pattern: '/event/:eventId/edit' },
+        ]);
+        expect(matchPath(compiled, '/event/99')?.name).toBe('event');
+        expect(matchPath(compiled, '/event/99/edit')?.name).toBe('edit');
+    });
+    it('URL-decodes param values', () => {
+        const compiled = compileRoutes([{ name: 'search', pattern: '/search/:query' }]);
+        expect(matchPath(compiled, '/search/hello%20world')?.params.query).toBe('hello world');
+    });
+});
+describe('matchPath — optional params', () => {
+    const compiled = compileRoutes([{ name: 'settings', pattern: '/settings/:page?' }]);
+    it('matches when the optional param is present', () => {
+        expect(matchPath(compiled, '/settings/account')).toEqual({
+            name: 'settings',
+            params: { page: 'account' },
+        });
+    });
+    it('matches when the optional param is absent', () => {
+        const result = matchPath(compiled, '/settings');
+        expect(result?.name).toBe('settings');
+        expect(result?.params).not.toHaveProperty('page');
+    });
+});
+// ─── buildPath ────────────────────────────────────────────────────────────────
+describe('buildPath — static patterns', () => {
+    it('returns the pattern as-is', () => {
+        expect(buildPath('/login')).toBe('/login');
+    });
+    it('returns / for an empty pattern', () => {
+        expect(buildPath('')).toBe('/');
+    });
+});
+describe('buildPath — required params', () => {
+    it('substitutes a single param', () => {
+        expect(buildPath('/event/:eventId', { eventId: '42' })).toBe('/event/42');
+    });
+    it('substitutes multiple params', () => {
+        expect(buildPath('/cal/:mm/:dd/:yyyy', { mm: '05', dd: '13', yyyy: '2026' }))
+            .toBe('/cal/05/13/2026');
+    });
+    it('substitutes params among literal segments', () => {
+        expect(buildPath('/event/:eventId/edit', { eventId: '99' })).toBe('/event/99/edit');
+    });
+    it('URL-encodes param values', () => {
+        expect(buildPath('/search/:query', { query: 'hello world' })).toBe('/search/hello%20world');
+    });
+    it('throws when a required param is missing', () => {
+        expect(() => buildPath('/event/:eventId', {})).toThrow('missing required param "eventId"');
+    });
+});
+describe('buildPath — optional params', () => {
+    it('inserts the value when the optional param is provided', () => {
+        expect(buildPath('/settings/:page?', { page: 'account' })).toBe('/settings/account');
+    });
+    it('drops the segment cleanly when the optional param is absent', () => {
+        expect(buildPath('/settings/:page?', {})).toBe('/settings');
+    });
+});