@olenbetong/appframe-ds 0.8.0 → 0.9.0

package/src/grid/useAfFilter.ts

@@ -0,0 +1,160 @@
+import {
+	countExpressions,
+	createEmptyFilter,
+	type FieldMetadata,
+	type FilterExpression,
+	type FilterTree,
+	pruneFilter,
+	toFilterTree,
+} from "@olenbetong/appframe-core";
+import type { DataObject, Filter } from "@olenbetong/appframe-data";
+import { deepEqual, useDebounce, useNamedFilter } from "@olenbetong/appframe-react";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+
+import { getFieldExpressions, setFieldExpressions } from "../filter/fieldFilter.js";
+
+/**
+ * The grid's filter, shared by the header filters and the filter builder.
+ *
+ * `filter` is the tree being edited and may contain incomplete criteria; only
+ * the pruned tree is ever sent to the server.
+ */
+export type AfFilterApi = {
+	/** The filter tree currently being edited. */
+	filter: FilterTree;
+	/** Replaces the whole tree. Applied to the data object after a short debounce. */
+	setFilter: (filter: FilterTree) => void;
+	/** The field's top level criteria. See `getFieldExpressions`. */
+	getFieldCriteria: (field: string) => FilterExpression[];
+	/** Replaces the field's top level criteria. */
+	setFieldCriteria: (field: string, expressions: FilterExpression[]) => void;
+	/** Number of criteria in the whole tree, shown on the toolbar filter button. */
+	filterCount: number;
+};
+
+/**
+ * Finds the grid's own named slice within a (possibly combined) filter object.
+ * Falls back to the whole filter object when no named slice is present, which
+ * preserves the behaviour for filter objects set without a name.
+ */
+function extractNamedSlice(filter: Filter, name: string): Filter {
+	if (!filter) return null;
+
+	if (filter.type === "group") {
+		if (filter.name === name) {
+			return filter;
+		}
+
+		let named = filter.items.find((item) => item.type === "group" && item.name === name);
+		if (named) {
+			return named;
+		}
+
+		let anyNamed = filter.items.some((item) => item.type === "group" && item.name != null);
+		if (anyNamed) {
+			return null;
+		}
+	}
+
+	return filter;
+}
+
+/**
+ * Owns the grid's filter as a single `FilterTree` in one named filter slot.
+ *
+ * Both the header filters and the toolbar's filter builder edit this tree, so
+ * a criterion added in one is immediately visible in the other. MUI's own
+ * `GridFilterModel` is not used as a transport: it cannot represent nested
+ * groups or the full Appframe operator set, so mirroring the tree into it would
+ * lose information.
+ *
+ * @param dataObject Data object the filter is applied to
+ * @param id The grid id, used as the named filter slot name
+ * @param autoLoad Whether the data object should load if it has no data yet
+ */
+export function useAfFilter({
+	autoLoad,
+	dataObject,
+	id,
+}: {
+	autoLoad: boolean;
+	dataObject: DataObject<any>;
+	id: string;
+}): AfFilterApi {
+	let defaultFilter = useMemo(
+		() => extractNamedSlice(dataObject.getParameter("filterObject") ?? null, id),
+		[dataObject, id],
+	);
+
+	// The named slot survives unmounting, so a grid that is navigated away from
+	// and back keeps its filter. `defaultFilter` only seeds the slot the first
+	// time it is registered.
+	let [applied, setApplied] = useNamedFilter(dataObject, id, {
+		type: "filterObject",
+		autoLoad,
+		defaultFilter,
+	});
+
+	let [filter, setFilter] = useState<FilterTree>(() => nameRoot(toFilterTree(applied), id));
+
+	// Applying on every keystroke would refresh the data object per character.
+	let debouncedFilter = useDebounce(filter, 400);
+	// The last filter the tree and the data object agreed on, so each direction
+	// of the sync below can tell a real change from an echo of its own change.
+	let syncedFilter = useRef<Filter>(applied);
+
+	// Tree -> data object
+	useEffect(() => {
+		let pruned = pruneFilter(debouncedFilter);
+		let next = pruned ? nameRoot(pruned, id) : null;
+
+		if (deepEqual(next, syncedFilter.current)) return;
+
+		syncedFilter.current = next;
+		setApplied(next);
+	}, [debouncedFilter, setApplied, id]);
+
+	// Data object -> tree, for filters changed by something other than the grid
+	useEffect(() => {
+		if (deepEqual(applied, syncedFilter.current)) return;
+
+		syncedFilter.current = applied;
+		setFilter(nameRoot(toFilterTree(applied), id));
+	}, [applied, id]);
+
+	let getFieldCriteria = useCallback((field: string) => getFieldExpressions(filter, field), [filter]);
+
+	let setFieldCriteria = useCallback(
+		(field: string, expressions: FilterExpression[]) =>
+			setFilter((current) => setFieldExpressions(current, field, expressions)),
+		[],
+	);
+
+	return useMemo(
+		() => ({
+			filter,
+			setFilter,
+			getFieldCriteria,
+			setFieldCriteria,
+			filterCount: countExpressions(filter),
+		}),
+		[filter, getFieldCriteria, setFieldCriteria],
+	);
+}
+
+/**
+ * The root group carries the slot name so a filter read back from the data
+ * object's combined `filterObject` can be recognised as this grid's.
+ */
+function nameRoot(filter: FilterTree | null | undefined, id: string): FilterTree {
+	let tree = filter ?? createEmptyFilter();
+
+	return tree.name === id ? tree : { ...tree, name: id };
+}
+
+/** Looks up the metadata for a field, matching case-insensitively. */
+export function findFilterField(fields: FieldMetadata[], name: string): FieldMetadata | undefined {
+	let lowerName = name.toLowerCase();
+
+	return fields.find((field) => field.name.toLowerCase() === lowerName);
+}

