@madojs/mado 0.11.0 → 0.12.0

package/starters/default/src/content/guides.ts

@@ -0,0 +1,55 @@
+// Browser-safe content module. `paths()` and `initialData()` in
+// `guide.page.ts` import from here, so this file MUST stay in the
+// client bundle — no Node-only APIs, no secrets, no env reads.
+//
+// In a larger app you would replace this with a markdown loader or a
+// public JSON file fetched at build time.
+// `Guide` is a JsonValue-safe shape: only plain string fields so it can
+// be passed to `static.initialData` and survive the snapshot serializer.
+// The explicit index signature satisfies Mado's `JsonValue` constraint
+// without any runtime cost.
+export type Guide = {
+  slug: string;
+  title: string;
+  summary: string;
+  body: string;
+  [key: string]: string;
+};
+
+export const guides: Guide[] = [
+  {
+    slug: "components",
+    title: "Web Components are the app shell",
+    summary:
+      "Every visual unit in Mado is a real custom element with its own open shadow root.",
+    body:
+      "Mado does not ship a virtual DOM. The same custom element you " +
+      "register with `component()` runs in the live SPA and inside the " +
+      "snapshotted Declarative Shadow DOM the static release produces.",
+  },
+  {
+    slug: "signals",
+    title: "Signals are the reactivity model",
+    summary:
+      "Read with `count()`, write with `count.set()`, derive with `computed()`.",
+    body:
+      "Signals are getter functions. Subscriptions are automatic inside " +
+      "`html\\`...\\`` template fragments and `effect()` callbacks, and " +
+      "released when the surrounding component or page unmounts.",
+  },
+  {
+    slug: "snapshots",
+    title: "Browser-rendered static snapshots",
+    summary:
+      "`mado release` runs your app in a real Chromium and freezes the " +
+      "rendered HTML — including the Shadow DOM — into one file per route.",
+    body:
+      "The snapshot ships as Declarative Shadow DOM. On first paint the " +
+      "client component re-attaches to the same host with zero hydration " +
+      "boundary and zero duplicated trees.",
+  },
+];
+
+export function findGuide(slug: string): Guide | undefined {
+  return guides.find((g) => g.slug === slug);
+}

package/starters/default/src/main.ts

@@ -1,16 +1,12 @@
-// App entry point. The ONLY file allowed to import CSS at runtime.
-import "./shared/styles/tokens.css";
-import "./shared/styles/reset.css";
-import "./shared/styles/shell.css";
-import "./shared/styles/content.css";
-
+// Single entrypoint: import the app routes and render them into the
+// `#app` host declared in `index.html`. There is no separate "bootstrap"
+// step — the router IS the application.
 import { html, render } from "@madojs/mado";
-
-import { init as initAuth } from "./modules/auth/auth.service";
+import "./components/feature-card.component";
+import "./components/live-counter.component";
 import appRoutes from "./app.routes";
+import "./styles/tokens.css";
+import "./styles/reset.css";
+import "./styles/document.css";
 
-// One-off boot order: init cross-cutting modules first, then render the
-// router view into #app.
-await initAuth();
-
-render(html`${appRoutes.view}`, document.getElementById("app")!);
+render(html`${appRoutes.view}`, document.getElementById("app")!);

package/starters/default/src/pages/app.page.ts

@@ -0,0 +1,41 @@
+// SPA-only interactive route. No `static:` declaration, so
+// `mado release` keeps it out of the sitemap and serves it through
+// the `_mado/spa.html` fallback at runtime — the canonical home for
+// in-app surfaces that should not appear in search results.
+import { html, page, routeUrl, signal } from "@madojs/mado";
+
+export default page({
+  title: "App",
+  head: () => ({
+    description: "A live SPA route demonstrating signals and components.",
+  }),
+  view: () => {
+    const name = signal("world");
+    return html`
+      <main class="document">
+        <p><a data-link href=${routeUrl("/")}>← Home</a></p>
+        <h1>Hello, ${() => name()}!</h1>
+        <p>
+          <label>
+            Your name:
+            <input
+              type="text"
+              .value=${() => name()}
+              @input=${(e: Event) =>
+                name.set((e.target as HTMLInputElement).value)}
+            />
+          </label>
+        </p>
+        <p>The same component model runs in the static landing AND here:</p>
+        <feature-card title="Live + static, one model">
+          Each <code>feature-card</code> below the title is a real custom
+          element with its own open shadow root. It works inside the
+          server-rendered snapshot and inside this SPA-only route without
+          changing a single line.
+        </feature-card>
+        <p>And here is a tiny reactive component you can drive locally:</p>
+        <p><live-counter></live-counter></p>
+      </main>
+    `;
+  },
+});

