@madojs/mado 0.5.0

package/dist/src/router/manifest.js

@@ -0,0 +1,302 @@
+/**
+ * routes() — high-level manifest router with lazy loading, layouts,
+ * prefetch and a sync-fast-path for already-loaded pages.
+ *
+ * On top of the raw router() from navigation.ts this adds:
+ *   - dynamic-import loaders (code splitting via `() => import(...)`),
+ *   - nested routes with layouts (via page.ts: nested({ layout, routes })),
+ *   - per-instance module cache (not global — two routes() calls
+ *     in the same process do NOT interfere),
+ *   - hover prefetch and programmatic prefetchPath(),
+ *   - smart loadingDelay (no progress-bar flicker on fast networks),
+ *   - sync-fast-path: if the page is already in cache — renders synchronously,
+ *     without loading state and without a microtask. Removes flicker on back/forward.
+ */
+import { signal } from "../signal.js";
+import { html } from "../html/template.js";
+import { applyHead } from "../head.js";
+import { flatten, patternToRegex, } from "./match.js";
+import { router } from "./navigation.js";
+/**
+ * Registry of active RoutesContexts. Used by the global
+ * prefetchPath() — iterates over all active instances. On router.dispose()
+ * the corresponding context is removed from the registry.
+ */
+const activeRoutes = new Set();
+/**
+ * Create a router from a manifest. Returns the same RouterApi as router().
+ */
+export function routes(manifest, options = {}) {
+    const ctx = {
+        moduleCache: new Map(),
+        pathToFlat: new Map(),
+        compiledForPrefetch: [],
+        renderSeq: 0,
+    };
+    activeRoutes.add(ctx);
+    const flat = flatten(manifest);
+    const lowLevel = {};
+    for (const [pattern, entry] of flat) {
+        lowLevel[pattern] = (params) => renderEntry(ctx, entry, params, options, ++ctx.renderSeq);
+        ctx.pathToFlat.set(pattern, entry);
+        if (pattern !== "*") {
+            ctx.compiledForPrefetch.push({ regex: patternToRegex(pattern), entry });
+        }
+    }
+    const api = router(lowLevel, {
+        viewTransitions: options.viewTransitions,
+        // Raise prefetch into sub-router: hover on a link → find matching FlatEntry → load loader + layouts.
+        prefetch: (pathname) => prefetchPathInContext(ctx, pathname),
+    });
+    const origDispose = api.dispose;
+    api.dispose = () => {
+        activeRoutes.delete(ctx);
+        origDispose();
+    };
+    return api;
+}
+// ---------- prefetch ----------
+/**
+ * Prefetch-load modules for a path (hover, programmatic).
+ * Safe to call repeatedly — cached.
+ *
+ * Iterates all active routes() and starts loaders for matched entries.
+ * If there is no active routes() — no-op.
+ */
+export function prefetchPath(pathname) {
+    for (const ctx of activeRoutes) {
+        prefetchPathInContext(ctx, pathname);
+    }
+}
+function prefetchPathInContext(ctx, pathname) {
+    const exact = ctx.pathToFlat.get(pathname);
+    const entry = exact ?? ctx.compiledForPrefetch.find((c) => c.regex.test(pathname))?.entry;
+    if (!entry)
+        return;
+    loadPage(ctx, entry.loader).catch(() => { });
+    for (const lt of entry.layouts)
+        loadPage(ctx, lt).catch(() => { });
+}
+// ---------- Loading ----------
+async function loadPage(ctx, loader) {
+    const cached = ctx.moduleCache.get(loader);
+    if (cached)
+        return cached;
+    const p = await loader();
+    ctx.moduleCache.set(loader, p);
+    return p;
+}
+/**
+ * Synchronous cache check. If all modules (page + layouts)
+ * are already loaded — returns them without a Promise. This allows
+ * renderEntry to render the page without loading state and without a microtask.
+ */
+function tryLoadSync(ctx, entry) {
+    const page = ctx.moduleCache.get(entry.loader);
+    if (!page)
+        return undefined;
+    const layouts = [];
+    for (const l of entry.layouts) {
+        const lp = ctx.moduleCache.get(l);
+        if (!lp)
+            return undefined;
+        layouts.push(lp);
+    }
+    return { page, layouts };
+}
+// ---------- Render ----------
+/**
+ * Apply the page's title/head. Extracted from renderEntry so it
+ * can be called from both the async and sync branch.
+ */
+function applyPageMeta(page, params, options) {
+    const title = typeof page.title === "function" ? page.title(params) : page.title;
+    if (title) {
+        document.title = title + (options.titleSuffix ?? "");
+    }
+    if (page.head) {
+        try {
+            const baked = readBaked();
+            applyHead(page.head(params, baked));
+        }
+        catch (err) {
+            // eslint-disable-next-line no-console
+            console.error("[mado] page.head() threw:", err);
+        }
+    }
+}
+/**
+ * SYNC FAST PATH: if the page is already in moduleCache, we render it
+ * right now, without loading state and without a microtask. This removes
+ * blank/progress flicker on repeat navigations.
+ *
+ * ASYNC PATH: on a cold navigation the module still needs to be loaded.
+ * To avoid flickering with a loading view on fast networks, we use
+ * `loadingDelay` (default 100ms): if loading finishes within that time
+ * — render the ready page immediately; otherwise show loading.
+ */
+function renderEntry(ctx, entry, params, options, seq) {
+    // ---------- SYNC FAST PATH ----------
+    const sync = tryLoadSync(ctx, entry);
+    if (sync) {
+        applyPageMeta(sync.page, params, options);
+        try {
+            return renderWithLayouts(sync.page, sync.layouts, params);
+        }
+        catch (err) {
+            const e = err instanceof Error ? err : new Error(String(err));
+            if (sync.page.errorView)
+                return sync.page.errorView(e, params);
+            return options.error?.(e) ?? html `<pre>${e.message}</pre>`;
+        }
+    }
+    // ---------- ASYNC PATH ----------
+    // 'idle' — first window (until loadingDelay): render empty to avoid
+    // progress-bar flicker on fast connections.
+    // 'loading' — module didn't arrive in time → show loading.
+    // 'ready' / 'error' — final states.
+    const state = signal({ kind: "idle" });
+    let resolved = false;
+    const delay = options.loadingDelay ?? 100;
+    const timer = delay > 0
+        ? setTimeout(() => {
+            if (!resolved && !isStale(ctx, seq))
+                state.set({ kind: "loading" });
+        }, delay)
+        : null;
+    // delay = 0 means show loading immediately.
+    if (delay === 0 && !isStale(ctx, seq))
+        state.set({ kind: "loading" });
+    Promise.all([
+        loadPage(ctx, entry.loader),
+        ...entry.layouts.map((l) => loadPage(ctx, l)),
+    ]).then(([pg, ...lts]) => {
+        resolved = true;
+        if (timer)
+            clearTimeout(timer);
+        if (isStale(ctx, seq))
+            return;
+        applyPageMeta(pg, params, options);
+        state.set({ kind: "ready", page: pg, layouts: lts });
+    }, (err) => {
+        resolved = true;
+        if (timer)
+            clearTimeout(timer);
+        if (isStale(ctx, seq))
+            return;
+        const e = err instanceof Error ? err : new Error(String(err));
+        state.set({ kind: "error", err: e });
+    });
+    return html `${() => {
+        const s = state();
+        if (s.kind === "idle")
+            return "";
+        if (s.kind === "loading") {
+            return options.loading?.() ?? defaultLoadingView();
+        }
+        if (s.kind === "error") {
+            return options.error?.(s.err) ?? html `<pre>${s.err.message}</pre>`;
+        }
+        try {
+            return renderWithLayouts(s.page, s.layouts, params);
+        }
+        catch (err) {
+            const e = err instanceof Error ? err : new Error(String(err));
+            if (s.page.errorView)
+                return s.page.errorView(e, params);
+            return options.error?.(e) ?? html `<pre>${e.message}</pre>`;
+        }
+    }}`;
+}
+function isStale(ctx, seq) {
+    return seq !== ctx.renderSeq;
+}
+/**
+ * Wrap a page's view in layouts (from inner to outer).
+ * Each layout receives `child` = TemplateResult of the nested page or
+ * next layout — composes like a matryoshka.
+ */
+function renderWithLayouts(page, layouts, params) {
+    const baked = readBaked();
+    const data = page.load ? page.load(params, baked) : undefined;
+    let view = page.view({
+        params,
+        data,
+        path: () => location.pathname,
+        child: null,
+    });
+    for (let i = layouts.length - 1; i >= 0; i--) {
+        const layout = layouts[i];
+        const layoutData = layout.load ? layout.load(params) : undefined;
+        view = layout.view({
+            params,
+            data: layoutData,
+            path: () => location.pathname,
+            child: view,
+        });
+    }
+    return view;
+}
+// ---------- Default loading view ----------
+//
+// Thin progress bar at the top of the screen. Style is injected once
+// globally (lazy, on first show). No animations for prefers-reduced-motion.
+const DEFAULT_LOADING_STYLE_ID = "mado-default-loading-style";
+const DEFAULT_LOADING_CSS = `
+  @keyframes mado-progress {
+    0%   { transform: translateX(-100%); }
+    50%  { transform: translateX(0%);    }
+    100% { transform: translateX(100%);  }
+  }
+  .mado-progress-bar {
+    position: fixed; top: 0; left: 0; right: 0;
+    height: 2px; background: rgba(0,0,0,.06);
+    z-index: 2147483647; overflow: hidden;
+    pointer-events: none;
+  }
+  .mado-progress-bar::after {
+    content: ""; display: block; height: 100%; width: 40%;
+    background: currentColor; opacity: .8;
+    animation: mado-progress 1.2s ease-in-out infinite;
+  }
+  @media (prefers-reduced-motion: reduce) {
+    .mado-progress-bar::after { animation: none; width: 100%; }
+  }
+`;
+function ensureDefaultLoadingStyle() {
+    if (typeof document === "undefined")
+        return;
+    if (document.getElementById(DEFAULT_LOADING_STYLE_ID))
+        return;
+    const style = document.createElement("style");
+    style.id = DEFAULT_LOADING_STYLE_ID;
+    style.textContent = DEFAULT_LOADING_CSS;
+    document.head.appendChild(style);
+}
+function defaultLoadingView() {
+    ensureDefaultLoadingStyle();
+    return html `<div class="mado-progress-bar" aria-hidden="true"></div>`;
+}
+/**
+ * Read baked data from `<script id="bake" type="application/json">`
+ * placed by `scripts/bake.mjs` during static generation. Returns
+ * undefined in SPA mode.
+ */
+function readBaked() {
+    const el = document.getElementById("bake");
+    if (!el || el.textContent == null)
+        return undefined;
+    try {
+        return JSON.parse(el.textContent);
+    }
+    catch {
+        return undefined;
+    }
+}
+// ---------- Test hooks ----------
+export const _testHooks = {
+    activeRoutesSize() {
+        return activeRoutes.size;
+    },
+};
+//# sourceMappingURL=manifest.js.map

