@guiexpert/table 1.1.29 → 1.1.31

package/lib/table/focus/focus-model.d.ts

@@ -1,6 +1,50 @@
 import { FocusType } from "./focus.type";
 import { FocusModelIf } from "./focus-model.if";
 import { EventFocusChangedListenerIf } from './event-focus-changed-listener.if';
+/**
+ * The `FocusModel` class is an implementation of the `FocusModelIf` interface.
+ * It provides core functionality to manage focus inside a data grid or spreadsheet-like structure.
+ * The focus can be set to a specific cell or to the whole row.
+ * This class also maintains a list of `EventFocusChangedListenerIf` instances and notifies them
+ * whenever there is a change in focus.
+ *
+ * ## Instance Properties:
+ *  - `selectionType: FocusType` — Specifies the type of selection that is currently in focus. It could be either a specific cell or the whole row. Defaults to "none".
+ *  - `rowIndex: number` — Specifies the row index of the cell that is currently in focus.
+ *  - `columnIndex: number` — Specifies the column index of the cell that is currently in focus.
+ *  - `listenerArr: EventFocusChangedListenerIf[]` — An array of `EventFocusChangedListenerIf` instances. These instances will be triggered when the focus changes.
+ *  - `changed` — A boolean flag to check if the focus has changed since the last trigger.
+ *
+ * ## Instance Methods:
+ *  - `getEventFocusChangedListeners` — Returns an array of `EventFocusChangedListenerIf` instances.
+ *  - `addEventFocusChangedListener(listener: EventFocusChangedListenerIf): void` — Adds a listener to the listeners array, if it's not already present.
+ *  - `removeEventFocusChangedListener(listener: EventFocusChangedListenerIf): void` — Removes a listener from the listeners array.
+ *  - `clear`: void  — Clears the current focus.
+ *  - `setFocus(rowIndex: number, columnIndex: number): void` — Sets focus on a given cell.
+ *  - `hasChanged(): boolean` — Checks if the focus has changed.
+ *  - `clearChanged`: void — Clears the `changed` flag.
+ *  - `hasFocus(rowIndex: number, columnIndex: number): boolean` — Checks if a given cell is in focus.
+ *  - `getFocus(): [number, number]` — Returns the row and column indexes of the cell that's currently in focus.
+ *
+ * ## Usage Example
+ *  ```typescript
+ *
+ * class MyFocusChangeListener implements EventFocusChangedListenerIf {
+ *   onFocusChanged(model: FocusModelIf): void {
+ *     console.log('Focus changed: ', model.getFocus());
+ *   }
+ * }
+ * let focusModel = new FocusModel("cell");
+ * focusModel.addEventFocusChangedListener(new MyFocusChangeListener());
+ * focusModel.setFocus(2, 3);
+ * ```
+ *
+ * @see [FocusType](./FocusType.md)
+ * @see [EventFocusChangedListenerIf](./EventFocusChangedListenerIf.md)
+ *
+ * @class
+ * @implements {FocusModelIf}
+ */
 export declare class FocusModel implements FocusModelIf {
     selectionType: FocusType;
     protected rowIndex: number;

package/lib/table/focus/focus.type.d.ts

@@ -1 +1,29 @@
+/**
+ * The `FocusType` type alias provides an enumerated set of string literal values
+ * which can be used to indicate the type of focus within the grid.
+ *
+ * The values are:
+ * - "none" : Indicating that cells and rows cannot have a focus.
+ * - "cell" : Indicating that cells can have a focus.
+ * - "row"  : Indicating that entire rows can have a focus.
+ *
+ * Typically, this type is used within the `FocusModel` class,
+ * specifically in the `constructor` and in the `setFocus` method,
+ * to set `selectionType` property and determine where the focus is set respectively.
+ *
+ * Here is a usage example with the `FocusModel` class:
+ *
+ * ```typescript
+ * let focusModel = new FocusModel("cell");
+ * focusModel.setFocus(2, 3);
+ * ```
+ *
+ * In the above example, a `FocusModel` instance is created with a `FocusType` of "cell".
+ * Then the focus is set to the cell at row index 2 and column index 3.
+ *
+ * @see FocusModel
+ * @see FocusModel#setFocus
+ * @see FocusModelIf
+ * @type
+ */
 export type FocusType = "none" | "cell" | "row";

package/lib/table/resize-handler.d.ts

@@ -1,6 +1,12 @@
 import { TableScope } from "./table-scope";
+/**
+ * Class representing a ResizeHandler.
+ * @class
+ * @classdesc Handles resizing of elements and calls a callback function on resize. These calls will be debounced with 500 ms.
+ */
 export declare class ResizeHandler {
     protected tableScope: TableScope;
-    constructor(tableScope: TableScope);
+    protected debounceDelay: number;
+    constructor(tableScope: TableScope, debounceDelay?: number);
     private handleResize;
 }

package/lib/table/selection/selection-model.d.ts

@@ -2,6 +2,42 @@ import { CellRange } from "../data/common/cell-range";
 import { ExtendedSelectionType, SelectionMode } from './selection.type';
 import { SelectionModelIf } from "./selection-model.if";
 import { EventSelectionChangedListenerIf } from './event-selection-changed-listener.if';
+/**
+ * `SelectionModel` is a class that manages the various modes and types of selections within a grid.
+ * It supports basic modes like single cell, row, column, and range selections, as well as advanced mode like negative ranges.
+ * Events related to selections, such as changes to a selection, are propagated to listeners through the EventSelectionChangedListener interface.
+ *
+ * The class extends `SelectionModelIf` interface and defines additional methods and fields specific to its functionality.
+ *
+ * @property {ExtendedSelectionType} selectionType - The type of selection being used. It's of type ExtendedSelectionType. Default: "none"
+ * @property {SelectionMode} selectionMode - The mode of selection being used. It's of type SelectionMode. Default: "single"
+ * @property {Array} ranges - This contains all the current selected cell ranges in the grid.
+ * @property {Array} negativeRanges - This contains all the current negative cell ranges in the grid.
+ * @property {boolean} allSelected - This is a flag to indicate whether all cells in the grid are selected or not.
+ * @property {boolean} silent - This is a flag to suppress the firing of selection change events.
+ * @property {Array} listenerArr - This contains all the listeners for selection change events.
+ *
+ * @method constructor(selectionType?: ExtendedSelectionType, selectionMode?: SelectionMode) - Constructs a new instance of the SelectionModel class.
+ * @method getEventSelectionChangedListeners(): EventSelectionChangedListenerIf[] - Returns the array of registered event selection changed listeners.
+ * @method addEventSelectionChangedListener(listener: EventSelectionChangedListenerIf): void - Adds an event selection changed listener to the array.
+ * @method removeEventSelectionChangedListener(listener: EventSelectionChangedListenerIf): void - Removes a specific event selection changed listener if it exists.
+ * @method fireChangeEvent(): void - Fires a change event on each registered listener when a selection change occurs. Does nothing if the silent property is true.
+ * @method firstClick(rowIndex: number, columnIndex: number): void - Initiates a selection operation at the specified coordinates. The nature of the operation is determined by the current selection type and mode.
+ * @method getSelectionCount(rowIndex: number, columnIndex: number): number - Returns the selection count of current ranges
+ * @method isInNegativeRange(rowIndex: number, columnIndex: number): boolean - Verifies if any point (cell) is in negative range or not.
+ * @method getRanges() - Returns the selection ranges
+ * @method clear(): void - Clears all selections in all ranges and resets allSelected and negativeRanges arrays.
+ * @method hasSelection(): boolean - Checks whether there is any selection. Returns true if yes, false if no.
+ * @method hasNoSelection(): boolean - Checks whether there is no selection. Returns true if yes, false if no.
+ * @method getMergedRowIndices(): number[] - Gets the array of merged row indices.
+ * @method selectAll(): void - Selects all selectable entities.
+ * @method isAllSelected() - Checks if all selectable entities are selected.
+ * @method addSelection(range: CellRange): void - Adds a certain range to the selection.
+ * @method removeSelection(range: CellRange): void - Removes a certain range from the selection.
+ * @method togglePoint(row: number, col: number): void - Toggles the selection state of a point at the specified row and column in a grid.
+ * @method isSelected(row: number, col: number): boolean - Checks if a specific cell in a grid is selected.
+ * @method addRange(range: CellRange): void - Adds a range of cells to the selection.
+ */
 export declare class SelectionModel implements SelectionModelIf {
     selectionType: ExtendedSelectionType;
     selectionMode: SelectionMode;

package/lib/table/service/excel-service.d.ts

@@ -0,0 +1,19 @@
+import { ExcelServiceIf } from './excel-service.if';
+export declare class ExcelService implements ExcelServiceIf {
+    /**
+     * Downloads a matrix data as an Excel file.
+     *
+     * @param {Array<Array<any>>} matrix - A 2D array representing the data to be included in the Excel file. Each inner array corresponds to a row in the sheet.
+     * @param {string} [filename='file.xlsx'] - The name of the Excel file to be downloaded. Defaults to 'file.xlsx'.
+     * @param {string} [author=''] - The author's name to include as metadata in the Excel file. Optional parameter.
+     * @return {void} Does not return a value.
+     * @throws {Error} Throws an error if the input matrix is not a valid 2D array or if the filename is an empty string.
+     */
+    downloadExcel(matrix: Array<Array<any>>, filename?: string, author?: string): void;
+    private generateMap;
+    private getX1WorksheetsSheet1Xml;
+    private escapeXml;
+    private getCellAddress;
+    createZip(files: Map<string, string>): Uint8Array;
+    private generateBuffer;
+}

package/lib/table/service/excel-service.if.d.ts

@@ -0,0 +1,3 @@
+export interface ExcelServiceIf {
+    downloadExcel(matrix: Array<Array<any>>, filename: string, author?: string): void;
+}

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

@@ -5,6 +5,15 @@ 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';
+/**
+* TableApi Class
+*
+* A class for interfacing with a table within the application.
+* It includes features for scrolling, updating cells, handling visibility of elements like header and footer,
+* and dealing with selections within the table.
+*
+* An instance of this class is automatically created for each table component.
+*/
 export declare class TableApi {
     readonly tableScope: TableScope;
     constructor(tableScope: TableScope);
@@ -100,6 +109,13 @@ export declare class TableApi {
      * @return {void}
      */
     repaintHard(): void;
+    /**
+     * Recalculates the column widths of the table.
+     *
+     * @param {number} clientWidth - The width of the client area.
+     *
+     * @return {void}
+     */
     recalcColumnWidths(clientWidth?: number): void;
     /**
      * Clears the current selection of the table.
@@ -137,6 +153,13 @@ export declare class TableApi {
      * @return {Promise<string>} - A promise that resolves with the copied data as a string.
      */
     copyToClipboard(): Promise<string>;
+    /**
+     * Downloads an Excel file containing data from the table's header, body, and footer areas.
+     * Extracts the table data into a 2D matrix and uses the Excel service to generate and download the file.
+     *
+     * @return {void} No return value, downloads the Excel file directly.
+     */
+    downloadExcel(): void;
     /**
      * Retrieves the current scope of the table.
      *

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

@@ -24,6 +24,7 @@ import { FocusModelIf } from './focus/focus-model.if';
 import { EventFocusChangedListenerIf } from './focus/event-focus-changed-listener.if';
 import { EventSelectionChangedListenerIf } from './selection/event-selection-changed-listener.if';
 import { ResizeHandler } from './resize-handler';
+import { ExcelServiceIf } from './service/excel-service.if';
 /**
  * The TableScope class extends the RenderScope class and provides functionality for rendering and interacting with a table.
  *
@@ -53,6 +54,7 @@ import { ResizeHandler } from './resize-handler';
 export declare class TableScope extends RenderScope implements OnActionTriggeredIf, EventFocusChangedListenerIf, EventSelectionChangedListenerIf {
     protected readonly eventListener: EventListenerIf;
     readonly copyService: CopyServiceIf;
+    readonly excelService: ExcelServiceIf;
     licenseManager: LicenseManager;
     mouseHandler: MouseHandler;
     inputHandler: InputHandler;
@@ -71,7 +73,7 @@ export declare class TableScope extends RenderScope implements OnActionTriggered
     private lastDragFrom;
     private lastDragTo;
     private firstDraggingRendering;
-    constructor(hostElement: HTMLDivElement, tableModel: TableModelIf, domService: DomServiceIf, tableOptions: TableOptionsIf, eventListener: EventListenerIf, copyService?: CopyServiceIf);
+    constructor(hostElement: HTMLDivElement, tableModel: TableModelIf, domService: DomServiceIf, tableOptions: TableOptionsIf, eventListener: EventListenerIf, copyService?: CopyServiceIf, excelService?: ExcelServiceIf);
     /**
      * Creates a TableScope instance.
      *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guiexpert/table",
-  "version": "1.1.29",
+  "version": "1.1.31",
   "private": false,
   "type": "module",
   "main": "./index.js",