@conduction/nextcloud-vue 2.79.0 → 2.80.0

package/src/integrations/builtin/field-inspection/CnFieldInspectionCard.vue

@@ -134,6 +134,13 @@
 					     (an invalid `ButtonType`, so the visual primary style never applied
 					     either). See CnFormPage.vue's inline comment for the submit-button
 					     half of this bug in detail. -->
+					<p v-if="saveError"
+						class="cn-field-inspection__error"
+						role="alert"
+						data-testid="cn-fi-save-error">
+						{{ saveError }}
+					</p>
+
 					<NcButton type="submit"
 						variant="primary"
 						data-testid="cn-fi-save"
@@ -157,7 +164,8 @@ import { NcButton, NcEmptyContent, NcLoadingIcon } from '@nextcloud/vue'
 import ClipboardCheckOutline from 'vue-material-design-icons/ClipboardCheckOutline.vue'
 import CnDetailCard from '../../../components/CnDetailCard/CnDetailCard.vue'
 import CnOfflineQueue from '../../../components/CnOfflineQueue/index.js'
-import { checklistProgress, classifyGps, syncIndicator, validateChecklistAnswers } from '../../offline/fieldCollectionHelpers.js'
+import { buildChecklistSubmission } from '../../offline/checklistSubmission.js'
+import { checklistProgress, classifyGps, normaliseChecklistTemplate, syncIndicator, validateChecklistAnswers } from '../../offline/fieldCollectionHelpers.js'
 import {
 	countPending,
 	countStuck,
@@ -236,6 +244,8 @@ export default {
 			activeTemplate: null,
 			answers: {},
 			errors: [],
+			/** Why the last save could not be queued, in words. */
+			saveError: '',
 		}
 	},
 
