@conduction/nextcloud-vue 2.58.0 → 2.60.0

package/src/utils/actionLink.js

@@ -62,6 +62,11 @@ export function resolveItemActionLink(action, item, router) {
  * on an in-app link that opens in place goes through the router; a URL, a
  * new-tab target or a modified click is left to the browser.
  *
+ * Hand-rolled rather than `NcActionRouter` / `NcButton :to`: the menus and
+ * bars using it must still emit their own events on click, and without an
+ * installed router `NcButton :to` falls back to a button that goes nowhere,
+ * while an `<a href>` still navigates.
+ *
  * @param {MouseEvent} event The click event.
  * @param {{to: (string|object|null), target: (string|undefined)}} link The resolved link.
  * @param {object} [router] The app's router.

package/src/utils/actionsDispatcher.js

@@ -341,6 +341,21 @@ export function interpolateActionTarget(target, ctx) {
 	return interpolateActionString(target || '', ctx || {})
 }
 
+// The tokens interpolateActionString resolves; a bare `@` or `{` is not one.
+const ACTION_TARGET_TOKEN = /@(?:objectId|object\.|page\.|workspace\.|config\.|range\.)|\{objectId\}/
+
+/**
+ * Whether an action target carries a token that interpolation would resolve,
+ * so it can only be known once the page context is. A `mailto:` address or a
+ * URL with an `@handle` in it has none.
+ *
+ * @param {string} target The action's raw `target`.
+ * @return {boolean}
+ */
+export function hasActionTargetTokens(target) {
+	return typeof target === 'string' && ACTION_TARGET_TOKEN.test(target)
+}
+
 /**
  * The link an action renders as when its only job is to navigate to a target
  * known at render time: `navigate` (token-interpolated like the dispatcher)

package/src/utils/dateVariant.js

@@ -0,0 +1,120 @@
+/**
+ * SPDX-FileCopyrightText: 2026 Conduction B.V.
+ * SPDX-License-Identifier: EUPL-1.2
+ *
+ * dateVariant: turn "how far away is this date" into a colour variant.
+ *
+ * A deadline reads differently depending on how close it is. The rules are the
+ * `variantWhen` shape the stat tile already uses (`[{ op, value, variant }]`,
+ * first match wins), compared against the number of CALENDAR days from today
+ * until the date: `0` is today, a negative number is overdue.
+ *
+ * ```js
+ * resolveDateVariant('2026-10-01', [
+ *   { op: 'lt', value: 0, variant: 'error' },     // overdue
+ *   { op: 'lte', value: 5, variant: 'warning' },  // within five days
+ * ])
+ * ```
+ *
+ * Shared by the `date` cell widget (CnCellRenderer) and the week strip, and
+ * meant for board cards too, so a deadline is coloured by one rule everywhere.
+ *
+ * @module utils/dateVariant
+ */
+
+import { compareVisibleWhen } from './visibleWhen.js'
+
+/** Variants a date rule may name. `danger` is accepted as an alias of `error`. */
+export const DATE_VARIANTS = Object.freeze(['default', 'success', 'warning', 'error'])
+
+const MS_PER_DAY = 86400000
+
+/**
+ * Parse a value into a Date. A date-only string (`2026-10-05`) is read as a
+ * LOCAL day, so it does not slide to the day before in a timezone west of UTC.
+ *
+ * @param {unknown} value A Date, a timestamp, or an ISO string.
+ * @return {Date|null} The date, or null when the value is not one.
+ * @spec openspec/changes/workplace-dashboard-primitives/specs/workplace-dashboard-primitives/spec.md#requirement-avatar-and-date-cells
+ */
+export function parseDateValue(value) {
+	if (value === null || value === undefined || value === '') {
+		return null
+	}
+	if (value instanceof Date) {
+		return Number.isNaN(value.getTime()) ? null : value
+	}
+	if (typeof value === 'string') {
+		const dateOnly = value.match(/^(\d{4})-(\d{2})-(\d{2})$/)
+		if (dateOnly) {
+			return new Date(Number(dateOnly[1]), Number(dateOnly[2]) - 1, Number(dateOnly[3]))
+		}
+	}
+	if (typeof value !== 'string' && typeof value !== 'number') {
+		return null
+	}
+	const parsed = new Date(value)
+	return Number.isNaN(parsed.getTime()) ? null : parsed
+}
+
+/**
+ * The local calendar day of a date as `YYYY-MM-DD`.
+ *
+ * @param {Date} date The date.
+ * @return {string} The day key.
+ * @spec openspec/changes/workplace-dashboard-primitives/specs/workplace-dashboard-primitives/spec.md#requirement-week-strip-widget
+ */
+export function dayKey(date) {
+	const month = String(date.getMonth() + 1).padStart(2, '0')
+	const day = String(date.getDate()).padStart(2, '0')
+	return `${date.getFullYear()}-${month}-${day}`
+}
+
+/**
+ * Whole calendar days from `now` until `value`: 0 today, negative when past.
+ *
+ * @param {unknown} value The date.
+ * @param {Date} [now] The reference moment (defaults to the current time).
+ * @return {number|null} The day count, or null when `value` is not a date.
+ * @spec openspec/changes/workplace-dashboard-primitives/specs/workplace-dashboard-primitives/spec.md#requirement-avatar-and-date-cells
+ */
+export function daysUntil(value, now = new Date()) {
+	const date = parseDateValue(value)
+	if (date === null) {
+		return null
+	}
+	// UTC midnights of the two LOCAL days, so a daylight-saving hour never
+	// turns one day into zero or two.
+	const target = Date.UTC(date.getFullYear(), date.getMonth(), date.getDate())
+	const today = Date.UTC(now.getFullYear(), now.getMonth(), now.getDate())
+	return Math.round((target - today) / MS_PER_DAY)
+}
+
+/**
+ * The variant of the first rule the date matches, or '' when none does.
+ *
+ * @param {unknown} value The date.
+ * @param {Array<{op: string, value: number, variant: string}>} rules The `variantWhen` rules.
+ * @param {Date} [now] The reference moment (defaults to the current time).
+ * @return {string} `success | warning | error | default`, or '' for no match.
+ * @spec openspec/changes/workplace-dashboard-primitives/specs/workplace-dashboard-primitives/spec.md#requirement-avatar-and-date-cells
+ */
+export function resolveDateVariant(value, rules, now = new Date()) {
+	if (!Array.isArray(rules) || rules.length === 0) {
+		return ''
+	}
+	const days = daysUntil(value, now)
+	if (days === null) {
+		return ''
+	}
+	for (const rule of rules) {
+		if (!rule || typeof rule !== 'object') {
+			continue
+		}
+		if (compareVisibleWhen(days, rule.op || 'eq', rule.value) === true) {
+			const variant = rule.variant === 'danger' ? 'error' : rule.variant
+			return DATE_VARIANTS.includes(variant) ? variant : ''
+		}
+	}
+	return ''
+}

package/src/utils/detailActionModel.js

@@ -0,0 +1,256 @@
+/**
+ * SPDX-FileCopyrightText: 2026 Conduction B.V.
+ * SPDX-License-Identifier: EUPL-1.2
+ *
+ * detailActionModel: the rules behind a detail page's four action levels and
+ * the case surfaces that read the record's stage.
+ *
+ *   1. the next step: one primary button, chosen by the record's stage,
+ *   2. quick actions: at most three always visible buttons,
+ *   3. the overflow menu: the rest, in named groups,
+ *   4. admin actions: the last group, for admins only.
+ *
+ * Pure functions, no Vue and no fetch, so CnDetailPage, the widgets and the
+ * tests all read one implementation.
+ *
+ * @module utils/detailActionModel
+ */
+
+import { readPath } from './readPath.js'
+import { evaluateVisibleWhenLocal } from './visibleWhen.js'
+
+/** The most quick actions a page shows. Later entries are dropped. */
+export const MAX_QUICK_ACTIONS = 3
+
+/**
+ * The record's stage, as the string a stage map is keyed on.
+ *
+ * @param {object|null} object The record.
+ * @param {string} [stageField] Dot-path to the stage. Defaults to `status`.
+ * @return {string} The stage, or '' when the record has none.
+ * @spec openspec/changes/detail-action-model-and-case-surfaces/specs/detail-action-model/spec.md#requirement-primary-action-follows-the-stage
+ */
+export function stageOf(object, stageField = 'status') {
+	if (!object || typeof object !== 'object') {
+		return ''
+	}
+	const value = readPath(object, stageField || 'status')
+	if (value === null || value === undefined || typeof value === 'object') {
+		return ''
+	}
+	return String(value)
+}
+
+/**
+ * Look a stage up in a stage-keyed map. An exact key wins; otherwise the
+ * match ignores case, because a status is stored as `in_behandeling` in one
+ * register and `In_Behandeling` in the next.
+ *
+ * @param {object|null} map The stage-keyed map.
+ * @param {string} stage The stage.
+ * @return {unknown} The entry, or undefined.
+ * @spec openspec/changes/detail-action-model-and-case-surfaces/specs/detail-action-model/spec.md#requirement-primary-action-follows-the-stage
+ */
+export function stageEntry(map, stage) {
+	if (!map || typeof map !== 'object' || Array.isArray(map) || stage === '') {
+		return undefined
+	}
+	if (Object.hasOwn(map, stage)) {
+		return map[stage]
+	}
+	const wanted = stage.toLowerCase()
+	const key = Object.keys(map).find((candidate) => candidate.toLowerCase() === wanted)
+	return key === undefined ? undefined : map[key]
+}
+
+/**
+ * Turn a pinned action entry into a descriptor the page can dispatch.
+ *
+ * An entry is the id of a declared header action, or an action object of its
+ * own. An object without an id gets `fallbackId`, since every dispatched
+ * action is addressed by id.
+ *
+ * @param {string|object|null} entry The entry.
+ * @param {string} fallbackId Id for an inline action that names none.
+ * @return {{id: string, inline: object|null}|null} The id, plus the inline definition when the entry carried one.
+ * @spec openspec/changes/detail-action-model-and-case-surfaces/specs/detail-action-model/spec.md#requirement-quick-actions
+ */
+export function normalisePinnedAction(entry, fallbackId) {
+	if (typeof entry === 'string') {
+		return entry === '' ? null : { id: entry, inline: null }
+	}
+	if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
+		return null
+	}
+	if (typeof entry.label !== 'string' || entry.label === '') {
+		return null
+	}
+	const id = typeof entry.id === 'string' && entry.id !== '' ? entry.id : fallbackId
+	return { id, inline: { ...entry, id } }
+}
+
+/**
+ * Split menu entries into the groups the overflow menu draws.
+ *
+ * Ungrouped entries come first, under no caption. Named groups follow in the
+ * order they first appear. Admin only entries are dropped for everyone else
+ * and form the last group for admins, whatever `group` they also name.
+ *
+ * `adminOnly` hides a control. It is never an authorization decision: the
+ * endpoint behind the action decides who may call it.
+ *
+ * @param {Array<object>} entries Menu-ready entries, each with an `id`.
+ * @param {object} actionsById The declared actions by id, carrying `group` / `adminOnly`.
+ * @param {{isAdmin?: boolean, adminLabel?: string}} [options] Who is looking, and what the admin group is called.
+ * @return {Array<{key: string, label: string, entries: Array<object>}>} The non-empty groups, in render order.
+ * @spec openspec/changes/detail-action-model-and-case-surfaces/specs/detail-action-model/spec.md#requirement-grouped-and-admin-only-menu-actions
+ */
+export function groupMenuEntries(entries, actionsById = {}, options = {}) {
+	const isAdmin = options.isAdmin === true
+	const plain = { key: '', label: '', entries: [] }
+	const named = []
+	const admin = { key: 'cn-admin', label: options.adminLabel || '', entries: [] }
+	for (const entry of Array.isArray(entries) ? entries : []) {
+		const declared = (entry && actionsById[entry.id]) || {}
+		if (declared.adminOnly === true) {
+			if (isAdmin) {
+				admin.entries.push(entry)
+			}
+			continue
+		}
+		const label = typeof declared.group === 'string' ? declared.group.trim() : ''
+		if (label === '') {
+			plain.entries.push(entry)
+			continue
+		}
+		let group = named.find((candidate) => candidate.label === label)
+		if (!group) {
+			group = { key: `cn-group-${named.length}`, label, entries: [] }
+			named.push(group)
+		}
+		group.entries.push(entry)
+	}
+	return [plain, ...named, admin].filter((group) => group.entries.length > 0)
+}
+
+/**
+ * Whether one checklist item is done for this record.
+ *
+ * `done` (a literal) wins, then `doneWhen` (a local visibleWhen condition),
+ * then `doneField` (truthy, and for a list: not empty).
+ *
+ * @param {object} item The checklist item.
+ * @param {object|null} object The record.
+ * @return {boolean} True when the item is done.
+ * @spec openspec/changes/detail-action-model-and-case-surfaces/specs/detail-action-model/spec.md#requirement-next-step-card
+ */
+export function isChecklistItemDone(item, object) {
+	if (!item || typeof item !== 'object') {
+		return false
+	}
+	if (typeof item.done === 'boolean') {
+		return item.done
+	}
+	const data = object && typeof object === 'object' ? object : {}
+	if (item.doneWhen && typeof item.doneWhen === 'object') {
+		return evaluateVisibleWhenLocal(item.doneWhen, data)
+	}
+	if (typeof item.doneField === 'string' && item.doneField !== '') {
+		const value = readPath(data, item.doneField)
+		return Array.isArray(value) ? value.length > 0 : Boolean(value)
+	}
+	return false
+}
+
+/**
+ * Resolve the "what now" card for the record's stage.
+ *
+ * @param {{stages?: object, title?: string}|null} config The `nextStep` config.
+ * @param {object|null} object The record.
+ * @param {string} [stageField] Dot-path to the stage.
+ * @return {{stage: string, title: string, items: Array<{label: string, done: boolean, hint: string}>, after: string}|null} The card, or null when this stage declares no checklist.
+ * @spec openspec/changes/detail-action-model-and-case-surfaces/specs/detail-action-model/spec.md#requirement-next-step-card
+ */
+export function resolveNextStep(config, object, stageField = 'status') {
+	if (!config || typeof config !== 'object') {
+		return null
+	}
+	const stage = stageOf(object, config.field || stageField)
+	const declared = stageEntry(config.stages, stage)
+	if (!declared || typeof declared !== 'object' || !Array.isArray(declared.checklist)) {
+		return null
+	}
+	const items = declared.checklist
+		.filter((item) => item && typeof item === 'object' && typeof item.label === 'string' && item.label !== '')
+		.map((item) => ({
+			label: item.label,
+			done: isChecklistItemDone(item, object),
+			hint: typeof item.hint === 'string' ? item.hint : '',
+		}))
+	if (items.length === 0) {
+		return null
+	}
+	return {
+		stage,
+		title: typeof declared.title === 'string' ? declared.title : (typeof config.title === 'string' ? config.title : ''),
+		items,
+		after: typeof declared.after === 'string' ? declared.after : '',
+	}
+}
+
+/**
+ * Resolve a header pill from the record.
+ *
+ * @param {{field?: string, colorMap?: object, labels?: object, variant?: string}|null} config The pill config.
+ * @param {object|null} object The record.
+ * @return {{label: string, colorKey: string, colorMap: object|null, variant: string}|null} What CnStatusBadge needs, or null when the field is empty.
+ * @spec openspec/changes/detail-action-model-and-case-surfaces/specs/detail-action-model/spec.md#requirement-header-pills
+ */
+export function resolvePill(config, object) {
+	if (!config || typeof config !== 'object' || typeof config.field !== 'string' || config.field === '') {
+		return null
+	}
+	const raw = stageOf(object, config.field)
+	if (raw === '') {
+		return null
+	}
+	const mapped = stageEntry(config.labels, raw)
+	return {
+		label: typeof mapped === 'string' && mapped !== '' ? mapped : raw,
+		colorKey: raw,
+		colorMap: config.colorMap && typeof config.colorMap === 'object' ? config.colorMap : null,
+		variant: typeof config.variant === 'string' && config.variant !== '' ? config.variant : 'default',
+	}
+}
+
+/**
+ * Resolve a tab's count.
+ *
+ * `count` (a number) wins. Otherwise `countField` is read off the record: a
+ * list counts its items, a number is taken as is.
+ *
+ * @param {{count?: number, countField?: string}|null} tab The tab declaration.
+ * @param {object|null} object The record.
+ * @return {number|null} The count, or null when the tab declares none.
+ * @spec openspec/changes/detail-action-model-and-case-surfaces/specs/detail-action-model/spec.md#requirement-tab-counts-and-overflow
+ */
+export function resolveTabCount(tab, object) {
+	if (!tab || typeof tab !== 'object') {
+		return null
+	}
+	if (typeof tab.count === 'number' && Number.isFinite(tab.count)) {
+		return tab.count
+	}
+	if (typeof tab.countField !== 'string' || tab.countField === '') {
+		return null
+	}
+	const value = readPath(object && typeof object === 'object' ? object : {}, tab.countField)
+	if (Array.isArray(value)) {
+		return value.length
+	}
+	if (value === null || value === undefined || value === '') {
+		return 0
+	}
+	const number = Number(value)
+	return Number.isFinite(number) ? number : null
+}

