@madojs/mado 0.5.0 → 0.6.0

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

@@ -1,40 +1,107 @@
 # Shadow DOM vs Light DOM
 
-Mado використовує Shadow DOM за замовчуванням, але це не означає, що його треба
-вмикати всюди.
+Mado використовує Shadow DOM за замовчуванням. Це хороший default для
+самодостатніх widgets, але не для кожного компонента в app.
 
-## Shadow DOM добре підходить для
+## Практичне правило
+
+У Mado layout — це теж component. Якщо файл описує видиму reusable частину
+UI-дерева — app shell, sidebar, modal, table, page section — за замовчуванням
+робіть Web Component через `component()`.
 
-- leaf-компонентів;
-- isolated widgets;
-- badges, cards, modals, buttons;
-- компонентів, які мають не ламатися від зовнішнього CSS.
+Звичайні функції залишайте для маленьких inline helpers:
 
 ```ts
-component("x-badge", () => () => html`<span><slot></slot></span>`, {
-  styles: css`:host { display: inline-block; }`,
-});
+const money = (value: number) => html`<span>${formatMoney(value)}</span>`;
 ```
 
-## Light DOM краще для
+Не варто робити 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 shell;
-- admin layouts;
-- route-level pages;
-- компонентів, які мають користуватися глобальними utility classes;
-- великих CRUD surfaces, де CSS має бути простим і передбачуваним.
+- 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
 
 ```ts
-component("x-app-layout", () => () => html`<main><slot></slot></main>`, {
-  shadow: false,
-  styles: css`x-app-layout main { display: grid; }`,
-});
+import "./components/app-layout.js";
+
+render(html`<x-app-layout>${router.view}</x-app-layout>`, app);
 ```
 
-## Практичне правило
+Import реєструє custom element через `customElements.define()`. Template створює
+`<x-app-layout>` element. Далі browser сам з'єднує tag з component class. Це не
+React-style component value, який передається як function.
 
-Якщо компонент — самостійний reusable visual, бери Shadow DOM. Якщо це частина
-app layout або page composition, часто краще Light DOM.
+## Routing and links
 
-Посилання з `data-link` працюють і в Shadow DOM, бо router використовує
+`data-link` працює всередині Shadow DOM, бо router використовує
 `event.composedPath()`.