@@ -449,8 +459,13 @@ export default {
 			this.errors = []
 			const cfg = this.config
 			const templateRef = item?.[cfg.templateRefField]
+			// The app's template shape (sections, its own item keys and type
+			// words) is read into the leaf's flat item list here, once.
 			this.activeTemplate = templateRef
-				? await getCachedObject(this.effectiveRegister, cfg.referenceSchema, 'references', String(templateRef))
+				? normaliseChecklistTemplate(
+						await getCachedObject(this.effectiveRegister, cfg.referenceSchema, 'references', String(templateRef)),
+						cfg,
+					)
 				: null
 			const initial = {}
 			for (const q of (this.activeTemplate?.items || [])) {
@@ -464,6 +479,7 @@ export default {
 			this.activeTemplate = null
 			this.answers = {}
 			this.errors = []
+			this.saveError = ''
 		},
 
 		/**
@@ -485,7 +501,9 @@ export default {
 		},
 
 		/**
-		 * Validate answers, then queue a `create` mutation for the result.
+		 * Validate answers, then queue the run: an object create on
+		 * `resultSchema`, or, when the config names a `resultEndpoint`, one
+		 * `submit` to that endpoint.
 		 *
 		 * @return {Promise<void>}
 		 */
@@ -499,26 +517,22 @@ export default {
 			try {
 				const cfg = this.config
 				const gps = await this.captureGps()
-				const gpsClass = classifyGps(gps)
-				const now = new Date().toISOString()
-				const items = this.activeTemplate.items.map((q) => ({
-					questionId: q.questionId,
-					answer: this.answers[q.questionId].answer,
-					evidenceRefs: this.answers[q.questionId].evidenceRefs,
-					answeredAt: now,
-					gpsAtAnswer: gps ? { ...gps, source: gpsClass.source } : { source: 'sensorless' },
-				}))
-				const payload = {
-					inspectionRef: this.itemId(this.activeItem),
-					checklistTemplateRef: this.activeTemplate.id ?? this.activeTemplate['@self']?.id,
-					items,
-				}
+				const submission = buildChecklistSubmission(cfg, {
+					plannedItem: this.activeItem,
+					template: this.activeTemplate,
+					answers: this.answers,
+					gps,
+					gpsSource: classifyGps(gps).source,
+					capturedAt: new Date().toISOString(),
+					capturedOffline: this.offline,
+				})
 				await enqueueMutation({
 					deviceId: this.deviceId,
-					operationType: 'create',
+					operationType: submission.operationType,
 					register: this.effectiveRegister,
-					schema: cfg.resultSchema,
-					payload,
+					schema: submission.schema,
+					endpoint: submission.endpoint,
+					payload: submission.payload,
 				})
 				this.pendingCount = await countPending(this.deviceId)
 				this.stuckCount = await countStuck(this.deviceId)
@@ -527,6 +541,7 @@ export default {
 					await this.drain()
 				}
 			} catch (e) {
+				this.saveError = e?.message || t('nextcloud-vue', 'The answers could not be saved on this device.')
 				// eslint-disable-next-line no-console
 				console.error('[CnFieldInspectionCard] saveChecklist failed', e)
 			} finally {

package/src/integrations/builtin/field-inspection.js

@@ -56,6 +56,27 @@ export const DEFAULT_FIELD_INSPECTION_CONFIG = {
 	// Schema holding conflict records. Empty keeps a conflict on the device,
 	// and the queue row says so rather than pretending it was filed.
 	conflictSchema: '',
+	// How a template's items are read (normaliseChecklistTemplate). Empty
+	// `sectionsField` reads a flat `items[]`; set it when the items sit inside
+	// ordered sections, each with its own `items[]`.
+	sectionsField: '',
+	itemKeyField: 'questionId',
+	itemTextField: 'text',
+	itemTypeField: 'type',
+	// The app's own item type words onto the leaf's (`yes_no`,
+	// `photo_required`; anything else renders as free text).
+	itemTypeMap: {},
+	// An item whose `photoRequiredField` equals `photoRequiredValue` needs a
+	// photo as well as an answer. Empty switches the gate off.
+	photoRequiredField: '',
+	photoRequiredValue: '',
+	// Where a finished run goes (checklistSubmission). Empty queues an object
+	// create on `resultSchema`. Set, it is a path under the Nextcloud root with
+	// `{field}` placeholders from the planned item, and the run replays as one
+	// POST there, naming the template and the planned item under these keys.
+	resultEndpoint: '',
+	resultTemplateParam: 'templateId',
+	resultPlannedItemParam: 'plannedItem',
 }
 
 /**

package/src/integrations/offline/checklistSubmission.js

@@ -0,0 +1,137 @@
+/**
+ * SPDX-FileCopyrightText: 2026 Conduction B.V. <info@conduction.nl>
+ * SPDX-License-Identifier: EUPL-1.2
+ *
+ * What a finished offline checklist run turns into in the queue.
+ *
+ * Two shapes, chosen by the leaf's `offlineConfig`:
+ *
+ * - `resultEndpoint` empty: an object create on `resultSchema`, the shape the
+ *   leaf has always queued (`inspectionRef`, `checklistTemplateRef`,
+ *   `items[]` with `questionId` / `answer` / `evidenceRefs`).
+ * - `resultEndpoint` set: a `submit` operation that replays the run as ONE
+ *   POST to an app's own endpoint, for an app that stores a run as something
+ *   other than a plain object (a completed task, say) and checks the run
+ *   server side before it stores anything. The endpoint is a path under the
+ *   Nextcloud root with `{field}` placeholders filled from the planned item,
+ *   e.g. `/apps/myapp/api/cases/{caseRef}/checklist-run`.
+ *
+ * Pure: no axios, no IndexedDB, no DOM. The card queues what this returns and
+ * the replay service sends it.
+ *
+ * @module integrations/offline/checklistSubmission
+ */
+
+import { translate as t } from '@nextcloud/l10n'
+
+/**
+ * Fill a `{field}` endpoint template from a planned item.
+ *
+ * Each value is URL-encoded, so a planned item can never steer the request to
+ * another path. A placeholder the item does not fill is an error rather than
+ * an empty path segment: a run sent to the wrong case is worse than one that
+ * waits.
+ *
+ * @param {string} template    The endpoint template.
+ * @param {object} plannedItem The planned item the run belongs to.
+ *
+ * @return {string} The filled path.
+ *
+ * @throws {Error} When a placeholder has no value on the item.
+ */
+export function fillEndpoint(template, plannedItem) {
+	return String(template).replace(/\{([A-Za-z0-9_.]+)\}/g, (match, field) => {
+		const value = field.split('.').reduce((node, key) => (node === null || node === undefined ? undefined : node[key]), plannedItem)
+		if (value === undefined || value === null || String(value) === '') {
+			throw new Error(t('nextcloud-vue', 'This planned item has no {field}, so the answers have nowhere to go.', { field }))
+		}
+		return encodeURIComponent(String(value))
+	})
+}
+
+/**
+ * The id of an object, wherever OpenRegister carries it.
+ *
+ * @param {object|null} object The object.
+ *
+ * @return {string} The id, or an empty string.
+ */
+function idOf(object) {
+	return String(object?.id ?? object?.['@self']?.id ?? object?.uuid ?? '')
+}
+
+/**
+ * Build the queue operation for a finished checklist run.
+ *
+ * @param {object}      config                  The leaf's offline config.
+ * @param {object}      run                     The run.
+ * @param {object}      run.plannedItem         The planned item.
+ * @param {object}      run.template            The normalised template (`items[]`).
+ * @param {object}      run.answers             Map of questionId to `{ answer, evidenceRefs }`.
+ * @param {object|null} [run.gps]               The GPS fix at save, or null.
+ * @param {string}      [run.gpsSource]         `sensor` or `sensorless`.
+ * @param {string}      [run.capturedAt]        ISO time of the save.
+ * @param {boolean}     [run.capturedOffline]   Whether the device was offline at save.
+ *
+ * @return {{ operationType: string, schema: string, endpoint: (string|null), payload: object }}
+ *   The operation fields for `enqueueMutation`.
+ *
+ * @throws {Error} When the endpoint cannot be filled from the planned item.
+ */
+export function buildChecklistSubmission(config, run) {
+	const capturedAt = run.capturedAt || new Date().toISOString()
+	const gpsAtAnswer = run.gps ? { ...run.gps, source: run.gpsSource || 'sensor' } : { source: 'sensorless' }
+	const items = Array.isArray(run.template?.items) ? run.template.items : []
+	const answers = run.answers ?? {}
+	const plannedItemId = idOf(run.plannedItem)
+	const templateId = idOf(run.template)
+
+	if (!config.resultEndpoint) {
+		return {
+			operationType: 'create',
+			schema: config.resultSchema,
+			endpoint: null,
+			payload: {
+				inspectionRef: plannedItemId,
+				checklistTemplateRef: templateId,
+				items: items.map((q) => ({
+					questionId: q.questionId,
+					answer: answers[q.questionId]?.answer,
+					evidenceRefs: answers[q.questionId]?.evidenceRefs ?? [],
+					answeredAt: capturedAt,
+					gpsAtAnswer,
+				})),
+			},
+		}
+	}
+
+	const payload = {
+		[config.resultTemplateParam || 'templateId']: templateId,
+		[config.resultPlannedItemParam || 'plannedItem']: plannedItemId,
+		capturedAt,
+		capturedOffline: run.capturedOffline === true,
+		items: items
+			.filter((q) => {
+				const entry = answers[q.questionId] ?? {}
+				const hasAnswer = entry.answer !== undefined && entry.answer !== null && String(entry.answer).trim() !== ''
+				return hasAnswer || (Array.isArray(entry.evidenceRefs) && entry.evidenceRefs.length > 0)
+			})
+			.map((q) => ({
+				itemId: q.questionId,
+				value: answers[q.questionId]?.answer ?? '',
+				photos: answers[q.questionId]?.evidenceRefs ?? [],
+				answeredAt: capturedAt,
+				gpsAtAnswer,
+			})),
+	}
+	if (run.gps) {
+		payload.location = { ...run.gps, source: run.gpsSource || 'sensor' }
+	}
+
+	return {
+		operationType: 'submit',
+		schema: config.resultSchema || '',
+		endpoint: fillEndpoint(config.resultEndpoint, run.plannedItem),
+		payload,
+	}
+}

package/src/integrations/offline/fieldCollectionHelpers.js

@@ -46,11 +46,71 @@ export function classifyGps(fix, available = true) {
 	return { quality: 'good', source: 'sensor', warning: null }
 }
 
+/**
+ * Read a checklist template into the leaf's flat item contract.
+ *
+ * A consuming app's template does not have to carry `items[]` with
+ * `questionId` / `text` / `type`. Its `offlineConfig` names where those live:
+ * `sectionsField` when the items sit inside ordered sections, and the
+ * `item*Field` keys for the item's key, text and type. `itemTypeMap` translates
+ * the app's own type words onto the leaf's (`yes_no`, `photo_required`, or any
+ * other word, which renders as free text). `photoRequiredField` and
+ * `photoRequiredValue` mark an item whose answer also needs a photo.
+ *
+ * The template's own keys are kept, so the id and version stay readable; only
+ * `items` is replaced by the normalised list.
+ *
+ * @param {object|null} template The template as cached.
+ * @param {object}      [config] The leaf's offline config.
+ *
+ * @return {object|null} The template with flat `items[]`, or null.
+ */
+export function normaliseChecklistTemplate(template, config = {}) {
+	if (template === null || typeof template !== 'object') {
+		return null
+	}
+
+	const keyField = config.itemKeyField || 'questionId'
+	const textField = config.itemTextField || 'text'
+	const typeField = config.itemTypeField || 'type'
+	const typeMap = (config.itemTypeMap && typeof config.itemTypeMap === 'object') ? config.itemTypeMap : {}
+
+	const sections = config.sectionsField ? template[config.sectionsField] : null
+	const raw = Array.isArray(sections)
+		? sections.flatMap((section) => (Array.isArray(section?.items) ? section.items : []))
+		: (Array.isArray(template.items) ? template.items : [])
+
+	const items = []
+	for (const item of raw) {
+		if (item === null || typeof item !== 'object') {
+			continue
+		}
+		const questionId = String(item[keyField] ?? '')
+		if (questionId === '') {
+			continue
+		}
+		const ownType = item[typeField]
+		const photoRequired = Boolean(config.photoRequiredField)
+			&& item[config.photoRequiredField] === config.photoRequiredValue
+		items.push({
+			...item,
+			questionId,
+			text: item[textField] ?? item.text ?? questionId,
+			type: typeMap[ownType] ?? ownType ?? 'text',
+			required: item.required === true,
+			photoRequired,
+		})
+	}
+
+	return { ...template, items }
+}
+
 /**
  * Validate a set of checklist answers against the template's required items.
  *
- * A `required` item must have a non-empty answer; a `photo_required` item must
- * additionally have at least one evidence reference. Returns the per-question
+ * A `required` item must have a non-empty answer; a `photo_required` item, and
+ * any item flagged `photoRequired` by {@link normaliseChecklistTemplate}, must
+ * have at least one evidence reference. Returns the per-question
  * blocking errors so the UI can prevent save (and the engine never queues an
  * invalid result).
  *
@@ -66,7 +126,7 @@ export function validateChecklistAnswers(template, answersByQuestion) {
 	const errors = []
 
 	for (const item of items) {
-		if (item?.required !== true) {
+		if (item?.required !== true && item?.photoRequired !== true) {
 			continue
 		}
 		const entry = answers[item.questionId] ?? {}
@@ -80,7 +140,12 @@ export function validateChecklistAnswers(template, answersByQuestion) {
 			continue
 		}
 
-		if (answer === undefined || answer === null || String(answer).trim() === '') {
+		if (item.photoRequired === true && evidenceRefs.length === 0) {
+			errors.push({ questionId: item.questionId, message: t('nextcloud-vue', 'Photo required for this question') })
+			continue
+		}
+
+		if (item.required === true && (answer === undefined || answer === null || String(answer).trim() === '')) {
 			errors.push({ questionId: item.questionId, message: t('nextcloud-vue', 'This question is required') })
 		}
 	}

package/src/integrations/offline/index.js

@@ -60,10 +60,13 @@ export {
 	checklistProgress,
 	classifyGps,
 	GPS_POOR_ACCURACY_M,
+	normaliseChecklistTemplate,
 	syncIndicator,
 	validateChecklistAnswers,
 } from './fieldCollectionHelpers.js'
 
+export { buildChecklistSubmission, fillEndpoint } from './checklistSubmission.js'
+
 export {
 	CACHE_PREFIX,
 	cacheNameFor,

package/src/integrations/offline/offlineDb.js

@@ -257,10 +257,12 @@ export async function getPlanningMeta(register, schema, collection = 'planning')
  *
  * @param {object} operation                  The mutation operation.
  * @param {string} operation.deviceId         Owning device id (IDOR scope).
- * @param {string} operation.operationType    create / update / delete.
+ * @param {string} operation.operationType    create / update / delete / submit.
  * @param {string} operation.register         Target register slug or id.
  * @param {string} operation.schema           Target schema slug or id.
  * @param {string} [operation.targetId]       Existing object id (update/delete).
+ * @param {string} [operation.endpoint]       Path under the Nextcloud root a
+ *                                            `submit` row is POSTed to.
  * @param {object} [operation.payload]        The object body (create/update).
  *
  * @return {Promise<string>} The queued operation id.
@@ -275,6 +277,9 @@ export async function enqueueMutation(operation) {
 		register: operation.register,
 		schema: operation.schema,
 		targetId: operation.targetId ?? null,
+		// A `submit` operation replays to an app's own endpoint instead of the
+		// object API (see checklistSubmission.js); every other row has none.
+		endpoint: operation.endpoint ?? null,
 		payload: operation.payload ?? {},
 		queuedAt: operation.queuedAt || new Date().toISOString(),
 		attemptCount: 0,

package/src/integrations/offline/syncReplayService.js

@@ -35,7 +35,8 @@ function objectsUrl(register, schema) {
 }
 
 /**
- * Replay one queued mutation against the OR object API.
+ * Replay one queued mutation against the OR object API, or, for a row that
+ * names an `endpoint`, as one POST to that endpoint.
  *
  * @param {object} operation       The queue operation row.
  * @param {object} [offlineConfig] The leaf's offline config (`register`,
@@ -54,7 +55,12 @@ export async function replayOperation(operation, offlineConfig = {}) {
 
 	try {
 		let response
-		if (operation.operationType === 'create' || operation.operationType === 'upload') {
+		if (typeof operation.endpoint === 'string' && operation.endpoint !== '') {
+			// A run the app checks and stores itself (a completed task, say):
+			// one POST to its endpoint under the Nextcloud root. The endpoint
+			// decides access from what it has stored, as the object API does.
+			response = await axios.post(generateUrl(operation.endpoint), payload)
+		} else if (operation.operationType === 'create' || operation.operationType === 'upload') {
 			response = await axios.post(base, payload)
 		} else if (operation.operationType === 'update') {
 			response = await axios.put(`${base}/${operation.targetId}`, payload)

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.79.0",
+	"version": "2.85.0",
 	"type": "object",
 	"required": ["$schema", "version"],
 	"allOf": [
@@ -760,8 +760,8 @@
 		},
 		"sentinelFilterToken": {
 			"type": "string",
-			"pattern": "^@(?:me(?:\\.(?:displayName|email))?|myGroups|now|today|monthStart|quarterStart|yearStart)$|^@today[+-][0-9]+d$",
-			"description": "Filter-value context: relative fetch-time tokens resolved by resolveFilterTokens (@me, @me.displayName, @me.email, @myGroups (the current user's group ids, an IN list), @now, @today, @today±Nd, @monthStart, @quarterStart, @yearStart). Mirrors SENTINEL_TOKEN_PATTERNS.filter in src/utils/sentinelTokens.js (byte-equality enforced by a unit test)."
+			"pattern": "^@(?:me(?:\\.(?:displayName|email))?|myGroups|now|today|monthStart|monthEnd|nextMonthStart|quarterStart|yearStart)$|^@today[+-][0-9]+d$",
+			"description": "Filter-value context: relative fetch-time tokens resolved by resolveFilterTokens (@me, @me.displayName, @me.email, @myGroups (the current user's group ids, an IN list), @now, @today, @today±Nd, @monthStart, @monthEnd, @nextMonthStart, @quarterStart, @yearStart). Mirrors SENTINEL_TOKEN_PATTERNS.filter in src/utils/sentinelTokens.js (byte-equality enforced by a unit test)."
 		},
 		"sentinelConfigToken": {
 			"type": "string",
@@ -1132,14 +1132,43 @@
 		"headerPill": {
 			"type": "object",
 			"additionalProperties": false,
-			"required": ["field"],
-			"description": "A pill in a detail page header, rendered through CnStatusBadge from one field of the record. Nothing renders while the field is empty.",
+			"anyOf": [
+				{ "required": ["field"] },
+				{ "required": ["text"] },
+				{ "required": ["countFrom"] }
+			],
+			"description": "A pill in a detail page header, rendered through CnStatusBadge: from one field of the record (`field`; nothing renders while it is empty), a constant (`text`), or a count of a related list (`countFrom` with `countLabel`; nothing renders at 0, while counting or after a failed count). screens-relation-pages, 2.85.0.",
 			"properties": {
 				"field": {
 					"type": "string",
 					"minLength": 1,
 					"description": "Dot-path to the value on the record."
 				},
+				"text": {
+					"type": "string",
+					"minLength": 1,
+					"description": "A constant label (an i18n key), such as \"Inwoner\" or \"Klant\". Used when `field` is not set."
+				},
+				"countFrom": {
+					"type": "object",
+					"additionalProperties": false,
+					"required": ["register", "schema"],
+					"description": "The list the pill counts with one list request (`_limit=1`, the response's `total`). `filter` values take the `@objectId` and `@object.<field>` tokens. Used when `field` is not set.",
+					"properties": {
+						"register": { "type": "string", "minLength": 1 },
+						"schema": { "type": "string", "minLength": 1 },
+						"filter": { "type": "object", "additionalProperties": true }
+					}
+				},
+				"countLabel": {
+					"type": "object",
+					"additionalProperties": false,
+					"description": "The count pill's label for one and for more, i18n keys with `{count}`: `{ \"one\": \"{count} lopende zaak\", \"other\": \"{count} lopende zaken\" }`.",
+					"properties": {
+						"one": { "type": "string", "minLength": 1 },
+						"other": { "type": "string", "minLength": 1 }
+					}
+				},
 				"colorMap": {
 					"type": "object",
 					"description": "Raw value to badge variant. Keys are matched ignoring case.",
@@ -2582,6 +2611,14 @@
 					"type": "string",
 					"description": "open-form: overrides the create dialog's heading. Defaults to 'Create {schema title}'."
 				},
+				"formEyebrow": {
+					"type": "string",
+					"description": "open-form: the context line above the create dialog's heading (board look), e.g. the list the record joins. Through the host translate. Absent: no line."
+				},
+				"formSubtitle": {
+					"type": "string",
+					"description": "open-form: the sentence under the create dialog's heading (board look), e.g. which fields are required and what happens on save. Through the host translate. Absent: no sentence."
+				},
 				"size": {
 					"type": "string",
 					"enum": ["small", "normal", "large", "full"],
@@ -4072,6 +4109,36 @@
 							"minLength": 1,
 							"description": "type='index', board look: free text after the footer's count, e.g. \"click a column header to sort\" (screens-index-list-parity). Maps to CnIndexPage `footerNote`."
 						},
+						"queryPresets": {
+							"type": "array",
+							"minItems": 1,
+							"description": "type='index': per-query overlays of this page (screens-index-query-presets). A menu entry that deep-links here with a query (`menu[].query`, e.g. { caseType: '<uuid>' }, the shape hydra gate-68 asks for instead of a second page) gets its own lenses, columns and copy: the first preset whose every `match` pair is in the route query replaces those keys of this config. Only the listed keys can be replaced; register, schema and permissions stay the page's. Switching preset remounts the list.",
+							"items": {
+								"type": "object",
+								"required": ["match"],
+								"additionalProperties": false,
+								"properties": {
+									"id": { "type": "string", "minLength": 1, "description": "A name for the preset, for people reading the manifest." },
+									"match": { "type": "object", "minProperties": 1, "additionalProperties": { "type": ["string", "number", "boolean"] }, "description": "Route query pairs that must ALL be present, e.g. { \"caseType\": \"<uuid>\" }. A repeated parameter matches when it holds the value." },
+									"title": { "type": "string", "minLength": 1, "description": "The page title while the preset applies." },
+									"quickFilters": { "type": "array", "description": "The lenses while the preset applies; same shape as config.quickFilters." },
+									"columns": { "type": "array", "description": "The columns while the preset applies; same shape as config.columns." },
+									"cardFields": { "type": "array", "items": { "type": "string" }, "description": "The card facts while the preset applies." },
+									"countText": { "type": "string", "minLength": 1, "description": "The count line while the preset applies." },
+									"searchPlaceholder": { "type": "string", "minLength": 1, "description": "The search placeholder while the preset applies." },
+									"footerNote": { "type": "string", "minLength": 1, "description": "The footer note while the preset applies." },
+									"defaultSort": { "type": "array", "description": "The default sort while the preset applies; same shape as config.defaultSort." },
+									"viewSwitch": { "type": "array", "items": { "type": "string", "enum": ["table", "cards", "board", "map"] }, "description": "The drawn view segments while the preset applies." }
+								}
+							}
+						},
+						"viewSwitch": {
+							"type": "array",
+							"minItems": 1,
+							"uniqueItems": true,
+							"items": { "type": "string", "enum": ["table", "cards", "board", "map"] },
+							"description": "type='index', board look: the segments the view switch draws, e.g. [\"table\", \"cards\", \"board\", \"map\"] as the boards do. A listed mode the page can open is an ordinary segment; one it cannot (no board columns, no map) is drawn disabled and named \"<mode>: not available on this list\". Order is always table, cards, board, map. Ignored without the board look (screens-view-switch-parity). Maps to CnIndexPage `viewSwitch`."
+						},
 						"searchPlaceholder": {
 							"type": "string",
 							"minLength": 1,
@@ -4087,6 +4154,38 @@
 							"description": "type='index': the property keys the cards view shows as the facts list of each card, in order; defaults to the first four list columns under the board look (screens-card-parity). Maps to CnIndexPage `cardFields`.",
 							"items": { "type": "string", "minLength": 1 }
 						},
+						"statRow": {
+							"type": "array",
+							"default": [],
+							"description": "type='index': KPI tiles above the list, between the header and the toolbar, in an auto-fit row (each at least 200px). Each entry is a widget definition, usually `type: \"stat\"`; the type resolves through the app's widget registry, then the dashboard catalog (screens-index-stat-row). Maps to CnIndexPage `statRow`.",
+							"items": {
+								"type": "object",
+								"required": ["id", "type"],
+								"properties": {
+									"id": { "type": "string", "minLength": 1 },
+									"type": { "type": "string", "minLength": 1 },
+									"title": { "type": "string" },
+									"content": { "type": "object" },
+									"headerLink": { "type": "object" }
+								}
+							}
+						},
+						"sidePanel": {
+							"type": "array",
+							"default": [],
+							"description": "type='index': titled cards in a 300px column right of the toolbar and the list (above them below 1024px). Each entry is a widget definition with an optional `title` (i18n key) and `headerLink`; the type resolves as for `statRow` (screens-index-stat-row). Maps to CnIndexPage `sidePanel`.",
+							"items": {
+								"type": "object",
+								"required": ["id", "type"],
+								"properties": {
+									"id": { "type": "string", "minLength": 1 },
+									"type": { "type": "string", "minLength": 1 },
+									"title": { "type": "string" },
+									"content": { "type": "object" },
+									"headerLink": { "type": "object" }
+								}
+							}
+						},
 						"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; under the board look it reads \"Download\" by default), `actions-menu` (the page's header actions as one labelled menu button, absent when the page has none), `import`, `refresh`, or the id of a `headerActions` entry. Under the board look the buttons render in a fixed order whatever the manifest declares: export, actions-menu, other secondary buttons, the buildiq square, then the primary button. 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`.",