@aurodesignsystem-dev/auro-formkit 0.0.0-pr1503.3 → 0.0.0-pr1503.5

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

@@ -1,9 +1,9 @@
 /**
  * @typedef {Object} FormStateMember - The form state member.
- * @property {string | number | boolean | string[] | null} value - The value of the form element.
+ * @property {string | number | boolean | string[] | Record<string, number> | null} value - The value of the form element. Mirrors the child component's own `.value`, so the shape varies by element type (e.g. an array for `auro-checkbox-group`, an object keyed by counter name for `auro-counter-group`). A `range` `auro-datepicker` is the one form-specific case: its `.values` array is stored rather than its single `.value` string.
  * @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.
+ * @property {boolean} disabled - Whether the form element is currently disabled. Cached from the live attribute via the MutationObserver in `connectedCallback` and refreshed from `_handleAttributeMutations`.
  */
 /**
  * @typedef {Object.<string, FormStateMember>} FormState - The form state.
@@ -95,6 +95,32 @@ export class AuroForm extends LitElement {
      * @type {MutationObserver[]}
      */
     private mutationObservers;
+    /**
+     * Captured initial (default) value per field `name`. Populated on first
+     * sight of each name in `_addElementToState` and preserved across
+     * subsequent `initializeState` cycles (slot change, rename, reset) so
+     * `_setInitialState` can detect user edits as `current !== initial`,
+     * matching HTML's `dirtyValueFlag` semantics.
+     * @private
+     * @type {Record<string, string | number | boolean | string[] | Record<string, number> | null | undefined>}
+     */
+    private _initialValues;
+    /**
+     * @private
+     * @type {MutationObserver | null}
+     */
+    private _attributeObserver;
+    /**
+     * Handle batched MutationObserver records for `disabled` and `name`
+     * attribute changes on tracked form elements. A `name` change invalidates
+     * the formState keying — we resolve it by re-initializing state. A `disabled`
+     * change simply needs a re-render (so `value` / `validity` getters re-evaluate)
+     * and a refresh of the submit/reset button enablement.
+     * @param {MutationRecord[]} mutations - The batched mutation records.
+     * @returns {void}
+     * @private
+     */
+    private _handleAttributeMutations;
     /**
      * 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}
@@ -155,6 +181,39 @@ export class AuroForm extends LitElement {
      * @private
      */
     private isFormElement;
+    /**
+     * Whether a given element is currently disabled. Disabled controls are excluded
+     * from submission, validity, and initial-state checks per the HTML spec
+     * (section 4.10.19.2 "Enabling and disabling form controls":
+     * https://www.w3.org/TR/2011/WD-html5-20110113/association-of-controls-and-forms.html).
+     *
+     * Implementation note: we deliberately read only the attribute. Every Auro
+     * form element in `formElementTags` declares `disabled` with `reflect: true`,
+     * so the attribute and property stay in sync. Reading the attribute also
+     * lets the MutationObserver in `connectedCallback` (which is filtered to
+     * `['disabled', 'name']`) be the single source of truth for re-renders.
+     * If a future form-element type ships without attribute reflection, expand
+     * this helper to also read `element.disabled`.
+     * @param {HTMLElement | undefined | null} element - The element to check.
+     * @returns {boolean}
+     * @private
+     */
+    private _isDisabled;
+    /**
+     * Whether the tracked form element registered under `name` is currently disabled.
+     * See `_isDisabled` for the HTML-spec rationale behind excluding disabled
+     * controls from form state.
+     *
+     * Reads a cached flag on `formState[name]` populated by `_addElementToState`
+     * at registration and refreshed by `_handleAttributeMutations` whenever the
+     * element's `disabled` attribute toggles. The cache is fed by the same
+     * `hasAttribute('disabled')` read as `_isDisabled`, so the "future form-element
+     * type without attribute reflection" caveat documented there applies here too.
+     * @param {string} name - The `name` attribute used to register the element.
+     * @returns {boolean}
+     * @private
+     */
+    private _isNameDisabled;
     /**
      * Validates if an event is from a valid form element with a name.
      * @param {Event} event - The event to validate.
@@ -170,10 +229,10 @@ export class AuroForm extends LitElement {
      */
     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.
+     * Returns the current values of all named, enabled form elements as a key-value object, keyed by each element's `name` attribute. Each value is the child component's own `.value`, so the shape depends on the element type — see that component's documentation for its exact shape (for example, `auro-checkbox-group` yields an array, `auro-counter-group` yields an object keyed by counter name, and `auro-select` with `multiSelect` yields a JSON-encoded string). The one form-specific exception is a `range` `auro-datepicker`, whose `.values` array (`[start, end]`) is stored instead of its single `.value` string.
+     * @returns {Record<string, string | number | boolean | string[] | Record<string, number> | null>} The current form values.
      */
