@conduction/nextcloud-vue 2.59.0 → 2.61.0

package/src/components/CnStackedBarWidget/CnStackedBarWidget.vue

@@ -0,0 +1,414 @@
+<!--
+  SPDX-FileCopyrightText: 2026 Conduction B.V.
+  SPDX-License-Identifier: EUPL-1.2
+-->
+<template>
+	<div class="cn-stacked-bar" data-testid="cn-stacked-bar">
+		<div v-if="loading" class="cn-stacked-bar__state" role="status">
+			<NcLoadingIcon :size="20" />
+			<span>{{ loadingLabel }}</span>
+		</div>
+		<p v-else-if="error" class="cn-stacked-bar__state" role="status">
+			{{ errorLabel }}
+		</p>
+		<p v-else-if="total === 0" class="cn-stacked-bar__state" data-testid="cn-stacked-bar-empty">
+			{{ emptyLabel }}
+		</p>
+		<template v-else>
+			<!-- The bar is a picture of the legend below it. The legend holds
+			     every label and number, so the bar itself is hidden from
+			     assistive technology rather than described twice. -->
+			<div class="cn-stacked-bar__bar" aria-hidden="true">
+				<span
+					v-for="segment in barSegments"
+					:key="segment.key"
+					class="cn-stacked-bar__segment"
+					:style="{ flexGrow: segment.count, backgroundColor: segment.color }" />
+			</div>
+			<ul class="cn-stacked-bar__legend">
+				<li
+					v-for="segment in segments"
+					:key="segment.key"
+					class="cn-stacked-bar__legend-item"
+					data-testid="cn-stacked-bar-legend-item">
+					<span class="cn-stacked-bar__label">
+						<span
+							class="cn-stacked-bar__dot"
+							aria-hidden="true"
+							:style="{ backgroundColor: segment.color }" />
+						{{ segment.label }}
+					</span>
+					<!-- The leading space keeps label and count two words for a
+					     screen reader; it is not drawn in this flex column. -->
+					<strong class="cn-stacked-bar__count">{{ ' ' + segment.count }}</strong>
+				</li>
+			</ul>
+		</template>
+	</div>
+</template>
+
+<script>
+import { translate as t } from '@nextcloud/l10n'
+import { NcLoadingIcon } from '@nextcloud/vue'
+import { fetchGroupedCounts } from '../../utils/fetchAggregate.js'
+
+/** The lightest step keeps this share of the primary colour, so it still stands out from the page. */
+const LIGHTEST_PRIMARY_SHARE = 70
+
+/**
+ * The colour of step `index` out of `count`, on one ramp that runs from a
+ * light tint of the primary colour, through the primary colour, to the text
+ * colour. Steps differ in LIGHTNESS, so they stay apart for somebody who
+ * cannot tell hues apart, and the ramp follows the theme because it is built
+ * from Nextcloud's own variables.
+ *
+ * @param {number} index The step, 0-based.
+ * @param {number} count The number of steps.
+ * @return {string} A CSS colour.
+ * @spec openspec/changes/workplace-dashboard-primitives/specs/workplace-dashboard-primitives/spec.md#requirement-stacked-bar-widget
+ */
+export function rampColor(index, count) {
+	if (count <= 1) {
+		return 'var(--color-primary-element)'
+	}
+	const position = index / (count - 1)
+	if (position < 0.5) {
+		const share = Math.round(LIGHTEST_PRIMARY_SHARE + (position / 0.5) * (100 - LIGHTEST_PRIMARY_SHARE))
+		return `color-mix(in srgb, var(--color-primary-element) ${share}%, var(--color-main-background))`
+	}
+	const textShare = Math.round(((position - 0.5) / 0.5) * 100)
+	if (textShare === 0) {
+		return 'var(--color-primary-element)'
+	}
+	if (textShare === 100) {
+		return 'var(--color-main-text)'
+	}
+	return `color-mix(in srgb, var(--color-main-text) ${textShare}%, var(--color-primary-element))`
+}
+
+/**
+ * CnStackedBarWidget shows how a total divides over a few groups: ONE bar cut
+ * into segments, with a legend below it that names every segment and gives
+ * its count. Use it for "my cases per step" or "requests per channel".
+ *
+ * Segments come from one grouped count request against an OpenRegister
+ * source (`source.groupBy`), or from static `segments`. `order` fixes the
+ * order of the segments, and `labels` gives a group key a readable name.
+ * Colours come from one ramp built on the theme's primary colour; the steps
+ * differ in lightness, never in hue alone. Resolved by its registry type key
+ * `stacked-bar`.
+ *
+ * ```json
+ * {
+ *   "widgetKey": "stacked-bar",
+ *   "props": {
+ *     "content": {
+ *       "source": { "register": "dossiq", "schema": "case", "groupBy": "status", "filter": { "assignee": "@me" } },
+ *       "order": ["received", "in_progress", "decision", "publish"],
+ *       "labels": { "received": "Received", "in_progress": "In progress", "decision": "Decision", "publish": "Publish" }
+ *     }
+ *   }
+ * }
+ * ```
+ */
+export default {
+	name: 'CnStackedBarWidget',
+
+	components: { NcLoadingIcon },
+
+	inject: {
+		/**
+		 * Host translate function provided by CnAppRoot. Segment labels and
+		 * the empty text run through it. Identity by default.
+		 */
+		cnTranslate: { default: () => (key) => key },
+	},
+
+	props: {
+		/**
+		 * The widget's configuration. `source` names the OpenRegister
+		 * register and schema, the `groupBy` field and an optional `filter`
+		 * (the shared @-token grammar). `segments` are static entries
+		 * `{ key?, label, value }` used when there is no source. `order` lists
+		 * group keys in the order they render; groups it does not list follow
+		 * in the order they arrive, and a listed key without records renders
+		 * with a count of 0. `labels` maps a group key to its label.
+		 * `emptyText` is shown when there is nothing to count.
+		 *
+		 * @type {{source?: {register?: string, schema?: string, groupBy?: string, filter?: object}, segments?: Array<{key?: string, label: string, value: number}>, order?: Array<string>, labels?: {[key: string]: string}, emptyText?: string}}
+		 */
+		content: {
+			type: Object,
+			default: () => ({}),
+		},
+
+		/**
+		 * Translate function. Falls back to the injected `cnTranslate`. Pass it
+		 * when mounting the widget outside a CnAppRoot.
+		 *
+		 * @type {((key: string) => string)|null}
+		 */
+		translate: {
+			type: Function,
+			default: null,
+		},
+	},
+
+	data() {
+		return {
+			groups: [],
+			loading: false,
+			error: '',
+		}
+	},
+
+	computed: {
+		/**
+		 * The translate function in use.
+		 *
+		 * @return {(key: string) => string}
+		 * @spec openspec/changes/workplace-dashboard-primitives/specs/workplace-dashboard-primitives/spec.md#requirement-stacked-bar-widget
+		 */
+		effectiveTranslate() {
+			return this.translate ?? this.cnTranslate
+		},
+
+		/**
+		 * Whether the segments come from OpenRegister.
+		 *
+		 * @return {boolean}
+		 * @spec openspec/changes/workplace-dashboard-primitives/specs/workplace-dashboard-primitives/spec.md#requirement-stacked-bar-widget
+		 */
+		hasSource() {
+			const s = this.content.source || {}
+			return Boolean(s.register && s.schema && s.groupBy)
+		},
+
+		/**
+		 * The raw groups, from the source or the static list, as `{ key, label, count }`.
+		 *
+		 * @return {Array<{key: string, label: string, count: number}>}
+		 * @spec openspec/changes/workplace-dashboard-primitives/specs/workplace-dashboard-primitives/spec.md#requirement-stacked-bar-widget
+		 */
+		rawGroups() {
+			if (this.hasSource) {
+				return this.groups.map((group) => ({ key: group.key, label: group.key, count: group.count }))
+			}
+			const list = Array.isArray(this.content.segments) ? this.content.segments : []
+			return list
+				.filter((segment) => segment && typeof segment === 'object')
+				.map((segment, index) => {
+					const count = Number(segment.value)
+					return {
+						key: String(segment.key ?? segment.label ?? index),
+						label: String(segment.label ?? segment.key ?? ''),
+						count: Number.isFinite(count) && count > 0 ? count : 0,
+					}
+				})
+		},
+
+		/**
+		 * The segments in render order, each with its label and colour.
+		 *
+		 * @return {Array<{key: string, label: string, count: number, color: string}>}
+		 * @spec openspec/changes/workplace-dashboard-primitives/specs/workplace-dashboard-primitives/spec.md#requirement-stacked-bar-widget
+		 */
+		segments() {
+			const order = Array.isArray(this.content.order) ? this.content.order.map(String) : []
+			const labels = (this.content.labels && typeof this.content.labels === 'object') ? this.content.labels : {}
+			const byKey = {}
+			for (const group of this.rawGroups) {
+				byKey[group.key] = group
+			}
+			const ordered = []
+			for (const key of order) {
+				ordered.push(byKey[key] || { key, label: key, count: 0 })
+			}
+			for (const group of this.rawGroups) {
+				if (!order.includes(group.key)) {
+					ordered.push(group)
+				}
+			}
+			return ordered.map((group, index) => ({
+				key: group.key,
+				label: this.effectiveTranslate(typeof labels[group.key] === 'string' ? labels[group.key] : group.label),
+				count: group.count,
+				color: rampColor(index, ordered.length),
+			}))
+		},
+
+		/**
+		 * The segments that take up room in the bar.
+		 *
+		 * @return {Array<object>}
+		 * @spec openspec/changes/workplace-dashboard-primitives/specs/workplace-dashboard-primitives/spec.md#requirement-stacked-bar-widget
+		 */
+		barSegments() {
+			return this.segments.filter((segment) => segment.count > 0)
+		},
+
+		/**
+		 * The sum of all counts.
+		 *
+		 * @return {number}
+		 * @spec openspec/changes/workplace-dashboard-primitives/specs/workplace-dashboard-primitives/spec.md#requirement-stacked-bar-widget
+		 */
+		total() {
+			return this.segments.reduce((sum, segment) => sum + segment.count, 0)
+		},
+
+		/**
+		 * The text shown when there is nothing to count.
+		 *
+		 * @return {string}
+		 * @spec openspec/changes/workplace-dashboard-primitives/specs/workplace-dashboard-primitives/spec.md#requirement-stacked-bar-widget
+		 */
+		emptyLabel() {
+			const text = this.content.emptyText
+			return (typeof text === 'string' && text !== '')
+				? this.effectiveTranslate(text)
+				: t('nextcloud-vue', 'Nothing to show yet')
+		},
+
+		/**
+		 * @return {string} The loading text.
+		 *
+		 * @spec openspec/changes/workplace-dashboard-primitives/specs/workplace-dashboard-primitives/spec.md#requirement-stacked-bar-widget
+		 */
+		loadingLabel() {
+			return t('nextcloud-vue', 'Loading…')
+		},
+
+		/**
+		 * @return {string} The text shown when the counts could not be loaded.
+		 *
+		 * @spec openspec/changes/workplace-dashboard-primitives/specs/workplace-dashboard-primitives/spec.md#requirement-stacked-bar-widget
+		 */
+		errorLabel() {
+			return t('nextcloud-vue', 'The numbers could not be loaded.')
+		},
+
+		/**
+		 * Changes whenever a new fetch is needed.
+		 *
+		 * @return {string}
+		 * @spec openspec/changes/workplace-dashboard-primitives/specs/workplace-dashboard-primitives/spec.md#requirement-stacked-bar-widget
+		 */
+		sourceKey() {
+			return JSON.stringify(this.content.source || {})
+		},
+	},
+
+	watch: {
+		/** @spec openspec/changes/workplace-dashboard-primitives/specs/workplace-dashboard-primitives/spec.md#requirement-stacked-bar-widget */
+		sourceKey() {
+			this.fetchGroups()
+		},
+	},
+
+	mounted() {
+		this.fetchGroups()
+	},
+
+	methods: {
+		/**
+		 * Load the count per group in one request.
+		 *
+		 * @return {Promise<void>}
+		 * @spec openspec/changes/workplace-dashboard-primitives/specs/workplace-dashboard-primitives/spec.md#requirement-stacked-bar-widget
+		 */
+		async fetchGroups() {
+			if (!this.hasSource) {
+				this.groups = []
+				this.error = ''
+				return
+			}
+			const requestKey = this.sourceKey
+			this.loading = true
+			this.error = ''
+			try {
+				const groups = await fetchGroupedCounts(this.content.source)
+				if (requestKey !== this.sourceKey) {
+					return
+				}
+				this.groups = groups
+			} catch (e) {
+				// eslint-disable-next-line no-console
+				console.warn('[CnStackedBarWidget] failed to load counts:', e)
+				this.error = (e && e.message) || 'error'
+				this.groups = []
+			} finally {
+				this.loading = false
+			}
+		},
+	},
+}
+</script>
+
+<style scoped>
+.cn-stacked-bar {
+	display: flex;
+	flex-direction: column;
+	gap: 16px;
+	width: 100%;
+}
+
+.cn-stacked-bar__state {
+	display: flex;
+	align-items: center;
+	gap: 8px;
+	margin: 0;
+	color: var(--color-text-maxcontrast);
+}
+
+.cn-stacked-bar__bar {
+	display: flex;
+	gap: 3px;
+	height: 12px;
+}
+
+.cn-stacked-bar__segment {
+	flex-basis: 0;
+	min-width: 4px;
+	border-radius: 6px;
+}
+
+.cn-stacked-bar__legend {
+	display: grid;
+	grid-template-columns: repeat(auto-fit, minmax(150px, 1fr));
+	gap: 12px;
+	margin: 0;
+	padding: 0;
+	list-style: none;
+}
+
+.cn-stacked-bar__legend-item {
+	display: flex;
+	flex-direction: column;
+	gap: 2px;
+	min-width: 0;
+}
+
+.cn-stacked-bar__label {
+	display: flex;
+	align-items: center;
+	gap: 8px;
+	font-size: 0.95em;
+	color: var(--color-text-maxcontrast);
+	overflow-wrap: anywhere;
+}
+
+.cn-stacked-bar__dot {
+	flex: none;
+	width: 10px;
+	height: 10px;
+	border-radius: 3px;
+}
+
+.cn-stacked-bar__count {
+	font-size: 1.5em;
+	font-weight: 700;
+	line-height: 1.2;
+	color: var(--color-main-text);
+}
+</style>

