@madojs/mado 0.11.1 → 0.12.0

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`.

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.