package/starters/default/src/pages/guide.page.ts

@@ -0,0 +1,40 @@
+// Dynamic static page. `static.paths()` enumerates the slugs that
+// the snapshot pipeline materialises at build time; `initialData()`
+// seeds the rendered HTML so neither the snapshot nor the live boot
+// has to re-fetch the guide body.
+import { html, page, routeUrl } from "@madojs/mado";
+import { findGuide, guides, type Guide } from "../content/guides";
+
+type Params = { slug: string };
+
+export default page<Params, Guide | null, Guide | null>({
+  static: {
+    paths: () => guides.map((g) => ({ slug: g.slug })),
+    initialData: (params) => findGuide(params.slug) ?? null,
+  },
+  title: (params) => findGuide(params.slug)?.title ?? "Guide not found",
+  head: (_params, seed) => {
+    if (!seed) return { title: "Guide not found" };
+    return { title: seed.title, description: seed.summary };
+  },
+  view: ({ data }) => {
+    if (!data) {
+      return html`
+        <main class="document">
+          <h1>Guide not found</h1>
+          <p><a data-link href=${routeUrl("/")}>Back home</a></p>
+        </main>
+      `;
+    }
+    return html`
+      <main class="document">
+        <p><a data-link href=${routeUrl("/")}>← Home</a></p>
+        <article>
+          <h1>${data.title}</h1>
+          <p class="lead">${data.summary}</p>
+          <p>${data.body}</p>
+        </article>
+      </main>
+    `;
+  },
+});

package/starters/default/src/pages/home.page.ts

@@ -0,0 +1,49 @@
+// Public landing page. `static: true` opts the route into the
+// browser-rendered snapshot pipeline — `mado release` captures this
+// view into `out/index.html` with the rendered Shadow DOM inlined.
+import { html, page, routeUrl } from "@madojs/mado";
+import { guides } from "../content/guides";
+
+export default page({
+  static: true,
+  title: "Mado — a calm native-first web framework",
+  head: () => ({
+    description:
+      "Build with real Web Components, signals, routing, data and forms. " +
+      "Ship live SPAs and browser-rendered static documents from one " +
+      "component model.",
+  }),
+  view: () => html`
+    <main class="document">
+      <header class="hero">
+        <h1>Mado</h1>
+        <p class="lead">
+          A calm native-first web framework for sites and apps.
+        </p>
+        <p>
+          <strong>One component model. One page model. One release command.</strong>
+        </p>
+      </header>
+
+      <section class="features">
+        ${guides.map(
+          (guide) => html`
+            <feature-card title=${guide.title}>
+              ${guide.summary}
+              <a data-link href=${routeUrl(`/guide/${guide.slug}`)}>
+                Read the guide →
+              </a>
+            </feature-card>
+          `,
+        )}
+      </section>
+
+      <section class="cta">
+        <h2>Open the app</h2>
+        <p>
+          <a data-link href=${routeUrl("/app")}>Launch the live SPA →</a>
+        </p>
+      </section>
+    </main>
+  `,
+});

package/starters/default/src/pages/not-found.page.ts

@@ -0,0 +1,18 @@
+// Catch-all 404. Not statically captured; the SPA shell serves it
+// whenever a deep link does not match a known route.
+import { html, page, routeUrl } from "@madojs/mado";
+
+export default page({
+  title: "Page not found",
+  head: () => ({
+    description: "The page you are looking for does not exist.",
+    meta: [{ name: "robots", content: "noindex" }],
+  }),
+  view: ({ path }) => html`
+    <main class="document">
+      <h1>404</h1>
+      <p>No page is registered for <code>${() => path()}</code>.</p>
+      <p><a data-link href=${routeUrl("/")}>Back home</a></p>
+    </main>
+  `,
+});

package/starters/default/src/styles/document.css

