@conduction/nextcloud-vue 2.68.0 → 2.70.0

package/src/mixins/pageViews.js

@@ -18,11 +18,19 @@
  * `layout` with its own grid, so a view looks exactly like the page's own
  * grid.
  *
+ * With `userLayout` on, a user arranges each view's grid for themselves, as
+ * they arrange the dashboard's own grid. The arrangement is stored per view,
+ * per page and per user, through the same user-preference record the
+ * dashboard uses (the server, mirrored in the browser). The manifest stays
+ * the base: it decides which widgets a view has, the user decides where they
+ * sit, and a reset returns the view to the manifest.
+ *
  * @mixin pageViews
  * @spec openspec/changes/view-switch-containers/specs/view-switch-containers/spec.md#requirement-a-page-declares-views-that-each-hold-a-widget-grid
  */
 import { translate as t } from '@nextcloud/l10n'
 import { readUserPreference, USER_PREFERENCE_STORAGE_PREFIX, writeUserPreference } from '../composables/useUserPreferences.js'
+import { dashboardLayoutKey, LAYOUT_GEOMETRY_FIELDS, mergeUserLayout, resolveUserLayoutApi } from '../store/plugins/dashboardLayouts.js'
 
 /** The query parameter that carries the chosen view. */
 export const PAGE_VIEW_QUERY_KEY = 'view'
@@ -30,18 +38,32 @@ export const PAGE_VIEW_QUERY_KEY = 'view'
 /** Prefix of the user-preference key; the page id follows it. */
 export const PAGE_VIEW_PREFERENCE_PREFIX = 'cn_page_view:'
 
+/**
+ * The page id one view's user layout is stored under: the page's own id,
+ * then `.view.`, then the view id. Spelled once, because a read and a write
+ * that disagree about the key read as an arrangement that never persists.
+ *
+ * @param {string} pageKey The page's id.
+ * @param {string} viewId The view id.
+ * @return {string} The page id handed to the layout store.
+ * @spec openspec/changes/page-view-user-layouts/specs/view-switch-containers/spec.md#requirement-a-user-arranges-each-view-for-themselves
+ */
+export function pageViewLayoutId(pageKey, viewId) {
+	return `${String(pageKey || 'page')}.view.${String(viewId)}`
+}
+
 let regionSeq = 0
 
 /**
- * Read the browser mirror of a user preference synchronously, so the stored
- * view is on screen from the first frame. Errors read as nothing stored.
+ * Read the browser mirror of a user preference synchronously, so a stored
+ * value is on screen from the first frame. Errors read as nothing stored.
  *
  * @param {string} appId The app id.
  * @param {string} key The preference key.
- * @return {string|null} The stored id, or null.
- * @spec openspec/changes/view-switch-containers/specs/view-switch-containers/spec.md#requirement-the-chosen-view-is-linkable-and-remembered
+ * @return {object|string|number|boolean|Array|null} The stored value, or null.
+ * @spec openspec/changes/page-view-user-layouts/specs/view-switch-containers/spec.md#requirement-a-user-arranges-each-view-for-themselves
  */
