@horon-ai/react 0.1.1 → 0.1.2

package/src/components/avatar.tsx

@@ -4,26 +4,32 @@ import type { ReactNode } from "react";
 
 import { cn } from "../lib/cn";
 
+/** Diameter of the avatar: `sm` 24px, `md` 32px, `lg` 40px, `xl` 56px. */
 export type AvatarSize = "sm" | "md" | "lg" | "xl";
 
+/** Props for {@link Avatar}: the avatar type and size, the image source, fallback content and the live dot. */
 export type AvatarProps = {
-  /** `initials` (default), `bot` (robot on the brand tint) or `image`. */
+  /** `initials` (default), `bot` (robot on the brand tint) or `image`. @default "initials" */
   type?: "initials" | "bot" | "image";
+  /** Diameter token; also scales the initials, the bot icon and the live dot. @default "md" */
   size?: AvatarSize;
   /** Image URL for `type="image"`; initials show while it loads or if it fails. */
   src?: string;
+  /** Alternative text for `type="image"`; pass `""` when the name is already shown next to the avatar. @default "" */
   alt?: string;
   /** Initials, or any fallback content. */
   children?: ReactNode;
-  /** Shows the live status dot at the bottom right. */
+  /** Shows the live status dot at the bottom right. @default false */
   live?: boolean;
-  /** Initials colour: `neutral` (default) or `sky`, the Paper account profile avatar (sky-100 fill, sky-700 text). */
+  /** Initials colour: `neutral` (default) or `sky`, the Paper account profile avatar (sky-100 fill, sky-700 text). @default "neutral" */
   tone?: "neutral" | "sky";
   /**
    * Border colour of the live dot, so it matches the surface behind it (glass panels, `bg-subtle`, brand tints).
    * Defaults to `border-bg-surface`.
+   * @default "border-bg-surface"
    */
   liveRingClassName?: string;
+  /** Extra classes merged onto the wrapper, for positioning or a custom size override. */
   className?: string;
 };
 
@@ -55,7 +61,17 @@ const typeClass = {
   image: "bg-sky-200 text-text-secondary",
 } as const;
 
