@conduction/nextcloud-vue 2.97.0 → 2.98.0

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.121.0",
+	"version": "2.122.0",
 	"type": "object",
 	"required": ["$schema", "version"],
 	"allOf": [
@@ -1296,6 +1296,7 @@
 						"filter": { "type": "object", "additionalProperties": true }
 					}
 				},
+				"resolve": { "type": "object", "additionalProperties": false, "required": ["register", "schema"], "description": "detail-pill-resolve: the field holds the id of a record of this register and schema; the pill shows that record's `labelField` (else its title or name) and keys `colorMap` by it. The raw value shows while the lookup runs and when it finds nothing.", "properties": { "register": { "type": "string", "minLength": 1 }, "schema": { "type": "string", "minLength": 1 }, "labelField": { "type": "string", "minLength": 1 } } },
 				"countLabel": {
 					"type": "object",
 					"additionalProperties": false,
@@ -2229,6 +2230,35 @@
 											"columnKeys": { "type": "array", "items": { "type": ["string", "number"] } }
 										}
 									},
+									"cellSource": {
+										"type": "object",
+										"additionalProperties": false,
+										"required": ["register", "schema", "rowField", "columnField", "valueField"],
+										"description": "chartKind 'matrix': read the cells from records that each hold one cell. The records are listed from register/schema with `filter` (tokens such as '@object.matrixVersion' resolved; the list waits while one is unresolved), then laid out by rowField / columnField with valueField as the cell. Labels come from rowLabels / columnLabels maps or rowLabelField / columnLabelField; order from rowOrder / columnOrder lists, else rowOrderField / columnOrderField, else natural order. valueLabels maps a stored value to the text shown; colorMap may key on either. With cellsPath the matrix sits inside ONE record: the first record filter finds (else fallbackFilter), its array at cellsPath narrowed by cellFilter (tokens allowed), and the axis order from rowOrderPath / columnOrderPath on that record. Wins over series / categories.",
+										"properties": {
+											"register": { "type": "string" },
+											"schema": { "type": "string" },
+											"filter": { "type": "object", "additionalProperties": true },
+											"rowField": { "type": "string" },
+											"columnField": { "type": "string" },
+											"valueField": { "type": "string" },
+											"rowLabelField": { "type": "string" },
+											"columnLabelField": { "type": "string" },
+											"rowLabels": { "type": "object", "additionalProperties": { "type": "string" } },
+											"columnLabels": { "type": "object", "additionalProperties": { "type": "string" } },
+											"valueLabels": { "type": "object", "additionalProperties": { "type": "string" } },
+											"rowOrder": { "type": "array", "items": { "type": ["string", "number"] } },
+											"columnOrder": { "type": "array", "items": { "type": ["string", "number"] } },
+											"rowOrderField": { "type": "string" },
+											"columnOrderField": { "type": "string" },
+											"limit": { "type": "integer", "minimum": 1 },
+											"cellsPath": { "type": "string", "description": "Path of the cells array inside the one record the source finds." },
+											"cellFilter": { "type": "object", "additionalProperties": true, "description": "Equality filter on the cells of that record, e.g. { actorType: '@object.actorType' }." },
+											"fallbackFilter": { "type": "object", "additionalProperties": true, "description": "Filter used when `filter` finds no record, e.g. { active: true }." },
+											"rowOrderPath": { "type": "string", "description": "Path of an array on that record giving the row order." },
+											"columnOrderPath": { "type": "string", "description": "Path of an array on that record giving the column order." }
+										}
+									},
 									"endpointSource": {
 										"$ref": "#/$defs/chartEndpointSource",
 										"description": "Wave 2 (#91): endpoint-bound series/labels — the shared endpoint transport plus the labelsPath / series[] {name, path} response mapping. Exactly one of dataSource | endpointSource (post-schema check)."
@@ -3702,8 +3732,8 @@
 						},
 						"entitySource": {
 							"type": "string",
-							"enum": ["flows", "flowRuns", "tasks", "endpoint", "search", "users"],
-							"description": "Name a registered NON-OBJECT entity collection for a type='index' page, instead of register+schema. Deliberately NOT called `source`: that key is already taken on page config and is polymorphic (a URL string in some manifests, an object with `params` in others), so reusing it would give one key two meanings and break six deployed shillinq pages. A flow definition is deliberately not an OpenRegister object, so an index had nothing to bind to and such lists became bespoke type='custom' pages. With a source the index loads the list itself. Takes precedence over register/schema; non-empty `objects` still wins over both. Registered sources live in src/composables/indexSources.js. `tasks` lists the viewer's task inbox from OpenRegister's flow-tasks read (cn-tasks-entity-source)."
+							"enum": ["flows", "flowRuns", "tasks", "endpoint", "search", "users", "organisations"],
+							"description": "Name a registered NON-OBJECT entity collection for a type='index' page, instead of register+schema. Deliberately NOT called `source`: that key is already taken on page config and is polymorphic (a URL string in some manifests, an object with `params` in others), so reusing it would give one key two meanings and break six deployed shillinq pages. A flow definition is deliberately not an OpenRegister object, so an index had nothing to bind to and such lists became bespoke type='custom' pages. With a source the index loads the list itself. Takes precedence over register/schema; non-empty `objects` still wins over both. Registered sources live in src/composables/indexSources.js. `tasks` lists the viewer's task inbox from OpenRegister's flow-tasks read (cn-tasks-entity-source). `organisations` lists the OpenRegister organisations the viewer belongs to. On a type='detail' page a source that reads one record (today `organisations`) loads the record whose id is the route's objectId, instead of register+schema, and feeds the header, pills, widgets and @objectId / @object.* tokens like a fetched object (organisations-entity-source)."
 						},
 						"sourceConfig": { "type": "object", "additionalProperties": true, "description": "type='index' with `entitySource`: what the named source loads with. `endpoint`: `url` (an app path, required) and `rowsPath` (default `results`); its other keys go along as query parameters. `search`: `kinds` (`{ id, label, register, schema, titleField?, subtitleField?, statusField?, href?, limit? }` or `{ id, label, files: true }`), `term` and `termQuery` (default `q`). `users`: `defaultGroup`, `functionField`, `rolesField`. `flows` / `tasks`: `app`, `scope`. Maps to CnIndexPage `sourceConfig`.", "properties": { "url": { "type": "string", "minLength": 1 }, "rowsPath": { "type": "string", "minLength": 1 }, "kinds": { "type": "array", "items": { "type": "object", "required": ["id"], "additionalProperties": true, "properties": { "id": { "type": "string", "minLength": 1 }, "label": { "type": "string" }, "register": { "type": "string" }, "schema": { "type": "string" }, "files": { "type": "boolean" } } } }, "term": { "type": "string" }, "termQuery": { "type": "string", "minLength": 1 }, "defaultGroup": { "type": "string", "minLength": 1 } } },
 						"app": {

package/src/utils/builtInFormatters.js

@@ -417,6 +417,38 @@ export function formatConnectionSettingsLabel(value) {
 		: ''
 }
 
+/**
+ * Show a value with all but its last characters replaced by `*`, as the facts
+ * widget's `masked` format does: an IBAN or a BSN reads `*****4567`.
+ *
+ * DISPLAY ONLY, NOT ACCESS CONTROL. The full value is still in the row the
+ * page received; a reader with the browser's developer tools can read it.
+ * A value the reader must not have belongs hidden in OpenRegister (property
+ * authorization), not masked here.
+ *
+ * The column's `formatterOptions.visible` sets how many characters stay
+ * (default 4); at most five `*` are drawn, so the length does not leak.
+ * Null-safe: `''` for null or empty.
+ *
+ * @param {unknown} value The value.
+ * @param {object} [_row] The full row (unused).
+ * @param {object} [_property] The schema property (unused).
+ * @param {{visible?: number}} [options] The column's `formatterOptions`.
+ * @return {string} The masked value.
+ * @spec openspec/changes/masked-formatter-max-aggregate/specs/index-page/spec.md#requirement-a-column-can-mask-its-value-for-display
+ */
+export function formatMasked(value, _row, _property, options) {
+	if (value === null || value === undefined || value === '') {
+		return ''
+	}
+	const text = String(value)
+	const visible = Number.isInteger(options && options.visible) && options.visible >= 0 ? options.visible : 4
+	if (text.length <= visible) {
+		return text
+	}
+	return '*'.repeat(Math.min(text.length - visible, 5)) + (visible > 0 ? text.slice(-visible) : '')
+}
+
 /**
  * Built-in formatter registry merged under any consumer-registered
  * `formatters` in `CnAppRoot`'s `cnFormatters` provide.
@@ -433,4 +465,5 @@ export const BUILT_IN_FORMATTERS = {
 	count: formatCount,
 	connectionStatus: formatConnectionStatus,
 	connectionSettingsLabel: formatConnectionSettingsLabel,
+	masked: formatMasked,
 }

package/src/utils/libraryWidgetKeys.js

@@ -93,6 +93,7 @@ export const DASHBOARD_CATALOG_WIDGET_KEYS = Object.freeze([
 	'banner',
 	'calendar',
 	'chart',
+	'checklist-run',
 	'chips-field',
 	'choice-picker',
 	'container',

package/src/utils/matrixCells.js

@@ -0,0 +1,154 @@
+/**
+ * SPDX-FileCopyrightText: 2026 Conduction B.V.
+ * SPDX-License-Identifier: EUPL-1.2
+ *
+ * matrixCells: lay out records that each hold one matrix cell as the rows and
+ * columns a `matrix` chart draws.
+ *
+ * A matrix kept as data is often stored one record per cell: the row it sits
+ * in, the column, and the value. This turns such a list into one series per
+ * row with a value per column, in a stable order, so the chart reads the same
+ * matrix the app computes with instead of a copy written into a manifest.
+ *
+ * @module utils/matrixCells
+ * @spec openspec/changes/matrix-cell-records/specs/matrix-cell-records/spec.md#requirement-a-matrix-can-read-its-cells-from-records
+ */
+
+import { readPath } from './readPath.js'
+
+/**
+ * A stored key as text, or null when there is none.
+ *
+ * @param {unknown} value The stored value.
+ * @return {string|null} The key.
+ */
+function keyOf(value) {
+	if (value === null || value === undefined || value === '' || typeof value === 'object') {
+		return null
+	}
+	return String(value)
+}
+
+/**
+ * The keys in the order they are drawn: the listed order first, then keys
+ * with an order value (lowest first), then the rest in natural order.
+ *
+ * @param {Map<string, {order: number}>} found The keys seen, with their lowest order value.
+ * @param {Array<string|number>|undefined} listed An explicit order.
+ * @return {string[]} The ordered keys.
+ */
+function orderKeys(found, listed) {
+	const explicit = Array.isArray(listed) ? listed.map((k) => String(k)).filter((k) => found.has(k)) : []
+	const rest = [...found.keys()].filter((k) => !explicit.includes(k))
+	rest.sort((a, b) => {
+		const oa = found.get(a).order
+		const ob = found.get(b).order
+		if (oa !== ob) {
+			return oa - ob
+		}
+		return a.localeCompare(b, undefined, { numeric: true })
+	})
+	return [...explicit, ...rest]
+}
+
+/**
+ * Lay out cell records as matrix rows and columns.
+ *
+ * Config: `rowField`, `columnField`, `valueField` (paths on a record);
+ * optional `rowLabelField` / `columnLabelField` (a path holding the label),
+ * `rowLabels` / `columnLabels` (key to label maps, these win), `rowOrder` /
+ * `columnOrder` (keys in order) and `rowOrderField` / `columnOrderField` (a
+ * numeric path to sort by). A record without a row or column is skipped; when
+ * two records name the same cell, the first wins.
+ *
+ * @param {Array<object>} records The cell records.
+ * @param {object} config The `cellSource` config.
+ * @return {{series: Array<{key: string, name: string, data: Array<unknown>}>, categories: string[], columnKeys: string[]}} The matrix.
+ * @spec openspec/changes/matrix-cell-records/specs/matrix-cell-records/spec.md#requirement-a-matrix-can-read-its-cells-from-records
+ */
+export function pivotCells(records, config) {
+	const cfg = config && typeof config === 'object' ? config : {}
+	const rows = new Map()
+	const columns = new Map()
+	const cells = new Map()
+	const note = (map, key, label, order) => {
+		const entry = map.get(key)
+		const value = Number(order)
+		const rank = Number.isFinite(value) ? value : Infinity
+		if (!entry) {
+			map.set(key, { label, order: rank })
+		} else {
+			entry.order = Math.min(entry.order, rank)
+			entry.label = entry.label || label
+		}
+	}
+	for (const record of Array.isArray(records) ? records : []) {
+		if (!record || typeof record !== 'object') {
+			continue
+		}
+		const row = keyOf(readPath(record, cfg.rowField))
+		const column = keyOf(readPath(record, cfg.columnField))
+		if (row === null || column === null) {
+			continue
+		}
+		note(rows, row, cfg.rowLabelField ? keyOf(readPath(record, cfg.rowLabelField)) : null, cfg.rowOrderField ? readPath(record, cfg.rowOrderField) : undefined)
+		note(columns, column, cfg.columnLabelField ? keyOf(readPath(record, cfg.columnLabelField)) : null, cfg.columnOrderField ? readPath(record, cfg.columnOrderField) : undefined)
+		const cell = `${row}\u0000${column}`
+		if (!cells.has(cell)) {
+			const value = readPath(record, cfg.valueField)
+			cells.set(cell, value === undefined ? null : value)
+		}
+	}
+	const rowKeys = orderKeys(rows, cfg.rowOrder)
+	const columnKeys = orderKeys(columns, cfg.columnOrder)
+	const labelOf = (key, map, labels) => {
+		if (labels && typeof labels === 'object' && typeof labels[key] === 'string') {
+			return labels[key]
+		}
+		return map.get(key).label || key
+	}
+	return {
+		series: rowKeys.map((row) => ({
+			key: row,
+			name: labelOf(row, rows, cfg.rowLabels),
+			data: columnKeys.map((column) => {
+				const value = cells.get(`${row}\u0000${column}`)
+				return value === undefined ? null : value
+			}),
+		})),
+		categories: columnKeys.map((column) => labelOf(column, columns, cfg.columnLabels)),
+		columnKeys,
+	}
+}
+
+/**
+ * The cells of a matrix kept inside ONE record: the array at `cellsPath`,
+ * narrowed by `cellFilter` (field to value, compared as text), with the axis
+ * order read from `rowOrderPath` / `columnOrderPath` on the record when the
+ * config gives no `rowOrder` / `columnOrder` list.
+ *
+ * @param {object|null} record The record that holds the matrix.
+ * @param {object} config The `cellSource` config.
+ * @param {object} [cellFilter] The `cellFilter`, tokens already resolved.
+ * @return {{cells: Array<object>, config: object}} The cells, and the config to lay them out with.
+ * @spec openspec/changes/matrix-cell-records/specs/matrix-cell-records/spec.md#requirement-a-matrix-can-read-its-cells-from-one-record
+ */
+export function cellsFromRecord(record, config, cellFilter = {}) {
+	const cfg = config && typeof config === 'object' ? config : {}
+	const list = record ? readPath(record, cfg.cellsPath) : null
+	const wanted = Object.entries(cellFilter && typeof cellFilter === 'object' ? cellFilter : {})
+	const cells = (Array.isArray(list) ? list : []).filter((cell) => cell && typeof cell === 'object'
+		&& wanted.every(([field, value]) => keyOf(readPath(cell, field)) === keyOf(value)))
+	const axis = (path) => {
+		const value = record && path ? readPath(record, path) : null
+		return Array.isArray(value) ? value : undefined
+	}
+	return {
+		cells,
+		config: {
+			...cfg,
+			rowOrder: Array.isArray(cfg.rowOrder) ? cfg.rowOrder : axis(cfg.rowOrderPath),
+			columnOrder: Array.isArray(cfg.columnOrder) ? cfg.columnOrder : axis(cfg.columnOrderPath),
+		},
+	}
+}

package/src/utils/nextcloudDirectory.js

@@ -0,0 +1,117 @@
+/**
+ * SPDX-FileCopyrightText: 2026 Conduction B.V.
+ * SPDX-License-Identifier: EUPL-1.2
+ */
+
+import { generateOcsUrl } from '@nextcloud/router'
+
+/**
+ * Nextcloud's own directory: groups, the users in a group, and whether a
+ * user is in today. Read through the OCS API with the reader's session, so
+ * Nextcloud decides what the reader may see (listing a group's members needs
+ * an admin or the group's sub-admin).
+ *
+ * @module utils/nextcloudDirectory
+ */
+
+const OCS_HEADERS = { 'OCS-APIRequest': 'true' }
+
+/**
+ * The `ocs.data` of an OCS response, or null.
+ *
+ * @param {object} res An axios response.
+ * @return {object|null}
+ */
+function ocsData(res) {
+	return (res && res.data && res.data.ocs && res.data.ocs.data) || null
+}
+
+/**
+ * The groups, with their member counts.
+ *
+ * @param {object} axios The axios instance.
+ * @param {{search?: string, limit?: number}} [options] Narrowing.
+ * @return {Promise<Array<{id: string, name: string, count: number}>>}
+ * @spec openspec/changes/index-groups-users-source/specs/index-page/spec.md#requirement-an-index-page-can-list-nextcloud-groups-and-their-members
+ */
+export async function fetchGroups(axios, options = {}) {
+	const res = await axios.get(generateOcsUrl('cloud/groups/details'), {
+		params: { search: options.search || '', limit: options.limit || 200, format: 'json' },
+		headers: OCS_HEADERS,
+	})
+	const groups = (ocsData(res) && ocsData(res).groups) || []
+	return groups.map((group) => ({
+		id: String(group.id),
+		name: group.displayname || String(group.id),
+		count: Number(group.usercount) || 0,
+	}))
+}
+
+/**
+ * The members of one group, with their details.
+ *
+ * @param {object} axios The axios instance.
+ * @param {string} groupId The group id.
+ * @return {Promise<Array<object>>} Nextcloud's user details, one per member.
+ * @spec openspec/changes/index-groups-users-source/specs/index-page/spec.md#requirement-an-index-page-can-list-nextcloud-groups-and-their-members
+ */
+export async function fetchGroupMembers(axios, groupId) {
+	const res = await axios.get(generateOcsUrl('cloud/groups/{groupId}/users/details', { groupId }), {
+		params: { format: 'json' },
+		headers: OCS_HEADERS,
+	})
+	const users = (ocsData(res) && ocsData(res).users) || {}
+	return Array.isArray(users) ? users : Object.values(users)
+}
+
+/**
+ * Whether a user is in today: an out-of-office period that runs now (the
+ * dav app's absence, Nextcloud 28 and later), else their user status.
+ *
+ * @param {object} axios The axios instance.
+ * @param {string} userId The user id.
+ * @param {object|null} status The user's entry from the user status list, or null.
+ * @return {Promise<{state: string, until: (string|null), message: string}>}
+ *   `state` is `absent` (with `until`, an ISO date), `away`, `present` or `unknown`.
+ * @spec openspec/changes/index-groups-users-source/specs/index-page/spec.md#requirement-an-index-page-can-list-nextcloud-groups-and-their-members
+ */
+export async function fetchPresence(axios, userId, status) {
+	try {
+		const res = await axios.get(generateOcsUrl('apps/dav/api/v1/outOfOffice/{userId}/now', { userId }), { params: { format: 'json' }, headers: OCS_HEADERS })
+		const ooo = ocsData(res)
+		if (ooo && ooo.endDate) {
+			const end = typeof ooo.endDate === 'number' ? new Date(ooo.endDate * 1000) : new Date(ooo.endDate)
+			return { state: 'absent', until: Number.isNaN(end.getTime()) ? null : end.toISOString().slice(0, 10), message: ooo.shortMessage || '' }
+		}
+	} catch {
+		// 404: no absence now, or an instance without the absence API.
+	}
+	if (status && typeof status === 'object') {
+		const message = typeof status.message === 'string' ? status.message : ''
+		if (status.status === 'online') {
+			return { state: 'present', until: null, message }
+		}
+		if (status.status === 'away' || status.status === 'dnd') {
+			return { state: 'away', until: null, message }
+		}
+	}
+	return { state: 'unknown', until: null, message: '' }
+}
+
+/**
+ * The user statuses Nextcloud shares with the reader, by user id. Empty when
+ * the user status app is off.
+ *
+ * @param {object} axios The axios instance.
+ * @return {Promise<Record<string, object>>}
+ * @spec openspec/changes/index-groups-users-source/specs/index-page/spec.md#requirement-an-index-page-can-list-nextcloud-groups-and-their-members
+ */
+export async function fetchStatuses(axios) {
+	try {
+		const res = await axios.get(generateOcsUrl('apps/user_status/api/v1/statuses'), { params: { limit: 500, format: 'json' }, headers: OCS_HEADERS })
+		const list = ocsData(res) || []
+		return Object.fromEntries((Array.isArray(list) ? list : []).map((entry) => [entry.userId, entry]))
+	} catch {
+		return {}
+	}
+}