♿️(frontend) make html export accessible to screen reader users

adjusted structure and semantics to ensure proper sr interpretation

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

Author: Ovgodd

CHANGELOG.md

@@ -16,6 +16,11 @@ and this project adheres to
 
 - ✅(backend) reduce flakiness on backend test #1769
 
+### Changed
+
+- ♿(frontend) improve accessibility:
+  - ♿(frontend) make html export accessible to screen reader users #1743
+
 ## [4.3.0] - 2026-01-05
 
 ### Added
@@ -60,7 +65,6 @@ and this project adheres to
 - 🐛(frontend) Select text + Go back one page crash the app #1733
 - 🐛(frontend) fix versioning conflict #1742
 
-
 ## [4.1.0] - 2025-12-09
 
 ### Added

src/frontend/apps/impress/src/features/docs/doc-export/__tests__/utilsMediaFilename.test.ts

@@ -1,4 +1,4 @@
-import { deriveMediaFilename } from '../utils';
+import { deriveMediaFilename } from '../utils_html';
 
 describe('deriveMediaFilename', () => {
   test('uses last URL segment when src is a valid URL', () => {

src/frontend/apps/impress/src/features/docs/doc-export/assets/export-html-styles.txt

@@ -184,6 +184,75 @@ s {
   margin: 0;
 }
 
+/* Remove bullet points from checkbox lists */
+ul.checklist,
+ul:has(li input[type='checkbox']) {
+  list-style: none;
+  padding-left: 0;
+  margin-left: 0;
+}
+
+ul.checklist li,
+ul:has(li input[type='checkbox']) li {
+  list-style: none;
+  display: flex;
+  align-items: center;
+  gap: 8px;
+}
+
+ul.checklist li input[type='checkbox'],
+ul:has(li input[type='checkbox']) li input[type='checkbox'] {
+  margin: 0;
+  width: 16px;
+  height: 16px;
+  cursor: pointer;
+  flex-shrink: 0;
+}
+
+ul.checklist li p,
+ul:has(li input[type='checkbox']) li p {
+  margin: 0;
+  flex: 1;
+}
+
+/* Native HTML Lists - remove default margins */
+ol,
+ul {
+  margin: 0;
+  padding-left: 24px;
+}
+
+ol {
+  list-style-type: decimal;
+}
+
+ul {
+  list-style-type: disc;
+}
+
+/* Nested lists */
+ul ul {
+  list-style-type: circle;
+}
+
+/* Keep decimal numbering for nested ol (remove this if you want letters) */
+ol ol {
+  list-style-type: decimal;
+}
+
+li {
+  margin: 0;
+  padding: 0;
+  line-height: 24px;
+}
+
+li p {
+  margin: 0;
+  display: inline;
+}
+
+
+
 /* Quotes */
 blockquote,
 .bn-block-content[data-content-type='quote'] blockquote {

src/frontend/apps/impress/src/features/docs/doc-export/components/ModalExport.tsx

@@ -29,11 +29,12 @@ import { TemplatesOrdering, useTemplates } from '../api/useTemplates';
 import { docxDocsSchemaMappings } from '../mappingDocx';
 import { odtDocsSchemaMappings } from '../mappingODT';
 import { pdfDocsSchemaMappings } from '../mappingPDF';
+import { downloadFile } from '../utils';
 import {
   addMediaFilesToZip,
-  downloadFile,
   generateHtmlDocument,
-} from '../utils';
+  improveHtmlAccessibility,
+} from '../utils_html';
 
 enum DocDownloadFormat {
   HTML = 'html',
@@ -161,10 +162,12 @@ export const ModalExport = ({ onClose, doc }: ModalExportProps) => {
 
       const zip = new JSZip();
 
+      improveHtmlAccessibility(parsedDocument, documentTitle);
       await addMediaFilesToZip(parsedDocument, zip, mediaUrl);
 
       const lang = i18next.language || fallbackLng;
-      const editorHtmlWithLocalMedia = parsedDocument.body.innerHTML;
+      const body = parsedDocument.body;
+      const editorHtmlWithLocalMedia = body ? body.innerHTML : '';
 
       const htmlContent = generateHtmlDocument(
         documentTitle,

src/frontend/apps/impress/src/features/docs/doc-export/index.ts

@@ -5,6 +5,7 @@
  */
 export * from './api';
 export * from './utils';
+export * from './utils_html';
 
 import * as ModalExport from './components/ModalExport';
 

src/frontend/apps/impress/src/features/docs/doc-export/utils.ts

@@ -5,11 +5,8 @@ import {
 } from '@blocknote/core';
 import { Canvg } from 'canvg';
 import { IParagraphOptions, ShadingType } from 'docx';
-import JSZip from 'jszip';
 import React from 'react';
 
-import { exportResolveFileUrl } from './api';
-
 export function downloadFile(blob: Blob, filename: string) {
   const url = window.URL.createObjectURL(blob);
   const a = document.createElement('a');
@@ -192,172 +189,3 @@ export function odtRegisterParagraphStyleForBlock(
 
   return styleName;
 }
-
-// Escape user-provided text  before injecting it into the exported HTML document.
-export const escapeHtml = (value: string): string =>
-  value
-    .replace(/&/g, '&')
-    .replace(/</g, '&lt;')
-    .replace(/>/g, '&gt;')
-    .replace(/"/g, '&quot;')
-    .replace(/'/g, '&#39;');
-
-interface MediaFilenameParams {
-  src: string;
-  index: number;
-  blob: Blob;
-}
-
-/**
- * Derives a stable, readable filename for media exported in the HTML ZIP.
- *
- * Rules:
- * - Default base name is "media-{index+1}".
- * - For non data: URLs, we reuse the last path segment when possible (e.g. 1-photo.png).
- * - If the base name has no extension, we try to infer one from the blob MIME type.
- */
-export const deriveMediaFilename = ({
-  src,
-  index,
-  blob,
-}: MediaFilenameParams): string => {
-  // Default base name
-  let baseName = `media-${index + 1}`;
-
-  // Try to reuse the last path segment for non data URLs.
-  if (!src.startsWith('data:')) {
-    try {
-      const url = new URL(src, window.location.origin);
-      const lastSegment = url.pathname.split('/').pop();
-      if (lastSegment) {
-        baseName = `${index + 1}-${lastSegment}`;
-      }
-    } catch {
-      // Ignore invalid URLs, keep default baseName.
-    }
-  }
-
-  let filename = baseName;
-
-  // Ensure the filename has an extension consistent with the blob MIME type.
-  const mimeType = blob.type;
-  if (mimeType && !baseName.includes('.')) {
-    const slashIndex = mimeType.indexOf('/');
-    const rawSubtype =
-      slashIndex !== -1 && slashIndex < mimeType.length - 1
-        ? mimeType.slice(slashIndex + 1)
-        : '';
-
-    let extension = '';
-    const subtype = rawSubtype.toLowerCase();
-
-    if (subtype.includes('svg')) {
-      extension = 'svg';
-    } else if (subtype.includes('jpeg') || subtype.includes('pjpeg')) {
-      extension = 'jpg';
-    } else if (subtype.includes('png')) {
-      extension = 'png';
-    } else if (subtype.includes('gif')) {
-      extension = 'gif';
-    } else if (subtype.includes('webp')) {
-      extension = 'webp';
-    } else if (subtype.includes('pdf')) {
-      extension = 'pdf';
-    } else if (subtype) {
-      extension = subtype.split('+')[0];
-    }
-
-    if (extension) {
-      filename = `${baseName}.${extension}`;
-    }
-  }
-
-  return filename;
-};
-
-/**
- * Generates a complete HTML document structure for export.
- *
- * @param documentTitle - The title of the document (will be escaped)
- * @param editorHtmlWithLocalMedia - The HTML content from the editor
- * @param lang - The language code for the document (e.g., 'fr', 'en')
- * @returns A complete HTML5 document string
- */
-export const generateHtmlDocument = (
-  documentTitle: string,
-  editorHtmlWithLocalMedia: string,
-  lang: string,
-): string => {
-  return `<!DOCTYPE html>
-<html lang="${lang}">
-  <head>
-    <meta charset="utf-8" />
-    <title>${escapeHtml(documentTitle)}</title>
-    <link rel="stylesheet" href="styles.css">
-  </head>
-  <body>
-    <main role="main">
-${editorHtmlWithLocalMedia}
-    </main>
-  </body>
-</html>`;
-};
-
-export const addMediaFilesToZip = async (
-  parsedDocument: Document,
-  zip: JSZip,
-  mediaUrl: string,
-) => {
-  const mediaFiles: { filename: string; blob: Blob }[] = [];
-  const mediaElements = Array.from(
-    parsedDocument.querySelectorAll<
-      HTMLImageElement | HTMLVideoElement | HTMLAudioElement | HTMLSourceElement
-    >('img, video, audio, source'),
-  );
-
-  await Promise.all(
-    mediaElements.map(async (element, index) => {
-      const src = element.getAttribute('src');
-
-      if (!src) {
-        return;
-      }
-
-      // data: URLs are already embedded and work offline; no need to create separate files.
-      if (src.startsWith('data:')) {
-        return;
-      }
-
-      // Only download same-origin resources (internal media like /media/...).
-      // External URLs keep their original src and are not included in the ZIP
-      let url: URL | null = null;
-      try {
-        url = new URL(src, mediaUrl);
-      } catch {
-        url = null;
-      }
-
-      if (!url || url.origin !== mediaUrl) {
-        return;
-      }
-
-      const fetched = await exportResolveFileUrl(url.href);
-
-      if (!(fetched instanceof Blob)) {
-        return;
-      }
-
-      const filename = deriveMediaFilename({
-        src: url.href,
-        index,
-        blob: fetched,
-      });
-      element.setAttribute('src', filename);
-      mediaFiles.push({ filename, blob: fetched });
-    }),
-  );
-
-  mediaFiles.forEach(({ filename, blob }) => {
-    zip.file(filename, blob);
-  });
-};