@conduction/nextcloud-vue 2.61.0 → 2.63.0

package/src/utils/columnFilters.js

@@ -0,0 +1,324 @@
+/**
+ * SPDX-FileCopyrightText: 2026 Conduction B.V.
+ * SPDX-License-Identifier: EUPL-1.2
+ */
+
+/**
+ * Per-column sorting and filtering for table headers.
+ *
+ * Pure helpers: which column can sort, which can filter and how, and the
+ * translation between a header filter's state and the OpenRegister query
+ * parameters the facet sidebar already sends. A header filter writes into the
+ * SAME active-filter map (`{ paramKey: values[] }`) the sidebar uses, so the
+ * fetch, the route query and saved views need nothing new.
+ *
+ * Parameter shapes, as OpenRegister reads them:
+ * - equality and "any of": `key=value`, `key[]=a&key[]=b`
+ * - ranges: `key[gte]=from`, `key[lte]=to`
+ *
+ * @module utils/columnFilters
+ * @spec openspec/changes/table-header-sort-and-filter/specs/cn-data-table/spec.md
+ */
+
+import { schemaRefSlug } from './schemaRefSlug.js'
+
+/** Column keys that mark a value computed on the client, never stored. */
+const COMPUTED_MARKERS = ['aggregate', 'compute', 'computed', 'virtual']
+
+/**
+ * Normalise a `$ref` to the referenced schema slug, or null.
+ *
+ * @param {unknown} ref A `$ref` value.
+ * @return {string|number|null} The slug.
+ */
+function refSlug(ref) {
+	if (typeof ref === 'number' && !Number.isNaN(ref)) {
+		return ref
+	}
+	if (typeof ref !== 'string' || ref === '') {
+		return null
+	}
+	const tail = ref.includes('/') ? ref.substring(ref.lastIndexOf('/') + 1) : ref
+	const slug = tail === '' ? '' : schemaRefSlug(tail)
+	return slug !== '' ? slug : null
+}
+
+/**
+ * The schema property behind a column, or null when the column has none.
+ *
+ * @param {object} column The column definition.
+ * @param {object|null} schema The table's schema.
+ * @return {object|null} The property.
+ */
+export function columnProperty(column, schema) {
+	if (!column || !schema || !schema.properties || typeof column.key !== 'string') {
+		return null
+	}
+	const prop = schema.properties[column.key]
+	return (prop && typeof prop === 'object') ? prop : null
+}
+
+/**
+ * Whether a column computes its value on the client, so the server cannot
+ * sort or filter on it.
+ *
+ * @param {object} column The column definition.
+ * @return {boolean} True for a computed column.
+ */
+function isComputedColumn(column) {
+	return COMPUTED_MARKERS.some((marker) => column[marker] !== undefined && column[marker] !== null && column[marker] !== false)
+}
+
+/**
+ * Whether a column header sorts.
+ *
+ * `sortable: false` always wins, and so does an explicit `sortable: true`.
+ * Otherwise, with a schema, a column sorts when a stored schema property backs
+ * it: OpenRegister orders on schema properties, so a widget or computed column
+ * with no property behind it stays unsortable. Without a schema nothing says
+ * the server can sort, so only an explicit flag makes the column sortable,
+ * which is how such tables behaved before.
+ *
+ * @param {object} column The column definition.
+ * @param {object|null} schema The table's schema.
+ * @return {boolean} True when the header sorts.
+ * @spec openspec/changes/table-header-sort-and-filter/specs/cn-data-table/spec.md#requirement-every-backed-column-sorts-by-default
+ */
+export function isColumnSortable(column, schema) {
+	if (!column || typeof column !== 'object') {
+		return false
+	}
+	if (column.sortable === false) {
+		return false
+	}
+	if (column.sortable === true) {
+		return true
+	}
+	if (!schema || isComputedColumn(column)) {
+		return false
+	}
+	const prop = columnProperty(column, schema)
+	return !!prop && prop.type !== 'object'
+}
+
+/**
+ * Display options for an enum filter: schema `enum` (or `items.enum`) with
+ * `x-enum-labels`, else a column `enum` hint, else a badge column's colour
+ * map keys.
+ *
+ * @param {object} column The column definition.
+ * @param {object|null} prop The schema property.
+ * @return {Array<{value: string, label: string}>} The options, or [].
+ */
+function enumOptions(column, prop) {
+	const p = prop || {}
+	const labels = p.enumLabels || p['x-enum-labels'] || (p.items && (p.items.enumLabels || p.items['x-enum-labels'])) || {}
+	let values = null
+	if (Array.isArray(p.enum) && p.enum.length > 0) {
+		values = p.enum
+	} else if (p.items && Array.isArray(p.items.enum) && p.items.enum.length > 0) {
+		values = p.items.enum
+	} else if (Array.isArray(column.enum) && column.enum.length > 0) {
+		values = column.enum
+	} else if (column.widget === 'badge' && column.widgetProps && column.widgetProps.colorMap) {
+		values = Object.keys(column.widgetProps.colorMap)
+	}
+	if (!values) {
+		return []
+	}
+	return values
+		.filter((v) => v !== null && v !== undefined && v !== '')
+		.map((v) => ({ value: String(v), label: String(labels[v] !== undefined ? labels[v] : v) }))
+}
+
+/**
+ * The reference a column points at, for a searchable object filter: a schema
+ * `$ref` (or `items.$ref`), else an `fkResolve` cell widget's config.
+ *
+ * @param {object} column The column definition.
+ * @param {object|null} prop The schema property.
+ * @return {{schema: (string|number), register: string, labelField: string}|null} The reference.
+ */
+function referenceTarget(column, prop) {
+	const widgetProps = (column.widget === 'fkResolve' && column.widgetProps) || null
+	const p = prop || {}
+	const schemaRef = refSlug(p.$ref) ?? (p.items ? refSlug(p.items.$ref) : null)
+	const schema = schemaRef ?? (widgetProps && widgetProps.schema ? widgetProps.schema : null)
+	if (schema === null || schema === undefined || schema === '') {
+		return null
+	}
+	const register = (widgetProps && widgetProps.register)
+		|| p['x-external-register']
+		|| (p.items && p.items['x-external-register'])
+		|| ''
+	const labelField = (widgetProps && widgetProps.labelField) || ''
+	return { schema, register, labelField }
+}
+
+/**
+ * How a column filters, or null when it does not.
+ *
+ * Kinds: `enum` (checkbox list), `boolean` (yes, no, any), `reference`
+ * (searchable list of the referenced objects), `number` and `date` (from and
+ * to), and `string` (equals). `filterable: false` on the column turns it
+ * off. A column with no schema property behind it only filters when it
+ * carries an enum hint (`enum`, or a badge widget's colour map), because the
+ * server cannot filter on a value it does not store.
+ *
+ * @param {object} column The column definition.
+ * @param {object|null} schema The table's schema.
+ * @return {{key: string, kind: string, label: string, options: Array<{value: string, label: string}>, reference: object|null, dateTime: boolean}|null} The filter definition.
+ * @spec openspec/changes/table-header-sort-and-filter/specs/cn-data-table/spec.md#requirement-every-backed-column-filters-from-its-header
+ */
+export function columnFilterDef(column, schema) {
+	if (!column || typeof column !== 'object' || typeof column.key !== 'string' || column.key === '') {
+		return null
+	}
+	if (column.filterable === false || isComputedColumn(column)) {
+		return null
+	}
+	const prop = columnProperty(column, schema)
+	const base = { key: column.key, label: column.label || (prop && prop.title) || column.key, options: [], reference: null, dateTime: false }
+
+	const options = enumOptions(column, prop)
+	if (options.length > 0) {
+		return { ...base, kind: 'enum', options }
+	}
+	if (!prop) {
+		return null
+	}
+	const reference = referenceTarget(column, prop)
+	if (reference) {
+		return { ...base, kind: 'reference', reference }
+	}
+	const type = Array.isArray(prop.type) ? prop.type.find((t) => t !== 'null') : prop.type
+	const format = prop.format || ''
+	if (type === 'boolean') {
+		return { ...base, kind: 'boolean' }
+	}
+	if (type === 'number' || type === 'integer') {
+		return { ...base, kind: 'number' }
+	}
+	if (type === 'string' && (format === 'date' || format === 'date-time')) {
+		return { ...base, kind: 'date', dateTime: format === 'date-time' }
+	}
+	if (type === 'string') {
+		return { ...base, kind: 'string' }
+	}
+	return null
+}
+
+/**
+ * Read one active-filter entry as a list of strings.
+ *
+ * @param {unknown} raw An active-filter value: an array, a scalar, or absent.
+ * @return {Array<string>} The values.
+ */
+function asList(raw) {
+	if (raw === undefined || raw === null || raw === '') {
+		return []
+	}
+	return (Array.isArray(raw) ? raw : [raw]).filter((v) => v !== undefined && v !== null && v !== '').map((v) => String(v))
+}
+
+/**
+ * The parameter keys one column filter owns.
+ *
+ * @param {object} def A filter definition from `columnFilterDef`.
+ * @return {Array<string>} The keys.
+ */
+export function columnFilterParamKeys(def) {
+	if (!def) {
+		return []
+	}
+	if (def.kind === 'number' || def.kind === 'date') {
+		return [`${def.key}[gte]`, `${def.key}[lte]`]
+	}
+	return [def.key]
+}
+
+/**
+ * A column filter's current state, read from the active-filter map.
+ *
+ * @param {object} def A filter definition.
+ * @param {object} activeFilters The active-filter map (`{ paramKey: values }`).
+ * @return {object} `{ values }` for enum and reference, `{ value }` for boolean and string, `{ from, to }` for number and date.
+ */
+export function columnFilterState(def, activeFilters) {
+	const filters = (activeFilters && typeof activeFilters === 'object') ? activeFilters : {}
+	if (!def) {
+		return {}
+	}
+	if (def.kind === 'enum' || def.kind === 'reference') {
+		return { values: asList(filters[def.key]) }
+	}
+	if (def.kind === 'number' || def.kind === 'date') {
+		const from = asList(filters[`${def.key}[gte]`])[0] || ''
+		const to = asList(filters[`${def.key}[lte]`])[0] || ''
+		// A date-time column is queried up to the end of the day; the input
+		// shows the date the person picked.
+		return {
+			from: def.kind === 'date' ? from.slice(0, 10) : from,
+			to: def.kind === 'date' ? to.slice(0, 10) : to,
+		}
+	}
+	return { value: asList(filters[def.key])[0] || '' }
+}
+
+/**
+ * Whether a column filter is active.
+ *
+ * @param {object} def A filter definition.
+ * @param {object} activeFilters The active-filter map.
+ * @return {boolean} True when any of its parameters is set.
+ */
+export function isColumnFilterActive(def, activeFilters) {
+	const filters = (activeFilters && typeof activeFilters === 'object') ? activeFilters : {}
+	return columnFilterParamKeys(def).some((key) => asList(filters[key]).length > 0)
+}
+
+/**
+ * The active-filter entries a column filter state produces. Every key the
+ * column owns is present; an empty list clears that key, so changing a range
+ * from "from and to" to "from" drops the old upper bound.
+ *
+ * @param {object} def A filter definition.
+ * @param {object} state The column filter state (see `columnFilterState`).
+ * @return {object} `{ paramKey: values[] }`.
+ * @spec openspec/changes/table-header-sort-and-filter/specs/cn-data-table/spec.md#requirement-a-header-filter-speaks-the-sidebars-query-language
+ */
+export function columnFilterParams(def, state) {
+	const s = state || {}
+	if (!def) {
+		return {}
+	}
+	if (def.kind === 'enum' || def.kind === 'reference') {
+		return { [def.key]: asList(s.values) }
+	}
+	if (def.kind === 'number' || def.kind === 'date') {
+		const from = s.from === undefined || s.from === null ? '' : String(s.from).trim()
+		let to = s.to === undefined || s.to === null ? '' : String(s.to).trim()
+		if (def.kind === 'date' && def.dateTime && to !== '' && to.length === 10) {
+			to = `${to}T23:59:59`
+		}
+		return {
+			[`${def.key}[gte]`]: from === '' ? [] : [from],
+			[`${def.key}[lte]`]: to === '' ? [] : [to],
+		}
+	}
+	if (def.kind === 'boolean') {
+		return { [def.key]: (s.value === 'true' || s.value === 'false') ? [s.value] : [] }
+	}
+	const value = s.value === undefined || s.value === null ? '' : String(s.value).trim()
+	return { [def.key]: value === '' ? [] : [value] }
+}
+
+/**
+ * Clear-all entries for one column: every key it owns, emptied.
+ *
+ * @param {object} def A filter definition.
+ * @return {object} `{ paramKey: [] }`.
+ */
+export function clearedColumnFilterParams(def) {
+	return Object.fromEntries(columnFilterParamKeys(def).map((key) => [key, []]))
+}

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