@rhi-zone/rainbow-router 0.0.1

package/dist/adapters/standard-schema.d.ts

@@ -0,0 +1,11 @@
+import type { StandardSchemaV1 } from '@standard-schema/spec';
+import type { ParamParser } from '../types.ts';
+/**
+ * Adapt a Standard Schema validator to a `ParamParser<T>`.
+ *
+ * Async schemas are not supported at the routing boundary: route matching must
+ * be synchronous so the router can produce a `MatchedRoute` in one pass.
+ * If `validate` returns a Promise we return `null` (no match) rather than
+ * attempting to await it.
+ */
+export declare const fromSchema: <T>(schema: StandardSchemaV1<string, T>) => ParamParser<T>;

package/dist/defaults.d.ts

@@ -0,0 +1,5 @@
+import type { RouterOptions, Router } from './router.ts';
+import type { RouteTree } from './types.ts';
+export declare const createRouter: (tree: RouteTree, options?: Omit<RouterOptions, 'scroll'> & {
+    scroll?: RouterOptions['scroll'];
+}) => Router;

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export type { ParamParser, ScrollHandler, ScrollNav, LoaderCtx, LoaderFn, RouteConfig, RouteTree, MatchedRoute, LoaderState } from './types.ts';
+export { match } from './matcher.ts';
+export type { RouterOptions, Router } from './router.ts';
+export { createRouter } from './router.ts';
+export type { Mountable, MountableFactory } from './mountable.ts';
+export { defineMountable } from './mountable.ts';

package/dist/index.js

@@ -0,0 +1,94 @@
+import { signal as v, notAsked as b, loading as k, success as L, failure as _ } from "@rhi-zone/rainbow";
+function g(l) {
+  return l == null ? {} : typeof l == "object" && !S(l) ? l : { component: l };
+}
+const j = /* @__PURE__ */ new Set(["component", "loader", "params", "scroll"]);
+function S(l) {
+  return l !== null && typeof l == "object" && Object.keys(l).some((e) => !j.has(e));
+}
+function E(l) {
+  return Object.keys(l).find((e) => e.startsWith("_"));
+}
+function K(l, e) {
+  const i = e.split("/").filter(Boolean), f = {}, c = [], s = l[""];
+  s !== void 0 && c.push(g(s));
+  let r = l;
+  for (let h = 0; h < i.length; h++) {
+    const w = i[h], p = h === i.length - 1;
+    let u = r[w];
+    if (u === void 0) {
+      const t = E(r);
+      if (t === void 0) return null;
+      const a = t.slice(1), n = r[t], o = n == null ? void 0 : n.params;
+      if (o && a in o) {
+        const d = o[a](w);
+        if (d === null) return null;
+        f[a] = d;
+      } else
+        f[a] = w;
+      u = n;
+    }
+    if (u == null) return null;
+    if (!S(u))
+      return p ? { layouts: c, leaf: g(u), params: f, pathname: e } : null;
+    if (r = u, !p) {
+      const t = r[""];
+      t !== void 0 && c.push(g(t));
+    }
+  }
+  const y = r[""];
+  return y === void 0 ? null : { layouts: c, leaf: g(y), params: f, pathname: e };
+}
+function R(l, e) {
+  const i = v(window.location.pathname), f = i.map((t) => K(l, t)), c = v(b);
+  let s = null, r = window.location.pathname;
+  const y = f.subscribe((t) => {
+    if (s == null || s.abort(), s = null, t === null || t.leaf.loader === void 0) {
+      c.set(b);
+      return;
+    }
+    const a = new AbortController();
+    s = a, c.set(k), t.leaf.loader({ params: t.params, signal: a.signal }).then(
+      (n) => {
+        a.signal.aborted || c.set(L(n));
+      },
+      (n) => {
+        a.signal.aborted || c.set(_(n));
+      }
+    );
+  }), h = (t) => {
+    var o;
+    const a = r, n = window.location.pathname;
+    r = n, i.set(n), (o = e == null ? void 0 : e.scroll) == null || o.call(e, {
+      type: "pop",
+      hash: window.location.hash.slice(1) || null,
+      from: a,
+      to: n
+    });
+  };
+  return window.addEventListener("popstate", h), {
+    current: f,
+    loaderState: c,
+    navigate: (t) => {
+      var m;
+      const a = new URL(t, location.href), n = a.pathname, o = a.hash.slice(1) || null, d = r;
+      r = n, history.pushState({ _type: "push" }, "", t), (m = e == null ? void 0 : e.scroll) == null || m.call(e, { type: "push", hash: o, from: d, to: n }), i.set(n);
+    },
+    replace: (t) => {
+      var m;
+      const a = new URL(t, location.href), n = a.pathname, o = a.hash.slice(1) || null, d = r;
+      r = n, history.replaceState({ _type: "replace" }, "", t), (m = e == null ? void 0 : e.scroll) == null || m.call(e, { type: "replace", hash: o, from: d, to: n }), i.set(n);
+    },
+    back: () => history.back(),
+    forward: () => history.forward(),
+    destroy: () => {
+      y(), window.removeEventListener("popstate", h), s == null || s.abort(), s = null;
+    }
+  };
+}
+const x = () => (l) => l;
+export {
+  R as createRouter,
+  x as defineMountable,
+  K as match
+};

