@conduction/nextcloud-vue 2.120.0 → 2.121.0

package/src/components/CnSchemaRulesWidget/schemaRules.js

@@ -0,0 +1,123 @@
+/**
+ * SPDX-FileCopyrightText: 2026 Conduction B.V.
+ * SPDX-License-Identifier: EUPL-1.2
+ *
+ * The rules OpenRegister's engine holds for a schema, read rather than kept:
+ * the closed sets (vocabulary), the inventory in evaluation order, and a dry
+ * run that writes nothing.
+ *
+ * A rule is keyed on its id (`<kind>:<schemaSlug>:<key>`), never on its
+ * position: the order belongs to the pipeline and moves the day a kind is
+ * added. Kind labels come from the vocabulary endpoint, so a kind added later
+ * renders instead of blanking.
+ */
+
+import axios from '@nextcloud/axios'
+import { generateUrl } from '@nextcloud/router'
+
+/** Where OpenRegister publishes the three closed sets. */
+export const RULE_VOCABULARY_PATH = '/apps/openregister/api/rules/vocabulary'
+
+/**
+ * @param {string} schema The schema slug.
+ * @return {string} The url of the schema's rule inventory.
+ */
+export function ruleInventoryUrl(schema) {
+	return generateUrl(`/apps/openregister/api/schemas/${encodeURIComponent(schema)}/rules`)
+}
+
+/**
+ * @param {string} schema The schema slug.
+ * @param {string} ruleId The rule id.
+ * @return {string} The url of the rule's dry run.
+ */
+export function ruleEvaluateUrl(schema, ruleId) {
+	return generateUrl(`/apps/openregister/api/schemas/${encodeURIComponent(schema)}/rules/${encodeURIComponent(ruleId)}/evaluate`)
+}
+
+/**
+ * @param {unknown} data An answer.
+ * @return {boolean} Whether it carries the three sets.
+ */
+export function isRuleVocabulary(data) {
+	return !!data && Array.isArray(data.kinds) && Array.isArray(data.verdicts) && Array.isArray(data.actions)
+}
+
+/**
+ * The kinds the engine publishes, keyed by kind.
+ *
+ * @param {object} vocabulary The vocabulary answer.
+ * @return {object} The descriptors, by kind.
+ */
+export function kindsByName(vocabulary) {
+	const kinds = {}
+	if (!isRuleVocabulary(vocabulary)) {
+		return kinds
+	}
+	vocabulary.kinds.forEach((kind) => {
+		const name = String((kind && kind.kind) ?? '')
+		if (name !== '') {
+			kinds[name] = kind
+		}
+	})
+	return kinds
+}
+
+/**
+ * Read the vocabulary. A refusal answers the empty sets: the vocabulary is open
+ * to any signed-in caller, so a refusal means an instance that predates the
+ * engine, and each rule then shows its own kind string.
+ *
+ * @return {Promise<object>} The vocabulary, possibly empty.
+ */
+export async function fetchRuleVocabulary() {
+	try {
+		const { data } = await axios.get(generateUrl(RULE_VOCABULARY_PATH))
+		return isRuleVocabulary(data) ? data : { kinds: [], verdicts: [], actions: [] }
+	} catch {
+		return { kinds: [], verdicts: [], actions: [] }
+	}
+}
+
+/**
+ * Read one schema's rules, in the order the engine evaluates them. The
+ * inventory is an admin read; a refusal throws for the caller to say so.
+ *
+ * @param {string} schema The schema slug.
+ * @return {Promise<Array<object>>} The rules.
+ */
+export async function fetchSchemaRules(schema) {
+	const { data } = await axios.get(ruleInventoryUrl(schema))
+	return Array.isArray(data && data.rules) ? data.rules : []
+}
+
+/**
+ * Try one rule against one stored object, writing nothing.
+ *
+ * @param {string} schema The schema slug.
+ * @param {string} ruleId The rule id.
+ * @param {string} register The register slug the object lives in.
+ * @param {string} objectId The object to try it against.
+ * @return {Promise<object>} The trial result, carrying `trace`.
+ */
+export async function evaluateRule(schema, ruleId, register, objectId) {
+	const { data } = await axios.post(ruleEvaluateUrl(schema, ruleId), { register, objectId })
+	return data || {}
+}
+
+/**
+ * The trace of a trial. `operand` and `operandValue` are what turn "why did this
+ * rule not fire" into a fact, so they are shown beside the verdict.
+ *
+ * @param {object} result The trial result.
+ * @return {{verdict: string, operand: string, operandValue: string, message: string}} The trace.
+ */
+export function traceOf(result) {
+	const trace = (result && result.trace) || {}
+	return {
+		verdict: String(trace.verdict ?? ''),
+		operand: String(trace.operand ?? ''),
+		operandValue: String(trace.operandValue ?? ''),
+		message: String(trace.message ?? (result && result.error && result.error.message) ?? ''),
+	}
+}

