@conduction/nextcloud-vue 2.119.0 → 2.121.0

package/src/utils/objectTranslations.js

@@ -0,0 +1,176 @@
+/**
+ * SPDX-FileCopyrightText: 2026 Conduction B.V.
+ * SPDX-License-Identifier: EUPL-1.2
+ *
+ * The OpenRegister translation reads and the one write behind
+ * CnObjectTranslationsWidget. The engine is OpenRegister's; nothing here
+ * translates or stores anything of its own.
+ *
+ *   GET   {apiBase}/registers/{register}                       languages, source first
+ *   GET   {apiBase}/registers/{register}/schemas                property titles
+ *   GET   {apiBase}/objects/{register}/{schema}/{id}?_translations=all&_translationMeta=true
+ *   GET   {apiBase}/translations/object/{uuid}?schema={schema}   per-value workflow status
+ *   PATCH {apiBase}/objects/{register}/{schema}/{id}             { property: languageMap }
+ *
+ * The WHOLE language map is written and no `X-Translation-Target-Language` is
+ * sent: OpenRegister refuses a language-keyed body that arrives with that
+ * header, and keeps one that arrives without it.
+ *
+ * The translatable properties come from `_meta.languageMeta`, which OpenRegister
+ * builds from the schema it imported, so a property it never read as
+ * translatable is not offered.
+ *
+ * A failed read throws: an outage and an object with nothing translated look
+ * the same from the browser, and only one of them is somebody's problem.
+ */
+import axios from '@nextcloud/axios'
+import { prefixUrl } from './headers.js'
+
+/** The OpenRegister API root a target defaults to. */
+export const DEFAULT_API_BASE = '/apps/openregister/api'
+
+/**
+ * A translation row is stale when the source value moved under it; OpenRegister
+ * flips a derived row to `outdated`. A stale value does not count as translated.
+ *
+ * @type {string}
+ */
+export const STATUS_OUTDATED = 'outdated'
+
+/**
+ * The slug of a schema given as a slug or as the schema object.
+ *
+ * @param {string|object} schema The schema.
+ * @return {string} The slug (or id).
+ */
+export function schemaSlugOf(schema) {
+	if (schema && typeof schema === 'object') {
+		return String(schema.slug || schema.id || schema.uuid || '')
+	}
+	return String(schema || '')
+}
+
+/**
+ * Normalise a target to `{register, schema, apiBase}`.
+ *
+ * @param {object} target `{register, schema, apiBase?}`.
+ * @return {{register: string, schema: string, apiBase: string}} The target.
+ */
+function normalise(target = {}) {
+	return {
+		register: String(target.register || ''),
+		schema: schemaSlugOf(target.schema),
+		apiBase: String(target.apiBase || DEFAULT_API_BASE).replace(/\/$/, ''),
+	}
+}
+
+/**
+ * The languages the register serves, source language first.
+ *
+ * @param {object} target The target.
+ * @return {Promise<string[]>} The language codes.
+ */
+export async function registerLanguages(target) {
+	const { apiBase, register } = normalise(target)
+	const { data } = await axios.get(prefixUrl(`${apiBase}/registers/${register}`))
+	const languages = data?.languages ?? data?.register?.languages ?? []
+	return Array.isArray(languages) ? languages.filter((code) => typeof code === 'string' && code !== '') : []
+}
+
+/**
+ * One object with every language of every value, and its label envelope.
+ *
+ * @param {object} target The target.
+ * @param {string} id     The object id.
+ * @return {Promise<{object: object, languageMeta: object}>} The values and the envelope.
+ */
+export async function objectWithTranslations(target, id) {
+	const { apiBase, register, schema } = normalise(target)
+	const { data } = await axios.get(
+		prefixUrl(`${apiBase}/objects/${register}/${schema}/${encodeURIComponent(id)}`),
+		{ params: { _translations: 'all', _translationMeta: 'true' } },
+	)
+	const object = data?.object ?? data ?? {}
+	return { object, languageMeta: object?._meta?.languageMeta ?? {} }
+}
+
+/**
+ * The schema's property definitions, for their titles (`languageMeta` carries
+ * none).
+ *
+ * @param {object} target The target.
+ * @return {Promise<object>} Property name to its definition.
+ */
+export async function schemaProperties(target) {
+	const { apiBase, register, schema } = normalise(target)
+	const { data } = await axios.get(prefixUrl(`${apiBase}/registers/${register}/schemas`))
+	const schemas = data?.results ?? data?.schemas ?? data ?? []
+	const list = Array.isArray(schemas) ? schemas : Object.values(schemas)
+	const found = list.find((entry) => [entry?.slug, entry?.id, entry?.uuid, entry?.title].map((v) => (v === undefined || v === null) ? '' : String(v)).includes(schema))
+	return found?.properties ?? {}
+}
+
+/**
+ * The sidecar rows for one object, so a stale value can be told apart.
+ *
+ * @param {object} target The target.
+ * @param {string} uuid   The object uuid.
+ * @return {Promise<Array<object>>} Rows naming property, language and status.
+ */
+export async function translationRows(target, uuid) {
+	const { apiBase, schema } = normalise(target)
+	const { data } = await axios.get(
+		prefixUrl(`${apiBase}/translations/object/${encodeURIComponent(uuid)}`),
+		{ params: { schema } },
+	)
+	const rows = data?.translations ?? []
+	return Array.isArray(rows) ? rows : []
+}
+
+/**
+ * Write one property back with every language it now holds.
+ *
+ * @param {object} target      The target.
+ * @param {string} id          The object id.
+ * @param {string} property    The property.
+ * @param {object} languageMap Every language of it, the edit included.
+ * @return {Promise<object>} The saved object.
+ */
+export async function saveTranslatedProperty(target, id, property, languageMap) {
+	const { apiBase, register, schema } = normalise(target)
+	const { data } = await axios.patch(
+		prefixUrl(`${apiBase}/objects/${register}/${schema}/${encodeURIComponent(id)}`),
+		{ [property]: languageMap },
+	)
+	return data?.object ?? data ?? {}
+}
+
+/**
+ * How many of a language's properties are present AND current.
+ *
+ * Deliberately not OpenRegister's `completeness`, which counts every non-empty
+ * row and never reads its status: a stale value is a wrong value. The source
+ * language is complete by definition for every non-empty value.
+ *
+ * @param {object}   args                The inputs.
+ * @param {string[]} args.properties     The translatable properties.
+ * @param {object}   args.values         Property to language to value.
+ * @param {object}   args.statuses       Property to language to status.
+ * @param {string}   args.language       The language counted.
+ * @param {string}   args.sourceLanguage The source language.
+ * @return {{translated: number, total: number}} The counts.
+ */
+export function completenessOf({ properties, values, statuses, language, sourceLanguage }) {
+	const total = properties.length
+	const translated = properties.filter((property) => {
+		const value = values?.[property]?.[language] ?? ''
+		if (typeof value !== 'string' || value.trim() === '') {
+			return false
+		}
+		if (language === sourceLanguage) {
+			return true
+		}
+		return (statuses?.[property]?.[language] ?? '') !== STATUS_OUTDATED
+	}).length
+	return { translated, total }
+}

