@horon-ai/react 0.1.1 → 0.1.2

package/src/components/kbd.tsx

@@ -5,13 +5,16 @@ import { cn } from "../lib/cn";
 import { formatShortcut } from "../lib/platform";
 import type { ControlSize } from "../lib/size";
 
+/** Height rung of the chip, shared with the other sized controls: `sm`, `md`, `lg`. */
 export type KbdSize = ControlSize;
 
+/** Props of {@link Kbd}: the native `kbd` attributes plus the chip size. */
 export type KbdProps = Omit<ComponentProps<"kbd">, "className"> & {
-  /** Chip size: `sm` tighter caption, `md` the Command palette chip (default), `lg` label-sm with more padding. */
+  /** Chip size: `sm` tighter caption, `md` the Command palette chip (default), `lg` label-sm with more padding. @default "md" */
   size?: KbdSize;
   /** Shortcut such as `Mod+Enter`, drawn with the OS's key labels (`⌘↵` / `Ctrl+Enter`) instead of children. */
   keys?: string;
+  /** Extra classes for the `kbd` element. */
   className?: string;
 };
 
@@ -22,7 +25,30 @@ const sizeClass: Record<KbdSize, string> = {
   lg: "h-6 gap-1 px-2 text-label-sm [&_svg]:size-3.5",
 };
 
-/** Figma `Kbd` (Command palette 110:676): a 6% ink chip with caption text. */
+/**
+ * Figma `Kbd` (Command palette 110:676): a 6% ink chip with caption text.
+ *
+ * A `<kbd>` for a keyboard shortcut: inline-flex, `rounded-xs`, secondary text, centred on a trimmed
+ * line box so the glyph sits optically centred in the chip. Pass `keys` as a `+`-joined shortcut such as
+ * `Mod+Enter` and the chip draws the OS's labels — `⌘↵` on macOS and iOS, `Ctrl+Enter` on Windows, Linux
+ * and Android, and the Mac symbols whenever the OS is still unknown (server render, first hydration pass).
+ * Without `keys` it renders `children`, so several chips can be composed by hand
+ * (`<Kbd>⌘</Kbd><Kbd>K</Kbd>`). Sizes are 16/20/24px tall, and any icon inside is resized with the chip
+ * (`2.5`/`3`/`3.5`), so pass a bare Phosphor icon or glyph.
+ *
+ * @example
+ * ```tsx
+ * import { Kbd } from "@horon-ai/react";
+ *
+ * function Hint() {
+ *   return (
+ *     <span className="flex items-center gap-1 text-caption">
+ *       Search <Kbd keys="Mod+K" />
+ *     </span>
+ *   );
+ * }
+ * ```
+ */
 export function Kbd({ size = "md", keys, className, children, ...props }: KbdProps) {
   const { os } = usePlatform();
   return (

package/src/components/knowledge-base-panel.tsx

@@ -5,32 +5,51 @@ import { cn } from "../lib/cn";
 import { PanelPillTabs } from "./bot-instructions-panel";
 import { Spinner } from "./spinner";
 
+/** One pill tab of {@link KnowledgeBasePanel}, such as "All" or "Documents". */
 export type KnowledgeBaseTab = {
+  /** Stable identifier; it is the tab's value and React key. */
   id: string;
+  /** Tab text. */
   label: ReactNode;
+  /** Optional count drawn in caption colour right of the label. */
   count?: number;
 };
 
+/** Props for {@link KnowledgeBasePanel}: header, tabs, indexing state and the dropzone handler. */
 export type KnowledgeBasePanelProps = Omit<ComponentProps<"section">, "className" | "title" | "onChange"> & {
+  /** Panel heading, rendered as the `h3`. */
   title: ReactNode;
   /** The 12/18 line under the title: sources, chunks, bots. */
   meta?: ReactNode;
+  /** Pills of the tab tray, in display order. */
   tabs: KnowledgeBaseTab[];
+  /** Controlled selected tab id. Leave unset to let the component hold the selection itself. */
   value?: string;
+  /** Initial selected tab when uncontrolled. Falls back to the first tab. */
   defaultValue?: string;
+  /** Fires with the new tab id when a pill is clicked. */
   onValueChange?: (id: string) => void;
-  /** Shows the spinner and "N indexing" at the right of the tabs when above zero. */
+  /** Shows the spinner and "N indexing" at the right of the tabs when above zero.
+   * @default 0 */
   indexing?: number;
+  /** Fires when the round settings button is clicked; the button always renders. */
   onSettings?: () => void;
+  /** Fires when "Add source" is clicked; the button always renders. */
   onAddSource?: () => void;
   /** Called with the files dropped on the dropzone or picked with Browse. Omit to hide the dropzone. */
   onFiles?: (files: File[]) => void;
+  /** Headline inside the dropzone.
+   * @default "Drop files here, or browse" */
   dropTitle?: ReactNode;
+  /** Supporting line under the dropzone headline.
+   * @default "PDF, DOCX, Markdown or TXT · Notion, Google Drive and websites from Add source" */
   dropHint?: ReactNode;
-  /** Pipeline column labels shown above the list; hidden on narrow widths. */
+  /** Pipeline column labels shown above the list; hidden on narrow widths.
+   * @default ["Parse", "Chunk", "Embed", "Index"] */
   stages?: string[];
   /** The list rows, usually `SourceRow variant="list"`. */
   children?: ReactNode;
+  /** Extra classes on the panel `section`, merged after the built-in ones. */
   className?: string;
 };
 
@@ -40,6 +59,25 @@ const defaultStages = ["Parse", "Chunk", "Embed", "Index"];
  * Paper `Knowledge base` (XVM-1): a 24px-radius surface panel with a header, a pill tab tray, a table head, a
  * flat divided source list and a dashed dropzone. The selected tab pill travels in 280ms, the dropzone border and
  * fill change in 150ms while a file is over it, and indexing progress fills are animated by the rows.
+ *
+ * The dropzone is a `<label>` wrapping a visually hidden multi-file input, so
+ * clicking it opens the file picker as well as accepting a drag; the input is
+ * cleared after each pick so the same file can be chosen twice. Passing `onFiles`
+ * is what makes the dropzone appear.
+ *
+ * @example
+ * ```tsx
+ * <KnowledgeBasePanel
+ *   title="Knowledge base"
+ *   meta="3 sources · 128 chunks"
+ *   tabs={[{ id: "all", label: "All", count: 3 }]}
+ *   indexing={2}
+ *   onAddSource={openSourcePicker}
+ *   onFiles={upload}
+ * >
+ *   <SourceRow variant="list" status="ready" icon={<FileText />} name="README.md" detail="24 chunks" />
+ * </KnowledgeBasePanel>
+ * ```
  */
 export function KnowledgeBasePanel({
   title,

package/src/components/liquid-glass.tsx

@@ -18,6 +18,22 @@
  *
  * Without backdrop-filter support, or with reduced transparency requested, the
  * fill turns to `glass-fill-frost` and the rim stays (see `globals.css`).
+ *
+ * It takes no props and renders a single `aria-hidden` span; every visual
+ * decision comes from the host's class list, so the same element serves buttons,
+ * headers, cards and sheets.
+ *
+ * @example
+ * ```tsx
+ * function GlassCard() {
+ *   return (
+ *     <div className="relative isolate overflow-clip rounded-xl bg-glass-regular p-4">
+ *       <LiquidGlass />
+ *       <span className="relative">Floating chrome over the backdrop</span>
+ *     </div>
+ *   );
+ * }
+ * ```
  */
 export function LiquidGlass() {
   return <span aria-hidden className="liquid-layers" />;

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 (