@guiexpert/table 1.1.92 → 1.1.94

package/lib/table/selection/selection-service.d.ts

@@ -51,6 +51,13 @@ export declare class SelectionService implements OnActionTriggeredIf {
      */
     onMouseClicked(evt: GeMouseEvent, _previousEvt: GeMouseEvent | undefined): boolean;
     onActionTriggered(actionId: ActionId): boolean;
+    /** True if the column is a row number column ({@link RowNumberColumnDef}). */
+    private isRowNumberColumn;
+    /** A click on the header cell of the row numbers: everything (selection types "row" and "range"). */
+    private selectAllByRowNumberHeader;
+    /** Selection type "range", click on a row number: the whole row – new, toggled (Ctrl/⌘) or removed (Ctrl/⌘+Alt). */
+    private clickRowNumber;
+    private static isRangeSelection;
     /** Speaks a message for screen readers – only if the selection model can select anything. */
     private announce;
     /** Runs `fn` so that all selection changes in it reach the table's listener as ONE onSelectionChanged event. */

package/lib/table/service/convenience-dom.service.d.ts

@@ -26,6 +26,11 @@ export interface AddColumnDivPara {
     sortState?: SortState;
     /** Accessible name of the row checkbox (`showCheckboxWihoutExtraColumn`), e.g. "Select row 5". @since 1.1.91 */
     checkboxAriaLabel?: string;
+    /**
+     * Index of the first data column – the column of the checkbox of `showCheckboxWihoutExtraColumn` and of the tree
+     * label. 0, behind a {@link RowNumberColumnDef} 1. Default 0. @since 1.1.93
+     */
+    firstDataColumnIndex?: number;
 }
 /** @category DOM */
 export declare class ConvenienceDomService {

package/lib/table/table-api.d.ts

@@ -10,6 +10,9 @@ import { ShortcutActionIdMapping } from './action/shortcut-actionid-mapping.type
 import { SelectionModelIf } from './selection/selection-model.if.js';
 import { TableModelIf } from './data/tablemodel/table-model.if.js';
 import { AreaModelIf } from './data/tablemodel/areamodel/area-model.if.js';
+import { PivotConfigIf } from './pivot/pivot-config.if.js';
+import { RowGroupField } from './rowgroup/row-group-field.type.js';
+import { SelectionAggregatesIf } from './aggregation/selection-aggregates.if.js';
 
 /**
  * The public API of one table – everything you do with a table after it has been created:
@@ -36,7 +39,7 @@ import { AreaModelIf } from './data/tablemodel/areamodel/area-model.if.js';
  * | export | {@link copyToClipboard}, {@link downloadExcel} |
  * | change data | {@link updateCells}, {@link setRows}, {@link addRows}, {@link updateRows}, {@link removeRows} |
  * | redraw | {@link repaint} (same row count), {@link repaintHard} (row count or heights changed) |
- * | columns | {@link autoResizeColumns}, {@link setColumnWidth}, {@link recalcColumnWidths} |
+ * | columns | {@link autoResizeColumns}, {@link setColumnWidth}, {@link recalcColumnWidths}, {@link getColumnIndex} |
  * | tree | {@link expandAll}, {@link collapseAll}, {@link setRowExpanded} |
  * | state | {@link getState}, {@link applyState}, {@link resetState} (with {@link TableOptionsIf.autoRestoreOptions}) |
  * | lifecycle | {@link destroy} |
@@ -390,6 +393,9 @@ export declare class TableApi {
      * Repainting the table ensures that all visible cells, rows, and styling reflect the
      * current state of the underlying data model and configuration settings.
      *
+     * Since 1.1.94 it also drops cached totals ({@link AreaModelIf.invalidateDerivedValues}, e.g. of a footer from
+     * `footerAggregates`), so they are computed again from the changed rows. Scrolling never does that.
+     *
      * @example
      * // Update data and repaint the table
      * const tableApi = new TableApi(tableScope);
@@ -805,6 +811,25 @@ export declare class TableApi {
      * tableApi.downloadExcel('quarterly-data.xlsx');
      */
     downloadExcel(fileName?: string, author?: string): Promise<void>;
+    /** The value of a cell for the Excel export – the shown number in a row number column (body; footer empty). */
+    private getExportValue;
+    /**
+     * The index of the column that shows a property – `-1` if there is none.
+     *
+     * Column indices count all columns, also a {@link RowNumberColumnDef} or {@link CheckboxColumnDef} in front:
+     * with row numbers (`rowNumbersVisible: true`) every data column has an index one higher. Get the index by the
+     * property instead of writing numbers into your code.
+     *
+     * @param {string} property - the property of the column definition, e.g. `"total"`
+     * @returns {number} the column index (fixed columns included) or -1
+     *
+     * @example
+     * const totalColumn = tableApi.getColumnIndex("total");
+     * tableApi.scrollToIndex(totalColumn, 0);
+     *
+     * @since 1.1.93
+     */
+    getColumnIndex(property: string): number;
     /**
      * Returns the TableScope instance associated with this TableApi.
      *
@@ -866,6 +891,28 @@ export declare class TableApi {
      * });
      */
     getSelectionModel(): SelectionModelIf | undefined;
+    /**
+     * Count, sum, average, minimum and maximum of the selected body cells – for a status bar like in a spreadsheet.
+     * Counted are the selected cells of the visible data columns; the numbers are the cell values of type `number`.
+     * Above {@link SelectionAggregator.maxCells} cells (default 1,000,000) nothing is computed (`capped: true`).
+     * Without a selection all values are 0 / `undefined`.
+     *
+     * @returns {SelectionAggregatesIf} `{ count, numericCount, sum, avg, min, max, capped }`
+     *
+     * @example
+     * // a status bar in plain HTML under the table
+     * const statusBar = document.querySelector<HTMLDivElement>("#status")!;
+     * const listener = new EventAdapter();
+     * listener.onSelectionChanged = () => {
+     *   const a = tableApi.getSelectionAggregates();
+     *   statusBar.textContent = a.capped ? "Selection too large"
+     *     : a.numericCount ? `Count ${a.count} · Sum ${formatAggregateValue(a.sum)} · Average ${formatAggregateValue(a.avg)}`
+     *     : "";
+     * };
+     *
+     * @since 1.1.94
+     */
+    getSelectionAggregates(): SelectionAggregatesIf;
     /**
      * Automatically resizes all columns to fit their content.
      *
@@ -1186,6 +1233,70 @@ export declare class TableApi {
      * tableApi.setRowExpanded(0, true);   // expand the first row
      */
     setRowExpanded(rowIndex: number, expanded: boolean): boolean;
+    /**
+     * Row grouping ({@link RowGroupFactory}): groups the rows by other levels – without a new table model (a new model
+     * would rebuild the table in every framework wrapper). Groups whose path stays keep their expanded state; filter,
+     * sorting and checked rows stay; the columns of the grouped properties are hidden (the previously grouped ones come
+     * back) and the header of the group column follows. An empty list shows the rows without groups.
+     *
+     * @param {RowGroupField[]} groupBy - the new levels, top first: property paths, functions or {@link RowGroupFieldIf}
+     * @returns {boolean} false if the body is no row grouping
+     *
+     * @example
+     * // a select with "region", "produkt", "region,produkt"
+     * select.addEventListener("change", () => tableApi.setRowGroupBy(select.value.split(",")));
+     *
+     * @example
+     * tableApi.setRowGroupBy([]);   // flat again (with the total row)
+     *
+     * @since 1.1.94
+     */
+    setRowGroupBy(groupBy: RowGroupField[]): boolean;
+    /**
+     * Row grouping: the current levels.
+     *
+     * @returns {RowGroupField[] | undefined} the levels, undefined if the body is no row grouping
+     *
+     * @example
+     * const levels = tableApi.getRowGroupBy();   // ["region", "produkt"]
+     *
+     * @since 1.1.94
+     */
+    getRowGroupBy(): RowGroupField[] | undefined;
+    /**
+     * Pivot table ({@link PivotFactory}): pivots again – other row fields, column fields or values, or new rows –
+     * without a new table model (a new model would rebuild the table in every framework wrapper). The model gets new
+     * columns, header and totals; rows whose path stays keep their expanded state, the filter stays, column widths of
+     * columns that stay are kept, so are columns hidden with `setColumnVisible`. Sorting, selection and focus are reset
+     * (the columns are different). An invalid configuration throws and changes nothing.
+     *
+     * @param {Partial<PivotConfigIf>} changes - the changed parts, e.g. `{ columnFields: ["jahr"] }`; `{}` = pivot the
+     *   current rows again (e.g. after new keys)
+     * @param {any[]} [rows] - new source rows (default: the current ones)
+     * @returns {boolean} false if the table model is no pivot table
+     *
+     * @example
+     * // a select with the column field
+     * select.addEventListener("change", () => tableApi.setPivotConfig({ columnFields: [select.value] }));
+     *
+     * @example
+     * tableApi.setPivotConfig({ values: [{ value: "umsatz", aggregator: "avg" }] });   // averages instead of sums
+     * tableApi.setPivotConfig({}, await loadSales());                                 // new data
+     *
+     * @since 1.1.94
+     */
+    setPivotConfig(changes: Partial<PivotConfigIf>, rows?: any[]): boolean;
+    /**
+     * Pivot table: the current configuration.
+     *
+     * @returns {PivotConfigIf | undefined} a copy, undefined if the table model is no pivot table
+     *
+     * @example
+     * const columnFields = tableApi.getPivotConfig()?.columnFields;   // ["monat"]
+     *
+     * @since 1.1.94
+     */
+    getPivotConfig(): PivotConfigIf | undefined;
     /**
      * Sorts the table data using a custom comparison function.
      *

package/lib/table/table-scope.d.ts

@@ -22,6 +22,8 @@ import { OnActionTriggeredIf } from './action/on-action-triggered.if.js';
 import { ActionId } from './action/action-id.type.js';
 import { ShortcutService } from './action/shortcut.service.js';
 import { TreeRowIf } from './data/common/tree-row-if.js';
+import { PivotConfigIf } from './pivot/pivot-config.if.js';
+import { RowGroupField } from './rowgroup/row-group-field.type.js';
 import { LicenseManager } from './license-manager.js';
 import { SelectionModel } from './selection/selection-model.js';
 import { CopyServiceIf } from './service/copy-service.if.js';
@@ -329,6 +331,23 @@ export declare class TableScope extends RenderScope implements OnActionTriggered
      * @returns {boolean} false if the body is no tree or the state was already set
      */
     setTreeRowExpanded(row: TreeRowIf<any>, expanded: boolean): boolean;
+    /**
+     * Groups the rows of a row grouping by other levels (see {@link TableApi.setRowGroupBy}).
+     *
+     * @param {RowGroupField[]} groupBy - the new levels, top first
+     * @returns {boolean} false if the body is no row grouping
+     */
+    setRowGroupBy(groupBy: RowGroupField[]): boolean;
+    /**
+     * Pivots a pivot table again (see {@link TableApi.setPivotConfig}): new columns, header and totals in the same model,
+     * then the layout of the table is built again. Sorting and selection are reset (the columns are different).
+     *
+     * @param {Partial<PivotConfigIf>} changes - the changed parts of the configuration
+     * @param {unknown[]} [rows] - new source rows
+     * @returns {boolean} false if the table model is no pivot table
+     * @since 1.1.94
+     */
+    setPivotConfig(changes: Partial<PivotConfigIf>, rows?: unknown[]): boolean;
     /**
      * Toggles the checkbox state of a specific row in a table.
      *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guiexpert/table",
-  "version": "1.1.92",
+  "version": "1.1.94",
   "license": "MIT",
   "author": "Dr. Marc Kronberg <info@gui.expert> (https://gui.expert)",
   "repository": {
@@ -73,6 +73,7 @@
     "test:watch": "vitest --project unit",
     "test:coverage": "vitest run --coverage",
     "test:types": "tsc -p tsconfig.spec.json --noEmit",
-    "npm-pub": "pnpm publish --no-git-checks --access public"
+    "npm-pub": "pnpm publish --no-git-checks --access public",
+    "bench": "vitest run --config bench/vitest.bench.config.ts"
   }
 }