@conduction/nextcloud-vue 2.83.0 → 2.85.0

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.93.0",
+	"version": "2.99.0",
 	"type": "object",
 	"required": ["$schema", "version"],
 	"allOf": [
@@ -150,6 +150,7 @@
 							"title": { "type": "string", "description": "i18n key / text for the tour name (restart menu)." },
 							"trigger": { "type": "string", "enum": ["first-visit", "version-bump", "empty-index", "manual"], "default": "manual", "description": "When the tour auto-starts." },
 							"minAppVersion": { "type": "string", "description": "Semver; the tour is inert below this app version." },
+							"startOn": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "uniqueItems": true, "description": "Route names the tour may auto-start on. A user who first lands anywhere else, such as on a case opened from a link, does not get the tour there: it waits until they reach one of these routes. Without it a tour whose first step is centered starts wherever the user lands. Has no effect on a tour started by hand." },
 							"steps": {
 								"type": "array",
 								"description": "Ordered steps.",
@@ -808,6 +809,11 @@
 			"pattern": "^@row\\.[A-Za-z][A-Za-z0-9_.@]*$",
 			"description": "Row context: a field of the row a row action runs on (@row.<field>, dot path allowed), read by the field-list widget's rowActions request url and payload (payload values resolve at any depth). Mirrors SENTINEL_TOKEN_PATTERNS.row."
 		},
+		"sentinelContextToken": {
+			"type": "string",
+			"pattern": "^@context\\.[A-Za-z][A-Za-z0-9_.]*$",
+			"description": "Detail context: a record a detail page reads beside the loaded one (`config.visibilityContext`), read by a grid widget's or a tab's `visibleWhen` field as @context.<name>.<field> (dot path allowed). Mirrors SENTINEL_TOKEN_PATTERNS.context."
+		},
 		"sentinelSubjectToken": {
 			"type": "string",
 			"pattern": "^@subject\\.[A-Za-z][A-Za-z0-9_.]*$",
@@ -826,6 +832,7 @@
 				{ "$ref": "#/$defs/sentinelAnswerToken" },
 				{ "$ref": "#/$defs/sentinelRowToken" },
 				{ "$ref": "#/$defs/sentinelSubjectToken" },
+				{ "$ref": "#/$defs/sentinelContextToken" },
 				{ "$ref": "#/$defs/sentinelDeprecatedToken" }
 			]
 		},
@@ -1109,7 +1116,12 @@
 							"additionalProperties": { "type": "string", "enum": ["default", "primary", "success", "warning", "error", "info", "purple", "teal"] }
 						},
 						"due": { "type": "string", "description": "The date field of the footer's due text, marked by `dueRule`." },
