first commit

2026-05-29 08:20:56 +01:00
commit 949299f58d
6368 changed files with 527176 additions and 0 deletions
--- a/docs/communication/emails/email-templates/src/components/email-image/email-image.md
+++ b/docs/communication/emails/email-templates/src/components/email-image/email-image.md
@@ -0,0 +1,85 @@
+# email-image
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+Renders an `<img>` inside a centring `<table>` with the canonical
+responsive-email defaults (`display:block`, `max-width:100%`,
+`border:0`, `outline:none`). The `alt` attribute is required — missing
+alt text breaks accessibility and triggers spam-filter heuristics in
+several large providers.
+
+The component is the right choice for hero images, illustrations, and
+inline graphics. For brand logos that benefit from MSO-specific
+fall-throughs, callers may render an additional `<v:image>` block
+wrapped in a `<!--[if mso]>` conditional via the renderer's `rawHtml`
+helper.
+
+## Features
+
+- Required `alt` prop (TypeScript will refuse to compile a missing alt).
+- Optional pixel `width` and `height` set as both HTML attributes and
+  CSS values for Outlook-on-desktop compatibility.
+- `display:block` removes the inline-baseline gap that produces a thin
+  border below the image in some clients.
+- `max-width:100%` makes images responsive — they scale down inside a
+  narrower container (mobile) but cap at their natural size on desktop.
+- Wrapper `<table>` honours the `align` prop (`center` by default).
+
+## Usage: Basic
+
+```ts
+import { EmailImage } from "@suaveplan/email-templates/components";
+import { renderVNode } from "@suaveplan/email-templates/vnode";
+
+renderVNode(EmailImage({
+  src: "https://cdn.example.test/hero.png",
+  alt: "A welcoming illustration",
+  width: 600,
+  height: 300,
+}));
+```
+
+## Usage: Advanced
+
+A left-aligned logo with rounded corners:
+
+```ts
+import { EmailImage } from "@suaveplan/email-templates/components";
+import { renderVNode } from "@suaveplan/email-templates/vnode";
+
+renderVNode(EmailImage({
+  src: "https://cdn.example.test/logo.png",
+  alt: "Acme",
+  width: 120,
+  height: 40,
+  align: "left",
+  style: { "border-radius": "4px" },
+}));
+```
+
+## API Reference
+
+| Prop      | Type                              | Description                                          |
+| --------- | --------------------------------- | ---------------------------------------------------- |
+| `src`     | `string`                          | Image URL.                                           |
+| `alt`     | `string`                          | Accessible alt text — required.                      |
+| `width`   | `number?`                         | Pixel width (HTML + CSS).                            |
+| `height`  | `number?`                         | Pixel height (HTML + CSS).                           |
+| `theme`   | `EmailTheme?`                     | Theme override (used for the bottom margin).         |
+| `align`   | `"left" \| "center" \| "right"`   | Cell alignment; defaults to `"center"`.              |
+| `style`   | `StyleObject?`                    | Additional `<img>` inline styles.                    |
+
+## Implementation Notes
+
+The `<img>` is wrapped in a single-row `<table>` because Outlook
+honours the table's `align` attribute reliably; CSS `text-align` on a
+plain `<img>` would behave inconsistently. The wrapping `<td>` carries
+the alignment hint while the `<img>` itself stays block-level.
+
+`width` and `height` set both the HTML attributes and the inline CSS
+because Outlook-on-Windows preserves the HTML attribute while modern
+clients use the CSS; the two values must agree.