@matthesketh/utopia-router 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matt Hesketh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE 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 SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,74 @@
+# @matthesketh/utopia-router
+
+File-based routing for UtopiaJS with History API, navigation guards, and reactive route state. SvelteKit-style file conventions (`+page.utopia`, `+layout.utopia`, `[param]`, `[...rest]`, `(group)`).
+
+## Install
+
+```bash
+pnpm add @matthesketh/utopia-router
+```
+
+## Usage
+
+```ts
+import { createRouter, currentRoute, navigate } from '@matthesketh/utopia-router';
+import { buildRouteTable } from '@matthesketh/utopia-router';
+
+const routes = buildRouteTable(routeManifest);
+createRouter(routes);
+
+// Reactive route state
+console.log(currentRoute().pathname);
+
+// Programmatic navigation
+navigate('/about');
+```
+
+## File Conventions
+
+| File Path | URL Pattern |
+|-----------|-------------|
+| `src/routes/+page.utopia` | `/` |
+| `src/routes/about/+page.utopia` | `/about` |
+| `src/routes/blog/[slug]/+page.utopia` | `/blog/:slug` |
+| `src/routes/[...rest]/+page.utopia` | `/*rest` (catch-all) |
+| `src/routes/(auth)/login/+page.utopia` | `/login` (route group) |
+| `src/routes/+layout.utopia` | Layout wrapper |
+| `src/routes/+error.utopia` | Error boundary |
+
+## API
+
+**Route matching:**
+
+| Export | Description |
+|--------|-------------|
+| `filePathToRoute(path)` | Convert a file path to a route pattern |
+| `compilePattern(pattern)` | Compile a route pattern to a regex matcher |
+| `matchRoute(routes, url)` | Match a URL against a route table |
+| `buildRouteTable(manifest)` | Build a route table from a file manifest |
+
+**Client-side router:**
+
+| Export | Description |
+|--------|-------------|
+| `createRouter(routes)` | Initialize the client router |
+| `navigate(url)` | Programmatic navigation |
+| `back()` | Go back in history |
+| `forward()` | Go forward in history |
+| `beforeNavigate(hook)` | Register a navigation guard |
+| `destroy()` | Tear down the router |
+| `currentRoute` | Reactive signal with the current route |
+| `isNavigating` | Reactive signal indicating navigation in progress |
+
+**Components:**
+
+| Export | Description |
+|--------|-------------|
+| `createRouterView()` | Render the matched route component |
+| `createLink(props)` | Create a client-side navigation link |
+
+See [docs/architecture.md](../../docs/architecture.md) for full routing details.
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,531 @@
+"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);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  back: () => back,
+  beforeNavigate: () => beforeNavigate,
+  buildRouteTable: () => buildRouteTable,
+  compilePattern: () => compilePattern,
+  createLink: () => createLink,
+  createRouter: () => createRouter,
+  createRouterView: () => createRouterView,
+  currentRoute: () => currentRoute,
+  destroy: () => destroy,
+  filePathToRoute: () => filePathToRoute,
+  forward: () => forward,
+  isNavigating: () => isNavigating,
+  matchRoute: () => matchRoute,
+  navigate: () => navigate
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/matcher.ts
+function filePathToRoute(filePath) {
+  let normalized = filePath.replace(/\\/g, "/");
+  const routesIdx = normalized.indexOf("routes/");
+  if (routesIdx !== -1) {
+    normalized = normalized.slice(routesIdx + "routes/".length);
+  }
+  normalized = normalized.replace(/\/?\+page\.\w+$/, "");
+  normalized = normalized.replace(/\/?\+(layout|error)\.\w+$/, "");
+  const segments = normalized.split("/").filter(Boolean);
+  const routeSegments = [];
+  for (const segment of segments) {
+    if (/^\(.+\)$/.test(segment)) {
+      continue;
+    }
+    if (/^\[\.\.\..+\]$/.test(segment)) {
+      const paramName = segment.slice(4, -1);
+      routeSegments.push(`*${paramName}`);
+      continue;
+    }
+    if (/^\[.+\]$/.test(segment)) {
+      const paramName = segment.slice(1, -1);
+      routeSegments.push(`:${paramName}`);
+      continue;
+    }
+    routeSegments.push(segment);
+  }
+  const path = "/" + routeSegments.join("/");
+  return path;
+}
+function compilePattern(pattern) {
+  const params = [];
+  if (pattern === "/") {
+    return {
+      regex: /^\/$/,
+      params: []
+    };
+  }
+  const segments = pattern.split("/").filter(Boolean);
+  let regexStr = "";
+  for (let i = 0; i < segments.length; i++) {
+    const segment = segments[i];
+    if (segment.startsWith("*")) {
+      const paramName = segment.slice(1);
+      params.push(paramName);
+      regexStr += "/(.+)";
+    } else if (segment.startsWith(":")) {
+      const paramName = segment.slice(1);
+      params.push(paramName);
+      regexStr += "/([^/]+)";
+    } else {
+      regexStr += "/" + escapeRegex(segment);
+    }
+  }
+  regexStr = "^" + regexStr + "/?$";
+  return {
+    regex: new RegExp(regexStr),
+    params
+  };
+}
+function escapeRegex(str) {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function matchRoute(url, routes2) {
+  const pathname = url.pathname;
+  for (const route of routes2) {
+    const match = route.pattern.exec(pathname);
+    if (match) {
+      const params = {};
+      for (let i = 0; i < route.params.length; i++) {
+        params[route.params[i]] = decodeURIComponent(match[i + 1]);
+      }
+      return { route, params, url };
+    }
+  }
+  return null;
+}
+function buildRouteTable(manifest) {
+  const pages = /* @__PURE__ */ new Map();
+  const layouts = /* @__PURE__ */ new Map();
+  const errors = /* @__PURE__ */ new Map();
+  for (const [filePath, importFn] of Object.entries(manifest)) {
+    const normalized = filePath.replace(/\\/g, "/");
+    if (/\+page\.\w+$/.test(normalized)) {
+      pages.set(normalized, importFn);
+    } else if (/\+layout\.\w+$/.test(normalized)) {
+      layouts.set(normalized, importFn);
+    } else if (/\+error\.\w+$/.test(normalized)) {
+      errors.set(normalized, importFn);
+    }
+  }
+  const routes2 = [];
+  for (const [filePath, importFn] of pages) {
+    const path = filePathToRoute(filePath);
+    const { regex, params } = compilePattern(path);
+    const layout = findNearestSpecialFile(filePath, layouts);
+    const error = findNearestSpecialFile(filePath, errors);
+    routes2.push({
+      path,
+      pattern: regex,
+      params,
+      component: importFn,
+      layout,
+      error
+    });
+  }
+  routes2.sort((a, b) => {
+    const scoreA = routeSpecificity(a.path);
+    const scoreB = routeSpecificity(b.path);
+    if (scoreA !== scoreB) {
+      return scoreB - scoreA;
+    }
+    return a.path.localeCompare(b.path);
+  });
+  return routes2;
+}
+function routeSpecificity(path) {
+  if (path === "/") {
+    return 10;
+  }
+  const segments = path.split("/").filter(Boolean);
+  let score = 0;
+  for (const segment of segments) {
+    if (segment.startsWith("*")) {
+      score += 1;
+    } else if (segment.startsWith(":")) {
+      score += 2;
+    } else {
+      score += 3;
+    }
+  }
+  return score;
+}
+function findNearestSpecialFile(pageFilePath, specialFiles) {
+  const normalized = pageFilePath.replace(/\\/g, "/");
+  const lastSlash = normalized.lastIndexOf("/");
+  let dir = lastSlash !== -1 ? normalized.slice(0, lastSlash) : "";
+  while (dir) {
+    for (const [specialPath, importFn] of specialFiles) {
+      const specialNorm = specialPath.replace(/\\/g, "/");
+      const specialLastSlash = specialNorm.lastIndexOf("/");
+      const specialDir = specialLastSlash !== -1 ? specialNorm.slice(0, specialLastSlash) : "";
+      if (specialDir === dir) {
+        return importFn;
+      }
+    }
+    const parentSlash = dir.lastIndexOf("/");
+    if (parentSlash === -1) {
+      break;
+    }
+    dir = dir.slice(0, parentSlash);
+  }
+  return void 0;
+}
+
+// src/router.ts
+var import_utopia_core = require("@matthesketh/utopia-core");
+var currentRoute = (0, import_utopia_core.signal)(null);
+var isNavigating = (0, import_utopia_core.signal)(false);
+var routes = [];
+var beforeNavigateHooks = [];
+var scrollPositions = /* @__PURE__ */ new Map();
+var navIndex = 0;
+var cleanup = null;
+function createRouter(routeTable) {
+  if (cleanup) {
+    cleanup();
+  }
+  routes = routeTable;
+  beforeNavigateHooks = [];
+  scrollPositions.clear();
+  navIndex = 0;
+  if (typeof window !== "undefined" && typeof history !== "undefined") {
+    history.replaceState({ _utopiaNavIndex: navIndex }, "");
+  }
+  if (typeof window !== "undefined") {
+    const url = new URL(window.location.href);
+    const match = matchRoute(url, routes);
+    currentRoute.set(match);
+  }
+  if (typeof window !== "undefined") {
+    const handlePopState = (event) => {
+      const state = event.state;
+      const targetIndex = state?._utopiaNavIndex ?? 0;
+      scrollPositions.set(navIndex, { x: window.scrollX, y: window.scrollY });
+      navIndex = targetIndex;
+      const url = new URL(window.location.href);
+      const match = matchRoute(url, routes);
+      runBeforeNavigateHooks(currentRoute.peek(), match).then((result) => {
+        if (result === false) {
+          return;
+        }
+        if (typeof result === "string") {
+          navigate(result, { replace: true });
+          return;
+        }
+        currentRoute.set(match);
+        const savedPos = scrollPositions.get(targetIndex);
+        if (savedPos) {
+          requestAnimationFrame(() => {
+            window.scrollTo(savedPos.x, savedPos.y);
+          });
+        }
+      });
+    };
+    const handleClick = (event) => {
+      if (event.button !== 0) return;
+      if (event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) return;
+      if (event.defaultPrevented) return;
+      const anchor = findAnchorElement(event.target);
+      if (!anchor) return;
+      if (anchor.hasAttribute("target") || anchor.hasAttribute("download")) return;
+      const href = anchor.getAttribute("href");
+      if (!href) return;
+      if (!href.startsWith("/") && !href.startsWith(window.location.origin)) return;
+      if (href.startsWith("#")) return;
+      event.preventDefault();
+      navigate(href);
+    };
+    window.addEventListener("popstate", handlePopState);
+    document.addEventListener("click", handleClick);
+    cleanup = () => {
+      window.removeEventListener("popstate", handlePopState);
+      document.removeEventListener("click", handleClick);
+      cleanup = null;
+    };
+  }
+}
+async function navigate(url, options = {}) {
+  if (typeof window === "undefined") return;
+  isNavigating.set(true);
+  try {
+    const fullUrl = new URL(url, window.location.origin);
+    const match = matchRoute(fullUrl, routes);
+    const hookResult = await runBeforeNavigateHooks(currentRoute.peek(), match);
+    if (hookResult === false) {
+      return;
+    }
+    if (typeof hookResult === "string") {
+      await navigate(hookResult, options);
+      return;
+    }
+    scrollPositions.set(navIndex, { x: window.scrollX, y: window.scrollY });
+    navIndex++;
+    const state = { _utopiaNavIndex: navIndex };
+    if (options.replace) {
+      history.replaceState(state, "", fullUrl.href);
+    } else {
+      history.pushState(state, "", fullUrl.href);
+    }
+    currentRoute.set(match);
+    requestAnimationFrame(() => {
+      if (fullUrl.hash) {
+        const el = document.getElementById(fullUrl.hash.slice(1));
+        if (el) {
+          el.scrollIntoView();
+          return;
+        }
+      }
+      window.scrollTo(0, 0);
+    });
+  } finally {
+    isNavigating.set(false);
+  }
+}
+function back() {
+  if (typeof window !== "undefined") {
+    history.back();
+  }
+}
+function forward() {
+  if (typeof window !== "undefined") {
+    history.forward();
+  }
+}
+function beforeNavigate(hook) {
+  beforeNavigateHooks.push(hook);
+  return () => {
+    const idx = beforeNavigateHooks.indexOf(hook);
+    if (idx !== -1) {
+      beforeNavigateHooks.splice(idx, 1);
+    }
+  };
+}
+function destroy() {
+  if (cleanup) {
+    cleanup();
+  }
+  routes = [];
+  beforeNavigateHooks = [];
+  scrollPositions.clear();
+  navIndex = 0;
+  currentRoute.set(null);
+  isNavigating.set(false);
+}
+function findAnchorElement(target) {
+  while (target) {
+    if (target.tagName === "A") {
+      return target;
+    }
+    target = target.parentElement;
+  }
+  return null;
+}
+async function runBeforeNavigateHooks(from, to) {
+  for (const hook of beforeNavigateHooks) {
+    const result = await hook(from, to);
+    if (result === false) {
+      return false;
+    }
+    if (typeof result === "string") {
+      return result;
+    }
+  }
+  return void 0;
+}
+
+// src/components.ts
+var import_utopia_core2 = require("@matthesketh/utopia-core");
+function createRouterView() {
+  const container = document.createElement("div");
+  container.setAttribute("data-utopia-router-view", "");
+  let currentCleanup = null;
+  let currentMatch = null;
+  (0, import_utopia_core2.effect)(() => {
+    const match = currentRoute();
+    if (match === currentMatch) {
+      return;
+    }
+    currentMatch = match;
+    if (currentCleanup) {
+      currentCleanup();
+      currentCleanup = null;
+    }
+    while (container.firstChild) {
+      container.removeChild(container.firstChild);
+    }
+    if (!match) {
+      const notFound = document.createElement("div");
+      notFound.setAttribute("data-utopia-not-found", "");
+      notFound.textContent = "Page not found";
+      container.appendChild(notFound);
+      return;
+    }
+    loadRouteComponent(match, container).then((cleanupFn) => {
+      currentCleanup = cleanupFn;
+    });
+  });
+  return container;
+}
+async function loadRouteComponent(match, container) {
+  try {
+    const promises = [match.route.component()];
+    if (match.route.layout) {
+      promises.push(match.route.layout());
+    }
+    const modules = await Promise.all(promises);
+    const pageModule = modules[0];
+    const layoutModule = modules.length > 1 ? modules[1] : null;
+    if (currentRoute.peek() !== match) {
+      return null;
+    }
+    const PageComponent = pageModule.default ?? pageModule;
+    const LayoutComponent = layoutModule ? layoutModule.default ?? layoutModule : null;
+    while (container.firstChild) {
+      container.removeChild(container.firstChild);
+    }
+    const pageNode = renderComponent(PageComponent, {
+      params: match.params,
+      url: match.url
+    });
+    if (LayoutComponent) {
+      const layoutNode = renderComponent(LayoutComponent, {
+        params: match.params,
+        url: match.url,
+        children: pageNode
+      });
+      container.appendChild(layoutNode);
+    } else {
+      container.appendChild(pageNode);
+    }
+    return () => {
+      while (container.firstChild) {
+        container.removeChild(container.firstChild);
+      }
+    };
+  } catch (err) {
+    if (match.route.error) {
+      try {
+        const errorModule = await match.route.error();
+        const ErrorComponent = errorModule.default ?? errorModule;
+        while (container.firstChild) {
+          container.removeChild(container.firstChild);
+        }
+        const errorNode = renderComponent(ErrorComponent, {
+          error: err,
+          params: match.params,
+          url: match.url
+        });
+        container.appendChild(errorNode);
+      } catch {
+        renderFallbackError(container, err);
+      }
+    } else {
+      renderFallbackError(container, err);
+    }
+    return () => {
+      while (container.firstChild) {
+        container.removeChild(container.firstChild);
+      }
+    };
+  }
+}
+function renderComponent(component, props) {
+  if (typeof component === "function") {
+    const result = component(props);
+    if (result instanceof Node) {
+      return result;
+    }
+    if (typeof result === "string") {
+      return document.createTextNode(result);
+    }
+    if (result && typeof result.render === "function") {
+      return result.render();
+    }
+  }
+  if (component && typeof component.render === "function") {
+    return component.render(props);
+  }
+  const div = document.createElement("div");
+  div.textContent = "[Component render error]";
+  return div;
+}
+function renderFallbackError(container, error) {
+  while (container.firstChild) {
+    container.removeChild(container.firstChild);
+  }
+  const errorDiv = document.createElement("div");
+  errorDiv.setAttribute("data-utopia-error", "");
+  errorDiv.style.cssText = "padding:2rem;color:#dc2626;font-family:monospace;";
+  errorDiv.innerHTML = `
+    <h2 style="margin:0 0 1rem">Route Error</h2>
+    <pre style="white-space:pre-wrap;word-break:break-word;">${escapeHtml(
+    error instanceof Error ? error.message : String(error)
+  )}</pre>
+  `;
+  container.appendChild(errorDiv);
+}
+function createLink(props) {
+  const anchor = document.createElement("a");
+  anchor.href = props.href;
+  if (props.class) {
+    anchor.className = props.class;
+  }
+  if (typeof props.children === "string") {
+    anchor.textContent = props.children;
+  } else {
+    anchor.appendChild(props.children);
+  }
+  if (props.activeClass) {
+    (0, import_utopia_core2.effect)(() => {
+      const match = currentRoute();
+      const isActive = match ? match.url.pathname === props.href || match.url.pathname.startsWith(props.href + "/") : false;
+      if (isActive) {
+        anchor.classList.add(props.activeClass);
+      } else {
+        anchor.classList.remove(props.activeClass);
+      }
+    });
+  }
+  return anchor;
+}
+function escapeHtml(str) {
+  return str.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#x27;");
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  back,
+  beforeNavigate,
+  buildRouteTable,
+  compilePattern,
+  createLink,
+  createRouter,
+  createRouterView,
+  currentRoute,
+  destroy,
+  filePathToRoute,
+  forward,
+  isNavigating,
+  matchRoute,
+  navigate
+});