@digital-realty/ix-tooltip 1.0.1

package/src/IxTooltip.ts

@@ -0,0 +1,214 @@
+/* eslint-disable class-methods-use-this */
+import { html, LitElement, TemplateResult, nothing } from 'lit';
+import { property, state } from 'lit/decorators.js';
+import {
+  computePosition,
+  Strategy,
+  Placement,
+  autoUpdate,
+  autoPlacement,
+  AutoPlacementOptions,
+  offset,
+  OffsetOptions,
+} from '@floating-ui/dom';
+import './templates/ix-simple-tooltip.js';
+
+export class IxTooltip extends LitElement {
+  static _placement: Placement | undefined = undefined;
+
+  static _strategy: Strategy = 'fixed';
+
+  static _tagName: string = 'ix-tooltip';
+
+  static _offsetOptions: OffsetOptions = { mainAxis: 10 };
+
+  static _hidingDuration: number = 500; // milliseconds
+
+  static _showTooltip: string = 'show-tooltip';
+
+  static _hideTooltip: string = 'hide-tooltip';
+
+  // eslint-disable-next-line lit/no-native-attributes
+  @property({ type: String, reflect: true }) id: string = 'tooltip';
+
+  // eslint-disable-next-line lit/no-native-attributes
+  @property({ type: String, reflect: true }) role: string = 'tooltip';
+
+  @property({ type: String, reflect: true }) placement: Placement | undefined =
+    IxTooltip._placement;
+
+  @property({ type: String, reflect: true }) strategy: Strategy =
+    IxTooltip._strategy;
+
+  @state() tooltip: TemplateResult | undefined = undefined;
+
+  @state() target: HTMLElement | undefined = undefined;
+
+  @state() hidding: boolean = false;
+
+  autoPlacementOptions: AutoPlacementOptions | undefined = undefined;
+
+  offsetOptions: OffsetOptions = IxTooltip._offsetOptions;
+
+  hidingDuration: number = IxTooltip._hidingDuration;
+
+  hideTimeout: ReturnType<typeof setTimeout> | undefined = undefined;
+
+  cleanup: () => void = () => undefined;
+
+  connectedCallback(): void {
+    super.connectedCallback();
+    document.addEventListener(IxTooltip._showTooltip, this.show);
+    document.addEventListener(IxTooltip._hideTooltip, this.hide);
+    document.addEventListener('keydown', this.handleEscapeKey);
+    document.addEventListener('focusin', this.handleShow);
+    document.addEventListener('focusout', this.handleHide);
+    document.addEventListener('mouseover', this.handleShow);
+    document.addEventListener('mouseout', this.handleHide);
+  }
+
+  disconnectedCallback(): void {
+    super.disconnectedCallback();
+    document.removeEventListener(IxTooltip._showTooltip, this.show);
+    document.removeEventListener(IxTooltip._hideTooltip, this.hide);
+    document.removeEventListener('keydown', this.handleEscapeKey);
+    document.removeEventListener('focusin', this.handleShow);
+    document.removeEventListener('focusout', this.handleHide);
+    document.removeEventListener('mouseover', this.handleShow);
+    document.removeEventListener('mouseout', this.handleHide);
+    this.hide();
+  }
+
+  handleEscapeKey = (e: KeyboardEvent) => {
+    if (this.tooltip && e.key === 'Escape') {
+      this.hide();
+    }
+  };
+
+  handleShow = (e: Event) => {
+    const target = <HTMLElement>e.composedPath()[0]; // I hate the shadowDOM
+    const eventTarget = <HTMLElement>e.target;
+
+    if (
+      eventTarget &&
+      eventTarget.tagName === IxTooltip._tagName.toUpperCase()
+    ) {
+      clearTimeout(this.hideTimeout);
+    }
+
+    if (target && target.hasAttribute('data-tooltip')) {
+      this.clearHideTimeout();
+      document.dispatchEvent(
+        new CustomEvent('show-tooltip', {
+          detail: {
+            target: e.target,
+            tooltip: html`<ix-simple-tooltip
+              >${target.getAttribute('data-tooltip')}</ix-simple-tooltip
+            >`,
+            placement: target.getAttribute('data-tooltip-placement'),
+            strategy: target.getAttribute('data-tooltip-strategy'),
+          },
+        }),
+      );
+    }
+  };
+
+  clearHideTimeout() {
+    if (this.hideTimeout) {
+      this.hidding = false;
+      clearTimeout(this.hideTimeout);
+    }
+  }
+
+  handleHide = (e: Event) => {
+    if (
+      this.tooltip &&
+      ((e.type === 'focusout' && this.shadowRoot?.activeElement !== null) ||
+        e.type === 'mouseout')
+    ) {
+      this.clearHideTimeout();
+      this.hidding = true;
+      this.hideTimeout = setTimeout(() => {
+        this.hide();
+      }, this.hidingDuration);
+    }
+  };
+
+  show = (e: any) => {
+    const {
+      placement,
+      strategy,
+      target,
+      tooltip,
+      autoPlacementOptions,
+      offsetOptions,
+      hidingDuration,
+    } = e.detail;
+
+    this.target = target;
+    this.placement = placement || IxTooltip._placement;
+    this.strategy = strategy || IxTooltip._strategy;
+    this.tooltip = tooltip;
+    this.autoPlacementOptions = autoPlacementOptions;
+    this.offsetOptions = offsetOptions || IxTooltip._offsetOptions;
+    this.hidingDuration =
+      hidingDuration !== undefined ? hidingDuration : IxTooltip._hidingDuration;
+    this.cleanup = autoUpdate(target, this, this.updatePosition);
+    this.hidding = false;
+  };
+
+  hide = () => {
+    this.cleanup();
+    this.placement = IxTooltip._placement;
+    this.strategy = IxTooltip._strategy;
+    this.offsetOptions = IxTooltip._offsetOptions;
+    this.hidingDuration = IxTooltip._hidingDuration;
+    this.target = undefined;
+    this.autoPlacementOptions = undefined;
+    this.tooltip = undefined;
+    this.hidding = false;
+  };
+
+  getAutoPlacementOptions() {
+    const autoPlacementOptions = {
+      ...this.autoPlacementOptions,
+    };
+
+    if (this.placement) {
+      autoPlacementOptions.allowedPlacements = [this.placement];
+    }
+
+    return autoPlacementOptions;
+  }
+
+  updatePosition = () => {
+    if (this.target) {
+      computePosition(this.target, this, {
+        strategy: this.strategy,
+        placement: this.placement,
+        middleware: [
+          autoPlacement(this.getAutoPlacementOptions()),
+          offset(this.offsetOptions),
+        ],
+      }).then(({ x, y }) => {
+        Object.assign(this.style, {
+          left: `${x}px`,
+          top: `${y}px`,
+          position: this.strategy,
+        });
+      });
+    } else {
+      this.hide();
+    }
+  };
+
+  render() {
+    return html`<div
+      tabindex="0"
+      class="wrapper ${this.hidding ? 'hidding' : ''}"
+      style="transition:${this.hidingDuration}ms opacity;"
+    >
+      ${this.tooltip || nothing}
+    </div> `;
+  }
+}

