fix(a11y): use figure/figcaption for media block captions

Closes #2055. Supersedes #2056.

When a file/image/video/audio block has a caption, render the wrapper
as <figure> with a <figcaption> instead of a <div>+<p>. This matches
the WCAG-recommended semantic for caption-content association and
removes the need for ad-hoc ARIA fallbacks.

Image alt text logic is also tightened:
- caption present -> alt="" (the figcaption is the accessible name;
  this avoids screen readers double-announcing the caption)
- no caption, name present -> alt={name}
- neither -> alt="" (decorative; aria-hidden was dropped because it
  would have removed unintentionally-unlabeled images from the
  accessibility tree entirely)

Co-Authored-By: Cyril G <c.gromoff@gmail.com>
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: 3 people

packages/core/src/blocks/File/helpers/render/createFileBlockWrapper.ts

@@ -26,7 +26,12 @@ export const createFileBlockWrapper = (
   element?: { dom: HTMLElement; destroy?: () => void },
   buttonIcon?: HTMLElement,
 ) => {
-  const wrapper = document.createElement("div");
+  // Use a <figure>/<figcaption> when the block has a caption, so the caption
+  // is semantically associated with its content for assistive tech. Falls back
+  // to a plain <div> when there is no caption (or the file has not been
+  // uploaded yet, since the upload UI never shows the caption).
+  const useFigure = block.props.url !== "" && !!block.props.caption;
+  const wrapper = document.createElement(useFigure ? "figure" : "div");
   wrapper.className = "bn-file-block-content-wrapper";
 
   // Show the add file button if the file has not been uploaded yet. Change to
@@ -73,7 +78,7 @@ export const createFileBlockWrapper = (
 
   // Show the caption if there is one.
   if (block.props.caption) {
-    const caption = document.createElement("p");
+    const caption = document.createElement("figcaption");
     caption.className = "bn-file-caption";
     caption.textContent = block.props.caption;
     wrapper.appendChild(caption);

packages/core/src/blocks/Image/block.ts

@@ -116,7 +116,11 @@ export const imageRender =
       image.src = block.props.url;
     }
 
-    image.alt = block.props.name || block.props.caption || "BlockNote image";
+    // When a caption is set, the wrapper renders a <figcaption> that serves as
+    // the image's accessible name, so an empty alt avoids double-announcement.
+    // Otherwise prefer the file name; fall back to "" (decorative) when neither
+    // is provided.
+    image.alt = block.props.caption ? "" : block.props.name || "";
     image.contentEditable = "false";
     image.draggable = false;
     imageWrapper.appendChild(image);
@@ -153,7 +157,10 @@ export const imageToExternalHTML =
     if (block.props.showPreview) {
       image = document.createElement("img");
       image.src = block.props.url;
-      image.alt = block.props.name || block.props.caption || "BlockNote image";
+      // When a caption is set, createFigureWithCaption wraps the image in a
+      // <figure>/<figcaption> below, which serves as the accessible name.
+      // An empty alt avoids screen readers announcing the caption twice.
+      image.alt = block.props.caption ? "" : block.props.name || "";
       if (block.props.previewWidth) {
         image.width = block.props.previewWidth;
       }

packages/react/src/blocks/File/helpers/render/FileBlockWrapper.tsx

@@ -29,8 +29,14 @@ export const FileBlockWrapper = (
 ) => {
   const showLoader = useUploadLoading(props.block.id);
 
+  // Use a <figure>/<figcaption> when the block has a caption, so the caption
+  // is semantically associated with its content for assistive tech.
+  const useFigure =
+    props.block.props.url !== "" && !!props.block.props.caption && !showLoader;
+  const Wrapper = useFigure ? "figure" : "div";
+
   return (
-    <div
+    <Wrapper
       className={"bn-file-block-content-wrapper"}
       onMouseEnter={props.onMouseEnter}
       onMouseLeave={props.onMouseLeave}
@@ -54,10 +60,12 @@ export const FileBlockWrapper = (
           )}
           {props.block.props.caption && (
             // Show the caption if there is one.
-            <p className={"bn-file-caption"}>{props.block.props.caption}</p>
+            <figcaption className={"bn-file-caption"}>
+              {props.block.props.caption}
+            </figcaption>
           )}
         </>
       )}
-    </div>
+    </Wrapper>
   );
 };

packages/react/src/blocks/Image/block.tsx

