@antelopejs/dms 0.7.11 → 0.7.13

package/frontend-vue/tests/module-routing.test.ts

@@ -0,0 +1,158 @@
+/**
+ * A module's own address (`/modules/<id>`) has no page: the navigation that
+ * enters it goes to the module's landing page instead — its `landingPage`
+ * when the caller may open it, else its first page — keeping the query and
+ * the hash it was entered with. The middleware answers the landing page
+ * rather than navigating to it, so the module's address never renders and,
+ * in a server render, becomes the response's redirect. A page the browser
+ * already draws at the module's address (a link that skipped the guard) loads
+ * the landing page instead of navigating from its own setup.
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { ref } from "vue";
+import { MODULE_URL_PREFIX } from "../layers/dms-layout/app/types/page";
+
+interface TreeNode {
+  id: string;
+  fullSlug: string;
+  layoutUrl?: string;
+  hasAccess?: boolean;
+  isModuleRoot?: boolean;
+  children: Record<string, TreeNode>;
+  childrenOrders: string[];
+}
+
+interface GuardedRoute {
+  path: string;
+  fullPath: string;
+}
+
+type Middleware = (to: GuardedRoute, from?: GuardedRoute) => Promise<unknown>;
+
+const navigateDms = vi.fn();
+
+function node(
+  id: string,
+  fullSlug: string,
+  children: TreeNode[] = [],
+  page: Partial<TreeNode> = {},
+): TreeNode {
+  return {
+    id,
+    fullSlug,
+    children: Object.fromEntries(children.map((child) => [child.id, child])),
+    childrenOrders: children.map((child) => child.id),
+    ...page,
+  };
+}
+
+const PAGE = { layoutUrl: "/layout" };
+
+function treeOf(moduleRoot: TreeNode): TreeNode {
+  return node("", "/", [node("modules", "/modules", [moduleRoot])]);
+}
+
+const apiModule = (pages: Partial<Record<string, Partial<TreeNode>>> = {}) =>
+  node(
+    "api",
+    "/modules/api",
+    [
+      node("monitor", "/modules/api", [
+        node("routes", "/modules/api/routes", [], { ...PAGE, ...pages.routes }),
+        node("overview", "/modules/api/overview", [], {
+          ...PAGE,
+          ...pages.overview,
+        }),
+      ]),
+    ],
+    { isModuleRoot: true },
+  );
+
+function stubSiteLayout(moduleRoot: TreeNode, landingPage?: string) {
+  vi.stubGlobal("useSiteLayout", () => ({
+    siteLayout: ref({}),
+    siteLayoutTree: ref(treeOf(moduleRoot)),
+    modules: ref({ api: { id: "api", hasAccess: true, landingPage } }),
+    findMatchingRoute: (path: string) =>
+      path.startsWith("/modules/api/") ? { metadata: {} } : null,
+    loadSiteLayout: vi.fn(),
+  }));
+}
+
+async function enter(
+  fullPath: string,
+  drawnThere = false,
+): Promise<unknown> {
+  const middleware = (
+    await import("../layers/dms-layout/app/middleware/module-routing.global")
+  ).default as unknown as Middleware;
+  const path = fullPath.replace(/[?#].*$/, "");
+  const to = { path, fullPath };
+  return middleware(to, drawnThere ? to : { path: "/home", fullPath: "/home" });
+}
+
+beforeEach(() => {
+  vi.resetModules();
+  vi.stubGlobal("defineDmsMiddleware", (handler: Middleware) => handler);
+  vi.stubGlobal("MODULE_URL_PREFIX", MODULE_URL_PREFIX);
+  vi.stubGlobal("navigateDms", navigateDms);
+  vi.stubGlobal("useHomepage", () => "/dashboard");
+  vi.stubGlobal("useModuleHistory", () => ({ record: vi.fn() }));
+  vi.stubGlobal("createError", (error: unknown) => error);
+});
+
+afterEach(() => {
+  navigateDms.mockReset();
+  vi.unstubAllGlobals();
+});
+
+describe("entering a module", () => {
+  it("goes to the module's landingPage", async () => {
+    stubSiteLayout(apiModule(), "overview");
+    expect(await enter("/modules/api")).toBe("/modules/api/overview");
+    expect(navigateDms).not.toHaveBeenCalled();
+  });
+
+  it("keeps the query and the hash it was entered with", async () => {
+    stubSiteLayout(apiModule(), "overview");
+    expect(await enter("/modules/api?live=0#errors")).toBe(
+      "/modules/api/overview?live=0#errors",
+    );
+  });
+
+  it("goes to the first page when there is no landingPage", async () => {
+    stubSiteLayout(apiModule());
+    expect(await enter("/modules/api")).toBe("/modules/api/routes");
+  });
+
+  it("goes to the first page the caller may open when the landingPage is closed to them", async () => {
+    stubSiteLayout(apiModule({ overview: { hasAccess: false } }), "overview");
+    expect(await enter("/modules/api")).toBe("/modules/api/routes");
+  });
+
+  it("sends to the homepage a caller who may open none of its pages", async () => {
+    stubSiteLayout(
+      apiModule({
+        routes: { hasAccess: false },
+        overview: { hasAccess: false },
+      }),
+      "overview",
+    );
+    await enter("/modules/api");
+    expect(navigateDms).toHaveBeenCalledWith("/dashboard", { replace: true });
+  });
+
+  it("loads the landing page when the browser already draws the module's address", async () => {
+    stubSiteLayout(apiModule(), "overview");
+    const replace = vi.fn();
+    vi.stubGlobal("window", { location: { replace } });
+    expect(await enter("/modules/api?live=0", true)).toBe(false);
+    expect(replace).toHaveBeenCalledWith("/modules/api/overview?live=0");
+  });
+
+  it("leaves a module page alone", async () => {
+    stubSiteLayout(apiModule(), "overview");
+    expect(await enter("/modules/api/routes?tab=tester")).toBeUndefined();
+    expect(navigateDms).not.toHaveBeenCalled();
+  });
+});

package/frontend-vue/tests/page-live-refresh.test.ts

@@ -0,0 +1,169 @@
+// @vitest-environment jsdom
+/**
+ * `usePageLiveRefresh`, the public face of the Direct / Pause gate: a module's
+ * own component refreshes on its topic at the page's `maxRate`, counts what
+ * it missed while paused and reads once on resume, reads at once on a user's
+ * refresh, and, with `idleRefresh`, reads again after a quiet period while
+ * the page is live only.
+ */
+import { createApp, defineComponent, h } from "vue";
+import { afterEach, beforeEach, expect, it, vi } from "vitest";
+import type { RealtimeTopicHandler } from "../layers/dms-core/app/composables/realtime/useUserRealtime";
+import { refreshPageBlocks } from "../layers/dms-ui/app/utils/blockRefresh";
+import {
+  createPageLiveController,
+  type PageLiveController,
+} from "../layers/dms-ui/app/build/composables/live/pageLiveController";
+import { setCurrentPageLive } from "../layers/dms-ui/app/build/composables/live/currentPageLive";
+import type {
+  PageLiveRefresh,
+  PageLiveRefreshOptions,
+} from "../layers/dms-ui/app/composables/live/usePageLiveRefresh";
+
+const topicHandlers = new Map<string, RealtimeTopicHandler[]>();
+
+vi.mock("../layers/dms-core/app/composables/realtime/useRealtimeTopic", () => ({
+  useRealtimeTopic: (topic: string, handler: RealtimeTopicHandler) => {
+    topicHandlers.set(topic, [...(topicHandlers.get(topic) ?? []), handler]);
+  },
+}));
+
+const { usePageLiveRefresh } = await import(
+  "../layers/dms-ui/app/composables/live/usePageLiveRefresh"
+);
+
+const TOPIC = "api:requests";
+const MAX_RATE_SECONDS = 15;
+const MAX_RATE_MS = MAX_RATE_SECONDS * 1000;
+const IDLE_SECONDS = 60;
+const mounted: Array<{ unmount: () => void }> = [];
+const controllers: PageLiveController[] = [];
+
+function publish() {
+  const event = { topic: TOPIC, type: "request", ts: Date.now() };
+  for (const handler of topicHandlers.get(TOPIC) ?? []) handler(event);
+}
+
+interface MountedRefresh {
+  onRefresh: ReturnType<typeof vi.fn>;
+  handle: PageLiveRefresh;
+}
+
+function mountComponent(
+  options: PageLiveRefreshOptions = { realtimeTopic: TOPIC },
+): MountedRefresh {
+  const onRefresh = vi.fn();
+  let handle: PageLiveRefresh | undefined;
+  const app = createApp(
+    defineComponent({
+      setup() {
+        handle = usePageLiveRefresh(onRefresh, options);
+        return () => h("div");
+      },
+    }),
+  );
+  app.mount(document.createElement("div"));
+  mounted.push(app);
+  return { onRefresh, handle: handle! };
+}
+
+function installLive(): PageLiveController {
+  const controller = createPageLiveController("api.routes", {
+    maxRate: MAX_RATE_SECONDS,
+  });
+  controllers.push(controller);
+  setCurrentPageLive(controller);
+  return controller;
+}
+
+beforeEach(() => {
+  vi.useFakeTimers();
+  topicHandlers.clear();
+  window.localStorage.clear();
+});
+
+afterEach(() => {
+  mounted.splice(0).forEach((app) => app.unmount());
+  controllers.splice(0).forEach((controller) => controller.dispose());
+  setCurrentPageLive(null);
+  vi.useRealTimers();
+});
+
+it("reads on its topic at the page's maxRate, the last event of a burst kept", () => {
+  installLive();
+  const { onRefresh } = mountComponent();
+
+  publish();
+  publish();
+  publish();
+  expect(onRefresh).toHaveBeenCalledTimes(1);
+
+  vi.advanceTimersByTime(MAX_RATE_MS);
+  expect(onRefresh).toHaveBeenCalledTimes(2);
+});
+
+it("reads nothing while paused, counts what it missed, and reads once on resume", () => {
+  const controller = installLive();
+  const { onRefresh, handle } = mountComponent();
+  controller.pause();
+
+  publish();
+  publish();
+  expect(onRefresh).not.toHaveBeenCalled();
+  expect(handle.missed.value).toBe(2);
+  expect(controller.missedCount.value).toBe(2);
+
+  controller.resume();
+  expect(onRefresh).toHaveBeenCalledTimes(1);
+  expect(handle.missed.value).toBe(0);
+});
+
+it("reads at once on a refresh the user asks for, paused or not", () => {
+  const controller = installLive();
+  const { onRefresh, handle } = mountComponent();
+  controller.pause();
+
+  refreshPageBlocks();
+  expect(onRefresh).toHaveBeenCalledTimes(1);
+
+  handle.refreshNow();
+  expect(onRefresh).toHaveBeenCalledTimes(2);
+});
+
+it("gates its own trigger like an event", () => {
+  const controller = installLive();
+  const { onRefresh, handle } = mountComponent({});
+  controller.pause();
+
+  handle.trigger();
+  expect(onRefresh).not.toHaveBeenCalled();
+  expect(handle.missed.value).toBe(1);
+});
+
+it("reads again after a quiet idleRefresh while live, never while paused", () => {
+  const controller = installLive();
+  const { onRefresh } = mountComponent({
+    realtimeTopic: TOPIC,
+    idleRefresh: IDLE_SECONDS,
+  });
+
+  vi.advanceTimersByTime(IDLE_SECONDS * 1000);
+  expect(onRefresh).toHaveBeenCalledTimes(1);
+
+  controller.pause();
+  vi.advanceTimersByTime(IDLE_SECONDS * 3000);
+  expect(onRefresh).toHaveBeenCalledTimes(1);
+  expect(controller.missedCount.value).toBe(0);
+
+  controller.resume();
+  vi.advanceTimersByTime(IDLE_SECONDS * 1000);
+  expect(onRefresh).toHaveBeenCalledTimes(2);
+});
+
+it("reads on every event on a page without live", () => {
+  const { onRefresh } = mountComponent();
+
+  publish();
+  publish();
+  expect(onRefresh).toHaveBeenCalledTimes(2);
+});

