fix(overlays): accessibility attrs setup/teardown

packages/overlays/docs/40-system-configuration.md

@@ -61,6 +61,44 @@ export const placementGlobal = () => html`
 `;
 ```
 
+## isTooltip (placementMode: 'local')
+
+As specified in the [overlay rationale](/?path=/docs/overlays-system-rationale--page) there are only two official types of overlays: dialogs and tooltips. And their main differences are:
+
+- Dialogs have a modal option, tooltips don’t
+- Dialogs have interactive content, tooltips don’t
+- Dialogs are opened via regular buttons (click/space/enter), tooltips act on focus/mouseover
+
+Since most overlays have interactive content the default is set to dialogs. To get a tooltip, you can add `isTooltip` to the config object. This only works for local placement and it also needs to have `handlesAccessibility` activated to work.
+
+```js preview-story
+export const isTooltip = () => {
+  function showTooltip() {
+    const tooltip = document.querySelector('#tooltip');
+    tooltip.opened = true;
+  }
+
+  function hideTooltip() {
+    const tooltip = document.querySelector('#tooltip');
+    tooltip.opened = false;
+  }
+
+  return html`
+    <demo-overlay-system
+      id="tooltip"
+      .config=${{ placementMode: 'local', isTooltip: true, handlesAccessibility: true }}
+    >
+      <button slot="invoker" @mouseenter="${showTooltip}" @mouseleave="${hideTooltip}">
+        Hover me to open the tooltip!
+      </button>
+      <div slot="content" class="demo-overlay">
+        Hello!
+      </div>
+    </demo-overlay-system>
+  `;
+};
+```
+
 ## trapsKeyboardFocus
 
 Boolean property. When true, the focus will rotate through the **focusable elements** inside the `contentNode`.
@@ -295,7 +333,7 @@ export const viewportConfig = () => html`
 
 ## popperConfig for local overlays (placementMode: 'local')
 
