@antelopejs/dms 0.7.7 → 0.7.9

package/frontend-vue/layers/dms-ui/app/utils/blockRefresh.ts

@@ -5,6 +5,12 @@
  */
 export const BLOCK_REFRESH_EVENT = "DmsComponent.Block.Refresh";
 
+/**
+ * The window event of a refresh nobody asked for (a timer, a feed): on a page
+ * declared with `live` it goes through the Direct / Pause gate.
+ */
+export const LIVE_BLOCK_REFRESH_EVENT = "DmsComponent.Block.LiveRefresh";
+
 /** The watch functions every block can name (see interface-dms). */
 export const BlockFunctions = {
   REFRESH_PAGE: "DmsComponent.Block.RefreshPage",
@@ -12,17 +18,49 @@ export const BlockFunctions = {
 
 /**
  * Asks every data block mounted on the page to read its data again: what a
- * component calls once an action of its own changed the record the page
- * shows. The page header calls it after a button changed something.
+ * component calls once an action of the user changed the record the page
+ * shows. The page header calls it after a button changed something, a form
+ * through `BlockFunctions.REFRESH_PAGE` once it saved. A user action always
+ * refreshes: on a page declared with `live` it reads even while paused, and
+ * the blocks it reads no longer count what they had missed.
  */
 export function refreshPageBlocks(): void {
   if (typeof window === "undefined") return;
   window.dispatchEvent(new CustomEvent(BLOCK_REFRESH_EVENT));
 }
 
-/** Calls `handler` on each `refreshPageBlocks()`; returns the unsubscribe. */
-export function onPageBlocksRefresh(handler: () => void): () => void {
+/**
+ * Asks every data block mounted on the page to read its data again because
+ * time passed or a feed moved, not because the user did something: on a page
+ * declared with `live` it goes through the page's Direct / Pause gate like a
+ * realtime event — capped by `maxRate` in Direct, counted while paused and
+ * read once on resume. Without `live`, it is `refreshPageBlocks()`.
+ */
+export function refreshLivePageBlocks(): void {
+  if (typeof window === "undefined") return;
+  window.dispatchEvent(new CustomEvent(LIVE_BLOCK_REFRESH_EVENT));
+}
+
+/**
+ * Calls `handler` on each `refreshPageBlocks()`; returns the unsubscribe. Every
+ * handler receives the same event for one call, which tells one refresh
+ * reaching several blocks from several refreshes.
+ */
+export function onPageBlocksRefresh(
+  handler: (event: Event) => void,
+): () => void {
+  return listen(BLOCK_REFRESH_EVENT, handler);
+}
+
+/** Calls `handler` on each `refreshLivePageBlocks()`; returns the unsubscribe. */
+export function onLivePageBlocksRefresh(
+  handler: (event: Event) => void,
+): () => void {
+  return listen(LIVE_BLOCK_REFRESH_EVENT, handler);
+}
+
+function listen(name: string, handler: (event: Event) => void): () => void {
   if (typeof window === "undefined") return () => {};
-  window.addEventListener(BLOCK_REFRESH_EVENT, handler);
-  return () => window.removeEventListener(BLOCK_REFRESH_EVENT, handler);
+  window.addEventListener(name, handler);
+  return () => window.removeEventListener(name, handler);
 }

package/frontend-vue/layers/dms-ui/app/utils/componentId.ts

@@ -0,0 +1,21 @@
+// A page's top-level block is identified by its key; a block nested in a
+// layout block (a Grid, a GridRow) by its parent's id, this separator, then
+// its own key.
+const CHILD_SEPARATOR = "-child-";
+
+/** The component id of the child `key` of the block `parentId`. */
+export function childComponentId(parentId: string, key: string): string {
+  return `${parentId}${CHILD_SEPARATOR}${key}`;
+}
+
+/**
+ * The component id of the block `key` declared next to the block
+ * `componentId`, under the same parent: a custom block reaching the form
+ * beside it (its `FIELD_CHANGE` events) without parsing ids.
+ */
+export function siblingComponentId(componentId: string, key: string): string {
+  const nested = componentId.lastIndexOf(CHILD_SEPARATOR);
+  return nested >= 0
+    ? childComponentId(componentId.slice(0, nested), key)
+    : key;
+}

package/frontend-vue/layers/dms-ui/app/utils/rowClickAction.ts

@@ -46,3 +46,15 @@ export const resolveRowClickAction = (
   if (isEnabledForRow(rowActions?.details, row)) return "details";
   return undefined;
 };
+
+/**
+ * The custom row actions `row` offers: those whose `rule` accepts it, in
+ * their declared order (a card's own menu, `actions.customFor`).
+ */
+export const rowCustomActions = (
+  custom: CustomRowAction[] | undefined,
+  row: Record<string, unknown>,
+): CustomRowAction[] =>
+  (custom ?? []).filter(
+    (action) => !action.rule || evaluateRowActionRule(action.rule, row),
+  );

package/frontend-vue/layers/dms-ui/i18n/locales/ui-en-GB.json

@@ -469,6 +469,19 @@
         "delete": {
           "description": "Delete hovered row",
           "condition": "Only when enableRowDelete is enabled"
+        },
+        "j": {
+          "description": "Next row"
+        },
+        "k": {
+          "description": "Previous row"
+        },
+        "row_open": {
+          "condition": "While a row is open in a side panel, a drawer or a modal, outside a text field"
+        },
+        "panel_escape": {
+          "description": "Close the row side panel",
+          "condition": "While a row is open in a side panel, once the table has no search or selection to clear"
         }
       },
       "tab": {
@@ -492,6 +505,11 @@
         "escape": {
           "description": "Close dialogs, menus and the palette"
         }
+      },
+      "livetoggle": {
+        "l": {
+          "description": "Switch the page between Direct and Pause"
+        }
       }
     },
     "notifications": {
@@ -709,6 +727,16 @@
     "action_error": {
       "forbidden": "You don’t have permission to do this.",
       "generic": "Something went wrong and the action couldn’t be completed. Try again."
+    },
+    "live": {
+      "direct": "Direct",
+      "pause": "Pause",
+      "aria_label": "Live updates",
+      "updated_seconds": "Updated {count} s ago",
+      "updated_minutes": "Updated {count} min ago",
+      "updated_hours": "Updated {count} h ago",
+      "new_rows": "{count} new",
+      "show_new": "Show"
     }
   }
 }

