@antelopejs/dms 0.8.3 → 0.9.1

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

@@ -1,3 +1,5 @@
+import { pageRoutePath } from "#dms-core/app/utils/pageRoutes";
+import { onBeforeMount } from "vue";
 import { NotificationEvents } from "./types/events";
 import { unreadToneWith } from "../../build/components/pages/settings/notification/notificationDisplay";
 
@@ -30,13 +32,22 @@ export interface UserNotification {
  * bell, the Notifications entry): the most important unread notification's,
  * which the server weighs as the inbox draws it.
  */
-interface FeedCounts {
+export interface FeedCounts {
   all: number;
   unread: number;
   unreadTone?: NotificationTone;
 }
 
-const API_BASE = "/settings/user/notifications";
+/**
+ * What a write on the feed answers (marking read or unread, deleting), and
+ * what its realtime event carries: the whole feed's counts after it.
+ */
+interface FeedWriteResult {
+  counts?: FeedCounts;
+}
+
+const API_BASE = pageRoutePath("/settings/user/notifications");
+const BELL_COUNTS_DATA_KEY = "dms-notification-bell-counts";
 const NOTIFICATION_COMPONENT_ID = "global-notifications";
 const NOTIFICATIONS_PAGE_SIZE = 20;
 
@@ -130,16 +141,35 @@ export const useNotifications = () => {
     unreadTone.value = counts.unread > 0 ? counts.unreadTone : undefined;
   };
 
+  /** Reads the whole feed's unread count and tone, the bell's badge. */
+  const readBellCounts = (signal?: AbortSignal) =>
+    $authFetch<FeedCounts>(`${API_BASE}/counts`, { signal });
+
+  /** Takes counts as the bell's: from now on, they are known. */
+  const applyBellCounts = (counts: FeedCounts | undefined) => {
+    if (counts) applyFeedCounts(counts);
+    areCountsLoaded.value = true;
+  };
+
   /** Loads the whole feed's unread count and tone, the bell's badge. */
   const fetchBellCounts = async () => {
     try {
-      const counts = await $authFetch<FeedCounts>(`${API_BASE}/counts`);
-      if (counts) applyFeedCounts(counts);
+      applyBellCounts(await readBellCounts());
     } finally {
       areCountsLoaded.value = true;
     }
   };
 
+  /**
+   * Takes the counts a write answered or its realtime event carried. A
+   * write's own event brings the same counts again, which changes nothing;
+   * without counts (a server before they were sent) they are read.
+   */
+  const takeWriteCounts = async (counts: FeedCounts | undefined) => {
+    if (counts) applyBellCounts(counts);
+    else await fetchBellCounts();
+  };
+
   const fetchUnreadPreview = async () => {
     const data = await $authFetch<UserNotification[]>(
       `${API_BASE}/unread-preview`,
@@ -168,30 +198,33 @@ export const useNotifications = () => {
   };
 
   const markAsRead = async (notificationId: string) => {
-    await $authFetch(`${API_BASE}/mark-read/${notificationId}`, {
-      method: "PUT",
-    });
+    const { counts } = await $authFetch<FeedWriteResult>(
+      `${API_BASE}/mark-read/${notificationId}`,
+      { method: "PUT" },
+    );
     setReadState([notificationId], true);
     unreadPreview.value = unreadPreview.value.filter((n) => !n.isRead);
-    await fetchBellCounts();
+    await takeWriteCounts(counts);
     emitRead([notificationId]);
   };
 
   const markAsUnread = async (notificationId: string) => {
-    await $authFetch(`${API_BASE}/mark-unread/${notificationId}`, {
-      method: "PUT",
-    });
+    const { counts } = await $authFetch<FeedWriteResult>(
+      `${API_BASE}/mark-unread/${notificationId}`,
+      { method: "PUT" },
+    );
     setReadState([notificationId], false);
-    await fetchBellCounts();
+    await takeWriteCounts(counts);
     emitCount();
   };
 
   const deleteNotification = async (notificationId: string) => {
-    await $authFetch(`${API_BASE}/delete/${notificationId}`, {
-      method: "DELETE",
-    });
+    const { counts } = await $authFetch<FeedWriteResult>(
+      `${API_BASE}/delete/${notificationId}`,
+      { method: "DELETE" },
+    );
     removeFromLists([notificationId]);
-    await fetchBellCounts();
+    await takeWriteCounts(counts);
 
     sendComponentEvent(
       NotificationEvents.NOTIFICATION_DELETED,
@@ -200,24 +233,26 @@ export const useNotifications = () => {
     );
   };
 
-  const handleRemoteRead = async (ids: string[]) => {
+  // The realtime events of the user's feed, this tab's own writes included:
+  // each carries the feed's counts after it.
+  const handleRemoteRead = async (ids: string[], counts?: FeedCounts) => {
     if (ids.length === 0) return;
     setReadState(ids, true);
     unreadPreview.value = unreadPreview.value.filter((n) => !n.isRead);
-    await fetchBellCounts();
+    await takeWriteCounts(counts);
     emitRead(ids);
   };
 
-  const handleRemoteUnread = async (ids: string[]) => {
+  const handleRemoteUnread = async (ids: string[], counts?: FeedCounts) => {
     if (ids.length === 0) return;
     setReadState(ids, false);
-    await fetchBellCounts();
+    await takeWriteCounts(counts);
     emitCount();
   };
 
-  const handleRemoteAllRead = async () => {
+  const handleRemoteAllRead = async (counts?: FeedCounts) => {
     setAllRead();
-    await fetchBellCounts();
+    await takeWriteCounts(counts);
     emitCount();
   };
 
@@ -251,6 +286,8 @@ export const useNotifications = () => {
     notifications,
     hasMore,
     fetchBellCounts,
+    readBellCounts,
+    applyBellCounts,
     fetchUnreadPreview,
     fetchNotifications,
     markAsRead,
@@ -262,3 +299,47 @@ export const useNotifications = () => {
     handleRemoteAllRead,
   };
 };
+
+/**
+ * The header bell's counts (the unread total and its tone) for the chrome
+ * drawing the bell, called in its setup: read with the page for a signed-in
+ * user, so a server render shows the badge, and the bell's state starts from
+ * the same counts in the browser before anything renders them. The browser
+ * neither asks again nor sees them move as it hydrates (which the inbox would
+ * take for a new notification and list again). The bell then keeps them
+ * current (realtime, its own refreshes).
+ */
+export function useRenderedBellCounts(): void {
+  const notifications = useNotifications();
+  if (
+    !useDmsUserSession().loggedIn.value ||
+    notifications.areCountsLoaded.value
+  )
+    return;
+  const read = useApiData<FeedCounts>(
+    BELL_COUNTS_DATA_KEY,
+    async ({ signal }) => {
+      const counts = await notifications.readBellCounts(signal);
+      notifications.applyBellCounts(counts);
+      return counts;
+    },
+  );
+  // A client navigation into the dashboard mounts the bell before this read
+  // answers: the bell waits for it instead of reading the counts again.
+  if (!import.meta.env.SSR)
+    renderedBellCountsRead = Promise.resolve(read).then(
+      () => undefined,
+      () => undefined,
+    );
+  onBeforeMount(() => {
+    if (read.data.value) notifications.applyBellCounts(read.data.value);
+  });
+}
+
+/** The browser's last `useRenderedBellCounts` read, settled or not. */
+let renderedBellCountsRead: Promise<void> | undefined;
+
+/** Waits for the counts `useRenderedBellCounts` reads, if it reads any. */
+export function settledRenderedBellCounts(): Promise<void> | undefined {
+  return renderedBellCountsRead;
+}

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

@@ -0,0 +1,109 @@
+import type {
+  StoreActionBody,
+  StoreListing,
+  StoreListingEntry,
+  StoreOperationKind,
+} from "../../types/module-store";
+import { isAwaitingFrontend } from "../../build/utils/module-store-catalog";
+
+export const ENDPOINT_STORE_LISTING = "/dms/store/listing";
+const ENDPOINT_STORE_ACTION = "/dms/store";
+/** How often the listing is read while an operation or the frontend runs. */
+const FOLLOW_INTERVAL_MS = 1000;
+
+/**
+ * The module store of the Modules page: the listing, the operations, and the
+ * follow-up that reads the listing again while something moves. An operation
+ * the owner started here reloads the page once the frontend serves its
+ * result, so a new module's pages appear without a manual refresh.
+ */
+export const useModuleStore = () => {
+  // Taken once, in setup: the follow-up reads the listing from a timer,
+  // outside any component context.
+  const { $authFetch } = useAuthFetch();
+  const listing = ref<StoreListing | undefined>(undefined);
+  const loadingError = ref<unknown>(null);
+  /** Modules an operation from this page changed, until the frontend follows. */
+  const awaitingReload = ref(new Set<string>());
+  let followTimer: ReturnType<typeof setTimeout> | undefined;
+
+  const isFollowing = computed(() => {
+    const modules = listing.value?.modules ?? [];
+    return (
+      listing.value?.busy === true ||
+      modules.some((entry) => isAwaitingFrontend(entry))
+    );
+  });
+
+  async function load(): Promise<void> {
+    try {
+      listing.value = await $authFetch<StoreListing>(ENDPOINT_STORE_LISTING);
+      loadingError.value = null;
+    } catch (error) {
+      loadingError.value = error;
+    }
+    reloadWhenServed();
+    scheduleFollow();
+  }
+
+  /**
+   * Reloads the page once every module an operation from here changed is
+   * served by the frontend (or has no interface at all). A frontend that
+   * never reported stays put: the page says what to run instead.
+   */
+  function reloadWhenServed(): void {
+    if (import.meta.env.SSR || awaitingReload.value.size === 0) return;
+    const changed = (listing.value?.modules ?? []).filter((entry) =>
+      awaitingReload.value.has(entry.id),
+    );
+    const isSettled = changed.every(
+      (entry) =>
+        entry.state !== "busy" &&
+        (entry.frontend === "synced" || entry.frontend === "none"),
+    );
+    const needsReload = changed.some((entry) => entry.frontend === "synced");
+    if (!isSettled) return;
+    awaitingReload.value = new Set();
+    if (needsReload) window.location.reload();
+  }
+
+  function scheduleFollow(): void {
+    if (import.meta.env.SSR) return;
+    if (followTimer) clearTimeout(followTimer);
+    followTimer = undefined;
+    if (!isFollowing.value) return;
+    followTimer = setTimeout(() => void load(), FOLLOW_INTERVAL_MS);
+  }
+
+  /**
+   * Starts `kind` on `entry`, with `body` when it carries more than the id;
+   * rejects with the server's answer when refused.
+   */
+  async function run(
+    kind: StoreOperationKind,
+    entry: StoreListingEntry,
+    body: StoreActionBody = { id: entry.id },
+  ): Promise<void> {
+    listing.value = await $authFetch<StoreListing>(
+      `${ENDPOINT_STORE_ACTION}/${kind}`,
+      { method: "POST", body },
+    );
+    awaitingReload.value = new Set([...awaitingReload.value, entry.id]);
+    scheduleFollow();
+  }
+
+  function stop(): void {
+    if (followTimer) clearTimeout(followTimer);
+    followTimer = undefined;
+  }
+
+  return {
+    listing,
+    loadingError,
+    isFollowing,
+    awaitingReload,
+    load,
+    run,
+    stop,
+  };
+};

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

@@ -10,15 +10,7 @@ export interface ModulesListingError {
   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";
 
 function readStatus(error: unknown): number | undefined {
   const details = error as
@@ -33,106 +25,37 @@ function toListingError(error: unknown): ModulesListingError {
   return { kind: "failed", status };
 }
 
+/**
+ * The modules catalog of the Modules page, read for platform owners only (a
+ * member's request would be refused): with the page, so a server render
+ * shows it and hands it to the browser, which does not ask again.
+ */
 export const useModulesListing = () => {
-  const modules = useDmsState<ModuleCatalogEntry[] | undefined>(
-    STATE_KEY_MODULES,
-    () => undefined,
+  const isOwner = useIsOwner();
+  const listing = useApiData<ModuleCatalogEntry[]>(() =>
+    isOwner.value ? ENDPOINT_MODULES_LISTING : null,
   );
-  const isLoading = useDmsState<boolean>(STATE_KEY_LOADING, () => false);
-  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
-  // scope, which the server shares across the requests it renders at once: a
-  // second render would wait on the first one's fetch, whose answer lands in
-  // the first request's state, and render an empty listing.
-  const dmsApp = useDmsApp() as unknown as Record<PropertyKey, unknown>;
-  const inFlightLoadingPromise = {
-    get value(): Promise<void> | null {
-      return (dmsApp[IN_FLIGHT_MODULES_LISTING_KEY] as Promise<void>) ?? null;
-    },
-    set value(promise: Promise<void> | null) {
-      dmsApp[IN_FLIGHT_MODULES_LISTING_KEY] = promise;
-    },
-  };
-
-  /**
-   * 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;
-    if (!keepOnFailure) loadingError.value = null;
 
-    const promise = $authFetch<ModuleCatalogEntry[]>(ENDPOINT_MODULES_LISTING)
-      .then((result) => {
-        modules.value = result;
-        loadingError.value = null;
-        fetchedAt.value = Date.now();
-      })
-      .catch((error: unknown) => {
-        const listingError = toListingError(error);
-        if (keepOnFailure && listingError.kind === "failed") return;
-        loadingError.value = listingError;
-        modules.value = undefined;
-      })
-      .finally(() => {
-        isLoading.value = false;
-        inFlightLoadingPromise.value = null;
-      });
-
-    inFlightLoadingPromise.value = promise;
-    return promise;
-  }
-
-  async function loadModulesListing(): Promise<void> {
-    if (inFlightLoadingPromise.value) {
-      await inFlightLoadingPromise.value;
-      return;
-    }
-    if (modules.value !== undefined) {
-      return;
-    }
-    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;
-    }
-    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);
-  }
+  const loadingError = computed<ModulesListingError | null>(() =>
+    listing.error.value ? toListingError(listing.error.value) : null,
+  );
+  // A failed read replaces the modules with the error.
+  const modules = computed<ModuleCatalogEntry[] | undefined>(() =>
+    loadingError.value ? undefined : (listing.data.value ?? undefined),
+  );
 
   return {
     modules,
-    isLoading,
+    isLoading: listing.pending,
     loadingError,
-    loadModulesListing,
-    refresh,
-    revalidate,
+    /** Waits for the catalog to be read. */
+    loadModulesListing: async (): Promise<void> => {
+      await listing;
+    },
+    /**
+     * Reads the catalog again (Refresh, Try again): the current list stays
+     * on screen while loading, and a failure is shown, not swallowed.
+     */
+    refresh: (): Promise<void> => listing.refresh(),
   };
 };

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

@@ -57,13 +57,3 @@ export function preloadPageLayoutComponents(
 
   loadPageLayoutComponents(layout).catch(() => {});
 }
-
-/**
- * Same as preloadPageLayoutComponents, for speculative loading (e.g. link
- * hover) where the user may never navigate to the page.
- */
-export function prefetchPageLayoutComponents(
-  layout: PageLayout | null | undefined,
-): void {
-  preloadPageLayoutComponents(layout);
-}