package/src/grid/useAfFilterFields.ts

@@ -0,0 +1,55 @@
+import type { FieldMetadata, FilterFieldType } from "@olenbetong/appframe-core";
+import type { DataObject } from "@olenbetong/appframe-data";
+import { useMemo } from "react";
+
+import type { AfGridColumn } from "./useAfColumns.js";
+
+/** Data object field types that do not map onto a filter builder field type. */
+const FIELD_TYPES: Record<string, FilterFieldType> = {
+	bigint: "number",
+	boolean: "boolean",
+	date: "date",
+	datetime: "datetime",
+	number: "number",
+	string: "string",
+	time: "string",
+	uniqueidentifier: "uniqueidentifier",
+};
+
+function toFilterFieldType(type: string | undefined): FilterFieldType {
+	return FIELD_TYPES[type?.toLowerCase() ?? ""] ?? "string";
+}
+
+/**
+ * The fields the filter builder offers, derived from the data object's own
+ * field definitions. Column definitions only contribute their header name as
+ * the caption, and `filterColumn` remaps a column onto the field it filters on.
+ *
+ * Fields that no column refers to are still offered, so the user can filter on
+ * data that is not displayed — the same as the Windows client.
+ */
+export function useAfFilterFields(dataObject: DataObject<any>, columns: AfGridColumn[]): FieldMetadata[] {
+	return useMemo(() => {
+		let captions = new Map<string, string>();
+
+		for (let column of columns) {
+			if (typeof column === "string") continue;
+
+			let field = column.filterColumn ?? column.field;
+
+			if (column.filterable === false && !column.filterColumn) continue;
+			if (column.headerName) captions.set(field.toLowerCase(), column.headerName);
+		}
+
+		return dataObject
+			.getFields()
+			.filter((field) => !!field.name)
+			.map((field) => ({
+				name: field.name,
+				caption: captions.get(field.name.toLowerCase()) ?? field.caption ?? field.name,
+				type: toFilterFieldType(field.type),
+				nullable: field.nullable !== false,
+			}))
+			.sort((a, b) => a.caption.localeCompare(b.caption));
+	}, [dataObject, columns]);
+}

package/src/grid/useAfGridApi.ts

