@vaadin/tooltip 25.2.7 → 25.3.0-alpha10

package/custom-elements.json

@@ -17,6 +17,64 @@
         }
       ]
     },
+    {
+      "kind": "javascript-module",
+      "path": "src/vaadin-tooltip-aria-mixin.js",
+      "declarations": [
+        {
+          "kind": "mixin",
+          "description": "A mixin providing linking of the tooltip content to the tooltip target\nelements using the `aria-describedby` or `aria-labelledby` attribute.\n\nTargets in the same root as the tooltip are linked by the content element\nID. ID references only resolve within a single tree scope, so targets in\nother roots are linked with ARIA element references instead.",
+          "name": "TooltipAriaMixin",
+          "members": [
+            {
+              "kind": "field",
+              "name": "ariaLinkMode",
+              "privacy": "public",
+              "type": {
+                "text": "string"
+              },
+              "description": "Controls which ARIA attribute is used to link the target element(s)\nwith the tooltip content. Supported values:\n\n- `aria-describedby` - links the tooltip as a description.\n- `aria-labelledby` - links the tooltip as an accessible name.\n- `none` - does not add any ARIA linking attribute.\n\nDefaults to `aria-describedby`.",
+              "attribute": "aria-link-mode"
+            },
+            {
+              "kind": "field",
+              "name": "ariaTarget",
+              "privacy": "public",
+              "type": {
+                "text": "object"
+              },
+              "description": "Element used to link with the ARIA attribute controlled by the\n`ariaLinkMode` property. Supports array of multiple elements.\nWhen not set, defaults to `target`.",
+              "attribute": "aria-target"
+            }
+          ],
+          "attributes": [
+            {
+              "name": "aria-link-mode",
+              "type": {
+                "text": "string"
+              },
+              "description": "Controls which ARIA attribute is used to link the target element(s)\nwith the tooltip content. Supported values:\n\n- `aria-describedby` - links the tooltip as a description.\n- `aria-labelledby` - links the tooltip as an accessible name.\n- `none` - does not add any ARIA linking attribute.\n\nDefaults to `aria-describedby`.",
+              "fieldName": "ariaLinkMode"
+            }
+          ],
+          "parameters": [
+            {
+              "name": "superClass"
+            }
+          ]
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "TooltipAriaMixin",
+          "declaration": {
+            "name": "TooltipAriaMixin",
+            "module": "src/vaadin-tooltip-aria-mixin.js"
+          }
+        }
+      ]
+    },
     {
       "kind": "javascript-module",
       "path": "src/vaadin-tooltip-mixin.js",
@@ -34,7 +92,11 @@
                 "text": "string"
               },
               "description": "Controls which ARIA attribute is used to link the target element(s)\nwith the tooltip content. Supported values:\n\n- `aria-describedby` - links the tooltip as a description.\n- `aria-labelledby` - links the tooltip as an accessible name.\n- `none` - does not add any ARIA linking attribute.\n\nDefaults to `aria-describedby`.",
-              "attribute": "aria-link-mode"
+              "attribute": "aria-link-mode",
+              "inheritedFrom": {
+                "name": "TooltipAriaMixin",
+                "module": "src/vaadin-tooltip-aria-mixin.js"
+              }
             },
             {
               "kind": "field",
@@ -44,7 +106,11 @@
                 "text": "object"
               },
               "description": "Element used to link with the ARIA attribute controlled by the\n`ariaLinkMode` property. Supports array of multiple elements.\nWhen not set, defaults to `target`.",
-              "attribute": "aria-target"
+              "attribute": "aria-target",
+              "inheritedFrom": {
+                "name": "TooltipAriaMixin",
+                "module": "src/vaadin-tooltip-aria-mixin.js"
+              }
             },
             {
               "kind": "field",
@@ -246,7 +312,11 @@
                 "text": "string"
               },
               "description": "Controls which ARIA attribute is used to link the target element(s)\nwith the tooltip content. Supported values:\n\n- `aria-describedby` - links the tooltip as a description.\n- `aria-labelledby` - links the tooltip as an accessible name.\n- `none` - does not add any ARIA linking attribute.\n\nDefaults to `aria-describedby`.",