package/src/utils/dueRule.js

@@ -0,0 +1,94 @@
+/**
+ * SPDX-FileCopyrightText: 2026 Conduction B.V.
+ * SPDX-License-Identifier: EUPL-1.2
+ *
+ * dueRule: decides whether a dated card is overdue, due soon or fine.
+ *
+ * A board's rule is `{ field, soonDays?, variantWhen? }`. `field` is a
+ * dot-path to the date on the row. `soonDays` (default 3) is how many days
+ * ahead still counts as "soon"; a date before today is overdue.
+ *
+ * The deciding is done by `utils/dateVariant.js`, the same rules a table's
+ * date cell uses, so a list and its board agree on what late means.
+ * `{ soonDays: 3 }` is shorthand for
+ * `variantWhen: [{ op: 'lt', value: 0, variant: 'error' }, { op: 'lte', value: 3, variant: 'warning' }]`,
+ * and a rule that carries its own `variantWhen` is used as written:
+ * `error` reads as overdue, `warning` as due soon.
+ *
+ * @module utils/dueRule
+ */
+
+import { daysUntil, parseDateValue, resolveDateVariant } from './dateVariant.js'
+import { readPath } from './readPath.js'
+
+export { daysUntil }
+
+/** How many days ahead counts as "soon" when the rule does not say. */
+export const DEFAULT_SOON_DAYS = 3
+
+/**
+ * Local midnight of a date value. A bare `YYYY-MM-DD` is a LOCAL day.
+ *
+ * @param {unknown} value A Date, a timestamp or a date string.
+ * @return {Date|null} Local midnight of that day, or null when unreadable.
+ * @spec openspec/changes/detail-action-model-and-case-surfaces/specs/detail-action-model/spec.md#requirement-late-marking-on-board-cards
+ */
+export function toLocalDay(value) {
+	const date = parseDateValue(value)
+	return date === null ? null : new Date(date.getFullYear(), date.getMonth(), date.getDate())
+}
+
+/**
+ * The `variantWhen` rules a due rule stands for.
+ *
+ * @param {{soonDays?: number, variantWhen?: Array<object>}|null} [rule] The due rule.
+ * @return {Array<{op: string, value: number, variant: string}>} The rules `resolveDateVariant` takes.
+ * @spec openspec/changes/detail-action-model-and-case-surfaces/specs/detail-action-model/spec.md#requirement-late-marking-on-board-cards
+ */
+export function dueRuleToVariantWhen(rule = {}) {
+	if (Array.isArray(rule?.variantWhen) && rule.variantWhen.length > 0) {
+		return rule.variantWhen
+	}
+	const given = rule?.soonDays
+	const soonDays = given !== null && given !== undefined && Number.isFinite(Number(given)) ? Number(given) : DEFAULT_SOON_DAYS
+	return [
+		{ op: 'lt', value: 0, variant: 'error' },
+		{ op: 'lte', value: soonDays, variant: 'warning' },
+	]
+}
+
+/**
+ * The due state of one date under a rule.
+ *
+ * @param {unknown} value The date.
+ * @param {{soonDays?: number, variantWhen?: Array<object>}|null} [rule] The rule.
+ * @param {Date} [now] The moment to measure from.
+ * @return {'overdue'|'soon'|'ok'|null} The state, or null when there is no readable date.
+ * @spec openspec/changes/detail-action-model-and-case-surfaces/specs/detail-action-model/spec.md#requirement-late-marking-on-board-cards
+ */
+export function dueStateOf(value, rule = {}, now = new Date()) {
+	if (daysUntil(value, now) === null) {
+		return null
+	}
+	const variant = resolveDateVariant(value, dueRuleToVariantWhen(rule), now)
+	if (variant === 'error') {
+		return 'overdue'
+	}
+	return variant === 'warning' ? 'soon' : 'ok'
+}
+
+/**
+ * The due state of a row under a `{ field, soonDays }` rule.
+ *
+ * @param {object} row The row or card.
+ * @param {{field?: string, soonDays?: number, variantWhen?: Array<object>}|null} rule The rule. Null or field-less means no marking.
+ * @param {Date} [now] The moment to measure from.
+ * @return {'overdue'|'soon'|'ok'|null} The state, or null when the rule does not apply.
+ * @spec openspec/changes/detail-action-model-and-case-surfaces/specs/detail-action-model/spec.md#requirement-late-marking-on-board-cards
+ */
+export function dueStateForRow(row, rule, now = new Date()) {
+	if (!rule || typeof rule.field !== 'string' || rule.field === '' || !row) {
+		return null
+	}
+	return dueStateOf(readPath(row, rule.field), rule, now)
+}

