@aurodesignsystem-dev/auro-formkit 0.0.0-pr1498.0 → 0.0.0-pr1499.0

package/components/menu/dist/index.js

@@ -1,4 +1,5 @@
 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';
@@ -113,6 +114,720 @@ 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.
 
@@ -273,7 +988,7 @@ function dispatchMenuEvent(element, eventName, detail = null) {
   element.dispatchEvent(new CustomEvent(eventName, eventConfig));
 }
 
-/* eslint-disable no-underscore-dangle, no-magic-numbers, max-lines, no-extra-parens, max-depth */
+/* eslint-disable no-underscore-dangle */
 // Copyright (c) 2025 Alaska Airlines. All right reserved. Licensed under the Apache-2.0 license
 // See LICENSE in the project root for license information.
 
@@ -287,12 +1002,16 @@ 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() {
@@ -310,8 +1029,6 @@ 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
@@ -324,24 +1041,13 @@ 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
      */
@@ -368,6 +1074,14 @@ 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.
        */
@@ -376,6 +1090,20 @@ 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
@@ -436,6 +1164,44 @@ class AuroMenu extends AuroElement {
         type: Object
       },
 
+      /**
+       * Available menu options.
+       * @readonly
+       */
+      options: {
+        type: Array,
+        reflect: false,
+        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.
        */
@@ -456,23 +1222,20 @@ class AuroMenu extends AuroElement {
   }
 
   /**
-   * This will register this element with the browser.
-   * @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/>
-   *
+   * @readonly
+   * @returns {string} - Returns the label of the currently selected option(s).
    */
-  static register(name = "auro-menu") {
-    AuroLibraryRuntimeUtils.prototype.registerComponent(name, AuroMenu);
-  }
+  get currentLabel() {
+    return this.menuService.currentLabel;
+  };
 
   /**
    * @readonly
    * @returns {Array<HTMLElement>} - Returns the array of available menu options.
+   * @deprecated Use `options` property instead.
    */
-  get options() {
-    return this.items;
+  get items() {
+    return this.options;
   }
 
   /**
@@ -483,101 +1246,145 @@ class AuroMenu extends AuroElement {
   }
 
   /**
-   * @param {number} value - Sets the index of the currently active option.
+   * @param {number} value - Sets the index of the currently active option.
+   */
+  set index(value) {
+    this.menuService.setHighlightedIndex(value);
+  }
+
+  /**
+   * This will register this element with the browser.
+   * @param {string} [name="auro-menu"] - The name of the element that you want to register.
+   *
+   * @example
+   * AuroMenu.register("custom-menu") // this will register this element to <custom-menu/>
+   *
+   */
+  static register(name = "auro-menu") {
+    AuroLibraryRuntimeUtils.prototype.registerComponent(name, AuroMenu);
+  }
+
+  /**
+   * Formatted value based on `multiSelect` state.
+   * Default type is `String`, changing to `Array<String>` when `multiSelect` is true.
+   * @private
+   * @returns {String|Array<String>}
+   */
+  get formattedValue() {
+    return this.menuService.currentValue;
+  }
+
+  /**
+   * Gets the current property values for the menu service.
+   * @private
+   * @returns {Object}
    */
-  set index(value) {
-    this.updateActiveOption(value);
+  get propertyValues() {
+    return {
+      size: this.size,
+      shape: this.shape,
+      noCheckmark: this.nocheckmark,
+      disabled: this.disabled
+    };
   }
 
   /**
-   * Gets the currently selected options as an array.
-   * @returns {Array<HTMLElement>}
+   * Provides the menu context to child components.
+   * Initializes the MenuService and subscribes to menu changes.
+   * @protected
    */
-  get selectedOptions() {
-    if (!this.optionSelected) {
-      return [];
-    }
-    if (Array.isArray(this.optionSelected)) {
-      return this.optionSelected;
+  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;
     }
-    return [this.optionSelected];
+
+    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
+    });
   }
 
   /**
-   * Gets the first selected option, or null if none.
-   * @returns {HTMLElement|null}
+   * Updates the currently active option in the menu.
+   * @param {HTMLElement} option - The option to set as active.
    */
-  get selectedOption() {
-    const opts = this.selectedOptions;
-    return opts.length > 0 ? opts[0] : null;
+  updateActiveOption(option) {
+    this.menuService.setHighlightedOption(option);
   }
 
   /**
-   * @readonly
-   * @returns {string} - Returns the label of the currently selected option(s).
+   * Sets the internal value and manages update state.
+   * @param {String|Array<String>} value - The value to set.
+   * @protected
    */
-  get currentLabel() {
-    if (!this.optionSelected) {
-      return '';
-    }
-    if (Array.isArray(this.optionSelected)) {
-      return this.optionSelected.map((opt) => opt.textContent).join(', ');
+  setInternalValue(value) {
+    if (this.value !== value) {
+      this.internalUpdateInProgress = true;
+      this.value = value;
+
+      setTimeout(() => {
+        this.internalUpdateInProgress = false;
+      });
     }
-    return this.optionSelected.textContent || '';
   }
 
   /**
-   * Formatted value based on `multiSelect` state.
-   * Default type is `String`, changing to `Array<String>` when `multiSelect` is true.
-   * @private
-   * @returns {String|Array<String>}
+   * Handles changes from the menu service and updates component state.
+   * @param {Object} event - The event object from the menu service.
+   * @protected
    */
-  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)];
+  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);
       }
-      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 {
-          const parsed = JSON.parse(this.value);
-          return Array.isArray(parsed) ? parsed : [this.value];
-        } catch {
-          return [this.value];
+
+      // Notify components of selection change
+      this.notifySelectionChange(event);
+    }
+
+    if (event.type === 'highlightChange') {
+      this.optionActive = event.option;
+      this._index = event.index;
+    }
+
+    if (event.type === 'optionsChange') {
+      this.options = event.options;
+      this.dispatchEvent(new CustomEvent('auroMenu-optionsChange', {
+        detail: {
+          options: event.options
         }
-      }
-      return [this.value];
+      }));
     }
