first commit

docs/communication/emails/email-templates/src/templates/verification/verification.md

@@ -0,0 +1,83 @@
+# verification
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+The `verificationTemplate` is the standard email-address verification
+flow message. It greets the recipient, optionally displays a one-time
+code in a centred tinted container with tracked letter-spacing for
+readability, exposes the verify-link CTA, and includes an expiry
+notice.
+
+The template handles both code-only and link-only verification flows by
+making the `code` field optional. When omitted, the code container is
+skipped entirely.
+
+## Features
+
+- Optional one-time code rendering in a tinted container (32 px,
+  bold, 8 px letter-spacing — the conventional "OTP display" treatment).
+- Configurable `expiresInMinutes` (defaults to `30`).
+- Themed verify-email CTA pointing at `verificationUrl`.
+- Footer with injectable `Clock` for deterministic year.
+- "If you didn't create an account" caution paragraph.
+
+## Usage: Basic
+
+```ts
+import { renderToHtml } from "@suaveplan/email-templates/renderer";
+import { verificationTemplate } from "@suaveplan/email-templates/templates";
+
+const { html, text, subject } = renderToHtml(verificationTemplate, {
+  recipientName: "Jane",
+  verificationUrl: "https://app.example.test/verify?token=abc",
+  code: "ABC123",
+});
+```
+
+## Usage: Advanced
+
+Link-only verification with a tighter expiry and a tenant-specific
+brand:
+
+```ts
+import { renderToHtml } from "@suaveplan/email-templates/renderer";
+import { createTheme } from "@suaveplan/email-templates/theme";
+import { verificationTemplate } from "@suaveplan/email-templates/templates";
+
+const theme = createTheme({ branding: { companyName: "Acme" } });
+renderToHtml(
+  verificationTemplate,
+  {
+    recipientName: "Jane",
+    verificationUrl: "https://acme.test/verify?token=abc",
+    expiresInMinutes: 5,
+    companyName: "Acme",
+  },
+  { theme },
+);
+```
+
+## API Reference
+
+| Symbol                  | Kind     | Description                                       |
+| ----------------------- | -------- | ------------------------------------------------- |
+| `verificationTemplate`  | const    | `EmailTemplate<VerificationProps>`.                |
+| `VerificationEmail`     | function | Component returning a `VNode`.                    |
+| `VerificationProps`     | type     | `{ recipientName, verificationUrl, code?, expiresInMinutes?, companyName? }` |
+
+## Implementation Notes
+
+The empty-string check on `code` is intentional: an upstream sanitiser
+that strips whitespace from a missing-value form field commonly produces
+`""` rather than `undefined`. Treating both as "no code" keeps the
+template stable against caller-side variance without requiring a Zod
+schema at the boundary.
+
+The OTP container's `letter-spacing: 8px` is wide enough that 6-digit
+codes render as visually-grouped pairs in most clients, which improves
+copy-by-eye accuracy. The font size (32 px) is large enough to remain
+legible on a phone-sized email preview without dominating the layout.