@antelopejs/dms 0.8.3 → 0.9.1

package/frontend-vue/tests/onboarding-transfer.test.ts

@@ -0,0 +1,106 @@
+// @vitest-environment jsdom
+/**
+ * The onboarding status the global middleware reads while a server renders a
+ * page reaches the browser with the page, through the runtime's real state
+ * transfer: the browser's run of the middleware asks nothing.
+ */
+import { createApp, createSSRApp, defineComponent, h, nextTick } from "vue";
+import { renderToString } from "vue/server-renderer";
+import { afterEach, beforeEach, expect, it, vi } from "vitest";
+import type { App } from "vue";
+import type { DmsFrontendRuntime } from "#dms/frontend-module";
+
+const engine = await import("#dms/frontend-module");
+vi.stubGlobal("useDmsState", engine.useDmsState);
+vi.stubGlobal("defineDmsMiddleware", engine.defineDmsMiddleware);
+vi.stubGlobal("navigateDms", engine.navigateDms);
+vi.stubGlobal("useDmsUserSession", () => ({ loggedIn: { value: true } }));
+vi.stubGlobal("useHomepage", () => "/dashboard");
+
+const $authFetch = vi.fn(async () => ({ has_onboarded: true }));
+vi.stubGlobal("useAuthFetch", () => ({ $authFetch }));
+// The status is read once per app however many callers ask (the preload
+// started with the app, the middleware).
+// No DMS app runs here: each runtime holds the deduper on a state of its own.
+vi.stubGlobal(
+  "useDmsApp",
+  () => engine.useDmsState("onboarding-test-app", () => ({})).value,
+);
+const { createTrailingDeduper } = await import(
+  "../layers/dms-core/app/utils/trailingDeduper"
+);
+vi.stubGlobal("createTrailingDeduper", createTrailingDeduper);
+const { useTrailingDeduper } = await import(
+  "../layers/dms-core/app/composables/useTrailingDeduper"
+);
+vi.stubGlobal("useTrailingDeduper", useTrailingDeduper);
+
+const { useOnboarding } = await import(
+  "../layers/dms-onboarding/app/composables/onboarding/useOnboarding"
+);
+vi.stubGlobal("useOnboarding", useOnboarding);
+const { default: onboardingMiddleware } = await import(
+  "../layers/dms-onboarding/app/middleware/onboarding.global"
+);
+
+const Page = defineComponent({
+  setup() {
+    engine.defineDmsPageMeta({});
+    const info = engine.useDmsState<{ hasOnboarded: boolean } | null>(
+      "dms-onboarding-info",
+    );
+    return () => h("p", info.value?.hasOnboarded ? "onboarded" : "unknown");
+  },
+});
+
+const mounted: App[] = [];
+
+function attach(app: App, runtime: DmsFrontendRuntime): void {
+  runtime.route.path = "/dashboard";
+  runtime.route.fullPath = "/dashboard";
+  engine.provideDmsFrontendRuntime(app, runtime);
+}
+
+beforeEach(async () => {
+  $authFetch.mockClear();
+  await engine.setupFrontendModules([
+    {
+      options: { public: {} },
+      module: {
+        setup(sdk) {
+          sdk.registerMiddleware("onboarding", onboardingMiddleware, {
+            global: true,
+          });
+        },
+      },
+    },
+  ]);
+});
+
+afterEach(() => {
+  mounted.splice(0).forEach((app) => app.unmount());
+});
+
+it("hands the onboarding status the server read to the browser", async () => {
+  const server = engine.createDmsFrontendRuntime(undefined, {}, true);
+  const serverApp = createSSRApp(Page);
+  attach(serverApp, server);
+  expect(await renderToString(serverApp)).toBe("<p>onboarded</p>");
+  expect($authFetch).toHaveBeenCalledTimes(1);
+  const payload = structuredClone(engine.serializeDmsPayload(server));
+  expect(payload.state["dms-onboarding-info"]).toEqual({ hasOnboarded: true });
+
+  $authFetch.mockClear();
+  const browser = engine.createDmsFrontendRuntime(undefined, {});
+  engine.restoreDmsPayload(browser, payload);
+  const browserApp = createApp(Page);
+  attach(browserApp, browser);
+  const host = document.createElement("div");
+  browserApp.mount(host);
+  mounted.push(browserApp);
+  await nextTick();
+  await new Promise((done) => setTimeout(done, 0));
+
+  expect($authFetch).not.toHaveBeenCalled();
+  expect(host.textContent).toBe("onboarded");
+});

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

