npm - @madojs/mado - Versions diffs - 0.5.1 → 0.6.1 - Mend

@madojs/mado 0.5.1 → 0.6.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (107) hide show

package/AGENTS.md +26 -0
package/CHANGELOG.md +265 -0
package/MADO_V1_PLAN.md +179 -0
package/README.md +31 -13
package/ROADMAP.md +28 -7
package/TODO.md +72 -0
package/dist/src/forms.d.ts +37 -4
package/dist/src/forms.js +331 -57
package/dist/src/forms.js.map +1 -1
package/dist/src/html/bindings.d.ts +41 -0
package/dist/src/html/bindings.js +163 -6
package/dist/src/html/bindings.js.map +1 -1
package/dist/src/html.d.ts +2 -0
package/dist/src/html.js +1 -0
package/dist/src/html.js.map +1 -1
package/dist/src/index.d.ts +6 -6
package/dist/src/index.js +2 -2
package/dist/src/index.js.map +1 -1
package/dist/src/page.d.ts +56 -0
package/dist/src/page.js +17 -0
package/dist/src/page.js.map +1 -1
package/dist/src/resource.js +11 -0
package/dist/src/resource.js.map +1 -1
package/dist/src/router/manifest.d.ts +16 -1
package/dist/src/router/manifest.js +210 -40
package/dist/src/router/manifest.js.map +1 -1
package/dist/src/router/match.d.ts +7 -2
package/dist/src/router/match.js +14 -4
package/dist/src/router/match.js.map +1 -1
package/dist/src/router/navigation.d.ts +10 -0
package/dist/src/router/navigation.js +71 -3
package/dist/src/router/navigation.js.map +1 -1
package/dist/src/signal.d.ts +15 -1
package/dist/src/signal.js +112 -16
package/dist/src/signal.js.map +1 -1
package/docs/en/02-project-layout.md +99 -40
package/docs/en/10-app-architecture.md +141 -0
package/docs/en/11-layouts.md +115 -0
package/docs/en/12-auth-and-api.md +217 -0
package/docs/en/13-deployment.md +192 -0
package/docs/en/14-testing.md +82 -0
package/docs/en/15-error-handling.md +100 -0
package/docs/en/16-bake-cookbook.md +93 -0
package/docs/en/README.md +7 -0
package/docs/fr/10-app-architecture.md +61 -0
package/docs/fr/11-layouts.md +35 -0
package/docs/fr/12-auth-and-api.md +35 -0
package/docs/fr/13-deployment.md +39 -0
package/docs/fr/14-testing.md +41 -0
package/docs/fr/15-error-handling.md +50 -0
package/docs/fr/16-bake-cookbook.md +35 -0
package/docs/fr/README.md +7 -0
package/docs/ru/10-app-architecture.md +100 -0
package/docs/ru/11-layouts.md +47 -0
package/docs/ru/12-auth-and-api.md +53 -0
package/docs/ru/13-deployment.md +60 -0
package/docs/ru/14-testing.md +50 -0
package/docs/ru/15-error-handling.md +56 -0
package/docs/ru/16-bake-cookbook.md +55 -0
package/docs/ru/README.md +7 -0
package/docs/uk/10-app-architecture.md +56 -0
package/docs/uk/11-layouts.md +34 -0
package/docs/uk/12-auth-and-api.md +34 -0
package/docs/uk/13-deployment.md +39 -0
package/docs/uk/14-testing.md +34 -0
package/docs/uk/15-error-handling.md +32 -0
package/docs/uk/16-bake-cookbook.md +36 -0
package/docs/uk/README.md +7 -0
package/llms.txt +9 -1
package/package.json +3 -1
package/scripts/_config.mjs +224 -0
package/scripts/bake.mjs +266 -121
package/scripts/bundle.mjs +133 -67
package/scripts/cli.mjs +195 -27
package/scripts/preview.mjs +125 -21
package/server/serve.mjs +161 -10
package/starters/admin/README.md +63 -0
package/starters/admin/index.html +28 -0
package/starters/admin/mado.config.json +22 -0
package/starters/admin/package.json +24 -0
package/starters/admin/public/favicon.svg +4 -0
package/starters/admin/src/components/x-button.ts +55 -0
package/starters/admin/src/components/x-input.ts +74 -0
package/starters/admin/src/layouts/app.ts +101 -0
package/starters/admin/src/layouts/auth.ts +41 -0
package/starters/admin/src/lib/api.ts +133 -0
package/starters/admin/src/lib/auth.ts +83 -0
package/starters/admin/src/main.ts +15 -0
package/starters/admin/src/pages/admin/dashboard.ts +48 -0
package/starters/admin/src/pages/admin/order-detail.ts +80 -0
package/starters/admin/src/pages/admin/orders.ts +117 -0
package/starters/admin/src/pages/home.ts +34 -0
package/starters/admin/src/pages/login.ts +70 -0
package/starters/admin/src/pages/not-found.ts +12 -0
package/starters/admin/src/routes.ts +40 -0
package/starters/admin/src/styles/global.ts +86 -0
package/starters/admin/tsconfig.json +15 -0
package/starters/crud/index.html +12 -4
package/starters/crud/mado.config.json +20 -0
package/starters/crud/package.json +9 -3
package/starters/crud/src/pages/home.ts +16 -0
package/starters/crud/src/routes.ts +4 -2
package/starters/minimal/index.html +12 -4
package/starters/minimal/mado.config.json +20 -0
package/starters/minimal/package.json +9 -3
package/starters/minimal/src/pages/home.ts +17 -0
package/starters/minimal/src/routes.ts +4 -2

