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

package/esm/core/{base/base-focusable-component.js → mixins/focus/with-focusable.js}

@@ -11,18 +11,26 @@
  * Adapted and influenced from [Material Web](https://github.com/material-components/material-web).
  * The original source code can be found at: [GitHub](https://github.com/material-components/material-web/blob/main/labs/behaviors/focusable.ts)
  */
-import { isFocusable } from '../../constants';
-import { BaseComponent } from './base-component';
+import { isFocusable } from '../../../constants';
 const _privateIsFocusable = Symbol('privateIsFocusable');
 const _externalTabIndex = Symbol('externalTabIndex');
 const _isUpdatingTabIndex = Symbol('isUpdatingTabIndex');
 const _updateTabIndex = Symbol('updateTabIndex');
 /**
- * Mixes in focusable functionality into a base component.
+ * Provides focusable functionality for an element.
+ *
+ * Elements can enable and disable their focusability with the `isFocusable`
+ * symbol property. **Use this instead of changing `tabIndex` directly.**
+ *
+ * This will preserve externally-set tabindices. If an element sets `tabindex="-1"`,
+ * but a user sets `tabindex="0"`, it will still be focusable.
+ *
+ * To remove user overrides and restore focus control to the element, remove the `tabindex` attribute.
  *
  * @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 WithFocusable(base) {
     var _a, _b, _c;
     class FocusableComponent extends base {
@@ -48,10 +56,14 @@ export function WithFocusable(base) {
             this[_updateTabIndex]();
         }
         connectedCallback() {
+            var _d;
+            (_d = super.connectedCallback) === null || _d === void 0 ? void 0 : _d.call(this);
             // This must be set in the connectedCallback to avoid sprouting a tabindex attribute on the host from the ctor
             this[isFocusable] = true;
         }
         attributeChangedCallback(name, oldValue, newValue) {
+            var _d;
+            (_d = super.attributeChangedCallback) === null || _d === void 0 ? void 0 : _d.call(this, name, oldValue, newValue);
             if (name !== 'tabindex' || this[_isUpdatingTabIndex]) {
                 return;
             }
@@ -75,16 +87,3 @@ export function WithFocusable(base) {
     }
     return FocusableComponent;
 }
-/**
- * Provides focusable functionality for an element.
- *
- * Elements can enable and disable their focusability with the `isFocusable`
- * symbol property. **Use this instead of changing `tabIndex` directly.**
- *
- * This will preserve externally-set tabindices. If an element sets `tabindex="-1"`,
- * but a user sets `tabindex="0"`, it will still be focusable.
- *
- * To remove user overrides and restore focus control to the element, remove the `tabindex` attribute.
- */
-export class BaseFocusableComponent extends WithFocusable(BaseComponent) {
-}

package/esm/core/mixins/form/with-form-associated.d.ts

@@ -0,0 +1,116 @@
+/**
+ * @license
+ * Copyright 2023 Tyler Technologies, Inc. 
+ * License: Apache-2.0
+ */
+/**
+ * @license
+ * Copyright 2023 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * Adapted and influenced from [Material Web](https://github.com/material-components/material-web).
+ * The original source code can be found at: [GitHub](https://github.com/material-components/material-web/blob/main/labs/behaviors/form-associated.ts)
+ */
+import { MixinBase, getFormState, getFormValue, getValidationMessage, inputType, internals, AbstractConstructor } from '../../../constants';
+import { FormRestoreReason, FormRestoreState, FormValue, InputType, InputValidationProps } from '../../utils/form-utils';
+import { IBaseComponent } from '../../base/base-component';
+/**
+ * A component that can be associated with a form.
+ */
+export interface IWithFormAssociation<TValue = FormValue | null> extends IBaseComponent {
+    /**
+     * The form element that the component is associated with.
+     */
+    readonly form: HTMLFormElement | null;
+    /**
+     * The labels associated with the component.
+     */
+    readonly labels: NodeList;
+    /**
+     * The HTML name to use in form submission.
+     */
+    name: string;
+    disabled: boolean;
+    /**
+     * Whether or not the component is readonly.
+     */
+    readonly: boolean;
+    /**
+     * The internals of the component.
+     */
+    readonly [internals]: ElementInternals;
+    /**
+     * Sets the value type accepted by the component. This is used to set the type of the internal
+     * input element and generate validation messages.
+     */
+    [inputType]: InputType;
+    /**
+     * Gets the validation message for the component.
+     *
+     * @param props Validation-affecting properties set on the component as well as the value of the
+     * component.
+     */
+    [getValidationMessage](props: Partial<InputValidationProps>): string | undefined;
+    /**
+     * Gets the current form value of the component.
+     */
+    [getFormValue](): FormValue | null;
+    /**
+     * Gets the current form state of the component, defaulting to the component's `[formValue]`.
+     *
+     * Used when the component's state is different from its value, such as a checkboxes that have
+     * both a boolean `checked` state and a string value.
+     */
+    [getFormState](): FormValue | null;
+    /**
+     * A callback for when the component should be enabled or disabled. This can be called when, for
+     * example, the component is within a disabled fieldset.
+     *
+     * @param disabled Whether or not the component should be disabled.
+     */
+    formDisabledCallback(disabled: boolean): void;
+    /**
+     * A callback for when the form's value is to be reset.
+     */
+    formResetCallback(): void;
+    /**
+     * A callback for when a form restores the state of the component. For example, when a page is
+     * reloaded or a form is autofilled.
+     *
+     * @param state The state to restore or null to reset the component's value.
+     * @param reason The reason the state was restored.
+     */
+    formStateRestoreCallback(state: FormRestoreState | null, reason: FormRestoreReason): void;
+    /**
+     * An optional callback for when the associated form changes.
+     *
+     * @param form The new associated form or null if there is none.
+     */
+    formAssociatedCallback?(form: HTMLFormElement | null): void;
+}
+export declare abstract class WithFormAssociationContract {
+    static readonly formAssociated: boolean;
+    get form(): HTMLFormElement | null;
+    get labels(): NodeList;
+    get name(): string;
+    set name(value: string);
+    abstract get disabled(): boolean;
+    abstract set disabled(value: boolean);
+    abstract get readonly(): boolean;
+    abstract set readonly(value: boolean);
+    abstract get [internals](): ElementInternals;
+    abstract [getFormValue](): FormValue | null;
+    [getFormState](): FormValue | null;
+    formDisabledCallback(disabled: boolean): void;
+    abstract formStateRestoreCallback(state: FormRestoreState | null, reason: FormRestoreReason): void;
+    abstract formResetCallback(): void;
+    set [inputType](type: InputType);
+    [getValidationMessage](props: Partial<InputValidationProps>): string | undefined;
+}
+/**
+ * Mixes in form functionality into a base component.
+ *
+ * @param base The base component to mix into.
+ * @returns The mixed-in base component.
+ */
+export declare function WithFormAssociation<TBase extends MixinBase>(base: TBase): AbstractConstructor<WithFormAssociationContract> & TBase;

package/esm/core/mixins/form/with-form-associated.js

@@ -0,0 +1,71 @@
+/**
+ * @license
+ * Copyright 2023 Tyler Technologies, Inc. 
+ * License: Apache-2.0
+ */
+/**
+ * @license
+ * Copyright 2023 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * Adapted and influenced from [Material Web](https://github.com/material-components/material-web).
+ * The original source code can be found at: [GitHub](https://github.com/material-components/material-web/blob/main/labs/behaviors/form-associated.ts)
+ */
+import { toggleAttribute } from '@tylertech/forge-core';
+import { getFormState, getFormValue, getValidationMessage, inputType, internals } from '../../../constants';
+/**
+ * Mixes in form functionality into a base component.
+ *
+ * @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 WithFormAssociation(base) {
+    class FormAssociatedComponent extends base {
+        get form() {
+            return this[internals].form;
+        }
+        get labels() {
+            return this[internals].labels;
+        }
+        get name() {
+            var _a;
+            return (_a = this.getAttribute('name')) !== null && _a !== void 0 ? _a : '';
+        }
+        set name(value) {
+            toggleAttribute(this, !!value, 'name', value);
+        }
+        [getFormState]() {
+            return this[getFormValue]();
+        }
+        formDisabledCallback(disabled) {
+            this.disabled = disabled;
+        }
+        set [inputType](type) {
+            // Create a detached input to retrieve localized validation messages from
+            const inputElement = type === 'select'
+                ? document.createElement('select')
+                : document.createElement('input');
+            inputElement.setAttribute('type', type);
+            inputElement.name = 'internal';
+            this._inputElement = inputElement;
+        }
+        [getValidationMessage](props) {
+            // If the input element hasn't been created yet return `undefined`
+            if (!this._inputElement) {
+                return undefined;
+            }
+            // A custom error message overrides all other messages
+            if (this[internals].validity.customError) {
+                return this[internals].validationMessage;
+            }
+            // Apply validation-affecting props to the input element to get the correct validation
+            // message
+            // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+            Object.entries(props).forEach(([key, value]) => this._inputElement[key] = value);
+            return this._inputElement.validationMessage;
+        }
+    }
+    FormAssociatedComponent.formAssociated = true;
+    return FormAssociatedComponent;
+}

package/esm/core/mixins/form/with-form-validity.d.ts

@@ -0,0 +1,35 @@
+/**
+ * @license
+ * Copyright 2023 Tyler Technologies, Inc. 
+ * License: Apache-2.0
+ */
+import { AbstractConstructor, MixinBase } from '../../../constants';
+import { IBaseComponent } from '../../base/base-component';
+/**
+ * An element that is integrated with native form validation.
+ */
+export interface IWithFormValidity extends IBaseComponent {
+    required: boolean;
+    readonly validity: ValidityState;
+    readonly validationMessage: string;
+    readonly willValidate: boolean;
+    checkValidity(): boolean;
+    reportValidity(): boolean;
+    setCustomValidity(error: string): void;
+}
+export declare abstract class WithFormValidityContract {
+    abstract required: boolean;
+    get validity(): ValidityState;
+    get validationMessage(): string;
+    get willValidate(): boolean;
+    checkValidity(): boolean;
+    reportValidity(): boolean;
+    setCustomValidity(error: string): void;
+}
+/**
+ * Provides form validity functionality for an element.
+ *
+ * @param base The base component to mix into.
+ * @returns The mixed-in base component.
+ */
+export declare function WithFormValidity<TBase extends MixinBase>(base: TBase): AbstractConstructor<WithFormValidityContract> & TBase;

package/esm/core/mixins/form/with-form-validity.js

@@ -0,0 +1,43 @@
+/**
+ * @license
+ * Copyright 2023 Tyler Technologies, Inc. 
+ * License: Apache-2.0
+ */
+import { internals } from '../../../constants';
+/**
+ * Provides form validity functionality for an element.
+ *
+ * @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 WithFormValidity(base) {
+    class FormValidity extends base {
+        constructor() {
+            super(...arguments);
+            // Needed for Safari, see https://bugs.webkit.org/show_bug.cgi?id=261432
+            // Replace with this.internals.validity.customError when resolved.
+            this._hasCustomValidityError = false;
+        }
+        get validity() {
+            return this[internals].validity;
+        }
+        get validationMessage() {
+            return this[internals].validationMessage;
+        }
+        get willValidate() {
+            return this[internals].willValidate;
+        }
+        checkValidity() {
+            return this[internals].checkValidity();
+        }
+        reportValidity() {
+            return this[internals].reportValidity();
+        }
+        setCustomValidity(error) {
+            this._hasCustomValidityError = error !== '';
+            this[internals].setCustomValidity({ customError: this._hasCustomValidityError }, error);
+        }
+    }
+    return FormValidity;
+}

package/esm/core/mixins/interactions/longpress/with-longpress-listener.d.ts

@@ -0,0 +1,33 @@
+/**
+ * @license
+ * Copyright 2023 Tyler Technologies, Inc. 
+ * License: Apache-2.0
+ */
+import { AbstractConstructor, MixinBase } from '../../../../constants';
+/**
+ * The delay in milliseconds before a longpress event is detected.
+ */
+export declare const LONGPRESS_TRIGGER_DELAY = 500;
+export declare abstract class WithLongpressListenerContract {
+    /**
+     * The delay in milliseconds before a longpress event is detected.
+     */
+    protected _longpressDelay: number;
+    /**
+     * Called when a longpress event is detected.
+     */
+    protected abstract _onLongpress(): void;
+    /**
+     * Called after a longpress event has been detected, but after the user has released the pointer.
+     */
+    protected _onLongpressEnd(evt: PointerEvent | TouchEvent): void;
+    /**
+     * Starts listening for longpress events.
+     */
+    protected _startLongpressListener(el: HTMLElement): void;
+    /**
+     * Stops listening for longpress events.
+     */
+    protected _stopLongpressListener(el: HTMLElement): void;
+}
+export declare function WithLongpressListener<TBase extends MixinBase<object>>(base?: TBase): AbstractConstructor<WithLongpressListenerContract> & TBase;

package/esm/core/mixins/interactions/longpress/with-longpress-listener.js

@@ -0,0 +1,82 @@
+/**
+ * @license
+ * Copyright 2023 Tyler Technologies, Inc. 
+ * License: Apache-2.0
+ */
+import { canUserHoverElements } from '../../../../constants';
+/**
+ * The delay in milliseconds before a longpress event is detected.
+ */
+export const LONGPRESS_TRIGGER_DELAY = 500;
+// eslint-disable-next-line @typescript-eslint/explicit-function-return-type
+export function WithLongpressListener(base = class {
+}) {
+    class LongpressListener extends base {
+        constructor() {
+            super(...arguments);
+            this._longpressStartListener = this._onLongpressStart.bind(this);
+            this._longpressEndListener = this._onLongpressEnd.bind(this);
+            this._longpressContextMenuListener = this._onLongpressContextMenu.bind(this);
+            this._longpressClickPrevent = this._onLongpressClickPrevent.bind(this);
+            this._longpressDelay = LONGPRESS_TRIGGER_DELAY;
+        }
+        _startLongpressListener(el) {
+            const type = canUserHoverElements ? 'pointerdown' : 'touchstart';
+            el.addEventListener(type, this._longpressStartListener);
+        }
+        _stopLongpressListener(el) {
+            const type = canUserHoverElements ? 'pointerdown' : 'touchstart';
+            el.removeEventListener(type, this._longpressStartListener);
+            this._unlistenLongpressEnd(el);
+        }
+        _onLongpressStart(evt) {
+            evt.target.setPointerCapture(evt.pointerId);
+            this._listenLongpressEnd(evt.target);
+            this._longpressTimeout = window.setTimeout(() => {
+                this._onLongpress();
+                if (!canUserHoverElements) {
+                    navigator.vibrate(1);
+                }
+                // We need to prevent any ghost click events from firing after a longpress is detected
+                evt.target.addEventListener('click', this._longpressClickPrevent, { capture: true, once: true });
+            }, this._longpressDelay);
+        }
+        _onLongpressClickPrevent(evt) {
+            evt.stopPropagation();
+        }
+        _onLongpressEnd(evt) {
+            this._clearTimeout();
+            this._unlistenLongpressEnd(evt.target);
+        }
+        _onLongpressContextMenu(evt) {
+            this._clearTimeout();
+            evt.target.removeEventListener('click', this._longpressClickPrevent, { capture: true });
+            this._unlistenLongpressEnd(evt.target);
+        }
+        _listenLongpressEnd(el) {
+            if (!canUserHoverElements) {
+                el.addEventListener('touchend', this._longpressEndListener);
+            }
+            else {
+                el.addEventListener('pointerup', this._longpressEndListener);
+                el.addEventListener('pointercancel', this._longpressEndListener);
+                el.addEventListener('contextmenu', this._longpressContextMenuListener);
+            }
+        }
+        _unlistenLongpressEnd(el) {
+            if (!canUserHoverElements) {
+                el.removeEventListener('touchend', this._longpressEndListener);
+            }
+            else {
+                el.removeEventListener('pointerup', this._longpressEndListener);
+                el.removeEventListener('pointercancel', this._longpressEndListener);
+                el.removeEventListener('contextmenu', this._longpressContextMenuListener);
+            }
+        }
+        _clearTimeout() {
+            window.clearTimeout(this._longpressTimeout);
+            this._longpressTimeout = undefined;
+        }
+    }
+    return LongpressListener;
+}

package/esm/core/mixins/internals/with-default-aria.d.ts

@@ -0,0 +1,32 @@
+/**
+ * @license
+ * Copyright 2023 Tyler Technologies, Inc. 
+ * License: Apache-2.0
+ */
+import { MixinBase, setDefaultAria, AbstractConstructor } from '../../../constants';
+import { ARIAMixinStrict, DefaultAriaOptions } from '../../utils/a11y-utils';
+import { IBaseComponent } from '../../base/base-component';
+/**
+ * A component with support for setting default ARIA.
+ */
+export interface IWithDefaultAria extends IBaseComponent {
+    /**
+     * Sets the default ARIA of the component using Element Internals if supported or sprouting
+     * ARIA attributes if not.
+     *
+     * @param properties The ARIA properties and values to set.
+     * @param options Whether or not to overwrite existing ARIA attributes. This only takes effect
+     * if Element Internals are not supported and a new attribute will be sprouted.
+     */
+    [setDefaultAria](properties: Partial<ARIAMixinStrict>, options?: DefaultAriaOptions): void;
+}
+export declare abstract class WithDefaultAriaContract {
+    [setDefaultAria](properties: Partial<ARIAMixinStrict>, options?: DefaultAriaOptions): void;
+}
+/**
+ * Mixes in Element Internals functionality into a base component.
+ *
+ * @param base The base component to mix into.
+ * @returns The mixed-in base component.
+ */
+export declare function WithDefaultAria<TBase extends MixinBase>(base: TBase): AbstractConstructor<WithDefaultAriaContract> & TBase;

package/esm/core/mixins/internals/with-default-aria.js

@@ -0,0 +1,22 @@
+/**
+ * @license
+ * Copyright 2023 Tyler Technologies, Inc. 
+ * License: Apache-2.0
+ */
+import { internals, setDefaultAria } from '../../../constants';
+import { setDefaultAria as setDefaultAriaUtil } from '../../utils/a11y-utils';
+/**
+ * Mixes in Element Internals functionality into a base component.
+ *
+ * @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 WithDefaultAria(base) {
+    class DefaultAria extends base {
+        [setDefaultAria](properties, options) {
+            setDefaultAriaUtil(this, this[internals], properties, options);
+        }
+    }
+    return DefaultAria;
+}

package/esm/core/mixins/internals/with-element-internals.d.ts

@@ -0,0 +1,26 @@
+/**
+ * @license
+ * Copyright 2023 Tyler Technologies, Inc. 
+ * License: Apache-2.0
+ */
+import { AbstractConstructor, internals, MixinBase } from '../../../constants';
+import { IBaseComponent } from '../../base/base-component';
+/**
+ * A component with attached Element Internals.
+ */
+export interface IWithElementInternals extends IBaseComponent {
+    /**
+     * The Element Internals of the component.
+     */
+    readonly [internals]: ElementInternals;
+}
+export declare abstract class WithElementInternalsContract {
+    readonly [internals]: ElementInternals;
+}
+/**
+ * Mixes in Element Internals functionality into a base component.
+ *
+ * @param base The base component to mix into.
+ * @returns The mixed-in base component.
+ */
+export declare function WithElementInternals<TBase extends MixinBase>(base: TBase): AbstractConstructor<WithElementInternalsContract> & TBase;

package/esm/core/mixins/internals/with-element-internals.js

@@ -0,0 +1,22 @@
+/**
+ * @license
+ * Copyright 2023 Tyler Technologies, Inc. 
+ * License: Apache-2.0
+ */
+import { internals } from '../../../constants';
+/**
+ * Mixes in Element Internals functionality into a base component.
+ *
+ * @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 WithElementInternals(base) {
+    class ElementInternalsComponent extends base {
+        constructor(...args) {
+            super(...args);
+            this[internals] = this.attachInternals();
+        }
+    }
+    return ElementInternalsComponent;
+}

package/esm/core/mixins/label/with-label-aware.d.ts

@@ -0,0 +1,33 @@
+/**
+ * @license
+ * Copyright 2023 Tyler Technologies, Inc. 
+ * License: Apache-2.0
+ */
+import { AbstractConstructor, MixinBase } from '../../../constants';
+import { IBaseComponent } from '../../base/base-component';
+/**
+ * An element that can be associated with a Forge label component.
+ */
+export interface IWithLabelAwareness extends IBaseComponent {
+    /**
+     * A callback for when the associated label's text content changes.
+     *
+     * @param value The new text content of the label, or null if the label was removed or has no
+     * text content.
+     */
+    labelChangedCallback(value: string | null): void;
+    /**
+     * A callback for when the associated label is clicked.
+     */
+    labelClickedCallback?(): void;
+}
+export declare abstract class WithLabelAwarenessContract {
+    abstract labelChangedCallback(value: string | null): void;
+}
+/**
+ * Mixes in Forge label awareness into a base component.
+ *
+ * @param base The base component to mix into.
+ * @returns The mixed-in base component.
+ */
+export declare function WithLabelAwareness<TBase extends MixinBase>(base: TBase): AbstractConstructor<WithLabelAwarenessContract> & TBase;

package/esm/core/mixins/label/with-label-aware.js

@@ -0,0 +1,17 @@
+/**
+ * @license
+ * Copyright 2023 Tyler Technologies, Inc. 
+ * License: Apache-2.0
+ */
+/**
+ * Mixes in Forge label awareness into a base component.
+ *
+ * @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 WithLabelAwareness(base) {
+    class LabelAwareComponent extends base {
+    }
+    return LabelAwareComponent;
+}