@madojs/mado 0.11.1 → 0.12.0

package/docs/en/14-forms.md

@@ -0,0 +1,244 @@
+# Forms
+
+> `useForm()` is a thin signal-wrapper around native HTML5 form
+> validation. For 90% of cases you write a `<form>`, attach
+> `onInput / onBlur / onSubmit` and you are done.
+
+```ts
+import { html, page, useForm } from "@madojs/mado";
+
+export default page({
+  view: () => {
+    const f = useForm({
+      email: { required: true, type: "email" },
+      age:   { required: true, type: "number", min: 18 },
+    });
+
+    return html`
+      <form @submit=${f.onSubmit(async (v) => { await api.save(v); f.reset(); })}>
+        <input name="email" type="email"
+               @input=${f.onInput} @blur=${f.onBlur} />
+        ${() =>
+          f.touched().email && f.errors().email
+            ? html`<small class="err">${f.errors().email}</small>`
+            : null}
+
+        <input name="age" type="number" @input=${f.onInput} />
+
+        <button ?disabled=${() => !f.isValid() || f.submitting()}>Save</button>
+      </form>
+    `;
+  },
+});
+```
+
+## The signals it exposes
+
+| Reader                 | Value                                                            |
+| ---------------------- | ---------------------------------------------------------------- |
+| `f.values()`           | object of current field values                                   |
+| `f.errors()`           | object of `field → error string` (validators + HTML5 constraints)|
+| `f.touched()`          | object of `field → boolean` (true after first blur)              |
+| `f.isValid()`          | true when `errors()` is empty                                    |
+| `f.submitting()`       | true while the `onSubmit` async handler is running               |
+| `f.dirty()`            | true when any value differs from initial                         |
+
+Writers: `f.setValue(name, v)`, `f.setError(name, msg)`,
+`f.reset(values?)`, `f.touch(name)`.
+
+## Schema
+
+The schema mirrors HTML5 constraints, with a few extras:
+
+```ts
+useForm({
+  email:    { required: true, type: "email" },
+  age:      { type: "number", min: 18, max: 120 },
+  name:     { required: true, minLength: 2, maxLength: 80 },
+  website:  { type: "url" },
+  tags:     { custom: (v) => Array.isArray(v) && v.length > 0 ? null : "pick at least one" },
+});
+```
+
+For cross-field or async rules use `validate`:
+
+```ts
+useForm({
+  password: { required: true, minLength: 8 },
+  confirm:  { required: true },
+}, {
+  validate: (values) =>
+    values.password !== values.confirm
+      ? { confirm: "passwords do not match" }
+      : null,
+});
+```
+
+Return `null` (everything is valid) or a partial `field → error`
+object.
+
+## Field arrays
+
+```ts
+const f = useForm({ tags: { custom: (v) => v.length > 0 ? null : "required" } });
+const tags = f.fieldArray<string>("tags");
+
+tags.append("rust");
+tags.remove(0);
+tags.move(0, 2);
+tags.items();   // current array (signal)
+```
+
+## With `mutation()`
+
+Forms compose with `mutation()` for typed write-paths:
+
+```ts
+import { mutation, navigate } from "@madojs/mado";
+
+const save = mutation((u: User) => api.save(u), {
+  invalidates: ["/api/users*"],
+});
+
+// inside view()
+const f = useForm({ name: { required: true } });
+return html`
+  <form @submit=${f.onSubmit(async (v) => {
+    await save.run(v);
+    navigate("/users");
+  })}>
+    <input name="name" @input=${f.onInput} />
+    <button ?disabled=${() => !f.isValid() || save.loading()}>Create</button>
+    ${() => save.error() ? html`<p class="err">${save.error()!.message}</p>` : null}
+  </form>
+`;
+```
+
+`save.loading()` reflects the request; `f.submitting()` reflects the
+`onSubmit` handler runtime. Usually only one of them is interesting.
+
+## Shadow DOM inputs — when you need them
+
+Most apps build forms from native `<input>` / `<select>` /
+`<textarea>` directly inside the `<form>`. `useForm()` reads
+`e.target.name` and `e.target.value` on the events, which works
+out-of-the-box for native controls.
+
+You only need a custom Web Component when the input has its own
+shadow tree (a date picker, a tag editor, a rich text field, …). Two
+browser-level facts make that path slightly different:
+
+1. **Event retargeting** — events that bubble out of an open shadow
+   root have their `target` retargeted to the host. `useForm()` reads
+   `e.target.name` and `e.target.value` — the host element must
+   expose both.
+2. **Form association** — a `<button type="submit">` inside a shadow
+   root is NOT part of the form-owner algorithm. Clicking it does
+   not submit the surrounding `<form>`.
+
+The two patterns below cover both. Reach for them **only** if a real
+custom input forces you to. For everything else, see "Light-DOM
+inputs" further down.
+
+### Custom input — proxy `name` / `value`
+
+```ts
+import { component, html } from "@madojs/mado";
+
+component("x-input", ({ host, attr }) => {
+  const type = attr("type", "text");
+
+  // After Shadow DOM retargets e.target from the inner <input> to
+  // <x-input>, useForm reads e.target.name / e.target.value. These
+  // getters bridge the gap.
+  Object.defineProperty(host, "name", {
+    get: () => host.getAttribute("name") ?? "",
+    configurable: true,
+  });
+  Object.defineProperty(host, "value", {
+    get: () => host.shadowRoot?.querySelector("input")?.value ?? "",
+    set: (v: string) => {
+      const input = host.shadowRoot?.querySelector("input");
+      if (input) input.value = v;
+    },
+    configurable: true,
+  });
+
+  return () => html`<input type=${type} />`;
+});
+```
+
+The inner `input` event already bubbles through the shadow boundary
+(`composed: true` by default), so `<form @input=${f.onInput}>` keeps
+working.
+
+### Custom submit button — `requestSubmit()`
+
+```ts
+import { component, html } from "@madojs/mado";
+
+component("x-button", ({ host, attr }) => {
+  const disabled = attr("disabled");
+
+  const onClick = () => {
+    const t = host.getAttribute("type");
+    if (t === "button" || t === "reset") return;
+    if (host.hasAttribute("disabled")) return;
+    host.closest("form")?.requestSubmit();
+  };
+
+  return () => html`
+    <button ?disabled=${() => disabled() !== ""} @click=${onClick}>
+      <slot></slot>
+    </button>
+  `;
+});
+```
+
+`host.closest("form")` works because the host itself lives in the
+light DOM. `requestSubmit()` triggers HTML5 validation and the
+`submit` event exactly like a native click.
+
+### Light-DOM input — the simpler alternative
+
+If a custom element is just a styled wrapper around a native control
+and does not need style encapsulation, use `{ shadow: false }`. The
+native `<input>` is then part of the document; no retargeting, no
+proxy properties, no submit bridge.
+
+```ts
+component(
+  "x-field",
+  ({ attr }) => {
+    const label = attr("label", "");
+    return () => html`
+      <label>
+        <span>${label}</span>
+        <slot></slot>
+      </label>
+    `;
+  },
+  { shadow: false },
+);
+```
+
+This is the only situation where `shadow: false` is the recommended
+default — and even then a `page()` is usually a better fit if the
+wrapper is layout-shaped rather than reusable.
+
+## Summary
+
+| Concern                    | Native form                          | Custom component with Shadow DOM         |
+| -------------------------- | ------------------------------------ | ----------------------------------------- |
+| `useForm` integration      | works out of the box                 | proxy `name` / `value` on the host        |
+| Submit button              | `<button type="submit">` works       | `host.closest("form")?.requestSubmit()`   |
+| Reactive attributes        | not needed                           | `ctx.attr(name)` returns a Signal         |
+| Style encapsulation        | global CSS                           | Shadow DOM CSS via `css\`\``              |
+
+## Further reading
+
+- [10-pages-and-components.md](./10-pages-and-components.md) — when
+  to reach for `component({ shadow: false })`.
+- [13-data.md](./13-data.md) — `mutation()` for typed writes.
+- [21-error-handling.md](./21-error-handling.md) — surfacing form
+  errors from network failures.

