@descope-ui/descope-tooltip 2.2.13

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+This file was generated using [@jscutlery/semver](https://github.com/jscutlery/semver).
+
+## [2.2.13](https://github.com/descope/web-components-ui/compare/web-components-ui-2.2.12...web-components-ui-2.2.13) (2025-12-21)
+
+# Changelog

package/e2e/descope-tooltip.spec.ts

@@ -0,0 +1,98 @@
+import { test, expect } from '@playwright/test';
+import { getStoryUrl, loopConfig } from 'e2e-utils';
+
+const componentAttributes = {
+  type: ['text', 'node'],
+  position: [
+    'top',
+    'top-start',
+    'top-end',
+    'bottom',
+    'bottom-start',
+    'bottom-end',
+    'start',
+    'start-top',
+    'start-bottom',
+    'end',
+    'end-top',
+    'end-bottom',
+  ],
+  opened: ['true', 'false'],
+};
+
+const storyName = 'descope-tooltip';
+
+test.describe('theme', () => {
+  loopConfig(componentAttributes, (attr, value) => {
+    test(`${attr}: ${value}`, async ({ page }) => {
+      await page.goto(getStoryUrl(storyName, { [attr]: value }), {
+        waitUntil: 'networkidle',
+      });
+      const component = page.locator('.tooltip-anchor');
+      const container = page.locator('.story-wrapper');
+
+      await component.hover();
+      await page.waitForTimeout(500);
+
+      expect(await container.screenshot()).toMatchSnapshot();
+    });
+  });
+
+  ['ltr', 'rtl'].forEach((direction) => {
+    test(`direction: ${direction}`, async ({ page }) => {
+      await page.goto(getStoryUrl(storyName, { direction, text: 'test--' }));
+      const component = page.locator('.tooltip-anchor');
+      const container = page.locator('.story-wrapper');
+
+      await component.hover();
+
+      expect(await container.screenshot()).toMatchSnapshot();
+    });
+  });
+});
+
+test.describe('logic', () => {
+  test('show and hide on hover and blur', async ({ page }) => {
+    await page.goto(getStoryUrl(storyName));
+    const component = page.locator('.tooltip-anchor');
+    const container = page.locator('.story-wrapper');
+
+    expect(await container.screenshot()).toMatchSnapshot();
+
+    await component.hover();
+    expect(await container.screenshot()).toMatchSnapshot();
+
+    await container.click();
+    expect(await container.screenshot()).toMatchSnapshot();
+  });
+
+  test('hover-delay', async ({ page }) => {
+    await page.goto(getStoryUrl(storyName, { hoverDelay: 2000 }));
+    const component = page.locator('.tooltip-anchor');
+    const container = page.locator('.story-wrapper');
+
+    // hover component
+    await component.hover();
+
+    // no tooltip should appear yet
+    expect(await container.screenshot()).toMatchSnapshot();
+
+    // wait 2 seconds
+    await page.waitForTimeout(2000);
+
+    // tooltip should appear
+    expect(await container.screenshot()).toMatchSnapshot();
+  });
+
+  test('hide-delay', async ({ page }) => {
+    await page.goto(getStoryUrl(storyName, { hideDelay: 5000 }));
+    const component = page.locator('.tooltip-anchor');
+    const container = page.locator('.story-wrapper');
+
+    await component.hover();
+    expect(await container.screenshot()).toMatchSnapshot();
+
+    await page.waitForTimeout(3000);
+    expect(await container.screenshot()).toMatchSnapshot();
+  });
+});

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@descope-ui/descope-tooltip",
+  "version": "2.2.13",
+  "exports": {
+    ".": {
+      "import": "./src/component/index.js"
+    },
+    "./theme": {
+      "import": "./src/theme.js"
+    },
+    "./class": {
+      "import": "./src/component/TooltipClass.js"
+    }
+  },
+  "devDependencies": {
+    "@playwright/test": "1.38.1",
+    "e2e-utils": "2.2.13"
+  },
+  "dependencies": {
+    "@vaadin/tooltip": "24.3.4",
+    "@descope-ui/common": "2.2.13",
+    "@descope-ui/theme-globals": "2.2.13",
+    "@descope-ui/descope-enriched-text": "2.2.13"
+  },
+  "publishConfig": {
+    "link-workspace-packages": false
+  },
+  "scripts": {
+    "test": "echo 'No tests defined' && exit 0",
+    "test:e2e": "echo 'No e2e tests defined' && exit 0"
+  }
+}

