@conduction/nextcloud-vue 2.62.0 → 2.64.0

package/src/components/CnDataTable/CnDataTable.vue

@@ -19,6 +19,36 @@
 			</span>
 		</div>
 
+		<!-- Active header filters, one removable chip each. -->
+		<ul
+			v-if="!isLoading && activeColumnFilterChips.length > 0"
+			class="cn-data-table__filter-chips"
+			:aria-label="activeFiltersLabel"
+			data-testid="cn-table-filter-chips">
+			<li v-for="chip in activeColumnFilterChips" :key="chip.key" class="cn-data-table__filter-chip">
+				<span>{{ chip.text }}</span>
+				<button
+					type="button"
+					class="cn-data-table__filter-chip-remove"
+					:aria-label="chip.removeLabel"
+					data-testid="cn-table-filter-chip-remove"
+					@click="clearColumnFilter(chip.col)">
+					×
+				</button>
+			</li>
+		</ul>
+
+		<CnColumnFilterPopover
+			v-if="openFilterColumn"
+			:key="openFilterKey"
+			:def="filterDefFor(openFilterColumn)"
+			:state="columnFilterStateFor(openFilterColumn)"
+			:label="translateLabel(openFilterColumn.label)"
+			:anchorRect="filterAnchorRect"
+			:register="filterRegister"
+			@apply="(state) => applyColumnFilter(openFilterColumn, state)"
+			@close="closeColumnFilter" />
+
 		<!-- Loading State -->
 		<div v-if="isLoading" class="cn-table-loading" data-testid="cn-object-list-loading">
 			<!-- Decorative: the adjacent <p> already carries the accessible
@@ -92,6 +122,7 @@
 							:style="col.width ? { width: col.width } : {}"
 							:tabindex="col.sortable ? 0 : null"
 							:aria-sort="ariaSortFor(col)"
+							:data-filtered="isColumnFiltered(col) ? 'true' : null"
 							:title="translateLabel(col.description) || null"
 							@click="col.sortable ? onHeaderClick(col.key, $event) : null"
 							@keydown.enter="col.sortable ? onHeaderKeydown(col.key, $event) : null">
@@ -108,6 +139,23 @@
 								class="cn-table-sort-badge">
 								{{ sortBadgeFor(col.key) }}
 							</span>
+							<!-- Header filter: a real button, so it is reachable with Tab
+							     and its click and Enter never also sort the column. -->
+							<button
+								v-if="filterDefFor(col)"
+								:ref="'filterButton-' + col.key"
+								type="button"
+								class="cn-table-header__filter"
+								:class="{ 'cn-table-header__filter--active': isColumnFiltered(col) }"
+								:aria-label="filterButtonLabel(col)"
+								aria-haspopup="dialog"
+								:aria-expanded="openFilterKey === col.key ? 'true' : 'false'"
+								data-testid="cn-table-header-filter"
+								@click.stop="toggleColumnFilter(col, $event)"
+								@keydown.enter.stop>
+								<FilterIcon v-if="isColumnFiltered(col)" :size="16" />
+								<FilterOutline v-else :size="16" />
+							</button>
 						</th>
 
 						<!-- Actions column -->
@@ -230,6 +278,14 @@
 									:row="row"
 									:rowKey="rowKey" />
 							</slot>
+							<!-- A second, muted line under the value, from `col.secondary`:
+							     a field key, a "{field} · {other}" template, or a function
+							     of the row. Lets one column read "title" over "number ·
+							     requester" without a custom cell. -->
+							<span
+								v-if="secondaryValue(row, col)"
+								class="cn-table-cell__secondary"
+								data-testid="cn-cell-secondary">{{ secondaryValue(row, col) }}</span>
 						</td>
 
 						<!-- Row actions -->
@@ -283,10 +339,14 @@
 
 <script>
 import axios from '@nextcloud/axios'
-import { translate as t } from '@nextcloud/l10n'
+import { translatePlural as n, translate as t } from '@nextcloud/l10n'
 import { generateUrl } from '@nextcloud/router'
 import { NcCheckboxRadioSwitch, NcLoadingIcon } from '@nextcloud/vue'
