Add aria-labels to PDF link annotations for accessibility

packages/react-pdf/src/LinkService.ts

@@ -17,6 +17,7 @@ import invariant from 'tiny-invariant';
 import type { PDFDocumentProxy } from 'pdfjs-dist';
 import type { IPDFLinkService } from 'pdfjs-dist/types/web/interfaces.js';
 import type {
+  Annotations,
   Dest,
   ExternalLinkRel,
   ExternalLinkTarget,
@@ -32,6 +33,7 @@ type PDFViewer = {
 };
 
 export default class LinkService implements IPDFLinkService {
+  annotationContext?: Map<string, Annotations[number]>;
   externalLinkEnabled: boolean;
   externalLinkRel?: ExternalLinkRel;
   externalLinkTarget?: ExternalLinkTarget;
@@ -46,6 +48,7 @@ export default class LinkService implements IPDFLinkService {
     this.isInPresentationMode = false;
     this.pdfDocument = undefined;
     this.pdfViewer = undefined;
+    this.annotationContext = undefined;
   }
 
   setDocument(pdfDocument: PDFDocumentProxy): void {
@@ -64,6 +67,18 @@ export default class LinkService implements IPDFLinkService {
     this.externalLinkTarget = externalLinkTarget;
   }
 
+  setAnnotationContext(annotations: Annotations): void {
+    this.annotationContext = new Map(
+      annotations
+        .filter((annotation) => 'id' in annotation)
+        .map((annotation) => [String(annotation.id), annotation]),
+    );
+  }
+
+  clearAnnotationContext(): void {
+    this.annotationContext = undefined;
+  }
+
   setHash(): void {
     // Intentionally empty
   }
@@ -100,6 +115,15 @@ export default class LinkService implements IPDFLinkService {
     link.href = url;
     link.rel = this.externalLinkRel || DEFAULT_LINK_REL;
     link.target = newWindow ? '_blank' : this.externalLinkTarget || '';
+
+    const elementId = link.getAttribute('data-element-id');
+    const overlaidText = elementId && this.annotationContext?.get(elementId)?.overlaidText;
+
+    const trimmedText = typeof overlaidText === 'string' ? overlaidText.trim() : '';
+
+    if (trimmedText) {
+      link.setAttribute('aria-label', trimmedText);
+    }
   }
 
   goToDestination(dest: Dest): Promise<void> {

packages/react-pdf/src/Page/AnnotationLayer.spec.tsx

@@ -288,6 +288,50 @@ describe('AnnotationLayer', () => {
       },
     );
 
+    it('renders all links with proper ARIA labels', async () => {
+      const {
+        func: onRenderAnnotationLayerSuccess,
+        promise: onRenderAnnotationLayerSuccessPromise,
+      } = makeAsyncCallback();
+
+      const { container } = await renderWithContext(
+        <AnnotationLayer />,
+        {
+          linkService,
+          pdf,
+        },
+        {
+          onRenderAnnotationLayerSuccess,
+          page,
+        },
+      );
+
+      expect.assertions(desiredAnnotations.length);
+
+      await onRenderAnnotationLayerSuccessPromise;
+
+      const wrapper = container.firstElementChild as HTMLDivElement;
+      const annotationItems = Array.from(wrapper.children);
+      const annotationLinkItems = annotationItems
+        .map((item) => item.firstChild as HTMLElement)
+        .filter((item) => item.tagName === 'A');
+
+      for (const link of annotationLinkItems) {
+        const matchingAnnotation = desiredAnnotations.find(
+          (annotation) => annotation.url === link.getAttribute('href'),
+        );
+
+        if (!matchingAnnotation) {
+          throw new Error('Matching annotation not found');
+        }
+
+        expect(link).toHaveAttribute(
+          'aria-label',
+          matchingAnnotation.overlaidText ? String(matchingAnnotation.overlaidText).trim() : '',
+        );
+      }
+    });
+
     it('renders annotations with the default imageResourcesPath given no imageResourcesPath', async () => {
       const pdf = await pdfjs.getDocument({ data: annotatedPdfFile.arrayBuffer }).promise;
       const annotatedPage = await pdf.getPage(1);

packages/react-pdf/src/Page/AnnotationLayer.tsx

@@ -175,8 +175,12 @@ export default function AnnotationLayer(): React.ReactElement {
         viewport: clonedViewport,
       };
 
+      const filteredAnnotations = filterAnnotations
+        ? filterAnnotations({ annotations })
+        : annotations;
+
       const renderParameters: AnnotationLayerParameters = {
-        annotations: filterAnnotations ? filterAnnotations({ annotations }) : annotations,
+        annotations: filteredAnnotations,
         annotationStorage: pdf.annotationStorage,
         div: layer,
         imageResourcesPath,
@@ -188,13 +192,17 @@ export default function AnnotationLayer(): React.ReactElement {
 
       layer.innerHTML = '';
 
+      linkService.setAnnotationContext(filteredAnnotations);
+
       try {
         new pdfjs.AnnotationLayer(annotationLayerParameters).render(renderParameters);
 
         // Intentional immediate callback
         onRenderSuccess();
       } catch (error) {
         onRenderError(error);
+      } finally {
+        linkService.clearAnnotationContext();
       }
 
       return () => {