@tylertech/forge 3.0.0-next.7 → 3.0.0-next.9

package/esm/state-layer/state-layer-constants.d.ts

@@ -0,0 +1,79 @@
+/**
+ * @license
+ * Copyright 2023 Tyler Technologies, Inc. 
+ * License: Apache-2.0
+ */
+export declare const STATE_LAYER_CONSTANTS: {
+    elementName: string;
+    attributes: {
+        TARGET: string;
+        DISABLED: string;
+    };
+    selectors: {
+        SURFACE: string;
+    };
+    classes: {
+        HOVERED: string;
+        PRESSED: string;
+    };
+};
+export declare class StateLayerCoords {
+    x: number;
+    y: number;
+    constructor(x: number, y: number);
+    static fromPointerEvent(event: PointerEvent): StateLayerCoords;
+}
+export declare const TOUCH_DELAY_MS = 150;
+export declare const PRESS_GROW_MS = 450;
+export declare const MINIMUM_PRESS_MS = 225;
+export declare const INITIAL_ORIGIN_SCALE = 0.2;
+export declare const PADDING = 10;
+export declare const SOFT_EDGE_MINIMUM_SIZE = 75;
+export declare const SOFT_EDGE_CONTAINER_RATIO = 0.35;
+export declare const PRESS_PSEUDO = "::after";
+export declare const ANIMATION_FILL = "forwards";
+export declare const EASING = "cubic-bezier(0.2, 0, 0, 1)";
+/**
+ * Interaction states for the state layer.
+ *
+ * On Touch:
+ *  - `INACTIVE -> TOUCH_DELAY -> WAITING_FOR_CLICK -> INACTIVE`
+ *  - `INACTIVE -> TOUCH_DELAY -> HOLDING -> WAITING_FOR_CLICK -> INACTIVE`
+ *
+ * On Mouse or Pen:
+ *   - `INACTIVE -> WAITING_FOR_CLICK -> INACTIVE`
+ */
+export declare enum PointerState {
+    /**
+     * Initial state of the control, no touch in progress.
+     *
+     * Transitions:
+     *   - on touch down: transition to `TOUCH_DELAY`.
+     *   - on mouse down: transition to `WAITING_FOR_CLICK`.
+     */
+    INACTIVE = 0,
+    /**
+     * Touch down has been received, waiting to determine if it's a swipe or
+     * scroll.
+     *
+     * Transitions:
+     *   - on touch up: begin press; transition to `WAITING_FOR_CLICK`.
+     *   - on cancel: transition to `INACTIVE`.
+     *   - after `TOUCH_DELAY_MS`: begin press; transition to `HOLDING`.
+     */
+    TOUCH_DELAY = 1,
+    /**
+     * A touch has been deemed to be a press
+     *
+     * Transitions:
+     *  - on up: transition to `WAITING_FOR_CLICK`.
+     */
+    HOLDING = 2,
+    /**
+     * The user touch has finished, transition into rest state.
+     *
+     * Transitions:
+     *   - on click end press; transition to `INACTIVE`.
+     */
+    WAITING_FOR_CLICK = 3
+}

package/esm/state-layer/state-layer-constants.js

