@helix-x/datagrid-ui 0.1.0 → 0.1.1

package/dist/index.d.ts

@@ -2,75 +2,284 @@ import * as react from 'react';
 import { ReactNode, Ref } from 'react';
 
 /**
- * The wire shapes below intentionally mirror what ag-grid's server-side row
- * model posts, because most existing backends that speak "grid" already parse
- * them. Keeping them identical is what lets a screen swap grids without a
- * backend change.
+ * Every public type in `@helix-x/datagrid-ui`.
+ *
+ * The filter, sort and row-request shapes deliberately mirror what ag-grid's
+ * server-side row model posts, so a backend written for that model accepts this
+ * grid's requests unchanged.
+ */
+
+/**
+ * Comparison operators available on a `text` column filter.
+ *
+ * `blank` and `notBlank` take no operand — see {@link isUnaryFilter}.
+ *
+ * @see {@link TEXT_FILTER_TYPES} for the same list as a runtime array.
  */
 type TextFilterType = 'contains' | 'notContains' | 'equals' | 'notEqual' | 'startsWith' | 'endsWith' | 'blank' | 'notBlank';
+/**
+ * Comparison operators available on a `number` column filter.
+ *
+ * `inRange` uses both `filter` and `filterTo`; `blank` and `notBlank` take no
+ * operand at all.
+ *
+ * @see {@link NUMBER_FILTER_TYPES} for the same list as a runtime array.
+ */
 type NumberFilterType = 'equals' | 'notEqual' | 'lessThan' | 'lessThanOrEqual' | 'greaterThan' | 'greaterThanOrEqual' | 'inRange' | 'blank' | 'notBlank';
+/**
+ * Comparison operators available on a `date` column filter.
+ *
+ * `inRange` uses both `dateFrom` and `dateTo`; `blank` and `notBlank` take no
+ * operand.
+ *
+ * @see {@link DATE_FILTER_TYPES} for the same list as a runtime array.
+ */
 type DateFilterType = 'equals' | 'notEqual' | 'before' | 'after' | 'inRange' | 'blank' | 'notBlank';
+/**
+ * A text filter as sent to the server.
+ *
+ * @example
+ * ```ts
+ * const model: TextFilterModel = {
+ *   filterType: 'text',
+ *   type: 'contains',
+ *   filter: 'acme',
+ * };
+ * ```
+ */
 interface TextFilterModel {
+    /** Discriminant. Always `'text'`. */
     filterType: 'text';
+    /** The comparison to apply. */
     type: TextFilterType;
+    /** The search term. Absent for `blank` and `notBlank`. */
     filter?: string;
 }
+/**
+ * A numeric filter as sent to the server.
+ *
+ * @example Between two values
+ * ```ts
+ * const model: NumberFilterModel = {
+ *   filterType: 'number',
+ *   type: 'inRange',
+ *   filter: 10,
+ *   filterTo: 100,
+ * };
+ * ```
+ */
 interface NumberFilterModel {
+    /** Discriminant. Always `'number'`. */
     filterType: 'number';
+    /** The comparison to apply. */
     type: NumberFilterType;
+    /** The operand, or the lower bound when `type` is `'inRange'`. */
     filter?: number;
+    /** The upper bound. Only meaningful when `type` is `'inRange'`. */
     filterTo?: number;
 }
+/**
+ * A date filter as sent to the server.
+ *
+ * Dates are calendar days, not instants — compare on the day, or a same-day
+ * timestamp will never match its own date.
+ *
+ * @example
+ * ```ts
+ * const model: DateFilterModel = {
+ *   filterType: 'date',
+ *   type: 'after',
+ *   dateFrom: '2026-01-01',
+ * };
+ * ```
+ */
 interface DateFilterModel {
+    /** Discriminant. Always `'date'`. */
     filterType: 'date';
+    /** The comparison to apply. */
     type: DateFilterType;
-    /** `YYYY-MM-DD` */
+    /** Lower bound, formatted `YYYY-MM-DD`. */
     dateFrom?: string;
+    /** Upper bound, formatted `YYYY-MM-DD`. Only used by `'inRange'`. */
     dateTo?: string;
 }
+/**
+ * A set (multi-select) filter as sent to the server.
+ *
+ * An empty `values` array means "no constraint" — that is how the grid clears
+ * a set filter. {@link buildSetFilter} returns `null` rather than an empty set.
+ *
+ * @example
+ * ```ts
+ * const model: SetFilterModel = {
+ *   filterType: 'set',
+ *   values: ['ACTIVE', 'PENDING'],
+ * };
+ * ```
+ */
 interface SetFilterModel {
+    /** Discriminant. Always `'set'`. */
     filterType: 'set';
+    /** The selected values. Compared as strings. */
     values: string[];
 }
+/**
+ * Any one column filter. Discriminate on `filterType`.
+ *
+ * @example
+ * ```ts
+ * function describe(filter: HxFilterModel) {
+ *   switch (filter.filterType) {
+ *     case 'text':   return filter.filter;
+ *     case 'number': return filter.filter;
+ *     case 'date':   return filter.dateFrom;
+ *     case 'set':    return filter.values.join(', ');
+ *   }
+ * }
+ * ```
+ */
 type HxFilterModel = TextFilterModel | NumberFilterModel | DateFilterModel | SetFilterModel;
+/**
+ * Every active filter, keyed by {@link ColumnDef.colId | column id}.
+ *
+ * A column with no entry is unfiltered. Use {@link withFilter} to add or remove
+ * one immutably.
+ */
 type FilterModelMap = Record<string, HxFilterModel>;
+/**
+ * Which filter UI a column offers, set via {@link ColumnDef.filter}.
+ *
+ * Pass `false` on the column instead to disable filtering entirely.
+ */
 type FilterKind = 'text' | 'number' | 'date' | 'set';
+/** Sort direction for one column. */
 type SortDirection = 'asc' | 'desc';
+/**
+ * One entry in the sort model.
+ *
+ * The model is an ordered array: the first entry is the primary sort, and later
+ * entries break ties in the ones before them.
+ *
+ * @example Sort by status, then by newest first
+ * ```ts
+ * const sortModel: SortModelItem[] = [
+ *   { colId: 'status',    sort: 'asc'  },
+ *   { colId: 'createdAt', sort: 'desc' },
+ * ];
+ * ```
+ */
 interface SortModelItem {
+    /** The {@link ColumnDef.colId | column id} to sort on. */
     colId: string;
+    /** Direction to sort in. */
     sort: SortDirection;
 }
 /**
+ * What the grid asks the server for: one page, with the active sort and
+ * filters.
+ *
  * Structurally compatible with ag-grid's `IServerSideGetRowsRequest`, so an
- * endpoint written for that model accepts this verbatim. The grouping/pivot
+ * endpoint written for that model accepts this verbatim. The grouping and pivot
  * fields are always sent empty — this grid does not implement them — but they
  * are present so servers that destructure them do not fall over.
+ *
+ * @example Handling the request on the server
+ * ```ts
+ * app.post('/api/rows', (req, res) => {
+ *   const { startRow, endRow, sortModel, filterModel } = req.body;
+ *   const filtered = applyFilters(allRows, filterModel);
+ *   const sorted   = applySort(filtered, sortModel);
+ *   res.json({ rows: sorted.slice(startRow, endRow), lastRow: filtered.length });
+ * });
+ * ```
  */
 interface HxRowsRequest {
+    /** Zero-based index of the first row wanted, inclusive. */
     startRow: number;
+    /** Index one past the last row wanted, exclusive. */
     endRow: number;
+    /** Active sorts, primary first. Empty when unsorted. */
     sortModel: SortModelItem[];
+    /** Active filters, keyed by column id. Empty when unfiltered. */
     filterModel: FilterModelMap;
+    /** Always empty. Present only for ag-grid wire compatibility. */
     rowGroupCols: never[];
+    /** Always empty. Present only for ag-grid wire compatibility. */
     valueCols: never[];
+    /** Always empty. Present only for ag-grid wire compatibility. */
     pivotCols: never[];
+    /** Always `false`. Present only for ag-grid wire compatibility. */
     pivotMode: false;
+    /** Always empty. Present only for ag-grid wire compatibility. */
     groupKeys: never[];
 }
+/**
+ * What the server returns for one {@link HxRowsRequest}.
+ *
+ * @typeParam T - The row type.
+ */
 interface HxRowsResponse<T> {
+    /** The rows for the requested page only, not the whole result set. */
     rows: T[];
-    /** Total row count across all pages, or -1 when unknown. */
+    /**
+     * Total row count across **all** pages — not `rows.length`. This is what
+     * drives the pager. Return `-1` when the total is genuinely unknown.
+     */
     lastRow: number;
 }
