@conduction/nextcloud-vue 2.83.0 → 2.85.0

package/src/utils/detailWidgetVisibility.js

@@ -0,0 +1,145 @@
+/**
+ * SPDX-FileCopyrightText: 2026 Conduction B.V.
+ * SPDX-License-Identifier: EUPL-1.2
+ *
+ * detailWidgetVisibility: whether a widget on a detail page shows for the
+ * loaded record, through the shared `visibleWhen` grammar.
+ *
+ * A detail page can name records it reads beside the loaded one
+ * (`visibilityContext`, e.g. a case's case type). A condition reads such a
+ * record as `@context.<name>.<path>`, so a widget can be shown for some case types
+ * only while the configuration stays in the app manifest.
+ *
+ * @module utils/detailWidgetVisibility
+ */
+
+import { cnFetchJson } from './cnFetch.js'
+import { evaluateVisibleWhenLocal, isLocallyDecidableVisibleWhen, isWorkspaceCondition } from './visibleWhen.js'
+
+/**
+ * Read a reference value as an id: a plain string or number, or an object
+ * carrying `id`, `uuid` or `@self.id` (an extended reference).
+ *
+ * @param {unknown} value The value of the reference field.
+ * @return {string} The id, or '' when there is none.
+ */
+function referenceId(value) {
+	if (typeof value === 'string' || typeof value === 'number') {
+		return String(value)
+	}
+	if (value && typeof value === 'object') {
+		const id = value.id ?? value.uuid ?? (value['@self'] && value['@self'].id)
+		return id === undefined || id === null ? '' : String(id)
+	}
+	return ''
+}
+
+/**
+ * The records a `visibilityContext` names for one loaded record.
+ *
+ * @param {object} context `{ <name>: { field, register, schema } }`.
+ * @param {object|null} record The loaded record.
+ * @return {Array<{key: string, register: string, schema: string, id: string}>} One entry per usable name; `id` is '' when the record holds no reference.
+ * @spec openspec/changes/detail-widgets-visible-when/specs/detail-widgets-visible-when/spec.md#requirement-a-detail-page-can-load-records-a-condition-names
+ */
+export function visibilityContextRefs(context, record) {
+	if (!context || typeof context !== 'object' || !record || typeof record !== 'object') {
+		return []
+	}
+	return Object.entries(context)
+		.filter(([name, ref]) => name !== '' && ref && typeof ref === 'object'
+			&& typeof ref.field === 'string' && ref.field !== ''
+			&& typeof ref.register === 'string' && ref.register !== ''
+			&& typeof ref.schema === 'string' && ref.schema !== '')
+		.map(([name, ref]) => ({
+			key: name,
+			register: ref.register,
+			schema: ref.schema,
+			id: referenceId(ref.field.split('.').reduce((obj, part) => (obj === null || obj === undefined ? obj : obj[part]), record)),
+		}))
+}
+
+/**
+ * Read the records `refs` names. A reference without an id, and a read that
+ * fails, resolve `null`: the record is absent, and a condition on it fails
+ * safe rather than throwing out of the page.
+ *
+ * @param {Array<{key: string, register: string, schema: string, id: string}>} refs From {@link visibilityContextRefs}.
+ * @param {Map<string, object|null>} [cache] Rows already read, by `register/schema/id`.
+ * @return {Promise<object>} `{ <name>: row | null }`.
+ * @spec openspec/changes/detail-widgets-visible-when/specs/detail-widgets-visible-when/spec.md#requirement-a-detail-page-can-load-records-a-condition-names
+ */
+export async function fetchVisibilityRows(refs, cache) {
+	const rows = {}
+	await Promise.all((refs || []).map(async (ref) => {
+		if (!ref.id) {
+			rows[ref.key] = null
+			return
+		}
+		const cacheKey = `${ref.register}/${ref.schema}/${ref.id}`
+		if (cache && cache.has(cacheKey)) {
+			rows[ref.key] = cache.get(cacheKey)
+			return
+		}
+		let row
+		try {
+			const body = await cnFetchJson(`/apps/openregister/api/objects/${encodeURIComponent(ref.register)}/${encodeURIComponent(ref.schema)}/${encodeURIComponent(ref.id)}`)
+			row = body && typeof body === 'object' ? body : null
+		} catch {
+			row = null
+		}
+		if (cache) {
+			cache.set(cacheKey, row)
+		}
+		rows[ref.key] = row
+	}))
+	return rows
+}
+
+/**
+ * The data a widget condition reads: the record, with the named records
+ * beside it under `@context.<name>`. Null while the record has not loaded.
+ *
+ * @param {object|null} record The loaded record.
+ * @param {object} [rows] `{ <name>: row | null }`.
+ * @return {object|null} The condition data.
+ * @spec openspec/changes/detail-widgets-visible-when/specs/detail-widgets-visible-when/spec.md#requirement-a-detail-grid-widget-shows-only-while-its-visiblewhen-holds-for-the-record
+ */
+export function widgetConditionData(record, rows) {
+	if (!record || typeof record !== 'object') {
+		return null
+	}
+	return { ...record, '@context': { ...(rows || {}) } }
+}
+
+/**
+ * Whether a widget's own `visibleWhen` lets it show on a detail page.
+ *
+ * No condition: shown, as before. A workspace condition: shown, a detail page
+ * has no workspace. While the data is not there (`data` null, or `pending`):
+ * hidden, so the widget never shows and then vanishes. A local condition is
+ * decided here; an endpoint or source condition takes its answer from
+ * `answers` (by widget id) and is hidden until it has one.
+ *
+ * @param {object|null} widget The widget definition.
+ * @param {object|null} data From {@link widgetConditionData}.
+ * @param {{pending?: boolean, answers?: object}} [state] Whether named records are still on their way, and the remote answers.
+ * @return {boolean} Whether the widget shows.
+ * @spec openspec/changes/detail-widgets-visible-when/specs/detail-widgets-visible-when/spec.md#requirement-a-detail-grid-widget-shows-only-while-its-visiblewhen-holds-for-the-record
+ */
+export function detailWidgetVisible(widget, data, state = {}) {
+	const cond = widget && typeof widget === 'object' ? widget.visibleWhen : null
+	if (cond === null || cond === undefined) {
+		return true
+	}
+	if (typeof cond === 'object' && !Array.isArray(cond) && isWorkspaceCondition(cond)) {
+		return true
+	}
+	if (!data || state.pending === true) {
+		return false
+	}
+	if (isLocallyDecidableVisibleWhen(cond)) {
+		return evaluateVisibleWhenLocal(cond, data)
+	}
+	return Boolean(state.answers && state.answers[widget.id] === true)
+}

