@tylertech/forge 3.0.0-next.15 → 3.0.0-next.16

package/esm/tooltip/tooltip-adapter.js

@@ -3,125 +3,133 @@
  * Copyright 2023 Tyler Technologies, Inc. 
  * License: Apache-2.0
  */
-import { removeAllChildren, removeElement, matchesSelectors } from '@tylertech/forge-core';
+import { getShadowElement, randomChars } from '@tylertech/forge-core';
+import { setDefaultAria } from '../constants';
+import { locateElementById } from '../core/utils/utils';
 import { BaseAdapter } from '../core/base/base-adapter';
-import { attachTooltip } from './tooltip-utils';
-/**
- * The DOM adapter for the tooltip component.
- */
+import { OVERLAY_CONSTANTS } from '../overlay';
+import { TOOLTIP_CONSTANTS } from './tooltip-constants';
 export class TooltipAdapter extends BaseAdapter {
     constructor(component) {
         super(component);
-        this._tooltipElement = null;
-    }
-    initializeTargetElement(selector) {
-        this._targetElement = this._getTargetElement(selector);
+        this._anchorElement = null;
+        this._overlayElement = null;
+        this._contentElement = getShadowElement(this._component, TOOLTIP_CONSTANTS.selectors.CONTENT);
+        this._arrowElement = getShadowElement(this._component, TOOLTIP_CONSTANTS.selectors.ARROW);
+    }
+    get anchorElement() {
+        return this._anchorElement;
+    }
+    syncAria() {
+        const role = this._component.type === 'description' ? 'tooltip' : null;
+        this._component[setDefaultAria]({ role });
+        this._component[setDefaultAria]({ ariaHidden: 'true' }, { setAttribute: !this._component.hasAttribute('aria-hidden') });
+        if (this._anchorElement) {
+            if (this._component.type === 'label' && this._anchorElement.hasAttribute('aria-labelledby')) {
+                return;
+            }
+            if (this._component.type === 'description' && this._anchorElement.hasAttribute('aria-describedby')) {
+                return;
+            }
+            if (!this._component.hasAttribute('id') && this._component.type !== 'presentation') {
+                this._component.id = `forge-tooltip-${randomChars()}`;
+            }
+            switch (this._component.type) {
+                case 'description':
+                    this._anchorElement.setAttribute('aria-describedby', this._component.id);
+                    break;
+                case 'label':
+                    this._anchorElement.setAttribute('aria-labelledby', this._component.id);
+                    break;
+            }
+        }
     }
-    initializeAccessibility(identifier) {
-        if (this._targetElement && !this._targetElement.hasAttribute('aria-describedby')) {
-            this._targetElement.setAttribute('aria-describedby', identifier);
+    detachAria() {
+        var _a, _b, _c, _d;
+        if (this._component.type === 'description' && ((_a = this._anchorElement) === null || _a === void 0 ? void 0 : _a.getAttribute('aria-describedby')) === this._component.id) {
+            (_b = this._anchorElement) === null || _b === void 0 ? void 0 : _b.removeAttribute('aria-describedby');
+        }
+        if (this._component.type === 'label' && ((_c = this._anchorElement) === null || _c === void 0 ? void 0 : _c.getAttribute('aria-labelledby')) === this._component.id) {
+            (_d = this._anchorElement) === null || _d === void 0 ? void 0 : _d.removeAttribute('aria-labelledby');
         }
     }
-    hasTargetElement() {
-        return !!this._targetElement;
+    setAnchorElement(element) {
+        this._anchorElement = element;
     }
-    hasTooltipElement() {
-        return !!this._tooltipElement;
+    tryLocateAnchorElement(id) {
+        this._anchorElement = this._tryFindAnchorElement(id);
     }
-    isTargetElementConnected() {
-        return !!this._targetElement && this._targetElement.isConnected;
+    addAnchorListener(type, listener, opts) {
+        var _a;
+        (_a = this._anchorElement) === null || _a === void 0 ? void 0 : _a.addEventListener(type, listener, opts);
     }
-    destroy(identifier) {
-        if (this._targetElement && this._targetElement.getAttribute('aria-describedby') === identifier) {
-            this._targetElement.removeAttribute('aria-describedby');
-        }
+    removeAnchorListener(type, listener) {
+        var _a;
+        (_a = this._anchorElement) === null || _a === void 0 ? void 0 : _a.removeEventListener(type, listener);
     }
-    /**
-     * Sets the text content of the host element to the provided text.
-     * @param text The text content.
-     */
-    setTextContent(text) {
-        removeAllChildren(this._component);
-        if (text) {
-            this._component.appendChild(document.createTextNode(text));
-        }
+    addLightDismissListener(listener) {
+        var _a;
+        (_a = this._overlayElement) === null || _a === void 0 ? void 0 : _a.addEventListener(OVERLAY_CONSTANTS.events.LIGHT_DISMISS, listener);
     }
-    /**
-     * Adds an event listener to the target element.
-     * @param targetElement The target element instance.
-     * @param type The event type.
-     * @param listener The event listener.
-     */
-    addTargetEventListener(type, listener) {
-        if (this._targetElement) {
-            this._targetElement.addEventListener(type, listener);
-        }
+    removeLightDismissListener(listener) {
+        var _a;
+        (_a = this._overlayElement) === null || _a === void 0 ? void 0 : _a.removeEventListener(OVERLAY_CONSTANTS.events.LIGHT_DISMISS, listener);
     }
-    /**
-     * Removes an event listener from the target element.
-     * @param type The event type.
-     * @param listener The event listener.
-     */
-    removeTargetEventListener(type, listener) {
-        if (this._targetElement) {
-            this._targetElement.removeEventListener(type, listener);
+    show() {
+        var _a;
+        // Tooltips are shown above all content via <forge-overlay>
+        // We do this by dynamically creating an overlay element and appending it to the shadow root
+        // then we move the tooltip content into the overlay element so that it can be presented.
+        if (!this._overlayElement) {
+            this._overlayElement = document.createElement(OVERLAY_CONSTANTS.elementName);
+            this._overlayElement.setAttribute('part', 'root:overlay');
         }
-    }
-    /**
-     * Displays the tooltip around the target element based on the provided configuration.
-     * @param position The position.
-     * @param content The tooltip content.
-     */
-    showTooltip(position, content) {
-        if (!this._targetElement) {
-            return;
+        this._overlayElement.placement = this._component.placement;
+        this._overlayElement.anchorElement = this._anchorElement;
+        this._overlayElement.arrowElement = this._arrowElement;
+        this._overlayElement.offset = { mainAxis: this._component.offset };
+        this._overlayElement.flip = this._component.flip;
+        if (this._component.fallbackPlacements) {
+            this._overlayElement.fallbackPlacements = this._component.fallbackPlacements;
         }
-        if (!content) {
-            const child = this._getTooltipContent();
-            content = child.cloneNode(true);
+        if (this._component.boundaryElement) {
+            this._overlayElement.boundaryElement = this._component.boundaryElement;
         }
-        const isEmptyTextNode = content.nodeType === 3 && (!content.textContent || content.textContent.trim().length === 0);
-        const isEmptyNode = !content || isEmptyTextNode;
-        if (isEmptyNode) {
-            return;
+        else if (this._component.boundary) {
+            const boundaryEl = locateElementById(this._component, this._component.boundary);
+            this._overlayElement.boundaryElement = boundaryEl;
         }
-        this._tooltipElement = attachTooltip(this._targetElement, position, content);
-    }
-    getInnerText() {
-        return this._component.innerText;
-    }
-    /**
-     * Removes the tooltip from the DOM.
-     * @param tooltipElement The target element instance.
-     */
-    hideTooltip() {
-        if (this._tooltipElement) {
-            removeElement(this._tooltipElement);
-            this._tooltipElement = null;
+        else {
+            this._overlayElement.boundaryElement = null;
         }
-    }
-    getTooltipElement() {
-        return this._tooltipElement;
+        (_a = this._component.shadowRoot) === null || _a === void 0 ? void 0 : _a.appendChild(this._overlayElement);
+        this._overlayElement.appendChild(this._contentElement);
+        this._overlayElement.open = true;
+    }
+    hide() {
+        var _a, _b;
+        // Move the tooltip content back into the component, and remove the overlay element to hide the tooltip visually
+        // Tooltips are still accessible when hidden, so we don't need to do anything else.
+        if (this._overlayElement) {
+            this._overlayElement.open = false;
+        }
+        (_a = this._component.shadowRoot) === null || _a === void 0 ? void 0 : _a.appendChild(this._contentElement);
+        (_b = this._overlayElement) === null || _b === void 0 ? void 0 : _b.remove();
     }
     /**
-     * Gets the target element based on the provided CSS selector.
-     * @param {string | undefined} selector The target element selector.
+     * Attempts to find an element with the given id. If no element is found, the previous sibling or parent element is returned.
+     *
+     * For backwards compatibility we allow for `id` to be a selector string, so that is evaluated if no element is found for the id.
      */
-    _getTargetElement(selector) {
-        if (selector) {
-            if (this._component.parentElement) {
-                if (matchesSelectors(this._component.parentElement, selector)) {
-                    return this._component.parentElement;
-                }
-                return this._component.parentElement.querySelector(selector);
+    _tryFindAnchorElement(id) {
+        var _a, _b;
+        if (id) {
+            const rootNode = this._component.getRootNode();
+            const targetEl = (_a = rootNode.getElementById(id)) !== null && _a !== void 0 ? _a : rootNode.querySelector(id);
+            if (targetEl) {
+                return targetEl;
             }
         }
-        else {
-            return (this._component.previousElementSibling || this._component.parentElement);
-        }
-        return null;
-    }
-    _getTooltipContent() {
-        return this._component.firstElementChild || this._component.firstChild || document.createTextNode('');
+        return ((_b = this._component.previousElementSibling) !== null && _b !== void 0 ? _b : this._component.parentElement);
     }
 }

package/esm/tooltip/tooltip-constants.d.ts

@@ -3,33 +3,56 @@
  * Copyright 2023 Tyler Technologies, Inc. 
  * License: Apache-2.0
  */
+import { PositionPlacement } from '../core/utils/position-utils';
+import { OverlayFlipState } from '../overlay/overlay-constants';
 export declare const TOOLTIP_CONSTANTS: {
     elementName: "forge-tooltip";
-    attributes: {
-        TEXT: string;
-        TARGET: string;
-        DELAY: string;
-        POSITION: string;
-        HOST: string;
-    };
-    classes: {
-        TOOLTIP: string;
-        TOOLTIP_OPEN: string;
-        TOOLTIP_TOP: string;
-        TOOLTIP_RIGHT: string;
-        TOOLTIP_BOTTOM: string;
-        TOOLTIP_LEFT: string;
+    observedAttributes: {
+        readonly ID: "id";
+        readonly OPEN: "open";
+        readonly TYPE: "type";
+        readonly ANCHOR: "anchor";
+        readonly TARGET: "target";
+        readonly PLACEMENT: "placement";
+        readonly POSITION: "position";
+        readonly DELAY: "delay";
+        readonly OFFSET: "offset";
+        readonly FLIP: "flip";
+        readonly BOUNDARY: "boundary";
+        readonly FALLBACK_PLACEMENTS: "fallback-placements";
+        readonly TRIGGER_TYPE: "trigger-type";
     };
-    selectors: {
-        HOST: string;
+    attributes: {
+        readonly ID: "id";
+        readonly OPEN: "open";
+        readonly TYPE: "type";
+        readonly ANCHOR: "anchor";
+        readonly TARGET: "target";
+        readonly PLACEMENT: "placement";
+        readonly POSITION: "position";
+        readonly DELAY: "delay";
+        readonly OFFSET: "offset";
+        readonly FLIP: "flip";
+        readonly BOUNDARY: "boundary";
+        readonly FALLBACK_PLACEMENTS: "fallback-placements";
+        readonly TRIGGER_TYPE: "trigger-type";
     };
     numbers: {
-        DEFAULT_DELAY: number;
-        LONGPRESS_THRESHOLD: number;
         LONGPRESS_VISIBILITY_DURATION: number;
     };
-    strings: {
-        DEFAULT_POSITION: string;
+    defaults: {
+        DELAY: number;
+        OFFSET: number;
+        FLIP: OverlayFlipState;
+        TYPE: TooltipType;
+        PLACEMENT: import("@floating-ui/utils").Placement;
+        TRIGGER_TYPES: TooltipTriggerType[];
+    };
+    selectors: {
+        readonly CONTENT: ".forge-tooltip";
+        readonly ARROW: ".arrow";
     };
 };
-export type TooltipBuilder = () => HTMLElement;
+export type TooltipType = 'presentation' | 'label' | 'description';
+export type TooltipPlacement = PositionPlacement;
+export type TooltipTriggerType = 'hover' | 'longpress' | 'focus';

package/esm/tooltip/tooltip-constants.js

@@ -5,37 +5,42 @@
  */
 import { COMPONENT_NAME_PREFIX } from '../constants';
 const elementName = `${COMPONENT_NAME_PREFIX}tooltip`;
-const attributes = {
-    TEXT: 'text',
+const observedAttributes = {
+    ID: 'id',
+    OPEN: 'open',
+    TYPE: 'type',
+    ANCHOR: 'anchor',
     TARGET: 'target',
-    DELAY: 'delay',
+    PLACEMENT: 'placement',
     POSITION: 'position',
-    HOST: 'forge-tooltip-host'
-};
-const classes = {
-    TOOLTIP: 'forge-tooltip',
-    TOOLTIP_OPEN: 'forge-tooltip--open',
-    TOOLTIP_TOP: 'forge-tooltip--top',
-    TOOLTIP_RIGHT: 'forge-tooltip--right',
-    TOOLTIP_BOTTOM: 'forge-tooltip--bottom',
-    TOOLTIP_LEFT: 'forge-tooltip--left'
-};
-const selectors = {
-    HOST: `[${attributes.HOST}]`
+    DELAY: 'delay',
+    OFFSET: 'offset',
+    FLIP: 'flip',
+    BOUNDARY: 'boundary',
+    FALLBACK_PLACEMENTS: 'fallback-placements',
+    TRIGGER_TYPE: 'trigger-type'
 };
+const attributes = Object.assign({}, observedAttributes);
 const numbers = {
-    DEFAULT_DELAY: 500,
-    LONGPRESS_THRESHOLD: 750,
     LONGPRESS_VISIBILITY_DURATION: 3000
 };
-const strings = {
-    DEFAULT_POSITION: 'right'
+const defaults = {
+    DELAY: 500,
+    OFFSET: 4,
+    FLIP: 'auto',
+    TYPE: 'presentation',
+    PLACEMENT: 'right',
+    TRIGGER_TYPES: ['hover']
+};
+const selectors = {
+    CONTENT: '.forge-tooltip',
+    ARROW: '.arrow'
 };
 export const TOOLTIP_CONSTANTS = {
     elementName,
+    observedAttributes,
     attributes,
-    classes,
-    selectors,
     numbers,
-    strings
+    defaults,
+    selectors
 };

package/esm/tooltip/tooltip-foundation.d.ts

@@ -5,101 +5,89 @@
  */
 import { ICustomElementFoundation } from '@tylertech/forge-core';
 import { ITooltipAdapter } from './tooltip-adapter';
-import { TooltipBuilder } from './tooltip-constants';
-import { PopupPlacement } from '../popup';
+import { TooltipPlacement, TooltipTriggerType, TooltipType } from './tooltip-constants';
+import { OverlayFlipState } from '../overlay/overlay-constants';
+import { PositionPlacement } from '../core/utils/position-utils';
 export interface ITooltipFoundation extends ICustomElementFoundation {
-    text: string;
-    builder: TooltipBuilder | undefined;
-    target: string;
-    delay: number;
-    position: PopupPlacement;
     open: boolean;
-    hide(): void;
-    tooltipElement: HTMLElement | null;
+    type: TooltipType;
+    placement: `${TooltipPlacement}`;
+    delay: number;
+    anchor: string;
+    anchorElement: HTMLElement | null;
+    offset: number;
+    flip: OverlayFlipState;
+    boundary: string | null;
+    boundaryElement: HTMLElement | null;
+    fallbackPlacements: PositionPlacement[] | null;
+    triggerType: TooltipTriggerType | TooltipTriggerType[];
+    syncTooltipAria(): void;
 }
-/**
- * The foundation class behind the tooltip component.
- */
-export declare class TooltipFoundation implements ITooltipFoundation {
+declare const BaseClass: import("../constants").AbstractConstructor<import("../core/mixins/interactions/longpress/with-longpress-listener").WithLongpressListenerContract> & import("../constants").MixinBase<object>;
+export declare class TooltipFoundation extends BaseClass implements ITooltipFoundation {
     private _adapter;
-    private static _tooltipIdentifier;
-    private _identifier;
-    private _text;
-    private _builder;
-    private _target;
+    private _open;
+    private _type;
+    private _anchor;
     private _delay;
-    private _position;
-    private _mouseOverTimeout;
-    private _isOpen;
-    private _touchTimeout;
-    private _mouseOverListener;
-    private _mouseOutListener;
-    private _touchStartListener;
-    private _touchEndListener;
+    private _placement;
+    private _offset;
+    private _flip;
+    private _boundary;
+    private _boundaryElement;
+    private _fallbackPlacements;
+    private _triggerTypes;
+    private _hoverStartListener;
+    private _hoverEndListener;
+    private _hoverTimeout;
+    private _focusListener;
+    private _blurListener;
+    private _longpressVisibilityTimeout;
     private _scrollListener;
-    private _clickListener;
     private _mouseDownListener;
     private _dragListener;
+    private _lightDismissListener;
     constructor(_adapter: ITooltipAdapter);
     initialize(): void;
-    disconnect(): void;
-    /**
-     * Generates the next available tooltip identifier.
-     */
-    private _getNextIdentifier;
-    /** Adds event listeners to the target element. */
-    private _addTargetListeners;
-    /**
-     * Removes the event listeners from the target element.
-     * @param targetElement The target element instance.
-     */
-    private _removeTargetListeners;
-    /**
-     * Handles the touchstart event on the target element to detect long press.
-     */
-    private _onTouchStart;
-    /**
-     * Handles the touchend event on the target element to cancel a long press action.
-     */
-    private _onTouchEnd;
-    private _clearTouchTimer;
-    /**
-     * Handles the mouseover event on the target element.
-     */
-    private _onMouseOver;
-    /**
-     * Handles the mouseout event on the target element.
-     */
-    private _onMouseOut;
-    /**
-     * Displays the tooltip.
-     */
+    destroy(): void;
+    syncTooltipAria(): void;
+    private _attachAnchorListeners;
+    private _detachAnchorListeners;
     private _show;
-    /**
-     * Hides the tooltip.
-     */
-    hide(): void;
-    /**
-     * Handles scrolling events when the tooltip is open.
-     */
-    private _onScroll;
-    private _targetInteracted;
-    /** Gets/sets the tooltip text. */
-    get text(): string;
-    set text(value: string);
-    /** Sets the tooltip builder function. */
-    get builder(): TooltipBuilder | undefined;
-    set builder(value: TooltipBuilder | undefined);
-    /** Gets/sets the target element CSS selector. */
-    get target(): string;
-    set target(value: string);
-    /** Gets/sets the interaction delay. */
+    private _hide;
+    private _attachDismissListeners;
+    private _detachDismissListeners;
+    private _onHoverStart;
+    private _onHoverEnd;
+    private _onFocus;
+    private _onBlur;
+    protected _onLongpress(): void;
+    protected _onLongpressEnd(evt: PointerEvent | TouchEvent): void;
+    private _onTryShow;
+    private _onTryHide;
+    get open(): boolean;
+    set open(value: boolean);
+    get type(): TooltipType;
+    set type(value: TooltipType);
+    get anchor(): string;
+    set anchor(value: string);
+    get anchorElement(): HTMLElement | null;
+    set anchorElement(element: HTMLElement | null);
     get delay(): number;
     set delay(value: number);
-    /** Gets/sets the tooltip position. */
-    get position(): PopupPlacement;
-    set position(value: PopupPlacement);
-    set open(value: boolean);
-    get open(): boolean;
-    get tooltipElement(): HTMLElement | null;
+    get placement(): TooltipPlacement;
+    set placement(value: TooltipPlacement);
+    get offset(): number;
+    set offset(value: number);
+    get flip(): OverlayFlipState;
+    set flip(value: OverlayFlipState);
+    get boundary(): string | null;
+    set boundary(value: string | null);
+    get boundaryElement(): HTMLElement | null;
+    set boundaryElement(element: HTMLElement | null);
+    get fallbackPlacements(): PositionPlacement[] | null;
+    set fallbackPlacements(value: PositionPlacement[] | null);
+    get triggerType(): TooltipTriggerType | TooltipTriggerType[];
+    set triggerType(value: TooltipTriggerType | TooltipTriggerType[]);
 }
+export {};