@antelopejs/dms 0.9.0 → 0.9.2

package/frontend-vue/tests/module-store-catalog.test.ts

@@ -5,11 +5,30 @@ import {
   moduleCategoryOptions,
 } from "../layers/dms-layout/app/build/utils/modules-catalog";
 import {
-  MODULE_STORE_CATALOG,
-  availableStoreModules,
-  moduleInstallCommand,
   type ModuleStoreEntry,
+  filterByScope,
+  isAwaitingFrontend,
+  needsDependencyChoice,
+  sortStoreModules,
+  storeActionBlock,
+  storeActions,
+  storeTileStatus,
+  toModuleStoreEntry,
 } from "../layers/dms-layout/app/build/utils/module-store-catalog";
+import {
+  OTHER_PACKAGE_CHOICE,
+  areDependencyDraftsValid,
+  buildInstallBody,
+  createDependencyDrafts,
+  isNpmPackageName,
+  parseDependencyConfig,
+  validateDependencyDraft,
+} from "../layers/dms-layout/app/build/utils/module-store-install";
+import type {
+  MissingInterface,
+  StoreListingEntry,
+} from "../layers/dms-layout/app/types/module-store";
+import catalogDocument from "../../data/module-store/catalog.json";
 import en from "../layers/dms-layout/i18n/locales/layout-en-GB.json";
 import fr from "../layers/dms-layout/i18n/locales/layout-fr-FR.json";
 
@@ -33,16 +52,33 @@ const resolve = (value: string): string => {
   return typeof text === "string" ? text : value;
 };
 
-function storeEntry(
+function listingEntry(
   id: string,
-  overrides: Partial<ModuleStoreEntry> = {},
-): ModuleStoreEntry {
+  overrides: Partial<StoreListingEntry> = {},
+): StoreListingEntry {
   return {
     id,
-    packageName: `@antelopejs/dms-${id}`,
+    package: `@antelopejs/dms-${id}`,
+    icon: "i-ph-cube",
+    category: "data",
     title: id[0].toUpperCase() + id.slice(1),
     description: `${id} description`,
-    icon: "i-ph-cube",
+    state: "available",
+    updateAvailable: false,
+    compatible: true,
+    frontend: "none",
+    missingInterfaces: [],
+    dependents: [],
+    ...overrides,
+  };
+}
+
+function storeEntry(
+  id: string,
+  overrides: Partial<ModuleStoreEntry> = {},
+): ModuleStoreEntry {
+  return {
+    ...toModuleStoreEntry(listingEntry(id)),
     catalogCategory: "Data",
     ...overrides,
   };
@@ -53,32 +89,95 @@ const catalog = [
     catalogCategory: "Content",
     description: "Asset library",
   }),
-  storeEntry("database"),
+  storeEntry("database", { state: "active", installedVersion: "0.1.2" }),
   storeEntry("lang", { title: "Translations", catalogCategory: "Content" }),
-  storeEntry("ai", { catalogCategory: "AI" }),
+  storeEntry("ai", {
+    catalogCategory: "AI",
+    state: "disabled",
+    installedVersion: "0.2.1",
+  }),
 ];
 
