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

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';

package/esm/core/utils/a11y-utils.d.ts

@@ -0,0 +1,156 @@
+/**
+ * @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/internal/aria/aria.ts)
+ */
+/**
+ * Reflective ARIA property name types.
+ */
+export type ARIAProperty = Exclude<keyof ARIAMixin, 'role'>;
+/**
+ * Reflective ARIA attributes.
+ */
+export type ARIAAttribute = `${ARIAPropertyToAttribute<ARIAProperty>}` | 'role';
+/**
+ * Reflective ARIA properties.
+ */
+export declare const ARIA_PROPERTIES: ARIAProperty[];
+/**
+ * ARIA role values.
+ */
+export type ARIARole = 'alert' | 'alertdialog' | 'button' | 'checkbox' | 'dialog' | 'gridcell' | 'link' | 'log' | 'marquee' | 'menuitem' | 'menuitemcheckbox' | 'menuitemradio' | 'option' | 'progressbar' | 'radio' | 'scrollbar' | 'searchbox' | 'slider' | 'spinbutton' | 'status' | 'switch' | 'tab' | 'tabpanel' | 'textbox' | 'timer' | 'tooltip' | 'treeitem' | 'combobox' | 'grid' | 'listbox' | 'menu' | 'menubar' | 'radiogroup' | 'tablist' | 'tree' | 'treegrid' | 'application' | 'article' | 'cell' | 'columnheader' | 'definition' | 'directory' | 'document' | 'feed' | 'figure' | 'group' | 'heading' | 'img' | 'list' | 'listitem' | 'math' | 'none' | 'note' | 'presentation' | 'region' | 'row' | 'rowgroup' | 'rowheader' | 'separator' | 'table' | 'term' | 'text' | 'toolbar' | 'banner' | 'complementary' | 'contentinfo' | 'form' | 'main' | 'navigation' | 'region' | 'search' | 'doc-abstract' | 'doc-acknowledgments' | 'doc-afterword' | 'doc-appendix' | 'doc-backlink' | 'doc-biblioentry' | 'doc-bibliography' | 'doc-biblioref' | 'doc-chapter' | 'doc-colophon' | 'doc-conclusion' | 'doc-cover' | 'doc-credit' | 'doc-credits' | 'doc-dedication' | 'doc-endnote' | 'doc-endnotes' | 'doc-epigraph' | 'doc-epilogue' | 'doc-errata' | 'doc-example' | 'doc-footnote' | 'doc-foreword' | 'doc-glossary' | 'doc-glossref' | 'doc-index' | 'doc-introduction' | 'doc-noteref' | 'doc-notice' | 'doc-pagebreak' | 'doc-pagelist' | 'doc-part' | 'doc-preface' | 'doc-prologue' | 'doc-pullquote' | 'doc-qna' | 'doc-subtitle' | 'doc-tip' | 'doc-toc';
+/**
+ * Strictly typed ARIA properties.
+ */
+export interface ARIAMixinStrict extends ARIAMixin {
+    ariaAtomic: 'true' | 'false' | null;
+    ariaAutoComplete: 'none' | 'inline' | 'list' | 'both' | null;
+    ariaBusy: 'true' | 'false' | null;
+    ariaChecked: 'true' | 'false' | null;
+    ariaColCount: `${number}` | null;
+    ariaColIndex: `${number}` | null;
+    ariaColSpan: `${number}` | null;
+    ariaCurrent: 'page' | 'step' | 'location' | 'date' | 'time' | 'true' | 'false' | null;
+    ariaDisabled: 'true' | 'false' | null;
+    ariaExpanded: 'true' | 'false' | null;
+    ariaHasPopup: 'false' | 'true' | 'menu' | 'listbox' | 'tree' | 'grid' | 'dialog' | null;
+    ariaHidden: 'true' | 'false' | null;
+    ariaInvalid: 'true' | 'false' | null;
+    ariaKeyShortcuts: string | null;
+    ariaLabel: string | null;
+    ariaLevel: `${number}` | null;
+    ariaLive: 'assertive' | 'off' | 'polite' | null;
+    ariaModal: 'true' | 'false' | null;
+    ariaMultiLine: 'true' | 'false' | null;
+    ariaMultiSelectable: 'true' | 'false' | null;
+    ariaOrientation: 'horizontal' | 'vertical' | 'undefined' | null;
+    ariaPlaceholder: string | null;
+    ariaPosInSet: `${number}` | null;
+    ariaPressed: 'true' | 'false' | null;
+    ariaReadOnly: 'true' | 'false' | null;
+    ariaRequired: 'true' | 'false' | null;
+    ariaRoleDescription: string | null;
+    ariaRowCount: `${number}` | null;
+    ariaRowIndex: `${number}` | null;
+    ariaRowSpan: `${number}` | null;
+    ariaSelected: 'true' | 'false' | null;
+    ariaSetSize: `${number}` | null;
+    ariaSort: 'ascending' | 'descending' | 'none' | 'other' | null;
+    ariaValueMax: `${number}` | null;
+    ariaValueMin: `${number}` | null;
+    ariaValueNow: `${number}` | null;
+    ariaValueText: string | null;
+    role: ARIARole | null;
+}
+/**
+ * The ARIA attribute corresponding to a given ARIA property.
+ */
+export type ARIAPropertyToAttribute<K extends string> = K extends `aria${infer Suffix}Element${infer OptS}` ? `aria-${Lowercase<Suffix>}` : K extends `aria${infer Suffix}` ? `aria-${Lowercase<Suffix>}` : K;
+/**
+ * Gets the ARIA attribute corresponding to a given ARIA property.
+ *
+ * @param property An ARIA mixin property.
+ * @returns An ARIA attribute name.
+ */
+export declare function ariaPropertyToAttribute<K extends ARIAProperty | 'role'>(property: K): string;
+/**
+ * Gets the ARIA property corresponding to a given ARIA attribute.
+ *
+ * @param attribute An ARIA attribute name.
+ * @returns An ARIA mixin property.
+ */
+export declare function ariaAttributeToProperty<K extends ARIAAttribute | 'role'>(attribute: K): ARIAProperty;
+export interface DefaultAriaOptions {
+    overwrite?: boolean;
+}
+/**
+ * Applies default ARIA to an element through ElementInternals if supported. Otherwise, ARIA
+ * attributes are set directly on the element and stored in additional `data-default-*` attributes
+ * for restoration in case attributes are overwritten during the element's lifecycle.
+ *
+ * This fallback is needed for browsers that don't support ARIA in ElementInternals, such as most
+ * recent versions of Firefox.
+ *
+ * Because new attributes may be sprouted on the element, it is necessary to call this after the
+ * element has been connected to the DOM.
+ *
+ * @param element - The element to set up ARIA attributes for.
+ * @param internals - The ElementInternals object to use for setting ARIA attributes if supported.
+ * @param properties - An object containing ARIA properties and their values to set as defaults.
+ * @param options - A `DefaultAriaOptions` object.
+ *
+ * @example
+ * class ButtonComponent extends BaseComponent {
+ *  public readonly internals: ElementInternals;
+ *
+ *  constructor() {
+ *   super();
+ *   this.internals = this.attachInternals();
+ *  }
+ *
+ *  public connectedCallback(): void {
+ *    setDefaultAria(this, this.internals, {
+ *     role: 'button'
+ *    });
+ *   }
+ * }
+ */
+export declare function setDefaultAria(element: HTMLElement, internals: ElementInternals, properties: Partial<ARIAMixinStrict>, options?: DefaultAriaOptions): void;
+/**
+ * Sets a `*Default` property on an element to backup the default value of an ARIA attribute.
+ *
+ * @param element The element to store the default ARIA value on.
+ * @param property The ARIA mixin property.
+ * @param value The default value to store.
+ */
+export declare function storeDefaultAria<T extends keyof ARIAMixinStrict>(element: HTMLElement, property: T, value: ARIAMixinStrict[T]): void;
+/**
+ * Removes a `*Default` property from an element.
+ *
+ * @param element The element to remove the default ARIA value from.
+ * @param property The ARIA mixin property.
+ */
+export declare function removeDefaultAria<T extends keyof ARIAMixinStrict>(element: HTMLElement, property: T): void;
+/**
+ * Gets a default ARIA value from an element's `*Default` property.
+ *
+ * @param element The element to retrieve the default ARIA value from.
+ * @param property An ARIA mixin property.
+ * @returns The value of the default ARIA attribute, or null if it does not exist.
+ */
+export declare function retrieveDefaultAria<T extends keyof ARIAMixinStrict>(element: HTMLElement, property: T): ARIAMixinStrict[T] | null;
+/**
+ * Restores the given ARIA attribute of an element to its default value if it exists.
+ *
+ * @param element The element to restore the ARIA attribute on.
+ * @param property The ARIA mixin property.
+ */
+export declare function restoreDefaultAria<T extends keyof ARIAMixinStrict>(element: HTMLElement, property: T): void;