+/**
+ * The grid's one required dependency: something that turns a request into rows.
+ *
+ * @typeParam T - The row type.
+ *
+ * @example
+ * ```tsx
+ * const dataSource: HxDataSource<Person> = {
+ *   getRows: async (request, signal) => {
+ *     const response = await fetch('/api/people', {
+ *       method: 'POST',
+ *       headers: { 'content-type': 'application/json' },
+ *       body: JSON.stringify(request),
+ *       signal,
+ *     });
+ *     return response.json();
+ *   },
+ * };
+ * ```
+ *
+ * @remarks
+ * Memoise the object (or define it outside the component). A new identity on
+ * every render causes a refetch.
+ */
 interface HxDataSource<T> {
+    /**
+     * Fetch one page of rows.
+     *
+     * @param request - The page, sort and filters being asked for.
+     * @param signal - Aborts when the grid supersedes this request. Pass it to
+     * `fetch` so a slow response for an old sort can never overwrite a newer one.
+     * @returns The page of rows plus the total row count.
+     */
     getRows(request: HxRowsRequest, signal: AbortSignal): Promise<HxRowsResponse<T>>;
 }
+/** Which edge a pinned column sticks to. */
 type Pinned = 'left' | 'right';
+/**
+ * What {@link ColumnDef.cellRenderer} receives.
+ *
+ * @typeParam T - The row type.
+ * @typeParam C - The {@link DataGridProps.context | context} type.
+ */
 interface CellRendererParams<T, C = unknown> {
+    /** The whole row, for cells that need more than their own field. */
     row: T;
+    /** Index within the currently loaded page, not the full result set. */
     rowIndex: number;
+    /** The raw value, after {@link ColumnDef.valueGetter}. */
     value: unknown;
+    /** The display string, after {@link ColumnDef.valueFormatter}. */
     formatted: string;
+    /** The column being rendered. */
     column: ColumnDef<T, C>;
     /**
      * Arbitrary app state handed to every renderer. Put volatile things here
@@ -78,425 +287,1393 @@ interface CellRendererParams<T, C = unknown> {
      * memoised on `[]` and never rebuild.
      */
     context: C;
+    /** The live imperative API, for renderers that act on the grid. */
     api: GridApi<T>;
 }
+/**
+ * What a cell editor receives — both the built-ins and your own.
+ *
+ * @typeParam T - The row type.
+ * @typeParam C - The {@link DataGridProps.context | context} type.
+ */
 interface EditorParams<T, C = unknown> {
+    /** Current draft value for this cell. */
     value: unknown;
+    /** The row being edited, as a draft copy. */
     row: T;
+    /** The column being edited. */
     column: ColumnDef<T, C>;
+    /** The grid's {@link DataGridProps.context | context}. */
     context: C;
     /** Writes into the row draft. Never hits the network. */
     onChange: (value: unknown) => void;
-    /** Commit the whole row. */
+    /** Commit the whole row, invoking {@link DataGridProps.onRowCommit}. */
     onCommit: () => void;
+    /** Abandon the edit and restore the original row. */
     onCancel: () => void;
+    /** Server-supplied message for this field, if the last commit was rejected. */
     error?: string;
+    /** True for the first editable cell in the row. */
     autoFocus?: boolean;
 }
+/**
+ * A custom cell editor.
+ *
+ * @typeParam T - The row type.
+ * @typeParam C - The context type.
+ *
+ * @example A trimming text editor
+ * ```tsx
+ * const TrimmedEditor: EditorComponent<Person> = ({ value, onChange, onCommit, onCancel }) => (
+ *   <input
+ *     autoFocus
+ *     value={String(value ?? '')}
+ *     onChange={(e) => onChange(e.target.value.trim())}
+ *     onKeyDown={(e) => {
+ *       if (e.key === 'Enter') onCommit();
+ *       if (e.key === 'Escape') onCancel();
+ *     }}
+ *   />
+ * );
+ * ```
+ */
 type EditorComponent<T, C = unknown> = (params: EditorParams<T, C>) => ReactNode;
+/**
+ * Names of the editors that ship with the grid.
+ *
+ * @see {@link BUILTIN_EDITORS} for the components these map to.
+ */
 type BuiltinEditor = 'text' | 'number' | 'select' | 'date' | 'checkbox';
+/** One choice offered by the `select` editor. */
 interface SelectOption {
+    /** Shown to the user. */
     label: string;
+    /** Written into the row draft. */
     value: unknown;
 }
+/**
+ * One column. This is the main thing you write when using the grid.
+ *
+ * @typeParam T - The row type.
+ * @typeParam C - The {@link DataGridProps.context | context} type.
+ *
+ * @example A representative set of columns
+ * ```tsx
+ * const columns: ColumnDef<Person>[] = [
+ *   { field: 'id',   header: 'ID', width: 90, filter: 'number' },
+ *   { field: 'name', header: 'Name', flex: 1, filter: 'text', editable: true },
+ *   {
+ *     field: 'status',
+ *     header: 'Status',
+ *     filter: 'set',
+ *     filterParams: { values: () => fetch('/api/statuses').then((r) => r.json()) },
+ *     editable: true,
+ *     editor: 'select',
+ *     editorParams: { options: [{ label: 'Active', value: 'ACTIVE' }] },
+ *   },
+ *   {
+ *     colId: 'fullName',
+ *     header: 'Full name',
+ *     sortable: false,
+ *     valueGetter: (row) => `${row.first} ${row.last}`,
+ *   },
+ * ];
+ * ```
+ *
+ * @remarks
+ * Define columns as a module constant or memoise on `[]`. Anything volatile
+ * belongs in {@link DataGridProps.context} instead, which reaches every
+ * renderer without rebuilding a single definition.
+ */
 interface ColumnDef<T, C = unknown> {
-    /** Stable identity. Falls back to `field` when omitted. */
+    /**
+     * Stable identity, used as the key in the sort and filter models and in
+     * persisted layout. Falls back to {@link ColumnDef.field | field} when
+     * omitted; one of the two is required.
+     */
     colId?: string;
-    /** Dotted path into the row. Also used as the server-side filter/sort key. */
+    /**
+     * Dotted path into the row (`'customer.name'`), and the key sent to the
+     * server for sorting and filtering.
+     *
+     * Omit it for purely derived columns and supply `colId` plus
+     * {@link ColumnDef.valueGetter | valueGetter} instead.
+     */
     field?: string;
+    /** Header content. Any node — an icon, a tooltip wrapper, anything. */
     header: ReactNode;
-    /** Plain-text header, used for exports when `header` is a node. */
+    /**
+     * Plain-text header for exports and aria labels. Required in practice
+     * whenever `header` is a node rather than a string.
+     */
     headerName?: string;
+    /**
+     * Starting width in pixels.
+     * @defaultValue 150
+     */
     width?: number;
+    /**
+     * Floor for both `flex` and user resizing.
+     * @defaultValue 60
+     */
     minWidth?: number;
+    /** Ceiling for user resizing. */
     maxWidth?: number;
-    /** Share of the leftover horizontal space. */
+    /**
+     * Share of the leftover horizontal space, like `flex-grow`. A column with
+     * `flex: 2` takes twice the slack of one with `flex: 1`.
+     */
     flex?: number;
+    /** Stick this column to an edge while the rest scroll horizontally. */
     pinned?: Pinned;
+    /** Start hidden. The user can still reveal it from the columns panel. */
     hide?: boolean;
+    /**
+     * Allow click-to-sort on the header.
+     * @defaultValue true
+     */
     sortable?: boolean;
+    /**
+     * Allow drag-to-resize.
+     * @defaultValue true
+     */
     resizable?: boolean;
     /** Prevent the user dragging this column out of position. */
     lockPosition?: boolean;
+    /**
+     * Which filter UI to offer, or `false` for none.
+     *
+     * @defaultValue undefined (no filter)
+     */
     filter?: FilterKind | false;
+    /** Extra options for the filter named by {@link ColumnDef.filter}. */
     filterParams?: {
-        /** Static values, or a loader for a set filter whose options come from an API. */
+        /**
+         * Options for a `set` filter: a static list, or a function called the first
+         * time the popover opens so the list can come from an API.
+         */
         values?: string[] | (() => Promise<string[]>);
         /** Hide the always-visible filter input under the header for this column. */
         suppressFloatingFilter?: boolean;
     };
-    /** Alternative flat keys to try when the server flattens nested fields. */
+    /**
+     * Alternative flat keys to try when the server flattens nested fields — some
+     * backends return `{"customer.name": x}` rather than a nested object, and
+     * change the prefix when grouping is on.
+     */
     fieldAliases?: string[];
+    /**
+     * Compute the cell value instead of reading `field`. Takes precedence over
+     * every other lookup.
+     */
     valueGetter?: (row: T) => unknown;
+    /**
+     * Turn the raw value into its display string. Also used for exports unless
+     * {@link ColumnDef.exportValue} is given.
+     */
     valueFormatter?: (value: unknown, row: T) => string;
+    /**
+     * Render the cell as markup. Presentation only — sorting and filtering still
+     * use `field`, so a decorated cell keeps behaving like a plain one.
+     */
     cellRenderer?: (params: CellRendererParams<T, C>) => ReactNode;
+    /** Whether the cell can be edited, optionally per row. */
     editable?: boolean | ((row: T) => boolean);
+    /**
+     * Which editor to use: a {@link BuiltinEditor} name or your own component.
+     * @defaultValue 'text'
+     */
     editor?: BuiltinEditor | EditorComponent<T, C>;
+    /** Extra options for the editor named by {@link ColumnDef.editor}. */
     editorParams?: {
+        /** Choices for the `select` editor. */
         options?: SelectOption[];
+        /** Placeholder for the `text` and `number` editors. */
         placeholder?: string;
     };
+    /**
+     * The flat string written to CSV and the clipboard. Supply this whenever
+     * {@link ColumnDef.cellRenderer} produces markup.
+     */
     exportValue?: (row: T) => string;
+    /** Leave this column out of CSV and clipboard output entirely. */
     suppressExport?: boolean;
+    /** Extra classes on every cell, optionally per row. */
     cellClassName?: string | ((row: T) => string);
+    /** Extra classes on the header cell. */
     headerClassName?: string;
-    /** Horizontal alignment of the cell content. */
+    /**
+     * Horizontal alignment of the cell content.
+     * @defaultValue 'left'
+     */
     align?: 'left' | 'center' | 'right';
 }
