@antelopejs/dms 0.8.2 → 0.9.0

package/frontend-vue/tests/use-api-data.test.ts

@@ -0,0 +1,410 @@
+// @vitest-environment jsdom
+/**
+ * `useApiData` through the runtime's real async data and the real
+ * `$authFetch`: a server render reads, renders and hands over the data, the
+ * browser hydrates with it and follows reactive requests, and every request
+ * keeps `$authFetch`'s headers and session retry.
+ */
+import {
+  createApp,
+  createSSRApp,
+  defineComponent,
+  h,
+  nextTick,
+  ref,
+  type App,
+  type Component,
+} from "vue";
+import { renderToString } from "vue/server-renderer";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import type { DmsFrontendRuntime, DmsPayload } from "#dms/frontend-module";
+
+const engine = await import("#dms/frontend-module");
+vi.stubGlobal("$fetch", engine.$fetch);
+vi.stubGlobal("useDmsFetch", engine.useDmsFetch);
+vi.stubGlobal("useDmsAsyncData", engine.useDmsAsyncData);
+vi.stubGlobal("useDmsState", engine.useDmsState);
+vi.stubGlobal("useDmsRuntimeConfig", () => ({
+  public: { dms: { baseURL: "" } },
+}));
+// The app's language, which a test may switch.
+const appLocale = ref("fr");
+vi.stubGlobal("useDmsApp", () => ({ $i18n: { locale: appLocale } }));
+vi.stubGlobal("HTTP_UNAUTHORIZED", 401);
+vi.stubGlobal("useDmsUserSession", () => ({ loggedIn: { value: true } }));
+const refreshSession = vi.fn(async () => true);
+vi.stubGlobal("useSessionRecovery", () => ({
+  refreshSession,
+  reconcileSession: vi.fn(),
+  redirectToAuth: vi.fn(),
+}));
+const { useAuthFetch } = await import(
+  "../layers/dms-core/app/composables/auth/useAuthFetch"
+);
+vi.stubGlobal("useAuthFetch", useAuthFetch);
+const { useApiData, useApiPagedData } = await import(
+  "../layers/dms-core/app/composables/auth/useApiData"
+);
+vi.stubGlobal("useApiData", useApiData);
+vi.stubGlobal("useDmsPagedData", engine.useDmsPagedData);
+
+interface Sent {
+  url: string;
+  query?: Record<string, unknown>;
+  headers: Headers;
+  signal?: AbortSignal;
+}
+
+const sent: Sent[] = [];
+let failNextWith: number | undefined;
+
+/** The transport under `$fetch`: what reaches the backend. */
+const transport = (async (
+  url: string,
+  options: {
+    query?: Record<string, unknown>;
+    headers?: HeadersInit;
+    signal?: AbortSignal;
+    onRequest?: (context: { options: { headers: Headers } }) => void;
+  } = {},
+) => {
+  const headers = new Headers(options.headers);
+  options.onRequest?.({ options: { headers } });
+  sent.push({ url, query: options.query, headers, signal: options.signal });
+  if (failNextWith) {
+    const status = failNextWith;
+    failNextWith = undefined;
+    throw Object.assign(new Error("Unauthorized"), {
+      statusCode: status,
+      response: { status },
+    });
+  }
+  return { url, page: options.query?.page ?? null };
+}) as never;
+
+const mounted: App[] = [];
+
+beforeEach(() => {
+  sent.length = 0;
+  failNextWith = undefined;
+  refreshSession.mockClear();
+});
+
+afterEach(() => {
+  mounted.splice(0).forEach((app) => app.unmount());
+});
+
+async function serverRender(
+  root: Component,
+): Promise<{ html: string; payload: DmsPayload }> {
+  const runtime = engine.createDmsFrontendRuntime(transport, {}, true);
+  const app = createSSRApp(root);
+  engine.provideDmsFrontendRuntime(app, runtime);
+  const html = await renderToString(app);
+  return { html, payload: engine.serializeDmsPayload(runtime) };
+}
+
+function hydrate(root: Component, html: string, payload: DmsPayload) {
+  const runtime: DmsFrontendRuntime = engine.createDmsFrontendRuntime(
+    transport,
+    {},
+  );
+  engine.restoreDmsPayload(runtime, structuredClone(payload));
+  const container = document.createElement("div");
+  container.innerHTML = html;
+  const app = createSSRApp(root);
+  engine.provideDmsFrontendRuntime(app, runtime);
+  app.mount(container);
+  mounted.push(app);
+  return container;
+}
+
+const settle = async () => {
+  await nextTick();
+  await new Promise((done) => setTimeout(done, 0));
+  await nextTick();
+};
+
+describe("useApiData", () => {
+  it("reads in the server render, and the browser hydrates without asking again", async () => {
+    const page = ref(1);
+    const Orders = defineComponent({
+      setup() {
+        const { data } = useApiData<{ page: number }>("/api/orders", {
+          query: () => ({ page: page.value }),
+        });
+        return () => h("p", `page:${data.value?.page}`);
+      },
+    });
+
+    const { html, payload } = await serverRender(Orders);
+    expect(html).toBe("<p>page:1</p>");
+    expect(sent).toHaveLength(1);
+    expect(sent[0]!.headers.get("x-content-language")).toBe("fr");
+    expect(sent[0]!.signal).toBeInstanceOf(AbortSignal);
+    expect(payload.data).toEqual({
+      [engine.dmsRequestKey("/api/orders", { query: { page: 1 } })!]: {
+        url: "/api/orders",
+        page: 1,
+      },
+    });
+
+    sent.length = 0;
+    const container = hydrate(Orders, html, payload);
+    await settle();
+    expect(sent).toEqual([]);
+
+    page.value = 2;
+    await settle();
+    expect(sent.map(({ query }) => query)).toEqual([{ page: 2 }]);
+    expect(container.textContent).toBe("page:2");
+  });
+
+  it("reads nothing while its URL is null", async () => {
+    const id = ref<string | null>(null);
+    const Detail = defineComponent({
+      setup() {
+        const { data } = useApiData<{ url: string }>(() =>
+          id.value ? `/api/orders/${id.value}` : null,
+        );
+        return () => h("p", data.value?.url ?? "none");
+      },
+    });
+
+    const { html, payload } = await serverRender(Detail);
+    expect(html).toBe("<p>none</p>");
+    const container = hydrate(Detail, html, payload);
+    await settle();
+    expect(sent).toEqual([]);
+
+    id.value = "7";
+    await settle();
+    expect(container.textContent).toBe("/api/orders/7");
+  });
+
+  it("loads data made of several requests under one key", async () => {
+    const Summary = defineComponent({
+      setup() {
+        const { data } = useApiData(
+          "orders-summary",
+          async ({ $authFetch, signal }) => {
+            const [orders, stats] = await Promise.all([
+              $authFetch<{ url: string }>("/api/orders", { signal }),
+              $authFetch<{ url: string }>("/api/stats", { signal }),
+            ]);
+            return `${orders.url}+${stats.url}`;
+          },
+        );
+        return () => h("p", String(data.value));
+      },
+    });
+
+    const { html, payload } = await serverRender(Summary);
+    expect(html).toBe("<p>/api/orders+/api/stats</p>");
+    expect(payload.data["orders-summary"]).toBe("/api/orders+/api/stats");
+    expect(sent.every(({ signal }) => signal instanceof AbortSignal)).toBe(
+      true,
+    );
+  });
+
+  it("refreshes an expired session and reads again", async () => {
+    failNextWith = 401;
+    const Orders = defineComponent({
+      setup() {
+        const { data } = useApiData<{ url: string }>("/api/orders");
+        return () => h("p", data.value?.url ?? "none");
+      },
+    });
+
+    const { html } = await serverRender(Orders);
+    expect(html).toBe("<p>/api/orders</p>");
+    expect(refreshSession).toHaveBeenCalledTimes(1);
+    expect(sent.map(({ headers }) => headers.get("x-auth-retry"))).toEqual([
+      null,
+      "1",
+    ]);
+  });
+
+  it("waits for execute() with immediate: false, as a dialog does", async () => {
+    let execute: (() => Promise<void>) | undefined;
+    const Dialog = defineComponent({
+      setup() {
+        const result = useApiData<{ url: string }>("/api/invoice", {
+          immediate: false,
+        });
+        execute = () => result.execute();
+        return () => h("p", result.data.value?.url ?? "closed");
+      },
+    });
+    const container = document.createElement("div");
+    const runtime = engine.createDmsFrontendRuntime(transport);
+    const dialog = createApp(Dialog);
+    engine.provideDmsFrontendRuntime(dialog, runtime);
+    dialog.mount(container);
+    mounted.push(dialog);
+    await settle();
+    expect(sent).toEqual([]);
+    expect(container.textContent).toBe("closed");
+
+    await execute!();
+    await settle();
+    expect(sent.map(({ url }) => url)).toEqual(["/api/invoice"]);
+    expect(container.textContent).toBe("/api/invoice");
+  });
+
+  it("polls with refreshInterval while a component shows the data", async () => {
+    const Status = defineComponent({
+      setup() {
+        const { data } = useApiData<{ url: string }>("/api/status", {
+          refreshInterval: 20,
+        });
+        return () => h("p", data.value?.url ?? "none");
+      },
+    });
+    const runtime = engine.createDmsFrontendRuntime(transport);
+    const app = createApp(Status);
+    engine.provideDmsFrontendRuntime(app, runtime);
+    app.mount(document.createElement("div"));
+    await settle();
+    expect(sent).toHaveLength(1);
+    await new Promise((done) => setTimeout(done, 70));
+    expect(sent.length).toBeGreaterThan(1);
+
+    app.unmount();
+    const afterUnmount = sent.length;
+    await new Promise((done) => setTimeout(done, 70));
+    expect(sent).toHaveLength(afterUnmount);
+  });
+
+  it("follows a reactive refreshInterval, and stops at 0", async () => {
+    const interval = ref(20);
+    const Install = defineComponent({
+      setup() {
+        useApiData("/api/install-check", { refreshInterval: interval });
+        return () => h("p");
+      },
+    });
+    const runtime = engine.createDmsFrontendRuntime(transport);
+    const app = createApp(Install);
+    engine.provideDmsFrontendRuntime(app, runtime);
+    app.mount(document.createElement("div"));
+    mounted.push(app);
+    await new Promise((done) => setTimeout(done, 70));
+    expect(sent.length).toBeGreaterThan(1);
+
+    interval.value = 0;
+    await settle();
+    const stopped = sent.length;
+    await new Promise((done) => setTimeout(done, 70));
+    expect(sent).toHaveLength(stopped);
+  });
+
+  it("polls from a plugin, outside any component", async () => {
+    const runtime = engine.createDmsFrontendRuntime(transport);
+    const app = createApp({ render: () => null });
+    engine.provideDmsFrontendRuntime(app, runtime);
+    const polling = ref(true);
+    await settle();
+    app.runWithContext(() =>
+      useApiData("/api/_ai/status", {
+        refreshInterval: () => (polling.value ? 20 : null),
+      }),
+    );
+    await new Promise((done) => setTimeout(done, 70));
+    expect(sent.length).toBeGreaterThan(1);
+
+    polling.value = false;
+    await settle();
+    const stopped = sent.length;
+    await new Promise((done) => setTimeout(done, 70));
+    expect(sent).toHaveLength(stopped);
+    runtime.scope.stop();
+  });
+
+  it("asks in the language current when each request leaves", async () => {
+    const runtime = engine.createDmsFrontendRuntime(transport);
+    const app = createApp({ render: () => null });
+    engine.provideDmsFrontendRuntime(app, runtime);
+    const { $authFetch } = app.runWithContext(() => useAuthFetch());
+    try {
+      appLocale.value = "de";
+      await app.runWithContext(() => $authFetch("/api/orders"));
+      expect(sent[0]!.headers.get("x-content-language")).toBe("de");
+    } finally {
+      appLocale.value = "fr";
+      runtime.scope.stop();
+    }
+  });
+
+  it("is the one read helper: useAuthFetch returns $authFetch alone", () => {
+    expect(Object.keys(useAuthFetch())).toEqual(["$authFetch"]);
+  });
+});
+
+describe("useApiPagedData", () => {
+  interface Listing {
+    url: string;
+    page: number | null;
+  }
+  const LAST_PAGE = 3;
+
+  function listing() {
+    let list: ReturnType<typeof useApiPagedData<Listing, number>> | undefined;
+    const Explorer = defineComponent({
+      setup() {
+        list = useApiPagedData<Listing, number>(
+          "media:root",
+          ({ $authFetch, cursor, signal }) =>
+            $authFetch<Listing>("/api/media", {
+              query: { page: cursor },
+              signal,
+            }),
+          {
+            initialCursor: 1,
+            nextCursor: (page) =>
+              (page.page ?? LAST_PAGE) < LAST_PAGE ? page.page! + 1 : null,
+          },
+        );
+        return () =>
+          h("p", list!.pages.value.map((page) => page.page).join(","));
+      },
+    });
+    return { Explorer, list: () => list! };
+  }
+
+  it("renders the first page on the server, then loads more in the browser", async () => {
+    const server = listing();
+    const { html, payload } = await serverRender(server.Explorer);
+    expect(html).toBe("<p>1</p>");
+    expect(sent[0]!.headers.get("x-content-language")).toBe("fr");
+
+    sent.length = 0;
+    const browser = listing();
+    const container = hydrate(browser.Explorer, html, payload);
+    await settle();
+    expect(sent).toEqual([]);
+
+    await browser.list().loadMore();
+    await browser.list().loadMore();
+    await settle();
+    expect(sent.map(({ query }) => query)).toEqual([{ page: 2 }, { page: 3 }]);
+    expect(container.textContent).toBe("1,2,3");
+    expect(browser.list().hasMore.value).toBe(false);
+  });
+
+  it("reads every loaded page again on a refresh", async () => {
+    const { Explorer, list } = listing();
+    const runtime = engine.createDmsFrontendRuntime(transport);
+    const app = createApp(Explorer);
+    engine.provideDmsFrontendRuntime(app, runtime);
+    app.mount(document.createElement("div"));
+    mounted.push(app);
+    await settle();
+    await list().loadMore();
+    sent.length = 0;
+
+    await list().refresh();
+    expect(sent.map(({ query }) => query)).toEqual([{ page: 1 }, { page: 2 }]);
+    expect(list().pages.value).toHaveLength(2);
+  });
+});

