@antelopejs/dms 0.7.7 → 0.7.9

package/frontend-vue/tests/table-cell-tones.test.ts

@@ -0,0 +1,176 @@
+// @vitest-environment jsdom
+/**
+ * A `duration` and a plain text (`string`) cell take the colour of the tone a
+ * row field holds (`toneField`), as text and never as a pill; a row without
+ * one keeps the default look. A duration may also be written in milliseconds
+ * whatever its size (`format: "ms"`).
+ */
+import { createApp, defineComponent, h, type App, type VNodeChild } from "vue";
+import { afterEach, beforeAll, describe, expect, it, vi } from "vitest";
+import type { DataType } from "../layers/dms-core/app/composables/data-types/useDataType";
+import { isObject } from "../layers/dms-core/app/utils/type-check";
+
+const stub = { default: { render: () => null } };
+vi.mock("@nuxt/ui/components/Avatar.vue", () => stub);
+vi.mock("@nuxt/ui/components/Badge.vue", () => stub);
+vi.mock("@nuxt/ui/components/Link.vue", () => stub);
+vi.mock("@nuxt/ui/runtime/vue/components/Icon.vue", () => stub);
+vi.mock("../layers/dms-ui/app/composables/useFileReadUrls", () => ({
+  useFileReadUrls: () => ({ getUrl: () => undefined, resolve: () => {} }),
+}));
+
+type Formatter = (
+  value: unknown,
+  locale: string,
+  options?: unknown,
+  row?: Record<string, unknown>,
+) => unknown;
+
+let formatMilliseconds: (ms: number, locale: string) => string;
+
+const formatters = new Map<string, Formatter>();
+const register = (dataType: DataType) =>
+  formatters.set(dataType.id, dataType.formatter?.default as Formatter);
+
+// Auto-imports of the layer the default types are registered with.
+function stubLayerGlobals() {
+  vi.stubGlobal("h", h);
+  vi.stubGlobal("isObject", isObject);
+  for (const name of [
+    "formatNumber",
+    "formatPrice",
+    "formatPercentage",
+    "formatTimeSpan",
+    "formatDate",
+    "getBooleanLabel",
+  ]) {
+    vi.stubGlobal(name, () => "");
+  }
+  vi.stubGlobal("useDataTypes", () => ({ registerDataType: register }));
+}
+
+beforeAll(async () => {
+  stubLayerGlobals();
+  const { registerDefaultDataTypes } = await import(
+    "../layers/dms-ui/app/build/composables/data-types/registerDefaults"
+  );
+  registerDefaultDataTypes();
+  ({ formatMilliseconds } = await import(
+    "../layers/dms-ui/app/build/composables/data-types/metricCells"
+  ));
+});
+
+let app: App | undefined;
+
+afterEach(() => {
+  app?.unmount();
+  app = undefined;
+});
+
+function render(content: unknown): HTMLElement {
+  const container = document.createElement("div");
+  app = createApp(
+    defineComponent({ setup: () => () => content as VNodeChild }),
+  );
+  app.mount(container);
+  return container;
+}
+
+const cell = (
+  id: string,
+  value: unknown,
+  options: unknown,
+  row: Record<string, unknown> = {},
+) => formatters.get(id)!(value, "en-GB", options, row);
+
+describe("milliseconds format", () => {
+  it("writes every duration in milliseconds, its digits grouped", () => {
+    expect(formatMilliseconds(2149, "en-GB")).toBe("2,149 ms");
+    expect(formatMilliseconds(2149, "fr-FR")).toBe("2 149 ms");
+    expect(formatMilliseconds(2149, "es-ES")).toBe("2.149 ms");
+    expect(formatMilliseconds(910.4, "en-GB")).toBe("910 ms");
+    expect(formatMilliseconds(125_000, "en-GB")).toBe("125,000 ms");
+  });
+});
+
+describe("duration cell", () => {
+  it("keeps its most readable unit by default and writes milliseconds with format ms", () => {
+    expect(render(cell("duration", 2149, {})).textContent).toBe("2.1 s");
+    app?.unmount();
+    expect(render(cell("duration", 2149, { format: "ms" })).textContent).toBe(
+      "2,149 ms",
+    );
+    app?.unmount();
+    expect(
+      render(cell("duration", 2.149, { unit: "s", format: "ms" })).textContent,
+    ).toBe("2,149 ms");
+  });
+
+  it("colours the figure in the row's tone, without a pill", () => {
+    const figure = render(
+      cell(
+        "duration",
+        2149,
+        { toneField: "durationTone" },
+        { durationTone: "warning" },
+      ),
+    ).firstElementChild!;
+    expect(figure.className).toContain("text-warning");
+    expect(figure.className).not.toContain("text-toned");
+    expect(figure.className).not.toMatch(/bg-|rounded/);
+  });
+
+  it("keeps today's colour for a row whose field holds no tone", () => {
+    for (const row of [{}, { durationTone: null }, { durationTone: "slow" }]) {
+      const figure = render(
+        cell("duration", 120, { toneField: "durationTone" }, row),
+      ).firstElementChild!;
+      expect(figure.className).toContain("text-toned");
+      expect(figure.className).not.toContain("text-warning");
+      app?.unmount();
+    }
+  });
+});
+
+describe("plain text cell", () => {
+  it("draws the bare value without a tone field, as a string column did", () => {
+    expect(cell("string", "Timeout", undefined)).toBe("Timeout");
+    expect(cell("string", "Timeout", {}, { messageTone: "error" })).toBe(
+      "Timeout",
+    );
+  });
+
+  it("keeps the bare value for a row whose field holds no tone", () => {
+    const options = { toneField: "messageTone" };
+    expect(cell("string", "OK", options, {})).toBe("OK");
+    expect(cell("string", "OK", options, { messageTone: "red" })).toBe("OK");
+  });
+
+  it("colours the text in the row's tone, without a pill", () => {
+    const text = render(
+      cell(
+        "string",
+        "ECONNRESET",
+        { toneField: "messageTone" },
+        { messageTone: "error" },
+      ),
+    ).firstElementChild!;
+    expect(text.textContent).toBe("ECONNRESET");
+    expect(text.className).toBe("text-error");
+  });
+
+  it("renders a non-string value as the untoned cell does, only adding the tone", () => {
+    const options = { toneField: "messageTone" };
+    for (const value of [2149, ["a", "b"], 0]) {
+      const plain = render(cell("string", value, options, {})).textContent;
+      app?.unmount();
+      const toned = render(
+        cell("string", value, options, { messageTone: "error" }),
+      ).firstElementChild!;
+      expect(toned.textContent).toBe(plain);
+      expect(toned.textContent).not.toContain("[object");
+      expect(toned.className).toBe("text-error");
+      app?.unmount();
+    }
+  });
+});

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

