@horon-ai/react 0.1.1 → 0.1.2

package/src/components/message-extras.tsx

@@ -7,7 +7,13 @@ import { IconButton } from "./icon-button";
 import { LiquidGlass } from "./liquid-glass";
 
 /** Figma `Date separator` (Message extras 109:667): caption between two 10% ink lines. */
-export function DateSeparator({ children, className }: { children: ReactNode; className?: string }) {
+// prettier-ignore
+export function DateSeparator({ children, className }: {
+  /** Caption text between the rules, such as "Today" or "Mar 4". */
+  children: ReactNode;
+  /** Extra classes on the row, merged after the built-in ones. */
+  className?: string;
+}) {
   return (
     <div role="separator" className={cn("flex items-center gap-3", className)}>
       <span className="h-px flex-1 bg-overlay-ink-10" />
@@ -17,17 +23,43 @@ export function DateSeparator({ children, className }: { children: ReactNode; cl
   );
 }
 
-export type MessageAction = { label: string; icon: ReactNode; onClick?: () => void };
+/** One button of a {@link MessageActions} pill. */
+export type MessageAction = {
+  /** Accessible label of the button; also its React key, so keep labels unique within a pill. */
+  label: string;
+  /** 16px glyph; sized by the pill's `[&>svg]:size-4`. */
+  icon: ReactNode;
+  /** Fires on click. */
+  onClick?: () => void;
+};
 
-/** Figma `Message actions` (109:667): a pill of 30px icon buttons with 16px icons, solid or regular glass. */
+/**
+ * Figma `Message actions` (109:667): a pill of 30px icon buttons with 16px icons, solid or regular glass.
+ *
+ * Hovering a button fills a circle behind the glyph; each button carries its
+ * label as `aria-label` and the pill exposes `role="toolbar"`. With
+ * `surface="glass"` it paints a `LiquidGlass` layer and the buttons sit above it.
+ *
+ * @example
+ * ```tsx
+ * <MessageActions
+ *   actions={[
+ *     { label: "Copy", icon: <Copy />, onClick: () => copy(text) },
+ *     { label: "Regenerate", icon: <ArrowsClockwise />, onClick: regenerate },
+ *   ]}
+ * />
+ * ```
+ */
 export function MessageActions({
   actions,
   surface = "solid",
   className,
 }: {
+  /** Buttons of the pill, rendered in order; each needs a unique label. */
   actions: MessageAction[];
-  /** `solid` (default) is an opaque surface pill with a default border; `glass` is the regular glass pill. */
+  /** `solid` (default) is an opaque surface pill with a default border; `glass` is the regular glass pill. @default "solid" */
   surface?: "solid" | "glass";
+  /** Extra classes on the pill, merged after the built-in ones. */
   className?: string;
 }) {
   return (
@@ -55,14 +87,20 @@ export function MessageActions({
   );
 }
 
+/** Props for {@link Attachment}: what the file is, how it looks and whether it can be removed. */
 export type AttachmentProps = {
+  /** File name, truncated to one line. */
   name: ReactNode;
   /** Caption, such as "PDF · 2.4 MB". */
   detail?: ReactNode;
   /** Image thumbnail URL; files show a document icon on a sky tile. */
   thumbnail?: string;
+  /** Renders the 32px remove button when set. */
   onRemove?: () => void;
+  /** Accessible label of the remove button.
+   * @default "Remove" */
   removeLabel?: string;
+  /** Extra classes on the card, merged after the built-in ones. */
   className?: string;
 };
 
@@ -103,11 +141,19 @@ export function Attachment({ name, detail, thumbnail, onRemove, removeLabel = "R
   );
 }
 
+/** Props for {@link CodeBlock}: the code text, its language caption and the copy-button labels. */
 export type CodeBlockProps = Omit<ComponentProps<"div">, "className" | "children"> & {
+  /** Source text, rendered verbatim inside a `<code>` in a horizontal scroller. */
   code: string;
+  /** Caption in the header bar, such as "tsx"; the space is kept even when empty. */
   language?: string;
+  /** Copy-button text before the copy succeeds.
+   * @default "Copy" */
   copyLabel?: string;
+  /** Copy-button text for 1500ms after a successful copy.
+   * @default "Copied" */
   copiedLabel?: string;
+  /** Extra classes on the outer `div`, merged after the built-in ones. */
   className?: string;
 };
 

package/src/components/modal.tsx

@@ -4,28 +4,71 @@ import type { ComponentProps, ReactNode } from "react";
 
 import { cn } from "../lib/cn";
 
+/**
+ * Root of a modal; owns open state. Re-exported from Base UI's `Dialog.Root`, so
+ * it accepts `open`, `defaultOpen`, `onOpenChange` and `modal`.
+ */
 export const Modal = BaseDialog.Root;
+
+/**
+ * The element that opens the modal. Base UI gives it the expanded state and the
+ * `aria-controls` link to the popup; use `render` to make an existing button the
+ * trigger.
+ *
+ * Part of {@link ModalContent}.
+ */
 export const ModalTrigger = BaseDialog.Trigger;
+
+/**
+ * A button that closes the modal when clicked. Any `Button`-like element can be
+ * its child; it also returns focus to the trigger.
+ *
+ * Part of {@link ModalContent}.
+ */
 export const ModalClose = BaseDialog.Close;
 
+/**
+ * Width step of the modal popup.
+ *
+ * - `sm` — 400px, for a short form.
+ * - `md` — 560px, the default reading width.
+ * - `lg` — 720px, for a wide editor or table.
+ */
 export type ModalSize = "sm" | "md" | "lg";
+
+/**
+ * Surface of the modal popup.
+ *
+ * - `solid` — the opaque page fill with a `0 24 64` shadow.
+ * - `glass` — the `veil-overlay` material, for a modal that floats over content.
+ */
 export type ModalSurface = "solid" | "glass";
 
-type DivProps = Omit<ComponentProps<"div">, "className"> & { className?: string };
+type DivProps = Omit<ComponentProps<"div">, "className"> & {
+  /** Extra classes on the element, merged after the built-in ones. */
+  className?: string;
+};
 
+/** Props for {@link ModalContent}: title and description, the size and surface, and an optional footer. */
 export type ModalContentProps = Omit<ComponentProps<typeof BaseDialog.Popup>, "className" | "title"> & {
+  /** Modal heading, rendered as the `Dialog.Title` that labels the popup. */
   title: ReactNode;
+  /** Supporting line under the title, rendered as the `Dialog.Description`. */
   description?: ReactNode;
-  /** Width: `sm` 400px, `md` 560px (default), `lg` 720px. Never wider than the viewport minus 32px. */
+  /** Width: `sm` 400px, `md` 560px (default), `lg` 720px. Never wider than the viewport minus 32px.
+   * @default "md" */
   size?: ModalSize;
-  /** `solid` (default) is the opaque page fill with a 0 24 64 shadow; `glass` is the veil (`veil-overlay`). */
+  /** `solid` (default) is the opaque page fill with a 0 24 64 shadow; `glass` is the veil (`veil-overlay`).
+   * @default "solid" */
   surface?: ModalSurface;
   /** Tile or icon before the title. */
   leading?: ReactNode;
-  /** Label for the close button; hides it when `null`. */
+  /** Label for the close button; hides it when `null`.
+   * @default "Close" */
   closeLabel?: string | null;
   /** `ModalFooter`, kept below the scrolling body. */
   footer?: ReactNode;
+  /** Extra classes on the popup, merged after the built-in ones. */
   className?: string;
 };
 
@@ -39,6 +82,30 @@ const widthClass: Record<ModalSize, string> = {
  * A modal for work that needs a form or a longer read, where `Dialog` is a short confirmation. It has three
  * fixed parts: a header (title, description and close), a body that scrolls on its own once the modal reaches
  * the viewport height, and a footer whose actions sit at the right. 24px padding, 20px radius, 32% scrim.
+ *
+ * The popup portals to `document.body` and renders its own backdrop and centred
+ * viewport, so it is unaffected by the caller's stacking context; Base UI traps
+ * focus, closes on Escape and on backdrop press, and restores focus to the
+ * trigger. Only the body scrolls: the header and footer stay put.
+ *
+ * @example
+ * ```tsx
+ * <Modal>
+ *   <ModalTrigger render={<Button variant="solid" />}>Rename workspace</ModalTrigger>
+ *   <ModalContent
+ *     title="Rename workspace"
+ *     description="This changes the name for every member."
+ *     footer={
+ *       <ModalFooter>
+ *         <ModalClose render={<Button variant="solid" />}>Cancel</ModalClose>
+ *         <Button onClick={save}>Save</Button>
+ *       </ModalFooter>
+ *     }
+ *   >
+ *     <Input aria-label="Workspace name" defaultValue="Horon" />
+ *   </ModalContent>
+ * </Modal>
+ * ```
  */
 export function ModalContent({
   title,

package/src/components/orchestrator-panel.tsx

@@ -5,20 +5,26 @@ import { cn } from "../lib/cn";
 import { SegmentedControl } from "./segmented-control";
 import { Spinner } from "./spinner";
 
+/** The lead bot row at the top of {@link OrchestratorPanel}. */
 export type OrchestratorLead = {
   /** One letter shown in the 22px ink tile. */
   initial: string;
+  /** Bot name, next to the tile. */
   name: ReactNode;
-  /** Role caption next to the name, such as "Lead". */
+  /** Role caption next to the name, such as "Lead". Defaults to "Lead" when unset.
+   * @default "Lead" */
   role?: ReactNode;
   /** Status text, such as "1 working". */
   status?: ReactNode;
   /** Shows the 13px spinner while the lead waits on its lanes. */
   running?: boolean;
+  /** Timing label at the right, in caption colour. */
   elapsed?: ReactNode;
 };
 
+/** One step of the lead's plan, listed under its row. */
 export type OrchestratorPlanItem = {
+  /** Step text; also the React key, so keep steps unique. */
   label: string;
   /** Dot color of the lane that runs this step, such as "bg-sky-600". Defaults to the live blue. */
   dotClassName?: string;
@@ -26,35 +32,73 @@ export type OrchestratorPlanItem = {
   running?: boolean;
 };
 
+/** The closing summary card of {@link OrchestratorPanel}. */
 export type OrchestratorSummary = {
+  /** Title of the card.
+   * @default "Summary" */
   title?: ReactNode;
   /** Right-aligned count, such as "1 of 3 returned". */
   count?: ReactNode;
+  /** Body text of the summary. */
   body: ReactNode;
 };
 
+/** Props for {@link OrchestratorPanel}: the header controls, the lead and its plan, the lanes and the summary. */
 export type OrchestratorPanelProps = {
+  /** Panel heading, rendered as the `h3`. */
   title: ReactNode;
-  /** Label before the segmented picker, such as "Bots in parallel". */
+  /** Label before the segmented picker, such as "Bots in parallel". @default "Bots in parallel" */
   parallelLabel?: ReactNode;
-  /** Choices of the parallel picker. */
+  /** Choices of the parallel picker. The picker only renders when this is set. */
   parallelOptions?: number[];
+  /** Controlled picked value; the picker is uncontrolled-looking when unset. */
   parallelValue?: number;
+  /** Fires with the picked number, converted from the segmented control's string value. */
   onParallelChange?: (value: number) => void;
+  /** Text of the Stop button.
+   * @default "Stop" */
   stopLabel?: ReactNode;
   /** Renders the Stop button when set. */
   onStop?: () => void;
+  /** The lead row: tile, name, role, status and elapsed. */
   lead: OrchestratorLead;
+  /** Steps under the lead; each row rises in with a 30ms stagger. Hides the list when empty. */
   plan?: OrchestratorPlanItem[];
   /** `AgentLane` cards; the branch connector draws one elbow per lane. */
   children?: ReactNode;
+  /** Closing summary card; the reveal wrapper collapses when unset. */
   summary?: OrchestratorSummary;
+  /** Extra classes on the panel `section`, merged after the built-in ones. */
   className?: string;
 };
 
 const stagger = (index: number) => ({ "--i": index, animationDelay: `calc(var(--i) * 30ms)` }) as CSSProperties;
 
-/** Figma `Orchestrator` (Agents N1): a 24px-radius solid panel, header with a parallel picker and Stop, a lead row, its plan, branching lanes and a summary. */
+/**
+ * Figma `Orchestrator` (Agents N1): a 24px-radius solid panel, header with a parallel picker and Stop, a lead row, its plan, branching lanes and a summary.
+ *
+ * Renders a lead bot that fans work out to lane cards: the connector draws one
+ * elbow per child and a vertical trunk between them, and the plan rows and lane
+ * cards rise in with a 30ms stagger. The summary does not rise; it is revealed by
+ * the `motion-reveal` wrapper around it. Every part is optional except `title` and
+ * `lead`, so the panel works as a bare lead view too.
+ *
+ * @example
+ * ```tsx
+ * <OrchestratorPanel
+ *   title="Orchestrator"
+ *   parallelOptions={[1, 2, 3]}
+ *   parallelValue={2}
+ *   onParallelChange={setParallel}
+ *   onStop={stop}
+ *   lead={{ initial: "H", name: "Horon", status: "2 working", running: true }}
+ *   plan={[{ label: "Collect sources" }, { label: "Draft the summary", running: true }]}
+ *   summary={{ count: "0 of 2 returned", body: "Lanes are still running." }}
+ * >
+ *   <AgentLane status="running" bot={{ initial: "R", name: "Researcher" }} task="Collect sources" />
+ * </OrchestratorPanel>
+ * ```
+ */
 export function OrchestratorPanel({
   title,
   parallelLabel = "Bots in parallel",

package/src/components/page-header.tsx

@@ -5,20 +5,43 @@ import { cn } from "../lib/cn";
 import { IconButton } from "./icon-button";
 import { LiquidGlass } from "./liquid-glass";
 
+/** Props for {@link PageHeader}: the title row, an optional back button, trailing actions and a filter row. */
 export type PageHeaderProps = {
+  /** Page title, rendered as the `h1`; truncated with an ellipsis when it does not fit. */
   title: ReactNode;
+  /** Renders a leading 40px back `IconButton` when set; the header drops the title's left padding in exchange. */
   onBack?: () => void;
+  /** Accessible label of the back button; `IconButton` sets it as `aria-label` and shows no visible tooltip.
+   * @default "Back" */
   backLabel?: string;
   /** Trailing 40px icon buttons, such as search. */
   actions?: ReactNode;
-  /** Content under the top row, such as a `SegmentedControl` filter. */
+  /** Content under the top row, such as a `SegmentedControl` filter. Animates in with `swap-move` when it appears. */
   children?: ReactNode;
-  /** `solid` (default) is an opaque surface header with a default border; `glass` is the regular glass header. */
+  /** `solid` (default) is an opaque surface header with a default border; `glass` is the regular glass header. @default "solid" */
   surface?: "solid" | "glass";
+  /** Extra classes on the `header` element, merged after the built-in ones. */
   className?: string;
 };
 
-/** Figma `Header with filter` (Segmented filters 88:723): a 28px-radius header, 8px padding, solid or regular glass. */
+/**
+ * Figma `Header with filter` (Segmented filters 88:723): a 28px-radius header, 8px padding, solid or regular glass.
+ *
+ * A single row of back button, title and actions, plus an optional filter row
+ * below it. The `glass` surface paints a `LiquidGlass` layer behind the content
+ * and keeps the header transparent.
+ *
+ * @example
+ * ```tsx
+ * <PageHeader
+ *   title="Sources"
+ *   onBack={() => history.back()}
+ *   actions={<IconButton label="Search" icon={<MagnifyingGlass />} />}
+ * >
+ *   <SegmentedControl value="all" onValueChange={() => {}} items={[{ value: "all", label: "All" }]} />
+ * </PageHeader>
+ * ```
+ */
 export function PageHeader({
   title,
   onBack,

package/src/components/plan-card.tsx

@@ -5,11 +5,20 @@ import type { ReactNode } from "react";
 import { cn } from "../lib/cn";
 import { Spinner } from "./spinner";
 
+/**
+ * Footer state of a `PlanCard`: at most one at a time, and setting it expands the
+ * footer.
+ *
+ * - `running` shows a 14px spinner and keeps the footer text in the primary colour.
+ * - `failed` shows a warning icon and tints the footer text with `text-text-danger`.
+ */
 export type PlanCardStatus = "running" | "failed";
 
+/** Props for {@link PlanCard}: a label, title and step list, plus the optional status footer. */
 export type PlanCardProps = {
   /** Label line next to the 16px list icon, such as "Plan · 5 steps". */
   label?: ReactNode;
+  /** Plan title, rendered as the `h3` under the label. */
   title: ReactNode;
   /** `PlanStep`s, stacked without dividers. */
   children?: ReactNode;
@@ -17,11 +26,29 @@ export type PlanCardProps = {
   status?: PlanCardStatus;
   /** Footer text, such as "Stopped · step 4 failed" or "Running · 1 of 5". */
   statusLabel?: ReactNode;
+  /** Right-aligned footer timestamp or duration, kept in caption colour. */
   elapsed?: ReactNode;
+  /** Extra classes on the `section` element, merged after the built-in ones. */
   className?: string;
 };
 
-/** Figma `Plan card` (Agents N3): a 20px-radius solid card with a label, title, the steps and a status footer. */
+/**
+ * Figma `Plan card` (Agents N3): a 20px-radius solid card with a label, title, the steps and a status footer.
+ *
+ * The footer is a `Collapsible` panel that stays mounted, so passing and clearing
+ * `status` plays the collapse animation instead of mounting and unmounting. Only
+ * the footer text fades in again, and only when `status` changes; the label line
+ * above the title does not animate.
+ *
+ * @example
+ * ```tsx
+ * <PlanCard label="Plan · 3 steps" title="Ship the parser" status="running" statusLabel="Running · 1 of 3">
+ *   <PlanStep status="done" index={1} title="Read the spec" />
+ *   <PlanStep status="running" index={2} title="Write the parser" />
+ *   <PlanStep status="pending" index={3} title="Publish" last />
+ * </PlanCard>
+ * ```
+ */
 export function PlanCard({ label, title, children, status, statusLabel, elapsed, className }: PlanCardProps) {
   return (
     <section

package/src/components/plan-step.tsx

@@ -4,25 +4,65 @@ import type { ReactNode } from "react";
 import { cn } from "../lib/cn";
 import { Spinner } from "./spinner";
 
+/**
+ * State of one step in a plan.
+ *
+ * - `done` — finished: sky marker with a check and a sky rail running to the next step.
+ * - `running` — in progress: spinner on a subtle fill.
+ * - `failed` — stopped with an error: danger marker with `!` and the error line expanded.
+ * - `pending` — not started: outlined marker that shows the step number.
+ */
 export type PlanStepStatus = "done" | "running" | "failed" | "pending";
 
+/**
+ * Props for {@link PlanStep}. Only `status`, `index` and `title` are required; everything else is
+ * optional decoration around the marker and the title line.
+ */
 export type PlanStepProps = {
+  /** Current step state; drives the marker glyph, the marker fill and the rail color. */
   status: PlanStepStatus;
   /** Step number, shown on pending steps. */
   index: number;
+  /** Step title; primary while done, running or failed, secondary while pending. */
   title: ReactNode;
+  /** Secondary line under the title, next to the tool tag. */
   description?: ReactNode;
   /** Tool id in mono, such as "stripe.query". */
   tool?: ReactNode;
+  /** Timing label at the right of the title; rendered only while `done` or `running`. */
   elapsed?: ReactNode;
+  /** Error line under the title, revealed only when `status` is `failed`. */
   error?: ReactNode;
+  /** Adds a "Retry from here" button in the expanded error block; it is inert unless `status` is `failed`. */
   onRetry?: () => void;
   /** Hides the rail line under the last step. */
   last?: boolean;
+  /** Classes merged onto the outer row. */
   className?: string;
 };
 
-/** Figma `Plan step` (Agent plan 191:8296): a 24px marker on a 2px rail, sky when done. */
+/**
+ * Figma `Plan step` (Agent plan 191:8296): a 24px marker on a 2px rail, sky when done.
+ *
+ * Stack the steps of an agent plan vertically and pass `last` to the final one so the rail stops
+ * there. The marker cross-fades on every status change, and the error block collapses unless the
+ * step failed.
+ *
+ * @example
+ * ```tsx
+ * import { PlanStep } from "@horon-ai/react";
+ *
+ * function Example() {
+ *   return (
+ *     <div>
+ *       <PlanStep status="done" index={1} title="Read the brief" elapsed="2s" />
+ *       <PlanStep status="running" index={2} title="Search the web" tool="web.search" />
+ *       <PlanStep status="pending" index={3} title="Write the summary" last />
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
 export function PlanStep({
   status,
   index,

package/src/components/plugin-row.tsx

@@ -7,29 +7,87 @@ import { IconButton } from "./icon-button";
 import { Menu, MenuContent, MenuTrigger } from "./menu";
 import { Switch } from "./switch";
 
+/**
+ * Props for {@link PluginRow}. The row also forwards every other `div` prop (except `children`)
+ * to the outer element, so `id`, `data-*` and DOM handlers work as usual.
+ */
 export type PluginRowProps = Omit<ComponentProps<"div">, "children"> & {
   /** Two-letter initials shown on the 40px tile. */
   initials: string;
+  /** Plugin name; truncated when the row gets narrow. */
   name: ReactNode;
+  /** Version string drawn in mono next to the name. */
   version?: ReactNode;
   /** Text of the update pill next to the version; omit when up to date. */
   updateBadge?: ReactNode;
+  /** Author line under the name. */
   author?: ReactNode;
+  /** Adds the sky "Verified" check after the author; only shown when `author` is set. */
   verified?: boolean;
   /** Capability chips, each with an optional 11px icon. */
-  chips?: { id: string; label: ReactNode; icon?: ReactNode }[];
+  chips?: {
+    /** Stable key for the chip. */
+    id: string;
+    /** Chip text. */
+    label: ReactNode;
+    /** Optional leading glyph, sized 11px. */
+    icon?: ReactNode;
+  }[];
+  /** Switch state for the plugin. Pass it with `onEnabledChange` to control the toggle. */
   enabled?: boolean;
+  /** Fires with the next switch state when the plugin is enabled or disabled. */
   onEnabledChange?: (enabled: boolean) => void;
-  /** Shows the Update button when set. */
+  /** Shows the Update button when set; without it the button stays collapsed. */
   onUpdate?: () => void;
+  /**
+   * Label of the Update button.
+   * @default "Update"
+   */
   updateLabel?: string;
+  /**
+   * Accessible name of the enable/disable switch.
+   * @default "Enabled"
+   */
   toggleLabel?: string;
+  /**
+   * Accessible name of the overflow menu button.
+   * @default "More"
+   */
   overflowLabel?: string;
   /** Items of the overflow menu; the menu button is hidden without them. */
   menu?: ReactNode;
 };
 
-/** Paper `Plugin row` (Settings 1VKS-0): tile, name with version and update pill, verified author, chips, and Update, Switch and overflow actions. */
+/**
+ * Paper `Plugin row` (Settings 1VKS-0): tile, name with version and update pill, verified author, chips, and Update, Switch and overflow actions.
+ *
+ * Rows stack directly in a list: each one draws its own bottom divider and drops it on the last
+ * child. The Update button collapses when `onUpdate` is missing, and the overflow menu only renders
+ * when `menu` has content.
+ *
+ * @example
+ * ```tsx
+ * import { MenuItem, PluginRow } from "@horon-ai/react";
+ *
+ * function Example() {
+ *   return (
+ *     <PluginRow
+ *       initials="ST"
+ *       name="Stripe"
+ *       version="2.4.1"
+ *       updateBadge="Update ready"
+ *       author="Stripe"
+ *       verified
+ *       chips={[{ id: "payments", label: "Payments" }]}
+ *       enabled
+ *       onEnabledChange={() => {}}
+ *       onUpdate={() => {}}
+ *       menu={<MenuItem>Uninstall</MenuItem>}
+ *     />
+ *   );
+ * }
+ * ```
+ */
 export function PluginRow({
   initials,
   name,

package/src/components/progress.tsx

@@ -3,13 +3,43 @@ import type { ComponentProps } from "react";
 
 import { cn } from "../lib/cn";
 
+/**
+ * Props for {@link Progress}. The remaining Base UI `Progress.Root` props (`min`, `max`, `format`,
+ * `locale`, `getAriaValueText`, `aria-valuetext`) pass through; the label is a separate
+ * `Progress.Label` part, which this wrapper does not render.
+ */
 export type ProgressProps = Omit<ComponentProps<typeof BaseProgress.Root>, "className" | "value"> & {
+  /** Classes merged onto the 240px root. */
   className?: string;
-  /** 0-100. Omit it (or pass `null`) for the indeterminate bar. */
+  /**
+   * Determinate progress in percent (0-100). Omit it (or pass `null`) for the indeterminate bar,
+   * which animates a third-width sweep inside the track.
+   * @default null
+   */
   value?: number | null;
 };
 
-/** Figma `Progress bar` (in Loading 109:733): a 6px 8% ink track with an ink fill. */
+/**
+ * Figma `Progress bar` (in Loading 109:733): a 6px 8% ink track with an ink fill.
+ *
+ * The width animates on a 400ms quint curve when `value` changes, so a value fed from state reads
+ * as movement rather than a jump. Base UI supplies the `progressbar` role and the `aria-valuenow`
+ * wiring.
+ *
+ * @example
+ * ```tsx
+ * import { Progress } from "@horon-ai/react";
+ *
+ * function Example() {
+ *   return (
+ *     <div>
+ *       <Progress value={64} aria-label="Upload" />
+ *       <Progress aria-label="Loading" />
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
 export function Progress({ className, value = null, ...props }: ProgressProps) {
   return (
     <BaseProgress.Root value={value} className={cn("w-60", className)} {...props}>