@highcharts/grid-pro 2.2.0 → 2.3.0

package/es-modules/Data/Modifiers/RangeModifier.d.ts

@@ -1,4 +1,4 @@
-import type DataEvent from '../DataEvent';
+import type { DataEventDetail } from '../DataEvent';
 import type { RangeModifierOptions } from './RangeModifierOptions';
 import DataModifier from './DataModifier.js';
 import DataTable from '../DataTable.js';
@@ -13,7 +13,7 @@ declare class RangeModifier extends DataModifier {
     /**
      * Constructs an instance of the range modifier.
      *
-     * @param {Partial<RangeModifier.Options>} [options]
+     * @param {Partial<RangeModifierOptions>} [options]
      * Options to configure the range modifier.
      */
     constructor(options?: Partial<RangeModifierOptions>);
@@ -29,14 +29,14 @@ declare class RangeModifier extends DataModifier {
      * @param {DataTable} table
      * Table to modify.
      *
-     * @param {DataEvent.Detail} [eventDetail]
+     * @param {DataEventDetail} [eventDetail]
      * Custom information for pending events.
      *
      * @return {DataTable}
      * Table with `modified` property as a reference or modified table, if
      * `modified` property of the original table is undefined.
      */
-    modifyTable(table: DataTable, eventDetail?: DataEvent.Detail): DataTable;
+    modifyTable(table: DataTable, eventDetail?: DataEventDetail): DataTable;
 }
 declare module './DataModifierType' {
     interface DataModifierTypes {

package/es-modules/Data/Modifiers/RangeModifier.js

@@ -13,8 +13,7 @@
  * */
 'use strict';
 import DataModifier from './DataModifier.js';
-import U from '../../Core/Utilities.js';
-const { merge } = U;
+import { merge } from '../../Shared/Utilities.js';
 /* *
  *
  *  Class
@@ -32,7 +31,7 @@ class RangeModifier extends DataModifier {
     /**
      * Constructs an instance of the range modifier.
      *
-     * @param {Partial<RangeModifier.Options>} [options]
+     * @param {Partial<RangeModifierOptions>} [options]
      * Options to configure the range modifier.
      */
     constructor(options) {
@@ -52,7 +51,7 @@ class RangeModifier extends DataModifier {
      * @param {DataTable} table
      * Table to modify.
      *
-     * @param {DataEvent.Detail} [eventDetail]
+     * @param {DataEventDetail} [eventDetail]
      * Custom information for pending events.
      *
      * @return {DataTable}

package/es-modules/Data/Modifiers/SortModifier.d.ts

@@ -1,11 +1,11 @@
-import type DataEvent from '../DataEvent';
+import type { DataEventDetail } from '../DataEvent';
 import type SortModifierOptions from './SortModifierOptions';
 import DataModifier from './DataModifier.js';
-import DataTable from '../DataTable.js';
+import DataTable, { type Row as DataTableRow } from '../DataTable.js';
 /** @private */
 interface SortRowReference {
     index: number;
-    row: DataTable.Row;
+    row: DataTableRow;
 }
 /**
  * Sort table rows according to values of a column.
@@ -22,7 +22,7 @@ declare class SortModifier extends DataModifier {
     /**
      * Constructs an instance of the sort modifier.
      *
-     * @param {Partial<SortDataModifier.Options>} [options]
+     * @param {Partial<SortModifierOptions>} [options]
      * Options to configure the sort modifier.
      */
     constructor(options?: Partial<SortModifierOptions>);
@@ -35,16 +35,11 @@ declare class SortModifier extends DataModifier {
      * @param {Highcharts.DataTable} table
      * Table with rows to reference.
      *
-     * @return {Array<SortModifier.RowReference>}
+     * @return {Array<SortRowReference>}
      * Array of row references.
      */
     protected getRowReferences(table: DataTable): Array<SortRowReference>;
-    modifyTable(table: DataTable, eventDetail?: DataEvent.Detail): DataTable;
-}
-/**
- * Additionally provided types for modifier events and options.
- */
-declare namespace SortModifier {
+    modifyTable(table: DataTable, eventDetail?: DataEventDetail): DataTable;
 }
 declare module './DataModifierType' {
     interface DataModifierTypes {

package/es-modules/Data/Modifiers/SortModifier.js

@@ -13,8 +13,7 @@
  * */
 'use strict';
 import DataModifier from './DataModifier.js';
-import U from '../../Core/Utilities.js';
-const { merge } = U;
+import { merge } from '../../Shared/Utilities.js';
 /* *
  *
  *  Class
@@ -59,7 +58,7 @@ class SortModifier extends DataModifier {
     /**
      * Constructs an instance of the sort modifier.
      *
-     * @param {Partial<SortDataModifier.Options>} [options]
+     * @param {Partial<SortModifierOptions>} [options]
      * Options to configure the sort modifier.
      */
     constructor(options) {
@@ -79,7 +78,7 @@ class SortModifier extends DataModifier {
      * @param {Highcharts.DataTable} table
      * Table with rows to reference.
      *
-     * @return {Array<SortModifier.RowReference>}
+     * @return {Array<SortRowReference>}
      * Array of row references.
      */
     getRowReferences(table) {

package/es-modules/Data/Modifiers/SortModifierOptions.d.ts

@@ -1,5 +1,5 @@
 import type DataModifierOptions from './DataModifierOptions';
-import type DataTable from '../DataTable';
+import type { CellType as DataTableCellType } from '../DataTable';
 /**
  * Definition of a sorting level when sorting by multiple columns.
  */
@@ -17,7 +17,7 @@ export interface SortModifierOrderByOption {
      * Custom compare function for this level. If not set, the modifier-level
      * `compare` is used.
      */
-    compare?: (a: DataTable.CellType, b: DataTable.CellType) => number;
+    compare?: (a: DataTableCellType, b: DataTableCellType) => number;
 }
 /**
  * Base options shared by sorting modifiers.
@@ -48,7 +48,7 @@ export interface SortModifierBaseOptions extends DataModifierOptions {
      * A number indicating whether the first value (`a`) is less than (`-1`),
      * equal to (`0`), or greater than (`1`) the second value (`b`).
      */
-    compare?: (a: DataTable.CellType, b: DataTable.CellType) => number;
+    compare?: (a: DataTableCellType, b: DataTableCellType) => number;
     /**
      * Column to update with order index instead of change order of rows.
      */

package/es-modules/Grid/Core/Accessibility/Accessibility.d.ts

@@ -101,7 +101,7 @@ declare class Accessibility {
     /**
      * Set a11y options for the Grid.
      */
-    setA11yOptions(): void;
+    setA11yOptions(): Promise<void>;
     /**
      * Adds the screen reader section before or after the Grid.
      *

package/es-modules/Grid/Core/Accessibility/Accessibility.js

@@ -20,10 +20,9 @@ import Globals from '../Globals.js';
 import ColumnFiltering from '../Table/Actions/ColumnFiltering/ColumnFiltering.js';
 import GridUtils from '../GridUtils.js';
 import AST from '../../../Core/Renderer/HTML/AST.js';
-import U from '../../../Core/Utilities.js';
 import HTMLU from '../../../Accessibility/Utils/HTMLUtilities.js';
+import { internalClearTimeout, replaceNested } from '../../../Shared/Utilities.js';
 const { formatText } = GridUtils;
-const { replaceNested } = U;
 const { getHeadingTagNameForElement } = HTMLU;
 /**
  *  Representing the accessibility functionalities for the Data Grid.
@@ -87,7 +86,7 @@ class Accessibility {
      */
     announce(msg, assertive = false) {
         if (this.announcerTimeout) {
-            clearTimeout(this.announcerTimeout);
+            internalClearTimeout(this.announcerTimeout);
         }
         this.announcerElement.remove();
         this.announcerElement.setAttribute('aria-live', assertive ? 'assertive' : 'polite');
@@ -213,13 +212,13 @@ class Accessibility {
     /**
      * Set a11y options for the Grid.
      */
-    setA11yOptions() {
+    async setA11yOptions() {
         const grid = this.grid;
         const tableEl = grid.tableElement;
         if (!tableEl) {
             return;
         }
-        tableEl.setAttribute('aria-rowcount', grid.dataTable?.getRowCount() || 0);
+        tableEl.setAttribute('aria-rowcount', await grid.dataProvider?.getRowCount() || 0);
         if (grid.captionElement) {
             tableEl.setAttribute('aria-labelledby', grid.captionElement.id);
         }
@@ -393,7 +392,7 @@ class Accessibility {
         }
         this.element.remove();
         this.announcerElement.remove();
-        clearTimeout(this.announcerTimeout);
+        internalClearTimeout(this.announcerTimeout);
     }
 }
 /* *

package/es-modules/Grid/Core/Data/DataProvider.d.ts

@@ -0,0 +1,97 @@
+import type { RowObject as RowObjectType, CellType as DataTableCellType, Column as DataTableColumnType } from '../../../Data/DataTable';
+import type QueryingController from '../Querying/QueryingController';
+import type { ColumnDataType } from '../Table/Column';
+/**
+ * Base class for Grid data providers.
+ *
+ * Data providers are responsible for serving data to the grid, applying query
+ * modifiers and persisting edits.
+ */
+export declare abstract class DataProvider {
+    /**
+     * Querying controller used to build and apply modifiers.
+     */
+    protected readonly querying: QueryingController;
+    /**
+     * Provider options as passed via `grid.options.data`.
+     */
+    protected readonly options: DataProviderOptions;
+    constructor(queryingController: QueryingController, options: DataProviderOptions);
+    /**
+     * Initializes the data provider.
+     */
+    init(): Promise<void>;
+    /**
+     * Returns all available column IDs.
+     */
+    abstract getColumnIds(): Promise<string[]>;
+    /**
+     * Returns a stable row id for a given row index (as used by the viewport).
+     */
+    abstract getRowId(rowIndex: number): Promise<RowId | undefined>;
+    /**
+     * Returns the current row index for a given stable row id.
+     */
+    abstract getRowIndex(rowId: RowId): Promise<number | undefined>;
+    /**
+     * Returns a row as an object keyed by column IDs.
+     */
+    abstract getRowObject(rowIndex: number): Promise<RowObjectType | undefined>;
+    /**
+     * Returns the current number of rows in the presentation dataset (after
+     * applying all query modifiers).
+     */
+    abstract getRowCount(): Promise<number>;
+    /**
+     * Returns the assumed / configured data type for a column.
+     */
+    abstract getColumnDataType(columnId: string): Promise<ColumnDataType>;
+    /**
+     * Returns a cell value for a given column and row index.
+     */
+    abstract getValue(columnId: string, rowIndex: number): Promise<DataTableCellType>;
+    /**
+     * Persists a cell value for a given row id.
+     */
+    abstract setValue(value: DataTableCellType, columnId: string, rowId: RowId): Promise<void>;
+    /**
+     * Applies the current query modifiers to update the provider's presentation
+     * state.
+     */
+    abstract applyQuery(): Promise<void>;
+    /**
+     * Destroys the provider and releases resources.
+     */
+    abstract destroy(): void;
+    /**
+     * Returns the number of items before pagination has been applied.
+     */
+    getPrePaginationRowCount(): Promise<number>;
+    /**
+     * Helper method to assume the data type of a column based on the sample
+     * of the column data.
+     *
+     * @param columnSample
+     * The sample of the column data to determine the data type from.
+     *
+     * @param columnId
+     * The id of the column to determine the data type for.
+     */
+    protected static assumeColumnDataType(columnSample: DataTableColumnType, columnId: string): ColumnDataType;
+}
+/**
+ * A type for the row ID.
+ */
+export type RowId = number | string;
+/**
+ * A base interface for the data provider options (`grid.options.data`).
+ */
+export interface DataProviderOptions {
+    /**
+     * The type of the data provider.
+     *
+     * @default 'local'
+     */
+    providerType?: string;
+}
+export default DataProvider;

package/es-modules/Grid/Core/Data/DataProvider.js

@@ -0,0 +1,89 @@
+/* *
+ *
+ *  Data Provider abstract class
+ *
+ *  (c) 2020-2025 Highsoft AS
+ *
+ *  License: www.highcharts.com/license
+ *
+ *  !!!!!!! SOURCE GETS TRANSPILED BY TYPESCRIPT. EDIT TS FILE ONLY. !!!!!!!
+ *
+ *  Authors:
+ *  - Dawid Dragula
+ *
+ * */
+'use strict';
+import { defined } from '../../../Shared/Utilities.js';
+/**
+ * Base class for Grid data providers.
+ *
+ * Data providers are responsible for serving data to the grid, applying query
+ * modifiers and persisting edits.
+ */
+export class DataProvider {
+    /* *
+     *
+     *  Constructor
+     *
+     * */
+    constructor(queryingController, options) {
+        this.querying = queryingController;
+        this.options = options;
+    }
+    /* *
+     *
+     *  Methods
+     *
+     * */
+    /**
+     * Initializes the data provider.
+     */
+    init() {
+        return Promise.resolve();
+    }
+    /**
+     * Returns the number of items before pagination has been applied.
+     */
+    async getPrePaginationRowCount() {
+        return await this.getRowCount();
+    }
+    /**
+     * Helper method to assume the data type of a column based on the sample
+     * of the column data.
+     *
+     * @param columnSample
+     * The sample of the column data to determine the data type from.
+     *
+     * @param columnId
+     * The id of the column to determine the data type for.
+     */
+    static assumeColumnDataType(columnSample, columnId) {
+        for (let i = 0, iEnd = columnSample.length; i < iEnd; ++i) {
+            if (!defined(columnSample[i])) {
+                // If the data is null or undefined, we should look
+                // at the next value to determine the type.
+                continue;
+            }
+            switch (typeof columnSample[i]) {
+                case 'number':
+                    return 'number';
+                case 'boolean':
+                    return 'boolean';
+                default:
+                    return 'string';
+            }
+        }
+        // eslint-disable-next-line no-console
+        console.warn(`Column "${columnId}" sample does not contain any defined ` +
+            'values; defaulting dataType to "string". Set `dataType` option ' +
+            'for the column to determine the data type and avoid unnecessary ' +
+            'column scanning.');
+        return 'string';
+    }
+}
+/* *
+ *
+ * Default Export
+ *
+ * */
+export default DataProvider;

package/es-modules/Grid/Core/Data/DataProviderRegistry.d.ts

@@ -0,0 +1,20 @@
+import type { DataProviderTypeRegistry } from './DataProviderType';
+/**
+ * Record of data provider classes
+ */
+export declare const types: DataProviderTypeRegistry;
+/**
+ * Method used to register new data provider classes.
+ *
+ * @param key
+ * Registry key of the data provider class.
+ *
+ * @param DataProviderClass
+ * Data provider class (aka class constructor) to register.
+ */
+export declare function registerDataProvider<T extends keyof DataProviderTypeRegistry>(key: T, DataProviderClass: DataProviderTypeRegistry[T]): boolean;
+declare const _default: {
+    readonly registerDataProvider: typeof registerDataProvider;
+    readonly types: DataProviderTypeRegistry;
+};
+export default _default;

package/es-modules/Grid/Core/Data/DataProviderRegistry.js

@@ -0,0 +1,52 @@
+/* *
+ *
+ *  Data Provider Registry
+ *
+ *  (c) 2020-2025 Highsoft AS
+ *
+ *  License: www.highcharts.com/license
+ *
+ *  !!!!!!! SOURCE GETS TRANSPILED BY TYPESCRIPT. EDIT TS FILE ONLY. !!!!!!!
+ *
+ *  Authors:
+ *  - Dawid Dragula
+ *
+ * */
+'use strict';
+/* *
+ *
+ *  Constants
+ *
+ * */
+/**
+ * Record of data provider classes
+ */
+export const types = {};
+/* *
+ *
+ *  Functions
+ *
+ * */
+/**
+ * Method used to register new data provider classes.
+ *
+ * @param key
+ * Registry key of the data provider class.
+ *
+ * @param DataProviderClass
+ * Data provider class (aka class constructor) to register.
+ */
+export function registerDataProvider(key, DataProviderClass) {
+    return (!!key &&
+        !types[key] &&
+        !!(types[key] = DataProviderClass));
+}
+/* *
+ *
+ * Default Export
+ *
+ * */
+export default {
+    registerDataProvider,
+    types
+};

package/es-modules/Grid/Core/Data/DataProviderType.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Contains all possible class types of the data provider registry.
+ */
+export type DataProviderClassType = DataProviderTypeRegistry[keyof DataProviderTypeRegistry];
+/**
+ * Contains all possible types of the class registry.
+ */
+export type DataProviderType = DataProviderClassType['prototype'];
+/**
+ * Union of all possible options of the data providers in the registry.
+ */
+export type DataProviderOptionsType = DataProviderType['options'];
+/**
+ * Describes the class registry as a record object with class name and their
+ * class types (aka class constructor).
+ */
+export interface DataProviderTypeRegistry {
+}
+export default DataProviderType;

package/es-modules/Grid/Core/Data/DataProviderType.js

@@ -0,0 +1,15 @@
+/* *
+ *
+ *  Data Provider Type
+ *
+ *  (c) 2020-2025 Highsoft AS
+ *
+ *  License: www.highcharts.com/license
+ *
+ *  !!!!!!! SOURCE GETS TRANSPILED BY TYPESCRIPT. EDIT TS FILE ONLY. !!!!!!!
+ *
+ *  Authors:
+ *  - Dawid Dragula
+ *
+ * */
+export {};

package/es-modules/Grid/Core/Data/LocalDataProvider.d.ts

@@ -0,0 +1,165 @@
+import type { DataProviderOptions, RowId } from './DataProvider';
+import { DataTableValue } from '../../../Data/DataTableOptions';
+import type { ColumnDataType } from '../Table/Column';
+import type { RowObject as RowObjectType, CellType as DataTableCellType } from '../../../Data/DataTable';
+import type DataConnectorType from '../../../Data/Connectors/DataConnectorType';
+import type { DataConnectorTypeOptions } from '../../../Data/Connectors/DataConnectorType';
+import type { MakeOptional, TypedArray } from '../../../Shared/Types';
+import { DataProvider } from './DataProvider.js';
+import DataTable from '../../../Data/DataTable.js';
+/**
+ * Local data provider for the Grid.
+ *
+ * Uses a DataTable instances to serve data to the grid, applying query
+ * modifiers and persisting edits locally.
+ */
+export declare class LocalDataProvider extends DataProvider {
+    static readonly tableChangeEventNames: readonly ["afterDeleteColumns", "afterDeleteRows", "afterSetCell", "afterSetColumns", "afterSetRows"];
+    /**
+     * The provider options.
+     */
+    readonly options: LocalDataProviderOptions;
+    /**
+     * The original table. Mutations (e.g. setValue) are applied here.
+     */
+    private dataTable?;
+    /**
+     * The connector instance used to populate the table.
+     */
+    private connector?;
+    /**
+     * The presentation table after applying query modifiers.
+     */
+    private presentationTable?;
+    /**
+     * The row count before pagination is applied.
+     */
+    private prePaginationRowCount?;
+    /**
+     * Unbind callbacks for DataTable events.
+     */
+    private dataTableEventDestructors;
+    /**
+     * Unbind callbacks for connector events.
+     */
+    private connectorEventDestructors;
+    /**
+     * Map of row IDs (from `idColumn`) to original data table row indexes.
+     * Set only when `options.idColumn` is configured.
+     */
+    private originalRowIndexesMap?;
+    init(): Promise<void>;
+    private initDataTable;
+    private setDataTable;
+    private handleTableChange;
+    private clearDataTableEvents;
+    private clearConnector;
+    private initConnector;
+    getColumnIds(): Promise<string[]>;
+    /**
+     * Returns the row ID for a given local row index. If not found, returns
+     * `undefined`.
+     *
+     * If the `data.idColumn` option is set, the row ID is the value of the
+     * row in the column with the given ID. Otherwise, the row ID is the
+     * original row index.
+     *
+     * @param rowIndex
+     * The local (presentation table) row index to get the row ID for.
+     */
+    getRowId(rowIndex: number): Promise<RowId | undefined>;
+    /**
+     * Returns the local (presentation table) row index for a given row ID. If
+     * not found, returns `undefined`.
+     *
+     * @param rowId
+     * The row ID to get the row index for. If the `data.idColumn` option is
+     * set, the row ID is the value of the row in the column with the given ID.
+     * Otherwise, the row ID is the original row index.
+     */
+    getRowIndex(rowId: RowId): Promise<number | undefined>;
+    /**
+     * Returns the original row index for a given local row index.
+     *
+     * @param localRowIndex
+     * The local row index to get the original row index for.
+     */
+    getOriginalRowIndexFromLocal(localRowIndex: number): Promise<number | undefined>;
+    /**
+     * Returns the local (presentation table) row index for a given original
+     * data table row index.
+     *
+     * @param originalRowIndex
+     * The original data table row index to get the presentation table row index
+     * for.
+     */
+    getLocalRowIndexFromOriginal(originalRowIndex: number): Promise<number | undefined>;
+    getRowObject(rowIndex: number): Promise<RowObjectType | undefined>;
+    getPrePaginationRowCount(): Promise<number>;
+    getRowCount(): Promise<number>;
+    getValue(columnId: string, rowIndex: number): Promise<DataTableCellType>;
+    setValue(value: DataTableCellType, columnId: string, rowId: RowId): Promise<void>;
+    /**
+     * Applies querying modifiers and updates the presentation table.
+     */
+    applyQuery(): Promise<void>;
+    destroy(): void;
+    getColumnDataType(columnId: string): Promise<ColumnDataType>;
+    /**
+     * Returns the current data table. When `presentation` is `true`, returns
+     * the presentation table (after modifiers).
+     *
+     * @param presentation
+     * Whether to return the presentation table (after modifiers).
+     *
+     * @return
+     * The data table.
+     */
+    getDataTable(presentation?: boolean): DataTable | undefined;
+    /**
+     * Checks if the object is an instance of DataConnector.
+     *
+     * @param connector
+     * The object to check.
+     *
+     * @returns `true` if the object is an instance of DataConnector, `false`
+     * otherwise.
+     */
+    private static isConnectorInstance;
+}
+export type GridDataConnectorTypeOptions = MakeOptional<DataConnectorTypeOptions, 'id'>;
+export interface LocalDataProviderOptions extends DataProviderOptions {
+    providerType?: 'local';
+    /**
+     * Data table as a source of data for the grid.
+     */
+    dataTable?: DataTable;
+    /**
+     * Connector instance or options used to populate the data table.
+     */
+    connector?: GridDataConnectorTypeOptions | DataConnectorType;
+    /**
+     * Columns data to initialize the Grid with.
+     */
+    columns?: Record<string, Array<DataTableValue> | TypedArray>;
+    /**
+     * Automatically update the grid when the data table changes. It is disabled
+     * by default unles the pagination is enabled.
+     *
+     * Use this option if you want the polling to update the grid when the data
+     * table changes.
+     *
+     * @default false
+     */
+    updateOnChange?: boolean;
+    /**
+     * The column ID that contains the stable, unique row IDs. If not
+     * provided, the original row index is used as the row ID.
+     */
+    idColumn?: string;
+}
+declare module './DataProviderType' {
+    interface DataProviderTypeRegistry {
+        local: typeof LocalDataProvider;
+    }
+}