Merge branch 'aahmedov/add-tooltip-web-components' into rkaraivanov/tooltip

Author: Zneeky

src/animations/presets/scale/index.ts

@@ -0,0 +1,18 @@
+import { EaseOut } from '../../easings.js';
+import { animation } from '../../types.js';
+
+const baseOptions: KeyframeAnimationOptions = {
+  duration: 350,
+  easing: EaseOut.Quad,
+};
+
+const scaleInCenter = (options = baseOptions) =>
+  animation(
+    [
+      { transform: 'scale(0)', opacity: 0 },
+      { transform: 'scale(1)', opacity: 1 },
+    ],
+    options
+  );
+
+export { scaleInCenter };

src/components/tooltip/tooltip-event-controller.ts

@@ -33,11 +33,11 @@ class TooltipController implements ReactiveController {
     this.remove(anchor);
 
     for (const trigger of show) {
-      anchor.addEventListener(trigger, this._host.show);
+      anchor.addEventListener(trigger, this._host[showOnTrigger]);
     }
 
     for (const trigger of hide) {
-      anchor.addEventListener(trigger, this._host[hideOnTrigger]);
+      anchor.addEventListener(trigger, (ev) => this._host[hideOnTrigger](ev));
     }
   }
 
@@ -48,7 +48,7 @@ class TooltipController implements ReactiveController {
     }
 
     for (const trigger of this._showTriggers) {
-      anchor.removeEventListener(trigger, this._host.show);
+      anchor.removeEventListener(trigger, this._host[showOnTrigger]);
     }
 
     for (const trigger of this._hideTriggers) {
@@ -58,17 +58,18 @@ class TooltipController implements ReactiveController {
 
   /** @internal */
   public hostConnected(): void {
-    this._host.addEventListener('pointerenter', this._host.show);
+    this._host.addEventListener('pointerenter', this._host[showOnTrigger]);
     this._host.addEventListener('pointerleave', this._host[hideOnTrigger]);
   }
 
   /** @internal */
   public hostDisconnected(): void {
-    this._host.removeEventListener('pointerenter', this._host.show);
+    this._host.removeEventListener('pointerenter', this._host[showOnTrigger]);
     this._host.removeEventListener('pointerleave', this._host[hideOnTrigger]);
   }
 }
 
+export const showOnTrigger = Symbol();
 export const hideOnTrigger = Symbol();
 
 export function addTooltipController(

src/components/tooltip/tooltip.ts

@@ -1,20 +1,30 @@
 import { LitElement, html, nothing } from 'lit';
 import { property, query } from 'lit/decorators.js';
 import { type Ref, createRef, ref } from 'lit/directives/ref.js';
+import { EaseOut } from '../../animations/easings.js';
 import { addAnimationController } from '../../animations/player.js';
-import { fadeIn, fadeOut } from '../../animations/presets/fade/index.js';
+import { fadeOut } from '../../animations/presets/fade/index.js';
+import { scaleInCenter } from '../../animations/presets/scale/index.js';
 import { watch } from '../common/decorators/watch.js';
 import { registerComponent } from '../common/definitions/register.js';
+import type { Constructor } from '../common/mixins/constructor.js';
+import { EventEmitterMixin } from '../common/mixins/event-emitter.js';
 import { getElementByIdFromRoot, isString } from '../common/util.js';
 import IgcPopoverComponent, { type IgcPlacement } from '../popover/popover.js';
 import { styles } from './themes/tooltip.base.css.js';
 import {
   addTooltipController,
   hideOnTrigger,
+  showOnTrigger,
 } from './tooltip-event-controller.js';
 import service from './tooltip-service.js';
 
-// TODO: Expose events
+export interface IgcTooltipComponentEventMap {
+  igcOpening: CustomEvent<Element | null>;
+  igcOpened: CustomEvent<Element | null>;
+  igcClosing: CustomEvent<Element | null>;
+  igcClosed: CustomEvent<Element | null>;
+}
 
 function parseTriggers(string: string): string[] {
   return (string ?? '').split(',').map((part) => part.trim());
@@ -24,11 +34,19 @@ function parseTriggers(string: string): string[] {
  * @element igc-tooltip
  *
  * @slot - default slot
+ *
+ * @fires igcOpening - Emitted before the tooltip begins to open. Can be canceled to prevent opening.
+ * @fires igcOpened - Emitted after the tooltip has successfully opened and is visible.
+ * @fires igcClosing - Emitted before the tooltip begins to close. Can be canceled to prevent closing.
+ * @fires igcClosed - Emitted after the tooltip has been fully removed from view.
  */
-export default class IgcTooltipComponent extends LitElement {
+export default class IgcTooltipComponent extends EventEmitterMixin<
+  IgcTooltipComponentEventMap,
+  Constructor<LitElement>
+>(LitElement) {
   public static readonly tagName = 'igc-tooltip';
 
-  public static override styles = styles;
+  public static styles = styles;
 
   /* blazorSuppress */
   public static register() {
@@ -40,10 +58,14 @@ export default class IgcTooltipComponent extends LitElement {
   private _containerRef: Ref<HTMLElement> = createRef();
   private _animationPlayer = addAnimationController(this, this._containerRef);
 
-  private _autoHideTimeout?: number;
+  private _timeoutId?: number;
+  private _toBeShown = false;
+  private _toBeHidden = false;
   private _open = false;
   private _showTriggers = ['pointerenter'];
   private _hideTriggers = ['pointerleave'];
+  private _showDelay = 500;
+  private _hideDelay = 500;
 
   @query('#arrow')
   protected _arrowElement!: HTMLElement;
@@ -133,19 +155,57 @@ export default class IgcTooltipComponent extends LitElement {
     this._hideTriggers = parseTriggers(value);
     this._controller.set(this._target, {
       show: this._showTriggers,
-      hide: this._showTriggers,
+      hide: this._hideTriggers,
     });
   }
 
   public get hideTriggers(): string {
     return this._hideTriggers.join();
   }
 
+  /**
+   * Specifies the number of milliseconds that should pass before showing the tooltip.
+   *
+   * @attr show-delay
+   */
+  @property({ attribute: 'show-delay', type: Number })
+  public set showDelay(value: number) {
+    this._showDelay = Math.max(0, value);
+  }
+
+  public get showDelay(): number {
+    return this._showDelay;
+  }
+
+  /**
+   * Specifies the number of milliseconds that should pass before hiding the tooltip.
+   *
+   * @attr hide-delay
+   */
+  @property({ attribute: 'hide-delay', type: Number })
+  public set hideDelay(value: number) {
+    this._hideDelay = Math.max(0, value);
+  }
+
+  public get hideDelay(): number {
+    return this._hideDelay;
+  }
+
+  /**
+   * Specifies a plain text as tooltip content.
+   *
+   * @attr
+   */
+  @property({ type: String })
+  public message = '';
+
   constructor() {
     super();
 
     this._internals = this.attachInternals();
     this._internals.role = 'tooltip';
+    this._internals.ariaAtomic = 'true';
+    this._internals.ariaLive = 'polite';
   }
 
   protected override async firstUpdated() {
@@ -189,40 +249,124 @@ export default class IgcTooltipComponent extends LitElement {
   }
 
   private async _toggleAnimation(dir: 'open' | 'close') {
-    const animation = dir === 'open' ? fadeIn : fadeOut;
-    return this._animationPlayer.playExclusive(animation());
+    const animation =
+      dir === 'open'
+        ? scaleInCenter({ duration: 150, easing: EaseOut.Quad })
+        : fadeOut({ duration: 75, easing: EaseOut.Sine });
+    return this._animationPlayer.playExclusive(animation);
+  }
+
+  /**
+   * Immediately stops any ongoing animation and resets the tooltip state.
+   *
+   * This method is used in edge cases when a transition needs to be forcefully interrupted,
+   * such as when a tooltip is in the middle of showing or hiding and the user suddenly
+   * triggers the opposite action (e.g., hovers in and out rapidly).
+   *
+   * It:
+   * - Reverts `open` based on whether it was mid-hide or mid-show.
+   * - Clears internal transition flags (`_toBeShown`, `_toBeHidden`).
+   * - Stops any active animations, causing `_toggleAnimation()` to return false.
+   *
+   */
+  private async _forceAnimationStop() {
+    this.open = this._toBeHidden;
+    this._toBeShown = false;
+    this._toBeHidden = false;
+    this._animationPlayer.stopAll();
+  }
+
+  private _setDelay(ms: number): Promise<void> {
+    clearTimeout(this._timeoutId);
+    return new Promise((resolve) => {
+      this._timeoutId = setTimeout(resolve, ms);
+    });
   }
 
   /** Shows the tooltip if not already showing. */
-  public show = async () => {
-    clearTimeout(this._autoHideTimeout);
-    if (this.open) {
-      return false;
-    }
+  public show = async (): Promise<boolean> => {
+    if (this.open) return false;
+
+    await this._setDelay(this.showDelay);
 
     this.open = true;
-    return await this._toggleAnimation('open');
+    this._toBeShown = true;
+    const result = await this._toggleAnimation('open');
+    this._toBeShown = false;
+
+    return result;
   };
 
   /** Hides the tooltip if not already hidden. */
-  public hide = async () => {
-    if (!this.open) {
-      return false;
+  public hide = async (): Promise<boolean> => {
+    if (!this.open) return false;
+
+    await this._setDelay(this.hideDelay);
+
+    this._toBeHidden = true;
+    const result = await this._toggleAnimation('close');
+    this.open = !result;
+    this._toBeHidden = false;
+
+    return result;
+  };
+
+  /** Toggles the tooltip between shown/hidden state after the appropriate delay. */
+  public toggle = async (): Promise<boolean> => {
+    return this.open ? this.hide() : this.show();
+  };
+
+  public showWithEvent = async () => {
+    if (this._toBeHidden) {
+      await this._forceAnimationStop();
+      return;
+    }
+    if (
+      this.open ||
+      !this.emitEvent('igcOpening', { cancelable: true, detail: this._target })
+    ) {
+      return;
+    }
+    if (await this.show()) {
+      this.emitEvent('igcOpened', { detail: this._target });
+    }
+  };
+
+  public hideWithEvent = async () => {
+    if (this._toBeShown) {
+      await this._forceAnimationStop();
+      return;
+    }
+    if (
+      !this.open ||
+      !this.emitEvent('igcClosing', { cancelable: true, detail: this._target })
+    ) {
+      return;
+    }
+    if (await this.hide()) {
+      this.emitEvent('igcClosed', { detail: this._target });
     }
+  };
 
-    await this._toggleAnimation('close');
-    this.open = false;
-    clearTimeout(this._autoHideTimeout);
-    return true;
+  protected [showOnTrigger] = () => {
+    clearTimeout(this._timeoutId);
+    this.showWithEvent();
   };
 
-  protected [hideOnTrigger] = () => {
-    this._autoHideTimeout = setTimeout(() => this.hide(), 180);
+  protected [hideOnTrigger] = (ev: Event) => {
+    const related = (ev as PointerEvent).relatedTarget as Node | null;
+    // If the pointer moved into the tooltip element, don't hide
+    if (related && (this.contains(related) || this._target?.contains(related)))
+      return;
+
+    clearTimeout(this._timeoutId);
+    this._timeoutId = setTimeout(() => this.hideWithEvent(), 180);
   };
 
   protected override render() {
     return html`
       <igc-popover
+        aria-hidden=${!this.open}
         .placement=${this.placement}
         .offset=${this.offset}
         .anchor=${this._target}
@@ -233,7 +377,7 @@ export default class IgcTooltipComponent extends LitElement {
         shift
       >
         <div ${ref(this._containerRef)} part="base">
-          <slot></slot>
+          ${this.message ? html`${this.message}` : html`<slot></slot>`}
           ${this.disableArrow ? nothing : html`<div id="arrow"></div>`}
         </div>
       </igc-popover>

stories/tooltip.stories.ts

@@ -189,6 +189,8 @@ export const Basic: Story = {
 
     <igc-input label="Password" required minlength="12"></igc-input>
     <igc-tooltip
+      .showDelay=${args.showDelay}
+      .hideDelay=${args.hideDelay}
       placement="bottom-end"
       offset="-4"
       disable-arrow
@@ -286,3 +288,38 @@ export const Triggers: Story = {
     </igc-tooltip>
   `,
 };
+
+export const Toggle: Story = {
+  render: () => {
+    // Use a template ref id to target the tooltip instance
+    const tooltipId = 'toggle-tooltip';
+    const buttonId = 'toggle-button';
+    const buttonIdToggler = 'toggler-button';
+
+    // Hook into the rendered DOM to attach click listener
+    setTimeout(() => {
+      const tooltip = document.getElementById(tooltipId) as IgcTooltipComponent;
+      const button = document.getElementById(
+        buttonIdToggler
+      ) as HTMLButtonElement;
+
+      if (tooltip && button) {
+        button.addEventListener('click', () => tooltip.toggle());
+      }
+    });
+
+    return html`
+      <igc-button id=${buttonIdToggler}>Toggle</igc-button>
+      <igc-button id=${buttonId}>Toggle Tooltip</igc-button>
+      <igc-tooltip
+        id=${tooltipId}
+        placement="bottom"
+        show-delay="500"
+        hide-delay="500"
+        message="Simple tooltip content"
+      >
+        This tooltip toggles on button click!
+      </igc-tooltip>
+    `;
+  },
+};