---
description: Email composer — one shared template for every "email people" surface; contract, brand, templates, merge fields, recipients
globs: {components,lib,hooks,src}/**/*.{tsx,ts},ts}
alwaysApply: false
appliesTo: [react]
---

# Exxat DS — email composer

**Narrative:** `docs/exxat-ds/email-composer-pattern.md` · **Skill:** `exxat-email-composer` · **Agent:** `email-builder`

One composer for the whole product. It lives in `packages/ui/src/components/templates/email-*`
and is imported through `@/components/templates/email-composer`. A hub never builds email UI.

## MUST

1. **Open it, don't build it.** Use **`useEmailHubAction(getContext)`** (hub header action + inline confirmation) or **`useEmailComposer().openComposer(context, handlers)`**. The provider is mounted once in `AppShellContextProviders`.
2. **One contract.** A hub hands over an **`EmailComposerContext`** (audiences, recipients with merge `fields`, templates per audience, `mergeFields`, `sender`, `brand`, optional `history`). Mapping rows → context lives in **`lib/email/*-email-context.ts`**; start from `people-email-context.ts`.
3. **Brand from the shell.** Build it with **`useEmailBrand()`**: the active school avatar and the `ExxatProductLogo` lock-up, passed as slots (`brand.logo`, `brand.productLogo`). Never import a logo file or draw a placeholder.
4. **Merge fields** are `{{key}}` text in subject and body, drawn as badge chips (`RichTextEditor mergeFields`, `MergeTagInput`). Every field has a **label + description**; group related fields with `tone` 1–5. Inserted by **`@`** typeahead and the toolbar **Insert merge field** menu (search + description). Never plain-text tags.
5. **Templates** are per audience. Mark **one** `isDefault` (shows a **Default** tag; there is no "Mark as default" action). 7+ templates get search. Every template brings a **header and footer** (default: logo with name above, product logo below) unless it is the blank template.
6. **Recipients page** (`EmailRecipientsReview`) opens first **only** when the selection has more than one audience (placements, schedules). One audience goes straight to compose. Role and send-mode choices use **`SelectionTileGrid`** (`interaction="radio"`), no helper sentences.
7. **Send flow.** Confirm before sending (states the email count); **Send ▾ Schedule**; **Send test email** only when the hub passes `onSendTest`; unsaved edits ask to discard. Outcomes are **inline** (`LocalBanner`) — **no toast** (`exxat-no-toast.mdc`).
8. **Layering.** The rail is `z-[80]`: menus and popovers inside it use `z-properties-sheet-portal`, dialogs use `z-[90]`. Esc closes only the innermost layer (the `@` list, a menu, then the rail).
9. **A11y.** Merge chips are `role="button"` with an Enter-for-details hint; the details card is labelled, moves focus in and returns it. Attachments are whole-tile buttons that open a preview. Verify with `/a11y-ship`.
10. **Icons** are Font Awesome Pro `fa-light` from the kit subset (`exxat-fontawesome-icons.mdc`).

## MUST NOT

- Fork the composer, or add a per-hub email sheet, preview, or template list.
- Copy components from the `Email UX` source folder (it uses lucide and its own shell UI). Rebuild from DS primitives only.
- Put hub-specific fields into the package types; use `fields` and `records`.
- Hard-code colours or logos; use tokens and the shell's own logo components.
- Add a "Mark as default" control, a toast, or a Recipients page for a single audience.

## See also

- **`exxat-page-vs-drawer.mdc`** — the composer is a floating rail, the hub behind it stays live.
- **`exxat-reuse-before-custom.mdc`** · **`exxat-copy-discipline.mdc`** (template copy) · **`exxat-accessibility.mdc`**.
