@olenbetong/appframe-ds 1.2.0 → 1.3.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;