@antelopejs/dms 0.7.19 → 0.7.21

package/frontend-vue/tests/table-view-record-link.test.ts

@@ -0,0 +1,207 @@
+// @vitest-environment jsdom
+/**
+ * A table with a `deepLink` action opens the row `?record=` names on arrival
+ * and on each visit that keeps the page mounted, including a link to a row
+ * closed meanwhile: the table removes the key in place, so the route still
+ * holds the same value and only the visit tells the link was followed again.
+ */
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { createApp, defineComponent, h, nextTick, reactive } from "vue";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import type { CustomRowAction } from "../layers/dms-ui/app/types/row-action";
+import type { DeepLinkedRow } from "../layers/dms-ui/app/build/composables/table-view/utils/recordLink";
+import {
+  clearWrittenRecord,
+  writeRecordId,
+} from "../layers/dms-ui/app/build/composables/table-view/utils/recordLink";
+import {
+  currentQuery,
+  withoutQueryParam,
+} from "../layers/dms-ui/app/build/composables/table-view/utils/urlFilters";
+
+type NavigateListener = (event: { detail: { page: { url: string } } }) => void;
+const navigateListeners = new Set<NavigateListener>();
+
+vi.mock("@inertiajs/vue3", () => ({
+  router: {
+    on: (type: string, listener: NavigateListener) => {
+      if (type !== "navigate") return () => {};
+      navigateListeners.add(listener);
+      return () => navigateListeners.delete(listener);
+    },
+  },
+}));
+
+const { useTableRecordLink } = await import(
+  "../layers/dms-ui/app/build/composables/table-view/useTableRecordLink"
+);
+
+interface Row {
+  id: string;
+}
+
+const ROWS: Row[] = [{ id: "r1" }, { id: "r2" }];
+const SCOPE = { tableId: "sends", isSoleTableView: true };
+const DRAWER = {
+  id: "details",
+  deepLink: true,
+  target: { type: "drawer" },
+} as unknown as CustomRowAction;
+
+const mounted: Array<{ unmount: () => void }> = [];
+
+const flush = () => new Promise<void>((done) => setTimeout(done));
+
+/** A visit of the page: Inertia pushes its URL, then announces it. */
+async function visit(route: { query: Record<string, unknown> }, url: string) {
+  window.history.pushState({}, "", url);
+  route.query = Object.fromEntries(new URL(url, "http://x").searchParams);
+  await nextTick();
+  navigateListeners.forEach((listener) =>
+    listener({ detail: { page: { url } } }),
+  );
+  await flush();
+}
+
+function mountTable(url: string) {
+  window.history.replaceState({}, "", url);
+  const route = reactive({
+    query: Object.fromEntries(new URL(url, "http://x").searchParams) as Record<
+      string,
+      unknown
+    >,
+  });
+  const opened: string[] = [];
+  const notify = vi.fn();
+  let link: { shown: (id?: string) => void } | undefined;
+  const app = createApp(
+    defineComponent({
+      setup() {
+        link = useTableRecordLink<Row>({
+          route,
+          urlScope: SCOPE,
+          action: DRAWER,
+          resolve: async (id): Promise<DeepLinkedRow<Row>> => {
+            const row = ROWS.find((candidate) => candidate.id === id);
+            return row ? { row, isMissing: false } : { isMissing: true };
+          },
+          // The drawer writes the row it opens, as the action's targets do.
+          open: (row) => {
+            opened.push(row.id);
+            writeRecordId(SCOPE, row.id);
+            link?.shown(row.id);
+          },
+          showMissing: () => {},
+          notify,
+        });
+        return () => h("div");
+      },
+    }),
+  );
+  app.mount(document.createElement("div"));
+  mounted.push(app);
+  // Closing the drawer removes the row from the URL in place.
+  const close = () => {
+    writeRecordId(SCOPE);
+    link?.shown(undefined);
+  };
+  return { route, opened, notify, close };
+}
+
+beforeEach(() => navigateListeners.clear());
+
+afterEach(() => {
+  mounted.splice(0).forEach((app) => app.unmount());
+  window.history.replaceState({}, "", "/");
+});
+
+describe("a record link on a mounted table", () => {
+  it("opens the row a link names on arrival, once", async () => {
+    const { route, opened } = mountTable("/sends?record=r1");
+    await flush();
+    // The visit that mounted the table is announced after it mounted.
+    navigateListeners.forEach((listener) =>
+      listener({ detail: { page: { url: "/sends?record=r1" } } }),
+    );
+    await flush();
+    expect(opened).toEqual(["r1"]);
+    expect(route.query.record).toBe("r1");
+  });
+
+  it("opens the row a visit to the same page names", async () => {
+    const { route, opened } = mountTable("/sends?record=r1");
+    await flush();
+    await visit(route, "/sends?record=r2");
+    expect(opened).toEqual(["r1", "r2"]);
+    expect(window.location.search).toBe("?record=r2");
+  });
+
+  it("opens the same row again after its drawer closed", async () => {
+    const { route, opened, close } = mountTable("/sends?record=r1");
+    await flush();
+    // A link to the row shown opens nothing more.
+    await visit(route, "/sends?record=r1");
+    expect(opened).toEqual(["r1"]);
+
+    close();
+    expect(window.location.search).toBe("");
+    await visit(route, "/sends?record=r1");
+    expect(opened).toEqual(["r1", "r1"]);
+  });
+
+  it("tells the user a link names no row and removes the key", async () => {
+    const { route, opened, notify } = mountTable("/sends?tab=all&record=gone");
+    await flush();
+    expect(opened).toEqual([]);
+    expect(notify).toHaveBeenCalledWith("notify");
+    expect(window.location.search).toBe("?tab=all");
+
+    // Following the same link again tells it again.
+    await visit(route, "/sends?tab=all&record=gone");
+    expect(notify).toHaveBeenCalledTimes(2);
+  });
+
+  it("stops following visits once unmounted", async () => {
+    const { route, opened } = mountTable("/sends");
+    mounted.splice(0).forEach((app) => app.unmount());
+    await visit(route, "/sends?record=r2");
+    expect(opened).toEqual([]);
+  });
+});
+
+describe("the URL a closed drawer leaves", () => {
+  it("removes only the row this drawer wrote, and says so", () => {
+    window.history.replaceState({}, "", "/sends");
+    const written = writeRecordId(SCOPE, "r1");
+    writeRecordId(SCOPE, "r2");
+    expect(clearWrittenRecord(written)).toBe(false);
+    expect(window.location.search).toBe("?record=r2");
+    expect(clearWrittenRecord(writeRecordId(SCOPE, "r2"))).toBe(true);
+    expect(window.location.search).toBe("");
+  });
+
+  it("rebuilds a removed filter's visit from the URL the browser shows", () => {
+    window.history.replaceState({}, "", "/sends?email=a%40b.test&tab=all");
+    // The route still holds the row of the drawer closed in place.
+    const routeQuery = { email: "a@b.test", tab: "all", record: "r1" };
+    expect(withoutQueryParam(currentQuery(routeQuery), "email")).toEqual({
+      tab: "all",
+    });
+  });
+});
+
+it("wires the record link and the filter chips into the table view", () => {
+  const source = readFileSync(
+    resolve(
+      __dirname,
+      "../layers/dms-ui/app/components/table-view/TableView.vue",
+    ),
+    "utf8",
+  );
+  expect(source).toContain("useTableRecordLink<T>({");
+  expect(source).toContain("onRecordShown: (id) => recordLink?.shown(id),");
+  expect(source).toContain(
+    "withoutQueryParam(currentQuery(route.query), param)",
+  );
+});

