Track HiveGrid Cloud planning reference

hivegrid-cloud/packages/mail/scripts/preview-server.ts

@@ -0,0 +1,81 @@
+/**
+ * Local React-Email preview server.
+ *
+ * Run via `pnpm --filter @toolctrl/mail preview` and visit
+ * http://localhost:3001 — the index lists every transactional
+ * template; clicking a name renders the template with the sample
+ * props from `previews.ts` so designers can iterate without
+ * triggering live email sends.
+ *
+ * Intentionally tiny — uses Node's built-in `http` server so the
+ * mail package keeps a small dep footprint. For production-grade
+ * preview workflows (visual-regression diffing, screenshot capture)
+ * mount the React-Email components in Storybook (Phase 08).
+ */
+import { createServer, type IncomingMessage, type ServerResponse } from "node:http";
+import { reactTransactionalTemplateNames, renderTransactionalEmail } from "../src/templates-react/render.js";
+import { samplePropsByTemplate } from "./previews.js";
+
+const PORT = Number.parseInt(process.env.MAIL_PREVIEW_PORT ?? "3001", 10);
+
+function escapeHtml(value: string): string {
+  return value
+    .replaceAll("&", "&")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;");
+}
+
+function renderIndex(): string {
+  const names = reactTransactionalTemplateNames();
+  const items = names
+    .map((name) => `<li><a href="/preview/${name}">${escapeHtml(name)}</a> &middot; <a href="/preview/${name}?format=text">text</a></li>`)
+    .join("");
+  return `<!doctype html><html><head><meta charset="utf-8"><title>Mail Preview</title>
+<style>body{font-family:system-ui;margin:40px;max-width:720px}a{color:#2563eb}li{margin:6px 0}</style>
+</head><body><h1>Mail template preview</h1>
+<p>Browsing ${names.length} transactional templates. Each entry links to the rendered HTML and a plain-text fallback.</p>
+<ul>${items}</ul>
+</body></html>`;
+}
+
+function handle(req: IncomingMessage, res: ServerResponse): void {
+  const url = new URL(req.url ?? "/", `http://localhost:${PORT}`);
+  if (url.pathname === "/" || url.pathname === "/preview") {
+    res.writeHead(200, { "content-type": "text/html; charset=utf-8" });
+    res.end(renderIndex());
+    return;
+  }
+  const match = /^\/preview\/(.+)$/.exec(url.pathname);
+  if (!match) {
+    res.writeHead(404, { "content-type": "text/plain" });
+    res.end("not found");
+    return;
+  }
+  const templateName = match[1] as ReturnType<typeof reactTransactionalTemplateNames>[number];
+  const sample = samplePropsByTemplate[templateName];
+  if (!sample) {
+    res.writeHead(404, { "content-type": "text/plain" });
+    res.end(`unknown template: ${templateName}`);
+    return;
+  }
+  try {
+    const rendered = renderTransactionalEmail(templateName, sample);
+    if (url.searchParams.get("format") === "text") {
+      res.writeHead(200, { "content-type": "text/plain; charset=utf-8" });
+      res.end(rendered.text);
+      return;
+    }
+    res.writeHead(200, { "content-type": "text/html; charset=utf-8" });
+    res.end(rendered.html);
+  } catch (error) {
+    res.writeHead(500, { "content-type": "text/plain" });
+    res.end(`render failed: ${(error as Error).message}`);
+  }
+}
+
+const server = createServer(handle);
+server.listen(PORT, () => {
+  // eslint-disable-next-line no-console
+  console.log(`📧 Mail preview server listening on http://localhost:${PORT}`);
+});

hivegrid-cloud/packages/mail/scripts/previews.ts

@@ -0,0 +1,73 @@
+/**
+ * Sample props per template, served by the local preview-server.
+ * Keep these realistic but synthetic — never seed with production
+ * PII. Used only in dev, never bundled into the published package.
+ */
+import { withBrandDefaults } from "../src/templates-react/_layout/theme.js";
+import type { ReactTemplatePropsMap } from "../src/templates-react/render.js";
+
+const brand = withBrandDefaults({
+  productName: "ToolCTRL",
+  tenantName: "Acme Inc",
+  primaryColor: "#2563eb",
+});
+
+export const samplePropsByTemplate: { [K in keyof ReactTemplatePropsMap]: ReactTemplatePropsMap[K] } = {
+  welcome: {
+    brand,
+    recipientName: "Ada Lovelace",
+    actionUrl: "https://app.example.com/login",
+  },
+  "magic-link": {
+    brand,
+    recipientName: "Ada Lovelace",
+    actionUrl: "https://app.example.com/magic/abc123",
+    expiresInMinutes: 15,
+  },
+  "password-reset": {
+    brand,
+    recipientName: "Ada Lovelace",
+    actionUrl: "https://app.example.com/reset?t=xyz789",
+  },
+  invitation: {
+    brand,
+    recipientName: "Ada Lovelace",
+    senderName: "Grace Hopper",
+    senderOrganization: "Acme Inc",
+    actionUrl: "https://app.example.com/invite/abc",
+  },
+  "subscription-success": {
+    brand,
+    recipientName: "Ada Lovelace",
+    planName: "Pro",
+    amountFormatted: "$29.00",
+    nextBillingDate: "2026-06-17",
+    actionUrl: "https://app.example.com/billing",
+  },
+  "subscription-failed": {
+    brand,
+    recipientName: "Ada Lovelace",
+    planName: "Pro",
+    amountFormatted: "$29.00",
+    failureReason: "Card declined",
+    retryAt: "2026-05-20",
+    actionUrl: "https://app.example.com/billing",
+  },
+  "invoice-sent": {
+    brand,
+    recipientName: "Ada Lovelace",
+    invoiceNumber: "INV-2026-0001",
+    amountFormatted: "€99.00",
+    issueDate: "2026-05-17",
+    dueDate: "2026-06-17",
+    actionUrl: "https://invoice.stripe.com/i/abc",
+  },
+  "tenant-notification": {
+    brand,
+    recipientName: "Ada Lovelace",
+    title: "New comment on Ticket #42",
+    body: "Grace mentioned you in a comment on Ticket #42. Tap below to read the thread.",
+    actionUrl: "https://app.example.com/tickets/42",
+    actionLabel: "View ticket",
+  },
+};