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

package/esm/overlay/mixins/with-overlay-aware.js

@@ -0,0 +1,152 @@
+/**
+ * @license
+ * Copyright 2023 Tyler Technologies, Inc. 
+ * License: Apache-2.0
+ */
+import { coerceBoolean } from '@tylertech/forge-core';
+import { coerceStringToArray } from '../../core/utils/utils';
+import { OVERLAY_CONSTANTS } from '../overlay-constants';
+/**
+ *
+ *
+ * @param base The base component to mix into.
+ * @returns The mixed-in base component.
+ */
+// eslint-disable-next-line @typescript-eslint/explicit-function-return-type
+export function WithOverlayAware(base) {
+    class OverlayAware extends base {
+        //
+        // Public members
+        //
+        get anchorElement() {
+            return this.overlayElement.anchorElement;
+        }
+        set anchorElement(value) {
+            this.overlayElement.anchorElement = value;
+        }
+        get anchor() {
+            return this.overlayElement.anchor;
+        }
+        set anchor(value) {
+            this.overlayElement.anchor = value;
+        }
+        get open() {
+            return this.overlayElement.open;
+        }
+        set open(value) {
+            this.overlayElement.open = value;
+        }
+        get inline() {
+            return this.overlayElement.inline;
+        }
+        set inline(value) {
+            this.overlayElement.inline = value;
+        }
+        get placement() {
+            return this.overlayElement.placement;
+        }
+        set placement(value) {
+            this.overlayElement.placement = value;
+        }
+        get positionStrategy() {
+            return this.overlayElement.positionStrategy;
+        }
+        set positionStrategy(value) {
+            this.overlayElement.positionStrategy = value;
+        }
+        get offset() {
+            return this.overlayElement.offset;
+        }
+        set offset(value) {
+            this.overlayElement.offset = value;
+        }
+        get shift() {
+            return this.overlayElement.shift;
+        }
+        set shift(value) {
+            this.overlayElement.shift = value;
+        }
+        get hide() {
+            return this.overlayElement.hide;
+        }
+        set hide(value) {
+            this.overlayElement.hide = value;
+        }
+        get persistent() {
+            return this.overlayElement.persistent;
+        }
+        set persistent(value) {
+            this.overlayElement.persistent = value;
+        }
+        get flip() {
+            return this.overlayElement.flip;
+        }
+        set flip(value) {
+            this.overlayElement.flip = value;
+        }
+        get boundary() {
+            return this.overlayElement.boundary;
+        }
+        set boundary(value) {
+            this.overlayElement.boundary = value;
+        }
+        get boundaryElement() {
+            return this.overlayElement.boundaryElement;
+        }
+        set boundaryElement(value) {
+            this.overlayElement.boundaryElement = value;
+        }
+        get fallbackPlacements() {
+            return this.overlayElement.fallbackPlacements;
+        }
+        set fallbackPlacements(value) {
+            this.overlayElement.fallbackPlacements = value;
+        }
+        //
+        // Public methods
+        //
+        position() {
+            this.overlayElement.position();
+        }
+        attributeChangedCallback(name, _oldValue, newValue) {
+            var _a;
+            (_a = super.attributeChangedCallback) === null || _a === void 0 ? void 0 : _a.call(this, name, _oldValue, newValue);
+            switch (name) {
+                case OVERLAY_CONSTANTS.observedAttributes.ANCHOR:
+                    this.anchor = newValue;
+                    break;
+                case OVERLAY_CONSTANTS.observedAttributes.OPEN:
+                    this.open = coerceBoolean(newValue);
+                    break;
+                case OVERLAY_CONSTANTS.observedAttributes.INLINE:
+                    this.inline = coerceBoolean(newValue);
+                    break;
+                case OVERLAY_CONSTANTS.observedAttributes.PLACEMENT:
+                    this.placement = newValue;
+                    break;
+                case OVERLAY_CONSTANTS.observedAttributes.POSITION_STRATEGY:
+                    this.positionStrategy = newValue;
+                    break;
+                case OVERLAY_CONSTANTS.observedAttributes.HIDE:
+                    this.hide = newValue;
+                    break;
+                case OVERLAY_CONSTANTS.observedAttributes.PERSISTENT:
+                    this.persistent = coerceBoolean(newValue);
+                    break;
+                case OVERLAY_CONSTANTS.observedAttributes.SHIFT:
+                    this.shift = coerceBoolean(newValue);
+                    break;
+                case OVERLAY_CONSTANTS.observedAttributes.FLIP:
+                    this.flip = newValue;
+                    break;
+                case OVERLAY_CONSTANTS.observedAttributes.BOUNDARY:
+                    this.boundary = newValue;
+                    break;
+                case OVERLAY_CONSTANTS.observedAttributes.FALLBACK_PLACEMENTS:
+                    this.fallbackPlacements = (newValue === null || newValue === void 0 ? void 0 : newValue.trim()) ? coerceStringToArray(newValue) : null;
+                    break;
+            }
+        }
+    }
+    return OverlayAware;
+}

