@conduction/nextcloud-vue 2.62.0 → 2.63.0

package/src/utils/groupAutocomplete.js

@@ -0,0 +1,119 @@
+/**
+ * Nextcloud group search for the schema-driven form's group picker
+ * (a property marked `format: 'nc-group'` or `referenceType: 'nextcloud-group'`).
+ *
+ * Asks the core autocomplete OCS endpoint for groups first: every signed-in
+ * user may call it, and it returns the group's display name. The provisioning
+ * endpoint `cloud/groups` is the fallback; it also answers non-admins, but it
+ * returns only group ids, so the id doubles as the label there.
+ *
+ * Options are `{ id: <gid>, label: <display name> }`: the form stores the gid.
+ *
+ * @module utils/groupAutocomplete
+ */
+
+import axios from '@nextcloud/axios'
+import { generateOcsUrl } from '@nextcloud/router'
+
+const OCS_HEADERS = {
+	'OCS-APIRequest': 'true',
+	Accept: 'application/json',
+}
+
+/**
+ * Read the `ocs.data` payload, tolerating a bare body.
+ *
+ * @param {object} response An axios response.
+ * @return {unknown} The data.
+ */
+function ocsData(response) {
+	const body = response && response.data
+	return body && body.ocs ? body.ocs.data : body
+}
+
+/**
+ * Map one autocomplete suggestion to an option, keeping only groups.
+ *
+ * @param {object} suggestion An autocomplete suggestion.
+ * @return {{id: string, label: string}|null} The option, or null when it is not a group.
+ */
+function toGroupOption(suggestion) {
+	if (!suggestion || typeof suggestion !== 'object') {
+		return null
+	}
+	const isGroup = suggestion.source === 'groups'
+		|| suggestion.shareType === 1
+		|| (suggestion.value && suggestion.value.shareType === 1)
+	if (!isGroup) {
+		return null
+	}
+	const gid = suggestion.id || (suggestion.value && suggestion.value.shareWith)
+	if (gid === undefined || gid === null || gid === '') {
+		return null
+	}
+	return { id: String(gid), label: suggestion.label || String(gid) }
+}
+
+/**
+ * Search Nextcloud groups by name or id. Fails soft: an error yields `[]`.
+ *
+ * @spec openspec/changes/form-pickers-from-schema/specs/schema-utilities/spec.md
+ * @param {string} [query] The search term (empty loads a first page).
+ * @param {object} [options] Tuning options.
+ * @param {number} [options.limit] Max results (default 25).
+ * @return {Promise<Array<{id: string, label: string}>>} Picker options.
+ */
+export async function searchNextcloudGroups(query = '', options = {}) {
+	const { limit = 25 } = options
+	try {
+		const response = await axios.get(generateOcsUrl('core/autocomplete/get'), {
+			headers: OCS_HEADERS,
+			params: {
+				search: query || '',
+				itemType: ' ',
+				itemId: ' ',
+				'shareTypes[]': 1,
+				limit,
+			},
+		})
+		const list = ocsData(response)
+		const groups = (Array.isArray(list) ? list : [])
+			.map(toGroupOption)
+			.filter((opt) => opt !== null)
+		if (groups.length > 0) {
+			return groups
+		}
+	} catch {
+		// Fall through to the provisioning endpoint.
+	}
+	try {
+		const response = await axios.get(generateOcsUrl('cloud/groups'), {
+			headers: OCS_HEADERS,
+			params: { search: query || '', limit },
+		})
+		const data = ocsData(response)
+		const gids = data && Array.isArray(data.groups) ? data.groups : []
+		return gids
+			.filter((gid) => typeof gid === 'string' && gid !== '')
+			.map((gid) => ({ id: gid, label: gid }))
+	} catch {
+		return []
+	}
+}
+
+/**
+ * Resolve a stored gid to `{ id, label }` for edit-mode display. Falls back
+ * to the gid itself when the name cannot be looked up.
+ *
+ * @spec openspec/changes/form-pickers-from-schema/specs/schema-utilities/spec.md
+ * @param {string} gid The stored group id.
+ * @return {Promise<{id: string, label: string}>} The resolved option.
+ */
+export async function resolveNextcloudGroup(gid) {
+	const fallback = { id: String(gid), label: String(gid) }
+	if (gid === undefined || gid === null || gid === '') {
+		return fallback
+	}
+	const results = await searchNextcloudGroups(String(gid))
+	return results.find((opt) => opt.id === String(gid)) || fallback
+}

