@madojs/mado 0.10.0 → 0.11.0

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

@@ -1,198 +1,63 @@
 # Shadow DOM vs Light DOM
 
-Компоненты Mado по умолчанию используют Shadow DOM. Это хороший дефолт для
-самодостаточных виджетов, но не для каждого компонента в приложении.
+Mado components используют Shadow DOM по умолчанию. Это хороший default для
+самодостаточных виджетов, но app zones и страницы обычно должны оставаться
+простыми light DOM templates.
 
-## Правило большого пальца
+## Правило
 
-В Mado layout — это тоже component. Если файл описывает видимую переиспользуемую
-часть UI-дерева — app shell, sidebar, modal, table, page section — по умолчанию
-делайте Web Component через `component()`.
-
-Обычные функции оставляйте для маленьких inline helpers:
+Используйте route layouts для app zones:
 
 ```ts
-const money = (value: number) => html`<span>${formatMoney(value)}</span>`;
+export default page({
+  view: ({ child }) => html`<main class="app-main">${child}</main>`,
+});
 ```
 
-Не стоит делать app shell функцией в публичных примерах. Это работает, но
-прячет browser model вместо того, чтобы её объяснять.
-
-Используйте **Shadow DOM** для leaf-виджетов:
-
-- кнопки, бейджи, карточки, метрики;
-- модалы, тосты, маленькие визуальные компоненты;
-- embed-виджеты, которые не должны наследовать CSS приложения случайно;
-- компоненты, стили которых принадлежат самому компоненту.
-
-Используйте **Light DOM** (`{ shadow: false }`) для структуры приложения,
-которая хочет разделять глобальные CSS-утилиты:
-
-- route/page компоненты;
-- admin-экраны с плотными таблицами/формами;
-- data-heavy экраны с таблицами и формами;
-- компоненты, которые намеренно используют глобальные layout/form/table утилиты;
-- места, где children должны оставаться обычным document DOM.
-
-Используйте **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.
-
-## Подвох
-
-Глобальный CSS не пересекает границу Shadow DOM.
-
-```ts
-// global.ts
-export const globalStyles = css`
-  .page-head {
-    display: flex;
-    justify-content: space-between;
-  }
-  .metric-grid {
-    display: grid;
-    grid-template-columns: repeat(4, 1fr);
-  }
-`;
-
-// ❌ .page-head и .metric-grid НЕ применятся внутри shadowRoot x-dashboard
-component(
-  "x-dashboard",
-  () => () => html`
-    <header class="page-head">...</header>
-    <div class="metric-grid">...</div>
-  `,
-);
-```
+Такие файлы живут в `src/layouts/` и подключаются в `src/app.routes.ts` через
+`layout()`. Они стилизуются обычным CSS из `src/shared/styles/shell.css`.
 
-Решение — сделать route/page компонент Light DOM:
+Используйте page files для screens:
 
 ```ts
-component(
-  "x-dashboard",
-  () => () => html`
-    <header class="page-head">...</header>
-    <div class="metric-grid">...</div>
-  `,
-  {
-    shadow: false,
-    styles: css`
-      x-dashboard {
-        display: block;
-      }
-      x-dashboard .panel {
-        padding: 1rem;
-      }
-    `,
-  },
-);
+export default page({
+  view: () => html`<section><h1>Users</h1></section>`,
+});
 ```
 
-Теперь глобальные утилиты и локальные scoped-стили работают вместе.
-
-## Как ведут себя стили
+Page-level tables, forms, prose and simple states стилизуются из
+`src/shared/styles/content.css`.
 
-- `styles: css\`\`` в Shadow DOM адоптируется в shadowRoot компонента.
-- `styles: css\`\``с`shadow: false` скоупится по имени тега и адоптируется
-  глобально.
-- CSS custom properties (`--accent`, `--bg` и т.д.) пересекают границу Shadow DOM.
-- Селекторы по классу (`.btn`, `.form-grid`, `.page-head`) **не** пересекают
-  границу Shadow DOM.
-- Slotted-children сохраняют свои стили из документа; shadow-компонент может
-  таргетировать их только через `::slotted(...)`.
-- `<slot>` проецирует children только в Shadow DOM. В компоненте с `shadow: false`
-  это обычный `<slot>` элемент, который не перемещает children в своё место.
+Используйте Shadow DOM components для leaf widgets:
 
