@madojs/mado 0.11.0 → 0.12.0

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

@@ -1,65 +0,0 @@
-# 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 les zones d'application et les pages restent
-généralement de simples templates light DOM.
-
-## Règle
-
-Utilisez les route layouts pour les zones d'application :
-
-```ts
-export default page({
-  view: ({ child }) => html`<main class="app-main">${child}</main>`,
-});
-```
-
-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 les page files pour les écrans :
-
-```ts
-export default page({
-  view: () => html`<section><h1>Users</h1></section>`,
-});
-```
-
-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-status-badge", ({ attr }) => {
-  const status = attr("status", "draft");
-  return () => html`<span>${status}</span>`;
-}, {
-  styles: css`
-    :host { display: inline-block; }
-    span { color: var(--color-text-muted); }
-  `,
-});
-```
-
-## Comment les styles se comportent
-
-- `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,138 +0,0 @@
-# Architecture d'application
-
-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
-├── app.routes.ts
-├── layouts/
-│   ├── 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/
-```
-
-## App Map
-
-`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 "./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);
-```
-
-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 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 générateur écrit seulement de nouveaux fichiers. Il ne modifie pas
-`app.routes.ts`.

package/docs/fr/11-layouts.md

@@ -1,47 +0,0 @@
-# Layouts
-
-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 "./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.js"),
-  "/login": layout({
-    layout: () => import("./layouts/auth-shell.layout.js"),
-    routes: authRoutes,
-  }),
-  "/billing": layout({
-    layout: () => import("./layouts/app-shell.layout.js"),
-    guard: requireAuth,
-    routes: billingRoutes,
-  }),
-  "*": () => import("./modules/home/not-found.page.js"),
-};
-
-export default routes(manifest);
-```
-
-Un layout est une `page({ view })` qui rend `child` :
-
-```ts
-export default page({
-  view: ({ child }) => html`
-    <div class="layout layout--app">
-      <main class="app-main">${child}</main>
-    </div>
-  `,
-});
-```
-
-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.

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

@@ -1,76 +0,0 @@
-# Auth et API
-
-Le starter par défaut est la recette recommandée. La mécanique HTTP vit dans
-`src/shared/http/`, l'état auth dans `src/modules/auth/`.
-
-```txt
-src/shared/http/
-  http-client.ts
-  http-error.ts
-  interceptors.ts
-
-src/modules/auth/
-  auth.connector.ts
-  auth.service.ts
-  auth.guard.ts
-  auth.routes.ts
-  auth.public.ts
-  _contracts/
-```
-
-Flow pour un business module :
-
-```txt
-connector -> resource/mutation -> page
-```
-
-Les pages n'importent pas de DTOs et n'appellent pas `fetch()` directement. Les
-connectors n'importent pas la réactivité Mado ou l'UI.
-
-## Auth Service
-
-Auth state est un ES module singleton :
-
-```ts
-const _user = signal<User | null>(null);
-const _token = signal<string | null>(null);
-
-export const user = () => _user();
-export const isAuthed = computed(() => _user() !== null);
-```
-
-Exposez seulement la surface nécessaire via `auth.public.ts`.
-
-## Guards
-
-```ts
-export function requireAuth(): boolean | string {
-  if (isAuthed()) return true;
-  return "/login";
-}
-```
-
-Use in `src/app.routes.ts`:
-
-```ts
-"/billing": layout({
-  layout: () => import("./layouts/app-shell.layout"),
-  guard: requireAuth,
-  routes: billingRoutes,
-}),
-```
-
-## Dev Proxy
-
-```ts
-export default defineConfig({
-  plugins: [mado()],
-  server: {
-    proxy: { "/api": "http://localhost:3000" },
-  },
-});
-```
-
-Rule: `shared/http` connaît HTTP, connectors connaissent un système externe,
-resources connaissent les cache keys, pages connaissent l'UI, `*.public.ts` est
-la surface cross-module.

package/docs/fr/13-deployment.md