@@ -0,0 +1,89 @@
+/**
+ * @license
+ * Copyright 2023 Tyler Technologies, Inc. 
+ * License: Apache-2.0
+ */
+import { COMPONENT_NAME_PREFIX } from '../constants';
+const elementName = `${COMPONENT_NAME_PREFIX}state-layer`;
+const observedAttributes = {
+    TARGET: 'target',
+    DISABLED: 'disabled'
+};
+const attributes = Object.assign({}, observedAttributes);
+const selectors = {
+    SURFACE: '.forge-state-layer'
+};
+const classes = {
+    HOVERED: 'forge-state-layer--hovered',
+    PRESSED: 'forge-state-layer--pressed'
+};
+export const STATE_LAYER_CONSTANTS = {
+    elementName,
+    attributes,
+    selectors,
+    classes
+};
+export class StateLayerCoords {
+    constructor(x, y) {
+        this.x = x;
+        this.y = y;
+    }
+    static fromPointerEvent(event) {
+        return new StateLayerCoords(event.pageX, event.pageY);
+    }
+}
+export const TOUCH_DELAY_MS = 150;
+export const PRESS_GROW_MS = 450;
+export const MINIMUM_PRESS_MS = 225;
+export const INITIAL_ORIGIN_SCALE = 0.2;
+export const PADDING = 10;
+export const SOFT_EDGE_MINIMUM_SIZE = 75;
+export const SOFT_EDGE_CONTAINER_RATIO = 0.35;
+export const PRESS_PSEUDO = '::after';
+export const ANIMATION_FILL = 'forwards';
+export const EASING = 'cubic-bezier(0.2, 0, 0, 1)';
+/**
+ * Interaction states for the state layer.
+ *
+ * On Touch:
+ *  - `INACTIVE -> TOUCH_DELAY -> WAITING_FOR_CLICK -> INACTIVE`
+ *  - `INACTIVE -> TOUCH_DELAY -> HOLDING -> WAITING_FOR_CLICK -> INACTIVE`
+ *
+ * On Mouse or Pen:
+ *   - `INACTIVE -> WAITING_FOR_CLICK -> INACTIVE`
+ */
+export var PointerState;
+(function (PointerState) {
+    /**
+     * Initial state of the control, no touch in progress.
+     *
+     * Transitions:
+     *   - on touch down: transition to `TOUCH_DELAY`.
+     *   - on mouse down: transition to `WAITING_FOR_CLICK`.
+     */
+    PointerState[PointerState["INACTIVE"] = 0] = "INACTIVE";
+    /**
+     * Touch down has been received, waiting to determine if it's a swipe or
+     * scroll.
+     *
+     * Transitions:
+     *   - on touch up: begin press; transition to `WAITING_FOR_CLICK`.
+     *   - on cancel: transition to `INACTIVE`.
+     *   - after `TOUCH_DELAY_MS`: begin press; transition to `HOLDING`.
+     */
+    PointerState[PointerState["TOUCH_DELAY"] = 1] = "TOUCH_DELAY";
+    /**
+     * A touch has been deemed to be a press
+     *
+     * Transitions:
+     *  - on up: transition to `WAITING_FOR_CLICK`.
+     */
+    PointerState[PointerState["HOLDING"] = 2] = "HOLDING";
+    /**
+     * The user touch has finished, transition into rest state.
+     *
+     * Transitions:
+     *   - on click end press; transition to `INACTIVE`.
+     */
+    PointerState[PointerState["WAITING_FOR_CLICK"] = 3] = "WAITING_FOR_CLICK";
+})(PointerState || (PointerState = {}));

package/esm/state-layer/state-layer-foundation.d.ts

@@ -0,0 +1,57 @@
+/**
+ * @license
+ * Copyright 2023 Tyler Technologies, Inc. 
+ * License: Apache-2.0
+ */
+import { ICustomElementFoundation } from '@tylertech/forge-core';
+import { IStateLayerAdapter } from './state-layer-adapter';
+import { StateLayerCoords } from './state-layer-constants';
+export interface IStateLayerFoundation extends ICustomElementFoundation {
+    targetElement: HTMLElement | null;
+    target: string | null;
+    disabled: boolean;
+    playAnimation(coords?: StateLayerCoords): void;
+}
+export declare class StateLayerFoundation implements IStateLayerFoundation {
+    private _adapter;
+    private _target;
+    private _disabled;
+    private _attached;
+    private _deferred;
+    private _pointerStartEvent;
+    private _pointerState;
+    private _checkBoundsAfterContextMenu;
+    private _pointerEnterListener;
+    private _pointerLeaveListener;
+    private _pointerDownListener;
+    private _pointerUpListener;
+    private _pointerCancelListener;
+    private _clickListener;
+    private _contextmenuListener;
+    constructor(_adapter: IStateLayerAdapter);
+    initialize(): void;
+    disconnect(): void;
+    playAnimation(coords?: StateLayerCoords): void;
+    private _deferInitialization;
+    private _applyListeners;
+    private _removeListeners;
+    private _onDeferredInitialize;
+    private _onPointerEnter;
+    private _onPointerLeave;
+    private _onPointerDown;
+    private _onPointerUp;
+    private _onClick;
+    private _onPointerCancel;
+    private _onContextmenu;
+    private _startAnimation;
+    private _endAnimation;
+    private _canHandleEvent;
+    private _isTouch;
+    get isAttached(): boolean;
+    get targetElement(): HTMLElement | null;
+    set targetElement(el: HTMLElement | null);
+    get target(): string | null;
+    set target(value: string | null);
+    get disabled(): boolean;
+    set disabled(value: boolean);
+}

