@antelopejs/dms 0.7.9 → 0.7.10

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

@@ -1,35 +1,78 @@
-import { computed, type ComputedRef } from "vue";
+import {
+  computed,
+  getCurrentScope,
+  onScopeDispose,
+  type ComputedRef,
+} from "vue";
 import { currentPageLive } from "../../build/composables/live/currentPageLive";
+import type { PageLiveController } from "../../build/composables/live/pageLiveController";
+import type { PageLiveNote, PageLiveNoteInput } from "../../types/live";
 
-/** The Direct / Pause state of the page on screen, for a module's component. */
+/** The Live / 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. */
+  /** The page declares `live`: it has a Live / Pause state at all. */
   isEnabled: ComputedRef<boolean>;
-  /** The page's data follows its events: Direct, or a page without `live`. */
+  /** The page's data follows its events: Live, or a page without `live`. */
   isLive: ComputedRef<boolean>;
   /** The page is paused: its blocks request nothing on their events. */
   isPaused: ComputedRef<boolean>;
+  /**
+   * Why the page paused by itself: a hold's reason, or its tab hidden in the
+   * background. `null` while live, and while paused by the user.
+   */
+  pauseReason: ComputedRef<PageLiveNote | null>;
   pause: () => void;
-  /** Leaves the pause: each block that missed an event refetches once. */
+  /**
+   * Leaves the pause: each block that missed an event refetches once. It also
+   * lifts the holds of the moment, until their component releases them.
+   */
   resume: () => void;
   toggle: () => void;
+  /**
+   * Holds the page paused for a reason, until `release()` or until the
+   * component goes: while the user types in a form whose results the live
+   * data would move, say. The toggle reads "Paused · <reason>"; give an i18n
+   * key prefixed with `$` (`hold("$api.live.typing_in_tester")`). Calling it
+   * again changes the reason. The page resumes once nothing holds it, unless
+   * the user paused it.
+   */
+  hold: (reason: PageLiveNoteInput) => void;
+  /** Drops this component's hold, if it holds the page. */
+  release: () => 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. */
+  /**
+   * What the page missed since the pause, in published rows: a message's
+   * `payload.ids` count once per row, its `payload.count` as that many, any
+   * other message as one.
+   */
   missedCount: ComputedRef<number>;
+  /** The breakdown of what was missed, as `setMissedDetail` gave it. */
+  missedDetail: ComputedRef<PageLiveNote | null>;
+  /**
+   * Gives the toggle a breakdown of what was missed, shown after the count
+   * ("Paused · 40 new requests · 2 in 5xx"): a component following the page's
+   * topic tallies what it cares about while paused and says it here, e.g.
+   * `setMissedDetail({ text: "$api.live.in_5xx", params: { count: 2 }, tone: "error" })`.
+   * Cleared on resume; `null` clears it.
+   */
+  setMissedDetail: (detail: PageLiveNoteInput | null) => void;
+  /** The realtime stream is down and the page reads its blocks on a clock. */
+  isPolling: ComputedRef<boolean>;
 }
 
 /**
- * Follows the Direct / Pause state of the page on screen (see the page option
+ * Follows the Live / 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.
+ * paused, show what was missed, offer its own switch, hold the page while the
+ * user types.
  *
  * 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.
+ * the page reads as live and never paused, and its actions do nothing.
  *
  * ```ts
- * const { isPaused, missedCount, resume } = usePageLive();
+ * const { isPaused, missedCount, resume, hold, release } = usePageLive();
  * ```
  *
  * A component that refetches on its own realtime topic need not use it:
@@ -37,16 +80,49 @@ export interface PageLiveState {
  */
 export function usePageLive(): PageLiveState {
   const isPaused = computed(() => currentPageLive()?.isPaused.value ?? false);
+  const hold = usePageLiveHold();
   return {
     isEnabled: computed(() => currentPageLive() !== null),
     isLive: computed(() => !isPaused.value),
     isPaused,
+    pauseReason: computed(() => currentPageLive()?.pauseReason.value ?? null),
     pause: () => currentPageLive()?.pause(),
     resume: () => currentPageLive()?.resume(),
     toggle: () => currentPageLive()?.toggle(),
+    hold: hold.hold,
+    release: hold.release,
     lastUpdatedAt: computed(
       () => currentPageLive()?.lastUpdatedAt.value ?? null,
     ),
     missedCount: computed(() => currentPageLive()?.missedCount.value ?? 0),
+    missedDetail: computed(() => currentPageLive()?.missedDetail.value ?? null),
+    setMissedDetail: (detail) => currentPageLive()?.setMissedDetail(detail),
+    isPolling: computed(() => currentPageLive()?.isPolling.value ?? false),
+  };
+}
+
+interface PageLiveHold {
+  hold: (reason: PageLiveNoteInput) => void;
+  release: () => void;
+}
+
+// One hold per call of usePageLive, released with the component's scope: a
+// component leaving the page never leaves it paused.
+function usePageLiveHold(): PageLiveHold {
+  const owner = Symbol("page-live-hold");
+  let holder: PageLiveController | null = null;
+  const release = () => {
+    holder?.release(owner);
+    holder = null;
+  };
+  if (getCurrentScope()) onScopeDispose(release);
+  return {
+    hold: (reason) => {
+      const controller = currentPageLive();
+      if (holder !== controller) release();
+      holder = controller;
+      controller?.hold(owner, reason);
+    },
+    release,
   };
 }

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

