@madojs/mado 0.6.1 → 0.7.0

package/docs/ru/09-shadow-vs-light-dom.md

@@ -1,10 +1,9 @@
 # Shadow DOM vs Light DOM
 
-Mado components use Shadow DOM by default. This is a good default for
-self-contained widgets, but it is not the right default for every component in
-an application.
+Компоненты Mado по умолчанию используют Shadow DOM. Это хороший дефолт для
+самодостаточных виджетов, но не для каждого компонента в приложении.
 
-## Rule of Thumb
+## Правило большого пальца
 
 В Mado layout — это тоже component. Если файл описывает видимую переиспользуемую
 часть UI-дерева — app shell, sidebar, modal, table, page section — по умолчанию
@@ -17,25 +16,25 @@ const money = (value: number) => html`<span>${formatMoney(value)}</span>`;
 ```
 
 Не стоит делать app shell функцией в публичных примерах. Это работает, но
-прячет browser model вместо того, чтобы ее объяснять.
+прячет browser model вместо того, чтобы её объяснять.
 
-Use **Shadow DOM** for leaf widgets:
+Используйте **Shadow DOM** для leaf-виджетов:
 
-- buttons, badges, cards, metrics;
-- modals, toasts, small visual components;
-- embed widgets that should not inherit app CSS accidentally;
-- components whose styling should be owned by the component itself.
+- кнопки, бейджи, карточки, метрики;
+- модалы, тосты, маленькие визуальные компоненты;
+- embed-виджеты, которые не должны наследовать CSS приложения случайно;
+- компоненты, стили которых принадлежат самому компоненту.
 
-Use **Light DOM** (`{ shadow: false }`) for app structure that wants to share
-global CSS utilities:
+Используйте **Light DOM** (`{ shadow: false }`) для структуры приложения,
+которая хочет разделять глобальные CSS-утилиты:
 
-- route/page components;
-- admin screens with dense table/form layouts;
-- data-heavy screens with tables and forms;
-- components that intentionally share global layout, form and table utilities;
-- places where children should simply remain normal document DOM.
+- route/page компоненты;
+- admin-экраны с плотными таблицами/формами;
+- data-heavy экраны с таблицами и формами;
+- компоненты, которые намеренно используют глобальные layout/form/table утилиты;
+- места, где children должны оставаться обычным document DOM.
 
-Use **Shadow DOM** для slot-based layouts:
+Используйте **Shadow DOM** для slot-based layouts:
 
 - app shells с `<slot>`;
 - sidebar/content wrappers;
@@ -44,73 +43,89 @@ Use **Shadow DOM** для slot-based layouts:
 `<slot>` — это feature Shadow DOM. В компоненте с `shadow: false` тег `<slot>`
 становится обычным DOM-элементом и не переносит children в это место layout.
 
-## The Footgun
+## Подвох
 
-Global CSS does not cross a Shadow DOM boundary.
+Глобальный CSS не пересекает границу Shadow DOM.
 
 ```ts
 // global.ts
 export const globalStyles = css`
-  .page-head { display: flex; justify-content: space-between; }
-  .metric-grid { display: grid; grid-template-columns: repeat(4, 1fr); }
+  .page-head {
+    display: flex;
+    justify-content: space-between;
+  }
+  .metric-grid {
+    display: grid;
+    grid-template-columns: repeat(4, 1fr);
+  }
 `;
 
-// ❌ .page-head and .metric-grid will not apply inside x-dashboard shadowRoot
-component("x-dashboard", () => () => html`
-  <header class="page-head">...</header>
-  <div class="metric-grid">...</div>
-`);
+// ❌ .page-head и .metric-grid НЕ применятся внутри shadowRoot x-dashboard
+component(
+  "x-dashboard",
+  () => () => html`
+    <header class="page-head">...</header>
+    <div class="metric-grid">...</div>
+  `,
+);
 ```
 
-Fix it by making the route/page component Light DOM:
+Решение — сделать route/page компонент Light DOM:
 
 ```ts
