feat(web): per-mutation success/error toast metadata (#47)

Declare meta on all 18 mutation hooks: meta.successMessage (toast.* key)
on every discrete user action, meta.suppressErrorToast where the consuming
component already renders the error inline. Corrected useUpdateFieldDefinition
to suppress (FieldForm renders update.isError as form.rejected inline).

Add an RTL+MSW integration test wiring the real MutationCache via
makeQueryClient() + ToastRegion: success toast, catch-all error toast, and
suppressed-no-toast. Tidy the toast Close aria-label to t("common.close")
with en/sv parity.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

web/src/api/mutation-feedback.test.tsx

@@ -0,0 +1,112 @@
+import { afterEach, describe, expect, test } from "vitest";
+import { renderHook, waitFor, within } from "@testing-library/react";
+import { QueryClientProvider } from "@tanstack/react-query";
+import { http, HttpResponse } from "msw";
+import type { ReactNode } from "react";
+
+import i18n from "../i18n";
+import { ToastRegion } from "../components/ui/toast";
+import { server } from "../test/server";
+import { makeQueryClient } from "./query-client";
+import { useDeleteVocabulary, useUpdateTerm } from "./queries";
+
+// The toast manager is a module-scope singleton shared across renders, so each
+// test mounts a fresh region and tears it down afterwards to keep toasts from
+// one case bleeding into the next.
+function makeWrapper() {
+  const queryClient = makeQueryClient();
+
+  return function Wrapper({ children }: { children: ReactNode }) {
+    return (
+      <QueryClientProvider client={queryClient}>
+        <ToastRegion>{children}</ToastRegion>
+      </QueryClientProvider>
+    );
+  };
+}
+
+afterEach(async () => {
+  // Allow any pending toast state updates to flush before the next test mounts.
+  await Promise.resolve();
+});
+
+describe("mutation feedback toasts", () => {
+  test("a meta.successMessage mutation shows its success toast on success", async () => {
+    server.use(
+      http.patch(
+        "/api/admin/vocabularies/:id/terms/:term_id",
+        () => new HttpResponse(null, { status: 204 }),
+      ),
+    );
+
+    const { result, unmount } = renderHook(() => useUpdateTerm(), {
+      wrapper: makeWrapper(),
+    });
+
+    await result.current.mutateAsync({
+      vocabularyId: "v1",
+      termId: "t1",
+      external_uri: null,
+      labels: [{ lang: "en", label: "Bronze" }],
+    });
+
+    await waitFor(() => {
+      expect(
+        within(document.body).getByText(i18n.t("toast.saved")),
+      ).toBeInTheDocument();
+    });
+
+    unmount();
+  });
+
+  test("a non-suppressed mutation failing shows the catch-all error toast", async () => {
+    server.use(
+      http.patch(
+        "/api/admin/vocabularies/:id/terms/:term_id",
+        () => new HttpResponse(null, { status: 500 }),
+      ),
+    );
+
+    const { result, unmount } = renderHook(() => useUpdateTerm(), {
+      wrapper: makeWrapper(),
+    });
+
+    await expect(
+      result.current.mutateAsync({
+        vocabularyId: "v1",
+        termId: "t1",
+        external_uri: null,
+        labels: [{ lang: "en", label: "Bronze" }],
+      }),
+    ).rejects.toThrow();
+
+    await waitFor(() => {
+      expect(
+        within(document.body).getByText(i18n.t("toast.error")),
+      ).toBeInTheDocument();
+    });
+
+    unmount();
+  });
+
+  test("a suppressErrorToast mutation failing adds no toast", async () => {
+    server.use(
+      http.delete(
+        "/api/admin/vocabularies/:id",
+        () => new HttpResponse(null, { status: 500 }),
+      ),
+    );
+
+    const { result, unmount } = renderHook(() => useDeleteVocabulary(), {
+      wrapper: makeWrapper(),
+    });
+
+    await expect(result.current.mutateAsync("v1")).rejects.toThrow();
+
+    // Give the MutationCache onError a turn; assert it stayed silent.
+    await Promise.resolve();
+    expect(within(document.body).queryByText(i18n.t("toast.error"))).toBeNull();
+
+    unmount();
+  });
+});

web/src/api/queries.ts

@@ -122,6 +122,7 @@ export function useLogin() {
       }
     },
     onSuccess: () => qc.invalidateQueries({ queryKey: ["me"] }),