package/dist/src/router/manifest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.js","sourceRoot":"","sources":["../../../src/router/manifest.ts"],"names":[],"mappings":"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"}

package/dist/src/router/match.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Pure pattern matching + flatten/normalize of the manifest.
+ *
+ * There is NO window/document/history or signals here — only functions
+ * over strings and objects. This allows:
+ *   - testing routing in Node without jsdom;
+ *   - reusing the same compile/regex in bake / prefetch without duplication.
+ */
+import { type Page, type RouteEntry } from "../page.js";
+import type { TemplateResult } from "../html/template-types.js";
+export type RouteParams = Record<string, string>;
+export type RouteHandler = (params: RouteParams) => TemplateResult;
+export type Routes = Record<string, RouteHandler>;
+export interface CompiledRoute {
+    pattern: string;
+    regex: RegExp;
+    keys: string[];
+    handler: RouteHandler;
+}
+/**
+ * Compile a pattern like `/users/:id` into a `CompiledRoute` with
+ * named keys and a regex for matching against `location.pathname`.
+ *
+ * Special case `*` — wildcard fallback, matches anything.
+ */
+export declare function compile(pattern: string, handler: RouteHandler): CompiledRoute;
+/**
+ * Find the first matching CompiledRoute for path. Returns already
+ * decoded params (decodeURIComponent on each segment).
+ * Wildcard (`*`) is skipped — handle it separately as a fallback.
+ */
+export declare function matchRoute(path: string, compiled: readonly CompiledRoute[]): {
+    route: CompiledRoute;
+    params: RouteParams;
+} | null;
+/** Simple regex WITHOUT keys — for prefetch (we only need the match fact). */
+export declare function patternToRegex(pattern: string): RegExp;
+export type RoutesMap = Record<string, RouteEntry>;
+export interface FlatEntry {
+    loader: () => Promise<Page> | Page;
+    layouts: Array<() => Promise<Page> | Page>;
+}
+/**
+ * Unfold a nested manifest into a flat list of `[fullPattern, FlatEntry]`.
+ * Accumulates parent layouts along the way, so each leaf route
+ * "knows" all its layouts (from outer to inner).
+ */
+export declare function flatten(map: RoutesMap, prefix?: string, layouts?: FlatEntry["layouts"]): Array<[string, FlatEntry]>;
+/** Careful path segment joining without duplicate slashes. */
+export declare function joinPath(a: string, b: string): string;
+/**
+ * Normalise a RouteEntry into a uniform `() => Promise<Page> | Page`.
+ *
+ * RouteEntry comes in three forms:
+ *   - a ready Page  → return as-is
+ *   - dynamic import → await the default export and check it's a Page
+ *   - something else  → throw (bad manifest entry)
+ *
+ * This function is the single place that handles both forms;
+ * the rest of the code works only with the unified loader.
+ */
+export declare function normalize(entry: RouteEntry): () => Promise<Page> | Page;