@@ -0,0 +1,204 @@
+// @vitest-environment jsdom
+/**
+ * A `liveHold` table on a paused live page keeps its rows: its events are
+ * counted into a "N new · Show" banner, a source route is told when the rows
+ * were frozen on every list it is asked for (the user's search, sort and
+ * pagination included), and Show reads the rows once without leaving the
+ * pause.
+ */
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { createApp, defineComponent, h, nextTick, type App } from "vue";
+import { refreshPageBlocks } from "../layers/dms-ui/app/utils/blockRefresh";
+import { afterEach, beforeEach, expect, it, vi } from "vitest";
+import type { RealtimeTopicHandler } from "../layers/dms-core/app/composables/realtime/useUserRealtime";
+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 {
+  LIVE_HELD_AT_QUERY_KEY,
+  sourceRouteQuery,
+} from "../layers/dms-ui/app/build/composables/table-view/useTableRows";
+import type { TableLiveHold } from "../layers/dms-ui/app/build/composables/table-view/useTableLiveHold";
+
+const topicHandlers = new Map<string, RealtimeTopicHandler>();
+
+vi.mock("../layers/dms-core/app/composables/realtime/useRealtimeTopic", () => ({
+  useRealtimeTopic: (topic: string, handler: RealtimeTopicHandler) => {
+    topicHandlers.set(topic, handler);
+  },
+}));
+
+const { useRefreshTriggers } = await import(
+  "../layers/dms-ui/app/build/composables/blocks/useRefreshTriggers"
+);
+const { useTableLiveHold } = await import(
+  "../layers/dms-ui/app/build/composables/table-view/useTableLiveHold"
+);
+
+const TOPIC = "api:requests";
+const tableViewSource = readFileSync(
+  resolve(
+    __dirname,
+    "../layers/dms-ui/app/components/table-view/TableView.vue",
+  ),
+  "utf8",
+);
+
+let apps: App[] = [];
+let live: PageLiveController;
+
+const publish = () =>
+  topicHandlers.get(TOPIC)?.({ topic: TOPIC, type: "request", ts: 1 });
+
+function mountTable(options: { liveHold: boolean; isSource?: boolean }) {
+  const refresh = vi.fn();
+  let hold: TableLiveHold | undefined;
+  const app = createApp(
+    defineComponent({
+      setup() {
+        const gate = useRefreshTriggers(TOPIC, refresh);
+        hold = useTableLiveHold({
+          isEnabled: options.liveHold,
+          isSource: options.isSource ?? true,
+          gate: () => gate,
+        });
+        return () => h("div");
+      },
+    }),
+  );
+  app.mount(document.createElement("div"));
+  apps.push(app);
+  return { refresh, hold: hold! };
+}
+
+beforeEach(() => {
+  vi.useFakeTimers();
+  topicHandlers.clear();
+  window.localStorage.clear();
+  live = createPageLiveController("api.logs", {});
+  setCurrentPageLive(live);
+});
+
+afterEach(() => {
+  apps.forEach((app) => app.unmount());
+  apps = [];
+  live.dispose();
+  setCurrentPageLive(null);
+  vi.unstubAllGlobals();
+  vi.useRealTimers();
+});
+
+it("holds the rows while paused and counts what came in", async () => {
+  const { refresh, hold } = mountTable({ liveHold: true });
+  expect(hold.isHolding.value).toBe(false);
+  expect(hold.heldQuery()).toEqual({});
+
+  live.pause();
+  await nextTick();
+  publish();
+  publish();
+
+  expect(refresh).not.toHaveBeenCalled();
+  expect(hold.isHolding.value).toBe(true);
+  expect(hold.newCount.value).toBe(2);
+});
+
+it("bounds a source table's lists at the moment it was frozen", async () => {
+  vi.setSystemTime(new Date("2026-10-11T08:00:00.000Z"));
+  const { hold } = mountTable({ liveHold: true });
+  live.pause();
+  await nextTick();
+
+  vi.setSystemTime(new Date("2026-10-11T08:05:00.000Z"));
+  // The user's search while paused still lists the rows as they stood.
+  expect(hold.heldQuery()).toEqual({
+    [LIVE_HELD_AT_QUERY_KEY]: "2026-10-11T08:00:00.000Z",
+  });
+
+  live.resume();
+  await nextTick();
+  expect(hold.heldQuery()).toEqual({});
+});
+
+it("sends no bound to a data controller's list", async () => {
+  const { hold } = mountTable({ liveHold: true, isSource: false });
+  live.pause();
+  await nextTick();
+  expect(hold.heldQuery()).toEqual({});
+});
+
+it("shows what is new once, staying paused, and holds from then", async () => {
+  vi.setSystemTime(new Date("2026-10-11T08:00:00.000Z"));
+  const { refresh, hold } = mountTable({ liveHold: true });
+  live.pause();
+  await nextTick();
+  publish();
+
+  vi.setSystemTime(new Date("2026-10-11T08:02:00.000Z"));
+  hold.showNew();
+
+  expect(refresh).toHaveBeenCalledTimes(1);
+  expect(live.isPaused.value).toBe(true);
+  expect(hold.newCount.value).toBe(0);
+  expect(hold.heldQuery()).toEqual({
+    [LIVE_HELD_AT_QUERY_KEY]: "2026-10-11T08:02:00.000Z",
+  });
+
+  // Nothing missed since Show: resuming has nothing to read again.
+  live.resume();
+  expect(refresh).toHaveBeenCalledTimes(1);
+});
+
+it("shows no banner count without liveHold, though it still pauses", async () => {
+  const { refresh, hold } = mountTable({ liveHold: false });
+  live.pause();
+  await nextTick();
+  publish();
+  expect(refresh).not.toHaveBeenCalled();
+  expect(hold.newCount.value).toBe(0);
+  expect(hold.heldQuery()).toEqual({});
+
+  live.resume();
+  expect(refresh).toHaveBeenCalledTimes(1);
+});
+
+it("lets the bound through to a source route whatever its capabilities", () => {
+  expect(
+    sourceRouteQuery(
+      { [LIVE_HELD_AT_QUERY_KEY]: "2026-10-11T08:00:00.000Z", search: "x" },
+      {},
+    ),
+  ).toEqual({ [LIVE_HELD_AT_QUERY_KEY]: "2026-10-11T08:00:00.000Z" });
+});
+
+it("reads on a user's refresh while held, and holds from then", async () => {
+  vi.setSystemTime(new Date("2026-10-11T08:00:00.000Z"));
+  const { refresh, hold } = mountTable({ liveHold: true });
+  live.pause();
+  await nextTick();
+  publish();
+
+  vi.setSystemTime(new Date("2026-10-11T08:03:00.000Z"));
+  refreshPageBlocks();
+
+  expect(refresh).toHaveBeenCalledTimes(1);
+  expect(live.isPaused.value).toBe(true);
+  expect(hold.newCount.value).toBe(0);
+  expect(hold.heldQuery()).toEqual({
+    [LIVE_HELD_AT_QUERY_KEY]: "2026-10-11T08:03:00.000Z",
+  });
+});
+
+it("wires the table view's rows, row events and banner to the hold", () => {
+  expect(tableViewSource).toMatch(/liveHold\?: boolean;/);
+  expect(tableViewSource).toContain("heldQuery: liveHold.heldQuery,");
+  expect(tableViewSource).toContain("refreshCallback: refreshByUser,");
+  expect(tableViewSource).toContain('@refresh="refreshByUser"');
+  expect(tableViewSource).toContain("gateRowEvent(payload.type, ids, event);");
+  expect(tableViewSource).toMatch(
+    /<LiveHoldBanner[\s\S]*@show="liveHold.showNew"/,
+  );
+});

