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

package/components/menu/demo/api.md

@@ -21,7 +21,7 @@ The `auro-menu` element provides users a way to select from a list of options.
 | [noCheckmark](#noCheckmark)              | `nocheckmark`              |           | `boolean`             | false       | When true, selected option will not show the checkmark. |
 | [optionActive](#optionActive)             | `optionactive`             |           | `object`              | "undefined" | Specifies the current active menuOption.         |
 | [optionSelected](#optionSelected)           | `optionSelected`           |           | `object`              | "undefined" | An array of currently selected menu options, type `HTMLElement` by default. In multi-select mode, `optionSelected` is an array of HTML elements. |
-| [options](#options)                  |                            | readonly  | `array`               |             | Available menu options                           |
+| [options](#options)                  |                            | readonly  | `array`               |             | Available menu options.                          |
 | [selectAllMatchingOptions](#selectAllMatchingOptions) | `selectAllMatchingOptions` |           | `boolean`             | false       | When true, selects all options that match the provided value/key when setting value and multiselect is enabled. |
 | [selectedOption](#selectedOption)           |                            | readonly  | `HTMLElement \| null` |             | Gets the first selected option, or null if none. |
 | [selectedOptions](#selectedOptions)          |                            | readonly  | `HTMLElement[]`       |             | Gets the currently selected options.             |

package/components/menu/demo/api.min.js

@@ -650,10 +650,20 @@ class AuroMenuOption extends AuroElement {
       subscribe: true
     });
 
-    // Establish the key property as early as possible
+    // Establish the key property as early as possible.
+    // When a framework (e.g. Svelte) inserts the element into the DOM before
+    // setting its `value` property, both `getAttribute('value')` and
+    // `getAttribute('key')` return null here. Setting `this.key = null`
+    // would block the fallback in `updated()` that assigns key from the
+    // value property (the guard checked `=== undefined`). Only assign key
+    // if at least one source attribute is actually present so that the
+    // `updated()` fallback can run when the value property arrives later.
     const valueAttr = this.getAttribute('value');
     const keyAttr = this.getAttribute('key');
-    this.key = keyAttr !== null ? keyAttr : valueAttr;
+    const resolvedKey = keyAttr !== null ? keyAttr : valueAttr;
+    if (resolvedKey !== null) {
+      this.key = resolvedKey;
+    }
   }
 
   firstUpdated() {
@@ -703,8 +713,14 @@ class AuroMenuOption extends AuroElement {
       this.updateTextHighlight();
     }
 
-    // Set the key to be the passed value if no key is provided
-    if (changedProperties.has('value') && this.key === undefined) {
+    // Set the key to be the passed value if no key is provided.
+    // Loose equality (== null) is intentional: it catches both null AND
+    // undefined. When a framework (e.g. Svelte, React) inserts the element
+    // before setting its value property, connectedCallback skips key
+    // assignment because both attributes are null at that point. The Lit
+    // property default for `key` is undefined (not null), so strict
+    // === null would miss the case and the fallback would never run.
+    if (changedProperties.has('value') && this.key == null) { // eslint-disable-line eqeqeq, no-eq-null
       this.key = this.value;
     }
   }
@@ -1073,6 +1089,9 @@ class MenuService {
     this._subscribers = [];
     this.internalUpdateInProgress = false;
     this.selectedOptions = [];
+    this._pendingValue = null;
+    this._pendingRetryScheduled = false;
+    this._pendingRetryCount = 0;
   }
 
   /**
@@ -1112,6 +1131,9 @@ class MenuService {
   hostDisconnected() {
     this._subscribers = [];
     this._menuOptions = [];
+    this._pendingValue = null;
+    this._pendingRetryScheduled = false;
+    this._pendingRetryCount = 0;
   }
 
   /**
@@ -1314,17 +1336,22 @@ class MenuService {
    * @param {string|number|Array<string|number>} value - The value(s) to select.
    */
   selectByValue(value) {
-    // Early exit for invalid/empty values or internal updates
-    if (this.internalUpdateInProgress ||
-        this.host.internalUpdateInProgress ||
-        value === undefined ||
+    const isEmptyValue = value === undefined ||
         value === null ||
         (Array.isArray(value) && value.length === 0) ||
-        (typeof value === 'string' && value.trim() === '')) {
+        (typeof value === 'string' && value.trim() === '');
+
+    // Early exit for invalid/empty values
+    if (isEmptyValue) {
       return;
     }
 
-    this.reset();
+    // If an internal update cycle is still in progress, defer value application
+    // rather than dropping it.
+    if (this.internalUpdateInProgress || this.host.internalUpdateInProgress) {
+      this.queuePendingValue(value);
+      return;
+    }
 
     // Normalize values to array of strings
     const normalizedValues = this._getNormalizedValues(value);
@@ -1336,33 +1363,100 @@ class MenuService {
       validatedValues = [normalizedValues[0]];
     }
 
+    if (this._menuOptions.length === 0) {
+      this.queuePendingValue(value);
+      return;
+    }
+
     // Find matching options by comparing available options to validated values
     const trackedKeys = new Set();
     const optionsToSelect = this._menuOptions.filter(option => {
       const passesFilter = validatedValues.includes(option.key);
       const alreadyTracked = trackedKeys.has(option.key);
+      const isActive = option.isActive;
       
       trackedKeys.add(option.key);
 
       // Include the option in the options to be selected if it passes the filter check and
       // either hasn't been tracked yet or selectAllMatchingOptions is true
-      return passesFilter && (!alreadyTracked || (alreadyTracked && this.selectAllMatchingOptions));
+      return isActive && passesFilter && (!alreadyTracked || (alreadyTracked && this.selectAllMatchingOptions));
     });
 
-    // Handle selection result
-    if (optionsToSelect.length && !this.optionsArraysMatch(optionsToSelect, this.selectedOptions)) {
-      this.selectOptions(optionsToSelect);
-    } else {
-      this.stageUpdate();
+    // Handle no matches: clear existing selection, but do not dispatch an intermediate
+    // undefined value that can overwrite the host value in parent components.
+    if (!optionsToSelect.length) {
+      const hasUnresolvedKeys = this._menuOptions.some((option) => option.isActive && option.key == null);
+
+      if (hasUnresolvedKeys) {
+        this.queuePendingValue(value);
+        return;
+      }
+
+      this.clearPendingValue();
+
+      if (this.selectedOptions.length > 0) {
+        this.selectedOptions = [];
+      }
+
+      // Always notify so the host resets any stale invalid value, even when
+      // selectedOptions was already empty (e.g. double-clicking set-invalid).
+      this.stageUpdate({ reason: 'no-match' });
+
+      // Dispatch failure event if no matches found
+      if (validatedValues.length) {
+        this.dispatchChangeEvent('auroMenu-selectValueFailure', {
+          message: 'No matching options found for the provided value(s).',
+          values: validatedValues
+        });
+      }
+
+      return;
     }
 
-    // Dispatch failure event if no matches found
-    if (!optionsToSelect.length && validatedValues.length) {
-      this.dispatchChangeEvent('auroMenu-selectValueFailure', {
-        message: 'No matching options found for the provided value(s).',
-        values: validatedValues
-      });
+    this.clearPendingValue();
+
+    if (this.optionsArraysMatch(optionsToSelect, this.selectedOptions)) {
+      return;
+    }
+
+    // Apply programmatic selection as a single transaction and emit one final state.
+    this.selectedOptions = optionsToSelect;
+    this.stageUpdate();
+  }
+
+  /**
+   * Queues a pending value and schedules a bounded retry.
+   * @param {string|number|Array<string|number>} value - The value to retry.
+   */
+  queuePendingValue(value) {
+    this._pendingValue = value;
+
+    if (this._pendingRetryScheduled || this._pendingRetryCount >= 5) {
+      return;
     }
+
+    this._pendingRetryScheduled = true;
+    this._pendingRetryCount += 1;
+
+    setTimeout(() => {
+      this._pendingRetryScheduled = false;
+
+      if (this._pendingValue == null) {
+        return;
+      }
+
+      const pendingValue = this._pendingValue;
+      this.selectByValue(pendingValue);
+    }, 0);
+  }
+
+  /**
+   * Clears pending retry state.
+   */
+  clearPendingValue() {
+    this._pendingValue = null;
+    this._pendingRetryScheduled = false;
+    this._pendingRetryCount = 0;
   }
 
   /**
@@ -1401,9 +1495,9 @@ class MenuService {
   /**
    * Stages an update to notify subscribers of state and value changes.
    */
-  stageUpdate() {
-    this.notifyStateChange();
-    this.notifyValueChange();
+  stageUpdate(meta = {}) {
+    this.notifyStateChange(meta);
+    this.notifyValueChange(meta);
   }
 
   /**
@@ -1418,14 +1512,18 @@ class MenuService {
   /**
    * Notifies subscribers of a state change (selected options has changed).
    */
-  notifyStateChange() {
-    this.notify({ type: 'stateChange', selectedOptions: this.selectedOptions });
+  notifyStateChange(meta = {}) {
+    this.notify({
+      type: 'stateChange',
+      selectedOptions: this.selectedOptions,
+      ...meta
+    });
   }
 
   /**
    * Notifies subscribers of a value change (current value has changed).
    */
-  notifyValueChange() {
+  notifyValueChange(meta = {}) {
 
     // Prepare details for the event
     const details = {
@@ -1441,10 +1539,9 @@ class MenuService {
 
     this.notify({
       type: 'valueChange',
+      ...meta,
       ...details
     });
-
-    this.dispatchChangeEvent('auroMenu-selectedOption', details);
   }
 
   /**
@@ -1472,6 +1569,10 @@ class MenuService {
   addMenuOption(option) {
     this._menuOptions.push(option);
     this.notify({ type: 'optionsChange', options: this._menuOptions });
+
+    if (this._pendingValue != null) {
+      this.queuePendingValue(this._pendingValue);
+    }
   }
 
   /**
@@ -1481,6 +1582,10 @@ class MenuService {
   removeMenuOption(option) {
     this._menuOptions = this._menuOptions.filter(opt => opt !== option);
     this.notify({ type: 'optionsChange', options: this._menuOptions });
+
+    if (this._menuOptions.length === 0) {
+      this.clearPendingValue();
+    }
   }
 
   /**
@@ -1754,7 +1859,7 @@ class AuroMenu extends AuroElement {
       },
 
       /**
-       * Available menu options
+       * Available menu options.
        * @readonly
        */
       options: {
@@ -1821,7 +1926,7 @@ class AuroMenu extends AuroElement {
   /**
    * @readonly
    * @returns {Array<HTMLElement>} - Returns the array of available menu options.
-   * @deprecated use `options` property instead.
+   * @deprecated Use `options` property instead.
    */
   get items() {
     return this.options;
@@ -1929,7 +2034,7 @@ class AuroMenu extends AuroElement {
       const newValue = event.stringValue;
 
       // Check if the option or value has actually changed
-      if (newValue === undefined || (this.optionSelected !== newOption || this.stringValue !== newValue)) {
+      if (this.optionSelected !== newOption || this.stringValue !== newValue) {
         this.optionSelected = newOption;
         this.setInternalValue(newValue);
       }
@@ -2003,8 +2108,13 @@ class AuroMenu extends AuroElement {
   updated(changedProperties) {
     super.updated(changedProperties);
 
-    // Update menu service properties on host update
-    if (changedProperties.has('value')) {
+    // Apply value selection synchronously so that static-HTML fixtures
+    // resolve within a single update cycle.  The refactored selectByValue
+    // no longer calls reset() first, so the destructive intermediate-event
+    // cascade that originally required deferral is eliminated.  If option
+    // keys are not yet resolved (framework mount-order race), selectByValue
+    // queues a bounded retry automatically via queuePendingValue.
+    if (changedProperties.has('value') && !this.internalUpdateInProgress) {
       this.menuService.selectByValue(this.value);
     }
 
@@ -2184,12 +2294,13 @@ class AuroMenu extends AuroElement {
    * @param {any} source - The source that triggers this event.
    * @private
    */
-  notifySelectionChange({value, stringValue, keys, options} = {}) {
+  notifySelectionChange({value, stringValue, keys, options, reason} = {}) {
     dispatchMenuEvent(this, 'auroMenu-selectedOption', {
       value,
       stringValue,
       keys,
-      options
+      options,
+      reason
     });
   }
 

package/components/menu/demo/index.min.js

@@ -558,10 +558,20 @@ class AuroMenuOption extends AuroElement {
       subscribe: true
     });
 
-    // Establish the key property as early as possible
+    // Establish the key property as early as possible.
+    // When a framework (e.g. Svelte) inserts the element into the DOM before
+    // setting its `value` property, both `getAttribute('value')` and
+    // `getAttribute('key')` return null here. Setting `this.key = null`
+    // would block the fallback in `updated()` that assigns key from the
+    // value property (the guard checked `=== undefined`). Only assign key
+    // if at least one source attribute is actually present so that the
+    // `updated()` fallback can run when the value property arrives later.
     const valueAttr = this.getAttribute('value');
     const keyAttr = this.getAttribute('key');
-    this.key = keyAttr !== null ? keyAttr : valueAttr;
+    const resolvedKey = keyAttr !== null ? keyAttr : valueAttr;
+    if (resolvedKey !== null) {
+      this.key = resolvedKey;
+    }
   }
 
   firstUpdated() {
@@ -611,8 +621,14 @@ class AuroMenuOption extends AuroElement {
       this.updateTextHighlight();
     }
 
-    // Set the key to be the passed value if no key is provided
-    if (changedProperties.has('value') && this.key === undefined) {
+    // Set the key to be the passed value if no key is provided.
+    // Loose equality (== null) is intentional: it catches both null AND
+    // undefined. When a framework (e.g. Svelte, React) inserts the element
+    // before setting its value property, connectedCallback skips key
+    // assignment because both attributes are null at that point. The Lit
+    // property default for `key` is undefined (not null), so strict
+    // === null would miss the case and the fallback would never run.
+    if (changedProperties.has('value') && this.key == null) { // eslint-disable-line eqeqeq, no-eq-null
       this.key = this.value;
     }
   }
@@ -981,6 +997,9 @@ class MenuService {
     this._subscribers = [];
     this.internalUpdateInProgress = false;
     this.selectedOptions = [];
+    this._pendingValue = null;
+    this._pendingRetryScheduled = false;
+    this._pendingRetryCount = 0;
   }
 
   /**
@@ -1020,6 +1039,9 @@ class MenuService {
   hostDisconnected() {
     this._subscribers = [];
     this._menuOptions = [];
+    this._pendingValue = null;
+    this._pendingRetryScheduled = false;
+    this._pendingRetryCount = 0;
   }
 
   /**
@@ -1222,17 +1244,22 @@ class MenuService {
    * @param {string|number|Array<string|number>} value - The value(s) to select.
    */
   selectByValue(value) {
-    // Early exit for invalid/empty values or internal updates
-    if (this.internalUpdateInProgress ||
-        this.host.internalUpdateInProgress ||
-        value === undefined ||
+    const isEmptyValue = value === undefined ||
         value === null ||
         (Array.isArray(value) && value.length === 0) ||
-        (typeof value === 'string' && value.trim() === '')) {
+        (typeof value === 'string' && value.trim() === '');
+
+    // Early exit for invalid/empty values
+    if (isEmptyValue) {
       return;
     }
 
-    this.reset();
+    // If an internal update cycle is still in progress, defer value application
+    // rather than dropping it.
+    if (this.internalUpdateInProgress || this.host.internalUpdateInProgress) {
+      this.queuePendingValue(value);
+      return;
+    }
 
     // Normalize values to array of strings
     const normalizedValues = this._getNormalizedValues(value);
@@ -1244,33 +1271,100 @@ class MenuService {
       validatedValues = [normalizedValues[0]];
     }
 
+    if (this._menuOptions.length === 0) {
+      this.queuePendingValue(value);
+      return;
+    }
+
     // Find matching options by comparing available options to validated values
     const trackedKeys = new Set();
     const optionsToSelect = this._menuOptions.filter(option => {
       const passesFilter = validatedValues.includes(option.key);
       const alreadyTracked = trackedKeys.has(option.key);
+      const isActive = option.isActive;
       
       trackedKeys.add(option.key);
 
       // Include the option in the options to be selected if it passes the filter check and
       // either hasn't been tracked yet or selectAllMatchingOptions is true
-      return passesFilter && (!alreadyTracked || (alreadyTracked && this.selectAllMatchingOptions));
+      return isActive && passesFilter && (!alreadyTracked || (alreadyTracked && this.selectAllMatchingOptions));
     });
 
-    // Handle selection result
-    if (optionsToSelect.length && !this.optionsArraysMatch(optionsToSelect, this.selectedOptions)) {
-      this.selectOptions(optionsToSelect);
-    } else {
-      this.stageUpdate();
+    // Handle no matches: clear existing selection, but do not dispatch an intermediate
+    // undefined value that can overwrite the host value in parent components.
+    if (!optionsToSelect.length) {
+      const hasUnresolvedKeys = this._menuOptions.some((option) => option.isActive && option.key == null);
+
+      if (hasUnresolvedKeys) {
+        this.queuePendingValue(value);
+        return;
+      }
+
+      this.clearPendingValue();
+
+      if (this.selectedOptions.length > 0) {
+        this.selectedOptions = [];
+      }
+
+      // Always notify so the host resets any stale invalid value, even when
+      // selectedOptions was already empty (e.g. double-clicking set-invalid).
+      this.stageUpdate({ reason: 'no-match' });
+
+      // Dispatch failure event if no matches found
+      if (validatedValues.length) {
+        this.dispatchChangeEvent('auroMenu-selectValueFailure', {
+          message: 'No matching options found for the provided value(s).',
+          values: validatedValues
+        });
+      }
+
+      return;
     }
 
-    // Dispatch failure event if no matches found
-    if (!optionsToSelect.length && validatedValues.length) {
-      this.dispatchChangeEvent('auroMenu-selectValueFailure', {
-        message: 'No matching options found for the provided value(s).',
-        values: validatedValues
-      });
+    this.clearPendingValue();
+
+    if (this.optionsArraysMatch(optionsToSelect, this.selectedOptions)) {
+      return;
+    }
+
+    // Apply programmatic selection as a single transaction and emit one final state.
+    this.selectedOptions = optionsToSelect;
+    this.stageUpdate();
+  }
+
+  /**
+   * Queues a pending value and schedules a bounded retry.
+   * @param {string|number|Array<string|number>} value - The value to retry.
+   */
+  queuePendingValue(value) {
+    this._pendingValue = value;
+
+    if (this._pendingRetryScheduled || this._pendingRetryCount >= 5) {
+      return;
     }
+
+    this._pendingRetryScheduled = true;
+    this._pendingRetryCount += 1;
+
+    setTimeout(() => {
+      this._pendingRetryScheduled = false;
+
+      if (this._pendingValue == null) {
+        return;
+      }
+
+      const pendingValue = this._pendingValue;
+      this.selectByValue(pendingValue);
+    }, 0);
+  }
+
+  /**
+   * Clears pending retry state.
+   */
+  clearPendingValue() {
+    this._pendingValue = null;
+    this._pendingRetryScheduled = false;
+    this._pendingRetryCount = 0;
   }
 
   /**
@@ -1309,9 +1403,9 @@ class MenuService {
   /**
    * Stages an update to notify subscribers of state and value changes.
    */
-  stageUpdate() {
-    this.notifyStateChange();
-    this.notifyValueChange();
+  stageUpdate(meta = {}) {
+    this.notifyStateChange(meta);
+    this.notifyValueChange(meta);
   }
 
   /**
@@ -1326,14 +1420,18 @@ class MenuService {
   /**
    * Notifies subscribers of a state change (selected options has changed).
    */
-  notifyStateChange() {
-    this.notify({ type: 'stateChange', selectedOptions: this.selectedOptions });
+  notifyStateChange(meta = {}) {
+    this.notify({
+      type: 'stateChange',
+      selectedOptions: this.selectedOptions,
+      ...meta
+    });
   }
 
   /**
    * Notifies subscribers of a value change (current value has changed).
    */
-  notifyValueChange() {
+  notifyValueChange(meta = {}) {
 
     // Prepare details for the event
     const details = {
@@ -1349,10 +1447,9 @@ class MenuService {
 
     this.notify({
       type: 'valueChange',
+      ...meta,
       ...details
     });
-
-    this.dispatchChangeEvent('auroMenu-selectedOption', details);
   }
 
   /**
@@ -1380,6 +1477,10 @@ class MenuService {
   addMenuOption(option) {
     this._menuOptions.push(option);
     this.notify({ type: 'optionsChange', options: this._menuOptions });
+
+    if (this._pendingValue != null) {
+      this.queuePendingValue(this._pendingValue);
+    }
   }
 
   /**
@@ -1389,6 +1490,10 @@ class MenuService {
   removeMenuOption(option) {
     this._menuOptions = this._menuOptions.filter(opt => opt !== option);
     this.notify({ type: 'optionsChange', options: this._menuOptions });
+
+    if (this._menuOptions.length === 0) {
+      this.clearPendingValue();
+    }
   }
 
   /**
@@ -1662,7 +1767,7 @@ class AuroMenu extends AuroElement {
       },
 
       /**
-       * Available menu options
+       * Available menu options.
        * @readonly
        */
       options: {
@@ -1729,7 +1834,7 @@ class AuroMenu extends AuroElement {
   /**
    * @readonly
    * @returns {Array<HTMLElement>} - Returns the array of available menu options.
-   * @deprecated use `options` property instead.
+   * @deprecated Use `options` property instead.
    */
   get items() {
     return this.options;
@@ -1837,7 +1942,7 @@ class AuroMenu extends AuroElement {
       const newValue = event.stringValue;
 
       // Check if the option or value has actually changed
-      if (newValue === undefined || (this.optionSelected !== newOption || this.stringValue !== newValue)) {
+      if (this.optionSelected !== newOption || this.stringValue !== newValue) {
         this.optionSelected = newOption;
         this.setInternalValue(newValue);
       }
@@ -1911,8 +2016,13 @@ class AuroMenu extends AuroElement {
   updated(changedProperties) {
     super.updated(changedProperties);
 
-    // Update menu service properties on host update
-    if (changedProperties.has('value')) {
+    // Apply value selection synchronously so that static-HTML fixtures
+    // resolve within a single update cycle.  The refactored selectByValue
+    // no longer calls reset() first, so the destructive intermediate-event
+    // cascade that originally required deferral is eliminated.  If option
+    // keys are not yet resolved (framework mount-order race), selectByValue
+    // queues a bounded retry automatically via queuePendingValue.
+    if (changedProperties.has('value') && !this.internalUpdateInProgress) {
       this.menuService.selectByValue(this.value);
     }
 
@@ -2092,12 +2202,13 @@ class AuroMenu extends AuroElement {
    * @param {any} source - The source that triggers this event.
    * @private
    */
-  notifySelectionChange({value, stringValue, keys, options} = {}) {
+  notifySelectionChange({value, stringValue, keys, options, reason} = {}) {
     dispatchMenuEvent(this, 'auroMenu-selectedOption', {
       value,
       stringValue,
       keys,
-      options
+      options,
+      reason
     });
   }