package/project.json

@@ -0,0 +1,17 @@
+{
+  "name": "@descope-ui/descope-tooltip",
+  "$schema": "../../node_modules/nx/schemas/project-schema.json",
+  "sourceRoot": "packages/web-components/components/descope-tooltip/src",
+  "projectType": "library",
+  "targets": {
+    "version": {
+      "executor": "@jscutlery/semver:version",
+      "options": {
+        "trackDeps": true,
+        "push": false,
+        "preset": "conventional"
+      }
+    }
+  },
+  "tags": []
+}

package/src/component/TooltipClass.js

@@ -0,0 +1,219 @@
+import {
+  componentNameValidationMixin,
+  portalMixin,
+} from '@descope-ui/common/components-mixins';
+import { compose } from '@descope-ui/common/utils';
+import {
+  forwardAttrs,
+  getComponentName,
+} from '@descope-ui/common/components-helpers';
+import { createBaseClass } from '@descope-ui/common/base-classes';
+import { EnrichedTextClass } from '@descope-ui/descope-enriched-text/class';
+
+export const componentName = getComponentName('tooltip');
+
+const tooltipAttrs = [
+  'text',
+  'position',
+  'hide-delay',
+  'hover-delay',
+  'opened',
+];
+
+const BaseClass = createBaseClass({
+  componentName,
+  baseSelector: 'vaadin-tooltip',
+});
+
+class RawTooltip extends BaseClass {
+  static get observedAttributes() {
+    return tooltipAttrs.concat(BaseClass.observedAttributes || []);
+  }
+
+  get isOpened() {
+    return this.getAttribute('opened') === 'true';
+  }
+
+  get overlay() {
+    return this.tooltip?._overlayElement;
+  }
+
+  get overlayContentNode() {
+    return this.overlay?.shadowRoot.querySelector('[part="content"]');
+  }
+
+  get tooltipText() {
+    return this.getAttribute('text')?.trim() || '';
+  }
+
+  init() {
+    super.init();
+
+    // Create the vaadin-tooltip here instead of constructor (for React compatibility)
+    this.style.display = 'contents';
+    this.insertAdjacentHTML('beforeend', '<vaadin-tooltip></vaadin-tooltip>');
+    this.tooltip = this.querySelector('vaadin-tooltip');
+
+    this.tooltip.style.width = '0';
+    this.tooltip.style.height = '0';
+    this.tooltip.style.display = 'block';
+    this.tooltip.style.overflow = 'hidden';
+    this.tooltip.style.position = 'absolute';
+
+    this.#setTooltipTarget();
+
+    setTimeout(() => this.#onOverlayReady());
+  }
+
+  #onOverlayReady() {
+    this.#initTooltipTextComponent();
+    this.#overrideAttachOverlay();
+
+    forwardAttrs(this, this.tooltip, {
+      includeAttrs: ['position', 'opened'],
+    });
+
+    this.#handleTooltipVisibility();
+  }
+
+  #setTooltipTarget() {
+    if (!this.children?.length) return;
+
+    let ele = Array.from(this.children).find(
+      (child) => child !== this.tooltip,
+    );
+
+    if (!ele) return;
+
+    this.tooltip.target = ele;
+  }
+
+  #clearOverlayContentNode() {
+    this.overlayContentNode.innerHTML = '';
+  }
+
+  #createEnrichedTextComponent() {
+    const enrichedText = document.createElement('descope-enriched-text');
+
+    enrichedText.setAttribute('link-target-blank', 'true');
+    enrichedText.textContent = this.tooltipText;
+
+    return enrichedText;
+  }
+
+  #initTooltipTextComponent() {
+    if (!this.overlayContentNode) return;
+
+    setTimeout(() => {
+      this.#clearOverlayContentNode();
+
+      this.textComponent = this.#createEnrichedTextComponent();
+
+      this.overlayContentNode.appendChild(this.textComponent);
+
+      forwardAttrs(this, this.textComponent, {
+        includeAttrs: ['readonly'],
+      });
+    });
+  }
+
+  // the default vaadin behavior is to attach the overlay to the body when opened
+  // we do not want that because it's difficult to style the overlay in this way
+  // so we override it to open inside the shadow DOM
+  #overrideAttachOverlay() {
+    if (!this.overlay) return;
+
+    if (this.isOpened) {
+      // When `opened` attr is used, vaadin doesn't execute `_attachOverlay`,
+      // and the overlay element is rendered outside the component, on the top
+      // level. We need to move it back to the local component's DOM.
+      setTimeout(() => this.tooltip.shadowRoot.appendChild(this.overlay));
+    } else {
+      this.overlay._detachOverlay = () => {};
+
+      this.overlay._attachOverlay = () =>
+        this.tooltip.shadowRoot.appendChild(this.overlay);
+    }
+  }
+
+  #handleTooltipVisibility() {
+    // This is Vaadin's API for manual control of tooltip visibility
+    this.tooltip?.toggleAttribute('manual', this.isOpened);
+  }
+
+  #updateText(value) {
+    if (!this.textComponent) return;
+    this.textComponent.textContent = value?.trim();
+  }
+
+  attributeChangedCallback(attrName, oldValue, newValue) {
+    super.attributeChangedCallback?.(attrName, oldValue, newValue);
+
+    if (oldValue !== newValue) {
+      if (attrName === 'text') {
+        this.#updateText(newValue);
+      }
+
+      if (attrName === 'opened') {
+        this.#handleTooltipVisibility(attrName, newValue)
+      }
+    }
+  }
+}
+
+const { overlay, content } = {
+  overlay: { selector: () => 'vaadin-tooltip-overlay::part(overlay)' },
+  content: { selector: () => 'vaadin-tooltip-overlay::part(content)' },
+};
+
+/**
+ * This component has no Shadow DOM of its own, so we can't add styles to it
+ * (otherwise it would affect the rest of the DOM).
+ * Note that all styles are within PortalMixin.
+ */
+export const TooltipClass = compose(
+  componentNameValidationMixin,
+  portalMixin({
+    selector: '',
+    mappings: {
+      fontFamily: {
+        ...content,
+        property: EnrichedTextClass.cssVarList.fontFamilyOverride,
+      },
+      fontSize: {
+        ...content,
+        property: EnrichedTextClass.cssVarList.fontSizeOverride,
+      },
+      fontWeight: {
+        ...content,
+        property: EnrichedTextClass.cssVarList.fontWeightOverride,
+      },
+      textColor: {
+        ...content,
+        property: EnrichedTextClass.cssVarList.textColorOverride,
+      },
+      hostDirection: {
+        ...content,
+        property: EnrichedTextClass.cssVarList.hostDirectionOverride,
+      },
+      backgroundColor: [{ ...overlay }, { ...content }],
+      borderColor: { ...overlay },
+      borderStyle: { ...overlay },
+      borderWidth: { ...overlay },
+      borderRadius: { ...overlay },
+      boxShadow: { ...overlay },
+      horizontalPadding: [
+        { ...content, property: 'padding-left' },
+        { ...content, property: 'padding-right' },
+      ],
+      verticalPadding: [
+        { ...content, property: 'padding-top' },
+        { ...content, property: 'padding-bottom' },
+      ],
+    },
+    forward: {
+      attributes: ['style'],
+      include: false,
+    },
+  }),
+)(RawTooltip);

