@highcharts/grid-pro 2.0.0

package/es-modules/Data/Connectors/DataConnector.d.ts

@@ -0,0 +1,204 @@
+import type { DataConnectorTypes } from './DataConnectorType';
+import type { DataConnectorOptions, MetaColumn, Metadata } from './DataConnectorOptions';
+import type DataEvent from '../DataEvent';
+import type DataConverterType from '../Converters/DataConverterType';
+import DataConverter from '../Converters/DataConverter.js';
+import DataTable from '../DataTable.js';
+/**
+ * Abstract class providing an interface for managing a DataConnector.
+ */
+declare abstract class DataConnector implements DataEvent.Emitter<DataConnector.Event> {
+    /**
+     * The DataConverter responsible for handling conversion of provided data to
+     * a DataConnector.
+     */
+    converter?: DataConverter;
+    /**
+     * Metadata to describe the connector and the content of columns.
+     */
+    readonly metadata: Metadata;
+    /**
+     * Tables managed by this DataConnector instance.
+     */
+    readonly dataTables: Record<string, DataTable>;
+    /**
+     * The options of the connector.
+     */
+    readonly options: DataConnectorOptions;
+    /**
+     * ID of the polling timeout.
+     */
+    private _polling?;
+    /**
+     * Whether the connector is currently polling for new data.
+     */
+    get polling(): boolean;
+    /**
+     * The polling controller used to abort the request when data polling stops.
+     * It gets assigned when data polling starts.
+     */
+    pollingController?: AbortController;
+    /**
+     * Constructor for the connector class.
+     *
+     * @param {DataConnectorOptions} [options]
+     * Options to use in the connector.
+     */
+    constructor(options: DataConnectorOptions);
+    /**
+     * Returns a single data table instance based on the provided key.
+     * Otherwise, returns the first data table.
+     *
+     * @param {string} [key]
+     * The data table key.
+     *
+     * @return {DataTable}
+     * The data table instance.
+     */
+    getTable(key?: string): DataTable;
+    /**
+     * Method for adding metadata for a single column.
+     *
+     * @param {string} name
+     * The name of the column to be described.
+     *
+     * @param {DataConnector.MetaColumn} columnMeta
+     * The metadata to apply to the column.
+     */
+    describeColumn(name: string, columnMeta: MetaColumn): void;
+    /**
+     * Method for applying columns meta information to the whole DataConnector.
+     *
+     * @param {Highcharts.Dictionary<DataConnector.MetaColumn>} columns
+     * Pairs of column names and MetaColumn objects.
+     */
+    describeColumns(columns: Record<string, MetaColumn>): void;
+    /**
+     * Returns the order of columns.
+     *
+     * @return {string[] | undefined}
+     * Order of columns.
+     */
+    getColumnOrder(): (string[] | undefined);
+    /**
+     * Retrieves the columns of the dataTable,
+     * applies column order from meta.
+     *
+     * @return {Highcharts.DataTableColumnCollection}
+     * An object with the properties `columnIds` and `columnValues`
+     */
+    getSortedColumns(): DataTable.ColumnCollection;
+    /**
+     * Sets the index and order of columns.
+     *
+     * @param {Array<string>} columnIds
+     * Order of columns.
+     */
+    setColumnOrder(columnIds: Array<string>): void;
+    /**
+     * The default load method, which fires the `afterLoad` event
+     *
+     * @return {Promise<DataConnector>}
+     * The loaded connector.
+     *
+     * @emits DataConnector#afterLoad
+     */
+    load(): Promise<this>;
+    /**
+     * Applies the data modifiers to the data tables according to the
+     * connector data tables options.
+     */
+    applyTableModifiers(): Promise<this>;
+    /**
+     * Starts polling new data after the specific time span in milliseconds.
+     *
+     * @param {number} refreshTime
+     * Refresh time in milliseconds between polls.
+     */
+    startPolling(refreshTime?: number): void;
+    /**
+     * Stops polling data. Shouldn't be performed if polling is already stopped.
+     */
+    stopPolling(): void;
+    /**
+     * Emits an event on the connector to all registered callbacks of this
+     * event.
+     *
+     * @param {DataConnector.Event} e
+     * Event object containing additional event information.
+     */
+    emit(e: DataConnector.Event): void;
+    /**
+     * Registers a callback for a specific connector event.
+     *
+     * @param type
+     * Event type.
+     *
+     * @param callback
+     * Function to register for the connector callback.
+     *
+     * @return {Function}
+     * Function to unregister callback from the connector event.
+     */
+    on<T extends DataConnector.Event['type']>(type: T, callback: DataEvent.Callback<this, Extract<DataConnector.Event, {
+        type: T;
+    }>>): Function;
+    /**
+     * Iterates over the dataTables and initiates the corresponding converters.
+     * Updates the dataTables and assigns the first converter.
+     *
+     * @param {T}[data]
+     * Data specific to the corresponding converter.
+     *
+     * @param {DataConnector.CreateConverterFunction}[createConverter]
+     * Creates a specific converter combining the dataTable options.
+     *
+     * @param {DataConnector.ParseDataFunction<T>}[parseData]
+     * Runs the converter parse method with the specific data type.
+     */
+    initConverters<T>(data: T, createConverter: DataConnector.CreateConverterFunction, parseData: DataConnector.ParseDataFunction<T>): void;
+}
+declare namespace DataConnector {
+    /**
+     * The event type that is provided on events within DataConnector.
+     */
+    interface Event extends DataEvent {
+        readonly type: 'loadError' | 'load' | 'afterLoad';
+        readonly error?: string | Error;
+    }
+    /**
+     * Creates a specific converter combining the dataTable options.
+     */
+    interface CreateConverterFunction {
+        (key: string): DataConverterType;
+    }
+    /**
+     * Runs the converter parse method with the specific data type.
+     */
+    interface ParseDataFunction<T> {
+        (converter: DataConverterType, data: T): DataTable.ColumnCollection;
+    }
+    /**
+     * Registry as a record object with connector names and their class.
+     */
+    const types: DataConnectorTypes;
+    /**
+     * Adds a connector class to the registry. The connector has to provide the
+     * `DataConnector.options` property and the `DataConnector.load` method to
+     * modify the table.
+     *
+     * @private
+     *
+     * @param {string} key
+     * Registry key of the connector class.
+     *
+     * @param {DataConnectorType} DataConnectorClass
+     * Connector class (aka class constructor) to register.
+     *
+     * @return {boolean}
+     * Returns true, if the registration was successful. False is returned, if
+     * their is already a connector registered with this key.
+     */
+    function registerType<T extends keyof DataConnectorTypes>(key: T, DataConnectorClass: DataConnectorTypes[T]): boolean;
+}
+export default DataConnector;