@@ -0,0 +1,141 @@
+// @vitest-environment jsdom
+/**
+ * A page's `useApiData` reads follow the page: `refreshPageBlocks()` (an
+ * action of the user) and an event on one of the page's realtime topics read
+ * them again through `refreshDmsPageData()`, without a `refresh()` of their
+ * own. A read that refreshes on its own triggers opts out.
+ */
+import { type App, createApp, defineComponent, h, nextTick, ref } from "vue";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import type { RealtimeTopicHandler } from "../layers/dms-core/app/composables/realtime/useUserRealtime";
+import { useRealDataEngine } from "./fixtures/dataEngine";
+import { refreshPageBlocks } from "../layers/dms-ui/app/utils/blockRefresh";
+
+const requests: string[] = [];
+// Holds the answers back while set.
+let held: Promise<void> | undefined;
+vi.stubGlobal("useAuthFetch", () => ({
+  $authFetch: async (url: string) => {
+    requests.push(url);
+    await held;
+    return { url };
+  },
+}));
+
+const { useApiData } = await import(
+  "../layers/dms-core/app/composables/auth/useApiData"
+);
+const { usePageDataRefresh } = await import(
+  "../layers/dms-ui/app/build/composables/live/usePageDataRefresh"
+);
+
+// Past the one-frame window a burst of refreshes collapses into.
+const settle = () => new Promise((resolve) => setTimeout(resolve, 40));
+
+const pageTopics = ref<string[]>([]);
+const handlers = new Map<string, Set<RealtimeTopicHandler>>();
+function subscribe(topic: string, handler: RealtimeTopicHandler) {
+  if (!handlers.has(topic)) handlers.set(topic, new Set());
+  handlers.get(topic)!.add(handler);
+  return () => handlers.get(topic)?.delete(handler);
+}
+function publish(topic: string, event: object): void {
+  for (const handler of handlers.get(topic) ?? [])
+    handler(event as Parameters<RealtimeTopicHandler>[0]);
+}
+
+const mounted: App[] = [];
+
+async function mountPage(): Promise<void> {
+  const Page = defineComponent({
+    setup() {
+      usePageDataRefresh({ pageTopics, subscribe });
+      useApiData("/api/orders");
+      useApiData("/api/own-triggers", { refreshOnPageRefresh: false });
+      return () => h("div");
+    },
+  });
+  const app = createApp(Page);
+  app.mount(document.createElement("div"));
+  mounted.push(app);
+  await settle();
+}
+
+beforeEach(() => {
+  useRealDataEngine();
+  requests.length = 0;
+  pageTopics.value = [];
+  handlers.clear();
+});
+
+afterEach(() => {
+  mounted.splice(0).forEach((app) => app.unmount());
+});
+
+describe("the page's data refresh", () => {
+  it("reads the page's data again on refreshPageBlocks()", async () => {
+    await mountPage();
+    expect(requests.sort()).toEqual(["/api/orders", "/api/own-triggers"]);
+    requests.length = 0;
+
+    refreshPageBlocks();
+    await settle();
+
+    expect(requests).toEqual(["/api/orders"]);
+  });
+
+  it("resolves refreshPageBlocks() once the page's data is read again", async () => {
+    await mountPage();
+    requests.length = 0;
+    let release!: () => void;
+    held = new Promise<void>((resolve) => (release = resolve));
+    let done = false;
+    const refreshed = refreshPageBlocks().then(() => (done = true));
+    await settle();
+    expect(requests).toEqual(["/api/orders"]);
+    expect(done).toBe(false);
+
+    release();
+    held = undefined;
+    await refreshed;
+    expect(done).toBe(true);
+  });
+
+  it("joins the refreshes of one burst", async () => {
+    await mountPage();
+    requests.length = 0;
+    await Promise.all([refreshPageBlocks(), refreshPageBlocks()]);
+    expect(requests).toEqual(["/api/orders"]);
+  });
+
+  it("reads it again on an event of one of the page's topics", async () => {
+    await mountPage();
+    pageTopics.value = ["table:orders"];
+    await nextTick();
+    requests.length = 0;
+
+    publish("table:orders", { topic: "table:orders", type: "updated" });
+    publish("table:orders", { topic: "table:orders", type: "updated" });
+    await settle();
+    expect(requests).toEqual(["/api/orders"]);
+
+    // A presence snapshot rides the topic too, and changes no data.
+    requests.length = 0;
+    publish("table:orders", { topic: "table:orders", entries: [] });
+    await settle();
+    expect(requests).toEqual([]);
+  });
+
+  it("stops following the topics the page no longer has", async () => {
+    await mountPage();
+    pageTopics.value = ["table:orders"];
+    await nextTick();
+    pageTopics.value = ["table:invoices"];
+    await nextTick();
+    requests.length = 0;
+
+    publish("table:orders", { topic: "table:orders", type: "updated" });
+    await settle();
+    expect(requests).toEqual([]);
+  });
+});