package/frontend-vue/tests/table-view-url-tab.test.ts

@@ -3,18 +3,32 @@
  * A table view opens the tab its URL names (`?<tableId>.tab=`, or `?tab=` on
  * a page with a single table view), on arrival and afterwards: a link or a
  * `router.replace` naming another tab switches to it in place, without
- * remounting the page.
+ * remounting the page. A tab the user opens is written back to the URL in
+ * place, under the same key.
  */
 import { readFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { createApp, defineComponent, h, nextTick, reactive, ref } from "vue";
-import { afterEach, describe, expect, it } from "vitest";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import {
   readTableUrlTab,
   useTableUrlTab,
 } from "../layers/dms-ui/app/build/composables/table-view/useTableUrlTab";
 import type { TableUrlScope } from "../layers/dms-ui/app/build/composables/table-view/utils/views";
 
+type NavigateListener = (event: { detail: { page: { url: string } } }) => void;
+const navigateListeners = new Set<NavigateListener>();
+
+vi.mock("@inertiajs/vue3", () => ({
+  router: {
+    on: (type: string, listener: NavigateListener) => {
+      if (type !== "navigate") return () => {};
+      navigateListeners.add(listener);
+      return () => navigateListeners.delete(listener);
+    },
+  },
+}));
+
 const OPENABLE_TABS = new Set(["all", "active", "archived"]);
 const mounted: Array<{ unmount: () => void }> = [];
 
@@ -39,10 +53,23 @@ function mountTable(scope: TableUrlScope, query: Record<string, string>) {
   return { route, activeTabId };
 }
 
+beforeEach(() => {
+  window.history.replaceState(null, "", "/runs");
+});
+
 afterEach(() => {
   mounted.splice(0).forEach((app) => app.unmount());
 });
 
+/** A visit of the page already shown: Inertia announces its URL. */
+async function visit(url: string) {
+  window.history.pushState(null, "", url);
+  navigateListeners.forEach((listener) =>
+    listener({ detail: { page: { url } } }),
+  );
+  await nextTick();
+}
+
 describe("the tab a URL names", () => {
   it("opens on arrival", () => {
     const { activeTabId } = mountTable(
@@ -102,6 +129,61 @@ describe("the tab a URL names", () => {
   });
 });
 
+describe("the tab the user opens", () => {
+  it("is written to the short key in place on a single table view", async () => {
+    window.history.replaceState(null, "", "/runs?page=2");
+    const { activeTabId } = mountTable(
+      { tableId: "runs", isSoleTableView: true },
+      {},
+    );
+    const entries = window.history.length;
+    activeTabId.value = "archived";
+    await nextTick();
+    expect(window.location.search).toBe("?page=2&tab=archived");
+    expect(window.history.length).toBe(entries);
+    activeTabId.value = "all";
+    await nextTick();
+    expect(window.location.search).toBe("?page=2&tab=all");
+  });
+
+  it("is written to the table's own key on a page with several tables", async () => {
+    window.history.replaceState(null, "", "/runs?jobs.tab=late");
+    const { activeTabId } = mountTable({ tableId: "runs" }, {});
+    activeTabId.value = "active";
+    await nextTick();
+    expect(window.location.search).toBe("?jobs.tab=late&runs.tab=active");
+  });
+
+  it("leaves the URL alone for a tab it cannot open in place", async () => {
+    const { activeTabId } = mountTable({ tableId: "runs" }, {});
+    activeTabId.value = "docs";
+    await nextTick();
+    expect(window.location.search).toBe("");
+  });
+
+  it("gives way to a link back to the tab the page was opened on", async () => {
+    window.history.replaceState(null, "", "/runs?runs.tab=active");
+    const { route, activeTabId } = mountTable(
+      { tableId: "runs" },
+      { "runs.tab": "active" },
+    );
+    activeTabId.value = "archived";
+    await nextTick();
+    expect(window.location.search).toBe("?runs.tab=archived");
+    // The route still holds the arrival's tab: only the visit tells.
+    await visit("/runs?runs.tab=active");
+    expect(route.query["runs.tab"]).toBe("active");
+    expect(activeTabId.value).toBe("active");
+  });
+
+  it("stops following visits once the table is gone", async () => {
+    const { activeTabId } = mountTable({ tableId: "runs" }, {});
+    mounted.splice(0).forEach((app) => app.unmount());
+    await visit("/runs?runs.tab=archived");
+    expect(activeTabId.value).toBe("all");
+  });
+});
+
 it("wires the URL tab into the table view", () => {
   const source = readFileSync(
     resolve(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@antelopejs/dms",
-  "version": "0.7.19",
+  "version": "0.7.21",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/AntelopeJS/dms.git"
@@ -37,7 +37,7 @@
     "@antelopejs/interface-data-api": ">=0.2.0 <1.0.0",
     "@antelopejs/interface-database": ">=0.1.8 <1.0.0",
     "@antelopejs/interface-database-decorators": ">=0.1.7 <1.0.0",
-    "@antelopejs/interface-dms": ">=0.5.12 <0.6.0",
+    "@antelopejs/interface-dms": ">=0.5.13 <0.6.0",
     "@antelopejs/interface-email": ">=0.0.5 <1.0.0",
     "@antelopejs/interface-file-storage": ">=0.1.3 <1.0.0",
     "archiver": "^7.0.1",