@ripetchor/r-router 1.0.0 → 1.0.1

package/README.md

@@ -1 +1,168 @@
-# r-router
+# R-Router
+
+HistoryAPI router.
+
+**WARNING**: This router is primarily intended for personal use. It may contain bugs or unexpected behavior. Use at your own risk.
+
+## Usage
+
+```typescript
+import { createRouter, RouterOutlet, RouteContext } from '@ripetchor/r-router';
+
+const routes = [
+  {
+    path: '/',
+    component: () => {
+      const div = document.createElement('div');
+      div.textContent = 'Home';
+      return div;
+    },
+  },
+  {
+    path: '/user/:id',
+    component: (ctx: RouteContext) => {
+      const div = document.createElement('div');
+      div.textContent = `User ID: ${ctx.params.id}`;
+      return div;
+    },
+  },
+  {
+    path: '/about',
+    loadComponent: async () => {
+      const { default: About } = await import('./About');
+      return About();
+    },
+  },
+  {
+    path: '/old-path',
+    redirectTo: '/new-path',
+  },
+  {
+    path: '*',
+    component: () => {
+      const div = document.createElement('div');
+      div.textContent = '404 Not Found';
+      return div;
+    },
+  },
+];
+
+const router = createRouter(routes, { defaultTitle: 'My App' });
+
+async function init() {
+  const outlet: RouterOutlet = await router.initialize();
+
+  const header = document.createElement('header');
+  const nav = document.createElement('nav');
+  const links = [
+    { text: 'Home', path: '/' },
+    { text: 'About', path: '/about' },
+    { text: 'User', path: '/user/1' },
+  ];
+
+  links.forEach((link) => {
+    const a = document.createElement('a');
+    a.href = link.path;
+    a.textContent = link.text;
+    a.addEventListener('click', (e) => {
+      e.preventDefault();
+      router.push(link.path);
+    });
+    nav.appendChild(a);
+  });
+
+  header.appendChild(nav);
+
+  const footer = document.createElement('footer');
+
+  document.body.appendChild(header);
+  document.body.appendChild(outlet);
+  document.body.appendChild(footer);
+}
+
+init();
+```
+
+## API
+
+### `createRouter(routes: Route[], options?: RouterOptions): Router`
+
+Creates a router instance.
+
+- `routes`: Array of route definitions.
+- `options`:
+  - `defaultTitle`: Fallback document title.
+  - `globalErrorComponent`: Custom error component.
+  - `sortRoutesBySpecificity`: Sort routes by specificity (default: `true`).
+  - `ignoreSameLocation`: Skip same-path navigation (default: `true`).
+
+#### `initialize(): Promise<RouterOutlet>`
+
+Sets up popstate listener, navigates to current path, returns root `RouterOutlet`(web-component). Throws an error if it has been initialized.
+
+#### `push(path: string, state?: unknown): Promise<void>`
+
+Navigates, adding to history.
+
+#### `replace(path: string, state?: unknown): Promise<void>`
+
+Navigates, replacing history entry.
+
+### Route Types
+
+- `SyncRoute`: Returns `HTMLElement` via `component(ctx: RouteContext)`.
+- `AsyncRoute`: Returns `Promise<HTMLElement>` via `loadComponent(ctx: RouteContext)`.
+- `RedirectRoute`: Redirects via `redirectTo`.
+
+#### `Route.beforeEnter`
+
+Runs before navigation. Return `false` to cancel, string to redirect, or `true` to proceed.
+
+```typescript
+{
+  path: '/protected',
+  beforeEnter: [(ctx: RouteContext) => isAuthenticated() ? true : '/login'],
+}
+```
+
+#### `Route.afterEnter`
+
+Runs after navigation.
+
+```typescript
+{
+  path: '/dashboard',
+  afterEnter: [(ctx: RouteContext) => console.log('Entered dashboard')],
+}
+```
+
+### Error Handling
+
+Use `errorComponent` in routes or `globalErrorComponent` in options.
+
+```typescript
+const routes = [
+  {
+    path: '*',
+    errorComponent: (error, ctx) => {
+      const div = document.createElement('div');
+      div.textContent = `Error: ${error.message}`;
+      return div;
+    },
+  },
+];
+
+// or
+
+const router = createRouter(routes, {
+  globalErrorComponent: (error) => {
+    const div = document.createElement('div');
+    div.textContent = 'Global Error';
+    return div;
+  },
+});
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -11,7 +11,7 @@ declare interface BaseRoute {
     title?: string | ((ctx: RouteContext) => string);
     beforeEnter?: BeforeEnterHook[];
     afterEnter?: AfterEnterHook[];
-    errorComponent?(error: unknown, ctx: RouteContext | null): HTMLElement;
+    errorComponent?(error: Error, ctx: RouteContext | null): HTMLElement;
 }
 
 export declare type BeforeEnterHook = (ctx: RouteContext) => boolean | string | Promise<boolean | string>;
@@ -26,7 +26,7 @@ declare interface RedirectRoute extends BaseRoute {
 
 export declare type Route = SyncRoute | AsyncRoute | RedirectRoute;
 
-declare interface RouteContext {
+export declare interface RouteContext {
     from: string | null;
     to: string;
     params: Record<string, string>;
@@ -38,9 +38,9 @@ export declare class Router {
     private readonly routerController;
     private initialized;
     private navigationController;
-    private readonly matchers;
+    private readonly routeMatchers;
     private readonly options;
-    private readonly rootOutletInternal;
+    private readonly outlet;
     private currentPath;
     constructor(routes: Route[], options?: RouterOptions);
     initialize(): Promise<Readonly<RouterOutlet>>;
@@ -52,7 +52,7 @@ export declare class Router {
 
 declare interface RouterOptions {
     defaultTitle?: string;
-    globalErrorComponent?: (error: unknown) => HTMLElement;
+    globalErrorComponent?: (error: Error) => HTMLElement;
     sortRoutesBySpecificity?: boolean;
     ignoreSameLocation?: boolean;
 }
@@ -71,4 +71,6 @@ declare interface SyncRoute extends BaseRoute {
     loadComponent?(): Promise<HTMLElement>;
 }
 
+export declare function withAbortSignal<T>(fn: () => Promise<T>, signal: AbortSignal): Promise<T>;
+
 export { }

package/dist/index.js

@@ -1,6 +1,6 @@
 function P(t, e) {
-  const n = document.createElement("div");
-  n.style.cssText = `
+  const o = document.createElement("div");
+  o.style.cssText = `
     position: fixed;
     inset: 0;
     background-color: rgba(0, 0, 0, 0.5);
@@ -11,8 +11,8 @@ function P(t, e) {
     backdrop-filter: blur(4px);
     animation: fadeIn 0.25s ease;
   `;
