@madojs/mado 0.11.0 → 0.12.0

package/docs/en/10-pages-and-components.md

@@ -0,0 +1,271 @@
+# Pages and Components
+
+> Mado has exactly two primitives. You decide which one to use by
+> looking at the URL bar, not at the DOM tree.
+
+This is the document that removes the most common Mado design
+question. By the end of it you should never again have to think
+"should this be a page or a component?", "should this be Shadow DOM
+or Light DOM?", or "how do I share styles across components?". You
+just write the thing.
+
+---
+
+## The one rule
+
+| If the unit is…                                          | Use         |
+| -------------------------------------------------------- | ----------- |
+| Something the URL points to (a route, a layout, a 404)   | `page()`    |
+| Something you would copy-paste under multiple URLs       | `component()` |
+
+That's it. Pages are the URLs your app exposes. Components are
+re-usable Web Components.
+
+A page can render any number of components. A component can never
+participate in routing. Pages live in `src/pages/` (universal
+starter) or in `src/modules/<name>/pages/` (modular starter).
+Components live in `src/components/` or `src/modules/<name>/components/`.
+
+You **never** wrap a page in `component()` — that breaks form
+participation, shared CSS and the static snapshot capture. You
+**never** route to a `component()` — only `page()` shows up in the
+router manifest.
+
+---
+
+## You write the same TypeScript either way
+
+```ts
+import { html, page, signal } from "@madojs/mado";
+
+// PAGE — has a URL, owns route + load + head + view
+export default page({
+  title: "Counter",
+  view: () => {
+    const n = signal(0);
+    return html`
+      <main>
+        <h1>Counter</h1>
+        <button @click=${() => n.set(n() + 1)}>Clicks: ${n}</button>
+      </main>
+    `;
+  },
+});
+```
+
+```ts
+import { component, css, html, signal } from "@madojs/mado";
+
+// COMPONENT — reusable, has no URL
+component(
+  "x-counter",
+  () => {
+    const n = signal(0);
+    return () => html`
+      <button @click=${() => n.set(n() + 1)}>Clicks: ${n}</button>
+    `;
+  },
+  { styles: css`button { padding: .5rem 1rem; }` },
+);
+```
+
+Same signals. Same `html\`\`` templates. Same lifecycle. Same data
+model (`resource()`, `mutation()`, `useForm()`, `effect()`). The
+only thing that changes is *where* the DOM lives.
+
+---
+
+## What changes under the hood
+
+| Property                                       | `page()`     | `component()` (default)        |
+| ---------------------------------------------- | ------------ | ------------------------------ |
+| DOM location                                   | Light DOM    | Open Shadow DOM                |
+| Sees global CSS (`shell.css`, `content.css`)   | Yes          | No (Shadow boundary)           |
+| Can use `<slot>`                               | No (uses `child`) | Yes                       |
+| Participates in a parent `<form>`              | Yes          | Only via `attachInternals()` or `shadow:false` |
+| Is captured by `mado static`                   | If `static: true \| { ... }` | Yes (DSD serialised) |
+| Has a hyphenated custom-element tag            | No           | Yes (`x-foo`, `my-bar`)        |
+| Owns its own CSS isolation                    | No           | Yes (via `css\`\``)            |
+
+That is the entire decision matrix. Anything beyond it is detail.
+
+---
+
+## `{ shadow: false }` — the only escape hatch you need
+
+Sometimes a custom element MUST live in the light DOM. Two real
+cases:
+
+1. **Form participation without `attachInternals()`.** A custom
+   input that should be submitted as part of a regular `<form>` and
+   whose author does not want to wire up `ElementInternals`.
+2. **Host-level CSS that the document must address by tag name**
+   (rare; usually solved by passing class attributes instead).
+
+For both, declare `{ shadow: false }`:
+
+```ts
+component(
+  "x-custom-input",
+  () => () => html`<input name="email" />`,
+  { shadow: false, styles: css`x-custom-input input { width: 100%; }` },
+);
+```
+
+That is the *only* place this option is justified. If you reach for
+`shadow: false` because you want to share document-level CSS classes,
+**stop** — you wanted a `page()`, not a component.
+
+Page-shaped wrappers (layouts, route shells) are written with
+`page({ view: ({ child }) => ... })`. They are not components.
+
+---
+
+## Decision table
+
+| You are writing…                              | Reach for                                     |
+| --------------------------------------------- | --------------------------------------------- |
+| A landing page                                | `page({ static: true, view })`                |
+| A dynamic SEO page (`/product/:slug`)         | `page({ static: { paths, initialData } })`    |
+| An app screen behind auth                     | `page({ view })` (no `static`)                |
+| A shared shell that wraps several pages       | `page({ view: ({ child }) => html\`...\` })`  |
+| A reusable button / badge / card / modal     | `component("x-foo", setup, { styles })`       |
+| A custom form input                          | `component("x-input", setup, { shadow: false })` |
+| A small inline render helper (no state)       | a plain `(arg) => html\`...\`` function      |
+
+When in doubt, ask: **does this thing have a URL?** Yes → page.
+No → component.
+
+---
+
+## Anti-patterns
+
+These are the four mistakes Mado generators and AI assistants tend
+to produce. Avoid them.
+
+### 1. Page inside a `component()`
+
+```ts
+// ❌ Don't
+component(
+  "x-home-page",
+  () => () => html`<h1>Home</h1><p>...</p>`,
+);
+
+// ✅ Do
+export default page({
+  static: true,
+  title: "Home",
+  view: () => html`<h1>Home</h1><p>...</p>`,
+});
+```
+
+Why: the page becomes invisible to the router, the static snapshot
+pipeline cannot find it, and shared CSS (`content.css`) does not
+cross the Shadow boundary.
+
+### 2. Component used as a route
+
+```ts
+// ❌ Don't
+import "./components/billing-screen.component.js";
+const manifest = { "/billing": () => html`<x-billing-screen/>` };
+
+// ✅ Do
+import billing from "./pages/billing.page.js";
+const manifest = { "/billing": billing };
+```
+
+Why: the router gives you `page.head()`, `page.load()`, the static
+snapshot pipeline, the `data-mado-head` lifecycle and the seed
+contract. A component does not.
+
+### 3. `shadow: false` to "fix" CSS in a route layout
+
+```ts
+// ❌ Don't — this is a page wearing the wrong hat
+component(
+  "x-app-shell",
+  () => ({ child }) => html`<header>...</header><main>${child}</main>`,
+  { shadow: false, styles: css`...` },
+);
+
+// ✅ Do
+export default page({
+  view: ({ child }) => html`<header>...</header><main>${child}</main>`,
+});
+```
+
+Why: light-DOM components do not get the route `child`, are not
+recognised by `layout()`, and the manifest cannot wrap them.
+
+### 4. Route-id state in layout view locals
+
+```ts
+// ❌ Don't — `current` is shared across every page rendered by this layout
+const current = signal<User | null>(null);
+export default page({
+  view: ({ child }) => {
+    effect(() => loadUser(routePath()).then(current.set));
+    return html`<x-shell .user=${current}>${child}</x-shell>`;
+  },
+});
+
+// ✅ Do — put the resource in the page that needs it
+const user = resource(() => `/api/users/${userId()}`, jsonFetcher<User>());
+```
+
+Layouts are stateless wrappers. Per-page state belongs in the page
+itself or in a `resource()` whose key is the page's identity.
+
+---
+
+## What about styles?
+
+- `page()` lives in the light DOM. Use `content.css` / `shell.css`
+  from `src/styles/` (universal starter) or `src/shared/styles/`
+  (modular starter). Class selectors work normally.
+- `component()` carries its own `css\`\``. CSS custom properties
+  (`--accent`, `--bg`) cross the Shadow boundary; class selectors
+  from the document do not.
+- The shared design tokens (colours, spacing, type) live in
+  `tokens.css`. They are CSS custom properties and reach both pages
+  and components through `var(--...)`.
+
+For the long form on style boundaries, see
+[20-deployment.md](./20-deployment.md) (production tuning) and the
+starter README files.
+
+---
+
+## What about routing and links?
+
+Internal navigation is base-aware. Always use `routeUrl()` and
+`data-link`:
+
+```ts
+import { html, routeUrl } from "@madojs/mado";
+
+html`<a data-link href=${routeUrl("/billing/invoices")}>Invoices</a>`;
+html`<a data-link href=${routeUrl("/")}>Home</a>`;     // → "/mado/" under base
+```
+
+`data-link` opts the anchor into SPA navigation. A bare `<a href>`
+performs a full document load — that is intentional for foreign
+links and downloads. The router intercepts links inside Shadow DOM
+too (it uses `event.composedPath()`).
+
+Full router contract: [12-routing.md](./12-routing.md).
+
+---
+
+## Further reading
+
+- [11-templates-and-signals.md](./11-templates-and-signals.md) — the
+  `html\`\`` parser, signals, `each`, reactive bindings.
+- [12-routing.md](./12-routing.md) — `routes()`, layouts, guards,
+  `routeUrl`, `navigate`, prefetch.
+- [15-static-snapshots.md](./15-static-snapshots.md) — when to mark
+  a page `static: true`.
+- [14-forms.md](./14-forms.md) — `useForm()` + the only Shadow DOM
+  case where `shadow: false` is right.

