@conduction/nextcloud-vue 2.66.0 → 2.68.0

package/src/composables/useDependencyCheck.js

@@ -3,6 +3,7 @@
  * SPDX-License-Identifier: EUPL-1.2
  */
 
+import { loadState } from '@nextcloud/initial-state'
 import { useAppStatus } from './useAppStatus.js'
 
 /**
@@ -59,3 +60,45 @@ export function checkDependencies(entries, serverStatuses = {}) {
 export function isDependencyResolved(row) {
 	return !!row && row.installed === true && row.enabled === true
 }
+
+/**
+ * Read the `dependency_statuses` initial state an app may inject from PHP.
+ *
+ * Keyed by app id: `{ installed, enabled }`. Returns `{}` when the app injects
+ * none or the state cannot be read, so callers fall back to `useAppStatus`.
+ *
+ * @param {string} appId The app whose initial state to read.
+ * @return {object} Server-reported statuses keyed by app id.
+ *
+ * @spec openspec/changes/optional-step-requires/specs/cn-setup-wizard/spec.md#requirement-a-step-whose-required-apps-are-absent-is-not-applicable
+ */
+export function readServerAppStatuses(appId) {
+	try {
+		const statuses = loadState(appId, 'dependency_statuses', {})
+		return (statuses && typeof statuses === 'object') ? statuses : {}
+	} catch {
+		return {}
+	}
+}
+
+/**
+ * The apps in a setup step's `requires` list that are not installed and
+ * enabled.
+ *
+ * This is the one resolution every setup surface uses: `CnSetupWizard` skips a
+ * step when it is non-empty, and `useSetupStatus` then counts that step as not
+ * applicable rather than unmet. Keeping both on one function is what stops the
+ * wizard and the status from disagreeing about the same step.
+ *
+ * @param {Array<string>} requires The step's `requires` app ids.
+ * @param {object} [serverStatuses] Server-reported statuses keyed by app id.
+ * @return {Array<{id: string, name: string, required: boolean, installed: boolean, enabled: boolean}>} The missing apps.
+ *
+ * @spec openspec/changes/optional-step-requires/specs/cn-setup-wizard/spec.md#requirement-a-step-whose-required-apps-are-absent-is-not-applicable
+ */
+export function missingRequiredApps(requires, serverStatuses = {}) {
+	if (!Array.isArray(requires) || requires.length === 0) {
+		return []
+	}
+	return checkDependencies(requires, serverStatuses).filter((row) => !isDependencyResolved(row))
+}

package/src/composables/useListView.js