-  const o = document.createElement("div");
-  o.style.cssText = `
+  const n = document.createElement("div");
+  n.style.cssText = `
     position: relative;
     max-width: 80dvh;
     width: 100%;
@@ -81,101 +81,115 @@ function P(t, e) {
   }, l.onmouseleave = () => {
     l.style.opacity = "0.7";
   }, l.onclick = () => {
-    n.remove();
+    o.remove();
   }, f.onmouseenter = () => {
     f.style.backgroundColor = "var(--button-bg-hover)";
   }, f.onmouseleave = () => {
     f.style.backgroundColor = "var(--button-bg)";
   }, f.onclick = () => {
     location.reload();
-  }, n.appendChild(o), o.append(l, r, i, a), t.stack && o.append(d), o.append(f);
+  }, o.appendChild(n), n.append(l, r, i, a), t.stack && n.append(d), n.append(f);
   const g = (u) => {
-    u.key === "Escape" && n.remove();
+    u.key === "Escape" && o.remove();
   };
   window.addEventListener("keydown", g);
   const w = new MutationObserver(() => {
-    document.body.contains(n) || (window.removeEventListener("keydown", g), w.disconnect());
+    document.body.contains(o) || (window.removeEventListener("keydown", g), w.disconnect());
   });
   w.observe(document.body, { childList: !0 });
   const y = () => {
     const u = window.matchMedia("(prefers-color-scheme: dark)").matches;
-    o.style.setProperty("--bg", u ? "#2b2b2b" : "#fff"), o.style.setProperty("--text", u ? "#eee" : "#222"), o.style.setProperty("--accent", u ? "#ff6b6b" : "#e74c3c"), o.style.setProperty(
+    n.style.setProperty("--bg", u ? "#2b2b2b" : "#fff"), n.style.setProperty("--text", u ? "#eee" : "#222"), n.style.setProperty("--accent", u ? "#ff6b6b" : "#e74c3c"), n.style.setProperty(
       "--code-bg",
       u ? "rgba(255,255,255,0.05)" : "rgba(0,0,0,0.05)"
-    ), o.style.setProperty("--button-bg", u ? "#3498db55" : "#3498db"), o.style.setProperty(
+    ), n.style.setProperty("--button-bg", u ? "#3498db55" : "#3498db"), n.style.setProperty(
       "--button-bg-hover",
       u ? "#3498db88" : "#2980b9"
-    ), o.style.setProperty("--button-text", "#fff");
+    ), n.style.setProperty("--button-text", "#fff");
   };
   window.matchMedia("(prefers-color-scheme: dark)").addEventListener("change", y), y();
   const b = document.createElement("style");
   return b.textContent = `
     @keyframes fadeIn { from { opacity: 0; } to { opacity: 1; } }
     @keyframes scaleIn { from { transform: scale(0.95); opacity: 0; } to { transform: scale(1); opacity: 1; } }
-  `, document.head.appendChild(b), n;
+  `, document.head.appendChild(b), o;
 }
-function k(t, e, n) {
-  t.title ? document.title = typeof t.title == "function" ? t.title(e) : t.title : document.title = n ?? "";
+async function p(t, e) {
+  if (e.aborted)
+    throw new DOMException("Aborted", "AbortError");
+  return new Promise((o, n) => {
+    const r = () => n(new DOMException("Aborted", "AbortError"));
+    e.addEventListener("abort", r), t().then(o).catch(n).finally(() => {
+      e.removeEventListener("abort", r);
+    });
+  });
 }
-function p(t, e, n) {
-  const o = e ?? null;
-  switch (n) {
+function k(t) {
+  const e = typeof t == "string" ? t : "Unknown error";
+  return t instanceof Error ? t : new Error(e);
+}
+function T(t, e, o) {
+  t.title ? document.title = typeof t.title == "function" ? t.title(e) : t.title : document.title = o ?? "";
+}
+function m(t, e, o) {
+  const n = e ?? null;
+  switch (o) {
     case "push":
-      window.history.pushState(o, "", t);
+      window.history.pushState(n, "", t);
       break;
     case "replace":
-      window.history.replaceState(o, "", t);
+      window.history.replaceState(n, "", t);
       break;
   }
 }
-function T(t, e) {
+function L(t, e) {
   t.replaceChildren(e);
 }
-function h(t, e, n, o, r) {
-  const i = n?.errorComponent?.(e, o) ?? r?.(e) ?? P(e, o);
-  t.replaceChildren(i);
+function h(t, e, o, n, r) {
+  const i = k(e), a = o?.errorComponent?.(i, n) ?? r?.(i) ?? P(i, n);
+  t.replaceChildren(a);
 }
 const A = "*";
-function L({ path: t }) {
+function z({ path: t }) {
   return t.includes(":");
 }
 function x(t) {
   const [, e] = t.split("?");
   return new URLSearchParams(e || "");
 }
-function $({ path: t }) {
+function S({ path: t }) {
   const e = t.replace(
     /:([^/]+)/g,
-    (n, o) => `(?<${o}>[^/]+)`
+    (o, n) => `(?<${n}>[^/]+)`
   );
   return new RegExp(`^${e}$`);
 }
-function S(t) {
-  const e = $(t);
+function $(t) {
+  const e = S(t);
   return {
     route: t,
     redirectTo: t.redirectTo || null,
-    match(n) {
-      const o = n.split("?")[0];
-      return e.test(o);
+    match(o) {
+      const n = o.split("?")[0];
+      return e.test(n);
     },
-    getParams(n) {
-      return e.exec(n)?.groups ?? {};
+    getParams(o) {
+      return e.exec(o)?.groups ?? {};
     },
     getQuery: x
   };
 }
-function z({ path: t }) {
+function M({ path: t }) {
   return t === A ? new RegExp("^.*$") : new RegExp(`^${t}$`);
 }
-function I(t) {
-  const e = z(t);
+function W(t) {
+  const e = M(t);
   return {
     route: t,
     redirectTo: t.redirectTo || null,
-    match(n) {
-      const o = n.split("?")[0];
-      return e.test(o);
+    match(o) {
+      const n = o.split("?")[0];
+      return e.test(n);
     },
     getParams() {
       return {};
@@ -183,30 +197,30 @@ function I(t) {
     getQuery: x
   };
 }
-function O(t) {
-  return L(t) ? S(t) : I(t);
+function U(t) {
+  return z(t) ? $(t) : W(t);
 }
-function M(t, e) {
-  for (let n = 0; n < e.length; n++)
-    if (e[n].match(t))
-      return e[n];
+function B(t, e) {
+  for (let o = 0; o < e.length; o++)
+    if (e[o].match(t))
+      return e[o];
   return null;
 }
-async function W(t, e) {
-  return typeof t.component == "function" ? t.component(e) : typeof t.loadComponent == "function" ? await t.loadComponent(e) : new Error("Failed to get component for route");
+async function H(t, e) {
+  return typeof t.component == "function" ? t.component(e) : typeof t.loadComponent == "function" ? await t.loadComponent(e) : new Error("Failed to get component for route: " + t.path);
 }
-async function B(t, e) {
-  const n = t.afterEnter;
-  if (!(!n || n.length === 0))
-    for (const o of n)
-      await o(e);
+async function I(t, e) {
+  const o = t.afterEnter;
+  if (!(!o || o.length === 0))
+    for (const n of o)
+      await n(e);
 }
-async function H(t, e) {
-  const n = t.beforeEnter;
-  if (!n || n.length === 0)
+async function O(t, e) {
+  const o = t.beforeEnter;
+  if (!o || o.length === 0)
     return null;
-  for (const o of n) {
-    const r = await o(e);
+  for (const n of o) {
+    const r = await n(e);
     if (r === !1 || typeof r == "string")
       return r;
   }
@@ -215,42 +229,32 @@ async function H(t, e) {
 function E(t) {
   return t instanceof DOMException && t.name === "AbortError";
 }
-class C extends HTMLElement {
-  constructor(e) {
-    super(), this.setAttribute("outlet-id", e.outletId);
-  }
-}
-customElements.define("router-outlet", C);
-async function m(t, e) {
-  if (e.aborted)
-    throw new DOMException("Aborted", "AbortError");
-  return new Promise((n, o) => {
-    const r = () => o(new DOMException("Aborted", "AbortError"));
-    e.addEventListener("abort", r), t().then(n).catch(o).finally(() => {
-      e.removeEventListener("abort", r);
-    });
-  });
-}
 function v(t) {
   const e = t.split("/").filter(Boolean);
   if (e.length === 0)
     return 0;
-  let n = 0;
-  for (let o = 0; o < e.length; o++) {
-    const r = e[o];
-    r === "*" ? n -= 100 : r.startsWith(":") ? n += 5 : n += 10;
+  let o = 0;
+  for (let n = 0; n < e.length; n++) {
+    const r = e[n];
+    r === "*" ? o -= 100 : r.startsWith(":") ? o += 5 : o += 10;
   }
-  return n += e.length * 0.1, n;
+  return o += e.length * 0.1, o;
 }
-function U(t) {
-  return t.toSorted((e, n) => v(n.path) - v(e.path));
+function D(t) {
+  return t.toSorted((e, o) => v(o.path) - v(e.path));
 }
-function D(t, e) {
+function Q(t, e) {
   if (t === null)
     return !1;
-  const n = new URL(t, location.origin), o = new URL(e, location.origin);
-  return !(n.pathname !== o.pathname || n.search !== o.search);
+  const o = new URL(t, location.origin), n = new URL(e, location.origin);
+  return !(o.pathname !== n.pathname || o.search !== n.search);
+}
+class C extends HTMLElement {
+  constructor(e) {
+    super(), this.setAttribute("outlet-id", e.outletId);
+  }
 }
+customElements.define("router-outlet", C);
 function R(t) {
   if (typeof t != "string")
     throw new Error(`Path must be a string, got ${typeof t}`);
@@ -271,16 +275,16 @@ function R(t) {
       `Path contains invalid characters: "${e.join("")}" in "${t}"`
     );
 }
-function Q(t) {
+function _(t) {
   const e = /* @__PURE__ */ new Set();
-  for (let n = 0; n < t.length; n++) {
-    const o = t[n].path;
-    if (e.has(o))
-      throw new Error(`Duplicate root route path: "${o}"`);
-    e.add(o);
+  for (let o = 0; o < t.length; o++) {
+    const n = t[o].path;
+    if (e.has(n))
+      throw new Error(`Duplicate root route path: "${n}"`);
+    e.add(n);
   }
 }
-function _(t) {
+function q(t) {
   if (!(t.redirectTo === null || t.redirectTo == null) && typeof t.redirectTo == "string") {
     const e = t.redirectTo;
     if (R(e), e === t.path)
@@ -289,74 +293,75 @@ function _(t) {
       throw new Error('Catch-all route "*" cannot have a redirect');
   }
 }
-function q(t) {
-  const e = typeof t.redirectTo == "string", n = typeof t.component == "function", o = typeof t.loadComponent == "function";
-  if (e && (n || o))
+function F(t) {
+  const e = typeof t.redirectTo == "string", o = typeof t.component == "function", n = typeof t.loadComponent == "function";
+  if (e && (o || n))
     throw new Error(
       `Redirect route "${t.path}" must not define components`
     );
-  if (n && o)
+  if (o && n)
     throw new Error(
       `Route "${t.path}" cannot have both component and loadComponent`
     );
-  if (!e && !n && !o)
+  if (!e && !o && !n)
     throw new Error(
       `Route "${t.path}" must define either "component" or "loadComponent"`
     );
 }
-function F(t) {
-  R(t.path), _(t), q(t);
-}
 function j(t) {
-  Q(t);
+  R(t.path), q(t), F(t);
+}
+function K(t) {
+  _(t);
   for (let e = 0; e < t.length; e++) {
-    const n = t[e];
-    F(n);
+    const o = t[e];
+    j(o);
   }
 }
-class K {
+class Z {
   routerController = new AbortController();
   initialized = !1;
   navigationController = null;
-  matchers = [];
+  routeMatchers = [];
   options;
-  rootOutletInternal = new C({ outletId: "root" });
+  outlet = new C({ outletId: "root" });
   currentPath = null;
-  constructor(e, n) {
-    j(e), this.options = {
+  constructor(e, o) {
+    K(e), this.options = {
       defaultTitle: document.title,
       sortRoutesBySpecificity: !0,
-      ...n
+      ignoreSameLocation: !0,
+      ...o
     };
-    const o = this.options.sortRoutesBySpecificity ? U(e) : e;
-    this.matchers = o.map(O);
+    const n = this.options.sortRoutesBySpecificity ? D(e) : e;
+    this.routeMatchers = n.map(U);
   }
   async initialize() {
     if (this.initialized)
       throw new Error("Router already initialized");
-    const e = async (o) => {
+    const e = async (n) => {
       const r = window.location.pathname + window.location.search;
-      await this.navigate(r, o.state, "none");
+      await this.navigate(r, n.state, "none");
     };
     window.addEventListener(
       "popstate",
-      (o) => {
-        e(o).catch(console.error);
+      (n) => {
+        e(n).catch(console.error);
       },
       { signal: this.routerController.signal }
     );
-    const n = window.location.pathname + window.location.search;
-    return await this.navigate(n, null, "none"), this.initialized = !0, this.rootOutletInternal;
+    const o = window.location.pathname + window.location.search;
+    return await this.navigate(o, null, "none"), this.initialized = !0, this.outlet;
   }
   destroy() {
     if (!this.initialized)
       throw new Error("Router not initialized");
     this.routerController.abort(), this.navigationController && (this.navigationController.abort(), this.navigationController = null), this.initialized = !1;
   }
-  async navigate(e, n, o, r = 0) {
+  async navigate(e, o, n, r = 0) {
     if (r > 5) {
       h(
-        this.rootOutletInternal,
+        this.outlet,
         new Error("Too many redirects"),
         null,
         null,
@@ -364,10 +369,10 @@ class K {
       );
       return;
     }
-    if (this.options.ignoreSameLocation && D(this.currentPath, e))
+    if (this.options.ignoreSameLocation && Q(this.currentPath, e))
       return;
     this.navigationController && (this.navigationController.abort("navigation canceled"), this.navigationController = null), this.navigationController = new AbortController();
-    const i = this.navigationController.signal, a = M(e, this.matchers), s = {
+    const i = this.navigationController.signal, a = B(e, this.routeMatchers), s = {
       from: this.currentPath,
       to: e,
       params: a?.getParams(e) ?? {},
@@ -376,8 +381,8 @@ class K {
     };
     try {
       if (!a) {
-        p(e, n, o), h(
-          this.rootOutletInternal,
+        m(e, o, n), h(
+          this.outlet,
           new Error('Route not found. Add "*" catch-all route'),
           null,
           s,
@@ -386,32 +391,32 @@ class K {
         return;
       }
       if (a.redirectTo) {
-        await this.navigate(a.redirectTo, n, "replace", r + 1);
+        await this.navigate(a.redirectTo, o, "replace", r + 1);
         return;
       }
       if (i.aborted)
         return;
-      const c = await m(
-        () => H(a.route, s),
+      const c = await p(
+        () => O(a.route, s),
         i
       );
       if (c === !1)
         return;
       if (typeof c == "string") {
-        await this.navigate(c, n, "replace", r + 1);
+        await this.navigate(c, o, "replace", r + 1);
         return;
       }
       if (i.aborted)
         return;
-      const d = await m(
-        () => W(a.route, s),
+      const d = await p(
+        () => H(a.route, s),
         i
       );
       if (d instanceof Error) {
         if (E(d))
           return;
-        p(e, n, o), h(
-          this.rootOutletInternal,
+        m(e, o, n), h(
+          this.outlet,
           d,
           a.route,
           s,
@@ -421,12 +426,12 @@ class K {
       }
       if (i.aborted)
         return;
-      T(this.rootOutletInternal, d), p(e, n, o), k(a.route, s, this.options.defaultTitle), this.currentPath = e, await m(() => B(a.route, s), i);
+      L(this.outlet, d), m(e, o, n), T(a.route, s, this.options.defaultTitle), this.currentPath = e, await p(() => I(a.route, s), i);
     } catch (c) {
       if (E(c))
         return;
       h(
-        this.rootOutletInternal,
+        this.outlet,
         c instanceof Error ? c : new Error("Unknown error"),
         a?.route ?? null,
         s,
@@ -436,25 +441,26 @@ class K {
       this.navigationController?.signal === i && (this.navigationController = null);
     }
   }
-  async push(e, n) {
+  async push(e, o) {
     try {
-      await this.navigate(e, n, "push");
-    } catch (o) {
-      console.error("[Router.push] Error:", o);
+      await this.navigate(e, o, "push");
+    } catch (n) {
+      console.error("[Router.push] Error:", n);
     }
   }
-  async replace(e, n) {
+  async replace(e, o) {
     try {
-      await this.navigate(e, n, "replace");
-    } catch (o) {
-      console.error("[Router.replace] Error:", o);
+      await this.navigate(e, o, "replace");
+    } catch (n) {
+      console.error("[Router.replace] Error:", n);
     }
   }
 }
-function G(t, e) {
-  return new K(t, e);
+function J(t, e) {
+  return new Z(t, e);
 }
 export {
-  K as Router,
-  G as createRouter
+  Z as Router,
+  J as createRouter,
+  p as withAbortSignal
 };

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "@ripetchor/r-router",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "type": "module",
+  "license": "MIT",
   "files": [
     "dist"
   ],