@madojs/mado 0.11.1 → 0.13.0

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

@@ -1,193 +0,0 @@
-# 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()` + layout groups + prefetch |
-| Data fetching | нет, нужно собирать | `resource()` + `mutation()` + glob-инвалидация |
-| Формы | нет | `useForm()` с HTML-like constraints |
-| SEO / static | сложно (`@lit-labs/ssr`) | `bake` (linkedom) + edge-prerender |
-| Билд | нужны framework-specific build plugins | Vite transport + native runtime |
-| Стиль кода | классы + декораторы | функции + 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 обязательны | Vite для dev/build, без runtime-зависимостей |
-| Роутер | `@solidjs/router` | в комплекте |
-| Data | `createResource` | `resource()` |
-| SSR | поддерживается серьёзно (SolidStart) | намеренно нет |
-| Экосистема | растёт, ~50 пакетов | нет |
-| Когда выбрать | нужен топовый перф + JSX + готов настраивать билд | нужен browser-native runtime с простым tooling |
-
-**Честный pitch:** *«Solid технически быстрее и зрелее. Mado проще концептуально: browser-native runtime, Web Components, tagged templates, а Vite забирает на себя скучный dev/build. Если нужны JSX и большая экосистема — берите 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 строк, маленькие модули. Если что-то сломалось — ты не идёшь в issue на 3000 комментариев. Ты идёшь в `src/router/` и читаешь код.»**
-
-Это называется **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-разработчик, перешедший на бекенд и теперь склеивающий фронт в свободное время.

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

