@antelopejs/dms 0.9.8 → 0.11.0

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

@@ -1,12 +1,17 @@
 import type { Tone } from "#dms-ui/app/types/tone";
 import type { StatusPillDot } from "#dms-ui/app/components/status-pill/StatusPill.vue";
-import type { ModuleCatalogEntry } from "../../types/page";
+import { type ModuleCatalogEntry, MODULE_URL_PREFIX } from "../../types/page";
 import type {
+  ModuleSourceKind,
   StoreListingEntry,
   StoreModuleState,
   StoreOperationKind,
 } from "../../types/module-store";
-import type { DisplayResolver } from "./modules-catalog";
+import {
+  type DisplayResolver,
+  compareDisplayNames,
+  moduleStatus,
+} from "./modules-catalog";
 
 /** A store module as the Modules page filters and draws it. */
 export type ModuleStoreEntry = StoreListingEntry & {
@@ -17,13 +22,19 @@ export type ModuleStoreEntry = StoreListingEntry & {
 /** 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;
-}
+/**
+ * The scopes in the order the store's switch shows them. The store is for
+ * discovering, so it opens on what can still be installed; "all" comes last,
+ * the widest view.
+ */
+export const STORE_SCOPES: readonly StoreScope[] = [
+  "available",
+  "installed",
+  "all",
+];
+
+/** The scope the store opens on. */
+export const DEFAULT_STORE_SCOPE: StoreScope = "available";
 
 /** One action a store tile offers. */
 export interface StoreAction {
@@ -42,18 +53,18 @@ export interface StoreAction {
 
 const CATEGORY_PREFIX = "$modules.store.category";
 
+/** The icon a tile's footer names a module's source with. */
+export const MODULE_SOURCE_ICONS: Record<ModuleSourceKind, string> = {
+  npm: "i-ph-package",
+  github: "i-ph-github-logo",
+  gitlab: "i-ph-gitlab-logo",
+  git: "i-ph-git-branch",
+  local: "i-ph-folder-simple",
+};
+
 /** 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",
@@ -85,21 +96,85 @@ const INSTALLED_STATES = new Set<StoreModuleState>([
   "pending",
 ]);
 
+/**
+ * The category a module is filed under, the same on its installed tile and
+ * its store tile: the one its registration names, else the store catalog's.
+ */
+export function resolveCatalogCategory(
+  registered: Pick<ModuleCatalogEntry, "catalogCategory"> | undefined,
+  entry: Pick<StoreListingEntry, "category">,
+): string {
+  return (
+    registered?.catalogCategory?.trim() ||
+    `${CATEGORY_PREFIX}.${entry.category}`
+  );
+}
+
 export function toModuleStoreEntry(
   entry: StoreListingEntry,
-  registeredModules: readonly Pick<ModuleCatalogEntry, "id" | "title">[] = [],
+  registeredModules: readonly Pick<
+    ModuleCatalogEntry,
+    "id" | "title" | "catalogCategory"
+  >[] = [],
 ): ModuleStoreEntry {
+  const registered = registeredModules.find((module) => module.id === entry.id);
   return {
     ...entry,
     // The registration also names Installed and navigation. Keep the catalog
     // fallback for unloaded modules, whose translations may not be served.
-    title:
-      registeredModules.find((module) => module.id === entry.id)?.title ??
-      entry.title,
-    catalogCategory: `${CATEGORY_PREFIX}.${entry.category}`,
+    title: registered?.title ?? entry.title,
+    catalogCategory: resolveCatalogCategory(registered, entry),
   };
 }
 
+/** A version as written, not a range: what an installed tile prints. */
+const PLAIN_VERSION = /^\d+\.\d+\.\d+/;
+
+/**
+ * Installed modules with the version, category and source their registration
+ * leaves out, read from the store listing of the same id. A module that registers
+ * neither still reads like the others on its tile and in the filters.
+ */
+export function withStoreDetails<T extends ModuleCatalogEntry>(
+  modules: readonly T[],
+  store: readonly StoreListingEntry[],
+): T[] {
+  const byId = new Map(store.map((entry) => [entry.id, entry]));
+  return modules.map((module) => {
+    const entry = byId.get(module.id);
+    if (!entry) return module;
+    const installed = entry.installedVersion;
+    return {
+      ...module,
+      version:
+        module.version ??
+        (installed && PLAIN_VERSION.test(installed) ? installed : undefined),
+      catalogCategory: resolveCatalogCategory(module, entry),
+      source: entry.source,
+    };
+  });
+}
+
+/**
+ * Where a store tile's Open button leads: the landing page of the installed
+ * module of the same id, when the caller may open it and it has pages (a
+ * module without one lands on its own address, which has nothing to show).
+ */
+export function storeOpenTarget(
+  entry: Pick<StoreListingEntry, "id">,
+  installedModules: readonly Pick<
+    ModuleCatalogEntry,
+    "id" | "hasAccess" | "landingSlug"
+  >[],
+): string | undefined {
+  const module = installedModules.find(
+    (candidate) => candidate.id === entry.id,
+  );
+  if (!module?.hasAccess || !module.landingSlug) return undefined;
+  const ownAddress = `${MODULE_URL_PREFIX}/${entry.id}`;
+  return module.landingSlug === ownAddress ? undefined : module.landingSlug;
+}
+
 /** 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;
@@ -115,29 +190,26 @@ export function filterByScope<T extends StoreListingEntry>(
   return entries.filter((entry) => isInstalled(entry) === wantsInstalled);
 }
 
-/** The store modules, alphabetical by their shown name. */
+/** The store modules, alphabetical by their shown name in `locale`'s order. */
 export function sortStoreModules<T extends StoreListingEntry>(
   entries: readonly T[],
   resolve: DisplayResolver,
+  locale?: string,
 ): T[] {
+  const compare = compareDisplayNames(locale);
   return [...entries].sort((a, b) =>
-    resolve(a.title).localeCompare(resolve(b.title)),
+    compare(resolve(a.title), 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[] {
+  // The developer's working copy is theirs to change in antelope.config.ts.
+  if (entry.isWorkingCopy) return [];
   const installed = entry.installedVersion !== undefined;
   const byState: Record<StoreModuleState, StoreOperationKind[]> = {
     available: ["install"],
@@ -166,6 +238,7 @@ export type StoreActionBlock =
   | "incompatible"
   | "frontend"
   | "interfaces"
+  | "used_by_project"
   | "dependents";
 
 /** Actions that load a new release of the module. */
@@ -197,10 +270,55 @@ export function storeActionBlock(
   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;
+  if (!TAKE_DOWN_ACTIONS.has(kind)) return undefined;
+  // The project cannot be removed first: only a change to its code frees it.
+  if (entry.usedByProject) return "used_by_project";
+  return entry.dependents.length > 0 ? "dependents" : undefined;
+}
+
+/** Translates an i18n key with its named parameters. */
+export type StoreTranslate = (
+  key: string,
+  params?: Record<string, string>,
+) => string;
+
+const LIST_SEPARATOR = ", ";
+
+const BLOCK_MESSAGES: Record<
+  StoreActionBlock,
+  (entry: StoreListingEntry, t: StoreTranslate) => string
+> = {
+  no_release: (_entry, t) => t("modules.store.no_release"),
+  incompatible: (entry, t) =>
+    t("modules.store.incompatible", {
+      range: entry.requiredInterfaceRange ?? "",
+    }),
+  frontend: (entry, t) =>
+    t("modules.store.frontend_requirement.needs", {
+      range: entry.frontendRequirement?.range ?? "",
+      running: entry.frontendRequirement?.running ?? "",
+    }),
+  interfaces: (entry, t) =>
+    t("modules.store.requires_first", {
+      interfaces: entry.missingInterfaces
+        .map((missing) => missing.interfacePackage)
+        .join(LIST_SEPARATOR),
+    }),
+  used_by_project: (_entry, t) => t("modules.store.used_by_project"),
+  dependents: (entry, t) =>
+    t("modules.store.used_by", {
+      modules: entry.dependents.join(LIST_SEPARATOR),
+    }),
+};
+
+/** Why `kind` cannot run on the module, worded for its tile, if it cannot. */
+export function storeBlockMessage(
+  entry: StoreListingEntry,
+  kind: StoreOperationKind,
+  t: StoreTranslate,
+): string | undefined {
+  const block = storeActionBlock(entry, kind);
+  return block ? BLOCK_MESSAGES[block](entry, t) : undefined;
 }
 
 /** Whether `kind` first asks which modules implement the missing interfaces. */
@@ -210,3 +328,81 @@ export function needsDependencyChoice(
 ): boolean {
   return PICKS_DEPENDENCIES.has(kind) && entry.missingInterfaces.length > 0;
 }
+
+/** What an installed module's pill says. */
+export interface InstalledTileStatus {
+  tone: Tone;
+  /** Full i18n key of the label. */
+  labelKey: string;
+  dot?: StatusPillDot;
+}
+
+/** Store states an installed module's pill says before anything else. */
+const STORE_STATE_PILLS: Partial<
+  Record<StoreModuleState, InstalledTileStatus>
+> = {
+  busy: { tone: "info", labelKey: "modules.store.state.busy", dot: "live" },
+  error: { tone: "error", labelKey: "modules.store.state.error" },
+  disabled: { tone: "warning", labelKey: "modules.store.state.disabled" },
+  pending: { tone: "warning", labelKey: "modules.store.state.pending" },
+};
+
+const MODULE_STATUS_PILLS: Record<
+  ReturnType<typeof moduleStatus>,
+  InstalledTileStatus
+> = {
+  live: { tone: "success", labelKey: "modules.status.live" },
+  beta: { tone: "secondary", labelKey: "modules.status.beta" },
+  update: { tone: "warning", labelKey: "modules.status.update" },
+  attention: { tone: "error", labelKey: "modules.status.attention" },
+};
+
+/**
+ * The pill of an installed module: what the store says of it first (an
+ * operation, an error, paused, not applied, a frontend to restart, an
+ * update), then what the module reports of itself, Active otherwise.
+ */
+export function installedTileStatus(
+  module: ModuleCatalogEntry,
+  entry: StoreListingEntry | undefined,
+): InstalledTileStatus {
+  const storeStatus = entry && STORE_STATE_PILLS[entry.state];
+  if (storeStatus) return storeStatus;
+  if (entry && isAwaitingFrontend(entry)) {
+    return { tone: "warning", labelKey: "modules.status.restart_required" };
+  }
+  if (entry?.updateAvailable) {
+    return { tone: "warning", labelKey: "modules.status.update" };
+  }
+  return MODULE_STATUS_PILLS[moduleStatus(module)];
+}
+
+/**
+ * Installed store modules that register no module of their own, as the
+ * Installed grid lists them: a paused module, one that did not start, or one
+ * without pages. antelope.config.ts still declares them, so they stay listed
+ * and managed there, with what the store knows of them.
+ */
+export function storeOnlyModules(
+  store: readonly ModuleStoreEntry[],
+  registered: readonly Pick<ModuleCatalogEntry, "id">[],
+): ModuleCatalogEntry[] {
+  const registeredIds = new Set(registered.map((module) => module.id));
+  return store
+    .filter((entry) => isInstalled(entry) && !registeredIds.has(entry.id))
+    .map((entry) => ({
+      id: entry.id,
+      title: entry.title,
+      description: entry.description,
+      icon: entry.icon,
+      hasAccess: true,
+      // Nothing to open: the module serves no page.
+      landingSlug: "",
+      catalogCategory: entry.catalogCategory,
+      version:
+        entry.installedVersion && PLAIN_VERSION.test(entry.installedVersion)
+          ? entry.installedVersion
+          : undefined,
+      source: entry.source,
+    }));
+}

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

@@ -1,9 +1,30 @@
 import type {
   ModuleCatalogEntry,
   ModuleStatus,
+  ModuleWithAccess,
   PageInfo,
   SiteLayout,
+  SiteLayoutTree,
 } from "../../types/page";
+import { resolveModuleLandingSlug } from "../../utils/moduleLanding";
+
+/** The Modules page, which lists and manages the installed modules. */
+export const MODULES_PAGE_PATH = "/modules";
+/** The module store, its own view under the Modules page. */
+export const MODULE_STORE_PATH = `${MODULES_PAGE_PATH}/store`;
+
+/**
+ * The grid of both module views, installed and store: three columns on a
+ * laptop, so a tile's description, readout and footer line have room. The
+ * min() keeps one column from overflowing a phone.
+ */
+export const MODULE_TILE_GRID_CLASS =
+  "grid grid-cols-[repeat(auto-fill,minmax(min(340px,100%),1fr))] gap-4";
+
+/** Where an installed module's tile is, the one that manages it. */
+export function installedModuleLink(moduleId: string): string {
+  return `${MODULES_PAGE_PATH}#module-${moduleId}`;
+}
 
 /** Category of the modules that declare none. */
 export const MODULE_CATEGORY_OTHER = "$modules.category_other";
@@ -12,6 +33,18 @@ export const MODULE_CATEGORY_ALL = "";
 
 export type ModuleSortMode = "recent" | "name";
 
+/** The order the installed modules open in until the user picks another. */
+export const DEFAULT_MODULE_SORT_MODE: ModuleSortMode = "name";
+
+const MODULE_SORT_MODES: readonly ModuleSortMode[] = ["name", "recent"];
+
+/** A remembered sort mode, or the default when it is missing or unknown. */
+export function parseModuleSortMode(value: unknown): ModuleSortMode {
+  return (
+    MODULE_SORT_MODES.find((mode) => mode === value) ?? DEFAULT_MODULE_SORT_MODE
+  );
+}
+
 /** Turns a display string (possibly a `$i18n.key`) into the shown text. */
 export type DisplayResolver = (value: string) => string;
 
@@ -78,23 +111,28 @@ export function summarizeModules(
 /**
  * Category filter options: the categories present, alphabetical, with
  * "Other" last. The "All" option is the caller's to add.
+ *
+ * Categories are told apart by their shown name: two modules that each name
+ * "Content" through their own i18n key share one option, whose value is the
+ * first key met.
  */
 export function moduleCategoryOptions(
   entries: readonly FilterableModule[],
   resolve: DisplayResolver,
 ): ModuleCategoryOption[] {
-  const counts = new Map<string, number>();
+  const byLabel = new Map<string, ModuleCategoryOption>();
   for (const entry of entries) {
-    const category = moduleCategory(entry);
-    counts.set(category, (counts.get(category) ?? 0) + 1);
+    const value = moduleCategory(entry);
+    const label = resolve(value);
+    const option = byLabel.get(label);
+    if (option) option.count += 1;
+    else byLabel.set(label, { value, label, count: 1 });
   }
-  return [...counts.entries()]
-    .map(([value, count]) => ({ value, label: resolve(value), count }))
-    .sort((a, b) => {
-      if (a.value === MODULE_CATEGORY_OTHER) return 1;
-      if (b.value === MODULE_CATEGORY_OTHER) return -1;
-      return a.label.localeCompare(b.label);
-    });
+  return [...byLabel.values()].sort((a, b) => {
+    if (a.value === MODULE_CATEGORY_OTHER) return 1;
+    if (b.value === MODULE_CATEGORY_OTHER) return -1;
+    return a.label.localeCompare(b.label);
+  });
 }
 
 function normalizeQuery(query: string): string {
@@ -106,10 +144,14 @@ export function filterModules<T extends FilterableModule>(
   options: { query: string; category: string; resolve: DisplayResolver },
 ): T[] {
   const query = normalizeQuery(options.query);
+  const category =
+    options.category === MODULE_CATEGORY_ALL
+      ? undefined
+      : options.resolve(options.category);
   return entries.filter((entry) => {
     if (
-      options.category !== MODULE_CATEGORY_ALL &&
-      moduleCategory(entry) !== options.category
+      category !== undefined &&
+      options.resolve(moduleCategory(entry)) !== category
     ) {
       return false;
     }
@@ -126,18 +168,36 @@ export function filterModules<T extends FilterableModule>(
   });
 }
 
+/**
+ * Compares shown names as `locale` orders them: accents and case only break
+ * ties ("Mailing", "Marketing", "Médiathèque"), and digits read as numbers.
+ * An unknown locale falls back to the runtime's own.
+ */
+export function compareDisplayNames(
+  locale?: string,
+): (a: string, b: string) => number {
+  const options: Intl.CollatorOptions = { numeric: true };
+  try {
+    return new Intl.Collator(locale, options).compare;
+  } catch {
+    return new Intl.Collator(undefined, options).compare;
+  }
+}
+
 /**
  * `recent`: most recently opened first, never-opened modules after them by
- * name. `name`: alphabetical.
+ * name. `name`: alphabetical by shown name, in `locale`'s order.
  */
 export function sortModules(
   entries: readonly ModuleCatalogEntry[],
   mode: ModuleSortMode,
   visitedAt: ReadonlyMap<string, number>,
   resolve: DisplayResolver,
+  locale?: string,
 ): ModuleCatalogEntry[] {
+  const compare = compareDisplayNames(locale);
   const byName = (a: ModuleCatalogEntry, b: ModuleCatalogEntry) =>
-    resolve(a.title).localeCompare(resolve(b.title));
+    compare(resolve(a.title), resolve(b.title));
   return [...entries].sort((a, b) => {
     if (mode === "recent") {
       const delta = (visitedAt.get(b.id) ?? -1) - (visitedAt.get(a.id) ?? -1);
@@ -197,3 +257,51 @@ export function findModulePageMatch(
   }
   return null;
 }
+
+/** A visited module as the command palette's recent modules list it. */
+export interface RecentModule {
+  moduleId: string;
+  /** Display name, possibly a `$i18n.key`. */
+  title: string;
+  icon: string;
+  /** The module's landing page, never the page it was left on. */
+  to: string;
+}
+
+/** A visit of the module history, oldest first as it keeps them. */
+export interface ModuleVisit {
+  moduleId: string;
+}
+
+/**
+ * The visited modules the caller may still open, most recent first, each
+ * leading to its landing page: every way into a module lands there. A module
+ * with no page the caller may open is left out.
+ */
+export function recentModules(
+  visits: readonly ModuleVisit[],
+  modules: Readonly<Record<string, ModuleWithAccess>> | undefined,
+  tree: SiteLayoutTree | undefined,
+): RecentModule[] {
+  return visits
+    .slice()
+    .reverse()
+    .flatMap((visit) => {
+      const module = modules?.[visit.moduleId];
+      if (!module?.hasAccess) return [];
+      const to = resolveModuleLandingSlug(
+        tree,
+        visit.moduleId,
+        module.landingPage,
+      );
+      if (!to) return [];
+      return [
+        {
+          moduleId: visit.moduleId,
+          title: module.title,
+          icon: module.icon,
+          to,
+        },
+      ];
+    });
+}

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

@@ -27,11 +27,37 @@ export const resolveLayoutBannerPresentation = (
   return { ...presentation, icon: banner.icon ?? presentation.icon };
 };
 
+/**
+ * Whether a path is in the module area: the modules page, the module store
+ * and every module's own pages, all under `MODULE_URL_PREFIX`.
+ */
+export const isModuleAreaPath = (path: string): boolean =>
+  path === MODULE_URL_PREFIX || path.startsWith(`${MODULE_URL_PREFIX}/`);
+
+const SCOPE_MATCHERS: Record<
+  LayoutBannerScope,
+  (isModuleArea: boolean) => boolean
+> = {
+  app: (isModuleArea) => !isModuleArea,
+  modules: (isModuleArea) => isModuleArea,
+  everywhere: () => true,
+};
+
+/** Whether a banner's scope, as the backend serves it, covers a page. */
+export const isLayoutBannerInScope = (
+  banner: LayoutBanner,
+  path: string,
+): boolean => SCOPE_MATCHERS[banner.scope](isModuleAreaPath(path));
+
 /**
  * The global banners rendered under the dashboard header, as resolved by the
  * server for this request (see `RegisterLayoutBanner` in
- * `@antelopejs/interface-dms/layout-banners`), minus the ones the user
- * dismissed.
+ * `@antelopejs/interface-dms/layout-banners`), keeping the ones whose scope
+ * covers the current route, minus the ones the user dismissed.
+ *
+ * The site layout is shared by every page, so the scope is applied here
+ * against the route: on the server-rendered page and again on each
+ * client-side navigation, without re-fetching the layout.
  *
  * Dismissals are kept in a session cookie rather than in local storage so the
  * server-rendered page already leaves a dismissed banner out, instead of
@@ -39,6 +65,7 @@ export const resolveLayoutBannerPresentation = (
  */
 export const useLayoutBanners = () => {
   const { siteLayout } = useSiteLayout();
+  const route = useDmsRoute();
   const dismissed = useDmsCookie<string[]>(DISMISSED_BANNERS_COOKIE, {
     default: () => [],
     sameSite: "lax",
@@ -46,7 +73,9 @@ export const useLayoutBanners = () => {
 
   const banners = computed<LayoutBanner[]>(() =>
     (siteLayout.value?.banners ?? []).filter(
-      (banner) => !banner.dismissible || !dismissed.value.includes(banner.key),
+      (banner) =>
+        isLayoutBannerInScope(banner, route.path) &&
+        (!banner.dismissible || !dismissed.value.includes(banner.key)),
     ),
   );