+const actionKinds = (entry: StoreListingEntry) =>
+  storeActions(entry).map((action) => action.kind);
+
 describe("module store catalog", () => {
-  it("hides the modules already installed", () => {
-    const available = availableStoreModules(
-      catalog,
-      new Set(["database", "demo"]),
-      resolve,
-    );
-    expect(available.map((entry) => entry.id)).toEqual(["ai", "media", "lang"]);
+  it("sorts the modules by their shown name", () => {
+    expect(
+      sortStoreModules(catalog, resolve).map((entry) => entry.title),
+    ).toEqual(["Ai", "Database", "Media", "Translations"]);
   });
 
-  it("lists every module, by name, when none is installed", () => {
+  it("splits installed modules, paused ones included, from available ones", () => {
     expect(
-      availableStoreModules(catalog, new Set(), resolve).map(
-        (entry) => entry.title,
+      filterByScope(catalog, "installed").map((entry) => entry.id),
+    ).toEqual(["database", "ai"]);
+    expect(
+      filterByScope(catalog, "available").map((entry) => entry.id),
+    ).toEqual(["media", "lang"]);
+    expect(filterByScope(catalog, "all")).toHaveLength(4);
+  });
+
+  it("counts a failed install as available, a failed update as installed", () => {
+    const failedInstall = listingEntry("api", { state: "error" });
+    const failedUpdate = listingEntry("api", {
+      state: "error",
+      installedVersion: "0.3.0",
+    });
+    expect(filterByScope([failedInstall], "available")).toHaveLength(1);
+    expect(filterByScope([failedUpdate], "installed")).toHaveLength(1);
+    expect(actionKinds(failedInstall)).toEqual(["install"]);
+    expect(actionKinds(failedUpdate)).toEqual(["apply", "uninstall"]);
+  });
+
+  it("offers each state its actions, the main one first", () => {
+    expect(actionKinds(listingEntry("a"))).toEqual(["install"]);
+    expect(actionKinds(listingEntry("a", { state: "active" }))).toEqual([
+      "disable",
+      "uninstall",
+    ]);
+    expect(
+      actionKinds(
+        listingEntry("a", { state: "active", updateAvailable: true }),
       ),
-    ).toEqual(["Ai", "Database", "Media", "Translations"]);
+    ).toEqual(["update", "disable", "uninstall"]);
+    expect(actionKinds(listingEntry("a", { state: "disabled" }))).toEqual([
+      "enable",
+      "uninstall",
+    ]);
+    expect(actionKinds(listingEntry("a", { state: "busy" }))).toEqual([]);
   });
 
-  it("is empty once every module is installed", () => {
-    const installed = new Set(catalog.map((entry) => entry.id));
-    expect(availableStoreModules(catalog, installed, resolve)).toEqual([]);
+  it("asks for confirmation before uninstalling only", () => {
+    const confirmed = storeActions(listingEntry("a", { state: "disabled" }))
+      .filter((action) => action.confirm)
+      .map((action) => action.kind);
+    expect(confirmed).toEqual(["uninstall"]);
+  });
+
+  it("flags an update on an active module's pill", () => {
+    expect(
+      storeTileStatus(
+        listingEntry("a", { state: "active", updateAvailable: true }),
+      ).labelKey,
+    ).toBe("update_available");
+    expect(storeTileStatus(listingEntry("a", { state: "busy" })).dot).toBe(
+      "live",
+    );
+  });
+
+  it("waits on the frontend only once the operation is over", () => {
+    expect(isAwaitingFrontend(listingEntry("a", { frontend: "pending" }))).toBe(
+      true,
+    );
+    expect(
+      isAwaitingFrontend(
+        listingEntry("a", { state: "busy", frontend: "pending" }),
+      ),
+    ).toBe(false);
+    expect(isAwaitingFrontend(listingEntry("a", { frontend: "unknown" }))).toBe(
+      false,
+    );
   });
 
   it("searches the name, description, category and id", () => {
@@ -95,23 +194,6 @@ describe("module store catalog", () => {
     expect(search("payments")).toEqual([]);
   });
 
-  it("filters by category, combined with the search", () => {
-    expect(
-      filterModules(catalog, {
-        query: "",
-        category: "Content",
-        resolve,
-      }).map((entry) => entry.id),
-    ).toEqual(["media", "lang"]);
-    expect(
-      filterModules(catalog, {
-        query: "lang",
-        category: "Data",
-        resolve,
-      }),
-    ).toEqual([]);
-  });
-
   it("offers the categories present, with their counts", () => {
     expect(moduleCategoryOptions(catalog, resolve)).toEqual([
       { value: "AI", label: "AI", count: 1 },
@@ -119,31 +201,168 @@ describe("module store catalog", () => {
       { value: "Data", label: "Data", count: 1 },
     ]);
   });
+});
+
+const REDIS: MissingInterface = {
+  interfacePackage: "@antelopejs/interface-redis",
+  candidates: [
+    { name: "redis", package: "@antelopejs/redis" },
+    { name: "valkey", package: "@antelopejs/valkey" },
+  ],
+};
+const QUEUE: MissingInterface = {
+  interfacePackage: "@antelopejs/interface-queue",
+  candidates: [],
+};
+
+const FRONTEND_REQUIREMENT = {
+  range: ">=0.7.0",
+  running: "0.6.0",
+  target: "0.7.2",
+  command: "pnpm add @antelopejs/dms-frontend@0.7.2",
+  breaks: [],
+};
+
+describe("module store blocked actions", () => {
+  const released = (overrides: Partial<StoreListingEntry> = {}) =>
+    listingEntry("cache", { latestVersion: "1.0.0", ...overrides });
+
+  it("lets a releasable module install and update", () => {
+    expect(storeActionBlock(released(), "install")).toBeUndefined();
+    expect(storeActionBlock(released(), "update")).toBeUndefined();
+  });
 
-  it("shows the AntelopeJS CLI command that adds the package", () => {
-    expect(moduleInstallCommand(storeEntry("media"))).toBe(
-      "ajs project modules add @antelopejs/dms-media",
+  it("blocks a release without a version, on another interface or dms-frontend", () => {
+    expect(storeActionBlock(listingEntry("cache"), "install")).toBe(
+      "no_release",
+    );
+    expect(storeActionBlock(released({ compatible: false }), "update")).toBe(
+      "incompatible",
     );
+    expect(
+      storeActionBlock(
+        released({ frontendRequirement: FRONTEND_REQUIREMENT }),
+        "install",
+      ),
+    ).toBe("frontend");
+  });
+
+  it("asks for the missing interfaces on install, refuses them on update", () => {
+    const missing = released({ missingInterfaces: [REDIS] });
+    expect(storeActionBlock(missing, "install")).toBeUndefined();
+    expect(needsDependencyChoice(missing, "install")).toBe(true);
+    expect(storeActionBlock(missing, "update")).toBe("interfaces");
+    expect(needsDependencyChoice(missing, "update")).toBe(false);
+    expect(needsDependencyChoice(released(), "install")).toBe(false);
+  });
+
+  it("keeps a module others need from being paused or removed", () => {
+    const needed = released({ state: "active", dependents: ["@acme/jobs"] });
+    expect(storeActionBlock(needed, "disable")).toBe("dependents");
+    expect(storeActionBlock(needed, "uninstall")).toBe("dependents");
+    expect(storeActionBlock(needed, "enable")).toBeUndefined();
+    expect(
+      storeActionBlock(released({ state: "active" }), "uninstall"),
+    ).toBeUndefined();
   });
 });
 
-describe("official module list", () => {
+describe("module store install dialog", () => {
+  it("accepts npm package names only", () => {
+    expect(isNpmPackageName("redis")).toBe(true);
+    expect(isNpmPackageName("@antelopejs/redis")).toBe(true);
+    expect(isNpmPackageName("Redis")).toBe(false);
+    expect(isNpmPackageName("git+https://github.com/a/b.git")).toBe(false);
+    expect(isNpmPackageName("./local/module")).toBe(false);
+    expect(isNpmPackageName("@scope")).toBe(false);
+    expect(isNpmPackageName("a".repeat(215))).toBe(false);
+  });
+
+  it("reads an empty config as none and refuses anything but an object", () => {
+    expect(parseDependencyConfig("  ")).toEqual({ isValid: true });
+    expect(parseDependencyConfig('{ "url": "redis://cache" }')).toEqual({
+      isValid: true,
+      config: { url: "redis://cache" },
+    });
+    expect(parseDependencyConfig("[]").isValid).toBe(false);
+    expect(parseDependencyConfig("null").isValid).toBe(false);
+    expect(parseDependencyConfig("{ url: }").isValid).toBe(false);
+  });
+
+  it("preselects the first candidate, or the other package without one", () => {
+    expect(
+      createDependencyDrafts([REDIS, QUEUE]).map((draft) => draft.choice),
+    ).toEqual(["@antelopejs/redis", OTHER_PACKAGE_CHOICE]);
+  });
+
+  it("keeps what an earlier attempt picked for the same interface", () => {
+    const [earlier] = createDependencyDrafts([REDIS]);
+    const edited = { ...earlier!, choice: "@antelopejs/valkey", config: "{}" };
+    expect(createDependencyDrafts([REDIS, QUEUE], [edited])[0]).toEqual(edited);
+  });
+
+  it("flags a missing or invalid package and a config that is not an object", () => {
+    const [draft] = createDependencyDrafts([QUEUE]);
+    expect(validateDependencyDraft(draft!)).toEqual({
+      package: "package_required",
+    });
+    expect(
+      validateDependencyDraft({
+        ...draft!,
+        otherPackage: "github:acme/queue",
+        config: "[1]",
+      }),
+    ).toEqual({ package: "package_invalid", config: "config_invalid" });
+    expect(
+      areDependencyDraftsValid([{ ...draft!, otherPackage: " @acme/queue " }]),
+    ).toBe(true);
+  });
+
+  it("builds the install body, leaving out an empty config", () => {
+    const [redis, queue] = createDependencyDrafts([REDIS, QUEUE]);
+    expect(
+      buildInstallBody("cache", [
+        redis!,
+        { ...queue!, otherPackage: "@acme/queue", config: '{"size":2}' },
+      ]),
+    ).toEqual({
+      id: "cache",
+      dependencies: [
+        {
+          interfacePackage: "@antelopejs/interface-redis",
+          package: "@antelopejs/redis",
+        },
+        {
+          interfacePackage: "@antelopejs/interface-queue",
+          package: "@acme/queue",
+          config: { size: 2 },
+        },
+      ],
+    });
+    expect(buildInstallBody("cache", [])).toEqual({ id: "cache" });
+  });
+});
+
+describe("bundled module catalog", () => {
+  const entries = catalogDocument.modules.map((entry) =>
+    toModuleStoreEntry(listingEntry(entry.id, { category: entry.category })),
+  );
+
   it("has unique ids and packages", () => {
-    const ids = MODULE_STORE_CATALOG.map((entry) => entry.id);
-    const packages = MODULE_STORE_CATALOG.map((entry) => entry.packageName);
+    const ids = catalogDocument.modules.map((entry) => entry.id);
+    const packages = catalogDocument.modules.map((entry) => entry.package);
     expect(new Set(ids).size).toBe(ids.length);
     expect(new Set(packages).size).toBe(packages.length);
   });
 
   it("translates every name, description and category in both locales", () => {
     for (const messages of [en, fr]) {
-      for (const entry of MODULE_STORE_CATALOG) {
+      for (const entry of entries) {
         for (const key of [
-          entry.title,
-          entry.description,
+          `$modules.store.catalog.${entry.id}.title`,
+          `$modules.store.catalog.${entry.id}.description`,
           entry.catalogCategory,
         ]) {
-          expect(key.startsWith("$")).toBe(true);
           expect(typeof lookup(messages, key.slice(1)), key).toBe("string");
         }
       }

package/frontend-vue/tests/top-list-card-period-badge-ssr.test.ts

@@ -0,0 +1,212 @@
+// @vitest-environment jsdom
+/**
+ * A TopListCard's period badge across a server render and its hydration,
+ * through the runtime's real payload: once its selector set up before it, the
+ * server prints the preset whatever it knows of the browser's time zone (a
+ * preset reads the same in every zone, and a relative one at every instant),
+ * and the browser hydrates it without a mismatch. A selector further down the
+ * page leaves a skeleton on both sides, which the label replaces once mounted.
+ */
+import {
+  createSSRApp,
+  defineComponent,
+  h,
+  nextTick,
+  onBeforeUnmount,
+  ref,
+  type App,
+  type Component,
+} from "vue";
+import { renderToString } from "vue/server-renderer";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import type { PeriodPreset } from "../layers/dms-core/app/composables/period/types";
+import { browserTimeZone } from "../layers/dms-core/app/utils/regional";
+import TopListCard from "../layers/dms-ui/app/components/top-list/TopListCard.vue";
+
+vi.mock("../layers/dms-ui/app/composables/chart/useChartFetch", () => ({
+  useChartFetch: () => ({
+    data: ref({ items: [{ id: "pro", title: "Pro", value: 12 }] }),
+    isLoading: ref(false),
+  }),
+}));
+
+const engine = await import("#dms/frontend-module");
+const { usePeriod } = await import(
+  "../layers/dms-core/app/composables/period/usePeriod"
+);
+const { registerPeriodScope } = await import(
+  "../layers/dms-core/app/composables/period/usePeriodScope"
+);
+const { TIME_ZONE_COOKIE } = await import(
+  "../layers/dms-core/app/composables/period/periodTimeZone"
+);
+
+const SCOPE = "dashboard";
+const SKELETON = "SKELETON";
+
+function selector(preset: PeriodPreset): Component {
+  return defineComponent({
+    setup() {
+      const period = usePeriod({ defaultPreset: preset });
+      onBeforeUnmount(registerPeriodScope(SCOPE, period.state));
+      return () => h("i");
+    },
+  });
+}
+
+// A skeleton carries an aria-label; the badge renders its label.
+const Slot = defineComponent({
+  props: { ariaLabel: String },
+  setup:
+    (props, { slots }) =>
+    () =>
+      h("span", props.ariaLabel ? SKELETON : slots.default?.()),
+});
+
+const Card = defineComponent({
+  setup: () => () =>
+    h(TopListCard, {
+      title: "Top plans",
+      componentId: "plans",
+      pageId: "dashboard",
+      fetchUrl: "/api/plans/top",
+      periodScope: SCOPE,
+    }),
+});
+
+function page(children: Component[]): App {
+  const app = createSSRApp({
+    render: () =>
+      h(
+        "main",
+        children.map((child) => h(child)),
+      ),
+  });
+  for (const name of ["DmsCard", "UBadge", "USkeleton", "DmsTopListRow"])
+    app.component(name, Slot);
+  return app;
+}
+
+function zoneCookie(zone: string): string {
+  return `${TIME_ZONE_COOKIE}=${encodeURIComponent(JSON.stringify(zone))}`;
+}
+
+async function serverRender(children: Component[], cookies?: string) {
+  const runtime = engine.createDmsFrontendRuntime(undefined, {}, true, cookies);
+  const app = page(children);
+  engine.provideDmsFrontendRuntime(app, runtime);
+  engine.setDmsServerRuntimeResolver(() => runtime);
+  // What the server sees: no `window`.
+  const browserWindow = globalThis.window;
+  vi.stubGlobal("window", undefined);
+  try {
+    const html = await renderToString(app);
+    return { html, payload: engine.serializeDmsPayload(runtime) };
+  } finally {
+    vi.stubGlobal("window", browserWindow);
+  }
+}
+
+const mounted: App[] = [];
+
+async function hydrate(
+  children: Component[],
+  { html, payload }: { html: string; payload: unknown },
+) {
+  const browser = engine.createDmsFrontendRuntime(undefined, {});
+  engine.restoreDmsPayload(
+    browser,
+    structuredClone(payload) as Parameters<typeof engine.restoreDmsPayload>[1],
+  );
+  const container = document.createElement("div");
+  container.innerHTML = html;
+  const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+  const error = vi.spyOn(console, "error").mockImplementation(() => {});
+  try {
+    const app = page(children);
+    engine.provideDmsFrontendRuntime(app, browser);
+    app.mount(container);
+    mounted.push(app);
+    await nextTick();
+    const mismatches = [...warn.mock.calls, ...error.mock.calls].filter(
+      (call) => /hydration|mismatch/i.test(String(call[0])),
+    );
+    return { container, mismatches };
+  } finally {
+    warn.mockRestore();
+    error.mockRestore();
+  }
+}
+
+/** The card head's badge: its preset label, or its skeleton. */
+function badge(html: string): string {
+  const label = /dms\.period\.presets\.[a-z0-9-]+/.exec(html)?.[0];
+  if (label) return label;
+  return html.includes(SKELETON) ? SKELETON : "none";
+}
+
+beforeEach(() => {
+  vi.stubGlobal("useI18n", () => ({ locale: ref("en-US"), t: String }));
+  vi.stubGlobal("useTranslation", () => ({
+    processI18n: (text: string) => text,
+  }));
+  vi.stubGlobal("useComponentEvent", () => ({}));
+  vi.stubGlobal("useWatch", () => ({ state: ref({}) }));
+  vi.stubGlobal("useDmsState", engine.useDmsState);
+  vi.stubGlobal("useDmsCookie", engine.useDmsCookie);
+});
+
+afterEach(() => {
+  mounted.splice(0).forEach((app) => app.unmount());
+  vi.unstubAllGlobals();
+});
+
+describe("a TopListCard's period badge across hydration", () => {
+  it("is in the server's HTML, and hydrates without a mismatch", async () => {
+    const children = [selector("this-month"), Card];
+    const rendered = await serverRender(
+      children,
+      zoneCookie(browserTimeZone()),
+    );
+    expect(badge(rendered.html)).toBe("dms.period.presets.this-month");
+
+    const { container, mismatches } = await hydrate(children, rendered);
+    expect(mismatches).toEqual([]);
+    expect(badge(container.innerHTML)).toBe("dms.period.presets.this-month");
+  });
+
+  it("is rendered before the browser's time zone is known", async () => {
+    const children = [selector("this-month"), Card];
+    const rendered = await serverRender(children);
+    expect(badge(rendered.html)).toBe("dms.period.presets.this-month");
+
+    const { mismatches } = await hydrate(children, rendered);
+    expect(mismatches).toEqual([]);
+  });
+
+  it("names a relative preset too", async () => {
+    const children = [selector("last-24h"), Card];
+    const rendered = await serverRender(
+      children,
+      zoneCookie(browserTimeZone()),
+    );
+    expect(badge(rendered.html)).toBe("dms.period.presets.last-24h");
+
+    const { mismatches } = await hydrate(children, rendered);
+    expect(mismatches).toEqual([]);
+  });
+
+  it("waits for a selector set up after the card, on both sides", async () => {
+    const children = [Card, selector("last-year")];
+    const rendered = await serverRender(
+      children,
+      zoneCookie(browserTimeZone()),
+    );
+    expect(badge(rendered.html)).toBe(SKELETON);
+
+    const { container, mismatches } = await hydrate(children, rendered);
+    expect(mismatches).toEqual([]);
+    await nextTick();
+    expect(badge(container.innerHTML)).toBe("dms.period.presets.last-year");
+  });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@antelopejs/dms",
-  "version": "0.9.0",
+  "version": "0.9.2",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/AntelopeJS/dms.git"
@@ -33,11 +33,11 @@
     "2fa": "^0.1.2",
     "@antelopejs/interface-api": ">=0.0.13 <1.0.0",
     "@antelopejs/interface-api-util": ">=0.1.2 <1.0.0",
-    "@antelopejs/interface-core": ">=0.1.1 <1.0.0",
+    "@antelopejs/interface-core": ">=0.2.3 <1.0.0",
     "@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.7.0 <0.8.0",
+    "@antelopejs/interface-dms": ">=0.7.1 <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",
@@ -54,7 +54,7 @@
     "zod": "~3.24.2"
   },
   "devDependencies": {
-    "@antelopejs/core": ">=1.13.4 <2",
+    "@antelopejs/core": ">=1.15.2 <2",
     "@antelopejs/tooling-configs": ">=0.0.7 <1.0.0",
     "@types/archiver": "^6.0.4",
     "@types/chai": "^4.3.20",
@@ -96,7 +96,7 @@
     "@antelopejs/interface-redis": ">=0.0.8 <1.0.0"
   },
   "peerDependencies": {
-    "@antelopejs/core": ">=1.13.2 <2"
+    "@antelopejs/core": ">=1.15.2 <2"
   },
   "peerDependenciesMeta": {
     "@antelopejs/core": {