@@ -0,0 +1,66 @@
+import type { GridApi } from "@mui/x-data-grid-pro";
+import type { DataObject } from "@olenbetong/appframe-data";
+
+import type React from "react";
+import { useCallback, useRef } from "react";
+
+import type { AfGridProps } from "./index.js";
+import { afColumnsToMuiColumn, getColumnVisibilityModel } from "./useAfColumns.js";
+import { afSortOrderToMuiSortModel } from "./useAfSortModel.js";
+
+export interface AfGridApi extends GridApi {
+	getDataObject: () => DataObject<any> | undefined;
+	resetLayout: () => void;
+}
+
+export function useAfGridApi(props: Partial<AfGridProps>, apiRef: React.RefObject<GridApi | null>) {
+	let propsRef = useRef<Partial<AfGridProps>>(props);
+	propsRef.current = props;
+
+	let getDataObject = useCallback(() => propsRef.current.dataObject, []);
+	let resetLayout = useCallback(() => {
+		if (propsRef.current.dataObject) {
+			let { disableDelete, disableEdit, idField = "PrimKey" } = propsRef.current;
+			apiRef.current?.updateColumns(
+				afColumnsToMuiColumn({
+					allowDelete: propsRef.current.dataObject.isDeleteAllowed(),
+					allowUpdate: propsRef.current.dataObject.isUpdateAllowed(),
+					disableDelete,
+					disableEdit,
+					idField,
+					apiRef,
+					columnsProp: propsRef.current.columns ?? [],
+					dataObject: propsRef.current.dataObject,
+				}),
+			);
+
+			if (propsRef.current.columns) {
+				propsRef.current.columns.forEach((column, index) => {
+					let field = typeof column === "string" ? column : column.field;
+					let width = typeof column === "string" ? 150 : (column.width ?? 150);
+					apiRef.current?.setColumnIndex(field, index);
+					apiRef.current?.setColumnWidth(field, width);
+				});
+				apiRef.current?.setColumnVisibilityModel({
+					...getColumnVisibilityModel(propsRef.current.columns),
+					...propsRef.current?.initialState?.columns?.columnVisibilityModel,
+				});
+			}
+
+			apiRef.current?.setDensity(propsRef.current.initialState?.density ?? "compact");
+			apiRef.current?.setPageSize(propsRef.current.dataObject.options.parameters.maxRecords ?? 100);
+			apiRef.current?.setSortModel(
+				afSortOrderToMuiSortModel(
+					propsRef.current.dataObject,
+					propsRef.current.dataObject.options.parameters.sortOrder,
+				),
+			);
+		}
+		apiRef.current?.setPinnedColumns(propsRef.current.initialState?.pinnedColumns ?? {});
+	}, [apiRef]);
+
+	if (apiRef.current) {
+		(apiRef.current as AfGridApi).getDataObject = getDataObject;
+		(apiRef.current as AfGridApi).resetLayout = resetLayout;
+	}
+}

package/src/grid/useAfKeyBindings.ts

@@ -0,0 +1,36 @@
+import type { GridApi } from "@mui/x-data-grid-pro";
+import type { DataObject } from "@olenbetong/appframe-data";
+
+import type React from "react";
+import { useCallback } from "react";
+
+import { addRow } from "./editing.js";
+
+export function useAfKeyBindings<T extends { PrimKey: string }>({
+	apiRef,
+	dataObject,
+}: {
+	apiRef: React.RefObject<GridApi | null>;
+	dataObject: DataObject<T>;
+}): Pick<React.HTMLProps<Element>, "onKeyDown" | "onKeyDownCapture" | "onKeyUp" | "onKeyUpCapture"> {
+	// oxlint-disable-next-line react-hooks/exhaustive-deps -- RefObject does not need to be in the dependency array
+	let onKeyUpCapture = useCallback(
+		(event: React.KeyboardEvent) => {
+			let handled = false;
+			if (["n", "N"].includes(event.key) && event.altKey && !event.shiftKey && !event.ctrlKey) {
+				handled = true;
+				addRow({ apiRef, dataObject });
+			}
+
+			if (handled) {
+				event.preventDefault();
+				event.stopPropagation();
+			}
+		},
+		[dataObject],
+	);
+
+	return {
+		onKeyUpCapture,
+	};
+}

package/src/grid/useAfPagination.ts