package/frontend-vue/tests/page-record-label.test.ts

@@ -0,0 +1,53 @@
+/**
+ * `usePageRecordLabel`, public: the label a record page's header ends its
+ * breadcrumb with, held with its page's path so it never outlives the page,
+ * and still reachable from its former `build/` path.
+ */
+import { reactive, ref, type Ref } from "vue";
+import { beforeEach, expect, it, vi } from "vitest";
+
+const route = reactive({ path: "/modules/api/routes" });
+let sharedState: Map<string, Ref<unknown>>;
+
+vi.stubGlobal("useDmsRoute", () => route);
+vi.stubGlobal("useDmsState", <T>(key: string, init?: () => T): Ref<T> => {
+  if (!sharedState.has(key)) sharedState.set(key, ref(init?.()));
+  return sharedState.get(key) as Ref<T>;
+});
+
+const { usePageRecordLabel } = await import(
+  "../layers/dms-core/app/composables/page/usePageRecordLabel"
+);
+const legacy = await import(
+  "../layers/dms-core/app/build/composables/page/usePageRecordLabel"
+);
+
+beforeEach(() => {
+  sharedState = new Map();
+  route.path = "/modules/api/routes";
+});
+
+it("reads the label set for the page on screen, shared between callers", () => {
+  const writer = usePageRecordLabel();
+  const reader = usePageRecordLabel();
+
+  writer.setLabel(route.path, "GET /api/invoices");
+
+  expect(reader.label.value).toBe("GET /api/invoices");
+});
+
+it("never shows a label on another page, and clears with no value", () => {
+  const { label, setLabel } = usePageRecordLabel();
+  setLabel(route.path, "GET /api/invoices");
+
+  route.path = "/modules/api/logs";
+  expect(label.value).toBeUndefined();
+
+  route.path = "/modules/api/routes";
+  setLabel(route.path, undefined);
+  expect(label.value).toBeUndefined();
+});
+
+it("stays importable from its former internal path", () => {
+  expect(legacy.usePageRecordLabel).toBe(usePageRecordLabel);
+});

