@madojs/mado 0.10.1 → 0.11.1

package/starters/default/src/modules/auth/auth.connector.ts

@@ -0,0 +1,45 @@
+// Canonical *.connector.ts shape:
+//   1. CONFIG    — base URL, version flags
+//   2. MAPPERS   — DTO → domain (pure functions, tested in isolation)
+//   3. ENDPOINTS — thin, return domain types
+//   4. ERRORS    — provider-specific subclasses of HttpError (optional)
+//
+// Connectors NEVER import signals, resources, html, or pages.
+
+import { httpClient } from "../../shared/http/http-client";
+import { HttpError } from "../../shared/http/http-error";
+
+import type { LoginRequestDTO, LoginResponseDTO } from "./_contracts/auth-api.types";
+import type { Credentials, User } from "./auth.types";
+
+// 1. CONFIG
+const base = "/api/auth";
+
+// 2. MAPPERS
+const toUser = (dto: LoginResponseDTO["user"]): User => ({
+  id: dto.id,
+  email: dto.email,
+  roles: dto.roles,
+  permissions: dto.permissions,
+});
+
+// 3. ENDPOINTS
+export const authApi = {
+  login: async (creds: Credentials): Promise<{ token: string; user: User }> => {
+    const req: LoginRequestDTO = { email: creds.email, password: creds.password };
+    const res = await httpClient.post<LoginResponseDTO>(`${base}/login`, req);
+    return { token: res.token, user: toUser(res.user) };
+  },
+
+  me: async (): Promise<User> => {
+    const res = await httpClient.get<LoginResponseDTO["user"]>(`${base}/me`);
+    return toUser(res);
+  },
+
+  logout: (): Promise<void> => httpClient.post<void>(`${base}/logout`),
+};
+
+// 4. ERRORS
+export class AuthError extends HttpError {
+  override readonly name = "AuthError";
+}

package/starters/default/src/modules/auth/auth.guard.ts

@@ -0,0 +1,22 @@
+// Route guards live in the auth module so they can be reused across
+// app.routes.ts and any module that needs to gate UI by permission.
+//
+// A guard is a plain function: returns `true` to allow, returns a path
+// (string) to redirect, or false to deny.
+
+import { hasPermission, isAuthed } from "./auth.service";
+
+export function requireAuth(): boolean | string {
+  if (isAuthed()) return true;
+  // Redirect to login. Real apps may want to preserve the original target
+  // via a query param; keep simple here.
+  return "/login";
+}
+
+export function requirePermission(perm: string): () => boolean | string {
+  return () => {
+    if (!isAuthed()) return "/login";
+    if (!hasPermission(perm)) return "/";
+    return true;
+  };
+}

package/starters/default/src/modules/auth/auth.public.ts

@@ -0,0 +1,9 @@
+// THE single import surface other modules (and app.routes.ts) may use to
+// reach into `auth`. Anything not re-exported here is private to the module.
+// ESLint enforces it.
+//
+// Re-export only what callers should actually depend on.
+
+export { requireAuth, requirePermission } from "./auth.guard";
+export { hasPermission, hasRole, isAuthed, isBooting, login, logout, user } from "./auth.service";
+export type { Credentials, User, UserId } from "./auth.types";

package/starters/default/src/modules/auth/auth.routes.ts

@@ -0,0 +1,8 @@
+// Canonical *.routes.ts shape: a plain map of path → lazy page imports.
+//
+// Modules NEVER wrap themselves in a layout. Wrapping (which shell + guard)
+// is a composition decision that lives in src/app.routes.ts.
+
+export const authRoutes = {
+  "/": () => import("./login.page"), // mounted as /login by app.routes.ts
+};

package/starters/default/src/modules/auth/auth.service.ts