package/frontend-vue/tests/page-fill-height.test.ts

@@ -28,6 +28,16 @@ import {
   usePageFillHeight,
 } from "../layers/dms-layout/app/composables/layout/usePageFillHeight";
 
+// The page's data refresh and the visit's navigation badges read the
+// realtime session and Inertia's page, which these tests do not run.
+vi.mock(
+  "../layers/dms-ui/app/build/composables/live/usePageDataRefresh",
+  () => ({ usePageDataRefresh: () => {} }),
+);
+vi.mock(
+  "../layers/dms-layout/app/build/composables/navigation/useVisitNavBadges",
+  () => ({ useVisitNavBadges: () => {} }),
+);
 vi.mock(
   "../layers/dms-layout/app/build/components/layout/DashboardSidebar.vue",
   () => ({ default: () => null }),
@@ -151,7 +161,7 @@ function installRuntime(): void {
     PAGE_FILL_HEIGHT_CLASSES,
     providePageFillHeight,
     usePageFillHeight,
-    createError: vi.fn(),
+    createDmsError: vi.fn(),
     defineDmsPageMeta: vi.fn(),
     firstAccessiblePagePath: vi.fn(),
     navigateDms: vi.fn(),
@@ -159,7 +169,7 @@ function installRuntime(): void {
     providePageRealtime: vi.fn(),
     resolveDmsComponent: () => "div",
     runCustomValidation: vi.fn(),
-    showError: vi.fn(),
+    showDmsError: vi.fn(),
     validateRequiredQueryParams: vi.fn(),
     useDefinedFunctions: () => ({ getFunction: () => undefined }),
     useDmsCookie: <T>(_name: string, options: { default?: () => T } = {}) =>
@@ -179,6 +189,9 @@ function installRuntime(): void {
       reconcileSession: async () => {},
       redirectToAuth: async () => {},
     }),
+    // The page brought its site layout.
+    useRenderedSiteLayout: () => {},
+    useRenderedBellCounts: () => {},
     useSiteLayout: () => ({
       siteLayout: ref({ pages: {} }),
       siteLayoutTree: ref([]),
@@ -197,7 +210,7 @@ function installRuntime(): void {
     }),
     useI18n: () => ({ t: (key: string) => key }),
     useTranslation: () => ({ processI18n: (value: string) => value }),
-    useUserSession: () => ({ loggedIn: ref(true) }),
+    useDmsUserSession: () => ({ loggedIn: ref(true) }),
   };
   Object.entries(runtime).forEach(([name, value]) =>
     vi.stubGlobal(name, value),

package/frontend-vue/tests/page-no-visible-blocks.test.ts

@@ -21,6 +21,16 @@ import {
   usePageFillHeight,
 } from "../layers/dms-layout/app/composables/layout/usePageFillHeight";
 
+// The page's data refresh and the visit's navigation badges read the
+// realtime session and Inertia's page, which these tests do not run.
+vi.mock(
+  "../layers/dms-ui/app/build/composables/live/usePageDataRefresh",
+  () => ({ usePageDataRefresh: () => {} }),
+);
+vi.mock(
+  "../layers/dms-layout/app/build/composables/navigation/useVisitNavBadges",
+  () => ({ useVisitNavBadges: () => {} }),
+);
 vi.mock(
   "../layers/dms-layout/app/build/composables/dev-reload/useDevReloadHolder",
   async () => {
@@ -73,7 +83,7 @@ function installRuntime(): void {
     PAGE_FILL_HEIGHT_CLASSES,
     providePageFillHeight,
     usePageFillHeight,
-    createError: vi.fn(),
+    createDmsError: vi.fn(),
     defineDmsPageMeta: vi.fn(),
     firstAccessiblePagePath: vi.fn(),
     navigateDms,
@@ -81,7 +91,7 @@ function installRuntime(): void {
     providePageRealtime: vi.fn(),
     resolveDmsComponent: () => "div",
     runCustomValidation: vi.fn(),
-    showError: vi.fn(),
+    showDmsError: vi.fn(),
     validateRequiredQueryParams: vi.fn(),
     useDefinedFunctions: () => ({ getFunction: () => undefined }),
     useDmsRoute: () => ({ path: "/examples/overview", query: {} }),

package/frontend-vue/tests/page-realtime-remount.test.ts

@@ -101,7 +101,7 @@ beforeEach(async () => {
   vi.stubGlobal("useDmsRuntimeConfig", () => ({
     public: { dms: { baseURL: BASE_URL } },
   }));
-  vi.stubGlobal("useUserSession", () => ({ loggedIn }));
+  vi.stubGlobal("useDmsUserSession", () => ({ loggedIn }));
   vi.stubGlobal("useSessionRecovery", () => ({
     refreshSession: async () => true,
     redirectToAuth: async () => {},

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

@@ -18,9 +18,6 @@ vi.stubGlobal("useDmsState", <T>(key: string, init?: () => T): 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();
@@ -47,7 +44,3 @@ it("never shows a label on another page, and clears with no value", () => {
   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/page-validation-redirect.test.ts

@@ -27,6 +27,16 @@ import {
 } from "../layers/dms-layout/app/composables/layout/usePageFillHeight";
 import type { PageValidation } from "../layers/dms-layout/app/types/page";
 
+// The page's data refresh and the visit's navigation badges read the
+// realtime session and Inertia's page, which these tests do not run.
+vi.mock(
+  "../layers/dms-ui/app/build/composables/live/usePageDataRefresh",
+  () => ({ usePageDataRefresh: () => {} }),
+);
+vi.mock(
+  "../layers/dms-layout/app/build/composables/navigation/useVisitNavBadges",
+  () => ({ useVisitNavBadges: () => {} }),
+);
 vi.mock(
   "../layers/dms-layout/app/build/composables/dev-reload/useDevReloadHolder",
   async () => {
@@ -72,7 +82,7 @@ function installRuntime(): void {
     PAGE_FILL_HEIGHT_CLASSES,
     providePageFillHeight,
     usePageFillHeight,
-    createError: ({ statusCode }: { statusCode: number }) =>
+    createDmsError: ({ statusCode }: { statusCode: number }) =>
       new HttpError(statusCode),
     defineDmsPageMeta: vi.fn(),
     firstAccessiblePagePath: vi.fn(),
@@ -81,7 +91,7 @@ function installRuntime(): void {
     providePageRealtime: vi.fn(),
     resolveDmsComponent: () => "div",
     runCustomValidation,
-    showError: vi.fn(),
+    showDmsError: vi.fn(),
     validateRequiredQueryParams,
     useDefinedFunctions: () => ({ getFunction: () => undefined }),
     useDmsRoute: () => ({ path: PAGE_PATH, query: pageQuery.value }),

package/frontend-vue/tests/period-hydration-now.test.ts

@@ -0,0 +1,185 @@
+// @vitest-environment jsdom
+/**
+ * A relative preset (`last-24h`) in a server render and in the browser that
+ * hydrates it, through the runtime's real async data: both resolve the period
+ * from the instant the server rendered at, so the browser hydrates the same
+ * bounds, key and card data without asking again, whatever time it is when
+ * it hydrates. Anywhere else, the period follows the browser's clock.
+ */
+import {
+  createApp,
+  createSSRApp,
+  defineComponent,
+  h,
+  nextTick,
+  onBeforeUnmount,
+  type App,
+  type Component,
+} from "vue";
+import { renderToString } from "vue/server-renderer";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import {
+  browserTimeZone,
+  setReaderTimeZoneSource,
+} from "../layers/dms-core/app/utils/regional";
+
+const engine = await import("#dms/frontend-module");
+vi.stubGlobal("useDmsAsyncData", engine.useDmsAsyncData);
+vi.stubGlobal("useDmsFetch", engine.useDmsFetch);
+vi.stubGlobal("useDmsState", engine.useDmsState);
+vi.stubGlobal("useDmsCookie", engine.useDmsCookie);
+
+const requests: string[] = [];
+vi.stubGlobal("useAuthFetch", () => ({
+  $authFetch: async (url: string) => {
+    requests.push(url);
+    return {
+      value: new URL(url, "http://dms.local").searchParams.get("to"),
+    };
+  },
+}));
+
+const { useApiData } = await import(
+  "../layers/dms-core/app/composables/auth/useApiData"
+);
+vi.stubGlobal("useApiData", useApiData);
+const { usePeriod } = await import(
+  "../layers/dms-core/app/composables/period/usePeriod"
+);
+const { registerPeriodScope } = await import(
+  "../layers/dms-core/app/composables/period/usePeriodScope"
+);
+const { TIME_ZONE_COOKIE, useTimeZoneCookie } = await import(
+  "../layers/dms-core/app/composables/period/periodTimeZone"
+);
+setReaderTimeZoneSource(() => useTimeZoneCookie().value);
+const ZONE_COOKIE = `${TIME_ZONE_COOKIE}=${encodeURIComponent(JSON.stringify(browserTimeZone()))}`;
+// jsdom's `document` stays while the server renders: its cookies are the ones
+// read then, as the request's would be.
+document.cookie = ZONE_COOKIE;
+const { useChartFetch } = await import(
+  "../layers/dms-ui/app/composables/chart/useChartFetch"
+);
+
+const SCOPE = "ops";
+const SERVER_NOW = new Date("2026-10-15T10:00:30.000Z");
+// The browser hydrates a minute and a half later, past a minute boundary.
+const HYDRATION_DELAY_MS = 90_000;
+
+const Selector = defineComponent({
+  setup() {
+    const period = usePeriod({ defaultPreset: "last-24h" });
+    onBeforeUnmount(registerPeriodScope(SCOPE, period.state));
+    return () => h("i", period.state.value.key);
+  },
+});
+
+const Card = defineComponent({
+  setup() {
+    const { data, isLoading } = useChartFetch<{ value: string }>({
+      fetchUrl: "/api/errors",
+      periodScope: SCOPE,
+    });
+    return () =>
+      h("p", isLoading.value ? "SKELETON" : `to:${data.value?.value}`);
+  },
+});
+
+const Page: Component = {
+  render: () => h("main", [h(Selector), h(Card)]),
+};
+
+const mounted: App[] = [];
+
+beforeEach(() => {
+  requests.length = 0;
+  vi.useFakeTimers({ toFake: ["Date"] });
+  vi.setSystemTime(SERVER_NOW);
+});
+
+afterEach(() => {
+  mounted.splice(0).forEach((app) => app.unmount());
+  vi.useRealTimers();
+});
+
+async function serverRender() {
+  const runtime = engine.createDmsFrontendRuntime(
+    undefined,
+    {},
+    true,
+    ZONE_COOKIE,
+  );
+  const app = createSSRApp(Page);
+  engine.provideDmsFrontendRuntime(app, runtime);
+  engine.setDmsServerRuntimeResolver(() => runtime);
+  // What the server sees: no `window`.
+  const browserWindow = globalThis.window;
+  vi.stubGlobal("window", undefined);
+  try {
+    const html = await renderToString(app);
+    return { html, payload: engine.serializeDmsPayload(runtime) };
+  } finally {
+    vi.stubGlobal("window", browserWindow);
+  }
+}
+
+async function hydrate(html: string, payload: unknown) {
+  const browser = engine.createDmsFrontendRuntime(undefined, {});
+  engine.restoreDmsPayload(
+    browser,
+    structuredClone(payload) as Parameters<typeof engine.restoreDmsPayload>[1],
+  );
+  const container = document.createElement("div");
+  container.innerHTML = html;
+  const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+  const error = vi.spyOn(console, "error").mockImplementation(() => {});
+  const app = createSSRApp(Page);
+  engine.provideDmsFrontendRuntime(app, browser);
+  app.mount(container);
+  mounted.push(app);
+  await nextTick();
+  await new Promise((done) => setTimeout(done, 300));
+  const mismatches = [...warn.mock.calls, ...error.mock.calls].filter((call) =>
+    /hydration/i.test(String(call[0])),
+  );
+  warn.mockRestore();
+  error.mockRestore();
+  return { container, mismatches };
+}
+
+describe("a relative preset across a server render and its hydration", () => {
+  it("renders the card's data with the server's instant", async () => {
+    const { html } = await serverRender();
+
+    expect(html).toContain(`to:${SERVER_NOW.toISOString()}`);
+    expect(html).toContain(`|${SERVER_NOW.toISOString()}|`);
+    expect(requests).toHaveLength(1);
+  });
+
+  it("hydrates the same bounds later on: no request, no mismatch", async () => {
+    const { html, payload } = await serverRender();
+    requests.length = 0;
+    vi.setSystemTime(SERVER_NOW.getTime() + HYDRATION_DELAY_MS);
+
+    const { container, mismatches } = await hydrate(html, payload);
+
+    expect(mismatches).toEqual([]);
+    expect(requests).toEqual([]);
+    expect(container.innerHTML).toBe(html);
+  });
+
+  it("follows the browser's clock on a client mount", async () => {
+    const later = SERVER_NOW.getTime() + HYDRATION_DELAY_MS;
+    vi.setSystemTime(later);
+    const app = createApp(Selector);
+    engine.provideDmsFrontendRuntime(
+      app,
+      engine.createDmsFrontendRuntime(undefined, {}),
+    );
+    const root = document.createElement("div");
+    app.mount(root);
+    mounted.push(app);
+
+    expect(root.textContent).toContain(`|${new Date(later).toISOString()}|`);
+  });
+});

package/frontend-vue/tests/period-live-pause.test.ts

@@ -7,6 +7,7 @@
  */
 import { createApp, defineComponent, h, ref } from "vue";
 import { afterEach, beforeEach, expect, it, vi } from "vitest";
+import { useRealDataEngine } from "./fixtures/dataEngine";
 import { createPageLiveController } from "../layers/dms-ui/app/build/composables/live/pageLiveController";
 import { setCurrentPageLive } from "../layers/dms-ui/app/build/composables/live/currentPageLive";
 import { usePageLive } from "../layers/dms-ui/app/composables/live/usePageLive";
@@ -57,6 +58,8 @@ function mountPageWithChart(): UsePeriodReturn {
   return period!;
 }
 
+beforeEach(() => useRealDataEngine());
+
 beforeEach(() => {
   vi.useFakeTimers();
   requests.length = 0;