@conduction/nextcloud-vue 2.58.0 → 2.60.0

package/src/components/CnNextStepCard/CnNextStepCard.vue

@@ -0,0 +1,319 @@
+<!--
+  - SPDX-FileCopyrightText: 2026 Conduction B.V.
+  - SPDX-License-Identifier: EUPL-1.2
+-->
+
+<template>
+	<section
+		v-if="normalisedItems.length > 0"
+		class="cn-next-step-card"
+		data-testid="cn-next-step-card"
+		:aria-labelledby="title ? titleId : null"
+		:aria-label="title ? null : fallbackLabel">
+		<div class="cn-next-step-card__main">
+			<component
+				:is="titleTag"
+				v-if="title"
+				:id="titleId"
+				class="cn-next-step-card__title">
+				{{ title }}
+			</component>
+			<ul class="cn-next-step-card__list">
+				<li
+					v-for="(item, index) in normalisedItems"
+					:key="`${index}-${item.label}`"
+					class="cn-next-step-card__item"
+					:class="{
+						'cn-next-step-card__item--done': item.done,
+						'cn-next-step-card__item--current': index === currentIndex,
+					}"
+					data-testid="cn-next-step-item">
+					<span class="cn-next-step-card__marker" aria-hidden="true">
+						<Check v-if="item.done" :size="14" />
+					</span>
+					<span class="cn-next-step-card__label">{{ item.label }}</span>
+					<span v-if="item.hint" class="cn-next-step-card__hint">{{ item.hint }}</span>
+					<!-- The state in words. The marker is a shape and a colour, and
+					     neither reaches a screen reader or a reader who cannot tell
+					     the two colours apart. -->
+					<span class="cn-next-step-card__state">{{ item.done ? doneLabel : todoLabel }}</span>
+				</li>
+			</ul>
+		</div>
+		<div v-if="actionLabel || $slots.action || after" class="cn-next-step-card__side">
+			<!-- @slot action Replace the primary button, for a host that renders its own control. -->
+			<slot name="action">
+				<NcButton
+					v-if="actionLabel"
+					:id="actionId || null"
+					variant="primary"
+					:disabled="actionDisabled"
+					data-testid="cn-next-step-action"
+					@click="$emit('action')">
+					{{ actionLabel }}
+				</NcButton>
+			</slot>
+			<span v-if="after" class="cn-next-step-card__after">{{ after }}</span>
+		</div>
+	</section>
+</template>
+
+<script>
+import { translate as t } from '@nextcloud/l10n'
+import { NcButton } from '@nextcloud/vue'
+import Check from 'vue-material-design-icons/Check.vue'
+
+let nextStepCardUid = 0
+
+/**
+ * CnNextStepCard: what this record needs now, next to the button that does it.
+ *
+ * A short checklist for the current step and one primary action. It answers
+ * "what do I do next?" on a record whose menu would otherwise make the handler
+ * guess. Renders nothing when there is no checklist, so a step that needs no
+ * explaining shows no empty card.
+ *
+ * ```vue
+ * <CnNextStepCard
+ *   title="What now? Step 2: handling"
+ *   :items="[
+ *     { label: 'Receipt confirmed', done: true },
+ *     { label: 'Review the open documents', hint: '2 of 5 done' },
+ *     { label: 'Draft the decision' },
+ *   ]"
+ *   action-label="Continue reviewing"
+ *   after="Then: step 3, decision"
+ *   @action="onContinue" />
+ * ```
+ *
+ * CnDetailPage renders this card from its `nextStep` config, and the
+ * `next-step` detail widget type renders it inside a grid.
+ */
+export default {
+	name: 'CnNextStepCard',
+
+	components: {
+		Check,
+		NcButton,
+	},
+
+	props: {
+		/** Heading of the card, for example "What now? Step 2: handling". */
+		title: {
+			type: String,
+			default: '',
+		},
+
+		/** Element the heading renders as. Pick the level that fits the page outline. */
+		titleTag: {
+			type: String,
+			default: 'h3',
+		},
+
+		/**
+		 * The checklist: `{ label, done?, hint? }` per item. The first item
+		 * that is not done is emphasised as the one to pick up now.
+		 */
+		items: {
+			type: Array,
+			default: () => [],
+		},
+
+		/** Label of the primary button. Empty renders no button. */
+		actionLabel: {
+			type: String,
+			default: '',
+		},
+
+		/** DOM id for the primary button, so a skip link can land on it. */
+		actionId: {
+			type: String,
+			default: '',
+		},
+
+		/** Disable the primary button, for example while its request is in flight. */
+		actionDisabled: {
+			type: Boolean,
+			default: false,
+		},
+
+		/** One line under the button saying what follows, for example "Then: step 3, decision". */
+		after: {
+			type: String,
+			default: '',
+		},
+
+		/** Text state of a done item, read by screen readers. */
+		doneLabel: {
+			type: String,
+			default: () => t('nextcloud-vue', 'Done'),
+		},
+
+		/** Text state of an open item, read by screen readers. */
+		todoLabel: {
+			type: String,
+			default: () => t('nextcloud-vue', 'To do'),
+		},
+	},
+
+	emits: [
+		/** The primary button was pressed. */
+		'action',
+	],
+
+	data() {
+		nextStepCardUid += 1
+		return {
+			titleId: `cn-next-step-title-${nextStepCardUid}`,
+		}
+	},
+
+	computed: {
+		/**
+		 * The items that can render: an object with a label.
+		 *
+		 * @return {Array<{label: string, done: boolean, hint: string}>} The checklist.
+		 * @spec openspec/changes/detail-action-model-and-case-surfaces/specs/detail-action-model/spec.md#requirement-next-step-card
+		 */
+		normalisedItems() {
+			return (Array.isArray(this.items) ? this.items : [])
+				.filter((item) => item && typeof item.label === 'string' && item.label !== '')
+				.map((item) => ({
+					label: item.label,
+					done: item.done === true,
+					hint: typeof item.hint === 'string' ? item.hint : '',
+				}))
+		},
+
+		/**
+		 * Index of the first open item, the one to pick up now.
+		 *
+		 * @return {number} The index, or -1 when everything is done.
+		 * @spec openspec/changes/detail-action-model-and-case-surfaces/specs/detail-action-model/spec.md#requirement-next-step-card
+		 */
+		currentIndex() {
+			return this.normalisedItems.findIndex((item) => !item.done)
+		},
+
+		/**
+		 * Accessible name for a card without a title.
+		 *
+		 * @return {string} The label.
+		 * @spec openspec/changes/detail-action-model-and-case-surfaces/specs/detail-action-model/spec.md#requirement-next-step-card
+		 */
+		fallbackLabel() {
+			return t('nextcloud-vue', 'Next step')
+		},
+	},
+}
+</script>
+
+<style scoped>
+.cn-next-step-card {
+	align-items: center;
+	background: var(--color-main-background);
+	border: 1px solid var(--color-border);
+	border-radius: var(--border-radius-large);
+	/* The edge says "this is the thing to act on". An inset shadow, so it
+	   follows the card's rounded corners instead of squaring them off. */
+	box-shadow: inset 4px 0 0 var(--color-primary-element);
+	display: flex;
+	flex-wrap: wrap;
+	gap: calc(4 * var(--default-grid-baseline)) calc(8 * var(--default-grid-baseline));
+	padding: calc(5 * var(--default-grid-baseline)) calc(6 * var(--default-grid-baseline));
+	padding-inline-start: calc(7 * var(--default-grid-baseline));
+}
+
+.cn-next-step-card__main {
+	display: flex;
+	flex: 1 1 420px;
+	flex-direction: column;
+	gap: calc(2.5 * var(--default-grid-baseline));
+	min-width: 0;
+}
+
+.cn-next-step-card__title {
+	color: var(--color-main-text);
+	font-size: 0.85em;
+	font-weight: 700;
+	letter-spacing: 0.06em;
+	margin: 0;
+	text-transform: uppercase;
+}
+
+.cn-next-step-card__list {
+	display: grid;
+	gap: calc(2 * var(--default-grid-baseline));
+	list-style: none;
+	margin: 0;
+	padding: 0;
+}
+
+.cn-next-step-card__item {
+	align-items: center;
+	color: var(--color-text-maxcontrast);
+	display: flex;
+	flex-wrap: wrap;
+	gap: calc(2.5 * var(--default-grid-baseline));
+}
+
+.cn-next-step-card__item--current {
+	color: var(--color-main-text);
+}
+
+.cn-next-step-card__item--current .cn-next-step-card__label {
+	font-weight: 700;
+}
+
+.cn-next-step-card__marker {
+	align-items: center;
+	border: 2px solid var(--color-border-maxcontrast);
+	border-radius: 50%;
+	box-sizing: border-box;
+	display: inline-flex;
+	flex: none;
+	height: 20px;
+	justify-content: center;
+	width: 20px;
+}
+
+.cn-next-step-card__item--current .cn-next-step-card__marker {
+	border-color: var(--color-primary-element);
+}
+
+.cn-next-step-card__item--done .cn-next-step-card__marker {
+	background: var(--color-primary-element);
+	border-color: var(--color-primary-element);
+	color: var(--color-primary-element-text);
+}
+
+.cn-next-step-card__hint {
+	color: var(--color-text-maxcontrast);
+	font-weight: 400;
+}
+
+/* Read, not seen. */
+.cn-next-step-card__state {
+	border: 0;
+	clip-path: inset(50%);
+	height: 1px;
+	margin: -1px;
+	overflow: hidden;
+	padding: 0;
+	position: absolute;
+	white-space: nowrap;
+	width: 1px;
+}
+
+.cn-next-step-card__side {
+	align-items: flex-start;
+	display: flex;
+	flex-direction: column;
+	gap: calc(2 * var(--default-grid-baseline));
+}
+
+.cn-next-step-card__after {
+	color: var(--color-text-maxcontrast);
+	font-size: 0.9em;
+}
+</style>

