@madojs/mado 0.5.1 → 0.6.1

package/starters/admin/src/components/x-input.ts

@@ -0,0 +1,74 @@
+// <x-input label name type placeholder required value @input @blur>
+//
+// Labeled input that proxies its events. Use inside `useForm()`:
+//
+//   <x-input name="email" type="email" required
+//            @input=${form.onInput} @blur=${form.onBlur}></x-input>
+
+import { component, css, html } from "@madojs/mado";
+
+component(
+  "x-input",
+  ({ host }) => () => {
+    const label = host.getAttribute("label") ?? "";
+    const name = host.getAttribute("name") ?? "";
+    const type = host.getAttribute("type") ?? "text";
+    const placeholder = host.getAttribute("placeholder") ?? "";
+    const required = host.hasAttribute("required");
+    const value = host.getAttribute("value") ?? "";
+    const error = host.getAttribute("error");
+
+    return html`
+      <label>
+        ${label
+          ? html`<span class="lbl">${label}${required ? html`<em>*</em>` : null}</span>`
+          : null}
+        <input
+          name=${name}
+          type=${type}
+          placeholder=${placeholder}
+          ?required=${required}
+          .value=${value}
+        >
+        ${error ? html`<small class="err">${error}</small>` : null}
+      </label>
+    `;
+  },
+  {
+    styles: css`
+      :host { display: block; }
+      label { display: block; }
+      .lbl {
+        display: block;
+        font-size: 12px;
+        color: var(--fg-muted);
+        margin-bottom: var(--space-1);
+      }
+      .lbl em {
+        color: var(--danger);
+        font-style: normal;
+        margin-left: 2px;
+      }
+      input {
+        width: 100%;
+        padding: 8px 10px;
+        font: inherit;
+        background: var(--bg);
+        color: var(--fg);
+        border: 1px solid var(--border);
+        border-radius: var(--radius-sm);
+      }
+      input:focus {
+        outline: none;
+        border-color: var(--accent);
+        box-shadow: 0 0 0 3px color-mix(in srgb, var(--accent) 25%, transparent);
+      }
+      .err {
+        display: block;
+        color: var(--danger);
+        font-size: 12px;
+        margin-top: var(--space-1);
+      }
+    `,
+  },
+);

package/starters/admin/src/layouts/app.ts

@@ -0,0 +1,101 @@
+// Admin shell layout: top bar + sidebar + content slot.
+//
+// A layout is just a `page({ view })` whose view renders `${ctx.child}`. The
+// router wraps every page in the enclosing group with this template, so the
+// shell is ALWAYS the outer frame, never below the page content.
+//
+// Keep the shell stateless if you can. Auth/user signals belong in
+// src/lib/auth.ts; the layout reads them.
+
+import { component, css, html, navigate, page } from "@madojs/mado";
+import { accessToken } from "../lib/api.js";
+import { logout } from "../lib/auth.js";
+import "../components/x-button.js";
+
+component(
+  "x-admin-shell",
+  () => () => html`
+    <header>
+      <a href="/admin" data-link class="brand">__APP_NAME__</a>
+      <nav>
+        <a href="/admin" data-link>Dashboard</a>
+        <a href="/admin/orders" data-link>Orders</a>
+      </nav>
+      <span class="spacer"></span>
+      <span class="user">${() => maskToken(accessToken())}</span>
+      <x-button
+        variant="ghost"
+        @click=${async () => {
+          await logout();
+          navigate("/login", { replace: true });
+        }}
+      >Sign out</x-button>
+    </header>
+    <aside>
+      <nav>
+        <a href="/admin" data-link>Overview</a>
+        <a href="/admin/orders" data-link>Orders</a>
+      </nav>
+    </aside>
+    <main>
+      <slot></slot>
+    </main>
+  `,
+  {
+    styles: css`
+      :host {
+        display: grid;
+        grid-template-columns: 220px 1fr;
+        grid-template-rows: 56px 1fr;
+        grid-template-areas:
+          "topbar topbar"
+          "side   main";
+        min-height: 100vh;
+      }
+      header {
+        grid-area: topbar;
+        display: flex;
+        align-items: center;
+        gap: var(--space-4);
+        padding: 0 var(--space-5);
+        background: var(--bg-elevated);
+        border-bottom: 1px solid var(--border);
+      }
+      header .brand { font-weight: 700; color: var(--fg); }
+      header nav { display: flex; gap: var(--space-3); }
+      header nav a { color: var(--fg-muted); }
+      header nav a:hover { color: var(--fg); text-decoration: none; }
+      header .user { color: var(--fg-muted); font-variant-numeric: tabular-nums; }
+      .spacer { flex: 1; }
+      aside {
+        grid-area: side;
+        border-right: 1px solid var(--border);
+        background: var(--bg-elevated);
+        padding: var(--space-4);
+      }
+      aside nav { display: flex; flex-direction: column; gap: var(--space-2); }
+      aside nav a {
+        padding: var(--space-2) var(--space-3);
+        border-radius: var(--radius-sm);
+        color: var(--fg-muted);
+      }
+      aside nav a:hover {
+        background: var(--bg);
+        color: var(--fg);
+        text-decoration: none;
+      }
+      main { grid-area: main; padding: var(--space-5); }
+    `,
+  },
+);
+
+function maskToken(token: string | null): string {
+  if (!token) return "—";
+  return `signed in · …${token.slice(-4)}`;
+}
+
+export default page({
+  view: ({ child }) => html`
+    <x-admin-shell>${child}</x-admin-shell>
+  `,
+});

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

@@ -0,0 +1,41 @@
+// Centered card layout for auth pages (login, signup, password reset).
+// Identical shape to layouts/app.ts but a different shell.
+
+import { component, css, html, page } from "@madojs/mado";
+
+component(
+  "x-auth-shell",
+  () => () => html`
+    <main>
+      <div class="card">
+        <slot></slot>
+      </div>
+    </main>
+  `,
+  {
+    styles: css`
+      :host {
+        display: block;
+        min-height: 100vh;
+      }
+      main {
+        min-height: 100vh;
+        display: grid;
+        place-items: center;
+        padding: var(--space-5);
+      }
+      .card {
+        background: var(--bg-elevated);
+        border: 1px solid var(--border);
+        border-radius: var(--radius);
+        box-shadow: var(--shadow-1);
+        padding: var(--space-6);
+        width: min(360px, 100%);
+      }
+    `,
+  },
+);
+
+export default page({
+  view: ({ child }) => html`<x-auth-shell>${child}</x-auth-shell>`,
+});

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,80 @@
+// Order detail page. Reads :id from params, fetches the order, and shows
+// inline loading/error/empty/ready states.
+
+import { each, 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>
+                ${each(
+                  o.items,
+                  (it) => it.sku,
+                  (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>
+        `;
+      }}
+    `;
+  },
+});