@madojs/mado 0.5.0 → 0.6.0

package/server/serve.mjs

@@ -6,19 +6,36 @@
 //   node server/serve.mjs basic                   # mount examples/basic/ at /
 //   EXAMPLE=showcase node server/serve.mjs        # mount examples/showcase/ at /
 //
-// Without EXAMPLE, / serves examples/index.html (example index).
+// Without EXAMPLE, / serves examples/index.html when running inside the Mado
+// repository, or ./index.html when running inside a generated app.
 // With EXAMPLE, all extensionless and /index.html requests fall back to
 // examples/<EXAMPLE>/index.html so the client router works from root, just
 // like a production SPA deploy.
 
-import { createServer } from "node:http";
-import { readFile, readdir, stat } from "node:fs/promises";
-import { watch, existsSync } from "node:fs";
+import { createServer, request as httpRequest } from "node:http";
+import { request as httpsRequest } from "node:https";
+import { readFile, readdir, readFile as readFileAsync, stat } from "node:fs/promises";
+import { watch, existsSync, readFileSync } from "node:fs";
 import { extname, join, resolve, sep } from "node:path";
 import { createHash } from "node:crypto";
 
 const ROOT = resolve(process.cwd());
-const PORT = Number(process.env.PORT ?? 5173);
+
+// Optional mado.config.json — used for dev.proxy and dev.port. Read with a
+// hand-rolled JSON parse to avoid a circular dep with scripts/_config.mjs
+// (this server is launched from cli.mjs and runs in its own Node process).
+const CONFIG = (() => {
+  try {
+    const file = join(ROOT, "mado.config.json");
+    if (!existsSync(file)) return {};
+    return JSON.parse(readFileSync(file, "utf8")) ?? {};
+  } catch {
+    return {};
+  }
+})();
+const PROXY_RULES = Object.entries(CONFIG.dev?.proxy ?? {}); // [["/api", "http://localhost:3000"], ...]
+
+const PORT = Number(process.env.PORT ?? CONFIG.dev?.port ?? 5173);
 const HMR = process.env.NO_HMR !== "1";
 
 const EXAMPLE = process.argv[2] ?? process.env.MADO_EXAMPLE ?? process.env.EXAMPLE ?? "";
@@ -26,6 +43,9 @@ const EXAMPLE_DIR = EXAMPLE
   ? resolve(join(ROOT, "examples", EXAMPLE))
   : "";
 const EXAMPLE_INDEX = EXAMPLE ? join(EXAMPLE_DIR, "index.html") : "";
