@pretable/core 0.0.3 → 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
@@ -104,6 +104,10 @@ interface PretableColumn<TRow extends PretableRow = PretableRow> {
104
104
  maxWidthPx?: number;
105
105
  resizable?: boolean;
106
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;
107
111
  editable?: boolean | ((input: PretableEditInput<TRow>) => boolean | Promise<boolean>);
108
112
  validate?: (value: unknown, input: PretableEditInput<TRow>) => (true | string) | Promise<true | string>;
109
113
  parseEditValue?: (raw: string, input: PretableEditInput<TRow>) => unknown;
@@ -129,6 +133,17 @@ interface PretableGridOptions<TRow extends PretableRow = PretableRow> {
129
133
  rows: TRow[];
130
134
  getRowId?: (row: TRow, index: number) => string;
131
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;
132
147
  }
133
148
  /**
134
149
  * One entry in the ordered sort list; index in the list = priority.
@@ -199,15 +214,78 @@ interface PretableTransaction<TRow extends PretableRow = PretableRow> {
199
214
  remove?: string[];
200
215
  }
201
216
  /**
202
- * 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.
203
218
  *
204
219
  * @public
205
220
  */
206
- interface PretableVisibleRow<TRow extends PretableRow = PretableRow> {
221
+ interface PretableDataRow<TRow extends PretableRow = PretableRow> {
222
+ kind: "data";
207
223
  id: string;
208
224
  row: TRow;
209
225
  sourceIndex: number;
226
+ /** Nesting depth beneath its group ancestors; `0` when ungrouped. */
227
+ depth: number;
210
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;
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;
211
289
  /**
212
290
  * Read-only state observed via `PretableGrid.getSnapshot`.
213
291
  *
@@ -223,6 +301,12 @@ interface PretableGridSnapshot<TRow extends PretableRow = PretableRow> {
223
301
  visibleRows: PretableVisibleRow<TRow>[];
224
302
  visibleRange: PretableRowRange;
225
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;
226
310
  }
227
311
  /**
228
312
  * Direction passed to `PretableGrid.moveFocus`.
@@ -280,6 +364,20 @@ interface PretableGrid<TRow extends PretableRow = PretableRow> {
280
364
  setSelectAllVisible(checked: boolean): void;
281
365
  setFocus(addr: PretableCellAddress | null): void;
282
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;
283
381
  setViewport(viewport: PretableViewportState): void;
284
382
  autosizeColumns(options?: AutosizeOptions): void;
285
383
  setColumnWidth(columnId: string, width: number): void;
@@ -337,4 +435,4 @@ interface PretableGrid<TRow extends PretableRow = PretableRow> {
337
435
  */
338
436
  declare function createGrid<TRow extends PretableRow = PretableRow>(options: PretableGridOptions<TRow>): PretableGrid<TRow>;
339
437
 
340
- export { type AutosizeOptions, type ColumnFilter, type ColumnOption, type ColumnType, type FilterOperator, type FilterValue, type PretableCellAddress, type PretableCellRange, type PretableColumn, type PretableEditInput, type PretableEditState, type PretableEditStatus, 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 PretableSortEntry, 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
@@ -104,6 +104,10 @@ interface PretableColumn<TRow extends PretableRow = PretableRow> {
104
104
  maxWidthPx?: number;
105
105
  resizable?: boolean;
106
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;
107
111
  editable?: boolean | ((input: PretableEditInput<TRow>) => boolean | Promise<boolean>);
108
112
  validate?: (value: unknown, input: PretableEditInput<TRow>) => (true | string) | Promise<true | string>;
109
113
  parseEditValue?: (raw: string, input: PretableEditInput<TRow>) => unknown;
@@ -129,6 +133,17 @@ interface PretableGridOptions<TRow extends PretableRow = PretableRow> {
129
133
  rows: TRow[];
130
134
  getRowId?: (row: TRow, index: number) => string;
131
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;
132
147
  }
133
148
  /**
134
149
  * One entry in the ordered sort list; index in the list = priority.
@@ -199,15 +214,78 @@ interface PretableTransaction<TRow extends PretableRow = PretableRow> {
199
214
  remove?: string[];
200
215
  }
201
216
  /**
202
- * 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.
203
218
  *
204
219
  * @public
205
220
  */
206
- interface PretableVisibleRow<TRow extends PretableRow = PretableRow> {
221
+ interface PretableDataRow<TRow extends PretableRow = PretableRow> {
222
+ kind: "data";
207
223
  id: string;
208
224
  row: TRow;
209
225
  sourceIndex: number;
226
+ /** Nesting depth beneath its group ancestors; `0` when ungrouped. */
227
+ depth: number;
210
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;
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;
211
289
  /**
212
290
  * Read-only state observed via `PretableGrid.getSnapshot`.
213
291
  *
@@ -223,6 +301,12 @@ interface PretableGridSnapshot<TRow extends PretableRow = PretableRow> {
223
301
  visibleRows: PretableVisibleRow<TRow>[];
224
302
  visibleRange: PretableRowRange;
225
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;
226
310
  }
227
311
  /**
228
312
  * Direction passed to `PretableGrid.moveFocus`.
@@ -280,6 +364,20 @@ interface PretableGrid<TRow extends PretableRow = PretableRow> {
280
364
  setSelectAllVisible(checked: boolean): void;
281
365
  setFocus(addr: PretableCellAddress | null): void;
282
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;
283
381
  setViewport(viewport: PretableViewportState): void;
284
382
  autosizeColumns(options?: AutosizeOptions): void;
285
383
  setColumnWidth(columnId: string, width: number): void;
@@ -337,4 +435,4 @@ interface PretableGrid<TRow extends PretableRow = PretableRow> {
337
435
  */
338
436
  declare function createGrid<TRow extends PretableRow = PretableRow>(options: PretableGridOptions<TRow>): PretableGrid<TRow>;
339
437
 
340
- export { type AutosizeOptions, type ColumnFilter, type ColumnOption, type ColumnType, type FilterOperator, type FilterValue, type PretableCellAddress, type PretableCellRange, type PretableColumn, type PretableEditInput, type PretableEditState, type PretableEditStatus, 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 PretableSortEntry, 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 };