@conduction/nextcloud-vue 2.61.0 → 2.63.0

package/src/composables/useWalkthrough.js

@@ -199,6 +199,162 @@ export function persistWalkthroughSeenVersion(appId, configKey, version, options
 	}
 }
 
+/**
+ * localStorage key prefix for the per-browser mirror of tour progress.
+ */
+export const WALKTHROUGH_PROGRESS_STORAGE_PREFIX = 'cn-walkthrough-progress:'
+
+/**
+ * The preference key that holds tour progress, next to the completion key.
+ *
+ * @param {string} configKey `manifest.walkthrough.completionConfigKey` (may be empty).
+ * @return {string} `<configKey>-progress`, or '' when no key is declared.
+ */
+export function walkthroughProgressKey(configKey) {
+	return configKey ? configKey + '-progress' : ''
+}
+
+/**
+ * Normalise stored progress (an object, or the JSON string a preference
+ * holds) into `{ tourId, stepId, index, version }`, or null.
+ *
+ * @spec openspec/changes/walkthrough-advance-pause-resume/specs/cn-walkthrough/spec.md
+ * @param {unknown} value The stored value.
+ * @return {{tourId: string, stepId: string, index: number, version: string}|null} The progress.
+ */
+export function normaliseWalkthroughProgress(value) {
+	let data = value
+	if (typeof data === 'string') {
+		if (data === '') {
+			return null
+		}
+		try {
+			data = JSON.parse(data)
+		} catch {
+			return null
+		}
+	}
+	if (!isPlainObject(data) || typeof data.tourId !== 'string' || data.tourId === '') {
+		return null
+	}
+	return {
+		tourId: data.tourId,
+		stepId: typeof data.stepId === 'string' ? data.stepId : '',
+		index: Number.isInteger(data.index) && data.index >= 0 ? data.index : 0,
+		version: typeof data.version === 'string' ? data.version : '',
+	}
+}
+
+/**
+ * Read the per-browser mirror of the tour progress. Synchronous.
+ *
+ * @spec openspec/changes/walkthrough-advance-pause-resume/specs/cn-walkthrough/spec.md
+ * @param {string} appId The Nextcloud app id.
+ * @param {Storage} [storage] Injectable storage backend.
+ * @return {object|null} The progress, or null.
+ */
+export function readLocalWalkthroughProgress(appId, storage) {
+	const s = resolveStorage(storage)
+	if (!s) {
+		return null
+	}
+	try {
+		return normaliseWalkthroughProgress(s.getItem(WALKTHROUGH_PROGRESS_STORAGE_PREFIX + appId))
+	} catch {
+		return null
+	}
+}
+
+/**
+ * Load the user's tour progress: the per-user preference
+ * `<completionConfigKey>-progress` when declared, else the local mirror.
+ *
+ * @spec openspec/changes/walkthrough-advance-pause-resume/specs/cn-walkthrough/spec.md
+ * @param {string} appId The Nextcloud app id.
+ * @param {string} configKey `manifest.walkthrough.completionConfigKey` (may be empty).
+ * @param {object} [options] `{ http, storage }` injection points for tests.
+ * @return {Promise<object|null>} The progress, or null.
+ */
+export async function loadWalkthroughProgress(appId, configKey, options = {}) {
+	const local = readLocalWalkthroughProgress(appId, options.storage)
+	const key = walkthroughProgressKey(configKey)
+	if (!key) {
+		return local
+	}
+	const http = options.http || axios
+	try {
+		const { data } = await http.get(walkthroughPreferenceUrl(appId, key))
+		if (!isPlainObject(data) || !('value' in data)) {
+			return local
+		}
+		return normaliseWalkthroughProgress(data.value) || local
+	} catch {
+		return local
+	}
+}
+
+/**
+ * Persist the user's tour progress, or clear it with `null`. Writes the
+ * local mirror and, with a completion key, the per-user preference. Never
+ * throws.
+ *
+ * @spec openspec/changes/walkthrough-advance-pause-resume/specs/cn-walkthrough/spec.md
+ * @param {string} appId The Nextcloud app id.
+ * @param {string} configKey `manifest.walkthrough.completionConfigKey` (may be empty).
+ * @param {object|null} progress `{ tourId, stepId, index, version }`, or null to clear.
+ * @param {object} [options] `{ http, storage }` injection points for tests.
+ * @return {Promise<boolean>} True when the server preference was written.
+ */
+export function persistWalkthroughProgress(appId, configKey, progress, options = {}) {
+	const value = progress ? normaliseWalkthroughProgress(progress) : null
+	const raw = value ? JSON.stringify(value) : ''
+	const s = resolveStorage(options.storage)
+	if (s) {
+		try {
+			if (raw) {
+				s.setItem(WALKTHROUGH_PROGRESS_STORAGE_PREFIX + appId, raw)
+			} else {
+				s.removeItem(WALKTHROUGH_PROGRESS_STORAGE_PREFIX + appId)
+			}
+		} catch {
+			/* quota / private mode: best-effort */
+		}
+	}
+	const key = walkthroughProgressKey(configKey)
+	if (!key) {
+		return Promise.resolve(false)
+	}
+	const http = options.http || axios
+	try {
+		return Promise.resolve(http.put(walkthroughPreferenceUrl(appId, key), { value: raw }))
+			.then(() => true)
+			.catch(() => false)
+	} catch {
+		return Promise.resolve(false)
+	}
+}
+
+/**
+ * Whether an `object-created` signal satisfies a step's `advanceOn`.
+ *
+ * The signal's own `register` / `schema` (the slugs the creating surface
+ * knows) are compared first; an object's `@self` values are numeric ids on
+ * OpenRegister and only match a step that also uses ids.
+ *
+ * @param {object} advanceOn The step's `advanceOn`.
+ * @param {object} signal `{ register?, schema?, object? }`.
+ * @return {boolean} True when it matches.
+ */
+function objectCreatedMatches(advanceOn, signal) {
+	const obj = signal.object || {}
+	const self = obj['@self'] || {}
+	const same = (want, candidates) => !want || candidates
+		.filter((c) => c !== null && c !== undefined && c !== '')
+		.some((c) => String(c).toLowerCase() === String(want).toLowerCase())
+	return same(advanceOn.register, [signal.register, obj.register, self.register])
+		&& same(advanceOn.schema, [signal.schema, obj.schema, self.schema])
+}
+
 /**
  * Compare two semver-ish strings. Missing / unparseable parts sort as 0.
  *
@@ -276,6 +432,9 @@ export function useWalkthrough(appId, manifest, options = {}) {
 		const currentIndex = ref(0)
 		const context = ref({})
 		const running = ref(false)
+		// True while the tour is hidden by ESC or a backdrop click. The tour
+		// and its step stay, so it continues where it was.
+		const paused = ref(false)
 		// True while a user-initiated replay is active (the "Restart tutorial"
 		// entry). A replay shows the FULL tour regardless of the persisted
 		// seen-version — otherwise a returning user, whose seenVersion already
@@ -479,6 +638,7 @@ export function useWalkthrough(appId, manifest, options = {}) {
 		 */
 		function start(tourId, startIndex = 0) {
 			replaying.value = false
+			paused.value = false
 			activeTourId.value = tourId
 			currentIndex.value = startIndex
 			context.value = {}
@@ -503,9 +663,59 @@ export function useWalkthrough(appId, manifest, options = {}) {
 		 */
 		function dismiss() {
 			running.value = false
+			paused.value = false
 			activeTourId.value = null
 			replaying.value = false
 		}
+		/**
+		 * Hide the active tour without ending it (ESC, a click on the dim).
+		 * The tour and step are kept, so `resumePaused()` continues there.
+		 *
+		 * @spec openspec/changes/walkthrough-advance-pause-resume/specs/cn-walkthrough/spec.md
+		 * @return {void}
+		 */
+		function pause() {
+			if (!activeTourId.value) {
+				return
+			}
+			running.value = false
+			paused.value = true
+		}
+		/**
+		 * Show a paused tour again at the step it was on.
+		 *
+		 * @spec openspec/changes/walkthrough-advance-pause-resume/specs/cn-walkthrough/spec.md
+		 * @return {boolean} True when there was a paused tour to show.
+		 */
+		function resumePaused() {
+			if (!paused.value || !activeTourId.value) {
+				return false
+			}
+			paused.value = false
+			running.value = true
+			return true
+		}
+		/**
+		 * Start a tour at a remembered step ("continue where you left off").
+		 * Runs in replay mode so a returning user sees the full tour, and
+		 * falls back to the first step when the step no longer exists.
+		 *
+		 * @spec openspec/changes/walkthrough-advance-pause-resume/specs/cn-walkthrough/spec.md
+		 * @param {string} tourId The tour id.
+		 * @param {string} [stepId] The step to continue at.
+		 * @return {boolean} True when the tour exists and started.
+		 */
+		function resumeAt(tourId, stepId) {
+			const tour = tours.find((t) => t.id === tourId)
+			if (!tour) {
+				return false
+			}
+			replaying.value = true
+			const idx = composeSteps(tour).findIndex((s) => s.id === stepId)
+			start(tourId, Math.max(0, idx))
+			replaying.value = true
+			return true
+		}
 		/**
 		 * Mark the active tour complete: stop running and invoke the
 		 * `onComplete(appVersion)` persistence callback so the seen version is
@@ -515,6 +725,7 @@ export function useWalkthrough(appId, manifest, options = {}) {
 		 */
 		function complete() {
 			running.value = false
+			paused.value = false
 			activeTourId.value = null
 			replaying.value = false
 			if (typeof options.onComplete === 'function') {
@@ -542,12 +753,9 @@ export function useWalkthrough(appId, manifest, options = {}) {
 					runCapture(step, { params: signal.params || {} })
 				}
 			} else if (signal.kind === 'object-created' && a.type === 'object-created') {
-				const obj = signal.object || {}
-				const reg = obj.register ?? obj['@self']?.register
-				const sch = obj.schema ?? obj['@self']?.schema
-				match = (!a.register || reg === a.register) && (!a.schema || sch === a.schema)
+				match = objectCreatedMatches(a, signal)
 				if (match) {
-					runCapture(step, { object: obj })
+					runCapture(step, { object: signal.object || {} })
 				}
 			} else if (signal.kind === 'element' && a.type === 'element-appears') {
 				match = true
@@ -575,9 +783,13 @@ export function useWalkthrough(appId, manifest, options = {}) {
 			isLast,
 			context,
 			running,
+			paused,
 			replaying,
 			start,
 			restart,
+			pause,
+			resumePaused,
+			resumeAt,
 			next,
 			back,
 			skip,

package/src/css/dashboard.css

@@ -80,3 +80,52 @@
 .cn-dashboard-list__item:hover {
 	background: var(--color-background-hover);
 }
+
+/* "Install <app>" placeholder in a widget whose app is missing.
+ *
+ * NcEmptyContent centres its content with `justify-content: center`. In a
+ * two-row dashboard tile (about 150px inside an `overflow: hidden` wrapper)
+ * the icon, name, description and button are taller than the tile, and plain
+ * `center` overflows on BOTH sides, so the top ran out of the widget and the
+ * name was cut off. `safe center` falls back to the start edge when the
+ * content does not fit, the spacing is compact, and what still does not fit
+ * scrolls instead of being clipped. Shared by CnDashboardPage and
+ * CnDetailWidgetHost (`cn-requires-app`). The class is doubled to outrank
+ * NcEmptyContent's own scoped rules (`.empty-content[data-v-…]`) whatever
+ * order the stylesheets load in. */
+.cn-requires-app.cn-requires-app.empty-content,
+.cn-requires-app.cn-requires-app .empty-content {
+	justify-content: safe center;
+	min-height: 0;
+	max-height: 100%;
+	overflow: auto;
+	margin: 0;
+	padding: calc(2 * var(--default-grid-baseline, 4px));
+	gap: var(--default-grid-baseline, 4px);
+	box-sizing: border-box;
+}
+
+.cn-requires-app.cn-requires-app .empty-content__icon {
+	width: auto;
+	height: auto;
+	min-height: 0;
+	margin: 0;
+	opacity: 0.7;
+}
+
+.cn-requires-app.cn-requires-app .empty-content__name {
+	margin: 0;
+	font-size: var(--default-font-size, 15px);
+	font-weight: 600;
+	text-align: center;
+}
+
+.cn-requires-app.cn-requires-app .empty-content__description {
+	margin: 0;
+	text-align: center;
+	font-size: 0.9em;
+}
+
+.cn-requires-app.cn-requires-app .empty-content__action {
+	margin-top: var(--default-grid-baseline, 4px);
+}

package/src/css/detail-page.css

@@ -106,6 +106,25 @@
 	flex-shrink: 0;
 }
 
+/* Every control in the header sits on one line at one height. The lifecycle
+   bar carries `margin: 0 0 8px` for its place above a page body; in the
+   header that margin pushed its buttons up and made the row 8px taller, so
+   the Edit button beside it read as the bigger one. A consumer's actions
+   component can bring its own margins too, so they are reset here as well. */
+.cn-detail-page .cn-detail-page__header-actions .cn-lifecycle-actions {
+	margin: 0;
+	flex-wrap: nowrap;
+}
+
+.cn-detail-page .cn-detail-page__header-actions > * {
+	margin-block: 0;
+}
+
+.cn-detail-page .cn-detail-page__header-actions .button-vue {
+	min-height: var(--default-clickable-area);
+	block-size: var(--default-clickable-area);
+}
+
 /* The sentence a refused lock acquire left behind, under the locked banner. */
 .cn-detail-page__lock-refusal {
 	margin: 0 0 calc(3 * var(--default-grid-baseline));

package/src/css/table.css

@@ -295,8 +295,88 @@
 	outline-offset: -2px;
 }
 
-/* Multi-column sort priority badge (1, 2, 3) — only rendered once more than
-   one sort key is active; a single active sort shows the arrow alone. */
+/* Header filter button (CnDataTable `filterable`). 24px hit area with the
+   16px icon; the filled icon plus the primary colour marks an active filter,
+   so the state never rests on colour alone. */
+.cn-table-header__filter {
+	display: inline-flex;
+	align-items: center;
+	justify-content: center;
+	width: 24px;
+	min-width: 24px;
+	height: 24px;
+	min-height: 24px;
+	margin: 0 0 0 4px;
+	padding: 0;
+	border: none;
+	border-radius: var(--border-radius, 4px);
+	background: transparent;
+	color: var(--color-text-maxcontrast);
+	vertical-align: middle;
+	cursor: pointer;
+}
+
+.cn-table-header__filter:hover {
+	background-color: var(--color-background-hover);
+	color: var(--color-main-text);
+}
+
+.cn-table-header__filter:focus-visible {
+	outline: 2px solid var(--color-main-text);
+	outline-offset: 0;
+}
+
+.cn-table-header__filter--active {
+	color: var(--color-primary-element);
+}
+
+/* Active header filters above the table, one removable chip each. */
+.cn-data-table__filter-chips {
+	display: flex;
+	flex-wrap: wrap;
+	gap: 6px;
+	margin: 0 0 8px;
+	padding: 0;
+	list-style: none;
+}
+
+.cn-data-table__filter-chip {
+	display: inline-flex;
+	align-items: center;
+	gap: 4px;
+	padding: 2px 4px 2px 10px;
+	border: 1px solid var(--color-border-dark);
+	border-radius: var(--border-radius-pill, 16px);
+	background-color: var(--color-background-dark);
+	color: var(--color-main-text);
+}
+
+.cn-data-table__filter-chip-remove {
+	display: inline-flex;
+	align-items: center;
+	justify-content: center;
+	width: 24px;
+	min-width: 24px;
+	height: 24px;
+	min-height: 24px;
+	margin: 0;
+	padding: 0;
+	border: none;
+	border-radius: 50%;
+	background: transparent;
+	color: var(--color-main-text);
+	cursor: pointer;
+}
+
+.cn-data-table__filter-chip-remove:hover {
+	background-color: var(--color-background-hover);
+}
+
+.cn-data-table__filter-chip-remove:focus-visible {
+	outline: 2px solid var(--color-main-text);
+}
+
+/* Multi-column sort priority badge (1, 2, 3), rendered only when two or more rendered, sortable columns are sorted. */
 .cn-table-sort-badge {
 	display: inline-flex;
 	align-items: center;

package/src/index.js

@@ -35,6 +35,7 @@ export {
 	CnActionsBar,
 	CnActionsMenu,
 	CnAddWidgetModal,
+	CnAdminActionCard,
 	CnAdminSettingsShell,
 	CnAdvancedFormDialog,
 	CnAppLoading,
@@ -268,6 +269,7 @@ export {
 	CnTileWidget,
 	CnTimelineStages,
 	CnTimelineView,
+	CnTimelineWidget,
 	CnTranslatedBadge,
 	CnTreeView,
 	CnUserActionMenu,

package/src/public/index.js

@@ -40,6 +40,10 @@
  * claiming purity is worth nothing; the check is in CI.
  */
 
+// The brand stripe imports nothing at all, so it is public-safe as it is: a
+// portal draws the organisation's motif under its header with the same
+// component, and the same tokens, as a Nextcloud page (brand-motif-token).
+import CnBrandStripe from '../components/CnBrandStripe/CnBrandStripe.vue'
 import CnSiteCard from './components/CnSiteCard.vue'
 import CnSiteCardGrid from './components/CnSiteCardGrid.vue'
 import CnSiteEmptyState from './components/CnSiteEmptyState.vue'
@@ -50,6 +54,7 @@ import CnSiteSearch from './components/CnSiteSearch.vue'
 import CnSiteSection from './components/CnSiteSection.vue'
 
 export {
+	CnBrandStripe,
 	CnSiteCard,
 	CnSiteCardGrid,
 	CnSiteEmptyState,

package/src/schemas/app-manifest-v2.schema.json

@@ -3,7 +3,7 @@
 	"$id": "https://raw.githubusercontent.com/ConductionNL/nextcloud-vue/main/src/schemas/app-manifest-v2.schema.json",
 	"title": "Conduction App Manifest v2",
 	"description": "v2 schema for the JSON-driven page and navigation manifest consumed by @conduction/nextcloud-vue. Introduces a uniform widgets[] array on every page type with a per-slot grid coordinate system, a typed actions[] discriminator, and the required $schema field for version detection. v1 manifests continue to validate against app-manifest.schema.json (unchanged).",
-	"version": "2.42.0",
+	"version": "2.45.0",
 	"type": "object",
 	"required": ["$schema", "version"],
 	"allOf": [
@@ -97,6 +97,8 @@
 							"suggestFrom": { "type": "string", "description": "choice: the configKey of an earlier choice this step pre-fills a suggestion from. When that value is set and the user has not yet picked here, the option matching suggestMap[parentValue] is auto-selected (still user-overridable)." },
 							"suggestMap": { "type": "object", "description": "choice: map of suggestFrom value → suggested option value. Used to auto-suggest a default (e.g. RGS template suggested from organisation type).", "additionalProperties": { "type": "string" } },
 							"multiple": { "type": "boolean", "default": false, "description": "choice: allow multi-select." },
+							"loadAction": { "type": "string", "minLength": 1, "description": "choice with display cards: an actionId each option card loads itself with. Every card except the one whose value is `none` gets its own Load button, which POSTs { dataset: <value> } to /api/setup/action/{loadAction}, spins while it runs and shows the result on that card. A successful load also selects the card. With loadAction the separate run-action step that loaded the picked dataset is no longer needed; manifests that keep it still work." },
+							"requires": { "type": "array", "items": { "type": "string", "minLength": 1 }, "uniqueItems": true, "description": "App ids this step needs. When any of them is not installed and enabled, the wizard skips the step and the summary shows it as skipped, naming the missing apps. Do not combine with required: true; setup status would keep reporting the skipped step as unmet." },
 							"action": { "type": "string", "description": "run-action: actionId POSTed to /api/setup/action/{action}." },
 							"onDemand": { "type": "boolean", "default": false, "description": "run-action: the step runs only when the user clicks Run, never automatically, and is never outstanding work (it does not open the wizard or decide where a resumed wizard starts). The summary ticks it only when its action succeeded in the current session and shows it as not run otherwise, whatever the server reports. For destructive steps an app reports as done on purpose so they never auto-run, such as removing example data." },
 							"healthCheck": { "type": "boolean", "default": false, "description": "summary: render a health recap." },
@@ -1173,6 +1175,11 @@
 					"type": "string",
 					"description": "i18n translation key resolved by the consuming app's t() function at render time."
 				},
+				"translateLabel": {
+					"type": "boolean",
+					"default": true,
+					"description": "Whether CnAppNav runs `label` through the translate function. Set false for a user-authored title (e.g. a catalog name) that must render as written even when it equals a translation key such as 'Search'. Rendered as text either way, never as HTML."
+				},
 				"icon": {
 					"type": "string",
 					"description": "CSS class for the icon (e.g. 'icon-checkmark') or MDI component name."
@@ -1186,6 +1193,11 @@
 					"additionalProperties": { "type": ["string", "number", "boolean"] },
 					"description": "Optional vue-router query parameters merged into the target route link (e.g. a filter like { caseType: '<uuid>' }). Deep-links a nav entry to a pre-filtered index page."
 				},
+				"params": {
+					"type": "object",
+					"additionalProperties": { "type": ["string", "number"], "minLength": 1 },
+					"description": "Optional vue-router route params for a parameterised route (e.g. { catalogSlug: 'news' } for a page at '/catalogs/:catalogSlug'). String values must be non-empty. CnAppNav links to { name: route, params, query }. The entry is active only while every declared param equals the current route's param (compared as strings), so sibling entries on one route that differ in params are never marked together. On pages whose path sits below its page path with these params filled in, it is active too: by the same params check when those routes carry the same param names, otherwise as the one entry marked below its route."
+				},
 				"order": {
 					"type": "integer",
 					"description": "Display order in the menu. Items without an order render last."
@@ -1259,6 +1271,11 @@
 			"properties": {
 				"id": { "type": "string" },
 				"label": { "type": "string" },
+				"translateLabel": {
+					"type": "boolean",
+					"default": true,
+					"description": "Same as menuItem.translateLabel: false renders `label` as written instead of translating it."
+				},
 				"icon": { "type": "string" },
 				"route": { "type": "string" },
 				"query": {
@@ -1266,6 +1283,11 @@
 					"additionalProperties": { "type": ["string", "number", "boolean"] },
 					"description": "Optional vue-router query parameters merged into the target route link (e.g. a filter like { caseType: '<uuid>' }). Deep-links a nav entry to a pre-filtered index page."
 				},
+				"params": {
+					"type": "object",
+					"additionalProperties": { "type": ["string", "number"], "minLength": 1 },
+					"description": "Optional vue-router route params for a parameterised route; string values must be non-empty. Same contract as menuItem.params: part of the link, and the entry is active only while every declared param equals the current route's param."
+				},
 				"order": { "type": "integer" },
 				"permission": { "type": "string" },
 				"section": {

package/src/store/useObjectStore.js

@@ -5,6 +5,7 @@ import { genericError, networkError, parseResponseError } from '../utils/errors.
 import { normalizeFacets } from '../utils/facets.js'
 import { buildHeaders, buildQueryString, capitalize, prefixUrl } from '../utils/headers.js'
 import { extractId } from '../utils/id.js'
+import { dispatchObjectCreated } from '../utils/walkthroughSignals.js'
 import { mergePluginActions, mergePluginGetters, mergePluginState } from './pluginMerge.js'
 import { liveUpdatesPlugin } from './plugins/liveUpdates.js'
 
@@ -830,6 +831,13 @@ const baseActions = {
 				[type]: { ...(this.objects[type] || {}), [savedId]: data },
 			}
 
+			// Every create through the store lets an `advanceOn:
+			// object-created` walkthrough step advance, whichever form made it.
+			if (!isUpdate) {
+				const config = this.objectTypeRegistry[type] || {}
+				dispatchObjectCreated({ register: config.registerSlug || config.register, schema: config.schemaSlug || config.schema, object: data })
+			}
+
 			return data
 		} catch (error) {
 			this.errors = {