@constela/router 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Constela Contributors
+
+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/dist/index.d.ts

@@ -0,0 +1,79 @@
+import { CompiledProgram } from '@constela/compiler';
+
+/**
+ * Router - Main routing implementation
+ */
+
+interface RouteContext {
+    path: string;
+    params: Record<string, string>;
+    query: URLSearchParams;
+}
+interface RouteDef {
+    path: string;
+    program: CompiledProgram;
+    title?: string | ((ctx: RouteContext) => string);
+}
+interface RouterOptions {
+    routes: RouteDef[];
+    basePath?: string;
+    fallback?: CompiledProgram;
+    onRouteChange?: (ctx: RouteContext) => void;
+}
+interface RouterInstance {
+    mount(el: HTMLElement): {
+        destroy(): void;
+    };
+    navigate(to: string, opts?: {
+        replace?: boolean;
+    }): void;
+    getContext(): RouteContext;
+}
+declare function createRouter(options: RouterOptions): RouterInstance;
+
+/**
+ * Router helper functions
+ */
+
+/**
+ * Binds an anchor element to use the router for navigation
+ *
+ * @param router - Router instance
+ * @param anchor - Anchor element to bind
+ * @param to - Path to navigate to (optional, uses href if not provided)
+ * @returns Cleanup function to remove the binding
+ */
+declare function bindLink(router: RouterInstance, anchor: HTMLAnchorElement, to?: string): () => void;
+/**
+ * Creates a link element bound to the router
+ *
+ * @param router - Router instance
+ * @param to - Path to navigate to
+ * @param text - Link text content
+ * @returns Object with element and destroy function
+ */
+declare function createLink(router: RouterInstance, to: string, text: string): {
+    element: HTMLAnchorElement;
+    destroy: () => void;
+};
+
+/**
+ * Route matching utilities
+ */
+interface MatchResult {
+    params: Record<string, string>;
+}
+/**
+ * Matches a URL path against a route pattern
+ *
+ * @param pattern - Route pattern (e.g., "/users/:id")
+ * @param path - URL path to match (e.g., "/users/123")
+ * @returns Match result with params, or null if no match
+ */
+declare function matchRoute(pattern: string, path: string): MatchResult | null;
+/**
+ * Parses URL params from a matched route
+ */
+declare function parseParams(pattern: string, path: string): Record<string, string>;
+
+export { type RouteContext, type RouteDef, type RouterInstance, type RouterOptions, bindLink, createLink, createRouter, matchRoute, parseParams };

package/dist/index.js