-/** A column with every default resolved. Internal, but exported for renderers. */
+/**
+ * A {@link ColumnDef} with every optional default filled in.
+ *
+ * Produced by {@link resolveColumn}. Mostly internal, but exported because the
+ * exporter helpers and the columns panel take it.
+ *
+ * @typeParam T - The row type.
+ * @typeParam C - The context type.
+ */
 interface ResolvedColumn<T, C = unknown> extends ColumnDef<T, C> {
+    /** Always present — `colId`, or `field` when `colId` was omitted. */
     colId: string;
+    /** Resolved width, never below `minWidth`. */
     width: number;
+    /** Resolved minimum width. */
     minWidth: number;
+    /** Resolved sortability. */
     sortable: boolean;
+    /** Resolved resizability. */
     resizable: boolean;
 }
-/** Geometry for one visible column, computed once per layout change. */
+/**
+ * Geometry for one visible column, computed once per layout change.
+ *
+ * @typeParam T - The row type.
+ * @typeParam C - The context type.
+ */
 interface ColumnLayoutItem<T, C = unknown> {
+    /** The column this geometry belongs to. */
     column: ResolvedColumn<T, C>;
+    /** Convenience copy of `column.colId`. */
     colId: string;
+    /** Final pixel width, after `flex` distribution and user resizing. */
     width: number;
     /** Offset from the left edge of the full (unscrolled) column strip. */
     left: number;
+    /** Which edge this column is pinned to, if any. */
     pinned?: Pinned;
     /** `left`/`right` offset to use for `position: sticky` on pinned columns. */
     stickyOffset: number;
 }
+/**
+ * The measured layout of every visible column.
+ *
+ * @typeParam T - The row type.
+ * @typeParam C - The context type.
+ */
 interface ColumnLayout<T, C = unknown> {
+    /** Visible columns in display order, each with its geometry. */
     items: ColumnLayoutItem<T, C>[];
+    /** Combined width of all visible columns. */
     totalWidth: number;
+    /** Combined width of the left-pinned columns. */
     leftPinnedWidth: number;
+    /** Combined width of the right-pinned columns. */
     rightPinnedWidth: number;
 }
+/**
+ * The outcome of {@link DataGridProps.onRowCommit}.
+ *
+ * Returning `ok: false` keeps the row in edit mode and paints each message onto
+ * the cell whose column id it is keyed by — which is how server-side validation
+ * reaches the user without being mirrored in the client.
+ *
+ * @example
+ * ```ts
+ * async function onRowCommit(draft: Person): Promise<RowCommitResult> {
+ *   const response = await fetch(`/api/people/${draft.id}`, {
+ *     method: 'PATCH',
+ *     body: JSON.stringify(draft),
+ *   });
+ *   if (response.status === 422) {
+ *     const { errors, message } = await response.json();
+ *     return { ok: false, errors, message };
+ *   }
+ *   return { ok: true, row: await response.json() };
+ * }
+ * ```
+ */
 type RowCommitResult = {
+    /** Discriminant: the row was saved. */
     ok: true;
+    /**
+     * The server's canonical copy, which replaces the row in place. Useful
+     * when the server fills in derived fields.
+     */
     row?: unknown;
 } | {
+    /** Discriminant: the row was rejected and stays open. */
     ok: false;
+    /** Messages keyed by column id, painted onto the offending cells. */
     errors: Record<string, string>;
+    /** A single message for the whole row. */
     message?: string;
 };
+/**
+ * Schema version for {@link PersistedGridState}.
+ *
+ * Saved state carrying a different version is discarded rather than migrated:
+ * the layout is a convenience, and a bad restore is worse than starting from
+ * the column defaults.
+ */
 declare const GRID_STATE_VERSION = 1;
+/**
+ * What the grid writes to `localStorage` under
+ * {@link DataGridProps.storageKey}.
+ *
+ * Stored under the key `hxg:<storageKey>`.
+ */
 interface PersistedGridState {
+    /** Schema version. Compared against {@link GRID_STATE_VERSION} on read. */
     v: number;
+    /** Column layout the user arranged. */
     columns: {
+        /** Column ids in display order. */
         order: string[];
+        /** Ids of columns the user hid. */
         hidden: string[];
+        /** User-resized widths, by column id. */
         widths: Record<string, number>;
+        /** User-pinned columns, by column id. */
         pinned: Record<string, Pinned>;
     };
+    /** The sort model at the time of saving. */
     sort: SortModelItem[];
+    /** The filter model at the time of saving. */
     filters: FilterModelMap;
+    /** Paging preferences. */
     pagination: {
+        /** Rows per page the user chose. */
         pageSize: number;
     };
 }
+/** Options for {@link GridApi.exportCsv}. */
 interface ExportCsvOptions {
+    /**
+     * Export only the selected rows rather than the whole loaded page.
+     * @defaultValue false
+     */
     onlySelected?: boolean;
+    /**
+     * File name, with or without the `.csv` suffix.
+     * @defaultValue the grid's `exportFileName` prop
+     */
     fileName?: string;
-    /** Field separator. Defaults to `,`. */
+    /**
+     * Field separator.
+     * @defaultValue ','
+     */
     separator?: string;
 }
+/**
+ * The imperative handle onto a live grid.
+ *
+ * Reach it either through {@link DataGridProps.apiRef} or as
+ * {@link DataGridProps.toolbar}'s argument.
+ *
+ * @typeParam T - The row type.
+ *
+ * @example
+ * ```tsx
+ * const apiRef = useRef<GridApi<Person>>(null);
+ *
+ * <DataGrid
+ *   apiRef={apiRef}
+ *   toolbar={(api) => (
+ *     <button onClick={() => api.exportCsv({ onlySelected: true })}>
+ *       Export selection
+ *     </button>
+ *   )}
+ *   {...rest}
+ * />
+ * ```
+ */
 interface GridApi<T> {
-    /** Re-fetch. `purge` drops every cached block first. */
+    /**
+     * Re-fetch the current page.
+     *
+     * @param options - `purge: true` drops every cached block first, so nothing
+     * stale can survive; otherwise cached neighbouring pages are kept.
+     */
     refresh(options?: {
         purge?: boolean;
     }): void;
+    /** The rows currently loaded for this page, in display order. */
     getDisplayedRows(): T[];
+    /** The selected rows that are on the current page. */
     getSelectedRows(): T[];
+    /** Ids of every selected row, including those on other pages. */
     getSelectedIds(): Array<string | number>;
+    /** Deselect everything. */
     clearSelection(): void;
+    /** Select every row on the current page. */
     selectAll(): void;
+    /** Download the rows as CSV, honouring each column's `exportValue`. */
     exportCsv(options?: ExportCsvOptions): void;
+    /** Copy the selection to the clipboard as TSV, which spreadsheets expect. */
     copySelectionToClipboard(): Promise<void>;
+    /** The active filters. */
     getFilterModel(): FilterModelMap;
+    /** Replace every filter at once, triggering one refetch. */
     setFilterModel(model: FilterModelMap): void;
+    /** The active sorts, primary first. */
     getSortModel(): SortModelItem[];
+    /** Replace the sort model, triggering one refetch. */
     setSortModel(model: SortModelItem[]): void;
+    /** Discard the user's column layout and return to the definitions' defaults. */
     resetColumns(): void;
-    /** Patch rows already on screen without a round trip. */
+    /**
+     * Patch rows already on screen, matched by `getRowId`, without a round trip.
+     *
+     * Ids that are not on the current page are ignored, so a live feed can push
+     * everything it has without the client filtering first. Scroll position,
+     * selection, sort and any open editor are all preserved.
+     *
+     * @param rows - Whole replacement rows, not partials.
+     */
     updateRows(rows: T[]): void;
+    /**
+     * Open the row editor programmatically.
+     * @param rowId - The id, as returned by `getRowId`.
+     */
     startEditing(rowId: string | number): void;
+    /** Close the editor, abandoning any uncommitted draft. */
     stopEditing(): void;
 }
 