package/src/components/CnStackedBarWidget/index.js

@@ -0,0 +1,14 @@
+/**
+ * SPDX-FileCopyrightText: 2026 Conduction B.V.
+ * SPDX-License-Identifier: EUPL-1.2
+ *
+ * CnStackedBarWidget: the `stacked-bar` dashboard widget (one segmented bar
+ * with a legend that carries the numbers). It is registered in
+ * `CnWidgetGrid/registerDashboardWidgets.js`, inline, because a bare
+ * side-effect import of this module may be tree-shaken away.
+ */
+
+import CnStackedBarWidget from './CnStackedBarWidget.vue'
+
+export { CnStackedBarWidget }
+export default CnStackedBarWidget

package/src/components/CnStackedBarWidgetForm/CnStackedBarWidgetForm.vue

@@ -0,0 +1,224 @@
+<!--
+  - SPDX-FileCopyrightText: 2026 Conduction B.V.
+  - SPDX-License-Identifier: EUPL-1.2
+-->
+
+<template>
+	<div class="cn-stacked-bar-form">
+		<div class="cn-stacked-bar-form__row2">
+			<CnRegisterSchemaSelect
+				:register="source.register"
+				:schema="source.schema"
+				@update:register="updateSource('register', $event)"
+				@update:schema="updateSource('schema', $event)" />
+		</div>
+
+		<CnFieldPicker
+			:value="groupBy"
+			:label="t('nextcloud-vue', 'Field to group by')"
+			:options="availableFields"
+			placeholder="status"
+			@update="updateField('groupBy', $event)" />
+
+		<CnFilterRowsEditor :value="filterRows" :fields="availableFields" @input="onFilterRows" />
+
+		<NcTextField
+			:modelValue="orderText"
+			:label="t('nextcloud-vue', 'Order of the segments (values, comma separated)')"
+			placeholder="received, in_progress, decision"
+			@update:modelValue="updateField('orderText', $event)" />
+
+		<NcTextField
+			:modelValue="emptyText"
+			:label="t('nextcloud-vue', 'Text when there is nothing to count')"
+			@update:modelValue="updateField('emptyText', $event)" />
+	</div>
+</template>
+
+<script>
+import { translate as t } from '@nextcloud/l10n'
+import { NcTextField } from '@nextcloud/vue'
+import CnFieldPicker from '../CnFieldPicker/CnFieldPicker.vue'
+import CnFilterRowsEditor from '../CnFilterRowsEditor/CnFilterRowsEditor.vue'
+import CnRegisterSchemaSelect from '../CnRegisterSchemaSelect/CnRegisterSchemaSelect.vue'
+import { fetchSchemaProperties } from '../../utils/fetchSchemaProperties.js'
+import { filterToRows, rowsToFilter } from '../CnFilterRowsEditor/filterRows.js'
+
+/**
+ * CnStackedBarWidgetForm is the settings form of a `stacked-bar` widget. It
+ * edits the source (register, schema, filter), the field the records are
+ * grouped by, the order of the segments and the empty text. Static `segments`
+ * and the `labels` map are written in the manifest and pass through
+ * untouched. Emits `update:content` on every change; `validate()` asks for a
+ * register, a schema and a group field unless the widget has static segments.
+ */
+export default {
+	name: 'CnStackedBarWidgetForm',
+
+	components: { NcTextField, CnFieldPicker, CnFilterRowsEditor, CnRegisterSchemaSelect },
+
+	props: {
+		/**
+		 * The placement being edited (pre-fills from `editingWidget.content`), or null.
+		 *
+		 * @type {{content: object}|null}
+		 */
+		editingWidget: { type: Object, default: null },
+		/**
+		 * Initial content values when not editing (registry defaults).
+		 *
+		 * @type {object}
+		 */
+		value: { type: Object, default: () => ({}) },
+	},
+
+	emits: [
+		/**
+		 * Emitted with the assembled content blob on every field change.
+		 *
+		 * @event update:content
+		 * @type {object}
+		 */
+		'update:content',
+	],
+
+	data() {
+		const initial = this.editingWidget?.content || this.value || {}
+		const src = initial.source || {}
+		return {
+			initial,
+			source: { register: src.register ?? '', schema: src.schema ?? '' },
+			groupBy: src.groupBy ?? '',
+			filterRows: filterToRows(src.filter || {}),
+			orderText: Array.isArray(initial.order) ? initial.order.join(', ') : '',
+			emptyText: initial.emptyText ?? '',
+			availableFields: [],
+		}
+	},
+
+	computed: {
+		/**
+		 * The assembled content blob. Keys the form does not edit (static
+		 * segments, labels) are carried over from the initial content.
+		 *
+		 * @return {object}
+		 * @spec openspec/changes/workplace-dashboard-primitives/specs/workplace-dashboard-primitives/spec.md#requirement-stacked-bar-widget
+		 */
+		assembledContent() {
+			return {
+				...this.initial,
+				source: {
+					register: this.source.register,
+					schema: this.source.schema,
+					groupBy: this.groupBy,
+					filter: rowsToFilter(this.filterRows),
+				},
+
+				order: this.orderText.split(',').map((key) => key.trim()).filter((key) => key !== ''),
+				emptyText: this.emptyText,
+			}
+		},
+	},
+
+	watch: {
+		'source.register': 'loadFields',
+		'source.schema': 'loadFields',
+	},
+
+	mounted() {
+		this.loadFields()
+	},
+
+	methods: {
+		t,
+
+		/**
+		 * Load the schema's field names for the picker.
+		 *
+		 * @return {Promise<void>}
+		 * @spec openspec/changes/workplace-dashboard-primitives/specs/workplace-dashboard-primitives/spec.md#requirement-stacked-bar-widget
+		 */
+		async loadFields() {
+			this.availableFields = await fetchSchemaProperties(this.source.register, this.source.schema)
+		},
+
+		/**
+		 * Set one field and emit the assembled content.
+		 *
+		 * @param {string} field The data key to write.
+		 * @param {string} value The new value.
+		 * @return {void}
+		 * @spec openspec/changes/workplace-dashboard-primitives/specs/workplace-dashboard-primitives/spec.md#requirement-stacked-bar-widget
+		 */
+		updateField(field, value) {
+			this[field] = value
+			this.$emit('update:content', this.assembledContent)
+		},
+
+		/**
+		 * Set the register or the schema and emit.
+		 *
+		 * @param {'register'|'schema'} field The source key to write.
+		 * @param {string} value The chosen slug.
+		 * @return {void}
+		 * @spec openspec/changes/workplace-dashboard-primitives/specs/workplace-dashboard-primitives/spec.md#requirement-stacked-bar-widget
+		 */
+		updateSource(field, value) {
+			this.source[field] = value
+			this.$emit('update:content', this.assembledContent)
+		},
+
+		/**
+		 * Take the filter editor's rows and emit.
+		 *
+		 * @param {Array<{key: string, op: string, value: string}>} rows The rows.
+		 * @return {void}
+		 * @spec openspec/changes/workplace-dashboard-primitives/specs/workplace-dashboard-primitives/spec.md#requirement-stacked-bar-widget
+		 */
+		onFilterRows(rows) {
+			this.filterRows = rows
+			this.$emit('update:content', this.assembledContent)
+		},
+
+		/**
+		 * Validate the form; an empty array means valid.
+		 *
+		 * @return {string[]} The validation errors.
+		 * @spec openspec/changes/workplace-dashboard-primitives/specs/workplace-dashboard-primitives/spec.md#requirement-stacked-bar-widget
+		 */
+		validate() {
+			const hasStatic = Array.isArray(this.initial.segments) && this.initial.segments.length > 0
+			if (hasStatic && !this.source.register && !this.source.schema) {
+				return []
+			}
+			const errors = []
+			if (!this.source.register || !this.source.schema) {
+				errors.push(t('nextcloud-vue', 'A register and schema are required'))
+			}
+			if (!this.groupBy) {
+				errors.push(t('nextcloud-vue', 'A field to group by is required'))
+			}
+			return errors
+		},
+	},
+}
+</script>
+
+<style scoped>
+.cn-stacked-bar-form {
+	display: flex;
+	flex-direction: column;
+	gap: 12px;
+}
+
+.cn-stacked-bar-form__row2 {
+	display: flex;
+	gap: 12px;
+	align-items: flex-end;
+}
+
+.cn-stacked-bar-form__row2 > * {
+	flex: 1;
+	min-width: 0;
+}
+</style>

