@antelopejs/dms 0.7.11 → 0.7.13

package/frontend-vue/tests/tab-url-slot.test.ts

@@ -0,0 +1,150 @@
+// @vitest-environment jsdom
+/**
+ * A tab set keeping its open tab in the URL writes the tab's slot
+ * (`?tab=tester`), which stays right when tabs are added or reordered, and
+ * still opens a tab named by its index (`?tab=2`). A tab's badge is a
+ * BlockText: an i18n key is written in the reader's language.
+ */
+import * as vue from "vue";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { useTab } from "../layers/dms-ui/app/composables/tab/useTab";
+import { TabEvents } from "../layers/dms-ui/app/composables/tab/types/events";
+import type { TabProps } from "../layers/dms-ui/app/composables/tab/types";
+import { AxeOrientation } from "../layers/dms-core/app/types/orientation";
+import { Color } from "../layers/dms-core/app/types/color";
+import { Size } from "../layers/dms-core/app/types/size";
+
+vi.mock("../layers/dms-ui/app/composables/chart/useChartFetch", () => ({
+  useChartFetch: () => ({ data: vue.ref(null) }),
+}));
+
+const ITEMS = [
+  { label: "Statistics", slot: "statistics" },
+  { label: "Documentation", slot: "documentation" },
+  { label: "Tester", slot: "tester" },
+];
+
+let route: { query: Record<string, string> };
+const push = vi.fn(async (to: { query: Record<string, string> }) => {
+  route.query = to.query;
+});
+
+function tabsAt(query: Record<string, string>) {
+  route.query = query;
+  return useTab(ITEMS.length, {
+    items: ITEMS,
+    persistState: true,
+  } as TabProps);
+}
+
+beforeEach(() => {
+  route = vue.reactive({ query: {} });
+  push.mockClear();
+  for (const name of ["computed", "ref", "watch", "useTemplateRef"] as const)
+    vi.stubGlobal(name, vue[name]);
+  vi.stubGlobal("TabEvents", TabEvents);
+  vi.stubGlobal("isNumber", (value: unknown) => typeof value === "number");
+  vi.stubGlobal("isString", (value: unknown) => typeof value === "string");
+  vi.stubGlobal("useComponentEvent", () => ({ sendComponentEvent: vi.fn() }));
+  vi.stubGlobal("useWatch", () => ({
+    isLoading: vue.ref(false),
+    state: vue.ref({}),
+  }));
+  vi.stubGlobal("useDmsRoute", () => route);
+  vi.stubGlobal("useDmsRouter", () => ({ push }));
+});
+
+afterEach(() => vi.unstubAllGlobals());
+
+describe("a tab in the URL", () => {
+  it("opens the tab its slot names", () => {
+    expect(tabsAt({ tab: "tester" }).activeTab.value).toBe("2");
+  });
+
+  it("still opens a tab named by its index", () => {
+    expect(tabsAt({ tab: "1" }).activeTab.value).toBe("1");
+  });
+
+  it("opens the first tab on a name it does not know", () => {
+    expect(tabsAt({ tab: "settings" }).activeTab.value).toBe("0");
+    expect(tabsAt({ tab: "7" }).activeTab.value).toBe("0");
+  });
+
+  it("writes the open tab's slot, and nothing for the first", async () => {
+    const { goToTab } = tabsAt({});
+    goToTab(2);
+    await vue.nextTick();
+    expect(push).toHaveBeenLastCalledWith({ query: { tab: "tester" } });
+    goToTab("statistics");
+    await vue.nextTick();
+    expect(push).toHaveBeenLastCalledWith({ query: {} });
+  });
+
+  it("follows a URL naming another slot", async () => {
+    const { activeTab } = tabsAt({});
+    route.query = { tab: "documentation" };
+    await vue.nextTick();
+    expect(activeTab.value).toBe("1");
+  });
+});
+
+describe("a tab's badge", () => {
+  interface TabsItem {
+    badge?: unknown;
+  }
+  let received: TabsItem[] = [];
+  let app: vue.App | undefined;
+
+  const Tabs = vue.defineComponent({
+    props: { items: { type: Array, default: () => [] } },
+    setup: (props) => () => {
+      received = props.items as TabsItem[];
+      return vue.h("div");
+    },
+  });
+
+  async function badgesOf(badges: unknown[]): Promise<unknown[]> {
+    vi.stubGlobal("AxeOrientation", AxeOrientation);
+    vi.stubGlobal("Color", Color);
+    vi.stubGlobal("Size", Size);
+    vi.stubGlobal("useI18n", () => ({
+      locale: vue.ref("en"),
+      t: (key: string) => `t(${key})`,
+    }));
+    vi.stubGlobal("useTranslation", () => ({ processI18n: String }));
+    vi.stubGlobal("useTab", () => ({ activeTab: vue.ref("0") }));
+    vi.stubGlobal("useTabShortcuts", () => {});
+    const { default: Tab } = await import(
+      "../layers/dms-ui/app/components/tab/Tab.vue"
+    );
+    app = vue.createApp({
+      render: () =>
+        vue.h(Tab, {
+          items: badges.map((badge, index) => ({ ...ITEMS[index], badge })),
+        }),
+    });
+    app.component("UTabs", Tabs);
+    app.mount(document.createElement("div"));
+    await vue.nextTick();
+    app.unmount();
+    return received.map((item) => item.badge);
+  }
+
+  it("writes an i18n key, a composed text and a badge label in the reader's language", async () => {
+    expect(
+      await badgesOf([
+        "$api.tabs.beta",
+        { key: "api.tabs.count" },
+        { label: "$api.tabs.new", color: "primary" },
+      ]),
+    ).toEqual([
+      "t(api.tabs.beta)",
+      "t(api.tabs.count)",
+      { label: "t(api.tabs.new)", color: "primary" },
+    ]);
+  });
+
+  it("keeps a count and a plain text as they are", async () => {
+    expect(await badgesOf([3, "Beta"])).toEqual([3, "Beta"]);
+  });
+});

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

