@antelopejs/dms 0.5.6 → 0.6.0

package/frontend-vue/layers/dms-ui/app/components/key-value-list/KeyValueList.vue

@@ -0,0 +1,223 @@
+<script setup lang="ts">
+import { computed } from "vue";
+import { regionalDateTimeFormat } from "#dms-core/app/utils/regional";
+import DmsStatusPill from "../status-pill/StatusPill.vue";
+import DmsAutoLink from "../link/AutoLink.vue";
+import { DMS_TONE_TEXT } from "../../build/utils/tone";
+import type { Tone } from "../../types/tone";
+
+/**
+ * How a value is drawn: `text` plain, `status` a tinted pill, `money` a
+ * currency amount, `date` a localized date, `link` an accent link, `mono` an
+ * identifier or a figure in the mono font.
+ */
+export type KeyValueType =
+  | "text"
+  | "status"
+  | "money"
+  | "date"
+  | "link"
+  | "mono";
+
+export interface KeyValueItem {
+  /** Stable key; the position is used without one. */
+  id?: string;
+  label: string;
+  /** Raw value; `null`/`undefined` renders as an em dash. */
+  value?: string | number | null;
+  type?: KeyValueType;
+  /** Route, `#anchor` or URL the value links to (any type). */
+  to?: string;
+  /** Text color (text, mono, money, date) or pill tone (status). */
+  tone?: Tone;
+  /** Dim note after the value ("Authenticator app"). */
+  detail?: string;
+  /** ISO 4217 code of a `money` value; overrides the list's `currency`. */
+  currency?: string;
+  /** This value alone is still loading: a skeleton stands in for it. */
+  loading?: boolean;
+}
+
+interface KeyValueListProps {
+  items?: KeyValueItem[];
+  /** Tighter rows (32px instead of 38px) for side panels. */
+  dense?: boolean;
+  /** Columns on wide screens (1–3); one on phones. */
+  columns?: number;
+  /** Loading: values turn to skeletons, or `skeletonCount` rows are drawn. */
+  loading?: boolean;
+  skeletonCount?: number;
+  /** Default ISO 4217 code of `money` values. */
+  currency?: string;
+}
+
+interface KeyValueListSlots {
+  /** Replaces a value cell; receives the item and its formatted text. */
+  value?: (props: { item: KeyValueItem; formatted: string }) => unknown;
+}
+
+const props = withDefaults(defineProps<KeyValueListProps>(), {
+  items: () => [],
+  dense: false,
+  columns: 1,
+  loading: false,
+  skeletonCount: 3,
+  currency: "EUR",
+});
+const slots = defineSlots<KeyValueListSlots>();
+
+const EMPTY_VALUE = "—";
+const MAX_COLUMNS = 3;
+
+// v2 .c-dl: label left, value right, rows split by a muted hairline. Each
+// column's first row drops its line, at every breakpoint.
+const COLUMN_CLASSES: Record<number, string> = {
+  1: "[&>div:first-child]:border-t-0",
+  2: "gap-x-8 sm:grid-cols-2 [&>div:first-child]:border-t-0 sm:[&>div:nth-child(2)]:border-t-0",
+  3: "gap-x-8 sm:grid-cols-2 lg:grid-cols-3 [&>div:first-child]:border-t-0 sm:[&>div:nth-child(2)]:border-t-0 lg:[&>div:nth-child(3)]:border-t-0",
+};
+
+const { locale } = useI18n();
+
+const columnClass = computed(
+  () =>
+    COLUMN_CLASSES[
+      Math.min(MAX_COLUMNS, Math.max(1, Math.round(props.columns)))
+    ],
+);
+// The row wraps: a value too long to sit beside its label (a phone, a narrow
+// column) drops under it, still right-aligned, instead of being cut.
+const rowClass = computed(() => [
+  "border-muted flex flex-wrap items-center gap-x-3 gap-y-0.5 border-t",
+  props.dense ? "min-h-8 py-1" : "min-h-[38px] py-1.5",
+]);
+const showPlaceholders = computed(
+  () => props.loading && props.items.length === 0,
+);
+
+type ValueFormatter = (item: KeyValueItem, value: string | number) => string;
+
+function formatNumber(_item: KeyValueItem, value: string | number): string {
+  if (typeof value !== "number") return value;
+  return new Intl.NumberFormat(locale.value).format(value);
+}
+
+function formatMoney(item: KeyValueItem, value: string | number): string {
+  if (typeof value !== "number") return value;
+  try {
+    return new Intl.NumberFormat(locale.value, {
+      style: "currency",
+      currency: item.currency ?? props.currency,
+    }).format(value);
+  } catch {
+    // An unknown currency code: the amount is still worth showing.
+    return formatNumber(item, value);
+  }
+}
+
+function formatDate(_item: KeyValueItem, value: string | number): string {
+  const date = new Date(value);
+  if (Number.isNaN(date.getTime())) return String(value);
+  return regionalDateTimeFormat(locale.value, { dateStyle: "medium" }).format(
+    date,
+  );
+}
+
+const FORMATTERS: Partial<Record<KeyValueType, ValueFormatter>> = {
+  money: formatMoney,
+  date: formatDate,
+};
+
+// Text styles per type; the tone colours every type but a link.
+const TYPE_CLASSES: Partial<Record<KeyValueType, string>> = {
+  link: "text-primary font-[550]",
+  mono: "font-mono text-[12.5px] tabular-nums",
+  money: "tabular-nums",
+};
+
+function format(item: KeyValueItem): string {
+  if (item.value === null || item.value === undefined || item.value === "") {
+    return EMPTY_VALUE;
+  }
+  const formatter = FORMATTERS[item.type ?? "text"] ?? formatNumber;
+  return formatter(item, item.value);
+}
+
+function valueClass(item: KeyValueItem): string[] {
+  const type = item.type ?? "text";
+  const color =
+    type === "link"
+      ? ""
+      : item.tone
+        ? DMS_TONE_TEXT[item.tone]
+        : "text-highlighted";
+  // A value longer than the whole row (an id, a long name) wraps rather than
+  // hiding its end: there is no hover on a phone to reveal it.
+  return ["wrap-anywhere", color, TYPE_CLASSES[type] ?? ""];
+}
+
+function keyOf(item: KeyValueItem, index: number): string {
+  return item.id ?? `${index}-${item.label}`;
+}
+</script>
+
+<template>
+  <!-- grid-cols-1: minmax(0, 1fr) tracks, so a long value truncates instead
+       of widening the list past a narrow screen. -->
+  <dl
+    class="grid grid-cols-1"
+    :class="[columnClass, props.dense ? 'text-[12.5px]' : 'text-[13px]']"
+    :aria-busy="props.loading || undefined"
+  >
+    <template v-if="showPlaceholders">
+      <div v-for="index in props.skeletonCount" :key="index" :class="rowClass">
+        <dt class="min-w-[120px] flex-none">
+          <USkeleton class="h-3 w-20" />
+        </dt>
+        <dd class="ms-auto">
+          <USkeleton class="h-3 w-24" />
+        </dd>
+      </div>
+    </template>
+    <template v-else>
+      <div
+        v-for="(item, index) in props.items"
+        :key="keyOf(item, index)"
+        :class="rowClass"
+      >
+        <dt class="text-muted min-w-[120px] flex-none">{{ item.label }}</dt>
+        <dd
+          class="ms-auto flex min-w-0 flex-wrap items-center justify-end gap-x-1.5 gap-y-0.5 text-end"
+        >
+          <USkeleton v-if="props.loading || item.loading" class="h-3 w-24" />
+          <slot
+            v-else-if="slots.value"
+            name="value"
+            :item="item"
+            :formatted="format(item)"
+          />
+          <template v-else>
+            <component
+              :is="item.to ? DmsAutoLink : 'span'"
+              :to="item.to"
+              class="min-w-0"
+              :class="item.to && item.type !== 'status' && 'hover:underline'"
+            >
+              <DmsStatusPill
+                v-if="item.type === 'status'"
+                :tone="item.tone ?? 'neutral'"
+                :label="format(item)"
+              />
+              <span v-else class="block" :class="valueClass(item)">
+                {{ format(item) }}
+              </span>
+            </component>
+            <span v-if="item.detail" class="text-dimmed truncate text-xs">
+              {{ item.detail }}
+            </span>
+          </template>
+        </dd>
+      </div>
+    </template>
+  </dl>
+</template>

