@guiexpert/table 1.1.91 → 1.1.93

package/lib/table/aria/live-announcer.d.ts

@@ -31,6 +31,7 @@ export declare class LiveAnnouncer {
     static defaultDelayInMs: number;
     private element?;
     private timeout?;
+    private pendingText?;
     constructor(document: Document | undefined, id: string, domService: DomServiceIf);
     /**
      * Speaks a message (replaces a message that is still waiting).
@@ -39,6 +40,14 @@ export declare class LiveAnnouncer {
      * @param {number} [delayInMs=LiveAnnouncer.defaultDelayInMs] - wait this long before the text is written
      */
     announce(text: string, delayInMs?: number): void;
+    /**
+     * Drops a message that is still waiting (not spoken yet) – only if it is `text` (or any message without `text`).
+     * Used when the reason for the message is gone, e.g. "Loading…" after the data arrived.
+     *
+     * @param {string} [text] - only this message is dropped
+     * @since 1.1.92
+     */
+    cancel(text?: string): void;
     /**
      * The live region element (created on the first call).
      *

package/lib/table/crud/crud-table-model-factory.d.ts

@@ -56,6 +56,7 @@ export declare class CrudTableModelFactory implements ActionEventListenerIf {
      *   list is loaded again (`fetchList`);
      * - `DELETE`: `deleteItem(id)` → the row is removed.
      *
+     * While a request runs, the table shows its loading overlay ({@link TableApi.showLoadingOverlay}, since 1.1.92).
      * A failed request is logged with `console.error`; the table stays unchanged.
      */
     onActionEvent(actionEvent: ActionEventIf): void;
@@ -67,6 +68,13 @@ export declare class CrudTableModelFactory implements ActionEventListenerIf {
     private addRow;
     /** Loads the list again (`fetchList`) – after a create whose response does not contain the new item. */
     private reloadRows;
+    /**
+     * Shows the loading overlay of the table while `request` runs (also when it fails). Before the table exists
+     * (first `fetchList` in {@link createTableModel}) there is nothing to show it on.
+     */
+    private whileLoading;
+    /** Requests on the way ({@link whileLoading}). */
+    private pendingRequests;
     private getIdKey;
     /** The action column carries the id as text (data-id) – compare as strings. */
     private hasId;

package/lib/table/data/common/event/ge-state-change-event.d.ts

@@ -0,0 +1,30 @@
+import { TableStateIf, TableStatePart } from '../../../state/table-state.if.js';
+
+/**
+ * The state of a table changed ({@link EventListenerIf.onStateChanged}): a column was resized, moved, hidden,
+ * the table was sorted, scrolled, a node expanded, a row checked or selected … Reported once after the changes
+ * settled ({@link TableOptionsIf.stateChangedDebounceDelay}, default 300 ms) and only if a part really changed;
+ * not while the table is built.
+ *
+ * @example
+ * const listener = new EventAdapter();
+ * listener.onStateChanged = (evt: GeStateChangeEvent) => {
+ *   if (!evt.changedParts.includes("scroll")) {               // e.g. ignore pure scrolling
+ *     void fetch("/api/prefs/orders", { method: "PUT", body: JSON.stringify(evt.state) });
+ *   }
+ * };
+ *
+ * @category State
+ * @since 1.1.92
+ */
+export declare class GeStateChangeEvent {
+    /** The whole state of the table now (all parts). */
+    readonly state: TableStateIf;
+    /** The parts that changed since the last event. */
+    readonly changedParts: TableStatePart[];
+    constructor(
+    /** The whole state of the table now (all parts). */
+    state: TableStateIf, 
+    /** The parts that changed since the last event. */
+    changedParts: TableStatePart[]);
+}

package/lib/table/data/options/auto-restore-options.d.ts

@@ -2,7 +2,7 @@ import { AutoRestoreOptionsIf } from './auto-restore-options.if.js';
 
 /**
  * Defaults for {@link TableOptionsIf.autoRestoreOptions}: everything off. Spread it and switch on what the table
- * should remember in `localStorage` (one key per table).
+ * should remember in `localStorage` (one key per table) – see {@link AutoRestoreOptionsIf} for all flags.
  *
  * @example
  * const tableOptions: TableOptionsIf = {
@@ -11,7 +11,8 @@ import { AutoRestoreOptionsIf } from './auto-restore-options.if.js';
  *     ...new AutoRestoreOptions<Order>(),
  *     getStorageKeyFn: () => "orders-table",          // unique per table
  *     autoRestoreSortingState: true,
- *     autoRestoreScrollPosition: true
+ *     autoRestoreScrollPosition: true,
+ *     autoRestoreColumnLayout: true                     // widths, order, visibility (since 1.1.92)
  *   }
  * };
  *
@@ -37,7 +38,18 @@ export declare class AutoRestoreOptions<T> implements AutoRestoreOptionsIf<T> {
     autoRestoreScrollPosition: boolean;
     autoRestoreCheckedState: boolean;
     autoRestoreSelectedState: boolean;
+    /** @since 1.1.92 */
+    autoRestoreColumnLayout: boolean;
+    /** @since 1.1.92 */
+    autoRestoreHeaderGroupState: boolean;
+    /** @since 1.1.92 */
+    autoRestoreCustomState: boolean;
     getStorageKeyFn: undefined;
+    /** @deprecated since 1.1.92 – never used by the table. */
     isSame: (r1: T, r2: T, options: AutoRestoreOptionsIf<T>) => boolean;
+    /**
+     * Default: the property `id`, then `uuid`, then the JSON of the row. The table itself uses only `id` / `uuid` of
+     * this default (since 1.1.92): rows without them are not stored – the JSON would write whole rows into the storage.
+     */
     getRowId: (row: T) => string | number;
 }

package/lib/table/data/options/auto-restore-options.if.d.ts

@@ -1,81 +1,123 @@
+import { StateStorageIf } from '../../state/state-storage.if.js';
+
 /**
- * `IsSameFn` is a type alias for a function used within the `AutoRestoreOptionsIf` interface. The function is designed to compare
- * two instances of a generic type `T`, in conjunction with supplied options of type `AutoRestoreOptionsIf<T>`.
+ * `IsSameFn` compares two rows with the help of {@link AutoRestoreOptionsIf.getRowId}.
  *
- * This function is used for determining if two instances of `T` are considered the same when restoring the state of an application.
- * This helps in preserving specific states of the application, like sorting or selected state, across different stages or conditions
- * based on the developer's implementation. By default, this function uses strict equality check (`===`) if not provided.
- *
- * @typedef
- * @typeparam T - The type of the objects that the function is comparing.
- *
- * @param {T} r1 - The first object instance of type `T`.
- * @param {T} r2 - The second object instance of type `T`.
- * @param {AutoRestoreOptionsIf<T>} optionsIf - The options that dictate the behavior of auto-restoring.
- *
- * @returns {boolean} - Returns `true` if the two instances are considered the same, `false` otherwise.
+ * @deprecated since 1.1.92 – never used by the table; rows are compared by {@link AutoRestoreOptionsIf.getRowId}.
  *
+ * @typeparam T - The type of the rows.
  * @category Options
  */
 export type IsSameFn<T> = (r1: T, r2: T, optionsIf: AutoRestoreOptionsIf<T>) => boolean;
 /**
- * GetRowIdFn is a type alias for a function that accepts an instance of type T and returns a unique identifier
- * (either a string or a number) for that instance. It is used for restoring state in conjunction with the
- * AutoRestoreOptionsIf interface.
- * @typedef
- * @typeparam T - The type of the object that the function is going to use.
+ * Returns a unique, stable id for a row – used to remember expanded tree nodes, checked and selected rows and the
+ * first visible row ({@link AutoRestoreOptionsIf}, {@link TableStateIf}).
+ *
+ * Tree tables get the object of the node (`treeRow.data`). Models without row objects (e.g. an own `AreaModel`
+ * that computes its values) get `undefined` and the displayed row index – declare the second parameter to support
+ * them: `(_row, rowIndex) => rowIndex`.
  *
+ * @example
+ * const getRowId: GetRowIdFn<Order> = (order: Order) => order.id;
+ *
+ * @typeparam T - The type of the rows.
  * @category Options
  */
-export type GetRowIdFn<T> = ((row: T) => string | number);
+export type GetRowIdFn<T> = ((row: T, rowIndex?: number) => string | number);
 /**
- * GetStorageKeyFn is a type alias for a function that returns a unique key (as a string) for storage.
- * It is used for restoring state in conjunction with the AutoRestoreOptionsIf interface.
- * @typedef
+ * Returns the storage key of a table – one key per table, e.g. `() => "orders"`. The state is stored under
+ * `<key>tableState`.
  *
  * @category Options
  */
 export type GetStorageKeyFn = (() => string);
 /**
- * The AutoRestoreOptionsIf interface is utilized to encapsulate options
- * for managing auto-restoring settings across different states of the application.
- * This interface is generic and can be used with any type.
- *
- * @interface
- * @typeparam T - Any type that this interface is going to use.
- * @property {boolean} autoRestoreSortingState - If true, the sorting state of
- * T elements will be preserved after changes in the application state.
- *
- * @property {boolean=} autoRestoreCollapsedExpandedState - Optional. If true,
- * the expanded/collapsed state of T elements will be preserved after changes in the application state.
- *
- * @property {boolean=} autoRestoreScrollPosition - Optional. If true, the scroll position
- * in the list of T elements will be preserved after changes in the application state.
- *
- * @property {boolean=} autoRestoreCheckedState - Optional. If true, the checked state of
- * T elements will be preserved after changes in the application state.
- *
- * @property {boolean=} autoRestoreSelectedState - Optional. If true, the selected state of
- * T elements will be preserved after changes in the application state.
- *
- * @property {(row: T) => string | number} getRowId - Function for generating a unique identifier
- * for an instance of T. If not provided, each instance of T will create a new entry every time state is saved.
- *
- * @property {() => string} getStorageKeyFn - Function for generating a unique key used for storage.
- * If not provided, a constant key 'autorestoreoptionsif' will be used.
- *
- * @property {(r1: T, r2: T, optionsIf: AutoRestoreOptionsIf<T>) => boolean} isSame - Function for checking
- * if two instances of T are considered the same when restoring state. If not provided, strict equality check (===) will be used.
+ * What a table remembers between page loads, and where. Everything is off by default ({@link AutoRestoreOptions});
+ * nothing is stored without {@link getStorageKeyFn} (the table warns once if a flag is set without it).
+ *
+ * The state is stored as one JSON value under `<key>tableState` in {@link storage} (default `localStorage`) –
+ * the same format as {@link TableApi.getState}. Columns are stored by property and rows by {@link getRowId}, so a
+ * moved column or new data never hits the wrong column or row. The stored state holds no cell values, but row ids
+ * can be personal data (e.g. an e-mail address as id) – prefer technical ids. The tree, checked rows, the selection
+ * and the first visible row need row ids; tree, checked and selected rows are computed only when their flag is set.
+ *
+ * | Flag | Remembers | since |
+ * |---|---|---|
+ * | {@link autoRestoreSortingState} | sorted columns | |
+ * | {@link autoRestoreScrollPosition} | scroll position | |
+ * | {@link autoRestoreCollapsedExpandedState} | expanded tree nodes | |
+ * | {@link autoRestoreColumnLayout} | width, order, visibility of the columns | 1.1.92 |
+ * | {@link autoRestoreHeaderGroupState} | collapsed header groups | 1.1.92 |
+ * | {@link autoRestoreCheckedState} | checked rows | 1.1.92 (declared before, without effect) |
+ * | {@link autoRestoreSelectedState} | selection | 1.1.92 (declared before, without effect) |
+ * | {@link autoRestoreCustomState} | your data ({@link TableApi.setCustomState}) | 1.1.92 |
+ *
+ * Before 1.1.92 sorting, scroll position and tree were stored under three keys (`<key>sortingState`,
+ * `<key>scrollState`, `<key>collapsedExpandedState`); they are read once and removed with the next save.
+ *
+ * @example
+ * const tableOptions: TableOptionsIf = {
+ *   ...new TableOptions(),
+ *   autoRestoreOptions: {
+ *     ...new AutoRestoreOptions<Order>(),
+ *     getStorageKeyFn: () => "orders",
+ *     getRowId: (order: Order) => order.id,
+ *     autoRestoreColumnLayout: true,
+ *     autoRestoreSortingState: true,
+ *     autoRestoreCheckedState: true
+ *   }
+ * };
+ *
+ * @typeparam T - The type of the rows.
+ * @see Training: [Remember the state](https://gui.expert/training/persist-state/)
  *
  * @category Options
  */
 export interface AutoRestoreOptionsIf<T> {
+    /** Remember the sorted columns (by property). */
     autoRestoreSortingState: boolean;
+    /** Remember expanded and collapsed nodes of a tree table (by {@link getRowId}). */
     autoRestoreCollapsedExpandedState?: boolean;
+    /** Remember the scroll position (and the id of the first visible row). */
     autoRestoreScrollPosition?: boolean;
+    /** Remember the checked rows (by {@link getRowId}). Since 1.1.92 (before: declared without effect). */
     autoRestoreCheckedState?: boolean;
+    /**
+     * Remember the selection: rows by {@link getRowId}, columns by property. Restored in the current row order.
+     * Since 1.1.92 (before: declared without effect).
+     */
     autoRestoreSelectedState?: boolean;
+    /**
+     * Remember width, order and visibility of the columns (by property). Widths are stored only for columns that were
+     * resized, so `%` and weight columns stay responsive.
+     * @since 1.1.92
+     */
+    autoRestoreColumnLayout?: boolean;
+    /**
+     * Remember collapsed and expanded header groups ({@link CellGroupIf.toggle}).
+     * @since 1.1.92
+     */
+    autoRestoreHeaderGroupState?: boolean;
+    /**
+     * Remember the data set with {@link TableApi.setCustomState} (e.g. a filter text).
+     * @since 1.1.92
+     */
+    autoRestoreCustomState?: boolean;
+    /**
+     * A unique, stable id per row (tree: per node). With the default of {@link AutoRestoreOptions} the table uses the
+     * property `id`, then `uuid`; rows without them are not stored (since 1.1.92 – the JSON of the row would write
+     * personal data into the storage; the table warns once).
+     */
     getRowId?: undefined | GetRowIdFn<T>;
+    /** The storage key of this table, e.g. `() => "orders"`. Without it nothing is stored. */
     getStorageKeyFn?: undefined | GetStorageKeyFn;
+    /**
+     * @deprecated since 1.1.92 – never used; rows are compared by {@link getRowId}.
+     */
     isSame?: undefined | IsSameFn<T>;
+    /**
+     * Where the state is stored. Default: `localStorage`; `sessionStorage` or an own {@link StateStorageIf} also work.
+     * @since 1.1.92
+     */
+    storage?: StateStorageIf;
 }

package/lib/table/data/options/default-row-id.d.ts

@@ -0,0 +1,4 @@
+/** Marks a function as the default `getRowId` of {@link AutoRestoreOptions}. */
+export declare function markDefaultGetRowId<F extends object>(fn: F): F;
+/** true for the default `getRowId` of {@link AutoRestoreOptions} (also after spreading the options). */
+export declare function isDefaultGetRowId(fn: unknown): boolean;

package/lib/table/data/options/overlay-options.d.ts

@@ -0,0 +1,30 @@
+import { OverlayOptionsIf } from './overlay-options.if.js';
+import { GeOverlayKind } from '../../overlay/ge-overlay-kind.type.js';
+
+/**
+ * The defaults of {@link OverlayOptionsIf}: English texts, an automatic "No rows to show", a loading overlay that
+ * blocks the body and appears right away.
+ *
+ * @example
+ * const overlayOptions = OverlayOptions.create({ noRowsText: "Keine Daten" });
+ * console.log(overlayOptions.loadingText); // "Loading…"
+ *
+ * @since 1.1.92
+ * @category Overlays
+ */
+export declare class OverlayOptions implements OverlayOptionsIf {
+    loadingText: string;
+    noRowsText: string;
+    noMatchesText: string;
+    autoNoRows: boolean;
+    blockInteractionWhileLoading: boolean;
+    loadingDelayInMs: number;
+    getOverlayElement?: (kind: GeOverlayKind, text: string) => HTMLElement | undefined;
+    /**
+     * The defaults with the given fields on top (`undefined` fields keep their default).
+     *
+     * @param {Partial<OverlayOptionsIf>} [partial] - e.g. `tableOptions.overlayOptions`
+     * @returns {OverlayOptions} a new object
+     */
+    static create(partial?: Partial<OverlayOptionsIf>): OverlayOptions;
+}

package/lib/table/data/options/overlay-options.if.d.ts

@@ -0,0 +1,79 @@
+import { GeOverlayKind } from '../../overlay/ge-overlay-kind.type.js';
+
+/**
+ * Texts and behaviour of the overlays over the table body: "Loading…" ({@link TableApi.showLoadingOverlay}),
+ * "No rows to show" (empty body) and "No matching rows" (the external filter hides all rows).
+ *
+ * Set it with {@link TableOptionsIf.overlayOptions} – every field is optional there, missing ones keep their
+ * default ({@link OverlayOptions}). The overlays are plain HTML and CSS (spinner: `@keyframes`), colours come from
+ * the CSS variables `--ge-table-overlay-bg`, `--ge-table-overlay-color`, `--ge-table-spinner-color`,
+ * `--ge-table-spinner-track-color` and `--ge-table-spinner-size`.
+ *
+ * @example
+ * const tableOptions: TableOptionsIf = {
+ *   ...new TableOptions(),
+ *   overlayOptions: {
+ *     loadingText: "Lädt…",
+ *     noRowsText: "Keine Daten",
+ *     noMatchesText: "Keine Treffer",
+ *     loadingDelayInMs: 200, // fast answers show no spinner at all
+ *   },
+ * };
+ *
+ * @since 1.1.92
+ * @see Training: [Live data](https://gui.expert/training/live-data/)
+ * @category Overlays
+ */
+export interface OverlayOptionsIf {
+    /** Text of the loading overlay. Default: `"Loading…"`. */
+    loadingText: string;
+    /** Text of the overlay of an empty body. Default: `"No rows to show"`. */
+    noRowsText: string;
+    /** Text when the external filter hides all rows. Default: `"No matching rows"`. */
+    noMatchesText: string;
+    /**
+     * `true` (default): an empty body shows "No rows to show" (or "No matching rows") by itself, after every
+     * repaint. `false`: only {@link TableApi.showNoRowsOverlay} shows it.
+     */
+    autoNoRows: boolean;
+    /**
+     * `true` (default): while "Loading…" is shown, the table ignores mouse events on the body (click, double click,
+     * hover, context menu – the page still sees them) and the keyboard cannot start editing or toggle rows in the body;
+     * navigation, copying and the header still work.
+     * `false`: the loading overlay is only a picture, the table stays usable.
+     * "No rows" / "No matching rows" never block.
+     */
+    blockInteractionWhileLoading: boolean;
+    /**
+     * Waits this long (ms) before the loading overlay appears. Answers that come faster show no spinner at all
+     * (no flashing); meanwhile an automatic "No rows to show" stays as it is. Default: `0` (right away).
+     */
+    loadingDelayInMs: number;
+    /**
+     * Own content of an overlay instead of the built-in one (spinner + text). Called once each time the overlay
+     * of a kind appears; return `undefined` to keep the built-in content for that kind. The table removes the
+     * element again when the overlay disappears or changes and in {@link TableApi.destroy}.
+     *
+     * The overlay is hidden from screen readers (`aria-hidden`, the table announces its text instead):
+     * put no buttons or links into it.
+     *
+     * @param {GeOverlayKind} kind - `"loading"`, `"noRows"` or `"noMatches"`
+     * @param {string} text - the text the built-in content would show
+     * @returns {HTMLElement | undefined} the element to show, or `undefined` for the default
+     *
+     * @example
+     * const tableOptions: TableOptionsIf = {
+     *   ...new TableOptions(),
+     *   overlayOptions: {
+     *     getOverlayElement: (kind: GeOverlayKind, text: string) => {
+     *       if (kind !== "noRows") return undefined; // built-in spinner and texts for the others
+     *       const div = document.createElement("div");
+     *       div.className = "my-empty-state";
+     *       div.textContent = `📭 ${text}`;
+     *       return div;
+     *     },
+     *   },
+     * };
+     */
+    getOverlayElement?: (kind: GeOverlayKind, text: string) => HTMLElement | undefined;
+}

package/lib/table/data/options/table-options.d.ts

@@ -11,6 +11,7 @@ import { FocusModelIf } from '../../focus/focus-model.if.js';
 import { ShortcutActionIdMapping } from '../../action/shortcut-actionid-mapping.type.js';
 import { HeaderGroupOptions } from './header-group-options.js';
 import { AriaTextsIf } from '../../aria/aria-texts.if.js';
+import { OverlayOptionsIf } from './overlay-options.if.js';
 
 /**
  * All default options of a table – see {@link TableOptionsIf} for the meaning of each field.
@@ -77,4 +78,6 @@ export declare class TableOptions implements TableOptionsIf {
     ariaDescribedBy?: string;
     /** Own screen reader texts; missing functions use the English defaults ({@link AriaTexts}). @since 1.1.91 */
     ariaTexts?: Partial<AriaTextsIf>;
+    /** Texts and behaviour of the "Loading…" / "No rows" overlays; missing fields use {@link OverlayOptions}. @since 1.1.92 */
+    overlayOptions?: Partial<OverlayOptionsIf>;
 }