package/src/component/index.js

@@ -0,0 +1,7 @@
+import '@descope-ui/descope-enriched-text';
+import '@vaadin/tooltip';
+import { componentName, TooltipClass } from './TooltipClass';
+
+customElements.define(componentName, TooltipClass);
+
+export { TooltipClass, componentName };

package/src/theme.js

@@ -0,0 +1,25 @@
+import globals from '@descope-ui/theme-globals';
+import { getThemeRefs } from '@descope-ui/common/theme-helpers';
+import { TooltipClass } from './component/TooltipClass';
+
+const globalRefs = getThemeRefs(globals);
+const vars = TooltipClass.cssVarList;
+
+const tooltip = {
+  [vars.fontFamily]: globalRefs.fonts.font1.family,
+  [vars.fontSize]: globals.typography.body2.size,
+  [vars.fontWeight]: globals.typography.body2.weight,
+  [vars.textColor]: globalRefs.colors.surface.contrast,
+  [vars.hostDirection]: globalRefs.direction,
+  [vars.backgroundColor]: globalRefs.colors.surface.main,
+  [vars.borderColor]: globalRefs.colors.surface.light,
+  [vars.borderStyle]: 'solid',
+  [vars.borderWidth]: globalRefs.border.xs,
+  [vars.borderRadius]: globalRefs.radius.xs,
+  [vars.horizontalPadding]: globalRefs.spacing.md,
+  [vars.verticalPadding]: globalRefs.spacing.sm,
+  [vars.boxShadow]: globalRefs.shadow.wide.sm,
+};
+
+export default tooltip;
+export { vars };

