@aurodesignsystem-dev/auro-formkit 0.0.0-pr1505.0 → 0.0.0-pr1505.1

package/custom-elements.json

@@ -6306,11 +6306,11 @@
               "name": "fromLabel"
             },
             {
-              "description": "Overrides the \"(optional)\" text rendered next to the first input's label when the datepicker is not `required`.",
+              "description": "Overrides the \" (optional)\" text rendered next to the first input's label when the datepicker is not `required`.",
               "name": "optionalFromLabel"
             },
             {
-              "description": "Overrides the \"(optional)\" text rendered next to the second input's label when `range` is set and the datepicker is not `required`.",
+              "description": "Overrides the \" (optional)\" text rendered next to the second input's label when `range` is set and the datepicker is not `required`.",
               "name": "optionalToLabel"
             },
             {
@@ -10501,6 +10501,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",
@@ -10582,10 +10622,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"
             },
             {
@@ -10602,7 +10684,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"
@@ -10762,6 +10844,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",
@@ -10855,6 +10957,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": [
@@ -11240,7 +11361,7 @@
               "name": "label"
             },
             {
-              "description": "Allows overriding the optional display text \"(optional)\", which appears next to the label.",
+              "description": "Allows overriding the optional display text \" (optional)\", which appears next to the label.",
               "name": "optionalLabel"
             },
             {
@@ -18606,6 +18727,32 @@
               ],
               "description": "Updates the active option in the menu."
             },
+            {
+              "kind": "method",
+              "name": "_getOptionDisplayText",
+              "parameters": [
+                {
+                  "name": "option",
+                  "description": "The menu option element.",
+                  "type": {
+                    "text": "HTMLElement"
+                  }
+                }
+              ],
+              "description": "Returns the lowercase, trimmed text content of a menu option.",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "string"
+                }
+              }
+            },
+            {
+              "kind": "method",
+              "name": "_clearTypeaheadBuffer",
+              "description": "Empties the type-ahead buffer and cancels any pending reset timeout.\nCalled when focus leaves the component, when Escape closes the bib, and on disconnect\nso a stale buffer never bridges into a fresh interaction.",
+              "privacy": "private"
+            },
             {
               "kind": "method",
               "name": "updateActiveOptionBasedOnKey",
@@ -18618,7 +18765,7 @@
                   }
                 }
               ],
-              "description": "Updates the active option in the menu based on keyboard input.",
+              "description": "Updates the active option in the menu based on keyboard input.\n\nImplements the WAI-ARIA APG Listbox type-ahead pattern: accumulates printable\nkeystrokes into a buffer that resets after `typeaheadTimeoutMs` of inactivity.\nA multi-character buffer matches the first option whose displayed text starts\nwith the buffer; repeating a single character cycles through options that start\nwith that character.",
               "privacy": "private",
               "return": {
                 "type": {
@@ -19014,6 +19161,24 @@
               },
               "default": "false"
             },
+            {
+              "kind": "field",
+              "name": "typeaheadBuffer",
+              "type": {
+                "text": "string"
+              },
+              "privacy": "private",
+              "default": "''"
+            },
+            {
+              "kind": "field",
+              "name": "_typeaheadTimeout",
+              "type": {
+                "text": "null"
+              },
+              "privacy": "private",
+              "default": "null"
+            },
             {
               "kind": "field",
               "name": "appearance",
@@ -19298,6 +19463,18 @@
               },
               "description": "Indicates whether the input is in a dirty state (has been interacted with)."
             },
+            {
+              "kind": "field",
+              "name": "typeaheadTimeoutMs",
+              "privacy": "public",
+              "type": {
+                "text": "number"
+              },
+              "description": "Milliseconds of keyboard inactivity before the type-ahead buffer resets.\nIncrease for users who type slowly.",
+              "default": "500",
+              "attribute": "typeaheadTimeoutMs",
+              "reflects": true
+            },
             {
               "kind": "field",
               "name": "validity",
@@ -19650,6 +19827,15 @@
                 "module": "components/layoutElement/src/auroElement.js"
               }
             },
