@dbx-tools/ui 0.0.0-stage → 0.9.61

package/src/branding/react/brand.tsx

@@ -0,0 +1,92 @@
+import { brandUtils } from "@dbx-tools/shared-core";
+import {
+  createContext,
+  type ImgHTMLAttributes,
+  type PropsWithChildren,
+  useContext,
+  useEffect,
+  useMemo,
+} from "react";
+import { applyBrandContext, type BrandAssetResolver, resolveBrandAsset } from "../browser.ts";
+
+interface BrandState {
+  context: brandUtils.BrandContext;
+  resolveAsset: BrandAssetResolver;
+}
+
+const BrandReactContext = createContext<BrandState>({
+  context: brandUtils.defaultBrandContext,
+  resolveAsset: resolveBrandAsset,
+});
+
+/** Brand input, asset resolver, and document-application behavior for {@link BrandProvider}. */
+export interface BrandProviderProps extends PropsWithChildren {
+  context?: brandUtils.BrandContextInput;
+  resolveAsset?: BrandAssetResolver;
+  applyToDocument?: boolean;
+}
+
+/** Provide a validated brand context to descendant React components. */
+export function BrandProvider({
+  children,
+  context,
+  resolveAsset = resolveBrandAsset,
+  applyToDocument = false,
+}: BrandProviderProps) {
+  const parsed = useMemo(() => brandUtils.parseBrandContext(context), [context]);
+  const value = useMemo(() => ({ context: parsed, resolveAsset }), [parsed, resolveAsset]);
+
+  useEffect(() => {
+    if (applyToDocument) applyBrandContext(parsed, { resolveAsset });
+  }, [applyToDocument, parsed, resolveAsset]);
+
+  return <BrandReactContext.Provider value={value}>{children}</BrandReactContext.Provider>;
+}
+
+/** Read the active validated brand context and asset resolver. */
+export function useBrand(): BrandState {
+  return useContext(BrandReactContext);
+}
+
+/** Image attributes and light/dark selection used by branded icons and logos. */
+export interface BrandImageProps extends Omit<ImgHTMLAttributes<HTMLImageElement>, "src" | "alt"> {
+  alt?: string;
+  mode?: "auto" | "light" | "dark";
+}
+
+function BrandImage({
+  asset,
+  alt,
+  mode = "auto",
+  ...props
+}: BrandImageProps & { asset: brandUtils.BrandAssetSet }) {
+  const { resolveAsset } = useBrand();
+  const light = resolveAsset(asset.light);
+  const dark = resolveAsset(asset.dark ?? asset.light);
+
+  if (mode !== "auto") {
+    return <img src={mode === "dark" ? dark : light} alt={alt ?? ""} {...props} />;
+  }
+  return (
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcSet={dark} />
+      <img src={light} alt={alt ?? ""} {...props} />
+    </picture>
+  );
+}
+
+/** Render the active brand icon with automatic light and dark assets. */
+export function BrandIcon(props: BrandImageProps) {
+  const { context } = useBrand();
+  const { alt, ...imageProps } = props;
+  return (
+    <BrandImage asset={context.assets.icon} alt={alt ?? `${context.name} icon`} {...imageProps} />
+  );
+}
+
+/** Render the active brand logo with automatic light and dark assets. */
+export function BrandLogo(props: BrandImageProps) {
+  const { context } = useBrand();
+  const { alt, ...imageProps } = props;
+  return <BrandImage asset={context.assets.logo} alt={alt ?? context.name} {...imageProps} />;
+}

package/src/branding/react/index.ts

@@ -0,0 +1,9 @@
+export {
+  BrandIcon,
+  BrandLogo,
+  BrandProvider,
+  useBrand,
+  type BrandImageProps,
+  type BrandProviderProps,
+} from "./brand.tsx";
+export type { BrandContext, BrandContextInput } from "@dbx-tools/shared-core";

package/src/branding/styles.css

@@ -0,0 +1,12 @@
+:root {
+  --brand-color-primary: #1b3139;
+  --brand-color-primary-hover: #0e538b;
+  --brand-color-accent: #00a972;
+  --brand-color-foreground: #1b3139;
+  --brand-color-background: #ffffff;
+  --brand-color-surface: #f9f7f4;
+  --brand-color-muted: #618794;
+  --brand-color-border: #e4e2dd;
+  --brand-font-sans: "DM Sans", ui-sans-serif, system-ui, sans-serif;
+  --brand-font-mono: "DM Mono", ui-monospace, SFMono-Regular, Menlo, monospace;
+}

