@antelopejs/dms 0.7.11 → 0.7.12

package/frontend-vue/layers/dms-ui/app/composables/live/usePageLiveRefresh.ts

@@ -0,0 +1,103 @@
+import { onBeforeUnmount, onMounted, type ComputedRef } from "vue";
+import { useRefreshTriggers } from "../../build/composables/blocks/useRefreshTriggers";
+import { usePageLive } from "./usePageLive";
+
+const MS_PER_SECOND = 1000;
+// How often an idle refresh looks at the clock: a read lands at most this
+// late after its idle period.
+const IDLE_CHECK_MS = 5 * MS_PER_SECOND;
+
+/** What makes a module's component read its data again (see {@link usePageLiveRefresh}). */
+export interface PageLiveRefreshOptions {
+  /**
+   * Realtime topics whose events make the component read again, as a
+   * built-in block's `realtimeTopic`.
+   */
+  realtimeTopic?: string | string[];
+  /**
+   * Reads again after this many seconds without a read, while the page is
+   * live: for data that moves with time alone (a health judged over the last
+   * hour, a "last seen"), when no event comes. Nothing is read while paused.
+   */
+  idleRefresh?: number;
+}
+
+/** The refresh of a module's component, gated like a built-in block's. */
+export interface PageLiveRefresh {
+  /** Events the component missed while the page is paused, 0 when live. */
+  missed: ComputedRef<number>;
+  /**
+   * A read nobody asked for (a clock, a feed of the component's own): capped
+   * by `maxRate` in Direct, counted while paused and read once on resume.
+   */
+  trigger: () => void;
+  /** Reads now, paused or not, as an action of the user does. */
+  refreshNow: () => void;
+}
+
+/**
+ * Keeps a module's own component in step with the page's Live / Pause state
+ * exactly as the built-in blocks with a `realtimeTopic` are: `refresh` runs on
+ * the events of `realtimeTopic` and on `refreshLivePageBlocks()` at most once
+ * per `maxRate` in Direct (the slower `slowRateAfter` rate once the page's
+ * `PeriodSelector` shows a long period), the last event of a burst included;
+ * paused, nothing runs, the missed events count in the toggle's "N new", and
+ * one read catches up on resume. `refreshPageBlocks()`, an action of the
+ * user, runs it at once, paused or not.
+ *
+ * On a page without `live`, `refresh` runs on every event and every refresh
+ * of the page. Call it from a component's setup; the subscriptions end with
+ * the component.
+ *
+ * ```ts
+ * const { useFetchAuth } = useAuthFetch();
+ * const { data, refresh } = useFetchAuth<Health>("/api/health");
+ * usePageLiveRefresh(() => void refresh(), {
+ *   realtimeTopic: "api:requests",
+ *   idleRefresh: 60,
+ * });
+ * ```
+ */
+export function usePageLiveRefresh(
+  refresh: () => void,
+  options: PageLiveRefreshOptions = {},
+): PageLiveRefresh {
+  let lastReadAt = Date.now();
+  const read = () => {
+    lastReadAt = Date.now();
+    refresh();
+  };
+  const gate = useRefreshTriggers(options.realtimeTopic, read);
+  if (options.idleRefresh) {
+    useIdleRefresh(
+      options.idleRefresh * MS_PER_SECOND,
+      () => lastReadAt,
+      gate.trigger,
+    );
+  }
+  return {
+    missed: gate.missed,
+    trigger: () => gate.trigger(),
+    refreshNow: () => gate.catchUp(),
+  };
+}
+
+// Browser only, from mount: a server render reads once and has no clock.
+function useIdleRefresh(
+  idleMs: number,
+  lastReadAt: () => number,
+  trigger: () => void,
+): void {
+  const live = usePageLive();
+  let timer: ReturnType<typeof setInterval> | undefined;
+  onMounted(() => {
+    timer = setInterval(
+      () => {
+        if (live.isPaused.value) return;
+        if (Date.now() - lastReadAt() >= idleMs) trigger();
+      },
+      Math.min(idleMs, IDLE_CHECK_MS),
+    );
+  });
+  onBeforeUnmount(() => clearInterval(timer));
+}

