@antelopejs/dms 0.6.1 → 0.6.2

package/frontend-vue/layers/dms-ui/app/build/composables/data-types/twoLineCell.ts

@@ -0,0 +1,118 @@
+import { h, type VNodeChild } from "vue";
+import type { DataType } from "#dms-core/app/composables/data-types/useDataType";
+import { useComposedText } from "../../../../../dms-core/app/composables/translation/useComposedText";
+import {
+  type ComposableText,
+  isComposedText,
+} from "../../../../../dms-core/app/utils/composedText";
+import { readRowField, readSubline, toneClass, type Row } from "./cellHelpers";
+
+const EMPTY = "—";
+const PRIMARY_CLASS = "text-highlighted truncate text-[13px] font-medium";
+const EMPTY_PRIMARY_CLASS = "text-dimmed truncate text-[13px]";
+const SUB_CLASS = "truncate text-xs";
+
+interface TwoLineOptions {
+  /** Row field holding the primary line, in place of the column's value. */
+  primaryField?: string;
+  /** Row field holding the secondary line. */
+  subField?: string;
+  /** Tone of the secondary line when the row gives none. */
+  subTone?: string;
+  /** Text of an empty primary line. */
+  emptyLabel?: string;
+  /** The column's own data type, which writes its value. */
+  columnType?: string;
+  /** The column's own type options (a select's items). */
+  typeOptions?: unknown;
+}
+
+const isBlank = (value: unknown): boolean =>
+  value === null || value === undefined || value === "";
+
+/** The column's value written by the column's own data type. */
+function formatColumnValue(
+  value: unknown,
+  locale: string,
+  opts: TwoLineOptions,
+  row: Row,
+): VNodeChild {
+  const { getDataType } = useDataTypes();
+  const formatter = opts.columnType
+    ? getDataType(opts.columnType)?.formatter
+    : undefined;
+  const format = formatter?.cell ?? formatter?.default;
+  if (!format) return String(value);
+  return format(value, locale, opts.typeOptions, row) as VNodeChild;
+}
+
+/** The primary line, or nothing when the row has none to show. */
+function readPrimary(
+  value: unknown,
+  locale: string,
+  opts: TwoLineOptions,
+  row: Row,
+): VNodeChild | undefined {
+  const { processText } = useComposedText();
+  if (opts.primaryField) {
+    const text = processText(
+      readRowField(row, opts.primaryField) as ComposableText,
+    );
+    return text || undefined;
+  }
+  if (isBlank(value)) return undefined;
+  if (isComposedText(value)) return processText(value);
+  return formatColumnValue(value, locale, opts, row);
+}
+
+/**
+ * `two_line`: a primary line — the column's value in its own format, or a row
+ * field's text — over a secondary line read off the row, in the row's tone,
+ * else `subTone`, else muted. No avatar.
+ */
+function renderTwoLine(
+  value: unknown,
+  locale: string,
+  options: unknown,
+  row: Row,
+) {
+  const { processText } = useComposedText();
+  const opts = (options ?? {}) as TwoLineOptions;
+  const primary = readPrimary(value, locale, opts, row);
+  const sub = readSubline(readRowField(row, opts.subField), {
+    processText,
+    isStringTranslated: true,
+  });
+  return h("span", { class: "flex min-w-0 flex-col leading-tight" }, [
+    primary === undefined
+      ? h(
+          "span",
+          { class: EMPTY_PRIMARY_CLASS },
+          opts.emptyLabel ? processText(opts.emptyLabel) : EMPTY,
+        )
+      : h("span", { class: PRIMARY_CLASS }, [primary]),
+    sub
+      ? h(
+          "span",
+          {
+            class: [SUB_CLASS, toneClass(sub.tone ?? opts.subTone, "muted")],
+            title: sub.text,
+          },
+          sub.text,
+        )
+      : null,
+  ]);
+}
+
+/**
+ * The `two_line` cell data type. It draws an empty value too: its primary
+ * line may come from another field, and its secondary line always does.
+ */
+export const registerTwoLineCellType = (
+  registerDataType: (dataType: DataType) => void,
+) => {
+  registerDataType({
+    id: "two_line",
+    formatter: { default: renderTwoLine, empty: renderTwoLine },
+  });
+};

