@madojs/mado 0.11.1 → 0.13.0

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

@@ -1,56 +0,0 @@
-# LLM zero-history test
-
-This document defines a practical validation test for Mado.
-
-The question is not "can an LLM generate frontend code?" It can. The question is:
-can a fresh LLM write idiomatic Mado without falling back to React-shaped code?
-
-## Allowed context
-
-For the first pass, give the agent only:
-
-- `AGENTS.md`
-- `README.md`
-- `docs/en/07-llm-pitfalls.md`
-- files from the external `madojs-examples` workspace only when the agent asks
-  for a larger app pattern
-
-The agent may search targeted APIs in `src/` when blocked, but should not load
-the whole framework into context.
-
-## Task
-
-Build a small ticket-admin SPA for a solo/backend developer.
-
-Required behavior:
-
-- routes: `/`, `/tickets`, `/tickets/new`, `/tickets/:id`, `*`;
-- in-memory mock API with realistic async delays;
-- list page with `resource()`, `queryParam()` search/status filters, `computed()`,
-  and keyed `each()` rows;
-- create and edit flows with `useForm()` + `mutation()` + `invalidates`;
-- local UI state with `signal()`;
-- slotted shell, metric, and badge components for a more realistic admin UI;
-- smoke test importing the built example.
-
-## Failure checklist
-
-Look for these after implementation:
-
-- JSX, `useState`, `useEffect`, `ref`, `$state`, or class-style components;
-- `${signal()}` or `${signal() + 1}` where a reactive child thunk is required;
-- `disabled=${...}` instead of `?disabled=${...}`;
-- dynamic lists rendered with unkeyed array mapping instead of `each()`;
-- browser ESM imports without `.js`;
-- `resource()` created outside component setup;
-- new runtime dependencies or new public framework APIs.
-
-## Result notes
-
-The historical tickets implementation lives in the external examples workspace.
-The core repository no longer ships that artifact or a dedicated smoke command;
-use this document as a manual evaluation script when updating LLM guidance.
-
-The main documentation pressure point remains lifecycle: examples should not
-make it look acceptable to create long-lived `resource()` instances accidentally
-at module scope or in route code that never cleans up.

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

