@conduction/nextcloud-vue 2.73.0 → 2.73.1

package/src/utils/notificationRuleLabel.js

@@ -0,0 +1,129 @@
+/**
+ * SPDX-FileCopyrightText: 2026 Conduction B.V. <info@conduction.nl>
+ * SPDX-License-Identifier: EUPL-1.2
+ *
+ * The label a person reads for one notification rule in their settings.
+ *
+ * A rule is declared in a schema's `x-openregister-notifications` map under a
+ * KEY (`caseAssigned`, `clientUpdated`, `onCreate`). The key is an identifier
+ * for a developer. The settings pane used to print it as is, so a person saw
+ * "substitutionRegisteredForSubstitute" next to a switch and had to guess.
+ *
+ * The label is taken from the first source that has one, most specific first:
+ *
+ *   1. the rule's own words, when OpenRegister passes them on the preference
+ *      entry (`label`, then `title`), as a plain string or a per-locale map
+ *      like the dialect's `subject` (`{ "nl": "…", "en": "…" }`);
+ *   2. the app's own label for the rule, from the `labels` map the app hands
+ *      to CnAppRoot (`notificationLabels`), keyed `<schema>.<key>` or `<key>`;
+ *   3. the library's wording for the generic object-event keys;
+ *   4. the key made readable: `caseAssigned` becomes "Case assigned".
+ *
+ * The rule's `subject` is used only when it carries no `{{placeholder}}`: it
+ * is the notification TITLE template, and "Case "{{title}}" assigned to you"
+ * reads worse as a setting than the readable key does.
+ *
+ * Pure: no store, no fetch, no Vue.
+ *
+ * @spec openspec/changes/notification-rule-labels-and-runtime-version/specs/notification-preferences/spec.md
+ */
+
+/**
+ * Pick the string for the current language out of a string or per-locale map.
+ *
+ * @param {string|object|null|undefined} value A string, or `{ nl, en, … }`.
+ * @param {string} [language] The current language, e.g. `nl` or `de_DE`.
+ * @return {string} The resolved text, or '' when there is none.
+ */
+export function resolveLocalised(value, language = 'en') {
+	if (typeof value === 'string') {
+		return value.trim()
+	}
+	if (!value || typeof value !== 'object' || Array.isArray(value)) {
+		return ''
+	}
+	const lang = String(language || 'en')
+	const base = lang.split(/[-_]/)[0]
+	for (const candidate of [lang, base, 'en']) {
+		if (typeof value[candidate] === 'string' && value[candidate].trim() !== '') {
+			return value[candidate].trim()
+		}
+	}
+	const first = Object.values(value).find((text) => typeof text === 'string' && text.trim() !== '')
+	return first ? first.trim() : ''
+}
+
+/**
+ * Make a rule key readable: split camelCase, snake_case and kebab-case into
+ * words, keep acronyms, and capitalise only the first word.
+ *
+ * `caseAssigned` → "Case assigned", `object_created` → "Object created",
+ * `newBRPRecord` → "New BRP record".
+ *
+ * @param {string} key The rule key.
+ * @return {string} A readable sentence-case label, or the key when it has no words.
+ */
+export function humaniseRuleKey(key) {
+	const words = String(key || '')
+		.replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+		.replace(/([A-Z]+)([A-Z][a-z])/g, '$1 $2')
+		.split(/[\s_\-.]+/)
+		.filter(Boolean)
+	if (words.length === 0) {
+		return String(key || '')
+	}
+	return words
+		.map((word, index) => {
+			const isAcronym = word.length > 1 && word === word.toUpperCase() && /[A-Z]/.test(word)
+			if (isAcronym) {
+				return word
+			}
+			const lower = word.toLowerCase()
+			return index === 0 ? lower.charAt(0).toUpperCase() + lower.slice(1) : lower
+		})
+		.join(' ')
+}
+
+/**
+ * The label for one preference entry.
+ *
+ * @param {object} entry A preference entry: `{ schema, notification, label?, title?, subject? }`.
+ * @param {object} [options] Where else a label may come from.
+ * @param {object} [options.labels] App-supplied labels keyed `<schema>.<key>` or `<key>`;
+ *   values are strings or per-locale maps.
+ * @param {object} [options.known] Library wording for generic keys, keyed by rule key.
+ * @param {string} [options.language] The current language.
+ * @return {string} The label to show.
+ */
+export function notificationRuleLabel(entry, { labels = {}, known = {}, language = 'en' } = {}) {
+	const key = String(entry?.notification ?? '')
+	const schema = String(entry?.schema ?? '')
+
+	for (const field of ['label', 'title']) {
+		const own = resolveLocalised(entry?.[field], language)
+		if (own) {
+			return own
+		}
+	}
+
+	const map = labels && typeof labels === 'object' ? labels : {}
+	for (const lookup of [schema ? `${schema}.${key}` : '', key]) {
+		if (lookup && Object.hasOwn(map, lookup)) {
+			const fromApp = resolveLocalised(map[lookup], language)
+			if (fromApp) {
+				return fromApp
+			}
+		}
+	}
+
+	if (known && typeof known[key] === 'string' && known[key]) {
+		return known[key]
+	}
+
+	const subject = resolveLocalised(entry?.subject, language)
+	if (subject && !subject.includes('{{')) {
+		return subject
+	}
+
+	return humaniseRuleKey(key)
+}

