@guiexpert/table 1.1.93 → 1.1.94

package/lib/table/data/tablemodel/areamodel/area-model-row-groups.d.ts

@@ -0,0 +1,314 @@
+import { AreaModelTree } from './area-model-tree.js';
+import { ColumnDefIf } from '../column/column-def.if.js';
+import { CellRendererIf } from '../../../renderer/cell-render.if.js';
+import { FilterFunction } from '../../common/filter-function.js';
+import { SortItem } from '../../common/sort-item.js';
+import { DerivedValuesChangeIf } from './derived-values-change.if.js';
+import { RowGroupField } from '../../../rowgroup/row-group-field.type.js';
+import { RowGroupModelOptionsIf } from '../../../rowgroup/row-group-model-options.if.js';
+import { RowGroup } from '../../../rowgroup/row-group.js';
+
+/**
+ * The body of a row grouping: flat rows grouped by one or more levels, each group a row with an arrow, a label
+ * (`"Nord (3)"`) and aggregates per column (sum, average, …); below it the sub-groups or the original rows. Usually
+ * created by {@link RowGroupFactory.createTableModel}, which also adds the group column, hides the grouped columns and
+ * adds a total row.
+ *
+ * It is a tree ({@link AreaModelTree}, `isAreaModelTree` is true): group rows are {@link TreeRowIf tree rows} with a
+ * {@link RowGroupIf} as `data`, detail rows hold your objects. Expanding, `tableApi.expandAll()`, keyboard, screen
+ * reader attributes and remembering expanded groups (`autoRestoreOptions`) work as in a tree table.
+ *
+ * - **Filter**: `externalFilterFunction` gets your object (as in a flat table) – never a group. Groups without a match
+ *   disappear; aggregates and counts follow the filter.
+ * - **Sorting**: by an aggregated column → groups by aggregate, rows by value; by the group column → groups by key;
+ *   `tableApi.sort(fn)` sorts the rows inside their groups with `fn(a, b)` on your objects.
+ * - **Editing**: group rows are not editable. A changed value recomputes only the groups of that row; a changed
+ *   grouped value moves the row to its new group.
+ * - **Regrouping**: {@link TableApi.setRowGroupBy} (or {@link setGroupBy} + `tableApi.repaintHard()`) – expanded
+ *   groups, filter, sorting and checked rows stay.
+ * - Aggregates are computed when a group row is read after a change – once, not per repaint or scroll frame.
+ *
+ * @example
+ * const tableModel = RowGroupFactory.createTableModel<Sale>({
+ *   rows: sales, columnDefs, groupBy: ["region", "produkt"], aggregations: { umsatz: "sum" }
+ * });
+ * const body = tableModel.getBodyModel() as AreaModelRowGroups<Sale>;
+ * body.getGroups().map(g => g.results.umsatz);   // [270, 180]
+ *
+ * @see Training: [Row grouping](https://gui.expert/training/row-grouping/)
+ *
+ * @typeParam T - the row type
+ * @since 1.1.94
+ * @category Row grouping
+ */
+export declare class AreaModelRowGroups<T = any> extends AreaModelTree<any> {
+    /** Marker for {@link isAreaModelRowGroups} (works across copies of the core). `type` stays `"AreaModelTree"`. */
+    readonly kind = "AreaModelRowGroups";
+    /** The options (groupBy as set by {@link setGroupBy}). */
+    readonly options: RowGroupModelOptionsIf<T>;
+    /** Properties of the columns the factory hid for the current grouping. @internal */
+    hiddenColumnProperties: string[];
+    private sourceRows;
+    private fields;
+    private groups;
+    private readonly specs;
+    private readonly specByKey;
+    private readonly textRenderer;
+    /** the tree row of every group by id */
+    private groupRowById;
+    /** the tree row of every source row by source index */
+    private detailRows;
+    /** the filter of the user (gets the objects) and its result per source index */
+    private userFilter?;
+    private accepted?;
+    private allDirty;
+    private readonly dirtyLeaves;
+    private totals;
+    private lastSort?;
+    private batchDepth;
+    private regroupPending;
+    private builds;
+    /**
+     * @param {T[]} rows - the rows (not changed by the model)
+     * @param {ColumnDefIf[]} columnDefs - the columns of the table, usually with a {@link RowGroupColumnDef}
+     * @param {RowGroupModelOptionsIf<T>} options - levels, aggregations, expanded state …
+     * @param {number} [defaultRowHeight=34] - row height in px
+     */
+    constructor(rows: T[], columnDefs: ColumnDefIf[], options: RowGroupModelOptionsIf<T>, defaultRowHeight?: number);
+    /**
+     * The rows the groups are built from.
+     *
+     * @returns {T[]} the source rows (do not modify the array – use {@link setRows})
+     *
+     * @example
+     * const all = body.getSourceRows().length;
+     */
+    getSourceRows(): T[];
+    /**
+     * Replaces the rows and groups them again (expanded groups, filter and sorting stay). Repaint with
+     * `tableApi.repaintHard()` – the row count changes.
+     *
+     * @param {T[]} rows - the new rows
+     *
+     * @example
+     * body.setRows(await loadSales());
+     * tableApi.repaintHard();
+     */
+    setRows(rows: T[]): void;
+    /**
+     * The current levels.
+     *
+     * @returns {RowGroupField<T>[]} a copy of the levels
+     *
+     * @example
+     * body.getGroupBy();   // ["region", "produkt"]
+     */
+    getGroupBy(): RowGroupField<T>[];
+    /**
+     * Groups the rows by other levels. Expanded groups whose path stays keep their state; filter, sorting and checked
+     * rows stay. An empty list shows the rows without groups. Prefer {@link TableApi.setRowGroupBy}: it also shows and
+     * hides the grouped columns and repaints.
+     *
+     * @param {RowGroupField<T>[]} groupBy - the new levels, top first
+     *
+     * @example
+     * body.setGroupBy(["produkt"]);
+     * tableApi.repaintHard();
+     */
+    setGroupBy(groupBy: RowGroupField<T>[]): void;
+    /**
+     * Builds the groups again from the current rows – after grouped values were changed outside the table (inside the
+     * table, editing a grouped value moves the row by itself). Repaint with `tableApi.repaintHard()`.
+     *
+     * @example
+     * sales[0].region = "Süd";   // a live update of a grouped value
+     * body.regroup();
+     * tableApi.repaintHard();
+     */
+    regroup(): void;
+    /**
+     * The groups of the top level (with sub-groups, counts and aggregates).
+     *
+     * @returns {RowGroup<T>[]} the groups in display order (do not modify)
+     *
+     * @example
+     * body.getGroups().map(g => `${g.label}: ${g.results.umsatz}`);   // ["Nord: 270", "Süd: 180"]
+     */
+    getGroups(): RowGroup<T>[];
+    /**
+     * The group with the given keys.
+     *
+     * @param {unknown[]} path - the keys from the top level down, e.g. `["Nord", "A"]`
+     * @returns {RowGroup<T> | undefined} the group, undefined if there is none
+     *
+     * @example
+     * body.findGroup(["Nord", "A"])?.results.umsatz;   // 220
+     */
+    findGroup(path: unknown[]): RowGroup<T> | undefined;
+    /**
+     * The group of a displayed row.
+     *
+     * @param {number} rowIndex - index of the displayed body row
+     * @returns {RowGroup<T> | undefined} the group of a group row, undefined for a detail row
+     *
+     * @example
+     * const group = body.getRowGroup(0);   // the first group (if the first row is a group row)
+     */
+    getRowGroup(rowIndex: number): RowGroup<T> | undefined;
+    /**
+     * Your object of a displayed detail row.
+     *
+     * @param {number} rowIndex - index of the displayed body row
+     * @returns {T | undefined} the object, undefined for a group row
+     *
+     * @example
+     * const sale = body.getDetailRow(1);
+     */
+    getDetailRow(rowIndex: number): T | undefined;
+    /**
+     * True if the displayed row is a group row.
+     *
+     * @param {number} rowIndex - index of the displayed body row
+     * @returns {boolean} true for a group row
+     *
+     * @example
+     * const bold = body.isGroupRowIndex(rowIndex);
+     */
+    isGroupRowIndex(rowIndex: number): boolean;
+    /**
+     * The aggregates over all rows the filter keeps (the same as the total row).
+     *
+     * @returns {Record<string, unknown>} key → result
+     *
+     * @example
+     * body.getTotals().umsatz;   // 450
+     */
+    getTotals(): Record<string, unknown>;
+    /**
+     * The checked objects (detail rows) – with a checkbox column or `showCheckboxWihoutExtraColumn`.
+     *
+     * @returns {T[]} the checked objects in source order
+     *
+     * @example
+     * const selected = body.getCheckedRows();
+     */
+    getCheckedRows(): T[];
+    /**
+     * Expands the groups above a level and collapses the others: `0` collapses all, `1` opens the top level, a large
+     * number opens all. Repaint with `tableApi.repaintHard()`.
+     *
+     * @param {number} level - the number of open levels
+     *
+     * @example
+     * body.expandToLevel(1);
+     * tableApi.repaintHard();
+     */
+    expandToLevel(level: number): void;
+    /**
+     * Counts how often the groups were built (start, {@link setRows}, {@link setGroupBy}, {@link regroup}, an edited
+     * grouped value). The table compares it before and after an edit to know that the rows moved (→ hard repaint).
+     *
+     * @returns {number} the number of builds
+     *
+     * @example
+     * const before = body.getBuildCount();
+     * body.setValue(1, 1, "Ost");
+     * const moved = body.getBuildCount() !== before;   // true: "region" is grouped
+     */
+    getBuildCount(): number;
+    /**
+     * Runs several `setValue` calls as one change: a row whose grouped value changes moves only at the end, so the row
+     * indices of the other calls stay valid (`tableApi.updateCells()` uses it).
+     *
+     * @param {() => void} fn - the changes
+     * @returns {boolean} true if the groups were built again at the end
+     *
+     * @example
+     * const moved = body.batch(() => {
+     *   body.setValue(1, 1, "Süd");      // region – moves the row
+     *   body.setValue(2, 4, 999);        // still the row that was at index 2
+     * });
+     */
+    batch(fn: () => void): boolean;
+    getValueAt(rowIndex: number, columnIndex: number): any;
+    getTextValueAt(rowIndex: number, columnIndex: number): string;
+    /** Group rows: the {@link AggregateCellRenderer} for aggregates, no renderer otherwise; detail rows: the column's. */
+    getCellRenderer(rowIndex: number, columnIndex: number): CellRendererIf | undefined;
+    getCustomClassesAt(rowIndex: number, columnIndex: number): string[];
+    /**
+     * True for the label cell of a group row (the table gives it `role="rowheader"`).
+     *
+     * @param {number} rowIndex - index of the displayed body row
+     * @param {number} columnIndex - column index
+     * @returns {boolean} true for the group label
+     */
+    isGroupLabelCell(rowIndex: number, columnIndex: number): boolean;
+    /** Group rows and the group column are not editable. */
+    isEditable(rowIndex: number, columnIndex: number): boolean;
+    /**
+     * Sets a value of a detail row (group rows: `false`). Only the groups of that row are computed again; if a grouped
+     * value changed, the row moves to its new group (the row count may change).
+     */
+    setValue(rowIndex: number, columnIndex: number, value: any): boolean;
+    /**
+     * Filters the rows: `predictFn` gets **your objects** (as in a flat table), index and array of the source rows –
+     * never a group. Groups without a matching row disappear (also below collapsed groups); counts and aggregates follow
+     * the filter. Usually called by `tableApi.externalFilterChanged()` with `tableOptions.externalFilterFunction`.
+     *
+     * @param {FilterFunction<S>} predictFn - returns a truthy value for the rows to show
+     *
+     * @example
+     * tableOptions.externalFilterFunction = (sale: Sale) => sale.monat === "Jan";
+     * tableApi.externalFilterChanged();   // Nord (2) 150 · Süd (1) 80
+     */
+    externalFilterChanged<S>(predictFn: FilterFunction<S>): void;
+    /**
+     * Sorts groups and rows (see the class description); the order is applied again after regrouping.
+     *
+     * @param {SortItem[]} sortItems - primary key first
+     * @returns {boolean} false for an empty list
+     *
+     * @example
+     * body.doSort([new SortItem(tableApi.getColumnIndex("umsatz"), "desc")]);   // groups by sum, rows by value
+     * tableApi.repaint();
+     */
+    doSort(sortItems: SortItem[]): boolean;
+    /**
+     * Sorts the rows inside their groups with your function – it gets your objects, as in a flat table. The groups keep
+     * their order. Used by `tableApi.sort(fn)`.
+     *
+     * @param {(a: any, b: any) => number} compareFn - compares two of your objects
+     *
+     * @example
+     * tableApi.sort((a: Sale, b: Sale) => b.umsatz - a.umsatz);
+     */
+    sort(compareFn: (a: any, b: any) => number): void;
+    /**
+     * Drops the computed aggregates; with `change` (an edit or `updateCells`) only those of the groups of the changed rows.
+     * The table calls it; the next read computes them again.
+     *
+     * @param {DerivedValuesChangeIf} [change] - the changed rows
+     *
+     * @example
+     * sales[0].umsatz = 999;        // changed outside the table
+     * tableApi.repaint();           // calls invalidateDerivedValues() – all groups are computed again
+     */
+    invalidateDerivedValues(change?: DerivedValuesChangeIf): void;
+    /** After sorting the tree rows: the groups (`getGroups()`, `children`) in display order. */
+    private syncGroupOrder;
+    /** The label of a group row in the group column. */
+    protected getGroupLabel(group: RowGroup<T>): string;
+    /** Computes what is missing: everything after a change of data/filter/grouping, otherwise the dirty paths. */
+    protected ensureAggregates(): void;
+    private markRowDirty;
+    private keysOf;
+    /** A comparator of two sibling rows for one sort column. */
+    private createRowComparator;
+    /**
+     * (Re)builds groups and tree rows from the source rows, keeps the expanded state of known groups, the checked
+     * detail rows, the filter and the sorting.
+     */
+    private build;
+    private createGroupRow;
+    private isExpandedByDefault;
+}