package/esm/state-layer/state-layer-foundation.js

@@ -0,0 +1,237 @@
+/**
+ * @license
+ * Copyright 2023 Tyler Technologies, Inc. 
+ * License: Apache-2.0
+ */
+import { PointerState, StateLayerCoords, STATE_LAYER_CONSTANTS, TOUCH_DELAY_MS } from './state-layer-constants';
+export class StateLayerFoundation {
+    constructor(_adapter) {
+        this._adapter = _adapter;
+        // State
+        this._target = null;
+        this._disabled = false;
+        this._attached = false;
+        this._deferred = true;
+        this._pointerState = PointerState.INACTIVE;
+        this._checkBoundsAfterContextMenu = false;
+        this._pointerEnterListener = (evt) => this._onPointerEnter(evt);
+        this._pointerLeaveListener = (evt) => this._onPointerLeave(evt);
+        this._pointerDownListener = (evt) => this._onPointerDown(evt);
+        this._pointerUpListener = (evt) => this._onPointerUp(evt);
+        this._pointerCancelListener = (evt) => this._onPointerCancel(evt);
+        this._clickListener = () => this._onClick();
+        this._contextmenuListener = () => this._onContextmenu();
+    }
+    initialize() {
+        this._adapter.trySetTarget(this._target);
+        // We defer initialization until the first pointerenter event is received.
+        //
+        // This is a performance optimization to avoid attaching many listeners to the target element
+        // until the user is first interacting with it.
+        this._deferInitialization();
+    }
+    disconnect() {
+        this._pointerStartEvent = undefined;
+        this._pointerState = PointerState.INACTIVE;
+        this._adapter.setHovered(false);
+        this._adapter.setPressed(false);
+        this._adapter.destroy();
+        this._removeListeners();
+    }
+    playAnimation(coords) {
+        this._adapter.startAnimation(coords);
+        this._endAnimation();
+    }
+    _deferInitialization() {
+        this._adapter.deferInitialization(this._onDeferredInitialize.bind(this));
+    }
+    _applyListeners() {
+        if (this._disabled) {
+            return;
+        }
+        this._adapter.addTargetListener('pointerenter', this._pointerEnterListener);
+        this._adapter.addTargetListener('pointerleave', this._pointerLeaveListener);
+        this._adapter.addTargetListener('pointerdown', this._pointerDownListener);
+        this._adapter.addTargetListener('pointerup', this._pointerUpListener);
+        this._adapter.addTargetListener('pointercancel', this._pointerCancelListener);
+        this._adapter.addTargetListener('click', this._clickListener);
+        this._adapter.addTargetListener('contextmenu', this._contextmenuListener);
+        this._attached = true;
+    }
+    _removeListeners() {
+        this._adapter.removeTargetListener('pointerenter', this._pointerEnterListener);
+        this._adapter.removeTargetListener('pointerleave', this._pointerLeaveListener);
+        this._adapter.removeTargetListener('pointerdown', this._pointerDownListener);
+        this._adapter.removeTargetListener('pointerup', this._pointerUpListener);
+        this._adapter.removeTargetListener('pointercancel', this._pointerCancelListener);
+        this._adapter.removeTargetListener('click', this._clickListener);
+        this._adapter.removeTargetListener('contextmenu', this._contextmenuListener);
+        this._attached = false;
+    }
+    _onDeferredInitialize(evt) {
+        this._applyListeners();
+        if ((evt === null || evt === void 0 ? void 0 : evt.type) === 'pointerenter') {
+            // Manually trigger the pointerenter listener since this is in response to a pointerenter event already
+            this._pointerEnterListener(evt);
+        }
+        this._deferred = false;
+    }
+    _onPointerEnter(evt) {
+        if (!this._canHandleEvent(evt)) {
+            return;
+        }
+        this._adapter.setHovered(true);
+    }
+    _onPointerLeave(evt) {
+        if (!this._canHandleEvent(evt)) {
+            return;
+        }
+        this._adapter.setHovered(false);
+        if (this._pointerState !== PointerState.INACTIVE) {
+            this._adapter.endAnimation();
+        }
+    }
+    async _onPointerDown(evt) {
+        this._pointerStartEvent = evt;
+        if (!this._canHandleEvent(evt)) {
+            return;
+        }
+        if (!this._isTouch(evt.pointerType)) {
+            this._pointerState = PointerState.WAITING_FOR_CLICK;
+            this._startAnimation(evt);
+            return;
+        }
+        // after a longpress contextmenu event, an extra `pointerdown` can be
+        // dispatched to the pressed element. Check that the down is within
+        // bounds of the element in this case.
+        if (this._checkBoundsAfterContextMenu && !this._adapter.inBounds(evt.x, evt.y)) {
+            return;
+        }
+        this._checkBoundsAfterContextMenu = false;
+        this._pointerState = PointerState.TOUCH_DELAY;
+        await new Promise(resolve => setTimeout(resolve, TOUCH_DELAY_MS));
+        if (this._pointerState !== PointerState.TOUCH_DELAY) {
+            return;
+        }
+        this._pointerState = PointerState.HOLDING;
+        this._startAnimation(evt);
+    }
+    _onPointerUp(evt) {
+        if (!this._canHandleEvent(evt)) {
+            return;
+        }
+        if (this._pointerState === PointerState.HOLDING) {
+            this._pointerState = PointerState.WAITING_FOR_CLICK;
+            return;
+        }
+        if (this._pointerState === PointerState.TOUCH_DELAY) {
+            this._pointerState = PointerState.WAITING_FOR_CLICK;
+            this._startAnimation(this._pointerStartEvent);
+            return;
+        }
+    }
+    _onClick() {
+        if (this._disabled) {
+            return;
+        }
+        if (this._pointerState === PointerState.WAITING_FOR_CLICK) {
+            this._endAnimation();
+            return;
+        }
+        if (this._pointerState === PointerState.INACTIVE) {
+            this._startAnimation(this._pointerStartEvent);
+            this._endAnimation();
+        }
+    }
+    _onPointerCancel(evt) {
+        if (!this._canHandleEvent(evt)) {
+            return;
+        }
+        this._endAnimation();
+    }
+    _onContextmenu() {
+        if (this._disabled) {
+            return;
+        }
+        this._checkBoundsAfterContextMenu = true;
+        this._adapter.endAnimation();
+    }
+    _startAnimation(evt) {
+        const coords = evt ? StateLayerCoords.fromPointerEvent(evt) : undefined;
+        this._adapter.startAnimation(coords);
+    }
+    _endAnimation() {
+        this._pointerState = PointerState.INACTIVE;
+        this._adapter.endAnimation();
+        this._pointerStartEvent = undefined;
+    }
+    _canHandleEvent({ type, isPrimary, buttons, pointerType, pointerId }) {
+        if (this._disabled || !isPrimary) {
+            return false;
+        }
+        if (this._pointerStartEvent && this._pointerStartEvent.pointerId !== pointerId) {
+            return false;
+        }
+        if (type === 'pointerenter' || type === 'pointerleave') {
+            return !this._isTouch(pointerType);
+        }
+        const isPrimaryButton = buttons === 1;
+        return this._isTouch(pointerType) || isPrimaryButton;
+    }
+    _isTouch(pointerType) {
+        return pointerType === 'touch';
+    }
+    get isAttached() {
+        return this._attached;
+    }
+    get targetElement() {
+        return this._adapter.getTargetElement();
+    }
+    set targetElement(el) {
+        // Always remove the listeners from the previous target element
+        if (this._attached) {
+            this._removeListeners();
+        }
+        this._adapter.setTargetElement(el);
+        // If we are not already deferring attaching the listeners, then do that now
+        if (!this._deferred) {
+            this._deferInitialization();
+        }
+    }
+    get target() {
+        return this._adapter.getHostAttribute(STATE_LAYER_CONSTANTS.attributes.TARGET);
+    }
+    set target(value) {
+        if (this._target !== value) {
+            this._target = value;
+            if (this._adapter.isConnected) {
+                if (this._attached) {
+                    this._removeListeners();
+                }
+                this._adapter.trySetTarget(value);
+                if (!this._deferred) {
+                    this._deferInitialization();
+                }
+            }
+            this._adapter.toggleHostAttribute(STATE_LAYER_CONSTANTS.attributes.TARGET, Boolean(this._target), this._target);
+        }
+    }
+    get disabled() {
+        return this._disabled;
+    }
+    set disabled(value) {
+        value = Boolean(value);
+        if (this._disabled !== value) {
+            this._disabled = value;
+            if (this._adapter.isConnected) {
+                if (this._disabled) {
+                    this._removeListeners();
+                }
+                else if (!this._deferred) {
+                    this._deferInitialization();
+                }
+            }
+            this._adapter.toggleHostAttribute(STATE_LAYER_CONSTANTS.attributes.DISABLED, this._disabled);
+        }
+    }
+}