package/dist/index.umd.cjs

@@ -0,0 +1 @@
+(function(u,c){typeof exports=="object"&&typeof module<"u"?c(exports,require("@rhi-zone/rainbow")):typeof define=="function"&&define.amd?define(["exports","@rhi-zone/rainbow"],c):(u=typeof globalThis<"u"?globalThis:u||self,c(u.RainbowRouter={},u.rainbow))})(this,(function(u,c){"use strict";function g(l){return l==null?{}:typeof l=="object"&&!S(l)?l:{component:l}}const k=new Set(["component","loader","params","scroll"]);function S(l){return l!==null&&typeof l=="object"&&Object.keys(l).some(e=>!k.has(e))}function R(l){return Object.keys(l).find(e=>e.startsWith("_"))}function j(l,e){const f=e.split("/").filter(Boolean),h={},i=[],r=l[""];r!==void 0&&i.push(g(r));let a=l;for(let m=0;m<f.length;m++){const w=f[m],b=m===f.length-1;let d=a[w];if(d===void 0){const t=R(a);if(t===void 0)return null;const s=t.slice(1),n=a[t],o=n==null?void 0:n.params;if(o&&s in o){const y=o[s](w);if(y===null)return null;h[s]=y}else h[s]=w;d=n}if(d==null)return null;if(!S(d))return b?{layouts:i,leaf:g(d),params:h,pathname:e}:null;if(a=d,!b){const t=a[""];t!==void 0&&i.push(g(t))}}const v=a[""];return v===void 0?null:{layouts:i,leaf:g(v),params:h,pathname:e}}function L(l,e){const f=c.signal(window.location.pathname),h=f.map(t=>j(l,t)),i=c.signal(c.notAsked);let r=null,a=window.location.pathname;const v=h.subscribe(t=>{if(r==null||r.abort(),r=null,t===null||t.leaf.loader===void 0){i.set(c.notAsked);return}const s=new AbortController;r=s,i.set(c.loading),t.leaf.loader({params:t.params,signal:s.signal}).then(n=>{s.signal.aborted||i.set(c.success(n))},n=>{s.signal.aborted||i.set(c.failure(n))})}),m=t=>{var o;const s=a,n=window.location.pathname;a=n,f.set(n),(o=e==null?void 0:e.scroll)==null||o.call(e,{type:"pop",hash:window.location.hash.slice(1)||null,from:s,to:n})};return window.addEventListener("popstate",m),{current:h,loaderState:i,navigate:t=>{var p;const s=new URL(t,location.href),n=s.pathname,o=s.hash.slice(1)||null,y=a;a=n,history.pushState({_type:"push"},"",t),(p=e==null?void 0:e.scroll)==null||p.call(e,{type:"push",hash:o,from:y,to:n}),f.set(n)},replace:t=>{var p;const s=new URL(t,location.href),n=s.pathname,o=s.hash.slice(1)||null,y=a;a=n,history.replaceState({_type:"replace"},"",t),(p=e==null?void 0:e.scroll)==null||p.call(e,{type:"replace",hash:o,from:y,to:n}),f.set(n)},back:()=>history.back(),forward:()=>history.forward(),destroy:()=>{v(),window.removeEventListener("popstate",m),r==null||r.abort(),r=null}}}const _=()=>l=>l;u.createRouter=L,u.defineMountable=_,u.match=j,Object.defineProperty(u,Symbol.toStringTag,{value:"Module"})}));

package/dist/matcher.d.ts

@@ -0,0 +1,13 @@
+import type { RouteTree, MatchedRoute } from './types.ts';
+/**
+ * Match a pathname against a route tree.
+ *
+ * Algorithm (mirrors the Lua trie router):
+ * 1. Split pathname into segments
+ * 2. Walk the tree segment-by-segment
+ * 3. At each node: try exact key first, then `_name` dynamic key
+ * 4. Run ParamParser for dynamic segment — null return = no match → 404
+ * 5. Collect `''` handlers at intermediate nodes as layout layers
+ * 6. At final segment: `''` key is the leaf handler
+ */
+export declare function match(tree: RouteTree, pathname: string): MatchedRoute | null;

