@opencorestack/opengridx 2.1.0 → 3.0.1

package/lib/utils/pivot/index.ts

@@ -0,0 +1,368 @@
+import type {
+    GridColDef,
+    GridFilterGroup,
+    GridFilterItem,
+    GridFilterModel,
+    GridPivotAggFn,
+    GridPivotModel,
+    GridPivotValueField,
+    GridRenderCellParams,
+    GridRowId,
+    GridRowModel,
+    GridSortItem,
+} from '../../types';
+import {
+    AGGREGATION_FUNCTIONS,
+    formatAggregateForColumn,
+    isAggregationAllowed,
+    isEmptyAggregateValue,
+} from '../aggregation';
+import { createRowFilter } from '../filtering';
+import { compareValues } from '../sorting';
+import { buildColumnLookup } from '../columnLookup';
+import { getCellValue, getFormattedValue } from '../values';
+
+/** Row id of the Grand Total row that closes every pivot. */
+export const PIVOT_GRAND_TOTAL_ID = '__pivot_grand_total__';
+/**
+ * Prefix of every pivot data row id. Pivot rows are keyed by their row-field values
+ * (`__pivot_row__:["North","Q1"]`), so their ids never collide with source row ids (a selection
+ * made on the source rows never marks an unrelated pivot row) and stay the same for the same
+ * group when the source data changes.
+ */
+export const PIVOT_ROW_ID_PREFIX = '__pivot_row__:';
+const pivotRowId = (groupKey: string): string => `${PIVOT_ROW_ID_PREFIX}${JSON.stringify(groupKey.split(SEP_COL))}`;
+const GRAND_TOTAL_LABEL = 'Grand Total';
+
+// Joins the values of several column fields into one column key.
+const SEP_COL = '\u0000';
+// Separates the parts of a generated value-column field: `[colKey␟]field␟aggFn`.
+export const PIVOT_FIELD_SEPARATOR = '\u001f';
+// A row field named `id` cannot keep its label under `id`, which must stay the unique pivot row id.
+const ID_LABEL_KEY = `${PIVOT_FIELD_SEPARATOR}id`;
+const labelKey = (field: string) => (field === 'id' ? ID_LABEL_KEY : field);
+
+export interface PivotResult {
+    /** Pivot data rows followed by the Grand Total row (omitted when there are no data rows). */
+    pivotRows: GridRowModel[];
+    /** Row-label columns (one per row field) followed by one value column per column key and value field. */
+    pivotColumns: GridColDef[];
+    /** The distinct column-field value combinations, in display order. */
+    colKeys: string[];
+    /** `false` when the model has no usable row field or value field. */
+    isValid: boolean;
+}
+
+export interface PivotOptions {
+    /**
+     * Filter applied to the generated pivot rows (conditions on generated value columns). Rows it
+     * removes are also left out of the Grand Total, so the total always matches the rows shown.
+     */
+    outputFilterModel?: GridFilterModel;
+    /** Sort applied to the pivot data rows. The Grand Total row always stays last. */
+    sortModel?: GridSortItem[];
+}
+
+export const EMPTY_PIVOT_RESULT: PivotResult = { pivotRows: [], pivotColumns: [], colKeys: [], isValid: false };
+
+// Groups are keyed by each value's display string, as row grouping does, so 1 and '1' share a group;
+// null, undefined and '' all key to '' and form one blank group.
+const keyOf = (values: unknown[]): string => values.map((v) => String(v ?? '')).join(SEP_COL);
+
+// The blank group is labelled null whichever blank value was seen first.
+const normalizeLabel = (v: unknown): unknown => (v === undefined || v === '' ? null : v);
+
+// Column-field values are ordered by their raw value: numbers and dates numerically, strings
+// naturally ('9' before '10'), blanks last.
+function compareDimension(a: unknown, b: unknown): number {
+    const aBlank = a == null;
+    const bBlank = b == null;
+    if (aBlank || bBlank) return aBlank === bBlank ? 0 : aBlank ? 1 : -1;
+    if (typeof a === 'number' && typeof b === 'number') return a - b;
+    if (a instanceof Date && b instanceof Date) return a.getTime() - b.getTime();
+    if (typeof a === 'boolean' && typeof b === 'boolean') return Number(a) - Number(b);
+    return String(a).localeCompare(String(b), undefined, { numeric: true });
+}
+
+function compareTuples(a: unknown[], b: unknown[]): number {
+    for (let i = 0; i < a.length; i++) {
+        const c = compareDimension(a[i], b[i]);
+        if (c !== 0) return c;
+    }
+    return 0;
+}
+
+// A number, or a Date for min / max of dates.
+function aggregate(values: unknown[] | undefined, fn: GridPivotAggFn): number | Date | null {
+    if (!values || values.length === 0) return null;
+    const result = AGGREGATION_FUNCTIONS[fn](values);
+    return typeof result === 'number' || result instanceof Date ? result : null;
+}
+
+const isFilterGroup = (item: GridFilterItem | GridFilterGroup): item is GridFilterGroup =>
+    'logicOperator' in item && 'items' in item;
+
+const hasFilterItems = (model?: GridFilterModel): model is GridFilterModel =>
+    Boolean(model && model.items && model.items.length > 0);
+
+/**
+ * Splits a filter model for pivot mode. Conditions on generated value columns (fields the source
+ * columns do not have) can only be evaluated on pivot rows; everything else, including the quick
+ * filter and conditions on row-field columns, is applied to the source rows before pivoting.
+ */
+export function splitPivotFilterModel(
+    filterModel: GridFilterModel,
+    sourceFields: ReadonlySet<string>,
+): { source: GridFilterModel; output: GridFilterModel } {
+    const isGenerated = (field: string) => !sourceFields.has(field) && field.includes(PIVOT_FIELD_SEPARATOR);
+    const targetsPivotRows = (item: GridFilterItem | GridFilterGroup): boolean =>
+        isFilterGroup(item)
+            ? item.items.length > 0 && item.items.every(targetsPivotRows)
+            : isGenerated(item.field);
+
+    const sourceItems: (GridFilterItem | GridFilterGroup)[] = [];
+    const outputItems: (GridFilterItem | GridFilterGroup)[] = [];
+    for (const item of filterModel.items ?? []) {
+        (targetsPivotRows(item) ? outputItems : sourceItems).push(item);
+    }
+    return {
+        source: { ...filterModel, items: sourceItems },
+        output: { items: outputItems, logicOperator: filterModel.logicOperator },
+    };
+}
+
+interface GroupEntry {
+    labels: unknown[];
+    /** First source row of the group: the `row` given to the row-field column's formatter and renderer. */
+    sample: GridRowModel;
+    /** Column key → value field → raw values. */
+    cells: Map<string, Map<string, unknown[]>>;
+}
+
+interface ColumnKeyInfo {
+    values: unknown[];
+    /** First source row with this column key: the `row` given to the header label's formatter. */
+    sample?: GridRowModel;
+}
+
+/**
+ * Builds pivot rows and columns from source rows. Values are read through each column's
+ * `valueGetter`, aggregated with the shared `lib/utils/aggregation` functions, and formatted with
+ * `formatAggregateForColumn` (the source column's `valueFormatter` for sum / avg / min / max, with the
+ * pivot row as its `row`, as for group rows and exports). Row and column fields on a
+ * `groupable: false` column, and value fields on an `aggregable: false` column or whose function
+ * the column's `availableAggregationFunctions` does not allow, are skipped.
+ */
+export function computePivot(
+    rows: GridRowModel[],
+    columns: GridColDef[],
+    model: GridPivotModel,
+    options: PivotOptions = {},
+): PivotResult {
+    const colDefMap = new Map(columns.map((c) => [c.field, c]));
+    const isGroupable = (f: string) => colDefMap.get(f)?.groupable !== false;
+    const rowFields = model.rowFields.filter(isGroupable);
+    const columnFields = model.columnFields.filter(isGroupable);
+
+    const seenValueFields = new Set<string>();
+    const valueFields: GridPivotValueField[] = model.valueFields.filter((vf) => {
+        if (!isAggregationAllowed(colDefMap.get(vf.field), vf.aggFn)) return false;
+        const id = `${vf.field}${PIVOT_FIELD_SEPARATOR}${vf.aggFn}`;
+        if (seenValueFields.has(id)) return false;
+        seenValueFields.add(id);
+        return true;
+    });
+
+    if (rowFields.length === 0 || valueFields.length === 0) return EMPTY_PIVOT_RESULT;
+
+    const hasColFields = columnFields.length > 0;
+    // Raw values are collected once per distinct field, however many functions use it.
+    const valueSourceFields = Array.from(new Set(valueFields.map((vf) => vf.field)));
+    const get = (row: GridRowModel, field: string) => getCellValue(row, field, colDefMap.get(field));
+
+    const groups = new Map<string, GroupEntry>();
+    // Without column fields there is exactly one column key, present even when there is no data.
+    const colKeyInfo = new Map<string, ColumnKeyInfo>(hasColFields ? [] : [['', { values: [] }]]);
+
+    for (const row of rows) {
+        const labelValues = rowFields.map((f) => get(row, f));
+        const rk = keyOf(labelValues);
+        let entry = groups.get(rk);
+        if (!entry) {
+            entry = { labels: labelValues.map(normalizeLabel), sample: row, cells: new Map() };
+            groups.set(rk, entry);
+        }
+
+        const colValues = columnFields.map((f) => get(row, f));
+        const ck = hasColFields ? keyOf(colValues) : '';
+        const info = colKeyInfo.get(ck);
+        if (!info) colKeyInfo.set(ck, { values: colValues.map(normalizeLabel), sample: row });
+        else if (!info.sample) info.sample = row;
+
+        let cell = entry.cells.get(ck);
+        if (!cell) {
+            cell = new Map();
+            entry.cells.set(ck, cell);
+        }
+        for (const f of valueSourceFields) {
+            const v = get(row, f);
+            if (isEmptyAggregateValue(v)) continue;
+            let bucket = cell.get(f);
+            if (!bucket) {
+                bucket = [];
+                cell.set(f, bucket);
+            }
+            bucket.push(v);
+        }
+    }
+
+    const colKeys = Array.from(colKeyInfo.keys()).sort((a, b) =>
+        compareTuples(colKeyInfo.get(a)!.values, colKeyInfo.get(b)!.values));
+
+    const cellField = (ck: string, vf: GridPivotValueField) => hasColFields
+        ? `${ck}${PIVOT_FIELD_SEPARATOR}${vf.field}${PIVOT_FIELD_SEPARATOR}${vf.aggFn}`
+        : `${vf.field}${PIVOT_FIELD_SEPARATOR}${vf.aggFn}`;
+
+    // ── Data rows ────────────────────────────────────────────────────────────
+    const entryByRowId = new Map<GridRowId, GroupEntry>();
+    let kept: { row: GridRowModel; entry: GroupEntry }[] = [];
+    for (const [groupKey, entry] of groups) {
+        const row: GridRowModel = { id: pivotRowId(groupKey) };
+        rowFields.forEach((f, i) => { row[labelKey(f)] = entry.labels[i]; });
+        row.id = pivotRowId(groupKey);
+        for (const ck of colKeys) {
+            const cell = entry.cells.get(ck);
+            for (const vf of valueFields) row[cellField(ck, vf)] = aggregate(cell?.get(vf.field), vf.aggFn);
+        }
+        entryByRowId.set(row.id, entry);
+        kept.push({ row, entry });
+    }
+
+    // Generated value columns are numeric (or dates for min / max of dates); row-label columns keep
+    // their source column's type, so filtering and sorting compare them the way the grid does.
+    const isRowField = (field: string) => rowFields.includes(field);
+    const typeOf = (field: string): GridColDef['type'] => (isRowField(field) ? colDefMap.get(field)?.type : 'number');
+
+    const { outputFilterModel, sortModel } = options;
+    if (hasFilterItems(outputFilterModel)) {
+        const generatedColumns: GridColDef[] = [];
+        for (const ck of colKeys) for (const vf of valueFields) generatedColumns.push({ field: cellField(ck, vf), type: 'number' });
+        const predicate = createRowFilter(outputFilterModel, buildColumnLookup(generatedColumns));
+        if (predicate) kept = kept.filter(({ row }) => predicate(row));
+    }
+
+    const sortValue = (row: GridRowModel, field: string) =>
+        field === 'id' && isRowField('id') ? row[ID_LABEL_KEY] : row[field];
+    if (sortModel && sortModel.length > 0) {
+        kept = [...kept].sort((a, b) => {
+            for (const item of sortModel) {
+                const c = compareValues(sortValue(a.row, item.field), sortValue(b.row, item.field), item.sort, typeOf(item.field));
+                if (c !== 0) return c;
+            }
+            return 0;
+        });
+    }
+
+    // ── Grand Total: aggregated from the raw values of the rows shown ────────
+    const pivotRows = kept.map((k) => k.row);
+    if (kept.length > 0) {
+        const total: GridRowModel = { id: PIVOT_GRAND_TOTAL_ID };
+        rowFields.forEach((f, i) => { total[labelKey(f)] = i === 0 ? GRAND_TOTAL_LABEL : ''; });
+        total.id = PIVOT_GRAND_TOTAL_ID;
+        for (const ck of colKeys) {
+            for (const f of valueSourceFields) {
+                const values: unknown[] = [];
+                for (const { entry } of kept) {
+                    const bucket = entry.cells.get(ck)?.get(f);
+                    if (bucket) for (const v of bucket) values.push(v);
+                }
+                for (const vf of valueFields) {
+                    if (vf.field === f) total[cellField(ck, vf)] = aggregate(values, vf.aggFn);
+                }
+            }
+        }
+        pivotRows.push(total);
+    }
+
+    // ── Columns ──────────────────────────────────────────────────────────────
+    const firstSample = kept[0]?.entry.sample;
+    const groupSample = (id: GridRowId | undefined): GridRowModel | undefined =>
+        id === PIVOT_GRAND_TOTAL_ID ? firstSample : id === undefined ? undefined : entryByRowId.get(id)?.sample;
+
+    const pivotColumns: GridColDef[] = rowFields.map((f) => buildRowFieldColumn(f, colDefMap.get(f), groupSample));
+
+    for (const ck of colKeys) {
+        const info = colKeyInfo.get(ck)!;
+        const colLabel = hasColFields
+            ? columnFields.map((f, i) => {
+                const def = colDefMap.get(f);
+                const shown = formatDimension(def, f, info.values[i], info.sample);
+                return def?.headerName ? `${def.headerName}: ${shown}` : shown;
+            }).join(' / ')
+            : '';
+
+        for (const vf of valueFields) {
+            const orig = colDefMap.get(vf.field);
+            const labelBase = vf.headerName ?? orig?.headerName ?? vf.field;
+            pivotColumns.push({
+                field: cellField(ck, vf),
+                headerName: colLabel ? `${colLabel} — ${labelBase} (${vf.aggFn})` : `${labelBase} (${vf.aggFn})`,
+                width: 140,
+                type: 'number',
+                align: 'right',
+                headerAlign: 'right',
+                sortable: true,
+                valueFormatter: ({ value, row }) => formatAggregateForColumn(value, vf.aggFn, orig, row),
+            });
+        }
+    }
+
+    return { pivotRows, pivotColumns, colKeys, isValid: true };
+}
+
+function formatDimension(def: GridColDef | undefined, field: string, value: unknown, sample?: GridRowModel): string {
+    const formatted = sample ? getFormattedValue(sample, field, value, def) : undefined;
+    if (formatted !== undefined) return formatted;
+    return value == null ? '' : String(value);
+}
+
+// A row-label column keeps how the source column displays its values (formatter, renderer, type,
+// alignment) and is always shown: the row fields are what the pivot rows are labelled by.
+function buildRowFieldColumn(
+    field: string,
+    orig: GridColDef | undefined,
+    groupSample: (id: GridRowId | undefined) => GridRowModel | undefined,
+): GridColDef {
+    const col: GridColDef = {
+        field,
+        headerName: orig?.headerName ?? field,
+        width: orig?.width ?? 140,
+        sortable: true,
+        hideable: false,
+    };
+    if (orig) {
+        if (orig.type !== undefined) col.type = orig.type;
+        if (orig.align !== undefined) col.align = orig.align;
+        if (orig.headerAlign !== undefined) col.headerAlign = orig.headerAlign;
+        if (orig.description !== undefined) col.description = orig.description;
+        if (orig.minWidth !== undefined) col.minWidth = orig.minWidth;
+        if (orig.maxWidth !== undefined) col.maxWidth = orig.maxWidth;
+        if (orig.valueOptions !== undefined) col.valueOptions = orig.valueOptions;
+    }
+    if (field === 'id') col.valueGetter = ({ row }) => row[ID_LABEL_KEY];
+
+    const isTotal = (row: GridRowModel | undefined) => row?.id === PIVOT_GRAND_TOTAL_ID;
+    const sourceFormatter = orig?.valueFormatter;
+    if (sourceFormatter) {
+        col.valueFormatter = ({ value, row }) => isTotal(row)
+            ? String(value ?? '')
+            : sourceFormatter({ value, row: groupSample(row?.id) ?? row, field });
+    }
+    const sourceRenderer = orig?.renderCell;
+    if (sourceRenderer) {
+        col.renderCell = (params: GridRenderCellParams) => isTotal(params.row)
+            ? (params.formattedValue ?? String(params.value ?? ''))
+            : sourceRenderer({ ...params, row: groupSample(params.row.id) ?? params.row });
+    }
+    return col;
+}

