@madojs/mado 0.5.0

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

@@ -0,0 +1,54 @@
+# Шлях Mado
+
+> Один зрозумілий шлях. Жорсткі контракти. Мінімум магії.
+
+Mado — це не лише набір API, а набір домовленостей. Якщо їх дотримуватись,
+проєкт залишається читабельним навіть тоді, коли в ньому десятки сторінок і
+кілька розробників.
+
+## Принципи
+
+1. **Один спосіб.** Для типової задачі має бути один канонічний шлях, а не п’ять
+   рівноправних стилів.
+2. **Явність замість магії.** Немає сканерів файлів, прихованих глобалів і
+   неочевидних side effects.
+3. **Платформа спочатку.** Якщо браузер уже має потрібну можливість, Mado дає
+   тонку обгортку, а не переписує платформу.
+4. **Суворий TypeScript.** `tsc --strict` — базовий контракт.
+5. **Нуль runtime-залежностей.** Кожна залежність — це довгострокове
+   зобов’язання.
+
+## Базова структура
+
+```text
+src/
+├── routes.ts
+├── main.ts
+├── pages/
+├── components/
+├── layouts/
+├── lib/
+└── styles/
+```
+
+Кожна сторінка живе в окремому файлі та експортує `page({...})`.
+Компоненти реєструються через `component()`. Дані читаються через `resource()`,
+зміни виконуються через `mutation()`, списки рендеряться через `each()`.
+
+## Імена компонентів
+
+Єдине правило браузера: ім’я custom element має містити дефіс. `x-*` у прикладах
+Mado — це демо-конвенція, а не вимога фреймворку. У production краще брати
+префікс домену: `app-*`, `crm-*`, `ticket-*`, `admin-*`.
+
+## Чого не робимо
+
+- Не пишемо JSX або Vue-шаблони.
+- Не читаємо сигнал через `.value`; сигнал читається як функція: `count()`.
+- Не використовуємо `disabled=${...}` для булевих атрибутів; треба
+  `?disabled=${...}`.
+- Не рендеримо динамічні списки через `.map()` там, де потрібне збереження DOM
+  стану; використовуємо `each()`.
+- Не додаємо runtime-залежності без дуже вагомої причини.
+
+Коли є сумнів, краще додати рецепт у документацію, ніж новий primitive в core.

package/docs/uk/01-routing.md

