From e59b830d747750977d5ac4bf24ce86bb96e90292 Mon Sep 17 00:00:00 2001
From: "Ashley Engelund (weedySeaDragon @ github)" <ashley.engelund@gmail.com>
Date: Thu, 8 Dec 2022 11:25:04 -0800
Subject: [PATCH] set svg role to 'graphics-document document'

---
 packages/mermaid/src/accessibility.spec.ts | 12 ++++++++++--
 packages/mermaid/src/accessibility.ts      | 17 ++++++++++++++++-
 2 files changed, 26 insertions(+), 3 deletions(-)

diff --git a/packages/mermaid/src/accessibility.spec.ts b/packages/mermaid/src/accessibility.spec.ts
index c633d0e15e..60415ea374 100644
--- a/packages/mermaid/src/accessibility.spec.ts
+++ b/packages/mermaid/src/accessibility.spec.ts
@@ -6,6 +6,13 @@ describe('accessibility', () => {
   const fauxSvgNode = new MockedD3();
 
   describe('setA11yDiagramInfo', () => {
+    it('sets the svg element role to "graphics-document document"', () => {
+      // @ts-ignore  Required to easily handle the d3 select types
+      const svgAttrSpy = vi.spyOn(fauxSvgNode, 'attr').mockReturnValue(fauxSvgNode);
+      setA11yDiagramInfo(fauxSvgNode, 'flowchart');
+      expect(svgAttrSpy).toHaveBeenCalledWith('role', 'graphics-document document');
+    });
+
     it('sets the aria-roledescription to the diagram type', () => {
       // @ts-ignore  Required to easily handle the d3 select types
       const svgAttrSpy = vi.spyOn(fauxSvgNode, 'attr').mockReturnValue(fauxSvgNode);
@@ -13,11 +20,12 @@ describe('accessibility', () => {
       expect(svgAttrSpy).toHaveBeenCalledWith('aria-roledescription', 'flowchart');
     });
 
-    it('does nothing if the diagram type is empty', () => {
+    it('does not set the aria-roledescription if the diagram type is empty', () => {
       // @ts-ignore  Required to easily handle the d3 select types
       const svgAttrSpy = vi.spyOn(fauxSvgNode, 'attr').mockReturnValue(fauxSvgNode);
       setA11yDiagramInfo(fauxSvgNode, '');
-      expect(svgAttrSpy).not.toHaveBeenCalled();
+      expect(svgAttrSpy).toHaveBeenCalledTimes(1);
+      expect(svgAttrSpy).toHaveBeenCalledWith('role', expect.anything()); // only called to set the role
     });
   });
 
diff --git a/packages/mermaid/src/accessibility.ts b/packages/mermaid/src/accessibility.ts
index b9e088e0be..13c2aa43ae 100644
--- a/packages/mermaid/src/accessibility.ts
+++ b/packages/mermaid/src/accessibility.ts
@@ -1,5 +1,8 @@
 /**
  * Accessibility (a11y) functions, types, helpers
+ * @see https://www.w3.org/WAI/
+ * @see https://www.w3.org/TR/wai-aria-1.1/
+ * @see https://www.w3.org/TR/svg-aam-1.0/
  *
  */
 import { D3Element } from './mermaidAPI';
@@ -7,12 +10,24 @@ import { D3Element } from './mermaidAPI';
 import isEmpty from 'lodash-es/isEmpty';
 
 /**
- * Add aria-roledescription to the svg element to the diagramType
+ * SVG element role:
+ * The SVG element role _should_ be set to 'graphics-document' per SVG standard
+ * but in practice is not always done by browsers, etc. (As of 2022-12-08).
+ * A fallback role of 'document' should be set for those browsers, etc., that only support ARIA 1.0.
+ *
+ * @see https://www.w3.org/TR/svg-aam-1.0/#roleMappingGeneralRules
+ * @see https://www.w3.org/TR/graphics-aria-1.0/#graphics-document
+ */
+const SVG_ROLE = 'graphics-document document';
+
+/**
+ * Add role and aria-roledescription to the svg element
  *
  * @param svg - d3 object that contains the SVG HTML element
  * @param diagramType - diagram name for to the aria-roledescription
  */
 export function setA11yDiagramInfo(svg: D3Element, diagramType: string | null | undefined) {
+  svg.attr('role', SVG_ROLE);
   if (!isEmpty(diagramType)) {
     svg.attr('aria-roledescription', diagramType);
   }