@olenbetong/appframe-ds 1.6.0 → 1.7.0

package/src/filter/useDistinctValues.ts

@@ -1,230 +1,230 @@
-import type { FieldMetadata, FilterExpression, FilterTree } from "@olenbetong/appframe-core";
-import { getValueType } from "@olenbetong/appframe-core";
-import type { DataObject, Filter } from "@olenbetong/appframe-data";
-import { useEffect, useMemo, useState } from "react";
-
-import { getFieldExpressions } from "./fieldFilter.js";
-
-export type DistinctValue = {
-	/** The raw value, as sent back in an `inlist` filter. */
-	value: string;
-	/** How many rows have this value, or null when counts are unavailable. */
-	count: number | null;
-};
-
-export type UseDistinctValuesResult = {
-	values: DistinctValue[];
-	loading: boolean;
-	error: string | null;
-	/** True when the list was truncated at `maxRecords`. */
-	truncated: boolean;
-};
-
-/** How many distinct values to load. The list is a picker, not a report. */
-const MAX_DISTINCT_VALUES = 200;
-
-/**
- * Builds the retrieve payload for the distinct value list of a field.
- *
- * `groupBy` plus a `COUNT` aggregate gives values and counts in one round trip.
- * The counted field must be a different field than the grouped one — asking for
- * `COUNT` of the grouped field collapses into a single column server side.
- *
- * The list respects every other active filter but ignores the field's own
- * criteria, so unchecking a value does not make the remaining values disappear.
- */
-export function buildDistinctParameters({
-	field,
-	countField,
-	filter,
-	search,
-	withCounts,
-}: {
-	field: FieldMetadata;
-	countField: string | null;
-	filter: FilterTree | null;
-	search?: string;
-	withCounts: boolean;
-}) {
-	let filterObject = withoutField(filter, field.name);
-
-	if (search) {
-		let searchExpression: FilterExpression = {
-			type: "expression",
-			column: field.name,
-			operator: "contains",
-			value: search,
-			valueType: getValueType(field, "contains"),
-		};
-
-		filterObject = filterObject
-			? { type: "group", mode: "and", items: [filterObject, searchExpression] }
-			: { type: "group", mode: "and", items: [searchExpression] };
-	}
-
-	let fields =
-		withCounts && countField
-			? [{ name: field.name }, { name: countField, aggregate: "COUNT" }]
-			: [{ name: field.name }];
-
-	return {
-		fields,
-		...(withCounts && countField ? { groupBy: [field.name] } : { distinctRows: true }),
-		filterObject,
-		maxRecords: MAX_DISTINCT_VALUES,
-		sortOrder: [{ [field.name]: "asc" }],
-	};
-}
-
-/**
- * Returns a copy of the filter with the field's own top level criteria removed,
- * and null when nothing is left.
- */
-function withoutField(filter: FilterTree | null, field: string): Filter {
-	if (!filter) return null;
-
-	let own = new Set<unknown>(getFieldExpressions(filter, field));
-	let items = filter.items.filter((item) => !own.has(item));
-
-	if (items.length === 0) return null;
-
-	return { type: "group", mode: filter.mode, items };
-}
-
-/** Whether a distinct value list makes sense for this field's type. */
-export function supportsDistinctValues(field: FieldMetadata | undefined): boolean {
-	return field?.type === "string" || field?.type === "number" || field?.type === "uniqueidentifier";
-}
-
-/**
- * Loads the distinct values of a field, with a row count per value.
- *
- * The query goes straight to the data object's 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 field The field to list values for
- * @param options Current filter, search text, and whether to load at all
- */
-export function useDistinctValues(
-	dataObject: DataObject<any>,
-	field: FieldMetadata | undefined,
-	{ filter, search, enabled = true }: { filter: FilterTree | null; search?: string; enabled?: boolean },
-): UseDistinctValuesResult {
-	let [result, setResult] = useState<UseDistinctValuesResult>({
-		values: [],
-		loading: false,
-		error: null,
-		truncated: false,
-	});
-
-	// The count column has to be a field other than the grouped one.
-	let countField = useMemo(() => {
-		if (!field) return null;
-
-		let lowerField = field.name.toLowerCase();
-		let names = dataObject
-			.getFields()
-			.map((definition) => definition.name)
-			.filter((name) => !!name && name.toLowerCase() !== lowerField);
-
-		return names.find((name) => name.toLowerCase() === "primkey") ?? names[0] ?? null;
-	}, [dataObject, field]);
-
-	// The filter is only used to scope the list, so re-running on every keystroke
-	// in an unrelated criterion is avoided by keying on its serialized form.
-	let filterKey = useMemo(() => JSON.stringify(filter ?? null), [filter]);
-
-	useEffect(() => {
-		if (!enabled || !field || !supportsDistinctValues(field)) {
-			return;
-		}
-
-		let controller = new AbortController();
-		let cancelled = false;
-
-		setResult((current) => ({ ...current, loading: true, error: null }));
-
-		async function load() {
-			if (!field) return;
-
-			let parsedFilter: FilterTree | null = JSON.parse(filterKey);
-
-			async function run(withCounts: boolean) {
-				let parameters = buildDistinctParameters({
-					field: field as FieldMetadata,
-					countField,
-					filter: parsedFilter,
-					search,
-					withCounts,
-				});
-
-				return (await dataObject.dataHandler.retrieve(parameters as any, {
-					signal: controller.signal,
-				})) as any[];
-			}
-
-			try {
-				let withCounts = !!countField;
-				let rows: any[];
-
-				try {
-					rows = await run(withCounts);
-				} catch (cause) {
-					if (controller.signal.aborted || !withCounts) throw cause;
-
-					// Counts are best effort: some views cannot be grouped, so fall
-					// back to a plain distinct list rather than showing an error.
-					withCounts = false;
-					rows = await run(false);
-				}
-
-				if (cancelled) return;
-
-				let values = rows
-					.map((row) => toDistinctValue(row, field as FieldMetadata, countField, withCounts))
-					.filter((value): value is DistinctValue => value !== null);
-
-				setResult({
-					values,
-					loading: false,
-					error: null,
-					truncated: values.length >= MAX_DISTINCT_VALUES,
-				});
-			} catch (cause) {
-				if (cancelled || controller.signal.aborted) return;
-
-				setResult({
-					values: [],
-					loading: false,
-					error: String((cause as Error)?.message ?? cause),
-					truncated: false,
-				});
-			}
-		}
-
-		void load();
-
-		return () => {
-			cancelled = true;
-			controller.abort();
-		};
-	}, [dataObject, field, countField, filterKey, search, enabled]);
-
-	return result;
-}
-
-function toDistinctValue(
-	row: Record<string, unknown>,
-	field: FieldMetadata,
-	countField: string | null,
-	withCounts: boolean,
-): DistinctValue | null {
-	let raw = row[field.name];
-
-	if (raw === null || raw === undefined || raw === "") return null;
-
-	let count = withCounts && countField ? Number(row[countField]) : null;
-
-	return { value: String(raw), count: Number.isFinite(count as number) ? (count as number) : null };
-}
+import type { FieldMetadata, FilterExpression, FilterTree } from "@olenbetong/appframe-core";
+import { getValueType } from "@olenbetong/appframe-core";
+import type { DataObject, Filter } from "@olenbetong/appframe-data";
+import { useEffect, useMemo, useState } from "react";
+
+import { getFieldExpressions } from "./fieldFilter.js";
+
+export type DistinctValue = {
+	/** The raw value, as sent back in an `inlist` filter. */
+	value: string;
+	/** How many rows have this value, or null when counts are unavailable. */
+	count: number | null;
+};
+
+export type UseDistinctValuesResult = {
+	values: DistinctValue[];
+	loading: boolean;
+	error: string | null;
+	/** True when the list was truncated at `maxRecords`. */
+	truncated: boolean;
+};
+
+/** How many distinct values to load. The list is a picker, not a report. */
+const MAX_DISTINCT_VALUES = 200;
+
+/**
+ * Builds the retrieve payload for the distinct value list of a field.
+ *
+ * `groupBy` plus a `COUNT` aggregate gives values and counts in one round trip.
+ * The counted field must be a different field than the grouped one — asking for
+ * `COUNT` of the grouped field collapses into a single column server side.
+ *
+ * The list respects every other active filter but ignores the field's own
+ * criteria, so unchecking a value does not make the remaining values disappear.
+ */
+export function buildDistinctParameters({
+	field,
+	countField,
+	filter,
+	search,
+	withCounts,
+}: {
+	field: FieldMetadata;
+	countField: string | null;
+	filter: FilterTree | null;
+	search?: string;
+	withCounts: boolean;
+}) {
+	let filterObject = withoutField(filter, field.name);
+
+	if (search) {
+		let searchExpression: FilterExpression = {
+			type: "expression",
+			column: field.name,
+			operator: "contains",
+			value: search,
+			valueType: getValueType(field, "contains"),
+		};
+
+		filterObject = filterObject
+			? { type: "group", mode: "and", items: [filterObject, searchExpression] }
+			: { type: "group", mode: "and", items: [searchExpression] };
+	}
+
+	let fields =
+		withCounts && countField
+			? [{ name: field.name }, { name: countField, aggregate: "COUNT" }]
+			: [{ name: field.name }];
+
+	return {
+		fields,
+		...(withCounts && countField ? { groupBy: [field.name] } : { distinctRows: true }),
+		filterObject,
+		maxRecords: MAX_DISTINCT_VALUES,
+		sortOrder: [{ [field.name]: "asc" }],
+	};
+}
+
+/**
+ * Returns a copy of the filter with the field's own top level criteria removed,
+ * and null when nothing is left.
+ */
+function withoutField(filter: FilterTree | null, field: string): Filter {
+	if (!filter) return null;
+
+	let own = new Set<unknown>(getFieldExpressions(filter, field));
+	let items = filter.items.filter((item) => !own.has(item));
+
+	if (items.length === 0) return null;
+
+	return { type: "group", mode: filter.mode, items };
+}
+
+/** Whether a distinct value list makes sense for this field's type. */
+export function supportsDistinctValues(field: FieldMetadata | undefined): boolean {
+	return field?.type === "string" || field?.type === "number" || field?.type === "uniqueidentifier";
+}
+
+/**
+ * Loads the distinct values of a field, with a row count per value.
+ *
+ * The query goes straight to the data object's 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 field The field to list values for
+ * @param options Current filter, search text, and whether to load at all
+ */
+export function useDistinctValues(
+	dataObject: DataObject<any>,
+	field: FieldMetadata | undefined,
+	{ filter, search, enabled = true }: { filter: FilterTree | null; search?: string; enabled?: boolean },
+): UseDistinctValuesResult {
+	let [result, setResult] = useState<UseDistinctValuesResult>({
+		values: [],
+		loading: false,
+		error: null,
+		truncated: false,
+	});
+
+	// The count column has to be a field other than the grouped one.
+	let countField = useMemo(() => {
+		if (!field) return null;
+
+		let lowerField = field.name.toLowerCase();
+		let names = dataObject
+			.getFields()
+			.map((definition) => definition.name)
+			.filter((name) => !!name && name.toLowerCase() !== lowerField);
+
+		return names.find((name) => name.toLowerCase() === "primkey") ?? names[0] ?? null;
+	}, [dataObject, field]);
+
+	// The filter is only used to scope the list, so re-running on every keystroke
+	// in an unrelated criterion is avoided by keying on its serialized form.
+	let filterKey = useMemo(() => JSON.stringify(filter ?? null), [filter]);
+
+	useEffect(() => {
+		if (!enabled || !field || !supportsDistinctValues(field)) {
+			return;
+		}
+
+		let controller = new AbortController();
+		let cancelled = false;
+
+		setResult((current) => ({ ...current, loading: true, error: null }));
+
+		async function load() {
+			if (!field) return;
+
+			let parsedFilter: FilterTree | null = JSON.parse(filterKey);
+
+			async function run(withCounts: boolean) {
+				let parameters = buildDistinctParameters({
+					field: field as FieldMetadata,
+					countField,
+					filter: parsedFilter,
+					search,
+					withCounts,
+				});
+
+				return (await dataObject.dataHandler.retrieve(parameters as any, {
+					signal: controller.signal,
+				})) as any[];
+			}
+
+			try {
+				let withCounts = !!countField;
+				let rows: any[];
+
+				try {
+					rows = await run(withCounts);
+				} catch (cause) {
+					if (controller.signal.aborted || !withCounts) throw cause;
+
+					// Counts are best effort: some views cannot be grouped, so fall
+					// back to a plain distinct list rather than showing an error.
+					withCounts = false;
+					rows = await run(false);
+				}
+
+				if (cancelled) return;
+
+				let values = rows
+					.map((row) => toDistinctValue(row, field as FieldMetadata, countField, withCounts))
+					.filter((value): value is DistinctValue => value !== null);
+
+				setResult({
+					values,
+					loading: false,
+					error: null,
+					truncated: values.length >= MAX_DISTINCT_VALUES,
+				});
+			} catch (cause) {
+				if (cancelled || controller.signal.aborted) return;
+
+				setResult({
+					values: [],
+					loading: false,
+					error: String((cause as Error)?.message ?? cause),
+					truncated: false,
+				});
+			}
+		}
+
+		void load();
+
+		return () => {
+			cancelled = true;
+			controller.abort();
+		};
+	}, [dataObject, field, countField, filterKey, search, enabled]);
+
+	return result;
+}
+
+function toDistinctValue(
+	row: Record<string, unknown>,
+	field: FieldMetadata,
+	countField: string | null,
+	withCounts: boolean,
+): DistinctValue | null {
+	let raw = row[field.name];
+
+	if (raw === null || raw === undefined || raw === "") return null;
+
+	let count = withCounts && countField ? Number(row[countField]) : null;
+
+	return { value: String(raw), count: Number.isFinite(count as number) ? (count as number) : null };
+}

