@horon-ai/react 0.1.1 → 0.1.3

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

@@ -11,9 +11,13 @@ import { Kbd } from "./kbd";
 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;
@@ -23,31 +27,76 @@ export type CommandItem = {
   meta?: ReactNode;
   /** 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"]]`; 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,
@@ -108,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",

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",