@madojs/mado 0.11.1 → 0.12.0

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

@@ -1,193 +0,0 @@
-# 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/18-api-freeze-map.md

@@ -1,64 +0,0 @@
-# Карта заморозки API
-
-> Что публично, что внутреннее, и что SemVer будет защищать в v1.
-
-Контракт Mado v1 намеренно небольшой. Код приложения импортирует API из корня
-пакета:
-
-```ts
-import { component, html, resource, routes, signal } from "@madojs/mado";
-```
-
-Публичные subpaths — side-effect модуль devtools и Vite integration:
-
-```ts
-import "@madojs/mado/devtools.js";
-import { mado } from "@madojs/mado/vite";
-```
-
-Все остальное под `dist/src/` — деталь реализации, даже если файл виден в
-репозитории.
-
-## Стабильный публичный API
-
-Эти имена публичны и будут защищены SemVer после v1:
-
-- Reactivity: `signal`, `computed`, `effect`, `untracked`, `batch`,
-  `flushSync`.
-- Templates и directives: `html`, `render`, `each`, `list`, `unsafeHTML`,
-  `ref`, `classMap`, `styleMap`.
-- Components и CSS: `component`, `css`, `cssVars`.
-- Routing и pages: `routes`, `router`, `page`, `layout`,
-  `navigate`, `queryParam`, `prefetchPath`.
-- Data: `resource`, `mutation`, `invalidate`, `jsonFetcher`, `HttpError`.
-- Forms: `useForm`.
-- Head и persistence: `applyHead`, `persisted`.
-- Context: `createContext`, `provide`, `inject`.
-- Advanced lifecycle helpers: `createLifecycle`, `runInLifecycle`,
-  `getCurrentLifecycle`.
-- Публичные TypeScript-типы, экспортируемые из `@madojs/mado`.
-
-## Внутреннее или нестабильное
-
-Это не публичный API:
-
-- Package subpaths кроме `@madojs/mado`, `@madojs/mado/devtools.js` и
-  `@madojs/mado/vite`.
-- Internals парсера/биндингов: `html/parser.js`, `html/bindings.js`,
-  `ChildState`, `EachEntry`.
-- Internals роутера: `router/match.js`, `router/navigation.js`,
-  `router/manifest.js`.
-- Diagnostics internals и все `_testHooks`.
-- Точный текст bundle, имена chunks и внутренняя структура файлов.
-
-Тесты репозитория могут импортировать внутренние файлы через относительные
-пути `dist/`. Код приложений так делать не должен.
-
-## Что может меняться
-
-Patch и minor релизы могут добавлять root exports, опции, diagnostics, docs или
-starter files. Они также могут менять internals, форму bundle и детали
-реализации, если стабильный API и задокументированное поведение остаются
-совместимыми.
-
-Ломающие изменения стабильного API требуют major version.

package/docs/ru/19-reactivity-ordering.md

@@ -1,95 +0,0 @@
-# Порядок reactivity
-
-> Небольшой набор ordering-гарантий, которые Mado считает публичным поведением.
-
-Reactivity в Mado синхронна для чтения и планирует side effects. Цель —
-предсказуемые UI-обновления без большой scheduling-модели.
-
-## Signals
-
-`signal(value)` возвращает getter-функцию. `set(next)` меняет значение сразу,
-если `Object.is(previous, next)` не вернул `true`.
-
-```ts
-const count = signal(0);
-count.set(1);
-count(); // 1, сразу
-```
-
-`computed` помечается до запуска effects, поэтому effect, читающий computed,
-видит актуальные dependencies, а не старый кеш.
-
-## Effects
-
-`effect(fn)` запускается один раз сразу. Последующие изменения dependencies
-планируют один запуск effect в microtask. В тестах можно вызвать `flushSync()`,
-чтобы синхронно очистить очередь.
-
-Если effect возвращает cleanup-функцию, Mado запускает ее перед следующим
-запуском effect и еще раз при вызове disposer.
-
-```ts
-const stop = effect(() => {
-  const id = setInterval(tick, 1000);
-  return () => clearInterval(id);
-});
-
-stop();
-```
-
-В компонентах и pages для unmount cleanup предпочитайте `ctx.onDispose()` /
-page `onDispose()`. Cleanup effect — это cleanup между запусками.
-
-## Batch
-
-`batch(fn)` группирует записи signals в один subscriber pass. Effects не
-запускаются до выхода из внешнего batch, включая вложенные batches.
-
-```ts
-batch(() => {
-  first.set("Ada");
-  batch(() => last.set("Lovelace"));
-});
-// effects увидят только финальную пару
-```
-
-Наблюдаемые `computed({ equals })` также сохраняют batch atomicity: они
-пересчитываются один раз после внешнего batch на полностью примененном state.
-Они не должны видеть половинчатый batch вроде `(new x, old y)`.
-
-## DOM updates
-
-`render(result, container)` переиспользует существующий template instance, когда
-следующий render имеет те же template strings. Для child bindings, возвращающих
-вложенный `html```, действует то же правило: те же strings обновляются на
-месте, другие strings пересобирают ветку.
-
-Это значит, что несвязанные изменения signals не пересоздают `<input>` внутри
-стабильного вложенного template, поэтому focus, DOM state и listeners
-сохраняются.
-
-Списки должны использовать `each(items, key, renderItem)`. Keys задают DOM
-identity. Duplicate keys предупреждают в development и получают positional
-suffix, чтобы все элементы все равно отрендерились, но duplicate keys — это
-ошибка данных.
-
-## Teardown компонентов
-
-Custom elements могут получить `disconnectedCallback()`, а затем
-`connectedCallback()` во время same-tick move. Mado откладывает teardown
-компонента до microtask и отменяет его при reconnect, поэтому keyed reorders
-сохраняют state компонента. Настоящее удаление все равно запускает cleanup на
-следующей microtask.
-
-## Не гарантируется
-
-Mado не гарантирует точное число внутренних scheduler microtasks, порядок
-независимых effects без общих dependencies, форму generated bundle или
-внутреннюю структуру modules. Это детали реализации.
-
-Invariant tests для этого контракта:
-
-- `test/reactivity-ordering.test.mjs`
-- `test/signal-batch-equals.test.mjs`
-- `test/update-nested-reuse.test.mjs`
-- `test/each-component-state.test.mjs`