package/frontend-vue/layers/dms-ui/app/build/composables/data-types/useColumnValueRenderer.ts

@@ -45,8 +45,10 @@ export function useColumnValueRenderer() {
   const { locale } = useI18n();
 
   // A display also reads the column's own type options (`typeOptions`): a
-  // select's items name the values it draws. A display declared without
-  // options reads them at the top level, as it always did.
+  // select's items name the values it draws; and the column's own type id
+  // (`columnType`), so it can write the value as the column would (an amount
+  // under `two_line`). A display declared without options reads the type
+  // options at the top level, as it always did.
   const resolveRenderer = (column: RenderableColumn) => {
     const typeOptions = column.type?.inputComponent?.options as
       | Record<string, unknown>
@@ -56,7 +58,7 @@ export function useColumnValueRenderer() {
     const displayOptions = column.display.options ?? typeOptions;
     return {
       typeId: column.display.type,
-      options: { ...displayOptions, typeOptions },
+      options: { ...displayOptions, typeOptions, columnType: column.type?.id },
     };
   };
 

package/frontend-vue/layers/dms-ui/app/build/utils/relativeDate.ts

@@ -1,29 +1,6 @@
+import { formatRelativeDistance } from "#dms-core/app/utils/formatter";
 import { regionalDateTimeFormat } from "#dms-core/app/utils/regional";
 
-const SECOND_MS = 1000;
-const MINUTE_MS = 60 * SECOND_MS;
-const HOUR_MS = 60 * MINUTE_MS;
-const DAY_MS = 24 * HOUR_MS;
-const WEEK_MS = 7 * DAY_MS;
-const MONTH_MS = 30 * DAY_MS;
-const YEAR_MS = 365 * DAY_MS;
-
-interface RelativeUnit {
-  unit: Intl.RelativeTimeFormatUnit;
-  ms: number;
-  /** The unit applies below this elapsed time. */
-  below: number;
-}
-
-const RELATIVE_UNITS: RelativeUnit[] = [
-  { unit: "minute", ms: MINUTE_MS, below: HOUR_MS },
-  { unit: "hour", ms: HOUR_MS, below: DAY_MS },
-  { unit: "day", ms: DAY_MS, below: WEEK_MS },
-  { unit: "week", ms: WEEK_MS, below: MONTH_MS },
-  { unit: "month", ms: MONTH_MS, below: YEAR_MS },
-  { unit: "year", ms: YEAR_MS, below: Number.POSITIVE_INFINITY },
-];
-
 function capitalize(text: string): string {
   return text ? `${text[0]!.toLocaleUpperCase()}${text.slice(1)}` : text;
 }
@@ -37,17 +14,9 @@ export function formatRelativeDate(
   locale: string,
   now: number = Date.now(),
 ): string {
-  const deltaMs = new Date(date).getTime() - now;
-  const distance = Math.abs(deltaMs);
-  const unit =
-    RELATIVE_UNITS.find((candidate) => distance < candidate.below) ??
-    RELATIVE_UNITS[RELATIVE_UNITS.length - 1]!;
-  const value = Math.round(deltaMs / unit.ms);
-  const format = new Intl.RelativeTimeFormat(locale, {
-    numeric: "auto",
-    style: "short",
-  });
-  return capitalize(format.format(value, unit.unit));
+  return capitalize(
+    formatRelativeDistance(date, locale, { style: "short", now }),
+  );
 }
 
 /** "Sep 27": day and short month. */

package/frontend-vue/layers/dms-ui/app/components/blocks/BannerBlock.vue

@@ -5,7 +5,9 @@ import DmsBlockActions, {
   type BlockAction,
 } from "../../build/components/blocks/BlockActions.vue";
 import { useWatch } from "../../../../dms-core/app/composables/watch/useWatch";
+import { useComposedText } from "../../../../dms-core/app/composables/translation/useComposedText";
 import type { DefaultComponentProps } from "../../../../dms-core/app/types/component";
+import type { BlockText } from "../../../../dms-core/app/types/composed-text";
 
 type BannerTone = "info" | "success" | "warning" | "error" | "primary";
 
@@ -14,8 +16,9 @@ type BannerTone = "info" | "success" | "warning" | "error" | "primary";
 // Dismissals live in a cookie (like the dashboard banners) so the server
 // render already leaves a dismissed banner out instead of flashing it.
 interface BannerBlockProps extends Partial<DefaultComponentProps> {
-  title?: string;
-  description?: string;
+  /** A string (`$` for an i18n key) or a composed text. */
+  title?: BlockText;
+  description?: BlockText;
   tone?: BannerTone;
   /** Overrides the tone's icon. */
   icon?: string;
@@ -56,7 +59,7 @@ const TONE_ICONS: Record<BannerTone, string> = {
 
 useWatch(props.watchActions || [], props.componentId);
 
-const { processI18n } = useTranslation();
+const { processText } = useComposedText();
 const dismissed = useDmsCookie<string[]>(DISMISSED_COOKIE, {
   default: () => [],
   maxAge: DISMISSED_MAX_AGE_S,
@@ -91,9 +94,9 @@ function dismiss(): void {
 <template>
   <DmsBanner
     v-if="isVisible"
-    :title="props.title ? processI18n(props.title) : undefined"
+    :title="props.title ? processText(props.title) : undefined"
     :description="
-      props.description ? processI18n(props.description) : undefined
+      props.description ? processText(props.description) : undefined
     "
     :icon="props.icon ?? TONE_ICONS[props.tone]"
     :tone="props.tone"

package/frontend-vue/layers/dms-ui/app/components/blocks/KeyValueListBlock.vue

@@ -8,13 +8,24 @@ import DmsBlockStatus, {
   type BlockEmptyText,
 } from "../../build/components/blocks/BlockStatus.vue";
 import { useBlockItems } from "../../build/composables/blocks/useBlockItems";
+import { useComposedText } from "../../../../dms-core/app/composables/translation/useComposedText";
 import type { DefaultComponentProps } from "../../../../dms-core/app/types/component";
+import type { BlockText } from "../../../../dms-core/app/types/composed-text";
+import { isComposedText } from "../../../../dms-core/app/utils/composedText";
 
 // `KeyValueList` block (interface-dms `base/key-value-list`): label / value
 // rows (v2 .c-dl), static or from `fetchUrl` (`{ items }`), in a card by
-// default. Labels, details and text values follow the `$` i18n convention.
+// default. Labels, details and text values follow the `$` i18n convention or
+// are composed texts.
+interface KeyValueListBlockItem
+  extends Omit<KeyValueItem, "label" | "value" | "detail"> {
+  label: BlockText;
+  value?: BlockText | number | null;
+  detail?: BlockText;
+}
+
 interface KeyValueListBlockProps extends DefaultComponentProps {
-  items?: KeyValueItem[];
+  items?: KeyValueListBlockItem[];
   dense?: boolean;
   columns?: number;
   currency?: string;
@@ -50,30 +61,39 @@ const props = withDefaults(defineProps<KeyValueListBlockProps>(), {
 
 const TRANSLATED_TYPES = new Set([undefined, "text", "status", "link"]);
 
-const { processI18n } = useTranslation();
+const { processText } = useComposedText();
 
-const { items, isPending, hasError, refresh } = useBlockItems<KeyValueItem>({
-  items: () => props.items,
-  fetchUrl: props.fetchUrl,
-  fetchUrlMethod: props.fetchUrlMethod,
-  routeParams: () => props.routeParams,
-  watchActions: props.watchActions,
-  componentId: props.componentId,
-});
+const { items, isPending, hasError, refresh } =
+  useBlockItems<KeyValueListBlockItem>({
+    items: () => props.items,
+    fetchUrl: props.fetchUrl,
+    fetchUrlMethod: props.fetchUrlMethod,
+    routeParams: () => props.routeParams,
+    watchActions: props.watchActions,
+    componentId: props.componentId,
+  });
+
+// A composed value already says how each of its parameters is written, so it
+// is composed whatever the row's type; a plain one is translated only where
+// the type draws text.
+function resolveValue(item: KeyValueListBlockItem): KeyValueItem["value"] {
+  if (isComposedText(item.value)) return processText(item.value);
+  if (typeof item.value === "string" && TRANSLATED_TYPES.has(item.type)) {
+    return processText(item.value);
+  }
+  return item.value as KeyValueItem["value"];
+}
 
 const resolvedItems = computed<KeyValueItem[]>(() =>
   items.value.map((item) => ({
     ...item,
-    label: processI18n(item.label ?? ""),
-    detail: item.detail ? processI18n(item.detail) : undefined,
-    value:
-      typeof item.value === "string" && TRANSLATED_TYPES.has(item.type)
-        ? processI18n(item.value)
-        : item.value,
+    label: processText(item.label),
+    detail: item.detail ? processText(item.detail) : undefined,
+    value: resolveValue(item),
   })),
 );
 const title = computed(() =>
-  props.title ? processI18n(props.title) : undefined,
+  props.title ? processText(props.title) : undefined,
 );
 const isEmpty = computed(
   () => !isPending.value && !hasError.value && resolvedItems.value.length === 0,

package/frontend-vue/layers/dms-ui/app/components/blocks/StatGroupBlock.vue

@@ -8,13 +8,23 @@ import DmsBlockStatus, {
   type BlockEmptyText,
 } from "../../build/components/blocks/BlockStatus.vue";
 import { useBlockItems } from "../../build/composables/blocks/useBlockItems";
+import { useComposedText } from "../../../../dms-core/app/composables/translation/useComposedText";
 import type { DefaultComponentProps } from "../../../../dms-core/app/types/component";
+import type { BlockText } from "../../../../dms-core/app/types/composed-text";
 
 // `StatGroup` block (interface-dms `base/stat-group`): the generic StatGroup
 // fed from the block options or from `fetchUrl` (`{ items }`). Texts follow
-// the `$` i18n-key convention; numeric values are formatted for the locale.
+// the `$` i18n-key convention or are composed texts; numeric values are
+// formatted for the locale.
+interface StatGroupBlockItem
+  extends Omit<StatGroupItem, "eyebrow" | "value" | "detail"> {
+  eyebrow: BlockText;
+  value: BlockText | number;
+  detail?: BlockText;
+}
+
 interface StatGroupBlockProps extends DefaultComponentProps {
-  items?: StatGroupItem[];
+  items?: StatGroupBlockItem[];
   layout?: StatGroupLayout;
   columns?: number;
   /** Accessible name of the group. */
@@ -43,31 +53,24 @@ const props = withDefaults(defineProps<StatGroupBlockProps>(), {
 
 const DEFAULT_SKELETON_COUNT = 4;
 
-const { locale } = useI18n();
-const { processI18n } = useTranslation();
+const { processText } = useComposedText();
 
-const { items, isPending, hasError, refresh } = useBlockItems<StatGroupItem>({
-  items: () => props.items,
-  fetchUrl: props.fetchUrl,
-  fetchUrlMethod: props.fetchUrlMethod,
-  routeParams: () => props.routeParams,
-  watchActions: props.watchActions,
-  componentId: props.componentId,
-});
-
-function formatValue(value: StatGroupItem["value"]): string {
-  if (typeof value === "number") {
-    return new Intl.NumberFormat(locale.value).format(value);
-  }
-  return processI18n(String(value ?? ""));
-}
+const { items, isPending, hasError, refresh } =
+  useBlockItems<StatGroupBlockItem>({
+    items: () => props.items,
+    fetchUrl: props.fetchUrl,
+    fetchUrlMethod: props.fetchUrlMethod,
+    routeParams: () => props.routeParams,
+    watchActions: props.watchActions,
+    componentId: props.componentId,
+  });
 
 const resolvedItems = computed<StatGroupItem[]>(() =>
   items.value.map((item) => ({
     ...item,
-    eyebrow: processI18n(item.eyebrow ?? ""),
-    value: formatValue(item.value),
-    detail: item.detail ? processI18n(item.detail) : undefined,
+    eyebrow: processText(item.eyebrow),
+    value: processText(item.value),
+    detail: item.detail ? processText(item.detail) : undefined,
   })),
 );
 </script>
@@ -88,6 +91,6 @@ const resolvedItems = computed<StatGroupItem[]>(() =>
     :skeleton-count="
       props.skeletonCount ?? props.columns ?? DEFAULT_SKELETON_COUNT
     "
-    :label="props.label ? processI18n(props.label) : undefined"
+    :label="props.label ? processText(props.label) : undefined"
   />
 </template>

package/frontend-vue/tests/composed-text-blocks.test.ts

@@ -0,0 +1,205 @@
+// @vitest-environment jsdom
+/**
+ * StatGroup, KeyValueList and Banner draw a composed text wherever they draw
+ * a text — from their options or from the JSON their route answers — in the
+ * reader's language, and keep drawing plain strings as before.
+ */
+import {
+  createApp,
+  defineComponent,
+  h,
+  reactive,
+  ref,
+  type Component,
+} from "vue";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { createI18n } from "vue-i18n";
+import { setRegionalPreferencesSource } from "../layers/dms-core/app/utils/regional";
+
+const i18n = createI18n({
+  legacy: false,
+  locale: "en",
+  fallbackLocale: "en",
+  missingWarn: false,
+  fallbackWarn: false,
+  messages: {
+    en: {
+      saas: {
+        stats: { mrr: "MRR", mrr_value: "{amount}", workspaces: "Workspaces" },
+        seats: "no seat | {count} seat | {count} seats",
+        retry: "Payment failed, retry {date}",
+        failed: "Payment failed",
+      },
+    },
+    fr: {
+      saas: {
+        stats: { mrr: "MRR", mrr_value: "{amount}", workspaces: "Espaces" },
+        seats: "aucun siège | {count} siège | {count} sièges",
+        retry: "Paiement refusé, nouvel essai {date}",
+        failed: "Paiement refusé",
+      },
+    },
+  },
+});
+
+let fetchedItems: unknown[] = [];
+
+vi.stubGlobal("useAuthFetch", () => ({
+  $authFetch: async () => ({ items: fetchedItems }),
+}));
+vi.stubGlobal("useDmsRoute", () => reactive({ query: {} }));
+
+vi.mock("../layers/dms-core/app/composables/watch/useWatch", () => ({
+  useWatch: () => ({ state: ref({}) }),
+}));
+vi.mock(
+  "../layers/dms-core/app/composables/components/useComponentEvent",
+  () => ({ useComponentEvent: () => ({}) }),
+);
+
+// The generic components only lay out what the block resolved: their props
+// are what is checked here.
+const propsProbe = (name: string, keys: string[]) => ({
+  default: defineComponent({
+    props: keys,
+    setup: (props) => () =>
+      h("pre", { "data-probe": name }, JSON.stringify(props)),
+  }),
+});
+vi.mock("../layers/dms-ui/app/components/stat-group/StatGroup.vue", () =>
+  propsProbe("stat-group", ["items"]),
+);
+vi.mock("../layers/dms-ui/app/components/key-value-list/KeyValueList.vue", () =>
+  propsProbe("key-value-list", ["items"]),
+);
+vi.mock("../layers/dms-ui/app/components/banner/Banner.vue", () =>
+  propsProbe("banner", ["title", "description"]),
+);
+
+const StatGroupBlock = (
+  await import("../layers/dms-ui/app/components/blocks/StatGroupBlock.vue")
+).default;
+const KeyValueListBlock = (
+  await import("../layers/dms-ui/app/components/blocks/KeyValueListBlock.vue")
+).default;
+const BannerBlock = (
+  await import("../layers/dms-ui/app/components/blocks/BannerBlock.vue")
+).default;
+
+const SETTLE_MS = 50;
+const settle = () => new Promise((resolve) => setTimeout(resolve, SETTLE_MS));
+const mounted: Array<{ unmount: () => void }> = [];
+
+function render(component: Component, props: Record<string, unknown>) {
+  const root = document.createElement("div");
+  const app = createApp(component, props);
+  app.mount(root);
+  mounted.push(app);
+  return () =>
+    JSON.parse(
+      (root.querySelector("[data-probe]")?.textContent ?? "{}").replace(
+        /[\u00a0\u202f]/g,
+        " ",
+      ),
+    );
+}
+
+const mrr = {
+  key: "$saas.stats.mrr_value",
+  params: { amount: { type: "money", value: 92200, currency: "EUR" } },
+};
+const seats = (value: number) => ({
+  key: "saas.seats",
+  params: { count: { type: "count", value } },
+});
+
+beforeEach(() => {
+  i18n.global.locale.value = "en";
+  fetchedItems = [];
+  setRegionalPreferencesSource(() => ({ timeZone: "UTC" }));
+  vi.stubGlobal("useI18n", () => ({
+    t: i18n.global.t,
+    locale: i18n.global.locale,
+  }));
+  vi.stubGlobal("useDmsCookie", () => ref<string[]>([]));
+});
+
+afterEach(() => {
+  mounted.splice(0).forEach((app) => app.unmount());
+  setRegionalPreferencesSource(() => ({}));
+});
+
+describe("StatGroupBlock", () => {
+  it("composes the label, the value and the detail of a cell", () => {
+    const read = render(StatGroupBlock, {
+      items: [
+        { eyebrow: "$saas.stats.mrr", value: mrr, detail: seats(3) },
+        { eyebrow: "Plain", value: 1284, detail: "As written" },
+      ],
+    });
+
+    expect(read().items).toEqual([
+      { eyebrow: "MRR", value: "€922.00", detail: "3 seats" },
+      { eyebrow: "Plain", value: "1,284", detail: "As written" },
+    ]);
+  });
+
+  it("composes the cells its route answers, in the reader's language", async () => {
+    i18n.global.locale.value = "fr";
+    fetchedItems = [
+      {
+        eyebrow: { key: "saas.stats.workspaces" },
+        value: mrr,
+        detail: seats(1),
+      },
+    ];
+    const read = render(StatGroupBlock, { fetchUrl: "/api/billing-stats" });
+    await settle();
+
+    expect(read().items).toEqual([
+      { eyebrow: "Espaces", value: "922,00 €", detail: "1 siège" },
+    ]);
+  });
+});
+
+describe("KeyValueListBlock", () => {
+  it("composes labels, details and values, whatever the row's type", () => {
+    const read = render(KeyValueListBlock, {
+      card: false,
+      items: [
+        { label: { key: "saas.stats.mrr" }, value: mrr, type: "money" },
+        { label: "Seats", value: seats(0), detail: { key: "saas.failed" } },
+        { label: "Next invoice", value: 588, type: "money" },
+        { label: "Plan", value: "$saas.stats.workspaces" },
+      ],
+    });
+
+    expect(read().items).toEqual([
+      { label: "MRR", value: "€922.00", type: "money" },
+      { label: "Seats", value: "no seat", detail: "Payment failed" },
+      { label: "Next invoice", value: 588, type: "money" },
+      { label: "Plan", value: "Workspaces" },
+    ]);
+  });
+});
+
+describe("BannerBlock", () => {
+  it("composes its title and description", () => {
+    const read = render(BannerBlock, {
+      title: { key: "saas.failed" },
+      description: {
+        key: "saas.retry",
+        params: { date: { type: "date", value: "2026-10-10", format: "day" } },
+      },
+    });
+
+    expect(read()).toEqual({
+      title: "Payment failed",
+      description: "Payment failed, retry Oct 10",
+    });
+  });
+
+  it("keeps a plain title as written", () => {
+    expect(render(BannerBlock, { title: "Beta" })().title).toBe("Beta");
+  });
+});