@antelopejs/dms 0.8.3 → 0.9.1

package/frontend-vue/layers/dms-layout/app/pages/[...slug].vue

@@ -3,6 +3,7 @@ import { withoutTrailingSlash } from "ufo";
 import { holdPageHeaderActions } from "../composables/layout/usePageHeaderActions";
 import { useDevReloading } from "../build/composables/dev-reload/useDevReloadHolder";
 import { usePageLiveHost } from "#dms-ui/app/build/composables/live/usePageLiveHost";
+import { usePageDataRefresh } from "#dms-ui/app/build/composables/live/usePageDataRefresh";
 import { pageValidationRedirect } from "../build/utils/pageValidationRedirect";
 
 defineOptions({ inheritAttrs: false });
@@ -42,7 +43,7 @@ async function checkPageMetadata(
     if (import.meta.env.DEV && devReloading.value) {
       return;
     }
-    throw showError({
+    throw showDmsError({
       statusCode: HTTP_NOT_FOUND,
       statusMessage: "Page not found",
     });
@@ -76,7 +77,7 @@ async function recheckAccessWithFreshSession(): Promise<void> {
     if (import.meta.env.DEV && devReloading.value) {
       return;
     }
-    throw showError({
+    throw showDmsError({
       statusCode: HTTP_NOT_FOUND,
       statusMessage: "Page not found",
     });
@@ -90,7 +91,7 @@ async function recheckAccessWithFreshSession(): Promise<void> {
     return;
   }
 
-  throw showError({
+  throw showDmsError({
     statusCode: HTTP_FORBIDDEN,
     statusMessage: "Access denied",
   });
@@ -140,7 +141,7 @@ async function enforcePageValidation(): Promise<void> {
     routeQuery: query,
   });
   if (!redirect) {
-    throw createError({
+    throw createDmsError({
       statusCode: HTTP_NOT_FOUND,
       statusMessage: "Page not found",
     });
@@ -172,7 +173,7 @@ const pagelayoutMetadata = computed(() => routeMatch.value?.metadata);
 const routeParams = computed(() => routeMatch.value?.params || {});
 
 if (siteLayout.loadingError && siteLayout.loadingError.value) {
-  throw createError({
+  throw createDmsError({
     statusCode: HTTP_INTERNAL_SERVER_ERROR,
     statusMessage: "Error loading site layout",
     message: siteLayout.loadingError.value || "Unknown error occurred",
@@ -186,7 +187,7 @@ await checkPageMetadata(pagelayoutMetadata.value);
 // flight the page is unregistered for a moment, and the plugin is already
 // waiting for it to come back.
 if (!pagelayoutMetadata.value && !(import.meta.env.DEV && devReloading.value)) {
-  throw createError({
+  throw createDmsError({
     statusCode: HTTP_NOT_FOUND,
     statusMessage: "Page not found",
   });
@@ -202,9 +203,9 @@ if (import.meta.env.DEV) {
   // the flag back with nobody watching.
   watch(devReloading, (reloading) => {
     if (!reloading && !pagelayoutMetadata.value) {
-      // `showError` commits the error itself; throwing on top of it would only
+      // `showDmsError` commits the error itself; throwing on top of it would only
       // add a second report of the same thing.
-      showError({
+      showDmsError({
         statusCode: HTTP_NOT_FOUND,
         statusMessage: "Page not found",
       });
@@ -246,6 +247,8 @@ usePageLiveHost(
   }),
   { isStreamConnected: () => !!realtime.sessionId.value },
 );
+// The page's `useApiData` reads follow its refreshes and its realtime events.
+usePageDataRefresh(realtime);
 
 function buildPageSetupContext(
   pageInfo: PageInfo,
@@ -495,7 +498,7 @@ if (import.meta.env.DEV) {
         void navigateDms(moved[0]);
         return;
       }
-      showError({
+      showDmsError({
         statusCode: HTTP_NOT_FOUND,
         statusMessage: "Page not found",
       });

package/frontend-vue/layers/dms-layout/app/plugins/dms-menu-sync.client.ts

@@ -1,8 +1,34 @@
+import { type Ref, watch } from "vue";
+
 const MENU_CHANGED_EVENT_TYPE = "menu-changed";
 
+/**
+ * Calls `onReconnect` each time the realtime stream opens again after it was
+ * lost: the events sent meanwhile never arrived. Not on its first opening,
+ * which follows the page load that brought the current menu.
+ *
+ * @param sessionId The stream's session id, unset while it is closed
+ * @param onReconnect What to run once it is back
+ */
+export function watchRealtimeReconnects(
+  sessionId: Ref<string | undefined>,
+  onReconnect: () => void,
+): void {
+  let hasConnected = !!sessionId.value;
+  watch(sessionId, (next, previous) => {
+    if (!next || next === previous) return;
+    if (hasConnected) onReconnect();
+    hasConnected = true;
+  });
+}
+
 // A module signalled that the data behind the menu changed (a project created,
-// an access scope edited). The event carries no data: the site layout and the
-// permission set are re-fetched, each resolved server-side against this user.
+// an access scope edited, a role or a membership changed): on the workspace's
+// topic, or on this member's own when only their access changed. The event
+// carries no data: the site layout, the page on screen and the permission set
+// are re-fetched, each resolved server-side against this user. The layout
+// comes back through Inertia, so the copy each visit carries over is the new
+// one. A stream that reconnects resyncs too: it missed what was sent meanwhile.
 export default defineDmsPlugin(() => {
   const realtime = useUserRealtime();
   const siteLayout = useSiteLayout();
@@ -16,7 +42,7 @@ export default defineDmsPlugin(() => {
         await Promise.all([
           // Background resync: a transient failure is logged below, never
           // escalated to the fatal error page over a working session.
-          siteLayout.refresh({ fatal: false }),
+          siteLayout.resync(),
           permissions.fetchPermissions(),
         ]);
       })
@@ -30,6 +56,8 @@ export default defineDmsPlugin(() => {
     void refresh();
   };
 
+  watchRealtimeReconnects(realtime.sessionId, () => void refresh());
+
   const unsubscribes: Array<() => void> = [];
 
   watch(

package/frontend-vue/layers/dms-layout/app/plugins/favicon.ts

@@ -0,0 +1,58 @@
+import { computed } from "vue";
+import type { DmsLogoSources } from "#dms-core/shared/types/app-config";
+
+const ICON_TYPES: Record<string, string> = {
+  svg: "image/svg+xml",
+  png: "image/png",
+  ico: "image/x-icon",
+  webp: "image/webp",
+};
+const FILE_EXTENSION = /\.([a-z0-9]+)(?:[?#]|$)/i;
+const LIGHT_SCHEME_MEDIA = "(prefers-color-scheme: light)";
+const DARK_SCHEME_MEDIA = "(prefers-color-scheme: dark)";
+
+// A type rather than an interface: unhead's link type carries an index
+// signature (`data-*`), which only a type alias satisfies implicitly.
+type IconLink = {
+  rel: "icon";
+  href: string;
+  type?: string;
+  media?: string;
+};
+
+function iconLink(href: string, media?: string): IconLink {
+  const extension = FILE_EXTENSION.exec(href)?.[1].toLowerCase() ?? "";
+  const type = ICON_TYPES[extension];
+  return {
+    rel: "icon",
+    href,
+    ...(type ? { type } : {}),
+    ...(media ? { media } : {}),
+  };
+}
+
+function faviconLinks(favicon: Partial<DmsLogoSources> = {}): IconLink[] {
+  const { light, dark } = favicon;
+  if (light && dark && light !== dark)
+    return [
+      iconLink(light, LIGHT_SCHEME_MEDIA),
+      iconLink(dark, DARK_SCHEME_MEDIA),
+    ];
+  const icon = light || dark;
+  return icon ? [iconLink(icon)] : [];
+}
+
+/**
+ * The browser tab icon, `branding.logo.favicon`. Its light and dark files
+ * follow the operating system's scheme: the browser draws the tab outside the
+ * page, where the dashboard's color mode does not reach. The app config is
+ * read inside the computed, so an edit applied in development without a
+ * reload replaces the icon too.
+ */
+export default defineDmsPlugin(() => {
+  useHead(
+    computed(() => ({
+      link: faviconLinks(useDmsAppConfig().branding.logo?.favicon),
+    })),
+  );
+});

package/frontend-vue/layers/dms-layout/app/plugins/notification-stream.client.ts

@@ -1,4 +1,7 @@
-import type { UserNotification } from "../composables/notification/useNotifications";
+import type {
+  FeedCounts,
+  UserNotification,
+} from "../composables/notification/useNotifications";
 
 const NOTIFICATION_TOPIC_PREFIX = "notifications:user:";
 const NOTIFICATION_NEW_TYPE = "notification:new";
@@ -9,6 +12,8 @@ const NOTIFICATION_UNREAD_TYPE = "notification:unread";
 interface IncomingPayload {
   notification?: UserNotification;
   ids?: string[];
+  /** The whole feed's counts after a read state change. */
+  counts?: FeedCounts;
 }
 
 const isNotificationEvent = (
@@ -21,7 +26,7 @@ const isNotificationEvent = (
 type Handler = (payload: IncomingPayload | undefined) => void | Promise<void>;
 
 export default defineDmsPlugin(() => {
-  const { user, loggedIn } = useUserSession();
+  const { user, loggedIn } = useDmsUserSession();
   const {
     handleIncomingNotification,
     handleRemoteRead,
@@ -32,16 +37,19 @@ export default defineDmsPlugin(() => {
 
   const handlers: Record<string, Handler> = {
     [NOTIFICATION_NEW_TYPE]: (payload) => {
-      if (payload?.notification) handleIncomingNotification(payload.notification);
+      if (payload?.notification)
+        handleIncomingNotification(payload.notification);
     },
     [NOTIFICATION_READ_TYPE]: async (payload) => {
-      if (Array.isArray(payload?.ids)) await handleRemoteRead(payload.ids);
+      if (Array.isArray(payload?.ids))
+        await handleRemoteRead(payload.ids, payload.counts);
     },
     [NOTIFICATION_UNREAD_TYPE]: async (payload) => {
-      if (Array.isArray(payload?.ids)) await handleRemoteUnread(payload.ids);
+      if (Array.isArray(payload?.ids))
+        await handleRemoteUnread(payload.ids, payload.counts);
     },
-    [NOTIFICATION_ALL_READ_TYPE]: async () => {
-      await handleRemoteAllRead();
+    [NOTIFICATION_ALL_READ_TYPE]: async (payload) => {
+      await handleRemoteAllRead(payload?.counts);
     },
   };
 

package/frontend-vue/layers/dms-layout/app/plugins/profile-sync.client.ts

@@ -1,3 +1,4 @@
+import { pageRoutePath } from "#dms-core/app/utils/pageRoutes";
 import { FormEvents } from "#dms-ui/app/composables/form/types/events";
 import type { ComponentEventData } from "#dms-core/app/types/component";
 
@@ -5,7 +6,10 @@ interface FormSubmitSuccessPayload {
   submitUrl?: string;
 }
 
-const REGION_PREFERENCES_ROUTE = "/settings/user/region/preferences";
+const REGION_PREFERENCES_ROUTE = pageRoutePath(
+  "/settings/user/region",
+  "/preferences",
+);
 
 /** The forms that edit the signed-in user's own record. */
 const SESSION_FORM_ROUTES = new Set([PROFILE_ROUTE, REGION_PREFERENCES_ROUTE]);

package/frontend-vue/layers/dms-layout/app/plugins/regional-preferences.ts

@@ -1,19 +1,25 @@
 import {
   readRegionalPreferences,
   type RegionalPreferenceFields,
+  setReaderTimeZoneSource,
   setRegionalPreferencesSource,
 } from "#dms-core/app/utils/regional";
+import { useTimeZoneCookie } from "#dms-core/app/composables/period/periodTimeZone";
 
 /**
  * Points the shared date formatters at the signed-in user's regional
- * preferences (time zone, clock, date format, first day of the week). Read on
- * every format, from the session of the request being rendered, so the server
- * HTML and the browser agree and a saved preference applies at once.
+ * preferences (time zone, clock, date format, first day of the week), and a
+ * server render at the browser's time zone. Read on every format, from the
+ * request being rendered, so the server HTML and the browser agree and a
+ * saved preference applies at once.
  */
 export default defineDmsPlugin(() => {
   setRegionalPreferencesSource(() =>
     readRegionalPreferences(
-      useUserSession<RegionalPreferenceFields>().user.value,
+      useDmsUserSession<RegionalPreferenceFields>().user.value,
     ),
   );
+  // A server render writes dates, and resolves periods, in the zone of the
+  // browser it renders for (its cookie), as the browser will.
+  setReaderTimeZoneSource(() => useTimeZoneCookie().value);
 });

package/frontend-vue/layers/dms-layout/app/plugins/time-zone-cookie.client.ts

@@ -0,0 +1,12 @@
+import { useTimeZoneCookie } from "#dms-core/app/composables/period/periodTimeZone";
+import { browserTimeZone } from "#dms-core/app/utils/regional";
+
+/**
+ * Keeps the browser's time zone in its cookie, so that the next server render
+ * resolves the dashboards' periods in it (see `usePeriodScope`).
+ */
+export default defineDmsPlugin(() => {
+  const cookie = useTimeZoneCookie();
+  const zone = browserTimeZone();
+  if (cookie.value !== zone) cookie.value = zone;
+});

package/frontend-vue/layers/dms-layout/app/types/module-store.ts

@@ -0,0 +1,134 @@
+/**
+ * Mirror of the backend's module store listing (`GET /dms/store/listing`,
+ * `src/store/types.ts` in `@antelopejs/dms`).
+ */
+export type StoreModuleState =
+  | "available"
+  | "busy"
+  | "active"
+  | "disabled"
+  | "error"
+  | "pending";
+
+export type StoreFrontendState = "none" | "synced" | "pending" | "unknown";
+
+export type StoreOperationKind =
+  | "install"
+  | "update"
+  | "enable"
+  | "disable"
+  | "uninstall"
+  | "apply";
+
+export type StoreOperationStep =
+  | "resolve"
+  | "dependencies"
+  | "unload"
+  | "load"
+  | "save";
+
+export interface StoreOperation {
+  moduleId: string;
+  kind: StoreOperationKind;
+  step: StoreOperationStep;
+  targetVersion?: string;
+  startedAt: number;
+}
+
+/** A module of the AntelopeJS interfaces registry that implements an interface. */
+export interface InterfaceImplementation {
+  /** Name the registry gives it, such as `redis`. */
+  name: string;
+  /** npm package it is installed from. */
+  package: string;
+}
+
+/** An interface the release to install needs and no running module implements. */
+export interface MissingInterface {
+  interfacePackage: string;
+  /** Registry modules that implement it, npm packages only. */
+  candidates: InterfaceImplementation[];
+}
+
+/** A frontend layer that would stop loading on another dms-frontend. */
+export interface FrontendBreak {
+  name: string;
+  /** The dms-frontend range the layer supports. */
+  range: string;
+}
+
+/** Why a release cannot load on the running dms-frontend, and what moving it would take. */
+export interface FrontendRequirement {
+  /** The dms-frontend range the release supports. */
+  range: string;
+  /** The dms-frontend version that runs. */
+  running: string;
+  /** Latest published dms-frontend in the range, when there is one. */
+  target?: string;
+  /** Command that moves the project to `target`. */
+  command?: string;
+  /** Layers already loaded that `target` would refuse. */
+  breaks: FrontendBreak[];
+}
+
+/** Where the store read the running dms-frontend version. */
+export type FrontendVersionSource = "reported" | "project";
+
+export interface StoreListingEntry {
+  id: string;
+  package: string;
+  icon: string;
+  /** Store category key, under `modules.store.category`. */
+  category: string;
+  /** `$i18n.key` */
+  title: string;
+  /** `$i18n.key` */
+  description: string;
+  state: StoreModuleState;
+  installedVersion?: string;
+  /** The version range antelope.config.ts declares. */
+  declaredRange?: string;
+  latestVersion?: string;
+  updateAvailable: boolean;
+  compatible: boolean;
+  requiredInterfaceRange?: string;
+  error?: string;
+  operation?: StoreOperation;
+  frontend: StoreFrontendState;
+  /** The dms-frontend range the release to install declares, when it does. */
+  frontendRange?: string;
+  /** Set when that range excludes the running dms-frontend. */
+  frontendRequirement?: FrontendRequirement;
+  /** Interfaces the release to install needs and nothing implements. */
+  missingInterfaces: MissingInterface[];
+  /** Running modules that need an interface only this one implements. */
+  dependents: string[];
+}
+
+export interface StoreListing {
+  enabled: boolean;
+  modules: StoreListingEntry[];
+  busy: boolean;
+  interfaceVersion: string;
+  dev: boolean;
+  /** Why antelope.config.ts cannot be read or edited, when it cannot. */
+  configError?: string;
+  /** The dms-frontend version that runs, when the store can tell. */
+  frontendVersion?: string;
+  frontendVersionSource?: FrontendVersionSource;
+}
+
+/** A module the owner picked to implement a missing interface. */
+export interface StoreDependencyChoice {
+  interfacePackage: string;
+  /** npm package, never a git or local source. */
+  package: string;
+  /** Config written to its antelope.config.ts entry. */
+  config?: Record<string, unknown>;
+}
+
+/** Body of `POST /dms/store/<kind>`; only an install carries dependencies. */
+export interface StoreActionBody {
+  id: string;
+  dependencies?: StoreDependencyChoice[];
+}

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

@@ -41,6 +41,13 @@ export interface CategoryInfo extends Omit<MenuOptions, "category"> {
   fullSlug: string;
   hasAccess?: boolean;
   isModuleRoot?: boolean;
+  /**
+   * The full id of the category this entry sits in, listed once in
+   * `SiteLayout.categories`; none at the root.
+   */
+  categoryId?: string;
+  /** Answers at its parent's slug: never the target of a URL of its own. */
+  urlTransparent?: boolean;
 }
 
 // Mirror of ModuleInfo and MODULE_URL_PREFIX from @antelopejs/interface-dms/page.
@@ -120,7 +127,13 @@ export interface LayoutBanner {
 }
 
 export type SiteLayout = {
+  /** By slug, the key a URL is resolved against. */
   pages: Record<string, PageInfo>;
+  /**
+   * Every category, once, by full id: pages and categories name theirs by
+   * `categoryId`. A URL resolves against the ones that are not
+   * `urlTransparent`, by `fullSlug`.
+   */
   categories: Record<string, CategoryInfo>;
   /** Absent when the backend predates layout banners. */
   banners?: LayoutBanner[];

package/frontend-vue/layers/dms-layout/i18n/locales/layout-en-GB.json

@@ -735,18 +735,85 @@
     },
     "store": {
       "title": "Module store",
-      "description": "Official AntelopeJS modules not installed on this platform.",
-      "soon": "Coming soon",
-      "banner": {
-        "title": "Coming soon",
-        "description": "Browse and install official modules from the AntelopeJS catalog directly from your dashboard."
+      "description": "Official AntelopeJS modules: install, update, pause or remove them without touching the project’s code.",
+      "scope": {
+        "label": "Show",
+        "all": "All · {count}",
+        "available": "Available · {count}",
+        "installed": "Installed · {count}"
       },
+      "state": {
+        "available": "Available",
+        "busy": "Working",
+        "active": "Active",
+        "disabled": "Paused",
+        "error": "Failed",
+        "pending": "Not applied",
+        "update_available": "Update"
+      },
+      "actions": {
+        "install": "Install",
+        "update": "Update",
+        "enable": "Resume",
+        "disable": "Pause",
+        "uninstall": "Uninstall",
+        "apply": "Apply",
+        "manage": "Manage"
+      },
+      "steps": {
+        "resolve": "Find the latest release",
+        "unload": "Stop the running version",
+        "load": "Download and start",
+        "save": "Write antelope.config.ts",
+        "dependencies": "Install the required modules"
+      },
+      "progress": {
+        "install": "Installing",
+        "update": "Updating",
+        "enable": "Resuming",
+        "disable": "Pausing",
+        "uninstall": "Uninstalling",
+        "apply": "Applying"
+      },
+      "more_actions": "More actions",
+      "incompatible": "Needs {'@'}antelopejs/interface-dms {range}: update the DMS first",
+      "no_release": "The npm registry has no release of it this platform can read",
+      "locked": "Another module is being changed",
+      "pending_hint": "antelope.config.ts and the running platform disagree: Apply brings them in line.",
+      "uninstall_confirm": {
+        "title": "Uninstall {module}?",
+        "description": "{module} stops and leaves the menu. Its data (collections, files, settings) stays in place and comes back if you install it again."
+      },
+      "action_failed": "{module} could not be changed",
+      "errors": {
+        "store_busy": "Another module is being changed. Try again once it is done.",
+        "store_module_unknown": "This module is not in the catalog.",
+        "store_disabled": "The store is read-only on this platform.",
+        "store_invalid_state": "The module changed in the meantime. The list is up to date again.",
+        "unauthorized": "Only platform owners manage modules.",
+        "store_module_required": "Other running modules need this one. Remove them first."
+      },
+      "frontend": {
+        "dev": {
+          "title": "Reloading the interface for {modules}",
+          "description": "The dev frontend picks up the change and the page reloads by itself."
+        },
+        "production": {
+          "title": "{modules}: rebuild the frontend",
+          "description": "The module runs on the backend. Run {command} and restart the frontend to show its pages."
+        },
+        "unknown": {
+          "title": "{modules}: restart the frontend",
+          "description": "The module runs on the backend, but no frontend server reported what it serves. Restart it ({command} in production) to show the module's pages."
+        }
+      },
+      "disabled": {
+        "title": "The store is read-only here",
+        "description": "Modules are installed from development, which writes them to antelope.config.ts; this platform loads what that file declares. Set store.enabled to true in the DMS configuration to change them from here."
+      },
+      "load_error": "The module store could not be loaded",
       "search_placeholder": "Search the store",
       "category_label": "Store category",
-      "available_soon": "Available soon",
-      "install": "Install",
-      "install_soon": "Coming soon",
-      "command_label": "Install command",
       "no_result": {
         "title": "No module in the store matches “{query}”",
         "title_filtered": "No module in the store matches these filters"
@@ -809,6 +876,37 @@
           "title": "SaaS",
           "description": "Plans, workspaces, billing with Stripe and customer lifecycle."
         }
+      },
+      "config_error": "antelope.config.ts cannot be edited from here",
+      "frontend_requirement": {
+        "needs": "Needs dms-frontend {range}, this project runs {running}.",
+        "run": "To move the project to dms-frontend {target}, run:",
+        "breaks": "dms-frontend {target} would refuse these installed layers:",
+        "supports": "supports {range}",
+        "no_target": "No published dms-frontend matches this range."
+      },
+      "requires": "Requires: {interfaces}",
+      "requires_first": "Needs {interfaces}, which no running module implements: install a module that does first.",
+      "used_by": "Used by: {modules}. Remove them first.",
+      "frontend_version": {
+        "label": "dms-frontend {version}",
+        "reported": "Reported by the running frontend server",
+        "project": "Read from the project’s dependencies: no frontend server reported its version"
+      },
+      "install_dialog": {
+        "title": "Install {module}",
+        "description": "{module} needs interfaces that no running module implements. Pick a module for each: it is installed first.",
+        "other": "Other npm package",
+        "package_label": "npm package",
+        "package_placeholder": "{'@'}scope/package",
+        "config_label": "Config (JSON)",
+        "config_hint": "Optional",
+        "note": "These modules are added to antelope.config.ts as their own entries, where their config can be edited later.",
+        "errors": {
+          "package_required": "Enter an npm package name.",
+          "package_invalid": "Not an npm package name: git and local sources are not allowed.",
+          "config_invalid": "Must be a JSON object."
+        }
       }
     },
     "sort": {