@conduction/nextcloud-vue 2.76.0 → 2.78.0

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 ────────────────────────────────────────────────────────
@@ -265,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]: {} }
 	},
 
 	/**
@@ -308,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)
 	},
 
 	/**
@@ -441,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.
 	},
@@ -737,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/badgeVariants.js

@@ -0,0 +1,29 @@
+/**
+ * SPDX-FileCopyrightText: 2026 Conduction B.V.
+ * SPDX-License-Identifier: EUPL-1.2
+ *
+ * badgeVariants: the colour variants a CnStatusBadge (a status pill) may take.
+ *
+ * The first six follow the Nextcloud colour roles. `purple` and `teal` are the
+ * two tones the drawn boards use for a status that has no Nextcloud role, such
+ * as "In behandeling" (work in progress) and "Omgezet naar een zaak" (handed
+ * on). One list, so the badge, the board card pill and the manifest schema
+ * accept the same names.
+ *
+ * @module utils/badgeVariants
+ * @spec openspec/changes/screens-cell-pill-parity/specs/cell-pill-tones/spec.md#requirement-a-status-pill-has-eight-tones
+ */
+
+/** Every variant a status pill accepts, in the order the docs list them. */
+export const BADGE_VARIANTS = Object.freeze(['default', 'primary', 'success', 'warning', 'error', 'info', 'purple', 'teal'])
+
+/**
+ * Whether a value names a badge variant.
+ *
+ * @param {unknown} variant The candidate variant.
+ * @return {boolean} True for one of `BADGE_VARIANTS`.
+ * @spec openspec/changes/screens-cell-pill-parity/specs/cell-pill-tones/spec.md#requirement-a-status-pill-has-eight-tones
+ */
+export function isBadgeVariant(variant) {
+	return typeof variant === 'string' && BADGE_VARIANTS.includes(variant)
+}

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'

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 ''
+}

package/src/utils/personalLenses.js

@@ -2,30 +2,37 @@
  * SPDX-FileCopyrightText: 2026 Conduction B.V.
  * SPDX-License-Identifier: EUPL-1.2
  *
- * The personal lenses of an index page (Favourites, Recent, Following) as
- * quick filters, appended after the page's own.
+ * The personal lenses of an index page (Following, Recent, Unread) as quick
+ * filters, appended after the page's own.
  *
- * @spec openspec/changes/record-favourite-and-follow/tasks.md#task-3
+ * There is no Favourites lens any more: a favourite is a follow with
+ * notifications off (OpenRegister `merge-follow-and-favourites`), so
+ * `favourite` is an alias of `watching` and asking for both gives one tab.
+ *
+ * @spec openspec/changes/one-follow-control/specs/record-follow/spec.md#requirement-index-pages-offer-one-following-lens-and-a-follow-column
  */
 import { translate as t } from '@nextcloud/l10n'
 
 /** Lens id to the query key OpenRegister reads. */
-export const LENS_FILTER_KEYS = { favourite: '_favourite', recent: '_recent', watching: '_watching', unread: '_unread' }
+export const LENS_FILTER_KEYS = { recent: '_recent', watching: '_watching', unread: '_unread' }
+
+/** Deprecated lens ids and the lens they now mean. */
+const LENS_ALIASES = { favourite: 'watching' }
 
 /**
  * Quick filters for the requested lenses. Unknown ids are ignored.
  *
- * @param {string[]} lenses Any of `favourite`, `recent`, `watching`, `unread`.
+ * @param {string[]} lenses Any of `watching`, `recent`, `unread`, and the deprecated `favourite` (read as `watching`).
  * @return {Array<{label: string, filter: object, lens: string}>} One tab per lens, in the order asked.
  */
 export function personalLensTabs(lenses) {
 	const labels = {
-		favourite: t('nextcloud-vue', 'Favourites'),
 		recent: t('nextcloud-vue', 'Recent'),
 		watching: t('nextcloud-vue', 'Following'),
 		unread: t('nextcloud-vue', 'Unread'),
 	}
 	return (Array.isArray(lenses) ? lenses : [])
+		.map((id) => (Object.hasOwn(LENS_ALIASES, id) ? LENS_ALIASES[id] : id))
 		.filter((id, i, all) => Object.hasOwn(LENS_FILTER_KEYS, id) && all.indexOf(id) === i)
 		.map((id) => ({ label: labels[id], filter: { [LENS_FILTER_KEYS[id]]: true }, lens: id }))
 }

package/src/utils/recordInteractions.js

@@ -2,8 +2,10 @@
  * SPDX-FileCopyrightText: 2026 Conduction B.V.
  * SPDX-License-Identifier: EUPL-1.2
  *
- * The per-user interaction calls OpenRegister serves on a record: favourite,
- * watch (follow) and the watchers list. Plain functions over `fetch`, shared
+ * The per-user interaction calls OpenRegister serves on a record: follow
+ * (watch, with its notifications switch), the watchers list, the read state,
+ * and the deprecated favourite (a quiet follow since OpenRegister's
+ * `merge-follow-and-favourites`). Plain functions over `fetch`, shared
  * by the interactions store plugin and by the toggles, so a toggle works with
  * or without the plugin installed.
  *
