@dbx-tools/ui-mastra 0.1.9

package/src/react/data-grid.tsx

@@ -0,0 +1,342 @@
+import {
+  Button,
+  DropdownMenu,
+  DropdownMenuCheckboxItem,
+  DropdownMenuContent,
+  DropdownMenuTrigger,
+  Table,
+  TableBody,
+  TableCell,
+  TableHead,
+  TableHeader,
+  TableRow,
+  cn,
+} from "@dbx-tools/ui-appkit/react";
+import { string } from "@dbx-tools/shared-core";
+import {
+  flexRender,
+  getCoreRowModel,
+  getSortedRowModel,
+  useReactTable,
+  type ColumnDef,
+  type SortingState,
+  type VisibilityState,
+} from "@tanstack/react-table";
+import {
+  ArrowDownIcon,
+  ArrowUpIcon,
+  ChevronsUpDownIcon,
+  Columns3Icon,
+  DownloadIcon,
+} from "lucide-react";
+import React, { useMemo, useState } from "react";
+
+// Interactive result table plus the cell/label/CSV helpers it and the
+// markdown table renderer share. Built on `@tanstack/react-table` over
+// AppKit's `Table` primitives so every table in the chat - statement
+// results and lifted markdown tables alike - reads as the same block.
+
+/** A statement row: column name -> cell value, as `StatementData.rows` arrives. */
+export type DataRow = Record<string, unknown>;
+
+/**
+ * Color-code numeric deltas like `+1.8%`, `-3.1%`, or `+0.6 pts` inside
+ * a single table cell. Matches the *first* signed numeric token in the
+ * cell; if no match, returns the children unchanged.
+ *
+ * Patterns recognized (case insensitive, allow comma/decimal):
+ *   +1.8%   -3.1%   +0.6 pts   -0.9 pts
+ */
+const DELTA_PATTERN = /^([+\u2212-])\s*\d[\d,.\s]*(?:%|\s*pts?)?$/i;
+
+export function colorizeDelta(content: React.ReactNode): React.ReactNode {
+  if (typeof content !== "string") return content;
+  const text = content.trim();
+  const match = DELTA_PATTERN.exec(text);
+  if (!match) return content;
+  const sign = match[1];
+  if (sign === "+") return <span className="font-medium text-success">{content}</span>;
+  if (sign === "-" || sign === "\u2212")
+    return <span className="font-medium text-destructive">{content}</span>;
+  return content;
+}
+
+/**
+ * Render a cell value: blank for nullish, otherwise the string form
+ * run through {@link colorizeDelta} so signed deltas keep their
+ * green/red treatment.
+ */
+export function renderDataCell(value: unknown): React.ReactNode {
+  return colorizeDelta(value == null ? "" : String(value));
+}
+
+/**
+ * Turn a raw statement column name into a human-readable header by
+ * tokenizing it (camelCase / snake_case / kebab / etc. all split) and
+ * Title-Casing each token: `total_revenue` -> "Total Revenue",
+ * `aiScore` -> "AI Score" (the tokenizer special-cases `ai`). Falls
+ * back to the original string when tokenization yields nothing (e.g. a
+ * punctuation-only column name). The raw name is still used as the
+ * column id, accessor key, and CSV header, so only the on-screen label
+ * is prettified.
+ */
+export function humanizeLabel(
+  value: string,
+  options?: string.TokenizeOptions,
+): string {
+  const tokens = [
+    ...string.tokenizeWithOptions(
+      { lowerCase: true, capitalize: true, ...options },
+      value,
+    ),
+  ];
+  return tokens.length > 0 ? tokens.join(" ") : value;
+}
+
+/**
+ * Serialize already-ordered `rows` to a CSV over `columns` and trigger
+ * a browser download. Fields are quoted only when they contain a
+ * comma, double-quote, or newline (RFC-4180 minimal quoting); embedded
+ * quotes are doubled. The blob URL is revoked right after the click so
+ * we don't leak object URLs across repeated exports.
+ */
+function downloadCsv(columns: string[], rows: DataRow[], filename: string): void {
+  const escape = (value: unknown): string => {
+    const s = value == null ? "" : String(value);
+    return /[",\n]/.test(s) ? `"${s.replace(/"/g, '""')}"` : s;
+  };
+  const csv = [
+    columns.map(escape).join(","),
+    ...rows.map((row) => columns.map((c) => escape(row[c])).join(",")),
+  ].join("\n");
+  const url = URL.createObjectURL(new Blob([csv], { type: "text/csv;charset=utf-8;" }));
+  const anchor = document.createElement("a");
+  anchor.href = url;
+  anchor.download = filename;
+  anchor.click();
+  URL.revokeObjectURL(url);
+}
+
+/**
+ * Wrapper class layered on every chat table (markdown + statement
+ * results). It frames the table as a distinct card so it reads as a
+ * separate block in the conversation. AppKit's `Table` family already
+ * owns row borders, hover, and color tokens - on top of that we add:
+ *   - `not-prose` to escape `@tailwindcss/typography`'s table styles
+ *     (margins, font-weight, etc.) which fight the AppKit defaults
+ *   - a `rounded-lg` border + `bg-card` + `shadow-sm` card frame with
+ *     `overflow-hidden` so the rounded corners clip the scroll area
+ *   - compact `text-xs` + `tabular-nums` so columns of numbers align
+ *   - right-alignment for every column except the first label column
+ *   - a `max-h-[60vh]` vertical cap so tall tables scroll their body
+ *     instead of running off the viewport, plus `overflow-auto` so wide
+ *     tables scroll horizontally *inside* the card rather than pushing
+ *     the chat past its max width. AppKit's `Table` nests the `<table>`
+ *     in its own scroll container (`<div>` - the wrapper's only child),
+ *     so the cap + overflow land there, making it the scroll ancestor
+ *     the sticky header pins to.
+ *   - a prominent, sticky header: tinted (`bg-muted`), bold, opaque
+ *     (so rows don't bleed through while scrolling), and divided from
+ *     the body with a bottom border.
+ */
+export const TABLE_WRAPPER_CLASSES = cn(
+  // Card-like frame so each table reads as a distinct block in the
+  // chat rather than bleeding into the surrounding prose.
+  "not-prose my-4 max-w-full overflow-hidden rounded-lg border border-border bg-card shadow-sm",
+  "text-xs tabular-nums",
+  "[&_th:not(:first-child)]:text-right [&_td:not(:first-child)]:text-right",
+  // The inner AppKit scroll container is the scroll surface for both
+  // axes; cap its height so tall tables scroll their body in place.
+  "[&>div]:max-h-[60vh] [&>div]:overflow-auto",
+  // Make the header read as a header: opaque, tinted, bold, and pinned
+  // to the top of the scroll container with a divider beneath it.
+  "[&_thead_th]:sticky [&_thead_th]:top-0 [&_thead_th]:z-10",
+  "[&_thead_th]:bg-muted [&_thead_th]:font-semibold [&_thead_th]:text-foreground",
+  "[&_thead_th]:border-b [&_thead_th]:border-border",
+);
+
+/**
+ * Card frame for {@link DataGrid} - the same rounded/bordered/elevated
+ * treatment as {@link TABLE_WRAPPER_CLASSES} so interactive statement
+ * tables and static markdown tables read as the same kind of block.
+ */
+const DATA_GRID_CARD_CLASSES = cn(
+  "not-prose my-4 max-w-full overflow-hidden rounded-lg border border-border bg-card shadow-sm",
+  "text-xs tabular-nums",
+);
+
+/** Toolbar strip across the top of a {@link DataGrid} card. */
+const DATA_GRID_TOOLBAR_CLASSES = cn(
+  "flex items-center justify-between gap-2",
+  "border-b border-border bg-muted/40 px-3 py-1.5 text-xs text-muted-foreground",
+);
+
+/**
+ * Scroll surface wrapping the {@link DataGrid} table. AppKit's `Table`
+ * nests its `<table>` inside its own scroll container `<div>` (this
+ * wrapper's only child), so the height cap + `overflow` must land on
+ * THAT div (`[&>div]`) - not this wrapper - to make it the single
+ * scroll box. Otherwise the inner container becomes a nested scroll
+ * box the sticky header pins to, and the header rides up with the body
+ * as the outer wrapper scrolls. With the cap on the inner div the
+ * sticky header pins to it and stays put. Header cells are tinted,
+ * bold, and opaque so rows don't bleed through while scrolling.
+ */
+const DATA_GRID_SCROLL_CLASSES = cn(
+  "[&>div]:max-h-[60vh] [&>div]:overflow-auto",
+  "[&_th:not(:first-child)]:text-right [&_td:not(:first-child)]:text-right",
+  "[&_thead_th]:sticky [&_thead_th]:top-0 [&_thead_th]:z-10",
+  "[&_thead_th]:bg-muted [&_thead_th]:font-semibold [&_thead_th]:text-foreground",
+  "[&_thead_th]:border-b [&_thead_th]:border-border",
+);
+
+/**
+ * Interactive table for a settled statement result, built on
+ * `@tanstack/react-table` over AppKit's `Table` primitives so it
+ * matches the rest of the chat. A toolbar in the card header carries
+ * the row count, a column show/hide menu, and a CSV export of the
+ * visible columns in the current sort order. Header cells are sort
+ * toggles (click to cycle asc -> desc -> none): the active column
+ * shows a direction arrow, idle columns a faded up/down glyph. All
+ * state is client-side - the rows arrive once from {@link DataSlot}.
+ */
+export const DataGrid = ({
+  columns,
+  rows,
+  truncated,
+  rowCount,
+  humanizeHeaders = false,
+}: {
+  columns: string[];
+  rows: DataRow[];
+  truncated: boolean;
+  rowCount: number;
+  /**
+   * Title-Case raw identifier column names for display (statement
+   * results). Off for markdown tables, whose headers are already
+   * human-authored and would be mangled by the tokenizer.
+   */
+  humanizeHeaders?: boolean;
+}) => {
+  const [sorting, setSorting] = useState<SortingState>([]);
+  const [columnVisibility, setColumnVisibility] = useState<VisibilityState>({});
+
+  const columnDefs = useMemo<ColumnDef<DataRow>[]>(
+    () =>
+      columns.map((col): ColumnDef<DataRow> => ({
+        id: col,
+        accessorFn: (row) => row[col],
+        header: humanizeHeaders ? humanizeLabel(col) : col,
+        cell: (info) => renderDataCell(info.getValue()),
+        sortUndefined: "last",
+      })),
+    [columns, humanizeHeaders],
+  );
+
+  const table = useReactTable({
+    data: rows,
+    columns: columnDefs,
+    state: { sorting, columnVisibility },
+    onSortingChange: setSorting,
+    onColumnVisibilityChange: setColumnVisibility,
+    getCoreRowModel: getCoreRowModel(),
+    getSortedRowModel: getSortedRowModel(),
+  });
+
+  const exportCsv = () =>
+    downloadCsv(
+      table.getVisibleLeafColumns().map((c) => c.id),
+      table.getSortedRowModel().rows.map((r) => r.original),
+      "statement.csv",
+    );
+
+  return (
+    <div className={DATA_GRID_CARD_CLASSES}>
+      <div className={DATA_GRID_TOOLBAR_CLASSES}>
+        <span>
+          {truncated
+            ? `Showing ${rows.length} of ${rowCount} rows`
+            : `${rows.length} ${rows.length === 1 ? "row" : "rows"}`}
+        </span>
+        <div className="flex items-center gap-1">
+          <DropdownMenu>
+            <DropdownMenuTrigger asChild>
+              <Button variant="ghost" size="sm" className="h-7 gap-1 px-2 text-xs">
+                <Columns3Icon className="size-3.5" />
+                Columns
+              </Button>
+            </DropdownMenuTrigger>
+            <DropdownMenuContent align="end" className="max-h-72 overflow-y-auto">
+              {table.getAllLeafColumns().map((column) => (
+                <DropdownMenuCheckboxItem
+                  key={column.id}
+                  className="text-xs"
+                  checked={column.getIsVisible()}
+                  // Keep the menu open while toggling several columns.
+                  onSelect={(e) => e.preventDefault()}
+                  onCheckedChange={(value) => column.toggleVisibility(!!value)}
+                >
+                  {String(column.columnDef.header)}
+                </DropdownMenuCheckboxItem>
+              ))}
+            </DropdownMenuContent>
+          </DropdownMenu>
+          <Button
+            variant="ghost"
+            size="sm"
+            className="h-7 gap-1 px-2 text-xs"
+            onClick={exportCsv}
+          >
+            <DownloadIcon className="size-3.5" />
+            Export
+          </Button>
+        </div>
+      </div>
+      <div className={DATA_GRID_SCROLL_CLASSES}>
+        <Table>
+          <TableHeader>
+            {table.getHeaderGroups().map((group) => (
+              <TableRow key={group.id}>
+                {group.headers.map((header) => {
+                  const sorted = header.column.getIsSorted();
+                  return (
+                    <TableHead key={header.id}>
+                      <button
+                        type="button"
+                        className="inline-flex items-center gap-1 hover:text-foreground"
+                        onClick={header.column.getToggleSortingHandler()}
+                      >
+                        {flexRender(
+                          header.column.columnDef.header,
+                          header.getContext(),
+                        )}
+                        {sorted === "asc" ? (
+                          <ArrowUpIcon className="size-3" />
+                        ) : sorted === "desc" ? (
+                          <ArrowDownIcon className="size-3" />
+                        ) : (
+                          <ChevronsUpDownIcon className="size-3 opacity-40" />
+                        )}
+                      </button>
+                    </TableHead>
+                  );
+                })}
+              </TableRow>
+            ))}
+          </TableHeader>
+          <TableBody>
+            {table.getRowModel().rows.map((row) => (
+              <TableRow key={row.id}>
+                {row.getVisibleCells().map((cell) => (
+                  <TableCell key={cell.id}>
+                    {flexRender(cell.column.columnDef.cell, cell.getContext())}
+                  </TableCell>
+                ))}
+              </TableRow>
+            ))}
+          </TableBody>
+        </Table>
+      </div>
+    </div>
+  );
+};

package/src/react/embed-slots.tsx

@@ -0,0 +1,258 @@
+import { Spinner } from "@dbx-tools/ui-appkit/react";
+import {
+  marker as markers,
+  type ParsedMarker,
+} from "@dbx-tools/shared-mastra";
+import ReactECharts from "echarts-for-react";
+import { ClockIcon } from "lucide-react";
+import { useMemo } from "react";
+import { normalizeChartOption } from "../support/chart-option";
+import { useChartFetch, useStatementFetch } from "../support/mastra-client";
+import { DataGrid, humanizeLabel } from "./data-grid";
+import { AssistantMarkdown } from "./markdown";
+
+// Inline embed slots: chart / data tables resolved from `[chart:<id>]`
+// and `[data:<id>]` markers in the assistant's prose, plus the splitter
+// that interleaves those slots with the surrounding markdown.
+
+/**
+ * Frame shared by every chart-slot state so the layout stays
+ * stable as a slot transitions from queueing → rendering →
+ * rendered (or → render-failed). Width tracks the bubble; height
+ * is fixed so Echarts has a deterministic canvas regardless of
+ * the parent's flex layout. `not-prose` opts out of Tailwind
+ * Typography.
+ */
+const CHART_FRAME_CLASSES =
+  "not-prose my-3 max-w-full rounded border border-border/60 bg-background/40 p-2";
+const CHART_HEIGHT_PX = 320;
+
+/**
+ * Compact inline notice rendered in place of an embed - a chart, data
+ * table, or any future `[<type>:<id>]` marker - whose backing cache
+ * entry 404'd, i.e. the embed id expired (TTL elapsed) or was never
+ * minted. The displayed noun is the marker `type` run through
+ * {@link humanizeLabel}, keeping this slot agnostic to which kinds
+ * exist. Deliberately small so an expired artifact in a long
+ * transcript reads as a quiet footnote rather than a broken,
+ * full-height frame. Only the genuine "settled 404" case reaches here;
+ * in-flight fetches and hard errors still render nothing (see
+ * {@link ChartSlot} / {@link DataSlot}).
+ */
+const ExpiredSlot = ({ type }: { type: string }) => (
+  <div className="not-prose my-3 inline-flex items-center gap-2 rounded-md border border-dashed border-border bg-muted/40 px-3 py-1.5 text-xs text-muted-foreground">
+    <ClockIcon className="size-3.5 shrink-0" />
+    <span>
+      This {humanizeLabel(type, { capitalize: false })} has expired and is no longer
+      available.
+    </span>
+  </div>
+);
+
+/**
+ * Inline chart slot. Each `[chart:<chartId>]` marker in the
+ * assistant's reply resolves to one of these. The Mastra plugin
+ * caches the resolved Echarts
+ * spec under the chartId; this slot fetches it via the generic
+ * `embedPathTemplate` (`/embed/chart/:id`, long-poll until ready /
+ * error / 404).
+ *
+ * Render contract:
+ *
+ *   - Cache entry settled with `result` -> render the full
+ *     Echarts spec.
+ *   - Fetch / long-poll in flight -> render the chart frame at its
+ *     known fixed footprint (`CHART_HEIGHT_PX`) with a centered
+ *     spinner, so the slot reserves the chart's eventual space and
+ *     the prose below doesn't reflow when it lands.
+ *   - 404 (unknown / TTL-expired id) -> render a small
+ *     {@link ExpiredSlot} notice so the reader knows the chart
+ *     used to be here but has aged out, instead of a silent gap.
+ *   - Settled with `error`, or a non-terminal payload that has
+ *     neither `result` nor `error` -> render NOTHING. Genuine
+ *     planner failures are silently dropped rather than left as
+ *     placeholder frames. The Echarts `option` already carries its
+ *     own `title.text`, so no separate header is needed above the
+ *     chart frame.
+ */
+const ChartSlot = ({ chartId }: { chartId: string }) => {
+  const { data: chart, loading, error } = useChartFetch(chartId);
+  // Patch presentation (compact ticks, axis-name placement, legible
+  // category labels) into the JSON-safe planner spec before rendering,
+  // matching the export path. Memoized on the resolved option identity.
+  const option = useMemo(
+    () => (chart?.result ? normalizeChartOption(chart.result.option) : undefined),
+    [chart?.result],
+  );
+  if (option) {
+    return (
+      <div className={CHART_FRAME_CLASSES}>
+        <ReactECharts
+          option={option}
+          style={{ height: CHART_HEIGHT_PX, width: "100%" }}
+          notMerge
+          lazyUpdate
+        />
+      </div>
+    );
+  }
+  // In-flight fetch: the chart's footprint is known ahead of time, so
+  // reserve the same frame + height with a spinner instead of
+  // collapsing - the chart fades in without shifting the prose below.
+  if (loading) {
+    return (
+      <div className={CHART_FRAME_CLASSES}>
+        <div
+          className="flex items-center justify-center"
+          style={{ height: CHART_HEIGHT_PX, width: "100%" }}
+        >
+          <Spinner className="size-5 text-muted-foreground" />
+        </div>
+      </div>
+    );
+  }
+  // Settled 404 (unknown / TTL-expired id) -> small "expired" notice.
+  // Hard-error / non-terminal payloads render nothing.
+  if (!error && chart === undefined) return <ExpiredSlot type="chart" />;
+  return null;
+};
+
+/**
+ * Inline data-table slot. Each `[data:<statement_id>]` marker in
+ * the assistant's reply resolves to one of these. A single
+ * OBO-scoped fetch against `embedPathTemplate` (`/embed/data/:id`)
+ * returns the columns + rows; the slot hands them to {@link DataGrid}
+ * for an interactive (sortable, column-toggle, CSV-export) table.
+ *
+ * Render contract (matches {@link ChartSlot}):
+ *
+ *   - 404 (unknown / TTL-expired id) -> render a small
+ *     {@link ExpiredSlot} notice so the reader knows a table aged
+ *     out rather than seeing a silent gap.
+ *   - Fetch in flight, hard error, or empty rows -> render
+ *     NOTHING. Stale markers in persisted transcripts stay quiet
+ *     so a reload doesn't leave dead frames.
+ *   - Data settled with rows -> render the {@link DataGrid}, whose
+ *     toolbar surfaces the "showing N of M rows" affordance when the
+ *     server-side cap truncated the result set.
+ */
+const DataSlot = ({ statementId }: { statementId: string }) => {
+  const { data, loading, error } = useStatementFetch(statementId);
+  // Settled 404 (unknown / TTL-expired id) -> small "expired" notice.
+  // In-flight fetches, hard errors, and empty result sets render
+  // nothing so stale markers in reloaded transcripts stay quiet.
+  if (!loading && !error && data === undefined) return <ExpiredSlot type="data" />;
+  if (!data || data.rows.length === 0) return null;
+  return (
+    <DataGrid
+      columns={data.columns}
+      rows={data.rows}
+      truncated={data.truncated}
+      rowCount={data.rowCount}
+      humanizeHeaders
+    />
+  );
+};
+
+/** One slice of an assistant message: prose, a chart slot, or a data slot. */
+type RenderSegment =
+  | { kind: "text"; text: string }
+  | { kind: "chart"; chartId: string }
+  | { kind: "data"; statementId: string };
+
+/**
+ * Map one parsed marker onto its render segment. The marker grammar
+ * matches ANY `[<type>:<id>]`, including fabricated ids the model
+ * glued together from a label (e.g. `[chart:placeholder]`), so the id
+ * is validated with {@link isUuid} before it's treated as a real
+ * embed. A non-UUID id - or a UUID with a type this UI can't render -
+ * collapses to an empty text segment: the marker is consumed so no
+ * literal `[<type>:...]` leaks into the prose, but no slot renders and
+ * no `/embed/<type>/:id` request fires. Only a UUID-shaped id with a
+ * known, renderable type (charts need ECharts, data needs a Table)
+ * resolves to a slot.
+ */
+const markerSegment = (marker: ParsedMarker): RenderSegment => {
+  if (!markers.isUuid(marker.id)) return { kind: "text", text: "" };
+  switch (marker.type) {
+    case "chart":
+      return { kind: "chart", chartId: marker.id };
+    case "data":
+      return { kind: "data", statementId: marker.id };
+    default:
+      return { kind: "text", text: "" };
+  }
+};
+
+const splitTextWithEmbeds = (text: string): RenderSegment[] => {
+  const segments: RenderSegment[] = [];
+  let lastIdx = 0;
+  // `parseMarkers` yields hits in source order with no overlaps (one
+  // regex pass), so the spans splice in directly - no sort or
+  // overlap guard needed.
+  for (const marker of markers.parseMarkers(text)) {
+    if (marker.start > lastIdx) {
+      segments.push({ kind: "text", text: text.slice(lastIdx, marker.start) });
+    }
+    segments.push(markerSegment(marker));
+    lastIdx = marker.end;
+  }
+  if (lastIdx < text.length) {
+    segments.push({ kind: "text", text: text.slice(lastIdx) });
+  }
+  return segments;
+};
+
+/**
+ * Render the assistant's markdown with chart and data tables
+ * placed at their inline marker positions. Each prose segment
+ * is its own {@link AssistantMarkdown} so streaming chunks still
+ * incrementally parse correctly; embed slots break the markdown
+ * flow with full-width block elements.
+ *
+ * Each marker resolves through its own slot:
+ *
+ *   - `[chart:<id>]` -> {@link ChartSlot} long-polls the
+ *     server-side chart cache and renders the Echarts spec
+ *     inline once ready (or nothing on miss / TTL-expired).
+ *   - `[data:<statement_id>]` -> {@link DataSlot} fetches the
+ *     statement rows OBO-scoped and renders an inline Table
+ *     (or nothing on 404 / empty result).
+ *
+ * Stale markers in persisted transcript text are silently
+ * dropped on reload so the prose around them stays clean.
+ *
+ * `streaming` flags the bubble as still receiving tokens; it opts the
+ * prose segments into Streamdown's word-by-word fade-in so the reply
+ * eases in rather than snapping in whole chunks. Settled bubbles pass
+ * `false` and render plain markdown.
+ */
+export const MarkdownWithEmbeds = ({
+  text,
+  streaming = false,
+}: {
+  text: string;
+  streaming?: boolean;
+}) => {
+  const segments = splitTextWithEmbeds(markers.stripIncompleteMarkerTail(text));
+  return (
+    <>
+      {segments.map((seg, i) => {
+        if (seg.kind === "text") {
+          if (seg.text.trim().length === 0) return null;
+          return (
+            <AssistantMarkdown key={`t-${i}`} animate={streaming}>
+              {seg.text}
+            </AssistantMarkdown>
+          );
+        }
+        if (seg.kind === "chart") {
+          return <ChartSlot key={`c-${i}-${seg.chartId}`} chartId={seg.chartId} />;
+        }
+        return (
+          <DataSlot key={`d-${i}-${seg.statementId}`} statementId={seg.statementId} />
+        );
+      })}
+    </>
+  );
+};

package/src/react/export-menu.tsx

@@ -0,0 +1,71 @@
+import {
+  Button,
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuTrigger,
+  Tooltip,
+  TooltipContent,
+  TooltipTrigger,
+} from "@dbx-tools/ui-appkit/react";
+import { DownloadIcon } from "lucide-react";
+import type { ExportFormat } from "../support/export";
+
+// Shared export affordance: a download button that opens a small menu of
+// output formats. Reused for both the whole-conversation export (header,
+// labelled) and per-message export (bubble action row, icon-only).
+
+/** Menu entries, in display order. */
+const FORMATS: ReadonlyArray<{ format: ExportFormat; label: string }> = [
+  { format: "pdf", label: "PDF" },
+  { format: "markdown", label: "Markdown" },
+];
+
+/**
+ * Export dropdown. Fires {@link onExport} with the chosen
+ * {@link ExportFormat}. `iconOnly` renders a compact icon trigger (used
+ * inside message bubbles) with the label surfaced as a tooltip; the
+ * default renders an icon + "Export" text button (used in the header).
+ */
+export const ExportMenu = ({
+  onExport,
+  iconOnly = false,
+  tooltip = "Export",
+}: {
+  onExport: (format: ExportFormat) => void;
+  iconOnly?: boolean;
+  tooltip?: string;
+}) => {
+  const trigger = iconOnly ? (
+    <Button type="button" size="icon" variant="ghost" className="size-7">
+      <DownloadIcon className="size-3" />
+    </Button>
+  ) : (
+    <Button type="button" size="sm" variant="outline" className="gap-1.5">
+      <DownloadIcon className="size-3" />
+      Export
+    </Button>
+  );
+
+  return (
+    <DropdownMenu>
+      {iconOnly ? (
+        <Tooltip>
+          <TooltipTrigger asChild>
+            <DropdownMenuTrigger asChild>{trigger}</DropdownMenuTrigger>
+          </TooltipTrigger>
+          <TooltipContent>{tooltip}</TooltipContent>
+        </Tooltip>
+      ) : (
+        <DropdownMenuTrigger asChild>{trigger}</DropdownMenuTrigger>
+      )}
+      <DropdownMenuContent align="end">
+        {FORMATS.map(({ format, label }) => (
+          <DropdownMenuItem key={format} onClick={() => onExport(format)}>
+            {label}
+          </DropdownMenuItem>
+        ))}
+      </DropdownMenuContent>
+    </DropdownMenu>
+  );
+};