@highcharts/grid-pro 2.2.0 → 2.3.0

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

@@ -0,0 +1,229 @@
+/* *
+ *
+ *  Grid Responsive composition
+ *
+ *  (c) 2020-2026 Highsoft AS
+ *
+ *  A commercial license may be required depending on use.
+ *  See www.highcharts.com/license
+ *
+ *
+ *  Authors:
+ *  - Dawid Dragula
+ *
+ * */
+'use strict';
+import Globals from '../../Core/Globals.js';
+import { addEvent, defined, diffObjects, merge, pushUnique } from '../../../Shared/Utilities.js';
+import { uniqueKey } from '../../../Core/Utilities.js';
+/* *
+ *
+ *  Composition
+ *
+ * */
+/**
+ * Extends the grid classes with responsive options.
+ *
+ * @param GridClass
+ * The class to extend.
+ *
+ */
+export function compose(GridClass) {
+    if (!pushUnique(Globals.composed, 'Responsive')) {
+        return;
+    }
+    addEvent(GridClass, 'beforeRenderViewport', initResizeObserver);
+    addEvent(GridClass, 'beforeDestroy', destroyResizeObserver);
+}
+/**
+ * Initializes the resize observer.
+ *
+ * @param this
+ * Reference to Grid.
+ */
+function initResizeObserver() {
+    destroyResizeObserver.call(this);
+    if (!this.container) {
+        return;
+    }
+    this.activeRules = new Set();
+    this.resizeObserver = new ResizeObserver((entries) => {
+        onResize.call(this, entries[0]);
+    });
+    this.resizeObserver.observe(this.container);
+}
+/**
+ * Destroys the resize observer.
+ *
+ * @param this
+ * Reference to Grid.
+ */
+function destroyResizeObserver() {
+    this.resizeObserver?.disconnect();
+    delete this.activeRules;
+}
+/**
+ * Checks if the responsive rule matches the current grid size.
+ *
+ * @param this
+ * Reference to Grid.
+ *
+ * @param rule
+ * The responsive rule to check.
+ *
+ * @param entry
+ * The resize observer entry.
+ */
+function matchResponsiveRule(rule, entry) {
+    const { maxWidth, maxHeight, minWidth, minHeight, callback } = rule.condition;
+    return ((!defined(callback) || callback?.call(this, this)) &&
+        (!defined(maxWidth) || entry.contentRect.width <= maxWidth) &&
+        (!defined(maxHeight) || entry.contentRect.height <= maxHeight) &&
+        (!defined(minWidth) || entry.contentRect.width >= minWidth) &&
+        (!defined(minHeight) || entry.contentRect.height >= minHeight));
+}
+/**
+ * Updates the grid based on the currently active responsive rules.
+ *
+ * @param this
+ * Reference to Grid.
+ *
+ * @param matchingRules
+ * Active responsive rules.
+ */
+function setResponsive(matchingRules) {
+    const ruleIds = matchingRules.map((rule) => rule._id);
+    const ruleIdsString = (ruleIds.toString() || void 0);
+    const currentRuleIds = this.currentResponsive?.ruleIds;
+    if (ruleIdsString === currentRuleIds) {
+        return;
+    }
+    if (this.currentResponsive) {
+        const undoOptions = this.currentResponsive.undoOptions;
+        this.currentResponsive = void 0;
+        this.updatingResponsive = true;
+        void this.update(undoOptions, true);
+        this.updatingResponsive = false;
+    }
+    if (ruleIdsString) {
+        const mergedOptions = merge(...matchingRules.map((rule) => rule.gridOptions));
+        const undoOptions = diffObjects(mergedOptions, this.options || {}, true);
+        const columnUndoOptions = getColumnUndoOptions.call(this, mergedOptions);
+        if (columnUndoOptions) {
+            undoOptions.columns = columnUndoOptions;
+        }
+        else {
+            syncColumnIds(undoOptions, mergedOptions);
+        }
+        this.currentResponsive = {
+            ruleIds: ruleIdsString,
+            mergedOptions,
+            undoOptions
+        };
+        if (!this.updatingResponsive) {
+            void this.update(mergedOptions, true);
+        }
+    }
+}
+/**
+ * Builds undo options for columns by matching them by id.
+ *
+ * @param this
+ * Reference to Grid.
+ *
+ * @param mergedOptions
+ * The merged responsive options used to apply updates.
+ */
+function getColumnUndoOptions(mergedOptions) {
+    const mergedColumns = mergedOptions.columns;
+    const currentColumns = this.options?.columns;
+    if (!mergedColumns || !currentColumns) {
+        return;
+    }
+    const result = [];
+    const columnMap = new Map();
+    for (let i = 0, iEnd = currentColumns.length; i < iEnd; ++i) {
+        const column = currentColumns[i];
+        if (typeof column.id === 'string') {
+            columnMap.set(column.id, column);
+        }
+    }
+    for (let i = 0, iEnd = mergedColumns.length; i < iEnd; ++i) {
+        const mergedColumn = mergedColumns[i];
+        const columnId = (typeof mergedColumn?.id === 'string') ?
+            mergedColumn.id :
+            void 0;
+        if (!mergedColumn || !columnId) {
+            continue;
+        }
+        const currentColumn = columnMap.get(columnId);
+        if (!currentColumn) {
+            continue;
+        }
+        const columnUndo = diffObjects(mergedColumn, currentColumn, true);
+        if (Object.keys(columnUndo).length > 0) {
+            columnUndo.id = columnId;
+            result.push(columnUndo);
+        }
+    }
+    if (result.length) {
+        return result;
+    }
+}
+/**
+ * Ensures column options keep their ids when undoing responsive updates.
+ *
+ * @param undoOptions
+ * The undo options to be updated.
+ *
+ * @param mergedOptions
+ * The merged responsive options used to apply updates.
+ */
+function syncColumnIds(undoOptions, mergedOptions) {
+    const mergedColumns = mergedOptions.columns;
+    const undoColumns = undoOptions.columns;
+    if (!mergedColumns || !undoColumns) {
+        return;
+    }
+    for (let i = 0, iEnd = Math.min(mergedColumns.length, undoColumns.length); i < iEnd; ++i) {
+        const mergedColumn = mergedColumns[i];
+        const undoColumn = undoColumns[i];
+        if (mergedColumn && undoColumn && !('id' in undoColumn)) {
+            undoColumn.id = mergedColumn.id;
+        }
+    }
+}
+/**
+ * Handles the resize event.
+ *
+ * @param this
+ * Reference to Grid.
+ *
+ * @param entry
+ * The resize observer entry.
+ */
+function onResize(entry) {
+    if (!this.activeRules) {
+        return;
+    }
+    const rules = this.options?.responsive?.rules || [];
+    const matchingRules = [];
+    for (const rule of rules) {
+        if (typeof rule._id === 'undefined') {
+            rule._id = uniqueKey();
+        }
+        if (matchResponsiveRule.call(this, rule, entry)) {
+            matchingRules.push(rule);
+        }
+    }
+    this.activeRules = new Set(matchingRules);
+    setResponsive.call(this, matchingRules);
+}
+/* *
+ *
+ *  Default Export
+ *
+ * */
+export default {
+    compose
+};