package/esm/overlay/overlay-adapter.d.ts

@@ -0,0 +1,54 @@
+/**
+ * @license
+ * Copyright 2023 Tyler Technologies, Inc. 
+ * License: Apache-2.0
+ */
+import { BaseAdapter, IBaseAdapter } from '../core/base/base-adapter';
+import { PositionPlacement, VirtualElement } from '../core/utils/position-utils';
+import { IOverlayComponent } from './overlay';
+import { IOverlayOffset, OverlayFlipState, OverlayHideState, OverlayLightDismissReason, OverlayPositionStrategy } from './overlay-constants';
+export interface IOverlayAdapter extends IBaseAdapter {
+    show(): void;
+    hide(): void;
+    tryHideDescendantOverlays(): void;
+    locateAnchorElement(id: string | null): HTMLElement | null;
+    isMostRecentOpenOverlay(): boolean;
+    positionElement(config: IPositionElementConfig): void;
+    tryCleanupAutoUpdate(): void;
+    addLightDismissListener(listener: (reason: OverlayLightDismissReason) => void): void;
+    removeLightDismissListener(): void;
+}
+export interface IPositionElementConfig {
+    anchorElement: HTMLElement | VirtualElement;
+    strategy: OverlayPositionStrategy;
+    placement: PositionPlacement;
+    auto: boolean;
+    hide: OverlayHideState;
+    offset: IOverlayOffset;
+    shift: boolean;
+    flip: OverlayFlipState;
+    boundary: string | null;
+    boundaryElement: HTMLElement | null;
+    fallbackPlacements: PositionPlacement[] | undefined;
+}
+export declare class OverlayAdapter extends BaseAdapter<IOverlayComponent> implements IOverlayAdapter {
+    private _rootElement;
+    private _autoUpdateCleanup?;
+    private _lightDismissController;
+    private _overlayStackAddTimeout?;
+    constructor(component: IOverlayComponent);
+    show(): Promise<void>;
+    hide(): void;
+    tryHideDescendantOverlays(): void;
+    locateAnchorElement(id: string | null): HTMLElement | null;
+    positionElement({ anchorElement, strategy, placement, auto, hide, offset, shift, flip, boundary, boundaryElement, fallbackPlacements }: IPositionElementConfig): void;
+    tryCleanupAutoUpdate(): void;
+    isMostRecentOpenOverlay(): boolean;
+    addLightDismissListener(listener: (reason: OverlayLightDismissReason) => void): void;
+    removeLightDismissListener(): void;
+    /**
+     * Finds all descendant overlays that are not persistent.
+     * @returns An array of descendant overlays.
+     */
+    private _findDescendantOverlays;
+}

package/esm/overlay/overlay-adapter.js