package/src/utils/formatMetric.js

@@ -226,6 +226,35 @@ export function metricLocale() {
 	}
 }
 
+/**
+ * A format spec with its literal `prefix` / `suffix` run through the host
+ * translate function. A `@`-token, an empty string, or a missing translate
+ * leaves the affix as written.
+ *
+ * @param {object} format The `content.format` spec.
+ * @param {((text: string) => string)|null} translate The host translate function.
+ * @return {object} A copy of the spec (the same object when nothing changes).
+ * @spec openspec/changes/screens-metric-affix-translate/specs/dashboard-page/spec.md#requirement-a-metric-prefix-and-suffix-are-translated
+ */
+export function translateMetricAffixes(format, translate) {
+	const fmt = format || {}
+	if (typeof translate !== 'function') {
+		return fmt
+	}
+	let out = fmt
+	for (const key of ['prefix', 'suffix']) {
+		const text = fmt[key]
+		if (typeof text === 'string' && text.trim() !== '' && text.charAt(0) !== '@') {
+			const translated = translate(text)
+			if (typeof translated === 'string' && translated !== text) {
+				out = out === fmt ? { ...fmt } : out
+				out[key] = translated
+			}
+		}
+	}
+	return out
+}
+
 /**
  * Format a numeric value per a manifest `content.format` spec.
  *
@@ -250,11 +279,18 @@ export function metricLocale() {
  * @param {unknown}      value     The raw value to format.
  * @param {object} format    The `content.format` spec (`{ style, currency, currencyField, decimals, prefix, suffix }`).
  * @param {object} configCtx The page-level app-config map for `@config.<key>` resolution.
+ * A literal `prefix` / `suffix` (one that is not a `@config.` or `@object.`
+ * token) is run through `translate` when one is given, as every other
+ * manifest-authored string is, so an app's catalogue entry for " days"
+ * (" dagen") applies. A token is resolved, never translated.
+ *
  * @param {object|null} [object] The detail page's object, for `currencyField` and `@object.<field>`.
+ * @param {((text: string) => string)|null} [translate] The host app's translate function (`cnTranslate`).
  * @return {string} The formatted display string.
  * @spec openspec/changes/stat-currency-from-object/specs/dashboard-page/spec.md#requirement-a-money-value-is-shown-in-the-currency-the-entry-names
+ * @spec openspec/changes/screens-metric-affix-translate/specs/dashboard-page/spec.md#requirement-a-metric-prefix-and-suffix-are-translated
  */