-						"owner": { "type": "string", "description": "The field of the owner shown as an avatar (initials) at the footer's end." }
+						"owner": { "type": "string", "description": "The field of the owner shown as an avatar (initials) at the footer's end." },
+						"formatters": {
+							"type": "object",
+							"description": "screens-board-reference-columns (2.97.0): a card field (one of the role fields above) to the id of a formatter in the app's `cnFormatters` registry, the one table columns name in `formatter`. The card shows the formatted text, so a reference reads as its name (`{ \"caseType\": \"caseTypeName\" }`).",
+							"additionalProperties": { "type": "string", "minLength": 1 }
+						}
 					}
 				},
 				"colorField": {
@@ -1138,6 +1150,95 @@
 				"dueRule": {
 					"$ref": "#/$defs/dueRule",
 					"description": "Marks late cards. A card whose date is before today gets an error edge and the label 'Overdue'; one due within `soonDays` gets 'Due soon'. Omitted, no card is marked."
+				},
+				"columnFields": {
+					"type": "array",
+					"minItems": 1,
+					"description": "screens-board-reference-columns (2.97.0): the fields the columns can come from, offered in a \"Columns:\" switch after the search when there are two or more (\"status | type | assignee\"). The entry on `statusField` is the default. An entry with a `source` takes its columns from the rows the field REFERENCES (a case's status pointing at statusType rows), fetched, not from the values on the cards; `kind: \"values\"` (a user id, which references no schema) takes the values present plus a column for no value. Without a `source` or `kind` the field's enum or lifecycle states are read as before. A drop writes the reference: through `moveHandler` when named, else a PATCH of the field on the row.",
+					"items": {
+						"type": "object",
+						"additionalProperties": false,
+						"required": ["field"],
+						"properties": {
+							"field": { "type": "string", "minLength": 1, "description": "The row field the columns come from." },
+							"label": { "type": "string", "description": "Its name in the column switch (an i18n key). Defaults to the field." },
+							"kind": { "type": "string", "enum": ["values"], "description": "`values`: the field references no schema (a Nextcloud user id); the columns are the values present on the rows, by `valueLabels` or the value itself, then one column for no value (`emptyLabel`)." },
+							"valueLabels": { "type": "object", "additionalProperties": { "type": "string" }, "description": "`kind: values`: raw value to the column label." },
+							"emptyLabel": { "type": "string", "description": "`kind: values`: the label of the column for no value (an i18n key). Defaults to \"Nobody\"." },
+							"source": {
+								"type": "object",
+								"additionalProperties": false,
+								"description": "The referenced rows that are the columns: one list request to `register`/`schema` (defaults: the page's register and the property's `$ref`).",
+								"properties": {
+									"register": { "type": "string", "minLength": 1 },
+									"schema": { "type": "string", "minLength": 1 },
+									"labelField": { "type": "string", "description": "The referenced row's field that names a column. Defaults to `name`, then `title`." },
+									"orderField": { "type": "string", "description": "The referenced row's numeric field the columns are ordered by." },
+									"colorField": { "type": "string", "description": "The referenced row's field that holds the column's dot colour (a badge variant or a CSS colour)." },
+									"filter": { "type": "object", "description": "Equality filters on the referenced rows, e.g. `{ \"isFinal\": false }` to leave out end states.", "additionalProperties": { "type": ["string", "number", "boolean"] } },
+									"mergeBy": { "type": "string", "description": "Merge referenced rows with the same value of this field into one column (statuses of every case type by `name`). A drop then writes the row of the card's own parent (`narrowBy`), and is refused when that parent has none." },
+									"narrowBy": {
+										"type": "object",
+										"additionalProperties": false,
+										"required": ["field", "rowField"],
+										"description": "The parent link: the referenced row's `field` equals the card's `rowField` (statusType.caseType = case.caseType). While the page filters on `rowField` with one value, the columns are that parent's rows only.",
+										"properties": {
+											"field": { "type": "string", "minLength": 1 },
+											"rowField": { "type": "string", "minLength": 1 }
+										}
+									}
+								}
+							},
+							"readOnly": { "type": "boolean", "default": false, "description": "No drag and no Move to while the columns come from this field." },
+							"moveHandler": { "type": "string", "minLength": 1, "description": "A handler in the app's registry that makes the move: it gets `{ card, toKey, field, value, target }` (value: the referenced id to write; target: its row) and returns a promise; a rejection shows its message as the refusal. Absent, the field is written with a PATCH." },
+							"moveTargetsHandler": { "type": "string", "minLength": 1, "description": "A handler in the app's registry that answers where one card may go: it gets `{ card, field }` and returns the values (referenced ids) it can reach. Columns out of reach fade during a drag, read \"not allowed\" in the card menu, and refuse a drop." }
+						}
+					}
+				},
+				"moveHandler": {
+					"type": "string",
+					"minLength": 1,
+					"description": "screens-board-reference-columns (2.97.0): a handler in the app's registry that moves a card on `statusField` (the app's transition), with the `columnFields[].moveHandler` call shape. Lets a manifest-only page run the host's transition, which the `runTransition` prop could not."
+				},
+				"moveTargetsHandler": {
+					"type": "string",
+					"minLength": 1,
+					"description": "screens-board-reference-columns (2.97.0): where a card on `statusField` may go, with the `columnFields[].moveTargetsHandler` call shape."
+				},
+				"narrow": {
+					"type": "object",
+					"additionalProperties": false,
+					"required": ["field"],
+					"description": "screens-board-reference-columns (2.97.0): a select after the search (\"Case type: All case types | Woo-verzoek | ...\") that sets the page filter on `field`. With a reference column's `narrowBy.rowField` on the same field, the columns narrow to that parent's rows.",
+					"properties": {
+						"field": { "type": "string", "minLength": 1, "description": "The row field the select filters on." },
+						"label": { "type": "string", "description": "The select's label (an i18n key), shown with a colon. Defaults to the property's title." },
+						"allLabel": { "type": "string", "description": "The option for no narrowing (an i18n key). Defaults to \"All\"." },
+						"source": {
+							"type": "object",
+							"additionalProperties": false,
+							"description": "Where the options come from (defaults: the page's register and the property's `$ref`).",
+							"properties": {
+								"register": { "type": "string", "minLength": 1 },
+								"schema": { "type": "string", "minLength": 1 },
+								"labelField": { "type": "string", "description": "The option row's label field. Defaults to `title`." },
+								"filter": { "type": "object", "additionalProperties": { "type": ["string", "number", "boolean"] } }
+							}
+						}
+					}
+				},
+				"columnSwitchLabel": {
+					"type": "string",
+					"description": "screens-board-reference-columns (2.97.0): the column switch's label (an i18n key), shown with a colon. Defaults to \"Columns\"."
+				},
+				"hint": {
+					"type": "string",
+					"description": "screens-board-reference-columns (2.97.0): one sentence after the board's controls, in the secondary colour (an i18n key), e.g. how a move works."
+				},
+				"wrap": {
+					"type": "boolean",
+					"default": false,
+					"description": "screens-board-reference-columns (2.97.0): wrap the columns onto more rows, as many to a row as fit at 240px, instead of one row that scrolls sideways. For a board with more stages than fit."
 				}
 			}
 		},
