@olenbetong/appframe-ds 1.11.0 → 1.13.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @olenbetong/appframe-ds
 
+## 1.13.0
+
+### Minor Changes
+
+- 5a5da91: `RouteErrorPage` shows thrown error responses (404, 403, 401, 5xx and others) as a centred status page with an icon, a plain-language heading, the app's own `statusText` when it gives one, and a way out (back, start page or refresh). Only unexpected errors and 5xx responses are reported with `af.common.logError`; unexpected exceptions look as before.
+
+## 1.12.0
+
+### Minor Changes
+
+- 407ab94: AfGrid offers the site assistant tools to read and change its layout, sort, filter and grouping and to read its rows, on pages where the assistant is switched on. New props `assistantLabel` and `disableAssistant`.
+
 ## 1.11.0
 
 ### Minor Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@olenbetong/appframe-ds",
-  "version": "1.11.0",
+  "version": "1.13.0",
   "description": "Components that bind Designsystemet components to Appframe data objects",
   "type": "module",
   "types": "./es/index.d.ts",
@@ -63,8 +63,8 @@
     "@atlaskit/pragmatic-drag-and-drop": "4.0.0",
     "@atlaskit/pragmatic-drag-and-drop-hitbox": "3.0.0",
     "@base-ui/react": "1.9.0",
-    "@olenbetong/appframe-core": "^2.16.0",
-    "@olenbetong/appframe-data": "^1.10.0",
+    "@olenbetong/appframe-core": "^2.16.1",
+    "@olenbetong/appframe-data": "^1.10.3",
     "@olenbetong/appframe-react": "^2.2.8",
     "clsx": "^2.1.1",
     "dockview-react": "8.8.3",
@@ -73,7 +73,7 @@
     "react": "19.3.1",
     "react-dom": "19.3.1",
     "react-window": "2.5.3",