+const EXAMPLES_INDEX = join(ROOT, "examples", "index.html");
+const APP_INDEX = join(ROOT, "index.html");
+const DEFAULT_INDEX = existsSync(EXAMPLES_INDEX) ? EXAMPLES_INDEX : APP_INDEX;
 
 if (EXAMPLE) {
   if (!existsSync(EXAMPLE_INDEX)) {
@@ -114,6 +134,16 @@ const server = createServer(async (req, res) => {
     const url = new URL(req.url ?? "/", `http://${req.headers.host}`);
     pathname = decodeURIComponent(url.pathname);
 
+    // Dev proxy: forward matching prefixes to an upstream backend, so the
+    // browser can reach the SPA and the API on a single origin without CORS.
+    const proxyRule = PROXY_RULES.find(([prefix]) => pathname.startsWith(prefix));
+    if (proxyRule) {
+      const [prefix, upstream] = proxyRule;
+      await proxyForward({ req, res, prefix, upstream, pathname, search: url.search });
+      reason = `proxy → ${upstream}`;
+      return;
+    }
+
     // SSE endpoint for HMR.
     if (pathname === "/__hmr") {
       res.writeHead(200, {
@@ -133,9 +163,7 @@ const server = createServer(async (req, res) => {
 
     // A mounted example owns root and SPA fallback. Otherwise serve the
     // examples index page.
-    const fallbackIndex = EXAMPLE
-      ? EXAMPLE_INDEX
-      : join(ROOT, "examples", "index.html");
+    const fallbackIndex = EXAMPLE ? EXAMPLE_INDEX : DEFAULT_INDEX;
 
     if (pathname === "/") {
       // Resolved through fallback below.
@@ -260,6 +288,10 @@ async function buildPreloadHints() {
         }
       }
     }
+  } else if (!existsSync(EXAMPLES_INDEX)) {
+    if (existsSync(join(ROOT, "dist/main.js"))) {
+      hrefs.push("/dist/main.js");
+    }
   }
   cachedPreloadHints = hrefs
     .map((h) => `  <link rel="modulepreload" href="${h}">`)
@@ -273,17 +305,75 @@ server.on("error", (err) => {
   process.exit(1);
 });
 
+async function proxyForward({ req, res, prefix, upstream, pathname, search }) {
+  // Strip the prefix only if the upstream URL itself ends with `/`; otherwise
+  // forward the full pathname so the backend sees /api/...
+  let upstreamUrl;
+  try {
+    upstreamUrl = new URL(upstream);
+  } catch {
+    res.writeHead(502).end(`bad upstream: ${upstream}`);
+    return;
+  }
+  const target = new URL(upstream);
+  // Compose path: <upstream.pathname rstrip "/"> + <pathname> + <search>
+  const tail = pathname; // keep the original /api/... so backends route normally
+  target.pathname = (target.pathname.replace(/\/$/, "")) + tail;
+  target.search = search;
+
+  const lib = target.protocol === "https:" ? httpsRequest : httpRequest;
+  const upstreamReq = lib(
+    target,
+    {
+      method: req.method,
+      headers: {
+        ...req.headers,
+        host: target.host,
+      },
+    },
+    (upstreamRes) => {
+      // Forward status and headers, then pipe the body.
+      res.writeHead(upstreamRes.statusCode ?? 502, upstreamRes.headers);
+      upstreamRes.pipe(res);
+    },
+  );
+  upstreamReq.on("error", (err) => {
+    console.error(`[serve] proxy error for ${pathname} → ${target.href}:`, err.message);
+    if (!res.headersSent) {
+      res.writeHead(502, { "content-type": "text/plain; charset=utf-8" });
+      res.end(`proxy upstream unavailable: ${target.host}\n${err.message}`);
+    } else {
+      res.end();
+    }
+  });
+  req.pipe(upstreamReq);
+  // Reference unused arg so lint is happy.
+  void prefix;
+}
+
 server.listen(PORT, () => {
-  const distReady = existsSync(join(ROOT, "dist/src/index.js"));
+  const distReady = existsSync(join(ROOT, "dist/src/index.js"))
+    || existsSync(join(ROOT, "dist/main.js"));
+  const mount = EXAMPLE
+    ? `examples/${EXAMPLE}/ -> /`
+    : existsSync(EXAMPLES_INDEX)
+      ? "examples/index.html landing"
+      : "index.html app";
   console.log("");
   console.log("Mado dev server");
   console.log(`  url:      http://localhost:${PORT}/`);
   console.log(`  root:     ${ROOT}`);
-  console.log(`  example:  ${EXAMPLE ? `examples/${EXAMPLE}/ -> /` : "examples/index.html landing"}`);
+  console.log(`  mount:    ${mount}`);
   console.log(`  hmr:      ${HMR ? "on" : "off"}`);
   console.log(`  preload:  ${PRELOAD}`);
   console.log(`  dist:     ${distReady ? "ready" : "missing (run mado build)"}`);
-  if (!EXAMPLE) {
+  if (PROXY_RULES.length > 0) {
+    console.log("  proxy:");
+    for (const [prefix, upstream] of PROXY_RULES) {
+      console.log(`            ${prefix.padEnd(10)} → ${upstream}`);
+    }
+  }
+  if (!EXAMPLE && existsSync(EXAMPLES_INDEX)) {
     console.log("  try:      mado serve basic");
     console.log("            mado serve showcase");
     console.log("            mado serve tickets");

package/starters/admin/README.md

@@ -0,0 +1,63 @@
+# __APP_NAME__
+
+A starter Mado admin app: nested routes, a guarded admin shell, a blessed API
+client, and a one-shot release pipeline.
+
+## What you get
+
+- `src/main.ts` — 8 lines: mount the router into `#app`. Layouts are NOT
+  declared here, only in `src/routes.ts`.
+- `src/routes.ts` — nested manifest with three groups:
+  - `/` → public landing (bakeable),
+  - `/login` → centered `auth` layout,
+  - `/admin` → `app` layout, **guarded** by `requireAuth`.
+- `src/layouts/app.ts` — admin shell (top bar + sidebar + content slot).
+- `src/layouts/auth.ts` — centered card for sign-in.
+- `src/lib/api.ts` — `createApiClient(baseUrl)` with bearer token, 401-refresh
+  retry, JSON in/out and a typed `ApiError`.
+- `src/lib/auth.ts` — memory-only `accessToken`, `restoreSession()` from an
+  HttpOnly refresh cookie, and the `requireAuth` guard.
+- `src/components/` — tiny `x-button` and `x-input` Web Components.
+- `mado.config.json` — one config file. Includes a `dev.proxy` for `/api`.
+
+## Commands
+
+```bash
+npm run dev        # tsc -w + dev server on http://localhost:5173, HMR on
+npm run build      # tsc → dist/
+npm run typecheck  # tsc --noEmit
+npm run bundle     # esbuild → out/assets/
+npm run bake       # prerender baked routes → out/baked/
+npm run release    # typecheck + build + bundle + bake + copy public/ → out/
+npm run preview    # serve out/ locally (production rehearsal)
+```
+
+To deploy, run `npm run release` and upload the entire `out/` directory
+anywhere static (nginx, Cloudflare Pages, S3, Netlify, GitHub Pages, …).
+
+## Backend expectations
+
+The blessed `api` client speaks JSON. The auth recipe expects:
+
+- `POST /api/auth/login` → `{ accessToken: string }` (sets refresh cookie)
+- `POST /api/auth/refresh` → `{ accessToken: string }` (reads refresh cookie)
+- `POST /api/auth/logout` → 204 (clears refresh cookie)
+
+Change `mado.config.json#dev.proxy` to point at your backend in development.
+
+## Where things live
+
+| What                | Where                                |
+|---------------------|--------------------------------------|
+| New URL             | `src/pages/*.ts` + add to `routes.ts`|
+| New protected URL   | inside the `/admin` layout block     |
+| New layout          | `src/layouts/*.ts`                   |
+| New reusable widget | `src/components/x-*.ts`              |
+| New API call        | `src/lib/api.ts` (add a method)      |
+| New global signal   | `src/lib/<name>.ts`                  |
+| Static image        | `public/<file>`                      |
+
+See the framework docs:
+[`docs/en/11-layouts.md`](https://github.com/madojs/mado/blob/main/docs/en/11-layouts.md),
+[`docs/en/12-auth-and-api.md`](https://github.com/madojs/mado/blob/main/docs/en/12-auth-and-api.md),
+[`docs/en/13-deployment.md`](https://github.com/madojs/mado/blob/main/docs/en/13-deployment.md).

package/starters/admin/index.html

@@ -0,0 +1,21 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <title>__APP_NAME__</title>
+    <link rel="icon" type="image/svg+xml" href="/favicon.svg">
+    <script type="importmap">
+      {
+        "imports": {
+          "@madojs/mado": "./node_modules/@madojs/mado/dist/src/index.js",
+          "@madojs/mado/": "./node_modules/@madojs/mado/dist/src/"
+        }
+      }
+    </script>
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="./dist/main.js"></script>
+  </body>
+</html>

package/starters/admin/mado.config.json

@@ -0,0 +1,22 @@
+{
+  "dev": {
+    "port": 5173,
+    "proxy": {
+      "/api": "http://localhost:3000"
+    }
+  },
+  "build": {
+    "out": "out",
+    "dist": "dist",
+    "publicDir": "public"
+  },
+  "bake": {
+    "entry": "src/routes.ts",
+    "template": "index.html",
+    "baseUrl": "https://example.com"
+  },
+  "bundle": {
+    "splitting": true,
+    "compress": ["gz", "br"]
+  }
+}

package/starters/admin/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "__PACKAGE_NAME__",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "build": "mado build",
+    "typecheck": "mado typecheck",
+    "dev": "mado dev",
+    "serve": "mado serve",
+    "bundle": "mado bundle",
+    "bake": "mado bake",
+    "release": "mado release",
+    "preview": "mado preview"
+  },
+  "dependencies": {
+    "@madojs/mado": "__MADOJS_VERSION__"
+  },
+  "devDependencies": {
+    "typescript": "^6.0.3"
+  }
+}

package/starters/admin/public/favicon.svg

@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32">
+  <rect width="32" height="32" rx="6" fill="#1f6feb"/>
+  <text x="16" y="22" text-anchor="middle" font-family="ui-sans-serif, system-ui, sans-serif" font-weight="700" font-size="18" fill="white">M</text>
+</svg>

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

@@ -0,0 +1,55 @@
+// <x-button variant="primary|ghost|danger" ?disabled>
+//
+// Wraps a native <button> so it can be slotted with text/icon and styled
+// consistently across the app. Click events bubble naturally because Shadow
+// DOM is `mode: open` and composed: true is the default for `click`.
+
+import { component, css, html } from "@madojs/mado";
+
+component(
+  "x-button",
+  ({ host }) => () => {
+    const variant = host.getAttribute("variant") ?? "primary";
+    const disabled = host.hasAttribute("disabled");
+    return html`
+      <button data-variant=${variant} ?disabled=${disabled}>
+        <slot></slot>
+      </button>
+    `;
+  },
+  {
+    styles: css`
+      :host { display: inline-flex; }
+      button {
+        display: inline-flex;
+        align-items: center;
+        gap: var(--space-2);
+        padding: 8px 14px;
+        border-radius: var(--radius-sm);
+        border: 1px solid transparent;
+        font: inherit;
+        cursor: pointer;
+        background: var(--accent);
+        color: var(--accent-fg);
+        transition: filter .12s ease;
+      }
+      button:hover:not(:disabled) { filter: brightness(1.07); }
+      button:active:not(:disabled) { filter: brightness(.95); }
+      button:disabled { opacity: .55; cursor: not-allowed; }
+
+      button[data-variant="ghost"] {
+        background: transparent;
+        color: var(--fg);
+        border-color: var(--border);
+      }
+      button[data-variant="ghost"]:hover:not(:disabled) {
+        background: var(--bg-elevated);
+      }
+
+      button[data-variant="danger"] {
+        background: var(--danger);
+        color: white;
+      }
+    `,
+  },
+);

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>`,
+});