@conduction/nextcloud-vue 2.105.0 → 2.106.0

package/src/components/CnIndexPage/CnIndexPageWidgets.vue

@@ -30,11 +30,15 @@
 				:showRefresh="false"
 				:headerLink="entry.headerLink"
 				:flush="variant === 'stat-row'">
+				<template v-if="headerNotes[entry.id]" #actions>
+					<span class="cn-index-page-widgets__note" data-testid="cn-index-page-widget-note">{{ headerNotes[entry.id] }}</span>
+				</template>
 				<component
 					:is="entry.renderer"
 					:widgetId="entry.id"
 					:content="entry.content"
-					v-bind="declaredContent(entry)" />
+					v-bind="declaredContent(entry)"
+					@header="onHeader(entry.id, $event)" />
 			</CnWidgetWrapper>
 		</div>
 	</component>
@@ -85,6 +89,13 @@ export default {
 		},
 	},
 
+	data() {
+		return {
+			/** The header note each widget reported (`header` event), by widget id. */
+			headerNotes: {},
+		}
+	},
+
 	computed: {
 		/**
 		 * The renderable entries, in the listed order.
@@ -122,6 +133,23 @@ export default {
 	},
 
 	methods: {
+		/**
+		 * Keep the header note a widget reports ("4 van 5 aanwezig"); only a
+		 * changed note is stored, so a report on render does not loop.
+		 *
+		 * @param {string} id The widget id.
+		 * @param {object} header `{ note?, link? }` from the widget.
+		 * @return {void}
+		 * @spec openspec/changes/side-panel-header-note/specs/side-panel-header-note/spec.md#requirement-a-side-panel-card-shows-the-note-its-widget-reports
+		 */
+		onHeader(id, header) {
+			const note = header && typeof header === 'object' && typeof header.note === 'string' ? header.note : ''
+			if ((this.headerNotes[id] || '') === note) {
+				return
+			}
+			this.headerNotes = { ...this.headerNotes, [id]: note }
+		},
+
 		/**
 		 * The content keys an entry's renderer declares as props. An undeclared
 		 * key would fall through onto the renderer's root; the whole content
@@ -158,6 +186,13 @@ export default {
 </script>
 
 <style scoped>
+.cn-index-page-widgets__note {
+	align-self: center;
+	color: var(--color-text-maxcontrast);
+	font-size: 14px;
+	white-space: nowrap;
+}
+
 .cn-index-page-widgets--stat-row {
 	margin-bottom: var(--cn-board-section-gap, 20px);
 }

package/src/components/CnIndexPage/useSelfFetchList.js

@@ -9,7 +9,7 @@ import { withPersonalLenses } from '../../utils/personalLenses.js'
 import { parseSortKeysFromQuery, resolveFilterMap, resolveQueryFilters } from '../../utils/routeFilters.js'
 import { orderToSortKeys } from '../../utils/sortOrder.js'
 
-function resolveInitialQuickFilterIndex(quickFilters) {
+export function resolveInitialQuickFilterIndex(quickFilters) {
 	const tabs = Array.isArray(quickFilters) ? quickFilters : null
 	if (!tabs || tabs.length === 0) {
 		return null
@@ -228,6 +228,22 @@ export function useSelfFetchList(props, instance, inject, extras = {}) {
 		? props.sortKeys
 		: (props.sortKey ? [{ key: props.sortKey, order: props.sortOrder || 'asc' }] : defaultOrderKeys)
 	// The lens that is active on mount may set its own order.
+	/**
+	 * The tabs the strip shows, so the fetch filters by the chip that is
+	 * lit: the page's `effectiveQuickFilters` (declared, generated from
+	 * `quickFiltersFrom`, or a named source's), else the prop while the
+	 * page's computeds do not exist yet (setup).
+	 *
+	 * @return {Array<object>|null} The tabs, or null when there are none.
+	 */
+	function shownQuickFilters() {
+		const shown = instance && instance.proxy ? instance.proxy.effectiveQuickFilters : undefined
+		if (shown !== undefined) {
+			return shown
+		}
+		return withPersonalLenses(props.quickFilters, props.personalLenses)
+	}
+
 	const initialTabs = withPersonalLenses(props.quickFilters, props.personalLenses)
 	const initialTabSort = (!isMultiQuickFilter && Array.isArray(initialTabs))
 		? quickFilterSortKeys(initialTabs[activeQuickFilterIndex.value])
@@ -275,7 +291,7 @@ export function useSelfFetchList(props, instance, inject, extras = {}) {
 			// The visible calendar month, only while the page is in calendar mode.
 			const month = (instance && instance.proxy && instance.proxy.calendarRangeFilter) || {}
 			const scope = { ...(widen ? { ...scopeBase, _content_search: 'true' } : scopeBase), ...month }
-			const lensed = withPersonalLenses(props.quickFilters, props.personalLenses)
+			const lensed = shownQuickFilters()
 			const tabs = Array.isArray(lensed) ? lensed : null
 			if (!tabs) {
 				return { ...queryFilters, ...scope, ...base }
@@ -290,7 +306,9 @@ export function useSelfFetchList(props, instance, inject, extras = {}) {
 
 			// Single mode: the active tab's filter spread last so it wins
 			// over a colliding props.filter entry.
-			const activeIdx = activeQuickFilterIndex.value
+			// Tabs that arrived after setup (`quickFiltersFrom`) have no index
+			// yet: the default tab is the one in force, as the strip shows.
+			const activeIdx = activeQuickFilterIndex.value ?? resolveInitialQuickFilterIndex(tabs)
 			const tabFilter = (activeIdx !== null && activeIdx !== undefined) ? tabs[activeIdx]?.filter : null
 			return { ...queryFilters, ...scope, ...base, ...resolveFilterMap(tabFilter, params, ctx) }
 		},
@@ -310,7 +328,7 @@ export function useSelfFetchList(props, instance, inject, extras = {}) {
 		// for a lens without goes back to the page's own order. A column the
 		// person sorts by afterwards still wins until the next switch.
 		if (!isMultiQuickFilter && before && now[0] !== before[0]) {
-			const tabs = withPersonalLenses(props.quickFilters, props.personalLenses) || []
+			const tabs = shownQuickFilters() || []
 			const keys = quickFilterSortKeys(tabs[now[0]]) || (quickFilterSortKeys(tabs[before[0]]) ? pageSortKeys : null)
 			if (keys && list.sortKeys) {
 				list.sortKeys.value = keys

package/src/components/CnIndexSidebar/CnIndexSidebar.md

@@ -197,6 +197,8 @@ With admin-only filter control:
 | `visibleColumns` | Array | `null` | Currently visible column keys; `null` means all visible |
 | `personalColumns` | Boolean | `true` | Show the Order and pin list and Reset columns in the Columns tab |
 | `pinnedCount` | Number | `0` | How many of the first visible columns are pinned to the start of the table |
+| `sortOptions` | Array | `[]` | The orders the Sort section in the Search tab offers: `[{ value, label, keys }]`, `keys` a `[{ key, order }]` list read as its ascending form. Empty draws no Sort section. Choosing a field or a direction emits `sort-change` with the new `[{ key, order }]`. |
+| `currentSort` | Array | `[]` | The list's current order, `[{ key, order }]`: the Sort section shows its field, its direction and "Current order: ...". |
 | `facetData` | Object | `{}` | Live facet data from the API: `{ fieldName: { values: [{ value, count }] } }` |
 | `columnGroups` | Array | `[]` | Extra column groups beyond schema properties and built-in Metadata. Each: `{ id, label, columns: [{ key, label }], expanded? }` |
 | `showMetadata` | Boolean | `true` | Whether to include the built-in Metadata column group |

package/src/components/CnIndexSidebar/CnIndexSidebar.vue

@@ -37,6 +37,42 @@
 						@update:modelValue="$emit('search', $event)" />
 				</div>
 
+				<!-- Sort (list, card and map views; the table sorts by its headers):
+				     the field, the direction and the order the list has now. -->
+				<div v-if="sortOptions.length > 0" class="cn-index-sidebar__section cn-index-sidebar__sort" data-testid="cn-index-sidebar-sort">
+					<h3>{{ t('nextcloud-vue', 'Sort') }}</h3>
+					<NcSelect
+						:modelValue="sortSelected"
+						:options="sortOptions"
+						label="label"
+						:clearable="false"
+						:inputLabel="t('nextcloud-vue', 'Sort by')"
+						@update:modelValue="onSortField" />
+					<div class="cn-index-sidebar__sort-direction" role="radiogroup" :aria-label="t('nextcloud-vue', 'Direction')">
+						<NcCheckboxRadioSwitch
+							type="radio"
+							name="cn-index-sidebar-sort-direction"
+							value="asc"
+							:modelValue="sortDirection"
+							:disabled="!sortSelected"
+							@update:modelValue="onSortDirection">
+							{{ t('nextcloud-vue', 'Ascending') }}
+						</NcCheckboxRadioSwitch>
+						<NcCheckboxRadioSwitch
+							type="radio"
+							name="cn-index-sidebar-sort-direction"
+							value="desc"
+							:modelValue="sortDirection"
+							:disabled="!sortSelected"
+							@update:modelValue="onSortDirection">
+							{{ t('nextcloud-vue', 'Descending') }}
+						</NcCheckboxRadioSwitch>
+					</div>
+					<p class="cn-index-sidebar__sort-current" data-testid="cn-index-sidebar-sort-current">
+						{{ currentSortText }}
+					</p>
+				</div>
+
 				<div v-if="hasActiveFilters" class="cn-index-sidebar__section">
 					<NcButton variant="tertiary" @click="onClearAll">
 						<template #icon>
@@ -273,6 +309,7 @@ import { METADATA_COLUMNS } from '../../constants/metadata.js'
 import { facetOptions } from '../../utils/facets.js'
 import { labelLang } from '../../utils/manifestTranslate.js'
 import { columnsFromSchema, filtersFromSchema } from '../../utils/schema.js'
+import { reverseSortKeys, sameSortKeys } from '../../utils/sortOrder.js'
 import { CnDateRangePicker, DEFAULT_DATE_RANGE_PRESETS } from '../CnDateRangePicker/index.js'
 import { CnIcon } from '../CnIcon/index.js'
 
@@ -366,6 +403,22 @@ export default {
 			default: 0,
 		},
 
+		/**
+		 * The orders the Sort section offers, `[{ value, label, keys }]`, each
+		 * `keys` a `[{ key, order }]` list read as its ascending form. Empty
+		 * draws no Sort section (the table view sorts by its headers).
+		 */
+		sortOptions: {
+			type: Array,
+			default: () => [],
+		},
+
+		/** The list's current order, `[{ key, order }]`. */
+		currentSort: {
+			type: Array,
+			default: () => [],
+		},
+
 		/** Current search term */
 		searchValue: {
 			type: String,
@@ -508,7 +561,7 @@ export default {
 		},
 	},
 
-	emits: ['clear-filters', 'columns-change', 'columns-reorder', 'columns-reset', 'pin-change', 'filter-change', 'search', 'tab-change', 'update:open'],
+	emits: ['clear-filters', 'columns-change', 'columns-reorder', 'columns-reset', 'pin-change', 'filter-change', 'search', 'sort-change', 'tab-change', 'update:open'],
 
 	data() {
 		return {
@@ -535,6 +588,56 @@ export default {
 	},
 
 	computed: {
+		/**
+		 * The Sort option the current order matches, as declared or reversed.
+		 *
+		 * @return {{option: object, direction: string}|null} The match, or null.
+		 */
+		sortMatch() {
+			const current = Array.isArray(this.currentSort) ? this.currentSort : []
+			for (const option of this.sortOptions) {
+				const keys = Array.isArray(option.keys) ? option.keys : []
+				if (sameSortKeys(keys, current)) {
+					return { option, direction: 'asc' }
+				}
+				if (sameSortKeys(reverseSortKeys(keys), current)) {
+					return { option, direction: 'desc' }
+				}
+			}
+			return null
+		},
+
+		/** @return {object|null} The Sort option shown as chosen. */
+		sortSelected() {
+			return this.sortMatch ? this.sortMatch.option : null
+		},
+
+		/** @return {string} The chosen direction, `asc` or `desc`. */
+		sortDirection() {
+			return this.sortMatch ? this.sortMatch.direction : 'asc'
+		},
+
+		/**
+		 * The order the list has now, in words: "Current order: Created,
+		 * descending", or that it is not sorted.
+		 *
+		 * @return {string} The sentence.
+		 */
+		currentSortText() {
+			const current = Array.isArray(this.currentSort) ? this.currentSort : []
+			if (current.length === 0) {
+				return t('nextcloud-vue', 'Not sorted')
+			}
+			const labelOf = (key) => {
+				const single = this.sortOptions.find((o) => Array.isArray(o.keys) && o.keys.length === 1 && o.keys[0].key === key)
+				return single ? single.label : key
+			}
+			const order = this.sortMatch && this.sortMatch.option.keys.length > 1
+				? `${this.sortMatch.option.label}, ${this.sortDirection === 'desc' ? t('nextcloud-vue', 'descending') : t('nextcloud-vue', 'ascending')}`
+				: current.map((entry) => `${labelOf(entry.key)}, ${entry.order === 'desc' ? t('nextcloud-vue', 'descending') : t('nextcloud-vue', 'ascending')}`).join('; ')
+			return t('nextcloud-vue', 'Current order: {order}', { order })
+		},
+
 		/** Resolved icon — explicit prop overrides schema.icon */
 		resolvedIcon() {
 			return this.icon || this.schema?.icon || ''
@@ -692,6 +795,50 @@ export default {
 	},
 
 	methods: {
+		t,
+
+		/**
+		 * A field chosen in the Sort section: its order, in the direction
+		 * already chosen.
+		 *
+		 * @param {object|null} option The chosen option.
+		 * @return {void}
+		 */
+		onSortField(option) {
+			const chosen = option && this.sortOptions.find((o) => o.value === option.value)
+			if (!chosen) {
+				return
+			}
+			this.emitSort(chosen, this.sortDirection)
+		},
+
+		/**
+		 * A direction chosen in the Sort section, for the chosen field.
+		 *
+		 * @param {string} direction `asc` or `desc`.
+		 * @return {void}
+		 */
+		onSortDirection(direction) {
+			if (!this.sortSelected) {
+				return
+			}
+			this.emitSort(this.sortSelected, direction === 'desc' ? 'desc' : 'asc')
+		},
+
+		/**
+		 * Emit the order an option stands for in a direction.
+		 *
+		 * @param {object} option The Sort option.
+		 * @param {string} direction `asc` or `desc`.
+		 * @return {void}
+		 */
+		emitSort(option, direction) {
+			const keys = Array.isArray(option.keys) ? option.keys : []
+			/**
+			 * @event sort-change The Sort section chose an order. Payload: `[{ key, order }]`.
+			 */
+			this.$emit('sort-change', direction === 'desc' ? reverseSortKeys(keys) : keys.map((k) => ({ key: k.key, order: k.order || 'asc' })))
+		},
 
 		/**
 		 * A manifest label through the injected lookup, or as written.

package/src/components/CnNcWidgetWidget/CnNcWidgetWidget.vue

@@ -46,7 +46,7 @@
 				{{ t('nextcloud-vue', 'This widget can only be shown on the Nextcloud dashboard itself.') }}
 			</div>
 
-			<div v-else-if="items.length === 0" class="cn-nc-widget-widget__state">
+			<div v-else-if="shownItems.length === 0" class="cn-nc-widget-widget__state">
 				{{ t('nextcloud-vue', 'No items available') }}
 			</div>
 
@@ -137,7 +137,10 @@ export default {
 
 	props: {
 		/**
-		 * Persisted widget content `{widgetId, displayMode, limit?, showAllUrl?, showAllLabel?, showHeader?}`.
+		 * Persisted widget content `{widgetId, displayMode, limit?, showAllUrl?, showAllLabel?, showHeader?, excludeApps?, excludeTypes?}`.
+		 * `excludeApps` (`["systemtags"]`) and `excludeTypes` leave out the
+		 * items of those apps or types (an item's own `app` / `type`, else the
+		 * app in its link or icon URL); the list then comes from the items API.
 		 * `showHeader: false` drops the widget's own header (icon and title);
 		 * it is dropped too when the hosting card draws a title row.
 		 * `limit` is the most items shown (the list then comes from the items
@@ -265,7 +268,38 @@ export default {
 		 * @return {object[]} the items.
 		 */
 		shownItems() {
-			return this.itemLimit > 0 ? this.items.slice(0, this.itemLimit) : this.items
+			const kept = this.hasExclusions ? this.items.filter((item) => !this.isExcluded(item)) : this.items
+			return this.itemLimit > 0 ? kept.slice(0, this.itemLimit) : kept
+		},
+
+		/**
+		 * The apps and item types `content.excludeApps` / `content.excludeTypes`
+		 * leave out, lower-cased.
+		 *
+		 * @spec openspec/changes/nc-widget-exclude-apps/specs/nc-widget/spec.md#requirement-a-nextcloud-widget-can-leave-out-items-of-an-app-or-type
+		 * @return {{apps: string[], types: string[]}}
+		 */
+		exclusions() {
+			const list = (value) => (Array.isArray(value) ? value : (typeof value === 'string' && value !== '' ? [value] : []))
+				.filter((entry) => typeof entry === 'string' && entry !== '')
+				.map((entry) => entry.toLowerCase())
+			return { apps: list(this.content && this.content.excludeApps), types: list(this.content && this.content.excludeTypes) }
+		},
+
+		/**
+		 * How many items to ask the API for: the limit (or the default), and
+		 * more while items are left out, so a filtered list still fills it.
+		 *
+		 * @return {number}
+		 */
+		requestLimit() {
+			const base = this.itemLimit > 0 ? this.itemLimit : API_ITEM_LIMIT
+			return this.hasExclusions ? Math.max(base * 3, 20) : base
+		},
+
+		/** @return {boolean} Whether any app or type is left out. */
+		hasExclusions() {
+			return this.exclusions.apps.length > 0 || this.exclusions.types.length > 0
 		},
 
 		/**
@@ -317,6 +351,34 @@ export default {
 	},
 
 	methods: {
+		/**
+		 * Whether an item belongs to an app or type the content leaves out: its
+		 * own `app` / `type` / `objectType`, else the app in an `/apps/<app>/`
+		 * part of its link or icons.
+		 *
+		 * @spec openspec/changes/nc-widget-exclude-apps/specs/nc-widget/spec.md#requirement-a-nextcloud-widget-can-leave-out-items-of-an-app-or-type
+		 * @param {object} item A widget item.
+		 * @return {boolean}
+		 */
+		isExcluded(item) {
+			if (!item || typeof item !== 'object') {
+				return false
+			}
+			const { apps, types } = this.exclusions
+			const own = (value) => (typeof value === 'string' ? value.toLowerCase() : '')
+			const appsOf = [own(item.app)]
+			for (const url of [item.link, item.iconUrl, item.overlayIconUrl]) {
+				const match = typeof url === 'string' ? url.match(/\/apps\/([a-z0-9_-]+)\//i) : null
+				if (match) {
+					appsOf.push(match[1].toLowerCase())
+				}
+			}
+			if (apps.length > 0 && appsOf.some((app) => app !== '' && apps.includes(app))) {
+				return true
+			}
+			return types.length > 0 && [own(item.type), own(item.objectType)].some((type) => type !== '' && types.includes(type))
+		},
+
 		t,
 
 		/**
@@ -339,7 +401,8 @@ export default {
 			// where the widget has a registered native callback.
 			// A `limit` also takes the API list first: the native callback paints
 			// as many items as it likes. Its fallback to native stays.
-			if (this.displayMode !== 'horizontal' && this.itemLimit === 0) {
+			// Leaving items out works on the API list only, so it skips native too.
+			if (this.displayMode !== 'horizontal' && this.itemLimit === 0 && !this.hasExclusions) {
 				const callback = this.resolveNativeCallback()
 				if (typeof callback === 'function') {
 					this.mountNative(callback)
@@ -424,7 +487,7 @@ export default {
 				// both the flat-array (older providers) and `{items}` (v2) shapes.
 				const url = generateOcsUrl('/apps/dashboard/api/v2/widget-items')
 				const response = await axios.get(url, {
-					params: { widgets: [this.widgetId], limit: this.itemLimit > 0 ? this.itemLimit : API_ITEM_LIMIT },
+					params: { widgets: [this.widgetId], limit: this.requestLimit },
 				})
 				const data = response && response.data && response.data.ocs ? response.data.ocs.data : null
 				const widgetData = data ? data[this.widgetId] : null

package/src/components/CnObjectCard/CnObjectCard.md

@@ -155,3 +155,4 @@ export default {
 | `leading` | Object | `null` | Leading element: `{ initials }` in a circle or `{ icon }` on a tint |
 | `footerAction` | Object | `null` | `{ label, meta?, ariaLabel? }`, one footer action; emits `footer-action` |
 | `cardFields` | Array | `null` | Property keys of the facts list, in order |
+| `layout` | Object | `null` | Board look: the record layout, `{ headPill, number, title, meta, footerPill, footerDate }`; each part names a field and is left out while it is empty. A part whose field names a page column (`cardFieldColumns`) reads through that column's formatter, and a meta part through its widget, as the table cell does. A pill with `due` (`{ soonWithin }`) or `variantWhen` reads its date: overdue as error, soon (or the matching rule) as warning, labelled by `labels[variant]` or `labels.overdue` / `labels.soon` through the host's translate, else Overdue / Soon; any other date draws no pill. |