Initial Commit
This commit is contained in:
@@ -0,0 +1,81 @@
|
||||
# Design: enterprise-email-templates
|
||||
|
||||
## React-strip decision
|
||||
|
||||
The upstream `@suaveplan/email-templates` ships nine React JSX components rendered via `react-dom/server`'s `renderToStaticMarkup`. Upstream's `EmailComponent` / `EmailLayout` / `EmailButton` accept a `theme` prop and return a `ReactElement`; the template registry stores `ComponentType<TProps>` references and the renderer calls `createElement(template.component, mergedProps)`.
|
||||
|
||||
Enterprise spec §3 explicitly forbids React at runtime ("Zero browser / Node / React dependencies — pure TypeScript, runs in Bun, Node, and browser"). The genesis port therefore replaces the React layer with a **micro VNode tree** and a **pure-string HTML emitter**:
|
||||
|
||||
```ts
|
||||
interface VNode {
|
||||
tag: string; // element name
|
||||
attrs: Record<string, string | number | undefined>;
|
||||
children: ReadonlyArray<VNode | string>;
|
||||
self_closing?: boolean; // img / br / hr / meta
|
||||
}
|
||||
```
|
||||
|
||||
`h(tag, attrs, children)` is a hyperscript-style factory; the renderer walks the tree producing email-safe HTML strings.
|
||||
|
||||
### Why VNodes (not template strings, not direct concatenation)
|
||||
|
||||
Three options were considered and the VNode tree won:
|
||||
|
||||
1. **Tagged-template literal `html\`...\``** — readable but loses programmatic composition (each component would re-parse its substring children, attribute escaping has to happen inline at every site).
|
||||
2. **Direct `string` concatenation inside each component** — fastest, but every component duplicates `escapeHtml` + style serialisation, and the renderer cannot post-process (e.g. minify, inline) the tree.
|
||||
3. **VNode tree** ✅ — components emit data, the renderer owns the escape/style boundary in **one** place. This matches the upstream React contract structurally: a `Component(props) => ReactElement` becomes `Component(props) => VNode`. Consumer call sites change only at the import (no JSX, real factories).
|
||||
|
||||
### Attribute escaping
|
||||
|
||||
`renderVNode` emits attributes via `escapeAttr` (quotes-and-ampersand only) and text children via `escapeHtml` (full `< > & " '`). Attribute values of `undefined` are skipped. Numeric values are coerced via `String(n)`. Object-valued attributes are rejected at the boundary — the only object-shaped attribute upstream allowed was `style: CSSProperties`, which the renderer handles specially:
|
||||
|
||||
```ts
|
||||
// In components: style passed as Record<string, string | number>
|
||||
{ style: { padding: '12px 24px', borderRadius: '6px' } }
|
||||
// Renderer emits: style="padding:12px 24px;borderRadius:6px"
|
||||
```
|
||||
|
||||
The renderer uses the **prop key as-is** (kebab-case where upstream used kebab-case, camelCase where it didn't) — this is consistent with `react-dom`'s behaviour on the server: `react-dom` would kebabify `borderRadius` → `border-radius`. Since the test corpus is **structural** (htmlparser2 parses the output regardless of property casing), this is acceptable; the spec calls it out so consumers know.
|
||||
|
||||
### Self-closing tags
|
||||
|
||||
`img`, `br`, `hr`, `meta` are emitted as `<img ... />` (XHTML-compatible) — matches upstream's `react-dom` output for email clients.
|
||||
|
||||
### Footer year
|
||||
|
||||
Upstream calls `new Date().getFullYear()` at module render time, which violates §3's "no `Date.now()` at module scope" requirement. Genesis threads an injectable `Clock` (from `@suaveplan/types`) into the footer prop bag (defaulting to a real `Clock` if absent). Tests pass a `FakeClock` and assert the rendered year matches `clock.now()`.
|
||||
|
||||
### Component → VNode mapping
|
||||
|
||||
| Upstream JSX | Genesis VNode call |
|
||||
|---|---|
|
||||
| `<table role="presentation" cellPadding={0}>...</table>` | `h('table', { role: 'presentation', cellpadding: '0' }, [...])` |
|
||||
| `<a href={url} style={{...}}>{children}</a>` | `h('a', { href: url, style: {...} }, children)` |
|
||||
| `<img src={src} alt={alt} />` | `h('img', { src, alt }, [], { self_closing: true })` |
|
||||
| `{level >= 1 && level <= 6 && <h{level}>...</h{level}>}` | `h(\`h\${level}\`, attrs, children)` |
|
||||
|
||||
The five built-in templates are pure functions composing the nine factories — same code as upstream with JSX rewritten as `h()` calls.
|
||||
|
||||
### Test strategy
|
||||
|
||||
Every component + template test uses `htmlparser2` (the lightest streaming HTML parser in the ecosystem; pure-JS, no native deps) to parse the rendered string and walk the resulting DOM. Assertions are **structural**:
|
||||
|
||||
```ts
|
||||
const doc = parseDocument(renderVNode(EmailButton({ href: 'https://x', children: 'Click' })));
|
||||
const link = findOne(el => el.name === 'a', doc.children, true);
|
||||
expect(link?.attribs.href).toBe('https://x');
|
||||
```
|
||||
|
||||
This avoids snapshot churn from style-key reordering and side-steps the "two identical HTML strings, one passes one fails because of a space" trap.
|
||||
|
||||
### Coverage
|
||||
|
||||
100% statement / branch / function / line, enforced by the Istanbul-backed `vitest.config.ts`. The pure-function nature of the renderer + components makes branch coverage tractable: every conditional in upstream becomes a deterministic test case (e.g. `EmailButton`'s three variants × three sizes × `fullWidth` toggle × `align` settings → 36 cases, covered by an `it.each` table).
|
||||
|
||||
### Telemetry
|
||||
|
||||
`getEmailTemplatesInstruments()` lazily constructs a meter + four instruments on first call. Constructor caches the meter; the test pattern follows `email-processing` — install an in-memory metric exporter in `tests/setup` and assert recorded series.
|
||||
|
||||
### Schemas
|
||||
|
||||
Zod schemas live next to types (`*.types.ts` ships TS types; `*.schemas.ts` ships Zod where runtime validation is needed). `EmailButton.variant` ∈ `['primary','secondary','outline']`, `EmailButton.size` ∈ `['sm','md','lg']`, `HeadingLevel` ∈ `[1..6]`, `NotificationLevel` ∈ `['info','success','warning','error']`. Validation failures throw `EmailTemplatesError(INVALID_OPTIONS, ...)`.
|
||||
@@ -0,0 +1,206 @@
|
||||
# OpenSpec Change: enterprise-email-templates
|
||||
|
||||
- **Change ID**: enterprise-email-templates
|
||||
- **Package**: `@suaveplan/email-templates`
|
||||
- **Category**: communication / emails
|
||||
- **Target path**: `packages/communication/emails/email-templates`
|
||||
- **Status**: IN PROGRESS
|
||||
- **Date**: 2026-05-25
|
||||
- **Reference spec**: `/mnt/s/web/suaveplan/enterprise/email-templates.md`
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
Deliver `@suaveplan/email-templates` on genesis as a universal-tier, **React-free** email template engine. Upstream ships JSX components rendered via `react-dom/server`; the genesis rebuild honours enterprise spec §3 ("Zero browser / Node / React dependencies — pure TypeScript, runs in Bun, Node, and browser") by re-implementing the full upstream surface as **VNode factories** (`{ tag, attrs, children }`) walked by a pure-string HTML renderer.
|
||||
|
||||
The full public surface is preserved: nine reusable components (`EmailLayout`, `EmailContainer`, `EmailHeading`, `EmailText`, `EmailLink`, `EmailImage`, `EmailDivider`, `EmailButton`, `EmailFooter`), five built-in templates (`welcome`, `verification`, `password-reset`, `notification`, `invoice`), a typed `TemplateRegistry`, fluent `TemplateBuilder`, theming primitives (`defaultTheme` / `createTheme` / `mergeThemes`), the `createEmailMessage` adapter, and renderer helpers (`renderToHtml`, `wrapInDocument`, `resolveSubject`, `escapeHtml`, `stripHtml`). Genesis adds structured `EmailTemplatesError` codes, Zod-validated public schemas, injectable `Clock` (to remove `new Date().getFullYear()` at module scope inside the footer), and OTel instruments on every render.
|
||||
|
||||
---
|
||||
|
||||
## Current-state audit (genesis)
|
||||
|
||||
The package does not exist on genesis yet. Upstream lives at `/mnt/s/web/suaveplan/packages/universal/email-templates/` (73 files, 4,949 LOC, React 19 runtime dep, 100% coverage). Every consumer presently imports JSX-returning `ComponentType`s; the genesis port must change the **component shape** from `ComponentType<P>` to `(props: P) => VNode` while keeping the same exported names.
|
||||
|
||||
---
|
||||
|
||||
## Available workspace deps on genesis
|
||||
|
||||
| Package | Role |
|
||||
|---|---|
|
||||
| `@suaveplan/error` | `EmailTemplatesError`; `EMAIL_TEMPLATES.*` code registry via `defineCodes` |
|
||||
| `@suaveplan/types` | `Clock`, injectable for the footer copyright year |
|
||||
| `@suaveplan/opentelemetry` | Lazy meter accessor (sibling-package convention) |
|
||||
| `@opentelemetry/api` (`catalog:observability`) | Counters + histogram |
|
||||
| `zod` (`catalog:forms`) | Public-input validation |
|
||||
| `tslib` (`catalog:build`) | Runtime helpers |
|
||||
|
||||
Dev deps: `@suaveplan/testing` (runner wrapper), `@vitest/coverage-istanbul`, `vitest`, `vite`, `vite-plugin-dts`.
|
||||
|
||||
---
|
||||
|
||||
## Public API surface (React-stripped)
|
||||
|
||||
### VNode core
|
||||
|
||||
```ts
|
||||
export interface VNode {
|
||||
readonly tag: string; // 'table' | 'tr' | 'td' | 'a' | ...
|
||||
readonly attrs: Readonly<Record<string, string | number | undefined>>;
|
||||
readonly children: ReadonlyArray<VNode | string>;
|
||||
readonly self_closing?: boolean; // img, br, hr, meta
|
||||
}
|
||||
export type EmailNode = VNode | string;
|
||||
export type EmailChildren = EmailNode | ReadonlyArray<EmailNode>;
|
||||
|
||||
export function h(
|
||||
tag: string,
|
||||
attrs?: Record<string, string | number | undefined>,
|
||||
children?: EmailChildren,
|
||||
): VNode;
|
||||
```
|
||||
|
||||
### Components (factories returning `VNode`)
|
||||
|
||||
```ts
|
||||
EmailLayout(props: EmailLayoutProps): VNode
|
||||
EmailContainer(props: EmailContainerProps): VNode
|
||||
EmailHeading(props: EmailHeadingProps): VNode
|
||||
EmailText(props: EmailTextProps): VNode
|
||||
EmailLink(props: EmailLinkProps): VNode
|
||||
EmailImage(props: EmailImageProps): VNode
|
||||
EmailDivider(props: EmailDividerProps): VNode
|
||||
EmailButton(props: EmailButtonProps): VNode
|
||||
EmailFooter(props: EmailFooterProps): VNode
|
||||
```
|
||||
|
||||
Each prop shape is identical to upstream **except** `children` is now `EmailChildren` instead of `ReactNode`, and `style` is `Record<string, string | number>` instead of `CSSProperties`.
|
||||
|
||||
### Templates
|
||||
|
||||
```ts
|
||||
WelcomeEmail(props: WelcomeProps & { theme?: EmailTheme; clock?: Clock }): VNode
|
||||
VerificationEmail(props: VerificationProps & { theme?: EmailTheme; clock?: Clock }): VNode
|
||||
PasswordResetEmail(props: PasswordResetProps & { theme?: EmailTheme; clock?: Clock }): VNode
|
||||
NotificationEmail(props: NotificationProps & { theme?: EmailTheme; clock?: Clock }): VNode
|
||||
InvoiceEmail(props: InvoiceProps & { theme?: EmailTheme; clock?: Clock }): VNode
|
||||
|
||||
export const welcomeTemplate: EmailTemplate<WelcomeProps>;
|
||||
export const verificationTemplate: EmailTemplate<VerificationProps>;
|
||||
export const passwordResetTemplate:EmailTemplate<PasswordResetProps>;
|
||||
export const notificationTemplate: EmailTemplate<NotificationProps>;
|
||||
export const invoiceTemplate: EmailTemplate<InvoiceProps>;
|
||||
```
|
||||
|
||||
### Renderer / registry / builder / theme / message
|
||||
|
||||
```ts
|
||||
export interface EmailTemplate<TProps = unknown> {
|
||||
readonly name: string;
|
||||
readonly subject: string | ((props: TProps) => string);
|
||||
readonly component: (props: TProps & { theme?: EmailTheme; clock?: Clock }) => VNode;
|
||||
readonly defaultProps?: Partial<TProps>;
|
||||
}
|
||||
|
||||
export function renderToHtml<T>(template: EmailTemplate<T>, props: T, options?: RenderOptions): RenderResult;
|
||||
export function wrapInDocument(body: string, options?: HtmlDocumentOptions): string;
|
||||
export function resolveSubject<T>(template: EmailTemplate<T>, props: T): string;
|
||||
export function escapeHtml(str: string): string;
|
||||
export function stripHtml(html: string): string;
|
||||
export function renderVNode(node: EmailNode): string; // new — VNode → HTML
|
||||
|
||||
export class TemplateRegistry<TMap extends TemplateMap = TemplateMap> { /* register/get/has/list/search/remove/clear */ }
|
||||
export function createRegistry<T extends TemplateMap = TemplateMap>(opts?: RegistryOptions): TemplateRegistry<T>;
|
||||
|
||||
export class TemplateBuilder<TProps> { /* name / subject / component / defaultProps / build */ }
|
||||
export function createTemplateBuilder<TProps>(): TemplateBuilder<TProps>;
|
||||
|
||||
export const defaultTheme: EmailTheme;
|
||||
export function createTheme(opts?: EmailThemeOptions): EmailTheme;
|
||||
export function mergeThemes(base: EmailTheme, override: EmailThemeOptions): EmailTheme;
|
||||
|
||||
export function createEmailMessage<T>(
|
||||
template: EmailTemplate<T>,
|
||||
props: T,
|
||||
recipient: EmailRecipient,
|
||||
options?: CreateEmailMessageOptions,
|
||||
): EmailMessageResult;
|
||||
```
|
||||
|
||||
### Error codes
|
||||
|
||||
```ts
|
||||
EMAIL_TEMPLATES.INVALID_TEMPLATE
|
||||
EMAIL_TEMPLATES.INVALID_OPTIONS
|
||||
EMAIL_TEMPLATES.RENDER_FAILURE
|
||||
EMAIL_TEMPLATES.DUPLICATE_NAME
|
||||
EMAIL_TEMPLATES.UNKNOWN_TEMPLATE
|
||||
EMAIL_TEMPLATES.INVALID_HEADING_LEVEL
|
||||
```
|
||||
|
||||
### OTel instruments
|
||||
|
||||
- `email_templates.render_total{template,outcome}` — counter
|
||||
- `email_templates.render_duration_ms{template}` — histogram
|
||||
- `email_templates.registry_register_total{outcome}` — counter
|
||||
- `email_templates.validation_failure_total{reason}` — counter
|
||||
|
||||
---
|
||||
|
||||
## Genesis additions
|
||||
|
||||
1. **VNode renderer** — new `renderVNode` function walks the tree producing HTML with: HTML-encoded text (`&<>"'`), inline `style="..."` emission from object styles, MSO-conditional comments preserved from upstream `wrapInDocument`, self-closing for `img`/`br`/`hr`/`meta`.
|
||||
2. **Injectable `Clock`** — footer copyright year reads from `clock.now()` instead of `new Date().getFullYear()` at call time; default supplied if omitted.
|
||||
3. **Structured errors** — `EmailTemplatesError` extends `SuaveplanError` with six stable codes.
|
||||
4. **Zod schemas** — public input validation for `EmailButtonProps.variant/size`, heading level (1–6), notification level, footer link, registry options.
|
||||
5. **OTel instrumentation** — counters + histogram wired in `renderToHtml`, `TemplateRegistry.register`, and the validation pathway.
|
||||
6. **Structured-HTML test assertions** — tests use `htmlparser2` (added to a sensible catalog) to parse rendered output and assert tag structure / attributes — never raw string snapshots, never mocks.
|
||||
|
||||
---
|
||||
|
||||
## File layout
|
||||
|
||||
```text
|
||||
packages/communication/emails/email-templates/
|
||||
package.json
|
||||
tsconfig.lib.json
|
||||
vite.config.ts
|
||||
vitest.config.ts
|
||||
README.md
|
||||
src/
|
||||
index.ts
|
||||
error-codes/{error-codes.ts, error-codes.test.ts, error-codes.md, index.ts}
|
||||
telemetry/{telemetry.ts, telemetry.test.ts, telemetry.md, index.ts}
|
||||
vnode/{vnode.ts, vnode.test.ts, vnode.md, vnode.types.ts, index.ts}
|
||||
theme/{theme.ts, theme.test.ts, theme.md, theme.types.ts, index.ts}
|
||||
renderer/{renderer.ts, renderer.test.ts, renderer.md, renderer.types.ts, index.ts}
|
||||
message/{message.ts, message.test.ts, message.md, message.types.ts, index.ts}
|
||||
template-builder/{template-builder.ts, template-builder.test.ts, template-builder.md, template-builder.types.ts, index.ts}
|
||||
template-registry/{template-registry.ts, template-registry.test.ts, template-registry.md, template-registry.types.ts, index.ts}
|
||||
components/
|
||||
email-layout/{email-layout.ts, email-layout.test.ts, email-layout.md, email-layout.types.ts, index.ts}
|
||||
email-container/{...}
|
||||
email-heading/{...}
|
||||
email-text/{...}
|
||||
email-link/{...}
|
||||
email-image/{...}
|
||||
email-divider/{...}
|
||||
email-button/{...}
|
||||
email-footer/{...}
|
||||
templates/
|
||||
welcome/{welcome.ts, welcome.test.ts, welcome.md, welcome.types.ts, index.ts}
|
||||
verification/{...}
|
||||
password-reset/{...}
|
||||
notification/{...}
|
||||
invoice/{...}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Affected dependents
|
||||
|
||||
None on genesis yet — `emailer`/`campaigns` consume their own minimal templating today; they may opt in to this package post-archive.
|
||||
|
||||
## Workspace dep prerequisites
|
||||
|
||||
`@suaveplan/error`, `@suaveplan/types`, `@suaveplan/opentelemetry`. All ✅ on `genesis`.
|
||||
@@ -0,0 +1,312 @@
|
||||
<!-- markdownlint-disable MD024 -->
|
||||
|
||||
# Capability Spec Delta: email-templates
|
||||
|
||||
**Package**: `@suaveplan/email-templates`
|
||||
**Status**: PROPOSED
|
||||
|
||||
> Every requirement carries a `**Verified by:**` line at authoring time.
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Error code registry
|
||||
|
||||
The package SHALL declare `EMAIL_TEMPLATES_CODES` via `defineCodes("EMAIL_TEMPLATES", [...])` covering `INVALID_TEMPLATE`, `INVALID_OPTIONS`, `RENDER_FAILURE`, `DUPLICATE_NAME`, `UNKNOWN_TEMPLATE`, `INVALID_HEADING_LEVEL`. A `EmailTemplatesError` class SHALL extend `SuaveplanError<EmailTemplatesCode>` and tag itself with `name === "EmailTemplatesError"`.
|
||||
|
||||
#### Scenario: every code is namespaced
|
||||
|
||||
- **WHEN** `EMAIL_TEMPLATES_CODES.INVALID_TEMPLATE` is read
|
||||
- **THEN** the value equals `"EMAIL_TEMPLATES.INVALID_TEMPLATE"` and every other declared code resolves to its dotted form.
|
||||
|
||||
#### Scenario: error preserves cause
|
||||
|
||||
- **WHEN** `new EmailTemplatesError(EMAIL_TEMPLATES_CODES.RENDER_FAILURE, "key", { cause: new Error("boom") })` is constructed
|
||||
- **THEN** `err.name === "EmailTemplatesError"`, `err.code === "EMAIL_TEMPLATES.RENDER_FAILURE"`, `(err.cause as Error).message === "boom"`.
|
||||
|
||||
**Verified by:** `src/error-codes/error-codes.test.ts::"exposes every code with namespaced value"` AND `src/error-codes/error-codes.test.ts::"EmailTemplatesError preserves cause"`.
|
||||
|
||||
---
|
||||
|
||||
### Requirement: VNode core and HTML renderer
|
||||
|
||||
The package SHALL expose a `VNode` interface `{ tag, attrs, children, self_closing? }`, a hyperscript factory `h(tag, attrs?, children?)`, and a `renderVNode(node)` function that returns a string. Text children MUST be HTML-escaped (`& < > " '`). Attribute values of `undefined` MUST be skipped. Object-valued `style` attributes MUST be serialised to inline CSS `key:value;...`. Self-closing tags (`img`, `br`, `hr`, `meta`) MUST emit `<tag ... />`.
|
||||
|
||||
#### Scenario: text escape
|
||||
|
||||
- **WHEN** `renderVNode(h("p", {}, "1 < 2 & x"))` is called
|
||||
- **THEN** the output equals `<p>1 < 2 & x</p>`.
|
||||
|
||||
#### Scenario: undefined attr skipped
|
||||
|
||||
- **WHEN** `renderVNode(h("a", { href: "https://x", title: undefined }, "L"))` is called
|
||||
- **THEN** the output contains `href="https://x"` and does NOT contain the word `title`.
|
||||
|
||||
#### Scenario: style object inlined
|
||||
|
||||
- **WHEN** `renderVNode(h("p", { style: { color: "red", padding: "4px" } }, "x"))` is called
|
||||
- **THEN** the output contains `style="color:red;padding:4px"`.
|
||||
|
||||
#### Scenario: self-closing img
|
||||
|
||||
- **WHEN** `renderVNode(h("img", { src: "a.png", alt: "x" }, [], { selfClosing: true }))` is called
|
||||
- **THEN** the output equals `<img src="a.png" alt="x" />`.
|
||||
|
||||
**Verified by:** `src/vnode/vnode.test.ts::"escapes text content"` AND `src/vnode/vnode.test.ts::"skips undefined attributes"` AND `src/vnode/vnode.test.ts::"inlines style object"` AND `src/vnode/vnode.test.ts::"emits self-closing img"`.
|
||||
|
||||
---
|
||||
|
||||
### Requirement: Theme system
|
||||
|
||||
The package SHALL export `defaultTheme: EmailTheme`, `createTheme(options?)`, and `mergeThemes(base, override)`. `defaultTheme.colors.primary === "#2563eb"`. `createTheme` MUST deep-merge into the defaults. `mergeThemes` MUST shallow-merge each section (colors / typography / spacing / branding) into the base.
|
||||
|
||||
#### Scenario: defaults are present
|
||||
|
||||
- **WHEN** `defaultTheme.spacing.md` is read
|
||||
- **THEN** the value equals `"16px"`.
|
||||
|
||||
#### Scenario: custom theme override
|
||||
|
||||
- **WHEN** `createTheme({ colors: { primary: "#ff0000" } }).colors.primary` is read
|
||||
- **THEN** the value equals `"#ff0000"` and `defaultTheme.colors.primary` is unchanged.
|
||||
|
||||
**Verified by:** `src/theme/theme.test.ts::"exposes default spacing"` AND `src/theme/theme.test.ts::"createTheme overrides colors"`.
|
||||
|
||||
---
|
||||
|
||||
### Requirement: EmailLayout component
|
||||
|
||||
The package SHALL export `EmailLayout(props)` returning a `VNode` rendering a `<table>` wrapper with the theme's muted background, a centred max-width inner `<table>`, and an optional preview-text `<div>` with `display:none;max-height:0;overflow:hidden`.
|
||||
|
||||
#### Scenario: preview block rendered
|
||||
|
||||
- **WHEN** `renderVNode(EmailLayout({ preview: "Hi", children: "body" }))` is parsed by htmlparser2
|
||||
- **THEN** a `<div>` with `style` containing `display:none` whose text equals `Hi` is present.
|
||||
|
||||
**Verified by:** `src/components/email-layout/email-layout.test.ts::"emits preview block when preview prop set"`.
|
||||
|
||||
---
|
||||
|
||||
### Requirement: EmailContainer component
|
||||
|
||||
The package SHALL export `EmailContainer(props)` rendering a `<table>` with a single `<td>` whose `padding` defaults to `theme.spacing.md`, optional `background`, and `align` defaulting to `"left"`.
|
||||
|
||||
#### Scenario: background applied
|
||||
|
||||
- **WHEN** `renderVNode(EmailContainer({ background: "#f00", children: "x" }))` is parsed
|
||||
- **THEN** the rendered `<td>` has `style` containing `background-color:#f00` (or `backgroundColor:#f00`).
|
||||
|
||||
**Verified by:** `src/components/email-container/email-container.test.ts::"applies background colour"`.
|
||||
|
||||
---
|
||||
|
||||
### Requirement: EmailHeading component
|
||||
|
||||
`EmailHeading(props)` SHALL render an `<h1>`…`<h6>` element matching `props.level` (default `1`), with theme-aware font sizing keyed by level. Invalid levels (`< 1`, `> 6`, non-integer) MUST throw `EmailTemplatesError(INVALID_HEADING_LEVEL)`.
|
||||
|
||||
#### Scenario: level 2 renders h2
|
||||
|
||||
- **WHEN** `renderVNode(EmailHeading({ level: 2, children: "Title" }))` is parsed
|
||||
- **THEN** the root element name equals `h2` and its text equals `Title`.
|
||||
|
||||
#### Scenario: invalid level rejected
|
||||
|
||||
- **WHEN** `EmailHeading({ level: 7 as any, children: "x" })` is called
|
||||
- **THEN** the call throws `EmailTemplatesError` with `code === EMAIL_TEMPLATES.INVALID_HEADING_LEVEL`.
|
||||
|
||||
**Verified by:** `src/components/email-heading/email-heading.test.ts::"renders the requested heading level"` AND `src/components/email-heading/email-heading.test.ts::"rejects invalid level"`.
|
||||
|
||||
---
|
||||
|
||||
### Requirement: EmailText component
|
||||
|
||||
`EmailText(props)` SHALL render a `<p>` element. Variants (`body` / `caption` / `lead`) MUST set distinct `font-size` + `line-height`. `muted = true` MUST use `theme.colors.mutedForeground`.
|
||||
|
||||
#### Scenario: caption variant size
|
||||
|
||||
- **WHEN** `renderVNode(EmailText({ variant: "caption", children: "x" }))` is parsed
|
||||
- **THEN** the `<p>` has `style` containing `13px`.
|
||||
|
||||
**Verified by:** `src/components/email-text/email-text.test.ts::"applies caption variant size"`.
|
||||
|
||||
---
|
||||
|
||||
### Requirement: EmailLink component
|
||||
|
||||
`EmailLink(props)` SHALL render an `<a>` with `target="_blank"`, `rel="noopener noreferrer"`, and `text-decoration: underline` by default. `underline: false` MUST emit `text-decoration: none`.
|
||||
|
||||
#### Scenario: rel attribute
|
||||
|
||||
- **WHEN** `renderVNode(EmailLink({ href: "https://x", children: "x" }))` is parsed
|
||||
- **THEN** the `<a>` has `rel="noopener noreferrer"`.
|
||||
|
||||
**Verified by:** `src/components/email-link/email-link.test.ts::"sets safe rel attribute"`.
|
||||
|
||||
---
|
||||
|
||||
### Requirement: EmailImage component
|
||||
|
||||
`EmailImage(props)` SHALL render a wrapping `<table>` plus `<img>` with `display:block`, `max-width:100%`, and `border:0`. `alt` is required.
|
||||
|
||||
#### Scenario: alt rendered
|
||||
|
||||
- **WHEN** `renderVNode(EmailImage({ src: "a.png", alt: "logo" }))` is parsed
|
||||
- **THEN** the `<img>` has `alt="logo"`.
|
||||
|
||||
**Verified by:** `src/components/email-image/email-image.test.ts::"renders alt attribute"`.
|
||||
|
||||
---
|
||||
|
||||
### Requirement: EmailDivider component
|
||||
|
||||
`EmailDivider(props)` SHALL render a `<table>` whose `<td>` carries `border-top: 1px solid` with the configured colour (default `theme.colors.border`).
|
||||
|
||||
#### Scenario: colour override
|
||||
|
||||
- **WHEN** `renderVNode(EmailDivider({ color: "#abcdef" }))` is parsed
|
||||
- **THEN** the `<td>` style contains `1px solid #abcdef`.
|
||||
|
||||
**Verified by:** `src/components/email-divider/email-divider.test.ts::"applies colour override"`.
|
||||
|
||||
---
|
||||
|
||||
### Requirement: EmailButton component
|
||||
|
||||
`EmailButton(props)` SHALL render a `<table>` containing an `<a>` styled as a CTA. Variants (`primary` / `secondary` / `outline`) MUST produce distinct background / border combinations. Sizes (`sm` / `md` / `lg`) MUST select distinct padding + font-size. `fullWidth` MUST emit `width: 100%`. Invalid variant or size MUST throw `EmailTemplatesError(INVALID_OPTIONS)`.
|
||||
|
||||
#### Scenario: outline variant has transparent background
|
||||
|
||||
- **WHEN** `renderVNode(EmailButton({ href: "https://x", children: "Go", variant: "outline" }))` is parsed
|
||||
- **THEN** the `<a>` style contains `transparent`.
|
||||
|
||||
#### Scenario: invalid variant rejected
|
||||
|
||||
- **WHEN** `EmailButton({ href: "https://x", children: "x", variant: "ghost" as any })` is called
|
||||
- **THEN** the call throws `EmailTemplatesError` with `code === EMAIL_TEMPLATES.INVALID_OPTIONS`.
|
||||
|
||||
**Verified by:** `src/components/email-button/email-button.test.ts::"renders outline variant"` AND `src/components/email-button/email-button.test.ts::"rejects invalid variant"`.
|
||||
|
||||
---
|
||||
|
||||
### Requirement: EmailFooter component with injectable clock
|
||||
|
||||
`EmailFooter(props)` SHALL render a footer block with company name, optional address, optional link row, and an optional unsubscribe link. The copyright year MUST be derived from a `clock: Clock` prop (default: real wall-clock); the footer MUST NOT call `new Date()` at module scope.
|
||||
|
||||
#### Scenario: clock controls year
|
||||
|
||||
- **WHEN** `renderVNode(EmailFooter({ clock: { now: () => 1735689600000 } as Clock }))` is parsed (i.e. 2025-01-01)
|
||||
- **THEN** the footer text contains `2025`.
|
||||
|
||||
#### Scenario: unsubscribe link present
|
||||
|
||||
- **WHEN** `renderVNode(EmailFooter({ unsubscribeUrl: "https://x/unsub" }))` is parsed
|
||||
- **THEN** an `<a>` with `href="https://x/unsub"` whose text equals `Unsubscribe` is present.
|
||||
|
||||
**Verified by:** `src/components/email-footer/email-footer.test.ts::"derives year from injected clock"` AND `src/components/email-footer/email-footer.test.ts::"emits unsubscribe link"`.
|
||||
|
||||
---
|
||||
|
||||
### Requirement: Renderer helpers
|
||||
|
||||
The package SHALL export `escapeHtml`, `stripHtml`, `resolveSubject`, `wrapInDocument`, and `renderToHtml`. `wrapInDocument(body, { title, previewText, lang, dir })` MUST emit `<!DOCTYPE html>` + `<html lang="..." dir="...">` + a `<head>` with `meta charset="utf-8"`, viewport meta, X-UA-Compatible meta, MSO conditional comment, and `<title>`. `renderToHtml(template, props, options)` MUST compose the template's VNode through `wrapInDocument`, produce a `RenderResult { html, text, subject }`, and emit OTel render counter + duration histogram tagged by `template` and `outcome`. Optional `minify: true` MUST collapse whitespace between tags.
|
||||
|
||||
#### Scenario: doctype emitted
|
||||
|
||||
- **WHEN** `wrapInDocument("<p>x</p>")` is called
|
||||
- **THEN** the output starts with `<!DOCTYPE html>`.
|
||||
|
||||
#### Scenario: end-to-end render of welcome template
|
||||
|
||||
- **WHEN** `renderToHtml(welcomeTemplate, { recipientName: "Jane", ctaUrl: "https://x" })` is called
|
||||
- **THEN** the result's `html` parses to a document with an `<h1>` whose text contains `Welcome`, the `text` is non-empty, and the `subject` contains `Welcome`.
|
||||
|
||||
**Verified by:** `src/renderer/renderer.test.ts::"wrapInDocument emits doctype"` AND `src/renderer/renderer.test.ts::"renderToHtml composes welcome template"`.
|
||||
|
||||
---
|
||||
|
||||
### Requirement: TemplateRegistry
|
||||
|
||||
`TemplateRegistry` SHALL provide `register`, `get`, `has`, `list`, `search`, `remove`, `clear`, and a `size` getter. Registering with an empty name MUST throw `EmailTemplatesError(INVALID_TEMPLATE)`. `search({ name, category, tags, author })` MUST match by partial name (case-insensitive), exact category, any-tag intersection, and exact author. `register()` MUST emit an OTel counter tagged by outcome.
|
||||
|
||||
#### Scenario: register and retrieve
|
||||
|
||||
- **WHEN** `r.register("welcome", welcomeTemplate); r.get("welcome")` is called
|
||||
- **THEN** the returned value is `welcomeTemplate`.
|
||||
|
||||
#### Scenario: search by tag
|
||||
|
||||
- **WHEN** two templates are registered with `tags: ["a"]` and `tags: ["b"]` and `r.search({ tags: ["b"] })` is called
|
||||
- **THEN** the result has length `1`.
|
||||
|
||||
**Verified by:** `src/template-registry/template-registry.test.ts::"registers and retrieves a template"` AND `src/template-registry/template-registry.test.ts::"filters search by tag"`.
|
||||
|
||||
---
|
||||
|
||||
### Requirement: TemplateBuilder
|
||||
|
||||
`TemplateBuilder<T>` SHALL provide fluent `name`, `subject`, `component`, `defaultProps`, and `build` methods. `build()` MUST throw `EmailTemplatesError(INVALID_TEMPLATE)` if `name`, `subject`, or `component` is missing.
|
||||
|
||||
#### Scenario: incomplete build rejected
|
||||
|
||||
- **WHEN** `createTemplateBuilder<{ a: string }>().name("x").build()` is called
|
||||
- **THEN** the call throws `EmailTemplatesError` with `code === EMAIL_TEMPLATES.INVALID_TEMPLATE`.
|
||||
|
||||
**Verified by:** `src/template-builder/template-builder.test.ts::"rejects incomplete build"`.
|
||||
|
||||
---
|
||||
|
||||
### Requirement: createEmailMessage adapter
|
||||
|
||||
`createEmailMessage(template, props, recipient, options?)` SHALL combine the render result with the recipient envelope returning `{ to, from?, cc?, bcc?, replyTo?, subject, html, text }`.
|
||||
|
||||
#### Scenario: recipient + render merge
|
||||
|
||||
- **WHEN** `createEmailMessage(welcomeTemplate, { recipientName: "J", ctaUrl: "https://x" }, { to: "j@x.test", from: "me@x.test" })` is called
|
||||
- **THEN** the result `.to === "j@x.test"`, `.from === "me@x.test"`, and `.subject` contains `Welcome`.
|
||||
|
||||
**Verified by:** `src/message/message.test.ts::"merges recipient envelope with render result"`.
|
||||
|
||||
---
|
||||
|
||||
### Requirement: Five built-in templates
|
||||
|
||||
The package SHALL export `welcomeTemplate`, `verificationTemplate`, `passwordResetTemplate`, `notificationTemplate`, `invoiceTemplate`. Each MUST be a complete `EmailTemplate<TProps>` with `name`, `subject`, and `component`. Rendering each one with valid props MUST produce a parseable HTML document.
|
||||
|
||||
#### Scenario: welcome renders with CTA
|
||||
|
||||
- **WHEN** `renderToHtml(welcomeTemplate, { recipientName: "Jane", ctaUrl: "https://x" })` is parsed
|
||||
- **THEN** an `<a>` with `href="https://x"` is present in the rendered document.
|
||||
|
||||
#### Scenario: invoice renders line items
|
||||
|
||||
- **WHEN** `renderToHtml(invoiceTemplate, { recipientName: "J", invoiceNumber: "001", invoiceDate: "2026-01-01", items: [{ description: "Widget", quantity: 2, unitPrice: 10, total: 20 }], subtotal: 20, total: 20 })` is parsed
|
||||
- **THEN** the rendered document contains a `<td>` whose text equals `Widget`.
|
||||
|
||||
#### Scenario: verification renders code block
|
||||
|
||||
- **WHEN** `renderToHtml(verificationTemplate, { recipientName: "J", verificationUrl: "https://x", code: "ABC123" })` is parsed
|
||||
- **THEN** a `<p>` whose text contains `ABC123` is present.
|
||||
|
||||
#### Scenario: notification level styling
|
||||
|
||||
- **WHEN** `renderToHtml(notificationTemplate, { recipientName: "J", title: "Heads up", message: "x", level: "warning" })` is parsed
|
||||
- **THEN** the rendered document contains the warning palette colour (e.g. `#d97706` or its background partner `#fffbeb`).
|
||||
|
||||
#### Scenario: password reset includes expiry
|
||||
|
||||
- **WHEN** `renderToHtml(passwordResetTemplate, { recipientName: "J", resetUrl: "https://x", expiresInMinutes: 30 })` is parsed
|
||||
- **THEN** the rendered document contains the substring `30 minutes`.
|
||||
|
||||
**Verified by:** `src/templates/welcome/welcome.test.ts::"renders CTA link"` AND `src/templates/invoice/invoice.test.ts::"renders line-item rows"` AND `src/templates/verification/verification.test.ts::"renders verification code"` AND `src/templates/notification/notification.test.ts::"applies level palette"` AND `src/templates/password-reset/password-reset.test.ts::"renders expiry notice"`.
|
||||
|
||||
---
|
||||
|
||||
### Requirement: OTel instruments
|
||||
|
||||
The package SHALL lazily construct a meter `@suaveplan/email-templates` exposing `render_total`, `render_duration_ms`, `registry_register_total`, and `validation_failure_total` instruments. The instrument accessor MUST cache and return the same instance on repeated calls.
|
||||
|
||||
#### Scenario: instruments cached
|
||||
|
||||
- **WHEN** `getEmailTemplatesInstruments()` is called twice
|
||||
- **THEN** both calls return the same object reference.
|
||||
|
||||
**Verified by:** `src/telemetry/telemetry.test.ts::"caches the instrument set"`.
|
||||
@@ -0,0 +1,73 @@
|
||||
# Tasks: enterprise-email-templates
|
||||
|
||||
**Change ID**: enterprise-email-templates
|
||||
**Package**: `@suaveplan/email-templates`
|
||||
**Target path**: `packages/communication/emails/email-templates`
|
||||
|
||||
---
|
||||
|
||||
## 0. Pre-flight (non-negotiable)
|
||||
|
||||
- [x] 0.1 `pwd && git worktree list && git status` clean.
|
||||
- [x] 0.2 Sync to base SHA `cd3e462c436722e86c150dce144efffd91195495`.
|
||||
- [x] 0.3 Read enterprise spec + every upstream source file.
|
||||
|
||||
## 1. Scaffold
|
||||
|
||||
- [x] 1.1 Create `packages/communication/emails/email-templates/` with `src/` + feature subdirs.
|
||||
- [x] 1.2 `package.json` 0.1.0, `type: module`, `sideEffects: false`, exports map per feature.
|
||||
- [x] 1.3 `tsconfig.lib.json` extending `../../../../tsconfig.base.json`.
|
||||
- [x] 1.4 `vite.config.ts` (multi-entry build, externals).
|
||||
- [x] 1.5 `vitest.config.ts` (forks, istanbul, 100% thresholds).
|
||||
- [x] 1.6 `README.md`.
|
||||
|
||||
## 2. Foundation modules
|
||||
|
||||
- [x] 2.1 `src/error-codes/error-codes.{ts,test.ts,md,index.ts}` — six EMAIL_TEMPLATES codes + EmailTemplatesError.
|
||||
- [x] 2.2 `src/telemetry/telemetry.{ts,test.ts,md,index.ts}` — meter + four instruments.
|
||||
- [x] 2.3 `src/vnode/vnode.{ts,test.ts,md,types.ts,index.ts}` — `h()`, `renderVNode`, escape helpers.
|
||||
- [x] 2.4 `src/theme/theme.{ts,test.ts,md,types.ts,index.ts}` — defaultTheme, createTheme, mergeThemes.
|
||||
|
||||
## 3. Renderer + message + builder + registry
|
||||
|
||||
- [x] 3.1 `src/renderer/renderer.{ts,test.ts,md,types.ts,index.ts}` — `renderToHtml`, `wrapInDocument`, `resolveSubject`, `escapeHtml`, `stripHtml`.
|
||||
- [x] 3.2 `src/message/message.{ts,test.ts,md,types.ts,index.ts}` — `createEmailMessage`.
|
||||
- [x] 3.3 `src/template-builder/template-builder.{ts,test.ts,md,types.ts,index.ts}` — TemplateBuilder + createTemplateBuilder.
|
||||
- [x] 3.4 `src/template-registry/template-registry.{ts,test.ts,md,types.ts,index.ts}` — TemplateRegistry + createRegistry + search.
|
||||
|
||||
## 4. Components (nine)
|
||||
|
||||
- [x] 4.1 EmailLayout
|
||||
- [x] 4.2 EmailContainer
|
||||
- [x] 4.3 EmailHeading
|
||||
- [x] 4.4 EmailText
|
||||
- [x] 4.5 EmailLink
|
||||
- [x] 4.6 EmailImage
|
||||
- [x] 4.7 EmailDivider
|
||||
- [x] 4.8 EmailButton
|
||||
- [x] 4.9 EmailFooter (clock-injectable)
|
||||
|
||||
## 5. Templates (five)
|
||||
|
||||
- [x] 5.1 Welcome
|
||||
- [x] 5.2 Verification
|
||||
- [x] 5.3 PasswordReset
|
||||
- [x] 5.4 Notification
|
||||
- [x] 5.5 Invoice
|
||||
|
||||
## 6. Index barrel
|
||||
|
||||
- [x] 6.1 `src/index.ts` — named re-exports for full surface (no `export *`).
|
||||
|
||||
## 7. Gate
|
||||
|
||||
- [x] 7.1 `bunx turbo lint typecheck test build --filter=@suaveplan/email-templates` green.
|
||||
- [x] 7.2 `bunx turbo test:coverage --filter=@suaveplan/email-templates` ≥ 100/100/100/100.
|
||||
- [x] 7.3 `bun scripts/folder-reorg/generate-manifest.ts` refresh MANIFEST.
|
||||
- [x] 7.4 STATUS.md flip `–` → `✅` + counter.
|
||||
|
||||
## 8. OpenSpec finalisation
|
||||
|
||||
- [x] 8.1 Fold spec delta into `openspec/specs/email-templates/spec.md`.
|
||||
- [x] 8.2 Move folder to `openspec/archive/2026-05-25-enterprise-email-templates/`.
|
||||
- [x] 8.3 Conventional-commit on `feat/migrate-email-templates`.
|
||||
Reference in New Issue
Block a user