@conduction/nextcloud-vue 2.75.0 → 2.77.0

package/src/css/table.css

@@ -284,9 +284,64 @@
 	background-color: var(--color-background-hover);
 }
 
-.cn-table-sort-indicator {
-	margin-inline-start: var(--default-grid-baseline);
-	opacity: 0.6;
+/* The sort control: a real button that looks like the header text, the label
+   followed by a 14px chevron 4px after it (the "Wettelijke termijn" header on
+   the DqWooVerzoeken board). Selector scoped under the table so it outranks
+   Nextcloud's own `button` rule, which would otherwise give it a border, a
+   fill, a 34px min-height and a margin. */
+.cn-data-table th .cn-table-header__sort {
+	display: inline-flex;
+	align-items: center;
+	gap: 4px;
+	max-width: 100%;
+	min-width: 0;
+	min-height: 0;
+	margin: 0;
+	padding: 0;
+	border: 0;
+	border-radius: var(--border-radius, 4px);
+	background: transparent;
+	color: inherit;
+	font: inherit;
+	font-weight: inherit;
+	text-align: start;
+	vertical-align: middle;
+	cursor: pointer;
+}
+
+.cn-data-table th .cn-table-header__sort:hover,
+.cn-data-table th .cn-table-header__sort:focus {
+	background: transparent;
+}
+
+.cn-data-table th .cn-table-header__sort:focus-visible {
+	outline: 2px solid var(--color-main-text);
+	outline-offset: 2px;
+}
+
+.cn-data-table th .cn-table-header__sort > :first-child {
+	min-width: 0;
+	overflow: hidden;
+	text-overflow: ellipsis;
+}
+
+/* The chevron. Unsorted columns show a pale down chevron, so every sortable
+   column says it sorts; the sorted column shows the direction at full text
+   colour. The direction is also in the header's `aria-sort`. */
+.cn-table-header__chevron {
+	display: inline-flex;
+	flex: none;
+	color: var(--color-main-text);
+}
+
+.cn-table-header__chevron--idle {
+	color: var(--color-text-maxcontrast);
+	opacity: 0.5;
+}
+
+.cn-data-table th.cn-table-header--sortable:hover .cn-table-header__chevron--idle,
+.cn-data-table th .cn-table-header__sort:focus-visible .cn-table-header__chevron--idle {
+	opacity: 1;
 }
 
 /* A column carrying a `description` gets a dotted underline — the long-standing
@@ -302,15 +357,12 @@
 	cursor: help;
 }
 
-.cn-data-table th.cn-table-header--sortable:focus-visible {
-	outline: 2px solid var(--color-main-text);
-	outline-offset: -2px;
-}
-
-/* Header filter button (CnDataTable `filterable`). 24px hit area with the
-   16px icon; the filled icon plus the primary colour marks an active filter,
-   so the state never rests on colour alone. */
-.cn-table-header__filter {
+/* Header filter button (CnDataTable `filterable`): a 14px funnel directly
+   after the sort chevron, in a 24px hit area. Muted with no filter set; with
+   a filter set it takes the dark primary and a dot, so the state never rests
+   on colour alone. */
+.cn-data-table th .cn-table-header__filter {
+	position: relative;
 	display: inline-flex;
 	align-items: center;
 	justify-content: center;
@@ -318,7 +370,7 @@
 	min-width: 24px;
 	height: 24px;
 	min-height: 24px;
-	margin: 0 0 0 4px;
+	margin: 0 0 0 2px;
 	padding: 0;
 	border: none;
 	border-radius: var(--border-radius, 4px);
@@ -328,18 +380,31 @@
 	cursor: pointer;
 }
 
-.cn-table-header__filter:hover {
+.cn-data-table th .cn-table-header__filter:hover {
 	background-color: var(--color-background-hover);
 	color: var(--color-main-text);
 }
 
-.cn-table-header__filter:focus-visible {
+.cn-data-table th .cn-table-header__filter:focus-visible {
 	outline: 2px solid var(--color-main-text);
 	outline-offset: 0;
 }
 
-.cn-table-header__filter--active {
-	color: var(--color-primary-element);
+.cn-data-table th .cn-table-header__filter--active,
+.cn-data-table th .cn-table-header__filter--active:hover {
+	color: var(--color-primary-element-light-text, var(--color-primary-element));
+}
+
+/* The active-filter dot, on the funnel's top right. */
+.cn-table-header__filter-dot {
+	position: absolute;
+	inset-block-start: 3px;
+	inset-inline-end: 3px;
+	width: 6px;
+	height: 6px;
+	border-radius: 50%;
+	background-color: var(--color-primary-element);
+	pointer-events: none;
 }
 
 /* Active header filters above the table, one removable chip each. */

package/src/index.js

@@ -542,6 +542,8 @@ export { cnFetch, cnFetchJson, CnHttpError, configureCnFetch } from './utils/cnF
 // CnLockIndicator, CnObjectCard and CnDataTable, and available to apps that
 // need the same answer without rendering a padlock.
 export { isLockedByCurrentUser, isObjectLocked, lockHolder, readLockPayload, resolveObjectLock } from './utils/objectLock.js'
+export { dispatchObjectsChanged } from './utils/objectSignals.js'
+export { lensUnavailableText, readLensReports } from './utils/lensAvailability.js'
 export { columnsFromSchema, fieldsFromSchema, filtersFromSchema, findRepeatingWrite, formatValue, journeyItemTargets, validateValue } from './utils/index.js'
 export { DYNAMIC_KEY_PREFIX, EXTENDS_FORM_KEY, PREFILL_KEY, splitDynamicFormData, usesArrayValues, valueArrayFor, valueRecordsFor } from './utils/index.js'
 // The OpenRegister schema API contract — shared so Buildiq and OpenRegister cannot
@@ -568,7 +570,7 @@ export {
 	SENTINEL_RESOLVERS,
 	warnIfDeprecated,
 } from './utils/resolveManifestTokens.js'
-export { filterWidgetsByVisibility, getCurrentUserGroups, getCurrentUserId, isWidgetVisible, resetVisibilityCache } from './utils/index.js'
+export { filterWidgetsByVisibility, getCurrentUserGroups, getCurrentUserId, isWidgetVisible, peekCurrentUserGroups, resetVisibilityCache } from './utils/index.js'
 export { safeHref, safeImageSrc, safeSvgPath } from './utils/index.js'
 export { followLinkClick, isModifiedClick, isNewTabHandled, isRowMiddleClick, openRowTarget, resolveHref } from './utils/index.js'
 export { resolveImageUrl } from './utils/index.js'

package/src/schemas/app-manifest-v2.schema.json

@@ -3,7 +3,7 @@
 	"$id": "https://raw.githubusercontent.com/ConductionNL/nextcloud-vue/main/src/schemas/app-manifest-v2.schema.json",
 	"title": "Conduction App Manifest v2",
 	"description": "v2 schema for the JSON-driven page and navigation manifest consumed by @conduction/nextcloud-vue. Introduces a uniform widgets[] array on every page type with a per-slot grid coordinate system, a typed actions[] discriminator, and the required $schema field for version detection. v1 manifests continue to validate against app-manifest.schema.json (unchanged).",
-	"version": "2.73.0",
+	"version": "2.75.0",
 	"type": "object",
 	"required": ["$schema", "version"],
 	"allOf": [
@@ -760,8 +760,8 @@
 		},
 		"sentinelFilterToken": {
 			"type": "string",
-			"pattern": "^@(?:me(?:\\.(?:displayName|email))?|now|today|monthStart|quarterStart|yearStart)$|^@today[+-][0-9]+d$",
-			"description": "Filter-value context: relative fetch-time tokens resolved by resolveFilterTokens (@me, @me.displayName, @me.email, @now, @today, @today±Nd, @monthStart, @quarterStart, @yearStart). Mirrors SENTINEL_TOKEN_PATTERNS.filter in src/utils/sentinelTokens.js (byte-equality enforced by a unit test)."
+			"pattern": "^@(?:me(?:\\.(?:displayName|email))?|myGroups|now|today|monthStart|quarterStart|yearStart)$|^@today[+-][0-9]+d$",
+			"description": "Filter-value context: relative fetch-time tokens resolved by resolveFilterTokens (@me, @me.displayName, @me.email, @myGroups (the current user's group ids, an IN list), @now, @today, @today±Nd, @monthStart, @quarterStart, @yearStart). Mirrors SENTINEL_TOKEN_PATTERNS.filter in src/utils/sentinelTokens.js (byte-equality enforced by a unit test)."
 		},
 		"sentinelConfigToken": {
 			"type": "string",
@@ -3304,19 +3304,23 @@
 					"properties": {
 						"favourite": {
 							"type": "boolean",
-							"description": "Detail pages: the star beside the title. Omitted means automatic: it shows when the object carries @self.favourite. false removes it."
+							"description": "Deprecated and ignored: there is no star any more, a favourite is a follow with notifications off. Kept so existing manifests stay valid; use follow."
 						},
 						"follow": {
 							"type": "boolean",
-							"description": "Detail pages: the Follow toggle beside the title, with the follower count for a user who may update the record. Omitted means automatic: it shows when the object carries @self.watching. false removes it, and the object read then no longer asks for @self.can."
+							"description": "Detail pages: the one Follow control beside the title, with a notifications on/off switch while the user follows and the follower count for a user who may update the record. Omitted means automatic: it shows when the object carries @self.watching. false removes it, and the object read then no longer asks for @self.can."
+						},
+						"showFollowColumn": {
+							"type": "boolean",
+							"description": "Index pages: add a first column with a follow toggle per row, bound to each row's @self.watching. Clicking it does not open the row. Default false."
 						},
 						"showFavouriteColumn": {
 							"type": "boolean",
-							"description": "Index pages: add a first column with a star per row, bound to each row's @self.favourite. Clicking it does not open the row. Default false."
+							"description": "Deprecated alias of showFollowColumn: the star column became the follow column. Default false."
 						},
 						"personalLenses": {
 							"type": "array",
-							"description": "Index pages: personal lenses added to the quick filters, in order. favourite lists the user's favourites, recent the records the user opened last (it owns the order, so column sorting is off), watching the records the user follows, unread the records changed since the user last looked. They combine with every other filter. Default none.",
+							"description": "Index pages: personal lenses added to the quick filters, in order. watching lists the records the user follows (labelled Following), recent the records the user opened last (it owns the order, so column sorting is off), unread the records changed since the user last looked. They combine with every other filter. favourite is a deprecated alias of watching; asking for both gives one tab. Default none.",
 							"items": { "enum": ["favourite", "recent", "watching", "unread"] },
 							"uniqueItems": true
 						},

package/src/store/plugins/interactions.js

@@ -3,7 +3,8 @@ import { listWatchers, setFavourite, setReadState, setWatcher, setWatching } fro
 /**
  * Interactions plugin for the object store.
  *
- * Per-user interaction calls on a record: favourite, follow (watch) and the
+ * Per-user interaction calls on a record: follow (watch, with its
+ * notifications switch), the deprecated favourite (a quiet follow), and the
  * followers list. Each write puts the server's answer into the stored object's
  * `@self`, so a list showing the same object agrees with the toggle.
  *
@@ -55,7 +56,10 @@ export function interactionsPlugin() {
 			},
 
 			/**
-			 * Star a record.
+			 * Star a record: a quiet follow on the server.
+			 *
+			 * @deprecated A favourite is a follow with notifications off since
+			 * OpenRegister's `merge-follow-and-favourites`; use `watch(type, id, { notify: false })`.
 			 *
 			 * @param {string} type The registered object type slug
 			 * @param {string} objectId The object ID
@@ -65,13 +69,15 @@ export function interactionsPlugin() {
 				const { register, schema } = this._interactionTarget(type)
 				const result = await setFavourite(register, schema, objectId, true)
 				if (result.ok) {
-					this._patchSelf(type, objectId, { favourite: true })
+					this._patchSelf(type, objectId, { favourite: true, watching: true })
 				}
 				return result
 			},
 
 			/**
-			 * Unstar a record.
+			 * Unstar a record: unfollow it.
+			 *
+			 * @deprecated Use `unwatch`.
 			 *
 			 * @param {string} type The registered object type slug
 			 * @param {string} objectId The object ID
@@ -81,7 +87,7 @@ export function interactionsPlugin() {
 				const { register, schema } = this._interactionTarget(type)
 				const result = await setFavourite(register, schema, objectId, false)
 				if (result.ok) {
-					this._patchSelf(type, objectId, { favourite: false })
+					this._patchSelf(type, objectId, { favourite: false, watching: false, watchNotify: undefined })
 				}
 				return result
 			},
@@ -119,17 +125,21 @@ export function interactionsPlugin() {
 			},
 
 			/**
-			 * Follow a record.
+			 * Follow a record, optionally setting its notifications switch.
 			 *
 			 * @param {string} type The registered object type slug
 			 * @param {string} objectId The object ID
+			 * @param {object} [options] Options
+			 * @param {boolean} [options.notify] The notifications switch; left out, a new follow notifies
 			 * @return {Promise<object>} The outcome
+			 * @spec openspec/changes/one-follow-control/specs/record-follow/spec.md#requirement-one-follow-control-with-a-notifications-switch
 			 */
-			async watch(type, objectId) {
+			async watch(type, objectId, options = {}) {
 				const { register, schema } = this._interactionTarget(type)
-				const result = await setWatching(register, schema, objectId, true)
+				const result = await setWatching(register, schema, objectId, true, options)
 				if (result.ok) {
-					this._patchSelf(type, objectId, { watching: true })
+					const notify = result.data && typeof result.data.notify === 'boolean' ? result.data.notify : true
+					this._patchSelf(type, objectId, { watching: true, favourite: true, watchNotify: notify })
 				}
 				return result
 			},
@@ -145,7 +155,7 @@ export function interactionsPlugin() {
 				const { register, schema } = this._interactionTarget(type)
 				const result = await setWatching(register, schema, objectId, false)
 				if (result.ok) {
-					this._patchSelf(type, objectId, { watching: false })
+					this._patchSelf(type, objectId, { watching: false, favourite: false, watchNotify: undefined })
 				}
 				return result
 			},

package/src/store/useObjectStore.js

@@ -6,6 +6,7 @@ import { genericError, networkError, parseResponseError } from '../utils/errors.
 import { normalizeFacets } from '../utils/facets.js'
 import { buildHeaders, buildQueryString, capitalize, prefixUrl } from '../utils/headers.js'
 import { extractId } from '../utils/id.js'
+import { readLensReports } from '../utils/lensAvailability.js'
 import { dispatchObjectCreated } from '../utils/walkthroughSignals.js'
 import { mergePluginActions, mergePluginGetters, mergePluginState } from './pluginMerge.js'
 import { liveUpdatesPlugin } from './plugins/liveUpdates.js'
@@ -86,6 +87,16 @@ function baseState(baseUrl = DEFAULT_BASE_URL) {
 		 * @type {{string: object}}
 		 */
 		facets: {},
+		/**
+		 * Personal-lens reports of the latest collection response per type:
+		 * the body's `@self.lenses` (`{ recent: { available, reason } }`),
+		 * `{}` when it carried none. Written with the rows, so it always
+		 * describes the page on screen.
+		 *
+		 * @type {{string: object}}
+		 * @spec openspec/changes/lens-says-why-it-is-empty/specs/personal-lens-availability/spec.md#requirement-a-list-response-carries-the-report-of-the-lenses-it-was-asked-for
+		 */
+		lenses: {},
 		/** @type {{baseUrl: string, organisationUuidGetter: (() => string|null)|null, languageGetter: (() => string|null)|null, targetLanguageGetter: (() => string|null)|null}} */
 		_options: {
 			baseUrl: prefixedBaseUrl,
@@ -195,6 +206,7 @@ const baseGetters = {
 	 * @return {(type: string) => object}
 	 */
 	getFacets: (state) => (type) => state.facets[type] || {},
+	getLenses: (state) => (type) => state.lenses[type] || {},
 }
 
 // ── Base actions ────────────────────────────────────────────────────────
@@ -240,9 +252,10 @@ const baseActions = {
 	 * @param {object} [slugs] Optional slug hints for live-updates transport
 	 * @param {string|null} [slugs.registerSlug] Canonical register slug (e.g. 'zaken')
 	 * @param {string|null} [slugs.schemaSlug]   Canonical schema slug (e.g. 'meldingen')
+	 * @param {string} [slugs.collectionUrl] Endpoint `fetchCollection` lists from instead of `/register/schema`; every other call keeps the pair URL
 	 */
 	registerObjectType(slug, schemaId, registerId, slugs = {}) {
-		const { registerSlug = null, schemaSlug = null } = slugs
+		const { registerSlug = null, schemaSlug = null, collectionUrl = null } = slugs
 		// Replace entire objects so Vue 2 reactivity detects the change
 		// (Vue 2 cannot track new properties added to existing reactive objects)
 		this.objectTypeRegistry = {
@@ -252,6 +265,7 @@ const baseActions = {
 				register: registerId,
 				registerSlug,
 				schemaSlug,
+				...(collectionUrl ? { collectionUrl } : {}),
 			},
 		}
 		this.collections = { ...this.collections, [slug]: [] }
@@ -263,6 +277,7 @@ const baseActions = {
 		this.schemas = { ...this.schemas, [slug]: null }
 		this.registers = { ...this.registers, [slug]: null }
 		this.facets = { ...this.facets, [slug]: {} }
+		this.lenses = { ...this.lenses, [slug]: {} }
 	},
 
 	/**
@@ -306,6 +321,7 @@ const baseActions = {
 		this.schemas = omit(this.schemas, slug)
 		this.registers = omit(this.registers, slug)
 		this.facets = omit(this.facets, slug)
+		this.lenses = omit(this.lenses, slug)
 	},
 
 	/**
@@ -439,6 +455,7 @@ const baseActions = {
 		this.collections = {}
 		this.objects = {}
 		this.facets = {}
+		this.lenses = {}
 		this.pagination = {}
 		// Errors + loading flags are per-fetch and don't need a reset.
 	},
@@ -496,6 +513,31 @@ const baseActions = {
 		return url
 	},
 
+	/**
+	 * Build the list URL for a type registered with a `collectionUrl`. `_order`
+	 * goes in the bracket form (`_order[key]=dir`) every PHP endpoint parses.
+	 *
+	 * @param {object} config The type config
+	 * @param {object} [params] Query parameters
+	 * @return {string} Full URL including query string
+	 */
+	_buildCollectionUrl(config, params = {}) {
+		const { _order: order, ...rest } = params
+		const merged = { ...rest }
+		if (order && typeof order === 'object') {
+			for (const [key, dir] of Object.entries(order)) {
+				merged[`_order[${key}]`] = dir
+			}
+		}
+		const lang = this._resolveLanguage()
+		if (lang) {
+			merged._lang = lang
+		}
+		const url = prefixUrl(config.collectionUrl)
+		const query = buildQueryString(merged)
+		return query && url.includes('?') ? url + '&' + query.slice(1) : url + query
+	},
+
 	/**
 	 * Fetch for a type, retrying ONCE with its `schemaFallback` when the
 	 * schema path segment answers 404. A type without a fallback (every type
@@ -685,14 +727,15 @@ const baseActions = {
 				}
 			}
 
-			const response = await this._fetchWithSchemaFallback(
-				type,
-				(schema) => this._buildUrlWithParams(type, fetchParams, null, schema),
-				{
-					method: 'GET',
-					headers: this._buildHeaders(),
-				},
-			)
+			const config = this._getTypeConfig(type)
+			const init = { method: 'GET', headers: this._buildHeaders() }
+			const response = config.collectionUrl
+				? await trackedFetch(this._buildCollectionUrl(config, fetchParams), init)
+				: await this._fetchWithSchemaFallback(
+						type,
+						(schema) => this._buildUrlWithParams(type, fetchParams, null, schema),
+						init,
+					)
 
 			if (!response.ok) {
 				const failure = await parseResponseError(response, type)
@@ -709,6 +752,8 @@ const baseActions = {
 			const results = data.results || data
 
 			this.collections = { ...this.collections, [type]: results }
+			// Why a personal lens came back empty, if it says (openregister#4514).
+			this.lenses = { ...this.lenses, [type]: readLensReports(data) }
 			this.pagination = {
 				...this.pagination,
 				[type]: {

package/src/utils/builtInFormatters.js

@@ -164,13 +164,15 @@ export function formatDaysUntil(value) {
 
 /**
  * Elapsed-time formatter (`daysSince` registry key), i18n'd through the
- * library's own translation slug (`nextcloud-vue`): a past date renders
- * "N days ago", today renders "Today", and a (nonsensical but harmless)
- * future date renders "In N days". Day counts are plural-aware via
- * `translatePlural`.
+ * library's own translation slug (`nextcloud-vue`) in the Nextcloud user
+ * language. Whole calendar days, read as a running phrase so it sits after a
+ * title or in a meta line: today renders "today", one day back renders
+ * "yesterday", further back renders "N days ago". A (nonsensical but
+ * harmless) future date renders "tomorrow" or "in N days". Day counts are
+ * plural-aware via `translatePlural`.
  *
  * Null-safe per the built-in-formatter contract: `''` for null/empty,
- * `String(value)` for unparseable input — never throws.
+ * `String(value)` for unparseable input, never throws.
  *
  * @param {unknown} value A `Date`, parseable date string, or timestamp.
  * @return {string} The relative-day phrasing (or ''/original on bad input).
@@ -185,13 +187,19 @@ export function formatDaysSince(value) {
 	}
 	const days = dayDiffFromToday(d)
 	if (days === 0) {
-		return t('nextcloud-vue', 'Today')
+		return t('nextcloud-vue', 'today')
+	}
+	if (days === -1) {
+		return t('nextcloud-vue', 'yesterday')
+	}
+	if (days === 1) {
+		return t('nextcloud-vue', 'tomorrow')
 	}
 	if (days < 0) {
 		const ago = Math.abs(days)
 		return n('nextcloud-vue', '{count} day ago', '{count} days ago', ago, { count: ago })
 	}
-	return n('nextcloud-vue', 'In {count} day', 'In {count} days', days, { count: days })
+	return n('nextcloud-vue', 'in {count} day', 'in {count} days', days, { count: days })
 }
 
 /**

package/src/utils/groupAutocomplete.js

@@ -14,6 +14,7 @@
 
 import axios from '@nextcloud/axios'
 import { generateOcsUrl } from '@nextcloud/router'
+import { reactive } from 'vue'
 
 const OCS_HEADERS = {
 	'OCS-APIRequest': 'true',
@@ -117,3 +118,77 @@ export async function resolveNextcloudGroup(gid) {
 	const results = await searchNextcloudGroups(String(gid))
 	return results.find((opt) => opt.id === String(gid)) || fallback
 }
+
+/**
+ * Display names already looked up, by group id. Reactive, so every cell that
+ * shows the same group updates when its name arrives.
+ *
+ * @type {Record<string, string>}
+ */
+const groupNames = reactive({})
+
+/** In-flight lookups by group id, so one id is asked for once. */
+const pendingNames = new Map()
+
+/**
+ * The cached display name of a group, or `null` when it has not been looked
+ * up yet. Reactive: read in a computed or a render, it updates when
+ * {@link loadGroupDisplayName} finishes.
+ *
+ * @spec openspec/changes/nextcloud-group-surfaces/specs/data-display/spec.md#requirement-a-group-cell-shows-the-groups-display-name
+ * @param {string} gid The group id.
+ * @return {string|null} The display name, or null when unknown.
+ */
+export function groupDisplayName(gid) {
+	if (gid === undefined || gid === null || gid === '') {
+		return null
+	}
+	const name = groupNames[String(gid)]
+	return typeof name === 'string' ? name : null
+}
+
+/**
+ * Look a group's display name up once per page and cache it. Concurrent
+ * callers for the same id share one request. A failed or empty lookup caches
+ * the id itself, so the cell shows the id and does not ask again.
+ *
+ * @spec openspec/changes/nextcloud-group-surfaces/specs/data-display/spec.md#requirement-a-group-cell-shows-the-groups-display-name
+ * @param {string} gid The group id.
+ * @return {Promise<string>} The display name, or the id.
+ */
+export function loadGroupDisplayName(gid) {
+	if (gid === undefined || gid === null || gid === '') {
+		return Promise.resolve('')
+	}
+	const key = String(gid)
+	const known = groupDisplayName(key)
+	if (known !== null) {
+		return Promise.resolve(known)
+	}
+	if (pendingNames.has(key)) {
+		return pendingNames.get(key)
+	}
+	const request = resolveNextcloudGroup(key)
+		.then((option) => (option && option.label) || key)
+		.catch(() => key)
+		.then((label) => {
+			groupNames[key] = label
+			pendingNames.delete(key)
+			return label
+		})
+	pendingNames.set(key, request)
+	return request
+}
+
+/**
+ * Forget every cached group name (tests, or after a group was renamed).
+ *
+ * @spec openspec/changes/nextcloud-group-surfaces/specs/data-display/spec.md#requirement-a-group-cell-shows-the-groups-display-name
+ * @return {void}
+ */
+export function clearGroupNameCache() {
+	pendingNames.clear()
+	for (const key of Object.keys(groupNames)) {
+		delete groupNames[key]
+	}
+}

package/src/utils/index.js

@@ -5,7 +5,7 @@ export { findRepeatingWrite, journeyItemTargets } from './journeyRepeatingWrite.
 export { columnsFromSchema, fieldsFromSchema, filtersFromSchema, formatValue, validateValue } from './schema.js'
 export { DYNAMIC_KEY_PREFIX, EXTENDS_FORM_KEY, PREFILL_KEY, splitDynamicFormData, usesArrayValues, valueArrayFor, valueRecordsFor } from './dynamicProperties.js'
 export { deleteSchema, describeSchemaChange, saveSchema, SchemaBreakingChangeError, SchemaHasObjectsError } from './schemaApi.js'
-export { filterWidgetsByVisibility, getCurrentUserGroups, getCurrentUserId, isWidgetVisible, resetVisibilityCache } from './widgetVisibility.js'
+export { filterWidgetsByVisibility, getCurrentUserGroups, getCurrentUserId, isWidgetVisible, peekCurrentUserGroups, resetVisibilityCache } from './widgetVisibility.js'
 export { isAppInstalled } from './appInstalled.js'
 export { getAssistantMark } from './assistantMark.js'
 export { passesContextPredicates } from './visibleIfContext.js'
@@ -19,3 +19,4 @@ export { validateFieldValue } from './formValidation.js'
 export { computeObjectDiff } from './computeObjectDiff.js'
 export { foldAuditTrailEntries } from './auditTrailDiff.js'
 export { isLockedByCurrentUser, isObjectLocked, lockHolder, readLockPayload, resolveObjectLock } from './objectLock.js'
+export { dispatchObjectsChanged } from './objectSignals.js'

package/src/utils/lensAvailability.js

@@ -0,0 +1,86 @@
+/**
+ * SPDX-FileCopyrightText: 2026 Conduction B.V.
+ * SPDX-License-Identifier: EUPL-1.2
+ *
+ * Why a personal lens (Recent, later Following) came back empty.
+ *
+ * OpenRegister reports per asked lens, at response level, whether it could
+ * answer: `@self.lenses.<lens> = { available, reason }` (openregister#4514,
+ * `read-history-on-audit-trail`). `available: false` always comes with an
+ * empty page. These helpers read that report and turn it into the short
+ * explanation a list shows in place of its generic empty text.
+ *
+ * The lens name is a key, so a later lens (`watching`) only needs copy.
+ *
+ * @spec openspec/changes/lens-says-why-it-is-empty/specs/personal-lens-availability/spec.md#requirement-an-unavailable-lens-explains-its-empty-page
+ */
+import { translate as t } from '@nextcloud/l10n'
+
+/**
+ * Built-in explanations per lens and reason. Object-neutral: the library
+ * does not know whether the app lists cases, tickets or documents. An app
+ * says it in its own words through `lensReasonTexts`.
+ *
+ * @return {Object<string, Object<string, string>>} Lens name to reason to text.
+ */
+function builtInTexts() {
+	return {
+		recent: {
+			'audit-trail-disabled': t('nextcloud-vue', 'This server does not keep track of what you open.'),
+			anonymous: t('nextcloud-vue', 'Log in to see what you opened recently.'),
+			'read-history-unavailable': t('nextcloud-vue', 'Your recent items are not available right now.'),
+		},
+	}
+}
+
+/**
+ * The lens reports of a list response body: `@self.lenses`, or `{}` when the
+ * body carries none (every response before openregister#4514, and every
+ * response that did not ask for a lens).
+ *
+ * @param {object|null|undefined} body A parsed list response.
+ * @return {Object<string, {available: boolean, reason: (string|null)}>} The reports, keyed by lens name.
+ * @spec openspec/changes/lens-says-why-it-is-empty/specs/personal-lens-availability/spec.md#requirement-a-list-response-carries-the-report-of-the-lenses-it-was-asked-for
+ */
+export function readLensReports(body) {
+	const lenses = body && typeof body === 'object' && body['@self'] && typeof body['@self'] === 'object'
+		? body['@self'].lenses
+		: null
+	return lenses && typeof lenses === 'object' && !Array.isArray(lenses) ? lenses : {}
+}
+
+/**
+ * The explanation for the first lens that reports `available: false` with a
+ * reason there is text for, or `''` when there is none (no report, every lens
+ * available, or a reason nobody wrote text for). The caller then shows its
+ * own empty text, as before.
+ *
+ * App text wins over built-in text; within app text, `<lens>.<reason>` wins
+ * over `<reason>`.
+ *
+ * @param {object|null|undefined} reports The lens reports (see `readLensReports`).
+ * @param {Object<string, string>|null} [overrides] App text keyed `<lens>.<reason>` or `<reason>`.
+ * @return {string} The explanation, or an empty string.
+ * @spec openspec/changes/lens-says-why-it-is-empty/specs/personal-lens-availability/spec.md#requirement-an-unavailable-lens-explains-its-empty-page
+ */
+export function lensUnavailableText(reports, overrides = null) {
+	if (!reports || typeof reports !== 'object') {
+		return ''
+	}
+	const own = overrides && typeof overrides === 'object' ? overrides : {}
+	const builtIn = builtInTexts()
+	for (const [lens, report] of Object.entries(reports)) {
+		if (!report || typeof report !== 'object' || report.available !== false) {
+			continue
+		}
+		const reason = typeof report.reason === 'string' ? report.reason : ''
+		if (reason === '') {
+			continue
+		}
+		const text = own[`${lens}.${reason}`] || own[reason] || (builtIn[lens] && builtIn[lens][reason]) || ''
+		if (text) {
+			return text
+		}
+	}
+	return ''
+}