package/frontend-vue/layers/dms-ui/app/components/kpi/KpiCard.vue

@@ -1,5 +1,12 @@
 <script setup lang="ts">
 import { computed } from "vue";
+import DmsStatCell from "../../build/components/stat/StatCell.vue";
+import DmsEyebrow from "../section-header/Eyebrow.vue";
+// Imported rather than resolved from the registry: a registered component is
+// a lazy chunk of its own, fetched only when the data first shows it, so the
+// trend would pop in a beat after the value.
+import DmsTrendBadge from "../chart/internal/TrendBadge.vue";
+import DmsSparkline from "../chart/internal/Sparkline.vue";
 import { useChartFetch } from "../../composables/chart/useChartFetch";
 import {
   ABSENT_VALUE_PARTS,
@@ -15,7 +22,10 @@ import type { DefaultComponentProps } from "../../../../dms-core/app/types/compo
 
 interface Props extends DefaultComponentProps {
   title: string;
-  /** "stat" = compact DMS v2 look: mono uppercase label, bare small icon. */
+  /**
+   * "stat" = the compact stat card (a StatGroup `cards` cell): icon well,
+   * label + value, delta.
+   */
   variant?: "default" | "stat";
   description?: string;
   icon?: string;
@@ -35,7 +45,9 @@ interface Props extends DefaultComponentProps {
   staticSparkline?: number[];
 }
 
-const DEFAULT_FALLBACK_ICON = "i-lucide-bar-chart-3";
+const DEFAULT_FALLBACK_ICON = "i-ph-chart-bar";
+// v2 KPI sparklines are cyan when the trend is good, not green.
+const POSITIVE_SPARKLINE_ACCENT = "primary";
 
 const props = withDefaults(defineProps<Props>(), {
   variant: "default",
@@ -46,7 +58,7 @@ const props = withDefaults(defineProps<Props>(), {
   currencyCode: "EUR",
 });
 
-const { locale } = useI18n();
+const { locale, t } = useI18n();
 const { processI18n } = useTranslation();
 useComponentEvent(props.componentId);
 const { state: watchState } = useWatch(
@@ -64,7 +76,7 @@ const staticData = computed<KpiCardResponse | null>(() => {
   };
 });
 
-const { data, isLoading } = useChartFetch<KpiCardResponse>({
+const { data, isLoading, error, refresh } = useChartFetch<KpiCardResponse>({
   fetchUrl: props.fetchUrl,
   fetchUrlMethod: props.fetchUrlMethod,
   periodScope: props.periodScope,
@@ -88,81 +100,189 @@ const formattedParts = computed(() =>
       ),
 );
 
+const isFirstLoad = computed(() => isLoading.value && data.value === null);
+// v2 error state: a failed first load shows a message and a retry button in
+// place of the value; a failed refetch keeps the last value.
+const hasError = computed(
+  () => !isLoading.value && data.value === null && Boolean(error.value),
+);
+// A refetch keeps the stale value on screen, faded, instead of a skeleton.
+const isRefreshing = computed(() => isLoading.value && data.value !== null);
 const showTrend = computed(() => props.showDelta && delta.value !== null);
+const hasSparkline = computed(
+  () => props.showSparkline && sparkline.value.length > 0,
+);
+const footnote = computed(() => {
+  const text = props.compareLabel || props.description;
+  return text ? processI18n(text) : "";
+});
 
 const resolvedSparklineAccent = computed(() =>
-  resolveSparklineAccent(props.sparklineAccent, {
-    delta: delta.value,
-    sparkline: sparkline.value,
-    invert: props.invert,
-  }),
+  resolveSparklineAccent(
+    props.sparklineAccent,
+    { delta: delta.value, sparkline: sparkline.value, invert: props.invert },
+    POSITIVE_SPARKLINE_ACCENT,
+  ),
 );
 
 const resolvedIcon = computed(() => props.icon || DEFAULT_FALLBACK_ICON);
-
 const isStat = computed(() => props.variant === "stat");
-const labelClass = computed(() =>
-  isStat.value
-    ? "text-dimmed truncate font-mono text-[10px] font-medium uppercase tracking-widest"
-    : "text-muted truncate text-sm",
-);
-const iconWrapClass = computed(() =>
-  isStat.value
-    ? "text-dimmed flex shrink-0 items-center justify-center"
-    : "bg-elevated dark:bg-accented text-toned flex shrink-0 items-center justify-center rounded-lg p-2",
-);
 </script>
 
 <template>
-  <DmsCard :padded="false" class="p-4 sm:p-5">
-    <div class="flex items-start justify-between gap-3">
-      <div class="min-w-0 flex-1">
-        <p :class="labelClass">{{ processI18n(title) }}</p>
-        <div class="mt-1 text-2xl font-semibold tracking-tight tabular-nums">
-          <USkeleton v-if="isLoading && data === null" class="h-8 w-24" />
-          <span v-else class="inline-flex items-baseline gap-x-1">
-            <span
-              v-if="formattedParts.unit && formattedParts.unitIsPrefix"
-              class="text-muted text-base font-medium"
-            >
-              {{ formattedParts.unit }}
-            </span>
-            <span>{{ formattedParts.value }}</span>
-            <span
-              v-if="formattedParts.unit && !formattedParts.unitIsPrefix"
-              class="text-muted text-base font-medium"
-            >
-              {{ formattedParts.unit }}
-            </span>
-          </span>
+  <DmsStatCell
+    v-if="isStat"
+    :eyebrow="processI18n(title)"
+    :icon="resolvedIcon"
+    :loading="isFirstLoad"
+    :refreshing="isRefreshing"
+    :aria-busy="isFirstLoad"
+  >
+    <template #value>
+      <span
+        v-if="formattedParts.unit && formattedParts.unitIsPrefix"
+        class="text-muted mr-0.5 text-[0.6em] font-medium"
+      >
+        {{ formattedParts.unit }}
+      </span>
+      <span>{{ formattedParts.value }}</span>
+      <span
+        v-if="formattedParts.unit && !formattedParts.unitIsPrefix"
+        class="text-muted ml-0.5 text-[0.6em] font-medium"
+      >
+        {{ formattedParts.unit }}
+      </span>
+    </template>
+    <!-- With no change to show (no comparison period), the trend's line
+         keeps its place: toggling a comparison never resizes the card. -->
+    <template v-if="showDelta || hasSparkline" #aside>
+      <div class="ml-auto grid shrink-0 justify-items-end gap-1">
+        <DmsTrendBadge
+          v-if="showTrend"
+          :delta="delta"
+          :invert="invert"
+          variant="text"
+        />
+        <span v-else-if="showDelta" class="h-4" aria-hidden="true" />
+        <div v-if="hasSparkline" class="h-6 w-16">
+          <DmsSparkline
+            :values="sparkline"
+            :accent="resolvedSparklineAccent"
+            :aria-label="processI18n(title)"
+          />
         </div>
-        <div
-          v-if="showTrend || compareLabel || description"
-          class="mt-2 flex min-w-0 items-center gap-x-2"
-        >
-          <DmsTrendBadge v-if="showTrend" :delta="delta" :invert="invert" />
-          <span v-if="compareLabel" class="text-muted truncate text-xs">
-            {{ processI18n(compareLabel) }}
-          </span>
-          <span v-else-if="description" class="text-muted truncate text-xs">
-            {{ processI18n(description) }}
-          </span>
+      </div>
+    </template>
+  </DmsStatCell>
+
+  <DmsCard
+    v-else
+    :padded="false"
+    class="flex min-h-[132px] flex-col gap-1.5 px-4 py-4 sm:px-[18px]"
+    :aria-busy="isFirstLoad"
+  >
+    <div class="flex min-w-0 items-center gap-2">
+      <UIcon
+        :name="resolvedIcon"
+        class="text-dimmed size-[15px] shrink-0"
+        :aria-hidden="true"
+      />
+      <DmsEyebrow
+        tone="muted"
+        truncate
+        class="max-sm:whitespace-normal"
+        :label="processI18n(title)"
+      />
+    </div>
+    <!-- The value's placeholder takes its 33px line. -->
+    <USkeleton v-if="isFirstLoad" class="mt-1 h-[33px] w-32" />
+    <div
+      v-else-if="hasError"
+      class="mt-auto flex items-center justify-between gap-2"
+      role="alert"
+    >
+      <p class="text-error flex min-w-0 items-center gap-1.5 text-[12.5px]">
+        <UIcon name="i-ph-warning-circle" class="size-4 shrink-0" />
+        <span class="truncate">{{ t("dms.table.load_error_title") }}</span>
+      </p>
+      <UButton
+        :label="t('dms.table.load_error_retry')"
+        icon="i-ph-arrows-clockwise"
+        color="neutral"
+        variant="outline"
+        size="xs"
+        @click="refresh()"
+      />
+    </div>
+    <p
+      v-else
+      class="text-highlighted mt-1 text-[30px] leading-[1.1] font-[650] tracking-[-0.035em] tabular-nums transition-opacity"
+      :class="isRefreshing && 'opacity-55'"
+    >
+      <span
+        v-if="formattedParts.unit && formattedParts.unitIsPrefix"
+        class="text-muted mr-0.5 text-[0.6em] font-medium tracking-[-0.01em]"
+      >
+        {{ formattedParts.unit }}
+      </span>
+      <span>{{ formattedParts.value }}</span>
+      <span
+        v-if="formattedParts.unit && !formattedParts.unitIsPrefix"
+        class="text-muted ml-0.5 text-[0.6em] font-medium tracking-[-0.01em]"
+      >
+        {{ formattedParts.unit }}
+      </span>
+    </p>
+    <!-- The trend (a 24px line) and the footnote (16px) as the loaded card
+         lays them out; the footnote is a prop, so it is known up front. -->
+    <div
+      v-if="isFirstLoad && (showDelta || footnote || showSparkline)"
+      class="mt-auto flex items-end gap-2"
+    >
+      <div class="grid">
+        <div v-if="showDelta" class="flex h-6 items-center">
+          <USkeleton class="h-3 w-[58px]" />
+        </div>
+        <div v-if="footnote" class="flex h-4 items-center">
+          <USkeleton class="h-2.5 w-28" />
         </div>
       </div>
-      <div :class="iconWrapClass">
-        <UIcon
-          :name="resolvedIcon"
-          :class="isStat ? 'size-4' : 'size-5'"
-          :aria-hidden="true"
+      <USkeleton v-if="showSparkline" class="ml-auto h-[34px] w-24" />
+    </div>
+    <!-- The trend's line holds its place, as in the skeleton, while there is
+         no change to show (no comparison period): no "0%" stand-in, and
+         toggling a comparison never moves the footnote. -->
+    <div
+      v-else-if="!hasError && (showDelta || footnote || hasSparkline)"
+      class="mt-auto flex items-end gap-2"
+    >
+      <div class="min-w-0">
+        <div v-if="showDelta" class="flex h-6 items-center">
+          <DmsTrendBadge
+            v-if="showTrend"
+            :delta="delta"
+            :invert="invert"
+            variant="text"
+          />
+        </div>
+        <p
+          v-if="footnote"
+          class="text-dimmed truncate text-xs max-sm:whitespace-normal"
+        >
+          {{ footnote }}
+        </p>
+      </div>
+      <div
+        v-if="hasSparkline"
+        class="ml-auto h-[34px] w-24 shrink-0 transition-opacity"
+        :class="isRefreshing && 'opacity-55'"
+      >
+        <DmsSparkline
+          :values="sparkline"
+          :accent="resolvedSparklineAccent"
+          :aria-label="processI18n(title)"
         />
       </div>
     </div>
-    <div v-if="showSparkline && sparkline.length > 0" class="mt-4 h-10">
-      <DmsSparkline
-        :values="sparkline"
-        :accent="resolvedSparklineAccent"
-        :aria-label="processI18n(title)"
-      />
-    </div>
   </DmsCard>
 </template>

package/frontend-vue/layers/dms-ui/app/components/link/AutoLink.vue

@@ -0,0 +1,33 @@
+<script setup lang="ts">
+import { computed } from "vue";
+import { EXTERNAL_LINK_ATTRIBUTES, linkKind } from "../../build/utils/link";
+
+// A link whose target comes from data (a block option, a fetched row): a DMS
+// route goes through <DmsLink> (Inertia visit), an in-page anchor stays a bare
+// <a href="#…">, and an absolute URL opens in a new tab. Unstyled, so the
+// caller's classes (.dms-card, a row) style it.
+interface AutoLinkProps {
+  /** Route path, `#anchor` or absolute URL. */
+  to: string;
+}
+
+interface AutoLinkSlots {
+  default?: () => unknown;
+}
+
+const props = defineProps<AutoLinkProps>();
+defineSlots<AutoLinkSlots>();
+
+const kind = computed(() => linkKind(props.to));
+</script>
+
+<template>
+  <DmsLink v-if="kind === 'internal'" :to="props.to"><slot /></DmsLink>
+  <a
+    v-else
+    :href="props.to"
+    v-bind="kind === 'external' ? EXTERNAL_LINK_ATTRIBUTES : {}"
+  >
+    <slot />
+  </a>
+</template>