@conduction/nextcloud-vue 2.79.0 → 2.81.0

package/src/components/CnStagesWidget/CnStagesWidget.vue

@@ -178,8 +178,10 @@ import {
 	readAvailableActions,
 	transitionError,
 } from '../../composables/useLifecycleTransitions.js'
+import { normalizeLook } from '../../composables/useLook.js'
 import { useObjectStore } from '../../store/useObjectStore.js'
 import { resolveObjectOpType } from '../../utils/actionsDispatcher.js'
+import { formatBoardDate } from '../../utils/boardDate.js'
 import { resolveObjectTokenContext } from '../../utils/detailObjectContext.js'
 import {
 	dropOptionalUnresolved,
@@ -264,6 +266,14 @@ function userError(message) {
  *   labelField?, descriptionField?, finalField?, limit? }`, an OpenRegister
  *   query whose filter takes the same tokens.
  *
+ * `datesSource`: `{ url, method?, params?, path?, idField?, dateField? }`, an
+ * endpoint (same token grammar) answering the date the record reached each
+ * stage, when the stage list does not carry it: the case type's statuses list
+ * the steps, `/blueprint?case=@objectId` says when this case reached them.
+ * Read once, merged into the steps by `idField` (default `id`) with the value
+ * at `dateField` (default `reachedAt`); a date it does not give falls back to
+ * the stage list's own `dateField`. The bars variant draws it.
+ *
  * `finalField` marks the stages that close the record, which the timeline
  * draws differently. It grants nothing either.
  *
@@ -356,7 +366,7 @@ export default {
 		 * `label`, the placement's own title, so a titled card does not have to
 		 * repeat itself, and then to "Stages".
 		 *
-		 * @type {{currentField?: string, stagesEndpoint?: object, stagesSource?: object, transition?: object, unreachableReason?: string, orientation?: ('horizontal'|'vertical'), size?: ('medium'|'small'), ariaLabel?: string, label?: string, variant?: ('dots'|'bars')}}
+		 * @type {{currentField?: string, stagesEndpoint?: object, stagesSource?: object, transition?: object, unreachableReason?: string, orientation?: ('horizontal'|'vertical'), size?: ('medium'|'small'), ariaLabel?: string, label?: string, variant?: ('dots'|'bars'), datesSource?: {url: string, method?: string, params?: object, path?: string, idField?: string, dateField?: string}}}
 		 */
 		content: {
 			type: Object,
@@ -437,6 +447,8 @@ export default {
 		const workspaceRaw = inject('cnWorkspaceContext', ref({}))
 		const appConfigRaw = inject('cnAppConfig', ref({}))
 		const cnTranslate = inject('cnTranslate', (key) => key)
+		// The app's look (`nextcloud` or `board`), provided by CnAppRoot or CnPageRenderer.
+		const cnLook = inject('cnLook', 'nextcloud')
 
 		/**
 		 * The token context: the bound record, its id, and the page context.
@@ -462,15 +474,24 @@ export default {
 			return (cfg && cfg.url) ? { url: cfg.url, method: cfg.method, params: cfg.params } : null
 		}, { ctx: tokenCtx })
 
+		// The dates the record reached each stage, when they live apart from
+		// the stage list (`datesSource`): one read, merged into the steps by id.
+		const datesRead = useEndpointSource(() => {
+			const cfg = props.content?.datesSource
+			return (cfg && cfg.url) ? { url: cfg.url, method: cfg.method, params: cfg.params } : null
+		}, { ctx: tokenCtx })
+
 		return {
 			detailCtxRaw,
 			objectCtxRaw,
 			cnTranslate,
+			cnLook,
 			tokenCtx,
 			stagesBody: stagesRead.data,
 			stagesBodyLoading: stagesRead.loading,
 			stagesBodyError: stagesRead.error,
 			stagesBodyBlocked: stagesRead.blocked,
+			datesBody: datesRead.data,
 		}
 	},
 
@@ -614,6 +635,42 @@ export default {
 			return normalizeStages(rows, { ...cfg, orderField })
 		},
 
+		/**
+		 * The reached dates by stage id, from `datesSource`: the rows at its
+		 * `path` (or the response itself when it is a list), keyed by
+		 * `idField` (default `id`), the value at `dateField` (default
+		 * `reachedAt`). Empty without the option, while it loads, or when it
+		 * failed: the steps then show the stage list's own dates.
+		 *
+		 * @return {{[id: string]: string}} Date by stage id.
+		 * @spec openspec/changes/screens-stage-dates-source/specs/stage-dates-source/spec.md#requirement-the-reached-dates-can-come-from-their-own-endpoint
+		 */
+		stageDates() {
+			const cfg = this.content.datesSource
+			const body = this.datesBody
+			if (!cfg || !cfg.url || body === null || body === undefined) {
+				return {}
+			}
+			const rows = Array.isArray(body) ? body : getByPath(body, cfg.path || '')
+			if (!Array.isArray(rows)) {
+				return {}
+			}
+			const idField = cfg.idField || 'id'
+			const dateField = cfg.dateField || 'reachedAt'
+			const out = {}
+			for (const row of rows) {
+				if (!row || typeof row !== 'object') {
+					continue
+				}
+				const id = getByPath(row, idField)
+				const date = getByPath(row, dateField)
+				if (id !== null && id !== undefined && id !== '' && typeof date === 'string' && date !== '') {
+					out[String(id)] = date
+				}
+			}
+			return out
+		},
+
 		/**
 		 * Whether the stage list is still on its way.
 		 *
@@ -795,7 +852,7 @@ export default {
 				}
 				return {
 					...stage,
-					date: this.stages[index]?.date || '',
+					date: this.barDate(this.stageDates[stage.id] || this.stages[index]?.date || '', state),
 					state,
 					clickable: this.interactive && state !== 'current',
 				}
@@ -891,6 +948,28 @@ export default {
 	},
 
 	methods: {
+		/**
+		 * A bar's date line. Under the board look a date value reads in the
+		 * board's short form ("3 okt"), and the current step's reads "sinds
+		 * 4 okt", as DqZaak draws it. Any other value, and every value outside
+		 * the board look, shows as written.
+		 *
+		 * @param {string} value The `dateField` value of the stage row.
+		 * @param {string} state The bar state (`done`, `current`, `todo`).
+		 * @return {string} The date line, or ''.
+		 * @spec openspec/changes/screens-stage-bar-dates-parity/specs/stage-bar-dates/spec.md#requirement-a-bar-date-reads-as-the-board-draws-it
+		 */
+		barDate(value, state) {
+			if (!value || normalizeLook(this.cnLook) !== 'board') {
+				return value
+			}
+			const short = formatBoardDate(value)
+			if (short === '') {
+				return value
+			}
+			return state === 'current' ? t('nextcloud-vue', 'since {date}', { date: short }) : short
+		},
+
 		/**
 		 * Translate a library string.
 		 *

package/src/components/CnStatWidget/CnStatWidget.vue

@@ -46,7 +46,7 @@
 					aria-hidden="true">
 					<CnWidgetIcon :name="resolvedIcon" :size="18" />
 				</span>
-				<span v-if="content.label" :title="resolvedLabel">{{ resolvedLabel }}</span>
+				<span v-if="content.label" class="cn-kpi-card__title-text" :title="resolvedLabel">{{ resolvedLabel }}</span>
 
 				<!-- Per-tile range override. Rendered ONLY when the tile declares its
 				     own `content.dateRange.presets`; a tile that merely follows the
@@ -163,6 +163,7 @@ import widgetLink from '../../mixins/widgetLink.js'
 import { useObjectStore } from '../../store/useObjectStore.js'
 import { resolveObjectOpType } from '../../utils/actionsDispatcher.js'
 import { resolveObjectTokenContext } from '../../utils/detailObjectContext.js'
+import { fetchListTotal, needsListEndpoint } from '../../utils/fetchFilterCounts.js'
 import { formatMetricValue, unwrapAppConfig } from '../../utils/formatMetric.js'
 import { dropOptionalUnresolved, resolveFilterTokens } from '../../utils/resolveFilterTokens.js'
 import { STATUS_TEXT_COLORS } from '../../utils/statusColors.js'
@@ -1746,8 +1747,7 @@ export default {
 			// drop any optional `@workspace.<key>?` / `@config.<key>?` that stayed
 			// unresolved so an unset value omits the filter (show all) instead of
 			// sending a literal token.
-			const ctx = { ...(this.objectCtx || {}), workspace: this.pageCtx, config: this.configCtx }
-			filter = dropOptionalUnresolved(resolveFilterTokens(filter, ctx))
+			filter = this.resolveSourceFilter(filter)
 			for (const [k, v] of Object.entries(filter)) {
 				if (v && typeof v === 'object') {
 					for (const [op, ov] of Object.entries(v)) {
@@ -1759,6 +1759,21 @@ export default {
 			}
 		},
 
+		/**
+		 * A source filter with its @-tokens resolved against the object, page
+		 * and config contexts, and unresolved optional clauses dropped.
+		 *
+		 * @param {object} filter The raw filter map.
+		 * @return {object} The resolved filter.
+		 */
+		resolveSourceFilter(filter) {
+			if (!filter || typeof filter !== 'object') {
+				return {}
+			}
+			const ctx = { ...(this.objectCtx || {}), workspace: this.pageCtx, config: this.configCtx }
+			return dropOptionalUnresolved(resolveFilterTokens(filter, ctx))
+		},
+
 		/**
 		 * Fetch one scalar from the OpenRegister `/value` aggregation endpoint.
 		 *
@@ -1768,9 +1783,19 @@ export default {
 		 * @param {string} metric The aggregation metric.
 		 * @param {?string} field The numeric field (non-count metrics).
 		 * @param {object} filter The filter map.
+		 * @param {string} [via] `"list"` counts through the list endpoint's total.
 		 * @return {Promise<number|null>} The aggregated value.
 		 */
-		async fetchAggregate(axios, generateUrl, s, metric, field, filter) {
+		async fetchAggregate(axios, generateUrl, s, metric, field, filter, via) {
+			// A count the aggregation endpoint cannot express (a filter holding a
+			// list of values, a test for no value (`null` or `{ isnull: true }`),
+			// or `via: "list"`) reads the list endpoint's total instead, because
+			// the aggregation endpoint has no null operator.
+			const resolved = this.resolveSourceFilter(filter)
+			const listed = Object.values(resolved).some((v) => Array.isArray(v) || (v && typeof v === 'object' && Object.values(v).some(Array.isArray)))
+			if ((!metric || metric === 'count') && (via === 'list' || listed || needsListEndpoint(resolved))) {
+				return fetchListTotal(s.register, s.schema, resolved, {})
+			}
 			const url = generateUrl(
 				'/apps/openregister/api/objects/aggregations/{register}/{schema}/value',
 				{ register: s.register, schema: s.schema },
@@ -1827,9 +1852,15 @@ export default {
 				if (s.kind === 'endpoint') {
 					this.value = await this.fetchEndpoint(s, refresh)
 				} else if (s.kind === 'ratio') {
-					const num = await this.fetchAggregate(axios, generateUrl, s, s.metric, s.field, (s.numerator && s.numerator.filter) || {})
-					const den = await this.fetchAggregate(axios, generateUrl, s, s.metric, s.field, (s.denominator && s.denominator.filter) || {})
+					// Each part may name its own metric, field and `via`, so "answered
+					// in time" over "answered" is two counts, and a share of a sum is
+					// two sums.
+					const part = (p) => this.fetchAggregate(axios, generateUrl, s, (p && p.metric) || s.metric, (p && p.field) || s.field, (p && p.filter) || {}, (p && p.via) || s.via)
+					const num = await part(s.numerator)
+					const den = await part(s.denominator)
 					this.value = (den && Number(den) !== 0) ? (Number(num) / Number(den)) * 100 : null
+				} else if (s.kind === 'elapsed') {
+					this.value = await this.fetchElapsed(axios, generateUrl, s)
 				} else if (s.kind === 'computed') {
 					// Fetch each named part, then evaluate the formula over them.
 					const { evalFormula } = await import('../../utils/evalFormula.js')
@@ -1842,7 +1873,7 @@ export default {
 				} else if (s.kind === 'weighted') {
 					this.value = await this.fetchWeighted(axios, generateUrl, s)
 				} else {
-					this.value = await this.fetchAggregate(axios, generateUrl, s, s.metric, s.field, s.filter || {})
+					this.value = await this.fetchAggregate(axios, generateUrl, s, s.metric, s.field, s.filter || {}, s.via)
 				}
 			} catch (e) {
 				this.error = (e && e.message) || 'error'
@@ -1852,6 +1883,56 @@ export default {
 			}
 		},
 
+		/**
+		 * The average time between two date fields of the matching objects
+		 * (`{ from, to, unit?, filter?, limit? }`): an average answer time is
+		 * `occurredAt` to `resolvedAt`. Computed client-side over the fetched
+		 * objects (capped at `limit`, default 1000), because the aggregation
+		 * endpoint averages one numeric field, not a difference. Objects missing
+		 * either date, or with `to` before `from`, are left out; null when none
+		 * is left. `unit` is `days` (default), `hours` or `minutes`.
+		 *
+		 * @param {object} axios The axios instance.
+		 * @param {(url: string, params?: object) => string} generateUrl The router helper.
+		 * @param {object} s The elapsed source.
+		 * @return {Promise<number|null>} The average, in `unit`.
+		 * @spec openspec/changes/screens-ratio-stat/specs/ratio-stat/spec.md#requirement-a-stat-can-average-the-time-between-two-dates
+		 */
+		async fetchElapsed(axios, generateUrl, s) {
+			if (!s.from || !s.to) {
+				return null
+			}
+			const url = generateUrl(
+				'/apps/openregister/api/objects/{register}/{schema}',
+				{ register: s.register, schema: s.schema },
+			)
+			const params = { _limit: s.limit || 1000 }
+			const filter = this.resolveSourceFilter(s.filter || {})
+			for (const [k, v] of Object.entries(filter)) {
+				if (v && typeof v === 'object' && !Array.isArray(v)) {
+					for (const [op, operand] of Object.entries(v)) {
+						params[`${k}[${op}]`] = operand
+					}
+				} else if (v !== '' && v !== null && v !== undefined) {
+					params[k] = v
+				}
+			}
+			const res = await axios.get(url, { params })
+			const rows = (res && res.data && res.data.results) || []
+			const per = { minutes: 60000, hours: 3600000, days: 86400000 }[s.unit] || 86400000
+			let sum = 0
+			let n = 0
+			for (const r of rows) {
+				const from = Date.parse(r && r[s.from])
+				const to = Date.parse(r && r[s.to])
+				if (Number.isFinite(from) && Number.isFinite(to) && to >= from) {
+					sum += (to - from) / per
+					n += 1
+				}
+			}
+			return n > 0 ? sum / n : null
+		},
+
 		/**
 		 * Compute a weighted sum `Σ (field × weightField) ÷ divisor` client-side
 		 * (no OpenRegister expression-aggregation primitive yet). Pulls the

package/src/components/CnStatsBlockWidget/CnStatsBlockWidget.vue

@@ -17,10 +17,42 @@
 <template>
 	<div
 		class="cn-stats-block-widget"
-		:class="[iconClass, { 'cn-stats-block-widget--multi': hasEntries }]">
+		:class="[iconClass, { 'cn-stats-block-widget--multi': hasEntries && !isRows, 'cn-stats-block-widget--rows': isRows }]">
+		<!-- Rows layout: a title and one label-left, number-right row per entry
+		     (the board's "Mijn Zuiddrecht nu" card). -->
+		<template v-if="isRows">
+			<h2 v-if="title" class="cn-stats-block-widget__rows-title" data-testid="cn-stats-block-rows-title">
+				{{ tl(title) }}
+			</h2>
+			<dl class="cn-stats-block-widget__rows" data-testid="cn-stats-block-rows">
+				<div
+					v-for="view in rowViews"
+					:key="view.key"
+					class="cn-stats-block-widget__row"
+					data-testid="cn-stats-block-row">
+					<dt class="cn-stats-block-widget__row-label">
+						<a
+							v-if="view.href"
+							:href="view.href"
+							data-testid="cn-stats-block-row-link"
+							@click="onRowClick($event, view.route)">{{ view.label }}</a>
+						<template v-else>
+							{{ view.label }}
+						</template>
+					</dt>
+					<dd
+						class="cn-stats-block-widget__row-value"
+						:class="'cn-stats-block-widget__row-value--' + view.variant"
+						data-testid="cn-stats-block-row-value">
+						{{ view.display }}
+					</dd>
+				</div>
+			</dl>
+		</template>
+
 		<!-- Multi-entry mode: one KPI per entry, all inside this widget card.
 		     An entry with hideWhenZero whose resolved count is 0 is omitted. -->
-		<template v-if="hasEntries">
+		<template v-else-if="hasEntries">
 			<CnStatsBlock
 				v-for="view in entryViews"
 				:key="view.key"
@@ -71,6 +103,7 @@ import { subscribe, unsubscribe } from '@nextcloud/event-bus'
 import CnStatsBlock from '../CnStatsBlock/CnStatsBlock.vue'
 import { useDataSource } from '../../composables/useDataSource.js'
 import { formatMetricValue, normalizeMetricFormat, unwrapAppConfig } from '../../utils/formatMetric.js'
+import { followLinkClick, resolveHref } from '../../utils/linkNavigation.js'
 import { dropOptionalUnresolved, hasUnresolvedTokens, resolveFilterTokens } from '../../utils/resolveFilterTokens.js'
 
 // The canonical KPI scale (`--cn-kpi-*`) lives in one stylesheet. Imported
@@ -167,6 +200,8 @@ export default {
 		 * currency (`currency`) and `@config.<key>` tokens in `format`.
 		 */
 		cnAppConfig: { default: () => ({}) },
+		/** The host's label lookup (CnAppRoot provides it); identity without one. */
+		cnTranslate: { default: () => (key) => key },
 	},
 
 	props: {
@@ -264,7 +299,10 @@ export default {
 
 		/**
 		 * `stacked` gives every block the board look (see CnStatsBlock
-		 * `layout`). Empty (the default) keeps the KPI card.
+		 * `layout`). `rows` draws the title and then one row per entry (or the
+		 * single source): the label on the left, the number on the right, the
+		 * label a link when the entry has a `route`. Empty (the default) keeps
+		 * the KPI card.
 		 *
 		 * @spec openspec/changes/zuiddrecht-pixel-gaps-3/specs/zuiddrecht-pixel-gaps-3/spec.md#requirement-a-stats-block-can-take-the-stacked-board-look
 		 */
@@ -353,6 +391,52 @@ export default {
 			return Array.isArray(this.entries) && this.entries.length > 0
 		},
 
+		/**
+		 * Whether the widget draws label/number rows (`layout: "rows"`).
+		 *
+		 * @return {boolean}
+		 */
+		isRows() {
+			return this.layout === 'rows'
+		},
+
+		/**
+		 * The rows of the rows layout: one per entry, or a single row from the
+		 * `dataSource` (labelled by `countLabel`). A row is `{ key, label,
+		 * display, variant, route, href }`; `display` is the formatted value,
+		 * a dash while it loads or when the count could not be read.
+		 *
+		 * @return {Array<object>}
+		 */
+		rowViews() {
+			if (!this.hasEntries) {
+				const formatted = this.formattedSingle
+				return [{
+					key: 'single',
+					label: this.tl(this.countLabel),
+					display: this.loading ? '\u2014' : (formatted !== null ? formatted : this.formatCount(this.resolvedCount)),
+					variant: this.variant || 'default',
+					route: this.route,
+					href: this.route ? resolveHref(this.route, this.$router) : '',
+				}]
+			}
+			return this.entryViews.map((view) => {
+				const resolved = view.resolved === true
+				let display = '\u2014'
+				if (resolved) {
+					display = view.formatted !== null ? view.formatted : this.formatCount(view.count)
+				}
+				return {
+					key: view.key,
+					label: this.tl(view.entry.title || ''),
+					display,
+					variant: view.entry.variant || 'default',
+					route: view.route,
+					href: view.route ? resolveHref(view.route, this.$router) : '',
+				}
+			})
+		},
+
 		/**
 		 * The unwrapped detail-page object context for token resolution, or
 		 * null on surfaces (dashboards) that don't provide one.
@@ -566,6 +650,37 @@ export default {
 	},
 
 	methods: {
+		/**
+		 * A manifest string through the host's label lookup.
+		 *
+		 * @param {string} text The text as written in the manifest.
+		 * @return {string} The translated text.
+		 */
+		tl(text) {
+			return typeof this.cnTranslate === 'function' ? this.cnTranslate(text) : text
+		},
+
+		/**
+		 * A count in the user's locale.
+		 *
+		 * @param {number} count The count.
+		 * @return {string} The localized count.
+		 */
+		formatCount(count) {
+			return new Intl.NumberFormat().format(count)
+		},
+
+		/**
+		 * Follow a row label's link in the router, leaving a modified click to the browser.
+		 *
+		 * @param {MouseEvent} event The click.
+		 * @param {object} route The route location.
+		 * @return {void}
+		 */
+		onRowClick(event, route) {
+			followLinkClick(event, route, this.$router)
+		},
+
 		/**
 		 * Re-query the tile's counts — the REST `/value` aggregation, the
 		 * per-entry counts of multi-entry mode, and the `dataSource` GraphQL
@@ -758,4 +873,66 @@ export default {
 	flex-direction: column;
 	gap: var(--cn-kpi-stack-gap, 12px);
 }
+
+/* Rows layout: the board's "label left, number right" card body. */
+.cn-stats-block-widget--rows {
+	display: flex;
+	flex-direction: column;
+	gap: 12px;
+	box-sizing: border-box;
+	padding: 20px 22px;
+}
+
+.cn-stats-block-widget__rows-title {
+	margin: 0;
+	font-size: 15px;
+	font-weight: 600;
+	color: var(--color-text-maxcontrast);
+}
+
+.cn-stats-block-widget__rows {
+	display: flex;
+	flex-direction: column;
+	gap: 8px;
+	margin: 0;
+	font-size: 14px;
+}
+
+.cn-stats-block-widget__row {
+	display: flex;
+	align-items: baseline;
+	justify-content: space-between;
+	gap: 16px;
+}
+
+.cn-stats-block-widget__row-label {
+	min-width: 0;
+	margin: 0;
+	overflow: hidden;
+	text-overflow: ellipsis;
+}
+
+.cn-stats-block-widget__row-value {
+	flex: none;
+	margin: 0;
+	font-size: 17px;
+	font-weight: 700;
+	text-align: right;
+}
+
+.cn-stats-block-widget__row-value--success {
+	color: var(--color-text-success, var(--color-success-text));
+}
+
+.cn-stats-block-widget__row-value--warning {
+	color: var(--color-text-warning, var(--color-warning-text));
+}
+
+.cn-stats-block-widget__row-value--error {
+	color: var(--color-text-error, var(--color-error-text));
+}
+
+.cn-stats-block-widget__row-value--primary {
+	color: var(--color-primary-element);
+}
 </style>