+
+```ts
+component("x-card-link", () => () => html`
+  <a href="/app/accounts" data-link>Accounts</a>
+`);
+```
+
+Link може бути в Shadow DOM; navigation все одно залишається SPA.
+
+## Де імпортувати компоненти
+
+Custom elements стають global після registration, але registration все одно є
+явним JavaScript import.
+
+```ts
+// main.ts: global app frame
+import "./components/app-shell.js";
+
+// pages/tickets.ts: component, яким володіє ця page
+import "../components/ticket-list.js";
+```
+
+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 навмисно:
+
+- `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.
+
+Якщо page раптом виглядає unstyled, перевірте, чи не використовує вона global
+classes всередині Shadow DOM component. Зазвичай проблема саме в цьому.

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

@@ -0,0 +1,56 @@
+# Архітектура застосунку
+
+Production-застосунок на Mado має бути простим: один manifest маршрутів, один
+shell, один API-клієнт, один auth-модуль і сторінки, які імпортують власні
+компоненти.
+
+```txt
+src/
+├── main.ts
+├── routes.ts
+├── layouts/
+├── pages/
+├── components/
+├── lib/
+└── styles/
+```
+
+`lib/` — бізнес-логіка, `layouts/` — обгортки груп маршрутів, `components/` —
+повторні UI-теги, `pages/` — один файл на сторінку.
+
+```ts
+import { html, render } from "@madojs/mado";
+import "./styles/global.js";
+import routesApi from "./routes.js";
+
+render(html`${routesApi.view}`, document.getElementById("app")!);
+```
+
+Feature-компоненти імпортує сторінка, яка їх рендерить.
+
+```ts
+import { layout, routes } from "@madojs/mado";
+import { requireAuth } from "./lib/auth.js";
+
+export const manifest = {
+  "/": () => import("./pages/home.js"),
+  "/admin": layout({
+    layout: () => import("./layouts/app.js"),
+    guard: requireAuth,
+    routes: { "/": () => import("./pages/admin/dashboard.js") },
+  }),
+  "*": () => import("./pages/not-found.js"),
+};
+
+export default routes(manifest);
+```
+
+`manifest` потрібен для `mado bake`. Для читання використовуй `resource()`, для
+запису `mutation(..., { invalidates })`, для форм `useForm()`.
+
+```bash
+mado dev
+mado release
+```
+
+Деплоїться `out/`, а не `dist/`.

package/docs/uk/11-layouts.md

@@ -0,0 +1,34 @@
+# Layouts
+
+Рекомендований спосіб layout у Mado — вкладена група маршрутів у `routes.ts`.
+
+```ts
+import { layout, routes } from "@madojs/mado";
+import { requireAuth } from "./lib/auth.js";
+
+export const manifest = {
+  "/": () => import("./pages/home.js"),
+  "/login": layout({
+    layout: () => import("./layouts/auth.js"),
+    routes: { "/": () => import("./pages/login.js") },
+  }),
+  "/admin": layout({
+    layout: () => import("./layouts/app.js"),
+    guard: requireAuth,
+    routes: { "/": () => import("./pages/admin/dashboard.js") },
+  }),
+};
+
+export default routes(manifest);
+```
+
+Layout — це `page({ view })`, яка рендерить `child`:
+
+```ts
+export default page({
+  view: ({ child }) => html`<x-app-shell>${child}</x-app-shell>`,
+});
+```
+
+Один shell на групу, не на кожну сторінку. Guard на групі захищає все
+піддерево.

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

@@ -0,0 +1,34 @@
+# Auth та API
+
+Starter `admin` містить рекомендований рецепт:
+
+- `src/lib/api.ts` — один HTTP-клієнт, `ApiError`, refresh після 401;
+- `src/lib/auth.ts` — `accessToken`, `restoreSession()`, `login()`,
+  `logout()`, `requireAuth`.
+
+Модель:
+
+- access token у пам'яті через `signal`, не в `localStorage`;
+- HttpOnly refresh cookie відновлює сесію;
+- усі запити проходять через API-клієнт;
+- захищені routes використовують group guard.
+
+```ts
+export const requireAuth: Guard = async ({ path }) => {
+  if (accessToken()) return;
+  if (await restoreSession()) return;
+  return { redirect: `/login?return=${encodeURIComponent(path)}`, replace: true };
+};
+```
+
+Dev proxy:
+
+```jsonc
+{
+  "dev": {
+    "proxy": { "/api": "http://localhost:3000" }
+  }
+}
+```
+
+Якщо backend має іншу auth-схему, змінюй `api.ts`/`auth.ts`, а не сторінки.

package/docs/uk/13-deployment.md

@@ -0,0 +1,39 @@
+# Deployment
+
+Одна команда, один artifact:
+
+```bash
+mado release
+```
+
+Результат:
+
+```txt
+out/
+├── index.html
+├── assets/
+├── baked/
+├── _redirects
+└── _headers
+```
+
+`out/` можна деплоїти на nginx, Cloudflare Pages, Netlify, S3/CloudFront або
+GitHub Pages.
+
+```bash
+mado release
+mado preview
+```
+
+`mado preview` показує `out/` як статичний хост: baked HTML має пріоритет,
+потім SPA fallback.
+
+Для VPS + nginx:
+
+```bash
+mado release
+rsync -avz --delete out/ user@server:/var/www/myapp/
+```
+
+Наданий `nginx.conf` налаштовує immutable cache для hash bundles, no-cache для
+HTML та fallback для deep links.

package/docs/uk/14-testing.md

@@ -0,0 +1,34 @@
+# Тестування
+
+Mado — це TypeScript і browser APIs. У репозиторії фреймворка тести йдуть через
+Node test runner та `linkedom`.
+
+```bash
+npm run typecheck
+npm run build
+npm test
+```
+
+DOM-тест:
+
+```js
+import test from "node:test";
+import assert from "node:assert/strict";
+
+const { parseHTML } = await import("linkedom");
+const { window } = parseHTML("<!doctype html><html><body></body></html>");
+globalThis.window = window;
+globalThis.document = window.document;
+
+const { html, render } = await import("../dist/src/html.js");
+
+test("renders", () => {
+  const root = document.createElement("div");
+  render(html`<p>${"hello"}</p>`, root);
+  assert.equal(root.querySelector("p").textContent, "hello");
+});
+```
+
+Покривай signals/computed/effect, HTML bindings, guards/redirects, scroll/focus,
+error boundaries, forms, resources/mutations і CLI-команди `mado release`,
+`mado bake`, `mado preview`.

package/docs/uk/15-error-handling.md

@@ -0,0 +1,32 @@
+# Обробка помилок
+
+Обробляй помилки там, де користувач може відновитися: маршрути, дані, дії
+користувача.
+
+```ts
+export default routes(manifest, {
+  errorPage: (err) => html`
+    <main>
+      <h1>Щось пішло не так</h1>
+      <pre>${err.message}</pre>
+      <a data-link href="/">На головну</a>
+    </main>
+  `,
+});
+```
+
+`page({ errorView })` має пріоритет над глобальною boundary.
+
+```ts
+const users = resource(() => "/api/users", jsonFetcher<User[]>());
+
+html`
+  ${() => users.error()
+    ? html`<p role="alert">${users.error()!.message}</p>
+         <button @click=${users.refresh}>Повторити</button>`
+    : null}
+`;
+```
+
+Валідація належить `useForm()`, помилки запису — поруч із submit-кнопкою.
+Зовнішні browser subscriptions очищай через `ctx.onDispose()`.

package/docs/uk/16-bake-cookbook.md

@@ -0,0 +1,36 @@
+# Bake cookbook
+
+`mado bake` рендерить вибрані маршрути у статичний HTML. Це для SEO та швидкого
+першого рендеру, не SSR з hydration.
+
+```ts
+export default page({
+  head: () => ({ title: "Products", description: "Catalog" }),
+  view: ({ data }) => html`
+    <main>
+      <h1>Products</h1>
+      ${data.products.map((p) => html`<article><h2>${p.name}</h2></article>`)}
+    </main>
+  `,
+  bake: {
+    paths: () => [{}],
+    data: async () => ({ products: await api.products() }),
+    revalidate: 3600,
+  },
+});
+```
+
+У baked views краще використовувати звичайні масиви (`items.map(...)`).
+Runtime-директиви на кшталт `each()` потрібні браузеру.
+
+```ts
+export const manifest = {
+  "/": () => import("./pages/home.js"),
+  "/blog/:slug": () => import("./pages/blog-post.js"),
+};
+export default routes(manifest);
+```
+
+`mado release` створює deploy artifact у `out/`. Якщо bake повідомляє про
+unsupported value, винеси runtime-only частину в клієнт або заміни її на
+серіалізований HTML.

package/docs/uk/README.md

@@ -14,3 +14,10 @@
 | Типові помилки 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) |
+| Архітектура застосунку | [10-app-architecture.md](./10-app-architecture.md) |
+| Layouts | [11-layouts.md](./11-layouts.md) |
+| Auth та 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) |

package/llms.txt

@@ -11,6 +11,7 @@ Mado is a narrowly-focused frontend framework that deliberately avoids React pat
 - **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`).