package/dist/src/router/match.js

@@ -0,0 +1,117 @@
+/**
+ * Pure pattern matching + flatten/normalize of the manifest.
+ *
+ * There is NO window/document/history or signals here — only functions
+ * over strings and objects. This allows:
+ *   - testing routing in Node without jsdom;
+ *   - reusing the same compile/regex in bake / prefetch without duplication.
+ */
+import { isNested, isPage } from "../page.js";
+/**
+ * Compile a pattern like `/users/:id` into a `CompiledRoute` with
+ * named keys and a regex for matching against `location.pathname`.
+ *
+ * Special case `*` — wildcard fallback, matches anything.
+ */
+export function compile(pattern, handler) {
+    if (pattern === "*") {
+        return { pattern, regex: /.*/, keys: [], handler };
+    }
+    const keys = [];
+    const re = pattern.replace(/\/$/, "").replace(/:[\w]+/g, (m) => {
+        keys.push(m.slice(1));
+        return "([^/]+)";
+    });
+    return {
+        pattern,
+        regex: new RegExp(`^${re}/?$`),
+        keys,
+        handler,
+    };
+}
+/**
+ * Find the first matching CompiledRoute for path. Returns already
+ * decoded params (decodeURIComponent on each segment).
+ * Wildcard (`*`) is skipped — handle it separately as a fallback.
+ */
+export function matchRoute(path, compiled) {
+    for (const r of compiled) {
+        if (r.pattern === "*")
+            continue;
+        const m = r.regex.exec(path);
+        if (m) {
+            const params = {};
+            r.keys.forEach((k, i) => {
+                params[k] = decodeURIComponent(m[i + 1] ?? "");
+            });
+            return { route: r, params };
+        }
+    }
+    return null;
+}
+/** Simple regex WITHOUT keys — for prefetch (we only need the match fact). */
+export function patternToRegex(pattern) {
+    const re = pattern.replace(/\/$/, "").replace(/:[\w]+/g, "([^/]+)");
+    return new RegExp(`^${re}/?$`);
+}
+/**
+ * Unfold a nested manifest into a flat list of `[fullPattern, FlatEntry]`.
+ * Accumulates parent layouts along the way, so each leaf route
+ * "knows" all its layouts (from outer to inner).
+ */
+export function flatten(map, prefix = "", layouts = []) {
+    const out = [];
+    for (const [k, v] of Object.entries(map)) {
+        const full = joinPath(prefix, k);
+        if (isNested(v)) {
+            const nextLayouts = v.layout
+                ? [...layouts, normalize(v.layout)]
+                : layouts;
+            for (const sub of flatten(v.routes, full, nextLayouts))
+                out.push(sub);
+        }
+        else {
+            out.push([full || "/", { loader: normalize(v), layouts }]);
+        }
+    }
+    return out;
+}
+/** Careful path segment joining without duplicate slashes. */
+export function joinPath(a, b) {
+    if (!a)
+        return b;
+    if (!b)
+        return a;
+    if (a.endsWith("/"))
+        a = a.slice(0, -1);
+    if (b.startsWith("/"))
+        b = b.slice(1);
+    return `${a}/${b}`;
+}
+/**
+ * Normalise a RouteEntry into a uniform `() => Promise<Page> | Page`.
+ *
+ * RouteEntry comes in three forms:
+ *   - a ready Page  → return as-is
+ *   - dynamic import → await the default export and check it's a Page
+ *   - something else  → throw (bad manifest entry)
+ *
+ * This function is the single place that handles both forms;
+ * the rest of the code works only with the unified loader.
+ */
+export function normalize(entry) {
+    if (isPage(entry))
+        return () => entry;
+    if (typeof entry === "function") {
+        return async () => {
+            const mod = await entry();
+            const p = mod.default;
+            if (!isPage(p)) {
+                throw new Error("[mado] Lazy route did not return page({...}) as the default export.");
+            }
+            return p;
+        };
+    }
+    throw new Error("[mado] Invalid entry in routes(): " + String(entry));
+}
+//# sourceMappingURL=match.js.map

