@madojs/mado 0.10.1 → 0.11.0

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

@@ -13,7 +13,7 @@ Mado est structuré **comme un serveur HTTP**. Sérieusement :
 |---|---|
 | Routeur HTTP (chi, axum, mux) | `routes()` — manifeste de chemins |
 | Handler `func(req, resp)` | `page({ view: (ctx) => html\`...\` })` |
-| Middleware | `layout` dans `nested()` (enveloppe le handler) |
+| Middleware | route group via `layout()` (enveloppe le handler) |
 | Moteur de template (Jinja, Handlebars) | tagged template `html\`\`` |
 | Client HTTP avec cache | `resource()` — fetch + cache + invalidation |
 | Variable réactive / atom | `signal()` — getter réactif |
@@ -360,17 +360,17 @@ export default page({
 ```
 
 ```ts
-// src/routes.ts
-import { routes, nested } from "@madojs/mado";
+// src/app.routes.ts
+import { layout, routes } from "@madojs/mado";
 
 export default routes({
   "/login": () => import("./pages/login.js"),
 
-  "/app/*": nested({
+  "/app": layout({
     layout: () => import("./layouts/auth-layout.js"),
     routes: {
-      "dashboard": () => import("./pages/dashboard.js"),
-      "users": () => import("./pages/users.js"),
+      "/dashboard": () => import("./pages/dashboard.js"),
+      "/users": () => import("./pages/users.js"),
     },
   }),
 });
@@ -433,6 +433,6 @@ Tout le reste — navigateur standard + TypeScript.
 - **[`01-routing.md`](./01-routing.md)** — le router en détail.
 - **[`02-project-layout.md`](./02-project-layout.md)** — structure du projet.
 - **[`03-static-bake.md`](./03-static-bake.md)** — SEO sans SSR.
-- **[`examples/showcase/`](../../examples/showcase/)** — exemple complet (landing + admin).
+- **[`10-app-architecture.md`](./10-app-architecture.md)** — forme canonique du starter.
 
 Si quelque chose n'est pas clair — ouvrez une issue, ou ouvrez simplement le source. Il est vraiment lisible en une soirée.

package/docs/fr/08-llm-zero-history-test.md

@@ -1,65 +1,38 @@
 # Test LLM sans historique
 
-Ce document définit un test de validation pratique pour Mado.
-
-La question n'est pas "un LLM peut-il générer du code frontend ?" Il le peut. La question est :
-un LLM fraîchement initialisé peut-il écrire du Mado idiomatique sans retomber dans du code
-de forme React ?
+Ce document définit un test manuel pour vérifier qu'un LLM fraîchement
+initialisé écrit du Mado idiomatique au lieu de reproduire React dans des
+tagged templates.
 
 ## Contexte autorisé
 
-Pour le premier passage, donnez à l'agent uniquement :
-
 - `AGENTS.md`
 - `README.md`
-- `docs/ru/07-llm-pitfalls.md`
-- `examples/basic/README.md` si un tour minimal de l'API est nécessaire
-- des fichiers `examples/showcase/**` spécifiques uniquement quand l'agent demande un pattern
-  d'application plus grande
-
-L'agent peut rechercher des API ciblées dans `src/` quand il est bloqué, mais ne doit pas
-charger tout le framework dans le context.
+- `docs/fr/07-llm-pitfalls.md` ou la version anglaise
+- fichiers de l'espace externe `madojs-examples` seulement si l'agent demande
+  un pattern d'application plus large
 
 ## Tâche
 
-Construire `examples/tickets` : une petite SPA d'administration de tickets pour un développeur
-solo/backend.
-
-Comportement requis :
+Construire une petite SPA ticket-admin :
 
 - routes : `/`, `/tickets`, `/tickets/new`, `/tickets/:id`, `*` ;
-- API mock en mémoire avec des délais async réalistes ;
-- page de liste avec `resource()`, `queryParam()` filtres de recherche/statut, `computed()`,
-  et des lignes `each()` avec clés ;
-- flux de création et d'édition avec `useForm()` + `mutation()` + `invalidates` ;
-- état UI local avec `signal()` ;
-- composants shell, metric et badge avec slot pour une UI admin plus réaliste ;
-- test de smoke important le build de l'exemple.
+- mock API en mémoire avec délais async réalistes ;
+- liste avec `resource()`, `queryParam()`, `computed()` et `each()` keyed ;
+- create/edit avec `useForm()` + `mutation()` + `invalidates` ;
+- état UI local avec `signal()`.
 
-## Liste de contrôle des échecs
+## Checklist d'échec
 
-Cherchez ces éléments après l'implémentation :
-
-- JSX, `useState`, `useEffect`, `ref`, `$state`, ou composants de style classe ;
-- `${signal()}` ou `${signal() + 1}` là où un thunk enfant réactif est requis ;
+- JSX, `useState`, `useEffect`, `ref`, `$state`, classes custom elements ;
+- `${signal()}` là où un child thunk réactif est nécessaire ;
 - `disabled=${...}` au lieu de `?disabled=${...}` ;
-- listes dynamiques rendues avec un mapping de tableau sans clé au lieu de `each()` ;
-- imports ESM navigateur sans `.js` ;
-- `resource()` créé en dehors du setup du composant ;
-- nouvelles dépendances runtime ou nouvelles API publiques du framework.
-
-## Notes de résultats
-
-L'implémentation actuelle de `examples/tickets` n'a pas nécessité de nouvelles API publiques ni
-de dépendances runtime.
+- `.map()` non-keyed pour des listes dynamiques ;
+- `resource()` créé hors contexte lifecycle-aware ;
+- nouvelles dépendances runtime ou nouvelles API publiques.
 
-CI exécute `npm run llm:smoke` comme proxy déterministe pour cette tâche :
-il vérifie que `llms.txt` contient toujours les règles clés, compare l'artefact
-commité `examples/tickets` à la surface API Mado requise et aux failure
-patterns, puis build le projet et lance `test/tickets-smoke.test.mjs`.
+## Notes
 
-Le principal point de pression dans la documentation reste le lifecycle : les anciens exemples
-peuvent donner l'impression qu'il est acceptable de créer `resource()` directement dans
-`page.view()`. L'exemple tickets utilise plutôt des composants wrapper au niveau page, de sorte
-que les resources sont enregistrées à l'intérieur du setup du composant et se nettoient avec
-le composant.
+L'implémentation historique tickets vit dans l'espace externe d'exemples. Le
+core repository ne livre plus cet artefact ; utilisez cette page comme script
+d'évaluation manuel quand vous mettez à jour les règles LLM.

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

@@ -1,184 +1,65 @@
 # Shadow DOM vs Light DOM
 
-Les composants Mado utilisent Shadow DOM par défaut. C'est un bon défaut pour les widgets
-autonomes, mais ce n'est pas le bon défaut pour chaque composant dans une application.
+Les composants Mado utilisent Shadow DOM par défaut. C'est un bon défaut pour
+les widgets autonomes, mais les zones d'application et les pages restent
+généralement de simples templates light DOM.
 
-## Règle générale
+## Règle
 
-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 :
+Utilisez les route layouts pour les zones d'application :
 
 ```ts
-const money = (value: number) => html`<span>${formatMoney(value)}</span>`;
+export default page({
+  view: ({ child }) => html`<main class="app-main">${child}</main>`,
+});
 ```
 
-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 ;
-- modals, toasts, petits composants visuels ;
-- widgets d'intégration qui ne devraient pas hériter du CSS de l'app accidentellement ;
-- composants dont le stylage doit appartenir au composant lui-même.
-
-Utilisez **Light DOM** (`{ shadow: false }`) pour la structure de l'app qui veut partager
-les utilitaires CSS globaux :
-
-- composants route/page ;
-- écrans admin avec des layouts denses de tableau/formulaire ;
-- écrans riches en données avec des tableaux et des formulaires ;
-- composants qui partagent intentionnellement les utilitaires globaux de layout, formulaire et
-  tableau ;
-- endroits où les enfants doivent simplement rester dans le DOM normal du document.
+Ces fichiers vivent dans `src/layouts/` et sont composés depuis
+`src/app.routes.ts` avec `layout()`. Ils sont stylés par
+`src/shared/styles/shell.css`.
 
-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.
+Utilisez les page files pour les écrans :
 
 ```ts
-// global.ts
-export const globalStyles = css`
-  .page-head { display: flex; justify-content: space-between; }
-  .metric-grid { display: grid; grid-template-columns: repeat(4, 1fr); }
-`;
-
-// ❌ .page-head et .metric-grid ne s'appliqueront pas à l'intérieur du shadowRoot de x-dashboard
-component("x-dashboard", () => () => html`
-  <header class="page-head">...</header>
-  <div class="metric-grid">...</div>
-`);
+export default page({
+  view: () => html`<section><h1>Users</h1></section>`,
+});
 ```
 
-Corrigez en rendant le composant route/page Light DOM :
+Les tables, forms, prose et états simples de page sont stylés par
+`src/shared/styles/content.css`.
+
+Utilisez Shadow DOM components pour les widgets feuilles :
+
+- buttons, badges, cards, metrics ;
+- spinners, modals, toasts ;
+- widgets qui doivent posséder leur CSS.
 
 ```ts
-component("x-dashboard", () => () => html`
-  <header class="page-head">...</header>
-  <div class="metric-grid">...</div>
-`, {
-  shadow: false,
+component("x-status-badge", ({ attr }) => {
+  const status = attr("status", "draft");
+  return () => html`<span>${status}</span>`;
+}, {
   styles: css`
-    x-dashboard { display: block; }
-    x-dashboard .panel { padding: 1rem; }
+    :host { display: inline-block; }
+    span { color: var(--color-text-muted); }
   `,
 });
 ```
 
-Maintenant les utilitaires globaux et les styles locaux scopés fonctionnent tous les deux.
-
 ## Comment les styles se comportent
 
-- `styles: css\`\`` en Shadow DOM est adopté dans le shadowRoot du composant.
-- `styles: css\`\`` avec `shadow: false` est scopé au nom du tag et adopté globalement.
-- Les propriétés CSS personnalisées (`--accent`, `--bg`, etc.) traversent les frontières Shadow DOM.
-- Les sélecteurs de classe comme `.btn`, `.form-grid`, `.page-head` ne traversent **pas** les
-  frontières Shadow DOM.
-- Les enfants slottés conservent leurs propres styles de document ; le composant shadow ne peut
-  les cibler qu'à travers `::slotted(...)`.
-- `<slot>` projette les enfants uniquement en Shadow DOM. Dans un composant `shadow: false`,
-  c'est juste un élément `<slot>` normal et ne déplacera pas les enfants à cet endroit dans
-  votre layout.
-
-## Forme recommandée de l'application
-
-```ts
-// racine et pages : Light DOM
-component("x-app", setup, { shadow: false });
-component("x-users-page", setup, { shadow: false });
-
-// layout basé sur slot : Shadow DOM par défaut, car il possède la grille du shell
-component("x-app-layout", setup);
-
-// widgets feuilles : Shadow DOM par défaut
-component("x-status-badge", setup);
-component("x-stat-card", setup);
-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\`\``.
-
-## Routage et liens
-
-`data-link` fonctionne à l'intérieur de Shadow DOM. Le router utilise `event.composedPath()`,
-donc l'interception de clic et le hover-prefetch peuvent voir les liens depuis les shadow roots
-ouverts.
-
-```ts
-component("x-card-link", () => () => html`
-  <a href="/app/accounts" data-link>Comptes</a>
-`);
-```
-
-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 :
-
-- `x-app` et les pages de route CRM sont Light DOM ;
-- `x-app-layout` garde Shadow DOM car il possède un shell sidebar/contenu basé sur slot ;
-- les utilitaires de tableau/formulaire/page vivent dans `styles/global.ts` ;
-- les composants feuilles comme `x-stat-card`, `x-status-badge`, `x-modal` et `x-toast-stack`
-  gardent Shadow DOM.
-
-Si une page a soudainement l'air sans style, vérifiez si elle utilise des classes globales
-à l'intérieur d'un composant Shadow DOM. C'est généralement le problème.
+- `tokens.css` définit des CSS custom properties ; `var(...)` traverse Shadow
+  DOM.
+- `reset.css`, `shell.css`, `content.css` s'appliquent seulement au document /
+  light DOM.
+- Les sélecteurs de classe comme `.data`, `.app-main`, `.error` ne traversent
+  pas Shadow DOM.
+- Les styles locaux des composants vivent dans ``css`...` `` dans les options de
+  `component()`.
+- Si un Shadow component accepte des enfants, utilisez `<slot>` et stylisez le
+  frame dans les styles du composant.
+
+Si une page semble sans style, vous avez probablement utilisé des classes
+globales dans un Shadow DOM component. Déplacez le markup dans une page/layout
+ou déplacez le CSS dans les styles du composant.

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

@@ -1,61 +1,138 @@
 # 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.
+Le starter officiel est la forme canonique d'une application Mado en
+production. Ce n'est pas un framework dans le framework : seulement des
+fichiers, des imports, les primitives Mado et des limites ESLint.
 
 ## Structure
 
 ```txt
 src/
 ├── main.ts
-├── routes.ts
+├── app.routes.ts
 ├── layouts/
-├── pages/
-├── components/
-├── lib/
-└── styles/
+│   ├── app-shell.layout.ts
+│   └── auth-shell.layout.ts
+├── shared/
+│   ├── http/
+│   ├── lib/
+│   ├── styles/
+│   └── ui/
+└── modules/
+    ├── auth/
+    │   ├── auth.routes.ts
+    │   ├── auth.public.ts
+    │   ├── auth.service.ts
+    │   ├── auth.connector.ts
+    │   ├── auth.guard.ts
+    │   ├── login.page.ts
+    │   └── _contracts/
+    └── billing/
+        ├── billing.routes.ts
+        ├── billing.public.ts
+        ├── billing.types.ts
+        ├── api/
+        ├── data/
+        ├── pages/
+        ├── components/
+        └── _contracts/
 ```
 
-`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.
+## App Map
 
-```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.
+`src/app.routes.ts` est la carte de toute l'application. Les modules exportent
+des route maps simples ; les app routes décident quel shell et quel guard
+enveloppent chaque zone.
 
 ```ts
 import { layout, routes } from "@madojs/mado";
-import { requireAuth } from "./lib/auth.js";
+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("./pages/home.js"),
-  "/admin": layout({
-    layout: () => import("./layouts/app.js"),
+  "/": () => 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: { "/": () => import("./pages/admin/dashboard.js") },
+    routes: billingRoutes,
   }),
-  "*": () => import("./pages/not-found.js"),
+  "*": () => import("./modules/home/not-found.page"),
 };
 
 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.
+Rules:
+
+- Export `manifest` pour `mado bake`.
+- Les modules n'appellent jamais `layout()`.
+- Les layouts décrivent des zones d'application, pas des domaines.
+- Ne cachez pas le router dans un custom element ou un second shell dans
+  `main.ts`.
+
+## File Forms
+
+| Suffix | Role |
+| --- | --- |
+| `*.page.ts` | route page, default `page({...})` |
+| `*.layout.ts` | app-zone wrapper, default `page(...)` |
+| `*.connector.ts` | one external API system |
+| `*.resource.ts` | `resource()` and `mutation()` layer |
+| `*.service.ts` | module singleton state |
+| `*.guard.ts` | route guard |
+| `*.routes.ts` | module-local route map |
+| `*.public.ts` | only public module surface |
+| `*.types.ts` | domain types |
+| `*.component.ts` | Web Component registration |
+
+Les signals, resources et forms locaux à une page vivent dans `view()`. L'état
+partagé par un module vit dans `*.service.ts`.
+
+## Data Flow
+
+```txt
+shared/http/http-client.ts
+        ▲
+modules/<x>/api/*.connector.ts      DTO -> domain mapping
+        ▲
+modules/<x>/data/*.resource.ts      cache keys + mutations
+        ▲
+modules/<x>/pages/*.page.ts         UI consumes domain types
+```
+
+## Styles
+
+| File | Role |
+| --- | --- |
+| `src/shared/styles/tokens.css` | design tokens as CSS custom properties |
+| `src/shared/styles/reset.css` | document/light DOM reset |
+| `src/shared/styles/shell.css` | app-zone layouts from `src/layouts/` |
+| `src/shared/styles/content.css` | page-level forms, tables, prose and states |
+
+Les composants feuilles gardent leurs styles dans ``css`...` `` dans les
+options de `component()` et dépendent des tokens, pas de classes globales.
+
+`vite.config.ts` active le transformer Lightning CSS de Vite. Mado ne possède
+pas le prefixing, le lowering CSS ou la minification.
+
+## CLI
 
 ```bash
-mado dev
-mado release
+mado new module billing
+mado new page billing/pages/invoices-list
+mado new connector billing/api/stripe
+mado new resource billing/data/invoices
+mado new service billing/cart
+mado new form billing/invoice
+mado new component billing/components/invoice-status-badge
+mado new guard billing/billing
+mado new layout app-shell
 ```
 
-Le dossier déployable est `out/`. `dist/` est interne.
+Le générateur écrit seulement de nouveaux fichiers. Il ne modifie pas
+`app.routes.ts`.

package/docs/fr/11-layouts.md

@@ -1,23 +1,27 @@
 # Layouts
 
-Le chemin recommandé pour les layouts Mado est un groupe de routes imbriqué
-dans `routes.ts`.
+Le chemin recommandé pour les layouts Mado est un route group dans
+`src/app.routes.ts`. Ne mettez pas un shell global dans `main.ts` si l'app a
+plusieurs zones : public, auth, app, embed.
 
 ```ts
 import { layout, routes } from "@madojs/mado";
-import { requireAuth } from "./lib/auth.js";
+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("./pages/home.js"),
+  "/": () => import("./modules/home/home.page.js"),
   "/login": layout({
-    layout: () => import("./layouts/auth.js"),
-    routes: { "/": () => import("./pages/login.js") },
+    layout: () => import("./layouts/auth-shell.layout.js"),
+    routes: authRoutes,
   }),
-  "/admin": layout({
-    layout: () => import("./layouts/app.js"),
+  "/billing": layout({
+    layout: () => import("./layouts/app-shell.layout.js"),
     guard: requireAuth,
-    routes: { "/": () => import("./pages/admin/dashboard.js") },
+    routes: billingRoutes,
   }),
+  "*": () => import("./modules/home/not-found.page.js"),
 };
 
 export default routes(manifest);
@@ -27,9 +31,17 @@ Un layout est une `page({ view })` qui rend `child` :
 
 ```ts
 export default page({
-  view: ({ child }) => html`<x-app-shell>${child}</x-app-shell>`,
+  view: ({ child }) => html`
+    <div class="layout layout--app">
+      <main class="app-main">${child}</main>
+    </div>
+  `,
 });
 ```
 
-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.
+Rules:
+
+- one shell per route group, not per page;
+- modules export plain route maps and do not call `layout()`;
+- a guard on the group protects the whole subtree;
+- layout view stays stateless; page-local state lives in pages/components/resources.