package/lib/table/data/options/table-options.if.d.ts

@@ -11,6 +11,8 @@ import { FocusModelIf } from '../../focus/focus-model.if.js';
 import { ShortcutActionIdMapping } from '../../action/shortcut-actionid-mapping.type.js';
 import { HeaderGroupOptionsIf } from './header-group-options.if.js';
 import { AriaTextsIf } from '../../aria/aria-texts.if.js';
+import { TableStateIf } from '../../state/table-state.if.js';
+import { OverlayOptionsIf } from './overlay-options.if.js';
 
 /**
  * Represents the options for configuring a table.
@@ -301,4 +303,37 @@ export interface TableOptionsIf {
      * @since 1.1.91
      */
     ariaTexts?: Partial<AriaTextsIf>;
+    /**
+     * Texts and behaviour of the overlays over the body: "Loading…" ({@link TableApi.showLoadingOverlay}),
+     * "No rows to show" (empty body, automatic) and "No matching rows" (the filter hides all rows).
+     * Fields you leave out keep their default ({@link OverlayOptions}).
+     *
+     * @example
+     * const tableOptions: TableOptionsIf = {
+     *   ...new TableOptions(),
+     *   overlayOptions: { noRowsText: "No orders yet", blockInteractionWhileLoading: false },
+     * };
+     *
+     * @since 1.1.92
+     */
+    overlayOptions?: Partial<OverlayOptionsIf>;
+    /**
+     * The state the table starts with: column layout, sorting, tree, checked and selected rows … – e.g. loaded from
+     * your server ({@link TableApi.getState}, {@link EventListenerIf.onStateChanged}). A state stored by
+     * {@link autoRestoreOptions} wins over it, part by part.
+     *
+     * @example
+     * const saved = (await (await fetch("/api/prefs/orders")).json()) as TableStateIf | null;
+     * const tableOptions: TableOptionsIf = { ...new TableOptions(), initialState: saved ?? undefined };
+     *
+     * @since 1.1.92
+     */
+    initialState?: Partial<TableStateIf>;
+    /**
+     * Delay in ms between the last change of the state (resize, sort, scroll …) and
+     * {@link EventListenerIf.onStateChanged} / the save of {@link autoRestoreOptions}. Default 300.
+     *
+     * @since 1.1.92
+     */
+    stateChangedDebounceDelay?: number;
 }

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