package/frontend-vue/tests/table-row-hover.test.ts

@@ -5,6 +5,7 @@ import { EYEBROW_CLASS } from "../layers/dms-ui/app/build/utils/eyebrow";
 import { REORDER_HANDLE_CLASS } from "../layers/dms-ui/app/build/composables/table-view/useReorderHandles";
 import {
   resolveRowClickAction,
+  rowCustomActions,
   type RowClickActionOptions,
 } from "../layers/dms-ui/app/utils/rowClickAction";
 import type { CustomRowAction } from "../layers/dms-ui/app/types/row-action";
@@ -158,3 +159,34 @@ describe("resolveRowClickAction", () => {
     expect(resolveRowClickAction(options, rowFor("sent"))).toBe("details");
   });
 });
+
+describe("rowCustomActions", () => {
+  const stopSelling: CustomRowAction = {
+    id: "stop_selling",
+    label: "Stop selling",
+    target: { type: "api", url: "/plans/{_id}/stop", method: "POST" },
+    rule: { field: "isActive", equals: true },
+  };
+  const remove: CustomRowAction = {
+    id: "delete",
+    label: "Delete",
+    target: { type: "api", url: "/plans/{_id}", method: "DELETE" },
+    rule: { field: "workspaces", equals: 0 },
+  };
+
+  it("lists the actions whose rule accepts the row, in their order", () => {
+    const actions = [detailsAction, stopSelling, remove];
+    expect(
+      rowCustomActions(actions, { isActive: true, workspaces: 0 }),
+    ).toEqual(actions);
+    expect(
+      rowCustomActions(actions, { isActive: false, workspaces: 2 }).map(
+        (action) => action.label,
+      ),
+    ).toEqual(["Details"]);
+  });
+
+  it("lists nothing for a table without custom actions", () => {
+    expect(rowCustomActions(undefined, {})).toEqual([]);
+  });
+});

