@llui/router 0.0.1 → 0.0.3

package/README.md

@@ -1,13 +1,107 @@
 # @llui/router
 
-Router for [LLui](https://github.com/fponticelli/llui).
-
-Structured path matching, history/hash mode, `routing.link()` helper, `routing.listener()` for popstate, and `createHandler()` for mergeHandlers integration.
+Router for [LLui](https://github.com/fponticelli/llui). Structured path matching with history and hash mode support.
 
 ```bash
 pnpm add @llui/router
 ```
 
+## Usage
+
+```ts
+import { route, param, rest, createRouter, connectRouter } from '@llui/router'
+import { div, a } from '@llui/dom'
+
+// Define routes
+const home = route([])
+const search = route(['search'], (b) => b, ['q', 'page'])
+const detail = route(['item', param('id')])
+const docs = route(['docs', rest('path')])
+
+// Create router
+const router = createRouter({ home, search, detail, docs }, { mode: 'history' })
+
+// Connect to effects system
+const routing = connectRouter(router)
+```
+
+## API
+
+### Route Definition
+
+| Function                                | Description                                               |
+| --------------------------------------- | --------------------------------------------------------- |
+| `route(segments, builder?, queryKeys?)` | Define a route with path segments and optional query keys |
+| `param(name)`                           | Named path parameter (e.g. `/item/:id`)                   |
+| `rest(name)`                            | Rest parameter capturing remaining path                   |
+
+### Router
+
+| Function                       | Description                                             |
+| ------------------------------ | ------------------------------------------------------- |
+| `createRouter(routes, config)` | Create router instance (`history` or `hash` mode)       |
+| `connectRouter(router)`        | Connect router to LLui effects, returns routing helpers |
+
+### Routing Helpers (from connectRouter)
+
+| Method / Effect                       | Description                                                   |
+| ------------------------------------- | ------------------------------------------------------------- |
+| `.link(send, route, attrs, children)` | Render a navigation link with client-side routing             |
+| `.listener(send)`                     | Popstate listener -- call in `view()` to react to URL changes |
+| `.handleEffect`                       | Effect handler plugin for navigate/push/replace effects       |
+| `.push(route)`                        | Push navigation effect                                        |
+| `.replace(route)`                     | Replace navigation effect                                     |
+| `.back()`                             | Navigate back effect                                          |
+| `.forward()`                          | Navigate forward effect                                       |
+| `.scroll()`                           | Scroll restoration effect                                     |
+
+## Guards
+
+Router guards let you block or redirect navigation. Pass `beforeEnter` and/or `beforeLeave` to `connectRouter`:
+
+```ts
+const routing = connectRouter(router, {
+  // Called before entering a new route
+  beforeEnter(to, from) {
+    // Return void   → allow
+    // Return false  → block
+    // Return Route  → redirect
+  },
+  // Called before leaving the current route
+  beforeLeave(from, to) {
+    // Return true  → allow
+    // Return false → block
+  },
+})
+```
+
+Guards run in the effect handler and the popstate listener, keeping `update()` pure.
+
+### Auth guard
+
+```ts
+const routing = connectRouter(router, {
+  beforeEnter(to) {
+    if (to.page === 'admin' && !isLoggedIn()) {
+      return { page: 'login' }
+    }
+  },
+})
+```
+
+### Unsaved changes guard
+
+```ts
+const routing = connectRouter(router, {
+  beforeLeave(from) {
+    if (from.page === 'editor' && hasUnsavedChanges()) {
+      return confirm('Discard unsaved changes?')
+    }
+    return true
+  },
+})
+```
+
 ## License
 
 MIT

package/dist/connect.d.ts

@@ -6,6 +6,21 @@ export interface RouterEffect {
     x?: number;
     y?: number;
 }
+export interface ConnectOptions<R> {
+    /**
+     * Called before entering a new route. Return:
+     * - `void` / `undefined` → allow navigation
+     * - `false` → block navigation (stay on current route)
+     * - a different `Route` → redirect to that route
+     */
+    beforeEnter?: (to: R, from: R | null) => R | false | void;
+    /**
+     * Called before leaving the current route. Return:
+     * - `true` → allow navigation
+     * - `false` → block (e.g. unsaved changes prompt)
+     */
+    beforeLeave?: (from: R, to: R) => boolean;
+}
 export interface ConnectedRouter<R> {
     /** Effect: push a new route onto history */
     push(route: R): RouterEffect;
@@ -50,5 +65,5 @@ export interface ConnectedRouter<R> {
         onNavigate: (state: S, route: R) => [S, E[]];
     }): (state: S, msg: M) => [S, E[]] | null;
 }
-export declare function connectRouter<R>(router: Router<R>): ConnectedRouter<R>;
+export declare function connectRouter<R>(router: Router<R>, options?: ConnectOptions<R>): ConnectedRouter<R>;
 //# sourceMappingURL=connect.d.ts.map

package/dist/connect.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"connect.d.ts","sourceRoot":"","sources":["../src/connect.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,SAAS,CAAA;AAKrC,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,UAAU,CAAA;IAChB,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,GAAG,QAAQ,CAAA;IAC1D,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,CAAC,CAAC,EAAE,MAAM,CAAA;IACV,CAAC,CAAC,EAAE,MAAM,CAAA;CACX;AAED,MAAM,WAAW,eAAe,CAAC,CAAC;IAChC,4CAA4C;IAC5C,IAAI,CAAC,KAAK,EAAE,CAAC,GAAG,YAAY,CAAA;IAC5B,4CAA4C;IAC5C,OAAO,CAAC,KAAK,EAAE,CAAC,GAAG,YAAY,CAAA;IAC/B,sBAAsB;IACtB,IAAI,IAAI,YAAY,CAAA;IACpB,yBAAyB;IACzB,OAAO,IAAI,YAAY,CAAA;IACvB,iCAAiC;IACjC,MAAM,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,YAAY,CAAA;IAE1C,8DAA8D;IAC9D,YAAY,EAAE,CAAC,GAAG,EAAE;QAAE,MAAM,EAAE;YAAE,IAAI,EAAE,MAAM,CAAA;SAAE,CAAC;QAAC,IAAI,EAAE,OAAO,CAAC;QAAC,MAAM,EAAE,WAAW,CAAA;KAAE,KAAK,OAAO,CAAA;IAEhG;;;OAGG;IACH,QAAQ,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,GAAG,EAAE,CAAC,KAAK,IAAI,EAAE,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,GAAG,IAAI,EAAE,CAAA;IAEzE;;;OAGG;IACH,IAAI,CAAC,CAAC,EACJ,IAAI,EAAE,CAAC,GAAG,EAAE,CAAC,KAAK,IAAI,EACtB,KAAK,EAAE,CAAC,EACR,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,QAAQ,EAAE,IAAI,EAAE,EAChB,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,GAC3B,WAAW,CAAA;IAEd;;;OAGG;IACH,aAAa,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,MAAM,EAAE;QAC7B,mDAAmD;QACnD,OAAO,CAAC,EAAE,MAAM,CAAA;QAChB,iCAAiC;QACjC,QAAQ,EAAE,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,CAAA;QACvB,oCAAoC;QACpC,KAAK,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,KAAK,CAAC,CAAA;QACjC,8CAA8C;QAC9C,UAAU,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAA;KAC7C,GAAG,CAAC,KAAK,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,GAAG,IAAI,CAAA;CAC1C;AAED,wBAAgB,aAAa,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,GAAG,eAAe,CAAC,CAAC,CAAC,CAgHtE"}
+{"version":3,"file":"connect.d.ts","sourceRoot":"","sources":["../src/connect.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,SAAS,CAAA;AAKrC,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,UAAU,CAAA;IAChB,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,GAAG,QAAQ,CAAA;IAC1D,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,CAAC,CAAC,EAAE,MAAM,CAAA;IACV,CAAC,CAAC,EAAE,MAAM,CAAA;CACX;AAED,MAAM,WAAW,cAAc,CAAC,CAAC;IAC/B;;;;;OAKG;IACH,WAAW,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,GAAG,IAAI,KAAK,CAAC,GAAG,KAAK,GAAG,IAAI,CAAA;IACzD;;;;OAIG;IACH,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,KAAK,OAAO,CAAA;CAC1C;AAED,MAAM,WAAW,eAAe,CAAC,CAAC;IAChC,4CAA4C;IAC5C,IAAI,CAAC,KAAK,EAAE,CAAC,GAAG,YAAY,CAAA;IAC5B,4CAA4C;IAC5C,OAAO,CAAC,KAAK,EAAE,CAAC,GAAG,YAAY,CAAA;IAC/B,sBAAsB;IACtB,IAAI,IAAI,YAAY,CAAA;IACpB,yBAAyB;IACzB,OAAO,IAAI,YAAY,CAAA;IACvB,iCAAiC;IACjC,MAAM,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,YAAY,CAAA;IAE1C,8DAA8D;IAC9D,YAAY,EAAE,CAAC,GAAG,EAAE;QAAE,MAAM,EAAE;YAAE,IAAI,EAAE,MAAM,CAAA;SAAE,CAAC;QAAC,IAAI,EAAE,OAAO,CAAC;QAAC,MAAM,EAAE,WAAW,CAAA;KAAE,KAAK,OAAO,CAAA;IAEhG;;;OAGG;IACH,QAAQ,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,GAAG,EAAE,CAAC,KAAK,IAAI,EAAE,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,GAAG,IAAI,EAAE,CAAA;IAEzE;;;OAGG;IACH,IAAI,CAAC,CAAC,EACJ,IAAI,EAAE,CAAC,GAAG,EAAE,CAAC,KAAK,IAAI,EACtB,KAAK,EAAE,CAAC,EACR,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,QAAQ,EAAE,IAAI,EAAE,EAChB,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,GAC3B,WAAW,CAAA;IAEd;;;OAGG;IACH,aAAa,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,MAAM,EAAE;QAC7B,mDAAmD;QACnD,OAAO,CAAC,EAAE,MAAM,CAAA;QAChB,iCAAiC;QACjC,QAAQ,EAAE,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,CAAA;QACvB,oCAAoC;QACpC,KAAK,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,KAAK,CAAC,CAAA;QACjC,8CAA8C;QAC9C,UAAU,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAA;KAC7C,GAAG,CAAC,KAAK,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,GAAG,IAAI,CAAA;CAC1C;AAED,wBAAgB,aAAa,CAAC,CAAC,EAC7B,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,EACjB,OAAO,CAAC,EAAE,cAAc,CAAC,CAAC,CAAC,GAC1B,eAAe,CAAC,CAAC,CAAC,CAyJpB"}

package/dist/connect.js

@@ -1,23 +1,57 @@
 import { a, onMount } from '@llui/dom';
-export function connectRouter(router) {
+export function connectRouter(router, options) {
+    let currentRoute = null;
+    /**
+     * Run guards for a navigation to `newRoute`. Returns the final route
+     * to navigate to, or `null` if navigation should be blocked.
+     */
+    function runGuards(newRoute) {
+        if (options?.beforeLeave && currentRoute !== null) {
+            if (!options.beforeLeave(currentRoute, newRoute))
+                return null;
+        }
+        if (options?.beforeEnter) {
+            const result = options.beforeEnter(newRoute, currentRoute);
+            if (result === false)
+                return null;
+            if (result !== undefined && result !== null && typeof result === 'object') {
+                return result;
+            }
+        }
+        return newRoute;
+    }
     function applyEffect(effect) {
         switch (effect.action) {
-            case 'push':
+            case 'push': {
+                const target = router.match(effect.path);
+                const finalRoute = runGuards(target);
+                if (finalRoute === null)
+                    return;
+                const finalPath = router.href(finalRoute);
                 if (router.mode === 'hash') {
-                    location.hash = effect.path;
+                    location.hash = finalPath;
                 }
                 else {
-                    history.pushState(null, '', effect.path);
+                    history.pushState(null, '', finalPath);
                 }
+                currentRoute = finalRoute;
                 break;
-            case 'replace':
+            }
+            case 'replace': {
+                const target = router.match(effect.path);
+                const finalRoute = runGuards(target);
+                if (finalRoute === null)
+                    return;
+                const finalPath = router.href(finalRoute);
                 if (router.mode === 'hash') {
-                    location.replace(effect.path);
+                    location.replace(finalPath);
                 }
                 else {
-                    history.replaceState(null, '', effect.path);
+                    history.replaceState(null, '', finalPath);
                 }
+                currentRoute = finalRoute;
                 break;
+            }
             case 'back':
                 history.back();
                 break;
@@ -58,7 +92,17 @@ export function connectRouter(router) {
                 const handler = () => {
                     const input = router.mode === 'hash' ? location.hash : location.pathname + location.search;
                     const route = router.match(input);
-                    send(factory(route));
+                    const finalRoute = runGuards(route);
+                    if (finalRoute === null) {
+                        // Guard blocked — restore previous URL
+                        if (currentRoute !== null) {
+                            const restorePath = router.href(currentRoute);
+                            history.pushState(null, '', restorePath);
+                        }
+                        return;
+                    }
+                    currentRoute = finalRoute;
+                    send(factory(finalRoute));
                 };
                 window.addEventListener(event, handler);
                 return () => window.removeEventListener(event, handler);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llui/router",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -21,7 +21,7 @@
     "test": "vitest run"
   },
   "peerDependencies": {
-    "@llui/dom": "^0.0.1"
+    "@llui/dom": "^0.0.3"
   },
   "devDependencies": {
     "@llui/dom": "workspace:*",