@@ -18,6 +18,13 @@ export declare class AreaModelArrayOfArrays<T> extends AbstractAreaModel<T[][]>
     constructor(areaIdent: AreaIdent, arr: T[][], defaultRowHeight: number, columnDefs?: ColumnDefIf[]);
     externalFilterChanged(predictFn: FilterFunction<any>): void;
     getRowCount(): number;
+    /**
+     * The number of all rows, without the external filter.
+     *
+     * @returns {number} the length of the array
+     * @since 1.1.92
+     */
+    getUnfilteredRowCount(): number;
     getValueAt(rowIndex: number, columnIndex: number): any;
     setValue(rowIndex: number, columnIndex: number, value: any): boolean;
     getRowByIndex(rowIndex: number): any;

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

@@ -10,6 +10,7 @@ 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';
+import { TableHeaderGroupStateIf } from '../../../state/table-state.if.js';
 
 /** @category Header groups */
 export declare class AreaModelCellGroups implements AreaModelIf {
@@ -56,4 +57,34 @@ export declare class AreaModelCellGroups implements AreaModelIf {
     setRowChecked(_rowIndex: number, _checked: boolean): void;
     setValue(_rowIndex: number, _columnIndex: number, _value: any): boolean;
     toggleHeaderGroup(mouseTargetData: MouseTargetData): ColumnDefIf[];
+    /**
+     * The header groups the user can collapse (`toggle: true`, not `visibility: "always"`) with their id
+     * ({@link CellGroupIf.id}, otherwise the path of the labels, e.g. `"Customer"` or `"2026/Q1"`; a second group with
+     * the same path gets `#2`) and their state.
+     *
+     * @returns {TableHeaderGroupStateIf[]} id and `closed` per group, in header order
+     * @example
+     * const header = tableApi.getTableModel().getAreaModel("header") as AreaModelCellGroups;
+     * console.log(header.getToggleGroupStates());   // [{ id: "Customer", closed: false }]
+     * @since 1.1.92
+     */
+    getToggleGroupStates(): TableHeaderGroupStateIf[];
+    /**
+     * Collapses or expands a header group by its id (see {@link getToggleGroupStates}) and returns the column
+     * definitions to use from now on – like a click on its toggle. {@link TableApi.setHeaderGroupCollapsed} does this
+     * and repaints.
+     *
+     * @param {string} id - the id of the group
+     * @param {boolean} closed - true = collapse
+     * @returns {ColumnDefIf[] | undefined} the merged column definitions, `undefined` if there is no such group
+     * @since 1.1.92
+     */
+    setGroupClosed(id: string, closed: boolean): ColumnDefIf[] | undefined;
+    /** The toggleable groups by id (header order). */
+    private getToggleGroups;
+    /**
+     * Keep the existing ColumnDef objects (width, classes, renderers, sorting …) – only their visibility
+     * comes from the rebuilt groups. Fresh defs would reset every width to the default (100 px).
+     */
+    private mergeColumnDefs;
 }

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

@@ -267,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.

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

@@ -113,6 +113,15 @@ export declare class AreaModelTree<S> extends AbstractAreaModel<TreeRow<S>> {
      */
     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;
     /**

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

@@ -261,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

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

@@ -23,6 +23,13 @@ export declare class CoverGridBodyModel<T> implements AreaModelIf {
     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/cellgroup/cell-group.d.ts

@@ -9,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

@@ -17,6 +17,12 @@
  * @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. */

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

@@ -4,3 +4,8 @@ import { ColumnDefIf } from './column-def.if.js';
 export declare function setApiColumnVisibility(columnDef: ColumnDefIf, visible: boolean): void;
 /** Sets the header group visibility of a column and rebuilds its `isVisible`. */
 export declare function setGroupColumnVisibility(columnDef: ColumnDefIf, isVisible: (() => boolean) | undefined): void;
+/**
+ * Whether the column is shown apart from a collapsed header group: hidden with `setColumnVisible(…, false)` or by its
+ * own `isVisible` (e.g. `FalseFn` in the code) → false.
+ */
+export declare function isApiColumnVisible(columnDef: ColumnDefIf): boolean;