package/src/components/CnSearchIndexStatus/CnSearchIndexStatus.vue

@@ -0,0 +1,160 @@
+<!--
+  - SPDX-FileCopyrightText: 2026 Conduction B.V.
+  - SPDX-License-Identifier: EUPL-1.2
+-->
+<template>
+	<div class="cn-search-index-status" data-testid="cn-search-index-status">
+		<NcLoadingIcon v-if="loading" :size="24" :name="t('nextcloud-vue', 'Loading')" />
+		<NcNoteCard v-else-if="error" type="error" data-testid="cn-search-index-error">
+			{{ error }}
+		</NcNoteCard>
+		<template v-else>
+			<dl class="cn-search-index-status__figures">
+				<div>
+					<dt>{{ t('nextcloud-vue', 'Tables in scope') }}</dt>
+					<dd data-testid="cn-search-index-tables">
+						{{ status.tableCount }}
+					</dd>
+				</div>
+				<div>
+					<dt>{{ t('nextcloud-vue', 'Indexes on them') }}</dt>
+					<dd data-testid="cn-search-index-indexes">
+						{{ status.indexCount }}
+					</dd>
+				</div>
+				<div>
+					<dt>{{ t('nextcloud-vue', 'Last run') }}</dt>
+					<dd data-testid="cn-search-index-last-run">
+						{{ lastRun }}
+					</dd>
+				</div>
+				<div>
+					<dt>{{ t('nextcloud-vue', 'Rebuild without locking') }}</dt>
+					<dd data-testid="cn-search-index-concurrent">
+						{{ concurrent }}
+					</dd>
+				</div>
+			</dl>
+			<p data-testid="cn-search-index-commands">
+				{{ t('nextcloud-vue', 'Run {command} status on the server for the same figures, and {command} rebuild --apply after a schema change.', { command }) }}
+			</p>
+		</template>
+	</div>
+</template>
+
+<script>
+import { getCanonicalLocale, translate as t } from '@nextcloud/l10n'
+import { NcLoadingIcon, NcNoteCard } from '@nextcloud/vue'
+import { fetchSearchIndexStatus, SEARCH_INDEX_COMMAND, SEARCH_INDEX_STATUS_URL } from './searchIndexStatus.js'
+
+/**
+ * CnSearchIndexStatus: the state of OpenRegister's search indexes (tables in
+ * scope, indexes on them, the last maintenance run, whether a rebuild locks a
+ * table), read live and never copied. The acts are named, not offered: a
+ * rebuild walks every table in scope and nothing stops one from a settings
+ * page, so the occ verbs are printed for somebody with a shell.
+ *
+ * @spec openspec/changes/search-index-status/specs/search-index-status/spec.md
+ */
+export default {
+	name: 'CnSearchIndexStatus',
+
+	components: { NcLoadingIcon, NcNoteCard },
+
+	props: {
+		/** The app path OpenRegister reports its indexes at. */
+		source: { type: String, default: SEARCH_INDEX_STATUS_URL },
+		/** The occ command that acts on the indexes. */
+		command: { type: String, default: SEARCH_INDEX_COMMAND },
+	},
+
+	data() {
+		return {
+			loading: true,
+			error: '',
+			status: { concurrentRebuildSupported: false, tables: {}, tableCount: 0, indexCount: 0, lastRun: null },
+		}
+	},
+
+	computed: {
+		/** @return {string} When maintenance last ran, or that it never has. */
+		lastRun() {
+			if (!this.status.lastRun) {
+				return t('nextcloud-vue', 'Never')
+			}
+			const when = new Date(this.status.lastRun)
+			if (Number.isNaN(when.getTime())) {
+				return String(this.status.lastRun)
+			}
+			return when.toLocaleString(getCanonicalLocale(), { dateStyle: 'medium', timeStyle: 'short' })
+		},
+
+		/** @return {string} Whether a rebuild locks the table, in words. */
+		concurrent() {
+			return this.status.concurrentRebuildSupported === true
+				? t('nextcloud-vue', 'Yes')
+				: t('nextcloud-vue', 'No, a rebuild locks the table it is on')
+		},
+	},
+
+	mounted() {
+		this.load()
+	},
+
+	methods: {
+		t,
+
+		/**
+		 * Read what OpenRegister says about its indexes.
+		 *
+		 * @return {Promise<void>}
+		 */
+		async load() {
+			this.loading = true
+			this.error = ''
+			try {
+				this.status = await fetchSearchIndexStatus(this.source)
+			} catch (e) {
+				this.error = String((e && e.message) || e)
+			} finally {
+				this.loading = false
+			}
+		},
+	},
+}
+</script>
+
+<style scoped>
+/* Label above value, and the label wraps: Nextcloud's settings stylesheet gives a `dt` a fixed width. */
+.cn-search-index-status__figures {
+	display: grid;
+	grid-template-columns: repeat(auto-fit, minmax(160px, 1fr));
+	gap: 16px 24px;
+	margin-block: 0 12px;
+}
+
+.cn-search-index-status__figures > div {
+	display: flex;
+	flex-direction: column;
+	gap: 2px;
+	min-width: 0;
+}
+
+.cn-search-index-status__figures dt {
+	display: block;
+	float: none;
+	width: auto;
+	margin: 0;
+	padding: 0;
+	text-align: start;
+	white-space: normal;
+	overflow-wrap: anywhere;
+	color: var(--color-text-maxcontrast);
+}
+
+.cn-search-index-status__figures dd {
+	font-weight: bold;
+	margin: 0;
+	overflow-wrap: anywhere;
+}
+</style>

