@conduction/nextcloud-vue 2.62.0 → 2.63.0

package/src/components/CnAdminActionCard/CnAdminActionCard.vue

@@ -0,0 +1,234 @@
+<!-- SPDX-License-Identifier: EUPL-1.2 -->
+<!-- SPDX-FileCopyrightText: 2026 Conduction B.V. <info@conduction.nl> -->
+<template>
+	<CnConfigurationCard class="cn-admin-action-card" :title="title" data-testid="cn-admin-action-card">
+		<p v-if="description" class="cn-admin-action-card__description">
+			{{ description }}
+		</p>
+		<!-- @slot default Extra content between the explanation and the button. -->
+		<slot />
+		<div class="cn-admin-action-card__footer">
+			<NcButton
+				:variant="buttonVariant"
+				:disabled="running || disabled"
+				data-testid="cn-admin-action-card-run"
+				@click="run">
+				<template v-if="running" #icon>
+					<NcLoadingIcon :size="20" />
+				</template>
+				{{ running ? runningLabel : resolvedButtonLabel }}
+			</NcButton>
+		</div>
+		<!-- role=status so a screen reader hears the outcome without moving focus. -->
+		<div role="status" aria-live="polite">
+			<NcNoteCard
+				v-if="result"
+				:type="result.success ? 'success' : 'error'"
+				data-testid="cn-admin-action-card-result">
+				{{ result.message }}
+			</NcNoteCard>
+		</div>
+	</CnConfigurationCard>
+</template>
+
+<script>
+import { translate as t } from '@nextcloud/l10n'
+import { NcButton, NcLoadingIcon, NcNoteCard } from '@nextcloud/vue'
+import CnConfigurationCard from '../CnConfigurationCard/CnConfigurationCard.vue'
+
+/**
+ * CnAdminActionCard — one maintenance action on an admin settings page.
+ *
+ * A card with a title, a short explanation and one button. The click POSTs
+ * an app action, the button spins while it runs, and the server's message
+ * shows below it as success or error. Use it for work an admin starts by
+ * hand, such as repairing the register or re-importing schemas. That work
+ * never belongs in the setup wizard.
+ *
+ * By default it posts to the app's setup action contract,
+ * `/apps/{appId}/api/setup/action/{action}`, the same endpoint the setup
+ * wizard uses. Pass `url` to post somewhere else.
+ *
+ * ```vue
+ * <CnAdminActionCard
+ *   app-id="pipelinq"
+ *   action="provision"
+ *   :title="t('pipelinq', 'Repair the register')"
+ *   :description="t('pipelinq', 'Creates missing schemas again. Your data stays as it is.')"
+ *   :button-label="t('pipelinq', 'Repair')" />
+ * ```
+ *
+ * @spec openspec/changes/setup-wizard-card-load-and-dependency-gate/specs/cn-setup-wizard/spec.md#requirement-an-admin-action-card-runs-one-server-action
+ */
+export default {
+	name: 'CnAdminActionCard',
+
+	components: {
+		CnConfigurationCard,
+		NcButton,
+		NcLoadingIcon,
+		NcNoteCard,
+	},
+
+	props: {
+		/** Card heading. Pass it translated. */
+		title: {
+			type: String,
+			required: true,
+		},
+
+		/** What the action does, in one or two short sentences. Pass it translated. */
+		description: {
+			type: String,
+			default: '',
+		},
+
+		/** The Nextcloud app id; builds the default action URL. */
+		appId: {
+			type: String,
+			default: '',
+		},
+
+		/** The action id, posted to `/apps/{appId}/api/setup/action/{action}`. */
+		action: {
+			type: String,
+			default: '',
+		},
+
+		/**
+		 * An app path to POST to instead of the setup action contract, e.g.
+		 * `/apps/pipelinq/api/settings/repair`. Passed through `generateUrl`.
+		 */
+		url: {
+			type: String,
+			default: '',
+		},
+
+		/** Request body to send with the POST. */
+		payload: {
+			type: Object,
+			default: () => ({}),
+		},
+
+		/** Button label. Defaults to "Run". */
+		buttonLabel: {
+			type: String,
+			default: '',
+		},
+
+		/** Label next to the spinner while the action runs. */
+		runningLabel: {
+			type: String,
+			default: () => t('nextcloud-vue', 'Running…'),
+		},
+
+		/** NcButton variant for the action button. */
+		buttonVariant: {
+			type: String,
+			default: 'secondary',
+		},
+
+		/** Disable the button, e.g. while a precondition is not met. */
+		disabled: {
+			type: Boolean,
+			default: false,
+		},
+	},
+
+	emits: ['result'],
+
+	data() {
+		return {
+			running: false,
+			/** @type {{ success: boolean, message: string }|null} */
+			result: null,
+		}
+	},
+
+	computed: {
+		resolvedButtonLabel() {
+			return this.buttonLabel || t('nextcloud-vue', 'Run')
+		},
+
+		/**
+		 * The app path the button posts to: `url` when set, else the setup
+		 * action contract. Empty when neither is configured.
+		 *
+		 * @return {string}
+		 */
+		actionPath() {
+			if (this.url) {
+				return this.url
+			}
+			if (this.appId && this.action) {
+				return `/apps/${this.appId}/api/setup/action/${this.action}`
+			}
+			return ''
+		},
+	},
+
+	methods: {
+		/**
+		 * Run the action: POST, spin while it runs, show the result.
+		 *
+		 * @return {Promise<void>}
+		 * @spec openspec/changes/setup-wizard-card-load-and-dependency-gate/specs/cn-setup-wizard/spec.md#requirement-an-admin-action-card-runs-one-server-action
+		 */
+		async run() {
+			if (this.running) {
+				return
+			}
+			if (!this.actionPath) {
+				this.result = { success: false, message: t('nextcloud-vue', 'This action is not configured.') }
+				return
+			}
+			this.running = true
+			this.result = null
+			let data
+			try {
+				const [{ default: axios }, { generateUrl }] = await Promise.all([
+					import('@nextcloud/axios'),
+					import('@nextcloud/router'),
+				])
+				const response = await axios.post(generateUrl(this.actionPath), this.payload)
+				data = response && response.data
+				this.result = {
+					success: !!data && data.success !== false,
+					message: (data && data.message) || t('nextcloud-vue', 'Done.'),
+				}
+			} catch (err) {
+				data = err && err.response ? err.response.data : null
+				this.result = { success: false, message: this.errorMessage(err) }
+			} finally {
+				this.running = false
+			}
+			/**
+			 * @event result The action finished.
+			 * @type {{ success: boolean, message: string, data: object|null }}
+			 */
+			this.$emit('result', { ...this.result, data })
+		},
+
+		errorMessage(err) {
+			const data = err && err.response && err.response.data
+			if (data && (data.message || data.error)) {
+				return data.message || data.error
+			}
+			return (err && err.message) || t('nextcloud-vue', 'Something went wrong.')
+		},
+	},
+}
+</script>
+
+<style scoped>
+.cn-admin-action-card__description {
+	margin: 0 0 12px;
+	color: var(--color-text-maxcontrast);
+}
+
+.cn-admin-action-card__footer {
+	display: flex;
+	gap: 8px;
+	margin-block: 8px;
+}
+</style>

