@olenbetong/appframe-ds 1.2.0 → 1.3.1

package/src/grid/index.tsx

@@ -1,489 +1,503 @@
-import "./index.css";
-
-import { Alert } from "@digdir/designsystemet-react";
-import {
-	DataGridPremium as DataGrid,
-	type DataGridPremiumProps as DataGridProps,
-	GRID_AGGREGATION_FUNCTIONS,
-	GRID_ROOT_GROUP_ID,
-	type GridAggregationFunction,
-	type GridApi,
-	type GridFilterModel,
-	useGridApiRef,
-} from "@mui/x-data-grid-premium";
-import { type DataObject, uid } from "@olenbetong/appframe-data";
-import { DataObjectProvider, useLoading } from "@olenbetong/appframe-react";
-
-import clsx from "clsx";
-import { useEffect, useMemo, useState } from "react";
-import { FilterBuilder } from "../filter/index.js";
-import { AfGridColumnsPanel } from "./AfGridColumnsPanel.js";
-import { type AfGridContextValue, AfGridContextProvider } from "./AfGridContext.js";
-import { AfGridError } from "./AfGridError.js";
-import { registerLicense } from "./license.js";
-import { AF_GRID_LOCALE_TEXT } from "./localization.js";
-import { dsBaseSlots } from "./slots/index.js";
-import { AfGridThemeProvider } from "./theme.js";
-import {
-	type AfExcelExportOptions,
-	AfGridExcelExportMenuItem,
-	type AfGridExcelExportOptions,
-	AfGridToolbar,
-	AfGridToolbarExcelExportButton,
-	GridToolbarAddButton,
-	GridToolbarAddIfAllowedButton,
-	GridToolbarColumnsButton,
-	GridToolbarContainer,
-	GridToolbarFilterButton,
-	GridToolbarMoreOptionsButton,
-	GridToolbarRefreshButton,
-	GridToolbarResetLayoutButton,
-} from "./Toolbar.js";
-import type { AfGridColumn } from "./useAfColumns.js";
-import { type AfGridColDef, useAfColumns } from "./useAfColumns.js";
-import { useAfCurrentIndex } from "./useAfCurrentIndex.js";
-import { useAfData } from "./useAfData.js";
-import { useAfFilterFields } from "./useAfFilterFields.js";
-import { useAfFilter } from "./useAfFilter.js";
-import { type AfGridApi, useAfGridApi } from "./useAfGridApi.js";
-import { useAfKeyBindings } from "./useAfKeyBindings.js";
-import { type AfGridNewItemRowPosition, NEW_ITEM_ROW_ID, isNewItemRow, useAfNewItemRow } from "./useAfNewItemRow.js";
-import { useAfPagination } from "./useAfPagination.js";
-import {
-	isPersistedStateLoaded,
-	type StatePersistenceConfig,
-	settingsLoaded,
-	useAfPersistedState,
-} from "./useAfPersistedState.js";
-import { useAfRowEditModel } from "./useAfRowEditModel.js";
-import { useAfRowGrouping } from "./useAfRowGrouping.js";
-import { useAfServerAggregation } from "./useAfServerAggregation.js";
-import { useAfSortModel } from "./useAfSortModel.js";
-import { getLocalizedString } from "../i18n.js";
-
-export * from "./formatters.js";
-export * from "./GridEditLookup.js";
-// MUI X as a namespace (`DataGrid.DataGridPremium`, `DataGrid.GridColDef`, `DataGrid.useGridApiRef`,
-// ...), for grids that are not bound to a data object - from here rather than the app, so a
-// platform app does not bundle a second MUI X. Same shape as appframe-mui exported it.
-export * as DataGrid from "@mui/x-data-grid-premium";
-export * as MuiDataGrid from "@mui/x-data-grid-premium";
-
-registerLicense();
-
-/**
- * The grid's criteria live in a `FilterTree` owned by `useAfFilter`, not in
- * MUI's filter model, so the model is always empty. It is hoisted so the
- * reference is stable and the grid does not treat it as a change.
- */
-const EMPTY_FILTER_MODEL: GridFilterModel = { items: [] };
-
-const privSysColumns: AfGridColDef[] = [
-	{ field: "PrimKey", editable: false, hide: true },
-	{ field: "Created", editable: false, hide: true },
-	{ field: "CreatedBy", editable: false, hide: true },
-	{ field: "Updated", editable: false, hide: true },
-	{ field: "UpdatedBy", editable: false, hide: true },
-];
-
-export const systemColumns = {
-	[Symbol.iterator]: () => privSysColumns[Symbol.iterator](),
-	PrimKey: privSysColumns[0],
-	Created: privSysColumns[1],
-	CreatedBy: privSysColumns[2],
-	Updated: privSysColumns[3],
-	UpdatedBy: privSysColumns[4],
-};
-
-export type {
-	AfExcelExportOptions,
-	AfGridApi,
-	AfGridColDef,
-	AfGridColumn,
-	AfGridExcelExportOptions,
-	AfGridNewItemRowPosition,
-};
-export type { AfGridGrouping, AfGridGroupingProps } from "./useAfRowGrouping.js";
-
-export {
-	AF_GRID_LOCALE_TEXT,
-	NEW_ITEM_ROW_ID,
-	isNewItemRow,
-	useAfNewItemRow,
-	AfGridColumnsPanel,
-	AfGridExcelExportMenuItem,
-	AfGridThemeProvider,
-	AfGridToolbar,
-	AfGridToolbarExcelExportButton,
-	GridToolbarAddButton,
-	GridToolbarAddIfAllowedButton,
-	GridToolbarColumnsButton,
-	GridToolbarContainer,
-	GridToolbarFilterButton,
-	GridToolbarMoreOptionsButton,
-	GridToolbarRefreshButton,
-	GridToolbarResetLayoutButton,
-	useAfColumns,
-	useAfCurrentIndex,
-	useAfData,
-	useAfFilter,
-	useAfFilterFields,
-	useAfPagination,
-	useAfPersistedState,
-	useAfRowEditModel,
-	useAfRowGrouping,
-	useAfServerAggregation,
-	useAfSortModel,
-};
-
-export type AfGridProps = {
-	apiRef?: React.RefObject<GridApi>;
-	/**
-	 * If set to true, the grid will automatically load data if the data object has not
-	 * been loaded previously.
-	 */
-	autoLoad?: boolean;
-	/**
-	 * Bind the focused/selected row to the current index in the data object.
-	 * Useful if you want child data to load as the user navigates the grid.
-	 */
-	bindIndex?: boolean;
-	columns: AfGridColumn[];
-	dataObject: DataObject<any>;
-	/**
-	 * The layout version of the grid. Persisted grid state will only be restored
-	 * if the version matches.
-	 */
-	layoutVersion?: string | number;
-	/**
-	 * Field that contains a unique identifier for each row. Defaults to PrimKey.
-	 */
-	idField?: string;
-	/**
-	 * A function that can be used to transform the data object data before it is
-	 * passed to the grid, for example to create summary rows.
-	 */
-	getData?: (data: Readonly<Readonly<any>[]>) => any[];
-	/**
-	 * Override the data object permission, and remove the delete button from the default row actions
-	 */
-	disableDelete?: boolean;
-	/**
-	 * Override the data object permission, and remove the edit button from the default row actions
-	 */
-	disableEdit?: boolean;
-	/**
-	 * Override the data object permission, and remove the Add button from the default toolbar.
-	 */
-	disableInsert?: boolean;
-	/**
-	 * Use to disable server sorting. Required for example when using row grouping.
-	 */
-	disableServerSorting?: boolean;
-	/**
-	 * The view the filter builder saves and loads saved filters for, and converts
-	 * its filter against. Without it the filter builder can still be used, but
-	 * saved filters are unavailable.
-	 */
-	filterViewName?: string;
-	/**
-	 * Where to show the new item row: a non-data row pinned above or below the data
-	 * that reads "Click here to add a new row" until the user starts editing it.
-	 * Editing it moves the data object to the new record at index -1, and committing
-	 * it saves the record. Only shown when the data object allows insert and
-	 * `disableInsert` is not set. `none` turns it off, in which case the Add button
-	 * appends an unsaved row to the data instead. Defaults to `bottom`.
-	 */
-	newItemRow?: AfGridNewItemRowPosition;
-	/**
-	 * A unique ID used to persist the grid state. It is better to use the layoutVersion
-	 * property if you would like to ignore any previously persisted state, as changing
-	 * this property will leave orphan records for the previous id in the Indexed DB
-	 * grid layout store.
-	 */
-	id: string;
-	/**
-	 * Object almost matching the grid state, but with all values as booleans. This
-	 * is used to configure which properties should be persisted.
-	 */
-	persistenceModel?: StatePersistenceConfig;
-	/**
-	 * Ask the server for the grand total instead of adding up the rows the grid is holding.
-	 *
-	 * MUI aggregates over the loaded rows, which on a dynamically loading data object is the
-	 * current page — a sum that looks like a total and is not one. With this on, the grid runs a
-	 * second retrieve under the same filters that returns only the aggregates, so the footer shows
-	 * the total over the whole result. Subtotals on grouped rows stay client side, since a group
-	 * only exists over the rows the grid has.
-	 *
-	 * `sum`, `avg`, `min` and `max` are resolved server side; `size` and any custom aggregation
-	 * function stay on the client. If the view cannot be aggregated the grid falls back to the
-	 * client total rather than failing.
-	 *
-	 * Defaults to true when the data object loads dynamically, since that is exactly the case
-	 * where the client total is wrong.
-	 */
-	serverAggregation?: boolean;
-} & Omit<
-	DataGridProps,
-	| "apiRef"
-	| "columns"
-	| "loading"
-	| "rows"
-	| "filterMode"
-	| "filterModel"
-	| "onFilterModelChange"
-	| "sortingMode"
-	| "sortModel"
-	| "onSortModelChange"
-	| "rowGroupingModel"
-	| "onRowGroupingModelChange"
-	| "aggregationModel"
-	| "onAggregationModelChange"
-	| "editRowsModel"
-	| "editMode"
-	| "onRowEditCommit"
-	| "onEditRowsModelChange"
-	| "pagination"
-	| "paginationMode"
-	| "pageSize"
-	| "rowCount"
-	| "rowsPerPageOptions"
-	| "onPageChange"
-	| "onPageSizeChange"
->;
-
-// This wrapper component prevents the actual grid from rendering until the persisted state has been loaded.
-// This is to prevent the grid from flickering when the persisted state is restored, plus the grid sometimes
-// resets the column order if not provided in the initial state
-export function AfGrid(props: AfGridProps) {
-	let [loaded, setLoaded] = useState(isPersistedStateLoaded());
-
-	useEffect(() => {
-		settingsLoaded.then(() => setLoaded(true));
-	}, []);
-
-	return (
-		<AfGridThemeProvider>
-			{loaded ? <AfGrid_ {...props} /> : <div className="AfGrid-loading">{getLocalizedString("Loading...")}</div>}
-		</AfGridThemeProvider>
-	);
-}
-
-function AfGrid_(props: AfGridProps) {
-	let {
-		autoLoad = false,
-		apiRef: apiRefProp,
-		bindIndex,
-		columns: columnsProp,
-		disableServerSorting,
-		disableInsert,
-		disableDelete,
-		disableEdit = false,
-		dataObject,
-		filterViewName,
-		layoutVersion = 0,
-		getData,
-		idField = "PrimKey",
-		id,
-		// Follows the data object's `newRecordPosition` when it has one (older data
-		// packages have none and append), so the row sits where the record will land
-		newItemRow: newItemRowPosition = dataObject.options?.newRecordPosition === "start" ? "top" : "bottom",
-		persistenceModel,
-		initialState,
-		pinnedRows,
-		getRowClassName,
-		serverAggregation = dataObject.options?.dynamicLoading === true,
-		...other
-	} = props;
-	let apiRefPriv = useGridApiRef();
-	let apiRef = apiRefProp ?? apiRefPriv;
-	useAfGridApi(props, apiRef);
-	let newItemRow = useAfNewItemRow({
-		apiRef,
-		dataObject,
-		position: newItemRowPosition,
-		disableInsert,
-		pinnedRows,
-		getRowClassName,
-	});
-	let initialState_ = useAfPersistedState({
-		apiRef,
-		columns: columnsProp,
-		id,
-		layoutVersion,
-		persistenceModel,
-		initialState,
-	});
-	// Seeded from the restored layout, so a persisted grouping survives a reload.
-	let grouping = useAfRowGrouping(initialState_);
-	let loading = useLoading(dataObject);
-	let paging = useAfPagination(dataObject);
-	let sortModel = useAfSortModel({
-		dataObject,
-		columns: columnsProp,
-		disableServerSorting,
-		isGrouping: grouping.isGrouping,
-	});
-	let gridFilter = useAfFilter({ autoLoad, dataObject, id });
-	let [snackbar, setSnackbar] = useState<string | null>(null);
-	let [isFilterBuilderOpen, setFilterBuilderOpen] = useState(false);
-	let [isColumnsPanelOpen, setColumnsPanelOpen] = useState(false);
-	let editProps = useAfRowEditModel({ dataObject, disableEdit, idField, apiRef, newItemRow });
-	let data = useAfData(dataObject, { getData });
-	useAfCurrentIndex({
-		apiRef,
-		dataObject,
-		idField,
-		enabled: !!bindIndex,
-		newItemRowId: newItemRow.enabled ? NEW_ITEM_ROW_ID : null,
-	});
-	let columns = useAfColumns({
-		apiRef,
-		dataObject,
-		disableEdit,
-		disableDelete,
-		columnsProp,
-		idField,
-	});
-	let filterFields = useAfFilterFields(dataObject, columnsProp);
-
-	let keyEvents = useAfKeyBindings({ apiRef, dataObject });
-
-	useEffect(() => {
-		if (!snackbar) return;
-
-		let timeout = setTimeout(() => setSnackbar(null), 6000);
-
-		return () => clearTimeout(timeout);
-	}, [snackbar]);
-
-	let serverAggregates = useAfServerAggregation(
-		dataObject,
-		grouping.gridProps.aggregationModel,
-		serverAggregation && !grouping.isGrouping,
-	);
-
-	/*
-	 * The grand total row asks for `groupId === GRID_ROOT_GROUP_ID`; every other call is a group
-	 * subtotal, which only means anything over the rows the grid actually has. So the server value
-	 * is substituted for the root and the built-in function is left to do the rest.
-	 */
-	let aggregationFunctions = useMemo(() => {
-		if (!serverAggregation) return undefined;
-
-		let base = other.aggregationFunctions ?? GRID_AGGREGATION_FUNCTIONS;
-		let wrapped: Record<string, GridAggregationFunction> = {};
-
-		for (let [name, fn] of Object.entries(base) as Array<[string, GridAggregationFunction]>) {
-			wrapped[name] = {
-				...fn,
-				apply: (params, api) => {
-					if (params.groupId === GRID_ROOT_GROUP_ID && params.field in serverAggregates.values) {
-						return serverAggregates.values[params.field];
-					}
-
-					return fn.apply(params, api);
-				},
-			};
-		}
-
-		return wrapped;
-	}, [serverAggregation, other.aggregationFunctions, serverAggregates.values]);
-
-	let gridContext = useMemo<AfGridContextValue>(
-		() => ({
-			id,
-			apiRef,
-			filterFields,
-			...gridFilter,
-			openFilterBuilder: () => setFilterBuilderOpen(true),
-			openColumnsPanel: () => setColumnsPanelOpen(true),
-		}),
-		[id, apiRef, filterFields, gridFilter],
-	);
-
-	return (
-		<DataObjectProvider dataObject={dataObject}>
-			<AfGridContextProvider value={gridContext}>
-				<div className="AfGrid-root" style={newItemRow.rootStyle} {...keyEvents} tabIndex={-1}>
-					<DataGrid
-						apiRef={apiRef}
-						rows={data}
-						columns={columns}
-						loading={loading}
-						getRowId={(row) => row[uid] ?? row[idField]}
-						{...editProps}
-						{...newItemRow.gridProps}
-						/*
-						 * Our own filter tree drives the data object, so MUI never
-						 * sees a filter model. The header filter cells are replaced
-						 * by `renderHeaderFilter` on every column.
-						 */
-						filterMode="server"
-						filterModel={EMPTY_FILTER_MODEL}
-						{...sortModel}
-						headerFilters
-						{...paging}
-						showToolbar
-						{...other}
-						{...grouping.gridProps}
-						/*
-						 * Spread rather than passed, because the grid merges props over its defaults with
-						 * `Object.assign`: an explicit `undefined` here would wipe out the built-in
-						 * aggregation functions rather than fall back to them, and the grid then throws on
-						 * the first render.
-						 */
-						{...(aggregationFunctions ? { aggregationFunctions } : {})}
-						localeText={{ ...other.localeText, ...AF_GRID_LOCALE_TEXT }}
-						slots={{
-							...dsBaseSlots,
-							toolbar: () => <AfGridToolbar disableInsert={disableInsert} />,
-							...other.slots,
-						}}
-						initialState={initialState_}
-						slotProps={{
-							...other.slotProps,
-							headerFilterCell: {
-								...other.slotProps?.headerFilterCell,
-								headerClassName: clsx(other.slotProps?.headerFilterCell?.headerClassName, "AfGrid-headerCell"),
-								showRightBorder: true,
-							},
-						}}
-						onProcessRowUpdateError={(error) => {
-							other.onProcessRowUpdateError?.(error);
-							let message = "message" in (error as any) ? (error as any).message : String(error);
-							setSnackbar(message);
-						}}
-					/>
-				</div>
-				<AfGridError apiRef={apiRef} dataObject={dataObject} />
-				{isColumnsPanelOpen && <AfGridColumnsPanel open onClose={() => setColumnsPanelOpen(false)} />}
-				<FilterBuilder
-					variant="dialog"
-					open={isFilterBuilderOpen}
-					onClose={() => setFilterBuilderOpen(false)}
-					fields={filterFields}
-					viewName={filterViewName}
-					dataObject={dataObject}
-					/*
-					 * The builder edits the same named slot and the same tree as the
-					 * header filters, so a criterion added in one shows up in the
-					 * other. Applying writes the slot directly, which skips the
-					 * header filters' debounce.
-					 */
-					slotName={id}
-					value={gridFilter.filter}
-					onChange={gridFilter.setFilter}
-				/>
-				{!!snackbar && (
-					<div className="AfGrid-snackbar">
-						<Alert data-color="danger" data-size="sm" onClick={() => setSnackbar(null)}>
-							{snackbar}
-						</Alert>
-					</div>
-				)}
-			</AfGridContextProvider>
-		</DataObjectProvider>
-	);
-}
+import "./index.css";
+
+import { Alert } from "@digdir/designsystemet-react";
+import {
+	DataGridPremium as DataGrid,
+	type DataGridPremiumProps as DataGridProps,
+	GRID_AGGREGATION_FUNCTIONS,
+	GRID_ROOT_GROUP_ID,
+	type GridAggregationFunction,
+	type GridApi,
+	type GridFilterModel,
+	type GridGroupNode,
+	useGridApiRef,
+} from "@mui/x-data-grid-premium";
+import { type DataObject, uid } from "@olenbetong/appframe-data";
+import { DataObjectProvider, useLoading } from "@olenbetong/appframe-react";
+
+import clsx from "clsx";
+import { useEffect, useMemo, useState } from "react";
+import { FilterBuilder } from "../filter/index.js";
+import { AfGridColumnsPanel } from "./AfGridColumnsPanel.js";
+import { type AfGridContextValue, AfGridContextProvider } from "./AfGridContext.js";
+import { AfGridError } from "./AfGridError.js";
+import { registerLicense } from "./license.js";
+import { AF_GRID_LOCALE_TEXT } from "./localization.js";
+import { dsBaseSlots } from "./slots/index.js";
+import { AfGridThemeProvider } from "./theme.js";
+import {
+	type AfExcelExportOptions,
+	AfGridExcelExportMenuItem,
+	type AfGridExcelExportOptions,
+	AfGridToolbar,
+	AfGridToolbarExcelExportButton,
+	GridToolbarAddButton,
+	GridToolbarAddIfAllowedButton,
+	GridToolbarColumnsButton,
+	GridToolbarContainer,
+	GridToolbarFilterButton,
+	GridToolbarMoreOptionsButton,
+	GridToolbarRefreshButton,
+	GridToolbarResetLayoutButton,
+} from "./Toolbar.js";
+import type { AfGridColumn } from "./useAfColumns.js";
+import { type AfGridColDef, useAfColumns } from "./useAfColumns.js";
+import { useAfCurrentIndex } from "./useAfCurrentIndex.js";
+import { useAfData } from "./useAfData.js";
+import { useAfFilterFields } from "./useAfFilterFields.js";
+import { useAfFilter } from "./useAfFilter.js";
+import { type AfGridApi, useAfGridApi } from "./useAfGridApi.js";
+import { useAfKeyBindings } from "./useAfKeyBindings.js";
+import { type AfGridNewItemRowPosition, NEW_ITEM_ROW_ID, isNewItemRow, useAfNewItemRow } from "./useAfNewItemRow.js";
+import { useAfPagination } from "./useAfPagination.js";
+import {
+	isPersistedStateLoaded,
+	type StatePersistenceConfig,
+	settingsLoaded,
+	useAfPersistedState,
+} from "./useAfPersistedState.js";
+import { useAfRowEditModel } from "./useAfRowEditModel.js";
+import { useAfRowGrouping } from "./useAfRowGrouping.js";
+import { useAfServerAggregation } from "./useAfServerAggregation.js";
+import { useAfSortModel } from "./useAfSortModel.js";
+import { getLocalizedString } from "../i18n.js";
+
+export * from "./formatters.js";
+export * from "./GridEditLookup.js";
+// MUI X as a namespace (`DataGrid.DataGridPremium`, `DataGrid.GridColDef`, `DataGrid.useGridApiRef`,
+// ...), for grids that are not bound to a data object - from here rather than the app, so a
+// platform app does not bundle a second MUI X. Same shape as appframe-mui exported it.
+export * as DataGrid from "@mui/x-data-grid-premium";
+export * as MuiDataGrid from "@mui/x-data-grid-premium";
+
+registerLicense();
+
+/**
+ * The grid's criteria live in a `FilterTree` owned by `useAfFilter`, not in
+ * MUI's filter model, so the model is always empty. It is hoisted so the
+ * reference is stable and the grid does not treat it as a change.
+ */
+const EMPTY_FILTER_MODEL: GridFilterModel = { items: [] };
+
+const privSysColumns: AfGridColDef[] = [
+	{ field: "PrimKey", editable: false, hide: true },
+	{ field: "Created", editable: false, hide: true },
+	{ field: "CreatedBy", editable: false, hide: true },
+	{ field: "Updated", editable: false, hide: true },
+	{ field: "UpdatedBy", editable: false, hide: true },
+];
+
+export const systemColumns = {
+	[Symbol.iterator]: () => privSysColumns[Symbol.iterator](),
+	PrimKey: privSysColumns[0],
+	Created: privSysColumns[1],
+	CreatedBy: privSysColumns[2],
+	Updated: privSysColumns[3],
+	UpdatedBy: privSysColumns[4],
+};
+
+export type {
+	AfExcelExportOptions,
+	AfGridApi,
+	AfGridColDef,
+	AfGridColumn,
+	AfGridExcelExportOptions,
+	AfGridNewItemRowPosition,
+};
+export type { AfGridGrouping, AfGridGroupingProps } from "./useAfRowGrouping.js";
+
+export {
+	AF_GRID_LOCALE_TEXT,
+	NEW_ITEM_ROW_ID,
+	isNewItemRow,
+	useAfNewItemRow,
+	AfGridColumnsPanel,
+	AfGridExcelExportMenuItem,
+	AfGridThemeProvider,
+	AfGridToolbar,
+	AfGridToolbarExcelExportButton,
+	GridToolbarAddButton,
+	GridToolbarAddIfAllowedButton,
+	GridToolbarColumnsButton,
+	GridToolbarContainer,
+	GridToolbarFilterButton,
+	GridToolbarMoreOptionsButton,
+	GridToolbarRefreshButton,
+	GridToolbarResetLayoutButton,
+	useAfColumns,
+	useAfCurrentIndex,
+	useAfData,
+	useAfFilter,
+	useAfFilterFields,
+	useAfPagination,
+	useAfPersistedState,
+	useAfRowEditModel,
+	useAfRowGrouping,
+	useAfServerAggregation,
+	useAfSortModel,
+};
+
+/** MUI's own default: the grand total in the footer, group subtotals inline. */
+function getDefaultAggregationPosition(groupNode: GridGroupNode) {
+	return groupNode.depth === -1 ? "footer" : "inline";
+}
+
+export type AfGridProps = {
+	apiRef?: React.RefObject<GridApi>;
+	/**
+	 * If set to true, the grid will automatically load data if the data object has not
+	 * been loaded previously.
+	 */
+	autoLoad?: boolean;
+	/**
+	 * Bind the focused/selected row to the current index in the data object.
+	 * Useful if you want child data to load as the user navigates the grid.
+	 */
+	bindIndex?: boolean;
+	columns: AfGridColumn[];
+	dataObject: DataObject<any>;
+	/**
+	 * The layout version of the grid. Persisted grid state will only be restored
+	 * if the version matches.
+	 */
+	layoutVersion?: string | number;
+	/**
+	 * Field that contains a unique identifier for each row. Defaults to PrimKey.
+	 */
+	idField?: string;
+	/**
+	 * A function that can be used to transform the data object data before it is
+	 * passed to the grid, for example to create summary rows.
+	 */
+	getData?: (data: Readonly<Readonly<any>[]>) => any[];
+	/**
+	 * Override the data object permission, and remove the delete button from the default row actions
+	 */
+	disableDelete?: boolean;
+	/**
+	 * Override the data object permission, and remove the edit button from the default row actions
+	 */
+	disableEdit?: boolean;
+	/**
+	 * Override the data object permission, and remove the Add button from the default toolbar.
+	 */
+	disableInsert?: boolean;
+	/**
+	 * Use to disable server sorting. Required for example when using row grouping.
+	 */
+	disableServerSorting?: boolean;
+	/**
+	 * The view the filter builder saves and loads saved filters for, and converts
+	 * its filter against. Without it the filter builder can still be used, but
+	 * saved filters are unavailable.
+	 */
+	filterViewName?: string;
+	/**
+	 * Where to show the new item row: a non-data row pinned above or below the data
+	 * that reads "Click here to add a new row" until the user starts editing it.
+	 * Editing it moves the data object to the new record at index -1, and committing
+	 * it saves the record. Only shown when the data object allows insert and
+	 * `disableInsert` is not set. `none` turns it off, in which case the Add button
+	 * appends an unsaved row to the data instead. Defaults to `bottom`.
+	 */
+	newItemRow?: AfGridNewItemRowPosition;
+	/**
+	 * A unique ID used to persist the grid state. It is better to use the layoutVersion
+	 * property if you would like to ignore any previously persisted state, as changing
+	 * this property will leave orphan records for the previous id in the Indexed DB
+	 * grid layout store.
+	 */
+	id: string;
+	/**
+	 * Object almost matching the grid state, but with all values as booleans. This
+	 * is used to configure which properties should be persisted.
+	 */
+	persistenceModel?: StatePersistenceConfig;
+	/**
+	 * Ask the server for the grand total instead of adding up the rows the grid is holding.
+	 *
+	 * MUI aggregates over the loaded rows, which on a dynamically loading data object is the
+	 * current page — a sum that looks like a total and is not one. With this on, the grid runs a
+	 * second retrieve under the same filters that returns only the aggregates, so the footer shows
+	 * the total over the whole result. Subtotals on grouped rows stay client side, since a group
+	 * only exists over the rows the grid has.
+	 *
+	 * `sum`, `avg`, `min` and `max` are resolved server side; `size` and any custom aggregation
+	 * function stay on the client. If the view cannot be aggregated the grid falls back to the
+	 * client total rather than failing.
+	 *
+	 * Defaults to true when the data object loads dynamically, since that is exactly the case
+	 * where the client total is wrong.
+	 */
+	serverAggregation?: boolean;
+} & Omit<
+	DataGridProps,
+	| "apiRef"
+	| "columns"
+	| "loading"
+	| "rows"
+	| "filterMode"
+	| "filterModel"
+	| "onFilterModelChange"
+	| "sortingMode"
+	| "sortModel"
+	| "onSortModelChange"
+	| "rowGroupingModel"
+	| "onRowGroupingModelChange"
+	| "aggregationModel"
+	| "onAggregationModelChange"
+	| "editRowsModel"
+	| "editMode"
+	| "onRowEditCommit"
+	| "onEditRowsModelChange"
+	| "pagination"
+	| "paginationMode"
+	| "pageSize"
+	| "rowCount"
+	| "rowsPerPageOptions"
+	| "onPageChange"
+	| "onPageSizeChange"
+>;
+
+// This wrapper component prevents the actual grid from rendering until the persisted state has been loaded.
+// This is to prevent the grid from flickering when the persisted state is restored, plus the grid sometimes
+// resets the column order if not provided in the initial state
+export function AfGrid(props: AfGridProps) {
+	let [loaded, setLoaded] = useState(isPersistedStateLoaded());
+
+	useEffect(() => {
+		settingsLoaded.then(() => setLoaded(true));
+	}, []);
+
+	return (
+		<AfGridThemeProvider>
+			{loaded ? <AfGrid_ {...props} /> : <div className="AfGrid-loading">{getLocalizedString("Loading...")}</div>}
+		</AfGridThemeProvider>
+	);
+}
+
+function AfGrid_(props: AfGridProps) {
+	let {
+		autoLoad = false,
+		apiRef: apiRefProp,
+		bindIndex,
+		columns: columnsProp,
+		disableServerSorting,
+		disableInsert,
+		disableDelete,
+		disableEdit = false,
+		dataObject,
+		filterViewName,
+		layoutVersion = 0,
+		getData,
+		idField = "PrimKey",
+		id,
+		// Follows the data object's `newRecordPosition` when it has one (older data
+		// packages have none and append), so the row sits where the record will land
+		newItemRow: newItemRowPosition = dataObject.options?.newRecordPosition === "start" ? "top" : "bottom",
+		persistenceModel,
+		initialState,
+		pinnedRows,
+		getRowClassName,
+		serverAggregation = dataObject.options?.dynamicLoading === true,
+		...other
+	} = props;
+	let apiRefPriv = useGridApiRef();
+	let apiRef = apiRefProp ?? apiRefPriv;
+	useAfGridApi(props, apiRef);
+	let newItemRow = useAfNewItemRow({
+		apiRef,
+		dataObject,
+		position: newItemRowPosition,
+		disableInsert,
+		pinnedRows,
+		getRowClassName,
+	});
+	let initialState_ = useAfPersistedState({
+		apiRef,
+		columns: columnsProp,
+		id,
+		layoutVersion,
+		persistenceModel,
+		initialState,
+	});
+	// Seeded from the restored layout, so a persisted grouping survives a reload.
+	let grouping = useAfRowGrouping(initialState_);
+	let loading = useLoading(dataObject);
+	let paging = useAfPagination(dataObject);
+	let sortModel = useAfSortModel({
+		dataObject,
+		columns: columnsProp,
+		disableServerSorting,
+		isGrouping: grouping.isGrouping,
+	});
+	let gridFilter = useAfFilter({ autoLoad, dataObject, id });
+	let [snackbar, setSnackbar] = useState<string | null>(null);
+	let [isFilterBuilderOpen, setFilterBuilderOpen] = useState(false);
+	let [isColumnsPanelOpen, setColumnsPanelOpen] = useState(false);
+	let editProps = useAfRowEditModel({ dataObject, disableEdit, idField, apiRef, newItemRow });
+	let data = useAfData(dataObject, { getData });
+	useAfCurrentIndex({
+		apiRef,
+		dataObject,
+		idField,
+		enabled: !!bindIndex,
+		newItemRowId: newItemRow.enabled ? NEW_ITEM_ROW_ID : null,
+	});
+	let columns = useAfColumns({
+		apiRef,
+		dataObject,
+		disableEdit,
+		disableDelete,
+		columnsProp,
+		idField,
+	});
+	let filterFields = useAfFilterFields(dataObject, columnsProp);
+
+	let keyEvents = useAfKeyBindings({ apiRef, dataObject });
+
+	useEffect(() => {
+		if (!snackbar) return;
+
+		let timeout = setTimeout(() => setSnackbar(null), 6000);
+
+		return () => clearTimeout(timeout);
+	}, [snackbar]);
+
+	let serverAggregates = useAfServerAggregation(
+		dataObject,
+		grouping.gridProps.aggregationModel,
+		serverAggregation && !grouping.isGrouping,
+	);
+
+	/*
+	 * The grand total row asks for `groupId === GRID_ROOT_GROUP_ID`; every other call is a group
+	 * subtotal, which only means anything over the rows the grid actually has. So the server value
+	 * is substituted for the root and the built-in function is left to do the rest.
+	 */
+	let aggregationFunctions = useMemo(() => {
+		if (!serverAggregation) return undefined;
+
+		let base = other.aggregationFunctions ?? GRID_AGGREGATION_FUNCTIONS;
+		let wrapped: Record<string, GridAggregationFunction> = {};
+
+		for (let [name, fn] of Object.entries(base) as Array<[string, GridAggregationFunction]>) {
+			wrapped[name] = {
+				...fn,
+				apply: (params, api) => {
+					if (params.groupId === GRID_ROOT_GROUP_ID && params.field in serverAggregates.values) {
+						return serverAggregates.values[params.field];
+					}
+
+					return fn.apply(params, api);
+				},
+			};
+		}
+
+		return wrapped;
+	}, [serverAggregation, other.aggregationFunctions, serverAggregates.values]);
+
+	let gridContext = useMemo<AfGridContextValue>(
+		() => ({
+			id,
+			apiRef,
+			filterFields,
+			...gridFilter,
+			openFilterBuilder: () => setFilterBuilderOpen(true),
+			openColumnsPanel: () => setColumnsPanelOpen(true),
+		}),
+		[id, apiRef, filterFields, gridFilter],
+	);
+
+	return (
+		<DataObjectProvider dataObject={dataObject}>
+			<AfGridContextProvider value={gridContext}>
+				<div className="AfGrid-root" style={newItemRow.rootStyle} {...keyEvents} tabIndex={-1}>
+					<DataGrid
+						apiRef={apiRef}
+						rows={data}
+						columns={columns}
+						loading={loading}
+						getRowId={(row) => row[uid] ?? row[idField]}
+						{...editProps}
+						{...newItemRow.gridProps}
+						/*
+						 * Our own filter tree drives the data object, so MUI never
+						 * sees a filter model. The header filter cells are replaced
+						 * by `renderHeaderFilter` on every column.
+						 */
+						filterMode="server"
+						filterModel={EMPTY_FILTER_MODEL}
+						{...sortModel}
+						headerFilters
+						{...paging}
+						showToolbar
+						{...other}
+						{...grouping.gridProps}
+						/*
+						 * Spread rather than passed, because the grid merges props over its defaults with
+						 * `Object.assign`: an explicit `undefined` here would wipe out the built-in
+						 * aggregation functions rather than fall back to them, and the grid then throws on
+						 * the first render.
+						 */
+						{...(aggregationFunctions ? { aggregationFunctions } : {})}
+						/*
+						 * The server totals arrive after the rows, as new aggregation functions, and the
+						 * grid only re-aggregates on row, column and model changes: without a nudge the
+						 * footer kept the totals of the previous load. Its one effect that re-aggregates
+						 * when the functions change is keyed on this prop and skipped while it is unset,
+						 * so the default position is passed explicitly.
+						 */
+						getAggregationPosition={other.getAggregationPosition ?? getDefaultAggregationPosition}
+						localeText={{ ...other.localeText, ...AF_GRID_LOCALE_TEXT }}
+						slots={{
+							...dsBaseSlots,
+							toolbar: () => <AfGridToolbar disableInsert={disableInsert} />,
+							...other.slots,
+						}}
+						initialState={initialState_}
+						slotProps={{
+							...other.slotProps,
+							headerFilterCell: {
+								...other.slotProps?.headerFilterCell,
+								headerClassName: clsx(other.slotProps?.headerFilterCell?.headerClassName, "AfGrid-headerCell"),
+								showRightBorder: true,
+							},
+						}}
+						onProcessRowUpdateError={(error) => {
+							other.onProcessRowUpdateError?.(error);
+							let message = "message" in (error as any) ? (error as any).message : String(error);
+							setSnackbar(message);
+						}}
+					/>
+				</div>
+				<AfGridError apiRef={apiRef} dataObject={dataObject} />
+				{isColumnsPanelOpen && <AfGridColumnsPanel open onClose={() => setColumnsPanelOpen(false)} />}
+				<FilterBuilder
+					variant="dialog"
+					open={isFilterBuilderOpen}
+					onClose={() => setFilterBuilderOpen(false)}
+					fields={filterFields}
+					viewName={filterViewName}
+					dataObject={dataObject}
+					/*
+					 * The builder edits the same named slot and the same tree as the
+					 * header filters, so a criterion added in one shows up in the
+					 * other. Applying writes the slot directly, which skips the
+					 * header filters' debounce.
+					 */
+					slotName={id}
+					value={gridFilter.filter}
+					onChange={gridFilter.setFilter}
+				/>
+				{!!snackbar && (
+					<div className="AfGrid-snackbar">
+						<Alert data-color="danger" data-size="sm" onClick={() => setSnackbar(null)}>
+							{snackbar}
+						</Alert>
+					</div>
+				)}
+			</AfGridContextProvider>
+		</DataObjectProvider>
+	);
+}