package/docs/en/15-static-snapshots.md

@@ -0,0 +1,181 @@
+# Static snapshots (`mado static`)
+
+> Browser-rendered static HTML for SEO and first paint. No SSR, no
+> hydration, no template-language bake.
+
+`mado static` is a *snapshot capture*: at release time Mado runs your
+app in a real headless Chromium, lets the page render to the DOM
+(including any Shadow DOM), then serialises the result — Declarative
+Shadow DOM and all — to one HTML file per route. On first paint the
+live SPA atomically replaces the static tree; there is no hydration
+protocol and no node reconciliation.
+
+It is the right tool for content that is the same for every visitor:
+public landing pages, product / catalogue pages, documentation, blog
+posts. It is intentionally **not** an SSR runtime for personalised
+data.
+
+## When `static` is suitable
+
+- Public pages with a single canonical representation per URL.
+- Pages whose data is known at build time (CMS dump, file system,
+  Markdown, JSON, build-time API call).
+- Pages that need to appear fully rendered in `view-source:`, in
+  social preview crawlers, and to JS-disabled clients.
+- First paint of a page that *later* upgrades into a live SPA route.
+
+## When `static` is **not** suitable
+
+- Personalised content per visitor (auth, geo, A/B). The capture sees
+  one DOM and would ship it to everyone.
+- Real-time data (chat, dashboards, prices). The snapshot is frozen
+  the moment of capture.
+- Routes behind guards. Static pages are public by definition; the
+  discovery pipeline refuses to capture guarded routes.
+
+For those cases keep the route SPA-only — Mado still serves a clean
+`_mado/spa.html` fallback for them.
+
+## Declaring a static page
+
+A page opts in through the `static` field on `page({ ... })`. Two
+shapes are accepted:
+
+```ts
+// Single static page (no params)
+import { html, page } from "@madojs/mado";
+
+export default page({
+  static: true,
+  title: "Pricing",
+  head: () => ({ description: "Plans and pricing." }),
+  view: () => html`<main><h1>Pricing</h1></main>`,
+});
+```
+
+```ts
+// Dynamic static route — one capture per `paths()` entry
+import { html, page } from "@madojs/mado";
+
+export default page<{ slug: string }, Guide>({
+  static: {
+    paths: async () => guides.map((g) => ({ slug: g.slug })),
+    initialData: async ({ slug }) => loadGuide(slug),
+  },
+  title: ({ slug }) => guides.find((g) => g.slug === slug)?.title ?? slug,
+  head: ({ slug }, seed) => ({
+    description: seed?.summary ?? "",
+  }),
+  view: (ctx) => html`<article>${ctx.data.body}</article>`,
+});
+```
+
+The seed produced by `initialData()` is JSON-serialised into the
+captured HTML as `<script type="application/json" data-mado-static-data="…">`.
+On first client boot Mado consumes it once so `page.load()` and
+`page.head()` see the same data the snapshot saw — no extra fetch.
+
+## Running
+
+In normal use `mado static` is invoked through `mado release`:
+
+```bash
+mado release          # vite build + mado static + deployment files
+mado preview          # serve out/ like a real static host
+```
+
+You can also invoke `mado static` on its own (for tighter loops in
+CI), but it operates on the existing `out/` artefact produced by
+`vite build`, so the canonical command is `release`.
+
+A public origin is required so static documents carry absolute
+canonical URLs. Set it in `vite.config.ts`:
+
+```ts
+import { defineConfig } from "vite";
+import { mado } from "@madojs/mado/vite";
+
+export default defineConfig({
+  plugins: [mado({ site: "https://your-app.example" })],
+});
+```
+
+…or override per run:
+
+```bash
+mado release --base-url https://staging.example
+MADO_SITE=https://staging.example mado release
+```
+
+## What the generated HTML contains
+
+For every captured route:
+
+- The full rendered light DOM.
+- Every open shadow root serialised through Declarative Shadow DOM
+  (`<template shadowrootmode="open">`).
+- Adopted stylesheets materialised into `<style>` tags inside the
+  shadow root.
+- A `<link rel="canonical">` and `<meta property="og:url">` derived
+  from `site + base + pathname` (if the page did not declare its own).
+  Both are marked `data-mado-head="static"` so the runtime `applyHead`
+  removes them on SPA navigation into a page without explicit head
+  metadata.
+- The seed `<script type="application/json" data-mado-static-data="…">`
+  for routes that declared `initialData()`.
+- Vite assets resolved through the active `base`.
+
+`<form>`, `<input>`, `<select>`, `<textarea>` and `<details>` state
+is serialised through attributes so a JS-disabled browser sees the
+same shape the snapshot captured.
+
+## Constraints and gotchas
+
+- **`paths()` and `initialData()` run during discovery AND ship in the
+  client bundle.** Keep them browser-safe. Never read secrets, never
+  call private services.
+- **Static pages cannot use guards** — route-level or layout-level.
+- **Wildcard routes (`*`) cannot be static.** They are the SPA
+  fallback.
+- **A compatible Chromium is required.** CI should install it through
+  Playwright:
+  ```bash
+  npx playwright install --with-deps chromium
+  ```
+  …or via the framework's installed `playwright-core` for revision
+  parity:
+  ```bash
+  node node_modules/playwright-core/cli.js install --with-deps chromium
+  ```
+- **Capture is strict by default.** Any failed fetch (script, style,
+  resource(), custom element definition) fails the snapshot. A small
+  allow-list covers `/favicon.ico`, `/favicon.svg`, `/robots.txt`
+  and `data:` URLs.
+- **All network calls happen against an internal capture server** that
+  serves the freshly built `out/` tree. There is no real network at
+  capture time.
+
+## Comparison
+
+| Approach                              | Mado static snapshot |
+| ------------------------------------- | -------------------- |
+| Next-style SSR + hydration            | not used             |
+| Astro-style island runtime            | not used             |
+| Build-time HTML from templates only   | not used             |
+| Browser-rendered DOM + DSD + takeover | **used**             |
+
+The result is a plain HTML file. Search engines, social preview
+crawlers and `curl` see exactly what your app renders on first paint;
+no JavaScript step is required to make the document meaningful.
+
+## Cookbook
+
+Concrete recipes for blog, product catalogue, documentation site and
+multi-locale builds live in [23-cookbook.md](./23-cookbook.md).
+
+## TL;DR
+
+- Declare `static: true | { paths, initialData }` on `page({ ... })`.
+- Run `mado release`.
+- Ship `out/` to any static host.
+- The live SPA takes over atomically on first paint.

