@antelopejs/dms 0.7.9 → 0.7.10

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

@@ -4,6 +4,8 @@ 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";
+import { useTablePreferences } from "../layers/dms-ui/app/build/composables/table-view/useTablePreferences";
+import { tablePreferenceId } from "../layers/dms-core/app/build/composables/user/tablePreferences";
 
 const PAGE_SIZE = 10;
 const THIRD_PAGE = 2;
@@ -16,19 +18,18 @@ const hiddenFiltersOf = (query: () => LocationQuery) =>
       : [{ accessorKey: "status", mode: "is", value: query().status }],
   );
 
-const TABLE_KEY = "tables.tasks.query-filters";
-const preferenceKey = (suffix: string) => `${TABLE_KEY}.${suffix}`;
+const COMPONENT_ID = "tasks";
+const PAGE_ID = "query-filters";
 
-// The `user-preferences` cookie, surviving the remounts of a page.
-let cookie: Ref<Record<string, unknown>>;
+// The `dms-preferences` cookie, surviving the remounts of a page.
+let cookie: Ref<string>;
 
 // 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,
+    preferences: useTablePreferences(COMPONENT_ID, PAGE_ID),
     defaults: { pageIndex: 0, pageSize: PAGE_SIZE },
     scope: () => [hiddenFilters.value, []],
   });
@@ -36,8 +37,9 @@ const mountTable = (query: Ref<LocationQuery>) => {
 };
 
 beforeEach(() => {
-  cookie = ref({});
+  cookie = ref("");
   vi.stubGlobal("useDmsCookie", () => cookie);
+  vi.stubGlobal("usePreferences", usePreferences);
   vi.stubGlobal("ref", ref);
   vi.stubGlobal("readonly", readonly);
   vi.stubGlobal("computed", computed);
@@ -100,16 +102,11 @@ describe("a hidden filter changed by the URL", () => {
     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 },
-          },
-        },
-      },
-    };
+  it("keeps a page stored without its hidden filters", () => {
+    usePreferences().setPreference(
+      `tables.${tablePreferenceId(COMPONENT_ID, PAGE_ID)}`,
+      { p: [PAGE_SIZE, THIRD_PAGE] },
+    );
     const table = mountTable(ref<LocationQuery>({}));
     expect(table.pagination.value.pageIndex).toBe(THIRD_PAGE);
   });

package/frontend-vue/tests/table-view-pinned-rows.test.ts