package/docs/ru/20-v1-stability.md

@@ -1,82 +0,0 @@
-# Стабильность v1
-
-> Что Mado обещает после v1, и что остается свободным для развития.
-
-Mado v1 означает, что публичный app-facing contract достаточно стабилен для
-реальных business apps. Это не значит, что каждый внутренний файл, generated
-byte, starter copy или diagnostic string заморожены навсегда.
-
-Читайте вместе с:
-
-- [Карта заморозки API](./18-api-freeze-map.md)
-- [Порядок reactivity](./19-reactivity-ordering.md)
-
-## Стабильно под SemVer
-
-После v1 Mado считает SemVer-protected:
-
-- Public exports из `@madojs/mado`.
-- Public TypeScript types из `@madojs/mado`.
-- Side-effect subpath `@madojs/mado/devtools.js`.
-- Template binding syntax: child `${}`, `@event`, `.prop`, `?boolean`,
-  attribute bindings, directives и `each()`.
-- Signal semantics, описанные в reactivity ordering guide.
-- Component lifecycle semantics: setup один раз за connection lifetime,
-  deferred teardown для same-tick moves, cleanup через `ctx.onDispose`.
-- Router/page/resource/form contracts, описанные в English docs.
-- Имена CLI commands и широкий смысл команд (`build`, `dev`, `release`,
-  `bake`, `preview`, `init`, `new`).
-
-Ломать это можно только в major version.
-
-## Разрешено в minor releases
-
-Minor releases могут добавлять:
-
-- New root exports.
-- New options на существующих API.
-- New diagnostics и warnings.
-- New starters, examples, docs и CLI flags.
-- Performance improvements и внутренние rewrites.
-
-Minor release не должен требовать изменений в уже корректных apps.
-
-## Разрешено в patch releases
-
-Patch releases могут исправлять bugs, ужесточать diagnostics, улучшать docs и
-делать совместимые implementation changes. Patch может изменить timing только
-когда старый timing был незадокументированным bug и новое поведение сохраняет
-reactivity ordering contract.
-
-## Нестабильно
-
-Это намеренно не защищено SemVer:
-
-- Internal package subpaths кроме `@madojs/mado/devtools.js`.
-- Файлы под `src/`, `dist/src/` и implementation module boundaries.
-- `_testHooks`, diagnostics internals и warning codes.
-- Точный JavaScript output, chunk names, sourcemap content и bundle byte layout.
-- Internal parser, binding, router и resource cache data structures.
-- Visual copy и demo data в starters.
-
-Apps не должны импортировать internal files или проверять точный bundle output.
-
-## Bundle и release output
-
-Mado держит size budget и deterministic release tests, но v1 stability не
-замораживает byte-for-byte bundler output. Hashes, chunk boundaries и asset
-names могут меняться, если задокументированный deployment contract продолжает
-работать.
-
-## Если релиз вас сломал
-
-Если update ломает код, который использует только public exports и
-задокументированное поведение, считайте это bug. Откройте issue и укажите:
-
-- версию Mado до и после;
-- задействованный public API;
-- минимальную репродукцию;
-- это runtime behaviour, TypeScript types, CLI output или docs.
-
-Если поломка зависит от internal subpath или точного generated output, ее все
-равно можно зарепортить, но это не считается SemVer break.

package/docs/ru/README.md

@@ -1,25 +0,0 @@
-# Mado docs — Русский
-
-| Раздел                      | Файл                                                         |
-| --------------------------- | ------------------------------------------------------------ |
-| Принципы                    | [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)           |
-| Карта заморозки API         | [18-api-freeze-map.md](./18-api-freeze-map.md)               |
-| Порядок reactivity          | [19-reactivity-ordering.md](./19-reactivity-ordering.md)     |
-| Стабильность v1             | [20-v1-stability.md](./20-v1-stability.md)                   |

