@madojs/mado 0.10.1 → 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

@@ -10,14 +10,11 @@ Résultat :
 
 ```txt
 out/
-├── index.html              ← shell SPA ou HTML baked promu pour /
-├── assets/                 ← bundles hashés (main-ABC.js, chunk-XYZ.js, ...)
+├── index.html              ← shell SPA ou HTML baked pour /
+├── assets/                 ← assets Vite hashés
 │   ├── *.gz                ← gzip précompressé
 │   └── *.br                ← brotli précompressé
-├── baked/                  ← copie de bake pour inspection/debugging
-│   ├── <route>/index.html
-│   └── sitemap.xml
-├── <route>/index.html      ← HTML baked promu pour les hébergeurs statiques
+├── <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
@@ -35,8 +32,7 @@ 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 ne fait plus de mapping virtuel depuis `out/baked/`, donc il vérifie
-exactement ce qui sera déployé.
+Preview vérifie exactement ce qui sera déployé.
 
 ## VPS + nginx
 
@@ -45,8 +41,9 @@ mado release
 rsync -avz --delete out/ user@server:/var/www/myapp/
 ```
 
-Le `nginx.conf` fourni gère le cache immutable pour les bundles hashés, no-cache
-pour HTML, et le 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
 

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

@@ -84,5 +84,5 @@ signale une directive non supportée :
 
 ## Canonical Links
 
-Passe `--base-url` ou configure `bake.baseUrl` dans `mado.config.json` pour que
-les liens canonical et le sitemap pointent vers la production.
+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.

package/docs/ru/01-routing.md

@@ -1,194 +1,119 @@
 # Routing
 
-> Один файл-манифест. Никаких сканеров папок. Никаких спецсимволов.
+> Один app map. Никаких folder scanners. Никаких специальных path symbols.
 
-## Зачем не file-based
+Mado не выводит routes из файлов. Composition должна читаться в одном месте.
 
-В Next/SvelteKit/SolidStart роут возникает «магически» по имени файла. У этого есть плюсы (видно структуру URL по `pages/`), но в проде это означает:
+## App Manifest
 
-- Невидимый плагин-сканер в билде. Без него файлы — просто файлы.
-- Спецсимволы в путях: `[id]`, `(group)`, `_layout`, `+page.svelte`, `...slug`.
-- Server-route vs client-route путаются.
-- Тестировать роутинг — мука: нужен эмулятор сборщика.
-
-Mado считает это **слишком магией**. Мы делаем иначе.
-
-## Манифест
-
-Один файл — `src/routes.ts`. В нём один объект. Читается сверху вниз.
+Используйте `src/app.routes.ts` как карту приложения:
 
 ```ts
-// src/routes.ts
-import { routes } from '@madojs/mado';
-
-export default routes({
-  '/':              () => import('./pages/home.js'),
-  '/about':         () => import('./pages/about.js'),
-  '/users/:id':     () => import('./pages/user-profile.js'),
-  '/users/:id/edit':() => import('./pages/user-edit.js'),
-  '*':              () => import('./pages/not-found.js'),
-});
+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);
 ```
 
-Хочешь увидеть все роуты? Открой `routes.ts`. Никаких сюрпризов.
+Открываешь `app.routes.ts` и видишь все зоны приложения: public pages, auth,
+protected app zones, guards и shells.
 
-## Что справа от пути
+`manifest` экспортируется отдельно, чтобы `mado bake` мог его прочитать.
 
-Любая запись — это **одно из трёх**:
+## Module Routes
 
-### 1. Lazy import (рекомендовано)
+Modules экспортируют plain route maps. Они не вызывают `layout()` и не решают,
+какой shell их оборачивает.
 
 ```ts
-'/posts': () => import('./pages/posts.js'),
+export const billingRoutes = {
+  "/invoices": () => import("./pages/invoices-list.page.js"),
+  "/invoices/:id": () => import("./pages/invoice-detail.page.js"),
+};
 ```
 
-- Браузер сам сделает chunk при бандлинге (esbuild --bundle --splitting).
-- Модуль загрузится только при заходе на роут.
-- Между навигациями результат кэшируется.
+Prefix применяет `src/app.routes.ts`, когда module монтируется под
+`"/billing"`.
 
-### 2. Готовая Page (eager)
+## Layout Group
 
 ```ts
-import about from './pages/about.js';
-
-'/about': about,
+"/admin": layout({
+  layout: () => import("./layouts/app-shell.layout.js"),
+  guard: requireAuth,
+  routes: adminRoutes,
+}),
 ```
 
-Сразу в графе, без задержек. Используй для критичных страниц (home, login).
-
-### 3. Nested с layout
+Layout — обычный `page({...})` file:
 
 ```ts
-import { routes, nested } from '@madojs/mado';
-
-export default routes({
-  '/': () => import('./pages/home.js'),
-
-  '/admin/*': nested({
-    layout: () => import('./layouts/admin.js'),
-    routes: {
-      '':       () => import('./pages/admin/dashboard.js'),
-      'users':  () => import('./pages/admin/users.js'),
-      'logs':   () => import('./pages/admin/logs.js'),
-    },
-  }),
-});
-```
-
-Layout — это **обычный** `page({...})`, который рендерит `ctx.child` куда хочет:
-
-```ts
-// src/layouts/admin.ts
-import { page, html, css, component } from '@madojs/mado';
+import { html, page } from "@madojs/mado";
 
 export default page({
   view: ({ child }) => html`