package/lib/utils/scroll/index.ts

@@ -1,13 +1,28 @@
+/**
+ * Height of the sticky block at the bottom of the viewport (bottom-pinned rows, their expanded
+ * detail panels and the aggregation footer), measured from the DOM.
+ */
+function stickyBottomHeight(viewport: HTMLElement): number {
+    const block = viewport.querySelector<HTMLElement>('.ogx__sticky-bottom');
+    return block ? block.getBoundingClientRect().height : 0;
+}
+
 /**
  * Vertically scrolls the grid viewport so the center (unpinned) row at `centerIndex`
- * is fully visible below the sticky header / top-pinned rows and above the
- * bottom-pinned rows. `cumulativeHeights` is the unpinned-row layout.
+ * is fully visible below the sticky header / top-pinned rows and above the sticky
+ * bottom block (bottom-pinned rows and aggregation footer). `cumulativeHeights` is the
+ * unpinned-row layout; `pinnedBottomHeight` is a lower bound for the bottom block.
+ *
+ * `cumulativeHeights` includes each row's expanded detail panel. Pass `rowHeight` to bring
+ * only the row itself into view: otherwise a panel taller than the viewport pushes its own
+ * row out of view above the header.
  */
 export function scrollRowIntoView(
     viewport: HTMLElement,
     centerIndex: number,
     cumulativeHeights: number[],
     pinnedBottomHeight: number,
+    rowHeight?: number,
 ): void {
     if (centerIndex < 0 || centerIndex >= cumulativeHeights.length) return;
     const virtualContainer = viewport.querySelector<HTMLElement>('.ogx__virtual-container');
@@ -17,12 +32,47 @@ export function scrollRowIntoView(
     // Everything above the center rows is sticky, so it covers exactly this many
     // pixels at the top of the viewport at any scroll position.
     const stickyTop = virtualContainer.getBoundingClientRect().top - viewport.getBoundingClientRect().top + scrollTop;
+    const bottomCover = Math.max(pinnedBottomHeight, stickyBottomHeight(viewport));
     const rowTop = stickyTop + (centerIndex === 0 ? 0 : cumulativeHeights[centerIndex - 1]);
-    const rowBottom = stickyTop + cumulativeHeights[centerIndex];
+    const rowBottom = rowHeight !== undefined
+        ? Math.min(rowTop + rowHeight, stickyTop + cumulativeHeights[centerIndex])
+        : stickyTop + cumulativeHeights[centerIndex];
 
     if (rowTop < scrollTop + stickyTop) {
         viewport.scrollTop = Math.max(0, rowTop - stickyTop);
-    } else if (rowBottom > scrollTop + clientHeight - pinnedBottomHeight) {
-        viewport.scrollTop = rowBottom - clientHeight + pinnedBottomHeight;
+    } else if (rowBottom > scrollTop + clientHeight - bottomCover) {
+        viewport.scrollTop = rowBottom - clientHeight + bottomCover;
+    }
+}
+
+export interface GridColumnScrollMetrics {
+    /** Cumulative widths of the unpinned columns (layout). */
+    unpinnedAccWidths: number[];
+    leftWidth: number;
+    rightWidth: number;
+    /** Width of all system columns (they precede the data columns). */
+    systemColumnsWidth: number;
+    /** Width of the system columns that are sticky. */
+    pinnedSystemColumnsWidth: number;
+}
+
+/**
+ * Horizontally scrolls the viewport so the unpinned column at `unpinnedIndex` is fully visible
+ * between the sticky left block (pinned system columns + left-pinned columns) and the
+ * right-pinned columns.
+ */
+export function scrollColumnIntoView(viewport: HTMLElement, unpinnedIndex: number, metrics: GridColumnScrollMetrics): void {
+    const { unpinnedAccWidths, leftWidth, rightWidth, systemColumnsWidth, pinnedSystemColumnsWidth } = metrics;
+    if (unpinnedIndex < 0 || unpinnedIndex >= unpinnedAccWidths.length) return;
+    const contentStart = systemColumnsWidth + leftWidth;
+    const colLeft = contentStart + (unpinnedIndex > 0 ? unpinnedAccWidths[unpinnedIndex - 1] : 0);
+    const colRight = contentStart + unpinnedAccWidths[unpinnedIndex];
+    const stickyLeft = pinnedSystemColumnsWidth + leftWidth;
+    const { scrollLeft, clientWidth } = viewport;
+
+    if (colLeft < scrollLeft + stickyLeft) {
+        viewport.scrollLeft = Math.max(0, colLeft - stickyLeft);
+    } else if (colRight > scrollLeft + clientWidth - rightWidth) {
+        viewport.scrollLeft = colRight - clientWidth + rightWidth;
     }
 }

package/lib/utils/scroll/scrollEnd.ts

@@ -0,0 +1,18 @@
+import type { GridRowScrollEndParams } from '../../types';
+
+/** How close (px) to the bottom of a scroll container counts as the end for `onRowsScrollEnd`. */
+export const ROWS_SCROLL_END_THRESHOLD = 100;
+
+/**
+ * The `onRowsScrollEnd` params for a scrolled row container, or null while it is further than
+ * ROWS_SCROLL_END_THRESHOLD from the bottom. Shared by the grid viewport and the list view.
+ */
+export function getRowsScrollEndParams(el: HTMLElement): GridRowScrollEndParams | null {
+    const { scrollTop, scrollHeight, clientHeight } = el;
+    if (scrollHeight - scrollTop - clientHeight >= ROWS_SCROLL_END_THRESHOLD) return null;
+    return {
+        visibleTop: scrollTop,
+        visibleBottom: scrollTop + clientHeight,
+        viewportHeight: clientHeight,
+    };
+}

package/lib/utils/sorting/index.ts

@@ -1,55 +1,179 @@
 
-import type { GridRowModel, GridSortItem } from '../../types';
+import type { GridColDef, GridRowModel, GridSortDirection, GridSortItem } from '../../types';
+import type { GridColumnLookup } from '../columnLookup';
+import { getCellValue, toDate, toNumber } from '../values';
 
-export function compareValues(a: unknown, b: unknown, direction: 'asc' | 'desc'): number {
+/**
+ * Language-aware string order: accented letters sort next to their base letter instead of after
+ * 'z', case is ignored, and digit runs compare by value ('item9' before 'item10').
+ */
+const collator = new Intl.Collator(undefined, { numeric: true, sensitivity: 'accent' });
 
-  if (a == null && b == null) return 0;
-  if (a == null) return direction === 'asc' ? 1 : -1;
-  if (b == null) return direction === 'asc' ? -1 : 1;
+// Values of different kinds are ordered by kind first, so the comparator stays transitive when a
+// column mixes, say, numbers and strings.
+const RANK_NUMBER = 0;
+const RANK_DATE = 1;
+const RANK_BOOLEAN = 2;
+const RANK_STRING = 3;
+const RANK_OTHER = 4;
 
-  if (typeof a === 'number' && typeof b === 'number') {
-    return direction === 'asc' ? a - b : b - a;
-  }
+/** A normalized sort value. null is the empty bucket (null, undefined, NaN, Invalid Date, unparsable). */
+type SortKey = { rank: number; num: number; str: string } | null;
+
+function numberKey(rank: number, num: number): SortKey {
+  return { rank, num, str: '' };
+}
 
-  if (a instanceof Date && b instanceof Date) {
-    return direction === 'asc' 
-      ? a.getTime() - b.getTime() 
-      : b.getTime() - a.getTime();
+/**
+ * Normalize a cell value for sorting. `type: 'number'` columns coerce numeric strings ('10' sorts
+ * after '9'), `type: 'date'` columns parse date strings; values that cannot be read go to the empty
+ * bucket together with null.
+ */
+function toSortKey(value: unknown, type?: GridColDef['type']): SortKey {
+  if (value == null) return null;
+  if (type === 'number') {
+    const n = toNumber(value);
+    return n === null ? null : numberKey(RANK_NUMBER, n);
+  }
+  if (type === 'date') {
+    const date = toDate(value);
+    return date ? numberKey(RANK_DATE, date.getTime()) : null;
+  }
+  switch (typeof value) {
+    case 'number':
+      return Number.isNaN(value) ? null : numberKey(RANK_NUMBER, value);
+    case 'bigint':
+      return numberKey(RANK_NUMBER, Number(value));
+    case 'boolean':
+      return numberKey(RANK_BOOLEAN, value ? 1 : 0);
+    case 'string':
+      return { rank: RANK_STRING, num: 0, str: value };
+    default:
+      break;
   }
+  if (value instanceof Date) {
+    const t = value.getTime();
+    return Number.isNaN(t) ? null : numberKey(RANK_DATE, t);
+  }
+  return { rank: RANK_OTHER, num: 0, str: String(value) };
+}
+
+/** Ascending comparison of two keys. The empty bucket sorts after every value. Never returns NaN. */
+function compareSortKeys(a: SortKey, b: SortKey): number {
+  if (a === null && b === null) return 0;
+  if (a === null) return 1;
+  if (b === null) return -1;
+  if (a.rank !== b.rank) return a.rank - b.rank;
+  if (a.rank === RANK_STRING || a.rank === RANK_OTHER) return collator.compare(a.str, b.str);
+  return a.num < b.num ? -1 : a.num > b.num ? 1 : 0;
+}
 
-  const aStr = String(a).toLowerCase();
-  const bStr = String(b).toLowerCase();
+function applyDirection(comparison: number, direction: 'asc' | 'desc'): number {
+  if (comparison === 0) return 0;
+  return direction === 'asc' ? comparison : -comparison;
+}
+
+/**
+ * Compare two cell values. Empty values (null, undefined, NaN, Invalid Date) sort last in 'asc'
+ * and first in 'desc'. Pass the column `type` to get numeric / date coercion of string values.
+ */
+export function compareValues(
+  a: unknown,
+  b: unknown,
+  direction: 'asc' | 'desc',
+  type?: GridColDef['type']
+): number {
+  return applyDirection(compareSortKeys(toSortKey(a, type), toSortKey(b, type)), direction);
+}
 
-  if (direction === 'asc') {
-    return aStr < bStr ? -1 : aStr > bStr ? 1 : 0;
-  } else {
-    return aStr > bStr ? -1 : aStr < bStr ? 1 : 0;
+/**
+ * Compare two rows by a sort model, reading cells through `valueGetter` and using each column's
+ * `type`. Returns 0 when every key is equal.
+ */
+export function compareRowsBySortModel(
+  a: GridRowModel,
+  b: GridRowModel,
+  sortModel: readonly GridSortItem[],
+  columns?: GridColumnLookup
+): number {
+  for (const sortItem of sortModel) {
+    const colDef = columns?.byField.get(sortItem.field);
+    const comparison = compareValues(
+      getCellValue(a, sortItem.field, colDef),
+      getCellValue(b, sortItem.field, colDef),
+      sortItem.sort,
+      colDef?.type
+    );
+    if (comparison !== 0) return comparison;
   }
+  return 0;
 }
 
 export function sortRows<R extends GridRowModel>(
   rows: R[],
-  sortModel: GridSortItem[]
+  sortModel: GridSortItem[],
+  columns?: GridColumnLookup
 ): R[] {
   if (sortModel.length === 0) {
     return rows;
   }
+  return sortItemsBySortModel(rows, sortModel, (row, sortItem) => {
+    const colDef = columns?.byField.get(sortItem.field);
+    return { value: getCellValue(row, sortItem.field, colDef), type: colDef?.type };
+  });
+}
 
-  const sortedRows = [...rows];
+/** The value an item sorts by for one sort key, and the column type used to compare it. */
+export interface GridSortValue {
+  value: unknown;
+  type?: GridColDef['type'];
+}
 
-  sortedRows.sort((a, b) => {
-    for (const sortItem of sortModel) {
-      const aValue = a[sortItem.field];
-      const bValue = b[sortItem.field];
+/**
+ * Stable sort of any items by a sort model. `readValue` gives the value (and column type) an item
+ * sorts by for each sort key; it is called once per item and key, not once per comparison. Used by
+ * the flat pipeline and by tree data / row grouping, whose synthetic group rows sort by their
+ * grouping value or label instead of a cell.
+ */
+export function sortItemsBySortModel<T>(
+  items: readonly T[],
+  sortModel: readonly GridSortItem[],
+  readValue: (item: T, sortItem: GridSortItem) => GridSortValue
+): T[] {
+  if (sortModel.length === 0 || items.length < 2) {
+    return [...items];
+  }
 
-      const comparison = compareValues(aValue, bValue, sortItem.sort);
+  // Read and normalize every sort value once, instead of calling valueGetter and parsing dates
+  // O(n log n) times inside the comparator.
+  const keys = sortModel.map(sortItem => items.map(item => {
+    const { value, type } = readValue(item, sortItem);
+    return toSortKey(value, type);
+  }));
 
-      if (comparison !== 0) {
-        return comparison;
-      }
+  const order = items.map((_, index) => index);
+  order.sort((ia, ib) => {
+    for (let k = 0; k < sortModel.length; k++) {
+      const comparison = applyDirection(compareSortKeys(keys[k][ia], keys[k][ib]), sortModel[k].sort);
+      if (comparison !== 0) return comparison;
     }
-    return 0;
+    return ia - ib;
   });
 
-  return sortedRows;
+  return order.map(index => items[index]);
+}
+
+/**
+ * The sort model after setting one column's direction while keeping the others: an existing key
+ * keeps its priority and only changes direction, a new key is appended, and `null` removes it.
+ */
+export function upsertSortItem(
+  sortModel: readonly GridSortItem[],
+  field: string,
+  direction: GridSortDirection
+): GridSortItem[] {
+  if (!direction) return sortModel.filter(item => item.field !== field);
+  const index = sortModel.findIndex(item => item.field === field);
+  if (index === -1) return [...sortModel, { field, sort: direction }];
+  return sortModel.map((item, i) => (i === index ? { field, sort: direction } : item));
 }