@@ -3526,7 +3627,7 @@
 						},
 						"titleField": {
 							"type": "string",
-							"description": "type='wiki': property on the article object holding the page title. Defaults to 'title'. Maps to CnWikiPage `titleField` prop."
+							"description": "type='wiki': property on the article object holding the page title. Defaults to 'title'. Maps to CnWikiPage `titleField` prop. type='detail' (detail-title-field): the record field (a dotted path, for example `number`) the header names the record by, as an invoice page names the invoice number instead of the schema title; an empty value falls back to the display name, and the breadcrumb's current crumb and the type eyebrow follow. Maps to CnDetailPage `titleField`."
 						},
 						"idParam": {
 							"type": "string",
@@ -4170,8 +4271,19 @@
 							"description": "type='index': show the page header (icon, title, description) inline. Default false: the title renders visually hidden and the sidebar names the page. Maps to CnIndexPage `showTitle`."
 						},
 						"countSubtitle": {
-							"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`."
+							"anyOf": [
+								{ "type": "string" },
+								{
+									"type": "object",
+									"additionalProperties": false,
+									"required": ["singular", "plural"],
+									"properties": {
+										"singular": { "type": "string", "minLength": 1, "description": "i18n key of the line for a total of one, e.g. \"{total} invoice\"." },
+										"plural": { "type": "string", "minLength": 1, "description": "i18n key of the line for any other total, e.g. \"{total} invoices\"." }
+									}
+								}
+							],
+							"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. `{ singular, plural }` picks the form by the total through the app's plural translation (`translatePlural`), so \"1 factuur\" and \"12 facturen\" each read right (index-count-plural). Maps to CnIndexPage `countSubtitle`."
 						},
 						"showTitleIcon": {
 							"type": "boolean",
@@ -4297,7 +4409,7 @@
 						},
 						"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`.",
+							"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`. type='reports' (screens-reports-header-buttons, 2.96.0): the same buttons beside the reports page title, as board DcRapportages draws \"Downloaden\". There `label` is required and `action` is the id of a `headerActions` entry (same shape as on an index page), which says what the click does; every click also emits `header-action`. Under the board look the buildiq square sits between the secondary buttons and the primary one. Maps to CnReportsPage `headerButtons`.",
 							"items": {
 								"type": "object",
 								"additionalProperties": false,
@@ -4349,6 +4461,20 @@
 							"minLength": 1,
 							"description": "type='detail': the id of a widget in `widgets` to render inside the header on its own row under the title, without a card of its own, e.g. the stages bars (zuiddrecht-pixel-gaps-2). The widget leaves the body grid. Maps to CnDetailPage `headerWidget`."
 						},
