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

package/components/menu/dist/index.js

@@ -1,5 +1,4 @@
 import { css, LitElement, html } from 'lit';
-import { createContext, ContextProvider, ContextConsumer } from '@lit/context';
 import { classMap } from 'lit/directives/class-map.js';
 import { unsafeStatic, literal, html as html$1 } from 'lit/static-html.js';
 import { ifDefined } from 'lit/directives/if-defined.js';
@@ -114,720 +113,6 @@ class AuroElement extends LitElement {
   }
 }
 
-/* eslint-disable */
-
-class MenuService {
-
-  /**
-   * PROPERTIES AND GETTERS
-   */
-
-  /**
-   * Gets the list of registered menu options.
-   * @returns {AuroMenuOption[]}
-   */
-  get menuOptions() {
-    return this._menuOptions;
-  }
-
-  /**
-   * Gets the currently highlighted option.
-   * @returns {AuroMenuOption|null}
-   */
-  get highlightedOption() {
-    return this._menuOptions[this.highlightedIndex] || null;
-  }
-
-  /**
-   * Gets the current value(s) of the selected option(s).
-   * @returns {string|string[]|undefined}
-   */
-  get currentValue() {
-    const values = (this.selectedOptions || []).map(option => option.value);
-    return this.multiSelect ? values : values[0];
-  }
-
-  /**
-   * Gets the label(s) of the currently selected option(s).
-   * @returns {string}
-   */
-  get currentLabel() {
-    const labels = (this.selectedOptions || []).map(option => option.textContent);
-    return this.multiSelect ? labels.join(", ") : labels[0] || '';
-  }
-
-  /**
-   * Gets the string representation of the current value(s).
-   * For multi-select, this is a JSON stringified array.
-   * @returns {string|undefined}
-   */
-  get stringValue() {
-    const { currentValue } = this;
-
-    if (Array.isArray(currentValue)) {
-      if (currentValue.length > 0) {
-        return JSON.stringify(currentValue);
-      }
-      return undefined;
-    }
-
-    if (typeof currentValue === 'string') {
-      if (currentValue.length > 0) {
-        return currentValue;
-      }
-      return undefined;
-    }
-
-    // Future: handle other types here (e.g., number, object, etc.)
-    return undefined;
-  }
-
-  /**
-   * Gets the key(s) of the currently selected option(s).
-   * @returns {string|string[]|undefined}
-   */
-  get currentKeys() {
-    const keys = (this.selectedOptions || []).map(option => option.key);
-    return this.multiSelect ? keys : keys[0];
-  }
-
-  /**
-   * CONSTRUCTOR
-   */
-
-  /**
-   * Creates a new MenuService instance.
-   * @param {Object} options - The options object.
-   *   @param {AuroMenu} options.host - The host element that this service will control. Required.
-   * @throws {Error} If the host is not provided.
-   */
-  constructor({ host } = {}) {
-
-    // Ensure a host was passed
-    if (!host) {
-      throw new Error("MenuService requires a host element.");
-    }
-
-    // Attach the service to the host
-    this.host = host;
-    this.host.addController(this);
-
-    // Set default properties
-    this.size = undefined;
-    this.shape = undefined;
-    this.noCheckmark = undefined;
-    this.disabled = undefined;
-    this.matchWord = undefined;
-    this.multiSelect = undefined;
-    this.allowDeselect = undefined;
-    this.selectAllMatchingOptions = undefined;
-
-    this.highlightedIndex = -1;
-
-    this._menuOptions = [];
-    this._subscribers = [];
-    this.internalUpdateInProgress = false;
-    this.selectedOptions = [];
-    this._pendingValue = null;
-    this._pendingRetryScheduled = false;
-    this._pendingRetryCount = 0;
-  }
-
-  /**
-   * PROPERTY SYNCING
-   */
-
-  /**
-   * Handles host updates.
-   * This is a lit reactive lifecycle method.
-   * This comes from the Lit controller interface provided by adding this service as a controller to the host.
-   * See constructor for `this.host.addController(this)`
-   * You can read more about Lit reactive controllers here: https://lit.dev/docs/composition/controllers/
-   */
-  hostUpdated() {
-
-    // Reset selection if multiSelect mode changes
-    if (this.host.multiSelect !== this.multiSelect) {
-      this.selectedOptions = [];
-    }
-
-    // Update properties on host update
-    this.setProperties({
-      size: this.host.size,
-      shape: this.host.shape,
-      noCheckmark: this.host.noCheckmark,
-      disabled: this.host.disabled,
-      matchWord: this.host.matchWord,
-      multiSelect: this.host.multiSelect,
-      allowDeselect: this.host.allowDeselect,
-      selectAllMatchingOptions: this.host.selectAllMatchingOptions
-    });
-  }
-
-  /**
-   * Handles host disconnection and memory cleanup.
-   */
-  hostDisconnected() {
-    this._subscribers = [];
-    this._menuOptions = [];
-    this._pendingValue = null;
-    this._pendingRetryScheduled = false;
-    this._pendingRetryCount = 0;
-  }
-
-  /**
-   * Sets a property value if it exists on the instance and the value has changed.
-   * @param {string} property
-   * @param {any} value
-   */
-  setProperty(property, value) {
-
-    // Only update if we are tracking the property in this service
-    if (this.hasOwnProperty(property)) {
-
-      // Check if the value has changed
-      const valueChanged = this[property] !== value;
-
-      // Update and notify if changed
-      if (valueChanged) {
-        this[property] = value;
-        this.notify({ property, value });
-      }
-    }
-  }
-
-  /**
-   * Sets multiple properties on the instance.
-   * @param {Object} properties - Key-value pairs of properties to set.
-   */
-  setProperties(properties) {
-    for (const [key, value] of Object.entries(properties)) {
-      this.setProperty(key, value);
-    }
-  }
-
-  /**
-   * MENU OPTION HIGHLIGHTING
-   */
-
-  /**
-   * Highlights the next active option in the menu.
-   */
-  highlightNext() {
-    this.moveHighlightedOption("next");
-  }
-
-  /**
-   * Highlights the previous active option in the menu.
-   */
-  highlightPrevious() {
-    this.moveHighlightedOption("previous");
-  }
-
-  /**
-   * Moves the highlighted option in the specified direction.
-   * @param {string} direction - The direction to move the highlight ("next" or "previous").
-   */
-  moveHighlightedOption(direction) {
-
-    // Get the active options
-    const activeOptions = this._menuOptions.filter(option => option.isActive);
-
-    // Get the currently active option
-    const currentActiveOption = activeOptions[activeOptions.indexOf(this.highlightedOption)];
-
-    // Determine the new index based on the currently active option and direction
-    let newIndex = currentActiveOption
-      ? direction === "previous"
-        ? activeOptions.indexOf(currentActiveOption) - 1
-        : activeOptions.indexOf(currentActiveOption) + 1
-      : direction === "previous"
-        ? activeOptions.length - 1
-        : 0;
-
-    // Wrap around the index if needed
-    newIndex = newIndex < 0 ? activeOptions.length - 1 : newIndex >= activeOptions.length ? 0 : newIndex;
-
-    // Get the new active option and set it as highlighted
-    const newActiveOption = activeOptions[newIndex];
-    this.setHighlightedOption(newActiveOption);
-  }
-
-  /**
-   * Sets the highlighted index to the specified option.
-   * @param {AuroMenuOption} option - The option to highlight.
-   */
-  setHighlightedOption(option) {
-
-    if (!option) return;
-
-    // Get the index of the option to highlight
-    const index = this._menuOptions.indexOf(option);
-
-    // Update highlighted index
-    this.highlightedIndex = index;
-
-    // Notify subscribers of highlight change
-    this.notify({ type: 'highlightChange', option, index: this.highlightedIndex });
-
-    // Dispatch the change event
-    this.dispatchChangeEvent('auroMenu-activatedOption', option);
-  }
-
-  /**
-   * Sets the highlighted option to the option at the specified index if it exists.
-   * @param {number} index
-   */
-  setHighlightedIndex(index) {
-    const option = this._menuOptions[index] || null;
-    this.setHighlightedOption(option);
-  }
-
-  /**
-   * Selects the currently highlighted option.
-   */
-  selectHighlightedOption() {
-    if (this.highlightedOption) {
-      this.toggleOption(this.highlightedOption);
-    }
-  }
-
-  /**
-   * SELECTION AND DESELECTION METHODS
-   */
-
-  /**
-   * Selects one or more options in a batch operation
-   * @param {AuroMenuOption|AuroMenuOption[]} options - Single option or array of options to select
-   */
-  selectOptions(options) {
-    let optionsToSelect = Array.isArray(options) ? options : [options];
-
-    // Filter out options that are inactive
-    optionsToSelect = optionsToSelect.filter(option => option.isActive);
-
-    if (!optionsToSelect.length) return;
-
-    if (this.multiSelect) {
-      this.selectedOptions = [...(this.selectedOptions || []), ...optionsToSelect];
-    } else {
-      // In single select mode, only take the last option
-      this.selectedOptions = [optionsToSelect[optionsToSelect.length - 1]];
-    }
-
-    this.stageUpdate();
-  }
-
-  /**
-   * Deselects one or more options in a batch operation
-   * @param {AuroMenuOption|AuroMenuOption[]} options - Single option or array of options to deselect
-   */
-  deselectOptions(options) {
-    const optionsToDeselect = Array.isArray(options) ? options : [options];
-
-    if (!optionsToDeselect.length) return;
-
-    // Check if deselection should be prevented
-    const shouldPreventDeselect = !this.allowDeselect && !this.multiSelect;
-    const isOnlySelectedOption = this.selectedOptions.length === 1 && optionsToDeselect.includes(this.selectedOptions[0]);
-
-    // Prevent deselecting the only selected option if not allowed
-    if (shouldPreventDeselect && isOnlySelectedOption) {
-      optionsToDeselect.forEach(option => {
-        option.selected = true;
-      });
-      this.dispatchChangeEvent('auroMenu-deselectPrevented', {
-        values: optionsToDeselect
-      });
-      return;
-    }
-
-    const optionsSet = new Set(optionsToDeselect);
-    const previousCount = this.selectedOptions.length;
-    this.selectedOptions = (this.selectedOptions || [])
-      .filter(opt => !optionsSet.has(opt));
-
-    if (this.selectedOptions.length < previousCount) {
-      this.stageUpdate();
-    }
-  }
-
-  /**
-   * Selects a single option.
-   * @param {AuroMenuOption} option
-   */
-  selectOption(option) {
-    this.selectOptions(option);
-  }
-
-  /**
-   * Deselects a single option.
-   * @param {AuroMenuOption} option
-   */
-  deselectOption(option) {
-    this.deselectOptions(option);
-  }
-
-  /**
-   * Toggles the selection state of a single option.
-   * @param {AuroMenuOption} option
-   */
-  toggleOption(option) {
-    if (option.selected) {
-      this.deselectOption(option);
-    } else {
-      this.selectOption(option);
-    }
-  }
-
-  /**
-   * Selects options based on their value(s) when compared to a passed value or values.
-   * Value or values are normalized to an array of strings that can be matched to option keys.
-   * @param {string|number|Array<string|number>} value - The value(s) to select.
-   */
-  selectByValue(value) {
-    const isEmptyValue = value === undefined ||
-        value === null ||
-        (Array.isArray(value) && value.length === 0) ||
-        (typeof value === 'string' && value.trim() === '');
-
-    // Early exit for invalid/empty values
-    if (isEmptyValue) {
-      this.selectedOptions.forEach(opt => opt.selected = false);
-      this.selectedOptions = [];
-      return;
-    }
-
-    // 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);
-
-    // Validate for single-select mode
-    let validatedValues = normalizedValues;
-    if (normalizedValues.length > 1 && !this.multiSelect) {
-      console.warn("MenuService - Multiple values provided for single-select menu. Only the first value will be selected.");
-      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 isActive && passesFilter && (!alreadyTracked || (alreadyTracked && this.selectAllMatchingOptions));
-    });
-
-    // 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;
-    }
-
-    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;
-  }
-
-  /**
-   * Resets the selected options to an empty array.
-   */
-  reset() {
-    const previousOptions = [...this.selectedOptions];
-    previousOptions.forEach(opt => opt.selected = false);
-    this.selectedOptions = [];
-
-    // Single update after clearing all
-    if (previousOptions.length) {
-      this.stageUpdate();
-    }
-  }
-
-  /**
-   * SUBSCRIPTION, NOTIFICATION AND EVENT DISPATCH METHODS
-   */
-
-  /**
-   * Subscribes a callback to menu service events.
-   * @param {Function} callback - The callback to invoke on events.
-   */
-  subscribe(callback) {
-    this._subscribers.push(callback);
-  }
-
-  /**
-   * Remove a previously subscribed callback from menu service events.
-   * @param {Function} callback
-   */
-  unsubscribe(callback) {
-    this._subscribers = this._subscribers.filter(cb => cb !== callback);
-  }
-
-  /**
-   * Stages an update to notify subscribers of state and value changes.
-   */
-  stageUpdate(meta = {}) {
-    this.notifyStateChange(meta);
-    this.notifyValueChange(meta);
-  }
-
-  /**
-   * Notifies subscribers of a menu service event.
-   * All notifications are sent to all subscribers.
-   * @param {string} event - The event to send to subscribers.
-   */
-  notify(event) {
-    this._subscribers.forEach(callback => callback(event));
-  }
-
-  /**
-   * Notifies subscribers of a state change (selected options has changed).
-   */
-  notifyStateChange(meta = {}) {
-    this.notify({
-      type: 'stateChange',
-      selectedOptions: this.selectedOptions,
-      ...meta
-    });
-  }
-
-  /**
-   * Notifies subscribers of a value change (current value has changed).
-   */
-  notifyValueChange(meta = {}) {
-
-    // Prepare details for the event
-    const details = {
-      value: this.currentValue,
-      stringValue: this.stringValue,
-      keys: this.currentKeys,
-      options: this.selectedOptions,
-      label: this.currentLabel
-    };
-
-    // If only one option is selected, include its index
-    if (this.selectedOptions.length === 1) details.index = this._menuOptions.indexOf(this.selectedOptions[0]);
-
-    this.notify({
-      type: 'valueChange',
-      ...meta,
-      ...details
-    });
-  }
-
-  /**
-   * Dispatches a custom event from the host element.
-   * @param {string} eventName
-   * @param {any} detail
-   */
-  dispatchChangeEvent(eventName, detail) {
-    this.host.dispatchEvent(new CustomEvent(eventName, {
-      bubbles: true,
-      cancelable: false,
-      composed: true,
-      detail
-    }));
-  }
-
-  /**
-   * MENU OPTION MANAGEMENT METHODS
-   */
-
-  /**
-   * Adds a menu option to the service's list.
-   * @param {AuroMenuOption} option - the option to track
-   */
-  addMenuOption(option) {
-    this._menuOptions.push(option);
-    this.notify({ type: 'optionsChange', options: this._menuOptions });
-
-    if (this._pendingValue != null) {
-      this.queuePendingValue(this._pendingValue);
-    }
-  }
-
-  /**
-   * Removes a menu option from the service's list.
-   * @param {AuroMenuOption} option - the option to remove
-   */
-  removeMenuOption(option) {
-    this._menuOptions = this._menuOptions.filter(opt => opt !== option);
-    this.notify({ type: 'optionsChange', options: this._menuOptions });
-
-    if (this._menuOptions.length === 0) {
-      this.clearPendingValue();
-    }
-  }
-
-  /**
-   * UTILITIES
-   */
-
-  /**
-   * Normalizes a value or array of values into an array of strings for option selection.
-   * This function ensures that input values are consistently formatted for matching menu options.
-   *
-   * @param {string|number|Array<string|number>} value - The value(s) to normalize.
-   * @returns {Array<string>} An array of string values suitable for option matching.
-   * @throws {Error} If any value is not a string or number.
-   */
-  _getNormalizedValues(value) {
-    let values = value;
-
-    // Handle JSON string and single value string input
-    if (!Array.isArray(values) && typeof values === 'string') {
-
-      // Attempt to parse as JSON array
-      try {
-
-        // Normalize single quotes to double quotes for JSON parsing
-        // This will not handle complex cases but will cover basic usage
-        const parseValue = values.replace(/'([^']*?)'/g, '"$1"');
-
-        // Attempt parse
-        const parsed = JSON.parse(parseValue);
-
-        // Ensure parsed value is an array
-        if (!Array.isArray(parsed)) throw new Error('Not an array');
-
-        // Set values to parsed array
-        values = parsed;
-      } catch (err) {
-
-        // If parsing fails, treat as single value
-        values = [value];
-      }
-    }
-
-    // Handle a single number being passed
-    if (typeof values === 'number') {
-      values = [String(values)];
-    }
-
-    // Coerce each value to string and validate types
-    values.forEach((val, index) => {
-
-      // Throw an error for invalid value types
-      if (typeof val !== 'string' && typeof val !== 'number') {
-        throw new Error('Value contains invalid value type. Supported types are string and number.');
-      }
-
-      // Convert numbers to strings for consistency
-      if (typeof val === 'number') {
-        values[index] = String(val);
-      }
-    });
-
-    // Return the resulting array of string values
-    return values;
-  }
-
-  /**
-   * Returns whether two arrays of options contain the same elements.
-   * @param {AuroMenuOption[]} arr1 - First array of options.
-   * @param {AuroMenuOption[]} arr2 - Second array of options.
-   * @returns {boolean} True if arrays match, false otherwise.
-   */
-  optionsArraysMatch(arr1, arr2) {
-    if (arr1.length !== arr2.length) return false;
-
-    const set1 = new Set(arr1);
-    const set2 = new Set(arr2);
-
-    for (let item of set1) {
-      if (!set2.has(item)) {
-        return false;
-      }
-    }
-
-    return true;
-  }
-}
-
-const MenuContext = createContext('menu-context');
-
 // Copyright (c) Alaska Air. All right reserved. Licensed under the Apache-2.0 license
 // See LICENSE in the project root for license information.
 
