@conduction/nextcloud-vue 2.68.0 → 2.69.0

package/src/utils/formatMetric.js

@@ -3,8 +3,16 @@
  * SPDX-License-Identifier: EUPL-1.2
  */
 
+import { getCanonicalLocale } from '@nextcloud/l10n'
 import { resolveFilterValue } from './resolveFilterTokens.js'
 
+/**
+ * The format styles a stat or stats-block entry may name.
+ *
+ * @type {Array<string>}
+ */
+export const METRIC_FORMAT_STYLES = ['number', 'currency', 'percent', 'duration-hours', 'decimal']
+
 /**
  * Unwrap a possibly-ref-wrapped `cnAppConfig` inject into a plain object.
  *
@@ -25,20 +33,25 @@ export function unwrapAppConfig(cnAppConfig) {
  * Resolve `@config.<key>` tokens in a `content.format` spec's string fields.
  *
  * Each of `currency` / `prefix` / `suffix` may be a `@config.<key>` token (e.g.
- * `currency: '@config.currency'`). Tokens are resolved against `configCtx`; a
- * token that stays unresolved (the config key is unset, or the config map has
- * not been injected yet during a route transition) is DROPPED so the downstream
- * literal default applies instead of a raw `@config.…` string leaking into
- * `Intl.NumberFormat`.
+ * `currency: '@config.currency'`), or an `@object.<field>` token read off the
+ * detail page's object when `object` is given. Tokens are resolved against
+ * `configCtx`; a token that stays unresolved (the config key is unset, or the
+ * config map has not been injected yet during a route transition) is DROPPED
+ * so the downstream literal default applies instead of a raw `@config.…`
+ * string leaking into `Intl.NumberFormat`.
  *
  * @param {object} format    The raw `content.format` spec.
  * @param {object} configCtx The page-level app-config map (from `unwrapAppConfig`).
+ * @param {object|null} [object] The detail page's object, for `@object.<field>` tokens.
  * @return {object} A copy of `format` with its string tokens resolved/dropped.
  */
