@horon-ai/react 0.1.1 → 0.1.2

package/src/components/combobox.tsx

@@ -7,9 +7,12 @@ import type { ControlSize } from "../lib/size";
 import { fieldBoxClass, fieldSizeClass, fieldTextClass, type InputSurface } from "./input";
 import { inputGroupSegmentClass, useInputGroup } from "./input-group";
 
+/** Height and text rung, shared with the other controls: `sm` 32px, `md` 40px, `lg` 48px. */
 export type ComboboxSize = ControlSize;
 
+/** One option in the list; the `value` is what the field reports and submits. */
 export type ComboboxItemData = {
+  /** Stable identity, reported by `value` / `onValueChange` and submitted with the form. */
   value: string;
   /** Row text and the text the search matches. */
   label: string;
@@ -19,46 +22,71 @@ export type ComboboxItemData = {
   trailing?: ReactNode;
   /** Extra search terms that are not shown, such as `KR` or `Korea`. */
   keywords?: readonly string[];
+  /** Dims the row to 40% and makes it unselectable. */
   disabled?: boolean;
 };
 
+/** Props shared by both value modes; `multiple` selects the mode in {@link ComboboxProps}. */
 type ComboboxBaseProps = {
+  /** Options in list order, in the shape of {@link ComboboxItemData}. */
   items: readonly ComboboxItemData[];
+  /** Text while nothing is chosen, and the field's `aria-label` in the `field` variant. @default "Search" */
   placeholder?: string;
-  /** Placeholder of the search box inside the popup (`segment` variant). */
+  /** Placeholder of the search box inside the popup (`segment` variant). @default "Search" */
   searchPlaceholder?: string;
-  /** Shown in the popup when nothing matches the search. */
+  /** Shown in the popup when nothing matches the search. @default "No results" */
   emptyLabel?: ReactNode;
+  /** Rung of the field, rows and chips. @default "md" */
   size?: ComboboxSize;
+  /** Surface of the field; the popup follows it. @default "solid" */
   surface?: InputSurface;
   /**
    * `field` is a searchable field (the default). `segment` is the tinted prefix or suffix of an
    * `InputGroup`: a button that opens a popup with the search box on top, taking the group's size.
+   * @default "field"
    */
   variant?: "field" | "segment";
+  /** Turns the field or chips border danger red and sets `aria-invalid`; a `segment` trigger gets neither, because the wrapping `InputGroup` owns that border. */
   invalid?: boolean;
+  /** Blocks the field; in a `segment` it also inherits `disabled` from the wrapping `InputGroup`. */
   disabled?: boolean;
   /** Form field name; the submitted value is the item `value`. */
   name?: string;
+  /** Extra classes on the field or trigger, merged after the surface and size classes. */
   className?: string;
+  /** Accessible name of the text field or segment trigger; the placeholder covers it in the `field` variant. */
   "aria-label"?: string;
 };
 
+/** Single-select combobox: `value` / `onValueChange` carry one item `value` or `null`. */
 export type ComboboxSingleProps = ComboboxBaseProps & {
+  /** Single-select mode; the default when the prop is omitted. */
   multiple?: false;
+  /** Controlled choice, as an item `value`; `null` means nothing is chosen. */
   value?: string | null;
+  /** Starting choice of the uncontrolled field. */
   defaultValue?: string | null;
+  /** Fires with the picked item `value`, or `null` when the field is cleared. */
   onValueChange?: (value: string | null) => void;
 };
 
+/** Multi-select combobox: the chosen items show as removable chips and the value is an array of item `value`s. */
 export type ComboboxMultipleProps = ComboboxBaseProps & {
   /** Chosen items show as removable chips in the field. */
   multiple: true;
+  /** Controlled selection, in the order chosen. */
   value?: readonly string[];
+  /** Starting selection of the uncontrolled field. */
   defaultValue?: readonly string[];
+  /** Fires with the full next selection as item `value`s, in the order chosen. */
   onValueChange?: (value: string[]) => void;
 };
 
+/**
+ * Props for {@link Combobox}, a discriminated union on `multiple`: without it the field is single-select
+ * and its value is `string | null`; with `multiple: true` it is multi-select and its value is `readonly string[]`.
+ * Narrow on `props.multiple` before reading `value` or `onValueChange`.
+ */
 export type ComboboxProps = ComboboxSingleProps | ComboboxMultipleProps;
 
 const itemClass: Record<ComboboxSize, string> = {
@@ -96,6 +124,28 @@ const shortLabel = (item: ComboboxItemData) => item.selectedLabel ?? item.label;
  * `multiple`, several items shown as chips. The popup matches `Select`: the veil, rows with
  * a check. `variant="segment"` puts it in an `InputGroup`, such as a country code before a
  * phone number.
+ *
+ * Filtering is a case-insensitive substring match over each item's `label`, `value` and `keywords`,
+ * with the query trimmed first; a blank query keeps every item. The chosen item's `selectedLabel`
+ * (falling back to `label`) is what the field shows, while the form and `onValueChange` carry `value`.
+ * The popup portals to the body, opens 4px below the field and is at least as wide as it; the list scrolls
+ * past 256px and the panel caps at 320px. In `segment` form the popup is a 256px column with its own search
+ * box on top; on `multiple` the field grows and wraps as chips fill it instead of fixing its height.
+ *
+ * @example
+ * ```tsx
+ * const [country, setCountry] = useState<string | null>("+82");
+ *
+ * <Combobox
+ *   aria-label="Country code"
+ *   value={country}
+ *   onValueChange={setCountry}
+ *   items={[
+ *     { value: "+82", label: "+82 South Korea", keywords: ["KR", "Korea"] },
+ *     { value: "+1", label: "+1 United States", keywords: ["US"] },
+ *   ]}
+ * />
+ * ```
  */
 export function Combobox(props: ComboboxProps) {
   const {

package/src/components/command-palette.tsx

@@ -11,9 +11,13 @@ import { Kbd } from "./kbd";
 const touchCloseClass =
   "flex size-7 shrink-0 motion-press cursor-pointer items-center justify-center rounded-full text-text-secondary hover:bg-overlay-ink-6 hover:text-text-primary focus-visible:outline-2 focus-visible:outline-text-brand [&_svg]:size-4";
 
+/** One selectable row of the palette. */
 export type CommandItem = {
+  /** Stable identity and the React key of the row; keep it unique across the palette. */
   value: string;
+  /** Row text; the query also matches it, together with `keywords`. */
   label: string;
+  /** Extra search terms that are not shown, such as an abbreviation or a path. */
   keywords?: string;
   /** 28px leading tile: an initial or a 16px icon. */
   tile?: ReactNode;
@@ -23,31 +27,76 @@ export type CommandItem = {
   meta?: ReactNode;
   /** Right-side hint, usually `<Kbd>`; hidden when the device shows no keyboard hints. */
   hint?: ReactNode;
+  /** Runs when the row is clicked, before the palette closes itself. */
   onSelect?: () => void;
 };
 
-export type CommandGroup = { label: string; items: CommandItem[] };
+/** A titled block of rows; groups are rendered in the order given. */
+export type CommandGroup = {
+  /** Section heading, `caption` secondary text above the rows. */
+  label: string;
+  /** Rows of this section. */
+  items: CommandItem[];
+};
 
+/** Props for {@link CommandPalette}: the dialog state, the grouped rows and the footer hints. */
 export type CommandPaletteProps = {
+  /** Controlled open state; leave it out to let the palette open from its `trigger`. */
   open?: boolean;
+  /** Called with the next open state when the palette opens, closes on Escape, closes on select or its backdrop is pressed. */
   onOpenChange?: (open: boolean) => void;
+  /** Sections of rows, in render order. */
   groups: CommandGroup[];
+  /** Search field placeholder; it also names the dialog (`aria-label`). @default "Search" */
   placeholder?: string;
   /** Shown when the query has no matches; defaults to "No results". */
   empty?: ReactNode;
   /** Footer key hints, such as `[["↑↓", "Move"], ["↵", "Open"]]`; hidden when the device shows no keyboard hints. */
   hints?: [ReactNode, string][];
+  /** Element rendered inside the dialog root as the opener, usually a `DialogTrigger`. */
   trigger?: ReactNode;
   /**
    * `solid` (default) is an opaque palette with a default border. `glass` puts it on the veil (`veil-overlay`).
+   * @default "solid"
    */
   surface?: "solid" | "glass";
+  /** Extra classes on the popup, merged after the surface, radius and motion classes. */
   className?: string;
 };
 
 /**
  * Figma `Command palette` (110:676): a 560px palette, 24px radius, with a 48px search row,
  * grouped 44px results and a key-hint footer.
+ *
+ * A Base UI dialog on a 32% scrim with a 6px blur, anchored to the top of the viewport 96px down rather
+ * than centred. It always renders {@link CommandPaletteBody} with its own close control — an `esc` chip on
+ * devices that show keyboard hints, a 28px `X` tile on touch — and every row select reports
+ * `onOpenChange(false)`. Row hints and the footer hints disappear on those touch devices too. The body
+ * owns filtering and keyboard movement.
+ *
+ * @example
+ * ```tsx
+ * const [open, setOpen] = useState(false);
+ *
+ * <CommandPalette
+ *   open={open}
+ *   onOpenChange={setOpen}
+ *   trigger={<DialogTrigger render={<Button variant="solid" />}>Search</DialogTrigger>}
+ *   groups={[
+ *     {
+ *       label: "Bots",
+ *       items: [
+ *         { value: "weekly", label: "Weekly digest", meta: "Product", hint: <Kbd>↵</Kbd> },
+ *         { value: "inbox", label: "Inbox triage", meta: "Ops" },
+ *       ],
+ *     },
+ *   ]}
+ *   hints={[
+ *     ["↑↓", "Move"],
+ *     ["↵", "Open"],
+ *   ]}
+ * />
+ * ```
  */
 export function CommandPalette({
   open,
@@ -108,17 +157,32 @@ export function CommandPalette({
   );
 }
 
+/** Props for {@link CommandPaletteBody}: the rows plus the close control and the select callback the host owns. */
 export type CommandPaletteBodyProps = {
+  /** Sections of rows, in render order. */
   groups: CommandGroup[];
+  /** Search field placeholder. @default "Search" */
   placeholder?: string;
+  /** Shown when the query has no matches. @default "No results" */
   empty?: ReactNode;
+  /** Accessible name of the fallback `esc` button, used when no `closeControl` is passed. @default "Close" */
   closeLabel?: string;
   /** A ready close control; the dialog passes its own `Dialog.Close` so uncontrolled palettes still close. */
   closeControl?: ReactNode;
+  /** Makes the fallback `esc` button close the palette; without both this and `closeControl` no button renders. */
   onClose?: () => void;
+  /** Called after a row's own `onSelect`, so the host can close its dialog. */
   onSelect?: () => void;
 };
 
+/**
+ * The search row, groups and result rows of a command palette.
+ *
+ * Part of {@link CommandPalette}. Renders a Base UI `Autocomplete` that is always open and inline: the
+ * query filters on label plus keywords (case-insensitive), the first row is highlighted as soon as the
+ * list renders, and arrow keys move through the rows while Enter picks the highlighted one. Escape is left
+ * to the host's close control, which is why this part owns no dialog state.
+ */
 export function CommandPaletteBody({
   groups,
   placeholder = "Search",

package/src/components/composer.tsx

@@ -5,21 +5,34 @@ import { cn } from "../lib/cn";
 import type { ControlSize } from "../lib/size";
 import { IconButton } from "./icon-button";
 
+/** Height and text rung of the composer: `sm` 32px, `md` 40px, `lg` 48px, shared with the other controls. */
 export type ComposerSize = ControlSize;
+/** `solid` is the opaque bordered pill; `glass` is the veil field for imagery and glass panels. */
 export type ComposerSurface = "solid" | "glass";
 
+/** Props for {@link Composer}: the message value, the send callback and the two side actions. */
 export type ComposerProps = {
+  /** Rung of the field and its icon buttons. @default "md" */
   size?: ComposerSize;
-  /** `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?: ComposerSurface;
+  /** Field placeholder; it doubles as the `aria-label` because the field has no visible label. @default "Message" */
   placeholder?: string;
+  /** Controlled text. Leave it out to let the composer own the value and still report changes. */
   value?: string;
+  /** Starting text of the uncontrolled composer. @default "" */
   defaultValue?: string;
+  /** Fires on every keystroke with the next full text, controlled or not. */
   onValueChange?: (value: string) => void;
+  /** Fires with the full (untrimmed) text when the form submits, from Enter or the send button; whitespace-only text blocks the submit. The field is cleared after. */
   onSubmit?: (value: string) => void;
+  /** Fires when the plus button is pressed; the composer itself opens nothing. */
   onAttach?: () => void;
+  /** Fires when the microphone button is pressed, i.e. while the field is empty. */
   onVoice?: () => void;
+  /** Disables the field and both icon buttons without changing the layout. */
   disabled?: boolean;
+  /** Extra classes on the form, merged after the surface and size classes. */
   className?: string;
 };
 
@@ -39,6 +52,20 @@ const textClass: Record<ComposerSize, string> = {
  * Figma `Composer` (63:462): a regular-glass pill with an attach button, the
  * message field, and a voice button that turns into the ink send button once
  * there is text.
+ *
+ * A real `form`, so Enter submits and the browser handles implicit submission; a value that is only
+ * whitespace blocks the send and leaves the typed text in place. The last slot swaps between the voice
+ * button (empty field) and the primary send button (`motion-swap`), and only the visible one is focusable.
+ *
+ * @example
+ * ```tsx
+ * <Composer
+ *   placeholder="Ask anything"
+ *   onAttach={() => openFilePicker()}
+ *   onVoice={() => startDictation()}
+ *   onSubmit={(text) => sendMessage(text)}
+ * />
+ * ```
  */
 export function Composer({
   size = "md",

package/src/components/data-table.tsx

@@ -26,19 +26,51 @@ import { Checkbox } from "./checkbox";
 import { IconButton } from "./icon-button";
 import { Input } from "./input";
 
-type WithClass<T> = Omit<T, "className"> & { className?: string };
+/** Strips an element's own `className` so a wrapper can merge its classes with the caller's. */
+type WithClass<T> = Omit<T, "className"> & {
+  /** Extra classes merged last onto the element, after the component's own classes. */
+  className?: string;
+};
 
+/** Viewport the table is designed for: `desktop` and `tablet` keep 24px card gutters, `mobile` narrows them to 18px. */
 export type DataTableDevice = "desktop" | "tablet" | "mobile";
 
 /**
  * Figma `Data table`: a solid surface card, 20px radius, 1px default border.
  * `device` sets the gutters: 24px on desktop and tablet, 18px on mobile (where the table scrolls sideways).
+ *
+ * The card is the context every part reads: it publishes `data-device`, which the header, cells and footer
+ * use to switch their padding, and `group/dt`, so the parts can be laid out in any order inside it.
+ *
+ * @example
+ * ```tsx
+ * function BotsTable({ bots }: { bots: { id: string; name: string; owner: string }[] }) {
+ *   const table = useDataTable({
+ *     data: bots,
+ *     columns: [
+ *       { accessorKey: "name", header: "Name" },
+ *       { accessorKey: "owner", header: "Owner" },
+ *     ],
+ *     pageSize: 10,
+ *   });
+ *
+ *   return (
+ *     <DataTable>
+ *       <DataTableView table={table} />
+ *       <DataTablePagination table={table} />
+ *     </DataTable>
+ *   );
+ * }
+ * ```
  */
 export function DataTable({
   device = "desktop",
   className,
   ...props
-}: WithClass<ComponentProps<"div">> & { device?: DataTableDevice }) {
+}: WithClass<ComponentProps<"div">> & {
+  /** Viewport the table is designed for. @default "desktop" */
+  device?: DataTableDevice;
+}) {
   return (
     <div
       data-device={device}
@@ -51,15 +83,24 @@ export function DataTable({
   );
 }
 
+/** Props for {@link DataTableHeader}: an optional leading icon, the heading and trailing actions. */
 export type DataTableHeaderProps = {
   /** 16px icon on the 26px brand tile. */
   icon?: ReactNode;
+  /** Card heading, `label-lg` primary text on one truncated line. */
   title: ReactNode;
   /** Trailing 16px icon buttons. */
   actions?: ReactNode;
+  /** Extra classes on the header row, merged after the padding classes. */
   className?: string;
 };
 
+/**
+ * The card's top row: leading icon tile, title and trailing actions, 24px gutters (18px on mobile).
+ *
+ * Part of {@link DataTable}. The actions column is `text-secondary` with 16px icons and pulls 6px into the
+ * header's vertical padding, so an icon button keeps its own footprint without inflating the row.
+ */
 export function DataTableHeader({ icon, title, actions, className }: DataTableHeaderProps) {
   return (
     <div className={cn("flex items-center gap-3 px-6 py-4.5 group-data-[device=mobile]/dt:px-4.5", className)}>
@@ -76,6 +117,12 @@ export function DataTableHeader({ icon, title, actions, className }: DataTableHe
   );
 }
 
+/**
+ * The scroll container and the `<table>` inside it, with collapsed borders.
+ *
+ * Part of {@link DataTable}. On `device="mobile"` the table switches to its min-content width so the
+ * wrapper scrolls sideways instead of squeezing columns; above that it fills the card.
+ */
 export function DataTableTable({ className, ...props }: WithClass<ComponentProps<"table">>) {
   return (
     <div className="w-full max-w-full min-w-0 overflow-x-auto">
@@ -87,13 +134,21 @@ export function DataTableTable({ className, ...props }: WithClass<ComponentProps
   );
 }
 
-/** Header cell: 52px, 14px icon and label-md secondary text. */
+/**
+ * Header cell: 52px, 14px icon and label-md secondary text.
+ *
+ * Part of {@link DataTable}. It draws the top and bottom hairlines and 24px outer gutters (18px on mobile);
+ * `DataTableView` passes `aria-sort` here for a sortable column, which is why it stays a plain `<th>`.
+ */
 export function DataTableHead({
   icon,
   className,
   children,
   ...props
-}: WithClass<ComponentProps<"th">> & { icon?: ReactNode }) {
+}: WithClass<ComponentProps<"th">> & {
+  /** 14px icon before the label, rendered inside the cell's inline label row. */
+  icon?: ReactNode;
+}) {
   return (
     <th
       className={cn(
@@ -110,11 +165,17 @@ export function DataTableHead({
   );
 }
 
+/** Body row: one bottom hairline; `DataTableView` adds the hover, selected and staggered rise classes. */
 export function DataTableRow({ className, ...props }: WithClass<ComponentProps<"tr">>) {
   return <tr className={cn("border-b border-border-default", className)} {...props} />;
 }
 
-/** Body cell: 52px; body-sm secondary text unless the content sets its own. */
+/**
+ * Body cell: 52px; body-sm secondary text unless the content sets its own.
+ *
+ * Part of {@link DataTable}. It keeps text on one line, uses the same 24/18px outer gutters as the head,
+ * and turns a direct `<label>` into a flex box so a checkbox and its text line up in the cell.
+ */
 export function DataTableCell({ className, ...props }: WithClass<ComponentProps<"td">>) {
   return (
     <td
@@ -127,8 +188,19 @@ export function DataTableCell({ className, ...props }: WithClass<ComponentProps<
   );
 }
 
-/** The 24px ink logo tile with a label-sm initial, beside a label-lg name. */
-export function DataTableItem({ logo, children }: { logo: ReactNode; children: ReactNode }) {
+/**
+ * The 24px ink logo tile with a label-sm initial, beside a label-lg name. Part of {@link DataTable}.
+ *
+ * prettier-ignore keeps the parameter pattern identical to the original instead of letting the formatter
+ * expand the destructured parameter onto separate lines.
+ */
+// prettier-ignore
+export function DataTableItem({ logo, children }: {
+  /** Tile content: a letter, or an icon the caller sizes (the tile is 24px square). */
+  logo: ReactNode;
+  /** The row's name, `label-lg` primary text truncated to the cell. */
+  children: ReactNode;
+}) {
   return (
     <span className="flex items-center gap-2.5">
       <span className="flex size-6 shrink-0 items-center justify-center rounded-xs bg-surface-ink text-label-sm text-text-on-ink">
@@ -139,12 +211,18 @@ export function DataTableItem({ logo, children }: { logo: ReactNode; children: R
   );
 }
 
-/** Figma `Table tag`: brand (sky tint) or neutral (subtle) label, 8px radius. */
+/**
+ * Figma `Table tag`: brand (sky tint) or neutral (subtle) label, 8px radius.
+ * Part of {@link DataTable}; it renders a non-interactive `span` so it fits inside a cell's text flow.
+ */
 export function DataTableTag({
   tone = "brand",
   className,
   ...props
-}: WithClass<ComponentProps<"span">> & { tone?: "brand" | "neutral" }) {
+}: WithClass<ComponentProps<"span">> & {
+  /** `brand` is the sky tint with brand text; `neutral` is the subtle fill with secondary text. @default "brand" */
+  tone?: "brand" | "neutral";
+}) {
   return (
     <span
       className={cn(
@@ -157,9 +235,22 @@ export function DataTableTag({
   );
 }
 
-export type DataTableFooterProps = { onAdd?: () => void; addLabel?: string; hint?: ReactNode; className?: string };
+/** Props for {@link DataTableFooter}: the add-row action and an optional caption hint. */
+export type DataTableFooterProps = {
+  /** Fires when the add-row row is pressed; the footer itself adds nothing. */
+  onAdd?: () => void;
+  /** Text of the add action, `label-md` secondary. @default "Add row" */
+  addLabel?: string;
+  /** Caption at the right edge, such as a total or a keyboard hint. */
+  hint?: ReactNode;
+  /** Extra classes on the footer row, merged after the padding classes. */
+  className?: string;
+};
 
-/** Footer: "Add row" with a 16px plus and a caption hint on the right. */
+/**
+ * Footer: "Add row" with a 16px plus and a caption hint on the right.
+ * Part of {@link DataTable}. The add action takes the free width, so the hint stays pinned right; both wrap onto a second line when narrow.
+ */
 export function DataTableFooter({ onAdd, addLabel = "Add row", hint, className }: DataTableFooterProps) {
   return (
     <div
@@ -181,13 +272,17 @@ export function DataTableFooter({ onAdd, addLabel = "Add row", hint, className }
   );
 }
 
+/** The `meta` a horon column can carry; `DataTableView` reads it for the head icon and the two class hooks. */
 export type DataTableColumnMeta = {
   /** 14px icon before the header label. */
   icon?: ReactNode;
+  /** Extra classes on this column's header cell, such as a width. */
   headClassName?: string;
+  /** Extra classes on each body cell of this column. */
   cellClassName?: string;
 };
 
+/** Empty meta object that gives `columnMeta` its type, so `meta` in a column def is checked against the shape above. */
 const columnMeta: DataTableColumnMeta = {};
 
 /** TanStack Table features every horon data table registers: sorting, filtering, selection, pagination. */
@@ -205,20 +300,54 @@ export const dataTableFeatures = tableFeatures({
   columnMeta,
 });
 
+/** The feature set `dataTableFeatures` builds; the type every column and table instance is parameterised by. */
 export type DataTableFeatures = typeof dataTableFeatures;
+
+/**
+ * A column definition bound to the horon feature set and to the row type.
+ * @typeParam TData - Shape of one row; derive it from the data array so `accessorKey` stays checked.
+ */
 export type DataTableColumn<TData extends RowData> = ColumnDef<DataTableFeatures, TData>;
+
+/**
+ * The table instance `useDataTable` returns; pass it to {@link DataTableView}, {@link DataTableSearch} and {@link DataTablePagination}.
+ * @typeParam TData - Shape of one row, the same one the columns were built from.
+ */
 export type DataTableInstance<TData extends RowData> = ReactTable<DataTableFeatures, TData>;
 
+/**
+ * Options for {@link useDataTable}.
+ * @typeParam TData - Shape of one row.
+ */
 export type UseDataTableOptions<TData extends RowData> = {
+  /** Rows to display; the table never mutates them. */
   data: TData[];
+  /** Column definitions, in display order; see {@link DataTableColumn}. */
   columns: DataTableColumn<TData>[];
+  /** Derives a stable row id from the row and its index; the default id is the row index. */
   getRowId?: (row: TData, index: number) => string;
   /** Rows per page. Omit it to show every row on one page. */
   pageSize?: number;
+  /** Makes every row selectable, which is what the checkbox column from {@link dataTableSelectColumn} toggles. @default false */
   enableRowSelection?: boolean;
 };
 
-/** Builds the TanStack table behind `DataTableView`, `DataTableSearch` and `DataTablePagination`. */
+/**
+ * Builds the TanStack table behind `DataTableView`, `DataTableSearch` and `DataTablePagination`.
+ *
+ * Registers {@link dataTableFeatures} and starts on page 1 with the given `pageSize` (10 by default in
+ * state). Without `pageSize` it turns on manual pagination, so the paginated row model is skipped and every
+ * row renders.
+ *
+ * @typeParam TData - Shape of one row.
+ * @param options - The table options; see {@link UseDataTableOptions}.
+ * @param options.data - Rows to display.
+ * @param options.columns - Column definitions, in display order.
+ * @param options.getRowId - Derives a stable row id; the row index is used when omitted.
+ * @param options.pageSize - Rows per page; omit it to show every row on one page.
+ * @param options.enableRowSelection - Makes rows selectable for the checkbox column.
+ * @returns A table instance to pass to the table parts.
+ */
 export function useDataTable<TData extends RowData>({
   data,
   columns,
@@ -237,7 +366,16 @@ export function useDataTable<TData extends RowData>({
   });
 }
 
-/** Leading checkbox column; the header box selects every row on the current page. */
+/**
+ * Leading checkbox column; the header box selects every row on the current page.
+ *
+ * Part of the {@link DataTable} set. The header box reports indeterminate when only some page rows are
+ * selected, each cell box is labelled "Select row <n>" and is disabled when the table does not allow
+ * selecting that row, and the column is pinned 48px wide and unsortable.
+ *
+ * @typeParam TData - Shape of one row.
+ * @returns A column definition to put first in the `columns` array; it reads the table's own selection state.
+ */
 export function dataTableSelectColumn<TData extends RowData>(): DataTableColumn<TData> {
   return {
     id: "select",
@@ -269,13 +407,29 @@ export function dataTableSelectColumn<TData extends RowData>(): DataTableColumn<
 
 const ariaSort = { asc: "ascending", desc: "descending" } as const;
 
+/**
+ * Props for {@link DataTableView}.
+ * @typeParam TData - Shape of one row.
+ */
 export type DataTableViewProps<TData extends RowData> = {
+  /** Instance from {@link useDataTable}. */
   table: DataTableInstance<TData>;
+  /** Cell shown when the filtered rows are empty. @default "No results." */
   emptyMessage?: ReactNode;
+  /** Extra classes on the `<table>`. */
   className?: string;
 };
 
-/** Renders a `useDataTable` instance with the Figma head and body cells; sortable heads toggle on click. */
+/**
+ * Renders a `useDataTable` instance with the Figma head and body cells; sortable heads toggle on click.
+ *
+ * A sortable head is a button with a three-state caret (none, ascending, descending) and sets `aria-sort` on
+ * the `<th>`; a non-sortable head shows the column's `meta.icon` instead. Rows rise in 30ms apart, hover with
+ * a 4% ink wash, and a selected row keeps the wash on its cells. A sort or page change remounts the
+ * body so the stagger replays. An empty row model renders one full-width cell with `emptyMessage`.
+ *
+ * @typeParam TData - Shape of one row, matching the instance.
+ */
 export function DataTableView<TData extends RowData>({
   table,
   emptyMessage = "No results.",
@@ -358,13 +512,27 @@ export function DataTableView<TData extends RowData>({
   );
 }
 
+/**
+ * Props for {@link DataTableSearch}.
+ * @typeParam TData - Shape of one row.
+ */
 export type DataTableSearchProps<TData extends RowData> = {
+  /** Instance from {@link useDataTable}. */
   table: DataTableInstance<TData>;
+  /** Field placeholder; it is also the `aria-label`. @default "Search" */
   placeholder?: string;
+  /** Extra classes on the input, merged after `min-w-0`. */
   className?: string;
 };
 
-/** Solid search field bound to the table's global filter. */
+/**
+ * Solid search field bound to the table's global filter.
+ * Part of the {@link DataTable} set: it is a small `Input` with a magnifier, writes every keystroke into the
+ * table's global filter and reads the current value back from the table state, so it stays in sync when
+ * something else clears the filter.
+ *
+ * @typeParam TData - Shape of one row.
+ */
 export function DataTableSearch<TData extends RowData>({
   table,
   placeholder = "Search",
@@ -384,12 +552,26 @@ export function DataTableSearch<TData extends RowData>({
   );
 }
 
+/**
+ * Props for {@link DataTablePagination}.
+ * @typeParam TData - Shape of one row.
+ */
 export type DataTablePaginationProps<TData extends RowData> = {
+  /** Instance from {@link useDataTable}. */
   table: DataTableInstance<TData>;
+  /** Extra classes on the row, merged after the padding classes. */
   className?: string;
 };
 
-/** Row count (or selection count) with previous and next page buttons. */
+/**
+ * Row count (or selection count) with previous and next page buttons.
+ *
+ * Part of the {@link DataTable} set. With a selection it reads "n of m selected", otherwise "n rows"
+ * (singular for one); the page label always shows at least one page, and each arrow is disabled at its end
+ * of the range. The count follows the filtered rows, not the raw data.
+ *
+ * @typeParam TData - Shape of one row.
+ */
 export function DataTablePagination<TData extends RowData>({ table, className }: DataTablePaginationProps<TData>) {
   const total = table.getFilteredRowModel().rows.length;
   const selected = table.getFilteredSelectedRowModel().rows.length;