@madojs/mado 0.5.0

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

@@ -0,0 +1,144 @@
+# 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-кодом, всё компилируется и запускается. Просто строка внутри подсвечивается как строка.

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

@@ -0,0 +1,193 @@
+# Why Mado (and why not Lit / Solid / Alpine / htmx)
+
+> Если ты выбираешь фронт-стек для нового проекта, эта страница для тебя.  
+> Если у тебя уже что-то работает — **не мигрируй ради миграции**, это всегда дороже, чем кажется.
+
+Mado — не «убийца» React/Vue/Svelte. Это узкоспециализированный инструмент. Здесь я честно объясняю, **в каких случаях Mado действительно лучше альтернатив**, а в каких — нет.
+
+---
+
+## TL;DR — одной таблицей
+
+| Если вам важно… | Берите |
+|---|---|
+| Лучшая обучающая инфраструктура / огромная экосистема | **React** или **Vue** |
+| Дизайн-система компонентов для встраивания в любые фреймворки | **Lit** |
+| Топовый перфоманс на больших списках, "близкий к ванилле" с JSX | **Solid** или **Svelte 5** |
+| Прогрессивное улучшение классических серверных приложений | **htmx** + ваш бек |
+| "Украшение" статического сайта реактивностью | **Alpine.js** |
+| Минимум инструмента, максимум платформы, всё в одной коробке (роутер + data + формы + SEO), читается за вечер | **Mado** ✓ |
+
+Если ваш кейс не попадает в последний пункт — Mado скорее всего не лучший выбор. Это нормально.
+
+---
+
+## Mado vs Lit
+
+**Lit** — самая близкая по духу альтернатива. Тот же подход: Web Components + tagged templates + минимум магии.
+
+| | Lit | Mado |
+|---|---|---|
+| Размер | ~6 КБ | ~16 КБ |
+| Возраст / поддержка | ~10 лет, Google | 6 месяцев, один автор |
+| Реактивность | декораторы `@property` + ручной `requestUpdate` | сигналы (`signal`/`computed`/`effect`) из коробки |
+| Роутер | нет, нужно искать (`@lit-labs/router`, etc) | в комплекте: `routes()` + nested + prefetch + sync-cache |
+| Data fetching | нет, нужно собирать | `resource()` + `mutation()` + glob-инвалидация |
+| Формы | нет | `useForm()` на нативной HTML5-валидации |
+| SEO / static | сложно (`@lit-labs/ssr`) | `bake` (linkedom) + edge-prerender |
+| Билд | нужен esbuild/rollup/webpack | хватает `tsc` |
+| Стиль кода | классы + декораторы | функции + tagged templates |
+| Экосистема | реальная (Shoelace, Material Web, и т.д.) | нет |
+| Когда выбрать | пишете дизайн-систему / Web-Components-библиотеку для встраивания | пишете приложение целиком, хотите всё в одной коробке |
+
+**Честный pitch:** *«Lit — лучше, если ты пишешь дизайн-систему компонентов. Mado — лучше, если ты пишешь приложение и хочешь батарейки в коробке без сборки 8 пакетов.»*
+
+---
+
+## Mado vs Solid
+
+**Solid** — топовая реактивная либа на сигналах. Технически очень крутая.
+
+| | Solid | Mado |
+|---|---|---|
+| Размер | ~7 КБ | ~16 КБ |
+| Перфоманс | топ-3 на js-framework-benchmark | хорошо, но не топ |
+| Реактивность | сигналы (тот же класс идей) | сигналы |
+| Шаблоны | JSX (компилируется в реактивные expressions) | tagged template `html\`\`` |
+| Компонентная модель | функции, виртуальные узлы Solid | Web Components |
+| Билд | Vite + babel-plugin-solid обязательны | только `tsc` |
+| Роутер | `@solidjs/router` | в комплекте |
+| Data | `createResource` | `resource()` |
+| SSR | поддерживается серьёзно (SolidStart) | намеренно нет |
+| Экосистема | растёт, ~50 пакетов | нет |
+| Когда выбрать | нужен топовый перф + JSX + готов настраивать билд | хотите запустить без билда / минимум инфраструктуры |
+
+**Честный pitch:** *«Solid технически быстрее и зрелее. Но Solid требует Vite + babel-плагин. Mado не требует ничего, кроме `tsc` — это «открой VS Code, F5 и работай». Если эта разница не критична — берите Solid.»*
+
+---
+
+## Mado vs Svelte 5
+
+**Svelte 5** с runes — тоже сигнальная модель, тоже минималистичная.
+
+| | Svelte 5 | Mado |
+|---|---|---|
+| Размер runtime | ~3 КБ | ~16 КБ |
+| Компилятор | обязателен (.svelte → JS) | нет |
+| Синтаксис | свой .svelte формат | TS + tagged templates |
+| Реактивность | `$state`/`$derived` (runes) | `signal`/`computed` |
+| SSR / SvelteKit | полноценная, mature | намеренно нет |
+| Экосистема | большая, dev-tools отличные | нет |
+| Когда выбрать | новый продакшен проект с командой | приватный/внутренний инструмент, нужна простота |
+
+**Честный pitch:** *«Svelte — продуктовый выбор. Mado — инженерный. Если у вас команда и продакшен — Svelte. Если вы один и хотите контроль — Mado.»*
+
+---
+
+## Mado vs htmx
+
+**htmx** — другая школа: HTML-fragments over the wire.
+
+| | htmx | Mado |
+|---|---|---|
+| Архитектура | HTML с сервера, обновление через fragments | SPA: JS грузит данные, рендерит сам |
+| Зависит от бека | сильно (бек должен уметь отдавать HTML) | слабо (бек — JSON API) |
+| State на клиенте | минимальный (cookies, localStorage) | полноценный (signal, persisted) |
+| Optimistic updates | сложно | легко (mutation + invalidates) |
+| Offline / PWA | плохо | нормально |
+| Размер | ~14 КБ | ~16 КБ |
+| Когда выбрать | классическое серверное приложение (Rails, Django, Phoenix), нужно «оживить» | SPA-опыт обязателен, бек — REST/GraphQL |
+
+**Честный pitch:** *«htmx — если бек крепкий и умеет HTML. Mado — если бек отдаёт JSON, а вам нужен полноценный SPA-опыт.»*
+
+---
+
+## Mado vs Alpine.js
+
+**Alpine** — реактивные атрибуты прямо в HTML.
+
+| | Alpine | Mado |
+|---|---|---|
+| Назначение | украшение статического HTML | полноценное SPA |
+| Размер | ~7 КБ | ~16 КБ |
+| State management | `x-data` локально | сигналы + context + persisted |
+| Роутинг | нет | в комплекте |
+| TypeScript | плохо | first-class |
+| Когда выбрать | статика, лендинги, нужны 5 интерактивных кнопок | full app: страницы, навигация, формы, data |
+
+**Честный pitch:** *«Alpine — для интерактива на статике. Mado — для полноценного приложения.»*
+
+---
+
+## Mado vs React + ecosystem
+
+Я не буду долго на этом останавливаться, потому что React — это **другая весовая категория** по экосистеме и зрелости. Но если вы серьёзно сравниваете:
+
+**React выигрывает:**
+- огромная экосистема: тысячи UI-китов, тысячи статей, бесконечные туториалы;
+- AI-помощники (ChatGPT, Copilot) знают React лучше всех;
+- лучший job market;
+- лучшая поддержка SSR (Next.js).
+
+**Mado выигрывает:**
+- размер бандла в десятки раз меньше;
+- нулевая инфраструктура (нет Vite, нет Babel, нет 200 пакетов);
+- читается за вечер — если что-то сломалось, открой `src/`;
+- сигналы вместо хуков (нет правил «нельзя в if», нет stale-closure ловушек);
+- не нужно мигрировать с major на major.
+
+**Когда выбрать Mado вместо React:**
+- проект на 1-3 человек, на годы вперёд;
+- размер бандла критичен;
+- вы устали от React-усталости и готовы пожертвовать экосистемой ради простоты.
+
+**Когда выбрать React:**
+- команда от 5 человек;
+- нужны UI-киты, нужна экосистема;
+- проект, который будет нанимать новых людей с рынка;
+- нужен SSR с гидрацией (Next.js).
+
+---
+
+## Сильнейший аргумент Mado
+
+Не размер, не перф, не сигналы — у всего этого есть конкуренты лучше.
+
+> **«Открой исходник и прочитай его за вечер. ~3500 строк, 12 модулей. Если что-то сломалось — ты не идёшь в issue на 3000 комментариев. Ты идёшь в `src/router.ts` и читаешь 500 строк.»**
+
+Это называется **ownership** — ты владеешь кодом, а не зависишь от чужого.
+
+Для бекендеров, которые привыкли к маленьким понятным библиотекам (chi в Go, axum в Rust, FastAPI в Python), это **родное ощущение**. Для тех, кому это не важно — берите что больше и зрелее.
+
+---
+
+## Что насчёт перфоманса?
+
+Честно: **Mado не самый быстрый**. Топ-3 на js-framework-benchmark — это Solid, Inferno, Svelte. Mado ближе к Lit / Preact по характеристикам.
+
+Что Mado делает для перфа из коробки:
+- **lazy `computed`** (dirty-flag, не eager);
+- **batch microtask scheduler** для `signal.set`;
+- **keyed reconciliation** в `each()` с реальным DOM-reuse;
+- **sync-rendering** для кешированных страниц в роутере;
+- **hover-prefetch** lazy-chunk'ов;
+- **View Transitions API** для плавных переходов;
+- **shared `adoptedStyleSheets`** для CSS;
+- **`modulepreload` hints** на dev-сервере.
+
+Этого достаточно для большинства приложений. Если вы строите Excel в браузере или 60fps WebGL-визуализацию — это не сюда (это в Solid или нативный JS).
+
+---
+
+## Резюме
+
+Mado — это **узкий** инструмент с честным позиционированием. Он сильнее всего там, где:
+
+1. Вы хотите **владеть** кодом и читать его целиком.
+2. Вам критична **простота инфраструктуры** (никакого Vite/Webpack/Babel).
+3. Вам нужны **батарейки в одной коробке** (роутер + data + формы + SEO).
+4. Вы не junior и не боитесь Web Components.
+
+Если хоть один пункт не про вас — берите альтернативу из таблицы выше. Не миритесь с инструментом, который не подходит.
+
+— Автор Mado, бывший React-разработчик, перешедший на бекенд и теперь склеивающий фронт в свободное время.