@madojs/mado 0.5.1 → 0.6.0

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

@@ -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

@@ -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

@@ -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

@@ -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

@@ -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

@@ -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()`.

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

@@ -0,0 +1,35 @@
+# Bake cookbook
+
+`mado bake` rend certaines routes en HTML statique. C'est pour le SEO et un
+premier rendu rapide, pas pour SSR + hydration.
+
+```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 `each()` sont pour le navigateur.
+
+```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.

package/docs/fr/README.md

@@ -14,3 +14,10 @@ Documentation française.
 | 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) |
+| Architecture d'application | [10-app-architecture.md](./10-app-architecture.md) |
+| Layouts | [11-layouts.md](./11-layouts.md) |
+| Auth et API | [12-auth-and-api.md](./12-auth-and-api.md) |
+| Déploiement | [13-deployment.md](./13-deployment.md) |
+| Tests | [14-testing.md](./14-testing.md) |
+| Gestion des erreurs | [15-error-handling.md](./15-error-handling.md) |
+| Bake cookbook | [16-bake-cookbook.md](./16-bake-cookbook.md) |

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

@@ -0,0 +1,100 @@
+# Архитектура приложения
+
+Базовая форма production-приложения на Mado должна быть скучной: один route
+manifest, один shell, один API-клиент, один auth-модуль и страницы, которые
+импортируют свои компоненты.
+
+## Структура
+
+```txt
+src/
+├── main.ts
+├── routes.ts
+├── layouts/
+│   ├── app.ts
+│   └── auth.ts
+├── pages/
+│   ├── home.ts
+│   ├── login.ts
+│   ├── not-found.ts
+│   └── admin/
+├── components/
+├── lib/
+│   ├── api.ts
+│   └── auth.ts
+└── styles/
+```
+
+`lib/` хранит бизнес-логику, `layouts/` оборачивает группы роутов,
+`components/` хранит переиспользуемые UI-теги, а `pages/` содержит один файл
+на страницу.
+
+## Entry point
+
+```ts
+import { html, render } from "@madojs/mado";
+import "./styles/global.js";
+import "./components/x-button.js";
+import routesApi from "./routes.js";
+
+render(html`${routesApi.view}`, document.getElementById("app")!);
+```
+
+В `main.ts` импортируй только глобальные провайдеры, стили и маленькие общие
+компоненты. Feature-компоненты импортирует страница, которая их рендерит.
+
+## Routes
+
+```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"),
+      "/orders": () => import("./pages/admin/orders.js"),
+    },
+  }),
+  "*": () => import("./pages/not-found.js"),
+};
+
+export default routes(manifest);
+```
+
+`export const manifest` нужен для `mado bake`.
+
+## API, forms, release
+
+Держи один API-клиент и один auth-модуль. Для списков используй `resource()`,
+для записей `mutation(..., { invalidates })`, для форм `useForm()`.
+
+```ts
+const form = useForm({
+  email: { required: true, type: "email" },
+  "items.*.title": { required: true },
+});
+const items = form.array("items");
+```
+
+Разработка:
+
+```bash
+mado dev
+```
+
+Продакшен:
+
+```bash
+mado release
+rsync -avz out/ user@server:/var/www/app/
+```
+
+Деплоится только `out/`. `dist/` — внутренний результат `tsc`.

package/docs/ru/11-layouts.md

@@ -0,0 +1,47 @@
+# Layouts
+
+В Mado blessed-способ для layout — nested route group в `routes.ts`.
+Не заворачивай каждую страницу вручную и не клади общий shell в `main.ts`,
+если в приложении есть разные зоны вроде public/login/admin.
+
+```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"),
+      "/orders": () => import("./pages/admin/orders.js"),
+    },
+  }),
+  "*": () => import("./pages/not-found.js"),
+};
+
+export default routes(manifest);
+```
+
+Layout — это обычная `page({ view })`, которая рендерит `child`:
+
+```ts
+export default page({
+  view: ({ child }) => html`<x-app-shell>${child}</x-app-shell>`,
+});
+```
+
+Правила:
+
+- один shell на группу, не на каждую страницу;
+- outer layouts оборачивают inner layouts;
+- guard на группе защищает всю поддеревянную часть;
+- layout можно lazy-load через `() => import(...)`.
+
+Single-shell wrapper в `main.ts` допустим только для приложений, где абсолютно
+все роуты живут в одной оболочке.

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

@@ -0,0 +1,53 @@
+# Auth and API
+
+Mado не навязывает auth, но starter `admin` дает blessed recipe:
+
+- `src/lib/api.ts` — один HTTP boundary, `ApiError`, refresh-on-401;
+- `src/lib/auth.ts` — `accessToken`, `restoreSession()`, `login()`,
+  `logout()`, `requireAuth` guard.
+
+Модель:
+
+- access token хранится в памяти через `signal`, не в `localStorage`;
+- HttpOnly refresh cookie восстанавливает сессию после reload;
+- все запросы идут через один API-клиент;
+- protected routes закрываются group guard.
+
+```ts
+export const requireAuth: Guard = async ({ path }) => {
+  if (accessToken()) return;
+  if (await restoreSession()) return;
+  return { redirect: `/login?return=${encodeURIComponent(path)}`, replace: true };
+};
+```
+
+В route manifest:
+
+```ts
+"/admin": layout({
+  layout: () => import("./layouts/app.js"),
+  guard: requireAuth,
+  routes: { "/": () => import("./pages/admin/dashboard.js") },
+}),
+```
+
+Backend contract по умолчанию:
+
+| Endpoint | Response | Notes |
+|---|---|---|
+| `POST /api/auth/login` | `{ accessToken }` | ставит HttpOnly refresh cookie |
+| `POST /api/auth/refresh` | `{ accessToken }` | читает refresh cookie |
+| `POST /api/auth/logout` | `204` | очищает cookie |
+
+Для dev proxy:
+
+```jsonc
+{
+  "dev": {
+    "proxy": { "/api": "http://localhost:3000" }
+  }
+}
+```
+
+Если backend использует другую схему auth, меняй только `api.ts`/`auth.ts`.
+Страницы должны оставаться невинными.

package/docs/ru/13-deployment.md

@@ -0,0 +1,60 @@
+# Deployment
+
+Один command, один artifact:
+
+```bash
+mado release
+```
+
+Результат:
+
+```txt
+out/
+├── index.html
+├── assets/
+├── baked/
+├── _redirects
+└── _headers
+```
+
+`out/` можно деплоить на nginx, Cloudflare Pages, Netlify, S3/CloudFront или
+GitHub Pages.
+
+## Preview
+
+```bash
+mado release
+mado preview
+```
+
+`mado preview` сервит `out/` как статический хост: baked HTML имеет приоритет,
+а неизвестные пути падают в SPA fallback.
+
+## VPS + nginx
+
+```bash
+mado release
+rsync -avz --delete out/ user@server:/var/www/myapp/
+```
+
+В репозитории есть production `nginx.conf`: hashed bundles кешируются
+immutably, HTML идет с `no-cache`, deep links работают через SPA fallback.
+
+## Cloudflare / Netlify
+
+```bash
+mado release
+npx wrangler pages deploy out --project-name=myapp
+```
+
+`_redirects` и `_headers` генерируются автоматически.
+
+## Cache rules
+
+| Path | Cache-Control |
+|---|---|
+| `/assets/main-*.js` | `public, max-age=31536000, immutable` |
+| `/*.html` | `no-cache, must-revalidate` |
+| other static files | `public, max-age=86400` |
+
+Если hard refresh на deep link дает 404, проблема в fallback настройке хоста.

package/docs/ru/14-testing.md

@@ -0,0 +1,50 @@
+# Тестирование
+
+Mado — это обычный TypeScript и browser APIs. В репозитории фреймворка тесты
+идут через Node test runner и `linkedom`.
+
+## Команды
+
+```bash
+npm run typecheck
+npm run build
+npm test
+```
+
+Перед merge/release прогоняй все три.
+
+## 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");
+});
+```
+
+Сначала `npm run build`, потом импорт из `dist/`.
+
+## Что покрывать
+
+- signals/computed/effect: scheduling и cleanup;
+- template bindings: children, attrs, events, directives;
+- routes: guards, redirects, scroll/focus, error boundaries;
+- forms: sync/async validation, races, field arrays;
+- resources/mutations: cache keys, invalidation, lifecycle cleanup;
+- CLI: `mado release`, `mado bake`, `mado preview`.
+
+Для реального браузера оставляй маленькие smoke-тесты: открыть страницу,
+кликнуть ссылку или отправить форму, проверить видимый результат.

package/docs/ru/15-error-handling.md

@@ -0,0 +1,56 @@
+# Обработка ошибок
+
+В Mado есть три практичных слоя ошибок: загрузка роутов, загрузка данных и
+действия пользователя.
+
+## Route errors
+
+Глобальная граница:
+
+```ts
+export default routes(manifest, {
+  errorPage: (err) => html`
+    <main>
+      <h1>Что-то пошло не так</h1>
+      <pre>${err.message}</pre>
+      <a data-link href="/">На главную</a>
+    </main>
+  `,
+});
+```
+
+Локальная `page({ errorView })` имеет приоритет над `errorPage`.
+
+## Resource errors
+
+`resource()` дает `error()` и `loading()`. Показывай retry рядом с данными.
+
+```ts
+const users = resource(() => "/api/users", jsonFetcher<User[]>());
+
+html`
+  ${() => users.error()
+    ? html`<p role="alert">${users.error()!.message}</p>
+         <button @click=${users.refresh}>Повторить</button>`
+    : null}
+`;
+```
+
+## Forms and mutations
+
+Ошибки валидации — в `useForm()`. Ошибки записи — рядом с submit-кнопкой.
+
+```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*"],
+});
+```
+
+## Cleanup
+
+Внешние browser subscriptions чисти через `ctx.onDispose()`. `resource()`,
+`effect()` и signals внутри component setup уже привязаны к lifecycle.