@guiexpert/table 1.1.90 → 1.1.91

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

@@ -1,16 +1,17 @@
-import { AreaIdent } from '../area-ident.type';
-import { ColumnDefIf } from '../column/column-def.if';
-import { AreaModelIf } from './area-model.if';
-import { CellGroupIf } from '../cellgroup/cell-group.if';
-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 { CellGroupExt } from '../cellgroup/cell-group-ext';
-import { MouseTargetData } from '../../event/mouse-target-data';
-import { HeaderGroupOptionsIf } from '../../options/header-group-options.if';
+import { AreaIdent } from '../area-ident.type.js';
+import { ColumnDefIf } from '../column/column-def.if.js';
+import { AreaModelIf } from './area-model.if.js';
+import { CellGroupIf } from '../cellgroup/cell-group.if.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';
+import { CellGroupExt } from '../cellgroup/cell-group-ext.js';
+import { MouseTargetData } from '../../event/mouse-target-data.js';
+import { HeaderGroupOptionsIf } from '../../options/header-group-options.if.js';
 
+/** @category Header groups */
 export declare class AreaModelCellGroups implements AreaModelIf {
     readonly areaIdent: AreaIdent;
     readonly groups: CellGroupIf[];

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

@@ -1,13 +1,15 @@
-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 { 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';
 
 /**
  * An invisible model, which is used internally for hiding a header.
+ *
+ * @category Area models
  */
 export declare class AreaModelHidden implements AreaModelIf {
     areaIdent: AreaIdent;

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

@@ -1,6 +1,6 @@
-import { AreaModelObjectArray } from './area-model-object-array';
-import { ColumnDefIf } from '../column/column-def.if';
-import { AreaIdent } from '../area-ident.type';
+import { AreaModelObjectArray } from './area-model-object-array.js';
+import { ColumnDefIf } from '../column/column-def.if.js';
+import { AreaIdent } from '../area-ident.type.js';
 
 /**
  * Represents an area model defined by an object array with column definitions.
@@ -29,10 +29,10 @@ import { AreaIdent } from '../area-ident.type';
  *   { id: 3, name: 'Bob', age: 40 }
  * ];
  *
- * const columnDefs = [
- *   { property: 'id', headerLabel: 'ID', width: new Size(50, 'px') },
- *   { property: 'name', headerLabel: 'Name', width: new Size(150, 'px') },
- *   { property: 'age', headerLabel: 'Age', width: new Size(100, 'px') }
+ * 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 AreaModelObjectArrayWithColumndefs<any>(
@@ -47,9 +47,9 @@ import { AreaIdent } from '../area-ident.type';
  * function createTableModel() {
  *   const rows = fetchDataFromServer();
  *   const columnDefs = [
- *     { property: 'id', headerLabel: 'ID', width: new Size(50, 'px') },
- *     { property: 'name', headerLabel: 'Name', width: new Size(150, 'px') },
- *     { property: 'age', headerLabel: 'Age', width: new Size(100, 'px') }
+ *     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.buildByTypedRowsParam({
@@ -81,6 +81,8 @@ import { AreaIdent } from '../area-ident.type';
  * @see {@link AreaModelObjectArray} - The parent class that provides the core functionality
  * @see {@link ColumnDefIf} - The interface that defines the structure of column definitions
  * @see {@link CrudTableModelFactory} - A factory class that uses this class for CRUD operations
+ *
+ * @category Area models
  */
 export declare class AreaModelObjectArrayWithColumndefs<T> extends AreaModelObjectArray<T> {
     areaIdent: AreaIdent;
@@ -103,10 +105,10 @@ export declare class AreaModelObjectArrayWithColumndefs<T> extends AreaModelObje
      *   { id: 2, name: 'Jane', age: 25 }
      * ];
      *
-     * const columnDefs = [
-     *   { property: 'id', headerLabel: 'ID', width: new Size(50, 'px') },
-     *   { property: 'name', headerLabel: 'Name', width: new Size(150, 'px') },
-     *   { property: 'age', headerLabel: 'Age', width: new Size(100, 'px') }
+     * 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 AreaModelObjectArrayWithColumndefs(

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(
@@ -432,7 +435,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 +454,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 +512,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 +545,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,14 +47,70 @@ 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;
     getValueAt(rowIndex: number, columnIndex: number): any;
@@ -42,14 +125,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;
 }