@aurodesignsystem/auro-formkit 3.4.1 → 3.5.0-rc-627.1.1

package/components/form/demo/index.md

@@ -17,23 +17,89 @@ It automatically "scrapes" its inner content for any auro form elements, and sur
 them (along with events) to the parent form element as a JSON object.
 <!-- AURO-GENERATED-CONTENT:END -->
 
-## Form data generation
+## Form value generation
 
-As covered in the description, `auro-form` makes a developer's life easier by surfacing Auro form elements as a JSON object.
-The most common use case the Auro team identified when building Form was the need to collect form data in a structured way.
+Auro form exists to make a developer's life easier through surfacing all Auro form elements in a given form as a single
+JSON object.
+The most common use case the Auro team identified when building Form was the need to collect form data in
+a structured way.
 
-The following is required for an Auro form element to be collected automatically:
+The following is required on each Auro form element in a form for it to be collected automatically:
 
-1. It _must_ have a `name` attribute. This is required if vanilla HTML forms, and we follow the same pattern.
-2. It _must_ be an Auro form element. See note below for custom elements.
+1. It **must** have a `name` attribute. This is required if vanilla HTML forms, and we follow the same pattern.
+2. It **must** be an Auro form element. See the section on custom elements for more information.
 
 That being said, we do _not_ require form elements to be direct children of `auro-form`.
 They can be nested within other elements for styling, such as a `div`, `span` or `fieldset`.
 
+### Form data structure
+
+In a correctly registered scenario, `auro-form`
+will automatically recognize the auro form elements and collect data from each on the form's `value` key as a JSON object.
+
+Each element will be added using the element's `name` attribute as the key, and the element's `value` as the value.
+
+A real-world example of this might be:
+
+```json
+{
+  "hotelCity": "New York",
+  "dates": ["2022-01-01", "2022-01-15"],
+  "numberOfGuests": 2
+}
+```
+
+If your project uses TypeScript, consider using a type like this to represent the form data:
+
+```typescript
+// Generic type for form values
+type AuroFormValue<T> = T | null;
+
+// Example types
+type AuroInputValue = AuroFormValue<string | number>;
+type AuroDatePickerValue = AuroFormValue<string[]>;
+
+// This is the type returned from the `AuroForm.value` getter
+interface AuroFormState {
+  // value varies based on form element
+  hotelCity: AuroInputValue;
+  dates: AuroDatePickerValue;
+  numberOfGuests: AuroInputValue;
+}
+```
+
+## Accessing form data
+
+As Auro components are designed to be framework-agnostic, data can be retrieved using simple vanilla JavaScript patterns.
+If you have ever worked with a standard HTML5 form, you are already equipped to work with Auro forms!
+
+Once you have a reference to the form element (React ref, querySelector, etc.),
+you can access the form data using the following methods:
+
+**Data keys + get methods**:
+- `.value` - Getter which returns the current form data as a JSON object.
+- `.validity` - Returns the current validity state of the form (`valid` or `invalid`).
+
+**Extra information**:
+- `.isInitialState` - Returns a boolean indicating if the form is in its initial state.
+
+**Events**
+- `input` - Fires when the form state changes.
+- `reset` - Fires when the form is reset.
+- `submit` - Fires when the form is submitted.
+
+**Advanced features**:
+- `.formState` - This is the internal form state. It includes extra `required` and `validity` information for each form element.
+This key is not required for normal form usage, but can add additional context for more complex forms.
+
 ## Important note for custom elements
 
-When consuming custom-named Auro form elements (like `auro-input` as `my-custom-input`), these elements _must_ be registered
-BEFORE auro-form due to rendering order and Shadown DOM limitations.
+This **only applies to custom-named elements**.
+
+When consuming custom-named Auro form elements (like `auro-input` registered as `my-custom-input`),
+these elements _must_ be registered BEFORE auro-form due to rendering order limitations.
+Auro form elements are automatically recognized based on their tag name (e.g. `auro-input`) or special auro attributes
+which are only assigned during the initial render.
 
 For example, the following is correct:
 
