@madojs/mado 0.11.1 → 0.12.0

package/starters/modular/src/main.ts

@@ -0,0 +1,16 @@
+// App entry point. The ONLY file allowed to import CSS at runtime.
+import "./shared/styles/tokens.css";
+import "./shared/styles/reset.css";
+import "./shared/styles/shell.css";
+import "./shared/styles/content.css";
+
+import { html, render } from "@madojs/mado";
+
+import { init as initAuth } from "./modules/auth/auth.service";
+import appRoutes from "./app.routes";
+
+// One-off boot order: init cross-cutting modules first, then render the
+// router view into #app.
+await initAuth();
+
+render(html`${appRoutes.view}`, document.getElementById("app")!);

package/starters/{default → modular}/src/modules/billing/pages/invoices-list.page.ts

@@ -1,4 +1,4 @@
-import { each, html, page, signal, untracked } from "@madojs/mado";
+import { each, html, page, routeUrl, signal, untracked } from "@madojs/mado";
 
 import { formatDate, formatMoney } from "../../../shared/lib/format-date";
 import "../../../shared/ui/x-spinner.component";
@@ -50,7 +50,7 @@ export default page({
                           (i) => html`
                             <tr>
                               <td>
-                                <a href=${`/billing/invoices/${i.id}`}>${i.number}</a>
+                                <a data-link href=${routeUrl(`/billing/invoices/${i.id}`)}>${i.number}</a>
                               </td>
                               <td>${i.customerEmail}</td>
                               <td>${formatMoney(i.amount, i.currency)}</td>
@@ -59,7 +59,7 @@ export default page({
                               </td>
                               <td>${formatDate(i.issuedAt)}</td>
                               <td>
-                                <a href=${`/billing/invoices/${i.id}`}>Open</a>
+                                <a data-link href=${routeUrl(`/billing/invoices/${i.id}`)}>Open</a>
                               </td>
                             </tr>
                           `,

package/starters/{default → modular}/src/modules/home/home.page.ts

@@ -6,7 +6,7 @@
 //
 // A page should be read top-to-bottom and understood without jumping files.
 
-import { html, page } from "@madojs/mado";
+import { html, page, routeUrl } from "@madojs/mado";
 
 // 1. LOCAL STATE — none
 // 2. DATA       — none
@@ -14,20 +14,18 @@ import { html, page } from "@madojs/mado";
 
 // 4. VIEW
 export default page({
+  static: true,
   title: "Home",
   head: () => ({
     description: "A modular Mado application.",
   }),
-  bake: {
-    paths: () => [{}],
-    data: () => ({}),
-  },
   view: () => html`
     <section>
       <h1>Mado App</h1>
       <p>
-        Welcome. Try <a href="/billing/invoices">billing</a> or
-        <a href="/login">sign in</a>.
+        Welcome. Try
+        <a data-link href=${routeUrl("/billing/invoices")}>billing</a>
+        or <a data-link href=${routeUrl("/login")}>sign in</a>.
       </p>
     </section>
   `,

package/starters/modular/src/modules/home/not-found.page.ts

@@ -0,0 +1,14 @@
+import { html, page, routeUrl } from "@madojs/mado";
+
+export default page({
+  title: "Not Found",
+  view: () => html`
+    <section>
+      <h1>404</h1>
+      <p>
+        This route does not exist.
+        <a data-link href=${routeUrl("/")}>Go home</a>.
+      </p>
+    </section>
+  `,
+});

package/starters/modular/src/styles.d.ts

@@ -0,0 +1 @@
+declare module "*.css";

package/starters/modular/src/vite-env.d.ts

@@ -0,0 +1 @@
+/// <reference types="vite/client" />

package/starters/modular/tsconfig.json

@@ -0,0 +1,24 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ES2022",
+    "moduleResolution": "Bundler",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "strict": true,
+    "noImplicitOverride": true,
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true,
+    "noFallthroughCasesInSwitch": true,
+    "forceConsistentCasingInFileNames": true,
+    "esModuleInterop": true,
+    "resolveJsonModule": true,
+    "skipLibCheck": true,
+    "useDefineForClassFields": true,
+    "experimentalDecorators": false,
+    "isolatedModules": true,
+    "verbatimModuleSyntax": true,
+    "noEmit": true
+  },
+  "include": ["src/**/*.ts", "src/**/*.d.ts"],
+  "exclude": ["node_modules", "out"]
+}

package/starters/modular/vite.config.ts

@@ -0,0 +1,131 @@
+import { defineConfig, type Plugin } from "vite";
+import { mado } from "@madojs/mado/vite";
+
+/**
+ * Tiny in-memory mock for the auth + billing API used by this starter.
+ *
+ * Mounted only in `dev` so `mado release` ships a clean bundle that
+ * talks to your real backend. The endpoint shape mirrors what
+ * `auth.connector.ts` and `stripe.connector.ts` expect: any change in
+ * one must be mirrored in the other.
+ *
+ * Disable by removing this plugin or setting `MADO_MOCK_API=0`.
+ */
+function devApiMock(): Plugin {
+  const users = new Map<string, { password: string; user: unknown }>([
+    [
+      "demo@mado.dev",
+      {
+        password: "demo",
+        user: {
+          id: "u_demo",
+          email: "demo@mado.dev",
+          roles: ["user"],
+          permissions: ["billing.read"],
+        },
+      },
+    ],
+  ]);
+  const invoices = Array.from({ length: 6 }, (_, i) => ({
+    id: `in_${1000 + i}`,
+    number: `INV-${1000 + i}`,
+    customer_email: "demo@mado.dev",
+    amount_due: 1000 * (i + 1),
+    currency: "usd",
+    status: i % 3 === 0 ? "paid" : i % 3 === 1 ? "pending" : "draft",
+    created: Math.floor(Date.now() / 1000) - i * 86_400,
+  }));
+  let token: string | null = null;
+  const json = (res: import("http").ServerResponse, status: number, body: unknown) => {
+    res.statusCode = status;
+    res.setHeader("content-type", "application/json");
+    res.end(JSON.stringify(body));
+  };
+  const readJson = (req: import("http").IncomingMessage) =>
+    new Promise<Record<string, unknown>>((resolve) => {
+      let buf = "";
+      req.on("data", (chunk) => (buf += chunk));
+      req.on("end", () => {
+        try {
+          resolve(buf ? JSON.parse(buf) : {});
+        } catch {
+          resolve({});
+        }
+      });
+    });
+
+  return {
+    name: "starter:dev-api-mock",
+    apply: "serve",
+    configureServer(server) {
+      if (process.env.MADO_MOCK_API === "0") return;
+      server.middlewares.use(async (req, res, next) => {
+        const url = req.url ?? "";
+        if (!url.startsWith("/api/")) return next();
+
+        // ---- auth -----------------------------------------------------
+        if (url === "/api/auth/login" && req.method === "POST") {
+          const body = await readJson(req);
+          const entry = users.get(String(body.email ?? ""));
+          if (!entry || entry.password !== body.password) {
+            return json(res, 401, { error: "invalid_credentials" });
+          }
+          token = `tok_${Math.random().toString(36).slice(2)}`;
+          return json(res, 200, { token, user: entry.user });
+        }
+        if (url === "/api/auth/me" && req.method === "GET") {
+          if (!token) return json(res, 401, { error: "unauthenticated" });
+          const entry = users.values().next().value;
+          return json(res, 200, entry.user);
+        }
+        if (url === "/api/auth/logout" && req.method === "POST") {
+          token = null;
+          return json(res, 204, null);
+        }
+
+        // ---- billing --------------------------------------------------
+        if (url.startsWith("/api/billing/stripe/invoices")) {
+          const id = url.match(/\/invoices\/([^/?]+)/)?.[1];
+          if (req.method === "POST" && url.endsWith("/pay") && id) {
+            const inv = invoices.find((x) => x.id === id);
+            if (!inv) return json(res, 404, { error: "not_found" });
+            inv.status = "paid";
+            return json(res, 200, inv);
+          }
+          if (id && req.method === "GET") {
+            const inv = invoices.find((x) => x.id === id);
+            return inv
+              ? json(res, 200, inv)
+              : json(res, 404, { error: "not_found" });
+          }
+          if (req.method === "GET") {
+            return json(res, 200, { data: invoices, has_more: false });
+          }
+        }
+
+        return next();
+      });
+    },
+  };
+}
+
+export default defineConfig({
+  plugins: [
+    devApiMock(),
+    mado({
+      // Public origin used to build absolute URLs for static snapshots
+      // (sitemap, canonical, OpenGraph). Combined with Vite's `base`,
+      // the canonical for a route is `site + base + pathname`.
+      //
+      // REQUIRED when any page declares `static`. Set to your deployment
+      // origin (e.g. https://your-app.example) before running
+      // `mado release`. Override per environment via:
+      //   mado release --base-url https://staging.example
+      //   MADO_SITE=https://staging.example mado release
+      // site: "https://your-app.example",
+    }),
+  ],
+  css: {
+    transformer: "lightningcss",
+  },
+});

package/TODO.md

@@ -1,79 +0,0 @@
-# TODO
-
-Backlog, not a roadmap. Keep this file small and honest: ideas stay here only
-while they are plausible next work. Promote concrete work to issues or release
-notes when it becomes real.
-
-## Before Public Demo / Release
-
-- [ ] Run the default starter as a real demo app and feed every friction point
-  back into docs, CLI generators, or starter structure.
-- [ ] Add focused tests for every `mado new` generator template.
-- [ ] Audit EN/RU/FR docs after each tooling/runtime change; no old `dist/`,
-  `tsc-only`, custom-bundler, or legacy example wording should remain.
-- [ ] Keep `mado preview` boring and reliable inside generated apps.
-- [ ] Add a short maintainer-only release checklist if manual npm publish stays
-  in use.
-
-## CLI / DX
-
-- [ ] Decide whether `npx mado create my-app` is worth adding after package
-  naming and install friction are clear.
-- [ ] Consider short aliases over `mado new` only after real usage shows they
-  save enough typing (`mado page`, `mado component`, etc.).
-- [ ] Split preview/static-server internals only if `scripts/preview.mjs` grows.
-- [ ] Typed navigation inferred from route patterns.
-- [ ] Editor highlighting docs should prefer existing tooling first; build a
-  Mado-specific VS Code extension only if current HTML/CSS template support is
-  not enough.
-
-## Runtime / App API
-
-- [ ] Mutation rollback helper on top of `resource().mutate()` and `mutation()`.
-- [ ] Document loading/error shell patterns before adding an `<x-async>` API.
-- [ ] `liveResource()` over SSE / WebSocket after a real app needs live data.
-- [ ] i18n helper once browser-native message formatting is realistic.
-- [ ] Accessibility helpers: focus trap, live region, click outside.
-
-## Styling
-
-- [ ] Docs for `::part`, `::slotted()` and `:host-context()`.
-- [ ] Document Vite CSS options, including `css.transformer: "lightningcss"`,
-  for apps that want Lightning CSS.
-- [ ] Optional tiny utilities stylesheet only if the starter/demo repeats the
-  same small classes often enough to justify it.
-- [ ] CSP-friendly style mode.
-
-## Bake / Smart Static
-
-- [ ] Add bake regression coverage for layout groups, dynamic params, sitemap,
-  and hard-refresh deploy paths.
-- [ ] Incremental bake cache after a real content-heavy app needs it.
-- [ ] Webhook re-bake endpoint only after incremental bake has a concrete use.
-- [ ] RSS / Atom feed generator for docs/blog/demo content.
-
-## Operations
-
-- [ ] Benchmark against Lit / Solid / Preact.
-- [ ] Source-map notes and a minimal dev error overlay.
-- [ ] `eslint-plugin-mado` rules only if docs/starter conventions are not enough
-  to prevent recurring mistakes.
-- [ ] Timeout / retry options for resource fetchers after real API friction.
-- [ ] Schema validation hook for resources after choosing a dependency-free
-  story or a clearly optional integration.
-- [ ] PWA scaffold only if the public demo or a real app needs offline behavior.
-
-## Community / GitHub
-
-- [ ] Minimal landing site built with Mado.
-- [ ] Public live demo: CRUD starter and showcase hosted from Mado itself.
-- [ ] Case study: real React page -> Mado + bake.
-- [ ] Convert contribution-ready TODO items into GitHub issues with labels
-  (`good first issue`, `help wanted`, `docs`, `cli`, `ci`) after the first
-  public feedback round.
-- [ ] Configure npm Trusted Publishing for GitHub Actions after verifying the
-  first manual publishes.
-- [ ] Decide the release flow: continue manual npm publish for patch releases or
-  publish from signed `v*` tags through `.github/workflows/release.yml`.
-- [ ] Improve generated release notes with PR links/authors when releases start
-  going through pull requests.

package/docs/en/01-routing.md

@@ -1,152 +0,0 @@
-# Routing
-
-> One app map. No folder scanners. No special path syntax.
-
-Mado does not infer routes from files. The browser sees files as files; route
-composition should be readable in one place.
-
-## App Manifest
-
-Use `src/app.routes.ts` as the application map:
-
-```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);
-```
-
-Open `app.routes.ts` and you can see the whole app: public pages, auth zone,
-protected app zones, guards and shells.
-
-Exporting `manifest` is important because `mado bake` reads it.
-
-## Module Routes
-
-Modules export plain route maps. They do not call `layout()` and they do not
-decide which shell wraps them.
-
-```ts
-// src/modules/billing/billing.routes.ts
-export const billingRoutes = {
-  "/invoices": () => import("./pages/invoices-list.page.js"),
-  "/invoices/:id": () => import("./pages/invoice-detail.page.js"),
-};
-```
-
-The prefix is applied by `src/app.routes.ts` when the module is mounted under
-`"/billing"`.
-
-## What Goes On The Right Side
-
-### Lazy page import
-
-```ts
-"/users/:id": () => import("./modules/users/pages/user-profile.page.js"),
-```
-
-Vite creates a separate chunk for dynamic imports in production.
-
-### Eager page
-
-```ts
-import home from "./modules/home/home.page.js";
-
-export const manifest = {
-  "/": home,
-};
-```
-
-Use this only for tiny critical pages.
-
-### Layout group
-
-```ts
-"/admin": layout({
-  layout: () => import("./layouts/app-shell.layout.js"),
-  guard: requireAuth,
-  routes: adminRoutes,
-}),
-```
-
-A layout is a normal `page({...})` file:
-
-```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>
-  `,
-});
-```
-
-Keep layout views stateless. Put page-specific signals, resources and forms in
-pages/components/resources, not in layout locals.
-
-## 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>`,
-});
-```
-
-If a lazy route does not default-export `page({...})`, `routes()` throws a clear
-error.
-
-## Navigation
-
-```ts
-import appRoutes from "./app.routes.js";
-
-appRoutes.navigate("/billing/invoices");
-appRoutes.navigate("/billing/invoices?page=2");
-appRoutes.navigate("/login", { replace: true });
-```
-
-Clicks on `<a href="/foo">` are intercepted for same-origin SPA navigation.
-External links still use normal browser navigation.
-
-## 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 });
-```
-
-`queryParam()` is a signal. Use it in pages or components when URL state is part
-of the UI.
-
-## What Is Intentionally Absent
-
-- No auto-scan of page folders.
-- No special filesystem route syntax like `[id]`, `(group)`, `_layout`.
-- No server routes in the client manifest.
-- No hidden layout discovery. App zones are explicit in `app.routes.ts`.

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