package/webpack/index.d.ts

@@ -28,3 +28,19 @@ export interface CnPublicPathOptions {
  * @param options Where the public path is read from at runtime.
  */
 export function withPublicPath<T extends object | object[]>(config: T, options?: CnPublicPathOptions): T
+
+export interface CnAppVersionDefineOptions {
+	/** The initial-state key the app's page provides its version under. Defaults to `version`. */
+	key?: string
+}
+
+/**
+ * A `webpack.DefinePlugin` expression for `appVersion` that reads the
+ * installed app version from the page's initial state at runtime, falling
+ * back to `fallback` (the build-time version) when the state is absent.
+ *
+ * @param appId The app id.
+ * @param fallback The build-time version.
+ * @param options Which initial-state key to read.
+ */
+export function appVersionDefine(appId: string, fallback?: string, options?: CnAppVersionDefineOptions): string

package/webpack/index.js

@@ -116,7 +116,77 @@ function withPublicPath(config, options = {}) {
 	}
 }
 
+/**
+ * The `appVersion` define, resolved in the browser from the INSTALLED app.
+ *
+ * THE PROBLEM
+ * -----------
+ * `@nextcloud/vue` prints `<app name> <appVersion>` in the footer of every
+ * NcAppSettingsDialog, and reads `appVersion` as a global the app's webpack
+ * config defines. Apps defined it from `package.json` (a `0.1.0` nobody bumps,
+ * so pipelinq read "pipelinq 0.1.0") or from `appinfo/info.xml` at build time.
+ * The second is still wrong on every release: the release workflow writes the
+ * release version into `info.xml` after the bundle is built, so dossiq
+ * 0.4.48-beta said "dossiq 0.4.47-unstable". A build cannot know the version
+ * it will be installed as.
+ *
+ * THE FIX
+ * -------
+ * Define `appVersion` as an EXPRESSION, not a literal. It runs once in the
+ * browser and reads the app's `version` initial state, which the app's page
+ * controller provides from what Nextcloud has installed
+ * (`IAppConfig::getValueString($appId, 'installed_version')`). It reads the
+ * same hidden input `@nextcloud/initial-state` `loadState()` reads; it cannot
+ * import that package because a define is pasted into every module as code.
+ * When the state is missing (a page that does not provide it, a test, a
+ * worker without a document) it falls back to the build-time version.
+ *
+ * USAGE
+ * -----
+ * ```js
+ * // webpack.config.js
+ * const { appVersionDefine } = require('@conduction/nextcloud-vue/webpack')
+ * new webpack.DefinePlugin({ appVersion: appVersionDefine('dossiq', readAppVersion()) })
+ * ```
+ * ```php
+ * // the controller that renders the app's page
+ * $this->initialState->provideInitialState('version', $this->appConfig->getValueString('dossiq', 'installed_version', ''));
+ * ```
+ *
+ * @param {string} appId The app id, as used for its initial state.
+ * @param {string} [fallback] The version to show when no initial state is
+ *   present, normally the build-time `info.xml` version.
+ * @param {object} [options] Options.
+ * @param {string} [options.key] The initial-state key. Defaults to `version`.
+ *
+ * @return {string} A JavaScript expression for `webpack.DefinePlugin`.
+ *
+ * @throws {TypeError} When `appId` is empty.
+ *
+ * @spec openspec/changes/notification-rule-labels-and-runtime-version/specs/notification-preferences/spec.md
+ */
+function appVersionDefine(appId, fallback = '', options = {}) {
+	const id = String(appId || '').trim()
+	if (id === '') {
+		throw new TypeError('appVersionDefine() needs the app id whose installed version it reads')
+	}
+	const key = String(options.key || 'version')
+	const elementId = JSON.stringify('initial-state-' + id + '-' + key)
+	const fallbackLiteral = JSON.stringify(String(fallback ?? ''))
+	return '(function () {'
+		+ ' try {'
+		+ ' var el = typeof document !== "undefined" && document.getElementById(' + elementId + ');'
+		+ ' if (el && el.value) {'
+		+ ' var v = JSON.parse(atob(el.value));'
+		+ ' if (typeof v === "string" && v !== "") { return v; }'
+		+ ' }'
+		+ ' } catch (e) {}'
+		+ ' return ' + fallbackLiteral + ';'
+		+ ' })()'
+}
+
 module.exports = {
 	AUTO_PUBLIC_PATH,
+	appVersionDefine,
 	withPublicPath,
 }