npm - @aurodesignsystem/auro-formkit - Versions diffs - 2.0.0-beta.8 → 2.0.0 - Mend

@aurodesignsystem/auro-formkit 2.0.0-beta.8 → 2.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (968) hide show

package/components/form/demo/readme.html ADDED Viewed

@@ -0,0 +1,49 @@
+<!--
+  Copyright (c) Alaska Air. All right reserved. Licensed under the Apache-2.0 license
+  See LICENSE in the project root for license information.
+  HTML in this document is standardized and NOT to be edited.
+  All demo code should be added/edited in ./demo/index.md
+  With the exception of adding custom elements if needed for the demo.
+  ----------------------- DO NOT EDIT -----------------------------
+-->
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Auro Web Component Generator | auro-form custom element</title>
+    <link
+      rel="stylesheet"
+      type="text/css"
+      href="https://cdn.jsdelivr.net/npm/prismjs@1.24.1/themes/prism.css"
+    />
+    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@aurodesignsystem/design-tokens@latest/dist/tokens/CSSCustomProperties.css">
+    <link rel="stylesheet" type="text/css" href="https://cdn.jsdelivr.net/npm/@aurodesignsystem/webcorestylesheets@latest/dist/demoWrapper.css" />
+    <link rel="stylesheet" type="text/css" href="https://cdn.jsdelivr.net/npm/@aurodesignsystem/webcorestylesheets@latest/dist/elementDemoStyles.css" />
+  </head>
+  <body class="auro-markdown">
+    <main></main>
+    <script type="module">
+      import 'https://cdn.jsdelivr.net/npm/marked@latest/marked.min.js';
+      import 'https://cdn.jsdelivr.net/npm/prismjs@latest/prism.js';
+      fetch('./readme.md')
+        .then((response) => response.text())
+        .then((text) => {
+          const rawHtml = marked.parse(text);
+          document.querySelector('main').innerHTML = rawHtml;
+          Prism.highlightAll();
+        })
+    </script>
+    <script type="module">
+      import { initExamples } from "./index.min.js";
+      initExamples();
+    </script>
+  </body>
+</html>

package/components/form/demo/readme.md ADDED Viewed