@@ -956,6 +241,18 @@ function arrayConverter(value) {
   throw new Error('Invalid value: Input must be an array or undefined');
 }
 
+/**
+ * Serializes a multi-select value array back into the String `value` property.
+ * An empty (or missing) array collapses to `undefined` so an emptied selection
+ * clears `value` rather than reflecting a `"[]"` attribute.
+ * @private
+ * @param {Array<string>|undefined} values - The selected values.
+ * @returns {string|undefined} JSON string of the values, or undefined when empty.
+ */
+function serializeMultiSelectValue(values) {
+  return values && values.length > 0 ? JSON.stringify(values) : undefined;
+}
+
 /**
  * Validates if an option can be interacted with.
  * @private
@@ -968,6 +265,20 @@ function isOptionInteractive(option) {
          !option.hasAttribute('static');
 }
 
+/**
+ * Validates if an option may be selected by matching a programmatic value.
+ * Unlike `isOptionInteractive`, `hidden` is allowed: the combobox toggles
+ * `hidden` as its type-ahead filter, so a filtered-out option is still a
+ * valid programmatic selection. Only disabled and static options — which are
+ * never selectable — are rejected.
+ * @param {HTMLElement} option - The option to check.
+ * @returns {boolean} True if option can be selected by value.
+ */
+function isSelectableByValue(option) {
+  return !option.hasAttribute('disabled') &&
+         !option.hasAttribute('static');
+}
+
 /**
  * Helper method to dispatch custom events.
  * @param {HTMLElement} element - Element to dispatch event from.
@@ -988,7 +299,7 @@ function dispatchMenuEvent(element, eventName, detail = null) {
   element.dispatchEvent(new CustomEvent(eventName, eventConfig));
 }
 
-/* eslint-disable no-underscore-dangle */
+/* eslint-disable no-underscore-dangle, no-magic-numbers, max-lines, no-extra-parens, max-depth */
 // Copyright (c) 2025 Alaska Airlines. All right reserved. Licensed under the Apache-2.0 license
 // See LICENSE in the project root for license information.
 
