@horon-ai/react 0.1.1 → 0.1.3

package/src/components/breadcrumb-header.tsx

@@ -6,26 +6,56 @@ import { BreadcrumbItem } from "./breadcrumb";
 import { IconButton } from "./icon-button";
 import { LiquidGlass } from "./liquid-glass";
 
+/** One crumb of {@link BreadcrumbHeader}; the last crumb in `crumbs` is the current page. */
 export type BreadcrumbHeaderCrumb = {
+  /** Crumb text; also its React key, so crumbs should have distinct labels. */
   label: string;
+  /** Makes the crumb a link; ignored for the last (current) crumb, which stays text. */
   href?: string;
   /** Leading 20px ink tile, such as the workspace initial. */
   tile?: ReactNode;
 };
 
+/** Props of {@link BreadcrumbHeader}. */
 export type BreadcrumbHeaderProps = Omit<ComponentProps<"header">, "className"> & {
   /** Crumbs in order; the last one is the current page. */
   crumbs: BreadcrumbHeaderCrumb[];
+  /** Adds the search icon button; without it the button is not rendered at all. */
   onSearch?: () => void;
+  /** Adds the "more" (three dots) icon button; without it the button is not rendered at all. */
   onMore?: () => void;
+  /** Accessible label of the search button. @default "Search" */
   searchLabel?: string;
+  /** Accessible label of the more button. @default "More" */
   moreLabel?: string;
-  /** `solid` (default) on the page, `glass` over imagery and glass panels. */
+  /** `solid` (default) on the page, `glass` over imagery and glass panels. @default "solid" */
   surface?: "solid" | "glass";
+  /** Extra classes merged onto the header. */
   className?: string;
 };
 
