Initial Commit

packages/communication/emails/email-templates/src/components/email-divider/email-divider.md

@@ -0,0 +1,66 @@
+# email-divider
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+A horizontal divider rendered as a single-row `<table>` whose `<td>`
+carries `border-top: 1px solid <color>`. The table-with-border-top
+approach renders consistently across every email client — Outlook,
+Gmail, Apple Mail, Outlook.com, mobile clients — while a plain `<hr>`
+historically produced wildly different visual weights (some clients
+emitting a 1 px line, others a 2 px etched groove, still others a 3D
+ridge).
+
+## Features
+
+- Themed colour by default (`theme.colors.border`); per-divider override
+  via the `color` prop.
+- Margin top + bottom of `theme.spacing.md` baked in.
+- 1 px collapse-safe sizing (`font-size: 1px`, `line-height: 1px`)
+  prevents the empty cell from inflating the divider thickness in
+  clients that auto-fill empty `<td>` with the inherited font-size.
+
+## Usage: Basic
+
+```ts
+import { EmailDivider } from "@suaveplan/email-templates/components";
+import { renderVNode } from "@suaveplan/email-templates/vnode";
+
+renderVNode(EmailDivider({}));
+```
+
+## Usage: Advanced
+
+A coloured divider with extra top margin to separate two sections:
+
+```ts
+import { EmailDivider } from "@suaveplan/email-templates/components";
+import { renderVNode } from "@suaveplan/email-templates/vnode";
+
+renderVNode(EmailDivider({
+  color: "#22d3ee",
+  style: { "margin-top": "40px", "margin-bottom": "40px" },
+}));
+```
+
+## API Reference
+
+| Prop    | Type           | Description                                              |
+| ------- | -------------- | -------------------------------------------------------- |
+| `theme` | `EmailTheme?`  | Theme override (border colour, spacing).                 |
+| `color` | `string?`      | Explicit divider colour; overrides `theme.colors.border`. |
+| `style` | `StyleObject?` | Additional `<td>` inline styles.                         |
+
+## Implementation Notes
+
+The cell contains a single non-breaking space character (rendered as a
+literal space) to satisfy the few clients that collapse empty `<td>`
+into zero-height boxes. Combined with the 1 px font-size + line-height,
+the cell renders as the border alone — exactly 1 px tall.
+
+The `<table>` wrapper uses `width: 100%` so the divider spans whatever
+column it lives in. Vertical margins come from the table, not the cell,
+so the divider sits inside the layout's vertical rhythm correctly.