@madojs/mado 0.5.0 → 0.6.0

package/starters/admin/src/lib/api.ts

@@ -0,0 +1,133 @@
+// Blessed API client recipe.
+//
+// One JSON fetch wrapper. One error type. Bearer token from `accessToken`.
+// A refresh path that asks `/api/auth/refresh` (HttpOnly cookie) and retries
+// once. Aborts via `AbortSignal`. JSON in / JSON out.
+//
+// Copy and adjust to your backend. Keep `api` as the single fetch boundary so
+// that auth, refresh, error parsing and tracing live in exactly one place.
+
+import { signal } from "@madojs/mado";
+
+/** Memory-only access token. Refresh restores it from an HttpOnly cookie. */
+export const accessToken = signal<string | null>(null);
+
+/** Typed HTTP error with structured `body` for the UI to inspect. */
+export class ApiError extends Error {
+  constructor(
+    public status: number,
+    public body: unknown,
+    message: string,
+  ) {
+    super(message);
+    this.name = "ApiError";
+  }
+}
+
+export interface ApiInit extends Omit<RequestInit, "body"> {
+  /** JSON-serialisable body. If set, `content-type: application/json` is added. */
+  json?: unknown;
+  /** Override the default base URL for this call. */
+  baseUrl?: string;
+}
+
+/**
+ * Join a base path and a relative path without losing prefixes.
+ * Works with both relative (`/api`) and absolute (`https://...`) bases.
+ */
+function joinUrl(base: string, path: string): string {
+  if (/^https?:\/\//.test(path)) return path;
+
+  const p = path.replace(/^\/+/, "");
+
+  // Absolute URL base — keep its pathname prefix (for example /api).
+  if (/^https?:\/\//.test(base)) {
+    return new URL(p, base.replace(/\/+$/, "") + "/").href;
+  }
+
+  // Relative base (e.g. "/api") — simple string join, normalising slashes.
+  const b = base.replace(/\/+$/, "");
+  return p ? `${b}/${p}` : b || "/";
+}
+
+/**
+ * Create an API client bound to a base URL. Returns an `api()` function that
+ * speaks JSON, attaches the access token, and retries once after a 401 if a
+ * refresh succeeds.
+ *
+ *   export const api = createApiClient("/api");
+ *   const user = await api<User>("/users/me");
+ *   await api("/posts", { method: "POST", json: { title: "hi" } });
+ */
+export function createApiClient(baseUrl: string) {
+  let refreshing: Promise<boolean> | null = null;
+
+  async function refresh(): Promise<boolean> {
+    if (refreshing) return refreshing;
+    refreshing = (async () => {
+      try {
+        const res = await fetch(joinUrl(baseUrl, "/auth/refresh"), {
+          method: "POST",
+          credentials: "include",
+        });
+        if (!res.ok) return false;
+        const data = (await res.json().catch(() => null)) as
+          | { accessToken?: string }
+          | null;
+        if (!data?.accessToken) return false;
+        accessToken.set(data.accessToken);
+        return true;
+      } catch {
+        return false;
+      } finally {
+        refreshing = null;
+      }
+    })();
+    return refreshing;
+  }
+
+  async function request<T>(
+    path: string,
+    init: ApiInit = {},
+    retried = false,
+  ): Promise<T> {
+    const url = joinUrl(init.baseUrl ?? baseUrl, path);
+    const headers = new Headers(init.headers);
+    if (init.json !== undefined && !headers.has("content-type")) {
+      headers.set("content-type", "application/json");
+    }
+    const token = accessToken();
+    if (token) headers.set("authorization", `Bearer ${token}`);
+
+    const res = await fetch(url, {
+      ...init,
+      headers,
+      credentials: init.credentials ?? "include",
+      body:
+        init.json !== undefined
+          ? JSON.stringify(init.json)
+          : (init as RequestInit).body,
+    });
+
+    if (res.status === 401) {
+      if (!retried && (await refresh())) {
+        return request<T>(path, init, true);
+      }
+      accessToken.set(null);
+      throw new ApiError(401, null, "Unauthorized");
+    }
+    if (!res.ok) {
+      const body = await res.json().catch(() => null);
+      throw new ApiError(res.status, body, `HTTP ${res.status} ${res.statusText}`);
+    }
+    if (res.status === 204) return null as unknown as T;
+    return (await res.json()) as T;
+  }
+
+  return function api<T>(path: string, init: ApiInit = {}): Promise<T> {
+    return request<T>(path, init);
+  };
+}
+
+/** Default app-wide client. Change the base URL via mado.config.json dev.proxy. */
+export const api = createApiClient("/api");

package/starters/admin/src/lib/auth.ts

@@ -0,0 +1,83 @@
+// Blessed auth recipe: memory-only access token + HttpOnly-cookie refresh +
+// `requireAuth` guard for use in nested route groups.
+//
+// Usage in routes.ts:
+//
+//   "/admin": layout({
+//     layout: () => import("./layouts/app.js"),
+//     guard:  requireAuth,
+//     routes: { ... },
+//   })
+//
+// When a user lands on a protected route, requireAuth() tries to silently
+// restore the access token via the refresh cookie. If that fails, it redirects
+// to `/login?return=<original-url>`. The login page reads `return` and
+// navigates back after a successful sign-in.
+
+import type { Guard } from "@madojs/mado";
+import { accessToken, api, ApiError } from "./api.js";
+
+let restorePromise: Promise<boolean> | null = null;
+
+/**
+ * Try once per session to restore the access token from the HttpOnly refresh
+ * cookie. Subsequent calls reuse the same promise so a hard refresh that hits
+ * five protected routes does not fire five refresh requests.
+ */
+export async function restoreSession(): Promise<boolean> {
+  if (accessToken()) return true;
+  if (restorePromise) return restorePromise;
+  restorePromise = (async () => {
+    try {
+      const data = await api<{ accessToken: string }>("/auth/refresh", {
+        method: "POST",
+      });
+      accessToken.set(data.accessToken);
+      return true;
+    } catch (e) {
+      // 401 is expected for unauthenticated visitors.
+      if (e instanceof ApiError && e.status === 401) return false;
+      return false;
+    } finally {
+      restorePromise = null;
+    }
+  })();
+  return restorePromise;
+}
+
+/**
+ * Route guard: only let the user in if they have a valid session. Otherwise
+ * redirect to /login, preserving the original URL as `?return=`.
+ */
+export const requireAuth: Guard = async ({ path }) => {
+  if (accessToken()) return;
+  if (await restoreSession()) return;
+  return {
+    redirect: `/login?return=${encodeURIComponent(path)}`,
+    replace: true,
+  };
+};
+
+export interface LoginCredentials {
+  email: string;
+  password: string;
+}
+
+/** Log in. Persists the access token in memory; refresh cookie is set by the server. */
+export async function login(creds: LoginCredentials): Promise<void> {
+  const data = await api<{ accessToken: string }>("/auth/login", {
+    method: "POST",
+    json: creds,
+  });
+  accessToken.set(data.accessToken);
+}
+
+/** Log out everywhere: drop token in memory and tell the server to invalidate the refresh cookie. */
+export async function logout(): Promise<void> {
+  try {
+    await api("/auth/logout", { method: "POST" });
+  } catch {
+    // Best-effort; even if the network is offline we still clear locally.
+  }
+  accessToken.set(null);
+}

package/starters/admin/src/main.ts

@@ -0,0 +1,15 @@
+// App entry point.
+//
+// The single job of main.ts is: mount the router into #app. Everything else
+// (layouts, guards, pages, auth) is declared in routes.ts and the modules it
+// imports. Do NOT wrap routes in a custom shell here — the shell is a `layout()`
+// (see src/layouts/) so it can be different per route group.
+
+import { html, render } from "@madojs/mado";
+import "./styles/global.js";
+import router from "./routes.js";
+
+const app = document.getElementById("app");
+if (!app) throw new Error("#app not found");
+
+render(html`${router.view}`, app);

package/starters/admin/src/pages/admin/dashboard.ts

@@ -0,0 +1,48 @@
+// Admin dashboard. Demonstrates `resource()` for loading data with
+// loading/error states.
+
+import { html, jsonFetcher, page, resource } from "@madojs/mado";
+
+interface Stats {
+  orders: number;
+  revenue: number;
+  customers: number;
+}
+
+export default page({
+  title: "Dashboard",
+  view: () => {
+    const stats = resource(() => "/api/admin/stats", jsonFetcher<Stats>(), {
+      staleTime: 30_000,
+    });
+
+    return html`
+      <h1 style="margin:0 0 24px;">Dashboard</h1>
+      ${() => {
+        if (stats.loading()) return html`<p class="muted">Loading…</p>`;
+        if (stats.error())
+          return html`<p style="color:var(--danger);">${stats.error()?.message}</p>`;
+        const s = stats.data();
+        if (!s) return null;
+        return html`
+          <div style="display:grid;grid-template-columns:repeat(3,1fr);gap:var(--space-4);">
+            <div class="card">
+              <div class="muted">Orders</div>
+              <div style="font-size:24px;font-weight:700;">${s.orders}</div>
+            </div>
+            <div class="card">
+              <div class="muted">Revenue</div>
+              <div style="font-size:24px;font-weight:700;">
+                $${s.revenue.toLocaleString()}
+              </div>
+            </div>
+            <div class="card">
+              <div class="muted">Customers</div>
+              <div style="font-size:24px;font-weight:700;">${s.customers}</div>
+            </div>
+          </div>
+        `;
+      }}
+    `;
+  },
+});

package/starters/admin/src/pages/admin/order-detail.ts

@@ -0,0 +1,78 @@
+// Order detail page. Reads :id from params, fetches the order, and shows
+// inline loading/error/empty/ready states.
+
+import { html, jsonFetcher, page, resource } from "@madojs/mado";
+
+interface OrderDetail {
+  id: string;
+  customer: string;
+  total: number;
+  status: string;
+  items: Array<{ sku: string; name: string; qty: number; price: number }>;
+}
+
+export default page<{ id: string }>({
+  title: ({ id }) => `Order ${id}`,
+  view: ({ params }) => {
+    const order = resource(
+      () => `/api/admin/orders/${params.id}`,
+      jsonFetcher<OrderDetail>(),
+      { staleTime: 15_000 },
+    );
+
+    return html`
+      <p>
+        <a href="/admin/orders" data-link>← All orders</a>
+      </p>
+      ${() => {
+        if (order.loading() && !order.data())
+          return html`<p class="muted">Loading order…</p>`;
+        if (order.error())
+          return html`<p style="color:var(--danger);">${order.error()?.message}</p>`;
+        const o = order.data();
+        if (!o)
+          return html`<p class="muted">Order not found.</p>`;
+        return html`
+          <h1 style="margin:0 0 8px;">Order ${o.id}</h1>
+          <p class="muted" style="margin:0 0 24px;">${o.customer} · ${o.status}</p>
+          <div class="card">
+            <table style="width:100%;border-collapse:collapse;">
+              <thead>
+                <tr style="text-align:left;border-bottom:1px solid var(--border);">
+                  <th style="padding:8px 0;">SKU</th>
+                  <th style="padding:8px 0;">Item</th>
+                  <th style="padding:8px 0;text-align:right;">Qty</th>
+                  <th style="padding:8px 0;text-align:right;">Price</th>
+                </tr>
+              </thead>
+              <tbody>
+                ${o.items.map(
+                  (it) => html`
+                    <tr style="border-bottom:1px solid var(--border);">
+                      <td style="padding:8px 0;">${it.sku}</td>
+                      <td style="padding:8px 0;">${it.name}</td>
+                      <td style="padding:8px 0;text-align:right;">${it.qty}</td>
+                      <td style="padding:8px 0;text-align:right;font-variant-numeric:tabular-nums;">
+                        $${it.price.toFixed(2)}
+                      </td>
+                    </tr>
+                  `,
+                )}
+              </tbody>
+              <tfoot>
+                <tr>
+                  <td colspan="3" style="padding-top:12px;text-align:right;font-weight:600;">
+                    Total
+                  </td>
+                  <td style="padding-top:12px;text-align:right;font-weight:600;font-variant-numeric:tabular-nums;">
+                    $${o.total.toFixed(2)}
+                  </td>
+                </tr>
+              </tfoot>
+            </table>
+          </div>
+        `;
+      }}
+    `;
+  },
+});

package/starters/admin/src/pages/admin/orders.ts

@@ -0,0 +1,117 @@
+// Orders list. Demonstrates queryParam() filters and each() keyed table rows.
+
+import {
+  each,
+  html,
+  jsonFetcher,
+  page,
+  queryParam,
+  resource,
+} from "@madojs/mado";
+
+interface Order {
+  id: string;
+  customer: string;
+  total: number;
+  status: "open" | "paid" | "shipped" | "cancelled";
+}
+
+export default page({
+  title: "Orders",
+  view: () => {
+    const status = queryParam("status", "");
+    const search = queryParam("q", "");
+
+    const orders = resource(
+      () => {
+        const params = new URLSearchParams();
+        if (status()) params.set("status", status());
+        if (search()) params.set("q", search());
+        const qs = params.toString();
+        return `/api/admin/orders${qs ? `?${qs}` : ""}`;
+      },
+      jsonFetcher<Order[]>(),
+      { staleTime: 5_000 },
+    );
+
+    return html`
+      <header style="display:flex;align-items:center;gap:var(--space-3);margin:0 0 16px;">
+        <h1 style="margin:0;">Orders</h1>
+        <span class="spacer"></span>
+        <input
+          type="search"
+          placeholder="Search…"
+          .value=${search}
+          @input=${(e: Event) => {
+            const t = e.target as HTMLInputElement;
+            search.set(t.value);
+          }}
+          style="padding:6px 10px;border:1px solid var(--border);border-radius:var(--radius-sm);background:var(--bg);color:var(--fg);"
+        >
+        <select
+          .value=${status}
+          @change=${(e: Event) => {
+            const t = e.target as HTMLSelectElement;
+            status.set(t.value);
+          }}
+          style="padding:6px 10px;border:1px solid var(--border);border-radius:var(--radius-sm);background:var(--bg);color:var(--fg);"
+        >
+          <option value="">All statuses</option>
+          <option value="open">Open</option>
+          <option value="paid">Paid</option>
+          <option value="shipped">Shipped</option>
+          <option value="cancelled">Cancelled</option>
+        </select>
+      </header>
+
+      <div class="card" style="padding:0;overflow:hidden;">
+        ${() => {
+          if (orders.loading() && !orders.data())
+            return html`<p class="muted" style="padding:16px;">Loading…</p>`;
+          if (orders.error())
+            return html`<p style="color:var(--danger);padding:16px;">
+              ${orders.error()?.message}
+            </p>`;
+          const list = orders.data() ?? [];
+          if (list.length === 0)
+            return html`<p class="muted" style="padding:24px;text-align:center;">
+              No orders match the current filters.
+            </p>`;
+          return html`
+            <table style="width:100%;border-collapse:collapse;">
+              <thead>
+                <tr style="text-align:left;border-bottom:1px solid var(--border);">
+                  <th style="padding:10px 14px;">ID</th>
+                  <th style="padding:10px 14px;">Customer</th>
+                  <th style="padding:10px 14px;">Status</th>
+                  <th style="padding:10px 14px;text-align:right;">Total</th>
+                </tr>
+              </thead>
+              <tbody>
+                ${() =>
+                  each(
+                    list,
+                    (o) => o.id,
+                    (o) => html`
+                      <tr style="border-bottom:1px solid var(--border);">
+                        <td style="padding:10px 14px;">
+                          <a href="/admin/orders/${o.id}" data-link>${o.id}</a>
+                        </td>
+                        <td style="padding:10px 14px;">${o.customer}</td>
+                        <td style="padding:10px 14px;">
+                          <span class="muted">${o.status}</span>
+                        </td>
+                        <td style="padding:10px 14px;text-align:right;font-variant-numeric:tabular-nums;">
+                          $${o.total.toFixed(2)}
+                        </td>
+                      </tr>
+                    `,
+                  )}
+              </tbody>
+            </table>
+          `;
+        }}
+      </div>
+    `;
+  },
+});

package/starters/admin/src/pages/home.ts

@@ -0,0 +1,25 @@
+// Public landing page. Demonstrates that the marketing surface can live
+// alongside the admin app without a guard, and can be baked for SEO.
+
+import { html, page } from "@madojs/mado";
+
+export default page({
+  title: "Welcome",
+  head: () => ({
+    description: "An admin app scaffold built with Mado.",
+    og: {
+      title: "__APP_NAME__",
+      description: "An admin app scaffold built with Mado.",
+      type: "website",
+    },
+  }),
+  view: () => html`
+    <main style="max-width:720px;margin:0 auto;padding:64px 24px;">
+      <h1>__APP_NAME__</h1>
+      <p>This is the public landing page.</p>
+      <p>
+        <a href="/admin" data-link>Open the admin app →</a>
+      </p>
+    </main>
+  `,
+});

package/starters/admin/src/pages/login.ts

@@ -0,0 +1,70 @@
+// Login page. Reads `?return=` to bounce the user back where they were
+// blocked by `requireAuth`.
+
+import { html, navigate, page, queryParam, signal, useForm } from "@madojs/mado";
+import { ApiError } from "../lib/api.js";
+import { login } from "../lib/auth.js";
+import "../components/x-input.js";
+import "../components/x-button.js";
+
+export default page({
+  title: "Sign in",
+  view: () => {
+    const returnTo = queryParam("return", "/admin");
+    const serverError = signal<string | null>(null);
+
+    const form = useForm({
+      email: { required: true, type: "email" as const },
+      password: { required: true, min: 4 },
+    });
+
+    const onSubmit = form.onSubmit(async (values) => {
+      serverError.set(null);
+      try {
+        await login({
+          email: String(values.email ?? ""),
+          password: String(values.password ?? ""),
+        });
+        navigate(returnTo(), { replace: true });
+      } catch (e) {
+        if (e instanceof ApiError && e.status === 401) {
+          serverError.set("Invalid email or password.");
+        } else {
+          serverError.set("Something went wrong. Try again.");
+        }
+      }
+    });
+
+    return html`
+      <h1 style="margin:0 0 16px;">Sign in</h1>
+      <p class="muted" style="margin:0 0 24px;">
+        Enter your credentials to continue.
+      </p>
+      <form @submit=${onSubmit} class="stack">
+        <x-input
+          label="Email"
+          name="email"
+          type="email"
+          required
+          @input=${form.onInput}
+          @blur=${form.onBlur}
+        ></x-input>
+        <x-input
+          label="Password"
+          name="password"
+          type="password"
+          required
+          @input=${form.onInput}
+          @blur=${form.onBlur}
+        ></x-input>
+        ${() =>
+          serverError()
+            ? html`<small style="color:var(--danger);">${serverError()}</small>`
+            : null}
+        <x-button
+          ?disabled=${() => !form.isValid() || form.submitting()}
+        >${() => (form.submitting() ? "Signing in…" : "Sign in")}</x-button>
+      </form>
+    `;
+  },
+});

package/starters/admin/src/pages/not-found.ts

@@ -0,0 +1,12 @@
+import { html, page } from "@madojs/mado";
+
+export default page({
+  title: "Not found",
+  view: () => html`
+    <main style="max-width:560px;margin:0 auto;padding:80px 24px;text-align:center;">
+      <h1 style="margin:0 0 12px;">404</h1>
+      <p class="muted">This page does not exist.</p>
+      <p><a href="/" data-link>← Back home</a></p>
+    </main>
+  `,
+});

package/starters/admin/src/routes.ts

@@ -0,0 +1,40 @@
+// The blessed routes manifest for an admin app.
+//
+//   "/"          → public landing
+//   "/login"     → centered auth layout
+//   "/admin/*"   → admin shell with sidebar/topbar, guarded by requireAuth
+//   "*"          → 404
+//
+// Layouts and guards live inside the layout() blocks. There is exactly one
+// canonical place to put a shell: a layout() in this manifest. Do not wrap
+// route output in main.ts or in custom-element wrappers — that path causes
+// the "shell-below-content" bug described in the v1 plan.
+//
+// Bake: `manifest` is exported separately for `mado bake` to discover pages
+// that declare `bake: { paths, data }`. Without this named export `mado bake`
+// fails with a clear error.
+
+import { layout, routes } from "@madojs/mado";
+import { requireAuth } from "./lib/auth.js";
+
+export const manifest = {
+  "/": () => import("./pages/home.js"),
+  "/login": layout({
+    layout: () => import("./layouts/auth.js"),
+    routes: {
+      "/": () => import("./pages/login.js"),
+    },
+  }),
+  "/admin": layout({
+    layout: () => import("./layouts/app.js"),
+    guard: requireAuth,
+    routes: {
+      "/": () => import("./pages/admin/dashboard.js"),
+      "/orders": () => import("./pages/admin/orders.js"),
+      "/orders/:id": () => import("./pages/admin/order-detail.js"),
+    },
+  }),
+  "*": () => import("./pages/not-found.js"),
+};
+
+export default routes(manifest);