@antelopejs/dms 0.7.9 → 0.7.10

package/frontend-vue/tests/guard.test.ts

@@ -0,0 +1,242 @@
+/**
+ * A Guard reads a route and, when its condition holds (the value it names is
+ * empty, or the route answers 404), draws one EmptyState instead of its
+ * children; it keeps them while the route loads, after any other failure,
+ * and once the value is set.
+ */
+import { computed, createSSRApp, defineComponent, h, ref } from "vue";
+import { renderToString } from "vue/server-renderer";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import Guard from "../layers/dms-ui/app/components/guard/Guard.vue";
+import {
+  isEmptyValue,
+  readFieldPath,
+} from "../layers/dms-ui/app/build/composables/blocks/useGuard";
+
+const answer = ref<unknown>(null);
+const failure = ref<unknown>(null);
+const fetchOptions = vi.fn();
+
+vi.mock("../layers/dms-ui/app/composables/chart/useChartFetch", () => ({
+  useChartFetch: (options: unknown) => {
+    fetchOptions(options);
+    return { data: answer, isLoading: ref(false), error: failure };
+  },
+}));
+
+vi.mock("../layers/dms-core/app/composables/watch/useWatch", () => ({
+  useWatch: () => ({ state: ref({}) }),
+}));
+
+const Slot = defineComponent({
+  setup:
+    (_, { slots }) =>
+    () =>
+      h("div", slots.default?.()),
+});
+
+const Button = defineComponent({
+  props: { label: String, to: String },
+  setup: (props) => () =>
+    h("a", { "data-button": "", href: props.to }, props.label),
+});
+
+const GUARD = {
+  fetchUrl: "/api/routes/activity?route={{query.route}}",
+  periodScope: "api",
+  realtimeTopic: "requests",
+  field: "summary.calls",
+  fallback: {
+    title: "$api.routes.statistics.idle_title",
+    icon: "i-ph-moon-stars",
+    actions: [{ label: "Test this route", to: "/routes?tab=2" }],
+  },
+};
+
+async function render(props: Record<string, unknown>): Promise<string> {
+  const app = createSSRApp({
+    render: () =>
+      h(
+        Guard,
+        { componentId: "statistics", pageId: "routes", ...props },
+        { default: () => h("section", { "data-children": "" }, "children") },
+      ),
+  });
+  for (const name of ["UIcon", "DmsLink"]) app.component(name, Slot);
+  app.component("UButton", Button);
+  return renderToString(app);
+}
+
+beforeEach(() => {
+  answer.value = null;
+  failure.value = null;
+  fetchOptions.mockClear();
+  // Nuxt auto-imports, which the components use unimported.
+  vi.stubGlobal("ref", ref);
+  vi.stubGlobal("computed", computed);
+  vi.stubGlobal("useI18n", () => ({
+    locale: ref("en-US"),
+    t: (key: string) => `t(${key})`,
+  }));
+  vi.stubGlobal("useTranslation", () => ({
+    processI18n: (text: string) => (text.startsWith("$") ? `t(${text})` : text),
+  }));
+});
+
+afterEach(() => vi.unstubAllGlobals());
+
+describe("Guard", () => {
+  it("reads the route like a block's data source", async () => {
+    await render({ ...GUARD });
+    expect(fetchOptions).toHaveBeenCalledWith(
+      expect.objectContaining({
+        fetchUrl: GUARD.fetchUrl,
+        periodScope: "api",
+        realtimeTopic: "requests",
+      }),
+    );
+  });
+
+  it("keeps its children until the route answers", async () => {
+    const html = await render({ ...GUARD });
+    expect(html).toContain("data-children");
+    expect(html).not.toContain("idle_title");
+  });
+
+  it("keeps its children while the value is set", async () => {
+    answer.value = { summary: { calls: 12 } };
+    const html = await render({ ...GUARD });
+    expect(html).toContain("data-children");
+    expect(html).not.toContain("idle_title");
+  });
+
+  it("keeps its children after a failure", async () => {
+    answer.value = { summary: { calls: 0 } };
+    failure.value = { statusCode: 500 };
+    const html = await render({ ...GUARD });
+    expect(html).toContain("data-children");
+  });
+
+  it("swaps its children for the fallback when the value is empty", async () => {
+    answer.value = { summary: { calls: 0 } };
+    const html = await render({ ...GUARD });
+    expect(html).not.toContain("data-children");
+    expect(html).toContain("t($api.routes.statistics.idle_title)");
+    expect(html).toMatch(
+      /<a data-button href="\/routes\?tab=2"[^>]*>Test this route</,
+    );
+  });
+
+  it("checks the whole answer without a field", async () => {
+    answer.value = [];
+    const html = await render({ ...GUARD, field: undefined });
+    expect(html).not.toContain("data-children");
+  });
+
+  it("lays the answer's own emptyState over the fallback", async () => {
+    answer.value = {
+      summary: { calls: 0 },
+      emptyState: {
+        description: "Last called Oct 10",
+        actions: [{ label: "Test this route", to: "/routes?route=r1&tab=2" }],
+      },
+    };
+    const html = await render({ ...GUARD });
+    expect(html).toContain("t($api.routes.statistics.idle_title)");
+    expect(html).toContain("Last called Oct 10");
+    expect(html).toMatch(
+      /<a data-button href="\/routes\?route=r1&amp;tab=2"[^>]*>/,
+    );
+  });
+
+  it("falls back on a translated title without a fallback", async () => {
+    answer.value = { summary: { calls: 0 } };
+    const html = await render({ ...GUARD, fallback: undefined });
+    expect(html).toContain("t(dms.blocks.empty)");
+  });
+
+  describe("when notFound", () => {
+    const NOT_FOUND = {
+      fetchUrl: "/api/routes/{{params.id}}",
+      when: "notFound",
+    };
+
+    it("swaps its children for Not found when the route answers 404", async () => {
+      failure.value = { statusCode: 404 };
+      const html = await render(NOT_FOUND);
+      expect(html).not.toContain("data-children");
+      expect(html).toContain("t(dms.blocks.not_found)");
+      expect(html).toContain("t(dms.blocks.not_found_hint)");
+    });
+
+    it("describes it with the 404's message, as a block does", async () => {
+      failure.value = {
+        statusCode: 404,
+        data: { message: "No such route" },
+      };
+      const html = await render(NOT_FOUND);
+      expect(html).toContain("t(dms.blocks.not_found)");
+      expect(html).toContain("No such route");
+      expect(html).not.toContain("t(dms.blocks.not_found_hint)");
+    });
+
+    it("reads the 404 body ofetch keeps on the response", async () => {
+      failure.value = {
+        response: {
+          status: 404,
+          _data: { emptyState: { title: "Workspace gone" } },
+        },
+      };
+      expect(await render(NOT_FOUND)).toContain("Workspace gone");
+    });
+
+    it("lets the fallback replace the 404's message", async () => {
+      failure.value = { statusCode: 404, data: { message: "No such route" } };
+      const html = await render({
+        ...NOT_FOUND,
+        fallback: { description: "This route was removed." },
+      });
+      expect(html).toContain("This route was removed.");
+      expect(html).not.toContain("No such route");
+    });
+
+    it("lays the 404 body's emptyState over the fallback", async () => {
+      failure.value = {
+        statusCode: 404,
+        data: { emptyState: { description: "Deleted on Oct 10" } },
+      };
+      const html = await render({
+        ...NOT_FOUND,
+        fallback: { title: "Route gone" },
+      });
+      expect(html).toContain("Route gone");
+      expect(html).toContain("Deleted on Oct 10");
+    });
+
+    it("keeps its children on an answer or another failure", async () => {
+      answer.value = null;
+      expect(await render(NOT_FOUND)).toContain("data-children");
+      answer.value = { id: "r1" };
+      expect(await render(NOT_FOUND)).toContain("data-children");
+      failure.value = { statusCode: 500 };
+      expect(await render(NOT_FOUND)).toContain("data-children");
+    });
+  });
+});
+
+describe("Guard field", () => {
+  it("reads a dot path, stopping where it ends", () => {
+    expect(readFieldPath({ a: { b: 3 } }, "a.b")).toBe(3);
+    expect(readFieldPath({ a: null }, "a.b")).toBeUndefined();
+    expect(readFieldPath({ calls: 0 }, "calls")).toBe(0);
+  });
+
+  it("calls absent, null, false, 0, empty text and empty lists empty", () => {
+    for (const value of [undefined, null, false, 0, "", []]) {
+      expect(isEmptyValue(value)).toBe(true);
+    }
+    for (const value of [1, true, "x", [0], {}]) {
+      expect(isEmptyValue(value)).toBe(false);
+    }
+  });
+});

