@conduction/nextcloud-vue 2.96.0 → 2.98.0

package/l10n/en.json

@@ -1145,6 +1145,8 @@
     "Due tomorrow": "Due tomorrow",
     "Due in {days} days": "Due in {days} days",
     "Available": "Available",
+    "{value} of {limit}": "{value} of {limit}",
+    "{value} of {limit}, over the limit": "{value} of {limit}, over the limit",
     "Ready to claim": "Ready to claim",
     "In progress": "In progress",
     "Completed": "Completed",
@@ -1584,7 +1586,25 @@
     "{s} s": "{s} s",
     "About this {app} installation.": "About this {app} installation.",
     "{version}, up to date": "{version}, up to date",
-    "for an SLA": "for an SLA"
+    "for an SLA": "for an SLA",
+    "About {name}": "About {name}",
+    "Sent message": "Sent message",
+    "Received message": "Received message",
+    "Loading messages…": "Loading messages…",
+    "Move {item} up": "Move {item} up",
+    "Move {item} down": "Move {item} down",
+    "Remove {item}": "Remove {item}",
+    "Nothing added yet.": "Nothing added yet.",
+    "Ordered list": "Ordered list",
+    "{item} moved to position {position} of {total}": "{item} moved to position {position} of {total}",
+    "{item} removed": "{item} removed",
+    "{item} added": "{item} added",
+    "Organisations": "Organisations",
+    "Provisioning": "Provisioning",
+    "Suspended": "Suspended",
+    "Deprovisioning": "Deprovisioning",
+    "Archived": "Archived",
+    "Retained": "Retained"
   },
   "plurals": {
     "{count} selected": [

package/l10n/nl.json

@@ -1171,6 +1171,8 @@
     "Due tomorrow": "Morgen",
     "Due in {days} days": "Over {days} dagen",
     "Available": "Beschikbaar",
+    "{value} of {limit}": "{value} van {limit}",
+    "{value} of {limit}, over the limit": "{value} van {limit}, boven de limiet",
     "Ready to claim": "Klaar om op te pakken",
     "In progress": "In behandeling",
     "Completed": "Afgerond",
@@ -1770,7 +1772,40 @@
     "{s} s": "{s} s",
     "About this {app} installation.": "Over deze {app}-installatie.",
     "{version}, up to date": "{version}, bijgewerkt",
-    "for an SLA": "voor een SLA"
+    "for an SLA": "voor een SLA",
+    "About {name}": "Over {name}",
+    "Sent message": "Verstuurd bericht",
+    "Received message": "Ontvangen bericht",
+    "Loading messages…": "Berichten laden…",
+    "Move {item} up": "{item} omhoog",
+    "Move {item} down": "{item} omlaag",
+    "Remove {item}": "{item} verwijderen",
+    "Nothing added yet.": "Nog niets toegevoegd.",
+    "Ordered list": "Lijst op volgorde",
+    "{item} moved to position {position} of {total}": "{item} staat nu op plaats {position} van {total}",
+    "{item} removed": "{item} verwijderd",
+    "{item} added": "{item} toegevoegd",
+    "Question {n} of {total}": "Vraag {n} van {total}",
+    "Questions answered": "Beantwoorde vragen",
+    "(required)": "(verplicht)",
+    "Answer this question to go on.": "Beantwoord deze vraag om verder te gaan.",
+    "Finish": "Afronden",
+    "Take or add a photo": "Foto maken of toevoegen",
+    "Another photo": "Nog een foto",
+    "Photo for question {n}": "Foto bij vraag {n}",
+    "This checklist has no questions.": "Deze checklist heeft geen vragen.",
+    "The checklist could not be loaded.": "De checklist kon niet worden geladen.",
+    "The answer could not be saved. Try again.": "Het antwoord kon niet worden opgeslagen. Probeer het opnieuw.",
+    "Checklist finished.": "Checklist afgerond.",
+    "Not applicable": "Niet van toepassing",
+    "Answer with a photo.": "Beantwoord met een foto.",
+    "This answer needs a photo. Add one to go on.": "Bij dit antwoord hoort een foto. Voeg er een toe om verder te gaan.",
+    "Organisations": "Organisaties",
+    "Provisioning": "Wordt ingericht",
+    "Suspended": "Opgeschort",
+    "Deprovisioning": "Wordt opgeheven",
+    "Archived": "Gearchiveerd",
+    "Retained": "Bewaard"
   },
   "plurals": {
     "{count} selected": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@conduction/nextcloud-vue",
-  "version": "2.96.0",
+  "version": "2.98.0",
   "description": "Shared Vue component library for Conduction Nextcloud apps — complements @nextcloud/vue with higher-level components, OpenRegister integration, and NL Design System support",
   "homepage": "https://github.com/ConductionNL/nextcloud-vue#readme",
   "bugs": {
@@ -86,7 +86,7 @@
     "jsdoc-baselines:update": "node scripts/check-jsdoc.js --update",
     "lint": "eslint src/ eslint/ testing/ tests/ e2e/",
     "lint-fix": "npm run lint -- --fix",
-    "prepare": "husky || true",
+    "prepare": "husky || true; git config merge.l10n.name 'l10n catalogue key-wise merge' || true; git config merge.l10n.driver 'node scripts/merge-l10n.js %O %A %B %P' || true",
     "prepublishOnly": "npm run build",
     "smoke-baseline:update": "node scripts/update-smoke-baseline.js",
     "styleguide": "cd styleguide && npm run server",

package/scripts/merge-l10n.js

@@ -0,0 +1,196 @@
+#!/usr/bin/env node
+/**
+ * SPDX-License-Identifier: EUPL-1.2
+ * SPDX-FileCopyrightText: 2026 Conduction B.V.
+ *
+ * Git merge driver for the l10n catalogues (`l10n/*.json`).
+ *
+ * Every branch that adds a library string appends to the end of `translations`
+ * (and sometimes `plurals`) in `l10n/en.json` and `l10n/nl.json`, so two
+ * branches always edit the same last lines and git calls it a conflict on
+ * every merge of development. A catalogue is a set of keys, not a sequence of
+ * lines, so this driver merges the three versions key by key: a key one side
+ * added is kept, a key one side removed is dropped, a key only one side
+ * changed takes that side's text, and only a key BOTH sides changed to
+ * different texts is a conflict.
+ *
+ * A conflict is written with `<<<<<<<` / `=======` / `>>>>>>>` markers around
+ * the two one-line entries and exit code 1, so git marks the path unmerged and
+ * the file does not parse until a person picks one. A side that does not
+ * parse is not guessed at: exit 1, our version untouched.
+ *
+ * Order: our keys in our order, then the keys only their side added, in
+ * theirs. Output is `JSON.stringify(doc, null, 2)` plus a newline, which is the
+ * shape every catalogue in this repo already has byte for byte.
+ *
+ * `merge=union` is not used on purpose: it concatenates both hunks, which on
+ * JSON drops a comma or doubles a brace, and a catalogue that does not parse
+ * turns every string back into its English key.
+ *
+ * Registration is local git config (git never runs a command a repository
+ * ships); `npm install` sets it through `prepare`, an existing clone runs:
+ *
+ *   git config merge.l10n.driver 'node scripts/merge-l10n.js %O %A %B %P'
+ *
+ * Without it git falls back to its ordinary merge, as before.
+ *
+ * Usage (what git invokes): node scripts/merge-l10n.js %O %A %B %P
+ */
+
+'use strict'
+
+const fs = require('fs')
+
+const MARKER_INDENT = '    '
+
+/**
+ * Whether two catalogue values are the same (a plural is an array of forms).
+ *
+ * @param {unknown} a One value, undefined for absent.
+ * @param {unknown} b The other.
+ * @return {boolean}
+ */
+function same(a, b) {
+	return a === b || (a !== undefined && b !== undefined && JSON.stringify(a) === JSON.stringify(b))
+}
+
+/**
+ * Three-way merge of one object of keys (a catalogue block).
+ *
+ * @param {object} base The ancestor's block.
+ * @param {object} ours Our block.
+ * @param {object} theirs Their block.
+ * @return {{merged: object, conflicts: Array<{key: string, ours: unknown, theirs: unknown}>}}
+ */
+function mergeBlock(base, ours, theirs) {
+	const merged = {}
+	const conflicts = []
+	const keys = [...Object.keys(ours), ...Object.keys(theirs).filter((key) => !Object.hasOwn(ours, key))]
+	for (const key of keys) {
+		const b = base[key]
+		const o = ours[key]
+		const t = theirs[key]
+		let value
+		if (same(o, t)) {
+			value = o
+		} else if (same(o, b)) {
+			value = t
+		} else if (same(t, b)) {
+			value = o
+		} else {
+			conflicts.push({ key, ours: o, theirs: t })
+			value = o === undefined ? t : o
+		}
+		if (value !== undefined) {
+			merged[key] = value
+		}
+	}
+	return { merged, conflicts }
+}
+
+/**
+ * Whether a value is a plain object (a catalogue block).
+ *
+ * @param {unknown} value The value.
+ * @return {boolean}
+ */
+function isBlock(value) {
+	return value !== null && typeof value === 'object' && !Array.isArray(value)
+}
+
+/**
+ * Merge three catalogue texts.
+ *
+ * @param {string} baseText The ancestor ('' when both sides added the file).
+ * @param {string} oursText Our version.
+ * @param {string} theirsText Their version.
+ * @return {{text: string|null, conflicts: number}} The merged text (null when a side does not parse) and the number of conflicting keys.
+ */
+function mergeCatalogues(baseText, oursText, theirsText) {
+	let base
+	let ours
+	let theirs
+	try {
+		base = baseText.trim() === '' ? {} : JSON.parse(baseText)
+		ours = JSON.parse(oursText)
+		theirs = JSON.parse(theirsText)
+	} catch {
+		return { text: null, conflicts: 0 }
+	}
+	if (!isBlock(base) || !isBlock(ours) || !isBlock(theirs)) {
+		return { text: null, conflicts: 0 }
+	}
+	const doc = {}
+	const conflicts = []
+	const topKeys = [...Object.keys(ours), ...Object.keys(theirs).filter((key) => !Object.hasOwn(ours, key))]
+	for (const key of topKeys) {
+		const [b, o, t] = [base[key], ours[key], theirs[key]]
+		if (isBlock(o) || isBlock(t)) {
+			const result = mergeBlock(isBlock(b) ? b : {}, isBlock(o) ? o : {}, isBlock(t) ? t : {})
+			doc[key] = result.merged
+			result.conflicts.forEach((conflict) => conflicts.push({ block: key, ...conflict }))
+			continue
+		}
+		const result = mergeBlock({ [key]: b }, o === undefined ? {} : { [key]: o }, t === undefined ? {} : { [key]: t })
+		if (Object.hasOwn(result.merged, key)) {
+			doc[key] = result.merged[key]
+		}
+		result.conflicts.forEach((conflict) => conflicts.push({ block: null, ...conflict }))
+	}
+	let text = JSON.stringify(doc, null, 2) + '\n'
+	for (const conflict of conflicts) {
+		text = markConflict(text, conflict)
+	}
+	return { text, conflicts: conflicts.length }
+}
+
+/**
+ * Put conflict markers around one key's entry, both sides on one line each.
+ *
+ * @param {string} text The serialised merge.
+ * @param {{block: string|null, key: string, ours: unknown, theirs: unknown}} conflict The conflict.
+ * @return {string} The text with markers.
+ */
+function markConflict(text, conflict) {
+	const indent = conflict.block ? MARKER_INDENT : '  '
+	const entry = (value) => (value === undefined ? `${indent}(removed)` : `${indent}${JSON.stringify(conflict.key)}: ${JSON.stringify(value)},`)
+	const lines = text.split('\n')
+	const start = lines.findIndex((line) => line.startsWith(`${indent}${JSON.stringify(conflict.key)}: `))
+	if (start < 0) {
+		return text
+	}
+	let end = start
+	if (/[[{]$/.test(lines[start])) {
+		const close = indent + (lines[start].endsWith('[') ? ']' : '}')
+		while (end < lines.length - 1 && !lines[end].startsWith(close)) {
+			end += 1
+		}
+	}
+	const block = ['<<<<<<< ours', entry(conflict.ours), '=======', entry(conflict.theirs), '>>>>>>> theirs']
+	lines.splice(start, end - start + 1, ...block)
+	return lines.join('\n')
+}
+
+module.exports = { mergeCatalogues }
+
+if (require.main === module) {
+	const [basePath, oursPath, theirsPath, label] = process.argv.slice(2)
+	const read = (file) => {
+		try {
+			return fs.readFileSync(file, 'utf8')
+		} catch {
+			return ''
+		}
+	}
+	const { text, conflicts } = mergeCatalogues(read(basePath), read(oursPath), read(theirsPath))
+	if (text === null) {
+		process.stderr.write(`merge-l10n: ${label || oursPath} does not parse on one side; resolve it by hand.\n`)
+		process.exit(1)
+	}
+	fs.writeFileSync(oursPath, text)
+	if (conflicts > 0) {
+		process.stderr.write(`merge-l10n: ${conflicts} key(s) in ${label || oursPath} were translated differently on both sides.\n`)
+		process.exit(1)
+	}
+	process.exit(0)
+}

package/src/components/CnAppRoot/CnAppRoot.md

@@ -87,6 +87,7 @@ With loading state, custom components, translate, permissions, and custom page t
 | `userSettingsTitle` | String | No | `''` | Title shown at the top of the hosted `NcAppSettingsDialog`. Empty (the default) resolves to "User settings" from the library catalogue ("Persoonlijke instellingen" in Dutch), then the app's `translate`. Override per app to brand the modal (e.g. `'Decidiq preferences'`). |
 | `userSettingsEyebrow` | String | No | `''` | Board look: the line above the user-settings title. Empty uses "Your account" ("Uw account"). Goes through the app's `translate`. |
 | `userSettingsSubtitle` | String | No | `''` | Board look: the sentence under the user-settings title. Empty uses "Only for you. Colleagues keep their own settings." Goes through the app's `translate`. |
+| `userSettingsNextcloudLinks` | Array | No | `[]` | Board look: Nextcloud's own personal settings, listed first in the user-settings navigation as links, `[{ label, section? \| href?, icon? }]`. With any, the app's sections sit under one entry named after the app. |
 | `userSettingsSections` | Array | No | `null` | The user-settings sections to draw, in order: `app` (the app's slot content), `notifications`, `credentials`, `walkthrough`, `integrations`. A key left out is not drawn. `null` keeps the defaults: every section after `#user-settings-sections` content, or only the `#user-settings` content and the integrations section. |
 | `adminSettingsTitle` | String | No | `''` | Title shown at the top of the admin-settings `NcAppSettingsDialog`. Empty (the default) resolves to `translate('Administration')`. Override per app (e.g. `'Pipelinq administration'`). |
 | `requiresApps` | Array | No | `['openregister']` | App ids that MUST be installed for the host app to function. Checked against the OCS capabilities API on mount. When any required app is missing, CnAppRoot renders the empty state from the `or-missing` slot (default: `<NcEmptyContent>`) instead of the renderer. Pass `[]` to opt out (e.g. launchpad, the docs/styleguide app) — useful for any consumer that does not depend on OpenRegister. |

package/src/components/CnAppRoot/CnAppRoot.vue

@@ -1687,6 +1687,20 @@ export default {
 			default: '',
 		},
 
+		/**
+		 * Board look: Nextcloud's own personal settings, listed first in the
+		 * user-settings navigation as links, `[{ label, section? | href?, icon? }]`
+		 * (`section` is a personal settings section id). With any, the app's
+		 * sections sit under one entry named after the app. Labels go through
+		 * the app's `translate`.
+		 *
+		 * @type {Array<object>}
+		 */
+		userSettingsNextcloudLinks: {
+			type: Array,
+			default: () => [],
+		},
+
 		/**
 		 * The sections of the user-settings modal, in the order they are
 		 * drawn. Keys: `app` (the content of the `#user-settings-sections`
@@ -3143,6 +3157,9 @@ export default {
 			if (this.userSettingsSubtitle) {
 				props.subtitle = this.translate(this.userSettingsSubtitle)
 			}
+			if (Array.isArray(this.userSettingsNextcloudLinks) && this.userSettingsNextcloudLinks.length > 0) {
+				props.nextcloudLinks = this.userSettingsNextcloudLinks.map((link) => ({ ...link, label: this.translate(link?.label || '') }))
+			}
 			return props
 		},
 

package/src/components/CnCellRenderer/CnCellRenderer.vue

@@ -24,6 +24,24 @@
 			</span>
 		</template>
 
+		<!-- Built-in "actions" widget: row actions as inline buttons ("Aan zaak
+		     koppelen", "Nieuwe zaak"). The page resolves the buttons
+		     (widgetProps.items) and runs a click (widgetProps.run). -->
+		<template v-else-if="widget === 'actions'">
+			<span class="cn-cell-renderer__actions" data-testid="cn-cell-actions">
+				<NcButton
+					v-for="item in actionItems"
+					:key="item.key"
+					:variant="item.variant"
+					size="small"
+					:disabled="item.disabled"
+					:data-testid="`cn-cell-action-${item.key}`"
+					@click.stop="runAction(item)">
+					{{ item.label }}
+				</NcButton>
+			</span>
+		</template>
+
 		<!-- Built-in "badge" widget: renders the value as a status pill. An enum
 		     value shows its label (x-enum-labels, translated) unless a formatter
 		     shapes it; the colour stays keyed on the raw value. -->
@@ -350,7 +368,7 @@
 
 <script>
 import { getCanonicalLocale, translate as t } from '@nextcloud/l10n'
-import { NcAvatar, NcCheckboxRadioSwitch, NcDateTime } from '@nextcloud/vue'
+import { NcAvatar, NcButton, NcCheckboxRadioSwitch, NcDateTime } from '@nextcloud/vue'
 import CheckBold from 'vue-material-design-icons/CheckBold.vue'
 import CnFkResolveCell from '../CnFkResolveCell/CnFkResolveCell.vue'
 import CnIcon from '../CnIcon/CnIcon.vue'
@@ -398,6 +416,7 @@ export default {
 		CnGroupNameCell,
 		CheckBold,
 		NcAvatar,
+		NcButton,
 		NcDateTime,
 	},
 
@@ -586,6 +605,24 @@ export default {
 	},
 
 	computed: {
+		/**
+		 * The `actions` widget's buttons for this row: the page's resolved
+		 * `widgetProps.items` (a list, or a function of the row returning
+		 * one), each `{ key, label, variant?, disabled? }`.
+		 *
+		 * @return {Array<{key: string, label: string, variant: string, disabled: boolean}>}
+		 * @spec openspec/changes/table-actions-column/specs/index-page/spec.md#requirement-a-column-can-show-row-actions-as-buttons
+		 */
+		actionItems() {
+			const raw = typeof this.widgetProps?.items === 'function' ? this.widgetProps.items(this.row) : this.widgetProps?.items
+			const items = Array.isArray(raw) ? raw : []
+			return items.map((item) => ({
+				...item,
+				variant: item.variant || 'secondary',
+				disabled: item.disabled === true,
+			}))
+		},
+
 		/**
 		 * Whether the "switch" widget is on: the pending state while a toggle
 		 * is in flight, else `widgetProps.checked(row)`, else the value.
@@ -1419,6 +1456,19 @@ export default {
 	},
 
 	methods: {
+		/**
+		 * Run an `actions` widget button for this row through the page.
+		 *
+		 * @param {{key: string}} item The button.
+		 * @return {void}
+		 * @spec openspec/changes/table-actions-column/specs/index-page/spec.md#requirement-a-column-can-show-row-actions-as-buttons
+		 */
+		runAction(item) {
+			if (typeof this.widgetProps?.run === 'function') {
+				this.widgetProps.run(item.key, this.row)
+			}
+		},
+
 		/**
 		 * The "switch" widget was flipped: show the new state and hand it to
 		 * `widgetProps.onToggle(row, on)`. A rejection puts the switch back.
@@ -1555,6 +1605,12 @@ export default {
 </script>
 
 <style scoped>
+.cn-cell-renderer__actions {
+	display: inline-flex;
+	flex-wrap: wrap;
+	gap: 8px;
+}
+
 .cn-cell-renderer__icon-label {
 	display: inline-flex;
 	align-items: center;

package/src/components/CnChartWidget/CnChartWidget.md

@@ -18,7 +18,7 @@ When `CnDashboardPage` resolves a widget definition with `type: "chart"`, it mou
 }
 ```
 
-Supported `props` keys forwarded by the dispatcher: `chartKind` (→ `type`), `series`, `categories`, `labels`, `options`, `colors`, `toolbar`, `legend`, `height`, `width`, `unavailableLabel`, plus the display passthrough `horizontal`, `legendPosition`, `valueAxisBaseline`, `valueFormat`, `colorMap`, `emptyLabel`, `views`, `endpointSource`, `barMax`, `footnote`, `highlight`. The `dataSource` field resolves declaratively: `aggregate: 'count'` / raw `graphql` via GraphQL, `bucket` / `groupBy` / the OBJECT-form `aggregate` (Wave 3: group-by + topN/Other + labelResolve) via OpenRegister's REST aggregation facets, with an optional sibling `drilldown: { route, filterParam }` that navigates on segment/bar click with the raw category key in the query.
+Supported `props` keys forwarded by the dispatcher: `chartKind` (→ `type`), `series`, `categories`, `labels`, `options`, `colors`, `toolbar`, `legend`, `height`, `width`, `unavailableLabel`, plus the display passthrough `horizontal`, `legendPosition`, `valueAxisBaseline`, `valueFormat`, `colorMap`, `emptyLabel`, `views`, `endpointSource`, `barMax`, `footnote`, `highlight`, `cellSource`. The `dataSource` field resolves declaratively: `aggregate: 'count'` / raw `graphql` via GraphQL, `bucket` / `groupBy` / the OBJECT-form `aggregate` (Wave 3: group-by + topN/Other + labelResolve) via OpenRegister's REST aggregation facets, with an optional sibling `drilldown: { route, filterParam }` that navigates on segment/bar click with the raw category key in the query.
 
 Area chart — time series data:
 
@@ -109,6 +109,7 @@ Fallback slot — shown when ApexCharts is not available:
 | `barMax` | Number | `null` | `bar-list`: the value a full track stands for (100 for percentages); null takes the largest value |
 | `footnote` | String | `''` | `bar-list` / `matrix`: a line under the rows, through the host's translate |
 | `highlight` | Object | `null` | `matrix`: the cell to outline, `{ row, column, columnKeys? }`, tokens such as `@object.behaviour` resolved |
+| `cellSource` | Object | `null` | `matrix`: read the cells from records that each hold one cell (`{ register, schema, filter?, rowField, columnField, valueField, … }`), or with `cellsPath` from the cells inside one record, see [Bar list and matrix](#bar-list-and-matrix) |
 | `valueAxisBaseline` | String | `'auto'` | How the value axis picks its baseline, so a small difference cannot read as a dramatic one. `'auto'` anchors magnitude marks (bar/area) at zero and stops line charts zooming past a quarter of the data's magnitude; `'zero'` always anchors at zero; `'fit'` restores plain ApexCharts autoscaling — use it for series that live far from zero (a percentage hovering 95–99), where a zero baseline flattens the signal. Pie-family charts, negative series, empty data and stacked charts (`options.chart.stacked` — where the visible height is the per-category sum, not the largest datapoint) always autoscale; an explicit `options.yaxis.min`/`max` still wins. The ceiling rounds up to a nice number (7 → 8, 62 → 80). |
 | `valueFormat` | String\|Object | `null` | Named value formatter for the value axis + tooltip: `'currency'`, `'currency-compact'`, `'percent'`, or `{ name, currency?, decimals? }` |
 | `colorMap` | Object | `null` | Per-category colour map (`{ categoryLabel: cssColor }`) for pie-family slices and (distributed) bar categories |

package/src/components/CnChartWidget/CnChartWidget.vue

@@ -138,9 +138,11 @@ import { useDataSource } from '../../composables/useDataSource.js'
 import { getByPath, useEndpointSource } from '../../composables/useEndpointSource.js'
 import { useObjectStore } from '../../store/useObjectStore.js'
 import { resolveObjectOpType } from '../../utils/actionsDispatcher.js'
+import { fetchReferenceObjects } from '../../utils/boardReferenceColumns.js'
 import { resolveObjectTokenContext } from '../../utils/detailObjectContext.js'
 import { safeCurrencyCode } from '../../utils/formatMetric.js'
-import { resolveFilterTokens } from '../../utils/resolveFilterTokens.js'
+import { cellsFromRecord, pivotCells } from '../../utils/matrixCells.js'
+import { hasUnresolvedTokens, resolveFilterTokens } from '../../utils/resolveFilterTokens.js'
 import { userLocale } from '../../utils/userLocale.js'
 
 /**
@@ -388,6 +390,26 @@ export default {
 			default: null,
 		},
 
+		/**
+		 * `matrix`: read the cells from records that each hold one cell, in
+		 * a register: `{ register, schema, filter?, rowField, columnField,
+		 * valueField, rowLabelField?, columnLabelField?, rowLabels?,
+		 * columnLabels?, valueLabels?, rowOrder?, columnOrder?, rowOrderField?,
+		 * columnOrderField?, limit? }`. `filter` takes tokens such as
+		 * `@object.matrixVersion`; the list waits while one is unresolved.
+		 * With `cellsPath` the matrix sits inside ONE record instead: the
+		 * first record `filter` finds (else `fallbackFilter`), its array at
+		 * `cellsPath` narrowed by `cellFilter` (tokens allowed), the axis
+		 * order from `rowOrderPath` / `columnOrderPath` on that record.
+		 * Wins over `series` / `categories`.
+		 *
+		 * @spec openspec/changes/matrix-cell-records/specs/matrix-cell-records/spec.md#requirement-a-matrix-can-read-its-cells-from-records
+		 */
+		cellSource: {
+			type: Object,
+			default: null,
+		},
+
 		/**
 		 * Chart data series. Format depends on chart type.
 		 * For line/area/bar: [{ name: string, data: number[] }]
@@ -800,6 +822,8 @@ export default {
 			// `drilldown` click navigates with the filterable value, not the
 			// display label.
 			aggregateData: null,
+			// The `cellSource` matrix, laid out (`{ series, categories, columnKeys }`), or null.
+			cellData: null,
 			// Active `views[]` switcher key (null = the first view). Local
 			// UI state only — never persisted.
 			activeViewKey: null,
@@ -900,6 +924,9 @@ export default {
 		 * and `labels`.
 		 */
 		resolvedSeries() {
+			if (this.cellData) {
+				return this.cellData.series
+			}
 			const ep = this.endpointChartData
 			if (ep) {
 				return ep.series
@@ -913,6 +940,9 @@ export default {
 		},
 
 		resolvedCategories() {
+			if (this.cellData) {
+				return this.cellData.categories
+			}
 			const ep = this.endpointChartData
 			if (ep) {
 				return ep.categories
@@ -926,6 +956,9 @@ export default {
 		},
 
 		resolvedLabels() {
+			if (this.cellData) {
+				return this.cellData.categories
+			}
 			const ep = this.endpointChartData
 			if (ep) {
 				return ep.labels
@@ -1316,6 +1349,30 @@ export default {
 			return this.emptyLabel !== '' && !this.hasChartData
 		},
 
+		/**
+		 * The `cellSource` list as it would be asked, tokens resolved, or null
+		 * while there is none or a filter token is unresolved. Refetches when
+		 * it changes.
+		 *
+		 * @return {string|null} The key.
+		 * @spec openspec/changes/matrix-cell-records/specs/matrix-cell-records/spec.md#requirement-a-matrix-can-read-its-cells-from-records
+		 */
+		cellSourceKey() {
+			const src = this.cellSource
+			if (!src || typeof src !== 'object' || !src.register || !src.schema || !src.rowField || !src.columnField || !src.valueField) {
+				return null
+			}
+			const ctx = this.chartTokenCtx()
+			const resolve = (value) => resolveFilterTokens(value && typeof value === 'object' ? value : {}, ctx)
+			const filter = resolve(src.filter)
+			const cellFilter = resolve(src.cellFilter)
+			if (hasUnresolvedTokens(filter) || hasUnresolvedTokens(cellFilter)) {
+				return null
+			}
+			const fallbackFilter = src.fallbackFilter ? resolve(src.fallbackFilter) : null
+			return JSON.stringify({ register: src.register, schema: src.schema, filter, fallbackFilter, cellFilter, limit: src.cellsPath ? 1 : (src.limit || 500) })
+		},
+
 		/**
 		 * The rows of a `bar-list`: the categories of the first displayed
 		 * series, each with its value's share of `barMax` (or the largest
@@ -1370,6 +1427,13 @@ export default {
 					cells: columns.map((column, index) => {
 						const raw = Array.isArray(entry.data) ? entry.data[index] : undefined
 						const isCurrent = current !== null && current.row === rowIndex && current.column === index
+						const valueLabels = this.cellSource && typeof this.cellSource.valueLabels === 'object' ? this.cellSource.valueLabels : null
+						if (valueLabels && raw !== null && raw !== undefined && typeof valueLabels[String(raw)] === 'string') {
+							const label = valueLabels[String(raw)]
+							const tone = map[String(raw)] || map[label]
+							const level = TONE_LEVELS[tone] ?? 0
+							return { text: this.hostTranslate(label), level: level || 'tone', color: level ? '' : (tone || ''), current: isCurrent }
+						}
 						if (typeof raw === 'string') {
 							const tone = map[raw]
 							const level = TONE_LEVELS[tone] ?? 0
@@ -1409,7 +1473,8 @@ export default {
 			const series = Array.isArray(this.plottedSeries) ? this.plottedSeries : []
 			const rowIndex = series.findIndex((entry, i) => entry && (String(entry.key ?? '') === row || String(entry.name ?? '') === row || String(i + 1) === row))
 			const columns = Array.isArray(this.resolvedCategories) ? this.resolvedCategories.map((c) => String(c)) : []
-			const keys = Array.isArray(def.columnKeys) ? def.columnKeys.map((k) => String(k)) : []
+			const declared = Array.isArray(def.columnKeys) ? def.columnKeys : (this.cellData ? this.cellData.columnKeys : [])
+			const keys = declared.map((k) => String(k))
 			let columnIndex = keys.indexOf(column)
 			if (columnIndex < 0) {
 				columnIndex = columns.findIndex((c, i) => c === column || String(i + 1) === column)
@@ -1586,6 +1651,10 @@ export default {
 		aggregateKey() {
 			this.fetchAggregateSource()
 		},
+
+		cellSourceKey() {
+			this.fetchCells()
+		},
 	},
 
 	created() {
@@ -1597,6 +1666,7 @@ export default {
 		this.fetchGroupBy()
 		this.fetchTimeBucket()
 		this.fetchAggregateSource()
+		this.fetchCells()
 		// Subscribe to the widget Refresh bus (B3 event-bus opt-in mode)
 		// FIRST, before the ResizeObserver early-return — environments
 		// without ResizeObserver (jsdom) must still get the subscription.
@@ -1753,6 +1823,7 @@ export default {
 				this.fetchGroupBy(),
 				this.fetchTimeBucket(),
 				this.fetchAggregateSource(),
+				this.fetchCells(),
 			])
 		},
 
@@ -1973,6 +2044,39 @@ export default {
 			}
 		},
 
+		/**
+		 * Read the `cellSource` records and lay them out as the matrix: one
+		 * record per cell, or with `cellsPath` the cells inside one record. A
+		 * failed read leaves the matrix empty rather than showing stale
+		 * cells; an answer to an older request is dropped.
+		 *
+		 * @return {Promise<void>}
+		 * @spec openspec/changes/matrix-cell-records/specs/matrix-cell-records/spec.md#requirement-a-matrix-can-read-its-cells-from-records
+		 * @spec openspec/changes/matrix-cell-records/specs/matrix-cell-records/spec.md#requirement-a-matrix-can-read-its-cells-from-one-record
+		 */
+		async fetchCells() {
+			const key = this.cellSourceKey
+			if (key === null) {
+				this.cellData = null
+				return
+			}
+			const { register, schema, filter, fallbackFilter, cellFilter, limit } = JSON.parse(key)
+			this._cellRequest = key
+			let records = await fetchReferenceObjects({ register, schema, filter, limit }).catch(() => [])
+			if (this.cellSource.cellsPath && records.length === 0 && fallbackFilter) {
+				records = await fetchReferenceObjects({ register, schema, filter: fallbackFilter, limit }).catch(() => [])
+			}
+			if (this._cellRequest !== key) {
+				return
+			}
+			if (this.cellSource.cellsPath) {
+				const { cells, config } = cellsFromRecord(records[0] || null, this.cellSource, cellFilter)
+				this.cellData = pivotCells(cells, config)
+				return
+			}
+			this.cellData = pivotCells(records, this.cellSource)
+		},
+
 		/**
 		 * Resolve the OBJECT-form `dataSource.aggregate` (Wave 3, #91) into
 		 * chart data: a categorical group-by over the schema's objects with