@@ -18,6 +18,10 @@ export const ImagePreview = (
 ) => {
   const resolved = useResolveUrl(props.block.props.url!);
 
+  // When a caption is set, FileBlockWrapper renders a <figcaption> that serves
+  // as the image's accessible name; an empty alt avoids double-announcement.
+  const alt = props.block.props.caption ? "" : props.block.props.name || "";
+
   return (
     <img
       className={"bn-visual-media"}
@@ -26,7 +30,7 @@ export const ImagePreview = (
           ? props.block.props.url
           : resolved.downloadUrl
       }
-      alt={props.block.props.caption || "BlockNote image"}
+      alt={alt}
       contentEditable={false}
       draggable={false}
     />
@@ -43,12 +47,13 @@ export const ImageToExternalHTML = (
     return <p>Add image</p>;
   }
 
+  // When a caption is set, the image is wrapped in <figure>/<figcaption>
+  // below; an empty alt avoids double-announcement of the caption text.
+  const alt = props.block.props.caption ? "" : props.block.props.name || "";
   const image = props.block.props.showPreview ? (
     <img
       src={props.block.props.url}
-      alt={
-        props.block.props.name || props.block.props.caption || "BlockNote image"
-      }
+      alt={alt}
       width={props.block.props.previewWidth}
     />
   ) : (

tests/src/unit/core/clipboard/copy/__snapshots__/text/html/basicBlocksWithProps.html

@@ -54,7 +54,7 @@ <h2 data-level="2">Heading 1</h2>
 >
   <img
     src="https://upload.wikimedia.org/wikipedia/commons/thumb/3/3f/Placeholder_view_vector.svg/1280px-Placeholder_view_vector.svg.png"
-    alt="1280px-Placeholder_view_vector.svg.png"
+    alt=""
     width="256"
   />
   <figcaption>Placeholder</figcaption>

tests/src/unit/core/clipboard/copy/__snapshots__/text/html/image.html

@@ -1,5 +1,5 @@
 <img
   src="https://ralfvanveen.com/wp-content/uploads/2021/06/Placeholder-_-Glossary.svg"
-  alt="BlockNote image"
+  alt=""
   data-url="https://ralfvanveen.com/wp-content/uploads/2021/06/Placeholder-_-Glossary.svg"
  />

tests/src/unit/core/clipboard/copy/__snapshots__/text/html/nestedImage.html

@@ -1,7 +1,7 @@
 <p>Paragraph 1</p>
 <img
   src="https://ralfvanveen.com/wp-content/uploads/2021/06/Placeholder-_-Glossary.svg"
-  alt="BlockNote image"
+  alt=""
   data-url="https://ralfvanveen.com/wp-content/uploads/2021/06/Placeholder-_-Glossary.svg"
   data-nesting-level="1"
  />

tests/src/unit/core/formatConversion/export/__snapshots__/blocknoteHTML/file/basic.html

@@ -9,7 +9,7 @@
         data-caption="Caption"
         data-file-block=""
       >
-        <div class="bn-file-block-content-wrapper">
+        <figure class="bn-file-block-content-wrapper">
           <div class="bn-file-name-with-icon">
             <div class="bn-file-icon">
               <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="currentColor">
@@ -20,8 +20,8 @@
             </div>
             <p class="bn-file-name">example</p>
           </div>
-          <p class="bn-file-caption">Caption</p>
-        </div>
+          <figcaption class="bn-file-caption">Caption</figcaption>
+        </figure>
       </div>
     </div>
   </div>

tests/src/unit/core/formatConversion/export/__snapshots__/blocknoteHTML/file/nested.html

@@ -9,7 +9,7 @@
         data-caption="Caption"
         data-file-block=""
       >
-        <div class="bn-file-block-content-wrapper">
+        <figure class="bn-file-block-content-wrapper">
           <div class="bn-file-name-with-icon">
             <div class="bn-file-icon">
               <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="currentColor">
@@ -20,8 +20,8 @@
             </div>
             <p class="bn-file-name">example</p>
           </div>
-          <p class="bn-file-caption">Caption</p>
-        </div>
+          <figcaption class="bn-file-caption">Caption</figcaption>
+        </figure>
       </div>
       <div class="bn-block-group" data-node-type="blockGroup">
         <div class="bn-block-outer" data-node-type="blockOuter" data-id="2">
@@ -34,7 +34,7 @@
               data-caption="Caption"
               data-file-block=""
             >
-              <div class="bn-file-block-content-wrapper">
+              <figure class="bn-file-block-content-wrapper">
                 <div class="bn-file-name-with-icon">
                   <div class="bn-file-icon">
                     <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="currentColor">
@@ -45,8 +45,8 @@
                   </div>
                   <p class="bn-file-name">example</p>
                 </div>
-                <p class="bn-file-caption">Caption</p>
-              </div>
+                <figcaption class="bn-file-caption">Caption</figcaption>
+              </figure>
             </div>
           </div>
         </div>

tests/src/unit/core/formatConversion/export/__snapshots__/blocknoteHTML/file/noName.html

@@ -8,7 +8,7 @@
         data-caption="Caption"
         data-file-block=""
       >
-        <div class="bn-file-block-content-wrapper">
+        <figure class="bn-file-block-content-wrapper">
           <div class="bn-file-name-with-icon">
             <div class="bn-file-icon">
               <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="currentColor">
@@ -19,8 +19,8 @@
             </div>
             <p class="bn-file-name"></p>
           </div>
-          <p class="bn-file-caption">Caption</p>
-        </div>
+          <figcaption class="bn-file-caption">Caption</figcaption>
+        </figure>
       </div>
     </div>
   </div>