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

package/components/combobox/demo/keyboard-behavior.md

@@ -30,7 +30,7 @@
 </thead>
 <tbody>
 <tr>
-<td rowspan="8">ArrowDown</td>
+<td rowspan="2">ArrowDown</td>
 <td rowspan="2">-</td>
 <td>Collapsed, list options have been populated</td>
 <td>
@@ -51,77 +51,7 @@
 </td>
 </tr>
 <tr>
-<td rowspan="2">Meta (Command / Windows key)</td>
-<td>Collapsed, list options have been populated</td>
-<td>
-              Trigger input element, <strong>NOT</strong> the trigger input clear button
-</td>
-<td>
-              Opens the bib.
-<div class="note">
-<strong>Note:</strong> On Windows, <code>Meta</code> + arrow key combinations are reserved by the operating system for window management. Windows users should use <code>Control</code> or <code>Alt</code> instead.
-</div>
-</td>
-</tr>
-<tr>
-<td>Expanded</td>
-<td>
-              Input element, <strong>NOT</strong> the input clear button
-<div class="note">
-<strong>Note:</strong> Includes both trigger and bib content inputs.
-</div>
-</td>
-<td>
-              Advances the <code>focused</code> option to the last enabled option in the list.
-</td>
-</tr>
-<tr>
-<td rowspan="2">Alt (Option)</td>
-<td>Collapsed, list options have been populated</td>
-<td>
-              Trigger input element, <strong>NOT</strong> the trigger input clear button
-</td>
-<td>Opens the bib.</td>
-</tr>
-<tr>
-<td>Expanded</td>
-<td>
-              Input element, <strong>NOT</strong> the input clear button
-<div class="note">
-<strong>Note:</strong> Includes both trigger and bib content inputs.
-</div>
-</td>
-<td>
-              Advances the <code>focused</code> option to the last enabled option in the list.
-</td>
-</tr>
-<tr>
-<td rowspan="2">Control</td>
-<td>Collapsed, list options have been populated</td>
-<td>
-              Trigger input element, <strong>NOT</strong> the trigger input clear button
-</td>
-<td>
-              Opens the bib.
-<div class="note">
-<strong>Note:</strong> On macOS, <code>Control</code> + arrow key combinations are reserved by the operating system for Mission Control and Application Windows. macOS users should use <code>Meta</code> or <code>Alt</code> instead.
-</div>
-</td>
-</tr>
-<tr>
-<td>Expanded</td>
-<td>
-              Input element, <strong>NOT</strong> the input clear button
-<div class="note">
-<strong>Note:</strong> Includes both trigger and bib content inputs.
-</div>
-</td>
-<td>
-              Advances the <code>focused</code> option to the last enabled option in the list.
-</td>
-</tr>
-<tr>
-<td rowspan="8">ArrowUp</td>
+<td rowspan="2">ArrowUp</td>
 <td rowspan="2">-</td>
 <td>Collapsed, list options have been populated</td>
 <td>
@@ -142,76 +72,6 @@
 </td>
 </tr>
 <tr>
-<td rowspan="2">Meta (Command / Windows key)</td>
-<td>Collapsed, list options have been populated</td>
-<td>
-              Trigger input element, <strong>NOT</strong> the trigger input clear button
-</td>
-<td>
-              Opens the bib.
-<div class="note">
-<strong>Note:</strong> On Windows, <code>Meta</code> + arrow key combinations are reserved by the operating system for window management. Windows users should use <code>Control</code> or <code>Alt</code> instead.
-</div>
-</td>
-</tr>
-<tr>
-<td>Expanded</td>
-<td>
-              Input element, <strong>NOT</strong> the input clear button
-<div class="note">
-<strong>Note:</strong> Includes both trigger and bib content inputs.
-</div>
-</td>
-<td>
-              Advances the <code>focused</code> option to the first enabled option in the list.
-</td>
-</tr>
-<tr>
-<td rowspan="2">Alt (Option)</td>
-<td>Collapsed, list options have been populated</td>
-<td>
-              Input element, <strong>NOT</strong> the input clear button
-</td>
-<td>Opens the bib.</td>
-</tr>
-<tr>
-<td>Expanded</td>
-<td>
-              Input element, <strong>NOT</strong> the input clear button
-<div class="note">
-<strong>Note:</strong> Includes both trigger and bib content inputs.
-</div>
-</td>
-<td>
-              Advances the <code>focused</code> option to the first enabled option in the list.
-</td>
-</tr>
-<tr>
-<td rowspan="2">Control</td>
-<td>Collapsed, list options have been populated</td>
-<td>
-              Trigger input element, <strong>NOT</strong> the trigger input clear button
-</td>
-<td>
-              Opens the bib.
-<div class="note">
-<strong>Note:</strong> On macOS, <code>Control</code> + arrow key combinations are reserved by the operating system for Mission Control and Application Windows. macOS users should use <code>Meta</code> or <code>Alt</code> instead.
-</div>
-</td>
-</tr>
-<tr>
-<td>Expanded</td>
-<td>
-              Input element, <strong>NOT</strong> the input clear button
-<div class="note">
-<strong>Note:</strong> Includes both trigger and bib content inputs.
-</div>
-</td>
-<td>
-              Advances the <code>focused</code> option to the first enabled option in the list.
-</td>
-</tr>
-<tr>
 <td>End</td>
 <td>-</td>
 <td>Expanded</td>
