@olenbetong/appframe-ds 0.7.0 → 0.9.0

package/src/filter/fieldFilter.ts

@@ -0,0 +1,139 @@
+import {
+	type FieldMetadata,
+	type FilterExpression,
+	type FilterOperator,
+	type FilterTree,
+	getLocalizedString,
+	getOperatorArity,
+	getOperatorLabel,
+	getValueType,
+	isExpression,
+	normalizeOperator,
+} from "@olenbetong/appframe-core";
+
+/**
+ * The criteria a header filter owns for a field: the expressions directly in
+ * the filter's root group that filter on that field.
+ *
+ * Expressions nested inside sub-groups are deliberately left out. A header
+ * filter is a flat list of criteria combined with the root group's operator, so
+ * it cannot represent a nested group without silently changing its meaning.
+ * Those stay editable in the filter builder only.
+ */
+export function getFieldExpressions(filter: FilterTree | null | undefined, field: string): FilterExpression[] {
+	if (!filter) return [];
+
+	let lowerField = field.toLowerCase();
+
+	return filter.items.filter(
+		(item): item is FilterExpression => isExpression(item) && item.column?.toLowerCase() === lowerField,
+	);
+}
+
+/**
+ * Returns a copy of the tree where the field's top-level expressions have been
+ * replaced by `expressions`, keeping the position of the first one so criteria
+ * do not jump around while they are edited.
+ */
+export function setFieldExpressions(filter: FilterTree, field: string, expressions: FilterExpression[]): FilterTree {
+	let lowerField = field.toLowerCase();
+	let isOwn = (item: FilterTree["items"][number]) => isExpression(item) && item.column?.toLowerCase() === lowerField;
+	let firstIndex = filter.items.findIndex(isOwn);
+	let others = filter.items.filter((item) => !isOwn(item));
+
+	if (expressions.length === 0) {
+		return { ...filter, items: others };
+	}
+
+	let insertAt = firstIndex === -1 ? others.length : Math.min(firstIndex, others.length);
+	let items = [...others.slice(0, insertAt), ...expressions, ...others.slice(insertAt)];
+
+	return { ...filter, items };
+}
+
+/**
+ * True when the criteria can be edited straight from the header input: exactly
+ * one criterion, taking exactly one literal value.
+ */
+export function isSimpleFieldFilter(expressions: FilterExpression[]): boolean {
+	if (expressions.length !== 1) return false;
+
+	let expression = expressions[0] as FilterExpression;
+
+	return getOperatorArity(normalizeOperator(expression.operator)) === "single" && expression.valueType !== "special";
+}
+
+function toDisplayValue(value: FilterExpression["value"]): string {
+	if (value === null || value === undefined) return "";
+	if (value instanceof Date) return value.toLocaleDateString();
+	if (Array.isArray(value)) return value.join(", ");
+
+	return String(value);
+}
+
+/** The value shown in the header input when the criteria are directly editable. */
+export function getSimpleValue(expressions: FilterExpression[]): string {
+	return isSimpleFieldFilter(expressions) ? toDisplayValue((expressions[0] as FilterExpression).value) : "";
+}
+
+/**
+ * Short read-only description of a field's criteria, shown in the header input
+ * when they are too complex to edit inline — e.g. `In list (3)`.
+ */
+export function summarizeFieldFilter(expressions: FilterExpression[], field?: FieldMetadata): string {
+	if (expressions.length === 0) return "";
+
+	if (expressions.length > 1) {
+		return getLocalizedString("{0} criteria").replace("{0}", String(expressions.length));
+	}
+
+	let expression = expressions[0] as FilterExpression;
+	let operator = normalizeOperator(expression.operator);
+	let label = getOperatorLabel(operator, field?.type);
+	let arity = getOperatorArity(operator);
+
+	if (arity === "none") return label;
+
+	if (arity === "list") {
+		let count = Array.isArray(expression.value) ? expression.value.length : 0;
+
+		return `${label} (${count})`;
+	}
+
+	return `${label} ${toDisplayValue(expression.value)}`.trim();
+}
+
+/**
+ * The values of the field's `inlist` criterion, which is what the distinct
+ * value checkbox list edits. Everything else in the panel is a normal
+ * criterion row.
+ */
+export function getInListValues(expressions: FilterExpression[]): string[] {
+	let inList = expressions.find((expression) => normalizeOperator(expression.operator) === "inlist");
+
+	return Array.isArray(inList?.value) ? inList.value.map(String) : [];
+}
+
+/**
+ * Replaces the field's `inlist` criterion with one holding `values`, or removes
+ * it when the selection is empty.
+ */
+export function setInListValues(
+	expressions: FilterExpression[],
+	values: string[],
+	field: FieldMetadata,
+): FilterExpression[] {
+	let others = expressions.filter((expression) => normalizeOperator(expression.operator) !== "inlist");
+
+	if (values.length === 0) return others;
+
+	let inList: FilterExpression = {
+		type: "expression",
+		column: field.name,
+		operator: "inlist" satisfies FilterOperator,
+		value: values,
+		valueType: getValueType(field, "inlist"),
+	};
+
+	return [...others, inList];
+}

