@antelopejs/dms 0.8.3 → 0.9.1

package/frontend-vue/layers/dms-layout/app/build/utils/module-store-catalog.ts

@@ -1,137 +1,203 @@
+import type { Tone } from "#dms-ui/app/types/tone";
+import type { StatusPillDot } from "#dms-ui/app/components/status-pill/StatusPill.vue";
+import type {
+  StoreListingEntry,
+  StoreModuleState,
+  StoreOperationKind,
+} from "../../types/module-store";
 import type { DisplayResolver } from "./modules-catalog";
 
-/**
- * One official module offered by the module store preview. The list below is
- * static for now: it stands in for the AntelopeJS module registry the store
- * will read once installing from the dashboard is possible.
- */
-export interface ModuleStoreEntry {
+/** A store module as the Modules page filters and draws it. */
+export type ModuleStoreEntry = StoreListingEntry & {
+  /** Store category, a `$i18n.key` (what the category chips read). */
+  catalogCategory: string;
+};
+
+/** Which store modules the store section shows. */
+export type StoreScope = "all" | "available" | "installed";
+
+/** What a store tile's pill says. */
+export interface StoreTileStatus {
+  tone: Tone;
+  /** i18n key under `modules.store.state`. */
+  labelKey: string;
+  dot?: StatusPillDot;
+}
+
+/** One action a store tile offers. */
+export interface StoreAction {
+  kind: StoreOperationKind;
+  /** i18n key under `modules.store.actions`. */
+  labelKey: string;
+  icon: string;
+  /** The action runs only once the owner confirms it. */
+  confirm?: boolean;
   /**
-   * Id the module registers in the catalog (`RegisterModule({ id })`): a
-   * store entry whose id is installed is hidden.
+   * Offered in the tile's menu only, never as its button: pausing or
+   * removing a running module is not what its tile should invite.
    */
-  id: string;
-  /** npm package the AntelopeJS CLI adds to the project. */
-  packageName: string;
-  /** Display name, a `$i18n.key`. */
-  title: string;
-  /** One-line summary, a `$i18n.key`. */
-  description: string;
-  /** Iconify name, the icon the module registers once installed. */
-  icon: string;
-  /** Store category, a `$i18n.key`. */
-  catalogCategory: string;
+  isMenuOnly?: boolean;
 }
 
-const CATEGORY = {
-  ai: "$modules.store.category.ai",
-  business: "$modules.store.category.business",
-  content: "$modules.store.category.content",
-  data: "$modules.store.category.data",
-  developer: "$modules.store.category.developer",
-  growth: "$modules.store.category.growth",
-  operations: "$modules.store.category.operations",
-} as const;
-
-function storeEntry(
-  id: string,
-  packageName: string,
-  icon: string,
-  catalogCategory: string,
-): ModuleStoreEntry {
+const CATEGORY_PREFIX = "$modules.store.category";
+
+/** The command that turns a production frontend into one serving new layers. */
+export const FRONTEND_BUILD_COMMAND = "ajs dms build";
+
+const STATUSES: Record<StoreModuleState, StoreTileStatus> = {
+  available: { tone: "neutral", labelKey: "available", dot: "none" },
+  busy: { tone: "info", labelKey: "busy", dot: "live" },
+  active: { tone: "success", labelKey: "active" },
+  disabled: { tone: "neutral", labelKey: "disabled" },
+  error: { tone: "error", labelKey: "error" },
+  pending: { tone: "warning", labelKey: "pending" },
+};
+
+const ACTIONS: Record<StoreOperationKind, StoreAction> = {
+  install: {
+    kind: "install",
+    labelKey: "install",
+    icon: "i-ph-download-simple",
+  },
+  update: { kind: "update", labelKey: "update", icon: "i-ph-arrow-circle-up" },
+  enable: { kind: "enable", labelKey: "enable", icon: "i-ph-play" },
+  disable: {
+    kind: "disable",
+    labelKey: "disable",
+    icon: "i-ph-pause",
+    isMenuOnly: true,
+  },
+  uninstall: {
+    kind: "uninstall",
+    labelKey: "uninstall",
+    icon: "i-ph-trash",
+    confirm: true,
+    isMenuOnly: true,
+  },
+  apply: { kind: "apply", labelKey: "apply", icon: "i-ph-arrows-clockwise" },
+};
+
+/** States of a module that antelope.config.ts declares. */
+const INSTALLED_STATES = new Set<StoreModuleState>([
+  "active",
+  "disabled",
+  "pending",
+]);
+
+export function toModuleStoreEntry(entry: StoreListingEntry): ModuleStoreEntry {
   return {
-    id,
-    packageName,
-    title: `$modules.store.catalog.${id}.title`,
-    description: `$modules.store.catalog.${id}.description`,
-    icon,
-    catalogCategory,
+    ...entry,
+    catalogCategory: `${CATEGORY_PREFIX}.${entry.category}`,
+  };
+}
+
+/** Whether the module is installed, from the store or by the config. */
+export function isInstalled(entry: StoreListingEntry): boolean {
+  if (INSTALLED_STATES.has(entry.state)) return true;
+  return entry.installedVersion !== undefined;
+}
+
+export function filterByScope<T extends StoreListingEntry>(
+  entries: readonly T[],
+  scope: StoreScope,
+): T[] {
+  if (scope === "all") return [...entries];
+  const wantsInstalled = scope === "installed";
+  return entries.filter((entry) => isInstalled(entry) === wantsInstalled);
+}
+
+/** The store modules, alphabetical by their shown name. */
+export function sortStoreModules<T extends StoreListingEntry>(
+  entries: readonly T[],
+  resolve: DisplayResolver,
+): T[] {
+  return [...entries].sort((a, b) =>
+    resolve(a.title).localeCompare(resolve(b.title)),
+  );
+}
+
+export function storeTileStatus(entry: StoreListingEntry): StoreTileStatus {
+  if (entry.state === "active" && entry.updateAvailable) {
+    return { tone: "warning", labelKey: "update_available" };
+  }
+  return STATUSES[entry.state];
+}
+
+/**
+ * What the tile offers, the main action first. A module in error offers to
+ * try its last step again: installing it when the file does not hold it,
+ * applying the file otherwise.
+ */
+export function storeActions(entry: StoreListingEntry): StoreAction[] {
+  const installed = entry.installedVersion !== undefined;
+  const byState: Record<StoreModuleState, StoreOperationKind[]> = {
+    available: ["install"],
+    busy: [],
+    active: entry.updateAvailable
+      ? ["update", "disable", "uninstall"]
+      : ["disable", "uninstall"],
+    disabled: ["enable", "uninstall"],
+    error: installed ? ["apply", "uninstall"] : ["install"],
+    pending: ["apply", "uninstall"],
   };
+  return byState[entry.state].map((kind) => ACTIONS[kind]);
 }
 
 /**
- * The official AntelopeJS DMS modules (one repository each under the
- * AntelopeJS organisation). Ids and icons are the ones each module registers;
- * Media and Builder register no catalog module, so theirs come from their
- * settings page and the v2 design.
+ * Whether the page waits on the frontend for this module: its backend side
+ * changed and the frontend server has not reported serving it yet.
  */
-export const MODULE_STORE_CATALOG: readonly ModuleStoreEntry[] = [
-  storeEntry("ai", "@antelopejs/dms-ai", "i-ph-robot", CATEGORY.ai),
-  storeEntry(
-    "api",
-    "@antelopejs/dms-api",
-    "i-ph-brackets-curly",
-    CATEGORY.developer,
-  ),
-  storeEntry(
-    "automation",
-    "@antelopejs/dms-automation",
-    "i-ph-flow-arrow",
-    CATEGORY.operations,
-  ),
-  storeEntry(
-    "builder",
-    "@antelopejs/dms-builder",
-    "i-ph-hammer",
-    CATEGORY.developer,
-  ),
-  storeEntry(
-    "cicd",
-    "@antelopejs-private/dms-cicd",
-    "i-ph-rocket-launch",
-    CATEGORY.operations,
-  ),
-  storeEntry(
-    "database",
-    "@antelopejs/dms-database",
-    "i-ph-database",
-    CATEGORY.data,
-  ),
-  storeEntry(
-    "lang",
-    "@antelopejs/dms-lang",
-    "i-ph-translate",
-    CATEGORY.content,
-  ),
-  storeEntry(
-    "mailing",
-    "@antelopejs/dms-mailing",
-    "i-ph-envelope-simple",
-    CATEGORY.growth,
-  ),
-  storeEntry(
-    "marketing",
-    "@antelopejs/dms-marketing",
-    "i-ph-chart-line-up",
-    CATEGORY.growth,
-  ),
-  storeEntry("media", "@antelopejs/dms-media", "i-ph-images", CATEGORY.content),
-  storeEntry(
-    "saas",
-    "@antelopejs/dms-saas",
-    "i-ph-buildings",
-    CATEGORY.business,
-  ),
-];
-
-/** The AntelopeJS CLI command that adds a package module to a project. */
-export const MODULE_INSTALL_COMMAND = "ajs project modules add";
-
-/** The full CLI command that adds the module to a project. */
-export function moduleInstallCommand(entry: ModuleStoreEntry): string {
-  return `${MODULE_INSTALL_COMMAND} ${entry.packageName}`;
+export function isAwaitingFrontend(entry: StoreListingEntry): boolean {
+  return entry.state !== "busy" && entry.frontend === "pending";
 }
 
+/** Why an action the tile offers cannot run, as the tile explains it. */
+export type StoreActionBlock =
+  | "no_release"
+  | "incompatible"
+  | "frontend"
+  | "interfaces"
+  | "dependents";
+
+/** Actions that load a new release of the module. */
+const RELEASE_ACTIONS = new Set<StoreOperationKind>(["install", "update"]);
 /**
- * The store entries not installed on this platform, alphabetical by their
- * shown name.
+ * Actions that pick the missing interfaces' modules in a dialog; the others
+ * refuse a release that misses one.
  */
-export function availableStoreModules(
-  catalog: readonly ModuleStoreEntry[],
-  installedIds: ReadonlySet<string>,
-  resolve: DisplayResolver,
-): ModuleStoreEntry[] {
-  return catalog
-    .filter((entry) => !installedIds.has(entry.id))
-    .sort((a, b) => resolve(a.title).localeCompare(resolve(b.title)));
+const PICKS_DEPENDENCIES = new Set<StoreOperationKind>(["install"]);
+/** Actions that take a running module down. */
+const TAKE_DOWN_ACTIONS = new Set<StoreOperationKind>(["disable", "uninstall"]);
+
+function releaseBlock(
+  entry: StoreListingEntry,
+  kind: StoreOperationKind,
+): StoreActionBlock | undefined {
+  if (!entry.latestVersion) return "no_release";
+  if (!entry.compatible) return "incompatible";
+  if (entry.frontendRequirement) return "frontend";
+  if (!PICKS_DEPENDENCIES.has(kind) && entry.missingInterfaces.length > 0) {
+    return "interfaces";
+  }
+  return undefined;
+}
+
+/** Why `kind` cannot run on the module, or undefined when it can. */
+export function storeActionBlock(
+  entry: StoreListingEntry,
+  kind: StoreOperationKind,
+): StoreActionBlock | undefined {
+  if (RELEASE_ACTIONS.has(kind)) return releaseBlock(entry, kind);
+  if (TAKE_DOWN_ACTIONS.has(kind) && entry.dependents.length > 0) {
+    return "dependents";
+  }
+  return undefined;
+}
+
+/** Whether `kind` first asks which modules implement the missing interfaces. */
+export function needsDependencyChoice(
+  entry: StoreListingEntry,
+  kind: StoreOperationKind,
+): boolean {
+  return PICKS_DEPENDENCIES.has(kind) && entry.missingInterfaces.length > 0;
 }

package/frontend-vue/layers/dms-layout/app/build/utils/module-store-install.ts

@@ -0,0 +1,146 @@
+import type {
+  MissingInterface,
+  StoreActionBody,
+  StoreDependencyChoice,
+} from "../../types/module-store";
+
+/**
+ * The radio value of the "Other npm package" choice: not an npm package
+ * name, so no candidate can take it.
+ */
+export const OTHER_PACKAGE_CHOICE = ":other";
+
+/**
+ * An npm package name, scoped or not: never a path, a URL or a git source,
+ * as the store only installs from the registry.
+ */
+const NPM_PACKAGE_PATTERN =
+  /^(?:@[a-z0-9][a-z0-9._~-]*\/)?[a-z0-9][a-z0-9._~-]*$/;
+const NPM_PACKAGE_MAX_LENGTH = 214;
+
+/** What the install dialog holds for one missing interface. */
+export interface DependencyDraft {
+  interfacePackage: string;
+  /** A candidate's package, or {@link OTHER_PACKAGE_CHOICE}. */
+  choice: string;
+  /** The package typed for the "Other npm package" choice. */
+  otherPackage: string;
+  /** The config as typed, JSON; empty means none. */
+  config: string;
+}
+
+/** Why a draft cannot be sent, by field: i18n keys under the dialog's errors. */
+export type DependencyDraftError =
+  | "package_required"
+  | "package_invalid"
+  | "config_invalid";
+
+export interface DependencyDraftErrors {
+  package?: DependencyDraftError;
+  config?: DependencyDraftError;
+}
+
+/** A config as the dialog reads it: absent when left empty. */
+export interface ParsedDependencyConfig {
+  isValid: boolean;
+  config?: Record<string, unknown>;
+}
+
+export function isNpmPackageName(value: string): boolean {
+  return (
+    value.length <= NPM_PACKAGE_MAX_LENGTH && NPM_PACKAGE_PATTERN.test(value)
+  );
+}
+
+const isPlainObject = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" && value !== null && !Array.isArray(value);
+
+/** Reads a typed config: empty is no config, anything else a JSON object. */
+export function parseDependencyConfig(text: string): ParsedDependencyConfig {
+  if (!text.trim()) return { isValid: true };
+  try {
+    const value: unknown = JSON.parse(text);
+    return isPlainObject(value)
+      ? { isValid: true, config: value }
+      : { isValid: false };
+  } catch {
+    return { isValid: false };
+  }
+}
+
+/**
+ * One draft per missing interface, the first candidate picked. A draft of
+ * an earlier attempt at the same interface is kept, so a retry starts from
+ * what the owner typed.
+ */
+export function createDependencyDrafts(
+  missing: readonly MissingInterface[],
+  previous: readonly DependencyDraft[] = [],
+): DependencyDraft[] {
+  return missing.map(({ interfacePackage, candidates }) => {
+    const earlier = previous.find(
+      (draft) => draft.interfacePackage === interfacePackage,
+    );
+    if (earlier) return { ...earlier };
+    return {
+      interfacePackage,
+      choice: candidates[0]?.package ?? OTHER_PACKAGE_CHOICE,
+      otherPackage: "",
+      config: "",
+    };
+  });
+}
+
+/** The package a draft installs, as the owner picked or typed it. */
+export function draftPackage(draft: DependencyDraft): string {
+  return draft.choice === OTHER_PACKAGE_CHOICE
+    ? draft.otherPackage.trim()
+    : draft.choice;
+}
+
+function packageError(
+  draft: DependencyDraft,
+): DependencyDraftError | undefined {
+  const packageName = draftPackage(draft);
+  if (!packageName) return "package_required";
+  return isNpmPackageName(packageName) ? undefined : "package_invalid";
+}
+
+export function validateDependencyDraft(
+  draft: DependencyDraft,
+): DependencyDraftErrors {
+  const errors: DependencyDraftErrors = {};
+  const packageProblem = packageError(draft);
+  if (packageProblem) errors.package = packageProblem;
+  if (!parseDependencyConfig(draft.config).isValid) {
+    errors.config = "config_invalid";
+  }
+  return errors;
+}
+
+export function areDependencyDraftsValid(
+  drafts: readonly DependencyDraft[],
+): boolean {
+  return drafts.every(
+    (draft) => Object.keys(validateDependencyDraft(draft)).length === 0,
+  );
+}
+
+function toDependencyChoice(draft: DependencyDraft): StoreDependencyChoice {
+  const { config } = parseDependencyConfig(draft.config);
+  const choice: StoreDependencyChoice = {
+    interfacePackage: draft.interfacePackage,
+    package: draftPackage(draft),
+  };
+  if (config) choice.config = config;
+  return choice;
+}
+
+/** The install request for module `id`, from drafts already validated. */
+export function buildInstallBody(
+  id: string,
+  drafts: readonly DependencyDraft[],
+): StoreActionBody {
+  if (drafts.length === 0) return { id };
+  return { id, dependencies: drafts.map(toDependencyChoice) };
+}

package/frontend-vue/layers/dms-layout/app/build/utils/modules-catalog.ts

@@ -2,6 +2,7 @@ import type {
   ModuleCatalogEntry,
   ModuleStatus,
   PageInfo,
+  SiteLayout,
 } from "../../types/page";
 
 /** Category of the modules that declare none. */
@@ -148,11 +149,10 @@ export function sortModules(
 
 /**
  * A page as `/dms/sitelayout` serves it: the payload also carries the
- * owning module and the parent category, which the shared type leaves out.
+ * owning module, which the shared type leaves out.
  */
 type ServedPage = PageInfo & {
   module?: string;
-  category?: { displayName?: string; isModuleRoot?: boolean };
 };
 
 function isOpenablePage(page: ServedPage): boolean {
@@ -169,19 +169,21 @@ function isOpenablePage(page: ServedPage): boolean {
  * the empty state can point to where the thing actually lives.
  */
 export function findModulePageMatch(
-  pages: Record<string, PageInfo> | undefined,
+  siteLayout: Pick<SiteLayout, "pages" | "categories"> | undefined,
   query: string,
   installedModuleIds: ReadonlySet<string>,
   resolve: DisplayResolver,
 ): ModulePageMatch | null {
   const needle = normalizeQuery(query);
-  if (!needle || !pages) return null;
-  for (const page of Object.values(pages) as ServedPage[]) {
+  if (!needle || !siteLayout) return null;
+  for (const page of Object.values(siteLayout.pages) as ServedPage[]) {
     if (!page.module || !installedModuleIds.has(page.module)) continue;
     if (!isOpenablePage(page)) continue;
     const pageTitle = resolve(page.displayName);
     if (!pageTitle.toLocaleLowerCase().includes(needle)) continue;
-    const parent = page.category;
+    const parent = page.categoryId
+      ? siteLayout.categories[page.categoryId]
+      : undefined;
     const sectionTitle =
       parent?.displayName && !parent.isModuleRoot
         ? resolve(parent.displayName)

package/frontend-vue/layers/dms-layout/app/build/utils/publicErrorMessage.ts

@@ -0,0 +1,19 @@
+// A fetch failure names the request it failed: `[GET] "http://10.0.0.4:5010/
+// dms/page?path=/x": 502 Bad Gateway`. On a server, that is the backend's
+// internal address, which an error page must never show.
+const FETCH_FAILURE = /^\[[A-Z]+\]\s+"[^"]*":\s*(.*)$/s;
+const ABSOLUTE_URL = /\b[a-z][a-z0-9+.-]*:\/\/[^\s"'<>]+/gi;
+const SPACES = /\s{2,}/g;
+
+/**
+ * The part of an error's message a page may show: a fetch failure's status
+ * text alone, and no absolute URL anywhere; nothing when nothing is left.
+ */
+export function publicErrorMessage(
+  message: string | undefined,
+): string | undefined {
+  if (!message) return undefined;
+  const statusText = FETCH_FAILURE.exec(message)?.[1] ?? message;
+  const shown = statusText.replace(ABSOLUTE_URL, "").replace(SPACES, " ");
+  return shown.trim() || undefined;
+}

package/frontend-vue/layers/dms-layout/app/components/navigation/CollapsedMenuItem.vue

@@ -102,15 +102,6 @@ const paddingLeft = computed(() => {
 const chevronClass = (isOpen: boolean) => {
   return theme({ isOpen }).chevron();
 };
-
-const { prefetchPageLayout } = usePrefetch();
-
-function onLinkHover(): void {
-  const { to } = props.item;
-  if (typeof to === "string") {
-    prefetchPageLayout(stripQueryAndHash(to));
-  }
-}
 </script>
 
 <template>
@@ -128,7 +119,6 @@ function onLinkHover(): void {
         :is="item.to ? DmsLink : 'div'"
         :to="item.to"
         :class="ui.topLevelButton()"
-        @mouseenter="onLinkHover"
       >
         <UIcon v-if="item.icon" :name="item.icon" :class="ui.icon()" />
         <UIcon
@@ -150,7 +140,6 @@ function onLinkHover(): void {
       :class="ui.link()"
       :style="{ paddingLeft }"
       :title="item.title"
-      @mouseenter="onLinkHover"
     >
       <UIcon v-if="item.icon" :name="item.icon" :class="ui.icon()" />
       <span>{{ item.label }}</span>

package/frontend-vue/layers/dms-layout/app/components/navigation/NavigationMenu.vue

@@ -206,6 +206,9 @@ function decorateMenuItem(item: DmsMenuItem): DmsMenuItem {
 
   return {
     ...item,
+    // Inertia prefetches the page on hover, the way a `DmsLink` does: the
+    // visit then shows it without a request, and its components load early.
+    ...(item.to ? { prefetch: true } : {}),
     ...(variant.link ? { class: [item.class, variant.link] } : {}),
     ...(statusClass ? { trailingIcon: STATUS_DOT_ICON } : {}),
     badge,
@@ -232,18 +235,6 @@ const groupedItems = computed((): NavigationMenuItem[][] => {
   );
 });
 
-const { prefetchPageLayout } = usePrefetch();
-
-function onMenuMouseover(event: MouseEvent): void {
-  const target = (event.target as HTMLElement).closest("a[href]");
-  if (!target) return;
-
-  const href = target.getAttribute("href");
-  if (href && href.startsWith("/")) {
-    prefetchPageLayout(stripQueryAndHash(href));
-  }
-}
-
 function isDesiredOpen(id: string): boolean {
   return props.modelValue?.includes(id) ?? false;
 }
@@ -271,7 +262,6 @@ function onStateChange(id: string, open: boolean): void {
     :orientation="orientation"
     :highlight="orientation === 'vertical'"
     value-key="id"
-    @mouseover="onMenuMouseover"
   >
     <template #item-leading="{ item, active, ui }">
       <DmsAccordionItemSync

package/frontend-vue/layers/dms-layout/app/composables/general/useSystemState.ts

@@ -16,17 +16,13 @@ export const useSystemState = () => {
     data: systemState,
     error,
     refresh,
-  } = useDmsLazyAsyncData(
-    SYSTEM_STATE_CACHE_KEY,
-    async () => {
-      const { $authFetch } = useAuthFetch();
-      return await $authFetch<SystemState>(SYSTEM_STATE_ENDPOINT);
-    },
-    {
-      default: () => ({ ...DEFAULT_SYSTEM_STATE }),
-      server: true,
-    },
-  );
+  } = useApiData<SystemState>(SYSTEM_STATE_ENDPOINT, {
+    key: SYSTEM_STATE_CACHE_KEY,
+    lazy: true,
+    default: () => ({ ...DEFAULT_SYSTEM_STATE }),
+    // The deployment's state, not the page's data.
+    refreshOnPageRefresh: false,
+  });
 
   const metaTitle = computed(() => systemState.value?.meta?.title ?? "");
   const metaDescription = computed(