@symbo.ls/router 3.5.1 → 3.14.0

package/LICENSE

@@ -0,0 +1,34 @@
+Creative Commons Attribution-NonCommercial 4.0 International License
+
+Copyright (c) 2023 symbo.ls
+
+This work is licensed under the Creative Commons Attribution-NonCommercial
+4.0 International License. To view a copy of this license, visit
+https://creativecommons.org/licenses/by-nc/4.0/ or send a letter to
+Creative Commons, PO Box 1866, Mountain View, CA 94042, USA.
+
+You are free to:
+
+  Share — copy and redistribute the material in any medium or format
+  Adapt — remix, transform, and build upon the material
+
+Under the following terms:
+
+  Attribution — You must give appropriate credit, provide a link to the
+  license, and indicate if changes were made. You may do so in any
+  reasonable manner, but not in any way that suggests the licensor endorses
+  you or your use.
+
+  NonCommercial — You may not use the material for commercial purposes.
+
+  No additional restrictions — You may not apply legal terms or
+  technological measures that legally restrict others from doing anything
+  the license permits.
+
+THE WORK IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE WORK OR THE USE OR OTHER DEALINGS IN THE
+WORK.

package/README.md

@@ -0,0 +1,234 @@
+# @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.
+
+## Custom Router Element
+
+Use `customRouterElement` in your `config.js` to route pages into a specific element within the component tree instead of the root. This is useful for persistent layouts where only the content area changes between routes.
+
+```js
+// symbols/config.js
+export default {
+  router: {
+    customRouterElement: 'Folder.Content'
+  }
+}
+```
+
+The value is a dot-separated path resolved from the root element. For example, `'Folder.Content'` means the router will find `root.Folder.Content` and render page content inside it.
+
+This allows you to define a layout once in the `/` (main) page and have sub-pages render inside a specific container:
+
+```js
+// pages/main.js — defines the persistent layout
+export const main = {
+  extends: 'Layout',
+  Folder: {
+    Content: {
+      // default content for '/' route
+    }
+  }
+}
+
+// pages/team.js — only defines content (rendered inside Folder.Content)
+export const team = {
+  state: 'team',
+  extends: 'Grid',
+  childExtends: 'TeamItem',
+  childrenAs: 'state',
+  children: (el, s) => s.data,
+}
+```
+
+## 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 `onRouteChanged` event on the element after navigation completes. Listen for it in your element definition:
+
+```js
+const App = {
+  routes: { ... },
+  onRouteChanged: (element, options) => {
+    console.log('Route changed:', element.state.route)
+  }
+}
+```
+
+## License
+
+MIT

package/dist/cjs/index.js

@@ -0,0 +1,281 @@
+"use strict";
+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);
+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
+});
+module.exports = __toCommonJS(index_exports);
+var import_utils = require("@symbo.ls/utils");
+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) => {
+  if (!route) route = typeof import_utils.window !== "undefined" ? import_utils.window.location.pathname : "/";
+  const routeArray = route.split("/");
+  const activeRoute = routeArray[level + 1];
+  if (activeRoute) return `/${activeRoute}`;
+};
+let lastPathname;
+let lastLevel = 0;
+const normalizePath = (p) => !p || p === "srcdoc" || p === "about:srcdoc" ? "/" : p;
+const defaultOptions = {
+  level: lastLevel,
+  pushState: true,
+  initialRender: false,
+  scrollToTop: true,
+  scrollToNode: false,
+  scrollNode: import_utils.document && import_utils.document.documentElement,
+  scrollBody: false,
+  useFragment: false,
+  updateState: true,
+  scrollToOffset: 0,
+  contentElementKey: "content",
+  scrollToOptions: { behavior: "smooth" },
+  useParamsMatching: true
+};
+const router = async (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;
+  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 = ref.contentElementKey || opts.contentElementKey || "content";
+  const origin = win.location.origin !== "null" ? win.location.origin : "http://localhost";
+  path = normalizePath(path);
+  const urlObj = new win.URL(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 (element.state?.root?.debugging) {
+    element.state.root.debugging = false;
+    return;
+  }
+  if (!content) {
+    if (opts.onNotFound) {
+      opts.onNotFound({ pathname, route, element });
+    } else if (!opts.silent) {
+      console.warn("[smbls/router] no content matched for path", pathname, "\u2014 available routes:", Object.keys(element.routes || {}));
+    }
+    return;
+  }
+  if (opts.guards && opts.guards.length) {
+    const guardContext = { pathname, route, params, query, hash, element, state };
+    const guardResult = await runGuards(opts.guards, guardContext);
+    if (guardResult === false) return;
+    if (typeof guardResult === "string") {
+      return router(guardResult, el, state, { ...options, guards: [] });
+    }
+  }
+  if (opts.pushState) {
+    try {
+      win.history.pushState(state, null, pathname + (search || "") + (hash || ""));
+    } catch (e) {
+    }
+  }
+  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();
+    }
+    const originContent = element.__ref?.origin?.content;
+    const contentStyles = {};
+    if (originContent) {
+      for (const k in originContent) {
+        const v = originContent[k];
+        if (k === "__ref" || k === "props" || k === "node" || k === "parent" || k === "key") continue;
+        if (typeof v === "string" || typeof v === "number" || typeof v === "boolean" || typeof v === "object" && v !== null && !v.node && !v.__ref) {
+          contentStyles[k] = v;
+        }
+      }
+    }
+    const nextContent = {
+      ...contentStyles,
+      ...typeof content === "object" ? content : { extends: content }
+    };
+    if (opts.useFragment) nextContent.tag = "fragment";
+    try {
+      element.set(nextContent, { contentElementKey });
+    } catch (err) {
+      console.error("[smbls/router] failed to render route content", pathname, err);
+    }
+  }
+  if (opts.scrollToTop && scrollNode?.scrollTo) {
+    scrollNode.scrollTo({
+      ...opts.scrollToOptions || {},
+      top: 0,
+      left: 0
+    });
+  }
+  if (opts.scrollToNode && content[contentElementKey]?.node?.scrollTo) {
+    content[contentElementKey].node.scrollTo({
+      ...opts.scrollToOptions || {},
+      top: 0,
+      left: 0
+    });
+  }
+  if (hash) {
+    const activeNode = doc.getElementById(hash);
+    if (activeNode && scrollNode?.scrollTo) {
+      const top = activeNode.getBoundingClientRect().top + rootNode.scrollTop - (opts.scrollToOffset || 0);
+      scrollNode.scrollTo({
+        ...opts.scrollToOptions || {},
+        top,
+        left: 0
+      });
+    }
+  }
+  (0, import_utils.triggerEventOn)("routeChanged", element, opts);
+};
+var index_default = router;