@@ -0,0 +1,39 @@
+/* Document-level layout: header, sections, hero. Component styles
+   live inside their own shadow roots, this stylesheet styles the
+   light-DOM wrappers only. */
+.document {
+  max-width: 56rem;
+  margin: 0 auto;
+  padding: 3rem 1.5rem;
+  display: grid;
+  gap: 2.5rem;
+}
+
+.hero h1 {
+  margin: 0 0 0.5rem;
+  font-size: 3rem;
+  letter-spacing: -0.01em;
+}
+
+.hero .lead {
+  margin: 0 0 0.75rem;
+  font-size: 1.25rem;
+  color: var(--mado-fg-muted);
+}
+
+.features {
+  display: grid;
+  gap: 1rem;
+  grid-template-columns: repeat(auto-fit, minmax(16rem, 1fr));
+}
+
+.cta {
+  padding: 1.5rem;
+  border: 1px dashed var(--mado-border);
+  border-radius: var(--mado-radius);
+  background: var(--mado-surface);
+}
+
+article p {
+  margin: 0.75rem 0;
+}

package/starters/default/src/styles/reset.css

@@ -0,0 +1,37 @@
+/* Tiny modern reset. Keep it boring so nothing here surprises a new
+   contributor. */
+*,
+*::before,
+*::after {
+  box-sizing: border-box;
+}
+
+html,
+body {
+  margin: 0;
+}
+
+body {
+  background: var(--mado-bg);
+  color: var(--mado-fg);
+  font-family: var(--mado-font-body);
+  line-height: 1.5;
+}
+
+a {
+  color: var(--mado-accent);
+}
+
+button,
+input,
+select,
+textarea {
+  font: inherit;
+  color: inherit;
+}
+
+code {
+  background: var(--mado-surface);
+  padding: 0.05rem 0.3rem;
+  border-radius: 4px;
+}

package/starters/default/src/styles/tokens.css

@@ -0,0 +1,30 @@
+/* Design tokens. Override these to re-skin the app without touching
+   component CSS. Custom properties penetrate shadow roots, so every
+   component reads them automatically. */
+:root {
+  --mado-bg: #fafafa;
+  --mado-surface: #ffffff;
+  --mado-surface-hover: #f1f5f9;
+  --mado-fg: #0f172a;
+  --mado-fg-muted: #475569;
+  --mado-border: #e2e8f0;
+  --mado-accent: #1d4ed8;
+
+  --mado-radius: 0.625rem;
+
+  --mado-font-body:
+    system-ui, -apple-system, "Segoe UI", Roboto, Helvetica, Arial,
+    sans-serif;
+}
+
+@media (prefers-color-scheme: dark) {
+  :root {
+    --mado-bg: #0b1220;
+    --mado-surface: #111827;
+    --mado-surface-hover: #1f2937;
+    --mado-fg: #e2e8f0;
+    --mado-fg-muted: #94a3b8;
+    --mado-border: #1f2937;
+    --mado-accent: #60a5fa;
+  }
+}

package/starters/default/src/styles.d.ts

@@ -1 +1,3 @@
-declare module "*.css";
+// Allow CSS imports in TS modules. Vite handles the side-effect at
+// build time; the runtime sees a no-op module.
+declare module "*.css";

package/starters/default/src/vite-env.d.ts

@@ -1 +1 @@
-/// <reference types="vite/client" />
+/// <reference types="vite/client" />

package/starters/default/vite.config.ts

