@madojs/mado 0.6.1 → 0.7.0

package/docs/ru/07-llm-pitfalls.md

@@ -4,6 +4,7 @@
 > делают при генерации Mado-кода. И как их исправлять.
 
 Этот документ — для **двух аудиторий**:
+
 1. **AI-агентов в IDE**, которые читают `AGENTS.md` / `.cursorrules` / `.github/copilot-instructions.md`. Здесь больше деталей по типичным граблям.
 2. **Людей**, которые получили от AI код с этими ошибками и не понимают, что не так.
 
@@ -17,19 +18,20 @@
 const count = signal(0);
 
 // ❌ AI генерирует это часто
-html`<div>Count: ${count() * 2}</div>`
+html`<div>Count: ${count() * 2}</div>`;
 // → Отрисует "Count: 0", и больше никогда не обновится.
 // count() прочитан один раз в момент создания TemplateResult.
 
 // ✅ Правильно — функция-геттер
-html`<div>Count: ${() => count() * 2}</div>`
+html`<div>Count: ${() => count() * 2}</div>`;
 // → Mado создаст effect() на эту функцию, при изменении count перерисует.
 
 // ✅ Тоже правильно — сам сигнал является функцией
-html`<div>Count: ${count}</div>`
+html`<div>Count: ${count}</div>`;
 ```
 
 **Правило:**
+
 - Если в `${...}` есть **выражение** (что-то делает с сигналом) — оборачивай в `() => ...`.
 - Если в `${...}` **сам сигнал** — можно как есть.
 
@@ -45,10 +47,10 @@ html`<div>Count: ${count}</div>`
 const loading = signal(false);
 
 // ❌ Это setAttribute("disabled", "false") — DOM воспринимает это как disabled
-html`<button disabled=${loading()}>Save</button>`
+html`<button disabled=${loading()}>Save</button>`;
 
 // ✅ Правильно — boolean-биндинг (toggle attribute)
-html`<button ?disabled=${loading}>Save</button>`
+html`<button ?disabled=${loading}>Save</button>`;
 ```
 
 **Правило для атрибутов:**