package/lib/table/data/tablemodel/areamodel/area-model-tree.d.ts

@@ -106,6 +106,20 @@ export declare class AreaModelTree<S> extends AbstractAreaModel<TreeRow<S>> {
      * @since 1.1.91
      */
     getDisplayedChildren(row: TreeRowIf<S>): TreeRowIf<S>[];
+    /**
+     * The leaves (rows without children) of the whole tree, depth-first in the current order – independent of the
+     * expanded state. Used for totals: collapsing a node does not change them, and parent rows are not counted twice.
+     *
+     * @param {boolean} [filtered=true] - only the leaves the active filter keeps (`externalFilterChanged`); `false`: all
+     * @returns {TreeRowIf<S>[]} a new array
+     *
+     * @example
+     * const treeModel = tableModel.getBodyModel() as AreaModelTree<OrderNode>;
+     * const total = aggregate(treeModel.getLeafRows(), row => row.data.total, "sum");
+     *
+     * @since 1.1.94
+     */
+    getLeafRows(filtered?: boolean): TreeRowIf<S>[];
     /**
      * The displayed rows: all parents expanded and accepted by the active filter, in display order.
      *

package/lib/table/data/tablemodel/areamodel/area-model.if.d.ts

@@ -1,3 +1,4 @@
+import { DerivedValuesChangeIf } from './derived-values-change.if.js';
 import { CellRendererIf } from '../../../renderer/cell-render.if.js';
 import { CheckedType } from '../../common/checked-type.js';
 import { CheckboxModelIf } from '../../../checkbox/checkbox-model.if.js';
@@ -280,6 +281,44 @@ export interface AreaModelIf {
      * @since 1.1.92
      */
     getUnfilteredRowCount?(): number;
+    /**
+     * Optional: drops cached, derived values (e.g. the totals of an {@link AreaModelAggregateFooter}). The table calls
+     * it for all three areas when data may have changed: filter, sorting, editing, `updateCells()` and the public
+     * `tableApi.repaint()` / `repaintHard()` – not on scrolling or internal repaints.
+     *
+     * After an edit and `updateCells()` the table passes `change` (since 1.1.94): the area and the displayed rows that
+     * changed – a model may recompute only what depends on them ({@link AreaModelRowGroups} recomputes the groups of
+     * these rows). Without `change` anything may have changed.
+     *
+     * @example
+     * class CachedTotalsFooter extends AreaModel {
+     *   private total?: number;
+     *   constructor(private readonly body: AreaModelObjectArray<Order>) {
+     *     super();
+     *     this.areaIdent = "footer";
+     *   }
+     *   invalidateDerivedValues(): void { this.total = undefined; }
+     *   override getRowCount(): number { return 1; }
+     *   override getValueAt(_row: number, _col: number): any {
+     *     return this.total ??= this.body.getFilteredRows().reduce((sum, o) => sum + o.total, 0);
+     *   }
+     * }
+     *
+     * @since 1.1.94
+     */
+    invalidateDerivedValues?(change?: DerivedValuesChangeIf): void;
+    /**
+     * Optional: true for a cell that names its row (a label such as "Nord" or "Total") – the table gives it
+     * `role="rowheader"` instead of `gridcell`, so screen readers announce it with the row.
+     *
+     * @example
+     * class LabeledBody extends AreaModel {
+     *   isRowHeaderCell(_rowIndex: number, columnIndex: number): boolean { return columnIndex === 0; }
+     * }
+     *
+     * @since 1.1.94
+     */
+    isRowHeaderCell?(rowIndex: number, columnIndex: number): boolean;
     /**
      * Returns the value of the cell at the specified row and column indices.
      * This is one of the most important methods in the area model, as it provides

package/lib/table/data/tablemodel/areamodel/derived-values-change.if.d.ts

@@ -0,0 +1,30 @@
+import { AreaIdent } from '../area-ident.type.js';
+
+/**
+ * What changed when the table calls {@link AreaModelIf.invalidateDerivedValues} after an edit or
+ * {@link TableApi.updateCells}: the area and the displayed rows. A model may use it to recompute only what depends on
+ * these rows (a row grouping recomputes the path of the changed row only). Without it everything may have changed.
+ *
+ * @example
+ * class MyModel extends AreaModel {
+ *   private readonly dirtyRows = new Set<number>();
+ *   private allDirty = true;
+ *
+ *   invalidateDerivedValues(change?: DerivedValuesChangeIf): void {
+ *     if (change?.area === "body") {
+ *       change.rowIndices.forEach(r => this.dirtyRows.add(r));   // only these rows
+ *     } else {
+ *       this.allDirty = true;                                      // anything may have changed
+ *     }
+ *   }
+ * }
+ *
+ * @since 1.1.94
+ * @category Area models
+ */
+export interface DerivedValuesChangeIf {
+    /** The area whose values changed. */
+    area: AreaIdent;
+    /** The changed rows (indices of the displayed rows at the time of the change). */
+    rowIndices: number[];
+}

package/lib/table/factory/pivot-factory.d.ts

@@ -0,0 +1,63 @@
+import { PivotTableModelParaIf } from './pivot-table-model-para.if.js';
+import { PivotTableModel } from '../pivot/pivot-table-model.js';
+
+/**
+ * Creates pivot tables: rows grouped by row fields (a hierarchy with subtotals), the values of column fields as
+ * columns (several fields = a multi-row header), aggregated values in the cells, total column and total row.
+ * MIT-licensed, no dependencies – at ag-Grid this is an Enterprise feature.
+ *
+ * The configuration has the form of a row grouping ({@link RowGroupFactory}): fields are property paths, functions
+ * (e.g. the quarter of a date) or {@link RowGroupFieldIf} with label, format and order; values use the aggregators of
+ * {@link Aggregators} (`sum`, `avg`, `count` …) or your own {@link AggregatorIf}. Subtotals and totals are merged from
+ * aggregation states – an average is always the average of the rows.
+ *
+ * Filter with `externalFilterFunction` (it gets your source objects, before the aggregation), sort by clicking a value
+ * column, export with `downloadExcel()`, and pivot again at runtime with {@link TableApi.setPivotConfig}.
+ *
+ * @example
+ * // case 1: regions × months, sum of umsatz, total column and total row
+ * const tableModel = PivotFactory.createTableModel<Sale>({
+ *   rows: sales,
+ *   rowFields: ["region"],
+ *   columnFields: [{ value: "monat", order: "insertion" }],
+ *   values: ["umsatz"]
+ * });
+ * // Region | Jan | Feb | Total
+ * // Nord   | 150 | 120 |   270
+ * // Süd    |  80 | 100 |   180
+ * // Total  | 230 | 220 |   450
+ *
+ * @example
+ * // countries › cities × years, revenue, all groups closed; pivot by another field with a select
+ * const tableModel = PivotFactory.createTableModel<Order>({
+ *   rows: orders,
+ *   rowFields: ["country", "city"],
+ *   columnFields: [{ name: "year", label: "Year", value: o => new Date(o.date).getFullYear() }],
+ *   values: [{ value: "total", label: "Revenue" }],
+ *   expanded: 0
+ * });
+ * select.addEventListener("change", () => tableApi.setPivotConfig({ columnFields: [select.value] }));
+ *
+ * @see Training: [Pivot tables](https://gui.expert/training/pivot-tables/)
+ *
+ * @since 1.1.94
+ * @category Pivot
+ */
+export declare class PivotFactory {
+    /**
+     * Creates the table model of a pivot table (see the class description).
+     *
+     * @param {PivotTableModelParaIf<T>} p - rows, row fields, column fields, values, options
+     * @returns {PivotTableModel<T>} the table model – a {@link TableModelIf}
+     *
+     * @example
+     * // case 3: the average – Jan total is 230 / 3 = 76.67, not the mean of the region averages (77.5)
+     * const tableModel = PivotFactory.createTableModel<Sale>({
+     *   rows: sales, rowFields: ["region"], columnFields: ["monat"],
+     *   values: [{ value: "umsatz", aggregator: "avg" }]
+     * });
+     */
+    static createTableModel<T = any>(p: PivotTableModelParaIf<T>): PivotTableModel<T>;
+    /** The pivot part of the parameters. */
+    private static toConfig;
+}

package/lib/table/factory/pivot-table-model-para.if.d.ts

@@ -0,0 +1,44 @@
+import { TableOptionsIf } from '../data/options/table-options.if.js';
+import { DefaultRowHeightsIf } from '../data/options/default-row-heights.if.js';
+import { GetT } from '../data/common/get-t.js';
+import { SelectionModelIf } from '../selection/selection-model.if.js';
+import { RowNumberOptionsIf } from '../data/common/row-number-options.if.js';
+import { SizeIf } from '../data/common/size.if.js';
+import { RowGroupColumnOptionsIf } from '../rowgroup/row-group-column-options.if.js';
+import { PivotConfigIf } from '../pivot/pivot-config.if.js';
+
+/**
+ * Parameters of {@link PivotFactory.createTableModel}: the rows, the pivot ({@link PivotConfigIf}) and the look of the
+ * table.
+ *
+ * @example
+ * const para: PivotTableModelParaIf<Sale> = {
+ *   rows: sales,
+ *   rowFields: ["region", "produkt"],
+ *   columnFields: [{ value: "monat", order: "insertion" }],
+ *   values: ["umsatz"],
+ *   emptyText: "–",
+ *   valueColumnWidth: px80
+ * };
+ * const tableModel = PivotFactory.createTableModel(para);
+ *
+ * @typeParam T - the row type
+ * @since 1.1.94
+ * @category Pivot
+ */
+export interface PivotTableModelParaIf<T = any> extends PivotConfigIf<T> {
+    /** The source rows (not changed). */
+    rows: T[];
+    /** The group column (arrows and row labels): header, width, `showCount` (default false), own label, fixed (default true). */
+    groupColumn?: Partial<RowGroupColumnOptionsIf<T>>;
+    /** The width of a value column. Default 100 px. */
+    valueColumnWidth?: SizeIf;
+    /** Row numbers in front of the group column (counted per displayed row). */
+    rowNumbersVisible?: boolean | Partial<RowNumberOptionsIf>;
+    /** Options of the table (row heights, selection model …). */
+    tableOptions?: TableOptionsIf;
+    /** Row heights of header, body and footer. Default: `tableOptions.defaultRowHeights`. */
+    defaultRowHeights?: DefaultRowHeightsIf;
+    /** Selection model factory. Default: `tableOptions.getSelectionModel`. */
+    getSelectionModel?: GetT<SelectionModelIf>;
+}

package/lib/table/factory/row-group-factory.d.ts

@@ -0,0 +1,70 @@
+import { TableModelIf } from '../data/tablemodel/table-model.if.js';
+import { RowGroupTableModelParaIf } from './row-group-table-model-para.if.js';
+
+/**
+ * Creates a table model that groups flat rows: one row per group with an arrow, a label (`"Nord (3)"`) and
+ * aggregates per column, below it the sub-groups or the original rows – plus a total row. MIT-licensed, no
+ * dependencies, built on the tree table ({@link AreaModelRowGroups}).
+ *
+ * What the factory does:
+ * - puts a {@link RowGroupColumnDef} (arrows, labels) behind row numbers and checkbox column and fixes it on the left;
+ * - hides the columns of grouped properties (`hideGroupedColumns`), their values are in the group column;
+ * - builds the body ({@link AreaModelRowGroups}) and a total row from the `aggregations` ({@link AreaModelAggregateFooter}).
+ *
+ * Regroup at runtime with {@link TableApi.setRowGroupBy}; filter, sort, edit and export as in any table.
+ *
+ * @example
+ * // R1: sales by region, sum of umsatz, total row
+ * const tableModel = RowGroupFactory.createTableModel<Sale>({
+ *   rows: sales,
+ *   columnDefs,
+ *   groupBy: ["region"],
+ *   aggregations: { umsatz: "sum" }
+ * });
+ * // ▾ Nord (3) … 270 · A Jan 100 · B Jan 50 · A Feb 120 · ▾ Süd (3) … 180 · … · footer "6 rows" … 450
+ *
+ * @example
+ * // two levels, all groups closed, regroup with a select
+ * const tableModel = RowGroupFactory.createTableModel<Order>({
+ *   rows: orders, columnDefs, groupBy: ["country", "city"],
+ *   aggregations: { quantity: "sum", total: "sum" }, expanded: 0
+ * });
+ * select.addEventListener("change", () => tableApi.setRowGroupBy(select.value.split(",")));
+ *
+ * @see Training: [Row grouping](https://gui.expert/training/row-grouping/)
+ *
+ * @since 1.1.94
+ * @category Row grouping
+ */
+export declare class RowGroupFactory {
+    /**
+     * Creates the table model of a row grouping (see the class description).
+     *
+     * @param {RowGroupTableModelParaIf<T>} p - rows, levels, columns, aggregations, options
+     * @returns {TableModelIf} the table model – its body is an {@link AreaModelRowGroups}
+     *
+     * @example
+     * const tableModel = RowGroupFactory.createTableModel<Sale>({
+     *   rows: sales, columnDefs, groupBy: ["region", "produkt"], aggregations: { umsatz: "avg" }
+     * });
+     * const body = tableModel.getBodyModel() as AreaModelRowGroups<Sale>;
+     * body.getGroups()[0].results.umsatz;   // 90 – Nord, the average of its three rows
+     */
+    static createTableModel<T = any>(p: RowGroupTableModelParaIf<T>): TableModelIf;
+    /**
+     * Hides the columns of the grouped properties (and shows the ones that are no longer grouped) and sets the header of
+     * the group column – after `body.setGroupBy(…)`. {@link TableApi.setRowGroupBy} calls it for you.
+     *
+     * @param {TableModelIf} tableModel - a table model of {@link createTableModel}
+     * @returns {boolean} false if the body is no row grouping
+     *
+     * @example
+     * const body = tableModel.getBodyModel() as AreaModelRowGroups<Sale>;
+     * body.setGroupBy(["produkt"]);
+     * RowGroupFactory.updateLayout(tableModel);
+     * tableApi.recalcWrappers();
+     * tableApi.repaintHard();
+     */
+    static updateLayout(tableModel: TableModelIf): boolean;
+    private static footerConfig;
+}

package/lib/table/factory/row-group-table-model-para.if.d.ts

@@ -0,0 +1,66 @@
+import { ColumnDefIf } from '../data/tablemodel/column/column-def.if.js';
+import { TableOptionsIf } from '../data/options/table-options.if.js';
+import { DefaultRowHeightsIf } from '../data/options/default-row-heights.if.js';
+import { GetT } from '../data/common/get-t.js';
+import { SelectionModelIf } from '../selection/selection-model.if.js';
+import { RowNumberOptionsIf } from '../data/common/row-number-options.if.js';
+import { AggregateSpecMap } from '../aggregation/aggregate-spec.if.js';
+import { AggregateFooterConfig } from '../data/tablemodel/areamodel/aggregate-footer-options.if.js';
+import { RowGroupField } from '../rowgroup/row-group-field.type.js';
+import { RowGroupColumnOptionsIf } from '../rowgroup/row-group-column-options.if.js';
+import { RowGroupExpanded } from '../rowgroup/row-group-model-options.if.js';
+
+/**
+ * Parameters of {@link RowGroupFactory.createTableModel}.
+ *
+ * @example
+ * const para: RowGroupTableModelParaIf<Sale> = {
+ *   rows: sales,
+ *   columnDefs,
+ *   groupBy: ["region", "produkt"],
+ *   aggregations: { umsatz: "sum" },
+ *   expanded: 1                      // regions open, products closed
+ * };
+ * const tableModel = RowGroupFactory.createTableModel(para);
+ *
+ * @typeParam T - the row type
+ * @since 1.1.94
+ * @category Row grouping
+ */
+export interface RowGroupTableModelParaIf<T = any> {
+    /** The flat rows (not changed). */
+    rows: T[];
+    /** The levels, top first: property paths (`"region"`), functions (`o => o.date.getFullYear()`) or {@link RowGroupFieldIf}. */
+    groupBy: RowGroupField<T>[];
+    /** The columns. Default: one per key of the first row. The group column is added in front of them. */
+    columnDefs?: ColumnDefIf[];
+    /** Aggregates in the group rows; the key is the property of the column (`{ umsatz: "sum" }`, see {@link AggregateSpecMap}). */
+    aggregations?: AggregateSpecMap<T>;
+    /**
+     * The total row: `true` = the `aggregations`, `false` = none, or an own configuration ({@link AggregateFooterConfig}).
+     * Default: `true` if there are aggregations.
+     */
+    footerAggregates?: boolean | AggregateFooterConfig<T>;
+    /** The group column: header, width, count, own label, fixed. */
+    groupColumn?: Partial<RowGroupColumnOptionsIf<T>>;
+    /** Hide the columns of the grouped properties. Default true. */
+    hideGroupedColumns?: boolean;
+    /** Expanded groups: `true` (default), `false`, open levels as a number (`0` = all closed) or a function per group. */
+    expanded?: RowGroupExpanded<T>;
+    /** The label of the group of empty keys (`null`, `undefined`, `""`). Default `"(empty)"`. */
+    emptyLabel?: string;
+    /** Options of the table (row heights, selection model, filter …). */
+    tableOptions?: TableOptionsIf;
+    /** Columns fixed on the left besides the group column (which is fixed by itself). Default 0. */
+    fixedLeftColumnCount?: number;
+    /** Columns fixed on the right. Default 0. */
+    fixedRightColumnCount?: number;
+    /** Row numbers in front of all columns (counted per displayed row, group rows included). */
+    rowNumbersVisible?: boolean | Partial<RowNumberOptionsIf>;
+    /** Set with a {@link CheckboxColumnDef} in `columnDefs` (default: detected). */
+    rowCheckboxVisible?: boolean;
+    /** Row heights of header, body and footer. Default: `tableOptions.defaultRowHeights`. */
+    defaultRowHeights?: DefaultRowHeightsIf;
+    /** Selection model factory. Default: `tableOptions.getSelectionModel`. */
+    getSelectionModel?: GetT<SelectionModelIf>;
+}