package/src/components/CnNextStepCard/CnNextStepWidget.vue

@@ -0,0 +1,59 @@
+<!--
+  - SPDX-FileCopyrightText: 2026 Conduction B.V.
+  - SPDX-License-Identifier: EUPL-1.2
+-->
+
+<template>
+	<CnNextStepCard
+		v-if="step"
+		:title="step.title"
+		:items="step.items"
+		:after="step.after" />
+</template>
+
+<script>
+import CnNextStepCard from './CnNextStepCard.vue'
+import { resolveNextStep } from '../../utils/detailActionModel.js'
+
+/**
+ * CnNextStepWidget: the `next-step` detail widget type.
+ *
+ * Renders CnNextStepCard for the bound record's stage from
+ * `content: { field?, stages: { <stage>: { title?, checklist, after? } } }`.
+ * The checklist only: the page's own primary button stays where the page
+ * puts it. Resolved by its registry key, not exported.
+ */
+export default {
+	name: 'CnNextStepWidget',
+
+	components: {
+		CnNextStepCard,
+	},
+
+	props: {
+		/** The widget's content: `{ field?, title?, stages }`. */
+		content: {
+			type: Object,
+			default: () => ({}),
+		},
+
+		/** The bound record. */
+		objectData: {
+			type: Object,
+			default: null,
+		},
+	},
+
+	computed: {
+		/**
+		 * The card for the record's stage.
+		 *
+		 * @return {object|null} The resolved card, or null when the stage declares none.
+		 * @spec openspec/changes/detail-action-model-and-case-surfaces/specs/detail-action-model/spec.md#requirement-next-step-card
+		 */
+		step() {
+			return resolveNextStep(this.content, this.objectData)
+		},
+	},
+}
+</script>