package/docs/uk/00-the-mado-way.md

@@ -1,82 +0,0 @@
-# Шлях Mado
-
-> Один зрозумілий шлях. Жорсткі контракти. Мінімум магії.
-
-Mado — framework для команд, що будують admin panels, internal tools і
-business SPA. Такі apps мають бути простими у розробці та нудними в підтримці,
-тому Mado обирає чіткі conventions замість п'яти рівноправних стилів.
-
-## Principles
-
-1. **One way.** If code feels unusual, first check whether a canonical helper/API
-   already exists.
-2. **Explicit over magic.** No file-system scanners, implicit globals or hidden
-   side effects.
-3. **Platform first.** Web Components, History API, `<form>`, `fetch` and Shadow
-   DOM stay visible.
-4. **Strict types.** `tsc --strict --noUncheckedIndexedAccess` always.
-5. **No runtime dependencies.** Dev/build tooling is fine; Mado runtime stays
-   native.
-
-## Project Structure
-
-```txt
-src/
-├── main.ts           ← boot: global CSS/providers + render router
-├── app.routes.ts     ← readable app map, exports `manifest` + default routes()
-├── layouts/          ← app-zone wrappers (`page({ view: ({ child }) => ... })`)
-├── shared/           ← UI bricks, http client, pure lib, global CSS
-└── modules/          ← bounded contexts
-    └── billing/
-        ├── billing.routes.ts
-        ├── billing.public.ts
-        ├── billing.types.ts
-        ├── pages/
-        ├── data/
-        ├── api/
-        └── _contracts/
-```
-
-The default starter is the canonical version of this shape.
-
-## One Component = One File
-
-```ts
-import { component, css, html } from "@madojs/mado";
-
-component("x-user-card", () => () => html`<div class="card"><slot></slot></div>`, {
-  styles: css`
-    .card { padding: 1rem; }
-  `,
-});
-```
-
-Importing the component file registers the element. Import it where the tag is
-used.
-
-## One Way To Describe A Page
-
-```ts
-import { html, page, resource, jsonFetcher } from "@madojs/mado";
-
-export default page({
-  title: ({ id }) => `User #${id}`,
-  view: ({ params }) => {
-    const user = resource(() => `/api/users/${params.id}`, jsonFetcher());
-    return html`...`;
-  },
-});
-```
-
-Page-local signals, resources and forms live inside `view()`. Module-wide state
-lives in `*.service.ts`.
-
-## What We Do Not Do
-
-- No JSX/Vue/Svelte syntax.
-- No custom elements without a hyphen.
-- No signal `.value`; a signal is a function.
-- No direct `innerHTML`.
-- No runtime packages without discussion.
-
-When in doubt, document one clear recipe instead of adding a new core primitive.

package/docs/uk/01-routing.md

@@ -1,76 +0,0 @@
-# Routing
-
-> One app map. No folder scanners. No magic path syntax.
-
-Mado uses an explicit route manifest. Route composition should be readable in
-one place: `src/app.routes.ts`.
-
-```ts
-import { layout, routes } from "@madojs/mado";
-import { requireAuth } from "./modules/auth/auth.public";
-import { authRoutes } from "./modules/auth/auth.routes";
-import { billingRoutes } from "./modules/billing/billing.routes";
-
-export const manifest = {
-  "/": () => import("./modules/home/home.page.js"),
-  "/login": layout({
-    layout: () => import("./layouts/auth-shell.layout.js"),
-    routes: authRoutes,
-  }),
-  "/billing": layout({
-    layout: () => import("./layouts/app-shell.layout.js"),
-    guard: requireAuth,
-    routes: billingRoutes,
-  }),
-  "*": () => import("./modules/home/not-found.page.js"),
-};
-
-export default routes(manifest);
-```
-
-Export `manifest` so `mado bake` can read it.
-
-## Module Routes
-
-Modules export plain route maps. They do not call `layout()`.
-
-```ts
-export const billingRoutes = {
-  "/invoices": () => import("./pages/invoices-list.page.js"),
-  "/invoices/:id": () => import("./pages/invoice-detail.page.js"),
-};
-```
-
-The prefix is applied by `src/app.routes.ts`.
-
-## Page
-
-```ts
-import { html, page } from "@madojs/mado";
-
-export default page<{ id: string }>({
-  title: ({ id }) => `User ${id}`,
-  view: ({ params }) => html`<h1>${params.id}</h1>`,
-});
-```
-
-## Navigation
-
-```ts
-import appRoutes from "./app.routes.js";
-
-appRoutes.navigate("/billing/invoices");
-appRoutes.navigate("/billing/invoices?page=2");
-appRoutes.navigate("/login", { replace: true });
-```
-
-## Query Params
-
-```ts
-import { queryParam } from "@madojs/mado";
-
-const search = queryParam("q", "");
-search.set("mado");
-```
-
-`queryParam()` returns a signal-like API and syncs state with the URL.