@pretable/core 0.0.3 → 0.0.6

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
@@ -102,8 +102,21 @@ interface PretableColumn<TRow extends PretableRow = PretableRow> {
102
102
  format?: (input: PretableFormatInput<TRow>) => string;
103
103
  minWidthPx?: number;
104
104
  maxWidthPx?: number;
105
+ /**
106
+ * Share of the width the fixed columns leave over, so the row ends exactly at
107
+ * the viewport edge instead of underfilling or overflowing it. Weights are
108
+ * relative: two columns at `flex: 1` split the remainder evenly, `1` and `3`
109
+ * split it a quarter to three quarters. `minWidthPx`/`maxWidthPx` still
110
+ * apply, and a column that has been resized (which sets `widthPx`) stops
111
+ * flexing — an explicit width outranks a computed one.
112
+ */
113
+ flex?: number;
105
114
  resizable?: boolean;
106
115
  reorderable?: boolean;
116
+ /** Group rows by this column by default; levels follow column order. */
117
+ rowGroup?: boolean;
118
+ /** Aggregate shown for this column on group rows. */
119
+ aggregate?: PretableAggregateSpec;
107
120
  editable?: boolean | ((input: PretableEditInput<TRow>) => boolean | Promise<boolean>);
108
121
  validate?: (value: unknown, input: PretableEditInput<TRow>) => (true | string) | Promise<true | string>;
109
122
  parseEditValue?: (raw: string, input: PretableEditInput<TRow>) => unknown;
@@ -129,6 +142,36 @@ interface PretableGridOptions<TRow extends PretableRow = PretableRow> {
129
142
  rows: TRow[];
130
143
  getRowId?: (row: TRow, index: number) => string;
131
144
  autosize?: boolean | AutosizeOptions;
145
+ /**
146
+ * Fold group aggregates over rows the active filter hides. Default `false`,
147
+ * so a group total always equals the sum of the rows visible beneath it.
148
+ * `childCount` is post-filter either way.
149
+ */
150
+ aggregateFilteredRows?: boolean;
151
+ /**
152
+ * Expanded state for groups with no entry in `groupExpansionOverrides`.
153
+ * Default `true`. Groups appearing mid-stream inherit it with no bookkeeping.
154
+ */
155
+ groupsDefaultExpanded?: boolean;
156
+ /**
157
+ * How many per-group expand/collapse decisions the grid remembers. Default
158
+ * `10_000`. Past the limit the least-recently-decided group is forgotten and
159
+ * reverts to `groupsDefaultExpanded`.
160
+ *
161
+ * **Why a limit exists.** Expansion state is keyed by a path-derived group id
162
+ * rather than owned by a node, which is what lets a group survive emptying and
163
+ * returning mid-stream. The price is that ids for groups which never return
164
+ * would otherwise accumulate forever under a stream whose grouping keys churn.
165
+ *
166
+ * Values below 1 clamp to 1; a non-finite value other than `Infinity` falls
167
+ * back to the default. Pass `Infinity` to opt out of the cap entirely and
168
+ * accept unbounded growth.
169
+ *
170
+ * `expandAll()` / `collapseAll()` are unaffected — they flip the default and
171
+ * clear the set, so "collapse everything" costs one entry-free operation no
172
+ * matter how many groups exist.
173
+ */
174
+ groupExpansionOverrideLimit?: number;
132
175
  }
133
176
  /**
134
177
  * One entry in the ordered sort list; index in the list = priority.
@@ -199,15 +242,78 @@ interface PretableTransaction<TRow extends PretableRow = PretableRow> {
199
242
  remove?: string[];
200
243
  }
201
244
  /**
202
- * A row currently in the visible window — includes its source-array index for stable identity.
245
+ * A data row in the flat visible list — includes its source-array index for stable identity.
203
246
  *
204
247
  * @public
205
248
  */
206
- interface PretableVisibleRow<TRow extends PretableRow = PretableRow> {
249
+ interface PretableDataRow<TRow extends PretableRow = PretableRow> {
250
+ kind: "data";
207
251
  id: string;
208
252
  row: TRow;
209
253
  sourceIndex: number;
254
+ /** Nesting depth beneath its group ancestors; `0` when ungrouped. */
255
+ depth: number;
210
256
  }
257
+ /**
258
+ * A group header row in the flat visible list.
259
+ *
260
+ * @public
261
+ */
262
+ interface PretableGroupRow {
263
+ kind: "group";
264
+ /** Stable, path-derived id (see `makeGroupId`). */
265
+ id: string;
266
+ /** Nesting depth; the outermost group level is `0`. */
267
+ depth: number;
268
+ /** The column this level groups by. */
269
+ columnId: string;
270
+ /** The group key value, as read from the grouping column. */
271
+ value: unknown;
272
+ /** Data rows beneath this group, post-filter. */
273
+ childCount: number;
274
+ /** Finalized aggregate values, keyed by column id. */
275
+ aggregates: Record<string, unknown>;
276
+ }
277
+ /**
278
+ * One entry in the flat visible-row list. The list stays flat — virtualization,
279
+ * selection ranges, focus and copy all depend on that — and the union is
280
+ * deliberately open: total/footer rows will join it later.
281
+ *
282
+ * @public
283
+ */
284
+ type PretableVisibleRow<TRow extends PretableRow = PretableRow> = PretableDataRow<TRow> | PretableGroupRow;
285
+ /**
286
+ * An aggregate function, defined as a monoid rather than as `(values) => result`.
287
+ *
288
+ * The engine folds over a group's descendant leaf rows (`init`, then
289
+ * `accumulate` per leaf, then `finalize`), so order-sensitive statistics such as
290
+ * median remain expressible. `merge` must nevertheless be associative with
291
+ * `init()` as its identity: that contract is what allows a future switch to
292
+ * child-aggregate rollup to be a pure internal optimization instead of a
293
+ * breaking change to every consumer's aggregate function.
294
+ *
295
+ * `accumulate` may mutate and return `acc` — the engine hands each fold a fresh
296
+ * `init()` and never retains an earlier accumulator. `merge` must NOT mutate
297
+ * either argument.
298
+ *
299
+ * @public
300
+ */
301
+ interface PretableAggregator<TAcc = unknown, TOut = unknown> {
302
+ /** Empty accumulator. */
303
+ init(): TAcc;
304
+ /** Fold one leaf cell value into the accumulator. */
305
+ accumulate(acc: TAcc, value: unknown, row: PretableRow): TAcc;
306
+ /** Combine two accumulators (must be associative; `init()` is the identity). */
307
+ merge(a: TAcc, b: TAcc): TAcc;
308
+ /** Produce the display value — always a plain scalar, never a wrapper object. */
309
+ finalize(acc: TAcc): TOut;
310
+ }
311
+ /**
312
+ * A column's aggregate: a built-in name or a custom {@link PretableAggregator}.
313
+ *
314
+ * @public
315
+ */
316
+ type PretableAggregateSpec = "sum" | "avg" | "min" | "max" | "count" | PretableAggregator;
211
317
  /**
212
318
  * Read-only state observed via `PretableGrid.getSnapshot`.
213
319
  *
@@ -223,6 +329,12 @@ interface PretableGridSnapshot<TRow extends PretableRow = PretableRow> {
223
329
  visibleRows: PretableVisibleRow<TRow>[];
224
330
  visibleRange: PretableRowRange;
225
331
  editing: PretableEditState | null;
332
+ /** Grouping columns, outermost first; `[]` when ungrouped. */
333
+ rowGroups: string[];
334
+ /** Group ids whose expanded state differs from {@link groupsDefaultExpanded}. */
335
+ groupExpansionOverrides: ReadonlySet<string>;
336
+ /** Expanded state for every group with no entry in the override set. */
337
+ groupsDefaultExpanded: boolean;
226
338
  }
227
339
  /**
228
340
  * Direction passed to `PretableGrid.moveFocus`.
@@ -280,6 +392,20 @@ interface PretableGrid<TRow extends PretableRow = PretableRow> {
280
392
  setSelectAllVisible(checked: boolean): void;
281
393
  setFocus(addr: PretableCellAddress | null): void;
282
394
  moveFocus(direction: PretableFocusDirection, options?: PretableMoveFocusOptions): void;
395
+ /**
396
+ * Replace the grouping levels, outermost first; `[]` ungroups. Ids that do
397
+ * not match a column are dropped, and expansion state for groups that no
398
+ * longer exist is pruned.
399
+ */
400
+ setRowGroups(columnIds: readonly string[]): void;
401
+ /** Flip one group's expanded state. Unknown ids are still recorded. */
402
+ toggleGroup(groupId: string): void;
403
+ /** Set one group's expanded state explicitly. */
404
+ setGroupExpanded(groupId: string, expanded: boolean): void;
405
+ /** Expand every group, including ones that do not exist yet. */
406
+ expandAll(): void;
407
+ /** Collapse every group, including ones that do not exist yet. */
408
+ collapseAll(): void;
283
409
  setViewport(viewport: PretableViewportState): void;
284
410
  autosizeColumns(options?: AutosizeOptions): void;
285
411
  setColumnWidth(columnId: string, width: number): void;
@@ -337,4 +463,4 @@ interface PretableGrid<TRow extends PretableRow = PretableRow> {
337
463
  */
338
464
  declare function createGrid<TRow extends PretableRow = PretableRow>(options: PretableGridOptions<TRow>): PretableGrid<TRow>;
339
465
 
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 };
466
+ 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
@@ -102,8 +102,21 @@ interface PretableColumn<TRow extends PretableRow = PretableRow> {
102
102
  format?: (input: PretableFormatInput<TRow>) => string;
103
103
  minWidthPx?: number;
104
104
  maxWidthPx?: number;
105
+ /**
106
+ * Share of the width the fixed columns leave over, so the row ends exactly at
107
+ * the viewport edge instead of underfilling or overflowing it. Weights are
108
+ * relative: two columns at `flex: 1` split the remainder evenly, `1` and `3`
109
+ * split it a quarter to three quarters. `minWidthPx`/`maxWidthPx` still
110
+ * apply, and a column that has been resized (which sets `widthPx`) stops
111
+ * flexing — an explicit width outranks a computed one.
112
+ */
113
+ flex?: number;
105
114
  resizable?: boolean;
106
115
  reorderable?: boolean;
116
+ /** Group rows by this column by default; levels follow column order. */
117
+ rowGroup?: boolean;
118
+ /** Aggregate shown for this column on group rows. */
119
+ aggregate?: PretableAggregateSpec;
107
120
  editable?: boolean | ((input: PretableEditInput<TRow>) => boolean | Promise<boolean>);
108
121
  validate?: (value: unknown, input: PretableEditInput<TRow>) => (true | string) | Promise<true | string>;
109
122
  parseEditValue?: (raw: string, input: PretableEditInput<TRow>) => unknown;
@@ -129,6 +142,36 @@ interface PretableGridOptions<TRow extends PretableRow = PretableRow> {
129
142
  rows: TRow[];
130
143
  getRowId?: (row: TRow, index: number) => string;
131
144
  autosize?: boolean | AutosizeOptions;
145
+ /**
146
+ * Fold group aggregates over rows the active filter hides. Default `false`,
147
+ * so a group total always equals the sum of the rows visible beneath it.
148
+ * `childCount` is post-filter either way.
149
+ */
150
+ aggregateFilteredRows?: boolean;
151
+ /**
152
+ * Expanded state for groups with no entry in `groupExpansionOverrides`.
153
+ * Default `true`. Groups appearing mid-stream inherit it with no bookkeeping.
154
+ */
155
+ groupsDefaultExpanded?: boolean;
156
+ /**
157
+ * How many per-group expand/collapse decisions the grid remembers. Default
158
+ * `10_000`. Past the limit the least-recently-decided group is forgotten and
159
+ * reverts to `groupsDefaultExpanded`.
160
+ *
161
+ * **Why a limit exists.** Expansion state is keyed by a path-derived group id
162
+ * rather than owned by a node, which is what lets a group survive emptying and
163
+ * returning mid-stream. The price is that ids for groups which never return
164
+ * would otherwise accumulate forever under a stream whose grouping keys churn.
165
+ *
166
+ * Values below 1 clamp to 1; a non-finite value other than `Infinity` falls
167
+ * back to the default. Pass `Infinity` to opt out of the cap entirely and
168
+ * accept unbounded growth.
169
+ *
170
+ * `expandAll()` / `collapseAll()` are unaffected — they flip the default and
171
+ * clear the set, so "collapse everything" costs one entry-free operation no
172
+ * matter how many groups exist.
173
+ */
174
+ groupExpansionOverrideLimit?: number;
132
175
  }
133
176
  /**
134
177
  * One entry in the ordered sort list; index in the list = priority.
@@ -199,15 +242,78 @@ interface PretableTransaction<TRow extends PretableRow = PretableRow> {
199
242
  remove?: string[];
200
243
  }
201
244
  /**
202
- * A row currently in the visible window — includes its source-array index for stable identity.
245
+ * A data row in the flat visible list — includes its source-array index for stable identity.
203
246
  *
204
247
  * @public
205
248
  */
206
- interface PretableVisibleRow<TRow extends PretableRow = PretableRow> {
249
+ interface PretableDataRow<TRow extends PretableRow = PretableRow> {
250
+ kind: "data";
207
251
  id: string;
208
252
  row: TRow;
209
253
  sourceIndex: number;
254
+ /** Nesting depth beneath its group ancestors; `0` when ungrouped. */
255
+ depth: number;
210
256
  }
257
+ /**
258
+ * A group header row in the flat visible list.
259
+ *
260
+ * @public
261
+ */
262
+ interface PretableGroupRow {
263
+ kind: "group";
264
+ /** Stable, path-derived id (see `makeGroupId`). */
265
+ id: string;
266
+ /** Nesting depth; the outermost group level is `0`. */
267
+ depth: number;
268
+ /** The column this level groups by. */
269
+ columnId: string;
270
+ /** The group key value, as read from the grouping column. */
271
+ value: unknown;
272
+ /** Data rows beneath this group, post-filter. */
273
+ childCount: number;
274
+ /** Finalized aggregate values, keyed by column id. */
275
+ aggregates: Record<string, unknown>;
276
+ }
277
+ /**
278
+ * One entry in the flat visible-row list. The list stays flat — virtualization,
279
+ * selection ranges, focus and copy all depend on that — and the union is
280
+ * deliberately open: total/footer rows will join it later.
281
+ *
282
+ * @public
283
+ */
284
+ type PretableVisibleRow<TRow extends PretableRow = PretableRow> = PretableDataRow<TRow> | PretableGroupRow;
285
+ /**
286
+ * An aggregate function, defined as a monoid rather than as `(values) => result`.
287
+ *
288
+ * The engine folds over a group's descendant leaf rows (`init`, then
289
+ * `accumulate` per leaf, then `finalize`), so order-sensitive statistics such as
290
+ * median remain expressible. `merge` must nevertheless be associative with
291
+ * `init()` as its identity: that contract is what allows a future switch to
292
+ * child-aggregate rollup to be a pure internal optimization instead of a
293
+ * breaking change to every consumer's aggregate function.
294
+ *
295
+ * `accumulate` may mutate and return `acc` — the engine hands each fold a fresh
296
+ * `init()` and never retains an earlier accumulator. `merge` must NOT mutate
297
+ * either argument.
298
+ *
299
+ * @public
300
+ */
301
+ interface PretableAggregator<TAcc = unknown, TOut = unknown> {
302
+ /** Empty accumulator. */
303
+ init(): TAcc;
304
+ /** Fold one leaf cell value into the accumulator. */
305
+ accumulate(acc: TAcc, value: unknown, row: PretableRow): TAcc;
306
+ /** Combine two accumulators (must be associative; `init()` is the identity). */
307
+ merge(a: TAcc, b: TAcc): TAcc;
308
+ /** Produce the display value — always a plain scalar, never a wrapper object. */
309
+ finalize(acc: TAcc): TOut;
310
+ }
311
+ /**
312
+ * A column's aggregate: a built-in name or a custom {@link PretableAggregator}.
313
+ *
314
+ * @public
315
+ */
316
+ type PretableAggregateSpec = "sum" | "avg" | "min" | "max" | "count" | PretableAggregator;
211
317
  /**
212
318
  * Read-only state observed via `PretableGrid.getSnapshot`.
213
319
  *
@@ -223,6 +329,12 @@ interface PretableGridSnapshot<TRow extends PretableRow = PretableRow> {
223
329
  visibleRows: PretableVisibleRow<TRow>[];
224
330
  visibleRange: PretableRowRange;
225
331
  editing: PretableEditState | null;
332
+ /** Grouping columns, outermost first; `[]` when ungrouped. */
333
+ rowGroups: string[];
334
+ /** Group ids whose expanded state differs from {@link groupsDefaultExpanded}. */
335
+ groupExpansionOverrides: ReadonlySet<string>;
336
+ /** Expanded state for every group with no entry in the override set. */
337
+ groupsDefaultExpanded: boolean;
226
338
  }
227
339
  /**
228
340
  * Direction passed to `PretableGrid.moveFocus`.
@@ -280,6 +392,20 @@ interface PretableGrid<TRow extends PretableRow = PretableRow> {
280
392
  setSelectAllVisible(checked: boolean): void;
281
393
  setFocus(addr: PretableCellAddress | null): void;
282
394
  moveFocus(direction: PretableFocusDirection, options?: PretableMoveFocusOptions): void;
395
+ /**
396
+ * Replace the grouping levels, outermost first; `[]` ungroups. Ids that do
397
+ * not match a column are dropped, and expansion state for groups that no
398
+ * longer exist is pruned.
399
+ */
400
+ setRowGroups(columnIds: readonly string[]): void;
401
+ /** Flip one group's expanded state. Unknown ids are still recorded. */
402
+ toggleGroup(groupId: string): void;
403
+ /** Set one group's expanded state explicitly. */
404
+ setGroupExpanded(groupId: string, expanded: boolean): void;
405
+ /** Expand every group, including ones that do not exist yet. */
406
+ expandAll(): void;
407
+ /** Collapse every group, including ones that do not exist yet. */
408
+ collapseAll(): void;
283
409
  setViewport(viewport: PretableViewportState): void;
284
410
  autosizeColumns(options?: AutosizeOptions): void;
285
411
  setColumnWidth(columnId: string, width: number): void;
@@ -337,4 +463,4 @@ interface PretableGrid<TRow extends PretableRow = PretableRow> {
337
463
  */
338
464
  declare function createGrid<TRow extends PretableRow = PretableRow>(options: PretableGridOptions<TRow>): PretableGrid<TRow>;
339
465
 
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 };
466
+ 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 };