-/** Paper `Header with breadcrumb`: a 52px regular-glass pill with a crumb row, search and more buttons. */
+/**
+ * Paper `Header with breadcrumb`: a 52px regular-glass pill with a crumb row, search and more buttons.
+ *
+ * The crumb trail scrolls sideways inside the pill instead of truncating; only the last crumb truncates.
+ * The two icon buttons (36px) are only rendered when their handlers are passed. On `glass` a
+ * {@link LiquidGlass} layer sits under the content, so the header must be placed over imagery.
+ *
+ * @example
+ * ```tsx
+ * import { BreadcrumbHeader } from "@horon-ai/react";
+ *
+ * function Example() {
+ *   return (
+ *     <BreadcrumbHeader
+ *       crumbs={[{ label: "H", tile: "H", href: "/" }, { label: "Projects", href: "/projects" }, { label: "Horon" }]}
+ *       onSearch={() => {}}
+ *       onMore={() => {}}
+ *     />
+ *   );
+ * }
+ * ```
+ */
 export function BreadcrumbHeader({
   crumbs,
   onSearch,

package/src/components/breadcrumb.tsx

@@ -4,15 +4,39 @@ import { Children, Fragment, type ComponentProps, type ReactNode } from "react";
 import { cn } from "../lib/cn";
 import { LiquidGlass } from "./liquid-glass";
 
+/** Tray material behind a {@link Breadcrumb} trail: `glass` is the regular glass tray, `solid` the opaque one. */
 export type BreadcrumbSurface = "glass" | "solid";
 
+/** Props of {@link Breadcrumb}. */
 export type BreadcrumbProps = Omit<ComponentProps<"nav">, "className"> & {
   /** `glass` wraps the crumbs in a regular-glass tray, `solid` in an opaque tray. Omitted keeps them bare. */
   surface?: BreadcrumbSurface;
+  /** Extra classes merged onto the navigation element. */
   className?: string;
 };
 
-/** Figma `Breadcrumb` (110:948): crumbs 6px apart with 14px carets; the last crumb is the current page. */
+/**
+ * Figma `Breadcrumb` (110:948): crumbs 6px apart with 14px carets; the last crumb is the current page.
+ *
+ * Renders a `<nav aria-label>` (default `"Breadcrumb"`) holding an ordered list, and inserts an
+ * `aria-hidden` caret between entries. The tray is a grid box so it can shrink below its trail's
+ * min-content; an over-wide trail scrolls inside it rather than truncating labels.
+ *
+ * @example
+ * ```tsx
+ * import { Breadcrumb, BreadcrumbItem } from "@horon-ai/react";
+ *
+ * function Example() {
+ *   return (
+ *     <Breadcrumb surface="solid">
+ *       <BreadcrumbItem href="/" tile="H">Home</BreadcrumbItem>
+ *       <BreadcrumbItem href="/projects">Projects</BreadcrumbItem>
+ *       <BreadcrumbItem current>Horon</BreadcrumbItem>
+ *     </Breadcrumb>
+ *   );
+ * }
+ * ```
+ */
 export function Breadcrumb({
   surface,
   className,
@@ -53,14 +77,20 @@ export function Breadcrumb({
   );
 }
 
+/** Props of {@link BreadcrumbItem}. */
 export type BreadcrumbItemProps = Omit<ComponentProps<"a">, "className"> & {
   /** Marks the current page: primary text and `aria-current`. */
   current?: boolean;
   /** Leading 20px ink tile, such as the workspace initial. */
   tile?: ReactNode;
+  /** Extra classes merged onto the crumb element. */
   className?: string;
 };
 
+/**
+ * One crumb of {@link Breadcrumb}: an anchor when `href` is set and the crumb is not current,
+ * otherwise a `<span>`. The current crumb renders primary text with `aria-current="page"`.
+ */
 export function BreadcrumbItem({ current, tile, href, className, children, ...props }: BreadcrumbItemProps) {
   const Element = href && !current ? "a" : "span";
   return (

package/src/components/button.tsx

@@ -4,14 +4,37 @@ import { Children, isValidElement, type ComponentProps, type ReactNode } from "r
 import { cn } from "../lib/cn";
 import { LiquidGlass } from "./liquid-glass";
 
+/**
+ * Visual treatment of {@link Button}.
+ *
+ * - `primary` — filled brand button, for the single main action of a screen or dialog.
+ * - `glass` — clear glass fill with a {@link LiquidGlass} layer, for chrome floating over imagery.
+ * - `solid` — bordered surface button, for secondary actions on a page.
+ * - `danger` — filled destructive action, such as delete.
+ * - `link` — size-independent text-only button; its `aria-current="page"` / `aria-current="true"` state
+ *   colors it like primary text, which is how an active navigation link is marked.
+ */
 export type ButtonVariant = "primary" | "glass" | "solid" | "danger" | "link";
+/**
+ * Height and text rung of a non-`link` {@link Button}, identical to {@link ControlSize}:
+ * `sm` 32px `label-md`, `md` 40px `label-lg`, `lg` 48px `label-lg`.
+ */
 export type ButtonSize = "sm" | "md" | "lg";
 
 type ButtonCommonProps = {
+  /**
+   * Visual treatment; `link` ignores the size rungs.
+   * @default "primary"
+   */
   variant?: ButtonVariant;
+  /**
+   * Height and label rung of the control; `link` stays text-only.
+   * @default "md"
+   */
   size?: ButtonSize;
   /** Leading icon; sized 16px (sm, md) or 20px (lg) and colored like the label. */
   icon?: ReactNode;
+  /** Extra classes appended last, so a caller can add width, margins or overrides. */
   className?: string;
 };
 
@@ -49,7 +72,29 @@ const variantClass: Record<ButtonVariant, string> = {
   link: "h-auto gap-1.5 rounded-sm px-1 text-label-sm text-text-secondary motion-colors hover:not-data-disabled:text-text-primary aria-[current=page]:text-text-primary aria-[current=true]:text-text-primary [&_svg]:size-3.5",
 };
 
-/** Figma `Button` (55:339): Primary, Glass, Solid and Danger in three sizes, plus a text-only `link` variant (size-independent). */
+/**
+ * Figma `Button` (55:339): Primary, Glass, Solid and Danger in three sizes, plus a text-only `link` variant (size-independent).
+ *
+ * Renders a Base UI button, or a real `<a>` once `href` is set (button-only attributes such as `type`,
+ * `disabled` and `form*` are then dropped instead of reaching the DOM). Sizes `sm` and `md` paint an
+ * invisible 44px hit area around the 32/40px control without moving it. A non-`link` button also accepts
+ * an `icon` before the label and, on `glass`, a {@link LiquidGlass} layer beneath its content.
+ *
+ * @example
+ * ```tsx
+ * import { Button } from "@horon-ai/react";
+ *
+ * function Example() {
+ *   return (
+ *     <div className="flex items-center gap-2">
+ *       <Button onClick={() => save()}>Save changes</Button>
+ *       <Button variant="solid" size="sm">Cancel</Button>
+ *       <Button variant="link" href="/settings">Settings</Button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
 export function Button({
   variant = "primary",
   size = "md",

package/src/components/calendar.tsx

@@ -4,31 +4,52 @@ import { useMemo, useRef, useState, type KeyboardEvent } from "react";
 import { cn } from "../lib/cn";
 import type { ControlSize } from "../lib/size";
 
-export type DateRange = { start: Date | null; end: Date | null };
+/**
+ * An inclusive date range for {@link Calendar} in `range` mode: both `start` and `end` are selected days,
+ * only those two endpoints are stored and the days between them are derived on render. Both ends are
+ * `null` before the first click, and `end` stays `null` while the user is picking the second day.
+ */
+export type DateRange = {
+  /** First selected day, or `null` when the range is empty. */
+  start: Date | null;
+  /** Last selected day; stays `null` until the second click completes the range. */
+  end: Date | null;
+};
+/** Day-cell rung of {@link Calendar}; identical to {@link ControlSize} (`sm` 32px, `md` 40px, `lg` 48px cells). */
 export type CalendarSize = ControlSize;
 
 type CommonProps = {
   /** First visible month; defaults to the selected date or today. */
   defaultMonth?: Date;
+  /**
+   * Controlled visible month. While set, the arrows and keyboard month changes only report
+   * through `onMonthChange` and the component keeps no month state of its own.
+   */
   month?: Date;
+  /** Fires with the first day of the month the user navigated to (arrows, or keyboard focus crossing a boundary). */
   onMonthChange?: (month: Date) => void;
+  /** Days for which this returns true render disabled and cannot be selected. */
   isDateDisabled?: (date: Date) => boolean;
   /** BCP 47 locale for the month title, weekdays and day labels. */
   locale?: string;
-  /** 0 = Sunday (the Figma calendar), 1 = Monday. */
+  /** 0 = Sunday (the Figma calendar), 1 = Monday. @default 0 */
   weekStartsOn?: 0 | 1;
+  /** Extra classes merged onto the calendar frame. */
   className?: string;
+  /** The day drawn as today, with the brand text color and the live dot; defaults to the real date at mount. */
   today?: Date;
   /**
    * `default` is the day picker calendar (60:245): centered title-sm month.
    * `popover` is the `Calendar popover` (88:495): 24px radius, left label-lg
    * month and 32px round arrow buttons on the right.
+   * @default "default"
    */
   variant?: "default" | "popover";
   /**
    * `solid` (default) is an opaque surface with a default border. `glass` puts it on the veil (`veil-overlay`),
    * the material of the `DateField` popup; `flat` keeps the 80% white fill of the old thick glass
    * without it (Paper Schedule mini calendar).
+   * @default "solid"
    */
   surface?: "glass" | "flat" | "solid";
   /** Days drawn as subtle ink circles in the day cell size, e.g. the week the schedule shows; selection still draws on top. */
@@ -36,11 +57,20 @@ type CommonProps = {
   /**
    * Day cell size: `sm` 32px, `md` 40px (default, the Figma size), `lg` 48px.
    * Scales the header, padding, weekday row and day text with the cells.
+   * @default "md"
    */
   size?: CalendarSize;
 };
 
-const containerSizeClass: Record<CalendarSize, { default: string; popover: string }> = {
+const containerSizeClass: Record<
+  CalendarSize,
+  {
+    /** Classes for the `default` variant: fills the parent up to the Figma width. */
+    default: string;
+    /** Classes for the `popover` variant: fixed Figma width, capped by the viewport. */
+    popover: string;
+  }
+> = {
   // The default calendar fills its parent up to the Figma width (250/314/374px: seven cells plus padding),
   // so it lands on that size on desktop and folds to the column on a narrow screen. `w-full` rather than a
   // fixed `w-*` keeps its min-content at zero, which is what lets a flex parent shrink it. The popover is
@@ -140,10 +170,31 @@ const popoverDayTextClass: Record<CalendarSize, string> = {
   lg: "[&_[role=gridcell]]:text-label-lg",
 };
 
+/**
+ * Props of {@link Calendar}. `mode` switches the value shape: `single` (the default) works with one
+ * `Date`, `range` with a {@link DateRange}; the callback always receives the same shape.
+ */
 export type CalendarProps = CommonProps &
   (
-    | { mode?: "single"; value?: Date | null; onValueChange?: (value: Date) => void }
-    | { mode: "range"; value?: DateRange; onValueChange?: (value: DateRange) => void }
+    | {
+        /** Pick one day. @default "single" */
+        mode?: "single";
+        /** Selected day, or `null` when nothing is selected. */
+        value?: Date | null;
+        /** Fires when a day is clicked, with the newly selected day. */
+        onValueChange?: (value: Date) => void;
+      }
+    | {
+        /** Pick a start and an end day. */
+        mode: "range";
+        /** Current range; omitted means both ends are empty. */
+        value?: DateRange;
+        /**
+         * Fires on every click: the first click sets `start` and clears `end`, the second sets `end`,
+         * and a click before `start` restarts the range at that day.
+         */
+        onValueChange?: (value: DateRange) => void;
+      }
   );
 
 const startOfDay = (date: Date) => new Date(date.getFullYear(), date.getMonth(), date.getDate());
@@ -162,7 +213,26 @@ function monthGrid(month: Date, weekStartsOn: 0 | 1): Date[] {
   return Array.from({ length: weeks * 7 }, (_, index) => addDays(start, index));
 }
 
-/** Figma `Day` (60:125) inside the `Calendar` of the day picker example (60:245). */
+/**
+ * Figma `Day` (60:125) inside the `Calendar` of the day picker example (60:245).
+ *
+ * A one-month grid with `grid`/`row`/`gridcell` roles and an `aria-label` on every day. The month starts
+ * from `defaultMonth`, else the selected day, else today, and slides between months with the arrow
+ * buttons; `month` makes that controlled. Arrow keys move focus by a day, a week vertically, and bring
+ * the focused month into view; only the focused day is tabbable. The variant controls the frame
+ * (`default` centered header, `popover` left title with round arrows) and `surface` its material.
+ *
+ * @example
+ * ```tsx
+ * import { useState } from "react";
+ * import { Calendar, type DateRange } from "@horon-ai/react";
+ *
+ * function Example() {
+ *   const [range, setRange] = useState<DateRange>({ start: null, end: null });
+ *   return <Calendar mode="range" value={range} onValueChange={setRange} weekStartsOn={1} />;
+ * }
+ * ```
+ */
 export function Calendar(props: CalendarProps) {
   const {
     defaultMonth,

package/src/components/card.tsx

@@ -5,8 +5,11 @@ import type { ComponentProps, ReactElement, ReactNode } from "react";
 import { cn } from "../lib/cn";
 import { LiquidGlass } from "./liquid-glass";
 
+/** Props of {@link Card}. */
 export type CardProps = Omit<ComponentProps<"div">, "className" | "title"> & {
+  /** Card heading on the title row, wrapping inside the card instead of truncating; the caret joins this row. */
   title?: ReactNode;
+  /** Body line under the title, in body-sm secondary text. */
   description?: ReactNode;
   /** Shows the trailing caret, for cards that open something. */
   interactive?: boolean;
@@ -17,12 +20,38 @@ export type CardProps = Omit<ComponentProps<"div">, "className" | "title"> & {
   /**
    * `solid` (default) is an opaque surface with a default border. `glass` is the thick glass.
    * `frost` is the Paper home board card: the same glass with the denser frost fill and a 0 8 24 6% drop.
+   * @default "solid"
    */
   surface?: "glass" | "frost" | "solid";
+  /** Extra classes merged onto the rendered root. */
   className?: string;
 };
 
-/** Figma `Card` (63:310): a 320px thick-glass card, 20px padding and radius, Default / Interactive / Selected. */
+/**
+ * Figma `Card` (63:310): a 320px thick-glass card, 20px padding and radius, Default / Interactive / Selected.
+ *
+ * `render` swaps the root element through Base UI's `useRender` (e.g. `<button />` or `<a />`); the glass
+ * layer is isolated behind the content, so the card never needs a stacking-context patch from the caller.
+ * `interactive` adds the caret, hover rim and press scale, `selected` the brand rim
+ * (`[data-selected]` is set too), and children render in a full-width block under the description.
+ *
+ * @example
+ * ```tsx
+ * import { Card } from "@horon-ai/react";
+ *
+ * function Example() {
+ *   return (
+ *     <Card
+ *       interactive
+ *       surface="frost"
+ *       title="Weekly digest"
+ *       description="A summary of everything the assistant saved this week."
+ *       render={<button type="button" />}
+ *     />
+ *   );
+ * }
+ * ```
+ */
 export function Card({
   title,
   description,

package/src/components/chat-bubble.tsx

@@ -3,13 +3,22 @@ import type { ComponentProps } from "react";
 import { cn } from "../lib/cn";
 import type { ControlSize } from "../lib/size";
 
+/** Padding and text rung of {@link ChatBubble}; identical to {@link ControlSize}. */
 export type ChatBubbleSize = ControlSize;
 
+/** Props of {@link ChatBubble}. */
 export type ChatBubbleProps = Omit<ComponentProps<"div">, "className"> & {
-  /** `me` is the ink bubble, `bot` the flat subtle bubble. Neither uses glass. */
+  /**
+   * `me` is the ink bubble, `bot` the flat subtle bubble. Neither uses glass.
+   * @default "me"
+   */
   from?: "me" | "bot";
-  /** Bubble size: `sm` 12/8px padding with body-sm, `md` 16/12px with body-md (default), `lg` 20/14px with body-lg. */
+  /**
+   * Bubble size: `sm` 12/8px padding with body-sm, `md` 16/12px with body-md (default), `lg` 20/14px with body-lg.
+   * @default "md"
+   */
   size?: ChatBubbleSize;
+  /** Extra classes merged onto the bubble. */
   className?: string;
 };
 
@@ -19,7 +28,27 @@ const sizeClass: Record<ChatBubbleSize, string> = {
   lg: "px-5 py-3.5 text-body-lg",
 };
 
-/** Figma `Chat bubble` (64:359): 16/12px padding, 20px radius, body-md text. */
+/**
+ * Figma `Chat bubble` (64:359): 16/12px padding, 20px radius, body-md text.
+ *
+ * `me` bubbles push to the right edge with the ink fill, `bot` bubbles stay left on the subtle fill;
+ * both cap at 560px or the parent's width, wrap long words and rise in with `motion-rise`. The `from`
+ * value is mirrored to `data-from` for styling hooks.
+ *
+ * @example
+ * ```tsx
+ * import { ChatBubble } from "@horon-ai/react";
+ *
+ * function Example() {
+ *   return (
+ *     <div className="flex flex-col gap-2">
+ *       <ChatBubble from="bot">What should I look up?</ChatBubble>
+ *       <ChatBubble from="me">The Q3 usage report, please.</ChatBubble>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
 export function ChatBubble({ from = "me", size = "md", className, ...props }: ChatBubbleProps) {
   return (
     <div

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);