@@ -53,25 +119,6 @@ import {AuroForm} from '@aurodesignsystem/auro-form';
 
 AuroForm.register(); // forms start rendering, looking for auro inputs, or custom-named inputs
 AuroInput.register('my-custom-input'); // too late, form has already rendered and did not find the custom element
-```
-
-In a correctly registered scenario, `auro-form` will automatically recognize the custom element and collect its data in the following shape:
-
-```typescript
-interface AuroFormState {
-  // value varies based on form element
-  [key: string]: string | string[] | number | boolean | null;
-}
-```
-
-A real-world example of this might be:
-
-```json
-{
-  "hotelCity": "New York",
-  "dates": ["2022-01-01", "2022-01-15"],
-  "numberOfGuests": 2
-}
 ```
 
 ## Examples
@@ -106,4 +153,251 @@ By default, Auro Form connects a `submit` event to all `type="submit"` buttons w
 </auro-form>
 ```
 <!-- AURO-GENERATED-CONTENT:END -->
+</auro-accordion>
+
+### Form with column layout
+Auro Form is designed to be completely unstyled by default, allowing developers to use divs, structural elements, or
+custom CSS to style the form.
+
+This example shows that you can use advanced layouts with Auro Form, such as a column layout.
+
+<div class="exampleWrapper">
+  <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/column-layout.html) -->
+  <!-- The below content is automatically added from ./../apiExamples/column-layout.html -->
+  <style>
+    .columned-form {
+      display: grid;
+      grid-template-columns: 1fr 1fr;
+      gap: 1rem;
+    }
+
+    .columned-form div {
+      display: flex;
+      flex-direction: column;
+      padding: 1rem;
+    }
+
+    .controls {
+      display: flex;
+      justify-content: flex-end;
+      margin-top: 1rem;
+    }
+  </style>
+  <auro-form>
+    <div class="columned-form">
+      <div>
+        <auro-input id="search-box" name="searchBox" required>
+          <span slot="label">Search flights</span>
+        </auro-input>
+        <auro-input id="last-name" name="lastName" required>
+          <span slot="label">Last Name</span>
+        </auro-input>
+      </div>
+      <div>
+        <div class="datepickerBlock">
+          <h4>Pick a date range</h4>
+          <auro-datepicker id="date-range" name="dateRange" required range>
+            <span slot="fromLabel">Start</span>
+            <span slot="toLabel">End</span>
+            <span slot="bib.fullscreen.dateLabel">Choose a range</span>
+          </auro-datepicker>
+        </div>
+        <div class="controls">
+          <auro-button type="submit">Submit</auro-button>
+        </div>
+      </div>
+    </div>
+  </auro-form>
+  <!-- AURO-GENERATED-CONTENT:END -->
+</div>
+<auro-accordion alignRight>
+  <span slot="trigger">See code</span>
+<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/column-layout.html) -->
+<!-- The below code snippet is automatically added from ./../apiExamples/column-layout.html -->
+
+```html
+<style>
+  .columned-form {
+    display: grid;
+    grid-template-columns: 1fr 1fr;
+    gap: 1rem;
+  }
+
+  .columned-form div {
+    display: flex;
+    flex-direction: column;
+    padding: 1rem;
+  }
+
+  .controls {
+    display: flex;
+    justify-content: flex-end;
+    margin-top: 1rem;
+  }
+</style>
+<auro-form>
+  <div class="columned-form">
+    <div>
+      <auro-input id="search-box" name="searchBox" required>
+        <span slot="label">Search flights</span>
+      </auro-input>
+      <auro-input id="last-name" name="lastName" required>
+        <span slot="label">Last Name</span>
+      </auro-input>
+    </div>
+    <div>
+      <div class="datepickerBlock">
+        <h4>Pick a date range</h4>
+        <auro-datepicker id="date-range" name="dateRange" required range>
+          <span slot="fromLabel">Start</span>
+          <span slot="toLabel">End</span>
+          <span slot="bib.fullscreen.dateLabel">Choose a range</span>
+        </auro-datepicker>
+      </div>
+      <div class="controls">
+        <auro-button type="submit">Submit</auro-button>
+      </div>
+    </div>
+  </div>
+</auro-form>
+```
+<!-- AURO-GENERATED-CONTENT:END -->
+</auro-accordion>
+
+### Complex form
+Finally, a more complex form example with multiple form elements, including a date picker and a select element.
+
+<div class="exampleWrapper">
+  <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/complex.html) -->
+  <!-- The below content is automatically added from ./../apiExamples/complex.html -->
+  <style>
+    .submitBlock {
+      margin-top: 1rem;
+      display: flex;
+      justify-content: flex-end;
+      gap: 1rem;
+    }
+
+    .datepickerBlock {
+      margin-top: 1rem;
+    }
+
+    .complex-form {
+      display: block;
+      width: 100%;
+      padding: 1rem;
+      border: 1px solid #2a2a2a;
+      border-radius: 1rem;
+    }
+  </style>
+  <h2>auro-form testing</h2>
+  <auro-form class="complex-form">
+    <auro-input id="first-name" name="firstName" required>
+      <span slot="label">First Name</span>
+    </auro-input>
+    <div>
+      <auro-input id="last-name" name="lastName" required>
+        <span slot="label">Last Name</span>
+      </auro-input>
+    </div>
+    <div>
+      <div>
+        <auro-input id="occupation" name="occupation" required>
+          <span slot="label">Occupation</span>
+        </auro-input>
+      </div>
+    </div>
+    <auro-input-two id="cool-fact" name="coolFact" required>
+      <span slot="label">Cool Fact</span>
+    </auro-input-two>
+    <div class="datepickerBlock">
+      <h4>Pick a cool date</h4>
+      <auro-datepicker id="date-example" name="dateExample" required>
+        <span slot="fromLabel">Choose a date</span>
+        <span slot="bib.fullscreen.dateLabel">Choose a date</span>
+      </auro-datepicker>
+    </div>
+    <div class="datepickerBlock">
+      <h4>Pick a date range</h4>
+      <auro-datepicker id="date-range" name="dateRange" required range>
+        <span slot="fromLabel">Start</span>
+        <span slot="toLabel">End</span>
+        <span slot="bib.fullscreen.dateLabel">Choose a range</span>
+      </auro-datepicker>
+    </div>
+    <div class="submitBlock">
+      <auro-button type="reset">Reset</auro-button>
+      <auro-button type="submit">Submit</auro-button>
+    </div>
+  </auro-form>
+  <!-- AURO-GENERATED-CONTENT:END -->
+</div>
+<auro-accordion alignRight>
+  <span slot="trigger">See code</span>
+<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/complex.html) -->
+<!-- The below code snippet is automatically added from ./../apiExamples/complex.html -->
+
+```html
+<style>
+  .submitBlock {
+    margin-top: 1rem;
+    display: flex;
+    justify-content: flex-end;
+    gap: 1rem;
+  }
+
+  .datepickerBlock {
+    margin-top: 1rem;
+  }
+
+  .complex-form {
+    display: block;
+    width: 100%;
+    padding: 1rem;
+    border: 1px solid #2a2a2a;
+    border-radius: 1rem;
+  }
+</style>
+<h2>auro-form testing</h2>
+<auro-form class="complex-form">
+  <auro-input id="first-name" name="firstName" required>
+    <span slot="label">First Name</span>
+  </auro-input>
+  <div>
+    <auro-input id="last-name" name="lastName" required>
+      <span slot="label">Last Name</span>
+    </auro-input>
+  </div>
+  <div>
+    <div>
+      <auro-input id="occupation" name="occupation" required>
+        <span slot="label">Occupation</span>
+      </auro-input>
+    </div>
+  </div>
+  <auro-input-two id="cool-fact" name="coolFact" required>
+    <span slot="label">Cool Fact</span>
+  </auro-input-two>
+  <div class="datepickerBlock">
+    <h4>Pick a cool date</h4>
+    <auro-datepicker id="date-example" name="dateExample" required>
+      <span slot="fromLabel">Choose a date</span>
+      <span slot="bib.fullscreen.dateLabel">Choose a date</span>
+    </auro-datepicker>
+  </div>
+  <div class="datepickerBlock">
+    <h4>Pick a date range</h4>
+    <auro-datepicker id="date-range" name="dateRange" required range>
+      <span slot="fromLabel">Start</span>
+      <span slot="toLabel">End</span>
+      <span slot="bib.fullscreen.dateLabel">Choose a range</span>
+    </auro-datepicker>
+  </div>
+  <div class="submitBlock">
+    <auro-button type="reset">Reset</auro-button>
+    <auro-button type="submit">Submit</auro-button>
+  </div>
+</auro-form>
+```
+<!-- AURO-GENERATED-CONTENT:END -->
 </auro-accordion>

