@tschk/moonshine-router 0.3.1

package/README.md

@@ -0,0 +1,22 @@
+# `@tschk/moonshine-router`
+
+Renderer-neutral route graph and matcher. Optional React navigation helpers.
+
+```ts
+import { createRouteGraph, matchRoutes } from "@tschk/moonshine-router";
+import {
+  MoonshineRouter,
+  Link,
+  useParams,
+  useNavigate,
+} from "@tschk/moonshine/router";
+```
+
+Features:
+
+- Pattern compiler with static, dynamic, optional, and rest segments.
+- Route graph with ambiguity detection.
+- Match precedence: `static > dynamic > optional > rest`.
+- `MoonshineRouter`, `Link`, `useParams`, `useNavigate`, `useLocation`.
+
+See [docs/ROUTING.md](../../docs/ROUTING.md).

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@tschk/moonshine-router",
+  "version": "0.3.1",
+  "description": "Renderer-neutral route graph and matcher with optional React navigation",
+  "license": "ISC",
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "format": "bunx prettier --check .",
+    "lint": "bunx oxlint .",
+    "typecheck": "bunx tsc --noEmit",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "@tschk/moonshine": "^0.3.1",
+    "@tschk/moonshine-framework": "^0.3.1"
+  },
+  "devDependencies": {
+    "@types/bun": "1.3.14",
+    "typescript": "7.0.2"
+  },
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  }
+}

package/src/graph.ts

@@ -0,0 +1,89 @@
+import { type RouteDefinition } from "@tschk/moonshine-framework";
+import { compilePattern, type CompiledPattern } from "./pattern.js";
+
+export type RouteGraph<T = RouteDefinition> = {
+  routes: CompiledRoute<T>[];
+};
+
+type CompiledRoute<T> = {
+  route: T;
+  compiled: CompiledPattern;
+};
+
+export function createRouteGraph<T extends RouteDefinition>(
+  routes: T[],
+): RouteGraph<T> {
+  const seen = new Map<string, { id: string; normalized: string }>();
+  const compiled: CompiledRoute<T>[] = [];
+
+  for (const route of routes) {
+    const compiledPattern = compilePattern(route.path);
+    const key = `${compiledPattern.normalized}|${compiledPattern.precedence.join(",")}`;
+    const existing = seen.get(key);
+    if (existing) {
+      throw new Error(
+        `Ambiguous routes "${existing.id}" and "${route.id}" both match ${existing.normalized}`,
+      );
+    }
+    seen.set(key, { id: route.id, normalized: compiledPattern.normalized });
+    compiled.push({ route, compiled: compiledPattern });
+  }
+
+  return { routes: compiled };
+}
+
+const MISSING = 4;
+
+function compareMatches(
+  a: { score: number[] },
+  b: { score: number[] },
+): number {
+  const max = Math.max(a.score.length, b.score.length);
+  for (let i = 0; i < max; i++) {
+    const av = i < a.score.length ? a.score[i] : MISSING;
+    const bv = i < b.score.length ? b.score[i] : MISSING;
+    if (av > bv) return -1;
+    if (av < bv) return 1;
+  }
+  return 0;
+}
+
+export type RouteMatch<T = RouteDefinition> = {
+  route: T;
+  path: string;
+  pattern: string;
+  params: Record<string, string>;
+};
+
+export function matchRoutes<T extends RouteDefinition>(
+  graph: RouteGraph<T>,
+  pathname: string,
+): RouteMatch<T> | null {
+  const matches: {
+    route: T;
+    pattern: string;
+    params: Record<string, string>;
+    score: number[];
+  }[] = [];
+
+  for (const { route, compiled } of graph.routes) {
+    const m = compiled.match(pathname);
+    if (!m) continue;
+    matches.push({
+      route,
+      pattern: compiled.pattern,
+      params: m.params,
+      score: m.score,
+    });
+  }
+
+  if (matches.length === 0) return null;
+  matches.sort(compareMatches);
+  const best = matches[0]!;
+  return {
+    route: best.route,
+    path: pathname,
+    pattern: best.pattern,
+    params: best.params,
+  };
+}