-component("x-dashboard", () => () => html`
-  <header class="page-head">...</header>
-  <div class="metric-grid">...</div>
-`, {
-  shadow: false,
-  styles: css`
-    x-dashboard { display: block; }
-    x-dashboard .panel { padding: 1rem; }
+component(
+  "x-dashboard",
+  () => () => html`
+    <header class="page-head">...</header>
+    <div class="metric-grid">...</div>
   `,
-});
+  {
+    shadow: false,
+    styles: css`
+      x-dashboard {
+        display: block;
+      }
+      x-dashboard .panel {
+        padding: 1rem;
+      }
+    `,
+  },
+);
 ```
 
-Now global utilities and local scoped styles both work.
+Теперь глобальные утилиты и локальные scoped-стили работают вместе.
 
-## How Styles Behave
+## Как ведут себя стили
 
-- `styles: css\`\`` in Shadow DOM is adopted into the component shadowRoot.
-- `styles: css\`\`` with `shadow: false` is scoped to the tag name and adopted
-  globally.
-- CSS custom properties (`--accent`, `--bg`, etc.) cross Shadow DOM boundaries.
-- Class selectors like `.btn`, `.form-grid`, `.page-head` do **not** cross
-  Shadow DOM boundaries.
-- Slotted children keep their own document styles; the shadow component can only
-  target them through `::slotted(...)`.
-- `<slot>` projects children only in Shadow DOM. In a `shadow: false` component
-  it is just a normal `<slot>` element and will not move children into that
-  place in your layout.
+- `styles: css\`\`` в Shadow DOM адоптируется в shadowRoot компонента.
+- `styles: css\`\``с`shadow: false` скоупится по имени тега и адоптируется
+  глобально.
+- CSS custom properties (`--accent`, `--bg` и т.д.) пересекают границу Shadow DOM.
+- Селекторы по классу (`.btn`, `.form-grid`, `.page-head`) **не** пересекают
+  границу Shadow DOM.
+- Slotted-children сохраняют свои стили из документа; shadow-компонент может
+  таргетировать их только через `::slotted(...)`.
+- `<slot>` проецирует children только в Shadow DOM. В компоненте с `shadow: false`
+  это обычный `<slot>` элемент, который не перемещает children в своё место.
 
-## Recommended App Shape
+## Рекомендованная архитектура
 
 ```ts
-// root and pages: Light DOM
+// root и pages: Light DOM
 component("x-app", setup, { shadow: false });
 component("x-users-page", setup, { shadow: false });
 
-// slot-based layout: Shadow DOM default, because it owns the shell grid
+// slot-based layout: Shadow DOM по умолчанию, потому что владеет shell grid
 component("x-app-layout", setup);
 
-// leaf widgets: Shadow DOM default
+// leaf widgets: Shadow DOM по умолчанию
 component("x-status-badge", setup);
 component("x-stat-card", setup);
 component("x-toast-stack", setup);
 ```
 
-This gives backend-admin screens predictable CSS while preserving encapsulation
-for reusable widgets and slot-based shells.
+Это даёт backend-admin экранам предсказуемый CSS, сохраняя инкапсуляцию
+для переиспользуемых виджетов и slot-based shells.
 
 Import model специально browser-native:
 
@@ -121,30 +136,31 @@ render(html`<x-app-layout>${router.view}</x-app-layout>`, app);
 ```
 
 Import регистрирует custom element через `customElements.define()`. Template
-создает `<x-app-layout>` element. Дальше браузер сам связывает тег с классом
-компонента. Тут нет React-style component value, который передается как функция.
+создаёт `<x-app-layout>` элемент. Дальше браузер сам связывает тег с классом
+компонента. Тут нет React-style component value, который передаётся как функция.
 
-If a layout does not need slot projection and should be styled entirely by
-global CSS, `shadow: false` can still be a good choice. If it contains
-`<slot>`, keep Shadow DOM and put the shell styles in that component.
+Если layout не нуждается в slot projection и должен стилизоваться полностью
+глобальным CSS, `shadow: false` — хороший выбор. Если он содержит `<slot>`,
+оставьте Shadow DOM и поместите стили shell в этот компонент.
 
-## Routing and Links
+## Маршрутизация и ссылки
 
-`data-link` works inside Shadow DOM. The router uses `event.composedPath()`, so
-click interception and hover-prefetch can see links from open shadow roots.
+`data-link` работает внутри Shadow DOM. Роутер использует `event.composedPath()`,
+поэтому перехват кликов и hover-prefetch видят ссылки из open shadow roots.
 
 ```ts
-component("x-card-link", () => () => html`
-  <a href="/app/accounts" data-link>Accounts</a>
-`);
+component(
+  "x-card-link",
+  () => () => html` <a href="/app/accounts" data-link>Accounts</a> `,
+);
 ```
 
-The link can be in Shadow DOM; navigation still stays SPA.
+Ссылка может быть внутри Shadow DOM — навигация всё равно остаётся SPA.
 
 ## Где импортировать компоненты
 
-Custom elements становятся глобальными после регистрации, но регистрация все
-равно остается явным JavaScript import.
+Custom elements становятся глобальными после регистрации, но регистрация всё
+равно остаётся явным JavaScript import.
 
 ```ts
 // main.ts: global app frame
@@ -158,7 +174,7 @@ import "../components/ticket-list.js";
 `<ticket-list>`. Файл должен быть где-то импортирован. После import он вызывает
 `customElements.define(...)`, и тег становится известен текущему document.
 
-Не стоит bulk-import всех компонентов в `main.ts` "just in case". Для маленьких
+Не стоит bulk-import всех компонентов в `main.ts` «на всякий случай». Для маленьких
 demo это работает, но прячет ownership и ломает lazy route loading. Лучше:
 
 - global app shell/providers импортировать в `main.ts`;
@@ -167,16 +183,16 @@ demo это работает, но прячет ownership и ломает lazy r
 - truly global leaf components импортировать в `main.ts` только если они реально
   используются везде.
 
-## Showcase Lesson
+## Урок из showcase
 
-`examples/showcase` uses this split deliberately:
+`examples/showcase` использует это разделение намеренно:
 
-- `x-app` and CRM route pages are Light DOM;
-- `x-app-layout` keeps Shadow DOM because it owns a slot-based sidebar/content
-  shell;
-- table/form/page utilities live in `styles/global.ts`;
-- leaf components such as `x-stat-card`, `x-status-badge`, `x-modal`, and
-  `x-toast-stack` keep Shadow DOM.
+- `x-app` и CRM route pages — Light DOM;
+- `x-app-layout` остаётся в Shadow DOM, потому что владеет slot-based
+  sidebar/content shell;
+- table/form/page утилиты живут в `styles/global.ts`;
+- leaf-компоненты типа `x-stat-card`, `x-status-badge`, `x-modal` и
+  `x-toast-stack` остаются в Shadow DOM.
 
-If a page suddenly looks unstyled, check whether it uses global classes inside a
-Shadow DOM component. That is usually the issue.
+Если страница внезапно выглядит без стилей, проверьте — не используете ли вы
+глобальные классы внутри Shadow DOM компонента. Обычно проблема именно в этом.

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

@@ -0,0 +1,193 @@
+# Shadow DOM + формы
+
+Использование `useForm()` с кастомными input-компонентами в Shadow DOM требует
+знания двух поведений на уровне браузера:
+
+1. **Ретаргетинг событий** — события, всплывающие из Shadow DOM, получают
+   `e.target`, перенаправленный на host-элемент. `useForm().onInput` читает
+   `e.target.name` и `e.target.value`, но host-элемент `<x-input>`
+   не имеет этих свойств нативно.
+
+2. **Ассоциация с формой** — `<button type="submit">` внутри Shadow Root
+   НЕ участвует в алгоритме form-owner для `<form>` в Light DOM. Клик по ней
+   не триггерит submit формы.
+
+Оба ограничения — на уровне спецификации, не баги Mado. Но фреймворк предоставляет
+паттерны, которые делают их безболезненными.
+
+## Паттерн: Proxy-свойства на input-компонентах
+
+Оборачивая `<input>` в Shadow DOM компонент, экспонируйте `name` и `value`
+как DOM-свойства на host, чтобы `useForm().onInput` работал после ретаргетинга:
+
+```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", "");
+
+  // Proxy-свойства для совместимости с useForm().
+  // После ретаргетинга Shadow DOM e.target из <input> → <x-input>,
+  // useForm читает e.target.name / e.target.value — эти геттеры наводят мост.
+  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} />`;
+});
+```
+
+Событие `input` от внутреннего `<input>` имеет `composed: true` по умолчанию,
+поэтому оно всплывает через границу shadow. После ретаргетинга `e.target` —
+это `<x-input>`, но теперь у него есть геттеры `.name` и `.value` → `useForm`
+работает.
+
+## Паттерн: Submit формы из Shadow DOM кнопок
+
+`<button type="submit">` внутри Shadow DOM не может триггерить submit `<form>`
+в Light DOM. Мост через `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")` работает, потому что сам host-элемент живёт в Light DOM
+(только его внутренности в тени). `requestSubmit()` триггерит валидацию и
+событие `submit` точно так, как если бы пользователь кликнул нативную submit-кнопку
+внутри формы.
+
+## Паттерн: Реактивные атрибуты через ctx.attr()
+
+С версии 0.7 `ctx.attr(name, defaultValue?)` возвращает `Signal<string>`,
+который автоматически обновляется при изменении атрибута на host. Никакого
+`MutationObserver` бойлерплейта:
+
+```ts
+component("x-badge", ({ attr }) => {
+  const variant = attr("variant", "default"); // Signal<string>
+
+  return () =>
+    html`<span class=${() => `badge badge-${variant()}`}>
+      <slot></slot>
+    </span>`;
+});
+```
+
+Родитель может использовать `?disabled=${() => !form.isValid()}` (boolean атрибут)
+или `.variant=${"danger"}` — компонент перерендеривается реактивно в любом случае.
+
+## Полный пример формы
+
+```ts
+import { page, html, useForm, navigate } from "@madojs/mado";
+import "../components/x-input.js";
+import "../components/x-button.js";
+
+export default page({
+  title: "Вход",
+  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="Пароль"
+          required
+          @input=${form.onInput}
+          @blur=${form.onBlur}
+        ></x-input>
+
+        <x-button type="submit" ?disabled=${() => !form.isValid()}>
+          Войти
+        </x-button>
+      </form>
+    `;
+  },
+});
+```
+
+## Когда использовать Light DOM
+
+Если ваш input-компонент — это просто стилизованная обёртка без нужды в
+инкапсуляции, `shadow: false` избегает обеих проблем (ретаргетинг и
+form-association):
+
+```ts
+component(
+  "x-field",
+  ({ attr }) => {
+    const label = attr("label", "");
+    return () => html`
+      <label>
+        <span>${label}</span>
+        <slot></slot>
+      </label>
+    `;
+  },
+  { shadow: false },
+);
+```
+
+С Light DOM нативный `<input>` — часть дерева документа, события не
+ретаргетируются, и submit формы работает нативно. Компромисс: стили не
+инкапсулированы (нужно скоупить самостоятельно).
+
+## Итого
+
+| Задача                      | Решение Shadow DOM                     | Альтернатива Light DOM      |
+| --------------------------- | -------------------------------------- | --------------------------- |
+| `useForm` + кастомный input | Proxy `name`/`value` на host           | Нативный `<input>` в slot   |
+| Submit формы                | `form.requestSubmit()` в click handler | Нативная кнопка работает    |
+| Реактивные атрибуты         | `ctx.attr()` → авто-сигнал             | `ctx.attr()` работает везде |
+| Инкапсуляция стилей         | Да (автоматически)                     | Ручной `@scope` или BEM     |

package/docs/ru/README.md

@@ -1,21 +1,22 @@
 # Mado docs — Русский
 
-| Раздел | Файл |
-|---|---|
-| Принципы | [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) |
-| Архитектура приложения | [10-app-architecture.md](./10-app-architecture.md) |
-| Layouts | [11-layouts.md](./11-layouts.md) |
-| Auth and API | [12-auth-and-api.md](./12-auth-and-api.md) |
-| Deployment | [13-deployment.md](./13-deployment.md) |
-| Тестирование | [14-testing.md](./14-testing.md) |
-| Обработка ошибок | [15-error-handling.md](./15-error-handling.md) |
-| Bake cookbook | [16-bake-cookbook.md](./16-bake-cookbook.md) |
+| Раздел                      | Файл                                                         |
+| --------------------------- | ------------------------------------------------------------ |
+| Принципы                    | [00-the-mado-way.md](./00-the-mado-way.md)                   |
+| Маршрутизация               | [01-routing.md](./01-routing.md)                             |
+| Структура проекта           | [02-project-layout.md](./02-project-layout.md)               |
+| Статический bake и SEO      | [03-static-bake.md](./03-static-bake.md)                     |
+| Настройка IDE               | [04-ide-setup.md](./04-ide-setup.md)                         |
+| Почему Mado                 | [05-why-mado.md](./05-why-mado.md)                           |
+| Для бекендеров              | [06-for-backenders.md](./06-for-backenders.md)               |
+| Типичные ошибки LLM         | [07-llm-pitfalls.md](./07-llm-pitfalls.md)                   |
+| Тест LLM с нулевой историей | [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)     |
+| Архитектура приложения      | [10-app-architecture.md](./10-app-architecture.md)           |
+| Макеты (layouts)            | [11-layouts.md](./11-layouts.md)                             |
+| Авторизация и API           | [12-auth-and-api.md](./12-auth-and-api.md)                   |
+| Развёртывание               | [13-deployment.md](./13-deployment.md)                       |
+| Тестирование                | [14-testing.md](./14-testing.md)                             |
+| Обработка ошибок            | [15-error-handling.md](./15-error-handling.md)               |
+| Рецепты bake                | [16-bake-cookbook.md](./16-bake-cookbook.md)                 |
+| Shadow DOM + формы          | [17-shadow-dom-forms.md](./17-shadow-dom-forms.md)           |

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

@@ -27,10 +27,10 @@ count.set(1);
 
 ```ts
 // Ні