@@ -0,0 +1,146 @@
+<!--
+The README.md file is a compiled document. No edits should be made directly to this file.
+README.md is created by running `npm run build:docs`.
+This file is generated based on a template fetched from
+`../../docs/templates/componentReadmeTemplate.md`
+and copied to `./componentDocs/README.md` each time the docs are compiled.
+The following sections are editable by making changes to the following files:
+| SECTION                | DESCRIPTION                                       | FILE LOCATION                       |
+|------------------------|---------------------------------------------------|-------------------------------------|
+| Description            | Description of the component                      | `./docs/partials/description.md`    |
+| Use Cases              | Examples for when to use this component           | `./docs/partials/useCases.md`       |
+| Additional Information | For use to add any component specific information | `./docs/partials/readmeAddlInfo.md` |
+| Component Example Code | HTML sample code of the components use            | `./apiExamples/basic.html`          |
+-->
+# Form
+<!-- AURO-GENERATED-CONTENT:START (FILE:src=./docs/partials/description.md) -->
+<!-- The below content is automatically added from ./docs/partials/description.md -->
+`<auro-form>` is a [HTML custom element](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_custom_elements) designed to
+serve as the base logic for all auro-constructed forms.
+It automatically "scrapes" its inner content for any auro form elements, and surfaces
+them (along with events) to the parent form element as a JSON object.
+<!-- AURO-GENERATED-CONTENT:END -->
+<!-- AURO-GENERATED-CONTENT:START (FILE:src=./docs/partials/readmeAddlInfo.md) -->
+<!-- The below content is automatically added from ./docs/partials/readmeAddlInfo.md -->
+<!-- AURO-GENERATED-CONTENT This file is to be used for any additional content that should be included in the README.md which is specific to this component. -->
+<!-- AURO-GENERATED-CONTENT:END -->
+## Getting Started
+<!-- AURO-GENERATED-CONTENT:START (FILE:src=../../docs/templates/componentInstall.md) -->
+<!-- The below content is automatically added from ../../docs/templates/componentInstall.md -->
+#### NPM Installation
+```shell
+$ npm i @aurodesignsystem/auro-formkit
+```
+<!-- AURO-GENERATED-CONTENT:END -->
+<!-- AURO-GENERATED-CONTENT:START (FILE:src=../../docs/templates/gettingStarted.md) -->
+<!-- The below content is automatically added from ../../docs/templates/gettingStarted.md -->
+### Import Options
+#### Automatic Registration
+For automatic registration, simply import the component:
+```javascript
+// Registers <auro-form> automatically
+import '@aurodesignsystem/auro-formkit/auro-form';
+```
+#### Custom Registration
+To protect from versioning conflicts with other instances of the component being loaded, it is recommended to use our static `AuroForm.register('custom-form')` method on the component class and pass in a unique name.
+```javascript
+// Import the class only
+import { AuroForm } from '@aurodesignsystem/auro-formkit/auro-form/class';
+// Register with a custom name if desired
+AuroForm.register('custom-form');
+```
+#### TypeScript Module Resolution
+When using TypeScript set `moduleResolution` to `bundler`, add the following to your `tsconfig.json`:
+```json
+{
+    "compilerOptions": {
+        "moduleResolution": "bundler"
+    }
+}
+```
+This configuration enables proper module resolution for the component's TypeScript files.
+<!-- AURO-GENERATED-CONTENT:END -->
+**Reference component in HTML**
+<!-- AURO-GENERATED-CONTENT:START (CODE:src=./apiExamples/basic.html) -->
+<!-- The below code snippet is automatically added from ./apiExamples/basic.html -->
+```html
+<auro-form>
+  <auro-input id="search-box" name="searchBox" required>
+    <span slot="label">Search flights</span>
+  </auro-input>
+  <auro-button type="submit">Submit</auro-button>
+</auro-form>
+```
+<!-- AURO-GENERATED-CONTENT:END -->
+### Design Token CSS Custom Property dependency
+<!-- AURO-GENERATED-CONTENT:START (REMOTE:url=https://raw.githubusercontent.com/AlaskaAirlines/WC-Generator/master/componentDocs/partials/development/designTokens.md) -->
+The use of any Auro custom element has a dependency on the [Auro Design Tokens](https://auro.alaskaair.com/getting-started/developers/design-tokens).
+<!-- AURO-GENERATED-CONTENT:END -->
+## Install from CDN
+<!-- AURO-GENERATED-CONTENT:START (FILE:src=../../docs/templates/bundleInstallDescription.md) -->
+<!-- The below content is automatically added from ../../docs/templates/bundleInstallDescription.md -->
+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@2.0.0-beta.54/auro-form/+esm"></script>
+```
+<!-- AURO-GENERATED-CONTENT:END -->
+## UI development browser support
+<!-- AURO-GENERATED-CONTENT:START (REMOTE:url=https://raw.githubusercontent.com/AlaskaAirlines/WC-Generator/master/componentDocs/partials/browserSupport.md) -->
+For the most up to date information on [UI development browser support](https://auro.alaskaair.com/support/browsersSupport)
+<!-- AURO-GENERATED-CONTENT:END -->
+## auro-form use cases
+<!-- AURO-GENERATED-CONTENT:START (FILE:src=./docs/partials/useCases.md) -->
+<!-- The below content is automatically added from ./docs/partials/useCases.md -->
+The `<auro-form>` element should be used in situations where users may:
+* ...
+* ...
+* ...
+<!-- AURO-GENERATED-CONTENT:END -->
+## Formkit development
+<!-- AURO-GENERATED-CONTENT:START (FILE:src=../../docs/partials/developmentDescription.md) -->
+<!-- The below content is automatically added from ../../docs/partials/developmentDescription.md -->
+### Filtering
+Running the `dev` command will open a `localhost` development server for all components in the monorepo at once.
+To only develop a single component, use the `--filter` flag:
+```shell
+npx turbo dev --filter=@aurodesignsystem/auro-input
+```
+<!-- AURO-GENERATED-CONTENT:END -->

package/components/form/demo/registerDemoDeps.js ADDED Viewed

@@ -0,0 +1,22 @@
+import {AuroInput} from "@aurodesignsystem/auro-input";
+import {AuroDatePicker} from "@aurodesignsystem/auro-datepicker";
+import {AuroCounter, AuroCounterGroup} from "@aurodesignsystem/auro-counter";
+import {AuroRadio, AuroRadioGroup} from "@aurodesignsystem/auro-radio";
+import {AuroCheckbox, AuroCheckboxGroup} from "@aurodesignsystem/auro-checkbox";
+import {AuroCombobox} from "@aurodesignsystem/auro-combobox";
+import {AuroMenu, AuroMenuOption} from "@aurodesignsystem/auro-menu";
+import {AuroSelect} from "@aurodesignsystem/auro-select";
+AuroInput.register();
+AuroInput.register('auro-input-two');
+AuroDatePicker.register();
+AuroCounter.register();
+AuroCounterGroup.register();
+AuroRadio.register();
+AuroRadioGroup.register();
+AuroCheckbox.register();
+AuroCheckboxGroup.register();
+AuroCombobox.register();
+AuroMenu.register();
+AuroMenuOption.register();
+AuroSelect.register();

package/components/form/demo/working.html ADDED Viewed

@@ -0,0 +1,117 @@
+<!--
+  Copyright (c) Alaska Air. All right reserved. Licensed under the Apache-2.0 license
+  See LICENSE in the project root for license information.
+  HTML in this document is standardized and NOT to be edited.
+  All demo code should be added/edited in ./demo/index.md
+  With the exception of adding custom elements if needed for the demo.
+  ----------------------- DO NOT EDIT -----------------------------
+-->
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>Auro Web Component Generator | auro-form custom element</title>
+  <link
+    rel="stylesheet"
+    type="text/css"
+    href="https://cdn.jsdelivr.net/npm/prismjs@1.24.1/themes/prism.css"
+  />
+  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@aurodesignsystem/design-tokens@latest/dist/tokens/CSSCustomProperties.css">
+  <link rel="stylesheet" type="text/css" href="https://cdn.jsdelivr.net/npm/@aurodesignsystem/webcorestylesheets@latest/dist/demoWrapper.css" />
+  <link rel="stylesheet" type="text/css" href="https://cdn.jsdelivr.net/npm/@aurodesignsystem/webcorestylesheets@latest/dist/elementDemoStyles.css" />
+  <script src="https://cdn.jsdelivr.net/npm/@aurodesignsystem/auro-button@8.2.0/dist/auro-button__bundled.js" type="module"></script>
+</head>
+<body class="auro-markdown">
+<main>
+  <style>
+    .submitBlock {
+      margin-top: 1rem;
+      display: flex;
+      justify-content: flex-end;
+      gap: 1rem;
+    }
+    .datepickerBlock {
+      margin-top: 1rem;
+    }
+    auro-form {
+      display: block;
+      width: 100%;
+      padding: 1rem;
+      border: 1px solid #2a2a2a;
+      border-radius: 1rem;
+    }
+  </style>
+  <h2>auro-form testing</h2>
+  <auro-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>
+</main>
+<!-- Form elements MUST be registered BEFORE form if custom names are used -->
+<script type="module" data-demo-script="true" src="./registerDemoDeps.js"></script>
+<script type="module" data-demo-script="true" src="./index.js"></script>
+<!--<script type="module" data-demo-script="true" src="~@auro-formkit/auro-input/dist/index.min.js"></script>-->
+<script>
+  const form = document.querySelector('auro-form');
+  form.addEventListener('submit', (event) => {
+    console.log(event)
+    console.log(event.target.value)
+  })
+</script>
+<!-- If additional elements are needed for the demo, add them here. -->
+<script src="https://cdn.jsdelivr.net/npm/@aurodesignsystem/auro-accordion@latest/dist/auro-accordion__bundled.js" type="module"></script>
+<script src="https://cdn.jsdelivr.net/npm/@aurodesignsystem/auro-accordion@latest/dist/auro-accordion__bundled.js" type="module"></script>
+</body>
+</html>

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

@@ -1,15 +1,43 @@
+/**
+ * @typedef {Object} FormStateMember - The form state member.
+ * @property {string | number | boolean | string[] | null} value - The value of the form element.
+ * @property {ValidityState} validity - The validity state of the form element, stored when fired from the form element.
+ * @property {boolean} required - Whether the form element is required or not.
+ * @property {HTMLElement} element - Whether the form element is required or not.
+ */
+/**
+ * @typedef {Object.<string, FormStateMember>} FormState - The form state.
+ */
 /**
  * The auro-form element provides users a way to ... (it would be great if you fill this out).
  *
  * @attr {Boolean} fixed - Uses fixed pixel values for element shape
  * @attr {String} cssClass - Applies designated CSS class to demo element - you want to delete me!
+ * @event {Event} change - Fires when form state changes.
  */
 export class AuroForm extends LitElement {
     static get properties(): {
-        cssClass: {
-            type: StringConstructor;
+        formState: {
+            attribute: boolean;
+        };
+        _validity: {
+            attribute: boolean;
+        };
+        _isInitialState: {
+            attribute: boolean;
+        };
+        _elements: {
+            attribute: boolean;
+        };
+        _submitElements: {
+            attribute: boolean;
+        };
+        _resetElements: {
+            attribute: boolean;
         };
     };
+    static get formElementTags(): string[];
+    static get buttonElementTags(): string[];
     static get styles(): import("lit").CSSResult[];
     /**
      * This will register this element with the browser.
@@ -20,7 +48,170 @@ export class AuroForm extends LitElement {
      *
      */
     static register(name?: string): void;
+    /** @type {FormState} */
+    formState: FormState;
+    /** @type {"valid" | "invalid" | null} */
+    _validity: "valid" | "invalid" | null;
+    _isInitialState: boolean;
+    /** @type {(HTMLElement & {reset: () => void})[]} */
+    _elements: (HTMLElement & {
+        reset: () => void;
+    })[];
+    /** @type {HTMLButtonElement[]} */
+    _submitelements: HTMLButtonElement[];
+    /** @type {HTMLButtonElement[]} */
+    _resetElements: HTMLButtonElement[];
+    /** @type {MutationObserver[]} */
+    mutationObservers: MutationObserver[];
+    /**
+     * Reset fires an event called `reset` - just as you would expect from a normal form.
+     */
+    reset(): void;
+    /**
+     * Submit fires an event called `submit` - just as you would expect from a normal form.
+     */
+    submit(): void;
+    /**
+     * Shared input listener for all form elements.
+     * @param {Event} event - The event that is fired from the form element.
+     */
+    sharedInputListener(event: Event): void;
+    /**
+     * Shared validation listener for all form elements.
+     * @param {Event} event - The event that is fired from the form element.
+     */
+    sharedValidationListener(event: Event): void;
+    /**
+     * 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.
+     *
+     * @returns {void}
+     */
+    mutationEventListener(): void;
+    /**
+     * Compare tag name with element to identify it (for API purposes).
+     * @param {string} elementTag - The HTML tag name like `auro-datepicker`.
+     * @param {HTMLElement} element - The actual HTML element to compare.
+     * @returns {boolean}
+     * @private
+     */
+    private _isElementTag;
+    /**
+     * Shared code for determining if an element is something we care about (submit, form element, etc.).
+     * @param {string[]} collection - The array to use for tag name search.
+     * @param {HTMLElement} element - The element to compare against the master list.
+     * @returns {boolean}
+     * @private
+     */
+    private _isInElementCollection;
+    /**
+     * Check if the tag name is a form element.
+     * @param {HTMLElement} element - The element to check (attr or tag name).
+     * @returns {boolean}
+     */
+    isFormElement(element: HTMLElement): boolean;
+    /**
+     * Validates if an event is from a valid form element with a name.
+     * @param {Event} event - The event to validate.
+     * @returns {boolean} - True if event is valid for processing.
+     * @private
+     */
+    private _eventIsValidFormEvent;
+    /**
+     * Check if the tag name is a button element.
+     * @param {HTMLElement} element - The element to check.
+     * @returns {boolean}
+     */
+    isButtonElement(element: HTMLElement): boolean;
+    /**
+     * 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.
+     */
+    get value(): Record<string, string | number | boolean | string[] | null>;
+    /**
+     * Getter for internal _submitElements.
+     * @returns {HTMLButtonElement[]}
+     */
+    get submitElements(): HTMLButtonElement[];
+    /**
+     * Getter for internal _resetElements.
+     * @returns {HTMLButtonElement[]}
+     */
+    get resetElements(): HTMLButtonElement[];
+    /**
+     * Infer validity status based on current formState.
+     * @private
+     */
+    private _calculateValidity;
+    /**
+     * Current validity state of the form, based on form element events.
+     * @returns {"valid" | "invalid"}
+     */
+    get validity(): "valid" | "invalid";
+    _setInitialState(): void;
+    /**
+     * Mostly internal way to determine if a form is in the initial state.
+     * @returns {boolean}
+     */
+    get isInitialState(): boolean;
+    setDisabledStateOnButtons(): void;
+    /**
+     * Construct the query strings from elements, append them together, execute, and return the NodeList.
+     * @returns {NodeList}
+     */
+    queryAuroElements(): NodeList;
+    /**
+     * Store an element in state and on the _elements array.
+     * @param {HTMLElement} element - The element to add to our state.
+     * @private
+     */
+    private _addElementToState;
+    /**
+     * Initialize (or reinitialize) the form state.
+     */
+    initializeState(): void;
+    _attachEventListeners(): void;
+    firstUpdated(_changedProperties: any): void;
+    updated(_changedProperties: any): void;
+    /**
+     * Slot change event listener. This is the main entry point for the form element.
+     * @param {Event} event - The slot change event.
+     * @returns {void}
+     */
+    onSlotChange(event: Event): void;
     render(): import("lit-html").TemplateResult<1>;
 }
+/**
+ * - The form state member.
+ */
+export type FormStateMember = {
+    /**
+     * - The value of the form element.
+     */
+    value: string | number | boolean | string[] | null;
+    /**
+     * - The validity state of the form element, stored when fired from the form element.
+     */
+    validity: ValidityState;
+    /**
+     * - Whether the form element is required or not.
+     */
+    required: boolean;
+    /**
+     * - Whether the form element is required or not.
+     */
+    element: HTMLElement;
+};
+/**
+ * - The form state.
+ */
+export type FormState = {
+    [x: string]: FormStateMember;
+};
 import { LitElement } from "lit";
-//# sourceMappingURL=auro-form.d.ts.map

package/components/form/dist/index.d.ts CHANGED Viewed

@@ -1,3 +1,2 @@
 export { AuroForm };
 import { AuroForm } from './auro-form.js';
-//# sourceMappingURL=index.d.ts.map