-function readStoredViewMirror(appId, key) {
+function readPreferenceMirror(appId, key) {
 	try {
 		if (typeof localStorage === 'undefined') {
 			return null
@@ -50,19 +72,45 @@ function readStoredViewMirror(appId, key) {
 		if (raw === null || raw === undefined) {
 			return null
 		}
-		const value = JSON.parse(raw)
-		return typeof value === 'string' && value !== '' ? value : null
+		return JSON.parse(raw)
 	} catch {
 		return null
 	}
 }
 
+/**
+ * Read the browser mirror of the stored view synchronously, so the stored
+ * view is on screen from the first frame.
+ *
+ * @param {string} appId The app id.
+ * @param {string} key The preference key.
+ * @return {string|null} The stored id, or null.
+ * @spec openspec/changes/view-switch-containers/specs/view-switch-containers/spec.md#requirement-the-chosen-view-is-linkable-and-remembered
+ */
+function readStoredViewMirror(appId, key) {
+	const value = readPreferenceMirror(appId, key)
+	return typeof value === 'string' && value !== '' ? value : null
+}
+
+/**
+ * Whether a stored layout record holds an arrangement.
+ *
+ * @param {object|Array<object>|null} record The record, or its items.
+ * @return {boolean}
+ */
+function holdsArrangement(record) {
+	const items = Array.isArray(record) ? record : (record && Array.isArray(record.items) ? record.items : [])
+	return items.length > 0
+}
+
 export const pageViews = {
 	inject: {
 		/** The host app id, provided by CnAppRoot; keys the stored view. */
 		cnPageViewsAppId: { from: 'cnAppId', default: '' },
 	},
 
+	emits: ['view-layout-change', 'view-layout-reset'],
+
 	props: {
 		/**
 		 * Views of this page, each its own widget grid behind one segmented
@@ -110,6 +158,17 @@ export const pageViews = {
 			viewChosen: false,
 			/** Id of the view region, the target of the options' `aria-controls`. */
 			viewRegionId: `cn-page-view-region-${regionSeq}`,
+			/**
+			 * This user's arrangement of each view, by view id, when the page
+			 * keeps a user layout. A separate copy, never the view's `layout`:
+			 * that array is the manifest, and writing a user's drag into it
+			 * would rearrange the view for everybody.
+			 *
+			 * @type {Record<string, Array<object>>}
+			 */
+			viewUserLayouts: {},
+			/** The views whose arrangement changed since the last save, by id. */
+			viewUserLayoutsDirty: {},
 		}
 	},
 
@@ -207,6 +266,32 @@ export const pageViews = {
 			return this.normalizedViews.find((view) => view.id === this.activeViewId) || null
 		},
 
+		/**
+		 * Whether a user arranges the views for themselves (`userLayout`).
+		 *
+		 * @return {boolean}
+		 * @spec openspec/changes/page-view-user-layouts/specs/view-switch-containers/spec.md#requirement-a-user-arranges-each-view-for-themselves
+		 */
+		viewUserLayoutOn() {
+			return this.userLayout === true && this.hasViews
+		},
+
+		/**
+		 * The chosen view's layout: this user's arrangement when they have
+		 * one, the manifest's otherwise.
+		 *
+		 * @return {Array<object>}
+		 * @spec openspec/changes/page-view-user-layouts/specs/view-switch-containers/spec.md#requirement-a-user-arranges-each-view-for-themselves
+		 */
+		activeViewLayout() {
+			const view = this.activeView
+			if (!view) {
+				return []
+			}
+			const arranged = this.viewUserLayoutOn ? this.viewUserLayouts[view.id] : null
+			return Array.isArray(arranged) ? arranged : view.layout
+		},
+
 		/**
 		 * The switch's options, for CnSegmentedControl.
 		 *
@@ -288,8 +373,21 @@ export const pageViews = {
 		},
 	},
 
+	watch: {
+		/**
+		 * Read the user's arrangement of a view the first time it is shown.
+		 *
+		 * @param {string|null} id The chosen view id.
+		 * @return {void}
+		 */
+		activeViewId(id) {
+			this.loadViewUserLayout(id)
+		},
+	},
+
 	created() {
 		this.loadStoredView()
+		this.loadViewUserLayout(this.activeViewId)
 	},
 
 	methods: {
@@ -361,18 +459,187 @@ export const pageViews = {
 		},
 
 		/**
-		 * Write a drag or resize in the chosen view's grid back onto its
-		 * layout items in place, as the page does for its own layout, so the
-		 * in-app manifest editor sees it.
+		 * The page id a view's arrangement is stored under.
+		 *
+		 * @param {string} viewId The view id.
+		 * @return {string}
+		 * @spec openspec/changes/page-view-user-layouts/specs/view-switch-containers/spec.md#requirement-a-user-arranges-each-view-for-themselves
+		 */
+		viewLayoutPageId(viewId) {
+			const pageKey = this.viewPreferenceKey.slice(PAGE_VIEW_PREFERENCE_PREFIX.length)
+			return pageViewLayoutId(pageKey, viewId)
+		},
+
+		/**
+		 * The layout store calls: the page's own (`userLayoutApi`, so an
+		 * injected `userLayoutStore` covers the views too), else the user
+		 * preferences.
+		 *
+		 * @return {{load: (appId: string, pageId: string) => Promise<object|null>, save: (appId: string, pageId: string, layout: Array<object>) => Promise<boolean>, reset: (appId: string, pageId: string) => Promise<boolean>}}
+		 */
+		viewLayoutApi() {
+			if (typeof this.userLayoutApi === 'function') {
+				return this.userLayoutApi()
+			}
+			return resolveUserLayoutApi(null)
+		},
+
+		/**
+		 * Read this user's arrangement of one view, once: the browser mirror
+		 * at once, then the server, which wins unless the user already moved
+		 * something in that view. A page without `userLayout` reads nothing.
+		 *
+		 * @param {string|null} viewId The view id.
+		 * @return {Promise<void>}
+		 * @spec openspec/changes/page-view-user-layouts/specs/view-switch-containers/spec.md#requirement-a-user-arranges-each-view-for-themselves
+		 */
+		async loadViewUserLayout(viewId) {
+			if (!this.viewUserLayoutOn || viewId === null || viewId === undefined) {
+				return
+			}
+			const view = this.normalizedViews.find((candidate) => candidate.id === String(viewId))
+			if (!view || Array.isArray(this.viewUserLayouts[view.id])) {
+				return
+			}
+			const appId = this.viewPreferenceAppId
+			const pageId = this.viewLayoutPageId(view.id)
+			const mirror = readPreferenceMirror(appId, dashboardLayoutKey(pageId))
+			this.viewUserLayouts = { ...this.viewUserLayouts, [view.id]: mergeUserLayout(view.layout, holdsArrangement(mirror) ? mirror : null) }
+			if (!appId) {
+				return
+			}
+			let record
+			try {
+				record = await this.viewLayoutApi().load(appId, pageId)
+			} catch {
+				// The mirror, or the manifest, stands: a store that cannot
+				// answer leaves the view as the user last saw it.
+				return
+			}
+			if (this.viewUserLayoutsDirty[view.id] || !holdsArrangement(record)) {
+				return
+			}
+			this.viewUserLayouts = { ...this.viewUserLayouts, [view.id]: mergeUserLayout(view.layout, record) }
+		},
+
+		/**
+		 * Store the arrangement of every view the user changed since the last
+		 * save. The page calls it when the user leaves edit mode, so a drag
+		 * is not a write per pixel gesture.
+		 *
+		 * @return {Promise<void>}
+		 * @spec openspec/changes/page-view-user-layouts/specs/view-switch-containers/spec.md#requirement-a-user-arranges-each-view-for-themselves
+		 */
+		async saveViewUserLayouts() {
+			if (!this.viewUserLayoutOn) {
+				return
+			}
+			const ids = Object.keys(this.viewUserLayoutsDirty).filter((id) => this.viewUserLayoutsDirty[id])
+			this.viewUserLayoutsDirty = {}
+			const appId = this.viewPreferenceAppId
+			for (const id of ids) {
+				const pageId = this.viewLayoutPageId(id)
+				const items = this.viewUserLayouts[id] || []
+				try {
+					if (appId) {
+						await this.viewLayoutApi().save(appId, pageId, items)
+					} else {
+						// No app to address: keep it in this browser only, as
+						// the chosen view is kept.
+						await writeUserPreference('', dashboardLayoutKey(pageId), { items: items.map((item) => this.viewGeometry(item, true)) })
+					}
+				} catch {
+					// The arrangement stands for this session. A toast on a
+					// failed layout write is noise on an instance without the
+					// preference route.
+				}
+			}
+		},
+
+		/**
+		 * Drop this user's arrangement of one view and return it to the
+		 * manifest layout. Other views keep theirs.
+		 *
+		 * @param {string} [viewId] The view id; the chosen view when left out.
+		 * @return {Promise<void>}
+		 * @spec openspec/changes/page-view-user-layouts/specs/view-switch-containers/spec.md#requirement-resetting-a-view-restores-its-manifest-layout
+		 */
+		async resetViewUserLayout(viewId) {
+			const id = viewId === undefined || viewId === null ? this.activeViewId : String(viewId)
+			const view = this.normalizedViews.find((candidate) => candidate.id === id)
+			if (!this.viewUserLayoutOn || !view) {
+				return
+			}
+			const appId = this.viewPreferenceAppId
+			const pageId = this.viewLayoutPageId(view.id)
+			try {
+				if (appId) {
+					await this.viewLayoutApi().reset(appId, pageId)
+				} else {
+					await writeUserPreference('', dashboardLayoutKey(pageId), { items: [] })
+				}
+			} catch {
+				// The view returns to the manifest either way, which is what
+				// the user asked for.
+			}
+			const dirty = { ...this.viewUserLayoutsDirty }
+			delete dirty[view.id]
+			this.viewUserLayoutsDirty = dirty
+			this.viewUserLayouts = { ...this.viewUserLayouts, [view.id]: mergeUserLayout(view.layout, null) }
+			/**
+			 * Emitted when the user drops their arrangement of a view and it
+			 * returns to the manifest layout.
+			 *
+			 * @event view-layout-reset
+			 * @type {{view: string}}
+			 */
+			this.$emit('view-layout-reset', { view: view.id })
+		},
+
+		/**
+		 * The geometry fields of one layout item, and nothing else.
+		 *
+		 * @param {object} item A layout item, or a grid update.
+		 * @param {boolean} [withWidgetId] Whether to keep the widget id too.
+		 * @return {object}
+		 */
+		viewGeometry(item, withWidgetId = false) {
+			const geometry = withWidgetId ? { widgetId: String(item?.widgetId ?? '') } : {}
+			for (const field of LAYOUT_GEOMETRY_FIELDS) {
+				if (item?.[field] !== undefined) {
+					geometry[field] = item[field]
+				}
+			}
+			return geometry
+		},
+
+		/**
+		 * A drag or resize in the chosen view's grid. With `userLayout` it
+		 * moves this user's copy of the view and marks it for saving; the
+		 * view's manifest `layout` is not touched. Without it the geometry is
+		 * written back onto the layout items in place, as the page does for
+		 * its own layout, so the in-app manifest editor sees it.
 		 *
 		 * @param {Array<object>} updated The layout from the grid.
 		 * @return {void}
+		 * @spec openspec/changes/page-view-user-layouts/specs/view-switch-containers/spec.md#requirement-a-user-arranges-each-view-for-themselves
 		 */
 		onViewLayoutChange(updated) {
 			const view = this.activeView
 			if (!view || !Array.isArray(updated)) {
 				return
 			}
+			if (this.viewUserLayoutOn) {
+				const current = Array.isArray(this.viewUserLayouts[view.id]) ? this.viewUserLayouts[view.id] : mergeUserLayout(view.layout, null)
+				const arranged = current.map((item) => {
+					const u = updated.find((candidate) => String(candidate.id) === String(item.id))
+					return u ? { ...item, ...this.viewGeometry(u) } : item
+				})
+				this.viewUserLayouts = { ...this.viewUserLayouts, [view.id]: arranged }
+				this.viewUserLayoutsDirty = { ...this.viewUserLayoutsDirty, [view.id]: true }
+				this.$emit('view-layout-change', { view: view.id, layout: arranged })
+				return
+			}
 			for (const u of updated) {
 				const item = view.layout.find((l) => String(l.id) === String(u.id))
 				if (!item) {

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.50.0",
+	"version": "2.52.0",
 	"type": "object",
 	"required": ["$schema", "version"],
 	"allOf": [
@@ -1569,6 +1569,11 @@
 						"href": { "type": "string" }
 					}
 				},
+				"showButtons": {
+					"type": "boolean",
+					"default": true,
+					"description": "`false` drops the widget's footer links (its definition's `buttons`, e.g. a calendar's \"More events\"), for a placement whose card says enough without them (zuiddrecht-pixel-gaps-3)."
+				},
 				"sizeToContent": {
 					"type": ["boolean", "integer"],
 					"minimum": 1,
@@ -2195,7 +2200,8 @@
 												}
 											},
 											"emptyText": { "type": "string", "description": "Text of a day without items." },
-											"weekOffset": { "type": "integer", "description": "Whole weeks from the current one (1 = next week)." }
+											"weekOffset": { "type": "integer", "description": "Whole weeks from the current one (1 = next week)." },
+											"inset": { "type": "boolean", "default": false, "description": "Draw the strip inside the board's inset (16px above, 24px at the sides, 22px below) instead of from card edge to card edge (zuiddrecht-pixel-gaps-3). Theme hook --cn-widget-board-inset." }
 										}
 									}
 								}
@@ -2246,7 +2252,8 @@
 											},
 											"order": { "type": "array", "items": { "type": "string" }, "description": "Group keys in the order they render. Unlisted groups follow; a listed key without records shows 0." },
 											"labels": { "type": "object", "additionalProperties": { "type": "string" }, "description": "The label of a group key." },
