@antelopejs/dms 0.9.8 → 0.10.0

package/frontend-vue/layers/dms-core/app/utils/formatter.ts

@@ -20,8 +20,6 @@ const TIME_UNITS = {
   ms: 1,
 } as const;
 
-const TIME_UNIT_ORDER = ["y", "M", "w", "d", "h", "m", "s", "ms"] as const;
-
 type TranslateFunction = (
   key: string,
   params?: Record<string, unknown>,
@@ -229,9 +227,56 @@ export function formatDateTime(
   });
 }
 
+// The narrow no-break space French (and a few other locales) groups digits
+// with: the interface's font draws it a fraction of a digit wide, so "1 234"
+// read as "1234" beside a column's "12 345". Groups take a full no-break space.
+const NARROW_GROUP_SEPARATOR = " ";
+const GROUP_SEPARATOR = " ";
+
+/** `Intl.NumberFormat`, its digit groups always shown and visible. */
+export interface ReadableNumberFormat {
+  format(value: number): string;
+  formatToParts(value: number): Intl.NumberFormatPart[];
+  resolvedOptions(): Intl.ResolvedNumberFormatOptions;
+}
+
+function readablePart(part: Intl.NumberFormatPart): Intl.NumberFormatPart {
+  return part.type === "group" && part.value === NARROW_GROUP_SEPARATOR
+    ? { ...part, value: GROUP_SEPARATOR }
+    : part;
+}
+
+/**
+ * `new Intl.NumberFormat(locale, options)` the way the interface writes a
+ * figure: a four-digit one grouped like a longer one ("1 234" next to
+ * "12 345", where Spanish or Polish would leave "1234" by default), with a
+ * group separator wide enough to see. `options.useGrouping` still decides.
+ * Throws as `Intl.NumberFormat` does on options it refuses.
+ */
+export function readableNumberFormat(
+  locale?: string,
+  options?: Intl.NumberFormatOptions,
+): ReadableNumberFormat {
+  const format = new Intl.NumberFormat(locale, {
+    useGrouping: true,
+    ...options,
+  });
+  const formatToParts = (value: number) =>
+    format.formatToParts(value).map(readablePart);
+  return {
+    format: (value) =>
+      formatToParts(value)
+        .map((part) => part.value)
+        .join(""),
+    formatToParts,
+    resolvedOptions: () => format.resolvedOptions(),
+  };
+}
+
 /**
- * A number written for `locale`; a value that is not a number is returned as
- * is. Options Intl refuses (an unknown currency) write the bare number.
+ * A number written for `locale` (see {@link readableNumberFormat}); a value
+ * that is not a number is returned as is. Options Intl refuses (an unknown
+ * currency) write the bare number.
  */
 export function formatNumber(
   value: number,
@@ -250,7 +295,7 @@ export function formatNumber(
 ): unknown {
   if (!isNumber(value)) return value;
   try {
-    return new Intl.NumberFormat(locale, options).format(value);
+    return readableNumberFormat(locale, options).format(value);
   } catch {
     return String(value);
   }
@@ -312,16 +357,19 @@ const TIME_SPAN_UNITS: Record<string, keyof typeof TIME_UNITS> = {
   w: "w",
   d: "d",
   h: "h",
+  min: "m",
   m: "m",
   s: "s",
   ms: "ms",
 };
 
-// `01:30`, `26:00:30`: hours, then minutes and seconds under 60.
+// `01:30`, `8:15`, `26:00:30`: hours, then minutes and seconds under 60.
 const CLOCK_SPAN = /^(\d+):([0-5]\d)(?::([0-5]\d))?$/;
-// `1h30m`, `1h 30m`, `1h:30m` (what `formatTimeSpan` writes), `1.5h`.
-const UNIT_SPAN = /^(?:\d+(?:\.\d+)?(?:ms|mo|[Mmwydhs])[\s:]*)+$/;
-const UNIT_SPAN_PART = /(\d+(?:\.\d+)?)(ms|mo|[Mmwydhs])/g;
+// `8h15`, `8 h 05`: hours, then bare minutes, the way a time is often written.
+const HOUR_MINUTE_SPAN = /^(\d+)\s*h\s*([0-5]?\d)$/i;
+// `1h30m`, `1h 30m`, `7 h 30 min`, `1h:30m` (older displays), `1.5h`.
+const UNIT_SPAN = /^(?:\d+(?:[.,]\d+)?\s*(?:ms|mo|min|[Mmwydhs])[\s:]*)+$/;
+const UNIT_SPAN_PART = /(\d+(?:[.,]\d+)?)\s*(ms|mo|min|[Mmwydhs])/g;
 
 function readClockSpan(text: string): number | undefined {
   const match = CLOCK_SPAN.exec(text);
@@ -334,24 +382,38 @@ function readClockSpan(text: string): number | undefined {
   );
 }
 
+function readHourMinuteSpan(text: string): number | undefined {
+  const match = HOUR_MINUTE_SPAN.exec(text);
+  if (!match) return undefined;
+  const [, hours, minutes] = match;
+  return Number(hours) * TIME_UNITS.h + Number(minutes) * TIME_UNITS.m;
+}
+
 function readUnitSpan(text: string): number | undefined {
   if (!UNIT_SPAN.test(text)) return undefined;
   let total = 0;
   for (const [, amount, unit] of text.matchAll(UNIT_SPAN_PART)) {
-    total += Number.parseFloat(amount!) * TIME_UNITS[TIME_SPAN_UNITS[unit!]!];
+    const value = Number.parseFloat(amount!.replace(",", "."));
+    total += value * TIME_UNITS[TIME_SPAN_UNITS[unit!]!];
   }
   return total;
 }
 
 /**
- * A duration typed in, in milliseconds: a clock duration (`01:30`,
- * `26:00:30`) or units (`1h30m`, `1h 30m`, `1.5h`), or `undefined` for a
- * text that is neither.
+ * A duration typed in, in milliseconds: a clock duration (`01:30`, `8:15`,
+ * `26:00:30`), hours then minutes (`8h15`, `8h`) or units (`1h30m`,
+ * `1h 30m`, `7 h 30 min`, `1.5h`), a `-` before any of them for a negative
+ * one, or `undefined` for a text that is neither. It reads all
+ * {@link formatDuration} writes.
  */
 export function readTimeSpan(value: string): number | undefined {
-  const text = value.trim();
+  const trimmed = value.trim();
+  const isNegative = trimmed.startsWith("-");
+  const text = isNegative ? trimmed.slice(1).trimStart() : trimmed;
   if (!text) return undefined;
-  return readClockSpan(text) ?? readUnitSpan(text);
+  const span =
+    readClockSpan(text) ?? readHourMinuteSpan(text) ?? readUnitSpan(text);
+  return span !== undefined && isNegative ? -span : span;
 }
 
 export function parseTimeSpan(value: string | number): number {
@@ -359,30 +421,99 @@ export function parseTimeSpan(value: string | number): number {
   return readTimeSpan(value) ?? 0;
 }
 
-const DEFAULT_SEPARATOR = ":";
-const ZERO_MS = "0ms";
+// Durations count in hours at most: a day or a month is a calendar span, not
+// a number of hours.
+const DURATION_UNITS = [
+  { symbol: "h", ms: TIME_UNITS.h, fractionDigits: 0 },
+  { symbol: "min", ms: TIME_UNITS.m, fractionDigits: 0 },
+  // The seconds carry the milliseconds, so nothing is rounded away.
+  { symbol: "s", ms: TIME_UNITS.s, fractionDigits: 3 },
+] as const;
+const MS_FRACTION_DIGITS = 3;
 
-export function formatTimeSpan(
-  ms: unknown,
-  separator: string = DEFAULT_SEPARATOR,
-): string {
-  if (!isNumber(ms)) return String(ms);
+/**
+ * How exact a written duration is: `exact` (the default) keeps every
+ * millisecond, so a field shows the value it holds and {@link readTimeSpan}
+ * reads it back; `rounded` keeps two units at most, the smaller one rounded
+ * ("2.1 s", "4 min 12 s", "7 h 30 min"), for a cell read at a glance.
+ */
+export type DurationPrecision = "exact" | "rounded";
+
+export interface DurationFormatOptions {
+  precision?: DurationPrecision;
+}
 
-  const totalMs = Number(ms);
-  if (totalMs === 0) return ZERO_MS;
+const ROUNDED_SECONDS_FRACTION_DIGITS = 1;
 
+function durationFigure(
+  locale: string,
+  value: number,
+  symbol: string,
+  fractionDigits: number,
+): string {
+  const figure = readableNumberFormat(locale, {
+    maximumFractionDigits: fractionDigits,
+    useGrouping: false,
+    numberingSystem: "latn",
+  }).format(value);
+  return `${figure} ${symbol}`;
+}
+
+function exactDuration(ms: number, locale: string): string {
+  let remaining = ms;
+  if (remaining < TIME_UNITS.s) {
+    return durationFigure(locale, remaining, "ms", MS_FRACTION_DIGITS);
+  }
   const parts: string[] = [];
-  let remaining = Math.abs(totalMs);
-
-  for (const unit of TIME_UNIT_ORDER) {
-    const unitValue = TIME_UNITS[unit];
-    if (remaining >= unitValue) {
-      const value = Math.floor(remaining / unitValue);
-      parts.push(`${value}${unit}`);
-      remaining %= unitValue;
-    }
+  for (const { symbol, ms: unitMs, fractionDigits } of DURATION_UNITS) {
+    const amount = fractionDigits
+      ? remaining / unitMs
+      : Math.floor(remaining / unitMs);
+    remaining -= amount * unitMs;
+    if (amount)
+      parts.push(durationFigure(locale, amount, symbol, fractionDigits));
   }
+  return parts.join(" ");
+}
+
+function roundedDuration(ms: number, locale: string): string {
+  if (ms < TIME_UNITS.s) return durationFigure(locale, Math.round(ms), "ms", 0);
+  if (ms < TIME_UNITS.m) {
+    return durationFigure(
+      locale,
+      ms / TIME_UNITS.s,
+      "s",
+      ROUNDED_SECONDS_FRACTION_DIGITS,
+    );
+  }
+  const [major, majorSymbol, minor, minorSymbol] =
+    ms < TIME_UNITS.h
+      ? ([TIME_UNITS.m, "min", TIME_UNITS.s, "s"] as const)
+      : ([TIME_UNITS.h, "h", TIME_UNITS.m, "min"] as const);
+  // Rounded as a whole first, so 1 min 59.7 s reads "2 min", not "1 min 60 s".
+  const total = Math.round(ms / minor) * minor;
+  const whole = Math.floor(total / major);
+  const rest = (total - whole * major) / minor;
+  const head = durationFigure(locale, whole, majorSymbol, 0);
+  return rest
+    ? `${head} ${durationFigure(locale, rest, minorSymbol, 0)}`
+    : head;
+}
 
-  const formatted = parts.join(separator);
-  return totalMs < 0 ? `-${formatted}` : formatted;
+/**
+ * A duration in milliseconds the way people write it, its figures in the
+ * reader's locale: "910 ms", "2.149 s", "4 min 12 s", "7 h 30 min". The one
+ * writer of a duration, for a field and a cell alike. Exact by default (hours
+ * and minutes whole, the seconds carrying the milliseconds), its figures
+ * neither grouped nor in another script, so {@link readTimeSpan} reads back
+ * the very value it wrote; `precision: "rounded"` for a cell.
+ */
+export function formatDuration(
+  ms: number,
+  locale: string,
+  { precision = "exact" }: DurationFormatOptions = {},
+): string {
+  const sign = ms < 0 ? "-" : "";
+  const write = precision === "rounded" ? roundedDuration : exactDuration;
+  return sign + write(Math.abs(ms), locale);
 }

package/frontend-vue/layers/dms-core/app/utils/url-interpolation.ts

@@ -12,8 +12,25 @@ const WHOLE_ROW_TOKEN = new RegExp(`^\\s*${ROW_TOKEN.source}\\s*$`);
 export const namesRowField = (template: string): boolean =>
   new RegExp(ROW_TOKEN.source).test(template);
 
+// A relation field is listed as the related row (a join): it stands for that
+// row's id, as the field stores it, rather than "[object Object]". A dotted
+// path (`{{row.customer.name}}`) still reaches into the row.
+const RELATED_ROW_ID_KEYS = ["_id", "id"] as const;
+
+const isPlainObject = (value: unknown): value is Record<string, unknown> =>
+  Object.prototype.toString.call(value) === "[object Object]";
+
+const relatedRowId = (value: Record<string, unknown>): unknown =>
+  RELATED_ROW_ID_KEYS.map((key) => value[key]).find(
+    (id) => id !== undefined && id !== null,
+  );
+
+const scalarOf = (value: unknown): unknown =>
+  isPlainObject(value) ? relatedRowId(value) : value;
+
 const rowValue = (data: Record<string, unknown>, key: string): string => {
-  const value: unknown = get(data, key);
+  const field: unknown = get(data, key);
+  const value = Array.isArray(field) ? field.map(scalarOf) : scalarOf(field);
   return value === undefined || value === null ? "" : String(value);
 };
 

package/frontend-vue/layers/dms-core/i18n/locales/core-en-GB.json

@@ -438,7 +438,8 @@
     "chart": {
       "no_data": "No data",
       "legend_period": "Period",
-      "legend_comparison": "Comparison"
+      "legend_comparison": "Comparison",
+      "versus_value": "vs {value}"
     },
     "period": {
       "aria_label": "Period selector",
@@ -463,12 +464,33 @@
         "all": "All time",
         "custom": "Custom"
       },
+      "short_presets": {
+        "last-hour": "1H",
+        "last-24h": "24H",
+        "today": "1D",
+        "yesterday": "-1D",
+        "last-7-days": "7D",
+        "last-30-days": "30D",
+        "last-90-days": "90D",
+        "this-month": "MTD",
+        "last-month": "-1M",
+        "this-quarter": "QTD",
+        "last-quarter": "-1Q",
+        "ytd": "YTD",
+        "last-year": "-1Y",
+        "all": "ALL"
+      },
       "comparisons": {
         "none": "No comparison",
         "previous-period": "vs previous period",
         "previous-year": "vs previous year",
         "custom": "Custom"
       },
+      "compare_labels": {
+        "previous-period": "vs previous period",
+        "previous-year": "vs previous year",
+        "custom": "vs comparison period"
+      },
       "compare_options": {
         "none": "No comparison",
         "previous-period": "Previous period",
@@ -494,7 +516,117 @@
     },
     "a11y": {
       "breadcrumb": "Breadcrumb",
-      "loading": "Loading"
+      "close": "Close",
+      "loading": "Loading",
+      "show_options": "Show options"
+    },
+    "automation": {
+      "triggers": {
+        "memberAdded": {
+          "name": "Member added",
+          "description": "Fires when a user becomes a member of a workspace"
+        },
+        "memberRemoved": {
+          "name": "Member removed",
+          "description": "Fires when members are removed from a workspace"
+        },
+        "inviteCreated": {
+          "name": "Invite created",
+          "description": "Fires when a user invite is created on a workspace"
+        },
+        "userRegistered": {
+          "name": "User registered",
+          "description": "Fires when a new user completes signup"
+        },
+        "recordCreated": {
+          "name": "Record created",
+          "description": "Fires when rows are created in a TableView-backed table"
+        },
+        "recordUpdated": {
+          "name": "Record updated",
+          "description": "Fires when rows are updated in a TableView-backed table"
+        },
+        "recordDeleted": {
+          "name": "Record deleted",
+          "description": "Fires when rows are deleted in a TableView-backed table"
+        },
+        "record": {
+          "fields": {
+            "location": "Data controller location to watch, e.g. \"/api/tables/members\". Leave empty to fire for every table."
+          }
+        }
+      },
+      "actions": {
+        "sendEmail": {
+          "name": "Send email",
+          "description": "Send an HTML email through the configured email provider, written out or rendered from a registered HTML template",
+          "fields": {
+            "template": "Name of a registered HTML template to render instead of the HTML",
+            "props": "Props the template is rendered with",
+            "language": "Language the template is rendered in; defaults to the recipient's when the address belongs to a user"
+          }
+        },
+        "sendNotification": {
+          "name": "Send notification",
+          "description": "Send an in-app notification to specific users and/or every user holding one of the given roles",
+          "fields": {
+            "userId": "One recipient, e.g. a trigger's user ID",
+            "tenantId": "Workspace whose members receive the role notification; leave empty for the default workspace",
+            "title": "Literal text, or a \"$\" translation key",
+            "description": "Literal text, or a \"$\" translation key",
+            "params": "Interpolation params of the title and description translations",
+            "idempotencyKey": "Stable event key, e.g. a trigger's delivery ID: a replayed event is delivered once"
+          }
+        },
+        "inviteUser": {
+          "name": "Invite user",
+          "description": "Invite an email address to a workspace: existing users are added as members directly, otherwise an invite is created (and its signup email sent unless Send the email is off)",
+          "fields": {
+            "tenantId": "Workspace to invite into; defaults to the default workspace",
+            "language": "Language of the invitation email and of the account it creates; defaults to en",
+            "inviterName": "Who the invitation email says it comes from"
+          }
+        }
+      },
+      "fields": {
+        "actorId": "Actor ID",
+        "actorName": "Actor name",
+        "asTenantOwner": "Workspace owner",
+        "at": "Date",
+        "deliveryId": "Delivery ID",
+        "description": "Description",
+        "email": "Email",
+        "error": "Error",
+        "firstname": "First name",
+        "html": "HTML",
+        "icon": "Icon",
+        "idempotencyKey": "Replay key",
+        "ids": "Record IDs",
+        "inviteId": "Invite ID",
+        "inviterName": "Inviter name",
+        "isTenantOwner": "Workspace owner",
+        "kind": "Result",
+        "language": "Language",
+        "lastname": "Last name",
+        "linkTo": "Link",
+        "location": "Table",
+        "messageId": "Message ID",
+        "name": "Name",
+        "ok": "Sent",
+        "params": "Parameters",
+        "props": "Template props",
+        "roleIds": "Roles",
+        "sendEmail": "Send the email",
+        "subject": "Subject",
+        "success": "Success",
+        "template": "Template",
+        "tenantId": "Workspace",
+        "title": "Title",
+        "to": "To",
+        "tone": "Tone",
+        "userId": "User",
+        "userIds": "Users"
+      }
     }
   }
 }

package/frontend-vue/layers/dms-core/i18n/locales/core-fr-FR.json

@@ -438,7 +438,8 @@
     "chart": {
       "no_data": "Aucune donnée",
       "legend_period": "Période",
-      "legend_comparison": "Comparaison"
+      "legend_comparison": "Comparaison",
+      "versus_value": "vs {value}"
     },
     "period": {
       "aria_label": "Sélecteur de période",
@@ -463,12 +464,33 @@
         "all": "Toute la période",
         "custom": "Personnalisé"
       },
+      "short_presets": {
+        "last-hour": "1 h",
+        "last-24h": "24 h",
+        "today": "Auj.",
+        "yesterday": "Hier",
+        "last-7-days": "7 j",
+        "last-30-days": "30 j",
+        "last-90-days": "90 j",
+        "this-month": "Mois",
+        "last-month": "M-1",
+        "this-quarter": "Trim.",
+        "last-quarter": "T-1",
+        "ytd": "Année",
+        "last-year": "A-1",
+        "all": "Tout"
+      },
       "comparisons": {
         "none": "Sans comparaison",
         "previous-period": "vs période précédente",
         "previous-year": "vs année précédente",
         "custom": "Personnalisé"
       },
+      "compare_labels": {
+        "previous-period": "vs période précédente",
+        "previous-year": "vs année précédente",
+        "custom": "vs période de comparaison"
+      },
       "compare_options": {
         "none": "Aucune comparaison",
         "previous-period": "Période précédente",
@@ -494,7 +516,117 @@
     },
     "a11y": {
       "breadcrumb": "Fil d'Ariane",
-      "loading": "Chargement"
+      "close": "Fermer",
+      "loading": "Chargement",
+      "show_options": "Afficher les options"
+    },
+    "automation": {
+      "triggers": {
+        "memberAdded": {
+          "name": "Membre ajouté",
+          "description": "Se déclenche quand un utilisateur devient membre d'un espace de travail"
+        },
+        "memberRemoved": {
+          "name": "Membre retiré",
+          "description": "Se déclenche quand des membres sont retirés d'un espace de travail"
+        },
+        "inviteCreated": {
+          "name": "Invitation créée",
+          "description": "Se déclenche quand une invitation est créée dans un espace de travail"
+        },
+        "userRegistered": {
+          "name": "Utilisateur inscrit",
+          "description": "Se déclenche quand un nouvel utilisateur termine son inscription"
+        },
+        "recordCreated": {
+          "name": "Enregistrement créé",
+          "description": "Se déclenche quand des lignes sont créées dans une table adossée à une TableView"
+        },
+        "recordUpdated": {
+          "name": "Enregistrement modifié",
+          "description": "Se déclenche quand des lignes sont modifiées dans une table adossée à une TableView"
+        },
+        "recordDeleted": {
+          "name": "Enregistrement supprimé",
+          "description": "Se déclenche quand des lignes sont supprimées dans une table adossée à une TableView"
+        },
+        "record": {
+          "fields": {
+            "location": "Emplacement du contrôleur de données à surveiller, par ex. \"/api/tables/members\". Laissez vide pour réagir à toutes les tables."
+          }
+        }
+      },
+      "actions": {
+        "sendEmail": {
+          "name": "Envoyer un e-mail",
+          "description": "Envoie un e-mail HTML via le fournisseur d'e-mail configuré, rédigé tel quel ou généré à partir d'un modèle HTML enregistré",
+          "fields": {
+            "template": "Nom d'un modèle HTML enregistré à générer à la place du HTML",
+            "props": "Propriétés avec lesquelles le modèle est généré",
+            "language": "Langue dans laquelle le modèle est généré ; par défaut celle du destinataire quand l'adresse appartient à un utilisateur"
+          }
+        },
+        "sendNotification": {
+          "name": "Envoyer une notification",
+          "description": "Envoie une notification dans l'application à des utilisateurs précis et/ou à tous les utilisateurs ayant l'un des rôles indiqués",
+          "fields": {
+            "userId": "Un destinataire, par ex. l'ID utilisateur d'un déclencheur",
+            "tenantId": "Espace de travail dont les membres reçoivent la notification par rôle ; laissez vide pour l'espace par défaut",
+            "title": "Texte littéral, ou clé de traduction \"$\"",
+            "description": "Texte littéral, ou clé de traduction \"$\"",
+            "params": "Paramètres d'interpolation des traductions du titre et de la description",
+            "idempotencyKey": "Clé stable de l'événement, par ex. l'ID de livraison d'un déclencheur : un événement rejoué n'est livré qu'une fois"
+          }
+        },
+        "inviteUser": {
+          "name": "Inviter un utilisateur",
+          "description": "Invite une adresse e-mail dans un espace de travail : un utilisateur existant y est ajouté directement comme membre, sinon une invitation est créée (et son e-mail d'inscription envoyé, sauf si Envoyer l'e-mail est désactivé)",
+          "fields": {
+            "tenantId": "Espace de travail où inviter ; par défaut l'espace par défaut",
+            "language": "Langue de l'e-mail d'invitation et du compte qu'il crée ; en par défaut",
+            "inviterName": "Nom de l'expéditeur indiqué dans l'e-mail d'invitation"
+          }
+        }
+      },
+      "fields": {
+        "actorId": "ID de l'auteur",
+        "actorName": "Nom de l'auteur",
+        "asTenantOwner": "Propriétaire de l'espace",
+        "at": "Date",
+        "deliveryId": "ID de livraison",
+        "description": "Description",
+        "email": "E-mail",
+        "error": "Erreur",
+        "firstname": "Prénom",
+        "html": "HTML",
+        "icon": "Icône",
+        "idempotencyKey": "Clé de rejeu",
+        "ids": "ID des enregistrements",
+        "inviteId": "ID de l'invitation",
+        "inviterName": "Nom de l'invitant",
+        "isTenantOwner": "Propriétaire de l'espace",
+        "kind": "Résultat",
+        "language": "Langue",
+        "lastname": "Nom",
+        "linkTo": "Lien",
+        "location": "Table",
+        "messageId": "ID du message",
+        "name": "Nom",
+        "ok": "Envoyée",
+        "params": "Paramètres",
+        "props": "Propriétés du modèle",
+        "roleIds": "Rôles",
+        "sendEmail": "Envoyer l'e-mail",
+        "subject": "Objet",
+        "success": "Succès",
+        "template": "Modèle",
+        "tenantId": "Espace de travail",
+        "title": "Titre",
+        "to": "Destinataire",
+        "tone": "Ton",
+        "userId": "Utilisateur",
+        "userIds": "Utilisateurs"
+      }
     }
   }
 }

package/frontend-vue/layers/dms-layout/app/build/components/layout/DashboardBanners.vue

@@ -3,8 +3,9 @@ import DmsBlockActions from "#dms-ui/app/build/components/blocks/BlockActions.vu
 import { useComposedText } from "#dms-core/app/composables/translation/useComposedText";
 
 /**
- * Stacks the global layout banners under the dashboard header, on every page
- * of the dashboard layout. Each banner carries its own live-region role, so a
+ * Stacks the global layout banners under the dashboard header, on the pages
+ * each banner's scope covers (the application's pages unless it says
+ * otherwise). Each banner carries its own live-region role, so a
  * banner appearing after a navigation is announced as well. A text is a
  * string or a composed text, written in the reader's language, followed by
  * the banner's link buttons.