first commit

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

@@ -0,0 +1,83 @@
+# notification
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+The `notificationTemplate` is the generic system-notification email — a
+configurable severity callout suitable for product-health alerts,
+audit-trail events, account-status changes, and similar operational
+messages. The `level` prop drives both the accent border colour and the
+container background, giving recipients an at-a-glance severity cue.
+
+## Features
+
+- Four severity levels — `info`, `success`, `warning`, `error` — each
+  selecting a distinct accent / background colour pair.
+- Optional `timestamp` (rendered as a muted caption above the action).
+- Optional `action` button (`{ label, url }`).
+- Subject derives from the `title` prop.
+- Validation: unknown level raises `EmailTemplatesError(INVALID_OPTIONS)`
+  and bumps an OTel counter.
+
+## Usage: Basic
+
+```ts
+import { renderToHtml } from "@suaveplan/email-templates/renderer";
+import { notificationTemplate } from "@suaveplan/email-templates/templates";
+
+renderToHtml(notificationTemplate, {
+  recipientName: "Jane",
+  title: "Heads up",
+  message: "Your subscription renews tomorrow.",
+  level: "info",
+});
+```
+
+## Usage: Advanced
+
+A warning notification with a timestamp and a follow-up action:
+
+```ts
+import { renderToHtml } from "@suaveplan/email-templates/renderer";
+import { notificationTemplate } from "@suaveplan/email-templates/templates";
+
+renderToHtml(notificationTemplate, {
+  recipientName: "Jane",
+  title: "Failed login from a new device",
+  message: "We blocked an attempt from a device we don't recognise. If this was you, you can dismiss this message.",
+  level: "warning",
+  timestamp: "2026-05-25 14:32 UTC",
+  action: {
+    label: "Review device activity",
+    url: "https://app.example.test/security/devices",
+  },
+});
+```
+
+## API Reference
+
+| Symbol                  | Kind     | Description                                          |
+| ----------------------- | -------- | ---------------------------------------------------- |
+| `notificationTemplate`  | const    | `EmailTemplate<NotificationProps>`.                   |
+| `NotificationEmail`     | function | Component returning a `VNode`.                       |
+| `NotificationProps`     | type     | `{ recipientName, title, message, level?, action?, companyName?, timestamp? }` |
+| `NotificationLevel`     | type     | `"info" \| "success" \| "warning" \| "error"`.       |
+| `NotificationAction`    | type     | `{ label, url }`.                                    |
+
+## Implementation Notes
+
+The accent colour for `info`/`success`/`warning`/`error` resolves from
+the theme's colour palette (`primary` for info; `success`/`warning`/`error`
+respectively). The container background, however, is a fixed lighter
+tint per level — those values are not in the theme because they're
+visually-tuned washes specific to this template's callout pattern.
+Consumers wanting a theme-driven wash can override via `EmailContainer`
+directly.
+
+The accent-bar effect is achieved with a `<div>` carrying
+`border-left: 4px solid <accent>`. The bar lives inside the
+`EmailContainer` cell so the container's themed border-radius rounds the
+outer edges while the bar stays sharp.