eidos-ui 1.2.0 → 2.1.0

package/dist/data-grid/index.d.cts

@@ -1,16 +1,18 @@
 import React__default from 'react';
 import { I as IconType } from '../renderIcon-C2lEMMzb.cjs';
+import { R as RowKey, e as TableFilters, B as BulkAction } from '../Table.types-CPj-udMc.cjs';
+export { a as BulkActionButton, b as BulkActionSplitButton, c as BulkActionSplitOption } from '../Table.types-CPj-udMc.cjs';
 import { C as ComboboxOption } from '../Combobox.types-B7ozlnA9.cjs';
 import { b as MenuItemType } from '../Menu.types-DwcuCZM7.cjs';
 import { S as SelectOption } from '../Select.types-CAkT2ACt.cjs';
 import { b as SegmentedOption, S as SegmentedControlColorProps } from '../SegmentedControl.types-Dm4SnwCK.cjs';
-import { d as TableFilters, B as BulkAction } from '../Table.types-DQ0ReOLj.cjs';
-export { a as BulkActionButton, b as BulkActionSplitButton, c as BulkActionSplitOption } from '../Table.types-DQ0ReOLj.cjs';
+import '../Button.types-DZRCVqyN.cjs';
 import '../sizes-DM6Rrrgq.cjs';
 import '../Input.types-DFZNyJGF.cjs';
-import '../Button.types-DZRCVqyN.cjs';
 
