// Turns a route's action result into the save confirmation at the top of the // screen. One hook call per screen, so every list and detail page reports a // save the same way. // // The contract is the action result shape the routes already return: // { intent?: string; ok?: true; error?: string } // `error` is an i18n key (never a raw message), which is what keeps the toast // inside the Klartext rule (A.1) instead of printing a provider string. // // Success is only ever reported for `ok === true` — the server's own answer. // A pending or failed write cannot produce a green toast. import { useEffect, useMemo, useRef } from "react"; import { useTranslation } from "react-i18next"; import { useLocation } from "react-router"; import { toast } from "sonner"; import { SaveToast } from "~/components/notifications/SaveToast"; /** How long a toast stays before it removes itself. */ export const SAVE_TOAST_DURATION_MS = 4000; export type ToastMessageValues = Readonly>; export type SaveActionResult = { readonly intent?: string | null; readonly ok?: boolean; /** * i18n key of a headline the action picked itself ("Tresor archiviert"). * Several routes already answer with one; it wins over the screen's default * so the confirmation names what actually ran. */ readonly messageKey?: string | null; /** Interpolation values for the success headline, e.g. a bulk-action count. */ readonly messageValues?: ToastMessageValues | null; /** i18n key describing what went wrong. */ readonly error?: string | null; /** Alias used by newer action contracts. */ readonly errorKey?: string | null; /** Interpolation values for the error detail. */ readonly errorValues?: ToastMessageValues | null; } | null | undefined; export type UseSaveToastOptions = { /** * i18n key of the success headline. Defaults to the shared "Gespeichert", * which is what almost every screen wants. */ readonly successKey?: string; /** Intent-specific success headlines for actions that only return an intent. */ readonly successKeyByIntent?: Readonly>; /** Optional detail line under the success headline. */ readonly successDescriptionKey?: string; /** * Keep successful, immediately visible UI changes quiet while still * reporting action errors. Defaults to true. */ readonly reportSuccess?: boolean; /** * Only report results of these intents. A screen whose action serves several * purposes (save, search, export) would otherwise toast for all of them. * Omit to report every result. */ readonly intents?: readonly string[]; }; /** * Fires exactly once per action result. React Router hands back the same * object identity until the next submission, so comparing the reference is * what keeps a re-render from toasting again. */ export function useSaveToast(result: SaveActionResult, options: UseSaveToastOptions = {}): void { const { t } = useTranslation(); const lastReported = useRef(undefined); // The latest copy is read inside the effect, so changing options between // renders never re-fires a toast that was already shown. const latest = useRef({ t, options }); latest.current = { t, options }; useEffect(() => { if (!result) return; if (lastReported.current === result) return; lastReported.current = result; const { t: translate, options: current } = latest.current; if (current.intents && !current.intents.includes(result.intent ?? "")) return; const errorKey = result.error ?? result.errorKey; if (errorKey) { // A key with no translation would print the key itself, which is exactly // the cryptic output the Klartext rule forbids — fall back to plain text. const detail = translate(errorKey, { ...result.errorValues, defaultValue: translate("shared.saveToast.errorFallback"), }); toast.custom( () => ( ), { duration: SAVE_TOAST_DURATION_MS } ); return; } if (result.ok !== true || current.reportSuccess === false) return; const intentKey = result.intent ? current.successKeyByIntent?.[result.intent] : undefined; const titleKey = result.messageKey || intentKey || current.successKey || "shared.saveToast.successTitle"; const title = translate(titleKey, { ...result.messageValues, defaultValue: translate("shared.saveToast.successTitle"), }); toast.custom( () => ( ), { duration: SAVE_TOAST_DURATION_MS } ); }, [result]); } /** * Reports a successful mutation that completed with a redirect. * * Routes opt in by appending `?toast=` to their redirect target. * The parameter is removed immediately after it has been consumed so reloads, * copied links and browser history do not repeat stale confirmations. */ export function useRedirectToast(): void { const location = useLocation(); const messageKey = new URLSearchParams(location.search).get("toast"); const result = useMemo( () => (messageKey ? { ok: true as const, messageKey } : undefined), [messageKey] ); useSaveToast(result); useEffect(() => { if (!messageKey) return; const url = new URL(window.location.href); url.searchParams.delete("toast"); window.history.replaceState( window.history.state, "", `${url.pathname}${url.search}${url.hash}` ); }, [messageKey]); }