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

package/custom-elements.json

@@ -10513,6 +10513,46 @@
               },
               "privacy": "private"
             },
+            {
+              "kind": "method",
+              "name": "_isDisabled",
+              "parameters": [
+                {
+                  "name": "element",
+                  "description": "The element to check.",
+                  "type": {
+                    "text": "HTMLElement | undefined | null"
+                  }
+                }
+              ],
+              "description": "Whether a given element is currently disabled. Disabled controls are excluded\nfrom submission, validity, and initial-state checks per the HTML spec\n(section 4.10.19.2 \"Enabling and disabling form controls\":\nhttps://www.w3.org/TR/2011/WD-html5-20110113/association-of-controls-and-forms.html).\n\nImplementation note: we deliberately read only the attribute. Every Auro\nform element in `formElementTags` declares `disabled` with `reflect: true`,\nso the attribute and property stay in sync. Reading the attribute also\nlets the MutationObserver in `connectedCallback` (which is filtered to\n`['disabled', 'name']`) be the single source of truth for re-renders.\nIf a future form-element type ships without attribute reflection, expand\nthis helper to also read `element.disabled`.",
+              "return": {
+                "type": {
+                  "text": "boolean"
+                }
+              },
+              "privacy": "private"
+            },
+            {
+              "kind": "method",
+              "name": "_isNameDisabled",
+              "parameters": [
+                {
+                  "name": "name",
+                  "description": "The `name` attribute used to register the element.",
+                  "type": {
+                    "text": "string"
+                  }
+                }
+              ],
+              "description": "Whether the tracked form element registered under `name` is currently disabled.\nSee `_isDisabled` for the HTML-spec rationale behind excluding disabled\ncontrols from form state.\n\nReads a cached flag on `formState[name]` populated by `_addElementToState`\nat registration and refreshed by `_handleAttributeMutations` whenever the\nelement's `disabled` attribute toggles. The cache is fed by the same\n`hasAttribute('disabled')` read as `_isDisabled`, so the \"future form-element\ntype without attribute reflection\" caveat documented there applies here too.",
+              "return": {
+                "type": {
+                  "text": "boolean"
+                }
+              },
+              "privacy": "private"
+            },
             {
               "kind": "method",
               "name": "_eventIsValidFormEvent",
@@ -10594,10 +10634,52 @@
               "privacy": "private",
               "readonly": true
             },
