fix(ui): clarify document errors and retain readable actions

job-tracker-ui/src/views/CvBuilderEditor.tsx

@@ -41,6 +41,8 @@ import {
 import { previewDocumentHtml } from "../cvPreview";
 import { useDialogActions } from "../dialogs";
 import { useI18n } from "../i18n/I18nProvider";
+import { PageHeader } from "../layout/PageLayout";
+import ViewStateNotice from "../components/ViewStateNotice";
 
 const MIN_PREVIEW_ZOOM = 0.2;
 type SaveState = "idle" | "unsaved" | "saving" | "saved" | "error" | "conflict";
@@ -75,7 +77,9 @@ export default function CvBuilderEditor() {
   const [exporting, setExporting] = useState(false);
   const [publishing, setPublishing] = useState(false);
   const [versions, setVersions] = useState<CvVariantVersionInfo[]>([]);
-  const [loadError, setLoadError] = useState<string | null>(null);
+  const [loadError, setLoadError] = useState<{ status?: number } | null>(null);
+  const [loadAttempt, setLoadAttempt] = useState(0);
+  const [opening, setOpening] = useState(true);
   const [mobilePane, setMobilePane] = useState<"edit" | "preview">("edit");
   const [historyRevision, setHistoryRevision] = useState(0);
 
@@ -93,6 +97,8 @@ export default function CvBuilderEditor() {
   const iframeRef = useRef<HTMLIFrameElement | null>(null);
   const scrollRef = useRef<HTMLDivElement | null>(null);
   const editorRef = useRef<HTMLDivElement | null>(null);
+  const loadRegion = useRef<HTMLDivElement | null>(null);
+  const retryFocus = useRef(false);
   const blockerPromptOpen = useRef(false);
   const undoStack = useRef<CvVariantSettings[]>([]);
   const redoStack = useRef<CvVariantSettings[]>([]);
@@ -103,6 +109,7 @@ export default function CvBuilderEditor() {
 
   useEffect(() => {
     let alive = true;
+    setOpening(true);
     (async () => {
       try {
         const [variant, themeList, outlineData] = await Promise.all([
@@ -114,16 +121,24 @@ export default function CvBuilderEditor() {
         applyVariant(variant);
         setThemes(themeList);
         setOutline(outlineData);
+        setLoadError(null);
       } catch (err) {
-        if (alive) setLoadError(getApiErrorMessage(err, t("cvEditorOpenFailed")));
+        if (alive) setLoadError({ status: (err as { response?: { status?: number } })?.response?.status });
+      } finally {
+        if (alive) setOpening(false);
       }
     })();
     return () => {
       alive = false;
       editorEpoch.current += 1;
     };
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [variantId]);
+  }, [variantId, loadAttempt]);
+
+  useEffect(() => {
+    if (!retryFocus.current || opening) return;
+    retryFocus.current = false;
+    (loadError ? loadRegion.current : editorRef.current)?.focus();
+  }, [opening, loadError]);
 
   const applyVariant = (variant: CvVariant) => {
     if (saveTimer.current) clearTimeout(saveTimer.current);
@@ -514,10 +529,15 @@ export default function CvBuilderEditor() {
   }, [compactEditor, editorReady, fitPreview, mobilePane]);
 
   if (loadError) {
+    const denied = loadError.status === 401 || loadError.status === 403;
     return (
-      <Box sx={{ p: 3 }}>
+      <Box ref={loadRegion} role="region" aria-label={t("cvEditorOpenFailed")} tabIndex={-1} aria-busy={opening} sx={{ display: "grid", gap: "var(--app-section-gap)", minWidth: 0 }}>
+        <PageHeader level="h2" title={t("cvBuilder")} />
         <Button startIcon={<ArrowBackIcon />} onClick={() => navigate("/career/builder")}>{t("cvEditorBack")}</Button>
-        <Alert severity="error" sx={{ mt: 2 }}>{loadError}</Alert>
+        <ViewStateNotice loading={opening} title={t("cvEditorOpenFailed")}
+          description={loadError.status === 404 ? t("cvEditorSourceUnavailable") : denied ? t("cvEditorPermissionDenied") : undefined}
+          error={{ kind: denied ? "unauthorized" : "unavailable", message: t("cvEditorOpenFailed"), retryable: !loadError.status || loadError.status >= 500 || loadError.status === 429 }}
+          onRetry={() => { retryFocus.current = true; loadRegion.current?.focus(); setLoadAttempt(value => value + 1); }} />
       </Box>
     );
   }
@@ -578,8 +598,8 @@ export default function CvBuilderEditor() {
         <Stack direction="row" justifyContent="space-between" alignItems="center" sx={{ px: 1.5, py: 0.5, borderBottom: "1px solid", borderColor: "divider" }}>
           <Typography component="h2" variant="subtitle2">{t("cvEditorEditingRegion")}</Typography>
           <Stack direction="row">
-            <Tooltip title={t("cvEditorUndo")}><span><IconButton size="small" aria-label={t("cvEditorUndo")} disabled={!canUndo} onClick={undo}><UndoIcon fontSize="small" /></IconButton></span></Tooltip>
-            <Tooltip title={t("cvEditorRedo")}><span><IconButton size="small" aria-label={t("cvEditorRedo")} disabled={!canRedo} onClick={redo}><RedoIcon fontSize="small" /></IconButton></span></Tooltip>
+            <Tooltip describeChild title={t("cvEditorUndo")}><span><IconButton size="small" aria-label={t("cvEditorUndo")} disabled={!canUndo} onClick={undo}><UndoIcon fontSize="small" /></IconButton></span></Tooltip>
+            <Tooltip describeChild title={t("cvEditorRedo")}><span><IconButton size="small" aria-label={t("cvEditorRedo")} disabled={!canRedo} onClick={redo}><RedoIcon fontSize="small" /></IconButton></span></Tooltip>
           </Stack>
         </Stack>
         <Tabs aria-label={t("cvEditorStudioNavigation")} value={tab} onChange={(_, v) => { setTab(v); if (v === 4) loadVersions(); }} variant="scrollable" scrollButtons="auto" allowScrollButtonsMobile sx={{ borderBottom: "1px solid", borderColor: "divider" }}>
@@ -1360,17 +1380,20 @@ function HistoryTab({ versions, onRestore }: { versions: CvVariantVersionInfo[];
   return (
     <Stack spacing={0.5}>
       <Typography variant="caption" color="text.secondary">{t("cvEditorVersionCount", { count: versions.length })}</Typography>
-      {versions.map((v) => (
+      {versions.map((v) => {
+        const sources = { autosave: "historySourceAutosave", manual: "historySourceManual", restore: "historySourceRestore", create: "historySourceCreate" } as const;
+        const source = Object.hasOwn(sources, v.source) ? sources[v.source as keyof typeof sources] : undefined;
+        return (
         <Paper key={v.version} variant="outlined" sx={{ p: 1, display: "flex", alignItems: "center", gap: 1 }}>
           <Box sx={{ flex: 1 }}>
-            <Typography variant="body2" sx={{ fontWeight: 700 }}>
+            <Typography component="div" variant="body2" sx={{ fontWeight: 700 }}>
               {t("cvEditorVersion", { version: v.version })} {v.isCurrent && <Chip size="small" label={t("cvEditorCurrent")} sx={{ ml: 0.5, height: 18 }} />}
             </Typography>
-            <Typography variant="caption" color="text.secondary">{relTime(v.createdAtUtc, language)} · {v.source}</Typography>
+            <Typography variant="caption" color="text.secondary">{relTime(v.createdAtUtc, language)} · {source ? t(source) : v.source}</Typography>
           </Box>
           {!v.isCurrent && <Button size="small" aria-label={t("cvEditorRestoreTitle", { version: v.version })} onClick={() => onRestore(v.version)}>{t("cvEditorRestore")}</Button>}
         </Paper>
-      ))}
+      ); })}
     </Stack>
   );
 }