fix(tooltip): announce content to assistive technology

.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/bottom.html

@@ -1,6 +1,6 @@
 <rh-tooltip position="bottom">
-  <rh-button>Bottom Tooltip</rh-button>
-  <span slot="content">Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut
+  <button aria-describedby="tooltip-content-1">Bottom Tooltip</button>
+  <span id="tooltip-content-1" slot="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.</span>
 </rh-tooltip>
 

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

@@ -1,7 +1,7 @@
 <rh-context-demo>
   <rh-tooltip>
-    <rh-button>Tooltip</rh-button>
-    <span slot="content">Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut
+    <button aria-describedby="tooltip-content-1">Tooltip</button>
+    <span id="tooltip-content-1" slot="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.</span>
   </rh-tooltip>
 </rh-context-demo>

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/left.html

@@ -4,8 +4,8 @@
 
 <p lang="he" dir="rtl" style="text-align: right;">
   <rh-tooltip position="left">
-    <rh-button>עם ישראל חי</rh-button>
-    <span slot="content">
+    <button aria-describedby="tooltip-content-1">עם ישראל חי</button>
+    <span id="tooltip-content-1" slot="content">
   בְּאֶרֶץ-יִשְׂרָאֵל קָם הָעָם הַיְּהוּדִי, בָּהּ עֻצְּבָה דְּמוּתוֹ הָרוּחָנִית, הַדָּתִית וְהַמְּדִינִית, בָּהּ חַי חַיֵּי קוֹמְמִיּוּת מַמְלַכְתִּית, בָּהּ יָצַר נִכְסֵי תַּרְבּוּת לְאֻמִּיִּים וּכְלַל-אֱנוֹשִׁיִּים וְהוֹרִישׁ לָעוֹלָם כֻּלּוֹ אֶת סֵפֶר הַסְּפָרִים הַנִּצְחִי.
   לְאַחַר שֶׁהֻגְלָה הָעָם מֵאַרְצוֹ בְּכֹחַ הַזְּרוֹעַ שָׁמַר לָהּ אֱמוּנִים בְּכָל אַרְצוֹת פְּזוּרָיו, וְלֹא חָדַל מִתְּפִלָּה וּמִתִּקְוָה לָשׁוּב לְאַרְצוֹ וּלְחַדֵּשׁ בְּתוֹכָהּ אֶת חֵרוּתוֹ הַמְּדִינִית. </span>
   </rh-tooltip>

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/demo/right.html

@@ -1,6 +1,6 @@
 <rh-tooltip position="right">
-  <rh-button>Right Tooltip</rh-button>
-  <span slot="content">Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut
+  <button aria-describedby="tooltip-content-1">Right Tooltip</button>
+  <span id="tooltip-content-1" slot="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.</span>
 </rh-tooltip>
 

elements/rh-tooltip/demo/top.html

@@ -1,6 +1,6 @@
 <rh-tooltip position="top">
-  <rh-button>Top Tooltip</rh-button>
-  <span slot="content">Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut
+  <button aria-describedby="tooltip-content-1">Top Tooltip</button>
+  <span id="tooltip-content-1" slot="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.</span>
 </rh-tooltip>
 

elements/rh-tooltip/docs/40-accessibility.md

@@ -1,3 +1,21 @@
+## Markup Guidance
+
+In order to create accessible tooltips, the trigger must have an `aria-describedby` attribute and the tooltip content must have a corresponding [IDREF](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id). See the [demos](/elements/tooltip/demos/) for further implementation details.
+
+### Should implementors use `<rh-tooltip>` with `<rh-button>`?
+
+Implementors may want to use `<rh-tooltip>` with `<rh-button>`. Unfortunately, that results in inaccessible tooltips for the following reasons:
+
+  * In order to be accessible, the `aria-describedby` must exist on a native interactive element (eg: `<button>`, `<input>`, etc) and not a `<rh-*>` element.
+  * While `<rh-button>` contains a `<button>` element, this `<button>` element exists in an encapsulated shadowdom. Any attributes (like `aria-describedby`) added into the shadowdom cannot communicate with IDREFs outside of the shadowdom—and vice versa.
+
+For these reasons, it's recommended to use native HTML elements for `<rh-tooltip>` triggers and content—paired with the appropriate `aria-describedby` and IDREF attributes.
+
+<rh-alert state="neutral">
+  <h3 slot="header">Cross-root ARIA</h3>
+  <p>An upcoming proposal called <a href="https://leobalter.github.io/cross-root-aria-delegation/">Cross-root ARIA</a> will solve this &lt;rh-button&gt; issue.</p>
+</rh-alert>
+
 ## Keyboard interactions
 
 A tooltip will appear when the trigger receives focus and disappear when moving focus away from the trigger.

elements/rh-tooltip/rh-tooltip.css

@@ -77,7 +77,7 @@
       var(--rh-tooltip__content--BackgroundColor, var(--rh-color-surface-darkest, #151515)));
 }
 
-.c {
+.display-c {
   display: contents;
 }
 

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'), {
+      ariaLive: 'polite',
+      // apply `.visually-hidden` styles
+      style: /* css */`
+        position: fixed;
+        top: 0;
+        left: 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 });
       });
     });
   });