package/src/components/CnSearchIndexStatus/index.js

@@ -0,0 +1,10 @@
+/**
+ * SPDX-FileCopyrightText: 2026 Conduction B.V.
+ * SPDX-License-Identifier: EUPL-1.2
+ */
+
+import CnSearchIndexStatus from './CnSearchIndexStatus.vue'
+
+export default CnSearchIndexStatus
+export { CnSearchIndexStatus }
+export { lastRunTime, SEARCH_INDEX_COMMAND } from './searchIndexStatus.js'

package/src/components/CnSearchIndexStatus/searchIndexStatus.js

@@ -0,0 +1,56 @@
+/**
+ * SPDX-FileCopyrightText: 2026 Conduction B.V.
+ * SPDX-License-Identifier: EUPL-1.2
+ */
+
+import axios from '@nextcloud/axios'
+import { generateUrl } from '@nextcloud/router'
+
+/** The occ command that rebuilds, snapshots, restores and reports the indexes. */
+export const SEARCH_INDEX_COMMAND = 'occ openregister:tables:search-index'
+
+/** Where OpenRegister reports its search indexes. */
+export const SEARCH_INDEX_STATUS_URL = '/apps/openregister/api/settings/search-index'
+
+/**
+ * When the last stored run finished, or started, or null when none ran.
+ *
+ * OpenRegister answers `lastRun` as the report of that run (`startedAt`,
+ * `finishedAt`) and as `[]` when nothing ran.
+ *
+ * @param {object|Array|string|null|undefined} report What OpenRegister answered as `lastRun`.
+ * @return {string|null} An ISO 8601 time, or null when no run is on record.
+ */
+export function lastRunTime(report) {
+	if (typeof report === 'string') {
+		return report === '' ? null : report
+	}
+	if (report === null || typeof report !== 'object' || Array.isArray(report)) {
+		return null
+	}
+	const time = report.finishedAt || report.startedAt || ''
+	return typeof time === 'string' && time !== '' ? time : null
+}
+
+/**
+ * What OpenRegister says about the indexes behind object search. A failed
+ * read throws: an outage and an instance with no indexes look the same from
+ * the browser, and only one of them is somebody's problem.
+ *
+ * @param {string} [url] The app path to read.
+ * @return {Promise<{concurrentRebuildSupported: boolean, tables: object, tableCount: number, indexCount: number, lastRun: (string|null)}>}
+ * @throws {Error} When it cannot be read.
+ */
+export async function fetchSearchIndexStatus(url = SEARCH_INDEX_STATUS_URL) {
+	const { data } = await axios.get(generateUrl(url))
+	if (data === null || typeof data !== 'object' || data.error !== undefined) {
+		throw new Error(String((data && data.error) ?? 'The search index status could not be read.'))
+	}
+	return {
+		concurrentRebuildSupported: data.concurrentRebuildSupported === true,
+		tables: data.tables && typeof data.tables === 'object' ? data.tables : {},
+		tableCount: Number(data.tableCount ?? 0),
+		indexCount: Number(data.indexCount ?? 0),
+		lastRun: lastRunTime(data.lastRun),
+	}
+}

