@antelopejs/dms 0.7.0 → 0.7.2

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

@@ -0,0 +1,84 @@
+// @vitest-environment jsdom
+/**
+ * A table view reads its rows again when they moved without a write through
+ * its own routes: on each event of its `realtimeTopic`, and each time the page
+ * asks its blocks to refresh (refreshPageBlocks). The re-read goes through the
+ * same refresh as the toolbar's button, which keeps the rows on screen.
+ */
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { createApp, defineComponent, h } from "vue";
+import { afterEach, beforeEach, expect, it, vi } from "vitest";
+import type { RealtimeTopicHandler } from "../layers/dms-core/app/composables/realtime/useUserRealtime";
+import { refreshPageBlocks } from "../layers/dms-ui/app/utils/blockRefresh";
+
+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 tableViewSource = readFileSync(
+  resolve(
+    __dirname,
+    "../layers/dms-ui/app/components/table-view/TableView.vue",
+  ),
+  "utf8",
+);
+
+const UPLOADS_TOPIC = "media:uploads";
+const mounted: Array<{ unmount: () => void }> = [];
+
+function mountBlock(topic: string | string[] | undefined) {
+  const onRefresh = vi.fn();
+  const Block = defineComponent({
+    setup() {
+      useRefreshTriggers(topic, onRefresh);
+      return () => h("div");
+    },
+  });
+  const app = createApp(Block);
+  app.mount(document.createElement("div"));
+  mounted.push(app);
+  return { onRefresh, unmount: () => app.unmount() };
+}
+
+beforeEach(() => topicHandlers.clear());
+
+afterEach(() => {
+  mounted.splice(0).forEach((app) => app.unmount());
+});
+
+it("refreshes on each page refresh while mounted", () => {
+  const block = mountBlock(undefined);
+  refreshPageBlocks();
+  expect(block.onRefresh).toHaveBeenCalledTimes(1);
+
+  block.unmount();
+  mounted.length = 0;
+  refreshPageBlocks();
+  expect(block.onRefresh).toHaveBeenCalledTimes(1);
+});
+
+it("refreshes on each event of any of its topics, not on a snapshot", () => {
+  const block = mountBlock([UPLOADS_TOPIC, "media:jobs"]);
+  expect([...topicHandlers.keys()]).toEqual([UPLOADS_TOPIC, "media:jobs"]);
+
+  topicHandlers.get(UPLOADS_TOPIC)?.({ type: "batch.done" } as never);
+  topicHandlers.get("media:jobs")?.({ type: "job.done" } as never);
+  topicHandlers.get(UPLOADS_TOPIC)?.({ entries: [] } as never);
+  expect(block.onRefresh).toHaveBeenCalledTimes(2);
+});
+
+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());",
+  );
+});

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

@@ -1,4 +1,5 @@
 import { describe, expect, it, vi } from "vitest";
