@olenbetong/appframe-ds 0.9.0 → 1.0.0

package/src/grid/useAfNewItemRow.ts

@@ -0,0 +1,258 @@
+import {
+	type DataGridPremiumProps as DataGridProps,
+	type GridApi,
+	type GridEventListener,
+	type GridPinnedRowsProp,
+	type GridRowId,
+	GridRowModes,
+	gridFocusCellSelector,
+	gridVisibleColumnDefinitionsSelector,
+} from "@mui/x-data-grid-premium";
+import { getLocalizedString } from "@olenbetong/appframe-core";
+import { type DataObject, uid } from "@olenbetong/appframe-data";
+import { setDataObjectField, usePermissions } from "@olenbetong/appframe-react";
+
+import type React from "react";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+
+import type { AfGridApi } from "./useAfGridApi.js";
+
+/**
+ * Row id of the new item row. It never collides with a data row, whose id is
+ * either the data object's uid or the value of the id field.
+ */
+export const NEW_ITEM_ROW_ID = "AfGrid-newItemRow";
+
+export const NEW_ITEM_ROW_CLASS = "AfGrid-newItemRow";
+
+/**
+ * Where the new item row is shown. `none` turns it off, and the Add button falls
+ * back to appending an unsaved row to the data.
+ */
+export type AfGridNewItemRowPosition = "top" | "bottom" | "none";
+
+export function isNewItemRow(id: GridRowId | null | undefined): boolean {
+	return id === NEW_ITEM_ROW_ID;
+}
+
+export type useAfNewItemRowOptions = {
+	apiRef: React.RefObject<GridApi | null>;
+	dataObject: DataObject<any>;
+	position: AfGridNewItemRowPosition;
+	disableInsert?: boolean;
+	pinnedRows?: GridPinnedRowsProp;
+	getRowClassName?: DataGridProps["getRowClassName"];
+};
+
+export type AfNewItemRow = {
+	/** True when the row is rendered, i.e. inserting is allowed and it is not turned off */
+	enabled: boolean;
+	/**
+	 * Saves the values the user entered in the new item row as a new record at
+	 * index -1 on the data object. Returns the blank row the grid should show
+	 * in the new item row afterwards. Throws if the save fails, so the grid keeps
+	 * the row in edit mode with the entered values.
+	 */
+	save: (record: Record<string, unknown>) => Promise<Record<string, unknown>>;
+	/** Focuses the new item row and starts editing it. Returns false when the row is not rendered. */
+	start: () => boolean;
+	/** Props to spread onto the grid */
+	gridProps: Pick<DataGridProps, "pinnedRows" | "getRowClassName">;
+	/** Style for the grid root, carrying the overlay text as a CSS custom property */
+	rootStyle: React.CSSProperties;
+};
+
+/**
+ * A DevExpress-style new item row: a single non-data row pinned above or below
+ * the data, showing an overlay text until the user starts editing it. The row
+ * lives outside the data set, so sorting, filtering, paging and grouping leave
+ * it alone.
+ *
+ * When editing starts the data object's current index moves to -1, the
+ * framework's new record, so bound forms and child data objects follow. The
+ * entered values are only written to the data object when the row is
+ * committed, exactly like edits to existing rows.
+ */
+export function useAfNewItemRow({
+	apiRef,
+	dataObject,
+	position,
+	disableInsert,
+	pinnedRows: pinnedRowsProp,
+	getRowClassName: getRowClassNameProp,
+}: useAfNewItemRowOptions): AfNewItemRow {
+	let { allowInsert } = usePermissions(dataObject);
+	let enabled = position !== "none" && allowInsert && !disableInsert;
+	// Bumped after a save, so the pinned row is replaced by a blank one
+	let [generation, setGeneration] = useState(0);
+	// The row that was current before editing started, restored when the edit is cancelled
+	let previousIndex = useRef(-1);
+	let wasEditing = useRef(false);
+
+	let row = useMemo(() => {
+		if (!enabled) return null;
+		// `getData(-1)` is a blank record with every field set to null
+		return { ...(dataObject.getData(-1) as Record<string, unknown>), [uid]: NEW_ITEM_ROW_ID, generation };
+	}, [enabled, dataObject, generation]);
+
+	let beginNewRecord = useCallback(() => {
+		if (dataObject.getCurrentIndex() !== -1) {
+			previousIndex.current = dataObject.getCurrentIndex();
+			dataObject.setCurrentIndex(-1);
+		}
+	}, [dataObject]);
+
+	let cancelNewRecord = useCallback(() => {
+		if (dataObject.getCurrentIndex() !== -1) return;
+
+		dataObject.cancelEdit();
+
+		let index = previousIndex.current;
+		if (index >= 0 && index < dataObject.getDataLength()) {
+			dataObject.setCurrentIndex(index);
+		}
+	}, [dataObject]);
+
+	let start = useCallback(() => {
+		let api = apiRef.current;
+		if (!enabled || !api) return false;
+
+		let visibleColumns = gridVisibleColumnDefinitionsSelector(apiRef);
+		let firstEditable = visibleColumns.find((c) => c.editable === true) ?? visibleColumns[0];
+		if (!firstEditable) return false;
+
+		api.setCellFocus(NEW_ITEM_ROW_ID, firstEditable.field);
+		if (api.getRowMode(NEW_ITEM_ROW_ID) !== GridRowModes.Edit) {
+			api.startRowEditMode({ id: NEW_ITEM_ROW_ID, fieldToFocus: firstEditable.field });
+		}
+
+		return true;
+	}, [apiRef, enabled]);
+
+	let save = useCallback(
+		async (record: Record<string, unknown>) => {
+			beginNewRecord();
+
+			for (let field in record) {
+				let value = record[field];
+				if (value === undefined || value === null) continue;
+				if (dataObject.getFields(field)) {
+					setDataObjectField(dataObject, field, value);
+				}
+			}
+
+			let blankRow = { ...(dataObject.getData(-1) as Record<string, unknown>), [uid]: NEW_ITEM_ROW_ID };
+
+			if (!dataObject.isDirty()) {
+				// Nothing was entered, so committing the row is the same as cancelling it
+				cancelNewRecord();
+				return blankRow;
+			}
+
+			let focusBefore = gridFocusCellSelector(apiRef);
+
+			try {
+				await dataObject.endEdit();
+			} catch (error) {
+				// The framework keeps a failed new record in storage as an unsaved row.
+				// The grid keeps the draft in the new item row instead, so the unsaved
+				// row is dropped and the current index goes back to the new record.
+				if (dataObject.getCurrentIndex() >= 0 && dataObject.isNewRecord(dataObject.getCurrentIndex())) {
+					dataObject.cancelEdit();
+				}
+				// Not through `beginNewRecord`, which would record the row the framework
+				// landed on as the one to restore on cancel
+				dataObject.setCurrentIndex(-1);
+				throw error;
+			}
+
+			setGeneration((g) => g + 1);
+
+			// The created row is the current row now; move the focus there once the
+			// grid has rendered it, so the user can keep working from where it landed.
+			let createdIndex = dataObject.getCurrentIndex();
+			if (createdIndex >= 0 && focusBefore) {
+				let createdRow = dataObject.getData(createdIndex) as any;
+				let createdId: GridRowId = createdRow[uid];
+				setTimeout(() => {
+					let api = apiRef.current;
+					if (!api || !api.getRow(createdId)) return;
+					let rowIndex = api.getRowIndexRelativeToVisibleRows(createdId);
+					if (rowIndex >= 0) api.scrollToIndexes({ rowIndex });
+					api.setCellFocus(createdId, focusBefore.field);
+				});
+			}
+
+			return blankRow;
+		},
+		[apiRef, dataObject, beginNewRecord, cancelNewRecord],
+	);
+
+	useEffect(() => {
+		if (!enabled) return;
+
+		// Moves the data object to the new record when editing starts, whether the
+		// user started it or `start` did, and discards it when the edit is cancelled.
+		// A commit goes through `save` instead.
+		const handleRowModesModelChange: GridEventListener<"rowModesModelChange"> = (model) => {
+			let entry = model[NEW_ITEM_ROW_ID] as { mode: GridRowModes; ignoreModifications?: boolean } | undefined;
+			let isEditing = entry?.mode === GridRowModes.Edit;
+
+			if (isEditing && !wasEditing.current) {
+				beginNewRecord();
+			} else if (!isEditing && wasEditing.current && entry?.ignoreModifications === true) {
+				// Deferred until the grid has left edit mode and put the focus back on the
+				// cell, so that a bound current index moves the focus from a mounted cell
+				// instead of from an editor that is about to be unmounted.
+				setTimeout(cancelNewRecord);
+			}
+
+			wasEditing.current = isEditing;
+		};
+
+		return apiRef.current?.subscribeEvent("rowModesModelChange", handleRowModesModelChange);
+	}, [apiRef, enabled, beginNewRecord, cancelNewRecord]);
+
+	let pinnedRows = useMemo<GridPinnedRowsProp | undefined>(() => {
+		if (!row) return pinnedRowsProp;
+
+		// The new item row sits next to the data, inside any rows the consumer pinned
+		return {
+			top: position === "top" ? [...(pinnedRowsProp?.top ?? []), row] : pinnedRowsProp?.top,
+			bottom: position === "bottom" ? [row, ...(pinnedRowsProp?.bottom ?? [])] : pinnedRowsProp?.bottom,
+		};
+	}, [row, position, pinnedRowsProp]);
+
+	let getRowClassName = useCallback<NonNullable<DataGridProps["getRowClassName"]>>(
+		(params) => {
+			let className = getRowClassNameProp?.(params) ?? "";
+			return params.id === NEW_ITEM_ROW_ID ? `${className} ${NEW_ITEM_ROW_CLASS}`.trim() : className;
+		},
+		[getRowClassNameProp],
+	);
+
+	let rootStyle = useMemo<React.CSSProperties>(
+		() =>
+			({
+				// Read by the overlay's `content`, so the text is localized without a DOM node
+				"--AfGrid-newItemRowText": JSON.stringify(getLocalizedString("Click here to add a new row")),
+			}) as React.CSSProperties,
+		[],
+	);
+
+	useEffect(() => {
+		if (apiRef.current) {
+			(apiRef.current as AfGridApi).startNewItemRow = start;
+		}
+	}, [apiRef, start]);
+
+	return {
+		enabled,
+		save,
+		start,
+		gridProps: enabled
+			? { pinnedRows, getRowClassName }
+			: { pinnedRows: pinnedRowsProp, getRowClassName: getRowClassNameProp },
+		rootStyle,
+	};
+}

