@madojs/mado 0.10.1 → 0.11.0

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

@@ -2,55 +2,81 @@
 
 > Один зрозумілий шлях. Жорсткі контракти. Мінімум магії.
 
-Mado — фреймворк для команд, що будують адмін-панелі, внутрішні інструменти
-та бізнес-SPA — застосунки, які мають бути простими у розробці та нудними в
-підтримці. Для цього він задає **набір домовленостей**. Якщо їх дотримуватись,
-проєкт залишається читабельним навіть тоді, коли в ньому десятки сторінок і
-кілька розробників.
-
-## Принципи
-
-1. **Один спосіб.** Для типової задачі має бути один канонічний шлях, а не п’ять
-   рівноправних стилів.
-2. **Явність замість магії.** Немає сканерів файлів, прихованих глобалів і
-   неочевидних side effects.
-3. **Платформа спочатку.** Якщо браузер уже має потрібну можливість, Mado дає
-   тонку обгортку, а не переписує платформу.
-4. **Суворий TypeScript.** `tsc --strict` — базовий контракт.
-5. **Нуль runtime-залежностей.** Кожна залежність — це довгострокове
-   зобов’язання.
-
-## Базова структура
-
-```text
+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/
-├── routes.ts
-├── main.ts
-├── pages/
-├── components/
-├── layouts/
-├── lib/
-└── styles/
+├── 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; }
+  `,
+});
 ```
 
-Кожна сторінка живе в окремому файлі та експортує `page({...})`.
-Компоненти реєструються через `component()`. Дані читаються через `resource()`,
-зміни виконуються через `mutation()`, списки рендеряться через `each()`.
+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`...`;
+  },
+});
+```
 
-Єдине правило браузера: ім’я custom element має містити дефіс. `x-*` у прикладах
-Mado — це демо-конвенція, а не вимога фреймворку. У production краще брати
-префікс домену: `app-*`, `crm-*`, `ticket-*`, `admin-*`.
+Page-local signals, resources and forms live inside `view()`. Module-wide state
+lives in `*.service.ts`.
 
-## Чого не робимо
+## What We Do Not Do
 
-- Не пишемо JSX або Vue-шаблони.
-- Не читаємо сигнал через `.value`; сигнал читається як функція: `count()`.
-- Не використовуємо `disabled=${...}` для булевих атрибутів; треба
-  `?disabled=${...}`.
-- Не рендеримо динамічні списки через `.map()` там, де потрібне збереження DOM
-  стану; використовуємо `each()`.
-- Не додаємо runtime-залежності без дуже вагомої причини.
+- 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.
 
-Коли є сумнів, краще додати рецепт у документацію, ніж новий primitive в core.
+When in doubt, document one clear recipe instead of adding a new core primitive.

package/docs/uk/01-routing.md

@@ -1,76 +1,70 @@
-# Маршрутизація
+# Routing
 
-Mado використовує явний route manifest: один файл показує весь URL-граф
-застосунку.
+> 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 { routes } from "@madojs/mado";
+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("./pages/home.js"),
-  "/users/:id": () => import("./pages/user-detail.js"),
-  "*": () => import("./pages/not-found.js"),
+  "/": () => 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);
 ```
 
-## Сторінка
-
-```ts
-import { page, html } from "@madojs/mado";
-
-export default page<{ id: string }>({
-  title: ({ id }) => `User ${id}`,
-  view: ({ params }) => html`<x-user data-id=${params.id}></x-user>`,
-});
-```
+Export `manifest` so `mado bake` can read it.
 
-Сторінка може мати `title`, `head`, `load`, `view`, `errorView` і `bake`.
-Маршрут може бути lazy import або готовим `page({...})`.
+## Module Routes
 
-## Nested routes
+Modules export plain route maps. They do not call `layout()`.
 
 ```ts