@@ -0,0 +1,53 @@
+import type { DataGridProProps, GridPaginationModel } from "@mui/x-data-grid-pro";
+import type { DataObject } from "@olenbetong/appframe-data";
+import { useDataLength, usePaging, useParameter } from "@olenbetong/appframe-react";
+
+import { useMemo } from "react";
+
+/**
+ * If the data object is dynamic, returns the data grid properties needed
+ * to bind the pagination to the data object.
+ *
+ * @param dataObject Data object grid is used with
+ */
+export function useAfPagination(dataObject: DataObject<any>): Partial<DataGridProProps> {
+	let paging = usePaging(dataObject);
+	let maxRecords = useParameter(dataObject, "maxRecords");
+	let dataLength = useDataLength(dataObject);
+
+	let paginationModel = useMemo(
+		() => ({
+			pageSize: maxRecords ?? 50,
+			page: paging.page || 0,
+		}),
+		[paging.page, maxRecords],
+	);
+
+	if (dataObject.isDynamicLoading()) {
+		return {
+			pagination: true,
+			paginationMode: "server",
+			paginationModel,
+			rowCount: dataLength,
+			pageSizeOptions: [10, 25, 50, 100, 250, 500, 1_000, 10_000],
+			onPaginationModelChange(newModel: GridPaginationModel) {
+				let newPageSize = newModel.pageSize ?? paginationModel.pageSize ?? 50;
+				if (newPageSize !== maxRecords) {
+					dataObject.setParameter("maxRecords", newPageSize);
+					// We don't want the pagination setup to load data when the grid is not set up to auto load
+					// data. To prevent that, we only refresh data if it is already loaded/loading.
+					if (dataObject.isDataLoaded() || dataObject.isDataLoading()) {
+						dataObject.refreshDataSource();
+					}
+				}
+
+				let newPage = typeof newModel.page === "number" && !Number.isNaN(newModel.page) ? newModel.page : paging.page;
+				if (newPage !== paging.page) {
+					paging.changePage(newPage);
+				}
+			},
+		};
+	}
+
+	return {};
+}

package/src/grid/useAfPersistedState.ts

