@antelopejs/dms 0.12.1 → 0.13.1

package/frontend-vue/layers/dms-core/app/composables/useApiErrorPresenter.ts

@@ -0,0 +1,159 @@
+import { decodeApiFailure } from "../build/composables/api-error";
+
+/** The supported tones for request failures. */
+export type ApiErrorSeverity = "info" | "warning" | "error";
+
+/** Localized text and tone for an inline error. */
+export interface ApiErrorNotice {
+  readonly message: string;
+  readonly severity: ApiErrorSeverity;
+}
+
+/** Placeholder values accepted by error translations. */
+export type ApiErrorParams = Readonly<
+  Record<string, string | number | boolean>
+>;
+
+/** Keys are resolved against loaded catalogs and never displayed verbatim. */
+export interface ResolveApiErrorOptions {
+  readonly fallbackKey: string;
+  readonly params?: ApiErrorParams;
+}
+
+/** A contextual action whose label is also a loaded translation key. */
+export interface ApiErrorAction {
+  readonly labelKey: string;
+  readonly onSelect: () => void | Promise<void>;
+}
+
+/** An existing progress notification, not the identity of a failure. */
+export type ApiErrorToastId = string | number;
+
+/** Toast presentation never overrides the server's translated reason or tone. */
+export interface PresentApiErrorOptions extends ResolveApiErrorOptions {
+  readonly actions?: readonly ApiErrorAction[];
+  readonly replaceToastId?: ApiErrorToastId;
+}
+
+/** Captured during setup and callable after awaits. */
+export interface ApiErrorPresenter {
+  resolveError(
+    error: unknown,
+    options: ResolveApiErrorOptions,
+  ): ApiErrorNotice | null;
+  presentError(error: unknown, options: PresentApiErrorOptions): void;
+}
+
+const GENERIC_KEY = "error.500.description";
+const PRESENTED_STATE_KEY = "dms.apiErrors.presentedResponses";
+const FAILURE_DURATION_MS = 5000;
+const ICONS: Record<ApiErrorSeverity, string> = {
+  info: "i-ph-info",
+  warning: "i-ph-warning",
+  error: "i-ph-warning-circle",
+};
+
+function isCompiledMessage(value: unknown): boolean {
+  return (
+    value !== null &&
+    typeof value === "object" &&
+    (("type" in value && value.type === 0) || ("t" in value && value.t === 0))
+  );
+}
+
+/**
+ * Resolves errors without side effects and presents at most one toast per failed
+ * Response in this app. Aborts without a failed response are silent.
+ */
+export function useApiErrorPresenter(): ApiErrorPresenter {
+  const toast = useToast();
+  const { i18n } = getPluginI18n();
+  const presented = useDmsState(
+    PRESENTED_STATE_KEY,
+    () => new WeakMap<object, ApiErrorToastId | null>(),
+  );
+
+  function lookup(
+    key: string | undefined,
+    params: ApiErrorParams = {},
+  ): string | null {
+    if (!key) return null;
+    try {
+      const message = i18n.tm(key.startsWith("$") ? key.slice(1) : key);
+      if (
+        typeof message !== "string" &&
+        typeof message !== "function" &&
+        !isCompiledMessage(message)
+      )
+        return null;
+      return i18n.rt(message, params);
+    } catch {
+      return null;
+    }
+  }
+
+  function noticeOf(
+    failure: ReturnType<typeof decodeApiFailure>,
+    options: ResolveApiErrorOptions,
+  ): ApiErrorNotice | null {
+    if (failure.cancelled) return null;
+    const params = { ...failure.params, ...options.params };
+    const message =
+      lookup(failure.key, params) ??
+      lookup(options.fallbackKey, params) ??
+      lookup(GENERIC_KEY);
+    if (message === null)
+      throw new Error(
+        "The core error.500.description translation must be loaded",
+      );
+    return { message, severity: failure.severity };
+  }
+
+  function resolveError(
+    error: unknown,
+    options: ResolveApiErrorOptions,
+  ): ApiErrorNotice | null {
+    return noticeOf(decodeApiFailure(error), options);
+  }
+
+  function presentError(error: unknown, options: PresentApiErrorOptions): void {
+    const failure = decodeApiFailure(error);
+    const notice = noticeOf(failure, options);
+    if (import.meta.env.SSR) return;
+    const replacement = options.replaceToastId;
+    const identity = failure.identity;
+    if (!notice || (identity && presented.value.has(identity))) {
+      if (
+        replacement !== undefined &&
+        (!identity || presented.value.get(identity) !== replacement)
+      )
+        toast.remove(replacement);
+      return;
+    }
+    const payload = {
+      title: notice.message,
+      description: undefined,
+      color: notice.severity,
+      icon: ICONS[notice.severity],
+      duration: FAILURE_DURATION_MS,
+      progress: true,
+      actions: options.actions?.flatMap((action) => {
+        const label = lookup(action.labelKey);
+        return label === null ? [] : [{ label, onClick: action.onSelect }];
+      }),
+    };
+    if (identity) presented.value.set(identity, replacement ?? null);
+    try {
+      if (replacement !== undefined) toast.update(replacement, payload);
+      else {
+        const added = toast.add(payload);
+        if (identity) presented.value.set(identity, added.id);
+      }
+    } catch (error) {
+      if (identity) presented.value.delete(identity);
+      throw error;
+    }
+  }
+
+  return { presentError, resolveError };
+}

