@madojs/mado 0.11.1 → 0.13.0

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

@@ -1,73 +0,0 @@
-# Структура проєкту
-
-Кожен 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/
-```
-
-## 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",
-  },
-});
-```
-
-Starter uses Vite's Lightning CSS transformer. Mado does not own prefixing, CSS
-lowering or minification.

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

@@ -1,48 +0,0 @@
-# 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.
-
-Це не hydration. Клієнтський Mado-застосунок все одно стартує нормально і
-перерендерює сторінку після завантаження.

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

@@ -1,26 +0,0 @@
-# Налаштування 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

@@ -1,34 +0,0 @@
-# Чому 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

@@ -1,55 +0,0 @@
-# Mado для бекендерів
-
-Якщо ти пишеш Go, Rust, .NET, Java, Python або Node backend, Mado можна уявляти
-як маленький HTTP-сервер у браузері.
-
-| Backend mental model | Mado |
-|---|---|
-| router | `routes()` |
-| handler | `page().view` |
-| middleware/layout | `layout()` route group |
-| 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*"],
-});
-```
-
-Ключі `resource()` — це identity кешу. Додавайте endpoint, query params і форму
-даних у ключ: два живі `resource()` з однаковим ключем ділять cache та
-in-flight request. Якщо той самий ключ використано з іншим fetcher, Mado
-попереджає, бо зазвичай це означає, що ключ кешу занадто широкий.
-
-## Форми
-
-```ts
-const form = useForm({
-  email: { required: true, type: "email" },
-});
-```
-
-Mado використовує schema-based validation, близьку до HTML constraints, а не
-окрему validation ecosystem.
-
-## Auth
-
-Auth зазвичай живе в `modules/auth` як signal/context. Protected area зручно
-робити через `layout()` group, який перевіряє session і показує dashboard або
-redirect/login.
-
-## Правило
-
-Не тягни backend-архітектуру в frontend дослівно. Тримай UI state локальним,
-data fetching через `resource()`, mutation через `mutation()`, а shared services
-через context.

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

@@ -1,145 +0,0 @@
-# Типові помилки 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-*`.
-
-## `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()`               |
-| `setInterval` в page view   | `onDispose(() => clearInterval(id))` |
-| читання сигналу в async init | `untracked(() => cursor())`  |

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