package/docs/en/{10-app-architecture.md → 16-app-architecture.md}

@@ -4,7 +4,58 @@ The official starter is the canonical production shape for Mado apps. It is
 not a demo architecture and not a framework inside the framework: it is plain
 files, imports, Mado primitives, and ESLint boundaries.
 
-## File Tree
+## Project layout (universal starter)
+
+Both starters share the same top-level shape. The universal starter is the
+minimum:
+
+```
+my-app/
+├── package.json              # exactly one runtime dep: @madojs/mado
+├── tsconfig.json             # strict TS, ES2022, Bundler resolution
+├── vite.config.ts            # mado() from @madojs/mado/vite
+├── index.html                # Vite entry + SPA shell
+├── public/                   # static assets (favicons, images, robots.txt)
+└── src/
+    ├── main.ts               # entry: mount router into #app
+    ├── app.routes.ts         # one app map (default + named `manifest`)
+    ├── pages/                # *.page.ts files
+    ├── components/           # reusable <x-tag> components
+    └── shared/               # http/, lib/, styles/, ui/
+```
+
+`index.html` belongs at the project root because Vite treats it as an entry
+template, not a static public file. Put only copy-as-is files in `public/`.
+
+### The three artifact states
+
+| Folder    | What it is                                                  | Who writes      | Who reads               | Deploy?       |
+| --------- | ----------------------------------------------------------- | --------------- | ----------------------- | ------------- |
+| `src/`    | your TypeScript source                                      | you             | Vite, `tsc --noEmit`    | ❌ no          |
+| `public/` | static assets copied as-is                                  | you             | Vite build              | ✅ via `out/` |
+| `out/`    | **the deploy artifact**: SPA shell + assets + snapshots     | `mado release`  | nginx / CDN / CF Pages  | ✅ **yes**    |
+
+One-liner: develop with `mado dev`, ship with `mado release`, upload `out/`.
+
+### Naming rules
+
+| What                       | Style              | Example                |
+| -------------------------- | ------------------ | ---------------------- |
+| File                       | kebab-case         | `user-profile.ts`      |
+| Component tag              | `x-` + kebab       | `<x-user-profile>`     |
+| Context                    | PascalCase + `Ctx` | `ThemeCtx`, `AuthCtx`  |
+| Signal                     | camelCase          | `userId`, `isLoggedIn` |
+| Page-internal element      | `x-<route>-page`   | `<x-posts-page>`       |
+
+### What does NOT belong in `src/`
+
+- ❌ Build-tool configs beyond `vite.config.ts` with `mado()`.
+- ❌ `.env` files — read env in `src/shared/lib/config.ts` from
+  `import.meta.env` and import that one module everywhere.
+- ❌ Tests mixed with code — put them in `test/`.
+- ❌ `examples/` folder — keep large demos outside the app repo.
+
+## File tree (modular reference starter)
 
 ```txt
 src/
@@ -68,7 +119,7 @@ export default routes(manifest);
 
 Rules:
 
-- Export `manifest` so `mado bake` can discover bakeable pages.
+- Export `manifest` so `mado static` can discover bakeable pages.
 - Modules never call `layout()`.
 - Layouts describe app zones, not domains.
 - Do not hide the router inside a custom element or a second shell in

package/docs/en/{13-deployment.md → 20-deployment.md}

@@ -8,11 +8,12 @@
 
 ```
 out/