package/src/components/CnAdminActionCard/index.js

@@ -0,0 +1,4 @@
+import CnAdminActionCard from './CnAdminActionCard.vue'
+
+export default CnAdminActionCard
+export { CnAdminActionCard }

package/src/components/CnAppNav/CnAppNav.vue

@@ -394,6 +394,44 @@ function byManifestOrder(a, b) {
 	return a.order - b.order
 }
 
+/** A `:name` page-path segment: name, optional `(regexp)`, optional modifier. */
+const PARAM_SEGMENT = /^:(\w+)(\([^)]*\))?([?*+])?$/
+
+/**
+ * Whether a `PARAM_SEGMENT` match may be left out (`?` or `*`).
+ *
+ * @param {Array<string>} param The match.
+ * @return {boolean} True for an optional segment.
+ */
+function isOptionalParam(param) {
+	return param[3] === '?' || param[3] === '*'
+}
+
+/**
+ * Whether a route param value fills its segment.
+ *
+ * @param {unknown} value The value.
+ * @return {boolean} False for undefined, null and the empty string.
+ */
+function isFilled(value) {
+	return value !== undefined && value !== null && value !== ''
+}
+
+/**
+ * Decode one percent-encoded path segment, or keep it as is when it is not
+ * valid percent-encoding.
+ *
+ * @param {string} segment The segment.
+ * @return {string} The decoded segment.
+ */
+function decodeSegment(segment) {
+	try {
+		return decodeURIComponent(segment)
+	} catch {
+		return segment
+	}
+}
+
 export default {
 	name: 'CnAppNav',
 
@@ -924,7 +962,9 @@ export default {
 		 * `/expenses/:id`) light up — and auto-expand — their index entry
 		 * even though the detail route name is not in the menu. Longest
 		 * prefix disambiguates nested namespaces (e.g. `/pos` vs
-		 * `/pos/refunds`). Returns null when nothing matches.
+		 * `/pos/refunds`). An entry with `params` matches by its page path
+		 * with those params filled in (see `pageMatchDepth`). Returns null
+		 * when nothing matches.
 		 *
 		 * @return {string|null}
 		 */