-    return this.value;
   }
 
   /**
-   * Selects options by value.
-   * @param {string|string[]|undefined|null} value - The value(s) to select.
-   * @public
+   * Gets the currently selected options.
+   * @returns {Array<HTMLElement>}
    */
-  selectByValue(value) {
-    const isEmpty = value === undefined ||
-      value === null ||
-      (Array.isArray(value) && value.length === 0) ||
-      (typeof value === 'string' && value.trim() === '');
-
-    if (isEmpty) {
-      this.clearSelection();
-      return;
-    }
+  get selectedOptions() {
+    return this.menuService ? this.menuService.selectedOptions : [];
+  }
 
-    // `value` is a String property; stringify arrays so attribute reflection and `formattedValue` parsing stay correct.
-    this.value = Array.isArray(value) ? JSON.stringify(value) : value;
+  /**
+   * Gets the first selected option, or null if none.
+   * @returns {HTMLElement|null}
+   */
+  get selectedOption() {
+    return this.menuService ? this.menuService.selectedOptions[0] : null;
   }
 
   // Lifecycle Methods
@@ -585,7 +1392,9 @@ class AuroMenu extends AuroElement {
   connectedCallback() {
     super.connectedCallback();
 
-    this.addEventListener('keydown', this.handleKeyDown);
+    this.provideContext();
+
+    // this.addEventListener('keydown', this.handleKeyDown);
     this.addEventListener('auroMenuOption-click', this.handleMouseSelect);
     this.addEventListener('auroMenuOption-mouseover', this.handleOptionHover);
     this.addEventListener('slotchange', this.handleSlotChange);
@@ -593,7 +1402,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);
@@ -608,114 +1417,25 @@ 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);
 
-    // 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();
-    }
-
-    // Reset selection if multiSelect mode changes
-    if (changedProperties.has('multiSelect') && !changedProperties.has("value")) {
-      this.clearSelection();
+    // 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);
     }
 