@@ -0,0 +1,82 @@
+# Маршрутизація
+
+Mado використовує явний route manifest: один файл показує весь URL-граф
+застосунку.
+
+```ts
+import { routes } from "@madojs/mado";
+
+export const manifest = {
+  "/": () => import("./pages/home.js"),
+  "/users/:id": () => import("./pages/user-detail.js"),
+  "*": () => import("./pages/not-found.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>`,
+});
+```
+
+Сторінка може мати `title`, `head`, `load`, `view`, `errorView` і `bake`.
+Маршрут може бути lazy import або готовим `page({...})`.
+
+## Nested routes
+
+```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 default routes(manifest);
+```
+
+Layout отримує дочірній view і може рендерити shell: nav, sidebar, toolbar,
+notifications.
+
+## Навігація
+
+Посилання з `data-link` перехоплюються роутером:
+
+```html
+<a href="/users/42" data-link>Open</a>
+```
+
+Програмна навігація:
+
+```ts
+import { navigate } from "@madojs/mado";
+
+navigate("/users/42");
+```
+
+Router підтримує hover-prefetch, stale async guard, scroll-to-top для нової
+навігації та `dispose()` для тестів/dev overlay.
+
+## Query params
+
+```ts
+import { queryParam } from "@madojs/mado";
+
+const search = queryParam("q", "");
+search.set("mado");
+```
+
+`queryParam()` повертає signal-like API і синхронізує стан із URL.

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

@@ -0,0 +1,46 @@
+# Структура проєкту
+
+Рекомендована структура Mado-застосунку:
+
+```text
+src/
+├── main.ts
+├── routes.ts
+├── pages/
+├── components/
+├── layouts/
+├── lib/
+└── styles/
+```
+
+## `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/`
+
+Глобальні tokens або shared CSS через `css```. Для app-shell часто зручно
+використовувати Light DOM, для leaf-компонентів — Shadow DOM.

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

@@ -0,0 +1,49 @@
+# Static Bake & SEO
+
+Mado навмисно не робить SSR із hydration. Для SEO-сторінок є `bake`: build-time
+prerender у статичний HTML із meta-тегами, JSON-LD і baked data.
+
+## Коли підходить
+
+- Блог, документація, landing pages.
+- Невеликі каталоги з кінцевим набором сторінок.
+- Сторінки, де crawlers мають одразу побачити контент.
+- Контент не персоналізований для конкретного користувача.
+
+## Коли не підходить
+
+- Авторизовані dashboards.
+- Персоналізований HTML.
+- Real-time дані.
+- Каталоги, які потребують справжнього server rendering на кожен запит.
+
+## Сторінка з bake
+
+```ts
+import { page, html } from "@madojs/mado";
+
+export default page<{ slug: string }, Product>({
+  title: ({ slug }) => `Product ${slug}`,
+  head: ({ slug }, data) => ({
+    description: data?.description ?? `Product ${slug}`,
+  }),
+  bake: {
+    paths: () => products.map((p) => ({ slug: p.slug })),
+    data: ({ slug }) => findProduct(slug),
+    revalidate: 3600,
+  },
+  view: ({ params }) => html`<x-product data-slug=${params.slug}></x-product>`,
+});
+```
+
+`bake.paths()` повертає всі params, `bake.data()` повертає дані для конкретної
+сторінки, `head()` формує SEO-метадані.
+
+## Edge prerender
+
+Для великих наборів сторінок можна робити той самий підхід на edge: Cloudflare
+Worker генерує HTML на cache miss, кладе в KV і віддає з TTL. Приклад лежить в
+`examples/cloudflare`.
+
+Це не hydration. Клієнтський Mado-застосунок все одно стартує нормально і
+перерендерює сторінку після завантаження.

package/docs/uk/04-ide-setup.md

@@ -0,0 +1,26 @@
+# Налаштування IDE
+
+Mado використовує tagged templates `html`` і `css``. Для TypeScript це звичайні
+рядки, тому підсвітка HTML/CSS залежить від IDE.
+
+## VS Code
+
+Рекомендовано встановити `lit-plugin` або інше розширення, яке розуміє
+`html``/`css`` tagged templates.
+
+## WebStorm
+
+WebStorm зазвичай розуміє tagged templates без додаткового налаштування.
+
+## Neovim / Helix
+
+Можна використовувати LSP/плагіни для lit-html або inline HTML у template
+strings.
+
+## Що IDE не перевірить
+
+- Чи правильно ти обгорнув `count()` у `() => count()`.
+- Чи варто використовувати `?disabled` замість `disabled`.
+- Чи є `.js` у browser ESM imports.
+
+Для цього потрібні правила з `AGENTS.md`, тести та уважний review.

package/docs/uk/05-why-mado.md

@@ -0,0 +1,34 @@
+# Чому Mado
+
+Mado не намагається “вбити React” або довести, що всі інші помиляються. Це
+інструмент для людей, які хочуть маленький, читабельний frontend runtime поверх
+нативного браузера.
+
+## Lit
+
+Lit чудовий для дизайн-систем і компонентів, які мають жити всередині будь-якого
+framework. Mado краще підходить, коли ти пишеш увесь застосунок і хочеш router,
+data, forms, context і static bake в одному маленькому пакеті.
+
+## Solid
+
+Solid швидший і зріліший. Якщо тобі комфортно з JSX transform, Vite і mature
+ecosystem — Solid може бути кращим вибором. Mado обирає інше: browser ESM,
+`tsc`, tagged templates і код, який можна прочитати.
+
+## htmx
+
+htmx сильний, коли backend володіє HTML fragments. Mado потрібен тоді, коли все
+ж хочеться SPA: локальний UI state, optimistic updates, query params, cached
+resources, persisted state і lazy modules.
+
+## React / Vue / Svelte
+
+Вони мають більші ecosystem, більше відповідей у Google/LLM і більше людей на
+ринку. Mado виграє не масштабом ecosystem, а ownership: маленький runtime,
+нуль runtime-залежностей і зрозумілі правила.
+
+## Головна теза
+
+Mado — не найшвидший у synthetic benchmarks і не найбагатший ecosystem. Його
+сенс у тому, що frontend знову можна тримати в голові.

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

@@ -0,0 +1,50 @@
+# Mado для бекендерів
+
+Якщо ти пишеш Go, Rust, .NET, Java, Python або Node backend, Mado можна уявляти
+як маленький HTTP-сервер у браузері.
+
+| Backend mental model | Mado |
+|---|---|
+| router | `routes()` |
+| handler | `page().view` |
+| middleware/layout | `nested()` + layout |
+| cache get-or-set | `resource()` |
+| POST/PUT/DELETE | `mutation()` |
+| cache invalidation | `invalidates` / `invalidate()` |
+| dependency injection | `createContext/provide/inject` |
+
+## CRUD
+
+```ts
+const users = resource(
+  () => "/api/users",
+  jsonFetcher<User[]>(),
+);
+
+const save = mutation(api.saveUser, {
+  invalidates: ["/api/users*"],
+});
+```
+
+## Форми
+
+```ts
+const form = useForm({
+  email: { required: true, type: "email" },
+});
+```
+
+Mado спирається на Constraint Validation API браузера, а не на окрему validation
+екосистему.
+
+## Auth
+
+Auth зазвичай живе в `lib/auth.ts` як signal/context. Protected area зручно
+робити через nested layout, який перевіряє session і показує dashboard або
+redirect/login.
+
+## Правило
+
+Не тягни backend-архітектуру в frontend дослівно. Тримай UI state локальним,
+data fetching через `resource()`, mutation через `mutation()`, а shared services
+через context.

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

@@ -0,0 +1,82 @@
+# Типові помилки LLM у Mado-коді
+
+Цей файл потрібен, щоб AI-агенти не писали React/Vue-код у Mado-проєкті.
+
+## JSX
+
+```ts
+// Ні
+const view = <button>{count}</button>;
+
+// Так
+const view = html`<button>${count}</button>`;
+```
+
+## `useState` / `useEffect`
+
+```ts
+// Ні
+const [count, setCount] = useState(0);
+
+// Так
+const count = signal(0);
+count.set(1);
+```
+
+## Signal `.value`
+
+```ts
+// Ні
+count.value
+
+// Так
+count()
+```
+
+## Нереактивний child binding
+
+```ts
+// Нереактивно: count() прочитано один раз
+html`<div>${count() * 2}</div>`;
+
+// Реактивно
+html`<div>${() => count() * 2}</div>`;
+```
+
+## Boolean attributes
+
+```ts
+// Ні
+html`<button disabled=${loading}>Save</button>`;
+
+// Так
+html`<button ?disabled=${loading}>Save</button>`;
+```
+
+## Списки
+
+```ts
+// Не для динамічного reorder
+items().map((item) => html`<li>${item.name}</li>`);
+
+// Так
+each(items(), (item) => item.id, (item) => html`<li>${item.name}</li>`);
+```
+
+## Imports
+
+У browser ESM локальні imports мають мати `.js`:
+
+```ts
+import "./components/x-card.js";
+```
+
+## `resource()` lifecycle
+
+`resource()` створюй у component setup або всередині явного lifecycle, щоб cleanup
+відбувався автоматично.
+
+## Component names
+
+Custom element name має містити дефіс. `x-*` — демо-конвенція; production може
+мати `app-*`, `crm-*`, `ticket-*`, `admin-*`.

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

@@ -0,0 +1,31 @@
+# LLM Zero-History Test
+
+Мета тесту: перевірити, чи може LLM без попередньої історії написати ідіоматичний
+Mado CRUD, не перетворюючи його на React у tagged templates.
+
+## Дозволений контекст
+
+- `AGENTS.md`
+- `README.md`
+- `docs/uk/07-llm-pitfalls.md` або відповідна англійська версія
+- `examples/basic/README.md`
+- конкретні файли прикладів тільки за потреби
+
+## Що перевіряти
+
+- Немає JSX, `useState`, `useEffect`.
+- Немає signal `.value`.
+- Reactive child bindings з `count()` обгорнуті у `() =>`.
+- Boolean attributes пишуться як `?disabled`, `?checked`.
+- Динамічні списки використовують `each()`.
+- Imports мають `.js`.
+- `resource()` створюється в lifecycle-aware контексті.
+
+## Артефакт
+
+`examples/tickets` — маленький ticket-admin SPA з routes, mock API, forms,
+resources, mutations, invalidation, `queryParam`, `computed`, `signal` і
+keyed lists.
+
+Критерій успіху: код виглядає як Mado, а не як React/Vue, переодягнений у
+template strings.

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

@@ -0,0 +1,40 @@
+# Shadow DOM vs Light DOM
+
+Mado використовує Shadow DOM за замовчуванням, але це не означає, що його треба
+вмикати всюди.
+
+## Shadow DOM добре підходить для
+
+- leaf-компонентів;
+- isolated widgets;
+- badges, cards, modals, buttons;
+- компонентів, які мають не ламатися від зовнішнього CSS.
+
+```ts
+component("x-badge", () => () => html`<span><slot></slot></span>`, {
+  styles: css`:host { display: inline-block; }`,
+});
+```
+
+## Light DOM краще для
+
+- app shell;
+- admin layouts;
+- route-level pages;
+- компонентів, які мають користуватися глобальними utility classes;
+- великих CRUD surfaces, де CSS має бути простим і передбачуваним.
+
+```ts
+component("x-app-layout", () => () => html`<main><slot></slot></main>`, {
+  shadow: false,
+  styles: css`x-app-layout main { display: grid; }`,
+});
+```
+
+## Практичне правило
+
+Якщо компонент — самостійний reusable visual, бери Shadow DOM. Якщо це частина
+app layout або page composition, часто краще Light DOM.
+
+Посилання з `data-link` працюють і в Shadow DOM, бо router використовує
+`event.composedPath()`.

package/docs/uk/README.md

@@ -0,0 +1,16 @@
+# Документація Mado — Українська
+
+Український комплект документації.
+
+| Розділ | Файл |
+|---|---|
+| Шлях Mado | [00-the-mado-way.md](./00-the-mado-way.md) |
+| Маршрутизація | [01-routing.md](./01-routing.md) |
+| Структура проєкту | [02-project-layout.md](./02-project-layout.md) |
+| Static 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 zero-history тест | [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) |

package/llms.txt

@@ -0,0 +1,155 @@
+# Mado
+
+> Small native-web SPA framework on the platform (Web Components + signals + tagged-template `html`).  
+> No build step (only `tsc`), no runtime dependencies, readable in an evening.
+
+Mado is a narrowly-focused frontend framework that deliberately avoids React patterns (no JSX, no hooks, no VDOM, no Vite). Target audience: backend developers and senior frontend engineers who are tired of the infrastructure complexity of React/Next.
+
+## Key things an AI assistant needs to know
+
+- **This is NOT React, NOT Lit, NOT Solid.** When generating code for Mado, **do not use JSX, `useState`, `useEffect`, classes, decorators, `requestUpdate`**. That will be an error.
+- **All templates are tagged template `html\`...\``** (not JSX). Allowed bindings inside: `${value}`, `attr=${v}`, `@evt=${fn}`, `.prop=${v}`, `?attr=${flag}`.
+- **Reactivity via signals.** `signal()`, `computed()`, `effect()`. A signal is a getter function (`count()`), not an object field (`count.value`).
+- **Components are Web Components.** Registered via `component('x-name', setupFn, options)`. Names must include a hyphen (`x-foo`, `my-button`).
+- **Cleanup via `ctx.onDispose(fn)`** in setup, not via return from effect.
+
+## Critical template rules
+
+1. **A reactive value in a template = getter function.**
+   ```ts
+   // ❌ NOT REACTIVE: read once at render time
+   html`<div>${count() * 2}</div>`
+   // ✅ REACTIVE: subscription
+   html`<div>${() => count() * 2}</div>`
+   ```
+   The signal itself can also be inserted directly — Mado will recognise it as a function:
+   ```ts
+   html`<div>${count}</div>`  // ✅ ok, count is a function
+   ```
+
+2. **DOM properties vs HTML attributes:**
+   - `attr=${v}` → setAttribute (strings/numbers only);
+   - `.prop=${v}` → DOM property (objects, arrays, numbers without serialisation);
+   - `?attr=${flag}` → boolean attribute (toggle attribute);
+   - `@evt=${fn}` → addEventListener.
+
+   ```ts
+   html`<input ?disabled=${isLoading} .value=${user.name} @input=${onInput}>`
+   ```
+
+3. **Lists — must use `each(items, keyFn, renderFn)`**, not `.map()` without a key:
+   ```ts
+   import { each } from "@madojs/mado";
+   html`<ul>${() => each(users(), u => u.id, u => html`<li>${u.name}</li>`)}</ul>`
+   ```
+
+## Canonical imports
+
+```ts
+// Everything you normally need — from one place:
+import {
+  signal, computed, effect, batch,
+  html, render,
+  each,
+  component,
+  css, cssVars,
+  routes, router, navigate, queryParam, prefetchPath,
+  page, nested,
+  resource, mutation, invalidate, jsonFetcher,
+  useForm,
+  createContext, provide, inject,
+  persisted,
+  lazy,
+} from "@madojs/mado";
+```
+
+## Canonical "Hello world"
+
+```ts
+// src/main.ts
+import { html, render } from "@madojs/mado";
+import routesApi from "./routes.js";
+render(html`${routesApi.view}`, document.getElementById("app")!);
+
+// src/routes.ts
+import { routes } from "@madojs/mado";
+export default routes({
+  "/": () => import("./pages/home.js"),
+  "*": () => import("./pages/not-found.js"),
+});
+
+// src/pages/home.ts
+import { page, component, html, css, signal } from "@madojs/mado";
+
+component("x-counter", () => {
+  const count = signal(0);
+  return () => html`
+    <button @click=${() => count.update(n => n + 1)}>${count}</button>
+  `;
+}, { styles: css`button { padding: .5rem 1rem; }` });
+
+export default page({
+  title: "Home",
+  view: () => html`<x-counter></x-counter>`,
+});
+```
+
+## Canonical CRUD pattern (for backend developers)
+
+```ts
+import { page, html, resource, mutation, each, useForm, navigate } from "@madojs/mado";
+import { api } from "../lib/api.js";
+
+const users = resource(() => "/api/users", () => api.list(), { staleTime: 30_000 });
+const create = mutation((u) => api.create(u), { invalidates: ["/api/users*"] });
+
+export default page({
+  view: () => {
+    const f = useForm({ name: { required: true } });
+    return html`
+      <form @submit=${f.onSubmit(async v => { await create.run(v); navigate("/"); })}>
+        <input name="name" @input=${f.onInput}>
+        <button ?disabled=${() => !f.isValid()}>Create</button>
+      </form>
+      ${() => each(users.data() ?? [], u => u.id, u => html`<li>${u.name}</li>`)}
+    `;
+  },
+});
+```
+
+## Documentation
+
+- README: https://github.com/madojs/mado#readme — full description + cookbook
+- docs/en/00-the-mado-way.md — philosophy and applicability boundaries
+- docs/en/01-routing.md — detailed router documentation
+- docs/en/02-project-layout.md — recommended project structure
+- docs/en/03-static-bake.md — SEO without SSR (static build / edge prerender)
+- docs/en/04-ide-setup.md — VS Code / WebStorm configuration
+- docs/en/05-why-mado.md — honest comparison with Lit / Solid / Svelte / htmx / Alpine / React
+- docs/en/06-for-backenders.md — mental model in 10 minutes for Go/Rust/.NET/Java developers
+- docs/en/07-llm-pitfalls.md — common mistakes when generating Mado code
+- examples/basic/ — minimal API tour
+- examples/tickets/ — LLM zero-history CRUD validation
+- examples/showcase/ — flagship CRM pressure app (auth, nested routes, forms, mutations)
+- examples/cloudflare/ — Edge prerender PoC on Cloudflare Workers
+
+## What Mado does NOT do (intentionally)
+
+- ❌ JSX → tagged templates instead
+- ❌ Virtual DOM → fine-grained signal updates
+- ❌ SSR with hydration → `bake` (static build) or edge-prerender for SEO
+- ❌ Hooks and rules of hooks → signals
+- ❌ Mandatory Webpack/Vite → only `tsc`
+- ❌ React-Router / TanStack → built-in 500-line `routes()`
+- ❌ React-Query / SWR → built-in `resource()`
+- ❌ Formik / RHF → built-in `useForm()` (HTML5 validation)
+- ❌ Redux / Zustand → `signal()` + `createContext`
+- ❌ Decorators → plain functions
+
+## Version
+
+`0.5.0` — early, API may change before 1.0. Semver is not guaranteed on minor versions before 1.0.
+
+## License
+
+MIT.