@madojs/mado 0.6.1 → 0.8.0

package/docs/fr/17-shadow-dom-forms.md

@@ -0,0 +1,196 @@
+# Shadow DOM + formulaires
+
+L'utilisation de `useForm()` avec des composants input personnalisés en Shadow DOM
+nécessite de connaître deux comportements au niveau du navigateur :
+
+1. **Retargeting des événements** — les événements qui remontent du Shadow DOM ont
+   leur `e.target` redirigé vers l'élément host. `useForm().onInput` lit
+   `e.target.name` et `e.target.value`, mais un élément host `<x-input>`
+   ne possède pas nativement ces propriétés.
+
+2. **Association de formulaire** — un `<button type="submit">` à l'intérieur d'un
+   Shadow Root ne fait PAS partie de l'algorithme form-owner pour `<form>` dans
+   le Light DOM. Cliquer dessus ne déclenche pas le submit du formulaire.
+
+Ces deux limitations sont au niveau de la spécification, pas des bugs Mado. Mais
+le framework fournit des patterns qui les rendent indolores.
+
+## Pattern : Propriétés proxy sur les composants input
+
+En encapsulant un `<input>` dans un composant Shadow DOM, exposez `name` et
+`value` comme propriétés DOM sur le host pour que `useForm().onInput` fonctionne
+après le retargeting :
+
+```ts
+import { component, css, html } from "@madojs/mado";
+
+component("x-input", ({ host, attr }) => {
+  const name = attr("name", "");
+  const type = attr("type", "text");
+  const value = attr("value", "");
+
+  // Propriétés proxy pour la compatibilité useForm().
+  // Après le retargeting Shadow DOM de e.target : <input> → <x-input>,
+  // useForm lit e.target.name / e.target.value — ces getters font le pont.
+  Object.defineProperty(host, "name", {
+    get: () => host.getAttribute("name") ?? "",
+    configurable: true,
+  });
+  Object.defineProperty(host, "value", {
+    get: () => host.shadowRoot?.querySelector("input")?.value ?? "",
+    set: (v: string) => {
+      const input = host.shadowRoot?.querySelector("input");
+      if (input) input.value = v;
+    },
+    configurable: true,
+  });
+
+  return () => html`<input name=${name} type=${type} .value=${value} />`;
+});
+```
+
+L'événement `input` du `<input>` interne a `composed: true` par défaut, donc
+il remonte à travers la frontière shadow. Après le retargeting, `e.target` est
+`<x-input>`, mais maintenant il a les getters `.name` et `.value` → `useForm`
+fonctionne.
+
+## Pattern : Submit de formulaire depuis des boutons Shadow DOM
+
+Un `<button type="submit">` dans le Shadow DOM ne peut pas déclencher le submit
+d'un `<form>` dans le Light DOM. Pont via `requestSubmit()` :
+
+```ts
+import { component, css, html } from "@madojs/mado";
+
+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>
+  `;
+});
+```
+
+`host.closest("form")` fonctionne parce que l'élément host lui-même vit dans
+le Light DOM (seuls ses éléments internes sont dans l'ombre). `requestSubmit()`
+déclenche la validation et l'événement `submit` exactement comme si l'utilisateur
+avait cliqué sur un bouton submit natif à l'intérieur du formulaire.
+
+## Pattern : Attributs réactifs avec ctx.attr()
+
+Depuis la v0.7, `ctx.attr(name, defaultValue?)` retourne un `Signal<string>` qui
+se met à jour automatiquement quand l'attribut change sur le host. Plus besoin de
+`MutationObserver` :
+
+```ts
+component("x-badge", ({ attr }) => {
+  const variant = attr("variant", "default"); // Signal<string>
+
+  return () =>
+    html`<span class=${() => `badge badge-${variant()}`}>
+      <slot></slot>
+    </span>`;
+});
+```
+
+Le parent peut utiliser `?disabled=${() => !form.isValid()}` (attribut booléen)
+ou `.variant=${"danger"}` — le composant se re-rend de manière réactive dans
+les deux cas.
+
+## Exemple complet de formulaire
+
+```ts
+import { page, html, useForm, navigate } from "@madojs/mado";
+import "../components/x-input.js";
+import "../components/x-button.js";
+
+export default page({
+  title: "Connexion",
+  view: () => {
+    const form = useForm({
+      email: { required: true, type: "email" },
+      password: { required: true, minLength: 6 },
+    });
+
+    const handleLogin = async (values) => {
+      await api("/auth/login", { method: "POST", json: values });
+      navigate("/admin");
+    };
+
+    return html`
+      <form @submit=${form.onSubmit(handleLogin)}>
+        <x-input
+          name="email"
+          type="email"
+          label="Email"
+          required
+          @input=${form.onInput}
+          @blur=${form.onBlur}
+        ></x-input>
+        ${() =>
+          form.errors().email
+            ? html`<small class="err">${form.errors().email}</small>`
+            : null}
+
+        <x-input
+          name="password"
+          type="password"
+          label="Mot de passe"
+          required
+          @input=${form.onInput}
+          @blur=${form.onBlur}
+        ></x-input>
+
+        <x-button type="submit" ?disabled=${() => !form.isValid()}>
+          Se connecter
+        </x-button>
+      </form>
+    `;
+  },
+});
+```
+
+## Quand utiliser Light DOM à la place
+
+Si votre composant input est juste un wrapper stylisé sans besoin
+d'encapsulation, `shadow: false` évite les deux problèmes (retargeting et
+association de formulaire) :
+
+```ts
+component(
+  "x-field",
+  ({ attr }) => {
+    const label = attr("label", "");
+    return () => html`
+      <label>
+        <span>${label}</span>
+        <slot></slot>
+      </label>
+    `;
+  },
+  { shadow: false },
+);
+```
+
+Avec Light DOM, le `<input>` natif fait partie de l'arbre du document, les
+événements ne sont pas retargetés, et le submit fonctionne nativement.
+Le compromis : les styles ne sont pas encapsulés (vous devez les scoper
+vous-même).
+
+## Résumé
+
+| Problème                       | Solution Shadow DOM                          | Alternative Light DOM           |
+| ------------------------------ | -------------------------------------------- | ------------------------------- |
+| `useForm` + input personnalisé | Proxy `name`/`value` sur le host             | `<input>` natif dans un slot    |
+| Submit de formulaire           | `form.requestSubmit()` dans le click handler | Le bouton natif fonctionne      |
+| Attributs réactifs             | `ctx.attr()` → signal auto                   | `ctx.attr()` fonctionne partout |
+| Encapsulation des styles       | Oui (automatique)                            | `@scope` manuel ou BEM          |

package/docs/fr/README.md

@@ -2,22 +2,23 @@
 
 Documentation française.
 
-| Section | Source |
-|---|---|
-| The Mado way | [00-the-mado-way.md](./00-the-mado-way.md) |
-| Routing | [01-routing.md](./01-routing.md) |
-| Project layout | [02-project-layout.md](./02-project-layout.md) |
-| Static bake & SEO | [03-static-bake.md](./03-static-bake.md) |
-| IDE setup | [04-ide-setup.md](./04-ide-setup.md) |
-| Why Mado | [05-why-mado.md](./05-why-mado.md) |
-| For backenders | [06-for-backenders.md](./06-for-backenders.md) |
-| LLM pitfalls | [07-llm-pitfalls.md](./07-llm-pitfalls.md) |
-| LLM zero-history test | [08-llm-zero-history-test.md](./08-llm-zero-history-test.md) |
-| Shadow DOM vs Light DOM | [09-shadow-vs-light-dom.md](./09-shadow-vs-light-dom.md) |
-| Architecture d'application | [10-app-architecture.md](./10-app-architecture.md) |
-| Layouts | [11-layouts.md](./11-layouts.md) |
-| Auth et API | [12-auth-and-api.md](./12-auth-and-api.md) |
-| Déploiement | [13-deployment.md](./13-deployment.md) |
-| Tests | [14-testing.md](./14-testing.md) |
-| Gestion des erreurs | [15-error-handling.md](./15-error-handling.md) |
-| Bake cookbook | [16-bake-cookbook.md](./16-bake-cookbook.md) |
+| Section                       | Fichier                                                      |
+| ----------------------------- | ------------------------------------------------------------ |
+| La voie Mado                  | [00-the-mado-way.md](./00-the-mado-way.md)                   |
+| Routage                       | [01-routing.md](./01-routing.md)                             |
+| Structure du projet           | [02-project-layout.md](./02-project-layout.md)               |
+| Prérendu statique & SEO       | [03-static-bake.md](./03-static-bake.md)                     |
+| Configuration IDE             | [04-ide-setup.md](./04-ide-setup.md)                         |
+| Pourquoi Mado                 | [05-why-mado.md](./05-why-mado.md)                           |
+| Pour les développeurs backend | [06-for-backenders.md](./06-for-backenders.md)               |
+| Pièges LLM                    | [07-llm-pitfalls.md](./07-llm-pitfalls.md)                   |
+| Test LLM sans historique      | [08-llm-zero-history-test.md](./08-llm-zero-history-test.md) |
+| Shadow DOM vs Light DOM       | [09-shadow-vs-light-dom.md](./09-shadow-vs-light-dom.md)     |
+| Architecture d'application    | [10-app-architecture.md](./10-app-architecture.md)           |
+| Mises en page (layouts)       | [11-layouts.md](./11-layouts.md)                             |
+| Auth et API                   | [12-auth-and-api.md](./12-auth-and-api.md)                   |
+| Déploiement                   | [13-deployment.md](./13-deployment.md)                       |
+| Tests                         | [14-testing.md](./14-testing.md)                             |
+| Gestion des erreurs           | [15-error-handling.md](./15-error-handling.md)               |
+| Guide de recettes bake        | [16-bake-cookbook.md](./16-bake-cookbook.md)                 |
+| Shadow DOM + formulaires      | [17-shadow-dom-forms.md](./17-shadow-dom-forms.md)           |

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 специально маленький, чтобы быть читаемым.