package/dist/src/router/match.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"match.js","sourceRoot":"","sources":["../../../src/router/match.ts"],"names":[],"mappings":"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"}

package/dist/src/router/navigation.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Browser integration: History API, click interception, hover-prefetch,
+ * View Transitions, queryParam.
+ *
+ * Everything that touches `window` / `document` / `history` lives here,
+ * so match.ts remains clean and testable without jsdom.
+ */
+import { type Signal } from "./../signal.js";
+import { type Routes } from "./match.js";
+import type { TemplateResult } from "../html/template-types.js";
+export interface RouterApi {
+    /** Signal function that returns the current TemplateResult. */
+    view: () => TemplateResult;
+    /** Current path as a signal. */
+    path: () => string;
+    /** Programmatic navigation. */
+    navigate(to: string, opts?: {
+        replace?: boolean;
+    }): void;
+    /** Remove all listeners and release resources. */
+    dispose(): void;
+}
+export interface RouterOptions {
+    /**
+     * Use the View Transitions API on navigation (smooth crossfade).
+     * Default `true` — if the browser doesn't support it, safely
+     * falls back to a plain set().
+     */
+    viewTransitions?: boolean;
+    /**
+     * Hook for hover prefetch. Receives the pathname of the candidate
+     * (without origin, query/hash stripped). Used by routes()
+     * to register loaders; raw router() doesn't normally need this.
+     */
+    prefetch?: (pathname: string) => void;
+}
+/**
+ * Minimal History API router.
+ *
+ *   const route = router({
+ *     '/':          () => html`<x-home/>`,
+ *     '/users/:id': ({ id }) => html`<x-user .id=${id}/>`,
+ *     '*':          () => html`<x-404/>`,
+ *   });
+ *
+ *   html`<main>${route.view}</main>`
+ *
+ * Lifecycle: subscribes to popstate + intercepts clicks
+ * on `<a data-link>` + hover-prefetch (if hook given). All this
+ * is removed in `dispose()` — mandatory to call in tests and
+ * dev-overlay, otherwise listener leak.
+ */
+export declare function router(routes: Routes, options?: RouterOptions): RouterApi;
+/**
+ * Global helper for programmatic navigation. Equivalent to
+ * `api.navigate(to)` for any active router — updates the URL
+ * via History API and dispatches `popstate`, which all
+ * active routers on the page will pick up.
+ *
+ *   import { navigate } from "@madojs/mado";
+ *   navigate("/users/42");
+ *
+ * Used inside form handlers / events when you don't have
+ * direct access to RouterApi (e.g. inside a component's setup function
+ * that didn't receive the router as a parameter).
+ */
+export declare function navigate(to: string, opts?: {
+    replace?: boolean;
+}): void;
+export interface QueryParam {
+    (): string;
+    set(value: string | null, opts?: {
+        push?: boolean;
+    }): void;
+}
+/**
+ * Reactive query parameter.
+ *
+ *   const page = queryParam('page', '1');
+ *   page();              // '1' (or current URL value)
+ *   page.set('2');       // history.replaceState and re-render
+ *   page.set(null);      // delete the parameter
+ */
+export declare function queryParam(name: string, defaultValue?: string): QueryParam;
+/**
+ * For typing purposes — same characteristics as Signal<string>.
+ * Convenient in places that expect a plain signal.
+ */
+export type QuerySignal = Signal<string>;