-											"emptyText": { "type": "string", "description": "Shown when the total is 0." }
+											"emptyText": { "type": "string", "description": "Shown when the total is 0." },
+											"inset": { "type": "boolean", "default": false, "description": "Draw the bar and legend inside the board's inset (16px above, 24px at the sides, 22px below) instead of from card edge to card edge (zuiddrecht-pixel-gaps-3). Theme hook --cn-widget-board-inset." }
 										}
 									}
 								}
@@ -2903,7 +2910,7 @@
 			"type": "object",
 			"required": ["register", "schema"],
 			"additionalProperties": false,
-			"description": "One KPI entry inside a multi-entry stats-block widget (CnStatsBlockWidget `entries[]`). Carries the same source contract as a type:'stat' widget: register + schema + metric + token-resolved filter (@today / @me / @workspace.* and ?-optional clauses), plus per-entry presentation (title, variant, countLabel), an optional route deep link, and hideWhenZero.",
+			"description": "One KPI entry inside a multi-entry stats-block widget (CnStatsBlockWidget `entries[]`). Carries the same source contract as a type:'stat' widget: register + schema + metric + token-resolved filter (@today / @me / @workspace.* and ?-optional clauses), plus per-entry presentation (title, variant, countLabel, format), an optional route deep link, and hideWhenZero. A money value names its currency with currencyField (the page object's field) or currency.",
 			"properties": {
 				"title": {
 					"type": "string",
@@ -2952,6 +2959,32 @@
 					"type": "boolean",
 					"default": false,
 					"description": "When true, the entry is omitted from the card when its resolved count is 0."
+				},
+				"format": {
+					"description": "How the value is shown, as a type:'stat' widget's content.format: a style name, or { style, currency, currencyField, decimals, prefix, suffix }. Omitted, the plain localized count is shown. Numbers are formatted with Intl in the user's locale.",
+					"oneOf": [
+						{ "type": "string", "enum": ["number", "currency", "percent", "decimal", "duration-hours"] },
+						{
+							"type": "object",
+							"additionalProperties": false,
+							"properties": {
+								"style": { "type": "string", "enum": ["number", "currency", "percent", "decimal", "duration-hours"] },
+								"currency": { "type": "string", "description": "ISO-4217 code, or a token such as @config.currency or @object.currency." },
+								"currencyField": { "type": "string", "description": "Field of the detail page's object that holds the currency (dot-path allowed)." },
+								"decimals": { "type": "integer", "minimum": 0, "description": "Fraction digits." },
+								"prefix": { "type": "string" },
+								"suffix": { "type": "string" }
+							}
+						}
+					]
+				},
+				"currency": {
+					"type": "string",
+					"description": "Shorthand for format.currency: an ISO-4217 code, or a token such as @config.currency. Implies format 'currency'."
+				},
+				"currencyField": {
+					"type": "string",
+					"description": "Shorthand for format.currencyField: the field of the detail page's object that holds the currency, e.g. 'currency'. Implies format 'currency'. The currency is taken from the object, then currency, then the app's reporting currency (config currency), then EUR."
 				}
 			}
 		},