package/src/grid/useAfPagination.ts

@@ -1,4 +1,4 @@
-import type { DataGridProProps, GridPaginationModel } from "@mui/x-data-grid-pro";
+import type { DataGridPremiumProps, GridPaginationModel } from "@mui/x-data-grid-premium";
 import type { DataObject } from "@olenbetong/appframe-data";
 import { useDataLength, usePaging, useParameter } from "@olenbetong/appframe-react";
 
@@ -10,7 +10,7 @@ import { useMemo } from "react";
  *
  * @param dataObject Data object grid is used with
  */
-export function useAfPagination(dataObject: DataObject<any>): Partial<DataGridProProps> {
+export function useAfPagination(dataObject: DataObject<any>): Partial<DataGridPremiumProps> {
 	let paging = usePaging(dataObject);
 	let maxRecords = useParameter(dataObject, "maxRecords");
 	let dataLength = useDataLength(dataObject);

package/src/grid/useAfPersistedState.ts

@@ -1,4 +1,4 @@
-import type { GridApi, GridInitialState, GridPaginationModel } from "@mui/x-data-grid-pro";
+import type { GridApi, GridInitialState, GridPaginationModel } from "@mui/x-data-grid-premium";
 
 import localforage from "localforage";
 import { useEffect, useState } from "react";
@@ -54,6 +54,12 @@ function removeNonPersistedState(state: GridInitialState, config?: StatePersiste
 	if (config?.pinnedColumns !== false) {
 		newState.pinnedColumns = state.pinnedColumns;
 	}
+	if (config?.rowGrouping !== false) {
+		newState.rowGrouping = state.rowGrouping;
+	}
+	if (config?.aggregation !== false) {
+		newState.aggregation = state.aggregation;
+	}
 	if (config?.columns?.columnVisibilityModel !== false) {
 		columns.columnVisibilityModel = state.columns?.columnVisibilityModel;
 	}
@@ -166,8 +172,10 @@ setTimeout(() => {
 }, 2000);
 
 export type StatePersistenceConfig = {
+	aggregation?: boolean;
 	density?: boolean;
 	pinnedColumns?: boolean;
+	rowGrouping?: boolean;
 	columns?: {
 		columnVisibilityModel?: boolean;
 		dimensions?: boolean;

package/src/grid/useAfRowEditModel.ts

@@ -1,18 +1,20 @@
 import {
-	type DataGridProProps as DataGridProps,
+	type DataGridPremiumProps as DataGridProps,
 	type GridApi,
 	type GridEventListener,
 	type GridRowId,
 	GridRowModes,
 	gridFocusCellSelector,
 	gridVisibleColumnFieldsSelector,
-} from "@mui/x-data-grid-pro";
-import type { DataObject } from "@olenbetong/appframe-data";
+} from "@mui/x-data-grid-premium";
+import { type DataObject, uid } from "@olenbetong/appframe-data";
 import { setDataObjectField } from "@olenbetong/appframe-react";
 
 import type React from "react";
 import { useCallback, useEffect } from "react";
 
+import { type AfNewItemRow, isNewItemRow } from "./useAfNewItemRow.js";
+
 function localDateAsUtcDate(date: Date) {
 	const utcDate = new Date(date);
 	console.log("year", utcDate, utcDate.getUTCFullYear(), date.getFullYear());
@@ -33,12 +35,12 @@ export type AfRowEditModelProps<T extends Record<string, unknown> = Record<strin
 	dataObject: DataObject<T>;
 	idField: string;
 	disableEdit: boolean;
+	/** The new item row, when the grid renders one. Commits on that row are saved through it. */
+	newItemRow?: AfNewItemRow;
 };
 
-const uid: any = globalThis.af?.data?.uid ?? Symbol();
-
 /**
- * Binds a MUI DataGridPro row editing model to a data object. Editing will not affect the
+ * Binds a MUI DataGridPremium row editing model to a data object. Editing will not affect the
  * data object until a save event is triggered. If saving fails, will attempt to go back
  * into edit mode with the unsaved changes.
  */
@@ -47,11 +49,16 @@ export function useAfRowEditModel<T extends Record<string, unknown> = Record<str
 	dataObject,
 	idField,
 	disableEdit,
+	newItemRow,
 }: AfRowEditModelProps<T>): Partial<DataGridProps> {
 	let processRowUpdate = useCallback(
 		async (newRow: any, oldRow: any) => {
 			let { id, isNew, ...record } = newRow;
-			id = (record as any)[(af as any).data.uid] ?? (record as any)[idField] ?? id;
+			id = (record as any)[uid] ?? (record as any)[idField] ?? id;
+
+			if (isNewItemRow(id) && newItemRow) {
+				return newItemRow.save(record);
+			}
 
 			if (isNew) {
 				let savedRow = await dataObject.addRow(newRow);
@@ -90,7 +97,7 @@ export function useAfRowEditModel<T extends Record<string, unknown> = Record<str
 
 			return savedNewRow;
 		},
-		[dataObject, idField],
+		[dataObject, idField, newItemRow],
 	);
 
 	useEffect(() => {
@@ -98,12 +105,15 @@ export function useAfRowEditModel<T extends Record<string, unknown> = Record<str
 		// to remove it manually if editing is cancelled
 		const handleRowModesModelChange: GridEventListener<"rowModesModelChange"> = (model) => {
 			for (let id of Object.keys(model)) {
+				// The new item row is not in the data object; `useAfNewItemRow` handles it
+				if (isNewItemRow(id)) continue;
+
 				if (model[id].mode === GridRowModes.View && (model[id] as any)?.ignoreModifications === true) {
 					let row = apiRef.current?.getRow(id);
 					if (row?.isNew) {
 						let focusBefore = gridFocusCellSelector(apiRef);
 
-						apiRef.current?.updateRows([{ [(af as any).data.uid]: id, id, _action: "delete" } as any]);
+						apiRef.current?.updateRows([{ [uid]: id, id, _action: "delete" } as any]);
 
 						setTimeout(() => {
 							if (focusBefore && dataObject.getDataLength()) {
@@ -117,9 +127,7 @@ export function useAfRowEditModel<T extends Record<string, unknown> = Record<str
 						// MUI grid only reverts changes on editable fields, while for example lookups can have edited
 						// values that are not editable, so we need to manually revert those changes
 						let index = dataObject.findIndex((r) => (r as any)[uid] === id || (r as any)[idField] === id);
-						apiRef.current?.updateRows([
-							{ [(af as any).data.uid]: id, id, ...(dataObject.getData(index) as any) } as any,
-						]);
+						apiRef.current?.updateRows([{ [uid]: id, id, ...(dataObject.getData(index) as any) } as any]);
 					}
 				}
 			}

package/src/grid/useAfRowGrouping.ts

@@ -0,0 +1,47 @@
+import type { GridAggregationModel, GridInitialState, GridRowGroupingModel } from "@mui/x-data-grid-premium";
+
+import { useState } from "react";
+
+export type AfGridGroupingProps = {
+	aggregationModel: GridAggregationModel;
+	onAggregationModelChange: (model: GridAggregationModel) => void;
+	rowGroupingModel: GridRowGroupingModel;
+	onRowGroupingModelChange: (model: GridRowGroupingModel) => void;
+};
+
+export type AfGridGrouping = {
+	/**
+	 * True while at least one column is grouped. The grid uses this to fall back
+	 * to client side sorting, which row grouping requires.
+	 */
+	isGrouping: boolean;
+	gridProps: AfGridGroupingProps;
+};
+
+/**
+ * Holds the row grouping and aggregation models in component state so the grid
+ * knows when a grouping is active, and seeds them from the restored layout.
+ *
+ * Both features are computed on the client, over the rows the grid has been
+ * given. With a dynamically loading data object that is the current page only,
+ * so a grouped grid usually wants `maxRecords` high enough to hold the whole
+ * result, or `dynamicLoading` turned off.
+ */
+export function useAfRowGrouping(initialState: GridInitialState): AfGridGrouping {
+	let [rowGroupingModel, setRowGroupingModel] = useState<GridRowGroupingModel>(
+		() => initialState.rowGrouping?.model ?? [],
+	);
+	let [aggregationModel, setAggregationModel] = useState<GridAggregationModel>(
+		() => initialState.aggregation?.model ?? {},
+	);
+
+	return {
+		isGrouping: rowGroupingModel.length > 0,
+		gridProps: {
+			aggregationModel,
+			onAggregationModelChange: setAggregationModel,
+			rowGroupingModel,
+			onRowGroupingModelChange: setRowGroupingModel,
+		},
+	};
+}

package/src/grid/useAfServerAggregation.ts

@@ -0,0 +1,145 @@
+import type { GridAggregationModel } from "@mui/x-data-grid-premium";
+import type { DataObject } from "@olenbetong/appframe-data";
+import { useEffect, useMemo, useState } from "react";
+
+/**
+ * MUI's aggregation function names mapped onto the SQL aggregates the data API understands.
+ *
+ * `size` counts rows rather than values, and the data API has no aggregate that skips nulls
+ * differently, so it is left to the client — the grid already knows the row count.
+ */
+const SQL_AGGREGATES: Record<string, string> = {
+	sum: "SUM",
+	avg: "AVG",
+	min: "MIN",
+	max: "MAX",
+};
+
+export type AfServerAggregationResult = {
+	/** Aggregated value per field, for the whole filtered result rather than the loaded page. */
+	values: Record<string, unknown>;
+	loading: boolean;
+	error: string | null;
+};
+
+const EMPTY: AfServerAggregationResult = { values: {}, loading: false, error: null };
+
+/**
+ * Reads the fields the aggregation model can be answered server side, as data API field
+ * definitions. A field the data object does not have — a calculated column, say — is skipped:
+ * the server cannot aggregate something it never sends.
+ */
+function getAggregateFields(dataObject: DataObject<any>, model: GridAggregationModel) {
+	let fields: Array<{ name: string; aggregate: string }> = [];
+
+	for (let [name, functionName] of Object.entries(model)) {
+		let aggregate = SQL_AGGREGATES[functionName];
+		if (!aggregate) continue;
+		if (!dataObject.getFields(name)) continue;
+
+		fields.push({ name, aggregate });
+	}
+
+	return fields;
+}
+
+/**
+ * Totals for the whole filtered result, not just the rows the grid is holding.
+ *
+ * MUI aggregates over the rows it has been given. On a dynamically loading data object that is
+ * the current page, so a sum over a paged grid is a sum of one page — which looks like a total
+ * and is not one. This asks the server for the real thing with a second, cheap retrieve: the same
+ * view under the same filters, requesting only the aggregates, returning a single row.
+ *
+ * The request goes straight to the data handler rather than through the data object, so the
+ * grid's own data and parameters are untouched.
+ *
+ * @param dataObject The grid's data object
+ * @param model The grid's aggregation model
+ * @param enabled Whether to load at all
+ */
+export function useAfServerAggregation(
+	dataObject: DataObject<any>,
+	model: GridAggregationModel,
+	enabled: boolean,
+): AfServerAggregationResult {
+	let [result, setResult] = useState<AfServerAggregationResult>(EMPTY);
+
+	// The model is an object rebuilt on every render, so key the effect on its content.
+	let modelKey = useMemo(() => JSON.stringify(model ?? {}), [model]);
+
+	/*
+	 * The totals have to follow the grid's filters exactly. Rather than mirroring every parameter
+	 * that can move them, this reloads whenever the data object does — which is precisely when a
+	 * filter, a where clause or a master row changed.
+	 */
+	let [reloadCount, setReloadCount] = useState(0);
+
+	useEffect(() => {
+		if (!enabled) return;
+
+		let controller = new AbortController();
+
+		function reload() {
+			setReloadCount((count) => count + 1);
+		}
+
+		dataObject.attachEvent("onDataLoaded", reload, { signal: controller.signal });
+		dataObject.attachEvent("onAfterSave", reload, { signal: controller.signal });
+		dataObject.attachEvent("onRecordDeleted", reload, { signal: controller.signal });
+
+		return () => controller.abort();
+	}, [dataObject, enabled]);
+
+	useEffect(() => {
+		let fields = getAggregateFields(dataObject, JSON.parse(modelKey));
+
+		if (!enabled || fields.length === 0) {
+			setResult(EMPTY);
+			return;
+		}
+
+		let controller = new AbortController();
+		let cancelled = false;
+
+		setResult((current) => ({ ...current, loading: true, error: null }));
+
+		dataObject.dataHandler
+			.retrieve(
+				{
+					fields,
+					// No groupBy: one row holding the aggregates over everything that matches.
+					maxRecords: 1,
+					whereClause: dataObject.getParameter("whereClause"),
+					whereObject: dataObject.getParameter("whereObject"),
+					filterString: dataObject.getParameter("filterString"),
+					filterObject: dataObject.getParameter("filterObject"),
+					masterChildCriteria: dataObject.getParameter("masterChildCriteria"),
+				} as any,
+				{ signal: controller.signal },
+			)
+			.then((rows: any[]) => {
+				if (cancelled) return;
+
+				setResult({ values: (rows?.[0] as Record<string, unknown>) ?? {}, loading: false, error: null });
+			})
+			.catch((cause: unknown) => {
+				if (cancelled || controller.signal.aborted) return;
+
+				/*
+				 * Not every view can be aggregated — one built on a UNION or holding a computed
+				 * column the server will not sum. Falling back to the client's page total is
+				 * wrong in a quieter way than showing an error banner over a working grid, so
+				 * the failure is reported to the caller and the grid keeps its own numbers.
+				 */
+				setResult({ values: {}, loading: false, error: String((cause as Error)?.message ?? cause) });
+			});
+
+		return () => {
+			cancelled = true;
+			controller.abort();
+		};
+	}, [dataObject, modelKey, enabled, reloadCount]);
+
+	return result;
+}

package/src/grid/useAfSortModel.ts

@@ -1,4 +1,4 @@
-import type { DataGridProProps, GridCallbackDetails, GridSortModel } from "@mui/x-data-grid-pro";
+import type { DataGridPremiumProps, GridCallbackDetails, GridSortModel } from "@mui/x-data-grid-premium";
 import type { DataObject, RetrieveParameters, SortOrder } from "@olenbetong/appframe-data";
 import { useParameter } from "@olenbetong/appframe-react";
 import { useCallback, useMemo } from "react";
@@ -37,11 +37,19 @@ export function useAfSortModel({
 	dataObject,
 	columns,
 	disableServerSorting = false,
+	isGrouping = false,
 }: {
 	dataObject: DataObject<any>;
 	columns: AfGridColumn[];
 	disableServerSorting?: boolean;
-}): Partial<DataGridProProps> {
+	/**
+	 * True while a row grouping is active. Grouped rows are built and ordered on
+	 * the client, so the grid has to sort locally — but the model stays
+	 * controlled and keeps writing through to the data object, so the sort order
+	 * still matches what an Excel export produces.
+	 */
+	isGrouping?: boolean;
+}): Partial<DataGridPremiumProps> {
 	let sortOrder = useParameter(dataObject, "sortOrder");
 	let sortModel = useMemo(() => {
 		let sortModel = afSortOrderToMuiSortModel(dataObject, sortOrder);
@@ -68,5 +76,9 @@ export function useAfSortModel({
 		[dataObject, columns],
 	);
 
-	return disableServerSorting ? {} : { sortingMode: "server", sortModel, onSortModelChange };
+	if (disableServerSorting) {
+		return {};
+	}
+
+	return { sortingMode: isGrouping ? "client" : "server", sortModel, onSortModelChange };
 }