-    "temporal-polyfill": "1.0.6"
+    "temporal-polyfill": "1.0.8"
   },
   "devDependencies": {
     "@digdir/designsystemet-react": "1.23.0",
@@ -82,7 +82,7 @@
     "@mui/material": "9.5.0",
     "@mui/x-data-grid-premium": "8.29.5",
     "@mui/x-license": "8.29.3",
-    "@navikt/aksel-icons": "8.21.0",
+    "@navikt/aksel-icons": "8.22.1",
     "@testing-library/dom": "^10.4.2",
     "@testing-library/jest-dom": "^7.0.1",
     "@testing-library/react": "16.3.3",
@@ -93,7 +93,7 @@
     "react-error-boundary": "6.1.6",
     "react-router": "8.5.1",
     "typescript": "7.0.2",
-    "vitest": "5.0.5"
+    "vitest": "5.1.0"
   },
   "scripts": {
     "build": "pnpm run build:tsc && pnpm test && pnpm run build:css",

package/src/grid/assistant.test.ts

@@ -0,0 +1,162 @@
+import type { FieldMetadata } from "@olenbetong/appframe-core";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { type AssistantGrid, createGridTools, registerAssistantGrid } from "./assistant.js";
+import { AssistantFilterError, toGridFilter } from "./assistantFilter.js";
+
+const fields: FieldMetadata[] = [
+	{ name: "Customer", type: "string" },
+	{ name: "Amount", type: "number" },
+	{ name: "Delivered", type: "date" },
+	{ name: "Closed", type: "boolean" },
+];
+
+describe("the assistant's grid filter", () => {
+	it("becomes the grid's filter tree, with the field's own name and value types", () => {
+		expect(
+			toGridFilter(
+				{
+					mode: "and",
+					items: [
+						{ column: "customer", operator: "contains", value: "Olen" },
+						{ column: "Amount", operator: "greaterThan", value: "1000" },
+						{ column: "Delivered", operator: "between", value: ["2026-01-01", "2026-06-30"] },
+						{ column: "Closed", operator: "isfalse" },
+					],
+				},
+				fields,
+			),
+		).toEqual({
+			type: "group",
+			mode: "and",
+			items: [
+				{ type: "expression", column: "Customer", operator: "contains", value: "Olen", valueType: "string" },
+				{ type: "expression", column: "Amount", operator: "greaterthan", value: 1000, valueType: "number" },
+				{
+					type: "expression",
+					column: "Delivered",
+					operator: "between",
+					value: ["2026-01-01", "2026-06-30"],
+					valueType: "array",
+				},
+				{ type: "expression", column: "Closed", operator: "isfalse", value: null, valueType: "null" },
+			],
+		});
+	});
+
+	it("turns a relative date into a special value", () => {
+		let tree = toGridFilter({ column: "Delivered", operator: "greaterthanorequal", value: "lastweek" }, fields);
+		expect(tree.items[0]).toMatchObject({ value: "LastWeek", valueType: "special" });
+	});
+
+	it("keeps nested groups", () => {
+		let tree = toGridFilter(
+			{
+				mode: "or",
+				items: [
+					{ column: "Customer", operator: "equals", value: "A" },
+					{ mode: "and", items: [{ column: "Amount", operator: "lessthan", value: 5 }] },
+				],
+			},
+			fields,
+		);
+		expect(tree.mode).toBe("or");
+		expect(tree.items[1]).toMatchObject({ type: "group", mode: "and" });
+	});
+
+	it("refuses unknown fields, wrong operators and missing values with a message to act on", () => {
+		expect(() => toGridFilter({ column: "Secret", operator: "equals", value: 1 }, fields)).toThrow(
+			AssistantFilterError,
+		);
+		expect(() => toGridFilter({ column: "Closed", operator: "contains", value: "x" }, fields)).toThrow(/It can use/);
+		expect(() => toGridFilter({ column: "Amount", operator: "equals" }, fields)).toThrow(/needs a value/);
+		expect(() => toGridFilter({ column: "Amount", operator: "between", value: [1] }, fields)).toThrow(/two values/);
+		expect(() => toGridFilter({ column: "Amount", operator: "equals", value: "many" }, fields)).toThrow(/is a number/);
+	});
+});
+
+describe("the grid tools", () => {
+	afterEach(() => {
+		delete (globalThis as { ob?: unknown }).ob;
+	});
+
+	function fakeGrid(label: string): AssistantGrid {
+		return {
+			label: () => label,
+			getLayout: vi.fn(() => ({ label })),
+			getRows: vi.fn((maxRows: number) => ({ maxRows })),
+			setColumns: vi.fn(),
+			sort: vi.fn(),
+			filter: vi.fn(),
+			group: vi.fn(),
+		};
+	}
+
+	function fakeChrome(enabled = true) {
+		let registered = new Map<string, { parameters?: any; handler: (args: any) => unknown }>();
+		(globalThis as { ob?: unknown }).ob = {
+			chrome: {
+				assistant: {
+					enabled,
+					registerTool: (tool: { name: string; parameters?: any; handler: (args: any) => unknown }) => {
+						registered.set(tool.name, tool);
+						return () => registered.delete(tool.name);
+					},
+				},
+			},
+		};
+		return registered;
+	}
+
+	it("registers one set of tools for all grids, naming them by label, and removes it with the last grid", async () => {
+		let registered = fakeChrome();
+		let offAll = [registerAssistantGrid(fakeGrid("Deliveries")), registerAssistantGrid(fakeGrid("Deliveries"))];
+		await Promise.resolve();
+
+		expect([...registered.keys()]).toEqual([
+			"get_grid_layout",
+			"get_grid_rows",
+			"set_grid_columns",
+			"sort_grid",
+			"filter_grid",
+			"group_grid",
+		]);
+		expect(registered.get("get_grid_layout")?.parameters.properties.grid.enum).toEqual([
+			"Deliveries",
+			"Deliveries (2)",
+		]);
+		expect(registered.get("get_grid_layout")?.handler({ grid: "Deliveries (2)" })).toEqual({ label: "Deliveries" });
+		expect(registered.get("get_grid_layout")?.handler({ grid: "Nope" })).toEqual({
+			error: expect.stringContaining("Deliveries, Deliveries (2)"),
+		});
+
+		for (let off of offAll) off();
+		await Promise.resolve();
+		expect(registered.size).toBe(0);
+	});
+
+	it("needs no grid name when there is one grid, and caps the rows", async () => {
+		let registered = fakeChrome();
+		let off = registerAssistantGrid(fakeGrid("Strings"));
+		await Promise.resolve();
+		expect(registered.get("get_grid_rows")?.handler({ maxRows: 5000 })).toEqual({ maxRows: 50 });
+		off();
+		await Promise.resolve();
+	});
+
+	it("registers nothing when the assistant is off for the page", async () => {
+		let registered = fakeChrome(false);
+		let off = registerAssistantGrid(fakeGrid("Strings"));
+		await Promise.resolve();
+		expect(registered.size).toBe(0);
+		off();
+		await Promise.resolve();
+	});
+
+	it("describes the filter syntax and the grids in the tools", () => {
+		let tools = createGridTools(["A", "B"]);
+		let filter = tools.find((tool) => tool.name === "filter_grid")!;
+		expect((filter.parameters as any).required).toEqual(["grid", "mode"]);
+		expect(tools[0].description).toContain("A, B");
+	});
+});

package/src/grid/assistant.ts

@@ -0,0 +1,248 @@
+import { getLocalizedString } from "../i18n.js";
+import { ASSISTANT_FILTER_SCHEMA, type AssistantFilterNode } from "./assistantFilter.js";
+
+/*
+ * The site assistant's tools for AfGrid: reading and changing the layout, sort, filter and grouping
+ * of the grids on the page, and reading the rows they show. One set of tools is registered while
+ * any grid is mounted, with a `grid` parameter naming the grid by its label, so a page with three
+ * grids does not send three sets with every question.
+ *
+ * The assistant belongs to the site chrome (synergi-chrome), which this package does not depend on:
+ * the tools go through `window.ob.chrome.assistant` when the page has it, and nothing happens
+ * otherwise. The tools change what the grid shows, never data, so they run without asking; the
+ * user can change any of it back in the grid.
+ */
+
+/** What a mounted grid offers the assistant. Every method reads the grid's current state. */
+export type AssistantGrid = {
+	label: () => string;
+	getLayout: () => unknown;
+	getRows: (maxRows: number) => unknown;
+	setColumns: (change: { show?: string[]; hide?: string[]; order?: string[] }) => unknown;
+	sort: (sort: { field: string; direction?: "asc" | "desc" }[]) => unknown;
+	filter: (mode: "replace" | "add" | "clear", filter?: AssistantFilterNode) => unknown;
+	group: (change: { groupBy?: string[]; totals?: Record<string, string> }) => unknown;
+};
+
+type ToolLike = {
+	name: string;
+	description: string;
+	label?: string;
+	parameters?: Record<string, unknown>;
+	handler: (args: any) => unknown;
+};
+
+type AssistantApiLike = { readonly enabled: boolean; registerTool: (tool: ToolLike) => () => void };
+
+/** The most rows `get_grid_rows` returns, so one call cannot fill the conversation. */
+export const MAX_ASSISTANT_ROWS = 50;
+
+function assistantApi(): AssistantApiLike | undefined {
+	return (globalThis as { ob?: { chrome?: { assistant?: AssistantApiLike } } }).ob?.chrome?.assistant;
+}
+
+const grids = new Set<AssistantGrid>();
+let unregister: (() => void)[] = [];
+let scheduled = false;
+let waitingForChrome = false;
+
+/** The grids by the label the assistant uses; a second grid with the same label gets " (2)". */
+function gridsByLabel(): Map<string, AssistantGrid> {
+	let byLabel = new Map<string, AssistantGrid>();
+	for (let grid of grids) {
+		let base = grid.label().trim() || "Grid";
+		let label = base;
+		for (let n = 2; byLabel.has(label); n++) label = `${base} (${n})`;
+		byLabel.set(label, grid);
+	}
+	return byLabel;
+}
+
+function schedule() {
+	if (scheduled) return;
+	scheduled = true;
+	// Grids mounting in the same render are registered together.
+	queueMicrotask(() => {
+		scheduled = false;
+		refresh();
+	});
+}
+
+function refresh() {
+	for (let remove of unregister) remove();
+	unregister = [];
+	if (grids.size === 0) return;
+
+	let api = assistantApi();
+	if (!api) {
+		// The chrome mounts after the app on some pages; register once it is there.
+		if (!waitingForChrome && typeof window !== "undefined") {
+			waitingForChrome = true;
+			window.addEventListener(
+				"ob:chrome-ready",
+				() => {
+					waitingForChrome = false;
+					schedule();
+				},
+				{ once: true },
+			);
+		}
+		return;
+	}
+	if (!api.enabled) return;
+
+	let labels = [...gridsByLabel().keys()];
+	unregister = createGridTools(labels).map((tool) => api.registerTool(tool));
+}
+
+/** Adds a grid to the assistant's tools; returns a function that removes it. */
+export function registerAssistantGrid(grid: AssistantGrid): () => void {
+	grids.add(grid);
+	schedule();
+	return () => {
+		grids.delete(grid);
+		schedule();
+	};
+}
+
+/** Re-reads the labels, after a grid's label changed. */
+export function refreshAssistantGrids() {
+	if (grids.size > 0) schedule();
+}
+
+function resolveGrid(name: unknown): AssistantGrid {
+	let byLabel = gridsByLabel();
+	if (byLabel.size === 1 && (name === undefined || name === null || name === "")) return [...byLabel.values()][0];
+	let grid = byLabel.get(String(name ?? ""));
+	if (!grid)
+		throw new Error(`No grid named "${String(name ?? "")}". The grids are: ${[...byLabel.keys()].join(", ")}.`);
+	return grid;
+}
+
+function withGrid<TArgs extends { grid?: string }>(run: (grid: AssistantGrid, args: TArgs) => unknown) {
+	return (args: TArgs) => {
+		try {
+			return run(resolveGrid(args?.grid), args ?? ({} as TArgs));
+		} catch (error) {
+			return { error: error instanceof Error ? error.message : String(error) };
+		}
+	};
+}
+
+/** The tools for the grids with these labels. Exported for tests. */
+export function createGridTools(labels: string[]): ToolLike[] {
+	let gridParameter = {
+		grid: {
+			type: "string",
+			enum: labels,
+			description:
+				labels.length === 1 ? "The grid. Can be left out: there is one." : "Which grid on the page, by its label.",
+		},
+	};
+	let required = labels.length === 1 ? [] : ["grid"];
+	let fieldList = { type: "array", items: { type: "string" } };
+
+	return [
+		{
+			name: "get_grid_layout",
+			label: getLocalizedString("Read the grid's layout"),
+			description: `The layout of a grid on the page (${labels.join(", ")}): its columns (field, header, whether shown), the fields it can be filtered on, the sort, the filter, the grouping and totals, and how many rows it has. Read it before changing the grid.`,
+			parameters: { type: "object", properties: gridParameter, required },
+			handler: withGrid((grid) => grid.getLayout()),
+		},
+		{
+			name: "get_grid_rows",
+			label: getLocalizedString("Read the rows in the grid"),
+			description: `The rows a grid shows, in its order and with its shown columns: the rows it has loaded (the current page when it pages), at most ${MAX_ASSISTANT_ROWS}. To look at other rows, filter or sort the grid first.`,
+			parameters: {
+				type: "object",
+				properties: {
+					...gridParameter,
+					maxRows: { type: "number", description: `At most this many rows (default and limit ${MAX_ASSISTANT_ROWS}).` },
+				},
+				required,
+			},
+			handler: withGrid((grid, { maxRows }: { grid?: string; maxRows?: number }) =>
+				grid.getRows(Math.max(1, Math.min(MAX_ASSISTANT_ROWS, Number(maxRows) || MAX_ASSISTANT_ROWS))),
+			),
+		},
+		{
+			name: "set_grid_columns",
+			label: getLocalizedString("Change the grid's columns"),
+			description:
+				"Shows or hides a grid's columns, and moves them. `order` lists fields in the order they should come first; the rest keep their order after them. Use the fields from get_grid_layout.",
+			parameters: {
+				type: "object",
+				properties: { ...gridParameter, show: fieldList, hide: fieldList, order: fieldList },
+				required,
+			},
+			handler: withGrid((grid, args: { grid?: string; show?: string[]; hide?: string[]; order?: string[] }) =>
+				grid.setColumns(args),
+			),
+		},
+		{
+			name: "sort_grid",
+			label: getLocalizedString("Sort the grid"),
+			description: "Sorts a grid by one or more columns, first one first. An empty list removes the sort.",
+			parameters: {
+				type: "object",
+				properties: {
+					...gridParameter,
+					sort: {
+						type: "array",
+						items: {
+							type: "object",
+							properties: { field: { type: "string" }, direction: { type: "string", enum: ["asc", "desc"] } },
+							required: ["field"],
+						},
+					},
+				},
+				required: [...required, "sort"],
+			},
+			handler: withGrid((grid, { sort }: { grid?: string; sort?: { field: string; direction?: "asc" | "desc" }[] }) =>
+				grid.sort(Array.isArray(sort) ? sort : []),
+			),
+		},
+		{
+			name: "filter_grid",
+			label: getLocalizedString("Filter the grid"),
+			description:
+				"Filters a grid on the server, like the grid's filter builder (which then shows it). `replace` swaps the filter for this one, `add` keeps the current filter and adds this one with AND, `clear` removes the filter. Columns are the filter fields from get_grid_layout, which may include fields that are not shown.",
+			parameters: {
+				type: "object",
+				properties: {
+					...gridParameter,
+					mode: { type: "string", enum: ["replace", "add", "clear"] },
+					filter: ASSISTANT_FILTER_SCHEMA,
+				},
+				required: [...required, "mode"],
+			},
+			handler: withGrid(
+				(grid, { mode, filter }: { grid?: string; mode?: "replace" | "add" | "clear"; filter?: AssistantFilterNode }) =>
+					grid.filter(mode ?? "replace", filter),
+			),
+		},
+		{
+			name: "group_grid",
+			label: getLocalizedString("Group the grid"),
+			description:
+				"Groups a grid's rows by columns (an empty list removes the grouping) and sets totals per column: sum, avg, min, max or size (count). Grouping and totals cover the rows the grid has loaded. Leave out what should stay as it is.",
+			parameters: {
+				type: "object",
+				properties: {
+					...gridParameter,
+					groupBy: fieldList,
+					totals: {
+						type: "object",
+						description: 'Field to total function, e.g. { "Amount": "sum" }. An empty object removes the totals.',
+						additionalProperties: { type: "string", enum: ["sum", "avg", "min", "max", "size"] },
+					},
+				},
+				required,
+			},
+			handler: withGrid((grid, args: { grid?: string; groupBy?: string[]; totals?: Record<string, string> }) =>
+				grid.group(args),
+			),
+		},
+	];
+}

package/src/grid/assistantFilter.ts

@@ -0,0 +1,97 @@
+import {
+	type FieldMetadata,
+	type FilterExpression,
+	type FilterGroup,
+	getDynamicValuesForField,
+	getOperatorArity,
+	getOperatorsForField,
+	getValueType,
+	normalizeOperator,
+} from "@olenbetong/appframe-core";
+
+import { findFilterField } from "./useAfFilter.js";
+
+/**
+ * A filter as the assistant writes it: groups of `column operator value`, without the type and
+ * value type fields the grid's filter tree carries. Converted with {@link toGridFilter}.
+ */
+export type AssistantFilterNode =
+	| { mode?: "and" | "or"; items: AssistantFilterNode[] }
+	| { column: string; operator: string; value?: unknown };
+
+/** The JSON Schema the assistant is given for {@link AssistantFilterNode}. */
+export const ASSISTANT_FILTER_SCHEMA = {
+	type: "object",
+	description:
+		"A group: { mode: 'and' | 'or', items: [...] }, where each item is another group or a criterion { column, operator, value }. Operators: equals, notequals, greaterthan, greaterthanorequal, lessthan, lessthanorequal, contains, notcontains, beginswith, endswith, isnull, isnotnull, isblank, isnotblank, istrue, isfalse, inlist and notinlist (value is an array), between and notbetween (value is [from, to]). Dates use the same comparisons with 'YYYY-MM-DD' values, or a relative value such as Today, Yesterday, ThisWeek, LastWeek, ThisMonth, LastMonth, ThisYear or LastYear; whole periods also have operators without a value: istoday, isyesterday, islastweek, isearlierthisweek, isearlierthismonth, isearlierthisyear, ispriorthisyear, istomorrow, isnextweek. A text field can compare with CurrentUser. Only the operators a field allows are accepted; an error lists them.",
+} as const;
+
+/** What went wrong in a filter, for the assistant to correct. */
+export class AssistantFilterError extends Error {}
+
+function isGroupNode(node: AssistantFilterNode): node is { mode?: "and" | "or"; items: AssistantFilterNode[] } {
+	return Array.isArray((node as { items?: unknown }).items);
+}
+
+function convertValue(
+	field: FieldMetadata,
+	operator: string,
+	value: unknown,
+): Pick<FilterExpression, "value" | "valueType"> {
+	let arity = getOperatorArity(operator as never);
+	if (arity === "none") return { value: null, valueType: "null" };
+
+	let valueType = getValueType(field, operator as never);
+	if (arity === "list" || arity === "pair") {
+		if (!Array.isArray(value) || value.length === 0) {
+			throw new AssistantFilterError(`The operator ${operator} on ${field.name} needs a list of values.`);
+		}
+		if (arity === "pair" && value.length !== 2) {
+			throw new AssistantFilterError(`The operator ${operator} on ${field.name} needs two values: [from, to].`);
+		}
+		return { value: value.map((item) => (item === null ? null : String(item))) as string[], valueType: "array" };
+	}
+
+	if (value === undefined || value === null || value === "") {
+		throw new AssistantFilterError(`The operator ${operator} on ${field.name} needs a value.`);
+	}
+	let text = String(value);
+	let special = getDynamicValuesForField(field).find((name) => name.toLowerCase() === text.toLowerCase());
+	if (special) return { value: special, valueType: "special" };
+	if (valueType === "number") {
+		let number = Number(value);
+		if (Number.isNaN(number)) throw new AssistantFilterError(`${field.name} is a number; "${text}" is not.`);
+		return { value: number, valueType };
+	}
+	return { value: text, valueType };
+}
+
+/**
+ * Turns the assistant's filter into the grid's filter tree, checking every column against the
+ * grid's filter fields and every operator against the column's type. Throws an
+ * {@link AssistantFilterError} the assistant can act on.
+ */
+export function toGridFilter(node: AssistantFilterNode, fields: FieldMetadata[]): FilterGroup {
+	if (!isGroupNode(node)) return { type: "group", mode: "and", items: [toItem(node, fields)] };
+	return {
+		type: "group",
+		mode: node.mode === "or" ? "or" : "and",
+		items: node.items.map((item) => (isGroupNode(item) ? toGridFilter(item, fields) : toItem(item, fields))),
+	};
+}
+
+function toItem(
+	node: { column: string; operator: string; value?: unknown },
+	fields: FieldMetadata[],
+): FilterExpression {
+	let field = node.column ? findFilterField(fields, node.column) : undefined;
+	if (!field || field.excludeFromFilter) {
+		throw new AssistantFilterError(`The grid cannot filter on "${node.column}". Use a field from get_grid_layout.`);
+	}
+	let operator = normalizeOperator(String(node.operator ?? ""));
+	let allowed = getOperatorsForField(field);
+	if (!allowed.includes(operator)) {
+		throw new AssistantFilterError(`${field.name} cannot use ${node.operator}. It can use: ${allowed.join(", ")}.`);
+	}
+	return { type: "expression", column: field.name, operator, ...convertValue(field, operator, node.value) };
+}

package/src/grid/index.tsx

@@ -54,6 +54,7 @@ import type { AfGridColumn } from "./useAfColumns.js";
 import { type AfGridColDef, type AfGridRowAction, useAfColumns } from "./useAfColumns.js";
 import { useAfCurrentIndex } from "./useAfCurrentIndex.js";
 import { useAfData } from "./useAfData.js";
+import { useAfAssistant } from "./useAfAssistant.js";
 import { useAfFilterFields } from "./useAfFilterFields.js";
 import { findFilterField, useAfFilter } from "./useAfFilter.js";
 import { type AfGridApi, useAfGridApi } from "./useAfGridApi.js";
@@ -311,6 +312,14 @@ export type AfGridProps = {
 	 * button still shows that the grid is loading.
 	 */
 	disableLoadingOverlay?: boolean;
+	/**
+	 * The grid's name for the site assistant ("Deliveries"), which can then read and change its
+	 * layout, sort, filter and grouping and read its rows (see `assistant.ts`). Defaults to the id.
+	 * The assistant only reaches the grid on pages where it is switched on.
+	 */
+	assistantLabel?: string;
+	/** Keeps the grid away from the site assistant. */
+	disableAssistant?: boolean;
 } & Omit<
 	DataGridProps,
 	| "apiRef"
@@ -382,6 +391,8 @@ function AfGrid_(props: AfGridProps) {
 		getRowClassName,
 		serverAggregation = dataObject.options?.dynamicLoading === true,
 		disableLoadingOverlay = false,
+		assistantLabel,
+		disableAssistant = false,
 		...other
 	} = props;
 	let apiRefPriv = useGridApiRef();
@@ -445,6 +456,16 @@ function AfGrid_(props: AfGridProps) {
 		getRowActions,
 	});
 	let filterFields = useAfFilterFields(dataObject, columnsProp);
