@pretable/core 0.0.2 → 0.0.5

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.
package/dist/index.d.cts CHANGED
@@ -32,6 +32,55 @@ type PretableRow = Record<string, unknown>;
32
32
  * @public
33
33
  */
34
34
  type PretableSortDirection = "asc" | "desc" | null;
35
+ /**
36
+ * Phase of an in-progress cell edit.
37
+ *
38
+ * @public
39
+ */
40
+ type PretableEditStatus = "checking" | "editing" | "validating" | "saving" | "error";
41
+ /**
42
+ * Input passed to a column's edit hooks (`editable`, `validate`, `parseEditValue`,
43
+ * `formatEditValue`).
44
+ *
45
+ * @public
46
+ */
47
+ interface PretableEditInput<TRow extends PretableRow = PretableRow> {
48
+ rowId: string;
49
+ columnId: string;
50
+ row: TRow;
51
+ column: PretableColumn<TRow>;
52
+ value: unknown;
53
+ }
54
+ /**
55
+ * In-progress cell edit observed via `PretableGrid.getSnapshot().editing`.
56
+ * `error` carries the validation message (status `"editing"`) or the commit
57
+ * failure message (status `"error"`).
58
+ *
59
+ * @public
60
+ */
61
+ interface PretableEditState {
62
+ rowId: string;
63
+ columnId: string;
64
+ draft: unknown;
65
+ status: PretableEditStatus;
66
+ error?: string;
67
+ }
68
+ /** @public */
69
+ type ColumnType = "text" | "number" | "date" | "enum" | "boolean";
70
+ /** @public */
71
+ type FilterOperator = "contains" | "notContains" | "equals" | "notEquals" | "startsWith" | "endsWith" | "gt" | "gte" | "lt" | "lte" | "between" | "isAnyOf" | "isNoneOf" | "on" | "before" | "after" | "dateBetween" | "isEmpty" | "isNotEmpty";
72
+ /** @public */
73
+ type FilterValue = string | number | readonly [number, number] | readonly [string, string] | readonly string[] | null;
74
+ /** @public — one column's active filter. `value` is omitted for isEmpty/isNotEmpty. */
75
+ interface ColumnFilter {
76
+ operator: FilterOperator;
77
+ value?: FilterValue;
78
+ }
79
+ /** @public */
80
+ interface ColumnOption {
81
+ value: string;
82
+ label?: string;
83
+ }
35
84
  /**
36
85
  * Engine-level column definition. `@pretable/react` extends this with React-specific render fields.
37
86
  *
@@ -42,15 +91,27 @@ interface PretableColumn<TRow extends PretableRow = PretableRow> {
42
91
  header?: string;
43
92
  wrap?: boolean;
44
93
  widthPx?: number;
45
- pinned?: "left";
94
+ pinned?: "left" | "right";
46
95
  sortable?: boolean;
96
+ /** Number-editor increment for ArrowUp/Down and steppers. Default 1. */
97
+ step?: number;
47
98
  filterable?: boolean;
99
+ type?: ColumnType;
100
+ options?: ColumnOption[];
48
101
  value?: (row: TRow) => unknown;
49
102
  format?: (input: PretableFormatInput<TRow>) => string;
50
103
  minWidthPx?: number;
51
104
  maxWidthPx?: number;
52
105
  resizable?: boolean;
53
106
  reorderable?: boolean;
107
+ /** Group rows by this column by default; levels follow column order. */
108
+ rowGroup?: boolean;
109
+ /** Aggregate shown for this column on group rows. */
110
+ aggregate?: PretableAggregateSpec;
111
+ editable?: boolean | ((input: PretableEditInput<TRow>) => boolean | Promise<boolean>);
112
+ validate?: (value: unknown, input: PretableEditInput<TRow>) => (true | string) | Promise<true | string>;
113
+ parseEditValue?: (raw: string, input: PretableEditInput<TRow>) => unknown;
114
+ formatEditValue?: (value: unknown, input: PretableEditInput<TRow>) => string;
54
115
  }
