@dbx-tools/ui-email 0.1.9

package/README.md

@@ -0,0 +1,118 @@
+# @dbx-tools/ui-email
+
+React email surfaces for AppKit chat and admin workflows.
+
+Import this package when a Databricks App needs to render model-drafted email,
+collect a human approval decision, or provide a standalone compose form using
+the same message contract as [`@dbx-tools/shared-email`](../../shared/email).
+Server-side sending and AppKit routes live in
+[`@dbx-tools/node-email`](../../node/email).
+
+Key features:
+
+- Approval card for suspended `send_email` tool calls.
+- Read-only draft preview for review queues, chat transcripts, and test pages.
+- Standalone compose form that emits shared `EmailMessage` payloads.
+- Compact Markdown body renderer shared across preview and compose surfaces.
+- Recipient parsing, address display, and attachment-label helpers that mirror
+  server expectations.
+- Styles wired to the AppKit UI/Tailwind foundation so host apps do not need a
+  separate email component theme.
+
+## Add The Styles
+
+```css
+@import "@databricks/appkit-ui/styles.css";
+@import "@dbx-tools/ui-email/styles.css";
+```
+
+The stylesheet pulls in the AppKit UI base styles and scans the email React
+components for Tailwind classes. Import it once from the app's global CSS entry.
+
+## Render A Send Approval
+
+```tsx
+import { EmailApprovalCard } from "@dbx-tools/ui-email/react";
+import { email } from "@dbx-tools/shared-email";
+
+const draft = email.emailMessageSchema.parse(toolCall.args);
+
+<EmailApprovalCard
+  email={draft}
+  pending={pending}
+  onApprove={() => addToolResult({ toolCallId: toolCall.id, result: { approved: true } })}
+  onDeny={() => addToolResult({ toolCallId: toolCall.id, result: { approved: false } })}
+/>;
+```
+
+`EmailApprovalCard` is the chat-facing component for the `send_email` tool. It
+renders the draft fields, Markdown body, attachment names, and Approve/Deny
+actions while leaving tool-call state and transport decisions to the host app.
+
+Wire `onApprove` and `onDeny` to the chat framework's tool-result mechanism.
+The component deliberately does not call the email API itself; the server-side
+tool resumes only after the host app records the user's decision.
+
+## Preview A Draft Inline
+
+```tsx
+import { EmailPreview } from "@dbx-tools/ui-email/react";
+
+<EmailPreview email={draft} />;
+```
+
+Use `EmailPreview` when a page needs a compact read-only summary without action
+buttons, such as a review queue, audit log, or test harness.
+
+## Provide A Compose View
+
+```tsx
+import { EmailComposeView } from "@dbx-tools/ui-email/react";
+
+<EmailComposeView
+  senders={senderOptions.senders}
+  defaultFrom={senderOptions.defaultSender}
+  onSend={(message, from) => sendEmail(message, from)}
+/>;
+```
+
+`EmailComposeView` owns the form state, normalizes recipient fields, converts
+attached files to base64 email attachments, and emits the assembled
+`EmailMessage`. Fetch sender options and dispatch the final send through the
+server package.
+
+## Render A Markdown Body
+
+```tsx
+import { EmailBody } from "@dbx-tools/ui-email/react";
+
+<EmailBody className="text-sm">{message.body}</EmailBody>;
+```
+
+`EmailBody` uses Streamdown to render compact Markdown for email text. It is
+shared by the compose preview and approval card so drafts look the same before
+and after submission.
+
+## Reuse Field Helpers
+
+```ts
+import { attachmentNames, joinAddresses, parseAddresses } from "@dbx-tools/ui-email/react";
+
+const to = parseAddresses("alice@example.com; bob@example.com");
+const label = joinAddresses(to);
+const files = attachmentNames(message.attachments);
+```
+
+The helpers keep free-text recipient parsing and attachment labels consistent
+across approval, compose, and custom UI surfaces.
+
+## Modules
+
+- `./react` - `EmailPreview`, `EmailApprovalCard`, `EmailComposeView`,
+  `EmailBody`, address/attachment helpers, shared email message types, and prop
+  types.
+- `./styles.css` - Tailwind/AppKit style entrypoint for the email components.
+
+Pair this package with [`@dbx-tools/node-email`](../../node/email) for SMTP or
+outbox delivery, and with [`@dbx-tools/shared-email`](../../shared/email) for
+schema validation in client/server boundaries.

package/index.ts