package/frontend-vue/layers/dms-ui/i18n/locales/ui-fr-FR.json

@@ -470,6 +470,19 @@
         "delete": {
           "description": "Supprimer la ligne survolée",
           "condition": "Uniquement quand enableRowDelete est activé"
+        },
+        "j": {
+          "description": "Ligne suivante"
+        },
+        "k": {
+          "description": "Ligne précédente"
+        },
+        "row_open": {
+          "condition": "Quand une ligne est ouverte dans un panneau latéral, un tiroir ou une fenêtre, hors d'un champ de saisie"
+        },
+        "panel_escape": {
+          "description": "Fermer le panneau latéral de la ligne",
+          "condition": "Quand une ligne est ouverte dans un panneau latéral, une fois que la table n'a plus de recherche ni de sélection à effacer"
         }
       },
       "tab": {
@@ -493,6 +506,11 @@
         "escape": {
           "description": "Fermer les dialogues, les menus et la palette"
         }
+      },
+      "livetoggle": {
+        "l": {
+          "description": "Basculer la page entre Direct et Pause"
+        }
       }
     },
     "notifications": {
@@ -710,6 +728,16 @@
     "action_error": {
       "forbidden": "Vous n’avez pas l’autorisation d’effectuer cette action.",
       "generic": "Une erreur est survenue et l’action n’a pas pu aboutir. Réessayez."
+    },
+    "live": {
+      "direct": "Direct",
+      "pause": "Pause",
+      "aria_label": "Mises à jour en direct",
+      "updated_seconds": "Mis à jour il y a {count} s",
+      "updated_minutes": "Mis à jour il y a {count} min",
+      "updated_hours": "Mis à jour il y a {count} h",
+      "new_rows": "{count} nouvelle | {count} nouvelles",
+      "show_new": "Afficher"
     }
   }
 }

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