+import { reactive } from "vue";
 import {
   processSourceRows,
   sourceRouteQuery,
@@ -25,6 +26,11 @@ const COLUMNS = [
 
 type Api = Parameters<typeof useTableRows>[0]["api"];
 
+interface PageRoute {
+  params: Record<string, string>;
+  query: Record<string, unknown>;
+}
+
 describe("source tables", () => {
   it("sends the route only the part of the query it handles", () => {
     const query = {
@@ -112,4 +118,65 @@ describe("source tables", () => {
       body: { queries: [{ id: "all", query: {} }] },
     });
   });
+
+  describe("with a templated fetchUrl", () => {
+    const FETCH_URL = "/api/ws/{{params.id}}/requests?route={{query.route}}";
+
+    function sourceRows(route: PageRoute) {
+      const api = vi.fn(async (_url: string) => ({ results: ROWS, total: 3 }));
+      const rows = useTableRows<LogRow>({
+        api: api as unknown as Api,
+        location: FETCH_URL,
+        source: { fetchUrl: FETCH_URL, capabilities: {} },
+        columns: COLUMNS,
+        route: () => ({ routeParams: route.params, routeQuery: route.query }),
+      });
+      return { api, rows };
+    }
+
+    it("requests the page's URL, its values encoded", async () => {
+      const { api, rows } = sourceRows({
+        params: { id: "ws-1" },
+        query: { route: "GET /api/a?b=c" },
+      });
+      await rows.list({});
+      expect(api).toHaveBeenCalledWith(
+        "/api/ws/ws-1/requests?route=GET%20%2Fapi%2Fa%3Fb%3Dc",
+        { query: {} },
+      );
+    });
+
+    it("requests nothing, and lists nothing, while a token has no value", async () => {
+      const { api, rows } = sourceRows({ params: { id: "ws-1" }, query: {} });
+      expect(rows.sourceUrl.value).toBe(undefined);
+      expect(await rows.list({ offset: 10, limit: 10 })).toEqual({
+        results: [],
+        total: 0,
+        offset: 10,
+        limit: 10,
+      });
+      expect(
+        await rows.countBatch([{ id: "orders", query: { search: "orders" } }]),
+      ).toEqual({ orders: 0 });
+      expect(api).not.toHaveBeenCalled();
+    });
+
+    it("follows the page URL, tab counters included", async () => {
+      const route = reactive<PageRoute>({
+        params: { id: "ws-1" },
+        query: { route: "GET /a" },
+      });
+      const { api, rows } = sourceRows(route);
+      await rows.list({});
+      route.query = { route: "POST /b" };
+      expect(rows.sourceUrl.value).toBe(
+        "/api/ws/ws-1/requests?route=POST%20%2Fb",
+      );
+      await rows.countBatch([{ id: "all", query: {} }]);
+      expect(api.mock.calls.map(([url]) => url)).toEqual([
+        "/api/ws/ws-1/requests?route=GET%20%2Fa",
+        "/api/ws/ws-1/requests?route=POST%20%2Fb",
+      ]);
+    });
+  });
 });

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 = 271;
+const EXPECTED_VUE_FILES = 273;
 
 function walk(directory: string): string[] {
   return readdirSync(directory).flatMap((name) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@antelopejs/dms",
-  "version": "0.7.0",
+  "version": "0.7.2",
   "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.4.2 <0.5.0",
+    "@antelopejs/interface-dms": ">=0.5.1 <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

@@ -32,16 +32,27 @@ For the framework underneath (the core, `ajs` CLI, interfaces as versioned contr
   `Grid`, `KpiCard`, … — fluent builders producing a **serializable description**, not live UI: the
   frontend renders it. **Components fetch their own data** via URLs (`fetchUrl`, `submitUrl`, …) —
   routes often declared `@Get`/`@Post` on the same page class; the backend stays the source of truth.
-  A URL names the record of its page with `{{params.id}}` / `{{query.X}}` (filled from the page URL;
+  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 re-fetch after a form saves.
+  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
+  `realtimeTopic` re-fetches a chart, list block, `Meter`, `Tab` badges or `TableView` on each `PublishMessage`.
+  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.
   A text naming values (an amount, a date, a count) is sent as a `ComposedText` —
   `{ key, params: { amount: { type: "money", value: 92200, currency: "EUR" } } }` — that the
-  browser writes in the reader's language: StatGroup / KeyValueList / Banner texts and layout
+  browser writes in the reader's language: StatGroup / KeyValueList / Banner / NavCardGrid /
+  ActivityFeed / Meter / TopListCard item texts (and ActivityFeed `params`, typed `count` for
+  plurals) and layout
   banners (`RegisterLayoutBanner({ resolve })` → `{ text, actions }`) take it; never format text server-side.
   A table cell's secondary line is a row field holding one (or `{ text, tone }`), named by
   `StatusPillDisplay({ subField })`, `IdentityDisplay({ subtitleField })` or
   `TwoLineDisplay({ subField })`; `IdentityDisplay({ emptyLabel, emptyIcon })` draws an empty row.
+  `StatusPillDisplay({ toneField })` reads the pill's tone from a row field (an HTTP status class),
+  and a `PillsDisplay` item may be `{ label, tone?, variant: "soft" | "outline" }`, styled per row.
+  A `KeyValueList` row takes `copy: true` (a copy button for its shown value) or `copyValue`
+  (the text to copy instead, e.g. a full URL behind a short label).
 - **It's interfaces all the way down.** Everything you consume from the DMS is an AntelopeJS
   interface imported as an `@antelopejs/interface-dms/...` subpath (see the imports below);
   a distributable module exposes its own from a companion `@antelopejs/interface-<name>` package listed in `antelopeJs.implements`.

package/skills/dms-pages/REFERENCE.md

@@ -9,12 +9,28 @@ Main builders: `Form`; `TableView(controller, options)`; the charts (`ChartLine`
 `ChartArea`, `ChartBar`, `ChartColumn`, `ChartDonut`, `ChartPie`, `ChartScatter`,
 `ChartMixed`, `ChartRadar`, `ChartRadialBar`, `ChartHeatmap`, `ChartCandlestick`, usually
 inside `ChartCard`); layout `Grid` + `GridRow`, `HStack` / `VStack` / `Spacer`, `Tab`,
-`Placeholder`; dashboard widgets `KpiCard`, `TopListCard`, `PeriodSelector`; and
+`Placeholder`; dashboard widgets `KpiCard`, `TopListCard`, `PeriodSelector`; display blocks
+`StatGroup`, `KeyValueList`, `NavCardGrid`, `EmptyState` (its `code` shows a snippet to
+start with), `Banner`, `Card`, and `CodeBlock` (read-only highlighted code with a copy
+button: `code` + `language`, or `fetchUrl` answering `{ code, language? }` — see
+`docs/04.components/11.display-blocks.md`); and
 `CustomComponent` (deep import from `@antelopejs/interface-dms/base/custom` — not in the barrel). Nest with
 `.child("key", builder)`; `Grid` children must be `GridRow`s. Builders also carry a
 behavioral DSL — permissioned `.action()`s and `.watch()` reactivity — see
 `docs/02.building/05.actions-and-reactivity.md`.
 
+A `TableView` scoped by the page URL takes `queryParamFilters: { status: { field: "status" } }`
+(hidden filters read from `?status=`; `routeParamFilters` for slug params like `:id`). No
+glue is needed around it: an active query filter shows the `filtered` empty state, and a
+link changing its value sends the table back to page 1. A drawer or modal row action already
+gets `navigation` (J / K, `index` / `total` in the order shown) —
+`docs/04.components/06.tables/8.row-drawers.md`.
+
+A button or row action (`customButtons`, `rowActions.custom`, a page's `headerActions`)
+points at an `ActionTarget`. A `drawer` target opens from the bottom; give it
+`direction: "right"` for a side sheet (an inspector, a detail panel) instead of hosting your
+own drawer in a `CustomComponent`.
+
 ## DataTypes
 
 A field's `type` is a **DataType instance**: `new DefaultDataTypes.StringType({ … })`. The