@antelopejs/dms 0.8.3 → 0.9.1

package/frontend-vue/tests/period-reader-zone.test.ts

@@ -0,0 +1,137 @@
+/**
+ * A server render resolves periods and writes dates in the time zone of the
+ * browser it renders for (its `dms-time-zone` cookie), whatever the server's
+ * own: the same bounds and the same text as the browser's, so hydration
+ * matches. Without the cookie, or in the server's own zone, nothing changes.
+ */
+import { afterEach, describe, expect, it } from "vitest";
+import {
+  browserTimeZone,
+  regionalDateTimeFormat,
+  regionalDayKey,
+  setReaderTimeZoneSource,
+} from "../layers/dms-core/app/utils/regional";
+import {
+  localClock,
+  zonedClock,
+} from "../layers/dms-core/app/composables/period/periodClock";
+import { resolvePresetRange } from "../layers/dms-core/app/composables/period/presetResolvers";
+import { resolveComparisonRange } from "../layers/dms-core/app/composables/period/compareResolvers";
+import {
+  formatPeriodDate,
+  parsePeriodDate,
+} from "../layers/dms-ui/app/build/composables/period/periodQuery";
+import { formatPeriodRange } from "../layers/dms-ui/app/build/composables/period/periodDisplay";
+
+// A zone far from any CI's, and one with a daylight saving change.
+const READER_ZONE =
+  browserTimeZone() === "Pacific/Kiritimati"
+    ? "Etc/GMT+12"
+    : "Pacific/Kiritimati";
+const NEW_YORK = "America/New_York";
+const NOW = new Date("2026-10-14T21:30:00.000Z");
+const FALLBACK = { from: NOW, to: NOW };
+
+function readFor(zone: string | null): void {
+  setReaderTimeZoneSource(() => zone);
+}
+
+function inZone(zone: string, date: Date) {
+  const { year, month, day, hours, minutes } = zonedClock(zone).wall(date);
+  return `${year}-${month + 1}-${day} ${hours}:${minutes}`;
+}
+
+afterEach(() => readFor(null));
+
+describe("the clock a period is resolved in", () => {
+  it("reads and builds wall times in a zone, across a daylight saving change", () => {
+    const clock = zonedClock(NEW_YORK);
+    // 8 March 2026: New York moves from UTC-5 to UTC-4 at 2:00.
+    const midnight = clock.instant({
+      year: 2026,
+      month: 2,
+      day: 8,
+      hours: 0,
+      minutes: 0,
+      seconds: 0,
+      milliseconds: 0,
+    });
+    expect(midnight.toISOString()).toBe("2026-03-08T05:00:00.000Z");
+    const evening = clock.instant({ ...clock.wall(midnight), hours: 23 });
+    expect(evening.toISOString()).toBe("2026-03-09T03:00:00.000Z");
+    // Day 0 rolls back to the last day of the month before, as Date's does.
+    const rolled = clock.wall(
+      clock.instant({ ...clock.wall(midnight), month: 3, day: 0 }),
+    );
+    expect([rolled.month, rolled.day]).toEqual([2, 31]);
+  });
+
+  it("matches Date's own calendar in the zone the code runs in", () => {
+    const local = zonedClock(browserTimeZone());
+    expect(local.wall(NOW)).toEqual(localClock.wall(NOW));
+    const wall = { ...localClock.wall(NOW), day: 40, hours: 0 };
+    expect(local.instant(wall).getTime()).toBe(
+      localClock.instant(wall).getTime(),
+    );
+  });
+});
+
+describe("a server render for a browser in another zone", () => {
+  it("resolves presets and comparisons on the browser's calendar days", () => {
+    readFor(READER_ZONE);
+    const range = resolvePresetRange("this-month", NOW, FALLBACK)!;
+    const reader = zonedClock(READER_ZONE);
+    expect(inZone(READER_ZONE, range.from)).toMatch(/-1 0:0$/);
+    expect(reader.wall(range.to).hours).toBe(23);
+    expect(reader.wall(range.to).month).toBe(reader.wall(range.from).month);
+    const previous = resolveComparisonRange("previous-year", range, null)!;
+    expect(reader.wall(previous.from).year).toBe(
+      reader.wall(range.from).year - 1,
+    );
+    expect(inZone(READER_ZONE, previous.from)).toMatch(/-1 0:0$/);
+  });
+
+  it("reads and writes the URL's days as the browser's", () => {
+    readFor(READER_ZONE);
+    const from = parsePeriodDate("2026-10-01", "start")!;
+    expect(inZone(READER_ZONE, from)).toBe("2026-10-1 0:0");
+    expect(formatPeriodDate(from, "start")).toBe("2026-10-01");
+    expect(parsePeriodDate("2026-02-30", "start")).toBeNull();
+  });
+
+  it("writes the period's label and other dates in the browser's zone", () => {
+    readFor(READER_ZONE);
+    const range = resolvePresetRange("this-month", NOW, FALLBACK)!;
+    const expected = new Intl.DateTimeFormat("en", {
+      month: "short",
+      day: "numeric",
+      timeZone: READER_ZONE,
+    }).format(range.from);
+    expect(formatPeriodRange(range, "en")).toContain(expected);
+    expect(
+      regionalDateTimeFormat("en", { dateStyle: "medium" }).format(NOW),
+    ).toBe(
+      new Intl.DateTimeFormat("en", {
+        dateStyle: "medium",
+        timeZone: READER_ZONE,
+      }).format(NOW),
+    );
+  });
+
+  it("files dates under the browser's calendar days", () => {
+    readFor(READER_ZONE);
+    const { year, month, day } = zonedClock(READER_ZONE).wall(NOW);
+    const pad = (value: number) => String(value).padStart(2, "0");
+    expect(regionalDayKey(NOW)).toBe(`${year}-${pad(month + 1)}-${pad(day)}`);
+  });
+
+  it("changes nothing without the browser's zone, or in the server's own", () => {
+    for (const zone of [null, browserTimeZone()]) {
+      readFor(zone);
+      const range = resolvePresetRange("this-month", NOW, FALLBACK)!;
+      expect(range.from).toEqual(
+        new Date(NOW.getFullYear(), NOW.getMonth(), 1),
+      );
+    }
+  });
+});