package/docs/en/11-templates-and-signals.md

@@ -0,0 +1,211 @@
+# Templates and signals
+
+> Reactivity in Mado is one primitive — `signal()` — composed into
+> three reading patterns. Templates are tagged `html\`\`` literals
+> the browser understands directly.
+
+By the end of this page you should be able to read and write any
+Mado view without surprises.
+
+## Signals
+
+A signal is a getter function with a `.set()` method.
+
+```ts
+import { signal, computed, effect } from "@madojs/mado";
+
+const count = signal(0);
+
+count();                    // 0       — read
+count.set(5);               //         — write
+count.update((n) => n + 1); // 6       — derived write
+count.peek();               // 6       — read without subscribing
+
+const doubled = computed(() => count() * 2);
+doubled();                  // 12
+
+effect(() => console.log("count =", count()));
+// → "count = 6"
+count.set(7);
+// → "count = 7"
+```
+
+Rules of thumb:
+
+- A signal is a **function**: `count()`, not `count.value`.
+- `effect()` and `computed()` track every signal read **during their
+  callback**. There is no dependency array.
+- `computed()` is lazy and de-duplicates: if its result is `Object.is`-
+  equal to the previous one, subscribers do not re-run.
+- `untracked(() => ...)` reads without subscribing. Use it inside
+  async callbacks created from a synchronous `view()` so the router's
+  render effect does not accidentally subscribe.
+- `batch(() => { a.set(...); b.set(...); })` flushes once after the
+  callback returns. `flushSync()` flushes pending effects immediately.
+
+`effect()` cleanups run before the next run and on disposal. Inside a
+component or a page they happen automatically when the host leaves
+the DOM; outside, register the disposer through
+`getCurrentLifecycle()` or pass an explicit one to a
+`createLifecycle()` you own.
+
+## Templates
+
+`html\`\`` parses once per template literal into a static fragment +
+binding indices, then patches only the changing slots on each
+re-render.
+
+```ts
+import { html } from "@madojs/mado";
+
+html`<h1>Hello, ${name}</h1>`;
+```
+
+Five binding shapes — and only these:
+
+| Shape                | Meaning                                                                 |
+| -------------------- | ----------------------------------------------------------------------- |
+| `${value}`           | Child content: text, nodes, arrays, nested `html`, `each()` results.    |
+| `attr=${v}`          | HTML attribute. String / number / falsy (`false`/`null`/`undefined` → remove). |
+| `.prop=${v}`         | DOM property. Use for `.value` of inputs, arrays, objects, numbers.     |
+| `?attr=${flag}`      | Boolean attribute. `true` → present, `false` → absent (`?disabled`).    |
+| `@event=${fn}`       | Event listener. Removed automatically on re-render.                     |
+
+### The single most common mistake
+
+```ts
+const count = signal(0);
+
+// ❌ NOT REACTIVE — count() is read once at render
+html`<div>${count() * 2}</div>`
+
+// ✅ REACTIVE — the function is re-invoked on signal change
+html`<div>${() => count() * 2}</div>`
+
+// ✅ ALSO OK — the signal itself IS a function
+html`<div>${count}</div>`
+```
+
+Rule of thumb: if you wrote `signal()` (with parens) inside `${...}`,
+wrap the whole expression in `() => ...`.
+
+### Lists — `each(items, keyFn, renderFn)`
+
+```ts
+import { each } from "@madojs/mado";
+
+html`<ul>
+  ${() =>
+    each(
+      users(),
+      (u) => u.id,
+      (u) => html`<li>${u.name}</li>`,
+    )}
+</ul>`;
+```
+
+`each()` is keyed: rows keep DOM identity across re-orders, so input
+focus, scroll position and component state survive. A plain `.map()`
+works but is not keyed; avoid it for anything but throwaway lists.
+
+### Directives
+
+Inline helpers you import alongside `html`:
+
+- `unsafeHTML(string)` — interpolate trusted HTML.
+- `ref((el) => …)` — get a callback when the element mounts.
+- `classMap({ active: isActive(), error: hasError() })` — toggle
+  class names declaratively.
+- `styleMap({ color: theme().fg, "--bg": theme().bg })` — set
+  inline styles, including custom properties.
+
+### Parser hard errors
+
+Mado refuses templates it cannot represent safely. Two cases you
+will hit:
+
+```ts
+// ❌ slots inside RAW_TEXT elements
+html`<textarea>${draft}</textarea>`;
+html`<title>${title}</title>`;
+
+// ✅ use properties / page APIs
+html`<textarea .value=${draft}></textarea>`;
+page({ title: ({ id }) => `User ${id}`, view: () => html`<main></main>` });
+
+// ❌ nested SVG-only templates (namespace context is lost)
+html`<svg>${html`<circle r="5"></circle>`}</svg>`;
+
+// ✅ keep SVG internals in one template
+html`<svg viewBox="0 0 10 10"><circle r="5"></circle></svg>`;
+```
+
+No dynamic `${...}` child slots inside `<script>`, `<style>`,
+`<textarea>` or `<title>`.
+
+## How the two compose
+
+```ts
+import { html, page, signal } from "@madojs/mado";
+
+export default page({
+  title: "Counter",
+  view: () => {
+    // 1. local state
+    const n = signal(0);
+
+    // 2. event handlers
+    const inc = () => n.update((x) => x + 1);
+
+    // 3. view — values that change are wrapped in arrow functions
+    return html`
+      <main>
+        <h1>Counter</h1>
+        <button @click=${inc} ?disabled=${() => n() >= 10}>${n}</button>
+      </main>
+    `;
+  },
+});
+```
+
+A page's `view()` runs **once** when the route commits; the returned
+template stays mounted until the route changes. Every reactive slot
+re-evaluates independently — Mado never re-runs the whole view.
+
+## Lifecycle reads
+
+Inside a `component(setup, …)` you get the lifecycle through `ctx`:
+
+```ts
+component("x-timer", (ctx) => {
+  const tick = signal(0);
+  const id = setInterval(() => tick.update((n) => n + 1), 1000);
+  ctx.onDispose(() => clearInterval(id));
+  return () => html`<span>${tick}</span>`;
+});
+```
+
+Inside a `page({ view })` use the same `onDispose` from the view
+context:
+
+```ts
+export default page({
+  view: ({ onDispose }) => {
+    const handler = () => { /* … */ };
+    window.addEventListener("resize", handler);
+    onDispose?.(() => window.removeEventListener("resize", handler));
+    return html`<main>…</main>`;
+  },
+});
+```
+
+`resource()`, `effect()` and `mutation()` subscribe to the active
+lifecycle automatically — you do not write cleanup for them.
+
+## Further reading
+
+- [10-pages-and-components.md](./10-pages-and-components.md) — the
+  page vs component decision.
+- [13-data.md](./13-data.md) — `resource()` and `mutation()`.
+- [31-reactivity-ordering.md](./31-reactivity-ordering.md) — signal
+  scheduling, equality and teardown guarantees.