@@ -0,0 +1,143 @@
+/**
+ * `pinnedRows`: the rows a rule accepts lead the list whatever the sort — the
+ * base language of a languages table stays on top whichever column the user
+ * sorts on, and on the first page.
+ */
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { describe, expect, it, vi } from "vitest";
+import {
+  processSourceRows,
+  useTableRows,
+} from "../layers/dms-ui/app/build/composables/table-view/useTableRows";
+import { pinRows } from "../layers/dms-ui/app/build/composables/table-view/utils/pinnedRows";
+import type { TableViewColumn } from "../layers/dms-ui/app/composables/table-view/types";
+
+interface LanguageRow extends Record<string, unknown> {
+  _id: string;
+  name: string;
+  coverage: number;
+  isBase: boolean;
+}
+
+const LANGUAGES: LanguageRow[] = [
+  { _id: "de", name: "Deutsch", coverage: 40, isBase: false },
+  { _id: "en", name: "English", coverage: 100, isBase: true },
+  { _id: "fr", name: "Français", coverage: 90, isBase: false },
+  { _id: "es", name: "Español", coverage: 10, isBase: false },
+];
+
+const COLUMNS = [
+  { id: "name", accessorKey: "name" },
+  { id: "coverage", accessorKey: "coverage" },
+] as TableViewColumn[];
+
+const BASE = { field: "isBase", equals: true };
+
+type Api = Parameters<typeof useTableRows>[0]["api"];
+
+const ids = (rows: LanguageRow[]) => rows.map((row) => row._id);
+
+describe("pinRows", () => {
+  it("puts the rows the rule accepts first, each part in its order", () => {
+    expect(
+      ids(pinRows(LANGUAGES, { field: "coverage", in: [10, 100] })),
+    ).toEqual(["en", "es", "de", "fr"]);
+  });
+
+  it("leaves the rows as they are without a rule, or when none matches", () => {
+    expect(pinRows(LANGUAGES, undefined)).toBe(LANGUAGES);
+    expect(pinRows(LANGUAGES, { field: "_id", equals: "it" })).toBe(LANGUAGES);
+  });
+});
+
+describe("a source sorted in the browser", () => {
+  it("keeps the pinned row first in either direction", () => {
+    const ascending = processSourceRows(
+      LANGUAGES,
+      { sortKey: "coverage", sortDirection: "asc" },
+      {},
+      COLUMNS,
+      BASE,
+    );
+    const descending = processSourceRows(
+      LANGUAGES,
+      { sortKey: "name", sortDirection: "desc" },
+      {},
+      COLUMNS,
+      BASE,
+    );
+    expect(ids(ascending.results)).toEqual(["en", "es", "de", "fr"]);
+    expect(ids(descending.results)).toEqual(["en", "fr", "es", "de"]);
+  });
+
+  it("pins before the page is cut: the pinned row opens the first page", () => {
+    const query = { sortKey: "coverage", sortDirection: "asc", limit: 2 };
+    const first = processSourceRows(LANGUAGES, query, {}, COLUMNS, BASE);
+    const second = processSourceRows(
+      LANGUAGES,
+      { ...query, offset: 2 },
+      {},
+      COLUMNS,
+      BASE,
+    );
+    expect(ids(first.results)).toEqual(["en", "es"]);
+    expect(ids(second.results)).toEqual(["de", "fr"]);
+    expect(first.total).toBe(4);
+  });
+});
+
+describe("rows a route sorts", () => {
+  it("pins within the list a source route sorted itself", async () => {
+    const sortedByRoute = [...LANGUAGES].sort(
+      (a, b) => a.coverage - b.coverage,
+    );
+    const api = vi.fn(async () => ({ results: sortedByRoute, total: 4 }));
+    const rows = useTableRows<LanguageRow>({
+      api: api as unknown as Api,
+      location: "/api/languages",
+      source: { fetchUrl: "/api/languages", capabilities: { sort: true } },
+      columns: COLUMNS,
+      pinnedRows: () => BASE,
+    });
+    const page = await rows.list({ sortKey: "coverage", sortDirection: "asc" });
+    expect(ids(page!.results)).toEqual(["en", "es", "de", "fr"]);
+  });
+
+  it("pins within the page a controller answers, read on each request", async () => {
+    const api = vi.fn(async () => ({
+      results: LANGUAGES,
+      total: 40,
+      offset: 0,
+      limit: 4,
+    }));
+    let pinned: typeof BASE | undefined = BASE;
+    const rows = useTableRows<LanguageRow>({
+      api: api as unknown as Api,
+      location: "/api/languages",
+      columns: COLUMNS,
+      pinnedRows: () => pinned,
+    });
+    expect(ids((await rows.list({}))!.results)).toEqual([
+      "en",
+      "de",
+      "fr",
+      "es",
+    ]);
+    pinned = undefined;
+    expect(ids((await rows.list({}))!.results)).toEqual(ids(LANGUAGES));
+  });
+});
+
+it("hands the table view's pinnedRows to its rows, except while grouped", () => {
+  const source = readFileSync(
+    resolve(
+      __dirname,
+      "../layers/dms-ui/app/components/table-view/TableView.vue",
+    ),
+    "utf8",
+  );
+  expect(source).toMatch(
+    /pinnedRows: \(\) => \(isGroupedDisplay\.value \? undefined : props\.pinnedRows\)/,
+  );
+});

package/frontend-vue/tests/table-view-sortable-columns.test.ts

