@olenbetong/appframe-ds 1.4.0 → 1.5.0

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # @olenbetong/appframe-ds
 
+## 1.5.0
+
+### Minor Changes
+
+- 1cae272: AfGrid takes `getRowActions`: extra buttons for each row in the grid's own actions column, after edit and delete, with the same keyboard navigation. An actions column of the app's own replaced the built-in one.
+
+### Patch Changes
+
+- 1cae272: AfGrid's row action buttons (edit, delete, save, cancel and any from `getRowActions`) have their labels as accessible names again; the icon button slot overwrote them with nothing. Starting edit with the edit button now focuses the first editable cell, and save and cancel leave the focus on the row's actions cell instead of the page.
+- 1cae272: AfGrid keeps the keyboard focus on the cell when a row or cell leaves edit mode. Chrome dropped it to the page after Escape (or saving), so the arrow keys scrolled the page instead of moving between cells.
+
+## 1.4.1
+
+### Patch Changes
+
+- b0630e5: Dialog motion: the opening transition now also plays for `ob-dialog-motion` elements (the app menu). Their starting style was a separate, less specific rule than the open state and lost to it, so they appeared without the transition and only faded on close.
+
 ## 1.4.0
 
 ### Minor Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@olenbetong/appframe-ds",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "Components that bind Designsystemet components to Appframe data objects",
   "type": "module",
   "types": "./es/index.d.ts",

package/src/grid/index.tsx

@@ -10,6 +10,7 @@ import {
 	type GridApi,
 	type GridFilterModel,
 	type GridGroupNode,
+	type GridRowParams,
 	useGridApiRef,
 } from "@mui/x-data-grid-premium";
 import { type DataObject, uid } from "@olenbetong/appframe-data";
@@ -41,7 +42,7 @@ import {
 	GridToolbarResetLayoutButton,
 } from "./Toolbar.js";
 import type { AfGridColumn } from "./useAfColumns.js";
-import { type AfGridColDef, useAfColumns } from "./useAfColumns.js";
+import { type AfGridColDef, type AfGridRowAction, useAfColumns } from "./useAfColumns.js";
 import { useAfCurrentIndex } from "./useAfCurrentIndex.js";
 import { useAfData } from "./useAfData.js";
 import { useAfFilterFields } from "./useAfFilterFields.js";
@@ -56,6 +57,7 @@ import {
 	settingsLoaded,
 	useAfPersistedState,
 } from "./useAfPersistedState.js";
+import { useAfKeepFocusAfterEdit } from "./useAfKeepFocusAfterEdit.js";
 import { useAfRowEditModel } from "./useAfRowEditModel.js";
 import { useAfRowGrouping } from "./useAfRowGrouping.js";
 import { useAfServerAggregation } from "./useAfServerAggregation.js";
@@ -103,6 +105,7 @@ export type {
 	AfGridColumn,
 	AfGridExcelExportOptions,
 	AfGridNewItemRowPosition,
+	AfGridRowAction,
 };
 export type { AfGridGrouping, AfGridGroupingProps } from "./useAfRowGrouping.js";
 