package/dist/matcher.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/mountable.d.ts

@@ -0,0 +1,6 @@
+import type { RouteTree } from './types.ts';
+export type Mountable<Context extends Record<string, string>> = RouteTree & {
+    readonly '~context': Context;
+};
+export type MountableFactory<Context extends Record<string, string>> = <Tree extends RouteTree>(tree: Tree) => Tree & Mountable<Context>;
+export declare const defineMountable: <Context extends Record<string, string>>() => MountableFactory<Context>;

package/dist/router.d.ts

@@ -0,0 +1,15 @@
+import type { ReadonlySignal, AsyncData } from '@rhi-zone/rainbow';
+import type { RouteTree, MatchedRoute, ScrollHandler } from './types.ts';
+export type RouterOptions = {
+    scroll?: ScrollHandler;
+};
+export type Router = {
+    readonly current: ReadonlySignal<MatchedRoute | null>;
+    readonly loaderState: ReadonlySignal<AsyncData<unknown>>;
+    navigate(pathname: string): void;
+    replace(pathname: string): void;
+    back(): void;
+    forward(): void;
+    destroy(): void;
+};
+export declare function createRouter(tree: RouteTree, options?: RouterOptions): Router;

package/dist/scroll.d.ts

@@ -0,0 +1,5 @@
+import type { ScrollHandler } from './types.ts';
+export declare const scrollTop: ScrollHandler;
+export declare const scrollNone: ScrollHandler;
+export declare const scrollToHash: ScrollHandler;
+export declare const scrollRestore: ScrollHandler;

package/dist/types.d.ts

@@ -0,0 +1,44 @@
+import type { AsyncData } from '@rhi-zone/rainbow';
+/** The router's only contract for param validation. null = no match → 404. */
+export type ParamParser<T> = (raw: string) => T | null;
+export type ScrollNav = {
+    readonly type: 'push' | 'pop' | 'replace';
+    readonly hash: string | null;
+    readonly from: string;
+    readonly to: string;
+};
+export type ScrollHandler = (nav: ScrollNav) => void;
+export type LoaderCtx<P extends Record<string, unknown> = Record<string, string>> = {
+    readonly params: P;
+    readonly signal: AbortSignal;
+};
+export type LoaderFn<P extends Record<string, unknown> = Record<string, string>, T = unknown> = (ctx: LoaderCtx<P>) => Promise<T>;
+/**
+ * A route node config — metadata attached to a path depth.
+ * Component type is `unknown` to stay framework-agnostic;
+ * the Lit/React/etc. adapters provide typed wrappers.
+ */
+export type RouteConfig = {
+    readonly component?: unknown;
+    readonly loader?: LoaderFn;
+    readonly params?: Record<string, ParamParser<unknown>>;
+    readonly scroll?: ScrollHandler;
+};
+/**
+ * A route tree node — either a shorthand component, a config, or a subtree.
+ * The `''` key at any subtree node is the handler at that exact depth.
+ */
+export type RouteTree = {
+    readonly [segment: string]: RouteTree | RouteConfig | unknown;
+};
+export type MatchedRoute = {
+    /** Layout stack from outermost to innermost, excluding leaf. */
+    readonly layouts: RouteConfig[];
+    /** The innermost matched config. */
+    readonly leaf: RouteConfig;
+    /** Validated and parsed params accumulated from all dynamic segments. */
+    readonly params: Record<string, unknown>;
+    /** The full matched pathname. */
+    readonly pathname: string;
+};
+export type LoaderState<T = unknown> = AsyncData<T, unknown>;

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@rhi-zone/rainbow-router",
+  "version": "0.0.1",
+  "description": "Trie-based SPA router for rainbow",
+  "type": "module",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./scroll": {
+      "import": "./dist/scroll.js",
+      "types": "./dist/scroll.d.ts"
+    },
+    "./defaults": {
+      "import": "./dist/defaults.js",
+      "types": "./dist/defaults.d.ts"
+    },
+    "./adapters/standard-schema": {
+      "import": "./dist/adapters/standard-schema.js",
+      "types": "./dist/adapters/standard-schema.d.ts"
+    }
+  },
+  "files": ["dist"],
+  "scripts": {
+    "dev": "vite build --watch",
+    "build": "vite build && tsgo --emitDeclarationOnly",
+    "typecheck": "tsgo --noEmit",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@rhi-zone/rainbow": "0.1.0"
+  },
+  "devDependencies": {
+    "@standard-schema/spec": "^1.0.0",
+    "vite": "^6.0.0",
+    "vitest": "^2.0.0"
+  }
+}