@highcharts/grid-pro 2.0.0

package/es-modules/Data/Converters/JSONConverter.js

@@ -0,0 +1,239 @@
+/* *
+ *
+ *  (c) 2009-2025 Highsoft AS
+ *
+ *  License: www.highcharts.com/license
+ *
+ *  !!!!!!! SOURCE GETS TRANSPILED BY TYPESCRIPT. EDIT TS FILE ONLY. !!!!!!!
+ *
+ *  Authors:
+ *  - Pawel Lysy
+ *  - Kamil Kubik
+ *
+ * */
+'use strict';
+import DataConverter from './DataConverter.js';
+import DataConverterUtils from './DataConverterUtils.js';
+import U from '../../Core/Utilities.js';
+const { error, isArray, merge, objectEach } = U;
+/* *
+ *
+ *  Class
+ *
+ * */
+/**
+ * Handles parsing and transforming JSON to a table.
+ *
+ * @private
+ */
+class JSONConverter extends DataConverter {
+    /* *
+     *
+     *  Constructor
+     *
+     * */
+    /**
+     * Constructs an instance of the JSON parser.
+     *
+     * @param {Partial<JSONConverterOptions>} [options]
+     * Options for the JSON parser.
+     */
+    constructor(options) {
+        const mergedOptions = merge(JSONConverter.defaultOptions, options);
+        super(mergedOptions);
+        /* *
+         *
+         *  Properties
+         *
+         * */
+        this.headerColumnIds = [];
+        this.headers = [];
+        this.options = mergedOptions;
+    }
+    /* *
+     *
+     *  Functions
+     *
+     * */
+    /**
+     * Initiates parsing of JSON structure.
+     *
+     * @param {Partial<JSONConverterOptions>}[options]
+     * Options for the parser
+     *
+     * @param {DataEvent.Detail} [eventDetail]
+     * Custom information for pending events.
+     *
+     * @emits JSONConverter#parse
+     * @emits JSONConverter#afterParse
+     */
+    parse(options, eventDetail) {
+        const converter = this;
+        options = merge(converter.options, options);
+        const { beforeParse, orientation, firstRowAsNames, columnIds } = options;
+        let data = options.data;
+        if (!data) {
+            return {};
+        }
+        converter.headers = [];
+        const columnsArray = [];
+        converter.emit({
+            type: 'parse',
+            columns: columnsArray,
+            detail: eventDetail,
+            headers: converter.headers
+        });
+        if (beforeParse) {
+            data = beforeParse(data);
+        }
+        data = data.slice();
+        if (orientation === 'columns') {
+            this.parseColumnsOrientation(columnsArray, data, firstRowAsNames, columnIds);
+        }
+        else if (orientation === 'rows') {
+            this.parseRowsOrientation(columnsArray, data, firstRowAsNames, columnIds);
+        }
+        converter.emit({
+            type: 'afterParse',
+            columns: columnsArray,
+            detail: eventDetail,
+            headers: converter.headers
+        });
+        return DataConverterUtils.getColumnsCollection(columnsArray, converter.headers);
+    }
+    /**
+     * Helper for parsing data in 'columns' orientation.
+     *
+     * @param {DataTable.BasicColumn[]} [columnsArray]
+     * Array of columns.
+     *
+     * @param {unknown[]} [data]
+     * Array of data elements.
+     *
+     * @param {Boolean} [firstRowAsNames]
+     * Defines row as names.
+     *
+     * @param {Array<string>} [columnIds]
+     * Column ids to retrieve.
+     *
+     * @return {void}
+     */
+    parseColumnsOrientation(columnsArray, data, firstRowAsNames, columnIds) {
+        const converter = this;
+        for (let i = 0, iEnd = data.length; i < iEnd; i++) {
+            const item = data[i];
+            if (!(Array.isArray(item))) {
+                return;
+            }
+            if (Array.isArray(converter.headers)) {
+                if (firstRowAsNames) {
+                    converter.headers.push(`${item.shift()}`);
+                }
+                else if (columnIds && Array.isArray(columnIds)) {
+                    converter.headers.push(columnIds[i]);
+                }
+                columnsArray.push(item);
+            }
+            else {
+                error('JSONConverter: Invalid `columnIds` option.', false);
+            }
+        }
+    }
+    /**
+     * Helper for parsing data in 'rows' orientation.
+     *
+     * @param {DataTable.BasicColumn[]} [columnsArray]
+     * Array of columns.
+     *
+     * Helper for parsing data in 'rows' orientation.
+     *
+     * @param {unknown[]} [data]
+     * Array of data elements.
+     *
+     * @param {Boolean} [firstRowAsNames]
+     * Defines row as names.
+     *
+     * @param {Array<string>} [columnIds]
+     * Column ids to retrieve.
+     *
+     * @return {DataTable.BasicColumn[]}
+     * Parsed columns.
+     */
+    parseRowsOrientation(columnsArray, data, firstRowAsNames, columnIds) {
+        const converter = this;
+        if (firstRowAsNames) {
+            converter.headers = data.shift();
+        }
+        else if (columnIds) {
+            converter.headerColumnIds = columnIds;
+        }
+        for (let rowIndex = 0, iEnd = data.length; rowIndex < iEnd; rowIndex++) {
+            let row = data[rowIndex];
+            if (!isArray(row)) {
+                row = this.convertItemToRow(row, columnIds);
+            }
+            for (let columnIndex = 0, jEnd = row.length; columnIndex < jEnd; columnIndex++) {
+                if (columnsArray.length < columnIndex + 1) {
+                    columnsArray.push([]);
+                }
+                columnsArray[columnIndex].push(row[columnIndex]);
+                // Create headers only once.
+                if (!firstRowAsNames && rowIndex === 0) {
+                    if (Array.isArray(converter.headerColumnIds)) {
+                        converter.headers.push(converter.headerColumnIds[columnIndex] ||
+                            columnIndex.toString());
+                    }
+                    else {
+                        error('JSONConverter: Invalid `columnIds` option.', false);
+                    }
+                }
+            }
+        }
+    }
+    /**
+     * Extracts a row from an object, using columnIds if provided.
+     *
+     * @param {Record<string, string|number>} [rowObj]
+     * Set of props.
+     *
+     * @param {Array<string>} [columnIds]
+     * Column ids to retrieve.
+     *
+     * @return {Array<string | number>}
+     * Row converted to array.
+     */
+    convertItemToRow(rowObj, columnIds) {
+        const converter = this;
+        if (columnIds && !(Array.isArray(columnIds))) {
+            const newRow = [];
+            objectEach(columnIds, (arrayWithPath, name) => {
+                newRow.push(arrayWithPath.reduce((acc, key) => acc[key], rowObj));
+                if (converter.headers.indexOf(name) < 0) {
+                    converter.headers.push(name);
+                }
+            });
+            return newRow;
+        }
+        converter.headerColumnIds = Object.keys(rowObj);
+        return Object.values(rowObj);
+    }
+}
+/* *
+ *
+ *  Static Properties
+ *
+ * */
+/**
+ * Default options
+ */
+JSONConverter.defaultOptions = {
+    ...DataConverter.defaultOptions,
+    orientation: 'rows'
+};
+DataConverter.registerType('JSON', JSONConverter);
+/* *
+ *
+ *  Default Export
+ *
+ * */
+export default JSONConverter;