package/frontend-vue/tests/table-source-period-scope.test.ts

@@ -0,0 +1,144 @@
+// @vitest-environment jsdom
+/**
+ * A `TableView.fromSource` table with a `periodScope` follows its
+ * PeriodSelector like a chart: its route is sent the period, it lists again
+ * when the period changes, and it requests nothing (keeping its skeleton)
+ * until the selector has registered the scope.
+ */
+import {
+  computed,
+  createApp,
+  defineComponent,
+  effectScope,
+  h,
+  nextTick,
+  type App,
+} from "vue";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import type { TableViewColumn } from "../layers/dms-ui/app/composables/table-view/types";
+
+const engine = await import("#dms/frontend-module");
+vi.stubGlobal("useDmsAsyncData", engine.useDmsAsyncData);
+vi.stubGlobal("useDmsLazyAsyncData", engine.useDmsLazyAsyncData);
+
+const { useTableRows } = await import(
+  "../layers/dms-ui/app/build/composables/table-view/useTableRows"
+);
+const { useTableListData } = await import(
+  "../layers/dms-ui/app/build/composables/table-view/useTableListData"
+);
+const { usePeriod } = await import(
+  "../layers/dms-core/app/composables/period/usePeriod"
+);
+const { registerPeriodScope } = await import(
+  "../layers/dms-core/app/composables/period/usePeriodScope"
+);
+
+const SCOPE = "report";
+const FETCH_URL = "/api/report";
+const COLUMNS = [{ id: "name", accessorKey: "name" }] as TableViewColumn[];
+
+type Api = Parameters<typeof useTableRows>[0]["api"];
+
+const requests: string[] = [];
+const api = (async (url: string) => {
+  requests.push(url);
+  return { results: [{ _id: "a", name: "row" }], total: 1 };
+}) as unknown as Api;
+
+const mounted: App[] = [];
+const cleanups: Array<() => void> = [];
+let listed: { value: unknown } | undefined;
+
+const SourceTable = defineComponent({
+  setup() {
+    const rows = useTableRows({
+      api,
+      location: FETCH_URL,
+      source: { fetchUrl: FETCH_URL, capabilities: {}, periodScope: SCOPE },
+      columns: COLUMNS,
+    });
+    void useTableListData({
+      componentId: "report",
+      pageId: "reports",
+      rows,
+      query: computed(() => ({ offset: 0, limit: 10 })),
+      archiveQuery: computed(() => ({})),
+      isSelfManaged: computed(() => false),
+    }).then(({ data }) => {
+      listed = data;
+    });
+    return () => h("div");
+  },
+});
+
+function mountTable(): void {
+  const app = createApp(SourceTable);
+  engine.provideDmsFrontendRuntime(app, engine.createDmsFrontendRuntime());
+  app.mount(document.createElement("div"));
+  mounted.push(app);
+}
+
+function registerSelector() {
+  const scope = effectScope();
+  const period = scope.run(() => usePeriod({ defaultPreset: "last-7-days" }))!;
+  cleanups.push(registerPeriodScope(SCOPE, period.state), () => scope.stop());
+  return period;
+}
+
+const settle = async () => {
+  await nextTick();
+  await new Promise((resolve) => setTimeout(resolve, 0));
+  await nextTick();
+};
+
+const periodOf = (url: string) =>
+  Object.fromEntries(new URL(url, "http://dms.local").searchParams);
+
+beforeEach(() => {
+  requests.length = 0;
+  listed = undefined;
+});
+
+afterEach(() => {
+  mounted.splice(0).forEach((app) => app.unmount());
+  cleanups.splice(0).forEach((cleanup) => cleanup());
+});
+
+describe("a source table bound to a period scope", () => {
+  it("requests nothing and keeps its skeleton until the scope registers", async () => {
+    mountTable();
+    await settle();
+    expect(requests).toEqual([]);
+    expect(listed).toBeDefined();
+    expect(listed!.value).toBeNull();
+  });
+
+  it("sends the period with its request once the scope registers", async () => {
+    const period = registerSelector();
+    mountTable();
+    await settle();
+    expect(requests).toHaveLength(1);
+    expect(listed!.value).toMatchObject({ total: 1 });
+    const { range } = period.state.value;
+    expect(periodOf(requests[0]!)).toEqual({
+      from: range.from.toISOString(),
+      to: range.to.toISOString(),
+      preset: "last-7-days",
+      comparison: "none",
+    });
+  });
+
+  it("lists again when the period changes", async () => {
+    const period = registerSelector();
+    mountTable();
+    await settle();
+    period.setPreset("last-30-days");
+    period.setComparison("previous-period");
+    await settle();
+    const last = periodOf(requests.at(-1)!);
+    expect(last.preset).toBe("last-30-days");
+    expect(last.comparison).toBe("previous-period");
+    expect(last.compareFrom).toBeDefined();
+  });
+});

