From 31fea43729f22f4972ed3e09fef3ddb3140c16d1 Mon Sep 17 00:00:00 2001
From: Cyril <c.gromoff@gmail.com>
Date: Wed, 25 Mar 2026 11:53:47 +0100
Subject: [PATCH] =?UTF-8?q?=E2=99=BF=EF=B8=8F(frontend)=20structure=205xx?=
 =?UTF-8?q?=20error=20alerts?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Use h1/p for 500/502/503; pass status from doc and version views.
---
 CHANGELOG.md                                  |  4 +++
 .../impress/src/components/TextErrors.tsx     | 34 +++++++++++++++++++
 .../components/DocVersionEditor.tsx           |  1 +
 .../doc-versioning/components/VersionList.tsx |  1 +
 src/frontend/apps/impress/src/hooks/index.ts  |  1 +
 .../src/hooks/useHttpErrorMessages.tsx        | 26 ++++++++++++++
 .../impress/src/pages/docs/[id]/index.tsx     |  1 +
 7 files changed, 68 insertions(+)
 create mode 100644 src/frontend/apps/impress/src/hooks/useHttpErrorMessages.tsx

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 060a0af0..102c6b60 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -12,6 +12,10 @@ and this project adheres to
 - 🐛(frontend) abort check media status unmount #2194
 - ✨(backend) order pinned documents by last updated at #2028
 
+### Changed
+
+ - ♿️(frontend) structure correctly 5xx error alerts #2128
+
 ## [v4.8.6] - 2026-04-08
 
 ### Added
diff --git a/src/frontend/apps/impress/src/components/TextErrors.tsx b/src/frontend/apps/impress/src/components/TextErrors.tsx
index d5c635e2..996cf0f6 100644
--- a/src/frontend/apps/impress/src/components/TextErrors.tsx
+++ b/src/frontend/apps/impress/src/components/TextErrors.tsx
@@ -4,6 +4,7 @@ import { useTranslation } from 'react-i18next';
 import styled from 'styled-components';
 
 import { Box, Text, TextType } from '@/components';
+import { useHttpErrorMessages } from '@/hooks';
 
 const AlertStyled = styled(Alert)`
   & .c__button--tertiary:hover {
@@ -16,6 +17,7 @@ interface TextErrorsProps extends TextType {
   defaultMessage?: string;
   icon?: ReactNode;
   canClose?: boolean;
+  status?: number;
 }
 
 export const TextErrors = ({
@@ -23,6 +25,7 @@ export const TextErrors = ({
   defaultMessage,
   icon,
   canClose = false,
+  status,
   ...textProps
 }: TextErrorsProps) => {
   return (
@@ -35,6 +38,7 @@ export const TextErrors = ({
       <TextOnlyErrors
         causes={causes}
         defaultMessage={defaultMessage}
+        status={status}
         {...textProps}
       />
     </AlertStyled>
@@ -44,9 +48,39 @@ export const TextErrors = ({
 export const TextOnlyErrors = ({
   causes,
   defaultMessage,
+  status,
   ...textProps
 }: TextErrorsProps) => {
   const { t } = useTranslation();
+  const httpError = useHttpErrorMessages(status);
+
+  if (httpError) {
+    return (
+      <Box $direction="column" $gap="0.2rem">
+        <Text
+          as="h1"
+          $theme="error"
+          $textAlign="center"
+          $margin="0"
+          $size="1rem"
+          $weight="unset"
+          {...textProps}
+        >
+          {httpError.title}
+        </Text>
+        <Text
+          as="p"
+          $theme="error"
+          $textAlign="center"
+          $margin="0"
+          $size="0.875rem"
+          {...textProps}
+        >
+          {httpError.detail}
+        </Text>
+      </Box>
+    );
+  }
 
   return (
     <Box $direction="column" $gap="0.2rem">
diff --git a/src/frontend/apps/impress/src/features/docs/doc-versioning/components/DocVersionEditor.tsx b/src/frontend/apps/impress/src/features/docs/doc-versioning/components/DocVersionEditor.tsx
index f903e70e..50c79eb0 100644
--- a/src/frontend/apps/impress/src/features/docs/doc-versioning/components/DocVersionEditor.tsx
+++ b/src/frontend/apps/impress/src/features/docs/doc-versioning/components/DocVersionEditor.tsx
@@ -58,6 +58,7 @@ export const DocVersionEditor = ({
       <Box $margin="large" className="--docs--doc-version-editor-error">
         <TextErrors
           causes={error.cause}
+          status={error.status}
           icon={
             error.status === 502 ? (
               <Text
diff --git a/src/frontend/apps/impress/src/features/docs/doc-versioning/components/VersionList.tsx b/src/frontend/apps/impress/src/features/docs/doc-versioning/components/VersionList.tsx
index c6ab1566..69778402 100644
--- a/src/frontend/apps/impress/src/features/docs/doc-versioning/components/VersionList.tsx
+++ b/src/frontend/apps/impress/src/features/docs/doc-versioning/components/VersionList.tsx
@@ -62,6 +62,7 @@ const VersionListState = ({
         >
           <TextErrors
             causes={error.cause}
+            status={error.status}
             icon={
               error.status === 502 ? (
                 <Icon iconName="wifi_off" $theme="danger" />
diff --git a/src/frontend/apps/impress/src/hooks/index.ts b/src/frontend/apps/impress/src/hooks/index.ts
index 340eaa5d..cd243993 100644
--- a/src/frontend/apps/impress/src/hooks/index.ts
+++ b/src/frontend/apps/impress/src/hooks/index.ts
@@ -1,4 +1,5 @@
 export * from './useClipboard';
 export * from './useCmdK';
 export * from './useDate';
+export * from './useHttpErrorMessages';
 export * from './useKeyboardAction';
diff --git a/src/frontend/apps/impress/src/hooks/useHttpErrorMessages.tsx b/src/frontend/apps/impress/src/hooks/useHttpErrorMessages.tsx
new file mode 100644
index 00000000..4d488a90
--- /dev/null
+++ b/src/frontend/apps/impress/src/hooks/useHttpErrorMessages.tsx
@@ -0,0 +1,26 @@
+import { useTranslation } from 'react-i18next';
+
+export const useHttpErrorMessages = (status?: number) => {
+  const { t } = useTranslation();
+
+  const messages: Record<number, { title: string; detail: string }> = {
+    500: {
+      title: t('500 - Internal Server Error'),
+      detail: t('The server met an unexpected condition.'),
+    },
+    502: {
+      title: t('502 - Bad Gateway'),
+      detail: t(
+        'The server received an invalid response. Please check your connection and try again.',
+      ),
+    },
+    503: {
+      title: t('503 - Service Unavailable'),
+      detail: t(
+        'The service is temporarily unavailable. Please try again later.',
+      ),
+    },
+  };
+
+  return status ? messages[status] : undefined;
+};
diff --git a/src/frontend/apps/impress/src/pages/docs/[id]/index.tsx b/src/frontend/apps/impress/src/pages/docs/[id]/index.tsx
index cc5b4ad0..9a81fc3b 100644
--- a/src/frontend/apps/impress/src/pages/docs/[id]/index.tsx
+++ b/src/frontend/apps/impress/src/pages/docs/[id]/index.tsx
@@ -220,6 +220,7 @@ const DocPage = ({ id }: DocProps) => {
       <Box $margin="large">
         <TextErrors
           causes={error.cause}
+          status={error.status}
           icon={
             error.status === 502 ? (
               <Icon iconName="wifi_off" $theme="danger" $withThemeInherited />