+/**
+ * A row's stable identity, as returned by `getRowId`.
+ *
+ * Selection, editing and {@link GridApi.updateRows} all key off this.
+ */
 type RowId = string | number;
+/**
+ * What {@link useSelectionModel} returns.
+ *
+ * @typeParam T - The row type.
+ */
 interface UseSelectionModelResult<T> {
+    /** Every selected id, including rows on pages that are not loaded. */
     selectedIds: Set<RowId>;
+    /** Whether one id is selected. */
     isSelected: (id: RowId) => boolean;
     /** True when every row currently on screen is selected. */
     allVisibleSelected: boolean;
+    /** True when some, but not all, visible rows are selected. */
     someVisibleSelected: boolean;
+    /**
+     * Toggle one row.
+     * @param id - The row to toggle.
+     * @param index - Its index in the loaded page, used as the shift anchor.
+     * @param shiftKey - Extend from the last toggled row instead of toggling one.
+     */
     toggleRow: (id: RowId, index: number, shiftKey: boolean) => void;
+    /** Select every visible row, or deselect them if all are already selected. */
     toggleAllVisible: () => void;
+    /** Deselect everything, including rows on other pages. */
     clear: () => void;
+    /** Select every row on the current page. */
     selectAllVisible: () => void;
+    /** The selected rows that are currently loaded. */
     getSelectedRows: () => T[];
 }
 /**
- * Selection lives here as a real React model rather than being read back out of
- * persisted grid state -- that indirection is what made the previous
- * implementation's "is anything selected?" check unreliable.
+ * Multi-row selection with shift-range support.
+ *
+ * Selection survives paging: ids stay selected even when their rows are not
+ * loaded, which is why `getSelectedRows` returns only the loaded subset while
+ * `selectedIds` holds everything.
+ *
+ * @typeParam T - The row type.
+ * @param rows - The currently loaded page.
+ * @param getRowId - Stable identity for a row.
+ * @param onSelectionChanged - Called with every selected id after each change.
+ * @returns The selection state and its mutators.
  */
 declare function useSelectionModel<T>(rows: T[], getRowId: (row: T) => RowId, onSelectionChanged?: (ids: RowId[]) => void): UseSelectionModelResult<T>;
 
+/**
+ * Props for {@link DataGrid}.
+ *
+ * @typeParam T - The row type.
+ * @typeParam C - The {@link DataGridProps.context | context} type. Inferred
+ * from `context`; defaults to `unknown`.
+ */
 interface DataGridProps<T, C = unknown> {
+    /**
+     * The columns to render.
+     *
+     * @remarks
+     * Define these as a module constant or memoise on `[]` — anything volatile
+     * belongs in {@link DataGridProps.context} instead.
+     */
     columns: ColumnDef<T, C>[];
+    /**
+     * Where rows come from. Memoise it; a new identity causes a refetch.
+     *
+     * @see {@link HxDataSource}
+     */
     dataSource: HxDataSource<T>;
+    /**
+     * Stable identity for a row, used for selection, editing and
+     * {@link GridApi.updateRows}. Must be stable across refetches.
+     */
     getRowId: (row: T) => RowId;
-    /** Volatile app state handed to every cell renderer. */
+    /**
+     * Volatile app state handed to every cell renderer.
+     *
+     * This is the escape hatch that keeps `columns` static: put in-flight ids,
+     * permission checks and event handlers here, and changing them re-renders
+     * cells without rebuilding a single column definition.
+     */
     context?: C;
-    /** localStorage key for column/sort/filter/page-size preferences. */
+    /**
+     * `localStorage` key for column layout, sort, filters and page size.
+     *
+     * Omit it and nothing is persisted. Stored under `hxg:<storageKey>`.
+     *
+     * @see {@link PersistedGridState}
+     */
     storageKey?: string;
+    /**
+     * Row height in pixels. Fixed for every row — that is what keeps
+     * virtualization O(1).
+     * @defaultValue 36
+     */
     rowHeight?: number;
+    /**
+     * Header height in pixels.
+     * @defaultValue 36
+     */
     headerHeight?: number;
-    /** Show the always-visible filter inputs under the header. */
+    /**
+     * Show the always-visible filter inputs under the header.
+     * @defaultValue true
+     */
     floatingFilter?: boolean;
+    /**
+     * Show the checkbox selection column.
+     * @defaultValue true
+     */
     selectable?: boolean;
+    /**
+     * Rows per page before the user changes it. A persisted preference wins.
+     * @defaultValue 20
+     */
     defaultPageSize?: number;
+    /**
+     * Page sizes offered in the pager.
+     * @defaultValue [10, 20, 50, 100]
+     */
     pageSizeOptions?: number[];
-    /** Enables row editing. Return `{ ok:false, errors }` to keep the row open. */
+    /**
+     * Enables row editing. Called when the user commits a row.
+     *
+     * Return `{ ok: false, errors }` to keep the row open and paint each message
+     * onto the cell whose column id it is keyed by.
+     *
+     * @param draft - The edited copy.
+     * @param original - The row as it was before editing.
+     * @see {@link RowCommitResult}
+     */
     onRowCommit?: (draft: T, original: T) => Promise<RowCommitResult> | RowCommitResult;
+    /**
+     * Called whenever the selection changes.
+     * @param ids - Every selected row id, including rows on other pages.
+     */
     onSelectionChanged?: (ids: RowId[]) => void;
     /** Enables dropping files onto a row (e.g. to attach documents to it). */
     onRowFilesDropped?: (row: T, files: File[]) => void;
+    /**
+     * Called when a fetch or a commit throws. Aborted requests are not reported.
+     */
     onError?: (error: unknown) => void;
-    /** Rendered above the header; receives the live api. */
+    /**
+     * Rendered into the toolbar strip above the header, left of the built-in
+     * Columns and Export CSV buttons.
+     *
+     * @param api - The live imperative API.
+     */
     toolbar?: (api: GridApi<T>) => ReactNode;
+    /**
+     * Shown when a query returns no rows.
+     * @defaultValue 'No rows'
+     */
     emptyMessage?: ReactNode;
+    /**
+     * Base file name for CSV export, without the extension.
+     * @defaultValue 'export'
+     */
     exportFileName?: string;
+    /** Extra classes on the grid's outer frame. */
     className?: string;
-    /** Height of the scrolling area. Defaults to `70vh`. */
+    /**
+     * Height of the whole grid. Any CSS length; a number is treated as pixels.
+     * @defaultValue '70vh'
+     */
     height?: number | string;
+    /**
+     * Receives the imperative {@link GridApi}. Accepts a ref object or a
+     * callback ref.
+     */
     apiRef?: Ref<GridApi<T>>;
 }