@@ -0,0 +1,71 @@
+// Canonical *.service.ts shape:
+//   1. PRIVATE STATE     — _signals, not exported
+//   2. PUBLIC READS      — getters / computed
+//   3. ACTIONS           — async functions that mutate state
+//   4. (optional) init() — wires interceptors, restores from storage
+//
+// Services are plain ES modules. The module identity = the singleton.
+
+import { computed, signal } from "@madojs/mado";
+
+import { registerAuthTokenProvider } from "../../shared/http/interceptors";
+
+import { authApi } from "./auth.connector";
+import type { Credentials, User } from "./auth.types";
+
+// 1. PRIVATE STATE
+const _user = signal<User | null>(null);
+const _token = signal<string | null>(null);
+const _booting = signal(true);
+
+const TOKEN_KEY = "mado.auth.token";
+
+// 2. PUBLIC READS
+//   Note: Mado signals are getter functions — read with `_user()`, write with
+//   `_user.set(value)` or `_user.update(fn)`. There is no `_user.value`.
+export const user = (): User | null => _user();
+export const token = (): string | null => _token();
+export const isAuthed = computed(() => _user() !== null);
+export const isBooting = (): boolean => _booting();
+
+export const hasRole = (role: string): boolean => _user()?.roles.includes(role) ?? false;
+export const hasPermission = (perm: string): boolean =>
+  _user()?.permissions.includes(perm) ?? false;
+
+// 3. ACTIONS
+export async function login(creds: Credentials): Promise<void> {
+  const { token: t, user: u } = await authApi.login(creds);
+  localStorage.setItem(TOKEN_KEY, t);
+  _token.set(t);
+  _user.set(u);
+}
+
+export async function logout(): Promise<void> {
+  try {
+    await authApi.logout();
+  } catch {
+    /* ignore network errors on logout */
+  }
+  localStorage.removeItem(TOKEN_KEY);
+  _token.set(null);
+  _user.set(null);
+}
+
+// 4. INIT
+// Called from main.ts at startup. Restores token, refetches user, wires the
+// HTTP auth interceptor.
+export async function init(): Promise<void> {
+  registerAuthTokenProvider(() => _token());
+
+  const saved = localStorage.getItem(TOKEN_KEY);
+  if (saved) {
+    _token.set(saved);
+    try {
+      _user.set(await authApi.me());
+    } catch {
+      localStorage.removeItem(TOKEN_KEY);
+      _token.set(null);
+    }
+  }
+  _booting.set(false);
+}

package/starters/default/src/modules/auth/auth.types.ts

@@ -0,0 +1,15 @@
+// Domain types exported by the auth module. Never import provider DTOs here.
+
+export type UserId = string;
+
+export interface User {
+  id: UserId;
+  email: string;
+  roles: string[];
+  permissions: string[];
+}
+
+export interface Credentials {
+  email: string;
+  password: string;
+}

package/starters/default/src/modules/auth/login.page.ts

@@ -0,0 +1,62 @@
+import { html, navigate, page, signal, useForm } from "@madojs/mado";
+
+import "../../shared/ui/x-button.component";
+
+import { login } from "./auth.service";
+
+// 1. LOCAL STATE
+// (per-view)
+
+// 2. DATA
+// (none)
+
+// 3. ACTIONS — handled inside the view (useForm is per-render)
+
+// 4. VIEW
+export default page({
+  title: "Sign in",
+  view: () => {
+    const submitting = signal(false);
+    const error = signal<string | null>(null);
+    const form = useForm({
+      email: { required: true, type: "email" },
+      password: { required: true, minLength: 6 },
+    });
+
+    const onSubmit = form.onSubmit(async (values) => {
+      submitting.set(true);
+      error.set(null);
+      try {
+        await login({
+          email: String(values.email ?? ""),
+          password: String(values.password ?? ""),
+        });
+        navigate("/");
+      } catch (err) {
+        error.set(err instanceof Error ? err.message : "Login failed");
+      } finally {
+        submitting.set(false);
+      }
+    });
+
+    return html`
+      <section>
+        <h1>Sign in</h1>
+        <form @submit=${onSubmit}>
+          <label>
+            Email
+            <input name="email" type="email" required @input=${form.onInput} />
+          </label>
+          <label>
+            Password
+            <input name="password" type="password" required @input=${form.onInput} />
+          </label>
+          ${() => (error() ? html`<p class="error">${error()}</p>` : null)}
+          <x-button ?disabled=${() => submitting() || !form.isValid()}>
+            ${() => (submitting() ? "Signing in…" : "Sign in")}
+          </x-button>
+        </form>
+      </section>
+    `;
+  },
+});

package/starters/default/src/modules/billing/_contracts/stripe.types.ts