package/src/email/react/email-approval-card.tsx

@@ -0,0 +1,169 @@
+import {
+  EmailCard,
+  emailBrandFromContext,
+  resolveEmailBrand,
+  type EmailBrand,
+} from "@dbx-tools/shared-email-template";
+import { CheckIcon, MailIcon, PaperclipIcon, XIcon } from "lucide-react";
+
+import { attachmentNames, joinAddresses, type EmailDraft } from "./fields.ts";
+import { useBrand } from "../../branding/react/index.ts";
+import { Button } from "../../react/index.ts";
+
+// Presentational pieces for an outbound email awaiting a human Approve /
+// Deny: a mail-client chrome (sender, recipients, subject, attachments)
+// around the shared React Email card, plus an approval card wrapping it.
+// State and the resolve transport belong to the caller; these components
+// only render and report intent. The editable counterpart is
+// `EmailComposeView` in `./email-compose`; both share `./fields` and
+// `./email-body`.
+
+export type { EmailDraft } from "./fields.ts";
+
+/** Props for {@link EmailPreview}. */
+export interface EmailPreviewProps {
+  email: EmailDraft;
+  /** Optional email-only brand. Defaults to the active `BrandProvider` context. */
+  brand?: EmailBrand;
+}
+
+/** Initials for the sender avatar when no logo is available. */
+function senderInitials(name: string): string {
+  const parts = name.trim().split(/\s+/).filter(Boolean);
+  if (parts.length === 0) return "?";
+  if (parts.length === 1) return parts[0]!.slice(0, 2).toUpperCase();
+  return `${parts[0]![0] ?? ""}${parts[1]![0] ?? ""}`.toUpperCase();
+}
+
+/** One muted "Label: value" row in the client chrome. */
+const ChromeRow = ({ label, value }: { label: string; value: string }) => (
+  <p className="truncate text-xs text-muted-foreground">
+    <span className="font-medium text-foreground/70">{label}</span> {value}
+  </p>
+);
+
+/**
+ * Render an email draft the way a mail client shows a received message: sender
+ * identity, recipients, subject, and attachment chips in chrome around the
+ * same branded React Email card used for delivery. Envelope fields stay out of
+ * the delivered HTML — they are transport metadata, not body content.
+ */
+export const EmailPreview = ({ email, brand }: EmailPreviewProps) => {
+  const { context } = useBrand();
+  const theme = resolveEmailBrand(brand ?? emailBrandFromContext(context));
+  const to = joinAddresses(email.to);
+  const cc = joinAddresses(email.cc);
+  const bcc = joinAddresses(email.bcc);
+  const subject = email.subject?.trim() || "Message";
+  const files = email.attachments?.map((att) => att.filename).filter(Boolean) ?? [];
+  const attachmentSummary = attachmentNames(email.attachments);
+
+  return (
+    <div className="overflow-hidden rounded-2xl border border-border bg-card shadow-sm">
+      <div className="space-y-3 border-b border-border bg-background px-4 py-3">
+        <div className="flex items-start gap-3">
+          <div
+            className="flex size-10 shrink-0 items-center justify-center rounded-full text-xs font-semibold"
+            style={{ backgroundColor: theme.accent, color: theme.onAccent }}
+            aria-hidden
+          >
+            {senderInitials(theme.name)}
+          </div>
+          <div className="min-w-0 flex-1 space-y-1">
+            <div className="flex items-baseline justify-between gap-3">
+              <div className="min-w-0">
+                <p className="truncate text-sm font-semibold text-foreground">{theme.name}</p>
+                {theme.website ? (
+                  <p className="truncate text-xs text-muted-foreground">{theme.website}</p>
+                ) : null}
+              </div>
+              <time className="shrink-0 text-xs text-muted-foreground">Just now</time>
+            </div>
+            {to ? <ChromeRow label="To" value={to} /> : null}
+            {cc ? <ChromeRow label="Cc" value={cc} /> : null}
+            {bcc ? <ChromeRow label="Bcc" value={bcc} /> : null}
+            <p className="pt-1 text-sm font-medium leading-snug text-foreground">{subject}</p>
+          </div>
+        </div>
+        {files.length > 0 ? (
+          <ul className="flex flex-wrap gap-1.5" aria-label={`Attachments: ${attachmentSummary}`}>
+            {files.map((filename) => (
+              <li
+                key={filename}
+                className="inline-flex max-w-full items-center gap-1.5 rounded-md border border-border bg-muted/40 px-2 py-1 text-xs text-foreground"
+              >
+                <PaperclipIcon className="size-3 shrink-0 text-muted-foreground" />
+                <span className="truncate">{filename}</span>
+              </li>
+            ))}
+          </ul>
+        ) : null}
+      </div>
+      <div style={{ backgroundColor: theme.surface }}>
+        <EmailCard subject={subject} body={email.body || ""} brand={theme} framed={false} />
+      </div>
+    </div>
+  );
+};
+
+/** Props for {@link EmailApprovalCard}. */
+export interface EmailApprovalCardProps {
+  email: EmailDraft;
+  /** Called when the user approves the send. */
+  onApprove?: () => void | Promise<void>;
+  /** Called when the user denies the send. */
+  onDeny?: () => void | Promise<void>;
+  /** Disable both actions while a decision is in flight. */
+  pending?: boolean;
+  /** Disable both actions regardless of pending state. */
+  disabled?: boolean;
+  /** Header label. Defaults to "Approval needed: send email". */
+  title?: string;
+}
+
+/**
+ * A drop-in approval card for the `send_email` tool: the email preview
+ * plus Approve / Deny actions. Wire `onApprove` / `onDeny` to whatever
+ * resumes the suspended tool call (e.g. the AI-SDK `addToolResult`).
+ */
+export const EmailApprovalCard = ({
+  email,
+  onApprove,
+  onDeny,
+  pending,
+  disabled,
+  title = "Approval needed: send email",
+}: EmailApprovalCardProps) => {
+  const blocked = Boolean(disabled) || Boolean(pending);
+  return (
+    <div className="not-prose my-2 rounded-md border border-warning/40 bg-warning/5 p-3">
+      <div className="mb-2 flex items-center gap-2 text-xs font-medium text-warning">
+        <MailIcon className="size-3.5" />
+        <span>{title}</span>
+      </div>
+      <EmailPreview email={email} />
+      <div className="mt-3 flex items-center gap-2">
+        <Button
+          type="button"
+          size="sm"
+          variant="default"
+          disabled={blocked || !onApprove}
+          onClick={() => onApprove?.()}
+        >
+          <CheckIcon className="size-3" />
+          Approve
+        </Button>
+        <Button
+          type="button"
+          size="sm"
+          variant="outline"
+          disabled={blocked || !onDeny}
+          onClick={() => onDeny?.()}
+        >
+          <XIcon className="size-3" />
+          Deny
+        </Button>
+      </div>
+    </div>
+  );
+};