-    get value(): Record<string, string | number | boolean | string[] | null>;
+    get value(): Record<string, string | number | boolean | string[] | Record<string, number> | null>;
     /**
      * Getter for internal _submitElements.
      * @returns {HTMLButtonElement[]}
@@ -186,8 +245,57 @@ export class AuroForm extends LitElement {
      * @private
      */
     private get resetElements();
+    /**
+     * Raw constraint-validation check. Returns `true` when no enabled field
+     * has a validity error. Unlike the public `validity` getter, this does
+     * NOT gate on `isInitialState` — callers that need to make a decision
+     * based on the actual constraint state (submit-button enablement, the
+     * internal `submit()` gate) read this so a pre-filled valid form is
+     * correctly recognized as submittable at first render.
+     * @returns {boolean}
+     * @private
+     */
+    private _isFormValid;
+    /**
+     * Whether the reset button should be enabled. True when the form has
+     * diverged from its initial state (so the user can always return to
+     * defaults — even if the dirty value lives behind a now-disabled field),
+     * OR when any non-disabled field has a current value or captured initial
+     * value (covers pre-filled forms and user-cleared-back-to-empty cases).
+     * @returns {boolean}
+     * @private
+     */
+    private _hasResetableState;
+    /**
+     * Collapse empty representations to a single canonical `null`.
+     *
+     * `_addElementToState` captures `null` for a field that mounts without a
+     * `value` attribute (`element.value || element.getAttribute('value')` is
+     * falsy → resolves to `null`), but `sharedInputListener` later stores the
+     * raw `event.target.value` — which is `''` for a user-cleared text input.
+     * Without this normalization, backspacing back to empty would taint the
+     * form forever (`'' !== null`) and Reset would stay enabled with nothing
+     * to actually reset.
+     *
+     * `''`, `undefined`, and `[]` all collapse to `null`. The empty-array case
+     * covers checkbox-group, radio-group, and multiselect, where `[]` means
+     * "no selection" — semantically the same as `null`/`''`. Genuine values
+     * — including `0`, `false`, non-empty strings, and non-empty arrays —
+     * pass through unchanged so number, boolean, and populated multi-value
+     * fields still compare correctly.
+     * @param {*} value - Value to normalize.
+     * @returns {*}
+     * @private
+     */
+    private _normalizeEmpty;
     /**
      * Infer validity status based on current formState.
+     *
+     * Validity stays `null` while the form is in its initial state — this is
+     * the "stay quiet until the user interacts" UX contract that consumers
+     * depend on to delay error indicators. Code that needs the raw
+     * constraint-validation result regardless of interaction (e.g.,
+     * submit-button enablement) should call `_isFormValid()` directly.
      * @private
      */
     private _calculateValidity;
@@ -197,7 +305,17 @@ export class AuroForm extends LitElement {
      */
     get validity(): "valid" | "invalid" | null;
     /**
-     * Determines whether the form is in its initial (untouched) state and updates `_isInitialState` accordingly.
+     * Determines whether the form is in its initial (untouched) state.
+     *
+     * A field is tainted if either:
+     *   - its value differs from the value captured on first render, OR
+     *   - its validity is failing (anything other than `null` or `'valid'`).
+     *
+     * Validity acts as a backup signal: it catches users who interact with a
+     * field without changing its value (e.g., focusing and blurring a required
+     * field). We skip `null` (not yet validated) and `'valid'` (the default
+     * after Auro's auto-validation on mount) because neither proves the user
+     * touched anything.
      * @returns {void}
      * @private
      */
@@ -255,9 +373,9 @@ export class AuroForm extends LitElement {
  */
 export type FormStateMember = {
     /**
-     * - The value of the form element.
+     * - The value of the form element. Mirrors the child component's own `.value`, so the shape varies by element type (e.g. an array for `auro-checkbox-group`, an object keyed by counter name for `auro-counter-group`). A `range` `auro-datepicker` is the one form-specific case: its `.values` array is stored rather than its single `.value` string.
      */
-    value: string | number | boolean | string[] | null;
+    value: string | number | boolean | string[] | Record<string, number> | null;
     /**
      * - The validity state of the form element, stored when fired from the form element.
      */
@@ -267,9 +385,9 @@ export type FormStateMember = {
      */
     required: boolean;
     /**
-     * - Whether the form element is required or not.
+     * - Whether the form element is currently disabled. Cached from the live attribute via the MutationObserver in `connectedCallback` and refreshed from `_handleAttributeMutations`.
      */
-    element: HTMLElement;
+    disabled: boolean;
 };
 /**
  * - The form state.