chore(overlays): add documentation about role=none is used

docs/fundamentals/systems/overlays/overview.md

@@ -111,8 +111,3 @@ class MyOverlayComponent extends OverlayMixin(LitElement) {
 ## Rationales
 
 Please check the [system rationals](./rationale.md) folder, where we go more in-depth.
-
-### Aria roles
-
-- No `aria-controls` as support for it is not quite there yet
-- No `aria-haspopup`. People knowing the haspopup and hear about it don’t expect a dialog to open (at this moment in time) but expect a sub-menu. Until support for the dialog value has better implementation, it’s probably best to not use aria-haspopup on the element that opens the modal dialog.

docs/fundamentals/systems/overlays/rationale.md

@@ -222,11 +222,8 @@ global(modal) dialog.
 
 ## Considerations
 
-### Future for mode local (Popper)
+We use the native dialog purely because it renders to the "top layer". Not because of its accessible role, which varies per component. In the future we can use the popover attribute(<https://open-ui.org/components/popover.research.explainer/>) for this (which neatly differentiates between presentation and semantics).
 
-- Default overflow and/or max-width behavior when content is too wide or high for the viewport.
+So in our use of the dialog we want also a dialog that only does presentation (rendering on top layer in this case), but we want to check the semantics ourselves. Hence: `role="none"`. Even though the outcome is completely accessible, AXE-core uses this rule as a kind of "precautionary measure".
 
-### Aria roles
-
-- No `aria-controls` as support for it is not quite there yet
-- No `aria-haspopup`. People knowing the haspop up and hear about it don’t expect a dialog to open (at this moment in time) but expect a sub-menu. Until support for the dialog value has better implementation, it’s probably best to not use aria-haspopup on the element that opens the modal dialog.
+After a cost/benefit analysis, we choose to be temporarily incompatible with AXE-core. Therefore, we recommend running tests with `{ ignoredRules: ['aria-allowed-role'] }`. When the popover is stable and used underwater in lion overlays, AXE can again be run without this ignoredRule.

packages/ui/components/listbox/test-suites/ListboxMixin.suite.js

@@ -393,7 +393,7 @@ export function runListboxMixinSuite(customConfig = {}) {
         `);
         await el.updateComplete;
         await el.updateComplete; // need 2 awaits as overlay.show is an async function
-
+        // for more info about why we need the ignoreRules, see: https://lion-web.netlify.app/fundamentals/systems/overlays/rationale/#considerations
         await expect(el).to.be.accessible({ ignoredRules: ['aria-allowed-role'] });
       });
 
@@ -405,6 +405,7 @@ export function runListboxMixinSuite(customConfig = {}) {
             <${optionTag} .choiceValue=${20}>Item 2</${optionTag}>
           </${tag}>
         `);
+        // for more info about why we need the ignoreRules, see: https://lion-web.netlify.app/fundamentals/systems/overlays/rationale/#considerations
         await expect(el).to.be.accessible({ ignoredRules: ['aria-allowed-role'] });
       });
 

packages/ui/components/overlays/src/OverlayController.js

@@ -570,6 +570,11 @@ export class OverlayController extends EventTarget {
     // We use a dialog for its visual capabilities: it renders to the top layer.
     // A11y will depend on the type of overlay and is arranged on contentNode level.
     // Also see: https://www.scottohara.me/blog/2019/03/05/open-dialog.html
+    //
+    // The role="dialog" is set on the contentNode (or another role), so role="none"
+    // is valid here, although AXE complains about this setup.
+    // For now we need to add `ignoredRules: ['aria-allowed-role']` in your AXE tests.
+    // see: https://lion-web.netlify.app/fundamentals/systems/overlays/rationale/#considerations
     wrappingDialogElement.setAttribute('role', 'none');
     wrappingDialogElement.setAttribute('data-overlay-outer-wrapper', '');
     // N.B. position: fixed is needed to escape out of 'overflow: hidden'