package/src/index.ts

@@ -0,0 +1,28 @@
+export { compilePattern, matchPath } from "./pattern.js";
+export type {
+  CompiledPattern,
+  MatchResult,
+  RouteParams,
+  Segment,
+  SegmentKind,
+} from "./pattern.js";
+
+export { createRouteGraph, matchRoutes } from "./graph.js";
+export type { RouteGraph, RouteMatch } from "./graph.js";
+
+export {
+  createMoonshineRouter,
+  navigate,
+  getLocation,
+  useLocation,
+  useParams,
+  useNavigate,
+  useRouter,
+  MoonshineRouter,
+  Link,
+} from "./navigation.js";
+export type {
+  MoonshineRouterInstance,
+  MoonshineRouterProps,
+  MoonshineRouteDefinition,
+} from "./navigation.js";

package/src/navigation.ts

@@ -0,0 +1,240 @@
+import { createSignal, type Signal } from "@tschk/moonshine";
+import {
+  createContext,
+  createElement,
+  useContext,
+  useEffect,
+  useRef,
+  useState,
+  useSyncExternalStore,
+  type ReactNode,
+} from "react";
+import { type RouteDefinition } from "@tschk/moonshine-framework";
+import { createRouteGraph, matchRoutes, type RouteMatch } from "./graph.js";
+
+export type RouteParams = Record<string, string>;
+
+function getBrowserPath(): string {
+  if (typeof window === "undefined") return "/";
+  return window.location.pathname || "/";
+}
+
+export type MoonshineRouterInstance = {
+  /** Navigate via History API (no full reload). */
+  navigate: (to: string, options?: { replace?: boolean }) => void;
+  /** Current pathname (reactive signal). */
+  getLocation: () => string;
+  /** Subscribe-friendly location signal. */
+  location: Signal<string>;
+  /** Sync signal from `window.location`. */
+  syncFromBrowser: () => void;
+};
+
+/** Create an isolated router runtime (no shared global path). */
+export function createMoonshineRouter(
+  initialPath = getBrowserPath(),
+): MoonshineRouterInstance {
+  const location = createSignal(initialPath);
+
+  const syncFromBrowser = () => {
+    location.set(getBrowserPath());
+  };
+
+  const navigate = (to: string, options?: { replace?: boolean }) => {
+    if (typeof window === "undefined") {
+      location.set(to);
+      return;
+    }
+    const url = new URL(to, window.location.origin);
+    if (options?.replace) {
+      window.history.replaceState({}, "", url.pathname + url.search + url.hash);
+    } else {
+      window.history.pushState({}, "", url.pathname + url.search + url.hash);
+    }
+    location.set(url.pathname);
+  };
+
+  return {
+    navigate,
+    getLocation: () => location(),
+    location,
+    syncFromBrowser,
+  };
+}
+
+/** Active mounted router for module-level navigate/getLocation. */
+let activeRouter: MoonshineRouterInstance | null = null;
+/** Fallback when nothing mounted (tests / early navigate). */
+const fallbackRouter = createMoonshineRouter();
+
+function currentRouter(): MoonshineRouterInstance {
+  return activeRouter ?? fallbackRouter;
+}
+
+/** Navigate via History API (targets active mounted router). */
+export function navigate(to: string, options?: { replace?: boolean }): void {
+  currentRouter().navigate(to, options);
+}
+
+/** Current pathname (reactive; active or fallback router). */
+export function getLocation(): string {
+  return currentRouter().getLocation();
+}
+
+export function useLocation(): string {
+  const ctx = useContext(RouterContext);
+  const source = ctx?.runtime.location ?? fallbackRouter.location;
+  return useSyncExternalStore(
+    source.subscribe,
+    () => source.peek(),
+    () => "/",
+  );
+}
+
+type RouterContextValue = {
+  match: RouteMatch<InternalRoute> | null;
+  params: RouteParams;
+  navigate: typeof navigate;
+  runtime: MoonshineRouterInstance;
+};
+
+const RouterContext = createContext<RouterContextValue | null>(null);
+
+export function useParams(): RouteParams {
+  return useContext(RouterContext)?.params ?? {};
+}
+
+export function useNavigate(): typeof navigate {
+  return useContext(RouterContext)?.navigate ?? navigate;
+}
+
+export function useRouter(): MoonshineRouterInstance {
+  return useContext(RouterContext)?.runtime ?? fallbackRouter;
+}
+
+export type MoonshineRouteDefinition = Partial<RouteDefinition> & {
+  path: string;
+  element: ReactNode;
+};
+
+type InternalRoute = RouteDefinition & { element: ReactNode };
+
+export type MoonshineRouterProps = {
+  routes: MoonshineRouteDefinition[];
+  /** Fallback when no route matches. */
+  fallback?: ReactNode;
+  /** Controlled path (defaults to browser location). */
+  path?: string;
+  /**
+   * Optional external runtime. When omitted, each mount owns an isolated
+   * instance (no cross-app global path bleed).
+   */
+  runtime?: MoonshineRouterInstance;
+};
+
+/**
+ * Minimal file-ish router: declarative routes with `:param` segments.
+ *
+ * ```tsx
+ * <MoonshineRouter
+ *   routes={[
+ *     { path: "/", element: <Home /> },
+ *     { path: "/users/:id", element: <User /> },
+ *   ]}
+ *   fallback={<NotFound />}
+ * />
+ * ```
+ */
+export function MoonshineRouter(props: MoonshineRouterProps): ReactNode {
+  const owned = useRef<MoonshineRouterInstance | null>(null);
+  if (!owned.current && !props.runtime) {
+    owned.current = createMoonshineRouter(props.path ?? getBrowserPath());
+  }
+  const runtime = props.runtime ?? owned.current!;
+
+  const browserPath = useSyncExternalStore(
+    runtime.location.subscribe,
+    () => runtime.location.peek(),
+    () => props.path ?? "/",
+  );
+  const pathname = props.path ?? browserPath;
+  const [ready, setReady] = useState(
+    typeof window === "undefined" || props.path !== undefined,
+  );
+
+  const graph = createRouteGraph<InternalRoute>(
+    props.routes.map((route) => ({
+      ...route,
+      id: route.id ?? route.path,
+      file: route.file ?? "",
+    })),
+  );
+
+  useEffect(() => {
+    const prev = activeRouter;
+    activeRouter = runtime;
+    if (props.path === undefined) {
+      runtime.syncFromBrowser();
+      setReady(true);
+      const onPop = () => runtime.syncFromBrowser();
+      window.addEventListener("popstate", onPop);
+      return () => {
+        window.removeEventListener("popstate", onPop);
+        activeRouter = prev;
+      };
+    }
+    return () => {
+      activeRouter = prev;
+    };
+  }, [runtime, props.path]);
+
+  const matched = matchRoutes<InternalRoute>(graph, pathname);
+  const value: RouterContextValue = {
+    match: matched,
+    params: matched?.params ?? {},
+    navigate: runtime.navigate,
+    runtime,
+  };
+
+  if (!ready && props.path === undefined && typeof window !== "undefined") {
+    // Avoid hydration flicker on first client paint before popstate sync
+  }
+
+  return createElement(
+    RouterContext.Provider,
+    { value },
+    matched?.route.element ?? props.fallback ?? null,
+  );
+}
+
+/** Anchor that uses client-side navigation. */
+export function Link(props: {
+  href: string;
+  children?: ReactNode;
+  className?: string;
+  replace?: boolean;
+}): ReactNode {
+  const nav = useNavigate();
+  return createElement(
+    "a",
+    {
+      href: props.href,
+      className: props.className,
+      onClick: (event: MouseEvent) => {
+        if (
+          event.defaultPrevented ||
+          event.button !== 0 ||
+          event.metaKey ||
+          event.altKey ||
+          event.ctrlKey ||
+          event.shiftKey
+        ) {
+          return;
+        }
+        event.preventDefault();
+        nav(props.href, { replace: props.replace });
+      },
+    },
+    props.children,
+  );
+}