+/**
+ * A virtualized, server-driven data grid.
+ *
+ * Paging, sorting and filtering are all resolved by your
+ * {@link HxDataSource | data source} — the grid holds one page at a time and
+ * never filters or sorts locally. Rows are windowed at a fixed height, so the
+ * DOM stays small regardless of the result set.
+ *
+ * @typeParam T - The row type.
+ * @typeParam C - The context type, inferred from the `context` prop.
+ *
+ * @example Minimal usage
+ * ```tsx
+ * const columns: ColumnDef<Person>[] = [
+ *   { field: 'name',  header: 'Name', flex: 1, filter: 'text' },
+ *   { field: 'email', header: 'Email', flex: 1 },
+ * ];
+ *
+ * function People() {
+ *   const dataSource = useMemo(
+ *     () => ({ getRows: (request, signal) => api.list(request, signal) }),
+ *     []
+ *   );
+ *
+ *   return (
+ *     <DataGrid
+ *       columns={columns}
+ *       dataSource={dataSource}
+ *       getRowId={(row) => row.id}
+ *     />
+ *   );
+ * }
+ * ```
+ *
+ * @example With editing, persistence and the imperative API
+ * ```tsx
+ * const apiRef = useRef<GridApi<Person>>(null);
+ *
+ * <DataGrid
+ *   columns={columns}
+ *   dataSource={dataSource}
+ *   getRowId={(row) => row.id}
+ *   storageKey="people"
+ *   apiRef={apiRef}
+ *   onRowCommit={async (draft) => {
+ *     const result = await api.save(draft);
+ *     return result.ok ? { ok: true } : { ok: false, errors: result.errors };
+ *   }}
+ *   toolbar={(api) => (
+ *     <button onClick={() => api.refresh({ purge: true })}>Refresh</button>
+ *   )}
+ * />
+ * ```
+ *
+ * @remarks
+ * Styling is plain Tailwind utility classes — there is no stylesheet to import.
+ * Tailwind skips `node_modules` when detecting content, so point it at the
+ * shipped bundle explicitly:
+ *
+ * ```css
+ * @import "tailwindcss";
+ * @source "../node_modules/@helix-x/datagrid-ui/dist/index.js";
+ * ```
+ *
+ * @see {@link DataGridProps} for every option.
+ * @see {@link GridApi} for what `apiRef` and `toolbar` receive.
+ */
 declare function DataGrid<T, C = unknown>({ columns, dataSource, getRowId, context, storageKey, rowHeight, headerHeight, floatingFilter, selectable, defaultPageSize, pageSizeOptions, onRowCommit, onSelectionChanged, onRowFilesDropped, onError, toolbar, emptyMessage, exportFileName, className, height, apiRef, }: DataGridProps<T, C>): react.JSX.Element;
 
+/** Props for {@link GridPagination}. */
 interface GridPaginationProps {
+    /** Zero-based current page. */
     page: number;
+    /** Rows per page. */
     pageSize: number;
+    /** Total across all pages. `-1` when the server reported it as unknown. */
     totalRows: number;
+    /** Page sizes to offer in the selector. */
     pageSizeOptions: number[];
+    /** Disables the controls while a fetch is in flight. */
     isLoading: boolean;
+    /** Called with the new zero-based page index. */
     onPageChange: (page: number) => void;
+    /** Called with the new page size. */
     onPageSizeChange: (pageSize: number) => void;
 }
+/**
+ * The grid's pager: range summary, page size selector and navigation.
+ *
+ * {@link DataGrid} renders this itself. It is exported for apps that build a
+ * custom surface on the same hooks.
+ */
 declare function GridPagination({ page, pageSize, totalRows, pageSizeOptions, isLoading, onPageChange, onPageSizeChange, }: GridPaginationProps): react.JSX.Element;
 
+/** Props for {@link GridOverlay}. */
 interface GridOverlayProps {
+    /** Which state to show. */
     kind: 'loading' | 'empty' | 'error';
+    /** Message body. Falls back to a default per `kind`. */
     message?: ReactNode;
 }
 /**
- * Sits over the row area rather than replacing it, so the header and column
- * widths stay put while a refetch is in flight.
+ * The loading, empty and error states shown over the row area.
+ *
+ * Overlays rather than replaces, so the header and column widths stay put while
+ * a refetch is in flight.
+ *
+ * @param props - Which state to show, and the message.
  */
 declare function GridOverlay({ kind, message }: GridOverlayProps): react.JSX.Element;
 
+/**
+ * Props for {@link ColumnsPanel}.
+ *
+ * @typeParam T - The row type.
+ * @typeParam C - The context type.
+ */
 interface ColumnsPanelProps<T, C> {
+    /** Every column, including hidden ones. */
     columns: ResolvedColumn<T, C>[];
+    /** Whether a column is currently hidden. */
     isHidden: (colId: string) => boolean;
+    /** Show or hide one column. */
     onToggle: (colId: string, hidden: boolean) => void;
+    /** Move a column to a new index. */
     onMove: (colId: string, toIndex: number) => void;
+    /** Pin a column, or `undefined` to unpin. */
     onPin: (colId: string, pinned: Pinned | undefined) => void;
+    /** Discard the user's layout. */
     onReset: () => void;
+    /** Dismiss the panel. */
     onClose: () => void;
 }
-/** Show/hide, reorder and pin, plus the "reset my preferences" escape hatch. */
+/**
+ * The side panel for showing, hiding, reordering and pinning columns, with the
+ * "reset my preferences" escape hatch.
+ *
+ * {@link DataGrid} renders this from its toolbar; exported for custom surfaces.
+ */
 declare function ColumnsPanel<T, C>({ columns, isHidden, onToggle, onMove, onPin, onReset, onClose, }: ColumnsPanelProps<T, C>): react.JSX.Element;
 
+/** Props for {@link FilterPopover}. */
 interface FilterPopoverProps {
+    /** Which filter UI to render. */
     kind: FilterKind;
+    /** The column's current filter, or `undefined` when unfiltered. */
     value: HxFilterModel | undefined;
+    /**
+     * Options for a `set` filter: a static list, or a loader called the first
+     * time the popover opens.
+     */
     setValues?: string[] | (() => Promise<string[]>);
+    /** Called with the new filter, or `null` to clear the column's filter. */
     onApply: (filter: HxFilterModel | null) => void;
+    /** Dismiss the popover. */
     onClose: () => void;
 }
 /** Header filter menu. Emits the wire-format model directly. */
+/**
+ * The per-column filter editor, covering all four
+ * {@link FilterKind | filter kinds}.
+ *
+ * {@link DataGrid} opens this from the header; exported for custom surfaces.
+ */
 declare function FilterPopover({ kind, value, setValues, onApply, onClose, }: FilterPopoverProps): react.JSX.Element;
 
+/**
+ * Single-line text input. The default editor when a column sets
+ * `editable: true` without naming one.
+ *
+ * Reads `editorParams.placeholder`.
+ */
 declare function TextEditor<T, C>({ value, onChange, onCommit, onCancel, error, autoFocus, column, }: EditorParams<T, C>): react.JSX.Element;
+/**
+ * Numeric input. Writes a `number`, or `null` when the field is cleared, so an
+ * empty cell is never stored as `NaN` or `''`.
+ *
+ * Reads `editorParams.placeholder`.
+ */
 declare function NumberEditor<T, C>({ value, onChange, onCommit, onCancel, error, autoFocus, }: EditorParams<T, C>): react.JSX.Element;
+/**
+ * Native date input. Reads and writes `YYYY-MM-DD` strings, matching
+ * {@link DateFilterModel}.
+ */
 declare function DateEditor<T, C>({ value, onChange, onCommit, onCancel, error, autoFocus, }: EditorParams<T, C>): react.JSX.Element;
+/**
+ * Dropdown over `editorParams.options`. Values round-trip by identity, so a
+ * non-string option value is preserved rather than stringified.
+ */
 declare function SelectEditor<T, C>({ value, onChange, onCommit, onCancel, error, autoFocus, column, }: EditorParams<T, C>): react.JSX.Element;
+/** Boolean checkbox. Writes `true` or `false`, never `undefined`. */
 declare function CheckboxEditor<T, C>({ value, onChange, onCommit, onCancel, autoFocus, }: EditorParams<T, C>): react.JSX.Element;
 
-/** Maps a `ColumnDef.editor` string to its component. */
+/**
+ * Maps a {@link BuiltinEditor} name to its component.
+ *
+ * Look one up to reuse it inside a custom editor, or to check which names are
+ * available.
+ *
+ * @example
+ * ```tsx
+ * const Base = BUILTIN_EDITORS.text;
+ * const UppercaseEditor: EditorComponent<Row> = (params) => (
+ *   <Base {...params} onChange={(v) => params.onChange(String(v).toUpperCase())} />
+ * );
+ * ```
+ */
 declare const BUILTIN_EDITORS: {
+    /** Single-line text input. See {@link TextEditor}. */
     readonly text: typeof TextEditor;
+    /** Numeric input that writes `null` when cleared. See {@link NumberEditor}. */
     readonly number: typeof NumberEditor;
+    /** Native date input over `YYYY-MM-DD`. See {@link DateEditor}. */
     readonly date: typeof DateEditor;
+    /** Dropdown over `editorParams.options`. See {@link SelectEditor}. */
     readonly select: typeof SelectEditor;
+    /** Boolean checkbox. See {@link CheckboxEditor}. */
     readonly checkbox: typeof CheckboxEditor;
 };
 
