@aurodesignsystem-dev/auro-formkit 0.0.0-pr1422.0 → 0.0.0-pr1422.2

package/components/form/demo/readme.md

@@ -0,0 +1,145 @@
+<!--
+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 -->
+
+## 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 want to build HTML forms.
+<!-- 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 -->
+
+### 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 -->
+
+## 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@latest/auro-form/+esm"></script>
+```
+<!-- 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 -->
+<!-- AURO-GENERATED-CONTENT:START (FILE:src=./docs/partials/customRegistration.md) -->
+<!-- The below content is automatically added from ./docs/partials/customRegistration.md -->
+
+## Custom Component Registration for Version Management
+
+There are two key parts to every Auro component: the <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes">class</a> and the custom element definition. The class defines the component's behavior, while the custom element registers it under a specific name so it can be used in HTML.
+
+When you install the component as described on the `Install` page, the class is imported automatically, and the component is registered globally for you.
+
+However, if you need to load multiple versions of the same component on a single page (for example, when two projects depend on different versions), you can manually register the class under a custom element name to avoid conflicts.
+
+You can do this by importing only the component class and using the `register(name)` method with a unique name:
+
+```js
+// Import the class only
+import { AuroForm } from '@aurodesignsystem/auro-formkit/auro-form/class';
+
+// Register with a custom name if desired
+AuroForm.register('custom-form');
+```
+
+This will create a new custom element `<custom-form>` that behaves exactly like `<auro-form>`, allowing both to coexist on the same page without interfering with each other.
+
+### Using Custom-Named Child Form 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:
+
+```javascript
+import { AuroInput } from '@aurodesignsystem/auro-formkit/auro-input/class';
+import { AuroForm } from '@aurodesignsystem/auro-formkit/auro-form/class';
+
+AuroInput.register('my-custom-input'); // adds an internal identifier auro-form uses to recognize the custom element
+AuroForm.register(); // render looks for said identifier
+```
+
+The following is NOT correct and will result in forms not working as expected:
+
+```javascript
+import { AuroInput } from '@aurodesignsystem/auro-formkit/auro-input/class';
+import { AuroForm } from '@aurodesignsystem/auro-formkit/auro-form/class';
+
+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
+```
+<!-- AURO-GENERATED-CONTENT:END -->

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

@@ -0,0 +1,280 @@
+/**
+ * @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 create and manage forms in a consistent manner.
+ * @customElement auro-form
+ *
+ * @slot default - The default slot for form elements.
+ *
+ * @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.
+ */
+export class AuroForm extends LitElement {
+    static get properties(): {
+        /** @private */
+        formState: {
+            type: ObjectConstructor;
+            attribute: boolean;
+        };
+        /** @private */
+        _validity: {
+            type: ObjectConstructor;
+            attribute: boolean;
+        };
+        /** @private */
+        _isInitialState: {
+            type: BooleanConstructor;
+            attribute: boolean;
+        };
+        /** @private */
+        _elements: {
+            type: ArrayConstructor;
+            attribute: boolean;
+        };
+        /** @private */
+        _submitElements: {
+            type: ArrayConstructor;
+            attribute: boolean;
+        };
+        /** @private */
+        _resetElements: {
+            type: ArrayConstructor;
+            attribute: boolean;
+        };
+    };
+    static get formElementTags(): string[];
+    static get buttonElementTags(): string[];
+    static get styles(): import("lit").CSSResult[];
+    /**
+     * 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") // registers as <custom-form>
+     */
+    static register(name?: string): void;
+    /**
+     * @type {FormState}
+     * @private
+     */
+    private formState;
+    /**
+     * @type {"valid" | "invalid" | null}
+     * @private
+     */
+    private _validity;
+    /** @private */
+    private _isInitialState;
+    /**
+     * @type {(HTMLElement & {reset: () => void})[]}
+     * @private
+     */
+    private _elements;
+    /**
+     * @type {HTMLButtonElement[]}
+     * @private
+     */
+    private _submitElements;
+    /**
+     * @type {HTMLButtonElement[]}
+     * @private
+     */
+    private _resetElements;
+    /**
+     * @private
+     * @type {MutationObserver[]}
+     */
+    private mutationObservers;
+    /**
+     * 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(): void;
+    /**
+     * 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(): Promise<void>;
+    /**
+     * Shared input listener for all form elements.
+     * @param {Event} event - The event that is fired from the form element.
+     * @private
+     */
+    private sharedInputListener;
+    /**
+     * Shared validation listener for all form elements.
+     * @param {Event} event - The event that is fired from the form element.
+     * @private
+     */
+    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.
+     *
+     * @returns {void}
+     * @private
+     */
+    private mutationEventListener;
+    /**
+     * Handle Enter key press on form elements.
+     * @param {KeyboardEvent} event - The keyboard event.
+     * @private
+     */
+    private handleKeyDown;
+    /**
+     * 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}
+     * @private
+     */
+    private isFormElement;
+    /**
+     * 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}
+     * @private
+     */
+    private isButtonElement;
+    /**
+     * 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(): Record<string, string | number | boolean | string[] | null>;
+    /**
+     * Getter for internal _submitElements.
+     * @returns {HTMLButtonElement[]}
+     * @private
+     */
+    private get submitElements();
+    /**
+     * Returns a collection of elements that will reset the form.
+     * @returns {HTMLButtonElement[]}
+     * @private
+     */
+    private get resetElements();
+    /**
+     * Infer validity status based on current formState.
+     * @private
+     */
+    private _calculateValidity;
+    /**
+     * 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(): "valid" | "invalid" | null;
+    /**
+     * Determines whether the form is in its initial (untouched) state and updates `_isInitialState` accordingly.
+     * @returns {void}
+     * @private
+     */
+    private _setInitialState;
+    /**
+     * 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(): boolean;
+    /**
+     * Enables or disables submit and reset buttons based on the current form state and validity.
+     * @returns {void}
+     * @private
+     */
+    private setDisabledStateOnButtons;
+    /**
+     * Construct the query strings from elements, append them together, execute, and return the NodeList.
+     * @returns {NodeList}
+     * @private
+     */
+    private queryAuroElements;
+    /**
+     * 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.
+     * @returns {void}
+     * @private
+     */
+    private initializeState;
+    /**
+     * 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
+     */
+    private _attachEventListeners;
+    /**
+     * Slot change event listener. This is the main entry point for the form element.
+     * @param {Event} event - The slot change event.
+     * @returns {void}
+     * @private
+     */
+    private onSlotChange;
+    /**
+     * @returns {import('lit').TemplateResult}
+     */
+    render(): import("lit").TemplateResult;
+}
+/**
+ * - 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";

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

@@ -0,0 +1,2 @@
+export { AuroForm };
+import { AuroForm } from './auro-form.js';