-export function formatMetricValue(value, format, configCtx, object = null) {
+export function formatMetricValue(value, format, configCtx, object = null, translate = null) {
 	if (value === null || value === undefined) {
 		return '—'
 	}
@@ -263,7 +299,7 @@ export function formatMetricValue(value, format, configCtx, object = null) {
 		return String(value)
 	}
 
-	const fmt = resolveConfigFormat(format, configCtx, object)
+	const fmt = resolveConfigFormat(translateMetricAffixes(format, translate), configCtx, object)
 	const locale = metricLocale()
 	// `duration-hours` and `decimal` default to ONE fraction digit; the
 	// other styles keep the pre-existing default of 0.

package/src/utils/gridStack.js

@@ -53,3 +53,42 @@ export function readGridGeometry(items) {
 	}
 	return map
 }
+
+/**
+ * Where the items under a growing cell go so they keep their order: every item
+ * the growth would overlap moves down by the growth, and so does every item
+ * that move would overlap in turn. Items beside the cell stay put.
+ *
+ * GridStack resolves the same collision itself, but not in order: when
+ * pipelinq's size-to-content banner grew from two rows to three, the
+ * full-width card under the stat tiles landed below the lists.
+ *
+ * @spec openspec/changes/dashboard-growth-keeps-order/specs/dashboard-grid/spec.md#requirement-a-growing-cell-keeps-the-order-of-the-cards-under-it
+ * @param {Array<{x: number, y: number, w: number, h: number}>} nodes The grid's items (the growing one among them).
+ * @param {{x: number, y: number, w: number, h: number}} node The growing item.
+ * @param {number} h Its new height, in grid rows.
+ * @return {Array<{node: object, y: number}>} The items to move and their new row, bottom-most first.
+ */
+export function planGrowth(nodes, node, h) {
+	const delta = h - node.h
+	if (!(delta > 0)) {
+		return []
+	}
+	const moved = new Map()
+	const overlaps = (a, b) => a.x < b.x + b.w && b.x < a.x + a.w && a.y < b.y + b.h && b.y < a.y + a.h
+	const queue = [{ x: node.x, y: node.y, w: node.w, h }]
+	while (queue.length > 0) {
+		const rect = queue.shift()
+		for (const other of nodes) {
+			if (other === node || moved.has(other) || !overlaps(rect, other)) {
+				continue
+			}
+			const next = { x: other.x, y: other.y + delta, w: other.w, h: other.h }
+			moved.set(other, next.y)
+			queue.push(next)
+		}
+	}
+	return [...moved.entries()]
+		.map(([item, y]) => ({ node: item, y }))
+		.sort((a, b) => b.y - a.y)
+}

package/src/utils/humaniseKey.js

@@ -0,0 +1,38 @@
+/**
+ * SPDX-FileCopyrightText: 2026 Conduction B.V. <info@conduction.nl>
+ * SPDX-License-Identifier: EUPL-1.2
+ *
+ * Make an identifier-shaped key readable for a person. Pure: no Vue.
+ */
+
+/**
+ * Split camelCase, snake_case and kebab-case into words, keep acronyms, and
+ * capitalise only the first word.
+ *
+ * `caseAssigned` → "Case assigned", `object_created` → "Object created",
+ * `newBRPRecord` → "New BRP record".
+ *
+ * @param {string} key The key.
+ * @return {string} A readable sentence-case label, or the key when it has no words.
+ * @spec openspec/changes/data-widget-nested-objects/specs/data-widget-nested-objects/spec.md#requirement-a-nested-object-reads-as-a-list-per-key
+ */
+export function humaniseKey(key) {
+	const words = String(key || '')
+		.replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+		.replace(/([A-Z]+)([A-Z][a-z])/g, '$1 $2')
+		.split(/[\s_\-.]+/)
+		.filter(Boolean)
+	if (words.length === 0) {
+		return String(key || '')
+	}
+	return words
+		.map((word, index) => {
+			const isAcronym = word.length > 1 && word === word.toUpperCase() && /[A-Z]/.test(word)
+			if (isAcronym) {
+				return word
+			}
+			const lower = word.toLowerCase()
+			return index === 0 ? lower.charAt(0).toUpperCase() + lower.slice(1) : lower
+		})
+		.join(' ')
+}

package/src/utils/notificationRuleLabel.js

@@ -28,6 +28,8 @@
  * @spec openspec/changes/notification-rule-labels-and-runtime-version/specs/notification-preferences/spec.md
  */
 
+import { humaniseKey } from './humaniseKey.js'
+
 /**
  * Pick the string for the current language out of a string or per-locale map.
  *
@@ -54,34 +56,14 @@ export function resolveLocalised(value, language = 'en') {
 }
 
 /**
- * Make a rule key readable: split camelCase, snake_case and kebab-case into
- * words, keep acronyms, and capitalise only the first word.
- *
- * `caseAssigned` → "Case assigned", `object_created` → "Object created",
- * `newBRPRecord` → "New BRP record".
+ * Make a rule key readable (`caseAssigned` → "Case assigned"); see `humaniseKey`.
  *
  * @param {string} key The rule key.
  * @return {string} A readable sentence-case label, or the key when it has no words.
+ * @spec openspec/changes/notification-rule-labels-and-runtime-version/specs/notification-preferences/spec.md#requirement-a-notification-rule-reads-as-a-label
  */
 export function humaniseRuleKey(key) {
-	const words = String(key || '')
-		.replace(/([a-z0-9])([A-Z])/g, '$1 $2')
-		.replace(/([A-Z]+)([A-Z][a-z])/g, '$1 $2')
-		.split(/[\s_\-.]+/)
-		.filter(Boolean)
-	if (words.length === 0) {
-		return String(key || '')
-	}
-	return words
-		.map((word, index) => {
-			const isAcronym = word.length > 1 && word === word.toUpperCase() && /[A-Z]/.test(word)
-			if (isAcronym) {
-				return word
-			}
-			const lower = word.toLowerCase()
-			return index === 0 ? lower.charAt(0).toUpperCase() + lower.slice(1) : lower
-		})
-		.join(' ')
+	return humaniseKey(key)
 }
 
 /**

package/src/utils/resolveManifestTokens.js

@@ -56,6 +56,7 @@ export const SENTINEL_RESOLVERS = Object.freeze({
 	answer: 'resolveAssignValue (utils/formAssign.js)',
 	row: 'CnFieldListWidget (rowActions request)',
 	subject: 'CnBannerWidget (action route)',
+	context: 'detailWidgetVisible (utils/detailWidgetVisibility.js)',
 })
 
 /**

package/src/utils/sentinelTokens.js

@@ -89,6 +89,9 @@ export const SENTINEL_TOKEN_PATTERNS = Object.freeze({
 	// A field of the record a start-here attention card names (`@subject.<field>`, dot path),
 	// read by the banner widget's action routes.
 	subject: '^@subject\\.[A-Za-z][A-Za-z0-9_.]*$',
+	// A record a detail page reads beside the loaded one (`visibilityContext`), read by a
+	// grid widget's or a tab's `visibleWhen` as `@context.<name>.<field>` (dot path).
+	context: '^@context\\.[A-Za-z][A-Za-z0-9_.]*$',
 	// Deprecated-but-not-yet-removed tokens. Kept in the schema union so
 	// deployed manifests still validate during the migration window; the gate
 	// downgrades them to a WARN (see SENTINEL_DEPRECATIONS).
@@ -112,6 +115,7 @@ export const SENTINEL_CONTEXTS = Object.freeze([
 	'answer',
 	'row',
 	'subject',
+	'context',
 ])
 
 /**
@@ -172,6 +176,11 @@ export const SENTINEL_VOCABULARY = Object.freeze({
 		description: 'A field of the record an attention card names (the first row of its ordered `visibleWhen` source query), read when the card builds an action\'s route. Dot paths are allowed (`@subject.owner.id`).',
 		members: ['@subject.<field>'],
 	},
+	context: {
+		resolver: 'CnDetailPage visibilityContext (detailWidgetVisibility), read by a grid widget\'s or a tab\'s visibleWhen',
+		description: 'A record the detail page reads beside the loaded one, named in `config.visibilityContext` (a case\'s case type). A `visibleWhen` field reads it as `@context.<name>.<field>`, dot paths allowed (`@context.caseType.category`).',
+		members: ['@context.<name>.<field>'],
+	},
 })
 
 /**