+/** What {@link useGridState} returns. */
 interface UseGridStateResult {
-    /** Read once on mount; never re-read, so it is safe as an initial value. */
+    /**
+     * The restored state, read once on mount and never re-read — so it is safe
+     * to use as a `useState` initial value. `undefined` when nothing was saved
+     * or the saved schema version did not match.
+     */
     initial: PersistedGridState | undefined;
+    /** Persist the column layout. */
     saveColumns: (columns: PersistedGridState['columns']) => void;
+    /** Persist the sort model. */
     saveSort: (sort: SortModelItem[]) => void;
+    /** Persist the filter model. */
     saveFilters: (filters: FilterModelMap) => void;
+    /** Persist the page size. */
     savePageSize: (pageSize: number) => void;
+    /** Delete the saved state entirely. */
     clear: () => void;
+    /** Whether anything was restored on mount. */
     hasSavedState: boolean;
 }
-/** Versioned, lean localStorage persistence for one grid. */
+/**
+ * Versioned `localStorage` persistence for one grid's layout.
+ *
+ * Writes go through a ref, so saving never causes a re-render. Every read and
+ * write is wrapped: a quota error or a privacy mode degrades to not persisting
+ * rather than throwing, and state saved under a different
+ * {@link GRID_STATE_VERSION} is discarded rather than migrated.
+ *
+ * @param storageKey - Key to store under, namespaced as `hxg:<storageKey>`.
+ * Pass `undefined` to disable persistence entirely.
+ * @returns The restored state and its setters.
+ */
 declare function useGridState(storageKey: string | undefined): UseGridStateResult;
 
+/**
+ * Options for {@link useServerDataSource}.
+ *
+ * @typeParam T - The row type.
+ */
 interface UseServerDataSourceOptions<T> {
+    /** Where rows come from. Memoise it, or every render refetches. */
     dataSource: HxDataSource<T>;
+    /** Rows per page. */
     pageSize: number;
+    /** Zero-based page index. */
     page: number;
+    /** Active sorts, primary first. */
     sortModel: SortModelItem[];
+    /** Active filters, keyed by column id. */
     filterModel: FilterModelMap;
-    /** Blocks to keep around so paging back and forth does not refetch. */
+    /**
+     * Blocks to keep around so paging back and forth does not refetch.
+     * @defaultValue 3
+     */
     maxCachedBlocks?: number;
+    /** Called when a fetch throws. Aborted requests are not reported. */
     onError?: (error: unknown) => void;
 }
+/**
+ * What {@link useServerDataSource} returns.
+ *
+ * @typeParam T - The row type.
+ */
 interface UseServerDataSourceResult<T> {
+    /** Rows for the current page. Empty while the first fetch is in flight. */
     rows: T[];
+    /** Total across all pages, from the response's `lastRow`. */
     totalRows: number;
+    /** True while a fetch is in flight. */
     isLoading: boolean;
+    /** The last error, or `null`. */
     error: unknown;
+    /**
+     * Re-fetch the current page.
+     * @param options - `purge: true` drops every cached block first.
+     */
     refresh: (options?: {
         purge?: boolean;
     }) => void;
-    /** Patch loaded rows in place, keyed by the grid's row id. */
+    /**
+     * Patch loaded rows in place, matched by id. Ids that are not loaded are
+     * ignored. No network request is made.
+     */
     patchRows: (rows: T[], getRowId: (row: T) => string | number) => void;
 }
 /**
  * Server-side paging with a small block cache.
  *
- * Two things here that the ag-grid screen this replaces did not do: every
- * request carries an AbortController and a sequence number, so a slow response
- * for an old sort/filter can never overwrite a newer one; and the cache is
- * dropped wholesale when the query changes, so stale blocks are never mixed
+ * {@link DataGrid} uses this internally; call it directly only when building a
+ * custom surface on top of the same data contract.
+ *
+ * @typeParam T - The row type.
+ * @param options - Data source, page, sort and filters.
+ * @returns The current page plus loading state and imperative helpers.
+ *
+ * @remarks
+ * Every request carries an `AbortController` and a sequence number, so a slow
+ * response for an old sort or filter can never overwrite a newer one. The cache
+ * is dropped wholesale when the query changes, so stale blocks are never mixed
  * with fresh ones.
+ *
+ * @example
+ * ```ts
+ * const { rows, totalRows, isLoading, refresh } = useServerDataSource({
+ *   dataSource,
+ *   page: 0,
+ *   pageSize: 50,
+ *   sortModel: [{ colId: 'name', sort: 'asc' }],
+ *   filterModel: {},
+ * });
+ * ```
  */
 declare function useServerDataSource<T>({ dataSource, pageSize, page, sortModel, filterModel, maxCachedBlocks, onError, }: UseServerDataSourceOptions<T>): UseServerDataSourceResult<T>;
 
+/** The slice of rows currently worth rendering. */
 interface VirtualWindow {
+    /** First row index to render, inclusive. Includes overscan. */
     startIndex: number;
+    /** Index one past the last row to render, exclusive. */
     endIndex: number;
 }
+/** Options for {@link useVirtualRows}. */
 interface UseVirtualRowsOptions {
+    /** How many rows exist in the current page. */
     rowCount: number;
+    /** Fixed height of every row, in pixels. */
     rowHeight: number;
+    /**
+     * Extra rows rendered above and below the viewport, so fast scrolling does
+     * not show blank space.
+     * @defaultValue 6
+     */
     overscan?: number;
 }
+/** What {@link useVirtualRows} returns. */
 interface UseVirtualRowsResult {
+    /** The rows to render right now. */
     window: VirtualWindow;
+    /** `rowCount * rowHeight` — the spacer height that gives the correct scrollbar. */
     totalHeight: number;
-    /** Attach to the scrolling element. */
+    /** Attach to the scrolling element's `onScroll`. */
     onScroll: (event: {
         currentTarget: HTMLElement;
     }) => void;
     /** Call when the viewport is measured or resized. */
     setViewportHeight: (height: number) => void;
+    /** Live scroll offset, readable without causing a re-render. */
     scrollTopRef: React.RefObject<number>;
 }
 /**
  * Fixed-height row windowing.
  *
+ * @param options - Row count, row height and overscan.
+ * @returns The visible window plus the handlers that maintain it.
+ *
+ * @remarks
  * Fixed heights are a deliberate constraint: they make the visible range O(1)
  * to compute and remove the measure-then-reflow pass that variable heights
  * force. Scroll position is tracked in a ref and only promoted to state when
- * the computed window actually changes, so scrolling within a row does not
- * re-render anything.
+ * the computed window actually changes, so scrolling within a single row
+ * re-renders nothing.
+ *
+ * @example
+ * ```tsx
+ * const { window, totalHeight, onScroll, setViewportHeight } = useVirtualRows({
+ *   rowCount: rows.length,
+ *   rowHeight: 36,
+ * });
+ *
+ * <div onScroll={onScroll} style={{ overflow: 'auto' }}>
+ *   <div style={{ height: totalHeight }}>
+ *     {rows.slice(window.startIndex, window.endIndex).map(renderRow)}
+ *   </div>
+ * </div>
+ * ```
  */
 declare function useVirtualRows({ rowCount, rowHeight, overscan, }: UseVirtualRowsOptions): UseVirtualRowsResult;
 
+/** The user's column layout, as persisted. */
 interface ColumnStateValue {
+    /** Column ids in display order. */
     order: string[];
+    /** Ids of hidden columns. */
     hidden: string[];
+    /** Widths in pixels, by column id. */
     widths: Record<string, number>;
+    /** Pinned edge, by column id. */
     pinned: Record<string, Pinned>;
 }
+/**
+ * What {@link useColumnState} returns.
+ *
+ * @typeParam T - The row type.
+ * @typeParam C - The context type.
+ */
 interface UseColumnStateResult<T, C> {
     /** Every column, in user order, including hidden ones (for the columns panel). */
     allColumns: ResolvedColumn<T, C>[];
+    /** Just the visible columns, in display order. */
     visibleColumns: ResolvedColumn<T, C>[];
+    /** Measured geometry for the visible columns. */
     layout: ColumnLayout<T, C>;
+    /** The raw layout state, ready to persist. */
     state: ColumnStateValue;
+    /** Whether a column is hidden. */
     isHidden: (colId: string) => boolean;
+    /** Show or hide one column. */
     setHidden: (colId: string, hidden: boolean) => void;
+    /** Resize one column. Clamped to its `minWidth` and `maxWidth`. */
     setWidth: (colId: string, width: number) => void;
+    /** Pin one column to an edge, or pass `undefined` to unpin it. */
     setPinned: (colId: string, pinned: Pinned | undefined) => void;
+    /** Move a column to a new index in the display order. */
     moveColumn: (colId: string, toIndex: number) => void;
+    /** Discard the user's layout and return to the column definitions' defaults. */
     reset: () => void;
 }