package/src/index.ts

@@ -0,0 +1 @@
+export { IxTooltip } from './IxTooltip.js';

package/src/ix-tooltip.ts

@@ -0,0 +1,36 @@
+import { css } from 'lit';
+import { IxTooltip } from './IxTooltip.js';
+
+export class IxTooltipStyled extends IxTooltip {
+  /*
+   * Are you about to try and modify the width?
+   * Don't try and do it with CSS vars, you won't get very far because this element should not be deeply nested
+   * What you should do instead is add this middleware https://floating-ui.com/docs/size
+   */
+  static override styles = css`
+    :host {
+      position: fixed;
+      top: 0;
+      left: 0;
+      width: max-content;
+    }
+
+    .wrapper {
+      opacity: 1;
+
+      &:focus {
+        outline: 0;
+      }
+
+      &.hidding {
+        opacity: 0;
+      }
+
+      &:hover {
+        opacity: 1;
+      }
+    }
+  `;
+}
+
+window.customElements.define('ix-tooltip', IxTooltipStyled);

package/src/templates/ix-simple-tooltip.ts

@@ -0,0 +1,24 @@
+import { html, css, LitElement } from 'lit';
+
+export class IxSimpleTooltip extends LitElement {
+  static styles = css`
+    :host {
+      background: var(
+        --ix-simple-tooltip-background-color,
+        var(--md-sys-color-on-primary-container, #000)
+      );
+      border-radius: var(--ix-simple-tooltip-border-radius, 5px);
+      color: var(
+        --ix-simple-tooltip-text-color,
+        var(--md-sys-color-on-primary, #fff)
+      );
+      padding: var(--ix-simple-tooltip-padding, 0.3rem 0.5rem);
+    }
+  `;
+
+  render() {
+    return html` <slot></slot>`;
+  }
+}
+
+window.customElements.define('ix-simple-tooltip', IxSimpleTooltip);

package/test/ix-tooltip-test-harness.ts

