feat: add markdown support to tooltip (#10245)

sissbruecker · web-flow · commit 322c15b25eab · 2025-10-02T17:09:09.000+03:00
diff --git a/dev/playground/tooltip.html b/dev/playground/tooltip.html
@@ -0,0 +1,32 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta http-equiv="X-UA-Compatible" content="IE=edge" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Tooltip</title>
+    <script type="module" src="../common.js"></script>
+    <script type="module">
+      import '@vaadin/tooltip';
+    </script>
+  </head>
+  <body>
+    <section class="section">
+      <h2 class="heading">Tooltip with Markdown</h2>
+      <button id="tooltip-with-markdown-target">Target</button>
+      <vaadin-tooltip markdown for="tooltip-with-markdown-target"></vaadin-tooltip>
+    </section>
+  </body>
+
+  <script type="module">
+    const markdownTooltip = document.querySelector('vaadin-tooltip[for="tooltip-with-markdown-target"]');
+    markdownTooltip.text = `
+## Tooltip Title
+
+This tooltip contains:
+
+- **Bold** and *italic* text
+- A [link](https://vaadin.com)
+- Code: \`console.log('Hello')\``;
+  </script>
+</html>
diff --git a/packages/tooltip/package.json b/packages/tooltip/package.json
@@ -36,6 +36,7 @@
     "@open-wc/dedupe-mixin": "^1.3.0",
     "@vaadin/a11y-base": "25.0.0-alpha20",
     "@vaadin/component-base": "25.0.0-alpha20",
+    "@vaadin/markdown": "25.0.0-alpha20",
     "@vaadin/overlay": "25.0.0-alpha20",
     "@vaadin/popover": "25.0.0-alpha20",
     "@vaadin/vaadin-themable-mixin": "25.0.0-alpha20",
diff --git a/packages/tooltip/src/styles/vaadin-tooltip-overlay-base-styles.js b/packages/tooltip/src/styles/vaadin-tooltip-overlay-base-styles.js
@@ -28,7 +28,7 @@ export const tooltipOverlayStyles = css`
       var(--vaadin-tooltip-shadow, 0 3px 8px -1px rgba(0, 0, 0, 0.2));
   }
 
-  [part='content'] {
+  :host(:not([markdown])) [part='content'] {
     white-space: pre-wrap;
   }
 
diff --git a/packages/tooltip/src/vaadin-tooltip-mixin.d.ts b/packages/tooltip/src/vaadin-tooltip-mixin.d.ts
@@ -87,4 +87,13 @@ export declare class TooltipMixinClass {
    * String used as a tooltip content.
    */
   text: string | null | undefined;
+
+  /**
+   * When enabled, the tooltip text is rendered as Markdown.
+   *
+   * **Note:** Using Markdown is discouraged if accessibility of the tooltip
+   * content is essential, as semantics of the rendered HTML content
+   * (headers, lists, ...) will not be conveyed to assistive technologies.
+   */
+  markdown: boolean;
 }
diff --git a/packages/tooltip/src/vaadin-tooltip-mixin.js b/packages/tooltip/src/vaadin-tooltip-mixin.js
@@ -328,6 +328,19 @@ export const TooltipMixin = (superClass) =>
           type: String,
         },
 
+        /**
+         * When enabled, the tooltip text is rendered as Markdown.
+         *
+         * **Note:** Using Markdown is discouraged if accessibility of the tooltip
+         * content is essential, as semantics of the rendered HTML content
+         * (headers, lists, ...) will not be conveyed to assistive technologies.
+         */
+        markdown: {
+          type: Boolean,
+          value: false,
+          reflectToAttribute: true,
+        },
+
         /**
          * Element used to link with the `aria-describedby`
          * attribute. When not set, defaults to `target`.
@@ -447,9 +460,8 @@ export const TooltipMixin = (superClass) =>
     updated(props) {
       super.updated(props);
 
-      if (props.has('text') || props.has('generator') || props.has('context')) {
+      if (props.has('text') || props.has('generator') || props.has('context') || props.has('markdown')) {
         this.__updateContent();
-        this.$.overlay.toggleAttribute('hidden', this.__contentNode.textContent.trim() === '');
       }
     }
 
@@ -681,8 +693,17 @@ export const TooltipMixin = (superClass) =>
     }
 
     /** @private */
-    __updateContent() {
-      this.__contentNode.textContent = typeof this.generator === 'function' ? this.generator(this.context) : this.text;
+    async __updateContent() {
+      const content = typeof this.generator === 'function' ? this.generator(this.context) : this.text;
+
+      if (this.markdown && content) {
+        const helpers = await this.constructor.__importMarkdownHelpers();
+        helpers.renderMarkdownToElement(this.__contentNode, content);
+      } else {
+        this.__contentNode.textContent = content || '';
+      }
+
+      this.$.overlay.toggleAttribute('hidden', this.__contentNode.textContent.trim() === '');
       this.dispatchEvent(new CustomEvent('content-changed', { detail: { content: this.__contentNode.textContent } }));
     }
 
@@ -708,6 +729,14 @@ export const TooltipMixin = (superClass) =>
       }
     }
 
+    /** @private **/
+    static __importMarkdownHelpers() {
+      if (!this.__markdownHelpers) {
+        this.__markdownHelpers = import('@vaadin/markdown/src/markdown-helpers.js');
+      }
+      return this.__markdownHelpers;
+    }
+
     /**
      * Fired when the tooltip text content is changed.
      *
diff --git a/packages/tooltip/src/vaadin-tooltip.d.ts b/packages/tooltip/src/vaadin-tooltip.d.ts
@@ -28,6 +28,19 @@ export interface TooltipEventMap extends HTMLElementEventMap, TooltipCustomEvent
  * <vaadin-tooltip text="Click to save changes" for="confirm"></vaadin-tooltip>
  * ```
  *
+ * ### Markdown Support
+ *
+ * The tooltip supports rendering Markdown content by setting the `markdown` property:
+ *
+ * ```html
+ * <button id="info">Info</button>
+ * <vaadin-tooltip
+ *   text="**Important:** Click to view *detailed* information"
+ *   markdown
+ *   for="info">
+ * </vaadin-tooltip>
+ * ```
+ *
  * ### Styling
  *
  * The following shadow DOM parts are available for styling:
@@ -41,6 +54,7 @@ export interface TooltipEventMap extends HTMLElementEventMap, TooltipCustomEvent
  *
  * Attribute        | Description
  * -----------------|----------------------------------------
+ * `markdown`       | Reflects the `markdown` property value.
  * `position`       | Reflects the `position` property value.
  *
  * ### Custom CSS Properties
diff --git a/packages/tooltip/src/vaadin-tooltip.js b/packages/tooltip/src/vaadin-tooltip.js
@@ -20,6 +20,19 @@ import { TooltipMixin } from './vaadin-tooltip-mixin.js';
  * <vaadin-tooltip text="Click to save changes" for="confirm"></vaadin-tooltip>
  * ```
  *
+ * ### Markdown Support
+ *
+ * The tooltip supports rendering Markdown content by setting the `markdown` property:
+ *
+ * ```html
+ * <button id="info">Info</button>
+ * <vaadin-tooltip
+ *   text="**Important:** Click to view *detailed* information"
+ *   markdown
+ *   for="info">
+ * </vaadin-tooltip>
+ * ```
+ *
  * ### Styling
  *
  * The following shadow DOM parts are available for styling:
@@ -33,6 +46,7 @@ import { TooltipMixin } from './vaadin-tooltip-mixin.js';
  *
  * Attribute        | Description
  * -----------------|----------------------------------------
+ * `markdown`       | Reflects the `markdown` property value.
  * `position`       | Reflects the `position` property value.
  *
  * ### Custom CSS Properties
@@ -90,6 +104,7 @@ class Tooltip extends TooltipMixin(ThemePropertyMixin(ElementMixin(PolylitMixin(
         @mouseenter="${this.__onOverlayMouseEnter}"
         @mouseleave="${this.__onOverlayMouseLeave}"
         modeless
+        ?markdown="${this.markdown}"
         exportparts="overlay, content"
         ><slot name="overlay"></slot
       ></vaadin-tooltip-overlay>
diff --git a/packages/tooltip/test/tooltip-markdown.test.js b/packages/tooltip/test/tooltip-markdown.test.js
@@ -0,0 +1,149 @@
+import { expect } from '@vaadin/chai-plugins';
+import { fixtureSync, nextRender, nextUpdate } from '@vaadin/testing-helpers';
+import sinon from 'sinon';
+import { Tooltip } from '../src/vaadin-tooltip.js';
+
+describe('markdown', () => {
+  let tooltip, overlay, contentNode;
+
+  before(async () => {
+    // Preload markdown helpers to avoid dynamic import delays
+    await Tooltip.__importMarkdownHelpers();
+  });
+
+  beforeEach(async () => {
+    tooltip = fixtureSync('<vaadin-tooltip></vaadin-tooltip>');
+    await nextRender();
+    overlay = tooltip.shadowRoot.querySelector('vaadin-tooltip-overlay');
+    contentNode = tooltip.querySelector('[slot="overlay"]');
+  });
+
+  it('should have markdown property with default value false', () => {
+    expect(tooltip.markdown).to.equal(false);
+  });
+
+  it('should reflect markdown property to attribute', async () => {
+    expect(tooltip.hasAttribute('markdown')).to.be.false;
+
+    tooltip.markdown = true;
+    await nextUpdate(tooltip);
+    expect(tooltip.hasAttribute('markdown')).to.be.true;
+  });
+
+  describe('markdown disabled', () => {
+    it('should not parse markdown syntax by default', async () => {
+      tooltip.text = '**Bold text** and *italic text*';
+      await nextUpdate(tooltip);
+      expect(contentNode.innerHTML).to.equal('**Bold text** and *italic text*');
+    });
+  });
+
+  describe('markdown enabled', () => {
+    beforeEach(async () => {
+      tooltip.markdown = true;
+      await nextUpdate(tooltip);
+    });
+
+    it('should parse markdown syntax', async () => {
+      tooltip.text = '**Bold text** and *italic text*';
+      await nextUpdate(tooltip);
+      expect(contentNode.innerHTML.trim()).to.equal('<p><strong>Bold text</strong> and <em>italic text</em></p>');
+    });
+
+    it('should update content when markdown text changes', async () => {
+      tooltip.text = '# Heading 1';
+      await nextUpdate(tooltip);
+      expect(contentNode.innerHTML.trim()).to.equal('<h1>Heading 1</h1>');
+
+      tooltip.text = '## Heading 2';
+      await nextUpdate(tooltip);
+      expect(contentNode.innerHTML.trim()).to.equal('<h2>Heading 2</h2>');
+    });
+
+    it('should handle empty/null/undefined content', async () => {
+      tooltip.text = '';
+      await nextUpdate(tooltip);
+      expect(contentNode.innerHTML).to.equal('');
+
+      tooltip.text = null;
+      await nextUpdate(tooltip);
+      expect(contentNode.innerHTML).to.equal('');
+
+      tooltip.text = undefined;
+      await nextUpdate(tooltip);
+      expect(contentNode.innerHTML).to.equal('');
+    });
+
+    it('should sanitize markdown', async () => {
+      tooltip.text = '<script>alert("xss")</script>\n\n**Safe content**';
+      await nextUpdate(tooltip);
+
+      expect(contentNode.innerHTML.trim()).to.equal('<p><strong>Safe content</strong></p>');
+    });
+
+    it('should hide overlay when markdown content is empty', async () => {
+      tooltip.text = '';
+      await nextUpdate(tooltip);
+
+      expect(overlay.hasAttribute('hidden')).to.be.true;
+    });
+
+    it('should show overlay when markdown content is not empty', async () => {
+      tooltip.text = '**Content**';
+      await nextUpdate(tooltip);
+
+      expect(overlay.hasAttribute('hidden')).to.be.false;
+    });
+
+    it('should fire content-changed event when markdown content is set', async () => {
+      const spy = sinon.spy();
+      tooltip.addEventListener('content-changed', spy);
+
+      tooltip.text = '**Bold text**';
+      await nextUpdate(tooltip);
+
+      expect(spy.callCount).to.equal(1);
+      expect(spy.firstCall.args[0].detail).to.deep.equal({ content: 'Bold text\n' });
+    });
+  });
+
+  describe('switching between text and markdown', () => {
+    it('should switch from text to markdown', async () => {
+      tooltip.text = '**Bold text**';
+      await nextUpdate(tooltip);
+      expect(contentNode.innerHTML).to.equal('**Bold text**');
+
+      tooltip.markdown = true;
+      await nextUpdate(tooltip);
+      expect(contentNode.innerHTML.trim()).to.equal('<p><strong>Bold text</strong></p>');
+    });
+
+    it('should switch from markdown to text', async () => {
+      tooltip.markdown = true;
+      tooltip.text = '**Bold text**';
+      await nextUpdate(tooltip);
+      expect(contentNode.innerHTML.trim()).to.equal('<p><strong>Bold text</strong></p>');
+
+      tooltip.markdown = false;
+      await nextUpdate(tooltip);
+      expect(contentNode.innerHTML).to.equal('**Bold text**');
+    });
+
+    it('should fire content-changed event when switching content types', async () => {
+      const spy = sinon.spy();
+      tooltip.addEventListener('content-changed', spy);
+
+      tooltip.text = '**Bold text**';
+      await nextUpdate(tooltip);
+
+      expect(spy.callCount).to.equal(1);
+      expect(spy.firstCall.args[0].detail).to.deep.equal({ content: '**Bold text**' });
+
+      tooltip.markdown = true;
+      await nextUpdate(tooltip);
+
+      expect(spy.callCount).to.equal(2);
+      expect(spy.secondCall.args[0].detail).to.deep.equal({ content: 'Bold text\n' });
+    });
+  });
+});
diff --git a/packages/tooltip/test/typings/tooltip.types.ts b/packages/tooltip/test/typings/tooltip.types.ts
@@ -19,6 +19,7 @@ assertType<string | null | undefined>(tooltip.text);
 assertType<Record<string, unknown>>(tooltip.context);
 assertType<(context: Record<string, unknown>) => string>(tooltip.generator);
 assertType<boolean>(tooltip.manual);
+assertType<boolean>(tooltip.markdown);
 assertType<boolean>(tooltip.opened);
 assertType<number>(tooltip.focusDelay);
 assertType<number>(tooltip.hideDelay);
diff --git a/packages/tooltip/test/visual/base/screenshots/tooltip/baseline/markdown.png b/packages/tooltip/test/visual/base/screenshots/tooltip/baseline/markdown.png
diff --git a/packages/tooltip/test/visual/base/tooltip.test.js b/packages/tooltip/test/visual/base/tooltip.test.js
@@ -6,10 +6,12 @@ import { mouseenter } from '../../helpers.js';
 describe('tooltip', () => {
   let div, target, element;
 
-  before(() => {
+  before(async () => {
     Tooltip.setDefaultFocusDelay(0);
     Tooltip.setDefaultHoverDelay(0);
     Tooltip.setDefaultHideDelay(0);
+    // Preload markdown helpers to avoid dynamic import delays
+    await Tooltip.__importMarkdownHelpers();
   });
 
   beforeEach(() => {
@@ -61,4 +63,23 @@ describe('tooltip', () => {
     await nextRender();
     await visualDiff(div, 'white-space-pre');
   });
+
+  it('markdown', async () => {
+    // Increase container height to fit larger tooltip content
+    div.style.height = '500px';
+
+    element.markdown = true;
+    element.text = `
+## Tooltip Title
+
+This tooltip contains:
+
+- **Bold** and *italic* text
+- A [link](https://vaadin.com)
+- Code: \`console.log('Hello')\``;
+    await nextUpdate(element);
+    mouseenter(target);
+    await nextRender();
+    await visualDiff(div, 'markdown');
+  });
 });
diff --git a/packages/tooltip/test/visual/lumo/screenshots/tooltip/baseline/markdown.png b/packages/tooltip/test/visual/lumo/screenshots/tooltip/baseline/markdown.png
diff --git a/packages/tooltip/test/visual/lumo/tooltip.test.js b/packages/tooltip/test/visual/lumo/tooltip.test.js
diff --git a/packages/vaadin-lumo-styles/src/components/tooltip-overlay.css b/packages/vaadin-lumo-styles/src/components/tooltip-overlay.css
