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

package/esm/checkbox/checkbox-foundation.js

@@ -5,168 +5,168 @@
  */
 import { CHECKBOX_CONSTANTS } from './checkbox-constants';
 export class CheckboxFoundation {
+    get _submittedValue() {
+        return this._checked ? this._value : null;
+    }
+    get _formState() {
+        return this._checked
+            ? this._indeterminate
+                ? 'checked-indeterminate'
+                : 'checked'
+            : this._indeterminate
+                ? 'unchecked-indeterminate'
+                : 'unchecked';
+    }
     constructor(_adapter) {
         this._adapter = _adapter;
+        // State
+        this._checked = false;
+        this._defaultChecked = false;
+        this._indeterminate = false;
+        this._value = 'on';
         this._dense = false;
-        this._currentCheckState = CHECKBOX_CONSTANTS.strings.TRANSITION_STATE_INIT;
-        this._currentAnimationClass = '';
-        this._animEndLatchTimer = 0;
-        this._enableAnimationEndHandler = false;
-    }
-    disconnect() {
-        this._adapter.unlisten('change', this._handleChange);
-        this._adapter.disconnect();
-        this._adapter.uninstallPropertyChangeHooks();
-        this._adapter.unlisten('animationend', this._handleAnimationEnd);
-    }
-    connect() {
+        this._disabled = false;
+        this._required = false;
+        this._readonly = false;
+        this._labelPosition = 'end';
+        this._changeListener = (evt) => this._handleChange(evt);
+        this._inputSlotListener = () => this._handleInputSlotChange();
+    }
+    initialize() {
         this._adapter.initialize();
-        this._currentCheckState = this._determineCheckState();
-        this._setDense(this.dense);
-        this._updateAriaChecked();
-        this._inputAttributeChangedListener = (name, value) => this._handleInputAttributeChange();
-        this._adapter.setInputAttributeObserver((name, value) => this._inputAttributeChangedListener(name, value));
-        this._handleChange = () => this._handleInputChange();
-        this._adapter.listen('change', this._handleChange);
-        this._adapter.installPropertyChangeHooks(() => {
-            this._handleInputChange();
-        });
-        this._handleAnimationEnd = () => this.handleAnimationEnd();
-        this._adapter.listen('animationend', this._handleAnimationEnd, true);
-        this._handleInputChange();
+        this._adapter.addRootListener('change', this._changeListener);
+        this._adapter.addInputSlotListener(this._inputSlotListener);
+        this._adapter.syncValue(this._submittedValue, this._formState);
     }
-    get dense() {
-        return this._dense;
+    ;
+    proxyClick() {
+        this._adapter.proxyClick();
     }
-    set dense(value) {
-        if (this._dense !== value) {
-            this._dense = value;
-            this._setDense(value);
-        }
+    proxyLabel(value) {
+        this._adapter.proxyLabel(value);
     }
-    handleAnimationEnd() {
-        if (!this._enableAnimationEndHandler) {
-            return;
-        }
-        const handler = () => {
-            this._adapter.removeRootClass(this._currentAnimationClass);
-            this._enableAnimationEndHandler = false;
-        };
-        clearTimeout(this._animEndLatchTimer);
-        this._animEndLatchTimer = setTimeout(handler, CHECKBOX_CONSTANTS.numbers.ANIM_END_LATCH_MS);
-    }
-    _setDense(value) {
-        this._adapter.setDense(value);
-    }
-    _determineCheckState() {
-        const { TRANSITION_STATE_INDETERMINATE, TRANSITION_STATE_CHECKED, TRANSITION_STATE_UNCHECKED } = CHECKBOX_CONSTANTS.strings;
-        if (this._adapter.isIndeterminate()) {
-            return TRANSITION_STATE_INDETERMINATE;
-        }
-        return this._adapter.isChecked() ? TRANSITION_STATE_CHECKED : TRANSITION_STATE_UNCHECKED;
-    }
-    _updateAriaChecked() {
-        const { ARIA_CHECKED_INDETERMINATE_VALUE, ARIA_CHECKED_ATTR } = CHECKBOX_CONSTANTS.strings;
-        // Ensure aria-checked is set to mixed if checkbox is in indeterminate state.
-        if (this._adapter.isIndeterminate()) {
-            this._adapter.setNativeAttribute(ARIA_CHECKED_ATTR, ARIA_CHECKED_INDETERMINATE_VALUE);
-            this._adapter.setRootClass(CHECKBOX_CONSTANTS.classes.INDETERMINATE);
-            if (!this._adapter.isChecked()) {
-                this._adapter.removeRootClass(CHECKBOX_CONSTANTS.classes.CHECKED);
-            }
-        }
-        else {
-            // The on/off state does not need to keep track of aria-checked, since
-            // the screenreader uses the checked property on the checkbox element.
-            this._adapter.removeNativeAttribute(ARIA_CHECKED_ATTR);
-            this._adapter.removeRootClass(CHECKBOX_CONSTANTS.classes.INDETERMINATE);
-        }
+    syncValidity(hasCustomValidityError) {
+        this._adapter.syncValidity(hasCustomValidityError);
     }
-    _handleInputChange() {
-        this._handleInputAttributeChange();
-        this._updateCheckboxStateClasses();
-        this._transitionCheckState();
+    setValidity(flags, message) {
+        this._adapter.setValidity(flags, message);
     }
-    _transitionCheckState() {
-        if (!this._adapter.isAttachedToDOM()) {
+    _handleChange(evt) {
+        if (this.readonly) {
+            this._adapter.setChecked(this._checked);
+            evt.stopPropagation();
             return;
         }
-        const oldState = this._currentCheckState;
-        const newState = this._determineCheckState();
-        if (oldState === newState) {
+        const target = evt.target;
+        const oldValue = this._checked;
+        const newValue = target.checked;
+        this._checked = newValue;
+        const isCancelled = !this._adapter.redispatchEvent(evt, { cancelable: true });
+        if (isCancelled) {
+            this._checked = oldValue;
+            this._adapter.setChecked(this._checked);
             return;
         }
-        this._updateAriaChecked();
-        const { TRANSITION_STATE_UNCHECKED } = CHECKBOX_CONSTANTS.strings;
-        const { SELECTED } = CHECKBOX_CONSTANTS.classes;
-        if (newState === TRANSITION_STATE_UNCHECKED) {
-            this._adapter.removeRootClass(SELECTED);
-        }
-        else {
-            this._adapter.setRootClass(SELECTED);
-        }
-        // Check to ensure that there isn't a previously existing animation class, in case for example
-        // the user interacted with the checkbox before the animation was finished.
-        if (this._currentAnimationClass.length > 0) {
-            clearTimeout(this._animEndLatchTimer);
-            this._adapter.removeRootClass(this._currentAnimationClass);
-        }
-        // Check to ensure that there isn't a previously existing animation class, in case for example
-        // the user interacted with the checkbox before the animation was finished.
-        if (this._currentAnimationClass.length > 0) {
-            clearTimeout(this._animEndLatchTimer);
-            this._adapter.removeRootClass(this._currentAnimationClass);
+        this._adapter.syncValue(this._submittedValue, this._formState);
+        this._adapter.toggleHostAttribute(CHECKBOX_CONSTANTS.attributes.CHECKED, this._checked);
+        // Toggle inderminate off after a user action
+        this._indeterminate = false;
+        this._adapter.setIndeterminate(this._indeterminate);
+        this._adapter.toggleHostAttribute(CHECKBOX_CONSTANTS.attributes.INDETERMINATE, this._indeterminate);
+    }
+    _handleInputSlotChange() {
+        this._adapter.detectInputElement();
+    }
+    get checked() {
+        return this._checked;
+    }
+    set checked(value) {
+        if (this._checked !== value) {
+            this._checked = value;
+            this._adapter.setChecked(this._checked);
+            this._adapter.syncValue(this._submittedValue, this._formState);
+            this._adapter.toggleHostAttribute(CHECKBOX_CONSTANTS.attributes.CHECKED, this._checked);
         }
-        this._currentAnimationClass = this._getTransitionAnimationClass(oldState, newState);
-        this._currentCheckState = newState;
-        // Check for parentNode so that animations are only run when the element is attached
-        // to the DOM.
-        if (this._adapter.isAttachedToDOM() && this._currentAnimationClass.length > 0) {
-            this._adapter.setRootClass(this._currentAnimationClass);
-            this._enableAnimationEndHandler = true;
+    }
+    get defaultChecked() {
+        return this._defaultChecked;
+    }
+    set defaultChecked(value) {
+        if (this._defaultChecked !== value) {
+            this._defaultChecked = value;
+            this._adapter.setDefaultChecked(this._defaultChecked);
+            this._adapter.toggleHostAttribute(CHECKBOX_CONSTANTS.attributes.DEFAULT_CHECKED, this._defaultChecked);
         }
     }
-    _handleInputAttributeChange() {
-        if (this._adapter.isDisabled()) {
-            this._adapter.setRootClass(CHECKBOX_CONSTANTS.classes.DISABLED);
-            this._adapter.setWrapperClass(CHECKBOX_CONSTANTS.classes.WRAPPER_DISABLED);
-            this._adapter.removeRootClass(CHECKBOX_CONSTANTS.classes.ENABLED);
+    get indeterminate() {
+        return this._indeterminate;
+    }
+    set indeterminate(value) {
+        if (this._indeterminate !== value) {
+            this._indeterminate = value;
+            this._adapter.setIndeterminate(this._indeterminate);
+            this._adapter.syncValue(this._submittedValue, this._formState);
+            this._adapter.toggleHostAttribute(CHECKBOX_CONSTANTS.attributes.INDETERMINATE, this._indeterminate);
         }
-        else {
-            this._adapter.removeRootClass(CHECKBOX_CONSTANTS.classes.DISABLED);
-            this._adapter.removeWrapperClass(CHECKBOX_CONSTANTS.classes.WRAPPER_DISABLED);
-            this._adapter.setRootClass(CHECKBOX_CONSTANTS.classes.ENABLED);
+    }
+    get value() {
+        return this._value;
+    }
+    set value(value) {
+        if (this._value !== value) {
+            this._value = value;
+            this._adapter.setValue(this._value);
+            this._adapter.syncValue(this._submittedValue, this._formState);
+            this._adapter.setHostAttribute(CHECKBOX_CONSTANTS.attributes.VALUE, this._value);
         }
-        this._updateCheckboxStateClasses();
-    }
-    _getTransitionAnimationClass(oldState, newState) {
-        const { TRANSITION_STATE_CHECKED, TRANSITION_STATE_UNCHECKED } = CHECKBOX_CONSTANTS.strings;
-        const { ANIM_UNCHECKED_CHECKED, ANIM_UNCHECKED_INDETERMINATE, ANIM_CHECKED_UNCHECKED, ANIM_CHECKED_INDETERMINATE, ANIM_INDETERMINATE_CHECKED, ANIM_INDETERMINATE_UNCHECKED } = CHECKBOX_CONSTANTS.classes;
-        switch (oldState) {
-            case TRANSITION_STATE_UNCHECKED:
-                return newState === TRANSITION_STATE_CHECKED ? ANIM_UNCHECKED_CHECKED : ANIM_UNCHECKED_INDETERMINATE;
-            case TRANSITION_STATE_CHECKED:
-                return newState === TRANSITION_STATE_UNCHECKED ? ANIM_CHECKED_UNCHECKED : ANIM_CHECKED_INDETERMINATE;
-            default:
-                // TRANSITION_STATE_INDETERMINATE
-                // Handles TRANSITION_STATE_INIT
-                return newState === TRANSITION_STATE_CHECKED ? ANIM_INDETERMINATE_CHECKED : ANIM_INDETERMINATE_UNCHECKED;
+    }
+    get dense() {
+        return this._dense;
+    }
+    set dense(value) {
+        if (this._dense !== value) {
+            this._dense = value;
+            this._adapter.toggleHostAttribute(CHECKBOX_CONSTANTS.attributes.DENSE, this._dense);
         }
     }
-    _updateCheckboxStateClasses() {
-        // Since we can't use the ::slotted():checked ~ selector, simulating the same functionality with classes
-        if (this._adapter.isChecked()) {
-            this._adapter.setRootClass(CHECKBOX_CONSTANTS.classes.CHECKED);
+    get disabled() {
+        return this._disabled;
+    }
+    set disabled(value) {
+        if (this._disabled !== value) {
+            this._disabled = value;
+            this._adapter.setDisabled(this.disabled);
+            this._adapter.toggleHostAttribute(CHECKBOX_CONSTANTS.attributes.DISABLED, this._disabled);
         }
-        else {
-            this._adapter.removeRootClass(CHECKBOX_CONSTANTS.classes.CHECKED);
+    }
+    get required() {
+        return this._required;
+    }
+    set required(value) {
+        if (this._required !== value) {
+            this._required = value;
+            this._adapter.setRequired(this._required);
+            this._adapter.toggleHostAttribute(CHECKBOX_CONSTANTS.attributes.REQUIRED, this._required);
         }
-        if (this._adapter.isIndeterminate()) {
-            this._adapter.setRootClass(CHECKBOX_CONSTANTS.classes.INDETERMINATE);
-            this._adapter.removeRootClass(CHECKBOX_CONSTANTS.classes.CHECKED);
+    }
+    get readonly() {
+        return this._readonly;
+    }
+    set readonly(value) {
+        if (this._readonly !== value) {
+            this._readonly = value;
+            this._adapter.setReadonly(this._readonly);
+            this._adapter.toggleHostAttribute(CHECKBOX_CONSTANTS.attributes.READONLY, this._readonly);
         }
-        else {
-            this._adapter.removeRootClass(CHECKBOX_CONSTANTS.classes.INDETERMINATE);
+    }
+    get labelPosition() {
+        return this._labelPosition;
+    }
+    set labelPosition(value) {
+        if (this.labelPosition !== value) {
+            this._labelPosition = value;
+            this._adapter.setLabelPosition(this._labelPosition);
+            this._adapter.setHostAttribute(CHECKBOX_CONSTANTS.attributes.LABEL_POSITION, this._labelPosition);
         }
     }
 }

package/esm/checkbox/checkbox.d.ts

@@ -3,9 +3,18 @@
  * Copyright 2023 Tyler Technologies, Inc. 
  * License: Apache-2.0
  */
-import { BaseComponent, IBaseComponent } from '../core/base/base-component';
-export interface ICheckboxComponent extends IBaseComponent {
+import { internals } from '../constants';
+import { BaseNullableFormComponent, IBaseNullableFormComponent } from '../core/base/base-nullable-form-component';
+import { ILabelAware } from '../label/label-aware';
+import { CheckboxLabelPosition, CheckboxState } from './checkbox-constants';
+export interface ICheckboxComponent extends IBaseNullableFormComponent, ILabelAware {
+    checked: boolean;
+    defaultChecked: boolean;
+    indeterminate: boolean;
     dense: boolean;
+    labelPosition: CheckboxLabelPosition;
+    toggle(force?: boolean): void;
+    setFormValue(value: string | File | FormData | null, state?: string | File | FormData | null | undefined): void;
 }
 declare global {
     interface HTMLElementTagNameMap {
@@ -13,18 +22,120 @@ declare global {
     }
 }
 /**
- * The custom element class behind the `<forge-checkbox>` element.
- *
  * @tag forge-checkbox
+ *
+ * @summary Checkboxes select single values for submission in a form.
+ *
+ * @description
+ * Use checkboxes to:
+ * - Select one or multiple items from a list.
+ * - Present a list containing sub-selections.
+ * - Turn an option on or off in desktop environment.
+ *
+ * @property {boolean} checked - Whether the checkbox is checked.
+ * @property {boolean} defaultChecked - Whether the checkbox is checked by default.
+ * @property {boolean} indeterminate - Toggles the indeterminate state. This does not affect whether the checkbox is checked or its form submission.
+ * @property {string} value - The value of the checkbox when checked.
+ * @property {boolean} disabled - Controls if the checkbix is disabled.
+ * @property {boolean} required = Controls if the checkbox is required.
+ * @property {boolean} readonly = Controls if the checkbox is readonly.
+ * @property {boolean} dense - The density state.
+ * @property {SwitchLabelPosition} labelPosition - Whether the label appears before or after the checkbox.
+ *
+ * @attribute {string} checked - Controls whether the checkbox is checked.
+ * @attribute {string} defaultChecked - Controls whether the checkbox is checked by default.
+ * @attribute {string} indeterminate - Controls the indeterminate state.
+ * @attribute {string} value - The value of the checkbox when checked.
+ * @attribute {string} disabled - Controls if the switch is disabled.
+ * @attribute {string} required - Controls if the switch is required.
+ * @attribute {string} readonly - Controls if the switch is readonly.
+ * @attribute {string} dense - Sets the density state.
+ * @attribute {string} label-position - Sets whether the label appears before or after the switch.
+ *
+ * @method {(force?: boolean) => void} toggle - Toggles whether the checkbox is is checked or forces a checked state.
+ *
+ * @event {Event} change - Dispatches when the checkbox is checked or unchecked.
+ *
+ * @cssproperty --forge-theme-tertiary - The primary color of the checkbox.
+ * @cssproperty --forge-theme-on-tertiary - The color of the checkmark and indeterminate mark.
+ * @cssproperty --forge-checkbox-primary-color - The primary color of the checkbox.
+ * @cssproperty --forge-checkbox-size - The inline and block size of the checkbox.
+ * @cssproperty --forge-checkbox-border-width - The width of the checkbox border.
+ * @cssproperty --forge-checkbox-state-layer-size - The inline and block size of the state layer.
+ * @cssproperty --forge-checkbox-state-layer-dense-size - The inline and block size of the state layer when dense.
+ * @cssproperty --forge-checkbox-background-color - The color of the checkbox background when unchecked and not indeterminate.
+ * @cssproperty --forge-checkbox-width - The inline size of the checkbox.
+ * @cssproperty --forge-checkbox-height - The block size of the checkbox.
+ * @cssproperty --forge-checkbox-unchecked-border-width - The width of the checkbox border when unchecked and not indeterminate.
+ * @cssproperty --forge-checkbox-unchecked-border-color - The color of the checkbox border when unchecked and not indeterminate.
+ * @cssproperty --forge-checkbox-shape - The shape of the checkbox.
+ * @cssproperty --forge-checkbox-elevation - The shadow of the checkbox.
+ * @cssproperty --forge-checkbox-gap - The space between the checkbox and label.
+ * @cssproperty --forge-checkbox-justify - How the checkbox and label are distributed along their main axis.
+ * @cssproperty --forge-checkbox-direction - Whether the checkbox and label are arranged along the inline or block axis.
+ * @cssproperty --forge-checkbox-checked-background-color - The color of the checkbox background when checked or indeterminate.
+ * @cssproperty --forge-checkbox-checked-border-width - The width of the checkbox border when checked or indeterminate.
+ * @cssproperty --forge-checkbox-checked-border-color - The color of the checkbox border when checked or indeterminate.
+ * @cssproperty --forge-checkbox-icon-color - The color of the checkmark and indeterminate mark.
+ * @cssproperty --forge-checkbox-icon-checked-color - The color of the checkmark mark.
+ * @cssproperty --forge-checkbox-icon-indeterminate-color - The color of the indeterminate mark.
+ * @cssproperty --forge-checkbox-icon-stroke-width - The stroke width of the checkmark and indeterminate marks.
+ * @cssproperty --forge-checkbox-state-layer-width - The inline size of the state layer.
+ * @cssproperty --forge-checkbox-state-layer-width - The inline size of the state layer.
+ * @cssproperty --forge-checkbox-state-layer-height - The block size of the state layer.
+ * @cssproperty --forge-checkbox-state-layer-checked-color - The color of the state layer when checked.
+ * @cssproperty --forge-checkbox-state-layer-unchecked-color - The color of the state layer when unchecked.
+ * @cssproperty --forge-checkbox-state-layer-shape - The shape of the state layer.
+ * @cssproperty --forge-checkbox-state-layer-dense-width - The inline size of the state layer when dense.
+ * @cssproperty --forge-checkbox-state-layer-dense-height - The block size of the state layer when dense.
+ * @cssproperty --forge-checkbox-disabled-opacity - The opacity when disabled.
+ * @cssproperty --forge-checkbox-animation-duration - The duration of animations.
+ * @cssproperty --forge-checkbox-background-animation-timing - The timing function of the background animations.
+ * @cssproperty --forge-checkbox-icon-animation-timing - The timing function of the checked and indeterminate icons animations.
+ *
+ * @csspart checkbox - Styles the checkbox container element.
+ * @csspart background - Styles the checkbox background element.
+ * @csspart checkmark - Styles the checkmark element.
+ * @csspart mixedmark - Styles the indeterminate mark element.
+ * @csspart label - Styles the label element.
+ * @csspart state-layer - Styles the state layer element.
+ * @csspart focus-indicator - Styles the focus indicator element.
  */
-export declare class CheckboxComponent extends BaseComponent implements ICheckboxComponent {
+export declare class CheckboxComponent extends BaseNullableFormComponent implements ICheckboxComponent {
     static get observedAttributes(): string[];
+    get name(): string;
+    set name(value: string);
+    get form(): HTMLFormElement | null;
+    get labels(): NodeList;
+    get validity(): ValidityState;
+    get validationMessage(): string;
+    get willValidate(): boolean;
+    readonly [internals]: ElementInternals;
     private _foundation;
     constructor();
-    connectedCallback(): Promise<void>;
+    connectedCallback(): void;
     attributeChangedCallback(name: string, oldValue: string, newValue: string): void;
-    disconnectedCallback(): void;
-    /** Gets or sets whether or not the checkbox is dense */
+    setFormValue(value: string | File | FormData | null, state?: string | File | FormData | null | undefined): void;
+    checkValidity(): boolean;
+    reportValidity(): boolean;
+    setCustomValidity(error: string): void;
+    formResetCallback(): void;
+    formStateRestoreCallback(state: CheckboxState, reason: 'restore' | 'autocomplete'): void;
+    formDisabledCallback(isDisabled: boolean): void;
+    labelClickedCallback(): void;
+    labelChangedCallback(value: string | null): void;
+    checked: boolean;
+    defaultChecked: boolean;
+    indeterminate: boolean;
+    value: string;
     dense: boolean;
-    private _ensureInputElement;
+    disabled: boolean;
+    required: boolean;
+    readonly: boolean;
+    labelPosition: CheckboxLabelPosition;
+    /**
+     * Toggles the checkbox checked or unchecked.
+     * @param force Whether to set the checkbox checked or unchecked.
+     */
+    toggle(force?: boolean): void;
 }