@miurajs/miura-router 0.0.0

package/README.md

@@ -0,0 +1,237 @@
+# `@miura/miura-router`
+
+Modern, declarative routing for miura applications. Built for Web Components, the router handles hash/history/memory navigation modes, async guards, data loaders, redirects, and DOM rendering hooks.
+
+## ✨ Features
+
+- **Multiple navigation modes**: `hash`, `history`, or in-memory for tests.
+- **Guards & loaders**: resolve access/gate data before components render.
+- **Nested routes & redirects**: declarative tree definitions.
+- **Type-safe route params**: `defineRoute<TParams>()` with typed `buildPath()` and `navigate()`.
+- **Runtime param validation**: optional Zod / Valibot / ArkType schema on any route.
+- **Event-driven**: emits lifecycle events through the framework EventBus.
+- **Performance hooks**: timing integration via `PerformanceMonitor`.
+
+## 🚦 Quick Start
+
+```ts
+import { createRouter } from '@miura/miura-router';
+
+const router = createRouter({
+  mode: 'history',
+  base: '/',
+  fallback: '/login',
+  routes: [
+    { path: '/', component: 'app-home' },
+    {
+      path: '/admin',
+      component: 'app-admin',
+      renderZone: '#primary',
+      guards: [async ({ data }) => (data.user?.isAdmin ? true : '/login')],
+      loaders: [async () => ({ stats: await fetchStats() })],
+    },
+  ],
+  render: (context) => mountIntoDom(context),
+  eventBus,
+  performance,
+});
+
+await router.start();
+```
+
+## 🛡️ Route Guards
+
+Guards run before loaders/rendering. They may:
+- return `true`/`void` to continue
+- return `false` to block (`router:blocked` event)
+- return a string path (sync/async) to redirect
+
+```ts
+const routes = [
+  {
+    path: '/dashboard',
+    component: 'app-dashboard',
+    guards: [async ({ data }) => (data.session ? true : '/login')],
+  },
+];
+```
+
+## 📦 Route Loaders
+
+Loaders run after guards and before rendering. Each loader can return any object; objects are shallow-merged in order.
+
+```ts
+const routes = [
+  {
+    path: '/profile/:id',
+    component: 'app-profile',
+    loaders: [
+      ({ params }) => ({ profile: fetchProfile(params.id) }),
+      async ({ params }) => ({ permissions: await fetchPermissions(params.id) }),
+    ],
+  },
+];
+```
+
+Access loader results inside the render callback (or components via `routeContext`) through `context.data`.
+
+## 🗂️ Nested Routes & Layout Outlets
+
+Define a `children` array on any route to create a parent/child hierarchy. The parent route acts as a layout shell; the matched child fills the `<router-outlet>` inside it.
+
+```ts
+const routes = [
+  {
+    path: '/app',
+    component: 'app-layout',      // renders the shell + <router-outlet>
+    children: [
+      { path: 'dashboard', component: 'app-dashboard' },
+      { path: 'settings',  component: 'app-settings'  },
+      { path: 'profile/:id', component: 'app-profile' },
+    ],
+  },
+];
+```
+
+```typescript
+// app-layout component
+template() {
+  return html`
+    <nav>...</nav>
+    <main>
+      <router-outlet></router-outlet>   <!-- child component mounts here -->
+    </main>
+  `;
+}
+```
+
+`context.matched` contains the full chain from root to leaf, so nested outlets at any depth receive the correct slice of the matched array.
+
+## 🔗 `<router-outlet>`
+
+The `<router-outlet>` custom element is a passive mount-point. The router's render callback uses `context.matched` to determine which components to mount at each level.
+
+```typescript
+import { RouterOutlet } from '@miura/miura-router';
+// RouterOutlet registers itself as <router-outlet> when imported
+```
+
+## � Redirects
+
+```ts
+{ path: '/old-path', redirect: '/new-path' }
+{ path: '/dynamic', redirect: (ctx) => `/target/${ctx.params.id}` }
+```
+
+## �📢 Router Events
+
+| Event | When |
+|-------|------|
+| `router:setup` | Router initialised |
+| `router:navigating` | Navigation started |
+| `router:navigated` | Navigation committed |
+| `router:blocked` | Guard returned `false` |
+| `router:not-found` | No matching route |
+| `router:error` | Unhandled navigation error |
+| `router:rendered` | Render callback completed |
+
+## 🛠️ Router API
+
+| Method | Description |
+|--------|-------------|
+| `router.navigate(path, opts?)` | Push a new entry and navigate |
+| `router.replace(path, opts?)` | Replace current entry and navigate |
+| `router.back()` | Go back in history |
+| `router.forward()` | Go forward in history |
+| `router.current` | Current `RouteContext` |
+| `router.previous` | Previous `RouteContext` |
+| `router.start()` | Start listening to navigation events |
+| `router.stop()` | Stop listening (keeps state) |
+| `router.destroy()` | Full teardown |
+
+`navigate()` and `replace()` both return `Promise<NavigationResult>`:
+
+```ts
+const result = await router.navigate('/dashboard');
+if (!result.ok) console.log('blocked:', result.reason);
+```
+
+## 🔷 Type-Safe Route Params
+
+Use `defineRoute<TParams>()` to get typed `buildPath()` and `navigate()` helpers with compile-time safety on route params.
+
+```ts
+import { defineRoute, createRouter } from '@miura/miura-router';
+
+// No params
+const homeRoute  = defineRoute({ path: '/', component: 'app-home' });
+
+// Single param — TypeScript enforces { id: string }
+const userRoute  = defineRoute<{ id: string }>({
+  path: '/users/:id',
+  component: 'user-page',
+});
+
+// Multiple params
+const postRoute  = defineRoute<{ userId: string; postId: string }>({
+  path: '/users/:userId/posts/:postId',
+  component: 'post-page',
+});
+
+// Pass records to createRouter
+const router = createRouter({
+  mode: 'history',
+  routes: [homeRoute.record, userRoute.record, postRoute.record],
+  render: (ctx) => mountComponent(ctx),
+});
+
+// Typed navigation — TS error if a param is missing or wrong type
+await userRoute.navigate(router, { id: '42' });
+await postRoute.navigate(router, { userId: '1', postId: '99' });
+
+// Build path without navigating
+userRoute.buildPath({ id: '42' });      // → '/users/42'
+postRoute.buildPath({ userId: '1', postId: '99' }); // → '/users/1/posts/99'
+```
+
+### Runtime validation with Zod
+
+Pass any Zod-compatible schema as a second argument. Params are validated (and coerced) after every match, before guards run.
+
+```ts
+import { z } from 'zod';
+
+const UserParams = z.object({ id: z.string().regex(/^\d+$/) });
+
+const userRoute = defineRoute(
+  { path: '/users/:id', component: 'user-page' },
+  UserParams, // ← schema
+);
+
+// Navigation to /users/abc → NavigationResult { ok: false, reason: 'error' }
+// Navigation to /users/42  → proceeds normally, ctx.params.id is '42'
+```
+
+The `ParamsSchema` interface is minimal — anything with `safeParse()` works (Zod, Valibot, ArkType, custom).
+
+## 🧪 Testing
+
+Use `mode: 'memory'` to avoid touching the real browser location. Provide a spy render callback to inspect contexts:
+
+```ts
+const renders: RouteRenderContext[] = [];
+const router = createRouter({
+  mode: 'memory',
+  routes,
+  render: (ctx) => { renders.push(ctx); },
+});
+await router.start();
+await router.navigate('/dashboard');
+assert.equal(renders.at(-1)?.route.component, 'app-dashboard');
+```
+
+The repository contains `test/router.guards-loaders.test.ts` covering redirects, blocks, and loader merges.
+
+## 📚 Framework Integration
+
+`miuraFramework` wires this router automatically. Define a static `router` config in your framework subclass, and the framework handles instantiation, DOM zones, and navigation helpers (`navigate`, `replaceRoute`, `goBack`, `goForward`).

