cortena-ui 1.1.0 → 1.2.0

package/src/a2ui/views.tsx

@@ -0,0 +1,1113 @@
+"use client";
+
+/**
+ * The cortena-ui side of the A2UI catalogue.
+ *
+ * One React view per catalogue entry. Each is a real component, not a render
+ * function, so an interactive entry can hold hooks (draft input state, the
+ * debounce timer) without the renderer having to care which entries are
+ * stateful.
+ *
+ * Views receive already-resolved props: the renderer has read the data
+ * bindings, validated against the entry's zod schema and normalised actions
+ * before any of this runs. A view therefore never parses A2UI, and never sees
+ * an unvalidated value.
+ *
+ * Every visual value is a cortena-design token, as everywhere else in the
+ * package. The Tailwind scale maps below exist because Tailwind only emits a
+ * class it can see in the source, so `gap-${n}` would silently produce nothing.
+ */
+
+import { AlertTriangle, CheckCircle2, Info, OctagonAlert, Terminal } from "lucide-react";
+import * as React from "react";
+import { Alert, AlertDescription, AlertIcon, AlertTitle } from "@/components/alert";
+import { Badge } from "@/components/badge";
+import { Button } from "@/components/button";
+import { ButtonLink } from "@/components/button-link";
+import { Card, CardContent } from "@/components/card";
+import { Chart } from "@/components/chart";
+import type { ChartDataFor, ChartType } from "@/components/chart";
+import { Checkbox } from "@/components/checkbox";
+import { DataTable } from "@/components/data-table";
+import type { DataSource, DataTableColumnDef } from "@/components/data-table";
+import { DateField, formatDateISO, parseDateISO } from "@/components/date-field";
+import { EmptyState } from "@/components/empty-state";
+import { Field, FieldDescription, FieldError, FieldLabel } from "@/components/field";
+import { Input } from "@/components/input";
+import { Markdown } from "@/components/markdown";
+import { Progress, ProgressLabel, ProgressValue } from "@/components/progress";
+import { RadioGroup, RadioGroupItem } from "@/components/radio-group";
+import { SectionCard } from "@/components/section-card";
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from "@/components/select";
+import { Separator } from "@/components/separator";
+import { StatusDot } from "@/components/status-dot";
+import { Switch } from "@/components/switch";
+import { Tabs, TabsContent, TabsList, TabsTrigger } from "@/components/tabs";
+import { Textarea } from "@/components/textarea";
+import { cn } from "@/lib/cn";
+import type { A2UIAction } from "./message";
+
+/** A row in an agent-drawn table. Every value is opaque until a column reads it. */
+export type A2UIRow = Record<string, unknown>;
+
+/** Where a node sits, carried into every action the view emits. */
+export interface A2UINodeInfo {
+  surfaceId: string;
+  componentId: string;
+  /** JSON pointer this node's relative bindings resolve against. */
+  dataContextPath: string;
+}
+
+/** A normalised action attached to an interactive property. */
+export interface A2UIResolvedAction {
+  name: string;
+  context?: Record<string, unknown>;
+}
+
+/** What every view receives. */
+export interface A2UIViewProps<P> {
+  props: P;
+  node: A2UINodeInfo;
+  /** Already-rendered child nodes, in the order the component listed them. */
+  children: React.ReactNode[];
+  /** The surface data model, for actions that report the whole form. */
+  dataModel: Record<string, unknown>;
+  /**
+   * Send an action. `action` is what the agent attached to the property; when
+   * it is absent the event still fires under `fallbackName` so a host can
+   * observe interactions the agent did not ask for.
+   */
+  emit: (
+    action: A2UIResolvedAction | undefined,
+    fallbackName: string,
+    payload?: Record<string, unknown>,
+  ) => void;
+  /** Write a value back to the data model where this prop was bound. No-op for a literal. */
+  writeBack: (property: string, value: unknown) => void;
+  /** Resolve a `{ kind: "server", sourceId }` handle into a real data source. */
+  resolveDataSource: (sourceId: string) => DataSource<A2UIRow> | undefined;
+  /** Debounce applied to continuous inputs before they become actions. */
+  debounceMs: number;
+}
+
+export type A2UIView<P> = React.FC<A2UIViewProps<P>>;
+
+/* ------------------------------------------------------------------ */
+/* Shared scales                                                       */
+/* ------------------------------------------------------------------ */
+
+/** Tailwind spacing steps an agent may pick. Written out so Tailwind emits them. */
+const GAP: Record<number, string> = {
+  0: "gap-0",
+  1: "gap-1",
+  2: "gap-2",
+  3: "gap-3",
+  4: "gap-4",
+  6: "gap-6",
+  8: "gap-8",
+};
+
+const PADDING: Record<number, string> = {
+  0: "p-0",
+  1: "p-1",
+  2: "p-2",
+  3: "p-3",
+  4: "p-4",
+  6: "p-6",
+  8: "p-8",
+};
+
+const HEIGHT: Record<number, string> = {
+  0: "h-0",
+  1: "h-1",
+  2: "h-2",
+  3: "h-3",
+  4: "h-4",
+  6: "h-6",
+  8: "h-8",
+};
+
+const ALIGN: Record<string, string> = {
+  start: "items-start",
+  center: "items-center",
+  end: "items-end",
+  stretch: "items-stretch",
+  baseline: "items-baseline",
+};
+
+const JUSTIFY: Record<string, string> = {
+  start: "justify-start",
+  center: "justify-center",
+  end: "justify-end",
+  between: "justify-between",
+};
+
+const TEXT_ALIGN: Record<string, string> = {
+  start: "text-left",
+  center: "text-center",
+  end: "text-right",
+};
+
+const TEXT_ROLE: Record<string, string> = {
+  heading:
+    "font-display text-[length:var(--ds-text-h3)] leading-[var(--ds-text-h3--line-height)] font-semibold",
+  subheading:
+    "text-[length:var(--ds-text-body-md)] leading-[var(--ds-text-body-md--line-height)] font-semibold",
+  body: "text-[length:var(--ds-text-body-sm)] leading-[var(--ds-text-body-sm--line-height)]",
+  caption: "text-[length:var(--ds-text-caption)] leading-[var(--ds-text-caption--line-height)]",
+  eyebrow:
+    "text-[length:var(--ds-text-eyebrow)] leading-[var(--ds-text-eyebrow--line-height)] font-medium uppercase tracking-[var(--ds-text-eyebrow--letter-spacing)]",
+};
+
+const TEXT_TONE: Record<string, string> = {
+  default: "text-[color:var(--ds-foreground)]",
+  muted: "text-[color:var(--ds-muted-foreground)]",
+  success: "text-[color:var(--ds-success)]",
+  warning: "text-[color:var(--ds-warning)]",
+  danger: "text-[color:var(--ds-destructive)]",
+  info: "text-[color:var(--ds-info)]",
+};
+
+/**
+ * Components that are inline by nature.
+ *
+ * A Column stretches its children on the cross axis, which is right for a field
+ * or a table and wrong for a badge — one would span the whole surface. `w-fit`
+ * gives the item an explicit cross size, which is what disables the stretch,
+ * without overriding a Row's own alignment.
+ */
+const INLINE = "w-fit";
+
+const ALERT_ICON: Record<string, React.ReactNode> = {
+  default: <Terminal />,
+  success: <CheckCircle2 />,
+  warn: <AlertTriangle />,
+  danger: <OctagonAlert />,
+  info: <Info />,
+};
+
+/**
+ * Debounce a value. Used for continuous inputs so an agent receives one action
+ * per pause rather than one per keystroke; the visible input stays immediate.
+ */
+function useDebouncedEmit(
+  emit: (value: unknown) => void,
+  delay: number,
+): (value: unknown) => void {
+  const latest = React.useRef(emit);
+  latest.current = emit;
+  const timer = React.useRef<ReturnType<typeof setTimeout> | undefined>(undefined);
+  React.useEffect(
+    () => () => {
+      if (timer.current !== undefined) {
+        clearTimeout(timer.current);
+      }
+    },
+    [],
+  );
+  return React.useCallback(
+    (value: unknown) => {
+      if (timer.current !== undefined) {
+        clearTimeout(timer.current);
+      }
+      timer.current = setTimeout(() => latest.current(value), delay);
+    },
+    [delay],
+  );
+}
+
+/**
+ * A value that follows the data model but can be typed over.
+ *
+ * The bound value wins whenever the agent changes it; between agent updates the
+ * local draft wins, so typing is not swallowed by a re-render.
+ *
+ * `key` is what identity is judged on, and defaults to the value itself. It
+ * matters for a value the renderer rebuilds each pass — a Date parsed from an
+ * ISO string is a new object every render, so comparing the objects would reset
+ * the draft forever. Compare the string instead.
+ */
+function useDraft<T>(bound: T, key: unknown = bound): [T, (next: T) => void] {
+  const [draft, setDraft] = React.useState<T>(bound);
+  const previous = React.useRef(key);
+  if (!Object.is(previous.current, key)) {
+    previous.current = key;
+    setDraft(bound);
+  }
+  return [draft, setDraft];
+}
+
+/* ------------------------------------------------------------------ */
+/* Layout                                                              */
+/* ------------------------------------------------------------------ */
+
+export interface ColumnProps {
+  gap?: number;
+  padding?: number;
+  align?: string;
+  justify?: string;
+}
+
+export const ColumnView: A2UIView<ColumnProps> = ({ props, children }) => (
+  <div
+    data-slot="a2ui-column"
+    className={cn(
+      "flex min-w-0 flex-col",
+      GAP[props.gap ?? 3],
+      props.padding !== undefined ? PADDING[props.padding] : undefined,
+      props.align ? ALIGN[props.align] : undefined,
+      props.justify ? JUSTIFY[props.justify] : undefined,
+    )}
+  >
+    {children}
+  </div>
+);
+
+export interface RowProps extends ColumnProps {
+  wrap?: boolean;
+}
+
+export const RowView: A2UIView<RowProps> = ({ props, children }) => (
+  <div
+    data-slot="a2ui-row"
+    className={cn(
+      "flex min-w-0 flex-row",
+      props.wrap === false ? "flex-nowrap" : "flex-wrap",
+      GAP[props.gap ?? 2],
+      props.padding !== undefined ? PADDING[props.padding] : undefined,
+      ALIGN[props.align ?? "center"],
+      props.justify ? JUSTIFY[props.justify] : undefined,
+    )}
+  >
+    {children}
+  </div>
+);
+
+export interface CardViewProps {
+  accent?: boolean;
+  flush?: boolean;
+}
+
+export const CardView: A2UIView<CardViewProps> = ({ props, children }) => (
+  <Card data-slot="a2ui-card" accent={props.accent}>
+    {props.flush ? (
+      <div className="flex flex-col gap-3">{children}</div>
+    ) : (
+      <CardContent className="flex flex-col gap-3 p-5">{children}</CardContent>
+    )}
+  </Card>
+);
+
+export interface SectionCardViewProps {
+  title: string;
+  description?: string;
+  flush?: boolean;
+}
+
+export const SectionCardView: A2UIView<SectionCardViewProps> = ({ props, children }) => (
+  <SectionCard
+    data-slot="a2ui-section-card"
+    title={props.title}
+    description={props.description}
+    flush={props.flush}
+  >
+    <div className="flex flex-col gap-3">{children}</div>
+  </SectionCard>
+);
+
+export interface DividerProps {
+  orientation?: "horizontal" | "vertical";
+}
+
+export const DividerView: A2UIView<DividerProps> = ({ props }) => (
+  <Separator data-slot="a2ui-divider" orientation={props.orientation ?? "horizontal"} />
+);
+
+export interface SpacerProps {
+  size?: number;
+}
+
+export const SpacerView: A2UIView<SpacerProps> = ({ props }) => (
+  <div data-slot="a2ui-spacer" aria-hidden className={cn("w-full", HEIGHT[props.size ?? 4])} />
+);
+
+/* ------------------------------------------------------------------ */
+/* Text                                                                */
+/* ------------------------------------------------------------------ */
+
+export interface TextProps {
+  text: string;
+  role?: string;
+  tone?: string;
+  align?: string;
+  mono?: boolean;
+}
+
+export const TextView: A2UIView<TextProps> = ({ props }) => (
+  <p
+    data-slot="a2ui-text"
+    data-role={props.role ?? "body"}
+    className={cn(
+      "min-w-0 break-words",
+      TEXT_ROLE[props.role ?? "body"],
+      TEXT_TONE[props.tone ?? "default"],
+      props.align ? TEXT_ALIGN[props.align] : undefined,
+      props.mono ? "font-[family-name:var(--ds-font-mono)]" : undefined,
+    )}
+  >
+    {props.text}
+  </p>
+);
+
+export interface MarkdownViewProps {
+  text: string;
+  compact?: boolean;
+}
+
+export const MarkdownView: A2UIView<MarkdownViewProps> = ({ props }) => (
+  <Markdown data-slot="a2ui-markdown" compact={props.compact}>
+    {props.text}
+  </Markdown>
+);
+
+/* ------------------------------------------------------------------ */
+/* Inputs                                                              */
+/* ------------------------------------------------------------------ */
+
+interface FieldShellProps {
+  label?: string;
+  description?: string;
+  error?: string;
+  children: React.ReactNode;
+  slot: string;
+  orientation?: "vertical" | "horizontal";
+  /**
+   * Ties the label to the control. Base UI's Field associates its own
+   * `Field.Control`; these views render plain cortena-ui controls, so the pair
+   * is wired explicitly rather than left to produce a label with no `for`.
+   */
+  controlId?: string;
+}
+
+function FieldShell({
+  label,
+  description,
+  error,
+  children,
+  slot,
+  orientation,
+  controlId,
+}: FieldShellProps) {
+  return (
+    <Field data-slot={slot} orientation={orientation ?? "vertical"} invalid={Boolean(error)}>
+      {label ? <FieldLabel htmlFor={controlId}>{label}</FieldLabel> : null}
+      {children}
+      {description ? <FieldDescription>{description}</FieldDescription> : null}
+      {error ? <FieldError>{error}</FieldError> : null}
+    </Field>
+  );
+}
+
+export interface TextFieldProps {
+  label?: string;
+  value?: string;
+  placeholder?: string;
+  description?: string;
+  error?: string;
+  type?: "text" | "email" | "url" | "tel" | "number" | "password" | "search";
+  disabled?: boolean;
+  required?: boolean;
+  onChange?: A2UIResolvedAction;
+}
+
+export const TextFieldView: A2UIView<TextFieldProps> = ({
+  props,
+  emit,
+  writeBack,
+  debounceMs,
+}) => {
+  const id = React.useId();
+  const [draft, setDraft] = useDraft(props.value ?? "");
+  const send = useDebouncedEmit(
+    (value) => emit(props.onChange, "change", { value }),
+    debounceMs,
+  );
+  return (
+    <FieldShell
+      slot="a2ui-text-field"
+      label={props.label}
+      description={props.description}
+      error={props.error}
+      controlId={id}
+    >
+      <Input
+        id={id}
+        type={props.type ?? "text"}
+        value={draft}
+        placeholder={props.placeholder}
+        disabled={props.disabled}
+        required={props.required}
+        aria-label={props.label ? undefined : (props.placeholder ?? "Text field")}
+        onChange={(event) => {
+          const next = event.target.value;
+          setDraft(next);
+          writeBack("value", next);
+          send(next);
+        }}
+      />
+    </FieldShell>
+  );
+};
+
+export interface TextAreaProps {
+  label?: string;
+  value?: string;
+  placeholder?: string;
+  description?: string;
+  error?: string;
+  rows?: number;
+  disabled?: boolean;
+  autoGrow?: boolean;
+  onChange?: A2UIResolvedAction;
+}
+
+export const TextAreaView: A2UIView<TextAreaProps> = ({ props, emit, writeBack, debounceMs }) => {
+  const id = React.useId();
+  const [draft, setDraft] = useDraft(props.value ?? "");
+  const send = useDebouncedEmit((value) => emit(props.onChange, "change", { value }), debounceMs);
+  return (
+    <FieldShell
+      slot="a2ui-text-area"
+      label={props.label}
+      description={props.description}
+      error={props.error}
+      controlId={id}
+    >
+      <Textarea
+        id={id}
+        value={draft}
+        rows={props.rows ?? 4}
+        placeholder={props.placeholder}
+        disabled={props.disabled}
+        autoGrow={props.autoGrow}
+        aria-label={props.label ? undefined : (props.placeholder ?? "Text area")}
+        onChange={(event) => {
+          const next = event.target.value;
+          setDraft(next);
+          writeBack("value", next);
+          send(next);
+        }}
+      />
+    </FieldShell>
+  );
+};
+
+export interface SelectOption {
+  value: string;
+  label?: string;
+  disabled?: boolean;
+}
+
+export interface SelectViewProps {
+  label?: string;
+  value?: string;
+  placeholder?: string;
+  description?: string;
+  error?: string;
+  options: SelectOption[];
+  disabled?: boolean;
+  onChange?: A2UIResolvedAction;
+}
+
+export const SelectView: A2UIView<SelectViewProps> = ({ props, emit, writeBack }) => {
+  const [draft, setDraft] = useDraft(props.value ?? null);
+  const items = React.useMemo(
+    () => props.options.map((option) => ({ value: option.value, label: option.label ?? option.value })),
+    [props.options],
+  );
+  return (
+    <FieldShell
+      slot="a2ui-select"
+      label={props.label}
+      description={props.description}
+      error={props.error}
+    >
+      <Select
+        items={items}
+        value={draft}
+        disabled={props.disabled}
+        onValueChange={(next) => {
+          const value = next === null ? "" : String(next);
+          setDraft(value);
+          writeBack("value", value);
+          emit(props.onChange, "change", { value });
+        }}
+      >
+        <SelectTrigger aria-label={props.label ?? props.placeholder ?? "Select"}>
+          <SelectValue placeholder={props.placeholder ?? "Select…"} />
+        </SelectTrigger>
+        <SelectContent>
+          {props.options.map((option) => (
+            <SelectItem key={option.value} value={option.value} disabled={option.disabled}>
+              {option.label ?? option.value}
+            </SelectItem>
+          ))}
+        </SelectContent>
+      </Select>
+    </FieldShell>
+  );
+};
+
+export interface CheckboxViewProps {
+  label?: string;
+  checked?: boolean;
+  description?: string;
+  disabled?: boolean;
+  onChange?: A2UIResolvedAction;
+}
+
+export const CheckboxView: A2UIView<CheckboxViewProps> = ({ props, emit, writeBack }) => {
+  const [draft, setDraft] = useDraft(props.checked ?? false);
+  return (
+    <FieldShell
+      slot="a2ui-checkbox"
+      description={props.description}
+      orientation="horizontal"
+    >
+      <label className="flex items-start gap-3 text-[length:var(--ds-text-caption-lg)] text-[color:var(--ds-foreground)]">
+        <span className="flex h-5 items-center">
+          <Checkbox
+            checked={draft}
+            disabled={props.disabled}
+            aria-label={props.label ?? "Checkbox"}
+            onCheckedChange={(checked) => {
+              setDraft(checked);
+              writeBack("checked", checked);
+              emit(props.onChange, "change", { checked });
+            }}
+          />
+        </span>
+        <span>{props.label}</span>
+      </label>
+    </FieldShell>
+  );
+};
+
+export interface SwitchViewProps extends CheckboxViewProps {}
+
+export const SwitchView: A2UIView<SwitchViewProps> = ({ props, emit, writeBack }) => {
+  const [draft, setDraft] = useDraft(props.checked ?? false);
+  return (
+    <FieldShell slot="a2ui-switch" description={props.description} orientation="horizontal">
+      <label className="flex items-center gap-3 text-[length:var(--ds-text-caption-lg)] text-[color:var(--ds-foreground)]">
+        <Switch
+          checked={draft}
+          disabled={props.disabled}
+          aria-label={props.label ?? "Switch"}
+          onCheckedChange={(checked) => {
+            setDraft(checked);
+            writeBack("checked", checked);
+            emit(props.onChange, "change", { checked });
+          }}
+        />
+        <span>{props.label}</span>
+      </label>
+    </FieldShell>
+  );
+};
+
+export interface RadioGroupViewProps {
+  label?: string;
+  value?: string;
+  description?: string;
+  options: SelectOption[];
+  disabled?: boolean;
+  onChange?: A2UIResolvedAction;
+}
+
+export const RadioGroupView: A2UIView<RadioGroupViewProps> = ({ props, emit, writeBack }) => {
+  const [draft, setDraft] = useDraft(props.value ?? "");
+  return (
+    <FieldShell
+      slot="a2ui-radio-group"
+      label={props.label}
+      description={props.description}
+    >
+      <RadioGroup
+        aria-label={props.label ?? "Options"}
+        value={draft}
+        disabled={props.disabled}
+        onValueChange={(next) => {
+          const value = String(next);
+          setDraft(value);
+          writeBack("value", value);
+          emit(props.onChange, "change", { value });
+        }}
+      >
+        {props.options.map((option) => (
+          <label
+            key={option.value}
+            className="flex items-start gap-3 text-[length:var(--ds-text-caption-lg)] text-[color:var(--ds-foreground)]"
+          >
+            <span className="flex h-5 items-center">
+              <RadioGroupItem value={option.value} disabled={option.disabled} />
+            </span>
+            <span>{option.label ?? option.value}</span>
+          </label>
+        ))}
+      </RadioGroup>
+    </FieldShell>
+  );
+};
+
+export interface DateFieldViewProps {
+  label?: string;
+  /** ISO `yyyy-mm-dd`; the wire format for a date in A2UI. */
+  value?: string;
+  min?: string;
+  max?: string;
+  description?: string;
+  error?: string;
+  disabled?: boolean;
+  onChange?: A2UIResolvedAction;
+}
+
+export const DateFieldView: A2UIView<DateFieldViewProps> = ({ props, emit, writeBack }) => {
+  const id = React.useId();
+  const bound = props.value ? parseDateISO(props.value) : undefined;
+  const [draft, setDraft] = useDraft<Date | undefined>(bound, props.value ?? "");
+  return (
+    <FieldShell
+      slot="a2ui-date-field"
+      label={props.label}
+      description={props.description}
+      error={props.error}
+      controlId={id}
+    >
+      <DateField
+        id={id}
+        value={draft}
+        min={props.min ? parseDateISO(props.min) : undefined}
+        max={props.max ? parseDateISO(props.max) : undefined}
+        disabled={props.disabled}
+        invalid={Boolean(props.error)}
+        aria-label={props.label ?? "Date"}
+        onValueChange={(date) => {
+          setDraft(date);
+          const value = date ? formatDateISO(date) : "";
+          writeBack("value", value);
+          emit(props.onChange, "change", { value });
+        }}
+      />
+    </FieldShell>
+  );
+};
+
+export interface ButtonViewProps {
+  label: string;
+  variant?: "primary" | "secondary" | "outline" | "ghost" | "soft" | "destructive" | "link";
+  size?: "sm" | "md" | "lg";
+  disabled?: boolean;
+  /** Report the whole surface data model with the action, for a form submit. */
+  submit?: boolean;
+  onPress?: A2UIResolvedAction;
+}
+
+export const ButtonView: A2UIView<ButtonViewProps> = ({ props, emit, dataModel }) => (
+  <Button
+    data-slot="a2ui-button"
+    className={INLINE}
+    variant={props.variant ?? "primary"}
+    size={props.size ?? "md"}
+    disabled={props.disabled}
+    onClick={() =>
+      emit(
+        props.onPress,
+        props.submit ? "submit" : "press",
+        props.submit ? { data: dataModel } : {},
+      )
+    }
+  >
+    {props.label}
+  </Button>
+);
+
+export interface ButtonLinkViewProps {
+  label: string;
+  href: string;
+  variant?: ButtonViewProps["variant"];
+  size?: ButtonViewProps["size"];
+  target?: "_self" | "_blank";
+}
+
+// ButtonLink sets its own `data-slot` after spreading props, so the A2UI marker
+// goes on a wrapper rather than being silently dropped.
+export const ButtonLinkView: A2UIView<ButtonLinkViewProps> = ({ props }) => (
+  <span data-slot="a2ui-button-link" className={cn("inline-flex", INLINE)}>
+    <ButtonLink
+      variant={props.variant ?? "secondary"}
+      size={props.size ?? "md"}
+      href={props.href}
+      target={props.target}
+      rel={props.target === "_blank" ? "noopener noreferrer" : undefined}
+    >
+      {props.label}
+    </ButtonLink>
+  </span>
+);
+
+export interface LinkViewProps {
+  label: string;
+  href: string;
+  target?: "_self" | "_blank";
+}
+
+export const LinkView: A2UIView<LinkViewProps> = ({ props }) => (
+  <a
+    data-slot="a2ui-link"
+    href={props.href}
+    target={props.target}
+    rel={props.target === "_blank" ? "noopener noreferrer" : undefined}
+    className={cn(
+      INLINE,
+      "text-[length:var(--ds-text-body-sm)] text-[color:var(--ds-primary)] underline underline-offset-4",
+      "hover:text-[color:var(--ds-primary-hover)]",
+    )}
+  >
+    {props.label}
+  </a>
+);
+
+/* ------------------------------------------------------------------ */
+/* Feedback                                                            */
+/* ------------------------------------------------------------------ */
+
+export interface BadgeViewProps {
+  label: string;
+  variant?: "default" | "success" | "warning" | "danger" | "info" | "neutral" | "outline";
+}
+
+export const BadgeView: A2UIView<BadgeViewProps> = ({ props }) => (
+  <Badge data-slot="a2ui-badge" className={INLINE} variant={props.variant ?? "default"}>
+    {props.label}
+  </Badge>
+);
+
+export interface AlertViewProps {
+  title?: string;
+  description?: string;
+  variant?: "default" | "success" | "warn" | "danger" | "info";
+}
+
+export const AlertView: A2UIView<AlertViewProps> = ({ props }) => {
+  const variant = props.variant ?? "default";
+  return (
+    <Alert data-slot="a2ui-alert" variant={variant}>
+      <AlertIcon>{ALERT_ICON[variant]}</AlertIcon>
+      <div>
+        {props.title ? <AlertTitle>{props.title}</AlertTitle> : null}
+        {props.description ? <AlertDescription>{props.description}</AlertDescription> : null}
+      </div>
+    </Alert>
+  );
+};
+
+export interface ProgressViewProps {
+  /** `null` renders the indeterminate bar. */
+  value?: number | null;
+  max?: number;
+  label?: string;
+  showValue?: boolean;
+}
+
+export const ProgressViewComponent: A2UIView<ProgressViewProps> = ({ props }) => (
+  <Progress
+    data-slot="a2ui-progress"
+    value={props.value === undefined ? null : props.value}
+    max={props.max}
+    aria-label={props.label ?? "Progress"}
+  >
+    {props.label ? <ProgressLabel>{props.label}</ProgressLabel> : null}
+    {props.showValue === false ? null : <ProgressValue />}
+  </Progress>
+);
+
+export interface StatusDotViewProps {
+  label?: string;
+  tone?: "accent" | "success" | "warning" | "danger" | "info" | "neutral";
+  live?: boolean;
+}
+
+export const StatusDotView: A2UIView<StatusDotViewProps> = ({ props }) => (
+  <StatusDot
+    data-slot="a2ui-status-dot"
+    className={INLINE}
+    tone={props.tone ?? "accent"}
+    live={props.live}
+    label={props.label}
+  />
+);
+
+export interface EmptyStateViewProps {
+  title: string;
+  description?: string;
+  size?: "default" | "compact";
+}
+
+export const EmptyStateView: A2UIView<EmptyStateViewProps> = ({ props, children }) => (
+  <EmptyState
+    data-slot="a2ui-empty-state"
+    title={props.title}
+    description={props.description}
+    size={props.size ?? "compact"}
+    action={children.length > 0 ? <div className="flex gap-2">{children}</div> : undefined}
+  />
+);
+
+/* ------------------------------------------------------------------ */
+/* Data                                                                */
+/* ------------------------------------------------------------------ */
+
+export interface A2UIColumn {
+  id: string;
+  label?: string;
+  align?: "start" | "center" | "end";
+  filter?: "faceted" | "text";
+  width?: number;
+}
+
+/**
+ * Where a table's rows come from.
+ *
+ * `client` carries the rows inline, which suits a short result an agent
+ * already has. `server` carries a handle instead: the agent obtains a
+ * `sourceId` from a tool and the host resolves it through
+ * `resolveDataSource`, so search, sort and paging run on the backend and the
+ * agent never has to put ten thousand rows in a message.
+ */
+export type A2UITableSource =
+  | { kind: "client"; rows: A2UIRow[] }
+  | { kind: "server"; sourceId: string };
+
+export interface DataTableViewProps {
+  columns: A2UIColumn[];
+  dataSource: A2UITableSource;
+  pageSize?: number;
+  density?: "default" | "compact";
+  searchPlaceholder?: string;
+  emptyMessage?: string;
+  maxHeight?: number;
+  onRowClick?: A2UIResolvedAction;
+}
+
+export const DataTableView: A2UIView<DataTableViewProps> = ({
+  props,
+  emit,
+  resolveDataSource,
+}) => {
+  const columns = React.useMemo<DataTableColumnDef<A2UIRow>[]>(
+    () =>
+      props.columns.map((column) => ({
+        id: column.id,
+        accessorKey: column.id,
+        header: column.label ?? column.id,
+        size: column.width,
+        meta: {
+          align: column.align,
+          filter: column.filter,
+          label: column.label ?? column.id,
+        },
+      })) as DataTableColumnDef<A2UIRow>[],
+    [props.columns],
+  );
+
+  const source = props.dataSource;
+  const resolved: DataSource<A2UIRow> | undefined =
+    source.kind === "client" ? { kind: "client", rows: source.rows } : resolveDataSource(source.sourceId);
+
+  if (!resolved) {
+    return (
+      <A2UIErrorCard
+        title="Unknown data source"
+        detail={`No data source is registered for "${(source as { sourceId: string }).sourceId}". The host resolves a server table through resolveDataSource.`}
+      />
+    );
+  }
+
+  return (
+    <div data-slot="a2ui-data-table">
+      <DataTable<A2UIRow>
+        columns={columns}
+        dataSource={resolved}
+        pageSize={props.pageSize ?? 10}
+        density={props.density ?? "compact"}
+        maxHeight={props.maxHeight}
+        searchPlaceholder={props.searchPlaceholder}
+        emptyMessage={props.emptyMessage}
+        onRowClick={(row) => emit(props.onRowClick, "rowClick", { row })}
+      />
+    </div>
+  );
+};
+
+export interface ChartViewProps {
+  type: ChartType;
+  data: unknown;
+  title?: string;
+  height?: number;
+  stacked?: boolean;
+  legend?: boolean;
+  grid?: boolean;
+  scale?: "sequential" | "diverging";
+  indexBy?: string;
+  keys?: string[];
+  from?: string;
+  to?: string;
+  emptyMessage?: string;
+}
+
+export const ChartView: A2UIView<ChartViewProps> = ({ props }) => (
+  <div data-slot="a2ui-chart" className="flex flex-col gap-2">
+    {props.title ? (
+      <p className="text-[length:var(--ds-text-caption-lg)] font-medium text-[color:var(--ds-foreground)]">
+        {props.title}
+      </p>
+    ) : null}
+    <Chart
+      type={props.type}
+      data={props.data as ChartDataFor<ChartType>}
+      height={props.height ?? 260}
+      stacked={props.stacked}
+      legend={props.legend}
+      grid={props.grid}
+      scale={props.scale}
+      indexBy={props.indexBy}
+      keys={props.keys}
+      from={props.from}
+      to={props.to}
+      emptyMessage={props.emptyMessage}
+    />
+  </div>
+);
+
+/* ------------------------------------------------------------------ */
+/* Tabs and media                                                      */
+/* ------------------------------------------------------------------ */
+
+export interface TabDescriptor {
+  value: string;
+  label: string;
+}
+
+export interface TabsViewProps {
+  tabs: TabDescriptor[];
+  value?: string;
+  onChange?: A2UIResolvedAction;
+}
+
+export const TabsView: A2UIView<TabsViewProps> = ({ props, children, emit, writeBack }) => {
+  const first = props.tabs[0]?.value ?? "";
+  const [draft, setDraft] = useDraft(props.value ?? first);
+  return (
+    <Tabs
+      data-slot="a2ui-tabs"
+      value={draft}
+      onValueChange={(next) => {
+        const value = String(next);
+        setDraft(value);
+        writeBack("value", value);
+        emit(props.onChange, "tabChange", { value });
+      }}
+    >
+      <TabsList>
+        {props.tabs.map((tab) => (
+          <TabsTrigger key={tab.value} value={tab.value}>
+            {tab.label}
+          </TabsTrigger>
+        ))}
+      </TabsList>
+      {props.tabs.map((tab, index) => (
+        <TabsContent key={tab.value} value={tab.value}>
+          {children[index] ?? null}
+        </TabsContent>
+      ))}
+    </Tabs>
+  );
+};
+
+export interface ImageViewProps {
+  src: string;
+  alt: string;
+  width?: number;
+  height?: number;
+  rounded?: boolean;
+  fit?: "cover" | "contain";
+}
+
+export const ImageView: A2UIView<ImageViewProps> = ({ props }) => (
+  <img
+    data-slot="a2ui-image"
+    src={props.src}
+    alt={props.alt}
+    width={props.width}
+    height={props.height}
+    className={cn(
+      INLINE,
+      "max-w-full",
+      props.fit === "cover" ? "object-cover" : "object-contain",
+      props.rounded === false ? undefined : "rounded-[var(--ds-radius-md)]",
+      "border border-[var(--ds-border-subtle)]",
+    )}
+  />
+);
+
+/* ------------------------------------------------------------------ */
+/* Error card                                                          */
+/* ------------------------------------------------------------------ */
+
+/**
+ * What the renderer draws instead of a component it cannot draw.
+ *
+ * Never raw markup and never the offending payload as HTML: the detail is set
+ * as text, so a malformed message cannot inject anything. This is the
+ * "fallback: an error card on malformed payloads" of `05-agent-ui.md`.
+ */
+export function A2UIErrorCard({
+  title,
+  detail,
+  componentId,
+}: {
+  title: string;
+  detail?: string;
+  componentId?: string;
+}) {
+  return (
+    <Alert data-slot="a2ui-error" variant="danger" role="alert">
+      <AlertIcon>
+        <OctagonAlert />
+      </AlertIcon>
+      <div className="min-w-0">
+        <AlertTitle>{title}</AlertTitle>
+        {detail ? (
+          <AlertDescription className="font-[family-name:var(--ds-font-mono)] text-[length:var(--ds-text-caption)] break-words">
+            {detail}
+          </AlertDescription>
+        ) : null}
+        {componentId ? (
+          <AlertDescription className="text-[length:var(--ds-text-caption-sm)] text-[color:var(--ds-muted-foreground)]">
+            Component id: {componentId}
+          </AlertDescription>
+        ) : null}
+      </div>
+    </Alert>
+  );
+}
+
+/** Re-exported so consumers can type an action handler without the message module. */
+export type { A2UIAction };