@@ -0,0 +1,182 @@
+/**
+ * @license
+ * Copyright 2023 Tyler Technologies, Inc. 
+ * License: Apache-2.0
+ */
+import { autoUpdate } from '@floating-ui/dom';
+import { getShadowElement } from '@tylertech/forge-core';
+import { BaseAdapter } from '../core/base/base-adapter';
+import { positionElementAsync, VirtualElement } from '../core/utils/position-utils';
+import { locateElementById } from '../core/utils/utils';
+import { OverlayComponent } from './overlay';
+import { overlayStack, OVERLAY_CONSTANTS, SUPPORTS_POPOVER } from './overlay-constants';
+export class OverlayAdapter extends BaseAdapter {
+    constructor(component) {
+        super(component);
+        this._lightDismissController = new AbortController();
+        this._rootElement = getShadowElement(component, OVERLAY_CONSTANTS.selectors.ROOT);
+    }
+    async show() {
+        if (!this._component.inline && SUPPORTS_POPOVER) {
+            this._rootElement.popover = 'manual';
+            this._rootElement.showPopover();
+        }
+        else {
+            this._rootElement.removeAttribute('popover');
+        }
+        OverlayComponent[overlayStack].add(this._component);
+    }
+    hide() {
+        var _a;
+        window.clearTimeout(this._overlayStackAddTimeout);
+        this.tryCleanupAutoUpdate();
+        if (SUPPORTS_POPOVER && this._rootElement.matches(':popover-open')) {
+            this._rootElement.hidePopover();
+            this._rootElement.removeAttribute('popover');
+        }
+        // Remove inline positioning styles
+        this._rootElement.style.removeProperty('top');
+        this._rootElement.style.removeProperty('left');
+        this._rootElement.style.removeProperty('display');
+        (_a = this._component.arrowElement) === null || _a === void 0 ? void 0 : _a.removeAttribute('style');
+        // Remove dynamic position attribute
+        this._component.removeAttribute(OVERLAY_CONSTANTS.attributes.POSITION_PLACEMENT);
+        OverlayComponent[overlayStack].delete(this._component);
+    }
+    tryHideDescendantOverlays() {
+        const descendantOverlays = this._findDescendantOverlays();
+        descendantOverlays
+            .filter(o => !o.persistent) // Ignore persistent overlays since those are manually controlled
+            .forEach(o => o.open = false);
+    }
+    locateAnchorElement(id) {
+        return locateElementById(this._component, id);
+    }
+    positionElement({ anchorElement, strategy, placement, auto, hide, offset, shift, flip, boundary, boundaryElement, fallbackPlacements }) {
+        var _a;
+        this.tryCleanupAutoUpdate();
+        const originalOffset = Object.assign({}, offset);
+        const boundaryEl = (_a = (boundaryElement ? boundaryElement : boundary ? this._component.closest(`#${boundary}`) : null)) !== null && _a !== void 0 ? _a : 'clippingAncestors';
+        this._autoUpdateCleanup = autoUpdate(anchorElement, this._rootElement, async () => {
+            const offsetOptions = Object.assign({}, originalOffset);
+            // If we have an arrow element and an offset, we need to adjust the current offset to account for the arrow length
+            if (this._component.arrowElement) {
+                const arrowOffset = this._component.arrowElementOffset || Math.sqrt(2 * this._component.arrowElement.offsetWidth ** 2) / 2; // Compute the hypotenuse length of the arrow element
+                if (offsetOptions.mainAxis == null) {
+                    offsetOptions.mainAxis = 0;
+                }
+                offsetOptions.mainAxis += arrowOffset;
+            }
+            const result = await positionElementAsync({
+                element: this._rootElement,
+                anchorElement,
+                strategy,
+                placement,
+                hide: hide !== 'never',
+                shift,
+                shiftOptions: {
+                    boundary: boundaryEl
+                },
+                auto,
+                autoOptions: {
+                    boundary: boundaryEl
+                },
+                flip: !auto && flip !== 'never',
+                flipOptions: {
+                    boundary: boundaryEl,
+                    fallbackAxisSideDirection: flip === 'auto' ? 'start' : undefined,
+                    fallbackPlacements,
+                    crossAxis: flip === 'cross' || flip === 'auto',
+                    mainAxis: flip === 'main' || flip === 'auto'
+                },
+                arrowElement: this._component.arrowElement,
+                topLayer: !this._component.inline && SUPPORTS_POPOVER,
+                offset: Boolean(offsetOptions),
+                offsetOptions,
+                transform: false
+            });
+            const side = result.placement.split('-')[0];
+            const staticSide = { top: 'bottom', right: 'left', bottom: 'top', left: 'right' }[side];
+            if (staticSide) {
+                // Update the dynamic position "side" via an attribute to allow for state-based position adjustments
+                this._component.setAttribute(OVERLAY_CONSTANTS.attributes.POSITION_PLACEMENT, result.placement);
+            }
+            // Position the optional arrow element
+            if (this._component.arrowElement && result.arrow) {
+                const { x: arrowX, y: arrowY } = result.arrow;
+                const arrowLen = this._component.arrowElement.offsetWidth;
+                const { borderWidth = '0' } = getComputedStyle(this._component.arrowElement);
+                const arrowBoxAdjust = parseFloat(borderWidth);
+                Object.assign(this._component.arrowElement.style, {
+                    top: arrowY != null ? `${arrowY}px` : '',
+                    left: arrowX != null ? `${arrowX}px` : '',
+                    right: '',
+                    bottom: '',
+                    [staticSide]: `${(-arrowLen / 2) - arrowBoxAdjust}px`
+                });
+            }
+        });
+    }
+    tryCleanupAutoUpdate() {
+        var _a;
+        (_a = this._autoUpdateCleanup) === null || _a === void 0 ? void 0 : _a.call(this);
+        this._autoUpdateCleanup = undefined;
+    }
+    isMostRecentOpenOverlay() {
+        return Array.from(OverlayComponent[overlayStack]).at(-1) === this._component;
+    }
+    addLightDismissListener(listener) {
+        this.removeLightDismissListener();
+        // Listen for escape key globally
+        const escapeListener = (evt) => {
+            if (evt.key === 'Escape') {
+                if (this.isMostRecentOpenOverlay()) {
+                    evt.preventDefault();
+                    evt.stopPropagation();
+                    listener('escape');
+                }
+            }
+        };
+        this._component.ownerDocument.addEventListener('keydown', escapeListener, { signal: this._lightDismissController.signal });
+        // Listen for click-outside (any clicks not within our overlay surface or the anchor element)
+        const pointerupListener = (evt) => {
+            const composedPath = evt.composedPath();
+            const stack = Array.from(OverlayComponent[overlayStack]);
+            const stackIndex = stack.indexOf(this._component);
+            const isFromOverlayAboveUs = composedPath.some(el => el instanceof OverlayComponent && stack.indexOf(el) > stackIndex);
+            const isRightClick = evt.button === 2;
+            // We ignore light dismiss events if the click originated from an overlay that is higher in the
+            // stack than us, or if the click was a right-click (potential context menu)
+            if (isFromOverlayAboveUs || isRightClick) {
+                return;
+            }
+            const isWithinAnchor = this._component.anchorElement instanceof VirtualElement ? false : this._component.anchorElement && composedPath.includes(this._component.anchorElement);
+            const isWithinOverlay = composedPath.includes(this._rootElement);
+            if (!isWithinAnchor && !isWithinOverlay) {
+                listener('click');
+            }
+        };
+        this._component.ownerDocument.addEventListener('pointerup', pointerupListener, { capture: true, signal: this._lightDismissController.signal });
+    }
+    removeLightDismissListener() {
+        this._lightDismissController.abort();
+        this._lightDismissController = new AbortController();
+    }
+    /**
+     * Finds all descendant overlays that are not persistent.
+     * @returns An array of descendant overlays.
+     */
+    _findDescendantOverlays() {
+        const allOverlays = Array.from(OverlayComponent[overlayStack]);
+        const overlaysAboveUs = allOverlays.slice(allOverlays.indexOf(this._component) + 1).reverse();
+        const descendantOverlays = [];
+        if (overlaysAboveUs.length) {
+            // Dispatch an event on each overlay after us to see if it is a descendant of our overlay
+            const listener = evt => descendantOverlays.push(evt.target);
+            this._component.addEventListener(OVERLAY_CONSTANTS.events.DESCENDANT_TEST, listener);
+            overlaysAboveUs.forEach(o => o.dispatchEvent(new CustomEvent(OVERLAY_CONSTANTS.events.DESCENDANT_TEST, { bubbles: true, composed: true })));
+            this._component.removeEventListener(OVERLAY_CONSTANTS.events.DESCENDANT_TEST, listener);
+        }
+        return descendantOverlays;
+    }
+}

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