package/es-modules/Data/Connectors/DataConnector.js

@@ -0,0 +1,345 @@
+/* *
+ *
+ *  (c) 2009-2025 Highsoft AS
+ *
+ *  License: www.highcharts.com/license
+ *
+ *  !!!!!!! SOURCE GETS TRANSPILED BY TYPESCRIPT. EDIT TS FILE ONLY. !!!!!!!
+ *
+ *  Authors:
+ *  - Sophie Bremer
+ *  - Wojciech Chmiel
+ *  - Gøran Slettemark
+ *  - Dawid Dragula
+ *  - Kamil Kubik
+ *
+ * */
+'use strict';
+import DataModifier from '../Modifiers/DataModifier.js';
+import DataTable from '../DataTable.js';
+import U from '../../Core/Utilities.js';
+const { addEvent, fireEvent, merge, pick } = U;
+/* *
+ *
+ *  Class
+ *
+ * */
+/**
+ * Abstract class providing an interface for managing a DataConnector.
+ */
+class DataConnector {
+    /**
+     * Whether the connector is currently polling for new data.
+     */
+    get polling() {
+        return !!this._polling;
+    }
+    /* *
+     *
+     *  Constructor
+     *
+     * */
+    /**
+     * Constructor for the connector class.
+     *
+     * @param {DataConnectorOptions} [options]
+     * Options to use in the connector.
+     */
+    constructor(options) {
+        /**
+         * Tables managed by this DataConnector instance.
+         */
+        this.dataTables = {};
+        /**
+         * Helper flag for detecting whether the data connector is loaded.
+         * @internal
+         */
+        this.loaded = false;
+        this.metadata = options.metadata || { columns: {} };
+        this.options = options;
+        // Create a data table for each defined in the dataTables user options.
+        const dataTables = options?.dataTables;
+        let dataTableIndex = 0;
+        if (options.options) {
+            // eslint-disable-next-line no-console
+            console.error('The `DataConnectorOptions.options` property was removed in Dashboards v4.0.0. Check how to upgrade your connector to use the new options structure here: https://api.highcharts.com/dashboards/#interfaces/Data_DataTableOptions.DataTableOptions-1');
+        }
+        if (dataTables && dataTables?.length > 0) {
+            for (let i = 0, iEnd = dataTables.length; i < iEnd; ++i) {
+                const dataTable = dataTables[i];
+                const key = dataTable?.key;
+                this.dataTables[key ?? dataTableIndex] =
+                    new DataTable(dataTable);
+                if (!key) {
+                    dataTableIndex++;
+                }
+            }
+            // If user options dataTables is not defined, generate a default table.
+        }
+        else {
+            this.dataTables[0] = new DataTable({
+                id: options.id // Required by DataTableCore
+            });
+        }
+    }
+    /* *
+     *
+     *  Methods
+     *
+     * */
+    /**
+     * Returns a single data table instance based on the provided key.
+     * Otherwise, returns the first data table.
+     *
+     * @param {string} [key]
+     * The data table key.
+     *
+     * @return {DataTable}
+     * The data table instance.
+     */
+    getTable(key) {
+        if (key) {
+            return this.dataTables[key];
+        }
+        return Object.values(this.dataTables)[0];
+    }
+    /**
+     * Method for adding metadata for a single column.
+     *
+     * @param {string} name
+     * The name of the column to be described.
+     *
+     * @param {DataConnector.MetaColumn} columnMeta
+     * The metadata to apply to the column.
+     */
+    describeColumn(name, columnMeta) {
+        const connector = this;
+        const columns = connector.metadata.columns;
+        columns[name] = merge(columns[name] || {}, columnMeta);
+    }
+    /**
+     * Method for applying columns meta information to the whole DataConnector.
+     *
+     * @param {Highcharts.Dictionary<DataConnector.MetaColumn>} columns
+     * Pairs of column names and MetaColumn objects.
+     */
+    describeColumns(columns) {
+        const connector = this;
+        const columnIds = Object.keys(columns);
+        let columnId;
+        while (typeof (columnId = columnIds.pop()) === 'string') {
+            connector.describeColumn(columnId, columns[columnId]);
+        }
+    }
+    /**
+     * Returns the order of columns.
+     *
+     * @return {string[] | undefined}
+     * Order of columns.
+     */
+    getColumnOrder() {
+        const connector = this, columns = connector.metadata.columns, names = Object.keys(columns || {});
+        if (names.length) {
+            return names.sort((a, b) => (pick(columns[a].index, 0) - pick(columns[b].index, 0)));
+        }
+    }
+    /**
+     * Retrieves the columns of the dataTable,
+     * applies column order from meta.
+     *
+     * @return {Highcharts.DataTableColumnCollection}
+     * An object with the properties `columnIds` and `columnValues`
+     */
+    getSortedColumns() {
+        return this.getTable().getColumns(this.getColumnOrder());
+    }
+    /**
+     * Sets the index and order of columns.
+     *
+     * @param {Array<string>} columnIds
+     * Order of columns.
+     */
+    setColumnOrder(columnIds) {
+        const connector = this;
+        for (let i = 0, iEnd = columnIds.length; i < iEnd; ++i) {
+            connector.describeColumn(columnIds[i], { index: i });
+        }
+    }
+    /**
+     * The default load method, which fires the `afterLoad` event
+     *
+     * @return {Promise<DataConnector>}
+     * The loaded connector.
+     *
+     * @emits DataConnector#afterLoad
+     */
+    load() {
+        this.emit({ type: 'afterLoad' });
+        return Promise.resolve(this);
+    }
+    /**
+     * Applies the data modifiers to the data tables according to the
+     * connector data tables options.
+     */
+    async applyTableModifiers() {
+        const tableOptionsArray = this.options?.dataTables;
+        for (const [key, table] of Object.entries(this.dataTables)) {
+            // Take data modifier options from the corresponsing data table
+            // options, otherwise take the data modifier options from the
+            // connector options.
+            const dataModifierOptions = tableOptionsArray?.find((dataTable) => dataTable.key === key)?.dataModifier ?? this.options?.dataModifier;
+            const ModifierClass = (dataModifierOptions &&
+                DataModifier.types[dataModifierOptions.type]);
+            await table.setModifier(ModifierClass ?
+                new ModifierClass(dataModifierOptions) :
+                void 0);
+        }
+        return this;
+    }
+    /**
+     * Starts polling new data after the specific time span in milliseconds.
+     *
+     * @param {number} refreshTime
+     * Refresh time in milliseconds between polls.
+     */
+    startPolling(refreshTime = 1000) {
+        const connector = this;
+        // Assign a new abort controller.
+        this.pollingController = new AbortController();
+        // Clear the polling timeout.
+        window.clearTimeout(connector._polling);
+        connector._polling = window.setTimeout(() => connector
+            .load()['catch']((error) => connector.emit({
+            type: 'loadError',
+            error
+        }))
+            .then(() => {
+            if (connector._polling) {
+                connector.startPolling(refreshTime);
+            }
+        }), refreshTime);
+    }
+    /**
+     * Stops polling data. Shouldn't be performed if polling is already stopped.
+     */
+    stopPolling() {
+        const connector = this;
+        if (!connector.polling) {
+            return;
+        }
+        // Abort the existing request.
+        connector?.pollingController?.abort();
+        // Clear the polling timeout.
+        window.clearTimeout(connector._polling);
+        delete connector._polling;
+    }
+    /**
+     * Emits an event on the connector to all registered callbacks of this
+     * event.
+     *
+     * @param {DataConnector.Event} e
+     * Event object containing additional event information.
+     */
+    emit(e) {
+        fireEvent(this, e.type, e);
+    }
+    /**
+     * Registers a callback for a specific connector event.
+     *
+     * @param type
+     * Event type.
+     *
+     * @param callback
+     * Function to register for the connector callback.
+     *
+     * @return {Function}
+     * Function to unregister callback from the connector event.
+     */
+    on(type, callback) {
+        return addEvent(this, type, callback);
+    }
+    /**
+     * Iterates over the dataTables and initiates the corresponding converters.
+     * Updates the dataTables and assigns the first converter.
+     *
+     * @param {T}[data]
+     * Data specific to the corresponding converter.
+     *
+     * @param {DataConnector.CreateConverterFunction}[createConverter]
+     * Creates a specific converter combining the dataTable options.
+     *
+     * @param {DataConnector.ParseDataFunction<T>}[parseData]
+     * Runs the converter parse method with the specific data type.
+     */
+    initConverters(data, createConverter, parseData) {
+        let index = 0;
+        for (const [key, table] of Object.entries(this.dataTables)) {
+            // Create a proper converter and parse its data.
+            const converter = createConverter(key);
+            const columns = parseData(converter, data);
+            // Update the dataTable.
+            table.deleteColumns();
+            table.setColumns(columns);
+            // Assign the first converter.
+            if (index === 0) {
+                this.converter = converter;
+            }
+            index++;
+        }
+    }
+}
+/* *
+ *
+ *  Class Namespace
+ *
+ * */
+(function (DataConnector) {
+    /* *
+     *
+     *  Declarations
+     *
+     * */
+    /* *
+     *
+     *  Constants
+     *
+     * */
+    /**
+     * Registry as a record object with connector names and their class.
+     */
+    DataConnector.types = {};
+    /* *
+     *
+     *  Functions
+     *
+     * */
+    /**
+     * Adds a connector class to the registry. The connector has to provide the
+     * `DataConnector.options` property and the `DataConnector.load` method to
+     * modify the table.
+     *
+     * @private
+     *
+     * @param {string} key
+     * Registry key of the connector class.
+     *
+     * @param {DataConnectorType} DataConnectorClass
+     * Connector class (aka class constructor) to register.
+     *
+     * @return {boolean}
+     * Returns true, if the registration was successful. False is returned, if
+     * their is already a connector registered with this key.
+     */
+    function registerType(key, DataConnectorClass) {
+        return (!!key &&
+            !DataConnector.types[key] &&
+            !!(DataConnector.types[key] = DataConnectorClass));
+    }
+    DataConnector.registerType = registerType;
+})(DataConnector || (DataConnector = {}));
+/* *
+ *
+ *  Default Export
+ *
+ * */
+export default DataConnector;

