@antelopejs/dms 0.9.8 → 0.11.0

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

@@ -1,8 +1,17 @@
-import { computed, shallowRef, watch, type ComputedRef } from "vue";
+import {
+  computed,
+  onScopeDispose,
+  shallowRef,
+  watch,
+  type ComputedRef,
+} from "vue";
+import { onPageBlocksRefresh } from "#dms-ui/app/utils/blockRefresh";
 import type { LayoutHeaderAction } from "../../build/components/layout/PageHeaderActionBar.vue";
 import type { PageLayout } from "../../types/page";
 import {
   isSamePageQuery,
+  isSameRouteParams,
+  fillRouteParams,
   layoutUrlWithQuery,
   pageQueryValues,
 } from "../../utils/pageQuery";
@@ -11,10 +20,12 @@ interface ServedHeaderActionsOptions {
   /** The buttons the page layout was served with. */
   actions: () => LayoutHeaderAction[];
   /**
-   * The page query their availability was resolved for, set when one of them
-   * declares an `availability` (`headerActionsQuery`).
+   * The page query they were served for, set when one of them declares an
+   * `availability` or the page reads a `record` (`headerActionsQuery`).
    */
   servedQuery: () => Record<string, string> | undefined;
+  /** The route parameters (`:id`) their availability was resolved for. */
+  servedParams?: () => Record<string, string> | undefined;
 }
 
 /**
@@ -22,20 +33,25 @@ interface ServedHeaderActionsOptions {
  * `availability` depends on the query (`?workspace=` names the record the
  * page acts on) was resolved for the query the layout was loaded with: when
  * the URL's query moves away from it, the header asks the page layout again
- * for that query and takes its buttons, keeping the last ones meanwhile.
- * Buttons without an availability never cause a request.
+ * for that query and takes its buttons, keeping the last ones meanwhile. The
+ * same goes for the route parameters: the layout of `/projects/project/:id`
+ * is cached once for the page, whichever record it was first served for.
+ * A write on the page (`refreshPageBlocks()`, after a header button or a
+ * form) asks again too: it may have changed the record the buttons read, or
+ * what their availability checks. Buttons without an availability, on a page
+ * reading no record, never cause a request.
  */
 export function useServedHeaderActions({
   actions,
   servedQuery,
+  servedParams = () => undefined,
 }: ServedHeaderActionsOptions): ComputedRef<LayoutHeaderAction[]> {
   const route = useDmsRoute();
   const siteLayout = useSiteLayout();
   const refreshed = shallowRef<LayoutHeaderAction[] | null>(null);
   let latestRequest = 0;
 
-  const layoutUrl = () =>
-    siteLayout.findMatchingRoute(route.path)?.metadata?.layoutUrl;
+  const pageRoute = () => siteLayout.findMatchingRoute(route.path);
 
   async function askFor(url: string, query: Record<string, string>) {
     const request = ++latestRequest;
@@ -58,17 +74,39 @@ export function useServedHeaderActions({
   function follow() {
     const served = servedQuery();
     const current = pageQueryValues(route.query as Record<string, unknown>);
-    const url = layoutUrl();
-    if (!served || !url || isSamePageQuery(served, current)) {
+    const match = pageRoute();
+    const layoutUrl = match?.metadata?.layoutUrl;
+    const params = match?.params ?? {};
+    const paramsServed = servedParams();
+    if (
+      !served ||
+      !layoutUrl ||
+      (isSamePageQuery(served, current) &&
+        (!paramsServed || isSameRouteParams(paramsServed, params)))
+    ) {
       latestRequest++;
       refreshed.value = null;
       return;
     }
-    void askFor(url, current);
+    void askFor(fillRouteParams(layoutUrl, params), current);
+  }
+
+  function askAgain() {
+    const layoutUrl = pageRoute()?.metadata?.layoutUrl;
+    if (!servedQuery() || !layoutUrl) return;
+    void askFor(
+      fillRouteParams(layoutUrl, pageRoute()?.params ?? {}),
+      pageQueryValues(route.query as Record<string, unknown>),
+    );
   }
 
   if (!import.meta.env.SSR) {
-    watch([() => route.query, servedQuery], follow, { immediate: true });
+    watch(
+      [() => route.query, () => route.path, servedQuery, servedParams],
+      follow,
+      { immediate: true },
+    );
+    onScopeDispose(onPageBlocksRefresh(askAgain));
   }
 
   return computed(() => refreshed.value ?? actions());

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

@@ -44,8 +44,9 @@ function normalizeHistory(raw: unknown): StoredHistory {
 
 /**
  * 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.
+ * and the server renders the same "recently used" order as the browser. It
+ * feeds that order and the command palette's recent modules; it never decides
+ * where entering a module lands, which is always the module's landing page.
  */
 export const useModuleHistory = (): ModuleHistoryApi => {
   const cookie = useDmsCookie<StoredHistory>(MODULE_HISTORY_COOKIE, {

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

@@ -16,13 +16,35 @@ const FOLLOW_INTERVAL_MS = 1000;
  * 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.
+ *
+ * The first read comes with the page (`useApiData`): a server render waits
+ * for it and hands it over, so the tiles render with their store details and
+ * never move once mounted.
  */
 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);
+  const isOwner = useIsOwner();
+  // Platform owners only: a member's read would be refused.
+  const initial = useApiData<StoreListing>(() =>
+    isOwner.value ? ENDPOINT_STORE_LISTING : null,
+  );
+  // The follow-up reads write into the same data, so a later visit shows
+  // the latest listing at once.
+  const listing = computed<StoreListing | undefined>({
+    get: () => initial.data.value ?? undefined,
+    set: (value) => {
+      initial.data.value = value ?? null;
+    },
+  });
+  /** The last follow-up read's failure; `null` once one succeeds. */
+  const followError = ref<unknown>(undefined);
+  const loadingError = computed<unknown>(() =>
+    followError.value === undefined
+      ? (initial.error.value ?? null)
+      : followError.value,
+  );
   /** Modules an operation from this page changed, until the frontend follows. */
   const awaitingReload = ref(new Set<string>());
   let followTimer: ReturnType<typeof setTimeout> | undefined;
@@ -38,9 +60,38 @@ export const useModuleStore = () => {
   async function load(): Promise<void> {
     try {
       listing.value = await $authFetch<StoreListing>(ENDPOINT_STORE_LISTING);
-      loadingError.value = null;
+      followError.value = null;
     } catch (error) {
-      loadingError.value = error;
+      followError.value = error;
+    }
+    reloadWhenServed();
+    scheduleFollow();
+  }
+
+  let isStopped = false;
+  let stopWaiting: (() => void) | undefined;
+
+  /**
+   * Starts following once mounted: reads again only when the first read
+   * failed, or something moves; a listing already on screen stays as is.
+   * A read still in flight (a client navigation, or the background read of a
+   * return to the page) is waited for until it settles.
+   */
+  function start(): void {
+    isStopped = false;
+    stopWaiting?.();
+    if (initial.pending.value) {
+      stopWaiting = watch(initial.pending, (pending) => {
+        if (pending) return;
+        stopWaiting?.();
+        stopWaiting = undefined;
+        if (!isStopped) start();
+      });
+      return;
+    }
+    if (!listing.value) {
+      void load();
+      return;
     }
     reloadWhenServed();
     scheduleFollow();
@@ -93,6 +144,9 @@ export const useModuleStore = () => {
   }
 
   function stop(): void {
+    isStopped = true;
+    stopWaiting?.();
+    stopWaiting = undefined;
     if (followTimer) clearTimeout(followTimer);
     followTimer = undefined;
   }
@@ -103,6 +157,7 @@ export const useModuleStore = () => {
     isFollowing,
     awaitingReload,
     load,
+    start,
     run,
     stop,
   };

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

@@ -0,0 +1,194 @@
+import type { Ref, VNode } from "vue";
+import ModuleStoreDependencyPicker from "../../build/components/pages/modules/ModuleStoreDependencyPicker.vue";
+import {
+  ConfirmActionError,
+  useConfirm,
+} from "#dms-ui/app/composables/confirm";
+import {
+  type ModuleStoreEntry,
+  isAwaitingFrontend,
+  needsDependencyChoice,
+} from "../../build/utils/module-store-catalog";
+import {
+  type DependencyDraft,
+  areDependencyDraftsValid,
+  buildInstallBody,
+  createDependencyDrafts,
+} from "../../build/utils/module-store-install";
+import type {
+  StoreActionBody,
+  StoreOperationKind,
+} from "../../types/module-store";
+import type { useModuleStore } from "./useModuleStore";
+
+/** What a refused store request carries: the server's error key, if any. */
+interface StoreRequestError {
+  data?: unknown;
+  message?: string;
+}
+
+/** What the frontend banner says while it lags behind the backend. */
+export interface StoreFrontendNotice {
+  key: "dev" | "production" | "unknown";
+  names: string;
+}
+
+type ModuleStore = ReturnType<typeof useModuleStore>;
+
+/**
+ * The store's actions as both Modules views run them: the confirmations,
+ * the install dialog that picks the modules for missing interfaces, and a
+ * refusal worded from the server's error key. Also what the frontend banner
+ * says while the interface lags behind the backend.
+ */
+export const useModuleStoreActions = (
+  moduleStore: ModuleStore,
+  entries: Ref<ModuleStoreEntry[]>,
+) => {
+  const { t } = useI18n();
+  const { processI18n } = useTranslation();
+  const toast = useToast();
+  const { confirm } = useConfirm();
+
+  function resolveStoreError(error: unknown): string {
+    const details = error as StoreRequestError | undefined;
+    const key = typeof details?.data === "string" ? details.data : undefined;
+    if (!key) return details?.message ?? "";
+    return t(`modules.store.errors.${key.replace("error.", "")}`);
+  }
+
+  /**
+   * Runs `kind` from a dialog: a refusal is worded as the toast words it and
+   * shown in the dialog, which stays open.
+   */
+  async function runFromDialog(
+    kind: StoreOperationKind,
+    entry: ModuleStoreEntry,
+    body?: StoreActionBody,
+  ): Promise<void> {
+    try {
+      await moduleStore.run(kind, entry, body);
+    } catch (error) {
+      throw new ConfirmActionError({
+        title: t("modules.store.action_failed", {
+          module: processI18n(entry.title),
+        }),
+        description: resolveStoreError(error),
+      });
+    }
+  }
+
+  /** What the owner last picked in a module's install dialog, for a retry. */
+  const lastDependencyDrafts = new Map<string, DependencyDraft[]>();
+
+  function renderDependencyPicker(
+    entry: ModuleStoreEntry,
+    drafts: Ref<DependencyDraft[]>,
+    showErrors: boolean,
+  ): VNode {
+    return h(ModuleStoreDependencyPicker, {
+      missing: entry.missingInterfaces,
+      drafts: drafts.value,
+      showErrors,
+      onUpdate: (index: number, patch: Partial<DependencyDraft>) => {
+        drafts.value = drafts.value.map((draft, position) =>
+          position === index ? { ...draft, ...patch } : draft,
+        );
+      },
+    });
+  }
+
+  /**
+   * Asks which modules implement the interfaces the release misses, then
+   * installs them with it. A refusal shows in the dialog, kept open.
+   */
+  async function installWithDependencies(
+    entry: ModuleStoreEntry,
+  ): Promise<void> {
+    const title = processI18n(entry.title);
+    const drafts = ref(
+      createDependencyDrafts(
+        entry.missingInterfaces,
+        lastDependencyDrafts.get(entry.id),
+      ),
+    );
+    const showErrors = ref(false);
+    await confirm({
+      title: t("modules.store.install_dialog.title", { module: title }),
+      description: t("modules.store.install_dialog.description", {
+        module: title,
+      }),
+      confirmLabel: t("modules.store.actions.install"),
+      confirmIcon: "i-ph-download-simple",
+      icon: "i-ph-puzzle-piece",
+      body: () => renderDependencyPicker(entry, drafts, showErrors.value),
+      validate: () => {
+        showErrors.value = true;
+        return areDependencyDraftsValid(drafts.value);
+      },
+      onConfirm: async () => {
+        lastDependencyDrafts.set(entry.id, drafts.value);
+        await runFromDialog(
+          "install",
+          entry,
+          buildInstallBody(entry.id, drafts.value),
+        );
+      },
+    });
+  }
+
+  async function runStoreAction(
+    kind: StoreOperationKind,
+    entry: ModuleStoreEntry,
+  ): Promise<void> {
+    const title = processI18n(entry.title);
+    if (needsDependencyChoice(entry, kind)) {
+      await installWithDependencies(entry);
+      return;
+    }
+    if (kind === "uninstall") {
+      await confirm({
+        title: t("modules.store.uninstall_confirm.title", { module: title }),
+        description: t("modules.store.uninstall_confirm.description", {
+          module: title,
+        }),
+        confirmLabel: t("modules.store.actions.uninstall"),
+        color: "error",
+        icon: "i-ph-trash",
+        onConfirm: () => runFromDialog(kind, entry),
+      });
+      return;
+    }
+    try {
+      await moduleStore.run(kind, entry);
+    } catch (error) {
+      toast.add({
+        color: "error",
+        icon: "i-ph-warning-circle",
+        title: t("modules.store.action_failed", { module: title }),
+        description: resolveStoreError(error),
+      });
+    }
+  }
+
+  /** Store modules whose interface the running frontend does not match yet. */
+  const frontendNotice = computed<StoreFrontendNotice | null>(() => {
+    const lagging = entries.value.filter(
+      (entry) =>
+        isAwaitingFrontend(entry) ||
+        (entry.frontend === "unknown" &&
+          moduleStore.awaitingReload.value.has(entry.id)),
+    );
+    if (lagging.length === 0) return null;
+    const names = lagging.map((entry) => processI18n(entry.title)).join(", ");
+    const hasReported = lagging.every((entry) => entry.frontend !== "unknown");
+    const key = !hasReported
+      ? "unknown"
+      : moduleStore.listing.value?.dev
+        ? "dev"
+        : "production";
+    return { key, names };
+  });
+
+  return { runStoreAction, frontendNotice };
+};

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

@@ -49,16 +49,36 @@ function loadPageLayoutComponents(
   );
 }
 
+// How long a navigation waits for the chunks of the page's blocks: on any
+// usable network they land well within it, and one that hangs does not hold
+// the page for long (its block then loads as it renders).
+export const PAGE_COMPONENTS_WAIT_MS = 3_000;
+
 /**
  * Start fetching the chunks of every component a page layout references,
  * in parallel, instead of letting each <Component :is> trigger its own
  * fetch when it mounts (which waterfalls for nested children).
  * No-op on the server: SSR resolves async components during render.
+ *
+ * Settles once they are all in, or failed, or after
+ * `PAGE_COMPONENTS_WAIT_MS`: the page's setup awaits it, so a client
+ * navigation shows the page with its blocks' code there. A lazy block
+ * renders nothing until its chunk lands, then pushes the page down and
+ * draws its skeleton again.
  */
 export function preloadPageLayoutComponents(
   layout: PageLayout | null | undefined,
-): void {
-  if (import.meta.env.SSR) return;
+): Promise<void> {
+  if (import.meta.env.SSR) return Promise.resolve();
 
-  loadPageLayoutComponents(layout).catch(() => {});
+  const loaded = loadPageLayoutComponents(layout).then(
+    () => {},
+    () => {},
+  );
+  return Promise.race([
+    loaded,
+    new Promise<void>((resolve) =>
+      setTimeout(resolve, PAGE_COMPONENTS_WAIT_MS),
+    ),
+  ]);
 }

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

@@ -1,4 +1,4 @@
-import { pageQueryValues } from "../../utils/pageQuery";
+import { fillRouteParams, pageQueryValues } from "../../utils/pageQuery";
 
 /**
  * Reads the same page cache that Inertia hydrates before navigation. Missing
@@ -8,8 +8,9 @@ export async function usePageLayout() {
   const route = useDmsRoute();
   const siteLayout = useSiteLayout();
 
+  const match = computed(() => siteLayout.findMatchingRoute(route.path));
   const layoutUrl = computed(() => {
-    const metadata = siteLayout.findMatchingRoute(route.path)?.metadata;
+    const metadata = match.value?.metadata;
     return metadata?.hasAccess === false ? undefined : metadata?.layoutUrl;
   });
   const pageLayout = computed(() =>
@@ -24,6 +25,7 @@ export async function usePageLayout() {
       await siteLayout.loadPageLayout(
         layoutUrl.value,
         pageQueryValues(route.query),
+        fillRouteParams(layoutUrl.value, match.value?.params ?? {}),
       );
     }
   };

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

@@ -0,0 +1,162 @@
+import { onScopeDispose, type Ref, watch } from "vue";
+import type { RealtimeTopicHandler } from "#dms-core/app/composables/realtime/useUserRealtime";
+import type { PageLayout } from "../../types/page";
+import {
+  fillRouteParams,
+  isSamePageQuery,
+  isSameRouteParams,
+  isViewStateKey,
+  layoutUrlWithQuery,
+  pageQueryValues,
+} from "../../utils/pageQuery";
+
+// One frame: the events of one burst (a bulk delete) read the record once.
+const BURST_WINDOW_MS = 16;
+
+/** How the server read the record a page shows (`DefaultLayout({ record })`). */
+type PageRecordStatus = "found" | "missing" | "error";
+
+interface RecordLayoutOptions {
+  recordStatus?: PageRecordStatus;
+  headerActionsQuery?: Record<string, string>;
+  headerActionsParams?: Record<string, string>;
+}
+
+/** What the page's record deletion listens to. */
+export interface PageRecordDeletionSource {
+  /** The page's layout as it was first served. */
+  pageLayout: () => PageLayout | null;
+  /** The page's realtime topics, once its session is subscribed to it. */
+  pageTopics: Ref<string[]>;
+  subscribe(topic: string, handler: RealtimeTopicHandler): () => void;
+}
+
+const optionsOf = (layout: PageLayout | null | undefined) =>
+  layout?.layout.options as RecordLayoutOptions | undefined;
+
+/**
+ * Leaves a detail page whose record was deleted, in every tab and for every
+ * member on it. The layout of a page reading a record (`DefaultLayout({
+ * record })`) says how the server read it (`recordStatus`); on each event of
+ * one of the page's realtime topics, the page asks its layout again, and a
+ * record it had `found` that is now `missing` was deleted: a toast says so,
+ * and the page opens its list (`MenuOptions.parent`), or stays on its
+ * not-found blocks without one. A page reading no record never asks.
+ */
+export function usePageRecordDeletion(source: PageRecordDeletionSource): void {
+  if (import.meta.env.SSR) return;
+  const route = useDmsRoute();
+  const siteLayout = useSiteLayout();
+  const toast = useToast();
+  const { t } = useI18n();
+
+  const pageRoute = () => siteLayout.findMatchingRoute(route.path);
+  const currentQuery = () =>
+    pageQueryValues(route.query as Record<string, unknown>);
+  /** The page URL the record is named by, leaving out the view's state. */
+  const recordKey = () =>
+    JSON.stringify([
+      route.path,
+      Object.entries(currentQuery()).filter(([name]) => !isViewStateKey(name)),
+    ]);
+
+  let known: { key: string; status: PageRecordStatus } | undefined;
+  let latestRead = 0;
+
+  async function readStatus(): Promise<PageRecordStatus | undefined> {
+    const match = pageRoute();
+    const layoutUrl = match?.metadata?.layoutUrl;
+    if (!layoutUrl) return undefined;
+    const { $authFetch } = useAuthFetch();
+    try {
+      const layout = await $authFetch<PageLayout>(
+        layoutUrlWithQuery(
+          fillRouteParams(layoutUrl, match.params ?? {}),
+          currentQuery(),
+        ),
+      );
+      return optionsOf(layout)?.recordStatus;
+    } catch {
+      // Unknown: the record is not taken for deleted on a failed read.
+      return undefined;
+    }
+  }
+
+  async function leave(): Promise<void> {
+    toast.add({
+      title: t("page.record_deleted.title"),
+      description: t("page.record_deleted.description"),
+      color: "warning",
+      icon: "i-ph-trash",
+    });
+    const match = pageRoute();
+    const parentSlug = match?.metadata?.parentSlug;
+    if (!parentSlug) return;
+    const path = fillRouteParams(parentSlug, match.params ?? {});
+    if (path.includes(":")) return;
+    const parent = siteLayout.findMatchingRoute(path)?.metadata;
+    if (!parent || parent.hasAccess === false) return;
+    await navigateDms(path, { replace: true });
+  }
+
+  async function check(): Promise<void> {
+    const key = recordKey();
+    const read = ++latestRead;
+    const status = await readStatus();
+    if (read !== latestRead || key !== recordKey() || !status) return;
+    const previous = known?.key === key ? known.status : undefined;
+    known = { key, status };
+    if (previous === "found" && status === "missing") await leave();
+  }
+
+  const declaresRecord = () =>
+    optionsOf(source.pageLayout())?.recordStatus !== undefined;
+
+  // What the page was served with stands for its URL when it was served for
+  // it; another record of the same page is read once to know where it stands.
+  function follow(): void {
+    if (known?.key === recordKey()) return;
+    latestRead++;
+    known = undefined;
+    const options = optionsOf(source.pageLayout());
+    if (!options?.recordStatus) return;
+    const served =
+      isSamePageQuery(options.headerActionsQuery ?? {}, currentQuery()) &&
+      isSameRouteParams(
+        options.headerActionsParams ?? {},
+        pageRoute()?.params ?? {},
+      );
+    if (served) known = { key: recordKey(), status: options.recordStatus };
+    else void check();
+  }
+
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  // Presence snapshots ride the same topics: they carry no `type`.
+  const onEvent: RealtimeTopicHandler = (event) => {
+    if (!("type" in event) || !declaresRecord()) return;
+    clearTimeout(timer);
+    timer = setTimeout(() => void check(), BURST_WINDOW_MS);
+  };
+
+  let unsubscribes: Array<() => void> = [];
+  const unsubscribeAll = () => {
+    for (const unsubscribe of unsubscribes) unsubscribe();
+    unsubscribes = [];
+  };
+  watch(
+    source.pageTopics,
+    (topics) => {
+      unsubscribeAll();
+      unsubscribes = topics.map((topic) => source.subscribe(topic, onEvent));
+    },
+    { immediate: true },
+  );
+  watch([() => route.path, () => route.query, source.pageLayout], follow, {
+    immediate: true,
+  });
+  onScopeDispose(() => {
+    unsubscribeAll();
+    clearTimeout(timer);
+    latestRead++;
+  });
+}

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

@@ -331,9 +331,14 @@ export const useSiteLayout = () => {
    * URL's, which the first request carries for the header buttons whose
    * availability reads it (the header asks again for another query).
    */
+  /**
+   * The layout of the page at `slug`, cached under it. `url`, the layout
+   * route with the page's `:id` filled in, is what is asked when it differs.
+   */
   const loadPageLayout = async (
     slug: string,
     query?: Record<string, string>,
+    url = slug,
   ): Promise<PageLayout> => {
     if (pageLayouts.value[slug]) {
       return pageLayouts.value[slug];
@@ -347,7 +352,7 @@ export const useSiteLayout = () => {
 
     const { $authFetch } = useAuthFetch();
     const request = $authFetch<PageLayout>(
-      layoutUrlWithQuery(slug, query ?? {}),
+      layoutUrlWithQuery(url, query ?? {}),
     ).then((result) => {
       if (pageLayouts.value === cache) cache[slug] = result;
       return result;