@madojs/mado 0.11.0 → 0.12.0

package/docs/en/17-shadow-dom-forms.md

@@ -1,192 +0,0 @@
-# Shadow DOM + Forms
-
-Using `useForm()` with custom input components that have Shadow DOM requires
-awareness of two browser-level behaviours:
-
-1. **Event retargeting** — events that bubble from Shadow DOM have their
-   `e.target` retargeted to the host element. `useForm().onInput` reads
-   `e.target.name` and `e.target.value`, but an `<x-input>` host element
-   doesn't natively have these properties.
-
-2. **Form association** — a `<button type="submit">` inside a Shadow Root is
-   NOT part of the form-owner algorithm for `<form>` in Light DOM. Clicking it
-   does not trigger form submit.
-
-Both are spec-level limitations, not Mado bugs. But the framework provides
-patterns that make them painless.
-
-## Pattern: Proxy Properties on Input Components
-
-When wrapping `<input>` in a Shadow DOM component, expose `name` and `value`
-as DOM properties on the host so that `useForm().onInput` works after event
-retargeting:
-
-```ts
-import { component, css, html } from "@madojs/mado";
-
-component("x-input", ({ host, attr }) => {
-  const name = attr("name", "");
-  const type = attr("type", "text");
-  const value = attr("value", "");
-
-  // Proxy properties for useForm() compatibility.
-  // After Shadow DOM retargets e.target from <input> to <x-input>,
-  // useForm reads e.target.name / e.target.value — these getters bridge the gap.
-  Object.defineProperty(host, "name", {
-    get: () => host.getAttribute("name") ?? "",
-    configurable: true,
-  });
-  Object.defineProperty(host, "value", {
-    get: () => host.shadowRoot?.querySelector("input")?.value ?? "",
-    set: (v: string) => {
-      const input = host.shadowRoot?.querySelector("input");
-      if (input) input.value = v;
-    },
-    configurable: true,
-  });
-
-  return () => html` <input name=${name} type=${type} .value=${value} /> `;
-});
-```
-
-The `input` event from the inner `<input>` has `composed: true` by default, so
-it will bubble through the shadow boundary. After retargeting, `e.target` is
-`<x-input>`, but now it has `.name` and `.value` getters → `useForm` works.
-
-## Pattern: Form Submit from Shadow DOM Buttons
-
-A `<button type="submit">` inside Shadow DOM cannot trigger `<form>` submit in
-Light DOM. Bridge it with `requestSubmit()`:
-
-```ts
-import { component, css, html } from "@madojs/mado";
-
-component("x-button", ({ host, attr }) => {
-  const disabled = attr("disabled");
-
-  const handleClick = () => {
-    const typeAttr = host.getAttribute("type");
-    if (typeAttr === "button" || typeAttr === "reset") return;
-    const form = host.closest("form");
-    if (form && !host.hasAttribute("disabled")) form.requestSubmit();
-  };
-
-  return () => html`
-    <button ?disabled=${() => disabled() !== ""} @click=${handleClick}>
-      <slot></slot>
-    </button>
-  `;
-});
-```
-
-`host.closest("form")` works because the host element itself lives in Light DOM
-(only its internals are shadowed). `requestSubmit()` triggers validation and the
-`submit` event exactly as if the user had clicked a native submit button inside
-the form.
-
-## Pattern: Reactive Attributes with ctx.attr()
-
-Since v0.7, `ctx.attr(name, defaultValue?)` returns a `Signal<string>` that
-updates automatically when the attribute changes on the host. No more
-`MutationObserver` boilerplate:
-
-```ts
-component("x-badge", ({ attr }) => {
-  const variant = attr("variant", "default"); // Signal<string>
-
-  return () =>
-    html`<span class=${() => `badge badge-${variant()}`}>
-      <slot></slot>
-    </span>`;
-});
-```
-
-The parent can use `?disabled=${() => !form.isValid()}` (boolean attribute) or
-`.variant=${"danger"}` — the component re-renders reactively either way.
-
-## Complete Form Example
-
-```ts
-import { page, html, useForm, navigate } from "@madojs/mado";
-import "../components/x-input.js";
-import "../components/x-button.js";
-
-export default page({
-  title: "Login",
-  view: () => {
-    const form = useForm({
-      email: { required: true, type: "email" },
-      password: { required: true, minLength: 6 },
-    });
-
-    const handleLogin = async (values) => {
-      await api("/auth/login", { method: "POST", json: values });
-      navigate("/admin");
-    };
-
-    return html`
-      <form @submit=${form.onSubmit(handleLogin)}>
-        <x-input
-          name="email"
-          type="email"
-          label="Email"
-          required
-          @input=${form.onInput}
-          @blur=${form.onBlur}
-        ></x-input>
-        ${() =>
-          form.errors().email
-            ? html`<small class="err">${form.errors().email}</small>`
-            : null}
-
-        <x-input
-          name="password"
-          type="password"
-          label="Password"
-          required
-          @input=${form.onInput}
-          @blur=${form.onBlur}
-        ></x-input>
-
-        <x-button type="submit" ?disabled=${() => !form.isValid()}>
-          Sign in
-        </x-button>
-      </form>
-    `;
-  },
-});
-```
-
-## When to Use Light DOM Instead
-
-If your input component is just a styled wrapper without encapsulation needs,
-`shadow: false` avoids both retargeting and form-association issues entirely:
-
-```ts
-component(
-  "x-field",
-  ({ attr }) => {
-    const label = attr("label", "");
-    return () => html`
-      <label>
-        <span>${label}</span>
-        <slot></slot>
-      </label>
-    `;
-  },
-  { shadow: false },
-);
-```
-
-With Light DOM, the native `<input>` is part of the document tree, events
-are not retargeted, and form submission works natively. The tradeoff: styles
-are not encapsulated (you must scope them yourself).
-
-## Summary
-
-| Concern                  | Shadow DOM Solution                     | Light DOM Alternative         |
-| ------------------------ | --------------------------------------- | ----------------------------- |
-| `useForm` + custom input | Proxy `name`/`value` on host            | Use native `<input>` in slot  |
-| Form submit              | `form.requestSubmit()` in click handler | Native button works           |
-| Reactive attributes      | `ctx.attr()` → auto-signal              | `ctx.attr()` works everywhere |
-| Style encapsulation      | Yes (automatic)                         | Manual `@scope` or BEM        |

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

