@madojs/mado 0.10.1 → 0.11.0

package/docs/ru/02-project-layout.md

@@ -1,64 +1,84 @@
 # Project Layout
 
-Каждый new-проект на Mado имеет одинаковую структуру. Это **обязательное** соглашение.
+Каждое Mado-приложение использует одну каноничную форму. Это не примерная
+рекомендация, а соглашение, чтобы люди и AI-ассистенты одинаково понимали,
+куда класть код.
 
-```
+```txt
 my-app/
 ├── package.json              # runtime dep: @madojs/mado
 ├── tsconfig.json             # strict TS, ES2022, Bundler resolution
-├── mado.config.json          # dev/build/bake/bundle config
-├── index.html                # SPA shell и template для bake
-├── public/                   # статика (favicon, images, robots.txt)
+├── vite.config.ts            # mado() from @madojs/mado/vite
+├── index.html                # Vite entry + SPA shell
+├── public/                   # статика: favicon, images, robots.txt
 └── src/
-    ├── main.ts               # точка входа: mount router в #app
-    ├── routes.ts             # route manifest (default + named manifest)
-    ├── pages/                # одна страница = один файл = `export default page({...})`
-    ├── components/           # переиспользуемые компоненты (x-*)
-    ├── layouts/              # layout-страницы (для nested)
-    └── lib/
-        ├── api.ts            # все fetch-обёртки
-        ├── contexts.ts       # createContext(...)
-        ├── theme.ts          # темы
-        └── ...               # утилиты, типы, бизнес-правила
+    ├── main.ts               # импорт CSS и mount router в #app
+    ├── app.routes.ts         # app map: manifest + default routes(...)
+    ├── layouts/              # layouts app-зон, не доменные модули
+    ├── shared/               # ui, http, lib, styles
+    └── modules/              # bounded contexts
+        └── billing/
+            ├── billing.routes.ts
+            ├── billing.public.ts
+            ├── billing.types.ts
+            ├── pages/
+            ├── data/
+            ├── api/
+            └── _contracts/
 ```
 
 ## Artifact States
 
 | Folder | Что это | Кто пишет | Deploy? |
-|---|---|---|---|
+| --- | --- | --- | --- |
 | `src/` | исходники TypeScript | ты | no |
-| `dist/` | output `tsc`, native ESM для dev | `mado build` | no |
-| `public/` | авторская статика | ты | через `out/` |
-| `out/` | deploy artifact: SPA shell + bundles + promoted baked HTML | `mado release` | yes |
+| `public/` | статика, копируется как есть | ты | через `out/` |
+| `out/` | deploy artifact: SPA shell + assets + baked HTML | `mado release` | yes |
+
+`mado release` = `typecheck` + Vite build (`out/index.html`, `out/assets/`,
+`public/*`) + `bake` прямо в route paths + `sitemap.xml` + precompression.
 
-`mado release` = `typecheck` + `build` (`dist/`) + `bundle`
-(`out/assets/`) + `bake` (`out/baked/`) + promote baked HTML и
-`sitemap.xml` в deployable `out/` paths + copy `public/*`.
+`index.html` лежит в корне, потому что для Vite это entry template. В
+`public/` кладите только файлы, которые нужно скопировать как есть.
 
 ## Куда положить новый файл?
 
 | Что | Куда |
-|---|---|
-| Страница на новый URL | `src/pages/foo.ts` + добавить в `src/routes.ts` |
-| Переиспользуемая UI-штука | `src/components/foo-bar.ts` |
-| Обёртка над API | `src/lib/api.ts` (добавить метод) |
-| Глобальный контекст (тема, юзер, i18n) | `src/lib/<name>.ts` |
-| Чистая функция без UI | `src/lib/util/<name>.ts` |
+| --- | --- |
+| Страница на новый URL | `src/modules/<module>/pages/<name>.page.ts` + module routes |
+| Module route map | `src/modules/<module>/<module>.routes.ts` |
+| App shell/layout | `src/layouts/<zone>.layout.ts` |
+| Shared UI widget | `src/shared/ui/<x-name>.component.ts` |
+| Module-only UI widget | `src/modules/<module>/components/<name>.component.ts` |
+| API connector | `src/modules/<module>/api/<provider>.connector.ts` |
+| Data resource/mutation | `src/modules/<module>/data/<name>.resource.ts` |
+| Auth/session | `src/modules/auth/` |
+| Public module surface | `src/modules/<module>/<module>.public.ts` |
+| Pure function без UI | `src/shared/lib/<name>.ts` |
+| Static image / favicon | `public/<file>` |
+| App-zone shell CSS | `src/shared/styles/shell.css` |
+| Page-level CSS | `src/shared/styles/content.css` |
 
-Если не понимаешь куда — это сигнал что **архитектура страдает**. Спроси команду, **зафиксируй** ответ в `docs/`.
+## Vite Config
 
-## Правила именования
+```ts
+import { defineConfig } from "vite";
+import { mado } from "@madojs/mado/vite";
+
+export default defineConfig({
+  plugins: [mado()],
+  css: {
+    transformer: "lightningcss",
+  },
+});
+```
 
-| Что | Стиль | Пример |
-|---|---|---|
-| Файл | kebab-case | `user-profile.ts` |
-| Тэг компонента | `x-` + kebab | `<x-user-profile>` |
-| Контекст | PascalCase + `Ctx` | `ThemeCtx`, `AuthCtx` |
-| Сигнал | camelCase | `userId`, `isLoggedIn` |
-| Page-функция (внутренний компонент) | `x-<route>-page` | `<x-posts-page>` |
+Starter включает Vite Lightning CSS transformer. Mado не владеет prefixing,
+CSS lowering или minification.
 
-## Что НЕ кладём в src/
+## Что НЕ кладём в `src/`
 
-- ❌ Конфиги билдеров (webpack, rollup, vite) — у нас их нет.
-- ❌ `.env`-файлы — env читается из `process.env`/`import.meta.env` в `lib/config.ts`.
-- ❌ Тесты вперемешку с кодом — все в `test/`.
+- Лишние build-tool configs — настройка живет в `vite.config.ts`.
+- `.env` files — читайте env в `src/shared/lib/config.ts` и импортируйте этот
+  модуль.
+- Tests рядом с кодом — держите их в `test/`.

package/docs/ru/03-static-bake.md

@@ -100,7 +100,7 @@ export default routes(manifest, { titleSuffix: " · MyShop" });
 ## Запуск
 
 ```bash
-npm install -D linkedom esbuild
+npm install -D linkedom vite
 npm run build
 npm run bake
 ```
@@ -144,7 +144,7 @@ out/
     {"slug":"mado-mug","name":"Mado-кружка","price":12,"..."}
   </script>
 
-  <script type="module" src="/dist/examples/main.js"></script>
+  <script type="module" src="/assets/index-HASH.js"></script>
 </body>
 ```
 

package/docs/ru/05-why-mado.md

@@ -31,11 +31,11 @@ Mado — не «убийца» React/Vue/Svelte. Это узкоспециали
 | Размер | ~6 КБ | ~16 КБ |
 | Возраст / поддержка | ~10 лет, Google | 6 месяцев, один автор |
 | Реактивность | декораторы `@property` + ручной `requestUpdate` | сигналы (`signal`/`computed`/`effect`) из коробки |
-| Роутер | нет, нужно искать (`@lit-labs/router`, etc) | в комплекте: `routes()` + nested + prefetch + sync-cache |
+| Роутер | нет, нужно искать (`@lit-labs/router`, etc) | в комплекте: `routes()` + layout groups + prefetch |
 | Data fetching | нет, нужно собирать | `resource()` + `mutation()` + glob-инвалидация |
 | Формы | нет | `useForm()` с HTML-like constraints |
 | SEO / static | сложно (`@lit-labs/ssr`) | `bake` (linkedom) + edge-prerender |
-| Билд | нужен esbuild/rollup/webpack | хватает `tsc` |
+| Билд | нужны framework-specific build plugins | Vite transport + native runtime |
 | Стиль кода | классы + декораторы | функции + tagged templates |
 | Экосистема | реальная (Shoelace, Material Web, и т.д.) | нет |
 | Когда выбрать | пишете дизайн-систему / Web-Components-библиотеку для встраивания | пишете приложение целиком, хотите всё в одной коробке |
@@ -55,14 +55,14 @@ Mado — не «убийца» React/Vue/Svelte. Это узкоспециали
 | Реактивность | сигналы (тот же класс идей) | сигналы |
 | Шаблоны | JSX (компилируется в реактивные expressions) | tagged template `html\`\`` |
 | Компонентная модель | функции, виртуальные узлы Solid | Web Components |
-| Билд | Vite + babel-plugin-solid обязательны | только `tsc` |
+| Билд | Vite + babel-plugin-solid обязательны | Vite для dev/build, без runtime-зависимостей |
 | Роутер | `@solidjs/router` | в комплекте |
 | Data | `createResource` | `resource()` |
 | SSR | поддерживается серьёзно (SolidStart) | намеренно нет |
 | Экосистема | растёт, ~50 пакетов | нет |
-| Когда выбрать | нужен топовый перф + JSX + готов настраивать билд | хотите запустить без билда / минимум инфраструктуры |
+| Когда выбрать | нужен топовый перф + JSX + готов настраивать билд | нужен browser-native runtime с простым tooling |
 
-**Честный pitch:** *«Solid технически быстрее и зрелее. Но Solid требует Vite + babel-плагин. Mado не требует ничего, кроме `tsc` — это «открой VS Code, F5 и работай». Если эта разница не критична — берите Solid.»*
+**Честный pitch:** *«Solid технически быстрее и зрелее. Mado проще концептуально: browser-native runtime, Web Components, tagged templates, а Vite забирает на себя скучный dev/build. Если нужны JSX и большая экосистема — берите Solid.»*
 
 ---
 
@@ -153,7 +153,7 @@ Mado — не «убийца» React/Vue/Svelte. Это узкоспециали
 
 Не размер, не перф, не сигналы — у всего этого есть конкуренты лучше.
 
-> **«Открой исходник и прочитай его за вечер. ~3500 строк, 12 модулей. Если что-то сломалось — ты не идёшь в issue на 3000 комментариев. Ты идёшь в `src/router.ts` и читаешь 500 строк.»**
+> **«Открой исходник и прочитай его за вечер. ~3500 строк, маленькие модули. Если что-то сломалось — ты не идёшь в issue на 3000 комментариев. Ты идёшь в `src/router/` и читаешь код.»**
 
 Это называется **ownership** — ты владеешь кодом, а не зависишь от чужого.
 

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

@@ -13,7 +13,7 @@ Mado устроен **как HTTP-сервер**. Серьёзно:
 |---|---|
 | HTTP-роутер (chi, axum, mux) | `routes()` — манифест путей |
 | Handler `func(req, resp)` | `page({ view: (ctx) => html\`...\` })` |
-| Middleware | `layout` в `nested()` (оборачивает handler) |
+| Middleware | route group через `layout()` (оборачивает handler) |
 | Шаблонизатор (Jinja, Handlebars) | `html\`\`` tagged template |
 | HTTP-клиент с кешем | `resource()` — fetch + cache + invalidation |
 | Reactive variable / atom | `signal()` — реактивный геттер |
@@ -350,17 +350,17 @@ export default page({
 ```
 
 ```ts
-// src/routes.ts
-import { routes, nested } from "@madojs/mado";
+// src/app.routes.ts
+import { layout, routes } from "@madojs/mado";
 
 export default routes({
   "/login": () => import("./pages/login.js"),
 
-  "/app/*": nested({
+  "/app": layout({
     layout: () => import("./layouts/auth-layout.js"),
     routes: {
-      "dashboard": () => import("./pages/dashboard.js"),
-      "users": () => import("./pages/users.js"),
+      "/dashboard": () => import("./pages/dashboard.js"),
+      "/users": () => import("./pages/users.js"),
     },
   }),
 });
@@ -423,6 +423,6 @@ export const api = new ApiClient("/api");
 - **[`01-routing.md`](./01-routing.md)** — детально про роутер.
 - **[`02-project-layout.md`](./02-project-layout.md)** — структура проекта.
 - **[`03-static-bake.md`](./03-static-bake.md)** — SEO без SSR.
-- **[`examples/showcase/`](../../examples/showcase/)** — полный пример (landing + admin).
+- **Внешний workspace `madojs-examples`** — полные демо (landing + admin).
 
 Если что-то непонятно — open issue, или просто открой исходник. Это правда читается за вечер.

package/docs/ru/08-llm-zero-history-test.md

@@ -13,15 +13,15 @@
 - `AGENTS.md`
 - `README.md`
 - `docs/en/07-llm-pitfalls.md`
-- `examples/basic/README.md` если нужен минимальный обзор API
-- конкретные файлы из `examples/showcase/**` только если агент сам попросит паттерн более крупного приложения
+- файлы из внешнего workspace `madojs-examples` только если агент сам попросит
+  паттерн более крупного приложения
 
 Агент может искать целевые API в `src/` когда заблокирован, но не должен
 загружать весь фреймворк в контекст.
 
 ## Задание
 
-Построить `examples/tickets`: маленький ticket-admin SPA для соло/бекенд-разработчика.
+Построить маленький ticket-admin SPA для соло/бекенд-разработчика.
 
 Требуемое поведение:
 
@@ -48,15 +48,10 @@
 
 ## Заметки по результатам
 
-Текущая реализация `examples/tickets` не потребовала новых публичных API или
-runtime-зависимостей.
+Историческая реализация tickets живет во внешнем workspace `madojs-examples`.
+Core-репозиторий больше не поставляет этот артефакт и отдельную smoke-команду;
+используйте этот документ как ручной сценарий оценки при обновлении LLM-guidance.
 
-CI запускает `npm run llm:smoke` как детерминированный proxy для этой задачи:
-проверяет, что `llms.txt` всё ещё содержит ключевые правила, сверяет
-зафиксированный артефакт `examples/tickets` с нужной Mado API surface и
-failure patterns, затем собирает проект и запускает `test/tickets-smoke.test.mjs`.
-
-Основная болевая точка в документации остается lifecycle: старые примеры могут
-создать впечатление, что создание `resource()` прямо в `page.view()` допустимо.
-Пример tickets использует page-level wrapper-компоненты вместо этого, поэтому
-ресурсы регистрируются внутри component setup и очищаются вместе с компонентом.
+Основная болевая точка в документации остается lifecycle: примеры не должны
+создавать впечатление, что long-lived `resource()` можно случайно держать на
+module scope или в route-коде без cleanup.

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.