@@ -1,174 +0,0 @@
-# Shadow DOM vs Light DOM
-
-Mado components use Shadow DOM by default. This is a good default for
-self-contained widgets, but it is not the right default for every component in
-an application.
-
-## Rule of Thumb
-
-Use Mado route layouts (`page({ view: ({ child }) => ... })`) for app zones:
-auth shells, admin shells, public shells and embedded shells. These live in
-`src/layouts/` and are composed from `src/app.routes.ts`.
-
-Use Web Components registered with `component()` for reusable UI elements and
-widgets. Use plain functions only for small inline template helpers:
-
-```ts
-const money = (value: number) => html`<span>${formatMoney(value)}</span>`;
-```
-
-Do not hide app shells inside `main.ts` or generic helper functions. The app
-map should show which layout wraps which route group.
-
-Use **Shadow DOM** for leaf widgets:
-
-- buttons, badges, cards, metrics;
-- modals, toasts, small visual components;
-- embed widgets that should not inherit app CSS accidentally;
-- components whose styling should be owned by the component itself.
-
-Use **Light DOM** for app structure that wants to share global CSS:
-
-- route pages and route layouts;
-- admin screens with dense table/form layouts;
-- data-heavy screens with tables and forms;
-- places where children should simply remain normal document DOM.
-
-Route layouts receive `child` from Mado, so they do not need `<slot>`.
-
-## The Footgun
-
-Global CSS does not cross a Shadow DOM boundary.
-
-```ts
-// global.ts
-export const globalStyles = css`
-  .page-head { display: flex; justify-content: space-between; }
-  .metric-grid { display: grid; grid-template-columns: repeat(4, 1fr); }
-`;
-
-// ❌ .page-head and .metric-grid will not apply inside x-dashboard shadowRoot
-component("x-dashboard", () => () => html`
-  <header class="page-head">...</header>
-  <div class="metric-grid">...</div>
-`);
-```
-
-Fix it by making the route/page component Light DOM:
-
-```ts
-component("x-dashboard", () => () => html`
-  <header class="page-head">...</header>
-  <div class="metric-grid">...</div>
-`, {
-  shadow: false,
-  styles: css`
-    x-dashboard { display: block; }
-    x-dashboard .panel { padding: 1rem; }
-  `,
-});
-```
-
-Now global utilities and local scoped styles both work.
-
-## How Styles Behave
-
-- `styles: css\`\`` in Shadow DOM is adopted into the component shadowRoot.
-- `styles: css\`\`` with `shadow: false` is scoped to the tag name and adopted
-  globally.
-- CSS custom properties (`--accent`, `--bg`, etc.) cross Shadow DOM boundaries.
-- Class selectors like `.btn`, `.form-grid`, `.page-head` do **not** cross
-  Shadow DOM boundaries.
-- Slotted children keep their own document styles; the shadow component can only
-  target them through `::slotted(...)`.
-- `<slot>` projects children only in Shadow DOM. In a `shadow: false` component
-  it is just a normal `<slot>` element and will not move children into that
-  place in your layout.
-
-## Recommended App Shape
-
-```ts
-// app zone: route layout, styled by shared/styles/shell.css
-export default page({
-  view: ({ child }) => html`<main class="app-main">${child}</main>`,
-});
-
-// route page: light DOM, styled by shared/styles/content.css
-export default page({
-  view: () => html`<section><h1>Users</h1></section>`,
-});
-
-// leaf widgets: Shadow DOM default
-component("x-status-badge", setup);
-component("x-stat-card", setup);
-component("x-toast-stack", setup);
-```
-
-This gives admin screens predictable CSS while preserving encapsulation for
-reusable leaf widgets.
-
-The import model is deliberately browser-native:
-
-```ts
-import "./components/app-layout.js";
-
-render(html`<x-app-layout>${router.view}</x-app-layout>`, app);
-```
-
-The import registers the custom element with `customElements.define()`. The
-template creates an `<x-app-layout>` element. The browser connects the two.
-There is no React-style component value being passed around.
-
-If you do need a reusable slot-based frame, keep it as a Shadow DOM component
-and put frame styles in that component.
-
-## Routing and Links
-
-`data-link` works inside Shadow DOM. The router uses `event.composedPath()`, so
-click interception and hover-prefetch can see links from open shadow roots.
-
-```ts
-component("x-card-link", () => () => html`
-  <a href="/app/accounts" data-link>Accounts</a>
-`);
-```
-
-The link can be in Shadow DOM; navigation still stays SPA.
-
-## Where To Import Components
-
-Custom elements are global after registration, but registration is still an
-explicit JavaScript import.
-
-```ts
-// main.ts: global app frame
-import "./components/app-shell.js";
-
-// pages/tickets.ts: page-owned feature component
-import "../components/ticket-list.js";
-```
-
-The browser does **not** download `ticket-list.js` just because it sees
-`<ticket-list>`. The file must be imported somewhere first. Once imported, it
-calls `customElements.define(...)`, and the tag becomes known in the current
-document.
-
-Do not bulk-import every component in `main.ts` "just in case". It works for
-tiny demos, but it hides ownership and defeats lazy route loading. Prefer:
-
-- global app shell/providers in `main.ts`;
-- page-owned components in that page file;
-- feature-owned shared components in the feature entry page;
-- truly global leaf components in `main.ts` only when they are used everywhere.
-
-## Starter Lesson
-
-The default starter uses this split deliberately:
-
-- route layouts are `page()` files under `src/layouts/`;
-- `shell.css` owns app-zone chrome;
-- `content.css` owns page-level tables/forms/prose;
-- leaf components such as `x-button`, `x-spinner` and badges keep Shadow DOM.
-
-If a page suddenly looks unstyled, check whether it uses global classes inside a
-Shadow DOM component. That is usually the issue.

package/docs/en/11-layouts.md

