@madojs/mado 0.10.0 → 0.11.0

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

@@ -1,35 +1,76 @@
 # Auth et API
 
-Le starter `admin` contient la recette recommandée :
+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/`.
 
-- `src/lib/api.ts` — un seul client HTTP, `ApiError`, refresh après 401 ;
-- `src/lib/auth.ts` — `accessToken`, `restoreSession()`, `login()`,
-  `logout()`, `requireAuth`.
+```txt
+src/shared/http/
+  http-client.ts
+  http-error.ts
+  interceptors.ts
 
-Modèle :
+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.
 
-- 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.
+## Auth Service
+
+Auth state est un ES module singleton :
 
 ```ts
-export const requireAuth: Guard = async ({ path }) => {
-  if (accessToken()) return;
-  if (await restoreSession()) return;
-  return { redirect: `/login?return=${encodeURIComponent(path)}`, replace: true };
-};
+const _user = signal<User | null>(null);
+const _token = signal<string | null>(null);
+
+export const user = () => _user();
+export const isAuthed = computed(() => _user() !== null);
 ```
 
-Dev proxy :
+Exposez seulement la surface nécessaire via `auth.public.ts`.
 
-```jsonc
-{
-  "dev": {
-    "proxy": { "/api": "http://localhost:3000" }
-  }
+## Guards
+
+```ts
+export function requireAuth(): boolean | string {
+  if (isAuthed()) return true;
+  return "/login";
 }
 ```
 
-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.
+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,6 +1,6 @@
 # Déploiement
 
-Une commande, un artefact :
+Une commande, un artefact déployable :
 
 ```bash
 mado release
@@ -10,30 +10,48 @@ Résultat :
 
 ```txt
 out/
-├── index.html
-├── assets/
-├── baked/
-├── _redirects
-└── _headers
+├── 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.
+Pages. Ne déploie pas `dist/` : c'est un output interne.
+
+## Preview
 
 ```bash
 mado release
 mado preview
 ```
 
-`mado preview` sert `out/` comme un hébergeur statique : HTML baked d'abord,
-fallback SPA ensuite.
+`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é.
 
-Pour VPS + nginx :
+## 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.
+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

@@ -22,7 +22,7 @@ globalThis.document = window.document;
 globalThis.Node = window.Node;
 globalThis.HTMLElement = window.HTMLElement;
 
