@conduction/nextcloud-vue 2.62.0 → 2.64.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/schemaRefSlug.js

@@ -35,9 +35,14 @@
  * registers author the slug by hand for multi-word titles) folds to one
  * `-`, leading/trailing dashes trimmed.
  *
- * Idempotent: a value that is already a slug (`report-period`, `cohort`)
- * passes through unchanged, so it is always safe to route an already-correct
- * value through this function defensively.
+ * Idempotent: a value that is already a slug (`report-period`, `cohort`,
+ * `statusType`) passes through unchanged, so it is always safe to route an
+ * already-correct value through this function defensively. A slug is any
+ * value that starts with a lowercase letter or digit and holds only
+ * letters, digits and dashes; only a title (capital initial, or spaces and
+ * punctuation) is kebab-cased.
+ *
+ * @spec openspec/changes/zuiddrecht-pixel-gaps/specs/zuiddrecht-pixel-gaps/spec.md#requirement-a-plain-schema-slug-is-left-as-written
  *
  * A numeric schema id (OpenRegister accepts either the slug or the numeric
  * id in the objects-API path) is returned unchanged — slugifying a number
@@ -63,6 +68,17 @@ export function schemaRefSlug(ref) {
 	if (tail === '') {
 		return ''
 	}
+	// A plain slug is left as written. OpenRegister matches a slug
+	// case-insensitively (`statusType`, `statustype` and `StatusType` all
+	// answer 200) but `status-type` is another slug and 404s, so a
+	// camelCase slug authored as a slug must not be kebab-cased. Only a
+	// `$ref` TITLE is: it starts with a capital (`ReportPeriod`) or carries
+	// spaces or punctuation (`Praktijkovereenkomst (POK)`). 2.62.0 kebab-cased
+	// everything and broke every camelCase slug (dossiq: statusType, caseType,
+	// caseObject, bezwaarDecision, bacAdviceRequest, wmsLayer, ...).
+	if (/^[a-z0-9][A-Za-z0-9-]*$/.test(tail)) {
+		return tail
+	}
 	const kebab = tail
 		// PascalCase / camelCase word boundaries: `ReportPeriod` -> `Report-Period`,
 		// an acronym run followed by a new capitalised word: `HTTPServer` -> `HTTP-Server`.