@highcharts/grid-pro 2.0.0

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

@@ -0,0 +1,374 @@
+/* *
+ *
+ *  (c) 2009-2025 Highsoft AS
+ *
+ *  License: www.highcharts.com/license
+ *
+ *  !!!!!!! SOURCE GETS TRANSPILED BY TYPESCRIPT. EDIT TS FILE ONLY. !!!!!!!
+ *
+ *  Authors:
+ *  - Torstein Hønsi
+ *  - Christer Vasseng
+ *  - Gøran Slettemark
+ *  - Sophie Bremer
+ *  - Kamil Kubik
+ *
+ * */
+'use strict';
+import DataConverter from './DataConverter.js';
+import DataConverterUtils from './DataConverterUtils.js';
+import U from '../../Core/Utilities.js';
+const { merge } = U;
+/* *
+ *
+ *  Class
+ *
+ * */
+/**
+ * Handles parsing and transforming CSV to a table.
+ *
+ * @private
+ */
+class CSVConverter extends DataConverter {
+    /* *
+     *
+     *  Constructor
+     *
+     * */
+    /**
+     * Constructs an instance of the CSV parser.
+     *
+     * @param {Partial<CSVConverterOptions>} [options]
+     * Options for the CSV parser.
+     */
+    constructor(options) {
+        const mergedOptions = merge(CSVConverter.defaultOptions, options);
+        super(mergedOptions);
+        /* *
+         *
+         *  Properties
+         *
+         * */
+        this.headers = [];
+        this.dataTypes = [];
+        this.options = mergedOptions;
+    }
+    /* *
+     *
+     *  Functions
+     *
+     * */
+    /**
+     * Parses the CSV string into a DataTable column collection.
+     * Handles line and item delimiters, optional header row, and
+     * applies pre-processing if a beforeParse callback is provided.
+     *
+     * @param {Partial<CSVConverterOptions>} [options]
+     * Options for the parser.
+     * @param {DataEvent.Detail} [eventDetail]
+     * Custom information for pending events.
+     * @return {DataTable.ColumnCollection}
+     * The parsed column collection.
+     *
+     * @emits CSVDataParser#parse
+     * @emits CSVDataParser#afterParse
+     */
+    parse(options, eventDetail) {
+        const converter = this, dataTypes = converter.dataTypes, parserOptions = merge(this.options, options), { beforeParse, lineDelimiter, firstRowAsNames, itemDelimiter } = parserOptions;
+        let lines, rowIt = 0, { csv, startRow, endRow } = parserOptions, column;
+        const columnsArray = [];
+        converter.emit({
+            type: 'parse',
+            columns: columnsArray,
+            detail: eventDetail,
+            headers: converter.headers
+        });
+        if (csv && beforeParse) {
+            csv = beforeParse(csv);
+        }
+        if (csv) {
+            lines = csv
+                .replace(/\r\n|\r/g, '\n') // Windows | Mac
+                .split(lineDelimiter || '\n');
+            if (!startRow || startRow < 0) {
+                startRow = 0;
+            }
+            if (!endRow || endRow >= lines.length) {
+                endRow = lines.length - 1;
+            }
+            if (!itemDelimiter) {
+                converter.guessedItemDelimiter =
+                    converter.guessDelimiter(lines);
+            }
+            // If the first row contain names, add them to the
+            // headers array and skip the row.
+            if (firstRowAsNames) {
+                const headers = lines[0].split(itemDelimiter || converter.guessedItemDelimiter || ',');
+                // Remove ""s from the headers
+                for (let i = 0; i < headers.length; i++) {
+                    headers[i] = headers[i].trim().replace(/^["']|["']$/g, '');
+                }
+                converter.headers = headers;
+                startRow++;
+            }
+            let offset = 0;
+            for (rowIt = startRow; rowIt <= endRow; rowIt++) {
+                if (lines[rowIt][0] === '#') {
+                    offset++;
+                }
+                else {
+                    converter.parseCSVRow(columnsArray, lines[rowIt], rowIt - startRow - offset);
+                }
+            }
+            if (dataTypes.length &&
+                dataTypes[0].length &&
+                dataTypes[0][1] === 'date' && // Format is a string date
+                !converter.options.dateFormat) {
+                converter.deduceDateFormat(columnsArray[0], null, true);
+            }
+            // Guess types.
+            for (let i = 0, iEnd = columnsArray.length; i < iEnd; ++i) {
+                column = columnsArray[i];
+                for (let j = 0, jEnd = column.length; j < jEnd; ++j) {
+                    if (column[j] && typeof column[j] === 'string') {
+                        let cellValue = converter.convertByType(column[j]);
+                        if (cellValue instanceof Date) {
+                            cellValue = cellValue.getTime();
+                        }
+                        columnsArray[i][j] = cellValue;
+                    }
+                }
+            }
+        }
+        // Normalize columns to same length to avoid truncation.
+        columnsArray.forEach((col) => {
+            col.length = Math.max(...columnsArray.map((c) => c.length));
+        });
+        converter.emit({
+            type: 'afterParse',
+            columns: columnsArray,
+            detail: eventDetail,
+            headers: converter.headers
+        });
+        return DataConverterUtils.getColumnsCollection(columnsArray, converter.headers);
+    }
+    /**
+     * Parses a single CSV row string into columns, handling delimiters,
+     * quoted values, data type inference, and column range selection.
+     */
+    parseCSVRow(columns, columnStr, rowNumber) {
+        const converter = this, dataTypes = converter.dataTypes, { startColumn, endColumn } = converter.options, itemDelimiter = (converter.options.itemDelimiter ||
+            converter.guessedItemDelimiter);
+        let { decimalPoint } = converter.options;
+        if (!decimalPoint || decimalPoint === itemDelimiter) {
+            decimalPoint = converter.guessedDecimalPoint || '.';
+        }
+        let i = 0, c = '', token = '', actualColumn = 0, column = 0;
+        const read = (j) => {
+            c = columnStr[j];
+        };
+        const pushType = (type) => {
+            if (dataTypes.length < column + 1) {
+                dataTypes.push([type]);
+            }
+            if (dataTypes[column][dataTypes[column].length - 1] !== type) {
+                dataTypes[column].push(type);
+            }
+        };
+        const push = () => {
+            if (startColumn > actualColumn || actualColumn > endColumn) {
+                // Skip this column, but increment the column count (#7272)
+                ++actualColumn;
+                token = '';
+                return;
+            }
+            // Save the type of the token.
+            if (typeof token === 'string') {
+                const parsedNumber = parseFloat(token);
+                if (!isNaN(parsedNumber) && isFinite(Number(token))) {
+                    token = parsedNumber;
+                    pushType('number');
+                }
+                else if (!isNaN(Date.parse(token))) {
+                    token = token.replace(/\//g, '-');
+                    pushType('date');
+                }
+                else {
+                    pushType('string');
+                }
+            }
+            else {
+                pushType('number');
+            }
+            if (columns.length < column + 1) {
+                columns.push([]);
+            }
+            // Try to apply the decimal point, and check if the token then is a
+            // number. If not, reapply the initial value
+            if (typeof token !== 'number' &&
+                DataConverterUtils.guessType(token, converter) !== 'number' &&
+                decimalPoint) {
+                const initialValue = token;
+                token = token.replace(decimalPoint, '.');
+                if (DataConverterUtils.guessType(token, converter) !== 'number') {
+                    token = initialValue;
+                }
+            }
+            columns[column][rowNumber] = token;
+            token = '';
+            ++column;
+            ++actualColumn;
+        };
+        if (!columnStr.trim().length) {
+            return;
+        }
+        if (columnStr.trim()[0] === '#') {
+            return;
+        }
+        for (; i < columnStr.length; i++) {
+            read(i);
+            if (c === '#') {
+                // If there are hexvalues remaining (#13283)
+                if (!/^#[A-F\d]{3,3}|[A-F\d]{6,6}/i.test(columnStr.substring(i))) {
+                    // The rest of the row is a comment
+                    push();
+                    return;
+                }
+            }
+            // Quoted string
+            if (c === '"') {
+                read(++i);
+                while (i < columnStr.length) {
+                    if (c === '"') {
+                        break;
+                    }
+                    token += c;
+                    read(++i);
+                }
+            }
+            else if (c === itemDelimiter) {
+                push();
+                // Actual column data
+            }
+            else {
+                token += c;
+            }
+        }
+        push();
+    }
+    /**
+     * Internal method that guesses the delimiter from the first
+     * 13 lines of the CSV
+     * @param {string[]} lines
+     * The CSV, split into lines
+     */
+    guessDelimiter(lines) {
+        let points = 0, commas = 0, guessed;
+        const potDelimiters = {
+            ',': 0,
+            ';': 0,
+            '\t': 0
+        }, linesCount = lines.length;
+        for (let i = 0; i < linesCount; i++) {
+            let inStr = false, c, cn, cl, token = '';
+            // We should be able to detect dateformats within 13 rows
+            if (i > 13) {
+                break;
+            }
+            const columnStr = lines[i];
+            for (let j = 0; j < columnStr.length; j++) {
+                c = columnStr[j];
+                cn = columnStr[j + 1];
+                cl = columnStr[j - 1];
+                if (c === '#') {
+                    // Skip the rest of the line - it's a comment
+                    break;
+                }
+                if (c === '"') {
+                    if (inStr) {
+                        if (cl !== '"' && cn !== '"') {
+                            while (cn === ' ' && j < columnStr.length) {
+                                cn = columnStr[++j];
+                            }
+                            // After parsing a string, the next non-blank
+                            // should be a delimiter if the CSV is properly
+                            // formed.
+                            if (typeof potDelimiters[cn] !== 'undefined') {
+                                potDelimiters[cn]++;
+                            }
+                            inStr = false;
+                        }
+                    }
+                    else {
+                        inStr = true;
+                    }
+                }
+                else if (typeof potDelimiters[c] !== 'undefined') {
+                    token = token.trim();
+                    if (!isNaN(Date.parse(token))) {
+                        potDelimiters[c]++;
+                    }
+                    else if (isNaN(Number(token)) ||
+                        !isFinite(Number(token))) {
+                        potDelimiters[c]++;
+                    }
+                    token = '';
+                }
+                else {
+                    token += c;
+                }
+                if (c === ',') {
+                    commas++;
+                }
+                if (c === '.') {
+                    points++;
+                }
+            }
+        }
+        // Count the potential delimiters.
+        // This could be improved by checking if the number of delimiters
+        // equals the number of columns - 1
+        if (potDelimiters[';'] > potDelimiters[',']) {
+            guessed = ';';
+        }
+        else if (potDelimiters[','] > potDelimiters[';']) {
+            guessed = ',';
+        }
+        else {
+            // No good guess could be made..
+            guessed = ',';
+        }
+        // Try to deduce the decimal point if it's not explicitly set.
+        // If both commas or points is > 0 there is likely an issue
+        if (points > commas) {
+            this.guessedDecimalPoint = '.';
+        }
+        else {
+            this.guessedDecimalPoint = ',';
+        }
+        return guessed;
+    }
+}
+/* *
+ *
+ *  Static Properties
+ *
+ * */
+/**
+ * Default options
+ */
+CSVConverter.defaultOptions = {
+    ...DataConverter.defaultOptions,
+    lineDelimiter: '\n',
+    startColumn: 0,
+    endColumn: Number.MAX_VALUE,
+    startRow: 0,
+    endRow: Number.MAX_VALUE
+};
+DataConverter.registerType('CSV', CSVConverter);
+/* *
+ *
+ *  Default Export
+ *
+ * */
+export default CSVConverter;

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

@@ -0,0 +1,53 @@
+/* *
+ *
+ *  (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 { CSVBeforeParseCallbackFunction } from '../Connectors/CSVConnectorOptions';
+
+import DataConverter from './DataConverter';
+
+/* *
+ *
+ *  Declarations
+ *
+ * */
+
+/**
+ * Options of the CSVConverter.
+ */
+export interface CSVConverterOptions extends DataConverter.Options {
+    startRow: number;
+    endRow: number;
+    startColumn: number;
+    endColumn: number;
+    csv?: string;
+    decimalPoint?: string;
+    itemDelimiter?: string;
+    lineDelimiter: string;
+    useLocalDecimalPoint?: boolean;
+    decimalRegex?: RegExp;
+    beforeParse?: CSVBeforeParseCallbackFunction;
+}
+
+/* *
+ *
+ *  Default Export
+ *
+ * */
+
+export default CSVConverterOptions;

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

@@ -0,0 +1,168 @@
+import type { DataConverterTypes } from './DataConverterType';
+import type DataEvent from '../DataEvent';
+import type { ColumnIdsOptions } from '../Connectors/JSONConnectorOptions';
+import DataTable from '../DataTable.js';
+/**
+ * Base class providing an interface and basic methods for a DataConverter
+ *
+ * @private
+ */
+declare class DataConverter implements DataEvent.Emitter<DataConverter.Event> {
+    /**
+     * Default options
+     */
+    protected static readonly defaultOptions: DataConverter.Options;
+    /**
+     * Constructs an instance of the DataConverter.
+     *
+     * @param {DataConverter.UserOptions} [options]
+     * Options for the DataConverter.
+     */
+    constructor(options?: DataConverter.UserOptions);
+    /**
+     * A collection of available date formats.
+     */
+    dateFormats: Record<string, DataConverter.DateFormatObject>;
+    /**
+     * Regular expression used in the trim method to change a decimal point.
+     */
+    decimalRegExp?: RegExp;
+    /**
+     * Options for the DataConverter.
+     */
+    readonly options: DataConverter.Options;
+    /**
+     * Converts a string value based on its guessed type.
+     *
+     * @param {*} value
+     * The value to examine.
+     *
+     * @return {number | string | Date}
+     * The converted value.
+     */
+    convertByType(value: DataConverter.Type): number | string | Date;
+    /**
+     * Tries to guess the date format
+     *  - Check if either month candidate exceeds 12
+     *  - Check if year is missing (use current year)
+     *  - Check if a shortened year format is used (e.g. 1/1/99)
+     *  - If no guess can be made, the user must be prompted
+     * data is the data to deduce a format based on
+     * @private
+     *
+     * @param {string[]} data
+     * Data to check the format.
+     *
+     * @param {number} limit
+     * Max data to check the format.
+     *
+     * @param {boolean} save
+     * Whether to save the date format in the converter options.
+     */
+    deduceDateFormat(data: string[], limit?: number | null, save?: boolean): string;
+    /**
+     * Emits an event on the DataConverter instance.
+     *
+     * @param {DataConverter.Event} [e]
+     * Event object containing additional event data
+     */
+    emit(e: DataConverter.Event): void;
+    /**
+     * Registers a callback for a specific event.
+     *
+     * @param {string} type
+     * Event type as a string.
+     *
+     * @param {DataEventEmitter.Callback} callback
+     * Function to register for an modifier callback.
+     *
+     * @return {Function}
+     * Function to unregister callback from the modifier event.
+     */
+    on<T extends DataConverter.Event['type']>(type: T, callback: DataEvent.Callback<this, Extract<DataConverter.Event, {
+        type: T;
+    }>>): Function;
+    /**
+     * Parse a date and return it as a number.
+     *
+     * @param {string} value
+     * Value to parse.
+     *
+     * @param {string} dateFormatProp
+     * Which of the predefined date formats
+     * to use to parse date values.
+     */
+    parseDate(value: string, dateFormatProp?: string): number;
+}
+/**
+ * Additionally provided types for events and conversion.
+ */
+declare namespace DataConverter {
+    /**
+     * The basic event object for a DataConverter instance.
+     * Valid types are `parse`, `afterParse`, and `parseError`
+     */
+    interface Event extends DataEvent {
+        readonly type: ('export' | 'afterExport' | 'exportError' | 'parse' | 'afterParse' | 'parseError');
+        readonly columns: DataTable.Column[];
+        readonly error?: string | Error;
+        readonly headers: string[] | ColumnIdsOptions;
+    }
+    interface DateFormatCallbackFunction {
+        (match: ReturnType<string['match']>): number;
+    }
+    interface DateFormatObject {
+        alternative?: string;
+        parser: DateFormatCallbackFunction;
+        regex: RegExp;
+    }
+    /**
+     * The shared options for all DataConverter instances
+     */
+    interface Options {
+        dateFormat?: string;
+        decimalPoint?: string;
+        firstRowAsNames: boolean;
+        /**
+         * A function to parse string representations of dates into JavaScript
+         * timestamps. If not set, the default implementation will be used.
+         */
+        parseDate?: DataConverter.ParseDateFunction;
+    }
+    /**
+     * A function to parse string representations of dates
+     * into JavaScript timestamps.
+     */
+    interface ParseDateFunction {
+        (dateValue: string): number;
+    }
+    /**
+     * Contains supported types to convert values from and to.
+     */
+    type Type = (boolean | null | number | string | DataTable | Date | undefined);
+    /**
+     * Options of the DataConverter.
+     */
+    type UserOptions = Partial<Options>;
+    /**
+     * Registry as a record object with connector names and their class.
+     */
+    const types: DataConverterTypes;
+    /**
+     * Adds a converter class to the registry.
+     *
+     * @private
+     *
+     * @param {string} key
+     * Registry key of the converter class.
+     *
+     * @param {DataConverterTypes} DataConverterClass
+     * Connector class (aka class constructor) to register.
+     *
+     * @return {boolean}
+     * Returns true, if the registration was successful. False is returned, if
+     * their is already a converter registered with this key.
+     */
+    function registerType<T extends keyof DataConverterTypes>(key: T, DataConverterClass: DataConverterTypes[T]): boolean;
+}
+export default DataConverter;