@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.cjs +985 -113
- package/dist/index.d.cts +200 -13
- package/dist/index.d.ts +200 -13
- package/dist/index.mjs +985 -113
- package/package.json +1 -1
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
|
-
*
|
|
149
|
+
* One entry in the ordered sort list; index in the list = priority.
|
|
78
150
|
*
|
|
79
151
|
* @public
|
|
80
152
|
*/
|
|
81
|
-
interface
|
|
82
|
-
columnId: string
|
|
83
|
-
direction:
|
|
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
|
|
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
|
|
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:
|
|
162
|
-
filters: Record<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
|
-
|
|
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,
|
|
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
|
-
|
|
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
|
|
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
|
-
*
|
|
149
|
+
* One entry in the ordered sort list; index in the list = priority.
|
|
78
150
|
*
|
|
79
151
|
* @public
|
|
80
152
|
*/
|
|
81
|
-
interface
|
|
82
|
-
columnId: string
|
|
83
|
-
direction:
|
|
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
|
|
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
|
|
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:
|
|
162
|
-
filters: Record<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
|
-
|
|
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,
|
|
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
|
-
|
|
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
|
|
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 };
|