@guiexpert/table 1.1.79 → 1.1.80

package/index.js

@@ -1198,28 +1198,128 @@ class Be {
   }
 }
 class L extends ue {
+  /**
+   * Creates an instance of AreaModelObjectArray.
+   * 
+   * @param {AreaIdent} areaIdent - Identifies which area of the table this model represents ('header', 'body', or 'footer')
+   * @param {T[]} rows - The array of objects that represent the rows in this area
+   * @param {number} defaultRowHeight - The default height for rows in this area (in pixels)
+   * @param {ColumnDefIf[]} [columnDefs=[]] - Definitions for the columns in this area
+   * @param {string} [selectedRowClass='ge-selected-row'] - CSS class to apply to selected rows
+   * @param {string} [focusedRowClass='ge-focused-row'] - CSS class to apply to the focused row
+   * 
+   * @example
+   * const rows = [
+   *   { id: 1, name: 'John', age: 30 },
+   *   { 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 bodyAreaModel = new AreaModelObjectArray(
+   *   'body',
+   *   rows,
+   *   30,
+   *   columnDefs
+   * );
+   */
   constructor(e, t, s, o = [], i = "ge-selected-row", r = "ge-focused-row") {
     super(e, o, s), this.areaIdent = e, this.rows = t, this.defaultRowHeight = s, this.columnDefs = o, this.selectedRowClass = i, this.focusedRowClass = r, this.sorterService = new Be(), this._focusedRowIndex = 0, this.filteredRows = [...t], this.properties = o.map((n) => n.property);
   }
+  /**
+   * Gets the index of the currently focused row.
+   * 
+   * @returns {number} The index of the focused row
+   * 
+   * @example
+   * const focusedRowIndex = bodyAreaModel.getFocusedRowIndex();
+   * console.log(`The focused row is at index ${focusedRowIndex}`);
+   */
   getFocusedRowIndex() {
     return this._focusedRowIndex;
   }
+  /**
+   * Sets the index of the focused row.
+   * This will apply the focused row styling to the specified row.
+   * 
+   * @param {number} value - The index of the row to focus
+   * 
+   * @example
+   * // Focus the second row (index 1)
+   * bodyAreaModel.setFocusedRowIndex(1);
+   */
   setFocusedRowIndex(e) {
     this._focusedRowIndex = e;
   }
+  /**
+   * Replaces the current rows array with a new one.
+   * This also resets the filtered rows to match the new rows array.
+   * 
+   * @param {T[]} rows - The new array of row objects
+   * 
+   * @example
+   * // Replace the current rows with new data
+   * const newRows = [
+   *   { id: 4, name: 'Alice', age: 35 },
+   *   { id: 5, name: 'Charlie', age: 45 }
+   * ];
+   * bodyAreaModel.setRows(newRows);
+   */
   setRows(e) {
     this.rows = e, this.filteredRows = [...e];
   }
+  /**
+   * Filters both the original rows and filtered rows arrays using the provided predicate function.
+   * Unlike `externalFilterChanged`, this method permanently modifies the original rows array.
+   * 
+   * @param {(row: T) => boolean} predict - A function that returns true for rows to keep and false for rows to filter out
+   * 
+   * @example
+   * // Remove all rows where age is less than 30
+   * bodyAreaModel.filterRowsByPredict(row => row.age >= 30);
+   */
   filterRowsByPredict(e) {
     this.rows = this.rows.filter(e), this.filteredRows = this.filteredRows.filter(e);
   }
   /**
-   * return row count of filtered rows
+   * Returns the number of rows in the filtered rows array.
+   * This is used to determine how many rows should be rendered in the table.
+   * 
+   * @returns {number} The number of rows in the filtered rows array
+   * 
+   * @example
+   * const rowCount = bodyAreaModel.getRowCount();
+   * console.log(`The table has ${rowCount} rows`);
    */
   getRowCount() {
     var e;
     return ((e = this.filteredRows) == null ? void 0 : e.length) ?? 0;
   }
+  /**
+   * Gets the value at the specified row and column indices.
+   * This method handles tree rows and nested properties.
+   * 
+   * @param {number} rowIndex - The index of the row
+   * @param {number} columnIndex - The index of the column
+   * @returns {any} The value at the specified cell, or an empty string if not found
+   * 
+   * @example
+   * // Get the value in the first row, second column
+   * const value = bodyAreaModel.getValueAt(0, 1);
+   * console.log(`The value is: ${value}`);
+   * 
+   * @example
+   * // Iterate through all cells in a row
+   * const rowIndex = 0;
+   * for (let colIndex = 0; colIndex < columnDefs.length; colIndex++) {
+   *   const value = bodyAreaModel.getValueAt(rowIndex, colIndex);
+   *   console.log(`Cell (${rowIndex}, ${colIndex}): ${value}`);
+   * }
+   */
   getValueAt(e, t) {
     const s = this.properties[t];
     let o = this.filteredRows[e];
@@ -1228,46 +1328,176 @@ class L extends ue {
   /**
    * Retrieves the filtered and sorted rows from the dataset.
    * These rows are used for rendering the table.
+   * Unlike `getAllRows()`, this method returns only the rows that match any applied filters.
    *
-   * @return {T[]} An array containing the filtered (and sorted) rows.
+   * @returns {T[]} An array containing the filtered (and sorted) rows
+   * 
+   * @example
+   * // Get all filtered rows
+   * const filteredRows = bodyAreaModel.getFilteredRows();
+   * 
+   * // Count rows that match a certain condition
+   * const adultsCount = filteredRows.filter(row => row.age >= 18).length;
    */
   getFilteredRows() {
     return this.filteredRows;
   }
+  /**
+   * Returns the original, unfiltered array of rows.
+   * This can be useful when you need to access all data regardless of any applied filters.
+   * 
+   * @returns {T[]} The original array of row objects
+   * 
+   * @example
+   * // Get all rows, including those filtered out
+   * const allRows = bodyAreaModel.getAllRows();
+   * 
+   * // Calculate average age across all rows
+   * const totalAge = allRows.reduce((sum, row) => sum + row.age, 0);
+   * const averageAge = totalAge / allRows.length;
+   */
   getAllRows() {
     return this.rows;
   }
   /**
    * Returns the first row from the filtered rows that matches the given criteria based on the provided predicate function.
+   * This method only searches within the filtered rows, not the original rows array.
    *
    * @param {Partial<T>} criteria - A partial object containing the search criteria
    * @param {(criteria: Partial<T>, row: T) => boolean} predicate - A function that takes the search criteria and a row,
    *        and returns true if the row matches the criteria
    * @returns {T | undefined} The first matching row, or undefined if no match is found
+   * 
+   * @example
+   * // Find a user by name in the filtered rows
+   * const criteria = { name: 'John' };
+   * const user = bodyAreaModel.findRowFromFilteredRowsByAllCriteria(
+   *   criteria,
+   *   (criteria, row) => row.name === criteria.name
+   * );
+   * 
+   * @example
+   * // Find a user by age range in the filtered rows
+   * const criteria = { minAge: 25, maxAge: 35 };
+   * const user = bodyAreaModel.findRowFromFilteredRowsByAllCriteria(
+   *   criteria,
+   *   (criteria, row) => row.age >= criteria.minAge && row.age <= criteria.maxAge
+   * );
    */
   findRowFromFilteredRowsByAllCriteria(e, t) {
     return this.getFilteredRows().find((s) => t(e, s));
   }
   /**
    * Searches through all rows to find a row that matches the given criteria based on the predicate function.
+   * This method searches within the original rows array, including rows that may have been filtered out.
    *
    * @param {Partial<T>} criteria - A partial object containing the search criteria
    * @param {(criteria: Partial<T>, row: T) => boolean} predicate - A function that takes the search criteria and a row,
    *        and returns true if the row matches the criteria
    * @returns {T | undefined} The first matching row from all rows, or undefined if no match is found
+   * 
+   * @example
+   * // Find a user by ID in all rows
+   * const criteria = { id: 42 };
+   * const user = bodyAreaModel.findRowFromAllRowsByAllCriteria(
+   *   criteria,
+   *   (criteria, row) => row.id === criteria.id
+   * );
+   * 
+   * @example
+   * // Find a user with a specific property value in all rows
+   * const criteria = { department: 'Engineering', role: 'Manager' };
+   * const user = bodyAreaModel.findRowFromAllRowsByAllCriteria(
+   *   criteria,
+   *   (criteria, row) => row.department === criteria.department && row.role === criteria.role
+   * );
    */
   findRowFromAllRowsByAllCriteria(e, t) {
     return this.getAllRows().find((s) => t(e, s));
   }
+  /**
+   * Returns the height of the row at the specified index.
+   * This implementation always returns the default row height.
+   * Override this method in subclasses to support variable row heights.
+   * 
+   * @param {number} _rowIndex - The index of the row (unused in this implementation)
+   * @returns {number} The height of the row in pixels
+   * 
+   * @example
+   * const rowHeight = bodyAreaModel.getRowHeight(0);
+   * console.log(`The first row has a height of ${rowHeight}px`);
+   */
   getRowHeight(e) {
     return this.defaultRowHeight;
   }
+  /**
+   * Returns the row object at the specified index from the filtered rows array.
+   * This method overrides the parent class implementation.
+   * 
+   * @param {number} rowIndex - The index of the row to retrieve
+   * @returns {any} The row object at the specified index, or undefined if the index is out of bounds
+   * 
+   * @example
+   * // Get the first row object
+   * const row = bodyAreaModel.getRowByIndex(0);
+   * console.log('First row:', row);
+   * 
+   * @example
+   * // Iterate through all rows
+   * for (let i = 0; i < bodyAreaModel.getRowCount(); i++) {
+   *   const row = bodyAreaModel.getRowByIndex(i);
+   *   console.log(`Row ${i}:`, row);
+   * }
+   */
   getRowByIndex(e) {
     return this.filteredRows[e];
   }
+  /**
+   * Applies an external filter function to the rows array.
+   * This method updates the filtered rows array without modifying the original rows array.
+   * 
+   * @param {FilterFunction<any>} predictFn - A function that returns true for rows to keep and false for rows to filter out
+   * 
+   * @example
+   * // Filter rows where age is greater than 30
+   * bodyAreaModel.externalFilterChanged(row => row.age > 30);
+   * 
+   * @example
+   * // Filter rows based on a search term
+   * const searchTerm = 'john';
+   * bodyAreaModel.externalFilterChanged(row => 
+   *   row.name.toLowerCase().includes(searchTerm.toLowerCase())
+   * );
+   * 
+   * @example
+   * // Clear all filters
+   * bodyAreaModel.externalFilterChanged(() => true);
+   */
   externalFilterChanged(e) {
     this.filteredRows = this.rows ? this.rows.filter(e) : [];
   }
+  /**
+   * Sorts the filtered rows based on the provided sort items.
+   * This method supports sorting by multiple columns with different sort directions.
+   * 
+   * @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
+   * 
+   * @example
+   * // Sort by age in ascending order
+   * bodyAreaModel.doSort([{ columnIndex: 2, sortState: 'asc' }]);
+   * 
+   * @example
+   * // Sort by name in descending order, then by age in ascending order
+   * bodyAreaModel.doSort([
+   *   { columnIndex: 1, sortState: 'desc' },
+   *   { columnIndex: 2, sortState: 'asc' }
+   * ]);
+   * 
+   * @example
+   * // Clear sorting
+   * bodyAreaModel.doSort([{ columnIndex: 0, sortState: 'none' }]);
+   */
   doSort(e) {
     for (const t of e) {
       const { columnIndex: s, sortState: o } = t, i = o === "asc" ? 1 : o === "desc" ? -1 : 0, r = this.properties[s];
@@ -1275,20 +1505,110 @@ class L extends ue {
     }
     return !0;
   }
+  /**
+   * Sorts the filtered rows using a custom comparator function.
+   * This method provides more flexibility than `doSort()` for complex sorting logic.
+   * 
+   * @param {(a: T, b: T) => number} compareFn - A function that compares two rows and returns a number:
+   *   - Negative if a should come before b
+   *   - Positive if a should come after b
+   *   - Zero if they are equivalent for sorting purposes
+   * 
+   * @example
+   * // Sort by name length
+   * bodyAreaModel.sort((a, b) => a.name.length - b.name.length);
+   * 
+   * @example
+   * // Sort by a computed value
+   * bodyAreaModel.sort((a, b) => {
+   *   const scoreA = a.wins * 3 + a.draws;
+   *   const scoreB = b.wins * 3 + b.draws;
+   *   return scoreB - scoreA; // Descending order
+   * });
+   */
   sort(e) {
     this.filteredRows = this.filteredRows.sort(e);
   }
+  /**
+   * Gets a value from an object using a property path.
+   * This method supports accessing nested properties using dot notation (e.g., 'person.name').
+   * 
+   * @param {T} t - The object to get the value from
+   * @param {string} property - The property path to access (e.g., 'name' or 'person.contact.email')
+   * @returns {any} The value at the specified property path, or undefined if not found
+   * 
+   * @example
+   * const user = { id: 1, name: 'John', contact: { email: 'john@example.com' } };
+   * 
+   * // Access simple property
+   * const name = bodyAreaModel.getValueByT(user, 'name');
+   * console.log(name); // 'John'
+   * 
+   * // Access nested property
+   * const email = bodyAreaModel.getValueByT(user, 'contact.email');
+   * console.log(email); // 'john@example.com'
+   */
   getValueByT(e, t) {
     if (e && t)
       return t.includes(".") ? this.getPropertyValue(e, t.split(".")) : e[t];
   }
+  /**
+   * Changes the order of columns by moving a column from one position to another.
+   * This method updates both the properties array and calls the parent class implementation.
+   * 
+   * @param {number} sourceColumnIndex - The index of the column to move
+   * @param {number} targetColumnIndex - The index where the column should be moved to
+   * 
+   * @example
+   * // Move the second column (index 1) to the fourth position (index 3)
+   * bodyAreaModel.changeColumnOrder(1, 3);
+   * 
+   * @example
+   * // Move the last column to the first position
+   * const lastIndex = bodyAreaModel.columnDefs.length - 1;
+   * bodyAreaModel.changeColumnOrder(lastIndex, 0);
+   */
   changeColumnOrder(e, t) {
     this.arrayMove(this.properties, e, t), super.changeColumnOrder(e, t);
   }
+  /**
+   * Gets the custom CSS classes that should be applied to a cell.
+   * This method extends the parent class implementation to add selection and focus classes.
+   * 
+   * @param {number} rowIndex - The index of the row
+   * @param {number} _columnIndex - The index of the column (unused in this implementation)
+   * @returns {string[]} An array of CSS class names to apply to the cell
+   * 
+   * @example
+   * // Get the CSS classes for a cell
+   * const classes = bodyAreaModel.getCustomClassesAt(1, 2);
+   * console.log('CSS classes:', classes);
+   * 
+   * @example
+   * // Apply the classes to a cell element
+   * const cellElement = document.createElement('div');
+   * const classes = bodyAreaModel.getCustomClassesAt(rowIndex, columnIndex);
+   * cellElement.classList.add(...classes);
+   */
   getCustomClassesAt(e, t) {
     const s = super.getCustomClassesAt(e, t);
     return this.getRowByIndex(e).selected && s.push(this.selectedRowClass), this._focusedRowIndex === e && s.push(this.focusedRowClass), s;
   }
+  /**
+   * Creates a comparator function for sorting rows based on a property and sort direction.
+   * This method supports custom sort comparators defined in column definitions.
+   * 
+   * @param {string} property - The property to sort by
+   * @param {number} f - The sort direction factor: 1 for ascending, -1 for descending, 0 for no sorting
+   * @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);
+   * 
+   * // Sort the rows using the comparator
+   * const sortedRows = [...bodyAreaModel.getFilteredRows()].sort(comparator);
+   */
   genericFlatTableSortComparator(e, t) {
     const s = this.columnDefs.find((o) => o.property === e);
     return (o, i) => {
@@ -1296,6 +1616,16 @@ class L extends ue {
       return s != null && s.sortComparator ? t * s.sortComparator(r, n, o, i, t) : this.sorterService.genericSortComparator(r, n, t);
     };
   }
+  /**
+   * Recursively gets a value from an object using an array of property names.
+   * This is a helper method used by `getValueByT` to access nested properties.
+   * 
+   * @param {any} o - The object to get the value from
+   * @param {string[]} props - An array of property names representing the path to the value
+   * @returns {any} The value at the specified property path, or undefined if not found
+   * 
+   * @private
+   */
   getPropertyValue(e, t) {
     const s = t.shift(), o = e[s];
     return o && t.length ? this.getPropertyValue(o, t) : o;
@@ -1306,41 +1636,302 @@ class st {
     this.tableScope = e;
   }
   /**
-   * Updates the cells in the table based on the provided events.
+   * Updates the cells in the table with the provided cell update events.
    *
-   * @param {TableCellUpdateEventIf[]} events - The array of events representing the updates to perform on the cells.
-   * @param {boolean} [repaintAll=false] - Optional parameter indicating whether to repaint all cells or not. Default value is false. If true, the full table will be rendered. If false, the table cell will be rendered immediately.
+   * This method allows you to update specific cells in the table without requiring a full table repaint,
+   * which can significantly improve performance when updating large tables frequently.
    *
-   * @return {void} - This method doesn't return anything.
+   * @param {TableCellUpdateEventIf[]} events - An array of cell update events, each defining a single cell update operation.
+   *        Each event must specify:
+   *        - area: The table area to update ('header', 'body', or 'footer')
+   *        - rowIndex: The row index of the cell to update
+   *        - columnIndex: The column index of the cell to update
+   *        - value: The new value to set for the cell
+   *        - cssClasses: Optional object mapping CSS class names to boolean values
+   *          (true to add the class, false to remove it)
+   *
+   * @param {boolean} [repaintAll=false] - Whether to repaint the entire table after updating cells.
+   *        - If true: All cells will be repainted after updating (slower but ensures visual consistency)
+   *        - If false: Only the modified cells will be repainted (faster, recommended for frequent updates)
+   *
+   * @returns {void}
+   *
+   * @example
+   * // Update a single cell with a new value and CSS classes
+   * tableApi.updateCells([{
+   *   area: 'body',
+   *   rowIndex: 3,
+   *   columnIndex: 2,
+   *   value: 42,
+   *   cssClasses: {
+   *     'highlight': true,   // Add 'highlight' class
+   *     'error': false       // Remove 'error' class if present
+   *   }
+   * }]);
+   *
+   * @example
+   * // Update multiple cells at once
+   * tableApi.updateCells([
+   *   {
+   *     area: 'body',
+   *     rowIndex: 1,
+   *     columnIndex: 1,
+   *     value: 'New Value 1',
+   *     cssClasses: { 'updated': true }
+   *   },
+   *   {
+   *     area: 'body',
+   *     rowIndex: 2,
+   *     columnIndex: 3,
+   *     value: 'New Value 2',
+   *     cssClasses: { 'updated': true }
+   *   }
+   * ]);
+   *
+   * @example
+   * // Update cells and repaint the entire table
+   * tableApi.updateCells([
+   *   { area: 'body', rowIndex: 0, columnIndex: 0, value: 'Hello', cssClasses: { 'bg-green-0': true } },
+   *   { area: 'body', rowIndex: 1, columnIndex: 1, value: 'World', cssClasses: { 'bg-red-0': true } }
+   * ], true);
+   *
+   * @example
+   * // High-performance animation example (update without full repaint)
+   * function animateCell() {
+   *   const value = Math.sin(Date.now() / 1000) * 50;
+   *   const cssClasses = {
+   *     'positive': value > 0,
+   *     'negative': value < 0
+   *   };
+   *
+   *   tableApi.updateCells([{
+   *     area: 'body',
+   *     rowIndex: 0,
+   *     columnIndex: 0,
+   *     value: Math.round(value),
+   *     cssClasses
+   *   }]);
+   *
+   *   requestAnimationFrame(animateCell);
+   * }
+   * animateCell();
    */
   updateCells(e, t = !1) {
     this.tableScope.updateCells(e, t);
   }
   /**
-   * Notifies that the external filter has changed.
+   * Notifies the table that an external filter has been changed and needs to be applied.
    *
-   * @return {void}
+   * This method is used when an external filter condition (defined by `tableOptions.externalFilterFunction`)
+   * has changed and the table needs to refresh its display to reflect the new filtering criteria.
+   *
+   * When called, this method:
+   * 1. Applies the external filter function to all rows
+   * 2. Clears the current selection (by default)
+   * 3. Scrolls to the top of the table
+   * 4. Recalculates table dimensions
+   * 5. Repaints the table to display only the filtered rows
+   *
+   * @example
+   * ```typescript
+   * // Define an external filter function in your table options
+   * const tableOptions = {
+   *   externalFilterFunction: (row: MyRowType) => {
+   *     // Return true to include the row, false to filter it out
+   *     return row.status === 'active';
+   *   }
+   * };
+   *
+   * // Initialize your table with these options
+   * const tableApi = new TableApi(tableScope);
+   *
+   * // Later, when filter criteria change (e.g., in a search input handler)
+   * function onFilterTextChanged() {
+   *   // Update the filter function if needed
+   *   tableOptions.externalFilterFunction = (row: MyRowType) => {
+   *     return row.name.includes(searchText);
+   *   };
+   *
+   *   // Apply the updated filter
+   *   tableApi.externalFilterChanged();
+   * }
+   * ```
+   *
+   * @returns {void}
+   * @see TableScope.externalFilterChanged
    */
   externalFilterChanged() {
     this.tableScope.externalFilterChanged();
   }
   /**
-   * Scrolls the table body to the specified pixel coordinates.
+   * Scrolls the table content to the specified pixel coordinates.
    *
-   * @param {number} px - The horizontal pixel coordinate to scroll to. Defaults to 0.
-   * @param {number} py - The vertical pixel coordinate to scroll to. Defaults to 0.
-   * @return {void}
+   * This method allows programmatic scrolling of the table viewport to exact pixel positions.
+   * It delegates the scrolling operation to the underlying TableScope instance.
+   *
+   * @param {number} px - The horizontal pixel coordinate to scroll to. Defaults to 0 (leftmost position).
+   * @param {number} py - The vertical pixel coordinate to scroll to. Defaults to 0 (topmost position).
+   * @returns {void}
+   *
+   * @example
+   * // Scroll to the top-left corner of the table
+   * tableApi.scrollToPixel(0, 0);
+   *
+   * @example
+   * // Scroll 200 pixels horizontally and 150 pixels vertically
+   * tableApi.scrollToPixel(200, 150);
+   *
+   * @example
+   * // Scroll only vertically, keeping the current horizontal position
+   * tableApi.scrollToPixel(undefined, 300);
+   *
+   * @example
+   * // Example in a component that needs precise scrolling control
+   * class TableScroller {
+   *   private tableApi: TableApi;
+   *
+   *   constructor(tableApi: TableApi) {
+   *     this.tableApi = tableApi;
+   *   }
+   *
+   *   scrollToPosition(x: number, y: number) {
+   *     // Scroll to exact pixel coordinates
+   *     this.tableApi.scrollToPixel(x, y);
+   *   }
+   *
+   *   scrollHalfway() {
+   *     const tableModel = this.tableApi.getTableModel();
+   *     const totalWidth = tableModel.getContentWidthInPixel();
+   *     const totalHeight = tableModel.getContentHeightInPixel();
+   *
+   *     // Scroll to the middle of the table content
+   *     this.tableApi.scrollToPixel(totalWidth / 2, totalHeight / 2);
+   *   }
+   * }
+   *
+   * @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
    */
   scrollToPixel(e = 0, t = 0) {
     this.tableScope.scrollToPixel(e, t);
   }
   /**
-   * Scrolls to the specified index in both horizontal and vertical directions.
+   * Scrolls the table to display the specified row and column indices at the top-left corner of the viewport.
    *
-   * @param {number} indexX - The index of the column to scroll to in the horizontal direction. Default is 0.
-   * @param {number} indexY - The index of the row to scroll to in the vertical direction. Default is 0.
+   * 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.
    *
-   * @return undefined
+   * @param {number} indexX - The horizontal index (column) to scroll to. Defaults to 0 (leftmost column).
+   * @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);
+   *
+   * @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
+   *   }
+   * }
+   *
+   * @see {@link scrollToPixel} - For scrolling to specific pixel coordinates
+   * @see {@link ensureRowIsVisible} - For scrolling to make a specific row visible
    */
   scrollToIndex(e = 0, t = 0) {
     this.tableScope.scrollToIndex(e, t);
@@ -1401,19 +1992,71 @@ class st {
   /**
    * Repaints the table.
    *
-   * This method calls the repaint method of the tableScope object
-   * to update and redraw the table based on the latest data.
+   * This method refreshes the visual representation of the table by delegating to the
+   * tableScope's repaint functionality. Use this method whenever the table's visual state
+   * needs to be updated after data changes, selection changes, or any modifications that
+   * affect the rendered output.
+   *
+   * Repainting the table ensures that all visible cells, rows, and styling reflect the
+   * current state of the underlying data model and configuration settings.
+   *
+   * @example
+   * // Update data and repaint the table
+   * const tableApi = new TableApi(tableScope);
+   * tableApi.setRows(newData);
+   * tableApi.repaint();
+   *
+   * @example
+   * // Update selection and repaint to show the visual change
+   * tableApi.getSelectionModel().selectCell(2, 3);
+   * tableApi.repaint();
+   *
+   * @example
+   * // After changing column visibility, repaint to reflect changes
+   * tableApi.setColumnVisible(0, false);
+   * tableApi.repaint();
+   *
+   * @returns {void}
    */
   repaint() {
     this.tableScope.repaint();
   }
   /**
-   * Repaints the table scope with hard repaint.
-   * Repaints the UI by resetting the size of the wrapper div,
-   * adjusting the containers and rows, and performing additional adjustments
-   * after scrolling.
+   * Performs a complete repaint of the table by triggering a hard repaint on the underlying table scope.
    *
-   * @return {void}
+   * A hard repaint is more thorough than a regular repaint and performs the following operations:
+   * - Recalculates the height and padding of the table model
+   * - Resets the size of the wrapper div elements
+   * - Adjusts containers and rows positioning
+   * - Makes additional adjustments after scrolling
+   *
+   * Use this method when regular repaint isn't sufficient, such as when:
+   * - Table dimensions have significantly changed
+   * - The structure of data has been modified (rows/columns added or removed)
+   * - The table layout needs complete recalculation
+   * - After major DOM changes affecting the table's container
+   *
+   * @example
+   * // Example 1: Basic usage
+   * tableApi.repaintHard();
+   *
+   * @example
+   * // Example 2: Using after major data changes
+   * tableApi.setRows(newDataSet);
+   * tableApi.repaintHard();
+   *
+   * @example
+   * // Example 3: Using after resizing a container
+   * window.addEventListener('resize', () => {
+   *   tableApi.repaintHard();
+   * });
+   *
+   * @example
+   * // Example 4: Using after changing column visibility
+   * tableApi.setColumnVisible(2, false);
+   * tableApi.repaintHard();
+   *
+   * @returns {void} This method doesn't return a value
    */
   repaintHard() {
     this.tableScope.repaintHard();
@@ -1429,8 +2072,30 @@ class st {
     this.tableScope.recalcColumnWidths(e);
   }
   /**
-   * Clears the current selection of the table.
-   * The table will be rendered automatically.
+   * Clears the current selection in the table.
+   *
+   * This method removes any selected cells, rows, or columns in the table.
+   * It provides a convenient way to programmatically clear all selections in the table
+   * without having to access the underlying selection model directly.
+   *
+   * When called, this method delegates to the table scope's clearSelection method with
+   * a parameter value of true, which ensures the table is automatically repainted after
+   * the selection is cleared.
+   *
+   * @example
+   * // Clear all selections in the table
+   * 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}
    */
@@ -1438,12 +2103,31 @@ class st {
     this.tableScope.clearSelection(!0);
   }
   /**
-   * Sets the selection model for the table scope.
+   * Sets the selection model for the table.
    *
-   * @param {SelectionModel} sm - The selection model to be set.
-   * @param {boolean} [repaint=true] - Indicates whether the table should be repainted after setting the selection model. Default value is true.
+   * This method allows you to replace the current selection model with a new one,
+   * which controls how cells, rows, or columns can be selected in the table.
    *
-   * @return {void}
+   * @param {SelectionModel} sm - The new selection model to be set. This model defines
+   *                              the selection behavior including selection type (none, cell, row, column),
+   *                              selection mode (single, multi), and manages the selected ranges.
+   * @param {boolean} [repaint=true] - Whether to repaint the table after changing the selection model.
+   *                                   Default is true, which immediately reflects the change visually.
+   *                                   Set to false if you want to avoid immediate repainting.
+   *
+   * @example
+   * // Create a new selection model with row selection and multi-select mode
+   * const selectionModel = new SelectionModel("row", "multi");
+   *
+   * // Set the new selection model and repaint the table
+   * tableApi.setSelectionModel(selectionModel);
+   *
+   * // Set a selection model without repainting (if you plan to make more changes)
+   * tableApi.setSelectionModel(selectionModel, false);
+   * // ... make other changes ...
+   * tableApi.repaint(); // Now repaint once
+   *
+   * @returns {void}
    */
   setSelectionModel(e, t = !0) {
     this.tableScope.setSelectionModel(e, t);
@@ -1459,9 +2143,36 @@ class st {
     this.tableScope.onActionTriggered(e);
   }
   /**
-   * Retrieves the mapping of shortcuts to corresponding action in the current table scope.
+   * Retrieves the shortcut action mapping from the table's shortcut service.
    *
-   * @return {ShortcutActionIdMapping} The mapping of shortcuts to corresponding action.
+   * This method provides access to the keyboard shortcut configuration that defines
+   * which keys trigger specific actions in the table. The mapping contains key-value
+   * pairs where:
+   * - Keys are string representations of keyboard shortcuts (e.g., "ctrl+c", "shift+arrow_down")
+   * - Values are ActionId values representing the corresponding table actions
+   *
+   * This mapping can be useful for:
+   * - Displaying available shortcuts to users
+   * - Creating custom shortcut documentation
+   * - Dynamically checking which actions are available via keyboard
+   * - Extending or integrating with the table's shortcut system
+   *
+   * @returns {ShortcutActionIdMapping} An object mapping shortcut key combinations to their corresponding action IDs.
+   *          For example: { "ctrl+c": "COPY_2_CLIPBOARD", "arrow_down": "NAVIGATE_DOWN" }
+   *
+   * @example
+   * // Get all available shortcuts in the table
+   * const shortcuts = tableApi.getShortcutActionMapping();
+   *
+   * // Check if a specific shortcut exists
+   * if (shortcuts["ctrl+c"]) {
+   *   console.log("Copy shortcut is available with action:", shortcuts["ctrl+c"]);
+   * }
+   *
+   * // Display available shortcuts in the UI
+   * Object.entries(shortcuts).forEach(([key, actionId]) => {
+   *   console.log(`${key}: ${actionId}`);
+   * });
    */
   getShortcutActionMapping() {
     return this.tableScope.shortcutService.getShortcutActionMapping();
@@ -1469,7 +2180,35 @@ class st {
   /**
    * Copies the selected data from the table to the clipboard.
    *
-   * @return {Promise<string>} - A promise that resolves with the copied data as a string.
+   * This method leverages the copyService to extract and copy the currently selected data
+   * from the table. It works with the current selection state and focus position to determine
+   * what content should be copied.
+   *
+   * 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.
+   *
+   * @example
+   * // Copy the currently selected data to clipboard
+   * tableApi.copyToClipboard().then(content => {
+   *   console.log('Copied to clipboard:', content);
+   * });
+   *
+   * // Using with a button click handler
+   * function onCopyButtonClick() {
+   *   if (tableApi) {
+   *     tableApi.copyToClipboard()
+   *       .then(content => {
+   *         console.log('Successfully copied data to clipboard');
+   *         // Optionally do something with the copied content
+   *       })
+   *       .catch(error => {
+   *         console.error('Failed to copy to clipboard:', error);
+   *       });
+   *   }
+   * }
+   *
+   * @returns {Promise<string>} A promise that resolves with the copied data as a string.
+   *   The string contains the tab-separated representation of the selected table data.
    */
   copyToClipboard() {
     return this.tableScope.copyService.copyToClipboard(
@@ -1479,11 +2218,33 @@ class st {
     );
   }
   /**
-   * Generates and downloads an Excel file based on the table data.
+   * Downloads the current table data as an Excel file.
+   *
+   * This method extracts all visible data from the table (including header, body, and footer areas),
+   * converts it into a matrix format, and triggers a download of an Excel file containing this data.
    *
-   * @param {string} fileName - The name of the Excel file to be downloaded. Defaults to 'table.xlsx'.
-   * @param {string} author - The author of the Excel file. If not provided, it will remain empty.
-   * @return {void} No return value. Initiates a file download of the Excel document.
+   * The method works by:
+   * 1. Creating an empty matrix to hold all table data
+   * 2. Iterating through each area of the table (header, body, footer)
+   * 3. For each area, iterating through all rows and columns to extract cell values
+   * 4. Passing the complete data matrix to the Excel service for file generation and download
+   *
+   * @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
+   *
+   * @example
+   * // Download table data with default filename
+   * tableApi.downloadExcel();
+   *
+   * @example
+   * // Download table data with custom filename and author
+   * tableApi.downloadExcel('sales-report.xlsx', 'John Doe');
+   *
+   * @example
+   * // Download table data with custom filename only
+   * tableApi.downloadExcel('quarterly-data.xlsx');
    */
   downloadExcel(e = "table.xlsx", t = "") {
     const s = [], o = this.tableScope.tableModel.getColumnCount(), i = ["header", "body", "footer"];
@@ -1499,18 +2260,66 @@ class st {
     return this.tableScope.excelService.downloadExcel(s, e, t);
   }
   /**
-   * Retrieves the current scope of the table.
+   * Returns the TableScope instance associated with this TableApi.
+   *
+   * The TableScope provides access to the core functionality and internal state of the table component,
+   * including rendering, event handling, selection, and other low-level operations.
    *
-   * @returns {TableScope} The current scope of the table.
+   * This method is useful for advanced customization scenarios where you need direct access
+   * to the table's internal structure and behaviors.
+   *
+   * @returns {TableScope} The TableScope instance that controls this table component
+   *
+   * @example
+   * // Access the TableScope to perform a custom operation
+   * const tableApi = new TableApi(myTableScope);
+   * const tableScope = tableApi.getTableScope();
+   *
+   * // Example: Manually trigger a context menu at a specific location
+   * const mouseEvent = new MouseEvent('contextmenu');
+   * const geMouseEvent = tableScope.createGeMouseEvent(mouseEvent);
+   * tableScope.contextmenu(geMouseEvent);
    */
   getTableScope() {
     return this.tableScope;
   }
   /**
-   * Retrieves the selection model of the table.
+   * Returns the current selection model for the table.
+   *
+   * The selection model manages cell selection state, including single cells, ranges, rows, and columns.
+   * This method provides access to the selection model instance, allowing operations like:
+   * - Checking if cells are selected
+   * - Getting selection ranges
+   * - Modifying selections
+   * - Adding/removing selection event listeners
+   *
+   * @returns {SelectionModelIf | undefined} The current selection model if available, otherwise undefined.
    *
-   * @return {SelectionModelIf | undefined} The selection model of the table,
-   * or undefined if no selection model is available.
+   * @example
+   * // Get the selection model
+   * const selectionModel = tableApi.getSelectionModel();
+   *
+   * // Check if a specific cell is selected
+   * if (selectionModel?.isSelected(3, 2)) {
+   *   console.log('Cell at row 3, column 2 is selected');
+   * }
+   *
+   * // Get all selected ranges
+   * const ranges = selectionModel?.getRanges();
+   * console.log('Selected ranges:', ranges);
+   *
+   * // Clear all selections
+   * selectionModel?.clear();
+   *
+   * // Toggle selection of a cell
+   * selectionModel?.togglePoint(5, 1);
+   *
+   * // Add a selection change listener
+   * selectionModel?.addEventSelectionChangedListener({
+   *   selectionChanged: () => {
+   *     console.log('Selection has changed');
+   *   }
+   * });
    */
   getSelectionModel() {
     return this.tableScope.selectionModel();
@@ -1981,28 +2790,191 @@ class st {
    * const tableApi = new TableApi(tableScope);
    * const firstVisibleIndex = tableApi.getFirstVisibleRowIndex();
    *
-   * // Use the index for scroll position calculations
-   * if (firstVisibleIndex >= 0) {
-   *   // Perform operations with the first visible row
-   *   console.log(`First visible row index: ${firstVisibleIndex}`);
+   * // Use the index for scroll position calculations
+   * if (firstVisibleIndex >= 0) {
+   *   // Perform operations with the first visible row
+   *   console.log(`First visible row index: ${firstVisibleIndex}`);
+   * }
+   * ```
+   */
+  getFirstVisibleRowIndex() {
+    return this.tableScope.getFirstVisibleRowIndex();
+  }
+  /**
+   * Retrieves the index of the first fully visible row in the table's viewport.
+   *
+   * A row is considered "fully visible" when it's completely within the visible area of the table.
+   * This differs from the regular "visible" row, which might be partially visible at the edges of the viewport.
+   *
+   * This method is useful for:
+   * - Determining which rows are completely in view for operations that require full visibility
+   * - Implementing pagination or virtualization logic that needs to know complete row visibility
+   * - Supporting keyboard navigation that should skip partially visible rows
+   *
+   * @returns {number} The index of the first fully visible row, or -1 if no rows are fully visible
+   *
+   * @example
+   * // Get the first fully visible row index
+   * const firstFullVisibleRow = tableApi.getFirstFullVisibleRowIndex();
+   *
+   * // Check if a specific row is fully visible
+   * const isRowFullyVisible = (rowIndex) => {
+   *   const firstFullVisible = tableApi.getFirstFullVisibleRowIndex();
+   *   const lastFullVisible = tableApi.getLastFullVisibleRowIndex();
+   *   return rowIndex >= firstFullVisible && rowIndex <= lastFullVisible;
+   * };
+   */
+  getFirstFullVisibleRowIndex() {
+    return this.tableScope.getFirstFullVisibleRowIndex();
+  }
+  /**
+   * Returns the index of the last row that is visible in the table's viewport.
+   *
+   * This method retrieves the last visible row index from the table scope, which keeps
+   * track of which rows are currently visible as the user scrolls through the table.
+   *
+   * This can be useful for:
+   * - Implementing virtualized scrolling optimizations
+   * - Determining if specific rows are currently in view
+   * - Implementing features that need to know the visible range of rows
+   *
+   * @returns {number} The index of the last visible row in the table viewport
+   *
+   * @example
+   * // Check if a specific row is currently visible in the viewport
+   * const lastVisibleIndex = tableApi.getLastVisibleRowIndex();
+   * const firstVisibleIndex = tableApi.getFirstVisibleRowIndex();
+   * const isRowVisible = rowIndex >= firstVisibleIndex && rowIndex <= lastVisibleIndex;
+   *
+   * @example
+   * // Get the range of visible rows
+   * const visibleRowsRange = {
+   *   first: tableApi.getFirstVisibleRowIndex(),
+   *   last: tableApi.getLastVisibleRowIndex()
+   * };
+   * console.log(`Visible rows: ${visibleRowsRange.first} to ${visibleRowsRange.last}`);
+   */
+  getLastVisibleRowIndex() {
+    return this.tableScope.getLastVisibleRowIndex();
+  }
+  /**
+   * Returns the index of the last fully visible row in the table's viewport.
+   *
+   * This method retrieves the last row that is completely visible within the current
+   * viewport of the table. A row is considered "fully visible" when its entire height
+   * is visible without any portion being cut off by the viewport boundaries.
+   *
+   * The distinction between "visible" and "fully visible" is important when scrolling:
+   * - A row can be partially visible (some portion is in view)
+   * - A row can be fully visible (the entire row is in view)
+   *
+   * @returns {number} The index of the last fully visible row in the table.
+   * If no row is fully visible or the table is empty, the method might return -1.
+   *
+   * @example
+   * ```typescript
+   * // Get the index of the last fully visible row
+   * const lastVisibleRowIndex = tableApi.getLastFullVisibleRowIndex();
+   *
+   * // Use this information to determine if a specific row is fully visible
+   * const isRowFullyVisible = rowIndex <= lastVisibleRowIndex && rowIndex >= tableApi.getFirstFullVisibleRowIndex();
+   *
+   * // Can be used with scrolling operations to ensure certain rows are visible
+   * if (rowIndex > lastVisibleRowIndex) {
+   *   tableApi.ensureRowIsVisible(rowIndex);
    * }
    * ```
    */
-  getFirstVisibleRowIndex() {
-    return this.tableScope.getFirstVisibleRowIndex();
-  }
-  getFirstFullVisibleRowIndex() {
-    return this.tableScope.getFirstFullVisibleRowIndex();
-  }
-  getLastVisibleRowIndex() {
-    return this.tableScope.getLastVisibleRowIndex();
-  }
   getLastFullVisibleRowIndex() {
     return this.tableScope.getLastFullVisibleRowIndex();
   }
+  /**
+   * Checks whether logging is currently active for the table component.
+   *
+   * This method returns the current state of logging for the table. When logging is active,
+   * the table outputs detailed information about its operations to the console, including:
+   *
+   * - Rendering processes and lifecycle events
+   * - Data modifications and updates
+   * - Event handling and user interactions
+   * - Performance metrics and state changes
+   *
+   * Logging can be toggled using the `setLoggingActive(boolean)` method.
+   *
+   * @returns {boolean} True if logging is currently enabled, false otherwise.
+   *
+   * @example
+   * // Check if logging is enabled
+   * if (tableApi.isLoggingActive()) {
+   *   console.log("Table logging is currently active");
+   * }
+   *
+   * // Conditionally enable logging only if it's not already active
+   * if (!tableApi.isLoggingActive()) {
+   *   tableApi.setLoggingActive(true);
+   *
+   *   // Perform operations that need debugging
+   *   tableApi.updateCells([
+   *     {
+   *       area: "body",
+   *       rowIndex: 2,
+   *       columnIndex: 3,
+   *       value: "New Value",
+   *       cssClasses: { "highlight": true }
+   *     }
+   *   ]);
+   *
+   *   // Run some additional operations...
+   *
+   *   // Disable logging when finished
+   *   tableApi.setLoggingActive(false);
+   * }
+   */
   setLoggingActive(e) {
     this.tableScope.loggingActive = e;
   }
+  /**
+   * Checks whether logging is currently active for the table component.
+   *
+   * This method returns the current state of logging for the table. When logging is active,
+   * the table outputs detailed information about its operations to the console, including:
+   *
+   * - Rendering processes and lifecycle events
+   * - Data modifications and updates
+   * - Event handling and user interactions
+   * - Performance metrics and state changes
+   *
+   * Logging can be toggled using the `setLoggingActive(boolean)` method.
+   *
+   * @returns {boolean} True if logging is currently enabled, false otherwise.
+   *
+   * @example
+   * // Check if logging is enabled
+   * if (tableApi.isLoggingActive()) {
+   *   console.log("Table logging is currently active");
+   * }
+   *
+   * // Conditionally enable logging only if it's not already active
+   * if (!tableApi.isLoggingActive()) {
+   *   tableApi.setLoggingActive(true);
+   *
+   *   // Perform operations that need debugging
+   *   tableApi.updateCells([
+   *     {
+   *       area: "body",
+   *       rowIndex: 2,
+   *       columnIndex: 3,
+   *       value: "New Value",
+   *       cssClasses: { "highlight": true }
+   *     }
+   *   ]);
+   *
+   *   // Run some additional operations...
+   *
+   *   // Disable logging when finished
+   *   tableApi.setLoggingActive(false);
+   * }
+   */
   isLoggingActive() {
     return this.tableScope.loggingActive;
   }
@@ -5471,6 +6443,35 @@ class oe {
   }
 }
 class Te extends L {
+  /**
+   * Creates an instance of AreaModelObjectArrayWithColumndefs.
+   *
+   * @param {AreaIdent} areaIdent - Identifies which area of the table this model represents ('header', 'body', or 'footer')
+   * @param {T[]} rows - The array of objects that represent the rows in this area
+   * @param {ColumnDefIf[]} columnDefs - Definitions for the columns in this area (required parameter)
+   * @param {number} defaultRowHeight - The default height for rows in this area (in pixels)
+   * @param {string} [selectedRowClass='ge-selected-row'] - CSS class to apply to selected rows
+   * @param {string} [focusedRowClass='ge-focused-row'] - CSS class to apply to the focused row
+   *
+   * @example
+   * const rows = [
+   *   { id: 1, name: 'John', age: 30 },
+   *   { 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 bodyAreaModel = new AreaModelObjectArrayWithColumndefs(
+   *   'body',
+   *   rows,
+   *   columnDefs,
+   *   30
+   * );
+   */
   constructor(e, t, s, o, i = "ge-selected-row", r = "ge-focused-row") {
     super(
       e,
@@ -6231,70 +7232,620 @@ class Os {
   constructor() {
     this.areaIdent = "body", this.rowSelectionModel = void 0;
   }
+  /**
+   * Changes the order of columns by moving a column from one position to another.
+   * This method is called when the user drags a column to a new position.
+   * The base implementation does nothing and should be overridden by subclasses
+   * that support column reordering.
+   * 
+   * @param {number} _sourceColumnIndex - The index of the column to move
+   * @param {number} _targetColumnIndex - The index where the column should be moved to
+   * @returns {void}
+   * 
+   * @example
+   * // Override in a subclass to implement column reordering
+   * changeColumnOrder(sourceColumnIndex: number, targetColumnIndex: number): void {
+   *   // Move the column in the internal data structure
+   *   this.arrayMove(this.columns, sourceColumnIndex, targetColumnIndex);
+   * }
+   */
   changeColumnOrder(e, t) {
   }
+  /**
+   * Sorts the rows in this area based on the provided sort items.
+   * This method is called when the user clicks on a sortable column header.
+   * The base implementation returns false (no sorting performed) and should be
+   * overridden by subclasses that support sorting.
+   * 
+   * @param {SortItem[]} _sortItems - An array of sort items, each containing a column index and sort direction
+   * @returns {boolean} True if sorting was performed, false otherwise
+   * 
+   * @example
+   * // Override in a subclass to implement sorting
+   * doSort(sortItems: SortItem[]): boolean {
+   *   if (!sortItems.length) return false;
+   *   
+   *   // Apply sorting to the rows
+   *   this.rows.sort((a, b) => {
+   *     const { columnIndex, sortState } = sortItems[0];
+   *     const valueA = this.getValueAt(this.rows.indexOf(a), columnIndex);
+   *     const valueB = this.getValueAt(this.rows.indexOf(b), columnIndex);
+   *     
+   *     const direction = sortState === 'asc' ? 1 : -1;
+   *     if (valueA < valueB) return -1 * direction;
+   *     if (valueA > valueB) return 1 * direction;
+   *     return 0;
+   *   });
+   *   
+   *   return true;
+   * }
+   */
   doSort(e) {
     return !1;
   }
+  /**
+   * Sorts the rows in this area using a custom comparator function.
+   * This method provides more flexibility than doSort for complex sorting logic.
+   * The base implementation does nothing and should be overridden by subclasses
+   * that support custom sorting.
+   * 
+   * @param {(a: any, b: any) => number} [_compareFn] - A function that compares two rows and returns a number:
+   *   - Negative if a should come before b
+   *   - Positive if a should come after b
+   *   - Zero if they are equivalent for sorting purposes
+   * @returns {void}
+   * 
+   * @example
+   * // Override in a subclass to implement custom sorting
+   * sort(compareFn?: (a: any, b: any) => number): void {
+   *   if (!compareFn) return;
+   *   
+   *   // Apply the custom sort function
+   *   this.rows.sort(compareFn);
+   * }
+   */
   sort(e) {
   }
+  /**
+   * Applies a filter function to the rows in this area.
+   * This method is called when a filter is applied to the table.
+   * The base implementation does nothing and should be overridden by subclasses
+   * that support filtering.
+   * 
+   * @param {FilterFunction<T>} _predictFn - A function that takes a row and returns true if the row should be visible
+   * @returns {void}
+   * 
+   * @example
+   * // Override in a subclass to implement filtering
+   * externalFilterChanged<T>(predictFn: FilterFunction<T>): void {
+   *   // Apply the filter to the rows
+   *   this.filteredRows = this.rows.filter(predictFn);
+   * }
+   */
   externalFilterChanged(e) {
   }
+  /**
+   * Returns a cell renderer for the cell at the specified row and column indices.
+   * A cell renderer is responsible for rendering the cell content in a custom way.
+   * The base implementation returns undefined (default rendering) and should be
+   * overridden by subclasses that support custom cell rendering.
+   * 
+   * @param {number} _rowIndex - The index of the row
+   * @param {number} _columnIndex - The index of the column
+   * @returns {CellRendererIf | undefined} A cell renderer instance, or undefined for default rendering
+   * 
+   * @example
+   * // Override in a subclass to provide custom cell renderers
+   * getCellRenderer(rowIndex: number, columnIndex: number): CellRendererIf | undefined {
+   *   // Get renderer from column definition
+   *   const columnDef = this.columnDefs[columnIndex];
+   *   return columnDef?.rendererMap?.[this.areaIdent];
+   * }
+   */
   getCellRenderer(e, t) {
   }
+  /**
+   * Returns the column span value for the cell at the specified row and column indices.
+   * A colspan value of N means the cell spans N columns horizontally.
+   * The base implementation returns 0 (no spanning) and should be overridden by
+   * subclasses that support column spanning.
+   * 
+   * @param {number} _rowIndex - The index of the row
+   * @param {number} _columnIndex - The index of the column
+   * @returns {number} The colspan value (number of columns the cell spans)
+   * 
+   * @example
+   * // Override in a subclass to implement column spanning
+   * getColspanAt(rowIndex: number, columnIndex: number): number {
+   *   // Special case: first row, first column spans 3 columns
+   *   if (rowIndex === 0 && columnIndex === 0) return 3;
+   *   
+   *   // No spanning for other cells
+   *   return 1;
+   * }
+   */
   getColspanAt(e, t) {
     return 0;
   }
+  /**
+   * Returns an array of CSS class names to apply to the cell at the specified row and column indices.
+   * This method allows for custom styling of individual cells.
+   * The base implementation returns an empty array (no custom classes) and should be
+   * overridden by subclasses that support custom cell styling.
+   * 
+   * @param {number} _rowIndex - The index of the row
+   * @param {number} _columnIndex - The index of the column
+   * @returns {string[]} An array of CSS class names
+   * 
+   * @example
+   * // Override in a subclass to implement custom cell classes
+   * getCustomClassesAt(rowIndex: number, columnIndex: number): string[] {
+   *   const classes: string[] = [];
+   *   
+   *   // Add classes based on row index
+   *   if (rowIndex % 2 === 0) {
+   *     classes.push('even-row');
+   *   } else {
+   *     classes.push('odd-row');
+   *   }
+   *   
+   *   // Add classes based on cell value
+   *   const value = this.getValueAt(rowIndex, columnIndex);
+   *   if (typeof value === 'number' && value < 0) {
+   *     classes.push('negative-value');
+   *   }
+   *   
+   *   return classes;
+   * }
+   */
   getCustomClassesAt(e, t) {
     return [];
   }
+  /**
+   * Returns an object containing CSS style properties to apply to the cell at the specified row and column indices.
+   * This method allows for inline styling of individual cells.
+   * The base implementation returns undefined (no custom styles) and should be
+   * overridden by subclasses that support custom cell styling.
+   * 
+   * @param {number} _rowIndex - The index of the row
+   * @param {number} _columnIndex - The index of the column
+   * @returns {{ [key: string]: string } | undefined} An object with CSS style properties, or undefined if no custom styles
+   * 
+   * @example
+   * // Override in a subclass to implement custom cell styles
+   * getCustomStyleAt(rowIndex: number, columnIndex: number): { [key: string]: string } | undefined {
+   *   // Apply background color based on value
+   *   const value = this.getValueAt(rowIndex, columnIndex);
+   *   
+   *   if (typeof value === 'number') {
+   *     // Color gradient based on value
+   *     if (value < 0) {
+   *       return { 'background-color': `rgba(255, 0, 0, ${Math.min(Math.abs(value) / 100, 0.5)})` };
+   *     } else if (value > 0) {
+   *       return { 'background-color': `rgba(0, 255, 0, ${Math.min(value / 100, 0.5)})` };
+   *     }
+   *   }
+   *   
+   *   return undefined; // No custom styles
+   * }
+   */
   getCustomStyleAt(e, t) {
   }
+  /**
+   * Returns the maximum colspan value that can occur in this area model.
+   * This value is used to optimize rendering performance.
+   * The base implementation returns 0 (no colspans) and should be overridden by
+   * subclasses that support column spanning.
+   * 
+   * @returns {number} The maximum possible colspan value in this area
+   * 
+   * @example
+   * // Override in a subclass to specify maximum colspan
+   * getMaxColspan(): number {
+   *   // If the model has colspans, return the maximum possible value
+   *   return 3; // If some cells span up to 3 columns
+   * }
+   */
   getMaxColspan() {
     return 0;
   }
+  /**
+   * Returns the maximum rowspan value that can occur in this area model.
+   * This value is used to optimize rendering performance.
+   * The base implementation returns 0 (no rowspans) and should be overridden by
+   * subclasses that support row spanning.
+   * 
+   * @returns {number} The maximum possible rowspan value in this area
+   * 
+   * @example
+   * // Override in a subclass to specify maximum rowspan
+   * getMaxRowspan(): number {
+   *   // If the model has rowspans, return the maximum possible value
+   *   return 2; // If some cells span up to 2 rows
+   * }
+   */
   getMaxRowspan() {
     return 0;
   }
+  /**
+   * Returns the row object at the specified index.
+   * This method provides access to the underlying data structure.
+   * The base implementation returns undefined and should be overridden by
+   * subclasses that have a row-based data structure.
+   * 
+   * @param {number} _rowIndex - The index of the row
+   * @returns {any} The row object, or undefined if the row doesn't exist
+   * 
+   * @example
+   * // Override in a subclass to provide access to row data
+   * getRowByIndex(rowIndex: number): any {
+   *   if (rowIndex < 0 || rowIndex >= this.data.length) return undefined;
+   *   return this.data[rowIndex];
+   * }
+   */
   getRowByIndex(e) {
   }
+  /**
+   * Returns the number of rows in this area.
+   * This is a fundamental method that determines the vertical size of the area.
+   * The base implementation returns 0 (no rows) and should be overridden by
+   * all subclasses.
+   * 
+   * @returns {number} The number of rows in the area
+   * 
+   * @example
+   * // Override in a subclass to provide the row count
+   * getRowCount(): number {
+   *   return this.data.length;
+   * }
+   */
   getRowCount() {
     return 0;
   }
+  /**
+   * Returns the height of the row at the specified index, in pixels.
+   * This method allows for variable row heights in the table.
+   * The base implementation returns 0 and should be overridden by
+   * all subclasses.
+   * 
+   * @param {number} _rowIndex - The index of the row
+   * @returns {number} The height of the row in pixels
+   * 
+   * @example
+   * // Override in a subclass to provide fixed row heights
+   * getRowHeight(rowIndex: number): number {
+   *   return 30; // 30px for all rows
+   * }
+   * 
+   * @example
+   * // Override in a subclass to provide variable row heights
+   * getRowHeight(rowIndex: number): number {
+   *   // First row is taller
+   *   if (rowIndex === 0) return 50;
+   *   
+   *   // Default height for other rows
+   *   return 30;
+   * }
+   */
   getRowHeight(e) {
     return 0;
   }
+  /**
+   * Returns the row span value for the cell at the specified row and column indices.
+   * A rowspan value of N means the cell spans N rows vertically.
+   * The base implementation returns 0 (no spanning) and should be overridden by
+   * subclasses that support row spanning.
+   * 
+   * @param {number} _rowIndex - The index of the row
+   * @param {number} _columnIndex - The index of the column
+   * @returns {number} The rowspan value (number of rows the cell spans)
+   * 
+   * @example
+   * // Override in a subclass to implement row spanning
+   * getRowspanAt(rowIndex: number, columnIndex: number): number {
+   *   // Special case: first column spans 2 rows at the beginning
+   *   if (columnIndex === 0 && rowIndex % 2 === 0) return 2;
+   *   
+   *   // No spanning for other cells
+   *   return 1;
+   * }
+   */
   getRowspanAt(e, t) {
     return 0;
   }
+  /**
+   * Returns the tooltip text for the cell at the specified row and column indices.
+   * This tooltip will be displayed when the user hovers over the cell.
+   * The base implementation returns undefined (no tooltip) and should be overridden by
+   * subclasses that support tooltips.
+   * 
+   * @param {number} _rowIndex - The index of the row
+   * @param {number} _columnIndex - The index of the column
+   * @returns {any} The tooltip content (usually a string)
+   * 
+   * @example
+   * // Override in a subclass to provide tooltips
+   * getTooltipAt(rowIndex: number, columnIndex: number): any {
+   *   // Use the cell value as the tooltip
+   *   return this.getValueAt(rowIndex, columnIndex);
+   *   
+   *   // Or provide a more detailed tooltip
+   *   // const value = this.getValueAt(rowIndex, columnIndex);
+   *   // return `Value: ${value}\nRow: ${rowIndex}\nColumn: ${columnIndex}`;
+   * }
+   */
   getTooltipAt(e, t) {
   }
+  /**
+   * 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
+   * the actual data to be displayed in each cell.
+   * The base implementation returns undefined and should be overridden by
+   * all subclasses.
+   * 
+   * @param {number} _rowIndex - The index of the row
+   * @param {number} _columnIndex - The index of the column
+   * @returns {any} The value at the specified cell
+   * 
+   * @example
+   * // Override in a subclass for a 2D array model
+   * getValueAt(rowIndex: number, columnIndex: number): any {
+   *   if (rowIndex < 0 || rowIndex >= this.data.length) return undefined;
+   *   const row = this.data[rowIndex];
+   *   if (columnIndex < 0 || columnIndex >= row.length) return undefined;
+   *   return row[columnIndex];
+   * }
+   * 
+   * @example
+   * // Override in a subclass for an object array model
+   * getValueAt(rowIndex: number, columnIndex: number): any {
+   *   const row = this.getRowByIndex(rowIndex);
+   *   if (!row) return undefined;
+   *   
+   *   const property = this.columnDefs[columnIndex].property;
+   *   return row[property];
+   * }
+   */
   getValueAt(e, t) {
   }
+  /**
+   * Returns a string representation of the cell value at the specified row and column indices.
+   * This method is used when exporting the table data or copying to clipboard.
+   * The base implementation returns an empty string and should be overridden by
+   * subclasses that need custom text conversion.
+   * 
+   * @param {number} _rowIndex - The index of the row
+   * @param {number} _columnIndex - The index of the column
+   * @returns {string} The text value of the specified cell
+   * 
+   * @example
+   * // Override in a subclass to provide text representation
+   * getTextValueAt(rowIndex: number, columnIndex: number): string {
+   *   const value = this.getValueAt(rowIndex, columnIndex);
+   *   
+   *   // Handle different data types appropriately
+   *   if (value === null || value === undefined) return '';
+   *   if (value instanceof Date) return value.toISOString();
+   *   return String(value);
+   * }
+   */
   getTextValueAt(e, t) {
     return "";
   }
+  /**
+   * Returns the Y-coordinate (in pixels) of the top of the row at the specified index.
+   * This method is used for scrolling and positioning rows in the viewport.
+   * The base implementation returns 0 and should be overridden by
+   * subclasses that support scrolling.
+   * 
+   * @param {number} _rowIndex - The index of the row
+   * @returns {number} The Y-coordinate of the top of the row, in pixels
+   * 
+   * @example
+   * // Override in a subclass with fixed row heights
+   * getYPosByRowIndex(rowIndex: number): number {
+   *   return rowIndex * this.defaultRowHeight;
+   * }
+   * 
+   * @example
+   * // Override in a subclass with variable row heights
+   * getYPosByRowIndex(rowIndex: number): number {
+   *   // Use a pre-calculated array of Y-positions
+   *   return this.yPositions[rowIndex];
+   *   
+   *   // Or calculate on-the-fly
+   *   // let yPos = 0;
+   *   // for (let i = 0; i < rowIndex; i++) {
+   *   //   yPos += this.getRowHeight(i);
+   *   // }
+   *   // return yPos;
+   * }
+   */
   getYPosByRowIndex(e) {
     return 0;
   }
+  /**
+   * Initializes the area model.
+   * This method is called internally by the TableModel during initialization.
+   * It can be used to perform any necessary setup, such as calculating row positions.
+   * The base implementation does nothing and can be overridden by
+   * subclasses that need initialization.
+   * 
+   * @returns {void}
+   * 
+   * @example
+   * // Override in a subclass to perform initialization
+   * init(): void {
+   *   // Calculate y-positions for all rows
+   *   this.yPositions = [];
+   *   let currentY = 0;
+   *   
+   *   for (let i = 0; i < this.getRowCount(); i++) {
+   *     this.yPositions[i] = currentY;
+   *     currentY += this.getRowHeight(i);
+   *   }
+   * }
+   */
   init() {
   }
+  /**
+   * Determines whether the cell at the specified row and column indices is editable.
+   * If true, the user can edit the cell content.
+   * The base implementation returns false (not editable) and should be overridden by
+   * subclasses that support cell editing.
+   * 
+   * @param {number} _rowIndex - The index of the row
+   * @param {number} _columnIndex - The index of the column
+   * @returns {boolean} True if the cell is editable, false otherwise
+   * 
+   * @example
+   * // Override in a subclass to implement cell editability
+   * isEditable(rowIndex: number, columnIndex: number): boolean {
+   *   // Header cells are not editable
+   *   if (this.areaIdent === 'header') return false;
+   *   
+   *   // First column is not editable (e.g., ID column)
+   *   if (columnIndex === 0) return false;
+   *   
+   *   // Other cells in the body are editable
+   *   return this.areaIdent === 'body';
+   * }
+   */
   isEditable(e, t) {
     return !1;
   }
+  /**
+   * Determines whether this area supports filtering.
+   * If true, the area can be filtered using the externalFilterChanged method.
+   * The base implementation returns false (not filterable) and should be overridden by
+   * subclasses that support filtering.
+   * 
+   * @returns {boolean} True if the area is filterable, false otherwise
+   * 
+   * @example
+   * // Override in a subclass to enable filtering
+   * isFilterable(): boolean {
+   *   // Only the body area is filterable
+   *   return this.areaIdent === 'body';
+   * }
+   */
   isFilterable() {
     return !1;
   }
+  /**
+   * Determines whether the row at the specified index is checkable.
+   * If true, a checkbox will be rendered at the beginning of the row.
+   * The base implementation returns false (not checkable) and should be overridden by
+   * subclasses that support row selection.
+   * 
+   * @param {number} _rowIndex - The index of the row
+   * @returns {boolean} True if the row is checkable, false otherwise
+   * 
+   * @example
+   * // Override in a subclass to implement row checkability
+   * isRowCheckable(rowIndex: number): boolean {
+   *   // All rows in the body are checkable
+   *   if (this.areaIdent !== 'body') return false;
+   *   
+   *   // Except for special rows
+   *   const row = this.getRowByIndex(rowIndex);
+   *   return row && !row.locked;
+   * }
+   */
   isRowCheckable(e) {
     return !1;
   }
+  /**
+   * Returns the checked state of the row at the specified index.
+   * The base implementation returns undefined (not checked) and should be overridden by
+   * subclasses that support row selection.
+   * 
+   * @param {number} _rowIndex - The index of the row
+   * @returns {CheckedType | undefined} The checked state of the row (true, false, or 'indeterminate'),
+   *                                   or undefined if the row is not checkable
+   * 
+   * @example
+   * // Override in a subclass to implement row checked state
+   * isRowChecked(rowIndex: number): CheckedType | undefined {
+   *   if (!this.rowSelectionModel) return undefined;
+   *   
+   *   const row = this.getRowByIndex(rowIndex);
+   *   return this.rowSelectionModel.isRowChecked(row);
+   * }
+   */
   isRowChecked(e) {
   }
+  /**
+   * Determines whether the cell at the specified row and column indices is selectable.
+   * If true, the user can select the cell.
+   * The base implementation returns false (not selectable) and should be overridden by
+   * subclasses that support cell selection.
+   * 
+   * @param {number} _rowIndex - The index of the row
+   * @param {number} _columnIndex - The index of the column
+   * @returns {boolean} True if the cell is selectable, false otherwise
+   * 
+   * @example
+   * // Override in a subclass to implement cell selectability
+   * isSelectable(rowIndex: number, columnIndex: number): boolean {
+   *   // All cells in the body are selectable
+   *   return this.areaIdent === 'body';
+   * }
+   */
   isSelectable(e, t) {
     return !1;
   }
+  /**
+   * Sets the checked state of the row at the specified index.
+   * The base implementation does nothing and should be overridden by
+   * subclasses that support row selection.
+   * 
+   * @param {number} _rowIndex - The index of the row
+   * @param {boolean} _checked - The new checked state
+   * @returns {void}
+   * 
+   * @example
+   * // Override in a subclass to implement row checking
+   * setRowChecked(rowIndex: number, checked: boolean): void {
+   *   if (!this.rowSelectionModel) return;
+   *   
+   *   const row = this.getRowByIndex(rowIndex);
+   *   if (row) {
+   *     this.rowSelectionModel.checkRow(row, checked);
+   *   }
+   * }
+   */
   setRowChecked(e, t) {
   }
+  /**
+   * Sets the value of a cell at the specified row and column indices.
+   * This method is called when a cell is edited by the user or programmatically.
+   * The base implementation returns false (value not set) and should be overridden by
+   * subclasses that support cell editing.
+   * 
+   * @param {number} _rowIndex - The index of the row containing the cell
+   * @param {number} _columnIndex - The index of the column containing the cell
+   * @param {any} _value - The new value to set
+   * @returns {boolean} - True if the value was successfully set, false otherwise
+   * 
+   * @example
+   * // Override in a subclass to implement cell value setting
+   * setValue(rowIndex: number, columnIndex: number, value: any): boolean {
+   *   // Check if the cell is editable
+   *   if (!this.isEditable(rowIndex, columnIndex)) return false;
+   *   
+   *   // For a 2D array model
+   *   if (rowIndex >= 0 && rowIndex < this.data.length) {
+   *     const row = this.data[rowIndex];
+   *     if (columnIndex >= 0 && columnIndex < row.length) {
+   *       row[columnIndex] = value;
+   *       return true;
+   *     }
+   *   }
+   *   
+   *   return false;
+   * }
+   */
   setValue(e, t, s) {
     return !1;
   }