@@ -1,7 +1,16 @@
+/**
+ * The key a table view opens its search with when its `searchShortcut`
+ * names none.
+ */
+export const DEFAULT_TABLE_SEARCH_SHORTCUT = "shift_f";
+
 export const TABLE_VIEW_SHIFT_F_METADATA: ShortcutMetadata = {
   key: ["$keyboard.shift", "f"],
   descriptionKey: "$dms.shortcuts.tableview.shift_f.description",
   component: "$dms.components.tableview",
+  condition: {
+    descriptionKey: "$dms.shortcuts.tableview.shift_f.condition",
+  },
 };
 
 export function createTableViewShiftFShortcut(
@@ -16,3 +25,14 @@ export function createTableViewShiftFShortcut(
     focusSearchBar();
   };
 }
+
+/**
+ * The `defineShortcuts` map opening a table's search on `key`, ⇧F when the
+ * table names none.
+ */
+export function tableSearchShortcuts(
+  key: string | undefined,
+  openSearch: () => void,
+): Record<string, () => void> {
+  return { [key || DEFAULT_TABLE_SEARCH_SHORTCUT]: openSearch };
+}

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

@@ -1,9 +1,19 @@
 import type { DrawerDirection } from "../../containers/types";
 
+/** What a side panel says on a row that is gone (backend `SidePanelNotFoundTexts`). */
+export interface SidePanelNotFoundTexts {
+  /** `$`: an i18n key; the DMS's generic title else. */
+  title?: string;
+  /** `$`: an i18n key; the DMS's generic text else. */
+  description?: string;
+}
+
 /** 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;
+  /** Title of the header while a row is open, receiving the row's fields. */
+  rowTitle?: string;
   /**
    * The row's position under the title: an i18n key (`$`-prefixed) receiving
    * `{ index }` (from 1) and `{ total }`.
@@ -11,6 +21,8 @@ export interface SidePanelTargetOptions {
   positionLabel?: string;
   /** The open row is kept in the URL (`?record=`): on unless `false`. */
   deepLink?: boolean;
+  /** The state drawn on a row that no longer exists (a 404). */
+  notFound?: SidePanelNotFoundTexts;
 }
 
 export type ActionTarget =

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

@@ -2,6 +2,7 @@ import type {
   FormContainer,
   FormPageUrls,
 } from "../../../build/composables/table-view/useTableViewConfig";
+import type { RowActionRule } from "#dms-core/app/types/row-action";
 import type { TableViewColumn } from "./column";
 import type { TableViewDisplayCapabilities } from "./display";
 import type { CustomButton } from "./custom-button";
@@ -283,6 +284,8 @@ export interface TableViewConfig<T extends Data>
   componentId?: string;
   pageId?: string;
   defaultSort?: { field: string; desc?: boolean };
+  /** Rows listed first whatever the sort: a rule on their fields. */
+  pinnedRows?: RowActionRule;
   queryParamFilters?: QueryParamFilters;
   routeParamFilters?: RouteParamFilters;
   routeParams?: Record<string, string>;
@@ -298,6 +301,8 @@ export interface TableViewConfig<T extends Data>
   /** The controller declares `@Searchable` fields. */
   searchable?: boolean;
   searchPlaceholder?: string;