package/src/utils/stateMachineValidation.js

@@ -0,0 +1,250 @@
+/**
+ * SPDX-FileCopyrightText: 2026 Conduction B.V. <info@conduction.nl>
+ * SPDX-License-Identifier: EUPL-1.2
+ *
+ * Structural validation of a state machine: states as nodes, transitions as
+ * directed edges between them. Used by CnStateMachineEditor for itemised
+ * feedback before a host saves or publishes; a host's server remains the
+ * authority on what it accepts.
+ *
+ * @module utils/stateMachineValidation
+ */
+
+import { translate as t } from '@nextcloud/l10n'
+
+/** Rule codes, one per kind of issue. */
+export const STATE_MACHINE_RULES = Object.freeze({
+	NO_FINAL_STATE: 'NO_FINAL_STATE',
+	UNREACHABLE_FINAL: 'UNREACHABLE_FINAL',
+	DANGLING_TRANSITION: 'DANGLING_TRANSITION',
+	DUPLICATE_TRANSITION: 'DUPLICATE_TRANSITION',
+	ORPHAN_STATE: 'ORPHAN_STATE',
+	CYCLE_NO_EXIT: 'CYCLE_NO_EXIT',
+})
+
+/**
+ * The record keys the validator reads, by role. A host whose records use other
+ * names passes its own (`{ final: 'isFinal', from: 'fromStatus' }`).
+ */
+export const DEFAULT_STATE_MACHINE_KEYS = Object.freeze({
+	id: 'id',
+	label: 'label',
+	final: 'final',
+	from: 'from',
+	to: 'to',
+	transitionLabel: 'label',
+})
+
+/**
+ * The default message of each rule, in the library's own domain.
+ *
+ * @return {object} Messages by rule code.
+ */
+function defaultMessages() {
+	return {
+		NO_FINAL_STATE: t('nextcloud-vue', 'No state is marked as final'),
+		UNREACHABLE_FINAL: t('nextcloud-vue', 'Final state "{name}" cannot be reached from any starting state'),
+		DANGLING_TRANSITION: t('nextcloud-vue', 'Transition "{label}" points at a state that no longer exists'),
+		DUPLICATE_TRANSITION: t('nextcloud-vue', 'Duplicate transition from "{from}" to "{to}"'),
+		ORPHAN_STATE: t('nextcloud-vue', 'State "{name}" has no transitions connecting it to the others'),
+		CYCLE_NO_EXIT: t('nextcloud-vue', 'Cycle with no way out to a final state: {names}'),
+	}
+}
+
+/**
+ * Normalise a list that may arrive as a JSON string or an array.
+ *
+ * @param {string|Array|null|undefined} raw The value.
+ * @return {Array} The array, or [] when it is neither.
+ */
+export function asList(raw) {
+	if (Array.isArray(raw)) {
+		return raw
+	}
+	if (typeof raw === 'string' && raw !== '') {
+		try {
+			const parsed = JSON.parse(raw)
+			return Array.isArray(parsed) ? parsed : []
+		} catch {
+			return []
+		}
+	}
+	return []
+}
+
+/**
+ * Fill `{name}` placeholders.
+ *
+ * @param {string} text The text.
+ * @param {object} vars Values by placeholder.
+ * @return {string} The filled text.
+ */
+function fill(text, vars) {
+	return String(text).replace(/\{(\w+)\}/g, (match, name) => (Object.hasOwn(vars, name) ? String(vars[name]) : match))
+}
+
+/**
+ * Validate a state machine.
+ *
+ * Errors block (no final state, a final state no start reaches, a transition to
+ * a state that is gone); warnings inform (duplicates, isolated states, cycles
+ * that never reach a final state). An empty machine has no issues: it is
+ * unfinished, not wrong.
+ *
+ * @param {object} graph The machine.
+ * @param {Array|string} graph.states The states.
+ * @param {Array|string} graph.transitions The transitions.
+ * @param {object} [options] Options.
+ * @param {object} [options.keys] Record keys by role, see DEFAULT_STATE_MACHINE_KEYS.
+ * @param {object} [options.messages] Message templates by rule code, overriding the defaults.
+ * @param {(text: string) => string} [options.translate] Applied to an overriding message before its placeholders are filled.
+ * @return {Array<{type: string, code: string, message: string}>} The issues.
+ */
+export function validateStateMachine({ states, transitions } = {}, options = {}) {
+	const keys = { ...DEFAULT_STATE_MACHINE_KEYS, ...(options.keys || {}) }
+	const translate = typeof options.translate === 'function' ? options.translate : (text) => text
+	const own = options.messages || {}
+	const defaults = defaultMessages()
+	const message = (code, vars) => {
+		const template = typeof own[code] === 'string' && own[code] !== '' ? translate(own[code]) : defaults[code]
+		return fill(template, vars)
+	}
+
+	const nodes = asList(states)
+	const edges = asList(transitions)
+	const issues = []
+	if (nodes.length === 0) {
+		return issues
+	}
+
+	const idOf = (node) => node[keys.id]
+	const nodeIds = new Set(nodes.map(idOf))
+	const nameOf = (id) => {
+		const node = nodes.find((candidate) => idOf(candidate) === id)
+		return (node && node[keys.label]) || id
+	}
+
+	const validEdges = []
+	edges.forEach((edge) => {
+		const from = edge[keys.from]
+		const to = edge[keys.to]
+		if (!nodeIds.has(from) || !nodeIds.has(to)) {
+			issues.push({
+				type: 'error',
+				code: STATE_MACHINE_RULES.DANGLING_TRANSITION,
+				message: message('DANGLING_TRANSITION', { label: edge[keys.transitionLabel] || `${from} → ${to}` }),
+			})
+			return
+		}
+		validEdges.push(edge)
+	})
+
+	const seenPairs = new Set()
+	validEdges.forEach((edge) => {
+		const pair = `${edge[keys.from]}::${edge[keys.to]}`
+		if (seenPairs.has(pair)) {
+			issues.push({
+				type: 'warning',
+				code: STATE_MACHINE_RULES.DUPLICATE_TRANSITION,
+				message: message('DUPLICATE_TRANSITION', { from: nameOf(edge[keys.from]), to: nameOf(edge[keys.to]) }),
+			})
+		}
+		seenPairs.add(pair)
+	})
+
+	const finals = nodes.filter((node) => node[keys.final] === true)
+	if (finals.length === 0) {
+		issues.push({
+			type: 'error',
+			code: STATE_MACHINE_RULES.NO_FINAL_STATE,
+			message: message('NO_FINAL_STATE', {}),
+		})
+	}
+
+	const forward = new Map(nodes.map((node) => [idOf(node), []]))
+	const reverse = new Map(nodes.map((node) => [idOf(node), []]))
+	validEdges.forEach((edge) => {
+		forward.get(edge[keys.from]).push(edge[keys.to])
+		reverse.get(edge[keys.to]).push(edge[keys.from])
+	})
+
+	if (nodes.length > 1) {
+		nodes.forEach((node) => {
+			if (reverse.get(idOf(node)).length === 0 && forward.get(idOf(node)).length === 0) {
+				issues.push({
+					type: 'warning',
+					code: STATE_MACHINE_RULES.ORPHAN_STATE,
+					message: message('ORPHAN_STATE', { name: node[keys.label] || idOf(node) }),
+				})
+			}
+		})
+	}
+
+	// Starting states are those nothing leads into. When every state has an
+	// incoming transition there is no entry point, so nothing is reachable.
+	const reachable = new Set()
+	const queue = nodes.filter((node) => reverse.get(idOf(node)).length === 0).map(idOf)
+	while (queue.length > 0) {
+		const current = queue.shift()
+		if (!reachable.has(current)) {
+			reachable.add(current)
+			forward.get(current).forEach((next) => queue.push(next))
+		}
+	}
+	finals.forEach((node) => {
+		if (!reachable.has(idOf(node))) {
+			issues.push({
+				type: 'error',
+				code: STATE_MACHINE_RULES.UNREACHABLE_FINAL,
+				message: message('UNREACHABLE_FINAL', { name: node[keys.label] || idOf(node) }),
+			})
+		}
+	})
+
+	const reachesFinal = new Set(finals.map(idOf))
+	const back = finals.map(idOf)
+	while (back.length > 0) {
+		reverse.get(back.shift()).forEach((previous) => {
+			if (!reachesFinal.has(previous)) {
+				reachesFinal.add(previous)
+				back.push(previous)
+			}
+		})
+	}
+
+	const WHITE = 0
+	const GREY = 1
+	const BLACK = 2
+	const colour = new Map(nodes.map((node) => [idOf(node), WHITE]))
+	const stack = []
+	const reported = new Set()
+	const visit = (id) => {
+		colour.set(id, GREY)
+		stack.push(id)
+		forward.get(id).forEach((next) => {
+			if (colour.get(next) === GREY) {
+				const cycle = stack.slice(stack.indexOf(next))
+				const cycleKey = [...cycle].sort().join(',')
+				if (!reported.has(cycleKey) && !cycle.some((member) => reachesFinal.has(member))) {
+					reported.add(cycleKey)
+					issues.push({
+						type: 'warning',
+						code: STATE_MACHINE_RULES.CYCLE_NO_EXIT,
+						message: message('CYCLE_NO_EXIT', { names: cycle.map(nameOf).join(' → ') }),
+					})
+				}
+			} else if (colour.get(next) === WHITE) {
+				visit(next)
+			}
+		})
+		stack.pop()
+		colour.set(id, BLACK)
+	}
+	nodes.forEach((node) => {
+		if (colour.get(idOf(node)) === WHITE) {
+			visit(idOf(node))
+		}
+	})
+
+	return issues
+}

package/src/utils/widgetDispatch.js

@@ -47,10 +47,12 @@ import { canonicalWidgetType } from './widgetTypeAliases.js'
  * header (link, note) come from the host, and it has no Add.
  * `parties` draws a record's parties by role and `map` a bare Leaflet map:
  * on a card surface both need the titled wrapper, and neither has an Add.
+ * `object-translations` is a bare per-language editor that takes the titled
+ * wrapper and has no Add.
  *
  * @type {string[]}
  */
-export const CONTENT_ONLY_TYPES = Object.freeze(['object-list', 'table', 'files', 'flow-runs', 'tasks', 'events', 'facts', 'linked', 'field-list', 'record-list', 'parties', 'map', 'settings-form', 'switch-rows', 'radio-cards', 'chips-field', 'toggle-table', 'choice-picker', 'checklist'])
+export const CONTENT_ONLY_TYPES = Object.freeze(['object-list', 'table', 'files', 'flow-runs', 'tasks', 'events', 'facts', 'linked', 'field-list', 'record-list', 'parties', 'map', 'settings-form', 'switch-rows', 'radio-cards', 'chips-field', 'toggle-table', 'choice-picker', 'checklist', 'object-translations'])
 
 /**
  * The stored content/config blob for a widget definition.