@@ -0,0 +1,12 @@
+// GENERATED by projen watch - DO NOT EDIT.
+// Regenerated from the exporting modules in ./src.
+// Hand edits are overwritten on the next watch; this file is read-only.
+
+export * as reactEmailApprovalCard from "./src/react/email-approval-card";
+export * as reactEmailBody from "./src/react/email-body";
+export * as reactEmailCompose from "./src/react/email-compose";
+export * as reactFields from "./src/react/fields";
+export type { EmailPreviewProps, EmailApprovalCardProps } from "./src/react/email-approval-card";
+export type { EmailBodyProps } from "./src/react/email-body";
+export type { EmailComposeProps } from "./src/react/email-compose";
+export type { EmailDraft } from "./src/react/fields";

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@dbx-tools/ui-email",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/reggie-db/dbx-tools.git",
+    "directory": "workspaces/ui/email"
+  },
+  "devDependencies": {
+    "@types/node": "^24.6.0",
+    "@types/react": "^19.2.2",
+    "@types/react-dom": "^19.2.2",
+    "tsx": "^4.23.0",
+    "typescript": "^5.9.3"
+  },
+  "dependencies": {
+    "lucide-react": "^0.554.0",
+    "react": "^19.2.4",
+    "react-dom": "^19.2.4",
+    "streamdown": "^2.5.0",
+    "@dbx-tools/shared-core": "0.1.9",
+    "@dbx-tools/shared-email": "0.1.9",
+    "@dbx-tools/ui-appkit": "0.1.9"
+  },
+  "main": "index.ts",
+  "license": "UNLICENSED",
+  "version": "0.1.9",
+  "types": "index.ts",
+  "type": "module",
+  "exports": {
+    "./react": "./src/react/index.ts",
+    "./styles.css": "./src/styles.css",
+    "./package.json": "./package.json"
+  },
+  "dbxToolsConfig": {
+    "tags": [
+      "ui"
+    ]
+  },
+  "//": "~~ Generated by projen. To modify, edit .projenrc.js and run \"pnpm exec projen\".",
+  "scripts": {
+    "build": "projen build",
+    "compile": "projen compile",
+    "default": "projen default",
+    "package": "projen package",
+    "post-compile": "projen post-compile",
+    "pre-compile": "projen pre-compile",
+    "test": "projen test",
+    "watch": "projen watch",
+    "projen": "projen"
+  }
+}

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

@@ -0,0 +1,129 @@
+import { Button } from "@dbx-tools/ui-appkit/react";
+import { CheckIcon, MailIcon, XIcon } from "lucide-react";
+import { EmailBody } from "./email-body";
+import { attachmentNames, joinAddresses, type EmailDraft } from "./fields";
+
+// Presentational pieces for an outbound email awaiting a human Approve /
+// Deny: the field preview (To / Cc / Subject / Body / Files, body
+// rendered as markdown) and a self-contained 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";
+
+/** Props for {@link EmailPreview}. */
+export interface EmailPreviewProps {
+  email: EmailDraft;
+}
+
+/**
+ * Render an email draft as a labelled `To` / `Cc` / `Subject` / `Body` /
+ * `Files` list. `to` / `cc` may carry one or more addresses; the body is
+ * markdown so links, lists, and emphasis render rather than showing raw
+ * syntax. Fields that are empty are omitted.
+ */
+export const EmailPreview = ({ email }: EmailPreviewProps) => {
+  const to = joinAddresses(email.to);
+  const cc = joinAddresses(email.cc);
+  const attachments = attachmentNames(email.attachments);
+  return (
+    <dl className="space-y-1 text-xs">
+      {to && (
+        <div className="flex gap-2">
+          <dt className="w-16 shrink-0 text-muted-foreground">To</dt>
+          <dd className="truncate">{to}</dd>
+        </div>
+      )}
+      {cc && (
+        <div className="flex gap-2">
+          <dt className="w-16 shrink-0 text-muted-foreground">Cc</dt>
+          <dd className="truncate">{cc}</dd>
+        </div>
+      )}
+      {email.subject && (
+        <div className="flex gap-2">
+          <dt className="w-16 shrink-0 text-muted-foreground">Subject</dt>
+          <dd className="truncate font-medium">{email.subject}</dd>
+        </div>
+      )}
+      {email.body && (
+        <div className="flex gap-2">
+          <dt className="w-16 shrink-0 text-muted-foreground">Body</dt>
+          <dd className="min-w-0 flex-1 break-words text-foreground">
+            <EmailBody>{email.body}</EmailBody>
+          </dd>
+        </div>
+      )}
+      {attachments && (
+        <div className="flex gap-2">
+          <dt className="w-16 shrink-0 text-muted-foreground">Files</dt>
+          <dd className="min-w-0 flex-1 truncate">{attachments}</dd>
+        </div>
+      )}
+    </dl>
+  );
+};
+
+/** 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/react/email-body.tsx

@@ -0,0 +1,29 @@
+// 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 { cn } from "@dbx-tools/ui-appkit/react";
+import { Streamdown } from "streamdown";
+
+/** Props for {@link EmailBody}. */
+export interface EmailBodyProps {
+  children: string;
+  /** Extra classes merged onto the prose container. */
+  className?: string;
+}
+
+/** Render an email body (Markdown) as compact, muted prose. */
+export const EmailBody = ({ children, className }: EmailBodyProps) => (
+  <Streamdown
+    controls={false}
+    className={cn(
+      "prose prose-sm dark:prose-invert max-w-none break-words",
+      "text-[11px] leading-snug text-muted-foreground",
+      "[&_strong]:text-foreground [&_p]:my-1 [&_ul]:my-1 [&_ol]:my-1 [&_ul]:pl-4 [&_ol]:pl-4",
+      className,
+    )}
+  >
+    {children}
+  </Streamdown>
+);

