@highcharts/grid-pro 2.0.0

package/es-modules/Data/DataTable.d.ts

@@ -0,0 +1,563 @@
+import type DataEvent from './DataEvent';
+import type DataModifier from './Modifiers/DataModifier';
+import type DataTableOptions from './DataTableOptions';
+import type { DataTableValue } from './DataTableOptions';
+import type { TypedArray } from '../Shared/Types';
+import DataTableCore from './DataTableCore.js';
+/**
+ * Class to manage columns and rows in a table structure. It provides methods
+ * to add, remove, and manipulate columns and rows, as well as to retrieve data
+ * from specific cells.
+ *
+ * @class
+ * @name Highcharts.DataTable
+ *
+ * @param {Highcharts.DataTableOptions} [options]
+ * Options to initialize the new DataTable instance.
+ */
+declare class DataTable extends DataTableCore implements DataEvent.Emitter<DataTable.Event> {
+    constructor(options?: DataTableOptions);
+    private modifier?;
+    private localRowIndexes?;
+    private originalRowIndexes?;
+    metadata?: Record<string, DataTableValue>;
+    /**
+     * Returns a clone of this table. The cloned table is completely independent
+     * of the original, and any changes made to the clone will not affect
+     * the original table.
+     *
+     * @function Highcharts.DataTable#clone
+     *
+     * @param {boolean} [skipColumns]
+     * Whether to clone columns or not.
+     *
+     * @param {Highcharts.DataTableEventDetail} [eventDetail]
+     * Custom information for pending events.
+     *
+     * @return {Highcharts.DataTable}
+     * Clone of this data table.
+     *
+     * @emits #cloneTable
+     * @emits #afterCloneTable
+     */
+    clone(skipColumns?: boolean, eventDetail?: DataEvent.Detail): DataTable;
+    /**
+     * Deletes columns from the table.
+     *
+     * @function Highcharts.DataTable#deleteColumns
+     *
+     * @param {Array<string>} [columnIds]
+     * Names of columns to delete. If no array is provided, all
+     * columns will be deleted.
+     *
+     * @param {Highcharts.DataTableEventDetail} [eventDetail]
+     * Custom information for pending events.
+     *
+     * @return {Highcharts.DataTableColumnCollection|undefined}
+     * Returns the deleted columns, if found.
+     *
+     * @emits #deleteColumns
+     * @emits #afterDeleteColumns
+     */
+    deleteColumns(columnIds?: Array<string>, eventDetail?: DataEvent.Detail): (DataTable.ColumnCollection | undefined);
+    /**
+     * Deletes the row index references. This is useful when the original table
+     * is deleted, and the references are no longer needed. This table is
+     * then considered an original table or a table that has the same rows
+     * order as the original table.
+     */
+    deleteRowIndexReferences(): void;
+    /**
+     * Deletes rows in this table.
+     *
+     * @function Highcharts.DataTable#deleteRows
+     *
+     * @param {number} [rowIndex]
+     * Index to start delete of rows. If not specified, all rows will be
+     * deleted.
+     *
+     * @param {number} [rowCount=1]
+     * Number of rows to delete.
+     *
+     * @param {Highcharts.DataTableEventDetail} [eventDetail]
+     * Custom information for pending events.
+     *
+     * @return {Array<Highcharts.DataTableRow>}
+     * Returns the deleted rows, if found.
+     *
+     * @emits #deleteRows
+     * @emits #afterDeleteRows
+     */
+    deleteRows(rowIndex?: number, rowCount?: number, eventDetail?: DataEvent.Detail): Array<DataTable.Row>;
+    /**
+     * Emits an event on this table to all registered callbacks of the given
+     * event.
+     * @private
+     *
+     * @param {DataTable.Event} e
+     * Event object with event information.
+     */
+    emit(e: DataTable.Event): void;
+    /**
+     * Fetches a single cell value.
+     *
+     * @function Highcharts.DataTable#getCell
+     *
+     * @param {string} columnId
+     * Column name of the cell to retrieve.
+     *
+     * @param {number} rowIndex
+     * Row index of the cell to retrieve.
+     *
+     * @return {Highcharts.DataTableCellType|undefined}
+     * Returns the cell value or `undefined`.
+     */
+    getCell(columnId: string, rowIndex: number): (DataTable.CellType | undefined);
+    /**
+     * Fetches the given column by the canonical column name.
+     * This function is a simplified wrap of {@link getColumns}.
+     *
+     * @function Highcharts.DataTable#getColumn
+     *
+     * @param {string} columnId
+     * Name of the column to get.
+     *
+     * @param {boolean} [asReference]
+     * Whether to return the column as a readonly reference.
+     *
+     * @return {Highcharts.DataTableColumn|undefined}
+     * A copy of the column, or `undefined` if not found.
+     */
+    getColumn(columnId: string, asReference?: boolean): (DataTable.Column | undefined);
+    /**
+     * Fetches all column IDs.
+     *
+     * @function Highcharts.DataTable#getColumnIds
+     *
+     * @return {Array<string>}
+     * Returns all column IDs.
+     */
+    getColumnIds(): Array<string>;
+    getColumns(columnIds?: Array<string>, asReference?: boolean): DataTable.ColumnCollection;
+    getColumns(columnIds: (Array<string> | undefined), asReference: true): Record<string, DataTable.Column>;
+    getColumns(columnIds: (Array<string> | undefined), asReference: false, asBasicColumns: true): Record<string, DataTable.BasicColumn>;
+    /**
+     * Takes the original row index and returns the local row index in the
+     * modified table for which this function is called.
+     *
+     * @param {number} originalRowIndex
+     * Original row index to get the local row index for.
+     *
+     * @return {number|undefined}
+     * Returns the local row index or `undefined` if not found.
+     */
+    getLocalRowIndex(originalRowIndex: number): (number | undefined);
+    /**
+     * Returns the modifier associated with this table, if any.
+     *
+     * @return {Highcharts.DataModifier|undefined}
+     * Returns the modifier or `undefined`.
+     *
+     * @private
+     */
+    getModifier(): (DataModifier | undefined);
+    /**
+     * Takes the local row index and returns the index of the corresponding row
+     * in the original table.
+     *
+     * @param {number} rowIndex
+     * Local row index to get the original row index for.
+     *
+     * @return {number|undefined}
+     * Returns the original row index or `undefined` if not found.
+     */
+    getOriginalRowIndex(rowIndex: number): (number | undefined);
+    /**
+     * Retrieves the row at a given index. This function is a simplified wrap of
+     * {@link getRows}.
+     *
+     * @function Highcharts.DataTable#getRow
+     *
+     * @param {number} rowIndex
+     * Row index to retrieve. First row has index 0.
+     *
+     * @param {Array<string>} [columnIds]
+     * Column names in order to retrieve.
+     *
+     * @return {Highcharts.DataTableRow}
+     * Returns the row values, or `undefined` if not found.
+     */
+    getRow(rowIndex: number, columnIds?: Array<string>): (DataTable.Row | undefined);
+    /**
+     * Returns the number of rows in this table.
+     *
+     * @function Highcharts.DataTable#getRowCount
+     *
+     * @return {number}
+     * Number of rows in this table.
+     */
+    getRowCount(): number;
+    /**
+     * Retrieves the index of the first row matching a specific cell value.
+     *
+     * @function Highcharts.DataTable#getRowIndexBy
+     *
+     * @param {string} columnId
+     * Column to search in.
+     *
+     * @param {Highcharts.DataTableCellType} cellValue
+     * Cell value to search for. `NaN` and `undefined` are not supported.
+     *
+     * @param {number} [rowIndexOffset]
+     * Index offset to start searching.
+     *
+     * @return {number|undefined}
+     * Index of the first row matching the cell value.
+     */
+    getRowIndexBy(columnId: string, cellValue: DataTable.CellType, rowIndexOffset?: number): (number | undefined);
+    /**
+     * Retrieves the row at a given index. This function is a simplified wrap of
+     * {@link getRowObjects}.
+     *
+     * @function Highcharts.DataTable#getRowObject
+     *
+     * @param {number} rowIndex
+     * Row index.
+     *
+     * @param {Array<string>} [columnIds]
+     * Column names and their order to retrieve.
+     *
+     * @return {Highcharts.DataTableRowObject}
+     * Returns the row values, or `undefined` if not found.
+     */
+    getRowObject(rowIndex: number, columnIds?: Array<string>): (DataTable.RowObject | undefined);
+    /**
+     * Fetches all or a number of rows as an object.
+     *
+     * @function Highcharts.DataTable#getRowObjects
+     *
+     * @param {number} [rowIndex]
+     * Index of the first row to fetch. Defaults to first row at index `0`.
+     *
+     * @param {number} [rowCount]
+     * Number of rows to fetch. Defaults to maximal number of rows.
+     *
+     * @param {Array<string>} [columnIds]
+     * Column names and their order to retrieve.
+     *
+     * @return {Highcharts.DataTableRowObject}
+     * Returns retrieved rows.
+     */
+    getRowObjects(rowIndex?: number, rowCount?: number, columnIds?: Array<string>): (Array<DataTable.RowObject>);
+    /**
+     * Fetches all or a number of rows as an array.
+     *
+     * @function Highcharts.DataTable#getRows
+     *
+     * @param {number} [rowIndex]
+     * Index of the first row to fetch. Defaults to first row at index `0`.
+     *
+     * @param {number} [rowCount]
+     * Number of rows to fetch. Defaults to maximal number of rows.
+     *
+     * @param {Array<string>} [columnIds]
+     * Column names and their order to retrieve.
+     *
+     * @return {Highcharts.DataTableRow}
+     * Returns retrieved rows.
+     */
+    getRows(rowIndex?: number, rowCount?: number, columnIds?: Array<string>): (Array<DataTable.Row>);
+    /**
+     * Returns the unique version tag of the current state of the table.
+     *
+     * @function Highcharts.DataTable#getVersionTag
+     *
+     * @return {string}
+     * Unique version tag.
+     */
+    getVersionTag(): string;
+    /**
+     * Determines whether all specified column names exist in the table.
+     *
+     * @function Highcharts.DataTable#hasColumns
+     *
+     * @param {Array<string>} columnIds
+     * Column names to check.
+     *
+     * @return {boolean}
+     * Returns `true` if all columns have been found, otherwise `false`.
+     */
+    hasColumns(columnIds: Array<string>): boolean;
+    /**
+     * Checks if any row in the specified column contains the given cell value.
+     *
+     * @function Highcharts.DataTable#hasRowWith
+     *
+     * @param {string} columnId
+     * Column to search in.
+     *
+     * @param {Highcharts.DataTableCellType} cellValue
+     * Cell value to search for. `NaN` and `undefined` are not supported.
+     *
+     * @return {boolean}
+     * True, if a row has been found, otherwise false.
+     */
+    hasRowWith(columnId: string, cellValue: DataTable.CellType): boolean;
+    /**
+     * Registers a callback function to be executed when a specific event is
+     * emitted. To stop listening to the event, call the function returned by
+     * this method.
+     *
+     * @function Highcharts.DataTable#on
+     *
+     * @param {string} type
+     * Event type as a string.
+     *
+     * @param {Highcharts.EventCallbackFunction<Highcharts.DataTable>} callback
+     * Function to register for an event callback.
+     *
+     * @return {Function}
+     * Function to unregister callback from the event.
+     */
+    on<T extends DataTable.Event['type']>(type: T, callback: DataEvent.Callback<this, Extract<DataTable.Event, {
+        type: T;
+    }>>): Function;
+    /**
+     * Changes the ID of an existing column to a new ID, effectively renaming
+     * the column.
+     *
+     * @function Highcharts.DataTable#changeColumnId
+     *
+     * @param {string} columnId
+     * Id of the column to be changed.
+     *
+     * @param {string} newColumnId
+     * New id of the column.
+     *
+     * @return {boolean}
+     * Returns `true` if successful, `false` if the column was not found.
+     */
+    changeColumnId(columnId: string, newColumnId: string): boolean;
+    /**
+     * Sets the value of a specific cell identified by column ID and row index.
+     * If the column does not exist, it will be created. If the row index is
+     * beyond the current row count, the table will be expanded to accommodate
+     * the new cell.
+     *
+     * @function Highcharts.DataTable#setCell
+     *
+     * @param {string} columnId
+     * Column name to set.
+     *
+     * @param {number|undefined} rowIndex
+     * Row index to set.
+     *
+     * @param {Highcharts.DataTableCellType} cellValue
+     * Cell value to set.
+     *
+     * @param {Highcharts.DataTableEventDetail} [eventDetail]
+     * Custom information for pending events.
+     *
+     * @emits #setCell
+     * @emits #afterSetCell
+     */
+    setCell(columnId: string, rowIndex: number, cellValue: DataTable.CellType, eventDetail?: DataEvent.Detail): void;
+    /**
+     * Replaces or updates multiple columns in the table with new data. If a
+     * column does not exist, it will be created and added to the table.
+     *
+     * @function Highcharts.DataTable#setColumns
+     *
+     * @param {Highcharts.DataTableColumnCollection} columns
+     * Columns as a collection, where the keys are the column names.
+     *
+     * @param {number} [rowIndex]
+     * Index of the first row to change. Keep undefined to reset.
+     *
+     * @param {Highcharts.DataTableEventDetail} [eventDetail]
+     * Custom information for pending events.
+     *
+     * @param {boolean} [typeAsOriginal=false]
+     * Determines whether the original column retains its type when data
+     * replaced. If `true`, the original column keeps its type. If not
+     * (default), the original column will adopt the type of the replacement
+     * column.
+     *
+     * @emits #setColumns
+     * @emits #afterSetColumns
+     */
+    setColumns(columns: DataTable.ColumnCollection, rowIndex?: number, eventDetail?: DataEvent.Detail, typeAsOriginal?: boolean): void;
+    /**
+     * Assigns a new data modifier to the table.
+     *
+     * This method does not modify the table directly. Instead, it sets the
+     * `.modified` property of the table with a modified copy of this table,
+     * as produced by the modifier.
+     *
+     * @param {Highcharts.DataModifier} [modifier]
+     * Modifier to set, or `undefined` to unset.
+     *
+     * @param {Highcharts.DataTableEventDetail} [eventDetail]
+     * Custom information for pending events.
+     *
+     * @return {Promise<Highcharts.DataTable>}
+     * Resolves to this table if successful, or rejects on failure.
+     *
+     * @emits #setModifier
+     * @emits #afterSetModifier
+     */
+    setModifier(modifier?: DataModifier, eventDetail?: DataEvent.Detail): Promise<DataTable>;
+    /**
+     * Sets the original row indexes for the table. It is used to keep the
+     * reference to the original rows when modifying the table.
+     *
+     * @param {Array<number|undefined>} originalRowIndexes
+     * Original row indexes array.
+     *
+     * @param {boolean} omitLocalRowIndexes
+     * Whether to omit the local row indexes calculation. Defaults to `false`.
+     */
+    setOriginalRowIndexes(originalRowIndexes: Array<number | undefined>, omitLocalRowIndexes?: boolean): void;
+    /**
+     * Sets cell values of a row. Will insert a new row, if no index was
+     * provided, or if the index is higher than the total number of table rows.
+     *
+     * Note: This function is just a simplified wrap of
+     * {@link Highcharts.DataTable#setRows}.
+     *
+     * @function Highcharts.DataTable#setRow
+     *
+     * @param {Highcharts.DataTableRow|Highcharts.DataTableRowObject} row
+     * Cell values to set.
+     *
+     * @param {number} [rowIndex]
+     * Index of the row to set. Leave `undefind` to add as a new row.
+     *
+     * @param {boolean} [insert]
+     * Whether to insert the row at the given index, or to overwrite the row.
+     *
+     * @param {Highcharts.DataTableEventDetail} [eventDetail]
+     * Custom information for pending events.
+     *
+     * @emits #setRows
+     * @emits #afterSetRows
+     */
+    setRow(row: (DataTable.Row | DataTable.RowObject), rowIndex?: number, insert?: boolean, eventDetail?: DataEvent.Detail): void;
+    /**
+     * Sets cell values for multiple rows. Will insert new rows, if no index was
+     * was provided, or if the index is higher than the total number of table
+     * rows.
+     *
+     * @function Highcharts.DataTable#setRows
+     *
+     * @param {Array<(Highcharts.DataTableRow|Highcharts.DataTableRowObject)>} rows
+     * Row values to set.
+     *
+     * @param {number} [rowIndex]
+     * Index of the first row to set. Leave `undefined` to add as new rows.
+     *
+     * @param {boolean} [insert]
+     * Whether to insert the row at the given index, or to overwrite the row.
+     *
+     * @param {Highcharts.DataTableEventDetail} [eventDetail]
+     * Custom information for pending events.
+     *
+     * @emits #setRows
+     * @emits #afterSetRows
+     */
+    setRows(rows: Array<(DataTable.Row | DataTable.RowObject)>, rowIndex?: number, insert?: boolean, eventDetail?: DataEvent.Detail): void;
+}
+/**
+ * Additionally it provides necessary types for events.
+ */
+declare namespace DataTable {
+    /**
+     * Possible value types for a table cell.
+     */
+    type CellType = (boolean | number | null | string | undefined);
+    /**
+     * Conventional array of table cells typed as `CellType`.
+     */
+    interface BasicColumn extends Array<DataTable.CellType> {
+        [index: number]: CellType;
+    }
+    /**
+     * Array of table cells in vertical expansion.
+     */
+    type Column = BasicColumn | TypedArray;
+    /**
+     * Collection of columns, where the key is the column name and
+     * the value is an array of column values.
+     */
+    interface ColumnCollection {
+        [columnId: string]: Column;
+    }
+    /**
+     * Event object for cell-related events.
+     */
+    interface CellEvent extends DataEvent {
+        readonly type: ('setCell' | 'afterSetCell');
+        readonly cellValue: DataTable.CellType;
+        readonly columnId: string;
+        readonly rowIndex: number;
+    }
+    /**
+     * Event object for clone-related events.
+     */
+    interface CloneEvent extends DataEvent {
+        readonly type: ('cloneTable' | 'afterCloneTable');
+        readonly tableClone?: DataTable;
+    }
+    /**
+     * Event object for column-related events.
+     */
+    interface ColumnEvent extends DataEvent {
+        readonly type: ('deleteColumns' | 'afterDeleteColumns' | 'setColumns' | 'afterSetColumns');
+        readonly columns?: ColumnCollection;
+        readonly columnIds: Array<string>;
+        readonly rowIndex?: number;
+    }
+    /**
+     * All information objects of DataTable events.
+     */
+    type Event = (CellEvent | CloneEvent | ColumnEvent | SetModifierEvent | RowEvent);
+    /**
+     * Event object for modifier-related events.
+     */
+    interface ModifierEvent extends DataEvent {
+        readonly type: ('setModifier' | 'afterSetModifier');
+        readonly modifier: (DataModifier | undefined);
+    }
+    /**
+     * Array of table cells in horizontal expansion. Index of the array is the
+     * index of the column names.
+     */
+    interface Row extends Array<CellType> {
+        [index: number]: CellType;
+    }
+    /**
+     * Event object for row-related events.
+     */
+    interface RowEvent extends DataEvent {
+        readonly type: ('deleteRows' | 'afterDeleteRows' | 'setRows' | 'afterSetRows');
+        readonly rowCount: number;
+        readonly rowIndex: number;
+        readonly rows?: Array<Row | RowObject>;
+    }
+    /**
+     * Object of row values, where the keys are the column names.
+     */
+    interface RowObject extends Record<string, CellType> {
+        [column: string]: CellType;
+    }
+    /**
+    * Event object for the setModifier events.
+    */
+    interface SetModifierEvent extends DataEvent {
+        readonly type: ('setModifier' | 'afterSetModifier' | 'setModifierError');
+        readonly error?: unknown;
+        readonly modifier?: DataModifier;
+        readonly modified?: DataTable;
+    }
+}
+export default DataTable;