package/es-modules/Grid/Core/Responsive/ResponsiveOptions.d.ts

@@ -0,0 +1,58 @@
+import type { DeepPartial } from '../../../Shared/Types';
+import type { Options } from '../Options';
+import type Grid from '../Grid';
+/**
+ * Options for the responsive behavior of the grid.
+ */
+export interface ResponsiveOptions {
+    /**
+     * A set of rules for responsive settings. The rules are executed from
+     * the top down.
+     */
+    rules?: Array<RuleOptions>;
+}
+/**
+ * A rule for the responsive behavior of the grid.
+ */
+export interface RuleOptions {
+    /**
+     * A full set of grid options to apply as overrides to the general grid
+     * options. The grid options are applied when the given rule is active.
+     */
+    gridOptions: DeepPartial<Exclude<Options, 'responsive' | 'id'>>;
+    /**
+     * Under which conditions the rule applies.
+     */
+    condition: RuleConditionOptions;
+}
+/**
+ * Conditions for the responsive rule.
+ */
+export interface RuleConditionOptions {
+    /**
+     * A callback function to gain complete control on when the responsive
+     * rule applies. Return `true` if it applies. This opens for checking
+     * against other metrics than the grid size, for example the document
+     * size or other elements.
+     */
+    callback?: (this: Grid, grid: Grid) => boolean;
+    /**
+     * The responsive rule applies if the grid width is less or equal to this.
+     */
+    maxWidth?: number;
+    /**
+     * The responsive rule applies if the grid height is less or equal to this.
+     */
+    maxHeight?: number;
+    /**
+     * The responsive rule applies if the grid width is greater or equal to
+     * this.
+     */
+    minWidth?: number;
+    /**
+     * The responsive rule applies if the grid height is greater or equal to
+     * this.
+     */
+    minHeight?: number;
+}
+export default ResponsiveOptions;

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

@@ -0,0 +1,15 @@
+/* *
+ *
+ *  Grid responsive options
+ *
+ *  (c) 2020-2026 Highsoft AS
+ *
+ *  A commercial license may be required depending on use.
+ *  See www.highcharts.com/license
+ *
+ *
+ *  Authors:
+ *  - Dawid Dragula
+ *
+ * */
+export {};

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

@@ -15,11 +15,10 @@
  *
  * */
 'use strict';
-import U from '../../../../../Core/Utilities.js';
 import GU from '../../../GridUtils.js';
 import Globals from '../../../Globals.js';
 import { conditionsMap } from './FilteringTypes.js';