package/esm/state-layer/state-layer-utils.d.ts

@@ -0,0 +1,26 @@
+/**
+ * @license
+ * Copyright 2023 Tyler Technologies, Inc. 
+ * License: Apache-2.0
+ */
+import { StateLayerCoords } from './state-layer-constants';
+export declare function calcRippleSize(hostEl: HTMLElement): {
+    rippleScale: string;
+    rippleSize: string;
+    initialSize: number;
+};
+export declare function getTranslationCoordinates(hostEl: HTMLElement, initialSize: number, coords?: StateLayerCoords): {
+    startPoint: {
+        x: number;
+        y: number;
+    };
+    endPoint: {
+        x: number;
+        y: number;
+    };
+};
+export declare function toNormalizedCoords(hostEl: HTMLElement, coords: StateLayerCoords): {
+    x: number;
+    y: number;
+};
+export declare function isInBounds(hostEl: HTMLElement, x: number, y: number): boolean;

package/esm/state-layer/state-layer-utils.js

@@ -0,0 +1,54 @@
+/**
+ * @license
+ * Copyright 2023 Tyler Technologies, Inc. 
+ * License: Apache-2.0
+ */
+import { INITIAL_ORIGIN_SCALE, PADDING, SOFT_EDGE_CONTAINER_RATIO, SOFT_EDGE_MINIMUM_SIZE, StateLayerCoords } from './state-layer-constants';
+export function calcRippleSize(hostEl) {
+    const { height, width } = hostEl.getBoundingClientRect();
+    const maxDim = Math.max(height, width);
+    const softEdgeSize = Math.max(SOFT_EDGE_CONTAINER_RATIO * maxDim, SOFT_EDGE_MINIMUM_SIZE);
+    const initialSize = Math.floor(maxDim * INITIAL_ORIGIN_SCALE);
+    const hypotenuse = Math.sqrt(width ** 2 + height ** 2);
+    const maxRadius = hypotenuse + PADDING;
+    const rippleScale = `${(maxRadius + softEdgeSize) / initialSize}`;
+    const rippleSize = `${initialSize}px`;
+    return { rippleScale, rippleSize, initialSize };
+}
+export function getTranslationCoordinates(hostEl, initialSize, coords) {
+    const { height, width } = hostEl.getBoundingClientRect();
+    const endPoint = {
+        x: (width - initialSize) / 2,
+        y: (height - initialSize) / 2
+    };
+    let startPoint;
+    if (isValidCoords(coords)) {
+        startPoint = toNormalizedCoords(hostEl, coords);
+    }
+    else {
+        startPoint = {
+            x: width / 2,
+            y: height / 2
+        };
+    }
+    startPoint = {
+        x: startPoint.x - (initialSize / 2),
+        y: startPoint.y - (initialSize / 2)
+    };
+    return { startPoint, endPoint };
+}
+export function toNormalizedCoords(hostEl, coords) {
+    const { scrollX, scrollY } = window;
+    const { left, top } = hostEl.getBoundingClientRect();
+    const documentX = scrollX + left;
+    const documentY = scrollY + top;
+    const { x, y } = coords;
+    return { x: x - documentX, y: y - documentY };
+}
+export function isInBounds(hostEl, x, y) {
+    const { height, width } = hostEl.getBoundingClientRect();
+    return x >= 0 && x <= width && y >= 0 && y <= height;
+}
+function isValidCoords(value) {
+    return value && (value instanceof StateLayerCoords || ['x', 'y'].every(key => key in value));
+}