@@ -315,10 +175,7 @@
 </div>
 </td>
 <td>
-              Advances the <code>focused</code> option to the first enabled option in the list.
-<div class="note">
-<strong>Note:</strong> the bib will <strong>NOT</strong> close and the page will <strong>NOT</strong> navigate to the previous focusable element in the tabindex order.
-</div>
+              The current <code>focused</code> option is selected, the bib is closed and <strong>focus</strong> is moved to the previous focusable element on the page.
 </td>
 </tr>
 </tbody>

package/components/combobox/demo/readme.md

@@ -24,7 +24,7 @@ The following sections are editable by making changes to the following files:
 <p>The component supports two modes:</p>
 <ul>
 <li><strong>Suggestion (default)</strong> — The user may type any value. The menu provides suggestions but does not restrict input.</li>
-<li><strong>Filter</strong> — The user must select from the menu. Typing filters the available options but does not set the component's value. The value is only set when a menu option is selected.</li>
+<li><strong>Filter</strong> — Typing filters the available options and sets the component's <code>value</code> to the typed text, but the input is not considered valid until a menu option is selected. Validation surfaces <code>valueMissing</code> until the typed value matches a chosen option.</li>
 </ul>
 <p>Common use cases:</p>
 <ul>

package/components/combobox/demo/why-combobox.md

@@ -4,7 +4,7 @@
 <p>Native <code>&lt;datalist&gt;</code> support varies between browsers. Some announce suggestion counts, others do not. Keyboard behavior is inconsistent, and there is no standard way to communicate selection state to screen readers.</p>
 <p><code>auro-combobox</code> provides:</p>
 <ul>
-<li><strong>ARIA combobox pattern</strong> — The input carries <code>aria-expanded</code>, <code>aria-owns</code>, and <code>aria-haspopup</code> to properly describe the relationship between the input and the suggestions list.</li>
+<li><strong>ARIA combobox pattern</strong> — The input carries <code>role="combobox"</code>, <code>aria-expanded</code>, and <code>aria-controls</code> to properly describe the relationship between the input and the suggestions list.</li>
 <li><strong>Active descendant tracking</strong> — <code>aria-activedescendant</code> moves with keyboard navigation so screen readers announce the highlighted option without moving DOM focus.</li>
 <li><strong>Live region announcements</strong> — Selections are announced via <code>aria-live="polite"</code>, and validation errors use <code>aria-live="assertive"</code>.</li>
 <li><strong>Full keyboard navigation</strong> — Arrow keys navigate options, Enter selects, Escape closes, Home/End jump to boundaries. A dedicated keyboard strategy handles all interactions.</li>
@@ -14,7 +14,7 @@
 <p><code>auro-combobox</code> supports two modes:</p>
 <ul>
 <li><strong>Suggestion mode</strong> (default) — The user can type any value. Suggestions are offered but not required.</li>
-<li><strong>Filter mode</strong> — The user must select from the available options. Typed text filters the list but cannot be submitted as a value. Validation enforces this constraint.</li>
+<li><strong>Filter mode</strong> — Typing filters the list and sets the component's <code>value</code> to the typed text, but validation keeps the input invalid until a menu option is selected. Consumers relying on <code>value</code> as a "committed selection" should gate on <code>validity</code>.</li>
 </ul>
 <auro-header level="2" id="realtimeFiltering">Real-time filtering</auro-header>
 <p><code>&lt;datalist&gt;</code> filtering is browser-controlled and cannot be customized. Some browsers match from the start of the option text, others match anywhere.</p>

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

