@highcharts/grid-pro 2.1.1 → 2.3.0

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

@@ -2,11 +2,11 @@
  *
  *  Highcharts Grid class
  *
- *  (c) 2020-2025 Highsoft AS
+ *  (c) 2020-2026 Highsoft AS
  *
- *  License: www.highcharts.com/license
+ *  A commercial license may be required depending on use.
+ *  See www.highcharts.com/license
  *
- *  !!!!!!! SOURCE GETS TRANSPILED BY TYPESCRIPT. EDIT TS FILE ONLY. !!!!!!!
  *
  *  Authors:
  *  - Dawid Dragula
@@ -16,17 +16,17 @@
 'use strict';
 import Accessibility from './Accessibility/Accessibility.js';
 import AST from '../../Core/Renderer/HTML/AST.js';
-import { defaultOptions } from './Defaults.js';
-import GridUtils from './GridUtils.js';
+import DataProviderRegistry from './Data/DataProviderRegistry.js';
 import DataTable from '../../Data/DataTable.js';
+import { defaultOptions } from './Defaults.js';
+import { makeHTMLElement, setHTMLContent, createOptionsProxy } from './GridUtils.js';
 import Table from './Table/Table.js';
-import U from '../../Core/Utilities.js';
 import QueryingController from './Querying/QueryingController.js';
 import Globals from './Globals.js';
 import TimeBase from '../../Shared/TimeBase.js';
 import Pagination from './Pagination/Pagination.js';
-const { makeHTMLElement, setHTMLContent } = GridUtils;
-const { defined, diffObjects, extend, fireEvent, getStyle, merge, pick } = U;
+import { defined, diffObjects, extend, fireEvent, merge, pick } from '../../Shared/Utilities.js';
+import { uniqueKey } from '../../Core/Utilities.js';
 /* *
  *
  *  Class
@@ -85,11 +85,6 @@ export class Grid {
          * The list of currently shown popups.
          */
         this.popups = new Set();
-        /**
-         * Functions that unregister events attached to the grid's data table,
-         * that need to be removed when the grid is destroyed.
-         */
-        this.dataTableEventDestructors = [];
         /**
          * Whether the Grid is rendered.
          */