@@ -86,6 +88,7 @@ component("x-counter", () => {
 ```
 
 **Ключевые отличия:**
+
 - Нет хуков, нет правил хуков.
 - `signal()` можно создавать где угодно — в setup, в effect, в обработчике.
 - `effect()` сам видит, что прочитал — не нужен dependency array.
@@ -93,7 +96,7 @@ component("x-counter", () => {
 
 ---
 
-## Pitfall #4: `useEffect(() => { ... return cleanup })` 
+## Pitfall #4: `useEffect(() => { ... return cleanup })`
 
 **Симптом:** AI пишет `return cleanup` в effect, ожидая что это сработает как в React.
 
@@ -172,11 +175,20 @@ import { Home } from "./pages/home.js";
 
 ```ts
 // ❌ Работает, но не keyed: пересоздаёт DOM на каждое изменение
-html`<ul>${() => items().map(t => html`<li>${t.name}</li>`)}</ul>`
+html`<ul>
+  ${() => items().map((t) => html`<li>${t.name}</li>`)}
+</ul>`;
 
 // ✅ Правильно: each() с key-функцией
 import { each } from "@madojs/mado";
-html`<ul>${() => each(items(), t => t.id, t => html`<li>${t.name}</li>`)}</ul>`
+html`<ul>
+  ${() =>
+    each(
+      items(),
+      (t) => t.id,
+      (t) => html`<li>${t.name}</li>`,
+    )}
+</ul>`;
 ```
 
 **Правило:** всегда используй `each()` для списков из массивов с устойчивыми ID. `.map()` оставь только для статичных списков.
@@ -191,15 +203,15 @@ html`<ul>${() => each(items(), t => t.id, t => html`<li>${t.name}</li>`)}</ul>`
 const count = signal(0);
 
 // ❌ Нет такого API
-count.value
-count.value = 5
-count.get()
+count.value;
+count.value = 5;
+count.get();
 
 // ✅ Правильно
-count()           // прочитать
-count.set(5)     // записать
-count.update(n => n + 1)
-count.peek()     // прочитать без подписки
+count(); // прочитать
+count.set(5); // записать
+count.update((n) => n + 1);
+count.peek(); // прочитать без подписки
 ```
 
 ---
@@ -220,7 +232,7 @@ component("x-app", ({ host }) => {
 });
 
 component("x-child", ({ host }) => {
-  const api = inject(host, ApiCtx);  // signal<value>
+  const api = inject(host, ApiCtx); // signal<value>
   return () => html`...`;
 });
 ```
@@ -242,6 +254,7 @@ if (typeof window !== "undefined") { ... }  // в Mado window есть ВСЕГ
 Mado **не делает SSR с гидрацией**. На сервере код не выполняется — есть только `bake` (статический prerender на build) и edge-prerender. Оба заменяют user code на linkedom-окружение, но это **только** для генерации HTML с meta-тегами, не для выполнения логики страницы.
 
 Это значит:
+
 - ✅ `window`, `document`, `location`, `fetch` — доступны без проверок.
 - ❌ Не пиши код, который пытается «универсально работать на сервере и клиенте».
 - ❌ Не используй паттерны Next.js (`getServerSideProps`, `headers()`).
@@ -259,7 +272,7 @@ const f = useForm({ resolver: zodResolver(schema) });
 // ✅ Правильно: HTML5-валидация атрибутами
 const f = useForm({
   email: { required: true, type: "email" },
-  age:   { required: true, type: "number", min: 18 },
+  age: { required: true, type: "number", min: 18 },
 });
 
 // ✅ Или кастомная функция, если HTML5 не хватает
@@ -287,11 +300,13 @@ Mado использует **Shadow DOM + `css\`\`` + CSS variables**. Глоба
 
 ```ts
 // Light-DOM page/screen компонент, Tailwind-классы работают
-component("x-admin-page", () => () => html`
-  <section class="bg-white shadow-lg rounded-lg p-4">
-    ...
-  </section>
-`, { shadow: false });
+component(
+  "x-admin-page",
+  () => () => html`
+    <section class="bg-white shadow-lg rounded-lg p-4">...</section>
+  `,
+  { shadow: false },
+);
 
 // Shadow-DOM компонент (default) — Tailwind НЕ работает.
 // Используй css`` или ::part() для внешней стилизации.
@@ -300,7 +315,7 @@ component("x-button", () => () => html`<button><slot></slot></button>`, {
     button {
       background: var(--button-bg, #2563eb);
       color: white;
-      padding: .5rem 1rem;
+      padding: 0.5rem 1rem;
       border-radius: 6px;
     }
   `,
@@ -333,6 +348,7 @@ Mado.signal(0);
 **Симптом:** AI предлагает `npm install lodash` / `npm install date-fns` / etc.
 
 Mado — **zero runtime deps** by design. Если AI хочет добавить:
+
 - **lodash** → используй нативный JS (`Object.entries`, `Array.prototype`, `structuredClone`);
 - **date-fns** → используй `Intl.DateTimeFormat` и `Intl.RelativeTimeFormat`;
 - **uuid** → `crypto.randomUUID()`;
@@ -351,19 +367,27 @@ Mado — **zero runtime deps** by design. Если AI хочет добавит
 // ❌ Работает, но плохо масштабируется и усложняет cleanup
 page({
   view: () => html`
-    <style>.panel { padding: 1rem; }</style>
+    <style>
+      .panel {
+        padding: 1rem;
+      }
+    </style>
     <section class="panel">...</section>
   `,
 });
 
 // ✅ Правильно: стили компонента через css``
-component("x-admin-panel", () => () => html`
-  <section class="panel">...</section>
-`, {
-  styles: css`
-    .panel { padding: 1rem; }
-  `,
-});
+component(
+  "x-admin-panel",
+  () => () => html` <section class="panel">...</section> `,
+  {
+    styles: css`
+      .panel {
+        padding: 1rem;
+      }
+    `,
+  },
+);
 ```
 
 Для backend-admin route/page экранов часто уместен `shadow: false`, чтобы
@@ -380,10 +404,10 @@ prefetch'ится.
 
 ```ts
 // ❌ Обычная ссылка: браузер сделает full reload
-html`<a href="/tickets/42">Open</a>`
+html`<a href="/tickets/42">Open</a>`;
 
 // ✅ SPA-навигация: router() перехватит click даже через Shadow DOM
-html`<a href="/tickets/42" data-link>Open</a>`
+html`<a href="/tickets/42" data-link>Open</a>`;
 ```
 
 Mado ищет ссылку через `event.composedPath()`, поэтому `data-link` работает
@@ -399,7 +423,10 @@ Mado ищет ссылку через `event.composedPath()`, поэтому `da
 
 ```ts
 // ❌ Нет lifecycle cleanup, будет dev-warning
-const tickets = resource(() => "tickets", () => api.listTickets());
+const tickets = resource(
+  () => "tickets",
+  () => api.listTickets(),
+);
 
 component("x-tickets", () => {
   return () => html`${() => tickets.data()?.length ?? 0}`;
@@ -407,7 +434,10 @@ component("x-tickets", () => {
 
 // ✅ Создавай resource внутри setup компонента
 component("x-tickets", () => {
-  const tickets = resource(() => "tickets", () => api.listTickets());
+  const tickets = resource(
+    () => "tickets",
+    () => api.listTickets(),
+  );
   return () => html`${() => tickets.data()?.length ?? 0}`;
 });
 ```
@@ -426,7 +456,7 @@ disconnect компонента.
 const view = signal(html`<x-home></x-home>`);
 
 // ✅ Нормальный паттерн: вложенный TemplateResult можно возвращать из child-binding
-html`${view}`
+html`${view}`;
 ```
 
 Начиная с v0.3 это закреплено регрессиями: при замене child-binding Mado
@@ -442,16 +472,23 @@ dispose'ит вложенные template instances/effects рекурсивно.
 
 ```ts
 // ❌ .page-head объявлен глобально, но x-dashboard по умолчанию Shadow DOM
-component("x-dashboard", () => () => html`
-  <header class="page-head">...</header>
-  <div class="metric-grid">...</div>
-`);
+component(
+  "x-dashboard",
+  () => () => html`
+    <header class="page-head">...</header>
+    <div class="metric-grid">...</div>
+  `,
+);
 
 // ✅ Page/layout/admin-shell компоненты часто должны быть Light DOM
-component("x-dashboard", () => () => html`
-  <header class="page-head">...</header>
-  <div class="metric-grid">...</div>
-`, { shadow: false });
+component(
+  "x-dashboard",
+  () => () => html`
+    <header class="page-head">...</header>
+    <div class="metric-grid">...</div>
+  `,
+  { shadow: false },
+);
 ```
 
 Правило: Shadow DOM — для leaf widgets и slot-based layouts, Light DOM — для
@@ -462,24 +499,124 @@ Shadow DOM; при `shadow: false` это обычный элемент.
 
 ---
 
+## Pitfall #20: `host.getAttribute()` в render = не реактивно
+
+**Симптом:** внешний вид компонента не обновляется при изменении атрибута родителем.
+
+```ts
+// ❌ host.getAttribute() в render-функции читается один раз, но
+// render перезапускается только при изменении его собственных сигналов.
+// Внешние изменения атрибута не триггерят перерисовку.
+component("x-badge", ({ host }) => () => {
+  const variant = host.getAttribute("variant") ?? "default";
+  return html`<span class=${variant}>...</span>`;
+});
+
+// ✅ Правильно: ctx.attr() — возвращает реактивный Signal<string>
+component("x-badge", ({ attr }) => {
+  const variant = attr("variant", "default");
+  return () => html`<span class=${() => `badge-${variant()}`}>...</span>`;
+});
+```
+
+**Правило:** никогда не читайте `host.getAttribute()` или `host.hasAttribute()` внутри
+render-функции для значений, которые могут измениться снаружи. Используйте `ctx.attr()` —
+он возвращает Signal, который автоматически обновляется через `attributeChangedCallback`.
+
+---
+
+## Pitfall #21: Shadow DOM `<button>` не сабмитит формы
+
+**Симптом:** клик по `<x-button type="submit">` внутри `<form>` ничего не делает.
+
+`<button>` внутри Shadow DOM не участвует в алгоритме form-owner для
+`<form>` в Light DOM — это ограничение спецификации, не баг Mado.
+
+```ts
+// ❌ Внутренняя <button type="submit"> не может триггерить родительскую <form>
+component("x-button", ({ host }) => {
+  return () => html`<button type="submit"><slot></slot></button>`;
+});
+
+// ✅ Мост через requestSubmit()
+component("x-button", ({ host, attr }) => {
+  const disabled = attr("disabled");
+
+  const handleClick = () => {
+    const typeAttr = host.getAttribute("type");
+    if (typeAttr === "button" || typeAttr === "reset") return;
+    const form = host.closest("form");
+    if (form && !host.hasAttribute("disabled")) form.requestSubmit();
+  };
+
+  return () => html`
+    <button ?disabled=${() => disabled() !== ""} @click=${handleClick}>
+      <slot></slot>
+    </button>
+  `;
+});
+```
+
+Подробнее: [`17-shadow-dom-forms.md`](./17-shadow-dom-forms.md).
+
+---
+
+## Pitfall #22: `useForm()` с Shadow DOM кастомными input
+
+**Симптом:** `form.onInput` получает `undefined` для name/value от `<x-input>`.
+
+Когда Shadow DOM input диспатчит `input` событие, браузер ретаргетирует
+`e.target` с внутреннего `<input>` на host `<x-input>`. Но `<x-input>`
+(HTMLElement) не имеет `.name` или `.value` — поэтому `useForm` ничего не получает.
+
+```ts
+// ❌ Нет proxy-свойств — useForm тихо игнорирует события
+component("x-input", ({ host, attr }) => {
+  const name = attr("name", "");
+  return () => html`<input name=${name} />`;
+});
+
+// ✅ Добавить proxy-свойства для совместимости с useForm
+component("x-input", ({ host, attr }) => {
+  const name = attr("name", "");
+
+  Object.defineProperty(host, "name", {
+    get: () => host.getAttribute("name") ?? "",
+    configurable: true,
+  });
+  Object.defineProperty(host, "value", {
+    get: () => host.shadowRoot?.querySelector("input")?.value ?? "",
+    configurable: true,
+  });
+
+  return () => html`<input name=${name} />`;
+});
+```
+
+Подробнее: [`17-shadow-dom-forms.md`](./17-shadow-dom-forms.md).
+
+---
+
 ## Cheat-sheet для AI
 
-| Если хочешь сделать… | Правильно в Mado |
-|---|---|
-| `useState(0)` | `signal(0)` |
-| `useEffect(() => {...}, [a, b])` | `effect(() => {...})` (auto-deps) |
-| `useEffect(() => return cleanup, [])` | `ctx.onDispose(cleanup)` |
-| `useMemo(() => x, [a])` | `computed(() => x)` |
-| `useCallback(fn, [])` | обычная функция |
-| `useContext(Ctx)` | `inject(host, Ctx)` |
-| `useQuery(['key'], fn)` | `resource(() => 'key', fn)` |
-| `useMutation(fn)` | `mutation(fn, { invalidates: [...] })` |
-| `useRouter().push('/')` | `navigate('/')` |
-| `useRouter().query.q` | `queryParam('q')` |
-| `<input value={v} onChange={...}>` | `<input .value=${v} @input=${...}>` |
-| `{items.map(x => ...)}` | `${() => each(items, x => x.id, x => ...)}` |
-| `useForm({ resolver: zodResolver })` | `useForm({...}, { validate: (v) => ... })` |
-| `class extends HTMLElement` | `component('x-name', setup)` |
-| `@customElement('x')` | `component('x-name', setup)` |
+| Если хочешь сделать…                  | Правильно в Mado                            |
+| ------------------------------------- | ------------------------------------------- |
+| `useState(0)`                         | `signal(0)`                                 |
+| `useEffect(() => {...}, [a, b])`      | `effect(() => {...})` (auto-deps)           |
+| `useEffect(() => return cleanup, [])` | `ctx.onDispose(cleanup)`                    |
+| `useMemo(() => x, [a])`               | `computed(() => x)`                         |
+| `useCallback(fn, [])`                 | обычная функция                             |
+| `useContext(Ctx)`                     | `inject(host, Ctx)`                         |
+| `useQuery(['key'], fn)`               | `resource(() => 'key', fn)`                 |
+| `useMutation(fn)`                     | `mutation(fn, { invalidates: [...] })`      |
+| `useRouter().push('/')`               | `navigate('/')`                             |
+| `useRouter().query.q`                 | `queryParam('q')`                           |
+| `<input value={v} onChange={...}>`    | `<input .value=${v} @input=${...}>`         |
+| `{items.map(x => ...)}`               | `${() => each(items, x => x.id, x => ...)}` |
+| `useForm({ resolver: zodResolver })`  | `useForm({...}, { validate: (v) => ... })`  |
+| `class extends HTMLElement`           | `component('x-name', setup)`                |
+| `@customElement('x')`                 | `component('x-name', setup)`                |
+| `host.getAttribute('x')` в render     | `ctx.attr('x', default)` (реактивно)        |
+| `jsonFetcher()` с авторизацией        | `apiFetcher()` (прикрепляет Bearer токен)   |
 
 Если что-то не подходит из этого списка — открой `src/` и **прочитай 500 строк**. Это серьёзно. Mado специально маленький, чтобы быть читаемым.

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

@@ -1,56 +1,57 @@
-# LLM zero-history test
+# Тест LLM с нулевой историей
 
-This document defines a practical validation test for Mado.
+Этот документ определяет практический валидационный тест для Mado.
 
-The question is not "can an LLM generate frontend code?" It can. The question is:
-can a fresh LLM write idiomatic Mado without falling back to React-shaped code?
+Вопрос не в том, «может ли LLM генерировать фронтенд-код?» — может. Вопрос в том:
+может ли свежая LLM написать идиоматичный Mado-код без скатывания в React-подобные
+паттерны?
 
-## Allowed context
+## Допустимый контекст
 
-For the first pass, give the agent only:
+При первом проходе предоставьте агенту только:
 
 - `AGENTS.md`
 - `README.md`
-- `docs/ru/07-llm-pitfalls.md`
-- `examples/basic/README.md` if a minimal API tour is needed
-- specific `examples/showcase/**` files only when the agent asks for a larger app pattern
+- `docs/en/07-llm-pitfalls.md`
+- `examples/basic/README.md` если нужен минимальный обзор API
+- конкретные файлы из `examples/showcase/**` только если агент сам попросит паттерн более крупного приложения
 
-The agent may search targeted APIs in `src/` when blocked, but should not load
-the whole framework into context.
+Агент может искать целевые API в `src/` когда заблокирован, но не должен
+загружать весь фреймворк в контекст.
 
-## Task
+## Задание
 
-Build `examples/tickets`: a small ticket-admin SPA for a solo/backend developer.
+Построить `examples/tickets`: маленький ticket-admin SPA для соло/бекенд-разработчика.
 
-Required behavior:
+Требуемое поведение:
 
-- routes: `/`, `/tickets`, `/tickets/new`, `/tickets/:id`, `*`;
-- in-memory mock API with realistic async delays;
-- list page with `resource()`, `queryParam()` search/status filters, `computed()`,
-  and keyed `each()` rows;
-- create and edit flows with `useForm()` + `mutation()` + `invalidates`;
-- local UI state with `signal()`;
-- slotted shell, metric, and badge components for a more realistic admin UI;
-- smoke test importing the built example.
+- маршруты: `/`, `/tickets`, `/tickets/new`, `/tickets/:id`, `*`;
+- in-memory mock API с реалистичными асинхронными задержками;
+- страница списка с `resource()`, `queryParam()` фильтрами поиска/статуса,
+  `computed()` и `each()` с ключами по строкам;
+- сценарии создания и редактирования с `useForm()` + `mutation()` + `invalidates`;
+- локальный UI-стейт через `signal()`;
+- slotted shell, metric и badge компоненты для более реалистичного admin UI;
+- smoke-тест, импортирующий собранный пример.
 
-## Failure checklist
+## Чеклист ошибок
 
-Look for these after implementation:
+Ищите следующее после реализации:
 
-- JSX, `useState`, `useEffect`, `ref`, `$state`, or class-style components;
-- `${signal()}` or `${signal() + 1}` where a reactive child thunk is required;
-- `disabled=${...}` instead of `?disabled=${...}`;
-- dynamic lists rendered with unkeyed array mapping instead of `each()`;
-- browser ESM imports without `.js`;
-- `resource()` created outside component setup;
-- new runtime dependencies or new public framework APIs.
+- JSX, `useState`, `useEffect`, `ref`, `$state` или class-style компоненты;
+- `${signal()}` или `${signal() + 1}` где требуется реактивный child thunk;
+- `disabled=${...}` вместо `?disabled=${...}`;
+- динамические списки, отрендеренные через unkeyed `.map()` вместо `each()`;
+- ESM-импорты в браузере без `.js`;
+- `resource()`, созданный вне component setup;
+- новые runtime-зависимости или новые публичные API фреймворка.
 
-## Result notes
+## Заметки по результатам
 
-The current `examples/tickets` implementation did not require new public APIs or
-runtime dependencies.
+Текущая реализация `examples/tickets` не потребовала новых публичных API или
+runtime-зависимостей.
 
-The main documentation pressure point remains lifecycle: older examples can make
-it look acceptable to create `resource()` directly in `page.view()`. The tickets
-example uses page-level wrapper components instead, so resources are registered
-inside component setup and clean up with the component.
+Основная болевая точка в документации остается lifecycle: старые примеры могут
+создать впечатление, что создание `resource()` прямо в `page.view()` допустимо.
+Пример tickets использует page-level wrapper-компоненты вместо этого, поэтому
+ресурсы регистрируются внутри component setup и очищаются вместе с компонентом.