@@ -49,6 +49,7 @@ export class AuroCombobox extends AuroElement {
             state: boolean;
             type: ArrayConstructor;
             reflect: boolean;
+            hasChanged(newVal: any, oldVal: any): any;
         };
         /**
          * Sets the behavior of the combobox, "filter" or "suggestion".
@@ -244,6 +245,8 @@ export class AuroCombobox extends AuroElement {
         };
         /**
          * If set, the `icon` attribute will be applied to the trigger `auro-input` element.
+         * Icon rendering is currently limited to `type="credit-card"`. Setting `triggerIcon`
+         * without a supported `type` propagates the attribute but does not render a visible icon.
          */
         triggerIcon: {
             type: BooleanConstructor;
@@ -271,7 +274,7 @@ export class AuroCombobox extends AuroElement {
             reflect: boolean;
         };
         /**
-         * Value selected for the dropdown menu.
+         * Value selected for the dropdown menu. When set programmatically or as a preset attribute, the value must match a selectable option. If it matches an option marked `disabled` or `static`, the selection is rejected: `value` and `optionSelected` are cleared to `undefined`. `hidden` options (including those filtered out by type-ahead) remain selectable by value.
          */
         value: {
             type: StringConstructor;
@@ -302,17 +305,6 @@ export class AuroCombobox extends AuroElement {
             reflect: boolean;
             attribute: boolean;
         };
-        /**
-         * Deferred aria-expanded state for the trigger input.
-         * Delays the "true" transition so VoiceOver finishes its character echo
-         * before announcing "expanded".
-         * @private
-         */
-        triggerExpandedState: {
-            type: BooleanConstructor;
-            reflect: boolean;
-            attribute: boolean;
-        };
     };
     static get styles(): import("lit").CSSResult[];
     /**
@@ -359,8 +351,6 @@ export class AuroCombobox extends AuroElement {
     availableOptions: any[] | any[] | undefined;
     dropdownId: any;
     dropdownOpen: any;
-    triggerExpandedState: boolean | undefined;
-    _expandedTimeout: number | null | undefined;
     _inFullscreenTransition: boolean | undefined;
     errorMessage: any;
     isHiddenWhileLoading: boolean | undefined;
@@ -371,6 +361,18 @@ export class AuroCombobox extends AuroElement {
     touched: boolean | undefined;
     validation: AuroFormValidation | undefined;
     validity: any;
+    _userTyped: boolean | undefined;
+    _pendingTimers: Set<any> | undefined;
+    /**
+     * Wraps setTimeout and records the timer id so disconnectedCallback
+     * can cancel any outstanding callbacks. The id is removed from the set
+     * once the callback fires so the set doesn't grow unbounded.
+     * @param {Function} fn - Callback to run.
+     * @param {number} ms - Delay in milliseconds.
+     * @returns {number} The timer id.
+     * @private
+     */
+    private _scheduleTimer;
     /**
      * Returns the current value of the input element within the combobox.
      * @returns {string|undefined} The value of the input element, or undefined if the input is not present.
@@ -411,9 +413,29 @@ export class AuroCombobox extends AuroElement {
      * @private
      */
     private updateTriggerTextDisplay;
+    /**
+     * Writes nextValue to the trigger input and the bib input when their current
+     * value differs, then re-asserts imask after Lit's update flushes.
+     * @param {string} nextValue - The value to write to both inputs.
+     * @returns {Promise<void>} Resolves after both inputs flush and imask
+     *   re-asserts; resolves immediately when no sync is needed.
+     * @private
+     */
+    private syncInputValuesAcrossTriggerAndBib;
+    _syncingDisplayValue: boolean | undefined;
     /**
      * Processes hidden state of all menu options and determines if there are any available options not hidden.
      * @private
+     * @param {object} [options={}] - Optional flag bag.
+     * @param {boolean} [options.preferComboboxValue=false] - When true,
+     *   handleMenuOptions matches the selected option against `this.value`
+     *   first instead of `this.input.value`. Needed on mount and re-mount
+     *   because under `persistInput` the consumer's typedValue prop can drift
+     *   from the framework value (Svelte `{#key}` re-mount after a swap, or
+     *   SPA preselect after route change) and the old input-first match would
+     *   then pick the stale text. Only handleSlotChange passes this; typing
+     *   and clearing paths keep the input-first match so user clears aren't
+     *   undone.
      * @returns {void}
      */
     private handleMenuOptions;
@@ -483,7 +505,10 @@ export class AuroCombobox extends AuroElement {
     private configureMenu;
     menu: Element | null | undefined;
     defaultMenuShape: string | null | undefined;
+    _pendingMenuValueSync: boolean | undefined;
     value: any;
+    _suppressClearBtnFocusOnSelection: boolean | undefined;
+    _programmaticFilterRefresh: boolean | undefined;
     /**
      * Binds all behavior needed to the input after rendering.
      * @private
@@ -513,6 +538,15 @@ export class AuroCombobox extends AuroElement {
      */
     private handleInputValueChange;
     _syncingBibValue: boolean | undefined;
+    /**
+     * Handles input value changes originating from the trigger input.
+     * Refreshes menu options and filtering, delegates to handleInputValueChange
+     * for value synchronization, and manages fullscreen bib focus.
+     * @private
+     * @param {Event} event - The input event from the trigger input element.
+     * @returns {void}
+     */
+    private handleTriggerInputValueChange;
     /**
      * Binds all behavior needed to the combobox after rendering.
      * @private
@@ -544,13 +578,13 @@ export class AuroCombobox extends AuroElement {
      * @returns {void}
      */
     clear(): void;
+    _clearing: boolean | undefined;
     /**
      * Validates value.
      * @param {boolean} [force=false] - Whether to force validation.
      */
     validate(force?: boolean): void;
     updated(changedProperties: any): void;
-    hasValue: boolean | undefined;
     /**
      * Applies slotted nodes to a target element with a new slot name.
      * @private