@antelopejs/dms 0.7.7 → 0.7.8

package/frontend-vue/tests/period-selector-url.test.ts

@@ -0,0 +1,268 @@
+// @vitest-environment jsdom
+/**
+ * A PeriodSelector keeps its period in the page URL: the period it starts
+ * from (the URL, then the user's last choice, then its default), the server
+ * render (no flash of the default), the in-place write on a change (no new
+ * history entry), and the period following a route changed from outside.
+ */
+import {
+  createApp,
+  createSSRApp,
+  defineComponent,
+  h,
+  nextTick,
+  reactive,
+  type App,
+} from "vue";
+import { renderToString } from "vue/server-renderer";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import type { PeriodPreset } from "../layers/dms-core/app/composables/period/types";
+
+const route = reactive<{ query: Record<string, string> }>({ query: {} });
+const preferences = new Map<string, unknown>();
+
+vi.stubGlobal("useDmsRoute", () => route);
+// Inertia's client-side replace moves its page URL, which the DMS route
+// follows: the route then holds the query the browser shows.
+const { inertiaReplace } = vi.hoisted(() => ({
+  inertiaReplace: vi.fn(({ url }: { url: string }) => {
+    route.query = Object.fromEntries(
+      new URL(url, "http://dms.local").searchParams,
+    );
+  }),
+}));
+vi.mock("@inertiajs/vue3", () => ({ router: { replace: inertiaReplace } }));
+vi.stubGlobal("usePreferences", () => ({
+  getPreference: <T>(key: string, fallback?: T) =>
+    (preferences.get(key) as T | undefined) ?? fallback,
+  setPreference: (key: string, value: unknown) => preferences.set(key, value),
+}));
+
+const { usePeriod } = await import(
+  "../layers/dms-core/app/composables/period/usePeriod"
+);
+const { usePeriodLocation, PERIOD_PREFERENCE_KEY } = await import(
+  "../layers/dms-ui/app/build/composables/period/usePeriodLocation"
+);
+
+type Period = ReturnType<typeof usePeriod>;
+
+const PAGE_ID = "dashboard";
+const PAGE_PATH = "/dashboard";
+const handles: Record<string, Period> = {};
+
+/** The selector's state wiring, as PeriodSelector.vue does it in setup. */
+function selector(id: string, defaultPreset: PeriodPreset = "this-month") {
+  return defineComponent({
+    setup() {
+      const period = usePeriod({
+        defaultPreset,
+        presets: ["last-7-days", "last-30-days", "this-month", "custom"],
+      });
+      usePeriodLocation(period, {
+        id,
+        pageId: PAGE_ID,
+        fallback: {
+          preset: period.preset.value,
+          comparison: period.comparison.value,
+          customRange: null,
+          customCompareRange: null,
+        },
+      });
+      handles[id] = period;
+      return () =>
+        h("span", `${period.preset.value}|${period.comparison.value}`);
+    },
+  });
+}
+
+const mounted: App[] = [];
+
+function mount(...ids: string[]): void {
+  const app = createApp({
+    setup: () => () =>
+      h(
+        "div",
+        ids.map((id) => h(selector(id))),
+      ),
+  });
+  app.mount(document.createElement("div"));
+  mounted.push(app);
+}
+
+const search = () => new URLSearchParams(window.location.search);
+
+const remember = (query: Record<string, string>) =>
+  preferences.set(PERIOD_PREFERENCE_KEY, { [`${PAGE_ID}#page`]: query });
+
+beforeEach(() => {
+  route.query = {};
+  preferences.clear();
+  inertiaReplace.mockClear();
+  window.history.replaceState(null, "", PAGE_PATH);
+});
+
+afterEach(() => {
+  mounted.splice(0).forEach((app) => app.unmount());
+});
+
+describe("the period a selector starts from", () => {
+  it("is the URL's", () => {
+    route.query = {
+      "page.period": "last-7-days",
+      "page.compare": "previous-year",
+    };
+    remember({
+      period: "last-30-days",
+    });
+    mount("page");
+    expect(handles.page!.preset.value).toBe("last-7-days");
+    expect(handles.page!.comparison.value).toBe("previous-year");
+  });
+
+  it("is the user's last choice when the URL names none", () => {
+    remember({
+      period: "last-30-days",
+      compare: "previous-period",
+    });
+    mount("page");
+    expect(handles.page!.preset.value).toBe("last-30-days");
+    expect(handles.page!.comparison.value).toBe("previous-period");
+  });
+
+  it("is the default when neither names a valid one", () => {
+    route.query = { "page.period": "next-century" };
+    remember({
+      period: "ytd",
+    });
+    mount("page");
+    expect(handles.page!.preset.value).toBe("this-month");
+    expect(handles.page!.comparison.value).toBe("none");
+  });
+
+  it("is a custom range read from the URL", () => {
+    route.query = { "page.from": "2026-10-01", "page.to": "2026-10-15" };
+    mount("page");
+    expect(handles.page!.preset.value).toBe("custom");
+    expect(handles.page!.state.value.range).toEqual({
+      from: new Date(2026, 9, 1),
+      to: new Date(2026, 9, 15, 23, 59, 59, 999),
+    });
+  });
+
+  it("is rendered by the server, so the default never flashes", async () => {
+    route.query = { "page.period": "last-7-days" };
+    const html = await renderToString(createSSRApp(selector("page")));
+    expect(html).toContain("last-7-days|none");
+  });
+});
+
+describe("the URL on load", () => {
+  it("carries the period the selector starts from, the default included", () => {
+    window.history.replaceState(null, "", `${PAGE_PATH}?requests.tab=get`);
+    mount("page");
+    expect(Object.fromEntries(search())).toEqual({
+      "requests.tab": "get",
+      "page.period": "this-month",
+      "page.compare": "none",
+    });
+  });
+
+  it("is left alone when it already names the period", () => {
+    window.history.replaceState(
+      null,
+      "",
+      `${PAGE_PATH}?page.period=this-month&page.compare=none`,
+    );
+    route.query = { "page.period": "this-month", "page.compare": "none" };
+    mount("page");
+    expect(inertiaReplace).not.toHaveBeenCalled();
+  });
+});
+
+describe("a change of period", () => {
+  it("reaches the route, so a tab written from it keeps the new period", async () => {
+    mount("page");
+    handles.page!.setPreset("last-7-days");
+    await nextTick();
+    // What useTab does: the route's query, plus its own key.
+    const query = { ...route.query, tab: "2" };
+    window.history.replaceState(
+      null,
+      "",
+      `${PAGE_PATH}?${new URLSearchParams(query)}`,
+    );
+    expect(search().get("tab")).toBe("2");
+    expect(search().get("page.period")).toBe("last-7-days");
+    expect(handles.page!.preset.value).toBe("last-7-days");
+  });
+
+  it("replaces the URL in place and remembers the choice", async () => {
+    mount("page");
+    const entries = window.history.length;
+    handles.page!.setPreset("last-7-days");
+    handles.page!.setComparison("previous-period");
+    await nextTick();
+    expect(search().get("page.period")).toBe("last-7-days");
+    expect(search().get("page.compare")).toBe("previous-period");
+    expect(window.history.length).toBe(entries);
+    expect(
+      (preferences.get(PERIOD_PREFERENCE_KEY) as Record<string, unknown>)[
+        `${PAGE_ID}#page`
+      ],
+    ).toEqual({ period: "last-7-days", compare: "previous-period" });
+  });
+
+  it("swaps the preset key for the custom range keys", async () => {
+    window.history.replaceState(
+      null,
+      "",
+      `${PAGE_PATH}?page.period=last-7-days`,
+    );
+    mount("page");
+    handles.page!.setCustomRange({
+      from: new Date(2026, 9, 1),
+      to: new Date(2026, 9, 2, 23, 59, 59, 999),
+    });
+    await nextTick();
+    expect(search().get("page.period")).toBeNull();
+    expect(search().get("page.from")).toBe("2026-10-01");
+    expect(search().get("page.to")).toBe("2026-10-02");
+  });
+
+  it("leaves another selector's keys and the other parameters alone", async () => {
+    window.history.replaceState(null, "", `${PAGE_PATH}?requests.tab=get`);
+    mount("sales", "traffic");
+    handles.sales!.setPreset("last-7-days");
+    await nextTick();
+    handles.traffic!.setPreset("last-30-days");
+    await nextTick();
+    expect(Object.fromEntries(search())).toEqual({
+      "requests.tab": "get",
+      "sales.period": "last-7-days",
+      "sales.compare": "none",
+      "traffic.period": "last-30-days",
+      "traffic.compare": "none",
+    });
+    expect(handles.sales!.preset.value).toBe("last-7-days");
+  });
+});
+
+describe("a route changed from outside", () => {
+  it("moves the period of the selector it names", async () => {
+    mount("sales", "traffic");
+    route.query = { "sales.period": "last-30-days" };
+    await nextTick();
+    expect(handles.sales!.preset.value).toBe("last-30-days");
+    expect(handles.traffic!.preset.value).toBe("this-month");
+  });
+
+  it("keeps the period when it names an invalid one", async () => {
+    mount("page");
+    handles.page!.setPreset("last-7-days");
+    await nextTick();
+    route.query = { "page.period": "last-decade" };
+    await nextTick();
+    expect(handles.page!.preset.value).toBe("last-7-days");
+  });
+});