@@ -100,9 +95,16 @@ export class Grid {
          * @internal
          */
         this.dirtyFlags = new Set();
+        /**
+         * Internal redraw queue used to prevent concurrent `redraw()` calls from
+         * interleaving async DOM work and corrupting the state (for example
+         * rendering duplicate pagination controls when `update()` is called
+         * multiple times without awaiting).
+         */
+        this.redrawQueue = Promise.resolve();
         this.renderTo = renderTo;
         this.loadUserOptions(options);
-        this.id = this.options?.id || U.uniqueKey();
+        this.id = this.options?.id || uniqueKey();
         this.querying = new QueryingController(this);
         this.locale = this.options?.lang?.locale || (this.container?.closest('[lang]')?.lang);
         this.time = new TimeBase(extend(this.options?.time, { locale: this.locale }), this.options?.lang);
@@ -118,6 +120,31 @@ export class Grid {
      *  Methods
      *
      * */
+    /**
+     * The data source of the Grid. It contains the original data table
+     * that was passed to the Grid.
+     *
+     * @deprecated Use `dataProvider` instead.
+     */
+    get dataTable() {
+        const dp = this.dataProvider;
+        if (dp && 'getDataTable' in dp) {
+            return dp.getDataTable();
+        }
+    }
+    /**
+     * The presentation table of the Grid. It contains a modified version
+     * of the data table that is used for rendering the Grid content. If
+     * not modified, just a reference to the original data table.
+     *
+     * @deprecated Use `dataProvider` instead.
+     */
+    get presentationTable() {
+        const dp = this.dataProvider;
+        if (dp && 'getDataTable' in dp) {
+            return dp.getDataTable(true);
+        }
+    }
     /*
      * Initializes the accessibility controller.
      */
@@ -153,8 +180,8 @@ export class Grid {
             throw new Error('Rendering div not found. It is unable to find the HTML ' +
                 'element to render the Grid in.');
         }
-        this.initialContainerHeight = getStyle(container, 'height', true) || 0;
         this.container = container;
+        this.container.style.minHeight = 0 + 'px';
         this.container.innerHTML = AST.emptyHTML;
         this.contentWrapper = makeHTMLElement('div', {
             className: Globals.getClassName('container')
@@ -195,6 +222,9 @@ export class Grid {
         merge(true, diff, diffObjects(newOptions, this.userOptions));
         this.userOptions = merge(this.userOptions, newOptions);
         this.options = merge(this.options ?? defaultOptions, this.userOptions);
+        this.viewport?.columns.forEach((column) => {
+            column.options = createOptionsProxy(this.columnOptionsMap?.[column.id]?.options ?? {}, this.options?.columnDefaults);
+        });
         return diff;
     }
     /**
@@ -330,7 +360,7 @@ export class Grid {
      * the ones that are currently defined in the user options. When `true`,
      * the columns not defined in the new options will be removed.
      */
-    async update(options = {}, redraw = true, oneToOne = false) {
+    update(options = {}, redraw = true, oneToOne = false) {
         fireEvent(this, 'beforeUpdate', {
             scope: 'grid',
             options,
@@ -341,20 +371,28 @@ export class Grid {
         const diff = this.loadUserOptions(options, oneToOne);
         const flags = this.dirtyFlags;
         if (viewport) {
-            if (!this.dataTable || 'dataTable' in diff) {
-                this.userOptions.dataTable = options.dataTable;
-                (this.options ?? {}).dataTable = options.dataTable;
-                this.loadDataTable();
-                // TODO: Sometimes it can be too much, so we need to check if
-                // the columns have changed or just their data. If just their
-                // data, we can just mark the grid.table as dirty instead of the
-                // whole grid.
+            if (!this.dataProvider ||
+                ('data' in diff) ||
+                ('dataTable' in diff)) {
+                if ( // Handle backward compatibility
+                diff.dataTable &&
+                    this.options?.dataTable &&
+                    this.options?.data?.providerType === 'local') {
+                    const userDT = this.options.dataTable;
+                    this.options.data.dataTable = 'clone' in userDT ?
+                        userDT : new DataTable(userDT);
+                }
+                this.loadDataProvider(); // Rebuild the data provider
+                // TODO(update): Sometimes it can be too much, so we need to
+                // check if the columns have changed or just their data. If
+                // just their data, we can just mark the grid.table as dirty
+                // instead of the whole grid.
                 flags.add('grid');
             }
             if ('columns' in diff) {
                 const ids = Object.keys(diff.columns ?? {});
                 for (const id of ids) {
-                    // TODO: Move this to the column update method.
+                    // TODO(update): Move this to the column update method.
                     this.loadColumnOptionDiffs(viewport, id, diff.columns?.[id]);
                     delete diff.columns?.[id];
                 }
@@ -371,7 +409,7 @@ export class Grid {
                     this.time.update({ locale: this.locale });
                 }
                 delete langDiff.locale;
-                // TODO: Add more lang diff checks here.
+                // TODO(update): Add more lang diff checks here.
                 if (Object.keys(langDiff).length > 0) {
                     flags.add('grid');
                 }
@@ -391,7 +429,7 @@ export class Grid {
                 this.pagination?.update(paginationDiff);
             }
             delete diff.pagination;
-            // TODO: Add more options that can be optimized here.
+            // TODO(update): Add more options that can be optimized here.
             if (Object.keys(diff).length > 0) {
                 flags.add('grid');
             }
@@ -399,15 +437,18 @@ export class Grid {
         else {
             flags.add('grid');
         }
+        const finish = () => {
+            fireEvent(this, 'afterUpdate', {
+                scope: 'grid',
+                options,
+                redraw,
+                oneToOne
+            });
+        };
         if (redraw) {
-            await this.redraw();
+            return this.redraw().then(finish);
         }
-        fireEvent(this, 'afterUpdate', {
-            scope: 'grid',
-            options,
-            redraw,
-            oneToOne
-        });
+        finish();
     }
     /**
      * Loads the column option diffs by updating the dirty flags.
@@ -439,8 +480,7 @@ export class Grid {
             const cellsDiff = columnDiff.cells ?? {};
             if ('format' in cellsDiff ||
                 'formatter' in cellsDiff ||
-                'className' in cellsDiff // TODO: check if this too
-            ) {
+                'className' in cellsDiff) {
                 // Optimization idea: list of columns to update
                 flags.add('rows');
             }
@@ -464,6 +504,7 @@ export class Grid {
             }
             delete sortingDiff.compare;
             delete sortingDiff.order;
+            delete sortingDiff.orderSequence;
             // Idea: sortable - redraw only header cell
             if (Object.keys(sortingDiff).length > 0) {
                 flags.add('grid');
@@ -493,50 +534,64 @@ export class Grid {
      * them minimizing the number of DOM operations.
      */
     async redraw() {
-        fireEvent(this, 'beforeRedraw');
-        const flags = this.dirtyFlags;
-        if (flags.has('grid')) {
-            return await this.render();
-        }
-        const { viewport: vp, pagination } = this;
-        const colResizing = vp?.columnResizing;
-        if (flags.has('sorting') ||
-            flags.has('filtering') ||
-            pagination?.isDirtyQuerying) {
-            this.querying.loadOptions();
-        }
-        if (colResizing?.isDirty) {
-            colResizing.loadColumns();
-        }
-        if (flags.has('rows') ||
-            flags.has('sorting') ||
-            flags.has('filtering') ||
-            pagination?.isDirtyQuerying) {
-            await vp?.updateRows();
-        }
-        else if (flags.has('reflow') ||
-            colResizing?.isDirty) {
-            vp?.reflow();
-        }
-        const columns = vp?.columns ?? [];
-        if (flags.has('sorting') ||
-            flags.has('filtering')) {
-            for (const column of columns) {
-                column.header?.toolbar?.refreshState();
+        const run = async () => {
+            fireEvent(this, 'beforeRedraw');
+            const flags = this.dirtyFlags;
+            const flagsToProcess = new Set(flags);
+            const { viewport: vp, pagination } = this;
+            const colResizing = vp?.columnResizing;
+            const paginationWasDirty = !!pagination?.isDirtyQuerying;
+            const colResizingWasDirty = !!colResizing?.isDirty;
+            if (flagsToProcess.has('grid')) {
+                await this.render(false);
+                for (const flag of flagsToProcess) {
+                    flags.delete(flag);
+                }
+                fireEvent(this, 'afterRedraw');
+                return;
             }
-        }
-        if (flags.has('filtering')) {
-            for (const column of columns) {
-                column.filtering?.refreshState();
+            await this.dataProvider?.init();
+            if (flagsToProcess.has('sorting') ||
+                flagsToProcess.has('filtering') ||
+                paginationWasDirty) {
+                this.querying.loadOptions();
             }
-        }
-        if (pagination?.isDirtyQuerying) {
-            pagination.updateControls(true);
-        }
-        delete pagination?.isDirtyQuerying;
-        delete colResizing?.isDirty;
-        flags.clear();
-        fireEvent(this, 'afterRedraw');
+            if (colResizingWasDirty) {
+                colResizing?.loadColumns();
+            }
+            if (flagsToProcess.has('rows') ||
+                flagsToProcess.has('sorting') ||
+                flagsToProcess.has('filtering') ||
+                paginationWasDirty) {
+                await vp?.updateRows();
+            }
+            else if (flagsToProcess.has('reflow') ||
+                colResizingWasDirty) {
+                vp?.reflow();
+            }
+            const columns = vp?.columns ?? [];
+            if (flagsToProcess.has('sorting') ||
+                flagsToProcess.has('filtering')) {
+                for (const column of columns) {
+                    column.header?.toolbar?.refreshState();
+                }
+            }
+            if (flagsToProcess.has('filtering')) {
+                for (const column of columns) {
+                    column.filtering?.refreshState();
+                }
+            }
+            pagination?.redraw();
+            delete colResizing?.isDirty;
+            for (const flag of ['sorting', 'filtering']) {
+                flags.delete(flag);
+            }
+            fireEvent(this, 'afterRedraw');
+        };
+        const queued = this.redrawQueue.then(run, run);
+        // Keep the queue progressing even if one redraw fails.
+        this.redrawQueue = queued['catch'](() => void 0);
+        return queued;
     }
     /**
      * Updates the column of the Grid with new options.
@@ -583,19 +638,105 @@ export class Grid {
             columnId
         });
     }
-    async render() {
+    /**
+     * Sets the sorting order for one or more columns. Provide the sortings
+     * in priority order. Use `null` to clear sorting.
+     *
+     * @param sortings
+     * The sorting definition in priority order.
+     */
+    async setSorting(sortings) {
+        const viewport = this.viewport;
+        if (!viewport) {
+            return;
+        }
+        if (viewport.validator?.errorCell) {
+            return;
+        }
+        const normalized = (sortings || []).filter((sorting) => !!(sorting.columnId && sorting.order));
+        const sortingController = this.querying.sorting;
+        const previousSortings = sortingController.currentSortings || [];
+        const eventColumnIds = new Set();
+        for (const sorting of previousSortings) {
+            if (sorting.columnId) {
+                eventColumnIds.add(sorting.columnId);
+            }
+        }
+        for (const sorting of normalized) {
+            eventColumnIds.add(sorting.columnId);
+        }
+        const eventColumns = Array.from(eventColumnIds)
+            .map((columnId) => {
+            const column = viewport.getColumn(columnId);
+            if (!column) {
+                return null;
+            }
+            const order = normalized.find((sorting) => sorting.columnId === columnId)?.order || null;
+            return { column, order };
+        })
+            .filter((item) => !!item);
+        for (const { column, order } of eventColumns) {
+            [column, this].forEach((source) => {
+                fireEvent(source, 'beforeSort', {
+                    target: column,
+                    order
+                });
+            });
+        }
+        sortingController.setSorting(normalized);
+        await viewport.updateRows();
+        const currentSortings = sortingController.currentSortings || [];
+        const hasMultiple = currentSortings.length > 1;
+        for (const column of viewport.columns) {
+            const sortingIndex = currentSortings.findIndex((sorting) => sorting.columnId === column.id);
+            if (sortingIndex !== -1 && currentSortings[sortingIndex].order) {
+                const sorting = currentSortings[sortingIndex];
+                const sortingOptions = {
+                    order: sorting.order
+                };
+                if (hasMultiple) {
+                    sortingOptions.priority = sortingIndex + 1;
+                }
+                column.setOptions({ sorting: sortingOptions });
+                if (!hasMultiple) {
+                    delete column.options.sorting?.priority;
+                }
+            }
+            else {
+                delete column.options.sorting?.order;
+                delete column.options.sorting?.priority;
+                if (column.options.sorting &&
+                    Object.keys(column.options.sorting).length < 1) {
+                    delete column.options.sorting;
+                }
+            }
+            column.sorting?.refreshHeaderAttributes();
+        }
+        this.accessibility?.userSortedColumn(currentSortings[0]?.order || null);
+        for (const { column, order } of eventColumns) {
+            [column, this].forEach((source) => {
+                fireEvent(source, 'afterSort', {
+                    target: column,
+                    order
+                });
+            });
+        }
+    }
+    async render(clearDirtyFlags = true) {
         if (this.isRendered) {
             this.destroy(true);
         }
-        this.loadDataTable();
+        await this.loadDataProvider().init();
         this.initContainer(this.renderTo);
         this.initAccessibility();
         this.initPagination();
         this.querying.loadOptions();
         await this.querying.proceed();
-        this.renderViewport();
+        await this.renderViewport();
         this.isRendered = true;
-        this.dirtyFlags.clear();
+        if (clearDirtyFlags) {
+            this.dirtyFlags.clear();
+        }
     }
     /**
      * Hovers the row with the provided index. It removes the hover effect from
@@ -685,20 +826,19 @@ export class Grid {
      */
     renderCaption() {
         const captionOptions = this.options?.caption;
-        const captionText = captionOptions?.text;
-        if (!captionText) {
+        if (!captionOptions?.text || !this.contentWrapper) {
             return;
         }
-        // Create a caption element.
-        this.captionElement = makeHTMLElement('div', {
-            className: Globals.getClassName('captionElement'),
-            id: this.id + '-caption'
-        }, this.contentWrapper);
-        // Render the caption element content.
-        setHTMLContent(this.captionElement, captionText);
-        if (captionOptions.className) {
-            this.captionElement.classList.add(...captionOptions.className.split(/\s+/g));
-        }
+        const tag = captionOptions.htmlTag?.toLowerCase();
+        const tagName = tag && AST.allowedTags.includes(tag) ? tag : 'div';
+        const defaultClass = Globals.getClassName('captionElement');
+        const className = captionOptions.className ?
+            `${defaultClass} ${captionOptions.className}` : defaultClass;
+        this.captionElement = new AST([{
+                tagName,
+                attributes: { 'class': className, id: this.id + '-caption' },
+                textContent: captionOptions.text
+            }]).addToDOM(this.contentWrapper);
     }
     /**
      * Render description under the grid.
@@ -741,11 +881,11 @@ export class Grid {
      * rendered, it will be destroyed and re-rendered with the new data.
      * @internal
      */
-    renderViewport() {
+    async renderViewport() {
         const viewportMeta = this.viewport?.getStateMeta();
         const pagination = this.pagination;
         const paginationPosition = pagination?.options?.position;
-        this.enabledColumns = this.getEnabledColumnIDs();
+        this.enabledColumns = await this.getEnabledColumnIDs();
         this.credits?.destroy();
         this.viewport?.destroy();
         delete this.viewport;
@@ -757,7 +897,8 @@ export class Grid {
             pagination?.render();
         }
         if (this.enabledColumns.length > 0) {
-            this.viewport = this.renderTable();
+            this.viewport = await this.renderTable();
+            this.viewport.tableElement.setAttribute('id', this.id);
             if (viewportMeta && this.viewport) {
                 this.viewport.applyStateMeta(viewportMeta);
             }
@@ -765,7 +906,7 @@ export class Grid {
         else {
             this.renderNoData();
         }
-        this.accessibility?.setA11yOptions();
+        await this.renderAccessibility();
         // Render bottom pagination, footer pagination,
         // or custom container pagination (after table).
         if (paginationPosition !== 'top') {
@@ -775,18 +916,33 @@ export class Grid {
         fireEvent(this, 'afterRenderViewport');
         this.viewport?.reflow();
     }
+    /**
+     * Renders the Grid accessibility.
+     * @internal
+     */
+    async renderAccessibility() {
+        const accessibility = this.accessibility;
+        if (!accessibility) {
+            return;
+        }
+        await accessibility.setA11yOptions();
+        accessibility.addScreenReaderSection('before');
+        accessibility.addScreenReaderSection('after');
+    }
     /**
      * Renders the table (viewport) of the Grid.
      *
      * @returns
      * The newly rendered table (viewport) of the Grid.
      */
-    renderTable() {
+    async renderTable() {
         this.tableElement = makeHTMLElement('table', {
             className: Globals.getClassName('tableElement')
         }, this.contentWrapper);
         this.tableElement.setAttribute('role', 'grid');
-        return new Table(this, this.tableElement);
+        const table = new Table(this, this.tableElement);
+        await table.init();
+        return table;
     }
     /**
      * Renders a message that there is no data to display.
@@ -801,12 +957,12 @@ export class Grid {
      * Returns the array of IDs of columns that should be displayed in the data
      * grid, in the correct order.
      */
-    getEnabledColumnIDs() {
+    async getEnabledColumnIDs() {
         const { columnOptionsMap } = this;
         const header = this.options?.header;
         const headerColumns = this.getColumnIds(header || [], false);
         const columnsIncluded = this.options?.rendering?.columns?.included || (headerColumns && headerColumns.length > 0 ?
-            headerColumns : this.dataTable?.getColumnIds());
+            headerColumns : await this.dataProvider?.getColumnIds());
         if (!columnsIncluded?.length) {
             return [];
         }
@@ -823,37 +979,25 @@ export class Grid {
         }
         return result;
     }
-    /**
-     * Loads the data table of the Grid. If the data table is passed as a
-     * reference, it should be used instead of creating a new one.
-     */
-    loadDataTable() {
+    loadDataProvider() {
+        this.dataProvider?.destroy();
         this.querying.shouldBeUpdated = true;
-        // Unregister all events attached to the previous data table.
-        this.dataTableEventDestructors.forEach((fn) => fn());
-        const tableOptions = this.options?.dataTable;
-        // If the table is passed as a reference, it should be used instead of
-        // creating a new one.
-        if (tableOptions?.clone) {
-            this.dataTable = tableOptions;
-            this.presentationTable = this.dataTable.getModified();
-            return;
-        }
-        const dt = this.dataTable = this.presentationTable =
-            new DataTable(tableOptions);
-        // If the data table is modified, mark the querying controller to be
-        // updated on the next proceed.
-        [
-            'afterDeleteColumns',
-            'afterDeleteRows',
-            'afterSetCell',
-            'afterSetColumns',
-            'afterSetRows'
-        ].forEach((eventName) => {
-            this.dataTableEventDestructors.push(dt.on(eventName, () => {
-                this.querying.shouldBeUpdated = true;
-            }));
-        });
+        const userDT = this.options?.dataTable;
+        const dataOptions = this.options?.data ?? {
+            providerType: 'local',
+            dataTable: userDT ?? {}
+        };
+        // Just for the backward compatibility, remove in the future
+        if (dataOptions.providerType === 'local' &&
+            !dataOptions.dataTable && userDT) {
+            dataOptions.dataTable = 'clone' in userDT ?
+                userDT : new DataTable(userDT);
+        }
+        // End of backward compatibility snippet
+        const DataProviderConstructor = DataProviderRegistry.types[dataOptions.providerType ?? 'local'] ??
+            DataProviderRegistry.types.local;
+        this.dataProvider = new DataProviderConstructor(this.querying, dataOptions);
+        return this.dataProvider;
     }
     /**
      * Extracts all references to columnIds on all levels below defined level
@@ -890,9 +1034,10 @@ export class Grid {
      * after destruction by calling the `render` method.
      */
     destroy(onlyDOM = false) {
+        fireEvent(this, 'beforeDestroy');
         this.isRendered = false;
         const dgIndex = Grid.grids.findIndex((dg) => dg === this);
-        this.dataTableEventDestructors.forEach((fn) => fn());
+        this.dataProvider?.destroy();
         this.accessibility?.destroy();
         this.pagination?.destroy();
         this.viewport?.destroy();
@@ -943,6 +1088,11 @@ export class Grid {
     /**
      * Returns the grid data as a JSON string.
      *
+     * **Note:** This method only works with `LocalDataProvider`.
+     * For other data providers, use your data source directly.
+     *
+     * @deprecated
+     *
      * @param modified
      * Whether to return the modified data table (after filtering/sorting/etc.)
      * or the unmodified, original one. Default value is set to `true`.
@@ -951,7 +1101,14 @@ export class Grid {
      * JSON representation of the data
      */
     getData(modified = true) {
-        const dataTable = modified ? this.presentationTable : this.dataTable;
+        if (!this.dataProvider || !('getDataTable' in this.dataProvider)) {
+            // eslint-disable-next-line no-console
+            console.warn('getData() works only with LocalDataProvider.');
+            return JSON.stringify({
+                error: 'getData() works only with LocalDataProvider.'
+            }, null, 2);
+        }
+        const dataTable = this.dataProvider.getDataTable(modified);
         const tableColumns = dataTable?.columns;
         const outputColumns = {};
         if (!this.enabledColumns || !tableColumns) {
@@ -993,12 +1150,35 @@ export class Grid {
      * Grid options.
      */
     getOptions(onlyUserOptions = true) {
-        const options = onlyUserOptions ? merge(this.userOptions) : merge(this.options);
-        if (options.dataTable?.id) {
+        const options = onlyUserOptions ?
+            merge(this.userOptions) :
+            merge(this.options);
+        // Keep `getOptions()` serializable:
+        if (options.dataTable && 'clone' in options.dataTable) {
             options.dataTable = {
                 columns: options.dataTable.columns
             };
         }
+        if (options.data?.providerType === 'local') {
+            if (options.data?.dataTable && 'clone' in options.data.dataTable) {
+                options.data.columns = options.data.dataTable.columns;
+            }
+            if (options.data?.connector &&
+                'initConverters' in options.data.connector) {
+                options.data.connector = options.data.connector.options;
+            }
+        }
+        // Clean up the column options by removing the ones that have no other
+        // options than `id`:
+        const oldColumnOptions = options.columns;
+        if (oldColumnOptions) {
+            options.columns = [];
+            for (const columnOption of oldColumnOptions) {
+                if (Object.keys(columnOption).length > 1) {
+                    options.columns.push(columnOption);
+                }
+            }
+        }
         return options;
     }
 }