package/es-modules/Data/Connectors/DataConnectorOptions.d.ts

@@ -0,0 +1,87 @@
+/* *
+ *
+ *  (c) 2009-2025 Highsoft AS
+ *
+ *  License: www.highcharts.com/license
+ *
+ *  !!!!!!! SOURCE GETS TRANSPILED BY TYPESCRIPT. EDIT TS FILE ONLY. !!!!!!!
+ *
+ *  Authors:
+ *  - Sophie Bremer
+ *  - Karol Kolodziej
+ *  - Dawid Dragula
+ *  - Kamil Kubik
+ *
+ * */
+
+/* *
+ *
+ *  Imports
+ *
+ * */
+
+import type { DataTableValue } from '../DataTableOptions';
+import type { DataModifierTypeOptions } from '../Modifiers/DataModifierType';
+
+/* *
+ *
+ *  Declarations
+ *
+ * */
+
+/**
+ * Option of the DataConnector.
+ */
+export interface DataConnectorOptions {
+    id: string;
+    type: string;
+    dataTables?: DataTableConnectorOptions[];
+    dataModifier?: DataModifierTypeOptions;
+    metadata?: Metadata;
+
+    /**
+     * @internal
+     * @private
+     * @deprecated
+     * Removed in Dashboards v4.0.0
+     *
+     * {@link https://api.highcharts.com/dashboards/#interfaces/Data_Connectors_DataConnectorOptions.DataConnectorOptions-1 | Check how to upgrade your connector to use the new options structure}
+     */
+    options?: never;
+}
+
+export interface DataTableConnectorOptions {
+    key?: string;
+    dataModifier?: DataModifierTypeOptions;
+    firstRowAsNames?: boolean;
+    metadata?: Record<string, DataTableValue>;
+}
+
+/**
+ * Contains custom metadata related to the connector source, for example the
+ * column order on the source side.
+ */
+export interface Metadata {
+    /**
+     * Metadata entry containing the name of the column and a metadata object.
+     */
+    columns: Record<string, MetaColumn>;
+}
+
+/**
+ * Metadata for a specific column in the connector source.
+ */
+export interface MetaColumn {
+    dataType?: string;
+    defaultValue?: boolean | null | number | string;
+    index?: number;
+    title?: string;
+}
+
+/* *
+ *
+ *  Default Export
+ *
+ * */
+
+export default DataConnectorOptions;

package/es-modules/Data/Connectors/DataConnectorType.d.ts

@@ -0,0 +1,45 @@
+/* *
+ *
+ *  (c) 2009-2025 Highsoft AS
+ *
+ *  License: www.highcharts.com/license
+ *
+ *  !!!!!!! SOURCE GETS TRANSPILED BY TYPESCRIPT. EDIT TS FILE ONLY. !!!!!!!
+ *
+ *  Authors:
+ *  - Sophie Bremer
+ *
+ * */
+
+/* *
+ *
+ *  Declarations
+ *
+ * */
+
+/**
+ * Describes the connector registry as a record object with key and
+ * class constructor.
+ */
+export interface DataConnectorTypes {
+    // Nothing here yet
+}
+
+/**
+ * Contains all possible connector types.
+ */
+export type DataConnectorType =
+    DataConnectorTypes[keyof DataConnectorTypes]['prototype'];
+
+/**
+ * Options for specific data connector type.
+ */
+export type DataConnectorTypeOptions = DataConnectorType['options'];
+
+/* *
+ *
+ *  Default Export
+ *
+ * */
+
+export default DataConnectorType;