package/frontend-vue/tests/period-scope-first-fetch.test.ts

@@ -19,6 +19,7 @@ import {
 } from "vue";
 import { renderToString } from "vue/server-renderer";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { useRealDataEngine } from "./fixtures/dataEngine";
 import type { PeriodState } from "../layers/dms-core/app/composables/period/types";
 
 const requests: string[] = [];
@@ -143,7 +144,13 @@ async function ssrThenHydrate(
   const container = document.createElement("div");
   container.innerHTML = html;
   document.body.appendChild(container);
+  // The browser starts from what the page carried, as it does after a server
+  // render: its first mount takes the data over instead of reading it again.
+  const payload = structuredClone(engine.serializeDmsPayload(renderRuntime));
+  const browser = engine.createDmsFrontendRuntime(undefined, {});
+  engine.restoreDmsPayload(browser, payload);
   const app = withComponents(createSSRApp(root as never), components);
+  engine.provideDmsFrontendRuntime(app, browser);
   app.mount(container);
   mounted.push(app);
   const deadline = Date.now() + SETTLE_MS;
@@ -163,6 +170,13 @@ function withComponents<
   return app;
 }
 
+const engine = await import("#dms/frontend-module");
+let renderRuntime: ReturnType<typeof useRealDataEngine>;
+
+beforeEach(() => {
+  renderRuntime = useRealDataEngine();
+});
+
 beforeEach(() => {
   requests.length = 0;
 });
@@ -238,6 +252,8 @@ describe("period-scoped cards on first paint", () => {
     }
   });
 
