@madojs/mado 0.11.0 → 0.12.0

package/docs/en/13-data.md

@@ -0,0 +1,225 @@
+# Data
+
+> `resource()` reads, `mutation()` writes, `jsonFetcher()` shapes
+> the wire. Backends, auth and modules all sit on top of this layer.
+
+Mado does not ship a generic HTTP client because the browser already
+has one. Instead it ships two small primitives that wrap `fetch()`
+into a cache + lifecycle:
+
+- `resource()` — keyed cache, loading / error / data signals, glob
+  invalidation, automatic cleanup.
+- `mutation()` — async action runner with the same loading / error /
+  data signals, plus declarative invalidation of related resources.
+
+A third helper, `jsonFetcher()`, is the default body parser: parses
+JSON, throws `HttpError` on `!ok`.
+
+## `resource()`
+
+```ts
+import { resource, jsonFetcher } from "@madojs/mado";
+
+const userId = signal(1);
+
+const user = resource(
+  () => `/api/users/${userId()}`,   // key (reactive — recomputed on change)
+  jsonFetcher<User>(),               // how to load
+  { staleTime: 60_000 },             // cache age
+);
+
+user.data();    // User | undefined
+user.error();   // Error | null
+user.loading(); // boolean
+
+await user.refresh();
+user.mutate((u) => (u ? { ...u, name: "patched" } : u));
+```
+
+Rules:
+
+- The key is the cache identity. Same key → shared cache and shared
+  in-flight request, even across components.
+- Distinct data needs distinct keys. Encode query params, auth scope
+  and tenant in the key string itself.
+- `staleTime` is "how long after a successful fetch the cached value
+  is reused without a re-fetch". `0` means "always re-fetch on
+  remount".
+- `resource()` inside a `component()` / `page()` cleans itself up
+  when the host leaves the DOM.
+
+## `mutation()`
+
+```ts
+import { mutation } from "@madojs/mado";
+
+const save = mutation<User, User>(
+  (u) =>
+    fetch("/api/users", {
+      method: "POST",
+      body: JSON.stringify(u),
+    }).then((r) => r.json()),
+  { invalidates: ["/api/users*"] },
+);
+
+await save.run(newUser);   // throws on failure
+save.loading();            // true while ANY run is in flight
+save.error();              // last failure
+save.data();               // last success
+```
+
+- `run()` is concurrent by default. `loading()` stays true while any
+  run is in flight. Use `{ abortPrevious: true }` for
+  search-as-you-type ("latest request wins").
+- `invalidates` runs after a successful mutation and is best-effort:
+  invalidation failures are logged but do not turn the mutation
+  itself into a failure.
+- `invalidates` may also be a function of `(result, args)` for
+  dynamic keys.
+
+## `jsonFetcher()` and `HttpError`
+
+```ts
+import { jsonFetcher, HttpError, resource } from "@madojs/mado";
+
+const me = resource(() => "/api/auth/me", jsonFetcher<User>());
+
+try {
+  await me.refresh();
+} catch (err) {
+  if (err instanceof HttpError && err.status === 401) {
+    navigate("/login");
+  } else throw err;
+}
+```
+
+`HttpError` carries `status`, `url` and the parsed body (JSON when
+possible, raw text otherwise). Use it for typed handling in pages
+and guards.
+
+## Modular shape — connector → resource → page
+
+The modular starter encodes one rule per layer; every business
+module follows the same flow:
+
+```
+connector  →  resource / mutation  →  page
+```
+
+```
+src/shared/http/
+  http-client.ts        # one fetch wrapper + query/body/error handling
+  http-error.ts         # HttpError type
+  interceptors.ts       # request/response hooks (auth header, retry, …)
+
+src/modules/<name>/
+  <name>.connector.ts   # external API contract, DTO -> domain
+  <name>.resource.ts    # resource()/mutation() with cache keys
+  <name>.types.ts       # domain types
+  pages/                # page()s — UI only
+  _contracts/           # backend DTO shapes, private to the connector
+```
+
+Hard rules:
+
+- Pages **never** import DTOs and **never** call `fetch()`.
+- Connectors **never** import signals, resources, html, components,
+  pages or services.
+- Public surface of a module is `<name>.public.ts`. Anything not
+  re-exported there is private.
+
+The universal starter does not insist on this layering — for a small
+app a single `src/lib/api.ts` is enough. Use the modular shape when
+the app grows enough that "which file owns this fetch?" becomes a
+real question.
+
+## Auth — service + guard
+
+Auth state is an ES-module singleton built from the same primitives:
+
+```ts
+// src/modules/auth/auth.service.ts
+import { computed, signal } from "@madojs/mado";
+import { authApi } from "./auth.connector";
+import type { Credentials, User } from "./auth.types";
+
+const _user  = signal<User | null>(null);
+const _token = signal<string | null>(null);
+
+export const user      = (): User | null => _user();
+export const isAuthed  = computed(() => _user() !== null);
+
+export async function login(creds: Credentials): Promise<void> {
+  const res = await authApi.login(creds);
+  _token.set(res.token);
+  _user.set(res.user);
+}
+
+export async function logout(): Promise<void> {
+  try { await authApi.logout(); } catch { /* best effort */ }
+  _token.set(null);
+  _user.set(null);
+}
+```
+
+Expose only what other modules need through `auth.public.ts`.
+
+The guard is a plain function returning `true | false | string`:
+
+```ts
+// src/modules/auth/auth.guard.ts
+import { isAuthed } from "./auth.service";
+
+export function requireAuth(): boolean | string {
+  return isAuthed() ? true : "/login";
+}
+```
+
+Mount it in `src/app.routes.ts`:
+
+```ts
+"/billing": layout({
+  layout: () => import("./layouts/app-shell.layout"),
+  guard:  requireAuth,
+  routes: billingRoutes,
+}),
+```
+
+Full guard contract: [12-routing.md](./12-routing.md#guards).
+
+## Dev proxy
+
+Configure backend proxying in `vite.config.ts`:
+
+```ts
+import { defineConfig } from "vite";
+import { mado } from "@madojs/mado/vite";
+
+export default defineConfig({
+  plugins: [mado()],
+  server: {
+    proxy: { "/api": "http://localhost:3000" },
+  },
+});
+```
+
+The modular starter ships a dev-only in-memory mock for `/api/auth/*`
+and `/api/billing/*` (`MADO_MOCK_API=0` to disable). Remove it once
+your real backend is wired.
+
+## Rule of thumb
+
+- `shared/http` knows HTTP.
+- `*.connector.ts` knows one external system and one DTO shape.
+- `*.resource.ts` knows cache keys and invalidation.
+- `*.page.ts` knows UI.
+- `*.public.ts` is the only cross-module surface.
+
+## Further reading
+
+- [12-routing.md](./12-routing.md) — guards, layouts, `routeUrl`.
+- [14-forms.md](./14-forms.md) — `useForm()`, then `mutation().run()`.
+- [21-error-handling.md](./21-error-handling.md) — route / data /
+  action error boundaries.
+- [16-app-architecture.md](./16-app-architecture.md) — the modular
+  starter shape end-to-end.

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.