@opencorestack/opengridx 3.6.0 → 3.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (62) hide show
  1. package/CHANGELOG.md +17 -0
  2. package/dist/index.d.ts +30 -0
  3. package/dist/opengridx.css +1 -1
  4. package/dist/opengridx.es.js +8566 -8130
  5. package/dist/opengridx.es.js.map +1 -1
  6. package/dist/opengridx.umd.js +15 -15
  7. package/dist/opengridx.umd.js.map +1 -1
  8. package/docs/API_REFERENCE.md +3 -2
  9. package/docs/architecture/datagrid-orchestration.md +46 -29
  10. package/docs/architecture/grid-row-meta.md +1 -1
  11. package/docs/customization/slots-api.md +1 -1
  12. package/docs/customization/theming.md +43 -0
  13. package/docs/features/virtualization.md +16 -2
  14. package/docs/performance.md +3 -1
  15. package/lib/components/AiAssistant/GridAiAssistantPanel.css +3 -1
  16. package/lib/components/Cell/Cell.css +4 -2
  17. package/lib/components/ColumnGroupHeader/ColumnGroupHeader.css +2 -2
  18. package/lib/components/ColumnVisibilityPanel/ColumnVisibilityPanel.css +3 -1
  19. package/lib/components/DataGrid/DataGrid.css +9 -9
  20. package/lib/components/DataGrid/DataGrid.tsx +163 -671
  21. package/lib/components/DataGrid/GridRoot.tsx +239 -0
  22. package/lib/components/DataGrid/GridViewport.tsx +314 -0
  23. package/lib/components/FilterPanel/FilterPanel.css +9 -8
  24. package/lib/components/Header/ColumnMenu.css +4 -3
  25. package/lib/components/Header/Header.css +5 -4
  26. package/lib/components/HeaderFilter/HeaderFilter.css +1 -1
  27. package/lib/components/Pagination/Pagination.css +1 -1
  28. package/lib/components/Row/Row.css +2 -2
  29. package/lib/components/Toolbar/GridToolbar.css +8 -7
  30. package/lib/components/Toolbar/PivotPanel.css +3 -3
  31. package/lib/hooks/core/useGridDevWarnings.ts +3 -1
  32. package/lib/hooks/core/useGridEditPipeline.ts +55 -0
  33. package/lib/hooks/core/useGridRangeEditing.ts +129 -0
  34. package/lib/hooks/core/useGridRenderWindow.ts +66 -0
  35. package/lib/hooks/core/useGridScrollViewport.ts +42 -0
  36. package/lib/hooks/core/useGridSelectionAndStateApi.ts +61 -0
  37. package/lib/hooks/core/useGridToolbarStack.ts +49 -0
  38. package/lib/hooks/core/useGridViewApis.ts +46 -0
  39. package/lib/styles/base/variables.css +12 -0
  40. package/lib/theme/DataGridThemeProvider.tsx +15 -0
  41. package/lib/theme/__baseline__/default-theme.darwin.chromium.json +1503 -0
  42. package/lib/theme/__baseline__/default-theme.darwin.firefox.json +1503 -0
  43. package/lib/theme/__baseline__/default-theme.darwin.webkit.json +1503 -0
  44. package/lib/theme/types.ts +31 -0
  45. package/lib/types/ai.ts +109 -0
  46. package/lib/types/api.ts +169 -0
  47. package/lib/types/columns.ts +341 -0
  48. package/lib/types/dataSource.ts +40 -0
  49. package/lib/types/editing.ts +77 -0
  50. package/lib/types/export.ts +164 -0
  51. package/lib/types/filtering.ts +52 -0
  52. package/lib/types/grouping.ts +27 -0
  53. package/lib/types/index.ts +18 -1702
  54. package/lib/types/locale.ts +51 -0
  55. package/lib/types/props.ts +405 -0
  56. package/lib/types/rows.ts +132 -0
  57. package/lib/types/selection.ts +66 -0
  58. package/lib/types/slots.ts +56 -0
  59. package/lib/types/sorting.ts +25 -0
  60. package/lib/types/state.ts +35 -0
  61. package/llms.txt +1 -1
  62. package/package.json +4 -2
