@guiexpert/table 1.1.93 → 1.1.94

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

@@ -0,0 +1,145 @@
+import { AreaModel } from './area-model.js';
+import { AreaModelIf } from './area-model.if.js';
+import { HasDefaultRowHeightIf } from './has-default-row-height-if.js';
+import { ColumnDefIf } from '../column/column-def.if.js';
+import { CellRendererIf } from '../../../renderer/cell-render.if.js';
+import { AggregateFooterConfig, AggregateFooterOptionsIf } from './aggregate-footer-options.if.js';
+import { ResolvedAggregateSpec } from '../../../aggregation/aggregate-internals.js';
+
+interface AggregationSource {
+    /** changes when the rows change (identity) – undefined: only invalidateDerivedValues() */
+    signal: unknown;
+    /** the number of rows, cheap (part of the cache key) – undefined: not known without computing the rows */
+    length?: number;
+    /** the rows (objects) – or, for models without row objects, the number of rows; called on a cache miss only */
+    getRows(): ArrayLike<unknown> | number;
+}
+/**
+ * A ready-made footer with totals (sum, average, count, …) that follow filter and sorting – without an own
+ * {@link AreaModel}. One or more total rows; every aggregate belongs to the column with the same **property**
+ * (column order, row numbers and the checkbox column don't matter). The easiest way is the factory option
+ * `footerAggregates` of {@link TableFactory.createTableModel}.
+ *
+ * - **Data**: the rows the body shows (`getFilteredRows()`), in a tree all leaves the filter keeps (expanded or not),
+ *   in other models every row via `getValueAt` of the column. Options `source: "all"` and `getRows` change that.
+ * - **Cells**: the value is the raw result (a number stays a number – Excel export, own footer renderers); the text is
+ *   formatted (`format` of the spec, otherwise {@link formatAggregateValue}). A footer renderer of the column
+ *   (`rendererMap.footer`) gets the raw value; without it the {@link AggregateCellRenderer} writes the text.
+ * - **Label**: `"6 rows"` (or the row's `label`) in the first data column without an aggregate, or in `labelProperty`;
+ *   screen readers announce it as row header.
+ * - **Cache**: computed once per change of the data, not per repaint or scroll frame. The table drops the cache when
+ *   it filters, sorts, edits, gets `updateCells()` or `tableApi.repaint()` / `repaintHard()` – after changing row
+ *   objects yourself call `tableApi.repaint()`, as for the cells.
+ *
+ * @example
+ * // one line: totals of quantity and total – the label "100,000 rows" goes into the first column without aggregate
+ * const tableModel = TableFactory.createTableModel({
+ *   rows: orders,
+ *   columnDefs,
+ *   footerAggregates: { quantity: "sum", total: "sum" }
+ * });
+ *
+ * @example
+ * // two total rows with own labels, an own body model
+ * const footer = new AreaModelAggregateFooter<Order>(() => tableModel.getBodyModel(), columnDefs, [
+ *   { label: "Sum", aggregates: { quantity: "sum", total: "sum" } },
+ *   { label: (rowCount: number) => `Ø of ${rowCount}`, aggregates: { quantity: "avg", total: "avg" } }
+ * ]);
+ * const tableModel = TableFactory.createTableModel({ rows: orders, columnDefs, footerAreaModel: footer });
+ *
+ * @example
+ * // read the results, e.g. for a title
+ * const footer = tableModel.getAreaModel("footer") as AreaModelAggregateFooter<Order>;
+ * const { total } = footer.getResults();           // { total: 27481033.5, … }
+ *
+ * @see {@link aggregateColumns} (the same without a table), {@link TableApi.getSelectionAggregates} (selected cells)
+ * @see Training: [Footer totals](https://gui.expert/training/footer-totals/)
+ *
+ * @since 1.1.94
+ * @category Aggregation
+ */
+export declare class AreaModelAggregateFooter<T = any> extends AreaModel implements HasDefaultRowHeightIf {
+    private readonly columnDefs;
+    /** Marker (works across copies of the core): {@link isAreaModelAggregateFooter}. */
+    readonly type = "AreaModelAggregateFooter";
+    /** Height of the footer rows in px (`rowHeight` of the options, default 34). */
+    defaultRowHeight: number;
+    private readonly getBody;
+    private readonly options;
+    private readonly footerRows;
+    private readonly textRenderer;
+    private cache?;
+    /**
+     * @param {AreaModelIf | (() => AreaModelIf)} body - the body model, or a function that returns it (if the footer is
+     *        created before the table model, e.g. `() => tableModel.getBodyModel()`)
+     * @param {ColumnDefIf[]} columnDefs - the column definitions of the table (the same array – columns are found by property)
+     * @param {AggregateFooterConfig<T>} config - `{ total: "sum" }` (one row), `[{ label, aggregates }, …]` (several rows)
+     *        or full {@link AggregateFooterOptionsIf}
+     */
+    constructor(body: AreaModelIf | (() => AreaModelIf), columnDefs: ColumnDefIf[], config: AggregateFooterConfig<T>);
+    /** The full options of a short configuration. */
+    static toOptions<T>(config: AggregateFooterConfig<T>): AggregateFooterOptionsIf<T>;
+    getRowCount(): number;
+    getRowHeight(_rowIndex: number): number;
+    getConstantRowHeight(): number | undefined;
+    /**
+     * Drops the cached results – the next cell read computes them again ({@link AreaModelIf.invalidateDerivedValues}).
+     * The table calls it when it filters, sorts, edits, gets `updateCells()` and on `tableApi.repaint()` / `repaintHard()`.
+     *
+     * @example
+     * order.total = 99;                                 // changed outside the table
+     * tableApi.repaint();                               // the cells and the footer show it
+     */
+    invalidateDerivedValues(): void;
+    /**
+     * The results of a footer row by key (also of keys without a column).
+     *
+     * @param {number} [rowIndex=0] - the footer row
+     * @returns {Record<string, unknown>} key → result (`{}` for a row that does not exist); do not modify it
+     *
+     * @example
+     * const footer = tableModel.getAreaModel("footer") as AreaModelAggregateFooter<Order>;
+     * document.title = `${formatAggregateValue(footer.getResults().total)} € in ${footer.getAggregationRowCount()} orders`;
+     */
+    getResults(rowIndex?: number): Record<string, unknown>;
+    /**
+     * The number of aggregated rows (e.g. the filtered body rows; in a tree the leaves).
+     *
+     * @returns {number} the number of rows the results are based on
+     */
+    getAggregationRowCount(): number;
+    /**
+     * Whether a cell shows the label of its footer row (the table gives it `role="rowheader"`).
+     *
+     * @param {number} rowIndex - footer row
+     * @param {number} columnIndex - column (model index)
+     * @returns {boolean} true for the label cell
+     */
+    isLabelCell(rowIndex: number, columnIndex: number): boolean;
+    getValueAt(rowIndex: number, columnIndex: number): any;
+    getTextValueAt(rowIndex: number, columnIndex: number): string;
+    /**
+     * The renderer of a cell: for a result the footer renderer of the column (it gets the raw value), otherwise – and for
+     * the label – an {@link AggregateCellRenderer} that writes {@link getTextValueAt} as text.
+     */
+    getCellRenderer(rowIndex: number, columnIndex: number): CellRendererIf | undefined;
+    getCustomClassesAt(rowIndex: number, columnIndex: number): string[];
+    /** The label column of a footer row, -1 for none. */
+    protected getLabelColumnIndex(rowIndex: number): number;
+    /** The label text of a footer row. */
+    protected getLabel(rowIndex: number): string;
+    /**
+     * The rows to aggregate: `getRows` of the options, the (filtered) rows of an object body, the leaves of a tree, or –
+     * for models without row objects – the row count.
+     * @internal
+     */
+    protected getSource(): AggregationSource;
+    /**
+     * The getter of a spec for a model without row objects: a property with a column → `getValueAt` of that column;
+     * a function or a path without column → applied to `getRowByIndex(r)`.
+     * @internal
+     */
+    protected createIndexGetter(body: AreaModelIf, spec: ResolvedAggregateSpec<T>): ((rowIndex: number) => unknown) | undefined;
+    private compute;
+}
+export {};

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