-    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();
-      }
-
-      // 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) => valueArray.includes(item.value)) : [];
-          newSelected = matchingOptions.length > 0 ? matchingOptions : undefined;
-        } else {
-          // In single-select mode, this.value should be a string
-          const matchingOption = this.items ? this.items.find((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
-      if (this.optionSelected !== undefined) {
-        const selected = Array.isArray(this.optionSelected) ? this.optionSelected : [this.optionSelected];
-        selected.forEach((opt) => {
-          if (opt.hasAttribute('event')) {
-            this.handleCustomEvent(opt);
-          }
-        });
-      }
+    // Handle loading state changes
+    if (changedProperties.has('loading')) {
+      this.setLoadingState(this.loading);
     }
 
-    // Process all other UI updates
     if (changedProperties.has('multiSelect') && this.rootMenu) {
       if (this.multiSelect) {
         this.setAttribute('aria-multiselectable', 'true');
@@ -723,129 +1443,30 @@ class AuroMenu extends AuroElement {
         this.removeAttribute('aria-multiselectable');
       }
     }
-
-    this.updateItemsState(changedProperties);
   }
 
   /**
-   * Updates the UI state and appearance of menu items based on changed properties.
+   * 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
-   * @param {Map<string, boolean>} changedProperties - LitElement's changed properties map.
    */
-  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
-      });
-    }
-
-    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');
+  setTagAttribute(tagName) {
+    if (this.tagName.toLowerCase() !== tagName) {
+      this.setAttribute(tagName, true);
     }
+  }
 
-    // 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;
-      }
+  /**
+   * 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
     });
-
   }
 
   // Init Methods
@@ -855,7 +1476,6 @@ class AuroMenu extends AuroElement {
    * @private
    */
   initializeMenu() {
-    this.initItems();
     if (this.rootMenu) {
       this.setAttribute('role', 'listbox');
       this.setAttribute('root', '');
@@ -865,117 +1485,15 @@ class AuroMenu extends AuroElement {
       }
     }
 
-    // Must run for nested menus too — sets level, role="group", and aria-label="submenu" based on parent.
     this.handleNestedMenus(this);
   }
 
   /**
-   * Initializes menu items and their attributes.
-   * @private
-   */
-  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 = JSON.stringify([
-          ...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.
+   * Selects the currently highlighted option.
+   * @protected
    */
-  handleDeselectState(option) {
-    if (this.multiSelect) {
-      // Remove this option from array
-      const newFormattedValue = (this.formattedValue || []).filter((val) => val !== option.value);
-
-      // If array is empty after removal, set back to undefined
-      if (newFormattedValue && newFormattedValue.length === 0) {
-        this.value = undefined;
-      } else {
-        this.value = JSON.stringify(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.
+  makeSelection() {
+    this.menuService.selectHighlightedOption();
   }
 
   /**
@@ -994,18 +1512,7 @@ class AuroMenu extends AuroElement {
    * @public
    */
   reset() {
-    // Reset to undefined - initial state
-    this.value = undefined;
-    this.optionSelected = undefined;
-    this._index = -1;
-
-    // Reset UI state
-    this.updateItemsState(new Map([
-      [
-        'optionSelected',
-        true
-      ]
-    ]));
+    this.menuService.reset();
 
     // Dispatch reset event
     dispatchMenuEvent(this, 'auroMenu-selectValueReset');
@@ -1017,239 +1524,44 @@ 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) {
-      menu.setAttribute('role', 'group');
-      menu.removeAttribute("root");
-      if (!menu.hasAttribute('aria-label')) {
-        menu.setAttribute('aria-label', 'submenu');
-      }
-    }
-
-    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);
+    if (menu.level > 0) {
+      menu.setAttribute('role', 'group');
+      menu.removeAttribute("root");
+      if (!menu.hasAttribute('aria-label')) {
+        menu.setAttribute('aria-label', 'submenu');
+      }
     }
+
+    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, '');
+    });
   }
 
   /**
-   * Navigates through options using keyboard.
-   * @param {string} direction - 'up' or 'down'.
+   * Navigates the menu options in the specified direction.
+   * @param {'up'|'down'} direction - The direction to navigate.
+   * @protected
    */
   navigateOptions(direction) {
-    // 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);
+    if (direction === 'up') {
+      this.menuService.highlightPrevious();
+    } else if (direction === 'down') {
+      this.menuService.highlightNext();
     }
   }
 
   /**
-   * 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.
+   * Handles slot change events.
+   * @private
    */
-  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;
+  handleSlotChange() {
+    if (this.rootMenu) {
+      this.initializeMenu();
     }
-
-    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]);
   }
 
   /**
@@ -1259,8 +1571,8 @@ class AuroMenu extends AuroElement {
    */
   handleCustomEvent(option) {
     const eventName = option.getAttribute('event');
-    dispatchMenuEvent(this, eventName, { option });
-    dispatchMenuEvent(this, 'auroMenu-customEventFired', { option });
+    dispatchMenuEvent(this, eventName);
+    dispatchMenuEvent(this, 'auroMenu-customEventFired');
   }
 
   /**
@@ -1268,33 +1580,14 @@ class AuroMenu extends AuroElement {
    * @param {any} source - The source that triggers this event.
    * @private
    */