package/frontend-vue/tests/header-action-page-query.test.ts

@@ -0,0 +1,286 @@
+// @vitest-environment jsdom
+/**
+ * A page header's buttons follow the page URL: a target URL takes the
+ * `{{params.X}}` / `{{query.X}}` tokens of a block's `fetchUrl`, and a
+ * button whose availability reads the query is asked for again when the
+ * query changes.
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import {
+  computed,
+  createApp,
+  defineComponent,
+  h,
+  nextTick,
+  reactive,
+  ref,
+  type App,
+  type FunctionalComponent,
+} from "vue";
+import { resolveLinkVariables } from "../layers/dms-ui/app/build/utils/urlVariables";
+import {
+  isSamePageQuery,
+  layoutUrlWithQuery,
+  pageQueryValues,
+} from "../layers/dms-layout/app/utils/pageQuery";
+
+const handleCustomButton = vi.fn();
+vi.mock("#dms-ui/app/build/composables/actions/useActionTargets", () => ({
+  useActionTargets: () => ({ handleCustomButton }),
+}));
+vi.mock("#dms-core/app/build/composables/auth/usePermissionPreview", () => ({
+  usePermissionPreview: () => ({
+    isHeaderActionHidden: () => false,
+    session: ref(null),
+  }),
+}));
+
+const LAYOUT_URL = "/modules/lang/queue/pagelayout";
+const route = reactive<{ path: string; query: Record<string, unknown> }>({
+  path: "/modules/lang/queue/de",
+  query: {},
+});
+const authFetch = vi.fn();
+
+const ButtonStub = defineComponent({
+  props: { label: String, disabled: Boolean, onClick: Function, to: String },
+  setup: (props) => () =>
+    h(
+      "button",
+      {
+        disabled: props.disabled,
+        "data-to": props.to,
+        onClick: () => props.onClick?.(),
+      },
+      props.label,
+    ),
+});
+const SlotStub: FunctionalComponent = (_, { slots }) => slots.default?.();
+
+let app: App | undefined;
+let host: HTMLDivElement;
+
+beforeEach(() => {
+  route.query = { workspace: "web" };
+  handleCustomButton.mockClear();
+  authFetch.mockReset();
+  vi.stubGlobal("useAuthFetch", () => ({ $authFetch: authFetch }));
+  vi.stubGlobal("computed", computed);
+  vi.stubGlobal("useTranslation", () => ({
+    processI18n: (value: string) => value,
+  }));
+  vi.stubGlobal("useI18n", () => ({ t: (key: string) => key }));
+  vi.stubGlobal("useDmsRoute", () => route);
+  vi.stubGlobal("useDmsRouter", () => ({ replace: vi.fn() }));
+  vi.stubGlobal("useSiteLayout", () => ({
+    quickActions: ref(null),
+    findMatchingRoute: () => ({
+      metadata: { layoutUrl: LAYOUT_URL },
+      params: { locale: "de" },
+    }),
+  }));
+  host = document.createElement("div");
+  document.body.append(host);
+});
+
+afterEach(() => {
+  app?.unmount();
+  app = undefined;
+  host.remove();
+  vi.unstubAllGlobals();
+});
+
+async function mount(path: string, props: Record<string, unknown>) {
+  const { default: component } = await import(path);
+  app = createApp({ render: () => h(component, props) });
+  app.component("UButton", ButtonStub);
+  app.component("UTooltip", SlotStub);
+  app.mount(host);
+  await nextTick();
+}
+
+const mountBar = (actions: unknown[]) =>
+  mount(
+    "../layers/dms-layout/app/build/components/layout/PageHeaderActionBar.vue",
+    { actions },
+  );
+
+const buttons = () => [...host.querySelectorAll("button")];
+
+describe("resolveLinkVariables", () => {
+  const context = {
+    routeParams: { id: "ws 1" },
+    routeQuery: { workspace: "web", tab: "a&b" },
+  };
+
+  it("fills the page's params and query, encoded", () => {
+    expect(
+      resolveLinkVariables(
+        "/ws/{{params.id}}?workspace={{query.workspace}}&tab={{query.tab}}",
+        context,
+      ),
+    ).toBe("/ws/ws%201?workspace=web&tab=a%26b");
+  });
+
+  it("leaves out a query pair the page has no value for", () => {
+    expect(
+      resolveLinkVariables(
+        "/t?missing={{query.locale}}&workspace={{query.workspace}}#keys",
+        context,
+      ),
+    ).toBe("/t?workspace=web#keys");
+    expect(resolveLinkVariables("/t?locale={{query.locale}}", context)).toBe(
+      "/t",
+    );
+  });
+
+  it("fills a query key carrying dots", () => {
+    expect(
+      resolveLinkVariables("/logs?period={{query.api.period}}", {
+        routeQuery: { "api.period": "7d" },
+      }),
+    ).toBe("/logs?period=7d");
+  });
+
+  it("empties any other token left without a value", () => {
+    expect(resolveLinkVariables("/t/{{params.slug}}/edit", context)).toBe(
+      "/t//edit",
+    );
+  });
+});
+
+describe("page query helpers", () => {
+  it("reads one value per name, the last, as the server does", () => {
+    expect(
+      pageQueryValues({ workspace: "web", tag: ["a", "b"], empty: null }),
+    ).toEqual({ workspace: "web", tag: "b" });
+  });
+
+  it("compares queries in any order", () => {
+    expect(isSamePageQuery({ a: "1", b: "2" }, { b: "2", a: "1" })).toBe(true);
+    expect(isSamePageQuery({ a: "1" }, { a: "1", b: "2" })).toBe(false);
+  });
+
+  it("leaves out the keys that only record the view's state", () => {
+    const base = { workspace: "shop" };
+    expect(
+      isSamePageQuery(base, {
+        workspace: "shop",
+        record: "42",
+        live: "0",
+        "api.period": "24h",
+        "api.compare": "previous",
+        "api.from": "2026-10-01",
+      }),
+    ).toBe(true);
+    expect(isSamePageQuery(base, { workspace: "blog", record: "42" })).toBe(
+      false,
+    );
+  });
+
+  it("asks the layout URL for a query", () => {
+    expect(layoutUrlWithQuery("/p/pagelayout", { workspace: "a b" })).toBe(
+      "/p/pagelayout?workspace=a+b",
+    );
+    expect(layoutUrlWithQuery("/p/pagelayout", {})).toBe("/p/pagelayout");
+  });
+});
+
+describe("a header button's target URL", () => {
+  it("links to the page's scope, and follows it", async () => {
+    await mountBar([
+      {
+        id: "matrix",
+        label: "Open matrix",
+        target: {
+          type: "page",
+          url: "/modules/lang/translations?workspace={{query.workspace}}&missingIn={{params.locale}}",
+        },
+      },
+    ]);
+    expect(buttons()[0]?.dataset.to).toBe(
+      "/modules/lang/translations?workspace=web&missingIn=de",
+    );
+
+    route.query = { workspace: "docs" };
+    await nextTick();
+    expect(buttons()[0]?.dataset.to).toBe(
+      "/modules/lang/translations?workspace=docs&missingIn=de",
+    );
+
+    route.query = {};
+    await nextTick();
+    expect(buttons()[0]?.dataset.to).toBe(
+      "/modules/lang/translations?missingIn=de",
+    );
+  });
+
+  it("runs an API target on the page's record", async () => {
+    await mountBar([
+      {
+        id: "export",
+        label: "Export",
+        target: {
+          type: "api",
+          url: "/api/lang/export?workspace={{query.workspace}}",
+          successMessage: "Done",
+        },
+        confirm: { title: "Export?" },
+      },
+    ]);
+    buttons()[0]?.click();
+    expect(handleCustomButton).toHaveBeenCalledWith(
+      expect.objectContaining({
+        target: expect.objectContaining({
+          url: "/api/lang/export?workspace=web",
+        }),
+      }),
+    );
+  });
+});
+
+describe("a header button's availability", () => {
+  const download = (disabled: boolean) => ({
+    id: "download",
+    label: "Download",
+    target: { type: "page", url: "/download" },
+    disabled,
+  });
+
+  const mountOutlet = (servedQuery?: Record<string, string>) =>
+    mount(
+      "../layers/dms-layout/app/build/components/layout/PageHeaderActionsOutlet.vue",
+      { actions: [download(false)], servedQuery },
+    );
+
+  it("is not asked again while the query is the one it was served for", async () => {
+    await mountOutlet({ workspace: "web" });
+    expect(authFetch).not.toHaveBeenCalled();
+    expect(buttons()[0]?.disabled).toBe(false);
+  });
+
+  it("is asked again for the page's query when it changes", async () => {
+    authFetch.mockResolvedValue({
+      components: {},
+      layout: { options: { headerActions: [download(true)] } },
+    });
+    await mountOutlet({ workspace: "web" });
+
+    route.query = { workspace: "gone" };
+    await nextTick();
+    await new Promise((resolve) => setTimeout(resolve));
+    expect(authFetch).toHaveBeenCalledWith(`${LAYOUT_URL}?workspace=gone`);
+    expect(buttons()[0]?.disabled).toBe(true);
+
+    route.query = { workspace: "web" };
+    await nextTick();
+    expect(buttons()[0]?.disabled).toBe(false);
+  });
+
+  it("is never asked again when no button declares one", async () => {
+    await mountOutlet(undefined);
+    route.query = { workspace: "gone" };
+    await nextTick();
+    expect(authFetch).not.toHaveBeenCalled();
+  });
+});

package/frontend-vue/tests/live-toggle.test.ts

@@ -5,7 +5,10 @@
  * text field, and nothing at all on a page without `live`.
  */
 import { createApp, h, nextTick, type App } from "vue";