@@ -1,428 +0,0 @@
-# Mado для бекендеров
-
-> Ты пишешь на Go / Rust / .NET / Java / Python и тебе нужно запилить веб-морду.  
-> Эта страница — mental model Mado за 10 минут, на твоём языке.
-
----
-
-## Главная аналогия
-
-Mado устроен **как HTTP-сервер**. Серьёзно:
-
-| Серверный мир | Mado |
-|---|---|
-| HTTP-роутер (chi, axum, mux) | `routes()` — манифест путей |
-| Handler `func(req, resp)` | `page({ view: (ctx) => html\`...\` })` |
-| Middleware | route group через `layout()` (оборачивает handler) |
-| Шаблонизатор (Jinja, Handlebars) | `html\`\`` tagged template |
-| HTTP-клиент с кешем | `resource()` — fetch + cache + invalidation |
-| Reactive variable / atom | `signal()` — реактивный геттер |
-| Background goroutine / task | `effect()` — авто-перезапускается при изменении сигнала |
-| `defer cleanup()` | `ctx.onDispose(fn)` в setup компонента |
-| ENV-переменные | `createContext()` + `provide()`/`inject()` |
-
-Если ты понимаешь HTTP-сервер, ты понимаешь Mado.
-
----
-
-## Файловая структура — как у обычного приложения
-
-```
-src/
-├── routes.ts         ← манифест путей (как router.go в chi)
-├── main.ts           ← entry point (как main.go: настройка + run)
-├── pages/            ← по одному файлу на страницу (как handler.go)
-├── components/       ← переиспользуемые UI (как helpers/)
-├── layouts/          ← обёртки для групп страниц (как middleware/)
-└── lib/              ← бизнес-логика, API-клиент (как service/, repo/)
-```
-
-Один файл = одна страница. Никакой file-based magic routing — всё руками в `routes.ts`.
-
----
-
-## Hello World — серверная аналогия
-
-### Go (chi) — для сравнения
-
-```go
-r := chi.NewRouter()
-r.Get("/", func(w http.ResponseWriter, r *http.Request) {
-    w.Write([]byte("<h1>Hello</h1>"))
-})
-r.Get("/users/{id}", func(w http.ResponseWriter, r *http.Request) {
-    id := chi.URLParam(r, "id")
-    fmt.Fprintf(w, "<h1>User %s</h1>", id)
-})
-http.ListenAndServe(":8080", r)
-```
-
-### Mado — то же самое
-
-```ts
-// src/routes.ts
-import { routes } from "@madojs/mado";
-
-export default routes({
-  "/": () => import("./pages/home.js"),
-  "/users/:id": () => import("./pages/user.js"),
-});
-```
-
-```ts
-// src/pages/home.ts
-import { page, html } from "@madojs/mado";
-export default page({
-  view: () => html`<h1>Hello</h1>`,
-});
-```
-
-```ts
-// src/pages/user.ts
-import { page, html } from "@madojs/mado";
-export default page<{ id: string }>({
-  view: ({ params }) => html`<h1>User ${params.id}</h1>`,
-});
-```
-
-Параметры пути попадают в `params` — так же, как в `chi.URLParam`.
-
----
-
-## Сигналы — это reactive variable
-
-Если ты писал на Erlang/Elixir с `Agent`, или на Rust с `Arc<Mutex<T>>`, или просто хранил state в struct и обновлял его — `signal` это то же самое, плюс **авто-перерисовка** компонентов, которые этот state читают.
-
-```ts
-import { signal, effect } from "@madojs/mado";
-
-// "переменная" с подпиской
-const count = signal(0);
-
-// читать
-console.log(count()); // 0
-
-// писать
-count.set(5);
-
-// "горутина", которая запускается на каждое изменение
-effect(() => {
-  console.log("count is now", count());
-});
-// → выведет "count is now 5"
-
-count.set(10);
-// → выведет "count is now 10"
-```
-
-Никаких правил вида «нельзя в условии». Сигнал — это просто функция-геттер. Где её прочитали — туда и подписались.
-
----
-
-## `resource()` — HTTP-клиент с кешем (как `cache.GetOrSet`)
-
-Это **самая полезная абстракция для бекендера**. Это как Redis с автоматической инвалидацией, только в браузере.
-
-```ts
-import { resource, mutation, jsonFetcher, invalidate } from "@madojs/mado";
-
-// "репозиторий пользователя"
-const userId = signal(1);
-
-const user = resource(
-  () => `/api/users/${userId()}`,         // ключ кеша (реактивный!)
-  jsonFetcher<User>(),                    // как загружать
-  { staleTime: 60_000 },                  // 60 секунд кеш
-);
-
-// в компоненте:
-user.data();     // User | undefined
-user.error();    // Error | null
-user.loading();  // boolean
-
-// мутация (как POST/PUT)
-const save = mutation<User, User>(
-  (u) => fetch("/api/users", { method: "POST", body: JSON.stringify(u) }).then(r => r.json()),
-  { invalidates: ["/api/users*"] },  // glob-инвалидация — как `cache.Drop("users:*")`
-);
-
-await save.run(newUser);
-// автоматически: user.data() обновится, если совпал glob
-```
-
-Ключи `resource()` — это identity кеша. Включайте endpoint, query params и
-форму данных в ключ: два живых `resource()` с одинаковым ключом разделяют кеш
-и in-flight request. Если один и тот же ключ используется с другим fetcher,
-Mado предупреждает, потому что обычно это значит, что ключ кеша слишком
-широкий.
-
-Если бы такая абстракция была в Go-мире для серверных кешей — мы бы все плакали от счастья.
-
----
-
-## Компоненты = handler с собственной памятью
-
-Компонент — это **handler**, который рендерит свой кусок UI. У него есть:
-
-- параметры (attributes/properties);
-- внутренний state (`signal`'ы);
-- lifecycle: `connectedCallback` (как Init), `disconnectedCallback` (как Close).
-
-```ts
-import { component, html, signal } from "@madojs/mado";
-
-component("x-counter", () => {
-  const count = signal(0);
-
-  return () => html`
-    <button @click=${() => count.update(n => n + 1)}>
-      Clicks: ${count}
-    </button>
-  `;
-});
-```
-
-Использование:
-
-```ts
-html`<x-counter></x-counter>`
-```
-
-Регистрируем тег `<x-counter>` в браузере — он становится «функцией», которую можно вставлять в HTML. Это **нативный** механизм браузера (Web Components), Mado только склеивает его с сигналами.
-
----
-
-## Формы — как `form.Validate()` на бекенде
-
-Mado использует **schema-based validation в духе HTML constraints**, плюс добавляет state-tracking.
-
-```ts
-import { useForm } from "@madojs/mado";
-
-const f = useForm({
-  email: { required: true, type: "email" },
-  age:   { required: true, type: "number", min: 18 },
-});
-
-// в шаблоне:
-html`
-  <form @submit=${f.onSubmit(async (v) => {
-    await api.save(v);
-    f.reset();
-  })}>
-    <input name="email" .value=${() => f.values().email ?? ""}
-           @input=${f.onInput} @blur=${f.onBlur} />
-    
-    ${() => f.errors().email && f.touched().email
-      ? html`<small>${f.errors().email}</small>`
-      : null}
-    
-    <button ?disabled=${() => !f.isValid() || f.submitting()}>Save</button>
-  </form>
-`;
-```
-
-Кастомная валидация — `validate: (values) => errors | null`. Никаких Yup-схем и зависимостей.
-
----
-
-## Контекст = DI / dependency injection
-
-Как в Go ты передаёшь `context.Context` через стек вызовов — так в Mado контекст пробрасывается через DOM-дерево.
-
-```ts
-import { createContext, provide, inject } from "@madojs/mado";
-
-// объявляем "тип" зависимости
-const ApiCtx = createContext<ApiClient>(defaultApiClient);
-
-// в корневом компоненте — предоставляем
-component("x-app", ({ host }) => {
-  provide(host, ApiCtx, new ApiClient("https://api.example.com"));
-  return () => html`<x-page/>`;
-});
-
-// в любом дочернем — забираем
-component("x-page", ({ host }) => {
-  const api = inject(host, ApiCtx);  // signal<ApiClient>
-  return () => html`<div>API version: ${() => api().version}</div>`;
-});
-```
-
-Это как `context.WithValue` / `ctx.Value` в Go, только реактивное.
-
----
-
-## SEO — не SSR, а `bake` (как `templ generate` в Go)
-
-Если ты привык к серверному рендерингу для SEO, в Mado это решается иначе: **prerender на build**.
-
-```ts
-// src/pages/product.ts
-export default page({
-  bake: {
-    paths: () => api.allProductSlugs(),   // build-time fetch
-    data: ({ slug }) => api.getProduct(slug),
-    revalidate: 3600,
-  },
-  head: ({ slug }, data) => ({
-    description: data.description,
-    canonical: `/product/${slug}`,
-    og: { title: data.name, image: data.image },
-  }),
-  view: ({ params }) => html`<x-product data-slug=${params.slug}/>`,
-});
-```
-
-```bash
-npm run bake   # → out/product/iphone-15/index.html (+ sitemap)
-```
-
-Краулер видит готовый HTML с meta-тегами. Пользователь видит то же самое + интерактив после загрузки JS.
-
-Подробнее: [`03-static-bake.md`](./03-static-bake.md).
-
----
-
-## Типичные задачи бекендера — рецепты
-
-### CRUD-страница со списком
-
-```ts
-import { page, html, resource, each, signal } from "@madojs/mado";
-
-export default page({
-  view: () => {
-    const users = resource(() => "/api/users", jsonFetcher<User[]>());
-    
-    return html`
-      ${() => users.loading() ? html`<p>Loading…</p>` : null}
-      ${() => users.error() ? html`<p>Error: ${users.error()!.message}</p>` : null}
-      <ul>
-        ${() => each(users.data() ?? [], u => u.id, u => html`
-          <li><a href="/users/${u.id}" data-link>${u.name}</a></li>
-        `)}
-      </ul>
-    `;
-  },
-});
-```
-
-### Форма с POST
-
-```ts
-import { useForm, mutation } from "@madojs/mado";
-
-const createUser = mutation<NewUser, User>(
-  (u) => fetch("/api/users", { method: "POST", body: JSON.stringify(u) }).then(r => r.json()),
-  { invalidates: ["/api/users*"] },
-);
-
-// в page.view:
-const f = useForm({ name: { required: true } });
-
-html`
-  <form @submit=${f.onSubmit(async (v) => {
-    await createUser.run(v);
-    navigate("/users");
-  })}>
-    <input name="name" @input=${f.onInput}>
-    <button>Create</button>
-  </form>
-`;
-```
-
-### Защищённая зона (auth middleware)
-
-```ts
-// src/layouts/auth-layout.ts
-import { page, html, effect } from "@madojs/mado";
-import { isAuthed, navigate } from "../lib/auth.js";
-
-export default page({
-  view: ({ child }) => {
-    effect(() => {
-      if (!isAuthed()) navigate("/login");
-    });
-    return html`<div class="app-shell">${child}</div>`;
-  },
-});
-```
-
-```ts
-// src/app.routes.ts
-import { layout, routes } from "@madojs/mado";
-
-export default routes({
-  "/login": () => import("./pages/login.js"),
-
-  "/app": layout({
-    layout: () => import("./layouts/auth-layout.js"),
-    routes: {
-      "/dashboard": () => import("./pages/dashboard.js"),
-      "/users": () => import("./pages/users.js"),
-    },
-  }),
-});
-```
-
-### Глобальный API-клиент (как singleton в Go)
-
-```ts
-// src/lib/api.ts
-export class ApiClient {
-  constructor(private base: string) {}
-  get<T>(path: string): Promise<T> {
-    return fetch(this.base + path).then(r => r.json());
-  }
-}
-
-export const api = new ApiClient("/api");
-```
-
-Используется напрямую `import { api } from '...'` либо через `createContext` для тестируемости.
-
----
-
-## Что **не** нужно учить (хорошие новости)
-
-- **Хуки и правила хуков.** Нет в Mado. Сигналы — обычные функции.
-- **VDOM и reconciliation.** Нет. Сигналы обновляют DOM напрямую, точечно.
-- **Webpack/Vite-конфиги.** Нет билда. `tsc → браузер`.
-- **`useEffect` dependency arrays.** `effect()` сам видит, что ты прочитал.
-- **State management библиотеки** (Redux/Zustand). Сигналы + context.
-- **CSS-in-JS трансформации.** Shadow DOM + `css\`\`` + cssVars.
-- **Routing v6 → v7 migration guide.** `routes()` — 500 строк, читается за 20 минут.
-
----
-
-## Что **придётся** освоить (честно)
-
-Это новые концепции. Не страшные, но плюс к React/Vue базе:
-
-1. **Custom Elements / Shadow DOM.** `<x-foo>` — это не div, это полноценный элемент с собственным DOM. Слоты, scoped CSS. Один вечер чтения MDN.
-2. **`attribute` vs `property`.** Attribute — это строка в HTML (`data-id="5"`), property — JS-свойство (`el.id = 5`). `?attr=${flag}` и `.prop=${value}` в шаблонах — это про разные вещи. Главное правило: **числа/объекты/массивы — через `.prop`, флаги — через `?attr`, строки — через `attr`**.
-3. **Сигналы.** Если первый раз — на 10 минут зависнешь, потом проще, чем хуки.
-4. **`html\`\``-шаблоны.** Это просто JS-функция с подсветкой через [lit-plugin](./04-ide-setup.md). Не магия.
-
-Всё остальное — стандартный браузер + TypeScript.
-
----
-
-## Чего не хватает (честно)
-
-- Нет hot reload, только full reload через SSE. Достаточно для большинства, но не как у Vite.
-- Нет dev-tools браузерного расширения. Используется `localStorage.madoDebug = '1'` + console.
-- Нет StackBlitz-стартеров (пока).
-- Нет AI-ассистента, который знает Mado так же хорошо, как React. Будут вопросы — читай `src/`, там не страшно.
-
----
-
-## Дальше
-
-- **[`01-routing.md`](./01-routing.md)** — детально про роутер.
-- **[`02-project-layout.md`](./02-project-layout.md)** — структура проекта.
-- **[`03-static-bake.md`](./03-static-bake.md)** — SEO без SSR.
-- **Внешний workspace `madojs-examples`** — полные демо (landing + admin).
-
-Если что-то непонятно — open issue, или просто открой исходник. Это правда читается за вечер.