package/src/components/CnNextStepCard/index.js

@@ -0,0 +1,4 @@
+import CnNextStepCard from './CnNextStepCard.vue'
+
+export default CnNextStepCard
+export { CnNextStepCard }

package/src/components/CnObjectCard/CnObjectCard.vue

@@ -2,7 +2,7 @@
 	<div
 		class="cn-object-card"
 		:class="{ 'cn-object-card--selected': selected }"
-		@mousedown="onPointerDown"
+		@mousedown="onCardMouseDown"
 		@click="onCardClick($event)"
 		@auxclick="onCardAuxClick($event)">
 		<!-- Selection checkbox -->
@@ -76,7 +76,7 @@
 import { NcCheckboxRadioSwitch } from '@nextcloud/vue'
 import { useClickDragGuard } from '../../composables/useClickDragGuard.js'
 import { resolveImageUrl } from '../../utils/resolveImageUrl.js'
-import { isRowMiddleClick } from '../../utils/rowAuxClick.js'
+import { isRowMiddleClick, preventMiddleClickAutoscroll } from '../../utils/rowAuxClick.js'
 import { formatValue } from '../../utils/schema.js'
 import { CnCellRenderer } from '../CnCellRenderer/index.js'
 import { CnLockIndicator } from '../CnLockIndicator/index.js'