package/index.ts

@@ -0,0 +1,5 @@
+export { MiuraRouter, createRouter } from './src/router.js';
+export { RouterOutlet } from './src/router-outlet.js';
+export { defineRoute, buildPath } from './src/route-builder.js';
+export type { TypedRoute, NavigableRouter } from './src/route-builder.js';
+export * from './src/types.js';

package/package.json

@@ -0,0 +1,23 @@
+{
+    "name": "@miurajs/miura-router",
+    "version": "0.0.0",
+    "type": "module",
+    "main": "./dist/index.js",
+    "module": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "import": "./index.ts"
+        }
+    },
+    "scripts": {
+        "build": "tsc"
+    },
+    "dependencies": {
+        "@miura/miura-debugger": "workspace:*"
+    },
+    "devDependencies": {
+        "typescript": "^5.4.5"
+    }
+}

package/src/route-builder.ts

@@ -0,0 +1,114 @@
+import type {
+    RouteRecord,
+    NavigationOptions,
+    NavigationResult,
+    ParamsSchema,
+} from './types.js';
+
+// ── Typed route builder ────────────────────────────────────────────────────────
+
+/**
+ * Minimal router interface required by `TypedRoute.navigate()`.
+ * `MiuraRouter` satisfies this; any compatible router will too.
+ */
+export interface NavigableRouter {
+    navigate(path: string, options?: NavigationOptions): Promise<NavigationResult>;
+}
+
+/**
+ * A typed route definition.  Created by `defineRoute<TParams>()`.
+ *
+ * Pass `record` to the `routes` array of `createRouter`, then use
+ * `buildPath()` / `navigate()` elsewhere for fully-typed navigation.
+ */
+export interface TypedRoute<TParams extends Record<string, string> = Record<string, string>> {
+    /** Raw RouteRecord — add this to `createRouter({ routes })`. */
+    readonly record: RouteRecord<TParams>;
+
+    /**
+     * Substitute `:param` segments in the route path with the supplied values.
+     *
+     * ```ts
+     * userRoute.buildPath({ id: '42' }) // → '/users/42'
+     * ```
+     * @throws if a required segment is missing from `params`.
+     */
+    buildPath(params: TParams): string;
+
+    /**
+     * Navigate the router to this route, substituting params into the path.
+     *
+     * ```ts
+     * await userRoute.navigate(router, { id: '42' });
+     * ```
+     */
+    navigate(router: NavigableRouter, params: TParams, options?: NavigationOptions): Promise<NavigationResult>;
+}
+
+/**
+ * Define a type-safe route.
+ *
+ * @param config  - Standard RouteRecord fields (without `paramsSchema`).
+ * @param schema  - Optional Zod-compatible schema for runtime param validation.
+ *
+ * ```ts
+ * // No runtime validation
+ * export const userRoute = defineRoute<{ id: string }>({
+ *   path: '/users/:id',
+ *   component: 'user-page',
+ * });
+ *
+ * // With Zod schema
+ * import { z } from 'zod';
+ * const UserParams = z.object({ id: z.string().regex(/^\d+$/) });
+ * export const userRoute = defineRoute({ path: '/users/:id', component: 'user-page' }, UserParams);
+ *
+ * // Usage
+ * createRouter({ routes: [userRoute.record, ...] });
+ * await userRoute.navigate(router, { id: '42' });
+ * userRoute.buildPath({ id: '42' }); // → '/users/42'
+ * ```
+ */
+export function defineRoute<TParams extends Record<string, string> = Record<string, string>>(
+    config: Omit<RouteRecord<TParams>, 'paramsSchema'>,
+    schema?: ParamsSchema<TParams>,
+): TypedRoute<TParams> {
+    const record: RouteRecord<TParams> = schema
+        ? { ...(config as RouteRecord<TParams>), paramsSchema: schema }
+        : (config as RouteRecord<TParams>);
+
+    return {
+        record,
+
+        buildPath(params: TParams): string {
+            return _interpolate(record.path, params);
+        },
+
+        navigate(router: NavigableRouter, params: TParams, options?: NavigationOptions): Promise<NavigationResult> {
+            return router.navigate(_interpolate(record.path, params), options);
+        },
+    };
+}
+
+// ── Utility — also exported for standalone use ─────────────────────────────────
+
+/**
+ * Substitute `:param` segments in a path pattern with values from `params`.
+ *
+ * ```ts
+ * buildPath('/users/:id/posts/:postId', { id: '1', postId: '99' })
+ * // → '/users/1/posts/99'
+ * ```
+ */
+export function buildPath(pattern: string, params: Record<string, string>): string {
+    return _interpolate(pattern, params);
+}
+
+function _interpolate(pattern: string, params: Record<string, string>): string {
+    return pattern.replace(/:(\w+)/g, (_, key) => {
+        if (!(key in params)) {
+            throw new Error(`[miura-router] Missing required param "${key}" for path "${pattern}"`);
+        }
+        return encodeURIComponent(params[key]);
+    });
+}