+  // Its period unknown to the server (no selector registered it before the
+  // card set up), a card renders its placeholder, never an empty value.
   it("shows a loading placeholder server-side rather than an empty value", async () => {
     const app = createSSRApp({
       render: () =>
@@ -246,7 +262,7 @@ describe("period-scoped cards on first paint", () => {
           componentId: "card",
           pageId: "page",
           fetchUrl: "/api/metrics/kpi/revenue",
-          periodScope: SCOPE,
+          periodScope: "unregistered-scope",
         }),
     });
     withComponents(app, {

package/frontend-vue/tests/period-ssr.test.ts

@@ -0,0 +1,195 @@
+/**
+ * A server render of a dashboard, through the runtime's real async data: a
+ * card bound to a period scope renders its data when the server resolves the
+ * period as the browser will (in the browser's time zone, read in its cookie;
+ * a selector set up before the card), and its placeholder
+ * otherwise, requesting nothing. Each request has its scopes.
+ */
+import { createSSRApp, defineComponent, h, ref, type Component } from "vue";
+import { renderToString } from "vue/server-renderer";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import type { PeriodPreset } from "../layers/dms-core/app/composables/period/types";
+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);
+    await new Promise((done) => setTimeout(done, 5));
+    return {
+      value: new URL(url, "http://dms.local").searchParams.get("preset"),
+    };
+  },
+}));
+
+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"
+);
+const { zonedClock } = await import(
+  "../layers/dms-core/app/composables/period/periodClock"
+);
+// What the regional-preferences plugin sets up.
+setReaderTimeZoneSource(() => useTimeZoneCookie().value);
+const { useChartFetch } = await import(
+  "../layers/dms-ui/app/composables/chart/useChartFetch"
+);
+
+const SCOPE = "dashboard";
+
+function selector(preset: PeriodPreset): Component {
+  return defineComponent({
+    setup() {
+      const period = usePeriod({ defaultPreset: preset });
+      registerPeriodScope(SCOPE, period.state);
+      return () => h("i");
+    },
+  });
+}
+
+const Card = defineComponent({
+  setup() {
+    const { data, isLoading } = useChartFetch<{ value: string }>({
+      fetchUrl: "/api/kpi",
+      periodScope: SCOPE,
+    });
+    return () =>
+      h("p", isLoading.value ? "SKELETON" : `value:${data.value?.value}`);
+  },
+});
+
+function zoneCookie(zone: string): string {
+  return `${TIME_ZONE_COOKIE}=${encodeURIComponent(JSON.stringify(zone))}`;
+}
+
+async function serverRender(children: Component[], cookies?: string) {
+  const runtime = engine.createDmsFrontendRuntime(undefined, {}, true, cookies);
+  const app = createSSRApp({
+    render: () =>
+      h(
+        "main",
+        children.map((c) => h(c)),
+      ),
+  });
+  engine.provideDmsFrontendRuntime(app, runtime);
+  engine.setDmsServerRuntimeResolver(() => runtime);
+  const html = await renderToString(app);
+  return { html, payload: engine.serializeDmsPayload(runtime) };
+}
+
+beforeEach(() => {
+  requests.length = 0;
+});
+
+describe("a period-scoped card in a server render", () => {
+  it("renders its data with the period the browser resolves, and hands it over", async () => {
+    const { html, payload } = await serverRender(
+      [selector("this-month"), Card],
+      zoneCookie(browserTimeZone()),
+    );
+
+    expect(html).toContain("value:this-month");
+    expect(requests).toHaveLength(1);
+    expect(requests[0]).toMatch(
+      /^\/api\/kpi\?from=.*&preset=this-month&comparison=none$/,
+    );
+    expect(Object.values(payload.data)).toEqual([{ value: "this-month" }]);
+  });
+
+  it("leaves it to the browser without the browser's time zone", async () => {
+    const { html } = await serverRender([selector("this-month"), Card]);
+
+    expect(html).toContain("SKELETON");
+    expect(requests).toEqual([]);
+  });
+
+  it("resolves the period in the browser's zone when it is not the server's", async () => {
+    const elsewhere =
+      browserTimeZone() === "Pacific/Kiritimati"
+        ? "Etc/GMT+12"
+        : "Pacific/Kiritimati";
+    const { html } = await serverRender(
+      [selector("this-month"), Card],
+      zoneCookie(elsewhere),
+    );
+
+    expect(html).toContain("value:this-month");
+    const query = new URL(requests[0]!, "http://dms.local").searchParams;
+    const from = zonedClock(elsewhere).wall(new Date(query.get("from")!));
+    const to = zonedClock(elsewhere).wall(new Date(query.get("to")!));
+    expect([from.day, from.hours, from.minutes]).toEqual([1, 0, 0]);
+    expect([to.hours, to.minutes, to.milliseconds]).toEqual([23, 59, 999]);
+    expect(to.month).toBe(from.month);
+  });
+
+  it("renders a relative preset too, from the instant it hands the browser", async () => {
+    const { html, payload } = await serverRender(
+      [selector("last-24h"), Card],
+      zoneCookie(browserTimeZone()),
+    );
+
+    expect(html).toContain("value:last-24h");
+    expect(requests).toHaveLength(1);
+    const query = new URL(requests[0]!, "http://dms.local").searchParams;
+    expect(payload.state["dms-period-render-now"]).toBe(
+      new Date(query.get("to")!).getTime(),
+    );
+  });
+
+  it("leaves it to the browser when its selector sets up after it", async () => {
+    const { html } = await serverRender(
+      [Card, selector("this-month")],
+      zoneCookie(browserTimeZone()),
+    );
+
+    expect(html).toContain("SKELETON");
+    expect(requests).toEqual([]);
+  });
+
+  it("keeps the scopes of concurrent requests apart", async () => {
+    const cookie = zoneCookie(browserTimeZone());
+    const [month, year] = await Promise.all([
+      serverRender([selector("this-month"), Card], cookie),
+      serverRender([selector("last-year"), Card], cookie),
+    ]);
+
+    expect(month.html).toContain("value:this-month");
+    expect(year.html).toContain("value:last-year");
+  });
+});
+
+describe("a card without a period in a server render", () => {
+  it("renders its data", async () => {
+    const Plain = defineComponent({
+      setup() {
+        const { data } = useChartFetch<{ value: string | null }>({
+          fetchUrl: "/api/plain",
+          watchSource: () => ref(1).value,
+        });
+        return () => h("p", `plain:${data.value ? "loaded" : "none"}`);
+      },
+    });
+    const { html } = await serverRender([Plain]);
+
+    expect(html).toContain("plain:loaded");
+    expect(requests).toEqual(["/api/plain"]);
+  });
+});