package/frontend-vue/layers/dms-ui/app/composables/tab/types/composable.ts

@@ -2,6 +2,7 @@ export interface UseTabReturn {
   activeTab: Ref<string>;
   nextTab: () => void;
   previousTab: () => void;
+  /** Opens a tab by its index, or by its slot (`"tester"`). */
   goToTab: (index: number | string) => void;
   goToFirstTab: () => void;
   goToLastTab: () => void;

package/frontend-vue/layers/dms-ui/app/composables/tab/types/item.ts

@@ -1,10 +1,17 @@
 import type { AvatarProps, BadgeProps } from "@nuxt/ui";
+import type { BlockText } from "../../../../../dms-core/app/types/composed-text";
 
 export interface TabItem {
   label: string;
+  /** The tab's id: its panel's slot, and its name in the URL (`?tab=<slot>`). */
   slot: string;
   icon?: string;
-  badge?: string | number | BadgeProps;
+  /**
+   * A count or a short word after the label: a `$` i18n key or a
+   * `ComposedText` is written in the reader's language, as is the `label`
+   * of a `BadgeProps`.
+   */
+  badge?: BlockText | number | BadgeProps;
   disabled?: boolean;
   shortcut?: string;
   avatar?: AvatarProps;

package/frontend-vue/layers/dms-ui/app/composables/tab/useTab.ts

@@ -1,3 +1,21 @@
+/**
+ * The index of the tab a URL names: its slot (`?tab=tester`), or its index
+ * (`?tab=2`) as written before tabs were named. `null` when it names none.
+ */
+function tabIndexOf(
+  value: unknown,
+  slots: readonly string[],
+  tabCount: number,
+): number | null {
+  if (typeof value !== "string" || value === "") return null;
+  const bySlot = slots.indexOf(value);
+  if (bySlot >= 0) return bySlot;
+  const index = Number(value);
+  return Number.isInteger(index) && index >= 0 && index < tabCount
+    ? index
+    : null;
+}
+
 export function useTab(
   tabCount: Ref<number> | number,
   props: TabProps,
@@ -15,24 +33,22 @@ export function useTab(
   const totalTabs = computed(() =>
     isNumber(tabCount) ? tabCount : tabCount.value,
   );
+  const slots = computed(() => (props.items ?? []).map((item) => item.slot));
+
+  const urlTabIndex = (value: unknown) =>
+    tabIndexOf(value, slots.value, totalTabs.value);
 
   const getInitialTab = () => {
-    if (props.persistState && route.query[stateKey]) {
-      const tabFromUrl = route.query[stateKey] as string;
-      const tabIndex = Number.parseInt(tabFromUrl, 10);
-      if (
-        !Number.isNaN(tabIndex) &&
-        tabIndex >= 0 &&
-        tabIndex < totalTabs.value
-      ) {
-        return tabFromUrl;
-      }
-    }
-    return String(0);
+    const fromUrl = props.persistState
+      ? urlTabIndex(route.query[stateKey])
+      : null;
+    return String(fromUrl ?? 0);
   };
 
   const activeTab = ref<string>(getInitialTab());
 
+  // The open tab is written by its slot, which stays right when tabs are
+  // added or reordered; a tab without one keeps its index.
   const updateUrl = async (newTab: string) => {
     if (!props.persistState) return;
 
@@ -41,13 +57,15 @@ export function useTab(
       // eslint-disable-next-line @typescript-eslint/no-dynamic-delete
       delete query[stateKey];
     } else {
-      query[stateKey] = newTab;
+      query[stateKey] = slots.value[Number(newTab)] || newTab;
     }
     await router.push({ query });
   };
 
   const goToTab = (index: number | string) => {
-    const indexNum = isString(index) ? Number.parseInt(index, 10) : index;
+    const indexNum = isString(index)
+      ? (tabIndexOf(index, slots.value, totalTabs.value) ?? -1)
+      : index;
     const indexStr = String(indexNum);
 
     if (indexNum < 0 || indexNum >= totalTabs.value) {
@@ -95,15 +113,9 @@ export function useTab(
     (newValue) => {
       if (!props.persistState) return;
 
-      const tabStr = newValue as string;
-      const tabIndex = Number.parseInt(tabStr, 10);
-      if (
-        !Number.isNaN(tabIndex) &&
-        tabIndex >= 0 &&
-        tabIndex < totalTabs.value &&
-        tabStr !== activeTab.value
-      ) {
-        activeTab.value = tabStr;
+      const tabIndex = urlTabIndex(newValue);
+      if (tabIndex !== null && String(tabIndex) !== activeTab.value) {
+        activeTab.value = String(tabIndex);
       }
     },
   );

package/frontend-vue/layers/dms-ui/app/types/input-number.ts

@@ -0,0 +1,18 @@
+/**
+ * Why a number field keeps another value than the one typed: above its `max`,
+ * below its `min`, or off its `step`.
+ */
+export type InputNumberAdjustmentReason = "min" | "max" | "step";
+
+/**
+ * What `DmsInputNumber` emits as `adjust` when it settles a typed number on
+ * another value (on leaving the field, or on Enter): 1020 typed in a field of
+ * steps of 50 gives `{ typed: 1020, value: 1000, reason: "step" }`.
+ */
+export interface InputNumberAdjustment {
+  /** The number as typed. */
+  typed: number;
+  /** The number the field keeps, and now shows. */
+  value: number;
+  reason: InputNumberAdjustmentReason;
+}

package/frontend-vue/layers/dms-ui/app/types/live.ts

@@ -51,4 +51,10 @@ export interface TableViewLiveHoldOptions {
   whileRowOpen?: boolean;
   /** While the user has scrolled its first row out of view. */
   whileScrolled?: boolean;
+  /** While the user's search narrows the rows. */
+  whileSearching?: boolean;
+  /** While the user sorts the rows otherwise than by the table's default. */
+  whileSorted?: boolean;
+  /** What the strip calls the new rows, given `{count}`. */
+  missedLabel?: string;
 }

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

@@ -0,0 +1,23 @@
+import { blockAnchorElement } from "../build/composables/page/blockAnchors";
+
+const DEFAULT_SCROLL: ScrollIntoViewOptions = { block: "start" };
+
+/**
+ * Brings a block of the page into view, by its anchor: the key path it is
+ * declared under, its static field's key for a top-level block (`summary`),
+ * then each child key down to it (`tabs.statistics`, `grid.row.latency`).
+ * Answers `false`, without scrolling, when no such block is on screen: an
+ * unknown key, a block in a closed tab, or one the viewer may not see.
+ *
+ * @param key The block's anchor
+ * @param options Passed to `scrollIntoView`; defaults to `{ block: "start" }`
+ */
+export function scrollToBlock(
+  key: string,
+  options: ScrollIntoViewOptions = DEFAULT_SCROLL,
+): boolean {
+  const element = blockAnchorElement(key);
+  if (!element) return false;
+  element.scrollIntoView(options);
+  return true;
+}

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

@@ -702,7 +702,9 @@
       "error_title": "Activity could not be loaded",
       "error_description": "Check your connection, then try again.",
       "retry": "Try again",
-      "list_label": "Activity"
+      "list_label": "Activity",
+      "show_more": "Show {count} more",
+      "show_fewer": "Show fewer"
     },
     "leave_guard": {
       "title": "Discard unsaved changes?",
@@ -745,7 +747,12 @@
       "paused": "Paused",
       "resume": "Resume",
       "reason_hidden": "tab hidden",
-      "polling": "no realtime, polling"
+      "polling": "no realtime, polling",
+      "table_held": "Table on hold",
+      "held_row_open": "row open",
+      "held_searching": "search active",
+      "held_sorted": "sorted otherwise than by default",
+      "held_scrolled": "scrolled down"
     }
   }
 }

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

@@ -703,7 +703,9 @@
       "error_title": "Impossible de charger l'activité",
       "error_description": "Vérifiez votre connexion, puis réessayez.",
       "retry": "Réessayer",
-      "list_label": "Activité"
+      "list_label": "Activité",
+      "show_more": "Afficher {count} de plus",
+      "show_fewer": "Afficher moins"
     },
     "leave_guard": {
       "title": "Abandonner les modifications non enregistrées ?",
@@ -746,7 +748,12 @@
       "paused": "En pause",
       "resume": "Reprendre",
       "reason_hidden": "onglet masqué",
-      "polling": "sans temps réel, relecture régulière"
+      "polling": "sans temps réel, relecture régulière",
+      "table_held": "Tableau figé",
+      "held_row_open": "ligne ouverte",
+      "held_searching": "recherche active",
+      "held_sorted": "tri autre que celui par défaut",
+      "held_scrolled": "défilé vers le bas"
     }
   }
 }

package/frontend-vue/tests/activity-feed-fold.test.ts

@@ -0,0 +1,119 @@
+// @vitest-environment jsdom
+/**
+ * An ActivityFeed that must not hide what its entries say: `wrap` lets each
+ * entry take the lines it needs instead of an ellipsis, and `visibleItems`
+ * shows the first entries with a "Show N more" button that unfolds the rest.
+ */
+import { computed, createApp, defineComponent, h, nextTick, ref } from "vue";
+import { afterEach, beforeEach, expect, it, vi } from "vitest";
+import ActivityFeed from "../layers/dms-ui/app/components/activity-feed/ActivityFeed.vue";
+
+const items = ref<Array<Record<string, unknown>>>([]);
+
+vi.mock("../layers/dms-ui/app/build/composables/blocks/useBlockItems", () => ({
+  useBlockItems: () => ({
+    items: computed(() => items.value),
+    count: computed(() => undefined),
+    isPending: computed(() => false),
+    hasError: computed(() => false),
+    refresh: async () => {},
+  }),
+}));
+
+const Stub = defineComponent({
+  inheritAttrs: false,
+  props: { title: { type: String, default: undefined }, label: String },
+  setup:
+    (props, { slots, attrs }) =>
+    () =>
+      h(
+        attrs.onClick ? "button" : "div",
+        { class: attrs.class, onClick: attrs.onClick },
+        [props.label ?? props.title, slots.default?.()],
+      ),
+});
+
+let app: ReturnType<typeof createApp> | undefined;
+
+function mountFeed(props: Record<string, unknown>): HTMLElement {
+  const host = document.createElement("div");
+  app = createApp(() =>
+    h(ActivityFeed, {
+      componentId: "attention",
+      pageId: "overview",
+      groupByDay: false,
+      ...props,
+    }),
+  );
+  for (const name of ["DmsCard", "UIcon", "USkeleton", "UButton", "ULink"]) {
+    app.component(name, Stub);
+  }
+  app.mount(host);
+  return host;
+}
+
+const entryTitles = (host: HTMLElement) =>
+  host.textContent?.match(/Route \d/g) ?? [];
+
+beforeEach(() => {
+  items.value = Array.from({ length: 5 }, (_, index) => ({
+    id: `r${index}`,
+    title: `Route ${index}`,
+    detail: `500 "Upstream timed out while reading the response" × ${index + 1}`,
+  }));
+  vi.stubGlobal("useI18n", () => ({
+    locale: ref("en-GB"),
+    t: (key: string, params?: { count?: number }) =>
+      params ? `${key}:${params.count}` : key,
+  }));
+  vi.stubGlobal("useTranslation", () => ({ processI18n: String }));
+});
+
+afterEach(() => {
+  app?.unmount();
+  vi.unstubAllGlobals();
+});
+
+it("shows every entry, without a fold, by default", () => {
+  const host = mountFeed({});
+  expect(entryTitles(host)).toHaveLength(5);
+  expect(host.querySelector(".dms-activity-feed__fold")).toBeNull();
+});
+
+it("shows the first visibleItems and unfolds the rest, then folds them back", async () => {
+  const host = mountFeed({ visibleItems: 3 });
+  expect(entryTitles(host)).toEqual(["Route 0", "Route 1", "Route 2"]);
+  const button = host.querySelector<HTMLButtonElement>(
+    ".dms-activity-feed__fold button",
+  )!;
+  expect(button.textContent).toBe("dms.activity_feed.show_more:2");
+
+  button.click();
+  await nextTick();
+  expect(entryTitles(host)).toHaveLength(5);
+  expect(button.textContent).toBe("dms.activity_feed.show_fewer");
+
+  button.click();
+  await nextTick();
+  expect(entryTitles(host)).toHaveLength(3);
+});
+
+it("needs no fold when the entries fit in visibleItems", () => {
+  const host = mountFeed({ visibleItems: 5 });
+  expect(host.querySelector(".dms-activity-feed__fold")).toBeNull();
+});
+
+it("cuts each entry to one line by default, and wraps it whole with wrap", () => {
+  const cut = mountFeed({ mono: true });
+  expect(cut.querySelector(".truncate")).not.toBeNull();
+  app?.unmount();
+
+  const wrapped = mountFeed({ mono: true, wrap: true });
+  expect(wrapped.querySelector(".truncate")).toBeNull();
+  expect(
+    wrapped.querySelector(".\\[overflow-wrap\\:anywhere\\]"),
+  ).not.toBeNull();
+  expect(wrapped.textContent).toContain(
+    '500 "Upstream timed out while reading the response" × 1',
+  );
+});

package/frontend-vue/tests/chart-legend.test.ts

@@ -0,0 +1,133 @@
+/**
+ * A chart names its series in a legend drawn in the dashboard's colours, at
+ * the top of an axis chart or under a circular one unless `legendPosition`
+ * says otherwise. Inside a ChartCard the chart's legend stays off, the card
+ * heading its single series, until the card asks for it with
+ * `showSeriesLegend`: no raw Apex `legend` option is needed for either.
+ */
+import { createSSRApp, defineComponent, h, ref, type PropType } from "vue";
+import { renderToString } from "vue/server-renderer";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import ChartCard from "../layers/dms-ui/app/components/chart/ChartCard.vue";
+import Chart from "../layers/dms-ui/app/components/chart/Chart.vue";
+import { useApexChart } from "../layers/dms-ui/app/composables/chart/useApexChart";
+import type { UseApexChartInput } from "../layers/dms-ui/app/composables/chart/useApexChart.types";
+import type { ChartSeries } from "../layers/dms-ui/app/composables/chart/types";
+
+const SERIES: ChartSeries[] = [
+  { name: "Average", data: [{ x: "10:00", y: 42 }] },
+  { name: "p95", data: [{ x: "10:00", y: 96 }] },
+];
+
+vi.mock("../layers/dms-ui/app/composables/chart/useChartFetch", () => ({
+  useChartFetch: () => ({
+    data: ref({ value: 42, series: SERIES }),
+    isLoading: ref(false),
+  }),
+}));
+
+interface LegendOptions {
+  show: boolean;
+  position: string;
+}
+
+const LegendProbe = defineComponent({
+  props: {
+    options: {
+      type: Object as PropType<{ legend: LegendOptions }>,
+      required: true,
+    },
+  },
+  setup: (props) => () =>
+    h("output", {
+      "data-show": String(props.options.legend.show),
+      "data-position": props.options.legend.position,
+    }),
+});
+
+const Slot = defineComponent({
+  setup:
+    (_, { slots }) =>
+    () =>
+      h("div", slots.default?.()),
+});
+
+function legendOf(input: Partial<UseApexChartInput>) {
+  const chart = useApexChart(() => ({
+    type: "line",
+    series: SERIES,
+    ...input,
+  }));
+  return chart.options.value.legend as Record<string, unknown>;
+}
+
+async function renderCard(cardProps: Record<string, unknown>) {
+  vi.stubGlobal("useI18n", () => ({
+    locale: ref("en"),
+    t: (key: string) => key,
+  }));
+  vi.stubGlobal("useTranslation", () => ({
+    processI18n: (text: string) => text,
+  }));
+  vi.stubGlobal("useComponentEvent", () => ({}));
+  vi.stubGlobal("useWatch", () => ({ state: ref({}) }));
+  const app = createSSRApp({
+    render: () =>
+      h(
+        ChartCard,
+        {
+          title: "Latency",
+          componentId: "card",
+          pageId: "routes",
+          ...cardProps,
+        },
+        () =>
+          h(Chart, {
+            type: "line",
+            componentId: "plot",
+            pageId: "routes",
+            legendPosition: "bottom",
+          }),
+      ),
+  });
+  for (const name of ["DmsCard", "DmsClientOnly", "UIcon", "USkeleton"])
+    app.component(name, Slot);
+  app.component("DmsApexChartHost", LegendProbe);
+  return renderToString(app);
+}
+
+afterEach(() => vi.unstubAllGlobals());
+
+describe("chart legend", () => {
+  it("sits above an axis chart and under a circular one by default", () => {
+    expect(legendOf({}).position).toBe("top");
+    expect(legendOf({ type: "donut", series: [] }).position).toBe("bottom");
+  });
+
+  it("follows legendPosition", () => {
+    expect(legendOf({ legendPosition: "bottom" }).position).toBe("bottom");
+    expect(
+      legendOf({ type: "donut", series: [], legendPosition: "top" }).position,
+    ).toBe("top");
+  });
+
+  it("is drawn in the dashboard's theme", () => {
+    const legend = legendOf({});
+    expect(legend.show).toBe(true);
+    expect(legend.markers).toMatchObject({ shape: "square", strokeWidth: 0 });
+    expect(legend.labels).toHaveProperty("colors");
+  });
+});
+
+describe("series legend of a ChartCard", () => {
+  it("stays off in a card by default", async () => {
+    const html = await renderCard({});
+    expect(html).toContain('data-show="false"');
+  });
+
+  it("names the series where the chart places it when the card asks", async () => {
+    const html = await renderCard({ showSeriesLegend: true });
+    expect(html).toContain('data-show="true"');
+    expect(html).toContain('data-position="bottom"');
+  });
+});

package/frontend-vue/tests/code-block.test.ts

@@ -94,6 +94,34 @@ describe("DmsCodeSnippet", () => {
     expect(pre().previousElementSibling).toBeNull();
   });
 
+  it("floats the copy button in the code's corner without a title or a language", async () => {
+    await mountSnippet({ code: '{"ok":true}' });
+    expect(host.querySelector("[data-floating-copy]")).toBe(copyButton());
+    expect(host.textContent).not.toContain("Text");
+    expect(pre().className).toContain("pe-10");
+  });
+
+  it("keeps the head of a snippet naming its language", async () => {
+    await mountSnippet({ code: "plain words", language: "text" });
+    expect(host.querySelector("[data-floating-copy]")).toBeNull();
+    expect(copyButton()).not.toBeNull();
+    expect(pre().className).not.toContain("pe-10");
+  });
+
+  it("breaks a word too long for the line with wrap anywhere", async () => {
+    await mountSnippet({ code: "x".repeat(400), wrap: "anywhere" });
+    expect(pre().className).toContain("[overflow-wrap:anywhere]");
+    expect(pre().className).toContain("whitespace-pre-wrap");
+  });
+
+  it("caps the height with a CSS length when no line count is set", async () => {
+    await mountSnippet({ code: "a", maxHeight: "20rem" });
+    expect(pre().style.maxHeight).toBe("20rem");
+    app?.unmount();
+    await mountSnippet({ code: "a\nb", maxHeight: "20rem", maxLines: 1 });
+    expect(pre().style.maxHeight).toBe("35px");
+  });
+
   it("wraps long lines or scrolls them, and caps the height in lines", async () => {
     await mountSnippet({ code: "a\nb\nc", wrap: true, maxLines: 2 });
     expect(pre().className).toContain("whitespace-pre-wrap");

package/frontend-vue/tests/field-suffix-count.test.ts

@@ -44,6 +44,7 @@ const load = async (name: string) =>
     .default as Component;
 
 beforeEach(() => {
+  vi.stubGlobal("useI18n", () => ({ locale: { value: "en" } }));
   vi.stubGlobal("useTranslation", () => ({
     processI18n: (text: string) => (text.startsWith("$") ? `t(${text})` : text),
   }));