package/src/utils/fetchAggregate.js

@@ -77,3 +77,39 @@ export async function fetchAggregateValue(source, ctx) {
 	const res = await axios.get(url, { params })
 	return (res && res.data && res.data.value !== undefined) ? res.data.value : null
 }
+
+/**
+ * Fetch the object count per distinct value of one field, in ONE request,
+ * from OpenRegister's `/grouped` aggregation endpoint.
+ *
+ * @param {object} source The grouped descriptor.
+ * @param {string} source.register The register slug.
+ * @param {string} source.schema The schema slug.
+ * @param {string} source.groupBy The field to group on.
+ * @param {object} [source.filter] The filter map.
+ * @param {{objectId?: (string|number), object?: object, workspace?: object}} [ctx] Optional
+ *   token-resolution context for the filter.
+ * @return {Promise<Array<{key: string, count: number}>>} One entry per group; [] when the source is incomplete.
+ * @spec openspec/changes/workplace-dashboard-primitives/specs/workplace-dashboard-primitives/spec.md#requirement-stacked-bar-widget
+ */
+export async function fetchGroupedCounts(source, ctx) {
+	const s = source || {}
+	if (!s.register || !s.schema || !s.groupBy) {
+		return []
+	}
+	const [{ default: axios }, { generateUrl }] = await Promise.all([
+		import('@nextcloud/axios'),
+		import('@nextcloud/router'),
+	])
+	const url = generateUrl(
+		'/apps/openregister/api/objects/aggregations/{register}/{schema}/grouped',
+		{ register: s.register, schema: s.schema },
+	)
+	const params = { groupBy: s.groupBy, metric: 'count' }
+	flattenAggFilter(params, s.filter || {}, ctx)
+	const res = await axios.get(url, { params })
+	const groups = (res && res.data && Array.isArray(res.data.groups)) ? res.data.groups : []
+	return groups
+		.filter((g) => g && g.key !== null && g.key !== undefined && g.key !== '')
+		.map((g) => ({ key: String(g.key), count: Number(g.value) || 0 }))
+}