@horon-ai/react 0.1.1 → 0.1.3

package/src/components/source-row.tsx

@@ -3,26 +3,41 @@ import type { ReactNode } from "react";
 
 import { cn } from "../lib/cn";
 
+/**
+ * Overall state of an indexed source: `ready` when every stage finished, `indexing` while the
+ * pipeline runs, and `failed` when a stage broke and Retry is offered.
+ */
 export type SourceStatus = "ready" | "indexing" | "failed";
 
+/** Props of {@link SourceRow}: the source's identity, its pipeline state and the Retry action. */
 export type SourceRowProps = {
+  /** Drives the default stage states, the detail color and which trailing control appears. */
   status: SourceStatus;
   /** 16px source icon on the 32px tile. */
   icon: ReactNode;
+  /** Source name, one truncated line at `label-md`. */
   name: ReactNode;
   /** Pages and chunks, progress, or the error. */
   detail: ReactNode;
-  /** 0-100 while indexing. */
+  /** 0-100 while indexing. @default 0 */
   progress?: number;
+  /** Called by the Retry button, which only appears when `status` is `failed`. */
   onRetry?: () => void;
-  /** `card` is a standalone subtle row; `list` is transparent with a 1px divider, for stacking inside a list. */
+  /** `card` is a standalone subtle row; `list` is transparent with a 1px divider, for stacking inside a list. @default "card" */
   variant?: "card" | "list";
-  /** Pipeline stage states; defaults to Parse, Chunk, Embed, Index derived from `status`. */
+  /** Pipeline stage states; defaults to Parse, Chunk, Embed, Index derived from `status`. @default `defaultStages[status]`: `ready` is all `done`, `indexing` is `done, done, active, todo`, `failed` is `done, done, failed, todo` */
   stages?: SourceStages;
+  /** Extra classes on the row, which owns the radius, border or divider. */
   className?: string;
 };
 
+/**
+ * One stage of the parse → chunk → embed → index pipeline: `done` is a 35% ink bar, `active`
+ * shows the live progress fill, `todo` is 8% ink and `failed` takes the red accent.
+ */
 export type SourceStage = "done" | "active" | "todo" | "failed";
+
+/** The four pipeline stages in display order: parse, chunk, embed, index. */
 export type SourceStages = [SourceStage, SourceStage, SourceStage, SourceStage];
 const stageNames = ["parse", "chunk", "embed", "index"] as const;
 
