npm - @madojs/mado - Versions diffs - 0.5.0 → 0.6.0 - Mend

@madojs/mado 0.5.0 → 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (122) hide show

package/AGENTS.md +49 -1
package/CHANGELOG.md +188 -0
package/MADO_V1_PLAN.md +179 -0
package/README.md +53 -14
package/ROADMAP.md +36 -5
package/TODO.md +72 -0
package/dist/src/forms.d.ts +41 -7
package/dist/src/forms.js +334 -59
package/dist/src/forms.js.map +1 -1
package/dist/src/html/bindings.d.ts +41 -0
package/dist/src/html/bindings.js +163 -6
package/dist/src/html/bindings.js.map +1 -1
package/dist/src/html.d.ts +2 -0
package/dist/src/html.js +1 -0
package/dist/src/html.js.map +1 -1
package/dist/src/index.d.ts +6 -6
package/dist/src/index.js +2 -2
package/dist/src/index.js.map +1 -1
package/dist/src/page.d.ts +56 -0
package/dist/src/page.js +17 -0
package/dist/src/page.js.map +1 -1
package/dist/src/router/manifest.d.ts +16 -1
package/dist/src/router/manifest.js +181 -38
package/dist/src/router/manifest.js.map +1 -1
package/dist/src/router/match.d.ts +7 -2
package/dist/src/router/match.js +14 -4
package/dist/src/router/match.js.map +1 -1
package/dist/src/router/navigation.d.ts +10 -0
package/dist/src/router/navigation.js +73 -12
package/dist/src/router/navigation.js.map +1 -1
package/dist/src/signal.d.ts +15 -1
package/dist/src/signal.js +112 -16
package/dist/src/signal.js.map +1 -1
package/docs/en/02-project-layout.md +99 -40
package/docs/en/05-why-mado.md +1 -1
package/docs/en/06-for-backenders.md +1 -1
package/docs/en/07-llm-pitfalls.md +1 -1
package/docs/en/09-shadow-vs-light-dom.md +60 -0
package/docs/en/10-app-architecture.md +141 -0
package/docs/en/11-layouts.md +115 -0
package/docs/en/12-auth-and-api.md +217 -0
package/docs/en/13-deployment.md +192 -0
package/docs/en/14-testing.md +82 -0
package/docs/en/15-error-handling.md +100 -0
package/docs/en/16-bake-cookbook.md +93 -0
package/docs/en/README.md +7 -0
package/docs/fr/05-why-mado.md +1 -1
package/docs/fr/06-for-backenders.md +1 -1
package/docs/fr/07-llm-pitfalls.md +1 -1
package/docs/fr/09-shadow-vs-light-dom.md +63 -0
package/docs/fr/10-app-architecture.md +61 -0
package/docs/fr/11-layouts.md +35 -0
package/docs/fr/12-auth-and-api.md +35 -0
package/docs/fr/13-deployment.md +39 -0
package/docs/fr/14-testing.md +41 -0
package/docs/fr/15-error-handling.md +50 -0
package/docs/fr/16-bake-cookbook.md +35 -0
package/docs/fr/README.md +7 -0
package/docs/ru/05-why-mado.md +2 -2
package/docs/ru/06-for-backenders.md +1 -1
package/docs/ru/09-shadow-vs-light-dom.md +60 -0
package/docs/ru/10-app-architecture.md +100 -0
package/docs/ru/11-layouts.md +47 -0
package/docs/ru/12-auth-and-api.md +53 -0
package/docs/ru/13-deployment.md +60 -0
package/docs/ru/14-testing.md +50 -0
package/docs/ru/15-error-handling.md +56 -0
package/docs/ru/16-bake-cookbook.md +55 -0
package/docs/ru/README.md +7 -0
package/docs/uk/06-for-backenders.md +2 -2
package/docs/uk/09-shadow-vs-light-dom.md +91 -24
package/docs/uk/10-app-architecture.md +56 -0
package/docs/uk/11-layouts.md +34 -0
package/docs/uk/12-auth-and-api.md +34 -0
package/docs/uk/13-deployment.md +39 -0
package/docs/uk/14-testing.md +34 -0
package/docs/uk/15-error-handling.md +32 -0
package/docs/uk/16-bake-cookbook.md +36 -0
package/docs/uk/README.md +7 -0
package/llms.txt +24 -1
package/package.json +3 -1
package/scripts/_config.mjs +224 -0
package/scripts/bake.mjs +217 -120
package/scripts/bundle.mjs +110 -67
package/scripts/cli.mjs +127 -16
package/scripts/preview.mjs +22 -12
package/server/serve.mjs +101 -11
package/starters/admin/README.md +63 -0
package/starters/admin/index.html +21 -0
package/starters/admin/mado.config.json +22 -0
package/starters/admin/package.json +22 -0
package/starters/admin/public/favicon.svg +4 -0
package/starters/admin/src/components/x-button.ts +55 -0
package/starters/admin/src/components/x-input.ts +74 -0
package/starters/admin/src/layouts/app.ts +101 -0
package/starters/admin/src/layouts/auth.ts +41 -0
package/starters/admin/src/lib/api.ts +133 -0
package/starters/admin/src/lib/auth.ts +83 -0
package/starters/admin/src/main.ts +15 -0
package/starters/admin/src/pages/admin/dashboard.ts +48 -0
package/starters/admin/src/pages/admin/order-detail.ts +78 -0
package/starters/admin/src/pages/admin/orders.ts +117 -0
package/starters/admin/src/pages/home.ts +25 -0
package/starters/admin/src/pages/login.ts +70 -0
package/starters/admin/src/pages/not-found.ts +12 -0
package/starters/admin/src/routes.ts +40 -0
package/starters/admin/src/styles/global.ts +86 -0
package/starters/admin/tsconfig.json +15 -0
package/starters/crud/README.md +14 -2
package/starters/crud/mado.config.json +20 -0
package/starters/crud/package.json +9 -4
package/starters/crud/src/components/app-shell.ts +13 -8
package/starters/crud/src/main.ts +1 -4
package/starters/crud/src/pages/ticket-detail.ts +1 -0
package/starters/crud/src/pages/ticket-new.ts +1 -0
package/starters/crud/src/pages/tickets.ts +1 -0
package/starters/crud/src/routes.ts +4 -2
package/starters/minimal/README.md +4 -2
package/starters/minimal/mado.config.json +20 -0
package/starters/minimal/package.json +8 -3
package/starters/minimal/src/components/app-counter.ts +1 -1
package/starters/minimal/src/routes.ts +4 -2