package/src/components/CnStackedBarWidgetForm/index.js

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

package/src/components/CnTabs/CnTab.vue

@@ -89,6 +89,28 @@ export default defineComponent({
 			type: Boolean,
 			default: false,
 		},
+
+		/**
+		 * A count shown after the title, for example the number of documents
+		 * behind the tab. `null` (the default) shows none; `0` is shown.
+		 *
+		 * @type {number|string|null}
+		 */
+		count: {
+			type: [Number, String],
+			default: null,
+		},
+
+		/**
+		 * List this tab under the strip's "More" menu instead of in the strip.
+		 * Picking it there selects it, and while it is the selected tab it
+		 * shows in the strip. Give an overflow tab a `title`: the menu needs
+		 * plain text, and a `#title` slot is markup.
+		 */
+		overflow: {
+			type: Boolean,
+			default: false,
+		},
 	},
 
 	emits: [
@@ -125,6 +147,19 @@ export default defineComponent({
 			get disabled() {
 				return props.disabled
 			},
+
+			get count() {
+				return props.count
+			},
+
+			get overflow() {
+				return props.overflow
+			},
+
+			// Plain text for the "More" menu, where a `#title` slot cannot go.
+			get label() {
+				return props.title
+			},
 		}
 
 		onMounted(() => tabsApi?.register(entry))