+						"visibilityContext": {
+							"type": "object",
+							"description": "type='detail': records the page reads beside the loaded one, so a widget's or a tab's `visibleWhen` can ask about them (detail-widgets-visible-when). `{ <name>: { field, register, schema } }`: `field` is the property of the loaded record holding the other record's id, and a condition reads that record as `@context.<name>.<path>`, e.g. `{ \"field\": \"@context.caseType.category\", \"op\": \"in\", \"value\": [\"Sociaal domein\"] }`. A record that cannot be read is absent, so its condition fails safe. Maps to CnDetailPage `visibilityContext`.",
+							"additionalProperties": {
+								"type": "object",
+								"required": ["field", "register", "schema"],
+								"additionalProperties": false,
+								"properties": {
+									"field": { "type": "string", "minLength": 1, "description": "Dot-path on the loaded record to the id of the record to read." },
+									"register": { "type": "string", "minLength": 1, "description": "Register slug or id of the record to read." },
+									"schema": { "type": "string", "minLength": 1, "description": "Schema slug or id of the record to read." }
+								}
+							}
+						},
 						"mapConfig": {
 							"type": "object",
 							"additionalProperties": true,
@@ -4510,6 +4636,11 @@
 						}
 					}
 				},
+				{
+					"description": "screens-board-reference-columns (2.97.0): config.board on an index page, the block CnPageRenderer hands to CnIndexPage's `board` prop, is typed by boardView like pages[].board.",
+					"if": { "properties": { "type": { "const": "index" } }, "required": ["type"] },
+					"then": { "properties": { "config": { "properties": { "board": { "$ref": "#/$defs/boardView" } } } } }
+				},
 				{
 					"description": "index-calendar-view-mode: config.calendar on an index page is typed by calendarView.",
 					"if": { "properties": { "type": { "const": "index" } }, "required": ["type"] },

package/src/store/useObjectStore.js

@@ -707,6 +707,8 @@ const baseActions = {
 	 * @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.
+	 * @param {boolean} [options.append] Add the fetched page after the rows already stored instead of replacing them. Dropped when the stored rows are no longer the page before it, or when `options.isCurrent()` returns false (the query changed meanwhile).
+	 * @param {() => boolean} [options.isCurrent] With `append`: asked once the page arrives; false drops it.
 	 * @return {Promise<Array>} The fetched collection (also stored in state)
 	 */
 	async fetchCollection(type, params = {}, options = {}) {
@@ -750,14 +752,26 @@ const baseActions = {
 
 			const data = await response.json()
 			const results = data.results || data
+			const append = options?.append === true
 
-			this.collections = { ...this.collections, [type]: results }
+			const stale = append && (
+				Number(this.pagination[type]?.page || 1) !== Number(params._page || 1) - 1
+				|| (typeof options.isCurrent === 'function' && !options.isCurrent())
+			)
+			if (stale) {
+				return []
+			}
+
+			this.collections = {
+				...this.collections,
+				[type]: append ? [...(this.collections[type] || []), ...results] : results,
+			}
 			// Why a personal lens came back empty, if it says (openregister#4514).
 			this.lenses = { ...this.lenses, [type]: readLensReports(data) }
 			this.pagination = {
 				...this.pagination,
 				[type]: {
-					total: data.total || results.length,
+					total: data.total || (append ? this.collections[type].length : results.length),
 					page: data.page || 1,
 					pages: data.pages || 1,
 					limit: params._limit || 20,

package/src/utils/boardColumns.js

@@ -128,6 +128,10 @@ function labelFor(field, value) {
  * @param {string} options.statusField - The property name on a row.
  * @param {string} [options.offBoardLabel] - What to call the off-board column.
  * @param {string} [options.colorField] - The key on a state that holds its dot colour.
+ * @param {?((row: object) => string)} [options.keyOf] - The column a row
+ *   belongs in, for a field whose raw value is not the column key (a
+ *   reference whose rows are merged by name). Absent, the row's
+ *   `statusField` value is the key.
  *
  * @return {{columns: Array<object>, usable: boolean}} The columns, each
  *   `{ key, label, cards, count }`, and whether the field could back a board.
@@ -138,6 +142,7 @@ export function buildBoardColumns({
 	statusField = '',
 	offBoardLabel = 'Elsewhere',
 	colorField = '',
+	keyOf = null,
 } = {}) {
 	const { stages, usable } = stagesOf(field, colorField)
 	if (usable === false) {
@@ -156,7 +161,9 @@ export function buildBoardColumns({
 
 	const offBoard = { key: OFF_BOARD_KEY, label: offBoardLabel, cards: [], count: 0 }
 	for (const row of rows) {
-		const value = String(row?.[statusField] ?? '')
+		const value = typeof keyOf === 'function'
+			? String(keyOf(row) ?? '')
+			: String(row?.[statusField] ?? '')
 		const column = byKey.get(value) || offBoard
 		column.cards.push(row)
 		column.count += 1

package/src/utils/boardReferenceColumns.js

@@ -0,0 +1,274 @@
+/**
+ * SPDX-FileCopyrightText: 2026 Conduction B.V. <info@conduction.nl>
+ * SPDX-License-Identifier: EUPL-1.2
+ *
+ * Board columns from a REFERENCED field (screens-board-reference-columns).
+ *
+ * A status that is an enum or a lifecycle list carries its stages on the
+ * field, and `boardColumns.js` reads them there. A status that is a reference
+ * to another object (a case's `status` pointing at a statusType row) carries
+ * nothing on the field: the stages are the rows of the referenced schema. This
+ * module turns those rows into the same `states` list `stagesOf()` reads, plus
+ * the map from a row's raw value (the referenced id) to its column.
+ *
+ * 🔴 THE COLUMNS ARE STILL THE SCHEMA'S, NOT THE DATA'S. They are the
+ * referenced rows, fetched, not the values present on the loaded cards, so an
+ * empty stage is still a column to drop a card into. The one exception is a
+ * field with no referenced schema at all (a Nextcloud user id): there the
+ * values present are all there is, and a "nobody" column is always added so
+ * work without an owner stays visible and can be dropped back to nobody.
+ *
+ * 🔴 MERGED COLUMNS RESOLVE PER CARD. Referenced rows are often per parent
+ * (every case type has its own "In behandeling"). Merged by name they make one
+ * column, and a drop must then write the row of THAT card's parent. A column
+ * with no row for the card's parent is not a place the card can go, and the
+ * drop is refused rather than written to some other parent's row.
+ *
+ * Pure apart from `fetchReferenceObjects`: no store, no Vue.
+ */
+
+import { buildHeaders, buildQueryString, prefixUrl } from './headers.js'
+import { readPath } from './readPath.js'
+import { schemaRefSlug } from './schemaRefSlug.js'
+
+/** The column of cards with no value, for a `values` column field. */
+export const NO_VALUE_KEY = '__none__'
+
+/**
+ * The id a reference value carries: a string as is, an object by its `id`,
+ * `uuid` or `@self.id`.
+ *
+ * @param {unknown} value A reference as a row holds it.
+ * @return {string} The id, '' when there is none.
+ */
+export function refIdOf(value) {
+	if (value === null || value === undefined) {
+		return ''
+	}
+	if (typeof value === 'object') {
+		const id = value.id ?? value.uuid ?? value['@self']?.id ?? value.value ?? ''
+		return id === null || id === undefined ? '' : String(id)
+	}
+	return String(value)
+}
+
+/**
+ * A value as text: a string or number as is, an object by its name.
+ *
+ * @param {unknown} value The raw value.
+ * @return {string} The text.
+ */
+function textOf(value) {
+	if (value === null || value === undefined) {
+		return ''
+	}
+	if (typeof value === 'object') {
+		return String(value.displayName ?? value.name ?? value.title ?? value.label ?? '').trim()
+	}
+	return String(value).trim()
+}
+
+/**
+ * The column fields a board offers, normalised. Without `columnFields` the
+ * board has one, its `statusField`, read from the schema as before.
+ *
+ * @param {object} board The board configuration (manifest `config.board`).
+ * @return {Array<{field: string, label: string, source: (object|null), kind: string, readOnly: boolean, moveHandler: string, moveTargetsHandler: string}>} The fields.
+ * @spec openspec/changes/screens-board-reference-columns/specs/board-view/spec.md#requirement-a-board-can-switch-the-field-its-columns-come-from
+ */
+export function columnFieldsOf(board) {
+	const declared = Array.isArray(board?.columnFields) ? board.columnFields : []
+	return declared
+		.map((entry) => (typeof entry === 'string' ? { field: entry } : entry))
+		.filter((entry) => entry && typeof entry.field === 'string' && entry.field !== '')
+		.map((entry) => ({
+			field: entry.field,
+			label: typeof entry.label === 'string' && entry.label !== '' ? entry.label : entry.field,
+			source: entry.source && typeof entry.source === 'object' ? entry.source : null,
+			kind: entry.kind === 'values' ? 'values' : (entry.source ? 'reference' : 'schema'),
+			readOnly: entry.readOnly === true,
+			moveHandler: typeof entry.moveHandler === 'string' ? entry.moveHandler : '',
+			moveTargetsHandler: typeof entry.moveTargetsHandler === 'string' ? entry.moveTargetsHandler : '',
+			valueLabels: entry.valueLabels && typeof entry.valueLabels === 'object' ? entry.valueLabels : null,
+			emptyLabel: typeof entry.emptyLabel === 'string' ? entry.emptyLabel : '',
+		}))
+}
+
+/**
+ * The register and schema a reference column reads its rows from: the
+ * source's own, else the page's register and the property's `$ref`.
+ *
+ * @param {object} source The column field's `source`.
+ * @param {object} options The context.
+ * @param {string} options.register The page's register.
+ * @param {object} [options.property] The field's schema property.
+ * @return {{register: string, schema: string}} Both, '' when unknown.
+ */
+export function referenceTargetOf(source, { register = '', property = null } = {}) {
+	const schema = source?.schema || schemaRefSlug(property?.$ref ?? property?.items?.$ref ?? '')
+	return {
+		register: String(source?.register || register || ''),
+		schema: schema === '' || schema === null || schema === undefined ? '' : String(schema),
+	}
+}
+
+/**
+ * The stages of a referenced field: the referenced rows, narrowed to one
+ * parent when asked, ordered, and merged by a field when asked.
+ *
+ * @param {object} options The call.
+ * @param {Array<object>} options.refs The referenced rows.
+ * @param {string} [options.labelField] The row field that names a column.
+ * @param {string} [options.orderField] The numeric row field the columns are ordered by.
+ * @param {string} [options.colorField] The row field that holds the dot colour.
+ * @param {string} [options.mergeBy] The row field whose equal values make one column.
+ * @param {{field: string, rowField: string}|null} [options.narrowBy] The parent link.
+ * @param {string} [options.narrowValue] The parent the board is narrowed to, '' for all.
+ * @return {{states: Array<{key: string, label: string, color: string}>, keyByValue: Map<string, string>, refsByKey: Map<string, Array<object>>}} The stages.
+ * @spec openspec/changes/screens-board-reference-columns/specs/board-view/spec.md#requirement-columns-can-be-the-rows-a-field-references
+ */
+export function buildReferenceStages({
+	refs = [],
+	labelField = '',
+	orderField = '',
+	colorField = '',
+	mergeBy = '',
+	narrowBy = null,
+	narrowValue = '',
+} = {}) {
+	const list = (Array.isArray(refs) ? refs : []).filter((ref) => ref && typeof ref === 'object' && refIdOf(ref) !== '')
+	const narrowed = narrowBy && narrowBy.field && narrowValue !== ''
+		? list.filter((ref) => refIdOf(readPath(ref, narrowBy.field)) === String(narrowValue))
+		: list
+
+	const orderOf = (ref) => {
+		const n = Number(orderField ? readPath(ref, orderField) : NaN)
+		return Number.isFinite(n) ? n : Number.MAX_SAFE_INTEGER
+	}
+	const ordered = narrowed
+		.map((ref, index) => ({ ref, index }))
+		.sort((a, b) => (orderOf(a.ref) - orderOf(b.ref)) || (a.index - b.index))
+		.map((entry) => entry.ref)
+
+	const states = []
+	const keyByValue = new Map()
+	const refsByKey = new Map()
+	for (const ref of ordered) {
+		const id = refIdOf(ref)
+		const label = textOf(labelField ? readPath(ref, labelField) : (ref.name ?? ref.title)) || id
+		const key = mergeBy ? (textOf(readPath(ref, mergeBy)) || id) : id
+		keyByValue.set(id, key)
+		if (!refsByKey.has(key)) {
+			refsByKey.set(key, [])
+			const color = colorField ? readPath(ref, colorField) : ref.color
+			states.push({ key, label, color: typeof color === 'string' ? color : '' })
+		}
+		refsByKey.get(key).push(ref)
+	}
+	return { states, keyByValue, refsByKey }
+}
+
+/**
+ * The stages of a field with no referenced schema (a user id): the values
+ * present on the rows, by label, then one column for no value.
+ *
+ * @param {object} options The call.
+ * @param {Array<object>} options.rows The rows the list holds.
+ * @param {string} options.field The row field.
+ * @param {object} [options.valueLabels] Raw value to the label to show.
+ * @param {string} [options.emptyLabel] The no-value column's label.
+ * @return {{states: Array<{key: string, label: string, color: string}>, keyByValue: Map<string, string>, refsByKey: Map<string, Array<object>>}} The stages.
+ * @spec openspec/changes/screens-board-reference-columns/specs/board-view/spec.md#requirement-a-field-without-a-referenced-schema-takes-its-values
+ */
+export function buildValueStages({ rows = [], field = '', valueLabels = null, emptyLabel = 'Nobody' } = {}) {
+	const labels = valueLabels && typeof valueLabels === 'object' ? valueLabels : {}
+	const seen = new Map()
+	for (const row of Array.isArray(rows) ? rows : []) {
+		const raw = readPath(row, field)
+		const id = refIdOf(raw)
+		if (id !== '' && !seen.has(id)) {
+			seen.set(id, typeof labels[id] === 'string' ? labels[id] : (textOf(raw) || id))
+		}
+	}
+	const states = [...seen.entries()]
+		.sort((a, b) => a[1].localeCompare(b[1]))
+		.map(([key, label]) => ({ key, label, color: '' }))
+	states.push({ key: NO_VALUE_KEY, label: emptyLabel, color: '' })
+	const keyByValue = new Map(states.map((state) => [state.key, state.key]))
+	keyByValue.set('', NO_VALUE_KEY)
+	return { states, keyByValue, refsByKey: new Map() }
+}
+
+/**
+ * The column a row sits in, under a value-to-column map.
+ *
+ * @param {object} row The row.
+ * @param {string} field The row field.
+ * @param {Map<string, string>} keyByValue The value-to-column map.
+ * @return {string} The column key, or the raw value when the map has none
+ *   (which lands the card in the off-board column).
+ */
+export function columnKeyOfRow(row, field, keyByValue) {
+	const id = refIdOf(readPath(row, field))
+	return keyByValue.has(id) ? keyByValue.get(id) : id
+}
+
+/**
+ * What a drop on a column writes for one card: the referenced row of that
+ * column which belongs to the card's parent, or null when the column has none
+ * (the card cannot go there).
+ *
+ * @param {object} options The call.
+ * @param {object} options.card The card.
+ * @param {string} options.toKey The column it was dropped on.
+ * @param {string} options.kind `reference` or `values`.
+ * @param {Map<string, Array<object>>} [options.refsByKey] The column's rows.
+ * @param {{field: string, rowField: string}|null} [options.narrowBy] The parent link.
+ * @return {{value: (string|null), target: (object|null)}|null} The value to write and its row, or null.
+ * @spec openspec/changes/screens-board-reference-columns/specs/board-view/spec.md#requirement-a-drop-writes-the-reference
+ */
+export function resolveDropValue({ card, toKey, kind, refsByKey = new Map(), narrowBy = null } = {}) {
+	if (kind === 'values') {
+		return { value: toKey === NO_VALUE_KEY ? null : String(toKey), target: null }
+	}
+	const candidates = refsByKey.get(String(toKey)) || []
+	if (candidates.length === 0) {
+		return null
+	}
+	if (narrowBy && narrowBy.field && narrowBy.rowField) {
+		const parent = refIdOf(readPath(card, narrowBy.rowField))
+		const match = candidates.find((ref) => refIdOf(readPath(ref, narrowBy.field)) === parent)
+		return match ? { value: refIdOf(match), target: match } : null
+	}
+	return { value: refIdOf(candidates[0]), target: candidates[0] }
+}
+
+/**
+ * Fetch the rows a reference column is built from, one list request.
+ *
+ * @param {object} options The call.
+ * @param {string} options.register The register slug.
+ * @param {string} options.schema The schema slug.
+ * @param {object} [options.filter] Equality filters, e.g. `{ isFinal: false }`.
+ * @param {number} [options.limit] The page size, 500 by default.
+ * @return {Promise<Array<object>>} The rows.
+ * @spec openspec/changes/screens-board-reference-columns/specs/board-view/spec.md#requirement-columns-can-be-the-rows-a-field-references
+ */
+export async function fetchReferenceObjects({ register, schema, filter = {}, limit = 500 } = {}) {
+	if (!register || !schema) {
+		return []
+	}
+	const params = { _limit: limit }
+	for (const [key, value] of Object.entries(filter || {})) {
+		if (value !== undefined && value !== null && typeof value !== 'object') {
+			params[key] = typeof value === 'boolean' ? String(value) : value
+		}
+	}
+	const url = prefixUrl(`/apps/openregister/api/objects/${encodeURIComponent(register)}/${encodeURIComponent(schema)}${buildQueryString(params)}`)
+	const response = await fetch(url, { headers: buildHeaders() })
+	if (!response.ok) {
+		throw new Error(`list returned ${response.status}`)
+	}
+	const data = await response.json()
+	return Array.isArray(data?.results) ? data.results : (Array.isArray(data) ? data : [])
+}

package/src/utils/buildManifest.js

@@ -137,7 +137,10 @@ export function mergeMenuItems(target, incoming) {
 			target.push(copy)
 			return
 		}
-		for (const key of ['label', 'icon', 'route', 'order', 'section', 'featureFlag', 'permission', 'visibleIf', 'href', 'action']) {
+		// `query` and `params` belong to `route`: an entry that takes its route
+		// from here without them opens the list unfiltered (a "board" entry to
+		// `Cases` with `{ _view: 'board' }` opened the table).
+		for (const key of ['label', 'icon', 'route', 'query', 'params', 'order', 'section', 'featureFlag', 'permission', 'visibleIf', 'href', 'action']) {
 			if (existing[key] === undefined && item[key] !== undefined) {
 				existing[key] = item[key]
 			}
@@ -195,6 +198,7 @@ export function applyMenuRelocations(menu, relocations) {
 	if (!relocations || typeof relocations !== 'object') {
 		return menu
 	}
+	const heldEntries = captionsHoldingEntries(menu)
 	for (let pass = 0; pass < 5; pass++) {
 		const moves = []
 		for (let i = menu.length - 1; i >= 0; i--) {
@@ -240,9 +244,42 @@ export function applyMenuRelocations(menu, relocations) {
 			}
 		})
 	}
-	// Drop empty group shells left behind by relocations.
-	return menu.filter((m) => m.route || m.href || m.action
+	// Drop empty group shells left behind by relocations. A caption (a
+	// section heading) has no route and no children and is kept, unless the
+	// relocations emptied it: every entry under it moved away.
+	const kept = menu.filter((m) => m.type === 'caption' || m.route || m.href || m.action
 		|| (Array.isArray(m.children) && m.children.length > 0))
+	const holdingNow = captionsHoldingEntries(kept)
+	return kept.filter((m) => m.type !== 'caption' || !heldEntries.has(m) || holdingNow.has(m))
+}
+
+/**
+ * The captions (`type: "caption"`) that have at least one entry under them:
+ * a non-caption entry of the same section before the next caption.
+ *
+ * @param {Array<object>} menu The top-level menu.
+ * @return {Set<object>} The captions holding an entry.
+ */
+function captionsHoldingEntries(menu) {
+	const holding = new Set()
+	menu.forEach((entry, index) => {
+		if (entry.type !== 'caption') {
+			return
+		}
+		const section = entry.section ?? 'main'
+		for (let i = index + 1; i < menu.length; i++) {
+			const next = menu[i]
+			if ((next.section ?? 'main') !== section) {
+				continue
+			}
+			if (next.type === 'caption') {
+				break
+			}
+			holding.add(entry)
+			break
+		}
+	})
+	return holding
 }
 
 /**