@olenbetong/appframe-ds 0.8.0 → 0.9.1

package/src/grid/filter.ts

@@ -0,0 +1,78 @@
+import {
+	GridCellParams,
+	type GridColDef,
+	GridFilterInputMultipleValue,
+	GridFilterInputValue,
+	type GridFilterItem,
+	type GridFilterOperator,
+	getGridBooleanOperators,
+	getGridDateOperators,
+	getGridNumericOperators,
+	getGridSingleSelectOperators,
+	getGridStringOperators,
+} from "@mui/x-data-grid-pro";
+import { getLocalizedString } from "@olenbetong/appframe-core";
+
+const stringOperators = getGridStringOperators();
+const numericOperators = getGridNumericOperators();
+const booleanOperators = getGridBooleanOperators();
+const dateOperators = getGridDateOperators();
+const singleSelectOperators = getGridSingleSelectOperators();
+
+export const operators = {
+	string: stringOperators,
+	number: numericOperators,
+	boolean: booleanOperators,
+	date: dateOperators,
+	dateTime: dateOperators,
+	singleSelect: singleSelectOperators,
+};
+
+const likeOperator: GridFilterOperator = {
+	label: getLocalizedString("like"),
+	headerLabel: getLocalizedString("Like"),
+	value: "like",
+	InputComponent: GridFilterInputValue,
+	getApplyFilterFn: (filterItem: GridFilterItem, column: GridColDef) => {
+		if (!filterItem.field || !filterItem.value || !filterItem.operator) {
+			return null;
+		}
+
+		// only supported by server side filtering
+		return (): boolean => true;
+	},
+};
+
+const notLikeOperator: GridFilterOperator = {
+	label: getLocalizedString("not like"),
+	headerLabel: getLocalizedString("Not like"),
+	value: "notLike",
+	InputComponent: GridFilterInputValue,
+	getApplyFilterFn: (filterItem: GridFilterItem, column: GridColDef) => {
+		if (!filterItem.field || !filterItem.value || !filterItem.operator) {
+			return null;
+		}
+
+		// only supported by server side filtering
+		return (): boolean => true;
+	},
+};
+
+const notInListOperator: GridFilterOperator = {
+	label: getLocalizedString("is none of"),
+	headerLabel: getLocalizedString("Is none of"),
+	value: "isNoneOf",
+	InputComponent: GridFilterInputMultipleValue,
+	getApplyFilterFn: (filterItem: GridFilterItem, column: GridColDef) => {
+		if (!filterItem.field || !filterItem.value || !filterItem.operator) {
+			return null;
+		}
+
+		// only supported by server side filtering
+		return (): boolean => true;
+	},
+};
+
+stringOperators.push(notInListOperator);
+stringOperators.push(likeOperator);
+stringOperators.push(notLikeOperator);

package/src/grid/formatters.ts

@@ -0,0 +1,48 @@
+const culture = globalThis.af?.userSession?.culture ?? "en-GB";
+export const dateFormatter = new Intl.DateTimeFormat(culture, {
+	year: "numeric",
+	month: "2-digit",
+	day: "2-digit",
+	timeZone: "utc",
+});
+
+export const dateTimeFormatter = new Intl.DateTimeFormat(culture, {
+	year: "numeric",
+	month: "2-digit",
+	day: "2-digit",
+	hour: "2-digit",
+	minute: "2-digit",
+	second: "2-digit",
+	timeZone: "utc",
+});
+
+export const intFormatter = new Intl.NumberFormat(culture, {
+	maximumFractionDigits: 0,
+});
+
+export const decFormatter = new Intl.NumberFormat(culture, {
+	maximumFractionDigits: 2,
+	minimumFractionDigits: 2,
+});
+
+export const intValueFormatter = (value: any) =>
+	value && typeof value === "number" ? intFormatter.format(value) : value;
+
+export const decimalValueFormatter = (value: any) =>
+	value && typeof value === "number" ? decFormatter.format(value) : value;
+
+export function dateValueFormatter(value: any) {
+	if (value && value instanceof Date) {
+		return dateFormatter.format(value);
+	}
+
+	return value;
+}
+
+export function dateTimeValueFormatter(value: any) {
+	if (value && value instanceof Date) {
+		return dateTimeFormatter.format(value);
+	}
+
+	return value;
+}