@@ -2,7 +2,20 @@ import { defineConfig } from "vite";
 import { mado } from "@madojs/mado/vite";
 
 export default defineConfig({
-  plugins: [mado()],
+  plugins: [
+    mado({
+      // Public origin used to build absolute URLs for static snapshots
+      // (sitemap, canonical, OpenGraph). Combined with Vite's `base`,
+      // the canonical for a route is `site + base + pathname`.
+      //
+      // REQUIRED when any page declares `static`. Set to your deployment
+      // origin (e.g. https://your-app.example) before running
+      // `mado release`. Override per environment via:
+      //   mado release --base-url https://staging.example
+      //   MADO_SITE=https://staging.example mado release
+      // site: "https://your-app.example",
+    }),
+  ],
   css: {
     transformer: "lightningcss",
   },

package/starters/modular/README.md

@@ -0,0 +1,142 @@
+# Mado modular starter
+
+Reference architecture for long-lived modular business applications:
+admin panels, internal tools, SaaS backoffice. The starter ships the
+opinions a team of more than one person will eventually adopt anyway —
+auth shell, guarded zones, module boundaries, HTTP client and
+contracts.
+
+If you are building a website, a landing page, a docs site or any
+small interactive app, prefer the universal starter:
+
+```bash
+mado init my-app                  # universal default
+mado init my-app --starter modular  # this starter
+```
+
+Both starters target the same Mado runtime. They only differ in how
+much structure is pre-created.
+
+## Commands
+
+```bash
+npm install
+npm run dev       # Vite dev server
+npm run build     # Vite production SPA build
+npm run release   # vite build + browser-rendered snapshots → out/
+npm run preview   # serve out/ like a real static host
+```
+
+`npm run release` requires a public origin so it can build absolute
+canonical URLs. Set it once in `vite.config.ts`:
+
+```ts
+mado({ site: "https://your-app.example" })
+```
+
+…or override per environment:
+
+```bash
+mado release --base-url https://staging.example
+```
+
+The public home page is captured as a static document; auth and
+billing surfaces stay SPA-only and are served through the
+`_mado/spa.html` fallback.
+
+## Dev API mock
+
+`vite.config.ts` mounts a tiny in-memory mock for the endpoints used by
+this starter so `npm run dev` is runnable out of the box:
+
+| Method + path                            | Behaviour                                      |
+| ---------------------------------------- | ---------------------------------------------- |
+| `POST /api/auth/login`                   | accepts `demo@mado.dev` / `demo`               |
+| `GET  /api/auth/me`                      | current user (after login)                     |
+| `POST /api/auth/logout`                  | clears the in-memory session                   |
+| `GET  /api/billing/stripe/invoices`      | lists six seeded invoices                      |
+| `GET  /api/billing/stripe/invoices/:id`  | returns a single invoice                       |
+| `POST /api/billing/stripe/invoices/:id/pay` | flips status to `paid`                      |
+
+The mock only runs under `vite dev`, so `mado release` ships a clean
+bundle that talks to your real backend. Disable the mock with
+`MADO_MOCK_API=0` or remove the `devApiMock()` plugin entry.
+
+When you wire up your real backend, mirror the request/response shape
+in `auth.connector.ts` and `stripe.connector.ts`. The contract types in
+`modules/<name>/_contracts/` are the source of truth.
+
+## Shape
+
+```txt
+public/                  static assets copied by Vite
+src/
+  main.ts                imports global CSS and mounts the router
+  app.routes.ts          app map: zones, layouts, guards and modules
+  layouts/               app-zone shells
+  shared/
+    http/                HTTP client and interceptors
+    lib/                 pure utilities
+    styles/              tokens, reset, shell and content CSS
+    ui/                  reusable x-* components
+  modules/               business modules
+    <name>/
+      <name>.routes.ts
+      <name>.public.ts
+      <name>.types.ts
+      pages/
+      data/
+      api/
+      components/
+      _contracts/
+```
+
+## CSS Contract
+
+- `tokens.css` defines CSS custom properties and is safe for Shadow DOM
+  components through `var(...)`.
+- `reset.css` normalizes the document/light DOM surface.
+- `shell.css` styles app-zone layouts from `src/layouts/`.
+- `content.css` styles page-level light DOM: forms, tables, prose and
+  simple states.
+- Reusable leaf components keep their own styles in ``css`...` ``
+  inside `component()` options.
+
+Vite uses Lightning CSS for CSS transforms/minification in this
+starter.
+
+## Internal links
+
+Always emit internal links through `routeUrl()` so they pick up the
+deployed Vite `base` automatically:
+
+```ts
+import { routeUrl } from "@madojs/mado";
+
+html`<a data-link href=${routeUrl("/billing/invoices")}>Invoices</a>`
+```
+
+The router only intercepts anchors that opt in with `data-link`; bare
+`<a href>` falls through to a full document load.
+
+## Generate files
+
+```bash
+npm run new -- module billing
+npm run new -- page billing/pages/invoices-list
+npm run new -- connector billing/api/stripe
+npm run new -- resource billing/data/invoices
+npm run new -- service billing/cart
+npm run new -- form billing/invoice
+npm run new -- component billing/components/invoice-status-badge
+npm run new -- guard billing/billing
+npm run new -- layout admin-shell
+```
+
+The generator writes files only. Wire new routes in
+`src/app.routes.ts` or the module route map by hand.
+
+## More
+
+The full architecture guide lives in the framework docs:
+https://github.com/madojs/mado/tree/main/docs/en

package/starters/modular/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <link rel="icon" href="/favicon.svg" />
+    <title>Mado App</title>
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>

package/starters/modular/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "__APP_NAME__",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "mado dev",
+    "build": "mado build",
+    "typecheck": "mado typecheck",
+    "test": "npm run typecheck && npm run lint",
+    "release": "mado release",
+    "preview": "mado preview",
+    "lint": "eslint \"src/**/*.ts\"",
+    "lint:fix": "eslint \"src/**/*.ts\" --fix",
+    "new": "mado new"
+  },
+  "dependencies": {
+    "@madojs/mado": "__MADOJS_VERSION__"
+  },
+  "devDependencies": {
+    "@typescript-eslint/eslint-plugin": "^8.0.0",
+    "@typescript-eslint/parser": "^8.0.0",
+    "eslint": "^9.0.0",
+    "eslint-plugin-boundaries": "^5.0.0",
+    "lightningcss": "^1.32.0",
+    "playwright-core": "^1.47.0",
+    "typescript": "^5.5.0",
+    "vite": "^8.0.16"
+  }
+}