package/src/utils/libraryWidgetKeys.js

@@ -67,6 +67,7 @@ export const BUILT_IN_WIDGET_KEYS = Object.freeze([
 	'integration',
 	'banner',
 	'audit-trail',
+	'timeline',
 	'header',
 	'text',
 	'divider',
@@ -131,6 +132,7 @@ export const DASHBOARD_CATALOG_WIDGET_KEYS = Object.freeze([
 	'tasks',
 	'text',
 	'tile',
+	'timeline',
 	'video',
 	'week-strip',
 	'workspace-filter',

package/src/utils/pickerOptions.js

@@ -0,0 +1,194 @@
+/**
+ * Option lists for the language and time zone pickers, and the defaults a
+ * schema can ask for with `x-default`.
+ *
+ * Both pickers store a code (`nl`, `Europe/Amsterdam`) and show a label in
+ * the user's own language, so a person picks "Nederlands" and the record
+ * stores `nl`.
+ *
+ * @module utils/pickerOptions
+ */
+
+import { getLanguage } from '@nextcloud/l10n'
+
+/**
+ * ISO 639-1 language codes. `Intl` has no list of languages, so the codes
+ * live here; the labels come from `Intl.DisplayNames` at runtime.
+ *
+ * @type {string[]}
+ */
+export const LANGUAGE_CODES = (''
+	+ 'aa ab af ak am an ar as av ay az ba be bg bi bm bn bo br bs '
+	+ 'ca ce ch co cr cs cu cv cy da de dv dz ee el en eo es et eu '
+	+ 'fa ff fi fj fo fr fy ga gd gl gn gu gv ha he hi ho hr ht hu '
+	+ 'hy hz ia id ie ig ii ik io is it iu ja jv ka kg ki kj kk kl '
+	+ 'km kn ko kr ks ku kv kw ky la lb lg li ln lo lt lu lv mg mh '
+	+ 'mi mk ml mn mr ms mt my na nb nd ne ng nl nn no nr nv ny oc '
+	+ 'oj om or os pa pi pl ps pt qu rm rn ro ru rw sa sc sd se sg '
+	+ 'si sk sl sm sn so sq sr ss st su sv sw ta te tg th ti tk tl '
+	+ 'tn to tr ts tt tw ty ug uk ur uz ve vi vo wa wo xh yi yo za '
+	+ 'zh zu'
+).split(' ')
+
+/**
+ * A small fallback for runtimes without `Intl.supportedValuesOf`.
+ *
+ * @type {string[]}
+ */
+const FALLBACK_TIMEZONES = 'UTC Europe/Amsterdam Europe/Berlin Europe/Brussels Europe/London Europe/Paris America/New_York America/Chicago America/Los_Angeles Asia/Tokyo Australia/Sydney'.split(' ')
+
+/**
+ * The user's Nextcloud language as a BCP 47 tag (`en_GB` becomes `en-GB`).
+ *
+ * @return {string} The tag, `en` when Nextcloud reports nothing.
+ */
+export function currentLanguageTag() {
+	let lang
+	try {
+		lang = getLanguage()
+	} catch {
+		lang = ''
+	}
+	return String(lang || 'en').replace(/_/g, '-')
+}
+
+/**
+ * The browser's time zone (IANA id).
+ *
+ * @return {string} The time zone, `UTC` when the runtime does not say.
+ */
+export function currentTimezone() {
+	try {
+		return Intl.DateTimeFormat().resolvedOptions().timeZone || 'UTC'
+	} catch {
+		return 'UTC'
+	}
+}
+
+/**
+ * Cached option lists, keyed by display language. Stable identity matters:
+ * the form's select matches the chosen option by reference.
+ *
+ * @type {Map<string, {codes: string[], labels: object}>}
+ */
+const languageCache = new Map()
+
+/**
+ * The language picker's codes and labels, labelled in `displayLanguage`.
+ *
+ * @spec openspec/changes/form-pickers-from-schema/specs/schema-utilities/spec.md
+ * @param {string} [displayLanguage] BCP 47 tag the labels are written in; defaults to the user's language.
+ * @return {{codes: string[], labels: object}} Codes sorted by label, and `{ code: label }`.
+ */
+export function languageOptions(displayLanguage) {
+	const locale = displayLanguage || currentLanguageTag()
+	if (languageCache.has(locale)) {
+		return languageCache.get(locale)
+	}
+	let names
+	try {
+		names = new Intl.DisplayNames([locale, 'en'], { type: 'language' })
+	} catch {
+		names = null
+	}
+	const labels = {}
+	for (const code of LANGUAGE_CODES) {
+		let label
+		try {
+			label = (names && names.of(code)) || code
+		} catch {
+			label = code
+		}
+		// `Intl` lower-cases some names ("nederlands" is fine in a sentence,
+		// not in a list); capitalise the first letter for the list.
+		labels[code] = label.charAt(0).toLocaleUpperCase(locale) + label.slice(1)
+	}
+	const codes = [...LANGUAGE_CODES].sort((a, b) => labels[a].localeCompare(labels[b], locale))
+	const result = { codes, labels }
+	languageCache.set(locale, result)
+	return result
+}
+
+/** @type {{codes: string[], labels: object}|null} */
+let timezoneCache = null
+
+/**
+ * The time zone picker's codes and labels (`Europe/Amsterdam` shows as
+ * `Europe/Amsterdam`, underscores as spaces).
+ *
+ * @spec openspec/changes/form-pickers-from-schema/specs/schema-utilities/spec.md
+ * @return {{codes: string[], labels: object}} IANA ids, and `{ id: label }`.
+ */
+export function timezoneOptions() {
+	if (timezoneCache) {
+		return timezoneCache
+	}
+	let codes
+	try {
+		codes = typeof Intl.supportedValuesOf === 'function' ? Intl.supportedValuesOf('timeZone') : []
+	} catch {
+		codes = []
+	}
+	if (!codes.length) {
+		codes = FALLBACK_TIMEZONES
+	}
+	if (!codes.includes('UTC')) {
+		codes = ['UTC', ...codes]
+	}
+	const labels = {}
+	for (const code of codes) {
+		labels[code] = code.replace(/_/g, ' ')
+	}
+	timezoneCache = { codes: [...codes], labels }
+	return timezoneCache
+}
+
+/**
+ * Fit a language tag to the property's `pattern`, if it has one.
+ *
+ * A schema that stores ISO 639-1 (`^[a-z]{2}$`) cannot take `en-GB`, so the
+ * tag falls back to its primary subtag. Without a pattern the full tag stays.
+ *
+ * @param {string} tag A BCP 47 tag.
+ * @param {string|undefined} pattern The property's `pattern`.
+ * @return {string} The tag as the schema accepts it.
+ */
+function fitLanguageTag(tag, pattern) {
+	if (!pattern) {
+		return tag
+	}
+	let re
+	try {
+		re = new RegExp(pattern)
+	} catch {
+		return tag
+	}
+	if (re.test(tag)) {
+		return tag
+	}
+	const primary = tag.split('-')[0].toLowerCase()
+	return re.test(primary) ? primary : tag
+}
+
+/**
+ * Resolve an `x-default` token to the value a NEW object starts with.
+ *
+ * - `current-language`: the user's Nextcloud language (BCP 47, fitted to the
+ *   property's `pattern`).
+ * - `current-timezone`: the browser's time zone.
+ *
+ * @spec openspec/changes/form-pickers-from-schema/specs/schema-utilities/spec.md
+ * @param {string|null} token The `x-default` value.
+ * @param {object} [field] The field descriptor (reads `validation.pattern`).
+ * @return {string|null} The value, or null for an unknown token.
+ */
+export function resolveDefaultToken(token, field = {}) {
+	if (token === 'current-language') {
+		const pattern = field && field.validation ? field.validation.pattern : undefined
+		return fitLanguageTag(currentLanguageTag(), pattern)
+	}
+	if (token === 'current-timezone') {
+		return currentTimezone()
+	}
+	return null
+}

package/src/utils/schema.js

@@ -297,10 +297,13 @@ function truncateString(str, maxLength) {
  *    surface (CnFormDialog) resolves the reference to a searchable dropdown
  *    of the referenced objects (label = human name, value = UUID).
  * 4. Nextcloud user reference: `referenceType: 'nextcloud-user'` (or
- *    `format: 'user'`/`'username'`) → `'user'`; an array of such
+ *    `format: 'user'`/`'username'`/`'nc-user'`) → `'user'`; an array of such
  *    properties → `'user-multiselect'`. CnFormDialog resolves these to a
  *    searchable dropdown of real Nextcloud users (label = display name,
- *    value = UID).
+ *    value = UID). A Nextcloud group (`referenceType: 'nextcloud-group'` or
+ *    `format: 'nc-group'`) → `'group'`, an array of groups →
+ *    `'group-multiselect'`. `format: 'language'` → `'language'` and
+ *    `format: 'timezone'` → `'timezone'` (both searchable code lists).
  * 5. Type-based: `boolean` → `'checkbox'`, `integer`/`number` → `'number'`,
  *    `array` + `items.enum` → `'multiselect'`, `array` → `'tags'`
  * 6. Format-based: `date-time` → `'datetime'`, `date` → `'date'`,
@@ -368,9 +371,32 @@ function isUserProp(prop) {
 		return true
 	}
 	const format = prop.format || ''
-	return format === 'user' || format === 'username'
+	return format === 'user' || format === 'username' || format === 'nc-user'
 }
 
+/**
+ * Whether a (single-value) schema property represents a Nextcloud group.
+ *
+ * A property is a group field when it declares `referenceType: 'nextcloud-group'`
+ * or `format: 'nc-group'`. CnFormDialog renders it as a searchable dropdown of
+ * Nextcloud groups (label = display name, value = group id).
+ *
+ * @spec openspec/changes/form-pickers-from-schema/specs/schema-utilities/spec.md
+ * @param {object} prop A schema property definition (or `items` for an array).
+ * @return {boolean} True when the property marks a Nextcloud group.
+ */
+function isGroupProp(prop) {
+	if (!prop || typeof prop !== 'object') {
+		return false
+	}
+	return prop.referenceType === 'nextcloud-group' || prop.format === 'nc-group'
+}
+
+/**
+ * @spec openspec/changes/form-pickers-from-schema/specs/schema-utilities/spec.md
+ * @param {object} prop The schema property definition.
+ * @return {string} The widget identifier (see the block above).
+ */
 function resolveWidget(prop) {
 	// Explicit widget hint takes priority
 	if (prop.widget) {
@@ -409,6 +435,24 @@ function resolveWidget(prop) {
 		return 'user-multiselect'
 	}
 
+	// Nextcloud group (`format: 'nc-group'` / `referenceType: 'nextcloud-group'`):
+	// a searchable dropdown of groups storing the group id.
+	if (isGroupProp(prop)) {
+		return 'group'
+	}
+	if (type === 'array' && isGroupProp(prop.items)) {
+		return 'group-multiselect'
+	}
+
+	// Language and time zone codes: a searchable list instead of a free-text
+	// box, so a person picks "Dutch" and the record stores `nl`.
+	if (type === 'string' && format === 'language') {
+		return 'language'
+	}
+	if (type === 'string' && format === 'timezone') {
+		return 'timezone'
+	}
+
 	// Boolean → switch/checkbox
 	if (type === 'boolean') {
 		return 'checkbox'
@@ -587,7 +631,8 @@ export function isTenantProperty(key, prop) {
  * @param {boolean} [options.includeReadOnly] Whether to include readOnly properties
  * @param {boolean} [options.hideTenant] Drop properties that hold the record's tenant (see `isTenantProperty`). Off by default, so a detail page still shows the tenant; CnFormDialog turns it on because nobody should be asked for it. `overrides[key].hidden === false` keeps one visible.
  * @param {(text: string) => string} [options.translate] Optional display-layer translation function applied to each field's `label` and `description`. Schema property titles/descriptions are authored in English as the canonical source; consumers pass their bound `t()` (via the injected `cnTranslate`) so the rendered field label follows the user's language. When omitted, label/description are the English source strings unchanged (pure, backward-compatible).
- * @return {Array<{key: string, label: string, description: string, descriptionLong: string, type: string, format: string|null, widget: string, required: boolean, readOnly: boolean, default: unknown, enum: Array|null, enumLabels: object|null, items: object|null, referenceType: string|null, referenceSemanticType: string|null, referenceSemanticApp: string|null, reference: {schema: string|number, multiple: boolean}|null, userPicker: {multiple: boolean}|null, fillFrom: object|null, validation: object, order: number}>} `description` is the inline helper text (see `splitDescription`); `descriptionLong` carries the full text when it was too long to render inline, else ''. `enumLabels` maps each raw enum value to its English display label (from the property's `x-enum-labels`), or null.
+ * @spec openspec/changes/form-pickers-from-schema/specs/schema-utilities/spec.md
+ * @return {Array<{key: string, label: string, description: string, descriptionLong: string, type: string, format: string|null, widget: string, required: boolean, readOnly: boolean, default: unknown, enum: Array|null, enumLabels: object|null, items: object|null, referenceType: string|null, referenceSemanticType: string|null, referenceSemanticApp: string|null, reference: {schema: string|number, multiple: boolean, register?: string, labelField?: string}|null, allowCreate: boolean, userPicker: {multiple: boolean}|null, groupPicker: {multiple: boolean}|null, defaultToken: string|null, fillFrom: object|null, validation: object, order: number}>} `description` is the inline helper text (see `splitDescription`); `descriptionLong` carries the property's `x-help` text when it declares one, else the full description when it was too long to render inline, else ''. `enumLabels` maps each raw enum value to its English display label (from the property's `x-enum-labels`), or null.
  */
 export function fieldsFromSchema(schema, options = {}) {
 	const { exclude = [], include = null, overrides = {}, includeReadOnly = false, hideTenant = false, translate } = options
@@ -663,11 +708,19 @@ export function fieldsFromSchema(schema, options = {}) {
 
 	return entries.map(([key, prop]) => {
 		const description = splitDescription(prop.description ? tr(prop.description) : '')
+		// `x-help` is the long explanation behind the (i) popover. It always
+		// shows the popover, while `description` stays the short helper line.
+		const help = typeof prop['x-help'] === 'string' && prop['x-help'].trim() !== ''
+			? tr(prop['x-help'].trim())
+			: ''
+		const labelField = prop['x-label-field']
+			|| (prop.items && prop.items['x-label-field'])
+			|| null
 		const field = {
 			key,
 			label: tr(prop.title || key),
 			description: description.short,
-			descriptionLong: description.long,
+			descriptionLong: help || description.long,
 			type: prop.type || 'string',
 			format: prop.format || null,
 			widget: resolveWidget(prop),
@@ -685,6 +738,10 @@ export function fieldsFromSchema(schema, options = {}) {
 			required: requiredKeys.includes(key),
 			readOnly: prop.readOnly || false,
 			default: prop.default !== undefined ? prop.default : null,
+			// A default that depends on who opens the form (`x-default:
+			// 'current-language'` / `'current-timezone'`). Resolved by the
+			// consuming form on a NEW object only; never on edit.
+			defaultToken: typeof prop['x-default'] === 'string' ? prop['x-default'] : null,
 			enum: prop.enum || null,
 			// Display labels for the enum CODES, keyed by raw value. An enum
 			// value is a stored contract value, not display text — several are
@@ -732,11 +789,23 @@ export function fieldsFromSchema(schema, options = {}) {
 			// form's own; absent, the reference stays same-register (the form's
 			// `register` prop is used). Consolidates the ad-hoc caseReference /
 			// approvalDecisionId / x-mirror-of variants onto one convention.
+			//
+			// `x-label-field` names the referenced object's property that labels
+			// an option and that an inline create writes the typed term to
+			// (`reference.labelField`, default `name` at the consumer).
 			reference: (normalizeRef(prop.$ref) !== null)
-				? { schema: normalizeRef(prop.$ref), multiple: false, ...(prop['x-external-register'] ? { register: prop['x-external-register'] } : {}) }
+				? { schema: normalizeRef(prop.$ref), multiple: false, ...(prop['x-external-register'] ? { register: prop['x-external-register'] } : {}), ...(labelField ? { labelField } : {}) }
 				: (prop.type === 'array' && prop.items && normalizeRef(prop.items.$ref) !== null)
-						? { schema: normalizeRef(prop.items.$ref), multiple: true, ...((prop.items['x-external-register'] || prop['x-external-register']) ? { register: prop.items['x-external-register'] || prop['x-external-register'] } : {}) }
+						? { schema: normalizeRef(prop.items.$ref), multiple: true, ...((prop.items['x-external-register'] || prop['x-external-register']) ? { register: prop.items['x-external-register'] || prop['x-external-register'] } : {}), ...(labelField ? { labelField } : {}) }
 						: null,
+			// Select OR create (`x-allow-create: true`, on the property or on
+			// its `items` for an array): the picker offers "Create" next to the
+			// existing objects. Only meaningful on a reference.
+			allowCreate: prop['x-allow-create'] === true
+				|| (prop.type === 'array' && !!prop.items && prop.items['x-allow-create'] === true),
+			// Template copy (`x-fill-from: { formKey: sourceKey }`): choosing a
+			// referenced object copies those of its values into this form.
+			fillFrom: (prop['x-fill-from'] && typeof prop['x-fill-from'] === 'object') ? prop['x-fill-from'] : null,
 			// Nextcloud user reference: when a property marks a NC user
 			// (`referenceType: 'nextcloud-user'`, or `format: 'user'`/
 			// `'username'`), tag it so CnFormDialog renders a searchable
@@ -749,6 +818,13 @@ export function fieldsFromSchema(schema, options = {}) {
 				: (prop.type === 'array' && isUserProp(prop.items))
 						? { multiple: true }
 						: null,
+			// Nextcloud group reference (`format: 'nc-group'` or
+			// `referenceType: 'nextcloud-group'`): the form stores the group id.
+			groupPicker: isGroupProp(prop)
+				? { multiple: false }
+				: (prop.type === 'array' && isGroupProp(prop.items))
+						? { multiple: true }
+						: null,
 			// Conditional immutability (AD: x-openregister-readonly-when): a
 			// property can declare it becomes read-only when another field on the
 			// same object holds a given value — e.g. a hybrid app's identity

package/src/utils/timelineEvents.js

@@ -0,0 +1,171 @@
+/**
+ * SPDX-FileCopyrightText: 2026 Conduction B.V.
+ * SPDX-License-Identifier: EUPL-1.2
+ */
+
+/**
+ * Turn an object's dated facts into timeline events.
+ *
+ * Pure helpers behind `CnTimelineWidget`. An event is
+ * `{ id, at, dateOnly, label, detail, source, upcoming }`, where `at` is a
+ * `Date`, `dateOnly` says the source value carried no time of day, and
+ * `upcoming` says the moment lies after `now`.
+ *
+ * @module utils/timelineEvents
+ * @spec openspec/changes/timeline-widget/specs/timeline-widget/spec.md
+ */
+
+/**
+ * Read a dotted path off an object (`@self.created`, `payment.clearedAt`).
+ *
+ * @param {object} obj The object.
+ * @param {string} path The dotted path.
+ * @return {unknown} The value, or undefined.
+ */
+export function readPath(obj, path) {
+	if (!obj || typeof path !== 'string' || path === '') {
+		return undefined
+	}
+	if (Object.hasOwn(obj, path)) {
+		return obj[path]
+	}
+	return path.split('.').reduce((acc, part) => ((acc === null || acc === undefined) ? undefined : acc[part]), obj)
+}
+
+/**
+ * Parse a stored date value. A bare `YYYY-MM-DD` is a calendar day and is
+ * read as local midnight, not UTC, so it never shows as the day before.
+ *
+ * @param {unknown} raw The stored value.
+ * @return {{at: Date, dateOnly: boolean}|null} The moment, or null when it is not a date.
+ */
+export function parseMoment(raw) {
+	if (raw === undefined || raw === null || raw === '') {
+		return null
+	}
+	if (typeof raw === 'string' && /^\d{4}-\d{2}-\d{2}$/.test(raw)) {
+		const [y, m, d] = raw.split('-').map(Number)
+		return { at: new Date(y, m - 1, d), dateOnly: true }
+	}
+	const at = new Date(raw)
+	return Number.isNaN(at.getTime()) ? null : { at, dateOnly: false }
+}
+
+/**
+ * Build one event, or null when the value is not a date.
+ *
+ * @param {object} spec `{ id, raw, label, detail, source }`.
+ * @param {Date} now The reference moment for `upcoming`.
+ * @return {object|null} The event.
+ */
+function makeEvent(spec, now) {
+	const moment = parseMoment(spec.raw)
+	if (!moment) {
+		return null
+	}
+	return {
+		id: spec.id,
+		at: moment.at,
+		dateOnly: moment.dateOnly,
+		label: spec.label || '',
+		detail: spec.detail || '',
+		source: spec.source,
+		upcoming: moment.at.getTime() > now.getTime(),
+	}
+}
+
+/**
+ * Events from the object's own date properties.
+ *
+ * @param {object} object The object.
+ * @param {Array<{field: string, label?: string}>} fields The configured date fields.
+ * @param {Date} [now] The reference moment.
+ * @return {Array<object>} One event per field that holds a date.
+ */
+export function fieldEvents(object, fields, now = new Date()) {
+	return (Array.isArray(fields) ? fields : [])
+		.filter((f) => f && typeof f.field === 'string')
+		.map((f) => makeEvent({ id: `field:${f.field}`, raw: readPath(object, f.field), label: f.label || f.field, source: 'field' }, now))
+		.filter(Boolean)
+}
+
+/**
+ * Events from related objects: one per row that holds a date in `dateField`.
+ *
+ * @param {Array<object>} rows The related objects.
+ * @param {{label?: string, dateField?: string, titleField?: string, schema?: string}} config The related-source config.
+ * @param {Date} [now] The reference moment.
+ * @return {Array<object>} The events.
+ */
+export function relatedEvents(rows, config, now = new Date()) {
+	const cfg = config || {}
+	const dateField = cfg.dateField || '@self.created'
+	return (Array.isArray(rows) ? rows : [])
+		.map((row, i) => {
+			const self = (row && row['@self']) || {}
+			const id = String(self.id || row.id || i)
+			const title = cfg.titleField ? readPath(row, cfg.titleField) : (row && (row.title || row.name)) || self.name
+			return makeEvent({
+				id: `related:${cfg.schema || ''}:${id}`,
+				raw: readPath(row, dateField),
+				label: cfg.label || '',
+				detail: title === undefined || title === null ? '' : String(title),
+				source: 'related',
+			}, now)
+		})
+		.filter(Boolean)
+}
+
+/**
+ * Events from audit-trail entries.
+ *
+ * @param {Array<object>} entries The audit-trail rows.
+ * @param {(action: string, actor: string) => string} describe Builds the label from action and actor.
+ * @param {Date} [now] The reference moment.
+ * @return {Array<object>} The events.
+ */
+export function auditEvents(entries, describe, now = new Date()) {
+	return (Array.isArray(entries) ? entries : [])
+		.map((e, i) => makeEvent({
+			id: `audit:${e && (e.id || e.uuid) ? (e.id || e.uuid) : i}`,
+			raw: e && (e.created || e.creationDateTime || e.timestamp),
+			label: describe(String((e && (e.action || e.event)) || ''), String((e && (e.actorDisplayName || e.userName || e.user || e.actor)) || '')),
+			source: 'audit',
+		}, now))
+		.filter(Boolean)
+}
+
+/**
+ * Events from OpenRegister's timeline (notes, calls, messages).
+ *
+ * @param {Array<object>} entries The timeline rows.
+ * @param {string} noteLabel The label for an entry without a kind.
+ * @param {Date} [now] The reference moment.
+ * @return {Array<object>} The events.
+ */
+export function timelineEntryEvents(entries, noteLabel, now = new Date()) {
+	return (Array.isArray(entries) ? entries : [])
+		.map((e, i) => makeEvent({
+			id: `timeline:${e && e.id ? e.id : i}`,
+			raw: e && e.created,
+			label: (e && (e.kindTitle || e.kind)) || noteLabel,
+			detail: [e && e.author, e && e.message].filter(Boolean).join(': '),
+			source: 'timeline',
+		}, now))
+		.filter(Boolean)
+}
+
+/**
+ * Sort events by time; ties keep their input order.
+ *
+ * @param {Array<object>} events The events.
+ * @param {'asc'|'desc'} [order] Oldest first (default) or newest first.
+ * @return {Array<object>} A new, sorted array.
+ */
+export function sortEvents(events, order = 'asc') {
+	const dir = order === 'desc' ? -1 : 1
+	return (events || [])
+		.map((e, i) => ({ e, i }))
+		.sort((a, b) => ((a.e.at.getTime() - b.e.at.getTime()) * dir) || (a.i - b.i))
+		.map(({ e }) => e)
+}