-type DataGridCellType = 'text' | 'number' | 'select' | 'checkbox' | 'date' | 'readonly' | 'actions';
+type DataGridCellType = 'text' | 'number' | 'select' | 'checkbox' | 'date' | 'readonly' | 'custom' | 'actions';
+/** Cell types that address a row field, i.e. everything but the two escape hatches. */
+type DataGridValueCellType = Exclude<DataGridCellType, 'custom' | 'actions'>;
 interface DataGridSelectOption {
     value: string;
     label: string;
@@ -22,9 +24,15 @@ interface DataGridSelectOption {
  * field (including ones you don't display), without hunting through column
  * definitions to find which ones set a filter flag.
  */
-interface DataGridFilterField {
-    /** Row data key this filter reads/writes. Does not need to match a `columns` entry. */
-    key: string;
+interface DataGridFilterField<T extends object = Record<string, unknown>> {
+    /**
+     * Row data key this filter reads/writes. Does not need to match a `columns`
+     * entry - the decoupling from `columns` is intact, so filtering an
+     * undisplayed field still works. It does have to be a real field of `T`,
+     * because the filter evaluates `row[key]`: a name that isn't on the row
+     * type used to compile fine and then silently match nothing.
+     */
+    key: RowKey<T>;
     label: string;
     /** Filter UI type. @default 'text' */
     filterType?: 'text' | 'select' | 'date' | 'boolean';
@@ -40,9 +48,12 @@ interface DataGridFilterField {
 type DataGridQuickFilterSelectOption = Omit<SelectOption, 'id'>;
 type DataGridQuickFilterComboboxOption = Omit<ComboboxOption, 'id'>;
 type DataGridQuickFilterSegmentedOption = SegmentedOption;
-interface DataGridQuickFilterBase {
-    /** Row data key this filter reads/writes. Does not need to match a `columns` entry. */
-    key: string;
+interface DataGridQuickFilterBase<T extends object = Record<string, unknown>> {
+    /**
+     * Row data key this filter reads/writes. Does not need to match a `columns`
+     * entry, but must be a real field of `T` - the filter evaluates `row[key]`.
+     */
+    key: RowKey<T>;
     /**
      * Short label for the control. The toolbar has no room for a visible field
      * label, so this is used as the control's placeholder and its accessible
@@ -63,7 +74,7 @@ interface DataGridQuickFilterBase {
      */
     defaultValue?: string | string[];
 }
-interface DataGridQuickFilterSelect extends DataGridQuickFilterBase {
+interface DataGridQuickFilterSelect<T extends object = Record<string, unknown>> extends DataGridQuickFilterBase<T> {
     type: 'select';
     options: DataGridQuickFilterSelectOption[];
     /** Select several values at once - writes a `string[]` filter value. @default false */
@@ -73,7 +84,7 @@ interface DataGridQuickFilterSelect extends DataGridQuickFilterBase {
     /** Defaults to `label`. */
     placeholder?: string;
 }
-interface DataGridQuickFilterCombobox extends DataGridQuickFilterBase {
+interface DataGridQuickFilterCombobox<T extends object = Record<string, unknown>> extends DataGridQuickFilterBase<T> {
     type: 'combobox';
     /** Optional so options can be supplied asynchronously via `onSearch`. */
     options?: DataGridQuickFilterComboboxOption[];
@@ -87,7 +98,7 @@ interface DataGridQuickFilterCombobox extends DataGridQuickFilterBase {
     loading?: boolean;
     loadingText?: string;
 }
-interface DataGridQuickFilterSegmented extends DataGridQuickFilterBase {
+interface DataGridQuickFilterSegmented<T extends object = Record<string, unknown>> extends DataGridQuickFilterBase<T> {
     type: 'segmented';
     /**
      * Rendered after the reset segment, which the grid always prepends - a
@@ -104,7 +115,7 @@ interface DataGridQuickFilterSegmented extends DataGridQuickFilterBase {
  * `DataGridProps.quickFilters`. Discriminated on `type`, so each control only
  * accepts the props that actually apply to it.
  */
-type DataGridQuickFilter = DataGridQuickFilterSelect | DataGridQuickFilterCombobox | DataGridQuickFilterSegmented;
+type DataGridQuickFilter<T extends object = Record<string, unknown>> = DataGridQuickFilterSelect<T> | DataGridQuickFilterCombobox<T> | DataGridQuickFilterSegmented<T>;
 /** A single entry in a `type: 'actions'` column's menu - see `DataGridColumn.actions`. */
 interface DataGridRowAction<T = Record<string, unknown>> {
     /** Defaults to `label` if omitted - only needs to be unique within this column's `actions`. */
@@ -118,24 +129,11 @@ interface DataGridRowAction<T = Record<string, unknown>> {
     /** Renders a separator directly above this item. */
     divider?: boolean;
 }
-interface DataGridColumn<T = Record<string, unknown>> {
-    /** Matches the key in the data row object. Unused when `type: 'actions'`, but still required - any placeholder string works. */
-    key: string;
+/** Members every column variant shares, whether or not it addresses a row field. */
+interface DataGridColumnCommon {
     header: string;
-    /** @default 'text' */
-    type?: DataGridCellType;
     width?: number | string;
     minWidth?: number | string;
-    /** @default true */
-    editable?: boolean;
-    /** Show error if cell is left empty */
-    required?: boolean;
-    /** For type='select' */
-    options?: DataGridSelectOption[];
-    /** Return an error string or `true` if valid */
-    validate?: (value: unknown) => string | true;
-    renderCell?: (value: unknown, row: T, rowIndex: number) => React__default.ReactNode;
-    renderEditor?: (value: unknown, onChange: (v: unknown) => void, row: T) => React__default.ReactNode;
     /** Enable click-to-sort on this column */
     sortable?: boolean;
     /**
@@ -149,6 +147,73 @@ interface DataGridColumn<T = Record<string, unknown>> {
     align?: 'left' | 'center' | 'right';
     /** Lock this column to the left or right edge on horizontal scroll */
     pin?: 'left' | 'right';
+    /**
+     * Render this column's value as the card's title instead of a label:value
+     * field row. Only the first column with `cardHeader` set is used - if
+     * several are marked, the rest are silently ignored.
+     */
+    cardHeader?: boolean;
+    /**
+     * Render this column's value as the card's subtitle, directly under the
+     * `cardHeader` value. Only the first column with `cardSubheader` set is
+     * used. Has no effect without a `cardHeader` column also being set.
+     */
+    cardSubheader?: boolean;
+}
+/**
+ * A column bound to the row field named by `key`, which is what makes `value`
+ * knowable: every callback below receives `T[K]` rather than `unknown`.
+ *
+ * Not used directly - `DataGridColumn` distributes this over `keyof T` so each
+ * entry in a `columns` array correlates its own `key` with its own value type.
+ */
+interface DataGridValueColumn<T extends object, K extends RowKey<T>> extends DataGridColumnCommon {
+    /** Matches the key in the data row object. */
+    key: K;
+    /** @default 'text' */
+    type?: DataGridValueCellType;
+    /** @default true */
+    editable?: boolean;
+    /** Show error if cell is left empty */
+    required?: boolean;
+    /** For type='select' */
+    options?: DataGridSelectOption[];
+    /** Return an error string or `true` if valid */
+    validate?: (value: T[K]) => string | true;
+    renderCell?: (value: T[K], row: T, rowIndex: number) => React__default.ReactNode;
+    renderEditor?: (value: T[K], onChange: (v: T[K]) => void, row: T) => React__default.ReactNode;
+}
+/**
+ * A column that renders from the whole row rather than one field - a computed
+ * or composite value (`${row.first} ${row.last}`), a link, a status derived
+ * from several fields. `key` is free-form here because nothing reads
+ * `row[key]`: it's only an identity for React keys, sorting and `data-col-key`.
+ *
+ * This is the home for what used to be expressible by pointing `key` at a
+ * field that didn't exist. Not editable - there is no single field to write
+ * back to - so `editable`, `required`, `validate` and `renderEditor` are all
+ * absent by design.
+ */
+interface DataGridCustomColumn<T extends object> extends DataGridColumnCommon {
+    /** Free-form - must only be unique within `columns`. */
+    key: string;
+    type: 'custom';
+    /**
+     * Required: a custom column has no field to fall back to rendering.
+     * `value` is always `undefined` and exists only to keep the parameter list
+     * aligned with `DataGridValueColumn.renderCell`, so `(_, row) => ...` reads
+     * the same on both.
+     */
+    renderCell: (value: undefined, row: T, rowIndex: number) => React__default.ReactNode;
+}
+/**
+ * The row-actions column. Addresses no field, so it needs no `key` at all -
+ * previously this had to carry a required placeholder string that nothing read.
+ */
+interface DataGridActionsColumn<T extends object> extends DataGridColumnCommon {
+    /** Optional, and unused - only ever an identity for React keys. */
+    key?: string;
+    type: 'actions';
     /**
      * The menu items shown for this row. Required for the column to render
      * anything - a `type: 'actions'` column with no `actions` renders nothing.
@@ -169,24 +234,31 @@ interface DataGridColumn<T = Record<string, unknown>> {
      * ignored.
      */
     renderActions?: (row: T, index: number) => MenuItemType[];
-    /**
-     * Render this column's value as the card's title instead of a label:value
-     * field row. Only the first column with `cardHeader` set is used - if
-     * several are marked, the rest are silently ignored.
-     */
-    cardHeader?: boolean;
-    /**
-     * Render this column's value as the card's subtitle, directly under the
-     * `cardHeader` value. Only the first column with `cardSubheader` set is
-     * used. Has no effect without a `cardHeader` column also being set.
-     */
-    cardSubheader?: boolean;
 }
-interface DataGridProps<T extends Record<string, unknown> = Record<string, unknown>> {
+/**
+ * One column definition. A union of three variants, discriminated on `type`:
+ *
+ * - **value column** (default, `type` omitted or a cell type) - `key` must be a
+ *   field of `T`, and `renderCell`/`renderEditor`/`validate` receive that
+ *   field's type instead of `unknown`.
+ * - **`type: 'custom'`** - renders from the whole row; `key` is free-form.
+ * - **`type: 'actions'`** - the row-actions menu; `key` is optional.
+ *
+ * The value variant is produced by distributing over `RowKey<T>`, which is
+ * what correlates `key` with the value type. Note this keeps a single public
+ * type parameter, so no consumer signature changes.
+ *
+ * With the untyped default `T`, `RowKey<T>` is `string` and `T[K]` is
+ * `unknown`, which is byte-identical to the pre-2.0 behaviour.
+ */
+type DataGridColumn<T extends object = Record<string, unknown>> = {
+    [K in RowKey<T>]: DataGridValueColumn<T, K>;
+}[RowKey<T>] | DataGridCustomColumn<T> | DataGridActionsColumn<T>;
+interface DataGridProps<T extends object = Record<string, unknown>> {
     columns: DataGridColumn<T>[];
     data: T[];
     /** Field name used as React key. @default 'id' */
-    rowKey?: string;
+    rowKey?: RowKey<T>;
     /** Called after each cell commit with the full updated dataset */
     onChange?: (data: T[]) => void;
     /** Returns a blank row object; if omitted, no Add-row button is shown */
@@ -206,11 +278,11 @@ interface DataGridProps<T extends Record<string, unknown> = Record<string, unkno
     onRowReorder?: (newData: T[]) => void;
     /** Controlled sort state. When provided, component is in server-side sort mode. */
     currentSort?: {
-        key: string;
+        key: RowKey<T>;
         direction: 'asc' | 'desc';
     };
     /** Server-side sort callback. When omitted, sorting is handled client-side. */
-    onSortChange?: (key: string, direction: 'asc' | 'desc') => void;
+    onSortChange?: (key: RowKey<T>, direction: 'asc' | 'desc') => void;
     /** Show the filter button in the toolbar. */
     showFilters?: boolean;
     /**
@@ -219,7 +291,7 @@ interface DataGridProps<T extends Record<string, unknown> = Record<string, unkno
      * (including ones that aren't rendered as a column at all), rather than
      * columns each carrying their own filter flag.
      */
-    filterConfig?: DataGridFilterField[];
+    filterConfig?: DataGridFilterField<T>[];
     /** Controlled filter state (the current values, keyed by `filterConfig[].key`). When provided with onFiltersChange → server-side mode. */
     filters?: TableFilters;
     /** Filter change callback. When omitted, filtering is handled client-side. */
@@ -239,7 +311,7 @@ interface DataGridProps<T extends Record<string, unknown> = Record<string, unkno
      * Hidden while rows are selected - the selection count and bulk actions
      * occupy the same toolbar zone.
      */
-    quickFilters?: DataGridQuickFilter[];
+    quickFilters?: DataGridQuickFilter<T>[];
     showPagination?: boolean;
     /** @default 10 */
     pageSize?: number;
@@ -252,7 +324,53 @@ interface DataGridProps<T extends Record<string, unknown> = Record<string, unkno
     /** Controlled selected row keys. */
     selectedRows?: string[];
     defaultSelectedRows?: string[];
+    /**
+     * Fires with every selected key, plus the row object for each of those keys.
+     *
+     * `selectedKeys` is authoritative; `selectedRows` is best-effort. The row
+     * for each selected key is cached, so a row selected on a previous page
+     * still comes back after `data` has moved on (which is what makes selection
+     * usable with server-side pagination) - but a key that was selected before
+     * the grid ever saw its row (seeded via `defaultSelectedRows`, say) has no
+     * row to hand back.
+     */
     onSelectionChange?: (selectedKeys: string[], selectedRows: T[]) => void;
+    /**
+     * What the select-all control acts on - the header checkbox in table mode,
+     * or the toolbar checkbox in card view (where there is no header row):
+     *
+     * - `'all'` - every row in `data`, across pages.
+     * - `'page'` - only the rows currently rendered.
+     *
+     * Either way it only ever adds to or removes from the rows in its own
+     * scope, so a selection made on another page survives.
+     *
+     * `'all'` can only reach the rows the grid actually holds. Under
+     * server-side pagination (`onPageChange` + `totalRows`) that is a single
+     * page: the grid cannot know the keys of rows it has never received, so
+     * "all" means "all 20 loaded", not "all 1000 matching", and it says so with
+     * a dev-only warning. Matches `Table.selectAllScope`.
+     *
+     * @default 'all'
+     */
+    selectAllScope?: 'all' | 'page';
+    /**
+     * Resolves the keys of **every** row matching the current query - the rows
+     * the grid cannot see, not just the loaded page. Supplying it adds a
+     * "Select all N" action to the toolbar once everything the grid does hold is
+     * selected, which is the only way to express "all 1000" when the grid only
+     * ever receives 20 of them.
+     *
+     * Called with no arguments and may be async (the action shows a loading
+     * state while it resolves); whatever it returns replaces the selection. It
+     * is up to you to apply the current filters/sort when resolving - the grid
+     * does not pass them, because in server-side mode you already own that
+     * query.
+     *
+     * Only rendered when the grid can tell it is holding a subset, i.e. when
+     * `totalRows` exceeds the number of loaded rows.
+     */
+    onSelectAllMatching?: () => string[] | Promise<string[]>;
     bulkActions?: BulkAction<T>[];
     /**
      * Renders a chevron column (table mode) / toolbar toggle (card mode) that
@@ -312,14 +430,14 @@ interface DataGridProps<T extends Record<string, unknown> = Record<string, unkno
      */
     cardMinWidth?: number;
 }
-type EditingCell = {
+type EditingCell<T extends object = Record<string, unknown>> = {
     rowIndex: number;
-    colKey: string;
+    colKey: RowKey<T>;
 } | null;
 
-declare function DataGridInner<T extends Record<string, unknown>>({ columns, data, rowKey, onChange, onRowAdd, editable, loading, emptyText, className, stickyHeader, maxHeight, showRowNumbers, draggableRows, onRowReorder, currentSort, onSortChange, showFilters, filterConfig, filters, onFiltersChange, quickFilters, showPagination, pageSize, pageSizeOptions, totalRows: totalRowsProp, onPageChange, selectable, selectedRows: controlledSelectedRows, defaultSelectedRows, onSelectionChange, bulkActions, expandable, renderExpandedContent, isRowExpandable, expandMultiple, expandedRows: controlledExpandedRows, defaultExpandedRows, onExpandedRowsChange, density, showDensity, hasCardView, cardViewBreakpoint, cardMinWidth, }: DataGridProps<T>): React__default.ReactElement;
+declare function DataGridInner<T extends object>({ columns: columnsProp, data, rowKey, onChange, onRowAdd, editable, loading, emptyText, className, stickyHeader, maxHeight, showRowNumbers, draggableRows, onRowReorder, currentSort, onSortChange, showFilters, filterConfig, filters, onFiltersChange, quickFilters, showPagination, pageSize, pageSizeOptions, totalRows: totalRowsProp, onPageChange, selectable, selectedRows: controlledSelectedRows, defaultSelectedRows, onSelectionChange, selectAllScope, onSelectAllMatching, bulkActions, expandable, renderExpandedContent, isRowExpandable, expandMultiple, expandedRows: controlledExpandedRows, defaultExpandedRows, onExpandedRowsChange, density, showDensity, hasCardView, cardViewBreakpoint, cardMinWidth, }: DataGridProps<T>): React__default.ReactElement;
 declare const DataGrid: typeof DataGridInner & {
     displayName: string;
 };
 
-export { BulkAction, DataGrid, type DataGridCellType, type DataGridColumn, type DataGridFilterField, type DataGridProps, type DataGridQuickFilter, type DataGridQuickFilterCombobox, type DataGridQuickFilterComboboxOption, type DataGridQuickFilterSegmented, type DataGridQuickFilterSegmentedOption, type DataGridQuickFilterSelect, type DataGridQuickFilterSelectOption, type DataGridRowAction, type DataGridSelectOption, type EditingCell };
+export { BulkAction, DataGrid, type DataGridActionsColumn, type DataGridCellType, type DataGridColumn, type DataGridCustomColumn, type DataGridFilterField, type DataGridProps, type DataGridQuickFilter, type DataGridQuickFilterCombobox, type DataGridQuickFilterComboboxOption, type DataGridQuickFilterSegmented, type DataGridQuickFilterSegmentedOption, type DataGridQuickFilterSelect, type DataGridQuickFilterSelectOption, type DataGridRowAction, type DataGridSelectOption, type DataGridValueCellType, type DataGridValueColumn, type EditingCell };