package/starters/modular/src/app.routes.ts

@@ -0,0 +1,39 @@
+// Single source of truth for the application route table.
+//
+// This file is the APP MAP. Reading it = understanding the app.
+//
+// One rule:
+//   Modules export plain `routes` maps. The choice of SHELL and GUARD for
+//   each zone of the app is made HERE, by wrapping a module's routes with
+//   a `layout({...})` block.
+//
+// `manifest` is exported separately so `mado static` can discover pages that
+// declare `static`.
+
+import { layout, routes } from "@madojs/mado";
+
+import { requireAuth } from "./modules/auth/auth.public";
+import { authRoutes } from "./modules/auth/auth.routes";
+import { billingRoutes } from "./modules/billing/billing.routes";
+
+export const manifest = {
+  // Public landing (no shell, no guard).
+  "/": () => import("./modules/home/home.page"),
+
+  // AUTH ZONE — centered card, no guard.
+  "/login": layout({
+    layout: () => import("./layouts/auth-shell.layout"),
+    routes: authRoutes,
+  }),
+
+  // APP ZONE — header + nav, guarded by requireAuth.
+  "/billing": layout({
+    layout: () => import("./layouts/app-shell.layout"),
+    guard: requireAuth,
+    routes: billingRoutes,
+  }),
+
+  "*": () => import("./modules/home/not-found.page"),
+};
+
+export default routes(manifest);

package/starters/{default → modular}/src/layouts/app-shell.layout.ts

@@ -9,27 +9,30 @@
 //
 // Layouts live in src/layouts/ because they describe APP ZONES, not domains.
 
-import { html, page } from "@madojs/mado";
+import { html, page, routeUrl } from "@madojs/mado";
 
 import { isAuthed, logout, user } from "../modules/auth/auth.public";
 import "../shared/ui/x-button.component";
 
 export default page({
   title: "Mado App",
+  // Every internal anchor uses `data-link` + `routeUrl()` so SPA
+  // navigation intercepts the click and the href stays correct under
+  // any Vite `base` (e.g. deploying the app under `/admin/`).
   view: ({ child }) => html`
     <div class="layout layout--app">
       <header class="app-header">
-        <a href="/" class="brand">Mado App</a>
+        <a data-link href=${routeUrl("/")} class="brand">Mado App</a>
         <nav>
-          <a href="/billing/invoices">Invoices</a>
+          <a data-link href=${routeUrl("/billing/invoices")}>Invoices</a>
           ${() =>
             isAuthed()
               ? html`<span class="who">${() => user()?.email ?? ""}</span>
                   <x-button variant="ghost" @click=${logout}>Sign out</x-button>`
-              : html`<a href="/login">Sign in</a>`}
+              : html`<a data-link href=${routeUrl("/login")}>Sign in</a>`}
         </nav>
       </header>
       <main class="app-main">${child}</main>
     </div>
   `,
-});
+});

package/starters/{default → modular}/src/layouts/auth-shell.layout.ts

@@ -4,14 +4,14 @@
 // auth ZONE. If tomorrow a `password-reset` module appears, it will reuse
 // this same shell.
 
-import { html, page } from "@madojs/mado";
+import { html, page, routeUrl } from "@madojs/mado";
 
 export default page({
   title: "Sign in",
   view: ({ child }) => html`
     <div class="layout layout--auth">
-      <a href="/" class="brand">Mado App</a>
+      <a data-link href=${routeUrl("/")} class="brand">Mado App</a>
       <main class="auth-main">${child}</main>
     </div>
   `,
-});
+});