package/docs/en/12-routing.md

@@ -0,0 +1,229 @@
+# Routing
+
+> One app map. No folder scanners. No special path syntax. Layouts
+> are pages that render `${child}`.
+
+Mado does not infer routes from files. Route composition lives in
+one file — `src/app.routes.ts` — so the whole map is readable at a
+glance.
+
+## The app manifest
+
+```ts
+// src/app.routes.ts
+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 = {
+  "/":       () => import("./modules/home/home.page"),
+  "/login": layout({
+    layout: () => import("./layouts/auth-shell.layout"),
+    routes: authRoutes,
+  }),
+  "/billing": layout({
+    layout: () => import("./layouts/app-shell.layout"),
+    guard:  requireAuth,
+    routes: billingRoutes,
+  }),
+  "*": () => import("./modules/home/not-found.page"),
+};
+
+export default routes(manifest);
+```
+
+Opening `app.routes.ts` shows the whole app: public pages, auth
+zone, protected zones, guards and shells.
+
+Exporting `manifest` is **required**: `mado static` discovers
+static routes by reading it.
+
+## Module routes
+
+Modules export plain route maps. They do not decide which shell
+wraps them; that happens in `app.routes.ts`.
+
+```ts
+// src/modules/billing/billing.routes.ts
+export const billingRoutes = {
+  "/invoices":     () => import("./pages/invoices-list.page"),
+  "/invoices/:id": () => import("./pages/invoice-detail.page"),
+};
+```
+
+When mounted under `"/billing"` the public URLs become
+`/billing/invoices` and `/billing/invoices/:id`.
+
+## Layouts (the one blessed path)
+
+A layout is a `page({ view })` that renders `${ctx.child}` somewhere:
+
+```ts
+// src/layouts/app-shell.layout.ts
+import { html, page } from "@madojs/mado";
+
+export default page({
+  view: ({ child }) => html`
+    <header class="app-header">…</header>
+    <main class="app-main">${child}</main>
+  `,
+});
+```
+
+Mount it through `layout({ layout, routes, guard? })` in
+`app.routes.ts`. That is the **only** canonical place to declare a
+layout.
+
+Two corollaries that prevent the classic "navigation appears below
+content" bug:
+
+- **Order matters.** Outer manifest entries wrap inner ones.
+- **One shell per group.** If a subtree needs a different shell,
+  open a new `layout({...})` group; do not branch inside one shell.
+
+Two acceptable alternatives exist but are escape hatches, not the
+default:
+
+- *Single shell in `main.ts`* — `render(html\`<x-shell>${routes.view}</x-shell>\`)`.
+  Caveat: every route lives inside one shell; no centred login page,
+  no marketing landing without admin chrome.
+- *Per-page wrapping inside `view`* — each page repeats the shell.
+  Caveat: the first time someone forgets it the layout disappears.
+  Do not start with this.
+
+Layouts are stateless wrappers. Per-page state belongs in the page
+or in a `resource()` keyed by the page's identity — never in layout
+view locals.
+
+## What goes on the right side
+
+### Lazy page import (preferred)
+
+```ts
+"/users/:id": () => import("./modules/users/pages/user-profile.page"),
+```
+
+Vite emits a separate chunk per dynamic import in production.
+
+### Eager page
+
+```ts
+import home from "./modules/home/home.page";
+
+export const manifest = { "/": home };
+```
+
+Use only for tiny critical pages.
+
+### Layout group
+
+```ts
+"/admin": layout({
+  layout: () => import("./layouts/app-shell.layout"),
+  guard:  requireAuth,
+  routes: adminRoutes,
+}),
+```
+
+## Page contract
+
+```ts
+import { html, page } from "@madojs/mado";
+
+export default page<{ id: string }>({
+  title: ({ id }) => `User ${id}`,
+  view:  ({ params }) => html`<h1>${params.id}</h1>`,
+});
+```
+
+If a lazy route does not default-export `page({...})`, `routes()`
+throws a clear error at load time.
+
+## Guards
+
+A guard is a function returning `true | false | string | { redirect, replace? } | { halt }`:
+
+```ts
+export function requireAuth(): boolean | string {
+  return isAuthed() ? true : "/login";
+}
+```
+
+Guards apply outer → inner: layout-group guards run before page
+guards. Static routes refuse all guards (they are public by
+definition).
+
+## Internal links — `routeUrl()` + `data-link`
+
+Vite's `base` flows into `appBase` and `routeUrl()` automatically.
+Internal links MUST use both:
+
+```ts
+import { html, routeUrl } from "@madojs/mado";
+
+html`<a data-link href=${routeUrl("/users/42")}>User 42</a>`;
+html`<a data-link href=${routeUrl("/")}>Home</a>`;     // → "/mado/" under base
+```
+
+- `routeUrl(path)` returns a base-prefixed URL (preserves query and
+  hash).
+- `data-link` opts the anchor into SPA navigation. A bare
+  `<a href>` performs a full document load — intentional for
+  foreign URLs and downloads.
+
+The router intercepts links inside open Shadow DOM (it uses
+`event.composedPath()`).
+
+## Programmatic navigation
+
+```ts
+import appRoutes from "./app.routes";
+import { navigate } from "@madojs/mado";
+
+appRoutes.navigate("/billing/invoices");
+appRoutes.navigate("/billing/invoices?page=2");
+appRoutes.navigate("/login", { replace: true });
+
+// Standalone helper — dispatches popstate, every active router updates.
+navigate("/users/42");
+```
+
+Both accept route paths (no base prefix). The active base is
+re-applied internally before `history.pushState`.
+
+## Query parameters
+
+```ts
+import { queryParam } from "@madojs/mado";
+
+const page = queryParam("page", "1");
+page();                        // current value (reactive)
+page.set("2");                 // history.replaceState
+page.set("3", { push: true }); // history.pushState
+page.set(null);                // delete the parameter
+```
+
+`queryParam()` returns a `Signal<string>`. Reading inside a
+template subscribes; updating triggers a re-render.
+
+## Prefetch
+
+Hover-prefetch is on by default for `<a data-link>`. Programmatic
+prefetch:
+
+```ts
+import { prefetchPath } from "@madojs/mado";
+prefetchPath("/billing/invoices/123");
+```
+
+Foreign-base links (outside the active prefix) are ignored — the
+manifest only knows base-free route paths.
+
+## What is intentionally absent
+
+- No auto-scan of page folders.
+- No filesystem route syntax (`[id]`, `(group)`, `_layout`).
+- No server routes in the client manifest.
+- No hidden layout discovery — app zones are explicit in
+  `app.routes.ts`.