package/es-modules/Data/Converters/JSONConverterOptions.d.ts

@@ -0,0 +1,52 @@
+/* *
+ *
+ *  (c) 2009-2025 Highsoft AS
+ *
+ *  License: www.highcharts.com/license
+ *
+ *  !!!!!!! SOURCE GETS TRANSPILED BY TYPESCRIPT. EDIT TS FILE ONLY. !!!!!!!
+ *
+ *  Authors:
+ *  - Kamil Kubik
+ *
+ * */
+
+/* *
+ *
+ *  Imports
+ *
+ * */
+
+import type {
+    ColumnIdsOptions,
+    JSONBeforeParseCallbackFunction
+} from '../Connectors/JSONConnectorOptions';
+
+import DataConverter from './DataConverter';
+
+/* *
+ *
+ *  Declarations
+ *
+ * */
+
+/**
+ * Options of the JSONConverter.
+ */
+export interface JSONConverterOptions extends DataConverter.Options {
+    orientation: 'columns' | 'rows';
+    data?: JSONData;
+    columnIds?: string[] | ColumnIdsOptions;
+    beforeParse?: JSONBeforeParseCallbackFunction;
+}
+
+export type JSONData =
+    (number | string)[][] | Record<string, number | string>[];
+
+/* *
+ *
+ *  Default Export
+ *
+ * */
+
+export default JSONConverterOptions;

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