+	useAfAssistant({
+		id,
+		label: assistantLabel,
+		disabled: disableAssistant,
+		apiRef,
+		dataObject,
+		gridFilter,
+		filterFields,
+		grouping: grouping.gridProps,
+	});
 
 	let keyEvents = useAfKeyBindings({ apiRef, dataObject });
 	let rootRef = useRef<HTMLDivElement>(null);

package/src/grid/useAfAssistant.ts

@@ -0,0 +1,195 @@
+import type { GridApi, GridColDef, GridSortModel } from "@mui/x-data-grid-premium";
+import { describeFilter, type FieldMetadata, pruneFilter } from "@olenbetong/appframe-core";
+import type { DataObject } from "@olenbetong/appframe-data";
+import { type RefObject, useEffect, useLayoutEffect, useRef } from "react";
+
+import { type AssistantGrid, refreshAssistantGrids, registerAssistantGrid } from "./assistant.js";
+import { type AssistantFilterNode, toGridFilter } from "./assistantFilter.js";
+import type { AfFilterApi } from "./useAfFilter.js";
+import type { AfGridGroupingProps } from "./useAfRowGrouping.js";
+
+type Options = {
+	id: string;
+	/** The grid's name for the assistant. Defaults to the grid id. */
+	label?: string;
+	disabled?: boolean;
+	apiRef: RefObject<GridApi | null>;
+	dataObject: DataObject<any>;
+	gridFilter: AfFilterApi;
+	filterFields: FieldMetadata[];
+	grouping: AfGridGroupingProps;
+};
+
+const TOTALS = new Set(["sum", "avg", "min", "max", "size"]);
+
+/** The grid's own columns: not the checkbox, row actions or the grouping column. */
+function dataColumns(api: GridApi): GridColDef[] {
+	return api.getAllColumns().filter((column) => !column.field.startsWith("__") && column.type !== "actions");
+}
+
+function json(value: unknown) {
+	if (value instanceof Date) return value.toISOString();
+	return value;
+}
+
+/**
+ * Offers the grid to the site assistant (see assistant.ts). The methods read the grid when called,
+ * through a ref updated after every render, so the tools always act on what the user sees.
+ */
+export function useAfAssistant(options: Options) {
+	let latest = useRef(options);
+	useLayoutEffect(() => {
+		latest.current = options;
+	});
+
+	let grid = useRef<AssistantGrid | null>(null);
+	grid.current ??= createAssistantGrid(() => latest.current);
+
+	let { disabled, label, id } = options;
+	useEffect(() => {
+		if (disabled) return;
+		return registerAssistantGrid(grid.current!);
+	}, [disabled]);
+
+	useEffect(() => {
+		refreshAssistantGrids();
+	}, [label, id]);
+}
+
+function createAssistantGrid(get: () => Options): AssistantGrid {
+	function api(): GridApi {
+		let current = get().apiRef.current;
+		if (!current) throw new Error("The grid is not ready yet.");
+		return current;
+	}
+
+	function columnByField(field: string) {
+		let lower = String(field ?? "").toLowerCase();
+		let column = dataColumns(api()).find((item) => item.field.toLowerCase() === lower);
+		if (!column) throw new Error(`The grid has no column "${field}". Use a field from get_grid_layout.`);
+		return column;
+	}
+
+	function visibility(): Record<string, boolean> {
+		return { ...api().state.columns.columnVisibilityModel };
+	}
+
+	function describe() {
+		let { gridFilter, filterFields } = get();
+		let pruned = pruneFilter(gridFilter.filter);
+		return pruned ? describeFilter(pruned, { fields: filterFields }) : null;
+	}
+
+	return {
+		label: () => get().label || get().id,
+
+		getLayout() {
+			let { dataObject, filterFields, grouping } = get();
+			let shown = visibility();
+			let columns = dataColumns(api()).map((column) => ({
+				field: column.field,
+				header: column.headerName ?? column.field,
+				shown: shown[column.field] !== false,
+			}));
+			let columnFields = new Set(columns.map((column) => column.field.toLowerCase()));
+			return {
+				columns,
+				// Filtering reaches the view, so a field that is not a column can be filtered on too.
+				otherFilterFields: filterFields
+					.filter((field) => !field.excludeFromFilter && !columnFields.has(field.name.toLowerCase()))
+					.map((field) => ({ field: field.name, type: field.type })),
+				sort: api().getSortModel(),
+				filter: describe(),
+				groupBy: grouping.rowGroupingModel,
+				totals: grouping.aggregationModel,
+				rows: { loaded: dataObject.getData().length, total: dataObject.getDataLength() },
+			};
+		},
+
+		getRows(maxRows) {
+			let grid = api();
+			let shown = visibility();
+			let columns = dataColumns(grid).filter((column) => shown[column.field] !== false);
+			let rows = grid
+				.getSortedRowIds()
+				.filter((rowId) => grid.getRowNode(rowId)?.type === "leaf")
+				.slice(0, maxRows)
+				.map((rowId) => {
+					let row = grid.getRow(rowId);
+					return Object.fromEntries(columns.map((column) => [column.field, json(grid.getRowValue(row, column))]));
+				});
+			return {
+				columns: columns.map((column) => ({ field: column.field, header: column.headerName ?? column.field })),
+				rows,
+				loaded: get().dataObject.getData().length,
+				total: get().dataObject.getDataLength(),
+			};
+		},
+
+		setColumns({ show = [], hide = [], order = [] }) {
+			let grid = api();
+			let model = visibility();
+			for (let field of show) model[columnByField(field).field] = true;
+			for (let field of hide) model[columnByField(field).field] = false;
+			grid.setColumnVisibilityModel(model);
+
+			if (order.length > 0) {
+				// After the checkbox and other built-in columns, which stay first.
+				let first = grid.getAllColumns().findIndex((column) => dataColumns(grid).includes(column));
+				order.forEach((field, index) => grid.setColumnIndex(columnByField(field).field, Math.max(0, first) + index));
+			}
+			return { columns: (this.getLayout() as { columns: unknown }).columns };
+		},
+
+		sort(sort) {
+			let model: GridSortModel = sort.map((item) => {
+				let column = columnByField(item.field);
+				if (column.sortable === false) throw new Error(`The grid cannot sort on ${column.field}.`);
+				return { field: column.field, sort: item.direction === "desc" ? "desc" : "asc" };
+			});
+			api().setSortModel(model);
+			return { sort: model };
+		},
+
+		filter(mode, filter) {
+			let { gridFilter, filterFields, id } = get();
+			if (mode === "clear") {
+				gridFilter.setFilter({ type: "group", name: id, mode: "and", items: [] });
+				return { filter: null };
+			}
+			if (!filter) throw new Error("Give a filter, or use mode 'clear'.");
+			let next = toGridFilter(filter as AssistantFilterNode, filterFields);
+			let current = pruneFilter(gridFilter.filter);
+			let tree =
+				mode === "add" && current
+					? { type: "group" as const, name: id, mode: "and" as const, items: [current, next] }
+					: { ...next, name: id };
+			gridFilter.setFilter(tree);
+			return {
+				filter: describeFilter(tree, { fields: filterFields }),
+				note: "The grid reloads with the new filter in a moment.",
+			};
+		},
+
+		group({ groupBy, totals }) {
+			let { grouping } = get();
+			if (groupBy) {
+				let fields = groupBy.map((field) => {
+					let column = columnByField(field);
+					if (column.groupable === false) throw new Error(`The grid cannot group by ${column.field}.`);
+					return column.field;
+				});
+				grouping.onRowGroupingModelChange(fields);
+			}
+			if (totals) {
+				let model: Record<string, string> = {};
+				for (let [field, total] of Object.entries(totals)) {
+					if (!TOTALS.has(total)) throw new Error(`Unknown total "${total}". Use sum, avg, min, max or size.`);
+					model[columnByField(field).field] = total;
+				}
+				grouping.onAggregationModelChange(model);
+			}
+			return { groupBy: groupBy ?? grouping.rowGroupingModel, totals: totals ?? grouping.aggregationModel };
+		},
+	};
+}