@@ -161,7 +161,7 @@ export default {
 		},
 	},
 
-	emits: ['click', 'select'],
+	emits: ['click', 'select', 'aux-click'],
 
 	setup() {
 		// Tell a deliberate card click apart from a text-selection drag.
@@ -287,14 +287,28 @@ export default {
 				return
 			}
 			/**
-			 * @event click Emitted when a non-selectable (or `clickToView`) card is clicked or middle-clicked. Payload: `(object, event)` — the card's object and the native click/auxclick event, for opening it in a new tab on a ctrl/cmd/shift or middle click. Selectable cards emit `select`; they also emit `click` (deprecated) when a `click` listener is present, so migrate selectable consumers to `@select`.
+			 * @event click Emitted when a non-selectable (or `clickToView`) card is clicked. Payload: `(object, event)` — the card's object and the native click event, for opening it in a new tab on a ctrl/cmd/shift click. A middle click emits `aux-click` instead. Selectable cards emit `select`; they also emit `click` (deprecated) when a `click` listener is present, so migrate selectable consumers to `@select`.
 			 * @type {object} The card's object.
 			 */
 			this.$emit('click', this.object, event)
 		},
 
 		/**
-		 * Card-body middle click: emits `click` like a navigating click.
+		 * Card mousedown: record the press for the drag guard, and on a card a
+		 * middle click opens, keep the browser from starting autoscroll.
+		 *
+		 * @param {MouseEvent} event The mousedown event.
+		 */
+		onCardMouseDown(event) {
+			this.onPointerDown(event)
+			if (!this.selectable || this.clickToView) {
+				preventMiddleClickAutoscroll(event)
+			}
+		},
+
+		/**
+		 * Card-body middle click: emits `aux-click`, not `click`, so an existing
+		 * `click` listener that navigates never moves the current tab away.
 		 * Ignored on a select-on-click card, on nested controls and on drags.
 		 *
 		 * @param {MouseEvent} event The auxclick event.
@@ -306,7 +320,11 @@ export default {
 			if (this.selectable && !this.clickToView) {
 				return
 			}
-			this.$emit('click', this.object, event)
+			/**
+			 * @event aux-click Emitted when a non-selectable (or `clickToView`) card is middle-clicked, for opening it in a new tab (see `openRowTarget`). Payload: `(object, event)` — the card's object and the native auxclick event.
+			 * @type {object} The card's object.
+			 */
+			this.$emit('aux-click', this.object, event)
 		},
 	},
 }

package/src/components/CnObjectDataWidget/CnObjectDataWidget.vue