+            {
+              "kind": "method",
+              "name": "_isFormValid",
+              "description": "Raw constraint-validation check. Returns `true` when no enabled field\nhas a validity error. Unlike the public `validity` getter, this does\nNOT gate on `isInitialState` — callers that need to make a decision\nbased on the actual constraint state (submit-button enablement, the\ninternal `submit()` gate) read this so a pre-filled valid form is\ncorrectly recognized as submittable at first render.",
+              "return": {
+                "type": {
+                  "text": "boolean"
+                }
+              },
+              "privacy": "private"
+            },
+            {
+              "kind": "method",
+              "name": "_hasResetableState",
+              "description": "Whether the reset button should be enabled. True when the form has\ndiverged from its initial state (so the user can always return to\ndefaults — even if the dirty value lives behind a now-disabled field),\nOR when any non-disabled field has a current value or captured initial\nvalue (covers pre-filled forms and user-cleared-back-to-empty cases).",
+              "return": {
+                "type": {
+                  "text": "boolean"
+                }
+              },
+              "privacy": "private"
+            },
+            {
+              "kind": "method",
+              "name": "_normalizeEmpty",
+              "parameters": [
+                {
+                  "name": "value",
+                  "description": "Value to normalize.",
+                  "type": {
+                    "text": "*"
+                  }
+                }
+              ],
+              "description": "Collapse empty representations to a single canonical `null`.\n\n`_addElementToState` captures `null` for a field that mounts without a\n`value` attribute (`element.value || element.getAttribute('value')` is\nfalsy → resolves to `null`), but `sharedInputListener` later stores the\nraw `event.target.value` — which is `''` for a user-cleared text input.\nWithout this normalization, backspacing back to empty would taint the\nform forever (`'' !== null`) and Reset would stay enabled with nothing\nto actually reset.\n\n`''`, `undefined`, and `[]` all collapse to `null`. The empty-array case\ncovers checkbox-group, radio-group, and multiselect, where `[]` means\n\"no selection\" — semantically the same as `null`/`''`. Genuine values\n— including `0`, `false`, non-empty strings, and non-empty arrays —\npass through unchanged so number, boolean, and populated multi-value\nfields still compare correctly.",
+              "return": {
+                "type": {
+                  "text": "*"
+                }
+              },
+              "privacy": "private"
+            },
             {
               "kind": "method",
               "name": "_calculateValidity",
-              "description": "Infer validity status based on current formState.",
+              "description": "Infer validity status based on current formState.\n\nValidity stays `null` while the form is in its initial state — this is\nthe \"stay quiet until the user interacts\" UX contract that consumers\ndepend on to delay error indicators. Code that needs the raw\nconstraint-validation result regardless of interaction (e.g.,\nsubmit-button enablement) should call `_isFormValid()` directly.",
               "privacy": "private"
             },
             {
@@ -10614,7 +10696,7 @@
             {
               "kind": "method",
               "name": "_setInitialState",
-              "description": "Determines whether the form is in its initial (untouched) state and updates `_isInitialState` accordingly.",
+              "description": "Determines whether the form is in its initial (untouched) state.\n\nA field is tainted if either:\n  - its value differs from the value captured on first render, OR\n  - its validity is failing (anything other than `null` or `'valid'`).\n\nValidity acts as a backup signal: it catches users who interact with a\nfield without changing its value (e.g., focusing and blurring a required\nfield). We skip `null` (not yet validated) and `'valid'` (the default\nafter Auro's auto-validation on mount) because neither proves the user\ntouched anything.",
               "return": {
                 "type": {
                   "text": "void"
@@ -10774,6 +10856,26 @@
               },
               "privacy": "private"
             },
+            {
+              "kind": "method",
+              "name": "_handleAttributeMutations",
+              "parameters": [
+                {
+                  "name": "mutations",
+                  "description": "The batched mutation records.",
+                  "type": {
+                    "text": "MutationRecord[]"
+                  }
+                }
+              ],
+              "description": "Handle batched MutationObserver records for `disabled` and `name`\nattribute changes on tracked form elements. A `name` change invalidates\nthe formState keying — we resolve it by re-initializing state. A `disabled`\nchange simply needs a re-render (so `value` / `validity` getters re-evaluate)\nand a refresh of the submit/reset button enablement.",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "privacy": "private"
+            },
             {
               "kind": "method",
               "name": "mutationEventListener",
@@ -10867,6 +10969,25 @@
               },
               "privacy": "private",
               "default": "[]"
+            },
+            {
+              "kind": "field",
+              "name": "_initialValues",
+              "type": {
+                "text": "Record<string, string | number | boolean | string[] | null | undefined>"
+              },
+              "description": "Captured initial (default) value per field `name`. Populated on first\nsight of each name in `_addElementToState` and preserved across\nsubsequent `initializeState` cycles (slot change, rename, reset) so\n`_setInitialState` can detect user edits as `current !== initial`,\nmatching HTML's `dirtyValueFlag` semantics.",
+              "privacy": "private",
+              "default": "{}"
+            },
+            {
+              "kind": "field",
+              "name": "_attributeObserver",
+              "type": {
+                "text": "MutationObserver | null"
+              },
+              "privacy": "private",
+              "default": "null"
             }
           ],
           "events": [
@@ -11716,61 +11837,6 @@
                 "module": "components/input/src/base-input.js"
               }
             },
-            {
-              "kind": "method",
-              "name": "_computeDateObjectFallback",
-              "parameters": [
-                {
-                  "name": "dateStr",
-                  "description": "ISO date string from `value`/`min`/`max`.",
-                  "type": {
-                    "text": "string|undefined"
-                  }
-                }
-              ],
-              "description": "Parses a date string into a Date object when the corresponding `_*Object`\nfield hasn't been synced yet by `updated()`. Returns undefined when the\ninput type/format isn't a full date or the string is not a valid date.\n\nWhy this exists: a parent (datepicker) can call `inputN.validate()` from\ninside its own `updated()` before this input's `updated()` has run\n`syncDateValues()` — so `_valueObject`/`_maxObject` are still `undefined`\nand range checks would otherwise silently no-op (flipping the result to\n`valid` or `patternMismatch`).",
-              "privacy": "private",
-              "return": {
-                "type": {
-                  "text": "Date|undefined"
-                }
-              },
-              "inheritedFrom": {
-                "name": "BaseInput",
-                "module": "components/input/src/base-input.js"
-              }
-            },
-            {
-              "kind": "method",
-              "name": "setDateObjectProperty",
-              "parameters": [
-                {
-                  "name": "propertyName",
-                  "description": "Public object property name.",
-                  "type": {
-                    "text": "'valueObject'|'minObject'|'maxObject'"
-                  }
-                },
-                {
-                  "name": "propertyValue",
-                  "description": "Value to assign.",
-                  "type": {
-                    "text": "Date|undefined"
-                  }
-                }
-              ],
-              "description": "Internal setter for readonly date object properties.",
-              "privacy": "private",
-              "return": {
-                "type": {
-                  "text": "void"
-                }
-              },
-              "inheritedFrom": {
-                "name": "BaseInput",
-                "module": "components/input/src/base-input.js"
-              }
-            },
             {
               "kind": "method",
               "name": "patchInputEvent",
@@ -11824,70 +11890,6 @@
                 "module": "components/input/src/base-input.js"
               }
             },