+/**
+ * Column order, visibility, width and pinning, merged over the definitions'
+ * defaults.
+ *
+ * Persisted state is merged key by key rather than replacing the defaults
+ * wholesale — so a layout saved before a new column was added does not hide
+ * that column, and does not discard defaults it says nothing about.
+ *
+ * @typeParam T - The row type.
+ * @typeParam C - The context type.
+ * @returns The resolved columns, their layout, and the mutators.
+ */
 declare function useColumnState<T, C>(columns: ColumnDef<T, C>[], persisted: PersistedGridState['columns'] | undefined, onChange: (state: ColumnStateValue) => void, availableWidth: number): UseColumnStateResult<T, C>;
 
+/**
+ * The row currently being edited.
+ *
+ * @typeParam T - The row type.
+ */
 interface EditState<T> {
+    /** Which row is open. */
     rowId: RowId;
+    /** The working copy, updated as the user types. */
     draft: T;
+    /** The row as it was when editing started, for cancel and for the commit callback. */
     original: T;
+    /** Server-supplied messages from the last rejected commit, keyed by column id. */
     errors: Record<string, string>;
+    /** True while a commit is in flight. */
     isSaving: boolean;
 }
+/**
+ * What {@link useEditModel} returns.
+ *
+ * @typeParam T - The row type.
+ */
 interface UseEditModelResult<T> {
+    /** The open row, or `null` when nothing is being edited. */
     edit: EditState<T> | null;
+    /** Whether a given row is the one currently open. */
     isEditing: (rowId: RowId) => boolean;
+    /** Open a row for editing, replacing any row already open. */
     start: (rowId: RowId, row: T) => void;
+    /**
+     * Write one field into the draft. Accepts a dotted path, creating
+     * intermediate objects as needed.
+     */
     setField: (field: string, value: unknown) => void;
+    /** Close without saving, discarding the draft. */
     cancel: () => void;
+    /** Run the commit callback. Keeps the row open if it returns `ok: false`. */
     commit: () => Promise<void>;
 }
 /**
  * Row-level editing against a draft copy.
  *
- * The draft never touches the data source, and the editors never call an API --
- * the single `onCommit` callback owns validation and persistence, so the app can
- * plug in whatever schema library it uses without the grid knowing about it.
+ * @typeParam T - The row type.
+ * @param onCommit - Owns validation and persistence. Return
+ * `{ ok: false, errors }` to keep the row open with per-field messages.
+ * @returns The edit state and its mutators.
+ *
+ * @remarks
+ * The draft never touches the data source, and editors never call an API — the
+ * single commit callback owns both, so an app can plug in whatever schema
+ * library it uses without the grid knowing about it.
+ *
+ * @see {@link RowCommitResult}
  */
 declare function useEditModel<T>(onCommit: (draft: T, original: T) => Promise<RowCommitResult> | RowCommitResult): UseEditModelResult<T>;
 
 /**
- * Resolves a cell value.
+ * Resolves a cell's raw value from its row.
+ *
+ * Tries, in order: {@link ColumnDef.valueGetter}, the dotted `field` path, the
+ * literal flat key, then each {@link ColumnDef.fieldAliases | alias}.
+ *
+ * @remarks
+ * The fallbacks exist because servers that flatten joined relations hand back
+ * `{"customer.businessName": x}` rather than a nested object — and some change
+ * the prefix when grouping is on.
  *
- * Servers that flatten joined relations hand back `{"customer.businessName": x}`
- * rather than a nested object -- and some flatten with a different prefix when
- * grouping is on. So: explicit getter, then the dotted path, then the literal
- * flat key, then any declared aliases.
+ * @param row - The row to read from.
+ * @param column - The column describing what to read.
+ * @returns The raw value, or `undefined` if nothing matched.
+ *
+ * @example
+ * ```ts
+ * resolveValue({ customer: { name: 'Acme' } }, { field: 'customer.name', header: 'C' });
+ * // 'Acme'
+ * ```
  */
 declare function resolveValue<T>(row: T, column: ColumnDef<T, never>): unknown;
-/** The display string for a cell, independent of any custom renderer. */
+/**
+ * The display string for a cell, independent of any custom renderer.
+ *
+ * Uses {@link ColumnDef.valueFormatter} when present. Otherwise `null` and
+ * `undefined` become `''`, `Date` becomes `YYYY-MM-DD`, booleans become
+ * `Yes`/`No`, and everything else is stringified.
+ *
+ * @param value - The raw value, usually from {@link resolveValue}.
+ * @param row - The row it came from, passed to the formatter.
+ * @param column - The column being formatted.
+ * @returns The display string.
+ */
 declare function formatValue<T>(value: unknown, row: T, column: ColumnDef<T, never>): string;
-/** The string written to CSV / clipboard for a cell. */
+/**
+ * The string written to CSV and the clipboard for a cell.
+ *
+ * Prefers {@link ColumnDef.exportValue}, falling back to {@link formatValue} —
+ * which is why a column with a markup `cellRenderer` should supply one.
+ *
+ * @param row - The row to export.
+ * @param column - The column being exported.
+ * @returns The flat string for this cell.
+ */
 declare function exportValue<T>(row: T, column: ColumnDef<T, never>): string;
-/** Plain-text header, for exports and aria labels. */
+/**
+ * Plain-text header, for exports and aria labels.
+ *
+ * Prefers {@link ColumnDef.headerName}, then a string or numeric `header`, then
+ * falls back to the column id.
+ *
+ * @param column - The column to label.
+ * @returns The header as plain text, or `''` if nothing usable was found.
+ */
 declare function headerText<T>(column: ColumnDef<T, never>): string;
+/**
+ * The stable id for a column: `colId`, or `field` when `colId` was omitted.
+ *
+ * @param column - The column to identify.
+ * @returns The column id.
+ * @throws If the column has neither `colId` nor `field`.
+ */
 declare function columnId<T, C>(column: ColumnDef<T, C>): string;
-/** Fills in the defaults every other module assumes are present. */
+/**
+ * Fills in the defaults every other module assumes are present.
+ *
+ * Width defaults to 150 (never below `minWidth`), `minWidth` to 60, and both
+ * `sortable` and `resizable` to `true`.
+ *
+ * @param column - The column as authored.
+ * @returns The same column with required fields resolved.
+ */
 declare function resolveColumn<T, C>(column: ColumnDef<T, C>): ResolvedColumn<T, C>;
+/**
+ * Whether a specific row's cell is editable in this column.
+ *
+ * @param column - The column to test.
+ * @param row - The row to test, for a predicate `editable`.
+ * @returns `true` when the cell can be edited.
+ */
 declare function isEditable<T, C>(column: ColumnDef<T, C>, row: T): boolean;
 
 /**
- * Every wire-format filter shape is built here, so the contract with the server
- * is defined in exactly one place.
+ * Builders and helpers for the wire-format filter shapes.
+ *
+ * Every filter the grid sends is constructed here, so the contract with the
+ * server is defined in exactly one place.
  */
+/** Every text operator, in the order the filter UI lists them. */
 declare const TEXT_FILTER_TYPES: TextFilterType[];
+/** Every numeric operator, in the order the filter UI lists them. */
 declare const NUMBER_FILTER_TYPES: NumberFilterType[];
+/** Every date operator, in the order the filter UI lists them. */
 declare const DATE_FILTER_TYPES: DateFilterType[];
+/**
+ * Human-readable label for each operator, e.g. `notEqual` → `'Not equal'`.
+ *
+ * Replace an entry to relabel an operator throughout the filter UI.
+ */
 declare const FILTER_TYPE_LABELS: Record<string, string>;
-/** Filter types that need no operand. */
+/**
+ * Whether an operator takes no operand — `blank` and `notBlank`.
+ *
+ * @param type - The operator name.
+ * @returns `true` when no value is needed.
+ */
 declare function isUnaryFilter(type: string): boolean;
+/**
+ * Whether an operator takes two operands — currently only `inRange`.
+ *
+ * @param type - The operator name.
+ * @returns `true` when both bounds are needed.
+ */
 declare function isRangeFilter(type: string): boolean;
+/**
+ * The operator a filter starts on when its popover is first opened.
+ *
+ * `contains` for text, `equals` for numbers and dates.
+ *
+ * @param kind - The filter kind.
+ * @returns The default operator name.
+ */
 declare function defaultFilterType(kind: FilterKind): string;