@@ -0,0 +1,17 @@
+// Raw Stripe DTOs. PRIVATE to stripe.connector.ts.
+// Other files (resources, pages) must use domain Invoice from billing.types.ts.
+
+export interface StripeInvoiceDTO {
+  id: string;
+  number: string;
+  customer_email: string;
+  amount_due: number; // cents
+  currency: string; // lowercase
+  status: "draft" | "open" | "paid" | "void" | "uncollectible";
+  created: number; // unix
+}
+
+export interface StripeListResponseDTO<T> {
+  data: T[];
+  has_more: boolean;
+}

package/starters/default/src/modules/billing/api/stripe.connector.ts

@@ -0,0 +1,71 @@
+// Connector for ONE external system (Stripe). Stays small and predictable:
+//   1. CONFIG    2. MAPPERS    3. ENDPOINTS    4. ERRORS
+//
+// If we ever swap Stripe → another PSP, only this file (and its _contracts/)
+// changes. Pages and resources keep using the domain `Invoice`.
+
+import { httpClient } from "../../../shared/http/http-client";
+import { HttpError } from "../../../shared/http/http-error";
+
+import type {
+  StripeInvoiceDTO,
+  StripeListResponseDTO,
+} from "../_contracts/stripe.types";
+import type { Invoice, InvoiceStatus } from "../billing.types";
+
+// 1. CONFIG
+const base = "/api/billing/stripe";
+
+// 2. MAPPERS
+const toStatus = (s: StripeInvoiceDTO["status"]): InvoiceStatus => {
+  switch (s) {
+    case "paid":
+      return "paid";
+    case "draft":
+      return "draft";
+    case "void":
+    case "uncollectible":
+      return "void";
+    default:
+      return "pending";
+  }
+};
+
+const toInvoice = (dto: StripeInvoiceDTO): Invoice => ({
+  id: dto.id,
+  number: dto.number,
+  customerEmail: dto.customer_email,
+  amount: dto.amount_due / 100,
+  currency: dto.currency.toUpperCase(),
+  status: toStatus(dto.status),
+  issuedAt: new Date(dto.created * 1000).toISOString(),
+});
+
+// 3. ENDPOINTS
+export const stripeApi = {
+  listInvoices: async (params: { limit?: number; cursor?: string } = {}): Promise<{
+    items: Invoice[];
+    hasMore: boolean;
+  }> => {
+    const res = await httpClient.get<StripeListResponseDTO<StripeInvoiceDTO>>(
+      `${base}/invoices`,
+      { query: { limit: params.limit ?? 25, starting_after: params.cursor } },
+    );
+    return { items: res.data.map(toInvoice), hasMore: res.has_more };
+  },
+
+  getInvoice: async (id: string): Promise<Invoice> => {
+    const dto = await httpClient.get<StripeInvoiceDTO>(`${base}/invoices/${id}`);
+    return toInvoice(dto);
+  },
+
+  payInvoice: async (id: string): Promise<Invoice> => {
+    const dto = await httpClient.post<StripeInvoiceDTO>(`${base}/invoices/${id}/pay`);
+    return toInvoice(dto);
+  },
+};
+
+// 4. ERRORS
+export class StripeError extends HttpError {
+  override readonly name = "StripeError";
+}

package/starters/default/src/modules/billing/billing.public.ts

@@ -0,0 +1,5 @@
+// Public surface of the billing module.
+// Anything not re-exported here is internal and may change without notice.
+
+export type { Invoice, InvoiceId, InvoiceStatus } from "./billing.types";
+export { useInvoice, useInvoices } from "./data/invoices.resource";

package/starters/default/src/modules/billing/billing.routes.ts

@@ -0,0 +1,9 @@
+// Canonical *.routes.ts shape: a plain map of path → lazy page imports.
+//
+// Modules NEVER wrap themselves in a layout. Wrapping (which shell + guard)
+// is a composition decision that lives in src/app.routes.ts.
+
+export const billingRoutes = {
+  "/invoices": () => import("./pages/invoices-list.page"),
+  "/invoices/:id": () => import("./pages/invoice-detail.page"),
+};

package/starters/default/src/modules/billing/billing.types.ts