@@ -0,0 +1,71 @@
+/**
+ * @license
+ * Copyright 2023 Tyler Technologies, Inc. 
+ * License: Apache-2.0
+ */
+import { PositionPlacement } from '../core/utils/position-utils';
+export declare const OVERLAY_CONSTANTS: {
+    elementName: "forge-overlay";
+    observedAttributes: {
+        readonly ANCHOR: "anchor";
+        readonly NO_ANCHOR: "no-anchor";
+        readonly OPEN: "open";
+        readonly INLINE: "inline";
+        readonly PLACEMENT: "placement";
+        readonly POSITION_STRATEGY: "position-strategy";
+        readonly HIDE: "hide";
+        readonly PERSISTENT: "persistent";
+        readonly SHIFT: "shift";
+        readonly FLIP: "flip";
+        readonly BOUNDARY: "boundary";
+        readonly FALLBACK_PLACEMENTS: "fallback-placements";
+    };
+    attributes: {
+        readonly POSITION_PLACEMENT: "position-placement";
+        readonly ANCHOR: "anchor";
+        readonly NO_ANCHOR: "no-anchor";
+        readonly OPEN: "open";
+        readonly INLINE: "inline";
+        readonly PLACEMENT: "placement";
+        readonly POSITION_STRATEGY: "position-strategy";
+        readonly HIDE: "hide";
+        readonly PERSISTENT: "persistent";
+        readonly SHIFT: "shift";
+        readonly FLIP: "flip";
+        readonly BOUNDARY: "boundary";
+        readonly FALLBACK_PLACEMENTS: "fallback-placements";
+    };
+    classes: {
+        readonly OVERLAY: "forge-overlay";
+    };
+    selectors: {
+        readonly ROOT: ".forge-overlay";
+    };
+    events: {
+        readonly LIGHT_DISMISS: "forge-overlay-light-dismiss";
+        readonly DESCENDANT_TEST: "forge-overlay-descendant-test";
+    };
+    defaults: {
+        readonly HIDE: "anchor-hidden";
+        readonly FLIP: "auto";
+    };
+};
+export declare const SUPPORTS_POPOVER: boolean;
+export interface IOverlayOffset {
+    mainAxis?: number;
+    crossAxis?: number;
+    alignmentAxis?: number;
+}
+export type OverlayPositionStrategy = 'absolute' | 'fixed';
+export type OverlayPlacement = PositionPlacement | 'auto';
+export type OverlayHideState = 'anchor-hidden' | 'never';
+export type OverlayFlipState = 'auto' | 'main' | 'cross' | 'never';
+export type OverlayLightDismissReason = 'click' | 'escape';
+export interface IOverlayToggleEvent extends Event {
+    newState: 'closed' | 'open';
+    oldState: 'closed' | 'open';
+}
+export interface OverlayLightDismissEventData {
+    reason: OverlayLightDismissReason;
+}
+export declare const overlayStack: unique symbol;