package/src/filter/index.ts

@@ -0,0 +1,27 @@
+export { ChipListInput, type ChipListInputProps } from "./ChipListInput.js";
+export {
+	getFieldExpressions,
+	getInListValues,
+	getSimpleValue,
+	isSimpleFieldFilter,
+	setFieldExpressions,
+	setInListValues,
+	summarizeFieldFilter,
+} from "./fieldFilter.js";
+export { FieldFilterPanel, type FieldFilterPanelProps } from "./FieldFilterPanel.js";
+export { FilterBuilder, type FilterBuilderProps, type SavedFilterValues } from "./FilterBuilder.js";
+export { FilterEditor } from "./FilterEditor.js";
+export { FilterGroupEditor, type FilterGroupEditorProps } from "./FilterGroupEditor.js";
+export { FilterNameDialog, type FilterNameDialogProps } from "./FilterNameDialog.js";
+export { FilterRow, type FilterRowProps } from "./FilterRow.js";
+export { FilterShareDialog, type FilterShareDialogProps } from "./FilterShareDialog.js";
+export { FilterStringField, type FilterStringFieldProps } from "./FilterStringField.js";
+export { FilterValueEditor, type FilterValueEditorProps } from "./FilterValueEditor.js";
+export { SavedFilterTree, type SavedFilterSelection, type SavedFilterTreeProps } from "./SavedFilterTree.js";
+export type { FilterEditorProps, FilterEditorSize, FilterValueOption, GetFieldOptions } from "./types.js";
+export {
+	type DistinctValue,
+	supportsDistinctValues,
+	useDistinctValues,
+	type UseDistinctValuesResult,
+} from "./useDistinctValues.js";

package/src/filter/types.ts

@@ -0,0 +1,38 @@
+import type { FieldMetadata, FilterTree } from "@olenbetong/appframe-core";
+
+/** A selectable value for a field that has a fixed list of values. */
+export type FilterValueOption = {
+	value: string;
+	label?: string;
+};
+
+/**
+ * Resolves the list of values offered in the value editor for a field. Return
+ * `undefined` to fall back to a free text editor.
+ *
+ * Lookup fields carry a `valueListRecordSource` in their metadata, but loading
+ * that record source needs a data object, which is out of scope for this
+ * component. Supply the options from the outside instead.
+ */
+export type GetFieldOptions = (field: FieldMetadata) => FilterValueOption[] | undefined;
+
+export type FilterEditorSize = "sm" | "md" | "lg";
+
+export type FilterEditorProps = {
+	/** The fields the user can filter on. Fields with `excludeFromFilter` are hidden. */
+	fields: FieldMetadata[];
+	/** The filter tree. Use together with `onChange` for a controlled component. */
+	value?: FilterTree | null;
+	/** The initial filter tree when uncontrolled. */
+	defaultValue?: FilterTree | null;
+	onChange?: (filter: FilterTree) => void;
+	/** Renders the tree without any editing affordances. */
+	readOnly?: boolean;
+	/** Shows the filter string below the tree, editable unless `readOnly`. */
+	showFilterString?: boolean;
+	/** View the filter applies to. Passed to the conversion endpoint. */
+	viewName?: string;
+	getFieldOptions?: GetFieldOptions;
+	className?: string;
+	"data-size"?: FilterEditorSize;
+};