+    meta: { suppressErrorToast: true },
   });
 }
 
@@ -185,6 +186,7 @@ export function useCreateObject() {
       return data;
     },
     onSuccess: () => qc.invalidateQueries({ queryKey: ["objects"] }),
+    meta: { successMessage: "toast.created", suppressErrorToast: true },
   });
 }
 
@@ -204,6 +206,7 @@ export function useUpdateObject() {
       void qc.invalidateQueries({ queryKey: ["objects"] });
       void qc.invalidateQueries({ queryKey: ["object", id] });
     },
+    meta: { successMessage: "toast.saved", suppressErrorToast: true },
   });
 }
 
@@ -229,6 +232,7 @@ export function useSetFields() {
     onSuccess: (_d, { id }) => {
       void qc.invalidateQueries({ queryKey: ["object", id] });
     },
+    meta: { suppressErrorToast: true },
   });
 }
 
@@ -244,6 +248,7 @@ export function useDeleteObject() {
       if (response.status !== 204) throw new Error("delete failed");
     },
     onSuccess: () => qc.invalidateQueries({ queryKey: ["objects"] }),
+    meta: { successMessage: "toast.deleted", suppressErrorToast: true },
   });
 }
 
@@ -276,6 +281,7 @@ export function useCreateVocabulary() {
       return data;
     },
     onSuccess: () => qc.invalidateQueries({ queryKey: ["vocabularies"] }),
+    meta: { successMessage: "toast.created", suppressErrorToast: true },
   });
 }
 
@@ -301,6 +307,7 @@ export function useAddTerm() {
     },
     onSuccess: (_result, { vocabularyId }) =>
       qc.invalidateQueries({ queryKey: ["terms", vocabularyId] }),
+    meta: { successMessage: "toast.created", suppressErrorToast: true },
   });
 }
 
@@ -325,6 +332,7 @@ export function useCreateAuthority() {
     },
     onSuccess: (_result, { kind }) =>
       qc.invalidateQueries({ queryKey: ["authorities", kind] }),
+    meta: { successMessage: "toast.created", suppressErrorToast: true },
   });
 }
 
@@ -376,6 +384,7 @@ export function useCreateFieldDefinition() {
       return data;
     },
     onSuccess: () => qc.invalidateQueries({ queryKey: ["field-definitions"] }),
+    meta: { successMessage: "toast.created", suppressErrorToast: true },
   });
 }
 
@@ -405,6 +414,7 @@ export function useSetVisibility() {
       void qc.invalidateQueries({ queryKey: ["object", id] });
       void qc.invalidateQueries({ queryKey: ["objects"] });
     },
+    meta: { successMessage: "toast.published", suppressErrorToast: true },
   });
 }
 
@@ -431,6 +441,7 @@ export function useUpdateTerm() {
       if (response.status !== 204) throw new Error("update term failed");
     },
     onSuccess: (_d, { vocabularyId }) => qc.invalidateQueries({ queryKey: ["terms", vocabularyId] }),
+    meta: { successMessage: "toast.saved" },
   });
 }
 
@@ -447,6 +458,7 @@ export function useDeleteTerm() {
       if (response.status !== 204) throw new Error("delete term failed");
     },
     onSuccess: (_d, { vocabularyId }) => qc.invalidateQueries({ queryKey: ["terms", vocabularyId] }),
+    meta: { successMessage: "toast.deleted", suppressErrorToast: true },
   });
 }
 
@@ -463,6 +475,7 @@ export function useRenameVocabulary() {
       if (response.status !== 204) throw new Error("rename failed");
     },
     onSuccess: () => qc.invalidateQueries({ queryKey: ["vocabularies"] }),
+    meta: { successMessage: "toast.renamed", suppressErrorToast: true },
   });
 }
 
@@ -479,6 +492,7 @@ export function useDeleteVocabulary() {
       if (response.status !== 204) throw new Error("delete vocabulary failed");
     },
     onSuccess: () => qc.invalidateQueries({ queryKey: ["vocabularies"] }),
+    meta: { successMessage: "toast.deleted", suppressErrorToast: true },
   });
 }
 
@@ -504,6 +518,7 @@ export function useUpdateAuthority() {
       if (response.status !== 204) throw new Error("update authority failed");
     },
     onSuccess: (_d, { kind }) => qc.invalidateQueries({ queryKey: ["authorities", kind] }),