-    <div class="admin">
-      <aside><nav>...</nav></aside>
-      <main>${child}</main>
+    <div class="layout layout--app">
+      <main class="app-main">${child}</main>
     </div>
   `,
 });
 ```
 
-## Контракт страницы
-
-```ts
-import { page, html, resource, jsonFetcher } from '@madojs/mado';
-
-export default page({
-  title: ({ id }) => `User #${id}`,        // string | (params) => string
-  load:  ({ id }) => resource(...),         // опц., возвращает Resource или данные
-  view:  ({ params, data, path, child }) => html`...`,  // ОБЯЗАТЕЛЬНО
-});
-```
-
-Три слота, всё. Если ты экспортируешь не `page({...})`, а просто функцию — `routes()` кинет понятную ошибку:
-
-```
-[Mado] Lazy-роут не вернул page({...}) как default-экспорт.
-```
+Layout view держим stateless. Page-specific signals, resources и forms живут в
+pages/components/resources, не в layout locals.
 
-## Параметры URL
+## Page Contract
 
 ```ts
-'/users/:id': () => import('./pages/user.js'),
-```
+import { html, page } from "@madojs/mado";
 
-```ts
 export default page<{ id: string }>({
   title: ({ id }) => `User ${id}`,
-  view:  ({ params }) => html`<h1>${params.id}</h1>`,
+  view: ({ params }) => html`<h1>${params.id}</h1>`,
 });
 ```
 
-Типы передаются в `page<Params>` — `tsc` проверит что вы не обратились к `params.foo`, которого нет в роуте.
-
-## Глобальные опции
-
-```ts
-export default routes(
-  { '/': home, '/about': about, '*': nf },
-  {
-    titleSuffix: ' · MyApp',                       // → "Главная · MyApp"
-    loading: () => html`<x-spinner/>`,             // пока модуль грузится
-    error:   (err) => html`<x-fatal-error .err=${err}/>`,
-  },
-);
-```
-
-## Программная навигация
+## Navigation
 
 ```ts
-import route from './routes.js';
+import appRoutes from "./app.routes.js";
 
-route.navigate('/posts');
-route.navigate('/posts?page=2');
-route.navigate('/posts', { replace: true });
+appRoutes.navigate("/billing/invoices");
+appRoutes.navigate("/billing/invoices?page=2");
+appRoutes.navigate("/login", { replace: true });
 ```
 
-Клики по `<a href="/foo" data-link>` перехватываются глобально (без атрибута — браузер сделает full reload, как и положено для внешних ссылок).
-
-## Query-параметры
+## Query Parameters
 
 ```ts
-import { queryParam } from '@madojs/mado';
-
-const page = queryParam('page', '1');
-page();              // '1'
-page.set('2');       // history.replaceState + перерисовка
-page.set(null);      // удалить параметр
-page.set('3', { push: true });   // history.pushState
-```
-
-`queryParam` — обычный сигнал. Использовать можно где угодно: в страницах, компонентах, computed.
-
-## Что осознанно отсутствует
+import { queryParam } from "@madojs/mado";
 
-- ❌ Авто-сканирование `pages/`. **Один файл-манифест явный**.
-- ❌ Спецсимволы в путях (`[id]`, `(group)`, `_layout`). **Параметры — только `:name`, ничего больше**.
-- ❌ Server-side роутинг в этом же манифесте. Mado — клиентский фреймворк.
-- ❌ Auto-prefetch при наведении. Если очень нужно — можно сделать вручную: `link.addEventListener('mouseenter', loader)`. Но обычно лишнее.
-
-## FAQ
-
-**А если у меня 100 роутов? Не разрастётся ли файл?**
-Разрастётся до ~150 строк. Это всё ещё **один источник правды** против сотни файлов в `pages/` с магическими именами. На практике даже у больших проектов (1000+ страниц) можно бить на feature-манифесты:
-
-```ts
-import { routes } from '@madojs/mado';
-import adminRoutes from './features/admin/routes.js';
-import billingRoutes from './features/billing/routes.js';
-
-export default routes({
-  ...adminRoutes,
-  ...billingRoutes,
-  '*': () => import('./pages/not-found.js'),
-});
+const page = queryParam("page", "1");
+page();
+page.set("2");
+page.set(null);
+page.set("3", { push: true });
 ```
 
-**Как тестировать роутинг?**
-Импортируешь `routes.ts` — это просто объект. Подставляешь свой mock-router. Никакой эмуляции сборщика не нужно.
+## Чего нет намеренно
 
-**Code splitting работает?**
-Да. При `esbuild --bundle --splitting --format=esm` каждый `() => import('./pages/x.js')` становится отдельным chunk'ом.
+- Auto-scan of page folders.
+- Filesystem syntax вроде `[id]`, `(group)`, `_layout`.
+- Server routes в client manifest.
+- Hidden layout discovery.