@antelopejs/dms 0.4.8 → 0.5.1

package/frontend-vue/tests/page-fill-height.test.ts

@@ -0,0 +1,352 @@
+// @vitest-environment jsdom
+import {
+  computed,
+  createApp,
+  createSSRApp,
+  h,
+  inject,
+  nextTick,
+  onMounted,
+  onUnmounted,
+  provide,
+  reactive,
+  ref,
+  Suspense,
+  toRef,
+  watch,
+  type App,
+  type Component,
+  type FunctionalComponent,
+} from "vue";
+import { renderToString } from "vue/server-renderer";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import DefaultLayout from "../layers/dms-layout/app/custom-layouts/DefaultLayout.vue";
+import CatchAllPage from "../layers/dms-layout/app/pages/[...slug].vue";
+import {
+  PAGE_FILL_HEIGHT_CLASSES,
+  providePageFillHeight,
+  usePageFillHeight,
+} from "../layers/dms-layout/app/composables/layout/usePageFillHeight";
+
+vi.mock(
+  "../layers/dms-layout/app/build/components/layout/DashboardSidebar.vue",
+  () => ({ default: () => null }),
+);
+vi.mock(
+  "../layers/dms-layout/app/build/components/layout/DashboardHeader.vue",
+  () => ({ default: () => null }),
+);
+vi.mock(
+  "../layers/dms-layout/app/build/components/layout/DashboardBanners.vue",
+  () => ({ default: () => null }),
+);
+
+interface PageLayoutFixture {
+  components: Record<string, { componentName: string }>;
+}
+
+const route = reactive({ path: "/tools/explorer", query: {} });
+const pageLayout = ref<PageLayoutFixture | null>(null);
+
+// The markup `DefaultLayout` and `pages/[...slug].vue` rendered for a
+// two-component page before `fillHeight` existed, with the stubs below.
+const FLOW_PAGE_MARKUP =
+  "<div data-dms-persistent-shell data-group><!---->" +
+  "<div data-panel><!--[--><!----><!----><!--]-->" +
+  "<div data-body>" +
+  '<div class="w-full max-w-none" data-dms-page-region data-dms-page-content><!--[-->' +
+  '<section class="flex gap-4 items-start pt-6 pb-7">' +
+  '<div class="rounded-lg bg-primary/10 shrink-0 ring ring-primary/20 flex items-center justify-center size-12"><i class="text-primary"></i></div>' +
+  '<div class="flex-1 min-w-0">' +
+  '<h1 class="text-highlighted text-[22px] font-semibold leading-tight tracking-tight"><!--[-->Explorer<!--]--></h1><!--v-if--></div><!--[--><!--]--></section><!--[-->' +
+  '<div class="dms-page-stack space-y-6">' +
+  '<div class="">' +
+  '<section data-component="stats" page-id="tools.explorer"></section></div>' +
+  '<div class="">' +
+  '<section data-component="explorer" page-id="tools.explorer"></section></div></div><!--]--><!--]--></div></div><!--[--><!----><!--]--></div></div>';
+
+function withComponents(...ids: string[]): PageLayoutFixture {
+  return {
+    components: Object.fromEntries(
+      ids.map((id) => [id, { componentName: `tool-${id}` }]),
+    ),
+  };
+}
+
+// Functional stubs hand non-class attributes on only when told to: these two
+// spread them, so the markers the layout sets stay in the markup.
+const Group: FunctionalComponent = (_, { attrs, slots }) =>
+  h("div", { ...attrs, "data-group": "" }, slots.default?.());
+Group.inheritAttrs = false;
+
+const Panel: FunctionalComponent = (_, { slots }) =>
+  h("div", { "data-panel": "" }, [
+    slots.header?.(),
+    h("div", { "data-body": "" }, slots.body?.()),
+    slots.footer?.(),
+  ]);
+
+// Nuxt UI merges its container classes with the ones it is given; the stub
+// keeps the given ones next to one of its own, so a lost class shows.
+const Container: FunctionalComponent = (_, { attrs, slots }) =>
+  h("div", { ...attrs, class: ["w-full", attrs.class] }, slots.default?.());
+Container.inheritAttrs = false;
+
+const PageComponent: FunctionalComponent<{ componentId: string }> = (props) =>
+  h("section", { "data-component": props.componentId });
+PageComponent.props = ["componentId"];
+
+const FillHeightProbe: FunctionalComponent = () =>
+  h("output", String(usePageFillHeight().value));
+
+function installRuntime(): void {
+  const runtime: Record<string, unknown> = {
+    computed,
+    inject,
+    onMounted,
+    onUnmounted,
+    provide,
+    ref,
+    toRef,
+    watch,
+    HTTP_FORBIDDEN: 403,
+    HTTP_INTERNAL_SERVER_ERROR: 500,
+    HTTP_NOT_FOUND: 404,
+    PAGE_FILL_HEIGHT_CLASSES,
+    providePageFillHeight,
+    usePageFillHeight,
+    createError: vi.fn(),
+    defineDmsPageMeta: vi.fn(),
+    firstAccessiblePagePath: vi.fn(),
+    navigateDms: vi.fn(),
+    preloadPageLayoutComponents: vi.fn(),
+    providePageRealtime: vi.fn(),
+    resolveDmsComponent: () => "div",
+    runCustomValidation: vi.fn(),
+    showError: vi.fn(),
+    validateRequiredQueryParams: vi.fn(),
+    useDefinedFunctions: () => ({ getFunction: () => undefined }),
+    useDevReloading: () => ref(false),
+    useDmsRoute: () => route,
+    useHomepage: () => "/",
+    usePageLayout: async () => ({ pageLayout }),
+    usePageRealtime: () => ({}),
+    usePermissions: () => ({
+      permissions: ref([]),
+      refreshIfStale: async () => {},
+    }),
+    useSessionRecovery: () => ({
+      loggedIn: ref(true),
+      reconcileSession: async () => {},
+      redirectToAuth: async () => {},
+    }),
+    useSiteLayout: () => ({
+      siteLayout: ref({ pages: {} }),
+      siteLayoutTree: ref([]),
+      loadingError: ref(null),
+      loadSiteLayout: async () => {},
+      refresh: async () => {},
+      refreshIfStale: async () => {},
+      findMatchingRoute: () => ({
+        metadata: { fullId: "tools.explorer", hasAccess: true },
+        params: {},
+      }),
+    }),
+    useTranslation: () => ({ processI18n: (value: string) => value }),
+  };
+  Object.entries(runtime).forEach(([name, value]) =>
+    vi.stubGlobal(name, value),
+  );
+}
+
+function withStubs(app: App): App {
+  app.component("UDashboardGroup", Group);
+  app.component("UDashboardPanel", Panel);
+  app.component("UContainer", Container);
+  app.component("UIcon", () => h("i"));
+  app.component("DmsAppWidgetsDock", () => null);
+  app.component("DmsRecursiveComponent", PageComponent);
+  return app;
+}
+
+function renderInLayout(
+  layoutProps: Record<string, unknown>,
+  page: Component,
+): Promise<string> {
+  const root = () =>
+    h(
+      DefaultLayout,
+      { title: "Explorer", ...layoutProps },
+      { default: () => h(page) },
+    );
+  return renderToString(withStubs(createSSRApp(root)));
+}
+
+function parse(markup: string): HTMLElement {
+  const host = document.createElement("div");
+  host.innerHTML = markup;
+  return host;
+}
+
+function classesOf(element: Element | null | undefined): string[] {
+  return element?.getAttribute("class")?.split(" ").filter(Boolean) ?? [];
+}
+
+function expectClasses(element: Element | null | undefined, classes: string) {
+  expect(classesOf(element)).toEqual(
+    expect.arrayContaining(classes.split(" ")),
+  );
+}
+
+function expectNoFillClasses(element: Element | null | undefined) {
+  const fillClasses = new Set(
+    `${PAGE_FILL_HEIGHT_CLASSES.region} ${PAGE_FILL_HEIGHT_CLASSES.column}`.split(
+      " ",
+    ),
+  );
+  expect(classesOf(element).filter((name) => fillClasses.has(name))).toEqual(
+    [],
+  );
+}
+
+beforeEach(() => {
+  installRuntime();
+  route.path = "/tools/explorer";
+  pageLayout.value = withComponents("stats", "explorer");
+});
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+});
+
+describe("usePageFillHeight", () => {
+  it("reads false under a layout that does not provide it", async () => {
+    const markup = await renderToString(createSSRApp(FillHeightProbe));
+    expect(markup).toBe("<output>false</output>");
+  });
+
+  it("follows the layout that provides it", async () => {
+    const fillHeight = ref(true);
+    const app = withStubs(
+      createApp(() =>
+        h(
+          DefaultLayout,
+          { fillHeight: fillHeight.value },
+          { default: () => h(FillHeightProbe) },
+        ),
+      ),
+    );
+    const host = document.createElement("div");
+    app.mount(host);
+    expect(host.querySelector("output")?.textContent).toBe("true");
+    fillHeight.value = false;
+    await nextTick();
+    expect(host.querySelector("output")?.textContent).toBe("false");
+    app.unmount();
+  });
+});
+
+describe("DefaultLayout without fillHeight", () => {
+  it("renders the page exactly as it did before the option existed", async () => {
+    expect(await renderInLayout({}, CatchAllPage)).toBe(FLOW_PAGE_MARKUP);
+  });
+
+  it("tells the page it does not fill the panel", async () => {
+    const markup = await renderInLayout({}, FillHeightProbe);
+    expect(parse(markup).querySelector("output")?.textContent).toBe("false");
+  });
+});
+
+describe("DefaultLayout with fillHeight", () => {
+  it("makes the page region a flex column with a minimum height", async () => {
+    const host = parse(
+      await renderInLayout({ fillHeight: true }, CatchAllPage),
+    );
+    const region = host.querySelector("[data-dms-page-content]");
+    expectClasses(region, PAGE_FILL_HEIGHT_CLASSES.region);
+    expectClasses(region, "w-full max-w-none");
+  });
+
+  it("keeps the page header a plain item of that column", async () => {
+    const host = parse(
+      await renderInLayout({ fillHeight: true }, CatchAllPage),
+    );
+    const header = host.querySelector("[data-dms-page-content] > section");
+    expect(classesOf(header)).toEqual([
+      "flex",
+      "gap-4",
+      "items-start",
+      "pt-6",
+      "pb-7",
+    ]);
+  });
+
+  it("gives the height left to the last component only", async () => {
+    const host = parse(
+      await renderInLayout({ fillHeight: true }, CatchAllPage),
+    );
+    const stack = host.querySelector(".dms-page-stack");
+    const [stats, explorer] = Array.from(stack?.children ?? []);
+    expectClasses(
+      stack,
+      `dms-page-stack space-y-6 ${PAGE_FILL_HEIGHT_CLASSES.column}`,
+    );
+    expectNoFillClasses(stats);
+    expectClasses(explorer, PAGE_FILL_HEIGHT_CLASSES.column);
+    expect(
+      explorer
+        ?.querySelector("[data-component]")
+        ?.getAttribute("data-component"),
+    ).toBe("explorer");
+  });
+
+  it("fills with the only component of a single-component page", async () => {
+    pageLayout.value = withComponents("explorer");
+    const host = parse(
+      await renderInLayout({ fillHeight: true }, CatchAllPage),
+    );
+    const wrappers = host.querySelectorAll(".dms-page-stack > div");
+    expect(wrappers).toHaveLength(1);
+    expectClasses(wrappers[0], PAGE_FILL_HEIGHT_CLASSES.column);
+  });
+
+  it("tells a custom page, rendered straight in the slot, to fill", async () => {
+    const markup = await renderInLayout({ fillHeight: true }, FillHeightProbe);
+    expect(parse(markup).querySelector("output")?.textContent).toBe("true");
+  });
+
+  it("drops the fill classes when a navigation lands on a page without the option", async () => {
+    const fillHeight = ref(true);
+    const app = withStubs(
+      createApp(() =>
+        h(
+          DefaultLayout,
+          { title: "Explorer", fillHeight: fillHeight.value },
+          {
+            default: () =>
+              h(Suspense, null, { default: () => h(CatchAllPage) }),
+          },
+        ),
+      ),
+    );
+    const host = document.createElement("div");
+    app.mount(host);
+    await vi.waitFor(() =>
+      expect(host.querySelector(".dms-page-stack")).not.toBeNull(),
+    );
+    expectClasses(
+      host.querySelector(".dms-page-stack"),
+      PAGE_FILL_HEIGHT_CLASSES.column,
+    );
+
+    fillHeight.value = false;
+    await nextTick();
+
+    expectNoFillClasses(host.querySelector("[data-dms-page-content]"));
+    expectNoFillClasses(host.querySelector(".dms-page-stack"));
+    host
+      .querySelectorAll(".dms-page-stack > div")
+      .forEach((wrapper) => expectNoFillClasses(wrapper));
+    app.unmount();
+  });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@antelopejs/dms",
-  "version": "0.4.8",
+  "version": "0.5.1",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/AntelopeJS/dms.git"
@@ -36,7 +36,7 @@
     "@antelopejs/interface-data-api": ">=0.1.9 <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.2.6 <1.0.0",
+    "@antelopejs/interface-dms": ">=0.3.2 <0.4.0",
     "@antelopejs/interface-email": ">=0.0.5 <1.0.0",
     "@antelopejs/interface-file-storage": ">=0.1.3 <1.0.0",
     "archiver": "^7.0.1",
@@ -52,8 +52,8 @@
     "zod": "~3.24.2"
   },
   "devDependencies": {
-    "@antelopejs/core": ">=1.9.1 <2",
-    "@antelopejs/tooling-configs": ">=0.0.6 <1.0.0",
+    "@antelopejs/core": ">=1.10.1 <2",
+    "@antelopejs/tooling-configs": ">=0.0.7 <1.0.0",
     "@types/archiver": "^6.0.4",
     "@types/chai": "^4.3.20",
     "@types/jsonwebtoken": "^9.0.10",
@@ -94,7 +94,7 @@
     "@antelopejs/interface-redis": ">=0.0.8 <1.0.0"
   },
   "peerDependencies": {
-    "@antelopejs/core": ">=1.9.1 <2"
+    "@antelopejs/core": ">=1.10.1 <2"
   },
   "peerDependenciesMeta": {
     "@antelopejs/core": {
@@ -107,7 +107,7 @@
     "dev": "ajs project run --inspect -w -p playground",
     "frontend:dev": "pnpm --dir playground frontend:dev",
     "lint:fix": "oxlint --fix --max-warnings=1000000 && oxfmt . && pnpm --dir frontend-vue lint:fix",
-    "lint": "oxlint && oxfmt --check . && pnpm --dir frontend-vue lint",
+    "lint": "oxlint && oxfmt --check . && pnpm --dir frontend-vue lint && antelopejs-check-interface-ranges",
     "typecheck": "pnpm --filter @antelopejs/interface-dms build && tsc --noEmit",
     "test": "pnpm run build && ajs module test .",
     "test:unit": "pnpm run build && DMS_TEST_DIR=dist/test/unit ajs module test .",

package/skills/dms-module/REFERENCE.md

@@ -19,7 +19,8 @@ first-party modules follow `dms-<name>` purely for discoverability.
         pages/                      # @RegisterPage classes + category.ts (see dms-pages)
         routes/                     # HTTP controllers feeding the components
         implementations/<name>/index.ts  # implementation of the module's own interface
-      frontend-vue/                 # Vue module: dms.frontend.ts, app/, i18n/locales/
+      frontend-vue/                 # Vue module: dms.frontend.ts, app/, i18n/locales/,
+                                    # package.json (engines: the loader releases it supports)
       package.json / tsconfig.json
     interface-<name>/               # the module's OWN interface, its own published package
       src/index.ts                  # (rare — many modules ship none)

package/skills/dms-module/SKILL.md

@@ -77,6 +77,11 @@ export function destroy(): void { /* deactivate subscriptions */ }
 register — it returns the module's root `CategoryInfo`. `AddFrontendModule` is what surfaces the
 module's frontend; without it the module is backend-only.
 
+`renderer` names the framework (Vue 3), not a loader release. The `@antelopejs/dms-frontend`
+releases the frontend module runs on go in the frontend module's own `package.json`, as
+`"engines": { "@antelopejs/dms-frontend": ">=0.3.2 <0.4.0" }`: the loader refuses the module
+outside that range. Cap it below the next loader minor while the loader is 0.x.
+
 ## Navigation & access — module pages are owner-only
 
 Three constraints are enforced at registration: a page's `category` must **descend from the

package/dist/realtime/tableview-bridge.d.ts

@@ -1 +0,0 @@
-export declare function installTableViewRealtimeBridge(): void;

package/dist/realtime/tableview-bridge.js

@@ -1,38 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.installTableViewRealtimeBridge = installTableViewRealtimeBridge;
-const table_view_1 = require("@antelopejs/interface-dms/base/table-view");
-const current_1 = require("./current");
-const registry_1 = require("./registry");
-const TABLEVIEW_ROW_TOPIC_PREFIX = "tableview:row:";
-const TABLEVIEW_PRESENCE_TOPIC_PREFIX = "tableview:presence:";
-const buildRowTopic = (location) => `${TABLEVIEW_ROW_TOPIC_PREFIX}${location}`;
-const buildPresenceTopic = (location) => `${TABLEVIEW_PRESENCE_TOPIC_PREFIX}${location}`;
-let isInstalled = false;
-function installTableViewRealtimeBridge() {
-    if (isInstalled)
-        return;
-    isInstalled = true;
-    (0, table_view_1.setRealtimeMutationHook)(async ({ controllerLocation, eventType, ids, sessionId, actor }) => {
-        await (0, current_1.getRealtimeBroker)().publish({
-            topic: buildRowTopic(controllerLocation),
-            type: eventType,
-            payload: { ids },
-            actorId: actor?.id,
-            ts: Date.now(),
-        });
-        if (sessionId && (eventType === "updated" || eventType === "deleted")) {
-            const presenceTopic = buildPresenceTopic(controllerLocation);
-            const tracker = (0, current_1.getPresenceTracker)();
-            await Promise.all(ids.map((id) => tracker.release(sessionId, presenceTopic, id)));
-        }
-    });
-    (0, table_view_1.setRealtimePresenceHook)(async ({ controllerLocation, sessionId, rowId, actor }) => {
-        await (0, current_1.getPresenceTracker)().acquire(sessionId, buildPresenceTopic(controllerLocation), rowId, actor);
-    });
-    (0, table_view_1.setRealtimePageTopicHook)(({ pageId, controllerLocation }) => {
-        (0, registry_1.registerPageTopic)(pageId, buildRowTopic(controllerLocation));
-        (0, registry_1.registerPageTopic)(pageId, buildPresenceTopic(controllerLocation));
-    });
-}
-//# sourceMappingURL=tableview-bridge.js.map

package/dist/realtime/tableview-bridge.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"tableview-bridge.js","sourceRoot":"","sources":["../../src/realtime/tableview-bridge.ts"],"names":[],"mappings":";;AAmBA,wEAsCC;AAzDD,0EAImD;AACnD,uCAAkE;AAClE,yCAA+C;AAE/C,MAAM,0BAA0B,GAAG,gBAAgB,CAAC;AACpD,MAAM,+BAA+B,GAAG,qBAAqB,CAAC;AAE9D,MAAM,aAAa,GAAG,CAAC,QAAgB,EAAU,EAAE,CACjD,GAAG,0BAA0B,GAAG,QAAQ,EAAE,CAAC;AAE7C,MAAM,kBAAkB,GAAG,CAAC,QAAgB,EAAU,EAAE,CACtD,GAAG,+BAA+B,GAAG,QAAQ,EAAE,CAAC;AAElD,IAAI,WAAW,GAAG,KAAK,CAAC;AAExB,SAAgB,8BAA8B;IAC5C,IAAI,WAAW;QAAE,OAAO;IACxB,WAAW,GAAG,IAAI,CAAC;IAEnB,IAAA,oCAAuB,EACrB,KAAK,EAAE,EAAE,kBAAkB,EAAE,SAAS,EAAE,GAAG,EAAE,SAAS,EAAE,KAAK,EAAE,EAAE,EAAE;QACjE,MAAM,IAAA,2BAAiB,GAAE,CAAC,OAAO,CAAC;YAChC,KAAK,EAAE,aAAa,CAAC,kBAAkB,CAAC;YACxC,IAAI,EAAE,SAAS;YACf,OAAO,EAAE,EAAE,GAAG,EAAE;YAChB,OAAO,EAAE,KAAK,EAAE,EAAE;YAClB,EAAE,EAAE,IAAI,CAAC,GAAG,EAAE;SACf,CAAC,CAAC;QACH,IAAI,SAAS,IAAI,CAAC,SAAS,KAAK,SAAS,IAAI,SAAS,KAAK,SAAS,CAAC,EAAE,CAAC;YACtE,MAAM,aAAa,GAAG,kBAAkB,CAAC,kBAAkB,CAAC,CAAC;YAC7D,MAAM,OAAO,GAAG,IAAA,4BAAkB,GAAE,CAAC;YACrC,MAAM,OAAO,CAAC,GAAG,CACf,GAAG,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,OAAO,CAAC,OAAO,CAAC,SAAS,EAAE,aAAa,EAAE,EAAE,CAAC,CAAC,CAC/D,CAAC;QACJ,CAAC;IACH,CAAC,CACF,CAAC;IAEF,IAAA,oCAAuB,EACrB,KAAK,EAAE,EAAE,kBAAkB,EAAE,SAAS,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE,EAAE;QACxD,MAAM,IAAA,4BAAkB,GAAE,CAAC,OAAO,CAChC,SAAS,EACT,kBAAkB,CAAC,kBAAkB,CAAC,EACtC,KAAK,EACL,KAAK,CACN,CAAC;IACJ,CAAC,CACF,CAAC;IAEF,IAAA,qCAAwB,EAAC,CAAC,EAAE,MAAM,EAAE,kBAAkB,EAAE,EAAE,EAAE;QAC1D,IAAA,4BAAiB,EAAC,MAAM,EAAE,aAAa,CAAC,kBAAkB,CAAC,CAAC,CAAC;QAC7D,IAAA,4BAAiB,EAAC,MAAM,EAAE,kBAAkB,CAAC,kBAAkB,CAAC,CAAC,CAAC;IACpE,CAAC,CAAC,CAAC;AACL,CAAC"}