@olenbetong/appframe-ds 1.0.3 → 1.2.0

package/src/grid/useAfCurrentIndex.ts

@@ -1,63 +1,63 @@
-import type { GridApi, GridCellParams, GridRowId } from "@mui/x-data-grid-premium";
-import { type DataObject, uid } from "@olenbetong/appframe-data";
-import { useEvent } from "@olenbetong/appframe-react";
-
-import { useEffect, useRef } from "react";
-
-export type useAfCurrentIndexOptions = {
-	apiRef: React.RefObject<GridApi | null>;
-	dataObject: DataObject<any>;
-	enabled: boolean;
-	idField: string;
-	/**
-	 * Id of the grid's new item row, if it has one. A current index of -1 then
-	 * focuses that row, since the framework's new record has no row in the data.
-	 */
-	newItemRowId?: GridRowId | null;
-};
-
-function getRowId(row: any, idField: string) {
-	if (!row) return row;
-	return row[uid] ?? row[idField];
-}
-
-export function useAfCurrentIndex({ apiRef, dataObject, idField, enabled, newItemRowId }: useAfCurrentIndexOptions) {
-	let triggeredByFocusEvent = useRef(false);
-	let focusColumn = useRef<string>(null);
-
-	useEffect(() => {
-		function handleFocusChange(options: GridCellParams) {
-			focusColumn.current = options.field;
-
-			let currentId = getRowId(dataObject.currentRow(), idField);
-			if (currentId !== options.id) {
-				let newIndex = dataObject.findIndex((row) => getRowId(row, idField) === options.id);
-				if (newIndex >= 0) {
-					triggeredByFocusEvent.current = true;
-					dataObject.setCurrentIndex(newIndex);
-				}
-			}
-		}
-
-		if (enabled) {
-			if (!focusColumn.current) {
-				focusColumn.current = apiRef.current?.getVisibleColumns()[0]?.field ?? null;
-			}
-
-			return apiRef.current?.subscribeEvent("cellFocusIn", handleFocusChange);
-		}
-	}, [apiRef, dataObject, idField, enabled]);
-
-	useEvent(dataObject, "onCurrentIndexChanged", (event) => {
-		if (enabled && triggeredByFocusEvent.current === false) {
-			if (focusColumn.current && document.activeElement?.closest(".MuiDataGrid-cell")) {
-				let rowId = event.detail === -1 ? newItemRowId : getRowId(dataObject.getData(event.detail), idField);
-				if (rowId != null) {
-					apiRef.current?.setCellFocus(rowId, focusColumn.current);
-				}
-			}
-		} else {
-			triggeredByFocusEvent.current = false;
-		}
-	});
-}
+import type { GridApi, GridCellParams, GridRowId } from "@mui/x-data-grid-premium";
+import { type DataObject, uid } from "@olenbetong/appframe-data";
+import { useEvent } from "@olenbetong/appframe-react";
+
+import { useEffect, useRef } from "react";
+
+export type useAfCurrentIndexOptions = {
+	apiRef: React.RefObject<GridApi | null>;
+	dataObject: DataObject<any>;
+	enabled: boolean;
+	idField: string;
+	/**
+	 * Id of the grid's new item row, if it has one. A current index of -1 then
+	 * focuses that row, since the framework's new record has no row in the data.
+	 */
+	newItemRowId?: GridRowId | null;
+};
+
+function getRowId(row: any, idField: string) {
+	if (!row) return row;
+	return row[uid] ?? row[idField];
+}
+
+export function useAfCurrentIndex({ apiRef, dataObject, idField, enabled, newItemRowId }: useAfCurrentIndexOptions) {
+	let triggeredByFocusEvent = useRef(false);
+	let focusColumn = useRef<string>(null);
+
+	useEffect(() => {
+		function handleFocusChange(options: GridCellParams) {
+			focusColumn.current = options.field;
+
+			let currentId = getRowId(dataObject.currentRow(), idField);
+			if (currentId !== options.id) {
+				let newIndex = dataObject.findIndex((row) => getRowId(row, idField) === options.id);
+				if (newIndex >= 0) {
+					triggeredByFocusEvent.current = true;
+					dataObject.setCurrentIndex(newIndex);
+				}
+			}
+		}
+
+		if (enabled) {
+			if (!focusColumn.current) {
+				focusColumn.current = apiRef.current?.getVisibleColumns()[0]?.field ?? null;
+			}
+
+			return apiRef.current?.subscribeEvent("cellFocusIn", handleFocusChange);
+		}
+	}, [apiRef, dataObject, idField, enabled]);
+
+	useEvent(dataObject, "onCurrentIndexChanged", (event) => {
+		if (enabled && triggeredByFocusEvent.current === false) {
+			if (focusColumn.current && document.activeElement?.closest(".MuiDataGrid-cell")) {
+				let rowId = event.detail === -1 ? newItemRowId : getRowId(dataObject.getData(event.detail), idField);
+				if (rowId != null) {
+					apiRef.current?.setCellFocus(rowId, focusColumn.current);
+				}
+			}
+		} else {
+			triggeredByFocusEvent.current = false;
+		}
+	});
+}

package/src/grid/useAfData.ts

@@ -1,20 +1,20 @@
-import type { DataObject } from "@olenbetong/appframe-data";
-import { useData } from "@olenbetong/appframe-react";
-
-import { useMemo } from "react";
-
-export function useAfData<T extends Record<string, unknown>, K = T[]>(
-	dataObject: DataObject<T>,
-	{ getData }: { getData?: (data: T[]) => K },
-): K {
-	let rawData = useData(dataObject);
-	let data = useMemo(() => {
-		if (getData) {
-			return getData(rawData as T[]) as K;
-		}
-
-		return rawData as K;
-	}, [rawData, getData]);
-
-	return data;
-}
+import type { DataObject } from "@olenbetong/appframe-data";
+import { useData } from "@olenbetong/appframe-react";
+
+import { useMemo } from "react";
+
+export function useAfData<T extends Record<string, unknown>, K = T[]>(
+	dataObject: DataObject<T>,
+	{ getData }: { getData?: (data: T[]) => K },
+): K {
+	let rawData = useData(dataObject);
+	let data = useMemo(() => {
+		if (getData) {
+			return getData(rawData as T[]) as K;
+		}
+
+		return rawData as K;
+	}, [rawData, getData]);
+
+	return data;
+}

package/src/grid/useAfFilter.ts

@@ -1,160 +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);
-}
+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

@@ -1,55 +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]);
-}
+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]);
+}