@antelopejs/dms 0.7.1 → 0.7.3

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

@@ -0,0 +1,126 @@
+// @vitest-environment jsdom
+/**
+ * The `pills` cell draws a list of strings and related rows as outline role
+ * pills, and the pill items a server styles per row in their own tone and
+ * variant.
+ */
+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>,
+) => VNodeChild;
+
+const registered = new Map<string, DataType["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("useTranslation", () => ({
+    processI18n: (text: string) => text.replace(/^\$/, "i18n:"),
+  }));
+  vi.stubGlobal("useDataTypes", () => ({
+    registerDataType: (dataType: DataType) =>
+      registered.set(dataType.id, dataType.formatter),
+  }));
+}
+
+let app: App | undefined;
+
+function renderPills(value: unknown, options: unknown = {}): HTMLElement {
+  const content = (registered.get("pills")!.default as Formatter)(
+    value,
+    "en",
+    options,
+    {},
+  );
+  const container = document.createElement("div");
+  app = createApp(defineComponent({ setup: () => () => content }));
+  app.component("UIcon", defineComponent({ render: () => h("i") }));
+  app.mount(container);
+  return container;
+}
+
+const pillsOf = (cell: HTMLElement) =>
+  [...cell.firstElementChild!.children].map((pill) => ({
+    label: pill.textContent,
+    className: pill.className,
+  }));
+
+beforeAll(async () => {
+  stubLayerGlobals();
+  const { registerDefaultDataTypes } = await import(
+    "../layers/dms-ui/app/build/composables/data-types/registerDefaults"
+  );
+  registerDefaultDataTypes();
+});
+
+afterEach(() => {
+  app?.unmount();
+  app = undefined;
+});
+
+describe("pills cell", () => {
+  it("draws strings and related rows as outline role pills, as before", () => {
+    const strings = pillsOf(renderPills(["$roles.admin", "Billing"]));
+    expect(strings.map((pill) => pill.label)).toEqual([
+      "i18n:roles.admin",
+      "Billing",
+    ]);
+    expect(strings[0]!.className).toContain("border-accented");
+    app?.unmount();
+
+    const rows = pillsOf(renderPills([{ _id: "r1", name: "Editor" }, "r2"]));
+    expect(rows.map((pill) => pill.label)).toEqual(["Editor"]);
+  });
+
+  it("draws a pill item in its tone and variant, beside plain strings", () => {
+    const pills = pillsOf(
+      renderPills([
+        { label: "EN", tone: "primary", variant: "soft" },
+        { label: "DE", variant: "outline" },
+        { label: "IT", tone: "success" },
+        "ES",
+      ]),
+    );
+
+    expect(pills.map((pill) => pill.label)).toEqual(["EN", "DE", "IT", "ES"]);
+    expect(pills[0]!.className).toContain("text-primary");
+    expect(pills[0]!.className).toContain("bg-(--dms-accent-tint)");
+    expect(pills[1]!.className).toContain("border");
+    expect(pills[1]!.className).toContain("bg-transparent");
+    expect(pills[2]!.className).toContain("bg-success/12");
+    expect(pills[3]!.className).toContain("border-accented");
+  });
+
+  it("draws a pill item without a tone nor a variant as a plain string", () => {
+    const [pill] = pillsOf(renderPills([{ label: "FR" }]));
+    expect(pill!.label).toBe("FR");
+    expect(pill!.className).toContain("border-accented");
+  });
+});

package/frontend-vue/tests/table-source-navigation.test.ts