package/esm/overlay/overlay-constants.js

@@ -0,0 +1,48 @@
+/**
+ * @license
+ * Copyright 2023 Tyler Technologies, Inc. 
+ * License: Apache-2.0
+ */
+import { COMPONENT_NAME_PREFIX } from '../constants';
+import { supportsPopover } from '../core';
+const elementName = `${COMPONENT_NAME_PREFIX}overlay`;
+const observedAttributes = {
+    ANCHOR: 'anchor',
+    NO_ANCHOR: 'no-anchor',
+    OPEN: 'open',
+    INLINE: 'inline',
+    PLACEMENT: 'placement',
+    POSITION_STRATEGY: 'position-strategy',
+    HIDE: 'hide',
+    PERSISTENT: 'persistent',
+    SHIFT: 'shift',
+    FLIP: 'flip',
+    BOUNDARY: 'boundary',
+    FALLBACK_PLACEMENTS: 'fallback-placements'
+};
+const attributes = Object.assign(Object.assign({}, observedAttributes), { POSITION_PLACEMENT: 'position-placement' });
+const classes = {
+    OVERLAY: 'forge-overlay'
+};
+const selectors = {
+    ROOT: `.${classes.OVERLAY}`
+};
+const events = {
+    LIGHT_DISMISS: `${elementName}-light-dismiss`,
+    DESCENDANT_TEST: `${elementName}-descendant-test`
+};
+const defaults = {
+    HIDE: 'anchor-hidden',
+    FLIP: 'auto'
+};
+export const OVERLAY_CONSTANTS = {
+    elementName,
+    observedAttributes,
+    attributes,
+    classes,
+    selectors,
+    events,
+    defaults
+};
+export const SUPPORTS_POPOVER = supportsPopover();
+export const overlayStack = Symbol('overlayStack');

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

