@antelopejs/dms 0.5.6 → 0.6.1

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

@@ -1,5 +1,13 @@
 import { NotificationEvents } from "./types/events";
 
+/** Icon well colour a sender may set on a notification. */
+export type NotificationTone =
+  | "neutral"
+  | "primary"
+  | "success"
+  | "warning"
+  | "error";
+
 export interface UserNotification {
   _id: string;
   userId: string;
@@ -10,17 +18,59 @@ export interface UserNotification {
   linkTo: string | null;
   isRead: boolean;
   categoryId: string;
+  subjectId?: string;
+  tone?: NotificationTone | null;
   createdAt: string;
   updatedAt: string;
 }
 
+/**
+ * The whole feed's totals, with what the header bell counts: the unread
+ * notifications that arrived since it was last opened.
+ */
+interface FeedCounts {
+  all: number;
+  unread: number;
+  unseen?: number;
+}
+
+const API_BASE = "/settings/user/notifications";
 const NOTIFICATION_COMPONENT_ID = "global-notifications";
 const NOTIFICATIONS_PAGE_SIZE = 20;
 
+const buildListUrl = (offset: number) =>
+  `${API_BASE}/list?limit=${NOTIFICATIONS_PAGE_SIZE}&offset=${offset}`;
+
+/**
+ * Shared notification state of the header bell (unseen count, popover feed)
+ * and of the settings navigation (unread count); the settings inbox is a
+ * table view of its own (`dms:inbox`), which lists the feed again when these
+ * counts change.
+ *
+ * Seen and read are two states. The bell's badge (`unseenCount`) counts the
+ * unread notifications that arrived since the bell last opened, and opening
+ * it resets the badge (`markAllSeen`). A notification becomes read only when
+ * it is opened or marked read; `unreadCount` (the whole feed's unread total)
+ * feeds the Notifications entry of the settings navigation and its overview
+ * card.
+ */
 export const useNotifications = () => {
   const { $authFetch } = useAuthFetch();
   const { sendComponentEvent } = useComponentEvent();
-  const unreadCount = useDmsState<number>("notifications-unread-count", () => 0);
+  const unreadCount = useDmsState<number>(
+    "notifications-unread-count",
+    () => 0,
+  );
+  const unseenCount = useDmsState<number>(
+    "notifications-unseen-count",
+    () => 0,
+  );
+  // Whether the counts have been asked once, answered or not: until then,
+  // a 0 unread is not known to be true.
+  const areCountsLoaded = useDmsState<boolean>(
+    "notifications-counts-loaded",
+    () => false,
+  );
   const unreadPreview = useDmsState<UserNotification[]>(
     "notifications-unread-preview",
     () => [],
@@ -32,18 +82,77 @@ export const useNotifications = () => {
   const offset = useDmsState<number>("notifications-offset", () => 0);
   const hasMore = useDmsState<boolean>("notifications-has-more", () => true);
 
-  const fetchUnreadCount = async () => {
-    const data = await $authFetch<{ count: number }>(
-      "/settings/user/notifications/unread-count",
+  const lists = [notifications, unreadPreview];
+
+  const setReadState = (ids: string[], isRead: boolean) => {
+    const idsSet = new Set(ids);
+    for (const list of lists) {
+      list.value = list.value.map((n) =>
+        idsSet.has(n._id) ? { ...n, isRead } : n,
+      );
+    }
+  };
+
+  const setAllRead = () => {
+    for (const list of lists) {
+      list.value = list.value.map((n) => ({ ...n, isRead: true }));
+    }
+    unreadPreview.value = [];
+  };
+
+  const removeFromLists = (ids: string[]) => {
+    const idsSet = new Set(ids);
+    for (const list of lists) {
+      list.value = list.value.filter((n) => !idsSet.has(n._id));
+    }
+  };
+
+  const emitRead = (ids: string[]) => {
+    for (const notificationId of ids) {
+      sendComponentEvent(
+        NotificationEvents.NOTIFICATION_READ,
+        NOTIFICATION_COMPONENT_ID,
+        { notificationId },
+      );
+    }
+  };
+
+  const emitCount = () => {
+    sendComponentEvent(
+      NotificationEvents.COUNT_CHANGED,
+      NOTIFICATION_COMPONENT_ID,
+      { count: unreadCount.value },
     );
-    if (data) {
-      unreadCount.value = data.count;
+  };
+
+  /** Takes the whole feed's unread and unseen totals. */
+  const applyFeedCounts = (counts: FeedCounts) => {
+    unreadCount.value = counts.unread;
+    if (typeof counts.unseen === "number") unseenCount.value = counts.unseen;
+  };
+
+  /** Loads the bell's unseen count and the whole feed's unread count. */
+  const fetchBellCounts = async () => {
+    try {
+      const counts = await $authFetch<FeedCounts>(`${API_BASE}/counts`);
+      if (counts) applyFeedCounts(counts);
+    } finally {
+      areCountsLoaded.value = true;
     }
   };
 
+  /**
+   * The bell was opened: its badge resets, and counts again what arrives
+   * later. The notifications stay unread.
+   */
+  const markAllSeen = async () => {
+    unseenCount.value = 0;
+    await $authFetch(`${API_BASE}/seen`, { method: "PUT" });
+  };
+
   const fetchUnreadPreview = async () => {
     const data = await $authFetch<UserNotification[]>(
-      "/settings/user/notifications/unread-preview",
+      `${API_BASE}/unread-preview`,
     );
     if (data) {
       unreadPreview.value = data;
@@ -58,7 +167,7 @@ export const useNotifications = () => {
     }
 
     const data = await $authFetch<UserNotification[]>(
-      `/settings/user/notifications/list?limit=${NOTIFICATIONS_PAGE_SIZE}&offset=${offset.value}`,
+      buildListUrl(offset.value),
     );
 
     if (data) {
@@ -69,121 +178,68 @@ export const useNotifications = () => {
   };
 
   const markAsRead = async (notificationId: string) => {
-    await $authFetch(
-      `/settings/user/notifications/mark-read/${notificationId}`,
-      {
-        method: "PUT",
-      },
-    );
-
-    const updateNotification = (n: UserNotification) => {
-      if (n._id === notificationId) {
-        return { ...n, isRead: true };
-      }
-      return n;
-    };
-
-    notifications.value = notifications.value.map(updateNotification);
-    unreadPreview.value = unreadPreview.value.map(updateNotification);
-
-    await fetchUnreadCount();
-
-    sendComponentEvent(
-      NotificationEvents.NOTIFICATION_READ,
-      NOTIFICATION_COMPONENT_ID,
-      { notificationId },
-    );
-  };
-
-  const deleteNotification = async (notificationId: string) => {
-    await $authFetch(`/settings/user/notifications/delete/${notificationId}`, {
-      method: "DELETE",
+    await $authFetch(`${API_BASE}/mark-read/${notificationId}`, {
+      method: "PUT",
     });
-
-    notifications.value = notifications.value.filter(
-      (n) => n._id !== notificationId,
-    );
-    unreadPreview.value = unreadPreview.value.filter(
-      (n) => n._id !== notificationId,
-    );
-
-    await fetchUnreadCount();
-
-    sendComponentEvent(
-      NotificationEvents.NOTIFICATION_DELETED,
-      NOTIFICATION_COMPONENT_ID,
-      { notificationId },
-    );
+    setReadState([notificationId], true);
+    unreadPreview.value = unreadPreview.value.filter((n) => !n.isRead);
+    await fetchBellCounts();
+    emitRead([notificationId]);
   };
 
-  const markAllAsRead = async () => {
-    await $authFetch("/settings/user/notifications/mark-all-read", {
+  const markAsUnread = async (notificationId: string) => {
+    await $authFetch(`${API_BASE}/mark-unread/${notificationId}`, {
       method: "PUT",
     });
-
-    notifications.value = notifications.value.map((n) => ({
-      ...n,
-      isRead: true,
-    }));
-    unreadPreview.value = [];
-
-    await fetchUnreadCount();
-
-    sendComponentEvent(
-      NotificationEvents.COUNT_CHANGED,
-      NOTIFICATION_COMPONENT_ID,
-      { count: 0 },
-    );
+    setReadState([notificationId], false);
+    await fetchBellCounts();
+    emitCount();
   };
 
-  const deleteAll = async () => {
-    await $authFetch("/settings/user/notifications/delete-all", {
+  const deleteNotification = async (notificationId: string) => {
+    await $authFetch(`${API_BASE}/delete/${notificationId}`, {
       method: "DELETE",
     });
-
-    notifications.value = [];
-    unreadPreview.value = [];
-    unreadCount.value = 0;
-    hasMore.value = false;
+    removeFromLists([notificationId]);
+    await fetchBellCounts();
 
     sendComponentEvent(
-      NotificationEvents.COUNT_CHANGED,
+      NotificationEvents.NOTIFICATION_DELETED,
       NOTIFICATION_COMPONENT_ID,
-      { count: 0 },
+      { notificationId },
     );
   };
 
   const handleRemoteRead = async (ids: string[]) => {
     if (ids.length === 0) return;
-    const idsSet = new Set(ids);
-    const updateNotification = (n: UserNotification) =>
-      idsSet.has(n._id) ? { ...n, isRead: true } : n;
-    notifications.value = notifications.value.map(updateNotification);
-    unreadPreview.value = unreadPreview.value.map(updateNotification);
-    await fetchUnreadCount();
-    for (const notificationId of ids) {
-      sendComponentEvent(
-        NotificationEvents.NOTIFICATION_READ,
-        NOTIFICATION_COMPONENT_ID,
-        { notificationId },
-      );
-    }
+    setReadState(ids, true);
+    unreadPreview.value = unreadPreview.value.filter((n) => !n.isRead);
+    await fetchBellCounts();
+    emitRead(ids);
+  };
+
+  const handleRemoteUnread = async (ids: string[]) => {
+    if (ids.length === 0) return;
+    setReadState(ids, false);
+    await fetchBellCounts();
+    emitCount();
   };
 
   const handleRemoteAllRead = async () => {
-    notifications.value = notifications.value.map((n) => ({
-      ...n,
-      isRead: true,
-    }));
-    unreadPreview.value = [];
-    await fetchUnreadCount();
-    sendComponentEvent(
-      NotificationEvents.COUNT_CHANGED,
-      NOTIFICATION_COMPONENT_ID,
-      { count: 0 },
-    );
+    setAllRead();
+    await fetchBellCounts();
+    emitCount();
+  };
+
+  /** The bell was opened in another tab: this one's badge resets too. */
+  const handleRemoteSeen = () => {
+    unseenCount.value = 0;
   };
 
+  /**
+   * A notification pushed in real time: the bell counts it as new (unseen)
+   * and unread, and lists it first.
+   */
   const handleIncomingNotification = (incoming: UserNotification) => {
     const isAlreadyKnown = notifications.value.some(
       (n) => n._id === incoming._id,
@@ -191,33 +247,36 @@ export const useNotifications = () => {
     if (isAlreadyKnown) return;
     notifications.value = [incoming, ...notifications.value];
     unreadPreview.value = [incoming, ...unreadPreview.value];
-    unreadCount.value += 1;
+    if (!incoming.isRead) {
+      unreadCount.value += 1;
+      unseenCount.value += 1;
+    }
     sendComponentEvent(
       NotificationEvents.NOTIFICATION_RECEIVED,
       NOTIFICATION_COMPONENT_ID,
       { notification: incoming },
     );
-    sendComponentEvent(
-      NotificationEvents.COUNT_CHANGED,
-      NOTIFICATION_COMPONENT_ID,
-      { count: unreadCount.value },
-    );
+    emitCount();
   };
 
   return {
     unreadCount,
+    unseenCount,
+    areCountsLoaded,
     unreadPreview,
     notifications,
     hasMore,
-    fetchUnreadCount,
+    fetchBellCounts,
     fetchUnreadPreview,
     fetchNotifications,
     markAsRead,
+    markAsUnread,
+    markAllSeen,
     deleteNotification,
-    markAllAsRead,
-    deleteAll,
     handleIncomingNotification,
     handleRemoteRead,
+    handleRemoteUnread,
     handleRemoteAllRead,
+    handleRemoteSeen,
   };
 };

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

@@ -1,40 +1,88 @@
-const MODULE_HISTORY_STATE_KEY = "dms-moduleHistory";
+const MODULE_HISTORY_COOKIE = "dms-module-history";
+// Kept for a year and bounded, so the cookie stays small on every request.
+const MODULE_HISTORY_MAX_AGE_SECONDS = 60 * 60 * 24 * 365;
+const MODULE_HISTORY_MAX_ENTRIES = 12;
+const MODULE_HISTORY_MAX_PATH_LENGTH = 300;
 
 export interface ModuleHistoryEntry {
   moduleId: string;
   path: string;
+  /** Epoch milliseconds of the last visit; 0 when unknown. */
+  visitedAt: number;
 }
 
 export interface ModuleHistoryApi {
   record: (moduleId: string, path: string) => void;
   getLast: (moduleId: string) => string | null;
+  /** Visited modules with their last path, ordered oldest to newest visit. */
   entries: ComputedRef<ModuleHistoryEntry[]>;
 }
 
+interface StoredVisit {
+  path: string;
+  at: number;
+}
+
+type StoredHistory = Record<string, StoredVisit>;
+
+/**
+ * Reads whatever the cookie holds into a clean history, dropping anything
+ * malformed: a hand-edited cookie or an older shape must never break the
+ * modules page or the command palette.
+ */
+function normalizeHistory(raw: unknown): StoredHistory {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return {};
+  const result: StoredHistory = {};
+  for (const [moduleId, value] of Object.entries(raw)) {
+    if (!value || typeof value !== "object") continue;
+    const { path, at } = value as Partial<StoredVisit>;
+    if (typeof path !== "string" || !path.startsWith("/")) continue;
+    result[moduleId] = { path, at: typeof at === "number" ? at : 0 };
+  }
+  return result;
+}
+
+/**
+ * Last page visited in each module, kept in a cookie so it survives reloads
+ * and the server renders the same catalog links and "recently used" order as
+ * the browser.
+ */
 export const useModuleHistory = (): ModuleHistoryApi => {
-  const history = useDmsState<Record<string, string>>(
-    MODULE_HISTORY_STATE_KEY,
-    () => ({}),
-  );
+  const cookie = useDmsCookie<StoredHistory>(MODULE_HISTORY_COOKIE, {
+    default: () => ({}),
+    maxAge: MODULE_HISTORY_MAX_AGE_SECONDS,
+    sameSite: "lax",
+  });
+
+  const history = computed(() => normalizeHistory(cookie.value));
 
   function record(moduleId: string, path: string): void {
-    if (!moduleId || !path) return;
+    if (!moduleId || !path || path.length > MODULE_HISTORY_MAX_PATH_LENGTH) {
+      return;
+    }
     // Re-insert the key so a revisited module moves to the end: a plain
     // spread would keep its first-visit position and break the
-    // oldest-to-newest ordering `entries` guarantees.
+    // oldest-to-newest ordering `entries` guarantees. The oldest visits
+    // fall off once the history is full.
     const { [moduleId]: _previous, ...others } = history.value;
-    history.value = { ...others, [moduleId]: path };
+    const kept = Object.entries(others).slice(
+      -(MODULE_HISTORY_MAX_ENTRIES - 1),
+    );
+    cookie.value = {
+      ...Object.fromEntries(kept),
+      [moduleId]: { path, at: Date.now() },
+    };
   }
 
   function getLast(moduleId: string): string | null {
-    return history.value[moduleId] ?? null;
+    return history.value[moduleId]?.path ?? null;
   }
 
-  /** Visited modules with their last path, ordered oldest to newest visit. */
   const entries = computed<ModuleHistoryEntry[]>(() =>
-    Object.entries(history.value).map(([moduleId, path]) => ({
+    Object.entries(history.value).map(([moduleId, visit]) => ({
       moduleId,
-      path,
+      path: visit.path,
+      visitedAt: visit.at,
     })),
   );
 

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

@@ -1,39 +1,49 @@
-type ModulesListingEntry = ModuleInfo & {
-  hasAccess: boolean;
-  landingSlug: string;
-};
+import type { ModuleCatalogEntry } from "../../types/page";
+
+/**
+ * Why the catalog could not be loaded: `forbidden` when the server refused
+ * the caller (not a platform owner), `failed` for anything else. `status` is
+ * the HTTP status when the server answered at all.
+ */
+export interface ModulesListingError {
+  kind: "forbidden" | "failed";
+  status?: number;
+}
 
 const STATE_KEY_MODULES = "dms-modulesListing";
 const STATE_KEY_LOADING = "dms-modulesListingLoading";
 const STATE_KEY_ERROR = "dms-modulesListingError";
+const STATE_KEY_FETCHED_AT = "dms-modulesListingFetchedAt";
+// A listing younger than this is fresh enough to show without refetching:
+// it also covers the hydration right after a server render.
+const REVALIDATE_AFTER_MS = 30_000;
+export const ENDPOINT_MODULES_LISTING = "/dms/modules-listing";
 const IN_FLIGHT_MODULES_LISTING_KEY = "__dmsInFlightModulesListing";
-const ENDPOINT_MODULES_LISTING = "/dms/modules-listing";
-const ERROR_FORBIDDEN_MESSAGE = "Forbidden: only owners can list modules";
-const ERROR_UNKNOWN_MESSAGE = "Unknown error loading modules listing";
 
-function isForbiddenError(error: unknown): boolean {
-  const status = error as
-    | { response?: { status?: number }; statusCode?: number }
+function readStatus(error: unknown): number | undefined {
+  const details = error as
+    | { response?: { status?: number }; statusCode?: number; status?: number }
     | undefined;
-  if (!status) return false;
-  if (status.response?.status === HTTP_FORBIDDEN) return true;
-  if (status.statusCode === HTTP_FORBIDDEN) return true;
-  return false;
+  return details?.response?.status ?? details?.statusCode ?? details?.status;
 }
 
-function extractErrorMessage(error: unknown): string {
-  if (isForbiddenError(error)) return ERROR_FORBIDDEN_MESSAGE;
-  if (error instanceof Error) return error.message;
-  return ERROR_UNKNOWN_MESSAGE;
+function toListingError(error: unknown): ModulesListingError {
+  const status = readStatus(error);
+  if (status === HTTP_FORBIDDEN) return { kind: "forbidden", status };
+  return { kind: "failed", status };
 }
 
 export const useModulesListing = () => {
-  const modules = useDmsState<ModulesListingEntry[] | undefined>(
+  const modules = useDmsState<ModuleCatalogEntry[] | undefined>(
     STATE_KEY_MODULES,
     () => undefined,
   );
   const isLoading = useDmsState<boolean>(STATE_KEY_LOADING, () => false);
-  const loadingError = useDmsState<string | null>(STATE_KEY_ERROR, () => null);
+  const loadingError = useDmsState<ModulesListingError | null>(
+    STATE_KEY_ERROR,
+    () => null,
+  );
+  const fetchedAt = useDmsState<number>(STATE_KEY_FETCHED_AT, () => 0);
 
   // Held on the DMS app, like the in-flight fetches of useSiteLayout: every
   // caller writes the same listing state, so they share one fetch. Not module
@@ -50,17 +60,26 @@ export const useModulesListing = () => {
     },
   };
 
-  function fetchModulesListing(): Promise<void> {
+  /**
+   * Fetches the catalog. With `keepOnFailure`, a failed request leaves the
+   * modules already on screen in place (a background revalidation must not
+   * blank the page); otherwise the failure replaces them with the error.
+   */
+  function fetchModulesListing(keepOnFailure = false): Promise<void> {
     const { $authFetch } = useAuthFetch();
     isLoading.value = true;
-    loadingError.value = null;
+    if (!keepOnFailure) loadingError.value = null;
 
-    const promise = $authFetch<ModulesListingEntry[]>(ENDPOINT_MODULES_LISTING)
+    const promise = $authFetch<ModuleCatalogEntry[]>(ENDPOINT_MODULES_LISTING)
       .then((result) => {
         modules.value = result;
+        loadingError.value = null;
+        fetchedAt.value = Date.now();
       })
       .catch((error: unknown) => {
-        loadingError.value = extractErrorMessage(error);
+        const listingError = toListingError(error);
+        if (keepOnFailure && listingError.kind === "failed") return;
+        loadingError.value = listingError;
         modules.value = undefined;
       })
       .finally(() => {
@@ -83,20 +102,37 @@ export const useModulesListing = () => {
     await fetchModulesListing();
   }
 
+  /**
+   * Loads the catalog again on request (Refresh, Try again): the current list
+   * stays on screen while loading, and a failure is shown, not swallowed.
+   */
   async function refresh(): Promise<void> {
     if (inFlightLoadingPromise.value) {
       await inFlightLoadingPromise.value;
     }
-    modules.value = undefined;
-    loadingError.value = null;
     await fetchModulesListing();
   }
 
+  /**
+   * Reloads statuses and readouts while keeping the current list on screen,
+   * unless the listing is only a few seconds old: readouts are live figures,
+   * so a later revisit should not show stale ones.
+   */
+  async function revalidate(): Promise<void> {
+    if (inFlightLoadingPromise.value) {
+      await inFlightLoadingPromise.value;
+      return;
+    }
+    if (Date.now() - fetchedAt.value < REVALIDATE_AFTER_MS) return;
+    await fetchModulesListing(true);
+  }
+
   return {
     modules,
     isLoading,
     loadingError,
     loadModulesListing,
     refresh,
+    revalidate,
   };
 };

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

@@ -28,10 +28,20 @@ export function collectPageLayoutComponentNames(
   return [...names];
 }
 
-function toCanonicalNames(layout: PageLayout | null | undefined): string[] {
-  return collectPageLayoutComponentNames(layout)
-    .map((name) => resolveDmsComponentName(name))
-    .filter((name): name is string => !!name);
+interface AsyncComponentLoader {
+  __asyncLoader?: () => Promise<unknown>;
+}
+
+function loadPageLayoutComponents(
+  layout: PageLayout | null | undefined,
+): Promise<unknown> {
+  return Promise.all(
+    collectPageLayoutComponentNames(layout).map((name) =>
+      (
+        resolveDmsComponent(name) as AsyncComponentLoader | undefined
+      )?.__asyncLoader?.(),
+    ),
+  );
 }
 
 /**
@@ -45,10 +55,7 @@ export function preloadPageLayoutComponents(
 ): void {
   if (import.meta.env.SSR) return;
 
-  const names = toCanonicalNames(layout);
-  if (names.length) {
-    preloadComponents(names).catch(() => {});
-  }
+  loadPageLayoutComponents(layout).catch(() => {});
 }
 
 /**
@@ -58,10 +65,5 @@ export function preloadPageLayoutComponents(
 export function prefetchPageLayoutComponents(
   layout: PageLayout | null | undefined,
 ): void {
-  if (import.meta.env.SSR) return;
-
-  const names = toCanonicalNames(layout);
-  if (names.length) {
-    prefetchComponents(names)?.catch(() => {});
-  }
+  preloadPageLayoutComponents(layout);
 }