-              "fieldName": "ariaLinkMode"
+              "fieldName": "ariaLinkMode",
+              "inheritedFrom": {
+                "name": "TooltipAriaMixin",
+                "module": "src/vaadin-tooltip-aria-mixin.js"
+              }
             },
             {
               "name": "focus-delay",
@@ -330,6 +400,10 @@
             }
           ],
           "mixins": [
+            {
+              "name": "TooltipAriaMixin",
+              "module": "src/vaadin-tooltip-aria-mixin.js"
+            },
             {
               "name": "PopoverPositionMixin",
               "package": "@vaadin/popover/src/vaadin-popover-position-mixin.js"
@@ -376,8 +450,8 @@
               "description": "Controls which ARIA attribute is used to link the target element(s)\nwith the tooltip content. Supported values:\n\n- `aria-describedby` - links the tooltip as a description.\n- `aria-labelledby` - links the tooltip as an accessible name.\n- `none` - does not add any ARIA linking attribute.\n\nDefaults to `aria-describedby`.",
               "attribute": "aria-link-mode",
               "inheritedFrom": {
-                "name": "TooltipMixin",
-                "module": "src/vaadin-tooltip-mixin.js"
+                "name": "TooltipAriaMixin",
+                "module": "src/vaadin-tooltip-aria-mixin.js"
               }
             },
             {
@@ -390,8 +464,8 @@
               "description": "Element used to link with the ARIA attribute controlled by the\n`ariaLinkMode` property. Supports array of multiple elements.\nWhen not set, defaults to `target`.",
               "attribute": "aria-target",
               "inheritedFrom": {
-                "name": "TooltipMixin",
-                "module": "src/vaadin-tooltip-mixin.js"
+                "name": "TooltipAriaMixin",
+                "module": "src/vaadin-tooltip-aria-mixin.js"
               }
             },
             {
@@ -644,30 +718,6 @@
               }
             }
           ],
-          "mixins": [
-            {
-              "name": "TooltipMixin",
-              "module": "src/vaadin-tooltip-mixin.js"
-            },
-            {
-              "name": "ThemePropertyMixin",
-              "package": "@vaadin/vaadin-themable-mixin/vaadin-theme-property-mixin.js"
-            },
-            {
-              "name": "ElementMixin",
-              "package": "@vaadin/component-base/src/element-mixin.js"
-            },
-            {
-              "name": "PolylitMixin",
-              "package": "@vaadin/component-base/src/polylit-mixin.js"
-            }
-          ],
-          "superclass": {
-            "name": "LitElement",
-            "package": "lit"
-          },
-          "tagName": "vaadin-tooltip",
-          "customElement": true,
           "attributes": [
             {
               "name": "aria-link-mode",
@@ -677,8 +727,8 @@
               "description": "Controls which ARIA attribute is used to link the target element(s)\nwith the tooltip content. Supported values:\n\n- `aria-describedby` - links the tooltip as a description.\n- `aria-labelledby` - links the tooltip as an accessible name.\n- `none` - does not add any ARIA linking attribute.\n\nDefaults to `aria-describedby`.",
               "fieldName": "ariaLinkMode",
               "inheritedFrom": {
-                "name": "TooltipMixin",
-                "module": "src/vaadin-tooltip-mixin.js"
+                "name": "TooltipAriaMixin",
+                "module": "src/vaadin-tooltip-aria-mixin.js"
               }
             },
             {
@@ -788,8 +838,39 @@
                 "name": "TooltipMixin",
                 "module": "src/vaadin-tooltip-mixin.js"
               }
+            },
+            {
+              "type": {
+                "text": "string"
+              },
+              "description": "The theme variants to apply to the component.",
+              "name": "theme"
             }
-          ]
+          ],
+          "mixins": [
+            {
+              "name": "TooltipMixin",
+              "module": "src/vaadin-tooltip-mixin.js"
+            },
+            {
+              "name": "ThemePropertyMixin",
+              "package": "@vaadin/vaadin-themable-mixin/vaadin-theme-property-mixin.js"
+            },
+            {
+              "name": "ElementMixin",
+              "package": "@vaadin/component-base/src/element-mixin.js"
+            },
+            {
+              "name": "PolylitMixin",
+              "package": "@vaadin/component-base/src/polylit-mixin.js"
+            }
+          ],
+          "superclass": {
+            "name": "LitElement",
+            "package": "lit"
+          },
+          "tagName": "vaadin-tooltip",
+          "customElement": true
         }
       ],
       "exports": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vaadin/tooltip",
