@horon-ai/react 0.1.0 → 0.1.2

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;

package/src/components/date-field.tsx

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

package/src/components/dialog.tsx

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

package/src/components/directory-card.tsx

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