"use client"; import type { ComponentDocSpec } from "@/lib/design-system/component-doc-types"; import { EmailChipFieldDemo, EmailComposerOpenPreview, EmailMessagePreviewDemo, EmailRecipientsReviewDemo, } from "@/components/design-system/email-composer-previews"; function ex( section: Omit, children: React.ReactNode, description?: string, ) { return { ...section, children, description }; } export const emailComposerComponentDoc: ComponentDocSpec = { slug: "email-composer", summary: "One composer for every surface that emails people. A hub hands over a context, and the shared rail handles recipients, templates, merge fields, preview, send, schedule and test.", sections: [ ex( { id: "composer", title: "Composer" }, , "Toolbar, From and Reply to, To badges with Cc and Bcc, Subject with the Template menu, an email header, the message, an email footer, and Send with Schedule. It opens on Recipients when the selection has more than one group.", ), ex( { id: "recipients", title: "Recipients and options" }, , "Select Role, send mode, skip people already emailed, send me a copy, and a filterable list. Shown first only for more than one group.", ), ex( { id: "preview", title: "Message preview" }, , "The shared email layout. The composer Preview tab and the history rail both render through it.", ), ex( { id: "chips", title: "Address field" }, , "To, Cc, Bcc, From and Reply to hold people as badges. While idle the row shows as many as fit and folds the rest into a count.", ), ], anatomy: [ { part: "EmailComposerProvider", description: "Mounted once in the app shell. Owns the composer and history rails." }, { part: "useEmailComposer", description: "openComposer(context, handlers) and openHistory(context)." }, { part: "EmailComposerSheet", description: "The rail, built on the floating Sheet so the hub behind stays live.", slug: "floating-sheet-panel" }, { part: "EmailRecipientsReview", description: "First page for multi-group selections.", slug: "email-recipients-review" }, { part: "EmailChipField", description: "Address badges that fit the available width.", slug: "email-chip-field" }, { part: "EmailHeaderFooterPicker", description: "Email header and footer inside the message area.", slug: "email-header-footer" }, { part: "MergeTagInput and RichTextEditor", description: "Merge fields as badges, inserted with @ or the toolbar menu.", slug: "merge-tag-input" }, { part: "EmailMessagePreview", description: "The shared email layout.", slug: "email-message-preview" }, { part: "EmailAttachmentPreviewDialog", description: "Whole attachment tile opens a preview.", slug: "email-attachment-preview" }, ], api: [ { prop: "context", type: "EmailComposerContext", description: "Audiences, recipients with merge fields, templates per audience, merge fields, sender, brand, optional history." }, { prop: "onSend", type: "(payload) => void", description: "The hub delivers the email here. Confirm the outcome inline, never as a toast." }, { prop: "onSendTest", type: "(payload, toEmail) => void", description: "Adds Send test email when passed." }, { prop: "brand", type: "EmailBrand", description: "From useEmailBrand(): the active school avatar and the Exxat product lock-up." }, ], ux: { job: "Write one email to many people and be sure each person gets the right version before it goes out.", principles: ["P1", "P2", "P5", "P6", "P8"], modernReferences: ["Gmail compose (M4)", "Linear composer rail (M7)"], patternDoc: "apps/web/docs/email-composer-pattern.md", rulePath: ".cursor/rules/exxat-email-composer.mdc", whenToUse: [ "Any surface that emails students, faculty, preceptors, placements or schedules", "A bulk email where each person needs their own merge fields", ], whenNotToUse: [ "A single in-app message thread", "System notifications with no author (use a template sent by the server)", ], }, extraImports: [ { label: "App import", path: "@/components/templates/email-composer" }, { label: "Hub wiring", path: "@/hooks/use-email-hub-action" }, { label: "Brand", path: "@/lib/email/use-email-brand" }, ], relatedSlugs: ["floating-sheet-panel", "dialog", "attachment", "popover"], };