@antelopejs/dms 0.7.6 → 0.7.8

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

@@ -8,7 +8,12 @@ import type {
   Table,
   VisibilityState,
 } from "@tanstack/vue-table";
-import { refDebounced, useActiveElement, watchDebounced } from "@vueuse/core";
+import {
+  refDebounced,
+  until,
+  useActiveElement,
+  watchDebounced,
+} from "@vueuse/core";
 import {
   QUICK_ACTION_BUTTON_KEY,
   QUICK_ACTION_COMPONENT_KEY,
@@ -71,7 +76,15 @@ import {
 import { selectedRowIds } from "../../build/composables/table-view/utils/bulkActions";
 import { isBulkAction } from "../../build/composables/actions/bulkSelection";
 import { selectionScopeKey } from "../../build/utils/selectionScope";
-import { readRecordId } from "../../build/composables/table-view/utils/recordLink";
+import {
+  isDeepLinkAction,
+  readRecordId,
+  resolveDeepLinkedRow,
+} from "../../build/composables/table-view/utils/recordLink";
+import {
+  rowSidePanelOwnerKey,
+  useRowSidePanelContent,
+} from "#dms-layout/app/build/composables/layout/rowSidePanel";
 import type { CustomRowAction } from "../../types/row-action";
 import {
   type QuickFilterItem,
@@ -110,6 +123,9 @@ import { useAccumulatedPages } from "../../build/composables/table-view/useAccum
 import { usePersistedPagination } from "../../build/composables/table-view/usePersistedPagination";
 import { useTableRows } from "../../build/composables/table-view/useTableRows";
 import { useRefreshTriggers } from "../../build/composables/blocks/useRefreshTriggers";
+import { useTableLiveHold } from "../../build/composables/table-view/useTableLiveHold";
+import { usePageLive } from "../../composables/live/usePageLive";
+import LiveHoldBanner from "../../build/components/table-view/LiveHoldBanner.vue";
 import { useTableReorder } from "../../build/composables/table-view/useTableReorder";
 import {
   groupedOptionsFor,
@@ -179,6 +195,8 @@ interface TableViewProps<T extends Data> extends TableViewConfig<T> {
   isSoleTableView?: boolean;
   /** Topics whose events make the table read its rows again. */
   realtimeTopic?: string | string[];
+  /** Keeps the rows while the live page is paused (backend `liveHold`). */
+  liveHold?: boolean;
 }
 
 const props = defineProps<TableViewProps<T>>();
@@ -801,6 +819,14 @@ const archiveQuery = computed(() =>
   archiveMode ? { showArchived: showArchived.value } : {},
 );
 
+// The gate is set up with the other refresh triggers below; the hold only
+// reads it once the table is on screen.
+const liveHold = useTableLiveHold({
+  isEnabled: !!props.liveHold,
+  isSource: tableRows.isSource,
+  gate: () => liveGate,
+});
+
 const { data, status, error, refresh } = await useTableListData<T>({
   componentId,
   pageId,
@@ -808,6 +834,7 @@ const { data, status, error, refresh } = await useTableListData<T>({
   query: queryRequest,
   archiveQuery,
   isSelfManaged: isActiveDisplaySelfManaged,
+  heldQuery: liveHold.heldQuery,
 });
 
 // Nothing listed yet (a client navigation paints before the first page
@@ -949,6 +976,7 @@ const { data: tabCountsData, refresh: refreshTabCounts } =
     rows: tableRows,
     queries: tabCountsQuery,
     archiveQuery,
+    heldQuery: liveHold.heldQuery,
   });
 
 const viewItems = computed<TableViewItem[]>(() =>
@@ -1125,8 +1153,19 @@ const refreshAll = async () => {
 
 // The rows can move without the table seeing it (a batch, a job, another
 // block's action): a topic of the backend or a page refresh reads them again,
-// keeping the current rows on screen until the answer lands.
-useRefreshTriggers(props.realtimeTopic, () => void refreshAll());
+// keeping the current rows on screen until the answer lands. On a live page
+// the row events below go through the same gate.
+const liveGate = useRefreshTriggers(
+  props.realtimeTopic,
+  () => void refreshAll(),
+);
+// What the user asks for (a row action, the refresh button, ⌘R, a display's
+// own action) reads at once, even while the live page is paused, and brings
+// a held table up to date.
+const refreshByUser = () => {
+  liveGate.acknowledge();
+  return refreshAll();
+};
 
 // "Preview as role": a link tab to a page the previewed role could not open
 // is drawn locked, one to a page it opens partially is drawn partially
@@ -1203,7 +1242,7 @@ const {
   caption,
   labelKey,
   rowIdKey: props.rowIdKey,
-  refreshCallback: refreshAll,
+  refreshCallback: refreshByUser,
   formComponents,
   formContainer,
   formPages,
@@ -1395,12 +1434,28 @@ const realtimeEventHandlers: Record<
   },
 };
 
+// On a live page a row event is one more event behind the table: in Direct
+// it reads the rows again (at most once per `maxRate`), paused it is counted
+// and the rows stay as they are. Rows gone elsewhere still leave a selection
+// the page shows moving.
+const { isEnabled: isPageLive, isPaused: isPagePaused } = usePageLive();
+const gateRowEvent = (type: string, ids: string[], event: object) => {
+  if (type === REALTIME_EVENT_TYPE.DELETED && !isPagePaused.value) {
+    deselectRows(ids);
+  }
+  liveGate.trigger(event);
+};
+
 useRealtimeTopic(realtimeRowTopic, (event) => {
   const payload = event as { type: string; payload?: { ids?: string[] } };
   const handler = realtimeEventHandlers[payload.type];
   if (!handler) return;
   const ids = payload.payload?.ids ?? [];
   if (ids.length === 0 && payload.type !== REALTIME_EVENT_TYPE.CREATED) return;
+  if (isPageLive.value) {
+    gateRowEvent(payload.type, ids, event);
+    return;
+  }
   void handler(ids);
 });
 
@@ -1599,20 +1654,36 @@ watch(rowSelect, (selection) => {
   if (Object.keys(selection).length === 0) allMatching.value = false;
 });
 
-// A deep-linked action reopens on the row the URL names, listed or not.
+// A deep-linked action reopens on the row the URL names, listed or not. A
+// list still loading is waited for first: a row it lists keeps its position
+// among the rows shown, and a source table without `fetchRowUrl` has no
+// route to read one row from.
 const deepLinkAction = (tableProps.value.rowActions?.custom ?? []).find(
-  (action) => action.deepLink,
+  isDeepLinkAction,
 );
 const openRecordFromUrl = async () => {
   const id = deepLinkAction ? readRecordId(route.query, urlScope) : undefined;
   if (!deepLinkAction || !id) return;
-  const listed = shownResults.value?.find((row) => getRowId(row) === id);
-  const row = listed ?? (await tableRows.getRow(id).catch(() => undefined));
+  await until(isListLoading).toBe(false);
+  const row = await resolveDeepLinkedRow(id, {
+    listed: shownResults.value ?? undefined,
+    idOf: getRowId,
+    getRow: tableRows.getRow,
+  });
   if (row) handleCustomRowAction(deepLinkAction, row as Data);
 };
 
 const selectedIds = computed(() => selectedRowIds(rowSelect.value));
 
+// The row a side panel has open, which the grid highlights.
+const rowSidePanel = useRowSidePanelContent();
+const rowSidePanelOwner = rowSidePanelOwnerKey(pageId!, componentId!);
+const openRowId = computed(() =>
+  rowSidePanel.value?.ownerKey === rowSidePanelOwner
+    ? rowSidePanel.value.rowKey
+    : undefined,
+);
+
 const isRowActionEnabled = (
   config: boolean | RowActionConfig | undefined,
   item: T,
@@ -1746,7 +1817,7 @@ const displayContext = computed(
     componentId,
     pageId,
     options: optionsForDisplay(activeDisplayId.value),
-    refresh: refreshAll,
+    refresh: refreshByUser,
     reorder: reorderState.value,
     table: displayTable.value,
   }),
@@ -1833,7 +1904,7 @@ onBeforeUnmount(() => unregisterQuickActionTarget?.());
 
 defineShortcuts(
   buildTableViewShortcuts({
-    refresh: refreshAll,
+    refresh: refreshByUser,
     tableProps,
     newRow: () => newRow(queryParamDefaults.value),
     globalFilter,
@@ -2004,8 +2075,9 @@ onMounted(() => {
     :bulk-actions="bulkCustomActions"
     v-model:all-matching="allMatching"
     :presence-by-row="presenceByRowFiltered"
+    :open-row-id="openRowId"
     @add="handleRowAdd"
-    @refresh="refreshAll"
+    @refresh="refreshByUser"
     @details="handleRowClick"
     @delete="(e) => deleteRows(e)"
     @archive="(e) => archiveRows(e)"
@@ -2016,6 +2088,12 @@ onMounted(() => {
     @duplicate="handleRowDuplicate"
     @edit="handleRowEdit"
   >
+    <template v-if="liveHold.newCount.value > 0" #notice>
+      <LiveHoldBanner
+        :count="liveHold.newCount.value"
+        @show="liveHold.showNew"
+      />
+    </template>
     <template v-if="hasViews" #views>
       <TableViews
         :items="viewItems"

package/frontend-vue/layers/dms-ui/app/composables/form/types/field.ts

@@ -54,7 +54,7 @@ export interface FormSection {
   label: string;
   description?: string;
   icon?: string;
-  /** Heading of the side navigation the section's entry sits under. */
+  /** Heading of the navigation (side list or chips) the section's entry sits under. */
   navGroup?: string;
   fieldIds: string[];
 }

package/frontend-vue/layers/dms-ui/app/composables/live/usePageLive.ts

@@ -0,0 +1,52 @@
+import { computed, type ComputedRef } from "vue";
+import { currentPageLive } from "../../build/composables/live/currentPageLive";
+
+/** The Direct / Pause state of the page on screen, for a module's component. */
+export interface PageLiveState {
+  /** The page declares `live`: it has a Direct / Pause state at all. */
+  isEnabled: ComputedRef<boolean>;
+  /** The page's data follows its events: Direct, or a page without `live`. */
+  isLive: ComputedRef<boolean>;
+  /** The page is paused: its blocks request nothing on their events. */
+  isPaused: ComputedRef<boolean>;
+  pause: () => void;
+  /** Leaves the pause: each block that missed an event refetches once. */
+  resume: () => void;
+  toggle: () => void;
+  /** When the page last read its data (ms since the epoch), `null` without `live`. */
+  lastUpdatedAt: ComputedRef<number | null>;
+  /** Distinct events the page received since the pause. */
+  missedCount: ComputedRef<number>;
+}
+
+/**
+ * Follows the Direct / Pause state of the page on screen (see the page option
+ * `live` and the `LiveToggle()` block), so a custom block stays in step with
+ * the built-in ones without reading the DOM: stop a client-side ticker while
+ * paused, show what was missed, offer its own switch.
+ *
+ * On a page without `live`, or while server-rendering, `isEnabled` is false,
+ * the page reads as live and never paused, and `pause` / `resume` do nothing.
+ *
+ * ```ts
+ * const { isPaused, missedCount, resume } = usePageLive();
+ * ```
+ *
+ * A component that refetches on its own realtime topic need not use it:
+ * built-in blocks with a `realtimeTopic` already follow the state.
+ */
+export function usePageLive(): PageLiveState {
+  const isPaused = computed(() => currentPageLive()?.isPaused.value ?? false);
+  return {
+    isEnabled: computed(() => currentPageLive() !== null),
+    isLive: computed(() => !isPaused.value),
+    isPaused,
+    pause: () => currentPageLive()?.pause(),
+    resume: () => currentPageLive()?.resume(),
+    toggle: () => currentPageLive()?.toggle(),
+    lastUpdatedAt: computed(
+      () => currentPageLive()?.lastUpdatedAt.value ?? null,
+    ),
+    missedCount: computed(() => currentPageLive()?.missedCount.value ?? 0),
+  };
+}

package/frontend-vue/layers/dms-ui/app/composables/table-view/shortcuts/index.ts

@@ -23,6 +23,11 @@ import {
 } from "./tableViewShiftA";
 import { TABLE_VIEW_DELETE_METADATA } from "./tableViewDelete";
 import { TABLE_VIEW_SHIFT_F_METADATA } from "./tableViewShiftF";
+import {
+  TABLE_VIEW_J_METADATA,
+  TABLE_VIEW_K_METADATA,
+  TABLE_VIEW_PANEL_ESCAPE_METADATA,
+} from "./tableViewRowPanel";
 
 export const TABLE_VIEW_SHORTCUTS_METADATA = [
   TABLE_VIEW_META_R_METADATA,
@@ -31,6 +36,9 @@ export const TABLE_VIEW_SHORTCUTS_METADATA = [
   TABLE_VIEW_SHIFT_A_METADATA,
   TABLE_VIEW_DELETE_METADATA,
   TABLE_VIEW_SHIFT_F_METADATA,
+  TABLE_VIEW_J_METADATA,
+  TABLE_VIEW_K_METADATA,
+  TABLE_VIEW_PANEL_ESCAPE_METADATA,
 ];
 
 interface BuildTableViewShortcutsParams<T extends Data> {

package/frontend-vue/layers/dms-ui/app/composables/table-view/shortcuts/tableViewRowPanel.ts

@@ -0,0 +1,30 @@
+// The keys of a row opened from the table (see `listenRowSteps` and
+// `listenRowPanelClose`): listed in the shortcuts help, handled by the panel,
+// drawer or modal while it is open.
+
+const ROW_OPEN_CONDITION = {
+  descriptionKey: "$dms.shortcuts.tableview.row_open.condition",
+};
+
+export const TABLE_VIEW_J_METADATA: ShortcutMetadata = {
+  key: ["j"],
+  descriptionKey: "$dms.shortcuts.tableview.j.description",
+  component: "$dms.components.tableview",
+  condition: ROW_OPEN_CONDITION,
+};
+
+export const TABLE_VIEW_K_METADATA: ShortcutMetadata = {
+  key: ["k"],
+  descriptionKey: "$dms.shortcuts.tableview.k.description",
+  component: "$dms.components.tableview",
+  condition: ROW_OPEN_CONDITION,
+};
+
+export const TABLE_VIEW_PANEL_ESCAPE_METADATA: ShortcutMetadata = {
+  key: ["$keyboard.escape"],
+  descriptionKey: "$dms.shortcuts.tableview.panel_escape.description",
+  component: "$dms.components.tableview",
+  condition: {
+    descriptionKey: "$dms.shortcuts.tableview.panel_escape.condition",
+  },
+};

package/frontend-vue/layers/dms-ui/app/composables/table-view/types/action-target.ts

@@ -1,5 +1,18 @@
 import type { DrawerDirection } from "../../containers/types";
 
+/** What a `sidePanel` target sets besides its component (backend `SidePanelTargetOptions`). */
+export interface SidePanelTargetOptions {
+  /** Title of the panel header (`$`: an i18n key); the action's label else. */
+  title?: string;
+  /**
+   * The row's position under the title: an i18n key (`$`-prefixed) receiving
+   * `{ index }` (from 1) and `{ total }`.
+   */
+  positionLabel?: string;
+  /** The open row is kept in the URL (`?record=`): on unless `false`. */
+  deepLink?: boolean;
+}
+
 export type ActionTarget =
   | {
       type: "drawer";
@@ -16,6 +29,8 @@ export type ActionTarget =
       title?: string;
       description?: string;
     }
+  /** A non-modal panel docked on the right of the page, on a row. */
+  | ({ type: "sidePanel"; component: ComponentInfo } & SidePanelTargetOptions)
   | { type: "page"; url: string }
   | { type: "external"; url: string; newTab?: boolean }
   /** Runs a quick action, by its `category:id` key or bare id. */

package/frontend-vue/layers/dms-ui/app/composables/table-view/types/config.ts

@@ -219,7 +219,11 @@ export interface TableViewSourceCapabilities {
 /** Where a `TableView.fromSource` table reads its rows (backend `source`). */
 export interface TableViewSourceConfig {
   fetchUrl: string;
+  /** Route answering one row, `{id}` its id (backend `fetchRowUrl`). */
+  fetchRowUrl?: string;
   capabilities: TableViewSourceCapabilities;
+  /** Id of the `PeriodSelector` whose period is sent to `fetchUrl`. */
+  periodScope?: string;
 }
 
 export interface TableViewListResponse<T> {

package/frontend-vue/layers/dms-ui/app/config/shortcuts-registry.ts

@@ -1,4 +1,5 @@
 import { GLOBAL_SHORTCUTS_METADATA } from "../build/composables/global/shortcuts";
+import { LIVE_TOGGLE_SHORTCUTS_METADATA } from "../build/composables/live/shortcuts";
 import { TAB_SHORTCUTS_METADATA } from "../composables/tab/shortcuts";
 import { TABLE_VIEW_SHORTCUTS_METADATA } from "../composables/table-view/shortcuts";
 import type { ComponentShortcuts } from "../types/shortcuts";
@@ -16,4 +17,8 @@ export default [
     component: "TableView",
     shortcuts: TABLE_VIEW_SHORTCUTS_METADATA,
   },
+  {
+    component: "LiveToggle",
+    shortcuts: LIVE_TOGGLE_SHORTCUTS_METADATA,
+  },
 ] satisfies ComponentShortcuts[];

package/frontend-vue/layers/dms-ui/app/types/live.ts

@@ -0,0 +1,8 @@
+/**
+ * Mirror of `PageLiveOptions` from `@antelopejs/interface-dms/page`: the
+ * Direct / Pause valve a page declares with `live`.
+ */
+export interface PageLiveOptions {
+  /** Shortest interval, in seconds, between two refetches of one block. */
+  maxRate?: number;
+}

package/frontend-vue/layers/dms-ui/app/types/row-action.ts

@@ -24,7 +24,10 @@ export interface CustomRowAction {
   isVisible?: boolean;
   /** Legacy spelling of `isVisible`, still honoured. */
   visible?: boolean;
-  /** Preferred row-click target when its rule accepts the row. */
+  /**
+   * Preferred row-click target when its rule accepts the row: a double-click,
+   * or a single click on a table with `rowClick: "single"`.
+   */
   isDefault?: boolean;
   /** Color of the inline button or menu entry. */
   color?: ColorValue;
@@ -34,6 +37,6 @@ export interface CustomRowAction {
   showLabel?: boolean;
   /** Offered on the selection bar too. */
   bulk?: CustomRowActionBulk;
-  /** The drawer or modal it opens is reflected in the URL (`?record=`). */
+  /** The drawer, modal or side panel it opens is reflected in the URL (`?record=`). */
   deepLink?: boolean;
 }

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/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();
+});