@horon-ai/react 0.1.0 → 0.1.2

package/src/components/chat-controls.tsx

@@ -4,11 +4,16 @@ import type { ComponentProps, ReactNode } from "react";
 import { cn } from "../lib/cn";
 import { LiquidGlass } from "./liquid-glass";
 
+/** Material of the chat controls: `solid` on raised surfaces, `glass` over imagery and glass panels. */
 export type ChatControlSurface = "solid" | "glass";
 
 type ButtonProps = Omit<ComponentProps<"button">, "className"> & {
+  /** Extra classes merged onto the control button. */
   className?: string;
-  /** `solid` (default) on raised surfaces, `glass` over imagery and glass panels. */
+  /**
+   * `solid` (default) on raised surfaces, `glass` over imagery and glass panels.
+   * @default "solid"
+   */
   surface?: ChatControlSurface;
 };
 
@@ -20,7 +25,22 @@ const surfaceClass: Record<ChatControlSurface, string> = {
   solid: "border border-border-default bg-bg-surface hover:bg-bg-subtle active:bg-interactive-secondary-hover",
 };
 
-/** Figma `Jump to latest` (Chat controls 88:659): a 44px clear-glass circle with a 20px caret. */
+/**
+ * Figma `Jump to latest` (Chat controls 88:659): a 44px clear-glass circle with a 20px caret.
+ *
+ * A square icon button with `aria-label` (default `"Jump to latest"`) that surfaces with the
+ * `motion-rise` entrance and forwards `onClick`; the caller's handler performs the scroll to the
+ * newest message.
+ *
+ * @example
+ * ```tsx
+ * import { JumpToLatest } from "@horon-ai/react";
+ *
+ * function Example() {
+ *   return <JumpToLatest surface="glass" onClick={() => scrollToLatest()} />;
+ * }
+ * ```
+ */
 export function JumpToLatest({
   surface = "solid",
   className,
@@ -40,7 +60,12 @@ export function JumpToLatest({
   );
 }
 
-/** Figma `New messages` (88:659): a 40px clear-glass pill with a 16px caret and a label. */
+/**
+ * Figma `New messages` (88:659): a 40px clear-glass pill with a 16px caret and a label.
+ *
+ * A peer of {@link JumpToLatest} for the "there are unread messages above" case; the child is the label
+ * and all button attributes are forwarded.
+ */
 export function NewMessagesPill({ surface = "solid", className, children, ...props }: ButtonProps) {
   return (
     <button
@@ -58,21 +83,49 @@ export function NewMessagesPill({ surface = "solid", className, children, ...pro
 /** Bar heights of the Figma waveform, in px. */
 const WAVEFORM = [8, 14, 22, 12, 26, 18, 10, 20, 28, 16, 9, 18, 24, 12, 7, 15, 21, 11];
 
+/** Props of {@link VoiceInput}. */
 export type VoiceInputProps = {
   /** Elapsed time, such as "0:07". */
   elapsed: ReactNode;
-  /** 0-1 levels for the 18 bars; defaults to the Figma waveform. */
+  /** 0-1 levels for the 18 bars; defaults to the Figma waveform. Each level is scaled to 4–28px. */
   levels?: number[];
-  /** Animates the waveform while true; set false once recording stops. */
+  /**
+   * Animates the waveform while true; set false once recording stops.
+   * @default true
+   */
   recording?: boolean;
+  /** Fires when the red stop button is pressed. */
   onStop?: () => void;
+  /**
+   * Accessible label of the stop button.
+   * @default "Stop recording"
+   */
   stopLabel?: string;
-  /** `solid` (default) on raised surfaces, `glass` over imagery and glass panels. */
+  /**
+   * `solid` (default) on raised surfaces, `glass` over imagery and glass panels.
+   * @default "solid"
+   */
   surface?: ChatControlSurface;
+  /** Extra classes merged onto the pill. */
   className?: string;
 };
 
-/** Figma `Voice input` (88:659): a 52px pill with a red stop button, waveform and timer. */
+/**
+ * Figma `Voice input` (88:659): a 52px pill with a red stop button, waveform and timer.
+ *
+ * The 18 bars keep the Figma heights unless `levels` is passed, in which case each 0-1 level maps to a
+ * 4–28px bar. With `recording` the bars run the `wave` animation on a 120ms stagger; the whole waveform
+ * is `aria-hidden`, so only the stop button and the elapsed text reach assistive technology.
+ *
+ * @example
+ * ```tsx
+ * import { VoiceInput } from "@horon-ai/react";
+ *
+ * function Example() {
+ *   return <VoiceInput elapsed="0:07" recording onStop={() => stopRecording()} />;
+ * }
+ * ```
+ */
 export function VoiceInput({
   elapsed,
   levels,

package/src/components/checkbox.tsx

@@ -5,15 +5,20 @@ import type { ComponentProps, ReactNode } from "react";
 import { cn } from "../lib/cn";
 import type { ControlSize } from "../lib/size";
 
+/** Box size of {@link Checkbox}; identical to {@link ControlSize}. */
 export type CheckboxSize = ControlSize;
 
+/** Props of {@link Checkbox}. */
 export type CheckboxProps = Omit<ComponentProps<typeof BaseCheckbox.Root>, "className"> & {
+  /** Label rendered after the box inside the same clickable `<label>`. */
   label?: ReactNode;
   /**
    * `md` is the 20px Figma Checkbox, `sm` the 18px box of the Data table (192:9046),
    * `lg` the 24px box.
+   * @default "md"
    */
   size?: CheckboxSize;
+  /** Extra classes merged onto the label wrapper. */
   className?: string;
 };
 
@@ -36,7 +41,23 @@ const indicatorClass: Record<CheckboxSize, string> = {
   lg: "[&_svg]:size-4",
 };
 
-/** Figma `Checkbox` (58:217): a 20px box, 6px radius, with a 10px gap to its label. */
+/**
+ * Figma `Checkbox` (58:217): a 20px box, 6px radius, with a 10px gap to its label.
+ *
+ * A Base UI checkbox: `checked` makes it controlled, otherwise it keeps its own state, and
+ * `defaultChecked` / `onCheckedChange` / `indeterminate` work as in Base UI. Checked and indeterminate
+ * boxes fill with the brand color and show a check or a dash; the wrapper `<label>` dims the whole control
+ * when the input is disabled.
+ *
+ * @example
+ * ```tsx
+ * import { Checkbox } from "@horon-ai/react";
+ *
+ * function Example() {
+ *   return <Checkbox label="Remember this chat" defaultChecked />;
+ * }
+ * ```
+ */
 export function Checkbox({ label, size = "md", className, ...props }: CheckboxProps) {
   return (
     <label

package/src/components/chip.tsx

@@ -5,11 +5,17 @@ import { Children, type ComponentProps, useState } from "react";
 import { cn } from "../lib/cn";
 import type { ControlSize } from "../lib/size";
 
+/** Height and label rung of {@link Chip}; identical to {@link ControlSize} (`sm` 28px, `md` 32px, `lg` 36px). */
 export type ChipSize = ControlSize;
 
+/** Props of {@link Chip}. */
 export type ChipProps = Omit<ComponentProps<typeof Toggle>, "className"> & {
-  /** `md` is the 32px Figma Chip; `sm` is 28px and `lg` 36px. */
+  /**
+   * `md` is the 32px Figma Chip; `sm` is 28px and `lg` 36px.
+   * @default "md"
+   */
   size?: ChipSize;
+  /** Extra classes merged onto the toggle button. */
   className?: string;
 };
 
@@ -32,7 +38,28 @@ const checkIconClass: Record<ChipSize, string> = {
   lg: "size-4",
 };
 
-/** Figma `Chip` (61:302): a 32px solid toggle, no glass; selected shows a check, the brand border and brand text. */
+/**
+ * Figma `Chip` (61:302): a 32px solid toggle, no glass; selected shows a check, the brand border and brand text.
+ *
+ * A Base UI toggle: `pressed` makes it controlled, otherwise it keeps its own state and reports through
+ * `onPressedChange`. The check is in a `0`-width slot that opens on press, so an unselected chip never
+ * reserves the icon space; the slot only animates after the first toggle, so a chip that mounts pressed
+ * does not flash it. An element child is laid out in a row at the label gap.
+ *
+ * @example
+ * ```tsx
+ * import { Chip } from "@horon-ai/react";
+ *
+ * function Example() {
+ *   return (
+ *     <div className="flex flex-wrap gap-2">
+ *       <Chip defaultPressed>Documents</Chip>
+ *       <Chip>Images</Chip>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
 export function Chip({ size = "md", className, children, onPressedChange, ...props }: ChipProps) {
   // The exit animation only plays after the first toggle, so a chip that mounts unpressed never flashes the check.
   const [toggled, setToggled] = useState(false);

package/src/components/choice-card.tsx

@@ -2,13 +2,20 @@ import { Radio as BaseRadio } from "@base-ui/react/radio";
 import type { ComponentProps, ReactNode } from "react";
 
 import { cn } from "../lib/cn";
+/**
+ * Props for {@link ChoiceCard}: a radio root plus the card's own title, description and badge slots.
+ * `value`, `disabled` and the other radio props pass straight through to the Base UI radio root.
+ */
 export type ChoiceCardProps = Omit<ComponentProps<typeof BaseRadio.Root>, "className" | "children" | "title"> & {
+  /** Card heading on the title line; `label-md` semibold primary text, wrapped onto as many lines as the card width allows. */
   title: ReactNode;
+  /** Optional second line under the title, rendered as `caption` secondary text. */
   description?: ReactNode;
   /** Pill at the end of the title line, e.g. "Recommended": 22px, 8px padding, 18% sky with brand text (Paper Mobile connection). */
   badge?: ReactNode;
-  /** `brand` (default) is 18% sky with brand text; `neutral` is 6% ink with secondary text. */
+  /** `brand` (default) is 18% sky with brand text; `neutral` is 6% ink with secondary text. @default "brand" */
   badgeTone?: "brand" | "neutral";
+  /** Extra classes on the card root, merged after the layout, border and state classes. */
   className?: string;
 };
 
@@ -16,6 +23,23 @@ export type ChoiceCardProps = Omit<ComponentProps<typeof BaseRadio.Root>, "class
  * Paper `Choice card` (1VXM-0 selected, 1VXR-0 default): a 252px solid card, padding 14, radius 16, gap 12,
  * with a 1px default border that turns brand when selected; no glass.
  * Use inside `RadioGroup`. The 18px radio is a ring: 1.5px grey when off, a 5px ink ring around an 8px core when on.
+ *
+ * The card is a Base UI radio root, so it belongs to a single-select group: arrow keys move the selection,
+ * `value` / `defaultValue` on the group pick the card, and `disabled` drops the card to 40% opacity and blocks
+ * the click. The radio mark is decorative; the accessible name is the card's own text.
+ *
+ * @example
+ * ```tsx
+ * <RadioGroup defaultValue="team">
+ *   <ChoiceCard value="solo" title="Solo" description="One workspace for yourself." />
+ *   <ChoiceCard
+ *     value="team"
+ *     title="Team"
+ *     description="Shared bots, memory and billing."
+ *     badge="Recommended"
+ *   />
+ * </RadioGroup>
+ * ```
  */
 export function ChoiceCard({ title, description, badge, badgeTone = "brand", className, ...props }: ChoiceCardProps) {
   return (

package/src/components/code-panel.tsx

@@ -2,12 +2,26 @@ import type { ComponentProps } from "react";
 
 import { cn } from "../lib/cn";
 
-export type CodePanelProps = Omit<ComponentProps<"pre">, "className"> & { className?: string };
+/** Props for {@link CodePanel}: the `<pre>` attributes (`children` carries the code) plus a merged `className`. */
+export type CodePanelProps = Omit<ComponentProps<"pre">, "className"> & {
+  /** Extra classes on the `<pre>`, merged after the panel surface and type classes. */
+  className?: string;
+};
 
 /**
  * Paper `Code block` (1VV9-0), the light variant: a 10px-radius neutral-50 panel with a 1px hairline,
  * Geist Mono 12px on a 21px line pitch (Paper rows are 19px with a 2px gap), no header bar or copy button. Wrap keys in `CodeKey`; plain text reads as the string color.
  * Chat surfaces keep the ink `CodeBlock` from message-extras.
+ *
+ * The `<pre>` scrolls horizontally instead of wrapping (`whitespace-pre`), and the dark theme swaps the
+ * panel to neutral-800 with a stronger border.
+ *
+ * @example
+ * ```tsx
+ * <CodePanel>
+ *   {"---\ntitle: Weekly digest\n---"}
+ * </CodePanel>
+ * ```
  */
 export function CodePanel({ className, ...props }: CodePanelProps) {
   return (
@@ -21,7 +35,18 @@ export function CodePanel({ className, ...props }: CodePanelProps) {
   );
 }
 
-/** A frontmatter key or other highlighted token inside a `CodePanel`. */
-export function CodeKey({ className, ...props }: Omit<ComponentProps<"span">, "className"> & { className?: string }) {
+/**
+ * A frontmatter key or other highlighted token inside a `CodePanel`.
+ *
+ * Part of {@link CodePanel}. Renders an inline `span` in the key colour, so it only changes the colour of
+ * the text it wraps; extra classes can override or add weight.
+ */
+export function CodeKey({
+  className,
+  ...props
+}: Omit<ComponentProps<"span">, "className"> & {
+  /** Extra classes on the span, merged after the key colour. */
+  className?: string;
+}) {
   return <span className={cn("text-syntax-key", className)} {...props} />;
 }

package/src/components/combobox.tsx

@@ -7,9 +7,12 @@ import type { ControlSize } from "../lib/size";
 import { fieldBoxClass, fieldSizeClass, fieldTextClass, type InputSurface } from "./input";
 import { inputGroupSegmentClass, useInputGroup } from "./input-group";
 
+/** Height and text rung, shared with the other controls: `sm` 32px, `md` 40px, `lg` 48px. */
 export type ComboboxSize = ControlSize;
 
+/** One option in the list; the `value` is what the field reports and submits. */
 export type ComboboxItemData = {
+  /** Stable identity, reported by `value` / `onValueChange` and submitted with the form. */
   value: string;
   /** Row text and the text the search matches. */
   label: string;
@@ -19,46 +22,71 @@ export type ComboboxItemData = {
   trailing?: ReactNode;
   /** Extra search terms that are not shown, such as `KR` or `Korea`. */
   keywords?: readonly string[];
+  /** Dims the row to 40% and makes it unselectable. */
   disabled?: boolean;
 };
 
+/** Props shared by both value modes; `multiple` selects the mode in {@link ComboboxProps}. */
 type ComboboxBaseProps = {
+  /** Options in list order, in the shape of {@link ComboboxItemData}. */
   items: readonly ComboboxItemData[];
+  /** Text while nothing is chosen, and the field's `aria-label` in the `field` variant. @default "Search" */
   placeholder?: string;
-  /** Placeholder of the search box inside the popup (`segment` variant). */
+  /** Placeholder of the search box inside the popup (`segment` variant). @default "Search" */
   searchPlaceholder?: string;
-  /** Shown in the popup when nothing matches the search. */
+  /** Shown in the popup when nothing matches the search. @default "No results" */
   emptyLabel?: ReactNode;
+  /** Rung of the field, rows and chips. @default "md" */
   size?: ComboboxSize;
+  /** Surface of the field; the popup follows it. @default "solid" */
   surface?: InputSurface;
   /**
    * `field` is a searchable field (the default). `segment` is the tinted prefix or suffix of an
    * `InputGroup`: a button that opens a popup with the search box on top, taking the group's size.
+   * @default "field"
    */
   variant?: "field" | "segment";
+  /** Turns the field or chips border danger red and sets `aria-invalid`; a `segment` trigger gets neither, because the wrapping `InputGroup` owns that border. */
   invalid?: boolean;
+  /** Blocks the field; in a `segment` it also inherits `disabled` from the wrapping `InputGroup`. */
   disabled?: boolean;
   /** Form field name; the submitted value is the item `value`. */
   name?: string;
+  /** Extra classes on the field or trigger, merged after the surface and size classes. */
   className?: string;
+  /** Accessible name of the text field or segment trigger; the placeholder covers it in the `field` variant. */
   "aria-label"?: string;
 };
 
+/** Single-select combobox: `value` / `onValueChange` carry one item `value` or `null`. */
 export type ComboboxSingleProps = ComboboxBaseProps & {
+  /** Single-select mode; the default when the prop is omitted. */
   multiple?: false;
+  /** Controlled choice, as an item `value`; `null` means nothing is chosen. */
   value?: string | null;
+  /** Starting choice of the uncontrolled field. */
   defaultValue?: string | null;
+  /** Fires with the picked item `value`, or `null` when the field is cleared. */
   onValueChange?: (value: string | null) => void;
 };
 
+/** Multi-select combobox: the chosen items show as removable chips and the value is an array of item `value`s. */
 export type ComboboxMultipleProps = ComboboxBaseProps & {
   /** Chosen items show as removable chips in the field. */
   multiple: true;
+  /** Controlled selection, in the order chosen. */
   value?: readonly string[];
+  /** Starting selection of the uncontrolled field. */
   defaultValue?: readonly string[];
+  /** Fires with the full next selection as item `value`s, in the order chosen. */
   onValueChange?: (value: string[]) => void;
 };
 
+/**
+ * Props for {@link Combobox}, a discriminated union on `multiple`: without it the field is single-select
+ * and its value is `string | null`; with `multiple: true` it is multi-select and its value is `readonly string[]`.
+ * Narrow on `props.multiple` before reading `value` or `onValueChange`.
+ */
 export type ComboboxProps = ComboboxSingleProps | ComboboxMultipleProps;
 
 const itemClass: Record<ComboboxSize, string> = {
@@ -96,6 +124,28 @@ const shortLabel = (item: ComboboxItemData) => item.selectedLabel ?? item.label;
  * `multiple`, several items shown as chips. The popup matches `Select`: the veil, rows with
  * a check. `variant="segment"` puts it in an `InputGroup`, such as a country code before a
  * phone number.
+ *
+ * Filtering is a case-insensitive substring match over each item's `label`, `value` and `keywords`,
+ * with the query trimmed first; a blank query keeps every item. The chosen item's `selectedLabel`
+ * (falling back to `label`) is what the field shows, while the form and `onValueChange` carry `value`.
+ * The popup portals to the body, opens 4px below the field and is at least as wide as it; the list scrolls
+ * past 256px and the panel caps at 320px. In `segment` form the popup is a 256px column with its own search
+ * box on top; on `multiple` the field grows and wraps as chips fill it instead of fixing its height.
+ *
+ * @example
+ * ```tsx
+ * const [country, setCountry] = useState<string | null>("+82");
+ *
+ * <Combobox
+ *   aria-label="Country code"
+ *   value={country}
+ *   onValueChange={setCountry}
+ *   items={[
+ *     { value: "+82", label: "+82 South Korea", keywords: ["KR", "Korea"] },
+ *     { value: "+1", label: "+1 United States", keywords: ["US"] },
+ *   ]}
+ * />
+ * ```
  */
 export function Combobox(props: ComboboxProps) {
   const {

package/src/components/command-palette.tsx

@@ -1,14 +1,23 @@
 import { Autocomplete } from "@base-ui/react/autocomplete";
 import { Dialog } from "@base-ui/react/dialog";
-import { MagnifyingGlass } from "@phosphor-icons/react";
+import { MagnifyingGlass, X } from "@phosphor-icons/react";
 import type { ReactNode } from "react";
 
+import { useDevice } from "../hooks/use-device";
 import { cn } from "../lib/cn";
 import { Kbd } from "./kbd";
 
+/** Close control shape for pointers that never reach a key: a 28px icon tile instead of the esc chip. */
+const touchCloseClass =
+  "flex size-7 shrink-0 motion-press cursor-pointer items-center justify-center rounded-full text-text-secondary hover:bg-overlay-ink-6 hover:text-text-primary focus-visible:outline-2 focus-visible:outline-text-brand [&_svg]:size-4";
+
+/** One selectable row of the palette. */
 export type CommandItem = {
+  /** Stable identity and the React key of the row; keep it unique across the palette. */
   value: string;
+  /** Row text; the query also matches it, together with `keywords`. */
   label: string;
+  /** Extra search terms that are not shown, such as an abbreviation or a path. */
   keywords?: string;
   /** 28px leading tile: an initial or a 16px icon. */
   tile?: ReactNode;
@@ -16,33 +25,78 @@ export type CommandItem = {
   tileClassName?: string;
   /** Caption after the label, such as the workspace. */
   meta?: ReactNode;
-  /** Right-side hint, usually `<Kbd>`. */
+  /** Right-side hint, usually `<Kbd>`; hidden when the device shows no keyboard hints. */
   hint?: ReactNode;
+  /** Runs when the row is clicked, before the palette closes itself. */
   onSelect?: () => void;
 };
 
-export type CommandGroup = { label: string; items: CommandItem[] };
+/** A titled block of rows; groups are rendered in the order given. */
+export type CommandGroup = {
+  /** Section heading, `caption` secondary text above the rows. */
+  label: string;
+  /** Rows of this section. */
+  items: CommandItem[];
+};
 
+/** Props for {@link CommandPalette}: the dialog state, the grouped rows and the footer hints. */
 export type CommandPaletteProps = {
+  /** Controlled open state; leave it out to let the palette open from its `trigger`. */
   open?: boolean;
+  /** Called with the next open state when the palette opens, closes on Escape, closes on select or its backdrop is pressed. */
   onOpenChange?: (open: boolean) => void;
+  /** Sections of rows, in render order. */
   groups: CommandGroup[];
+  /** Search field placeholder; it also names the dialog (`aria-label`). @default "Search" */
   placeholder?: string;
   /** Shown when the query has no matches; defaults to "No results". */
   empty?: ReactNode;
-  /** Footer key hints, such as `[["↑↓", "Move"], ["↵", "Open"]]`. */
+  /** Footer key hints, such as `[["↑↓", "Move"], ["↵", "Open"]]`; hidden when the device shows no keyboard hints. */
   hints?: [ReactNode, string][];
+  /** Element rendered inside the dialog root as the opener, usually a `DialogTrigger`. */
   trigger?: ReactNode;
   /**
    * `solid` (default) is an opaque palette with a default border. `glass` puts it on the veil (`veil-overlay`).
+   * @default "solid"
    */
   surface?: "solid" | "glass";
+  /** Extra classes on the popup, merged after the surface, radius and motion classes. */
   className?: string;
 };
 
 /**
  * Figma `Command palette` (110:676): a 560px palette, 24px radius, with a 48px search row,
  * grouped 44px results and a key-hint footer.
+ *
+ * A Base UI dialog on a 32% scrim with a 6px blur, anchored to the top of the viewport 96px down rather
+ * than centred. It always renders {@link CommandPaletteBody} with its own close control — an `esc` chip on
+ * devices that show keyboard hints, a 28px `X` tile on touch — and every row select reports
+ * `onOpenChange(false)`. Row hints and the footer hints disappear on those touch devices too. The body
+ * owns filtering and keyboard movement.
+ *
+ * @example
+ * ```tsx
+ * const [open, setOpen] = useState(false);
+ *
+ * <CommandPalette
+ *   open={open}
+ *   onOpenChange={setOpen}
+ *   trigger={<DialogTrigger render={<Button variant="solid" />}>Search</DialogTrigger>}
+ *   groups={[
+ *     {
+ *       label: "Bots",
+ *       items: [
+ *         { value: "weekly", label: "Weekly digest", meta: "Product", hint: <Kbd>↵</Kbd> },
+ *         { value: "inbox", label: "Inbox triage", meta: "Ops" },
+ *       ],
+ *     },
+ *   ]}
+ *   hints={[
+ *     ["↑↓", "Move"],
+ *     ["↵", "Open"],
+ *   ]}
+ * />
+ * ```
  */
 export function CommandPalette({
   open,
@@ -55,6 +109,7 @@ export function CommandPalette({
   surface = "solid",
   className,
 }: CommandPaletteProps) {
+  const { keyboardHints } = useDevice();
   return (
     <Dialog.Root open={open} onOpenChange={onOpenChange}>
       {trigger}
@@ -76,13 +131,16 @@ export function CommandPalette({
               placeholder={placeholder}
               empty={empty}
               closeControl={
-                <Dialog.Close aria-label="Close" className="motion-press cursor-pointer">
-                  <Kbd>esc</Kbd>
+                <Dialog.Close
+                  aria-label="Close"
+                  className={keyboardHints ? "motion-press cursor-pointer" : touchCloseClass}
+                >
+                  {keyboardHints ? <Kbd keys="Escape" /> : <X aria-hidden />}
                 </Dialog.Close>
               }
               onSelect={() => onOpenChange?.(false)}
             />
-            {hints && hints.length > 0 && (
+            {keyboardHints && hints && hints.length > 0 && (
               <div className="relative flex flex-wrap items-center gap-x-4 gap-y-1 px-3 pt-2 pb-1">
                 {hints.map(([key, label]) => (
                   <span key={label} className="flex items-center gap-1.5 text-caption text-text-secondary">
@@ -99,17 +157,32 @@ export function CommandPalette({
   );
 }
 
+/** Props for {@link CommandPaletteBody}: the rows plus the close control and the select callback the host owns. */
 export type CommandPaletteBodyProps = {
+  /** Sections of rows, in render order. */
   groups: CommandGroup[];
+  /** Search field placeholder. @default "Search" */
   placeholder?: string;
+  /** Shown when the query has no matches. @default "No results" */
   empty?: ReactNode;
+  /** Accessible name of the fallback `esc` button, used when no `closeControl` is passed. @default "Close" */
   closeLabel?: string;
   /** A ready close control; the dialog passes its own `Dialog.Close` so uncontrolled palettes still close. */
   closeControl?: ReactNode;
+  /** Makes the fallback `esc` button close the palette; without both this and `closeControl` no button renders. */
   onClose?: () => void;
+  /** Called after a row's own `onSelect`, so the host can close its dialog. */
   onSelect?: () => void;
 };
 
+/**
+ * The search row, groups and result rows of a command palette.
+ *
+ * Part of {@link CommandPalette}. Renders a Base UI `Autocomplete` that is always open and inline: the
+ * query filters on label plus keywords (case-insensitive), the first row is highlighted as soon as the
+ * list renders, and arrow keys move through the rows while Enter picks the highlighted one. Escape is left
+ * to the host's close control, which is why this part owns no dialog state.
+ */
 export function CommandPaletteBody({
   groups,
   placeholder = "Search",
@@ -119,6 +192,7 @@ export function CommandPaletteBody({
   onClose,
   onSelect,
 }: CommandPaletteBodyProps) {
+  const { keyboardHints } = useDevice();
   return (
     <Autocomplete.Root
       open
@@ -138,8 +212,13 @@ export function CommandPaletteBody({
         />
         {closeControl ??
           (onClose === undefined ? null : (
-            <button type="button" aria-label={closeLabel} className="motion-press cursor-pointer" onClick={onClose}>
-              <Kbd>esc</Kbd>
+            <button
+              type="button"
+              aria-label={closeLabel}
+              className={keyboardHints ? "motion-press cursor-pointer" : touchCloseClass}
+              onClick={onClose}
+            >
+              {keyboardHints ? <Kbd keys="Escape" /> : <X aria-hidden />}
             </button>
           ))}
       </div>
@@ -179,7 +258,7 @@ export function CommandPaletteBody({
                   <span className="truncate text-label-md text-text-primary">{item.label}</span>
                   {item.meta && <span className="shrink-0 text-caption text-text-secondary">{item.meta}</span>}
                   <span className="flex-1" />
-                  {item.hint}
+                  {keyboardHints && item.hint}
                 </Autocomplete.Item>
               )}
             </Autocomplete.Collection>

package/src/components/composer.tsx

@@ -5,21 +5,34 @@ import { cn } from "../lib/cn";
 import type { ControlSize } from "../lib/size";
 import { IconButton } from "./icon-button";
 
+/** Height and text rung of the composer: `sm` 32px, `md` 40px, `lg` 48px, shared with the other controls. */
 export type ComposerSize = ControlSize;
+/** `solid` is the opaque bordered pill; `glass` is the veil field for imagery and glass panels. */
 export type ComposerSurface = "solid" | "glass";
 
+/** Props for {@link Composer}: the message value, the send callback and the two side actions. */
 export type ComposerProps = {
+  /** Rung of the field and its icon buttons. @default "md" */
   size?: ComposerSize;
-  /** `solid` (default) on raised surfaces, `glass` over imagery and glass panels. */
+  /** `solid` (default) on raised surfaces, `glass` over imagery and glass panels. @default "solid" */
   surface?: ComposerSurface;
+  /** Field placeholder; it doubles as the `aria-label` because the field has no visible label. @default "Message" */
   placeholder?: string;
+  /** Controlled text. Leave it out to let the composer own the value and still report changes. */
   value?: string;
+  /** Starting text of the uncontrolled composer. @default "" */
   defaultValue?: string;
+  /** Fires on every keystroke with the next full text, controlled or not. */
   onValueChange?: (value: string) => void;
+  /** Fires with the full (untrimmed) text when the form submits, from Enter or the send button; whitespace-only text blocks the submit. The field is cleared after. */
   onSubmit?: (value: string) => void;
+  /** Fires when the plus button is pressed; the composer itself opens nothing. */
   onAttach?: () => void;
+  /** Fires when the microphone button is pressed, i.e. while the field is empty. */
   onVoice?: () => void;
+  /** Disables the field and both icon buttons without changing the layout. */
   disabled?: boolean;
+  /** Extra classes on the form, merged after the surface and size classes. */
   className?: string;
 };
 
@@ -39,6 +52,20 @@ const textClass: Record<ComposerSize, string> = {
  * Figma `Composer` (63:462): a regular-glass pill with an attach button, the
  * message field, and a voice button that turns into the ink send button once
  * there is text.
+ *
+ * A real `form`, so Enter submits and the browser handles implicit submission; a value that is only
+ * whitespace blocks the send and leaves the typed text in place. The last slot swaps between the voice
+ * button (empty field) and the primary send button (`motion-swap`), and only the visible one is focusable.
+ *
+ * @example
+ * ```tsx
+ * <Composer
+ *   placeholder="Ask anything"
+ *   onAttach={() => openFilePicker()}
+ *   onVoice={() => startDictation()}
+ *   onSubmit={(text) => sendMessage(text)}
+ * />
+ * ```
  */
 export function Composer({
   size = "md",