@antelopejs/dms 0.14.0 → 0.15.0

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## v0.15.0
+
+[compare changes](https://github.com/AntelopeJS/dms/compare/v0.14.0...v0.15.0)
+
+### 🚀 Enhancements
+
+- **dms-ui:** State the data state of each data block on its root element ([#585](https://github.com/AntelopeJS/dms/pull/585))
+
+### 🩹 Fixes
+
+- **table-view:** Currency on prices, settled counters, no add without a new route ([#611](https://github.com/AntelopeJS/dms/pull/611))
+- **interface-dms:** Name a bucketed series' periods for a person, 202608 as Aug 2026 ([#617](https://github.com/AntelopeJS/dms/pull/617))
+- **chart:** Thin the category x-axis labels of a long series so they never overlap ([#626](https://github.com/AntelopeJS/dms/pull/626))
+
+### 🏡 Chore
+
+- **release:** @antelopejs/interface-dms v0.10.3 ([53af1aad](https://github.com/AntelopeJS/dms/commit/53af1aad))
+
+### ❤️ Contributors
+
+- Antony Rizzitelli ([@Upd4ting](http://github.com/Upd4ting))
+
 ## v0.14.0
 
 [compare changes](https://github.com/AntelopeJS/dms/compare/v0.13.1...v0.14.0)

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

@@ -271,6 +271,20 @@ export function formatNumber(
   }
 }
 
+const CURRENCY_CODE = /^[A-Za-z]{3}$/;
+
+/**
+ * The currency an amount is written in: `options.currency` when it is an
+ * ISO 4217 code, euros otherwise (a missing or malformed code never turns the
+ * amount into a bare number).
+ */
+function priceCurrency(options: Intl.NumberFormatOptions | undefined): string {
+  const code = options?.currency;
+  return typeof code === "string" && CURRENCY_CODE.test(code)
+    ? code.toUpperCase()
+    : DEFAULT_CURRENCY;
+}
+
 /** An amount, in euros unless `options.currency` says otherwise. */
 export function formatPrice(
   value: number,
@@ -289,10 +303,10 @@ export function formatPrice(
 ): Parameters<typeof isNumber>[0] {
   return formatNumber(value, locale, {
     style: "currency",
-    currency: DEFAULT_CURRENCY,
     minimumFractionDigits: DEFAULT_PRICE_FRACTION_DIGITS,
     maximumFractionDigits: DEFAULT_PRICE_FRACTION_DIGITS,
     ...options,
+    currency: priceCurrency(options),
   });
 }
 

package/frontend-vue/layers/dms-ui/app/build/composables/blocks/blockDataState.ts

@@ -0,0 +1,86 @@
+import {
+  computed,
+  inject,
+  toValue,
+  type ComputedRef,
+  type InjectionKey,
+  type MaybeRefOrGetter,
+  type Ref,
+} from "vue";
+import type { ChartSeries } from "../../../composables/chart/types";
+
+/**
+ * What a data block shows its reader: still waiting for its first answer
+ * (`loading`), content (`ok`), an answer with nothing to draw (`empty`), or a
+ * request that failed with nothing to fall back on (`error`).
+ */
+export type BlockDataState = "loading" | "ok" | "empty" | "error";
+
+/**
+ * The attributes a data block carries on its root element. An overlay or a
+ * test harness reads them from the DOM, so the names are a contract.
+ */
+export const BLOCK_ATTRIBUTES = {
+  /** The block's position in the page layout: its key, then each child id, joined by dots. */
+  path: "data-dms-block",
+  /** The block kind as the page author names it, for example `ChartCard`. */
+  type: "data-dms-block-type",
+  /** A {@link BlockDataState}. */
+  state: "data-dms-block-state",
+} as const;
+
+/** The layout path of the block being rendered, provided by `RecursiveComponent`. */
+export const BLOCK_PATH_KEY: InjectionKey<Ref<string | undefined>> =
+  Symbol("dms-block-path");
+
+export interface BlockStateFacts {
+  /** An answer for the current inputs is still to come. */
+  loading: boolean;
+  /** The last request failed. */
+  failed: boolean;
+  /** The block has something to show its reader. */
+  hasContent: boolean;
+}
+
+/**
+ * The state of a block from three facts. Content wins over everything: a
+ * block refreshing or failing a refresh still shows what it had.
+ */
+export function resolveBlockState(facts: BlockStateFacts): BlockDataState {
+  if (facts.hasContent) return "ok";
+  if (facts.loading) return "loading";
+  if (facts.failed) return "error";
+  return "empty";
+}
+
+function isDrawable(point: ChartSeries["data"][number]): boolean {
+  if (typeof point === "number") return Number.isFinite(point);
+  return point.y !== null && point.y !== undefined;
+}
+
+/** Whether any series holds a point a chart can draw: not absent, not `null`. */
+export function hasDrawablePoints(series: readonly ChartSeries[]): boolean {
+  return series.some((entry) => entry.data.some(isDrawable));
+}
+
+export type BlockStateAttributes = {
+  [BLOCK_ATTRIBUTES.state]: BlockDataState;
+  [BLOCK_ATTRIBUTES.type]: string;
+  [BLOCK_ATTRIBUTES.path]?: string;
+};
+
+/**
+ * The attributes to bind on a data block's root element (`v-bind`): its
+ * kind, its state, and its layout path when a `RecursiveComponent` renders it.
+ */
+export function useBlockStateAttributes(
+  type: string,
+  state: MaybeRefOrGetter<BlockDataState>,
+): ComputedRef<BlockStateAttributes> {
+  const path = inject(BLOCK_PATH_KEY, null);
+  return computed(() => ({
+    [BLOCK_ATTRIBUTES.state]: toValue(state),
+    [BLOCK_ATTRIBUTES.type]: type,
+    [BLOCK_ATTRIBUTES.path]: path?.value,
+  }));
+}

package/frontend-vue/layers/dms-ui/app/build/composables/chart/apexAxes.ts

@@ -15,7 +15,15 @@ import {
 const CROSSHAIR_DASH = 3;
 const HIGH_CONTRAST_YAXIS_TYPES: ChartType[] = ["radar"];
 const CATEGORY_YAXIS_TYPES: ChartType[] = ["heatmap"];
-const SELF_THINNED_XAXIS_TYPES: ChartType[] = ["heatmap"];
+const SELF_THINNED_XAXIS_TYPES: ChartType[] = [
+  "heatmap",
+  "line",
+  "area",
+  "rangeArea",
+  "column",
+  "bar",
+  "mixed",
+];
 
 type YAxis = NonNullable<Exclude<ApexOptions["yaxis"], unknown[]>>;
 type XAxis = NonNullable<ApexOptions["xaxis"]>;
@@ -42,11 +50,22 @@ export function buildYAxis(
   return yaxis;
 }
 
-function thinsOwnXLabels(input: UseApexChartInput): boolean {
+/**
+ * Whether the chart draws a category x-axis whose labels this module thins.
+ * A horizontal bar puts its categories on the other axis. `bucketed` marks a
+ * datetime series Apex draws as a category axis of bucket labels.
+ */
+export function thinsOwnXLabels(
+  input: UseApexChartInput,
+  bucketed = false,
+): boolean {
   const settings = input.xAxis;
+  const horizontalBar =
+    input.type === "bar" && input.orientation !== "vertical";
   return (
     SELF_THINNED_XAXIS_TYPES.includes(input.type) &&
-    (input.xaxisType ?? "category") === "category" &&
+    !horizontalBar &&
+    (bucketed || (input.xaxisType ?? "category") === "category") &&
     settings?.hideOverlappingLabels !== false &&
     settings?.tickAmount === undefined &&
     !settings?.rotate

package/frontend-vue/layers/dms-ui/app/build/composables/table-view/tableViewCounts.ts

@@ -83,15 +83,27 @@ export function useTableViewCountsData<T extends Data>(
   const { liveHold } = scope.liveHold;
   const { tableViewItems, canSaveViews } = scope.views;
   const { props } = scope;
-  const { data: tabCountsData, refresh: refreshTabCounts } =
-    useTableCountsData<T>({
-      componentId,
-      pageId,
-      rows: tableRows,
-      queries: tabCountsQuery,
-      archiveQuery,
-      heldQuery: liveHold.heldQuery,
-    });
+  const {
+    data: tabCountsData,
+    status: tabCountsStatus,
+    refresh: refreshTabCounts,
+  } = useTableCountsData<T>({
+    componentId,
+    pageId,
+    rows: tableRows,
+    queries: tabCountsQuery,
+    archiveQuery,
+    heldQuery: liveHold.heldQuery,
+  });
+
+  /**
+   * The counters are still on their way: no answer yet, and no failure. A
+   * request that failed leaves `data` null as a pending one does, so it
+   * would draw the counters' skeleton for good.
+   */
+  const areCountsPending = computed(
+    () => tabCountsData.value == null && tabCountsStatus.value !== "error",
+  );
 
   const viewItems = computed<TableViewItem[]>(() =>
     tableViewItems.value.map((view) => ({
@@ -104,13 +116,20 @@ export function useTableViewCountsData<T extends Data>(
       count: view.count
         ? tabCountsData.value?.[`${VIEW_COUNT_ID_PREFIX}${view.id}`]
         : undefined,
-      countPending: !!view.count && tabCountsData.value == null,
+      countPending: !!view.count && areCountsPending.value,
     })),
   );
   const viewsLayout = props.views?.layout ?? "tabs";
   const hasViews =
     !!props.views && (props.views.items.length > 0 || canSaveViews);
-  return { refreshTabCounts, tabCountsData, viewItems, viewsLayout, hasViews };
+  return {
+    refreshTabCounts,
+    tabCountsData,
+    areCountsPending,
+    viewItems,
+    viewsLayout,
+    hasViews,
+  };
 }
 
 export function useTableViewLinkCounts<T extends Data>(

package/frontend-vue/layers/dms-ui/app/build/composables/table-view/tableViewTabs.ts

@@ -89,7 +89,7 @@ export function useTableViewTabs<T extends Data>(
 export function useTableViewTabPresentation<T extends Data>(
   scope: Pick<TableViewScope<T>, "countsData" | "linkCounts" | "tabs">,
 ) {
-  const { tabCountsData } = scope.countsData;
+  const { tabCountsData, areCountsPending } = scope.countsData;
   const { linkTabCountsLoaded, linkTabCounts } = scope.linkCounts;
   const { resolvedTabs } = scope.tabs;
   const permissionPreview = usePermissionPreview();
@@ -104,7 +104,7 @@ export function useTableViewTabPresentation<T extends Data>(
   };
 
   const isTabCountPending = (tab: ResolvedTab): boolean => {
-    if (!tab.to) return tabCountsData.value == null;
+    if (!tab.to) return areCountsPending.value;
     return !!tab.countFrom && !linkTabCountsLoaded.value;
   };
 

package/frontend-vue/layers/dms-ui/app/components/RecursiveComponent.vue

@@ -9,6 +9,7 @@ import {
 } from "./grid/constants";
 import DmsPermissionVeil from "../build/components/permission/PermissionVeil.vue";
 import { registerBlockAnchor } from "../build/composables/page/blockAnchors";
+import { BLOCK_PATH_KEY } from "../build/composables/blocks/blockDataState";
 
 interface Props {
   component: ResolvedComponentInfo;
@@ -40,6 +41,11 @@ function anchorBlock(instance: Element | ComponentPublicInstance | null): void {
   anchored = block;
 }
 
+provide(
+  BLOCK_PATH_KEY,
+  computed(() => props.layoutPath),
+);
+
 const { t } = useI18n();
 const preview = usePermissionPreview();
 const previewBlock = computed(() => preview.blockFor(props.layoutPath));

package/frontend-vue/layers/dms-ui/app/components/chart/Chart.vue

@@ -2,6 +2,11 @@
 import { computed, inject, ref, watch } from "vue";
 import DmsEmptyState from "../empty-state/EmptyState.vue";
 import DmsChartSkeleton from "../../build/components/chart/internal/ChartSkeleton.vue";
+import {
+  hasDrawablePoints,
+  resolveBlockState,
+  useBlockStateAttributes,
+} from "../../build/composables/blocks/blockDataState";
 import {
   chartFrameHeight,
   useApexChart,
@@ -148,7 +153,7 @@ const staticDonut = computed<DonutRecord[]>(() => {
 
 const isNested = computed(() => !!nestedContext);
 
-const { data, isLoading } = useChartFetch<ChartResponse>({
+const { data, isLoading, error } = useChartFetch<ChartResponse>({
   fetchUrl: isNested.value ? undefined : props.fetchUrl,
   fetchUrlMethod: props.fetchUrlMethod,
   routeParams: () => props.routeParams,
@@ -318,6 +323,16 @@ const isAwaitingData = computed(() =>
 
 const isRefreshing = computed(() => hasData.value && isAwaitingData.value);
 
+const blockAttributes = useBlockStateAttributes("Chart", () =>
+  resolveBlockState({
+    loading: isAwaitingData.value,
+    failed: !nestedContext && Boolean(error.value),
+    hasContent: isCircular.value
+      ? finalDonutData.value.some((record) => record.value !== 0)
+      : hasDrawablePoints(finalSeries.value),
+  }),
+);
+
 const isDrawn = ref(false);
 watch(hasData, (present) => {
   if (!present) isDrawn.value = false;
@@ -328,6 +343,7 @@ watch(hasData, (present) => {
   <!-- Standalone charts get the card frame; charts nested inside a
        DmsChartCard inherit its frame instead. -->
   <div
+    v-bind="blockAttributes"
     class="dms-chart"
     :class="nestedContext ? undefined : 'dms-card p-3.5 sm:pr-[18px]'"
   >

package/frontend-vue/layers/dms-ui/app/components/chart/ChartCard.vue

@@ -1,5 +1,10 @@
 <script setup lang="ts">
 import { computed, provide, reactive } from "vue";
+import {
+  hasDrawablePoints,
+  resolveBlockState,
+  useBlockStateAttributes,
+} from "../../build/composables/blocks/blockDataState";
 import DmsEyebrow from "../section-header/Eyebrow.vue";
 
 import DmsTrendBadge from "./internal/TrendBadge.vue";
@@ -71,7 +76,7 @@ const { state: watchState } = useWatch(
 );
 const watchKey = computed(() => JSON.stringify(watchState.value));
 
-const { data, isLoading } = useChartFetch<ChartCardResponse>({
+const { data, isLoading, error } = useChartFetch<ChartCardResponse>({
   fetchUrl: props.fetchUrl,
   fetchUrlMethod: props.fetchUrlMethod,
   routeParams: () => props.routeParams,
@@ -159,6 +164,17 @@ const comparisonLegendLabel = computed(() =>
       t(DEFAULT_COMPARISON_LABEL_KEY, "Comparison")),
 );
 
+const blockAttributes = useBlockStateAttributes("ChartCard", () =>
+  resolveBlockState({
+    loading: isLoading.value,
+    failed: Boolean(error.value),
+    hasContent:
+      value.value !== undefined ||
+      hasDrawablePoints(cardSeries.value) ||
+      hasDrawablePoints(cardComparisonSeries.value),
+  }),
+);
+
 const isFirstLoad = computed(() => isLoading.value && data.value === null);
 
 const isRefreshing = computed(() => isLoading.value && data.value !== null);
@@ -170,7 +186,11 @@ const hasMeta = computed(
 </script>
 
 <template>
-  <DmsCard :padded="false" class="flex min-w-0 flex-col">
+  <DmsCard
+    v-bind="blockAttributes"
+    :padded="false"
+    class="flex min-w-0 flex-col"
+  >
     <div class="flex flex-wrap items-start gap-3 px-4 pt-4 pb-1.5 sm:px-[18px]">
       <div class="grid min-w-0 justify-items-start">
         <DmsEyebrow

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

@@ -1,5 +1,9 @@
 <script setup lang="ts">
 import { computed } from "vue";
+import {
+  resolveBlockState,
+  useBlockStateAttributes,
+} from "../../build/composables/blocks/blockDataState";
 import DmsStatCell from "../../build/components/stat/StatCell.vue";
 import DmsEyebrow from "../section-header/Eyebrow.vue";
 
@@ -129,6 +133,14 @@ const previousText = computed(() => {
   return t("dms.chart.versus_value", { value: formatted });
 });
 
+const blockAttributes = useBlockStateAttributes("KpiCard", () =>
+  resolveBlockState({
+    loading: isLoading.value,
+    failed: Boolean(error.value),
+    hasContent: value.value !== undefined,
+  }),
+);
+
 const isFirstLoad = computed(() => isLoading.value && data.value === null);
 
 const hasError = computed(
@@ -181,6 +193,7 @@ const isStat = computed(() => props.variant === "stat");
 <template>
   <DmsStatCell
     v-if="isStat"
+    v-bind="blockAttributes"
     :eyebrow="processI18n(title)"
     :icon="resolvedIcon"
     :loading="isFirstLoad"
@@ -245,6 +258,7 @@ const isStat = computed(() => props.variant === "stat");
 
   <DmsCard
     v-else
+    v-bind="blockAttributes"
     :padded="false"
     class="flex min-h-[132px] flex-col gap-1.5 px-4 py-4 sm:px-[18px]"
     :aria-busy="isFirstLoad"

package/frontend-vue/layers/dms-ui/app/components/table-view/TableView.vue

@@ -18,6 +18,10 @@ import ExpandedRowDetail from "../../build/components/table-view/ExpandedRowDeta
 import LiveHoldBanner from "../../build/components/table-view/LiveHoldBanner.vue";
 import TableViews from "../../build/components/table/Views.vue";
 import { useTableViewSetup } from "../../build/composables/table-view/tableViewSetup";
+import {
+  resolveBlockState,
+  useBlockStateAttributes,
+} from "../../build/composables/blocks/blockDataState";
 
 interface TableViewProps<T extends Data> extends TableViewConfig<T> {
   /** Expandable rows: caret column + detail band (backend `expandable`). */
@@ -143,18 +147,27 @@ const {
   handleRowEdit,
   contextForSlot,
 } = useTableViewSetup<T>(props);
+
+const blockAttributes = useBlockStateAttributes("TableView", () =>
+  resolveBlockState({
+    loading: isListLoading.value,
+    failed: Boolean(listLoadError.value || listNotFound.value),
+    hasContent: (shownResults.value?.length ?? 0) > 0,
+  }),
+);
 </script>
 
 <template>
   <DmsBlockStatus
     v-if="listNotFound"
+    v-bind="blockAttributes"
     state="not-found"
     :not-found="listNotFound"
   />
   <UTable
     v-else
     ref="tableRoot"
-    v-bind="tableProps"
+    v-bind="{ ...tableProps, ...blockAttributes }"
     v-model:pagination="paginationState"
     v-model:global-filter="globalFilter"
     v-model:sorting="sorting"

package/frontend-vue/layers/dms-ui/app/components/top-list/TopListCard.vue

@@ -1,5 +1,9 @@
 <script setup lang="ts">
 import { computed, nextTick, onMounted, ref, watch } from "vue";
+import {
+  resolveBlockState,
+  useBlockStateAttributes,
+} from "../../build/composables/blocks/blockDataState";
 import DmsEmptyState from "../empty-state/EmptyState.vue";
 import DmsSectionHeader from "../section-header/SectionHeader.vue";
 import DmsBlockActions, {
@@ -219,6 +223,14 @@ const badgeLabel = computed<string | null>(() => {
 const comparison = usePeriodComparisonDisplay(props.periodScope);
 const showRowDelta = computed(() => props.showDelta && !comparison.isOff.value);
 
+const blockAttributes = useBlockStateAttributes("TopListCard", () =>
+  resolveBlockState({
+    loading: isLoading.value,
+    failed: Boolean(error.value),
+    hasContent: items.value.length > 0,
+  }),
+);
+
 const isFirstLoad = computed(() => isLoading.value && data.value === null);
 
 const isRefreshing = computed(() => isLoading.value && data.value !== null);
@@ -268,7 +280,11 @@ const gridStyle = computed(() => ({
 </script>
 
 <template>
-  <DmsCard :padded="false" class="flex min-w-0 flex-col overflow-hidden">
+  <DmsCard
+    v-bind="blockAttributes"
+    :padded="false"
+    class="flex min-w-0 flex-col overflow-hidden"
+  >
     <DmsSectionHeader
       size="card"
       class="border-default border-b py-3.5 pr-4 pl-[18px]"

package/frontend-vue/layers/dms-ui/app/composables/chart/apexCategoryLabels.ts

@@ -1,5 +1,4 @@
 import { isNumber } from "../../../../dms-core/app/utils/type-check";
-import type { ChartXAxisFormatter } from "./types";
 
 /**
  * Width of one character of the axis font (11px, monospace) in pixels, with a
@@ -38,19 +37,22 @@ export function categoryLabelStep(
 }
 
 /**
- * A heatmap gives every column a label and ApexCharts does not thin them
- * (`hideOverlappingLabels` only acts on other charts), so on a phone they run
- * into each other ("07:0009:00"). This formatter keeps one label every few
- * columns, from the plot's width, and leaves the tooltip's (no column index)
- * whole.
+ * A category x-axis gives every point a label and ApexCharts does not thin
+ * them (`hideOverlappingLabels` only acts on numeric and datetime axes), so a
+ * long series or a narrow plot runs them into each other ("Aug 4, 2026Aug 8,
+ * 2026"). This formatter keeps one label every few columns, from the plot's
+ * width, and leaves the tooltip's (no column index) whole.
  */
 export function thinnedCategoryFormatter(
-  format: ChartXAxisFormatter | undefined,
+  format: ApexLabelFormatter | undefined,
 ): ApexLabelFormatter {
-  const write = (value: string, timestamp?: number): string =>
-    format ? format(value, timestamp) : String(value ?? "");
+  const write = (
+    value: string,
+    timestamp?: number,
+    opts?: ApexLabelFormatterOpts,
+  ): string => (format ? format(value, timestamp, opts) : String(value ?? ""));
   return (value, timestamp, opts) => {
-    const label = write(value, timestamp);
+    const label = write(value, timestamp, opts);
     const index = opts?.i;
     const globals = opts?.w?.globals;
     if (!isNumber(index) || !globals) return label;

package/frontend-vue/layers/dms-ui/app/composables/chart/useApexChart.ts

@@ -16,7 +16,12 @@ import {
 import { APEX_TYPE_CONFIGS } from "./apexTypeConfigs";
 import { buildAnnotations } from "./apexAnnotations";
 import { buildPlotOptions, ringFitsSliceLabels } from "./apexPlotOptions";
-import { buildXAxis, buildYAxis } from "../../build/composables/chart/apexAxes";
+import {
+  buildXAxis,
+  buildYAxis,
+  thinsOwnXLabels,
+} from "../../build/composables/chart/apexAxes";
+import { thinnedCategoryFormatter } from "./apexCategoryLabels";
 import {
   applyHeatmapThemeMode,
   applyValueBasedColorScale,
@@ -271,10 +276,14 @@ function applyDatetimeBuckets(
   if (!buckets) return;
   const xaxis = options.xaxis;
   const { format: _datetimeFormat, ...labels } = xaxis.labels;
+  const bucketLabels = bucketAxisFormatter(buckets, input);
+  const bucketFormatter = thinsOwnXLabels(input, true)
+    ? thinnedCategoryFormatter(bucketLabels)
+    : bucketLabels;
   options.xaxis = {
     ...xaxis,
     type: "category",
-    labels: { ...labels, formatter: bucketAxisFormatter(buckets, input) },
+    labels: { ...labels, formatter: bucketFormatter },
   };
   const tooltip = options.tooltip;
   options.tooltip = {

package/frontend-vue/layers/dms-ui/app/entries/composables/blocks/blockDataState.ts

@@ -0,0 +1 @@
+export * from "../../../build/composables/blocks/blockDataState";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@antelopejs/dms",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "description": "AntelopeJS DMS. Plug in your PostgreSQL, MongoDB or RethinkDB database and your coding agent builds a back office and analytics dashboard as typed TypeScript. Real-time updates on the data the DMS manages.",
   "keywords": [
     "antelopejs",