package/frontend-vue/layers/dms-core/app/composables/useFieldErrors.ts

@@ -1,8 +1,5 @@
 import { nextTick, reactive } from "vue";
-import {
-  type I18nTranslate,
-  resolveApiMessage,
-} from "./translation/useTranslation";
+import { type I18nTranslate } from "./translation/useTranslation";
 import { resolveApiErrorMessage } from "./useApiError";
 import { isBoolean, isNumber, isObject, isString } from "../utils/type-check";
 
@@ -19,11 +16,10 @@ import { isBoolean, isNumber, isObject, isString } from "../utils/type-check";
 export interface ApiFieldError {
   /** Id of the field, as the form names it (the request body key). */
   field: string;
-  /**
-   * What to show under the field: an i18n key (bare `error.xxx` or `$key`)
-   * or prose, resolved with `resolveApiMessage`.
-   */
+  /** Server translation key, resolved by the API error presenter. */
   message: string;
+  /** Caller key used only when the server's message is not translated. */
+  fallbackKey?: string;
   /** The values of the field the error names (addresses of a list…). */
   values?: string[];
   /**
@@ -325,7 +321,7 @@ function lookupCode<F extends string>(
   if (!entry) return undefined;
   return isString(entry)
     ? { field: entry, message: code }
-    : { field: entry.field, message: entry.message };
+    : { field: entry.field, message: code, fallbackKey: entry.message };
 }
 
 function fromBody(body: ReturnType<typeof bodyOf>): ApiFieldError[] {
@@ -489,11 +485,7 @@ export interface HandleApiErrorOptions {
 export function useFieldErrors<F extends string>(
   options: UseFieldErrorsOptions<F>,
 ) {
-  const { t } = useI18n();
-  const toast = useToast();
-  const consumeReadOnlyRefusal = useReadOnlyRefusal();
-  const translate = (key: string, params: Parameters<I18nTranslate>[1] = {}) =>
-    t(key, params);
+  const { presentError, resolveError } = useApiErrorPresenter();
   const fieldIds = Object.keys(options.fields) as F[];
   const errors: Partial<Record<F, string>> = reactive({});
 
@@ -549,21 +541,20 @@ export function useFieldErrors<F extends string>(
   async function applyApiError(
     error: Parameters<typeof resolveApiErrorMessage>[0],
   ): Promise<boolean> {
-    const { fields } = resolveFieldErrors(error, {
+    const { fields, hasUnmatched } = resolveFieldErrors(error, {
       fields: fieldIds,
       codes: options.codes,
     });
     if (fields.length === 0) return false;
     clear();
     for (const entry of fields) {
-      errors[entry.field as F] = resolveApiMessage(
-        translate,
-        entry.message,
-        entry.params,
-      );
+      errors[entry.field as F] = resolveError(entry.message, {
+        fallbackKey: entry.fallbackKey ?? "dms.field_errors.invalid",
+        params: entry.params,
+      })?.message;
     }
     await focus(fields[0]!.field as F);
-    return true;
+    return !hasUnmatched;
   }
   /* oxlint-enable anti-slop/require-safety-comment-for-type-assertion */
 
@@ -572,13 +563,8 @@ export function useFieldErrors<F extends string>(
     error: Parameters<typeof resolveApiErrorMessage>[0],
     toastOptions: HandleApiErrorOptions,
   ) {
-    if (consumeReadOnlyRefusal(error)) return;
-    toast.add({
-      title: t(toastOptions.toastTitle),
-      description: toastOptions.toastDescription
-        ? t(toastOptions.toastDescription)
-        : resolveApiMessage(translate, describeApiError(error)),
-      color: "error",
+    presentError(error, {
+      fallbackKey: toastOptions.toastDescription ?? toastOptions.toastTitle,
     });
   }
 
@@ -591,7 +577,6 @@ export function useFieldErrors<F extends string>(
     error: Parameters<typeof resolveApiErrorMessage>[0],
     toastOptions: HandleApiErrorOptions,
   ): Promise<boolean> {
-    if (consumeReadOnlyRefusal(error)) return false;
     if (await applyApiError(error)) return true;
     toastError(error, toastOptions);
     return false;

package/frontend-vue/layers/dms-layout/app/build/components/layout/PageHeaderActionBar.vue

@@ -75,13 +75,15 @@ const { quickActions } = siteLayout;
 const route = useDmsRoute();
 const router = useDmsRouter();
 const { $authFetch } = useAuthFetch();
+const { presentError } = useApiErrorPresenter();
 
 const { handleCustomButton } = useActionTargets({
   api: $authFetch,
   componentId: "page-header",
   pageId: siteLayout.findMatchingRoute(route.path)?.metadata?.fullId ?? "page",
   refreshCallback: refreshPageBlocks,
-  handleApiError: (error, title) => useApiError(error, { title }),
+  handleApiError: (error, title) =>
+    presentError(error, { fallbackKey: title ?? "error.500.description" }),
 });
 
 function pressComponentButton(componentId: string, buttonId?: string) {

package/frontend-vue/layers/dms-layout/app/build/components/pages/settings/notification/NotificationInboxDisplay.vue

@@ -27,7 +27,7 @@ const props = defineProps<NotificationInboxDisplayProps>();
 const SKELETON_ROWS = 3;
 
 const { t, locale } = useI18n();
-const toast = useToast();
+const { presentError } = useApiErrorPresenter();
 const { confirm } = useConfirm();
 const catalog = useNotificationCatalog();
 const {
@@ -70,8 +70,8 @@ const runThenRefresh = async (action: () => ReturnType<typeof markAsRead>) => {
     await action();
 
     await nextTick();
-  } catch {
-    toast.add({ title: t("dms.form.error_title"), color: "error" });
+  } catch (error) {
+    presentError(error, { fallbackKey: "dms.form.error_title" });
   } finally {
     ownChanges--;
   }

package/frontend-vue/layers/dms-layout/app/build/components/pages/settings/profile/ProfilePersonalInfo.vue

@@ -44,6 +44,7 @@ const EMAIL_ANCHOR = "#email";
 
 const { t } = useI18n();
 const toast = useToast();
+const { presentError } = useApiErrorPresenter();
 const { $authFetch } = useAuthFetch();
 const { processApiMessage } = useTranslation();
 const { user, refresh: refreshSession } = useCurrentUser();
@@ -130,10 +131,9 @@ async function onFileChange(event: Event): Promise<void> {
     }
     avatar.value = { key: result.key! };
     pickedAvatarUrl.value = URL.createObjectURL(file);
-  } catch {
-    toast.add({
-      title: t("page.settings.profile.avatar_error"),
-      color: "error",
+  } catch (error) {
+    presentError(error, {
+      fallbackKey: "page.settings.profile.avatar_error",
     });
   } finally {
     isUploading.value = false;

package/frontend-vue/layers/dms-layout/app/build/components/pages/settings/security/SecurityEmail.vue

@@ -38,6 +38,7 @@ const FIELD_CODES = {
 
 const { t } = useI18n();
 const toast = useToast();
+const { presentError } = useApiErrorPresenter();
 const { $authFetch } = useAuthFetch();
 const { refresh: refreshSession } = useCurrentUser();
 const { overview, refresh } = useSecurityOverview();
@@ -180,9 +181,8 @@ async function submit(): Promise<void> {
     isCodeOpen.value = true;
   } catch (error) {
     if (await flagField(error)) return;
-    toast.add({
-      title: errorMessage(error, "page.settings.security.email.error"),
-      color: "error",
+    presentError(error, {
+      fallbackKey: "page.settings.security.email.error",
     });
   } finally {
     isSaving.value = false;
@@ -217,9 +217,8 @@ async function confirmCode(code: string): Promise<void> {
       );
       return;
     }
-    toast.add({
-      title: errorMessage(error, "page.settings.security.email.error"),
-      color: "error",
+    presentError(error, {
+      fallbackKey: "page.settings.security.email.error",
     });
     if (errorCode(error) === CODE_BURNT) {
       isCodeOpen.value = false;
@@ -239,9 +238,8 @@ async function cancelChange(): Promise<void> {
     });
     await refresh();
   } catch (error) {
-    toast.add({
-      title: errorMessage(error, "page.settings.security.email.error"),
-      color: "error",
+    presentError(error, {
+      fallbackKey: "page.settings.security.email.error",
     });
   }
 }

package/frontend-vue/layers/dms-layout/app/build/components/pages/settings/security/SecurityPassword.vue

@@ -36,10 +36,11 @@ const CONFIRM_FIELD_ID = "security-confirm-password";
 
 const { t } = useI18n();
 const toast = useToast();
+const { presentError } = useApiErrorPresenter();
 const { $authFetch } = useAuthFetch();
 const { processApiMessage } = useTranslation();
 const { overview, refresh } = useSecurityOverview();
-const { formatDate, daysSince, errorMessage } = useSecurityFormat();
+const { formatDate, daysSince } = useSecurityFormat();
 const { passwordSchema } = usePasswordStrength(ref(""));
 const adoptSessionHandoff = useSessionHandoff();
 
@@ -170,9 +171,8 @@ async function submit(): Promise<void> {
       document.getElementById(CURRENT_FIELD_ID)?.focus();
       return;
     }
-    toast.add({
-      title: errorMessage(error, "page.settings.security.password.error"),
-      color: "error",
+    presentError(error, {
+      fallbackKey: "page.settings.security.password.error",
     });
   } finally {
     isSaving.value = false;

package/frontend-vue/layers/dms-layout/app/build/components/pages/settings/security/SecuritySessions.vue

@@ -50,10 +50,11 @@ const DEVICE_ICONS: Readonly<
 
 const { t } = useI18n();
 const toast = useToast();
+const { presentError } = useApiErrorPresenter();
 const { $authFetch } = useAuthFetch();
 const adoptSessionHandoff = useSessionHandoff();
 const { overview, refresh: refreshOverview } = useSecurityOverview();
-const { formatDate, formatRelative, errorMessage } = useSecurityFormat();
+const { formatDate, formatRelative } = useSecurityFormat();
 
 const list = useApiData<SessionsRead>(SESSIONS_URL, {
   transform: (sessions) => ({
@@ -106,9 +107,8 @@ async function revoke(session: SessionInfo): Promise<void> {
     toast.add({ title: t("page.settings.sessions.revoked"), color: "success" });
     await refreshOverview();
   } catch (error) {
-    toast.add({
-      title: errorMessage(error, "page.settings.sessions.revoke_error"),
-      color: "error",
+    presentError(error, {
+      fallbackKey: "page.settings.sessions.revoke_error",
     });
   } finally {
     revokingId.value = null;
@@ -134,9 +134,8 @@ async function signOutOthers(): Promise<void> {
     });
     await Promise.all([fetchSessions(), refreshOverview()]);
   } catch (error) {
-    toast.add({
-      title: errorMessage(error, "page.settings.sessions.revoke_all_error"),
-      color: "error",
+    presentError(error, {
+      fallbackKey: "page.settings.sessions.revoke_all_error",
     });
   } finally {
     isSigningOutOthers.value = false;

package/frontend-vue/layers/dms-layout/app/build/components/pages/settings/security/SecurityTwoFactor.vue

@@ -65,6 +65,7 @@ const METHODS: MethodConfig[] = [
 
 const { t } = useI18n();
 const toast = useToast();
+const { presentError } = useApiErrorPresenter();
 const { $authFetch } = useAuthFetch();
 const { overview, attention, attentionToneOf, refresh } = useSecurityOverview();
 const { formatDate, errorMessage } = useSecurityFormat();
@@ -148,7 +149,7 @@ function fail(
   error: Parameters<typeof errorMessage>[0],
   fallbackKey: string,
 ): void {
-  toast.add({ title: errorMessage(error, fallbackKey), color: "error" });
+  presentError(error, { fallbackKey });
 }
 
 function showCodes(

package/frontend-vue/layers/dms-layout/app/build/composables/settings/profile/useAccountData.ts

@@ -12,7 +12,6 @@ import {
 } from "#dms-ui/app/composables/confirm/types";
 import { resolveFieldErrors } from "#dms-core/app/composables/useFieldErrors";
 import { REQUIRED_MESSAGE } from "#dms-core/app/composables/useFormValidation";
-import { useSecurityFormat } from "../security/useSecurityFormat";
 
 const PROFILE_ENDPOINT = pageRoutePath("/settings/user/profile");
 const EXPORT_ENDPOINT = `${PROFILE_ENDPOINT}/account-export`;
@@ -63,24 +62,14 @@ function useAccountDataContext() {
   const { confirm } = useConfirm();
   const { user, clear } = useDmsUserSession<User>();
   const { removeAccount } = useMultiAccount();
-  const { processI18n, processApiMessage } = useTranslation();
-  const { errorMessage, errorCode } = useSecurityFormat();
+  const { processApiMessage } = useTranslation();
+  const { presentError, resolveError } = useApiErrorPresenter();
   const toast = useToast();
   const { t } = useI18n();
 
   const isExporting = ref(false);
   const isCheckingDeletion = ref(false);
 
-  /** A message key the API answers with (`$…`), else a known error code. */
-  function describeError(
-    error: Parameters<typeof errorCode>[0],
-    fallbackKey: string,
-  ): string {
-    const code = errorCode(error);
-    if (code?.startsWith("$")) return processI18n(code);
-    return errorMessage(error, fallbackKey);
-  }
-
   async function exportData(): Promise<void> {
     isExporting.value = true;
     try {
@@ -97,11 +86,7 @@ function useAccountDataContext() {
         title: t(`${I18N}.export_done`),
       });
     } catch (error) {
-      toast.add({
-        color: "error",
-        icon: "i-ph-warning-circle",
-        title: describeError(error, `${I18N}.export_error`),
-      });
+      presentError(error, { fallbackKey: `${I18N}.export_error` });
     } finally {
       isExporting.value = false;
     }
@@ -128,7 +113,8 @@ function useAccountDataContext() {
     t,
     isExporting,
     isCheckingDeletion,
-    describeError,
+    presentError,
+    resolveError,
     exportData,
     signOutDeleted,
   };
@@ -260,11 +246,10 @@ export function useAccountData() {
   const {
     $authFetch,
     confirm,
-    processApiMessage,
-    toast,
+    presentError,
+    resolveError,
     t,
     isCheckingDeletion,
-    describeError,
     signOutDeleted,
   } = context;
   const { impactList, passwordField, explainBlockers, passwordCheck } =
@@ -305,19 +290,18 @@ export function useAccountData() {
         },
       }).fields;
       if (fieldError?.field === "confirmation") {
-        throw new ConfirmTextError(processApiMessage(fieldError.message));
+        throw new ConfirmTextError(fieldError.message, { cause: error });
       }
       if (fieldError?.field === "password") {
-        passwordError.value = processApiMessage(fieldError.message);
+        passwordError.value = resolveError(fieldError.message, {
+          fallbackKey: fieldError.fallbackKey ?? "dms.field_errors.invalid",
+          params: fieldError.params,
+        })?.message;
         await nextTick();
         passwordInput.value?.inputRef?.focus();
         return false;
       }
-      toast.add({
-        color: "error",
-        icon: "i-ph-warning-circle",
-        title: describeError(error, `${I18N}.delete_error`),
-      });
+      presentError(error, { fallbackKey: `${I18N}.delete_error` });
       return false;
     }
   }
@@ -353,11 +337,7 @@ export function useAccountData() {
     try {
       impact = await $authFetch<AccountDeletionImpact>(DELETION_ENDPOINT);
     } catch (error) {
-      toast.add({
-        color: "error",
-        icon: "i-ph-warning-circle",
-        title: describeError(error, `${I18N}.delete_error`),
-      });
+      presentError(error, { fallbackKey: `${I18N}.delete_error` });
       return;
     } finally {
       isCheckingDeletion.value = false;

package/frontend-vue/layers/dms-layout/app/build/composables/settings/security/useSecurityFormat.ts

@@ -7,8 +7,6 @@ const MS_PER_HOUR = 60 * MS_PER_MINUTE;
 const MS_PER_DAY = 24 * MS_PER_HOUR;
 const MS_PER_MONTH = 30 * MS_PER_DAY;
 const MS_PER_YEAR = 365 * MS_PER_DAY;
-const ERROR_CODE_PREFIX = "error.";
-const SECURITY_ERRORS_PREFIX = "page.settings.security.errors.";
 
 interface RelativeUnit {
   unit: Intl.RelativeTimeFormatUnit;
@@ -35,7 +33,8 @@ type DateInput = string | Date;
  * translation of API error codes into sentences.
  */
 export function useSecurityFormat() {
-  const { locale, t, te } = useI18n();
+  const { locale } = useI18n();
+  const { resolveError } = useApiErrorPresenter();
 
   const formatDate = (value: DateInput): string =>
     regionalDateTimeFormat(locale.value, { dateStyle: "medium" }).format(
@@ -74,14 +73,7 @@ export function useSecurityFormat() {
    */
   // oxlint-disable-next-line anti-slop/no-unknown-parameters -- JavaScript throws arbitrary values. FetchError-derived parameters would reject the boundary inputs this formatter already handles.
   const errorMessage = (error: unknown, fallbackKey: string): string => {
-    // oxlint-disable-next-line anti-slop/require-safety-comment-for-type-assertion -- Unchecked optional property projection preserves primitive and nullish thrown values; this is not a validated FetchError and owner typing cannot guarantee one.
-    const code = (error as FetchErrorLike | undefined)?.data;
-    if (!isString(code) || !code.startsWith(ERROR_CODE_PREFIX)) {
-      return t(fallbackKey);
-    }
-    const ownKey = `${SECURITY_ERRORS_PREFIX}${code.slice(ERROR_CODE_PREFIX.length)}`;
-    if (te(ownKey)) return t(ownKey);
-    return te(code) ? t(code) : t(fallbackKey);
+    return resolveError(error, { fallbackKey })?.message ?? "";
   };
 
   /** @returns The error code (`error.xxx`) the API answered with, if any */

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

@@ -23,6 +23,7 @@ const FOLLOW_INTERVAL_MS = 1000;
  */
 export const useModuleStore = () => {
   const { $authFetch } = useAuthFetch();
+  const { resolveError } = useApiErrorPresenter();
   const isOwner = useIsOwner();
 
   const initial = useApiData<StoreListing>(() =>
@@ -42,6 +43,13 @@ export const useModuleStore = () => {
       ? (initial.error.value ?? null)
       : followError.value,
   );
+  const loadingNotice = computed(() =>
+    loadingError.value
+      ? resolveError(loadingError.value, {
+          fallbackKey: "modules.store.load_error",
+        })
+      : null,
+  );
   /** Modules an operation from this page changed, until the frontend follows. */
   const awaitingReload = ref(new Set<string>());
   let followTimer: ReturnType<typeof setTimeout> | undefined;
@@ -151,6 +159,7 @@ export const useModuleStore = () => {
   return {
     listing,
     loadingError,
+    loadingNotice,
     isFollowing,
     awaitingReload,
     load,