+import FilterIcon from 'vue-material-design-icons/Filter.vue'
+import FilterOutline from 'vue-material-design-icons/FilterOutline.vue'
+import CnColumnFilterPopover from './CnColumnFilterPopover.vue'
 import { useClickDragGuard } from '../../composables/useClickDragGuard.js'
+import { clearedColumnFilterParams, columnFilterDef, columnFilterParams, columnFilterState, isColumnFilterActive, isColumnSortable } from '../../utils/columnFilters.js'
 import { followLinkClick, openRowTarget, resolveHref } from '../../utils/linkNavigation.js'
 import { nextSortState } from '../../utils/multiColumnSort.js'
 import { isNewTabClick, isNewTabHandled, isRowMiddleClick, markNewTabHandled, preventMiddleClickAutoscroll } from '../../utils/rowAuxClick.js'
@@ -357,8 +417,11 @@ export default {
 		NcLoadingIcon,
 		NcCheckboxRadioSwitch,
 		CnCellRenderer,
+		CnColumnFilterPopover,
 		CnIcon,
 		CnLockIndicator,
+		FilterIcon,
+		FilterOutline,
 	},
 
 	inject: {
@@ -389,7 +452,13 @@ export default {
 		 * reader is looking. `columnsFromSchema` fills it from the JSON Schema property
 		 * description automatically, so schema-driven tables get it for free.
 		 *
-		 * @type {Array<{key: string, label: string, description: string, sortable: boolean, width: string, class: string, cellClass: string}|string>}
+		 * `secondary` draws a second, muted line under the cell's value: a field
+		 * key (`"number"`), a template with `{field}` placeholders
+		 * (`"{number} · {requester}"`, dotted paths allowed), or a function of
+		 * the row. Empty fields leave their placeholder blank; a line that
+		 * resolves to nothing is not drawn.
+		 *
+		 * @type {Array<{key: string, label: string, description: string, sortable: boolean, width: string, class: string, cellClass: string, secondary: (string|((row: object) => string))}|string>}
 		 */
 		columns: {
 			type: Array,
@@ -727,9 +796,39 @@ export default {
 			type: Boolean,
 			default: false,
 		},
+
+		/**
+		 * Show a filter button in every header whose column can filter (see
+		 * `columnFilterDef`): enum, boolean, text, number, date and reference
+		 * columns backed by a schema property. A column opts out with
+		 * `filterable: false`. Applying a filter emits `column-filter`; the
+		 * host owns the filter state and passes it back as `activeFilters`.
+		 *
+		 * @spec openspec/changes/table-header-sort-and-filter/specs/cn-data-table/spec.md#requirement-every-backed-column-filters-from-its-header
+		 */
+		filterable: {
+			type: Boolean,
+			default: false,
+		},
+
+		/**
+		 * The active filter map, `{ paramKey: values[] }`: the same map the
+		 * facet sidebar writes, so a header filter and a sidebar filter on one
+		 * field show the same state.
+		 */
+		activeFilters: {
+			type: Object,
+			default: () => ({}),
+		},
+
+		/** Register slug a reference column's filter searches in when the column names none. */
+		filterRegister: {
+			type: String,
+			default: '',
+		},
 	},
 
-	emits: ['row-click', 'row-aux-click', 'row-context-menu', 'select', 'select-all', 'sort', 'view-all'],
+	emits: ['row-click', 'row-aux-click', 'row-context-menu', 'select', 'select-all', 'sort', 'view-all', 'column-filter'],
 
 	setup() {
 		// Tell a deliberate row click apart from a text-selection drag.
@@ -738,6 +837,10 @@ export default {
 
 	data() {
 		return {
+			/** Key of the column whose filter panel is open, or ''. */
+			openFilterKey: '',
+			/** The open filter button's bounding rect, to place the panel. */
+			filterAnchorRect: null,
 			/**
 			 * Resolved aggregate-column values, keyed by `String(row[rowKey])`
 			 * then by column key. Populated by `loadAggregates()` for columns
@@ -855,8 +958,12 @@ export default {
 						overrides: this.columnOverrides,
 					})
 				: this.columns
+			// Every column backed by a schema property sorts unless it says
+			// `sortable: false`; object columns from a manifest used to need an
+			// explicit flag and so could not sort at all.
+			const withSort = (c) => (c && typeof c === 'object' ? { ...c, sortable: isColumnSortable(c, this.schema) } : c)
 			if (!(cols || []).some((c) => typeof c === 'string')) {
-				return cols || []
+				return (cols || []).map(withSort)
 			}
 			const schemaCols = this.schema
 				? columnsFromSchema(this.schema, { overrides: this.columnOverrides })
@@ -864,7 +971,7 @@ export default {
 			const byKey = new Map(schemaCols.map((c) => [c.key, c]))
 			return (cols || []).map((c) => {
 				if (typeof c !== 'string') {
-					return c
+					return withSort(c)
 				}
 				return byKey.get(c) || { key: c, label: c, sortable: true }
 			})
@@ -905,6 +1012,40 @@ export default {
 			return links
 		},
 
+		/**
+		 * The column whose filter panel is open, or null.
+		 *
+		 * @return {object|null}
+		 */
+		openFilterColumn() {
+			if (!this.openFilterKey) {
+				return null
+			}
+			return this.effectiveColumns.find((c) => c && c.key === this.openFilterKey && this.filterDefFor(c)) || null
+		},
+
+		/**
+		 * One chip per column with an active header filter.
+		 *
+		 * @return {Array<{key: string, col: object, text: string, removeLabel: string}>}
+		 */
+		activeColumnFilterChips() {
+			if (!this.filterable) {
+				return []
+			}
+			return this.effectiveColumns
+				.filter((c) => c && this.isColumnFiltered(c))
+				.map((col) => {
+					const label = this.translateLabel(col.label)
+					const text = t('nextcloud-vue', '{column}: {value}', { column: label, value: this.columnFilterSummary(col) })
+					return { key: col.key, col, text, removeLabel: t('nextcloud-vue', 'Remove filter {column}', { column: label }) }
+				})
+		},
+
+		activeFiltersLabel() {
+			return t('nextcloud-vue', 'Active filters')
+		},
+
 		effectiveSortKeys() {
 			if (this.sortKeys && this.sortKeys.length > 0) {
 				return this.sortKeys
@@ -1288,6 +1429,36 @@ export default {
 		 * @param {object} col The column definition.
 		 * @return {unknown} The value handed to the slot / CnCellRenderer.
 		 */
+		/**
+		 * The secondary line of a cell, from `col.secondary`: a function is
+		 * called with the row; a string with `{field}` placeholders is a
+		 * template filled from the row (dotted paths allowed); any other
+		 * string is a field key. Returns '' when there is nothing to draw.
+		 *
+		 * @spec openspec/changes/zuiddrecht-pixel-gaps/specs/zuiddrecht-pixel-gaps/spec.md#requirement-a-table-column-carries-a-secondary-line
+		 * @param {object} row The row.
+		 * @param {object} col The column definition.
+		 * @return {string} The secondary text, or ''.
+		 */
+		secondaryValue(row, col) {
+			const spec = col?.secondary
+			if (typeof spec === 'function') {
+				const out = spec(row)
+				return out === null || out === undefined ? '' : String(out)
+			}
+			if (typeof spec !== 'string' || spec === '') {
+				return ''
+			}
+			const asText = (v) => (v === null || v === undefined ? '' : String(v))
+			if (spec.includes('{')) {
+				const filled = spec.replace(/\{([^}]+)\}/g, (_, key) => asText(this.getCellValue(row, key.trim())))
+				// A template whose every field is empty leaves only separators:
+				// nothing worth a line.
+				return /[\p{L}\p{N}]/u.test(filled) ? filled.trim() : ''
+			}
+			return asText(this.getCellValue(row, spec))
+		},
+
 		cellValue(row, col) {
 			if (col && col.aggregate) {
 				const cached = this.aggregateValues[String(row[this.rowKey])]
@@ -1576,6 +1747,135 @@ export default {
 		 * @param {string} key Column key.
 		 * @param {MouseEvent} [event] The originating click event.
 		 */
+		/**
+		 * The filter definition for a column, or null when it does not filter
+		 * (header filters off, `filterable: false`, or nothing to filter on).
+		 *
+		 * @param {object} col The column.
+		 * @return {object|null}
+		 */
+		filterDefFor(col) {
+			if (!this.filterable || !col) {
+				return null
+			}
+			return columnFilterDef(col, this.schema)
+		},
+
+		columnFilterStateFor(col) {
+			return columnFilterState(this.filterDefFor(col), this.activeFilters)
+		},
+
+		isColumnFiltered(col) {
+			const def = this.filterDefFor(col)
+			return !!def && isColumnFilterActive(def, this.activeFilters)
+		},
+
+		filterButtonLabel(col) {
+			const column = this.translateLabel(col.label)
+			return this.isColumnFiltered(col)
+				? t('nextcloud-vue', 'Filter {column}, active', { column })
+				: t('nextcloud-vue', 'Filter {column}', { column })
+		},
+
+		/**
+		 * Short text for an active filter: the picked labels, or the range.
+		 *
+		 * @param {object} col The column.
+		 * @return {string}
+		 */
+		columnFilterSummary(col) {
+			const def = this.filterDefFor(col)
+			const state = this.columnFilterStateFor(col)
+			if (!def) {
+				return ''
+			}
+			if (def.kind === 'enum') {
+				const labels = Object.fromEntries((def.options || []).map((o) => [o.value, o.label]))
+				return state.values.map((v) => this.translateLabel(labels[v] || v)).join(', ')
+			}
+			if (def.kind === 'reference') {
+				return n('nextcloud-vue', '{count} selected', '{count} selected', state.values.length, { count: state.values.length })
+			}
+			if (def.kind === 'number' || def.kind === 'date') {
+				if (state.from && state.to) {
+					return t('nextcloud-vue', '{from} to {to}', { from: state.from, to: state.to })
+				}
+				return state.from
+					? t('nextcloud-vue', 'from {value}', { value: state.from })
+					: t('nextcloud-vue', 'up to {value}', { value: state.to })
+			}
+			if (def.kind === 'boolean') {
+				return state.value === 'true' ? t('nextcloud-vue', 'Yes') : t('nextcloud-vue', 'No')
+			}
+			return state.value
+		},
+
+		/**
+		 * Open or close a column's filter panel under its button.
+		 *
+		 * @param {object} col The column.
+		 * @param {Event} event The click.
+		 * @return {void}
+		 */
+		toggleColumnFilter(col, event) {
+			if (this.openFilterKey === col.key) {
+				this.closeColumnFilter()
+				return
+			}
+			const target = event && event.currentTarget
+			this.filterAnchorRect = target && typeof target.getBoundingClientRect === 'function'
+				? target.getBoundingClientRect()
+				: null
+			this.openFilterKey = col.key
+		},
+
+		/**
+		 * Close the open panel and give focus back to its button.
+		 *
+		 * @return {void}
+		 */
+		closeColumnFilter() {
+			const key = this.openFilterKey
+			this.openFilterKey = ''
+			if (!key) {
+				return
+			}
+			this.$nextTick(() => {
+				const ref = this.$refs['filterButton-' + key]
+				const button = Array.isArray(ref) ? ref[0] : ref
+				if (button && typeof button.focus === 'function') {
+					button.focus()
+				}
+			})
+		},
+
+		/**
+		 * Apply a panel's state: emit the query parameters it stands for.
+		 *
+		 * @param {object} col The column.
+		 * @param {object} state The panel state.
+		 * @return {void}
+		 * @spec openspec/changes/table-header-sort-and-filter/specs/cn-data-table/spec.md#requirement-a-header-filter-speaks-the-sidebars-query-language
+		 */
+		applyColumnFilter(col, state) {
+			const def = this.filterDefFor(col)
+			if (def) {
+				/**
+				 * @event column-filter A header filter was applied or cleared.
+				 * @type {{ key: string, params: object }} `params` maps each query parameter the column owns to its values; an empty list clears it.
+				 */
+				this.$emit('column-filter', { key: col.key, params: columnFilterParams(def, state) })
+			}
+			this.closeColumnFilter()
+		},
+
+		clearColumnFilter(col) {
+			const def = this.filterDefFor(col)
+			if (def) {
+				this.$emit('column-filter', { key: col.key, params: clearedColumnFilterParams(def) })
+			}
+		},
+
 		onHeaderClick(key, event) {
 			this.applySort(key, !!(event && event.shiftKey))
 		},

package/src/components/CnDetailPage/CnDetailPage.md

@@ -430,3 +430,7 @@ Four levels of action and the case surfaces around them. All opt in. See [the re
 ## Not found
 
 When the schema-driven fetch answers 404 the page shows a not-found state whose back button is a router link to `notFoundRoute` (default `null`, which means the app root `/`). `notFoundRouteLabel` names that page in the button's "Back to …" label.
+
+### Type eyebrow and breadcrumb
+
+`showTypeEyebrow` (default `true`) can drop the type label above the record name. `breadcrumb` (`{ label, route?, params?, href? }`) draws a breadcrumb line above the header: that crumb, then the record's name as the current crumb.

package/src/components/CnDetailPage/CnDetailPage.vue

@@ -41,6 +41,13 @@
 			{{ skipLinkLabel }}
 		</a>
 
+		<!-- Breadcrumb line (manifest `config.breadcrumb`): the list the record
+		     belongs to, then the record itself as the current crumb. -->
+		<CnBreadcrumbs
+			v-if="breadcrumbCrumbs.length > 0 && !objectNotFound"
+			class="cn-detail-page__breadcrumbs"
+			:crumbs="breadcrumbCrumbs"
+			data-testid="cn-detail-page-breadcrumbs" />
 		<!-- Header -->
 		<div v-if="!objectNotFound" class="cn-detail-page__header" data-testid="cn-detail-page-header">
 			<!-- Header (left block) — overridable via #header slot. Default
@@ -98,7 +105,7 @@
 						     (ADR-062). Only shown once the object resolves to a
 						     display name that differs from the type label. -->
 						<p
-							v-if="typeEyebrow"
+							v-if="typeEyebrow && showTypeEyebrow"
 							class="cn-detail-page__type-eyebrow"
 							data-testid="cn-detail-page-type-eyebrow">
 							{{ typeEyebrow }}
@@ -1025,6 +1032,7 @@ import {
 	widgetTitleOf,
 } from '../../utils/widgetDispatch.js'
 import { CnActionButtons } from '../CnActionButtons/index.js'
+import { CnBreadcrumbs } from '../CnBreadcrumbs/index.js'
 import { CnIcon } from '../CnIcon/index.js'
 import { CnStatusBadge } from '../CnStatusBadge/index.js'
 import { getWidgetTypeEntry } from '../CnWidgetGrid/dashboardWidgetRegistry.js'
@@ -1172,6 +1180,7 @@ export default {
 		CnDashboardGrid,
 		CnLifecycleActions,
 		CnActionButtons,
+		CnBreadcrumbs,
 		CnStatusBadge,
 		CnSummaryAggregates,
 		CnRelatedCollections,
@@ -2078,6 +2087,34 @@ export default {
 			default: null,
 		},
 
+		/**
+		 * Whether the type eyebrow (the type label above the record name)
+		 * renders once the record resolves. `false` (manifest
+		 * `config.showTypeEyebrow: false`) drops it for a header that says
+		 * the type in a pill instead.
+		 *
+		 * @spec openspec/changes/zuiddrecht-pixel-gaps/specs/zuiddrecht-pixel-gaps/spec.md#requirement-a-detail-page-drops-its-eyebrow-and-shows-a-breadcrumb
+		 */
+		showTypeEyebrow: {
+			type: Boolean,
+			default: true,
+		},
+
+		/**
+		 * A breadcrumb line above the header (manifest `config.breadcrumb`):
+		 * `{ label, route?, params?, href? }` names the list the record
+		 * belongs to; the record's display name follows as the current
+		 * crumb. `label` goes through the host translate function. Null (the
+		 * default) draws no trail.
+		 *
+		 * @spec openspec/changes/zuiddrecht-pixel-gaps/specs/zuiddrecht-pixel-gaps/spec.md#requirement-a-detail-page-drops-its-eyebrow-and-shows-a-breadcrumb
+		 * @type {{label: string, route?: string, params?: object, href?: string}|null}
+		 */
+		breadcrumb: {
+			type: Object,
+			default: null,
+		},
+
 		/**
 		 * A column of cards beside the body (manifest `config.sideColumn`),
 		 * for the record's facts: deadline, requester, handler, links. Each
@@ -3201,6 +3238,28 @@ export default {
 			return this.objectDisplayName || this.resolvedTitle
 		},
 
+		/**
+		 * The breadcrumb trail: the declared crumb (a router target from
+		 * `route` + `params`, or an `href`), then the record's display name
+		 * as the current crumb. Empty without a `breadcrumb` label.
+		 *
+		 * @spec openspec/changes/zuiddrecht-pixel-gaps/specs/zuiddrecht-pixel-gaps/spec.md#requirement-a-detail-page-drops-its-eyebrow-and-shows-a-breadcrumb
+		 * @return {Array<{label: string, to?: object, href?: string}>}
+		 */
+		breadcrumbCrumbs() {
+			const crumb = this.breadcrumb
+			if (!crumb || typeof crumb.label !== 'string' || crumb.label === '') {
+				return []
+			}
+			const first = { label: this.effectiveTranslate(crumb.label) }
+			if (crumb.route) {
+				first.to = { name: crumb.route, ...(crumb.params ? { params: crumb.params } : {}) }
+			} else if (crumb.href) {
+				first.href = crumb.href
+			}
+			return [first, { label: this.displayTitle }]
+		},
+
 		/**
 		 * Effective translate function: the injected `cnTranslate` (the host
 		 * app's bound `t()`), identity by default.

package/src/components/CnDetailWidgetHost/CnDetailWidgetHost.vue

@@ -74,9 +74,9 @@
 			<template v-if="widget && widget.icon" #title-icon>
 				<CnIcon :name="widget.icon" :size="20" />
 			</template>
-			<NcEmptyContent :name="missingAppName" :description="missingAppDescription">
+			<NcEmptyContent class="cn-requires-app" :name="missingAppName" :description="missingAppDescription">
 				<template #icon>
-					<CnIcon :name="(widget && widget.icon) || 'PuzzleOutline'" :size="44" />
+					<CnIcon :name="(widget && widget.icon) || 'PuzzleOutline'" :size="32" />
 				</template>
 			</NcEmptyContent>
 		</CnWidgetWrapper>

package/src/components/CnFieldHelper/CnFieldHelper.vue

@@ -2,7 +2,7 @@
 	<!-- Keeps the legacy `cn-form-dialog__helper` class alongside its own so
 	     consumer stylesheets that target the old helper span still apply. -->
 	<span
-		v-if="error || text"
+		v-if="error || text || more"
 		class="cn-field-helper cn-form-dialog__helper"
 		:class="{ 'cn-field-helper--error': !!error, 'cn-form-dialog__helper--error': !!error }">
 		{{ error || text }}
@@ -42,7 +42,9 @@ import InformationOutline from 'vue-material-design-icons/InformationOutline.vue
  * `fieldsFromSchema` splits it and puts the full text on the field's
  * `descriptionLong`; pass that as `more` and this renders an ⓘ button that
  * reveals it in a popover, so a paragraph-length schema description cannot
- * push the rest of the form off screen.
+ * push the rest of the form off screen. A schema property's `x-help` text
+ * also lands on `descriptionLong`, so the ⓘ shows even when the description
+ * is short or absent.
  *
  * `CnFormDialog` uses this for every auto-generated field. Use it directly when
  * rendering your own fields through the `#form-fields` or `#field-<key>` slots,