@@ -0,0 +1,74 @@
+// @vitest-environment jsdom
+/**
+ * A chart on a paused live page sends no request on its events or on a page
+ * refresh, and reads once when the page resumes.
+ */
+import { createApp, defineComponent, h, ref } from "vue";
+import { afterEach, expect, it, vi } from "vitest";
+import {
+  refreshLivePageBlocks,
+  refreshPageBlocks,
+} from "../layers/dms-ui/app/utils/blockRefresh";
+import { createPageLiveController } from "../layers/dms-ui/app/build/composables/live/pageLiveController";
+import { setCurrentPageLive } from "../layers/dms-ui/app/build/composables/live/currentPageLive";
+
+const requests: string[] = [];
+
+vi.stubGlobal("useAuthFetch", () => ({
+  $authFetch: async (url: string) => {
+    requests.push(url);
+    return { value: requests.length };
+  },
+}));
+vi.stubGlobal("useDmsRoute", () => ({ query: {} }));
+vi.stubGlobal("ref", ref);
+
+const { useChartFetch } = await import(
+  "../layers/dms-ui/app/composables/chart/useChartFetch"
+);
+
+// useChartFetch debounces every refresh past the first by 180ms.
+const SETTLE_MS = 250;
+const settle = () => new Promise((resolve) => setTimeout(resolve, SETTLE_MS));
+
+const apps: Array<() => void> = [];
+
+afterEach(() => {
+  apps.splice(0).forEach((unmount) => unmount());
+  setCurrentPageLive(null);
+  window.localStorage.clear();
+});
+
+it("requests nothing while paused and reads once on resume", async () => {
+  const live = createPageLiveController("api.overview", {});
+  setCurrentPageLive(live);
+  const app = createApp(
+    defineComponent({
+      setup() {
+        useChartFetch<{ value: number }>({ fetchUrl: "/api/overview/chart" });
+        return () => h("div");
+      },
+    }),
+  );
+  app.mount(document.createElement("div"));
+  apps.push(() => app.unmount());
+  await settle();
+  expect(requests).toHaveLength(1);
+
+  live.pause();
+  refreshLivePageBlocks();
+  refreshLivePageBlocks();
+  await settle();
+  expect(requests).toHaveLength(1);
+
+  live.resume();
+  await settle();
+  expect(requests).toHaveLength(2);
+
+  // An action of the user refreshes even while paused.
+  live.pause();
+  refreshPageBlocks();
+  await settle();
+  expect(requests).toHaveLength(3);
+  live.dispose();
+});

package/frontend-vue/tests/component-id.test.ts

@@ -0,0 +1,18 @@
+import { describe, expect, it } from "vitest";
+import {
+  childComponentId,
+  siblingComponentId,
+} from "../layers/dms-ui/app/utils/componentId";
+
+describe("siblingComponentId", () => {
+  it("names a top-level block's neighbour by its key", () => {
+    expect(siblingComponentId("preview", "form")).toBe("form");
+  });
+
+  it("names a nested block's neighbour under the same parent", () => {
+    const row = childComponentId("editor", "row");
+    expect(siblingComponentId(childComponentId(row, "preview"), "form")).toBe(
+      "editor-child-row-child-form",
+    );
+  });
+});

package/frontend-vue/tests/field-row.test.ts

@@ -74,6 +74,20 @@ describe("FieldRow", () => {
     expect(body().className).toContain("py-4");
   });
 