55
116
  /**
56
117
  * Input passed to a column's `format` function.
@@ -72,15 +133,26 @@ interface PretableGridOptions<TRow extends PretableRow = PretableRow> {
72
133
  rows: TRow[];
73
134
  getRowId?: (row: TRow, index: number) => string;
74
135
  autosize?: boolean | AutosizeOptions;
136
+ /**
137
+ * Fold group aggregates over rows the active filter hides. Default `false`,
138
+ * so a group total always equals the sum of the rows visible beneath it.
139
+ * `childCount` is post-filter either way.
140
+ */
141
+ aggregateFilteredRows?: boolean;
142
+ /**
143
+ * Expanded state for groups with no entry in `groupExpansionOverrides`.
144
+ * Default `true`. Groups appearing mid-stream inherit it with no bookkeeping.
145
+ */
146
+ groupsDefaultExpanded?: boolean;
75
147
  }
76
148
  /**
77
- * Active sort. `columnId` is null when no column is sorted.
149
+ * One entry in the ordered sort list; index in the list = priority.
78
150
  *
79
151
  * @public
80
152
  */
81
- interface PretableSortState {
82
- columnId: string | null;
83
- direction: PretableSortDirection;
153
+ interface PretableSortEntry {
154
+ columnId: string;
155
+ direction: "asc" | "desc";
84
156
  }
85
157
  /**
86
158
  * Cell address — the (rowId, columnId) pair that uniquely identifies a cell.
@@ -142,15 +214,78 @@ interface PretableTransaction<TRow extends PretableRow = PretableRow> {
142
214
  remove?: string[];
143
215
  }
144
216
  /**
145
- * A row currently in the visible window — includes its source-array index for stable identity.
217
+ * A data row in the flat visible list — includes its source-array index for stable identity.
146
218
  *
147
219
  * @public
148
220
  */
149
- interface PretableVisibleRow<TRow extends PretableRow = PretableRow> {
221
+ interface PretableDataRow<TRow extends PretableRow = PretableRow> {
222
+ kind: "data";
150
223
  id: string;
151
224
  row: TRow;
152
225
  sourceIndex: number;
226
+ /** Nesting depth beneath its group ancestors; `0` when ungrouped. */
227
+ depth: number;
228
+ }
229
+ /**
230
+ * A group header row in the flat visible list.
231
+ *
232
+ * @public
233
+ */
234
+ interface PretableGroupRow {
235
+ kind: "group";
236
+ /** Stable, path-derived id (see `makeGroupId`). */
237
+ id: string;
238
+ /** Nesting depth; the outermost group level is `0`. */
239
+ depth: number;
240
+ /** The column this level groups by. */
241
+ columnId: string;
242
+ /** The group key value, as read from the grouping column. */
243
+ value: unknown;
244
+ /** Data rows beneath this group, post-filter. */
245
+ childCount: number;
246
+ /** Finalized aggregate values, keyed by column id. */
247
+ aggregates: Record<string, unknown>;
248
+ }
249
+ /**
250
+ * One entry in the flat visible-row list. The list stays flat — virtualization,
251
+ * selection ranges, focus and copy all depend on that — and the union is
252
+ * deliberately open: total/footer rows will join it later.
253
+ *
254
+ * @public
255
+ */
256
+ type PretableVisibleRow<TRow extends PretableRow = PretableRow> = PretableDataRow<TRow> | PretableGroupRow;
257
+ /**
258
+ * An aggregate function, defined as a monoid rather than as `(values) => result`.
259
+ *
260
+ * The engine folds over a group's descendant leaf rows (`init`, then
261
+ * `accumulate` per leaf, then `finalize`), so order-sensitive statistics such as
262
+ * median remain expressible. `merge` must nevertheless be associative with
263
+ * `init()` as its identity: that contract is what allows a future switch to
264
+ * child-aggregate rollup to be a pure internal optimization instead of a
265
+ * breaking change to every consumer's aggregate function.
266
+ *
267
+ * `accumulate` may mutate and return `acc` — the engine hands each fold a fresh
268
+ * `init()` and never retains an earlier accumulator. `merge` must NOT mutate
269
+ * either argument.
270
+ *
271
+ * @public
272
+ */
273
+ interface PretableAggregator<TAcc = unknown, TOut = unknown> {
274
+ /** Empty accumulator. */
275
+ init(): TAcc;
276
+ /** Fold one leaf cell value into the accumulator. */
277
+ accumulate(acc: TAcc, value: unknown, row: PretableRow): TAcc;
278
+ /** Combine two accumulators (must be associative; `init()` is the identity). */
279
+ merge(a: TAcc, b: TAcc): TAcc;
280
+ /** Produce the display value — always a plain scalar, never a wrapper object. */
281
+ finalize(acc: TAcc): TOut;
153
282
  }
283
+ /**
284
+ * A column's aggregate: a built-in name or a custom {@link PretableAggregator}.
285
+ *
286
+ * @public
287
+ */
288
+ type PretableAggregateSpec = "sum" | "avg" | "min" | "max" | "count" | PretableAggregator;
154
289
  /**
155
290
  * Read-only state observed via `PretableGrid.getSnapshot`.
156
291
  *
@@ -158,13 +293,20 @@ interface PretableVisibleRow<TRow extends PretableRow = PretableRow> {
158
293
  */
159
294
  interface PretableGridSnapshot<TRow extends PretableRow = PretableRow> {
160
295
  viewport: PretableViewportState;
161
- sort: PretableSortState;
162
- filters: Record<string, string>;
296
+ sort: PretableSortEntry[];
297
+ filters: Record<string, ColumnFilter>;
163
298
  selection: PretableSelectionState;
164
299
  focus: PretableFocusState;
165
300
  totalRowCount: number;
166
301
  visibleRows: PretableVisibleRow<TRow>[];
167
302
  visibleRange: PretableRowRange;
303
+ editing: PretableEditState | null;
304
+ /** Grouping columns, outermost first; `[]` when ungrouped. */
305
+ rowGroups: string[];
306
+ /** Group ids whose expanded state differs from {@link groupsDefaultExpanded}. */
307
+ groupExpansionOverrides: ReadonlySet<string>;
308
+ /** Expanded state for every group with no entry in the override set. */
309
+ groupsDefaultExpanded: boolean;
168
310
  }
169
311
  /**
170
312
  * Direction passed to `PretableGrid.moveFocus`.
@@ -207,9 +349,12 @@ interface PretableGrid<TRow extends PretableRow = PretableRow> {
207
349
  /** Read the current snapshot. Stable reference until the next mutation. */
208
350
  getSnapshot(): PretableGridSnapshot<TRow>;
209
351
  setSort(columnId: string | null, direction: PretableSortDirection): void;
210
- setFilter(columnId: string, value: string): void;
352
+ /** Atomically replace the ordered sort list. Unknown and `sortable: false` columns are dropped. */
353
+ replaceSort(entries: PretableSortEntry[]): void;
354
+ setColumnFilter(columnId: string, filter: ColumnFilter | null): void;
211
355
  clearFilters(): void;
212
- replaceFilters(nextFilters: Record<string, string>): void;
356
+ replaceFilters(nextFilters: Record<string, ColumnFilter>): void;
357
+ distinctColumnValues(columnId: string): string[];
213
358
  setSelection(state: PretableSelectionState): void;
214
359
  selectAll(): void;
215
360
  clearSelection(): void;
@@ -219,15 +364,57 @@ interface PretableGrid<TRow extends PretableRow = PretableRow> {
219
364
  setSelectAllVisible(checked: boolean): void;
220
365
  setFocus(addr: PretableCellAddress | null): void;
221
366
  moveFocus(direction: PretableFocusDirection, options?: PretableMoveFocusOptions): void;
367
+ /**
368
+ * Replace the grouping levels, outermost first; `[]` ungroups. Ids that do
369
+ * not match a column are dropped, and expansion state for groups that no
370
+ * longer exist is pruned.
371
+ */
372
+ setRowGroups(columnIds: readonly string[]): void;
373
+ /** Flip one group's expanded state. Unknown ids are still recorded. */
374
+ toggleGroup(groupId: string): void;
375
+ /** Set one group's expanded state explicitly. */
376
+ setGroupExpanded(groupId: string, expanded: boolean): void;
377
+ /** Expand every group, including ones that do not exist yet. */
378
+ expandAll(): void;
379
+ /** Collapse every group, including ones that do not exist yet. */
380
+ collapseAll(): void;
222
381
  setViewport(viewport: PretableViewportState): void;
223
382
  autosizeColumns(options?: AutosizeOptions): void;
224
383
  setColumnWidth(columnId: string, width: number): void;
225
384
  moveColumn(columnId: string, toIndex: number): void;
226
- setColumnPinned(columnId: string, pinned: "left" | null): void;
385
+ /**
386
+ * Set the relative order of the columns. Ids that do not match a column are
387
+ * ignored, and columns absent from `ids` keep their current relative order at
388
+ * the end. Pin state is never read from `ids` nor changed: the result is
389
+ * regrouped into `[pinned "left"…, unpinned…, pinned "right"…]`, so an order
390
+ * that interleaves pinned and unpinned columns is normalised rather than
391
+ * honoured literally.
392
+ */
393
+ setColumnOrder(ids: readonly string[]): void;
394
+ setColumnPinned(columnId: string, pinned: "left" | "right" | null): void;
227
395
  autosizeColumn(columnId: string, options?: AutosizeOptions): void;
228
396
  resetColumnLayout(): void;
229
397
  mergeColumnsFromProps(nextColumns: PretableColumn<TRow>[]): void;
230
398
  applyTransaction(transaction: PretableTransaction<TRow>): void;
399
+ /**
400
+ * Replace the full row set in place. Unlike recreating the grid, this
401
+ * preserves selection and focus (both keyed by row id), dropping only the
402
+ * references whose rows are no longer present. Suited to high-frequency
403
+ * updates where row identities are stable.
404
+ */
405
+ setRows(rows: TRow[]): void;
406
+ beginEdit(addr: PretableCellAddress, opts?: {
407
+ draft?: unknown;
408
+ status?: "checking" | "editing";
409
+ }): void;
410
+ setEditDraft(value: unknown): void;
411
+ markEditing(): void;
412
+ markEditValidating(): void;
413
+ markEditSaving(): void;
414
+ markEditInvalid(message: string): void;
415
+ markEditError(message: string): void;
416
+ commitEditSucceeded(): void;
417
+ cancelEdit(): void;
231
418
  }
232
419
 
233
420
  /**
@@ -248,4 +435,4 @@ interface PretableGrid<TRow extends PretableRow = PretableRow> {
248
435
  */
249
436
  declare function createGrid<TRow extends PretableRow = PretableRow>(options: PretableGridOptions<TRow>): PretableGrid<TRow>;
250
437
 
251
- export { type AutosizeOptions, type PretableCellAddress, type PretableCellRange, type PretableColumn, type PretableFocusDirection, type PretableFocusState, type PretableFormatInput, type PretableGrid, type PretableGridOptions, type PretableGridSnapshot, type PretableMoveFocusOptions, type PretableRow, type PretableRowRange, type PretableRowSelectionTriState, type PretableSelectionState, type PretableSortDirection, type PretableSortState, type PretableTransaction, type PretableViewportState, type PretableVisibleRow, createGrid };
438
+ export { type AutosizeOptions, type ColumnFilter, type ColumnOption, type ColumnType, type FilterOperator, type FilterValue, type PretableAggregateSpec, type PretableAggregator, type PretableCellAddress, type PretableCellRange, type PretableColumn, type PretableDataRow, type PretableEditInput, type PretableEditState, type PretableEditStatus, type PretableFocusDirection, type PretableFocusState, type PretableFormatInput, type PretableGrid, type PretableGridOptions, type PretableGridSnapshot, type PretableGroupRow, type PretableMoveFocusOptions, type PretableRow, type PretableRowRange, type PretableRowSelectionTriState, type PretableSelectionState, type PretableSortDirection, type PretableSortEntry, type PretableTransaction, type PretableViewportState, type PretableVisibleRow, createGrid };
package/dist/index.d.ts CHANGED
@@ -32,6 +32,55 @@ type PretableRow = Record<string, unknown>;
32
32
  * @public
33
33
  */
34
34
  type PretableSortDirection = "asc" | "desc" | null;
35
+ /**
36
+ * Phase of an in-progress cell edit.
37
+ *
38
+ * @public
39
+ */
40
+ type PretableEditStatus = "checking" | "editing" | "validating" | "saving" | "error";
41
+ /**
42
+ * Input passed to a column's edit hooks (`editable`, `validate`, `parseEditValue`,
43
+ * `formatEditValue`).
44
+ *
45
+ * @public
46
+ */
47
+ interface PretableEditInput<TRow extends PretableRow = PretableRow> {
48
+ rowId: string;
49
+ columnId: string;
50
+ row: TRow;
51
+ column: PretableColumn<TRow>;
52
+ value: unknown;
53
+ }
54
+ /**
55
+ * In-progress cell edit observed via `PretableGrid.getSnapshot().editing`.
56
+ * `error` carries the validation message (status `"editing"`) or the commit
57
+ * failure message (status `"error"`).
58
+ *
59
+ * @public
60
+ */
61
+ interface PretableEditState {
62
+ rowId: string;
63
+ columnId: string;
64
+ draft: unknown;
65
+ status: PretableEditStatus;
66
+ error?: string;
67
+ }
68
+ /** @public */
69
+ type ColumnType = "text" | "number" | "date" | "enum" | "boolean";
70
+ /** @public */
71
+ type FilterOperator = "contains" | "notContains" | "equals" | "notEquals" | "startsWith" | "endsWith" | "gt" | "gte" | "lt" | "lte" | "between" | "isAnyOf" | "isNoneOf" | "on" | "before" | "after" | "dateBetween" | "isEmpty" | "isNotEmpty";
72
+ /** @public */
73
+ type FilterValue = string | number | readonly [number, number] | readonly [string, string] | readonly string[] | null;
74
+ /** @public — one column's active filter. `value` is omitted for isEmpty/isNotEmpty. */
75
+ interface ColumnFilter {
76
+ operator: FilterOperator;
77
+ value?: FilterValue;
78
+ }
79
+ /** @public */
80
+ interface ColumnOption {
81
+ value: string;
82
+ label?: string;
83
+ }
35
84
  /**
36
85
  * Engine-level column definition. `@pretable/react` extends this with React-specific render fields.
37
86
  *
@@ -42,15 +91,27 @@ interface PretableColumn<TRow extends PretableRow = PretableRow> {
42
91
  header?: string;
43
92
  wrap?: boolean;
44
93
  widthPx?: number;
45
- pinned?: "left";
94
+ pinned?: "left" | "right";
46
95
  sortable?: boolean;
96
+ /** Number-editor increment for ArrowUp/Down and steppers. Default 1. */
97
+ step?: number;
47
98
  filterable?: boolean;
99
+ type?: ColumnType;
100
+ options?: ColumnOption[];
48
101
  value?: (row: TRow) => unknown;
49
102
  format?: (input: PretableFormatInput<TRow>) => string;
50
103
  minWidthPx?: number;
51
104
  maxWidthPx?: number;
52
105
  resizable?: boolean;
53
106
  reorderable?: boolean;
107
+ /** Group rows by this column by default; levels follow column order. */
108
+ rowGroup?: boolean;
109
+ /** Aggregate shown for this column on group rows. */
110
+ aggregate?: PretableAggregateSpec;
111
+ editable?: boolean | ((input: PretableEditInput<TRow>) => boolean | Promise<boolean>);
112
+ validate?: (value: unknown, input: PretableEditInput<TRow>) => (true | string) | Promise<true | string>;
113
+ parseEditValue?: (raw: string, input: PretableEditInput<TRow>) => unknown;
114
+ formatEditValue?: (value: unknown, input: PretableEditInput<TRow>) => string;
54
115
  }
55
116
  /**
56
117
  * Input passed to a column's `format` function.
@@ -72,15 +133,26 @@ interface PretableGridOptions<TRow extends PretableRow = PretableRow> {
72
133
  rows: TRow[];
73
134
  getRowId?: (row: TRow, index: number) => string;
74
135
  autosize?: boolean | AutosizeOptions;
136
+ /**
137
+ * Fold group aggregates over rows the active filter hides. Default `false`,
138
+ * so a group total always equals the sum of the rows visible beneath it.
139
+ * `childCount` is post-filter either way.
140
+ */
141
+ aggregateFilteredRows?: boolean;
142
+ /**
143
+ * Expanded state for groups with no entry in `groupExpansionOverrides`.
144
+ * Default `true`. Groups appearing mid-stream inherit it with no bookkeeping.
145
+ */
146
+ groupsDefaultExpanded?: boolean;
75
147
  }
