@horon-ai/react 0.1.0 → 0.1.2

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,

package/src/components/breadcrumb.tsx

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

package/src/components/button.tsx

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

package/src/components/calendar.tsx

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

package/src/components/card.tsx

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

package/src/components/chat-bubble.tsx

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