@@ -3655,7 +3688,12 @@
 						"showWidgetActions": {
 							"type": "boolean",
 							"default": true,
-							"description": "type='dashboard': `false` drops the overflow Actions menu from every widget that does not set `showActions` itself, for a dashboard whose widget headers carry a header link and nothing else (zuiddrecht-pixel-gaps-2). Maps to CnDashboardPage `showWidgetActions`."
+							"description": "type='dashboard' and type='detail': `false` drops the overflow Actions menu from every widget that does not set `showActions` itself, for a dashboard whose widget headers carry a header link and nothing else (zuiddrecht-pixel-gaps-2), or a record page whose data cards carry none (zuiddrecht-pixel-gaps-3; a card with an Add action keeps it). Maps to CnDashboardPage / CnDetailPage `showWidgetActions`."
+						},
+						"gridFloat": {
+							"type": "boolean",
+							"default": true,
+							"description": "type='dashboard': `false` packs widgets upward (GridStack `float: false`), so a size-to-content widget that shrinks closes the gap under it instead of leaving an empty band (zuiddrecht-pixel-gaps-3). Maps to CnDashboardPage `gridFloat`."
 						},
 						"showTitle": {
 							"type": "boolean",
@@ -3666,6 +3704,33 @@
 							"type": "string",
 							"description": "type='index': an i18n key for the description line with `{total}` replaced by the collection's total, e.g. \"{total} open cases\" (zuiddrecht-pixel-gaps). Shown in place of `description` once a total is known. Maps to CnIndexPage `countSubtitle`."
 						},