-import { afterEach, beforeEach, expect, it, vi } from "vitest";
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { usePageLive } from "../layers/dms-ui/app/composables/live/usePageLive";
 import { defineShortcuts } from "@nuxt/ui/runtime/composables/defineShortcuts.js";
 import {
   createPageLiveController,
@@ -33,6 +36,9 @@ async function createToggle(
       h(LiveToggleBlock, { componentId: "live", pageId: "api.logs", ...props }),
   });
   toggle.component("UIcon", () => h("i"));
+  toggle.component("UButton", (buttonProps: { label?: string }, { attrs }) =>
+    h("button", { ...attrs, type: "button" }, buttonProps.label),
+  );
   toggle.mount(target);
   await nextTick();
   return toggle;
@@ -160,3 +166,83 @@ it("switches once per L with two toggles on the page", async () => {
   expect(controller.isPaused.value).toBe(false);
   second.unmount();
 });
+
+describe("the pill variant and the paused state", () => {
+  const pill = (value: string) =>
+    host.querySelector<HTMLButtonElement>(`button[data-value="${value}"]`);
+  const resumeButton = () =>
+    host.querySelector<HTMLButtonElement>('[data-action="resume"]');
+
+  it("draws a Live pill with a pulsing dot beside Pause", async () => {
+    installLive();
+    await mountToggle({ variant: "pill" });
+    expect(pill("direct")?.getAttribute("aria-pressed")).toBe("true");
+    expect(pill("direct")?.textContent).toContain("dms.live.direct");
+    expect(host.querySelector(".dms-live-toggle__dot")?.className).toContain(
+      "animate-pulse",
+    );
+    expect(host.textContent).toContain("dms.live.updated_seconds:0");
+    expect(resumeButton()).toBeNull();
+
+    pill("pause")?.click();
+    await nextTick();
+    expect(live?.isPaused.value).toBe(true);
+    expect(resumeButton()).not.toBeNull();
+
+    resumeButton()?.click();
+    await nextTick();
+    expect(live?.isPaused.value).toBe(false);
+  });
+
+  it("says what was missed, with the module's label and breakdown", async () => {
+    const controller = installLive();
+    await mountToggle({
+      variant: "pill",
+      missedLabel: "$api.live.new_requests",
+    });
+    controller.pause();
+    const block = controller.subscribe(() => {});
+    block.trigger({ topic: "api", payload: { count: 40 } });
+    usePageLive().setMissedDetail({
+      text: "$api.live.in_5xx",
+      params: { count: 2 },
+      tone: "error",
+    });
+    await nextTick();
+
+    const status = host.querySelector(".dms-live-toggle__status");
+    expect(status?.textContent).toContain(
+      "dms.live.paused · api.live.new_requests:40",
+    );
+    expect(status?.querySelector(".text-error")?.textContent).toContain(
+      "api.live.in_5xx:2",
+    );
+  });
+
+  it("names the reason a component holds the page for", async () => {
+    installLive();
+    await mountToggle();
+    usePageLive().hold("$api.live.typing_in_tester");
+    await nextTick();
+    expect(host.textContent).toContain(
+      "dms.live.paused · api.live.typing_in_tester",
+    );
+    expect(host.textContent).not.toContain("dms.live.updated");
+  });
+
+  it("reads Live in en-GB, Direct in fr-FR", () => {
+    const locale = (name: string) =>
+      JSON.parse(
+        readFileSync(
+          resolve(__dirname, `../layers/dms-ui/i18n/locales/ui-${name}.json`),
+          "utf8",
+        ),
+      ).dms.live;
+    expect(locale("en-GB").direct).toBe("Live");
+    expect(locale("fr-FR").direct).toBe("Direct");
+    for (const key of ["paused", "resume", "reason_hidden", "polling"]) {
+      expect(locale("en-GB")[key]).toBeTruthy();
+      expect(locale("fr-FR")[key]).toBeTruthy();
+    }
+  });
+});

package/frontend-vue/tests/page-layout-registration.test.ts

@@ -38,6 +38,7 @@ it("loads a page registered after setup without changing the route", async () =>
   await nextTick();
   expect(loadPageLayout).toHaveBeenCalledExactlyOnceWith(
     "/new-page/pagelayout",
+    {},
   );
   expect(pageLayout.value).toBe("/new-page/pagelayout");
   expect(route.path).toBe("/new-page");