+  /** Key opening the search (`defineShortcuts` notation); `shift_f` else. */
+  searchShortcut?: string;
   quickFilters?: TableViewQuickFilter[];
   /** Rows per page while the user picked none. */
   pageSize?: number;

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

@@ -0,0 +1,55 @@
+import { injectLocal } from "@vueuse/core";
+import { computed, type ComputedRef, type ShallowRef } from "vue";
+import type {
+  Data,
+  TableSharedData,
+} from "../../build/components/table/Table.vue";
+
+/** What narrows a table's rows, and the ways out, for its empty state. */
+export interface TableViewEmptyStateControls {
+  /** The text searched, empty when none. */
+  search: ComputedRef<string>;
+  /** A search, a filter chip, a quick filter or a URL filter narrows the rows. */
+  isFiltered: ComputedRef<boolean>;
+  /** A search narrows the rows: `clearSearch` has something to clear. */
+  canClearSearch: ComputedRef<boolean>;
+  /** A filter chip (a quick filter's included) narrows the rows. */
+  canClearFilters: ComputedRef<boolean>;
+  /** Empties the search, as the table's own "Clear search" does. */
+  clearSearch: () => void;
+  /** Clears the filter chips (pinned ones back to their value), the search kept. */
+  clearFilters: () => void;
+  /** Clears both, as the table's "Clear filters and search" does. */
+  clearAll: () => void;
+  /** Lists the rows again. */
+  refresh: () => void;
+}
+
+/**
+ * The search and filters of the table a component is drawn in, for a custom
+ * empty state (`emptyStates.*.component`) or anything else inside the table:
+ * offer "Clear search" and "Clear filters" without reading the table's
+ * internals. A filter the page URL applies (`queryParamFilters`) counts in
+ * `isFiltered` but is not the table's to clear: the page clears its own.
+ *
+ * Outside a table, nothing narrows and every action does nothing.
+ *
+ * ```ts
+ * const { canClearSearch, clearSearch } = useTableViewEmptyState();
+ * ```
+ */
+export function useTableViewEmptyState(): TableViewEmptyStateControls {
+  const shared =
+    injectLocal<ShallowRef<TableSharedData<Data>>>("tableSharedData");
+  const table = () => shared?.value;
+  return {
+    search: computed(() => table()?.globalFilterState.value ?? ""),
+    isFiltered: computed(() => !!table()?.isFiltered.value),
+    canClearSearch: computed(() => !!table()?.clearableFilters.value.search),
+    canClearFilters: computed(() => !!table()?.clearableFilters.value.filters),
+    clearSearch: () => table()?.clearSearch(),
+    clearFilters: () => table()?.clearFilters(),
+    clearAll: () => table()?.resetFilters(),
+    refresh: () => table()?.emits("refresh"),
+  };
+}

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

@@ -1,8 +1,54 @@
+/**
+ * Mirror of `PageLivePeriod` from `@antelopejs/interface-dms/page`: whole
+ * minutes, hours or days (`"30m"`, `"24h"`, `"7d"`).
+ */
+export type PageLivePeriod = `${number}${"m" | "h" | "d"}`;
+
+/** Mirror of `PageLiveSlowRate`: the cadence of a page showing a long period. */
+export interface PageLiveSlowRate {
+  period: PageLivePeriod;
+  maxRate: number;
+}
+
 /**
  * Mirror of `PageLiveOptions` from `@antelopejs/interface-dms/page`: the
- * Direct / Pause valve a page declares with `live`.
+ * Live / Pause valve a page declares with `live`.
  */
 export interface PageLiveOptions {
   /** Shortest interval, in seconds, between two refetches of one block. */
   maxRate?: number;
+  /** The slower cadence once the page's period spans `period` or more. */
+  slowRateAfter?: PageLiveSlowRate;
+  /** Key the remembered Live / Pause choice is shared under. */
+  rememberKey?: string;
+}
+
+/** How the live toggle draws a note: a breakdown in 5xx reads as an error. */
+export type PageLiveNoteTone = "neutral" | "warning" | "error";
+
+/**
+ * A short text the live toggle shows: why the page holds ("typing in the
+ * Tester"), or what its missed events hold ("2 in 5xx"). `text` is an i18n
+ * key prefixed with `$`, translated with `params` (pluralised on
+ * `params.count` when it is a number), or a text shown as is.
+ */
+export interface PageLiveNote {
+  text: string;
+  params?: Record<string, unknown>;
+  tone?: PageLiveNoteTone;
+}
+
+/** A {@link PageLiveNote}, or its `text` alone. */
+export type PageLiveNoteInput = string | PageLiveNote;
+
+/**
+ * Mirror of `TableViewLiveHoldOptions` from
+ * `@antelopejs/interface-dms/base/table-view`: when a `liveHold` table also
+ * holds its rows while its page is live.
+ */
+export interface TableViewLiveHoldOptions {
+  /** While one of its rows is open in the side panel. */
+  whileRowOpen?: boolean;
+  /** While the user has scrolled its first row out of view. */
+  whileScrolled?: boolean;
 }

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

