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

package/esm/core/base/base-element-internals-component.d.ts

@@ -0,0 +1,41 @@
+/**
+ * @license
+ * Copyright 2023 Tyler Technologies, Inc. 
+ * License: Apache-2.0
+ */
+import { internals, MixinBase, setDefaultAria, AbstractConstructor } from '../../constants';
+import { ARIAAttribute, ARIAMixinStrict, DefaultAriaOptions } from '../utils/a11y-utils';
+import { IBaseComponent } from './base-component';
+/**
+ * A component with attached Element Internals.
+ */
+export interface IWithElementInternals extends IBaseComponent {
+    /**
+     * The Element Internals of the component.
+     */
+    readonly [internals]: ElementInternals;
+    /**
+     * 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 WithElementInternalsContract {
+    readonly [internals]: ElementInternals;
+    attributeChangedCallback(name: string, oldValue: string, newValue: string): void;
+    [setDefaultAria](properties: Partial<ARIAMixinStrict>, options?: DefaultAriaOptions): void;
+}
+/**
+ * Mixes in Element Internals functionality into a base component.
+ *
+ * @param base The base component to mix into.
+ * @param observedAria An array of ARIA attributes to observe for changes. If an observed attribute
+ * is removed, the default ARIA will be restored. This is only used if Element Internals is not
+ * supported.
+ * @returns The mixed-in base component.
+ */
+export declare function WithElementInternals<TBase extends MixinBase>(base: TBase, observedAria?: ARIAAttribute[]): AbstractConstructor<WithElementInternalsContract> & TBase;

package/esm/core/base/base-element-internals-component.js

@@ -0,0 +1,47 @@
+/**
+ * @license
+ * Copyright 2023 Tyler Technologies, Inc. 
+ * License: Apache-2.0
+ */
+import { internals, setDefaultAria } from '../../constants';
+import { ariaAttributeToProperty, restoreDefaultAria as restoreDefaultAriaUtil, setDefaultAria as setDefaultAriaUtil } from '../utils/a11y-utils';
+import { supportsElementInternalsAria } from '../utils/feature-detection';
+/**
+ * Mixes in Element Internals functionality into a base component.
+ *
+ * @param base The base component to mix into.
+ * @param observedAria An array of ARIA attributes to observe for changes. If an observed attribute
+ * is removed, the default ARIA will be restored. This is only used if Element Internals is not
+ * supported.
+ * @returns The mixed-in base component.
+ */
+// eslint-disable-next-line @typescript-eslint/explicit-function-return-type
+export function WithElementInternals(base, observedAria) {
+    class ElementInternalsComponent extends base {
+        constructor(...args) {
+            super(...args);
+            this[internals] = this.attachInternals();
+        }
+        attributeChangedCallback(name, oldValue, newValue) {
+            var _a;
+            (_a = super.attributeChangedCallback) === null || _a === void 0 ? void 0 : _a.call(this, name, oldValue, newValue);
+            // If Element Internals is supported our default ARIA is never set as an attribute, so
+            // there's nothing to do here.
+            if (!observedAria || supportsElementInternalsAria()) {
+                return;
+            }
+            // If the observed attribute is removed, restore the default ARIA.
+            if (observedAria.includes(name) && !newValue) {
+                const ariaPropertyName = ariaAttributeToProperty(name);
+                this._restoreDefaultAria(ariaPropertyName);
+            }
+        }
+        [setDefaultAria](properties, options) {
+            setDefaultAriaUtil(this, this[internals], properties, options);
+        }
+        _restoreDefaultAria(name) {
+            restoreDefaultAriaUtil(this, name);
+        }
+    }
+    return ElementInternalsComponent;
+}

package/esm/core/base/base-focusable-component.d.ts

@@ -11,28 +11,24 @@
  * 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, MixinBase, MixinReturn } from '../../constants';
-import { BaseComponent, IBaseComponent } from './base-component';
+import { AbstractConstructor, isFocusable, MixinBase } from '../../constants';
+import { IBaseComponent } from './base-component';
 /**
  * An element that can enable and disable `tabindex` focusability.
  */