package/docs/en/14-testing.md ADDED Viewed

@@ -0,0 +1,82 @@
+# Testing
+Mado projects are plain TypeScript and browser APIs, so tests should stay plain
+too. The framework repository uses Node's built-in test runner plus `linkedom`
+for DOM tests.
+## Commands
+```bash
+npm run typecheck
+npm run build
+npm test
+```
+Before publishing or merging a release branch, run all three.
+## Unit tests with DOM
+```js
+import test from "node:test";
+import assert from "node:assert/strict";
+const { parseHTML } = await import("linkedom");
+const { window } = parseHTML("<!doctype html><html><body></body></html>");
+globalThis.window = window;
+globalThis.document = window.document;
+globalThis.Node = window.Node;
+globalThis.HTMLElement = window.HTMLElement;
+const { html, render } = await import("../dist/src/html.js");
+test("renders a value", () => {
+  const root = document.createElement("div");
+  render(html`<p>${"hello"}</p>`, root);
+  assert.equal(root.querySelector("p").textContent, "hello");
+});
+```
+Build first, then import from `dist/`. This tests the same files the browser
+will load.
+## What to cover
+Test behavior, not internal implementation details:
+- signal/computed scheduling and cleanup;
+- template binding edges: child values, attributes, events, directives;
+- 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`.
+## Browser smoke tests
+Use Playwright or another browser runner for flows that require real layout,
+focus, navigation or custom-element lifecycle. Keep them small:
+1. start the app;
+2. visit one route;
+3. click one link or submit one form;
+4. assert the user-visible result.
+Most regression tests should still be fast Node tests.
+## Test data
+Keep API data in local fixtures or tiny in-memory fake clients. Do not call real
+services from framework tests. For app tests, make the API client injectable via
+`createContext()` so pages can run against a fake client.
+## Release checklist
+```bash
+npm run typecheck
+npm run build
+npm test
+npm run bundle
+npm run bake
+```
+`mado release` runs the production path for an app. In the framework repository,
+the lower-level commands remain useful when debugging a single stage.

package/docs/en/15-error-handling.md ADDED Viewed

@@ -0,0 +1,100 @@
+# Error handling
+Mado has three practical error layers: route loading, data loading, and user
+actions. Handle each layer where the user can recover.
+## Route errors
+Use a global `errorPage` in `routes()` for lazy import, `load()` and `view()`
+failures.
+```ts
+export default routes(manifest, {
+  errorPage: (err) => html`
+    <main>
+      <h1>Something went wrong</h1>
+      <pre>${err.message}</pre>
+      <a data-link href="/">Go home</a>
+    </main>
+  `,
+});
+```
+For a specific page, `page({ errorView })` wins over the global route boundary.
+```ts
+export default page({
+  load: async () => api.get("/reports"),
+  errorView: (err) => html`<x-report-error .error=${err}></x-report-error>`,
+  view: ({ data }) => html`<x-report .data=${data}></x-report>`,
+});
+```
+## Resource errors
+`resource()` exposes `error()` and `loading()`. Render a retry path near the data.
+```ts
+const users = resource(() => "/api/users", jsonFetcher<User[]>());
+html`
+  ${() => users.error()
+    ? html`<p role="alert">${users.error()!.message}</p>
+         <button @click=${users.refresh}>Retry</button>`
+    : null}
+`;
+```
+Use `HttpError` or your own API error type when the UI needs status codes.
+## Form and mutation errors
+Validation errors belong in `useForm()`. Server errors from writes belong near
+the submit button.
+```ts
+const form = useForm(
+  { email: { required: true, type: "email" } },
+  { validateAsync: (values) => api.validateUser(values) },
+);
+const save = mutation((values) => api.post("/users", values), {
+  invalidates: ["/api/users*"],
+});
+html`
+  <form @submit=${form.onSubmit(async values => {
+    await save.run(values);
+  })}>
+    <button ?disabled=${() => form.validating() || form.submitting()}>
+      Save
+    </button>
+    ${() => save.error() ? html`<p role="alert">${save.error()!.message}</p>` : null}
+  </form>
+`;
+```
+## Component cleanup
+If you subscribe to external browser APIs, clean them with `ctx.onDispose()`.
+Signals, effects and resources created inside setup are lifecycle-aware.
+```ts
+component("x-online", (ctx) => {
+  const online = signal(navigator.onLine);
+  const onChange = () => online.set(navigator.onLine);
+  window.addEventListener("online", onChange);
+  window.addEventListener("offline", onChange);
+  ctx.onDispose(() => {
+    window.removeEventListener("online", onChange);
+    window.removeEventListener("offline", onChange);
+  });
+  return () => html`${() => online() ? "Online" : "Offline"}`;
+});
+```
+## Logging rule
+Log once at the boundary that owns recovery. Avoid logging the same failure in
+the API client, resource, page and component. The user should get one visible
+message and developers should get one useful console error.

package/docs/en/16-bake-cookbook.md ADDED Viewed

@@ -0,0 +1,93 @@
+# Bake cookbook
+`mado bake` renders selected routes into static HTML. It is for SEO and fast
+first paint, not for server-side hydration.
+## Minimal baked page
+```ts
+export default page({
+  head: () => ({ title: "Products", description: "Product catalog" }),
+  view: ({ data }) => html`
+    <main>
+      <h1>Products</h1>
+      ${data.products.map((p) => html`<article><h2>${p.name}</h2></article>`)}
+    </main>
+  `,
+  bake: {
+    paths: () => [{}],
+    data: async () => ({ products: await api.products() }),
+    revalidate: 3600,
+  },
+});
+```
+For baked pages, use plain arrays in `view()` when possible. Runtime-only
+directives such as keyed `each()` are for the browser.
+## Dynamic routes
+```ts
+export default page<{ slug: string }>({
+  head: ({ slug }, data) => ({ title: data.title, canonical: `/blog/${slug}` }),
+  view: ({ data }) => html`<article>${unsafeHTML(data.html)}</article>`,
+  bake: {
+    paths: async () => (await api.posts()).map((p) => ({ slug: p.slug })),
+    data: ({ slug }) => api.post(slug),
+  },
+});
+```
+`unsafeHTML()` is allowed only for trusted or already-sanitized HTML.
+## Route manifest
+`mado bake` needs the source manifest:
+```ts
+export const manifest = {
+  "/": () => import("./pages/home.js"),
+  "/blog/:slug": () => import("./pages/blog-post.js"),
+};
+export default routes(manifest);
+```
+## Output
+By default app-mode writes baked pages under `out/baked/`. `mado release`
+produces the final deploy artifact:
+```bash
+mado release
+tree out
+```
+The deployable folder is `out/`, not `dist/`.
+## Unsupported values
+Bake intentionally fails loudly instead of writing `[object Object]`. If a baked
+view throws an unsupported directive error:
+- replace `each()` with `items.map(...)` in baked markup;
+- keep interactive-only widgets behind client routes;
+- make sure every value can be serialized to static HTML.
+## Canonical links
+Pass `--base-url` or set `bake.baseUrl` in `mado.config.json` so generated
+canonical links and sitemap entries point to production.
+```json
+{
+  "bake": {
+    "baseUrl": "https://example.com"
+  }
+}
+```
+## When not to bake
+Do not bake pages whose content is user-specific, permission-dependent, or
+changes every few seconds. Use a normal SPA route with `resource()` instead.

package/docs/en/README.md CHANGED Viewed

@@ -14,3 +14,10 @@ English documentation set.
 | LLM pitfalls | [07-llm-pitfalls.md](./07-llm-pitfalls.md) |
 | LLM zero-history test | [08-llm-zero-history-test.md](./08-llm-zero-history-test.md) |
 | Shadow DOM vs Light DOM | [09-shadow-vs-light-dom.md](./09-shadow-vs-light-dom.md) |
+| App architecture | [10-app-architecture.md](./10-app-architecture.md) |
+| Layouts | [11-layouts.md](./11-layouts.md) |
+| Auth and API | [12-auth-and-api.md](./12-auth-and-api.md) |
+| Deployment | [13-deployment.md](./13-deployment.md) |
+| Testing | [14-testing.md](./14-testing.md) |
+| Error handling | [15-error-handling.md](./15-error-handling.md) |
+| Bake cookbook | [16-bake-cookbook.md](./16-bake-cookbook.md) |

package/docs/fr/05-why-mado.md CHANGED Viewed

@@ -33,7 +33,7 @@ Si votre cas ne tombe pas dans le dernier point — Mado n'est probablement pas
 | Réactivité | décorateurs `@property` + `requestUpdate` manuel | signals (`signal`/`computed`/`effect`) intégrés |
 | Router | aucun, vous devez en trouver un (`@lit-labs/router`, etc.) | inclus : `routes()` + nested + prefetch + sync-cache |
 | Chargement de données | aucun, vous devez l'assembler | `resource()` + `mutation()` + invalidation glob |
-| Forms | aucun | `useForm()` sur validation HTML5 native |
+| Forms | aucun | `useForm()` avec contraintes proches du HTML |
 | SEO / statique | complexe (`@lit-labs/ssr`) | `bake` (linkedom) + edge-prerender |
 | Build | nécessite esbuild/rollup/webpack | `tsc` suffit |
 | Style de code | classes + décorateurs | fonctions + tagged templates |

package/docs/fr/06-for-backenders.md CHANGED Viewed

@@ -195,7 +195,7 @@ Mado ne fait que le coller avec les signals.
 ## Forms — comme `form.Validate()` côté backend
-Mado utilise la **validation HTML5 native**, plus ajoute le suivi d'état.
+Mado utilise une **validation par schéma proche des contraintes HTML natives**, plus le suivi d'état.
 ```ts
 import { useForm } from "@madojs/mado";