package/src/layout/ErrorBoundary.css

@@ -99,3 +99,54 @@
 	word-break: break-all;
 	font-size: var(--ds-font-size-1, 0.75rem);
 }
+
+.RouteErrorPage-status {
+	display: flex;
+	flex-direction: column;
+	align-items: center;
+	gap: var(--ds-size-3, 0.75rem);
+	max-width: 36rem;
+	margin: 0 auto;
+	padding: 12vh var(--ds-size-4, 1rem) var(--ds-size-8, 2rem);
+	text-align: center;
+}
+
+.RouteErrorPage-icon {
+	display: grid;
+	place-items: center;
+	width: 5rem;
+	height: 5rem;
+	margin-bottom: var(--ds-size-2, 0.5rem);
+	border-radius: 50%;
+	background: var(--ds-color-neutral-surface-tinted, rgb(0 0 0 / 0.05));
+	color: var(--ds-color-neutral-text-subtle, #555);
+	font-size: 2.75rem;
+}
+
+.RouteErrorPage-code {
+	margin: 0;
+	color: var(--ds-color-neutral-text-subtle, #555);
+	font-size: clamp(3.5rem, 12vw, 6rem);
+	font-weight: 700;
+	line-height: 1;
+	letter-spacing: 0.04em;
+	font-variant-numeric: tabular-nums;
+}
+
+.RouteErrorPage-status h1,
+.RouteErrorPage-detail,
+.RouteErrorPage-hint {
+	margin: 0;
+}
+
+.RouteErrorPage-hint {
+	color: var(--ds-color-neutral-text-subtle, #555);
+}
+
+.RouteErrorPage-actions {
+	display: flex;
+	flex-wrap: wrap;
+	justify-content: center;
+	gap: var(--ds-size-2, 0.5rem);
+	margin-top: var(--ds-size-4, 1rem);
+}

package/src/layout/ErrorBoundary.test.tsx

@@ -0,0 +1,53 @@
+import { render, screen } from "@testing-library/react";
+import { createMemoryRouter, RouterProvider } from "react-router";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { RouteErrorPage } from "./ErrorBoundary.js";
+
+function renderThrowing(error: () => unknown) {
+	let router = createMemoryRouter([
+		{
+			path: "/",
+			loader: () => {
+				throw error();
+			},
+			Component: () => null,
+			errorElement: <RouteErrorPage />,
+		},
+	]);
+	return render(<RouterProvider router={router} />);
+}
+
+describe("RouteErrorPage", () => {
+	let logError = vi.fn();
+	(globalThis as any).af = { common: { logError } };
+
+	afterEach(() => logError.mockClear());
+
+	it("shows a status page with the app's own text for a thrown 404", async () => {
+		renderThrowing(() => new Response("", { status: 404, statusText: "The invoice was not found" }));
+		expect(await screen.findByRole("heading", { name: "We could not find what you were looking for" })).toBeTruthy();
+		expect(screen.getByText("404")).toBeTruthy();
+		expect(screen.getByText("The invoice was not found")).toBeTruthy();
+		expect(screen.getByRole("button", { name: "Go to the start page" })).toBeTruthy();
+		expect(logError).not.toHaveBeenCalled();
+	});
+
+	it("leaves out a standard reason phrase", async () => {
+		renderThrowing(() => new Response("", { status: 403, statusText: "Forbidden" }));
+		expect(await screen.findByRole("heading", { name: "You do not have access to this" })).toBeTruthy();
+		expect(screen.queryByText("Forbidden")).toBeNull();
+	});
+
+	it("offers a refresh and reports server errors", async () => {
+		renderThrowing(() => new Response("", { status: 500 }));
+		expect(await screen.findByRole("button", { name: "Refresh page" })).toBeTruthy();
+		expect(logError).toHaveBeenCalled();
+	});
+
+	it("shows an unexpected exception with its message", async () => {
+		renderThrowing(() => new TypeError("Boom"));
+		expect(await screen.findByText("Boom")).toBeTruthy();
+		expect(logError).toHaveBeenCalled();
+	});
+});

package/src/layout/ErrorBoundary.tsx

@@ -3,8 +3,18 @@ import "./ErrorBoundary.css";
 import type { DataObject } from "@olenbetong/appframe-data";
 import { useError } from "@olenbetong/appframe-react";
 
+import { Button, Heading, Paragraph } from "@digdir/designsystemet-react";
+import {
+	ArrowLeftIcon,
+	CloudSlashIcon,
+	ExclamationmarkTriangleIcon,
+	FileSearchIcon,
+	PadlockLockedIcon,
+	PersonIcon,
+} from "@navikt/aksel-icons";
+
 import { Component, useEffect } from "react";
-import { useAsyncError, useRouteError } from "react-router";
+import { type ErrorResponse, isRouteErrorResponse, useAsyncError, useNavigate, useRouteError } from "react-router";
 
 import { PageContainer } from "./PageContainer.js";
 import { getLocalizedString } from "../i18n.js";
@@ -127,13 +137,127 @@ export function ErrorAlertFallback({ error, className }: ErrorAlertFallbackProps
 
 // ── RouteErrorPage ────────────────────────────────────────────────────────────
 
+/** The reason phrases a server sends on its own; anything else in statusText was written for the user. */
+const standardStatusTexts = new Set([
+	"Bad Request",
+	"Unauthorized",
+	"Forbidden",
+	"Not Found",
+	"Method Not Allowed",
+	"Conflict",
+	"Gone",
+	"Internal Server Error",
+	"Bad Gateway",
+	"Service Unavailable",
+	"Gateway Timeout",
+]);
+
+type StatusPage = {
+	icon: React.ReactNode;
+	title: string;
+	message: string;
+	retry: boolean;
+};
+
+function statusPage(status: number): StatusPage {
+	if (status === 404 || status === 410) {
+		return {
+			icon: <FileSearchIcon aria-hidden />,
+			title: getLocalizedString("We could not find what you were looking for"),
+			message: getLocalizedString("It may have been moved or deleted, or the link may be wrong."),
+			retry: false,
+		};
+	}
+	if (status === 403) {
+		return {
+			icon: <PadlockLockedIcon aria-hidden />,
+			title: getLocalizedString("You do not have access to this"),
+			message: getLocalizedString("Contact the IT department if you need access."),
+			retry: false,
+		};
+	}
+	if (status === 401) {
+		return {
+			icon: <PersonIcon aria-hidden />,
+			title: getLocalizedString("You are not logged in"),
+			message: getLocalizedString("Refresh the page to log in again."),
+			retry: true,
+		};
+	}
+	if (status >= 500) {
+		return {
+			icon: <CloudSlashIcon aria-hidden />,
+			title: getLocalizedString("The server could not complete the request"),
+			message: getLocalizedString("Try again in a moment. If the error persists, contact the IT department."),
+			retry: true,
+		};
+	}
+	return {
+		icon: <ExclamationmarkTriangleIcon aria-hidden />,
+		title: getLocalizedString("The request could not be completed"),
+		message: getLocalizedString(
+			"Check what you entered and try again. If the error persists, contact the IT department.",
+		),
+		retry: true,
+	};
+}
+
+/** A thrown `Response` or `data()`: a status page, with the app's own text when it gave one. */
+function RouteErrorResponsePage({ error }: { error: ErrorResponse }) {
+	const navigate = useNavigate();
+	const page = statusPage(error.status);
+	const detail =
+		error.statusText && !standardStatusTexts.has(error.statusText)
+			? error.statusText
+			: typeof error.data === "string" && error.data.trim()
+				? error.data
+				: null;
+	const canGoBack = typeof window !== "undefined" && window.history.length > 1;
+
+	return (
+		<div className="RouteErrorPage-status">
+			<div className="RouteErrorPage-icon">{page.icon}</div>
+			<p className="RouteErrorPage-code">{error.status}</p>
+			<Heading level={1} data-size="md">
+				{page.title}
+			</Heading>
+			{detail && <Paragraph className="RouteErrorPage-detail">{detail}</Paragraph>}
+			<Paragraph data-size="sm" className="RouteErrorPage-hint">
+				{page.message}
+			</Paragraph>
+			<div className="RouteErrorPage-actions">
+				{canGoBack && (
+					<Button variant="secondary" onClick={() => navigate(-1)}>
+						<ArrowLeftIcon aria-hidden />
+						{getLocalizedString("Go back")}
+					</Button>
+				)}
+				{page.retry ? (
+					<Button onClick={() => window.location.reload()}>{getLocalizedString("Refresh page")}</Button>
+				) : (
+					<Button onClick={() => navigate("/")}>{getLocalizedString("Go to the start page")}</Button>
+				)}
+			</div>
+		</div>
+	);
+}
+
 export function RouteErrorPage() {
 	const error = useRouteError();
-	const { message, stackTrace, title } = parseError(error);
+	const isResponse = isRouteErrorResponse(error);
 
 	useEffect(() => {
-		(globalThis as any).af?.common?.logError?.(error);
-	}, [error]);
+		// A missing page or a refused request is expected; only unexpected errors are worth reporting.
+		if (!isResponse || error.status >= 500) {
+			(globalThis as any).af?.common?.logError?.(error);
+		}
+	}, [error, isResponse]);
+
+	if (isResponse) {
+		return <RouteErrorResponsePage error={error} />;
+	}
+
+	const { message, stackTrace, title } = parseError(error);
 
 	return (
 		<PageContainer className="flow">