-            {
-              "kind": "method",
-              "name": "syncDateValues",
-              "parameters": [
-                {
-                  "name": "changedProperties",
-                  "default": "undefined",
-                  "description": "Optional map of changed properties used to limit which values are synchronized.",
-                  "optional": true,
-                  "type": {
-                    "text": "Map<string, unknown>|undefined"
-                  }
-                }
-              ],
-              "description": "Synchronizes the ISO string values and Date object representations for date-related properties.\nThis keeps the model and display values aligned when either side changes.\n\nWhen a full date format is in use, this method updates `value`, `min`, and `max` from their corresponding\nDate objects or vice versa, based on which properties have changed. It only runs when the current configuration\nrepresents a full year/month/day date format.",
-              "return": {
-                "type": {
-                  "text": "void"
-                }
-              },
-              "privacy": "private",
-              "inheritedFrom": {
-                "name": "BaseInput",
-                "module": "components/input/src/base-input.js"
-              }
-            },
-            {
-              "kind": "method",
-              "name": "syncSingleDateValue",
-              "parameters": [
-                {
-                  "name": "changedProperties",
-                  "description": "Map of changed properties from Lit.",
-                  "type": {
-                    "text": "Map<string, unknown>|undefined"
-                  }
-                },
-                {
-                  "name": "objectProperty",
-                  "description": "Date object property name.",
-                  "type": {
-                    "text": "string"
-                  }
-                },
-                {
-                  "name": "valueProperty",
-                  "description": "ISO string property name.",
-                  "type": {
-                    "text": "string"
-                  }
-                }
-              ],
-              "description": "Synchronizes one date object/string property pair.",
-              "privacy": "private",
-              "return": {
-                "type": {
-                  "text": "void"
-                }
-              },
-              "inheritedFrom": {
-                "name": "BaseInput",
-                "module": "components/input/src/base-input.js"
-              }
-            },
             {
               "kind": "method",
               "name": "configureAutoFormatting",
@@ -12263,15 +12265,6 @@
                 "module": "components/input/src/base-input.js"
               }
             },
-            {
-              "kind": "field",
-              "name": "_maxObject",
-              "default": "undefined",
-              "inheritedFrom": {
-                "name": "BaseInput",
-                "module": "components/input/src/base-input.js"
-              }
-            },
             {
               "kind": "field",
               "name": "maxLength",
@@ -12303,15 +12296,6 @@
                 "module": "components/input/src/base-input.js"
               }
             },
-            {
-              "kind": "field",
-              "name": "_minObject",
-              "default": "undefined",
-              "inheritedFrom": {
-                "name": "BaseInput",
-                "module": "components/input/src/base-input.js"
-              }
-            },
             {
               "kind": "field",
               "name": "minLength",
@@ -12420,15 +12404,6 @@
                 "module": "components/input/src/base-input.js"
               }
             },
-            {
-              "kind": "field",
-              "name": "_valueObject",
-              "default": "undefined",
-              "inheritedFrom": {
-                "name": "BaseInput",
-                "module": "components/input/src/base-input.js"
-              }
-            },
             {
               "kind": "field",
               "name": "a11yRole",
@@ -13827,53 +13802,6 @@
               },
               "readonly": true
             },