@@ -31,13 +33,18 @@ export function interactionUrl(register, schema, id, tail) {
 /**
  * Send one interaction call and normalise the answer. Never throws.
  *
- * @param {string} method HTTP method.
- * @param {string} url    Full URL.
+ * @param {string}      method HTTP method.
+ * @param {string}      url    Full URL.
+ * @param {object|null} [body] JSON body, or null for none.
  * @return {Promise<{ok: boolean, status: number|null, data: (object|null), message: string}>} The outcome; `message` is the server's, or a network message.
  */
-async function call(method, url) {
+async function call(method, url, body = null) {
 	try {
-		const response = await fetch(prefixUrl(url), { method, headers: buildHeaders() })
+		const init = { method, headers: buildHeaders() }
+		if (body !== null) {
+			init.body = JSON.stringify(body)
+		}
+		const response = await fetch(prefixUrl(url), init)
 		if (!response.ok) {
 			const error = await parseResponseError(response, 'record')
 			// The server's own words win over the generic status text.
@@ -61,6 +68,9 @@ async function call(method, url) {
 /**
  * Star or unstar a record for the current user.
  *
+ * @deprecated A star is a quiet follow since OpenRegister's
+ * `merge-follow-and-favourites`; use `setWatching(..., { notify: false })`.
+ *
  * @param {string}  register Register slug.
  * @param {string}  schema   Schema slug.
  * @param {string}  id       Object id.
@@ -72,16 +82,24 @@ export function setFavourite(register, schema, id, on) {
 }
 
 /**
- * Follow or unfollow a record for the current user.
+ * Follow or unfollow a record for the current user, optionally setting the
+ * follow's notifications switch.
  *
- * @param {string}  register Register slug.
- * @param {string}  schema   Schema slug.
- * @param {string}  id       Object id.
- * @param {boolean} on       True to follow, false to unfollow.
+ * `options.notify` is sent only when following and only when it is a boolean:
+ * left out, a new follow notifies and an existing follow keeps its setting.
+ *
+ * @param {string}  register         Register slug.
+ * @param {string}  schema           Schema slug.
+ * @param {string}  id               Object id.
+ * @param {boolean} on               True to follow, false to unfollow.
+ * @param {object}  [options]        Options.
+ * @param {boolean} [options.notify] The notifications switch.
  * @return {Promise<object>} The outcome (see `call`).
+ * @spec openspec/changes/one-follow-control/specs/record-follow/spec.md#requirement-one-follow-control-with-a-notifications-switch
  */
-export function setWatching(register, schema, id, on) {
-	return call(on ? 'PUT' : 'DELETE', interactionUrl(register, schema, id, 'watch'))
+export function setWatching(register, schema, id, on, options = {}) {
+	const body = on && options && typeof options.notify === 'boolean' ? { notify: options.notify } : null
+	return call(on ? 'PUT' : 'DELETE', interactionUrl(register, schema, id, 'watch'), body)
 }
 
 /**

package/src/utils/resolveFilterTokens.js

@@ -10,6 +10,13 @@
  * Supported tokens:
  *  - `@me`                → the current Nextcloud user id (`getCurrentUser()` from
  *                           `@nextcloud/auth`; `window.OC.currentUser` fallback)
+ *  - `@myGroups`          → the ids of the Nextcloud groups the current user is
+ *                           in, as an ARRAY (an IN filter). `ctx.myGroups` wins;
+ *                           otherwise a reactive peek over `getCurrentUserGroups`.
+ *                           Stays UNRESOLVED while loading and when the user is
+ *                           in no group, so the caller waits instead of sending
+ *                           an empty IN list (which OpenRegister reads as "no
+ *                           constraint"). Spread in place inside an IN-list array.
  *  - `@now`               → the current instant, ISO-8601
  *  - `@today`             → today at 00:00, `YYYY-MM-DD` (date-prefix comparable)
  *  - `@today±Nd`          → relative-date arithmetic at day granularity: N days
@@ -56,6 +63,34 @@
 
 import { getCurrentUser } from '@nextcloud/auth'
 import { TODAY_DELTA_RE } from './sentinelTokens.js'
+import { peekCurrentUserGroups } from './widgetVisibility.js'
+
+/** The filter token for the current user's group ids. */
+export const MY_GROUPS_TOKEN = '@myGroups'
+
+/**
+ * Resolve `@myGroups`: the current user's group ids, or the token itself while
+ * they are loading or when there are none (an empty IN list would match every
+ * row, so "no team" must mean "wait", never "everything").
+ *
+ * @spec openspec/changes/nextcloud-group-surfaces/specs/schema-utilities/spec.md#requirement-mygroups-resolves-to-the-current-users-group-ids
+ * @param {{myGroups?: string[]}} [ctx] Optional context; `ctx.myGroups` wins.
+ * @return {string[]|string} The group ids, or `'@myGroups'` when unresolved.
+ */
+function resolveMyGroups(ctx) {
+	let groups = ctx && Array.isArray(ctx.myGroups) ? ctx.myGroups : null
+	if (groups === null) {
+		try {
+			groups = peekCurrentUserGroups()
+		} catch {
+			groups = null
+		}
+	}
+	const ids = Array.isArray(groups)
+		? groups.filter((g) => typeof g === 'string' && g !== '')
+		: []
+	return ids.length > 0 ? [...ids] : MY_GROUPS_TOKEN
+}
 
 /**
  * Format a Date as `YYYY-MM-DD` (local).
@@ -73,7 +108,7 @@ function ymd(d) {
  * Resolve a single filter value if it is a dynamic `@`-token, else pass through.
  *
  * @param {unknown} v The candidate value.
- * @param {{objectId?: (string|number), object?: object, workspace?: object, config?: object, range?: object}} [ctx] Optional
+ * @param {{objectId?: (string|number), object?: object, workspace?: object, config?: object, range?: object, myGroups?: string[]}} [ctx] Optional
  *   context for `@objectId` / `@object.<field>` (detail page),
  *   `@workspace.<key>` (page-level workspace state), and `@config.<key>`
  *   (page-level app config) tokens.
@@ -84,6 +119,9 @@ export function resolveFilterValue(v, ctx) {
 		return v
 	}
 	const now = new Date()
+	if (v === MY_GROUPS_TOKEN) {
+		return resolveMyGroups(ctx)
+	}
 	if (v === '@objectId') {
 		return (ctx && ctx.objectId !== undefined && ctx.objectId !== null) ? String(ctx.objectId) : v
 	}
@@ -313,8 +351,13 @@ export function resolveFilterTokens(filter, ctx) {
 	if (!filter || typeof filter !== 'object') {
 		return filter
 	}
+	// An item that resolves to a list (`@myGroups`) is spread in place, so
+	// `['@myGroups', 'archive']` stays one flat IN list.
 	const resolveOne = (v) => (Array.isArray(v)
-		? v.map((item) => resolveFilterValue(item, ctx))
+		? v.flatMap((item) => {
+				const r = resolveFilterValue(item, ctx)
+				return Array.isArray(r) ? r : [r]
+			})
 		: resolveFilterValue(v, ctx))
 	const out = {}
 	for (const [k, v] of Object.entries(filter)) {

package/src/utils/schema.js

@@ -385,7 +385,7 @@ function isUserProp(prop) {
  * @param {object} prop A schema property definition (or `items` for an array).
  * @return {boolean} True when the property marks a Nextcloud group.
  */
-function isGroupProp(prop) {
+export function isGroupProp(prop) {
 	if (!prop || typeof prop !== 'object') {
 		return false
 	}

package/src/utils/sentinelTokens.js

@@ -26,7 +26,7 @@
  * A token is valid only in the context whose resolver runs on it:
  *
  *  - **filter**       — `resolveFilterTokens`, resolved at fetch time:
- *                       `@me`, `@now`, `@today`, `@today±Nd`, `@monthStart`,
+ *                       `@me`, `@myGroups`, `@now`, `@today`, `@today±Nd`, `@monthStart`,
  *                       `@quarterStart`, `@yearStart`.
  *  - **config**       — `IAppConfig`-sourced: `@resolve:<key>`, `@config.<key>`
  *                       (trailing `?` marks optional).
@@ -67,7 +67,7 @@
  * @type {Readonly<Record<string, string>>}
  */
 export const SENTINEL_TOKEN_PATTERNS = Object.freeze({
-	filter: '^@(?:me(?:\\.(?:displayName|email))?|now|today|monthStart|quarterStart|yearStart)$|^@today[+-][0-9]+d$',
+	filter: '^@(?:me(?:\\.(?:displayName|email))?|myGroups|now|today|monthStart|quarterStart|yearStart)$|^@today[+-][0-9]+d$',
 	config: '^@resolve:[a-z][a-z0-9_-]*$|^@config\\.[A-Za-z][A-Za-z0-9_.]*\\??$',
 	object: '^@objectId$|^@object\\.[A-Za-z][A-Za-z0-9_]*$',
 	workspace: '^@workspace\\.[A-Za-z][A-Za-z0-9_]*\\??$',
@@ -116,8 +116,8 @@ export const SENTINEL_CONTEXTS = Object.freeze([
 export const SENTINEL_VOCABULARY = Object.freeze({
 	filter: {
 		resolver: 'resolveFilterTokens',
-		description: 'Relative fetch-time tokens (current user / relative dates).',
-		members: ['@me', '@me.displayName', '@me.email', '@now', '@today', '@today±Nd', '@monthStart', '@quarterStart', '@yearStart'],
+		description: 'Relative fetch-time tokens (current user, the current user\'s groups as an IN list, relative dates).',
+		members: ['@me', '@me.displayName', '@me.email', '@myGroups', '@now', '@today', '@today±Nd', '@monthStart', '@quarterStart', '@yearStart'],
 	},
 	config: {
 		resolver: 'resolveManifestSentinels / resolveFilterTokens',