@domql/router 3.1.2 → 3.2.7

package/README.md

@@ -0,0 +1,198 @@
+# @domql/router
+
+Client-side router plugin for DOMQL. Handles route matching, navigation, scroll management, and state updates within DOMQL elements.
+
+## Install
+
+```bash
+npm install @domql/router
+```
+
+## Basic Usage
+
+```js
+import { router } from '@domql/router'
+
+// Navigate to a path
+router('/about', element)
+
+// With state and options
+router('/dashboard', element, { userId: 1 }, { scrollToTop: true })
+```
+
+Define routes on your DOMQL element:
+
+```js
+const App = {
+  routes: {
+    '/': HomePage,
+    '/about': AboutPage,
+    '/contact': ContactPage,
+    '/*': NotFoundPage
+  }
+}
+```
+
+## Dynamic Route Params
+
+Match routes with `:param` segments. Enable with `useParamsMatching: true`.
+
+```js
+const App = {
+  routes: {
+    '/': HomePage,
+    '/:id': UserPage,
+    '/:category/:slug': ArticlePage,
+    '/*': NotFoundPage
+  }
+}
+
+router('/users/42', element, {}, { useParamsMatching: true })
+// state.params = { id: '42' }
+
+router('/tech/my-article', element, {}, { useParamsMatching: true })
+// state.params = { category: 'tech', slug: 'my-article' }
+```
+
+Exact segments score higher than params, so `/about` will match a literal `/about` route before `/:id`.
+
+## Query String Parsing
+
+Query parameters are automatically parsed and stored in state.
+
+```js
+router('/search?q=hello&tag=a&tag=b', element)
+// state.query = { q: 'hello', tag: ['a', 'b'] }
+```
+
+Duplicate keys are collected into arrays.
+
+## Guards / Middleware
+
+Run async guard functions before navigation. Return `true` to allow, `false` to block, or a string to redirect.
+
+```js
+const authGuard = ({ element }) => {
+  if (!element.state.root.isLoggedIn) return '/login'
+  return true
+}
+
+const roleGuard = ({ params }) => {
+  if (params.section === 'admin') return false
+  return true
+}
+
+router('/dashboard', element, {}, {
+  guards: [authGuard, roleGuard]
+})
+```
+
+Guard functions receive a context object:
+
+```js
+{
+  pathname,  // full pathname
+  route,     // matched route key
+  params,    // dynamic route params
+  query,     // parsed query string
+  hash,      // URL hash
+  element,   // DOMQL element
+  state      // navigation state
+}
+```
+
+## 404 Handling
+
+Provide an `onNotFound` callback for unmatched routes:
+
+```js
+router('/unknown', element, {}, {
+  onNotFound: ({ pathname, route, element }) => {
+    console.warn(`No route found for ${pathname}`)
+  }
+})
+```
+
+You can also define a `/*` wildcard route as a catch-all fallback.
+
+## Options
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `level` | `number` | `0` | Route nesting level (which path segment to match) |
+| `pushState` | `boolean` | `true` | Push to browser history |
+| `initialRender` | `boolean` | `false` | Whether this is the initial page render |
+| `scrollToTop` | `boolean` | `true` | Scroll to top after navigation |
+| `scrollToNode` | `boolean` | `false` | Scroll within the element node |
+| `scrollNode` | `Element` | `document.documentElement` | Node to scroll |
+| `scrollToOffset` | `number` | `0` | Offset when scrolling to hash anchors |
+| `scrollToOptions` | `object` | `{ behavior: 'smooth' }` | Options passed to `scrollTo()` |
+| `useFragment` | `boolean` | `false` | Use fragment tag for content |
+| `updateState` | `boolean` | `true` | Update element state on navigation |
+| `contentElementKey` | `string` | `'content'` | Key for the content element slot |
+| `removeOldElement` | `boolean` | `false` | Remove old content element before setting new |
+| `useParamsMatching` | `boolean` | `false` | Enable dynamic `:param` route matching |
+| `guards` | `function[]` | `undefined` | Array of guard/middleware functions |
+| `onNotFound` | `function` | `undefined` | Callback when no route matches |
+
+## Exported Utilities
+
+### `getActiveRoute(level, route)`
+
+Returns the active route segment at the given nesting level.
+
+```js
+import { getActiveRoute } from '@domql/router'
+
+getActiveRoute(0, '/users/42')  // '/users'
+getActiveRoute(1, '/users/42')  // '/42'
+```
+
+### `parseQuery(search)`
+
+Parses a query string into an object.
+
+```js
+import { parseQuery } from '@domql/router'
+
+parseQuery('?page=1&sort=name')  // { page: '1', sort: 'name' }
+```
+
+### `matchRoute(pathname, routes, level)`
+
+Matches a pathname against a routes object. Returns `{ key, content, params }`.
+
+```js
+import { matchRoute } from '@domql/router'
+
+const routes = { '/': Home, '/:id': Detail, '/*': NotFound }
+const result = matchRoute('/42', routes)
+// { key: '/:id', content: Detail, params: { id: '42' } }
+```
+
+### `parseRoutePattern(pattern)`
+
+Parses a route pattern string into segments, param definitions, and wildcard flag. Results are cached.
+
+### `runGuards(guards, context)`
+
+Runs an array of async guard functions sequentially. Returns `true`, `false`, or a redirect path string.
+
+## Events
+
+The router triggers an `on.routeChanged` event on the element after navigation completes. Listen for it in your element definition:
+
+```js
+const App = {
+  routes: { ... },
+  on: {
+    routeChanged: (element, options) => {
+      console.log('Route changed:', element.state.route)
+    }
+  }
+}
+```
+
+## License
+
+MIT