@@ -1,34 +0,0 @@
-# LLM Zero-History Test
-
-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` or the English version
-- files from the external `madojs-examples` workspace only when the agent asks
-  for a larger app pattern
-
-## Task
-
-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()`.
-
-## Failure Checklist
-
-- 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.
-
-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,58 +0,0 @@
-# Shadow DOM vs Light DOM
-
-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
-
-Use route layouts for app zones:
-
-```ts
-export default page({
-  view: ({ child }) => html`<main class="app-main">${child}</main>`,
-});
-```
-
-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`.
-
-Use page files for screens:
-
-```ts
-export default page({
-  view: () => html`<section><h1>Users</h1></section>`,
-});
-```
-
-Page-level tables, forms, prose and simple states are styled by
-`src/shared/styles/content.css`.
-
-Use Shadow DOM components for leaf widgets:
-
-- buttons, badges, cards, metrics;
-- spinners, modals, toasts;
-- widgets that should own their CSS.
-
-```ts
-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); }
-  `,
-});
-```
-
-## Style Behavior
-
-- `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.
-
-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.

package/docs/uk/10-app-architecture.md

@@ -1,97 +0,0 @@
-# Архітектура застосунку
-
-Офіційний starter — канонічна production-форма Mado-застосунку. Це не
-framework всередині framework: лише files, imports, Mado primitives та ESLint
-boundaries.
-
-```txt
-src/
-├── main.ts
-├── app.routes.ts
-├── layouts/
-│   ├── app-shell.layout.ts
-│   └── auth-shell.layout.ts
-├── shared/
-│   ├── http/
-│   ├── lib/
-│   ├── styles/
-│   └── ui/
-└── modules/
-    ├── auth/
-    │   ├── auth.routes.ts
-    │   ├── auth.public.ts
-    │   ├── auth.service.ts
-    │   ├── auth.connector.ts
-    │   ├── auth.guard.ts
-    │   ├── login.page.ts
-    │   └── _contracts/
-    └── billing/
-        ├── billing.routes.ts
-        ├── billing.public.ts
-        ├── billing.types.ts
-        ├── api/
-        ├── data/
-        ├── pages/
-        ├── components/
-        └── _contracts/
-```
-
-`src/app.routes.ts` is the app map. Modules export plain route maps; app routes
-decide which shell and guard wrap each zone.
-
-```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"),
-  "/login": layout({
-    layout: () => import("./layouts/auth-shell.layout"),
-    routes: authRoutes,
-  }),
-  "/billing": layout({
-    layout: () => import("./layouts/app-shell.layout"),
-    guard: requireAuth,
-    routes: billingRoutes,
-  }),
-  "*": () => import("./modules/home/not-found.page"),
-};
-
-export default routes(manifest);
-```
-
-Page-local signals, resources and forms live inside `view()`. Module-wide state
-lives in `*.service.ts`.
-
-## Styles
-
-| File | Role |
-| --- | --- |
-| `src/shared/styles/tokens.css` | design tokens as CSS custom properties |
-| `src/shared/styles/reset.css` | document/light DOM reset |
-| `src/shared/styles/shell.css` | app-zone layouts from `src/layouts/` |
-| `src/shared/styles/content.css` | page-level forms, tables, prose and states |
-
-Leaf components keep their own styles in ``css`...` `` inside `component()`
-options and depend on tokens, not global classes.
-
-`vite.config.ts` uses Vite's Lightning CSS transformer. Mado does not own
-prefixing, CSS lowering or minification.
-
-## CLI
-
-```bash
-mado new module billing
-mado new page billing/pages/invoices-list
-mado new connector billing/api/stripe
-mado new resource billing/data/invoices
-mado new service billing/cart
-mado new form billing/invoice
-mado new component billing/components/invoice-status-badge
-mado new guard billing/billing
-mado new layout app-shell
-```
-
-The generator writes files only and does not edit `app.routes.ts`.

package/docs/uk/11-layouts.md

@@ -1,47 +0,0 @@
-# Layouts
-
-The blessed layout recipe in Mado is a route group in `src/app.routes.ts`.
-Do not put a single global shell in `main.ts` when the app has multiple zones:
-public, auth, app, embed.
-
-```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);
-```
-
-A layout is a normal `page({ view })` that renders `child`:
-
-```ts
-export default page({
-  view: ({ child }) => html`
-    <div class="layout layout--app">
-      <main class="app-main">${child}</main>
-    </div>
-  `,
-});
-```
-
-Rules:
-
-- one shell per route group, not per page;
-- modules export plain route maps and do not call `layout()`;
-- guard on a group protects the whole subtree;
-- layout view stays stateless; page-local state lives in pages/components/resources.

package/docs/uk/12-auth-and-api.md

@@ -1,70 +0,0 @@
-# Auth and API
-
-The default starter is the blessed recipe. HTTP mechanics live in
-`src/shared/http/`, auth state lives in `src/modules/auth/`.
-
-```txt
-src/shared/http/
-  http-client.ts
-  http-error.ts
-  interceptors.ts
-
-src/modules/auth/
-  auth.connector.ts
-  auth.service.ts
-  auth.guard.ts
-  auth.routes.ts
-  auth.public.ts
-  _contracts/
-```
-
-Business module flow:
-
-```txt
-connector -> resource/mutation -> page
-```
-
-Pages do not import DTOs and do not call `fetch()` directly. Connectors do not
-import Mado reactivity or UI.
-
-## Auth Service
-
-```ts
-const _user = signal<User | null>(null);
-const _token = signal<string | null>(null);
-
-export const user = () => _user();
-export const isAuthed = computed(() => _user() !== null);
-```
-
-Expose only what other modules need through `auth.public.ts`.
-
-## Guards
-
-```ts
-export function requireAuth(): boolean | string {
-  if (isAuthed()) return true;
-  return "/login";
-}
-```
-
-Use in `src/app.routes.ts`:
-
-```ts
-"/billing": layout({
-  layout: () => import("./layouts/app-shell.layout"),
-  guard: requireAuth,
-  routes: billingRoutes,
-}),
-```
-
-## Dev Proxy
-
-```ts
-export default defineConfig({
-  plugins: [mado()],
-  server: {
-    proxy: { "/api": "http://localhost:3000" },
-  },
-});
-```