first commit

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

@@ -0,0 +1,93 @@
+# invoice
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+The `invoiceTemplate` is the receipt / invoice / order-confirmation
+email. It renders a heading carrying the invoice number, a metadata line
+(date, optional due date), a line-items table with description /
+quantity / unit-price / total columns, a subtotal-tax-total summary, and
+an optional "Pay Now" CTA when `paymentUrl` is supplied.
+
+The template is intentionally generic — it does not assume a specific
+tax-jurisdiction or currency formatting; consumers pass pre-formatted
+strings (date, currency symbol) and pre-computed numbers (subtotal,
+tax, total). The template focuses on layout, not arithmetic.
+
+## Features
+
+- Line-items table with description, quantity, unit price, total columns.
+- Subtotal + optional tax + total summary at right-align.
+- Optional `paymentUrl` renders a "Pay Now" CTA.
+- Currency symbol is configurable (`currency` defaults to `"$"`).
+- Optional `dueDate` appears alongside the invoice date.
+
+## Usage: Basic
+
+```ts
+import { renderToHtml } from "@suaveplan/email-templates/renderer";
+import { invoiceTemplate } from "@suaveplan/email-templates/templates";
+
+renderToHtml(invoiceTemplate, {
+  recipientName: "Jane",
+  invoiceNumber: "INV-001",
+  invoiceDate: "2026-01-15",
+  items: [
+    { description: "Pro plan – Jan 2026", quantity: 1, unitPrice: 29, total: 29 },
+  ],
+  subtotal: 29,
+  total: 29,
+});
+```
+
+## Usage: Advanced
+
+A multi-line invoice with tax, a due date, a payment CTA, and a
+non-USD currency:
+
+```ts
+import { renderToHtml } from "@suaveplan/email-templates/renderer";
+import { invoiceTemplate } from "@suaveplan/email-templates/templates";
+
+renderToHtml(invoiceTemplate, {
+  recipientName: "Jane",
+  invoiceNumber: "INV-001",
+  invoiceDate: "2026-01-15",
+  dueDate: "2026-01-31",
+  currency: "€",
+  items: [
+    { description: "Pro plan – Jan 2026", quantity: 1, unitPrice: 29, total: 29 },
+    { description: "Add-on: extra seat",  quantity: 2, unitPrice:  5, total: 10 },
+  ],
+  subtotal: 39,
+  tax: 3.9,
+  total: 42.9,
+  paymentUrl: "https://billing.example.test/pay?invoice=INV-001",
+});
+```
+
+## API Reference
+
+| Symbol            | Kind     | Description                                          |
+| ----------------- | -------- | ---------------------------------------------------- |
+| `invoiceTemplate` | const    | `EmailTemplate<InvoiceProps>`.                        |
+| `InvoiceEmail`    | function | Component returning a `VNode`.                       |
+| `InvoiceProps`    | type     | `{ recipientName, invoiceNumber, invoiceDate, dueDate?, items, subtotal, tax?, total, currency?, paymentUrl?, companyName? }` |
+| `InvoiceLineItem` | type     | `{ description, quantity, unitPrice, total }`.       |
+
+## Implementation Notes
+
+Currency formatting uses `Number.prototype.toFixed(2)` — locale-agnostic
+two-decimal-place rendering. Consumers needing locale-aware grouping
+separators (e.g. `1,234.56` vs `1 234,56`) should pre-format the strings
+upstream; the template intentionally does not depend on `Intl.NumberFormat`
+because email-template environments span Node, Bun, and browsers where
+the Intl data sets vary.
+
+The line-items table renders a single `<tbody>` per call; the table
+header sits in its own `<thead>` so accessibility scanners report the
+correct table-with-headers structure even though most email clients
+ignore the distinction.