package/src/email/react/email-body.tsx

@@ -0,0 +1,23 @@
+// Compact, muted Markdown renderer for an email body. Shared by the
+// read-only approval preview and the compose view's live preview so both
+// render the drafted Markdown identically (links, lists, emphasis, and
+// tables rather than raw syntax).
+
+import { EmailBody as SharedEmailBody, type EmailBrand } from "@dbx-tools/shared-email-template";
+import { cn } from "@dbx-tools/ui/react";
+
+/** Props for {@link EmailBody}. */
+export interface EmailBodyProps {
+  children: string;
+  /** Extra classes merged onto the prose container. */
+  className?: string;
+  /** Optional brand override; dbx-tools branding is the default. */
+  brand?: EmailBrand;
+}
+
+/** Render an email body with the same React Email component used for delivery. */
+export const EmailBody = ({ children, className, brand }: EmailBodyProps) => (
+  <div className={cn("max-w-none break-words", className)}>
+    <SharedEmailBody body={children} brand={brand} />
+  </div>
+);

package/src/email/react/email-compose.tsx

@@ -0,0 +1,346 @@
+import type { EmailAttachment, EmailMessage } from "@dbx-tools/shared-email";
+import { EyeIcon, PaperclipIcon, PencilIcon, SendIcon, XIcon } from "lucide-react";
+import { useCallback, useEffect, useId, useRef, useState, type ReactNode } from "react";
+
+import { EmailPreview } from "./email-approval-card.tsx";
+import { joinAddresses, parseAddresses, type EmailDraft } from "./fields.ts";
+import {
+  Button,
+  Input,
+  Label,
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+  Textarea,
+  cn,
+} from "../../react/index.ts";
+
+// A standard, editable email compose form usable outside a chat bubble
+// (a settings page, a standalone "send" view, etc.). It shares the
+// address / attachment helpers (`./fields`) and the React Email body
+// renderer (`./email-body`) with the read-only `EmailPreview`, so the
+// two surfaces stay visually and semantically in sync.
+//
+// The component is presentational and self-contained: it owns the draft
+// as local state (seeded from `defaultValue`), emits changes via
+// `onChange`, and hands the assembled `EmailMessage` (plus the chosen
+// `From`, when a sender list is provided) to `onSend`. Wiring the actual
+// dispatch - and fetching the `senders` list from the plugin's
+// `GET /senders` route - is the caller's job.
+
+/** Props for {@link EmailComposeView}. */
+export interface EmailComposeProps {
+  /** Initial draft to seed the form (uncontrolled thereafter). */
+  defaultValue?: EmailDraft;
+  /** Called on every edit with the current assembled message. */
+  onChange?: (message: EmailMessage) => void;
+  /** Called when the user submits; receives the message and chosen `From`. */
+  onSend?: (message: EmailMessage, from?: string) => void | Promise<void>;
+  /** Called when the user cancels. Omit to hide the Cancel button. */
+  onCancel?: () => void;
+  /**
+   * Permitted `From` addresses (e.g. from the plugin's `GET /senders`).
+   * When non-empty a `From` dropdown is shown and its value is passed to
+   * `onSend`; omit for a server-resolved sender (no dropdown).
+   */
+  senders?: string[];
+  /** Preselected `From`. Defaults to the first {@link senders} entry. */
+  defaultFrom?: string;
+  /** Disable actions while a send is in flight. */
+  pending?: boolean;
+  /** Disable all actions regardless of pending state. */
+  disabled?: boolean;
+  /** Show the attachment control. Defaults to `true`. */
+  allowAttachments?: boolean;
+  /** Card header label. Defaults to "New message". */
+  title?: string;
+  /** Submit button label. Defaults to "Send". */
+  sendLabel?: string;
+}
+
+/** Read a `File` into a base64 {@link EmailAttachment}. */
+async function fileToAttachment(file: File): Promise<EmailAttachment> {
+  const dataUrl = await new Promise<string>((resolve, reject) => {
+    const reader = new FileReader();
+    reader.onload = () => resolve(String(reader.result));
+    reader.onerror = () => reject(reader.error);
+    reader.readAsDataURL(file);
+  });
+  // A data URL is `data:<mime>;base64,<payload>`; keep only the payload.
+  const content = dataUrl.slice(dataUrl.indexOf(",") + 1);
+  return {
+    filename: file.name,
+    content,
+    encoding: "base64",
+    ...(file.type ? { contentType: file.type } : {}),
+  };
+}
+
+/** A labelled field row: label above its control. */
+const Field = ({
+  label,
+  htmlFor,
+  children,
+}: {
+  label: string;
+  htmlFor?: string;
+  children: ReactNode;
+}) => (
+  <div className="grid gap-1.5">
+    <Label htmlFor={htmlFor} className="text-xs text-muted-foreground">
+      {label}
+    </Label>
+    {children}
+  </div>
+);
+
+/**
+ * A standard, editable email compose form. Reuses the shared field and
+ * body helpers so a drafted message renders the same here as in the
+ * read-only approval preview.
+ */
+export const EmailComposeView = ({
+  defaultValue,
+  onChange,
+  onSend,
+  onCancel,
+  senders,
+  defaultFrom,
+  pending,
+  disabled,
+  allowAttachments = true,
+  title = "New message",
+  sendLabel = "Send",
+}: EmailComposeProps) => {
+  const [to, setTo] = useState(joinAddresses(defaultValue?.to));
+  const [cc, setCc] = useState(joinAddresses(defaultValue?.cc));
+  const [bcc, setBcc] = useState(joinAddresses(defaultValue?.bcc));
+  const [subject, setSubject] = useState(defaultValue?.subject ?? "");
+  const [body, setBody] = useState(defaultValue?.body ?? "");
+  const [attachments, setAttachments] = useState<EmailAttachment[]>(
+    defaultValue?.attachments ?? [],
+  );
+  const [from, setFrom] = useState(defaultFrom ?? senders?.[0] ?? "");
+  const [showPreview, setShowPreview] = useState(false);
+
+  const fileInput = useRef<HTMLInputElement>(null);
+  const onChangeRef = useRef(onChange);
+  onChangeRef.current = onChange;
+  const ids = useId();
+  const fieldId = (name: string) => `${ids}-${name}`;
+
+  const hasSenderPicker = Boolean(senders && senders.length > 0);
+  const blocked = Boolean(disabled) || Boolean(pending);
+  const recipients = parseAddresses(to);
+  const canSend = recipients.length > 0 && Boolean(onSend) && !blocked;
+
+  // Assemble the current draft into a wire-format message, omitting empty
+  // optional fields so the payload stays minimal.
+  const buildMessage = useCallback((): EmailMessage => {
+    const ccList = parseAddresses(cc);
+    const bccList = parseAddresses(bcc);
+    return {
+      to: parseAddresses(to),
+      subject,
+      body,
+      ...(ccList.length ? { cc: ccList } : {}),
+      ...(bccList.length ? { bcc: bccList } : {}),
+      ...(attachments.length ? { attachments } : {}),
+    };
+  }, [to, cc, bcc, subject, body, attachments]);
+
+  useEffect(() => {
+    onChangeRef.current?.(buildMessage());
+  }, [buildMessage]);
+
+  const addFiles = useCallback(async (files: FileList | null) => {
+    if (!files || files.length === 0) return;
+    const read = await Promise.all([...files].map(fileToAttachment));
+    setAttachments((prev) => [...prev, ...read]);
+  }, []);
+
+  const removeAttachment = useCallback((index: number) => {
+    setAttachments((prev) => prev.filter((_, i) => i !== index));
+  }, []);
+
+  const submit = useCallback(() => {
+    if (!canSend) return;
+    void onSend?.(buildMessage(), hasSenderPicker ? from : undefined);
+  }, [canSend, onSend, buildMessage, hasSenderPicker, from]);
+
+  return (
+    <div className="not-prose flex flex-col gap-3 rounded-md border border-border bg-card p-4 text-sm">
+      <div className="text-sm font-medium">{title}</div>
+
+      {hasSenderPicker && (
+        <Field label="From" htmlFor={fieldId("from")}>
+          <Select value={from} onValueChange={setFrom} disabled={blocked}>
+            <SelectTrigger id={fieldId("from")} className="h-8">
+              <SelectValue placeholder="Select a sender" />
+            </SelectTrigger>
+            <SelectContent>
+              {senders?.map((address) => (
+                <SelectItem key={address} value={address}>
+                  {address}
+                </SelectItem>
+              ))}
+            </SelectContent>
+          </Select>
+        </Field>
+      )}
+
+      <Field label="To" htmlFor={fieldId("to")}>
+        <Input
+          id={fieldId("to")}
+          value={to}
+          onChange={(e) => setTo(e.target.value)}
+          placeholder="alice@example.com, bob@example.com"
+          disabled={blocked}
+          className="h-8"
+        />
+      </Field>
+
+      <div className="grid gap-3 sm:grid-cols-2">
+        <Field label="Cc" htmlFor={fieldId("cc")}>
+          <Input
+            id={fieldId("cc")}
+            value={cc}
+            onChange={(e) => setCc(e.target.value)}
+            placeholder="Optional"
+            disabled={blocked}
+            className="h-8"
+          />
+        </Field>
+        <Field label="Bcc" htmlFor={fieldId("bcc")}>
+          <Input
+            id={fieldId("bcc")}
+            value={bcc}
+            onChange={(e) => setBcc(e.target.value)}
+            placeholder="Optional"
+            disabled={blocked}
+            className="h-8"
+          />
+        </Field>
+      </div>
+
+      <Field label="Subject" htmlFor={fieldId("subject")}>
+        <Input
+          id={fieldId("subject")}
+          value={subject}
+          onChange={(e) => setSubject(e.target.value)}
+          placeholder="Subject"
+          disabled={blocked}
+          className="h-8"
+        />
+      </Field>
+
+      <div className="grid gap-1.5">
+        <div className="flex items-center justify-between">
+          <Label htmlFor={fieldId("body")} className="text-xs text-muted-foreground">
+            Body
+          </Label>
+          <Button
+            type="button"
+            size="sm"
+            variant="ghost"
+            className="h-6 px-2 text-xs"
+            disabled={!body}
+            onClick={() => setShowPreview((v) => !v)}
+          >
+            {showPreview ? (
+              <>
+                <PencilIcon className="size-3" /> Edit
+              </>
+            ) : (
+              <>
+                <EyeIcon className="size-3" /> Preview
+              </>
+            )}
+          </Button>
+        </div>
+        {showPreview ? (
+          <EmailPreview email={{ ...buildMessage(), body: body || "_Nothing to preview yet._" }} />
+        ) : (
+          <Textarea
+            id={fieldId("body")}
+            value={body}
+            onChange={(e) => setBody(e.target.value)}
+            placeholder="Write your message..."
+            disabled={blocked}
+            className="min-h-32 font-mono text-xs"
+          />
+        )}
+      </div>
+
+      {allowAttachments && (
+        <div className="grid gap-1.5">
+          <div className="flex items-center gap-2">
+            <input
+              ref={fileInput}
+              type="file"
+              multiple
+              hidden
+              onChange={(e) => {
+                void addFiles(e.target.files);
+                e.target.value = "";
+              }}
+            />
+            <Button
+              type="button"
+              size="sm"
+              variant="outline"
+              className="h-7"
+              disabled={blocked}
+              onClick={() => fileInput.current?.click()}
+            >
+              <PaperclipIcon className="size-3" /> Attach files
+            </Button>
+          </div>
+          {attachments.length > 0 && (
+            <ul className="flex flex-wrap gap-1.5">
+              {attachments.map((att, index) => (
+                <li
+                  key={`${att.filename}-${index}`}
+                  className="flex items-center gap-1 rounded bg-muted px-2 py-1 text-xs"
+                >
+                  <span className="max-w-40 truncate">{att.filename}</span>
+                  <button
+                    type="button"
+                    aria-label={`Remove ${att.filename}`}
+                    className={cn(
+                      "text-muted-foreground hover:text-foreground",
+                      blocked && "pointer-events-none opacity-50",
+                    )}
+                    onClick={() => removeAttachment(index)}
+                  >
+                    <XIcon className="size-3" />
+                  </button>
+                </li>
+              ))}
+            </ul>
+          )}
+        </div>
+      )}
+
+      <div className="mt-1 flex items-center gap-2">
+        <Button type="button" size="sm" disabled={!canSend} onClick={submit}>
+          <SendIcon className="size-3" />
+          {pending ? "Sending..." : sendLabel}
+        </Button>
+        {onCancel && (
+          <Button
+            type="button"
+            size="sm"
+            variant="outline"
+            disabled={blocked}
+            onClick={() => onCancel()}
+          >
+            Cancel
+          </Button>
+        )}
+      </div>
+    </div>
+  );
+};

