@horon-ai/react 0.1.1 → 0.1.2

package/src/components/date-field.tsx

@@ -6,20 +6,32 @@ import type { ControlSize } from "../lib/size";
 import { Calendar, type CalendarProps, type DateRange } from "./calendar";
 import { fieldBoxClass, fieldSizeClass, fieldTextClass, type InputSurface } from "./input";
 
+/** Height and text rung of the trigger and the calendar inside: `sm` 32px, `md` 40px, `lg` 48px. */
 export type DateFieldSize = ControlSize;
+/** Surface of the trigger: `glass` over imagery and glass panels, `solid` on raised surfaces, `solid-on-page` on the page background. */
 export type DateFieldSurface = InputSurface;
 
 type WithoutCalendarSurface<T> = T extends unknown ? Omit<T, "size" | "surface"> : never;
 
+/**
+ * Props for {@link DateField}: every `Calendar` prop except its own `size` and `surface`, plus the trigger's
+ * placeholder, format and classes. `value` is the calendar's value too, so pass a `Date` in `single` mode and
+ * a `DateRange` in `range` mode; the trigger text is drawn from the same value.
+ */
 export type DateFieldProps = WithoutCalendarSurface<CalendarProps> & {
+  /** Rung of the trigger, and of the calendar in the popup. @default "md" */
   size?: DateFieldSize;
-  /** `solid` (default) on raised surfaces, `glass` over imagery and glass panels, `solid-on-page` directly on the page background. */
+  /** `solid` (default) on raised surfaces, `glass` over imagery and glass panels, `solid-on-page` directly on the page background. @default "solid" */
   surface?: DateFieldSurface;
+  /** Text while nothing is picked; it also styles as placeholder text. @default "Pick a date" */
   placeholder?: string;
+  /** Marks the trigger `aria-invalid` and turns its border danger red. */
   invalid?: boolean;
+  /** Dims the trigger and blocks the popup. */
   disabled?: boolean;
   /** Formats the trigger text; defaults to "Oct 20, 2026" and "Oct 20 – Oct 24, 2026". */
   format?: (value: Date | DateRange) => string;
+  /** Extra classes on the trigger button, merged after the field surface and size classes. */
   triggerClassName?: string;
 };
 
@@ -42,7 +54,24 @@ const popupCalendarWidthClass: Record<DateFieldSize, string> = {
   lg: "w-93.5 max-w-[calc(100vw-2rem)]",
 };
 