@@ -1,57 +0,0 @@
-# Déploiement
-
-Une commande, un artefact déployable :
-
-```bash
-mado release
-```
-
-Résultat :
-
-```txt
-out/
-├── index.html              ← shell SPA ou HTML baked pour /
-├── assets/                 ← assets Vite hashés
-│   ├── *.gz                ← gzip précompressé
-│   └── *.br                ← brotli précompressé
-├── <route>/index.html      ← HTML baked pour les hébergeurs statiques
-├── sitemap.xml             ← sitemap à la racine du site
-├── _redirects              ← fallback SPA Cloudflare Pages / Netlify
-└── _headers                ← règles de cache
-```
-
-Déploie `out/` sur nginx, Cloudflare Pages, Netlify, S3/CloudFront ou GitHub
-Pages. Ne déploie pas `dist/` : c'est un output interne.
-
-## Preview
-
-```bash
-mado release
-mado preview
-```
-
-`mado preview` sert le `out/` final comme un hébergeur statique : fichiers réels
-d'abord (`/<route>/index.html` si la route est baked), fallback SPA ensuite.
-Preview vérifie exactement ce qui sera déployé.
-
-## VPS + nginx
-
-```bash
-mado release
-rsync -avz --delete out/ user@server:/var/www/myapp/
-```
-
-La recette nginx optionnelle vit dans `docs/recipes/nginx/`. Elle gère le cache
-immutable pour `/assets/*`, no-cache pour HTML, et le fallback SPA pour les deep
-links.
-
-## Cloudflare / Netlify
-
-```bash
-mado release
-npx wrangler pages deploy out --project-name=myapp
-```
-
-`_redirects` et `_headers` sont générés automatiquement si tu n'en fournis pas.
-Les routes baked sont promues en vrais fichiers (`out/<route>/index.html`), donc
-l'hébergeur statique les sert avant le fallback SPA.

package/docs/fr/14-testing.md

@@ -1,41 +0,0 @@
-# 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/template.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

@@ -1,50 +0,0 @@
-# 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()`.

package/docs/fr/16-bake-cookbook.md

@@ -1,88 +0,0 @@
-# Bake Cookbook
-
-`mado bake` rend certaines routes en HTML statique. C'est pour le SEO et un
-premier rendu rapide, pas pour SSR + hydration.
-
-## Page Minimale
-
-```ts
-export default page({
-  head: () => ({ title: "Products", description: "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,
-  },
-});
-```
-
-Dans les vues baked, préfère les tableaux simples (`items.map(...)`). Les
-directives runtime comme keyed `each()` sont pour le navigateur.
-
-## Routes Dynamiques
-
-```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),
-  },
-});
-```
-
-Utilise `unsafeHTML()` seulement pour du HTML fiable ou déjà nettoyé.
-
-## Route Manifest
-
-`mado bake` a besoin du manifest source :
-
-```ts
-export const manifest = {
-  "/": () => import("./pages/home.js"),
-  "/blog/:slug": () => import("./pages/blog-post.js"),
-};
-
-export default routes(manifest);
-```
-
-## Output
-
-Standalone `mado bake` écrit les pages baked dans `out/baked/` par défaut.
-`mado release` utilise le shell de production bundlé, garde cette copie
-`out/baked/` pour inspection, promeut le HTML dans les vrais chemins de route
-dans `out/`, et copie le sitemap vers `out/sitemap.xml`.
-
-```bash
-mado release
-tree out
-```
-
-Le dossier déployable est `out/`, pas `dist/`.
-
-## Client Boot
-
-Le HTML baked marque `#app` avec `data-mado-baked`. Ce n'est pas de
-l'hydration : au démarrage, `render()` remplace le DOM baked par les bindings
-vivants de l'application.
-
-## Valeurs Non Supportées
-
-Bake échoue volontairement au lieu d'écrire `[object Object]`. Si une vue baked
-signale une directive non supportée :
-
-- remplace `each()` par `items.map(...)` dans le markup baked ;
-- garde les widgets interactifs dans des routes client-only ;
-- assure-toi que chaque valeur peut être sérialisée en HTML statique.
-
-## Canonical Links
-
-Passe `--base-url` pour que les liens canonical et le sitemap pointent vers la
-production.