+- **Component files register tags as side effects.** The browser does not auto-import files by tag name. If `<x-card>` works, some imported module already ran `customElements.define("x-card", ...)`.
 - **Cleanup via `ctx.onDispose(fn)`** in setup, not via return from effect.
 
 ## Critical template rules
@@ -94,6 +95,20 @@ export default page({
 });
 ```
 
+## Component registration imports
+
+```ts
+// main.ts: global shell/provider components only
+import "./components/app-shell.js";
+
+// pages/tickets.ts: feature/page-owned components
+import "../components/ticket-list.js";
+```
+
+Do not bulk-import every component in `main.ts` "just in case". Import the
+registration near the route/page that owns the tag. This preserves lazy loading
+and makes the code readable to humans and LLMs.
+
 ## Canonical CRUD pattern (for backend developers)
 
 ```ts
@@ -128,6 +143,13 @@ export default page({
 - 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
+- docs/en/10-app-architecture.md — canonical app file layout, routes, auth/API and release shape
+- docs/en/11-layouts.md — blessed layout recipe
+- docs/en/12-auth-and-api.md — blessed auth/API client recipe
+- docs/en/13-deployment.md — deployment recipes and cache rules
+- docs/en/14-testing.md — testing strategy and commands
+- docs/en/15-error-handling.md — route/data/action error boundaries
+- docs/en/16-bake-cookbook.md — static bake recipes and failure modes
 - examples/basic/ — minimal API tour
 - examples/tickets/ — LLM zero-history CRUD validation
 - examples/showcase/ — flagship CRM pressure app (auth, nested routes, forms, mutations)
@@ -148,7 +170,8 @@ export default page({
 
 ## Version
 
-`0.5.0` — early, API may change before 1.0. Semver is not guaranteed on minor versions before 1.0.
+`0.6.0` — pre-1.0 product-surface release. API may still change before 1.0.
+Semver is not guaranteed on minor versions before 1.0.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@madojs/mado",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Mado — a small native-web SPA framework with Web Components, signals, tagged-template html, router, resources, and forms. TypeScript-only build, zero runtime dependencies.",
   "type": "module",
   "license": "MIT",
@@ -48,7 +48,9 @@
     "README.md",
     "LICENSE",
     "CHANGELOG.md",
+    "MADO_V1_PLAN.md",
     "ROADMAP.md",
+    "TODO.md",
     "AGENTS.md",
     "llms.txt",
     "docs/**/*.md"