-/** Figma `Avatar` (61:347): Initials, Bot and Image in four sizes, with an optional live dot. */
+/**
+ * Figma `Avatar` (61:347): Initials, Bot and Image in four sizes, with an optional live dot. Built on Base UI's
+ * avatar primitive, so an image that fails to load falls back to the children instead of a broken icon.
+ *
+ * @example
+ * ```tsx
+ * <Avatar type="image" size="lg" src={user.photoUrl} alt="" live>
+ *   {initials}
+ * </Avatar>
+ * ```
+ */
 export function Avatar({
   type = "initials",
   size = "md",

package/src/components/badge.tsx

@@ -3,16 +3,27 @@ import type { ComponentProps } from "react";
 import { cn } from "../lib/cn";
 import type { ControlSize } from "../lib/size";
 
-/** `surface` is the white (raised surface) pill with a 1px default border and primary text. */
+/** Tint of the pill and its dot; `neutral` is the default.
+ *
+ * - `neutral`: 6% ink pill with secondary text, the default.
+ * - `brand`: sky-tinted pill with brand text, for counts and states tied to the brand.
+ * - `danger`: red-tinted pill with danger text, for errors and destructive states.
+ * - `solid`: filled brand pill with on-primary text, for the strongest emphasis.
+ * - `surface`: the white (raised surface) pill with a 1px default border and primary text.
+ */
 export type BadgeTone = "neutral" | "brand" | "danger" | "solid" | "surface";
+/** Size token shared with the form controls (`sm`, `md`, `lg`); the rendered heights are documented on {@link Badge}. */
 export type BadgeSize = ControlSize;
 
+/** Props for {@link Badge}: the tone, size, optional status dot and extra span props. */
 export type BadgeProps = Omit<ComponentProps<"span">, "className"> & {
+  /** Colour treatment of the pill and its dot. @default "neutral" */
   tone?: BadgeTone;
   /** Leading status dot; 4px (sm), 6px (md) or 8px (lg). */
   dot?: boolean;
-  /** `md` is the 22px Figma Badge; `sm` 20px and `lg` 26px. */
+  /** `md` is the 22px Figma Badge; `sm` 20px and `lg` 26px. @default "md" */
   size?: BadgeSize;
+  /** Extra classes merged onto the pill, for margins or alignment. */
   className?: string;
 };
 
@@ -44,7 +55,17 @@ const dotClass: Record<BadgeTone, string> = {
   surface: "bg-text-primary",
 };
 
-/** Figma `Badge` (61:283): a 22px translucent pill with label-sm text. */
+/**
+ * Figma `Badge` (61:283): a 22px translucent pill with label-sm text. Renders a non-interactive `span`, so it can
+ * sit inside buttons, list rows and headings without changing their layout height.
+ *
+ * @example
+ * ```tsx
+ * <Badge tone="brand" dot>
+ *   Running
+ * </Badge>
+ * ```
+ */
 export function Badge({ tone = "neutral", dot, size = "md", className, children, ...props }: BadgeProps) {
   return (
     <span

package/src/components/banner.tsx

@@ -5,18 +5,24 @@ import { cn } from "../lib/cn";
 import type { ControlSize } from "../lib/size";
 import { LiquidGlass } from "./liquid-glass";
 
+/** Severity of the strip: `info` tints the rim and icon brand, `danger` uses the danger rim and role="alert". */
 export type BannerTone = "info" | "danger";
+/** Size token shared with the form controls; the rendered heights are documented on {@link Banner}. */
 export type BannerSize = ControlSize;
+/** `solid` paints the raised surface, `glass` layers the glass material for use over imagery. */
 export type BannerSurface = "solid" | "glass";
 
+/** Props for {@link Banner}: the tone, size and surface of the strip plus its optional trailing action. */
 export type BannerProps = Omit<ComponentProps<"div">, "className"> & {
+  /** Severity; also picks the icon and the ARIA role. @default "info" */
   tone?: BannerTone;
   /** Trailing underlined action, such as a link or button. */
   action?: ReactNode;
-  /** Banner size: `sm` 32px minimum, `md` the Figma 48px strip (default), `lg` 56px; scales icon, text and padding. */
+  /** Banner size: `sm` 32px minimum, `md` the Figma 48px strip (default), `lg` 56px; scales icon, text and padding. @default "md" */
   size?: BannerSize;
-  /** `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?: BannerSurface;
+  /** Extra classes merged onto the strip, for margins or width overrides. */
   className?: string;
 };
 
@@ -59,7 +65,17 @@ const solidEdgeClass: Record<BannerTone, string> = {
   danger: "border-border-danger",
 };
 
-/** Figma `Banner` (62:318): a strip with a tinted rim, 16px icon and an underlined action. */
+/**
+ * Figma `Banner` (62:318): a strip with a tinted rim, 16px icon and an underlined action. The tone sets the ARIA
+ * role — `danger` renders `role="alert"` (announced immediately), `info` renders `role="status"`.
+ *
+ * @example
+ * ```tsx
+ * <Banner tone="danger" action={<a href="/settings">Review</a>}>
+ *   Your API key expired.
+ * </Banner>
+ * ```
+ */
 export function Banner({
   tone = "info",
   action,

package/src/components/bot-instructions-panel.tsx

@@ -6,20 +6,50 @@ import { useActiveIndicator } from "../hooks/use-active-indicator";
 import { useDevice } from "../hooks/use-device";
 import { Kbd } from "./kbd";
 
-type WithClass<T> = Omit<T, "className"> & { className?: string };
+/** Drops the base type's `className` so the panel can own it. */
+type WithClass<T> = Omit<T, "className"> & {
+  /** Extra classes merged onto the root element. */
+  className?: string;
+};
 
+/** Props for {@link PanelPillTabs}: the tab items, the controlled or default selection and the change handler. */
 export type PanelPillTabsProps = {
-  items: { value: string; label: ReactNode }[];
+  /** Tabs in display order; the first one is the default selection. */
+  items: {
+    /** Value handed to `onValueChange` and compared against `value`. */
+    value: string;
+    /** Tab label. */
+    label: ReactNode;
+  }[];
+  /** Controlled selected value; omit it to let the track keep its own selection. */
   value?: string;
+  /** Selection used before the first click, falling back to the first item. */
   defaultValue?: string;
+  /** Fires with the next value on click or arrow-key navigation. */
   onValueChange?: (value: string) => void;
+  /** Accessible name of the tab list. */
   "aria-label"?: string;
+  /** Extra classes merged onto the track, for width overrides. */
   className?: string;
 };
 
 /**
- * The 5% ink pill track shared by the Bot panels (Paper `YNQ-1`): 3px padding, 2px gap, 28px options with
+ * The 5% ink pill track shared by the Bot panels (Paper `YNQ-1`): 3px padding, 2px gap, 30px options with
  * 12px inset and a 10% ink selection that slides between options in 280ms.
+ *
+ * Works controlled (`value`) or uncontrolled (`defaultValue`); the arrow keys wrap around, move the selection
+ * and focus the newly selected tab, while only the selected tab stays in the tab order.
+ *
+ * @example
+ * ```tsx
+ * <PanelPillTabs
+ *   aria-label="Instructions view"
+ *   items={[
+ *     { value: "instructions", label: "Instructions" },
+ *     { value: "example", label: "Example" },
+ *   ]}
+ * />
+ * ```
  */
 export function PanelPillTabs({ items, value, defaultValue, onValueChange, className, ...props }: PanelPillTabsProps) {
   const [inner, setInner] = useState(defaultValue ?? items[0]?.value ?? "");
@@ -82,6 +112,7 @@ export function PanelPillTabs({ items, value, defaultValue, onValueChange, class
   );
 }
 
+/** Chip tint: `sky` the default light blue, `brand` the deeper sky-700, `neutral` grey. */
 export type InstructionVariableTone = "sky" | "brand" | "neutral";
 
 const variableToneClass: Record<InstructionVariableTone, string> = {
@@ -97,26 +128,53 @@ const variableDotClass: Record<InstructionVariableTone, string> = {
 };
 
 /** One piece of an instruction line: plain text, or a `{{variable}}` chip. */
-export type InstructionPart = string | { variable: string; tone?: InstructionVariableTone };
+export type InstructionPart =
+  | string
+  | {
+      /** Variable name, rendered inside the chip without the braces. */
+      variable: string;
+      /** Chip tint. @default "sky" */
+      tone?: InstructionVariableTone;
+    };
 
-export type InstructionVariable = { name: string; tone?: InstructionVariableTone; value: string };
+/** A test value for one `{{variable}}` in the prompt, shown under the instructions. */
+export type InstructionVariable = {
+  /** Variable name shown above the test value. */
+  name: string;
+  /** Dot tint matching the chip in the prompt. @default "sky" */
+  tone?: InstructionVariableTone;
+  /** Test value used when the instruction is run. */
+  value: string;
+};
 
+/** Props for {@link BotInstructionsPanel}: the bot, the prompt lines, the optional example, variables and scenarios, and the run handler. */
 export type BotInstructionsPanelProps = WithClass<Omit<ComponentProps<"section">, "title">> & {
+  /** Panel heading. @default "Instructions" */
   title?: ReactNode;
   /** Version label in the header pill, for example `v4`. */
   version?: string;
   /** Status next to the version, rendered with a live dot. */
   versionStatus?: string;
-  bot: { initial: string; name: string };
-  /** The editable prompt, one array of parts per line. */
+  /** Bot whose prompt is shown; the initial fills the 18px tile. */
+  bot: {
+    /** One-character tile label. */
+    initial: string;
+    /** Bot name next to the tile. */
+    name: string;
+  };
+  /** The prompt text, one array of parts per line, rendered read-only. */
   instructions: InstructionPart[][];
   /** Shown under the Example tab instead of the prompt. */
   example?: ReactNode;
+  /** Prompt length shown at the right of the tab row; hidden when undefined. */
   tokenCount?: number;
   /** Test values for each variable in the prompt. */
   variables?: InstructionVariable[];
+  /** Test scenarios offered as pills under the prompt. */
   scenarios?: string[];
+  /** Scenario selected on first render, falling back to the first scenario. */
   defaultScenario?: string;
+  /** Fires with the selected scenario (or undefined) when Run is pressed; the panel does not run anything itself. */
   onRun?: (scenario: string | undefined) => void;
   /** The last run's output, or a hint until there is one. */
   output?: ReactNode;
@@ -130,13 +188,17 @@ function partKey(part: InstructionPart) {
   return typeof part === "string" ? part : part.variable;
 }
 
+/** Inline rounded chip that stands in for a `{{variable}}` inside a prompt line. */
 function VariableChip({
   tone = "sky",
   className,
   children,
 }: {
+  /** Chip tint. @default "sky" */
   tone?: InstructionVariableTone;
+  /** Extra classes merged onto the chip. */
   className?: string;
+  /** Variable name shown without braces. */
   children: ReactNode;
 }) {
   return (
@@ -153,6 +215,23 @@ function Divider() {
 /**
  * Bot instructions panel (Paper `YN3-1` / `GOZ-0`): a 24px-radius surface with the bot header, an
  * Instructions / Example tab pair over the prompt text with `{{variable}}` chips, and a test-run block.
+ *
+ * The tab and the selected scenario are local state; the panel only reports a run through `onRun`. Output is
+ * re-keyed per run so it animates in every time. A caret blinks at the end of the prompt while the prompt area
+ * has focus. The Run button carries a `Mod+Enter` chip — ⌘↵ on macOS and iOS, Ctrl+Enter elsewhere — which is
+ * hidden on touch devices that show no keyboard hints.
+ *
+ * @example
+ * ```tsx
+ * <BotInstructionsPanel
+ *   version="v4"
+ *   bot={{ initial: "R", name: "Researcher" }}
+ *   instructions={[["Summarise ", { variable: "sheet" }, " for the team."]]}
+ *   variables={[{ name: "sheet", value: "Q3 metrics" }]}
+ *   scenarios={["Weekly digest", "Board update"]}
+ *   onRun={(scenario) => run(scenario)}
+ * />
+ * ```
  */
 export function BotInstructionsPanel({
   title = "Instructions",

package/src/components/bot-list-row.tsx

@@ -3,7 +3,9 @@ import type { ComponentProps, ReactNode } from "react";
 import { cn } from "../lib/cn";
 import { Avatar } from "./avatar";
 
+/** Props for {@link BotListRow}: the bot name, last-activity time and preview, the live and selected states. */
 export type BotListRowProps = Omit<ComponentProps<"button">, "className"> & {
+  /** Bot display name, truncated with an ellipsis when it does not fit. */
   name: ReactNode;
   /** Last activity time, such as "8:41 AM". */
   time?: ReactNode;
@@ -11,11 +13,21 @@ export type BotListRowProps = Omit<ComponentProps<"button">, "className"> & {
   preview?: ReactNode;
   /** Running bots show the live dot on the avatar. */
   live?: boolean;
+  /** The row for the bot currently open in the panel; paints the 10% ink selected fill and sets `aria-pressed`. */
   selected?: boolean;
+  /** Extra classes merged onto the button, for margins or width overrides. */
   className?: string;
 };
 
-/** Figma `Bot list row` (64:456): a flat 12px-padded row; hover 5% ink, selected 10% ink. */
+/**
+ * Figma `Bot list row` (64:456): a flat 12px-padded row; hover 5% ink, selected 10% ink. The whole row is the
+ * button, so the accessible name comes from its text content (name, time and preview).
+ *
+ * @example
+ * ```tsx
+ * <BotListRow name="Researcher" time="8:41 AM" preview="Pulled the Q3 numbers" live selected />
+ * ```
+ */
 export function BotListRow({ name, time, preview, live, selected, className, ...props }: BotListRowProps) {
   return (
     <button

package/src/components/bot-memory-panel.tsx

@@ -5,17 +5,28 @@ import { cn } from "../lib/cn";
 import { PanelPillTabs } from "./bot-instructions-panel";
 import { Switch } from "./switch";
 
-type WithClass<T> = Omit<T, "className"> & { className?: string };
+type WithClass<T> = Omit<T, "className"> & {
+  /** Extra classes merged onto the root element. */
+  className?: string;
+};
 
+/** One switch row of {@link BotMemoryPanel}: a label, an optional description and the Switch state. */
 export type BotMemorySetting = {
+  /** Stable key of the row, passed back to `onSettingChange`. */
   id: string;
+  /** Row title, also used as the switch's `aria-label`. */
   label: string;
+  /** Optional second line under the label, e.g. what the setting does. */
   description?: string;
+  /** Initial switch state; the switch is uncontrolled after mount. */
   defaultChecked?: boolean;
 };
 
+/** One remembered item of {@link BotMemoryPanel}, grouped under its `group` heading. */
 export type BotMemoryItem = {
+  /** Stable key of the memory. */
   id: string;
+  /** The remembered text, on the first line of the row. */
   text: string;
   /** Where the memory came from, for example `From a chat · Oct 8`. */
   source: string;
@@ -25,25 +36,47 @@ export type BotMemoryItem = {
   fresh?: boolean;
 };
 
-export type BotMemoryToast = { title: string; message?: string };
+/** The transient "Memory updated" pill of {@link BotMemoryPanel}: a title and an optional second line. */
+export type BotMemoryToast = {
+  /** Bold pill text, e.g. "Memory updated". */
+  title: string;
+  /** Optional detail shown after the title, e.g. what was saved. */
+  message?: string;
+};
 
+/** Props of {@link BotMemoryPanel}. */
 export type BotMemoryPanelProps = WithClass<Omit<ComponentProps<"section">, "title">> & {
+  /**
+   * Heading of the panel.
+   * @default "Memory"
+   */
   title?: ReactNode;
+  /** Muted second line under the heading, e.g. how many memories are stored. */
   subtitle?: ReactNode;
   /** Fill of the memory meter, 0 to 100. */
   usage: number;
+  /** Switch rows shown under the header, in order. */
   settings?: BotMemorySetting[];
+  /** All memories; they are grouped by `group` and filtered by the pill tabs. */
   memories: BotMemoryItem[];
   /** The "Memory updated" pill; it enters with a pop and leaves through its close button. */
   toast?: BotMemoryToast;
+  /** Fires once the closing pill has finished its exit animation. */
   onToastDismiss?: () => void;
+  /** "Add memory" at the bottom of the panel. */
   onAdd?: () => void;
+  /** Fires when a settings switch is flipped, with the setting `id` and the new state. */
   onSettingChange?: (id: string, checked: boolean) => void;
   /** Makes the search button actionable; without it the icon is a plain decoration. */
   onSearch?: () => void;
 };
 
-function Divider({ inset }: { inset?: boolean }) {
+/** Hairline separator between panel rows. */
+// prettier-ignore
+function Divider({ inset }: {
+  /** Indents the rule by 20px to match the surrounding rows. */
+  inset?: boolean;
+}) {
   return (
     <div className={cn("flex self-stretch", inset && "px-5")}>
       <div role="separator" className="h-px flex-1 bg-overlay-ink-8" />
@@ -54,6 +87,28 @@ function Divider({ inset }: { inset?: boolean }) {
 /**
  * Bot memory panel (Paper `ZO2-1` / `HPY-0`): a 24px-radius surface with a memory meter, two switch rows,
  * a filter pill track, a transient "Memory updated" pill and the grouped memories.
+ *
+ * The meter clamps `usage` to 0–100 and exposes it as a `progressbar`. The filter tabs are built from the
+ * memories' `group` values plus an "All" tab and are component state; each row rises in with a 30ms
+ * stagger. The toast pill shows while a `toast` is passed, plays its exit animation when its close button
+ * is pressed, re-enters with a pop for a new toast object, and calls `onToastDismiss` when the exit
+ * animation ends.
+ *
+ * @example
+ * ```tsx
+ * import { BotMemoryPanel } from "@horon-ai/react";
+ *
+ * function Example() {
+ *   return (
+ *     <BotMemoryPanel
+ *       usage={42}
+ *       settings={[{ id: "auto", label: "Memory", description: "Let the assistant remember chats", defaultChecked: true }]}
+ *       memories={[{ id: "m1", text: "Prefers Korean replies", source: "From a chat · Oct 8", group: "Preference" }]}
+ *       onAdd={() => {}}
+ *     />
+ *   );
+ * }
+ * ```
  */
 export function BotMemoryPanel({
   title = "Memory",

package/src/components/bottom-sheet.tsx

@@ -4,23 +4,42 @@ import type { ComponentProps, ReactNode } from "react";
 
 import { cn } from "../lib/cn";
 
+/**
+ * Root of the bottom sheet: owns the open state and the drag/Escape dismissal. Wrap a
+ * {@link BottomSheetTrigger} and a {@link BottomSheetContent}; the sheet is only mounted while open.
+ */
 export const BottomSheet = Drawer.Root;
+/** The element that opens the sheet, forwarded to Base UI's trigger unchanged. */
 export const BottomSheetTrigger = Drawer.Trigger;
+/** A close control for the sheet body; it also dismisses on scrim, Escape and a downward drag. */
 export const BottomSheetClose = Drawer.Close;
 
+/** Props of {@link BottomSheetContent}. */
 export type BottomSheetContentProps = Omit<ComponentProps<typeof Drawer.Popup>, "className" | "title"> & {
+  /** Sheet title, rendered in the drawer's title slot above the children. */
   title: ReactNode;
   /**
    * `panel` is the Figma panel sheet (374px max, label-lg title). `detail` is the Paper detail sheet:
    * full width, 18px rhythm, a caller-built header (tile, title, description) set flush left.
+   * @default "panel"
    */
   variant?: "panel" | "detail";
-  /** `glass` is the veil sheet (`veil-overlay`); `solid` is the Paper workspace sheet: opaque default fill, 20px top corners, 8/24/16 padding. */
+  /**
+   * `glass` is the veil sheet (`veil-overlay`); `solid` is the Paper workspace sheet: opaque default fill, 20px top corners, 8/24/16 padding.
+   * @default "solid"
+   */
   surface?: "glass" | "solid";
-  /** Draws the dimmed, blurred scrim behind the sheet. Paper's floating panel sheet has none. */
+  /**
+   * Draws the dimmed, blurred scrim behind the sheet. Paper's floating panel sheet has none.
+   * @default true
+   */
   backdrop?: boolean;
-  /** Insets the sheet 16px from the sides and bottom edge (Paper's 358px panel sheet) instead of docking it full width. */
+  /**
+   * Insets the sheet 16px from the sides and bottom edge (Paper's 358px panel sheet) instead of docking it full width.
+   * @default false
+   */
   floating?: boolean;
+  /** Extra classes merged onto the sheet popup. */
   className?: string;
 };
 
@@ -28,6 +47,29 @@ export type BottomSheetContentProps = Omit<ComponentProps<typeof Drawer.Popup>,
  * Figma `Bottom sheet` (Panels 88:808): the veil with 32px top corners, a 36x5 grabber and a
  * label-lg title. There is no close button: the sheet closes on the scrim, on Escape, on a
  * downward drag of the grabber, or through the caller's own bottom action row.
+ *
+ * Portal-mounted above the page (z-50). The popup slides up on open and down on close; the body
+ * scrolls on its own with `overscroll-contain`, and the sheet is capped at `100dvh` minus 2rem.
+ *
+ * @example
+ * ```tsx
+ * import { BottomSheet, BottomSheetAction, BottomSheetActions, BottomSheetContent, BottomSheetTrigger } from "@horon-ai/react";
+ *
+ * function Example() {
+ *   return (
+ *     <BottomSheet>
+ *       <BottomSheetTrigger>Open sheet</BottomSheetTrigger>
+ *       <BottomSheetContent title="Reminder" floating>
+ *         <p className="text-body-sm text-text-secondary">Every weekday at 9:00</p>
+ *         <BottomSheetActions>
+ *           <BottomSheetAction>Cancel</BottomSheetAction>
+ *           <BottomSheetAction variant="primary">Save</BottomSheetAction>
+ *         </BottomSheetActions>
+ *       </BottomSheetContent>
+ *     </BottomSheet>
+ *   );
+ * }
+ * ```
  */
 export function BottomSheetContent({
   title,
@@ -82,14 +124,17 @@ export function BottomSheetContent({
   );
 }
 
+/** Props of {@link BottomSheetRow}. */
 export type BottomSheetRowProps = Omit<ComponentProps<"button">, "className"> & {
+  /** Leading icon rendered at 20px in secondary text color. */
   icon?: ReactNode;
   /** Current value on the right, such as "On" or "Weekdays". */
   value?: ReactNode;
+  /** Extra classes merged onto the row button. */
   className?: string;
 };
 
-/** A 48px settings row: 20px icon, label, value and a 16px caret. */
+/** A 48px settings row: 20px icon, label, value and a 16px caret. Part of {@link BottomSheetContent}. */
 export function BottomSheetRow({ icon, value, className, children, ...props }: BottomSheetRowProps) {
   return (
     <button
@@ -108,22 +153,31 @@ export function BottomSheetRow({ icon, value, className, children, ...props }: B
   );
 }
 
-/** The action row: secondary first, the primary action at the right edge, 8px apart. */
+/** The action row: secondary first, the primary action at the right edge, 8px apart. Wraps onto a second line when the sheet is too narrow. Part of {@link BottomSheetContent}. */
 export function BottomSheetActions({
   className,
   ...props
-}: Omit<ComponentProps<"div">, "className"> & { className?: string }) {
+}: Omit<ComponentProps<"div">, "className"> & {
+  /** Extra classes merged onto the action row. */
+  className?: string;
+}) {
   return (
     <div className={cn("relative flex w-full flex-wrap items-center justify-end gap-2 pt-3", className)} {...props} />
   );
 }
 
+/** Props of {@link BottomSheetAction}. */
 export type BottomSheetActionProps = Omit<ComponentProps<"button">, "className"> & {
+  /**
+   * `primary` is the filled brand pill, `secondary` the 6% ink pill.
+   * @default "secondary"
+   */
   variant?: "primary" | "secondary";
+  /** Extra classes merged onto the action button. */
   className?: string;
 };
 
-/** The sheet's 44px pill actions: `secondary` is 6% ink, `primary` is ink. */
+/** The sheet's 44px pill actions: `secondary` is 6% ink, `primary` is ink. Part of {@link BottomSheetActions}. */
 export function BottomSheetAction({ variant = "secondary", className, ...props }: BottomSheetActionProps) {
   return (
     <button

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,