package/frontend-vue/tests/regional-format.test.ts

@@ -1,7 +1,18 @@
-import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import {
+  afterEach,
+  beforeEach,
+  describe,
+  expect,
+  expectTypeOf,
+  it,
+  vi,
+} from "vitest";
 import { ref } from "vue";
 import { useRegionalFormat } from "../layers/dms-core/app/composables/user/useRegionalFormat";
-import { setRegionalPreferencesSource } from "../layers/dms-core/app/utils/regional";
+import {
+  regionalFormatLocale,
+  setRegionalPreferencesSource,
+} from "../layers/dms-core/app/utils/regional";
 
 // 23:30 UTC on 30 Sep: already 1 Oct in Brussels.
 const LATE_EVENING_UTC = new Date(Date.UTC(2026, 8, 30, 23, 30));
@@ -64,4 +75,60 @@ describe("useRegionalFormat", () => {
     const { formatRelativeTime } = useRegionalFormat();
     expect(formatRelativeTime(Date.now())).toBe("common.time.just_now:{}");
   });
+
+  it("types a formatted number as a string", () => {
+    const { formatNumber, formatPercentage, formatPrice } = useRegionalFormat();
+    const written: string[] = [
+      formatNumber(1234.5),
+      formatPercentage(0.25),
+      formatPrice(12),
+    ];
+    expect(written).toEqual([
+      new Intl.NumberFormat("fr-FR").format(1234.5),
+      new Intl.NumberFormat("fr-FR", { style: "percent" }).format(0.25),
+      new Intl.NumberFormat("fr-FR", {
+        style: "currency",
+        currency: "EUR",
+      }).format(12),
+    ]);
+    expectTypeOf(formatNumber(1)).toEqualTypeOf<string>();
+    expectTypeOf(formatNumber("n/a" as unknown)).toEqualTypeOf<unknown>();
+    expect(formatNumber("n/a")).toBe("n/a");
+  });
+
+  it("names the locale of the DMS texts for the interface language", () => {
+    locale.value = "en";
+    const { formatLocale } = useRegionalFormat();
+    expect(formatLocale.value).toBe("en-GB");
+    locale.value = "fr";
+    expect(formatLocale.value).toBe("fr-FR");
+  });
+
+  it("writes in the locale of the DMS texts when asked", () => {
+    locale.value = "en";
+    const interfaceFormat = useRegionalFormat();
+    const textFormat = useRegionalFormat({ locale: "format" });
+    const clock: Intl.DateTimeFormatOptions = {
+      hour: "numeric",
+      minute: "2-digit",
+    };
+    expect(interfaceFormat.dateTimeFormat(clock).format(LATE_EVENING_UTC)).toBe(
+      "1:30 AM",
+    );
+    expect(textFormat.dateTimeFormat(clock).format(LATE_EVENING_UTC)).toBe(
+      "1:30",
+    );
+    expect(textFormat.formatDate(LATE_EVENING_UTC, DAY_MONTH_YEAR)).toBe(
+      "1 October 2026",
+    );
+  });
+});
+
+describe("regionalFormatLocale", () => {
+  it("reads a bare DMS language as the region its texts are written for", () => {
+    expect(regionalFormatLocale("en")).toBe("en-GB");
+    expect(regionalFormatLocale("fr")).toBe("fr-FR");
+    expect(regionalFormatLocale("en-US")).toBe("en-US");
+    expect(regionalFormatLocale("de")).toBe("de");
+  });
 });