@@ -0,0 +1,76 @@
+/**
+ * @license
+ * Copyright 2023 Tyler Technologies, Inc. 
+ * License: Apache-2.0
+ */
+import { PositionPlacement } from '../core/utils/position-utils';
+import { IBaseOverlayFoundation, BaseOverlayFoundation } from './base/base-overlay-foundation';
+import { IOverlayAdapter } from './overlay-adapter';
+import { IOverlayOffset, OverlayPlacement, OverlayPositionStrategy, OverlayFlipState, OverlayHideState } from './overlay-constants';
+export interface IOverlayFoundation extends IBaseOverlayFoundation {
+    arrowElement: HTMLElement;
+    arrowElementOffset: number;
+}
+export declare class OverlayFoundation extends BaseOverlayFoundation<IOverlayAdapter> implements IOverlayFoundation {
+    private _anchorElement;
+    private _anchor;
+    private _noAnchor;
+    private _open;
+    private _inline;
+    private _placement;
+    private _positionStrategy;
+    private _offset;
+    private _shift;
+    private _hide;
+    private _flip;
+    private _boundary;
+    private _boundaryElement;
+    private _fallbackPlacements;
+    private _persistent;
+    private _arrowElement;
+    private _arrowElementOffset;
+    private _lightDismissListener;
+    constructor(adapter: IOverlayAdapter);
+    initialize(): void;
+    destroy(): void;
+    position(): void;
+    private _onLightDismiss;
+    protected _applyOpen(value: boolean): void;
+    private _showOverlay;
+    private _hideOverlay;
+    private _applyLightDismissListener;
+    get anchorElement(): HTMLElement | null;
+    set anchorElement(value: HTMLElement | null);
+    get anchor(): string | null;
+    set anchor(value: string | null);
+    get noAnchor(): boolean;
+    set noAnchor(value: boolean);
+    get open(): boolean;
+    set open(value: boolean);
+    get arrowElement(): HTMLElement;
+    set arrowElement(value: HTMLElement);
+    get arrowElementOffset(): number;
+    set arrowElementOffset(value: number);
+    get inline(): boolean;
+    set inline(value: boolean);
+    get placement(): OverlayPlacement;
+    set placement(value: OverlayPlacement);
+    get positionStrategy(): OverlayPositionStrategy;
+    set positionStrategy(value: OverlayPositionStrategy);
+    get offset(): IOverlayOffset;
+    set offset(value: IOverlayOffset);
+    get shift(): boolean;
+    set shift(value: boolean);
+    get hide(): OverlayHideState;
+    set hide(value: OverlayHideState);
+    get persistent(): boolean;
+    set persistent(value: boolean);
+    get flip(): OverlayFlipState;
+    set flip(value: OverlayFlipState);
+    get boundary(): string | null;
+    set boundary(value: string | null);
+    get boundaryElement(): HTMLElement | null;
+    set boundaryElement(value: HTMLElement | null);
+    get fallbackPlacements(): PositionPlacement[] | null;
+    set fallbackPlacements(value: PositionPlacement[] | null);
+}