-├── index.html              ← SPA shell or baked HTML for /
+├── index.html              ← captured snapshot for / (or SPA shell)
 ├── assets/                 ← Vite hashed assets
 │   ├── *.gz                ← precompressed gzip (gzip_static / Accept-Encoding)
 │   └── *.br                ← precompressed brotli (brotli_static / Accept-Encoding)
-├── <route>/index.html      ← prerendered SEO HTML for baked routes
+├── <route>/index.html      ← captured snapshot per static route
+├── _mado/spa.html          ← SPA fallback shell (noindex)
 ├── sitemap.xml             ← generated sitemap
 ├── favicon.svg             ← your public/ assets copied verbatim
 ├── _redirects              ← Cloudflare Pages / Netlify SPA fallback
@@ -89,8 +90,9 @@ Build command:    npm ci && npx mado release
 Output directory: out
 ```
 
-For catalogs too big to bake at build time, keep edge prerender experiments in
-the external examples workspace rather than in the core package.
+For catalogs too big to snapshot at release time, keep on-demand snapshot
+experiments in the external examples workspace rather than in the core
+package.
 
 ---
 
@@ -182,10 +184,57 @@ jobs:
 - **`/assets/*` files change but the browser keeps the old one.** They
   should not — the filename is hashed by Vite during `mado release`. If you bypassed
   build and shipped your own unhashed JS, give it a hash or short cache.
-- **Baked SEO page shows `[object Object]`.** Should never happen after the
-  v1 bake update — bake now raises a loud error in that case. If you see it,
-  upgrade `@madojs/mado` and re-run `mado bake`.
+- **Captured snapshot shows `[object Object]`.** `mado static` rejects
+  non-JSON-serialisable seeds at build time and points at the bad
+  field. If you still see it, upgrade `@madojs/mado` and re-run
+  `mado release`.
+
+## Sub-path deployments and `base`
+
+A deployment under a sub-path (`https://your.site/docs/`, GitHub
+Pages project URL, an admin panel mounted under `/admin/`, …) only
+requires two changes:
+
+```ts
+// vite.config.ts
+import { defineConfig } from "vite";
+import { mado } from "@madojs/mado/vite";
+
+export default defineConfig({
+  base: "/docs/",                       // ← active prefix
+  plugins: [mado({ site: "https://your.site" })],
+});
+```
+
+Then make every internal anchor go through `routeUrl()` + `data-link`
+so the URL is correct under any base:
+
+```ts
+import { html, routeUrl } from "@madojs/mado";
+
+html`<a data-link href=${routeUrl("/")}>Home</a>`;     // → "/docs/"
+html`<a data-link href=${routeUrl("/guides/intro")}>Intro</a>`;
+```
+
+`mado release` honours `base` end-to-end:
+
+- captured snapshots load assets through `/docs/assets/...`;
+- sitemap URLs are `https://your.site/docs/...`;
+- canonicals and `og:url` include the prefix;
+- `mado preview` redirects bare `/` to `/docs/` and serves SPA
+  fallback under `/docs/<anything>`.
+
+On the production host:
+
+- **nginx** — keep `try_files $uri $uri/ /index.html;` but mount the
+  app under the matching prefix (`location /docs/ { ... }`).
+- **Cloudflare Pages / Netlify** — `_redirects` is generated with the
+  base prefix already baked in.
+- **GitHub Pages (project site)** — set `base: "/<repo>/"` and use
+  the `gh-pages` deploy path; canonical URLs land at
+  `https://<user>.github.io/<repo>/...`.
 
-See also: [`02-project-layout.md`](./02-project-layout.md) for the
-`src/`/`public/`/`out/` model and [`03-static-bake.md`](./03-static-bake.md)
-for the SEO bake mechanics.
+See also: [`16-app-architecture.md`](./16-app-architecture.md) for the
+`src/` / `public/` / `out/` model and
+[`15-static-snapshots.md`](./15-static-snapshots.md) for the static
+snapshot mechanics.

package/docs/en/{14-testing.md → 22-testing.md}

@@ -48,7 +48,7 @@ Test behavior, not internal implementation details:
 - route guards, redirects, scroll/focus behavior, error boundaries;
 - forms: validation, async validation races, field arrays;
 - resources/mutations: cache keys, invalidation, lifecycle cleanup;
-- CLI flows: `mado release`, `mado bake`, `mado preview`.
+- CLI flows: `mado release`, `mado static`, `mado preview`.
 
 ## Browser smoke tests
 
@@ -74,9 +74,10 @@ services from framework tests. For app tests, make the API client injectable via
 npm run typecheck
 npm run build
 npm test
-npm run bake
+npm run release
 ```
 
-`mado release` runs the production path for an app: typecheck, Vite build,
-bake, compression and deploy helper files. In the framework repository,
-`npm run build` still emits `dist/src` for package tests and publishing.
+`mado release` runs the production path for an app: typecheck, Vite
+build, static-snapshot capture, compression and deploy helper files.
+In the framework repository, `npm run build` still emits `dist/src`
+for package tests and publishing.