fix(tooltip): announce content to assistive technology (#2069)

* feat(tooltip): add ESC to close functionality

* refactor(tooltip): rename CSS class

* fix(tooltip): add `aria-describedby`/`id` pair

* chore(tooltip): add changeset

* fix(tooltip): remove slotchange handler functions

* fix(tooltip): use native `<button>` with `aria-describedby`/ IDREF pair

* docs(tooltip): add a11y markup guidance around `<button>`/`<rh-button>`

* fix(tooltip): attach event listener to `globalThis` for improved performance

* fix(tooltip): announce content

* fix(tooltip): global announcer

* test(tooltip): ax queries

* fix(tooltip): surrender to compilers

* fix(tooltip): crossbrowser aria

* docs(tooltip): remove test icon

* fix(tooltip): revert regression

* perf(tooltip): shave bytes

* fix(tooltip): use logical properties for announcer

* docs(tooltip): remove outdated a11y docs

* fix(tooltip): re-add `<rh-button>` to tooltip demos

* fix(tooltip): prune unused class

* fix(tooltip): change `aria-live` to `role: status`

---------

Co-authored-by: Benny Powers <[email protected]>
Co-authored-by: Benny Powers - עם ישראל חי! <[email protected]>

.changeset/brown-fans-poke.md

@@ -0,0 +1,5 @@
+---
+"@rhds/elements": patch
+---
+
+`<rh-tooltip>`: make tooltip content available to assistive technology

elements/rh-tooltip/demo/content-attributes.html

@@ -0,0 +1,9 @@
+<rh-tooltip content="Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut
+    labore et dolore magna aliqua. Mi eget mauris pharetra et ultrices.">
+  <rh-button>Tooltip</rh-button>
+</rh-tooltip>
+
+<script type="module">
+  import '@rhds/elements/rh-button/rh-button.js';
+  import '@rhds/elements/rh-tooltip/rh-tooltip.js';
+</script>

elements/rh-tooltip/demo/rh-tooltip.html

@@ -8,4 +8,3 @@
   import '@rhds/elements/rh-button/rh-button.js';
   import '@rhds/elements/rh-tooltip/rh-tooltip.js';
 </script>
-

elements/rh-tooltip/rh-tooltip.css

@@ -77,10 +77,6 @@
       var(--rh-tooltip__content--BackgroundColor, var(--rh-color-surface-darkest, #151515)));
 }
 
-.c {
-  display: contents;
-}
-
 .open #tooltip {
   opacity: 1;
 }

elements/rh-tooltip/rh-tooltip.ts

@@ -1,4 +1,4 @@
-import { html, LitElement } from 'lit';
+import { html, LitElement, isServer } from 'lit';
 import { customElement } from 'lit/decorators/custom-element.js';
 import { property } from 'lit/decorators/property.js';
 import { classMap } from 'lit/directives/class-map.js';
@@ -43,6 +43,41 @@ export class RhTooltip extends LitElement {
 
   static readonly styles = [styles];
 
+  private static instances = new Set<RhTooltip>();
+
+  static {
+    if (!isServer) {
+      globalThis.addEventListener('keydown', (event: KeyboardEvent) => {
+        const { instances } = RhTooltip;
+        for (const instance of instances) {
+          instance.#onKeydown(event);
+        }
+      });
+      RhTooltip.initAnnouncer();
+    }
+  }
+
+  private static announcer: HTMLElement;
+
+  private static announce(message: string) {
+    this.announcer.innerText = message;
+  }
+
+  private static initAnnouncer() {
+    document.body.append((this.announcer = Object.assign(document.createElement('div'), {
+      role: 'status',
+      // apply `.visually-hidden` styles
+      style: /* css */`
+        position: fixed;
+        inset-block-start: 0;
+        inset-inline-start: 0;
+        overflow: hidden;
+        clip: rect(0,0,0,0);
+        white-space: nowrap;
+        border: 0;`,
+    })));
+  }
+
   /** The position of the tooltip, relative to the invoking content */
   @property() position: Placement = 'top';
 
@@ -57,10 +92,22 @@ export class RhTooltip extends LitElement {
 
   #initialized = false;
 
+  get #content() {
+    if (!this.#float.open || isServer) {
+      return '';
+    } else {
+      return this.content || (this.shadowRoot
+          ?.getElementById('content') as HTMLSlotElement)
+          ?.assignedNodes().map(x => x.textContent ?? '')
+          ?.join(' ');
+    }
+  }
+
   override connectedCallback(): void {
     super.connectedCallback();
     ENTER_EVENTS.forEach(evt => this.addEventListener(evt, this.show));
     EXIT_EVENTS.forEach(evt => this.addEventListener(evt, this.hide));
+    RhTooltip.instances.add(this);
   }
 
   override render() {
@@ -71,15 +118,15 @@ export class RhTooltip extends LitElement {
       <div id="container"
            style="${styleMap(styles)}"
            class="${classMap({ open,
-                              'initialized': !!this.#initialized,
+                               initialized: !!this.#initialized,
                                [on]: !!on,
                                [anchor]: !!anchor,
                                [alignment]: !!alignment })}">
-        <div class="c" role="tooltip" aria-labelledby="tooltip">
-          <slot id="invoker"></slot>
+        <div id="invoker">
+          <slot id="invoker-slot"></slot>
         </div>
-        <div class="c" aria-hidden="${String(!open) as 'true' | 'false'}">
-          <slot id="tooltip" name="content">${this.content}</slot>
+        <div id="tooltip" role="status">
+          <slot id="content" name="content">${this.content}</slot>
         </div>
       </div>
     `;
@@ -94,12 +141,20 @@ export class RhTooltip extends LitElement {
       : { mainAxis: 15, alignmentAxis: -4 };
     await this.#float.show({ offset, placement });
     this.#initialized ||= true;
+    RhTooltip.announce(this.#content);
   }
 
   /** Hide the tooltip */
   async hide() {
     await this.#float.hide();
+    RhTooltip.announcer.innerText = '';
   }
+
+  #onKeydown = (event: KeyboardEvent): void => {
+    if (event.key === 'Escape') {
+      this.hide();
+    }
+  };
 }
 
 declare global {

elements/rh-tooltip/test/rh-tooltip.spec.ts

@@ -56,10 +56,8 @@ describe('<rh-tooltip>', function() {
       beforeEach(() => sendMouseToTooltip(element));
       it('content should be available to assistive technology', async function() {
         await sendMouseToTooltip(element);
-        const snapshot = await a11ySnapshot();
-        expect(snapshot.children?.length).to.equal(1);
-        expect(snapshot.children?.at(0)?.role).to.equal('text');
-        expect(snapshot.children?.at(0)?.name).to.equal(content);
+        expect(await a11ySnapshot())
+            .to.have.axQuery({ role: 'text', name: content });
       });
     });
   });