-/** Figma `Date field` (60:244): a 280px field that opens the calendar, in three sizes and two surfaces. */
+/**
+ * Figma `Date field` (60:244): a 280px field that opens the calendar, in three sizes and two surfaces.
+ *
+ * A `Popover` trigger, not an input: the button shows the formatted value or the placeholder and opens the
+ * calendar in a portal at the trigger's start edge, 4px below. The popup names its own width (250/314/374px
+ * by rung, capped to the viewport) because the calendar fills its parent and a positioner is auto-width.
+ *
+ * @example
+ * ```tsx
+ * const [date, setDate] = useState<Date | null>(new Date());
+ *
+ * <DateField
+ *   value={date}
+ *   onValueChange={setDate}
+ *   placeholder="Pick a date"
+ * />
+ * ```
+ */
 export function DateField({
   size = "md",
   surface = "solid",

package/src/components/dialog.tsx

@@ -4,14 +4,44 @@ import type { ComponentProps, ReactNode } from "react";
 
 import { cn } from "../lib/cn";
 
+/**
+ * State holder for a dialog: give it `open` / `onOpenChange` to control it, or neither plus a
+ * `defaultOpen` to leave it uncontrolled. It renders nothing itself; the parts below supply the surface.
+ *
+ * @example
+ * ```tsx
+ * const [open, setOpen] = useState(false);
+ *
+ * <Dialog open={open} onOpenChange={setOpen}>
+ *   <DialogTrigger render={<Button />}>Rename bot</DialogTrigger>
+ *   <DialogContent
+ *     title="Rename bot"
+ *     description="The new name shows up everywhere the bot is mentioned."
+ *   >
+ *     <Input defaultValue="Weekly digest" aria-label="Bot name" />
+ *     <DialogFooter>
+ *       <DialogClose render={<Button variant="solid" />}>Cancel</DialogClose>
+ *       <Button onClick={() => setOpen(false)}>Save</Button>
+ *     </DialogFooter>
+ *   </DialogContent>
+ * </Dialog>
+ * ```
+ */
 export const Dialog = BaseDialog.Root;
+
+/** The control that opens the dialog. It takes `render` to put the press behaviour on your own button. */
 export const DialogTrigger = BaseDialog.Trigger;
+
+/** The control that closes the dialog: it sets the dialog's open state to false, so a controlled dialog also sees `onOpenChange`. */
 export const DialogClose = BaseDialog.Close;
 
+/** Props for {@link DialogContent}: the Base UI popup attributes plus the heading, description and surface choices. */
 export type DialogContentProps = Omit<ComponentProps<typeof BaseDialog.Popup>, "className" | "title"> & {
+  /** Heading rendered as the popup's `title-md` title, which also names the dialog for assistive tech. */
   title: ReactNode;
+  /** Optional `body-md` secondary paragraph under the title, wired to the popup's description. */
   description?: ReactNode;
-  /** Label for the close button; hides it when `null`. */
+  /** Label for the close button; hides it when `null`. @default "Close" */
   closeLabel?: string | null;
   /** Slot marker on the close control, for a surface its own app selects the control by. */
   closeSlot?: string;
@@ -21,14 +51,21 @@ export type DialogContentProps = Omit<ComponentProps<typeof BaseDialog.Popup>, "
    * `glass` is the veil dialog (`veil-overlay`). `solid` is the Paper workspace modal:
    * opaque default fill, 20px radius, 24px padding and a 0 24 64 shadow, no glass layer.
    * Both surfaces share the 16px block rhythm between title, description and actions.
+   * @default "solid"
    */
   surface?: "glass" | "solid";
+  /** Extra classes on the popup panel, merged after the surface, radius and motion classes. */
   className?: string;
 };
 
 /**
- * Figma `Dialog on scrim` (63:329): a 40% scrim and a 420px veil dialog,
+ * Figma `Dialog on scrim` (63:329): the `bg-scrim` ink at 32% alpha and a 420px veil dialog,
  * 24px padding, title-md heading with a 32px close target, body-md description.
+ *
+ * Part of {@link Dialog}. Portals to the body over a 6px-blurred scrim and centres through a fixed viewport
+ * with 16px gutters, so on a narrow screen the panel keeps its padding and shrinks to the gutters instead;
+ * the panel caps at `100dvh - 32px` and scrolls its own content. Base UI owns the focus trap, Escape to
+ * close and the scroll lock.
  */
 export function DialogContent({
   title,
@@ -84,10 +121,15 @@ export function DialogContent({
 /**
  * The action row: secondary first, the primary action at the right edge, 8px apart.
  * `w-full` is what right-aligns it — the dialog popup stacks children at their content width.
+ *
+ * Part of {@link Dialog}. Renders a plain `div`, so it can also close a `BottomSheet` body with the same rhythm.
  */
 export function DialogFooter({
   className,
   ...props
-}: Omit<ComponentProps<"div">, "className"> & { className?: string }) {
+}: Omit<ComponentProps<"div">, "className"> & {
+  /** Extra classes on the row, merged after the alignment and gap classes. */
+  className?: string;
+}) {
   return <div className={cn("relative flex w-full flex-wrap items-center justify-end gap-2", className)} {...props} />;
 }

package/src/components/directory-card.tsx

@@ -5,19 +5,40 @@ import { cn } from "../lib/cn";
 import { IconButton } from "./icon-button";
 import { LiquidGlass } from "./liquid-glass";
 
+/** Props for {@link DirectoryCard}: the tile icon and copy, plus an optional add action. */
 export type DirectoryCardProps = Omit<ComponentProps<"div">, "children"> & {
   /** 20px icon shown in inverse on the 40px tile. */
   icon: ReactNode;
+  /** Tile label, `label-md` primary text on one truncated line. */
   name: ReactNode;
   /** One line; longer text is clamped. */
   description?: ReactNode;
+  /** Adds an `IconButton` with a plus when set; the card shows no button without it. */
   onAdd?: () => void;
+  /** Accessible name of the add button (`aria-label`), since it shows only a plus icon. @default "Add" */
   addLabel?: 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?: "solid" | "glass";
 };
 
-/** Paper `Directory card` (Settings 1VJJ-0): 40px tile, name and one-line description, plus an add button. */
+/**
+ * Paper `Directory card` (Settings 1VJJ-0): 40px tile, name and one-line description, plus an add button.
+ *
+ * The `glass` surface paints the thick glass fill and mounts a `LiquidGlass` layer behind the content, so
+ * it belongs only over imagery or a glass panel. The add button inherits the same surface, which keeps the
+ * two materials matched.
+ *
+ * @example
+ * ```tsx
+ * <DirectoryCard
+ *   icon={<Folder />}
+ *   name="Product"
+ *   description="Specs, research and launch notes."
+ *   onAdd={() => openFolderPicker()}
+ *   addLabel="Connect folder"
+ * />
+ * ```
+ */
 export function DirectoryCard({
   icon,
   name,

package/src/components/document-extract-panel.tsx

@@ -4,52 +4,97 @@ import { type ComponentProps, type ReactNode, useMemo, useState } from "react";
 import { cn } from "../lib/cn";
 import { PanelPillTabs } from "./bot-instructions-panel";
 
-type WithClass<T> = Omit<T, "className"> & { className?: string };
+/** Strips a section's own `className` so the panel can merge its classes with the caller's. */
+type WithClass<T> = Omit<T, "className"> & {
+  /** Extra classes merged last onto the element. */
+  className?: string;
+};
 
+/** Row state of a plain field: `filled` reads fine, `check` marks a value the extractor is unsure about. */
 export type ExtractFieldStatus = "filled" | "check";
 
+/** One extracted scalar value: one row in the Fields view and one entry in the JSON view. */
 export type ExtractField = {
+  /** Stable identity; confirming a row records this id and drives the footer counters. */
   id: string;
+  /** Row label on the left, 100px wide; also the key in the JSON view. */
   label: string;
+  /** The read value, shown truncated in a button-sized pill. */
   value: string;
   /** Field type shown at the row end, for example `Text` or `Date`. */
   type?: string;
+  /** `check` marks the value for confirmation: the row takes the danger border and a "Check" caption. */
   status?: ExtractFieldStatus;
 };
 
+/** One extracted table: a labelled block with a header row and body rows instead of a single value. */
 export type ExtractTable = {
+  /** Stable identity, counted like a field in the footer. */
   id: string;
+  /** Row label above the table. */
   label: string;
+  /** Field type shown at the row end, such as `Table`. */
   type?: string;
-  columns: { label: string; align?: "start" | "end"; width?: number }[];
+  /** Column definitions, in order; a cell reads its column by index. */
+  columns: {
+    /** Column heading, `caption` secondary text. */
+    label: string;
+    /** Cell alignment; `end` right-aligns numbers. */
+    align?: "start" | "end";
+    /** Fixed column width in px; a column without it shares the free width. */
+    width?: number;
+  }[];
+  /** Body rows; each inner array is one row, matched to `columns` by index. */
   rows: string[][];
 };
 
+/** A labelled section of the Fields view, grouped under a dot and a heading. */
 export type ExtractGroup = {
+  /** Stable identity for the React key. */
   id: string;
+  /** Section heading, `label-md` primary text. */
   label: string;
+  /** Fields and tables of this section, in display order. */
   fields: (ExtractField | ExtractTable)[];
 };
 
+/** Props for {@link DocumentExtractPanel}: the sheet to view, the extracted groups and the footer actions. */
 export type DocumentExtractPanelProps = WithClass<Omit<ComponentProps<"section">, "title">> & {
+  /** Document name in the viewer toolbar; `label-md` primary text, truncated. */
   fileName: string;
+  /** Page indicator at the right of the toolbar. @default "1 / 1" */
   pageLabel?: string;
   /** The paper sheet content. Wrap fields in `ExtractHighlight` to outline what was read. */
   sheet: ReactNode;
+  /** Extracted sections, in display order; the same data feeds the Fields, JSON and Schema views. */
   groups: ExtractGroup[];
+  /** Starting zoom the toolbar shows; 70 draws the sheet at its design size (scale 1) and the range is 30–150. @default 70 */
   defaultZoom?: number;
-  bot?: { initial: string; name: string; elapsed?: string };
+  /** Bot credited in the footer; without it the footer shows no attribution. */
+  bot?: {
+    /** One-letter mark on the 20px brand square. */
+    initial: string;
+    /** Bot name, `caption` secondary text. */
+    name: string;
+    /** Optional run time appended as "· 12s". */
+    elapsed?: string;
+  };
+  /** Fires when the Extract button is pressed; the panel also bumps its run counter, which remounts the active view and replays its entry animation. */
   onExtract?: () => void;
+  /** Fires after Accept all has queued the confirmation of every row, so the confirmed marks land on the next render. */
   onAcceptAll?: () => void;
   /** Makes the file name actionable; without it the name is a plain label. */
   onOpenFile?: () => void;
 };
 
+/** Lowest and highest zoom the toolbar allows, and the step of one press. */
 const ZOOM_MIN = 30;
 const ZOOM_MAX = 150;
 const ZOOM_STEP = 10;
+/** The fit zoom: 100% of the sheet box is drawn at this percent, so the default 70 shows it at its design size. */
 const ZOOM_FIT = 70;
 
+/** Outline colours for `ExtractHighlight`: brand-family tints for reads, neutral and ink for notes and marks. */
 const highlightTone = {
   sky: "border-accent-sky-500-90 bg-accent-sky-500-12",
   brand: "border-accent-sky-700-90 bg-accent-sky-700-12",
@@ -62,7 +107,10 @@ export function ExtractHighlight({
   tone = "sky",
   className,
   ...props
-}: WithClass<ComponentProps<"div">> & { tone?: keyof typeof highlightTone }) {
+}: WithClass<ComponentProps<"div">> & {
+  /** Outline and fill pair: `sky` for a normal read, `brand` for a highlighted one, `neutral` and `ink` for notes. @default "sky" */
+  tone?: keyof typeof highlightTone;
+}) {
   return (
     <div
       className={cn("flex flex-col gap-px rounded-sm border-[1.2px] px-1 py-0.5", highlightTone[tone], className)}
@@ -79,7 +127,12 @@ function isChecked(field: ExtractField, resolved: Set<string>) {
   return field.status === "check" && !resolved.has(field.id);
 }
 
-function Divider({ vertical }: { vertical?: boolean }) {
+/** One hairline between the panel's regions; `vertical` draws it as a column rule for the split layout. */
+// prettier-ignore
+function Divider({ vertical }: {
+  /** Draws a column rule instead of a row rule. */
+  vertical?: boolean;
+}) {
   return (
     <div
       role="separator"
@@ -95,6 +148,31 @@ function stepClass() {
 /**
  * Document extract panel (Paper `YUT-1` / `GWP-0`): a viewer with zoom controls on the left and the extracted
  * fields on the right, with Fields / JSON / Schema views, a per-row confirmation check and an Accept all footer.
+ *
+ * Laid out with container queries, not the viewport: the two columns stack below the 4xl container width and
+ * split above it, with the viewer column fixed at 540px. Zoom runs 30–150 in steps of 10, "Fit" returns to 70
+ * (the sheet's design size), and the sheet is scaled from its top edge, so it never reflows. A field with
+ * `status: "check"` renders as a button that confirms that one row; Accept all confirms every row at once.
+ * The footer counts filled and unresolved rows, keeps a dot per field and credits the bot when `bot` is set.
+ *
+ * @example
+ * ```tsx
+ * <DocumentExtractPanel
+ *   fileName="invoice-0424.pdf"
+ *   groups={[
+ *     {
+ *       id: "vendor",
+ *       label: "Vendor",
+ *       fields: [
+ *         { id: "name", label: "Name", value: "Northwind Supply", type: "Text" },
+ *         { id: "due", label: "Due", value: "Oct 24, 2026", type: "Date", status: "check" },
+ *       ],
+ *     },
+ *   ]}
+ *   sheet={<h1 className="text-title-md">Northwind Supply</h1>}
+ *   onAcceptAll={() => saveExtraction()}
+ * />
+ * ```
  */
 export function DocumentExtractPanel({
   fileName,

package/src/components/empty-state.tsx

@@ -2,17 +2,36 @@ import type { ReactNode } from "react";
 
 import { cn } from "../lib/cn";
 
+/** Props for {@link EmptyState}: an optional illustration, the copy and one action. */
 export type EmptyStateProps = {
-  /** 140px illustration, such as a mascot pose. */
+  /** 140px illustration, such as a mascot pose. The slot is square and the child is stretched to fill it. */
   illustration?: ReactNode;
+  /** Heading, rendered as a `title-md` balanced paragraph. */
   title: ReactNode;
+  /** Supporting copy under the heading, `body-md` secondary text across the full column width. */
   description?: ReactNode;
   /** Action under the text, usually a `Button`. */
   action?: ReactNode;
+  /** Extra classes on the column, merged after the width, spacing and entry animation. */
   className?: string;
 };
 
-/** Figma `Empty state` (64:485): centered 140px mascot, title-md heading, body-md text, action. */
+/**
+ * Figma `Empty state` (64:485): centered 140px mascot, title-md heading, body-md text, action.
+ *
+ * A 360px-max column with a rise-in animation and no border or fill, so it drops into a card, a panel body
+ * or an empty table area without drawing its own surface.
+ *
+ * @example
+ * ```tsx
+ * <EmptyState
+ *   illustration={<img src="/mascots/horon-mascot-welcome.webp" alt="" />}
+ *   title="Meet your first bot"
+ *   description="Give it a role and a task. It keeps working after you close the laptop."
+ *   action={<Button>Create a bot</Button>}
+ * />
+ * ```
+ */
 export function EmptyState({ illustration, title, description, action, className }: EmptyStateProps) {
   return (
     <div

package/src/components/field.tsx

@@ -4,8 +4,12 @@ import { createContext, useContext, type ComponentProps } from "react";
 import { cn } from "../lib/cn";
 import type { ControlSize } from "../lib/size";
 
-type WithClass<T> = Omit<T, "className"> & { className?: string };
+type WithClass<T> = Omit<T, "className"> & {
+  /** Extra classes appended after the part's own classes. */
+  className?: string;
+};
 
+/** `md` outside a `Field`, so a part rendered on its own keeps the default rung rather than throwing. */
 const FieldSizeContext = createContext<ControlSize>("md");
 
 const gapClass: Record<ControlSize, string> = {
@@ -26,12 +30,38 @@ const metaClass: Record<ControlSize, string> = {
   lg: "text-body-sm",
 };
 
-/** Figma `Field examples` (58:163): label, control and help text, 6/8/10px apart. */
+/**
+ * Figma `Field examples` (58:163): label, control and help text, 6/8/10px apart.
+ *
+ * Wraps Base UI's `Field.Root`, a vertical stack (`max-w-full`, left aligned) whose gaps and text
+ * rungs follow `size` through context, so `FieldLabel`, `FieldDescription` and `FieldError` match the
+ * control without repeating the size. `invalid` (or Base UI's own validation) marks the control inside
+ * the field invalid, and the control's box paints its danger border from that.
+ *
+ * @example
+ * ```tsx
+ * import { Field, FieldDescription, FieldError, FieldLabel, Input } from "@horon-ai/react";
+ *
+ * function EmailField() {
+ *   return (
+ *     <Field size="md">
+ *       <FieldLabel htmlFor="email">Email</FieldLabel>
+ *       <Input id="email" type="email" placeholder="you@example.com" />
+ *       <FieldDescription>We only use it to sign you in.</FieldDescription>
+ *       <FieldError>Enter a valid address.</FieldError>
+ *     </Field>
+ *   );
+ * }
+ * ```
+ */
 export function Field({
   size = "md",
   className,
   ...props
-}: WithClass<Omit<ComponentProps<typeof BaseField.Root>, "size">> & { size?: ControlSize }) {
+}: WithClass<Omit<ComponentProps<typeof BaseField.Root>, "size">> & {
+  /** Control rung shared by every part; sets the gap (6/8/10px) and the label and meta type scales. @default "md" */
+  size?: ControlSize;
+}) {
   return (
     <FieldSizeContext.Provider value={size}>
       <BaseField.Root
@@ -42,6 +72,11 @@ export function Field({
   );
 }
 
+/**
+ * Part of {@link Field}. The control's label (`Field.Label`): `label-sm/md/lg` from the field's size,
+ * primary text, and the disabled colour when its control is disabled. Give it `htmlFor` matching the
+ * control's `id`, which is also what makes clicking the text focus the control.
+ */
 export function FieldLabel({ className, ...props }: WithClass<ComponentProps<typeof BaseField.Label>>) {
   const size = useContext(FieldSizeContext);
   return (
@@ -52,11 +87,22 @@ export function FieldLabel({ className, ...props }: WithClass<ComponentProps<typ
   );
 }
 
+/**
+ * Part of {@link Field}. The help line under the control (`Field.Description`) in secondary text:
+ * `caption` at sm and md, `body-sm` at lg. Always full width so the copy wraps inside the field, and
+ * Base UI wires it to the control as the description for assistive tech.
+ */
 export function FieldDescription({ className, ...props }: WithClass<ComponentProps<typeof BaseField.Description>>) {
   const size = useContext(FieldSizeContext);
   return <BaseField.Description className={cn(metaClass[size], "w-full text-text-secondary", className)} {...props} />;
 }
 
+/**
+ * Part of {@link Field}. The validation message (`Field.Error`) in `text-text-danger` at the field's
+ * meta rung. It stays mounted only while it should show: Base UI renders it when the enclosing field is
+ * invalid, or when `match` is set, and keeps it mounted through its exit — the row collapses from `1fr`
+ * to `0fr` as it fades, so the parts below glide up instead of jumping.
+ */
 export function FieldError({ className, children, ...props }: WithClass<ComponentProps<typeof BaseField.Error>>) {
   const size = useContext(FieldSizeContext);
   // Base UI keeps the message mounted through its exit (`data-ending-style`), so the row can close

package/src/components/file-drop.tsx

@@ -4,26 +4,61 @@ import { type ComponentProps, type DragEvent, type ReactNode, useId, useState }
 import { cn } from "../lib/cn";
 import { Spinner } from "./spinner";
 
+/**
+ * How the drop target is painted: `solid` fills it with the raised surface (`bg-bg-surface`), `glass`
+ * leaves it transparent on the veil so imagery behind shows through.
+ */
 export type FileDropSurface = "solid" | "glass";
 
+/** Props of {@link FileDrop}: the native file input attributes plus the target's own state. */
 export type FileDropProps = Omit<ComponentProps<"input">, "className" | "type" | "children" | "onDrop"> & {
-  /** Label next to the icon. */
+  /** Label next to the icon. @default "Drop files here or click to upload" */
   label?: ReactNode;
   /** Shows a spinner in place of the icon while files upload. */
   uploading?: boolean;
   /** Danger rim for a rejected file. */
   rejected?: boolean;
-  /** Called with the dropped files. */
+  /** Called with the dropped or picked files, in picker order; fires on both drop and native file input change. */
   onFiles?: (files: File[]) => void;
-  /** `solid` (default) fills the target with the raised surface; `glass` puts it on the veil over imagery. */
+  /** `solid` (default) fills the target with the raised surface; `glass` puts it on the veil over imagery. @default "solid" */
   surface?: FileDropSurface;
+  /** Extra classes for the label that forms the target. */
   className?: string;
 };
 
 /**
  * Paper `File drop` (1VWI-0): a 1.5px dashed r10 target, icon 16 and a 13/18 500 label centred with gap 8.
- * Dragging swaps the dashes for a 1px brand rim; no shake or bounce. Solid fills with the raised surface,
+ * Dragging keeps the dashed edge and repaints it in the brand border, adds a 1px inset brand rim and, on
+ * `solid`, shifts the fill to `bg-bg-subtle`; no shake or bounce. Solid fills with the raised surface,
  * glass sits on the veil (`veil-drop`) and keeps the dashed border as its only outline.
+ *
+ * The target is a `<label>` around a screen-reader-only `<input type="file">`, so a click opens the native
+ * picker and the control stays keyboard reachable; the focus ring is drawn on the label through
+ * `has-[:focus-visible]`. Drops land in `onFiles` with `DataTransfer.files`, and the input's change event
+ * also calls `onFiles` before forwarding `onChange`. While `uploading`, the icon becomes a spinner, the
+ * input is disabled and drops are ignored; `rejected` paints a danger rim. The target is capped at 550px
+ * and never wider than its parent.
+ *
+ * @example
+ * ```tsx
+ * import { useState } from "react";
+ * import { FileDrop } from "@horon-ai/react";
+ *
+ * function Example() {
+ *   const [uploading, setUploading] = useState(false);
+ *   return (
+ *     <FileDrop
+ *       accept=".pdf,.png"
+ *       label="Drop contracts here or click to upload"
+ *       uploading={uploading}
+ *       onFiles={(files) => {
+ *         setUploading(true);
+ *         void upload(files).finally(() => setUploading(false));
+ *       }}
+ *     />
+ *   );
+ * }
+ * ```
  */
 export function FileDrop({
   label = "Drop files here or click to upload",

package/src/components/filter-bar.tsx

@@ -3,18 +3,27 @@ import { type ComponentProps, type ReactNode, useRef, useState } from "react";
 import { cn } from "../lib/cn";
 import { useActiveIndicator } from "../hooks/use-active-indicator";
 
+/** One option in a `FilterBar`. */
 export type FilterBarItem = {
+  /** Stable value reported through `onValueChange` and compared with `value`. */
   value: string;
+  /** Visible chip text; normally a short noun such as `All` or `Agents`. */
   label: ReactNode;
-  /** Count shown after the label, such as 4. */
+  /** Count shown after the label, such as 4. Omit to hide the slot. */
   count?: number;
+  /** Disables just this option: 40% opacity, not clickable. */
   disabled?: boolean;
 };
 
+/** Props of {@link FilterBar}: the options and the selection, controlled or uncontrolled. */
 export type FilterBarProps = Omit<ComponentProps<"div">, "onChange" | "defaultValue"> & {
+  /** Options in display order; the first one is the initial selection when `defaultValue` is omitted. */
   items: FilterBarItem[];
+  /** Controlled selection. Pass `onValueChange` to hear about clicks. */
   value?: string;
+  /** Initial selection when uncontrolled. @default items[0].value */
   defaultValue?: string;
+  /** Called with the clicked option's `value`; clicks on the already-selected option still fire. */
   onValueChange?: (value: string) => void;
 };
 
@@ -22,6 +31,34 @@ export type FilterBarProps = Omit<ComponentProps<"div">, "onChange" | "defaultVa
  * Paper `Filter bar` (Agents N2): a 5% ink pill track with 30px options; the selected option sits on a sliding 10% ink pill.
  * The pills never wrap, so a screen too narrow for all of them scrolls the track sideways instead of widening the page.
  * The track keeps its intrinsic width (and so stays centred by its parent) unless that width exceeds the box.
+ *
+ * Selection is controlled through `value` or uncontrolled from `defaultValue`, which falls back to the first
+ * item. The group is a `radiogroup` labelled by `aria-label` (`Filter` when omitted), each option a
+ * `<button role="radio" aria-checked>`; the background pill is measured by the active option and hides when
+ * none matches, and it lands without animating on the first paint. There is no roving tab index: every enabled
+ * option is a tab stop, and Space or Enter selects it.
+ *
+ * @example
+ * ```tsx
+ * import { useState } from "react";
+ * import { FilterBar } from "@horon-ai/react";
+ *
+ * function Example() {
+ *   const [scope, setScope] = useState("all");
+ *   return (
+ *     <FilterBar
+ *       aria-label="Scope"
+ *       value={scope}
+ *       onValueChange={setScope}
+ *       items={[
+ *         { value: "all", label: "All", count: 12 },
+ *         { value: "agents", label: "Agents", count: 4 },
+ *         { value: "archived", label: "Archived", disabled: true },
+ *       ]}
+ *     />
+ *   );
+ * }
+ * ```
  */
 export function FilterBar({
   items,