-  "version": "25.2.7",
+  "version": "25.3.0-alpha10",
   "publishConfig": {
     "access": "public"
   },
@@ -35,20 +35,20 @@
   ],
   "dependencies": {
     "@open-wc/dedupe-mixin": "^1.3.0",
-    "@vaadin/a11y-base": "~25.2.7",
-    "@vaadin/component-base": "~25.2.7",
-    "@vaadin/markdown": "~25.2.7",
-    "@vaadin/overlay": "~25.2.7",
-    "@vaadin/popover": "~25.2.7",
-    "@vaadin/vaadin-themable-mixin": "~25.2.7",
+    "@vaadin/a11y-base": "25.3.0-alpha10",
+    "@vaadin/component-base": "25.3.0-alpha10",
+    "@vaadin/markdown": "25.3.0-alpha10",
+    "@vaadin/overlay": "25.3.0-alpha10",
+    "@vaadin/popover": "25.3.0-alpha10",
+    "@vaadin/vaadin-themable-mixin": "25.3.0-alpha10",
     "lit": "^3.0.0"
   },
   "devDependencies": {
-    "@vaadin/aura": "~25.2.7",
-    "@vaadin/chai-plugins": "~25.2.7",
-    "@vaadin/test-runner-commands": "~25.2.7",
+    "@vaadin/aura": "25.3.0-alpha10",
+    "@vaadin/chai-plugins": "25.3.0-alpha10",
+    "@vaadin/test-runner-commands": "25.3.0-alpha10",
     "@vaadin/testing-helpers": "^2.0.0",
-    "@vaadin/vaadin-lumo-styles": "~25.2.7",
+    "@vaadin/vaadin-lumo-styles": "25.3.0-alpha10",
     "sinon": "^22.0.0"
   },
   "customElements": "custom-elements.json",
@@ -56,5 +56,5 @@
     "web-types.json",
     "web-types.lit.json"
   ],
-  "gitHead": "14be1af674f3968cce68c6eb4742340694c4a949"
+  "gitHead": "f2833abdf9b613fa0d0ed216830e3f4de87b7dac"
 }

package/src/vaadin-tooltip-aria-mixin.d.ts

@@ -0,0 +1,41 @@
+/**
+ * @license
+ * Copyright (c) 2026 - 2026 Vaadin Ltd.
+ * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
+ */
+import type { Constructor } from '@open-wc/dedupe-mixin';
+
+/**
+ * A mixin providing linking of the tooltip content to the tooltip target
+ * elements using the `aria-describedby` or `aria-labelledby` attribute.
+ *
+ * Targets in the same root as the tooltip are linked by the content element
+ * ID. ID references only resolve within a single tree scope, so targets in
+ * other roots are linked with ARIA element references instead.
+ */
+export declare function TooltipAriaMixin<T extends Constructor<HTMLElement>>(
+  base: T,
+): Constructor<TooltipAriaMixinClass> & T;
+
+export declare class TooltipAriaMixinClass {
+  /**
+   * Element used to link with the ARIA attribute controlled by the
+   * `ariaLinkMode` property. Supports array of multiple elements.
+   * When not set, defaults to `target`.
+   */
+  ariaTarget: HTMLElement | HTMLElement[] | null | undefined;
+
+  /**
+   * Controls which ARIA attribute is used to link the target element(s)
+   * with the tooltip content. Supported values:
+   *
+   * - `aria-describedby` - links the tooltip as a description.
+   * - `aria-labelledby` - links the tooltip as an accessible name.
+   * - `none` - does not add any ARIA linking attribute.
+   *
+   * Defaults to `aria-describedby`.
+   *
+   * @attr {string} aria-link-mode
+   */
+  ariaLinkMode: 'aria-describedby' | 'aria-labelledby' | 'none';
+}

package/src/vaadin-tooltip-aria-mixin.js