package/src/pattern.ts

@@ -0,0 +1,148 @@
+export type RouteParams = Record<string, string>;
+
+export type SegmentKind = "static" | "dynamic" | "optional" | "rest";
+
+export const SEGMENT_PRECEDENCE: Record<SegmentKind, number> = {
+  static: 3,
+  dynamic: 2,
+  optional: 1,
+  rest: 0,
+};
+
+export type Segment = {
+  kind: SegmentKind;
+  name: string;
+  value: string;
+};
+
+export type MatchResult = {
+  params: RouteParams;
+  score: number[];
+};
+
+export type CompiledPattern = {
+  pattern: string;
+  segments: Segment[];
+  precedence: number[];
+  normalized: string;
+  match: (pathname: string) => MatchResult | null;
+};
+
+function splitPath(path: string): string[] {
+  return path
+    .replace(/\/+$/, "")
+    .replace(/^\/+/, "")
+    .split("/")
+    .filter(Boolean);
+}
+
+function decodePart(part: string): string | null {
+  try {
+    return decodeURIComponent(part);
+  } catch {
+    return null;
+  }
+}
+
+export function compilePattern(pattern: string): CompiledPattern {
+  const raw = pattern.replace(/\/+$/, "").replace(/^\/+/, "");
+  const parts = raw === "" ? [] : raw.split("/").filter(Boolean);
+  const segments: Segment[] = [];
+  const precedence: number[] = [];
+  let normalized = "";
+
+  for (const part of parts) {
+    if (part.startsWith("*")) {
+      const name = part.length > 1 ? part.slice(1) : "*";
+      segments.push({ kind: "rest", name, value: part });
+      precedence.push(SEGMENT_PRECEDENCE.rest);
+      normalized += "/*rest";
+    } else if (part.startsWith(":")) {
+      const optional = part.endsWith("?");
+      const name = optional ? part.slice(1, -1) : part.slice(1);
+      const kind: SegmentKind = optional ? "optional" : "dynamic";
+      segments.push({ kind, name, value: name });
+      precedence.push(SEGMENT_PRECEDENCE[kind]);
+      normalized += optional ? "/:param?" : "/:param";
+    } else {
+      segments.push({ kind: "static", name: part, value: part });
+      precedence.push(SEGMENT_PRECEDENCE.static);
+      normalized += "/" + part;
+    }
+  }
+
+  if (normalized === "") {
+    normalized = "/";
+  }
+
+  const match = (pathname: string): MatchResult | null => {
+    const pathParts = splitPath(pathname);
+    const params: RouteParams = {};
+    const score: number[] = [];
+    let i = 0;
+
+    for (const segment of segments) {
+      if (segment.kind === "rest") {
+        const remaining = pathParts.slice(i).join("/");
+        try {
+          params[segment.name] = decodeURIComponent(remaining);
+        } catch {
+          return null;
+        }
+        score.push(SEGMENT_PRECEDENCE.rest);
+        i = pathParts.length;
+        continue;
+      }
+
+      if (segment.kind === "static") {
+        const part = pathParts[i];
+        if (part === undefined) return null;
+        const decoded = decodePart(part);
+        if (decoded === null) return null;
+        if (decoded !== segment.value) return null;
+        score.push(SEGMENT_PRECEDENCE.static);
+        i++;
+        continue;
+      }
+
+      if (segment.kind === "dynamic") {
+        const part = pathParts[i];
+        if (part === undefined) return null;
+        const decoded = decodePart(part);
+        if (decoded === null) return null;
+        params[segment.name] = decoded;
+        score.push(SEGMENT_PRECEDENCE.dynamic);
+        i++;
+        continue;
+      }
+
+      if (segment.kind === "optional") {
+        const part = pathParts[i];
+        if (part === undefined) {
+          score.push(0);
+          continue;
+        }
+        const decoded = decodePart(part);
+        if (decoded === null) return null;
+        params[segment.name] = decoded;
+        score.push(SEGMENT_PRECEDENCE.optional);
+        i++;
+        continue;
+      }
+    }
+
+    if (i < pathParts.length) return null;
+    return { params, score };
+  };
+
+  return { pattern, segments, precedence, normalized, match };
+}
+
+export function matchPath(
+  pattern: string,
+  pathname: string,
+): { path: string; pattern: string; params: RouteParams } | null {
+  const result = compilePattern(pattern).match(pathname);
+  if (!result) return null;
+  return { path: pathname, pattern, params: result.params };
+}