package/frontend-vue/tests/scroll-to-block.test.ts

@@ -0,0 +1,171 @@
+// @vitest-environment jsdom
+/**
+ * A page's block is brought into view by its anchor, the key path it is
+ * declared under (`summary`, `tabs.statistics`): `scrollToBlock` scrolls its
+ * first element and answers whether it found it. A block that is not on
+ * screen — never drawn, or unmounted since — answers false.
+ */
+import {
+  createApp,
+  defineComponent,
+  Fragment,
+  h,
+  nextTick,
+  ref,
+  type App,
+  type ComponentPublicInstance,
+} from "vue";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { registerBlockAnchor } from "../layers/dms-ui/app/build/composables/page/blockAnchors";
+import { scrollToBlock } from "../layers/dms-ui/app/utils/scrollToBlock";
+
+vi.mock("#dms-core/app/build/composables/auth/usePermissionPreview", () => ({
+  usePermissionPreview: () => ({
+    blockFor: () => undefined,
+    isActive: ref(false),
+    session: ref(null),
+  }),
+}));
+
+let app: App | undefined;
+let host: HTMLDivElement;
+const scrolled: Array<{ element: Element; options: unknown }> = [];
+
+const Section = defineComponent({
+  setup:
+    (_, { slots }) =>
+    () =>
+      h("section", { class: "section" }, slots.default?.()),
+});
+
+// A block rendering several roots: its anchor is its first element.
+const Pair = defineComponent({
+  setup: () => () =>
+    h(Fragment, [h("h3", { class: "pair-head" }), h("p", "body")]),
+});
+
+// A list beside the item it selects, like a split layout: one child in a
+// named slot, the other in the default one.
+const Split = defineComponent({
+  setup:
+    (_, { slots }) =>
+    () =>
+      h("div", { class: "split" }, [
+        h("aside", slots.aside?.()),
+        h("article", slots.default?.()),
+      ]),
+});
+
+const resolvedChild = (id: string, component: unknown, slot?: string) => ({
+  id,
+  component,
+  options: {},
+  children: [],
+  ...(slot ? { slot } : {}),
+});
+
+async function mountPage(showSecond = ref(true)) {
+  const { default: RecursiveComponent } = await import(
+    "../layers/dms-ui/app/components/RecursiveComponent.vue"
+  );
+  const block = (id: string, component: unknown, children: unknown[] = []) =>
+    h(RecursiveComponent, {
+      component: { ...resolvedChild(id, component), children },
+      pageId: "routes",
+      componentId: id,
+      layoutPath: id,
+    });
+  app = createApp({
+    render: () =>
+      h("main", [
+        block("summary", Pair),
+        showSecond.value
+          ? block("tabs", Section, [resolvedChild("statistics", Section)])
+          : null,
+        block("explorer", Split, [
+          resolvedChild("tree", Section, "aside"),
+          resolvedChild("header", Pair),
+        ]),
+      ]),
+  });
+  app.component("DmsRecursiveComponent", RecursiveComponent);
+  app.mount(host);
+  await nextTick();
+  return showSecond;
+}
+
+beforeEach(() => {
+  vi.stubGlobal("useI18n", () => ({ t: String }));
+  vi.stubGlobal("useTranslation", () => ({ processI18n: String }));
+  vi.stubGlobal("computed", (getter: () => unknown) => ({
+    get value() {
+      return getter();
+    },
+  }));
+  vi.stubGlobal("provide", () => {});
+  host = document.createElement("div");
+  document.body.append(host);
+  scrolled.length = 0;
+  Element.prototype.scrollIntoView = function (options?: unknown) {
+    scrolled.push({ element: this, options });
+  };
+});
+
+afterEach(() => {
+  app?.unmount();
+  host.remove();
+  vi.unstubAllGlobals();
+});
+
+describe("scrollToBlock", () => {
+  it("scrolls a top-level block and a nested one by their key path", async () => {
+    await mountPage();
+    expect(scrollToBlock("tabs.statistics")).toBe(true);
+    expect(scrolled.at(-1)?.element).toBe(
+      host.querySelectorAll("section.section")[1],
+    );
+    expect(scrolled.at(-1)?.options).toEqual({ block: "start" });
+    expect(scrollToBlock("summary", { behavior: "smooth" })).toBe(true);
+    expect(scrolled.at(-1)).toEqual({
+      element: host.querySelector(".pair-head"),
+      options: { behavior: "smooth" },
+    });
+  });
+
+  it("finds the children of a block that places them in its slots", async () => {
+    await mountPage();
+    expect(scrollToBlock("explorer.header")).toBe(true);
+    expect(scrolled.at(-1)?.element).toBe(
+      host.querySelector(".split article .pair-head"),
+    );
+    expect(scrollToBlock("explorer.tree")).toBe(true);
+    expect(scrolled.at(-1)?.element).toBe(
+      host.querySelector(".split aside section"),
+    );
+  });
+
+  it("answers false for a block that is not on screen", async () => {
+    const showSecond = await mountPage();
+    expect(scrollToBlock("missing")).toBe(false);
+    showSecond.value = false;
+    await nextTick();
+    expect(scrollToBlock("tabs")).toBe(false);
+    expect(scrollToBlock("tabs.statistics")).toBe(false);
+    expect(scrolled).toEqual([]);
+  });
+});
+
+describe("registerBlockAnchor", () => {
+  it("leaves an anchor to the block that took it over", () => {
+    const first = {} as ComponentPublicInstance;
+    const second = {
+      $: { subTree: { el: document.createElement("div") } },
+    } as unknown as ComponentPublicInstance;
+    registerBlockAnchor("chart", first);
+    registerBlockAnchor("chart", second);
+    registerBlockAnchor("chart", null, first);
+    expect(scrollToBlock("chart")).toBe(true);
+    registerBlockAnchor("chart", null, second);
+    expect(scrollToBlock("chart")).toBe(false);
+  });
+});

