@guiexpert/table 1.1.90 → 1.1.92

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

@@ -1,9 +1,9 @@
-import { CellRendererIf } from '../../../renderer/cell-render.if';
-import { CheckedType } from '../../common/checked-type';
-import { CheckboxModelIf } from '../../../checkbox/checkbox-model.if';
-import { FilterFunction } from '../../common/filter-function';
-import { SortItem } from '../../common/sort-item';
-import { AreaIdent } from '../area-ident.type';
+import { CellRendererIf } from '../../../renderer/cell-render.if.js';
+import { CheckedType } from '../../common/checked-type.js';
+import { CheckboxModelIf } from '../../../checkbox/checkbox-model.if.js';
+import { FilterFunction } from '../../common/filter-function.js';
+import { SortItem } from '../../common/sort-item.js';
+import { AreaIdent } from '../area-ident.type.js';
 
 /**
  * @interface AreaModelIf
@@ -57,7 +57,7 @@ import { AreaIdent } from '../area-ident.type';
  *   [2, "Jane", 25],
  *   [3, "Bob", 40]
  * ];
- * const footerData = [["", "Average", 31.67]];
+ * const footerData = [["", "Average", "31.67"]];
  *
  * // Create the table model with all three areas
  * const tableModel: TableModelIf = TableFactory.createTableModel({
@@ -88,9 +88,9 @@ import { AreaIdent } from '../area-ident.type';
  *
  * // Define column definitions
  * const columnDefs: ColumnDefIf[] = [
- *   { property: "id", headerLabel: "ID", width: 80 },
- *   { property: "name", headerLabel: "Name", width: 150 },
- *   { property: "age", headerLabel: "Age", width: 80 }
+ *   new ColumnDef('id', 'ID', new Size(80, 'px')),
+ *   new ColumnDef('name', 'Name', new Size(150, 'px')),
+ *   new ColumnDef('age', 'Age', new Size(80, 'px'))
  * ];
  *
  * // Create the table model
@@ -109,35 +109,36 @@ import { AreaIdent } from '../area-ident.type';
  * // Example of implementing a custom AreaModelIf
  * import { AreaModelIf, AreaIdent, CellRendererIf } from "@guiexpert/table";
  *
- * class CustomAreaModel implements AreaModelIf {
+ * class CustomAreaModel extends AreaModel {
  *   constructor(
- *     public areaIdent: AreaIdent,
- *     private data: any[][],
- *     private defaultRowHeight: number = 30
- *   ) {}
+ *     areaIdent: AreaIdent,
+ *     private readonly data: any[][],
+ *     private readonly rowHeight: number = 30
+ *   ) {
+ *     super();
+ *     this.areaIdent = areaIdent;
+ *   }
  *
- *   getRowCount(): number {
+ *   override getRowCount(): number {
  *     return this.data.length;
  *   }
  *
- *   getValueAt(rowIndex: number, columnIndex: number): any {
- *     if (rowIndex < 0 || rowIndex >= this.data.length) return undefined;
- *     const row = this.data[rowIndex];
- *     if (columnIndex < 0 || columnIndex >= row.length) return undefined;
- *     return row[columnIndex];
+ *   override getValueAt(rowIndex: number, columnIndex: number): any {
+ *     return this.data[rowIndex]?.[columnIndex];
  *   }
  *
- *   getRowHeight(rowIndex: number): number {
- *     return this.defaultRowHeight;
+ *   override getRowHeight(_rowIndex: number): number {
+ *     return this.rowHeight;
  *   }
- *
- *   // Implement other required methods...
+ *   // AreaModel has defaults for all other methods
  * }
  *
  * @see {@link TableModelIf} - The parent interface that contains area models
  * @see {@link AreaModel} - A base implementation of this interface
  * @see {@link AbstractAreaModel} - An abstract implementation with common functionality
  * @see {@link AreaModelObjectArray} - An implementation for object array data
+ *
+ * @category Area models
  */
 export interface AreaModelIf {
     /**
@@ -148,7 +149,8 @@ export interface AreaModelIf {
      *
      * @example
      * // Creating an area model for the header
-     * const headerModel = new AreaModel("header");
+     * const headerModel = new AreaModel();
+     * headerModel.areaIdent = "header";
      *
      * @example
      * // Checking which area a model represents
@@ -167,7 +169,8 @@ export interface AreaModelIf {
      * // Creating a checkbox model for row selection
      * import { CheckboxModel } from "@guiexpert/table";
      *
-     * const bodyModel = new AreaModel("body");
+     * const bodyModel = new AreaModel();
+     * bodyModel.areaIdent = "body";
      * bodyModel.rowSelectionModel = new CheckboxModel();
      *
      * // Later, check if a row is selected
@@ -258,6 +261,25 @@ export interface AreaModelIf {
      * }
      */
     getRowCount(): number;
+    /**
+     * The number of rows the area would show **without** the external filter. Optional: the table uses it to tell
+     * "No rows to show" (no rows at all) from "No matching rows" (the filter hides all rows) – see
+     * {@link OverlayOptionsIf}. Models without it always get "No rows to show".
+     *
+     * @returns {number} e.g. all rows of an object array; for a tree the displayed rows before filtering
+     *
+     * @example
+     * class OrdersBodyModel extends AreaModel {
+     *   private all: string[][] = [];
+     *   private shown: string[][] = [];
+     *   override getRowCount(): number { return this.shown.length; }
+     *   getUnfilteredRowCount(): number { return this.all.length; }
+     *   override getValueAt(rowIndex: number, columnIndex: number): any { return this.shown[rowIndex]?.[columnIndex]; }
+     * }
+     *
+     * @since 1.1.92
+     */
+    getUnfilteredRowCount?(): number;
     /**
      * 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
@@ -673,7 +695,8 @@ export interface AreaModelIf {
     isEditable(rowIndex: number, columnIndex: number): boolean;
     /**
      * Determines whether the cell at the specified row and column indices is selectable.
-     * If true, the user can select the cell.
+     * If true, the user can select the cell: the table draws the selection only on selectable body cells.
+     * All built-in models and {@link AreaModel} return `true` (except the hidden and cover-grid models).
      *
      * @param {number} rowIndex - The index of the row
      * @param {number} columnIndex - The index of the column
@@ -733,9 +756,9 @@ export interface AreaModelIf {
      * @example
      * // Check if a row is checked
      * const checkedState = bodyAreaModel.isRowChecked(1);
-     * if (checkedState === true) {
+     * if (checkedState === "full") {
      *   console.log('This row is checked');
-     * } else if (checkedState === 'indeterminate') {
+     * } else if (checkedState === "semi") {
      *   console.log('This row is partially checked');
      * }
      *
@@ -836,27 +859,29 @@ export interface AreaModelIf {
      * ]);
      *
      * @example
-     * // Implementation example
-     * doSort(sortItems: SortItem[]): boolean {
-     *   if (!sortItems.length) return false;
-     *
-     *   // Apply sorting to the rows
-     *   for (const sortItem of sortItems) {
-     *     const { columnIndex, sortState } = sortItem;
-     *     const property = this.columnDefs[columnIndex].property;
-     *     const direction = sortState === 'asc' ? 1 : -1;
-     *
-     *     this.rows.sort((a, b) => {
-     *       const valueA = a[property];
-     *       const valueB = b[property];
-     *
-     *       if (valueA < valueB) return -1 * direction;
-     *       if (valueA > valueB) return 1 * direction;
-     *       return 0;
-     *     });
-     *   }
+     * // Implementation example: a body model that sorts its own rows
+     * class MyBodyModel extends AreaModelObjectArray<any> {
+     *   override doSort(sortItems: SortItem[]): boolean {
+     *     if (!sortItems.length) return false;
      *
-     *   return true;
+     *     // Apply sorting to the rows
+     *     for (const sortItem of sortItems) {
+     *       const { columnIndex, sortState } = sortItem;
+     *       const property = this.columnDefs[columnIndex].property;
+     *       const direction = sortState === 'asc' ? 1 : -1;
+     *
+     *       this.rows.sort((a, b) => {
+     *         const valueA = a[property];
+     *         const valueB = b[property];
+     *
+     *         if (valueA < valueB) return -1 * direction;
+     *         if (valueA > valueB) return 1 * direction;
+     *         return 0;
+     *       });
+     *     }
+     *
+     *     return true;
+     *   }
      * }
      */
     doSort(sortItems: SortItem[]): boolean;

package/lib/table/data/tablemodel/areamodel/async-area-model-object-array.d.ts

@@ -1,8 +1,8 @@
-import { AbstractAreaModel } from './abstract-area-model';
-import { ColumnDefIf } from '../column/column-def.if';
-import { FilterFunction } from '../../common/filter-function';
-import { SorterService } from '../../../service/sorter.service';
-import { SortItem } from '../../common/sort-item';
+import { AbstractAreaModel } from './abstract-area-model.js';
+import { ColumnDefIf } from '../column/column-def.if.js';
+import { FilterFunction } from '../../common/filter-function.js';
+import { SorterService } from '../../../service/sorter.service.js';
+import { SortItem } from '../../common/sort-item.js';
 
 export declare class AsyncBodyAreaModelObjectArray<T> extends AbstractAreaModel<T> {
     protected readonly maxRowCount: number;

package/lib/table/data/tablemodel/areamodel/col-and-rowspan-model.d.ts

@@ -1,16 +1,27 @@
-import { CellRange } from '../../common/cell-range';
-import { AreaModelIf } from './area-model.if';
-import { TableModelIf } from '../table-model.if';
+import { CellRange } from '../../common/cell-range.js';
+import { AreaModelIf } from './area-model.if.js';
+import { TableModelIf } from '../table-model.if.js';
 
 /**
  * Represents a model for handling colspan and rowspan in a table.
+ *
+ * @category Area models
  */
 export declare class ColAndRowspanModel {
     protected tableModel: TableModelIf;
     protected areaModel: AreaModelIf;
     protected colAndRowspanRanges: CellRange[] | undefined;
     constructor(tableModel: TableModelIf, areaModel: AreaModelIf);
+    /** Row count of the area model at the last {@link init} (−1: not initialized yet). */
+    protected rowCountAtInit: number;
     init(): void;
+    /**
+     * Builds the ranges again if the row count of the area model changed since the last {@link init} – e.g. after
+     * `setRows()` or a filter (the old ranges could point to rows that no longer exist). Cheap otherwise.
+     *
+     * @returns {boolean} true if the ranges were rebuilt
+     */
+    initIfRowCountChanged(): boolean;
     getRanges(): CellRange[];
     isInRange(rowIndex: number, columnIndex: number): boolean;
 }

package/lib/table/data/tablemodel/areamodel/cover-grid-body-model.d.ts

@@ -1,12 +1,13 @@
-import { AreaModelIf } from './area-model.if';
-import { CellRendererIf } from '../../../renderer/cell-render.if';
-import { CheckedType } from '../../common/checked-type';
-import { CheckboxModelIf } from '../../../checkbox/checkbox-model.if';
-import { FilterFunction } from '../../common/filter-function';
-import { SortItem } from '../../common/sort-item';
-import { AreaIdent } from '../area-ident.type';
-import { SorterService } from '../../../service/sorter.service';
+import { AreaModelIf } from './area-model.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';
+import { FilterFunction } from '../../common/filter-function.js';
+import { SortItem } from '../../common/sort-item.js';
+import { AreaIdent } from '../area-ident.type.js';
+import { SorterService } from '../../../service/sorter.service.js';
 
+/** @category Area models */
 export declare class CoverGridBodyModel<T> implements AreaModelIf {
     items: T[];
     cellRenderer: CellRendererIf;
@@ -17,10 +18,18 @@ export declare class CoverGridBodyModel<T> implements AreaModelIf {
     rowSelectionModel: CheckboxModelIf<any> | undefined;
     areaIdent: AreaIdent;
     filteredItems: T[];
+    /** @internal */
     protected sorterService: SorterService;
     constructor(items: T[], cellRenderer: CellRendererIf, coverWidth?: number, coverHeight?: number, width?: number, firstRowPaddingTop?: number);
     setParentWidth(widthInPixel: number): void;
     getRowCount(): number;
+    /**
+     * The number of grid rows without the external filter (`0` without items).
+     *
+     * @returns {number} grid rows for all items
+     * @since 1.1.92
+     */
+    getUnfilteredRowCount(): number;
     getColumnCount(): number;
     getValueAt(rowIndex: number, columnIndex: number): T | undefined;
     getTextValueAt(_rowIndex: number, _columnIndex: number): string;

package/lib/table/data/tablemodel/areamodel/has-default-row-height-if.d.ts

@@ -1,3 +1,4 @@
+/** @category Area models */
 export interface HasDefaultRowHeightIf {
     defaultRowHeight: number;
 }

package/lib/table/data/tablemodel/areamodel/object-array-holder.if.d.ts

@@ -1,3 +1,4 @@
+/** @category Area models */
 export interface ObjectArrayHolderIf<T> {
     getAllRows(): T[];
     getFilteredRows(): T[];

package/lib/table/data/tablemodel/cellgroup/cell-group-ext.d.ts

@@ -1,6 +1,7 @@
-import { CellGroupIf } from './cell-group.if';
-import { CellGroup } from './cell-group';
+import { CellGroupIf } from './cell-group.if.js';
+import { CellGroup } from './cell-group.js';
 
+/** @category Header groups */
 export declare class CellGroupExt extends CellGroup {
     rowIndex: number;
     childIndex: number;

package/lib/table/data/tablemodel/cellgroup/cell-group.d.ts

@@ -1,5 +1,6 @@
-import { CellGroupIf } from './cell-group.if';
+import { CellGroupIf } from './cell-group.if.js';
 
+/** @category Header groups */
 export declare class CellGroup implements CellGroupIf {
     data: any;
     property?: string | undefined;
@@ -8,5 +9,7 @@ export declare class CellGroup implements CellGroupIf {
     visibility: "always" | "inverted" | "normal" | undefined;
     children: CellGroupIf[] | undefined;
     impl: string;
+    /** See {@link CellGroupIf.id}. @since 1.1.92 */
+    id?: string;
     constructor(data: any, property?: string | undefined, toggle?: boolean | undefined, closed?: boolean, visibility?: "always" | "inverted" | "normal" | undefined, children?: CellGroupIf[] | undefined);
 }

package/lib/table/data/tablemodel/cellgroup/cell-group.if.d.ts

@@ -1,9 +1,43 @@
+/**
+ * One node of a grouped header ({@link AreaModelCellGroups}): a group with `children`, or a leaf with a `property`
+ * (a leaf becomes a column).
+ *
+ * @example
+ * const groups: CellGroupIf[] = [
+ *   { data: "Order", children: [{ data: "ID", property: "id" }, { data: "Date", property: "date" }] },
+ *   { data: "Customer", toggle: true, children: [
+ *     { data: "Customer", property: "customer", visibility: "always" },   // stays visible when collapsed
+ *     { data: "City", property: "city" }] }
+ * ];
+ * const columnDefs = CellgroupFactory.buildColumnDefs(CellgroupFactory.buildGroupExts(groups));
+ * const header = new AreaModelCellGroups("header", groups, columnDefs, 34);
+ *
+ * @see Training: [Header models: multi-row and grouped](https://gui.expert/training/header-groups/)
+ *
+ * @category Header groups
+ */
 export interface CellGroupIf {
+    /**
+     * A stable id of the group, used to remember whether it is collapsed ({@link TableHeaderGroupStateIf},
+     * {@link TableApi.setHeaderGroupCollapsed}). Default: the path of the labels, e.g. `"Customer"` or `"2026/Q1"`.
+     * @since 1.1.92
+     */
+    id?: string;
+    /** The label of the group or column. */
     data: any;
+    /** Set on leaves only: the property shown in this column. */
     property?: string;
+    /** Show a ❯ toggle so that the user can collapse / expand the group. */
     toggle?: boolean;
+    /** Current state: collapsed. */
     closed?: boolean;
+    /**
+     * When is this child visible? `"always"` – also when the group is collapsed; `"inverted"` – only when collapsed
+     * (e.g. a summary column); `"normal"` / undefined – only when expanded.
+     */
     visibility?: "always" | "inverted" | "normal" | undefined;
+    /** Sub-groups or columns. */
     children?: CellGroupIf[] | undefined;
+    /** Internal: the implementation type of the node. */
     impl?: string;
 }

package/lib/table/data/tablemodel/cellgroup/cellgroup-factory.d.ts

@@ -1,7 +1,8 @@
-import { CellGroupIf } from './cell-group.if';
-import { ColumnDefIf } from '../column/column-def.if';
-import { CellGroupExt } from './cell-group-ext';
+import { CellGroupIf } from './cell-group.if.js';
+import { ColumnDefIf } from '../column/column-def.if.js';
+import { CellGroupExt } from './cell-group-ext.js';
 
+/** @category Header groups */
 export declare class CellgroupFactory {
     static buildColumnDefs(cellGroups: CellGroupIf[], ret?: ColumnDefIf[]): ColumnDefIf[];
     static buildGroupExts(cellGroups: CellGroupIf[], ret?: CellGroupExt[], deep?: number, parent?: CellGroupExt): CellGroupExt[];

package/lib/table/data/tablemodel/column/column-def.d.ts

@@ -1,15 +1,38 @@
-import { SizeIf } from '../../common/size.if';
-import { ColumnDefIf, ValueRowSortComparator } from './column-def.if';
-import { CellRendererIf } from '../../../renderer/cell-render.if';
-import { AreaObjectMapType } from '../../common/area-map.type';
-import { AreaObjectMap } from '../../common/area-map';
-import { BooleanFunction } from '../../common/boolean-function';
-import { SortState } from '../../common/sort-state.type';
-import { GetEditRenderer } from '../../../renderer/edit/edit-cell-renderer.type';
-import { editInputPipe } from '../../../renderer/edit/edit-input-pipe.if';
+import { SizeIf } from '../../common/size.if.js';
+import { ColumnDefIf, ValueRowSortComparator } from './column-def.if.js';
+import { CellRendererIf } from '../../../renderer/cell-render.if.js';
+import { AreaObjectMapType } from '../../common/area-map.type.js';
+import { AreaObjectMap } from '../../common/area-map.js';
+import { BooleanFunction } from '../../common/boolean-function.js';
+import { SortState } from '../../common/sort-state.type.js';
+import { GetEditRenderer } from '../../../renderer/edit/edit-cell-renderer.type.js';
+import { editInputPipe } from '../../../renderer/edit/edit-input-pipe.if.js';
 
 /**
- * Represents a column definition for one column of the table.
+ * The column definition – see {@link ColumnDefIf} for all fields.
+ *
+ * Two ways to create one:
+ *
+ * @example
+ * // short: property, header label, width, CSS classes
+ * new ColumnDef("customer", "Customer", px180, bodyLeft);
+ * new ColumnDef("total", "Total", px120, allRight);          // numbers: right-aligned in header, body and footer
+ *
+ * @example
+ * // named parameters for everything else
+ * ColumnDef.create({
+ *   property: "status",
+ *   headerLabel: "Status",
+ *   width: px110,
+ *   bodyRenderer: new StatusBadgeRenderer(),
+ *   sortable: TrueFn,
+ *   sortComparator: (a: string, b: string) => STATUS_ORDER.indexOf(a) - STATUS_ORDER.indexOf(b)
+ * });
+ *
+ * @see Training: [Columns with ColumnDef](https://gui.expert/training/column-definitions/),
+ *   [Sorting](https://gui.expert/training/sorting/), [Cell renderers](https://gui.expert/training/cell-renderers/)
+ *
+ * @category Columns
  */
 export declare class ColumnDef implements ColumnDefIf {
     property: string;
@@ -31,26 +54,60 @@ export declare class ColumnDef implements ColumnDefIf {
     visible: boolean;
     constructor(property: string, headerLabel: string, width?: SizeIf, classes?: AreaObjectMapType<string[]>, rendererMap?: AreaObjectMapType<CellRendererIf>, minWidth?: SizeIf, maxWidth?: SizeIf, sortable?: BooleanFunction | undefined, sortComparator?: ValueRowSortComparator | undefined, sortState?: SortState | undefined, sortStatesOrder?: SortState[] | undefined, sortIconVisible?: BooleanFunction | undefined, editable?: BooleanFunction | undefined, getEditRenderer?: GetEditRenderer | undefined, editInputPipe?: editInputPipe | undefined, isVisible?: BooleanFunction);
     static bodyRenderer(bodyRenderer: CellRendererIf): AreaObjectMap<CellRendererIf>;
+    /**
+     * Creates a column definition from named parameters. Everything is optional; defaults: width 100 px,
+     * visible, not editable, sortable only if `sortable` is given.
+     *
+     * `headerRenderer` / `bodyRenderer` / `footerRenderer` and `headerClasses` / `bodyClasses` / `footerClasses`
+     * fill {@link ColumnDefIf.rendererMap} and {@link ColumnDefIf.classes}.
+     *
+     * @example
+     * ColumnDef.create({
+     *   property: "price", headerLabel: "Price", width: px100,
+     *   headerClasses: ["ge-table-text-align-right"], bodyClasses: ["ge-table-text-align-right"],
+     *   sortable: TrueFn
+     * });
+     */
     static create(param: {
+        /** Property of the row object, see {@link ColumnDefIf.property}. */
         property?: string;
+        /** Header label. */
         headerLabel?: string;
+        /** Width, default 100 px. */
         width?: SizeIf;
+        /** Lower limit for % widths. */
         minWidth?: SizeIf;
+        /** Upper limit for % widths. */
         maxWidth?: SizeIf;
+        /** Renderer of the header cell. */
         headerRenderer?: CellRendererIf;
+        /** Renderer of the body cells. */
         bodyRenderer?: CellRendererIf;
+        /** Renderer of the footer cells. */
         footerRenderer?: CellRendererIf;
+        /** CSS classes of the header cell, e.g. `["ge-table-text-align-right"]`. */
         headerClasses?: string[];
+        /** CSS classes of the body cells. */
         bodyClasses?: string[];
+        /** CSS classes of the footer cells. */
         footerClasses?: string[];
+        /** Sortable by double-click on the header, e.g. `TrueFn`. */
         sortable?: BooleanFunction;
+        /** Show the sort icon (default: follows `sortable`). */
         sortIconVisible?: BooleanFunction;
+        /** Own comparison of two cell values. */
         sortComparator?: ValueRowSortComparator;
+        /** Initial sort icon (`"asc"`, `"desc"`); sort the rows with `tableModel.doSort()` to match. */
         sortState?: SortState;
+        /** Order of the sort states on repeated double-clicks. */
         sortStatesOrder?: SortState[];
+        /** Cells can be edited, e.g. `TrueFn`. */
         editable?: BooleanFunction;
+        /** Column is shown (default `TrueFn`). */
         isVisible?: BooleanFunction;
+        /** The editor of this column. */
         getEditRenderer?: GetEditRenderer;
+        /** Converts the editor text before it is stored, e.g. `editInputPipeForNumber`. */
         editInputPipe?: editInputPipe;
     }): ColumnDefIf;
 }