-import { nested, routes } from "@madojs/mado";
-
-export const manifest = {
-  "/": () => import("./pages/home.js"),
-  "/app": nested({
-    layout: () => import("./layouts/app-layout.js"),
-    routes: {
-      "/dashboard": () => import("./pages/dashboard.js"),
-      "/settings": () => import("./pages/settings.js"),
-    },
-  }),
+export const billingRoutes = {
+  "/invoices": () => import("./pages/invoices-list.page.js"),
+  "/invoices/:id": () => import("./pages/invoice-detail.page.js"),
 };
-
-export default routes(manifest);
 ```
 
-Layout отримує дочірній view і може рендерити shell: nav, sidebar, toolbar,
-notifications.
+The prefix is applied by `src/app.routes.ts`.
 
-## Навігація
+## Page
 
-Посилання з `data-link` перехоплюються роутером:
+```ts
+import { html, page } from "@madojs/mado";
 
-```html
-<a href="/users/42" data-link>Open</a>
+export default page<{ id: string }>({
+  title: ({ id }) => `User ${id}`,
+  view: ({ params }) => html`<h1>${params.id}</h1>`,
+});
 ```
 
-Програмна навігація:
+## Navigation
 
 ```ts
-import { navigate } from "@madojs/mado";
+import appRoutes from "./app.routes.js";
 
-navigate("/users/42");
+appRoutes.navigate("/billing/invoices");
+appRoutes.navigate("/billing/invoices?page=2");
+appRoutes.navigate("/login", { replace: true });
 ```
 
-Router підтримує hover-prefetch, stale async guard, scroll-to-top для нової
-навігації та `dispose()` для тестів/dev overlay.
-
-## Query params
+## Query Params
 
 ```ts
 import { queryParam } from "@madojs/mado";
@@ -79,4 +73,4 @@ const search = queryParam("q", "");
 search.set("mado");
 ```
 
-`queryParam()` повертає signal-like API і синхронізує стан із URL.
+`queryParam()` returns a signal-like API and syncs state with the URL.

package/docs/uk/02-project-layout.md

@@ -1,46 +1,73 @@
 # Структура проєкту
 
-Рекомендована структура Mado-застосунку:
-
-```text
-src/
-├── main.ts
-├── routes.ts
-├── pages/
-├── components/
-├── layouts/
-├── lib/
-└── styles/
+Кожен Mado-застосунок використовує одну канонічну форму. Це потрібно, щоб люди
+й AI-асистенти однаково розуміли, де живе код.
+
+```txt
+my-app/
+├── package.json              # runtime dep: @madojs/mado
+├── tsconfig.json             # strict TS, ES2022, Bundler resolution
+├── vite.config.ts            # mado() from @madojs/mado/vite
+├── index.html                # Vite entry + SPA shell
+├── public/                   # static assets: favicon, images, robots.txt
+└── src/
+    ├── main.ts               # imports CSS and mounts router into #app
+    ├── app.routes.ts         # app map: manifest + default routes(...)
+    ├── layouts/              # app-zone layouts
+    ├── shared/               # ui, http, lib, styles
+    └── modules/              # bounded contexts
+        └── billing/
+            ├── billing.routes.ts
+            ├── billing.public.ts
+            ├── billing.types.ts
+            ├── pages/
+            ├── data/
+            ├── api/
+            └── _contracts/
 ```
 
-## `main.ts`
-
-Точка входу: встановлює глобальні стилі, провайдери контексту та монтує кореневий
-компонент у `#app`.
-
-## `routes.ts`
-
-Єдиний manifest маршрутів. Немає file-system routing, груп у назвах папок або
-прихованих conventions.
-
-## `pages/`
-
-Одна сторінка — один файл — `export default page({...})`.
-
-## `components/`
-
-Повторно використовувані Web Components. Імпорт файлу реєструє компонент як side
-effect.
-
-## `layouts/`
-
-Shell для nested routes: admin layout, marketing layout, authenticated area.
-
-## `lib/`
-
-API-клієнти, contexts, чиста бізнес-логіка без UI.
-
-## `styles/`
+## Artifact States
+
+| Folder | Що це | Хто пише | Deploy? |
+| --- | --- | --- | --- |
+| `src/` | TypeScript sources | ви | no |
+| `public/` | static assets copied as-is | ви | via `out/` |
+| `out/` | deploy artifact: SPA shell + assets + baked HTML | `mado release` | yes |
+
+`mado release` = `typecheck` + Vite build (`out/index.html`, `out/assets/`,
+`public/*`) + `bake` directly into route paths + `sitemap.xml` + precompression.
+
+## Where To Put Files
+
+| What | Where |
+| --- | --- |
+| Page for a new URL | `src/modules/<module>/pages/<name>.page.ts` + module routes |
+| Module route map | `src/modules/<module>/<module>.routes.ts` |
+| App shell/layout | `src/layouts/<zone>.layout.ts` |
+| Shared UI widget | `src/shared/ui/<x-name>.component.ts` |
+| Module-only UI widget | `src/modules/<module>/components/<name>.component.ts` |
+| API connector | `src/modules/<module>/api/<provider>.connector.ts` |
+| Data resource/mutation | `src/modules/<module>/data/<name>.resource.ts` |
+| Auth/session | `src/modules/auth/` |
+| Public module surface | `src/modules/<module>/<module>.public.ts` |
+| Pure function without UI | `src/shared/lib/<name>.ts` |
+| Static image / favicon | `public/<file>` |
+| App-zone shell CSS | `src/shared/styles/shell.css` |
+| Page-level CSS | `src/shared/styles/content.css` |
+
+## Vite Config
+
+```ts
+import { defineConfig } from "vite";
+import { mado } from "@madojs/mado/vite";
+
+export default defineConfig({
+  plugins: [mado()],
+  css: {
+    transformer: "lightningcss",
+  },
+});
+```
 
-Глобальні tokens або shared CSS через `css```. Для app-shell часто зручно
-використовувати Light DOM, для leaf-компонентів — Shadow DOM.
+Starter uses Vite's Lightning CSS transformer. Mado does not own prefixing, CSS
+lowering or minification.

package/docs/uk/03-static-bake.md

@@ -42,8 +42,7 @@ export default page<{ slug: string }, Product>({
 ## Edge prerender
 
 Для великих наборів сторінок можна робити той самий підхід на edge: Cloudflare
-Worker генерує HTML на cache miss, кладе в KV і віддає з TTL. Приклад лежить в
-`examples/cloudflare`.
+Worker генерує HTML на cache miss, кладе в KV і віддає з TTL.
 
 Це не hydration. Клієнтський Mado-застосунок все одно стартує нормально і
 перерендерює сторінку після завантаження.

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

@@ -7,7 +7,7 @@
 |---|---|
 | router | `routes()` |
 | handler | `page().view` |
-| middleware/layout | `nested()` + layout |
+| middleware/layout | `layout()` route group |
 | cache get-or-set | `resource()` |
 | POST/PUT/DELETE | `mutation()` |
 | cache invalidation | `invalidates` / `invalidate()` |
@@ -44,8 +44,8 @@ Mado використовує schema-based validation, близьку до HTML
 
 ## Auth
 
-Auth зазвичай живе в `lib/auth.ts` як signal/context. Protected area зручно
-робити через nested layout, який перевіряє session і показує dashboard або
+Auth зазвичай живе в `modules/auth` як signal/context. Protected area зручно
+робити через `layout()` group, який перевіряє session і показує dashboard або
 redirect/login.
 
 ## Правило

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

@@ -1,36 +1,34 @@
 # LLM Zero-History Test
 
-Мета тесту: перевірити, чи може LLM без попередньої історії написати ідіоматичний
-Mado CRUD, не перетворюючи його на React у tagged templates.
+This document defines a manual validation test: can a fresh LLM write idiomatic
+Mado without falling back to React-shaped code?
 
-## Дозволений контекст
+## Allowed Context
 
 - `AGENTS.md`
 - `README.md`
-- `docs/uk/07-llm-pitfalls.md` або відповідна англійська версія
-- `examples/basic/README.md`
-- конкретні файли прикладів тільки за потреби
+- `docs/uk/07-llm-pitfalls.md` or the English version
+- files from the external `madojs-examples` workspace only when the agent asks
+  for a larger app pattern
 
-## Що перевіряти
+## Task
 
-- Немає JSX, `useState`, `useEffect`.
-- Немає signal `.value`.
-- Reactive child bindings з `count()` обгорнуті у `() =>`.
-- Boolean attributes пишуться як `?disabled`, `?checked`.
-- Динамічні списки використовують `each()`.
-- Imports мають `.js`.
-- `resource()` створюється в lifecycle-aware контексті.
+Build a small ticket-admin SPA:
 
-## Артефакт
+- routes: `/`, `/tickets`, `/tickets/new`, `/tickets/:id`, `*`;
+- in-memory mock API with realistic async delays;
+- list page with `resource()`, `queryParam()`, `computed()` and keyed `each()`;
+- create/edit flows with `useForm()` + `mutation()` + `invalidates`;
+- local UI state with `signal()`.
 
-`examples/tickets` — маленький ticket-admin SPA з routes, mock API, forms,
-resources, mutations, invalidation, `queryParam`, `computed`, `signal` і
-keyed lists.
+## Failure Checklist
 
-CI запускає `npm run llm:smoke` як детермінований proxy для цієї задачі:
-перевіряє, що `llms.txt` містить ключові правила, звіряє закомічений артефакт
-`examples/tickets` з потрібною Mado API surface та failure patterns, потім
-збирає проєкт і запускає `test/tickets-smoke.test.mjs`.
+- JSX, `useState`, `useEffect`, `ref`, `$state`, class-style components;
+- `${signal()}` where a reactive child thunk is required;
+- `disabled=${...}` instead of `?disabled=${...}`;
+- unkeyed `.map()` for dynamic lists;
+- `resource()` created outside lifecycle-aware context;
+- new runtime dependencies or new public APIs.
 
-Критерій успіху: код виглядає як Mado, а не як React/Vue, переодягнений у
-template strings.
+The historical tickets implementation lives in the external examples workspace.
+The core repository no longer ships that artifact.

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

@@ -1,107 +1,58 @@
 # Shadow DOM vs Light DOM
 
-Mado використовує Shadow DOM за замовчуванням. Це хороший default для
-самодостатніх widgets, але не для кожного компонента в app.
+Mado components use Shadow DOM by default. This is good for self-contained
+widgets, but app zones and pages usually stay as light DOM templates.
 
-## Практичне правило
+## Rule
 
-У Mado layout — це теж component. Якщо файл описує видиму reusable частину
-UI-дерева — app shell, sidebar, modal, table, page section — за замовчуванням
-робіть Web Component через `component()`.
-
-Звичайні функції залишайте для маленьких inline helpers:
-
-```ts
-const money = (value: number) => html`<span>${formatMoney(value)}</span>`;
-```
-
-Не варто робити app shell функцією в public examples. Це працює, але ховає
-browser model замість того, щоб її пояснювати.
-
-Використовуйте **Shadow DOM** для leaf widgets:
-
-- buttons, badges, cards, metrics;
-- modals, toasts, small visual components;
-- embedded widgets, які не мають випадково успадковувати app CSS;
-- components, чиї styles належать самому component.
-
-Використовуйте **Light DOM** (`{ shadow: false }`) для app structure, якій
-потрібні global CSS utilities:
-
-- route/page components;
-- admin screens з dense table/form layouts;
-- data-heavy screens з tables and forms;
-- місця, де children мають залишатися normal document DOM.
-
-Використовуйте **Shadow DOM** для slot-based layouts:
-
-- app shells, які render `<slot>`;
-- sidebar/content wrappers;
-- reusable layout frames, які володіють своїм grid/header/sidebar CSS.
-
-`<slot>` — це feature Shadow DOM. У component з `shadow: false` тег `<slot>` є
-звичайним DOM element і не переносить children у це місце layout.
-
-## Як працює import
+Use route layouts for app zones:
 
 ```ts
-import "./components/app-layout.js";
-
-render(html`<x-app-layout>${router.view}</x-app-layout>`, app);
+export default page({
+  view: ({ child }) => html`<main class="app-main">${child}</main>`,
+});
 ```
 
-Import реєструє custom element через `customElements.define()`. Template створює
-`<x-app-layout>` element. Далі browser сам з'єднує tag з component class. Це не
-React-style component value, який передається як function.
-
-## Routing and links
+These files live in `src/layouts/` and are composed from `src/app.routes.ts`
+with `layout()`. They are styled by `src/shared/styles/shell.css`.
 
-`data-link` працює всередині Shadow DOM, бо router використовує
-`event.composedPath()`.
+Use page files for screens:
 
 ```ts
-component("x-card-link", () => () => html`
-  <a href="/app/accounts" data-link>Accounts</a>
-`);
+export default page({
+  view: () => html`<section><h1>Users</h1></section>`,
+});
 ```
 
-Link може бути в Shadow DOM; navigation все одно залишається SPA.
+Page-level tables, forms, prose and simple states are styled by
+`src/shared/styles/content.css`.
 
-## Де імпортувати компоненти
+Use Shadow DOM components for leaf widgets:
 
-Custom elements стають global після registration, але registration все одно є
-явним JavaScript import.
+- buttons, badges, cards, metrics;
+- spinners, modals, toasts;
+- widgets that should own their CSS.
 
 ```ts
-// main.ts: global app frame
-import "./components/app-shell.js";
-
-// pages/tickets.ts: component, яким володіє ця page
-import "../components/ticket-list.js";
+component("x-status-badge", ({ attr }) => {
+  const status = attr("status", "draft");
+  return () => html`<span>${status}</span>`;
+}, {
+  styles: css`
+    :host { display: inline-block; }
+    span { color: var(--color-text-muted); }
+  `,
+});
 ```
 
-Browser **не** завантажує `ticket-list.js` лише тому, що побачив
-`<ticket-list>`. File має бути imported десь першим. Після import він викликає
-`customElements.define(...)`, і tag стає відомим у поточному document.
-
-Не робіть bulk-import усіх components у `main.ts` "just in case". Це працює в
-tiny demos, але ховає ownership і ламає lazy route loading. Краще:
-
-- global app shell/providers імпортувати в `main.ts`;
-- components, якими володіє одна page, імпортувати в цій page;
-- shared feature components імпортувати у feature entry page;
-- truly global leaf components імпортувати в `main.ts` лише якщо вони реально
-  використовуються всюди.
-
-## Showcase lesson
-
-`examples/showcase` використовує цей split навмисно:
+## Style Behavior
 
-- `x-app` і CRM route pages — Light DOM;
-- `x-app-layout` — Shadow DOM, бо він володіє slot-based sidebar/content shell;
-- table/form/page utilities живуть у `styles/global.ts`;
-- leaf components на кшталт `x-stat-card`, `x-status-badge`, `x-modal`,
-  `x-toast-stack` залишають Shadow DOM.
+- `tokens.css` defines CSS custom properties; `var(...)` crosses Shadow DOM.
+- `reset.css`, `shell.css`, `content.css` apply only to document/light DOM.
+- Class selectors like `.data`, `.app-main`, `.error` do not cross Shadow DOM.
+- Component-local styles live in ``css`...` `` inside `component()` options.
+- If a Shadow component accepts children, use `<slot>` and style the frame in
+  component styles.
 
-Якщо page раптом виглядає unstyled, перевірте, чи не використовує вона global
-classes всередині Shadow DOM component. Зазвичай проблема саме в цьому.
+If a page looks unstyled, you probably used global classes inside a Shadow DOM
+component. Move markup into a page/layout or move CSS into component styles.