package/src/filter/useDistinctValues.test.ts

@@ -0,0 +1,102 @@
+import type { FieldMetadata, FilterExpression, FilterTree } from "@olenbetong/appframe-core";
+import { describe, expect, test } from "vitest";
+
+import { buildDistinctParameters } from "./useDistinctValues.js";
+
+const field: FieldMetadata = { name: "Name", caption: "Name", type: "string", nullable: true };
+
+function expression(column: string, value = "x"): FilterExpression {
+	return { type: "expression", column, operator: "contains", value } as FilterExpression;
+}
+
+function tree(...items: FilterTree["items"]): FilterTree {
+	return { type: "group", mode: "and", items };
+}
+
+describe("buildDistinctParameters", () => {
+	test("groups by the field and counts another field", () => {
+		let parameters = buildDistinctParameters({
+			field,
+			countField: "PrimKey",
+			filter: null,
+			withCounts: true,
+		});
+
+		expect(parameters.fields).toEqual([{ name: "Name" }, { name: "PrimKey", aggregate: "COUNT" }]);
+		expect(parameters).toMatchObject({ groupBy: ["Name"], sortOrder: [{ Name: "asc" }] });
+		expect(parameters).not.toHaveProperty("distinctRows");
+	});
+
+	test("falls back to a plain distinct list without counts", () => {
+		let parameters = buildDistinctParameters({
+			field,
+			countField: "PrimKey",
+			filter: null,
+			withCounts: false,
+		});
+
+		expect(parameters.fields).toEqual([{ name: "Name" }]);
+		expect(parameters).toMatchObject({ distinctRows: true });
+		expect(parameters).not.toHaveProperty("groupBy");
+	});
+
+	test("has no counts when no other field is available to count", () => {
+		let parameters = buildDistinctParameters({ field, countField: null, filter: null, withCounts: true });
+
+		expect(parameters.fields).toEqual([{ name: "Name" }]);
+		expect(parameters).toMatchObject({ distinctRows: true });
+	});
+
+	test("keeps other criteria but drops the field's own", () => {
+		let filter = tree(expression("Name"), expression("Other"));
+		let parameters = buildDistinctParameters({ field, countField: "PrimKey", filter, withCounts: true });
+
+		expect(parameters.filterObject).toEqual(tree(expression("Other")));
+	});
+
+	test("has no filter when the field owns every criterion", () => {
+		let parameters = buildDistinctParameters({
+			field,
+			countField: "PrimKey",
+			filter: tree(expression("Name")),
+			withCounts: true,
+		});
+
+		expect(parameters.filterObject).toBe(null);
+	});
+
+	test("adds the search text as a criterion on the field", () => {
+		let parameters = buildDistinctParameters({
+			field,
+			countField: "PrimKey",
+			filter: null,
+			search: "ab",
+			withCounts: true,
+		});
+
+		expect(parameters.filterObject).toMatchObject({
+			type: "group",
+			items: [{ column: "Name", operator: "contains", value: "ab" }],
+		});
+	});
+
+	test("combines the search text with the other criteria", () => {
+		let parameters = buildDistinctParameters({
+			field,
+			countField: "PrimKey",
+			filter: tree(expression("Other")),
+			search: "ab",
+			withCounts: true,
+		});
+
+		expect(parameters.filterObject).toMatchObject({
+			items: [tree(expression("Other")), { column: "Name", value: "ab" }],
+		});
+	});
+
+	test("caps the number of values loaded", () => {
+		let parameters = buildDistinctParameters({ field, countField: "PrimKey", filter: null, withCounts: true });
+
+		expect(parameters.maxRecords).toBe(200);
+	});
+});

package/src/filter/useDistinctValues.ts

@@ -0,0 +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 };
+}

package/src/global.d.ts

@@ -0,0 +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;

package/src/grid/AfGridColumnsPanel.tsx

