svelte-navigator-lite 2.0.0 → 2.1.0

package/README.md

@@ -19,16 +19,19 @@ Define your routes and guards, then call `createRouter` on mount.
     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'             },
-                { name: 'edit',     pattern: '/event/:eventId/edit'        },
-                { name: 'login',    pattern: '/login',  guards: ['unauth'] },
-                { name: 'signup',   pattern: '/signup', guards: ['unauth'] },
+                { 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' },
@@ -40,6 +43,9 @@ Define your routes and guards, then call `createRouter` on mount.
 </script>
 
 <AppShell />
+{#if router.overlay}
+    <svelte:component this={currentOverlay} />
+{/if}
 ```
 
 ## Route patterns
@@ -81,14 +87,39 @@ import { router } from 'svelte-navigator-lite';
 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
 
-router.is('cal')              // true if current route === 'cal'
+router.is('cal')                 // true if current route === 'cal'
 router.matches(['cal', 'event']) // true if current route is in the list
 ```
 
 All properties are reactive — use them in Svelte templates or `$effect` blocks and they update automatically on navigation.
 
+## Overlays
+
+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.
+
+```typescript
+routes: [
+    { name: 'cal',   pattern: '/cal'                                },
+    { name: 'event', pattern: '/event/:eventId', overlay: true      },
+    { name: 'edit',  pattern: '/event/:eventId/edit', overlay: true },
+]
+```
+
+```svelte
+<!-- The base layout always renders -->
+<AppShell />
+
+<!-- Overlay components mount on top when their route is active -->
+{#if router.overlay}
+    <svelte:component this={overlayMap[router.route]} />
+{/if}
+```
+
+`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
 
 Guards are defined once in `createRouter` and referenced by name in route definitions.
@@ -96,9 +127,9 @@ Guards are defined once in `createRouter` and referenced by name in route defini
 ```typescript
 createRouter({
     routes: [
-        { name: 'cal',          pattern: '/cal',          guards: ['auth']  },
-        { name: 'login',        pattern: '/login',        guards: ['unauth'] },
-        { name: 'verify-email', pattern: '/verify-email', guards: ['unauth'] },
+        { 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: {
@@ -150,7 +181,7 @@ await goto('/some/path', { replaceState: true }); // replace instead of push
 
 ## Migrating from v1
 
-The `rootPath` + `segments` route definition is replaced by a single `pattern` string, and `routeGuards` inline on each route are replaced by named guards defined once.
+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.
 
 ```typescript
 // v1
@@ -161,6 +192,6 @@ The `rootPath` + `segments` route definition is replaced by a single `pattern` s
 }
 
 // v2
-{ name: 'edit', pattern: '/event/:eventId/edit', guards: ['auth'] }
-// with guard defined once in createRouter: auth: { condition: () => !auth.isValid(), redirectTo: 'login' }
+{ name: 'edit', pattern: '/event/:eventId/edit', guards: ['auth'], overlay: true }
+// guard defined once: auth: { condition: () => !auth.isValid(), redirectTo: 'login' }
 ```

package/dist/match.d.ts

@@ -5,6 +5,7 @@ type CompiledRoute = {
     regex: RegExp;
     paramNames: string[];
     guards: string[];
+    overlay: boolean;
 };
 export type RouteMatch = {
     name: string;

package/dist/match.js

@@ -20,6 +20,7 @@ export function compileRoutes(routes) {
             regex: new RegExp(`^${regexStr}/?$`),
             paramNames,
             guards: route.guards ?? [],
+            overlay: route.overlay ?? false,
         };
     });
 }

package/dist/router.svelte.d.ts

@@ -10,6 +10,7 @@ declare function _createRouter(): {
     readonly params: Record<string, string>;
     readonly searchParams: Record<string, string>;
     readonly notFound: boolean;
+    readonly overlay: boolean;
     is(route: string): boolean;
     matches(routes: string[]): boolean;
     parseUrl: (url: string) => void;
@@ -22,6 +23,7 @@ export declare const router: {
     readonly params: Record<string, string>;
     readonly searchParams: Record<string, string>;
     readonly notFound: boolean;
+    readonly overlay: boolean;
     is(route: string): boolean;
     matches(routes: string[]): boolean;
     parseUrl: (url: string) => void;

package/dist/router.svelte.js

@@ -70,6 +70,7 @@ function _createRouter() {
         get params() { return state.params; },
         get searchParams() { return state.searchParams; },
         get notFound() { return state.notFound; },
+        get overlay() { return compiled.find(r => r.name === state.current)?.overlay ?? false; },
         is(route) { return state.current === route; },
         matches(routes) { return routes.includes(state.current); },
         parseUrl,

package/dist/types.d.ts

@@ -2,6 +2,7 @@ export type RouteDefinition = {
     name: string;
     pattern: string;
     guards?: string[];
+    overlay?: boolean;
 };
 export type Guard = {
     condition: () => boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "svelte-navigator-lite",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "A lightweight router for Svelte 5",
   "type": "module",
   "main": "./dist/index.js",
@@ -12,7 +12,9 @@
       "types": "./dist/index.d.ts"
     }
   },
-  "files": ["dist"],
+  "files": [
+    "dist"
+  ],
   "scripts": {
     "build": "tsc",
     "dev": "tsc --watch",
@@ -29,10 +31,15 @@
     "typescript": "^5.0.0",
     "vitest": "^3.0.0"
   },
-  "keywords": ["svelte", "router", "navigation", "svelte5"],
+  "keywords": [
+    "svelte",
+    "router",
+    "navigation",
+    "svelte5"
+  ],
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/jeremyjfleming/svelte-navigator-lite"
+    "url": "git+https://github.com/jeremyjfleming/svelte-navigator-lite.git"
   }
 }