@@ -1002,16 +313,12 @@ function dispatchMenuEvent(element, eventName, detail = null) {
  * @event {CustomEvent<any>} auroMenu-customEventFired - Notifies that a custom event has been fired.
  * @event {CustomEvent<{ loading: boolean; hasLoadingPlaceholder: boolean; }>} auroMenu-loadingChange - Notifies when the loading attribute is changed.
  * @event {CustomEvent<any>} auroMenu-selectValueFailure - Notifies that an attempt to select a menuoption by matching a value has failed.
- * @event {CustomEvent<{ values: HTMLElement[] }>} auroMenu-deselectPrevented - Notifies that deselection was prevented and includes the affected options in `detail.values`.
  * @event {CustomEvent<any>} auroMenu-selectValueReset - Notifies that the component value has been reset.
  * @event {CustomEvent<any>} auroMenu-selectedOption - Notifies that a new menuoption selection has been made.
  * @slot loadingText - Text to show while loading attribute is set
  * @slot loadingIcon - Icon to show while loading attribute is set
  * @slot - Slot for insertion of menu options.
  */
-
-/* eslint-disable max-lines */
-
 class AuroMenu extends AuroElement {
 
   constructor() {
@@ -1029,6 +336,8 @@ class AuroMenu extends AuroElement {
      */
     this.size = "sm";
 
+    // Value of the selected options
+    this.value = undefined;
     // Currently selected option
     this.optionSelected = undefined;
     // String used for highlighting/filtering
@@ -1041,13 +350,24 @@ class AuroMenu extends AuroElement {
     this.loading = false;
     // Multi-select mode
     this.multiSelect = false;
-    // Allow deselecting of menu options
-    this.allowDeselect = false;
-    // Select all matching options when setting value in multi-select mode
-    this.selectAllMatchingOptions = false;
 
     // Event Bindings
 
+    /**
+     * @private
+     */
+    this.handleKeyDown = this.handleKeyDown.bind(this);
+
+    /**
+     * @private
+     */
+    this.handleMouseSelect = this.handleMouseSelect.bind(this);
+
+    /**
+     * @private
+     */
+    this.handleOptionHover = this.handleOptionHover.bind(this);
+
     /**
      * @private
      */
@@ -1074,14 +394,6 @@ class AuroMenu extends AuroElement {
     return {
       ...super.properties,
 
-      /**
-       * Allows deselecting an already selected option when clicked again in single-select mode.
-       */
-      allowDeselect: {
-        type: Boolean,
-        reflect: true,
-      },
-
       /**
        * When true, the entire menu and all options are disabled.
        */
@@ -1090,20 +402,6 @@ class AuroMenu extends AuroElement {
         reflect: true
       },
 
-      /**
-       * Indicates whether the menu has a loadingIcon or loadingText to render when in a loading state.
-       */
-      hasLoadingPlaceholder: {
-        type: Boolean
-      },
-
-      /**
-       * @private
-       */
-      layout: {
-        type: String
-      },
-
       /**
        * Indent level for submenus.
        * @private
@@ -1150,60 +448,26 @@ class AuroMenu extends AuroElement {
 
       /**
        * Specifies the current active menuOption.
+       * @readonly
        */
       optionActive: {
         type: Object,
-        attribute: 'optionactive'
+        attribute: false
       },
 
       /**
-       * An array of currently selected menu options, type `HTMLElement` by default. In multi-select mode, `optionSelected` is an array of HTML elements.
+       * The currently selected menu option(s). In single-select mode this is a single `HTMLElement` (or `undefined` when nothing is selected). In multi-select mode this is an array of `HTMLElement`s.
+       * @readonly
        */
       optionSelected: {
         // Allow HTMLElement, HTMLElement[] arrays and undefined
-        type: Object
-      },
-
-      /**
-       * Available menu options.
-       * @readonly
-       */
-      options: {
-        type: Array,
-        reflect: false,
+        type: Object,
         attribute: false
       },
 
-      /**
-       * Sets the size of the menu.
-       * @type {'sm' | 'md'}
-       * @default 'sm'
-       */
-      size: {
-        type: String,
-        reflect: true
-      },
-
-      /**
-       * When true, selects all options that match the provided value/key when setting value and multiselect is enabled.
-       */
-      selectAllMatchingOptions: {
-        type: Boolean,
-        reflect: true,
-      },
-
-      /**
-       * Sets the shape of the menu.
-       * @type {'box' | 'round'}
-       * @default 'box'
-       */
-      shape: {
-        type: String,
-        reflect: true
-      },
-
       /**
        * The value of the selected option. In multi-select mode, this is a JSON stringified array of selected option values.
+       * Options marked `disabled` or `static` are not selectable by value; `hidden` options remain selectable. In single-select mode, if the value matches a non-selectable option the selection is cleared (`optionSelected` becomes `undefined`) and `auroMenu-selectValueFailure` is dispatched. In multi-select mode, non-selectable entries are dropped from the value and the remaining selectable entries are selected; `auroMenu-selectValueFailure` is dispatched only when none of the entries match a selectable option.
        */
       value: {
         type: String,
@@ -1213,48 +477,17 @@ class AuroMenu extends AuroElement {
     };
   }
 
-  static get styles() {
-    return [
-      styleCss$1,
-      colorCss$1,
-      tokensCss
-    ];
-  }
-
-  /**
-   * @readonly
-   * @returns {string} - Returns the label of the currently selected option(s).
-   */
-  get currentLabel() {
-    return this.menuService.currentLabel;
-  };
-
-  /**
-   * @readonly
-   * @returns {Array<HTMLElement>} - Returns the array of available menu options.
-   * @deprecated Use `options` property instead.
-   */
-  get items() {
-    return this.options;
-  }
-
-  /**
-   * @returns {number} - Returns the index of the currently active option.
-   */
-  get index() {
-    return this._index;
-  }
-
-  /**
-   * @param {number} value - Sets the index of the currently active option.
-   */
-  set index(value) {
-    this.menuService.setHighlightedIndex(value);
-  }
-
+  static get styles() {
+    return [
+      styleCss$1,
+      colorCss$1,
+      tokensCss
+    ];
+  }
+
   /**
    * This will register this element with the browser.
-   * @param {string} [name="auro-menu"] - The name of the element that you want to register.
+   * @param {string} [name="auro-menu"] - The name of element that you want to register to.
    *
    * @example
    * AuroMenu.register("custom-menu") // this will register this element to <custom-menu/>
@@ -1265,126 +498,116 @@ class AuroMenu extends AuroElement {
   }
 
   /**
-   * Formatted value based on `multiSelect` state.
-   * Default type is `String`, changing to `Array<String>` when `multiSelect` is true.
-   * @private
-   * @returns {String|Array<String>}
+   * @readonly
+   * @returns {Array<HTMLElement>} - Returns the array of available menu options.
    */
-  get formattedValue() {
-    return this.menuService.currentValue;
+  get options() {
+    return this.items;
   }
 
   /**
-   * Gets the current property values for the menu service.
-   * @private
-   * @returns {Object}
+   * @returns {number} - Returns the index of the currently active option.
    */
-  get propertyValues() {
-    return {
-      size: this.size,
-      shape: this.shape,
-      noCheckmark: this.nocheckmark,
-      disabled: this.disabled
-    };
+  get index() {
+    return this._index;
   }
 
   /**
-   * Provides the menu context to child components.
-   * Initializes the MenuService and subscribes to menu changes.
-   * @protected
+   * @param {number} value - Sets the index of the currently active option.
    */
-  provideContext() {
-    if (this.parentElement && this.parentElement.closest('auro-menu, [auro-menu]')) {
-      this.rootMenu = false;
-      this.menuService = this.parentElement.menuService;
-      this._contextProvider = this.parentElement._contextProvider;
-      return;
-    }
-
-    this.menuService = new MenuService({host: this});
-    this.menuService.setProperties(this.propertyValues);
-    this.menuService.subscribe(this.handleMenuChange.bind(this));
-    this._contextProvider = new ContextProvider(this, {
-      context: MenuContext,
-      initialValue: this.menuService
-    });
+  set index(value) {
+    this.updateActiveOption(value);
   }
 
   /**
-   * Updates the currently active option in the menu.
-   * @param {HTMLElement} option - The option to set as active.
+   * Gets the currently selected options as an array.
+   * @returns {Array<HTMLElement>}
    */
-  updateActiveOption(option) {
-    this.menuService.setHighlightedOption(option);
+  get selectedOptions() {
+    if (!this.optionSelected) {
+      return [];
+    }
+    if (Array.isArray(this.optionSelected)) {
+      return this.optionSelected;
+    }
+    return [this.optionSelected];
   }
 
   /**
-   * Sets the internal value and manages update state.
-   * @param {String|Array<String>} value - The value to set.
-   * @protected
+   * Gets the first selected option, or null if none.
+   * @returns {HTMLElement|null}
    */
-  setInternalValue(value) {
-    if (this.value !== value) {
-      this.internalUpdateInProgress = true;
-      this.value = value;
-
-      setTimeout(() => {
-        this.internalUpdateInProgress = false;
-      });
-    }
+  get selectedOption() {
+    const opts = this.selectedOptions;
+    return opts.length > 0 ? opts[0] : null;
   }
 
   /**
-   * Handles changes from the menu service and updates component state.
-   * @param {Object} event - The event object from the menu service.
-   * @protected
+   * @readonly
+   * @returns {string} - Returns the label of the currently selected option(s).
    */
-  handleMenuChange(event) {
-    if (event.type === 'valueChange') {
-
-      // New option is array value or first option with fallback to undefined for empty array in all cases
-      const newOption = this.multiSelect && event.options.length ? event.options : event.options[0] || undefined;
-      const newValue = event.stringValue;
-
-      // Check if the option or value has actually changed
-      if (this.optionSelected !== newOption || this.stringValue !== newValue) {
-        this.optionSelected = newOption;
-        this.setInternalValue(newValue);
-      }
-
-      // Notify components of selection change
-      this.notifySelectionChange(event);
-    }
-
-    if (event.type === 'highlightChange') {
-      this.optionActive = event.option;
-      this._index = event.index;
+  get currentLabel() {
+    if (!this.optionSelected) {
+      return '';
     }
-
-    if (event.type === 'optionsChange') {
-      this.options = event.options;
-      this.dispatchEvent(new CustomEvent('auroMenu-optionsChange', {
-        detail: {
-          options: event.options
-        }
-      }));
+    if (Array.isArray(this.optionSelected)) {
+      return this.optionSelected.map((opt) => opt.textContent).join(', ');
     }
+    return this.optionSelected.textContent || '';
   }
 
   /**
-   * Gets the currently selected options.
-   * @returns {Array<HTMLElement>}
+   * Formatted value based on `multiSelect` state.
+   * Default type is `String`, changing to `Array<String>` when `multiSelect` is true.
+   * @private
+   * @returns {String|Array<String>}
    */
-  get selectedOptions() {
-    return this.menuService ? this.menuService.selectedOptions : [];
+  get formattedValue() {
+    if (this.multiSelect) {
+      if (!this.value) {
+        return undefined;
+      }
+      // Defensive: `value` is declared as String, but consumers may assign arrays or other
+      // types programmatically. Normalize without throwing so render/update never hard-crashes.
+      if (Array.isArray(this.value)) {
+        return this.value;
+      }
+      if (typeof this.value !== 'string') {
+        return [String(this.value)];
+      }
+      if (this.value.startsWith("[")) {
+        // Malformed JSON (e.g. a literal string that happens to start with "[") falls back
+        // to a single-item array rather than throwing during render.
+        try {
+          // any valid JSON starting with `[` ALWAYS parses to an array
+          return JSON.parse(this.value);
+        } catch {
+          return [this.value];
+        }
+      }
+      return [this.value];
+    }
+    return this.value;
   }
 
   /**
-   * Gets the first selected option, or null if none.
-   * @returns {HTMLElement|null}
+   * Selects options by value. Options marked `disabled` or `static` are not selectable; `hidden` options remain selectable. In single-select mode, if the value matches a non-selectable option the selection is cleared and `auroMenu-selectValueFailure` is dispatched. In multi-select mode, non-selectable entries are dropped and the remaining selectable entries are selected; `auroMenu-selectValueFailure` is dispatched only when none of the entries match a selectable option. Passing `undefined`, `null`, an empty string, or an empty array clears the selection without dispatching a failure.
+   * @param {string|string[]|undefined|null} value - The value(s) to select.
+   * @public
    */
-  get selectedOption() {
-    return this.menuService ? this.menuService.selectedOptions[0] : null;
+  selectByValue(value) {
+    const isEmpty = value === undefined ||
+      value === null ||
+      (Array.isArray(value) && value.length === 0) ||
+      (typeof value === 'string' && value.trim() === '');
+
+    if (isEmpty) {
+      this.clearSelection();
+      return;
+    }
+
+    // `value` is a String property; stringify arrays so attribute reflection and `formattedValue` parsing stay correct.
+    this.value = Array.isArray(value) ? JSON.stringify(value) : value;
   }
 
   // Lifecycle Methods
@@ -1392,9 +615,7 @@ class AuroMenu extends AuroElement {
   connectedCallback() {
     super.connectedCallback();
 
-    this.provideContext();
-
-    // this.addEventListener('keydown', this.handleKeyDown);
+    this.addEventListener('keydown', this.handleKeyDown);
     this.addEventListener('auroMenuOption-click', this.handleMouseSelect);
     this.addEventListener('auroMenuOption-mouseover', this.handleOptionHover);
     this.addEventListener('slotchange', this.handleSlotChange);
@@ -1402,7 +623,7 @@ class AuroMenu extends AuroElement {
   }
 
   disconnectedCallback() {
-    // this.removeEventListener('keydown', this.handleKeyDown);
+    this.removeEventListener('keydown', this.handleKeyDown);
     this.removeEventListener('auroMenuOption-click', this.handleMouseSelect);
     this.removeEventListener('auroMenuOption-mouseover', this.handleOptionHover);
     this.removeEventListener('slotchange', this.handleSlotChange);
@@ -1417,25 +638,140 @@ class AuroMenu extends AuroElement {
     this.initializeMenu();
   }
 
+  /**
+   * Sets an attribute that matches the default tag name if the tag name is not the default.
+   * @param {string} tagName - The tag name to set as an attribute.
+   * @private
+   */
+  setTagAttribute(tagName) {
+    if (this.tagName.toLowerCase() !== tagName) {
+      this.setAttribute(tagName, true);
+    }
+  }
 
+  // eslint-disable-next-line complexity
   updated(changedProperties) {
     super.updated(changedProperties);
 
-    // 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);
+    // Single source of truth for 'auroMenu-selectedOption'. Selection handlers
+    // mutate optionSelected and let Lit's update cycle dispatch here; the prior
+    // .value comparison missed multi-select array changes and combined with the
+    // explicit calls in handleDeselectState/makeSelection produced 2-3 duplicate
+    // events per selection.
+    if (changedProperties.has('optionSelected')) {
+      this.notifySelectionChange();
     }
 
-    // Handle loading state changes
-    if (changedProperties.has('loading')) {
-      this.setLoadingState(this.loading);
+    // Reset selection if multiSelect mode changes
+    if (changedProperties.has('multiSelect') && !changedProperties.has("value")) {
+      this.clearSelection();
+    }
+
+    if (changedProperties.has("value")) {
+      // Ensure items are populated before matching. `firstUpdated` normally initializes them,
+      // but a `value` change can arrive before slotted options are appended (e.g. parent sets
+      // value before children render). Without this guard, matching against an empty `items`
+      // would falsely dispatch `auroMenu-selectValueFailure` for valid initial values.
+      if (!this.items) {
+        this.initItems();
+      }
+
+      // Set when reconciliation reassigns `value` below. That reassignment schedules a
+      // second updated() cycle, so the `event`-attribute dispatch is deferred to that
+      // cycle to avoid firing option custom events twice on the same selection.
+      let valueReconciled = false;
+
+      // Handle null/undefined/empty case — empty/whitespace strings clear selection
+      // consistently with selectByValue(''), and avoid downstream `.includes('')` matches.
+      if (this.value === undefined || this.value === null || (typeof this.value === 'string' && this.value.trim() === '')) {
+        this.clearSelection();
+      } else {
+        let newSelected = null;
+
+        if (this.multiSelect) {
+          // In multiselect mode, this.value should be an array of strings.
+          // Defensive default: `formattedValue` can be undefined for unexpected value types,
+          // and calling `.includes` on undefined would throw during reconciliation.
+          const valueArray = this.formattedValue || [];
+          const matchingOptions = this.items ? this.items.filter((item) => isSelectableByValue(item) && valueArray.includes(item.value)) : [];
+          newSelected = matchingOptions.length > 0 ? matchingOptions : undefined;
+
+          // Reconcile `value` with the selectable set. Drop only entries whose option is
+          // loaded but non-selectable (disabled/static) — leaving them would desync `value`
+          // from `optionSelected`, and the toggle handlers rebuild `value` from `formattedValue`,
+          // so the rejected entry would resurface on the next select/deselect. Entries with no
+          // matching item yet are preserved so async preselection still works once options render.
+          const rejectedValues = this.items
+            ? this.items.filter((item) => !isSelectableByValue(item) && valueArray.includes(item.value)).map((item) => item.value)
+            : [];
+          if (rejectedValues.length > 0) {
+            const reconciled = valueArray.filter((val) => !rejectedValues.includes(val));
+            this.value = serializeMultiSelectValue(reconciled);
+            valueReconciled = true;
+          }
+        } else {
+          // In single-select mode, this.value should be a string. Reject
+          // disabled/static options so a programmatic value pointing at a
+          // non-selectable option falls through to the no-match path below
+          // (dispatching auroMenu-selectValueFailure) instead of pinning it.
+          // `hidden` is intentionally NOT excluded: the combobox toggles
+          // `hidden` as its type-ahead filter, so a filtered-out option is
+          // still a valid programmatic selection.
+          const matchingOption = this.items ? this.items.find((item) => isSelectableByValue(item) && item.value === this.value) : undefined;
+
+          if (matchingOption) {
+            newSelected = matchingOption;
+            this._index = this.items.indexOf(matchingOption);
+          } else {
+            // If no matching option found, reset selection
+            newSelected = undefined;
+            this._index = -1;
+          }
+        }
+
+        // If no matching options were found in either mode
+        if (!newSelected || (Array.isArray(newSelected) && newSelected.length === 0)) {
+          // Defer failure when no options are loaded yet (async pattern: parent sets
+          // value before slotted options render). handleSlotChange re-runs matching
+          // once items arrive. Without this guard, a valid preselected value gets
+          // cleared by the failure listener before options ever exist to match against.
+          const hasItemsToMatch = this.items && this.items.length > 0;
+          if (hasItemsToMatch) {
+            // Clear state BEFORE dispatching so synchronous listeners (e.g. auro-select's
+            // updateDisplayedValue) read fresh `optionSelected` rather than the stale prior
+            // selection and re-render the old label.
+            if (this.optionSelected !== undefined) {
+              this.optionSelected = undefined;
+            }
+            this._index = -1;
+            dispatchMenuEvent(this, 'auroMenu-selectValueFailure');
+          }
+        } else if (!this.selectionEquals(this.optionSelected, newSelected)) {
+          this.optionSelected = newSelected;
+        }
+      }
+
+      // Update UI state
+      this.updateItemsState(new Map([
+        [
+          'optionSelected',
+          true
+        ]
+      ]));
+
+      // Notify of changes. Skip when reconciliation just reassigned `value`: the
+      // follow-on update cycle re-runs this branch and fires the events exactly once.
+      if (this.optionSelected !== undefined && !valueReconciled) {
+        const selected = Array.isArray(this.optionSelected) ? this.optionSelected : [this.optionSelected];
+        selected.forEach((opt) => {
+          if (opt.hasAttribute('event')) {
+            this.handleCustomEvent(opt);
+          }
+        });
+      }
     }
 
+    // Process all other UI updates
     if (changedProperties.has('multiSelect') && this.rootMenu) {
       if (this.multiSelect) {
         this.setAttribute('aria-multiselectable', 'true');
@@ -1443,30 +779,129 @@ class AuroMenu extends AuroElement {
         this.removeAttribute('aria-multiselectable');
       }
     }
+
+    this.updateItemsState(changedProperties);
   }
 
   /**
-   * Sets an attribute that matches the default tag name if the tag name is not the default.
-   * @param {string} tagName - The tag name to set as an attribute.
+   * Updates the UI state and appearance of menu items based on changed properties.
    * @private
+   * @param {Map<string, boolean>} changedProperties - LitElement's changed properties map.
    */
-  setTagAttribute(tagName) {
-    if (this.tagName.toLowerCase() !== tagName) {
-      this.setAttribute(tagName, true);
+  updateItemsState(changedProperties) {
+    // Handle loading state changes
+    if (changedProperties.has('loading')) {
+      this.setAttribute("aria-busy", this.loading);
+      dispatchMenuEvent(this, "auroMenu-loadingChange", {
+        loading: this.loading,
+        hasLoadingPlaceholder: this.hasLoadingPlaceholder
+      });
     }
-  }
 
-  /**
-   * Sets the loading state and dispatches a loading change event.
-   * @param {boolean} isLoading - Whether the menu is loading.
-   * @protected
-   */
-  setLoadingState(isLoading) {
-    this.setAttribute("aria-busy", isLoading);
-    dispatchMenuEvent(this, "auroMenu-loadingChange", {
-      loading: isLoading,
-      hasLoadingPlaceholder: this.hasLoadingPlaceholder
+    if (!this.items) {
+      return;
+    }
+
+    // Handle noCheckmark propagation to all menus and options.
+    // Propagate in both directions so toggling back to false also clears nested elements
+    // (otherwise nested menus/options would stay stuck in no-checkmark mode).
+    if (changedProperties.has('noCheckmark')) {
+      this.querySelectorAll('auro-menu, [auro-menu], auro-menuoption, [auro-menuoption]').forEach((element) => {
+        element.noCheckmark = this.noCheckmark;
+      });
+    }
+
+    // Handle layout propagation to all menus and options.
+    // Skip elements that had size/shape set by the author (marked in initItems);
+    // explicit per-option overrides must survive menu-level propagation.
+    const propagationTargets = this.querySelectorAll('auro-menu, [auro-menu], auro-menuoption, [auro-menuoption]');
+    [
+      'size',
+      'shape'
+    ].forEach((prop) => {
+      if (changedProperties.has(prop)) {
+        const explicitKey = prop === 'size' ? '_explicitSize' : '_explicitShape';
+        propagationTargets.forEach((el) => {
+          if (el[explicitKey]) {
+            return;
+          }
+          el.setAttribute(prop, this[prop]);
+        });
+      }
+    });
+
+    // Regex for matchWord if needed
+    let regexWord = null;
+
+    if (changedProperties.has('matchWord') && this.matchWord && this.matchWord.length) {
+      const escapedWord = this.matchWord.replace(/[.*+?^${}()|[\]\\]/gu, '\\$&');
+      regexWord = new RegExp(escapedWord, 'giu');
+    }
+
+    // Handle direct item updates
+    this.items.forEach((option) => {
+      // Update selection if option or value changed
+      if (changedProperties.has('optionSelected') || changedProperties.has('value')) {
+        const isSelected = this.isOptionSelected(option);
+        option.setAttribute('aria-selected', isSelected ? 'true' : 'false');
+
+        // Add/remove selected attribute based on state
+        if (isSelected) {
+          option.setAttribute('selected', '');
+        } else {
+          option.removeAttribute('selected');
+        }
+      }
+
+      // Update text highlighting if matchWord changed
+      if (changedProperties.has('matchWord') && regexWord &&
+          isOptionInteractive(option) && !option.hasAttribute('persistent')) {
+        // Create nested spacers
+        const nested = option.querySelectorAll('.nestingSpacer');
+
+        const displayValueEl = option.querySelector('[slot="displayValue"]');
+        if (displayValueEl) {
+          option.removeChild(displayValueEl);
+        }
+
+        // Build highlighted content via DOM APIs rather than innerHTML so any
+        // `<`, `>`, or `&` in the option text renders literally (prevents XSS).
+        const originalText = option.textContent;
+        option.textContent = '';
+
+        nested.forEach(() => {
+          const spacer = document.createElement('span');
+          spacer.className = 'nestingSpacer';
+          option.appendChild(spacer);
+        });
+
+        const matches = [...originalText.matchAll(regexWord)];
+        let lastIndex = 0;
+        matches.forEach((match) => {
+          const [matchText] = match;
+          if (match.index > lastIndex) {
+            option.appendChild(document.createTextNode(originalText.slice(lastIndex, match.index)));
+          }
+          const strong = document.createElement('strong');
+          strong.textContent = matchText;
+          option.appendChild(strong);
+          lastIndex = match.index + matchText.length;
+        });
+        if (lastIndex < originalText.length) {
+          option.appendChild(document.createTextNode(originalText.slice(lastIndex)));
+        }
+
+        if (displayValueEl) {
+          option.append(displayValueEl);
+        }
+      }
+
+      // Update disabled state
+      if (changedProperties.has('disabled')) {
+        option.disabled = this.disabled;
+      }
     });
+
   }
 
   // Init Methods
@@ -1476,6 +911,7 @@ class AuroMenu extends AuroElement {
    * @private
    */
   initializeMenu() {
+    this.initItems();
     if (this.rootMenu) {
       this.setAttribute('role', 'listbox');
       this.setAttribute('root', '');
@@ -1485,15 +921,111 @@ class AuroMenu extends AuroElement {
       }
     }
 
+    // Must run for nested menus too — sets level, role="group", and aria-label="submenu" based on parent.
     this.handleNestedMenus(this);
   }
 
   /**
-   * Selects the currently highlighted option.
-   * @protected
+   * Initializes menu items and their attributes.
+   * @private
    */
-  makeSelection() {
-    this.menuService.selectHighlightedOption();
+  initItems() {
+    const found = Array.from(this.querySelectorAll('auro-menuoption, [auro-menuoption]'));
+    this.items = found.length > 0 ? found : undefined;
+
+    // Record whether each propagation target had an author-set size/shape attribute
+    // BEFORE menu has had a chance to propagate. Marker is set once per element so a
+    // later menu-driven setAttribute doesn't re-flag the element as "explicit".
+    this.querySelectorAll('auro-menu, [auro-menu], auro-menuoption, [auro-menuoption]').forEach((el) => {
+      if (el._explicitSize === undefined) {
+        el._explicitSize = el.hasAttribute('size');
+      }
+      if (el._explicitShape === undefined) {
+        el._explicitShape = el.hasAttribute('shape');
+      }
+    });
+
+    if (this.noCheckmark) {
+      this.updateItemsState(new Map([
+        [
+          'noCheckmark',
+          true
+        ]
+      ]));
+    }
+
+    this.dispatchEvent(new CustomEvent('auroMenu-optionsChange', {
+      detail: {
+        options: this.items
+      }
+    }));
+  }
+
+  // Logic Methods
+
+  /**
+   * Updates menu state when an option is selected.
+   * @private
+   * @param {HTMLElement} option - The option element to select.
+   */
+  handleSelectState(option) {
+    if (this.multiSelect) {
+      const currentValue = this.formattedValue || [];
+      const currentSelected = this.optionSelected || [];
+
+      if (!currentValue.includes(option.value)) {
+        this.value = serializeMultiSelectValue([
+          ...currentValue,
+          option.value
+        ]);
+      }
+      if (!currentSelected.includes(option)) {
+        this.optionSelected = [
+          ...currentSelected,
+          option
+        ];
+      }
+    } else {
+      this.value = option.value;
+      this.optionSelected = option;
+    }
+
+    this._index = this.items.indexOf(option);
+  }
+
+  /**
+   * Deselects a menu option and updates related state.
+   * @private
+   * @param {HTMLElement} option - The menuoption to be deselected.
+   */
+  handleDeselectState(option) {
+    if (this.multiSelect) {
+      // Remove this option from array; an empty result collapses `value` to undefined.
+      const newFormattedValue = (this.formattedValue || []).filter((val) => val !== option.value);
+      this.value = serializeMultiSelectValue(newFormattedValue);
+
+      this.optionSelected = this.optionSelected.filter((val) => val !== option);
+      if (this.optionSelected.length === 0) {
+        this.optionSelected = undefined;
+      }
+    } else {
+      // For single-select: Back to undefined when deselected
+      this.value = undefined;
+      this.optionSelected = undefined;
+    }
+
+    // Update the index tracking
+    this._index = this.items.indexOf(option);
+
+    // Update UI to reflect changes
+    this.updateItemsState(new Map([
+      [
+        'optionSelected',
+        true
+      ]
+    ]));
+
+    // Notification happens via updated() when optionSelected changes above.
   }
 
   /**
@@ -1512,7 +1044,23 @@ class AuroMenu extends AuroElement {
    * @public
    */
   reset() {
-    this.menuService.reset();
+    // Reset to undefined - initial state
+    this.value = undefined;
+    this.optionSelected = undefined;
+    this._index = -1;
+
+    // Clear active option state so a follow-up open/navigation starts fresh
+    // rather than reusing a stale reference from before the reset.
+    this.items?.forEach((item) => item.classList.remove('active'));
+    this.optionActive = undefined;
+
+    // Reset UI state
+    this.updateItemsState(new Map([
+      [
+        'optionSelected',
+        true
+      ]
+    ]));
 
     // Dispatch reset event
     dispatchMenuEvent(this, 'auroMenu-selectValueReset');
@@ -1524,6 +1072,14 @@ class AuroMenu extends AuroElement {
    * @param {HTMLElement} menu - Root menu element.
    */
   handleNestedMenus(menu) {
+    // Slot changes can fire on a menu mid-teardown (e.g. while a parent menu
+    // is removing children to rebuild its content). In that window the menu
+    // is detached and parentElement is null. Skip — handleNestedMenus will
+    // run again when the menu is reattached.
+    if (!menu.parentElement) {
+      return;
+    }
+
     menu.level = menu.parentElement.level >= 0 ? menu.parentElement.level + 1 : 0;
 
     if (menu.level > 0) {
@@ -1534,34 +1090,221 @@ class AuroMenu extends AuroElement {
       }
     }
 
-    const options = menu.querySelectorAll(':scope > auro-menuoption, :scope > [auro-menuoption]');
-    options.forEach((option) => {
-      const regex = new RegExp(this.nestingSpacer, "gu");
-      option.innerHTML = this.nestingSpacer.repeat(menu.level) + option.innerHTML.replace(regex, '');
-    });
+    const options = menu.querySelectorAll(':scope > auro-menuoption, :scope > [auro-menuoption]');
+    options.forEach((option) => {
+      const regex = new RegExp(this.nestingSpacer, "gu");
+      option.innerHTML = this.nestingSpacer.repeat(menu.level) + option.innerHTML.replace(regex, '');
+    });
+  }
+
+  // Event Handlers
+
+  /**
+   * Makes a selection based on the current index.
+   * @private
+   */
+  makeSelection() {
+    if (!this.items) {
+      this.initItems();
+    }
+
+    // Get currently selected menu option based on index
+    const option = this.items ? this.items[this._index] : undefined;
+
+    // Return early if option is not interactive
+    if (!option || !isOptionInteractive(option)) {
+      return;
+    }
+
+    // Handle custom events first
+    if (option.hasAttribute('event')) {
+      this.handleCustomEvent(option);
+      return;
+    }
+
+    if (this.multiSelect) {
+      // In multiselect, toggle individual selections
+      this.toggleOption(option);
+      // In single select, only handle selection of new options
+    } else if (!this.isOptionSelected(option)) {
+      this.clearSelection();
+      this.handleSelectState(option);
+    } else {
+      // Re-selecting the already-selected option in single-select doesn't change
+      // state, so updated() won't fire. Notify explicitly so consumers (e.g.
+      // auro-select closing its dropdown on Enter) still get the event.
+      this.notifySelectionChange();
+    }
+  }
+
+  /**
+   * Toggle the selection state of the menuoption.
+   * @private
+   * @param {HTMLElement} option - The menuoption to toggle.
+   */
+  toggleOption(option) {
+    const isCurrentlySelected = this.isOptionSelected(option);
+
+    if (isCurrentlySelected) {
+      this.handleDeselectState(option);
+    } else if (option.value === undefined || option.value === '') {
+      dispatchMenuEvent(this, 'auroMenu-selectValueFailure');
+    } else {
+      this.handleSelectState(option);
+    }
+  }
+
+  /**
+   * Handles keyboard navigation and selection.
+   * @private
+   * @param {KeyboardEvent} event - The keydown event.
+   */
+  handleKeyDown(event) {
+    switch (event.key) {
+      case "ArrowDown":
+        event.preventDefault();
+        this.navigateOptions('down');
+        break;
+      case "ArrowUp":
+        event.preventDefault();
+        this.navigateOptions('up');
+        break;
+      case "Tab":
+        // Do not preventDefault on Tab so focus can move out of the menu (a11y: avoid trapping keyboard users).
+        this.makeSelection();
+        break;
+      case "Enter":
+        event.preventDefault();
+        this.makeSelection();
+        break;
+    }
+  }
+
+  /**
+   * Handles option selection via click events from menuoptions.
+   * @private
+   * @param {CustomEvent} event - The auroMenuOption-click event.
+   */
+  handleMouseSelect(event) {
+    if (!this.rootMenu || this.disabled) {
+      return;
+    }
+
+    const option = event.detail;
+    if (option && this.items) {
+      const idx = this.items.indexOf(option);
+      if (idx >= 0) {
+        this._index = idx;
+        this.makeSelection();
+      }
+    }
+  }
+
+  /**
+   * Handles option hover events.
+   * @private
+   * @param {CustomEvent} event - Event object from the browser.
+   */
+  handleOptionHover(event) {
+    const option = event.detail;
+    if (this.items) {
+      const idx = this.items.indexOf(option);
+      if (idx >= 0) {
+        this.updateActiveOption(idx);
+      }
+    }
+  }
+
+  /**
+   * Handles slot change events.
+   * @private
+   */
+  handleSlotChange() {
+    if (this.parentElement && this.parentElement.closest('auro-menu, [auro-menu]')) {
+      this.rootMenu = false;
+    }
+
+    // Nested menus must also reinitialize so items, level, role="group", and aria-label refresh on content changes.
+    // Root-specific attributes (listbox/root/aria-multiselectable) remain gated by `rootMenu` inside initializeMenu.
+    this.initializeMenu();
+
+    // When options arrive after `value` was set (async option load), re-run matching
+    // against the now-populated items. The earlier updated('value') call deferred
+    // the failure dispatch because items were empty; this triggers the match now.
+    const hasPendingValue = this.value !== undefined &&
+      this.value !== null &&
+      !(typeof this.value === 'string' && this.value.trim() === '');
+    if (hasPendingValue && this.items && this.items.length > 0 && this.optionSelected === undefined) {
+      this.requestUpdate('value', undefined);
+    }
   }
 
   /**
-   * Navigates the menu options in the specified direction.
-   * @param {'up'|'down'} direction - The direction to navigate.
-   * @protected
+   * Navigates through options using keyboard.
+   * @param {string} direction - 'up' or 'down'.
    */
   navigateOptions(direction) {
-    if (direction === 'up') {
-      this.menuService.highlightPrevious();
-    } else if (direction === 'down') {
-      this.menuService.highlightNext();
+    // Return early if no items exist
+    if (!this.items || !this.items.length) {
+      return;
+    }
+
+    let newIndex = this._index;
+    if (newIndex === -1 && direction === 'up') {
+      newIndex = this.items.length;
+    }
+    const increment = direction === 'down' ? 1 : -1;
+    const maxIterations = this.items.length;
+    let iterations = 0;
+    let foundInteractiveOption = false;
+
+    do {
+      newIndex = (newIndex + increment + this.items.length) % this.items.length;
+      iterations += 1;
+
+      // Check if current option is interactive
+      const currentOption = this.items[newIndex];
+      if (isOptionInteractive(currentOption)) {
+        foundInteractiveOption = true;
+        break;
+      }
+
+      // Break if all options were checked
+      if (iterations >= maxIterations) {
+        break;
+      }
+    } while (iterations < maxIterations);
+
+    // Update only if an interactive option was found
+    if (foundInteractiveOption) {
+      this.updateActiveOption(newIndex);
     }
   }
 
   /**
-   * Handles slot change events.
-   * @private
+   * Updates the active option state and dispatches events.
+   * Accepts either a numeric index or an HTMLElement option.
+   * @param {number|HTMLElement} indexOrOption - Index of the option or the option element to make active.
    */
-  handleSlotChange() {
-    if (this.rootMenu) {
-      this.initializeMenu();
+  updateActiveOption(indexOrOption) {
+    let idx = -1;
+
+    if (typeof indexOrOption === 'number') {
+      idx = indexOrOption;
+    } else {
+      idx = this.items ? this.items.indexOf(indexOrOption) : -1;
     }
+
+    if (!this.items || !this.items[idx]) {
+      return;
+    }
+
+    this.items.forEach((item) => item.classList.remove('active'));
+    this.items[idx].classList.add('active');
+    this.optionActive = this.items[idx];
+    this._index = idx;
+
+    dispatchMenuEvent(this, 'auroMenu-activatedOption', this.items[idx]);
   }
 
   /**
@@ -1571,8 +1314,8 @@ class AuroMenu extends AuroElement {
    */
   handleCustomEvent(option) {
     const eventName = option.getAttribute('event');
-    dispatchMenuEvent(this, eventName);
-    dispatchMenuEvent(this, 'auroMenu-customEventFired');
+    dispatchMenuEvent(this, eventName, { option });
+    dispatchMenuEvent(this, 'auroMenu-customEventFired', { option });
   }
 
   /**
@@ -1580,14 +1323,33 @@ class AuroMenu extends AuroElement {
    * @param {any} source - The source that triggers this event.
    * @private
    */
-  notifySelectionChange({value, stringValue, keys, options, reason} = {}) {
-    dispatchMenuEvent(this, 'auroMenu-selectedOption', {
-      value,
-      stringValue,
-      keys,
-      options,
-      reason
-    });
+  notifySelectionChange(source = undefined) {
+    dispatchMenuEvent(this, 'auroMenu-selectedOption', { source });
+  }
+
+  /**
+   * @private
+   * @param {any} current - Current selection.
+   * @param {any} next - New selection to compare.
+   * @returns {boolean} Whether the selections are equal.
+   */
+  selectionEquals(current, next) {
+    if (current === next) {
+      return true;
+    }
+    if (!current || !next) {
+      return false;
+    }
+    if (Array.isArray(current) && Array.isArray(next)) {
+      if (current.length !== next.length) {
+        return false;
+      }
+      // Compare as sets — selection order may differ from DOM order after value-driven
+      // reconciliation, but the selected set is what matters for change detection.
+      const nextSet = new Set(next);
+      return current.every((item) => nextSet.has(item));
+    }
+    return false;
   }
 
   /**
@@ -1602,7 +1364,6 @@ class AuroMenu extends AuroElement {
     }
 
     if (this.multiSelect) {
-      // In multi-select mode, check if the option is in the selected array
       return Array.isArray(this.optionSelected) && this.optionSelected.some((selectedOption) => selectedOption === option);
     }
 
@@ -1742,40 +1503,16 @@ let menuOptionIdCounter = 0;
  * The `auro-menuoption` element provides users a way to define a menu option.
  * @customElement auro-menuoption
  *
+ * @attr {Boolean} static - When present, marks the option as non-interactive — it renders but is skipped during keyboard navigation and cannot be selected. Useful for section headers, informational rows inside a menu, or attaching event listeners.
  * @slot default - The default slot for the menu option text.
  *
  * @event auroMenuOption-mouseover - Notifies that this option has been hovered over.
+ * @event auroMenuOption-click - Notifies that this option has been clicked.
  */
 class AuroMenuOption extends AuroElement {
-
-  /**
-   * This will register this element with the browser.
-   * @param {string} [name="auro-menuoption"] - The name of the element that you want to register.
-   *
-   * @example
-   * AuroMenuOption.register("custom-menuoption") // this will register this element to <custom-menuoption/>
-   *
-   */
-  static register(name = "auro-menuoption") {
-    AuroLibraryRuntimeUtils.prototype.registerComponent(name, AuroMenuOption);
-  }
-
-  /**
-   * Returns whether the menu option is currently active and selectable.
-   * An option is considered active if it is not hidden, not disabled, and not static.
-   * @returns {boolean} True if the option is active, false otherwise.
-   */
-  get isActive() {
-    return !this.hasAttribute('hidden') &&
-      !this.disabled &&
-      !this.hasAttribute('static');
-  }
-
   constructor() {
     super();
 
-    this.bindEvents();
-
     /**
      * @private
      */
@@ -1796,83 +1533,62 @@ class AuroMenuOption extends AuroElement {
     this.noCheckmark = false;
     this.disabled = false;
     this.noMatch = false;
+    this.persistent = false;
 
     /**
      * @private
      */
-    this.runtimeUtils = new AuroLibraryRuntimeUtils();
-
-    // Initialize context-related properties
-    this.menuService = null;
-    this.unsubscribe = null;
+    this.tabIndex = -1;
 
     /**
      * @private
      */
-    this.handleMenuChange = this.handleMenuChange.bind(this);
+    this.runtimeUtils = new AuroLibraryRuntimeUtils();
+
+    this.addEventListener('click', this.handleClick.bind(this));
   }
 
   static get properties() {
     return {
       ...super.properties,
-
-      /**
-       * When true, disables the menu option.
-       */
-      disabled: {
+      noCheckmark: {
         type: Boolean,
         reflect: true
       },
 
       /**
-       * @private
+       * **Deprecated.** Use the `value` attribute on `auro-menu` to set the selected option when the menu renders (or call `menu.selectByValue(value)` programmatically). Support for the child-level `selected` attribute will be removed in a future major release.
+       *
+       * @deprecated Use the `value` attribute on `auro-menu` instead.
        */
-      event: {
-        type: String,
+      selected: {
+        type: Boolean,
         reflect: true
       },
-
-      /**
-       * @private
-       */
-      layout: {
-        type: String
+      disabled: {
+        type: Boolean,
+        reflect: true
       },
-
-      /**
-       * Allows users to set a unique key for the menu option for specified option selection. If no key is provided, the value property will be used.
-       */
-      key: {
+      value: {
         type: String,
         reflect: true
       },
-
-      /**
-       * @private
-       */
-      menuService: {
-        type: Object,
-        state: true
+      tabIndex: {
+        type: Number,
+        reflect: true
       },
 
       /**
        * @private
        */
-      matchWord: {
+      event: {
         type: String,
-        state: true
-      },
-
-      /**
-       * @private
-       */
-      noCheckmark: {
-        type: Boolean,
         reflect: true
       },
 
       /**
-       * When true, marks this option as the "no matching results" placeholder shown by combobox when the user's input does not match any available options. Enables distinct styling and prevents the option from being treated as a selectable match.
+       * When true, marks this option as the "no matching results" placeholder shown by combobox
+       * when the user's input does not match any available options.
        */
       noMatch: {
         type: Boolean,
@@ -1880,29 +1596,11 @@ class AuroMenuOption extends AuroElement {
         attribute: 'nomatch'
       },
 
-      /**
-       * Specifies that an option is selected.
-       */
-      selected: {
+      /** When true, this option is excluded from `matchWord` DOM rewriting — useful for utility rows (e.g., "Add new…") that must render identically regardless of the current filter. */
+      persistent: {
         type: Boolean,
         reflect: true
       },
-
-      /**
-       * Specifies the tab index of the menu option.
-       */
-      tabIndex: {
-        type: Number,
-        reflect: true
-      },
-
-      /**
-       * Specifies the value to be sent to a server.
-       */
-      value: {
-        type: String,
-        reflect: true
-      },
     };
   }
 
@@ -1914,41 +1612,48 @@ class AuroMenuOption extends AuroElement {
     ];
   }
 
+  /**
+   * This will register this element with the browser.
+   * @param {string} [name="auro-menuoption"] - The name of element that you want to register to.
+   *
+   * @example
+   * AuroMenuOption.register("custom-menuoption") // this will register this element to <custom-menuoption/>
+   *
+   */
+  static register(name = "auro-menuoption") {
+    AuroLibraryRuntimeUtils.prototype.registerComponent(name, AuroMenuOption);
+  }
+
+  /**
+   * Returns whether the menu option is currently active and selectable.
+   * @returns {boolean}
+   */
+  get isActive() {
+    return !this.hasAttribute('hidden') &&
+      !this.disabled &&
+      !this.hasAttribute('static');
+  }
+
   connectedCallback() {
     super.connectedCallback();
 
-    // Add the tag name as an attribute if it is different than the component name
-    // Add this step soon as this node gets attached to the DOM to avoid racing condition with menu's value setting logic.
     this.runtimeUtils.handleComponentTagRename(this, 'auro-menuoption');
-
-    // Set up context consumption in connectedCallback
-    this._contextConsumer = new ContextConsumer(this, {
-      context: MenuContext,
-      callback: this.attachTo.bind(this),
-      subscribe: true
-    });
-
-    // 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');
-    const resolvedKey = keyAttr !== null ? keyAttr : valueAttr;
-    if (resolvedKey !== null) {
-      this.key = resolvedKey;
-    }
   }
 
   firstUpdated() {
-    // Add the tag name as an attribute if it is different than the component name
     this.runtimeUtils.handleComponentTagRename(this, 'auro-menuoption');
 
-    // Generate unique ID if not already set (required for aria-activedescendant)
+    // firstUpdated can fire on an option that was detached before the first
+    // render completed (e.g. dynamic-menu rebuilds clear and repopulate the
+    // menu mid-cycle). parentElement is null in that case — fall back to
+    // defaults; the next render after re-attachment will pick up real values.
+    if (!this.hasAttribute('size')) {
+      this.size = this.parentElement ? this.parentElement.getAttribute('size') || 'sm' : 'sm';
+    }
+    if (!this.hasAttribute('shape')) {
+      this.shape = this.parentElement ? this.parentElement.getAttribute('shape') || 'box' : 'box';
+    }
+
     if (!this.id) {
       menuOptionIdCounter += 1;
       this.id = `menuoption-${menuOptionIdCounter}`;
@@ -1970,16 +1675,8 @@ class AuroMenuOption extends AuroElement {
   updated(changedProperties) {
     super.updated(changedProperties);
 
-    // Update aria-selected attribute if selected changed
     if (changedProperties.has('selected')) {
-
-      // Update aria-selected attribute
       this.setAttribute('aria-selected', this.selected.toString());
-
-      // Update menu service selection state if this isn't an internal update
-      if (this.internalUpdateInProgress !== true && this.menuService) {
-        this.menuService[this.selected ? 'selectOption' : 'deselectOption'](this);
-      }
     }
 
     if (changedProperties.has('disabled')) {
@@ -1989,231 +1686,48 @@ class AuroMenuOption extends AuroElement {
         this.removeAttribute('aria-disabled');
       }
     }
-
-    if (changedProperties.has('active')) {
-      this.updateActiveClasses();
-    }
-
-    // Update text highlight if matchWord changed
-    if (changedProperties.has('matchWord')) {
-      this.updateTextHighlight();
-    }
-
-    // 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;
-    }
-  }
-
-  disconnectedCallback() {
-    if (this.menuService) {
-      this.menuService.unsubscribe(this.handleMenuChange);
-      this.menuService.removeMenuOption(this);
-    }
-  }
-
-  /**
-   * Sets up event listeners for user interaction with the menu option.
-   * This function enables click and mouse enter events to trigger selection and highlighting logic.
-   */
-  bindEvents() {
-    this.addEventListener('click', this.handleClick.bind(this));
-    this.addEventListener('mouseenter', this.handleMouseEnter.bind(this));
   }
 
-  /**
-   * Attaches this menu option to a menu service and subscribes to its events.
-   * This method enables the option to participate in menu selection and highlighting logic.
-   * @param {Object} service - The menu service instance to attach to.
-   */
-  attachTo(service) {
-    if (!service) {
-      return;
-    }
-    this.menuService = service;
-    this.menuService.addMenuOption(this);
-    this.menuService.subscribe(this.handleMenuChange);
+  handleMenuChange() {
+    // no-op: menu owns state in the distributed architecture
   }
 
-  /**
-   * Handles changes from the menu service and updates the option's state.
-   * This function synchronizes the option's properties and selection/highlight state with menu events.
-   * @param {Object} event - The event object from the menu service.
-   */
-  handleMenuChange(event) {
-
-    // Ignore events without a type or property
-    if (!event || (!event.type && !event.property)) {
-      return;
-    }
-
-    // Update reactive properties based on event type
-    if (event.property && Object.keys(AuroMenuOption.properties).includes(event.property)) {
-      this[event.property] = event.value;
-    }
-
-    // Handle highlight changes
-    if (event.type === 'highlightChange') {
-      const isActive = event.option === this;
-      this.active = isActive;
-      this.updateActiveClasses();
-    }
-
-    if (event.type === 'stateChange') {
-      const isSelected = event.selectedOptions.includes(this);
-      this.setInternalSelected(isSelected);
-    }
+  setSelected(value) {
+    this.selected = value;
   }
 
-  /**
-   * Updates the internal selected state of the menu option bypassing 'updated' and triggers custom events if selected.
-   * This function ensures the option's selection state is synchronized with menu logic and notifies listeners.
-   * @param {boolean} isSelected - Whether the option should be marked as selected.
-   */
-  setInternalSelected(isSelected) {
-    this.internalUpdateInProgress = true;
-    this.selected = isSelected;
-
-    // Fire custom event if selected
-    if (isSelected) {
-      this.handleCustomEvent();
+  updateActive(active) {
+    this.active = active;
+    if (active) {
+      this.classList.add('active');
+    } else {
+      this.classList.remove('active');
     }
-
-    setTimeout(() => {
-      this.internalUpdateInProgress = false;
-    }, 0);
-  }
-
-  /**
-   * Sets the selected state of the menu option.
-   * This function updates whether the option is currently selected.
-   * @param {boolean} isSelected - Whether the option should be marked as selected.
-   * @deprecated Simply modify the `selected` property directly instead.
-   */
-  setSelected(isSelected) {
-    this.selected = isSelected;
-  }
-
-  /**
-   * Updates the active state and visual highlighting of the menu option.
-   * This function toggles the option's active status and applies or removes the active CSS class.
-   * @param {boolean} isActive - Whether the option should be marked as active.
-   * @deprecated Simply modify the `active` property directly instead.
-   */
-  updateActive(isActive) {
-
-    // Set active state
-    this.active = isActive;
-    this.updateActiveClasses();
-  }
-
-  /**
-   * Updates the CSS class for the menu option based on its active state.
-   * This function adds or removes the 'active' class to visually indicate the option's active status.
-   * @private
-   */
-  updateActiveClasses() {
-    // Update class based on active state
-    if (this.active) this.classList.add('active');
-    else this.classList.remove('active');
   }
 
-
-  /**
-   * Updates the visual highlighting of text within the menu option based on the current match word.
-   * This function highlights matching text segments and manages nested spacers for display formatting.
-   * @private
-   */
-  updateTextHighlight() {
-
-    // Regex for matchWord if needed
-    let regexWord = null;
-
-    if (this.matchWord && this.matchWord.length) {
-      const escapedWord = this.matchWord.replace(/[.*+?^${}()|[\]\\]/gu, '\\$&');
-      regexWord = new RegExp(escapedWord, 'giu');
-    }
-
-    // Update text highlighting if matchWord changed
-    if (regexWord &&
-      this.isActive && !this.hasAttribute('persistent')) {
-      const nested = this.querySelectorAll('.nestingSpacer');
-
-      const displayValueEl = this.querySelector('[slot="displayValue"]');
-      if (displayValueEl) {
-        this.removeChild(displayValueEl);
-      }
-
-      // Create nested spacers
-      const nestingSpacerBundle = [...nested].map(() => this.nestingSpacer).join('');
-
-      // Update with spacers and matchWord
-      this.innerHTML = nestingSpacerBundle +
-        this.textContent.replace(
-          regexWord,
-          (match) => `<strong>${match}</strong>`
-        );
-      if (displayValueEl) {
-        this.append(displayValueEl);
-      }
-    }
+  attachTo() {
+    // no-op: menu owns state in the distributed architecture
   }
 
   /**
-   * Handles click events on the menu option, toggling its selected state.
-   * This function dispatches a click event and updates selection if the option is not disabled.
+   * Handles click events on the menu option.
    * @private
    */
   handleClick() {
-    if (!this.disabled && !this.menuService?.disabled) {
-      this.dispatchClickEvent();
-      this.selected = !this.selected;
-    }
-  }
-
-  /**
-   * Handles mouse enter events to highlight the menu option.
-   * This function updates the menu service to set this option as the currently highlighted item if not disabled.
-   * @private
-   */
-  handleMouseEnter() {
     if (!this.disabled) {
-      this.menuService.setHighlightedOption(this);
-    }
-  }
-
-  /**
-   * Dispatches custom events defined for this menu option.
-   * This function notifies listeners when a custom event is triggered by the option.
-   * @private
-   */
-  handleCustomEvent() {
-    if (this.event) {
-      dispatchMenuEvent(this, this.event, { option: this });
-      dispatchMenuEvent(this, 'auroMenu-customEventFired', { option: this });
+      // Pure event emitter: the parent menu owns selection state and will
+      // update `selected` via setSelected(). Toggling here desyncs the option
+      // UI from auro-menu.optionSelected (e.g. single-select re-click on the
+      // already-selected option would flip the option off while the menu keeps it on).
+      this.dispatchEvent(new CustomEvent('auroMenuOption-click', {
+        bubbles: true,
+        cancelable: false,
+        composed: true,
+        detail: this
+      }));
     }
   }
 
-  /**
-   * Dispatches a click event for this menu option.
-   * This function notifies listeners that the option has been clicked.
-   * @private
-   */
-  dispatchClickEvent() {
-    this.dispatchEvent(new CustomEvent('auroMenuOption-click', {
-      bubbles: true,
-      cancelable: false,
-      composed: true,
-      detail: this
-    }));
-  }
-
   /**
    * Generates an HTML element containing an SVG icon based on the provided `svgContent`.
    *
@@ -2253,8 +1767,8 @@ class AuroMenuOption extends AuroElement {
     return html$1`
       <div class="${classes}">
         ${this.selected && !this.noCheckmark
-        ? this.generateIconHtml(checkmarkIcon.svg)
-        : undefined}
+          ? this.generateIconHtml(checkmarkIcon.svg)
+          : undefined}
         <slot></slot>
       </div>
     `;