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

package/components/menu/dist/auro-menu.context.d.ts

@@ -59,6 +59,9 @@ export class MenuService {
     _subscribers: any[];
     internalUpdateInProgress: boolean;
     selectedOptions: any[];
+    _pendingValue: string | number | (string | number)[];
+    _pendingRetryScheduled: boolean;
+    _pendingRetryCount: number;
     /**
      * PROPERTY SYNCING
      */
@@ -149,6 +152,15 @@ export class MenuService {
      * @param {string|number|Array<string|number>} value - The value(s) to select.
      */
     selectByValue(value: string | number | Array<string | number>): void;
+    /**
+     * Queues a pending value and schedules a bounded retry.
+     * @param {string|number|Array<string|number>} value - The value to retry.
+     */
+    queuePendingValue(value: string | number | Array<string | number>): void;
+    /**
+     * Clears pending retry state.
+     */
+    clearPendingValue(): void;
     /**
      * Resets the selected options to an empty array.
      */
@@ -169,7 +181,7 @@ export class MenuService {
     /**
      * Stages an update to notify subscribers of state and value changes.
      */
-    stageUpdate(): void;
+    stageUpdate(meta?: {}): void;
     /**
      * Notifies subscribers of a menu service event.
      * All notifications are sent to all subscribers.
@@ -179,11 +191,11 @@ export class MenuService {
     /**
      * Notifies subscribers of a state change (selected options has changed).
      */
-    notifyStateChange(): void;
+    notifyStateChange(meta?: {}): void;
     /**
      * Notifies subscribers of a value change (current value has changed).
      */
-    notifyValueChange(): void;
+    notifyValueChange(meta?: {}): void;
     /**
      * Dispatches a custom event from the host element.
      * @param {string} eventName

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

@@ -171,7 +171,7 @@ export 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.
      */
     readonly get items(): Array<HTMLElement>;
     /**

package/components/menu/dist/index.js

@@ -532,10 +532,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() {
@@ -585,8 +595,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;
     }
   }
@@ -955,6 +971,9 @@ class MenuService {
     this._subscribers = [];
     this.internalUpdateInProgress = false;
     this.selectedOptions = [];
+    this._pendingValue = null;
+    this._pendingRetryScheduled = false;
+    this._pendingRetryCount = 0;
   }
 
   /**
@@ -994,6 +1013,9 @@ class MenuService {
   hostDisconnected() {
     this._subscribers = [];
     this._menuOptions = [];
+    this._pendingValue = null;
+    this._pendingRetryScheduled = false;
+    this._pendingRetryCount = 0;
   }
 
   /**
@@ -1196,17 +1218,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);
@@ -1218,33 +1245,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;
   }
 
   /**
@@ -1283,9 +1377,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);
   }
 
   /**
@@ -1300,14 +1394,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 = {
@@ -1323,10 +1421,9 @@ class MenuService {
 
     this.notify({
       type: 'valueChange',
+      ...meta,
       ...details
     });
-
-    this.dispatchChangeEvent('auroMenu-selectedOption', details);
   }
 
   /**
@@ -1354,6 +1451,10 @@ class MenuService {
   addMenuOption(option) {
     this._menuOptions.push(option);
     this.notify({ type: 'optionsChange', options: this._menuOptions });
+
+    if (this._pendingValue != null) {
+      this.queuePendingValue(this._pendingValue);
+    }
   }
 
   /**
@@ -1363,6 +1464,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();
+    }
   }
 
   /**
@@ -1636,7 +1741,7 @@ class AuroMenu extends AuroElement {
       },
 
       /**
-       * Available menu options
+       * Available menu options.
        * @readonly
        */
       options: {
@@ -1703,7 +1808,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;
@@ -1811,7 +1916,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);
       }
@@ -1885,8 +1990,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);
     }
 
@@ -2066,12 +2176,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
     });
   }