@@ -0,0 +1,15 @@
+// Domain types for the billing module. Public via billing.public.ts.
+
+export type InvoiceId = string;
+
+export type InvoiceStatus = "draft" | "pending" | "paid" | "void";
+
+export interface Invoice {
+  id: InvoiceId;
+  number: string;
+  customerEmail: string;
+  amount: number;
+  currency: string;
+  status: InvoiceStatus;
+  issuedAt: string; // ISO date
+}

package/starters/default/src/modules/billing/components/invoice-status-badge.component.ts

@@ -0,0 +1,43 @@
+// Module-local UI brick. Reactive attribute via ctx.attr().
+//
+// If another module ever needs this badge, MOVE the file to shared/ui/.
+// Don't import across modules.
+
+import { component, css, html } from "@madojs/mado";
+
+component(
+  "invoice-status-badge",
+  ({ attr }) => {
+    const status = attr("status", "pending");
+    return () => html`
+      <span class=${() => `badge badge--${status()}`}>${status}</span>
+    `;
+  },
+  {
+    styles: css`
+      .badge {
+        display: inline-block;
+        padding: 0 var(--space-2);
+        border-radius: var(--radius-sm);
+        font-size: 0.85em;
+        line-height: 1.6;
+      }
+      .badge--paid {
+        background: color-mix(in srgb, var(--color-success) 18%, transparent);
+        color: var(--color-success);
+      }
+      .badge--pending {
+        background: color-mix(in srgb, var(--color-text-muted) 18%, transparent);
+        color: var(--color-text-muted);
+      }
+      .badge--void {
+        background: color-mix(in srgb, var(--color-danger) 18%, transparent);
+        color: var(--color-danger);
+      }
+      .badge--draft {
+        background: color-mix(in srgb, var(--color-border) 60%, transparent);
+        color: var(--color-text);
+      }
+    `,
+  },
+);

package/starters/default/src/modules/billing/data/invoices.resource.ts

@@ -0,0 +1,35 @@
+// Canonical *.resource.ts shape:
+//   - Factories that return `resource(...)` / `mutation(...)`.
+//   - Resource KEYS use the API URL (or a clear URL-shaped string) so
+//     `invalidates: ["/api/billing/invoices*"]` matches naturally.
+//   - NO UI, NO services. Pure data layer over the connector.
+
+import { mutation, resource } from "@madojs/mado";
+
+import { stripeApi } from "../api/stripe.connector";
+import type { InvoiceId } from "../billing.types";
+
+const listKey = (cursor: string | undefined) =>
+  `/api/billing/invoices?cursor=${cursor ?? "first"}`;
+const oneKey = (id: InvoiceId) => `/api/billing/invoices/${id}`;
+
+export const useInvoices = (cursor: () => string | undefined) =>
+  resource(
+    () => listKey(cursor()),
+    () => {
+      const c = cursor();
+      return stripeApi.listInvoices(c ? { cursor: c } : {});
+    },
+    { staleTime: 30_000 },
+  );
+
+export const useInvoice = (id: () => InvoiceId) =>
+  resource(
+    () => oneKey(id()),
+    () => stripeApi.getInvoice(id()),
+    { staleTime: 60_000 },
+  );
+
+export const payInvoice = mutation((id: InvoiceId) => stripeApi.payInvoice(id), {
+  invalidates: ["/api/billing/invoices*"],
+});

package/starters/default/src/modules/billing/pages/invoice-detail.page.ts

