@aurodesignsystem/auro-formkit 5.10.0 → 5.11.0

package/components/form/dist/registered.js

@@ -106,26 +106,31 @@ class AuroLibraryRuntimeUtils {
  *
  * @slot default - The default slot for form elements.
  *
- * @event {Event} change - Fires when form state changes.
+ * @event input - Fires when a child form element receives user input.
+ * @event change - Fires when a child form element's value changes or the form is initialized.
+ * @event reset - Fires when the form is reset. The event detail contains the previous value of the form before reset.
+ * @event submit - Fires when the form is submitted. The event detail contains the current value of the form.
  */
 class AuroForm extends LitElement {
   static get properties() {
     return {
 
-      /**
-       * Applies designated CSS class to demo element - you want to delete me!
-       */
-      cssClass: { type: Boolean },
-
-      /**
-       * If declared, use fixed pixel values for element shape.
-       */
-      fixed: { type: Boolean, reflect: true },
+      /** @private */
       formState: { type: Object, attribute: false },
+
+      /** @private */
       _validity: { type: Object, attribute: false },
+
+      /** @private */
       _isInitialState: { type: Boolean, attribute: false },
+
+      /** @private */
       _elements: { type: Array, attribute: false },
+
+      /** @private */
       _submitElements: { type: Array, attribute: false },
+
+      /** @private */
       _resetElements: { type: Array, attribute: false },
     };
   }
@@ -133,20 +138,37 @@ class AuroForm extends LitElement {
   constructor() {
     super();
 
-    /** @type {FormState} */
+    /**
+     * @type {FormState}
+     * @private
+     */
     this.formState = {};
 
-    /** @type {"valid" | "invalid" | null} */
+    /**
+     * @type {"valid" | "invalid" | null}
+     * @private
+     */
     this._validity = null;
+
+    /** @private */
     this._isInitialState = true;
 
-    /** @type {(HTMLElement & {reset: () => void})[]} */
+    /**
+     * @type {(HTMLElement & {reset: () => void})[]}
+     * @private
+     */
     this._elements = [];
 
-    /** @type {HTMLButtonElement[]} */
+    /**
+     * @type {HTMLButtonElement[]}
+     * @private
+     */
     this._submitelements = [];
 
-    /** @type {HTMLButtonElement[]} */
+    /**
+     * @type {HTMLButtonElement[]}
+     * @private
+     */
     this._resetElements = [];
 
     /**
@@ -156,11 +178,23 @@ class AuroForm extends LitElement {
     this.mutationObservers = [];
 
     // Bind listeners
+    /** @private */
     this.reset = this.reset.bind(this);
+
+    /** @private */
     this.submit = this.submit.bind(this);
+
+    /** @private */
     this.sharedInputListener = this.sharedInputListener.bind(this);
+
+    /** @private */
     this.sharedValidationListener = this.sharedValidationListener.bind(this);
+
+    /** @private */
     this.mutationEventListener = this.mutationEventListener.bind(this);
+
+    /** @private */
+    this.handleKeyDown = this.handleKeyDown.bind(this);
   }
 
   // Note: button is NOT considered a form element in this context
@@ -205,6 +239,7 @@ class AuroForm extends LitElement {
    * Check if the tag name is a form element.
    * @param {HTMLElement} element - The element to check (attr or tag name).
    * @returns {boolean}
+   * @private
    */
   isFormElement(element) {
     return this._isInElementCollection(AuroForm.formElementTags, element);
@@ -233,6 +268,7 @@ class AuroForm extends LitElement {
    * Check if the tag name is a button element.
    * @param {HTMLElement} element - The element to check.
    * @returns {boolean}
+   * @private
    */
   isButtonElement(element) {
     return this._isInElementCollection(AuroForm.buttonElementTags, element);
@@ -243,13 +279,8 @@ class AuroForm extends LitElement {
   }
 
   /**
-   * Reduce the form value into a key-value pair.
-   *
-   * NOTE: form keys use `name` first, and `id` second if `name` is not available.
-   * This follows standard HTML5 form behavior - submission uses `name` by default when creating
-   * the FormData object.
-   *
-   * @returns {Record<string, string | number | boolean | string[] | null>} The form value.
+   * Returns the current values of all named form elements as a key-value object, keyed by each element's `name` attribute.
+   * @returns {Record<string, string | number | boolean | string[] | null>} The current form values.
    */
   get value() {
     return Object.keys(this.formState).reduce((acc, key) => {
@@ -261,6 +292,7 @@ class AuroForm extends LitElement {
   /**
    * Getter for internal _submitElements.
    * @returns {HTMLButtonElement[]}
+   * @private
    */
   get submitElements() {
     return this._submitelements;
@@ -269,6 +301,7 @@ class AuroForm extends LitElement {
   /**
    * Returns a collection of elements that will reset the form.
    * @returns {HTMLButtonElement[]}
+   * @private
    */
   get resetElements() {
     return this._resetElements;
@@ -295,8 +328,8 @@ class AuroForm extends LitElement {
   }
 
   /**
-   * Current validity state of the form, based on form element events.
-   * @returns {"valid" | "invalid"}
+   * Returns `'valid'` if all required and interacted-with form elements are valid, `'invalid'` if any are not, or `null` if the form has not been interacted with yet.
+   * @returns {"valid" | "invalid" | null}
    */
   get validity() {
     // Force calculate, as sometimes validity won't reflect
@@ -305,6 +338,11 @@ class AuroForm extends LitElement {
     return this._validity;
   }
 
+  /**
+   * Determines whether the form is in its initial (untouched) state and updates `_isInitialState` accordingly.
+   * @returns {void}
+   * @private
+   */
   _setInitialState() {
     const anyTainted = Object.keys(this.formState).some((key) => this.formState[key].validity !== null || this.formState[key].value !== null);
 
@@ -318,13 +356,18 @@ class AuroForm extends LitElement {
   }
 
   /**
-   * Mostly internal way to determine if a form is in the initial state.
+   * Returns `true` if no form element has been interacted with or had its value changed since the form was initialized or last reset.
    * @returns {boolean}
    */
   get isInitialState() {
     return this._isInitialState;
   }
 
+  /**
+   * Enables or disables submit and reset buttons based on the current form state and validity.
+   * @returns {void}
+   * @private
+   */
   setDisabledStateOnButtons() {
     this._resetElements.forEach((element) => {
       if (this.isInitialState) {
@@ -346,6 +389,7 @@ class AuroForm extends LitElement {
   /**
    * Construct the query strings from elements, append them together, execute, and return the NodeList.
    * @returns {NodeList}
+   * @private
    */
   queryAuroElements() {
     const queries = [
@@ -392,6 +436,8 @@ class AuroForm extends LitElement {
 
   /**
    * Initialize (or reinitialize) the form state.
+   * @returns {void}
+   * @private
    */
   initializeState() {
     this.formState = {};
@@ -432,7 +478,8 @@ class AuroForm extends LitElement {
   }
 
   /**
-   * Reset fires an event called `reset` - just as you would expect from a normal form.
+   * Resets all form elements to their initial state and fires a `reset` event. The event's `detail.previousValue` contains the form values captured immediately before the reset.
+   * @returns {void}
    */
   reset() {
     const previousValue = this.value;
@@ -460,36 +507,36 @@ class AuroForm extends LitElement {
   }
 
   /**
-   * Submit fires an event called `submit` - just as you would expect from a normal form.
+   * Validates all form elements. If all are valid, fires a `submit` event with `detail.value` containing the current form values. If any element is invalid, its error state is surfaced and the `submit` event is not fired.
+   * @returns {Promise<void>}
    */
-  submit() {
-    // Steps required to get out of beta:
-    // 1. Submit triggers a forced validation on ALL elements
-    // 2. Wait for validation to complete (this.updateComplete.then or similar)
-    // 3. If still valid, go ahead with submit.
+  async submit() {
+    // Force validation on ALL elements
     this._elements.forEach((element) => {
-      if (element.tagName.toLowerCase() !== "auro-datepicker") {
-        // Next line currently does NOT force
-        element.validate();
-      }
+      element.validate(true);
     });
 
-    this.dispatchEvent(new CustomEvent('submit', {
-      bubbles: true,
-      composed: true,
-      detail: {
-        value: this.value
-      }
-    }));
+    // Wait for validation to complete and formState to update
+    await this.updateComplete;
+
+    // Only dispatch submit event if form is valid
+    if (this.validity === 'valid') {
+      this.dispatchEvent(new CustomEvent('submit', {
+        bubbles: true,
+        composed: true,
+        detail: {
+          value: this.value
+        }
+      }));
+    }
   }
 
   /**
-   * This will register this element with the browser.
-   * @param {string} [name="auro-form"] - The name of element that you want to register to.
+   * Registers the `auro-form` custom element with the browser under a given tag name.
+   * @param {string} [name="auro-form"] - The custom element tag name to register.
    *
    * @example
-   * AuroForm.register("custom-form") // this will register this element to <custom-form/>
-   *
+   * AuroForm.register("custom-form") // registers as <custom-form>
    */
   static register(name = "auro-form") {
     AuroLibraryRuntimeUtils.prototype.registerComponent(name, AuroForm);
@@ -497,8 +544,8 @@ class AuroForm extends LitElement {
 
   /**
    * Shared input listener for all form elements.
-   * @private
    * @param {Event} event - The event that is fired from the form element.
+   * @private
    */
   sharedInputListener(event) {
     const targetName = event.target.getAttribute("name");
@@ -530,8 +577,8 @@ class AuroForm extends LitElement {
 
   /**
    * Shared validation listener for all form elements.
-   * @private
    * @param {Event} event - The event that is fired from the form element.
+   * @private
    */
   sharedValidationListener(event) {
     const targetName = event.target.getAttribute("name");
@@ -548,24 +595,58 @@ class AuroForm extends LitElement {
     this.requestUpdate('formState');
   }
 
+  /**
+   * Handle Enter key press on form elements.
+   * @param {KeyboardEvent} event - The keyboard event.
+   * @private
+   */
+  handleKeyDown(event) {
+    if (event.key === 'Enter' && this.isFormElement(event.target)) {
+      // Don't submit if it's a textarea (allow new lines)
+      if (event.target.tagName.toLowerCase() === 'textarea' ||
+          event.target.hasAttribute('textarea')) {
+        return;
+      }
+
+      event.preventDefault();
+      this.submit();
+    }
+  }
+
+  /**
+   * Attaches input, validation, and keydown listeners to all tracked form and button elements.
+   * Removes existing listeners first to avoid duplicates on re-initialization.
+   * @returns {void}
+   * @private
+   */
   _attachEventListeners() {
     this.queryAuroElements().forEach((element) => {
       // remove any existing event listeners (in case of re-initialization)
       element.removeEventListener('input', this.sharedInputListener);
       element.removeEventListener('auroFormElement-validated', this.sharedValidationListener);
+      element.removeEventListener('keydown', this.handleKeyDown);
 
       // add new event listeners
       element.addEventListener('input', this.sharedInputListener);
       element.addEventListener('auroFormElement-validated', this.sharedValidationListener);
+      element.addEventListener('keydown', this.handleKeyDown);
     });
   }
 
+  /**
+   * @param {import('lit').PropertyValues} _changedProperties - Map of changed properties with their previous values.
+   * @returns {void}
+   */
   firstUpdated(_changedProperties) {
     super.firstUpdated(_changedProperties);
 
     this._attachEventListeners();
   }
 
+  /**
+   * @param {import('lit').PropertyValues} _changedProperties - Map of changed properties with their previous values.
+   * @returns {void}
+   */
   updated(_changedProperties) {
     super.updated(_changedProperties);
 
@@ -586,8 +667,8 @@ class AuroForm extends LitElement {
    * root-level elements are added/removed. This is a workaround to ensure
    * nested form elements are also observed.
    *
-   * @private
    * @returns {void}
+   * @private
    */
   mutationEventListener() {
     this.initializeState();
@@ -598,6 +679,7 @@ class AuroForm extends LitElement {
    * Slot change event listener. This is the main entry point for the form element.
    * @param {Event} event - The slot change event.
    * @returns {void}
+   * @private
    */
   onSlotChange(event) {
     this.initializeState();
@@ -621,7 +703,9 @@ class AuroForm extends LitElement {
     });
   }
 
-  // function that renders the HTML and CSS into the scope of the component
+  /**
+   * @returns {import('lit').TemplateResult}
+   */
   render() {
     return html`
         <form>

package/components/input/demo/api.md

@@ -9,6 +9,7 @@ The `auro-input` element provides users a way to enter data into a text field.
 
 | Property                          | Attribute                         | Type                                             | Default     | Description                                      |
 |-----------------------------------|-----------------------------------|--------------------------------------------------|-------------|--------------------------------------------------|
+| `a11yActivedescendant`            | `a11yActivedescendant`            | `string`                                         |             | The value for the aria-activedescendant attribute.<br />Points to the ID of the currently active/highlighted option in a listbox. |
 | `a11yControls`                    | `a11yControls`                    | `string`                                         |             | The value for the aria-controls attribute.       |
 | `a11yExpanded`                    | `a11yExpanded`                    | `boolean`                                        |             | The value for the aria-expanded attribute.       |
 | `a11yRole`                        | `a11yRole`                        | `string`                                         |             | The value for the role attribute.                |

package/components/input/demo/api.min.js

@@ -4964,7 +4964,7 @@ class AuroFormValidation {
         }
       }
 
-      if (!hasValue && elem.required && elem.touched) {
+      if (!hasValue && elem.required && (force || elem.touched)) {
         elem.validity = 'valueMissing';
         elem.errorMessage = elem.setCustomValidityValueMissing || elem.setCustomValidity || '';
       } else if (hasValue && this.runtimeUtils.elementMatch(elem, 'auro-input')) {
@@ -4988,7 +4988,7 @@ class AuroFormValidation {
       if (!isCombobox || isCombobox && !elem.persistInput) {
 
         // run validation on all inputs since we're going to use them to set the validity of this component
-        this.auroInputElements.forEach(input => input.validate());
+        this.auroInputElements.forEach(input => input.validate(force));
 
         // Reset element validity to the validity of the input
         elem.validity = this.auroInputElements[0].validity;
@@ -5194,6 +5194,17 @@ class AuroElement extends i$3 {
  */
 class BaseInput extends AuroElement {
 
+  // Delegate focus to the native <input> inside the shadow root so that
+  // showModal()'s dialog focusing steps reach the input element.
+  // This keeps the mobile virtual keyboard open when the fullscreen dialog
+  // opens, because the browser sees an input-to-input focus transfer.
+  static get shadowRootOptions() {
+    return {
+      ...AuroElement.shadowRootOptions,
+      delegatesFocus: true,
+    };
+  }
+
   constructor() {
     super();
 
@@ -5211,6 +5222,7 @@ class BaseInput extends AuroElement {
     this.icon = false;
     this.disabled = false;
     this.dvInputOnly = false;
+    this.hideLabelVisually = false;
     this.max = undefined;
     this.maxLength = undefined;
     this.min = undefined;
@@ -5318,6 +5330,15 @@ class BaseInput extends AuroElement {
         reflect: true
       },
 
+      /**
+       * The value for the aria-activedescendant attribute.
+       * Points to the ID of the currently active/highlighted option in a listbox.
+       */
+      a11yActivedescendant: {
+        type: String,
+        reflect: true
+      },
+
       /**
        * If set, the label will remain fixed in the active position.
        */
@@ -5424,6 +5445,16 @@ class BaseInput extends AuroElement {
         attribute: false
       },
 
+      /**
+       * If set, the label will be hidden visually but still accessible to assistive technologies.
+       * @private
+       */
+      hideLabelVisually: {
+        type: Boolean,
+        reflect: true
+      },
+
+
       /**
        * If set, will render an icon inside the input to the left of the value. Support is limited to auro-input instances with credit card format.
        */
@@ -6001,31 +6032,34 @@ class BaseInput extends AuroElement {
     // Process credit card type detection and formatting during input
     if (this.type === 'credit-card') {
       this.processCreditCard();
-    }
+      this.touched = true;
+      this.validation.validate(this);
+    } else {
 
-    // Sets value property to value of element value (el.value).
-    this.value = this.inputElement.value;
+      // Sets value property to value of element value (el.value).
+      this.value = this.inputElement.value;
 
-    // Determine if the value change was programmatic, including autofill.
-    const inputWasProgrammatic = !this.matches(":focus") || event.isProgrammatic;
+      // Determine if the value change was programmatic, including autofill.
+      const inputWasProgrammatic = !this.matches(":focus") || event.isProgrammatic;
 
-    // Validation on input or programmatic value change (including autofill).
-    if (this.validateOnInput || inputWasProgrammatic) {
-      this.touched = true;
-      this.validation.validate(this);
-    }
+      // Validation on input or programmatic value change (including autofill).
+      if (this.validateOnInput || inputWasProgrammatic) {
+        this.touched = true;
+        this.validation.validate(this);
+      }
 
-    // Prevents cursor jumping in Safari.
-    const { selectionStart } = this.inputElement;
+      // Prevents cursor jumping in Safari.
+      const { selectionStart } = this.inputElement;
 
-    if (this.setSelectionInputTypes.includes(this.type)) {
-      this.updateComplete.then(() => {
-        try {
-          this.inputElement.setSelectionRange(selectionStart, selectionStart);
-        } catch (error) { // eslint-disable-line
-          // do nothing
-        }
-      });
+      if (this.setSelectionInputTypes.includes(this.type)) {
+        this.updateComplete.then(() => {
+          try {
+            this.inputElement.setSelectionRange(selectionStart, selectionStart);
+          } catch (error) { // eslint-disable-line
+            // do nothing
+          }
+        });
+      }
     }
   }
 
@@ -6058,6 +6092,11 @@ class BaseInput extends AuroElement {
     this.inputElement.scrollLeft = 100;
 
     if (!this.noValidate) {
+      // For credit card inputs with mask, ensure value is synced from mask instance
+      if (this.type === 'credit-card' && this.maskInstance) {
+        this.value = this.maskInstance.value;
+      }
+
       this.validation.validate(this);
     }
   }
@@ -6082,6 +6121,20 @@ class BaseInput extends AuroElement {
     return activeEl;
   }
 
+  /**
+   * Sets the active descendant element for accessibility.
+   * Uses ariaActiveDescendantElement to cross shadow DOM boundaries.
+   * This function is used in components that contain `auro-input` to set the active descendant.
+   * @private
+   * @param {HTMLElement|null} element - The element to set as the active descendant, or null to clear.
+   * @returns {void}
+   */
+  setActiveDescendant(element) {
+    if (this.inputElement) {
+      this.inputElement.ariaActiveDescendantElement = element;
+    }
+  }
+
   /**
    * Validates value.
    * @param {boolean} [force=false] - Whether to force validation.
@@ -6706,7 +6759,7 @@ class AuroHelpText extends i$3 {
   }
 }
 
-var formkitVersion = '202602140013';
+var formkitVersion = '202603102257';
 
 // Copyright (c) 2025 Alaska Airlines. All right reserved. Licensed under the Apache-2.0 license
 // See LICENSE in the project root for license information.
@@ -6888,7 +6941,7 @@ class AuroInput extends BaseInput {
     return {
       'is-disabled': this.disabled,
       'withValue': this.hasValue,
-      'util_displayHiddenVisually': this.labelHidden,
+      'util_displayHiddenVisually': this.labelHidden || this.hideLabelVisually,
       [this.labelFontClass]: true,
     };
   }
@@ -7060,6 +7113,7 @@ class AuroInput extends BaseInput {
         ?activeLabel="${this.activeLabel}"
         ?disabled="${this.disabled}"
         ?required="${this.required}"
+        aria-activedescendant=${o(this.a11yActivedescendant)}
         aria-controls=${o(this.a11yControls)}
         aria-describedby="${this.uniqueId}"
         aria-expanded=${o(this.a11yExpanded)}