@conduction/nextcloud-vue 2.62.0 → 2.64.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

@@ -8,6 +8,12 @@
 	position: relative;
 }
 
+/* The breadcrumb line above the header (`config.breadcrumb`). */
+.cn-detail-page__breadcrumbs {
+	margin-bottom: calc(2 * var(--default-grid-baseline));
+	color: var(--color-text-maxcontrast);
+}
+
 /* Header */
 .cn-detail-page__header {
 	display: flex;
@@ -106,6 +112,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));
@@ -156,7 +181,7 @@
 
 .cn-detail-page__stats-table thead th {
 	padding: calc(1.5 * var(--default-grid-baseline)) calc(2 * var(--default-grid-baseline));
-	text-align: left;
+	text-align: start;
 	font-weight: 600;
 	font-size: 0.9em;
 	color: var(--color-text-maxcontrast);
@@ -181,7 +206,7 @@
 }
 
 .cn-detail-page__stats-cell--indented {
-	padding-left: calc(5 * var(--default-grid-baseline)) !important;
+	padding-inline-start: calc(5 * var(--default-grid-baseline)) !important;
 }
 
 .cn-detail-page__stats-cell--center {
@@ -189,7 +214,7 @@
 }
 
 .cn-detail-page__stats-cell--right {
-	text-align: right;
+	text-align: end;
 }
 
 /* Body & content */
@@ -323,7 +348,7 @@
 
 .cn-detail-page__sidebar-toggle {
 	position: fixed;
-	right: calc(5 * var(--default-grid-baseline));
+	inset-inline-end: calc(5 * var(--default-grid-baseline));
 	top: 80px;
 	z-index: 10;
 }

package/src/css/kpi-card.css

@@ -133,7 +133,7 @@
 	padding: var(--cn-kpi-padding-flat, 8px);
 	box-sizing: border-box;
 	overflow: hidden;
-	text-align: left;
+	text-align: start;
 	text-decoration: none;
 	color: inherit;
 	background: transparent;
@@ -248,6 +248,29 @@
 	white-space: nowrap;
 }
 
+/* A caption coloured by a rule (`captionVariant` / `overrides[].captionVariant`):
+   "1 due today" in the error colour. Foreground tokens, which stay readable in
+   dark mode. */
+.cn-kpi-card__label--primary {
+	color: var(--color-primary-element);
+	font-weight: 600;
+}
+
+.cn-kpi-card__label--success {
+	color: var(--color-text-success, var(--color-success-text));
+	font-weight: 600;
+}
+
+.cn-kpi-card__label--warning {
+	color: var(--color-element-warning, var(--color-warning-text));
+	font-weight: 600;
+}
+
+.cn-kpi-card__label--error {
+	color: var(--color-text-error, var(--color-error-text));
+	font-weight: 600;
+}
+
 /* Semantic variants. Each re-points the ONE accent token, so the icon tint
    and the number move together by construction — there is no second place to
    forget. The inline KPI below shares the same modifiers for the same reason:

package/src/css/table.css

@@ -155,7 +155,7 @@
 .cn-data-table th,
 .cn-data-table td {
 	padding: calc(3 * var(--default-grid-baseline));
-	text-align: left;
+	text-align: start;
 	border-bottom: 1px solid var(--color-border);
 	vertical-align: middle;
 	max-width: var(--cn-table-cell-max-width, 22rem);
@@ -174,6 +174,18 @@
 	white-space: normal;
 }
 
+/* The secondary line of a cell (`columns[].secondary`): muted, smaller, on its
+   own line under the value. Theme hooks: --cn-table-secondary-size and
+   --cn-table-secondary-color. */
+.cn-data-table .cn-table-cell__secondary {
+	display: block;
+	color: var(--cn-table-secondary-color, var(--color-text-maxcontrast));
+	font-size: var(--cn-table-secondary-size, 0.9em);
+	line-height: 1.35;
+	overflow: hidden;
+	text-overflow: ellipsis;
+}
+
 /* Back to wrapping, for a column holding prose rather than a label:
    `columns: [{ key: 'description', cellClass: 'cn-cell--wrap' }]`. */
 .cn-data-table th.cn-cell--wrap,
@@ -235,7 +247,7 @@
 }
 
 .cn-data-table td.cn-cell--end {
-	text-align: right;
+	text-align: end;
 	white-space: nowrap;
 }
 
@@ -273,7 +285,7 @@
 }
 
 .cn-table-sort-indicator {
-	margin-left: var(--default-grid-baseline);
+	margin-inline-start: var(--default-grid-baseline);
 	opacity: 0.6;
 }
 
@@ -295,6 +307,87 @@
 	outline-offset: -2px;
 }
 
+/* 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;
@@ -302,7 +395,7 @@
 	justify-content: center;
 	min-width: 14px;
 	height: 14px;
-	margin-left: 2px;
+	margin-inline-start: 2px;
 	padding: 0 3px;
 	border-radius: 7px;
 	background-color: var(--color-primary-element);
@@ -367,7 +460,7 @@
 
 .cn-table-col--icon {
 	width: 40px;
-	padding-right: 0;
+	padding-inline-end: 0;
 	text-align: center;
 	color: var(--color-text-maxcontrast);
 }
@@ -430,7 +523,7 @@
 
 .viewTable { width: 100%; border-collapse: collapse; background-color: var(--color-main-background); }
 
-.viewTable th, .viewTable td { padding: calc(3 * var(--default-grid-baseline)); text-align: left; border-bottom: 1px solid var(--color-border); vertical-align: middle; }
+.viewTable th, .viewTable td { padding: calc(3 * var(--default-grid-baseline)); text-align: start; border-bottom: 1px solid var(--color-border); vertical-align: middle; }
 
 .viewTable th { background: var(--color-background-hover); font-weight: 500; color: var(--color-text-maxcontrast); background-color: var(--color-background-dark); }
 

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,