package/test/graph.test.ts

@@ -0,0 +1,23 @@
+import { describe, expect, test } from "bun:test";
+import { createRouteGraph, matchRoutes } from "../src/graph";
+
+describe("createRouteGraph", () => {
+  test("static beats dynamic beats rest", () => {
+    const graph = createRouteGraph([
+      { id: "rest", path: "/blog/*rest", file: "rest.tsx" },
+      { id: "slug", path: "/blog/:slug", file: "slug.tsx" },
+      { id: "new", path: "/blog/new", file: "new.tsx" },
+    ]);
+    expect(matchRoutes(graph, "/blog/new")?.route.id).toBe("new");
+    expect(matchRoutes(graph, "/blog/post")?.params).toEqual({ slug: "post" });
+  });
+
+  test("throws for ambiguous routes", () => {
+    expect(() =>
+      createRouteGraph([
+        { id: "a", path: "/users/:param", file: "a.tsx" },
+        { id: "b", path: "/users/:id", file: "b.tsx" },
+      ]),
+    ).toThrow(/Ambiguous routes "a" and "b" both match \/users\/:param/);
+  });
+});

package/test/pattern.test.ts

@@ -0,0 +1,58 @@
+import { describe, expect, test } from "bun:test";
+import { compilePattern, matchPath } from "../src/pattern";
+
+describe("compilePattern", () => {
+  test("static matches exact", () => {
+    const p = compilePattern("/about");
+    expect(p.match("/about")?.params).toEqual({});
+    expect(p.match("/other")).toBeNull();
+  });
+
+  test("dynamic captures a parameter", () => {
+    const p = compilePattern("/users/:id");
+    const m = p.match("/users/42");
+    expect(m?.params).toEqual({ id: "42" });
+    expect(m?.score).toEqual([3, 2]);
+  });
+
+  test("optional segment may be omitted", () => {
+    const p = compilePattern("/:tab?");
+    expect(p.match("/")?.params).toEqual({});
+    expect(p.match("/profile")?.params).toEqual({ tab: "profile" });
+  });
+
+  test("rest captures the remainder", () => {
+    const p = compilePattern("/blog/*rest");
+    const m = p.match("/blog/a/b");
+    expect(m?.params).toEqual({ rest: "a/b" });
+    expect(m?.score).toEqual([3, 0]);
+  });
+
+  test("decodes parameter values", () => {
+    const p = compilePattern("/users/:id");
+    expect(p.match("/users/bob%20smith")?.params.id).toBe("bob smith");
+  });
+
+  test("malformed encoding returns no match", () => {
+    const p = compilePattern("/users/:id");
+    expect(p.match("/users/bob%ZZ")).toBeNull();
+  });
+
+  test("precedence reflects segment kind", () => {
+    const p = compilePattern("/blog/:slug?");
+    expect(p.precedence).toEqual([3, 1]);
+  });
+});
+
+describe("matchPath", () => {
+  test("returns a match object", () => {
+    const m = matchPath("/users/:id", "/users/7");
+    expect(m).not.toBeNull();
+    expect(m!.params.id).toBe("7");
+    expect(m!.pattern).toBe("/users/:id");
+  });
+
+  test("rejects length mismatch", () => {
+    expect(matchPath("/a/b", "/a")).toBeNull();
+  });
+});

package/tsconfig.json

@@ -0,0 +1,4 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "include": ["src/**/*", "test/**/*"]
+}