@antelopejs/dms 0.7.10 → 0.7.12

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,142 @@
+// @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")]),
+});
+
+const resolvedChild = (id: string, component: unknown) => ({
+  id,
+  component,
+  options: {},
+  children: [],
+});
+
+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,
+      ]),
+  });
+  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("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+/");

package/frontend-vue/tests/tab-slot-spacing.test.ts

@@ -19,3 +19,11 @@ it("spaces the blocks of a tab the way the page spaces its own", () => {
     ),
   );
 });
+
+// A guard holding two blocks drew them edge to edge: the page spaces its own
+// wrapper, not the blocks inside it.
+it("spaces the blocks of a guard the way the page spaces its own", () => {
+  expect(sourceOf("dms-ui/app/components/guard/Guard.vue")).toMatch(
+    new RegExp(`<div class="[^"]*\\b${BLOCK_SPACING}\\b[^"]*" data-dms-guard>`),
+  );
+});

package/frontend-vue/tests/tab-url-slot.test.ts

@@ -0,0 +1,150 @@
+// @vitest-environment jsdom
+/**
+ * A tab set keeping its open tab in the URL writes the tab's slot
+ * (`?tab=tester`), which stays right when tabs are added or reordered, and
+ * still opens a tab named by its index (`?tab=2`). A tab's badge is a
+ * BlockText: an i18n key is written in the reader's language.
+ */
+import * as vue from "vue";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { useTab } from "../layers/dms-ui/app/composables/tab/useTab";
+import { TabEvents } from "../layers/dms-ui/app/composables/tab/types/events";
+import type { TabProps } from "../layers/dms-ui/app/composables/tab/types";
+import { AxeOrientation } from "../layers/dms-core/app/types/orientation";
+import { Color } from "../layers/dms-core/app/types/color";
+import { Size } from "../layers/dms-core/app/types/size";
+
+vi.mock("../layers/dms-ui/app/composables/chart/useChartFetch", () => ({
+  useChartFetch: () => ({ data: vue.ref(null) }),
+}));
+
+const ITEMS = [
+  { label: "Statistics", slot: "statistics" },
+  { label: "Documentation", slot: "documentation" },
+  { label: "Tester", slot: "tester" },
+];
+
+let route: { query: Record<string, string> };
+const push = vi.fn(async (to: { query: Record<string, string> }) => {
+  route.query = to.query;
+});
+
+function tabsAt(query: Record<string, string>) {
+  route.query = query;
+  return useTab(ITEMS.length, {
+    items: ITEMS,
+    persistState: true,
+  } as TabProps);
+}
+
+beforeEach(() => {
+  route = vue.reactive({ query: {} });
+  push.mockClear();
+  for (const name of ["computed", "ref", "watch", "useTemplateRef"] as const)
+    vi.stubGlobal(name, vue[name]);
+  vi.stubGlobal("TabEvents", TabEvents);
+  vi.stubGlobal("isNumber", (value: unknown) => typeof value === "number");
+  vi.stubGlobal("isString", (value: unknown) => typeof value === "string");
+  vi.stubGlobal("useComponentEvent", () => ({ sendComponentEvent: vi.fn() }));
+  vi.stubGlobal("useWatch", () => ({
+    isLoading: vue.ref(false),
+    state: vue.ref({}),
+  }));
+  vi.stubGlobal("useDmsRoute", () => route);
+  vi.stubGlobal("useDmsRouter", () => ({ push }));
+});
+
+afterEach(() => vi.unstubAllGlobals());
+
+describe("a tab in the URL", () => {
+  it("opens the tab its slot names", () => {
+    expect(tabsAt({ tab: "tester" }).activeTab.value).toBe("2");
+  });
+
+  it("still opens a tab named by its index", () => {
+    expect(tabsAt({ tab: "1" }).activeTab.value).toBe("1");
+  });
+
+  it("opens the first tab on a name it does not know", () => {
+    expect(tabsAt({ tab: "settings" }).activeTab.value).toBe("0");
+    expect(tabsAt({ tab: "7" }).activeTab.value).toBe("0");
+  });
+
+  it("writes the open tab's slot, and nothing for the first", async () => {
+    const { goToTab } = tabsAt({});
+    goToTab(2);
+    await vue.nextTick();
+    expect(push).toHaveBeenLastCalledWith({ query: { tab: "tester" } });
+    goToTab("statistics");
+    await vue.nextTick();
+    expect(push).toHaveBeenLastCalledWith({ query: {} });
+  });
+
+  it("follows a URL naming another slot", async () => {
+    const { activeTab } = tabsAt({});
+    route.query = { tab: "documentation" };
+    await vue.nextTick();
+    expect(activeTab.value).toBe("1");
+  });
+});
+
+describe("a tab's badge", () => {
+  interface TabsItem {
+    badge?: unknown;
+  }
+  let received: TabsItem[] = [];
+  let app: vue.App | undefined;
+
+  const Tabs = vue.defineComponent({
+    props: { items: { type: Array, default: () => [] } },
+    setup: (props) => () => {
+      received = props.items as TabsItem[];
+      return vue.h("div");
+    },
+  });
+
+  async function badgesOf(badges: unknown[]): Promise<unknown[]> {
+    vi.stubGlobal("AxeOrientation", AxeOrientation);
+    vi.stubGlobal("Color", Color);
+    vi.stubGlobal("Size", Size);
+    vi.stubGlobal("useI18n", () => ({
+      locale: vue.ref("en"),
+      t: (key: string) => `t(${key})`,
+    }));
+    vi.stubGlobal("useTranslation", () => ({ processI18n: String }));
+    vi.stubGlobal("useTab", () => ({ activeTab: vue.ref("0") }));
+    vi.stubGlobal("useTabShortcuts", () => {});
+    const { default: Tab } = await import(
+      "../layers/dms-ui/app/components/tab/Tab.vue"
+    );
+    app = vue.createApp({
+      render: () =>
+        vue.h(Tab, {
+          items: badges.map((badge, index) => ({ ...ITEMS[index], badge })),
+        }),
+    });
+    app.component("UTabs", Tabs);
+    app.mount(document.createElement("div"));
+    await vue.nextTick();
+    app.unmount();
+    return received.map((item) => item.badge);
+  }
+
+  it("writes an i18n key, a composed text and a badge label in the reader's language", async () => {
+    expect(
+      await badgesOf([
+        "$api.tabs.beta",
+        { key: "api.tabs.count" },
+        { label: "$api.tabs.new", color: "primary" },
+      ]),
+    ).toEqual([
+      "t(api.tabs.beta)",
+      "t(api.tabs.count)",
+      { label: "t(api.tabs.new)", color: "primary" },
+    ]);
+  });
+
+  it("keeps a count and a plain text as they are", async () => {
+    expect(await badgesOf([3, "Beta"])).toEqual([3, "Beta"]);
+  });
+});