@@ -36,7 +51,31 @@ const stageFill = { done: "bg-overlay-ink-35", todo: "bg-overlay-ink-8", failed:
 const stage = (state: keyof typeof stageFill) =>
   cn("h-[3px] w-6 overflow-clip rounded-full transition-colors duration-150 sm:w-11", stageFill[state]);
 
-/** Figma `Source row` (Knowledge base): a flat row with a four-stage pipeline (parse, chunk, embed, index). */
+/**
+ * Figma `Source row` (Knowledge base): a flat row with a four-stage pipeline (parse, chunk, embed, index).
+ *
+ * The four 24px stage bars (44px from `sm` up) show the pipeline; the `active` bar fills to
+ * `progress`. The trailing slot is state-specific: a check when ready, a live percentage while
+ * indexing, and a Retry button when failed, where the detail line turns danger red with a warning icon.
+ *
+ * @example
+ * ```tsx
+ * import { FilePdf } from "@phosphor-icons/react";
+ * import { SourceRow } from "@horon-ai/react";
+ *
+ * function IndexingSource() {
+ *   return (
+ *     <SourceRow
+ *       status="indexing"
+ *       icon={<FilePdf />}
+ *       name="Q4 launch brief.pdf"
+ *       detail="42 pages · embedding"
+ *       progress={68}
+ *     />
+ *   );
+ * }
+ * ```
+ */
 export function SourceRow({
   status,
   icon,

package/src/components/spinner.tsx

@@ -1,17 +1,44 @@
 import { cn } from "../lib/cn";
 
+/**
+ * Named spinner rungs, in 14/16/24/32px (`xs`, `sm`, `md`, `lg`); a raw number is also
+ * accepted for one-off sizes.
+ */
 export type SpinnerSize = "xs" | "sm" | "md" | "lg";
 
+/** Props of {@link Spinner}: a rung or pixel size, the accessible label, and extra classes. */
 export type SpinnerProps = {
-  /** Named size, or a pixel size for the one-off spinners in agent rows (12, 15, 20). */
+  /** Named size, or a pixel size for the one-off spinners in agent rows (12, 15, 20). @default "sm" */
   size?: SpinnerSize | number;
+  /** Accessible name announced while spinning (`role="status"`). @default "Loading" */
   label?: string;
+  /** Extra classes on the `<svg>`; `animate-spin` and `shrink-0` are always applied. */
   className?: string;
 };
 
 const sizeClass: Record<SpinnerSize, string> = { xs: "size-3.5", sm: "size-4", md: "size-6", lg: "size-8" };
 
-/** Figma `Spinner` (Loading 109:733): a 10% ink ring with a quarter ink arc, 11% stroke. */
+/**
+ * Figma `Spinner` (Loading 109:733): a 10% ink ring with a quarter ink arc, 11% stroke.
+ *
+ * Sizes are fixed pixel rungs (`xs` 14px, `sm` 16px, `md` 24px, `lg` 32px) or a raw number;
+ * it never shrinks, spins for as long as it is mounted, and announces `label` through
+ * `role="status"`.
+ *
+ * @example
+ * ```tsx
+ * import { Spinner } from "@horon-ai/react";
+ *
+ * function Saving() {
+ *   return (
+ *     <span className="flex items-center gap-2 text-text-secondary">
+ *       <Spinner size="sm" label="Saving" />
+ *       Saving
+ *     </span>
+ *   );
+ * }
+ * ```
+ */
 export function Spinner({ size = "sm", label = "Loading", className }: SpinnerProps) {
   return (
     <svg

package/src/components/split-button.tsx

@@ -5,21 +5,55 @@ import type { ComponentProps, ReactNode } from "react";
 import { cn } from "../lib/cn";
 import { Menu, MenuContent, MenuTrigger } from "./menu";
 
+/**
+ * Props of {@link SplitButton}: the Base UI button props (`onClick`, `disabled`, `type`, plus
+ * aria attributes) with the label, icon and menu the split pill adds.
+ */
 export type SplitButtonProps = Omit<ComponentProps<typeof BaseButton>, "className" | "children"> & {
-  /** Primary action label. */
+  /** Primary action label, rendered at `label-md` inside the left half. */
   children: ReactNode;
   /** 16px leading icon. */
   icon?: ReactNode;
-  /** Menu items (`MenuItem`, `MenuSeparator`) opened by the caret. */
+  /** Menu items (`MenuItem`, `MenuSeparator`) opened by the caret. Without it the pill is a single full-round button. */
   menu?: ReactNode;
+  /** Accessible name of the caret trigger. @default "More actions" */
   menuLabel?: string;
+  /** Extra classes on the pill container, which owns the fill, the press scale and the disabled dim. */
   className?: string;
 };
 
 const halfClass =
   "relative inline-flex h-full cursor-pointer items-center select-none focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-text-brand data-disabled:cursor-not-allowed";
 
-/** Paper `Split button` (1VGK-0): one primary pill on `Button`'s 32px rung, two hit areas split by a 1x18 bar. */
+/**
+ * Paper `Split button` (1VGK-0): one primary pill on `Button`'s 32px rung, two hit areas split by a 1x18 bar.
+ *
+ * The container owns the primary fill, the 0.97 press scale and the 40% disabled dim, so both halves
+ * stay one pill; the caret opens the menu aligned to the end and rotates while the popup is open.
+ * Without `menu` there is no divider or caret and the button keeps a full round shape.
+ *
+ * @example
+ * ```tsx
+ * import { MenuItem, SplitButton } from "@horon-ai/react";
+ *
+ * function Publish() {
+ *   return (
+ *     <SplitButton
+ *       menuLabel="Publish options"
+ *       onClick={() => publishNow()}
+ *       menu={
+ *         <>
+ *           <MenuItem onClick={() => schedulePublish()}>Schedule</MenuItem>
+ *           <MenuItem onClick={() => saveDraft()}>Save as draft</MenuItem>
+ *         </>
+ *       }
+ *     >
+ *       Publish
+ *     </SplitButton>
+ *   );
+ * }
+ * ```
+ */
 export function SplitButton({
   children,
   icon,

package/src/components/switch.tsx

@@ -4,12 +4,19 @@ import type { ComponentProps, ReactNode } from "react";
 import { cn } from "../lib/cn";
 import type { ControlSize } from "../lib/size";
 
-/** `compact` is the 40x24 Paper bot-memory switch and keeps its own rung. */
+/** Shared control rungs plus `compact`, the 40x24 Paper bot-memory switch that keeps its own rung. */
 export type SwitchSize = ControlSize | "compact";
 
+/**
+ * Props of {@link Switch}: Base UI's switch root props (`checked`, `defaultChecked`,
+ * `onCheckedChange`, `disabled`, `name`) plus the rung and the optional inline label.
+ */
 export type SwitchProps = Omit<ComponentProps<typeof BaseSwitch.Root>, "className"> & {
+  /** Track and thumb rung: `sm` 32x20, `md` 44x26, `lg` 52x30, `compact` 40x24. @default "md" */
   size?: SwitchSize;
+  /** When set, the switch sits at the end of a label row and the whole row toggles it. */
   label?: ReactNode;
+  /** Extra classes, applied to the label row when `label` is set and to the switch itself otherwise. */
   className?: string;
 };
 
@@ -38,6 +45,29 @@ const labelClass: Record<SwitchSize, string> = {
  * Switch: MD 44x26 and SM 32x20 tracks with a white thumb 2px in; LG is 52x30; COMPACT 40x24 with an
  * 18px thumb 3px in (Paper bot memory). The thumb stays white on the grey track in both themes and
  * takes the inverse of the ink fill when checked, so the checked state reads the same in dark.
+ *
+ * Renders Base UI's switch button (`role="switch"`, `aria-checked`) and is controlled or
+ * uncontrolled the same way; the thumb springs across in 220ms and the track repaints on hover,
+ * checked and disabled states. With `label` the control becomes a `<label>` row whose text
+ * toggles it, so the switch does not need its own accessible name.
+ *
+ * @example
+ * ```tsx
+ * import { useState } from "react";
+ * import { Switch } from "@horon-ai/react";
+ *
+ * function MemoryToggle() {
+ *   const [remember, setRemember] = useState(true);
+ *   return (
+ *     <Switch
+ *       label="Remember this bot's memory"
+ *       size="compact"
+ *       checked={remember}
+ *       onCheckedChange={setRemember}
+ *     />
+ *   );
+ * }
+ * ```
  */
 export function Switch({ size = "md", label, className, ...props }: SwitchProps) {
   const control = (

package/src/components/tab-bar.tsx

@@ -5,17 +5,34 @@ import type { ControlSize } from "../lib/size";
 import { useActiveIndicator } from "../hooks/use-active-indicator";
 import { LiquidGlass } from "./liquid-glass";
 
-export type TabBarItem = { value: string; label: string; icon: ReactNode };
+/** One destination in a {@link TabBar}: its stable value, the accessible name, and the icon shown in the tab. */
+export type TabBarItem = {
+  /** Identifies the tab; compared against the bar's `value`. */
+  value: string;
+  /** Accessible name of the icon-only button. */
+  label: string;
+  /** The tab icon; sized by the bar (20/22/24px per rung). */
+  icon: ReactNode;
+};
+
+/** Tab bar rungs: `sm` 56x40, `md` 64x48 (the Figma size) and `lg` 72x56. */
 export type TabBarSize = ControlSize;
 
+/** Props of {@link TabBar}: the destinations, the selected value, and the track rung and surface. */
 export type TabBarProps = {
+  /** Destinations in display order; each keeps its fixed tap size and scrolls if the row overflows. */
   items: TabBarItem[];
+  /** Currently selected item's `value`; the control is fully controlled. */
   value: string;
+  /** Called with the clicked item's `value`; the bar itself does not change `value`. */
   onValueChange?: (value: string) => void;
-  /** `md` is the 64x48 Figma tab; `sm` is 56x40 and `lg` 72x56. */
+  /** `md` is the 64x48 Figma tab; `sm` is 56x40 and `lg` 72x56. @default "md" */
   size?: TabBarSize;
+  /** `glass` (default) adds the liquid glass layer inside the pill; `flat` keeps the glass fill but omits that layer. @default "glass" */
   surface?: "glass" | "flat";
+  /** Accessible name of the `<nav>` landmark. @default "Main" */
   "aria-label"?: string;
+  /** Extra classes on the scrolling track. */
   className?: string;
 };
 
@@ -35,6 +52,34 @@ const tabClass: Record<TabBarSize, string> = {
  * Figma `Tab bar` (63:441): the mobile bottom navigation, a regular-glass pill
  * with icon-only 64x48 tabs and 22px icons; the current tab is a 10% ink pill
  * that slides to the tab you pick.
+ *
+ * The bar is controlled: it reports clicks through `onValueChange` and marks the matching
+ * item with `aria-current="page"`. Tabs keep their fixed tap size, so an over-wide row scrolls
+ * horizontally instead of shrinking; the moving pill is measured from the current tab and
+ * honours `prefers-reduced-motion`.
+ *
+ * @example
+ * ```tsx
+ * import { useState } from "react";
+ * import { House, MagnifyingGlass, User } from "@phosphor-icons/react";
+ * import { TabBar } from "@horon-ai/react";
+ *
+ * function MobileNav() {
+ *   const [tab, setTab] = useState("home");
+ *   return (
+ *     <TabBar
+ *       aria-label="Sections"
+ *       value={tab}
+ *       onValueChange={setTab}
+ *       items={[
+ *         { value: "home", label: "Home", icon: <House /> },
+ *         { value: "search", label: "Search", icon: <MagnifyingGlass /> },
+ *         { value: "profile", label: "Profile", icon: <User /> },
+ *       ]}
+ *     />
+ *   );
+ * }
+ * ```
  */
 export function TabBar({
   items,

package/src/components/tabs.tsx

@@ -5,23 +5,61 @@ import { cn } from "../lib/cn";
 import type { ControlSize } from "../lib/size";
 import { LiquidGlass } from "./liquid-glass";
 
+/** Tab rungs, shared with `ControlSize`: `sm` 26px, `md` 30px and `lg` 36px tab height. */
 export type TabsSize = ControlSize;
 
 /** `Tabs` owns the size; every `TabsTab` inside reads it so one list stays on one rung. */
 const TabsSizeContext = createContext<ControlSize>("md");
 
+/**
+ * Shape of a tab list: `pill` is the tray of rounded pill tabs, `underline` is a bare
+ * text row with a 2px bar that slides under the active tab.
+ */
 export type TabsListVariant = "pill" | "underline";
 
 /** `TabsList` owns the variant; its `TabsTab`s read it to drop the pill shape on the underline list. */
 const TabsVariantContext = createContext<TabsListVariant>("pill");
 
-type WithClass<T> = Omit<T, "className"> & { className?: string };
+/** Drops the native `className` slot and re-adds it as optional, so every part takes extra classes. */
+type WithClass<T> = Omit<T, "className"> & {
+  /** Extra classes appended after the part's own classes, so conflicting utilities win. */
+  className?: string;
+};
 
+/**
+ * The root of a tab set (Figma `Tabs` example 62:353): it stacks the list and panels in a
+ * 16px-gap column, caps at its container, and provides the size rung every `TabsTab` inside
+ * reads. It is controlled or uncontrolled like Base UI's tabs (`value`/`defaultValue` plus
+ * `onValueChange`), and panels are matched to tabs by `value`.
+ *
+ * @example
+ * ```tsx
+ * import { Tabs, TabsList, TabsPanel, TabsTab } from "@horon-ai/react";
+ *
+ * function SettingsTabs() {
+ *   return (
+ *     <Tabs defaultValue="general">
+ *       <TabsList variant="underline">
+ *         <TabsTab value="general">General</TabsTab>
+ *         <TabsTab value="billing" count={3}>
+ *           Billing
+ *         </TabsTab>
+ *       </TabsList>
+ *       <TabsPanel value="general">General settings</TabsPanel>
+ *       <TabsPanel value="billing">Three open invoices</TabsPanel>
+ *     </Tabs>
+ *   );
+ * }
+ * ```
+ */
 export function Tabs({
   size = "md",
   className,
   ...props
-}: WithClass<ComponentProps<typeof BaseTabs.Root>> & { size?: TabsSize }) {
+}: WithClass<ComponentProps<typeof BaseTabs.Root>> & {
+  /** Rung for this tab set: tab heights of 26px (`sm`), 30px (`md`) or 36px (`lg`). @default "md" */
+  size?: TabsSize;
+}) {
   return (
     <TabsSizeContext.Provider value={size}>
       <BaseTabs.Root className={cn("flex max-w-full min-w-0 flex-col gap-4", className)} {...props} />
@@ -44,6 +82,8 @@ const listClass: Record<TabsSize, string> = {
  *
  * `variant="underline"` is the document variant: no tray, a full-width 1px default border under
  * the tabs, and a 2px primary bar that slides under the active tab. `surface` does not apply to it.
+ *
+ * Part of {@link Tabs}; it also provides the variant every `TabsTab` inside reads.
  */
 export function TabsList({
   variant = "pill",
@@ -52,9 +92,9 @@ export function TabsList({
   children,
   ...props
 }: WithClass<ComponentProps<typeof BaseTabs.List>> & {
-  /** `pill` (default) is the tray of pill tabs; `underline` is a text row with a sliding underline. */
+  /** `pill` (default) is the tray of pill tabs; `underline` is a text row with a sliding underline. @default "pill" */
   variant?: TabsListVariant;
-  /** `solid` (default) is an opaque surface tray with a default border; `glass` is the regular glass tray. */
+  /** `solid` (default) is an opaque surface tray with a default border; `glass` is the regular glass tray. @default "solid" */
   surface?: "solid" | "glass";
 }) {
   const size = useContext(TabsSizeContext);
@@ -112,7 +152,14 @@ const countClass: Record<TabsSize, string> = {
   lg: "h-6 px-2",
 };
 
-/** Figma `Tabs` (62:335): a pill tab; the list's indicator draws the selection under the active tab. */
+/**
+ * Figma `Tabs` (62:335): a pill tab; the list's indicator draws the selection under the active tab.
+ *
+ * Part of {@link Tabs}. The tab takes its height, text and icon size from the surrounding
+ * `Tabs`; on an underline list it drops the pill radius and side padding. Base UI marks it
+ * `role="tab"` with `aria-selected`, and hover or the active state moves the label to the
+ * primary text color.
+ */
 export function TabsTab({
   className,
   icon,
@@ -157,6 +204,13 @@ export function TabsTab({
   );
 }
 
+/**
+ * The content region of one tab, rendered by Base UI with `role="tabpanel"` and matched to a
+ * `TabsTab` by `value`. The outline is suppressed, and a panel swap slides the content in 4px
+ * over the shared 200ms swap move; a change in content height is not animated.
+ *
+ * Part of {@link Tabs}.
+ */
 export function TabsPanel({ className, ...props }: WithClass<ComponentProps<typeof BaseTabs.Panel>>) {
   return <BaseTabs.Panel className={cn("animate-swap-move outline-none", className)} {...props} />;
 }

package/src/components/task-row.tsx

@@ -4,26 +4,46 @@ import type { ReactNode } from "react";
 import { cn } from "../lib/cn";
 import { Spinner } from "./spinner";
 
+/**
+ * Task lifecycle states a {@link TaskRow} renders: `running` shows a spinner and Cancel,
+ * `review` a check and Review, `failed` a warning and Retry, `done` a muted check and Archive.
+ */
 export type TaskStatus = "running" | "review" | "failed" | "done";
 
+/** Props of {@link TaskRow}: the task's state and texts plus the actions offered for that state. */
 export type TaskRowProps = {
+  /** Drives the status icon, the message color and which actions appear. */
   status: TaskStatus;
+  /** Task name, one truncated line at `label-lg`. */
   title: ReactNode;
   /** Elapsed time, such as "1m 56s". */
   elapsed?: ReactNode;
   /** Bot initial and name. */
-  bot: { initial: string; name: ReactNode; tileClassName?: string };
+  bot: {
+    /** One or two characters shown in the 18px tile; falls back to the status color when `tileClassName` is absent. */
+    initial: string;
+    /** Bot name after the tile, kept on one line. */
+    name: ReactNode;
+    /** Overrides the status-driven tile fill; the text is forced to `text-inverse` when set. */
+    tileClassName?: string;
+  };
+  /** Project shown after the bot name, separated by a dot and a folder icon. */
   project?: ReactNode;
   /** Status line: the current step, the result or the error. */
   message: ReactNode;
   /** Caption after the message, such as "2 drafts · 1 calendar change". */
   detail?: ReactNode;
+  /** Called by the Cancel pill; shown only while `running`. */
   onCancel?: () => void;
+  /** Called by the Retry pill; shown only when `failed`. */
   onRetry?: () => void;
+  /** Called by the Review pill; shown only when `review`. */
   onReview?: () => void;
+  /** Called by the archive icon button; shown when `review` or `done`. */
   onArchive?: () => void;
-  /** `card` is a standalone subtle row; `list` is transparent with a 1px divider, for stacking inside a list. */
+  /** `card` is a standalone subtle row; `list` is transparent with a 1px divider, for stacking inside a list. @default "card" */
   variant?: "card" | "list";
+  /** Extra classes on the row container, which owns the radius and divider. */
   className?: string;
 };
 
@@ -37,7 +57,33 @@ const botTile: Record<TaskStatus, string> = {
 const pill =
   "motion-press flex h-7.5 shrink-0 cursor-pointer items-center justify-center gap-1.5 rounded-full px-3 text-label-sm focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-text-brand";
 
-/** Figma `Task row` (Agent tasks 112:939): a flat subtle row, 16px radius, with Running / Review / Failed / Done. */
+/**
+ * Figma `Task row` (Agent tasks 112:939): a flat subtle row, 16px radius, with Running / Review / Failed / Done.
+ *
+ * The status drives the icon, the message color and the one primary action offered: Cancel while
+ * running, Retry when failed, Review when waiting for a person, and Archive once review or done.
+ * Every state change animates in with the shared pop/fade motion.
+ *
+ * @example
+ * ```tsx
+ * import { TaskRow } from "@horon-ai/react";
+ *
+ * function RunningTask() {
+ *   return (
+ *     <TaskRow
+ *       status="running"
+ *       title="Draft the Q4 launch note"
+ *       elapsed="1m 56s"
+ *       bot={{ initial: "H", name: "Horon" }}
+ *       project="Launch"
+ *       message="Writing the second draft"
+ *       detail="2 drafts · 1 calendar change"
+ *       onCancel={() => cancelTask("launch-note")}
+ *     />
+ *   );
+ * }
+ * ```
+ */
 export function TaskRow({
   status,
   title,

package/src/components/textarea-field.tsx

@@ -5,20 +5,29 @@ import { cn } from "../lib/cn";
 import type { ControlSize } from "../lib/size";
 import { fieldBoxClass, fieldTextClass, type InputSurface } from "./input";
 
+/** Field rungs, shared with `ControlSize`: `sm` 88px, `md` 112px and `lg` 136px boxes. */
 export type TextareaFieldSize = ControlSize;
 
+/**
+ * Props of {@link TextareaField}: the native textarea attributes plus a label row, a description
+ * or error footer, an optional counter and the surface.
+ */
 export type TextareaFieldProps = Omit<ComponentProps<"textarea">, "className"> & {
+  /** Field label, one line at the rung's label size. */
   label: ReactNode;
   /** Right side of the label row, such as "Optional". */
   hint?: ReactNode;
+  /** Help text in the footer; replaced by `error` when one is set. */
   description?: ReactNode;
   /** Error message; replaces the description and turns the border and footer red. */
   error?: ReactNode;
   /** Shows a "count / max" counter when set. */
   maxLength?: number;
+  /** Box height, text and footer sizes: 88/112/136px. @default "md" */
   size?: TextareaFieldSize;
-  /** Solid (default) or glass, as on `Input`. */
+  /** Solid (default) or glass, as on `Input`. @default "solid" */
   surface?: InputSurface;
+  /** Extra classes on the field root, which is capped at 360px by default. */
   className?: string;
 };
 
@@ -47,7 +56,32 @@ const boxClass: Record<TextareaFieldSize, string> = {
   lg: "h-34 px-5 py-3.5",
 };
 
-/** Figma `Textarea field` (60:466): label row, glass or solid box, footer with help text and counter. */
+/**
+ * Figma `Textarea field` (60:466): label row, glass or solid box, footer with help text and counter.
+ *
+ * Built on Base UI's field: the label is linked to the textarea, `disabled` dims the whole field
+ * to 60%, and `error` marks the field invalid, swaps the description for the error and paints the
+ * border and footer with the danger color. The counter follows the live length, including a
+ * controlled `value` that changes without an input event.
+ *
+ * @example
+ * ```tsx
+ * import { TextareaField } from "@horon-ai/react";
+ *
+ * function PromptField() {
+ *   return (
+ *     <TextareaField
+ *       label="Instructions"
+ *       hint="Optional"
+ *       description="Tell the bot how to answer."
+ *       maxLength={280}
+ *       size="md"
+ *       placeholder="Be concise and cite sources."
+ *     />
+ *   );
+ * }
+ * ```
+ */
 export function TextareaField({
   label,
   hint,

package/src/components/textarea.tsx

@@ -5,14 +5,20 @@ import { cn } from "../lib/cn";
 import type { ControlSize } from "../lib/size";
 import { fieldBoxClass, fieldTextClass, type InputSurface } from "./input";
 
+/** Textarea rungs, shared with `ControlSize`: `sm` 88px, `md` 112px and `lg` 136px minimum heights. */
 export type TextareaSize = ControlSize;
 
+/** Props of {@link Textarea}: the native textarea attributes plus the rung, invalid state and surface. */
 export type TextareaProps = Omit<ComponentProps<"textarea">, "className"> & {
+  /** Minimum box height, padding and text rung: 88/112/136px. @default "md" */
   size?: TextareaSize;
+  /** Marks the box invalid (`data-invalid`) and the textarea `aria-invalid`, painting the danger border. */
   invalid?: boolean;
-  /** Solid (default) or glass, as on `Input`. */
+  /** Solid (default) or glass, as on `Input`. @default "solid" */
   surface?: InputSurface;
+  /** Extra classes on the box that wraps the textarea. */
   className?: string;
+  /** Classes for the native `<textarea>` itself, such as a fixed height or font. */
   textareaClassName?: string;
 };
 
@@ -22,7 +28,34 @@ const sizeClass: Record<TextareaSize, string> = {
   lg: "min-h-34 px-5 py-3.5",
 };
 
-/** Figma `Textarea` (58:137): an 88/112/136px glass or solid box with 12/14/20px padding, the same field rungs as `Input`. */
+/**
+ * Figma `Textarea` (58:137): an 88/112/136px glass or solid box with 12/14/20px padding, the same field rungs as `Input`.
+ *
+ * A bare field box: no label or footer (use {@link TextareaField} for those). The box draws the
+ * `:focus-within` ring and the invalid border; the textarea itself fills it, starts at three rows
+ * and is not user-resizable, so the rung keeps its height.
+ *
+ * @example
+ * ```tsx
+ * import { useState } from "react";
+ * import { Textarea } from "@horon-ai/react";
+ *
+ * function Notes() {
+ *   const [notes, setNotes] = useState("");
+ *   return (
+ *     <Textarea
+ *       aria-label="Notes"
+ *       size="md"
+ *       surface="solid"
+ *       rows={4}
+ *       placeholder="Add a note"
+ *       value={notes}
+ *       onChange={(event) => setNotes(event.target.value)}
+ *     />
+ *   );
+ * }
+ * ```
+ */
 export function Textarea({
   size = "md",
   invalid,