@ngrok/mantle 0.70.1 → 0.71.0

package/dist/data-table.d.ts

@@ -1,6 +1,6 @@
-import { t as Button } from "./button-DDK6nEac.js";
-import { s as SortingMode } from "./direction-Jk7BkzGo.js";
-import { t as Table$1 } from "./table-4q1UxE7L.js";
+import { t as Button } from "./button-Bq0x5Pv4.js";
+import { s as SortingMode } from "./direction-DtBAQn7p.js";
+import { t as Table$1 } from "./table-BsNJBKiq.js";
 import * as _$react from "react";
 import { ComponentProps, ReactNode } from "react";
 import * as _$react_jsx_runtime0 from "react/jsx-runtime";
@@ -16,19 +16,51 @@ type DataTableProps<TData> = ComponentProps<typeof Table$1.Root> & {
   table: Table<TData>;
 };
 /**
- * A data table component that provides sorting and other data table functionality.
- * Built on top of TanStack Table for advanced table features.
+ * The root container for a data table. Wraps all other `DataTable`
+ * sub-components and provides the table context to its descendants.
+ *
+ * REQUIRED: Construct a TanStack Table instance via `useReactTable` (from
+ * `@tanstack/react-table`, also re-exported from `@ngrok/mantle/data-table`)
+ * and pass it through the `table` prop. The instance owns columns, data, and
+ * any sorting / filtering / pagination state — the wrapper components read
+ * from it.
  *
  * @see https://mantle.ngrok.com/components/data-table#datatableroot
  *
  * @example
  * ```tsx
- * <DataTable table={table}>
- *   <DataTable.Head />
- *   <DataTable.Body>
- *     <DataTable.Rows />
- *   </DataTable.Body>
- * </DataTable>
+ * import {
+ *   DataTable,
+ *   createColumnHelper,
+ *   getCoreRowModel,
+ *   useReactTable,
+ * } from "@ngrok/mantle/data-table";
+ *
+ * type Row = { id: string; name: string };
+ * const columnHelper = createColumnHelper<Row>();
+ * const columns = [
+ *   columnHelper.accessor("name", {
+ *     id: "name",
+ *     header: () => <DataTable.Header>Name</DataTable.Header>,
+ *     cell: (props) => <DataTable.Cell>{props.getValue()}</DataTable.Cell>,
+ *   }),
+ * ];
+ *
+ * function MyTable({ data }: { data: Row[] }) {
+ *   const table = useReactTable({ data, columns, getCoreRowModel: getCoreRowModel() });
+ *   const rows = table.getRowModel().rows;
+ *
+ *   return (
+ *     <DataTable.Root table={table}>
+ *       <DataTable.Head />
+ *       <DataTable.Body>
+ *         {rows.length > 0
+ *           ? rows.map((row) => <DataTable.Row key={row.id} row={row} />)
+ *           : <DataTable.EmptyRow>No results.</DataTable.EmptyRow>}
+ *       </DataTable.Body>
+ *     </DataTable.Root>
+ *   );
+ * }
  * ```
  */
 declare function Root<TData>({
@@ -68,25 +100,33 @@ type DataTableHeaderSortButtonProps<TData, TValue> = Omit<ComponentProps<typeof
   sortingMode: SortingMode;
 });
 /**
- * A sortable button toggle for a column header in a data table.
- * If the column is sortable, clicking the button will toggle the sorting
- * direction.
+ * A sortable button toggle for a column header in a data table. Renders a sort
+ * icon that reflects the current direction, handles ARIA announcements, and
+ * cycles through sort states on click.
+ *
+ * Each click cycles through:
+ * - For `"alphanumeric"` sorting: `unsorted → ascending → descending → unsorted`
+ * - For `"time"` sorting: `unsorted → newest-first → oldest-first → unsorted`
+ *
+ * For right-aligned numeric columns, pass `className="justify-end"` and
+ * `iconPlacement="start"` so the sort icon stays paired with the label.
  *
  * @see https://mantle.ngrok.com/components/data-table#datatableheadersortbutton
  *
  * @example
  * ```tsx
- * <DataTable.HeaderSortButton
- *   column={column}
- *   sortingMode="alphanumeric"
- * >
- *   Column Title
- * </DataTable.HeaderSortButton>
+ * columnHelper.accessor("email", {
+ *   id: "email",
+ *   header: (props) => (
+ *     <DataTable.Header>
+ *       <DataTable.HeaderSortButton column={props.column} sortingMode="alphanumeric">
+ *         Email
+ *       </DataTable.HeaderSortButton>
+ *     </DataTable.Header>
+ *   ),
+ *   cell: (props) => <DataTable.Cell>{props.getValue()}</DataTable.Cell>,
+ * });
  * ```
- *
- * Each click cycles through:
- * - For alphanumeric sorting: unsorted ➡️ ascending ➡️ descending ➡️ unsorted
- * - For time sorting: unsorted ➡️ newest-to-oldest ➡️ oldest-to-newest ➡️ unsorted
  */
 declare function HeaderSortButton<TData, TValue>({
   children,
@@ -104,18 +144,25 @@ declare namespace HeaderSortButton {
 }
 type DataTableHeaderProps = ComponentProps<typeof Table$1.Header>;
 /**
- * A header for a data table.
- * This is typically used to wrap the `DataTable.HeaderSortButton` component.
+ * A `<th>` optimized for header actions. Wrap each column's header content in
+ * this; for sortable columns, nest a `DataTable.HeaderSortButton` inside.
+ * Non-sortable columns can render plain text.
  *
  * @see https://mantle.ngrok.com/components/data-table#datatableheader
  *
  * @example
  * ```tsx
- * <DataTable.Header>
- *   <DataTable.HeaderSortButton column={column} sortingMode="alphanumeric">
- *     Column Title
- *   </DataTable.HeaderSortButton>
- * </DataTable.Header>
+ * columnHelper.accessor("name", {
+ *   id: "name",
+ *   header: (props) => (
+ *     <DataTable.Header>
+ *       <DataTable.HeaderSortButton column={props.column} sortingMode="alphanumeric">
+ *         Name
+ *       </DataTable.HeaderSortButton>
+ *     </DataTable.Header>
+ *   ),
+ *   cell: (props) => <DataTable.Cell>{props.getValue()}</DataTable.Cell>,
+ * });
  * ```
  */
 declare function Header({
@@ -127,6 +174,28 @@ declare namespace Header {
   var displayName: string;
 }
 type DataTableHeadProps = Omit<ComponentProps<typeof Table$1.Head>, "children">;
+/**
+ * The `<thead>` container that renders column headers automatically from
+ * `table.getHeaderGroups()`. Does not accept children — headers come from each
+ * column's `header` definition on the TanStack Table column config.
+ *
+ * @see https://mantle.ngrok.com/components/data-table#datatablehead
+ *
+ * @example
+ * ```tsx
+ * const table = useReactTable({ data, columns, getCoreRowModel: getCoreRowModel() });
+ * const rows = table.getRowModel().rows;
+ *
+ * <DataTable.Root table={table}>
+ *   <DataTable.Head />
+ *   <DataTable.Body>
+ *     {rows.length > 0
+ *       ? rows.map((row) => <DataTable.Row key={row.id} row={row} />)
+ *       : <DataTable.EmptyRow>No results.</DataTable.EmptyRow>}
+ *   </DataTable.Body>
+ * </DataTable.Root>
+ * ```
+ */
 declare function Head<TData>(props: DataTableHeadProps): _$react_jsx_runtime0.JSX.Element;
 declare namespace Head {
   var displayName: string;
@@ -134,7 +203,32 @@ declare namespace Head {
 type DataTableRowProps<TData> = Omit<ComponentProps<typeof Table$1.Row>, "children"> & {
   row: Row<TData>;
 };
+/**
+ * A single data table body row rendered from a TanStack Table row instance.
+ * Does not accept children — cells come from each column's `cell` definition.
+ *
+ * When `onClick` is provided, the row automatically receives `cursor-pointer`.
+ * Pass a different `cursor-*` class via `className` (e.g. `cursor-default`,
+ * `cursor-wait`) to override. For keyboard and screen-reader access, also
+ * render a `<Link>` inside the primary cell — a `<tr>` is not focusable.
+ *
+ * @see https://mantle.ngrok.com/components/data-table#datatablerow
+ *
+ * @example
+ * ```tsx
+ * const navigate = useNavigate();
+ *
+ * {rows.map((row) => (
+ *   <DataTable.Row
+ *     key={row.id}
+ *     row={row}
+ *     onClick={() => navigate(href("/payments/:id", { id: row.original.id }))}
+ *   />
+ * ))}
+ * ```
+ */
 declare function Row$1<TData>({
+  className,
   row,
   ...props
 }: DataTableRowProps<TData>): _$react_jsx_runtime0.JSX.Element;
@@ -142,6 +236,29 @@ declare namespace Row$1 {
   var displayName: string;
 }
 type DataTableEmptyRowProps = ComponentProps<typeof Table$1.Row>;
+/**
+ * An empty-state row that spans every column. Render this as the `else` branch
+ * when `rows.length === 0` to keep the table's frame intact instead of
+ * collapsing to an empty `<tbody>`. The cell `colSpan` is computed from the
+ * TanStack Table instance via context, so no manual column count is needed.
+ *
+ * @see https://mantle.ngrok.com/components/data-table#datatableemptyrow
+ *
+ * @example
+ * ```tsx
+ * const table = useReactTable({ data, columns, getCoreRowModel: getCoreRowModel() });
+ * const rows = table.getRowModel().rows;
+ *
+ * <DataTable.Root table={table}>
+ *   <DataTable.Head />
+ *   <DataTable.Body>
+ *     {rows.length > 0
+ *       ? rows.map((row) => <DataTable.Row key={row.id} row={row} />)
+ *       : <DataTable.EmptyRow>No results.</DataTable.EmptyRow>}
+ *   </DataTable.Body>
+ * </DataTable.Root>
+ * ```
+ */
 declare function EmptyRow<TData>({
   children,
   ...props
@@ -150,6 +267,29 @@ declare namespace EmptyRow {
   var displayName: string;
 }
 type DataTableActionCellProps = ComponentProps<typeof Table$1.Cell>;
+/**
+ * A sticky-right `<td>` for per-row action buttons (typically an `IconButton`
+ * that opens a `DropdownMenu`). Pair with `DataTable.ActionHeader`.
+ *
+ * If the row has `onClick`, pass `onClick={(event) => event.stopPropagation()}`
+ * on this cell so clicks on action controls don't bubble and fire the row
+ * handler.
+ *
+ * @see https://mantle.ngrok.com/components/data-table#datatableactioncell
+ *
+ * @example
+ * ```tsx
+ * columnHelper.display({
+ *   id: "actions",
+ *   header: () => <DataTable.ActionHeader />,
+ *   cell: () => (
+ *     <DataTable.ActionCell onClick={(event) => event.stopPropagation()}>
+ *       <DropdownMenu.Root>...</DropdownMenu.Root>
+ *     </DataTable.ActionCell>
+ *   ),
+ * });
+ * ```
+ */
 declare function ActionCell({
   children,
   className,
@@ -184,8 +324,17 @@ declare namespace ActionHeader {
   var displayName: string;
 }
 /**
- * A data table component that provides sorting and other data table functionality.
- * Built on top of TanStack Table for advanced table features.
+ * Use `DataTable` for INTERACTIVE tabular data — sorting, filtering, pagination,
+ * row selection, and server-side or client-side data. Built on TanStack Table;
+ * the consumer MUST construct a `useReactTable` instance from
+ * `@tanstack/react-table` and pass it to `DataTable.Root` via the `table` prop.
+ * Every TanStack utility (`createColumnHelper`, `getCoreRowModel`,
+ * `getSortedRowModel`, `getPaginationRowModel`, `getFilteredRowModel`,
+ * `useReactTable`, …) is re-exported from `@ngrok/mantle/data-table` so a single
+ * import covers both the wrapper components and the TanStack helpers.
+ *
+ * For STATIC, layout-driven tables (read-only data dumps, simple key/value
+ * displays, plain markup tables with no interactivity), use `Table` instead.
  *
  * @see https://mantle.ngrok.com/components/data-table
  *
@@ -206,49 +355,304 @@ declare namespace ActionHeader {
  * ```
  *
  * @example
+ * Minimal — read-only table with a single sortable column:
  * ```tsx
- * <DataTable table={table}>
- *   <DataTable.Head />
- *   <DataTable.Body>
- *     <DataTable.Rows />
- *   </DataTable.Body>
- * </DataTable>
+ * import {
+ *   DataTable,
+ *   createColumnHelper,
+ *   getCoreRowModel,
+ *   useReactTable,
+ * } from "@ngrok/mantle/data-table";
+ *
+ * type Row = { id: string; name: string };
+ *
+ * const columnHelper = createColumnHelper<Row>();
+ * const columns = [
+ *   columnHelper.accessor("name", {
+ *     id: "name",
+ *     header: (props) => (
+ *       <DataTable.Header>
+ *         <DataTable.HeaderSortButton column={props.column} sortingMode="alphanumeric">
+ *           Name
+ *         </DataTable.HeaderSortButton>
+ *       </DataTable.Header>
+ *     ),
+ *     cell: (props) => <DataTable.Cell>{props.getValue()}</DataTable.Cell>,
+ *   }),
+ * ];
+ *
+ * function MyTable({ data }: { data: Row[] }) {
+ *   const table = useReactTable({ data, columns, getCoreRowModel: getCoreRowModel() });
+ *   const rows = table.getRowModel().rows;
+ *
+ *   return (
+ *     <DataTable.Root table={table}>
+ *       <DataTable.Head />
+ *       <DataTable.Body>
+ *         {rows.length > 0
+ *           ? rows.map((row) => <DataTable.Row key={row.id} row={row} />)
+ *           : <DataTable.EmptyRow>No results.</DataTable.EmptyRow>}
+ *       </DataTable.Body>
+ *     </DataTable.Root>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * Sortable + filterable + paginated — with a global text filter and page controls:
+ * ```tsx
+ * import {
+ *   DataTable,
+ *   createColumnHelper,
+ *   getCoreRowModel,
+ *   getFilteredRowModel,
+ *   getPaginationRowModel,
+ *   getSortedRowModel,
+ *   useReactTable,
+ * } from "@ngrok/mantle/data-table";
+ * import { Button } from "@ngrok/mantle/button";
+ * import { Input } from "@ngrok/mantle/input";
+ * import { useState } from "react";
+ *
+ * type Payment = { id: string; amount: number; status: "pending" | "succeeded" | "failed"; email: string };
+ *
+ * const columnHelper = createColumnHelper<Payment>();
+ * const columns = [
+ *   columnHelper.accessor("status", {
+ *     id: "status",
+ *     header: (props) => (
+ *       <DataTable.Header>
+ *         <DataTable.HeaderSortButton column={props.column} sortingMode="alphanumeric">
+ *           Status
+ *         </DataTable.HeaderSortButton>
+ *       </DataTable.Header>
+ *     ),
+ *     cell: (props) => <DataTable.Cell>{props.getValue()}</DataTable.Cell>,
+ *   }),
+ *   columnHelper.accessor("email", {
+ *     id: "email",
+ *     header: (props) => (
+ *       <DataTable.Header>
+ *         <DataTable.HeaderSortButton column={props.column} sortingMode="alphanumeric">
+ *           Email
+ *         </DataTable.HeaderSortButton>
+ *       </DataTable.Header>
+ *     ),
+ *     cell: (props) => <DataTable.Cell>{props.getValue()}</DataTable.Cell>,
+ *   }),
+ *   columnHelper.accessor("amount", {
+ *     id: "amount",
+ *     header: (props) => (
+ *       <DataTable.Header className="text-right">
+ *         <DataTable.HeaderSortButton
+ *           column={props.column}
+ *           sortingMode="alphanumeric"
+ *           className="justify-end"
+ *           iconPlacement="start"
+ *         >
+ *           Amount
+ *         </DataTable.HeaderSortButton>
+ *       </DataTable.Header>
+ *     ),
+ *     cell: (props) => (
+ *       <DataTable.Cell className="text-right tabular-nums">
+ *         {new Intl.NumberFormat("en-US", { style: "currency", currency: "USD" }).format(props.getValue())}
+ *       </DataTable.Cell>
+ *     ),
+ *   }),
+ * ];
+ *
+ * function PaymentsTable({ data }: { data: Payment[] }) {
+ *   const [globalFilter, setGlobalFilter] = useState("");
+ *
+ *   const table = useReactTable({
+ *     data,
+ *     columns,
+ *     state: { globalFilter },
+ *     onGlobalFilterChange: setGlobalFilter,
+ *     getCoreRowModel: getCoreRowModel(),
+ *     getSortedRowModel: getSortedRowModel(),
+ *     getFilteredRowModel: getFilteredRowModel(),
+ *     getPaginationRowModel: getPaginationRowModel(),
+ *   });
+ *   const rows = table.getRowModel().rows;
+ *
+ *   return (
+ *     <div className="space-y-4">
+ *       <Input
+ *         placeholder="Filter payments…"
+ *         value={globalFilter}
+ *         onChange={(event) => setGlobalFilter(event.target.value)}
+ *       />
+ *       <DataTable.Root table={table}>
+ *         <DataTable.Head />
+ *         <DataTable.Body>
+ *           {rows.length > 0
+ *             ? rows.map((row) => <DataTable.Row key={row.id} row={row} />)
+ *             : <DataTable.EmptyRow>No payments match.</DataTable.EmptyRow>}
+ *         </DataTable.Body>
+ *       </DataTable.Root>
+ *       <div className="flex items-center justify-between gap-2">
+ *         <span className="text-sm text-muted">
+ *           Page {table.getState().pagination.pageIndex + 1} of {table.getPageCount()}
+ *         </span>
+ *         <div className="flex gap-2">
+ *           <Button
+ *             type="button"
+ *             priority="neutral"
+ *             onClick={() => table.previousPage()}
+ *             disabled={!table.getCanPreviousPage()}
+ *           >
+ *             Previous
+ *           </Button>
+ *           <Button
+ *             type="button"
+ *             priority="neutral"
+ *             onClick={() => table.nextPage()}
+ *             disabled={!table.getCanNextPage()}
+ *           >
+ *             Next
+ *           </Button>
+ *         </div>
+ *       </div>
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * Row action column — a sticky right-edge cell with a dropdown menu of actions.
+ * If the row also has `onClick`, stop propagation on the action cell so clicks
+ * don't bubble up and fire the row handler:
+ * ```tsx
+ * import { DataTable, createColumnHelper } from "@ngrok/mantle/data-table";
+ * import { DropdownMenu } from "@ngrok/mantle/dropdown-menu";
+ * import { IconButton } from "@ngrok/mantle/icon-button";
+ * import { DotsThreeVerticalIcon } from "@phosphor-icons/react/DotsThreeVertical";
+ *
+ * const columnHelper = createColumnHelper<Payment>();
+ *
+ * const columns = [
+ *   // …other columns…
+ *   columnHelper.display({
+ *     id: "actions",
+ *     header: () => <DataTable.ActionHeader />,
+ *     cell: (props) => (
+ *       <DataTable.ActionCell onClick={(event) => event.stopPropagation()}>
+ *         <DropdownMenu.Root>
+ *           <DropdownMenu.Trigger asChild>
+ *             <IconButton type="button" label="Actions" icon={<DotsThreeVerticalIcon />} />
+ *           </DropdownMenu.Trigger>
+ *           <DropdownMenu.Content align="end">
+ *             <DropdownMenu.Item onSelect={() => copy(props.row.original.id)}>
+ *               Copy ID
+ *             </DropdownMenu.Item>
+ *             <DropdownMenu.Item onSelect={() => refund(props.row.original.id)}>
+ *               Refund
+ *             </DropdownMenu.Item>
+ *           </DropdownMenu.Content>
+ *         </DropdownMenu.Root>
+ *       </DataTable.ActionCell>
+ *     ),
+ *   }),
+ * ];
+ * ```
+ *
+ * @example
+ * Clickable row navigating to a detail page — also render a `<Link>` inside the
+ * primary cell so the row is reachable by keyboard and screen readers (a `<tr>`
+ * is not focusable):
+ * ```tsx
+ * import { DataTable } from "@ngrok/mantle/data-table";
+ * import { Link, href, useNavigate } from "react-router";
+ *
+ * function PaymentsTable({ data }: { data: Payment[] }) {
+ *   const navigate = useNavigate();
+ *   const table = useReactTable({ data, columns, getCoreRowModel: getCoreRowModel() });
+ *   const rows = table.getRowModel().rows;
+ *
+ *   return (
+ *     <DataTable.Root table={table}>
+ *       <DataTable.Head />
+ *       <DataTable.Body>
+ *         {rows.map((row) => (
+ *           <DataTable.Row
+ *             key={row.id}
+ *             row={row}
+ *             onClick={() => navigate(href("/payments/:id", { id: row.original.id }))}
+ *           />
+ *         ))}
+ *       </DataTable.Body>
+ *     </DataTable.Root>
+ *   );
+ * }
+ *
+ * // The primary column's cell renders a <Link> for keyboard / a11y reachability.
+ * columnHelper.accessor("email", {
+ *   id: "email",
+ *   header: (props) => <DataTable.Header>Email</DataTable.Header>,
+ *   cell: (props) => (
+ *     <DataTable.Cell>
+ *       <Link to={href("/payments/:id", { id: props.row.original.id })}>
+ *         {props.getValue()}
+ *       </Link>
+ *     </DataTable.Cell>
+ *   ),
+ * });
  * ```
  */
 declare const DataTable: {
   /**
-   * The root container of the data table component.
+   * The root container of the data table component. REQUIRED: pass a
+   * `useReactTable` instance (from `@tanstack/react-table`, also re-exported
+   * from `@ngrok/mantle/data-table`) via the `table` prop — every other
+   * `DataTable.*` part reads from it through context.
    *
    * @see https://mantle.ngrok.com/components/data-table#datatableroot
    *
    * @example
    * ```tsx
+   * const table = useReactTable({ data, columns, getCoreRowModel: getCoreRowModel() });
+   * const rows = table.getRowModel().rows;
+   *
    * <DataTable.Root table={table}>
    *   <DataTable.Head />
    *   <DataTable.Body>
-   *     <DataTable.Rows />
+   *     {rows.length > 0
+   *       ? rows.map((row) => <DataTable.Row key={row.id} row={row} />)
+   *       : <DataTable.EmptyRow>No results.</DataTable.EmptyRow>}
    *   </DataTable.Body>
    * </DataTable.Root>
    * ```
    */
   readonly Root: typeof Root;
   /**
-   * A sticky action cell positioned at the end of each row for action buttons.
+   * A sticky action cell positioned at the end of each row, typically holding
+   * an `IconButton` that opens a `DropdownMenu`. Pair with `DataTable.ActionHeader`.
+   *
+   * If the row has `onClick`, stop propagation on this cell so clicks on action
+   * controls don't bubble up and fire the row handler.
    *
    * @see https://mantle.ngrok.com/components/data-table#datatableactioncell
    *
    * @example
    * ```tsx
-   * <DataTable.ActionCell>
-   *   <Button size="sm">Edit</Button>
-   *   <Button size="sm">Delete</Button>
-   * </DataTable.ActionCell>
+   * columnHelper.display({
+   *   id: "actions",
+   *   header: () => <DataTable.ActionHeader />,
+   *   cell: () => (
+   *     <DataTable.ActionCell onClick={(event) => event.stopPropagation()}>
+   *       <DropdownMenu.Root>...</DropdownMenu.Root>
+   *     </DataTable.ActionCell>
+   *   ),
+   * });
    * ```
    */
   readonly ActionCell: typeof ActionCell;
   /**
    * A sticky header cell that pairs with `DataTable.ActionCell`, keeping the
    * action column aligned across the header and body when scrolling horizontally.
+   * Use as the `header` for a `columnHelper.display` action column.
    *
    * @see https://mantle.ngrok.com/components/data-table#datatableactionheader
    *
@@ -257,100 +661,151 @@ declare const DataTable: {
    * columnHelper.display({
    *   id: "actions",
    *   header: () => <DataTable.ActionHeader />,
-   *   cell: () => <DataTable.ActionCell>{...}</DataTable.ActionCell>,
-   * })
+   *   cell: () => (
+   *     <DataTable.ActionCell onClick={(event) => event.stopPropagation()}>
+   *       <DropdownMenu.Root>...</DropdownMenu.Root>
+   *     </DataTable.ActionCell>
+   *   ),
+   * });
    * ```
    */
   readonly ActionHeader: typeof ActionHeader;
   /**
-   * A table cell component for rendering individual data cells.
+   * A `<td>` for rendering an individual data cell. Re-exported from
+   * `Table.Cell`. Every cell rendered by a column's `cell` function should
+   * be wrapped in this — a raw `<td>` skips mantle typography and padding.
    *
    * @see https://mantle.ngrok.com/components/data-table#datatablecell
    *
    * @example
    * ```tsx
-   * <DataTable.Cell>
-   *   Cell content
-   * </DataTable.Cell>
+   * columnHelper.accessor("name", {
+   *   id: "name",
+   *   header: (props) => <DataTable.Header>Name</DataTable.Header>,
+   *   cell: (props) => <DataTable.Cell>{props.getValue()}</DataTable.Cell>,
+   * });
    * ```
    */
   readonly Cell: _$react.ForwardRefExoticComponent<Omit<_$react.DetailedHTMLProps<_$react.TdHTMLAttributes<HTMLTableDataCellElement>, HTMLTableDataCellElement>, "ref"> & _$react.RefAttributes<HTMLTableDataCellElement>>;
   /**
-   * The table body container for rows of data.
+   * The `<tbody>` container for rows of data. Typically wraps a map of
+   * `DataTable.Row`, with a `DataTable.EmptyRow` fallback when there is
+   * no data.
    *
    * @see https://mantle.ngrok.com/components/data-table#datatablebody
    *
    * @example
    * ```tsx
    * <DataTable.Body>
-   *   <DataTable.Rows />
+   *   {rows.length > 0
+   *     ? rows.map((row) => <DataTable.Row key={row.id} row={row} />)
+   *     : <DataTable.EmptyRow>No results.</DataTable.EmptyRow>}
    * </DataTable.Body>
    * ```
    */
   readonly Body: _$react.ForwardRefExoticComponent<Omit<Omit<_$react.DetailedHTMLProps<_$react.HTMLAttributes<HTMLTableSectionElement>, HTMLTableSectionElement>, "ref"> & _$react.RefAttributes<HTMLTableSectionElement>, "ref"> & _$react.RefAttributes<HTMLTableSectionElement>>;
   /**
-   * An empty state row that spans all columns when there's no data to display.
+   * An empty-state row that spans every column. Render this as the `else`
+   * branch when `rows.length === 0` to keep the table's frame intact instead
+   * of collapsing to an empty `<tbody>`.
    *
    * @see https://mantle.ngrok.com/components/data-table#datatableemptyrow
    *
    * @example
    * ```tsx
-   * <DataTable.EmptyRow>
-   *   No data available
-   * </DataTable.EmptyRow>
+   * <DataTable.Body>
+   *   {rows.length > 0
+   *     ? rows.map((row) => <DataTable.Row key={row.id} row={row} />)
+   *     : <DataTable.EmptyRow>No results.</DataTable.EmptyRow>}
+   * </DataTable.Body>
    * ```
    */
   readonly EmptyRow: typeof EmptyRow;
   /**
-   * The table header container that renders column headers automatically.
+   * The `<thead>` container that renders column headers automatically from
+   * `table.getHeaderGroups()`. Does not accept children — headers come from
+   * each column's `header` definition.
    *
    * @see https://mantle.ngrok.com/components/data-table#datatablehead
    *
    * @example
    * ```tsx
-   * <DataTable.Head />
+   * <DataTable.Root table={table}>
+   *   <DataTable.Head />
+   *   <DataTable.Body>...</DataTable.Body>
+   * </DataTable.Root>
    * ```
    */
   readonly Head: typeof Head;
   /**
-   * A header cell component optimized for data table header actions.
+   * A `<th>` optimized for header actions. Wrap each column's header content
+   * in this; for sortable columns, nest a `DataTable.HeaderSortButton` inside.
    *
    * @see https://mantle.ngrok.com/components/data-table#datatableheader
    *
    * @example
    * ```tsx
-   * <DataTable.Header>
-   *   <DataTable.HeaderSortButton column={column} sortingMode="alphanumeric">
-   *     Column Title
-   *   </DataTable.HeaderSortButton>
-   * </DataTable.Header>
+   * columnHelper.accessor("name", {
+   *   id: "name",
+   *   header: (props) => (
+   *     <DataTable.Header>
+   *       <DataTable.HeaderSortButton column={props.column} sortingMode="alphanumeric">
+   *         Name
+   *       </DataTable.HeaderSortButton>
+   *     </DataTable.Header>
+   *   ),
+   *   cell: (props) => <DataTable.Cell>{props.getValue()}</DataTable.Cell>,
+   * });
    * ```
    */
   readonly Header: typeof Header;
   /**
-   * A sortable button toggle for column headers with sorting functionality.
+   * A sortable button toggle for a column header. Clicks cycle through
+   * sort directions: for `"alphanumeric"`, `unsorted → asc → desc → unsorted`;
+   * for `"time"`, `unsorted → desc (newest-first) → asc → unsorted`.
+   *
+   * Pass `className="justify-end"` and `iconPlacement="start"` for
+   * right-aligned numeric columns so the sort icon stays paired with the label.
    *
    * @see https://mantle.ngrok.com/components/data-table#datatableheadersortbutton
    *
    * @example
    * ```tsx
-   * <DataTable.HeaderSortButton
-   *   column={column}
-   *   sortingMode="alphanumeric"
-   * >
-   *   Column Title
-   * </DataTable.HeaderSortButton>
+   * columnHelper.accessor("email", {
+   *   id: "email",
+   *   header: (props) => (
+   *     <DataTable.Header>
+   *       <DataTable.HeaderSortButton column={props.column} sortingMode="alphanumeric">
+   *         Email
+   *       </DataTable.HeaderSortButton>
+   *     </DataTable.Header>
+   *   ),
+   *   cell: (props) => <DataTable.Cell>{props.getValue()}</DataTable.Cell>,
+   * });
    * ```
    */
   readonly HeaderSortButton: typeof HeaderSortButton;
   /**
-   * A single data table row component for rendering custom row layouts.
+   * A single data table body row rendered from a TanStack Table row instance.
+   * Does not accept children — cells come from each column's `cell` definition.
+   *
+   * When `onClick` is provided, the row automatically receives `cursor-pointer`.
+   * Pass a different `cursor-*` class via `className` to override. For keyboard
+   * and screen-reader access, also render a `<Link>` inside the primary cell.
    *
    * @see https://mantle.ngrok.com/components/data-table#datatablerow
    *
    * @example
    * ```tsx
-   * <DataTable.Row row={row} />
+   * const navigate = useNavigate();
+   *
+   * {rows.map((row) => (
+   *   <DataTable.Row
+   *     key={row.id}
+   *     row={row}
+   *     onClick={() => navigate(href("/payments/:id", { id: row.original.id }))}
+   *   />
+   * ))}
    * ```
    */
   readonly Row: typeof Row$1;