-export interface IBaseFocusableComponent extends IBaseComponent {
+export interface IWithFocusable extends IBaseComponent {
     /**
      * Whether or not the element can be focused. Defaults to true. Set to false
      * to disable focusing (unless a user has set a `tabindex`).
      */
     [isFocusable]: boolean;
+}
+export declare abstract class WithFocusableContract {
+    get [isFocusable](): boolean;
+    set [isFocusable](value: boolean);
     connectedCallback(): void;
     attributeChangedCallback(name: string, oldValue: string, newValue: string): void;
 }
-/**
- * Mixes in focusable functionality into a base component.
- *
- * @param base The base component to mix into.
- * @returns The mixed-in base component.
- */
-export declare function WithFocusable<T extends MixinBase<BaseComponent>>(base: T): MixinReturn<T, IBaseFocusableComponent>;
-declare const BaseFocusableComponent_base: MixinReturn<typeof BaseComponent, IBaseFocusableComponent>;
 /**
  * Provides focusable functionality for an element.
  *
@@ -43,7 +39,8 @@ declare const BaseFocusableComponent_base: MixinReturn<typeof BaseComponent, IBa
  * 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.
  */
-export declare abstract class BaseFocusableComponent extends BaseFocusableComponent_base implements IBaseFocusableComponent {
-}
-export {};
+export declare function WithFocusable<TBase extends MixinBase>(base: TBase): AbstractConstructor<WithFocusableContract> & TBase;

package/esm/core/base/base-focusable-component.js

@@ -12,17 +12,25 @@
  * 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';
 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/base/base-form-associated-component.d.ts

@@ -0,0 +1,122 @@
+/**
+ * @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-component';
+/**
+ * A component that can be associated with a form.
+ */
+export interface IWithFormAssociation 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 value to use in form submission.
+     */
+    value: FormValue | null;
+    /**
+     * 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 value(): FormValue | null;
+    abstract set value(value: FormValue | null);
+    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/base/base-form-associated-component.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/base/base-form-component.d.ts

@@ -5,7 +5,6 @@
  */
 import { internals } from '../../constants';
 import { BaseComponent, IBaseComponent } from './base-component';
-import { IBaseFocusableComponent } from './base-focusable-component';
 export interface IBaseFormComponent<T = string> extends IBaseComponent {
     value: T;
     disabled: boolean;
@@ -34,12 +33,3 @@ export declare abstract class BaseFormComponent<T = string> extends BaseComponen
     abstract formStateRestoreCallback(state: unknown, reason: 'restore' | 'autocomplete'): void;
     abstract formDisabledCallback(isDisabled: boolean): void;
 }
-export interface IBaseFocusableFormComponent<T = string> extends IBaseFormComponent<T>, IBaseFocusableComponent {
-}
-declare const BaseFocusableFormComponent_base: import("../../constants").MixinReturn<typeof BaseFormComponent, IBaseFocusableComponent>;
-/**
- * Any form associated Custom HTML element that focus on the host element.
- */
-export declare abstract class BaseFocusableFormComponent<T = string> extends BaseFocusableFormComponent_base<T> implements IBaseFocusableFormComponent<T> {
-}
-export {};

package/esm/core/base/base-form-component.js

@@ -5,15 +5,9 @@
  */
 import { internals } from '../../constants';
 import { BaseComponent } from './base-component';
-import { WithFocusable } from './base-focusable-component';
 /**
  * Any form associated Custom HTML element.
  */
 export class BaseFormComponent extends BaseComponent {
 }
 BaseFormComponent.formAssociated = true;
-/**
- * Any form associated Custom HTML element that focus on the host element.
- */
-export class BaseFocusableFormComponent extends WithFocusable(BaseFormComponent) {
-}

package/esm/core/base/base-label-aware-component.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-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/base/base-label-aware-component.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;
+}

package/esm/core/base/base-nullable-form-component.d.ts

@@ -3,7 +3,6 @@
  * Copyright 2023 Tyler Technologies, Inc. 
  * License: Apache-2.0
  */
-import { IBaseFocusableComponent } from './base-focusable-component';
 import { BaseFormComponent, IBaseFormComponent } from './base-form-component';
 export interface IBaseNullableFormComponent<T = string> extends IBaseFormComponent<T> {
     required: boolean;
@@ -24,12 +23,3 @@ export declare abstract class BaseNullableFormComponent<T = string> extends Base
     abstract reportValidity(): boolean;
     abstract setCustomValidity(error: string): void;
 }
-export interface IBaseFocusableNullableFormComponent<T = string> extends IBaseFormComponent<T>, IBaseFocusableComponent {
-}
-declare const BaseFocusableNullableFormComponent_base: import("../..").MixinReturn<typeof BaseFormComponent, IBaseFocusableComponent>;
-/**
- * Any form associated Custom HTML element that focus on the host element.
- */
-export declare abstract class BaseFocusableNullableFormComponent<T = string> extends BaseFocusableNullableFormComponent_base<T> implements IBaseFocusableNullableFormComponent<T> {
-}
-export {};

package/esm/core/base/base-nullable-form-component.js

@@ -3,7 +3,6 @@
  * Copyright 2023 Tyler Technologies, Inc. 
  * License: Apache-2.0
  */
-import { WithFocusable } from './base-focusable-component';
 import { BaseFormComponent } from './base-form-component';
 export class BaseNullableFormComponent extends BaseFormComponent {
     constructor() {
@@ -13,8 +12,3 @@ export class BaseNullableFormComponent extends BaseFormComponent {
         this._hasCustomValidityError = false;
     }
 }
-/**
- * Any form associated Custom HTML element that focus on the host element.
- */
-export class BaseFocusableNullableFormComponent extends WithFocusable(BaseFormComponent) {
-}

package/esm/core/base/index.d.ts

@@ -5,3 +5,7 @@
  */
 export * from './base-adapter';
 export * from './base-component';
+export * from './base-element-internals-component';
+export * from './base-focusable-component';
+export * from './base-form-associated-component';
+export * from './base-label-aware-component';

package/esm/core/base/index.js

@@ -5,3 +5,7 @@
  */
 export * from './base-adapter';
 export * from './base-component';
+export * from './base-element-internals-component';
+export * from './base-focusable-component';
+export * from './base-form-associated-component';
+export * from './base-label-aware-component';