@@ -0,0 +1,176 @@
+import type DataTable from './DataTable';
+/**
+ * This class manages state cursors pointing on {@link Data.DataTable}. It
+ * creates a relation between states of the user interface and the table cells,
+ * columns, or rows.
+ *
+ * @class
+ * @name Data.DataCursor
+ */
+declare class DataCursor {
+    constructor(stateMap?: DataCursor.StateMap);
+    /**
+     * Contains arguments currently in use of an emitting loop.
+     */
+    private readonly emittingRegister;
+    /**
+     * Contains listeners of states on tables.
+     */
+    readonly listenerMap: DataCursor.ListenerMap;
+    /**
+     * Contains lasting states that are kept over multiple changes.
+     */
+    readonly stateMap: DataCursor.StateMap;
+    /**
+     * This function registers a listener for a specific state and table.
+     *
+     * @example
+     * ```TypeScript
+     * dataCursor.addListener(myTable.id, 'hover', (e: DataCursor.Event) => {
+     *     if (e.cursor.type === 'position') {
+     *         console.log(`Hover over row #${e.cursor.row}.`);
+     *     }
+     * });
+     * ```
+     *
+     * @function #addListener
+     *
+     * @param {Data.DataCursor.TableId} tableId
+     * The ID of the table to listen to.
+     *
+     * @param {Data.DataCursor.State} state
+     * The state on the table to listen to.
+     *
+     * @param {Data.DataCursor.Listener} listener
+     * The listener to register.
+     *
+     * @return {Data.DataCursor}
+     * Returns the DataCursor instance for a call chain.
+     */
+    addListener(tableId: DataCursor.TableId, state: DataCursor.State, listener: DataCursor.Listener): this;
+    /**
+     * @private
+     */
+    private buildEmittingTag;
+    /**
+     * This function emits a state cursor related to a table. It will provide
+     * lasting state cursors of the table to listeners.
+     *
+     * @example
+     * ```ts
+     * dataCursor.emit(myTable, {
+     *     type: 'position',
+     *     column: 'city',
+     *     row: 4,
+     *     state: 'hover',
+     * });
+     * ```
+     *
+     * @param {Data.DataTable} table
+     * The related table of the cursor.
+     *
+     * @param {Data.DataCursor.Type} cursor
+     * The state cursor to emit.
+     *
+     * @param {Event} [event]
+     * Optional event information from a related source.
+     *
+     * @param {boolean} [lasting]
+     * Whether this state cursor should be kept until it is cleared with
+     * {@link DataCursor#remitCursor}.
+     *
+     * @return {Data.DataCursor}
+     * Returns the DataCursor instance for a call chain.
+     */
+    emitCursor(table: DataTable, cursor: DataCursor.Type, event?: Event, lasting?: boolean): this;
+    /**
+     * Removes a lasting state cursor.
+     *
+     * @function #remitCursor
+     *
+     * @param {string} tableId
+     * ID of the related cursor table.
+     *
+     * @param {Data.DataCursor.Type} cursor
+     * Copy or reference of the cursor.
+     *
+     * @return {Data.DataCursor}
+     * Returns the DataCursor instance for a call chain.
+     */
+    remitCursor(tableId: string, cursor: DataCursor.Type): this;
+    /**
+     * This function removes a listener.
+     *
+     * @function #addListener
+     *
+     * @param {Data.DataCursor.TableId} tableId
+     * The ID of the table the listener is connected to.
+     *
+     * @param {Data.DataCursor.State} state
+     * The state on the table the listener is listening to.
+     *
+     * @param {Data.DataCursor.Listener} listener
+     * The listener to deregister.
+     *
+     * @return {Data.DataCursor}
+     * Returns the DataCursor instance for a call chain.
+     */
+    removeListener(tableId: DataCursor.TableId, state: DataCursor.State, listener: DataCursor.Listener): this;
+}
+/**
+ * @class Data.DataCursor
+ */
+declare namespace DataCursor {
+    type Type = (Position | Range);
+    interface Position {
+        type: 'position';
+        column?: string;
+        row?: number;
+        state: State;
+        sourceId?: string;
+    }
+    interface Range {
+        type: 'range';
+        columns?: Array<string>;
+        firstRow: number;
+        lastRow: number;
+        state: State;
+        sourceId?: string;
+    }
+    interface Event {
+        cursor: Type;
+        cursors: Array<Type>;
+        event?: globalThis.Event;
+        table: DataTable;
+    }
+    type Listener = (this: DataCursor, e: Event) => void;
+    type ListenerMap = Record<TableId, Record<State, Array<Listener>>>;
+    type State = string;
+    type StateMap = Record<TableId, Record<State, Array<Type>>>;
+    type TableId = string;
+    type TableMap = Record<TableId, DataTable>;
+    /**
+     * Finds the index of an cursor in an array.
+     * @private
+     */
+    function getIndex(needle: DataCursor.Type, cursors: Array<DataCursor.Type>): number;
+    /**
+     * Checks whether two cursor share the same properties.
+     * @private
+     */
+    function isEqual(cursorA: Type, cursorB: Type): boolean;
+    /**
+     * Checks whether a cursor is in a range.
+     * @private
+     */
+    function isInRange(needle: Type, range: Type): boolean;
+    /**
+     * @private
+     */
+    function toPositions(cursor: Type): Array<Position>;
+    /**
+     * @private
+     */
+    function toRange(cursor: Type, defaultRange?: Range): Range;
+}
+export default DataCursor;