package/src/email/react/fields.ts

@@ -0,0 +1,33 @@
+// Shared, presentational helpers for the email field UIs (the read-only
+// approval preview and the editable compose view). Keeping the address
+// and attachment formatting here lets both surfaces agree on how a draft
+// is displayed and how free-text address input is normalized.
+
+import { net } from "@dbx-tools/shared-core";
+import type { EmailAttachment, EmailMessage } from "@dbx-tools/shared-email";
+
+/** A partially-filled email, as it streams in from a tool call or a form. */
+export type EmailDraft = Partial<EmailMessage>;
+
+/** Render an address array as a single comma-separated display string. */
+export const joinAddresses = (addresses: string[] | undefined): string =>
+  (addresses ?? [])
+    .map((a) => a.trim())
+    .filter(Boolean)
+    .join(", ");
+
+/**
+ * Split a free-text address field (comma / semicolon / whitespace
+ * separated) into a trimmed, de-duplicated address array - the inverse
+ * of {@link joinAddresses} for compose inputs. Delegates to the shared
+ * {@link net.parseEmails} so the UI reads addresses the same way the
+ * server does.
+ */
+export const parseAddresses = (raw: string): string[] => net.parseEmails(raw);
+
+/** Comma-separated list of attachment filenames for a compact display. */
+export const attachmentNames = (attachments: EmailAttachment[] | undefined): string =>
+  (attachments ?? [])
+    .map((a) => a.filename)
+    .filter(Boolean)
+    .join(", ");