@@ -0,0 +1,123 @@
+// @vitest-environment jsdom
+/**
+ * A `TableView.fromSource` table whose `fetchUrl` reads the page query lists
+ * again when a link changes that query, through the runtime's real async data
+ * cache: whether the link keeps the page mounted (the watch) or remounts it
+ * (a fresh instance binding to the cached entry of its key).
+ */
+import {
+  computed,
+  createApp,
+  defineComponent,
+  h,
+  nextTick,
+  type App,
+} from "vue";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import type { DmsFrontendRuntime } from "#dms/frontend-module";
+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 { useTableCountsData, useTableListData } = await import(
+  "../layers/dms-ui/app/build/composables/table-view/useTableListData"
+);
+
+const FETCH_URL = "/api/log/route?route={{query.route}}";
+const COLUMNS = [{ id: "path", accessorKey: "path" }] as TableViewColumn[];
+const TAB_QUERIES = [{ id: "get", query: { filter_method: "is:GET" } }];
+const ROUTE_VALUE = "GET /api/search?q=shoes&page=2";
+const ENCODED_URL =
+  "/api/log/route?route=GET%20%2Fapi%2Fsearch%3Fq%3Dshoes%26page%3D2";
+
+type Api = Parameters<typeof useTableRows>[0]["api"];
+
+const requests: string[] = [];
+const api = (async (url: string) => {
+  requests.push(url);
+  return { results: [{ _id: "a", path: "/api/search" }], total: 1 };
+}) as unknown as Api;
+
+let runtime: DmsFrontendRuntime;
+const mounted: App[] = [];
+
+const SourceTable = defineComponent({
+  setup() {
+    const route = runtime.route;
+    const rows = useTableRows({
+      api,
+      location: FETCH_URL,
+      source: { fetchUrl: FETCH_URL, capabilities: { filter: true } },
+      columns: COLUMNS,
+      route: () => ({ routeParams: {}, routeQuery: route.query }),
+    });
+    const archiveQuery = computed(() => ({}));
+    const keys = { componentId: "requests", pageId: "sources", rows };
+    void useTableListData({
+      ...keys,
+      query: computed(() => ({ offset: 0, limit: 10 })),
+      archiveQuery,
+      isSelfManaged: computed(() => false),
+    });
+    void useTableCountsData({
+      ...keys,
+      queries: computed(() => TAB_QUERIES),
+      archiveQuery,
+    });
+    return () => h("div");
+  },
+});
+
+function mountTable(): void {
+  const app = createApp(SourceTable);
+  engine.provideDmsFrontendRuntime(app, runtime);
+  app.mount(document.createElement("div"));
+  mounted.push(app);
+}
+
+const settle = async () => {
+  await nextTick();
+  await new Promise((resolve) => setTimeout(resolve, 0));
+};
+
+beforeEach(() => {
+  requests.length = 0;
+  runtime = engine.createDmsFrontendRuntime();
+});
+
+afterEach(() => {
+  mounted.splice(0).forEach((app) => app.unmount());
+});
+
+describe("a source table following the page query", () => {
+  it("requests nothing while the query value is missing", async () => {
+    mountTable();
+    await settle();
+    expect(requests).toEqual([]);
+  });
+
+  it("lists again when the page stays mounted", async () => {
+    mountTable();
+    await settle();
+    runtime.route.query = { route: ROUTE_VALUE };
+    await settle();
+    expect(requests).toEqual([ENCODED_URL, ENCODED_URL]);
+  });
+
+  // An Inertia link without preserveState remounts the page: the new table
+  // reads the new query from its first render, so its URL never changes.
+  it("lists again when the link remounts the page", async () => {
+    mountTable();
+    await settle();
+    mounted.pop()?.unmount();
+    runtime.route.query = { route: ROUTE_VALUE };
+    mountTable();
+    await settle();
+    expect(requests).toEqual([ENCODED_URL, ENCODED_URL]);
+  });
+});

package/frontend-vue/tests/table-view-hidden-filters-page.test.ts