+						"showTitleIcon": {
+							"type": "boolean",
+							"default": true,
+							"description": "type='index': `false` drops the icon before the page title, for a title that stands alone as the board draws it (zuiddrecht-pixel-gaps-3). Maps to CnIndexPage `showTitleIcon`."
+						},
+						"showCount": {
+							"type": "boolean",
+							"default": true,
+							"description": "type='index': `false` drops the actions bar's \"Showing 20 of 258\" line, for a page whose title line already gives the total through `countSubtitle` (zuiddrecht-pixel-gaps-3). Maps to CnIndexPage `showCount`."
+						},
+						"headerButtons": {
+							"type": "array",
+							"description": "type='index': buttons beside the page title, as the board's \"Export\" and \"New case\" (zuiddrecht-pixel-gaps-3). `action` is `add` (the Add flow; the label defaults to the Add label), `export` (the export leaf in `format`, else the export dialog), `import`, `refresh`, or the id of a `headerActions` entry. Shown only with `showTitle`; when they show, the actions bar drops its Views and Actions menus, and the Add button and Export menu when a button takes their action. Maps to CnIndexPage `headerButtons`.",
+							"items": {
+								"type": "object",
+								"additionalProperties": false,
+								"required": ["action"],
+								"properties": {
+									"id": { "type": "string", "minLength": 1 },
+									"label": { "type": "string", "minLength": 1, "description": "i18n key; optional for `add`." },
+									"action": { "type": "string", "minLength": 1 },
+									"variant": { "type": "string", "enum": ["primary", "secondary"], "default": "secondary" },
+									"icon": { "type": "string", "minLength": 1, "description": "MDI icon name." },
+									"format": { "type": "string", "enum": ["csv", "excel"], "default": "csv", "description": "For `export`." }
+								}
+							}
+						},
 						"showTypeEyebrow": {
 							"type": "boolean",
 							"default": true,
@@ -3681,7 +3746,9 @@
 								"route": { "type": "string" },
 								"params": { "type": "object", "additionalProperties": true },
 								"href": { "type": "string" },
-								"icon": { "type": "string", "minLength": 1, "description": "Optional MDI icon name (e.g. `Home`) drawn as the first crumb instead of the label, which then becomes its accessible name (zuiddrecht-pixel-gaps-2). Without it the label shows as text." }
+								"icon": { "type": "string", "minLength": 1, "description": "Optional MDI icon name (e.g. `Home`) drawn as the first crumb instead of the label, which then becomes its accessible name (zuiddrecht-pixel-gaps-2). Without it the label shows as text." },
+								"currentField": { "type": "string", "minLength": 1, "description": "A field of the record (dotted path, e.g. `identifier`) whose value is the current crumb instead of the display name; an empty value falls back to the display name (zuiddrecht-pixel-gaps-3)." },
+								"separator": { "type": "string", "minLength": 1, "maxLength": 3, "description": "Text drawn between the crumbs (e.g. `/`) instead of the chevron (zuiddrecht-pixel-gaps-3)." }
 							}
 						},
 						"headerCard": {

package/src/store/plugins/dashboardLayouts.js

@@ -156,6 +156,40 @@ export function mergeUserLayout(manifestLayout, record) {
 	return [...arranged, ...appended]
 }
 
+/**
+ * The three calls a user layout needs: from a store that carries the
+ * `dashboardLayoutsPlugin` actions, or straight over user preferences.
+ *
+ * Both paths write through `writeUserPreference`, so a record lands on the
+ * server and in the browser mirror whichever one a page uses. CnDashboardPage
+ * reads its own grid's record through this, and the page views mixin reads
+ * each view's record through it, so the two cannot disagree about where a
+ * user's arrangement lives.
+ *
+ * @param {object|null} [store] A store with `loadDashboardLayout`, `saveDashboardLayout` and `resetDashboardLayout`, or null.
+ * @return {{ load: (appId: string, pageId: string) => Promise<object|null>, save: (appId: string, pageId: string, layout: Array<object>) => Promise<boolean>, reset: (appId: string, pageId: string) => Promise<boolean> }} The api.
+ * @spec openspec/changes/page-view-user-layouts/specs/view-switch-containers/spec.md#requirement-a-user-arranges-each-view-for-themselves
+ */
+export function resolveUserLayoutApi(store = null) {
+	if (store && typeof store.loadDashboardLayout === 'function') {
+		return {
+			load: (...a) => store.loadDashboardLayout(...a),
+			save: (...a) => store.saveDashboardLayout(...a),
+			reset: (...a) => store.resetDashboardLayout(...a),
+		}
+	}
+
+	return {
+		load: (appId, pageId) => readUserPreference(appId, dashboardLayoutKey(pageId), null),
+		save: (appId, pageId, layout) => writeUserPreference(
+			appId,
+			dashboardLayoutKey(pageId),
+			{ items: (Array.isArray(layout) ? layout : []).map(geometryOf).filter((entry) => entry.widgetId !== '') },
+		),
+		reset: (appId, pageId) => writeUserPreference(appId, dashboardLayoutKey(pageId), { items: [] }),
+	}
+}
+
 /**
  * Plugin definition.
  *

package/src/utils/capabilityComparison.js

@@ -22,6 +22,34 @@
  * @module utils/capabilityComparison
  */
 
+/*
+ * `process.env.NODE_ENV` is substituted by every consuming app's bundler at
+ * build time (webpack's DefinePlugin, rollup's replace); see NcSelectTags.js.
+ */
+/* global process */
+
+let deprecationWarned = false
+
+/**
+ * Warn once per page load, in a development build only, that the in-app
+ * capability comparison is deprecated. Called by CnFeaturesAndRoadmapPage,
+ * CnFeaturesAndRoadmapView and CnCapabilityTable when a comparison is
+ * actually given, so an app that passes none hears nothing.
+ *
+ * @spec openspec/changes/zuiddrecht-pixel-gaps-3/specs/zuiddrecht-pixel-gaps-3/spec.md#requirement-the-in-app-capability-comparison-is-deprecated
+ * @param {string} source What carried the comparison, for the message.
+ * @return {boolean} True when this call printed the warning.
+ */
+export function warnCapabilityComparisonDeprecated(source) {
+	if (deprecationWarned || process.env.NODE_ENV === 'production') {
+		return false
+	}
+	deprecationWarned = true
+	// eslint-disable-next-line no-console -- a deliberate deprecation notice to the developer integrating the component
+	console.warn(`[nextcloud-vue] ${source} is deprecated: the in-app capability comparison (capabilityComparison, the features_roadmap_capabilities initial state, CnCapabilityTable) will be removed in a future major version. Publish the comparison on the app's docs site and link to it instead.`)
+	return true
+}
+
 /**
  * Ratings in the order they are counted and rendered.
  *