@madojs/mado 0.11.0 → 0.12.0

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

@@ -1,63 +0,0 @@
-# Shadow DOM vs Light DOM
-
-Mado components используют Shadow DOM по умолчанию. Это хороший default для
-самодостаточных виджетов, но app zones и страницы обычно должны оставаться
-простыми light DOM templates.
-
-## Правило
-
-Используйте route layouts для app zones:
-
-```ts
-export default page({
-  view: ({ child }) => html`<main class="app-main">${child}</main>`,
-});
-```
-
-Такие файлы живут в `src/layouts/` и подключаются в `src/app.routes.ts` через
-`layout()`. Они стилизуются обычным CSS из `src/shared/styles/shell.css`.
-
-Используйте page files для screens:
-
-```ts
-export default page({
-  view: () => html`<section><h1>Users</h1></section>`,
-});
-```
-
-Page-level tables, forms, prose and simple states стилизуются из
-`src/shared/styles/content.css`.
-
-Используйте Shadow DOM components для leaf widgets:
-
-- buttons, badges, cards, metrics;
-- spinners, modals, toasts;
-- widgets, которые должны владеть своим 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); }
-  `,
-});
-```
-
-## Как ведут себя стили
-
-- `tokens.css` задает CSS custom properties; `var(...)` проходит через Shadow
-  DOM.
-- `reset.css`, `shell.css`, `content.css` применяются только к document/light
-  DOM.
-- Class selectors вроде `.data`, `.app-main`, `.error` не проходят внутрь
-  Shadow DOM.
-- Component-local styles пишутся в ``css`...` `` внутри `component()` options.
-- Если Shadow component принимает children, используйте `<slot>` и стилизуйте
-  frame внутри component styles.
-
-Если page выглядит без стилей, почти всегда вы использовали global classes
-внутри Shadow DOM component. Вынесите markup в page/layout или перенесите CSS в
-component styles.

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

@@ -1,152 +0,0 @@
-# Архитектура приложения
-
-Официальный starter — каноничная production-форма Mado-приложения. Это не
-framework внутри framework: только файлы, imports, Mado primitives и ESLint
-boundaries.
-
-## Структура
-
-```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` — карта всего приложения. Modules экспортируют plain route
-maps; app routes решают, какой shell и guard оборачивают каждую зону.
-
-```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`, чтобы `mado bake` мог найти bakeable pages.
-- Modules не вызывают `layout()`.
-- Layouts описывают app zones, не домены.
-- Router не прячется в custom element или втором shell в `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 |
-
-Page-local signals, resources and forms live inside `view()`. Module-wide state
-lives in `*.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
-```
-
-## Module Boundaries
-
-Модуль opaque, кроме `<module>.public.ts`. Другие modules импортируют через этот
-файл или никак. DTO внешних систем лежат в `_contracts/` и остаются private для
-connector.
-
-Default starter enforces this with ESLint:
-
-- no barrels (`index.ts`);
-- no `export *`;
-- no CSS imports outside `src/main.ts`;
-- no cross-module imports except public surfaces;
-- no `_contracts` imports outside connectors.
-
-## 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 |
-
-Reusable leaf components keep their own styles in ``css`...` `` inside
-`component()` options and depend on tokens, not global classes.
-
-`vite.config.ts` opts into Vite Lightning CSS transformer. Mado does not own
-prefixing, CSS lowering or minification.
-
-## CLI
-
-Use `mado new` for boring file scaffolding:
-
-```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
-```
-
-The generator writes files only. It does not edit `app.routes.ts`, does not scan
-the filesystem, and refuses to overwrite existing files.

package/docs/ru/11-layouts.md

@@ -1,47 +0,0 @@
-# Layouts
-
-Blessed layout способ в Mado — route group в `src/app.routes.ts`.
-Не заворачивайте каждую страницу вручную и не кладите общий shell в `main.ts`,
-если есть разные зоны: 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);
-```
-
-Layout — обычный `page({ view })`, который рендерит `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()`;
-- guard on a group protects the whole subtree;
-- layout view stays stateless; page-local state lives in pages/components/resources.

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