package/src/components/CnShippedConfigurationSection/CnShippedConfigurationSection.vue

@@ -0,0 +1,328 @@
+<!--
+  - SPDX-FileCopyrightText: 2026 Conduction B.V.
+  - SPDX-License-Identifier: EUPL-1.2
+-->
+<template>
+	<div class="cn-shipped-configuration" data-testid="cn-shipped-configuration">
+		<p v-if="description" class="cn-shipped-configuration__intro">
+			{{ text(description) }}
+		</p>
+
+		<NcSelect v-if="schemas.length > 1"
+			v-model="schemaOption"
+			class="cn-shipped-configuration__picker"
+			:options="schemaOptions"
+			:inputLabel="t('nextcloud-vue', 'Show')"
+			:clearable="false"
+			data-testid="cn-shipped-schema" />
+
+		<table class="cn-shipped-configuration__table" data-testid="cn-shipped-configuration-table">
+			<thead>
+				<tr>
+					<th scope="col">
+						{{ t('nextcloud-vue', 'Name') }}
+					</th>
+					<th scope="col">
+						{{ t('nextcloud-vue', 'State') }}
+					</th>
+					<th scope="col">
+						{{ t('nextcloud-vue', 'Shipped set') }}
+					</th>
+					<th scope="col">
+						{{ t('nextcloud-vue', 'Version') }}
+					</th>
+					<th scope="col">
+						{{ t('nextcloud-vue', 'Newer version') }}
+					</th>
+				</tr>
+			</thead>
+			<tbody>
+				<tr v-for="row in rows" :key="row.targetObject">
+					<td>{{ row.title || row.targetObject }}</td>
+					<td :data-testid="'cn-shipped-state-' + row.targetObject">
+						{{ stateLabel(row) }}
+					</td>
+					<td>{{ row.set }}</td>
+					<td>{{ row.setVersion }}</td>
+					<td>
+						<NcButton v-if="updatable(row)"
+							:data-testid="'cn-shipped-adopt-' + row.targetObject"
+							:disabled="adopting === row.targetObject"
+							@click="adopt(row)">
+							{{ adoptLabel(row) }}
+						</NcButton>
+						<span v-else class="cn-shipped-configuration__muted">
+							{{ t('nextcloud-vue', 'Up to date') }}
+						</span>
+					</td>
+				</tr>
+				<tr v-if="!rows.length">
+					<td colspan="5"
+						class="cn-shipped-configuration__muted"
+						data-testid="cn-shipped-configuration-empty">
+						{{ emptyLine }}
+					</td>
+				</tr>
+			</tbody>
+		</table>
+
+		<NcNoteCard v-if="loadError" type="error" data-testid="cn-shipped-configuration-error">
+			{{ loadError }}
+		</NcNoteCard>
+		<NcNoteCard v-if="adoptError" type="error" data-testid="cn-shipped-configuration-adopt-error">
+			{{ adoptError }}
+		</NcNoteCard>
+	</div>
+</template>
+
+<script>
+import axios from '@nextcloud/axios'
+import { showSuccess } from '@nextcloud/dialogs'
+import { translate as t } from '@nextcloud/l10n'
+import { generateUrl } from '@nextcloud/router'
+import { NcButton, NcNoteCard, NcSelect } from '@nextcloud/vue'
+
+/**
+ * The states a seeded object can be in.
+ *
+ * @type {Readonly<Record<string, string>>}
+ */
+export const SHIPPED_STATES = Object.freeze({
+	shipped: 'shipped',
+	changed: 'changed',
+	local: 'local',
+	removed: 'removed',
+})
+
+/**
+ * CnShippedConfigurationSection: what an app shipped, what this instance
+ * changed, and what it authored. One row per seeded object with the set and
+ * version it came from, its state, and the newer version offered per object.
+ * Taking a newer version over a local change says so on the button, because
+ * the change goes.
+ *
+ * The app's endpoint answers `GET {endpoint}/{schema}` with `{ items: [{
+ * targetObject, title, state, set, setVersion, latestVersion, updateAvailable
+ * }] }` and takes `POST {endpoint}/{schema}/{targetObject}/adopt` with `{ set,
+ * acceptLocalChangeLoss }`, refusing with `{ reason }`. An empty ledger beside
+ * a register that holds objects is said as such (`countUrl`), not as "nothing
+ * seeded".
+ *
+ * @spec openspec/changes/shipped-configuration-section/specs/shipped-configuration-section/spec.md
+ */
+export default {
+	name: 'CnShippedConfigurationSection',
+
+	components: { NcButton, NcNoteCard, NcSelect },
+
+	inject: {
+		/** The host app's translate, for the texts the page declares. */
+		cnTranslate: { default: () => (key) => key },
+	},
+
+	props: {
+		/** The app path of the shipped ledger (`/apps/<app>/api/starter/shipped`). */
+		endpoint: { type: String, required: true },
+		/** The schemas to show, `[{ slug, label }]`; the first is shown first. */
+		schemas: { type: Array, default: () => [] },
+		/**
+		 * An app path that counts a schema's objects, `{schema}` filled in
+		 * (`/apps/openregister/api/objects/<register>/{schema}`), read with
+		 * `_limit=1` for its `total`.
+		 */
+		countUrl: { type: String, default: '' },
+		/** A line above the table. */
+		description: { type: String, default: '' },
+	},
+
+	data() {
+		return {
+			schema: this.schemas.length > 0 ? String(this.schemas[0].slug) : '',
+			rows: [],
+			present: null,
+			loadError: '',
+			adoptError: '',
+			adopting: '',
+		}
+	},
+
+	computed: {
+		/** @return {Array<{id: string, label: string}>} The picker's options. */
+		schemaOptions() {
+			return this.schemas.map((option) => ({ id: String(option.slug), label: this.text(option.label || option.slug) }))
+		},
+
+		schemaOption: {
+			/** @return {object|null} The chosen schema. */
+			get() {
+				return this.schemaOptions.find((option) => option.id === this.schema) || null
+			},
+
+			/** @param {object|null} option The chosen schema. */
+			set(option) {
+				if (option) {
+					this.schema = option.id
+					this.reload()
+				}
+			},
+		},
+
+		/** @return {string} What the empty table says, which depends on what the register holds. */
+		emptyLine() {
+			if (typeof this.present === 'number' && this.present > 0) {
+				return t('nextcloud-vue', 'The register holds {count} of these. None came from a shipped set, so there is no shipped version to compare with.', { count: this.present })
+			}
+			return t('nextcloud-vue', 'Nothing has been seeded yet.')
+		},
+	},
+
+	mounted() {
+		this.reload()
+	},
+
+	methods: {
+		t,
+
+		/**
+		 * @param {string} value A declared text.
+		 * @return {string} It, translated by the host.
+		 */
+		text(value) {
+			return value ? String(this.cnTranslate(String(value))) : ''
+		},
+
+		/**
+		 * Read what shipped for the shown schema. A failed read empties the
+		 * table: rows left beside an error would read as the current state.
+		 *
+		 * @return {Promise<void>}
+		 */
+		async reload() {
+			if (!this.schema) {
+				return
+			}
+			try {
+				const { data } = await axios.get(generateUrl(`${this.endpoint}/${encodeURIComponent(this.schema)}`))
+				this.rows = Array.isArray(data && data.items) ? data.items : []
+				this.loadError = ''
+				this.present = null
+				if (this.rows.length === 0) {
+					this.present = await this.count()
+				}
+			} catch {
+				this.rows = []
+				this.present = null
+				this.loadError = t('nextcloud-vue', 'Could not read the shipped configuration.')
+			}
+		},
+
+		/**
+		 * How many objects of the shown schema the register holds, whatever
+		 * brought them.
+		 *
+		 * @return {Promise<number|null>} The count, or null when it cannot be read.
+		 */
+		async count() {
+			if (!this.countUrl) {
+				return null
+			}
+			try {
+				const { data } = await axios.get(generateUrl(this.countUrl.replace('{schema}', encodeURIComponent(this.schema))), { params: { _limit: 1 } })
+				const total = Number(data && data.total)
+				return Number.isFinite(total) ? total : null
+			} catch {
+				return null
+			}
+		},
+
+		/**
+		 * @param {object} row A ledger row.
+		 * @return {string} What an administrator reads beside the object.
+		 */
+		stateLabel(row) {
+			const state = (row && row.state) || SHIPPED_STATES.local
+			return {
+				[SHIPPED_STATES.shipped]: t('nextcloud-vue', 'Shipped, unchanged'),
+				[SHIPPED_STATES.changed]: t('nextcloud-vue', 'Shipped, changed here'),
+				[SHIPPED_STATES.removed]: t('nextcloud-vue', 'Shipped, removed here'),
+			}[state] || t('nextcloud-vue', 'Yours')
+		},
+
+		/**
+		 * @param {object} row A ledger row.
+		 * @return {boolean} Whether a newer shipped version can be taken.
+		 */
+		updatable(row) {
+			return Boolean(row && row.updateAvailable && row.state !== SHIPPED_STATES.removed)
+		},
+
+		/**
+		 * @param {object} row A ledger row.
+		 * @return {boolean} Whether taking the newer version overwrites a local change.
+		 */
+		losesLocalChange(row) {
+			return Boolean(row && row.state === SHIPPED_STATES.changed)
+		},
+
+		/**
+		 * @param {object} row A ledger row.
+		 * @return {string} The button's words, which say when a local change goes.
+		 */
+		adoptLabel(row) {
+			return this.losesLocalChange(row)
+				? t('nextcloud-vue', 'Take {version} and lose your change', { version: row.latestVersion })
+				: t('nextcloud-vue', 'Take {version}', { version: row.latestVersion })
+		},
+
+		/**
+		 * Take the newer shipped version of one object, then read the ledger again.
+		 *
+		 * @param {object} row A ledger row.
+		 * @return {Promise<void>}
+		 */
+		async adopt(row) {
+			this.adopting = row.targetObject
+			this.adoptError = ''
+			try {
+				await axios.post(
+					generateUrl(`${this.endpoint}/${encodeURIComponent(this.schema)}/${encodeURIComponent(row.targetObject)}/adopt`),
+					{ set: row.set, acceptLocalChangeLoss: this.losesLocalChange(row) },
+				)
+				showSuccess(t('nextcloud-vue', 'The newer version was taken.'))
+				await this.reload()
+			} catch (error) {
+				const data = error && error.response && error.response.data
+				this.adoptError = String((data && (data.reason || data.message)) || t('nextcloud-vue', 'The newer version was not taken.'))
+			} finally {
+				this.adopting = ''
+			}
+		},
+	},
+}
+</script>
+
+<style scoped>
+.cn-shipped-configuration__intro,
+.cn-shipped-configuration__muted {
+	color: var(--color-text-maxcontrast);
+}
+
+.cn-shipped-configuration__picker {
+	max-width: 320px;
+}
+
+.cn-shipped-configuration__table {
+	width: 100%;
+	border-collapse: collapse;
+	margin-top: 12px;
+	/* Nextcloud sets `table { white-space: nowrap }`; a cell here can be a sentence. */
+	white-space: normal;
+}
+
+.cn-shipped-configuration__table th,
+.cn-shipped-configuration__table td {
+	padding: 6px 8px;
+	border-bottom: 1px solid var(--color-border);
+	text-align: start;
+}
+</style>

package/src/components/CnShippedConfigurationSection/index.js

@@ -0,0 +1,9 @@
+/**
+ * SPDX-FileCopyrightText: 2026 Conduction B.V.
+ * SPDX-License-Identifier: EUPL-1.2
+ */
+
+import CnShippedConfigurationSection from './CnShippedConfigurationSection.vue'
+
+export default CnShippedConfigurationSection
+export { CnShippedConfigurationSection }