-## Рекомендованная архитектура
+- buttons, badges, cards, metrics;
+- spinners, modals, toasts;
+- widgets, которые должны владеть своим CSS.
 
 ```ts
-// root и pages: Light DOM
-component("x-app", setup, { shadow: false });
-component("x-users-page", setup, { shadow: false });
-
-// slot-based layout: Shadow DOM по умолчанию, потому что владеет shell grid
-component("x-app-layout", setup);
-
-// leaf widgets: Shadow DOM по умолчанию
-component("x-status-badge", setup);
-component("x-stat-card", setup);
-component("x-toast-stack", setup);
-```
-
-Это даёт backend-admin экранам предсказуемый CSS, сохраняя инкапсуляцию
-для переиспользуемых виджетов и 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>` элемент. Дальше браузер сам связывает тег с классом
-компонента. Тут нет React-style component value, который передаётся как функция.
-
-Если layout не нуждается в slot projection и должен стилизоваться полностью
-глобальным CSS, `shadow: false` — хороший выбор. Если он содержит `<slot>`,
-оставьте Shadow DOM и поместите стили shell в этот компонент.
-
-## Маршрутизация и ссылки
-
-`data-link` работает внутри Shadow DOM. Роутер использует `event.composedPath()`,
-поэтому перехват кликов и hover-prefetch видят ссылки из open shadow roots.
-
-```ts
-component(
-  "x-card-link",
-  () => () => html` <a href="/app/accounts" data-link>Accounts</a> `,
-);
-```
-
-Ссылка может быть внутри Shadow DOM — навигация всё равно остаётся 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";
+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); }
+  `,
+});
 ```
 
-Браузер **не** скачивает `ticket-list.js` только потому, что увидел
-`<ticket-list>`. Файл должен быть где-то импортирован. После import он вызывает
-`customElements.define(...)`, и тег становится известен текущему document.
-
-Не стоит bulk-import всех компонентов в `main.ts` «на всякий случай». Для маленьких
-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
-
-`examples/showcase` использует это разделение намеренно:
-
-- `x-app` и CRM route pages — Light DOM;
-- `x-app-layout` остаётся в Shadow DOM, потому что владеет slot-based
-  sidebar/content shell;
-- table/form/page утилиты живут в `styles/global.ts`;
-- leaf-компоненты типа `x-stat-card`, `x-status-badge`, `x-modal` и
-  `x-toast-stack` остаются в Shadow DOM.
+## Как ведут себя стили
 
-Если страница внезапно выглядит без стилей, проверьте — не используете ли вы
-глобальные классы внутри Shadow DOM компонента. Обычно проблема именно в этом.
+- `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,100 +1,152 @@
 # Архитектура приложения
 
-Базовая форма production-приложения на Mado должна быть скучной: один route
-manifest, один shell, один API-клиент, один auth-модуль и страницы, которые
-импортируют свои компоненты.
+Официальный starter — каноничная production-форма Mado-приложения. Это не
+framework внутри framework: только файлы, imports, Mado primitives и ESLint
+boundaries.
 
 ## Структура
 
 ```txt
 src/
 ├── main.ts
-├── routes.ts
+├── app.routes.ts
 ├── layouts/
-│   ├── app.ts
-│   └── auth.ts
-├── pages/
-│   ├── home.ts
-│   ├── login.ts
-│   ├── not-found.ts
-│   └── admin/
-├── components/
-├── lib/
-│   ├── api.ts
-│   └── auth.ts
-└── styles/
+│   ├── 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/
 ```
 
-`lib/` хранит бизнес-логику, `layouts/` оборачивает группы роутов,
-`components/` хранит переиспользуемые UI-теги, а `pages/` содержит один файл
-на страницу.
+## App Map
 
-## 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
+`src/app.routes.ts` — карта всего приложения. Modules экспортируют plain route
+maps; app routes решают, какой shell и guard оборачивают каждую зону.
 
 ```ts
 import { layout, routes } from "@madojs/mado";
-import { requireAuth } from "./lib/auth.js";
+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("./pages/home.js"),
+  "/": () => import("./modules/home/home.page"),
   "/login": layout({
-    layout: () => import("./layouts/auth.js"),
-    routes: { "/": () => import("./pages/login.js") },
+    layout: () => import("./layouts/auth-shell.layout"),
+    routes: authRoutes,
   }),
-  "/admin": layout({
-    layout: () => import("./layouts/app.js"),
+  "/billing": layout({
+    layout: () => import("./layouts/app-shell.layout"),
     guard: requireAuth,
-    routes: {
-      "/": () => import("./pages/admin/dashboard.js"),
-      "/orders": () => import("./pages/admin/orders.js"),
-    },
+    routes: billingRoutes,
   }),
-  "*": () => import("./pages/not-found.js"),
+  "*": () => import("./modules/home/not-found.page"),
 };
 
 export default routes(manifest);
 ```
 
-`export const manifest` нужен для `mado bake`.
+Rules:
 
-## API, forms, release
+- Export `manifest`, чтобы `mado bake` мог найти bakeable pages.
+- Modules не вызывают `layout()`.
+- Layouts описывают app zones, не домены.
+- Router не прячется в custom element или втором shell в `main.ts`.
 
-Держи один API-клиент и один auth-модуль. Для списков используй `resource()`,
-для записей `mutation(..., { invalidates })`, для форм `useForm()`.
+## File Forms
 