+  it("spans both form columns with its control when it has no label", async () => {
+    await mount({ layout: "form" }, { default: () => h("input") });
+    expect(body().children).toHaveLength(1);
+    expect(body().firstElementChild!.className).toContain("col-span-full");
+  });
+
+  it("keeps a labelled control in the form's control column", async () => {
+    await mount(
+      { label: "Name", layout: "form" },
+      { default: () => h("input") },
+    );
+    expect(body().lastElementChild!.className).not.toContain("col-span-full");
+  });
+
   it("leaves the spacing to the list of a stacked form", async () => {
     await mount({
       label: "Name",

package/frontend-vue/tests/live-hold-banner.test.ts

@@ -0,0 +1,37 @@
+// @vitest-environment jsdom
+/**
+ * The strip of a held table: "N new · Show", Show reading the rows again.
+ */
+import { createApp, h, type App } from "vue";
+import { afterEach, expect, it, vi } from "vitest";
+
+let app: App | undefined;
+
+afterEach(() => {
+  app?.unmount();
+  vi.unstubAllGlobals();
+});
+
+it("draws the banner and reads the rows on Show", async () => {
+  vi.stubGlobal("useI18n", () => ({
+    t: (key: string, params?: { count?: number }) =>
+      params ? `${key}:${params.count}` : key,
+  }));
+  const { default: LiveHoldBanner } = await import(
+    "../layers/dms-ui/app/build/components/table-view/LiveHoldBanner.vue"
+  );
+  const onShow = vi.fn();
+  const host = document.createElement("div");
+  app = createApp({
+    render: () => h(LiveHoldBanner, { count: 3, onShow }),
+  });
+  app.component("UIcon", () => h("i"));
+  app.component("UButton", (props: { label: string }, { attrs }) =>
+    h("button", attrs, props.label),
+  );
+  app.mount(host);
+
+  expect(host.textContent).toContain("dms.live.new_rows:3");
+  host.querySelector("button")?.click();
+  expect(onShow).toHaveBeenCalledTimes(1);
+});

package/frontend-vue/tests/live-toggle.test.ts

@@ -0,0 +1,162 @@
+// @vitest-environment jsdom
+/**
+ * The LiveToggle block: Direct / Pause as a two-segment toggle, "updated N s
+ * ago" counted every second in the browser, L switching the page outside a
+ * text field, and nothing at all on a page without `live`.
+ */
+import { createApp, h, nextTick, type App } from "vue";
+import { afterEach, beforeEach, expect, it, vi } from "vitest";
+import { defineShortcuts } from "@nuxt/ui/runtime/composables/defineShortcuts.js";
+import {
+  createPageLiveController,
+  type PageLiveController,
+} from "../layers/dms-ui/app/build/composables/live/pageLiveController";
+import { setCurrentPageLive } from "../layers/dms-ui/app/build/composables/live/currentPageLive";
+import { formatElapsed } from "../layers/dms-ui/app/build/composables/live/formatElapsed";
+
+let app: App | undefined;
+let host: HTMLDivElement;
+let live: PageLiveController | undefined;
+
+const t = (key: string, params?: { count?: number }) =>
+  params?.count === undefined ? key : `${key}:${params.count}`;
+
+async function createToggle(
+  target: HTMLElement,
+  props: Record<string, unknown> = {},
+): Promise<App> {
+  const { default: LiveToggleBlock } = await import(
+    "../layers/dms-ui/app/components/blocks/LiveToggleBlock.vue"
+  );
+  const toggle = createApp({
+    render: () =>
+      h(LiveToggleBlock, { componentId: "live", pageId: "api.logs", ...props }),
+  });
+  toggle.component("UIcon", () => h("i"));
+  toggle.mount(target);
+  await nextTick();
+  return toggle;
+}
+
+async function mountToggle(props: Record<string, unknown> = {}) {
+  app = await createToggle(host, props);
+}
+
+const segment = (value: string) =>
+  host.querySelector<HTMLButtonElement>(
+    `[role="radio"][data-value="${value}"]`,
+  ) ??
+  [...host.querySelectorAll<HTMLButtonElement>('[role="radio"]')].find(
+    (button) => button.textContent?.includes(`dms.live.${value}`),
+  );
+
+const pressL = (target: EventTarget = document) =>
+  target.dispatchEvent(
+    new KeyboardEvent("keydown", { key: "l", bubbles: true }),
+  );
+
+beforeEach(() => {
+  vi.useFakeTimers();
+  vi.stubGlobal("useI18n", () => ({ t }));
+  vi.stubGlobal("defineShortcuts", defineShortcuts);
+  host = document.createElement("div");
+  document.body.append(host);
+  window.localStorage.clear();
+});
+
+afterEach(() => {
+  app?.unmount();
+  app = undefined;
+  host.remove();
+  live?.dispose();
+  live = undefined;
+  setCurrentPageLive(null);
+  vi.unstubAllGlobals();
+  vi.useRealTimers();
+});
+
+function installLive() {
+  live = createPageLiveController("api.logs", { maxRate: 2 });
+  setCurrentPageLive(live);
+  return live;
+}
+
+it("renders nothing on a page without live", async () => {
+  await mountToggle();
+  expect(host.querySelector(".dms-live-toggle")).toBeNull();
+});
+
+it("shows the page's state and switches it", async () => {
+  const controller = installLive();
+  await mountToggle();
+  expect(segment("direct")?.getAttribute("aria-checked")).toBe("true");
+
+  segment("pause")?.click();
+  await nextTick();
+  expect(controller.isPaused.value).toBe(true);
+  expect(segment("pause")?.getAttribute("aria-checked")).toBe("true");
+
+  segment("direct")?.click();
+  await nextTick();
+  expect(controller.isPaused.value).toBe(false);
+});
+
+it("counts the seconds since the last update, every second", async () => {
+  installLive();
+  await mountToggle();
+  expect(host.textContent).toContain("dms.live.updated_seconds:0");
+
+  vi.advanceTimersByTime(3000);
+  await nextTick();
+  expect(host.textContent).toContain("dms.live.updated_seconds:3");
+
+  vi.advanceTimersByTime(60_000);
+  await nextTick();
+  expect(host.textContent).toContain("dms.live.updated_minutes:1");
+});
+
+it("hides the time when asked to", async () => {
+  installLive();
+  await mountToggle({ showUpdatedAt: false });
+  expect(host.textContent).not.toContain("dms.live.updated");
+});
+
+it("switches on L, but not while typing", async () => {
+  const controller = installLive();
+  await mountToggle();
+
+  pressL();
+  expect(controller.isPaused.value).toBe(true);
+  pressL();
+  expect(controller.isPaused.value).toBe(false);
+
+  const field = document.createElement("input");
+  document.body.append(field);
+  field.focus();
+  await nextTick();
+  pressL(field);
+  expect(controller.isPaused.value).toBe(false);
+  field.remove();
+});
+
+it("reads elapsed times in seconds, minutes, then hours", () => {
+  expect(formatElapsed(-5)).toEqual({ unit: "seconds", count: 0 });
+  expect(formatElapsed(59_999)).toEqual({ unit: "seconds", count: 59 });
+  expect(formatElapsed(60_000)).toEqual({ unit: "minutes", count: 1 });
+  expect(formatElapsed(2 * 3_600_000 + 1)).toEqual({ unit: "hours", count: 2 });
+});
+
+it("switches once per L with two toggles on the page", async () => {
+  const controller = installLive();
+  await mountToggle();
+  const second = await createToggle(document.createElement("div"));
+
+  pressL();
+  expect(controller.isPaused.value).toBe(true);
+
+  app?.unmount();
+  app = undefined;
+  pressL();
+  expect(controller.isPaused.value).toBe(false);
+  second.unmount();
+});