@@ -1,75 +0,0 @@
-# Auth and API
-
-Default starter — blessed recipe. HTTP mechanics живут в `src/shared/http/`,
-auth state — в `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 для business module:
-
-```txt
-connector -> resource/mutation -> page
-```
-
-Pages не импортируют DTOs и не вызывают `fetch()` напрямую. Connectors не
-импортируют Mado reactivity или UI.
-
-## Auth Service
-
-Auth state — 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);
-```
-
-Expose only what other modules need through `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` knows HTTP, connectors know one external system, resources
-know cache keys, pages know UI, `*.public.ts` is the cross-module surface.

package/docs/ru/13-deployment.md

@@ -1,66 +0,0 @@
-# Deployment
-
-Одна команда, один deploy artifact:
-
-```bash
-mado release
-```
-
-Результат:
-
-```txt
-out/
-├── index.html              ← SPA shell или baked HTML для /
-├── assets/                 ← Vite hashed assets
-│   ├── *.gz                ← precompressed gzip
-│   └── *.br                ← precompressed brotli
-├── <route>/index.html      ← baked HTML для static hosts
-├── sitemap.xml             ← sitemap в root сайта
-├── _redirects              ← Cloudflare Pages / Netlify SPA fallback
-└── _headers                ← cache rules
-```
-
-`out/` можно деплоить на nginx, Cloudflare Pages, Netlify, S3/CloudFront или
-GitHub Pages. Деплоится только `out/`.
-
-## Preview
-
-```bash
-mado release
-mado preview
-```
-
-`mado preview` сервит финальный `out/` как обычный static host: сначала реальные
-файлы (`/<route>/index.html`, если route был baked), потом SPA fallback в
-`index.html`. Preview проверяет ровно то, что будет загружено на хостинг.
-
-## VPS + nginx
-
-```bash
-mado release
-rsync -avz --delete out/ user@server:/var/www/myapp/
-```
-
-Опциональный nginx-рецепт лежит в `docs/recipes/nginx/`: assets кешируются
-immutable, HTML идет с `no-cache`, deep links работают через SPA fallback.
-
-## Cloudflare / Netlify
-
-```bash
-mado release
-npx wrangler pages deploy out --project-name=myapp
-```
-
-`_redirects` и `_headers` генерируются автоматически, если ты не положил свои.
-Baked routes промотируются в реальные файлы (`out/<route>/index.html`), поэтому
-static host отдаст их до SPA fallback.
-
-## 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

@@ -1,50 +0,0 @@
-# Тестирование
-
-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/template.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

@@ -1,56 +0,0 @@
-# Обработка ошибок
-
-В 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

@@ -1,95 +0,0 @@
-# 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
-директивы вроде keyed `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.
-
-## Route Manifest
-
-`mado bake` нужен source manifest:
-
-```ts
-export const manifest = {
-  "/": () => import("./pages/home.js"),
-  "/blog/:slug": () => import("./pages/blog-post.js"),
-};
-
-export default routes(manifest);
-```
-
-## Output
-
-Standalone `mado bake` по умолчанию пишет baked pages прямо в `out/`.
-`mado release` сначала запускает Vite build, затем bake заменяет route HTML
-на месте и пишет sitemap в `out/sitemap.xml`.
-
-```bash
-mado release
-tree out
-```
-
-Deployable folder — `out/`, не `dist/`.
-
-`mado release --keep-bake-dir` оставляет дополнительную копию `out/baked/`
-только для debugging/inspection.
-
-## Client Boot
-
-Baked HTML помечает `#app` атрибутом `data-mado-baked`. Это не hydration:
-клиентский `render()` заменяет baked DOM живыми bindings при старте приложения.
-Так первый ответ содержит SEO/first-paint HTML, а SPA после загрузки работает
-как обычно.
-
-## Unsupported Values
-
-Bake намеренно падает громко вместо записи `[object Object]`. Если baked view
-ругается на unsupported directive:
-
-- замени `each()` на `items.map(...)` в baked markup;
-- интерактивные виджеты оставь в client-only routes;
-- убедись, что все значения сериализуются в статический HTML.
-
-## Canonical Links
-
-Передай `--base-url`, чтобы canonical links и sitemap указывали на production.
-
-```bash
-mado bake --base-url https://example.com
-mado release --base-url https://example.com
-```