package/src/react/email-compose.tsx

@@ -0,0 +1,345 @@
+import {
+  Button,
+  Input,
+  Label,
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+  Textarea,
+  cn,
+} from "@dbx-tools/ui-appkit/react";
+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 { EmailBody } from "./email-body";
+import { joinAddresses, parseAddresses, type EmailDraft } from "./fields";
+
+// 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 Markdown 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 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(() => {
+    onChange?.(buildMessage());
+  }, [buildMessage, onChange]);
+
+  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 (Markdown)
+          </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 ? (
+          <div className="min-h-32 rounded-md border border-border bg-background p-3">
+            <EmailBody>{body || "_Nothing to preview yet._"}</EmailBody>
+          </div>
+        ) : (
+          <Textarea
+            id={fieldId("body")}
+            value={body}
+            onChange={(e) => setBody(e.target.value)}
+            placeholder="Write your message in Markdown..."
+            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/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(", ");

package/src/react/index.ts

@@ -0,0 +1,17 @@
+// React surface for `@dbx-tools/ui-email`: a read-only Approve / Deny card for
+// the `send_email` tool's approval flow, the field preview it wraps, and a
+// standard editable compose view for use outside a chat bubble. All three share
+// `./fields` and `./email-body`, so a drafted message renders identically across
+// them. Styled with AppKit tokens.
+
+export type { EmailAttachment, EmailMessage } from "@dbx-tools/shared-email";
+export {
+  EmailApprovalCard,
+  EmailPreview,
+  type EmailApprovalCardProps,
+  type EmailPreviewProps,
+} from "./email-approval-card";
+export { EmailBody, type EmailBodyProps } from "./email-body";
+export { EmailComposeView, type EmailComposeProps } from "./email-compose";
+export { attachmentNames, joinAddresses, parseAddresses } from "./fields";
+export type { EmailDraft } from "./fields";

package/src/styles.css

@@ -0,0 +1,20 @@
+/*
+ * @dbx-tools/ui-email stylesheet.
+ *
+ * Import once from the host app's Tailwind entry, after Tailwind and
+ * your AppKit-UI theme:
+ *
+ *   @import "tailwindcss";
+ *   @import "@databricks/appkit-ui/styles.css";
+ *   @import "@dbx-tools/ui-email/styles.css";
+ *
+ * Defines NO design tokens - the email preview styles exclusively with
+ * AppKit semantic tokens and inherits the host app's theme.
+ *
+ * Pulls shared Streamdown / shiki styling from `@dbx-tools/ui-appkit` and
+ * registers this package's React components with Tailwind via `@source`.
+ */
+
+@import "@dbx-tools/ui-appkit/styles.css";
+
+@source "./react";

package/tsconfig.json

@@ -0,0 +1,43 @@
+// ~~ Generated by projen. To modify, edit .projenrc.js and run "pnpm exec projen".
+{
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib",
+    "alwaysStrict": true,
+    "declaration": true,
+    "esModuleInterop": true,
+    "experimentalDecorators": true,
+    "inlineSourceMap": true,
+    "inlineSources": true,
+    "lib": [
+      "ES2022",
+      "DOM",
+      "DOM.Iterable"
+    ],
+    "module": "ESNext",
+    "noEmitOnError": false,
+    "noFallthroughCasesInSwitch": true,
+    "noImplicitAny": true,
+    "noImplicitReturns": true,
+    "noImplicitThis": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "resolveJsonModule": true,
+    "strict": true,
+    "strictNullChecks": true,
+    "strictPropertyInitialization": true,
+    "stripInternal": true,
+    "target": "ES2022",
+    "types": [],
+    "moduleResolution": "bundler",
+    "skipLibCheck": true,
+    "jsx": "react-jsx"
+  },
+  "include": [
+    "src/**/*.ts",
+    "src/**/*.tsx"
+  ],
+  "exclude": [
+    "node_modules"
+  ]
+}