@@ -1,1703 +1,19 @@
1
- import type { GridToolbarProps } from '../components/Toolbar/GridToolbar';
2
- import type { PaginationProps } from '../components/Pagination/Pagination';
3
-
4
- /** Unique identifier for a row (string or number). */
5
- export type GridRowId = string | number;
6
-
7
- /** Base interface for a grid row data object. */
8
- export interface GridRowModel {
9
- /** Uniquely identifies the row. */
10
- id: GridRowId;
11
- /** Internal: row is a skeleton placeholder during infinite-scroll loading. */
12
- _isSkeleton?: boolean;
13
- /** Internal: server-reported child count for lazy-loaded tree nodes. */
14
- serverChildrenCount?: number;
15
- /** Any other dynamic row properties. */
16
- [key: string]: unknown;
17
- }
18
-
19
1
  /**
20
- * The constraint on the row type `R` of the generic grid types (`DataGridProps<R>`, `GridColDef<R>`,
21
- * `GridRenderCellParams<R>` …): any object type. Your own interfaces and type aliases can be used as `R`
22
- * directly; they do not need an index signature or to extend `GridRowModel`. Rows without an `id`
23
- * field need `getRowId`. `GridRowModel` stays the default `R` (rows with any keys, read as `unknown`).
24
- * @since v3.0
25
- */
26
- export type GridValidRowModel = object;
27
-
28
- /**
29
- * A callback that is checked bivariantly in its parameter, like a method. Used for `GridColDef`
30
- * options that are either a value or a function, so a column typed for your rows (`GridColDef<Row>`)
31
- * can still be used where an untyped `GridColDef` is expected.
32
- */
33
- type GridColDefCallback<P, T> = { bivarianceHack(params: P): T }['bivarianceHack'];
34
-
35
- /**
36
- * Hierarchy metadata for a row. Exposed via `params.rowMeta` in `renderCell`.
37
- * Not present (`undefined`) for flat rows with no active tree-data or row-grouping.
38
- *
39
- * @since v1.1 — replaces the `_hasChildren` / `_treeDepth` / `_groupingField` etc.
40
- * fields that were injected onto row objects. Since v3.0 those fields are no longer
41
- * added at runtime: row objects reach `renderCell` exactly as you passed them.
42
- */
43
- export interface GridRowMeta {
44
- /** The row has children to show: the expand toggle is rendered for it. */
45
- hasChildren?: boolean;
46
- treeDepth?: number;
47
- groupingField?: string;
48
- groupingValue?: unknown;
49
- /** The label the grid shows for a synthetic row: the group label, or the path segment of an auto-created tree parent. */
50
- groupLabel?: string;
51
- /**
52
- * Data rows below this row at any depth that pass the active filter (row-grouping leaves, or
53
- * tree-data rows; auto-created tree parents are not counted). The "(n)" shown next to group labels.
54
- */
55
- descendantCount?: number;
56
- isExpanded?: boolean;
57
- /**
58
- * The row is synthetic: a row-grouping group row, a group subtotal row, or a tree-data parent the
59
- * grid created for a path segment with no row of its own. Synthetic rows are never selected,
60
- * edited or given a detail panel, and `valueGetter` is not called for them.
61
- */
62
- isGroupRow?: boolean;
63
- /**
64
- * The row is the subtotal row of the group described by `groupingField` / `groupingValue`, shown
65
- * after the group's children when `getAggregationPosition` returns `'footer'` for it.
66
- * @since v3.0
67
- */
68
- isGroupFooter?: boolean;
69
- }
70
-
71
- export type GridAlignment = 'left' | 'center' | 'right';
72
-
73
- /** Represents a row node in the grid's hierarchical tree structure. */
74
- export interface GridTreeNode {
75
- /** Unique ID of the row. */
76
- id: GridRowId;
77
- /** ID of the parent node, or null if root. */
78
- parentId: GridRowId | null;
79
- /** Current depth in the tree (0 for root). */
80
- depth: number;
81
- /** The key used for grouping at this level. */
82
- groupingKey: string;
83
-
84
- /** The field this node is grouping by. */
85
- groupingField?: string;
86
- /** The actual value being grouped. */
87
- groupingValue?: unknown;
88
-
89
- /** Computed aggregation results for this group. */
90
- aggregatedValues?: Record<string, unknown>;
91
- /** Position of the aggregation row relative to the group. */
92
- aggregationPosition?: 'inline' | 'footer' | null;
93
- /** Current expansion state. */
94
- isExpanded: boolean;
95
- /** IDs of the direct child nodes. */
96
- children?: GridRowId[];
97
- /** Display label for the group. */
98
- label?: string;
99
-
100
- /** Row grouping: the number of leaf rows in the group that pass the active filter (recursive). */
101
- descendantCount?: number;
102
-
103
- /** Count of children on the server (for lazy loading). */
104
- serverChildrenCount?: number;
105
- }
106
-
107
- export type GridSortDirection = 'asc' | 'desc' | null;
108
-
109
- /**
110
- * Metadata for a single column.
111
- * Governs rendering, sorting, filtering, and data transformation.
112
- */
113
- export interface GridColDef<R extends GridValidRowModel = GridRowModel> {
114
- /** The unique identifier for the column, typically matching a row object key. */
115
- field: string;
116
- /** Text displayed in the column header. */
117
- headerName?: string;
118
- /** Tooltip shown on header hover — used as the column's accessibility label. */
119
- description?: string;
120
- /** If true, this column can be used as a grouping dimension. */
121
- groupable?: boolean;
122
-
123
- /**
124
- * Custom formatter for the group-header label when this column is used as a grouping field.
125
- * Receives the field name and grouped value; return the string to display.
126
- * Falls back to `"field: value"` when omitted.
127
- */
128
- groupingValueFormatter?: (params: { field: string; value: unknown }) => string;
129
-
130
- /** If true, this column can be summarized using aggregation functions. */
131
- aggregable?: boolean;
132
- /** Restricts which aggregation functions are offered for this column (e.g., ['sum', 'avg']). */
133
- availableAggregationFunctions?: string[];
134
-
135
- /** Width in pixels or a percentage string. Defaults to automatic calculation. */
136
- width?: number | string;
137
- /** Minimum width in pixels. */
138
- minWidth?: number;
139
- /** Maximum width in pixels. */
140
- maxWidth?: number;
141
- /** Relative flex weight used when distributing extra space. */
142
- flex?: number;
143
- /** Content alignment within cells. */
144
- align?: GridAlignment;
145
- /** Content alignment within the header cell. */
146
- headerAlign?: GridAlignment;
147
- /**
148
- * Wraps this column's header title onto several lines instead of cutting it with an ellipsis.
149
- * Overrides the grid's `wrapHeaderText`. The header keeps `headerHeight`: the title shows as many
150
- * lines as fit and ends in an ellipsis if it is still longer. Raise `headerHeight` for more lines.
151
- */
152
- wrapHeaderText?: boolean;
153
- /** If false, sorting is disabled for this column. */
154
- sortable?: boolean;
155
- /** If false, filtering is disabled for this column. */
156
- filterable?: boolean;
157
- /**
158
- * Set to `false` to leave this column's cell in the header filter row (`headerFilters`) empty.
159
- * Columns with `filterable: false` or `type: 'image'` have no header filter either.
160
- * @since v3.5
161
- */
162
- headerFilter?: boolean;
163
- /**
164
- * The operator a new header filter (`headerFilters`) for this column starts with. Defaults by type:
165
- * `contains` (string), `=` (number), `is` (date, boolean, singleSelect).
166
- * @since v3.5
167
- */
168
- headerFilterOperator?: GridFilterOperator;
169
- /** If false, the user cannot manually resize this column. */
170
- resizable?: boolean;
171
- /** If false, the column cannot be hidden via the UI. */
172
- hideable?: boolean;
173
- /** If false, the column cannot be pinned. */
174
- pinnable?: boolean;
175
- /** Internal: marks this column as a virtual spacer used for horizontal virtualization. */
176
- isSpacer?: boolean;
177
- /** Type used to determine default operators and formatting logic. */
178
- type?: 'string' | 'number' | 'date' | 'boolean' | 'singleSelect' | 'image';
179
- /** Options used for 'singleSelect' type. */
180
- valueOptions?: Array<string | number | { value: unknown; label: string }>;
181
-
182
- // The row callbacks below are declared as methods so that `GridColDef<Row>` stays assignable to an
183
- // untyped `GridColDef` (method parameters are checked bivariantly).
184
- /** Function to compute a cell value from raw row data. */
185
- valueGetter?(params: GridValueGetterParams<R>): unknown;
186
- /**
187
- * Maps an edited value back onto the row when an edit is committed; return the updated row.
188
- * Needed for editable columns with a `valueGetter`, whose value is not stored in `row[field]`.
189
- * Without it the commit writes `row[field] = value`.
190
- * @since v3.0
191
- */
192
- valueSetter?(params: GridValueSetterParams<R>): R;
193
- /**
194
- * Turns pasted text into this column's value (clipboard paste), instead of the default parser for
195
- * the column `type` (see `docs/features/clipboard.md`). Use it for locales such as `1.234,5` or for
196
- * custom codes. Throw (or return `undefined`) to reject the text: the cell is skipped with reason
197
- * `'invalidValue'`. The value then goes through `valueSetter` and `processRowUpdate` like an edit.
198
- * @since v3.4
199
- */
200
- valueParser?(text: string, params: GridValueParserParams<R>): unknown;
201
- /**
202
- * Custom ascending comparator for client-side sorting by this column, used instead of the built-in
203
- * type-aware comparison. `v1` / `v2` are the cell values (`valueGetter` applied) and **include
204
- * `null` / `undefined`**, so the comparator decides where empty values go. The grid reverses the
205
- * result for 'desc' and chains it with the other sort keys in a multi-sort. Row grouping uses the
206
- * grouping column's comparator to order groups by their grouping value. A comparator that throws
207
- * or returns NaN is read as 0 (with a one-time dev warning). Ignored with `sortingMode="server"`.
208
- * @since v3.1
209
- */
210
- sortComparator?(v1: unknown, v2: unknown, params1: GridSortCellParams<R>, params2: GridSortCellParams<R>): number;
211
- /**
212
- * Decides the value the fill handle (or Ctrl/Cmd+D, Ctrl/Cmd+R) writes into a cell of this column.
213
- * `params.value` is what the grid would write (a continued series, the repeated pattern or a copy);
214
- * return it to keep that, or any other value. A throw skips the cell with reason `'invalidValue'`.
215
- * The value then goes through `valueSetter` and `processRowUpdate` like an edit. @since v3.5
216
- */
217
- fillValue?(params: GridFillValueParams<R>): unknown;
218
- /** Function to format a value into a human-readable string. */
219
- valueFormatter?(params: GridValueFormatterParams<R>): string;
220
- /** Custom component or element to render in the cell. */
221
- renderCell?(params: GridRenderCellParams<R>): React.ReactNode;
222
- /** Custom component or element to render in the header. */
223
- renderHeader?(params: GridRenderHeaderParams): React.ReactNode;
224
- /** Component to render when the cell is in edit mode. Receives `onValueChange`, `onCommit` and `onCancel`. */
225
- renderEditCell?(params: GridRenderEditCellParams<R>): React.ReactNode;
226
- /** If true, the cell's value can be modified by the user. */
227
- editable?: boolean;
228
- /** Optional stacking order (CSS z-index). */
229
- zIndex?: number;
230
- /** If true, the column kebab/hamburger menu is disabled. */
231
- disableColumnMenu?: boolean;
232
-
233
- /**
234
- * Number of columns this cell should occupy horizontally: the origin plus the next visible columns
235
- * in render order, clamped to the end of the origin's pinned section. Fractions are floored,
236
- * `Infinity` means "to the end", and NaN / values below 1 mean no span. `params.value` is the
237
- * `valueGetter` result. A function that throws is treated as 1.
238
- */
239
- colSpan?: number | GridColDefCallback<GridRenderCellParams<R>, number>;
240
- /**
241
- * Number of rows this cell should occupy vertically, clamped to the end of its row section
242
- * (top-pinned, scrolling or bottom-pinned rows) and to the first row with an expanded detail
243
- * panel. Normalised like `colSpan`. With both set, the origin covers the whole rectangle.
244
- */
245
- rowSpan?: number | GridColDefCallback<GridRenderCellParams<R>, number>;
246
-
247
- /**
248
- * Custom CSS class applied to every cell in this column.
249
- * Can be a static string or a function that receives the cell params and returns a string.
250
- * Useful for per-row conditional styling without custom renderCell.
251
- * @example
252
- * cellClassName: 'my-class'
253
- * cellClassName: ({ value }) => value > 100 ? 'cell--high' : 'cell--low'
254
- */
255
- cellClassName?: string | GridColDefCallback<GridRenderCellParams<R>, string>;
256
-
257
- /**
258
- * Custom CSS class applied to the header cell of this column.
259
- * @example
260
- * headerClassName: 'my-header'
261
- */
262
- headerClassName?: string;
263
-
264
- /**
265
- * If false, this column is excluded from all exports (CSV, Excel, JSON, Print).
266
- * Useful for action columns with buttons.
267
- * @default true
268
- */
269
- exportable?: boolean;
270
-
271
- /**
272
- * Example values for this column, put into the schema from `getGridAiSchema`
273
- * (`@opencorestack/opengridx/ai`) to help a language model write filters ("Acme" → `customer`).
274
- * **These values are sent to the model.** The grid never reads row data for the schema; only what
275
- * you list here leaves the app, so list nothing private. Strings, numbers and booleans are used
276
- * (at most 10); other values are ignored. Not used by the grid itself.
277
- * @since v3.4
278
- */
279
- aiExamples?: unknown[];
280
- }
281
-
282
- /** Column definition used exclusively in List View mode. */
283
- export interface GridListViewColDef<R extends GridValidRowModel = GridRowModel> {
284
- field: string;
285
- renderCell(params: GridRenderCellParams<R>): React.ReactNode;
286
- }
287
-
288
- /**
289
- * Describes one level of column grouping.
290
- * Groups can be nested by placing child GridColumnGroup objects in `children`.
291
- * Leaf groups reference actual column fields via `children: string[]`.
292
- *
293
- * Example – two levels:
294
- * [
295
- * { groupId: 'q1', headerName: 'Q1 2024', children: ['q1Sales', 'q1Target'] },
296
- * { groupId: 'info', headerName: 'Info', children: [
297
- * { groupId: 'personal', headerName: 'Personal', children: ['name', 'age'] }
298
- * ] }
299
- * ]
300
- */
301
- export interface GridColumnGroup {
302
- /** Unique identifier for this group. */
303
- groupId: string;
304
- /** Text displayed in the group header cell. */
305
- headerName: string;
306
- /** CSS class(es) added to this group's header cell(s). */
307
- headerClassName?: string;
308
- /**
309
- * Either an array of column field strings (leaf group)
310
- * or an array of child GridColumnGroup objects (nested group).
311
- */
312
- children: Array<string | GridColumnGroup>;
313
- }
314
-
315
- export type GridColumnGroupingModel = GridColumnGroup[];
316
-
317
-
318
- /**
319
- * Parameters passed to `GridColDef.sortComparator` for each side of a comparison. For a row-grouping
320
- * group row, `row` is the synthetic group row and `value` its grouping value.
321
- * @since v3.1
322
- */
323
- export interface GridSortCellParams<R extends GridValidRowModel = GridRowModel> {
324
- id: GridRowId;
325
- field: string;
326
- row: R;
327
- value: unknown;
328
- }
329
-
330
- /** Parameters passed to the `valueGetter` function. */
331
- export interface GridValueGetterParams<R extends GridValidRowModel = GridRowModel> {
332
- /** The row object. */
333
- row: R;
334
- /** The field name. */
335
- field: string;
336
- /** The raw value from the row object. */
337
- value: unknown;
338
- }
339
-
340
- /** The way a fill extends the cell range. @since v3.5 */
341
- export type GridFillDirection = 'down' | 'up' | 'right' | 'left';
342
-
343
- /** Parameters passed to `GridColDef.fillValue`. @since v3.5 */
344
- export interface GridFillValueParams<R extends GridValidRowModel = GridRowModel> {
345
- /** The row of the cell being filled, as stored now. */
346
- row: R;
347
- id: GridRowId;
348
- field: string;
349
- colDef: GridColDef<R>;
350
- direction: GridFillDirection;
351
- /** The source cells' values in fill order: the value next to the first filled cell is last. */
352
- sourceValues: unknown[];
353
- /** Position of this cell among the filled cells of its line, from 0 (next to the source). */
354
- index: number;
355
- /** What the grid would write: the continued series, the repeated pattern or a copy. */
356
- value: unknown;
357
- /** Whether a copy was asked for (Alt held at release, or the keyboard shortcuts), so no series. */
358
- copy: boolean;
359
- }
360
-
361
- /** `onFill` details: the batch edit result plus the direction of the fill. @since v3.5 */
362
- export interface GridFillResult extends GridBatchEditResult {
363
- direction: GridFillDirection;
364
- }
365
-
366
- /** Parameters passed to `GridColDef.valueParser`. @since v3.4 */
367
- export interface GridValueParserParams<R extends GridValidRowModel = GridRowModel> {
368
- /** The row the text is pasted into, as stored now. */
369
- row: R;
370
- field: string;
371
- colDef: GridColDef<R>;
372
- }
373
-
374
- /**
375
- * Parameters passed to the `valueSetter` function.
376
- * @since v3.0
377
- */
378
- export interface GridValueSetterParams<R extends GridValidRowModel = GridRowModel> {
379
- /** The committed value from the editor. */
380
- value: unknown;
381
- /** The row as it was before the edit. */
382
- row: R;
383
- /** The field name. */
384
- field: string;
385
- }
386
-
387
- /** Parameters passed to the `valueFormatter` function. */
388
- export interface GridValueFormatterParams<R extends GridValidRowModel = GridRowModel> {
389
- /** The raw value to format. */
390
- value: unknown;
391
- /** The row object. */
392
- row: R;
393
- /** The field name. */
394
- field: string;
395
- }
396
-
397
- /** Parameters passed to the `renderCell` function. */
398
- export interface GridRenderCellParams<R extends GridValidRowModel = GridRowModel> {
399
- /** The current cell value. */
400
- value: unknown;
401
- /**
402
- * The value after `colDef.valueFormatter` (or `String(value)` when no formatter is set; `''` for null/undefined).
403
- * @since v2.1
404
- */
405
- formattedValue?: string;
406
- /** The row object. */
407
- row: R;
408
- /** The field name and unique ID. */
409
- field: string;
410
- /** The column definition. */
411
- colDef: GridColDef<R>;
412
- /** The index of the row in the currently visible dataset. */
413
- rowIndex: number;
414
- /** The index of the column. */
415
- colIndex: number;
416
- /**
417
- * Hierarchy metadata for this row. `undefined` for flat rows (no tree-data or row-grouping active).
418
- * @since v1.1
419
- */
420
- rowMeta?: GridRowMeta;
421
- }
422
-
423
- /**
424
- * Parameters passed to `renderEditCell`. `value` is the pending (uncommitted) value.
425
- * @since v3.0
426
- */
427
- export interface GridRenderEditCellParams<R extends GridValidRowModel = GridRowModel> extends GridRenderCellParams<R> {
428
- /** Updates the pending value. Call it on every change; nothing is saved until `onCommit`. */
429
- onValueChange: (value: unknown) => void;
430
- /** Commits the pending value (runs `processRowUpdate`) and leaves edit mode. */
431
- onCommit: () => void;
432
- /** Discards the pending value and leaves edit mode. */
433
- onCancel: () => void;
434
- }
435
-
436
- export interface GridRenderHeaderParams {
437
- field: string;
438
- colDef: GridColDef;
439
- colIndex: number;
440
- }
441
-
442
- export interface GridSortModel {
443
- field: string;
444
- sort: GridSortDirection;
445
- }
446
-
447
- export interface GridSortItem {
448
- field: string;
449
- sort: 'asc' | 'desc';
450
- }
451
-
452
- export type GridFilterOperator =
453
- | 'contains'
454
- | 'equals'
455
- | 'startsWith'
456
- | 'endsWith'
457
- | 'isEmpty'
458
- | 'isNotEmpty'
459
- | 'isAnyOf'
460
- | '='
461
- | '>'
462
- | '>='
463
- | '<'
464
- | '<='
465
- | '!='
466
- | 'is'
467
- | 'not'
468
- | 'after'
469
- | 'onOrAfter'
470
- | 'before'
471
- | 'onOrBefore';
472
-
473
- /** Describes a filter condition for a specific column. */
474
- export interface GridFilterItem {
475
- /** Optional ID for the filter item. */
476
- id?: string | number;
477
- /** The field name to filter. */
478
- field: string;
479
- /** The comparison operator. */
480
- operator: GridFilterOperator;
481
- /** The value to compare against. */
482
- value?: unknown;
483
- }
484
-
485
- /** Describes a group of filters combined with a logical operator. */
486
- export interface GridFilterGroup {
487
- /** Optional ID for the group. */
488
- id?: string | number;
489
- /** Logical operator to join child items ('and' | 'or'). */
490
- logicOperator: 'and' | 'or';
491
- /** Array of child filter items or groups. */
492
- items: (GridFilterItem | GridFilterGroup)[];
493
- }
494
-
495
- /** The overall state of grid filtering. */
496
- export interface GridFilterModel {
497
- /** Root-level filter items or groups. */
498
- items?: (GridFilterItem | GridFilterGroup)[];
499
- /** Global logical operator (defaults to 'and'). */
500
- logicOperator?: 'and' | 'or';
501
- /** Array of strings used for the quick search feature across all columns. */
502
- quickFilterValues?: string[];
503
- }
504
-
505
- /**
506
- * Configuration options for exporting the DataGrid to PDF format.
507
- * Requires jspdf and jspdf-autotable peer dependencies.
508
- */
509
- export interface PdfExportOptions<R extends GridValidRowModel = GridRowModel> {
510
- /**
511
- * Output filename without extension. Default: 'export'
512
- */
513
- fileName?: string;
514
-
515
- /**
516
- * Title text displayed in the document header.
517
- * When omitted, no header block is rendered.
518
- */
519
- title?: string;
520
-
521
- /**
522
- * URL or data URI of a logo image rendered left of the title.
523
- * Only used when `title` is also set. Default: none
524
- */
525
- logoUrl?: string;
526
-
527
- /**
528
- * Page orientation. Default: 'landscape'
529
- */
530
- orientation?: 'portrait' | 'landscape';
531
-
532
- /**
533
- * If provided, only rows whose id is in this array are exported. A non-empty selection takes
534
- * precedence over `groupedRows` (the selected rows are exported flat), and the footer totals
535
- * are recomputed over the selected rows.
536
- */
537
- selectedRows?: (string | number)[];
538
-
539
- /**
540
- * The grid's `getRowId`, when it has one: `selectedRows` holds those ids, and the grid does not
541
- * copy them onto `row.id` (v3.0+). Defaults to `row.id`.
542
- */
543
- getRowId?: (row: R) => GridRowId;
544
-
545
- /**
546
- * Aggregation result from apiRef.current.getAggregationResult().
547
- * When provided alongside aggregationModel, appends a footer row.
548
- */
549
- aggregationResult?: Record<string, unknown> | null;
550
-
551
- /**
552
- * Aggregation model from apiRef.current.getAggregationModel().
553
- */
554
- aggregationModel?: GridAggregationModel | null;
555
-
556
- /**
557
- * Active filter model. When provided, a filter summary is shown in the header.
558
- */
559
- filterModel?: GridFilterModel | null;
560
-
561
- /**
562
- * Whether to apply alternating row shading. Default: true
563
- */
564
- alternateRowColor?: boolean;
565
-
566
- /**
567
- * Column header background color (hex). Default: '#4f46e5'
568
- */
569
- headerBackgroundColor?: string;
570
-
571
- /**
572
- * Column header text color (hex). Default: '#ffffff'
573
- */
574
- headerTextColor?: string;
575
-
576
- /**
577
- * Base font size in points for table body. Default: 9
578
- */
579
- fontSize?: number;
580
-
581
- /**
582
- * A TrueType font for the whole document. The built-in Helvetica font only covers Latin-1 and
583
- * WinAnsi punctuation (é, ü, €, “ ”, •). Without this option other characters (₹, Greek,
584
- * Cyrillic, CJK, Devanagari, U+202F used by some locales as a thousands separator) are
585
- * replaced with `?` (spaces and minus signs with their ASCII forms) and a warning is logged.
586
- * `data` is the `.ttf` file as a base64 string; `boldData` is an optional bold face for the
587
- * title, header and totals (the regular face is used when omitted). jsPDF does not shape
588
- * complex scripts, so Devanagari or Arabic ligatures may not join.
589
- * @since v3.0
590
- */
591
- font?: {
592
- /** Font family name, e.g. 'NotoSans'. */
593
- name: string;
594
- /** Base64-encoded .ttf file. */
595
- data: string;
596
- /** Base64-encoded bold .ttf file. Default: `data`. */
597
- boldData?: string;
598
- };
599
-
600
- /**
601
- * Pre-built grouped export rows from `apiRef.current.getGroupedExportRows()`.
602
- * When provided, the PDF table reflects the grouping structure (group headers,
603
- * leaf rows, per-group subtotals, grand total) instead of a flat row list.
604
- * Has no effect when the grid has no active `rowGroupingModel`, or when `selectedRows` is non-empty.
605
- */
606
- groupedRows?: GridGroupedExportRow[];
607
-
608
- /**
609
- * Called as the export advances: `prepare` (formatting rows; `total` = source rows or grouped
610
- * entries), `render` (drawing table rows; `total` = table body rows) and `save` (`0/1` before the
611
- * file is written, `1/1` after). `done` never decreases within a phase and ends at `total`.
612
- * @since v3.2
613
- */
614
- onProgress?: (progress: PdfExportProgress) => void;
615
-
616
- /**
617
- * Cancels the export. When aborted, the returned promise rejects with a `DOMException` named
618
- * `'AbortError'` and no file is saved. Checked between slices of work, so cancellation takes
619
- * effect within one slice; the final save step cannot be interrupted once started.
620
- * @since v3.2
621
- */
622
- signal?: AbortSignal;
623
-
624
- /**
625
- * Table-row count above which a development-mode warning recommends `exportToCsv` or
626
- * `exportToExcelAdvanced`. The export still runs (nothing is thrown). Pass `Infinity` to silence it.
627
- * Default: 20000
628
- * @since v3.2
629
- */
630
- maxRows?: number;
631
- }
632
-
633
- /** Progress reported by `PdfExportOptions.onProgress`. @since v3.2 */
634
- export interface PdfExportProgress {
635
- phase: 'prepare' | 'render' | 'save';
636
- done: number;
637
- total: number;
638
- }
639
-
640
- /**
641
- * A single entry in the ordered list returned by `GridApi.getGroupedExportRows()`.
642
- * Traverse in array order to reproduce the on-screen grouping structure.
643
- */
644
- export interface GridGroupedExportRow {
645
- /** Discriminator: the kind of row this entry represents. */
646
- type: 'group-header' | 'leaf' | 'group-subtotal' | 'grand-total';
647
- /** Nesting depth (0 = top-level group, 1 = nested group, etc.). */
648
- depth: number;
649
- /** The grouping field for this level (absent on 'leaf' and 'grand-total'). */
650
- groupField?: string;
651
- /** The raw grouping value for this level (absent on 'leaf' and 'grand-total'). */
652
- groupValue?: unknown;
653
- /**
654
- * The group label exactly as the grid shows it (from `groupingValueFormatter`, else `"field: value"`),
655
- * on 'group-header' and 'group-subtotal' entries from `getGroupedExportRows()`. Exporters use it for
656
- * group-header rows; when absent they apply the column's `groupingValueFormatter` themselves.
657
- * @since v3.0
658
- */
659
- groupLabel?: string;
660
- /** Per-group aggregation results (present on 'group-subtotal' and 'grand-total'). */
661
- aggregatedValues?: Record<string, unknown>;
662
- /** The original data row (only present when `type === 'leaf'`). */
663
- row?: GridRowModel;
664
- }
665
-
666
- export type GridPinnedPosition = 'left' | 'right';
667
-
668
- export type GridColumnVisibilityModel = Record<string, boolean>;
669
-
670
- /** Configuration for pinning columns to the grid edges. */
671
- export interface GridColumnPinning {
672
- /** Field strings to pin to the left edge. */
673
- left?: string[];
674
- /** Field strings to pin to the right edge. */
675
- right?: string[];
676
- }
677
-
678
- /** Configuration for pinning rows to the grid viewport. */
679
- export interface GridRowPinning {
680
- /** Row IDs to pin to the top. */
681
- top?: GridRowId[];
682
- /** Row IDs to pin to the bottom. */
683
- bottom?: GridRowId[];
684
- }
685
-
686
- export interface GridColumnOrderChangeParams {
687
- column: GridColDef;
688
- oldIndex: number;
689
- targetIndex: number;
690
- }
691
-
692
- export type GridColumnOrder = string[];
693
-
694
- export interface GridRowOrderChangeParams<R extends GridValidRowModel = GridRowModel> {
695
- row: R;
696
- oldIndex: number;
697
- targetIndex: number;
698
- }
699
-
700
- export interface GridGetRowsParams {
701
- startRow: number;
702
- endRow: number;
703
- sortModel: GridSortItem[];
704
- filterModel: GridFilterModel;
705
- groupKeys: string[];
706
- aggregationModel?: GridAggregationModel;
707
- }
708
-
709
- export interface GridGetRowsResponse<R extends GridValidRowModel = GridRowModel> {
710
- rows: R[];
711
- rowCount?: number;
712
- aggregationResults?: Record<string, unknown>;
713
- }
714
-
715
- /**
716
- * Interface for providing data to the grid from a remote source.
717
- * Enables server-side sorting, filtering, and pagination.
718
- */
719
- export interface GridDataSource<R extends GridValidRowModel = GridRowModel> {
720
- /**
721
- * Fetches a chunk of rows based on current grid state.
722
- * @param params Sorting, filtering, and range parameters.
723
- */
724
- getRows: (params: GridGetRowsParams) => Promise<GridGetRowsResponse<R>>;
725
- /**
726
- * Optional: Fetches aggregation results for the entire dataset.
727
- */
728
- getAggregations?: (params: Omit<GridGetRowsParams, 'startRow' | 'endRow'>) => Promise<Record<string, unknown>>;
729
- }
730
-
731
- export interface GridPaginationModel {
732
- page: number;
733
- pageSize: number;
734
- }
735
-
736
- export type GridRowSelectionModel = GridRowId[];
737
-
738
- /** One cell, addressed by its row id and column field. @since v3.3 */
739
- export interface GridCellCoordinates {
740
- id: GridRowId;
741
- field: string;
742
- }
743
-
744
- /**
745
- * A rectangle of cells between two corners. `anchor` is the active cell: it keeps focus, is the cell
746
- * an edit starts in, and stays put while the range is extended. `head` is the corner that moves with
747
- * Shift+arrows or the pointer, and the one scrolled into view. A single cell has `anchor` equal to `head`.
748
- * @since v3.3
749
- */
750
- export interface GridCellRange {
751
- anchor: GridCellCoordinates;
752
- head: GridCellCoordinates;
753
- }
754
-
755
- /**
756
- * The cell selection: zero or one range in 3.3 (the array form leaves room for several ranges later).
757
- * Corners are ids and fields, so the rectangle follows its corner rows through sorting and filtering.
758
- * @since v3.3
759
- */
760
- export type GridCellSelectionModel = readonly GridCellRange[];
761
-
762
- /** What changed the cell selection. @since v3.3 */
763
- export type GridCellSelectionReason = 'pointer' | 'keyboard' | 'selectAll' | 'api' | 'clear' | 'dataChange';
764
-
765
- /** Second argument of `onCellSelectionModelChange`. @since v3.3 */
766
- export interface GridCellSelectionChangeDetails {
767
- reason: GridCellSelectionReason;
768
- }
769
-
770
- /** One cell of the selected range, as returned by `apiRef.getSelectedCells()`. @since v3.3 */
771
- export interface GridSelectedCell {
772
- id: GridRowId;
773
- field: string;
774
- /** The cell's value, read through the column's `valueGetter`. */
775
- value: unknown;
776
- }
777
-
778
- /**
779
- * Props the grid passes to `slots.cellSelectionStats` (the status bar of `showCellSelectionStats`),
780
- * before `slotProps.cellSelectionStats` is merged over them. Rendered only while more than one cell
781
- * is selected.
782
- * @since v3.3
783
- */
784
- export interface GridCellSelectionStatsSlotProps {
785
- apiRef: React.MutableRefObject<GridApi>;
786
- /** Cells in the rectangle (rows × columns), synthetic rows and span-covered positions included. */
787
- cellCount: number;
788
- rowCount: number;
789
- columnCount: number;
790
- /** Non-empty cells of data rows. */
791
- count: number;
792
- /** Cells holding a number. */
793
- numericCount: number;
794
- /** Sum of the numeric cells, or `null` when there are none. */
795
- sum: number | null;
796
- /** Average of the numeric cells, or `null` when there are none. */
797
- average: number | null;
798
- }
799
-
800
- export interface GridPinnedColumns {
801
- left?: string[];
802
- right?: string[];
803
- }
804
-
805
- export interface GridPinnedRows<R extends GridValidRowModel = GridRowModel> {
806
- top?: R[];
807
- bottom?: R[];
808
- }
809
-
810
- export type GridRowGroupingModel = string[];
811
-
812
- export interface GridAggregationModel {
813
- [field: string]: string;
814
- }
815
-
816
- export type GridAggregationResult = Record<string, unknown>;
817
-
818
- /**
819
- * Where a group's aggregates are shown, as returned by `getAggregationPosition`: `'inline'` on the group row,
820
- * `'footer'` on a subtotal row after the group's children, `null` hidden.
821
- */
822
- export type GridAggregationPosition = 'inline' | 'footer' | null;
823
-
824
- export type GridPivotAggFn = 'sum' | 'avg' | 'count' | 'min' | 'max';
825
-
826
- export interface GridPivotValueField {
827
- field: string;
828
- aggFn: GridPivotAggFn;
829
- headerName?: string;
830
- }
831
-
832
- export interface GridPivotModel {
833
- rowFields: string[];
834
- columnFields: string[];
835
- valueFields: GridPivotValueField[];
836
- }
837
-
838
- export interface GridInternalState {
839
- rows: {
840
- idRowsLookup: Map<GridRowId, GridRowModel>;
841
- allRows: GridRowId[];
842
- /** Row object → its getRowId() key. Rows are stored untouched, so this is how ids are resolved. */
843
- idByRow: Map<GridRowModel, GridRowId>;
844
- };
845
- pagination: {
846
- /** Server-reported total (dataSource responses); undefined until one arrives. */
847
- rowCount?: number;
848
- };
849
- columns: {
850
- all: GridColDef[];
851
- lookup: Map<string, GridColDef>;
852
- orderedFields: string[];
853
- columnVisibilityModel: GridColumnVisibilityModel;
854
- };
855
- pinning: {
856
- pinnedColumns: GridPinnedColumns;
857
- pinnedRows: GridPinnedRows;
858
- };
859
- dimensions: {
860
- rowHeight: number;
861
- headerHeight: number;
862
- viewportWidth: number;
863
- viewportHeight: number;
864
- };
865
- dataSource: {
866
- loading: boolean;
867
- error: unknown;
868
- };
869
- }
870
-
871
- export interface GridRowScrollEndParams {
872
- visibleTop: number;
873
- visibleBottom: number;
874
- viewportHeight: number;
875
- }
876
-
877
- /**
878
- * Why a cell of a batch edit (paste, range clear, undo, redo) was not written:
879
- * - `'notEditable'`: the column is not `editable`, `isCellEditable` returned false, or the row is a
880
- * synthetic row (group header, subtotal, tree auto-parent, pivot Grand Total);
881
- * - `'invalidValue'`: the pasted text does not parse for the column type (or `valueParser` rejected it);
882
- * - `'changed'`: undo/redo only, the cell no longer holds the value the history recorded;
883
- * - `'missing'`: undo/redo only, the row is gone.
884
- * @since v3.4
885
- */
886
- export type GridEditSkipReason = 'notEditable' | 'invalidValue' | 'changed' | 'missing';
887
-
888
- /** What a batch edit (paste, range clear, undo, redo) did. @since v3.4 */
889
- export interface GridBatchEditResult {
890
- /** Rows whose `processRowUpdate` succeeded and that were stored, in the order they were first touched. */
891
- updated: GridRowId[];
892
- /** Rows whose `valueSetter` or `processRowUpdate` threw or rejected (also reported to `onProcessRowUpdateError`). */
893
- failed: { id: GridRowId; error: unknown }[];
894
- /** Cells that were not written, with the reason. */
895
- skipped: { id: GridRowId; field: string; reason: GridEditSkipReason }[];
896
- }
897
-
898
- /** `onClipboardPaste` details: the batch edit result plus the text that was pasted. @since v3.4 */
899
- export interface GridClipboardPasteResult extends GridBatchEditResult {
900
- text: string;
901
- }
902
-
903
- /** `onBeforeClipboardPaste` params. @since v3.4 */
904
- export interface GridBeforeClipboardPasteParams {
905
- /** The clipboard text (`text/plain`). */
906
- text: string;
907
- /** The cell the paste starts from (the range's top-left cell, or the focused cell). */
908
- anchor: GridCellCoordinates | null;
909
- }
910
-
911
- /** `onHistoryChange` params. @since v3.4 */
912
- export interface GridHistoryChangeParams {
913
- canUndo: boolean;
914
- canRedo: boolean;
915
- /** Number of actions that can be undone. */
916
- size: number;
917
- }
918
-
919
- /** `undoRedo` options. @since v3.4 */
920
- export interface GridUndoRedoOptions {
921
- /** How many actions are kept; the oldest is dropped beyond it. Default: 100. */
922
- limit?: number;
923
- }
924
-
925
- /** Overrideable user-visible strings for internationalisation. All fields are optional; defaults match the built-in English strings. */
926
- export interface GridLocaleText {
927
- /** Label before the rows-per-page select. Default: `"Rows per page:"` */
928
- paginationRowsPerPage?: string;
929
- /** Range label. Receives (from, to, count). Default: `` (f, t, c) => `${f}–${t} of ${c}` `` */
930
- paginationOf?: (from: number, to: number, count: number) => string;
931
- /** Page counter label. Receives (page, pageCount). Default: `` (p, pc) => `Page ${p} of ${pc}` `` */
932
- paginationPage?: (page: number, pageCount: number) => string;
933
- /** Empty-state label. When set, overrides the `noRowsLabel` prop on DataGrid. Default: `"No Data"` */
934
- noRowsLabel?: string;
935
- /**
936
- * Screen-reader announcement after the cell range changes (`cellSelection`). Receives (cells, rows,
937
- * columns). Default: `` (c, r, col) => `${c} cells selected, ${r} rows by ${col} columns` `` (singular for 1).
938
- * @since v3.3
939
- */
940
- cellSelectionAnnouncement?: (cellCount: number, rowCount: number, columnCount: number) => string;
941
- /** Label of the toolbar button that opens the `aiAssistant` panel. Default: `"Ask AI"` @since v3.5 */
942
- aiAssistantButton?: string;
943
- /** Header filter cell whose column has a filter the row cannot edit. Default: `"Custom filter"` @since v3.6 */
944
- headerFilterCustom?: string;
945
- /** Tooltip of the "Custom filter" cell. Default: `"Set in the filter panel"` @since v3.6 */
946
- headerFilterCustomTooltip?: string;
947
- /** `aria-label` of a header filter cell. Receives the column header. Default: `` (h) => `Filter ${h}` `` @since v3.6 */
948
- headerFilterCellLabel?: (header: string) => string;
949
- /** `aria-label` of the value input or select. Default: `` (h) => `Filter value for ${h}` `` @since v3.6 */
950
- headerFilterValueLabel?: (header: string) => string;
951
- /**
952
- * `aria-label` of the operator button. Receives the header and the operator's label.
953
- * Default: `` (h, op) => `Filter operator for ${h}: ${op}` `` @since v3.6
954
- */
955
- headerFilterOperatorButtonLabel?: (header: string, operatorLabel: string) => string;
956
- /** `aria-label` of the operator menu. Default: `` (h) => `Filter operator for ${h}` `` @since v3.6 */
957
- headerFilterOperatorMenuLabel?: (header: string) => string;
958
- /** `aria-label` of the clear button. Default: `` (h) => `Clear filter for ${h}` `` @since v3.6 */
959
- headerFilterClearLabel?: (header: string) => string;
960
- /** Tooltip of the clear button. Default: `"Clear"` @since v3.6 */
961
- headerFilterClearTooltip?: string;
962
- /** Empty choice of the boolean and single-select filters. Default: `"Any"` @since v3.6 */
963
- headerFilterAny?: string;
964
- /** "true" choice of the boolean filter. Default: `"Yes"` @since v3.6 */
965
- headerFilterTrue?: string;
966
- /** "false" choice of the boolean filter. Default: `"No"` @since v3.6 */
967
- headerFilterFalse?: string;
968
- /**
969
- * Operator names in the header filter menu, tooltips and no-value cells ("Is empty"). Missing
970
- * operators keep their English name. @since v3.6
971
- */
972
- headerFilterOperators?: Partial<Record<GridFilterOperator, string>>;
973
- }
974
-
975
- /**
976
- * Main properties for the DataGrid component.
977
- */
978
- export interface DataGridProps<R extends GridValidRowModel = GridRowModel> {
979
- /** The dataset to display in the grid. */
980
- rows: R[];
981
- /** Column definitions governing how data is displayed and interacted with. */
982
- columns: GridColDef<R>[];
983
-
984
- /** Function to extract a unique ID from a row object. Defaults to `row.id`. */
985
- getRowId?: (row: R) => GridRowId;
986
-
987
- /** Height of each row in pixels. Defaults to 52. */
988
- rowHeight?: number;
989
- /** Height of the header row in pixels. Defaults to 56. */
990
- headerHeight?: number;
991
- /**
992
- * Wraps header titles onto several lines instead of cutting them with an ellipsis. The header
993
- * keeps `headerHeight` (2 lines at the default 56px, 3 at 72px, 4 at 88px); a title that still
994
- * does not fit ends in an ellipsis. `GridColDef.wrapHeaderText` overrides it per column.
995
- * Defaults to `false`.
996
- */
997
- wrapHeaderText?: boolean;
998
- /**
999
- * Adds a filter row under the column headers: one control per column (text, number, date, a Yes / No
1000
- * select for booleans, the `valueOptions` for singleSelect) with an operator menu and a clear button.
1001
- * It reads and writes `filterModel`: each cell owns the root-level item with `id: 'header:<field>'`,
1002
- * so the filter panel, quick filter and `filterMode="server"` keep working. A model the row cannot
1003
- * show (root `logicOperator: 'or'`, other conditions on the column, nested groups) is shown as
1004
- * "Custom filter" and left untouched. See `docs/features/header-filters.md`. Defaults to `false`.
1005
- * @since v3.5
1006
- */
1007
- headerFilters?: boolean;
1008
- /** Height of the header filter row (`headerFilters`) in pixels. Defaults to 40. @since v3.5 */
1009
- headerFilterHeight?: number;
1010
- /** If true, the grid height will adjust to match the total height of its rows. */
1011
- autoHeight?: boolean;
1012
- /**
1013
- * Minimum number of rows to render outside the visible viewport (overscan buffer).
1014
- * The grid adapts this value upward automatically based on scroll velocity to prevent
1015
- * blank flashes during fast scrolling. This prop sets the floor — the buffer never
1016
- * drops below this value regardless of scroll speed. Defaults to `3`.
1017
- */
1018
- overscanRowCount?: number;
1019
-
1020
- /** Sorting mode: 'client' (default) or 'server'. */
1021
- sortingMode?: 'client' | 'server';
1022
- /** The current sorting model. */
1023
- sortModel?: GridSortItem[];
1024
- /** Callback fired when the sorting model changes. */
1025
- onSortModelChange?: (model: GridSortItem[]) => void;
1026
- /**
1027
- * When true, clicking any sortable column header appends/cycles that column in the
1028
- * sort model instead of replacing it — no Shift key required. Plain click still
1029
- * cycles asc → desc → removed for that column while all other active sort keys stay.
1030
- * Shift+click continues to work regardless of this prop.
1031
- */
1032
- multiSort?: boolean;
1033
-
1034
- /** Filtering mode: 'client' (default) or 'server'. */
1035
- filterMode?: 'client' | 'server';
1036
- /** The current filter model. */
1037
- filterModel?: GridFilterModel;
1038
- /** Callback fired when the filter model changes. */
1039
- onFilterModelChange?: (model: GridFilterModel) => void;
1040
-
1041
- /** If true, pagination UI and logic are enabled. */
1042
- pagination?: boolean;
1043
- /** Pagination mode: 'client' (default), 'server', or 'infinite'. */
1044
- paginationMode?: 'client' | 'server' | 'infinite';
1045
- /** The current pagination state (page and pageSize). */
1046
- paginationModel?: GridPaginationModel;
1047
- /** Callback fired when the pagination model changes. */
1048
- onPaginationModelChange?: (model: GridPaginationModel) => void;
1049
- /** Array of available page sizes (e.g., [10, 25, 50]). */
1050
- pageSizeOptions?: number[];
1051
- /** Total number of rows (required for server-side pagination). */
1052
- rowCount?: number;
1053
-
1054
- /** Defines which columns are pinned to the sides. */
1055
- pinnedColumns?: GridColumnPinning;
1056
- /** Callback fired when column pinning changes. */
1057
- onPinnedColumnsChange?: (model: GridColumnPinning) => void;
1058
-
1059
- /** Controls which columns are visible. */
1060
- columnVisibilityModel?: GridColumnVisibilityModel;
1061
- /** Callback fired when column visibility changes. */
1062
- onColumnVisibilityModelChange?: (model: GridColumnVisibilityModel) => void;
1063
-
1064
- /** Defines which rows are pinned to the top or bottom. */
1065
- pinnedRows?: GridRowPinning;
1066
-
1067
- /** If true, a column of checkboxes is added for row selection. */
1068
- checkboxSelection?: boolean;
1069
- /** If true, the checkbox column remains visible during horizontal scrolling. */
1070
- pinCheckboxColumn?: boolean;
1071
- /** If true, the expansion column (for Master-Detail) remains visible during horizontal scrolling. */
1072
- pinExpandColumn?: boolean;
1073
- /** The current selection state (array of row IDs). */
1074
- rowSelectionModel?: GridRowSelectionModel;
1075
- /** Callback fired when the selection model changes. */
1076
- onRowSelectionModelChange?: (model: GridRowSelectionModel) => void;
1077
- /** If true, clicking a row won't toggle its selection. */
1078
- disableRowSelectionOnClick?: boolean;
1079
- /** If true, the user can only select a single row at a time. */
1080
- disableMultipleRowSelection?: boolean;
1081
- /**
1082
- * If true, Ctrl/Cmd+C does not copy the selected rows, so the page (or your own handler) owns
1083
- * the shortcut. `apiRef.current.copySelectedRows()` still works. Default: false.
1084
- */
1085
- disableClipboardCopy?: boolean;
1086
-
1087
- /**
1088
- * Lets users select a rectangle of cells (drag, Shift+click, Shift+arrows, Ctrl/Cmd+A) and copy it
1089
- * with Ctrl/Cmd+C as tab-separated text. While on, Ctrl/Cmd+C copies the cell range (the focused
1090
- * cell at minimum) instead of the selected rows; `apiRef.copySelectedRows()` still copies rows.
1091
- * Default: false. @since v3.3
1092
- */
1093
- cellSelection?: boolean;
1094
- /** Controlled cell selection (zero or one range). Needs `cellSelection`. @since v3.3 */
1095
- cellSelectionModel?: GridCellSelectionModel;
1096
- /** Fired when the cell selection changes, with what changed it. @since v3.3 */
1097
- onCellSelectionModelChange?: (model: GridCellSelectionModel, details: GridCellSelectionChangeDetails) => void;
1098
- /**
1099
- * Shows a status bar under the grid with the count of non-empty cells and the sum and average of the
1100
- * numeric cells in the range, while more than one cell is selected. Replaceable through
1101
- * `slots.cellSelectionStats`. Needs `cellSelection`. Default: false. @since v3.3
1102
- */
1103
- showCellSelectionStats?: boolean;
1104
-
1105
- /**
1106
- * With `cellSelection` on, Ctrl/Cmd+V pastes tab-separated text (Excel, Google Sheets) into the
1107
- * editable cells from the range's top-left cell (or the focused cell), through `valueSetter` and
1108
- * `processRowUpdate`. `true` turns the shortcut off; `apiRef.pasteText()` still works. Default: false.
1109
- * @since v3.4
1110
- */
1111
- disableClipboardPaste?: boolean;
1112
- /**
1113
- * Fired after every paste with the result (`updated` rows, `failed` rows, `skipped` cells and why)
1114
- * and the pasted text. @since v3.4
1115
- */
1116
- onClipboardPaste?: (result: GridClipboardPasteResult) => void;
1117
- /**
1118
- * Called before a paste is applied. Return `false` to cancel it, or a string to paste instead of the
1119
- * clipboard text. A throw cancels the paste. @since v3.4
1120
- */
1121
- onBeforeClipboardPaste?: (params: GridBeforeClipboardPasteParams) => boolean | string;
1122
- /**
1123
- * With `cellSelection` on, Delete / Backspace on a range of more than one cell empties its editable
1124
- * cells (`null`, or `''` in string columns) as one edit. `true` turns that off. Default: false.
1125
- * @since v3.4
1126
- */
1127
- disableRangeClear?: boolean;
1128
- /**
1129
- * Undo and redo of cell edits, pastes and range clears: Ctrl/Cmd+Z, Ctrl/Cmd+Shift+Z and Ctrl+Y while
1130
- * focus is in the grid and no editor is open, and `apiRef.undo()` / `redo()`. Undo and redo write
1131
- * through `valueSetter` and `processRowUpdate`, like an edit. `{ limit }` sets how many actions are
1132
- * kept (default 100). Default: false. @since v3.4
1133
- */
1134
- undoRedo?: boolean | GridUndoRedoOptions;
1135
- /** Fired when what can be undone or redone changes (`undoRedo`). @since v3.4 */
1136
- onHistoryChange?: (params: GridHistoryChangeParams) => void;
1137
- /**
1138
- * With `cellSelection` on, a fill handle sits on the bottom-right corner of the range: dragging it
1139
- * down, up, right or left fills the new cells from the range (a series of numbers or dates with an
1140
- * equal step continues, anything else repeats; Alt at release copies), and Ctrl/Cmd+D / Ctrl/Cmd+R
1141
- * fill down from the range's top row / right from its left column. `true` hides the handle and turns
1142
- * the shortcuts off. Default: false. @since v3.5
1143
- */
1144
- disableFillHandle?: boolean;
1145
- /** Fired after every fill with the result and its direction. @since v3.5 */
1146
- onFill?: (result: GridFillResult) => void;
1147
-
1148
- /** Loading state. With no rows the body shows skeleton rows (or `slots.loadingOverlay`); with rows, they stay and a progress bar (or `slots.loadingOverlay`) is shown over them. */
1149
- loading?: boolean;
1150
- /** Visual density of the grid. */
1151
- density?: 'compact' | 'standard' | 'comfortable';
1152
-
1153
- /** Optional custom CSS class for the grid container. */
1154
- className?: string;
1155
- /** Optional custom inline styles for the grid container. */
1156
- style?: React.CSSProperties;
1157
- /** Total height of the grid container (pixels or percentage). */
1158
- height?: number | string;
1159
-
1160
- /** ARIA label for accessibility. */
1161
- ariaLabel?: string;
1162
- /** Message displayed when there are no rows to show. */
1163
- noRowsLabel?: string;
1164
- /** Overrides for user-visible strings (i18n). All fields are optional. */
1165
- localeText?: GridLocaleText;
1166
-
1167
- /** Advanced: The starting internal state of the grid. */
1168
- initialState?: import('../state/types').GridInitialState;
1169
- /**
1170
- * Called on mount and whenever the value of the sorting, filter, pagination, columns (widths, order,
1171
- * visibility, pinning) or density state changes. Selection, expansion and editing do not call it.
1172
- */
1173
- onStateChange?: (state: import('../state/types').GridState) => void;
1174
-
1175
- /**
1176
- * Callback fired when a row is clicked. Tree-data parent rows are real rows: a click fires this and
1177
- * selects them like any row (the chevron expands them). Synthetic rows (row-grouping group rows,
1178
- * subtotal rows and auto-created tree parents) do not fire it: clicking a group row toggles it.
1179
- */
1180
- onRowClick?: (params: GridRowParams<R>) => void;
1181
- /**
1182
- * Callback fired when a row is double-clicked. Also fires for group rows; check
1183
- * `apiRef` / `rowMeta` if you only want leaf rows. Not fired when the double-click
1184
- * lands on the checkbox, expand icon, drag handle, or an open cell editor.
1185
- * @since v2.1
1186
- */
1187
- onRowDoubleClick?: (params: GridRowParams<R>) => void;
1188
- /** Callback fired when a cell is clicked. */
1189
- onCellClick?: (params: GridCellParams<R>) => void;
1190
-
1191
- /**
1192
- * Renders the detail panel content for a row in Master-Detail mode. Called for data rows only:
1193
- * synthetic group, subtotal and auto-created tree-parent rows have no detail panel.
1194
- */
1195
- getDetailPanelContent?: (params: GridDetailPanelParams<R>) => React.ReactNode;
1196
- /** Defines the height of the detail panel. Called for data rows only, like `getDetailPanelContent`. */
1197
- getDetailPanelHeight?: (params: GridDetailPanelParams<R>) => GridDetailPanelHeight;
1198
- /** Controlled state for expanded detail panels. */
1199
- detailPanelExpandedRowIds?: Set<GridRowId>;
1200
- /** Callback fired when expanded detail panels change. */
1201
- onDetailPanelExpandedRowIdsChange?: (expandedRowIds: Set<GridRowId>) => void;
1202
-
1203
- /** If true, manual column reordering via drag-and-drop is disabled. */
1204
- disableColumnReorder?: boolean;
1205
- /** Controlled horizontal order of column fields. */
1206
- columnOrder?: GridColumnOrder;
1207
- /**
1208
- * Fired when the user moves one column (header drag or Columns panel). `oldIndex` / `targetIndex`
1209
- * are positions in the grid's full column order: every current column, in order.
1210
- */
1211
- onColumnOrderChange?: (params: GridColumnOrderChangeParams) => void;
1212
- /**
1213
- * Fired with the whole new column order after every change: a header drag, a Columns panel drag
1214
- * and the panel's Reset. The easiest way to keep a controlled `columnOrder` in sync.
1215
- * Not fired for the generated columns of pivot mode.
1216
- */
1217
- onColumnOrderModelChange?: (columnOrder: GridColumnOrder) => void;
1218
-
1219
- /** If true, rows can be reordered via drag-and-drop. */
1220
- rowReordering?: boolean;
1221
- /** Callback fired when rows are reordered. */
1222
- onRowOrderChange?: (params: GridRowOrderChangeParams<R>) => void;
1223
-
1224
- /** If true, enables hierarchical tree data display. */
1225
- treeData?: boolean;
1226
- /**
1227
- * Function to get the path (array of strings) for a row in Tree Data mode. Required with `treeData`:
1228
- * without it the rows are shown flat. Segments may contain any character, including '/'. Keep the
1229
- * function identity stable (module scope or useCallback); a new function rebuilds the tree.
1230
- */
1231
- getTreeDataPath?: (row: R) => string[];
1232
- /**
1233
- * Adds a dedicated grouping column (pinned left) under row grouping or tree data, configured by these
1234
- * fields. Every key is optional: `field` is always `'__group__'` (a `field` you pass is ignored).
1235
- */
1236
- groupingColDef?: Partial<GridColDef<R>>;
1237
- /** Initial expansion depth for Tree Data. */
1238
- defaultGroupingExpansionDepth?: number;
1239
-
1240
- /**
1241
- * The row grouping model: the fields to group by, outermost first. Passing it controls grouping;
1242
- * without it the grid keeps its own model, which `apiRef.setRowGroupingModel` and the AI assistant change.
1243
- */
1244
- rowGroupingModel?: GridRowGroupingModel;
1245
- /** Fired when the row grouping model changes (`apiRef.setRowGroupingModel`, the AI assistant). @since v3.5 */
1246
- onRowGroupingModelChange?: (model: GridRowGroupingModel) => void;
1247
- /** Controlled state for data aggregation (e.g., { salary: 'sum' }). */
1248
- aggregationModel?: GridAggregationModel;
1249
- /** Callback fired when aggregation model changes. */
1250
- onAggregationModelChange?: (model: GridAggregationModel) => void;
1251
- /**
1252
- * Advanced: where aggregation results appear. Called for every group node (with its current
1253
- * `isExpanded`) and once with `null` for the grand total. `'inline'` (default for groups) shows them
1254
- * on the group row; `'footer'` on a subtotal row after the group's children while it is expanded
1255
- * (inline while collapsed); `null` hides them. For the grand total, `null` hides the footer row.
1256
- */
1257
- getAggregationPosition?: (groupNode: GridTreeNode | null) => 'inline' | 'footer' | null;
1258
-
1259
- /** If true, switches the grid to multidimensional Pivot Mode. */
1260
- pivotMode?: boolean;
1261
- /** Controlled state for pivot configuration (rows, columns, values). */
1262
- pivotModel?: GridPivotModel;
1263
- /** Callback fired when pivot model changes. */
1264
- onPivotModelChange?: (model: GridPivotModel) => void;
1265
-
1266
- /** Predicate to control cell editability on a per-cell basis. */
1267
- isCellEditable?: (params: GridCellParams<R>) => boolean;
1268
- /** Callback to process an updated row after inline editing. Supports promises and validation. */
1269
- processRowUpdate?: (newRow: R, oldRow: R) => R | Promise<R>;
1270
- /** Callback fired if `processRowUpdate` throws or rejects. */
1271
- onProcessRowUpdateError?: (error: unknown) => void;
1272
-
1273
- /** Interface for connecting the grid to an external (server-side) data source. */
1274
- dataSource?: GridDataSource<R>;
1275
- /** Callback fired when scrolling reaches the bottom of the grid viewport. */
1276
- onRowsScrollEnd?: (params: GridRowScrollEndParams) => void;
1277
-
1278
- /**
1279
- * Advanced: reactive reference to the internal API for imperative control. Pass
1280
- * `useGridApiRef<MyRow>()` to have the row getters typed as `MyRow`; a plain `useGridApiRef()` also works.
1281
- */
1282
- apiRef?: React.MutableRefObject<GridApi<R>> | React.MutableRefObject<GridApi>;
1283
-
1284
- /** Custom components to replace internal grid parts. */
1285
- slots?: {
1286
- /**
1287
- * Component rendered as the grid toolbar. Receives `GridToolbarSlotProps` (plus `slotProps.toolbar`),
1288
- * so it can be typed with `GridToolbarProps` or wrap the exported `GridToolbar`.
1289
- */
1290
- toolbar?: React.ComponentType<GridToolbarSlotProps & Record<string, unknown>>;
1291
- /**
1292
- * Component rendered as the pagination control. Receives `PaginationProps` (plus `slotProps.pagination`),
1293
- * so it can be typed with `PaginationProps` or wrap the exported `Pagination`.
1294
- */
1295
- pagination?: React.ComponentType<GridPaginationSlotProps & Record<string, unknown>>;
1296
- /** Component rendered when the grid is empty. Receives only `slotProps.noRowsOverlay`. */
1297
- noRowsOverlay?: React.ComponentType<GridOverlaySlotProps>;
1298
- /** Component rendered during loading states. Receives only `slotProps.loadingOverlay`. */
1299
- loadingOverlay?: React.ComponentType<GridOverlaySlotProps>;
1300
- /**
1301
- * Component rendered at the very bottom of the grid, in place of the pagination area.
1302
- * Receives `GridFooterSlotProps` (plus `slotProps.footer`).
1303
- */
1304
- footer?: React.ComponentType<GridFooterSlotProps & Record<string, unknown>>;
1305
- /**
1306
- * Replaces the status bar of `showCellSelectionStats`. Receives `GridCellSelectionStatsSlotProps`
1307
- * (plus `slotProps.cellSelectionStats`). @since v3.3
1308
- */
1309
- cellSelectionStats?: React.ComponentType<GridCellSelectionStatsSlotProps & Record<string, unknown>>;
1310
- /** Replaces the `aiAssistant` panel. Receives `GridAiAssistantPanelProps` while the panel is open. @since v3.5 */
1311
- aiAssistantPanel?: React.ComponentType<GridAiAssistantPanelProps & Record<string, unknown>>;
1312
- };
1313
- /** Properties passed directly to custom slots. */
1314
- slotProps?: {
1315
- /**
1316
- * Merged over the props the grid passes to the toolbar. Typed as `GridToolbarProps` (so render props
1317
- * such as `renderQuickFilter` are checked and their parameters inferred), plus any extra keys a custom
1318
- * toolbar reads. `columns` / `baseColumns` are not checked, so typed `GridColDef<R>[]` can be passed.
1319
- */
1320
- toolbar?: Omit<Partial<GridToolbarProps>, 'columns' | 'baseColumns'> & Record<string, unknown>;
1321
- /** Merged over the `PaginationProps` the grid passes to the pagination slot. */
1322
- pagination?: Partial<GridPaginationSlotProps> & Record<string, unknown>;
1323
- noRowsOverlay?: GridOverlaySlotProps;
1324
- loadingOverlay?: GridOverlaySlotProps;
1325
- /** Merged over the `GridFooterSlotProps` the grid passes to the footer slot. */
1326
- footer?: Partial<GridFooterSlotProps> & Record<string, unknown>;
1327
- /** Merged over the `GridCellSelectionStatsSlotProps` the grid passes to the status bar. */
1328
- cellSelectionStats?: Partial<GridCellSelectionStatsSlotProps> & Record<string, unknown>;
1329
- /** Extra props for `slots.aiAssistantPanel`. */
1330
- aiAssistantPanel?: Record<string, unknown>;
1331
- };
1332
-
1333
- /** When true, renders the grid as a single-column list of cards. Perfect for mobile/responsive views. */
1334
- listView?: boolean;
1335
- /** The column definition used in list view. Must supply a `renderCell` function. */
1336
- listViewColumn?: GridListViewColDef<R>;
1337
-
1338
- /**
1339
- * Defines column groups rendered as spanning header rows above the normal
1340
- * column headers, supporting multiple levels of nesting.
1341
- */
1342
- columnGroupingModel?: GridColumnGroupingModel;
1343
-
1344
- /**
1345
- * The "Ask AI" prompt panel: users describe the view they want and the grid applies the validated
1346
- * reply as one undoable step, shown as removable chips. The built-in toolbar shows an **Ask AI**
1347
- * button; `apiRef.openAiAssistant()` opens it without one. Build `onPrompt` with
1348
- * `createGridAiPromptHandler` from `@opencorestack/opengridx/ai`. @since v3.5
1349
- */
1350
- aiAssistant?: GridAiAssistantOptions;
1351
- /** Fired after the assistant applied a reply. @since v3.5 */
1352
- onAiAssistantApply?: (result: GridAiPromptResult) => void;
1353
- /** Fired when `onPrompt` fails or returns a result that was not validated. @since v3.5 */
1354
- onAiAssistantError?: (error: unknown) => void;
1355
- }
1356
-
1357
- /**
1358
- * `DataGridProps<R>` with untyped `columns` (`GridColDef[]`, i.e. `GridColDef<GridRowModel>[]`). `DataGrid`
1359
- * accepts these props as well as `DataGridProps<R>`, so columns written without a row type work with rows of
1360
- * any type `R`. Their callbacks then see `params.row` as `GridRowModel`; type the columns as
1361
- * `GridColDef<R>[]` to get your row type there.
1362
- * @since v3.0
1363
- */
1364
- export type DataGridUntypedColumnsProps<R extends GridValidRowModel = GridRowModel> =
1365
- Omit<DataGridProps<R>, 'columns'> & { columns: GridColDef[] };
1366
-
1367
- /**
1368
- * Props the grid passes to `slots.toolbar`, before `slotProps.toolbar` is merged over them: the
1369
- * `GridToolbarProps` it controls (columns, models and their change handlers) plus `apiRef`.
1370
- * @since v3.0
1371
- */
1372
- export interface GridToolbarSlotProps extends GridToolbarProps {
1373
- apiRef: React.MutableRefObject<GridApi>;
1374
- }
1375
-
1376
- /**
1377
- * Props the grid passes to `slots.pagination`, before `slotProps.pagination` is merged over them.
1378
- * @since v3.0
1379
- */
1380
- export type GridPaginationSlotProps = PaginationProps;
1381
-
1382
- /**
1383
- * Props of `slots.noRowsOverlay` and `slots.loadingOverlay`: the grid passes none of its own, only
1384
- * `slotProps.noRowsOverlay` / `slotProps.loadingOverlay`.
1385
- * @since v3.0
1386
- */
1387
- export type GridOverlaySlotProps = Record<string, unknown>;
1388
-
1389
- /**
1390
- * Props the grid passes to `slots.footer`, before `slotProps.footer` is merged over them.
1391
- * @since v3.0
1392
- */
1393
- export interface GridFooterSlotProps {
1394
- apiRef: React.MutableRefObject<GridApi>;
1395
- /** The active aggregation model (`{}` when none). */
1396
- aggregationModel: GridAggregationModel;
1397
- /** The grand-total aggregation result, or `null` when no aggregation is active. */
1398
- aggregationResult: GridAggregationResult | null;
1399
- /**
1400
- * The built-in pager's count: rows after filtering, pinned rows excluded (`rowCount` from the
1401
- * server in server pagination mode). Under tree data / row grouping: the filtered data rows.
1402
- */
1403
- rowCount: number;
1404
- /** Whether pagination is in effect (false under row grouping and infinite scroll). */
1405
- pagination: boolean;
1406
- paginationModel: GridPaginationModel;
1407
- pageSizeOptions: number[];
1408
- onPaginationModelChange: (model: GridPaginationModel) => void;
1409
- }
1410
-
1411
- /** The `slots` prop of `DataGrid`: components that replace built-in parts of the grid. */
1412
- export type GridSlots = NonNullable<DataGridProps['slots']>;
1413
-
1414
- /** The `slotProps` prop of `DataGrid`: props for each slot, keyed like `GridSlots`. */
1415
- export type GridSlotProps = NonNullable<DataGridProps['slotProps']>;
1416
-
1417
- export interface GridRowParams<R extends GridValidRowModel = GridRowModel> {
1418
- row: R;
1419
- id: GridRowId;
1420
- rowIndex: number;
1421
- }
1422
-
1423
- export interface GridCellParams<R extends GridValidRowModel = GridRowModel> {
1424
- row: R;
1425
- field: string;
1426
- value: unknown;
1427
- colDef: GridColDef<R>;
1428
- rowIndex: number;
1429
- colIndex: number;
1430
- }
1431
-
1432
- export interface GridDetailPanelParams<R extends GridValidRowModel = GridRowModel> {
1433
- row: R;
1434
- id: GridRowId;
1435
- rowIndex: number;
1436
- }
1437
-
1438
- export type GridDetailPanelHeight = number | 'auto';
1439
-
1440
- /**
1441
- * The Imperative API for interacting with the DataGrid.
1442
- * Access this via the `apiRef` prop or a ref passed to the component.
1443
- */
1444
- /**
1445
- * The imperative grid API. `R` types the row getters (`getRow`, `getAllRows`, `getVisibleRows`,
1446
- * `getAllFilteredRows`); it defaults to `GridRowModel`, so `GridApi` alone keeps working.
1447
- */
1448
- export interface GridApi<R extends GridValidRowModel = GridRowModel> {
1449
- /**
1450
- * Returns the row model with the given ID.
1451
- * @param id The row unique ID.
1452
- */
1453
- getRow: (id: GridRowId) => R | null;
1454
- /** Returns all rows currently loaded into the grid. */
1455
- getAllRows: () => R[];
1456
- /** Returns all rows currently visible after filtering and sorting. */
1457
- getVisibleRows: () => R[];
1458
- /** Returns all filtered and sorted rows, ignoring pagination. Use this for full-dataset exports. */
1459
- getAllFilteredRows: () => R[];
1460
- /**
1461
- * Returns an ordered flat list of `GridGroupedExportRow` entries that mirrors the
1462
- * on-screen grouping tree: group-headers, leaf rows, per-group subtotals, and a
1463
- * grand-total entry at the end. Returns `null` when no `rowGroupingModel` is active.
1464
- * Pass the result to export functions that accept a `groupedRows` option.
1465
- */
1466
- getGroupedExportRows: () => GridGroupedExportRow[] | null;
1467
- /** Returns the current aggregation results. */
1468
- getAggregationResult: () => Record<string, unknown> | null;
1469
- /** Returns the active aggregation configuration. */
1470
- getAggregationModel: () => GridAggregationModel | null;
1471
-
1472
- /** Returns the column definition for the given field. */
1473
- getColumn: (field: string) => GridColDef | null;
1474
- /** Returns all defined columns. */
1475
- getAllColumns: () => GridColDef[];
1476
- /** Returns all columns currently visible. */
1477
- getVisibleColumns: () => GridColDef[];
1478
-
1479
- /**
1480
- * Sets the selection state of a specific row.
1481
- * @param id The row unique ID.
1482
- * @param isSelected Visibility state.
1483
- */
1484
- selectRow: (id: GridRowId, isSelected?: boolean) => void;
1485
- /**
1486
- * Sets the selection state for multiple rows at once.
1487
- * @param ids Array of row IDs.
1488
- * @param isSelected Visibility state.
1489
- */
1490
- selectRows: (ids: GridRowId[], isSelected?: boolean) => void;
1491
- /** Returns an array of IDs for all currently selected rows. */
1492
- getSelectedRows: () => GridRowId[];
1493
-
1494
- /**
1495
- * Triggers sorting on a specific column.
1496
- * @param field The column field.
1497
- * @param direction Sort order ('asc', 'desc', or null to clear).
1498
- */
1499
- sortColumn: (field: string, direction: GridSortDirection) => void;
1500
- /** Returns the active sorting model. */
1501
- getSortModel: () => GridSortItem[];
1502
-
1503
- /** Programmatically sets the filtering model. */
1504
- setFilterModel: (model: GridFilterModel) => void;
1505
- /** Returns the current filtering model. */
1506
- getFilterModel: () => GridFilterModel;
1507
-
1508
- /** Changes the current page. */
1509
- setPage: (page: number) => void;
1510
- /** Changes the current page size. */
1511
- setPageSize: (pageSize: number) => void;
1512
-
1513
- /** Scrolls the grid viewport to a specific row or column index. */
1514
- scrollToIndexes: (params: { rowIndex?: number; colIndex?: number }) => void;
1515
-
1516
- /**
1517
- * Sizes a column to fit its header and the cells rendered right now (the virtualization window),
1518
- * clamped to `minWidth` (default 50px) / `maxWidth`, like double-clicking its resize handle.
1519
- * Does nothing for `resizable: false` columns or a column that is not rendered.
1520
- * A flex column gets a fixed width. @since v3.1
1521
- */
1522
- autosizeColumn: (field: string) => void;
1523
- /** `autosizeColumn` for several columns (default: every column). @since v3.1 */
1524
- autosizeColumns: (fields?: readonly string[]) => void;
1525
-
1526
- /**
1527
- * Programmatically copies all currently selected rows to the clipboard as TSV: every selected
1528
- * row that passes the filter (other pages, collapsed groups and pinned rows included), with the
1529
- * visible columns in screen order. Equivalent to the user pressing Ctrl+C / Cmd+C.
1530
- * @returns A Promise that resolves when the text is written (or when no selected row was found,
1531
- * in which case nothing is written) and rejects when the clipboard write fails.
1532
- */
1533
- copySelectedRows: () => Promise<void>;
1534
-
1535
- /** The cell selection (`[]` when `cellSelection` is off or nothing is selected). @since v3.3 */
1536
- getCellSelectionModel: () => GridCellSelectionModel;
1537
- /**
1538
- * Replaces the cell selection (only the first range is kept) and moves focus to its anchor.
1539
- * Does nothing while `cellSelection` is off. @since v3.3
1540
- */
1541
- setCellSelectionModel: (model: GridCellSelectionModel) => void;
1542
- /** Selects the rectangle between two cells; `anchor` becomes the active cell. @since v3.3 */
1543
- selectCellRange: (anchor: GridCellCoordinates, head: GridCellCoordinates) => void;
1544
- /** Empties the cell selection. Focus stays where it is. @since v3.3 */
1545
- clearCellSelection: () => void;
1546
- /**
1547
- * Cells of the current range in display order (row by row, columns in screen order), values read
1548
- * through the column's `valueGetter`. Synthetic rows (group headers, subtotals, tree auto-parents, the
1549
- * pivot Grand Total) and positions covered by a span are left out. @since v3.3
1550
- */
1551
- getSelectedCells: () => GridSelectedCell[];
1552
- /**
1553
- * Copies the cell range (the focused cell when nothing is selected) as tab-separated text, formatted
1554
- * the way the cells show it, with no header line. Resolves without writing when there is nothing to
1555
- * copy; rejects when the clipboard write fails. @since v3.3
1556
- */
1557
- copySelectedCells: () => Promise<void>;
1558
-
1559
- /**
1560
- * Pastes tab-separated text as Ctrl/Cmd+V does: from `anchor` (default: the range's top-left cell,
1561
- * else the focused cell), with `onBeforeClipboardPaste` and `onClipboardPaste`. Works with
1562
- * `disableClipboardPaste`. Resolves once every row's `processRowUpdate` has settled. @since v3.4
1563
- */
1564
- pasteText: (text: string, anchor?: GridCellCoordinates) => Promise<GridBatchEditResult>;
1565
- /** Undoes the last action (`undoRedo`). Resolves with what was written. @since v3.4 */
1566
- undo: () => Promise<GridBatchEditResult>;
1567
- /** Redoes the last undone action (`undoRedo`). @since v3.4 */
1568
- redo: () => Promise<GridBatchEditResult>;
1569
- /** Whether there is an action to undo. @since v3.4 */
1570
- canUndo: () => boolean;
1571
- /** Whether there is an undone action to redo. @since v3.4 */
1572
- canRedo: () => boolean;
1573
- /** Forgets every action (undo and redo). @since v3.4 */
1574
- clearHistory: () => void;
1575
-
1576
- /** Replaces the sort model (fires `onSortModelChange`). @since v3.5 */
1577
- setSortModel: (model: GridSortItem[]) => void;
1578
- /** Replaces the row grouping model (fires `onRowGroupingModelChange`). @since v3.5 */
1579
- setRowGroupingModel: (model: GridRowGroupingModel) => void;
1580
- /** Replaces the aggregation model (fires `onAggregationModelChange`). @since v3.5 */
1581
- setAggregationModel: (model: GridAggregationModel) => void;
1582
- /** Replaces the column visibility model (fires `onColumnVisibilityModelChange`). @since v3.5 */
1583
- setColumnVisibilityModel: (model: GridColumnVisibilityModel) => void;
1584
- /** Replaces the pivot model (fires `onPivotModelChange`). @since v3.5 */
1585
- setPivotModel: (model: GridPivotModel) => void;
1586
- /**
1587
- * The current filter, sort, grouping, aggregation, pivot and column visibility models, in the shape
1588
- * of the AI toolkit (`GridAiState`). @since v3.5
1589
- */
1590
- getGridAiState: () => GridAiState;
1591
- /** Opens the `aiAssistant` panel (does nothing without `aiAssistant`). @since v3.5 */
1592
- openAiAssistant: () => void;
1593
- /** Closes the `aiAssistant` panel. @since v3.5 */
1594
- closeAiAssistant: () => void;
1595
- }
1596
-
1597
- // ── AI toolkit (v3.4 state types; v3.5 assistant) ──────────────────────────────────────────────────
1598
- // Type-only and React-free: the `@opencorestack/opengridx/ai` entry point re-exports them.
1599
-
1600
- /** A part of the grid state a model may change. @since v3.4 */
1601
- export type GridAiPart = 'filter' | 'sort' | 'grouping' | 'aggregation' | 'pivot' | 'columnVisibility';
1602
-
1603
- /** Grid state as the AI toolkit reads and writes it. Only the parts present are applied. @since v3.4 */
1604
- export interface GridAiState {
1605
- filterModel?: GridFilterModel;
1606
- sortModel?: GridSortItem[];
1607
- rowGroupingModel?: GridRowGroupingModel;
1608
- aggregationModel?: GridAggregationModel;
1609
- pivotModel?: GridPivotModel;
1610
- columnVisibilityModel?: GridColumnVisibilityModel;
1611
- }
1612
-
1613
- /** One thing the validator dropped or could not use. `path` points into the model output. @since v3.4 */
1614
- export interface GridAiValidationError {
1615
- path: string;
1616
- message: string;
1617
- }
1618
-
1619
- /** One earlier prompt of this session and the state the assistant applied for it. @since v3.5 */
1620
- export interface GridAiHistoryEntry {
1621
- prompt: string;
1622
- applied: GridAiState;
1623
- }
1624
-
1625
- /** What `aiAssistant.onPrompt` receives next to the prompt. @since v3.5 */
1626
- export interface GridAiPromptContext {
1627
- /** The grid's current models (`apiRef.getGridAiState()`). */
1628
- currentState: GridAiState;
1629
- /** Earlier prompts of this session, oldest first. */
1630
- history: GridAiHistoryEntry[];
1631
- /** Aborted when the user presses Stop, sends another prompt or closes the panel. */
1632
- signal: AbortSignal;
1633
- }
1634
-
1635
- /**
1636
- * What `aiAssistant.onPrompt` resolves with. The grid applies it only when its `state` comes from
1637
- * `validateGridAiState` (or `createGridAiPromptHandler`), which brands the result and its `state`.
1638
- * @since v3.5
1639
- */
1640
- export interface GridAiPromptResult {
1641
- state: GridAiState;
1642
- /** What the validator dropped; shown as "Ignored: …". */
1643
- errors: GridAiValidationError[];
1644
- /** The assistant's reply text, shown in the panel. */
1645
- message?: string;
1646
- }
1647
-
1648
- /** The `aiAssistant` prop: the "Ask AI" prompt panel. @since v3.5 */
1649
- export interface GridAiAssistantOptions {
1650
- /**
1651
- * Answers a prompt. Call your own model and return the validated result: `createGridAiPromptHandler`
1652
- * from `@opencorestack/opengridx/ai` builds this function, or call `validateGridAiState` yourself.
1653
- */
1654
- onPrompt: (prompt: string, context: GridAiPromptContext) => Promise<GridAiPromptResult>;
1655
- /** Placeholder of the prompt input. Default: `"Ask about this table…"` */
1656
- placeholder?: string;
1657
- /** Example prompts shown as clickable chips. */
1658
- suggestions?: string[];
1659
- /** Shows a microphone button where the browser has speech recognition; the microphone is asked for only on click. Default: true. */
1660
- voice?: boolean;
1661
- /** The parts of the state the assistant may change. Default: every part. */
1662
- parts?: GridAiPart[];
1663
- }
1664
-
1665
- /** One change the assistant applied, shown as a removable chip. @since v3.5 */
1666
- export interface GridAiChip {
1667
- id: string;
1668
- part: GridAiPart;
1669
- label: string;
1670
- }
1671
-
1672
- /** The assistant panel's state. @since v3.5 */
1673
- export type GridAiAssistantStatus = 'idle' | 'running' | 'applied' | 'stopped' | 'error';
1674
-
1675
- /** Props of `slots.aiAssistantPanel` and the built-in panel, rendered while the panel is open. @since v3.5 */
1676
- export interface GridAiAssistantPanelProps {
1677
- status: GridAiAssistantStatus;
1678
- /** The status line: "Thinking…", "Applied 3 changes", an error. */
1679
- statusText: string;
1680
- /** The assistant's reply text (`result.message`). */
1681
- message: string | null;
1682
- /** What the last reply asked for that was ignored. */
1683
- errors: GridAiValidationError[];
1684
- /** The changes the last reply applied. */
1685
- chips: GridAiChip[];
1686
- /** Earlier prompts of this session, oldest first. */
1687
- history: GridAiHistoryEntry[];
1688
- suggestions: string[];
1689
- placeholder: string;
1690
- /** `voice` is on and this browser has speech recognition. */
1691
- voiceAvailable: boolean;
1692
- /** Undo can restore the state from before the last reply. */
1693
- canUndo: boolean;
1694
- submit: (prompt: string) => void;
1695
- /** Aborts the running request. */
1696
- stop: () => void;
1697
- /** Restores the state from before the last reply. */
1698
- undo: () => void;
1699
- /** Re-applies the last reply without this change. */
1700
- removeChip: (id: string) => void;
1701
- /** Closes the panel; focus returns to where it was before it opened. */
1702
- close: () => void;
1703
- }
2
+ * Public types of the grid, split by domain. Everything is re-exported from here, so
3
+ * imports from `types` keep working. Add a new type to the file for its domain.
4
+ */
5
+ export type * from './rows';
6
+ export type * from './columns';
7
+ export type * from './sorting';
8
+ export type * from './filtering';
9
+ export type * from './editing';
10
+ export type * from './export';
11
+ export type * from './dataSource';
12
+ export type * from './selection';
13
+ export type * from './grouping';
14
+ export type * from './state';
15
+ export type * from './locale';
16
+ export type * from './props';
17
+ export type * from './slots';
18
+ export type * from './api';
19
+ export type * from './ai';