@@ -1,85 +0,0 @@
-# La voie Mado
-
-> Une seule bonne façon. Des contrats stricts. Pas de magie.
-
-Mado est un framework pour les équipes qui construisent des panneaux d'admin,
-des outils internes et des SPA métier. Ces apps doivent être simples à créer
-et ennuyeuses à maintenir. Mado préfère donc des conventions claires à cinq
-styles équivalents.
-
-## Principes
-
-1. **Une seule voie.** Si vous écrivez quelque chose d'inhabituel, vérifiez
-   d'abord s'il existe déjà un helper/API canonique.
-2. **L'explicite plutôt que la magie.** Pas de file-system scanners, globals
-   implicites ou side effects cachés.
-3. **La plateforme d'abord.** Web Components, History API, `<form>`, `fetch` et
-   Shadow DOM restent visibles.
-4. **Types stricts.** `tsc --strict --noUncheckedIndexedAccess` toujours.
-5. **Pas de dépendances runtime.** Le tooling dev/build est acceptable ; le
-   runtime Mado reste natif.
-
-## Structure du projet
-
-```txt
-src/
-├── main.ts           ← boot: global CSS/providers + render router
-├── app.routes.ts     ← readable app map, exports `manifest` + default routes()
-├── layouts/          ← app-zone wrappers (`page({ view: ({ child }) => ... })`)
-├── shared/           ← UI bricks, http client, pure lib, global CSS
-└── modules/          ← bounded contexts
-    └── billing/
-        ├── billing.routes.ts
-        ├── billing.public.ts
-        ├── billing.types.ts
-        ├── pages/
-        ├── data/
-        ├── api/
-        └── _contracts/
-```
-
-Le starter par défaut est la version canonique de cette forme. Si d'anciens
-exemples divergent, le starter et `docs/10-app-architecture.md` gagnent.
-
-## Un composant = un fichier
-
-```ts
-import { component, css, html } from "@madojs/mado";
-
-component("x-user-card", () => () => html`<div class="card"><slot></slot></div>`, {
-  styles: css`
-    .card { padding: 1rem; }
-  `,
-});
-```
-
-Importer le fichier du composant enregistre l'élément. Importez-le là où le tag
-est utilisé.
-
-## Une seule façon de décrire une page
-
-```ts
-import { html, page, resource, jsonFetcher } from "@madojs/mado";
-
-export default page({
-  title: ({ id }) => `User #${id}`,
-  view: ({ params }) => {
-    const user = resource(() => `/api/users/${params.id}`, jsonFetcher());
-    return html`...`;
-  },
-});
-```
-
-Les signals, resources et forms locaux à une page vivent dans `view()`. L'état
-partagé par un module vit dans `*.service.ts`.
-
-## Ce que nous ne faisons pas
-
-- Pas de JSX/Vue/Svelte syntax.
-- Pas de custom elements sans trait d'union.
-- Pas de lecture de signal via `.value`; un signal est une fonction.
-- Pas de `innerHTML` direct.
-- Pas de runtime packages sans discussion.
-
-En cas de doute, documentez une recette claire plutôt que d'ajouter un nouveau
-primitive au core.

package/docs/fr/01-routing.md

@@ -1,120 +0,0 @@
-# Routage
-
-> Une seule app map. Pas de folder scanners. Pas de syntaxe magique.
-
-Mado ne déduit pas les routes depuis les fichiers. La composition doit rester
-lisible dans un seul endroit.
-
-## App Manifest
-
-Utilisez `src/app.routes.ts` comme carte de l'application :
-
-```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);
-```
-
-Ouvrez `app.routes.ts` pour voir les zones de l'app : pages publiques, auth,
-zones protégées, guards et shells.
-
-Exportez `manifest` pour `mado bake`.
-
-## Module Routes
-
-Les modules exportent de simples route maps. Ils n'appellent pas `layout()` et
-ne décident pas quel shell les enveloppe.
-
-```ts
-export const billingRoutes = {
-  "/invoices": () => import("./pages/invoices-list.page.js"),
-  "/invoices/:id": () => import("./pages/invoice-detail.page.js"),
-};
-```
-
-Le prefix est appliqué par `src/app.routes.ts` quand le module est monté sous
-`"/billing"`.
-
-## Layout Group
-
-```ts
-"/admin": layout({
-  layout: () => import("./layouts/app-shell.layout.js"),
-  guard: requireAuth,
-  routes: adminRoutes,
-}),
-```
-
-Un layout est un fichier `page({...})` ordinaire :
-
-```ts
-import { html, page } from "@madojs/mado";
-
-export default page({
-  view: ({ child }) => html`
-    <div class="layout layout--app">
-      <main class="app-main">${child}</main>
-    </div>
-  `,
-});
-```
-
-Gardez les layout views stateless. Les signals, resources et forms spécifiques
-à une page vivent dans les pages/components/resources.
-
-## Page Contract
-
-```ts
-import { html, page } from "@madojs/mado";
-
-export default page<{ id: string }>({
-  title: ({ id }) => `User ${id}`,
-  view: ({ params }) => html`<h1>${params.id}</h1>`,
-});
-```
-
-## Navigation
-
-```ts
-import appRoutes from "./app.routes.js";
-
-appRoutes.navigate("/billing/invoices");
-appRoutes.navigate("/billing/invoices?page=2");
-appRoutes.navigate("/login", { replace: true });
-```
-
-## Query Parameters
-
-```ts
-import { queryParam } from "@madojs/mado";
-
-const page = queryParam("page", "1");
-page();
-page.set("2");
-page.set(null);
-page.set("3", { push: true });
-```
-
-## Ce qui est absent volontairement
-
-- Pas d'auto-scan des dossiers de pages.
-- Pas de syntaxe filesystem comme `[id]`, `(group)`, `_layout`.
-- Pas de server routes dans le manifest client.
-- Pas de découverte cachée des layouts.

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

@@ -1,84 +0,0 @@
-# Structure du projet
-
-Chaque application Mado utilise la même forme canonique. Cette convention
-permet aux humains et aux assistants IA de savoir où placer le code.
-
-```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                # entrée Vite + shell SPA
-├── public/                   # assets statiques: favicon, images, robots.txt
-└── src/
-    ├── main.ts               # importe le CSS et monte le router dans #app
-    ├── app.routes.ts         # app map: manifest + default routes(...)
-    ├── layouts/              # layouts de zones d'application
-    ├── shared/               # ui, http, lib, styles
-    └── modules/              # bounded contexts
-        └── billing/
-            ├── billing.routes.ts
-            ├── billing.public.ts
-            ├── billing.types.ts
-            ├── pages/
-            ├── data/
-            ├── api/
-            └── _contracts/
-```
-
-## États Des Artefacts
-
-| Dossier | Ce que c'est | Écrit par | Déployer ? |
-| --- | --- | --- | --- |
-| `src/` | sources TypeScript | vous | non |
-| `public/` | assets statiques copiés tels quels | vous | via `out/` |
-| `out/` | artefact déployable: shell SPA + assets + HTML baked | `mado release` | oui |
-
-`mado release` = `typecheck` + build Vite (`out/index.html`, `out/assets/`,
-`public/*`) + `bake` directement dans les chemins de routes + `sitemap.xml` +
-precompression.
-
-`index.html` reste à la racine car Vite le traite comme entry template. Mettez
-dans `public/` uniquement les fichiers à copier tels quels.
-
-## Où mettre un nouveau fichier ?
-
-| Quoi | Où |
-| --- | --- |
-| Page pour une nouvelle URL | `src/modules/<module>/pages/<name>.page.ts` + module routes |
-| Route map de module | `src/modules/<module>/<module>.routes.ts` |
-| App shell/layout | `src/layouts/<zone>.layout.ts` |
-| Widget UI partagé | `src/shared/ui/<x-name>.component.ts` |
-| Widget UI propre à un module | `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/` |
-| Surface publique de module | `src/modules/<module>/<module>.public.ts` |
-| Fonction pure sans UI | `src/shared/lib/<name>.ts` |
-| Image statique / favicon | `public/<file>` |
-| CSS de shell | `src/shared/styles/shell.css` |
-| CSS de contenu page | `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",
-  },
-});
-```
-
-Le starter active le transformer Lightning CSS de Vite. Mado ne possède pas le
-prefixing, le lowering CSS ou la minification.
-
-## Ce qui ne va PAS dans `src/`
-
-- Configs de build-tool supplémentaires — utilisez `vite.config.ts`.
-- Fichiers `.env` — lisez l'env dans `src/shared/lib/config.ts` puis importez
-  ce module.
-- Tests mélangés au code — gardez-les dans `test/`.