package/esm/state-layer/state-layer.d.ts

@@ -0,0 +1,66 @@
+/**
+ * @license
+ * Copyright 2023 Tyler Technologies, Inc. 
+ * License: Apache-2.0
+ */
+import { StateLayerCoords } from './state-layer-constants';
+import { BaseComponent, IBaseComponent } from '../core/base/base-component';
+export interface IStateLayerComponent extends IBaseComponent {
+    targetElement: HTMLElement | null;
+    target: string | null;
+    disabled: boolean;
+    playAnimation(coords?: StateLayerCoords): void;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'forge-state-layer': IStateLayerComponent;
+    }
+}
+/**
+ * @tag forge-state-layer
+ *
+ * @summary State layers show the interaction status of an element.
+ *
+ * @description
+ * A state layer is a semi-transparent overlay on an element that indicates its interaction
+ * state. State layers provide a systematic approach to visualizing states by using opacity.
+ * A layer can be applied to an entire element or in a circular shape. Only one state layer
+ * can be applied at a given time.
+ *
+ * @property {HTMLElement} targetElement - The element to attach the state layer to.
+ * @property {string} target - The id of the element to attach the state layer to.
+ * @property {boolean} disabled - Controls whether the state layer is disabled.
+ *
+ * @attribute {string} target - The id of the element to attach the state layer to.
+ * @attribute {boolean} disabled - Controls whether the state layer is disabled.
+ *
+ * @cssproperty --forge-state-layer-color - The color of the state layer.
+ * @cssproperty --forge-state-layer-hover-color - The color of the state layer when hovered.
+ * @cssproperty --forge-state-layer-hover-opacity - The opacity of the state layer when hovered.
+ * @cssproperty --forge-state-layer-pressed-color - The color of the state layer when pressed.
+ * @cssproperty --forge-state-layer-pressed-opacity - The opacity of the state layer when pressed.
+ * @cssproperty --forge-state-layer-hover-duration - The duration of the hover animation.
+ * @cssproperty --forge-state-layer-animation-duration - The duration of the animation.
+ * @cssproperty --forge-state-layer-pressed-duration - The duration of the pressed animation.
+ *
+ * @csspart surface - The surface element.
+ */
+export declare class StateLayerComponent extends BaseComponent implements IStateLayerComponent {
+    static get observedAttributes(): string[];
+    private _foundation;
+    constructor();
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    attributeChangedCallback(name: string, oldValue: string, newValue: string): void;
+    targetElement: HTMLElement | null;
+    target: string | null;
+    disabled: boolean;
+    /**
+     * Triggers the animation to run.
+     *
+     * Note: If coordinates are not provided, the transition will originate from the center of the target element.
+     *
+     * @param {StateLayerCoords} [coords] - The coordinates to play the animation from.
+     */
+    playAnimation(coords?: StateLayerCoords): void;
+}