@conduction/nextcloud-vue 2.56.0-beta.36 → 2.56.0-beta.38

package/src/store/useObjectStore.js

@@ -618,6 +618,7 @@ const baseActions = {
 	 * Fetch the schema definition for a registered type.
 	 * Uses cache — only fetches once per type per session.
 	 *
+	 * @spec openspec/changes/zuiddrecht-pixel-gaps-2/specs/zuiddrecht-pixel-gaps-2/spec.md#requirement-a-schema-title-falls-back-to-its-written-form
 	 * @param {string} type The registered type slug
 	 * @return {Promise<object|null>} The schema object or null on error
 	 */
@@ -638,8 +639,12 @@ const baseActions = {
 			const registerScope = config.register
 				? `?register=${encodeURIComponent(config.register)}`
 				: ''
-			const response = await trackedFetch(
-				prefixUrl(`/apps/openregister/api/schemas/${config.schema}${registerScope}`),
+			// Through the schema fallback like every objects-API call: a type
+			// resolveObjectOpType registered from a title (`APInvoice` ->
+			// `ap-invoice`) retries once with the title as written on a 404.
+			const response = await this._fetchWithSchemaFallback(
+				type,
+				(schema) => prefixUrl(`/apps/openregister/api/schemas/${schema ?? config.schema}${registerScope}`),
 				{ method: 'GET', headers: this._buildHeaders() },
 			)
 
@@ -707,6 +712,8 @@ const baseActions = {
 	 * @param {object} [params] Query parameters (_limit, _page, _search, _order, filters)
 	 * @param {object} [options] Call options
 	 * @param {{error?: object|null}} [options.outcome] Opt-in sink for THIS call's own result: `error` is set to the error it records on `errors[type]`, or `null` on success. Unlike `errors[type]`, which every call for the type shares, a later call cannot overwrite it.
+	 * @param {boolean} [options.append] Add the fetched page after the rows already stored instead of replacing them. Dropped when the stored rows are no longer the page before it, or when `options.isCurrent()` returns false (the query changed meanwhile).
+	 * @param {() => boolean} [options.isCurrent] With `append`: asked once the page arrives; false drops it.
 	 * @return {Promise<Array>} The fetched collection (also stored in state)
 	 */
 	async fetchCollection(type, params = {}, options = {}) {
@@ -750,14 +757,26 @@ const baseActions = {
 
 			const data = await response.json()
 			const results = data.results || data
+			const append = options?.append === true
 
-			this.collections = { ...this.collections, [type]: results }
+			const stale = append && (
+				Number(this.pagination[type]?.page || 1) !== Number(params._page || 1) - 1
+				|| (typeof options.isCurrent === 'function' && !options.isCurrent())
+			)
+			if (stale) {
+				return []
+			}
+
+			this.collections = {
+				...this.collections,
+				[type]: append ? [...(this.collections[type] || []), ...results] : results,
+			}
 			// Why a personal lens came back empty, if it says (openregister#4514).
 			this.lenses = { ...this.lenses, [type]: readLensReports(data) }
 			this.pagination = {
 				...this.pagination,
 				[type]: {
-					total: data.total || results.length,
+					total: data.total || (append ? this.collections[type].length : results.length),
 					page: data.page || 1,
 					pages: data.pages || 1,
 					limit: params._limit || 20,

package/src/utils/boardColumns.js

@@ -55,12 +55,28 @@ export function stagesOf(field, colorField = '') {
 					label: String(entry?.label ?? entry?.title ?? entry?.key ?? entry?.value ?? ''),
 					hidden: entry?.hidden === true,
 					color: colorOf(field, entry, colorField),
+					capacity: capacityValue(entry?.capacity),
 				}))
 		.filter((stage) => stage.key !== '')
 
 	return { stages, usable: stages.length > 0 }
 }
 
+/**
+ * A column limit as a usable number.
+ *
+ * @param {unknown} value - The declared limit.
+ * @return {number|null} The limit, or null when there is none (not a number above 0).
+ * @spec openspec/changes/board-column-capacity/specs/board-view/spec.md#requirement-a-column-can-carry-a-capacity
+ */
+export function capacityValue(value) {
+	if (value === null || value === undefined || value === '') {
+		return null
+	}
+	const n = Number(value)
+	return Number.isFinite(n) && n > 0 ? n : null
+}
+
 /**
  * The colour a state declares: the `colorField` key on the state, else its
  * `color`, else (for a plain enum value) the field's `enumColors` entry.
@@ -128,6 +144,10 @@ function labelFor(field, value) {
  * @param {string} options.statusField - The property name on a row.
  * @param {string} [options.offBoardLabel] - What to call the off-board column.
  * @param {string} [options.colorField] - The key on a state that holds its dot colour.
+ * @param {?((row: object) => string)} [options.keyOf] - The column a row
+ *   belongs in, for a field whose raw value is not the column key (a
+ *   reference whose rows are merged by name). Absent, the row's
+ *   `statusField` value is the key.
  *
  * @return {{columns: Array<object>, usable: boolean}} The columns, each
  *   `{ key, label, cards, count }`, and whether the field could back a board.
@@ -138,6 +158,7 @@ export function buildBoardColumns({
 	statusField = '',
 	offBoardLabel = 'Elsewhere',
 	colorField = '',
+	keyOf = null,
 } = {}) {
 	const { stages, usable } = stagesOf(field, colorField)
 	if (usable === false) {
@@ -149,6 +170,7 @@ export function buildBoardColumns({
 		key: stage.key,
 		label: stage.label,
 		color: stage.color,
+		capacity: stage.capacity ?? null,
 		cards: [],
 		count: 0,
 	}))
@@ -156,7 +178,9 @@ export function buildBoardColumns({
 
 	const offBoard = { key: OFF_BOARD_KEY, label: offBoardLabel, cards: [], count: 0 }
 	for (const row of rows) {
-		const value = String(row?.[statusField] ?? '')
+		const value = typeof keyOf === 'function'
+			? String(keyOf(row) ?? '')
+			: String(row?.[statusField] ?? '')
 		const column = byKey.get(value) || offBoard
 		column.cards.push(row)
 		column.count += 1
@@ -170,3 +194,35 @@ export function buildBoardColumns({
 
 	return { columns, usable: true }
 }
+
+/**
+ * Where a card may move, from what `allowedMoves` answered: plain column keys
+ * and `{ key, allowed, reason }` entries. A key any entry allows is allowed;
+ * a blocked key keeps the first reason given for it.
+ *
+ * @param {unknown} answer The answer.
+ * @return {{keys: Array<string>, reasons: object}|null} The allowed keys and the reasons by key, or null for everywhere.
+ * @spec openspec/changes/board-move-block-reasons/specs/board-view/spec.md#requirement-a-move-target-can-be-blocked-with-a-reason
+ */
+export function normalizeAllowed(answer) {
+	if (!Array.isArray(answer)) {
+		return null
+	}
+	const keys = []
+	const reasons = {}
+	for (const entry of answer) {
+		if (entry && typeof entry === 'object') {
+			const key = String(entry.key ?? '')
+			if (entry.allowed === false) {
+				if (!reasons[key] && typeof entry.reason === 'string' && entry.reason.trim() !== '') {
+					reasons[key] = entry.reason.trim()
+				}
+			} else {
+				keys.push(key)
+			}
+		} else if (entry !== null && entry !== undefined) {
+			keys.push(String(entry))
+		}
+	}
+	return { keys, reasons }
+}

package/src/utils/boardReferenceColumns.js

@@ -0,0 +1,326 @@
+/**
+ * SPDX-FileCopyrightText: 2026 Conduction B.V. <info@conduction.nl>
+ * SPDX-License-Identifier: EUPL-1.2
+ *
+ * Board columns from a REFERENCED field (screens-board-reference-columns).
+ *
+ * A status that is an enum or a lifecycle list carries its stages on the
+ * field, and `boardColumns.js` reads them there. A status that is a reference
+ * to another object (a case's `status` pointing at a statusType row) carries
+ * nothing on the field: the stages are the rows of the referenced schema. This
+ * module turns those rows into the same `states` list `stagesOf()` reads, plus
+ * the map from a row's raw value (the referenced id) to its column.
+ *
+ * 🔴 THE COLUMNS ARE STILL THE SCHEMA'S, NOT THE DATA'S. They are the
+ * referenced rows, fetched, not the values present on the loaded cards, so an
+ * empty stage is still a column to drop a card into. The one exception is a
+ * field with no referenced schema at all (a Nextcloud user id): there the
+ * values present are all there is, and a "nobody" column is always added so
+ * work without an owner stays visible and can be dropped back to nobody.
+ *
+ * 🔴 MERGED COLUMNS RESOLVE PER CARD. Referenced rows are often per parent
+ * (every case type has its own "In behandeling"). Merged by name they make one
+ * column, and a drop must then write the row of THAT card's parent. A column
+ * with no row for the card's parent is not a place the card can go, and the
+ * drop is refused rather than written to some other parent's row.
+ *
+ * Pure apart from `fetchReferenceObjects`: no store, no Vue.
+ */
+
+import { capacityValue } from './boardColumns.js'
+import { buildHeaders, buildQueryString, prefixUrl } from './headers.js'
+import { readPath } from './readPath.js'
+import { schemaRefSlug } from './schemaRefSlug.js'
+
+/** The column of cards with no value, for a `values` column field. */
+export const NO_VALUE_KEY = '__none__'
+
+/**
+ * The id a reference value carries: a string as is, an object by its `id`,
+ * `uuid` or `@self.id`.
+ *
+ * @param {unknown} value A reference as a row holds it.
+ * @return {string} The id, '' when there is none.
+ */
+export function refIdOf(value) {
+	if (value === null || value === undefined) {
+		return ''
+	}
+	if (typeof value === 'object') {
+		const id = value.id ?? value.uuid ?? value['@self']?.id ?? value.value ?? ''
+		return id === null || id === undefined ? '' : String(id)
+	}
+	return String(value)
+}
+
+/**
+ * A value as text: a string or number as is, an object by its name.
+ *
+ * @param {unknown} value The raw value.
+ * @return {string} The text.
+ */
+function textOf(value) {
+	if (value === null || value === undefined) {
+		return ''
+	}
+	if (typeof value === 'object') {
+		return String(value.displayName ?? value.name ?? value.title ?? value.label ?? '').trim()
+	}
+	return String(value).trim()
+}
+
+/**
+ * The column fields a board offers, normalised. Without `columnFields` the
+ * board has one, its `statusField`, read from the schema as before.
+ *
+ * @param {object} board The board configuration (manifest `config.board`).
+ * @return {Array<{field: string, label: string, source: (object|null), kind: string, readOnly: boolean, moveHandler: string, moveTargetsHandler: string}>} The fields.
+ * @spec openspec/changes/screens-board-reference-columns/specs/board-view/spec.md#requirement-a-board-can-switch-the-field-its-columns-come-from
+ */
+export function columnFieldsOf(board) {
+	const declared = Array.isArray(board?.columnFields) ? board.columnFields : []
+	return declared
+		.map((entry) => (typeof entry === 'string' ? { field: entry } : entry))
+		.filter((entry) => entry && typeof entry.field === 'string' && entry.field !== '')
+		.map((entry) => ({
+			field: entry.field,
+			label: typeof entry.label === 'string' && entry.label !== '' ? entry.label : entry.field,
+			source: entry.source && typeof entry.source === 'object' ? entry.source : null,
+			kind: entry.kind === 'values' ? 'values' : (entry.source ? 'reference' : 'schema'),
+			readOnly: entry.readOnly === true,
+			moveHandler: typeof entry.moveHandler === 'string' ? entry.moveHandler : '',
+			moveTargetsHandler: typeof entry.moveTargetsHandler === 'string' ? entry.moveTargetsHandler : '',
+			valueLabels: entry.valueLabels && typeof entry.valueLabels === 'object' ? entry.valueLabels : null,
+			emptyLabel: typeof entry.emptyLabel === 'string' ? entry.emptyLabel : '',
+		}))
+}
+
+/**
+ * The register and schema a reference column reads its rows from: the
+ * source's own, else the page's register and the property's `$ref`.
+ *
+ * @param {object} source The column field's `source`.
+ * @param {object} options The context.
+ * @param {string} options.register The page's register.
+ * @param {object} [options.property] The field's schema property.
+ * @return {{register: string, schema: string}} Both, '' when unknown.
+ */
+export function referenceTargetOf(source, { register = '', property = null } = {}) {
+	const schema = source?.schema || schemaRefSlug(property?.$ref ?? property?.items?.$ref ?? '')
+	return {
+		register: String(source?.register || register || ''),
+		schema: schema === '' || schema === null || schema === undefined ? '' : String(schema),
+	}
+}
+
+/**
+ * The stages of a referenced field: the referenced rows, narrowed to one
+ * parent when asked, ordered, and merged by a field when asked.
+ *
+ * @param {object} options The call.
+ * @param {Array<object>} options.refs The referenced rows.
+ * @param {string} [options.labelField] The row field that names a column.
+ * @param {string} [options.orderField] The numeric row field the columns are ordered by.
+ * @param {string} [options.colorField] The row field that holds the dot colour.
+ * @param {string} [options.mergeBy] The row field whose equal values make one column.
+ * @param {{field: string, rowField: string}|null} [options.narrowBy] The parent link.
+ * @param {string} [options.narrowValue] The parent the board is narrowed to, '' for all.
+ * @param {string} [options.capacityField] The numeric row field that holds a column's limit.
+ *   A column merged from two or more rows shows none: each row has its own limit.
+ * @return {{states: Array<{key: string, label: string, color: string, capacity?: (number|null)}>, keyByValue: Map<string, string>, refsByKey: Map<string, Array<object>>}} The stages.
+ * @spec openspec/changes/screens-board-reference-columns/specs/board-view/spec.md#requirement-columns-can-be-the-rows-a-field-references
+ */
+export function buildReferenceStages({
+	refs = [],
+	labelField = '',
+	orderField = '',
+	colorField = '',
+	mergeBy = '',
+	narrowBy = null,
+	narrowValue = '',
+	capacityField = '',
+} = {}) {
+	const list = (Array.isArray(refs) ? refs : []).filter((ref) => ref && typeof ref === 'object' && refIdOf(ref) !== '')
+	const narrowed = narrowBy && narrowBy.field && narrowValue !== ''
+		? list.filter((ref) => refIdOf(readPath(ref, narrowBy.field)) === String(narrowValue))
+		: list
+
+	const orderOf = (ref) => {
+		const n = Number(orderField ? readPath(ref, orderField) : NaN)
+		return Number.isFinite(n) ? n : Number.MAX_SAFE_INTEGER
+	}
+	const ordered = narrowed
+		.map((ref, index) => ({ ref, index }))
+		.sort((a, b) => (orderOf(a.ref) - orderOf(b.ref)) || (a.index - b.index))
+		.map((entry) => entry.ref)
+
+	const states = []
+	const keyByValue = new Map()
+	const refsByKey = new Map()
+	for (const ref of ordered) {
+		const id = refIdOf(ref)
+		const label = textOf(labelField ? readPath(ref, labelField) : (ref.name ?? ref.title)) || id
+		const key = mergeBy ? (textOf(readPath(ref, mergeBy)) || id) : id
+		keyByValue.set(id, key)
+		if (!refsByKey.has(key)) {
+			refsByKey.set(key, [])
+			const color = colorField ? readPath(ref, colorField) : ref.color
+			const state = { key, label, color: typeof color === 'string' ? color : '' }
+			if (capacityField) {
+				state.capacity = capacityOfRef(ref, capacityField)
+			}
+			states.push(state)
+		}
+		refsByKey.get(key).push(ref)
+	}
+	for (const state of states) {
+		if (capacityField && refsByKey.get(state.key).length > 1) {
+			state.capacity = null
+		}
+	}
+	return { states, keyByValue, refsByKey }
+}
+
+/**
+ * The limit one referenced row declares.
+ *
+ * @param {object} ref The referenced row.
+ * @param {string} capacityField The row field that holds the limit.
+ * @return {number|null} The limit, or null when it has none.
+ * @spec openspec/changes/board-column-capacity/specs/board-view/spec.md#requirement-a-column-can-carry-a-capacity
+ */
+export function capacityOfRef(ref, capacityField) {
+	return capacityField ? capacityValue(readPath(ref, capacityField)) : null
+}
+
+/**
+ * Whether a drop fills a referenced row past its limit: the cards that
+ * already carry that row, counted against the row's own limit. Counted per
+ * row, not per column, so a column merged from several rows still refuses
+ * the one that is full.
+ *
+ * @param {object} options The call.
+ * @param {object} options.target The referenced row the drop would write.
+ * @param {object} options.card The card being moved.
+ * @param {Array<object>} options.rows The cards the board holds.
+ * @param {string} options.field The row field the columns come from.
+ * @param {string} options.capacityField The referenced row's limit field.
+ * @param {string} [options.rowKey] The row key, so the moving card is not counted.
+ * @return {{count: number, capacity: number}|null} The count and limit when full, else null.
+ * @spec openspec/changes/board-column-capacity/specs/board-view/spec.md#requirement-a-drop-into-a-full-column-is-refused
+ */
+export function fullTargetOf({ target, card, rows = [], field, capacityField, rowKey = 'id' } = {}) {
+	const capacity = capacityOfRef(target, capacityField)
+	if (capacity === null) {
+		return null
+	}
+	const id = refIdOf(target)
+	const self = String(card?.[rowKey] ?? '')
+	const count = (Array.isArray(rows) ? rows : []).filter((row) => String(row?.[rowKey] ?? '') !== self && refIdOf(readPath(row, field)) === id).length
+	return count >= capacity ? { count, capacity } : null
+}
+
+/**
+ * The stages of a field with no referenced schema (a user id): the values
+ * present on the rows, by label, then one column for no value.
+ *
+ * @param {object} options The call.
+ * @param {Array<object>} options.rows The rows the list holds.
+ * @param {string} options.field The row field.
+ * @param {object} [options.valueLabels] Raw value to the label to show.
+ * @param {string} [options.emptyLabel] The no-value column's label.
+ * @return {{states: Array<{key: string, label: string, color: string}>, keyByValue: Map<string, string>, refsByKey: Map<string, Array<object>>}} The stages.
+ * @spec openspec/changes/screens-board-reference-columns/specs/board-view/spec.md#requirement-a-field-without-a-referenced-schema-takes-its-values
+ */
+export function buildValueStages({ rows = [], field = '', valueLabels = null, emptyLabel = 'Nobody' } = {}) {
+	const labels = valueLabels && typeof valueLabels === 'object' ? valueLabels : {}
+	const seen = new Map()
+	for (const row of Array.isArray(rows) ? rows : []) {
+		const raw = readPath(row, field)
+		const id = refIdOf(raw)
+		if (id !== '' && !seen.has(id)) {
+			seen.set(id, typeof labels[id] === 'string' ? labels[id] : (textOf(raw) || id))
+		}
+	}
+	const states = [...seen.entries()]
+		.sort((a, b) => a[1].localeCompare(b[1]))
+		.map(([key, label]) => ({ key, label, color: '' }))
+	states.push({ key: NO_VALUE_KEY, label: emptyLabel, color: '' })
+	const keyByValue = new Map(states.map((state) => [state.key, state.key]))
+	keyByValue.set('', NO_VALUE_KEY)
+	return { states, keyByValue, refsByKey: new Map() }
+}
+
+/**
+ * The column a row sits in, under a value-to-column map.
+ *
+ * @param {object} row The row.
+ * @param {string} field The row field.
+ * @param {Map<string, string>} keyByValue The value-to-column map.
+ * @return {string} The column key, or the raw value when the map has none
+ *   (which lands the card in the off-board column).
+ */
+export function columnKeyOfRow(row, field, keyByValue) {
+	const id = refIdOf(readPath(row, field))
+	return keyByValue.has(id) ? keyByValue.get(id) : id
+}
+
+/**
+ * What a drop on a column writes for one card: the referenced row of that
+ * column which belongs to the card's parent, or null when the column has none
+ * (the card cannot go there).
+ *
+ * @param {object} options The call.
+ * @param {object} options.card The card.
+ * @param {string} options.toKey The column it was dropped on.
+ * @param {string} options.kind `reference` or `values`.
+ * @param {Map<string, Array<object>>} [options.refsByKey] The column's rows.
+ * @param {{field: string, rowField: string}|null} [options.narrowBy] The parent link.
+ * @return {{value: (string|null), target: (object|null)}|null} The value to write and its row, or null.
+ * @spec openspec/changes/screens-board-reference-columns/specs/board-view/spec.md#requirement-a-drop-writes-the-reference
+ */
+export function resolveDropValue({ card, toKey, kind, refsByKey = new Map(), narrowBy = null } = {}) {
+	if (kind === 'values') {
+		return { value: toKey === NO_VALUE_KEY ? null : String(toKey), target: null }
+	}
+	const candidates = refsByKey.get(String(toKey)) || []
+	if (candidates.length === 0) {
+		return null
+	}
+	if (narrowBy && narrowBy.field && narrowBy.rowField) {
+		const parent = refIdOf(readPath(card, narrowBy.rowField))
+		const match = candidates.find((ref) => refIdOf(readPath(ref, narrowBy.field)) === parent)
+		return match ? { value: refIdOf(match), target: match } : null
+	}
+	return { value: refIdOf(candidates[0]), target: candidates[0] }
+}
+
+/**
+ * Fetch the rows a reference column is built from, one list request.
+ *
+ * @param {object} options The call.
+ * @param {string} options.register The register slug.
+ * @param {string} options.schema The schema slug.
+ * @param {object} [options.filter] Equality filters, e.g. `{ isFinal: false }`.
+ * @param {number} [options.limit] The page size, 500 by default.
+ * @return {Promise<Array<object>>} The rows.
+ * @spec openspec/changes/screens-board-reference-columns/specs/board-view/spec.md#requirement-columns-can-be-the-rows-a-field-references
+ */
+export async function fetchReferenceObjects({ register, schema, filter = {}, limit = 500 } = {}) {
+	if (!register || !schema) {
+		return []
+	}
+	const params = { _limit: limit }
+	for (const [key, value] of Object.entries(filter || {})) {
+		if (value !== undefined && value !== null && typeof value !== 'object') {
+			params[key] = typeof value === 'boolean' ? String(value) : value
+		}
+	}
+	const url = prefixUrl(`/apps/openregister/api/objects/${encodeURIComponent(register)}/${encodeURIComponent(schema)}${buildQueryString(params)}`)
+	const response = await fetch(url, { headers: buildHeaders() })
+	if (!response.ok) {
+		throw new Error(`list returned ${response.status}`)
+	}
+	const data = await response.json()
+	return Array.isArray(data?.results) ? data.results : (Array.isArray(data) ? data : [])
+}

package/src/utils/buildManifest.js

@@ -137,7 +137,10 @@ export function mergeMenuItems(target, incoming) {
 			target.push(copy)
 			return
 		}
-		for (const key of ['label', 'icon', 'route', 'order', 'section', 'featureFlag', 'permission', 'visibleIf', 'href', 'action']) {
+		// `query` and `params` belong to `route`: an entry that takes its route
+		// from here without them opens the list unfiltered (a "board" entry to
+		// `Cases` with `{ _view: 'board' }` opened the table).
+		for (const key of ['label', 'icon', 'route', 'query', 'params', 'order', 'section', 'featureFlag', 'permission', 'visibleIf', 'href', 'action']) {
 			if (existing[key] === undefined && item[key] !== undefined) {
 				existing[key] = item[key]
 			}

package/src/utils/schema.js

@@ -7,6 +7,7 @@
  */
 
 import { schemaRefSlug } from './schemaRefSlug.js'
+import { userLocale } from './userLocale.js'
 
 /**
  * Default column widths per property type/format.
@@ -159,7 +160,7 @@ export function formatValue(value, property = {}, options = {}) {
 		if (Number.isNaN(num)) {
 			return String(value)
 		}
-		return num.toLocaleString()
+		return num.toLocaleString(userLocale())
 	}
 
 	// Array
@@ -213,17 +214,17 @@ export function formatValue(value, property = {}, options = {}) {
 				return str
 			}
 			if (format === 'date') {
-				return date.toLocaleDateString(undefined, {
+				return date.toLocaleDateString(userLocale(), {
 					day: '2-digit',
 					month: '2-digit',
 					year: 'numeric',
 				})
 			}
-			return date.toLocaleDateString(undefined, {
+			return date.toLocaleDateString(userLocale(), {
 				day: '2-digit',
 				month: '2-digit',
 				year: 'numeric',
-			}) + ', ' + date.toLocaleTimeString(undefined, {
+			}) + ', ' + date.toLocaleTimeString(userLocale(), {
 				hour: '2-digit',
 				minute: '2-digit',
 				second: '2-digit',

package/src/utils/userLocale.js

@@ -0,0 +1,26 @@
+/**
+ * SPDX-FileCopyrightText: 2026 Conduction B.V.
+ * SPDX-License-Identifier: EUPL-1.2
+ */
+
+import { getCanonicalLocale } from '@nextcloud/l10n'
+
+/**
+ * The BCP 47 tag dates and numbers are written in: the locale the user chose
+ * in Nextcloud (`nl_NL` becomes `nl-NL`), not the browser's.
+ *
+ * `toLocaleDateString(undefined)` answers in the BROWSER's locale, so a Dutch
+ * instance opened in an English browser wrote 10/15/2026. Pass this instead.
+ *
+ * @return {string|undefined} The tag, or undefined for the runtime default
+ *   when Nextcloud names none or Intl does not accept it.
+ * @spec openspec/changes/dates-in-the-users-locale/specs/data-display/spec.md#requirement-a-date-reads-in-the-users-nextcloud-locale
+ */
+export function userLocale() {
+	try {
+		const tag = getCanonicalLocale()
+		return tag && Intl.DateTimeFormat.supportedLocalesOf([tag]).length > 0 ? tag : undefined
+	} catch {
+		return undefined
+	}
+}