package/components/form/demo/index.min.js

@@ -153,7 +153,10 @@ class AuroForm extends i {
     /** @type {HTMLButtonElement[]} */
     this._resetElements = [];
 
-    /** @type {MutationObserver[]} */
+    /**
+     * @private
+     * @type {MutationObserver[]}
+     */
     this.mutationObservers = [];
 
     // Bind listeners
@@ -268,7 +271,7 @@ class AuroForm extends i {
   }
 
   /**
-   * Getter for internal _resetElements.
+   * Returns a collection of elements that will reset the form
    * @returns {HTMLButtonElement[]}
    */
   get resetElements() {
@@ -498,6 +501,7 @@ class AuroForm extends i {
 
   /**
    * Shared input listener for all form elements.
+   * @private
    * @param {Event} event - The event that is fired from the form element.
    */
   sharedInputListener(event) {
@@ -530,6 +534,7 @@ class AuroForm extends i {
 
   /**
    * Shared validation listener for all form elements.
+   * @private
    * @param {Event} event - The event that is fired from the form element.
    */
   sharedValidationListener(event) {
@@ -585,6 +590,7 @@ class AuroForm extends i {
    * root-level elements are added/removed. This is a workaround to ensure
    * nested form elements are also observed.
    *
+   * @private
    * @returns {void}
    */
   mutationEventListener() {

package/components/form/demo/readme.md

@@ -109,7 +109,7 @@ The use of any Auro custom element has a dependency on the [Auro Design Tokens](
 In cases where the project is not able to process JS assets, there are pre-processed assets available for use. Legacy browsers such as IE11 are no longer supported.
 
 ```html
-<script type="module" src="https://cdn.jsdelivr.net/npm/@aurodesignsystem/auro-formkit@3.4.0/auro-form/+esm"></script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/@aurodesignsystem/auro-formkit@0.0.0/auro-form/+esm"></script>
 ```
 <!-- AURO-GENERATED-CONTENT:END -->
 

package/components/form/demo/registerDemoDeps.js

@@ -1,3 +1,4 @@
+import "@aurodesignsystem/auro-button";
 import {AuroInput} from "@aurodesignsystem/auro-input";
 import {AuroDatePicker} from "@aurodesignsystem/auro-datepicker";
 import {AuroCounter, AuroCounterGroup} from "@aurodesignsystem/auro-counter";

package/components/form/dist/auro-form.d.ts

@@ -61,8 +61,11 @@ export class AuroForm extends LitElement {
     _submitelements: HTMLButtonElement[];
     /** @type {HTMLButtonElement[]} */
     _resetElements: HTMLButtonElement[];
-    /** @type {MutationObserver[]} */
-    mutationObservers: MutationObserver[];
+    /**
+     * @private
+     * @type {MutationObserver[]}
+     */
+    private mutationObservers;
     /**
      * Reset fires an event called `reset` - just as you would expect from a normal form.
      */
@@ -73,22 +76,25 @@ export class AuroForm extends LitElement {
     submit(): void;
     /**
      * Shared input listener for all form elements.
+     * @private
      * @param {Event} event - The event that is fired from the form element.
      */
-    sharedInputListener(event: Event): void;
+    private sharedInputListener;
     /**
      * Shared validation listener for all form elements.
+     * @private
      * @param {Event} event - The event that is fired from the form element.
      */
-    sharedValidationListener(event: Event): void;
+    private sharedValidationListener;
     /**
      * Mutation observer for form elements. Slot change does not trigger unless
      * root-level elements are added/removed. This is a workaround to ensure
      * nested form elements are also observed.
      *
+     * @private
      * @returns {void}
      */
-    mutationEventListener(): void;
+    private mutationEventListener;
     /**
      * Compare tag name with element to identify it (for API purposes).
      * @param {string} elementTag - The HTML tag name like `auro-datepicker`.
@@ -140,7 +146,7 @@ export class AuroForm extends LitElement {
      */
     get submitElements(): HTMLButtonElement[];
     /**
-     * Getter for internal _resetElements.
+     * Returns a collection of elements that will reset the form
      * @returns {HTMLButtonElement[]}
      */
     get resetElements(): HTMLButtonElement[];

package/components/form/dist/index.js

@@ -129,7 +129,10 @@ class AuroForm extends LitElement {
     /** @type {HTMLButtonElement[]} */
     this._resetElements = [];
 
-    /** @type {MutationObserver[]} */
+    /**
+     * @private
+     * @type {MutationObserver[]}
+     */
     this.mutationObservers = [];
 
     // Bind listeners
@@ -244,7 +247,7 @@ class AuroForm extends LitElement {
   }
 
   /**
-   * Getter for internal _resetElements.
+   * Returns a collection of elements that will reset the form
    * @returns {HTMLButtonElement[]}
    */
   get resetElements() {
@@ -474,6 +477,7 @@ class AuroForm extends LitElement {
 
   /**
    * Shared input listener for all form elements.
+   * @private
    * @param {Event} event - The event that is fired from the form element.
    */
   sharedInputListener(event) {
@@ -506,6 +510,7 @@ class AuroForm extends LitElement {
 
   /**
    * Shared validation listener for all form elements.
+   * @private
    * @param {Event} event - The event that is fired from the form element.
    */
   sharedValidationListener(event) {
@@ -561,6 +566,7 @@ 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}
    */
   mutationEventListener() {

package/components/form/dist/registered.js

@@ -129,7 +129,10 @@ class AuroForm extends LitElement {
     /** @type {HTMLButtonElement[]} */
     this._resetElements = [];
 
-    /** @type {MutationObserver[]} */
+    /**
+     * @private
+     * @type {MutationObserver[]}
+     */
     this.mutationObservers = [];
 
     // Bind listeners
@@ -244,7 +247,7 @@ class AuroForm extends LitElement {
   }
 
   /**
-   * Getter for internal _resetElements.
+   * Returns a collection of elements that will reset the form
    * @returns {HTMLButtonElement[]}
    */
   get resetElements() {
@@ -474,6 +477,7 @@ class AuroForm extends LitElement {
 
   /**
    * Shared input listener for all form elements.
+   * @private
    * @param {Event} event - The event that is fired from the form element.
    */
   sharedInputListener(event) {
@@ -506,6 +510,7 @@ class AuroForm extends LitElement {
 
   /**
    * Shared validation listener for all form elements.
+   * @private
    * @param {Event} event - The event that is fired from the form element.
    */
   sharedValidationListener(event) {
@@ -561,6 +566,7 @@ 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}
    */
   mutationEventListener() {

package/components/input/README.md

@@ -99,7 +99,7 @@ The use of any Auro custom element has a dependency on the [Auro Design Tokens](
 In cases where the project is not able to process JS assets, there are pre-processed assets available for use. Legacy browsers such as IE11 are no longer supported.
 
 ```html
-<script type="module" src="https://cdn.jsdelivr.net/npm/@aurodesignsystem/auro-formkit@3.4.0/auro-input/+esm"></script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/@aurodesignsystem/auro-formkit@0.0.0/auro-input/+esm"></script>
 ```
 <!-- AURO-GENERATED-CONTENT:END -->
 

package/components/input/demo/api.md

@@ -29,7 +29,7 @@ Generate unique names for dependency components.
 | [errorMessage](#errorMessage)                    | `errorMessage`                    | `string`  |             | Contains the help text message for the current validity error. |
 | [format](#format)                          | `format`                          | `string`  |             | Specifies the input mask format.                 |
 | [icon](#icon)                            | `icon`                            | `boolean` | false       | 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. |
-| [id](#id)                              | `id`                              | `string`  |             | Sets the unique ID of the element.               |
+| [id](#id)                              | `id`                              | `string`  |             | The id global attribute defines an identifier (ID) which must be unique in the whole document. |
 | [inputmode](#inputmode)                       | `inputmode`                       | `string`  |             | Exposes inputmode attribute for input.           |
 | [lang](#lang)                            | `lang`                            | `string`  |             | Defines the language of an element.              |
 | [max](#max)                             | `max`                             | `string`  | "undefined" | The maximum value allowed. This only applies for inputs with a type of `number` and all date formats. |

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

@@ -4978,6 +4978,9 @@ class AuroFormValidation {
  * @attr {Boolean} bordered - Applies bordered UI variant.
  * @attr {Boolean} borderless - Applies borderless UI variant.
  *
+ * @prop {string} id - The id global attribute defines an identifier (ID) which must be unique in the whole document.
+ * @attr id
+ *
  * @slot helptext - Sets the help text displayed below the input.
  * @slot label - Sets the label text for the input.
  *
@@ -5168,13 +5171,6 @@ class BaseInput extends i {
         reflect: true
       },
 
-      /**
-       * Sets the unique ID of the element.
-       */
-      id: {
-        type: String
-      },
-
       /** Exposes inputmode attribute for input.  */
       inputmode: {
         type: String,
@@ -5395,6 +5391,16 @@ class BaseInput extends i {
         type: Boolean,
         reflect: true,
         attribute: false
+      },
+
+      /**
+       * @private
+       * id for input node
+       */
+      inputId: {
+        type: String,
+        reflect: false,
+        attribute: false
       }
     };
   }
@@ -5426,6 +5432,7 @@ class BaseInput extends i {
     if (this.tagName.toLowerCase() !== 'auro-input') {
       this.setAttribute('auro-input', true);
     }
+    this.inputId = this.id ? `${this.id}-input` : window.crypto.randomUUID();
 
     this.inputElement = this.renderRoot.querySelector('input');
     this.labelElement = this.shadowRoot.querySelector('label');
@@ -7091,7 +7098,7 @@ class AuroInput extends BaseInput {
             : undefined
             }
           </div>
-          <label for=${this.id} class="${e$2(labelClasses)}" part="label">
+          <label for=${this.inputId} class="${e$2(labelClasses)}" part="label">
             <slot name="label">
               ${this.label}
             </slot>
@@ -7101,7 +7108,7 @@ class AuroInput extends BaseInput {
             @input="${this.handleInput}"
             @focusin="${this.handleFocusin}"
             @blur="${this.handleBlur}"
-            id="${this.id}"
+            id="${this.inputId}"
             name="${o$3(this.name)}"
             type="${this.type === 'password' && this.showPassword ? 'text' : this.getInputType(this.type)}"
             pattern="${o$3(this.definePattern())}"
@@ -7169,7 +7176,7 @@ class AuroInput extends BaseInput {
                   variant="flat"
                   ?onDark="${this.onDark}"
                   class="notificationBtn clearBtn"
-                  aria-label="${i18n(this.lang, 'clearInput')}"
+                  arialabel="${i18n(this.lang, 'clearInput')}"
                   @click="${this.handleClickClear}">
                   <${this.iconTag}
                     customColor