@@ -94,6 +94,13 @@ export function useListView(objectTypeOrOptions, options) {
 	// field (a folder pane grouping by it, say) reads them here rather than
 	// deriving them from `objects`, which is only the current page.
 	const facets = computed(() => objectStore.facets[objectType] || {})
+	// Outcome of the latest `refresh()`: the store's error for it, or null once
+	// it succeeded or a later fetch stored new rows. The store keeps the previous
+	// rows on a failed fetch, so this is how a consumer tells stale rows from
+	// current ones.
+	const error = ref(null)
+	let refreshSeq = 0
+	let pendingRefreshes = 0
 
 	let searchTimeout = null
 
@@ -178,14 +185,48 @@ export function useListView(objectTypeOrOptions, options) {
 
 	/**
 	 * Fetch the collection using current state params and update sidebar facet data.
+	 * Only the most recently started refresh sets `error`, so an older response
+	 * settling late cannot override a newer one's outcome.
 	 *
 	 * @param {number} [page] Page to fetch
 	 * @return {Promise<void>}
 	 */
 	async function refresh(page = 1) {
-		await objectStore.fetchCollection(objectType, buildParams(page))
+		const seq = ++refreshSeq
+		// This call's own result. `errors[objectType]` is shared by every call
+		// for the type and is not cleared on success, so it cannot say which
+		// request failed; it is only the fallback for a store that ignores
+		// `options.outcome`.
+		const outcome = {}
+		pendingRefreshes++
+		try {
+			await objectStore.fetchCollection(objectType, buildParams(page), { outcome })
+		} catch (e) {
+			if (seq === refreshSeq) {
+				error.value = e
+			}
+			throw e
+		} finally {
+			pendingRefreshes--
+		}
+		if (seq === refreshSeq) {
+			error.value = ('error' in outcome) ? outcome.error : (objectStore.errors?.[objectType] || null)
+		}
 	}
 
+	// A fetch outside `refresh()` (e.g. the live-updates refetch) that stores
+	// new rows recovers the list from an earlier failure. Rows written while
+	// a refresh is pending are left to that refresh, which decides `error`.
+	watch(
+		() => objectStore.collections[objectType],
+		() => {
+			if (pendingRefreshes === 0) {
+				error.value = null
+			}
+		},
+		{ flush: 'sync' },
+	)
+
 	// ── Event handlers ───────────────────────────────────────────────────
 
 	/**
@@ -323,6 +364,7 @@ export function useListView(objectTypeOrOptions, options) {
 		loading,
 		pagination,
 		facets,
+		error,
 		// Local state
 		searchTerm,
 		sortKey,

package/src/composables/useSetupStatus.js

@@ -4,6 +4,7 @@
  */
 
 import { computed, ref } from 'vue'
+import { missingRequiredApps, readServerAppStatuses } from './useDependencyCheck.js'
 
 /**
  * Per-`appId` cache of setup-status results. The Vue refs are stored so all
@@ -27,6 +28,14 @@ const cache = new Map()
  * every non-admin user of an app with a `setup` block met a wizard they had no
  * permission to complete instead of the app itself.
  *
+ * A step that declares `requires: [appId, ...]` is **not applicable** while any
+ * of those apps is not installed and enabled: it is neither met nor unmet, so
+ * it never lands in `requiredUnmet` or `optionalUnmet`. `CnSetupWizard` skips
+ * such a step, and counting it as unmet kept the wizard reopening (optional
+ * step) or gating the app (required step) for a step it would never show. App
+ * status is resolved exactly as the wizard does it: the `dependency_statuses`
+ * initial state first, then `useAppStatus`.
+ *
  * @param {string} appId Nextcloud app id (e.g. `"procest"`).
  * @param {object} manifest The app manifest (reads `manifest.setup`).
  * @return {{
@@ -35,6 +44,7 @@ const cache = new Map()
  *   requiredUnmet: import('vue').ComputedRef<Array<object>>,
  *   optionalUnmet: import('vue').ComputedRef<Array<object>>,
  *   optionalUnmetReported: import('vue').ComputedRef<Array<object>>,
+ *   notApplicable: import('vue').ComputedRef<Array<object>>,
  *   completed: import('vue').ComputedRef<boolean>,
  *   enabled: boolean,
  *   loading: import('vue').Ref<boolean>,
@@ -45,6 +55,7 @@ const cache = new Map()
  *
  * @example
  * const { requiredUnmet, completed, loading } = useSetupStatus('procest', manifest)
+ * @spec openspec/changes/optional-step-requires/specs/cn-setup-wizard/spec.md#requirement-a-step-whose-required-apps-are-absent-is-not-applicable
  */
 export function useSetupStatus(appId, manifest) {
 	const setup = (manifest && manifest.setup) || {}
@@ -68,6 +79,9 @@ export function useSetupStatus(appId, manifest) {
 		cache.set(appId, entry)
 	}
 	const { status, loading, error, forbidden } = entry
+	// Same source the wizard's dependency gate reads. Initial state is fixed
+	// for the page lifetime, so one read per call is enough.
+	const serverAppStatuses = readServerAppStatuses(appId)
 
 	const steps = computed(() => stepDefs.map((s) => {
 		const bag = status.value.steps || {}
@@ -81,7 +95,12 @@ export function useSetupStatus(appId, manifest) {
 		// that act on an unmet step — CnAppRoot auto-opening the non-gating
 		// wizard — must act only on steps the server actually reported, or an
 		// unknowable step parks the wizard over the app for ever.
-		return { ...s, done: st.done === true, reported, detail: st.detail }
+		//
+		// `applicable` is false when the step `requires` an app that is not
+		// installed and enabled. The wizard skips such a step, so it can never
+		// be done here; it is not applicable rather than unmet.
+		const missingApps = missingRequiredApps(s.requires, serverAppStatuses).map((row) => row.id)
+		return { ...s, done: st.done === true, reported, detail: st.detail, applicable: missingApps.length === 0, missingApps }
 	}))
 	// Presentational step types carry no work, so the server never reports a
 	// `done` flag for them. Counting them as "unmet" made `optionalUnmet`
@@ -89,7 +108,9 @@ export function useSetupStatus(appId, manifest) {
 	// which kept CnAppRoot's non-gating setup wizard auto-opening over the
 	// app on every fresh browser profile no matter how complete setup was.
 	// Only actionable steps can be unmet.
-	const isActionable = (s) => s.type !== 'info' && s.type !== 'summary'
+	// A step whose required apps are absent is skipped by the wizard, so it
+	// is neither met nor unmet (see `applicable` above).
+	const isActionable = (s) => s.type !== 'info' && s.type !== 'summary' && s.applicable !== false
 	// `forbidden` empties BOTH lists, and that is what actually suppresses the
 	// wizard: CnAppRoot gates on `requiredUnmet.length > 0` (blocking) and on
 	// `requiredUnmet.length === 0 && optionalUnmet.length > 0` (auto-open) —
@@ -110,6 +131,8 @@ export function useSetupStatus(appId, manifest) {
 	// suppressing it is what left dossiq's `seed` step (and with it the app's
 	// only demo-data affordance) permanently unreachable.
 	const optionalUnmetReported = computed(() => optionalUnmet.value.filter((s) => s.reported === true))
+	// Steps the wizard skips because an app in their `requires` is absent.
+	const notApplicable = computed(() => steps.value.filter((s) => s.applicable === false))
 	const completed = computed(() => {
 		if (!enabled) {
 			return true
@@ -170,7 +193,7 @@ export function useSetupStatus(appId, manifest) {
 		refresh()
 	}
 
-	return { steps, status, requiredUnmet, optionalUnmet, optionalUnmetReported, completed, enabled, loading, error, forbidden, refresh }
+	return { steps, status, requiredUnmet, optionalUnmet, optionalUnmetReported, notApplicable, completed, enabled, loading, error, forbidden, refresh }
 }
 
 /**

package/src/css/actions-bar.css

@@ -35,6 +35,23 @@
 	color: var(--color-text-maxcontrast);
 }
 
+/* Beside the inline search (`showCountWithSearch`): the search field shrinks
+   first and the counter stays on one line. */
+.cn-actions-bar__count--beside-search {
+	flex-shrink: 0;
+	white-space: nowrap;
+}
+
+/* Taken out of the flex row so it adds no gap, but kept in the accessibility
+   tree so the live region exists before a total appears. */
+.cn-actions-bar__count--empty {
+	position: absolute;
+	width: 1px;
+	height: 1px;
+	overflow: hidden;
+	clip-path: inset(50%);
+}
+
 /* Inline search field */
 .cn-actions-bar__search {
 	position: relative;
@@ -294,8 +311,9 @@
 		display: contents;
 	}
 
-	/* #after-search filter buttons + the view toggle ride beside the
-	   search field (DOM order — search first via its own order). */
+	/* #after-search filter buttons, the beside-search counter and the view
+	   toggle ride beside the search field (DOM order — search first via its
+	   own order). */
 	.cn-actions-bar__info > * {
 		order: 1;
 	}

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.48.0",
+	"version": "2.50.0",
 	"type": "object",
 	"required": ["$schema", "version"],
 	"allOf": [
@@ -98,7 +98,7 @@
 							"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." },
+							"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. Setup status then counts the step as not applicable, neither met nor unmet, so it never reopens the wizard or gates the app. This holds for a required step too." },
 							"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." },
@@ -236,7 +236,7 @@
 				},
 				"settingsLabel": {
 					"type": "string",
-					"description": "Override label for the settings foldout's gear button. Defaults to 'Settings'."
+					"description": "Override label for the settings foldout's gear button. Defaults to 'Advanced'."
 				},
 				"card": {
 					"type": "object",
@@ -3458,14 +3458,30 @@
 						"actions": {
 							"type": "array",
 							"items": {
-								"type": "object",
-								"required": ["label"],
-								"additionalProperties": true,
-								"properties": {
-									"label": { "type": "string", "minLength": 1 }
-								}
+								"anyOf": [
+									{
+										"type": "object",
+										"required": ["label"],
+										"additionalProperties": true,
+										"properties": {
+											"label": { "type": "string", "minLength": 1 },
+											"id": { "type": "string", "not": { "pattern": "^builtin:" } },
+											"builtin": false
+										}
+									},
+									{
+										"type": "string",
+										"enum": ["builtin:view", "builtin:edit", "builtin:copy", "builtin:delete"]
+									}
+								]
 							},
-							"description": "Declarative actions on a page. Governed ONLY by \"an object carrying a non-empty label\", deliberately: this key is polymorphic by page type (index rows dispatch $defs/action; detail pages also carry type='lifecycle-transition' entries), so one closed grammar here would reject working manifests. A label is what every dialect needs — CnRowActions renders an entry from its label and icon, so an entry without one became a full-height, clickable, EMPTY row in the overflow menu. Two shapes hit this, both meaning \"show the built-in\": a bare string (\"edit\") and a key-only object ({\"key\": \"edit\"}). Built-ins are enabled with config.actionToggles / the show*Action keys, never by naming them here."
+							"allOf": [
+								{ "contains": { "const": "builtin:view" }, "minContains": 0, "maxContains": 1 },
+								{ "contains": { "const": "builtin:edit" }, "minContains": 0, "maxContains": 1 },
+								{ "contains": { "const": "builtin:copy" }, "minContains": 0, "maxContains": 1 },
+								{ "contains": { "const": "builtin:delete" }, "minContains": 0, "maxContains": 1 }
+							],
+							"description": "Declarative actions on a page. An object entry is governed ONLY by \"an object carrying a non-empty label\", deliberately: this key is polymorphic by page type (index rows dispatch $defs/action; detail pages also carry type='lifecycle-transition' entries), so one closed grammar here would reject working manifests. A label is what every dialect needs — CnRowActions renders an entry from its label and icon, so an entry without one became a full-height, clickable, EMPTY row in the overflow menu. An object is always an app action whatever its id: an id, when present, must be a string that does not start with 'builtin:', and the object may not set a 'builtin' key. On a type='index' page an entry may also be one of the placeholders \"builtin:view\", \"builtin:edit\", \"builtin:copy\" or \"builtin:delete\", each at most once, which puts that built-in row action at its position in the menu. A placeholder only places a built-in: config.actionToggles / the show*Action keys still decide whether it renders. Enabled built-ins the array does not place are appended after everything else in the order View, Edit, Copy, Delete. Any other string (a bare \"edit\", an unknown \"builtin:archive\") is refused, and placeholders are refused on every page type other than index."
 						},
 						"rowIndicators": {
 							"type": "array",
@@ -3732,6 +3748,10 @@
 									"type": "boolean",
 									"description": "Whether the built-in create / edit form dialog is enabled. Maps to CnIndexPage `showFormDialog`."
 								},
+								"showViewAction": {
+									"type": "boolean",
+									"description": "Whether to add a View action to row actions. Maps to CnIndexPage `showViewAction`."
+								},
 								"showEditAction": {
 									"type": "boolean",
 									"description": "Whether to add an Edit action to row actions. Maps to CnIndexPage `showEditAction`."
@@ -3824,6 +3844,24 @@
 						}
 					}
 				},
+				{
+					"description": "The \"builtin:<id>\" placeholders in config.actions place CnIndexPage's built-in row actions, so only a type='index' page may use them. On every other page type config.actions holds objects only; a placeholder there would validate and then render nothing (row-action-builtin-placement).",
+					"if": {
+						"not": {
+							"properties": { "type": { "const": "index" } },
+							"required": ["type"]
+						}
+					},
+					"then": {
+						"properties": {
+							"config": {
+								"properties": {
+									"actions": { "items": { "type": "object" } }
+								}
+							}
+						}
+					}
+				},
 				{
 					"description": "tabInAddress puts the active tab of a record in the address. Only a detail page has a record and a tab strip, so the key is refused elsewhere rather than validating into a no-op (case-page-and-list-as-a-place).",
 					"if": {

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

@@ -50,7 +50,7 @@
 				},
 				"settingsLabel": {
 					"type": "string",
-					"description": "Override label for the settings foldout's gear button. Defaults to 'Settings'."
+					"description": "Override label for the settings foldout's gear button. Defaults to 'Advanced'."
 				},
 				"primaryAction": {
 					"$ref": "#/$defs/primaryAction",

package/src/store/plugins/liveUpdates.js

@@ -432,19 +432,29 @@ export function liveUpdatesPlugin(opts = {}) {
 			const collectionInFlight = new Map()
 
 			const originalFetchCollection = store.fetchCollection.bind(store)
-			store.fetchCollection = async function dedupedFetchCollection(type, params = {}) {
+			store.fetchCollection = async function dedupedFetchCollection(type, params = {}, options = {}) {
 				if (!store.__liveDedupActive) {
-					return originalFetchCollection(type, params)
+					return originalFetchCollection(type, params, options)
 				}
 				const key = collectionDedupKey(type, params)
-				if (collectionInFlight.has(key)) {
-					return collectionInFlight.get(key)
+				let entry = collectionInFlight.get(key)
+				if (!entry) {
+					// The shared request reports into its own sink, copied to
+					// each caller's `options.outcome` below, so a caller that
+					// joined it learns that request's result too.
+					const outcome = {}
+					const promise = originalFetchCollection(type, params, { ...options, outcome }).finally(() => {
+						collectionInFlight.delete(key)
+					})
+					entry = { promise, outcome }
+					collectionInFlight.set(key, entry)
 				}
-				const promise = originalFetchCollection(type, params).finally(() => {
-					collectionInFlight.delete(key)
-				})
-				collectionInFlight.set(key, promise)
-				return promise
+				const results = await entry.promise
+				const sink = options && options.outcome
+				if (sink && typeof sink === 'object' && 'error' in entry.outcome) {
+					sink.error = entry.outcome.error
+				}
+				return results
 			}
 		},
 	}

package/src/store/useObjectStore.js

@@ -656,9 +656,12 @@ const baseActions = {
 	 *
 	 * @param {string} type The registered type slug
 	 * @param {object} [params] Query parameters (_limit, _page, _search, _order, filters)
+	 * @param {object} [options] Call options
+	 * @param {{error?: object|null}} [options.outcome] Opt-in sink for THIS call's own result: `error` is set to the error it records on `errors[type]`, or `null` on success. Unlike `errors[type]`, which every call for the type shares, a later call cannot overwrite it.
 	 * @return {Promise<Array>} The fetched collection (also stored in state)
 	 */
-	async fetchCollection(type, params = {}) {
+	async fetchCollection(type, params = {}, options = {}) {
+		const outcome = (options && typeof options.outcome === 'object' && options.outcome) || null
 		this.loading = { ...this.loading, [type]: true }
 		this.errors = { ...this.errors, [type]: null }
 
@@ -685,9 +688,13 @@ const baseActions = {
 			)
 
 			if (!response.ok) {
-				this.errors = { ...this.errors, [type]: await parseResponseError(response, type) }
+				const failure = await parseResponseError(response, type)
+				this.errors = { ...this.errors, [type]: failure }
+				if (outcome) {
+					outcome.error = failure
+				}
 				// eslint-disable-next-line no-console -- diagnostic for a failure this code already degrades from
-				console.error(`Error fetching ${type} collection:`, this.errors[type])
+				console.error(`Error fetching ${type} collection:`, failure)
 				return []
 			}
 
@@ -711,13 +718,17 @@ const baseActions = {
 				this.facets = { ...this.facets, [type]: transformed }
 			}
 
+			if (outcome) {
+				outcome.error = null
+			}
 			return results
 		} catch (error) {
-			this.errors = {
-				...this.errors,
-				[type]: error.name === 'TypeError'
-					? networkError(error)
-					: genericError(error),
+			const failure = error.name === 'TypeError'
+				? networkError(error)
+				: genericError(error)
+			this.errors = { ...this.errors, [type]: failure }
+			if (outcome) {
+				outcome.error = failure
 			}
 			// eslint-disable-next-line no-console -- diagnostic for a failure this code already degrades from
 			console.error(`Error fetching ${type} collection:`, error)

package/src/utils/resolveRowActions.js

@@ -0,0 +1,127 @@
+/**
+ * SPDX-FileCopyrightText: 2026 Conduction B.V. <info@conduction.nl>
+ * SPDX-License-Identifier: EUPL-1.2
+ */
+
+/**
+ * The built-in row action ids, in their default order.
+ *
+ * @type {ReadonlyArray<string>}
+ */
+export const BUILTIN_ROW_ACTION_IDS = Object.freeze(['view', 'edit', 'copy', 'delete'])
+
+/**
+ * The prefix that marks a row action entry as a placeholder for a built-in.
+ *
+ * @type {string}
+ */
+export const BUILTIN_PLACEHOLDER_PREFIX = 'builtin:'
+
+/**
+ * Whether an entry is one of the four built-in placeholders (`"builtin:view"`, `"builtin:edit"`, `"builtin:copy"`, `"builtin:delete"`).
+ *
+ * @param {object|string} entry A declared row action entry.
+ * @return {boolean} True for a known placeholder string.
+ */
+export function isBuiltinPlaceholder(entry) {
+	return typeof entry === 'string'
+		&& entry.startsWith(BUILTIN_PLACEHOLDER_PREFIX)
+		&& BUILTIN_ROW_ACTION_IDS.includes(entry.slice(BUILTIN_PLACEHOLDER_PREFIX.length))
+}
+
+/**
+ * A short name for an entry in a warning message.
+ *
+ * @param {object} action An app action object.
+ * @return {string} Its id, else its label, quoted.
+ */
+function describe(action) {
+	const name = (typeof action.id === 'string' && action.id !== '') ? action.id : action.label
+	return JSON.stringify(name === undefined ? '' : name)
+}
+
+/**
+ * Resolve a page's declared row actions and its enabled built-ins into the one ordered list every row surface renders.
+ *
+ * - An object is an app action, whatever its `id`; a `builtin` key on it is dropped, since only real built-ins carry that marker.
+ * - A placeholder (`"builtin:edit"`) puts that built-in at its position when it is enabled, and renders nothing when it is not: the toggle wins.
+ * - A repeated placeholder keeps its first position.
+ * - Any other entry is dropped.
+ * - Enabled built-ins the entries do not place are appended in the order `builtins` gives them.
+ *
+ * Every dropped or questionable entry is reported in `warnings`; the caller decides whether to log them.
+ *
+ * @param {Array<object|string>} declared The declared entries: app action objects and placeholders.
+ * @param {Array<{id: string}>} builtins The enabled built-in actions, in default order.
+ * @param {object} [options] Options.
+ * @param {(action: object) => object} [options.prepare] Maps an app action to the object rendered for it.
+ * @return {{actions: Array<object>, warnings: Array<{code: string, message: string}>, deleteNotLast: boolean}} The ordered actions, the warnings, and whether the built-in Delete is enabled but not last.
+ */
+export function resolveRowActions(declared, builtins, { prepare = (action) => action } = {}) {
+	const enabled = new Map()
+	for (const builtin of (Array.isArray(builtins) ? builtins : [])) {
+		if (builtin && typeof builtin.id === 'string') {
+			enabled.set(builtin.id, builtin)
+		}
+	}
+	const placed = new Set()
+	const actions = []
+	const warnings = []
+
+	for (const entry of (Array.isArray(declared) ? declared : [])) {
+		if (entry && typeof entry === 'object' && !Array.isArray(entry)) {
+			let action = entry
+			if (Object.hasOwn(entry, 'builtin')) {
+				const { builtin, ...rest } = entry
+				action = rest
+				warnings.push({
+					code: 'builtin-key-ignored',
+					message: `Action ${describe(entry)} sets "builtin", which only built-in actions carry; the key is ignored and the entry stays an app action.`,
+				})
+			}
+			actions.push(prepare(action))
+			continue
+		}
+		if (isBuiltinPlaceholder(entry)) {
+			const id = entry.slice(BUILTIN_PLACEHOLDER_PREFIX.length)
+			if (placed.has(id)) {
+				warnings.push({
+					code: 'repeated-placeholder',
+					message: `"${entry}" is placed more than once; only its first position is used.`,
+				})
+				continue
+			}
+			placed.add(id)
+			if (!enabled.has(id)) {
+				warnings.push({
+					code: 'disabled-placeholder',
+					message: `"${entry}" is placed but that built-in action is turned off, so it renders nothing. Its show*Action toggle decides whether it renders.`,
+				})
+				continue
+			}
+			actions.push(enabled.get(id))
+			continue
+		}
+		warnings.push({
+			code: 'invalid-entry',
+			message: `Ignoring action ${JSON.stringify(entry)}: actions must be objects with an id and a label, or one of ${BUILTIN_ROW_ACTION_IDS.map((id) => `"${BUILTIN_PLACEHOLDER_PREFIX}${id}"`).join(', ')}. To turn a built-in action on or off use the showViewAction / showEditAction / showCopyAction / showDeleteAction props.`,
+		})
+	}
+
+	for (const builtin of enabled.values()) {
+		if (!placed.has(builtin.id)) {
+			actions.push(builtin)
+		}
+	}
+
+	const deleteIndex = actions.findIndex((action) => action && action.builtin === true && action.id === 'delete')
+	const deleteNotLast = deleteIndex !== -1 && deleteIndex !== actions.length - 1
+	if (deleteNotLast) {
+		warnings.push({
+			code: 'delete-not-last',
+			message: `"${BUILTIN_PLACEHOLDER_PREFIX}delete" is not the last row action; it renders before ${actions.slice(deleteIndex + 1).map((a) => (a.builtin === true ? `"${BUILTIN_PLACEHOLDER_PREFIX}${a.id}"` : describe(a))).join(', ')}. Delete is normally last.`,
+		})
+	}
+
+	return { actions, warnings, deleteNotLast }
+}