-const { html, render } = await import("../dist/src/html.js");
+const { html, render } = await import("../dist/src/html/template.js");
 
 test("renders", () => {
   const root = document.createElement("div");

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

@@ -1,8 +1,10 @@
-# Bake cookbook
+# 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" }),
@@ -21,15 +23,66 @@ export default page({
 ```
 
 Dans les vues baked, préfère les tableaux simples (`items.map(...)`). Les
-directives runtime comme `each()` sont pour le navigateur.
+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);
 ```
 
-`mado release` produit l'artefact déployable dans `out/`. Si bake signale une
-valeur non supportée, remplace la partie runtime-only ou rends-la côté client.
+## 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.

package/docs/fr/18-api-freeze-map.md

@@ -27,7 +27,7 @@ Ces noms sont publics et protégés par SemVer une fois v1 publiée :
 - Templates et directives : `html`, `render`, `each`, `list`, `unsafeHTML`,
   `ref`, `classMap`, `styleMap`.
 - Composants et CSS : `component`, `css`, `cssVars`.
-- Routage et pages : `routes`, `router`, `page`, `layout`, `nested`,
+- Routage et pages : `routes`, `router`, `page`, `layout`,
   `navigate`, `queryParam`, `prefetchPath`.
 - Data : `resource`, `mutation`, `invalidate`, `jsonFetcher`, `HttpError`.
 - Formulaires : `useForm`.

package/docs/fr/20-v1-stability.md

@@ -26,7 +26,7 @@ Après v1, Mado considère comme protégés par SemVer :
   `ctx.onDispose`.
 - Les contrats router/page/resource/form documentés dans les docs anglaises.
 - Les noms de commandes CLI et leur intention générale (`build`, `dev`,
-  `release`, `bake`, `bundle`, `preview`, `init`, `new`).
+  `release`, `bake`, `preview`, `init`, `new`).
 
 Casser cela nécessite une version majeure.
 

package/docs/recipes/nginx/README.md

@@ -0,0 +1,13 @@
+# Nginx Container Recipe
+
+Optional static deployment recipe for a generated Mado app.
+
+Copy this directory into your app as `docker/`, then build from the app root:
+
+```bash
+docker build -f docker/Containerfile -t myapp .
+docker run --rm -p 8080:80 myapp
+```
+
+The container runs `npm run release` and serves the resulting `out/` directory
+with nginx. This is a recipe, not a framework runtime requirement.

package/docs/ru/00-the-mado-way.md

@@ -2,105 +2,83 @@
 
 > Один правильный путь. Жёсткие контракты. Никакой магии.
 
-Mado — фреймворк для команд, которые строят админки, внутренние инструменты
-и бизнес-SPA — приложения, которые должны быть просты в разработке и скучны
-в поддержке. Для этого он задаёт **набор соглашений**. Если ты следуешь им,
-проект остаётся понятным даже когда в нём 200 экранов и 5 разработчиков. Если
-нарушаешь — типы и линтер скажут об этом сразу.
+Mado — фреймворк для команд, которые строят админки, внутренние инструменты и
+business SPA. Такие приложения должны быть простыми в разработке и скучными в
+поддержке. Поэтому Mado задает соглашения, а не предлагает пять равноценных
+стилей.
 
 ## Принципы
 
-1. **Один способ.** Для каждой задачи — один правильный путь, не пять. Если ты пишешь странное — спроси себя, не существует ли уже идиоматичный хелпер.
-2. **Явность над магией.** Никаких сканеров файлов, неявных глобалов, скрытых side-effects. Всё, что делает фреймворк, можно прочитать в одном файле.
-3. **Платформа сначала.** Если в браузере уже есть фича — используем её напрямую. Своих абстракций над `fetch`, `<form>`, History API, Shadow DOM не плодим.
-4. **Жёсткие типы.** `tsc --strict --noUncheckedIndexedAccess` всегда. Если что-то не типизируется — это сигнал что API кривой.
-5. **Никаких рантайм-зависимостей.** Любая зависимость — обязательство на годы; экосистема Web Components этого не требует.
+1. **Один способ.** Если пишешь что-то необычное, сначала проверь, нет ли уже
+   каноничного helper/API.
+2. **Явность над магией.** Никаких file-system scanners, implicit globals и
+   скрытых side effects.
+3. **Платформа сначала.** Web Components, History API, `<form>`, `fetch` и
+   Shadow DOM остаются платформой, а не прячутся под тяжелыми абстракциями.
+4. **Strict types.** `tsc --strict --noUncheckedIndexedAccess` всегда.
+5. **No runtime dependencies.** Dev/build tooling допустим, runtime Mado
+   остается нативным.
 
-## Соглашения
+## Структура проекта
 
-### Структура проекта
-
-```
+```txt
 src/
-├── routes.ts         ← манифест маршрутов, один файл на проект
-├── main.ts           ← точка входа: провайдеры + монтаж <x-app>
-├── pages/            ← одна страница = один файл = `export default page({...})`
-├── components/       ← переиспользуемые компоненты, side-effect-регистрация
-├── lib/              ← контексты, API-клиенты, бизнес-логика без UI
-└── styles/           ← общие стили (если нужны), .ts с css``
-```
-
-Это **обязательно**, не "по желанию". Если у проекта будет 10 разработчиков — они все должны писать одинаково.
-
-### Один компонент = один файл
-
-```ts
-// src/components/user-card.ts
-import { component, html, css } from "@madojs/mado";
-
-component(
-  "x-user-card",
-  () => {
-    return () => html`<div class="card"><slot /></div>`;
-  },
-  {
-    styles: css`
-      .card {
-        padding: 1rem;
-      }
-    `,
-  },
-);
+├── main.ts           ← boot: global CSS/providers + render router
+├── app.routes.ts     ← readable app map, exports `manifest` + default routes()
+├── layouts/          ← app-zone wrappers (`page({ view: ({ child }) => ... })`)
+├── shared/           ← UI bricks, http client, pure lib, global CSS
+└── modules/          ← bounded contexts
+    └── billing/
+        ├── billing.routes.ts
+        ├── billing.public.ts
+        ├── billing.types.ts
+        ├── pages/
+        ├── data/
+        ├── api/
+        └── _contracts/
 ```
 
-Импорт `import './components/user-card.js'` **регистрирует** компонент через `customElements.define`. Это side-effect. Где компонент нужен — там и импортируем.
-
-### Один способ загрузки данных
+Default starter — каноничная версия этой формы. Если docs и старые примеры
+расходятся, starter и `docs/10-app-architecture.md` главнее.
 
-❌ Не зовём `fetch()` напрямую из компонента. Всегда через:
+## Один компонент = один файл
 
 ```ts
-// чтение → resource
-const user = resource(() => `/api/users/${id()}`, jsonFetcher());
+import { component, css, html } from "@madojs/mado";
 
-// запись → mutation
-const save = mutation(api.save, { invalidates: ["/api/users*"] });
+component("x-user-card", () => () => html`<div class="card"><slot></slot></div>`, {
+  styles: css`
+    .card { padding: 1rem; }
+  `,
+});
 ```
 
-Это даёт кеш, отмену, обработку ошибок, авто-инвалидацию.
+Import component file registers the element. Import it where the tag is used.
 
-### Один способ описать страницу
+## Один способ описать страницу
 
 ```ts
-// src/pages/user-profile.ts
-import { page, html, resource, jsonFetcher } from "@madojs/mado";
+import { html, page, resource, jsonFetcher } from "@madojs/mado";
 
 export default page({
   title: ({ id }) => `User #${id}`,
-  view: ({ params }) => html`...`,
+  view: ({ params }) => {
+    const user = resource(() => `/api/users/${params.id}`, jsonFetcher());
+    return html`...`;
+  },
 });
 ```
 
-Три слота — `title`, `load`, `view`. Других нет. Хочешь что-то ещё — это уже компонент или хелпер.
-
-### Один способ объявить роуты
-
-См. [`01-routing.md`](./01-routing.md).
+Page-local signals, resources and forms live inside `view()`. Module-wide state
+belongs in `*.service.ts`.
 
 ## Чего НЕ делаем
 
-- ❌ Не пишем компоненты без дефиса. Это правило браузера для custom elements: `user-card` ок, `usercard` нет.
-- `x-*` — только convention для примеров и тестов Mado, не брендовый стандарт. В production лучше брать префикс домена: `app-*`, `crm-*`, `ticket-*`, `admin-*`.
-- ❌ Не используем `innerHTML` напрямую. Только через `html\`\``.
-- ❌ Не вызываем `setTimeout`/`setInterval` без cleanup. Только внутри `effect()`.
-- ❌ Не храним глобальный мутируемый state. Используем сигналы и `context`.
-- ❌ Не подключаем pkg без обсуждения. Каждая зависимость — обязательство.
-
-## Когда сомневаешься
-
-Если ты задаёшься вопросом "а как тут лучше?" — это сигнал, что:
-
-1. Либо есть встроенный хелпер, который ты не знаешь (загляни в `docs/`).
-2. Либо это новая ситуация — её надо обсудить и **зафиксировать** в этом документе как ещё одно соглашение.
+- Не используем JSX/Vue/Svelte syntax.
+- Не пишем custom elements без дефиса.
+- Не читаем signals через `.value`; signal читается как function.
+- Не используем `innerHTML` напрямую.
+- Не добавляем runtime packages без обсуждения.
 
-«Лучше единый-окей, чем разный-идеальный.»
+Когда сомневаешься, лучше записать один честный рецепт в docs, чем добавить
+новый primitive в core.