package/frontend-vue/tests/permission-preview-partial.test.ts

@@ -198,8 +198,6 @@ describe("NavigationMenu in a role preview", () => {
       if (!state.has(key)) state.set(key, ref(initial()));
       return state.get(key);
     });
-    vi.stubGlobal("usePrefetch", () => ({ prefetchPageLayout: vi.fn() }));
-    vi.stubGlobal("stripQueryAndHash", (path: string) => path);
     vi.stubGlobal("MENU_STATUS_TEXT_CLASSES", MENU_STATUS_TEXT_CLASSES);
     host = document.createElement("div");
     document.body.append(host);

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

@@ -0,0 +1,194 @@
+// @vitest-environment jsdom
+/**
+ * The permission set the `auth` middleware preloads 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 finds it and asks nothing.
+ * A caller that only needs a set joins a load in flight.
+ */
+import {
+  createApp,
+  createSSRApp,
+  defineComponent,
+  h,
+  nextTick,
+  type App,
+} from "vue";
+import { renderToString } from "vue/server-renderer";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import type { DmsFrontendRuntime } from "#dms/frontend-module";
+
+const engine = await import("#dms/frontend-module");
+const { createTrailingDeduper } = await import(
+  "../layers/dms-core/app/utils/trailingDeduper"
+);
+vi.stubGlobal("useDmsState", engine.useDmsState);
+vi.stubGlobal("useDmsApp", engine.useDmsApp);
+vi.stubGlobal("defineDmsMiddleware", engine.defineDmsMiddleware);
+vi.stubGlobal("useDmsError", engine.useDmsError);
+vi.stubGlobal("abortDmsNavigation", engine.abortDmsNavigation);
+vi.stubGlobal("navigateDms", engine.navigateDms);
+vi.stubGlobal("createTrailingDeduper", createTrailingDeduper);
+vi.stubGlobal("useDmsRuntimeConfig", () => ({ public: { dms: {} } }));
+vi.stubGlobal("useSiteLayout", () => ({
+  siteLayout: { value: {} },
+  findMatchingRoute: () => ({ metadata: {} }),
+}));
+vi.stubGlobal("useDmsUserSession", () => ({
+  loggedIn: { value: true },
+  user: { value: { isValidated: true } },
+}));
+
+const { useTrailingDeduper } = await import(
+  "../layers/dms-core/app/composables/useTrailingDeduper"
+);
+vi.stubGlobal("useTrailingDeduper", useTrailingDeduper);
+const { usePermissions } = await import(
+  "../layers/dms-core/app/composables/auth/usePermissions"
+);
+vi.stubGlobal("usePermissions", usePermissions);
+const { default: authMiddleware } = await import(
+  "../layers/dms-auth/app/middleware/auth"
+);
+
+const PERMISSION = "orders.read";
+
+interface PendingRequest {
+  resolve: (ids: string[]) => void;
+}
+
+const requests: PendingRequest[] = [];
+// Answers each request once the test releases it, in order.
+const $authFetch = vi.fn(
+  () =>
+    new Promise<string[]>((resolve) => {
+      requests.push({ resolve });
+    }),
+);
+vi.stubGlobal("useAuthFetch", () => ({ $authFetch }));
+
+const mounted: App[] = [];
+
+const settle = async () => {
+  await nextTick();
+  await new Promise((resolve) => setTimeout(resolve, 0));
+};
+
+async function answerRequests(): Promise<void> {
+  for (let round = 0; round < 3; round++) {
+    await settle();
+    for (const request of requests.splice(0)) request.resolve([PERMISSION]);
+  }
+}
+
+const Page = defineComponent({
+  setup() {
+    defineDmsPageMeta({ auth: true });
+    const { hasPermission } = usePermissions();
+    return () => h("p", hasPermission(PERMISSION) ? "can read" : "cannot read");
+  },
+});
+const { defineDmsPageMeta } = engine;
+
+/** A runtime whose app carries the DMS app context, as the real app's does. */
+function attach(app: App, runtime: DmsFrontendRuntime): void {
+  const context = {} as DmsFrontendRuntime["appContext"];
+  app.config.globalProperties.$dms = context;
+  runtime.appContext = context;
+  runtime.route.matched = [{}];
+  engine.provideDmsFrontendRuntime(app, runtime);
+}
+
+beforeEach(async () => {
+  requests.length = 0;
+  $authFetch.mockClear();
+  await engine.setupFrontendModules([
+    {
+      options: { public: {} },
+      module: {
+        setup(sdk) {
+          sdk.registerMiddleware("auth", authMiddleware);
+        },
+      },
+    },
+  ]);
+});
+
+afterEach(() => {
+  mounted.splice(0).forEach((app) => app.unmount());
+});
+
+describe("permissions handed to the browser", () => {
+  it("renders the page with the set the server loaded, and the browser asks nothing", async () => {
+    const server = engine.createDmsFrontendRuntime(undefined, {}, true);
+    const serverApp = createSSRApp(Page);
+    attach(serverApp, server);
+    const rendering = renderToString(serverApp);
+    await answerRequests();
+    expect(await rendering).toContain("can read");
+    expect($authFetch).toHaveBeenCalledTimes(1);
+
+    const payload = structuredClone(engine.serializeDmsPayload(server));
+    expect(payload.state["dms-user-permissions"]).toEqual(
+      new Set([PERMISSION]),
+    );
+
+    $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 answerRequests();
+
+    expect($authFetch).not.toHaveBeenCalled();
+    expect(host.textContent).toBe("can read");
+  });
+});
+
+describe("loading the permission set", () => {
+  function browserPermissions() {
+    const runtime = engine.createDmsFrontendRuntime();
+    const app = createApp({ render: () => null });
+    attach(app, runtime);
+    return app.runWithContext(() => usePermissions());
+  }
+
+  it("joins a first load in flight instead of loading twice", async () => {
+    const permissions = browserPermissions();
+    const loads = Promise.all([
+      permissions.loadPermissions(),
+      permissions.loadPermissions(),
+    ]);
+    await answerRequests();
+    await loads;
+
+    expect($authFetch).toHaveBeenCalledTimes(1);
+    expect(permissions.hasPermission(PERMISSION)).toBe(true);
+  });
+
+  it("still gives a refresh asked during a load its own pass", async () => {
+    const permissions = browserPermissions();
+    const runs = Promise.all([
+      permissions.loadPermissions(),
+      permissions.fetchPermissions(),
+    ]);
+    await answerRequests();
+    await runs;
+
+    expect($authFetch).toHaveBeenCalledTimes(2);
+  });
+
+  it("loads again when the load it joined was cleared meanwhile", async () => {
+    const permissions = browserPermissions();
+    const first = permissions.loadPermissions();
+    permissions.clear();
+    const second = permissions.loadPermissions();
+    await answerRequests();
+    await Promise.all([first, second]);
+
+    expect($authFetch).toHaveBeenCalledTimes(2);
+    expect(permissions.isLoaded.value).toBe(true);
+  });
+});