package/frontend-vue/tests/user-language.test.ts

@@ -17,7 +17,7 @@ function stubComposables(authFetch = vi.fn(async () => ({}))): LanguageHarness {
     $i18n: { setLocale: harness.setLocale },
   }));
   vi.stubGlobal("useAuthFetch", () => ({ $authFetch: harness.authFetch }));
-  vi.stubGlobal("useUserSession", () => ({
+  vi.stubGlobal("useDmsUserSession", () => ({
     user: { value: { name: "Ada", email: "ada@example.com", language: "en" } },
     fetch: harness.refreshUser,
   }));
@@ -35,10 +35,13 @@ describe("useUserLanguage", () => {
     await useUserLanguage().changeLanguage("fr");
 
     expect(harness.setLocale).toHaveBeenCalledWith("fr");
-    expect(harness.authFetch).toHaveBeenCalledWith("/settings/user/profile", {
-      method: "POST",
-      body: { name: "Ada", email: "ada@example.com", language: "fr" },
-    });
+    expect(harness.authFetch).toHaveBeenCalledWith(
+      "/dms/pages/settings/user/profile",
+      {
+        method: "POST",
+        body: { name: "Ada", email: "ada@example.com", language: "fr" },
+      },
+    );
     expect(harness.refreshUser).toHaveBeenCalled();
   });
 

package/frontend-vue/tests/widget-label-i18n.test.ts

@@ -1,6 +1,7 @@
 import { createSSRApp, defineComponent, h, ref, type PropType } from "vue";
 import { renderToString } from "vue/server-renderer";
-import { afterEach, describe, expect, it, vi } from "vitest";
+import { beforeEach, afterEach, describe, expect, it, vi } from "vitest";
+import { useRealDataEngine } from "./fixtures/dataEngine";
 import Chart from "../layers/dms-ui/app/components/chart/Chart.vue";
 import ChartCard from "../layers/dms-ui/app/components/chart/ChartCard.vue";
 import TopListCard from "../layers/dms-ui/app/components/top-list/TopListCard.vue";
@@ -144,6 +145,8 @@ afterEach(() => {
   sendComponentEvent.mockClear();
 });
 
+beforeEach(() => useRealDataEngine());
+
 describe("module-supplied widget strings and the $ convention", () => {
   it("resolves top list row titles, descriptions and aria-labels", async () => {
     const html = await renderTopList();

package/frontend-vue/vitest.config.ts

@@ -15,6 +15,12 @@ export default defineConfig({
         __dirname,
         "node_modules/@antelopejs/dms-frontend/templates/vue/frontend-module.ts",
       ),
+      // The server routes run under Vitest through the renderer's own router
+      // (`module-testing.mjs`), so their import resolves to its definitions.
+      "#dms/server": resolve(
+        __dirname,
+        "node_modules/@antelopejs/dms-frontend/templates/vue/server-module.ts",
+      ),
       "#shortcuts-aggregated": resolve(
         __dirname,
         "layers/dms-ui/app/config/shortcuts-registry.ts",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@antelopejs/dms",
-  "version": "0.8.2",
+  "version": "0.9.0",
   "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.6.0 <0.7.0",
+    "@antelopejs/interface-dms": ">=0.7.0 <0.8.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

@@ -31,7 +31,8 @@ For the framework underneath (the core, `ajs` CLI, interfaces as versioned contr
   `@RegisterPage()`. Its **static fields are components** — `Form`, `TableView`, `Chart*`,
   `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.
+  routes often declared `@Get`/`@Post` on the same page class, served under `/dms/pages<slug>`
+  (`pageRoutePath(slug, route)`); 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, percent-encoded;
   nothing is fetched while one is unresolved) — every token is `{{<scope>.<key>}}`: `params`, `query`, `row` (an
   action's row), `response` (a form's redirect), and the same page tokens work in every URL and link option, and `.watch(FormEvents.SUBMIT_SUCCESS,

package/skills/dms-module/SKILL.md

@@ -79,7 +79,7 @@ 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.4.0 <0.5.0" }`: the loader refuses the module
+`"engines": { "@antelopejs/dms-frontend": ">=0.6.0 <0.7.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()`

package/skills/dms-pages/SKILL.md

@@ -83,7 +83,10 @@ decorators (`Controller`, `Get`, `Post`, `@Parameter`, `@JSONBody`), return a pl
 for 200 or throw `new HTTPResult(status, body)`. `GetModel(Model)` (from
 `@antelopejs/interface-database-decorators`) gives `get` / `getAll` / `insert` / `update` /
 `delete`. Routes under a controller that a page or DataController wraps **inherit** its auth —
-already gated to logged-in callers (see **dms-auth**).
+already gated to logged-in callers (see **dms-auth**). A route declared on a page class is
+served under `/dms/pages`, not at the page's own path (which is the page): name it with
+`pageRoutePath(slug, "/route")` from `@antelopejs/interface-dms/page` in a `fetchUrl` /
+`submitUrl`. A plain `Controller` the frontend calls sits under `/api/<module>/`.
 
 A **`TableView` is normally backed by a `DataController`**: a class
 `extends DataController(TableClass, TableViewRoutes.All, Controller("/path"))` registered

package/frontend-vue/layers/dms-core/app/build/composables/page/usePageRecordLabel.ts

@@ -1,9 +0,0 @@
-/**
- * The former path of `usePageRecordLabel`, kept for the modules that import
- * it from here. Import it from `#dms-core/app/composables/page/usePageRecordLabel`,
- * or call the auto-imported `usePageRecordLabel()`.
- *
- * @internal
- * @deprecated Use `#dms-core/app/composables/page/usePageRecordLabel`.
- */
-export { usePageRecordLabel } from "../../../composables/page/usePageRecordLabel";

package/frontend-vue/layers/dms-layout/app/composables/page/usePrefetch.ts

@@ -1,21 +0,0 @@
-export function usePrefetch() {
-  const siteLayout = useSiteLayout();
-
-  function prefetchPageLayout(slug: string): void {
-    const page = siteLayout.siteLayout.value?.pages?.[slug];
-    if (!page?.layoutUrl) return;
-
-    const cached = siteLayout.pageLayouts.value[page.layoutUrl];
-    if (cached) {
-      prefetchPageLayoutComponents(cached);
-      return;
-    }
-
-    siteLayout
-      .loadPageLayout(page.layoutUrl)
-      .then((layout) => prefetchPageLayoutComponents(layout))
-      .catch(() => {});
-  }
-
-  return { prefetchPageLayout };
-}

package/frontend-vue/layers/dms-ui/app/build/composables/form/useControlError.ts

@@ -1,10 +0,0 @@
-/**
- * Former home of `useControlError`, kept importable for the modules that
- * reached it here.
- *
- * @deprecated Import `useControlError` from
- * `#dms-ui/app/composables/form/useControlError` (or rely on its auto-import).
- * This path is removed in the next breaking release.
- */
-export * from "../../../composables/form/useControlError";
-export * from "./formControlErrors";

package/frontend-vue/layers/dms-ui/app/build/composables/table-view/useServerRenderedAsyncData.ts

@@ -1,23 +0,0 @@
-/**
- * Async data a list renders from: awaited during the server render, so the
- * markup carries the rows (and hydration reuses them), but never awaited in
- * the browser, so a client navigation paints the list chrome and its skeleton
- * right away instead of holding the page's Suspense until the fetch returns.
- *
- * Callers still `await` the result: on the server it is the fetch, in the
- * browser an already settled value. Read the loading state from the returned
- * `data` (`null` until the first result) rather than from `status`, which
- * stays `idle` until the deferred fetch starts.
- *
- * @param key Async data key (shared with the hydration payload)
- * @param handler Fetches the data
- * @param options `useDmsAsyncData` options (`watch`, `transform`…)
- */
-export function useServerRenderedAsyncData<T>(
-  key: string,
-  handler: () => Promise<T>,
-  options: Parameters<typeof useDmsAsyncData<T>>[2] = {},
-): Promise<Awaited<ReturnType<typeof useDmsAsyncData<T>>>> {
-  if (import.meta.env.SSR) return useDmsAsyncData<T>(key, handler, options);
-  return Promise.resolve(useDmsLazyAsyncData<T>(key, handler, options));
-}

package/frontend-vue/tests/control-error-path.test.ts

@@ -1,11 +0,0 @@
-import { describe, expect, it } from "vitest";
-import * as legacy from "../layers/dms-ui/app/build/composables/form/useControlError";
-import { useControlError } from "../layers/dms-ui/app/composables/form/useControlError";
-import { FORM_CONTROL_ERRORS_KEY } from "../layers/dms-ui/app/build/composables/form/formControlErrors";
-
-describe("useControlError location", () => {
-  it("stays importable from its former build/ path", () => {
-    expect(legacy.useControlError).toBe(useControlError);
-    expect(legacy.FORM_CONTROL_ERRORS_KEY).toBe(FORM_CONTROL_ERRORS_KEY);
-  });
-});