package/frontend-vue/tests/table-view-refresh.test.ts

@@ -78,7 +78,7 @@ it("refreshes on each event of any of its topics, not on a snapshot", () => {
 
 it("wires the table view's realtimeTopic and page refresh to its refresh", () => {
   expect(tableViewSource).toMatch(/realtimeTopic\?: string \| string\[\];/);
-  expect(tableViewSource).toContain(
-    "useRefreshTriggers(props.realtimeTopic, () => void refreshAll());",
+  expect(tableViewSource).toMatch(
+    /const liveGate = useRefreshTriggers\(\s*props\.realtimeTopic,\s*\(\) => void refreshAll\(\),\s*\);/,
   );
 });

package/frontend-vue/tests/table-view-sources.test.ts

@@ -179,4 +179,44 @@ describe("source tables", () => {
       ]);
     });
   });
+
+  describe("reading one row (fetchRowUrl)", () => {
+    const FETCH_URL = "/api/ws/{{params.ws}}/requests";
+    const ROW_URL = "/api/ws/{{params.ws}}/requests/{id}";
+
+    function rowsWith(
+      api: (url: string) => Promise<unknown>,
+      fetchRowUrl?: string,
+    ) {
+      return useTableRows<LogRow>({
+        api: api as unknown as Api,
+        location: FETCH_URL,
+        source: { fetchUrl: FETCH_URL, fetchRowUrl, capabilities: {} },
+        columns: COLUMNS,
+        route: () => ({ routeParams: { ws: "ws-1" }, routeQuery: {} }),
+      });
+    }
+
+    it("reads a row by id, its id and the page's tokens filled", async () => {
+      const api = vi.fn(async () => ROWS[2]);
+      const rows = rowsWith(api, ROW_URL);
+      expect(await rows.getRow("c/42")).toBe(ROWS[2]);
+      expect(api).toHaveBeenCalledWith("/api/ws/ws-1/requests/c%2F42");
+    });
+
+    it("rejects as the route does on a missing row", async () => {
+      const api = vi.fn(async () => {
+        throw Object.assign(new Error("Not Found"), { statusCode: 404 });
+      });
+      await expect(rowsWith(api, ROW_URL).getRow("gone")).rejects.toThrow(
+        "Not Found",
+      );
+    });
+
+    it("requests nothing without fetchRowUrl", async () => {
+      const api = vi.fn(async () => ROWS[0]);
+      expect(await rowsWith(api).getRow("a")).toBeUndefined();
+      expect(api).not.toHaveBeenCalled();
+    });
+  });
 });