@@ -120,6 +120,8 @@
       "clear_selection": "Clear selection",
       "expand_row": "Expand row",
       "collapse_row": "Collapse row",
+      "row_actions": "Row actions",
+      "row_actions_for": "Actions for {label}",
       "tabs": {
         "all": "All"
       },
@@ -464,7 +466,8 @@
           "condition": "Only when enableRowSelection is enabled"
         },
         "shift_f": {
-          "description": "Open/focus search bar"
+          "description": "Open/focus search bar",
+          "condition": "Unless the table names another key (searchShortcut), such as /"
         },
         "delete": {
           "description": "Delete hovered row",
@@ -722,21 +725,27 @@
       "empty": "Nothing to show yet",
       "load_error": "Couldn't load this block",
       "load_error_hint": "Check your connection, then try again.",
-      "retry": "Try again"
+      "retry": "Try again",
+      "not_found": "Not found",
+      "not_found_hint": "What this shows doesn’t exist, or no longer does."
     },
     "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",
+      "direct": "Live",
       "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"
+      "show_new": "Show",
+      "paused": "Paused",
+      "resume": "Resume",
+      "reason_hidden": "tab hidden",
+      "polling": "no realtime, polling"
     }
   }
 }

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

@@ -120,6 +120,8 @@
       "clear_selection": "Effacer la sélection",
       "expand_row": "Déplier la ligne",
       "collapse_row": "Replier la ligne",
+      "row_actions": "Actions de la ligne",
+      "row_actions_for": "Actions pour {label}",
       "tabs": {
         "all": "Tous"
       },
@@ -465,7 +467,8 @@
           "condition": "Uniquement quand enableRowSelection est activé"
         },
         "shift_f": {
-          "description": "Ouvrir/focus la barre de recherche"
+          "description": "Ouvrir/focus la barre de recherche",
+          "condition": "Sauf si le tableau nomme une autre touche (searchShortcut), comme /"
         },
         "delete": {
           "description": "Supprimer la ligne survolée",
@@ -723,7 +726,9 @@
       "empty": "Rien à afficher pour l'instant",
       "load_error": "Impossible de charger ce bloc",
       "load_error_hint": "Vérifiez votre connexion, puis réessayez.",
-      "retry": "Réessayer"
+      "retry": "Réessayer",
+      "not_found": "Introuvable",
+      "not_found_hint": "Ce qui est affiché ici n’existe pas, ou plus."
     },
     "action_error": {
       "forbidden": "Vous n’avez pas l’autorisation d’effectuer cette action.",
@@ -737,7 +742,11 @@
       "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"
+      "show_new": "Afficher",
+      "paused": "En pause",
+      "resume": "Reprendre",
+      "reason_hidden": "onglet masqué",
+      "polling": "sans temps réel, relecture régulière"
     }
   }
 }

package/frontend-vue/tests/activity-feed-fill-height.test.ts