@@ -0,0 +1,137 @@
+import { computed, nextTick, readonly, ref, watch, type Ref } from "vue";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import type { LocationQuery } from "vue-router";
+import { useAccumulatedPages } from "../layers/dms-ui/app/build/composables/table-view/useAccumulatedPages";
+import { usePersistedPagination } from "../layers/dms-ui/app/build/composables/table-view/usePersistedPagination";
+import { usePreferences } from "../layers/dms-core/app/composables/user/usePreferences";
+
+const PAGE_SIZE = 10;
+const THIRD_PAGE = 2;
+
+// What a table view derives from `queryParamFilters: { status: { field: "status" } }`.
+const hiddenFiltersOf = (query: () => LocationQuery) =>
+  computed(() =>
+    query().status === undefined
+      ? []
+      : [{ accessorKey: "status", mode: "is", value: query().status }],
+  );
+
+const TABLE_KEY = "tables.tasks.query-filters";
+const preferenceKey = (suffix: string) => `${TABLE_KEY}.${suffix}`;
+
+// The `user-preferences` cookie, surviving the remounts of a page.
+let cookie: Ref<Record<string, unknown>>;
+
+// What a table view does on mount: its page, read back from the cookie,
+// under the hidden filters the URL sets.
+const mountTable = (query: Ref<LocationQuery>) => {
+  const hiddenFilters = hiddenFiltersOf(() => query.value);
+  const pagination = usePersistedPagination({
+    preferences: usePreferences(),
+    preferenceKey,
+    defaults: { pageIndex: 0, pageSize: PAGE_SIZE },
+    scope: () => [hiddenFilters.value, []],
+  });
+  return { hiddenFilters, pagination };
+};
+
+beforeEach(() => {
+  cookie = ref({});
+  vi.stubGlobal("useDmsCookie", () => cookie);
+  vi.stubGlobal("ref", ref);
+  vi.stubGlobal("readonly", readonly);
+  vi.stubGlobal("computed", computed);
+  vi.stubGlobal("watch", watch);
+});
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+});
+
+describe("a hidden filter changed by the URL", () => {
+  it("sends the pager back to page 1", () => {
+    const query = ref<LocationQuery>({ status: "pending" });
+    const { pagination } = mountTable(query);
+    pagination.value = { pageIndex: THIRD_PAGE, pageSize: PAGE_SIZE };
+
+    query.value = { status: "cancelled" };
+
+    expect(pagination.value).toEqual({ pageIndex: 0, pageSize: PAGE_SIZE });
+  });
+
+  it("keeps the page when another query parameter changes", () => {
+    const query = ref<LocationQuery>({ status: "pending" });
+    const { pagination } = mountTable(query);
+    pagination.value = { pageIndex: THIRD_PAGE, pageSize: PAGE_SIZE };
+
+    query.value = { status: "pending", record: "42" };
+
+    expect(pagination.value.pageIndex).toBe(THIRD_PAGE);
+  });
+
+  it("sends the pager back to page 1 when the filter goes away", () => {
+    const query = ref<LocationQuery>({ status: "pending" });
+    const { pagination } = mountTable(query);
+    pagination.value = { pageIndex: THIRD_PAGE, pageSize: PAGE_SIZE };
+
+    query.value = {};
+
+    expect(pagination.value.pageIndex).toBe(0);
+  });
+
+  it("starts at page 1 when a link remounts the page under another value", async () => {
+    const first = mountTable(ref<LocationQuery>({ status: "pending" }));
+    first.pagination.value = { pageIndex: THIRD_PAGE, pageSize: PAGE_SIZE };
+    await nextTick();
+
+    const other = mountTable(ref<LocationQuery>({ status: "completed" }));
+    expect(other.pagination.value).toEqual({
+      pageIndex: 0,
+      pageSize: PAGE_SIZE,
+    });
+  });
+
+  it("restores the page of a remount under the same value", async () => {
+    const first = mountTable(ref<LocationQuery>({ status: "pending" }));
+    first.pagination.value = { pageIndex: THIRD_PAGE, pageSize: PAGE_SIZE };
+    await nextTick();
+
+    const again = mountTable(ref<LocationQuery>({ status: "pending" }));
+    expect(again.pagination.value.pageIndex).toBe(THIRD_PAGE);
+  });
+
+  it("keeps a page stored before its hidden filters were", () => {
+    cookie.value = {
+      tables: {
+        tasks: {
+          "query-filters": {
+            pagination: { pageIndex: THIRD_PAGE, pageSize: PAGE_SIZE },
+          },
+        },
+      },
+    };
+    const table = mountTable(ref<LocationQuery>({}));
+    expect(table.pagination.value.pageIndex).toBe(THIRD_PAGE);
+  });
+
+  it("starts a load-more list over from one page", async () => {
+    const query = ref<LocationQuery>({ status: "pending" });
+    const hiddenFilters = hiddenFiltersOf(() => query.value);
+    const pagination = ref({ pageIndex: 0, pageSize: PAGE_SIZE });
+    const pages = useAccumulatedPages({
+      mode: "loadMore",
+      pagination,
+      resetOn: [hiddenFilters],
+    });
+    pages.loadNextPage();
+    expect(pages.requestedPagination.value.pageSize).toBe(PAGE_SIZE * 2);
+
+    query.value = { status: "cancelled" };
+    await nextTick();
+
+    expect(pages.requestedPagination.value).toEqual({
+      pageIndex: 0,
+      pageSize: PAGE_SIZE,
+    });
+  });
+});

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.1",
+  "version": "0.7.3",
   "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.0 <0.6.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