@olenbetong/appframe-ds 1.0.3 → 1.2.0

package/src/grid/useAfNewItemRow.ts

@@ -1,258 +1,258 @@
-import {
-	type DataGridPremiumProps as DataGridProps,
-	type GridApi,
-	type GridEventListener,
-	type GridPinnedRowsProp,
-	type GridRowId,
-	GridRowModes,
-	gridFocusCellSelector,
-	gridVisibleColumnDefinitionsSelector,
-} from "@mui/x-data-grid-premium";
-import { getLocalizedString } from "@olenbetong/appframe-core";
-import { type DataObject, uid } from "@olenbetong/appframe-data";
-import { setDataObjectField, usePermissions } from "@olenbetong/appframe-react";
-
-import type React from "react";
-import { useCallback, useEffect, useMemo, useRef, useState } from "react";
-
-import type { AfGridApi } from "./useAfGridApi.js";
-
-/**
- * Row id of the new item row. It never collides with a data row, whose id is
- * either the data object's uid or the value of the id field.
- */
-export const NEW_ITEM_ROW_ID = "AfGrid-newItemRow";
-
-export const NEW_ITEM_ROW_CLASS = "AfGrid-newItemRow";
-
-/**
- * Where the new item row is shown. `none` turns it off, and the Add button falls
- * back to appending an unsaved row to the data.
- */
-export type AfGridNewItemRowPosition = "top" | "bottom" | "none";
-
-export function isNewItemRow(id: GridRowId | null | undefined): boolean {
-	return id === NEW_ITEM_ROW_ID;
-}
-
-export type useAfNewItemRowOptions = {
-	apiRef: React.RefObject<GridApi | null>;
-	dataObject: DataObject<any>;
-	position: AfGridNewItemRowPosition;
-	disableInsert?: boolean;
-	pinnedRows?: GridPinnedRowsProp;
-	getRowClassName?: DataGridProps["getRowClassName"];
-};
-
-export type AfNewItemRow = {
-	/** True when the row is rendered, i.e. inserting is allowed and it is not turned off */
-	enabled: boolean;
-	/**
-	 * Saves the values the user entered in the new item row as a new record at
-	 * index -1 on the data object. Returns the blank row the grid should show
-	 * in the new item row afterwards. Throws if the save fails, so the grid keeps
-	 * the row in edit mode with the entered values.
-	 */
-	save: (record: Record<string, unknown>) => Promise<Record<string, unknown>>;
-	/** Focuses the new item row and starts editing it. Returns false when the row is not rendered. */
-	start: () => boolean;
-	/** Props to spread onto the grid */
-	gridProps: Pick<DataGridProps, "pinnedRows" | "getRowClassName">;
-	/** Style for the grid root, carrying the overlay text as a CSS custom property */
-	rootStyle: React.CSSProperties;
-};
-
-/**
- * A DevExpress-style new item row: a single non-data row pinned above or below
- * the data, showing an overlay text until the user starts editing it. The row
- * lives outside the data set, so sorting, filtering, paging and grouping leave
- * it alone.
- *
- * When editing starts the data object's current index moves to -1, the
- * framework's new record, so bound forms and child data objects follow. The
- * entered values are only written to the data object when the row is
- * committed, exactly like edits to existing rows.
- */
-export function useAfNewItemRow({
-	apiRef,
-	dataObject,
-	position,
-	disableInsert,
-	pinnedRows: pinnedRowsProp,
-	getRowClassName: getRowClassNameProp,
-}: useAfNewItemRowOptions): AfNewItemRow {
-	let { allowInsert } = usePermissions(dataObject);
-	let enabled = position !== "none" && allowInsert && !disableInsert;
-	// Bumped after a save, so the pinned row is replaced by a blank one
-	let [generation, setGeneration] = useState(0);
-	// The row that was current before editing started, restored when the edit is cancelled
-	let previousIndex = useRef(-1);
-	let wasEditing = useRef(false);
-
-	let row = useMemo(() => {
-		if (!enabled) return null;
-		// `getData(-1)` is a blank record with every field set to null
-		return { ...(dataObject.getData(-1) as Record<string, unknown>), [uid]: NEW_ITEM_ROW_ID, generation };
-	}, [enabled, dataObject, generation]);
-
-	let beginNewRecord = useCallback(() => {
-		if (dataObject.getCurrentIndex() !== -1) {
-			previousIndex.current = dataObject.getCurrentIndex();
-			dataObject.setCurrentIndex(-1);
-		}
-	}, [dataObject]);
-
-	let cancelNewRecord = useCallback(() => {
-		if (dataObject.getCurrentIndex() !== -1) return;
-
-		dataObject.cancelEdit();
-
-		let index = previousIndex.current;
-		if (index >= 0 && index < dataObject.getDataLength()) {
-			dataObject.setCurrentIndex(index);
-		}
-	}, [dataObject]);
-
-	let start = useCallback(() => {
-		let api = apiRef.current;
-		if (!enabled || !api) return false;
-
-		let visibleColumns = gridVisibleColumnDefinitionsSelector(apiRef);
-		let firstEditable = visibleColumns.find((c) => c.editable === true) ?? visibleColumns[0];
-		if (!firstEditable) return false;
-
-		api.setCellFocus(NEW_ITEM_ROW_ID, firstEditable.field);
-		if (api.getRowMode(NEW_ITEM_ROW_ID) !== GridRowModes.Edit) {
-			api.startRowEditMode({ id: NEW_ITEM_ROW_ID, fieldToFocus: firstEditable.field });
-		}
-
-		return true;
-	}, [apiRef, enabled]);
-
-	let save = useCallback(
-		async (record: Record<string, unknown>) => {
-			beginNewRecord();
-
-			for (let field in record) {
-				let value = record[field];
-				if (value === undefined || value === null) continue;
-				if (dataObject.getFields(field)) {
-					setDataObjectField(dataObject, field, value);
-				}
-			}
-
-			let blankRow = { ...(dataObject.getData(-1) as Record<string, unknown>), [uid]: NEW_ITEM_ROW_ID };
-
-			if (!dataObject.isDirty()) {
-				// Nothing was entered, so committing the row is the same as cancelling it
-				cancelNewRecord();
-				return blankRow;
-			}
-
-			let focusBefore = gridFocusCellSelector(apiRef);
-
-			try {
-				await dataObject.endEdit();
-			} catch (error) {
-				// The framework keeps a failed new record in storage as an unsaved row.
-				// The grid keeps the draft in the new item row instead, so the unsaved
-				// row is dropped and the current index goes back to the new record.
-				if (dataObject.getCurrentIndex() >= 0 && dataObject.isNewRecord(dataObject.getCurrentIndex())) {
-					dataObject.cancelEdit();
-				}
-				// Not through `beginNewRecord`, which would record the row the framework
-				// landed on as the one to restore on cancel
-				dataObject.setCurrentIndex(-1);
-				throw error;
-			}
-
-			setGeneration((g) => g + 1);
-
-			// The created row is the current row now; move the focus there once the
-			// grid has rendered it, so the user can keep working from where it landed.
-			let createdIndex = dataObject.getCurrentIndex();
-			if (createdIndex >= 0 && focusBefore) {
-				let createdRow = dataObject.getData(createdIndex) as any;
-				let createdId: GridRowId = createdRow[uid];
-				setTimeout(() => {
-					let api = apiRef.current;
-					if (!api || !api.getRow(createdId)) return;
-					let rowIndex = api.getRowIndexRelativeToVisibleRows(createdId);
-					if (rowIndex >= 0) api.scrollToIndexes({ rowIndex });
-					api.setCellFocus(createdId, focusBefore.field);
-				});
-			}
-
-			return blankRow;
-		},
-		[apiRef, dataObject, beginNewRecord, cancelNewRecord],
-	);
-
-	useEffect(() => {
-		if (!enabled) return;
-
-		// Moves the data object to the new record when editing starts, whether the
-		// user started it or `start` did, and discards it when the edit is cancelled.
-		// A commit goes through `save` instead.
-		const handleRowModesModelChange: GridEventListener<"rowModesModelChange"> = (model) => {
-			let entry = model[NEW_ITEM_ROW_ID] as { mode: GridRowModes; ignoreModifications?: boolean } | undefined;
-			let isEditing = entry?.mode === GridRowModes.Edit;
-
-			if (isEditing && !wasEditing.current) {
-				beginNewRecord();
-			} else if (!isEditing && wasEditing.current && entry?.ignoreModifications === true) {
-				// Deferred until the grid has left edit mode and put the focus back on the
-				// cell, so that a bound current index moves the focus from a mounted cell
-				// instead of from an editor that is about to be unmounted.
-				setTimeout(cancelNewRecord);
-			}
-
-			wasEditing.current = isEditing;
-		};
-
-		return apiRef.current?.subscribeEvent("rowModesModelChange", handleRowModesModelChange);
-	}, [apiRef, enabled, beginNewRecord, cancelNewRecord]);
-
-	let pinnedRows = useMemo<GridPinnedRowsProp | undefined>(() => {
-		if (!row) return pinnedRowsProp;
-
-		// The new item row sits next to the data, inside any rows the consumer pinned
-		return {
-			top: position === "top" ? [...(pinnedRowsProp?.top ?? []), row] : pinnedRowsProp?.top,
-			bottom: position === "bottom" ? [row, ...(pinnedRowsProp?.bottom ?? [])] : pinnedRowsProp?.bottom,
-		};
-	}, [row, position, pinnedRowsProp]);
-
-	let getRowClassName = useCallback<NonNullable<DataGridProps["getRowClassName"]>>(
-		(params) => {
-			let className = getRowClassNameProp?.(params) ?? "";
-			return params.id === NEW_ITEM_ROW_ID ? `${className} ${NEW_ITEM_ROW_CLASS}`.trim() : className;
-		},
-		[getRowClassNameProp],
-	);
-
-	let rootStyle = useMemo<React.CSSProperties>(
-		() =>
-			({
-				// Read by the overlay's `content`, so the text is localized without a DOM node
-				"--AfGrid-newItemRowText": JSON.stringify(getLocalizedString("Click here to add a new row")),
-			}) as React.CSSProperties,
-		[],
-	);
-
-	useEffect(() => {
-		if (apiRef.current) {
-			(apiRef.current as AfGridApi).startNewItemRow = start;
-		}
-	}, [apiRef, start]);
-
-	return {
-		enabled,
-		save,
-		start,
-		gridProps: enabled
-			? { pinnedRows, getRowClassName }
-			: { pinnedRows: pinnedRowsProp, getRowClassName: getRowClassNameProp },
-		rootStyle,
-	};
-}
+import {
+	type DataGridPremiumProps as DataGridProps,
+	type GridApi,
+	type GridEventListener,
+	type GridPinnedRowsProp,
+	type GridRowId,
+	GridRowModes,
+	gridFocusCellSelector,
+	gridVisibleColumnDefinitionsSelector,
+} from "@mui/x-data-grid-premium";
+import { type DataObject, uid } from "@olenbetong/appframe-data";
+import { setDataObjectField, usePermissions } from "@olenbetong/appframe-react";
+
+import type React from "react";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+
+import type { AfGridApi } from "./useAfGridApi.js";
+import { getLocalizedString } from "../i18n.js";
+
+/**
+ * Row id of the new item row. It never collides with a data row, whose id is
+ * either the data object's uid or the value of the id field.
+ */
+export const NEW_ITEM_ROW_ID = "AfGrid-newItemRow";
+
+export const NEW_ITEM_ROW_CLASS = "AfGrid-newItemRow";
+
+/**
+ * Where the new item row is shown. `none` turns it off, and the Add button falls
+ * back to appending an unsaved row to the data.
+ */
+export type AfGridNewItemRowPosition = "top" | "bottom" | "none";
+
+export function isNewItemRow(id: GridRowId | null | undefined): boolean {
+	return id === NEW_ITEM_ROW_ID;
+}
+
+export type useAfNewItemRowOptions = {
+	apiRef: React.RefObject<GridApi | null>;
+	dataObject: DataObject<any>;
+	position: AfGridNewItemRowPosition;
+	disableInsert?: boolean;
+	pinnedRows?: GridPinnedRowsProp;
+	getRowClassName?: DataGridProps["getRowClassName"];
+};
+
+export type AfNewItemRow = {
+	/** True when the row is rendered, i.e. inserting is allowed and it is not turned off */
+	enabled: boolean;
+	/**
+	 * Saves the values the user entered in the new item row as a new record at
+	 * index -1 on the data object. Returns the blank row the grid should show
+	 * in the new item row afterwards. Throws if the save fails, so the grid keeps
+	 * the row in edit mode with the entered values.
+	 */
+	save: (record: Record<string, unknown>) => Promise<Record<string, unknown>>;
+	/** Focuses the new item row and starts editing it. Returns false when the row is not rendered. */
+	start: () => boolean;
+	/** Props to spread onto the grid */
+	gridProps: Pick<DataGridProps, "pinnedRows" | "getRowClassName">;
+	/** Style for the grid root, carrying the overlay text as a CSS custom property */
+	rootStyle: React.CSSProperties;
+};
+
+/**
+ * A DevExpress-style new item row: a single non-data row pinned above or below
+ * the data, showing an overlay text until the user starts editing it. The row
+ * lives outside the data set, so sorting, filtering, paging and grouping leave
+ * it alone.
+ *
+ * When editing starts the data object's current index moves to -1, the
+ * framework's new record, so bound forms and child data objects follow. The
+ * entered values are only written to the data object when the row is
+ * committed, exactly like edits to existing rows.
+ */
+export function useAfNewItemRow({
+	apiRef,
+	dataObject,
+	position,
+	disableInsert,
+	pinnedRows: pinnedRowsProp,
+	getRowClassName: getRowClassNameProp,
+}: useAfNewItemRowOptions): AfNewItemRow {
+	let { allowInsert } = usePermissions(dataObject);
+	let enabled = position !== "none" && allowInsert && !disableInsert;
+	// Bumped after a save, so the pinned row is replaced by a blank one
+	let [generation, setGeneration] = useState(0);
+	// The row that was current before editing started, restored when the edit is cancelled
+	let previousIndex = useRef(-1);
+	let wasEditing = useRef(false);
+
+	let row = useMemo(() => {
+		if (!enabled) return null;
+		// `getData(-1)` is a blank record with every field set to null
+		return { ...(dataObject.getData(-1) as Record<string, unknown>), [uid]: NEW_ITEM_ROW_ID, generation };
+	}, [enabled, dataObject, generation]);
+
+	let beginNewRecord = useCallback(() => {
+		if (dataObject.getCurrentIndex() !== -1) {
+			previousIndex.current = dataObject.getCurrentIndex();
+			dataObject.setCurrentIndex(-1);
+		}
+	}, [dataObject]);
+
+	let cancelNewRecord = useCallback(() => {
+		if (dataObject.getCurrentIndex() !== -1) return;
+
+		dataObject.cancelEdit();
+
+		let index = previousIndex.current;
+		if (index >= 0 && index < dataObject.getDataLength()) {
+			dataObject.setCurrentIndex(index);
+		}
+	}, [dataObject]);
+
+	let start = useCallback(() => {
+		let api = apiRef.current;
+		if (!enabled || !api) return false;
+
+		let visibleColumns = gridVisibleColumnDefinitionsSelector(apiRef);
+		let firstEditable = visibleColumns.find((c) => c.editable === true) ?? visibleColumns[0];
+		if (!firstEditable) return false;
+
+		api.setCellFocus(NEW_ITEM_ROW_ID, firstEditable.field);
+		if (api.getRowMode(NEW_ITEM_ROW_ID) !== GridRowModes.Edit) {
+			api.startRowEditMode({ id: NEW_ITEM_ROW_ID, fieldToFocus: firstEditable.field });
+		}
+
+		return true;
+	}, [apiRef, enabled]);
+
+	let save = useCallback(
+		async (record: Record<string, unknown>) => {
+			beginNewRecord();
+
+			for (let field in record) {
+				let value = record[field];
+				if (value === undefined || value === null) continue;
+				if (dataObject.getFields(field)) {
+					setDataObjectField(dataObject, field, value);
+				}
+			}
+
+			let blankRow = { ...(dataObject.getData(-1) as Record<string, unknown>), [uid]: NEW_ITEM_ROW_ID };
+
+			if (!dataObject.isDirty()) {
+				// Nothing was entered, so committing the row is the same as cancelling it
+				cancelNewRecord();
+				return blankRow;
+			}
+
+			let focusBefore = gridFocusCellSelector(apiRef);
+
+			try {
+				await dataObject.endEdit();
+			} catch (error) {
+				// The framework keeps a failed new record in storage as an unsaved row.
+				// The grid keeps the draft in the new item row instead, so the unsaved
+				// row is dropped and the current index goes back to the new record.
+				if (dataObject.getCurrentIndex() >= 0 && dataObject.isNewRecord(dataObject.getCurrentIndex())) {
+					dataObject.cancelEdit();
+				}
+				// Not through `beginNewRecord`, which would record the row the framework
+				// landed on as the one to restore on cancel
+				dataObject.setCurrentIndex(-1);
+				throw error;
+			}
+
+			setGeneration((g) => g + 1);
+
+			// The created row is the current row now; move the focus there once the
+			// grid has rendered it, so the user can keep working from where it landed.
+			let createdIndex = dataObject.getCurrentIndex();
+			if (createdIndex >= 0 && focusBefore) {
+				let createdRow = dataObject.getData(createdIndex) as any;
+				let createdId: GridRowId = createdRow[uid];
+				setTimeout(() => {
+					let api = apiRef.current;
+					if (!api || !api.getRow(createdId)) return;
+					let rowIndex = api.getRowIndexRelativeToVisibleRows(createdId);
+					if (rowIndex >= 0) api.scrollToIndexes({ rowIndex });
+					api.setCellFocus(createdId, focusBefore.field);
+				});
+			}
+
+			return blankRow;
+		},
+		[apiRef, dataObject, beginNewRecord, cancelNewRecord],
+	);
+
+	useEffect(() => {
+		if (!enabled) return;
+
+		// Moves the data object to the new record when editing starts, whether the
+		// user started it or `start` did, and discards it when the edit is cancelled.
+		// A commit goes through `save` instead.
+		const handleRowModesModelChange: GridEventListener<"rowModesModelChange"> = (model) => {
+			let entry = model[NEW_ITEM_ROW_ID] as { mode: GridRowModes; ignoreModifications?: boolean } | undefined;
+			let isEditing = entry?.mode === GridRowModes.Edit;
+
+			if (isEditing && !wasEditing.current) {
+				beginNewRecord();
+			} else if (!isEditing && wasEditing.current && entry?.ignoreModifications === true) {
+				// Deferred until the grid has left edit mode and put the focus back on the
+				// cell, so that a bound current index moves the focus from a mounted cell
+				// instead of from an editor that is about to be unmounted.
+				setTimeout(cancelNewRecord);
+			}
+
+			wasEditing.current = isEditing;
+		};
+
+		return apiRef.current?.subscribeEvent("rowModesModelChange", handleRowModesModelChange);
+	}, [apiRef, enabled, beginNewRecord, cancelNewRecord]);
+
+	let pinnedRows = useMemo<GridPinnedRowsProp | undefined>(() => {
+		if (!row) return pinnedRowsProp;
+
+		// The new item row sits next to the data, inside any rows the consumer pinned
+		return {
+			top: position === "top" ? [...(pinnedRowsProp?.top ?? []), row] : pinnedRowsProp?.top,
+			bottom: position === "bottom" ? [row, ...(pinnedRowsProp?.bottom ?? [])] : pinnedRowsProp?.bottom,
+		};
+	}, [row, position, pinnedRowsProp]);
+
+	let getRowClassName = useCallback<NonNullable<DataGridProps["getRowClassName"]>>(
+		(params) => {
+			let className = getRowClassNameProp?.(params) ?? "";
+			return params.id === NEW_ITEM_ROW_ID ? `${className} ${NEW_ITEM_ROW_CLASS}`.trim() : className;
+		},
+		[getRowClassNameProp],
+	);
+
+	let rootStyle = useMemo<React.CSSProperties>(
+		() =>
+			({
+				// Read by the overlay's `content`, so the text is localized without a DOM node
+				"--AfGrid-newItemRowText": JSON.stringify(getLocalizedString("Click here to add a new row")),
+			}) as React.CSSProperties,
+		[],
+	);
+
+	useEffect(() => {
+		if (apiRef.current) {
+			(apiRef.current as AfGridApi).startNewItemRow = start;
+		}
+	}, [apiRef, start]);
+
+	return {
+		enabled,
+		save,
+		start,
+		gridProps: enabled
+			? { pinnedRows, getRowClassName }
+			: { pinnedRows: pinnedRowsProp, getRowClassName: getRowClassNameProp },
+		rootStyle,
+	};
+}

package/src/grid/useAfPagination.ts

@@ -1,53 +1,53 @@
-import type { DataGridPremiumProps, GridPaginationModel } from "@mui/x-data-grid-premium";
-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<DataGridPremiumProps> {
-	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 {};
-}
+import type { DataGridPremiumProps, GridPaginationModel } from "@mui/x-data-grid-premium";
+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<DataGridPremiumProps> {
+	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 {};
+}