+            {
+              "name": "typeaheadTimeoutMs",
+              "type": {
+                "text": "number"
+              },
+              "description": "Milliseconds of keyboard inactivity before the type-ahead buffer resets.\nIncrease for users who type slowly.",
+              "default": "500",
+              "fieldName": "typeaheadTimeoutMs"
+            },
             {
               "name": "validity",
               "type": {
@@ -19728,7 +19914,7 @@
           "type": {
             "text": "object"
           },
-          "default": "{ ArrowDown(component, evt, ctx) { evt.preventDefault(); if (ctx.isExpanded) { if (evt.altKey || evt.ctrlKey || evt.metaKey) { // navigate to last enabled option selectKeyboardStrategy.End(component, evt, ctx); } else { navigateArrow(component, 'down', { ctx }); } } else { component.dropdown.show(); } }, ArrowUp(component, evt, ctx) { evt.preventDefault(); if (ctx.isExpanded) { if (evt.altKey || evt.ctrlKey || evt.metaKey) { // navigate to first enabled option selectKeyboardStrategy.Home(component, evt, ctx); } else { navigateArrow(component, 'up', { ctx }); } } else { component.dropdown.show(); } }, Escape(component, evt, ctx) { if (!ctx.isExpanded) { return; } // Prevent the Escape key from bubbling up and closing any parent dialogs / drawers / popups evt.stopPropagation(); component.dropdown.hide(); }, End(component, evt, ctx) { if (!ctx.isExpanded) { return; } evt.preventDefault(); evt.stopPropagation(); // `pop()` is safe here: getEnabledOptions returns a fresh filtered array. const lastOption = getEnabledOptions(component.menu).pop(); if (lastOption) { component.menu.updateActiveOption(lastOption); } }, Enter(component, evt, ctx) { evt.preventDefault(); evt.stopPropagation(); if (!ctx.isExpanded) { component.dropdown.show(); return; } component.menu.makeSelection(); }, Home(component, evt, ctx) { if (!ctx.isExpanded) { return; } evt.preventDefault(); evt.stopPropagation(); const [firstOption] = getEnabledOptions(component.menu); if (firstOption) { component.menu.updateActiveOption(firstOption); } }, Tab(component, evt, ctx) { if (!ctx.isExpanded) { return; } // Tab selects the focused option and closes the popup per the // WAI-ARIA APG select-only combobox / listbox pattern. if (component.optionActive) { component.menu.makeSelection(); } component.dropdown.hide(); }, default(component, evt, ctx) { component.updateActiveOptionBasedOnKey(evt.key); if (evt.key === ' ') { evt.preventDefault(); evt.stopPropagation(); if (ctx.isExpanded) { component.dropdown.hide(); return; } component.dropdown.show(); } }, }"
+          "default": "{ ArrowDown(component, evt, ctx) { evt.preventDefault(); if (ctx.isExpanded) { if (evt.altKey || evt.ctrlKey || evt.metaKey) { // navigate to last enabled option selectKeyboardStrategy.End(component, evt, ctx); } else { navigateArrow(component, 'down', { ctx }); } } else { component.dropdown.show(); } }, ArrowUp(component, evt, ctx) { evt.preventDefault(); if (ctx.isExpanded) { if (evt.altKey || evt.ctrlKey || evt.metaKey) { // navigate to first enabled option selectKeyboardStrategy.Home(component, evt, ctx); } else { navigateArrow(component, 'up', { ctx }); } } else { component.dropdown.show(); } }, Escape(component, evt, ctx) { // Always clear the type-ahead buffer — Escape is a universal cancel. // Safe to call when the buffer is empty. // eslint-disable-next-line no-underscore-dangle if (typeof component._clearTypeaheadBuffer === 'function') { // eslint-disable-next-line no-underscore-dangle component._clearTypeaheadBuffer(); } if (!ctx.isExpanded) { return; } // Prevent the Escape key from bubbling up and closing any parent dialogs / drawers / popups evt.stopPropagation(); component.dropdown.hide(); }, End(component, evt, ctx) { if (!ctx.isExpanded) { return; } evt.preventDefault(); evt.stopPropagation(); // `pop()` is safe here: getEnabledOptions returns a fresh filtered array. const lastOption = getEnabledOptions(component.menu).pop(); if (lastOption) { component.menu.updateActiveOption(lastOption); } }, Enter(component, evt, ctx) { evt.preventDefault(); evt.stopPropagation(); if (!ctx.isExpanded) { component.dropdown.show(); return; } component.menu.makeSelection(); }, Home(component, evt, ctx) { if (!ctx.isExpanded) { return; } evt.preventDefault(); evt.stopPropagation(); const [firstOption] = getEnabledOptions(component.menu); if (firstOption) { component.menu.updateActiveOption(firstOption); } }, Tab(component, evt, ctx) { if (!ctx.isExpanded) { return; } // Tab selects the focused option and closes the popup per the // WAI-ARIA APG select-only combobox / listbox pattern. if (component.optionActive) { component.menu.makeSelection(); } component.dropdown.hide(); }, default(component, evt, ctx) { // Space resolves to either typeahead-buffer extension or bib toggle // depending on whether a type-ahead buffer is active. Mirrors native // <select> and the WAI-ARIA APG Listbox guidance: mid-typeahead space // is a search character (e.g. \"San Francisco\"); otherwise it toggles. if (evt.key === ' ') { evt.preventDefault(); evt.stopPropagation(); if (component.typeaheadBuffer && component.typeaheadBuffer.length > 0) { component.updateActiveOptionBasedOnKey(evt.key); return; } if (ctx.isExpanded) { component.dropdown.hide(); } else { component.dropdown.show(); } return; } component.updateActiveOptionBasedOnKey(evt.key); }, }"
         }
       ],
       "exports": [
@@ -19764,6 +19950,25 @@
               "text": "Array<HTMLElement>"
             }
           }
+        },
+        {
+          "kind": "function",
+          "name": "getActiveOptions",
+          "parameters": [
+            {
+              "name": "menu",
+              "description": "The auro-menu element.",
+              "type": {
+                "text": "HTMLElement | null | undefined"
+              }
+            }
+          ],
+          "description": "Returns the active (selectable + visible) options for type-ahead navigation.\n\nUses auro-menuoption's `isActive` getter, which excludes disabled, hidden,\nand static options (e.g. `static nomatch` placeholders) so the type-ahead\ncursor never lands on a non-actionable item. Same empty-safe handling as\n`getEnabledOptions`.",
+          "return": {
+            "type": {
+              "text": "Array<HTMLElement>"
+            }
+          }
         }
       ],
       "exports": [
@@ -19774,6 +19979,14 @@
             "name": "getEnabledOptions",
             "module": "components/select/src/selectUtils.js"
           }
+        },
+        {
+          "kind": "js",
+          "name": "getActiveOptions",
+          "declaration": {
+            "name": "getActiveOptions",
+            "module": "components/select/src/selectUtils.js"
+          }
         }
       ]
     }

package/package.json

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