@@ -456,6 +456,13 @@ export default {
 		 * identity when used standalone (no CnAppRoot ancestor).
 		 */
 		cnTranslate: { default: () => (key) => key },
+		/**
+		 * Formatter registry, provided by CnAppRoot (`cnFormatters`: the
+		 * library's built-ins plus the app's `formatters`). A field override
+		 * `{ formatter: '<id>' }` renders the value through the same function a
+		 * table column with that `formatter` uses. Empty when used standalone.
+		 */
+		cnFormatters: { default: () => ({}) },
 		/**
 		 * The host surface's panel-action channel, when this widget is rendered
 		 * in a tab panel. Null everywhere else, which is every other surface.
@@ -641,6 +648,11 @@ export default {
 		 * - `editable` (boolean) — Override editability (default: based on schema readOnly)
 		 * - `label` (string) — Override the display label
 		 * - `widget` (string) — Override the widget type for editing
+		 * - `formatter` (string) — Display the value through the formatter
+		 *   registered under this id on CnAppRoot (`cnFormatters`), called as
+		 *   `(value, object, property)` like a table cell's formatter. An id
+		 *   nobody registered, or a formatter that throws, keeps the default
+		 *   rendering. Editing still writes the stored value.
 		 *
 		 * Accepts an Array too: an empty overrides map (`{}`) round-trips through
 		 * PHP/JSON as an empty Array (`[]`), so a persisted manifest can deliver
@@ -917,12 +929,46 @@ export default {
 			}
 		},
 
+		/**
+		 * Display values of the fields whose override names a registered
+		 * formatter, keyed by field key. A field is left out when its formatter
+		 * id is not registered or the formatter throws, so it falls back to the
+		 * default rendering.
+		 *
+		 * @return {Record<string, string>}
+		 */
+		formatterDisplayValues() {
+			const values = {}
+			for (const field of this.resolvedFields) {
+				const fn = field.formatter && this.cnFormatters && this.cnFormatters[field.formatter]
+				if (typeof fn !== 'function') {
+					continue
+				}
+				const raw = field.key in this.dirtyFields
+					? this.dirtyFields[field.key]
+					: (this.objectData || {})[field.key]
+				const prop = (this.schema.properties && this.schema.properties[field.key]) || {}
+				try {
+					const formatted = fn(raw, this.objectData || {}, prop)
+					values[field.key] = (formatted === null || formatted === undefined || formatted === '') ? '—' : String(formatted)
+				} catch (e) {
+					// eslint-disable-next-line no-console
+					console.warn(`[CnObjectDataWidget] formatter "${field.formatter}" threw; falling back`, e)
+				}
+			}
+			return values
+		},
+
 		/**
 		 * Formatted display values for each field.
 		 */
 		displayValues() {
 			const values = {}
 			for (const field of this.resolvedFields) {
+				if (field.key in this.formatterDisplayValues) {
+					values[field.key] = this.formatterDisplayValues[field.key]
+					continue
+				}
 				// Show pending edit value if dirty
 				const raw = field.key in this.dirtyFields
 					? this.dirtyFields[field.key]
@@ -1191,6 +1237,9 @@ export default {
 		 * @return {'object-array'|'scalar-array'|'object'|'scalar'} The value kind.
 		 */
 		fieldValueKind(field) {
+			if (field.key in this.formatterDisplayValues) {
+				return 'scalar'
+			}
 			const prop = ((this.schema && this.schema.properties) || {})[field.key]
 			if (this.isRelationField(prop)) {
 				return 'scalar'

package/src/components/CnObjectDataWidgetForm/CnObjectDataWidgetForm.vue

@@ -268,6 +268,9 @@ export default {
 					gridColumn: Number.isFinite(o.gridColumn) ? o.gridColumn : 1,
 					widget: o.widget || 'auto',
 					editable: o.editable !== false,
+					// Not edited here, but carried through, so saving the
+					// cog editor does not drop a manifest-authored formatter.
+					formatter: typeof o.formatter === 'string' ? o.formatter : '',
 				}
 			})
 		},
@@ -386,6 +389,9 @@ export default {
 				if (row.editable === false) {
 					o.editable = false
 				}
+				if (row.formatter) {
+					o.formatter = row.formatter
+				}
 				if (Object.keys(o).length) {
 					out[row.key] = o
 				}

package/src/components/CnObjectKanban/CnObjectKanban.vue

@@ -50,11 +50,27 @@
 					<template #item="{ element: card }">
 						<div
 							class="cn-object-kanban__card"
-							:class="{ 'cn-object-kanban__card--pending': isPending(card) }">
+							:class="{
+								'cn-object-kanban__card--pending': isPending(card),
+								'cn-object-kanban__card--overdue': dueState(card) === 'overdue',
+								'cn-object-kanban__card--soon': dueState(card) === 'soon',
+							}">
 							<!-- @slot card Fully replace the default card rendering. -->
 							<!-- @binding {object} object The card's object. -->
 							<!-- @binding {object} column The column the card currently sits in. -->
-							<slot name="card" :object="card" :column="column">
+							<!-- @binding {string|null} dueState The card's due state under `dueRule`: `overdue`, `soon`, `ok`, or null without a rule. -->
+							<slot
+								name="card"
+								:object="card"
+								:column="column"
+								:dueState="dueState(card)">
+								<span
+									v-if="dueLabel(card)"
+									class="cn-object-kanban__due"
+									:class="`cn-object-kanban__due--${dueState(card)}`"
+									data-testid="cn-kanban-due">
+									{{ dueLabel(card) }}
+								</span>
 								<div class="cn-object-kanban__card-title" @click="onCardClick(card)">
 									{{ cardTitle(card) }}
 								</div>
@@ -92,6 +108,7 @@ import { translate as t } from '@nextcloud/l10n'
 import { NcButton, NcEmptyContent, NcLoadingIcon } from '@nextcloud/vue'
 import draggable from 'vuedraggable'
 import ViewColumn from 'vue-material-design-icons/ViewColumn.vue'
+import { dueStateForRow } from '../../utils/dueRule.js'
 import { CnCellRenderer } from '../CnCellRenderer/index.js'
 
 /**
@@ -225,6 +242,22 @@ export default {
 			type: String,
 			default: 'id',
 		},
+
+		/**
+		 * Marks late cards: `{ field, soonDays? }`. `field` is the dot-path to
+		 * a card's due date. A date before today gets an error edge and the
+		 * label "Overdue"; a date within `soonDays` (default 3) gets "Due
+		 * soon" in the warning colour. `null` (the default) marks nothing.
+		 *
+		 * The same rule shape the table's date cell uses, so a list and its
+		 * board agree on what late means.
+		 *
+		 * @type {{field: string, soonDays?: number}|null}
+		 */
+		dueRule: {
+			type: Object,
+			default: null,
+		},
 	},
 
 	emits: ['card-click', 'load-more', 'move', 'move-rejected'],
@@ -240,6 +273,8 @@ export default {
 			// objectId -> { fromValue, toValue, card, originIndex }
 			pendingMoves: {},
 			dragOriginValue: null,
+			// The day late marking measures from.
+			today: new Date(),
 		}
 	},
 
@@ -294,6 +329,33 @@ export default {
 	methods: {
 		t,
 
+		/**
+		 * A card's due state under `dueRule`.
+		 *
+		 * @param {object} card The card's row.
+		 * @return {'overdue'|'soon'|'ok'|null} The state, or null when no rule applies.
+		 * @spec openspec/changes/detail-action-model-and-case-surfaces/specs/detail-action-model/spec.md#requirement-late-marking-on-board-cards
+		 */
+		dueState(card) {
+			return dueStateForRow(card, this.dueRule, this.today)
+		},
+
+		/**
+		 * The words a late card carries. Colour alone would not reach a reader
+		 * who cannot see it, or cannot tell red from amber.
+		 *
+		 * @param {object} card The card's row.
+		 * @return {string} "Overdue", "Due soon", or '' for a card that is fine.
+		 * @spec openspec/changes/detail-action-model-and-case-surfaces/specs/detail-action-model/spec.md#requirement-late-marking-on-board-cards
+		 */
+		dueLabel(card) {
+			const state = this.dueState(card)
+			if (state === 'overdue') {
+				return t('nextcloud-vue', 'Overdue')
+			}
+			return state === 'soon' ? t('nextcloud-vue', 'Due soon') : ''
+		},
+
 		/**
 		 * Rebuild `localColumns` from either the `columns` prop (backend-paginated
 		 * mode) or `objects` + `groupByField` (locally-derived mode).
@@ -703,6 +765,28 @@ export default {
 	opacity: 0.6;
 }
 
+/* A late card. The label carries the meaning; the edge helps a sighted
+   reader find it. An inset shadow, so the card keeps its size. */
+.cn-object-kanban__card--overdue {
+	border-color: var(--color-error);
+	box-shadow: inset 3px 0 0 var(--color-error);
+}
+
+.cn-object-kanban__due {
+	display: block;
+	font-size: 0.85em;
+	font-weight: 700;
+}
+
+.cn-object-kanban__due--overdue {
+	color: var(--color-error-text, var(--color-error));
+}
+
+.cn-object-kanban__due--soon {
+	color: var(--color-warning-text, var(--color-main-text));
+	font-weight: 600;
+}
+
 .cn-object-kanban__card-title {
 	font-weight: 500;
 	cursor: pointer;