@conduction/nextcloud-vue 2.61.0 → 2.63.0

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)
+}