-For locally DOM positioned overlays that position themselves relative to their invoker, we use <a href="https://popper.js.org/" target="_blank">Popper.js</a> for positioning.
+For locally DOM positioned overlays that position themselves relative to their invoker, we use [Popper.js](https://popper.js.org/) for positioning.
 
 > In Popper, `contentNode` is often referred to as `popperElement`, and `invokerNode` is often referred to as the `referenceElement`.
 
@@ -306,7 +344,7 @@ Features:
 
 > Popper strictly is scoped on positioning. **It does not change the dimensions of the content node nor the invoker node**.
 > This also means that if you use the arrow feature, you are in charge of styling it properly, use the x-placement attribute for this.
-> An example implementation can be found in [lion-tooltip](?path=/docs/overlays-tooltip), where an arrow is set by default.
+> An example implementation can be found in [lion-tooltip](?path=/docs/overlays-tooltip--main#tooltip), where an arrow is set by default.
 
 To override the default options we set for local mode, you add a `popperConfig` object to the config passed to the OverlayController.
 Here's a succinct overview of some often used popper properties:

packages/overlays/src/OverlayController.js

@@ -100,6 +100,7 @@ export class OverlayController {
       hidesOnOutsideEsc: false,
       hidesOnOutsideClick: false,
       isTooltip: false,
+      invokerRelation: 'description',
       handlesUserInteraction: false,
       handlesAccessibility: false,
       popperConfig: {
@@ -134,7 +135,7 @@ export class OverlayController {
 
     this.manager.add(this);
     this._contentId = `overlay-content--${Math.random().toString(36).substr(2, 10)}`;
-
+    this.__originalAttrs = new Map();
     if (this._defaultConfig.contentNode) {
       if (!this._defaultConfig.contentNode.isConnected) {
         throw new Error(
@@ -236,18 +237,32 @@ export class OverlayController {
   // eslint-disable-next-line class-methods-use-this
   __validateConfiguration(newConfig) {
     if (!newConfig.placementMode) {
-      throw new Error('You need to provide a .placementMode ("global"|"local")');
+      throw new Error(
+        '[OverlayController] You need to provide a .placementMode ("global"|"local")',
+      );
     }
     if (!['global', 'local'].includes(newConfig.placementMode)) {
       throw new Error(
-        `"${newConfig.placementMode}" is not a valid .placementMode, use ("global"|"local")`,
+        `[OverlayController] "${newConfig.placementMode}" is not a valid .placementMode, use ("global"|"local")`,
       );
     }
     if (!newConfig.contentNode) {
-      throw new Error('You need to provide a .contentNode');
+      throw new Error('[OverlayController] You need to provide a .contentNode');
     }
     if (this.__isContentNodeProjected && !newConfig.contentWrapperNode) {
-      throw new Error('You need to provide a .contentWrapperNode when .contentNode is projected');
+      throw new Error(
+        '[OverlayController] You need to provide a .contentWrapperNode when .contentNode is projected',
+      );
+    }
+    if (newConfig.isTooltip && newConfig.placementMode !== 'local') {
+      throw new Error(
+        '[OverlayController] .isTooltip should be configured with .placementMode "local"',
+      );
+    }
+    if (newConfig.isTooltip && !newConfig.handlesAccessibility) {
+      throw new Error(
+        '[OverlayController] .isTooltip only takes effect when .handlesAccessibility is enabled',
+      );
     }
     // if (newConfig.popperConfig.modifiers.arrow && !newConfig.contentWrapperNode) {
     //   throw new Error('You need to provide a .contentWrapperNode when Popper arrow is enabled');
@@ -257,9 +272,6 @@ export class OverlayController {
   async _init({ cfgToAdd }) {
     this.__initcontentWrapperNode({ cfgToAdd });
     this.__initConnectionTarget();
-    if (this.handlesAccessibility) {
-      this.__initAccessibility({ cfgToAdd });
-    }
 
     if (this.placementMode === 'local') {
       // Lazily load Popper if not done yet
@@ -339,27 +351,58 @@ export class OverlayController {
     }
   }
 
-  __initAccessibility() {
+  __setupTeardownAccessibility({ phase }) {
-    // TODO: remove a11y attributes on teardown
+    if (phase === 'init') {
-    if (!this.contentNode.id) {
+      this.__storeOriginalAttrs(this.contentNode, ['role', 'id']);
-      this.contentNode.setAttribute('id', this._contentId);
+      this.__storeOriginalAttrs(this.invokerNode, [
+        'aria-expanded',
+        'aria-labelledby',
+        'aria-describedby',
+      ]);
+
+      if (!this.contentNode.id) {
+        this.contentNode.setAttribute('id', this._contentId);
+      }
+      if (this.isTooltip) {
+        if (this.invokerNode) {
+          this.invokerNode.setAttribute(
+            this.invokerRelation === 'label' ? 'aria-labelledby' : 'aria-describedby',
+            this._contentId,
+          );
+        }
+        this.contentNode.setAttribute('role', 'tooltip');
+      } else {
+        if (this.invokerNode) {
+          this.invokerNode.setAttribute('aria-expanded', this.isShown);
+        }
+        if (!this.contentNode.role) {
+          this.contentNode.setAttribute('role', 'dialog');
+        }
+      }
+    } else if (phase === 'teardown') {
+      this.__restorOriginalAttrs();
     }
-    if (this.isTooltip) {
+  }
-      if (this.invokerNode) {
+
-        this.invokerNode.setAttribute(
+  __storeOriginalAttrs(node, attrs) {
-          this.invokerRelation === 'label' ? 'aria-labelledby' : 'aria-describedby',
+    const attrMap = {};
-          this._contentId,
+    attrs.forEach(attrName => {
-        );
+      attrMap[attrName] = node.getAttribute(attrName);
-      }
+    });
-      this.contentNode.setAttribute('role', 'tooltip');
+    this.__originalAttrs.set(node, attrMap);
-    } else {
+  }
-      if (this.invokerNode) {
+
-        this.invokerNode.setAttribute('aria-expanded', this.isShown);
+  __restorOriginalAttrs() {
-      }
+    for (const [node, attrMap] of this.__originalAttrs) {
-      if (!this.contentNode.role) {
+      Object.entries(attrMap).forEach(([attrName, value]) => {
-        this.contentNode.setAttribute('role', 'dialog');
+        if (value !== null) {
-      }
+          node.setAttribute(attrName, value);
+        } else {
+          node.removeAttribute(attrName);
+        }
+      });
     }
+    this.__originalAttrs.clear();
   }
 
   get isShown() {
@@ -772,6 +815,9 @@ export class OverlayController {
   }
 
   _handleAccessibility({ phase }) {
+    if (phase === 'init' || phase === 'teardown') {
+      this.__setupTeardownAccessibility({ phase });
+    }
     if (this.invokerNode && !this.isTooltip) {
       this.invokerNode.setAttribute('aria-expanded', phase === 'show');
     }

packages/overlays/src/utils/typedef.js

@@ -35,6 +35,7 @@
  * @property {boolean} [isTooltip=false] has a totally different interaction- and accessibility
  * pattern from all other overlays. Will behave as role="tooltip" element instead of a role="dialog"
  * element.
+ * @property {'label'|'description'} [invokerRelation='description']
  * @property {boolean} [handlesAccessibility]
  *  For non `isTooltip`:
  *    - sets aria-expanded="true/false" and aria-haspopup="true" on invokerNode

packages/overlays/test/OverlayController.test.js

@@ -18,12 +18,12 @@ import { simulateTab } from '../src/utils/simulate-tab.js';
 
 const withGlobalTestConfig = () => ({
   placementMode: 'global',
-  contentNode: fixtureSync(html` <div>my content</div> `),
+  contentNode: fixtureSync(html`<div>my content</div>`),
 });
 
 const withLocalTestConfig = () => ({
   placementMode: 'local',
-  contentNode: fixtureSync(html` <div>my content</div> `),
+  contentNode: fixtureSync(html`<div>my content</div>`),
   invokerNode: fixtureSync(html`
     <div role="button" style="width: 100px; height: 20px;">Invoker</div>
   `),
@@ -134,7 +134,7 @@ describe('OverlayController', () => {
       it.skip('creates local target next to sibling for placement mode "local"', async () => {
         const ctrl = new OverlayController({
           ...withLocalTestConfig(),
-          invokerNode: await fixture(html` <button>Invoker</button> `),
+          invokerNode: await fixture(html`<button>Invoker</button>`),
         });
         expect(ctrl._renderTarget).to.be.undefined;
         expect(ctrl.content).to.equal(ctrl.invokerNode.nextElementSibling);
@@ -293,7 +293,7 @@ describe('OverlayController', () => {
         });
         await ctrl.show();
 
-        const elOutside = await fixture(html` <button>click me</button> `);
+        const elOutside = await fixture(html`<button>click me</button>`);
         const input1 = ctrl.contentNode.querySelectorAll('input')[0];
         const input2 = ctrl.contentNode.querySelectorAll('input')[1];
 
@@ -308,7 +308,7 @@ describe('OverlayController', () => {
       });
 
       it('allows to move the focus outside of the overlay if trapsKeyboardFocus is disabled', async () => {
-        const contentNode = await fixture(html` <div><input /></div> `);
+        const contentNode = await fixture(html`<div><input /></div>`);
 
         const ctrl = new OverlayController({
           ...withGlobalTestConfig(),
@@ -316,10 +316,10 @@ describe('OverlayController', () => {
           trapsKeyboardFocus: true,
         });
         // add element to dom to allow focus
-        await fixture(html` ${ctrl.content} `);
+        await fixture(html`${ctrl.content}`);
         await ctrl.show();
 
-        const elOutside = await fixture(html` <input /> `);
+        const elOutside = await fixture(html`<input />`);
         const input = ctrl.contentNode.querySelector('input');
 
         input.focus();
@@ -524,7 +524,7 @@ describe('OverlayController', () => {
       });
 
       it('works with 3rd party code using "event.stopPropagation()" on capture phase', async () => {
-        const invokerNode = await fixture(html` <div role="button">Invoker</div> `);
+        const invokerNode = await fixture(html`<div role="button">Invoker</div>`);
         const contentNode = await fixture('<div>Content</div>');
         const ctrl = new OverlayController({
           ...withLocalTestConfig(),
@@ -1011,7 +1011,7 @@ describe('OverlayController', () => {
     it('reinitializes content', async () => {
       const ctrl = new OverlayController({
         ...withLocalTestConfig(),
-        contentNode: await fixture(html` <div>content1</div> `),
+        contentNode: await fixture(html`<div>content1</div>`),
       });
       await ctrl.show(); // Popper adds inline styles
       expect(ctrl.content.style.transform).not.to.be.undefined;
@@ -1019,13 +1019,13 @@ describe('OverlayController', () => {
 
       ctrl.updateConfig({
         placementMode: 'local',
-        contentNode: await fixture(html` <div>content2</div> `),
+        contentNode: await fixture(html`<div>content2</div>`),
       });
       expect(ctrl.contentNode.textContent).to.include('content2');
     });
 
     it('respects the initial config provided to new OverlayController(initialConfig)', async () => {
-      const contentNode = fixtureSync(html` <div>my content</div> `);
+      const contentNode = fixtureSync(html`<div>my content</div>`);
 
       const ctrl = new OverlayController({
         // This is the shared config
@@ -1045,7 +1045,7 @@ describe('OverlayController', () => {
 
     // Currently not working, enable again when we fix updateConfig
     it.skip('allows for updating viewport config placement only, while keeping the content shown', async () => {
-      const contentNode = fixtureSync(html` <div>my content</div> `);
+      const contentNode = fixtureSync(html`<div>my content</div>`);
 
       const ctrl = new OverlayController({
         // This is the shared config
@@ -1071,7 +1071,7 @@ describe('OverlayController', () => {
   });
 
   describe('Accessibility', () => {
-    it('adds and removes [aria-expanded] on invoker', async () => {
+    it('synchronizes [aria-expanded] on invoker', async () => {
       const invokerNode = await fixture('<div role="button">invoker</div>');
       const ctrl = new OverlayController({
         ...withLocalTestConfig(),
@@ -1232,6 +1232,66 @@ describe('OverlayController', () => {
         });
         expect(ctrl.contentNode.getAttribute('role')).to.equal('tooltip');
       });
+
+      describe('Teardown', () => {
+        it('restores [role] on dialog content', async () => {
+          const invokerNode = await fixture('<div role="button">invoker</div>');
+          const ctrl = new OverlayController({
+            ...withLocalTestConfig(),
+            handlesAccessibility: true,
+            invokerNode,
+          });
+          expect(ctrl.contentNode.getAttribute('role')).to.equal('dialog');
+          ctrl.teardown();
+          expect(ctrl.contentNode.getAttribute('role')).to.equal(null);
+        });
+
+        it('restores [role] on tooltip content', async () => {
+          const invokerNode = await fixture('<div role="button">invoker</div>');
+          const contentNode = await fixture('<div role="presentation">content</div>');
+          const ctrl = new OverlayController({
+            ...withLocalTestConfig(),
+            handlesAccessibility: true,
+            isTooltip: true,
+            invokerNode,
+            contentNode,
+          });
+          expect(contentNode.getAttribute('role')).to.equal('tooltip');
+          ctrl.teardown();
+          expect(contentNode.getAttribute('role')).to.equal('presentation');
+        });
+
+        it('restores [aria-describedby] on content', async () => {
+          const invokerNode = await fixture('<div role="button">invoker</div>');
+          const contentNode = await fixture('<div role="presentation">content</div>');
+          const ctrl = new OverlayController({
+            ...withLocalTestConfig(),
+            handlesAccessibility: true,
+            isTooltip: true,
+            invokerNode,
+            contentNode,
+          });
+          expect(invokerNode.getAttribute('aria-describedby')).to.equal(contentNode.id);
+          ctrl.teardown();
+          expect(invokerNode.getAttribute('aria-describedby')).to.equal(null);
+        });
+
+        it('restores [aria-labelledby] on content', async () => {
+          const invokerNode = await fixture('<div role="button">invoker</div>');
+          const contentNode = await fixture('<div role="presentation">content</div>');
+          const ctrl = new OverlayController({
+            ...withLocalTestConfig(),
+            handlesAccessibility: true,
+            isTooltip: true,
+            invokerNode,
+            contentNode,
+            invokerRelation: 'label',
+          });
+          expect(invokerNode.getAttribute('aria-labelledby')).to.equal(contentNode.id);
+          ctrl.teardown();
+          expect(invokerNode.getAttribute('aria-labelledby')).to.equal(null);
+        });
+      });
     });
   });
 
@@ -1244,7 +1304,7 @@ describe('OverlayController', () => {
         new OverlayController({
           contentNode,
         });
-      }).to.throw('You need to provide a .placementMode ("global"|"local")');
+      }).to.throw('[OverlayController] You need to provide a .placementMode ("global"|"local")');
     });
 
     it('throws if invalid .placementMode gets passed on', async () => {
@@ -1252,7 +1312,9 @@ describe('OverlayController', () => {
         new OverlayController({
           placementMode: 'invalid',
         });
-      }).to.throw('"invalid" is not a valid .placementMode, use ("global"|"local")');
+      }).to.throw(
+        '[OverlayController] "invalid" is not a valid .placementMode, use ("global"|"local")',
+      );
     });
 
     it('throws if no .contentNode gets passed on', async () => {
@@ -1260,7 +1322,7 @@ describe('OverlayController', () => {
         new OverlayController({
           placementMode: 'global',
         });
-      }).to.throw('You need to provide a .contentNode');
+      }).to.throw('[OverlayController] You need to provide a .contentNode');
     });
 
     it('throws if contentNodewrapper is not provided for projected contentNode', async () => {
@@ -1284,7 +1346,39 @@ describe('OverlayController', () => {
           ...withLocalTestConfig(),
           contentNode,
         });
-      }).to.throw('You need to provide a .contentWrapperNode when .contentNode is projected');
+      }).to.throw(
+        '[OverlayController] You need to provide a .contentWrapperNode when .contentNode is projected',
+      );
+    });
+
+    it('throws if placementMode is global for a tooltip', async () => {
+      const contentNode = document.createElement('div');
+      document.body.appendChild(contentNode);
+      expect(() => {
+        new OverlayController({
+          placementMode: 'global',
+          contentNode,
+          isTooltip: true,
+          handlesAccessibility: true,
+        });
+      }).to.throw(
+        '[OverlayController] .isTooltip should be configured with .placementMode "local"',
+      );
+    });
+
+    it('throws if handlesAccessibility is false for a tooltip', async () => {
+      const contentNode = document.createElement('div');
+      document.body.appendChild(contentNode);
+      expect(() => {
+        new OverlayController({
+          placementMode: 'local',
+          contentNode,
+          isTooltip: true,
+          handlesAccessibility: false,
+        });
+      }).to.throw(
+        '[OverlayController] .isTooltip only takes effect when .handlesAccessibility is enabled',
+      );
     });
   });
 });

packages/tooltip/src/LionTooltip.js

@@ -128,6 +128,8 @@ export class LionTooltip extends OverlayMixin(LitElement) {
           this.__syncFromPopperState(data);
         },
       },
+      isTooltip: true,
+      handlesAccessibility: true,
     };
   }