✨(frontend) fix rgaa 1.9.1: convert to figure/figcaption structure if caption exists

ensure semantic html structure by using figure/figcaption when captions are present

Signed-off-by: Cyril <[email protected]>

Author: Ovgodd

CHANGELOG.md

@@ -1,4 +1,3 @@
-
 All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0),
@@ -17,6 +16,7 @@ and this project adheres to
   - ♿ add document visible in list and openable via enter key #1365
   - ♿ add pdf outline property to enable bookmarks display #1368
   - ♿ hide decorative icons from assistive tech with aria-hidden #1404
+  - ♿ fix rgaa 1.9.1: convert to figure/figcaption structure #1426
   - ♿ remove redundant aria-label to avoid over-accessibility #1420
 
 ### Fixed
@@ -32,7 +32,6 @@ and this project adheres to
 - ♿(frontend) improve accessibility:
   - ♿improve NVDA navigation in DocShareModal #1396
 
-
 ## [3.7.0] - 2025-09-12
 
 ### Added

src/frontend/apps/impress/src/features/docs/doc-editor/components/custom-blocks/AccessibleImageBlock.tsx

@@ -25,10 +25,64 @@ export const accessibleImageRender = (
   const dom = imageRenderComputed.dom;
   const imgSelector = dom.querySelector('img');
 
-  imgSelector?.setAttribute('alt', '');
-  imgSelector?.setAttribute('role', 'presentation');
-  imgSelector?.setAttribute('aria-hidden', 'true');
-  imgSelector?.setAttribute('tabindex', '-1');
+  // Set accessibility attributes for the image
+  if (block.props.caption) {
+    // If there's a caption, make the image accessible with the caption as alt text
+    imgSelector?.setAttribute('alt', block.props.caption);
+    imgSelector?.removeAttribute('aria-hidden');
+    imgSelector?.setAttribute('tabindex', '0');
+  } else {
+    // If no caption, keep image decorative
+    imgSelector?.setAttribute('alt', '');
+    imgSelector?.setAttribute('role', 'presentation');
+    imgSelector?.setAttribute('aria-hidden', 'true');
+    imgSelector?.setAttribute('tabindex', '-1');
+  }
+
+  // Fix RGAA 1.9.1: Convert to figure/figcaption structure if caption exists
+  if (block.props.caption) {
+    const captionElement = dom.querySelector('.bn-file-caption');
+
+    if (captionElement) {
+      const figureElement = document.createElement('figure');
+
+      // Copy all attributes from the original div
+      figureElement.className = dom.className;
+      const styleAttr = dom.getAttribute('style');
+      if (styleAttr) {
+        figureElement.setAttribute('style', styleAttr);
+      }
+
+      Array.from(dom.children).forEach((child) => {
+        figureElement.appendChild(child.cloneNode(true));
+      });
+
+      // Replace the <p> caption with <figcaption>
+      const figcaptionElement = document.createElement('figcaption');
+      const originalCaption = figureElement.querySelector('.bn-file-caption');
+      if (originalCaption) {
+        figcaptionElement.className = originalCaption.className;
+        figcaptionElement.textContent = originalCaption.textContent;
+        originalCaption.parentNode?.replaceChild(
+          figcaptionElement,
+          originalCaption,
+        );
+
+        // Add explicit role and aria-label for better screen reader support
+        figureElement.setAttribute('role', 'img');
+        figureElement.setAttribute(
+          'aria-label',
+          `Image: ${figcaptionElement.textContent}`,
+        );
+      }
+
+      // Return the figure element as the new dom
+      return {
+        ...imageRenderComputed,
+        dom: figureElement,
+      };
+    }
+  }
 
   return {
     ...imageRenderComputed,