@olenbetong/appframe-ds 1.2.0 → 1.3.0

package/src/grid/useAfServerAggregation.ts

@@ -1,145 +1,158 @@
-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;
-}
+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 });
+		/*
+		 * A dynamically loading data object reports every load page by page and never fires
+		 * onDataLoaded, so listening for that alone left the totals on whatever the first load
+		 * saw. The first page of a load is the one that follows a new filter; later pages only
+		 * scroll further into the same result, which the totals already cover.
+		 */
+		dataObject.attachEvent(
+			"onPartialDataLoaded",
+			(event) => {
+				if (event.detail.skip === 0) 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,84 +1,84 @@
-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";
-import type { AfGridColDef, AfGridColumn } from "./useAfColumns";
-
-const convertMap: Record<SortOrder, "asc" | "desc"> = {
-	asc: "asc",
-	desc: "desc",
-	ascnullslast: "asc",
-	descnullsfirst: "desc",
-};
-
-export function afSortOrderToMuiSortModel(
-	dataObject: DataObject<any>,
-	sortOrder?: RetrieveParameters<any>["sortOrder"],
-): GridSortModel {
-	return (
-		sortOrder?.flatMap((x) => {
-			let itemFields = Object.keys(x);
-			let items: GridSortModel = itemFields
-				.filter((field) => dataObject.getFields(field))
-				.map((field) => ({ field, sort: convertMap[x[field]] }));
-
-			return items;
-		}) ?? []
-	);
-}
-
-/**
- * Converts between DataObject sort parameter and DataGrid sort model.
- * Updates the data when the sort model changes.
- *
- * @param dataObject Data object grid is used with
- */
-export function useAfSortModel({
-	dataObject,
-	columns,
-	disableServerSorting = false,
-	isGrouping = false,
-}: {
-	dataObject: DataObject<any>;
-	columns: AfGridColumn[];
-	disableServerSorting?: boolean;
-	/**
-	 * 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);
-		sortModel = sortModel.filter((s) => columns.find((c) => (typeof c === "string" ? c : c.field) === s.field));
-
-		return sortModel;
-	}, [dataObject, sortOrder, columns]);
-
-	let onSortModelChange = useCallback(
-		(sortModel: GridSortModel, details: GridCallbackDetails) => {
-			let sortOrder: Record<string, SortOrder>[] = [];
-			for (let item of sortModel) {
-				let colDef = columns.find((c) => typeof c !== "string" && c.field === item.field) as AfGridColDef | undefined;
-				if (item.sort) {
-					sortOrder.push({
-						[colDef?.sortColumn ?? item.field]: item.sort as SortOrder,
-					});
-				}
-			}
-
-			dataObject.setParameter("sortOrder", sortOrder);
-			dataObject.refreshDataSource();
-		},
-		[dataObject, columns],
-	);
-
-	if (disableServerSorting) {
-		return {};
-	}
-
-	return { sortingMode: isGrouping ? "client" : "server", sortModel, onSortModelChange };
-}
+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";
+import type { AfGridColDef, AfGridColumn } from "./useAfColumns";
+
+const convertMap: Record<SortOrder, "asc" | "desc"> = {
+	asc: "asc",
+	desc: "desc",
+	ascnullslast: "asc",
+	descnullsfirst: "desc",
+};
+
+export function afSortOrderToMuiSortModel(
+	dataObject: DataObject<any>,
+	sortOrder?: RetrieveParameters<any>["sortOrder"],
+): GridSortModel {
+	return (
+		sortOrder?.flatMap((x) => {
+			let itemFields = Object.keys(x);
+			let items: GridSortModel = itemFields
+				.filter((field) => dataObject.getFields(field))
+				.map((field) => ({ field, sort: convertMap[x[field]] }));
+
+			return items;
+		}) ?? []
+	);
+}
+
+/**
+ * Converts between DataObject sort parameter and DataGrid sort model.
+ * Updates the data when the sort model changes.
+ *
+ * @param dataObject Data object grid is used with
+ */
+export function useAfSortModel({
+	dataObject,
+	columns,
+	disableServerSorting = false,
+	isGrouping = false,
+}: {
+	dataObject: DataObject<any>;
+	columns: AfGridColumn[];
+	disableServerSorting?: boolean;
+	/**
+	 * 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);
+		sortModel = sortModel.filter((s) => columns.find((c) => (typeof c === "string" ? c : c.field) === s.field));
+
+		return sortModel;
+	}, [dataObject, sortOrder, columns]);
+
+	let onSortModelChange = useCallback(
+		(sortModel: GridSortModel, details: GridCallbackDetails) => {
+			let sortOrder: Record<string, SortOrder>[] = [];
+			for (let item of sortModel) {
+				let colDef = columns.find((c) => typeof c !== "string" && c.field === item.field) as AfGridColDef | undefined;
+				if (item.sort) {
+					sortOrder.push({
+						[colDef?.sortColumn ?? item.field]: item.sort as SortOrder,
+					});
+				}
+			}
+
+			dataObject.setParameter("sortOrder", sortOrder);
+			dataObject.refreshDataSource();
+		},
+		[dataObject, columns],
+	);
+
+	if (disableServerSorting) {
+		return {};
+	}
+
+	return { sortingMode: isGrouping ? "client" : "server", sortModel, onSortModelChange };
+}

package/src/i18n.ts

@@ -1,13 +1,13 @@
-/*
- * The package's strings live in their own globalization project, `appframe-ds`, so one
- * translation covers every app and the package can word a term its own way. The templates
- * render the dictionary as af.i18n["appframe-ds"]; on a page that does not (a legacy
- * template) the localizer falls back to the article's strings, exactly as before. See
- * `createLocalizer` in @olenbetong/appframe-core.
- */
-
-import { createLocalizer } from "@olenbetong/appframe-core";
-
-export const PROJECT = "appframe-ds";
-
-export const { getLocalizedString, localize } = createLocalizer(PROJECT);
+/*
+ * The package's strings live in their own globalization project, `appframe-ds`, so one
+ * translation covers every app and the package can word a term its own way. The templates
+ * render the dictionary as af.i18n["appframe-ds"]; on a page that does not (a legacy
+ * template) the localizer falls back to the article's strings, exactly as before. See
+ * `createLocalizer` in @olenbetong/appframe-core.
+ */
+
+import { createLocalizer } from "@olenbetong/appframe-core";
+
+export const PROJECT = "appframe-ds";
+
+export const { getLocalizedString, localize } = createLocalizer(PROJECT);

package/src/index.ts

@@ -1,14 +1,14 @@
-export * from "./AfLookup/index.js";
-export * from "./autocomplete/index.js";
-export * from "./binding/index.js";
-export * from "./container/index.js";
-export * from "./cutoff/index.js";
-export * from "./filter/index.js";
-export * from "./input/index.js";
-export * from "./layout/index.js";
-export * from "./link/index.js";
-export * from "./list/index.js";
-export * from "./page/index.js";
-export * from "./paper/index.js";
-export * from "./progress/index.js";
-export * from "./sortable/index.js";
+export * from "./AfLookup/index.js";
+export * from "./autocomplete/index.js";
+export * from "./binding/index.js";
+export * from "./container/index.js";
+export * from "./cutoff/index.js";
+export * from "./filter/index.js";
+export * from "./input/index.js";
+export * from "./layout/index.js";
+export * from "./link/index.js";
+export * from "./list/index.js";
+export * from "./page/index.js";
+export * from "./paper/index.js";
+export * from "./progress/index.js";
+export * from "./sortable/index.js";