@antelopejs/dms 0.7.11 → 0.7.13

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

@@ -3,6 +3,7 @@ import type {
   ChartAnnotation,
   ChartAutoYRange,
   ChartCurve,
+  ChartLegendPosition,
   ChartSeries,
   ChartType,
   ChartXAxis,
@@ -35,6 +36,7 @@ export interface UseApexChartInput {
   showGrid?: boolean;
   showTooltip?: boolean;
   showLegend?: boolean;
+  legendPosition?: ChartLegendPosition;
   smooth?: boolean;
   curve?: ChartCurve;
   stacked?: boolean;

package/frontend-vue/layers/dms-ui/app/composables/form/types/validation.ts

@@ -1,7 +1,17 @@
 import type { InjectionKey } from "vue";
 
+/**
+ * A check a `Form` runs before each submit: `false` stops the submit before
+ * anything is sent. See `useEnclosingForm().addValidator`.
+ */
 export type FormValidator = () => boolean;
+
+/** Adds a {@link FormValidator} to a `Form`; returns its removal. */
 export type RegisterValidator = (validator: FormValidator) => () => void;
 
+/**
+ * What a `Form` provides to register a validator. Kept for the fields that
+ * inject it; a module's field calls `useEnclosingForm().addValidator`.
+ */
 export const FORM_VALIDATOR_KEY: InjectionKey<RegisterValidator> =
   Symbol("form-validator");

package/frontend-vue/layers/dms-ui/app/composables/form/useEnclosingForm.ts

@@ -0,0 +1,61 @@
+import { getCurrentScope, inject, onScopeDispose } from "vue";
+import { FORM_HANDLE_KEY } from "../../build/composables/form/enclosingForm";
+import type { FormValidator } from "./types/validation";
+
+/** The DMS `Form` a custom field is drawn in (see {@link useEnclosingForm}). */
+export interface EnclosingForm {
+  /**
+   * Submits the form as its save button does: the form validates its fields,
+   * runs the validators, then sends what changed. Resolves once the submit
+   * was handled; a refused one shows its errors as usual.
+   */
+  submit: () => Promise<void>;
+  /**
+   * Runs `validator` before each submit: answering `false` stops it, before
+   * anything is sent (and before the other validators). Removed when the
+   * calling component goes, or by calling the returned function.
+   */
+  addValidator: (validator: FormValidator) => () => void;
+  /**
+   * Brings a field of the form into view, by its id, and focuses its control:
+   * its first focusable part when the control is a group.
+   */
+  focusField: (fieldId: string) => Promise<void>;
+}
+
+/**
+ * The DMS `Form` the calling component is drawn in: what a custom field (an
+ * `inputComponent` of the module's own) needs of it without reading the DOM.
+ * `null` outside a `Form`.
+ *
+ * ```ts
+ * const form = useEnclosingForm();
+ * const { confirm } = useConfirm();
+ * // Ask before a save that deletes data; submit again once confirmed.
+ * form?.addValidator(() => {
+ *   if (!isLowered.value || isConfirmed) return true;
+ *   void confirm({ title: "Delete older logs?" }).then((accepted) => {
+ *     isConfirmed = accepted;
+ *     if (accepted) void form.submit();
+ *   });
+ *   return false;
+ * });
+ * ```
+ *
+ * A page opened on the anchor of a field (`/settings#retentionDays`, the
+ * field's id) scrolls to it and focuses it once the form is drawn, without
+ * any of this: `focusField` is for a link or a button inside the page.
+ */
+export function useEnclosingForm(): EnclosingForm | null {
+  const handle = inject(FORM_HANDLE_KEY, null);
+  if (!handle) return null;
+  return {
+    submit: handle.submit,
+    addValidator: (validator) => {
+      const remove = handle.registerValidator(validator);
+      if (getCurrentScope()) onScopeDispose(remove);
+      return remove;
+    },
+    focusField: handle.revealField,
+  };
+}

package/frontend-vue/layers/dms-ui/app/composables/global/searchShortcuts.ts

@@ -0,0 +1,24 @@
+/**
+ * Focuses a page's own search (⌘ / on macOS, Ctrl / elsewhere), so it never
+ * competes with "/" for the navigation search. `meta` is read as Ctrl off
+ * macOS by `defineShortcuts`. The shifted variant is the same physical keys
+ * on layouts where "/" needs Shift (AZERTY: Shift + :), which
+ * `defineShortcuts` would otherwise reject as an extra modifier.
+ */
+export const PAGE_SEARCH_SHORTCUTS = ["meta_/", "meta_shift_/"] as const;
+
+/**
+ * `defineShortcuts` map focusing a page's own search on ⌘ / or Ctrl /: the
+ * keys a custom page binds its search to, "/" being the navigation
+ * search's.
+ *
+ * @example
+ * ```ts
+ * defineShortcuts(buildPageSearchShortcuts(() => input.value?.focus()));
+ * ```
+ */
+export function buildPageSearchShortcuts(
+  focus: () => void,
+): Record<string, () => void> {
+  return Object.fromEntries(PAGE_SEARCH_SHORTCUTS.map((key) => [key, focus]));
+}

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

@@ -75,8 +75,9 @@ export interface PageLiveState {
  * const { isPaused, missedCount, resume, hold, release } = usePageLive();
  * ```
  *
- * A component that refetches on its own realtime topic need not use it:
- * built-in blocks with a `realtimeTopic` already follow the state.
+ * A component that refetches on its own realtime topic need not read it:
+ * `usePageLiveRefresh` gates its refresh as the built-in blocks with a
+ * `realtimeTopic` are.
  */
 export function usePageLive(): PageLiveState {
   const isPaused = computed(() => currentPageLive()?.isPaused.value ?? false);

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/block-fetch-options-forwarding.test.ts

@@ -49,6 +49,8 @@ const BLOCKS: Record<string, string> = {
   ActivityFeed:
     "../layers/dms-ui/app/components/activity-feed/ActivityFeed.vue",
   MeterBlock: "../layers/dms-ui/app/components/meter/MeterBlock.vue",
+  ChartCard: "../layers/dms-ui/app/components/chart/ChartCard.vue",
+  TopListCard: "../layers/dms-ui/app/components/top-list/TopListCard.vue",
 };
 const GLOBAL_COMPONENTS = ["DmsCard", "UIcon", "USkeleton", "UButton", "ULink"];
 const SCOPE = "dashboard";
@@ -81,6 +83,9 @@ beforeEach(() => {
   vi.stubGlobal("useI18n", () => ({ locale: ref("en-GB"), t: String }));
   vi.stubGlobal("useTranslation", () => ({ processI18n: String }));
   vi.stubGlobal("useDmsCookie", () => ref<string[]>([]));
+  // The cards reach these through auto-imports rather than imports.
+  vi.stubGlobal("useComponentEvent", () => ({}));
+  vi.stubGlobal("useWatch", () => ({ state: ref({}) }));
 });
 
 afterEach(() => vi.unstubAllGlobals());

package/frontend-vue/tests/breadcrumb-target.test.ts

@@ -18,6 +18,16 @@ describe("buildBreadcrumbTarget", () => {
     expect(buildBreadcrumbTarget("/projects", {}, {})).to.equal(undefined);
   });
 
+  it("links a module's root to the module's landing page", () => {
+    expect(
+      buildBreadcrumbTarget(
+        "/modules/api",
+        { landingSlug: "/modules/api/overview" },
+        {},
+      ),
+    ).to.equal("/modules/api/overview");
+  });
+
   it("carries only the query values an ancestor page requires", () => {
     expect(
       buildBreadcrumbTarget("/projects/project", PROJECT_PAGE, {