@antelopejs/dms 0.7.18 → 0.7.20

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## v0.7.20
+
+[compare changes](https://github.com/AntelopeJS/dms/compare/v0.7.19...v0.7.20)
+
+### 🩹 Fixes
+
+- **table-view:** Reopen a record link to a closed row and keep chips from restoring it ([#249](https://github.com/AntelopeJS/dms/pull/249))
+
+### ❤️ Contributors
+
+- Antony Rizzitelli <rizzitelli.antony@pm.me>
+
+## v0.7.19
+
+[compare changes](https://github.com/AntelopeJS/dms/compare/v0.7.18...v0.7.19)
+
 ## v0.7.18
 
 [compare changes](https://github.com/AntelopeJS/dms/compare/v0.7.17...v0.7.18)

package/frontend-vue/layers/dms-ui/app/build/composables/actions/useActionTargets.ts

@@ -110,6 +110,11 @@ export interface ActionTargetsConfig {
   rowNavigation?: RowNavigationSource;
   /** Where a `deepLink` action writes the row it has open in the URL. */
   recordScope?: TableUrlScope;
+  /**
+   * Told the row a `deepLink` action shows each time it writes it in the URL,
+   * and `undefined` once its container closed and removed it.
+   */
+  onRecordShown?: (id?: string) => void;
   /**
    * The field a row's id is read from (`_id` by default): it fills `{id}` in
    * the `from` URL of a row action's confirmation, as on a built-in action.
@@ -326,11 +331,12 @@ export function useActionTargets(config: ActionTargetsConfig) {
     return (id?: string): void => {
       if (!deepLink || !config.recordScope || !config.rowNavigation) return;
       if (!id) {
-        clearWrittenRecord(written);
+        if (clearWrittenRecord(written)) config.onRecordShown?.(undefined);
         written = undefined;
         return;
       }
       written = writeRecordId(config.recordScope, id);
+      config.onRecordShown?.(id);
     };
   };
   const rowRecorder = (deepLink?: boolean) => {

package/frontend-vue/layers/dms-ui/app/build/composables/table-view/useTableRecordLink.ts

@@ -0,0 +1,93 @@
+import { router as inertiaRouter } from "@inertiajs/vue3";
+import { onBeforeUnmount, onMounted, watch } from "vue";
+import type { CustomRowAction } from "../../../types/row-action";
+import {
+  deepLinkOutcome,
+  type DeepLinkedRow,
+  readRecordId,
+  writeRecordId,
+} from "./utils/recordLink";
+import { queryOfUrl } from "./utils/urlFilters";
+import type { TableUrlScope } from "./utils/views";
+
+/** What `useTableRecordLink` follows the URL's `?record=` with. */
+export interface TableRecordLinkOptions<T> {
+  route: { query: Record<string, unknown> };
+  urlScope: TableUrlScope;
+  /** The table's `deepLink` action: the container a link opens. */
+  action: CustomRowAction;
+  /** Finds the row a link names, once the list is loaded. */
+  resolve: (id: string) => Promise<DeepLinkedRow<T>>;
+  /** Opens the row found in the action's container. */
+  open: (row: T) => void;
+  /** Opens a side panel's own "no longer available" state on the id. */
+  showMissing: (id: string) => void;
+  /** Tells the user the link led nowhere, or could not be followed. */
+  notify: (outcome: "notify" | "notifyFailed") => void;
+}
+
+/** What the table tells the link about the row its container shows. */
+export interface TableRecordLink {
+  /**
+   * The row the action's container shows, as written in the URL, or
+   * `undefined` once it closed: a link to the row shown opens nothing again,
+   * a link to a row closed reopens it.
+   */
+  shown: (id?: string) => void;
+}
+
+/**
+ * Opens the row the URL's `?record=` names: on arrival, and on each visit
+ * that keeps the page mounted (a link to the same page naming a row, back and
+ * forward), as a fresh load would. The visit is followed rather than the
+ * route's value: the table writes and removes the key in place, so a link to
+ * a row closed meanwhile leaves the route's value unchanged. A link naming no
+ * row removes the key and tells the user.
+ */
+export function useTableRecordLink<T>(
+  options: TableRecordLinkOptions<T>,
+): TableRecordLink {
+  const { action, urlScope } = options;
+  // The row opened or being opened: arrival and the visit that mounted the
+  // table name it twice, a visit while it is open names it again.
+  let linkedId: string | undefined;
+
+  const settle = async (id: string) => {
+    const found = await options.resolve(id);
+    const outcome = deepLinkOutcome(found, action);
+    if (outcome === "open") return options.open(found.row as T);
+    if (outcome === "missingPanel") return options.showMissing(id);
+    writeRecordId(urlScope);
+    if (linkedId === id) linkedId = undefined;
+    options.notify(outcome);
+  };
+
+  const follow = (query: Record<string, unknown>) => {
+    const id = readRecordId(query, urlScope);
+    if (!id || id === linkedId) return;
+    linkedId = id;
+    void settle(id);
+  };
+
+  let stopFollowingVisits: (() => void) | undefined;
+  onMounted(() => {
+    follow(options.route.query);
+    stopFollowingVisits = inertiaRouter.on("navigate", (event) =>
+      follow(queryOfUrl(event.detail.page.url)),
+    );
+  });
+  onBeforeUnmount(() => stopFollowingVisits?.());
+
+  // A visit Inertia does not announce (a `router.replace`) still moves the
+  // route: a new value there is followed as well.
+  watch(
+    () => readRecordId(options.route.query, urlScope),
+    () => follow(options.route.query),
+  );
+
+  return {
+    shown: (id) => {
+      linkedId = id;
+    },
+  };
+}

package/frontend-vue/layers/dms-ui/app/build/composables/table-view/useTableViewRowActions.ts

@@ -76,6 +76,8 @@ interface TableRowActionsConfig {
   rowNavigation?: RowNavigationSource;
   /** Where a `deepLink` action writes its open row in the URL. */
   recordScope?: TableUrlScope;
+  /** Told the row a `deepLink` action shows, `undefined` once closed. */
+  onRecordShown?: (id?: string) => void;
 }
 
 interface BulkActionConfig {
@@ -814,6 +816,7 @@ export const useTableRowActions = <T extends Data>(
     handleApiError,
     rowNavigation: config.rowNavigation,
     recordScope: config.recordScope,
+    onRecordShown: config.onRecordShown,
     rowIdKey: config.rowIdKey,
   });
 

package/frontend-vue/layers/dms-ui/app/build/composables/table-view/utils/recordLink.ts

@@ -58,15 +58,18 @@ export interface WrittenRecord {
 /**
  * Removes the row a table wrote in the URL, only while the URL still holds
  * it: a container closing as the user leaves the page must not erase the
- * `?record=` of the page reached.
+ * `?record=` of the page reached. Returns whether it removed it.
  */
-export function clearWrittenRecord(written: WrittenRecord | undefined): void {
-  if (typeof window === "undefined" || !written) return;
+export function clearWrittenRecord(
+  written: WrittenRecord | undefined,
+): boolean {
+  if (typeof window === "undefined" || !written) return false;
   const url = new URL(window.location.href);
-  if (url.pathname !== written.pathname) return;
-  if (url.searchParams.get(written.key) !== written.id) return;
+  if (url.pathname !== written.pathname) return false;
+  if (url.searchParams.get(written.key) !== written.id) return false;
   url.searchParams.delete(written.key);
   window.history.replaceState(window.history.state, "", url);
+  return true;
 }
 
 /** Where a deep link finds its row: among the rows listed, or by id. */

package/frontend-vue/layers/dms-ui/app/build/composables/table-view/utils/urlFilters.ts

@@ -27,3 +27,21 @@ export function withoutQueryParam<Query extends Record<string, unknown>>(
   const { [param]: _removed, ...rest } = query;
   return rest as Query;
 }
+
+/** The query of a URL, absolute or relative to the page, one value per key. */
+export function queryOfUrl(url: string): Record<string, string> {
+  return Object.fromEntries(new URL(url, "http://dms.invalid").searchParams);
+}
+
+/**
+ * The query the browser shows, else the route's on a server render. A table
+ * writes some keys in place (the open `?record=`, removed on close), so the
+ * route, which follows the last visit, can still hold a key the browser no
+ * longer shows: a visit rebuilt from it would bring the key back.
+ */
+export function currentQuery(
+  routeQuery: Record<string, unknown>,
+): Record<string, unknown> {
+  if (typeof window === "undefined") return routeQuery;
+  return queryOfUrl(window.location.href);
+}

package/frontend-vue/layers/dms-ui/app/components/table-view/TableView.vue

@@ -78,12 +78,8 @@ import { selectedRowIds } from "../../build/composables/table-view/utils/bulkAct
 import { isBulkAction } from "../../build/composables/actions/bulkSelection";
 import { selectionScopeKey } from "../../build/utils/selectionScope";
 import {
-  type DeepLinkOutcome,
-  deepLinkOutcome,
   isDeepLinkAction,
-  readRecordId,
   resolveDeepLinkedRow,
-  writeRecordId,
 } from "../../build/composables/table-view/utils/recordLink";
 import {
   rowSidePanelOwnerKey,
@@ -119,6 +115,7 @@ import type {
   TableViewSwitcherItem,
 } from "../../build/components/table/Table.vue";
 import {
+  currentQuery,
   visibleUrlFilters,
   withoutQueryParam,
 } from "../../build/composables/table-view/utils/urlFilters";
@@ -155,6 +152,7 @@ import {
   readTableUrlTab,
   useTableUrlTab,
 } from "../../build/composables/table-view/useTableUrlTab";
+import { useTableRecordLink } from "../../build/composables/table-view/useTableRecordLink";
 import TableViews, {
   type TableViewItem,
 } from "../../build/components/table/Views.vue";
@@ -411,9 +409,11 @@ const shownUrlFilters = computed<TableUrlFilter[]>(() =>
   visibleUrlFilters(queryParamFilters, route.query as Record<string, unknown>),
 );
 
+// Rebuilt from the URL the browser shows: a `?record=` a closed drawer
+// removed in place must not come back with the visit.
 const removeUrlFilter = (param: string) =>
   router.replace({
-    query: withoutQueryParam(route.query, param),
+    query: withoutQueryParam(currentQuery(route.query), param),
   });
 
 const routeParamHiddenFilters = computed<TableFilter[]>(() => {
@@ -1298,6 +1298,7 @@ const {
     rowIdKey: props.rowIdKey ?? ROW_ID_DEFAULT_KEY,
   },
   recordScope: urlScope,
+  onRecordShown: (id) => recordLink?.shown(id),
 });
 
 // Custom actions offered on the selection bar. "Select all N matching"
@@ -1704,59 +1705,40 @@ watch(rowSelect, (selection) => {
 const deepLinkAction = (tableProps.value.rowActions?.custom ?? []).find(
   isDeepLinkAction,
 );
-const openRecordFromUrl = async () => {
-  const id = deepLinkAction ? readRecordId(route.query, urlScope) : undefined;
-  if (!deepLinkAction || !id) return;
-  await until(isListLoading).toBe(false);
-  const { row, isMissing } = await resolveDeepLinkedRow(id, {
-    listed: shownResults.value ?? undefined,
-    idOf: getRowId,
-    getRow: tableRows.getRow,
-  });
-  const outcome = deepLinkOutcome({ row, isMissing }, deepLinkAction);
-  deepLinkOutcomes[outcome](deepLinkAction, id, row as Data);
-};
+const recordLink = deepLinkAction
+  ? useTableRecordLink<T>({
+      route,
+      urlScope,
+      action: deepLinkAction,
+      resolve: async (id) => {
+        await until(isListLoading).toBe(false);
+        return resolveDeepLinkedRow(id, {
+          listed: shownResults.value ?? undefined,
+          idOf: getRowId,
+          getRow: tableRows.getRow,
+        });
+      },
+      open: (row) => handleCustomRowAction(deepLinkAction, row as Data),
+      showMissing: (id) => handleMissingRow(deepLinkAction, id),
+      notify: (outcome) => toast.add(recordLinkToasts[outcome]()),
+    })
+  : undefined;
 
-const notifyUnresolvedRecordLink = () => {
-  writeRecordId(urlScope);
-  toast.add({
+const recordLinkToasts = {
+  notify: () => ({
     title: t("dms.record_link.not_found_title"),
     description: t("dms.record_link.not_found_description"),
     color: Color.warning,
     icon: "i-ph-link-break",
-  });
-};
-
-const notifyFailedRecordLink = () => {
-  writeRecordId(urlScope);
-  toast.add({
+  }),
+  notifyFailed: () => ({
     title: t("dms.record_link.failed_title"),
     description: t("dms.record_link.failed_description"),
     color: Color.error,
     icon: "i-ph-warning-circle",
-  });
-};
-
-const deepLinkOutcomes: Record<
-  DeepLinkOutcome,
-  (action: CustomRowAction, id: string, row: Data) => void
-> = {
-  open: (action, _id, row) => handleCustomRowAction(action, row),
-  missingPanel: (action, id) => handleMissingRow(action, id),
-  notify: notifyUnresolvedRecordLink,
-  notifyFailed: notifyFailedRecordLink,
+  }),
 };
 
-// A visit that keeps the page mounted (a link to the same page with another
-// `?record=`) opens the row it names, as a fresh load would. The table's own
-// writes replace the URL in place and never reach the route.
-watch(
-  () => readRecordId(route.query, urlScope),
-  (id, previous) => {
-    if (id && id !== previous) void openRecordFromUrl();
-  },
-);
-
 const selectedIds = computed(() => selectedRowIds(rowSelect.value));
 
 const isRowActionEnabled = (
@@ -2086,7 +2068,6 @@ const checkUrlParameter = () => {
 
 onMounted(() => {
   checkUrlParameter();
-  void openRecordFromUrl();
   void loadRelationQuickFilters();
   void refreshLinkTabCounts();
   // The registry is client-only; once hydrated, degrade to the table display if

package/frontend-vue/tests/table-view-bulk-drawer.test.ts

@@ -271,9 +271,11 @@ describe("action targets on a selection and on a listed row", () => {
   it("steps a row's drawer through the rows shown and keeps it in the URL", async () => {
     window.history.replaceState(null, "", "/runs");
     const rows = [{ _id: "r1" }, { _id: "r2" }];
+    const onRecordShown = vi.fn();
     const targets = mountTargets({
       rowNavigation: { rows: () => rows, rowIdKey: "_id" },
       recordScope: { tableId: "runs", isSoleTableView: true },
+      onRecordShown,
     });
     targets.handleCustomRowAction(
       {
@@ -306,6 +308,7 @@ describe("action targets on a selection and on a listed row", () => {
     await nextTick();
     await Promise.resolve();
     expect(window.location.search).toBe("");
+    expect(onRecordShown.mock.calls).toEqual([["r1"], ["r2"], [undefined]]);
     window.dispatchEvent(new KeyboardEvent("keydown", { key: "k" }));
     expect(drawer!.patches).toHaveLength(1);
   });

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@antelopejs/dms",
-  "version": "0.7.18",
+  "version": "0.7.20",
   "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.11 <0.6.0",
+    "@antelopejs/interface-dms": ">=0.5.12 <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",