@@ -0,0 +1,172 @@
+// src/router.ts
+import { createApp } from "@constela/runtime";
+
+// src/matcher.ts
+function matchRoute(pattern, path) {
+  const normalizedPattern = pattern === "/" ? "/" : pattern.replace(/\/+$/, "");
+  const normalizedPath = path === "/" ? "/" : path.replace(/\/+$/, "");
+  if (normalizedPattern === "/") {
+    return normalizedPath === "/" ? { params: {} } : null;
+  }
+  const patternParts = normalizedPattern.split("/").filter(Boolean);
+  const pathParts = normalizedPath.split("/").filter(Boolean);
+  if (patternParts.length !== pathParts.length) {
+    return null;
+  }
+  const params = {};
+  for (let i = 0; i < patternParts.length; i++) {
+    const patternPart = patternParts[i];
+    const pathPart = pathParts[i];
+    if (patternPart.startsWith(":")) {
+      const paramName = patternPart.slice(1);
+      params[paramName] = decodeURIComponent(pathPart);
+    } else if (patternPart !== pathPart) {
+      return null;
+    }
+  }
+  return { params };
+}
+function parseParams(pattern, path) {
+  const match = matchRoute(pattern, path);
+  return match?.params ?? {};
+}
+
+// src/router.ts
+function createRouter(options) {
+  const { routes, basePath = "", fallback, onRouteChange } = options;
+  const normalizedBasePath = basePath.replace(/\/+$/, "");
+  let mountElement = null;
+  let currentApp = null;
+  let currentContext = {
+    path: "",
+    params: {},
+    query: new URLSearchParams()
+  };
+  let destroyed = false;
+  function normalizePath(path) {
+    const [pathPart, queryPart] = path.split("?");
+    const cleanPath = pathPart.startsWith("/") ? pathPart : "/" + pathPart;
+    const fullPath = normalizedBasePath ? normalizedBasePath + cleanPath : cleanPath;
+    return queryPart ? `${fullPath}?${queryPart}` : fullPath;
+  }
+  function parseCurrentUrl() {
+    const rawPathname = window.location.pathname;
+    const [pathnameWithoutQuery, embeddedQuery] = rawPathname.split("?");
+    const pathname = pathnameWithoutQuery;
+    const queryString = window.location.search || (embeddedQuery ? `?${embeddedQuery}` : "");
+    const path = normalizedBasePath ? pathname.replace(new RegExp(`^${normalizedBasePath}`), "") || "/" : pathname;
+    const query = new URLSearchParams(queryString);
+    return { path, query };
+  }
+  function findMatchingRoute(path) {
+    for (const route of routes) {
+      const match = matchRoute(route.path, path);
+      if (match) {
+        return { route, params: match.params };
+      }
+    }
+    return { route: null, params: {} };
+  }
+  function renderRoute() {
+    if (!mountElement) return;
+    if (currentApp) {
+      currentApp.destroy();
+      currentApp = null;
+    }
+    const { path, query } = parseCurrentUrl();
+    const { route, params } = findMatchingRoute(path);
+    currentContext = {
+      path,
+      params,
+      query
+    };
+    const program = route?.program ?? fallback;
+    if (!program) {
+      throw new Error(`No route matched for path: ${path} and no fallback provided`);
+    }
+    currentApp = createApp(program, mountElement);
+    if (route?.title) {
+      const title = typeof route.title === "function" ? route.title(currentContext) : route.title;
+      document.title = title;
+    }
+    if (onRouteChange) {
+      onRouteChange(currentContext);
+    }
+  }
+  function handlePopState() {
+    if (destroyed || !mountElement) return;
+    try {
+      renderRoute();
+    } catch (error) {
+      console.error("Router error during navigation:", error);
+    }
+  }
+  return {
+    mount(el) {
+      mountElement = el;
+      window.addEventListener("popstate", handlePopState);
+      renderRoute();
+      return {
+        destroy() {
+          if (destroyed) return;
+          destroyed = true;
+          window.removeEventListener("popstate", handlePopState);
+          if (currentApp) {
+            currentApp.destroy();
+            currentApp = null;
+          }
+          mountElement = null;
+        }
+      };
+    },
+    navigate(to, opts) {
+      if (!mountElement) return;
+      const fullPath = normalizePath(to);
+      if (opts?.replace) {
+        window.history.replaceState({}, "", fullPath);
+      } else {
+        window.history.pushState({}, "", fullPath);
+      }
+      renderRoute();
+    },
+    getContext() {
+      return { ...currentContext };
+    }
+  };
+}
+
+// src/helpers.ts
+function bindLink(router, anchor, to) {
+  const targetPath = to ?? anchor.getAttribute("href") ?? "/";
+  function handleClick(event) {
+    if (event.ctrlKey || event.metaKey || event.shiftKey || event.altKey) {
+      return;
+    }
+    if (event.button !== 0) {
+      return;
+    }
+    event.preventDefault();
+    router.navigate(targetPath);
+  }
+  anchor.addEventListener("click", handleClick);
+  return () => {
+    anchor.removeEventListener("click", handleClick);
+  };
+}
+function createLink(router, to, text) {
+  const anchor = document.createElement("a");
+  anchor.href = to;
+  anchor.textContent = text;
+  const cleanup = bindLink(router, anchor, to);
+  return {
+    element: anchor,
+    destroy: cleanup
+  };
+}
+export {
+  bindLink,
+  createLink,
+  createRouter,
+  matchRoute,
+  parseParams
+};

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@constela/router",
+  "version": "0.1.0",
+  "description": "Client-side routing for Constela applications",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {},
+  "peerDependencies": {
+    "@constela/compiler": "^0.1.0",
+    "@constela/runtime": "^0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.10.0",
+    "jsdom": "^25.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.3.0",
+    "vitest": "^2.0.0",
+    "@constela/runtime": "0.2.0",
+    "@constela/compiler": "0.2.0"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "license": "MIT",
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "type-check": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "clean": "rm -rf dist"
+  }
+}