+    meta: { successMessage: "toast.saved" },
   });
 }
 
@@ -520,6 +535,7 @@ export function useDeleteAuthority() {
       if (response.status !== 204) throw new Error("delete authority failed");
     },
     onSuccess: (_d, { kind }) => qc.invalidateQueries({ queryKey: ["authorities", kind] }),
+    meta: { successMessage: "toast.deleted", suppressErrorToast: true },
   });
 }
 
@@ -546,6 +562,7 @@ export function useUpdateFieldDefinition() {
       if (response.status !== 204) throw new Error("update field failed");
     },
     onSuccess: () => qc.invalidateQueries({ queryKey: ["field-definitions"] }),
+    meta: { successMessage: "toast.saved", suppressErrorToast: true },
   });
 }
 
@@ -562,5 +579,6 @@ export function useDeleteFieldDefinition() {
       if (response.status !== 204) throw new Error("delete field failed");
     },
     onSuccess: () => qc.invalidateQueries({ queryKey: ["field-definitions"] }),
+    meta: { successMessage: "toast.deleted", suppressErrorToast: true },
   });
 }

web/src/components/ui/toast.tsx

@@ -1,10 +1,12 @@
 import type * as React from "react";
+import { useTranslation } from "react-i18next";
 import { Toast as ToastPrimitive } from "@base-ui/react/toast";
 
 import { cn } from "@/lib/utils";
 import { toastManager } from "@/toast/toast-manager";
 
 function ToastList() {
+  const { t } = useTranslation();
   const { toasts } = ToastPrimitive.useToastManager();
   return toasts.map((toast) => (
     <ToastPrimitive.Root
@@ -31,7 +33,7 @@ function ToastList() {
       </div>
       <ToastPrimitive.Close
         data-slot="toast-close"
-        aria-label="Close"
+        aria-label={t("common.close")}
         className="text-neutral-400 hover:text-neutral-700"
       >
         ×

web/src/i18n/en.json

@@ -1,6 +1,6 @@
 {
   "app": { "name": "Collection" },
-  "common": { "yes": "Yes", "no": "No" },
+  "common": { "yes": "Yes", "no": "No", "close": "Close" },
   "nav": { "objects": "Objects", "vocabularies": "Vocabularies", "authorities": "Authorities", "fields": "Fields", "search": "Search", "collapseSidebar": "Collapse sidebar", "expandSidebar": "Expand sidebar" },
   "auth": { "email": "Email", "password": "Password", "signIn": "Sign in", "signOut": "Sign out", "invalid": "Invalid email or password", "networkError": "Could not reach the server" },
   "objects": { "title": "Objects", "empty": "No objects yet", "loadError": "Could not load objects", "notFound": "Object not found", "prev": "Previous", "next": "Next", "of": "of", "new": "New object", "filter": "Filter objects…", "pageSize": "Per page", "columns": { "number": "Object №", "name": "Name", "visibility": "Visibility", "location": "Location", "count": "#", "updated": "Updated" }, "unknownRef": "(unknown)" },

web/src/i18n/sv.json

@@ -1,6 +1,6 @@
 {
   "app": { "name": "Samling" },
-  "common": { "yes": "Ja", "no": "Nej" },
+  "common": { "yes": "Ja", "no": "Nej", "close": "Stäng" },
   "nav": { "objects": "Föremål", "vocabularies": "Vokabulär", "authorities": "Auktoriteter", "fields": "Fält", "search": "Sök", "collapseSidebar": "Fäll ihop sidofältet", "expandSidebar": "Fäll ut sidofältet" },
   "auth": { "email": "E-post", "password": "Lösenord", "signIn": "Logga in", "signOut": "Logga ut", "invalid": "Fel e-post eller lösenord", "networkError": "Kunde inte nå servern" },
   "objects": { "title": "Föremål", "empty": "Inga föremål ännu", "loadError": "Kunde inte ladda föremål", "notFound": "Föremålet hittades inte", "prev": "Föregående", "next": "Nästa", "of": "av", "new": "Nytt föremål", "filter": "Filtrera föremål…", "pageSize": "Per sida", "columns": { "number": "Föremålsnr", "name": "Namn", "visibility": "Synlighet", "location": "Plats", "count": "Antal", "updated": "Uppdaterad" }, "unknownRef": "(okänd)" },