package/src/grid/index.css

@@ -0,0 +1,187 @@
+.AfGrid-root {
+	height: 100%;
+}
+
+.AfGrid-loading {
+	display: flex;
+	align-items: center;
+	justify-content: center;
+	height: 100%;
+}
+
+.AfGrid-toolbar {
+	display: flex;
+	flex-wrap: wrap;
+	gap: var(--ds-size-1, 0.25rem);
+	align-items: center;
+	padding: var(--ds-size-1, 0.25rem);
+}
+
+.MuiDataGrid-headerFilterRow .MuiDataGrid-columnHeader.AfGrid-headerCell {
+	align-items: center;
+	padding-block: 0;
+	background-color: var(--ds-color-neutral-surface-tinted, rgb(0 0 0 / 2%));
+
+	&:focus-within {
+		background-color: var(--ds-color-neutral-surface-hover, rgb(0 0 0 / 4%));
+	}
+}
+
+.AfGrid-errorOverlay {
+	position: absolute;
+	inset-inline: 0;
+	top: var(--DataGrid-topContainerHeight);
+	z-index: 10;
+	padding: var(--ds-size-1, 0.25rem) var(--ds-size-2, 0.5rem);
+	pointer-events: none;
+}
+
+.AfGrid-errorAlert {
+	display: flex;
+	gap: var(--ds-size-2, 0.5rem);
+	align-items: center;
+	justify-content: space-between;
+	pointer-events: auto;
+}
+
+.AfGrid-snackbar {
+	position: fixed;
+	top: var(--ds-size-4, 1rem);
+	left: 50%;
+	z-index: 1400;
+	transform: translateX(-50%);
+}
+
+.AfGrid-columnsPanelSearch {
+	display: flex;
+	flex-direction: column;
+	gap: var(--ds-size-3, 0.75rem);
+}
+
+.AfGrid-columnsPanelList {
+	display: flex;
+	flex-direction: column;
+	gap: var(--ds-size-1, 0.25rem);
+	max-height: 50vh;
+	margin: 0;
+	padding: 0;
+	overflow-y: auto;
+	list-style: none;
+}
+
+.AfGrid-columnsPanelItem {
+	padding: var(--ds-size-1, 0.25rem);
+	border-radius: var(--ds-border-radius-md, 4px);
+	cursor: grab;
+}
+
+.AfGrid-columnsPanelItem:hover {
+	background-color: var(--ds-color-neutral-surface-hover, rgb(0 0 0 / 4%));
+}
+
+.AfGrid-columnsPanelActions {
+	display: flex;
+	gap: var(--ds-size-2, 0.5rem);
+	justify-content: flex-end;
+}
+
+/* Header filters */
+
+/*
+ * The header filter row is short, so the input drops the border radius and any
+ * vertical padding and fills the cell instead.
+ *
+ * The height has to be clamped to the cell. Designsystemet gives the input a
+ * min-height taller than the row MUI reserves, and a cell that grows past that
+ * stretches the row without MUI knowing — leaving the cells that hold no input
+ * (unfilterable columns such as `actions`) short of the row they sit in.
+ */
+.AfGrid-headerFilterInput.ObInputAdornments-root {
+	--obInputAdornments-padding: 0;
+	--obInputAdornments-gap: 0;
+
+	block-size: 100%;
+	min-block-size: 0;
+	background-color: transparent;
+	border-color: transparent;
+	border-radius: 0;
+}
+
+.AfGrid-headerFilterInput .ObInputAdornments-field {
+	min-block-size: 0;
+}
+
+.AfGrid-headerFilterInput.ObInputAdornments-root:hover:not(:focus-within) {
+	border-color: transparent;
+}
+
+.AfGrid-headerFilterInput .ObInputAdornments-field {
+	padding-inline: var(--ds-size-1, 0.25rem);
+	text-overflow: ellipsis;
+}
+
+/* Read-only cells show a summary, so the text cursor would be misleading */
+.AfGrid-headerFilterInput .ObInputAdornments-field:read-only {
+	cursor: pointer;
+	color: var(--ds-color-neutral-text-subtle, #68707c);
+}
+
+/*
+ * The header filter row is denser than a normal form row, so the buttons and
+ * their icons are stepped down from the default `sm` size.
+ */
+.AfGrid-headerFilterInput .ds-button {
+	--dsc-button-size: var(--ds-size-7, 1.5rem);
+	--ds-icon-size: var(--ds-size-4, 1rem);
+
+	min-height: 0;
+	padding: 0;
+}
+
+/* The funnel is highlighted while the column has criteria, as in the toolbar */
+.AfGrid-headerFilterButton[data-active] {
+	--dsc-button-color: var(--ds-color-accent-base-default);
+	--dsc-button-color--hover: var(--ds-color-accent-base-hover);
+}
+
+.AfGrid-headerFilterEmpty {
+	display: block;
+	inline-size: 100%;
+	block-size: 100%;
+}
+
+/*
+ * The panel is a native popover, so it renders in the top layer and is not
+ * clipped by the grid's own overflow. `display` must stay scoped to
+ * `:popover-open`, or it overrides the user agent rule that hides a closed
+ * popover and the panel is always visible.
+ */
+.AfGrid-headerFilterPanel.ds-popover {
+	--dsc-popover-max-width: none;
+	--dsc-popover-padding: var(--ds-size-3, 0.75rem);
+
+	inline-size: 22rem;
+	max-inline-size: 90vw;
+	block-size: 26rem;
+	max-block-size: 80vh;
+}
+
+/*
+ * A column with many distinct values needs a taller list than one with a
+ * handful, so the panel is resizable and the panel body follows its height.
+ * `resize` needs a non-visible overflow to take effect.
+ */
+.AfGrid-headerFilterPanel.ds-popover:popover-open {
+	display: flex;
+	flex-direction: column;
+	gap: var(--ds-size-3, 0.75rem);
+	min-inline-size: 18rem;
+	min-block-size: 16rem;
+	overflow: auto;
+	resize: both;
+}
+
+.AfGrid-headerFilterPanel .ObFieldFilterPanel-root {
+	flex: 1 1 auto;
+	min-block-size: 0;
+}

package/src/grid/index.tsx

@@ -0,0 +1,376 @@
+import "./index.css";
+
+import { Alert } from "@digdir/designsystemet-react";
+import {
+	DataGridPro as DataGrid,
+	type DataGridProProps as DataGridProps,
+	type GridApi,
+	type GridFilterModel,
+	useGridApiRef,
+} from "@mui/x-data-grid-pro";
+import { getLocalizedString } from "@olenbetong/appframe-core";
+import type { DataObject } from "@olenbetong/appframe-data";
+import { DataObjectProvider, useLoading } from "@olenbetong/appframe-react";
+
+import clsx from "clsx";
+import { useEffect, useMemo, useState } from "react";
+import { FilterBuilder } from "../filter/index.js";
+import { AfGridColumnsPanel } from "./AfGridColumnsPanel.js";
+import { type AfGridContextValue, AfGridContextProvider } from "./AfGridContext.js";
+import { AfGridError } from "./AfGridError.js";
+import { registerLicense } from "./license.js";
+import { AF_GRID_LOCALE_TEXT } from "./localization.js";
+import { dsBaseSlots } from "./slots/index.js";
+import { AfGridThemeProvider } from "./theme.js";
+import {
+	type AfExcelExportOptions,
+	AfGridExcelExportMenuItem,
+	type AfGridExcelExportOptions,
+	AfGridToolbar,
+	AfGridToolbarExcelExportButton,
+	GridToolbarAddButton,
+	GridToolbarAddIfAllowedButton,
+	GridToolbarColumnsButton,
+	GridToolbarContainer,
+	GridToolbarFilterButton,
+	GridToolbarMoreOptionsButton,
+	GridToolbarRefreshButton,
+	GridToolbarResetLayoutButton,
+} from "./Toolbar.js";
+import type { AfGridColumn } from "./useAfColumns.js";
+import { type AfGridColDef, useAfColumns } from "./useAfColumns.js";
+import { useAfCurrentIndex } from "./useAfCurrentIndex.js";
+import { useAfData } from "./useAfData.js";
+import { useAfFilterFields } from "./useAfFilterFields.js";
+import { useAfFilter } from "./useAfFilter.js";
+import { type AfGridApi, useAfGridApi } from "./useAfGridApi.js";
+import { useAfKeyBindings } from "./useAfKeyBindings.js";
+import { useAfPagination } from "./useAfPagination.js";
+import {
+	isPersistedStateLoaded,
+	type StatePersistenceConfig,
+	settingsLoaded,
+	useAfPersistedState,
+} from "./useAfPersistedState.js";
+import { useAfRowEditModel } from "./useAfRowEditModel.js";
+import { useAfSortModel } from "./useAfSortModel.js";
+
+export * from "./formatters.js";
+export * as MuiDataGrid from "@mui/x-data-grid-pro";
+
+registerLicense();
+
+/**
+ * The grid's criteria live in a `FilterTree` owned by `useAfFilter`, not in
+ * MUI's filter model, so the model is always empty. It is hoisted so the
+ * reference is stable and the grid does not treat it as a change.
+ */
+const EMPTY_FILTER_MODEL: GridFilterModel = { items: [] };
+
+const privSysColumns: AfGridColDef[] = [
+	{ field: "PrimKey", editable: false, hide: true },
+	{ field: "Created", editable: false, hide: true },
+	{ field: "CreatedBy", editable: false, hide: true },
+	{ field: "Updated", editable: false, hide: true },
+	{ field: "UpdatedBy", editable: false, hide: true },
+];
+
+export const systemColumns = {
+	[Symbol.iterator]: () => privSysColumns[Symbol.iterator](),
+	PrimKey: privSysColumns[0],
+	Created: privSysColumns[1],
+	CreatedBy: privSysColumns[2],
+	Updated: privSysColumns[3],
+	UpdatedBy: privSysColumns[4],
+};
+
+export type { AfExcelExportOptions, AfGridApi, AfGridColDef, AfGridColumn, AfGridExcelExportOptions };
+
+export {
+	AF_GRID_LOCALE_TEXT,
+	AfGridColumnsPanel,
+	AfGridExcelExportMenuItem,
+	AfGridThemeProvider,
+	AfGridToolbar,
+	AfGridToolbarExcelExportButton,
+	GridToolbarAddButton,
+	GridToolbarAddIfAllowedButton,
+	GridToolbarColumnsButton,
+	GridToolbarContainer,
+	GridToolbarFilterButton,
+	GridToolbarMoreOptionsButton,
+	GridToolbarRefreshButton,
+	GridToolbarResetLayoutButton,
+	useAfColumns,
+	useAfCurrentIndex,
+	useAfData,
+	useAfFilter,
+	useAfFilterFields,
+	useAfPagination,
+	useAfPersistedState,
+	useAfRowEditModel,
+	useAfSortModel,
+};
+
+export type AfGridProps = {
+	apiRef?: React.RefObject<GridApi>;
+	/**
+	 * If set to true, the grid will automatically load data if the data object has not
+	 * been loaded previously.
+	 */
+	autoLoad?: boolean;
+	/**
+	 * Bind the focused/selected row to the current index in the data object.
+	 * Useful if you want child data to load as the user navigates the grid.
+	 */
+	bindIndex?: boolean;
+	columns: AfGridColumn[];
+	dataObject: DataObject<any>;
+	/**
+	 * The layout version of the grid. Persisted grid state will only be restored
+	 * if the version matches.
+	 */
+	layoutVersion?: string | number;
+	/**
+	 * Field that contains a unique identifier for each row. Defaults to PrimKey.
+	 */
+	idField?: string;
+	/**
+	 * A function that can be used to transform the data object data before it is
+	 * passed to the grid, for example to create summary rows.
+	 */
+	getData?: (data: Readonly<Readonly<any>[]>) => any[];
+	/**
+	 * Override the data object permission, and remove the delete button from the default row actions
+	 */
+	disableDelete?: boolean;
+	/**
+	 * Override the data object permission, and remove the edit button from the default row actions
+	 */
+	disableEdit?: boolean;
+	/**
+	 * Override the data object permission, and remove the Add button from the default toolbar.
+	 */
+	disableInsert?: boolean;
+	/**
+	 * Use to disable server sorting. Required for example when using row grouping.
+	 */
+	disableServerSorting?: boolean;
+	/**
+	 * The view the filter builder saves and loads saved filters for, and converts
+	 * its filter against. Without it the filter builder can still be used, but
+	 * saved filters are unavailable.
+	 */
+	filterViewName?: string;
+	/**
+	 * A unique ID used to persist the grid state. It is better to use the layoutVersion
+	 * property if you would like to ignore any previously persisted state, as changing
+	 * this property will leave orphan records for the previous id in the Indexed DB
+	 * grid layout store.
+	 */
+	id: string;
+	/**
+	 * Object almost matching the grid state, but with all values as booleans. This
+	 * is used to configure which properties should be persisted.
+	 */
+	persistenceModel?: StatePersistenceConfig;
+} & Omit<
+	DataGridProps,
+	| "apiRef"
+	| "columns"
+	| "loading"
+	| "rows"
+	| "filterMode"
+	| "filterModel"
+	| "onFilterModelChange"
+	| "sortingMode"
+	| "sortModel"
+	| "onSortModelChange"
+	| "editRowsModel"
+	| "editMode"
+	| "onRowEditCommit"
+	| "onEditRowsModelChange"
+	| "pagination"
+	| "paginationMode"
+	| "pageSize"
+	| "rowCount"
+	| "rowsPerPageOptions"
+	| "onPageChange"
+	| "onPageSizeChange"
+>;
+
+// This wrapper component prevents the actual grid from rendering until the persisted state has been loaded.
+// This is to prevent the grid from flickering when the persisted state is restored, plus the grid sometimes
+// resets the column order if not provided in the initial state
+export function AfGrid(props: AfGridProps) {
+	let [loaded, setLoaded] = useState(isPersistedStateLoaded());
+
+	useEffect(() => {
+		settingsLoaded.then(() => setLoaded(true));
+	}, []);
+
+	return (
+		<AfGridThemeProvider>
+			{loaded ? <AfGrid_ {...props} /> : <div className="AfGrid-loading">{getLocalizedString("Loading...")}</div>}
+		</AfGridThemeProvider>
+	);
+}
+
+function AfGrid_(props: AfGridProps) {
+	let {
+		autoLoad = false,
+		apiRef: apiRefProp,
+		bindIndex,
+		columns: columnsProp,
+		disableServerSorting,
+		disableInsert,
+		disableDelete,
+		disableEdit = false,
+		dataObject,
+		filterViewName,
+		layoutVersion = 0,
+		getData,
+		idField = "PrimKey",
+		id,
+		persistenceModel,
+		initialState,
+		...other
+	} = props;
+	let apiRefPriv = useGridApiRef();
+	let apiRef = apiRefProp ?? apiRefPriv;
+	useAfGridApi(props, apiRef);
+	let loading = useLoading(dataObject);
+	let paging = useAfPagination(dataObject);
+	let sortModel = useAfSortModel({
+		dataObject,
+		columns: columnsProp,
+		disableServerSorting,
+	});
+	let gridFilter = useAfFilter({ autoLoad, dataObject, id });
+	let [snackbar, setSnackbar] = useState<string | null>(null);
+	let [isFilterBuilderOpen, setFilterBuilderOpen] = useState(false);
+	let [isColumnsPanelOpen, setColumnsPanelOpen] = useState(false);
+	let editProps = useAfRowEditModel({ dataObject, disableEdit, idField, apiRef });
+	let data = useAfData(dataObject, { getData });
+	useAfCurrentIndex({
+		apiRef,
+		dataObject,
+		idField,
+		enabled: !!bindIndex,
+	});
+	let columns = useAfColumns({
+		apiRef,
+		dataObject,
+		disableEdit,
+		disableDelete,
+		columnsProp,
+		idField,
+	});
+	let filterFields = useAfFilterFields(dataObject, columnsProp);
+
+	let initialState_ = useAfPersistedState({
+		apiRef,
+		columns: columnsProp,
+		id,
+		layoutVersion,
+		persistenceModel,
+		initialState,
+	});
+
+	let keyEvents = useAfKeyBindings({ apiRef, dataObject });
+
+	useEffect(() => {
+		if (!snackbar) return;
+
+		let timeout = setTimeout(() => setSnackbar(null), 6000);
+
+		return () => clearTimeout(timeout);
+	}, [snackbar]);
+
+	let gridContext = useMemo<AfGridContextValue>(
+		() => ({
+			id,
+			apiRef,
+			filterFields,
+			...gridFilter,
+			openFilterBuilder: () => setFilterBuilderOpen(true),
+			openColumnsPanel: () => setColumnsPanelOpen(true),
+		}),
+		[id, apiRef, filterFields, gridFilter],
+	);
+
+	return (
+		<DataObjectProvider dataObject={dataObject}>
+			<AfGridContextProvider value={gridContext}>
+				<div className="AfGrid-root" {...keyEvents} tabIndex={-1}>
+					<DataGrid
+						apiRef={apiRef}
+						rows={data}
+						columns={columns}
+						loading={loading}
+						getRowId={(row) => row[af.data.uid] ?? row[idField]}
+						{...editProps}
+						/*
+						 * Our own filter tree drives the data object, so MUI never
+						 * sees a filter model. The header filter cells are replaced
+						 * by `renderHeaderFilter` on every column.
+						 */
+						filterMode="server"
+						filterModel={EMPTY_FILTER_MODEL}
+						{...sortModel}
+						headerFilters
+						{...paging}
+						showToolbar
+						{...other}
+						localeText={{ ...other.localeText, ...AF_GRID_LOCALE_TEXT }}
+						slots={{
+							...dsBaseSlots,
+							toolbar: () => <AfGridToolbar disableInsert={disableInsert} />,
+							...other.slots,
+						}}
+						initialState={initialState_}
+						slotProps={{
+							...other.slotProps,
+							headerFilterCell: {
+								...other.slotProps?.headerFilterCell,
+								headerClassName: clsx(other.slotProps?.headerFilterCell?.headerClassName, "AfGrid-headerCell"),
+								showRightBorder: true,
+							},
+						}}
+						onProcessRowUpdateError={(error) => {
+							other.onProcessRowUpdateError?.(error);
+							let message = "message" in (error as any) ? (error as any).message : String(error);
+							setSnackbar(message);
+						}}
+					/>
+				</div>
+				<AfGridError apiRef={apiRef} dataObject={dataObject} />
+				{isColumnsPanelOpen && <AfGridColumnsPanel open onClose={() => setColumnsPanelOpen(false)} />}
+				<FilterBuilder
+					variant="dialog"
+					open={isFilterBuilderOpen}
+					onClose={() => setFilterBuilderOpen(false)}
+					fields={filterFields}
+					viewName={filterViewName}
+					dataObject={dataObject}
+					/*
+					 * The builder edits the same named slot and the same tree as the
+					 * header filters, so a criterion added in one shows up in the
+					 * other. Applying writes the slot directly, which skips the
+					 * header filters' debounce.
+					 */
+					slotName={id}
+					value={gridFilter.filter}
+					onChange={gridFilter.setFilter}
+				/>
+				{!!snackbar && (
+					<div className="AfGrid-snackbar">
+						<Alert data-color="danger" data-size="sm" onClick={() => setSnackbar(null)}>
+							{snackbar}
+						</Alert>
+					</div>
+				)}
+			</AfGridContextProvider>
+		</DataObjectProvider>
+	);
+}