@@ -945,20 +985,15 @@ export default {
 				return routeName ?? null
 			}
 			let best = null
-			let bestLen = -1
+			let bestDepth = 0
 			for (const it of flat) {
 				if (!it.route) {
 					continue
 				}
-				const pagePath = this.pageForItem(it)?.route
-				if (!pagePath || pagePath === '/' || pagePath.includes(':')) {
-					continue
-				}
-				if (path === pagePath || path.startsWith(pagePath + '/')) {
-					if (pagePath.length > bestLen) {
-						best = it.route
-						bestLen = pagePath.length
-					}
+				const depth = this.pageMatchDepth(it, path)
+				if (depth > bestDepth) {
+					best = it.route
+					bestDepth = depth
 				}
 			}
 			return best ?? routeName ?? null
@@ -1007,7 +1042,9 @@ export default {
 		 * that route, else the first in menu order.
 		 *
 		 * Null whenever the existing rule already marks an entry, so a list
-		 * with an entry without a `query` behaves as it did.
+		 * with an entry without a `query` behaves as it did. An entry with
+		 * `params` is a candidate only when the current path sits below its
+		 * own filled-in page path, so another param value is never marked.
 		 *
 		 * @return {object|null} The entry to mark, or null.
 		 * @spec openspec/changes/live-check-follow-ups/specs/live-check-follow-ups/spec.md#requirement-a-page-below-a-list-marks-one-menu-entry
@@ -1017,7 +1054,9 @@ export default {
 			if (!active || this.$route?.name === active) {
 				return null
 			}
-			const entries = this.flatEntries.filter((entry) => !entry.href && entry.route === active)
+			const path = this.$route?.path
+			const entries = this.flatEntries.filter((entry) => !entry.href && entry.route === active
+				&& (!this.hasParams(entry) || this.pageMatchDepth(entry, path) > 0))
 			if (entries.length === 0 || entries.some((entry) => this.isActiveByRule(entry))) {
 				return null
 			}
@@ -1067,6 +1106,8 @@ export default {
 		// stays out of `data()`: a reactive Set mutated inside render would
 		// re-trigger the render effect.
 		this._autoCountWarned = new Set()
+		// Same latch, for warnUnfilledRouteParam() (`itemTo()` runs during render).
+		this._unfilledParamWarned = new Set()
 	},
 
 	methods: {
@@ -1275,7 +1316,19 @@ export default {
 				.sort(byManifestOrder)
 		},
 
+		/**
+		 * The label an entry shows: run through the translate function, or
+		 * as written when the entry sets `translateLabel: false` (a
+		 * user-authored title that may equal a translation key). Every
+		 * place the nav shows an entry's label reads it from here.
+		 *
+		 * @param {object} item Menu entry.
+		 * @return {string} The label to render as text.
+		 */
 		resolveLabel(item) {
+			if (item.translateLabel === false) {
+				return item.label
+			}
 			return this.effectiveTranslate(item.label)
 		},
 
@@ -1286,7 +1339,10 @@ export default {
 		 * work" and "Queue" on one list). The route name alone lit both. An
 		 * entry with a `query` is active only when the address carries that
 		 * query; an entry without one steps back when a sibling's query
-		 * matches, so exactly one of them is marked.
+		 * matches, so exactly one of them is marked. `params` work the
+		 * same way against the route's params, so of several entries on a
+		 * `/items/:slug` route only the one whose `slug` is in the address
+		 * is marked.
 		 *
 		 * On a page below a list where that rule marks nothing, the one
 		 * entry `subRouteParent` picks is active instead.
@@ -1305,9 +1361,9 @@ export default {
 		},
 
 		/**
-		 * The route and query rule on its own, without the fallback for a
-		 * page below a list. `subRouteParent` asks this to see whether the
-		 * rule already marks an entry.
+		 * The route, query and params rule on its own, without the fallback
+		 * for a page below a list. `subRouteParent` asks this to see whether
+		 * the rule already marks an entry.
 		 *
 		 * @param {object} item Menu entry.
 		 * @return {boolean} True when the rule marks the entry.
@@ -1321,17 +1377,155 @@ export default {
 			if (item.route !== this.activeRouteName) {
 				return false
 			}
-			if (item.query && typeof item.query === 'object') {
-				return this.queryMatches(item)
+			if (this.isNarrowed(item)) {
+				return this.narrowingMatches(item)
 			}
-			const siblings = []
-			for (const entry of this.visibleItems) {
-				siblings.push(entry, ...this.visibleChildren(entry))
-			}
-			return !siblings.some((entry) => entry !== item
+			return !this.flatEntries.some((entry) => entry !== item
 				&& entry.route === item.route
-				&& entry.query && typeof entry.query === 'object'
-				&& this.queryMatches(entry))
+				&& this.isNarrowed(entry)
+				&& this.narrowingMatches(entry))
+		},
+
+		/**
+		 * Whether an entry narrows its route with a `query` or `params`.
+		 *
+		 * @param {object} item Menu entry.
+		 * @return {boolean} True when the entry declares either.
+		 */
+		isNarrowed(item) {
+			return Boolean(item.query && typeof item.query === 'object') || this.hasParams(item)
+		},
+
+		/**
+		 * Whether the address carries every `query` key and every `params`
+		 * key the entry declares.
+		 *
+		 * @param {object} item Menu entry that narrows its route.
+		 * @return {boolean} True when everything it declares matches.
+		 */
+		narrowingMatches(item) {
+			const queryOk = !(item.query && typeof item.query === 'object') || this.queryMatches(item)
+			const paramsOk = !this.hasParams(item) || this.paramsMatch(item)
+			return queryOk && paramsOk
+		},
+
+		/**
+		 * Whether an entry declares a non-empty `params` object.
+		 *
+		 * @param {object} item Menu entry.
+		 * @return {boolean} True when it has route params.
+		 */
+		hasParams(item) {
+			return Boolean(item?.params) && typeof item.params === 'object' && Object.keys(item.params).length > 0
+		},
+
+		/**
+		 * Whether the route's params carry every key of an entry's
+		 * `params`. Values are compared as strings.
+		 *
+		 * @param {object} item Menu entry with `params`.
+		 * @return {boolean} True when every declared key matches.
+		 */
+		paramsMatch(item) {
+			const current = this.$route?.params ?? {}
+			return Object.keys(item.params).every((key) => String(current[key] ?? '') === String(item.params[key]))
+		},
+
+		/**
+		 * The segments of an entry's page path with its `params` filled in,
+		 * as plain values. A missing optional `:name?` segment is dropped;
+		 * null when a required one has no param, or without a page.
+		 *
+		 * @param {object} item Menu entry with `params`.
+		 * @return {Array<string>|null} The segments, or null.
+		 */
+		filledPageSegments(item) {
+			const pagePath = this.pageForItem(item)?.route
+			if (!pagePath) {
+				return null
+			}
+			const segments = []
+			for (const part of pagePath.split('/').filter(Boolean)) {
+				const param = PARAM_SEGMENT.exec(part)
+				if (!param) {
+					segments.push(part)
+					continue
+				}
+				const value = item.params?.[param[1]]
+				if (isFilled(value)) {
+					segments.push(String(value))
+				} else if (!isOptionalParam(param)) {
+					return null
+				}
+			}
+			return segments
+		},
+
+		/**
+		 * The required route param the router cannot fill when it resolves
+		 * an entry's link on its manifest page. vue-router fills a named
+		 * link's required params from the current route, then overlays every
+		 * key the entry declares, empty or null included. So a declared key
+		 * decides on its own value, and only an undeclared one falls back
+		 * to the current route. Null without a known page, or when every
+		 * required segment is filled. Reads `$route`, so it follows
+		 * navigation.
+		 *
+		 * @param {object} item Menu entry.
+		 * @return {string|null} The param name, or null.
+		 */
+		unfilledRouteParam(item) {
+			const pagePath = this.pageForItem(item)?.route
+			if (!pagePath) {
+				return null
+			}
+			const declared = item.params && typeof item.params === 'object' ? item.params : {}
+			const current = this.$route?.params ?? {}
+			for (const part of pagePath.split('/')) {
+				const param = PARAM_SEGMENT.exec(part)
+				if (!param || isOptionalParam(param)) {
+					continue
+				}
+				const value = param[1] in declared ? declared[param[1]] : current[param[1]]
+				if (!isFilled(value)) {
+					return param[1]
+				}
+			}
+			return null
+		},
+
+		/**
+		 * How deep a path sits on an entry's page path: the page path's
+		 * segment count when the path is that page or below it, else 0.
+		 * A `/` page path, or one with an unfilled `:name`, never matches.
+		 *
+		 * Without `params` the page path is compared as written. With
+		 * `params`, segments are compared decoded, because the router
+		 * percent-encodes param values in the path and the entry holds them
+		 * plain.
+		 *
+		 * @param {object} item Menu entry.
+		 * @param {string|undefined} path The path to test.
+		 * @return {number} The depth of the match, or 0.
+		 */
+		pageMatchDepth(item, path) {
+			if (!path) {
+				return 0
+			}
+			if (!this.hasParams(item)) {
+				const pagePath = this.pageForItem(item)?.route
+				if (!pagePath || pagePath === '/' || pagePath.includes(':')) {
+					return 0
+				}
+				const below = path === pagePath || path.startsWith(pagePath + '/')
+				return below ? pagePath.split('/').filter(Boolean).length : 0
+			}
+			const segments = this.filledPageSegments(item)
+			if (!segments || segments.length === 0) {
+				return 0
+			}
+			const current = path.split('/').filter(Boolean).map(decodeSegment)
+			return segments.every((segment, index) => current[index] === segment) ? segments.length : 0
 		},
 
 		/**
@@ -1454,6 +1648,27 @@ export default {
 			console.warn(`[CnAppNav] Menu entry "${item.id}" declares count: "auto" but has no resolvable index-type page with register + schema config — no badge will render.`)
 		},
 
+		/**
+		 * One-shot `console.warn` per menu entry whose link cannot fill a
+		 * required route param. Keyed by `id`, else route and label, so
+		 * entries without an id each get their own warning.
+		 *
+		 * @param {{ id?: string, route: string, label?: string }} item Menu entry descriptor.
+		 * @param {string} param The unfilled param name.
+		 * @return {void}
+		 * @private
+		 */
+		warnUnfilledRouteParam(item, param) {
+			const key = item.id ?? `${item.route}|${item.label ?? ''}`
+			if (this._unfilledParamWarned.has(key)) {
+				return
+			}
+			this._unfilledParamWarned.add(key)
+			const name = item.id ?? item.label ?? item.route
+			// eslint-disable-next-line no-console
+			console.warn(`[CnAppNav] Menu entry "${name}" cannot fill the required route param "${param}" of page "${item.route}" from its params or the current route — the entry renders without a link.`)
+		},
+
 		/**
 		 * Look up an item's resolved page (`pages[]` entry whose `id`
 		 * matches the menu item's `route`) — used to decide whether the
@@ -1476,11 +1691,17 @@ export default {
 		 * items (`action: "user-settings"`) and `href` items return
 		 * `null` so the entry is NOT a vue-router link: action items
 		 * fall through to the click handler, `href` items render a real
-		 * anchor via `itemHref`. Route items return a named route.
+		 * anchor via `itemHref`. Route items return a named route that
+		 * carries the item's `params` and `query` when it declares them.
+		 *
+		 * An item whose manifest page has a required segment that neither
+		 * its `params` nor the current route fill also returns null, with a
+		 * one-time warning: the router throws resolving such a link, which
+		 * would take the whole navigation down rather than that one entry.
 		 *
 		 * @param {object} item Menu item being rendered.
-		 * @return {object|null} A `{ name }` route object, or null for
-		 *   action / href / route-less items.
+		 * @return {object|null} A `{ name, params?, query? }` route object,
+		 *   or null for action / href / route-less / unfillable items.
 		 */
 		itemTo(item) {
 			if (item.action) {
@@ -1492,9 +1713,22 @@ export default {
 			if (!item.route) {
 				return null
 			}
-			// Carry optional query params so a nav entry can deep-link to a
-			// pre-filtered index page (e.g. one entry per case type → Cases?caseType=…).
-			return item.query ? { name: item.route, query: item.query } : { name: item.route }
+			const unfilled = this.unfilledRouteParam(item)
+			if (unfilled) {
+				this.warnUnfilledRouteParam(item, unfilled)
+				return null
+			}
+			const to = { name: item.route }
+			// Params fill a parameterised route (one entry per catalog →
+			// /catalogs/:slug); query deep-links to a pre-filtered index page
+			// (one entry per case type → Cases?caseType=…).
+			if (this.hasParams(item)) {
+				to.params = item.params
+			}
+			if (item.query) {
+				to.query = item.query
+			}
+			return to
 		},
 
 		/**
@@ -1646,6 +1880,11 @@ export default {
 				this.cnReplayWalkthrough(item.tourId)
 				return
 			}
+			// An entry left without a link (see itemTo) renders a `#` anchor;
+			// following it would change the address, so the click goes nowhere.
+			if (!item.href && this.unfilledRouteParam(item) && event && typeof event.preventDefault === 'function') {
+				event.preventDefault()
+			}
 			if (this.visibleChildren(item).length === 0) {
 				return
 			}