@@ -0,0 +1,222 @@
+import type { GridApi, GridInitialState, GridPaginationModel } from "@mui/x-data-grid-pro";
+
+import localforage from "localforage";
+import { useEffect, useState } from "react";
+
+import type { AfGridProps } from "./index.js";
+import { getColumnVisibilityModel } from "./useAfColumns.js";
+
+const settingsStore = localforage.createInstance({
+	name: `AfGridLayouts.${globalThis.af?.userSession?.login ?? "anonymous"}`,
+});
+
+type GridSettings = {
+	layoutVersion: string | number;
+	state: GridInitialState;
+};
+
+const settingsCache: Record<string, GridSettings> = {};
+
+async function persistState(
+	key: string,
+	layoutVersion: string | number,
+	state: GridInitialState | null | undefined,
+	config?: StatePersistenceConfig,
+) {
+	if (state) {
+		state = structuredClone(state);
+
+		let settings: GridSettings = {
+			layoutVersion,
+			state: removeNonPersistedState(state, config),
+		};
+
+		if (state.pagination?.paginationModel?.page !== undefined) {
+			delete state.pagination.paginationModel.page;
+		}
+
+		settingsCache[key] = settings;
+		await settingsStore.setItem<GridSettings>(key, settings);
+	}
+}
+
+function removeNonPersistedState(state: GridInitialState, config?: StatePersistenceConfig): GridInitialState {
+	const newState: GridInitialState = {};
+	let columns: GridInitialState["columns"] = {};
+	let filter: GridInitialState["filter"] = {};
+	let pagination: GridInitialState["pagination"] = { paginationModel: {} };
+	let sorting: GridInitialState["sorting"] = {};
+
+	// Persist the relevant state unless explicitly disabled in the config
+	if (config?.density !== false) {
+		newState.density = state.density;
+	}
+	if (config?.pinnedColumns !== false) {
+		newState.pinnedColumns = state.pinnedColumns;
+	}
+	if (config?.columns?.columnVisibilityModel !== false) {
+		columns.columnVisibilityModel = state.columns?.columnVisibilityModel;
+	}
+	if (config?.columns?.dimensions !== false) {
+		columns.dimensions = state.columns?.dimensions;
+	}
+	if (config?.columns?.orderedFields !== false) {
+		columns.orderedFields = state.columns?.orderedFields;
+	}
+	if (config?.pagination?.paginationModel.pageSize !== false) {
+		(pagination.paginationModel as Partial<GridPaginationModel>).pageSize = state.pagination?.paginationModel?.pageSize;
+	}
+	if (config?.preferencePanel === true) {
+		newState.preferencePanel = state.preferencePanel;
+	}
+
+	// Sort model, current page and filter model are not persisted by default
+	if (config?.sorting?.sortModel === true) {
+		sorting.sortModel = state.sorting?.sortModel;
+	}
+	if (config?.pagination?.paginationModel.page === true) {
+		(pagination.paginationModel as Partial<GridPaginationModel>).page = state.pagination?.paginationModel?.page;
+	}
+	if (config?.filter?.filterModel === true) {
+		filter.filterModel = state.filter?.filterModel;
+	}
+
+	return {
+		...newState,
+		columns,
+		filter,
+		pagination,
+		sorting,
+	};
+}
+
+let isLoaded = false;
+export const isPersistedStateLoaded = () => isLoaded;
+
+type GetInitialStateProps = Pick<AfGridProps, "id" | "layoutVersion" | "columns" | "initialState" | "persistenceModel">;
+
+function getInitialState({ columns, persistenceModel, id, initialState, layoutVersion }: GetInitialStateProps) {
+	let key = `${af.article.id}.${id}`;
+	let persistedState = settingsCache[key];
+
+	let state: GridInitialState =
+		persistedState?.layoutVersion === layoutVersion
+			? removeNonPersistedState(persistedState.state, persistenceModel)
+			: {
+					density: "compact",
+					...initialState,
+				};
+
+	if (!state.columns) {
+		state.columns = {};
+	}
+
+	if (!state.columns.columnVisibilityModel) {
+		state.columns.columnVisibilityModel = getColumnVisibilityModel(columns);
+	}
+
+	if (!state.columns.orderedFields) {
+		state.columns.orderedFields = columns
+			.filter((c) => typeof c === "string" || !c.hide)
+			.map((c) => (typeof c === "string" ? c : c.field));
+	} else {
+		// Append any columns added since the layout was saved that aren't already present
+		let known = new Set(state.columns.orderedFields);
+		for (let c of columns) {
+			let field = typeof c === "string" ? c : c.field;
+			let hidden = typeof c !== "string" && c.hide;
+			if (!hidden && !known.has(field)) {
+				state.columns.orderedFields.push(field);
+			}
+		}
+	}
+
+	return state;
+}
+
+// Load all article grid layouts even if the grid is not mounted yet.
+// This ways the persisted state can be restored faster after the initial
+// page load.
+export const settingsLoaded = settingsStore
+	.keys()
+	.then((keys) =>
+		Promise.allSettled(
+			keys
+				.filter((key) => key.startsWith(af.article.id))
+				.map((key) =>
+					settingsStore.getItem<GridSettings>(key).then((settings) => {
+						if (settings && !settingsCache[key]) {
+							settingsCache[key] = settings;
+						}
+					}),
+				),
+		),
+	)
+	.then(() => {
+		isLoaded = true;
+	});
+
+// Clean legacy state from local storage
+setTimeout(() => {
+	for (let key of Object.keys(localStorage)) {
+		if (key.includes("AfGrid")) {
+			localStorage.removeItem(key);
+		}
+	}
+}, 2000);
+
+export type StatePersistenceConfig = {
+	density?: boolean;
+	pinnedColumns?: boolean;
+	columns?: {
+		columnVisibilityModel?: boolean;
+		dimensions?: boolean;
+		orderedFields?: boolean;
+	};
+	filter?: {
+		filterModel?: boolean;
+	};
+	pagination?: {
+		paginationModel: {
+			page?: boolean;
+			pageSize?: boolean;
+		};
+	};
+	preferencePanel?: boolean;
+	sorting?: {
+		sortModel: boolean;
+	};
+};
+
+/**
+ * On mount, load the persisted state from Indexed DB, and if the persisted
+ * layout version matches, restore the layout. Then listen to changes to the
+ * state, and store the latest version in Indexed DB.
+ */
+export function useAfPersistedState(
+	props: { apiRef: React.RefObject<GridApi | null> } & Pick<
+		AfGridProps,
+		"id" | "layoutVersion" | "columns" | "initialState" | "persistenceModel"
+	>,
+): GridInitialState {
+	let { apiRef, columns, id, initialState, layoutVersion = 0, persistenceModel } = props;
+	let [initialState_] = useState(() => getInitialState({ columns, persistenceModel, id, initialState, layoutVersion }));
+
+	useEffect(() => {
+		let key = `${af.article.id}.${id}`;
+		let persistTimeout: any;
+
+		return apiRef.current?.subscribeEvent("stateChange", () => {
+			// Debounce the save, as state changes can be very frequent.
+			clearTimeout(persistTimeout);
+			persistTimeout = setTimeout(() => {
+				// Use optional chaining, as the component may unmount before the timeout
+				// fires.
+				let state = apiRef.current?.exportState();
+				persistState(key, layoutVersion, state, persistenceModel);
+			}, 300);
+		});
+	}, [apiRef, id, layoutVersion, persistenceModel]);
+
+	return initialState_;
+}