@guiexpert/table 1.1.89 → 1.1.91

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

@@ -1,352 +1,73 @@
-import { TableScope } from './table-scope';
-import { ColumnDefIf } from './data/tablemodel/column/column-def.if';
-import { TableCellUpdateEventIf } from './data/common/event/input/table-cell-update-event.if';
-import { SelectionModel } from './selection/selection-model';
-import { ActionId } from './action/action-id.type';
-import { ShortcutActionIdMapping } from './action/shortcut-actionid-mapping.type';
-import { SelectionModelIf } from './selection/selection-model.if';
-import { TableModelIf } from './data/tablemodel/table-model.if';
-import { AreaModelIf } from './data/tablemodel/areamodel/area-model.if';
+import { SortState } from './data/common/sort-state.type.js';
+import { TableScope } from './table-scope.js';
+import { ColumnDefIf } from './data/tablemodel/column/column-def.if.js';
+import { TableCellUpdateEventIf } from './data/common/event/input/table-cell-update-event.if.js';
+import { SelectionModel } from './selection/selection-model.js';
+import { ActionId } from './action/action-id.type.js';
+import { ShortcutActionIdMapping } from './action/shortcut-actionid-mapping.type.js';
+import { SelectionModelIf } from './selection/selection-model.if.js';
+import { TableModelIf } from './data/tablemodel/table-model.if.js';
+import { AreaModelIf } from './data/tablemodel/areamodel/area-model.if.js';
 
 /**
- * # TableApi
- *
- * The TableApi class provides a comprehensive interface for programmatically interacting with a table component.
- * After creating a table component, each component gets its own TableApi instance that serves as the primary
- * means for developers to control and interact with the rendered table.
- *
- * ## Overview
- *
- * TableApi acts as a facade over the internal table implementation, providing a clean, well-documented API
- * that abstracts away the complexity of the underlying table mechanics. It delegates most operations to the
- * TableScope instance, which contains the actual implementation details.
- *
- * ## Core Functionality
- *
- * The TableApi provides methods for:
- *
- * ### Data Management
- * - Setting, adding, and removing rows
- * - Updating individual cells or ranges of cells
- * - Finding and filtering rows based on criteria
- * - Sorting data with custom comparators
- *
- * ### Visual Control
- * - Scrolling to specific positions (by pixel or row/column index)
- * - Controlling visibility of header, footer, and columns
- * - Adjusting column widths (manually or automatically)
- * - Repainting the table (normal or hard repaint)
- *
- * ### Selection and Focus
- * - Managing cell, row, or column selection
- * - Clearing selections
- * - Ensuring specific rows are visible in the viewport
- *
- * ### Export and Clipboard
- * - Copying selected data to clipboard
- * - Exporting table data to Excel
- *
- * ### Events and Actions
- * - Triggering specific actions programmatically
- * - Responding to external filter changes
- *
- * ### Debugging
- * - Enabling/disabling logging for troubleshooting
- *
- * ## Usage Patterns
- *
- * The TableApi is designed to be used in several common patterns:
- *
- * ### 1. Direct Method Calls
- *
- * The most straightforward usage is to call methods directly on the TableApi instance:
- *
- * ```typescript
- * // Get the API from your table component
- * const api = tableComponent.api;
- *
- * // Call methods directly
- * api.setRows(newData);
- * api.scrollToIndex(0, 10);
- * api.repaint();
- * ```
- *
- * ### 2. Chaining Operations
- *
- * While the TableApi doesn't support method chaining directly (most methods return void),
- * you can group related operations together:
- *
- * ```typescript
- * // Perform a sequence of related operations
- * function updateTableSection(api, newRows, startIndex) {
- *   api.addRowsAt(newRows, startIndex);
- *   api.ensureRowIsVisible(startIndex);
- *   api.repaint();
- * }
- * ```
- *
- * ### 3. Event-Driven Updates
- *
- * Use the TableApi to respond to external events:
- *
- * ```typescript
- * // Update table in response to user input
- * searchInput.addEventListener('input', (e) => {
- *   const searchText = e.target.value;
- *   tableOptions.externalFilterFunction = row => row.name.includes(searchText);
- *   tableApi.externalFilterChanged();
- * });
- * ```
- *
- * ### 4. Integration with Application State
- *
- * Synchronize table state with application state:
- *
- * ```typescript
- * // In a state management effect or watcher
- * function onAppStateChanged(newState) {
- *   if (newState.tableData !== currentTableData) {
- *     tableApi.setRows(newState.tableData);
- *     tableApi.repaint();
- *     currentTableData = newState.tableData;
- *   }
- * }
- * ```
- *
- * ## Performance Considerations
- *
- * The TableApi provides methods that are optimized for different performance scenarios:
- *
- * - For frequent small updates: Use `updateCells()` with `repaintAll=false`
- * - For complete data replacement: Use `setRows()`
- * - For structural changes: Follow with `repaintHard()`
- * - For visual-only changes: Use `repaint()`
- *
- * ## Common Use Cases
- *
- * ### Real-time Data Updates
- *
- * ```typescript
- * // Update specific cells with new values from a data stream
- * dataStream.subscribe(update => {
- *   const cellUpdates = update.changes.map(change => ({
- *     area: 'body',
- *     rowIndex: change.rowIndex,
- *     columnIndex: change.columnIndex,
- *     value: change.newValue,
- *     cssClasses: { 'updated': true }
- *   }));
- *
- *   tableApi.updateCells(cellUpdates);
- * });
- * ```
- *
- * ### Interactive Filtering
- *
- * ```typescript
- * // Set up filter controls
- * function applyFilters(filters) {
- *   tableOptions.externalFilterFunction = row => {
- *     return Object.entries(filters).every(([key, value]) => {
- *       if (!value) return true; // Skip empty filters
- *       return row[key].toString().includes(value);
- *     });
- *   };
- *
- *   tableApi.externalFilterChanged();
- * }
- * ```
- *
- * ### Custom Sorting
- *
- * ```typescript
- * // Apply multi-column sorting
- * function sortByMultipleColumns(sortConfig) {
- *   tableApi.sort((a, b) => {
- *     for (const {column, direction} of sortConfig) {
- *       const aValue = a[column];
- *       const bValue = b[column];
- *       const comparison = compare(aValue, bValue);
- *
- *       if (comparison !== 0) {
- *         return direction === 'asc' ? comparison : -comparison;
- *       }
- *     }
- *     return 0;
- *   });
- * }
- *
- * function compare(a, b) {
- *   if (typeof a === 'string' && typeof b === 'string') {
- *     return a.localeCompare(b);
- *   }
- *   return a < b ? -1 : a > b ? 1 : 0;
- * }
- * ```
- *
- * ### Row Management
- *
- * ```typescript
- * // Add, update, and remove rows based on user interactions
- * function onAddRow(newRow) {
- *   tableApi.addRows([newRow]);
- *   tableApi.ensureRowIsVisible(tableApi.getDisplayedRowCount() - 1);
- * }
- *
- * function onUpdateRow(updatedRow) {
- *   tableApi.updateRows([updatedRow], (a, b) => a.id === b.id);
- * }
- *
- * function onDeleteRow(rowToDelete) {
- *   tableApi.removeRows([rowToDelete], (a, b) => a.id === b.id);
- * }
- * ```
- *
- * ### Export and Reporting
- *
- * ```typescript
- * // Set up export buttons
- * exportButton.addEventListener('click', () => {
- *   tableApi.downloadExcel('report.xlsx', 'Report Generator');
- * });
- *
- * copyButton.addEventListener('click', () => {
- *   tableApi.copyToClipboard()
- *     .then(() => showNotification('Data copied to clipboard'))
- *     .catch(err => showError('Failed to copy data', err));
- * });
- * ```
- *
- * ### Responsive Behavior
- *
- * ```typescript
- * // Handle window resize events
- * window.addEventListener('resize', () => {
- *   tableApi.autoResizeColumns();
- *   tableApi.repaintHard();
- * });
- * ```
- *
- * ## Integration with Frameworks
- *
- * ### React
- *
- * ```jsx
- * function DataTable({ data, onRowSelect }) {
- *   const tableRef = useRef(null);
- *
- *   useEffect(() => {
- *     if (tableRef.current && tableRef.current.api) {
- *       tableRef.current.api.setRows(data);
- *       tableRef.current.api.repaint();
- *     }
- *   }, [data]);
- *
- *   return <div ref={tableRef} className="table-container" />;
- * }
- * ```
- *
- * ### Vue
- *
- * ```vue
- * <template>
- *   <div ref="tableContainer"></div>
- * </template>
- *
- * <script>
- * export default {
- *   props: ['tableData'],
- *   watch: {
- *     tableData(newData) {
- *       if (this.tableApi) {
- *         this.tableApi.setRows(newData);
- *         this.tableApi.repaint();
- *       }
- *     }
- *   },
- *   mounted() {
- *     // Initialize table and get API reference
- *     this.tableApi = initializeTable(this.$refs.tableContainer).api;
- *   }
- * }
- * </script>
- * ```
- *
- * ### Angular
- *
- * ```typescript
- * @Component({
- *   selector: 'app-data-table',
- *   template: '<div #tableContainer></div>'
- * })
- * export class DataTableComponent implements OnInit, OnChanges {
- *   @Input() data: any[];
- *   @ViewChild('tableContainer') tableContainer: ElementRef;
- *
- *   private tableApi: TableApi;
- *
- *   ngOnInit() {
- *     this.tableApi = initializeTable(this.tableContainer.nativeElement).api;
- *   }
- *
- *   ngOnChanges(changes) {
- *     if (changes.data && this.tableApi) {
- *       this.tableApi.setRows(this.data);
- *       this.tableApi.repaint();
- *     }
- *   }
- * }
- * ```
- *
- * ## Error Handling
- *
- * The TableApi methods generally don't throw exceptions, but instead log warnings to the console
- * when operations cannot be completed (e.g., when trying to use row operations on an incompatible
- * area model type). It's good practice to check console warnings during development.
- *
- * For asynchronous operations like clipboard access, proper error handling should be used:
- *
- * ```typescript
- * tableApi.copyToClipboard()
- *   .then(content => {
- *     console.log('Copied to clipboard:', content);
- *   })
- *   .catch(error => {
- *     console.error('Failed to copy to clipboard:', error);
- *     // Show user-friendly error message
- *   });
- * ```
- *
- * ## Debugging
- *
- * For troubleshooting complex table behavior, the logging system can be enabled:
- *
- * ```typescript
- * // Enable detailed logging
- * tableApi.setLoggingActive(true);
- *
- * // Perform operations that need debugging
- * tableApi.updateCells([...]);
- * tableApi.scrollToIndex(5, 10);
- *
- * // Check if logging is active
- * const isLogging = tableApi.isLoggingActive();
- *
- * // Disable logging when done
- * tableApi.setLoggingActive(false);
- * ```
- *
- * ## Advanced Usage
- *
- * For advanced scenarios, you can access the underlying TableScope:
- *
- * ```typescript
- * const tableScope = tableApi.getTableScope();
- * // Now you can access internal implementation details
- * // Note: This is generally not recommended unless absolutely necessary
- * ```
- *
- * @class TableApi
+ * The public API of one table – everything you do with a table after it has been created:
+ * scrolling, sorting, filtering, selection, copy, Excel export, updating cells and rows, repainting.
+ *
+ * Every table has exactly one `TableApi`. You never create it yourself – you get it:
+ *
+ * | Where | How |
+ * |---|---|
+ * | Plain TypeScript | `new TableScope(host, model, new SimpleDomService(), options, listener).firstInit().getApi()` |
+ * | Web Component | `el.addEventListener("tableReady", e => e.detail)` |
+ * | React / Preact / Solid | `<GuiexpertTable tableReady={api => …} />` |
+ * | Vue 3 | `<GuiexpertTable @tableReady="api => …" />` |
+ * | Svelte 5 | `<GuiexpertTable onTableReady={api => …} />` |
+ * | Angular | `<guiexpert-table (tableReady)="onReady($event)" />` |
+ *
+ * ## The most important methods
+ *
+ * | Task | Methods |
+ * |---|---|
+ * | scroll | {@link scrollToIndex}, {@link ensureRowIsVisible}, {@link ensureColumnIsVisible}, {@link scrollToPixel}, {@link getFirstVisibleRowIndex} |
+ * | sort | {@link sortByColumn}, {@link sort}, {@link reSort} |
+ * | filter | {@link externalFilterChanged} (with {@link TableOptionsIf.externalFilterFunction}) |
+ * | export | {@link copyToClipboard}, {@link downloadExcel} |
+ * | change data | {@link updateCells}, {@link setRows}, {@link addRows}, {@link updateRows}, {@link removeRows} |
+ * | redraw | {@link repaint} (same row count), {@link repaintHard} (row count or heights changed) |
+ * | columns | {@link autoResizeColumns}, {@link setColumnWidth}, {@link recalcColumnWidths} |
+ * | tree | {@link expandAll}, {@link collapseAll}, {@link setRowExpanded} |
+ * | lifecycle | {@link destroy} |
+ *
+ * @example
+ * // plain TypeScript: create a table and talk to it
+ * const tableModel = TableFactory.createTableModel({ rows: orders });
+ * const tableApi = new TableScope(host, tableModel, new SimpleDomService(), new TableOptions(), new EventAdapter())
+ *   .firstInit()
+ *   .getApi();
+ *
+ * tableApi.scrollToIndex(0, 50_000);                  // column 0, row 50,000
+ * tableApi.sortByColumn("total", "desc");             // like a double-click on the header
+ * await tableApi.copyToClipboard();                   // the current selection, tab-separated
+ * await tableApi.downloadExcel("orders.xlsx");        // the current view as .xlsx
+ *
+ * @example
+ * // live data: change single cells, only the visible ones are redrawn
+ * tableApi.updateCells([
+ *   new TableCellUpdateEvent("body", 3, 2, 101.5, { "tick-up": true }),
+ *   new TableCellUpdateEvent("body", 3, 3, 0.42)
+ * ]);
+ *
+ * @example
+ * // replace the rows of an object-array table – the row count changes, so repaint hard
+ * tableApi.setRows(newOrders);
+ * tableApi.externalFilterChanged();                   // only if a filter function is set
+ * tableApi.repaintHard();
+ *
+ * @see Training: [Your first table](https://gui.expert/training/first-table/),
+ *   [Sorting](https://gui.expert/training/sorting/), [Filtering](https://gui.expert/training/filtering/),
+ *   [Excel export](https://gui.expert/training/excel-export/), [Live data](https://gui.expert/training/live-data/)
+ *
+ * @category Table & API
  */
 export declare class TableApi {
     readonly tableScope: TableScope;
@@ -495,7 +216,8 @@ export declare class TableApi {
      *
      * @example
      * // Scroll only vertically, keeping the current horizontal position
-     * tableApi.scrollToPixel(undefined, 300);
+     * // (an omitted or undefined px means 0; for rows use scrollToIndex(-1, rowIndex))
+     * tableApi.scrollToPixel(tableApi.getTableScope().scrollViewport.scrollLeft, 300);
      *
      * @example
      * // Example in a component that needs precise scrolling control
@@ -521,58 +243,6 @@ export declare class TableApi {
      *   }
      * }
      *
-     * @example
-     * // Advanced usage with animated scrolling
-     * class SmoothScroller {
-     *   private tableApi: TableApi;
-     *   private animationFrameId: number | null = null;
-     *
-     *   constructor(tableApi: TableApi) {
-     *     this.tableApi = tableApi;
-     *   }
-     *
-     *   smoothScrollTo(targetX: number, targetY: number, duration: number = 500) {
-     *     // Cancel any ongoing animation
-     *     if (this.animationFrameId !== null) {
-     *       cancelAnimationFrame(this.animationFrameId);
-     *     }
-     *
-     *     const startTime = performance.now();
-     *     const startX = this.tableApi.getTableScope().getScrollLeft();
-     *     const startY = this.tableApi.getTableScope().getScrollTop();
-     *     const distanceX = targetX - startX;
-     *     const distanceY = targetY - startY;
-     *
-     *     const step = (currentTime: number) => {
-     *       const elapsed = currentTime - startTime;
-     *       const progress = Math.min(elapsed / duration, 1);
-     *
-     *       // Use easing function for smooth animation
-     *       const easeProgress = 1 - Math.pow(1 - progress, 3); // Cubic ease-out
-     *
-     *       const currentX = startX + distanceX * easeProgress;
-     *       const currentY = startY + distanceY * easeProgress;
-     *
-     *       this.tableApi.scrollToPixel(currentX, currentY);
-     *
-     *       if (progress < 1) {
-     *         this.animationFrameId = requestAnimationFrame(step);
-     *       } else {
-     *         this.animationFrameId = null;
-     *       }
-     *     };
-     *
-     *     this.animationFrameId = requestAnimationFrame(step);
-     *   }
-     *
-     *   cancelAnimation() {
-     *     if (this.animationFrameId !== null) {
-     *       cancelAnimationFrame(this.animationFrameId);
-     *       this.animationFrameId = null;
-     *     }
-     *   }
-     * }
-     *
      * @see {@link scrollToIndex} - For scrolling based on row and column indices
      * @see {@link ensureRowIsVisible} - For scrolling to make a specific row visible
      */
@@ -580,112 +250,130 @@ export declare class TableApi {
     /**
      * Scrolls the table to display the specified row and column indices at the top-left corner of the viewport.
      *
-     * This method allows programmatic scrolling to a specific position in the table grid based on row and column indices.
-     * It uses the underlying TableScope's scrolling mechanism to navigate to the target location.
+     * The row becomes the first row of the body, the column the first column of the scrollable (center) part –
+     * as far as the scroll range allows: the last columns and rows cannot move further than to the right/bottom edge.
+     *
+     * Fixed columns (`fixedLeftColumnCount` / `fixedRightColumnCount`) are always visible: a fixed west column scrolls
+     * back to the start (x = 0), a fixed east column – and `-1` or any other index outside the columns – keeps the
+     * current horizontal position.
      *
-     * @param {number} indexX - The horizontal index (column) to scroll to. Defaults to 0 (leftmost column).
+     * @param {number} indexX - The column index (model index, fixed columns included) to scroll to.
+     *   Defaults to 0 (first column). `-1` keeps the horizontal position.
      * @param {number} indexY - The vertical index (row) to scroll to. Defaults to 0 (topmost row).
      * @returns {void}
      *
      * @example
      * // Scroll to the 5th row, keeping the current horizontal scroll position
-     * tableApi.scrollToIndex(0, 5);
+     * tableApi.scrollToIndex(-1, 5);
      *
      * @example
      * // Scroll to column 3, row 10
      * tableApi.scrollToIndex(3, 10);
      *
      * @example
-     * // Example in a component that needs to navigate to specific content
-     * class TableNavigator {
-     *   private tableApi: TableApi;
-     *
-     *   constructor(tableApi: TableApi) {
-     *     this.tableApi = tableApi;
-     *   }
-     *
-     *   goToCell(columnIndex: number, rowIndex: number) {
-     *     // Navigate directly to the specified cell position
-     *     this.tableApi.scrollToIndex(columnIndex, rowIndex);
-     *
-     *     // Optional: Select the cell after navigating to it
-     *     const selectionModel = this.tableApi.getSelectionModel();
-     *     if (selectionModel) {
-     *       selectionModel.selectCell(rowIndex, columnIndex);
-     *     }
-     *   }
-     * }
-     *
-     * @example
-     * // Advanced usage with search functionality
-     * class TableSearcher {
-     *   findAndScrollToMatch(searchTerm: string) {
-     *     const tableModel = this.tableApi.getTableModel();
-     *     const bodyModel = tableModel.getAreaModel('body');
-     *
-     *     // Search for the term in the table data
-     *     for (let row = 0; row < bodyModel.getRowCount(); row++) {
-     *       for (let col = 0; col < tableModel.getColumnCount(); col++) {
-     *         const cellContent = bodyModel.getValueAt(row, col)?.toString() || '';
-     *
-     *         if (cellContent.includes(searchTerm)) {
-     *           // Found a match, scroll to it
-     *           this.tableApi.scrollToIndex(col, row);
-     *           return true;
-     *         }
-     *       }
-     *     }
-     *
-     *     return false; // No match found
-     *   }
-     * }
+     * // Scroll to column 3, keeping the rows that are currently shown
+     * tableApi.scrollToIndex(3, tableApi.getFirstVisibleRowIndex());
      *
      * @see {@link scrollToPixel} - For scrolling to specific pixel coordinates
      * @see {@link ensureRowIsVisible} - For scrolling to make a specific row visible
      */
     scrollToIndex(indexX?: number, indexY?: number): void;
     /**
-     * Sets whether the header is visible or not.
+     * Shows or hides the header and repaints the table.
+     *
+     * A hidden header takes no space – the body moves up and shows more rows. The header rows stay in the model
+     * (labels, sort icons, header groups), so `setHeaderVisible(true)` brings them back unchanged.
+     * Requires a {@link TableModel} (what all factories create).
      *
-     * @param _visible - A boolean value indicating whether the header should be visible. Default value is true.
+     * @param {boolean} [visible=true] - false hides the header
+     * @returns {void}
+     *
+     * @example
+     * // a compact view without column headers
+     * tableApi.setHeaderVisible(false);
      *
-     * @return undefined
+     * @example
+     * // toggle from a button
+     * document.querySelector("#toggle-header")!.addEventListener("click", () =>
+     *   tableApi.setHeaderVisible(!tableApi.isHeaderVisible()));
      */
-    setHeaderVisible(_visible?: boolean): void;
+    setHeaderVisible(visible?: boolean): void;
     /**
-     * Sets the visibility of a column in the table.
+     * Shows or hides a column and repaints the table.
+     *
+     * The column keeps its definition, its position (also when other columns are dragged) and its width:
+     * a hidden column is just not rendered (width 0), not copied ({@link copyToClipboard}) and not exported
+     * ({@link downloadExcel}). Showing it again restores the previous width. Works for fixed columns, too.
      *
-     * @param {_column} - The column index or column definition to set visibility for.
-     * @param {_visible=true} - The flag to set visibility to. true for visible, false for hidden.
+     * The same as {@link ColumnDefIf.isVisible} – this method sets it to {@link TrueFn} / {@link FalseFn} (an own
+     * `isVisible` function of the column is replaced). Columns without a column definition (e.g. `bodyData` +
+     * `columnSizes` without `columnDefs`) can't be hidden.
      *
-     * @return {void} - There is no return value.
+     * @param {number | string | ColumnDefIf} column - column index (fixed columns included), property (e.g. `"category"`)
+     *   or the column definition
+     * @param {boolean} [visible=true] - false hides the column
+     * @returns {boolean} false if the column (definition) does not exist
+     *
+     * @example
+     * // hide a column by property, show it again later
+     * tableApi.setColumnVisible("category", false);
+     * tableApi.setColumnVisible("category", true);
+     *
+     * @example
+     * // a checkbox list "visible columns"
+     * tableApi.getTableModel().getColumnDefs()?.forEach((columnDef, index) => {
+     *   const checkbox = document.createElement("input");
+     *   checkbox.type = "checkbox";
+     *   checkbox.checked = tableApi.isColumnVisible(index);
+     *   checkbox.addEventListener("change", () => tableApi.setColumnVisible(columnDef, checkbox.checked));
+     *   document.body.append(checkbox, columnDef.headerLabel);
+     * });
      */
-    setColumnVisible(_column: number | ColumnDefIf, _visible?: boolean): void;
+    setColumnVisible(column: number | string | ColumnDefIf, visible?: boolean): boolean;
     /**
-     * Returns whether a column is visible or not.
+     * Returns whether a column is visible ({@link ColumnDefIf.isVisible}, see {@link setColumnVisible}).
+     * Columns without a column definition are always visible.
      *
-     * @param {number | ColumnDefIf} _column - The column index or the column definition.
-     * @return {boolean} - True if the column is visible, false otherwise.
+     * @param {number | string | ColumnDefIf} column - column index, property or column definition
+     * @return {boolean} - True if the column is visible, false if it is hidden or does not exist.
+     *
+     * @example
+     * if (!tableApi.isColumnVisible("category")) {
+     *   tableApi.setColumnVisible("category", true);
+     * }
      */
-    isColumnVisible(_column: number | ColumnDefIf): boolean;
+    isColumnVisible(column: number | string | ColumnDefIf): boolean;
     /**
-     * Checks if the header is visible.
+     * Checks if the header is visible: it has at least one row and is not hidden with {@link setHeaderVisible}.
      *
      * @return {boolean} - Returns true if the header is visible, otherwise returns false.
+     *
+     * @example
+     * const headerShown = tableApi.isHeaderVisible();
      */
     isHeaderVisible(): boolean;
     /**
-     * Sets the visibility of the footer.
+     * Shows or hides the footer and repaints the table.
      *
-     * @param {boolean} _visible - Indicates whether the footer should be visible or not. Default value is true.
+     * A hidden footer takes no space – the body gets taller. Its rows stay in the model, so `setFooterVisible(true)`
+     * brings them back (an own footer model, e.g. totals, is asked for its values again).
+     * Requires a {@link TableModel} (what all factories create).
      *
-     * @return {void} - This method does not return any value.
+     * @param {boolean} [visible=true] - false hides the footer
+     * @returns {void}
+     *
+     * @example
+     * // show the totals footer only while a filter is active
+     * tableApi.setFooterVisible(!!tableOptions.externalFilterFunction);
      */
-    setFooterVisible(_visible?: boolean): void;
+    setFooterVisible(visible?: boolean): void;
     /**
-     * Determines if the footer is visible.
+     * Determines if the footer is visible: it has at least one row and is not hidden with {@link setFooterVisible}.
      *
      * @returns {boolean} True if the footer is visible, false otherwise.
+     *
+     * @example
+     * const footerShown = tableApi.isFooterVisible();
      */
     isFooterVisible(): boolean;
     /**
@@ -707,12 +395,12 @@ export declare class TableApi {
      *
      * @example
      * // Update selection and repaint to show the visual change
-     * tableApi.getSelectionModel().selectCell(2, 3);
+     * tableApi.getSelectionModel()?.togglePoint(2, 3);
      * tableApi.repaint();
      *
      * @example
-     * // After changing column visibility, repaint to reflect changes
-     * tableApi.setColumnVisible(0, false);
+     * // After changing values in the row objects yourself, repaint to show them
+     * orders[0].status = "paid";
      * tableApi.repaint();
      *
      * @returns {void}
@@ -763,8 +451,9 @@ export declare class TableApi {
      * });
      *
      * @example
-     * // Example 4: Using after changing column visibility
-     * tableApi.setColumnVisible(2, false);
+     * // Example 4: Using after changing ColumnDefIf.isVisible yourself
+     * // (setColumnVisible() does this on its own)
+     * column.isVisible = FalseFn;
      * tableApi.repaintHard();
      *
      * @returns {void} This method doesn't return a value
@@ -790,20 +479,9 @@ export declare class TableApi {
      * the selection is cleared.
      *
      * @example
-     * // Clear all selections in the table
+     * // Clear all selections in the table (e.g. from a "reset" button)
      * tableApi.clearSelection();
      *
-     * // Example usage in a component
-     * class MyComponent {
-     *   @ViewChild('tableComponent') tableComponent: TableComponent;
-     *
-     *   resetTableSelection(): void {
-     *     if (this.tableComponent?.api) {
-     *       this.tableComponent.api.clearSelection();
-     *     }
-     *   }
-     * }
-     *
      * @returns {void}
      */
     clearSelection(): void;
@@ -885,6 +563,7 @@ export declare class TableApi {
      *
      * The copied data is formatted as tab-separated text that can be pasted into spreadsheet
      * applications like Excel or text editors while maintaining the tabular structure.
+     * Screen readers hear "12 cells copied" ({@link AriaTextsIf.copied}).
      *
      * @example
      * // Copy the currently selected data to clipboard
@@ -910,6 +589,38 @@ export declare class TableApi {
      *   The string contains the tab-separated representation of the selected table data.
      */
     copyToClipboard(): Promise<string>;
+    /**
+     * Speaks a message to screen reader users through the live region of the table (`role="status"`,
+     * polite – it does not interrupt). The table itself announces sorting, filter results, copying and
+     * "select all"; use this for your own events, e.g. after loading or saving data.
+     *
+     * @example
+     * fetch("/api/orders").then(r => r.json()).then(orders => {
+     *   tableApi.setRows(orders);
+     *   tableApi.announce(`${orders.length} orders loaded`);
+     * });
+     *
+     * @param {string} text - plain text (not HTML)
+     * @since 1.1.91
+     * @see Training: [Accessible tables: keyboard and screen readers](https://gui.expert/training/accessibility/)
+     */
+    announce(text: string): void;
+    /**
+     * The header cell that has the keyboard focus. Arrow up in the first body row moves the focus into the header
+     * (Enter sorts or opens/closes a header group there); arrow down leaves it. The {@link FocusModelIf} holds
+     * the body focus only and is not changed by this.
+     *
+     * @example
+     * const headerFocus = tableApi.getHeaderFocus();
+     * if (headerFocus) {
+     *   const [headerRow, column] = headerFocus;
+     *   console.log(`header cell ${headerRow}/${column} has the focus`);
+     * }
+     *
+     * @returns {[number, number] | undefined} header row index and column index, `undefined` if the focus is in the body
+     * @since 1.1.91
+     */
+    getHeaderFocus(): [number, number] | undefined;
     /**
      * Downloads the current table data as an Excel file.
      *
@@ -925,7 +636,7 @@ export declare class TableApi {
      * @param {string} fileName - The name of the Excel file to be downloaded (default: 'table.xlsx')
      * @param {string} author - Optional metadata for the Excel file to specify the author (default: '')
      *
-     * @returns {void} The result of the excelService.downloadExcel method call
+     * @returns {Promise<void>} resolves when the (compressed) file has been handed to the browser
      *
      * @example
      * // Download table data with default filename
@@ -939,7 +650,7 @@ export declare class TableApi {
      * // Download table data with custom filename only
      * tableApi.downloadExcel('quarterly-data.xlsx');
      */
-    downloadExcel(fileName?: string, author?: string): void;
+    downloadExcel(fileName?: string, author?: string): Promise<void>;
     /**
      * Returns the TableScope instance associated with this TableApi.
      *
@@ -995,7 +706,7 @@ export declare class TableApi {
      *
      * // Add a selection change listener
      * selectionModel?.addEventSelectionChangedListener({
-     *   selectionChanged: () => {
+     *   onSelectionChanged: () => {
      *     console.log('Selection has changed');
      *   }
      * });
@@ -1046,6 +757,10 @@ export declare class TableApi {
     /**
      * Sets the rows data for the table body, replacing any existing rows.
      *
+     * Only works with an {@link AreaModelObjectArray} body – logs a console warning otherwise.
+     * Does **not** repaint and resets filtering and sorting of the body: afterwards call
+     * {@link externalFilterChanged} (if a filter function is set) and {@link repaintHard} (the row count changed).
+     *
      * @template T - The type of elements in the rows array
      * @param {T[]} rows - An array of data objects to set as the table's rows
      *
@@ -1054,13 +769,15 @@ export declare class TableApi {
      * It only works with tables that use AreaModelObjectArray as their body model.
      *
      * @return {void} - This method doesn't return anything.
-     *
-     * @throws {Warning} Logs a console warning if the table's body model is not an AreaModelObjectArray
      */
     setRows<T>(rows: T[]): void;
     /**
      * Adds new rows to the end of the table body.
      *
+     * Only works with an {@link AreaModelObjectArray} body – logs a console warning otherwise.
+     * Does **not** repaint and resets filtering and sorting of the body: afterwards call
+     * {@link externalFilterChanged} (if a filter function is set) and {@link repaintHard} (the row count changed).
+     *
      * @template T - The type of elements in the rows array
      * @param {T[]} rows - An array of data objects to append to the table's existing rows
      *
@@ -1070,12 +787,20 @@ export declare class TableApi {
      *
      * @return {void} - This method doesn't return anything.
      *
-     * @throws {Warning} Logs a console warning if the table's body model is not an AreaModelObjectArray
+     *
+     * @example
+     * tableApi.addRows([{ id: 100_001, customer: "New GmbH" }]);
+     * tableApi.repaintHard();
+     * tableApi.ensureRowIsVisible(tableApi.getDisplayedRowCount() - 1);
      */
     addRows<T>(rows: T[]): void;
     /**
      * Inserts new rows at a specific position in the table body.
      *
+     * Only works with an {@link AreaModelObjectArray} body – logs a console warning otherwise.
+     * Does **not** repaint and resets filtering and sorting of the body: afterwards call
+     * {@link externalFilterChanged} (if a filter function is set) and {@link repaintHard} (the row count changed).
+     *
      * @template T - The type of elements in the rows array
      * @param {T[]} rows - An array of data objects to insert into the table
      * @param {number} rowIndex - The index position where the new rows should be inserted
@@ -1086,13 +811,15 @@ export declare class TableApi {
      * It only works with tables that use AreaModelObjectArray as their body model.
      *
      * @return {void} - This method doesn't return anything.
-     *
-     * @throws {Warning} Logs a console warning if the table's body model is not an AreaModelObjectArray
      */
     addRowsAt<T>(rows: T[], rowIndex: number): void;
     /**
      * Removes specified rows from the table body.
      *
+     * Only works with an {@link AreaModelObjectArray} body – logs a console warning otherwise.
+     * Does **not** repaint and resets filtering and sorting of the body: afterwards call
+     * {@link externalFilterChanged} (if a filter function is set) and {@link repaintHard} (the row count changed).
+     *
      * @template T - The type of elements in the rows array
      * @param {T[]} rows - An array of data objects to remove from the table
      * @param {(a: T, b: T) => boolean} predicate - A comparison function that determines if two rows match
@@ -1104,13 +831,13 @@ export declare class TableApi {
      * It only works with tables that use AreaModelObjectArray as their body model.
      *
      * @return {void} - This method doesn't return anything.
-     *
-     * @throws {Warning} Logs a console warning if the table's body model is not an AreaModelObjectArray
      */
     removeRows<T>(rows: T[], predicate?: (a: T, b: T) => boolean): void;
     /**
      * Searches for and returns rows from the table body that match the given criteria.
      *
+     * Only works with an {@link AreaModelObjectArray} body – logs a console warning otherwise.
+     *
      * @template T - The type of elements in the rows array
      *
      * @description
@@ -1133,13 +860,11 @@ export declare class TableApi {
      *
      * @example
      * // Find rows with simple equality comparison
-     * const matchingRows = table.findRows([row1, row2]);
+     * const matchingRows = tableApi.findRows([orders[0], orders[1]]);
      *
      * @example
      * // Find rows with custom comparison logic
-     * const matchingRows = table.findRows([row1, row2], (a, b) => a.id === b.id);
-     *
-     * @throws {Warning} Logs a console warning if the table's body model is not an AreaModelObjectArray
+     * const matchingRows = tableApi.findRows<Order>([{ ...orders[0] }], (a, b) => a.id === b.id);
      */
     findRows<T>(rows: T[], predicate?: (a: T, b: T) => boolean): T[];
     /**
@@ -1179,12 +904,6 @@ export declare class TableApi {
      *   (criteria, row) => row.name.toLowerCase().includes(criteria.name!.toLowerCase())
      * );
      *
-     * // Find a person within age range
-     * const ageCriteria = { minAge: 25, maxAge: 35 };
-     * const person3 = tableApi.findRowFromFilteredRowsByAllCriteria<Person>(
-     *   ageCriteria,
-     *   (criteria, row) => row.age >= criteria.minAge! && row.age <= criteria.maxAge!
-     * );
      * ```
      *
      * @throws {Warning} Logs a warning to console if the body model is not an instance of AreaModelObjectArray
@@ -1221,17 +940,16 @@ export declare class TableApi {
      * // Find a product row with partial match on name
      * const criteria = { name: "Phone" };
      * const product = tableApi.findRowFromAllRowsByAllCriteria(criteria,
-     *   (criteria, row) => row.name.includes(criteria.name)
+     *   (criteria, row) => row.name.includes(criteria.name!)
      * );
      *
      * @example
      * // Find an order with complex matching logic
-     * const criteria = { total: 100, status: "pending" };
-     * const order = tableApi.findRowFromAllRowsByAllCriteria(criteria,
+     * const criteria = { total: 100, status: "paid" as const };
+     * const order = tableApi.findRowFromAllRowsByAllCriteria<Order>(criteria,
      *   (criteria, row) => {
-     *     return row.total > criteria.total &&
-     *            row.status === criteria.status &&
-     *            row.items.length > 0;
+     *     return row.total > criteria.total! &&
+     *            row.status === criteria.status;
      *   }
      * );
      *
@@ -1241,6 +959,9 @@ export declare class TableApi {
     /**
      * Updates existing rows in the table body with new data.
      *
+     * Only works with an {@link AreaModelObjectArray} body – logs a console warning otherwise.
+     * The properties are copied into the existing objects; nothing is repainted – call {@link repaint} afterwards.
+     *
      * @template T - The type of elements in the rows array
      * @param {T[]} rows - An array of data objects containing the updated values
      * @param {(a: T, b: T) => boolean} predicate - A comparison function that determines which rows to update
@@ -1254,21 +975,63 @@ export declare class TableApi {
      * It only works with tables that use AreaModelObjectArray as their body model.
      *
      * @return {void} - This method doesn't return anything.
-     *
-     * @throws {Warning} Logs a console warning if the table's body model is not an AreaModelObjectArray
      */
     updateRows<T>(rows: T[], predicate?: (a: T, b: T) => boolean): void;
     /**
-     * Re-applies the current sorting configuration to the table data.
+     * Sorts by one column from code – e.g. from your own button – exactly like a double click on the
+     * column header: rows, header icon, filter (sort order survives filtering) and auto-restore.
+     *
+     * @param {number | string} column - column index or property, e.g. `"total"`
+     * @param {SortState} [sortState] - `"asc"` or `"desc"`; omitted: toggles like the header (asc → desc → …)
+     * @returns {boolean} false if the column does not exist
+     *
+     * @example
+     * document.querySelector("#by-total")!.addEventListener("click", () => tableApi.sortByColumn("total", "desc"));
+     */
+    sortByColumn(column: number | string, sortState?: SortState): boolean;
+    /**
+     * Re-applies the current sorting configuration to the table data and repaints.
      *
      * @description
-     * This method triggers a re-sort of the table data using the current sorting configuration.
-     * It's useful when the underlying data has changed and needs to be re-sorted without changing
-     * the sort columns or direction.
+     * The current sorting is the last {@link sort} function, otherwise the columns with a sort state (the header icons,
+     * also restored by `autoRestoreOptions`). Useful when the underlying data has changed and needs to be re-sorted
+     * without changing the sort columns or direction. (Before 1.1.91 only the sort items stored by `autoRestoreOptions`
+     * were used – without them `reSort()` did nothing.)
+     *
+     * @example
+     * orders[0].total = 999_999;
+     * tableApi.reSort();
      *
      * @return {void} - This method doesn't return anything.
      */
     reSort(): void;
+    /**
+     * Tree tables: expands every row on every level (like the "expand all" icon in the header) and repaints.
+     * No effect for other tables.
+     *
+     * @example
+     * document.querySelector("#expand")!.addEventListener("click", () => tableApi.expandAll());
+     */
+    expandAll(): void;
+    /**
+     * Tree tables: collapses every row on every level and repaints. No effect for other tables.
+     *
+     * @example
+     * tableApi.collapseAll();
+     */
+    collapseAll(): void;
+    /**
+     * Tree tables: expands or collapses the displayed body row `rowIndex` (like a click on its arrow), repaints and
+     * remembers the state with `autoRestoreOptions`.
+     *
+     * @param {number} rowIndex - index of the displayed body row
+     * @param {boolean} expanded - the new state
+     * @returns {boolean} false if the table is no tree, the row does not exist or already has this state
+     *
+     * @example
+     * tableApi.setRowExpanded(0, true);   // expand the first row
+     */
+    setRowExpanded(rowIndex: number, expanded: boolean): boolean;
     /**
      * Sorts the table data using a custom comparison function.
      *
@@ -1286,7 +1049,7 @@ export declare class TableApi {
      *
      * @example
      * // Sort table rows by a specific property in ascending order
-     * table.api.sort((a, b) => {
+     * tableApi.sort((a: Person, b: Person) => {
      *   if (a.name < b.name) return -1;
      *   if (a.name > b.name) return 1;
      *   return 0;
@@ -1294,24 +1057,29 @@ export declare class TableApi {
      *
      * @example
      * // Sort numbers in descending order
-     * table.api.sort((a, b) => b.value - a.value);
+     * tableApi.sort((a: { value: number }, b: { value: number }) => b.value - a.value);
      *
      * @example
      * // Sort with multiple criteria
-     * table.api.sort((a, b) => {
+     * tableApi.sort((a: Order, b: Order) => {
      *   // First sort by status
      *   const statusCompare = a.status.localeCompare(b.status);
      *   if (statusCompare !== 0) return statusCompare;
      *
      *   // Then sort by name if status is equal
-     *   return a.name.localeCompare(b.name);
+     *   return a.customer.localeCompare(b.customer);
      * });
      *
      * @example
      * // Case-insensitive string sorting
-     * table.api.sort((a, b) =>
+     * tableApi.sort((a: Person, b: Person) =>
      *   a.name.toLowerCase().localeCompare(b.name.toLowerCase())
      * );
+     *
+     * @example
+     * // Tree tables: the function compares the tree rows of siblings (your objects: a.data / b.data),
+     * // children stay below their parent
+     * tableApi.sort((a: TreeRowIf<OrderNode>, b: TreeRowIf<OrderNode>) => b.data.total - a.data.total);
      */
     sort(compareFn: (a: any, b: any) => number): void;
     /**
@@ -1331,41 +1099,32 @@ export declare class TableApi {
      * // Ensure row 5 is visible in the viewport
      * tableApi.ensureRowIsVisible(5);
      *
-     * @example
-     * // Example usage in a component
-     * class MyTableComponent {
-     *   private tableApi: TableApi;
-     *
-     *   scrollToSpecificRow(rowIndex: number) {
-     *     // This will scroll the row into view if it's not visible
-     *     const didScroll = this.tableApi.ensureRowIsVisible(rowIndex);
-     *
-     *     if (didScroll) {
-     *       console.log(`Table scrolled to show row ${rowIndex}`);
-     *     } else {
-     *       console.log(`Row ${rowIndex} was already visible`);
-     *     }
-     *   }
-     * }
-     *
-     * @example
-     * // Example with row selection
-     * class TableHandler {
-     *   selectAndShowRow(rowIndex: number) {
-     *     // First ensure the row is visible
-     *     this.tableApi.ensureRowIsVisible(rowIndex);
-     *
-     *     // Then perform selection
-     *     this.selectionModel.selectRow(rowIndex);
-     *   }
-     * }
-     *
      * @throws {Error} Implicitly may throw if rowIndex is not a number or if required properties are undefined
      *
      * @see {@link scrollToIndex} - The underlying method used for scrolling
      * @see {@link getDisplayedRowCount} - Related method for getting visible row count
      */
     ensureRowIsVisible(rowIndex: number): boolean;
+    /**
+     * Ensures that a column is fully visible by scrolling horizontally if necessary – the counterpart of
+     * {@link ensureRowIsVisible}. A column left of the viewport becomes the first visible column, a column right of it
+     * the last one. The vertical position is kept. The arrow keys use it for the focused cell.
+     *
+     * Fixed columns (`fixedLeftColumnCount` / `fixedRightColumnCount`) are always visible, hidden columns
+     * ({@link setColumnVisible}) can't be scrolled to: both return `false`.
+     *
+     * @param {number} columnIndex - The column index (model index over west + center + east)
+     * @returns {boolean} true if the table was scrolled, false if the column was already visible
+     *
+     * @example
+     * // show the column of a search hit (rowIndex/columnIndex from your own search)
+     * const rowIndex = 1200, columnIndex = 14;
+     * tableApi.ensureColumnIsVisible(columnIndex);
+     * tableApi.ensureRowIsVisible(rowIndex);
+     *
+     * @see {@link scrollToIndex} - scrolls a column and row to the top left
+     */
+    ensureColumnIsVisible(columnIndex: number): boolean;
     /**
      * Retrieves the number of rows currently displayed in the table.
      *
@@ -1425,7 +1184,7 @@ export declare class TableApi {
      * const firstFullVisibleRow = tableApi.getFirstFullVisibleRowIndex();
      *
      * // Check if a specific row is fully visible
-     * const isRowFullyVisible = (rowIndex) => {
+     * const isRowFullyVisible = (rowIndex: number) => {
      *   const firstFullVisible = tableApi.getFirstFullVisibleRowIndex();
      *   const lastFullVisible = tableApi.getLastFullVisibleRowIndex();
      *   return rowIndex >= firstFullVisible && rowIndex <= lastFullVisible;