@@ -8,6 +8,7 @@ const items = ref<Array<Record<string, unknown>>>([]);
 vi.mock("../layers/dms-ui/app/build/composables/blocks/useBlockItems", () => ({
   useBlockItems: () => ({
     items: computed(() => items.value),
+    count: computed(() => undefined),
     isPending: computed(() => false),
     hasError: computed(() => false),
     refresh: async () => {},

package/frontend-vue/tests/activity-feed-head.test.ts

@@ -0,0 +1,140 @@
+/**
+ * An ActivityFeed's head carries a count beside its title (the option, or the
+ * `count` its route answers) and a soft badge before its actions; each entry
+ * may add a third, dimmed mono line under its details.
+ */
+import { computed, createSSRApp, defineComponent, h, ref } from "vue";
+import { renderToString } from "vue/server-renderer";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import ActivityFeed from "../layers/dms-ui/app/components/activity-feed/ActivityFeed.vue";
+
+const items = ref<Array<Record<string, unknown>>>([]);
+const fetchedCount = ref<number | undefined>(undefined);
+
+vi.mock("../layers/dms-ui/app/build/composables/blocks/useBlockItems", () => ({
+  useBlockItems: () => ({
+    items: computed(() => items.value),
+    count: computed(() => fetchedCount.value),
+    isPending: computed(() => false),
+    hasError: computed(() => false),
+    refresh: async () => {},
+  }),
+}));
+
+const Card = defineComponent({
+  props: {
+    title: { type: String, default: undefined },
+    count: { type: [Number, String], default: undefined },
+  },
+  setup:
+    (props, { slots }) =>
+    () =>
+      h("div", { "data-card": "" }, [
+        h("header", [
+          props.title,
+          props.count === undefined
+            ? null
+            : h("span", { "data-count": "" }, String(props.count)),
+          slots.actions?.(),
+        ]),
+        slots.default?.(),
+      ]),
+});
+
+const Badge = defineComponent({
+  props: { label: String },
+  setup: (props) => () => h("span", { "data-badge": "" }, props.label),
+});
+
+const Slot = defineComponent({
+  setup:
+    (_, { slots }) =>
+    () =>
+      h("div", slots.default?.()),
+});
+
+async function render(props: Record<string, unknown>): Promise<string> {
+  const app = createSSRApp({
+    render: () =>
+      h(ActivityFeed, {
+        componentId: "attention",
+        pageId: "overview",
+        title: "Needs attention",
+        fetchUrl: "/api/attention",
+        groupByDay: false,
+        ...props,
+      }),
+  });
+  app.component("DmsCard", Card);
+  app.component("UBadge", Badge);
+  for (const name of ["UIcon", "USkeleton", "UButton", "ULink", "NuxtLink"]) {
+    app.component(name, Slot);
+  }
+  return renderToString(app);
+}
+
+beforeEach(() => {
+  items.value = [
+    {
+      id: "cart",
+      title: "POST /cart/checkout",
+      meta: ["Client errors"],
+      detail: '400 "Cart is empty" × 16',
+    },
+  ];
+  fetchedCount.value = undefined;
+  vi.stubGlobal("useI18n", () => ({ locale: ref("en-GB"), t: String }));
+  vi.stubGlobal("useTranslation", () => ({
+    processI18n: (text: string) => (text.startsWith("$") ? `t(${text})` : text),
+  }));
+});
+
+afterEach(() => vi.unstubAllGlobals());
+
+describe("ActivityFeed head", () => {
+  it("draws no count and no badge unless asked", async () => {
+    const html = await render({});
+    expect(html).not.toContain("data-count");
+    expect(html).not.toContain("data-badge");
+  });
+
+  it("shows the count option beside the title", async () => {
+    const html = await render({ count: 7 });
+    expect(html).toMatch(/<span data-count[^>]*>7<\/span>/);
+  });
+
+  it("prefers the count its route answers", async () => {
+    fetchedCount.value = 4;
+    const html = await render({ count: 7 });
+    expect(html).toMatch(/<span data-count[^>]*>4<\/span>/);
+  });
+
+  it("draws a translated badge in the head", async () => {
+    // `t` is stubbed as String: a translated key reads as the bare key.
+    const html = await render({ badge: "$api.overview.last_24h" });
+    expect(html).toMatch(
+      /<span data-badge[^>]*>api\.overview\.last_24h<\/span>/,
+    );
+  });
+
+  it("draws a literal badge as written", async () => {
+    const html = await render({ badge: "Last 24 h" });
+    expect(html).toMatch(/<span data-badge[^>]*>Last 24 h<\/span>/);
+  });
+});
+
+describe("ActivityFeed entry detail", () => {
+  it("writes the detail as a third, dimmed mono line", async () => {
+    const html = await render({});
+    const line = /<p class="([^"]*)"[^>]*>([^<]*)<\/p>/.exec(html);
+    expect(line?.[2]?.trim()).toBe("400 &quot;Cart is empty&quot; × 16");
+    expect(line?.[1]).toContain("font-mono");
+    expect(line?.[1]).toContain("text-dimmed");
+  });
+
+  it("draws no detail line for an entry without one", async () => {
+    items.value = [{ id: "a", title: "GET /health" }];
+    const html = await render({});
+    expect(html).not.toMatch(/<p class="[^"]*font-mono/);
+  });
+});