@@ -1,113 +0,0 @@
-# Layouts
-
-> **One blessed path.** Layouts in Mado are route groups with a shared
-> shell. There is exactly one canonical place to declare a layout — your
-> `app.routes.ts` manifest. Putting layout code anywhere else (in `main.ts`, in a
-> page view, in a global custom-element wrapper) is a bug pattern: the LLM and
-> the human both produce visually broken UI when they guess differently.
-
-## The canonical recipe
-
-```ts
-// src/app.routes.ts
-import { layout, routes } from "@madojs/mado";
-import { requireAuth } from "./modules/auth/auth.public.js";
-import { authRoutes } from "./modules/auth/auth.routes.js";
-import { billingRoutes } from "./modules/billing/billing.routes.js";
-
-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 just a `page({ view })` that renders `${ctx.child}` somewhere:
-
-```ts
-// src/layouts/app.ts
-import { html, page } from "@madojs/mado";
-import "../components/app-shell.js";   // <x-app-shell> (sidebar + topbar + slot)
-
-export default page({
-  view: ({ child }) => html`
-    <x-app-shell>${child}</x-app-shell>
-  `,
-});
-```
-
-That is the whole API.
-
-- **Order of layouts** matters: outer groups wrap inner groups. The order in
-  the manifest is exactly the order of rendering.
-- **One shell per group**, not one shell per page. If you want a different
-  shell for a subtree, create a new group with its own `layout`.
-- **Layouts can be lazy** (`() => import(...)`). They are loaded together
-  with the page.
-
-## Why "one blessed path"
-
-Without this convention, every page accumulates `<x-app-shell>${...}</x-app-shell>`
-boilerplate, the LLM eventually puts the shell wrapper into `main.ts` "to make
-it consistent", and the next refactor produces the classic
-*"navigation appears below the page content"* screenshot. The layout-group
-recipe makes the shell the **outer frame** structurally; there is no way to
-re-order it by accident.
-
-## Two acceptable alternatives (with caveats)
-
-These exist for completeness. Reach for them only if you cannot use layout
-groups.
-
-### a) A single shell with the router slot in `main.ts`
-
-```ts
-import { html, render } from "@madojs/mado";
-import "./components/app-shell.js";
-import router from "./routes.js";
-
-render(html`<x-app-shell>${router.view}</x-app-shell>`, app);
-```
-
-Caveat: every route now lives inside one shell. You cannot have a centered
-login page or a marketing landing page without the admin chrome around it.
-Use this only for single-shell apps.
-
-### b) Per-page wrapping inside `view`
-
-```ts
-export default page({
-  view: () => html`
-    <x-app-shell>
-      <h1>Orders</h1>
-      ...
-    </x-app-shell>
-  `,
-});
-```
-
-Caveat: repetition. Every new page must remember the wrapper. The first time
-someone forgets it, the layout disappears and the LLM "fixes" it in the wrong
-place. **Do not start with this.**
-
-## Where to find more
-
-- `src/page.ts` defines `layout()`, `page()`, `Guard` and `LayoutRoutes`.
-- `src/router/manifest.ts` flattens the layout manifest and applies guards
-  outer → inner before the page renders.
-- The default starter (`mado init my-app`) ships with public, auth and
-  authenticated app zones and is the reference implementation.
-
-If you ever feel tempted to invent a fourth pattern, write it down in your
-project `docs/` first and discuss it with the team. The cost of inconsistency
-in this exact spot is higher than the cost of a slightly awkward layout.

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

@@ -1,124 +0,0 @@
-# Auth and API
-
-The default starter is the blessed recipe. It keeps HTTP mechanics in
-`src/shared/http/` and auth state in `src/modules/auth/`.
-
-## Shape
-
-```txt
-src/shared/http/
-  http-client.ts       # one fetch wrapper + query/body/error handling
-  http-error.ts        # one error shape
-  interceptors.ts      # request/response hooks
-
-src/modules/auth/
-  auth.connector.ts    # /api/auth wire contract, DTO -> domain
-  auth.service.ts      # token/user signals + login/logout/init
-  auth.guard.ts        # requireAuth(), requirePermission()
-  auth.routes.ts       # login route map
-  auth.public.ts       # only public auth surface
-  _contracts/          # backend DTOs, private to connector
-```
-
-Every business module follows the same flow:
-
-```txt
-connector -> resource/mutation -> page
-```
-
-Pages do not import DTOs. Pages do not call `fetch()` directly. Connectors do
-not import Mado reactivity or UI.
-
-## HTTP Client
-
-Use one small HTTP client for the app. It owns:
-
-- base URL handling;
-- JSON request/response defaults;
-- query string serialization;
-- `HttpError`;
-- request/response interceptors.
-
-Module connectors build on it:
-
-```ts
-import { httpClient } from "../../shared/http/http-client";
-import type { User } from "./auth.types";
-import type { LoginResponseDTO } from "./_contracts/auth-api.types";
-
-const toUser = (dto: LoginResponseDTO["user"]): User => ({
-  id: dto.id,
-  email: dto.email,
-  roles: dto.roles,
-  permissions: dto.permissions,
-});
-
-export const authApi = {
-  me: async () => toUser(await httpClient.get<LoginResponseDTO["user"]>("/api/auth/me")),
-};
-```
-
-## Auth Service
-
-Auth state is an ES module singleton:
-
-```ts
-const _user = signal<User | null>(null);
-const _token = signal<string | null>(null);
-
-export const user = () => _user();
-export const isAuthed = computed(() => _user() !== null);
-
-export async function login(creds: Credentials): Promise<void> {
-  const res = await authApi.login(creds);
-  _token.set(res.token);
-  _user.set(res.user);
-}
-```
-
-Expose only what other modules need through `auth.public.ts`.
-
-## Guards
-
-Guards are plain functions:
-
-```ts
-export function requireAuth(): boolean | string {
-  if (isAuthed()) return true;
-  return "/login";
-}
-```
-
-Use them in `src/app.routes.ts`:
-
-```ts
-"/billing": layout({
-  layout: () => import("./layouts/app-shell.layout"),
-  guard: requireAuth,
-  routes: billingRoutes,
-}),
-```
-
-## Dev Proxy
-
-Configure proxying in `vite.config.ts`:
-
-```ts
-import { defineConfig } from "vite";
-import { mado } from "@madojs/mado/vite";
-
-export default defineConfig({
-  plugins: [mado()],
-  server: {
-    proxy: { "/api": "http://localhost:3000" },
-  },
-});
-```
-
-## Rule of Thumb
-
-- `shared/http` knows HTTP.
-- `*.connector.ts` knows one external system.
-- `*.resource.ts` knows cache keys and invalidation.
-- `*.page.ts` knows UI.
-- `*.public.ts` is the only cross-module surface.

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

@@ -1,100 +0,0 @@
-# Bake cookbook
-
-`mado bake` renders selected routes into static HTML. It is for SEO and fast
-first paint, not for server-side hydration.
-
-## Minimal baked page
-
-```ts
-export default page({
-  head: () => ({ title: "Products", description: "Product 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,
-  },
-});
-```
-
-For baked pages, use plain arrays in `view()` when possible. Runtime-only
-directives such as keyed `each()` are for the browser.
-
-## 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()` is allowed only for trusted or already-sanitized HTML.
-
-## Route manifest
-
-`mado bake` needs the source manifest:
-
-```ts
-export const manifest = {
-  "/": () => import("./pages/home.js"),
-  "/blog/:slug": () => import("./pages/blog-post.js"),
-};
-
-export default routes(manifest);
-```
-
-## Output
-
-By default standalone `mado bake` writes baked pages directly into `out/`.
-`mado release` first lets Vite build the production shell and assets, then bake
-replaces route HTML in place and writes `out/sitemap.xml`:
-
-```bash
-mado release
-tree out
-```
-
-The deployable folder is `out/`, not `dist/`.
-
-Use `mado release --keep-bake-dir` only when you want an extra `out/baked/`
-inspection copy during debugging.
-
-## Client boot
-
-Baked HTML marks `#app` with `data-mado-baked`. This is not hydration: when the
-client app starts, `render()` replaces the baked DOM with live bindings. The
-first response contains SEO/first-paint HTML, then the SPA takes over normally.
-
-## Unsupported values
-
-Bake intentionally fails loudly instead of writing `[object Object]`. If a baked
-view throws an unsupported directive error:
-
-- replace `each()` with `items.map(...)` in baked markup;
-- keep interactive-only widgets behind client routes;
-- make sure every value can be serialized to static HTML.
-
-## Canonical links
-
-Pass `--base-url` so generated canonical links and sitemap entries point to
-production.
-
-```bash
-mado bake --base-url https://example.com
-mado release --base-url https://example.com
-```
-
-## When not to bake
-
-Do not bake pages whose content is user-specific, permission-dependent, or
-changes every few seconds. Use a normal SPA route with `resource()` instead.