@@ -1,124 +0,0 @@
-# Project layout
-
-Every Mado app uses the same shape. This is a **mandatory** convention — it
-exists so that you, your teammates, and any LLM assistant always know where
-things live.
-
-```
-my-app/
-├── package.json              # exactly one runtime dep: @madojs/mado
-├── tsconfig.json             # strict TS, ES2022, Bundler resolution
-├── vite.config.ts            # optional; use mado() from @madojs/mado/vite
-├── index.html                # Vite entry + SPA shell
-├── public/                   # static assets (favicons, images, robots.txt)
-└── src/
-    ├── main.ts               # entry: mount router into #app
-    ├── app.routes.ts         # one app map (default + named `manifest`)
-    ├── layouts/              # app-zone layouts, not domain modules
-    ├── shared/               # ui, http, lib, styles
-    └── modules/              # bounded contexts
-        └── billing/
-            ├── billing.routes.ts
-            ├── billing.public.ts
-            ├── billing.types.ts
-            ├── pages/
-            ├── data/
-            ├── api/
-            └── _contracts/
-```
-
-## The three artifact states (read this once, never wonder again)
-
-| Folder      | What it is                                                     | Who writes        | Who reads                  | Deploy?           |
-|-------------|----------------------------------------------------------------|-------------------|----------------------------|-------------------|
-| `src/`      | your source (TypeScript)                                       | you               | Vite, `tsc --noEmit`       | ❌ no             |
-| `public/`   | static assets copied as-is (favicon, images, robots.txt)       | you               | Vite build                 | ✅ via `out/`     |
-| `out/`      | **the deploy artifact**: SPA shell + assets + baked HTML       | `mado release`    | nginx / CDN / Cloudflare   | ✅ **yes**        |
-
-One-liner to remember:
-> Develop with `mado dev`. To ship: run `mado release`, then upload `out/`.
-
-`mado release` = `typecheck` + Vite build (`out/index.html`, `out/assets/`,
-`public/*`) + `bake` directly into deployable route paths + `sitemap.xml` +
-precompressed assets and CDN helper files.
-
-`index.html` belongs at the project root because Vite treats it as an entry
-template, not as a static public file. Put only copy-as-is files in `public/`.
-
-### Quick deployment matrix
-
-| Target                | Command                              | Where it goes              |
-|-----------------------|--------------------------------------|----------------------------|
-| VPS + nginx           | `mado release && rsync -avz out/ …`  | `/var/www/<app>/`          |
-| Cloudflare Pages      | `mado release && wrangler pages deploy out` | CF Pages                 |
-| Netlify / S3 / GH Pages | `mado release && upload out/*`     | any static host            |
-
-See `docs/en/13-deployment.md` for full recipes.
-
-## Where to put a new file?
-
-| 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`                       |
-| Reusable 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 with no UI            | `src/shared/lib/<name>.ts`                           |
-| Static image / favicon              | `public/<file>`                                      |
-| App-zone shell CSS                  | `src/shared/styles/shell.css`                       |
-| Page-level table/form/prose CSS      | `src/shared/styles/content.css`                     |
-
-If you don't know where — that is a signal that **the architecture is
-suffering**. Ask the team and **record** the answer in `docs/`. Don't invent a
-new top-level folder.
-
-## Naming rules
-
-| What                                | Style                | Example                |
-|-------------------------------------|----------------------|------------------------|
-| File                                | kebab-case           | `user-profile.ts`      |
-| Component tag                       | `x-` + kebab         | `<x-user-profile>`     |
-| Context                             | PascalCase + `Ctx`   | `ThemeCtx`, `AuthCtx`  |
-| Signal                              | camelCase            | `userId`, `isLoggedIn` |
-| Page-internal element               | `x-<route>-page`     | `<x-posts-page>`       |
-
-## Vite config
-
-App/dev/build settings live in `vite.config.ts`.
-
-```ts
-import { defineConfig } from "vite";
-import { mado } from "@madojs/mado/vite";
-
-export default defineConfig({
-  plugins: [mado()],
-  css: {
-    transformer: "lightningcss",
-  },
-  server: {
-    proxy: { "/api": "http://localhost:3000" },
-  },
-});
-```
-
-The default starter opts into Vite's Lightning CSS transformer. CSS
-minification is already handled by Vite; the explicit transformer keeps
-prefixing and modern CSS lowering in Vite instead of in Mado.
-
-`mado bake` uses conventions by default: `src/app.routes.ts` first,
-then `src/routes.ts`, `index.html` as the template, and `out/` as output.
-Use CLI flags (`--entry`, `--template`, `--out`, `--base-url`) for the few
-values that are specific to prerendering.
-
-## What does NOT go in `src/`
-
-- ❌ Extra build tool configs — use `vite.config.ts` with `mado()` when needed.
-- ❌ `.env` files — read env in `src/shared/lib/config.ts` from `import.meta.env` /
-  `process.env` and import that one module everywhere.
-- ❌ Tests mixed with code — put them in `test/`.
-- ❌ `examples/` folder — keep large demos outside the app repo.