@@ -0,0 +1,75 @@
+// eslint-disable-next-line max-classes-per-file
+import { html, LitElement, css } from 'lit';
+import '../src/ix-tooltip.js';
+
+class FancyTooltip extends LitElement {
+  static styles = css`
+    :host {
+      background: white;
+      border: 1px solid gray;
+      box-shadow: 0 0 6px black;
+      display: block;
+      padding: 4px;
+    }
+  `;
+
+  render() {
+    return html`<slot></slot>`;
+  }
+}
+
+window.customElements.define('fancy-tooltip', FancyTooltip);
+
+export class IxTooltipTestHarness extends LitElement {
+  protected createRenderRoot(): Element | ShadowRoot {
+    return this;
+  }
+
+  handleFancyMouseOver(e: Event) {
+    document.dispatchEvent(
+      new CustomEvent('show-tooltip', {
+        detail: {
+          target: e.target,
+          tooltip: html`<fancy-tooltip
+            ><h2>Some fancy title</h2>
+            <p>Some fancy description in a paragraph</p>
+            <br /><a href="#">Some fancy link</a></fancy-tooltip
+          >`,
+        },
+      }),
+    );
+  }
+
+  render() {
+    return html`
+      <a
+        href="#"
+        data-tooltip="tooltip text first element"
+        aria-describedby="tooltip"
+      >
+        first link element
+      </a>
+      <br />
+      <br />
+      <a
+        href="#"
+        data-tooltip="tooltip text second element"
+        aria-describedby="tooltip"
+      >
+        second link element
+      </a>
+      <br />
+      <br />
+      <a
+        href="#"
+        aria-describedby="tooltip"
+        @mouseover=${this.handleFancyMouseOver}
+      >
+        A more complicated tooltip
+      </a>
+      <ix-tooltip> </ix-tooltip>
+    `;
+  }
+}
+
+window.customElements.define('ix-tooltip-test-harness', IxTooltipTestHarness);

package/test/ix-tooltip.test.ts

@@ -0,0 +1,109 @@
+import { html } from 'lit';
+import { fixture, expect, aTimeout } from '@open-wc/testing';
+import { sendKeys, sendMouse, resetMouse } from '@web/test-runner-commands';
+import './ix-tooltip-test-harness.js';
+import type { IxTooltipTestHarness } from './ix-tooltip-test-harness.js';
+import { IxTooltip } from '../src/IxTooltip.js';
+
+function getMiddleOfElement(element: HTMLElement) {
+  const { x, y, width, height } = element.getBoundingClientRect();
+
+  return {
+    x: Math.floor(x + window.scrollX + width / 2),
+    y: Math.floor(y + window.scrollY + height / 2),
+  };
+}
+
+describe('IxTooltip', () => {
+  let harnessEl: IxTooltipTestHarness;
+  let tooltipEl: IxTooltip;
+
+  beforeEach(async () => {
+    harnessEl = await fixture<IxTooltipTestHarness>(html`
+      <ix-tooltip-test-harness></ix-tooltip-test-harness>
+    `);
+
+    tooltipEl = <IxTooltip>harnessEl.querySelector('ix-tooltip');
+  });
+
+  afterEach(async () => {
+    await resetMouse();
+  });
+
+  it('renders the test harness element and its DOM', async () => {
+    expect(harnessEl).to.exist;
+    expect(harnessEl.innerHTML).to.exist;
+  });
+
+  it('renders the tooltip and its shadowDOM', async () => {
+    expect(tooltipEl).to.exist;
+    expect(tooltipEl.shadowRoot).to.exist;
+  });
+
+  it('shows a tooltip on element tab focus, removes on esc', async () => {
+    harnessEl.focus();
+    await sendKeys({
+      press: 'Tab',
+    });
+
+    let toolTipText = document.activeElement?.getAttribute('data-tooltip');
+    expect(toolTipText).to.equal('tooltip text first element');
+    expect(
+      tooltipEl.shadowRoot?.querySelector('ix-simple-tooltip')?.innerHTML,
+    ).to.contain(toolTipText);
+
+    await sendKeys({
+      press: 'Tab',
+    });
+
+    toolTipText = document.activeElement?.getAttribute('data-tooltip');
+    expect(toolTipText).to.equal('tooltip text second element');
+    expect(
+      tooltipEl.shadowRoot?.querySelector('ix-simple-tooltip')?.innerHTML,
+    ).to.contain(toolTipText);
+
+    await sendKeys({
+      press: 'Escape',
+    });
+
+    expect(tooltipEl.shadowRoot?.querySelector('ix-simple-tooltip')).to.be.null;
+  });
+
+  it('shows a tooltip on element mouse over, remove on mouse out', async () => {
+    const triggerEls = harnessEl.querySelectorAll(
+      '[data-tooltip]',
+    ) as unknown as HTMLElement[];
+
+    let { x, y } = getMiddleOfElement(triggerEls[0]);
+    await sendMouse({ type: 'move', position: [x, y] });
+
+    let toolTipText = triggerEls[0].getAttribute('data-tooltip');
+    expect(toolTipText).to.equal('tooltip text first element');
+    expect(
+      tooltipEl.shadowRoot?.querySelector('ix-simple-tooltip')?.innerHTML,
+    ).to.contain(toolTipText);
+
+    ({ x, y } = getMiddleOfElement(triggerEls[1]));
+    await sendMouse({ type: 'move', position: [x, y] });
+
+    toolTipText = triggerEls[1].getAttribute('data-tooltip');
+    expect(toolTipText).to.equal('tooltip text second element');
+    expect(
+      tooltipEl.shadowRoot?.querySelector('ix-simple-tooltip')?.innerHTML,
+    ).to.contain(toolTipText);
+
+    await sendMouse({ type: 'move', position: [500, 500] });
+
+    expect(tooltipEl.shadowRoot?.querySelector('.wrapper')).to.have.class(
+      'hidding',
+    );
+
+    await aTimeout(500);
+
+    expect(tooltipEl.shadowRoot?.querySelector('.wrapper')).to.not.have.class(
+      'hidding',
+    );
+
+    expect(tooltipEl.shadowRoot?.querySelector('ix-simple-tooltip')).to.be.null;
+  });
+});