package/frontend-vue/tests/post-login-redirect.test.ts

@@ -9,7 +9,7 @@ const navigateTo = vi.fn();
 
 beforeEach(() => {
   vi.stubGlobal("useDmsApp", () => ({ $i18n: { setLocale } }));
-  vi.stubGlobal("useUserSession", () => ({
+  vi.stubGlobal("useDmsUserSession", () => ({
     fetch: refreshUser,
     user: { value: { language: "fr" } },
   }));
@@ -37,7 +37,7 @@ describe("post-login redirect", () => {
     await usePostLoginRedirect(resolveDestination);
 
     expect(resolveDestination).toHaveBeenCalledOnce();
-    expect(navigateTo).toHaveBeenCalledWith("/dashboard");
+    expect(navigateTo).toHaveBeenCalledWith("/dashboard", {});
     expect(refreshUser.mock.invocationCallOrder[0]).toBeLessThan(
       refreshLayout.mock.invocationCallOrder[0]!,
     );
@@ -45,12 +45,17 @@ describe("post-login redirect", () => {
 
   it("preserves explicit login destinations", async () => {
     await usePostLoginRedirect("/reports");
-    expect(navigateTo).toHaveBeenCalledWith("/reports");
+    expect(navigateTo).toHaveBeenCalledWith("/reports", {});
+  });
+
+  it("opens the destination in place of the current page when asked", async () => {
+    await usePostLoginRedirect("/reports", { replace: true });
+    expect(navigateTo).toHaveBeenCalledWith("/reports", { replace: true });
   });
 
   it("falls back to the homepage when no page is accessible", async () => {
     await usePostLoginRedirect(() => undefined);
-    expect(navigateTo).toHaveBeenCalledWith("/");
+    expect(navigateTo).toHaveBeenCalledWith("/", {});
   });
 
   it("does not navigate when session refresh fails", async () => {
@@ -61,7 +66,7 @@ describe("post-login redirect", () => {
   });
 
   it("rejects a session refresh that resolves without an authenticated user", async () => {
-    vi.stubGlobal("useUserSession", () => ({
+    vi.stubGlobal("useDmsUserSession", () => ({
       fetch: refreshUser,
       user: { value: null },
     }));