-count.value
+count.value;
 
 // Так
-count()
+count();
 ```
 
 ## Нереактивний child binding
@@ -60,7 +60,11 @@ html`<button ?disabled=${loading}>Save</button>`;
 items().map((item) => html`<li>${item.name}</li>`);
 
 // Так
-each(items(), (item) => item.id, (item) => html`<li>${item.name}</li>`);
+each(
+  items(),
+  (item) => item.id,
+  (item) => html`<li>${item.name}</li>`,
+);
 ```
 
 ## Imports
@@ -80,3 +84,60 @@ import "./components/x-card.js";
 
 Custom element name має містити дефіс. `x-*` — демо-конвенція; production може
 мати `app-*`, `crm-*`, `ticket-*`, `admin-*`.
+
+## `host.getAttribute()` у render — не реактивно
+
+```ts
+// Ні: читається один раз, не оновлюється
+component("x-badge", ({ host }) => () => {
+  const variant = host.getAttribute("variant") ?? "default";
+  return html`<span class=${variant}>...</span>`;
+});
+
+// Так: ctx.attr() — реактивний Signal
+component("x-badge", ({ attr }) => {
+  const variant = attr("variant", "default");
+  return () => html`<span class=${() => `badge-${variant()}`}>...</span>`;
+});
+```
+
+## Shadow DOM кнопка і submit форми
+
+`<button type="submit">` всередині Shadow DOM не тригерить submit `<form>` у Light DOM.
+Використовуйте `form.requestSubmit()` у click handler.
+
+```ts
+const handleClick = () => {
+  const form = host.closest("form");
+  if (form && !host.hasAttribute("disabled")) form.requestSubmit();
+};
+```
+
+## `useForm()` + Shadow DOM input
+
+Після ретаргетингу `e.target` — це `<x-input>`, у якого немає `.name`/`.value`.
+Додайте proxy-властивості на host:
+
+```ts
+Object.defineProperty(host, "name", {
+  get: () => host.getAttribute("name") ?? "",
+});
+Object.defineProperty(host, "value", {
+  get: () => host.shadowRoot?.querySelector("input")?.value ?? "",
+});
+```
+
+Детальніше: [`17-shadow-dom-forms.md`](./17-shadow-dom-forms.md).
+
+## Шпаргалка
+
+| React/інше                  | Mado                         |
+| --------------------------- | ---------------------------- |
+| `useState(0)`               | `signal(0)`                  |
+| `useEffect(() => {...})`    | `effect(() => {...})`        |
+| `useMemo(() => x)`          | `computed(() => x)`          |
+| `useQuery(['key'], fn)`     | `resource(() => 'key', fn)`  |
+| `useRouter().push('/')`     | `navigate('/')`              |
+| `class extends HTMLElement` | `component('x-name', setup)` |
+| `host.getAttribute('x')`    | `ctx.attr('x', default)`     |
+| `jsonFetcher()` з auth      | `apiFetcher()`               |