-            {
-              "kind": "method",
-              "name": "_computeDateObjectFallback",
-              "parameters": [
-                {
-                  "name": "dateStr",
-                  "description": "ISO date string from `value`/`min`/`max`.",
-                  "type": {
-                    "text": "string|undefined"
-                  }
-                }
-              ],
-              "description": "Parses a date string into a Date object when the corresponding `_*Object`\nfield hasn't been synced yet by `updated()`. Returns undefined when the\ninput type/format isn't a full date or the string is not a valid date.\n\nWhy this exists: a parent (datepicker) can call `inputN.validate()` from\ninside its own `updated()` before this input's `updated()` has run\n`syncDateValues()` — so `_valueObject`/`_maxObject` are still `undefined`\nand range checks would otherwise silently no-op (flipping the result to\n`valid` or `patternMismatch`).",
-              "privacy": "private",
-              "return": {
-                "type": {
-                  "text": "Date|undefined"
-                }
-              }
-            },
-            {
-              "kind": "method",
-              "name": "setDateObjectProperty",
-              "parameters": [
-                {
-                  "name": "propertyName",
-                  "description": "Public object property name.",
-                  "type": {
-                    "text": "'valueObject'|'minObject'|'maxObject'"
-                  }
-                },
-                {
-                  "name": "propertyValue",
-                  "description": "Value to assign.",
-                  "type": {
-                    "text": "Date|undefined"
-                  }
-                }
-              ],
-              "description": "Internal setter for readonly date object properties.",
-              "privacy": "private",
-              "return": {
-                "type": {
-                  "text": "void"
-                }
-              }
-            },
             {
               "kind": "method",
               "name": "patchInputEvent",
@@ -13915,62 +13843,6 @@
                 }
               }
             },
-            {
-              "kind": "method",
-              "name": "syncDateValues",
-              "parameters": [
-                {
-                  "name": "changedProperties",
-                  "default": "undefined",
-                  "description": "Optional map of changed properties used to limit which values are synchronized.",
-                  "optional": true,
-                  "type": {
-                    "text": "Map<string, unknown>|undefined"
-                  }
-                }
-              ],
-              "description": "Synchronizes the ISO string values and Date object representations for date-related properties.\nThis keeps the model and display values aligned when either side changes.\n\nWhen a full date format is in use, this method updates `value`, `min`, and `max` from their corresponding\nDate objects or vice versa, based on which properties have changed. It only runs when the current configuration\nrepresents a full year/month/day date format.",
-              "return": {
-                "type": {
-                  "text": "void"
-                }
-              },
-              "privacy": "private"
-            },
-            {
-              "kind": "method",
-              "name": "syncSingleDateValue",
-              "parameters": [
-                {
-                  "name": "changedProperties",
-                  "description": "Map of changed properties from Lit.",
-                  "type": {
-                    "text": "Map<string, unknown>|undefined"
-                  }
-                },
-                {
-                  "name": "objectProperty",
-                  "description": "Date object property name.",
-                  "type": {
-                    "text": "string"
-                  }
-                },
-                {
-                  "name": "valueProperty",
-                  "description": "ISO string property name.",
-                  "type": {
-                    "text": "string"
-                  }
-                }
-              ],
-              "description": "Synchronizes one date object/string property pair.",
-              "privacy": "private",
-              "return": {
-                "type": {
-                  "text": "void"
-                }
-              }
-            },
             {
               "kind": "method",
               "name": "configureAutoFormatting",
@@ -14258,11 +14130,6 @@
               "default": "undefined",
               "attribute": "max"
             },
-            {
-              "kind": "field",
-              "name": "_maxObject",
-              "default": "undefined"
-            },
             {
               "kind": "field",
               "name": "maxLength",
@@ -14286,11 +14153,6 @@
               "default": "undefined",
               "attribute": "min"
             },
-            {
-              "kind": "field",
-              "name": "_minObject",
-              "default": "undefined"
-            },
             {
               "kind": "field",
               "name": "minLength",
@@ -14383,11 +14245,6 @@
               "default": "undefined",
               "attribute": "value"
             },
-            {
-              "kind": "field",
-              "name": "_valueObject",
-              "default": "undefined"
-            },
             {
               "kind": "field",
               "name": "a11yRole",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aurodesignsystem-dev/auro-formkit",
-  "version": "0.0.0-pr1506.0",
+  "version": "0.0.0-pr1506.2",
   "description": "A collection of web components used to build forms.",
   "homepage": "https://github.com/AlaskaAirlines/auro-formkit#readme",
   "bugs": {