@madojs/mado 0.11.1 → 0.13.0

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

@@ -1,84 +0,0 @@
-# Project Layout
-
-Каждое Mado-приложение использует одну каноничную форму. Это не примерная
-рекомендация, а соглашение, чтобы люди и AI-ассистенты одинаково понимали,
-куда класть код.
-
-```txt
-my-app/
-├── package.json              # runtime dep: @madojs/mado
-├── tsconfig.json             # strict TS, ES2022, Bundler resolution
-├── vite.config.ts            # mado() from @madojs/mado/vite
-├── index.html                # Vite entry + SPA shell
-├── public/                   # статика: favicon, images, robots.txt
-└── src/
-    ├── 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 |
-| `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.
-
-`index.html` лежит в корне, потому что для Vite это entry template. В
-`public/` кладите только файлы, которые нужно скопировать как есть.
-
-## Куда положить новый файл?
-
-| Что | Куда |
-| --- | --- |
-| Страница на новый 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` |
-
-## Vite Config
-
-```ts
-import { defineConfig } from "vite";
-import { mado } from "@madojs/mado/vite";
-
-export default defineConfig({
-  plugins: [mado()],
-  css: {
-    transformer: "lightningcss",
-  },
-});
-```
-
-Starter включает Vite Lightning CSS transformer. Mado не владеет prefixing,
-CSS lowering или minification.
-
-## Что НЕ кладём в `src/`
-
-- Лишние build-tool configs — настройка живет в `vite.config.ts`.
-- `.env` files — читайте env в `src/shared/lib/config.ts` и импортируйте этот
-  модуль.
-- Tests рядом с кодом — держите их в `test/`.

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

@@ -1,250 +0,0 @@
-# Smart Static (`bake`)
-
-> Выпекание HTML для SEO без runtime SSR. **Идея: данные и view в одном файле, статика на выходе.**
-
-`bake` — это **build-time prerender**, не SSR. На выходе — статические `*.html` файлы, которые любой nginx/Cloudflare раздаёт как обычную статику. На клиенте Web Components оживают и работает SPA-навигация дальше.
-
----
-
-## Когда `bake` подходит
-
-- **Маркетинговые страницы**: лендинги, landing/sub-landings под рекламные кампании, страницы продуктов.
-- **Каталог с относительно стабильным набором страниц**: блог, документация, портфолио, e-commerce до **~10k SKU** с обновлениями реже раза в час.
-- **Контент, общий для всех пользователей**: вся страница одинакова для гостя и для авторизованного юзера (или авторизация дорисовывается через `effect()` уже на клиенте).
-- Нужен **хороший SEO** (rich snippets, OG, JSON-LD) и **быстрый first paint** без поднятия node-серверов в проде.
-
-## Когда `bake` **не** подходит
-
-- **Сотни тысяч страниц с частыми изменениями**. `bake` обходит все `paths` синхронно за один прогон. На 100k+ страниц это минуты ребилда, и инвалидация одной страницы либо требует полного rebake, либо отдельной CI-логики (см. ниже про точечный revalidate).
-- **Персонализированный контент в HTML**. Если на странице должно быть "Привет, Иван" в `<title>` или в meta — это не для `bake`. Авторизованный кабинет, личный фид, корзина с реальными ценами для юзера — оставляйте SPA.
-- **Нужны server-only API в render**: cookies, headers, реальные сетевые запросы к закрытым API. На bake-стороне доступен только `linkedom`, никакого Node-окружения для компонентов.
-- **A/B-тесты и flag'и, которые меняют разметку в первом paint**. `bake` зафиксирует один вариант. Динамику делайте на клиенте через `effect()`.
-- **Real-time / часто меняющиеся данные** (биржевые котировки, остатки на складе минута-в-минуту). `bake.revalidate` — это метаданные, не runtime: фреймворк сам ничего не перевыпекает.
-- Контент **под авторизацией** (admin, internal tools). Незачем; используйте SPA-режим.
-
----
-
-## Концепция
-
-`page({...})` имеет четыре опциональных слота, относящихся к `bake`:
-
-- `head` — meta, OG, JSON-LD.
-- `bake.paths` — список URL-параметров для генерации (build-time, может быть `async`).
-- `bake.data` — данные для конкретного URL (build-time, может быть `async`).
-- `bake.revalidate` — через сколько секунд кэш устарел (записывается в `<meta>`, реальную инвалидацию решает ваша CI/CDN).
-
-Команда `npm run bake` обходит все `page` с `bake`, генерит HTML через `linkedom`, складывает в `out/<path>/index.html`. **Никакого Chromium не нужно** — `linkedom` весит ~50 КБ.
-
----
-
-## Пример
-
-```ts
-// src/pages/product.ts
-import { page, component, html } from "@madojs/mado";
-import { findProduct, products, type Product } from "../lib/products.js";
-
-component("x-product-page", ({ host }) => {
-  return () => {
-    const p = findProduct(host.dataset.slug);
-    return p
-      ? html`<h1>${p.name}</h1><p>${p.description}</p>`
-      : html`<p>Не найдено.</p>`;
-  };
-});
-
-export default page<{ slug: string }, Product | undefined>({
-  title: ({ slug }) => `${findProduct(slug)?.name} — MyShop`,
-
-  head: ({ slug }, baked) => {
-    const p = baked ?? findProduct(slug);
-    if (!p) return {};
-    return {
-      description: p.description,
-      canonical: `/product/${p.slug}`,
-      og: { title: p.name, image: p.image, type: "product" },
-      jsonLd: {
-        "@context": "https://schema.org",
-        "@type": "Product",
-        name: p.name,
-        offers: { "@type": "Offer", price: p.price, priceCurrency: p.currency },
-      },
-    };
-  },
-
-  bake: {
-    paths: () => products.map((p) => ({ slug: p.slug })),
-    data: ({ slug }) => findProduct(slug),
-    revalidate: 3600,
-  },
-
-  view: ({ params }) =>
-    html`<x-product-page data-slug=${params.slug}></x-product-page>`,
-});
-```
-
-```ts
-// src/routes.ts
-import { routes, type RoutesMap } from "@madojs/mado";
-
-// Экспортируем И default (RouterApi для рантайма), И manifest (для bake-скрипта).
-export const manifest: RoutesMap = {
-  "/": () => import("./pages/home.js"),
-  "/product/:slug": () => import("./pages/product.js"),
-  "*": () => import("./pages/not-found.js"),
-};
-
-export default routes(manifest, { titleSuffix: " · MyShop" });
-```
-
-## Запуск
-
-```bash
-npm install -D linkedom vite
-npm run build
-npm run bake
-```
-
-Получаешь:
-
-```
-out/
-├── product/
-│   ├── mado-mug/index.html        ← HTML с meta + JSON-LD
-│   ├── raw-bundler/index.html
-│   └── shadow-dom/index.html
-└── sitemap.xml
-```
-
-## Что внутри сгенерированного HTML
-
-```html
-<head>
-  <title>Mado-кружка — MyShop</title>
-  <meta name="description" content="..." data-mado-head="baked">
-  <link rel="canonical" href="/product/mado-mug" data-mado-head="baked">
-  <meta property="og:title" content="Mado-кружка" data-mado-head="baked">
-  <meta property="og:image" content="..." data-mado-head="baked">
-  <script type="application/ld+json" data-mado-head="baked">
-    {"@context":"https://schema.org","@type":"Product","..."}
-  </script>
-  <meta name="bake-revalidate" content="3600" data-mado-head="baked">
-</head>
-<body>
-  <div id="app">
-    <x-product-page data-slug="mado-mug">
-      <h1>Mado-кружка</h1>
-      <p>Кружка с надписью «zero dependencies».</p>
-      <strong>12 EUR</strong>
-    </x-product-page>
-  </div>
-
-  <!-- предзагруженные данные для гидрации -->
-  <script id="bake" type="application/json">
-    {"slug":"mado-mug","name":"Mado-кружка","price":12,"..."}
-  </script>
-
-  <script type="module" src="/assets/index-HASH.js"></script>
-</body>
-```
-
-После загрузки JS:
-
-1. Web Components `<x-product-page>` оживают (браузер уже знает кастомные элементы).
-2. `page.load()` получает `baked` как initialData — никаких лишних `fetch`.
-3. SPA-навигация работает дальше как обычно.
-
----
-
-## Cookbook: типовые сценарии
-
-### Блог (Markdown → bake)
-
-```ts
-// src/lib/posts.ts
-import { readdirSync, readFileSync } from "node:fs";
-// (этот модуль импортируется только из bake-скрипта,
-// в браузере не должен попасть в граф — выносите в lib/server/ или ifdef'ьте)
-
-export const allPosts = () =>
-  readdirSync("content/blog").map((file) => ({
-    slug: file.replace(/\.md$/, ""),
-    ...parseFrontmatter(readFileSync(`content/blog/${file}`, "utf-8")),
-  }));
-```
-
-```ts
-// src/pages/blog-post.ts
-import { page, html } from "@madojs/mado";
-import { allPosts } from "../lib/posts.js";
-
-export default page<{ slug: string }>({
-  title: ({ slug }) => allPosts().find((p) => p.slug === slug)?.title ?? slug,
-  head: ({ slug }, post) => ({
-    description: post?.excerpt,
-    canonical: `/blog/${slug}`,
-    og: { title: post?.title, type: "article" },
-  }),
-  bake: {
-    paths: () => allPosts().map(({ slug }) => ({ slug })),
-    data: ({ slug }) => allPosts().find((p) => p.slug === slug),
-  },
-  view: ({ params }) =>
-    html`<x-blog-post data-slug=${params.slug}></x-blog-post>`,
-});
-```
-
-### Каталог продуктов (e-commerce, ≤ 10k SKU)
-
-- `bake.paths` → SELECT slug FROM products
-- `bake.data` → SELECT * FROM products WHERE slug=?
-- Полная инвалидация раз в N часов через cron + `npm run bake`
-- Точечная инвалидация одного товара: webhook → пересборка только этого `paths`
-
-### Документация
-
-- `bake.paths` — обход файловой системы `docs/**/*.md`
-- `bake.data` — парсинг Markdown
-- `head.jsonLd` — `TechArticle`
-
----
-
-## Revalidate / CDN
-
-`bake.revalidate: 3600` пишет в HTML `<meta name="bake-revalidate" content="3600">`. Это **метаданные** — фреймворк сам ничего не перевыпекает. Стратегии:
-
-1. **Простейший вариант**: cron в CI — `npm run bake && rsync out/ origin:/var/www/`.
-2. **Через CDN** (Cloudflare/Fastly): кладёте HTML с `Cache-Control: max-age=3600`. CDN сам инвалидирует.
-3. **Webhook-триггер**: API magazin → POST `/_revalidate?path=/product/mado-mug` → CI пере-выпекает только эту страницу (можно сделать `bake.paths`, который возвращает точечный список по env-параметру).
-
----
-
-## Сравнение с альтернативами
-
-|                          | Next.js SSG/ISR    | playwright-prerender | **mado bake** |
-|--------------------------|--------------------|----------------------|-----------------|
-| Нужен Chrome в CI        | нет                | **да** (~300 МБ)     | **нет**         |
-| Нужен node в проде       | для ISR            | нет                  | **нет**         |
-| Время на 1000 страниц    | минуты             | минуты               | **секунды**     |
-| Magic-уровень            | high               | low                  | **zero**        |
-| HTML-парсер              | React-renderer     | браузер              | linkedom (~50 КБ) |
-| Конфигурация             | next.config.js + … | один скрипт          | один скрипт     |
-| Источник правды view+data | разные             | страница             | **одна страница** |
-
----
-
-## Ограничения и подводные камни
-
-- **В bake-стороне нет браузера.** Не работают: `setTimeout` (точнее работает, но bake завершается раньше), `fetch` к относительным URL, любые `effect()`/`signal()` побочки, реальные `requestAnimationFrame`. Render-функция должна быть детерминирована от `params` / `data`.
-- **`linkedom` ≠ браузер.** Не все API DOM поддержаны (например, `HTMLElement.click()` ведёт себя проще). Тяжёлая логика в Web Components будет выполнена только в браузере после `connectedCallback`; в baked HTML попадёт только то, что синхронно отрендерилось при первом проходе.
-- **Динамичный контент дорисовывайте на клиенте.** Текущее время, A/B-тест, гео-баннер, корзина юзера — не должны быть в выпеченном HTML. Используйте `effect()` для дорисовки.
-- **Серверные импорты не должны попадать в клиентский граф.** Если `lib/posts.ts` импортит `node:fs`, его нельзя импортить из `view`. Держите такие модули в отдельной папке (`lib/build/`) и используйте только из `bake.paths`/`bake.data`.
-- **`paths` и `data` исполняются на каждый bake-прогон.** Если за ними тяжёлый запрос к БД — кешируйте на уровне скрипта.
-
----
-
-## TL;DR
-
-Если страница **общая для всех пользователей**, имеет **относительно стабильный набор URL'ов** и важен **SEO + первый paint** — добавьте `bake: { paths, data }` и получите статический HTML с meta/JSON-LD/sitemap за миллисекунды. Без node-сервера, без Chrome, без магии.
-
-Если страница персонализирована, или URL'ов миллион, или контент меняется в реальном времени — `bake` не ваш инструмент. Оставляйте SPA или подключайте отдельный SSR-фреймворк.

package/docs/ru/04-ide-setup.md

@@ -1,144 +0,0 @@
-# IDE-поддержка `html\`\`` и `css\`\``
-
-Из коробки `html\`...\`` и `css\`...\`` — это просто tagged-template-строки. TypeScript их не знает, IDE их не подсвечивает. Это **сознательный компромисс** ради нулевых рантайм-зависимостей и отсутствия билд-плагинов.
-
-Хорошая новость: Mado использует те же конвенции, что и [lit](https://lit.dev), поэтому работают **готовые** IDE-инструменты от lit-экосистемы.
-
----
-
-## VS Code (рекомендованный сетап)
-
-### 1. Установить [lit-plugin](https://marketplace.visualstudio.com/items?itemName=runem.lit-plugin)
-
-VS Code → Extensions → найти **"lit-plugin"** (от runem) → Install.
-
-Что появится:
-
-- Подсветка HTML внутри `html\`\``.
-- Подсветка CSS внутри `css\`\``.
-- Авто-комплит HTML-тегов, атрибутов, событий.
-- Проверка опечаток в атрибутах.
-- Go-to-definition для кастомных элементов (если описаны через `customElements.json` или JSDoc).
-- Diagnostics на неверные binding'и.
-
-### 2. Указать имена тегов
-
-`lit-plugin` ищет идентификаторы `html` и `css` в импортах. Если вы не переименовываете их при импорте — настройка нулевая, всё работает:
-
-```ts
-import { html, css } from "@madojs/mado";
-
-const tpl = html`<button @click=${fn}>${label}</button>`;
-```
-
-### 3. (Опционально) Свои `customElements.json`
-
-Если хотите авто-комплит по своим `<x-*>`-компонентам, опишите их через [Custom Elements Manifest](https://github.com/webcomponents/custom-elements-manifest):
-
-```bash
-npm install --save-dev @custom-elements-manifest/analyzer
-npx cem analyze --globs "src/components/**/*.ts"
-```
-
-Создаст `custom-elements.json`, который `lit-plugin` подхватит автоматически.
-
----
-
-## WebStorm / IntelliJ
-
-WebStorm понимает `html\`\`` и `css\`\`` **из коробки** — нативная поддержка lit-style template-литералов с 2021 года. Никаких плагинов ставить не нужно.
-
-Если подсветка не появляется:
-
-- Settings → Languages & Frameworks → JavaScript → проверить, что включено "Use types from server"
-- Перезагрузить TS-сервер: ⌘+⇧+P → "Restart TypeScript Server"
-
----
-
-## Neovim / Helix
-
-Используйте [`lit-html-server`](https://github.com/runem/lit-analyzer/tree/master/packages/lit-html-server) (LSP-сервер от того же автора, что и lit-plugin):
-
-```bash
-npm install -g lit-html-server
-```
-
-`init.lua` (для `lspconfig`):
-
-```lua
-require('lspconfig').lit_html.setup{
-  cmd = { 'lit-html-server', '--stdio' },
-  filetypes = { 'typescript', 'javascript' },
-}
-```
-
----
-
-## Что НЕ работает (известные ограничения)
-
-- **Type-check биндингов через сигналы.** `html\`<input .value=${count}>\`` — `lit-plugin` ожидает строку, а `count` это `Signal<number>`. Подавляется через `// @ts-expect-error` или комментарием `<!-- @ts-ignore -->`. Будет улучшено в Phase 3+.
-- **Кастомные директивы (`each`)** распознаются как обычные функции — без специальной семантики у плагина.
-- **Атрибуты с префиксами `@`, `.`, `?`** иногда подсвечиваются как ошибки, если в `lit-plugin` отключён `"no-unknown-attribute": false`. В `.vscode/settings.json`:
-
-```json
-{
-  "lit-plugin.rules": {
-    "no-unknown-attribute": "off",
-    "no-incompatible-type-binding": "off"
-  }
-}
-```
-
----
-
-## JSDoc-типизация компонентов
-
-Чтобы IDE подхватывал кастомные элементы внутри `html\`\``, аннотируйте `component()`-определение через JSDoc:
-
-```ts
-/**
- * @element x-counter
- * @attr {number} initial - стартовое значение
- * @fires {CustomEvent<number>} change - на каждое изменение
- */
-component("x-counter", () => {
-  /* ... */
-});
-```
-
-`lit-plugin` это распознаёт и предлагает атрибуты при печати `<x-counter ...>`.
-
----
-
-## Prettier / форматирование
-
-Prettier с **3.0+** форматирует `html\`\`` через [`@prettier/plugin-xml`](https://github.com/prettier/plugin-xml) или встроенный режим. Минимальный `.prettierrc`:
-
-```json
-{
-  "semi": true,
-  "singleQuote": false,
-  "embeddedLanguageFormatting": "auto"
-}
-```
-
-Опция `embeddedLanguageFormatting: "auto"` (default) форматирует содержимое tagged-template-литералов с известными тегами (`html`, `css`).
-
----
-
-## ESLint
-
-Если используете ESLint, плагин [`eslint-plugin-lit`](https://github.com/43081j/eslint-plugin-lit) даёт правила специально под tagged-template-html (а правила [`eslint-plugin-wc`](https://github.com/43081j/eslint-plugin-wc) — под Web Components в целом). Конфигурация — на ваш вкус, не required.
-
----
-
-## TL;DR
-
-| Редактор | Setup | Уровень DX |
-|---|---|---|
-| **VS Code** | поставить `lit-plugin` | ★★★★ |
-| **WebStorm** | ничего | ★★★★ |
-| **Neovim/Helix** | `lit-html-server` через LSP | ★★★ |
-| **Vim без LSP** | вручную | ★ |
-
-Без IDE-плагина Mado тоже работает: `html\`\`` остаётся валидным TS-кодом, всё компилируется и запускается. Просто строка внутри подсвечивается как строка.