@@ -0,0 +1,70 @@
+import { html, page, signal } from "@madojs/mado";
+
+import { formatDate, formatMoney } from "../../../shared/lib/format-date";
+import "../../../shared/ui/x-button.component";
+import "../../../shared/ui/x-spinner.component";
+
+import { hasPermission } from "../../auth/auth.public";
+
+import "../components/invoice-status-badge.component";
+import { payInvoice, useInvoice } from "../data/invoices.resource";
+
+// 4. VIEW
+export default page({
+  title: "Invoice",
+  // The router passes URL params and the matched query to the view.
+  view: ({ params }) => {
+    if (!params.id) return html`<p class="error">Missing invoice id.</p>`;
+    const invoiceId = params.id;
+
+    // 1. LOCAL STATE  (per-render)
+    const paying = signal(false);
+
+    // 2. DATA
+    const invoice = useInvoice(() => invoiceId);
+
+    // 3. ACTIONS
+    const onPay = async () => {
+      const current = invoice.data();
+      if (!current) return;
+      paying.set(true);
+      try {
+        await payInvoice.run(current.id);
+        invoice.refresh();
+      } finally {
+        paying.set(false);
+      }
+    };
+
+    return html`
+      <section>
+        ${() =>
+          invoice.loading()
+            ? html`<x-spinner></x-spinner>`
+            : invoice.error()
+              ? html`<p class="error">${() => invoice.error()?.message}</p>`
+              : (() => {
+                  const i = invoice.data();
+                  if (!i) return null;
+                  return html`
+                    <h1>Invoice ${i.number}</h1>
+                    <dl>
+                      <dt>Customer</dt><dd>${i.customerEmail}</dd>
+                      <dt>Amount</dt><dd>${formatMoney(i.amount, i.currency)}</dd>
+                      <dt>Status</dt>
+                      <dd>
+                        <invoice-status-badge status=${i.status}></invoice-status-badge>
+                      </dd>
+                      <dt>Issued</dt><dd>${formatDate(i.issuedAt)}</dd>
+                    </dl>
+                    ${i.status === "pending" && hasPermission("billing.invoices.pay")
+                      ? html`<x-button ?disabled=${paying} @click=${onPay}>
+                          ${() => (paying() ? "Paying…" : "Pay now")}
+                        </x-button>`
+                      : null}
+                  `;
+                })()}
+      </section>
+    `;
+  },
+});

package/starters/default/src/modules/billing/pages/invoices-list.page.ts

@@ -0,0 +1,73 @@
+import { each, html, page, signal, untracked } from "@madojs/mado";
+
+import { formatDate, formatMoney } from "../../../shared/lib/format-date";
+import "../../../shared/ui/x-spinner.component";
+
+import "../components/invoice-status-badge.component";
+import { useInvoices } from "../data/invoices.resource";
+
+// 1. LOCAL STATE
+// (per-view)
+
+// 2. DATA
+// (per-view)
+
+// 3. ACTIONS
+// (pagination handlers would go here)
+
+// 4. VIEW
+export default page({
+  title: "Invoices",
+  view: () => {
+    const cursor = signal<string | undefined>(undefined);
+    const invoices = untracked(() => useInvoices(cursor));
+
+    return html`
+      <section>
+        <h1>Invoices</h1>
+        ${() =>
+          invoices.loading()
+            ? html`<x-spinner></x-spinner>`
+            : invoices.error()
+              ? html`<p class="error">${() => invoices.error()?.message}</p>`
+              : html`
+                  <table class="data">
+                    <thead>
+                      <tr>
+                        <th>Number</th>
+                        <th>Customer</th>
+                        <th>Amount</th>
+                        <th>Status</th>
+                        <th>Issued</th>
+                        <th></th>
+                      </tr>
+                    </thead>
+                    <tbody>
+                      ${() =>
+                        each(
+                          invoices.data()?.items ?? [],
+                          (i) => i.id,
+                          (i) => html`
+                            <tr>
+                              <td>
+                                <a href=${`/billing/invoices/${i.id}`}>${i.number}</a>
+                              </td>
+                              <td>${i.customerEmail}</td>
+                              <td>${formatMoney(i.amount, i.currency)}</td>
+                              <td>
+                                <invoice-status-badge status=${i.status}></invoice-status-badge>
+                              </td>
+                              <td>${formatDate(i.issuedAt)}</td>
+                              <td>
+                                <a href=${`/billing/invoices/${i.id}`}>Open</a>
+                              </td>
+                            </tr>
+                          `,
+                        )}
+                    </tbody>
+                  </table>
+                `}
+      </section>
+    `;
+  },
+});

package/starters/default/src/modules/home/home.page.ts

@@ -0,0 +1,34 @@
+// Canonical *.page.ts shape:
+//   1. LOCAL STATE       — per-view signals owned by this page
+//   2. DATA              — resources from this module's *.resource.ts
+//   3. ACTIONS           — event handlers, mutations
+//   4. VIEW              — default export via page({...})
+//
+// A page should be read top-to-bottom and understood without jumping files.
+
+import { html, page } from "@madojs/mado";
+
+// 1. LOCAL STATE — none
+// 2. DATA       — none
+// 3. ACTIONS    — none
+
+// 4. VIEW
+export default page({
+  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>.
+      </p>
+    </section>
+  `,
+});

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

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