package/docs/fr/07-llm-pitfalls.md CHANGED Viewed

@@ -256,7 +256,7 @@ Cela signifie :
 // ❌ Pas une telle API
 const f = useForm({ resolver: zodResolver(schema) });
-// ✅ Correct : validation HTML5 via attributs
+// ✅ Correct : validation proche du HTML via le schéma useForm
 const f = useForm({
   email: { required: true, type: "email" },
   age:   { required: true, type: "number", min: 18 },

package/docs/fr/09-shadow-vs-light-dom.md CHANGED Viewed

@@ -5,6 +5,19 @@ autonomes, mais ce n'est pas le bon défaut pour chaque composant dans une appli
 ## Règle générale
+Dans Mado, un layout est aussi un composant. Si un fichier décrit une partie
+visible et réutilisable de l'arbre UI — app shell, sidebar, modal, table,
+section de page — préférez un Web Component déclaré avec `component()`.
+Gardez les fonctions simples pour de petits helpers inline :
+```ts
+const money = (value: number) => html`<span>${formatMoney(value)}</span>`;
+```
+Ne faites pas d'app shell sous forme de fonction dans les exemples publics. Cela
+fonctionne, mais cela cache le modèle du navigateur au lieu de l'enseigner.
 Utilisez **Shadow DOM** pour les widgets feuilles :
 - boutons, badges, cartes, métriques ;
@@ -22,6 +35,16 @@ les utilitaires CSS globaux :
   tableau ;
 - endroits où les enfants doivent simplement rester dans le DOM normal du document.
+Utilisez **Shadow DOM** pour les layouts basés sur des slots :
+- app shells qui rendent `<slot>` ;
+- wrappers sidebar/contenu ;
+- frames de layout réutilisables qui possèdent leur propre CSS grid/header/sidebar.
+`<slot>` est une fonctionnalité Shadow DOM. Dans un composant `shadow: false`,
+`<slot>` est juste un élément DOM normal et ne déplace pas les enfants à cet
+endroit du layout.
 ## Le piège
 Le CSS global ne franchit pas une frontière Shadow DOM.
@@ -89,6 +112,18 @@ component("x-toast-stack", setup);
 Cela donne aux écrans d'admin backend un CSS prévisible tout en préservant l'encapsulation
 pour les widgets réutilisables et les shells basés sur slot.
+Le modèle d'import est volontairement natif au navigateur :
+```ts
+import "./components/app-layout.js";
+render(html`<x-app-layout>${router.view}</x-app-layout>`, app);
+```
+L'import enregistre le custom element avec `customElements.define()`. Le template
+crée un élément `<x-app-layout>`. Le navigateur relie les deux. Il n'y a pas de
+valeur de composant à la React que l'on passe comme fonction.
 Si un layout n'a pas besoin de projection slot et doit être entièrement stylé par du CSS
 global, `shadow: false` peut rester un bon choix. S'il contient `<slot>`, gardez Shadow DOM
 et mettez les styles du shell dans `styles: css\`\``.
@@ -107,6 +142,34 @@ component("x-card-link", () => () => html`
 Le lien peut être en Shadow DOM ; la navigation reste SPA.
+## Où importer les composants
+Les custom elements sont globaux après leur enregistrement, mais cet
+enregistrement reste un import JavaScript explicite.
+```ts
+// main.ts : frame global de l'app
+import "./components/app-shell.js";
+// pages/tickets.ts : composant possédé par cette page
+import "../components/ticket-list.js";
+```
+Le navigateur ne télécharge **pas** `ticket-list.js` simplement parce qu'il voit
+`<ticket-list>`. Le fichier doit d'abord être importé quelque part. Une fois
+importé, il appelle `customElements.define(...)`, et le tag devient connu dans
+le document courant.
+N'importez pas tous les composants en masse dans `main.ts` "au cas où". Cela
+fonctionne pour de petites démos, mais cache l'ownership et casse le chargement
+paresseux des routes. Préférez :
+- app shell/providers globaux dans `main.ts` ;
+- composants utilisés par une seule page dans ce fichier page ;
+- composants partagés d'une feature dans la page d'entrée de cette feature ;
+- petits leaf components vraiment globaux dans `main.ts` seulement s'ils sont
+  utilisés partout.
 ## Leçon du Showcase
 `examples/showcase` utilise cette séparation délibérément :

package/docs/fr/10-app-architecture.md ADDED Viewed

@@ -0,0 +1,61 @@
+# Architecture d'application
+La forme recommandée d'une app Mado en production est volontairement simple :
+un manifeste de routes, un shell, un client API, un module auth, et des pages
+qui importent leurs propres composants.
+## Structure
+```txt
+src/
+├── main.ts
+├── routes.ts
+├── layouts/
+├── pages/
+├── components/
+├── lib/
+└── styles/
+```
+`lib/` contient la logique métier, `layouts/` enveloppe les groupes de routes,
+`components/` contient les tags réutilisables, et `pages/` contient un fichier
+par page.
+```ts
+import { html, render } from "@madojs/mado";
+import "./styles/global.js";
+import routesApi from "./routes.js";
+render(html`${routesApi.view}`, document.getElementById("app")!);
+```
+N'importe pas tous les composants dans `main.ts`. Une page importe les
+composants qu'elle rend.
+```ts
+import { layout, routes } from "@madojs/mado";
+import { requireAuth } from "./lib/auth.js";
+export const manifest = {
+  "/": () => import("./pages/home.js"),
+  "/admin": layout({
+    layout: () => import("./layouts/app.js"),
+    guard: requireAuth,
+    routes: { "/": () => import("./pages/admin/dashboard.js") },
+  }),
+  "*": () => import("./pages/not-found.js"),
+};
+export default routes(manifest);
+```
+Exporte `manifest` pour `mado bake`. Utilise `resource()` pour les lectures,
+`mutation(..., { invalidates })` pour les écritures, et `useForm()` pour les
+workflows utilisateur.
+```bash
+mado dev
+mado release
+```
+Le dossier déployable est `out/`. `dist/` est interne.

package/docs/fr/11-layouts.md ADDED Viewed

@@ -0,0 +1,35 @@
+# Layouts
+Le chemin recommandé pour les layouts Mado est un groupe de routes imbriqué
+dans `routes.ts`.
+```ts
+import { layout, routes } from "@madojs/mado";
+import { requireAuth } from "./lib/auth.js";
+export const manifest = {
+  "/": () => import("./pages/home.js"),
+  "/login": layout({
+    layout: () => import("./layouts/auth.js"),
+    routes: { "/": () => import("./pages/login.js") },
+  }),
+  "/admin": layout({
+    layout: () => import("./layouts/app.js"),
+    guard: requireAuth,
+    routes: { "/": () => import("./pages/admin/dashboard.js") },
+  }),
+};
+export default routes(manifest);
+```
+Un layout est une `page({ view })` qui rend `child` :
+```ts
+export default page({
+  view: ({ child }) => html`<x-app-shell>${child}</x-app-shell>`,
+});
+```
+Règles : un shell par groupe, pas par page ; les layouts externes enveloppent
+les layouts internes ; un guard sur le groupe protège tout le sous-arbre.

package/docs/fr/12-auth-and-api.md ADDED Viewed

@@ -0,0 +1,35 @@
+# Auth et API
+Le starter `admin` contient la recette recommandée :
+- `src/lib/api.ts` — un seul client HTTP, `ApiError`, refresh après 401 ;
+- `src/lib/auth.ts` — `accessToken`, `restoreSession()`, `login()`,
+  `logout()`, `requireAuth`.
+Modèle :
+- access token en mémoire via `signal`, pas dans `localStorage` ;
+- refresh cookie HttpOnly pour restaurer la session ;
+- toutes les requêtes passent par le client API ;
+- les routes protégées utilisent un group guard.
+```ts
+export const requireAuth: Guard = async ({ path }) => {
+  if (accessToken()) return;
+  if (await restoreSession()) return;
+  return { redirect: `/login?return=${encodeURIComponent(path)}`, replace: true };
+};
+```
+Dev proxy :
+```jsonc
+{
+  "dev": {
+    "proxy": { "/api": "http://localhost:3000" }
+  }
+}
+```
+Si ton backend a une autre forme, modifie `api.ts` et `auth.ts`. Les pages ne
+doivent pas connaître les détails d'authentification.

package/docs/fr/13-deployment.md ADDED Viewed

@@ -0,0 +1,39 @@
+# Déploiement
+Une commande, un artefact :
+```bash
+mado release
+```
+Résultat :
+```txt
+out/
+├── index.html
+├── assets/
+├── baked/
+├── _redirects
+└── _headers
+```
+Déploie `out/` sur nginx, Cloudflare Pages, Netlify, S3/CloudFront ou GitHub
+Pages.
+```bash
+mado release
+mado preview
+```
+`mado preview` sert `out/` comme un hébergeur statique : HTML baked d'abord,
+fallback SPA ensuite.
+Pour VPS + nginx :
+```bash
+mado release
+rsync -avz --delete out/ user@server:/var/www/myapp/
+```
+Le `nginx.conf` fourni gère cache immutable pour les bundles hashés, no-cache
+pour HTML, et fallback SPA pour les deep links.

package/docs/fr/14-testing.md ADDED Viewed

@@ -0,0 +1,41 @@
+# Tests
+Mado utilise TypeScript et les APIs du navigateur. Le dépôt du framework teste
+avec le test runner de Node et `linkedom`.
+```bash
+npm run typecheck
+npm run build
+npm test
+```
+Un test DOM minimal :
+```js
+import test from "node:test";
+import assert from "node:assert/strict";
+const { parseHTML } = await import("linkedom");
+const { window } = parseHTML("<!doctype html><html><body></body></html>");
+globalThis.window = window;
+globalThis.document = window.document;
+globalThis.Node = window.Node;
+globalThis.HTMLElement = window.HTMLElement;
+const { html, render } = await import("../dist/src/html.js");
+test("renders", () => {
+  const root = document.createElement("div");
+  render(html`<p>${"hello"}</p>`, root);
+  assert.equal(root.querySelector("p").textContent, "hello");
+});
+```
+À couvrir :
+- signals/computed/effect : scheduling et nettoyage ;
+- bindings HTML : children, attributs, événements, directives ;
+- routes : guards, redirects, scroll/focus, error boundaries ;
+- formulaires : validation sync/async, races, field arrays ;
+- resources/mutations : clés de cache, invalidation, lifecycle ;
+- CLI : `mado release`, `mado bake`, `mado preview`.

package/docs/fr/15-error-handling.md ADDED Viewed

@@ -0,0 +1,50 @@
+# Gestion des erreurs
+Traite les erreurs au niveau où l'utilisateur peut récupérer : routes, données,
+actions utilisateur.
+## Routes
+```ts
+export default routes(manifest, {
+  errorPage: (err) => html`
+    <main>
+      <h1>Une erreur est survenue</h1>
+      <pre>${err.message}</pre>
+      <a data-link href="/">Accueil</a>
+    </main>
+  `,
+});
+```
+`page({ errorView })` a priorité sur cette boundary globale.
+## Données
+```ts
+const users = resource(() => "/api/users", jsonFetcher<User[]>());
+html`
+  ${() => users.error()
+    ? html`<p role="alert">${users.error()!.message}</p>
+         <button @click=${users.refresh}>Réessayer</button>`
+    : null}
+`;
+```
+## Formulaires et mutations
+La validation va dans `useForm()`. Les erreurs serveur d'écriture restent près
+du bouton de soumission.
+```ts
+const form = useForm(
+  { email: { required: true, type: "email" } },
+  { validateAsync: (values) => api.validateUser(values) },
+);
+const save = mutation((values) => api.post("/users", values), {
+  invalidates: ["/api/users*"],
+});
+```
+Nettoie les subscriptions navigateur externes avec `ctx.onDispose()`.