package/src/global.d.ts

@@ -1,11 +1,11 @@
-/// <reference path="@olenbetong/appframe-core" />
-/// <reference path="@olenbetong/appframe-data" />
-
-declare module "*.css" {}
-
-/**
- * The MUI X license key, replaced at build time by the `appframe()` Vite plugin.
- * Declared as possibly undefined, because consumers are free to bundle this
- * package without the define.
- */
-declare const __MUI_X_LICENSE_KEY__: string | undefined;
+/// <reference path="@olenbetong/appframe-core" />
+/// <reference path="@olenbetong/appframe-data" />
+
+declare module "*.css" {}
+
+/**
+ * The MUI X license key, replaced at build time by the `appframe()` Vite plugin.
+ * Declared as possibly undefined, because consumers are free to bundle this
+ * package without the define.
+ */
+declare const __MUI_X_LICENSE_KEY__: string | undefined;

package/src/grid/formatters.ts

@@ -46,3 +46,26 @@ export function dateTimeValueFormatter(value: any) {
 
 	return value;
 }
+
+export const localDateFormatter = new Intl.DateTimeFormat(culture, {
+	year: "numeric",
+	month: "2-digit",
+	day: "2-digit",
+});
+
+export const localDateTimeFormatter = new Intl.DateTimeFormat(culture, {
+	year: "numeric",
+	month: "2-digit",
+	day: "2-digit",
+	hour: "2-digit",
+	minute: "2-digit",
+	second: "2-digit",
+});
+
+export function localDateValueFormatter(value: any) {
+	return value && value instanceof Date ? localDateFormatter.format(value) : value;
+}
+
+export function localDateTimeValueFormatter(value: any) {
+	return value && value instanceof Date ? localDateTimeFormatter.format(value) : value;
+}