-  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;
+  notifySelectionChange({value, stringValue, keys, options, reason} = {}) {
+    dispatchMenuEvent(this, 'auroMenu-selectedOption', {
+      value,
+      stringValue,
+      keys,
+      options,
+      reason
+    });
   }
 
   /**
@@ -1309,6 +1602,7 @@ 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);
     }
 
@@ -1451,12 +1745,37 @@ let menuOptionIdCounter = 0;
  * @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
      */
@@ -1481,57 +1800,109 @@ class AuroMenuOption extends AuroElement {
     /**
      * @private
      */
-    this.tabIndex = -1;
+    this.runtimeUtils = new AuroLibraryRuntimeUtils();
+
+    // Initialize context-related properties
+    this.menuService = null;
+    this.unsubscribe = null;
 
     /**
      * @private
      */
-    this.runtimeUtils = new AuroLibraryRuntimeUtils();
-
-    this.addEventListener('click', this.handleClick.bind(this));
+    this.handleMenuChange = this.handleMenuChange.bind(this);
   }
 
   static get properties() {
     return {
       ...super.properties,
-      noCheckmark: {
+
+      /**
+       * When true, disables the menu option.
+       */
+      disabled: {
         type: Boolean,
         reflect: true
       },
-      selected: {
-        type: Boolean,
+
+      /**
+       * @private
+       */
+      event: {
+        type: String,
         reflect: true
       },
-      disabled: {
-        type: Boolean,
-        reflect: true
+
+      /**
+       * @private
+       */
+      layout: {
+        type: String
       },
-      value: {
+
+      /**
+       * 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: {
         type: String,
         reflect: true
       },
-      tabIndex: {
-        type: Number,
-        reflect: true
+
+      /**
+       * @private
+       */
+      menuService: {
+        type: Object,
+        state: true
       },
 
       /**
        * @private
        */
-      event: {
+      matchWord: {
         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.
+       * 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.
        */
       noMatch: {
         type: Boolean,
         reflect: true,
         attribute: 'nomatch'
       },
+
+      /**
+       * Specifies that an option is selected.
+       */
+      selected: {
+        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
+      },
     };
   }
 
@@ -1543,48 +1914,41 @@ 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');
 
-    // 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';
-    }
-
+    // Generate unique ID if not already set (required for aria-activedescendant)
     if (!this.id) {
       menuOptionIdCounter += 1;
       this.id = `menuoption-${menuOptionIdCounter}`;
@@ -1606,8 +1970,16 @@ 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')) {
@@ -1617,48 +1989,231 @@ 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);
+    }
   }
 
-  handleMenuChange() {
-    // no-op: menu owns state in the distributed architecture
+  /**
+   * 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));
   }
 
-  setSelected(value) {
-    this.selected = value;
+  /**
+   * 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);
   }
 
-  updateActive(active) {
-    this.active = active;
-    if (active) {
-      this.classList.add('active');
-    } else {
-      this.classList.remove('active');
+  /**
+   * 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);
+    }
+  }
+
+  /**
+   * 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();
     }
+
+    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');
   }
 
-  attachTo() {
-    // no-op: menu owns state in the distributed architecture
+
+  /**
+   * 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);
+      }
+    }
   }
 
   /**
-   * Handles click events on the menu option.
+   * 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.
    * @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) {
-      // 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
-      }));
+      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 });
     }
   }
 
+  /**
+   * 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`.
    *
@@ -1698,8 +2253,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>
     `;