package/src/router-outlet.ts

@@ -0,0 +1,87 @@
+import type { RouteContext, RouteRecord } from './types.js';
+
+/**
+ * RouterOutlet — `<miura-router-outlet>`
+ *
+ * Drop this element into any layout component's template to mark where child
+ * routes should render. The router identifies outlets by their `name` attribute
+ * (default: "default") and injects child route components into them.
+ *
+ * Usage:
+ *   ```html
+ *   <!-- In a layout component template -->
+ *   <nav>...</nav>
+ *   <miura-router-outlet></miura-router-outlet>
+ *   ```
+ *
+ *   ```html
+ *   <!-- Named outlet -->
+ *   <miura-router-outlet name="sidebar"></miura-router-outlet>
+ *   ```
+ *
+ * Routes define which outlet they target via `renderZone`:
+ *   ```ts
+ *   { path: '/users/:id', component: 'user-detail', renderZone: 'sidebar' }
+ *   ```
+ */
+export class RouterOutlet extends HTMLElement {
+    private _current: HTMLElement | null = null;
+
+    static get observedAttributes() {
+        return ['name'];
+    }
+
+    get outletName(): string {
+        return this.getAttribute('name') || 'default';
+    }
+
+    connectedCallback(): void {
+        if (!this.hasAttribute('role')) {
+            this.setAttribute('role', 'region');
+        }
+    }
+
+    /**
+     * Render a route component into this outlet.
+     * Called by MiuraRouter when the matched route targets this outlet.
+     */
+    renderRoute(record: RouteRecord, context: RouteContext): void {
+        this._clearCurrent();
+
+        const element = document.createElement(record.component);
+        this._injectContext(element, context);
+        this.appendChild(element);
+        this._current = element as HTMLElement;
+    }
+
+    /**
+     * Clear whatever is currently rendered in this outlet.
+     */
+    clear(): void {
+        this._clearCurrent();
+    }
+
+    private _clearCurrent(): void {
+        if (this._current) {
+            this._current.remove();
+            this._current = null;
+        }
+    }
+
+    private _injectContext(element: Element, context: RouteContext): void {
+        if ('routeContext' in element) {
+            (element as any).routeContext = context;
+            return;
+        }
+        element.setAttribute('data-route', JSON.stringify({
+            params: context.params,
+            query: Object.fromEntries(context.query.entries()),
+            hash: context.hash,
+        }));
+    }
+}
+
+/** Register the element if not already registered */
+if (!customElements.get('miura-router-outlet')) {
+    customElements.define('miura-router-outlet', RouterOutlet);
+}