-const { defined, fireEvent } = U;
+import { defined, fireEvent } from '../../../../../Shared/Utilities.js';
 const { makeHTMLElement } = GU;
 /* *
  *
@@ -328,7 +327,7 @@ class ColumnFiltering {
     renderClearButton(inputWrapper) {
         this.clearButton = makeHTMLElement('button', {
             className: Globals.getClassName('clearFilterButton'),
-            innerText: 'Clear filter' // TODO: Lang
+            innerText: 'Clear filter' // TODO(lang): Lang
         }, inputWrapper);
         this.clearButton.setAttribute('tabindex', '-1');
         this.clearButton.disabled = !this.isFilteringApplied();

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

@@ -7,7 +7,7 @@ import HeaderCell from '../../Header/HeaderCell.js';
 declare class FilterCell extends HeaderCell {
     column: Column;
     constructor(row: Row, column: Column);
-    render(): void;
+    render(): Promise<void>;
     onKeyDown(e: KeyboardEvent): void;
     onClick(e: MouseEvent): void;
 }

package/es-modules/Grid/Core/Table/Actions/ColumnFiltering/FilterCell.js

@@ -14,8 +14,7 @@
  * */
 'use strict';
 import HeaderCell from '../../Header/HeaderCell.js';
-import U from '../../../../../Core/Utilities.js';
-const { fireEvent } = U;
+import { fireEvent } from '../../../../../Shared/Utilities.js';
 /* *
  *
  *  Class
@@ -40,10 +39,10 @@ class FilterCell extends HeaderCell {
      *  Methods
      *
      * */
-    render() {
+    async render() {
         const { column } = this;
         if (!column) {
-            return;
+            return Promise.resolve();
         }
         // Render content of th element
         this.row.htmlElement.appendChild(this.htmlElement);

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

@@ -14,6 +14,6 @@ declare class FilterRow extends HeaderRow {
      */
     constructor(viewport: Table);
     createCell(column: Column): FilterCell;
-    renderContent(): void;
+    renderContent(): Promise<void>;
 }
 export default FilterRow;

package/es-modules/Grid/Core/Table/Actions/ColumnFiltering/FilterRow.js

@@ -48,7 +48,7 @@ class FilterRow extends HeaderRow {
     createCell(column) {
         return new FilterCell(this, column);
     }
-    renderContent() {
+    async renderContent() {
         const vp = this.viewport;
         const enabledColumns = vp.grid.enabledColumns || [];
         vp.theadElement?.appendChild(this.htmlElement);
@@ -59,7 +59,7 @@ class FilterRow extends HeaderRow {
                 continue;
             }
             const cell = this.createCell(column);
-            cell.render();
+            await cell.render();
             if (column.options.filtering?.inline) {
                 column.filtering?.renderFilteringContent(cell.htmlElement);
             }

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

@@ -12,6 +12,10 @@ declare class ColumnSorting {
      * The head element of the column.
      */
     headerCellElement: HTMLElement;
+    /**
+     * Last index used from the configured order sequence.
+     */
+    private lastOrderSequenceIndex?;
     /**
      * Constructs sorting for a dedicated column.
      *
@@ -37,6 +41,17 @@ declare class ColumnSorting {
      * The column to update.
      */
     private updateColumnOptions;
+    /**
+     * Returns sorting order sequence for this column.
+     */
+    private getOrderSequence;
+    /**
+     * Normalizes arbitrary sorting values to valid order states.
+     *
+     * @param order
+     * Value to normalize.
+     */
+    private normalizeOrder;
     /**
      * Set sorting order for the column. It will modify the presentation data
      * and rerender the rows.
@@ -50,7 +65,8 @@ declare class ColumnSorting {
      */
     setOrder(order: ColumnSortingOrder, additive?: boolean): Promise<void>;
     /**
-     * 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.

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

@@ -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,7 +41,8 @@ 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.
@@ -52,18 +52,40 @@ class ColumnSorting {
             const querying = viewport.grid.querying;
             const sortingController = querying.sorting;
             const additive = !!e?.shiftKey;
-            const currentOrder = (additive ?
-                sortingController.currentSortings?.find((sorting) => sorting.columnId === this.column.id)?.order :
-                (sortingController.currentSorting?.columnId ===
-                    this.column.id ?
-                    sortingController.currentSorting.order :
-                    null)) || 'none';
-            const consequents = {
-                none: 'asc',
-                asc: 'desc',
-                desc: null
-            };
-            void this.setOrder(consequents[currentOrder], additive);
+            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;
@@ -155,6 +177,27 @@ class ColumnSorting {
             }
         }
     }
+    /**
+     * 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.

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

@@ -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,34 @@ 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.
      */
@@ -48,6 +76,16 @@ declare class RowsVirtualizer {
      * 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.
      *
@@ -58,12 +96,17 @@ 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.
@@ -120,5 +163,16 @@ declare class RowsVirtualizer {
      * 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;