package/frontend-vue/tests/vue-inventory.test.ts

@@ -2,7 +2,7 @@ import { readFileSync, readdirSync, statSync } from "node:fs";
 import { join, relative } from "node:path";
 import { describe, expect, it } from "vitest";
 
-const EXPECTED_VUE_FILES = 273;
+const EXPECTED_VUE_FILES = 276;
 
 function walk(directory: string): string[] {
   return readdirSync(directory).flatMap((name) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@antelopejs/dms",
-  "version": "0.7.7",
+  "version": "0.7.9",
   "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.3 <0.6.0",
+    "@antelopejs/interface-dms": ">=0.5.5 <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",

package/skills/dms/SKILL.md

@@ -35,8 +35,13 @@ For the framework underneath (the core, `ajs` CLI, interfaces as versioned contr
   A URL names the record of its page with `{{params.id}}` / `{{query.X}}` (filled from the page URL, percent-encoded;
   nothing is fetched while one is unresolved), and `.watch(FormEvents.SUBMIT_SUCCESS,
   BlockFunctions.REFRESH_PAGE)` makes the page's data blocks (table views included) re-fetch after a form saves;
-  `periodScope` binds a card, chart, list block or `Meter` to a `PeriodSelector`, and
+  `periodScope` binds a card, chart, list block, `Meter` or `TableView.fromSource` to a `PeriodSelector`
+  (which keeps its period in the page URL, `?<id>.period=`), and
   `realtimeTopic` re-fetches a chart, list block, `Meter`, `Tab` badges or `TableView` on each `PublishMessage`.
+  A monitoring page that must not refetch on every event declares `live: { maxRate }` in its page options
+  and places a `LiveToggle()` (Direct / Pause, L key); `liveHold: true` keeps a table's rows while paused.
+  A custom component follows that state with `usePageLive()`; `refreshPageBlocks()` (user actions) always reads,
+  `refreshLivePageBlocks()` (timers, feeds) is held while paused.
   A status the backend computes (health, outage) is a `Banner({ fetchUrl })`: the route answers
   a `BannerContent` (its buttons may run `api` / modal / quick-action targets with `confirm`)
   or `null` for no banner — the block then draws nothing.
@@ -50,7 +55,9 @@ For the framework underneath (the core, `ajs` CLI, interfaces as versioned contr
   `StatusPillDisplay({ subField })`, `IdentityDisplay({ subtitleField })` or
   `TwoLineDisplay({ subField })`; `IdentityDisplay({ emptyLabel, emptyIcon })` draws an empty row,
   and `IdentityDisplay({ iconField })` reads each row's tile icon from a row field.
-  `StatusPillDisplay({ toneField })` reads the pill's tone from a row field (an HTTP status class),
+  `StatusPillDisplay({ toneField })` reads the pill's tone from a row field (an HTTP status class);
+  `DurationDisplay({ toneField })` and `TextDisplay({ toneField })` colour their text with it (a slow
+  duration, an error message), and `DurationDisplay({ format: "ms" })` writes "2,149 ms" on every row;
   and a `PillsDisplay` item may be `{ label, tone?, variant: "soft" | "outline" }`, styled per row.
   A `StatGroup` detail and a `NavCardGrid` card title take up to two lines before their ellipsis.
   A unit after a number field is `NumberType({ suffix: "$…days" })`, a character counter on a