@@ -0,0 +1,126 @@
+/**
+ * @license
+ * Copyright (c) 2026 - 2026 Vaadin Ltd.
+ * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
+ */
+import { addAriaElementReference, removeAriaElementReference } from '@vaadin/a11y-base/src/aria-element-reference.js';
+import { addValuesToAttribute, removeValuesFromAttribute } from '@vaadin/component-base/src/dom-utils.js';
+
+/**
+ * A mixin providing linking of the tooltip content to the tooltip target
+ * elements using the `aria-describedby` or `aria-labelledby` attribute.
+ *
+ * Targets in the same root as the tooltip are linked by the content element
+ * ID. ID references only resolve within a single tree scope, so targets in
+ * other roots are linked with ARIA element references instead.
+ */
+export const TooltipAriaMixin = (superClass) =>
+  class TooltipAriaMixinClass extends superClass {
+    #ariaReferences = [];
+
+    static get properties() {
+      return {
+        /**
+         * Element used to link with the ARIA attribute controlled by the
+         * `ariaLinkMode` property. Supports array of multiple elements.
+         * When not set, defaults to `target`.
+         */
+        ariaTarget: {
+          type: Object,
+        },
+
+        /**
+         * Controls which ARIA attribute is used to link the target element(s)
+         * with the tooltip content. Supported values:
+         *
+         * - `aria-describedby` - links the tooltip as a description.
+         * - `aria-labelledby` - links the tooltip as an accessible name.
+         * - `none` - does not add any ARIA linking attribute.
+         *
+         * Defaults to `aria-describedby`.
+         *
+         * @attr {string} aria-link-mode
+         */
+        ariaLinkMode: {
+          type: String,
+          value: 'aria-describedby',
+        },
+
+        /**
+         * Element used to link with the `aria-describedby`
+         * attribute. When not set, defaults to `target`.
+         * @protected
+         */
+        _effectiveAriaTarget: {
+          type: Object,
+          computed: '__computeAriaTarget(ariaTarget, target)',
+        },
+      };
+    }
+
+    /** @protected */
+    connectedCallback() {
+      super.connectedCallback();
+      this.#addAriaReferences();
+    }
+
+    /** @protected */
+    disconnectedCallback() {
+      super.disconnectedCallback();
+      this.#removeAriaReferences();
+    }
+
+    /** @protected */
+    updated(props) {
+      super.updated(props);
+
+      if (props.has('_effectiveAriaTarget') || props.has('ariaLinkMode')) {
+        this.#updateAriaReferences();
+      }
+    }
+
+    #addAriaReferences() {
+      const mode = this.ariaLinkMode;
+      const targets = this._effectiveAriaTarget;
+      const contentNode = this.__contentNode;
+      if (!contentNode || !targets || !mode || mode === 'none') {
+        return;
+      }
+
+      [targets].flat().forEach((target) => {
+        const byReference = target.getRootNode() !== this.getRootNode();
+        if (byReference) {
+          addAriaElementReference(target, mode, contentNode);
+        } else {
+          addValuesToAttribute(target, mode, contentNode.id);
+        }
+
+        this.#ariaReferences.push({ target, mode, byReference });
+      });
+    }
+
+    #removeAriaReferences() {
+      const contentNode = this.__contentNode;
+
+      this.#ariaReferences.forEach(({ target, mode, byReference }) => {
+        if (byReference) {
+          removeAriaElementReference(target, mode, contentNode);
+        } else {
+          removeValuesFromAttribute(target, mode, contentNode.id);
+        }
+      });
+      this.#ariaReferences = [];
+    }
+
+    #updateAriaReferences() {
+      this.#removeAriaReferences();
+      this.#addAriaReferences();
+    }
+
+    /** @private */
+    __computeAriaTarget(ariaTarget, target) {
+      const isElementNode = (el) => el?.nodeType === Node.ELEMENT_NODE;
+      const isAriaTargetSet = Array.isArray(ariaTarget) ? ariaTarget.some(isElementNode) : ariaTarget;
+      return ariaTarget === null || isAriaTargetSet ? ariaTarget : target;
+    }
+  };

package/src/vaadin-tooltip-mixin.d.ts