76
148
  /**
77
- * Active sort. `columnId` is null when no column is sorted.
149
+ * One entry in the ordered sort list; index in the list = priority.
78
150
  *
79
151
  * @public
80
152
  */
81
- interface PretableSortState {
82
- columnId: string | null;
83
- direction: PretableSortDirection;
153
+ interface PretableSortEntry {
154
+ columnId: string;
155
+ direction: "asc" | "desc";
84
156
  }
85
157
  /**
86
158
  * Cell address — the (rowId, columnId) pair that uniquely identifies a cell.
@@ -142,15 +214,78 @@ interface PretableTransaction<TRow extends PretableRow = PretableRow> {
142
214
  remove?: string[];
143
215
  }
144
216
  /**
145
- * A row currently in the visible window — includes its source-array index for stable identity.
217
+ * A data row in the flat visible list — includes its source-array index for stable identity.
146
218
  *
147
219
  * @public
148
220
  */
149
- interface PretableVisibleRow<TRow extends PretableRow = PretableRow> {
221
+ interface PretableDataRow<TRow extends PretableRow = PretableRow> {
222
+ kind: "data";
150
223
  id: string;
151
224
  row: TRow;
152
225
  sourceIndex: number;
226
+ /** Nesting depth beneath its group ancestors; `0` when ungrouped. */
227
+ depth: number;
228
+ }
229
+ /**
230
+ * A group header row in the flat visible list.
231
+ *
232
+ * @public
233
+ */
234
+ interface PretableGroupRow {
235
+ kind: "group";
236
+ /** Stable, path-derived id (see `makeGroupId`). */
237
+ id: string;
238
+ /** Nesting depth; the outermost group level is `0`. */
239
+ depth: number;
240
+ /** The column this level groups by. */
241
+ columnId: string;
242
+ /** The group key value, as read from the grouping column. */
243
+ value: unknown;
244
+ /** Data rows beneath this group, post-filter. */
245
+ childCount: number;
246
+ /** Finalized aggregate values, keyed by column id. */
247
+ aggregates: Record<string, unknown>;
248
+ }
249
+ /**
250
+ * One entry in the flat visible-row list. The list stays flat — virtualization,
251
+ * selection ranges, focus and copy all depend on that — and the union is
252
+ * deliberately open: total/footer rows will join it later.
253
+ *
254
+ * @public
255
+ */
256
+ type PretableVisibleRow<TRow extends PretableRow = PretableRow> = PretableDataRow<TRow> | PretableGroupRow;
257
+ /**
258
+ * An aggregate function, defined as a monoid rather than as `(values) => result`.
259
+ *
260
+ * The engine folds over a group's descendant leaf rows (`init`, then
261
+ * `accumulate` per leaf, then `finalize`), so order-sensitive statistics such as
262
+ * median remain expressible. `merge` must nevertheless be associative with
263
+ * `init()` as its identity: that contract is what allows a future switch to
264
+ * child-aggregate rollup to be a pure internal optimization instead of a
265
+ * breaking change to every consumer's aggregate function.
266
+ *
267
+ * `accumulate` may mutate and return `acc` — the engine hands each fold a fresh
268
+ * `init()` and never retains an earlier accumulator. `merge` must NOT mutate
269
+ * either argument.
270
+ *
271
+ * @public
272
+ */
273
+ interface PretableAggregator<TAcc = unknown, TOut = unknown> {
274
+ /** Empty accumulator. */
275
+ init(): TAcc;
276
+ /** Fold one leaf cell value into the accumulator. */
277
+ accumulate(acc: TAcc, value: unknown, row: PretableRow): TAcc;
278
+ /** Combine two accumulators (must be associative; `init()` is the identity). */
279
+ merge(a: TAcc, b: TAcc): TAcc;
280
+ /** Produce the display value — always a plain scalar, never a wrapper object. */
281
+ finalize(acc: TAcc): TOut;
153
282
  }
283
+ /**
284
+ * A column's aggregate: a built-in name or a custom {@link PretableAggregator}.
285
+ *
286
+ * @public
287
+ */
288
+ type PretableAggregateSpec = "sum" | "avg" | "min" | "max" | "count" | PretableAggregator;
154
289
  /**
155
290
  * Read-only state observed via `PretableGrid.getSnapshot`.
156
291
  *
@@ -158,13 +293,20 @@ interface PretableVisibleRow<TRow extends PretableRow = PretableRow> {
158
293
  */
159
294
  interface PretableGridSnapshot<TRow extends PretableRow = PretableRow> {
160
295
  viewport: PretableViewportState;
161
- sort: PretableSortState;
162
- filters: Record<string, string>;
296
+ sort: PretableSortEntry[];
297
+ filters: Record<string, ColumnFilter>;
163
298
  selection: PretableSelectionState;
164
299
  focus: PretableFocusState;
165
300
  totalRowCount: number;
166
301
  visibleRows: PretableVisibleRow<TRow>[];
167
302
  visibleRange: PretableRowRange;
303
+ editing: PretableEditState | null;
304
+ /** Grouping columns, outermost first; `[]` when ungrouped. */
305
+ rowGroups: string[];
306
+ /** Group ids whose expanded state differs from {@link groupsDefaultExpanded}. */
307
+ groupExpansionOverrides: ReadonlySet<string>;
308
+ /** Expanded state for every group with no entry in the override set. */
309
+ groupsDefaultExpanded: boolean;
168
310
  }
169
311
  /**
170
312
  * Direction passed to `PretableGrid.moveFocus`.
@@ -207,9 +349,12 @@ interface PretableGrid<TRow extends PretableRow = PretableRow> {
207
349
  /** Read the current snapshot. Stable reference until the next mutation. */
208
350
  getSnapshot(): PretableGridSnapshot<TRow>;
209
351
  setSort(columnId: string | null, direction: PretableSortDirection): void;
210
- setFilter(columnId: string, value: string): void;
352
+ /** Atomically replace the ordered sort list. Unknown and `sortable: false` columns are dropped. */
353
+ replaceSort(entries: PretableSortEntry[]): void;
354
+ setColumnFilter(columnId: string, filter: ColumnFilter | null): void;
211
355
  clearFilters(): void;
212
- replaceFilters(nextFilters: Record<string, string>): void;
356
+ replaceFilters(nextFilters: Record<string, ColumnFilter>): void;
357
+ distinctColumnValues(columnId: string): string[];
213
358
  setSelection(state: PretableSelectionState): void;
214
359
  selectAll(): void;
215
360
  clearSelection(): void;
@@ -219,15 +364,57 @@ interface PretableGrid<TRow extends PretableRow = PretableRow> {
219
364
  setSelectAllVisible(checked: boolean): void;
220
365
  setFocus(addr: PretableCellAddress | null): void;
221
366
  moveFocus(direction: PretableFocusDirection, options?: PretableMoveFocusOptions): void;
367
+ /**
368
+ * Replace the grouping levels, outermost first; `[]` ungroups. Ids that do
369
+ * not match a column are dropped, and expansion state for groups that no
370
+ * longer exist is pruned.
371
+ */
372
+ setRowGroups(columnIds: readonly string[]): void;
373
+ /** Flip one group's expanded state. Unknown ids are still recorded. */
374
+ toggleGroup(groupId: string): void;
375
+ /** Set one group's expanded state explicitly. */
376
+ setGroupExpanded(groupId: string, expanded: boolean): void;
377
+ /** Expand every group, including ones that do not exist yet. */
378
+ expandAll(): void;
379
+ /** Collapse every group, including ones that do not exist yet. */
380
+ collapseAll(): void;
222
381
  setViewport(viewport: PretableViewportState): void;
223
382
  autosizeColumns(options?: AutosizeOptions): void;
224
383
  setColumnWidth(columnId: string, width: number): void;
225
384
  moveColumn(columnId: string, toIndex: number): void;
226
- setColumnPinned(columnId: string, pinned: "left" | null): void;
385
+ /**
386
+ * Set the relative order of the columns. Ids that do not match a column are
387
+ * ignored, and columns absent from `ids` keep their current relative order at
388
+ * the end. Pin state is never read from `ids` nor changed: the result is
389
+ * regrouped into `[pinned "left"…, unpinned…, pinned "right"…]`, so an order
390
+ * that interleaves pinned and unpinned columns is normalised rather than
391
+ * honoured literally.
392
+ */
393
+ setColumnOrder(ids: readonly string[]): void;
394
+ setColumnPinned(columnId: string, pinned: "left" | "right" | null): void;
227
395
  autosizeColumn(columnId: string, options?: AutosizeOptions): void;
228
396
  resetColumnLayout(): void;
229
397
  mergeColumnsFromProps(nextColumns: PretableColumn<TRow>[]): void;
230
398
  applyTransaction(transaction: PretableTransaction<TRow>): void;
399
+ /**
400
+ * Replace the full row set in place. Unlike recreating the grid, this
401
+ * preserves selection and focus (both keyed by row id), dropping only the
402
+ * references whose rows are no longer present. Suited to high-frequency
403
+ * updates where row identities are stable.
404
+ */
405
+ setRows(rows: TRow[]): void;
406
+ beginEdit(addr: PretableCellAddress, opts?: {
407
+ draft?: unknown;
408
+ status?: "checking" | "editing";
409
+ }): void;
410
+ setEditDraft(value: unknown): void;
411
+ markEditing(): void;
412
+ markEditValidating(): void;
413
+ markEditSaving(): void;
414
+ markEditInvalid(message: string): void;
415
+ markEditError(message: string): void;
416
+ commitEditSucceeded(): void;
417
+ cancelEdit(): void;
231
418
  }
232
419
 
233
420
  /**
@@ -248,4 +435,4 @@ interface PretableGrid<TRow extends PretableRow = PretableRow> {
248
435
  */
249
436
  declare function createGrid<TRow extends PretableRow = PretableRow>(options: PretableGridOptions<TRow>): PretableGrid<TRow>;
250
437
 
251
- export { type AutosizeOptions, type PretableCellAddress, type PretableCellRange, type PretableColumn, type PretableFocusDirection, type PretableFocusState, type PretableFormatInput, type PretableGrid, type PretableGridOptions, type PretableGridSnapshot, type PretableMoveFocusOptions, type PretableRow, type PretableRowRange, type PretableRowSelectionTriState, type PretableSelectionState, type PretableSortDirection, type PretableSortState, type PretableTransaction, type PretableViewportState, type PretableVisibleRow, createGrid };
438
+ export { type AutosizeOptions, type ColumnFilter, type ColumnOption, type ColumnType, type FilterOperator, type FilterValue, type PretableAggregateSpec, type PretableAggregator, type PretableCellAddress, type PretableCellRange, type PretableColumn, type PretableDataRow, type PretableEditInput, type PretableEditState, type PretableEditStatus, type PretableFocusDirection, type PretableFocusState, type PretableFormatInput, type PretableGrid, type PretableGridOptions, type PretableGridSnapshot, type PretableGroupRow, type PretableMoveFocusOptions, type PretableRow, type PretableRowRange, type PretableRowSelectionTriState, type PretableSelectionState, type PretableSortDirection, type PretableSortEntry, type PretableTransaction, type PretableViewportState, type PretableVisibleRow, createGrid };