@@ -156,6 +159,14 @@ export type AfGridProps = {
 	bindIndex?: boolean;
 	columns: AfGridColumn[];
 	dataObject: DataObject<any>;
+	/**
+	 * Extra buttons for each row in the grid's own actions column, after edit and delete. They
+	 * show while the row is not being edited, and the column is added for them even when the data
+	 * object allows neither updates nor deletes. An actions column of your own replaces that
+	 * column, built-in actions included, and loses their keyboard navigation; use this instead.
+	 * Keep the function stable (`useCallback`): a new one rebuilds the columns.
+	 */
+	getRowActions?: (params: GridRowParams) => AfGridRowAction[];
 	/**
 	 * The layout version of the grid. Persisted grid state will only be restored
 	 * if the version matches.
@@ -282,6 +293,7 @@ function AfGrid_(props: AfGridProps) {
 		apiRef: apiRefProp,
 		bindIndex,
 		columns: columnsProp,
+		getRowActions,
 		disableServerSorting,
 		disableInsert,
 		disableDelete,
@@ -336,6 +348,7 @@ function AfGrid_(props: AfGridProps) {
 	let [isFilterBuilderOpen, setFilterBuilderOpen] = useState(false);
 	let [isColumnsPanelOpen, setColumnsPanelOpen] = useState(false);
 	let editProps = useAfRowEditModel({ dataObject, disableEdit, idField, apiRef, newItemRow });
+	useAfKeepFocusAfterEdit(apiRef);
 	let data = useAfData(dataObject, { getData });
 	useAfCurrentIndex({
 		apiRef,
@@ -351,6 +364,7 @@ function AfGrid_(props: AfGridProps) {
 		disableDelete,
 		columnsProp,
 		idField,
+		getRowActions,
 	});
 	let filterFields = useAfFilterFields(dataObject, columnsProp);
 

package/src/grid/slots/index.tsx

@@ -100,8 +100,15 @@ function BaseButton(props: GridSlotProps["baseButton"]) {
 function BaseIconButton(props: GridSlotProps["baseIconButton"]) {
 	let { children, size, label, color: _color, edge: _edge, touchRippleRef: _touchRippleRef, ...other } = props;
 
+	// `GridActionsCellItem` names its button through `aria-label`, not `label`; keep it
 	return (
-		<Button {...(other as any)} icon variant="tertiary" data-size={dsSize(size)} aria-label={label}>
+		<Button
+			{...(other as any)}
+			icon
+			variant="tertiary"
+			data-size={dsSize(size)}
+			aria-label={label ?? (other as any)["aria-label"]}
+		>
 			{children}
 		</Button>
 	);

package/src/grid/slots/slots.test.tsx

@@ -4,6 +4,21 @@ import { afterEach, describe, expect, it, vi } from "vitest";
 import { dsBaseSlots } from "./index.js";
 
 const BaseSkeleton = dsBaseSlots.baseSkeleton as React.ComponentType<Record<string, unknown>>;
+const BaseIconButton = dsBaseSlots.baseIconButton as React.ComponentType<Record<string, unknown>>;
+
+describe("baseIconButton", () => {
+	it("keeps the aria-label GridActionsCellItem names its button with", () => {
+		let { getByRole } = render(<BaseIconButton aria-label="Edit">x</BaseIconButton>);
+
+		expect(getByRole("button")).toHaveAttribute("aria-label", "Edit");
+	});
+
+	it("prefers the label prop", () => {
+		let { getByRole } = render(<BaseIconButton label="Save">x</BaseIconButton>);
+
+		expect(getByRole("button")).toHaveAttribute("aria-label", "Save");
+	});
+});
 
 describe("baseSkeleton", () => {
 	afterEach(() => {

package/src/grid/useAfColumns.tsx

@@ -15,6 +15,7 @@ import {
 	type GridRowParams,
 	getAggregationFooterRowIdFromGroupId,
 	gridEditRowsStateSelector,
+	gridVisibleColumnDefinitionsSelector,
 	useGridApiContext,
 	useGridSelector,
 } from "@mui/x-data-grid-premium";
@@ -244,6 +245,21 @@ const GridActionItem = React.forwardRef<
 });
 
 export type AfGridColumn = string | AfGridColDef;
+
+/**
+ * An extra button in the grid's actions column, next to edit and delete. Shown only while the row
+ * is not being edited, and reached with the arrow keys like the built-in actions.
+ */
+export type AfGridRowAction = {
+	key: string;
+	icon: React.ReactElement;
+	/** The button's accessible name and tooltip, and its text in the overflow menu. */
+	label: string;
+	onClick: () => void;
+	disabled?: boolean;
+	/** Puts the action in the column's overflow menu instead of showing it as a button. */
+	showInMenu?: boolean;
+};
 const muiColumnTypes = ["string", "number", "date", "dateTime", "boolean", "singleSelect", "actions"];
 
 export type useAfColumnsOptions = {
@@ -253,6 +269,7 @@ export type useAfColumnsOptions = {
 	dataObject: DataObject<any>;
 	columnsProp: AfGridColumn[];
 	idField: string;
+	getRowActions?: (params: GridRowParams) => AfGridRowAction[];
 };
 
 export function useAfColumns({
@@ -262,6 +279,7 @@ export function useAfColumns({
 	disableDelete,
 	columnsProp,
 	idField,
+	getRowActions,
 }: useAfColumnsOptions): GridColDef[] {
 	let { allowUpdate, allowDelete } = usePermissions(dataObject);
 
@@ -277,13 +295,26 @@ export function useAfColumns({
 			idField,
 		});
 
+		// The edit, save and cancel buttons disappear as the row changes mode, taking the focus with
+		// them. Editing starts in the first editable column, and leaving edit mode puts the grid's
+		// focus on the row's actions cell, which `useAfKeepFocusAfterEdit` then restores.
 		const handleEditClick = (id: GridRowId) => (event: React.MouseEvent<any>) => {
 			event.stopPropagation();
-			apiRef.current?.startRowEditMode({ id });
+			let api = apiRef.current;
+			if (!api) return;
+
+			let fieldToFocus = gridVisibleColumnDefinitionsSelector(apiRef).find(
+				(column) => column.editable && column.type !== "actions",
+			)?.field;
+			if (fieldToFocus) {
+				api.setCellFocus(id, fieldToFocus);
+			}
+			api.startRowEditMode({ id, fieldToFocus });
 		};
 
 		const handleSaveClick = (id: GridRowId) => async (event: React.MouseEvent<any>) => {
 			event.stopPropagation();
+			apiRef.current?.setCellFocus(id, "actions");
 			apiRef.current?.stopRowEditMode({ id });
 		};
 
@@ -294,6 +325,7 @@ export function useAfColumns({
 
 		const handleCancelClick = (id: GridRowId) => (event: React.MouseEvent<any>) => {
 			event.stopPropagation();
+			apiRef.current?.setCellFocus(id, "actions");
 			apiRef.current?.stopRowEditMode({ id, ignoreModifications: true });
 
 			const row = apiRef.current?.getRow(id);
@@ -302,12 +334,13 @@ export function useAfColumns({
 			}
 		};
 
-		if (!columns.find((c) => c.type === "actions") && (allowDelete || allowUpdate)) {
+		if (!columns.find((c) => c.type === "actions") && (allowDelete || allowUpdate || getRowActions)) {
 			columns.push({
 				field: "actions",
 				type: "actions",
 				headerName: getLocalizedString("Actions"),
-				getActions: ({ id }: GridRowParams) => {
+				getActions: (params: GridRowParams) => {
+					let { id } = params;
 					// The new item row only exists while inserting is allowed, so its save and
 					// cancel actions do not depend on the update permission, and it has nothing
 					// to edit or delete in view mode.
@@ -339,6 +372,33 @@ export function useAfColumns({
 						return actions;
 					}
 
+					let rowActions = (getRowActions?.(params) ?? []).map(({ key, icon, label, onClick, disabled, showInMenu }) =>
+						showInMenu ? (
+							<GridActionItem
+								key={key}
+								icon={icon}
+								label={label}
+								onClick={onClick}
+								disabled={disabled}
+								showInMenu
+								mode={GridRowModes.View}
+								dataObject={dataObject}
+								rowId={id}
+							/>
+						) : (
+							<GridActionItem
+								key={key}
+								icon={icon}
+								label={label}
+								onClick={onClick}
+								disabled={disabled}
+								mode={GridRowModes.View}
+								dataObject={dataObject}
+								rowId={id}
+							/>
+						),
+					);
+
 					return [
 						<GridActionItem
 							key="edit"
@@ -360,6 +420,7 @@ export function useAfColumns({
 							rowId={id}
 							requireDelete
 						/>,
+						...rowActions,
 						...actions,
 					];
 				},
@@ -367,5 +428,5 @@ export function useAfColumns({
 		}
 
 		return columns;
-	}, [columnsProp, disableDelete, disableEdit, allowUpdate, allowDelete, idField, dataObject, apiRef]);
+	}, [columnsProp, disableDelete, disableEdit, allowUpdate, allowDelete, idField, dataObject, apiRef, getRowActions]);
 }

package/src/grid/useAfKeepFocusAfterEdit.ts

@@ -0,0 +1,64 @@
+import { type GridApi, gridFocusCellSelector } from "@mui/x-data-grid-premium";
+
+import type React from "react";
+import { useEffect } from "react";
+
+/** How long after a row or cell changes mode a focus loss is still blamed on it. */
+const EDIT_STOP_WINDOW_MS = 1000;
+
+/**
+ * Keeps the keyboard focus in the grid when a row or cell enters or leaves edit mode.
+ *
+ * Two things drop the focus to `<body>`, after which the arrow keys scroll the page instead of
+ * moving between cells: when editing stops (Escape, Enter), the grid moves the focus from the
+ * editor back to the cell and Chrome then takes it from that cell with no script involved; and the
+ * edit, save and cancel buttons are removed while they have the focus. This puts the focus back on
+ * the cell the grid's own focus state points at - but only right after a mode change, and only
+ * when the focus was lost from that cell, so a click outside the grid (which clears that state)
+ * keeps the focus where it went.
+ */
+export function useAfKeepFocusAfterEdit(apiRef: React.RefObject<GridApi | null>) {
+	useEffect(() => {
+		let api = apiRef.current;
+		let root = api?.rootElementRef?.current;
+		if (!api || !root) return;
+
+		let lastModeChange = 0;
+		let markModeChange = () => {
+			lastModeChange = Date.now();
+		};
+
+		let handleFocusOut = (event: FocusEvent) => {
+			if (event.relatedTarget || Date.now() - lastModeChange > EDIT_STOP_WINDOW_MS) return;
+			let lostFrom = (event.target as HTMLElement).closest?.<HTMLElement>(".MuiDataGrid-row");
+			if (!lostFrom) return;
+
+			setTimeout(() => {
+				let doc = root.ownerDocument;
+				if (doc.activeElement !== doc.body) return;
+
+				// The focus state may have moved on to another cell of the same row (the save and
+				// cancel buttons move it to the actions cell), so restore whatever it points at.
+				let focused = gridFocusCellSelector(apiRef);
+				if (!focused || String(focused.id) !== lostFrom.dataset.id) return;
+
+				let cell = apiRef.current?.getCellElement(focused.id, focused.field);
+				if (!cell) return;
+
+				let target = cell.querySelector<HTMLElement>('[tabindex="0"]') ?? cell;
+				target.focus({ preventScroll: true });
+			}, 0);
+		};
+
+		let unsubscribers = [
+			api.subscribeEvent("rowModesModelChange", markModeChange),
+			api.subscribeEvent("cellModesModelChange", markModeChange),
+		];
+		root.addEventListener("focusout", handleFocusOut);
+
+		return () => {
+			for (let unsubscribe of unsubscribers) unsubscribe();
+			root.removeEventListener("focusout", handleFocusOut);
+		};
+	}, [apiRef]);
+}

package/src/layout/DialogMotion.css

@@ -45,6 +45,17 @@
 		animation: none;
 		transition-duration: var(--ob-dialog-enter-duration);
 		transition-timing-function: ease-out;
+
+		/*
+		 * Nested so it has exactly this rule's selector. A separate @starting-style rule for
+		 * `.ob-dialog-motion[open]` is less specific than this one, whose `:is()` takes the
+		 * specificity of `.ds-dialog:is(...)`, and loses to it: the dialog then has no
+		 * starting frame and appears without the transition.
+		 */
+		@starting-style {
+			opacity: 0;
+			translate: 0 var(--ob-dialog-offset);
+		}
 	}
 
 	&::backdrop {
@@ -60,18 +71,9 @@
 		opacity: 1;
 		transition-duration: var(--ob-dialog-enter-duration);
 		transition-timing-function: ease-out;
-	}
-}
 
-@starting-style {
-	.ds-dialog:is(:not([data-placement]), [data-placement="center"])[open],
-	.ob-dialog-motion[open] {
-		opacity: 0;
-		translate: 0 var(--ob-dialog-offset);
-	}
-
-	.ds-dialog:is(:not([data-placement]), [data-placement="center"])[open]::backdrop,
-	.ob-dialog-motion[open]::backdrop {
-		opacity: 0;
+		@starting-style {
+			opacity: 0;
+		}
 	}
 }