@@ -6,6 +6,7 @@
 import type { Constructor } from '@open-wc/dedupe-mixin';
 import type { PopoverPositionMixinClass } from '@vaadin/popover/src/vaadin-popover-position-mixin.js';
 import type { PopoverTargetMixinClass } from '@vaadin/popover/src/vaadin-popover-target-mixin.js';
+import type { TooltipAriaMixinClass } from './vaadin-tooltip-aria-mixin.js';
 
 export type { PopoverPosition as TooltipPosition } from '@vaadin/popover/src/vaadin-popover-position-mixin.js';
 
@@ -14,30 +15,13 @@ export type { PopoverPosition as TooltipPosition } from '@vaadin/popover/src/vaa
  */
 export declare function TooltipMixin<T extends Constructor<HTMLElement>>(
   base: T,
-): Constructor<PopoverPositionMixinClass> & Constructor<PopoverTargetMixinClass> & Constructor<TooltipMixinClass> & T;
+): Constructor<PopoverPositionMixinClass> &
+  Constructor<PopoverTargetMixinClass> &
+  Constructor<TooltipAriaMixinClass> &
+  Constructor<TooltipMixinClass> &
+  T;
 
 export declare class TooltipMixinClass {
-  /**
-   * Element used to link with the ARIA attribute controlled by the
-   * `ariaLinkMode` property. Supports array of multiple elements.
-   * When not set, defaults to `target`.
-   */
-  ariaTarget: HTMLElement | HTMLElement[] | null | undefined;
-
-  /**
-   * Controls which ARIA attribute is used to link the target element(s)
-   * with the tooltip content. Supported values:
-   *
-   * - `aria-describedby` - links the tooltip as a description.
-   * - `aria-labelledby` - links the tooltip as an accessible name.
-   * - `none` - does not add any ARIA linking attribute.
-   *
-   * Defaults to `aria-describedby`.
-   *
-   * @attr {string} aria-link-mode
-   */
-  ariaLinkMode: 'aria-describedby' | 'aria-labelledby' | 'none';
-
   /**
    * Object with properties passed to `generator` and
    * `shouldShow` functions for generating tooltip text

package/src/vaadin-tooltip-mixin.js

@@ -4,11 +4,11 @@
  * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
  */
 import { isKeyboardActive } from '@vaadin/a11y-base/src/focus-utils.js';
-import { addValueToAttribute, removeValueFromAttribute } from '@vaadin/component-base/src/dom-utils.js';
 import { SlotController } from '@vaadin/component-base/src/slot-controller.js';
 import { generateUniqueId } from '@vaadin/component-base/src/unique-id-utils.js';
 import { PopoverPositionMixin } from '@vaadin/popover/src/vaadin-popover-position-mixin.js';
 import { PopoverTargetMixin } from '@vaadin/popover/src/vaadin-popover-target-mixin.js';
+import { TooltipAriaMixin } from './vaadin-tooltip-aria-mixin.js';
 
 const DEFAULT_DELAY = 500;
 
@@ -218,35 +218,9 @@ class TooltipStateController {
  * A mixin providing common tooltip functionality.
  */
 export const TooltipMixin = (superClass) =>
-  class TooltipMixinClass extends PopoverPositionMixin(PopoverTargetMixin(superClass)) {
+  class TooltipMixinClass extends TooltipAriaMixin(PopoverPositionMixin(PopoverTargetMixin(superClass))) {
     static get properties() {
       return {
-        /**
-         * Element used to link with the ARIA attribute controlled by the
-         * `ariaLinkMode` property. Supports array of multiple elements.
-         * When not set, defaults to `target`.
-         */
-        ariaTarget: {
-          type: Object,
-        },
-
-        /**
-         * Controls which ARIA attribute is used to link the target element(s)
-         * with the tooltip content. Supported values:
-         *
-         * - `aria-describedby` - links the tooltip as a description.
-         * - `aria-labelledby` - links the tooltip as an accessible name.
-         * - `none` - does not add any ARIA linking attribute.
-         *
-         * Defaults to `aria-describedby`.
-         *
-         * @attr {string} aria-link-mode
-         */
-        ariaLinkMode: {
-          type: String,
-          value: 'aria-describedby',
-        },
-
         /**
          * Object with properties passed to `generator` and
          * `shouldShow` functions for generating tooltip text
@@ -355,16 +329,6 @@ export const TooltipMixin = (superClass) =>
           reflectToAttribute: true,
         },
 
-        /**
-         * Element used to link with the `aria-describedby`
-         * attribute. When not set, defaults to `target`.
-         * @protected
-         */
-        _effectiveAriaTarget: {
-          type: Object,
-          computed: '__computeAriaTarget(ariaTarget, target)',
-        },
-
         /** @private */
         __isTargetHidden: {
           type: Boolean,
@@ -476,16 +440,6 @@ export const TooltipMixin = (superClass) =>
       if (props.has('text') || props.has('generator') || props.has('context') || props.has('markdown')) {
         this.__updateContent();
       }
-
-      const ariaTargetChanged = props.has('_effectiveAriaTarget');
-      const ariaLinkChanged = props.has('ariaLinkMode');
-
-      if (ariaTargetChanged || ariaLinkChanged) {
-        const oldTarget = ariaTargetChanged ? props.get('_effectiveAriaTarget') : this._effectiveAriaTarget;
-        const oldMode = ariaLinkChanged ? props.get('ariaLinkMode') : this.ariaLinkMode;
-
-        this.__updateAriaAttributes(oldTarget, oldMode);
-      }
     }
 
     /** @private */
@@ -746,32 +700,6 @@ export const TooltipMixin = (superClass) =>
       }
     }
 
-    /** @private */
-    __computeAriaTarget(ariaTarget, target) {
-      const isElementNode = (el) => el?.nodeType === Node.ELEMENT_NODE;
-      const isAriaTargetSet = Array.isArray(ariaTarget) ? ariaTarget.some(isElementNode) : ariaTarget;
-      return ariaTarget === null || isAriaTargetSet ? ariaTarget : target;
-    }
-
-    /** @private */
-    __updateAriaAttributes(oldTarget, oldMode) {
-      // Remove the previously applied attribute from the previous target(s).
-      if (oldTarget && oldMode && oldMode !== 'none') {
-        [oldTarget].flat().forEach((target) => {
-          removeValueFromAttribute(target, oldMode, this._uniqueId);
-        });
-      }
-
-      // Apply the current attribute to the current target(s).
-      const target = this._effectiveAriaTarget;
-      const mode = this.ariaLinkMode;
-      if (target && mode && mode !== 'none') {
-        [target].flat().forEach((el) => {
-          addValueToAttribute(el, mode, this._uniqueId);
-        });
-      }
-    }
-
     /** @private **/
     static __importMarkdownHelpers() {
       if (!this.__markdownHelpers) {

package/src/vaadin-tooltip-overlay.js

@@ -16,6 +16,7 @@ import { tooltipOverlayStyles } from './styles/vaadin-tooltip-overlay-base-style
 /**
  * An element used internally by `<vaadin-tooltip>`. Not intended to be used separately.
  *
+ * @attr {string} theme - The theme variants to apply to the component.
  * @customElement vaadin-tooltip-overlay
  * @extends HTMLElement
  * @private

package/src/vaadin-tooltip.js

@@ -73,6 +73,7 @@ import { TooltipMixin } from './vaadin-tooltip-mixin.js';
  *
  * @fires {CustomEvent} content-changed - Fired when the tooltip text content is changed.
  *
+ * @attr {string} theme - The theme variants to apply to the component.
  * @customElement vaadin-tooltip
  * @extends HTMLElement
  */

package/web-types.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/web-types",
   "name": "@vaadin/tooltip",
-  "version": "25.2.7",
+  "version": "25.3.0-alpha10",
   "description-markup": "markdown",
   "contributions": {
     "html": {
@@ -105,9 +105,7 @@
               "description": "The theme variants to apply to the component.",
               "value": {
                 "type": [
-                  "string",
-                  "null",
-                  "undefined"
+                  "string"
                 ]
               }
             }

package/web-types.lit.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/web-types",
   "name": "@vaadin/tooltip",
-  "version": "25.2.7",
+  "version": "25.3.0-alpha10",
   "description-markup": "markdown",
   "framework": "lit",
   "framework-config": {