package/docs/ru/14-testing.md ADDED Viewed

@@ -0,0 +1,50 @@
+# Тестирование
+Mado — это обычный TypeScript и browser APIs. В репозитории фреймворка тесты
+идут через Node test runner и `linkedom`.
+## Команды
+```bash
+npm run typecheck
+npm run build
+npm test
+```
+Перед merge/release прогоняй все три.
+## 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;
+globalThis.Node = window.Node;
+globalThis.HTMLElement = window.HTMLElement;
+const { html, render } = await import("../dist/src/html.js");
+test("renders a value", () => {
+  const root = document.createElement("div");
+  render(html`<p>${"hello"}</p>`, root);
+  assert.equal(root.querySelector("p").textContent, "hello");
+});
+```
+Сначала `npm run build`, потом импорт из `dist/`.
+## Что покрывать
+- signals/computed/effect: scheduling и cleanup;
+- template bindings: children, attrs, events, directives;
+- routes: guards, redirects, scroll/focus, error boundaries;
+- forms: sync/async validation, races, field arrays;
+- resources/mutations: cache keys, invalidation, lifecycle cleanup;
+- CLI: `mado release`, `mado bake`, `mado preview`.
+Для реального браузера оставляй маленькие smoke-тесты: открыть страницу,
+кликнуть ссылку или отправить форму, проверить видимый результат.

package/docs/ru/15-error-handling.md ADDED Viewed

@@ -0,0 +1,56 @@
+# Обработка ошибок
+В Mado есть три практичных слоя ошибок: загрузка роутов, загрузка данных и
+действия пользователя.
+## Route errors
+Глобальная граница:
+```ts
+export default routes(manifest, {
+  errorPage: (err) => html`
+    <main>
+      <h1>Что-то пошло не так</h1>
+      <pre>${err.message}</pre>
+      <a data-link href="/">На главную</a>
+    </main>
+  `,
+});
+```
+Локальная `page({ errorView })` имеет приоритет над `errorPage`.
+## Resource errors
+`resource()` дает `error()` и `loading()`. Показывай retry рядом с данными.
+```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}
+`;
+```
+## Forms and mutations
+Ошибки валидации — в `useForm()`. Ошибки записи — рядом с submit-кнопкой.
+```ts
+const form = useForm(
+  { email: { required: true, type: "email" } },
+  { validateAsync: (values) => api.validateUser(values) },
+);
+const save = mutation((values) => api.post("/users", values), {
+  invalidates: ["/api/users*"],
+});
+```
+## Cleanup
+Внешние browser subscriptions чисти через `ctx.onDispose()`. `resource()`,
+`effect()` и signals внутри component setup уже привязаны к lifecycle.

package/docs/ru/16-bake-cookbook.md ADDED Viewed

@@ -0,0 +1,55 @@
+# 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()` нужны браузеру.
+## Dynamic routes
+```ts
+export default page<{ slug: string }>({
+  head: ({ slug }, data) => ({ title: data.title, canonical: `/blog/${slug}` }),
+  view: ({ data }) => html`<article>${unsafeHTML(data.html)}</article>`,
+  bake: {
+    paths: async () => (await api.posts()).map((p) => ({ slug: p.slug })),
+    data: ({ slug }) => api.post(slug),
+  },
+});
+```
+`unsafeHTML()` используй только для доверенного или заранее очищенного HTML.
+## Manifest и output
+```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 значение:
+замени `each()` на `items.map(...)` или вынеси интерактивный кусок в клиент.

package/docs/ru/README.md CHANGED Viewed

@@ -12,3 +12,10 @@
 | LLM pitfalls | [07-llm-pitfalls.md](./07-llm-pitfalls.md) |
 | LLM zero-history test | [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 and 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/docs/uk/10-app-architecture.md ADDED Viewed

@@ -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 ADDED Viewed

@@ -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 ADDED Viewed

@@ -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 ADDED Viewed

@@ -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 ADDED Viewed

@@ -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 ADDED Viewed

@@ -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 ADDED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -143,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)
@@ -163,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 CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@madojs/mado",
-  "version": "0.5.1",
+  "version": "0.6.1",
   "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"