@highcharts/grid-pro 2.1.1 → 2.3.0

package/es-modules/Grid/Core/Table/Actions/ColumnSorting.js

@@ -2,11 +2,11 @@
  *
  *  Grid ColumnSorting 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
@@ -15,8 +15,7 @@
  * */
 'use strict';
 import Globals from '../../Globals.js';
-import U from '../../../../Core/Utilities.js';
-const { fireEvent } = U;
+import { fireEvent } from '../../../../Shared/Utilities.js';
 /* *
  *
  *  Class
@@ -42,25 +41,59 @@ class ColumnSorting {
      */
     constructor(column, headerCellElement) {
         /**
-         * Toggle sorting order for the column in the order: asc -> desc -> none
+         * Toggle sorting order for the column according to the configured
+         * sorting order sequence.
+         *
+         * @param e
+         * Optional mouse or keyboard event.
          */
-        this.toggle = () => {
+        this.toggle = (e) => {
             const viewport = this.column.viewport;
             const querying = viewport.grid.querying;
             const sortingController = querying.sorting;
-            const currentOrder = (sortingController.currentSorting?.columnId === this.column.id ?
-                sortingController.currentSorting.order : null) || 'none';
-            const consequents = {
-                none: 'asc',
-                asc: 'desc',
-                desc: null
-            };
-            void this.setOrder(consequents[currentOrder]);
+            const additive = !!e?.shiftKey;
+            let hasCurrentColumnSorting = false;
+            const currentOrder = (() => {
+                if (additive) {
+                    const currentSorting = sortingController.currentSortings?.find((sorting) => sorting.columnId === this.column.id);
+                    hasCurrentColumnSorting = !!currentSorting;
+                    return this.normalizeOrder(currentSorting?.order);
+                }
+                const currentSorting = sortingController.currentSorting;
+                hasCurrentColumnSorting =
+                    currentSorting?.columnId === this.column.id;
+                return hasCurrentColumnSorting ?
+                    this.normalizeOrder(currentSorting?.order) :
+                    null;
+            })();
+            const orderSequence = this.getOrderSequence();
+            if (orderSequence.length < 1) {
+                return;
+            }
+            let nextOrderIndex = 0;
+            const lastIndex = this.lastOrderSequenceIndex;
+            if (hasCurrentColumnSorting &&
+                typeof lastIndex === 'number' &&
+                orderSequence[lastIndex] === currentOrder) {
+                nextOrderIndex = (lastIndex + 1) % orderSequence.length;
+            }
+            else {
+                const currentOrderIndex = orderSequence.indexOf(currentOrder);
+                nextOrderIndex = (currentOrderIndex === -1 ?
+                    0 :
+                    (currentOrderIndex + 1) % orderSequence.length);
+            }
+            this.lastOrderSequenceIndex = nextOrderIndex;
+            const nextOrder = orderSequence[nextOrderIndex];
+            void this.setOrder(nextOrder, additive);
         };
         this.column = column;
         this.headerCellElement = headerCellElement;
         this.addHeaderElementAttributes();
-        if (column.options.sorting?.sortable) {
+        const sortingOptions = column.options.sorting;
+        const sortingEnabled = sortingOptions?.enabled ??
+            sortingOptions?.sortable;
+        if (sortingEnabled) {
             headerCellElement.classList.add(Globals.getClassName('columnSortable'));
         }
     }
@@ -76,19 +109,25 @@ class ColumnSorting {
         const col = this.column;
         const a11y = col.viewport.grid.accessibility;
         const sortingOptions = col.options.sorting;
-        const { currentSorting } = col.viewport.grid.querying.sorting;
+        const { currentSorting, currentSortings } = col.viewport.grid.querying.sorting;
         const sortedAscClassName = Globals.getClassName('columnSortedAsc');
         const sortedDescClassName = Globals.getClassName('columnSortedDesc');
         const el = this.headerCellElement;
-        if (currentSorting?.columnId !== col.id || !currentSorting?.order) {
+        const sortingEnabled = sortingOptions?.enabled ??
+            sortingOptions?.sortable;
+        const columnSorting = (currentSortings?.find((sorting) => sorting.columnId === col.id) ||
+            (currentSorting?.columnId === col.id ?
+                currentSorting :
+                void 0));
+        if (!columnSorting?.order) {
             el.classList.remove(sortedAscClassName);
             el.classList.remove(sortedDescClassName);
-            if (sortingOptions?.sortable) {
+            if (sortingEnabled) {
                 a11y?.setColumnSortState(el, 'none');
             }
             return;
         }
-        switch (currentSorting?.order) {
+        switch (columnSorting.order) {
             case 'asc':
                 el.classList.add(sortedAscClassName);
                 el.classList.remove(sortedDescClassName);
@@ -101,6 +140,12 @@ class ColumnSorting {
                 break;
         }
     }
+    /**
+     * Refreshes the sorting-related header attributes and classes.
+     */
+    refreshHeaderAttributes() {
+        this.addHeaderElementAttributes();
+    }
     /**
      * Updates the column options with the new sorting state.
      *
@@ -108,18 +153,51 @@ class ColumnSorting {
      * The column to update.
      */
     updateColumnOptions(col) {
-        const order = col.viewport.grid.querying.sorting.currentSorting?.order;
-        if (col.id === this.column.id && order) {
-            col.setOptions({ sorting: { order } });
+        const sortings = col.viewport.grid.querying.sorting.currentSortings || [];
+        const sortingIndex = sortings.findIndex((sorting) => sorting.columnId === col.id);
+        if (sortingIndex !== -1 && sortings[sortingIndex].order) {
+            const sorting = sortings[sortingIndex];
+            const sortingOptions = {
+                order: sorting.order
+            };
+            if (sortings.length > 1) {
+                sortingOptions.priority = sortingIndex + 1;
+            }
+            col.setOptions({ sorting: sortingOptions });
+            if (sortings.length < 2) {
+                delete col.options.sorting?.priority;
+            }
         }
         else {
             delete col.options.sorting?.order;
+            delete col.options.sorting?.priority;
             if (col.options.sorting &&
                 Object.keys(col.options.sorting).length < 1) {
                 delete col.options.sorting;
             }
         }
     }
+    /**
+     * Returns sorting order sequence for this column.
+     */
+    getOrderSequence() {
+        return this.column.options.sorting?.orderSequence || [
+            'asc',
+            'desc',
+            null
+        ];
+    }
+    /**
+     * Normalizes arbitrary sorting values to valid order states.
+     *
+     * @param order
+     * Value to normalize.
+     */
+    normalizeOrder(order) {
+        return order === 'asc' || order === 'desc' ?
+            order :
+            null;
+    }
     /**
      * Set sorting order for the column. It will modify the presentation data
      * and rerender the rows.
@@ -127,8 +205,11 @@ class ColumnSorting {
      * @param order
      * The order of sorting. It can be `'asc'`, `'desc'` or `null` if the
      * sorting should be disabled.
+     *
+     * @param additive
+     * Whether to add this sort to existing sorts or replace them.
      */
-    async setOrder(order) {
+    async setOrder(order, additive = false) {
         const viewport = this.column.viewport;
         // Do not call sorting when cell is currently edited and validated.
         if (viewport.validator?.errorCell) {
@@ -143,11 +224,40 @@ class ColumnSorting {
                 order
             });
         });
-        sortingController.setSorting(order, this.column.id);
+        if (additive) {
+            const baseSortings = (sortingController.currentSortings ||
+                (sortingController.currentSorting?.columnId &&
+                    sortingController.currentSorting.order ?
+                    [sortingController.currentSorting] :
+                    [])).filter((sorting) => !!(sorting.columnId && sorting.order));
+            const sortings = baseSortings.slice();
+            const index = sortings.findIndex((sorting) => sorting.columnId === this.column.id);
+            if (!order) {
+                if (index !== -1) {
+                    sortings.splice(index, 1);
+                }
+            }
+            else {
+                const sorting = {
+                    columnId: this.column.id,
+                    order
+                };
+                if (index !== -1) {
+                    sortings[index] = sorting;
+                }
+                else {
+                    sortings.push(sorting);
+                }
+            }
+            sortingController.setSorting(sortings);
+        }
+        else {
+            sortingController.setSorting(order, this.column.id);
+        }
         await viewport.updateRows();
         for (const col of viewport.columns) {
             this.updateColumnOptions(col);
-            col.sorting?.addHeaderElementAttributes();
+            col.sorting?.refreshHeaderAttributes();
         }
         a11y?.userSortedColumn(order);
         [this.column, viewport.grid].forEach((source) => {

package/es-modules/Grid/Core/Table/Actions/ColumnsResizer.js

@@ -2,11 +2,11 @@
  *
  *  Grid Columns Resizer 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,9 +16,8 @@
 'use strict';
 import GridUtils from '../../GridUtils.js';
 import Globals from '../../Globals.js';
-import Utils from '../../../../Core/Utilities.js';
+import { fireEvent } from '../../../../Shared/Utilities.js';
 const { makeHTMLElement } = GridUtils;
-const { fireEvent } = Utils;
 /* *
  *
  *  Class
@@ -58,7 +57,6 @@ class ColumnsResizer {
             const vp = this.viewport;
             vp.columnResizing.resize(this, diff);
             vp.reflow();
-            vp.rowsVirtualizer.adjustRowHeights();
             fireEvent(this.draggedColumn, 'afterResize', {
                 target: this.draggedColumn,
                 originalEvent: e

package/es-modules/Grid/Core/Table/Actions/RowsVirtualizer.d.ts

@@ -7,7 +7,7 @@ declare class RowsVirtualizer {
     /**
      * The default height of a row.
      */
-    readonly defaultRowHeight: number;
+    defaultRowHeight: number;
     /**
      * The index of the first visible row.
      */
@@ -35,6 +35,57 @@ declare class RowsVirtualizer {
      * Rendering row settings.
      */
     rowSettings?: RowsSettings;
+    /**
+     * Cached max element height in CSS pixels.
+     */
+    private static maxElementHeight?;
+    /**
+     * The maximum height of a HTML element in most browsers.
+     * Firefox has a lower limit than other browsers.
+     */
+    private static getMaxElementHeight;
+    /**
+     * The maximum height of the scrollable element in CSS pixels.
+     */
+    private maxElementHeight;
+    /**
+     * The total height of the grid, used when the Grid height
+     * exceeds the max element height.
+     */
+    private totalGridHeight;
+    /**
+     * The overflow height of the grid, used when the Grid height
+     * exceeds the max element height.
+     */
+    private gridHeightOverflow;
+    /**
+     * The scroll offset in pixels used to adjust the row positions when
+     * the Grid height exceeds the max element height.
+     */
+    private scrollOffset;
+    /**
+     * Reuse pool for rows that are currently out of viewport.
+     */
+    private readonly rowPool;
+    /**
+     * Maximum number of rows to keep in the reuse pool.
+     */
+    private static readonly MAX_POOL_SIZE;
+    /**
+     * Flag indicating if a scroll update is queued for the next animation
+     * frame.
+     */
+    private scrollQueued;
+    /**
+     * Flag indicating if rows are currently being rendered to prevent
+     * concurrent render operations.
+     */
+    private isRendering;
+    /**
+     * Pending row cursor to render after current render completes.
+     * Used to ensure the final scroll position is rendered.
+     */
+    private pendingRowCursor;
     /**
      * Constructs an instance of the rows virtualizer.
      *
@@ -45,17 +96,26 @@ declare class RowsVirtualizer {
     /**
      * Renders the rows in the viewport for the first time.
      */
-    initialRender(): void;
+    initialRender(): Promise<void>;
     /**
      * Renders the rows in the viewport. It is called when the rows need to be
      * re-rendered, e.g., after a sort or filter operation.
      */
-    rerender(): void;
+    rerender(): Promise<void>;
+    /**
+     * Refreshes the rendered rows without a full teardown.
+     * It updates the row range and reuses existing rows when possible.
+     */
+    refreshRows(): Promise<void>;
     /**
      * Method called on the viewport scroll event, only when the virtualization
      * is enabled.
      */
     scroll(): void;
+    /**
+     * Applies the scroll logic for virtualized rows.
+     */
+    private applyScroll;
     /**
      * Adjusts the visible row heights from the bottom of the viewport.
      */
@@ -78,10 +138,41 @@ declare class RowsVirtualizer {
      * Reflow the rendered rows content dimensions.
      */
     reflowRows(): void;
+    /**
+     * Gets a row from the pool or creates a new one for the given index.
+     *
+     * @param index
+     * The row index in the data table.
+     *
+     * @returns
+     * A TableRow instance ready for use.
+     */
+    private getOrCreateRow;
+    /**
+     * Adds a row to the reuse pool, or destroys it if the pool is full.
+     *
+     * @param row
+     * The row to pool.
+     */
+    private poolRow;
     /**
      * Returns the default height of a row. This method should be called only
      * once on initialization.
+     *
+     * @returns
+     * The default height of a row.
      */
     private getDefaultRowHeight;
+    /**
+     * Updates cached row count and derived grid height metrics used for
+     * overflow-aware scrolling.
+     */
+    private updateGridMetrics;
+    /**
+     * Updates row translate offsets based on scroll scaling. When the grid
+     * exceeds the max element height, it keeps the bottom rows aligned to the
+     * maximum scrollable height.
+     */
+    private adjustRowOffsets;
 }
 export default RowsVirtualizer;