package/dist/cjs/index.js

@@ -22,12 +22,115 @@ __export(index_exports, {
   getActiveRoute: () => getActiveRoute,
   lastLevel: () => lastLevel,
   lastPathname: () => lastPathname,
-  router: () => router
+  matchRoute: () => matchRoute,
+  parseQuery: () => parseQuery,
+  parseRoutePattern: () => parseRoutePattern,
+  router: () => router,
+  runGuards: () => runGuards
 });
 module.exports = __toCommonJS(index_exports);
-var import_event = require("@domql/event");
 var import_utils = require("@domql/utils");
 var import_set = require("@domql/element/set");
+const paramPattern = /^:(.+)/;
+const wildcardPattern = /^\*$/;
+const routeCache = /* @__PURE__ */ new Map();
+const parseRoutePattern = (pattern) => {
+  const cached = routeCache.get(pattern);
+  if (cached) return cached;
+  const segments = pattern.replace(/^\//, "").split("/");
+  const params = [];
+  let hasWildcard = false;
+  for (let i = 0; i < segments.length; i++) {
+    const match = segments[i].match(paramPattern);
+    if (match) {
+      params.push({ index: i, name: match[1] });
+    } else if (wildcardPattern.test(segments[i])) {
+      hasWildcard = true;
+    }
+  }
+  const result = { segments, params, hasWildcard, pattern };
+  routeCache.set(pattern, result);
+  return result;
+};
+const matchRoute = (pathname, routes, level = 0) => {
+  const pathSegments = pathname.replace(/^\//, "").split("/").filter(Boolean);
+  const relevantSegments = pathSegments.slice(level);
+  const routePath = "/" + (relevantSegments[0] || "");
+  let bestMatch = null;
+  let bestScore = -1;
+  let matchedParams = {};
+  for (const key in routes) {
+    if (key === "/*") continue;
+    const parsed = parseRoutePattern(key);
+    const score = scoreMatch(relevantSegments, parsed);
+    if (score > bestScore) {
+      bestScore = score;
+      bestMatch = key;
+      matchedParams = extractParams(relevantSegments, parsed);
+    }
+  }
+  if (!bestMatch && routes["/*"]) {
+    bestMatch = "/*";
+  }
+  return {
+    key: bestMatch,
+    content: bestMatch ? routes[bestMatch] : null,
+    params: matchedParams,
+    routePath
+  };
+};
+const scoreMatch = (pathSegments, parsed) => {
+  const { segments, hasWildcard } = parsed;
+  if (!hasWildcard && segments.length !== pathSegments.length && segments.length !== 1) {
+    if (segments.length > pathSegments.length) return -1;
+  }
+  let score = 0;
+  const len = Math.min(segments.length, pathSegments.length);
+  for (let i = 0; i < len; i++) {
+    if (segments[i] === pathSegments[i]) {
+      score += 3;
+    } else if (paramPattern.test(segments[i])) {
+      score += 1;
+    } else if (wildcardPattern.test(segments[i])) {
+      score += 0.5;
+    } else {
+      return -1;
+    }
+  }
+  return score;
+};
+const extractParams = (pathSegments, parsed) => {
+  const params = {};
+  for (const { index, name } of parsed.params) {
+    if (pathSegments[index]) {
+      params[name] = decodeURIComponent(pathSegments[index]);
+    }
+  }
+  return params;
+};
+const parseQuery = (search) => {
+  if (!search || search === "?") return {};
+  const params = {};
+  const searchParams = new URLSearchParams(search);
+  searchParams.forEach((value, key) => {
+    if (params[key] !== void 0) {
+      if (!Array.isArray(params[key])) params[key] = [params[key]];
+      params[key].push(value);
+    } else {
+      params[key] = value;
+    }
+  });
+  return params;
+};
+const runGuards = async (guards, context) => {
+  if (!guards || !guards.length) return true;
+  for (const guard of guards) {
+    const result = await guard(context);
+    if (result === false) return false;
+    if (typeof result === "string") return result;
+  }
+  return true;
+};
 const getActiveRoute = (level = 0, route = import_utils.window.location.pathname) => {
   const routeArray = route.split("/");
   const activeRoute = routeArray[level + 1];
@@ -47,9 +150,10 @@ const defaultOptions = {
   updateState: true,
   scrollToOffset: 0,
   contentElementKey: "content",
-  scrollToOptions: { behavior: "smooth" }
+  scrollToOptions: { behavior: "smooth" },
+  useParamsMatching: false
 };
-const router = async (path, el, state = {}, options = {}) => {
+const router = (path, el, state = {}, options = {}) => {
   const element = el || void 0;
   const win = element.context.window || import_utils.window;
   const doc = element.context.document || import_utils.document;
@@ -66,31 +170,55 @@ const router = async (path, el, state = {}, options = {}) => {
   const contentElementKey = (0, import_set.setContentKey)(element, opts);
   const urlObj = new win.URL(win.location.origin + path);
   const { pathname, search, hash } = urlObj;
+  const query = parseQuery(search);
   const rootNode = element.node;
-  const route = getActiveRoute(opts.level, pathname);
-  const content = element.routes[route || "/"] || element.routes["/*"];
-  const scrollNode = opts.scrollToNode ? rootNode : opts.scrollNode;
   const hashChanged = hash && hash !== win.location.hash.slice(1);
   const pathChanged = pathname !== lastPathname;
   lastPathname = pathname;
+  let route, content, params;
+  if (opts.useParamsMatching) {
+    const match = matchRoute(pathname, element.routes, opts.level);
+    route = match.routePath;
+    content = match.content;
+    params = match.params;
+  } else {
+    route = getActiveRoute(opts.level, pathname);
+    content = element.routes[route || "/"] || element.routes["/*"];
+    params = {};
+  }
+  const scrollNode = opts.scrollToNode ? rootNode : opts.scrollNode;
   if (!content || element.state.root.debugging) {
     element.state.root.debugging = false;
+    if (opts.onNotFound) {
+      opts.onNotFound({ pathname, route, element });
+    }
     return;
   }
+  if (opts.guards && opts.guards.length) {
+    const guardContext = { pathname, route, params, query, hash, element, state };
+    const guardResult = runGuards(opts.guards, guardContext);
+    if (guardResult === false) return;
+    if (typeof guardResult === "string") {
+      return router(guardResult, el, state, { ...options, guards: [] });
+    }
+  }
   if (opts.pushState) {
     win.history.pushState(state, null, pathname + (search || "") + (hash || ""));
   }
   if (pathChanged || !hashChanged) {
+    const stateUpdate = { route, hash, debugging: false };
+    if (Object.keys(params).length) stateUpdate.params = params;
+    if (Object.keys(query).length) stateUpdate.query = query;
     if (opts.updateState) {
-      await element.state.update(
-        { route, hash, debugging: false },
+      element.state.update(
+        stateUpdate,
         { preventContentUpdate: true }
       );
     }
     if (contentElementKey && opts.removeOldElement) {
       element[contentElementKey].remove();
     }
-    await element.set(
+    element.set(
       {
         tag: opts.useFragment && "fragment",
         extends: content
@@ -115,7 +243,7 @@ const router = async (path, el, state = {}, options = {}) => {
   if (hash) {
     const activeNode = doc.getElementById(hash);
     if (activeNode) {
-      const top = activeNode.getBoundingClientRect().top + rootNode.scrollTop - opts.scrollToOffset || 0;
+      const top = activeNode.getBoundingClientRect().top + rootNode.scrollTop - (opts.scrollToOffset || 0);
       scrollNode.scrollTo({
         ...opts.scrollToOptions || {},
         top,
@@ -123,6 +251,6 @@ const router = async (path, el, state = {}, options = {}) => {
       });
     }
   }
-  await (0, import_event.triggerEventOn)("routeChanged", element, opts);
+  (0, import_utils.triggerEventOn)("routeChanged", element, opts);
 };
 var index_default = router;

package/dist/esm/index.js

@@ -1,25 +1,105 @@
-var __defProp = Object.defineProperty;
-var __defProps = Object.defineProperties;
-var __getOwnPropDescs = Object.getOwnPropertyDescriptors;
-var __getOwnPropSymbols = Object.getOwnPropertySymbols;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __propIsEnum = Object.prototype.propertyIsEnumerable;
-var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
-var __spreadValues = (a, b) => {
-  for (var prop in b || (b = {}))
-    if (__hasOwnProp.call(b, prop))
-      __defNormalProp(a, prop, b[prop]);
-  if (__getOwnPropSymbols)
-    for (var prop of __getOwnPropSymbols(b)) {
-      if (__propIsEnum.call(b, prop))
-        __defNormalProp(a, prop, b[prop]);
+import { document, window, triggerEventOn } from "@domql/utils";
+import { setContentKey } from "@domql/element/set";
+const paramPattern = /^:(.+)/;
+const wildcardPattern = /^\*$/;
+const routeCache = /* @__PURE__ */ new Map();
+const parseRoutePattern = (pattern) => {
+  const cached = routeCache.get(pattern);
+  if (cached) return cached;
+  const segments = pattern.replace(/^\//, "").split("/");
+  const params = [];
+  let hasWildcard = false;
+  for (let i = 0; i < segments.length; i++) {
+    const match = segments[i].match(paramPattern);
+    if (match) {
+      params.push({ index: i, name: match[1] });
+    } else if (wildcardPattern.test(segments[i])) {
+      hasWildcard = true;
     }
-  return a;
+  }
+  const result = { segments, params, hasWildcard, pattern };
+  routeCache.set(pattern, result);
+  return result;
+};
+const matchRoute = (pathname, routes, level = 0) => {
+  const pathSegments = pathname.replace(/^\//, "").split("/").filter(Boolean);
+  const relevantSegments = pathSegments.slice(level);
+  const routePath = "/" + (relevantSegments[0] || "");
+  let bestMatch = null;
+  let bestScore = -1;
+  let matchedParams = {};
+  for (const key in routes) {
+    if (key === "/*") continue;
+    const parsed = parseRoutePattern(key);
+    const score = scoreMatch(relevantSegments, parsed);
+    if (score > bestScore) {
+      bestScore = score;
+      bestMatch = key;
+      matchedParams = extractParams(relevantSegments, parsed);
+    }
+  }
+  if (!bestMatch && routes["/*"]) {
+    bestMatch = "/*";
+  }
+  return {
+    key: bestMatch,
+    content: bestMatch ? routes[bestMatch] : null,
+    params: matchedParams,
+    routePath
+  };
+};
+const scoreMatch = (pathSegments, parsed) => {
+  const { segments, hasWildcard } = parsed;
+  if (!hasWildcard && segments.length !== pathSegments.length && segments.length !== 1) {
+    if (segments.length > pathSegments.length) return -1;
+  }
+  let score = 0;
+  const len = Math.min(segments.length, pathSegments.length);
+  for (let i = 0; i < len; i++) {
+    if (segments[i] === pathSegments[i]) {
+      score += 3;
+    } else if (paramPattern.test(segments[i])) {
+      score += 1;
+    } else if (wildcardPattern.test(segments[i])) {
+      score += 0.5;
+    } else {
+      return -1;
+    }
+  }
+  return score;
+};
+const extractParams = (pathSegments, parsed) => {
+  const params = {};
+  for (const { index, name } of parsed.params) {
+    if (pathSegments[index]) {
+      params[name] = decodeURIComponent(pathSegments[index]);
+    }
+  }
+  return params;
+};
+const parseQuery = (search) => {
+  if (!search || search === "?") return {};
+  const params = {};
+  const searchParams = new URLSearchParams(search);
+  searchParams.forEach((value, key) => {
+    if (params[key] !== void 0) {
+      if (!Array.isArray(params[key])) params[key] = [params[key]];
+      params[key].push(value);
+    } else {
+      params[key] = value;
+    }
+  });
+  return params;
+};
+const runGuards = async (guards, context) => {
+  if (!guards || !guards.length) return true;
+  for (const guard of guards) {
+    const result = await guard(context);
+    if (result === false) return false;
+    if (typeof result === "string") return result;
+  }
+  return true;
 };
-var __spreadProps = (a, b) => __defProps(a, __getOwnPropDescs(b));
-import { triggerEventOn } from "@domql/event";
-import { document, window } from "@domql/utils";
-import { setContentKey } from "@domql/element/set";
 const getActiveRoute = (level = 0, route = window.location.pathname) => {
   const routeArray = route.split("/");
   const activeRoute = routeArray[level + 1];
@@ -39,13 +119,18 @@ const defaultOptions = {
   updateState: true,
   scrollToOffset: 0,
   contentElementKey: "content",
-  scrollToOptions: { behavior: "smooth" }
+  scrollToOptions: { behavior: "smooth" },
+  useParamsMatching: false
 };
-const router = async (path, el, state = {}, options = {}) => {
+const router = (path, el, state = {}, options = {}) => {
   const element = el || void 0;
   const win = element.context.window || window;
   const doc = element.context.document || document;
-  const opts = __spreadValues(__spreadValues(__spreadValues({}, defaultOptions), element.context.routerOptions), options);
+  const opts = {
+    ...defaultOptions,
+    ...element.context.routerOptions,
+    ...options
+  };
   lastLevel = opts.lastLevel;
   const ref = element.__ref;
   if (opts.contentElementKey !== "content" && opts.contentElementKey !== ref.contentElementKey || !ref.contentElementKey) {
@@ -54,31 +139,55 @@ const router = async (path, el, state = {}, options = {}) => {
   const contentElementKey = setContentKey(element, opts);
   const urlObj = new win.URL(win.location.origin + path);
   const { pathname, search, hash } = urlObj;
+  const query = parseQuery(search);
   const rootNode = element.node;
-  const route = getActiveRoute(opts.level, pathname);
-  const content = element.routes[route || "/"] || element.routes["/*"];
-  const scrollNode = opts.scrollToNode ? rootNode : opts.scrollNode;
   const hashChanged = hash && hash !== win.location.hash.slice(1);
   const pathChanged = pathname !== lastPathname;
   lastPathname = pathname;
+  let route, content, params;
+  if (opts.useParamsMatching) {
+    const match = matchRoute(pathname, element.routes, opts.level);
+    route = match.routePath;
+    content = match.content;
+    params = match.params;
+  } else {
+    route = getActiveRoute(opts.level, pathname);
+    content = element.routes[route || "/"] || element.routes["/*"];
+    params = {};
+  }
+  const scrollNode = opts.scrollToNode ? rootNode : opts.scrollNode;
   if (!content || element.state.root.debugging) {
     element.state.root.debugging = false;
+    if (opts.onNotFound) {
+      opts.onNotFound({ pathname, route, element });
+    }
     return;
   }
+  if (opts.guards && opts.guards.length) {
+    const guardContext = { pathname, route, params, query, hash, element, state };
+    const guardResult = runGuards(opts.guards, guardContext);
+    if (guardResult === false) return;
+    if (typeof guardResult === "string") {
+      return router(guardResult, el, state, { ...options, guards: [] });
+    }
+  }
   if (opts.pushState) {
     win.history.pushState(state, null, pathname + (search || "") + (hash || ""));
   }
   if (pathChanged || !hashChanged) {
+    const stateUpdate = { route, hash, debugging: false };
+    if (Object.keys(params).length) stateUpdate.params = params;
+    if (Object.keys(query).length) stateUpdate.query = query;
     if (opts.updateState) {
-      await element.state.update(
-        { route, hash, debugging: false },
+      element.state.update(
+        stateUpdate,
         { preventContentUpdate: true }
       );
     }
     if (contentElementKey && opts.removeOldElement) {
       element[contentElementKey].remove();
     }
-    await element.set(
+    element.set(
       {
         tag: opts.useFragment && "fragment",
         extends: content
@@ -87,28 +196,31 @@ const router = async (path, el, state = {}, options = {}) => {
     );
   }
   if (opts.scrollToTop) {
-    scrollNode.scrollTo(__spreadProps(__spreadValues({}, opts.scrollToOptions || {}), {
+    scrollNode.scrollTo({
+      ...opts.scrollToOptions || {},
       top: 0,
       left: 0
-    }));
+    });
   }
   if (opts.scrollToNode) {
-    content[contentElementKey].node.scrollTo(__spreadProps(__spreadValues({}, opts.scrollToOptions || {}), {
+    content[contentElementKey].node.scrollTo({
+      ...opts.scrollToOptions || {},
       top: 0,
       left: 0
-    }));
+    });
   }
   if (hash) {
     const activeNode = doc.getElementById(hash);
     if (activeNode) {
-      const top = activeNode.getBoundingClientRect().top + rootNode.scrollTop - opts.scrollToOffset || 0;
-      scrollNode.scrollTo(__spreadProps(__spreadValues({}, opts.scrollToOptions || {}), {
+      const top = activeNode.getBoundingClientRect().top + rootNode.scrollTop - (opts.scrollToOffset || 0);
+      scrollNode.scrollTo({
+        ...opts.scrollToOptions || {},
         top,
         left: 0
-      }));
+      });
     }
   }
-  await triggerEventOn("routeChanged", element, opts);
+  triggerEventOn("routeChanged", element, opts);
 };
 var index_default = router;
 export {
@@ -116,5 +228,9 @@ export {
   getActiveRoute,
   lastLevel,
   lastPathname,
-  router
+  matchRoute,
+  parseQuery,
+  parseRoutePattern,
+  router,
+  runGuards
 };

package/dist/iife/index.js

@@ -0,0 +1,312 @@
+"use strict";
+var DomqlRouter = (() => {
+  var __defProp = Object.defineProperty;
+  var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+  var __getOwnPropNames = Object.getOwnPropertyNames;
+  var __hasOwnProp = Object.prototype.hasOwnProperty;
+  var __export = (target, all) => {
+    for (var name in all)
+      __defProp(target, name, { get: all[name], enumerable: true });
+  };
+  var __copyProps = (to, from, except, desc) => {
+    if (from && typeof from === "object" || typeof from === "function") {
+      for (let key of __getOwnPropNames(from))
+        if (!__hasOwnProp.call(to, key) && key !== except)
+          __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+    }
+    return to;
+  };
+  var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+  // index.js
+  var index_exports = {};
+  __export(index_exports, {
+    default: () => index_default,
+    getActiveRoute: () => getActiveRoute,
+    lastLevel: () => lastLevel,
+    lastPathname: () => lastPathname,
+    matchRoute: () => matchRoute,
+    parseQuery: () => parseQuery,
+    parseRoutePattern: () => parseRoutePattern,
+    router: () => router,
+    runGuards: () => runGuards
+  });
+
+  // ../../packages/utils/dist/esm/globals.js
+  var window2 = globalThis;
+  var document = window2.document;
+
+  // ../../packages/utils/dist/esm/types.js
+  var isFunction = (arg) => typeof arg === "function";
+
+  // ../../packages/utils/dist/esm/triggerEvent.js
+  var getOnOrPropsEvent = (param, element) => {
+    const onEvent = element.on?.[param];
+    if (onEvent) return onEvent;
+    const props = element.props;
+    if (!props) return;
+    const propKey = "on" + param.charAt(0).toUpperCase() + param.slice(1);
+    return props[propKey];
+  };
+  var applyEvent = (param, element, state, context, options) => {
+    if (!isFunction(param)) return;
+    const result = param.call(
+      element,
+      element,
+      state || element.state,
+      context || element.context,
+      options
+    );
+    if (result && typeof result.then === "function") {
+      result.catch(() => {
+      });
+    }
+    return result;
+  };
+  var triggerEventOn = (param, element, options) => {
+    if (!element) {
+      throw new Error("Element is required");
+    }
+    const appliedFunction = getOnOrPropsEvent(param, element);
+    if (appliedFunction) {
+      const { state, context } = element;
+      return applyEvent(appliedFunction, element, state, context, options);
+    }
+  };
+
+  // ../../packages/element/dist/esm/set.js
+  var setContentKey = (element, opts = {}) => {
+    const { __ref: ref } = element;
+    const contentElementKey = opts.contentElementKey;
+    if (!ref.contentElementKey || contentElementKey !== ref.contentElementKey) {
+      ref.contentElementKey = contentElementKey || "content";
+    }
+    return ref.contentElementKey;
+  };
+
+  // index.js
+  var paramPattern = /^:(.+)/;
+  var wildcardPattern = /^\*$/;
+  var routeCache = /* @__PURE__ */ new Map();
+  var parseRoutePattern = (pattern) => {
+    const cached = routeCache.get(pattern);
+    if (cached) return cached;
+    const segments = pattern.replace(/^\//, "").split("/");
+    const params = [];
+    let hasWildcard = false;
+    for (let i = 0; i < segments.length; i++) {
+      const match = segments[i].match(paramPattern);
+      if (match) {
+        params.push({ index: i, name: match[1] });
+      } else if (wildcardPattern.test(segments[i])) {
+        hasWildcard = true;
+      }
+    }
+    const result = { segments, params, hasWildcard, pattern };
+    routeCache.set(pattern, result);
+    return result;
+  };
+  var matchRoute = (pathname, routes, level = 0) => {
+    const pathSegments = pathname.replace(/^\//, "").split("/").filter(Boolean);
+    const relevantSegments = pathSegments.slice(level);
+    const routePath = "/" + (relevantSegments[0] || "");
+    let bestMatch = null;
+    let bestScore = -1;
+    let matchedParams = {};
+    for (const key in routes) {
+      if (key === "/*") continue;
+      const parsed = parseRoutePattern(key);
+      const score = scoreMatch(relevantSegments, parsed);
+      if (score > bestScore) {
+        bestScore = score;
+        bestMatch = key;
+        matchedParams = extractParams(relevantSegments, parsed);
+      }
+    }
+    if (!bestMatch && routes["/*"]) {
+      bestMatch = "/*";
+    }
+    return {
+      key: bestMatch,
+      content: bestMatch ? routes[bestMatch] : null,
+      params: matchedParams,
+      routePath
+    };
+  };
+  var scoreMatch = (pathSegments, parsed) => {
+    const { segments, hasWildcard } = parsed;
+    if (!hasWildcard && segments.length !== pathSegments.length && segments.length !== 1) {
+      if (segments.length > pathSegments.length) return -1;
+    }
+    let score = 0;
+    const len = Math.min(segments.length, pathSegments.length);
+    for (let i = 0; i < len; i++) {
+      if (segments[i] === pathSegments[i]) {
+        score += 3;
+      } else if (paramPattern.test(segments[i])) {
+        score += 1;
+      } else if (wildcardPattern.test(segments[i])) {
+        score += 0.5;
+      } else {
+        return -1;
+      }
+    }
+    return score;
+  };
+  var extractParams = (pathSegments, parsed) => {
+    const params = {};
+    for (const { index, name } of parsed.params) {
+      if (pathSegments[index]) {
+        params[name] = decodeURIComponent(pathSegments[index]);
+      }
+    }
+    return params;
+  };
+  var parseQuery = (search) => {
+    if (!search || search === "?") return {};
+    const params = {};
+    const searchParams = new URLSearchParams(search);
+    searchParams.forEach((value, key) => {
+      if (params[key] !== void 0) {
+        if (!Array.isArray(params[key])) params[key] = [params[key]];
+        params[key].push(value);
+      } else {
+        params[key] = value;
+      }
+    });
+    return params;
+  };
+  var runGuards = async (guards, context) => {
+    if (!guards || !guards.length) return true;
+    for (const guard of guards) {
+      const result = await guard(context);
+      if (result === false) return false;
+      if (typeof result === "string") return result;
+    }
+    return true;
+  };
+  var getActiveRoute = (level = 0, route = window2.location.pathname) => {
+    const routeArray = route.split("/");
+    const activeRoute = routeArray[level + 1];
+    if (activeRoute) return `/${activeRoute}`;
+  };
+  var lastPathname;
+  var lastLevel = 0;
+  var defaultOptions = {
+    level: lastLevel,
+    pushState: true,
+    initialRender: false,
+    scrollToTop: true,
+    scrollToNode: false,
+    scrollNode: document && document.documentElement,
+    scrollBody: false,
+    useFragment: false,
+    updateState: true,
+    scrollToOffset: 0,
+    contentElementKey: "content",
+    scrollToOptions: { behavior: "smooth" },
+    useParamsMatching: false
+  };
+  var router = (path, el, state = {}, options = {}) => {
+    const element = el || void 0;
+    const win = element.context.window || window2;
+    const doc = element.context.document || document;
+    const opts = {
+      ...defaultOptions,
+      ...element.context.routerOptions,
+      ...options
+    };
+    lastLevel = opts.lastLevel;
+    const ref = element.__ref;
+    if (opts.contentElementKey !== "content" && opts.contentElementKey !== ref.contentElementKey || !ref.contentElementKey) {
+      ref.contentElementKey = opts.contentElementKey || "content";
+    }
+    const contentElementKey = setContentKey(element, opts);
+    const urlObj = new win.URL(win.location.origin + path);
+    const { pathname, search, hash } = urlObj;
+    const query = parseQuery(search);
+    const rootNode = element.node;
+    const hashChanged = hash && hash !== win.location.hash.slice(1);
+    const pathChanged = pathname !== lastPathname;
+    lastPathname = pathname;
+    let route, content, params;
+    if (opts.useParamsMatching) {
+      const match = matchRoute(pathname, element.routes, opts.level);
+      route = match.routePath;
+      content = match.content;
+      params = match.params;
+    } else {
+      route = getActiveRoute(opts.level, pathname);
+      content = element.routes[route || "/"] || element.routes["/*"];
+      params = {};
+    }
+    const scrollNode = opts.scrollToNode ? rootNode : opts.scrollNode;
+    if (!content || element.state.root.debugging) {
+      element.state.root.debugging = false;
+      if (opts.onNotFound) {
+        opts.onNotFound({ pathname, route, element });
+      }
+      return;
+    }
+    if (opts.guards && opts.guards.length) {
+      const guardContext = { pathname, route, params, query, hash, element, state };
+      const guardResult = runGuards(opts.guards, guardContext);
+      if (guardResult === false) return;
+      if (typeof guardResult === "string") {
+        return router(guardResult, el, state, { ...options, guards: [] });
+      }
+    }
+    if (opts.pushState) {
+      win.history.pushState(state, null, pathname + (search || "") + (hash || ""));
+    }
+    if (pathChanged || !hashChanged) {
+      const stateUpdate = { route, hash, debugging: false };
+      if (Object.keys(params).length) stateUpdate.params = params;
+      if (Object.keys(query).length) stateUpdate.query = query;
+      if (opts.updateState) {
+        element.state.update(
+          stateUpdate,
+          { preventContentUpdate: true }
+        );
+      }
+      if (contentElementKey && opts.removeOldElement) {
+        element[contentElementKey].remove();
+      }
+      element.set(
+        {
+          tag: opts.useFragment && "fragment",
+          extends: content
+        },
+        { contentElementKey }
+      );
+    }
+    if (opts.scrollToTop) {
+      scrollNode.scrollTo({
+        ...opts.scrollToOptions || {},
+        top: 0,
+        left: 0
+      });
+    }
+    if (opts.scrollToNode) {
+      content[contentElementKey].node.scrollTo({
+        ...opts.scrollToOptions || {},
+        top: 0,
+        left: 0
+      });
+    }
+    if (hash) {
+      const activeNode = doc.getElementById(hash);
+      if (activeNode) {
+        const top = activeNode.getBoundingClientRect().top + rootNode.scrollTop - (opts.scrollToOffset || 0);
+        scrollNode.scrollTo({
+          ...opts.scrollToOptions || {},
+          top,
+          left: 0
+        });
+      }
+    }
+    triggerEventOn("routeChanged", element, opts);
+  };
+  var index_default = router;
+  return __toCommonJS(index_exports);
+})();

package/index.js

@@ -1,9 +1,137 @@
 'use strict'
 
-import { triggerEventOn } from '@domql/event'
-import { document, window } from '@domql/utils'
+import { document, window, triggerEventOn } from '@domql/utils'
 import { setContentKey } from '@domql/element/set'
 
+// --- Route matching utilities ---
+
+const paramPattern = /^:(.+)/
+const wildcardPattern = /^\*$/
+
+const routeCache = new Map()
+
+export const parseRoutePattern = (pattern) => {
+  const cached = routeCache.get(pattern)
+  if (cached) return cached
+
+  const segments = pattern.replace(/^\//, '').split('/')
+  const params = []
+  let hasWildcard = false
+
+  for (let i = 0; i < segments.length; i++) {
+    const match = segments[i].match(paramPattern)
+    if (match) {
+      params.push({ index: i, name: match[1] })
+    } else if (wildcardPattern.test(segments[i])) {
+      hasWildcard = true
+    }
+  }
+
+  const result = { segments, params, hasWildcard, pattern }
+  routeCache.set(pattern, result)
+  return result
+}
+
+export const matchRoute = (pathname, routes, level = 0) => {
+  const pathSegments = pathname.replace(/^\//, '').split('/').filter(Boolean)
+  const relevantSegments = pathSegments.slice(level)
+  const routePath = '/' + (relevantSegments[0] || '')
+
+  let bestMatch = null
+  let bestScore = -1
+  let matchedParams = {}
+
+  for (const key in routes) {
+    if (key === '/*') continue
+
+    const parsed = parseRoutePattern(key)
+    const score = scoreMatch(relevantSegments, parsed)
+
+    if (score > bestScore) {
+      bestScore = score
+      bestMatch = key
+      matchedParams = extractParams(relevantSegments, parsed)
+    }
+  }
+
+  if (!bestMatch && routes['/*']) {
+    bestMatch = '/*'
+  }
+
+  return {
+    key: bestMatch,
+    content: bestMatch ? routes[bestMatch] : null,
+    params: matchedParams,
+    routePath
+  }
+}
+
+const scoreMatch = (pathSegments, parsed) => {
+  const { segments, hasWildcard } = parsed
+
+  if (!hasWildcard && segments.length !== pathSegments.length &&
+      segments.length !== 1) {
+    // For single-segment patterns, match just the first segment
+    if (segments.length > pathSegments.length) return -1
+  }
+
+  let score = 0
+  const len = Math.min(segments.length, pathSegments.length)
+
+  for (let i = 0; i < len; i++) {
+    if (segments[i] === pathSegments[i]) {
+      score += 3 // exact match
+    } else if (paramPattern.test(segments[i])) {
+      score += 1 // param match
+    } else if (wildcardPattern.test(segments[i])) {
+      score += 0.5
+    } else {
+      return -1 // no match
+    }
+  }
+
+  return score
+}
+
+const extractParams = (pathSegments, parsed) => {
+  const params = {}
+  for (const { index, name } of parsed.params) {
+    if (pathSegments[index]) {
+      params[name] = decodeURIComponent(pathSegments[index])
+    }
+  }
+  return params
+}
+
+export const parseQuery = (search) => {
+  if (!search || search === '?') return {}
+  const params = {}
+  const searchParams = new URLSearchParams(search)
+  searchParams.forEach((value, key) => {
+    if (params[key] !== undefined) {
+      if (!Array.isArray(params[key])) params[key] = [params[key]]
+      params[key].push(value)
+    } else {
+      params[key] = value
+    }
+  })
+  return params
+}
+
+// --- Route guards / middleware ---
+
+export const runGuards = async (guards, context) => {
+  if (!guards || !guards.length) return true
+  for (const guard of guards) {
+    const result = await guard(context)
+    if (result === false) return false
+    if (typeof result === 'string') return result // redirect path
+  }
+  return true
+}
+
+// --- Core router ---
+
 export const getActiveRoute = (level = 0, route = window.location.pathname) => {
   const routeArray = route.split('/')
   const activeRoute = routeArray[level + 1]
@@ -25,10 +153,11 @@ const defaultOptions = {
   updateState: true,
   scrollToOffset: 0,
   contentElementKey: 'content',
-  scrollToOptions: { behavior: 'smooth' }
+  scrollToOptions: { behavior: 'smooth' },
+  useParamsMatching: false
 }
 
-export const router = async (path, el, state = {}, options = {}) => {
+export const router = (path, el, state = {}, options = {}) => {
   const element = el || this
   const win = element.context.window || window
   const doc = element.context.document || document
@@ -38,6 +167,7 @@ export const router = async (path, el, state = {}, options = {}) => {
     ...options
   }
   lastLevel = opts.lastLevel
+
   const ref = element.__ref
 
   if (
@@ -53,27 +183,60 @@ export const router = async (path, el, state = {}, options = {}) => {
   const urlObj = new win.URL(win.location.origin + path)
   const { pathname, search, hash } = urlObj
 
+  const query = parseQuery(search)
+
   const rootNode = element.node
-  const route = getActiveRoute(opts.level, pathname)
-  const content = element.routes[route || '/'] || element.routes['/*']
-  const scrollNode = opts.scrollToNode ? rootNode : opts.scrollNode
   const hashChanged = hash && hash !== win.location.hash.slice(1)
   const pathChanged = pathname !== lastPathname
   lastPathname = pathname
 
+  // Route matching - support both simple and param-based
+  let route, content, params
+  if (opts.useParamsMatching) {
+    const match = matchRoute(pathname, element.routes, opts.level)
+    route = match.routePath
+    content = match.content
+    params = match.params
+  } else {
+    route = getActiveRoute(opts.level, pathname)
+    content = element.routes[route || '/'] || element.routes['/*']
+    params = {}
+  }
+
+  const scrollNode = opts.scrollToNode ? rootNode : opts.scrollNode
+
   if (!content || element.state.root.debugging) {
     element.state.root.debugging = false
+
+    if (opts.onNotFound) {
+      opts.onNotFound({ pathname, route, element })
+    }
     return
   }
 
+  // Run guards
+  if (opts.guards && opts.guards.length) {
+    const guardContext = { pathname, route, params, query, hash, element, state }
+    const guardResult = runGuards(opts.guards, guardContext)
+    if (guardResult === false) return
+    if (typeof guardResult === 'string') {
+      // Redirect
+      return router(guardResult, el, state, { ...options, guards: [] })
+    }
+  }
+
   if (opts.pushState) {
     win.history.pushState(state, null, pathname + (search || '') + (hash || ''))
   }
 
   if (pathChanged || !hashChanged) {
+    const stateUpdate = { route, hash, debugging: false }
+    if (Object.keys(params).length) stateUpdate.params = params
+    if (Object.keys(query).length) stateUpdate.query = query
+
     if (opts.updateState) {
-      await element.state.update(
-        { route, hash, debugging: false },
+      element.state.update(
+        stateUpdate,
         { preventContentUpdate: true }
       )
     }
@@ -82,7 +245,7 @@ export const router = async (path, el, state = {}, options = {}) => {
       element[contentElementKey].remove()
     }
 
-    await element.set(
+    element.set(
       {
         tag: opts.useFragment && 'fragment',
         extends: content
@@ -112,7 +275,7 @@ export const router = async (path, el, state = {}, options = {}) => {
       const top =
         activeNode.getBoundingClientRect().top +
           rootNode.scrollTop -
-          opts.scrollToOffset || 0
+          (opts.scrollToOffset || 0)
       scrollNode.scrollTo({
         ...(opts.scrollToOptions || {}),
         top,
@@ -122,7 +285,7 @@ export const router = async (path, el, state = {}, options = {}) => {
   }
 
   // trigger `on.routeChanged`
-  await triggerEventOn('routeChanged', element, opts)
+  triggerEventOn('routeChanged', element, opts)
 }
 
 export default router

package/package.json

@@ -1,32 +1,41 @@
 {
   "name": "@domql/router",
-  "version": "3.1.2",
+  "version": "3.2.7",
   "license": "MIT",
   "type": "module",
-  "module": "dist/esm/index.js",
-  "unpkg": "dist/iife/index.js",
-  "jsdelivr": "dist/iife/index.js",
-  "main": "dist/esm/index.js",
-  "exports": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "unpkg": "./dist/iife/index.js",
+  "jsdelivr": "./dist/iife/index.js",
+  "main": "./dist/cjs/index.js",
+  "exports": {
+    ".": {
+      "import": "./dist/esm/index.js",
+      "require": "./dist/cjs/index.js",
+      "browser": "./dist/iife/index.js",
+      "default": "./dist/esm/index.js"
+    }
+  },
   "source": "index.js",
   "files": [
-    "*.js",
-    "dist"
+    "dist",
+    "*.js"
   ],
   "scripts": {
     "copy:package:cjs": "cp ../../build/package-cjs.json dist/cjs/package.json",
-    "build:esm": "npx esbuild *.js --target=es2017 --format=esm --outdir=dist/esm",
-    "build:cjs": "npx esbuild *.js --target=node16 --format=cjs --outdir=dist/cjs",
-    "build:iife": "npx esbuild *.js --target=node16 --format=iife --outdir=dist/iife",
-    "build": "npx rimraf -I dist; npm run build:cjs; npm run build:esm",
-    "prepublish": "npx rimraf -I dist && npm run build && npm run copy:package:cjs"
+    "build:esm": "cross-env NODE_ENV=$NODE_ENV esbuild *.js --target=es2020 --format=esm --outdir=dist/esm --define:process.env.NODE_ENV=process.env.NODE_ENV",
+    "build:cjs": "cross-env NODE_ENV=$NODE_ENV esbuild *.js --target=node18 --format=cjs --outdir=dist/cjs --define:process.env.NODE_ENV=process.env.NODE_ENV",
+    "build:iife": "cross-env NODE_ENV=$NODE_ENV esbuild index.js --bundle --target=es2020 --format=iife --global-name=DomqlRouter --outfile=dist/iife/index.js --define:process.env.NODE_ENV=process.env.NODE_ENV",
+    "build": "node ../../build/build.js",
+    "prepublish": "npm run build && npm run copy:package:cjs"
   },
   "dependencies": {
-    "@domql/event": "^3.1.2",
-    "@domql/utils": "^3.1.2"
+    "@domql/element": "^3.2.3",
+    "@domql/utils": "^3.2.3"
   },
-  "gitHead": "429b36616aa04c8587a26ce3c129815115e35897",
+  "gitHead": "9fc1b79b41cdc725ca6b24aec64920a599634681",
   "devDependencies": {
     "@babel/core": "^7.26.0"
-  }
+  },
+  "browser": "./dist/iife/index.js",
+  "sideEffects": false
 }

package/dist/cjs/package.json

@@ -1,4 +0,0 @@
-{
-  "type": "commonjs",
-  "main": "index.js"
-}