@@ -1,3 +1,5 @@
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
 import { describe, expect, it, vi } from "vitest";
 import enGB from "../layers/dms-ui/i18n/locales/ui-en-GB.json";
 import frFR from "../layers/dms-ui/i18n/locales/ui-fr-FR.json";
@@ -13,6 +15,7 @@ import {
   sanitizeSorting,
   sortableColumnIds,
   sortDirectionLabelKey,
+  sortingOrDefault,
   sortValueKind,
 } from "../layers/dms-ui/app/build/composables/table-view/utils/sortableColumns";
 
@@ -92,6 +95,48 @@ describe("sanitizeSorting", () => {
   });
 });
 
+describe("sortingOrDefault", () => {
+  const byDueDate = [{ id: "due_date", desc: true }];
+
+  it("keeps a sort the route serves", () => {
+    const sorting = [{ id: "completion_percentage", desc: false }];
+    expect(sortingOrDefault(sorting, sortable, byDueDate)).toEqual(sorting);
+  });
+
+  // Clearing the sort (a third click on a header) used to be remembered as
+  // `[]`: the table then listed in the database's natural order for good.
+  it("goes back to the default sort once the user clears theirs", () => {
+    expect(sortingOrDefault([], sortable, byDueDate)).toEqual(byDueDate);
+    expect(sortingOrDefault(null, sortable, byDueDate)).toEqual(byDueDate);
+    expect(
+      sortingOrDefault([{ id: "name", desc: false }], sortable, byDueDate),
+    ).toEqual(byDueDate);
+  });
+
+  it("stays unsorted without a default, or when the route refuses it", () => {
+    expect(sortingOrDefault([], sortable, [])).toEqual([]);
+    expect(
+      sortingOrDefault([], new Set(["completion_percentage"]), byDueDate),
+    ).toEqual([]);
+  });
+
+  it("is what the table view restores, and corrects, its sort with", () => {
+    const tableView = readFileSync(
+      resolve(
+        __dirname,
+        "../layers/dms-ui/app/components/table-view/TableView.vue",
+      ),
+      "utf8",
+    );
+    expect(tableView).toMatch(
+      /const sorting = ref<SortingState>\(\s*sortingOrDefault\(/,
+    );
+    expect(tableView).toMatch(
+      /const sanitized = sortingOrDefault\(\s*next,\s*sortableIds\.value,\s*defaultSortState,\s*\);/,
+    );
+  });
+});
+
 describe("resolveDefaultSort", () => {
   it("uses a sortable default sort", () => {
     expect(

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

@@ -15,6 +15,7 @@ import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import TableViews from "../layers/dms-ui/app/build/components/table/Views.vue";
 import { mergeColumnOrder } from "../layers/dms-ui/app/build/composables/table/utils/columnOrder";
 import { useTableViews } from "../layers/dms-ui/app/build/composables/table-view/useTableViews";
+import type { TablePreferences } from "../layers/dms-ui/app/build/composables/table-view/useTablePreferences";
 import {
   isSameTableState,
   readTableUrlKey,
@@ -211,12 +212,22 @@ describe("useTableViews", () => {
     const preferences = new Map<string, unknown>(
       Object.entries(options.preferences ?? {}),
     );
-    vi.stubGlobal("usePreferences", () => ({
-      getPreference: (key: string, fallback: unknown) =>
-        preferences.has(key) ? preferences.get(key) : fallback,
-      setPreference: (key: string, value: unknown) =>
-        preferences.set(key, value),
-    }));
+    // `useTablePreferences`: the browser-only fields come back once mounted.
+    const restores: Array<() => void> = [];
+    const tablePreferences: TablePreferences = {
+      get: <V>(field: string, fallback: V) =>
+        (preferences.has(field) ? preferences.get(field) : fallback) as V,
+      set: (field, value) => {
+        preferences.set(field, value);
+      },
+      restore: (field, state) => {
+        restores.push(() => {
+          if (preferences.has(field)) {
+            state.value = preferences.get(field) as typeof state.value;
+          }
+        });
+      },
+    };
     vi.stubGlobal("useUserSession", () => ({
       user: ref({ _id: options.userId ?? "u1" }),
     }));
@@ -244,11 +255,15 @@ describe("useTableViews", () => {
     app = createApp(
       defineComponent({
         setup() {
+          onMounted(() => restores.forEach((restore) => restore()));
+          // As the table view does, before its views.
+          tablePreferences.restore("density", state.density);
+          tablePreferences.restore("columnOrder", state.columnOrder);
           api = useTableViews({
             views: options.views,
             defaults: DEFAULTS,
             state,
-            preferenceKey: (suffix) => `tables.content.page.${suffix}`,
+            preferences: tablePreferences,
             urlScope: { tableId: "content", isSoleTableView: true },
           });
           return () => h("div");
@@ -300,7 +315,7 @@ describe("useTableViews", () => {
     const { api, state } = await mountViews({
       views: VIEWS,
       query: { view: "mine" },
-      preferences: { "tables.content.page.activeView": "all" },
+      preferences: { activeView: "all" },
     });
     expect(api.activeViewId.value).toBe("mine");
     expect(state.columnFilters.value).toEqual([
@@ -323,13 +338,43 @@ describe("useTableViews", () => {
     ]);
   });
 
+  it("opens a user view the URL names once its views are restored in the browser", async () => {
+    const { api } = await mountViews({
+      views: VIEWS,
+      query: { view: "user-mine" },
+      preferences: {
+        userViews: [
+          { id: "user-mine", label: "Mine", ownerId: "u1", search: "x" },
+        ],
+      },
+    });
+    expect(api.activeViewId.value).toBe("user-mine");
+    expect(toasts).toEqual([]);
+  });
+
+  it("restores the browser-only state, a view opened on arrival keeping its own", async () => {
+    const opened = await mountViews({
+      views: VIEWS,
+      query: { view: "all" },
+      preferences: { density: "compact" },
+    });
+    expect(opened.state.density.value).toBe("default");
+    app?.unmount();
+
+    const kept = await mountViews({
+      views: VIEWS,
+      preferences: { density: "compact", activeView: "" },
+    });
+    expect(kept.state.density.value).toBe("compact");
+  });
+
   it("opens the default view on a first visit only", async () => {
     const first = await mountViews({ views: VIEWS });
     expect(first.api.activeViewId.value).toBe("all");
     app?.unmount();
     const later = await mountViews({
       views: VIEWS,
-      preferences: { "tables.content.page.activeView": "" },
+      preferences: { activeView: "" },
     });
     expect(later.api.activeViewId.value).toBe(undefined);
   });
@@ -354,9 +399,7 @@ describe("useTableViews", () => {
       views: VIEWS,
       viewName: " Printers ",
       preferences: {
-        "tables.content.page.userViews": [
-          { id: "user-x", label: "Theirs", ownerId: "u2" },
-        ],
+        userViews: [{ id: "user-x", label: "Theirs", ownerId: "u2" }],
       },
     });
     state.globalFilter.value = "printer";
@@ -373,9 +416,7 @@ describe("useTableViews", () => {
       "i18n:tickets.mine",
       "Printers",
     ]);
-    expect(
-      (preferences.get("tables.content.page.userViews") as unknown[]).length,
-    ).toBe(2);
+    expect((preferences.get("userViews") as unknown[]).length).toBe(2);
 
     state.density.value = "compact";
     await nextTick();

package/frontend-vue/tests/top-list-card-value-suffix.test.ts

@@ -0,0 +1,107 @@
+/**
+ * A TopListCard writes its unit after each formatted value (`valueSuffix`),
+ * and a row's `valueLabel` replaces the formatted value outright.
+ */
+import { createSSRApp, defineComponent, h, ref } from "vue";
+import { renderToString } from "vue/server-renderer";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import TopListCard from "../layers/dms-ui/app/components/top-list/TopListCard.vue";
+
+const rows = ref<Array<Record<string, unknown>>>([]);
+
+vi.mock("../layers/dms-ui/app/composables/chart/useChartFetch", () => ({
+  useChartFetch: () => ({
+    data: ref({ items: rows.value }),
+    isLoading: ref(false),
+  }),
+}));
+
+const Slot = defineComponent({
+  setup:
+    (_, { slots }) =>
+    () =>
+      h("div", slots.default?.()),
+});
+
+async function render(props: Record<string, unknown>): Promise<string> {
+  const app = createSSRApp({
+    render: () =>
+      h(TopListCard, {
+        title: "Slowest routes",
+        componentId: "slowest",
+        pageId: "overview",
+        showDelta: false,
+        valuePrecision: 0,
+        ...props,
+      }),
+  });
+  for (const name of [
+    "DmsCard",
+    "DmsLink",
+    "UBadge",
+    "UIcon",
+    "USkeleton",
+    "UButton",
+  ]) {
+    app.component(name, Slot);
+  }
+  return renderToString(app);
+}
+
+/** The text of each row's value cell. */
+function values(html: string): string[] {
+  return [...html.matchAll(/<span class="text-toned[^"]*"[^>]*>([^<]*)</g)].map(
+    (match) => (match[1] ?? "").trim(),
+  );
+}
+
+beforeEach(() => {
+  rows.value = [
+    { id: "a", title: "GET /orders", value: 1864 },
+    { id: "b", title: "GET /cart", value: 296 },
+  ];
+  vi.stubGlobal("useI18n", () => ({ locale: ref("en-US"), t: String }));
+  vi.stubGlobal("useTranslation", () => ({
+    processI18n: (text: string) => (text.startsWith("$") ? `t(${text})` : text),
+  }));
+  vi.stubGlobal("useComponentEvent", () => ({}));
+  vi.stubGlobal("useWatch", () => ({ state: ref({}) }));
+});
+
+afterEach(() => vi.unstubAllGlobals());
+
+describe("TopListCard value unit", () => {
+  it("writes the bare formatted value by default", async () => {
+    expect(values(await render({}))).toEqual(["1,864", "296"]);
+  });
+
+  it("writes the suffix right after each value", async () => {
+    expect(values(await render({ valueSuffix: " ms" }))).toEqual([
+      "1,864 ms",
+      "296 ms",
+    ]);
+  });
+
+  it("translates a `$` suffix", async () => {
+    expect(values(await render({ valueSuffix: "$units.ms" }))).toEqual([
+      "1,864t($units.ms)",
+      "296t($units.ms)",
+    ]);
+  });
+
+  it("writes a row's valueLabel as is, without the suffix", async () => {
+    rows.value = [
+      {
+        id: "a",
+        title: "GET /orders",
+        value: 1864,
+        valueLabel: "1.9 s (partial)",
+      },
+      { id: "b", title: "GET /cart", value: 296 },
+    ];
+    expect(values(await render({ valueSuffix: " ms" }))).toEqual([
+      "1.9 s (partial)",
+      "296 ms",
+    ]);
+  });
+});

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

package/package.json

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

@@ -39,9 +39,15 @@ For the framework underneath (the core, `ajs` CLI, interfaces as versioned contr
   (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.
+  (`slowRateAfter: { period: "7d", maxRate: 60 }` for long periods, `rememberKey: "<module>"` to share the
+  choice between pages; `maxRate` is also the polling interval while the stream is down) and places a
+  `LiveToggle()` (Live / Pause, L key; `variant: "pill"`, `missedLabel` for "N new requests").
+  `liveHold: true` keeps a table's rows while paused; `liveHold: { whileRowOpen, whileScrolled }` also
+  holds the table alone. Paused, an event counts as its `payload.ids` rows or its `payload.count`, so a
+  module may batch publishes with `{ count }`. A hidden tab and `?live=0` pause the page too.
+  A custom component follows that state with `usePageLive()`, holds the page with `hold(reason)` /
+  `release()` and adds a breakdown with `setMissedDetail()`; `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.

package/skills/dms-module/SKILL.md

@@ -82,6 +82,11 @@ releases the frontend module runs on go in the frontend module's own `package.js
 `"engines": { "@antelopejs/dms-frontend": ">=0.4.0 <0.5.0" }`: the loader refuses the module
 outside that range. Cap it below the next loader minor while the loader is 0.x.
 
+An absolute link (a public file, a snippet to copy, a mail) is built on `await GetApiBaseUrl()`
+(`@antelopejs/interface-dms/api-base-url`, the backend) or `await GetClientBaseUrl()`
+(`/client-base-url`, the dashboard), never on `Host` / `X-Forwarded-*`: a reverse proxy may not
+forward them. Both answer the DMS config (`apiBaseUrl`, `clientBaseUrl`).
+
 ## Navigation & access — module pages are owner-only
 
 Three constraints are enforced at registration: a page's `category` must **descend from the

package/skills/dms-pages/REFERENCE.md

@@ -9,7 +9,7 @@ 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`; display blocks
+`Guard`, `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
@@ -19,6 +19,15 @@ button: `code` + `language`, or `fetchUrl` answering `{ code, language? }` — s
 behavioral DSL — permissioned `.action()`s and `.watch()` reactivity — see
 `docs/02.building/05.actions-and-reactivity.md`.
 
+`Guard({ fetchUrl, field?, when?, fallback? })` wraps any blocks and shows one `EmptyState`
+(`fallback`) in their place when the route says there is nothing: `when: "empty"` (default)
+checks the value at `field` (absent / `null` / `false` / `0` / `""` / `[]`), `when: "notFound"`
+a 404. The children show while loading and on any other failure; an `emptyState` in the
+answer is laid over `fallback` — `docs/04.components/03.layout-and-containers.md#guard`.
+A block whose `fetchUrl` answers 404 shows its own "Not found" (no retry), the 404 body's
+`message` / `emptyState` over it; a `Guard` with `when: "notFound"` draws the same state once
+for the blocks it wraps — `docs/04.components/11.display-blocks.md#not-found`.
+
 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
@@ -26,16 +35,28 @@ link changing its value sends the table back to page 1. A drawer or modal row ac
 gets `navigation` (J / K, `index` / `total` in the order shown) —
 `docs/04.components/06.tables/8.row-drawers.md`.
 
+A page's `headerActions` follow its URL: a target URL takes `{{params.X}}` / `{{query.X}}`
+(`?workspace={{query.workspace}}`, a pair the page has no value for is dropped), and an
+`availability` reads `context.query`, asked again when the query changes — no need to build
+the header in Vue with `usePageHeaderActions` to carry the scope —
+`docs/07.interfaces/3.base/6.layout.md#buttons-that-follow-the-page-url`.
+
 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`.
 To read rows one after the other next to the table (a request log), use a `sidePanel`
 target instead: a non-modal panel docked on the right whose header the DMS draws (title,
-`positionLabel` "x of y", previous / next, J / K, close), `?record=` kept by default (`deepLink: false` opts out) and the table's
+`rowTitle` naming the row from its fields, `positionLabel` "x of y", previous / next, J / K, close), `?record=` kept by default (`deepLink: false` opts out), a "not found" state on a 404 (`notFound: { title, description }`) and the table's
 `rowClick: "single"` (a `TableView.fromSource` table reads a deep-linked row beyond its first page through `fetchRowUrl: "/api/x/{id}"`) — never bridge the table's DOM to build one —
 `docs/04.components/06.tables/8.row-drawers.md#side-panel`.
 
+A row that must stay on top of a table under any sort (a base language, a default
+workspace) takes `pinnedRows: { field: "isBase", equals: true }` — never sort on the
+server for it. A row action names its row with `{field}` braces in its `label`
+(`"Translate {name}"`), and `rowActions.menuLabel` (`"Actions for {name}"`) names the
+row's ⋯ button — `docs/04.components/06.tables/0.index.md#pinned-rows`.
+
 ## DataTypes
 
 A field's `type` is a **DataType instance**: `new DefaultDataTypes.StringType({ … })`. The