package/src/grid/index.css

@@ -140,8 +140,8 @@
 
 /* The funnel is highlighted while the column has criteria, as in the toolbar */
 .AfGrid-headerFilterButton[data-active] {
-	--dsc-button-color: var(--ds-color-accent-base-default);
-	--dsc-button-color--hover: var(--ds-color-accent-base-hover);
+	--dsc-button-color: var(--ds-color-brand-base-default);
+	--dsc-button-color--hover: var(--ds-color-brand-base-hover);
 }
 
 .AfGrid-headerFilterEmpty {
@@ -243,3 +243,9 @@
 .AfGrid-root .MuiDataGrid-cell a.ds-button {
 	text-decoration: none;
 }
+
+/* Group rows (row grouping): tinted and bold, so the subtotals read apart from the data rows */
+.AfGrid-root .MuiDataGrid-row.AfGrid-groupRow {
+	background-color: var(--ds-color-neutral-background-tinted);
+	font-weight: 600;
+}

package/src/grid/index.tsx

@@ -9,6 +9,9 @@ import {
 	type GridAggregationFunction,
 	type GridApi,
 	type GridFilterModel,
+	type GridColSpanFn,
+	type GridGroupingColDefOverride,
+	type GridGroupingColDefOverrideParams,
 	type GridGroupNode,
 	type GridRowParams,
 	useGridApiRef,
@@ -17,9 +20,10 @@ 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 { useCallback, useEffect, useMemo, useState } from "react";
 import { FilterBuilder } from "../filter/index.js";
 import { AfGridColumnsPanel } from "./AfGridColumnsPanel.js";
+import { AfHeaderFilterCell } from "./AfHeaderFilterCell.js";
 import { type AfGridContextValue, AfGridContextProvider } from "./AfGridContext.js";
 import { AfGridError } from "./AfGridError.js";
 import { registerLicense } from "./license.js";
@@ -141,6 +145,58 @@ export {
 };
 
 /** MUI's own default: the grand total in the footer, group subtotals inline. */
+/**
+ * On a group row the grouping cell spans the following visible columns up to the first one that
+ * shows an aggregate, since those cells are empty there. Data rows span nothing.
+ */
+const spanGroupLabel: GridColSpanFn = (_value, row, column, apiRef) => {
+	// The callback is typed with the community API; this grid is premium, which has aggregation.
+	let api = apiRef.current as GridApi | null;
+	if (!api || api.getRowNode(api.getRowId(row))?.type !== "group") return 1;
+
+	let aggregated = api.state.aggregation?.model ?? {};
+	let columns = api.getVisibleColumns();
+	let index = columns.findIndex((c) => c.field === column.field);
+	let span = 1;
+
+	while (index + span < columns.length && !aggregated[columns[index + span].field]) {
+		span++;
+	}
+
+	return span;
+};
+
+/**
+ * MUI generates the grouping column itself, so it never passes through `useAfColumns` and got
+ * MUI's own header filter. It gets ours instead, filtering on the grouped field when the rows are
+ * grouped by a single field, and an empty cell like any unfilterable column otherwise.
+ *
+ * On group rows the column spans the empty cells after it, so the group label is readable in a
+ * column no wider than its expand toggle. A grid can still set its own `colSpan`.
+ */
+function getGroupingColDef(
+	params: GridGroupingColDefOverrideParams,
+	groupingColDef: DataGridProps["groupingColDef"],
+	dataObject: DataObject<any>,
+): GridGroupingColDefOverride {
+	let base = typeof groupingColDef === "function" ? groupingColDef(params) : groupingColDef;
+	let filterColumn = params.fields.length === 1 ? params.fields[0] : undefined;
+
+	return {
+		...base,
+		colSpan: base?.colSpan ?? spanGroupLabel,
+		renderHeaderFilter:
+			base?.renderHeaderFilter ??
+			((props) => (
+				<AfHeaderFilterCell
+					{...props}
+					colDef={{ ...props.colDef, filterColumn } as AfGridColDef}
+					dataObject={dataObject}
+				/>
+			)),
+	};
+}
+
 function getDefaultAggregationPosition(groupNode: GridGroupNode) {
 	return groupNode.depth === -1 ? "footer" : "inline";
 }
@@ -241,6 +297,12 @@ export type AfGridProps = {
 	 * where the client total is wrong.
 	 */
 	serverAggregation?: boolean;
+	/**
+	 * Leave out MUI's loading overlay while the data object loads. For a grid that refreshes on a
+	 * timer: the overlay covers the rows and blocks selecting text in them. The toolbar's refresh
+	 * button still shows that the grid is loading.
+	 */
+	disableLoadingOverlay?: boolean;
 } & Omit<
 	DataGridProps,
 	| "apiRef"
@@ -312,18 +374,25 @@ function AfGrid_(props: AfGridProps) {
 		pinnedRows,
 		getRowClassName,
 		serverAggregation = dataObject.options?.dynamicLoading === true,
+		disableLoadingOverlay = false,
 		...other
 	} = props;
 	let apiRefPriv = useGridApiRef();
 	let apiRef = apiRefProp ?? apiRefPriv;
 	useAfGridApi(props, apiRef);
+	// Group rows (row grouping) are marked so AfGrid's stylesheet can set them apart from the data rows.
+	let getRowClassNameWithGroups = useCallback<NonNullable<DataGridProps["getRowClassName"]>>(
+		(params) =>
+			clsx(getRowClassName?.(params), apiRef.current?.getRowNode(params.id)?.type === "group" && "AfGrid-groupRow"),
+		[getRowClassName, apiRef],
+	);
 	let newItemRow = useAfNewItemRow({
 		apiRef,
 		dataObject,
 		position: newItemRowPosition,
 		disableInsert,
 		pinnedRows,
-		getRowClassName,
+		getRowClassName: getRowClassNameWithGroups,
 	});
 	let initialState_ = useAfPersistedState({
 		apiRef,
@@ -431,7 +500,7 @@ function AfGrid_(props: AfGridProps) {
 						apiRef={apiRef}
 						rows={data}
 						columns={columns}
-						loading={loading}
+						loading={!disableLoadingOverlay && loading}
 						getRowId={(row) => row[uid] ?? row[idField]}
 						{...editProps}
 						{...newItemRow.gridProps}
@@ -463,6 +532,7 @@ function AfGrid_(props: AfGridProps) {
 						 * so the default position is passed explicitly.
 						 */
 						getAggregationPosition={other.getAggregationPosition ?? getDefaultAggregationPosition}
+						groupingColDef={(params) => getGroupingColDef(params, other.groupingColDef, dataObject)}
 						localeText={{ ...other.localeText, ...AF_GRID_LOCALE_TEXT }}
 						slots={{
 							...dsBaseSlots,