@olenbetong/appframe-ds 1.5.0 → 1.6.1

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/useAfColumns.tsx

@@ -28,8 +28,15 @@ import React, { useMemo } from "react";
 import { AfHeaderFilterCell } from "./AfHeaderFilterCell.js";
 import { deleteRow } from "./editing.js";
 import { operators } from "./filter.js";
-import { dateTimeValueFormatter, dateValueFormatter } from "./formatters.js";
+import {
+	dateTimeValueFormatter,
+	dateValueFormatter,
+	localDateTimeValueFormatter,
+	localDateValueFormatter,
+} from "./formatters.js";
 import { isNewItemRow } from "./useAfNewItemRow.js";
+import { parseUtcDate, parseUtcDateTime } from "./utcDate.js";
+import { renderUtcDateEditCell, renderUtcDateTimeEditCell } from "./utcDateEditing.js";
 import { getLocalizedString } from "../i18n.js";
 
 /** `auto-generated-group-footer-`, without spelling it out: every group's total row shares it. */
@@ -48,6 +55,12 @@ export type AfGridColDef = GridColDef & {
 	 * from server-side sort and filter operations.
 	 */
 	calculated?: boolean;
+	/**
+	 * Date and dateTime columns hold wall-clock values by default: stored without a time zone,
+	 * shown and edited as they are. Set this for columns holding real UTC instants (such as
+	 * Created/Updated in newer tables) to show and edit them in the user's local time.
+	 */
+	storedAsUtc?: boolean;
 };
 
 /**
@@ -133,10 +146,19 @@ export function afColumnsToMuiColumn({
 
 			let valueFormatter: (value: any) => string | number | boolean | object | null | undefined = (value) => value;
 
+			// Wall-clock dates are shown and edited in UTC (see utcDate); real UTC instants
+			// use local time and MUI's own editors
+			let storedAsUtc = typeof column !== "string" && !!column.storedAsUtc;
+			let dateEditing: Pick<GridColDef, "renderEditCell" | "valueParser"> = {};
+
 			if (type === "date") {
-				valueFormatter = dateValueFormatter;
+				valueFormatter = storedAsUtc ? localDateValueFormatter : dateValueFormatter;
+				if (!storedAsUtc) dateEditing = { renderEditCell: renderUtcDateEditCell, valueParser: parseUtcDate };
 			} else if (type === "dateTime") {
-				valueFormatter = dateTimeValueFormatter;
+				valueFormatter = storedAsUtc ? localDateTimeValueFormatter : dateTimeValueFormatter;
+				if (!storedAsUtc) {
+					dateEditing = { renderEditCell: renderUtcDateTimeEditCell, valueParser: parseUtcDateTime };
+				}
 			}
 
 			let editable = allowUpdate && !fieldDef?.ignored && !fieldDef?.computed && !fieldDef?.joined;
@@ -155,18 +177,20 @@ export function afColumnsToMuiColumn({
 					type: type as GridColType,
 					headerName: column,
 					valueFormatter,
+					...dateEditing,
 					editable,
 					align,
 					headerAlign: align,
 					width: currentWidth ?? 150,
 				};
 			} else {
-				let { hide, calculated, ...rest } = column;
+				let { hide, calculated, storedAsUtc: _storedAsUtc, ...rest } = column;
 				col = {
 					headerName: fieldDef?.caption ?? fieldName,
 					editable,
 					type: type as GridColType,
 					valueFormatter,
+					...dateEditing,
 					align,
 					headerAlign: align,
 					...rest,

package/src/grid/utcDate.test.ts

@@ -0,0 +1,25 @@
+import { describe, expect, it } from "vitest";
+
+import { fromUtcInputValue, parseUtcDate, parseUtcDateTime, toUtcInputValue } from "./utcDate.js";
+
+describe("UTC date editing in AfGrid", () => {
+	it("stores an entered date as UTC midnight of that date", () => {
+		expect(parseUtcDate("2026-10-10")?.toISOString()).toBe("2026-10-10T00:00:00.000Z");
+	});
+
+	it("stores an entered date and time as that wall-clock time in UTC", () => {
+		expect(parseUtcDateTime("2026-10-10T07:30")?.toISOString()).toBe("2026-10-10T07:30:00.000Z");
+	});
+
+	it("shows a stored date as its UTC date", () => {
+		let stored = new Date("2026-10-10T00:00:00Z");
+		expect(toUtcInputValue(stored, false)).toBe("2026-10-10");
+		expect(toUtcInputValue(stored, true)).toBe("2026-10-10T00:00");
+	});
+
+	it("treats empty and invalid values as no date", () => {
+		expect(fromUtcInputValue("", false)).toBeNull();
+		expect(fromUtcInputValue(null, true)).toBeNull();
+		expect(toUtcInputValue(new Date("invalid"), false)).toBe("");
+	});
+});

package/src/grid/utcDate.ts

@@ -0,0 +1,28 @@
+// Appframe dates are wall-clock values stored as UTC (the grid formats them with
+// timeZone "utc"). MUI's own date editors read and write local time, which shifts a date
+// entered in Norway to 22:00 the day before, so date columns are edited in UTC throughout.
+
+export function toUtcInputValue(value: unknown, withTime: boolean): string {
+	if (!(value instanceof Date) || Number.isNaN(value.getTime())) {
+		return "";
+	}
+
+	return value.toISOString().slice(0, withTime ? 16 : 10);
+}
+
+export function fromUtcInputValue(value: unknown, withTime: boolean): Date | null {
+	if (typeof value !== "string" || !value) {
+		return null;
+	}
+
+	let date = new Date(withTime ? `${value.slice(0, 16)}:00Z` : `${value.slice(0, 10)}T00:00:00Z`);
+	return Number.isNaN(date.getTime()) ? null : date;
+}
+
+export function parseUtcDate(value: unknown) {
+	return fromUtcInputValue(value, false);
+}
+
+export function parseUtcDateTime(value: unknown) {
+	return fromUtcInputValue(value, true);
+}

package/src/grid/utcDateEditing.tsx

@@ -0,0 +1,11 @@
+import { GridEditInputCell, type GridRenderEditCellParams } from "@mui/x-data-grid-premium";
+
+import { toUtcInputValue } from "./utcDate.js";
+
+export function renderUtcDateEditCell(params: GridRenderEditCellParams) {
+	return <GridEditInputCell {...params} type="date" value={toUtcInputValue(params.value, false)} />;
+}
+
+export function renderUtcDateTimeEditCell(params: GridRenderEditCellParams) {
+	return <GridEditInputCell {...params} type="datetime-local" value={toUtcInputValue(params.value, true)} />;
+}