-```ts
-const form = useForm({
-  email: { required: true, type: "email" },
-  "items.*.title": { required: true },
-});
-const items = form.array("items");
-```
+| 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`.
 
-```bash
-mado dev
+## 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 release
-rsync -avz out/ user@server:/var/www/app/
+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
 ```
 
-Деплоится только `out/`. `dist/` — внутренний результат `tsc`.
+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 +1,47 @@
 # Layouts
 
-В Mado blessed-способ для layout — nested route group в `routes.ts`.
-Не заворачивай каждую страницу вручную и не клади общий shell в `main.ts`,
-если в приложении есть разные зоны вроде public/login/admin.
+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 "./lib/auth.js";
+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("./pages/home.js"),
+  "/": () => import("./modules/home/home.page.js"),
   "/login": layout({
-    layout: () => import("./layouts/auth.js"),
-    routes: { "/": () => import("./pages/login.js") },
+    layout: () => import("./layouts/auth-shell.layout.js"),
+    routes: authRoutes,
   }),
-  "/admin": layout({
-    layout: () => import("./layouts/app.js"),
+  "/billing": layout({
+    layout: () => import("./layouts/app-shell.layout.js"),
     guard: requireAuth,
-    routes: {
-      "/": () => import("./pages/admin/dashboard.js"),
-      "/orders": () => import("./pages/admin/orders.js"),
-    },
+    routes: billingRoutes,
   }),
-  "*": () => import("./pages/not-found.js"),
+  "*": () => import("./modules/home/not-found.page.js"),
 };
 
 export default routes(manifest);
 ```
 
-Layout — это обычная `page({ view })`, которая рендерит `child`:
+Layout — обычный `page({ view })`, который рендерит `child`:
 
 ```ts
 export default page({
-  view: ({ child }) => html`<x-app-shell>${child}</x-app-shell>`,
+  view: ({ child }) => html`
+    <div class="layout layout--app">
+      <main class="app-main">${child}</main>
+    </div>
+  `,
 });
 ```
 
-Правила:
+Rules:
 
-- один shell на группу, не на каждую страницу;
-- outer layouts оборачивают inner layouts;
-- guard на группе защищает всю поддеревянную часть;
-- layout можно lazy-load через `() => import(...)`.
-
-Single-shell wrapper в `main.ts` допустим только для приложений, где абсолютно
-все роуты живут в одной оболочке.
+- 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,53 +1,75 @@
 # Auth and API
 
-Mado не навязывает auth, но starter `admin` дает blessed recipe:
+Default starter — blessed recipe. HTTP mechanics живут в `src/shared/http/`,
+auth state — в `src/modules/auth/`.
 
-- `src/lib/api.ts` — один HTTP boundary, `ApiError`, refresh-on-401;
-- `src/lib/auth.ts` — `accessToken`, `restoreSession()`, `login()`,
-  `logout()`, `requireAuth` guard.
+```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.
 
-- access token хранится в памяти через `signal`, не в `localStorage`;
-- HttpOnly refresh cookie восстанавливает сессию после reload;
-- все запросы идут через один API-клиент;
-- protected routes закрываются group guard.
+## Auth Service
+
+Auth state — 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);
 ```
 
-В route manifest:
+Expose only what other modules need through `auth.public.ts`.
+
+## Guards
 
 ```ts
-"/admin": layout({
-  layout: () => import("./layouts/app.js"),
-  guard: requireAuth,
-  routes: { "/": () => import("./pages/admin/dashboard.js") },
-}),
+export function requireAuth(): boolean | string {
+  if (isAuthed()) return true;
+  return "/login";
+}
 ```
 
-Backend contract по умолчанию:
+Use in `src/app.routes.ts`:
 
-| Endpoint | Response | Notes |
-|---|---|---|
-| `POST /api/auth/login` | `{ accessToken }` | ставит HttpOnly refresh cookie |
-| `POST /api/auth/refresh` | `{ accessToken }` | читает refresh cookie |
-| `POST /api/auth/logout` | `204` | очищает cookie |
+```ts
+"/billing": layout({
+  layout: () => import("./layouts/app-shell.layout"),
+  guard: requireAuth,
+  routes: billingRoutes,
+}),
+```
 
-Для dev proxy:
+## Dev Proxy
 
-```jsonc
-{
-  "dev": {
-    "proxy": { "/api": "http://localhost:3000" }
-  }
-}
+```ts
+export default defineConfig({
+  plugins: [mado()],
+  server: {
+    proxy: { "/api": "http://localhost:3000" },
+  },
+});
 ```
 
-Если backend использует другую схему auth, меняй только `api.ts`/`auth.ts`.
-Страницы должны оставаться невинными.
+Rule: `shared/http` knows HTTP, connectors know one external system, resources
+know cache keys, pages know UI, `*.public.ts` is the cross-module surface.