@@ -15,7 +15,7 @@ import { TableHeaderGroupStateIf } from '../../../state/table-state.if.js';
 /** @category Header groups */
 export declare class AreaModelCellGroups implements AreaModelIf {
     readonly areaIdent: AreaIdent;
-    readonly groups: CellGroupIf[];
+    groups: CellGroupIf[];
     columnDefs: ColumnDefIf[];
     readonly defaultRowHeight: number;
     private headerGroupOptions;
@@ -80,6 +80,23 @@ export declare class AreaModelCellGroups implements AreaModelIf {
      * @since 1.1.92
      */
     setGroupClosed(id: string, closed: boolean): ColumnDefIf[] | undefined;
+    /**
+     * Replaces the header groups (e.g. a pivot table with other column keys): builds the header rows again and returns
+     * the column definitions in header order – existing definitions with the same property are kept (width, classes,
+     * renderers), their visibility follows the (collapsed) groups. Repaint the table afterwards (a pivot table does all of
+     * this in {@link TableApi.setPivotConfig}).
+     *
+     * @param {CellGroupIf[]} groups - the new groups; every column is a leaf with a `property`
+     * @param {ColumnDefIf[]} [columnDefs] - definitions to use for these properties (default: the current ones)
+     * @returns {ColumnDefIf[]} the column definitions, one per leaf, in header order
+     * @example
+     * const header = tableApi.getTableModel().getAreaModel("header") as AreaModelCellGroups;
+     * const columnDefs = header.setGroups([
+     *   { data: "Customer", children: [{ data: "Name", property: "name" }, { data: "City", property: "city" }] }
+     * ]);
+     * @since 1.1.94
+     */
+    setGroups(groups: CellGroupIf[], columnDefs?: ColumnDefIf[]): ColumnDefIf[];
     /** The toggleable groups by id (header order). */
     private getToggleGroups;
     /**

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

@@ -0,0 +1,47 @@
+import { AreaModel } from './area-model.js';
+import { HasDefaultRowHeightIf } from './has-default-row-height-if.js';
+import { CellRendererIf } from '../../../renderer/cell-render.if.js';
+import { AreaModelPivot } from './area-model-pivot.js';
+
+/**
+ * The total row of a pivot table: the label `"Total"` in the group column and the column totals (cells, subtotals,
+ * grand total) of the {@link AreaModelPivot}. The totals come from the source rows (merged states), never from the
+ * displayed rows – an average stays the average of all rows. Created by {@link PivotFactory.createTableModel}
+ * (`totalRow: false` → no row).
+ *
+ * @example
+ * const footer = tableModel.getAreaModel("footer") as AreaModelPivotFooter;
+ * footer.getValueAt(0, pivotModel.getPivotBody().getColumnIndex([]));   // 450 – the grand total
+ *
+ * @since 1.1.94
+ * @category Pivot
+ */
+export declare class AreaModelPivotFooter<T = any> extends AreaModel implements HasDefaultRowHeightIf {
+    private readonly body;
+    defaultRowHeight: number;
+    /** Marker (works across copies of the core). */
+    readonly type = "AreaModelPivotFooter";
+    private readonly textRenderer;
+    /**
+     * @param {AreaModelPivot<T>} body - the pivot body (its columns and totals)
+     * @param {number} [defaultRowHeight=34] - row height in px
+     */
+    constructor(body: AreaModelPivot<T>, defaultRowHeight?: number);
+    /** 1 – or 0 with `totalRow: false` or without row fields (the body shows the total then). */
+    getRowCount(): number;
+    getRowHeight(_rowIndex: number): number;
+    getConstantRowHeight(): number | undefined;
+    getValueAt(rowIndex: number, columnIndex: number): any;
+    getTextValueAt(rowIndex: number, columnIndex: number): string;
+    getCellRenderer(_rowIndex: number, columnIndex: number): CellRendererIf | undefined;
+    getCustomClassesAt(rowIndex: number, columnIndex: number): string[];
+    /**
+     * True for the label cell ("Total") – the table gives it `role="rowheader"`.
+     *
+     * @param {number} rowIndex - footer row
+     * @param {number} columnIndex - column index
+     * @returns {boolean} true for the group column of the total row
+     */
+    isRowHeaderCell(rowIndex: number, columnIndex: number): boolean;
+    private isLabelColumn;
+}

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

@@ -0,0 +1,250 @@
+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 { RowGroupIf } from '../../../rowgroup/row-group.if.js';
+import { PivotConfigIf } from '../../../pivot/pivot-config.if.js';
+import { PivotColumnInfoIf } from '../../../pivot/pivot-column-info.if.js';
+import { PivotResult } from '../../../pivot/pivot-result.js';
+import { RowGroupColumnOptionsIf } from '../../../rowgroup/row-group-column-options.if.js';
+
+/**
+ * The body of a pivot table: one row per row group (a tree for several row fields, with subtotals in the group rows),
+ * one column per column key × value, plus subtotal and total columns. Created by {@link PivotFactory.createTableModel}
+ * – the factory also builds the grouped header and the total row.
+ *
+ * It is a tree ({@link AreaModelTree}, `isAreaModelTree` is true): rows are tree rows with a {@link RowGroupIf} as
+ * `data`; expanding, `tableApi.expandAll()`, keyboard, screen reader attributes and remembering expanded rows work as
+ * in a tree table. The cells come from a {@link PivotResult} ({@link getResult}).
+ *
+ * - **Filter**: `externalFilterFunction` gets your **source objects** (as in a flat table and a row grouping) – it
+ *   filters before the aggregation; all cells and totals follow. Rows without a matching source row disappear; the
+ *   columns stay (they come from all rows).
+ * - **Sorting**: by a value column → the rows of every level by that value (empty cells last); by the group column →
+ *   by key. `tableApi.sort(fn)` compares two {@link RowGroupIf}.
+ * - Cells are not editable. Changed source data: {@link TableApi.setPivotConfig} with new rows or `tableApi.repaint()` (same
+ *   keys), new keys or fields: {@link TableApi.setPivotConfig}.
+ *
+ * @example
+ * const tableModel = PivotFactory.createTableModel<Sale>({
+ *   rows: sales, rowFields: ["region"], columnFields: ["monat"], values: ["umsatz"]
+ * });
+ * const pivotBody = tableModel.getPivotBody();
+ * pivotBody.getValueAt(0, pivotBody.getColumnIndex(["Jan"]));   // 150 – Nord, Jan
+ *
+ * @see Training: [Pivot tables](https://gui.expert/training/pivot-tables/)
+ *
+ * @typeParam T - the row type
+ * @since 1.1.94
+ * @category Pivot
+ */
+export declare class AreaModelPivot<T = any> extends AreaModelTree<any> {
+    /** Marker for {@link isAreaModelPivot} (works across copies of the core). `type` stays `"AreaModelTree"`. */
+    readonly kind = "AreaModelPivot";
+    private config;
+    private sourceRows;
+    private result;
+    private rowFields;
+    private groupColumnOptions;
+    private readonly textRenderer;
+    private infoByProperty;
+    private userFilter?;
+    private accepted?;
+    private dirty;
+    private builds;
+    /**
+     * @param {T[]} rows - the source rows (not changed)
+     * @param {PivotConfigIf<T>} config - row fields, column fields, values
+     * @param {Partial<RowGroupColumnOptionsIf<T>>} [groupColumn] - label options of the group column (`showCount`, `label`)
+     * @param {number} [defaultRowHeight=34] - row height in px
+     */
+    constructor(rows: T[], config: PivotConfigIf<T>, groupColumn?: Partial<RowGroupColumnOptionsIf<T>>, defaultRowHeight?: number);
+    /**
+     * The current configuration.
+     *
+     * @returns {PivotConfigIf<T>} a copy
+     *
+     * @example
+     * pivotBody.getConfig().columnFields;   // ["monat"]
+     */
+    getConfig(): PivotConfigIf<T>;
+    /**
+     * The pivot: row and column hierarchies and all values (also subtotals and totals) – for drill-down, own
+     * evaluations or a chart next to the table.
+     *
+     * @returns {PivotResult<T>} the result (do not modify)
+     *
+     * @example
+     * const result = pivotBody.getResult();
+     * result.columnLeaves.map(c => c.label);   // ["Jan", "Feb"]
+     * result.getValue();                       // 450
+     */
+    getResult(): PivotResult<T>;
+    /**
+     * The rows the pivot is built from.
+     *
+     * @returns {T[]} the source rows (do not modify the array – use `tableApi.setPivotConfig({}, rows)`)
+     *
+     * @example
+     * pivotBody.getSourceRows().length;   // 6
+     */
+    getSourceRows(): T[];
+    /**
+     * Counts how often the pivot was built (start, new configuration, new rows).
+     *
+     * @returns {number} the number of builds
+     *
+     * @example
+     * const before = pivotBody.getBuildCount();
+     */
+    getBuildCount(): number;
+    /**
+     * Builds the pivot again (keys, rows) – {@link PivotTableModel.setPivotConfig} calls it, followed
+     * by the new columns ({@link setColumnDefs}). Expanded rows whose path stays keep their state; the filter stays, the
+     * sorting is reset.
+     *
+     * @param {PivotConfigIf<T>} config - the configuration
+     * @param {T[]} [rows] - new source rows (default: the current ones)
+     * @internal
+     */
+    configure(config: PivotConfigIf<T>, rows?: T[]): void;
+    /**
+     * Sets the columns (group column, value columns) after a new layout. @internal
+     *
+     * @param {ColumnDefIf[]} columnDefs - all columns of the table
+     */
+    setColumnDefs(columnDefs: ColumnDefIf[]): void;
+    /**
+     * The property of a column (follows moved columns).
+     *
+     * @param {number} columnIndex - column index
+     * @returns {string | undefined} the property, e.g. {@link RowGroupColumnDef.PROPERTY} for the group column
+     *
+     * @example
+     * pivotBody.getPropertyAt(0);   // "RowGroupColumn"
+     */
+    getPropertyAt(columnIndex: number): string | undefined;
+    /**
+     * The row group of a displayed row.
+     *
+     * @param {number} rowIndex - index of the displayed body row
+     * @returns {RowGroupIf<T> | undefined} the group, undefined for the total row of a pivot without row fields
+     *
+     * @example
+     * pivotBody.getRowGroup(0)?.path;   // ["Nord"]
+     */
+    getRowGroup(rowIndex: number): RowGroupIf<T> | undefined;
+    /**
+     * What a column shows: a column key, a subtotal or a total, and which value.
+     *
+     * @param {number} columnIndex - column index
+     * @returns {PivotColumnInfoIf | undefined} undefined for the group column (and row numbers)
+     *
+     * @example
+     * pivotBody.getColumnInfo(1)?.column?.label;   // "Jan"
+     */
+    getColumnInfo(columnIndex: number): PivotColumnInfoIf | undefined;
+    /**
+     * The property of a value column – for `tableApi.getColumnIndex()`, `sortByColumn()`, `setColumnWidth()` …
+     *
+     * @param {unknown[]} columnPath - the column keys from the top column field down, e.g. `[2026, 1]`; `[]` = the total column
+     * @param {number | string} [value=0] - the index or name of the value
+     * @returns {string | undefined} the property, undefined if there is no such column
+     *
+     * @example
+     * tableApi.sortByColumn(pivotBody.getColumnProperty([])!, "desc");   // rows by their total, largest first
+     */
+    getColumnProperty(columnPath: unknown[], value?: number | string): string | undefined;
+    /**
+     * The index of a value column (see {@link getColumnProperty}).
+     *
+     * @param {unknown[]} columnPath - the column keys, `[]` = the total column
+     * @param {number | string} [value=0] - the index or name of the value
+     * @returns {number} the column index or -1
+     *
+     * @example
+     * pivotBody.getColumnIndex(["Jan"]);   // 1
+     */
+    getColumnIndex(columnPath: unknown[], value?: number | string): number;
+    /**
+     * The source rows behind a cell (drill-down): the rows of its row group and column key that the filter keeps.
+     *
+     * @param {number} rowIndex - index of the displayed body row
+     * @param {number} columnIndex - column index (the group column: all rows of the row group)
+     * @returns {T[]} a new array in source order
+     *
+     * @example
+     * pivotBody.getCellSourceRows(0, 1).map(s => s.umsatz);   // [100, 50] – Nord, Jan
+     */
+    getCellSourceRows(rowIndex: number, columnIndex: number): T[];
+    getValueAt(rowIndex: number, columnIndex: number): any;
+    getTextValueAt(rowIndex: number, columnIndex: number): string;
+    /** Value columns: the {@link AggregateCellRenderer} (text node); the group column: none (label as text). */
+    getCellRenderer(_rowIndex: number, columnIndex: number): CellRendererIf | undefined;
+    getCustomClassesAt(rowIndex: number, columnIndex: number): string[];
+    /**
+     * True for the label cell of a 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 column
+     */
+    isRowHeaderCell(rowIndex: number, columnIndex: number): boolean;
+    /** Pivot cells are computed – not editable. */
+    isEditable(_rowIndex: number, _columnIndex: number): boolean;
+    /** Pivot cells are computed – `setValue` does nothing (`false`). */
+    setValue(_rowIndex: number, _columnIndex: number, _value: any): boolean;
+    /**
+     * Filters the **source rows** before the aggregation: `predictFn` gets your objects (as in a flat table), index and
+     * array of the source rows. All cells and totals follow; rows without a matching source row disappear. Usually
+     * called by `tableApi.externalFilterChanged()` with `tableOptions.externalFilterFunction`.
+     *
+     * @param {FilterFunction<S>} predictFn - returns a truthy value for the rows to count
+     *
+     * @example
+     * tableOptions.externalFilterFunction = (sale: Sale) => sale.produkt === "A";
+     * tableApi.externalFilterChanged();   // Nord: Jan 100, Feb 120 · Süd: Jan 80, Feb 30
+     */
+    externalFilterChanged<S>(predictFn: FilterFunction<S>): void;
+    /**
+     * Sorts the rows of every level: by a value column by its values (empty cells last, in both directions), by the
+     * group column by key. A new pivot ({@link TableApi.setPivotConfig}) starts unsorted (the columns are different).
+     *
+     * @param {SortItem[]} sortItems - primary key first
+     * @returns {boolean} false for an empty list
+     *
+     * @example
+     * pivotBody.doSort([new SortItem(pivotBody.getColumnIndex([]), "desc")]);   // by the total, largest first
+     * tableApi.repaint();
+     */
+    doSort(sortItems: SortItem[]): boolean;
+    /**
+     * Sorts the rows of every level with your function – it gets two {@link RowGroupIf} (siblings).
+     *
+     * @param {(a: any, b: any) => number} compareFn - compares two row groups
+     *
+     * @example
+     * tableApi.sort((a: RowGroupIf, b: RowGroupIf) => b.count - a.count);   // most source rows first
+     */
+    sort(compareFn: (a: any, b: any) => number): void;
+    /**
+     * Computes the cells again on the next read – the table calls it after filter, sorting and `tableApi.repaint()`.
+     *
+     * @example
+     * sales[0].umsatz = 999;   // changed outside the table
+     * tableApi.repaint();      // calls invalidateDerivedValues() – all cells are computed again
+     */
+    invalidateDerivedValues(): void;
+    private isSubtotalSuppressed;
+    /** The label of a row in the group column. */
+    protected getGroupLabel(group: RowGroupIf<T>): string;
+    private ensureComputed;
+    /** The filter result per source row (1 = counted). */
+    private acceptedBy;
+    private createRowComparator;
+    /** (Re)builds the pivot and the tree rows; keeps the expanded state of known row groups and the filter (a new pivot is unsorted). */
+    private build;
+    private createRow;
+    private isExpandedByDefault;
+}