package/tsconfig.json

@@ -0,0 +1,22 @@
+{
+  "compilerOptions": {
+    "target": "es2021",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "noEmitOnError": true,
+    "lib": ["es2021", "dom", "DOM.Iterable"],
+    "strict": true,
+    "esModuleInterop": false,
+    "allowSyntheticDefaultImports": true,
+    "experimentalDecorators": true,
+    "importHelpers": true,
+    "outDir": "dist",
+    "sourceMap": true,
+    "inlineSources": true,
+    "rootDir": "./",
+    "declaration": true,
+    "incremental": true,
+    "skipLibCheck": true
+  },
+  "include": ["**/*.ts"]
+}

package/web-dev-server.config.js

@@ -0,0 +1,27 @@
+// import { hmrPlugin, presets } from '@open-wc/dev-server-hmr';
+
+/** Use Hot Module replacement by adding --hmr to the start command */
+const hmr = process.argv.includes('--hmr');
+
+export default /** @type {import('@web/dev-server').DevServerConfig} */ ({
+  open: '/demo/',
+  /** Use regular watch mode if HMR is not enabled. */
+  watch: !hmr,
+  /** Resolve bare module imports */
+  nodeResolve: {
+    exportConditions: ['browser', 'development'],
+  },
+
+  /** Compile JS for older browsers. Requires @web/dev-server-esbuild plugin */
+  // esbuildTarget: 'auto'
+
+  /** Set appIndex to enable SPA routing */
+  // appIndex: 'demo/index.html',
+
+  plugins: [
+    /** Use Hot Module Replacement by uncommenting. Requires @open-wc/dev-server-hmr plugin */
+    // hmr && hmrPlugin({ exclude: ['**/*/node_modules/**/*'], presets: [presets.lit] }),
+  ],
+
+  // See documentation for all available options
+});

package/web-test-runner.config.js

@@ -0,0 +1,41 @@
+import { playwrightLauncher } from '@web/test-runner-playwright';
+
+const filteredLogs = ['Running in dev mode', 'Lit is in dev mode'];
+
+export default /** @type {import("@web/test-runner").TestRunnerConfig} */ ({
+  /** Test files to run */
+  files: 'dist/test/**/*.test.js',
+
+  /** Resolve bare module imports */
+  nodeResolve: {
+    exportConditions: ['browser', 'development'],
+  },
+
+  /** Filter out lit dev mode logs */
+  filterBrowserLogs(log) {
+    for (const arg of log.args) {
+      if (typeof arg === 'string' && filteredLogs.some(l => arg.includes(l))) {
+        return false;
+      }
+    }
+    return true;
+  },
+
+  /** Compile JS for older browsers. Requires @web/dev-server-esbuild plugin */
+  // esbuildTarget: 'auto',
+
+  /** Amount of browsers to run concurrently */
+  // concurrentBrowsers: 2,
+
+  /** Amount of test files per browser to test concurrently */
+  // concurrency: 1,
+
+  /** Browsers to run tests on */
+   browsers: [
+     playwrightLauncher({ product: 'chromium' }),
+  //   playwrightLauncher({ product: 'firefox' }),
+  //   playwrightLauncher({ product: 'webkit' }),
+   ],
+
+  // See documentation for all available options
+});