feat: add ariaTarget property for setting aria-describedby

packages/component-base/src/tooltip-controller.d.ts

@@ -23,6 +23,13 @@ type TooltipPosition =
  * A controller that manages the slotted tooltip element.
  */
 export class TooltipController extends SlotController {
+  /**
+   * An HTML element for linking with the tooltip overlay
+   * via `aria-describedby` attribute used by screen readers.
+   * When not set, defaults to `target`.
+   */
+  ariaTarget: HTMLElement;
+
   /**
    * Object with properties passed to `generator`
    * function to be used for generating tooltip text.
@@ -51,6 +58,12 @@ export class TooltipController extends SlotController {
    */
   target: HTMLElement;
 
+  /**
+   * Set an HTML element for linking with the tooltip overlay
+   * via `aria-describedby` attribute used by screen readers.
+   */
+  setAriaTarget(ariaTarget: HTMLElement): void;
+
   /**
    * Set a context object to be used by generator.
    */

packages/component-base/src/tooltip-controller.js

@@ -26,6 +26,10 @@ export class TooltipController extends SlotController {
   initCustomNode(tooltipNode) {
     tooltipNode.target = this.target;
 
+    if (this.ariaTarget !== undefined) {
+      tooltipNode.ariaTarget = this.ariaTarget;
+    }
+
     if (this.context !== undefined) {
       tooltipNode.context = this.context;
     }
@@ -47,6 +51,20 @@ export class TooltipController extends SlotController {
     }
   }
 
+  /**
+   * Set an HTML element for linking with the tooltip overlay
+   * via `aria-describedby` attribute used by screen readers.
+   * @param {HTMLElement} ariaTarget
+   */
+  setAriaTarget(ariaTarget) {
+    this.ariaTarget = ariaTarget;
+
+    const tooltipNode = this.node;
+    if (tooltipNode) {
+      tooltipNode.ariaTarget = ariaTarget;
+    }
+  }
+
   /**
    * Set a context object to be used by generator.
    * @param {object} context

packages/component-base/test/tooltip-controller.test.js

@@ -79,6 +79,13 @@ describe('TooltipController', () => {
       controller.setPosition('top-start');
       expect(tooltip.position).to.not.eql('top-start');
     });
+
+    it('should update tooltip ariaTarget using controller setAriaTarget method', () => {
+      const input = document.createElement('input');
+      host.appendChild(input);
+      controller.setAriaTarget(input);
+      expect(tooltip.ariaTarget).to.equal(input);
+    });
   });
 
   describe('slotted tooltip', () => {

packages/tooltip/src/vaadin-tooltip.d.ts

@@ -78,6 +78,12 @@ declare class Tooltip extends OverlayClassMixin(ThemePropertyMixin(ElementMixin(
    */
   static setDefaultHoverDelay(delay: number): void;
 
+  /**
+   * Element used to link with the `aria-describedby`
+   * attribute. When not set, defaults to `target`.
+   */
+  ariaTarget: HTMLElement | undefined;
+
   /**
    * Object with properties passed to `generator` and
    * `shouldShow` functions for generating tooltip text

packages/tooltip/src/vaadin-tooltip.js

@@ -281,6 +281,14 @@ class Tooltip extends OverlayClassMixin(ThemePropertyMixin(ElementMixin(PolymerE
 
   static get properties() {
     return {
+      /**
+       * Element used to link with the `aria-describedby`
+       * attribute. When not set, defaults to `target`.
+       */
+      ariaTarget: {
+        type: Object,
+      },
+
       /**
        * Object with properties passed to `generator` and
        * `shouldShow` functions for generating tooltip text
@@ -420,6 +428,17 @@ class Tooltip extends OverlayClassMixin(ThemePropertyMixin(ElementMixin(PolymerE
         value: 'bottom',
       },
 
+      /**
+       * Element used to link with the `aria-describedby`
+       * attribute. When not set, defaults to `target`.
+       * @protected
+       */
+      _effectiveAriaTarget: {
+        type: Object,
+        computed: '__computeAriaTarget(ariaTarget, target)',
+        observer: '__effectiveAriaTargetChanged',
+      },
+
       /** @private */
       __effectivePosition: {
         type: String,
@@ -518,6 +537,11 @@ class Tooltip extends OverlayClassMixin(ThemePropertyMixin(ElementMixin(PolymerE
     document.body.removeEventListener('vaadin-overlay-open', this.__onOverlayOpen);
   }
 
+  /** @private */
+  __computeAriaTarget(ariaTarget, target) {
+    return ariaTarget || target;
+  }
+
   /** @private */
   __computeHorizontalAlign(position) {
     return ['top-end', 'bottom-end', 'start-top', 'start', 'start-bottom'].includes(position) ? 'end' : 'start';
@@ -553,6 +577,17 @@ class Tooltip extends OverlayClassMixin(ThemePropertyMixin(ElementMixin(PolymerE
     root.textContent = typeof this.generator === 'function' ? this.generator(this.context) : this.text;
   }
 
+  /** @private */
+  __effectiveAriaTargetChanged(ariaTarget, oldAriaTarget) {
+    if (oldAriaTarget) {
+      removeValueFromAttribute(oldAriaTarget, 'aria-describedby', this._uniqueId);
+    }
+
+    if (ariaTarget) {
+      addValueToAttribute(ariaTarget, 'aria-describedby', this._uniqueId);
+    }
+  }
+
   /** @private */
   __autoOpenedChanged(opened, oldOpened) {
     if (opened) {
@@ -596,8 +631,6 @@ class Tooltip extends OverlayClassMixin(ThemePropertyMixin(ElementMixin(PolymerE
       oldTarget.removeEventListener('mousedown', this.__onMouseDown);
 
       this.__targetVisibilityObserver.unobserve(oldTarget);
-
-      removeValueFromAttribute(oldTarget, 'aria-describedby', this._uniqueId);
     }
 
     if (target) {
@@ -611,8 +644,6 @@ class Tooltip extends OverlayClassMixin(ThemePropertyMixin(ElementMixin(PolymerE
       requestAnimationFrame(() => {
         this.__targetVisibilityObserver.observe(target);
       });
-
-      addValueToAttribute(target, 'aria-describedby', this._uniqueId);
     }
   }
 

packages/tooltip/test/tooltip.test.js

@@ -158,6 +158,40 @@ describe('vaadin-tooltip', () => {
     });
   });
 
+  describe('ariaTarget', () => {
+    let target, ariaTarget;
+
+    beforeEach(() => {
+      target = document.createElement('div');
+      target.textContent = 'Target';
+      document.body.appendChild(target);
+
+      ariaTarget = document.createElement('input');
+      target.appendChild(ariaTarget);
+    });
+
+    afterEach(() => {
+      document.body.removeChild(target);
+    });
+
+    it('should set aria-describedby on the ariaTarget element', () => {
+      tooltip.target = target;
+      tooltip.ariaTarget = ariaTarget;
+
+      expect(ariaTarget.getAttribute('aria-describedby')).to.equal(overlay.id);
+    });
+
+    it('should remove aria-describedby when the ariaTarget is cleared', () => {
+      tooltip.target = target;
+      tooltip.ariaTarget = ariaTarget;
+
+      tooltip.ariaTarget = null;
+
+      expect(ariaTarget.hasAttribute('aria-describedby')).to.be.false;
+      expect(target.getAttribute('aria-describedby')).to.equal(overlay.id);
+    });
+  });
+
   describe('for', () => {
     let target;
 

packages/tooltip/test/typings/tooltip.types.ts

@@ -15,6 +15,7 @@ assertType<ThemePropertyMixinClass>(tooltip);
 
 // Properties
 assertType<string | undefined>(tooltip.for);
+assertType<HTMLElement | undefined>(tooltip.ariaTarget);
 assertType<HTMLElement | undefined>(tooltip.target);
 assertType<string | null | undefined>(tooltip.text);
 assertType<Record<string, unknown>>(tooltip.context);