@horon-ai/react 0.1.0 → 0.1.2

package/src/components/list-detail.tsx

@@ -6,33 +6,73 @@ import { Button } from "./button";
 import { CodePanel } from "./code-panel";
 import { LiquidGlass } from "./liquid-glass";
 
+/** One selectable row of a {@link ListDetail} list. */
 export type ListDetailItem = {
+  /** Stable identifier; it is the value the selection reports and the React key. */
   id: string;
+  /** Row title, drawn in mono and truncated to one line. */
   title: ReactNode;
+  /** Secondary line under the title, in secondary colour. */
   meta?: ReactNode;
 };
 
+/** A captioned group of {@link ListDetailItem} rows. */
 export type ListDetailGroup = {
+  /** Stable identifier used as the group's React key. */
   id: string;
+  /** Caption above the rows, in 11px semibold secondary text. */
   label: ReactNode;
+  /** Rows of this group, in display order. */
   items: ListDetailItem[];
 };
 
+/** Props for {@link ListDetail}: the groups and one render function for the selected item. */
 export type ListDetailProps = Omit<ComponentProps<"div">, "className" | "children" | "onChange"> & {
+  /** Groups rendered into the left list; the flat order also drives the selection fallback. */
   groups: ListDetailGroup[];
+  /** Controlled selected id. Leave unset to let the component hold the selection itself. */
   value?: string;
+  /** Initial selection when uncontrolled. Falls back to the first item of the first group. */
   defaultValue?: string;
+  /** Fires with the new id whenever a row is clicked, controlled or not. */
   onValueChange?: (id: string) => void;
   /** Renders the detail pane for the selected item. */
   children: (item: ListDetailItem) => ReactNode;
-  /** `solid` (default) is an opaque surface shell with a default border; `glass` is the thick glass shell. */
+  /** `solid` (default) is an opaque surface shell with a default border; `glass` is the thick glass shell. @default "solid" */
   surface?: "solid" | "glass";
+  /** Extra classes on the shell, merged after the built-in ones. */
   className?: string;
 };
 
 /**
  * Paper `List and detail` (1W6P-0): a 16px-radius shell, solid or thick glass, with a 250px list on an inset
  * surface and a detail pane. Selecting a row fills it in 150ms and swaps the detail with a short rise.
+ *
+ * Selection is controlled or uncontrolled like a native input: pass `value` to
+ * own it, or `defaultValue` for the initial row. Below `sm` the two panes stack
+ * instead of shrinking the list. The list is a `role="listbox"` whose rows are
+ * `role="option"` buttons with `aria-selected`; they respond to clicks and the
+ * keyboard's normal button activation.
+ *
+ * @example
+ * ```tsx
+ * <ListDetail
+ *   groups={[
+ *     {
+ *       id: "sources",
+ *       label: "Sources",
+ *       items: [{ id: "readme", title: "README.md", meta: "2.1 KB" }],
+ *     },
+ *   ]}
+ * >
+ *   {(item) => (
+ *     <>
+ *       <ListDetailHeader title={item.title} description="Indexed 4 minutes ago" />
+ *       <ListDetailMeta items={[{ id: "chunks", label: "Chunks", value: 42 }]} />
+ *     </>
+ *   )}
+ * </ListDetail>
+ * ```
  */
 export function ListDetail({
   groups,
@@ -103,16 +143,24 @@ export function ListDetail({
   );
 }
 
+/** Props for {@link ListDetailHeader}: a tile icon, title, description and a right-hand action cluster. */
 export type ListDetailHeaderProps = Omit<ComponentProps<"div">, "className" | "title"> & {
+  /** Glyph on the 40px sky tile; the tile only renders when this is set. */
   icon?: ReactNode;
+  /** Detail title, drawn in mono at `label-lg` semibold. */
   title: ReactNode;
+  /** One line under the title, in body-sm secondary colour. */
   description?: ReactNode;
   /** Right-hand cluster: a state label, a `Switch`, an icon button. */
   actions?: ReactNode;
+  /** Extra classes on the row, merged after the built-in ones. */
   className?: string;
 };
 
-/** Detail header: a 40px sky tile with an 18px icon, title and description, actions on the right. */
+/** Detail header: a 40px sky tile with a 20px icon, title and description, actions on the right.
+ *
+ * Part of {@link ListDetail}.
+ */
 export function ListDetailHeader({ icon, title, description, actions, className, ...props }: ListDetailHeaderProps) {
   return (
     <div className={cn("flex flex-wrap items-center gap-3", className)} {...props}>
@@ -130,12 +178,25 @@ export function ListDetailHeader({ icon, title, description, actions, className,
   );
 }
 
+/** Props for {@link ListDetailMeta}: the label/value pairs of the meta box. */
 export type ListDetailMetaProps = Omit<ComponentProps<"dl">, "className"> & {
-  items: { id: string; label: ReactNode; value: ReactNode }[];
+  /** Pairs rendered in a two-column grid, label over value. */
+  items: {
+    /** Stable identifier of the pair; its React key. */
+    id: string;
+    /** Term above the value, in `label-sm` secondary text. */
+    label: ReactNode;
+    /** Definition under the label, truncated to one line. */
+    value: ReactNode;
+  }[];
+  /** Extra classes on the `dl`, merged after the built-in ones. */
   className?: string;
 };
 
-/** Meta box: a subtle-fill 12px-radius box with equal columns of a label over a 14/20 value. */
+/** Meta box: a subtle-fill 12px-radius box with equal columns of a label over a 14/20 value.
+ *
+ * Part of {@link ListDetail}.
+ */
 export function ListDetailMeta({ items, className, ...props }: ListDetailMetaProps) {
   return (
     <dl
@@ -152,13 +213,21 @@ export function ListDetailMeta({ items, className, ...props }: ListDetailMetaPro
   );
 }
 
+/** Props for {@link ListDetailInstructions}: the block heading, the text and the edit callback. */
 export type ListDetailInstructionsProps = Omit<ComponentProps<"div">, "className" | "onChange"> & {
+  /** Heading above the panel.
+   * @default "Instructions" */
   title?: ReactNode;
   /** Small chip beside the title, such as the file name. */
   tag?: ReactNode;
+  /** Controlled text. Leave unset to let the component hold the draft itself. */
   value?: string;
+  /** Initial text when uncontrolled.
+   * @default "" */
   defaultValue?: string;
+  /** Fires with the full textarea value on every keystroke in edit mode. */
   onValueChange?: (value: string) => void;
+  /** Extra classes on the wrapper, merged after the built-in ones. */
   className?: string;
 };
 
@@ -244,14 +313,21 @@ export function ListDetailInstructions({
   );
 }
 
+/** Props for {@link ListDetailFiles}: the row label and the chips it wraps. */
 export type ListDetailFilesProps = Omit<ComponentProps<"div">, "className"> & {
+  /** Heading above the chips.
+   * @default "Files" */
   label?: ReactNode;
   /** Chips, usually a small `Button` with an icon. */
   children: ReactNode;
+  /** Extra classes on the wrapper, merged after the built-in ones. */
   className?: string;
 };
 
-/** Files row: a 13/18 label over a wrap of 32px glass chips, 6px apart. */
+/** Files row: a 13/18 label over a wrap of 32px glass chips, 6px apart.
+ *
+ * Part of {@link ListDetail}.
+ */
 export function ListDetailFiles({ label = "Files", children, className, ...props }: ListDetailFilesProps) {
   return (
     <div className={cn("flex flex-col gap-2", className)} {...props}>
@@ -261,11 +337,17 @@ export function ListDetailFiles({ label = "Files", children, className, ...props
   );
 }
 
-/** Footer: a 1px top rule and 8px-spaced glass buttons; use `<span className="flex-1" />` as the spacer. */
+/** Footer: a 1px top rule and 8px-spaced glass buttons; use `<span className="flex-1" />` as the spacer.
+ *
+ * Part of {@link ListDetail}.
+ */
 export function ListDetailFooter({
   className,
   ...props
-}: Omit<ComponentProps<"div">, "className"> & { className?: string }) {
+}: Omit<ComponentProps<"div">, "className"> & {
+  /** Extra classes on the row, merged after the built-in ones. */
+  className?: string;
+}) {
   return (
     <div
       className={cn("flex flex-wrap items-center gap-2 border-t border-border-default pt-3.5", className)}

package/src/components/marketplace-card.tsx

@@ -5,23 +5,59 @@ import { cn } from "../lib/cn";
 import { Button } from "./button";
 import { LiquidGlass } from "./liquid-glass";
 
+/** Props for {@link MarketplaceCard}: identity, copy, capability chips and the install action. */
 export type MarketplaceCardProps = Omit<ComponentProps<"div">, "children"> & {
   /** Two-letter initials shown on the 40px ink tile. */
   initials: string;
+  /** Card title on the row beside the tile; truncated in one line. */
   name: ReactNode;
+  /** Publisher line under the name, in caption colour. */
   author?: ReactNode;
+  /** Body copy under the header; any length, wrapped by the paragraph. */
   description?: ReactNode;
-  /** Capability chips, each with an optional 11px icon. */
-  chips?: { id: string; label: ReactNode; icon?: ReactNode }[];
+  /** Capability chips, each with an optional 12px icon. */
+  chips?: {
+    /** Stable key for this chip; also its React key. */
+    id: string;
+    /** Chip text. */
+    label: ReactNode;
+    /** Optional leading icon, rendered at 12px by the chip's `[&_svg]:size-3`. */
+    icon?: ReactNode;
+  }[];
+  /** Rating value shown after a filled star, such as "4.8". Hides the star when unset. */
   score?: ReactNode;
+  /** Install-count caption, separated from the score by a middle dot when both are set. */
   installs?: ReactNode;
+  /** Renders the Install button in the footer when set; receives the native click event. */
   onInstall?: () => void;
+  /** Text of the Install button.
+   * @default "Install" */
   installLabel?: string;
-  /** `solid` (default) is an opaque surface card with a default border; `glass` is the thick glass card. */
+  /** `solid` (default) is an opaque surface card with a default border; `glass` is the thick glass card. @default "solid" */
   surface?: "solid" | "glass";
 };
 
-/** Paper `Marketplace card` (Settings 1VMY-0): solid or thick glass column with tile header, description, chips and a footer with rating and Install. */
+/**
+ * Paper `Marketplace card` (Settings 1VMY-0): solid or thick glass column with tile header, description, chips and a footer with rating and Install.
+ *
+ * The card is a plain `div`, so any extra native attribute (`data-*`, `id`,
+ * `onClick`) passes through. With `surface="glass"` it paints a `LiquidGlass`
+ * layer and every child is positioned to stay above it.
+ *
+ * @example
+ * ```tsx
+ * <MarketplaceCard
+ *   initials="GH"
+ *   name="GitHub"
+ *   author="by Horon"
+ *   description="Read repositories and open pull requests."
+ *   chips={[{ id: "official", label: "Official" }]}
+ *   score="4.8"
+ *   installs="12k installs"
+ *   onInstall={() => install("github")}
+ * />
+ * ```
+ */
 export function MarketplaceCard({
   initials,
   name,

package/src/components/mcp-server-row.tsx

@@ -8,9 +8,24 @@ import { Menu, MenuContent, MenuTrigger } from "./menu";
 
 const pillClass = "inline-flex h-5.5 items-center rounded-full px-2 text-label-sm";
 
+/**
+ * Colour of an MCP server's status pill.
+ *
+ * - `connected` — muted pill with a live dot, the healthy default.
+ * - `warning` — danger-tinted pill with a danger dot, for a server that needs attention.
+ * - `neutral` — muted pill with a placeholder-coloured dot, for an idle or unknown state.
+ */
 export type McpServerStatusTone = "connected" | "warning" | "neutral";
 
-const statusToneClass: Record<McpServerStatusTone, { pill: string; dot: string }> = {
+const statusToneClass: Record<
+  McpServerStatusTone,
+  {
+    /** Classes of the pill itself: background tint and text colour. */
+    pill: string;
+    /** Classes of the 6px dot inside the pill: its fill colour. */
+    dot: string;
+  }
+> = {
   connected: { pill: "bg-overlay-ink-6 text-text-primary", dot: "bg-status-live" },
   warning: { pill: "bg-accent-red-500-14 text-text-danger", dot: "bg-text-danger" },
   neutral: { pill: "bg-overlay-ink-6 text-text-secondary", dot: "bg-text-placeholder" },
@@ -26,29 +41,60 @@ const withKeys = (values: string[] | undefined) => {
   });
 };
 
+/** Props for {@link McpServerRow}: the server identity, its tags and status, and the two actions. */
 export type McpServerRowProps = Omit<ComponentProps<"div">, "className" | "title"> & {
   /** Server name; its first two letters fill the 40px tile unless `initials` is set. */
   name: string;
+  /** Overrides the two-letter tile text derived from `name`; up to two characters read best. */
   initials?: string;
   /** Tags next to the name, such as "Official". */
   tags?: string[];
   /** Tags tinted brand, such as "All devices". */
   brandTags?: string[];
+  /** Body line under the tags, in body-sm secondary colour. */
   description?: ReactNode;
   /** Meta line, joined by "·". */
   meta?: string[];
+  /** Text inside the status pill.
+   * @default "Connected" */
   statusLabel?: ReactNode;
-  /** Colour of the status pill: a live dot by default, a danger tint for a warning, a muted dot for a neutral state. */
+  /** Colour of the status pill: a live dot by default, a danger tint for a warning, a muted dot for a neutral state.
+   * @default "connected" */
   statusTone?: McpServerStatusTone;
+  /** Text of the Configure button.
+   * @default "Configure" */
   configureLabel?: ReactNode;
+  /** Fires when the Configure button is clicked; the button always renders, so pass this to make it do anything. */
   onConfigure?: () => void;
   /** Overflow menu items (`MenuItem`). Hides the overflow button when absent. */
   menu?: ReactNode;
+  /** Accessible label of the overflow button.
+   * @default "More" */
   menuLabel?: string;
+  /** Extra classes on the row `div`, merged after the built-in ones. */
   className?: string;
 };
 
-/** Paper `MCP server row` (1VHS-0): a divided row with a 40px tile, tags, a status pill and two actions. */
+/**
+ * Paper `MCP server row` (1VHS-0): a divided row with a 40px tile, tags, a status pill and two actions.
+ *
+ * A row of a settings list rather than a card: it draws only a bottom border and
+ * drops it on the last child. The main cluster wraps (`basis-40`) so the row stays
+ * usable in a narrow column; its overflow menu opens from the row and portals to
+ * `document.body`.
+ *
+ * @example
+ * ```tsx
+ * <McpServerRow
+ *   name="Linear"
+ *   tags={["Official"]}
+ *   description="Read issues and projects."
+ *   meta={["12 tools", "OAuth"]}
+ *   onConfigure={() => openConfig("linear")}
+ *   menu={<MenuItem>Reconnect</MenuItem>}
+ * />
+ * ```
+ */
 export function McpServerRow({
   name,
   initials,

package/src/components/menu.tsx

@@ -3,15 +3,38 @@ import { createContext, useContext, type ComponentProps, type ReactNode } from "
 
 import { cn } from "../lib/cn";
 
-type WithClass<T> = Omit<T, "className"> & { className?: string };
+type WithClass<T> = Omit<T, "className"> & {
+  /** Extra classes merged onto the element the part renders. */
+  className?: string;
+};
 
+/**
+ * Visual treatment of the popup.
+ *
+ * - `glass` — the Figma `Menu` on the veil: 20px radius, 40px rows, 220px wide.
+ * - `solid` — the Account / Workspace menu that opens over glass chrome: opaque fill, 18px radius, `shadow-popover`, 36px rows, 256px wide.
+ * - `paper` — the Paper workspace switcher: default fill, 1px default border, 14px radius, `0 12 32` shadow, 304px wide, 36px rows.
+ */
 export type MenuSurface = "glass" | "solid" | "paper";
 
 const SurfaceContext = createContext<MenuSurface>("glass");
 
+/**
+ * Root of a menu; owns open state and the trigger/popup pair. Re-exported from
+ * Base UI's `Menu.Root`, so it accepts `open`, `defaultOpen`, `onOpenChange` and
+ * `modal`.
+ */
 export const Menu = BaseMenu.Root;
+
+/**
+ * The element that opens the menu. Base UI gives it `aria-haspopup` and the
+ * expanded state; use `render` to make an existing button the trigger.
+ *
+ * Part of {@link MenuContent}.
+ */
 export const MenuTrigger = BaseMenu.Trigger;
 
+/** Props for {@link MenuContent}: the surface variant and the Base UI positioner offsets. */
 export type MenuContentProps = WithClass<ComponentProps<typeof BaseMenu.Popup>> & {
   /**
    * `glass` is the Figma `Menu` on the veil (20px radius, 40px rows).
@@ -19,21 +42,58 @@ export type MenuContentProps = WithClass<ComponentProps<typeof BaseMenu.Popup>>
    * (opaque fill, 18px radius, soft shadow, 36px rows).
    * `paper` is the Paper workspace switcher: default fill, 1px default border, 14px radius,
    * 0 12 32 shadow, 304px wide, 36px rows.
+   * @default "solid"
    */
   surface?: MenuSurface;
+  /** Preferred side of the anchor the popup opens on; flips when it does not fit. */
   side?: ComponentProps<typeof BaseMenu.Positioner>["side"];
+  /** Alignment of the popup against the anchor.
+   * @default "start" */
   align?: ComponentProps<typeof BaseMenu.Positioner>["align"];
+  /** Gap in px between the anchor and the popup.
+   * @default 8 */
   sideOffset?: number;
+  /** Offset in px along the alignment axis. */
   alignOffset?: number;
 };
 
+/**
+ * Radius, border, fill and shadow of the popup per {@link MenuSurface}. Width is
+ * not part of this map; `MenuContent` applies it directly (`w-55` glass, `w-76`
+ * paper, `w-64` solid).
+ */
 export const menuPopupClass = {
   glass: "rounded-xl veil-overlay",
   solid: "rounded-[18px] bg-glass-fill-solid shadow-popover",
   paper: "rounded-[14px] border border-border-default bg-bg-default shadow-[0_12px_32px_#0A142424]",
 } as const;
 
-/** Figma `Menus and popovers` (88:495): `Menu`, `Account menu` and `Workspace menu`. */
+/**
+ * Figma `Menus and popovers` (88:495): `Menu`, `Account menu` and `Workspace menu`.
+ *
+ * The popup portals to `document.body` through `BaseMenu.Portal`, so it escapes
+ * any `overflow: hidden` ancestor and always paints above the page at `z-50`.
+ * Base UI handles keyboard navigation, focus return to the trigger and dismissal;
+ * the surface prop only changes the look. Its width is capped at the viewport
+ * minus 32px so the 304px `paper` menu still fits a 320px screen.
+ *
+ * @example
+ * ```tsx
+ * <Menu>
+ *   <MenuTrigger render={<Button variant="solid" />}>Account</MenuTrigger>
+ *   <MenuContent align="end">
+ *     <MenuLabel>Workspaces</MenuLabel>
+ *     <MenuItem icon={<GearSix />} trailing="⌘," onClick={openSettings}>
+ *       Settings
+ *     </MenuItem>
+ *     <MenuSeparator />
+ *     <MenuItem icon={<Trash />} danger onClick={remove}>
+ *       Delete
+ *     </MenuItem>
+ *   </MenuContent>
+ * </Menu>
+ * ```
+ */
 export function MenuContent({
   surface = "solid",
   side,
@@ -72,18 +132,27 @@ export function MenuContent({
   );
 }
 
+/** Props for {@link MenuItem}: optional leading icon, description line and trailing shortcut. */
 export type MenuItemProps = WithClass<ComponentProps<typeof BaseMenu.Item>> & {
   /** 18px leading icon, or a 28px workspace tile. */
   icon?: ReactNode;
-  /** Caption under the label, such as "3 members". */
+  /** Caption under the label, such as "3 members". Grows the row to 48px. */
   description?: ReactNode;
   /** Right side: a shortcut such as "⌘C", or a check. */
   trailing?: ReactNode;
+  /** Paints the label and icon in `text-text-danger`; pair it with `onClick` or `disabled` for a destructive command. */
   danger?: boolean;
   /** Current choice drawn on the brand tint (Paper workspace switcher). */
   selected?: boolean;
 };
 
+/**
+ * One row of a {@link MenuContent}: icon, label, optional description and trailing
+ * shortcut. It is a Base UI `Menu.Item`, so it closes the menu on click, is
+ * disabled through `disabled` and highlighted with the arrow keys.
+ *
+ * Part of {@link MenuContent}.
+ */
 export function MenuItem({
   icon,
   description,
@@ -131,6 +200,17 @@ export function MenuItem({
   );
 }
 
+/**
+ * A 1px rule between groups of items, drawn full width inside the popup's own
+ * `p-1.5` inset. Its wrapper adds `px-1.5` on glass and `px-2.5` on solid and
+ * paper, so the line starts 12px from the popup edge on glass and 16px on the
+ * others: on solid and paper it lines up with the row padding (`px-2.5`), while
+ * the glass rows are inset further (`px-3`) and the rule runs wider than they do.
+ *
+ * It renders as a Base UI `Menu.Separator`, so it is hidden from the keyboard.
+ *
+ * Part of {@link MenuContent}.
+ */
 export function MenuSeparator({ className, ...props }: WithClass<ComponentProps<typeof BaseMenu.Separator>>) {
   const surface = useContext(SurfaceContext);
   return (

package/src/components/message-extras.tsx

@@ -1,12 +1,19 @@
 import { Copy, FileText, X } from "@phosphor-icons/react";
-import { useEffect, useState, type ComponentProps, type ReactNode } from "react";
+import type { ComponentProps, ReactNode } from "react";
 
+import { useCopyToClipboard } from "../hooks/use-copy-to-clipboard";
 import { cn } from "../lib/cn";
 import { IconButton } from "./icon-button";
 import { LiquidGlass } from "./liquid-glass";
 
 /** Figma `Date separator` (Message extras 109:667): caption between two 10% ink lines. */
-export function DateSeparator({ children, className }: { children: ReactNode; className?: string }) {
+// prettier-ignore
+export function DateSeparator({ children, className }: {
+  /** Caption text between the rules, such as "Today" or "Mar 4". */
+  children: ReactNode;
+  /** Extra classes on the row, merged after the built-in ones. */
+  className?: string;
+}) {
   return (
     <div role="separator" className={cn("flex items-center gap-3", className)}>
       <span className="h-px flex-1 bg-overlay-ink-10" />
@@ -16,17 +23,43 @@ export function DateSeparator({ children, className }: { children: ReactNode; cl
   );
 }
 
-export type MessageAction = { label: string; icon: ReactNode; onClick?: () => void };
+/** One button of a {@link MessageActions} pill. */
+export type MessageAction = {
+  /** Accessible label of the button; also its React key, so keep labels unique within a pill. */
+  label: string;
+  /** 16px glyph; sized by the pill's `[&>svg]:size-4`. */
+  icon: ReactNode;
+  /** Fires on click. */
+  onClick?: () => void;
+};
 
-/** Figma `Message actions` (109:667): a pill of 30px icon buttons with 16px icons, solid or regular glass. */
+/**
+ * Figma `Message actions` (109:667): a pill of 30px icon buttons with 16px icons, solid or regular glass.
+ *
+ * Hovering a button fills a circle behind the glyph; each button carries its
+ * label as `aria-label` and the pill exposes `role="toolbar"`. With
+ * `surface="glass"` it paints a `LiquidGlass` layer and the buttons sit above it.
+ *
+ * @example
+ * ```tsx
+ * <MessageActions
+ *   actions={[
+ *     { label: "Copy", icon: <Copy />, onClick: () => copy(text) },
+ *     { label: "Regenerate", icon: <ArrowsClockwise />, onClick: regenerate },
+ *   ]}
+ * />
+ * ```
+ */
 export function MessageActions({
   actions,
   surface = "solid",
   className,
 }: {
+  /** Buttons of the pill, rendered in order; each needs a unique label. */
   actions: MessageAction[];
-  /** `solid` (default) is an opaque surface pill with a default border; `glass` is the regular glass pill. */
+  /** `solid` (default) is an opaque surface pill with a default border; `glass` is the regular glass pill. @default "solid" */
   surface?: "solid" | "glass";
+  /** Extra classes on the pill, merged after the built-in ones. */
   className?: string;
 }) {
   return (
@@ -54,14 +87,20 @@ export function MessageActions({
   );
 }
 
+/** Props for {@link Attachment}: what the file is, how it looks and whether it can be removed. */
 export type AttachmentProps = {
+  /** File name, truncated to one line. */
   name: ReactNode;
   /** Caption, such as "PDF · 2.4 MB". */
   detail?: ReactNode;
   /** Image thumbnail URL; files show a document icon on a sky tile. */
   thumbnail?: string;
+  /** Renders the 32px remove button when set. */
   onRemove?: () => void;
+  /** Accessible label of the remove button.
+   * @default "Remove" */
   removeLabel?: string;
+  /** Extra classes on the card, merged after the built-in ones. */
   className?: string;
 };
 
@@ -102,11 +141,19 @@ export function Attachment({ name, detail, thumbnail, onRemove, removeLabel = "R
   );
 }
 
+/** Props for {@link CodeBlock}: the code text, its language caption and the copy-button labels. */
 export type CodeBlockProps = Omit<ComponentProps<"div">, "className" | "children"> & {
+  /** Source text, rendered verbatim inside a `<code>` in a horizontal scroller. */
   code: string;
+  /** Caption in the header bar, such as "tsx"; the space is kept even when empty. */
   language?: string;
+  /** Copy-button text before the copy succeeds.
+   * @default "Copy" */
   copyLabel?: string;
+  /** Copy-button text for 1500ms after a successful copy.
+   * @default "Copied" */
   copiedLabel?: string;
+  /** Extra classes on the outer `div`, merged after the built-in ones. */
   className?: string;
 };
 
@@ -119,25 +166,14 @@ export function CodeBlock({
   className,
   ...props
 }: CodeBlockProps) {
-  const [copied, setCopied] = useState(false);
-  useEffect(() => {
-    if (!copied) return undefined;
-    const timer = setTimeout(() => setCopied(false), 1500);
-    return () => clearTimeout(timer);
-  }, [copied]);
-  const copy = () => {
-    navigator.clipboard?.writeText(code).then(
-      () => setCopied(true),
-      () => undefined,
-    );
-  };
+  const { copied, copy } = useCopyToClipboard(1500);
   return (
     <div className={cn("flex flex-col overflow-clip rounded-lg bg-surface-ink", className)} {...props}>
       <div className="flex items-center gap-2 bg-bg-surface-6 py-2 pr-3.5 pl-3.5 text-caption text-text-on-ink">
         <span className="min-w-0 flex-1 opacity-70">{language}</span>
         <button
           type="button"
-          onClick={copy}
+          onClick={() => copy(code)}
           className="flex shrink-0 motion-press cursor-pointer items-center gap-1 focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-text-brand"
         >
           <Copy aria-hidden className="size-3.5 shrink-0" />