package/frontend-vue/tests/period-url-query.test.ts

@@ -0,0 +1,351 @@
+/**
+ * A PeriodSelector keeps its period in the page URL under keys prefixed with
+ * its id. These cover what the URL holds: how a selection is written and read
+ * back, which source wins (the URL, then the user's last choice, then the
+ * default), that two selectors never read each other's keys, and that a value
+ * the selector cannot honour falls back silently.
+ */
+import { describe, expect, it } from "vitest";
+import {
+  formatPeriodDate,
+  isPeriodQueryCurrent,
+  mergePeriodSearch,
+  parsePeriodDate,
+  periodQueryKeys,
+  type PeriodChoices,
+  type PeriodSelection,
+  readComparisonChoice,
+  readRangeChoice,
+  rememberPeriod,
+  resolvePeriodSelection,
+  writePeriodQuery,
+} from "../layers/dms-ui/app/build/composables/period/periodQuery";
+
+const CHOICES: PeriodChoices = {
+  presets: ["last-7-days", "last-30-days", "this-month", "custom"],
+  comparisons: ["none", "previous-period", "previous-year", "custom"],
+};
+const DEFAULT: PeriodSelection = {
+  preset: "this-month",
+  comparison: "none",
+  customRange: null,
+  customCompareRange: null,
+};
+const PAGE = periodQueryKeys("page");
+const STORED = periodQueryKeys();
+
+const day = (year: number, month: number, date: number) =>
+  new Date(year, month - 1, date);
+const endOfDay = (year: number, month: number, date: number) =>
+  new Date(year, month - 1, date, 23, 59, 59, 999);
+
+describe("the keys of a selector", () => {
+  it("prefixes every key with the selector id", () => {
+    expect(PAGE).toEqual({
+      period: "page.period",
+      compare: "page.compare",
+      from: "page.from",
+      to: "page.to",
+      compareFrom: "page.compareFrom",
+      compareTo: "page.compareTo",
+    });
+  });
+
+  it("keeps the bare keys without an id", () => {
+    expect(STORED.period).toBe("period");
+  });
+});
+
+describe("serializing a selection", () => {
+  it("writes a preset and its comparison", () => {
+    expect(
+      writePeriodQuery(
+        { ...DEFAULT, preset: "last-7-days", comparison: "previous-period" },
+        PAGE,
+      ),
+    ).toEqual({
+      "page.period": "last-7-days",
+      "page.compare": "previous-period",
+    });
+  });
+
+  it("writes a custom range of whole days as bare dates", () => {
+    expect(
+      writePeriodQuery(
+        {
+          ...DEFAULT,
+          preset: "custom",
+          customRange: { from: day(2026, 10, 1), to: endOfDay(2026, 10, 31) },
+        },
+        PAGE,
+      ),
+    ).toEqual({
+      "page.from": "2026-10-01",
+      "page.to": "2026-10-31",
+      "page.compare": "none",
+    });
+  });
+
+  it("writes an instant that is not a day boundary as an ISO date-time", () => {
+    const from = new Date(2026, 9, 1, 10, 30);
+    expect(formatPeriodDate(from, "start")).toBe(from.toISOString());
+  });
+
+  it("writes a custom comparison with its own range", () => {
+    expect(
+      writePeriodQuery(
+        {
+          ...DEFAULT,
+          comparison: "custom",
+          customCompareRange: {
+            from: day(2025, 10, 1),
+            to: endOfDay(2025, 10, 31),
+          },
+        },
+        PAGE,
+      ),
+    ).toEqual({
+      "page.period": "this-month",
+      "page.compare": "custom",
+      "page.compareFrom": "2025-10-01",
+      "page.compareTo": "2025-10-31",
+    });
+  });
+
+  it("reads back what it wrote", () => {
+    const selection: PeriodSelection = {
+      preset: "custom",
+      comparison: "custom",
+      customRange: {
+        from: new Date(2026, 9, 1, 8),
+        to: new Date(2026, 9, 2, 18),
+      },
+      customCompareRange: { from: day(2026, 9, 1), to: endOfDay(2026, 9, 2) },
+    };
+    const query = writePeriodQuery(selection, PAGE);
+    expect(
+      resolvePeriodSelection([{ query, keys: PAGE }], CHOICES, DEFAULT),
+    ).toEqual(selection);
+    expect(isPeriodQueryCurrent(query, PAGE, selection)).toBe(true);
+  });
+});
+
+describe("parsing the URL", () => {
+  it("reads an ISO date as the start or the end of that local day", () => {
+    expect(parsePeriodDate("2026-10-01", "start")).toEqual(day(2026, 10, 1));
+    expect(parsePeriodDate("2026-10-01", "end")).toEqual(endOfDay(2026, 10, 1));
+  });
+
+  it("reads an ISO date-time as that instant", () => {
+    expect(parsePeriodDate("2026-10-01T08:00:00.000Z", "start")).toEqual(
+      new Date("2026-10-01T08:00:00.000Z"),
+    );
+  });
+
+  it.each(["2026-02-30", "yesterday", "1700000000", "2026-13-01", ""])(
+    "refuses %j",
+    (text) => {
+      expect(parsePeriodDate(text, "start")).toBeNull();
+    },
+  );
+
+  it("reads a preset the selector offers", () => {
+    const query = { "page.period": "last-30-days" };
+    expect(readRangeChoice({ query, keys: PAGE }, CHOICES)).toEqual({
+      preset: "last-30-days",
+      customRange: null,
+    });
+  });
+
+  it("prefers a custom range to a preset", () => {
+    const query = {
+      "page.period": "last-30-days",
+      "page.from": "2026-10-01",
+      "page.to": "2026-10-15",
+    };
+    expect(readRangeChoice({ query, keys: PAGE }, CHOICES)).toEqual({
+      preset: "custom",
+      customRange: { from: day(2026, 10, 1), to: endOfDay(2026, 10, 15) },
+    });
+  });
+
+  it("takes the first value of a repeated key", () => {
+    const query = { "page.period": ["last-7-days", "last-30-days"] };
+    expect(readRangeChoice({ query, keys: PAGE }, CHOICES)?.preset).toBe(
+      "last-7-days",
+    );
+  });
+
+  it.each([
+    ["an unknown preset", { "page.period": "last-decade" }],
+    ["a preset the selector does not offer", { "page.period": "ytd" }],
+    ["custom with no range", { "page.period": "custom" }],
+    [
+      "a range ending before it starts",
+      { "page.from": "2026-10-15", "page.to": "2026-10-01" },
+    ],
+    ["half a range", { "page.from": "2026-10-01" }],
+  ])("ignores %s", (_, query) => {
+    expect(readRangeChoice({ query, keys: PAGE }, CHOICES)).toBeNull();
+  });
+
+  it("ignores a custom range the selector does not offer", () => {
+    const query = { "page.from": "2026-10-01", "page.to": "2026-10-15" };
+    const presets = CHOICES.presets.filter((preset) => preset !== "custom");
+    expect(
+      readRangeChoice({ query, keys: PAGE }, { ...CHOICES, presets }),
+    ).toBeNull();
+  });
+
+  it.each([
+    ["an unknown comparison", { "page.compare": "previous-decade" }],
+    ["a custom comparison with no range", { "page.compare": "custom" }],
+  ])("ignores %s", (_, query) => {
+    expect(readComparisonChoice({ query, keys: PAGE }, CHOICES)).toBeNull();
+  });
+});
+
+describe("the order of the sources", () => {
+  const stored = {
+    query: { period: "last-30-days", compare: "previous-year" },
+    keys: STORED,
+  };
+
+  it("reads the URL first", () => {
+    const url = {
+      query: { "page.period": "last-7-days", "page.compare": "none" },
+      keys: PAGE,
+    };
+    expect(
+      resolvePeriodSelection([url, stored], CHOICES, DEFAULT),
+    ).toMatchObject({ preset: "last-7-days", comparison: "none" });
+  });
+
+  it("reads the user's last choice when the URL names nothing", () => {
+    expect(
+      resolvePeriodSelection(
+        [{ query: {}, keys: PAGE }, stored],
+        CHOICES,
+        DEFAULT,
+      ),
+    ).toMatchObject({ preset: "last-30-days", comparison: "previous-year" });
+  });
+
+  it("falls back to the default when no source names a period", () => {
+    expect(
+      resolvePeriodSelection(
+        [
+          { query: {}, keys: PAGE },
+          { query: {}, keys: STORED },
+        ],
+        CHOICES,
+        DEFAULT,
+      ),
+    ).toEqual(DEFAULT);
+  });
+
+  it("skips an invalid URL value for the next source, half by half", () => {
+    const url = {
+      query: {
+        "page.period": "last-decade",
+        "page.compare": "previous-period",
+      },
+      keys: PAGE,
+    };
+    expect(
+      resolvePeriodSelection([url, stored], CHOICES, DEFAULT),
+    ).toMatchObject({
+      preset: "last-30-days",
+      comparison: "previous-period",
+    });
+  });
+
+  it("skips an invalid stored value for the default", () => {
+    const broken = { query: { period: 42, compare: "?" }, keys: STORED };
+    expect(
+      resolvePeriodSelection(
+        [{ query: {}, keys: PAGE }, broken],
+        CHOICES,
+        DEFAULT,
+      ),
+    ).toEqual(DEFAULT);
+  });
+});
+
+describe("several selectors on one page", () => {
+  const query = {
+    "sales.period": "last-7-days",
+    "sales.compare": "previous-year",
+    "traffic.period": "last-30-days",
+    "traffic.compare": "none",
+    period: "this-month",
+  };
+
+  it("reads each selector's own keys only", () => {
+    const read = (id: string) =>
+      resolvePeriodSelection(
+        [{ query, keys: periodQueryKeys(id) }],
+        CHOICES,
+        DEFAULT,
+      );
+    expect(read("sales")).toMatchObject({
+      preset: "last-7-days",
+      comparison: "previous-year",
+    });
+    expect(read("traffic")).toMatchObject({
+      preset: "last-30-days",
+      comparison: "none",
+    });
+    expect(read("other")).toEqual(DEFAULT);
+  });
+
+  it("rewrites one selector's keys and keeps every other parameter", () => {
+    const search =
+      "?requests.tab=get&sales.period=last-7-days&sales.compare=none&traffic.period=last-30-days";
+    const next = mergePeriodSearch(search, periodQueryKeys("sales"), {
+      ...DEFAULT,
+      preset: "custom",
+      customRange: { from: day(2026, 10, 1), to: endOfDay(2026, 10, 2) },
+    });
+    expect(Object.fromEntries(new URLSearchParams(next))).toEqual({
+      "requests.tab": "get",
+      "sales.compare": "none",
+      "sales.from": "2026-10-01",
+      "sales.to": "2026-10-02",
+      "traffic.period": "last-30-days",
+    });
+  });
+});
+
+describe("the last choices kept in the browser", () => {
+  it("keeps only the most recent ones", () => {
+    let store = {};
+    for (let index = 0; index < 25; index++) {
+      store = rememberPeriod(store, `page-${index}#page`, { period: "ytd" });
+    }
+    const keys = Object.keys(store);
+    expect(keys).toHaveLength(20);
+    expect(keys[0]).toBe("page-5#page");
+    expect(keys.at(-1)).toBe("page-24#page");
+  });
+
+  it("moves a selector chosen again to the most recent place", () => {
+    const store = rememberPeriod(
+      { "a#page": { period: "ytd" }, "b#page": { period: "ytd" } },
+      "a#page",
+      { period: "last-7-days" },
+      2,
+    );
+    expect(Object.keys(store)).toEqual(["b#page", "a#page"]);
+    expect(store["a#page"]).toEqual({ period: "last-7-days" });
+    expect(
+      Object.keys(rememberPeriod(store, "c#page", { period: "ytd" }, 2)),
+    ).toEqual(["a#page", "c#page"]);
+  });
+
+  it("starts over from a store that is not an object", () => {
+    expect(rememberPeriod("broken", "a#page", { period: "ytd" })).toEqual({
+      "a#page": { period: "ytd" },
+    });
+  });
+});