@guiexpert/table 1.1.90 → 1.1.92

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

@@ -1,10 +1,10 @@
-import { AbstractAreaModel } from './abstract-area-model';
-import { ColumnDefIf } from '../column/column-def.if';
-import { AreaIdent } from '../area-ident.type';
-import { FilterFunction } from '../../common/filter-function';
-import { SorterService } from '../../../service/sorter.service';
-import { SortItem } from '../../common/sort-item';
-import { ObjectArrayHolderIf } from './object-array-holder.if';
+import { AbstractAreaModel } from './abstract-area-model.js';
+import { ColumnDefIf } from '../column/column-def.if.js';
+import { AreaIdent } from '../area-ident.type.js';
+import { FilterFunction } from '../../common/filter-function.js';
+import { SorterService } from '../../../service/sorter.service.js';
+import { SortItem } from '../../common/sort-item.js';
+import { ObjectArrayHolderIf } from './object-array-holder.if.js';
 
 /**
  * @class AreaModelObjectArray
@@ -35,10 +35,10 @@ import { ObjectArrayHolderIf } from './object-array-holder.if';
  *   { id: 3, name: 'Bob', age: 40 }
  * ];
  *
- * const columnDefs = [
- *   { property: 'id', headerLabel: 'ID', width: 50 },
- *   { property: 'name', headerLabel: 'Name', width: 150 },
- *   { property: 'age', headerLabel: 'Age', width: 100 }
+ * const columnDefs: ColumnDefIf[] = [
+ *   new ColumnDef('id', 'ID', new Size(50, 'px')),
+ *   new ColumnDef('name', 'Name', new Size(150, 'px')),
+ *   new ColumnDef('age', 'Age', new Size(100, 'px'))
  * ];
  *
  * const bodyAreaModel = new AreaModelObjectArray<any>(
@@ -50,7 +50,7 @@ import { ObjectArrayHolderIf } from './object-array-holder.if';
  *
  * @example
  * // Using with TableFactory to create a complete table model
- * import { TableFactory } from '../../../factory/table-factory';
+ * import { TableFactory } from '../../../factory/table-factory.js';
  *
  * const rows = [
  *   { id: 1, name: 'John', age: 30 },
@@ -58,10 +58,10 @@ import { ObjectArrayHolderIf } from './object-array-holder.if';
  *   { id: 3, name: 'Bob', age: 40 }
  * ];
  *
- * const columnDefs = [
- *   { property: 'id', headerLabel: 'ID', width: 50 },
- *   { property: 'name', headerLabel: 'Name', width: 150 },
- *   { property: 'age', headerLabel: 'Age', width: 100 }
+ * const columnDefs: ColumnDefIf[] = [
+ *   new ColumnDef('id', 'ID', new Size(50, 'px')),
+ *   new ColumnDef('name', 'Name', new Size(150, 'px')),
+ *   new ColumnDef('age', 'Age', new Size(100, 'px'))
  * ];
  *
  * const tableModel = TableFactory.createByObjectArray(
@@ -82,11 +82,11 @@ import { ObjectArrayHolderIf } from './object-array-holder.if';
  *   { id: 2, person: { name: 'Jane', contact: { email: 'jane@example.com', phone: '098-765-4321' } } }
  * ];
  *
- * const columnDefs = [
- *   { property: 'id', headerLabel: 'ID', width: 50 },
- *   { property: 'person.name', headerLabel: 'Name', width: 150 },
- *   { property: 'person.contact.email', headerLabel: 'Email', width: 200 },
- *   { property: 'person.contact.phone', headerLabel: 'Phone', width: 150 }
+ * const columnDefs: ColumnDefIf[] = [
+ *   new ColumnDef('id', 'ID', new Size(50, 'px')),
+ *   new ColumnDef('person.name', 'Name', new Size(150, 'px')),
+ *   new ColumnDef('person.contact.email', 'Email', new Size(200, 'px')),
+ *   new ColumnDef('person.contact.phone', 'Phone', new Size(150, 'px'))
  * ];
  *
  * const bodyAreaModel = new AreaModelObjectArray<any>(
@@ -139,6 +139,8 @@ import { ObjectArrayHolderIf } from './object-array-holder.if';
  * @see {@link AbstractAreaModel} - The parent class that provides the base implementation
  * @see {@link ObjectArrayHolderIf} - The interface that defines methods for accessing rows
  * @see {@link AreaModelObjectArrayWithColumndefs} - A subclass that changes the constructor parameter order
+ *
+ * @category Area models
  */
 export declare class AreaModelObjectArray<T> extends AbstractAreaModel<T> implements ObjectArrayHolderIf<T> {
     areaIdent: AreaIdent;
@@ -166,6 +168,7 @@ export declare class AreaModelObjectArray<T> extends AbstractAreaModel<T> implem
      * Service for handling sorting operations.
      * @protected
      * @type {SorterService}
+     * @internal
      */
     protected sorterService: SorterService;
     /**
@@ -184,10 +187,10 @@ export declare class AreaModelObjectArray<T> extends AbstractAreaModel<T> implem
      *   { id: 2, name: 'Jane', age: 25 }
      * ];
      *
-     * const columnDefs = [
-     *   { property: 'id', headerLabel: 'ID', width: 50 },
-     *   { property: 'name', headerLabel: 'Name', width: 150 },
-     *   { property: 'age', headerLabel: 'Age', width: 100 }
+     * const columnDefs: ColumnDefIf[] = [
+     *   new ColumnDef('id', 'ID', new Size(50, 'px')),
+     *   new ColumnDef('name', 'Name', new Size(150, 'px')),
+     *   new ColumnDef('age', 'Age', new Size(100, 'px'))
      * ];
      *
      * const bodyAreaModel = new AreaModelObjectArray(
@@ -264,6 +267,19 @@ export declare class AreaModelObjectArray<T> extends AbstractAreaModel<T> implem
      * console.log(`The table has ${rowCount} rows`);
      */
     getRowCount(): number;
+    /**
+     * The number of all rows, without the external filter (the filter only shrinks {@link getRowCount}).
+     *
+     * @returns {number} `getAllRows().length`
+     *
+     * @example
+     * if (bodyAreaModel.getRowCount() === 0 && bodyAreaModel.getUnfilteredRowCount() > 0) {
+     *   console.log("The filter hides all rows");
+     * }
+     *
+     * @since 1.1.92
+     */
+    getUnfilteredRowCount(): number;
     /**
      * Gets the value at the specified row and column indices.
      * This method handles tree rows and nested properties.
@@ -432,7 +448,8 @@ export declare class AreaModelObjectArray<T> extends AbstractAreaModel<T> implem
     externalFilterChanged(predictFn: FilterFunction<any>): void;
     /**
      * Sorts the filtered rows based on the provided sort items.
-     * This method supports sorting by multiple columns with different sort directions.
+     * This method supports sorting by multiple columns with different sort directions: the first item is the primary
+     * key, the following ones break ties.
      *
      * @param {SortItem[]} sortItems - An array of sort items, each containing a column index and sort state
      * @returns {boolean} Always returns true to indicate sorting was performed
@@ -450,7 +467,7 @@ export declare class AreaModelObjectArray<T> extends AbstractAreaModel<T> implem
      *
      * @example
      * // Clear sorting
-     * bodyAreaModel.doSort([{ columnIndex: 0, sortState: 'none' }]);
+     * bodyAreaModel.doSort([new SortItem(0, '')]);
      */
     doSort(sortItems: SortItem[]): boolean;
     /**
@@ -508,7 +525,7 @@ export declare class AreaModelObjectArray<T> extends AbstractAreaModel<T> implem
      *
      * @example
      * // Move the last column to the first position
-     * const lastIndex = bodyAreaModel.columnDefs.length - 1;
+     * const lastIndex = tableModel.getColumnCount() - 1;
      * bodyAreaModel.changeColumnOrder(lastIndex, 0);
      */
     changeColumnOrder(sourceColumnIndex: number, targetColumnIndex: number): void;
@@ -541,11 +558,11 @@ export declare class AreaModelObjectArray<T> extends AbstractAreaModel<T> implem
      * @returns {(a: T, b: T) => number} A comparator function that compares two rows
      *
      * @example
-     * // Create a comparator for sorting by name in ascending order
-     * const comparator = bodyAreaModel.genericFlatTableSortComparator('name', 1);
+     * // inside a subclass: a comparator for sorting by name in ascending order
+     * const comparator = this.genericFlatTableSortComparator('name', 1);
      *
      * // Sort the rows using the comparator
-     * const sortedRows = [...bodyAreaModel.getFilteredRows()].sort(comparator);
+     * const sortedRows = [...this.getFilteredRows()].sort(comparator);
      */
     protected genericFlatTableSortComparator(property: string, f: number): (a: T, b: T) => number;
     /**

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

@@ -1,17 +1,44 @@
-import { TreeRow } from '../../common/tree-row';
-import { AbstractAreaModel } from './abstract-area-model';
-import { AreaIdent } from '../area-ident.type';
-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 { TreeRowIf } from '../../common/tree-row-if';
+import { TreeRow } from '../../common/tree-row.js';
+import { AbstractAreaModel } from './abstract-area-model.js';
+import { AreaIdent } from '../area-ident.type.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';
+import { TreeRowIf } from '../../common/tree-row-if.js';
 
 /**
  * Represents a  tree-based table model.
  * Extends the AbstractAreaModel class.
  *
+ * The displayed rows always come from one pipeline: all tree rows (in their current, possibly sorted order)
+ * → rows whose parents are all expanded → active filter. Everything that changes one of these inputs
+ * ({@link recalcVisibleTreeRows} after an expand/collapse, {@link externalFilterChanged}, {@link doSort},
+ * {@link toggleExpandCollapseAll}) runs the whole pipeline, so a filter survives expanding, collapsing and sorting.
+ *
+ * Filter semantics: the filter function receives the {@link TreeRowIf tree row} – your object is `row.data`.
+ * It is called for **every** row, also for rows below collapsed parents. A row is shown if it or one of its
+ * descendants matches (`row.keep`) and all its parents are expanded. So a match below a collapsed node keeps
+ * that node visible (still collapsed); expanding it reveals the path to the match. The children of a matching
+ * row are not kept automatically.
+ *
  * @template S - The type of the row data.
+ *
+ * @example
+ * // a tree table with a live search over the labels
+ * const filter = { text: "" };
+ * const tableOptions: TableOptionsIf = {
+ *   ...new TableOptions(),
+ *   externalFilterFunction: (row: TreeRowIf<OrderNode>) => row.data.label.toLowerCase().includes(filter.text)
+ * };
+ * const rows = TreeFactory.buildTreeRows<OrderNode>(nodes, { expanded: false });
+ * const tableModel = TableFactory.createTableModel({ rows, columnDefs, tableOptions });
+ * searchInput.addEventListener("input", () => {
+ *   filter.text = searchInput.value.toLowerCase();
+ *   tableApi.externalFilterChanged(); // parents of matches stay visible; expanding and sorting keep the filter
+ * });
+ *
+ * @category Tree & checkboxes
  */
 export declare class AreaModelTree<S> extends AbstractAreaModel<TreeRow<S>> {
     areaIdent: AreaIdent;
@@ -20,16 +47,81 @@ export declare class AreaModelTree<S> extends AbstractAreaModel<TreeRow<S>> {
     protected columnDefs: ColumnDefIf[];
     type: string;
     protected readonly properties: string[];
+    /** @internal */
     protected sorterService: SorterService;
     private readonly service;
+    /** the displayed rows: all parents expanded and accepted by the filter */
     private filteredFlattenRows;
+    /** the visible rows (all parents expanded), not filtered */
     private flattenRows;
     private lastPredictFn?;
+    /** `row.keep` was set for the current filter (it depends on the filter and the data, not on expand/collapse). */
+    private keepMarked;
     constructor(areaIdent: AreaIdent, rows: TreeRowIf<S>[], defaultRowHeight: number, columnDefs?: ColumnDefIf[]);
     changeColumnOrder(sourceColumnIndex: number, targetColumnIndex: number): void;
-    recalcVisibleTreeRows(): void;
+    /**
+     * Rebuilds the displayed rows after the `expanded` state of rows has changed and applies the active filter
+     * (see {@link externalFilterChanged}) again. The table calls it on every expand/collapse click. Call it
+     * yourself after changing `row.expanded` from code, then repaint with `tableApi.repaintHard()`
+     * (the row count changes).
+     *
+     * @example
+     * // expand all first-level rows from code
+     * const treeModel = tableModel.getBodyModel() as AreaModelTree<OrderNode>;
+     * for (const row of treeModel.rows) row.expanded = true;
+     * treeModel.recalcVisibleTreeRows();
+     * tableApi.repaintHard();
+     *
+     * @param {boolean} [refilter=true] - run the filter function again (needed after the rows changed). `false` after a
+     *        pure expand/collapse: whether a row matches does not depend on it (the table does this on every click –
+     *        before, the filter ran over all nodes for each click).
+     */
+    recalcVisibleTreeRows(refilter?: boolean): void;
+    /**
+     * The displayed top-level rows: all of {@link rows}, with an active filter only the matching ones (or with a
+     * matching descendant).
+     *
+     * @returns {TreeRowIf<S>[]} the top-level rows that are shown
+     */
+    getDisplayedRootRows(): TreeRowIf<S>[];
+    /**
+     * True if the row has children that are shown when it is expanded – with an active filter only children that
+     * match (or have a matching descendant) count. The arrow of a row without such children is hidden.
+     *
+     * @param {TreeRowIf<S>} row - a tree row of this model
+     * @returns {boolean} true if the row has displayed children
+     */
+    hasDisplayedChildren(row: TreeRowIf<S>): boolean;
+    /**
+     * The displayed children of a row (in display order): all children, with an active filter only those that match
+     * (or have a matching descendant). They are on screen if the row is expanded.
+     * Used for the screen reader attributes `aria-setsize` / `aria-posinset` of tree rows.
+     *
+     * @example
+     * const treeModel = tableModel.getBodyModel() as AreaModelTree<OrderNode>;
+     * const shown = treeModel.getDisplayedChildren(treeModel.rows[0]).length;
+     *
+     * @param {TreeRowIf<S>} row - a tree row of this model
+     * @returns {TreeRowIf<S>[]} the displayed children (empty for a leaf)
+     * @since 1.1.91
+     */
+    getDisplayedChildren(row: TreeRowIf<S>): TreeRowIf<S>[];
+    /**
+     * The displayed rows: all parents expanded and accepted by the active filter, in display order.
+     *
+     * @returns {TreeRowIf<S>[]} the displayed tree rows (do not modify the array)
+     */
     getFilteredFlattenRows(): TreeRowIf<S>[];
     getRowCount(): number;
+    /**
+     * The number of rows the tree shows without the external filter: all nodes whose parents are expanded
+     * (collapsed children do not count). `0` only for a tree without rows.
+     *
+     * @returns {number} displayed rows before filtering
+     *
+     * @since 1.1.92
+     */
+    getUnfilteredRowCount(): number;
     getValueAt(rowIndex: number, columnIndex: number): any;
     getRowHeight(_rowIndex: number): number;
     /**
@@ -42,14 +134,73 @@ export declare class AreaModelTree<S> extends AbstractAreaModel<TreeRow<S>> {
     getCustomClassesAt(rowIndex: number, _columnIndex: number): string[];
     getRowByIndex(idx: number): TreeRowIf<S> | undefined;
     getValueByT(t: S, property: string): any;
+    /**
+     * Filters the tree; the function is remembered and applied again on every expand/collapse
+     * ({@link recalcVisibleTreeRows}), {@link toggleExpandCollapseAll} and {@link doSort}.
+     *
+     * The function is called once for **every** tree row in depth-first order – also for rows below collapsed
+     * parents – with the {@link TreeRowIf tree row} (not your object: use `row.data`), the index of the row in
+     * this depth-first list and the list itself. Shown are the rows that match or have a matching descendant
+     * (`row.keep = true`) and whose parents are all expanded. A match below a collapsed node therefore keeps the
+     * collapsed node visible. Usually called by `tableApi.externalFilterChanged()` with
+     * `tableOptions.externalFilterFunction`.
+     *
+     * @param {FilterFunction<S>} predictFn - returns a truthy value for the rows to show
+     *
+     * @example
+     * const treeModel = tableModel.getBodyModel() as AreaModelTree<OrderNode>;
+     * treeModel.externalFilterChanged((row: TreeRowIf<OrderNode>) => row.data.total > 1000);
+     * tableApi.repaintHard();
+     *
+     * // remove the filter
+     * treeModel.externalFilterChanged(() => true);
+     */
     externalFilterChanged<S>(predictFn: FilterFunction<S>): void;
+    /**
+     * Sorts the rows of every level (children stay below their parent) and keeps the active filter. The first sort
+     * item is the primary key, the following ones break ties. The `rows` array and the children arrays are reordered
+     * in place, so the order survives expanding, collapsing and filtering. Sort state `""` keeps the current order.
+     *
+     * @param {SortItem[]} sortItems - primary key first; an empty list does nothing
+     * @returns {boolean} `true` if the rows were sorted, `false` for an empty list
+     *
+     * @example
+     * tableModel.getBodyModel().doSort([new SortItem(1, "desc")]);
+     * tableApi.repaint();
+     */
     doSort(sortItems: SortItem[]): boolean;
+    /**
+     * Sorts the rows of every level with your own function (children stay below their parent) and keeps the active
+     * filter. Used by `tableApi.sort(fn)` – before, sorting a tree with a function did nothing.
+     *
+     * @param {(a: TreeRowIf<S>, b: TreeRowIf<S>) => number} compareFn - compares two sibling rows – like the filter
+     *        function it gets the tree rows: your objects are `a.data` / `b.data`
+     *
+     * @example
+     * tableApi.sort((a, b) => a.data.total - b.data.total);   // sorts the siblings of every level by total
+     */
+    sort(compareFn: (a: TreeRowIf<S>, b: TreeRowIf<S>) => number): void;
+    /**
+     * Expands or collapses every row on every level and applies the active filter again.
+     *
+     * @param {boolean} expanded - `true` expands, `false` collapses all rows
+     */
     toggleExpandCollapseAll(expanded: boolean): void;
     setAllParentsOk(item: TreeRowIf<any>): boolean;
     setValue(rowIndex: number, columnIndex: number, value: any): boolean;
     protected genericTreeTableSortComparator(property: string, f: number): (a: TreeRowIf<S>, b: TreeRowIf<S>) => number;
     private expandAllRecursive;
-    private doFiltering;
+    /**
+     * The one pipeline behind the displayed rows: all rows (current order) → visible (all parents expanded)
+     * → active filter.
+     */
+    private refreshDisplayedRows;
+    /**
+     * Sets `keep` on every row (also below collapsed parents): true for matching rows and all their ancestors.
+     */
+    private markKeptRows;
+    /** all rows depth-first, independent of the expanded state */
+    private collectAllRows;
     private getPropertyValue;
-    private treeSort;
+    private treeSortWith;
 }

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

@@ -1,96 +1,59 @@
-import { AreaModelIf } from './area-model.if';
-import { AreaIdent } from '../area-ident.type';
-import { CheckboxModelIf } from '../../../checkbox/checkbox-model.if';
-import { SortItem } from '../../common/sort-item';
-import { FilterFunction } from '../../common/filter-function';
-import { CellRendererIf } from '../../../renderer/cell-render.if';
-import { CheckedType } from '../../common/checked-type';
+import { AreaModelIf } from './area-model.if.js';
+import { AreaIdent } from '../area-ident.type.js';
+import { CheckboxModelIf } from '../../../checkbox/checkbox-model.if.js';
+import { SortItem } from '../../common/sort-item.js';
+import { FilterFunction } from '../../common/filter-function.js';
+import { CellRendererIf } from '../../../renderer/cell-render.if.js';
+import { CheckedType } from '../../common/checked-type.js';
 
 /**
- * @class AreaModel
- * @implements {AreaModelIf}
- * @description
- * The AreaModel class is a base implementation of the AreaModelIf interface.
- * It represents a model for a specific area of a table (header, body, or footer)
- * and provides methods for accessing and manipulating data within that area.
+ * Base class for area models of your own – every method of {@link AreaModelIf} has a sensible default,
+ * override only what you need (at least {@link getRowCount}, {@link getValueAt} and {@link getRowHeight}).
  *
- * In the GuiExpert Table library, a table is divided into three main areas:
- * - Header: Contains column titles and optional filter/sort controls
- * - Body: Contains the main data of the table
- * - Footer: Contains summary information or additional controls
- *
- * Each of these areas can be further divided into three sections:
- * - West: Fixed columns on the left side
- * - Center: Scrollable columns in the middle
- * - East: Fixed columns on the right side
- *
- * <pre>
- *  +----------------+-------------------+--------------+
- *  |  header/west   |  header/center    | header/east  |
- *  +----------------+-------------------+--------------+
- *  |  body/west     |  body/center      | body/east    |
- *  +----------------+-------------------+--------------+
- *  |  footer/west   |  footer/center    | footer/east  |
- *  +----------------+-------------------+--------------+
- * </pre>
- *
- * This base AreaModel class provides default implementations for all methods
- * required by the AreaModelIf interface. Most methods return default values
- * or do nothing, making this class suitable as a starting point for creating
- * more specialized area models.
+ * A table consists of three area models – header, body and footer ({@link AreaIdent}) – and asks them only for
+ * the cells that are visible. That makes models possible that compute values on demand (millions of rows,
+ * server data) or summarise other models (footer totals).
  *
  * @example
- * // Creating a basic area model for the header
- * const headerModel = new AreaModel();
- * headerModel.areaIdent = "header";
- *
- * @example
- * // Extending AreaModel to create a custom implementation
- * class CustomAreaModel extends AreaModel {
- *   private data: any[][];
- *
- *   constructor(data: any[][]) {
+ * // a body with two million rows – no array behind it
+ * class TwoMillionRows extends AreaModel {
+ *   constructor() {
  *     super();
- *     this.data = data;
+ *     this.areaIdent = "body";
  *   }
- *
- *   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 getRowCount(): number { return 2_000_000; }
+ *   override getRowHeight(_rowIndex: number): number { return 34; }
+ *   override getConstantRowHeight(): number { return 34; }   // all rows equally high → O(1) scrolling
+ *   override getValueAt(row: number, col: number): any {
+ *     return col === 0 ? row + 1 : `cell ${row}/${col}`;
  *   }
- *
- *   // Override other methods as needed...
  * }
+ * const tableModel = TableFactory.createTableModel({
+ *   bodyAreaModel: new TwoMillionRows(),
+ *   columnDefs: [new ColumnDef("id", "ID", px100, allRight), new ColumnDef("text", "Text", px200)]
+ * });
  *
  * @example
- * // Using AreaModel with a TableModel
- * import { TableFactory, TableModelIf } from "@guiexpert/table";
- *
- * // Create a table model with custom area models
- * const tableModel: TableModelIf = TableFactory.createTableModel();
- *
- * // Set custom area models
- * const headerModel = new CustomAreaModel([["ID", "Name", "Age"]]);
- * headerModel.areaIdent = "header";
- * tableModel.setAreaModel("header", headerModel);
+ * // a footer that sums the rows the body currently shows (after filter and sorting)
+ * class TotalsFooter extends AreaModel {
+ *   constructor(private readonly getBody: () => AreaModelObjectArray<Order>) {
+ *     super();
+ *     this.areaIdent = "footer";
+ *   }
+ *   override getRowCount(): number { return 1; }
+ *   override getRowHeight(_rowIndex: number): number { return 34; }
+ *   override getValueAt(_row: number, col: number): any {
+ *     const rows = this.getBody().getFilteredRows();
+ *     return col === 0 ? `${rows.length} orders` : col === 5 ? rows.reduce((s, o) => s + o.total, 0) : "";
+ *   }
+ * }
  *
- * const bodyModel = new CustomAreaModel([
- *   [1, "John", 30],
- *   [2, "Jane", 25],
- *   [3, "Bob", 40]
- * ]);
- * bodyModel.areaIdent = "body";
- * tableModel.setAreaModel("body", bodyModel);
+ * @see {@link AreaModelObjectArray} (objects), {@link AreaModelArrayOfArrays} (rows of values), {@link AreaModelTree} (trees)
+ * @see Training: [The TableModel: three times three areas](https://gui.expert/training/table-model-areas/),
+ *   [Own AreaModel: two million rows](https://gui.expert/training/custom-area-model/),
+ *   [Footer totals](https://gui.expert/training/footer-totals/)
  *
- * @see {@link AreaModelIf} - The interface that this class implements
- * @see {@link AbstractAreaModel} - An abstract implementation with common functionality
- * @see {@link AreaModelObjectArray} - An implementation for object array data
+ * @category Area models
  */
 export declare class AreaModel implements AreaModelIf {
     /**
@@ -141,31 +104,29 @@ export declare class AreaModel implements AreaModelIf {
     changeColumnOrder(_sourceColumnIndex: number, _targetColumnIndex: number): void;
     /**
      * Sorts the rows in this area based on the provided sort items.
-     * This method is called when the user clicks on a sortable column header.
+     * Called when the user double-clicks a sortable column header (and by {@link TableApi.sortByColumn}).
      * The base implementation returns false (no sorting performed) and should be
-     * overridden by subclasses that support sorting.
+     * overridden by subclasses that hold their rows themselves.
      *
      * @param {SortItem[]} _sortItems - An array of sort items, each containing a column index and sort direction
      * @returns {boolean} True if sorting was performed, false otherwise
      *
      * @example
-     * // Override in a subclass to implement sorting
-     * doSort(sortItems: SortItem[]): boolean {
-     *   if (!sortItems.length) return false;
+     * class SortableRows extends AreaModel {
+     *   constructor(private readonly rows: any[][]) {
+     *     super();
+     *     this.areaIdent = "body";
+     *   }
+     *   override getRowCount(): number { return this.rows.length; }
+     *   override getValueAt(row: number, col: number): any { return this.rows[row][col]; }
      *
-     *   // Apply sorting to the rows
-     *   this.rows.sort((a, b) => {
+     *   override doSort(sortItems: SortItem[]): boolean {
+     *     if (!sortItems.length) return false;
      *     const { columnIndex, sortState } = sortItems[0];
-     *     const valueA = this.getValueAt(this.rows.indexOf(a), columnIndex);
-     *     const valueB = this.getValueAt(this.rows.indexOf(b), columnIndex);
-     *
-     *     const direction = sortState === 'asc' ? 1 : -1;
-     *     if (valueA < valueB) return -1 * direction;
-     *     if (valueA > valueB) return 1 * direction;
-     *     return 0;
-     *   });
-     *
-     *   return true;
+     *     const direction = sortState === "asc" ? 1 : -1;
+     *     this.rows.sort((a, b) => (a[columnIndex] < b[columnIndex] ? -1 : a[columnIndex] > b[columnIndex] ? 1 : 0) * direction);
+     *     return true;
+     *   }
      * }
      */
     doSort(_sortItems: SortItem[]): boolean;
@@ -641,19 +602,20 @@ export declare class AreaModel implements AreaModelIf {
     isRowChecked(_rowIndex: number): CheckedType | undefined;
     /**
      * Determines whether the cell at the specified row and column indices is selectable.
-     * If true, the user can select the cell.
-     * The base implementation returns false (not selectable) and should be overridden by
-     * subclasses that support cell selection.
+     * The table draws the selection (of the {@link SelectionModel}) only on selectable body cells.
+     *
+     * Default: `true` – all cells are selectable, like in all built-in area models
+     * (up to 1.1.90 the default of `AreaModel` was `false`: a selection on an own model was not drawn).
+     * Override it to exclude cells, e.g. a column of row numbers.
      *
      * @param {number} _rowIndex - The index of the row
      * @param {number} _columnIndex - The index of the column
      * @returns {boolean} True if the cell is selectable, false otherwise
      *
      * @example
-     * // Override in a subclass to implement cell selectability
-     * isSelectable(rowIndex: number, columnIndex: number): boolean {
-     *   // All cells in the body are selectable
-     *   return this.areaIdent === 'body';
+     * // Override in a subclass: the first column (row numbers) never shows a selection
+     * override isSelectable(_rowIndex: number, columnIndex: number): boolean {
+     *   return columnIndex > 0;
      * }
      */
     isSelectable(_rowIndex: number, _columnIndex: number): boolean;