-export function resolveConfigFormat(format, configCtx) {
+export function resolveConfigFormat(format, configCtx, object = null) {
 	const fmt = format || {}
 	const out = { ...fmt }
-	const ctx = { config: (configCtx && typeof configCtx === 'object') ? configCtx : {} }
+	const ctx = {
+		config: (configCtx && typeof configCtx === 'object') ? configCtx : {},
+		object: (object && typeof object === 'object') ? object : null,
+	}
 	for (const key of ['currency', 'prefix', 'suffix']) {
 		const raw = fmt[key]
 		if (typeof raw !== 'string' || raw.charAt(0) !== '@') {
@@ -68,6 +81,114 @@ export function safeCurrencyCode(currency) {
 		: 'EUR'
 }
 
+/**
+ * Whether a value is a three-letter currency code.
+ *
+ * @param {unknown} value The candidate.
+ * @return {boolean}
+ */
+function isCurrencyCode(value) {
+	return typeof value === 'string' && /^[A-Za-z]{3}$/.test(value)
+}
+
+/**
+ * Read a dot-path off an object.
+ *
+ * @param {object} object The object.
+ * @param {string} path The path, e.g. `currency` or `price.currency`.
+ * @return {unknown} The value, or undefined.
+ */
+function readPath(object, path) {
+	return String(path).split('.').reduce((acc, key) => (acc && typeof acc === 'object' ? acc[key] : undefined), object)
+}
+
+/**
+ * The currency a money value is shown in. In order:
+ *
+ * 1. `currencyField`: the field of the page's object that holds the currency
+ *    (a detail page; e.g. a contract's own `currency`).
+ * 2. `currency`: a literal code, or a token (`@config.currency`,
+ *    `@object.currency`).
+ * 3. The app's reporting currency, `currency` in the page's app config.
+ * 4. `EUR`.
+ *
+ * A step whose value is not a three-letter code is skipped, so an object
+ * without a currency falls back to the reporting currency instead of
+ * throwing in `Intl.NumberFormat`.
+ *
+ * @param {object} format The format spec (`{ currency?, currencyField? }`).
+ * @param {object} configCtx The page-level app-config map.
+ * @param {object|null} [object] The detail page's object.
+ * @return {string} An upper-case three-letter code.
+ * @spec openspec/changes/stat-currency-from-object/specs/dashboard-page/spec.md#requirement-a-money-value-is-shown-in-the-currency-the-entry-names
+ */
+export function resolveFormatCurrency(format, configCtx, object = null) {
+	const fmt = format || {}
+	if (typeof fmt.currencyField === 'string' && fmt.currencyField !== '' && object && typeof object === 'object') {
+		const own = readPath(object, fmt.currencyField)
+		if (isCurrencyCode(own)) {
+			return own.toUpperCase()
+		}
+	}
+	const declared = resolveConfigFormat({ currency: fmt.currency }, configCtx, object).currency
+	if (isCurrencyCode(declared)) {
+		return declared.toUpperCase()
+	}
+	const reporting = configCtx && typeof configCtx === 'object' ? configCtx.currency : undefined
+	return safeCurrencyCode(reporting)
+}
+
+/**
+ * The format spec of a stat or stats-block entry in one shape.
+ *
+ * `format` may be a style name (`"currency"`) or an object (`{ style,
+ * currency, currencyField, decimals, prefix, suffix }`). A sibling `currency`
+ * or `currencyField` on the entry itself fills the same keys, and either one
+ * makes the style `currency` when none is named. Answers null when the entry
+ * declares no format at all, so the caller keeps its own rendering.
+ *
+ * @param {object} entry The declaration (`{ format?, currency?, currencyField? }`).
+ * @return {object|null} The format spec, or null.
+ * @spec openspec/changes/stat-currency-from-object/specs/dashboard-page/spec.md#requirement-a-stats-block-entry-formats-its-value
+ */
+export function normalizeMetricFormat(entry) {
+	const source = entry && typeof entry === 'object' ? entry : {}
+	let fmt = null
+	if (typeof source.format === 'string' && source.format !== '') {
+		fmt = { style: source.format }
+	} else if (source.format && typeof source.format === 'object' && !Array.isArray(source.format)) {
+		fmt = { ...source.format }
+	}
+	for (const key of ['currency', 'currencyField']) {
+		if (typeof source[key] === 'string' && source[key] !== '') {
+			fmt = fmt || {}
+			if (fmt[key] === undefined) {
+				fmt[key] = source[key]
+			}
+		}
+	}
+	if (fmt && !fmt.style && (fmt.currency || fmt.currencyField)) {
+		fmt.style = 'currency'
+	}
+	return fmt
+}
+
+/**
+ * The user's locale for number formatting: the Nextcloud locale setting,
+ * else the browser's.
+ *
+ * @return {string|undefined} A BCP 47 tag, or undefined for the runtime default.
+ */
+export function metricLocale() {
+	try {
+		const tag = getCanonicalLocale()
+		// A tag Intl does not accept would throw a RangeError on every value.
+		return tag && Intl.NumberFormat.supportedLocalesOf([tag]).length > 0 ? tag : undefined
+	} catch {
+		return undefined
+	}
+}
+
 /**
  * Format a numeric value per a manifest `content.format` spec.
  *
@@ -85,12 +206,18 @@ export function safeCurrencyCode(currency) {
  *  - `decimal` is a plain number with ONE fraction digit by default (the
  *    fleet KPIs' `toFixed(1)` convention), where `number` defaults to 0.
  *
+ * The currency follows `resolveFormatCurrency`: the object's own currency
+ * (`currencyField`), then `currency`, then the app's reporting currency, then
+ * EUR. Numbers are formatted in the user's locale (`metricLocale`).
+ *
  * @param {unknown}      value     The raw value to format.
- * @param {object} format    The `content.format` spec (`{ style, currency, decimals, prefix, suffix }`).
+ * @param {object} format    The `content.format` spec (`{ style, currency, currencyField, decimals, prefix, suffix }`).
  * @param {object} configCtx The page-level app-config map for `@config.<key>` resolution.
+ * @param {object|null} [object] The detail page's object, for `currencyField` and `@object.<field>`.
  * @return {string} The formatted display string.
+ * @spec openspec/changes/stat-currency-from-object/specs/dashboard-page/spec.md#requirement-a-money-value-is-shown-in-the-currency-the-entry-names
  */
-export function formatMetricValue(value, format, configCtx) {
+export function formatMetricValue(value, format, configCtx, object = null) {
 	if (value === null || value === undefined) {
 		return '—'
 	}
@@ -99,7 +226,8 @@ export function formatMetricValue(value, format, configCtx) {
 		return String(value)
 	}
 
-	const fmt = resolveConfigFormat(format, configCtx)
+	const fmt = resolveConfigFormat(format, configCtx, object)
+	const locale = metricLocale()
 	// `duration-hours` and `decimal` default to ONE fraction digit; the
 	// other styles keep the pre-existing default of 0.
 	const oneDigitDefault = fmt.style === 'duration-hours' || fmt.style === 'decimal'
@@ -107,26 +235,26 @@ export function formatMetricValue(value, format, configCtx) {
 
 	let body
 	if (fmt.style === 'currency') {
-		body = new Intl.NumberFormat(undefined, {
+		body = new Intl.NumberFormat(locale, {
 			style: 'currency',
-			currency: safeCurrencyCode(fmt.currency),
+			currency: resolveFormatCurrency(format, configCtx, object),
 			minimumFractionDigits: decimals,
 			maximumFractionDigits: decimals,
 		}).format(num)
 	} else if (fmt.style === 'percent') {
 		// Values are stored as the literal percent (83.3), not a 0–1 ratio.
-		body = new Intl.NumberFormat(undefined, {
+		body = new Intl.NumberFormat(locale, {
 			minimumFractionDigits: decimals,
 			maximumFractionDigits: decimals,
 		}).format(num) + '%'
 	} else if (fmt.style === 'duration-hours') {
 		// An hour count (e.g. mean resolution time): `42.5h`.
-		body = new Intl.NumberFormat(undefined, {
+		body = new Intl.NumberFormat(locale, {
 			minimumFractionDigits: decimals,
 			maximumFractionDigits: decimals,
 		}).format(num) + 'h'
 	} else {
-		body = new Intl.NumberFormat(undefined, {
+		body = new Intl.NumberFormat(locale, {
 			minimumFractionDigits: decimals,
 			maximumFractionDigits: decimals,
 		}).format(num)