package/stories/descope-tooltip.stories.js

@@ -0,0 +1,122 @@
+import { componentName } from '../src/component';
+import { directionControl } from '@descope-ui/common/sb-controls';
+
+const Template = ({
+  text,
+  position,
+  direction,
+  type,
+  textContent,
+  hoverDelay,
+  hideDelay,
+  opened,
+  readonly,
+}) => `
+    <descope-tooltip
+      text="${text || ''}"
+      position="${position || 'top'}"
+      hover-delay="${hoverDelay || 0}"
+      hide-delay="${hideDelay || 0}"
+      st-host-direction="${direction ?? ''}"
+      opened="${opened || false}"
+      readonly="${readonly || false}"
+    >
+      ${type === 'node' ? `<descope-button class="tooltip-anchor" size="md" variant="contained" mode="primary" full-width="true">Click</descope-button>` : ''}
+      ${type === 'text' ? `<span class="tooltip-anchor">${textContent}</span>` : ''}
+    </descope-tooltip>
+  `;
+
+export default {
+  component: componentName,
+  title: 'descope-tooltip',
+  decorators: [
+    (story) => {
+      return `
+      <style nonce="${window.DESCOPE_NONCE}">
+        .story-wrapper {
+          display: flex;
+          width: 100%;
+          align-items: center;
+          justify-content: center;
+        }
+        .content {
+          padding: 6em;
+          width: 300px;
+        }
+      </style>
+      <div class="story-wrapper">
+        <div class="content">
+        ${story()}
+        </div>
+      </div>
+    `;
+    },
+  ],
+  parameters: {
+    panelPosition: 'right',
+    controls: { expanded: true },
+  },
+  argTypes: {
+    ...directionControl,
+    type: {
+      name: 'Content Type',
+      control: { type: 'select' },
+      options: ['node', 'text'],
+    },
+    text: {
+      name: 'Tooltip Text',
+      control: { type: 'text' },
+    },
+    textContent: {
+      name: 'Text Content',
+      control: { type: 'text' },
+    },
+    position: {
+      name: 'Position',
+      control: { type: 'select' },
+      options: [
+        'top',
+        'top-start',
+        'top-end',
+        'bottom',
+        'bottom-start',
+        'bottom-end',
+        'start',
+        'start-top',
+        'start-bottom',
+        'end',
+        'end-top',
+        'end-bottom',
+      ],
+    },
+    hoverDelay: {
+      name: 'Hover Delay',
+      control: { type: 'number' },
+    },
+    hideDelay: {
+      name: 'Hide Delay',
+      control: { type: 'number' },
+    },
+    opened: {
+      name: 'Opened',
+      control: { type: 'boolean' },
+    },
+    readonly: {
+      name: 'readonly',
+      control: { type: 'boolean' },
+    },
+  },
+};
+
+export const Default = Template.bind({});
+
+Default.args = {
+  text: 'This is a [tooltip](http://descope.test) with **markdown** support!',
+  hoverDelay: 1,
+  hideDelay: 1,
+  opened: false,
+  readonly: false,
+  type: 'text',
+  textContent:
+    'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.',
+};