@@ -292,3 +292,93 @@ it("holds the table while its first row is scrolled out of view", async () => {
   expect(refresh).toHaveBeenCalledTimes(2);
   element.remove();
 });
+
+it("holds the table alone while searching or sorted, saying why", async () => {
+  const isSearching = ref(false);
+  const isSorted = ref(false);
+  const isRowOpen = ref(false);
+  const { refresh, hold } = mountTable({
+    liveHold: { whileSearching: true, whileSorted: true, whileRowOpen: true },
+    signals: {
+      isSearching: () => isSearching.value,
+      isSorted: () => isSorted.value,
+      isRowOpen: () => isRowOpen.value,
+    },
+  });
+  expect(hold.reason.value).toBe(null);
+
+  isSorted.value = true;
+  await nextTick();
+  publish();
+  expect(refresh).not.toHaveBeenCalled();
+  expect(hold.reason.value).toBe("sorted");
+
+  isSearching.value = true;
+  await nextTick();
+  expect(hold.reason.value).toBe("searching");
+
+  isRowOpen.value = true;
+  await nextTick();
+  expect(hold.reason.value).toBe("rowOpen");
+
+  // Paused, the page's toggle says why: the table names no reason.
+  live.pause();
+  await nextTick();
+  expect(hold.isHolding.value).toBe(true);
+  expect(hold.reason.value).toBe(null);
+});
+
+it("holds for no search nor sort the options leave off", async () => {
+  const { refresh, hold } = mountTable({
+    liveHold: { whileRowOpen: true },
+    signals: { isSearching: () => true, isSorted: () => true },
+  });
+  publish();
+  expect(refresh).toHaveBeenCalledTimes(1);
+  expect(hold.reason.value).toBe(null);
+});
+
+it("tells the hold about the table's search and sort, and the banner why", () => {
+  expect(tableViewSource).toContain(
+    "isSearching: () => !!effectiveGlobalFilter.value,",
+  );
+  expect(tableViewSource).toContain(
+    "isSorted: () => !isSameSorting(effectiveSorting.value, defaultSortState),",
+  );
+  expect(tableViewSource).toMatch(
+    /v-if="liveHold\.newCount\.value > 0 \|\| liveHold\.reason\.value"/,
+  );
+  expect(tableViewSource).toContain(':reason="liveHold.reason.value"');
+});
+
+it("hands the strip the paused page's breakdown and the table's missedLabel", async () => {
+  const isRowOpen = ref(false);
+  const { hold } = mountTable({
+    liveHold: { whileRowOpen: true, missedLabel: "$api.live.new_requests" },
+    signals: { isRowOpen: () => isRowOpen.value },
+  });
+  expect(hold.missedLabel).toBe("$api.live.new_requests");
+  const detail = { text: "$api.live.in_5xx", params: { count: 1 } };
+
+  // Held by an open row, the page live: the page has no breakdown to give.
+  isRowOpen.value = true;
+  await nextTick();
+  publish();
+  live.setMissedDetail(detail);
+  expect(hold.missedDetail.value).toBe(null);
+
+  live.pause();
+  await nextTick();
+  publish();
+  live.setMissedDetail(detail);
+  expect(hold.missedDetail.value).toEqual(detail);
+
+  live.resume();
+  await nextTick();
+  expect(hold.missedDetail.value).toBe(null);
+});
+
+it("passes the strip its wording and breakdown", () => {
+  expect(tableViewSource).toContain(':missed-label="liveHold.missedLabel"');
+  expect(tableViewSource).toContain(':detail="liveHold.missedDetail.value"');
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@antelopejs/dms",
-  "version": "0.7.11",
+  "version": "0.7.13",
   "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.6 <0.6.0",
+    "@antelopejs/interface-dms": ">=0.5.8 <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

@@ -42,12 +42,21 @@ For the framework underneath (the core, `ajs` CLI, interfaces as versioned contr
   (`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
+  `liveHold: true` keeps a table's rows while paused; `liveHold: { whileRowOpen, whileScrolled,
+  whileSearching, whileSorted }` also holds the table alone, its strip saying why ("Table on hold ·
+  search active"); `liveHold.missedLabel` words its "N new", and paused, it adds the
+  `setMissedDetail()` breakdown ("12 new requests · 2 in 5xx"). 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
+  `release()` and adds a breakdown with `setMissedDetail()`; a custom component that reads its own data
+  on a topic calls `usePageLiveRefresh(refresh, { realtimeTopic, idleRefresh })`, gated exactly like a
+  built-in block (never a throttle of its own); `refreshPageBlocks()` (user actions) always
   reads, `refreshLivePageBlocks()` (timers, feeds) is held while paused.
+  A custom component on a record page names its record at the end of the breadcrumb with
+  `usePageRecordLabel().setLabel(useDmsRoute().path, label)` (auto-imported; never the `build/` path).
+  A custom component formats through `useRegionalFormat()` (`formatNumber` & co. return `string` for a
+  number); `useRegionalFormat({ locale: "format" })` writes in `formatLocale`, the locale of the DMS's
+  texts (`en` → `en-GB`) — never a hand-rolled `en` → `en-GB` mapping.
   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.
@@ -66,6 +75,8 @@ For the framework underneath (the core, `ajs` CLI, interfaces as versioned contr
   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.
+  An `ActivityFeed` whose entries must be read whole sets `wrap: true` (no ellipsis; leave `fillHeight`
+  off so the card grows) and `visibleItems: N` for a "Show N more" fold.
   A unit after a number field is `NumberType({ suffix: "$…days" })`, a character counter on a
   text field `StringType({ maxLength, showCount: true })` — no custom `inputComponent` for either.
   A `TableView` over a shared controller hides a column on one page with
@@ -73,8 +84,21 @@ For the framework underneath (the core, `ajs` CLI, interfaces as versioned contr
   just to hide it.
   A long sectioned `Form` groups its navigation with `FormSection.navGroup` ("Billing", "Legal"),
   in the side list and in the `sectionNav: "jump"` chips alike (a form whose side column holds a preview).
+  A module's own `inputComponent` submits its form, adds a validator and focuses a field with
+  `useEnclosingForm()` (never `closest("form")` / `requestSubmit()`), and a link ending in `#<fieldId>`
+  opens the form on that field, focused. `DmsInputNumber` emits `adjust` (`{ typed, value, reason:
+  "min" | "max" | "step" }`) when it keeps another value than the one typed, and redraws the kept
+  value itself: a note "1020 → 1,000" listens to it — never a forced remount (`:key`).
   `TopListCard({ actions })` puts link buttons in its head ("Catalogue →"), and `Tab({ fit: true })`
-  keeps a pill tab list to its tabs' width.
+  keeps a pill tab list to its tabs' width; with `persistState` the URL names the open tab by its slot
+  (`?tab=tester`, an index still read), and a tab `badge` takes a `$` key or a `ComposedText`. A `ChartCard` plotting several series names them with
+  `showSeriesLegend: true` (placed by the chart's `legendPosition: "top" | "bottom"`) — never a raw
+  Apex `legend` in `rawOptions`.
+  A custom component brings a block of its page into view with `scrollToBlock("tabs.statistics")`
+  (the block's key path; `false` when it is not on screen) — never a DOM query of its own.
+  Code in a custom component is a `DmsCodeSnippet` (`language`, `title`, `maxLines` or a CSS
+  `maxHeight`, `wrap: true | "anywhere"`; without title and language its copy button floats in the
+  corner) — never a `<pre>` and copy button of the module's own.
   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).
   A table ordered by hand (`reorder: { field }`) moves its rows on the grid and its cards on

package/skills/dms-module/SKILL.md

@@ -93,7 +93,8 @@ Three constraints are enforced at registration: a page's `category` must **desce
 module root** (nest under what `RegisterModule` returned, or rely on `defaultCategory`),
 module pages cannot use the Settings category, and the module must exist before a page names
 it. Pages resolve at `/modules/<moduleId>/<urlSlug>`; entering the module lands on
-`landingPage` if set, else the first page by `order`. Access is **owner-only by design**: the
+`landingPage` if set, else the first page by `order` — `/modules/<id>` itself redirects there (server
+redirect, query and hash kept), so never register a hidden page to forward it. Access is **owner-only by design**: the
 Modules group is visible to the platform owner alone (the `*` holder), and the
 `modules.<moduleId>.…` permission ids are module-scoped — never grantable through Roles. On a
 SaaS deployment that means you, the maker, not your customers; a screen for end users belongs