@conduction/nextcloud-vue 2.100.0 → 2.101.0

package/src/composables/indexSources.js

@@ -11,6 +11,8 @@ import HandBackRight from 'vue-material-design-icons/HandBackRight.vue'
 import LightningBolt from 'vue-material-design-icons/LightningBolt.vue'
 import Pencil from 'vue-material-design-icons/Pencil.vue'
 import { formatRelativeDate } from '../utils/boardDate.js'
+import { fetchReferenceObjects } from '../utils/boardReferenceColumns.js'
+import { fillTemplate } from '../utils/fillTemplate.js'
 import { FLOW_RUN_ERROR_STATUSES, flowRunStatuses } from '../utils/flowRunStatus.js'
 import { fetchGroupMembers, fetchPresence, fetchStatuses } from '../utils/nextcloudDirectory.js'
 import { readPath } from '../utils/readPath.js'
@@ -648,6 +650,10 @@ function readRowsPath(body, path) {
  * requested: page-config keys must never become query parameters. The list
  * stays empty and one console error names the page.
  *
+ * A quick filter with `showCount` is counted with `count(config)`: the same
+ * request with that tab's filter, its total read at `sourceConfig.totalPath`
+ * (`total` by default), else the number of rows the answer holds.
+ *
  * @return {object} The source adapter.
  * @spec openspec/changes/index-endpoint-source/specs/index-page/spec.md#requirement-an-index-page-can-list-rows-from-an-app-endpoint
  */
@@ -656,6 +662,36 @@ function endpointSource() {
 	let seq = 0
 	let warned = false
 
+	/**
+	 * The query parameters for a config: every key but the url and the paths,
+	 * empty values left out, a list joined by commas.
+	 *
+	 * @param {object} rest The config without `url`, `rowsPath` and `totalPath`.
+	 * @return {object} The parameters.
+	 */
+	const paramsOf = (rest) => {
+		const params = {}
+		for (const [key, value] of Object.entries(rest)) {
+			if (value === undefined || value === null || value === '') {
+				continue
+			}
+			params[key] = Array.isArray(value) ? value.join(',') : (typeof value === 'object' ? JSON.stringify(value) : value)
+		}
+		return params
+	}
+
+	/**
+	 * Whether a config can be requested: it names a url and is not the page
+	 * config handed over in its place.
+	 *
+	 * @param {object} config The config.
+	 * @return {boolean}
+	 */
+	const requestable = (config) => {
+		const url = config && config.url
+		return typeof url === 'string' && url !== '' && !Object.hasOwn(config, 'entitySource')
+	}
+
 	return {
 		/**
 		 * Fetch the rows.
@@ -664,10 +700,9 @@ function endpointSource() {
 		 * @return {Promise<void>} Resolves when loaded; a failed request leaves no rows and rethrows.
 		 */
 		load: async (config) => {
-			const { url, rowsPath, ...rest } = config || {}
+			const { url, rowsPath, totalPath, ...rest } = config || {}
 			const mine = ++seq
-			const pageConfig = Boolean(config && Object.hasOwn(config, 'entitySource'))
-			if (typeof url !== 'string' || url === '' || pageConfig) {
+			if (!requestable(config)) {
 				state.rows = []
 				if (!warned) {
 					warned = true
@@ -677,13 +712,7 @@ function endpointSource() {
 				}
 				return
 			}
-			const params = {}
-			for (const [key, value] of Object.entries(rest)) {
-				if (value === undefined || value === null || value === '') {
-					continue
-				}
-				params[key] = Array.isArray(value) ? value.join(',') : (typeof value === 'object' ? JSON.stringify(value) : value)
-			}
+			const params = paramsOf(rest)
 			state.loading = true
 			try {
 				const { default: axios } = await import('@nextcloud/axios')
@@ -705,6 +734,29 @@ function endpointSource() {
 			}
 		},
 
+		/**
+		 * Count the rows for a config without touching the rows on screen, for
+		 * a quick-filter tab with `showCount`.
+		 *
+		 * @param {object} config The page's source config with the tab's filter merged in.
+		 * @return {Promise<number>} The total, or NaN when nothing can be requested.
+		 */
+		count: async (config) => {
+			if (!requestable(config)) {
+				return Number.NaN
+			}
+			const { url, rowsPath, totalPath, ...rest } = config
+			const { default: axios } = await import('@nextcloud/axios')
+			const res = await axios.get(generateUrl(url), { params: paramsOf(rest) })
+			const body = res ? res.data : null
+			const total = body && typeof body === 'object' && !Array.isArray(body) ? readRowsPath(body, totalPath || 'total') : undefined
+			if (typeof total === 'number' && Number.isFinite(total)) {
+				return total
+			}
+			const rows = Array.isArray(body) ? body : readRowsPath(body, rowsPath || 'results')
+			return Array.isArray(rows) ? rows.length : Number.NaN
+		},
+
 		/**
 		 * @return {Array<object>} The rows the endpoint returned.
 		 */
@@ -737,39 +789,102 @@ function fillRowTemplate(template, row) {
  * and its count (DqZoekresultaten).
  *
  * `sourceConfig.kinds` lists what is searched:
- * `{ id, label, register, schema, titleField?, subtitleField?, statusField?, href?, limit? }`
+ * `{ id, label, register, schema, titleField?, subtitleField?, statusField?, statusResolve?, linkedField?, linkedTemplate?, href?, limit? }`
  * for objects (OpenRegister's `_search`, so the reader sees what they may
  * read), or `{ id, label, files: true, limit? }` for the reader's files
  * (Nextcloud's unified search). The term is `sourceConfig.term`, else the
  * address's `?q=` (or `sourceConfig.termQuery`). A kind that fails shows no
  * rows and no count; the others still answer.
  *
+ * The kind's `label` goes through the app's translate (the "Soort" cell and
+ * the quick filters). `statusResolve: { register?, schema, labelField? }`
+ * reads `statusField` as a reference and shows the referenced object's label
+ * (`labelField`, else `title`, then `name`); the status column is a pill,
+ * coloured by `sourceConfig.statusColorMap`. `linkedTemplate` (a field
+ * template, "{case.title}") or `linkedField` (a path) fills the "Linked"
+ * column, drawn when a kind declares one; `sourceConfig.linkedLabel` names it.
+ * The page's title and count line can name the term as `{term}`, and the
+ * count is the active kind's total. Kind, link and status are filterable.
+ *
  * @param {object} [config] The page's source config.
+ * @param {object} [context] The page's helpers.
+ * @param {Function} [context.translate] The app's translate.
  * @return {object} The source adapter.
  * @spec openspec/changes/index-search-source/specs/index-page/spec.md#requirement-an-index-page-can-search-several-schemas-and-files
  */
-function searchSource(config = {}) {
+function searchSource(config = {}, context = {}) {
+	const translate = typeof context.translate === 'function' ? context.translate : (text) => text
 	const kinds = (Array.isArray(config && config.kinds) ? config.kinds : [])
 		.filter((kind) => kind && typeof kind.id === 'string' && kind.id !== '' && (kind.files === true || (kind.register && kind.schema)))
-	const state = reactive({ rows: [], totals: {}, loading: false, kind: 'all', term: '' })
+		.map((kind) => ({ ...kind, label: translate(String(kind.label || kind.id)) }))
+	const hasLinked = kinds.some((kind) => kind.linkedTemplate || kind.linkedField)
+	const state = reactive({ rows: [], totals: {}, loading: false, kind: 'all', term: '', filters: {} })
 	let seq = 0
 
+	/**
+	 * The labels of the objects a kind's status points at, by id: the
+	 * referenced schema read once per search.
+	 *
+	 * @param {object} kind The kind with `statusResolve`.
+	 * @return {Promise<Map<string, string>>} Labels by id; empty when it cannot be read.
+	 */
+	const statusLabels = async (kind) => {
+		const resolve = kind.statusResolve
+		if (!resolve || !resolve.schema) {
+			return new Map()
+		}
+		const objects = await fetchReferenceObjects({ register: resolve.register || kind.register, schema: resolve.schema }).catch(() => [])
+		const labels = new Map()
+		for (const object of objects) {
+			const id = object.id || object.uuid || (object['@self'] && object['@self'].id)
+			const label = readPath(object, resolve.labelField || 'title') ?? object.name
+			if (id !== undefined && label !== undefined && label !== null) {
+				labels.set(String(id), String(label))
+			}
+		}
+		return labels
+	}
+
+	/**
+	 * What a row shows in the Linked column.
+	 *
+	 * @param {object} kind The row's kind.
+	 * @param {object} object The found object.
+	 * @return {string}
+	 */
+	const linkedOf = (kind, object) => {
+		if (kind.linkedTemplate) {
+			return fillTemplate(translate(kind.linkedTemplate), object)
+		}
+		if (kind.linkedField) {
+			const value = readPath(object, kind.linkedField)
+			return value === undefined || value === null ? '' : String(value)
+		}
+		return ''
+	}
+
 	const searchObjects = async (axios, kind, term) => {
 		const url = generateUrl('/apps/openregister/api/objects/{register}/{schema}', { register: kind.register, schema: kind.schema })
 		const res = await axios.get(url, { params: { _search: term, _limit: kind.limit || 20 } })
 		const body = (res && res.data) || {}
 		const results = Array.isArray(body.results) ? body.results : (Array.isArray(body) ? body : [])
+		const labels = kind.statusResolve && kind.statusField ? await statusLabels(kind) : null
 		return {
 			total: typeof body.total === 'number' ? body.total : results.length,
 			rows: results.map((object) => {
 				const id = object.id || object.uuid || (object['@self'] && object['@self'].id)
+				const rawStatus = kind.statusField ? readPath(object, kind.statusField) : undefined
+				const status = rawStatus === undefined || rawStatus === null
+					? ''
+					: (labels ? (labels.get(String(rawStatus)) || '') : String(rawStatus))
 				return {
 					id: `${kind.id}:${id}`,
 					kind: kind.id,
 					kindLabel: kind.label,
 					title: String(readPath(object, kind.titleField || 'title') ?? object.name ?? id ?? ''),
 					subtitle: kind.subtitleField ? String(readPath(object, kind.subtitleField) ?? '') : '',
-					status: kind.statusField ? String(readPath(object, kind.statusField) ?? '') : '',
+					status,
+					linked: linkedOf(kind, object),
 					href: kind.href ? generateUrl(fillRowTemplate(kind.href, { ...object, id })) : '',
 					object,
 				}
@@ -792,6 +907,7 @@ function searchSource(config = {}) {
 				title: entry.title || '',
 				subtitle: entry.subline || '',
 				status: '',
+				linked: '',
 				href: entry.resourceUrl || '',
 			})),
 		}
@@ -806,6 +922,17 @@ function searchSource(config = {}) {
 		 */
 		load: async (cfg) => {
 			state.kind = cfg && typeof cfg.kind === 'string' ? cfg.kind : 'all'
+			// The header filters on Kind, Linked and Status narrow the answer
+			// already fetched; they do not search again.
+			const filters = {}
+			for (const key of ['kindLabel', 'linked', 'status']) {
+				const value = cfg && cfg[key]
+				const values = (Array.isArray(value) ? value : (value === undefined || value === null || value === '' ? [] : [value])).map(String)
+				if (values.length > 0) {
+					filters[key] = values
+				}
+			}
+			state.filters = filters
 			const query = typeof window !== 'undefined' ? new URLSearchParams(window.location.search) : null
 			const term = String((cfg && cfg.term) || (query && query.get((cfg && cfg.termQuery) || 'q')) || '').trim()
 			const mine = ++seq
@@ -837,7 +964,20 @@ function searchSource(config = {}) {
 		/**
 		 * @return {Array<object>} The results of the active kind, or all of them.
 		 */
-		rows: () => (state.kind === 'all' ? state.rows : state.rows.filter((row) => row.kind === state.kind)),
+		rows: () => (state.kind === 'all' ? state.rows : state.rows.filter((row) => row.kind === state.kind))
+			.filter((row) => Object.entries(state.filters).every(([key, values]) => values.includes(String(row[key])))),
+
+		/**
+		 * @return {string} The term searched for, for a `{term}` in the title or count line.
+		 */
+		term: () => state.term,
+
+		/**
+		 * @return {number} The active kind's total, or every kind's together on All.
+		 */
+		total: () => (state.kind === 'all'
+			? Object.values(state.totals).reduce((sum, value) => sum + value, 0)
+			: (state.totals[state.kind] || 0)),
 
 		/**
 		 * @return {boolean} Whether a search is in flight.
@@ -846,8 +986,14 @@ function searchSource(config = {}) {
 
 		columns: [
 			{ key: 'title', label: t('nextcloud-vue', 'Result'), secondary: 'subtitle' },
-			{ key: 'kindLabel', label: t('nextcloud-vue', 'Kind') },
-			{ key: 'status', label: t('nextcloud-vue', 'Status') },
+			{ key: 'kindLabel', label: t('nextcloud-vue', 'Kind'), enum: kinds.map((kind) => kind.label) },
+			...(hasLinked ? [{ key: 'linked', label: config.linkedLabel ? translate(config.linkedLabel) : t('nextcloud-vue', 'Linked') }] : []),
+			{
+				key: 'status',
+				label: t('nextcloud-vue', 'Status'),
+				widget: 'badge',
+				widgetProps: { colorMap: (config && config.statusColorMap) || {} },
+			},
 		],
 
 		quickFilters: kinds.length > 0
@@ -1125,10 +1271,11 @@ export const indexSources = {
  *
  * @param {string} name The source name from `config.source`.
  * @param {object} [config] The page's source config, for a source that builds its tabs from it.
+ * @param {object} [context] The page's helpers a source may use, such as `translate` (the app's catalogue).
  *
  * @return {object|null} The adapter, or null when the name is not registered.
  */
-export function resolveIndexSource(name, config) {
+export function resolveIndexSource(name, config, context) {
 	const key = String(name || '')
 	if (!key) {
 		return null
@@ -1141,7 +1288,7 @@ export function resolveIndexSource(name, config) {
 		return null
 	}
 
-	return factory(config || {})
+	return factory(config || {}, context || {})
 }
 
 /**

package/src/composables/useEndpointSource.js

@@ -155,7 +155,7 @@ export function interpolateUrlTokens(str, ctx) {
  *
  * @param {{url: string, method?: string, params?: object}} config The endpointSource block.
  * @param {{objectId?: (string|number), object?: object, workspace?: object, config?: object, range?: object}} [ctx] The token context.
- * @return {{url: string, method: ('GET'|'POST'), params: object, blocked: boolean}} The resolved request.
+ * @return {{url: string, method: ('GET'|'POST'), params: object, blocked: boolean, responsePath: string}} The resolved request.
  */
 export function resolveEndpointRequest(config, ctx) {
 	const cfg = config || {}
@@ -163,8 +163,30 @@ export function resolveEndpointRequest(config, ctx) {
 	const resolved = resolveFilterTokens(cfg.params || {}, ctx)
 	const params = dropOptionalUnresolved(resolved)
 	const method = String(cfg.method || 'GET').toUpperCase() === 'POST' ? 'POST' : 'GET'
-	const blocked = hasUnresolvedTokens(params) || hasEmptyPathSegment(cfg.url || '', url)
-	return { url, method, params, blocked }
+	const responsePath = resolveResponsePath(cfg.responsePath, ctx)
+	const blocked = hasUnresolvedTokens(params) || hasEmptyPathSegment(cfg.url || '', url) || responsePath === null
+	return { url, method, params, blocked, responsePath: responsePath || '' }
+}
+
+/**
+ * Resolve the tokens in a `responsePath` (`phaseDays.@workspace.measure`), so a
+ * page control can choose which part of one response a widget reads. Null when
+ * a token resolved to nothing and left an empty path segment: the read waits
+ * instead of plucking the wrong part.
+ *
+ * @param {string|undefined} path The configured path.
+ * @param {object} [ctx] The token context.
+ * @return {string|null} The resolved path, '' for none, null when blocked.
+ */
+function resolveResponsePath(path, ctx) {
+	if (typeof path !== 'string' || path === '') {
+		return ''
+	}
+	if (path.indexOf('@') === -1) {
+		return path
+	}
+	const resolved = interpolateUrlTokens(path, ctx)
+	return resolved.split('.').some((segment) => segment === '') ? null : resolved
 }
 
 /**
@@ -309,7 +331,7 @@ export async function fetchEndpointSource(config, ctx, opts) {
 		return null
 	}
 	const body = await fetchSharedResponse(request, opts)
-	const payload = getByPath(body, config.responsePath)
+	const payload = getByPath(body, request.responsePath)
 	return payload === undefined ? null : payload
 }
 
@@ -378,7 +400,7 @@ export function useEndpointSource(source, options) {
 			u: request.url,
 			m: request.method,
 			p: request.params,
-			r: cfg.responsePath || '',
+			r: request.responsePath,
 			b: request.blocked,
 		})
 	})
@@ -418,7 +440,7 @@ export function useEndpointSource(source, options) {
 			if (seq !== fetchSeq) {
 				return
 			}
-			const payload = getByPath(body, cfg.responsePath)
+			const payload = getByPath(body, request.responsePath)
 			data.value = payload === undefined ? null : payload
 		} catch (e) {
 			if (seq !== fetchSeq) {

package/src/css/index-page.css

@@ -73,6 +73,123 @@
 	min-height: 300px;
 }
 
+/* The map with its numbered list (`mapConfig.list`, DqZakenKaart): one framed
+   card, the map taking the larger share and the list beside it, stacking
+   under a narrow width. */
+.cn-index-page__map-card {
+	display: flex;
+	flex: 1;
+	flex-wrap: wrap;
+	gap: 16px;
+	min-height: 0;
+	padding: 16px;
+	border: 1px solid var(--color-border);
+	border-radius: var(--cn-board-card-radius, 12px);
+	background: var(--color-main-background);
+}
+
+.cn-index-page__map-card .cn-index-page__map {
+	flex: 3 1 420px;
+	min-width: 0;
+}
+
+.cn-index-page__map-side {
+	display: flex;
+	flex: 2 1 320px;
+	flex-direction: column;
+	gap: 12px;
+	min-width: 0;
+	overflow-y: auto;
+}
+
+.cn-index-page__map-list {
+	display: flex;
+	flex-direction: column;
+	margin: 0;
+	padding: 0;
+	border: 1px solid var(--color-border);
+	border-radius: 10px;
+	list-style: none;
+}
+
+.cn-index-page__map-item {
+	display: flex;
+	gap: 12px;
+	padding: 12px 14px;
+}
+
+.cn-index-page__map-item + .cn-index-page__map-item {
+	border-top: 1px solid var(--color-border);
+}
+
+.cn-index-page__map-item--active {
+	background: var(--color-primary-element-light);
+}
+
+.cn-index-page__map-number {
+	display: inline-flex;
+	flex: none;
+	align-items: center;
+	justify-content: center;
+	width: 26px;
+	height: 26px;
+	border-radius: 13px;
+	background: var(--color-primary-element);
+	color: var(--color-primary-element-text);
+	font-size: 13px;
+	font-weight: 700;
+}
+
+.cn-index-page__map-item--active .cn-index-page__map-number {
+	background: var(--color-primary-element-light-text);
+}
+
+.cn-index-page__map-text {
+	display: flex;
+	flex: 1;
+	flex-direction: column;
+	gap: 4px;
+	min-width: 0;
+}
+
+.cn-index-page__map-title {
+	margin: 0;
+	padding: 0;
+	border: 0;
+	background: none;
+	color: var(--color-main-text);
+	font: inherit;
+	font-size: 15px;
+	font-weight: 600;
+	line-height: 1.35;
+	text-align: start;
+	cursor: pointer;
+}
+
+.cn-index-page__map-sub,
+.cn-index-page__map-due {
+	color: var(--color-text-maxcontrast);
+	font-size: 13px;
+}
+
+.cn-index-page__map-pills {
+	display: flex;
+	flex-wrap: wrap;
+	align-items: center;
+	gap: 6px;
+}
+
+.cn-index-page__map-missing {
+	display: flex;
+	flex-direction: column;
+	align-items: flex-start;
+	gap: 8px;
+	padding: 14px;
+	border: 1px solid var(--color-border);
+	border-radius: 10px;
+	font-size: 14px;
+}
+
 /* Opt-in folder navigation pane (left of the list). */
 .cn-index-page__folder-pane {
 	flex: 0 0 240px;

package/src/css/look-board.css

@@ -99,6 +99,50 @@
 	padding-inline-start: 56px;
 }
 
+/* The dashboard header as the board draws it (DqTermijnen): the actions on
+   the title's row, the description and its segmented period under both, at
+   the header's full width. As two flex columns the description sat in the
+   title's column only, so a long period group wrapped under its text and the
+   actions dropped to a line of their own. The title column never shrinks
+   below its longest word; the actions wrap their buttons first.
+   @spec openspec/changes/dashboard-board-header-row/specs/dashboard-page/spec.md#requirement-the-board-dashboard-header-keeps-its-actions-on-the-title-row */
+.cn-look-board .cn-dashboard-page:not(.cn-look-nextcloud *) .cn-dashboard-page__header {
+	display: grid;
+	grid-template-columns: minmax(min-content, 1fr) auto;
+	align-items: start;
+	column-gap: 16px;
+	row-gap: 0;
+}
+
+.cn-look-board .cn-dashboard-page:not(.cn-look-nextcloud *) .cn-dashboard-page__header-left {
+	display: contents;
+}
+
+.cn-look-board .cn-dashboard-page:not(.cn-look-nextcloud *) .cn-dashboard-page__title-row {
+	grid-column: 1;
+	grid-row: 1;
+	align-self: center;
+}
+
+.cn-look-board .cn-dashboard-page:not(.cn-look-nextcloud *) .cn-dashboard-page__header-left > :not(.cn-dashboard-page__title-row) {
+	grid-column: 1 / -1;
+}
+
+.cn-look-board .cn-dashboard-page:not(.cn-look-nextcloud *) .cn-dashboard-page__header > .cn-dashboard-page__header-actions {
+	grid-column: 2;
+	grid-row: 1;
+	justify-content: flex-end;
+	margin-inline-start: 0;
+}
+
+/* A stat tile in the board's KPI row carries the board's own 18px 20px inset
+   (`cn-kpi-card--board`), so the card-fit cell adds none of its own: with
+   both the label sat 29px from the tile's top and 37px from its side, and
+   the row stood about 1.4 times the board's height. */
+.cn-look-board .cn-dashboard-page:not(.cn-look-nextcloud *) .cn-dashboard-page__kpi-cell .cn-dashboard-page__card-fit .cn-widget-wrapper__content:has(> .cn-kpi-card--board.cn-kpi-card--stacked) {
+	padding: 0;
+}
+
 /* ---- The header button ------------------------------------------------- */
 .cn-look-board .cn-index-page__header-buttons:not(.cn-look-nextcloud *),
 .cn-look-board .cn-detail-page__header-actions:not(.cn-look-nextcloud *),

package/src/index.js

@@ -158,6 +158,7 @@ export {
 	CnGaugeWidget,
 	CnGaugeWidgetForm,
 	CnGraphCanvas,
+	CnGroupedCardsWidget,
 	CnGuardianHome,
 	CnHeaderWidget,
 	CnHeaderWidgetForm,

package/src/schemas/app-manifest-v2.schema.json

@@ -3,7 +3,7 @@
 	"$id": "https://raw.githubusercontent.com/ConductionNL/nextcloud-vue/main/src/schemas/app-manifest-v2.schema.json",
 	"title": "Conduction App Manifest v2",
 	"description": "v2 schema for the JSON-driven page and navigation manifest consumed by @conduction/nextcloud-vue. Introduces a uniform widgets[] array on every page type with a per-slot grid coordinate system, a typed actions[] discriminator, and the required $schema field for version detection. v1 manifests continue to validate against app-manifest.schema.json (unchanged).",
-	"version": "2.123.0",
+	"version": "2.124.0",
 	"type": "object",
 	"required": ["$schema", "version"],
 	"allOf": [
@@ -98,6 +98,7 @@
 							"title": { "type": "string" },
 							"body": { "type": "string", "description": "info: explanatory copy." },
 							"note": { "type": "string", "minLength": 1, "description": "choice: a footnote under the options, translated like body." },
+							"visibleWhen": { "description": "Offer the step only when the setup status says so: a dotted path into the setup status document whose value must be truthy, or { path, equals } for an exact value. Hidden while the status loads.", "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "object", "required": ["path"], "additionalProperties": false, "properties": { "path": { "type": "string", "minLength": 1 }, "equals": {} } } ] },
 							"footnote": { "type": "string", "minLength": 1, "description": "choice: the same footnote under another name; note wins when both are set." },
 							"required": { "type": "boolean", "default": false, "description": "When true the step gates the app until done." },
 							"schema": { "description": "config-fields: a JSON Schema ref (string) or inline object rendered via fieldsFromSchema." },
@@ -4372,6 +4373,35 @@
 							"default": true,
 							"description": "type='dashboard' and type='detail': `false` drops the overflow Actions menu from every widget that does not set `showActions` itself, for a dashboard whose widget headers carry a header link and nothing else (zuiddrecht-pixel-gaps-2), or a record page whose data cards carry none (zuiddrecht-pixel-gaps-3; a card with an Add action keeps it). When the key is not set a detail page keeps the menu, except under the board look, where side cards carry none (screens-detail-page-parity). Maps to CnDashboardPage / CnDetailPage `showWidgetActions`."
 						},
+						"pageFilters": {
+							"type": "array",
+							"description": "type='dashboard': page-level filter controls in the header. Each selection is written into the page's workspace context, so a widget reads it through a `@page.<key>` / `@workspace.<key>` token (an endpoint widget also in its `responsePath`). Maps to the CnDashboardPage `pageFilters` prop.",
+							"items": {
+								"type": "object",
+								"required": ["key", "options"],
+								"additionalProperties": false,
+								"properties": {
+									"key": { "type": "string", "minLength": 1, "description": "Workspace-context key written on change (the `@page.<key>` / `@workspace.<key>` token name)." },
+									"label": { "type": "string", "description": "Control label (i18n key or plain text)." },
+									"type": { "type": "string", "enum": ["select"], "default": "select", "description": "Control type, carried over from v1." },
+									"control": { "type": "string", "enum": ["select", "segmented"], "default": "select", "description": "How the filter is drawn: a select, or a compact segmented group." },
+									"placement": { "type": "string", "enum": ["row", "description"], "default": "row", "description": "Where the filter sits: in the header's filter row, or (a segmented group) on the description line after the period group (DqProcesanalyse)." },
+									"default": { "type": ["string", "number"], "description": "Initial value seeded into the context on mount; the first option's value when omitted." },
+									"options": {
+										"type": "array",
+										"items": {
+											"type": "object",
+											"required": ["value", "label"],
+											"additionalProperties": false,
+											"properties": {
+												"value": { "type": ["string", "number"], "description": "Value written into the context when picked." },
+												"label": { "type": "string", "description": "Display text (i18n key or plain text)." }
+											}
+										}
+									}
+								}
+							}
+						},
 						"kpiRow": {
 							"type": "array",
 							"items": { "type": "string" },

package/src/utils/languageMapText.js

@@ -0,0 +1,46 @@
+/**
+ * SPDX-FileCopyrightText: 2026 Conduction B.V.
+ * SPDX-License-Identifier: EUPL-1.2
+ */
+
+import { getLanguage } from '@nextcloud/l10n'
+
+/**
+ * The user's Nextcloud language as a bare code (`nl_NL` reads `nl`), or ''.
+ *
+ * @return {string} The code.
+ */
+function userLanguage() {
+	try {
+		return String(getLanguage() || '').split(/[-_]/)[0].toLowerCase()
+	} catch {
+		return ''
+	}
+}
+
+/**
+ * The text of a value that may be a language map (`{ nl: 'Ontvangst', en:
+ * 'Intake' }`), in the user's Nextcloud language, then Dutch, then English,
+ * then the first text it holds. A plain value comes back as text; anything
+ * else as ''.
+ *
+ * @param {(string|number|object|null|undefined)} value The value.
+ * @return {string} The text.
+ * @spec openspec/changes/grouped-cards-widget/specs/grouped-cards-widget/spec.md#requirement-a-widget-draws-groups-of-cards-from-an-endpoint
+ */
+export function languageMapText(value) {
+	if (typeof value === 'string' || typeof value === 'number') {
+		return String(value)
+	}
+	if (!value || typeof value !== 'object' || Array.isArray(value)) {
+		return ''
+	}
+	const language = userLanguage()
+	for (const key of [language, 'nl', 'en']) {
+		if (key && typeof value[key] === 'string' && value[key] !== '') {
+			return value[key]
+		}
+	}
+	const first = Object.values(value).find((text) => typeof text === 'string' && text !== '')
+	return first || ''
+}

package/src/utils/libraryWidgetKeys.js

@@ -71,6 +71,8 @@ export const BUILT_IN_WIDGET_KEYS = Object.freeze([
 	'header',
 	'text',
 	'divider',
+	'saved-view-alert',
+	'exports',
 ])
 
 /**
@@ -109,6 +111,7 @@ export const DASHBOARD_CATALOG_WIDGET_KEYS = Object.freeze([
 	'files',
 	'flow-runs',
 	'gauge',
+	'grouped-cards',
 	'header',
 	'image',
 	'interaction-form',