+/**
+ * Builds a text filter, or `null` when there is nothing to send.
+ *
+ * @param type - The operator.
+ * @param filter - The search term. Ignored for unary operators.
+ * @returns The filter model, or `null` if a non-unary operator got a blank term.
+ *
+ * @example
+ * ```ts
+ * buildTextFilter('contains', 'acme');
+ * // { filterType: 'text', type: 'contains', filter: 'acme' }
+ * buildTextFilter('contains', '   '); // null
+ * ```
+ */
 declare function buildTextFilter(type: TextFilterType, filter: string): HxFilterModel | null;
+/**
+ * Builds a numeric filter, or `null` when the input is incomplete.
+ *
+ * @param type - The operator.
+ * @param filter - The operand, or lower bound for `inRange`, as typed.
+ * @param filterTo - The upper bound. Required for `inRange`.
+ * @returns The filter model, or `null` if a required operand is missing or not
+ * a number.
+ *
+ * @example
+ * ```ts
+ * buildNumberFilter('inRange', '10', '100');
+ * // { filterType: 'number', type: 'inRange', filter: 10, filterTo: 100 }
+ * buildNumberFilter('inRange', '10'); // null — no upper bound
+ * ```
+ */
 declare function buildNumberFilter(type: NumberFilterType, filter: string, filterTo?: string): HxFilterModel | null;
+/**
+ * Builds a date filter, or `null` when the input is incomplete.
+ *
+ * @param type - The operator.
+ * @param dateFrom - Lower bound, formatted `YYYY-MM-DD`.
+ * @param dateTo - Upper bound. Required for `inRange`.
+ * @returns The filter model, or `null` if a required bound is missing.
+ */
 declare function buildDateFilter(type: DateFilterType, dateFrom: string, dateTo?: string): HxFilterModel | null;
+/**
+ * Builds a set filter, or `null` when nothing is selected.
+ *
+ * Returning `null` rather than an empty set is what clears the filter — see
+ * {@link withFilter}.
+ *
+ * @param values - The selected values.
+ * @returns The filter model, or `null` for an empty selection.
+ */
 declare function buildSetFilter(values: string[]): HxFilterModel | null;
-/** Sets or clears one column's entry, returning a new map. */
+/**
+ * Sets or clears one column's filter, returning a new map.
+ *
+ * Never mutates the map it is given, so the result is safe to hand straight to
+ * `setState`.
+ *
+ * @param model - The current filter model.
+ * @param colId - The column to change.
+ * @param filter - The new filter, or `null` to remove the column's entry.
+ * @returns A new filter model.
+ *
+ * @example
+ * ```ts
+ * const next = withFilter(filterModel, 'status', buildSetFilter(['ACTIVE']));
+ * const cleared = withFilter(filterModel, 'status', null);
+ * ```
+ */
 declare function withFilter(model: FilterModelMap, colId: string, filter: HxFilterModel | null): FilterModelMap;
-/** A short label for the floating filter / header indicator. */
+/**
+ * A short human-readable summary of a filter, for the floating filter input and
+ * the header's active-filter indicator.
+ *
+ * @param filter - The filter to describe.
+ * @returns A short label, e.g. `'Between 10 - 100'` or `'3 selected'`.
+ */
 declare function describeFilter(filter: HxFilterModel): string;
 
+/**
+ * Serialises rows to delimited text with a header line.
+ *
+ * Values are quoted per RFC 4180 when they contain the separator, a quote or a
+ * newline. Columns marked {@link ColumnDef.suppressExport} are skipped, and
+ * lines are joined with CRLF.
+ *
+ * @param rows - The rows to serialise.
+ * @param columns - Columns to include, in output order.
+ * @param separator - The field separator.
+ * @returns The delimited document.
+ */
 declare function toDelimited<T>(rows: T[], columns: Array<ResolvedColumn<T, never> | ColumnDef<T, never>>, separator: string): string;
+/**
+ * Serialises rows to CSV.
+ *
+ * @param rows - The rows to serialise.
+ * @param columns - Columns to include, in output order.
+ * @param separator - Field separator.
+ * @returns The CSV document, without a BOM — {@link downloadCsv} adds one.
+ *
+ * @example
+ * ```ts
+ * const csv = toCsv(api.getSelectedRows(), columns);
+ * ```
+ */
 declare function toCsv<T>(rows: T[], columns: Array<ResolvedColumn<T, never> | ColumnDef<T, never>>, separator?: string): string;
-/** Tab-separated, which is what spreadsheets expect from the clipboard. */
+/**
+ * Serialises rows to tab-separated text, which is what spreadsheets expect to
+ * receive from the clipboard.
+ *
+ * @param rows - The rows to serialise.
+ * @param columns - Columns to include, in output order.
+ * @returns The TSV document.
+ */
 declare function toTsv<T>(rows: T[], columns: Array<ResolvedColumn<T, never> | ColumnDef<T, never>>): string;
+/**
+ * Triggers a browser download of CSV content.
+ *
+ * A UTF-8 BOM is prepended, which is what makes Excel read the file as UTF-8
+ * rather than ANSI. The `.csv` extension is added if missing.
+ *
+ * @param content - The CSV document, e.g. from {@link toCsv}.
+ * @param fileName - File name, with or without the extension.
+ */
 declare function downloadCsv(content: string, fileName: string): void;
+/**
+ * Copies text to the clipboard, falling back to a hidden `textarea` on browsers
+ * and non-secure origins without the async clipboard API.
+ *
+ * @param text - The text to copy.
+ */
 declare function copyToClipboard(text: string): Promise<void>;
 
-export { BUILTIN_EDITORS, type BuiltinEditor, type CellRendererParams, CheckboxEditor, type ColumnDef, type ColumnLayout, type ColumnLayoutItem, ColumnsPanel, DATE_FILTER_TYPES, DataGrid, type DataGridProps, DateEditor, type DateFilterModel, type DateFilterType, type EditorComponent, type EditorParams, type ExportCsvOptions, FILTER_TYPE_LABELS, type FilterKind, type FilterModelMap, FilterPopover, GRID_STATE_VERSION, type GridApi, GridOverlay, GridPagination, type HxDataSource, type HxFilterModel, type HxRowsRequest, type HxRowsResponse, NUMBER_FILTER_TYPES, NumberEditor, type NumberFilterModel, type NumberFilterType, type PersistedGridState, type Pinned, type ResolvedColumn, type RowCommitResult, type RowId, SelectEditor, type SelectOption, type SetFilterModel, type SortDirection, type SortModelItem, TEXT_FILTER_TYPES, TextEditor, type TextFilterModel, type TextFilterType, buildDateFilter, buildNumberFilter, buildSetFilter, buildTextFilter, columnId, copyToClipboard, defaultFilterType, describeFilter, downloadCsv, exportValue, formatValue, headerText, isEditable, isRangeFilter, isUnaryFilter, resolveColumn, resolveValue, toCsv, toDelimited, toTsv, useColumnState, useEditModel, useGridState, useSelectionModel, useServerDataSource, useVirtualRows, withFilter };
+export { BUILTIN_EDITORS, type BuiltinEditor, type CellRendererParams, CheckboxEditor, type ColumnDef, type ColumnLayout, type ColumnLayoutItem, type ColumnStateValue, ColumnsPanel, type ColumnsPanelProps, DATE_FILTER_TYPES, DataGrid, type DataGridProps, DateEditor, type DateFilterModel, type DateFilterType, type EditState, type EditorComponent, type EditorParams, type ExportCsvOptions, FILTER_TYPE_LABELS, type FilterKind, type FilterModelMap, FilterPopover, type FilterPopoverProps, GRID_STATE_VERSION, type GridApi, GridOverlay, type GridOverlayProps, GridPagination, type GridPaginationProps, type HxDataSource, type HxFilterModel, type HxRowsRequest, type HxRowsResponse, NUMBER_FILTER_TYPES, NumberEditor, type NumberFilterModel, type NumberFilterType, type PersistedGridState, type Pinned, type ResolvedColumn, type RowCommitResult, type RowId, SelectEditor, type SelectOption, type SetFilterModel, type SortDirection, type SortModelItem, TEXT_FILTER_TYPES, TextEditor, type TextFilterModel, type TextFilterType, type UseColumnStateResult, type UseEditModelResult, type UseGridStateResult, type UseSelectionModelResult, type UseServerDataSourceOptions, type UseServerDataSourceResult, type UseVirtualRowsOptions, type UseVirtualRowsResult, type VirtualWindow, buildDateFilter, buildNumberFilter, buildSetFilter, buildTextFilter, columnId, copyToClipboard, defaultFilterType, describeFilter, downloadCsv, exportValue, formatValue, headerText, isEditable, isRangeFilter, isUnaryFilter, resolveColumn, resolveValue, toCsv, toDelimited, toTsv, useColumnState, useEditModel, useGridState, useSelectionModel, useServerDataSource, useVirtualRows, withFilter };