@@ -0,0 +1,118 @@
+import { Button, Checkbox, Dialog, Heading, Search } from "@digdir/designsystemet-react";
+import {
+	type GridApi,
+	gridColumnDefinitionsSelector,
+	gridColumnVisibilityModelSelector,
+	useGridSelector,
+} from "@mui/x-data-grid-pro";
+import { getLocalizedString } from "@olenbetong/appframe-core";
+
+import { useState } from "react";
+import { useAfGridContext } from "./AfGridContext.js";
+
+export type AfGridColumnsPanelProps = {
+	open: boolean;
+	onClose: () => void;
+};
+
+/**
+ * Replacement for the grid's own column panel, built with Designsystemet
+ * components. Columns can be searched, toggled and reordered by dragging.
+ *
+ * Rendered as a sibling of the grid rather than inside it, so it reads the grid
+ * api from `AfGridContext` — `useGridApiContext` is only available inside the
+ * `DataGrid` subtree. `AfGrid` mounts it only while it is open, so the grid
+ * state is always initialized by the time the selectors run.
+ */
+export function AfGridColumnsPanel({ open, onClose }: AfGridColumnsPanelProps) {
+	let { apiRef } = useAfGridContext();
+	let columns = useGridSelector(apiRef as React.RefObject<GridApi>, gridColumnDefinitionsSelector);
+	let visibilityModel = useGridSelector(apiRef as React.RefObject<GridApi>, gridColumnVisibilityModelSelector);
+	let [search, setSearch] = useState("");
+	let [dragField, setDragField] = useState<string | null>(null);
+
+	let togglable = columns.filter((column) => column.hideable !== false && column.type !== "actions");
+	let query = search.trim().toLowerCase();
+	let matching = query
+		? togglable.filter((column) => (column.headerName ?? column.field).toLowerCase().includes(query))
+		: togglable;
+
+	function setAll(isVisible: boolean) {
+		let model = { ...visibilityModel };
+
+		for (let column of matching) {
+			model[column.field] = isVisible;
+		}
+
+		apiRef.current?.setColumnVisibilityModel(model);
+	}
+
+	function handleDrop(targetField: string) {
+		if (!dragField || dragField === targetField) return;
+
+		let order = apiRef.current?.getAllColumns().map((column) => column.field) ?? [];
+		let targetIndex = order.indexOf(targetField);
+
+		if (targetIndex >= 0) {
+			apiRef.current?.setColumnIndex(dragField, targetIndex);
+		}
+
+		setDragField(null);
+	}
+
+	return (
+		<Dialog
+			open={open}
+			className="AfGrid-columnsPanel"
+			closedby="any"
+			onClose={onClose}
+			closeButton={getLocalizedString("Close")}
+		>
+			<Dialog.Block>
+				<Heading level={2} data-size="xs">
+					{getLocalizedString("Columns")}
+				</Heading>
+			</Dialog.Block>
+			<Dialog.Block className="AfGrid-columnsPanelSearch">
+				<Search data-size="sm">
+					<Search.Input
+						aria-label={getLocalizedString("Search")}
+						value={search}
+						onChange={(event) => setSearch(event.currentTarget.value)}
+					/>
+					<Search.Clear onClick={() => setSearch("")} />
+				</Search>
+				<ul className="AfGrid-columnsPanelList">
+					{matching.map((column) => (
+						<li
+							key={column.field}
+							className="AfGrid-columnsPanelItem"
+							draggable
+							onDragStart={() => setDragField(column.field)}
+							onDragOver={(event) => event.preventDefault()}
+							onDrop={() => handleDrop(column.field)}
+						>
+							<Checkbox
+								data-size="sm"
+								label={column.headerName ?? column.field}
+								checked={visibilityModel[column.field] !== false}
+								onChange={(event) => apiRef.current?.setColumnVisibility(column.field, event.currentTarget.checked)}
+							/>
+						</li>
+					))}
+				</ul>
+			</Dialog.Block>
+			<Dialog.Block className="AfGrid-columnsPanelActions">
+				<Button variant="tertiary" data-size="sm" onClick={() => setAll(false)}>
+					{getLocalizedString("Hide all")}
+				</Button>
+				<Button variant="tertiary" data-size="sm" onClick={() => setAll(true)}>
+					{getLocalizedString("Show all")}
+				</Button>
+				<Button data-size="sm" onClick={onClose}>
+					{getLocalizedString("Close")}
+				</Button>
+			</Dialog.Block>
+		</Dialog>
+	);
+}