package/frontend-vue/tests/settings-search-shortcuts.test.ts

@@ -13,6 +13,7 @@ import {
   buildPageSearchShortcuts,
   pageSearchAriaKeyshortcuts,
 } from "../layers/dms-ui/app/build/composables/global/searchShortcuts";
+import * as publicSearchShortcuts from "../layers/dms-ui/app/composables/global/searchShortcuts";
 import registry from "../layers/dms-ui/app/config/shortcuts-registry";
 
 let app: App;
@@ -130,6 +131,22 @@ describe("settings search shortcut maps", () => {
     expect(nav.filter((key) => page.includes(key))).toEqual([]);
   });
 
+  it("are public where the UI toolkit docs import them", () => {
+    expect(publicSearchShortcuts.buildPageSearchShortcuts).toBe(
+      buildPageSearchShortcuts,
+    );
+    expect(publicSearchShortcuts.PAGE_SEARCH_SHORTCUTS).toBe(
+      PAGE_SEARCH_SHORTCUTS,
+    );
+    const docs = readFileSync(
+      resolve(__dirname, "../../docs/06.frontend-composables/05.ui-toolkit.md"),
+      "utf8",
+    );
+    expect(docs).toContain(
+      'from "#dms-ui/app/composables/global/searchShortcuts"',
+    );
+  });
+
   it("describe the page search keys per platform", () => {
     expect(pageSearchAriaKeyshortcuts(true)).toBe("Meta+/");
     expect(pageSearchAriaKeyshortcuts(false)).toBe("Control+/");