@madojs/mado 0.5.0 → 0.6.0

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/05-why-mado.md

@@ -33,7 +33,7 @@ Mado — не «убийца» React/Vue/Svelte. Это узкоспециали
 | Реактивность | декораторы `@property` + ручной `requestUpdate` | сигналы (`signal`/`computed`/`effect`) из коробки |
 | Роутер | нет, нужно искать (`@lit-labs/router`, etc) | в комплекте: `routes()` + nested + prefetch + sync-cache |
 | Data fetching | нет, нужно собирать | `resource()` + `mutation()` + glob-инвалидация |
-| Формы | нет | `useForm()` на нативной HTML5-валидации |
+| Формы | нет | `useForm()` с HTML-like constraints |
 | SEO / static | сложно (`@lit-labs/ssr`) | `bake` (linkedom) + edge-prerender |
 | Билд | нужен esbuild/rollup/webpack | хватает `tsc` |
 | Стиль кода | классы + декораторы | функции + tagged templates |
@@ -190,4 +190,4 @@ Mado — это **узкий** инструмент с честным позиц
 
 Если хоть один пункт не про вас — берите альтернативу из таблицы выше. Не миритесь с инструментом, который не подходит.
 
-— Автор Mado, бывший React-разработчик, перешедший на бекенд и теперь склеивающий фронт в свободное время.
+— Автор Mado, бывший React-разработчик, перешедший на бекенд и теперь склеивающий фронт в свободное время.

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

@@ -188,7 +188,7 @@ html`<x-counter></x-counter>`
 
 ## Формы — как `form.Validate()` на бекенде
 
-Mado использует **нативную HTML5-валидацию**, plus добавляет state-tracking.
+Mado использует **schema-based validation в духе HTML constraints**, плюс добавляет state-tracking.
 
 ```ts
 import { useForm } from "@madojs/mado";

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

@@ -6,6 +6,19 @@ an application.
 
 ## Rule of Thumb
 
+В Mado layout — это тоже component. Если файл описывает видимую переиспользуемую
+часть UI-дерева — app shell, sidebar, modal, table, page section — по умолчанию
+делайте Web Component через `component()`.
+
+Обычные функции оставляйте для маленьких inline helpers:
+
+```ts
+const money = (value: number) => html`<span>${formatMoney(value)}</span>`;
+```
+
+Не стоит делать app shell функцией в публичных примерах. Это работает, но
+прячет browser model вместо того, чтобы ее объяснять.
+
 Use **Shadow DOM** for leaf widgets:
 
 - buttons, badges, cards, metrics;
@@ -22,6 +35,15 @@ global CSS utilities:
 - components that intentionally share global layout, form and table utilities;
 - places where children should simply remain normal document DOM.
 
+Use **Shadow DOM** для slot-based layouts:
+
+- app shells с `<slot>`;
+- sidebar/content wrappers;
+- reusable layout frames, которые владеют своим grid/header/sidebar CSS.
+
+`<slot>` — это feature Shadow DOM. В компоненте с `shadow: false` тег `<slot>`
+становится обычным DOM-элементом и не переносит children в это место layout.
+
 ## The Footgun
 
 Global CSS does not cross a Shadow DOM boundary.
@@ -90,6 +112,18 @@ component("x-toast-stack", setup);
 This gives backend-admin screens predictable CSS while preserving encapsulation
 for reusable widgets and slot-based shells.
 
+Import model специально browser-native:
+
+```ts
+import "./components/app-layout.js";
+
+render(html`<x-app-layout>${router.view}</x-app-layout>`, app);
+```
+
+Import регистрирует custom element через `customElements.define()`. Template
+создает `<x-app-layout>` element. Дальше браузер сам связывает тег с классом
+компонента. Тут нет React-style component value, который передается как функция.
+
 If a layout does not need slot projection and should be styled entirely by
 global CSS, `shadow: false` can still be a good choice. If it contains
 `<slot>`, keep Shadow DOM and put the shell styles in that component.
@@ -107,6 +141,32 @@ component("x-card-link", () => () => html`
 
 The link can be in Shadow DOM; navigation still stays SPA.
 
+## Где импортировать компоненты
+
+Custom elements становятся глобальными после регистрации, но регистрация все
+равно остается явным JavaScript import.
+
+```ts
+// main.ts: global app frame
+import "./components/app-shell.js";
+
+// pages/tickets.ts: component, которым владеет эта page
+import "../components/ticket-list.js";
+```
+
+Браузер **не** скачивает `ticket-list.js` только потому, что увидел
+`<ticket-list>`. Файл должен быть где-то импортирован. После import он вызывает
+`customElements.define(...)`, и тег становится известен текущему document.
+
+Не стоит bulk-import всех компонентов в `main.ts` "just in case". Для маленьких
+demo это работает, но прячет ownership и ломает lazy route loading. Лучше:
+
+- global app shell/providers импортировать в `main.ts`;
+- components, которыми владеет одна page, импортировать в этой page;
+- shared components feature-а импортировать в feature entry page;
+- truly global leaf components импортировать в `main.ts` только если они реально
+  используются везде.
+
 ## Showcase Lesson
 
 `examples/showcase` uses this split deliberately:

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.

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

@@ -0,0 +1,55 @@
+# Bake cookbook
+
+`mado bake` рендерит выбранные роуты в статический HTML. Это для SEO и быстрого
+первого ответа, не 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,
+  },
+});
+```
+
+В baked views лучше использовать обычные массивы (`items.map(...)`). Runtime
+директивы вроде `each()` нужны браузеру.
+
+## Dynamic routes
+
+```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),
+  },
+});
+```
+
+`unsafeHTML()` используй только для доверенного или заранее очищенного HTML.
+
+## Manifest и output
+
+```ts
+export const manifest = {
+  "/": () => import("./pages/home.js"),
+  "/blog/:slug": () => import("./pages/blog-post.js"),
+};
+export default routes(manifest);
+```
+
+`mado release` создает deploy artifact в `out/`. Если bake ругается на
+unsupported value, значит в статическую страницу попало runtime-only значение:
+замени `each()` на `items.map(...)` или вынеси интерактивный кусок в клиент.

package/docs/ru/README.md

@@ -12,3 +12,10 @@
 | 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) |
+| Архитектура приложения | [10-app-architecture.md](./10-app-architecture.md) |
+| Layouts | [11-layouts.md](./11-layouts.md) |
+| Auth and API | [12-auth-and-api.md](./12-auth-and-api.md) |
+| Deployment | [13-deployment.md](./13-deployment.md) |
+| Тестирование | [14-testing.md](./14-testing.md) |
+| Обработка ошибок | [15-error-handling.md](./15-error-handling.md) |
+| Bake cookbook | [16-bake-cookbook.md](./16-bake-cookbook.md) |

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

@@ -34,8 +34,8 @@ const form = useForm({
 });
 ```
 
-Mado спирається на Constraint Validation API браузера, а не на окрему validation
-екосистему.
+Mado використовує schema-based validation, близьку до HTML constraints, а не
+окрему validation ecosystem.
 
 ## Auth