AuroMenu: Support Multi-Select For Multiple Options w/ Same Value

[StephenRiosDev]

Auro Menu Technical Reference (TRD)

This document covers all relevant module updates for supporting multi-select, multiple matching values, and enhanced selection logic using menuService.

---

Component: auro-menu

Provides

• MenuContext
  • Syncs the following values:
    • size
    • shape
    • noCheckmark
    • disabled
    • matchWord

---

Properties

Property	Type	Description
selectedOptions	Array[menuOption]	Returns the selected options from MenuContext.
value	String or Array[String{Key}]	Represents the selected value(s) of the menu. Setting depends on multiSelect.
selectAllMatchingOptions	Boolean	When true, selecting a value will select all options that share that value/key.

---

Getters

get selectedOptions()

Returns MenuContext.selectedOptions.

get value()

Returns:

menuService.getValue();

---

Setters

set value(value: String | Array[String])

Sets selected value(s) in the menu.

Logic:

• Calls:

  menuService.selectOptionsByKey(keys);

• Emits a valueChange event (via menuService.notifyValueChange()).

Multi-select behavior:

• If multiSelect is true:
  • Accepts Array[String{Key}] values.
  • If selectAllMatchingOptions is true, all matching options for each key are selected.
  • If selectAllMatchingOptions is false and there are multiple matching options, emits warning and selects first option with matching key only
• If multiSelect is false:
  • Accepts a single String value.
  • If selectAllMatchingOptions is true, all matching options for each key are selected.
  • If selectAllMatchingOptions is false and there are multiple matching options, emits warning and selects first option with matching key only

---

Event Handlers

keyhandler

Handles keyboard interaction:

• Enter / Tab:

  menuService.selectHighlightedOption();

• ArrowDown:

  menuService.highlightNextOption();

• ArrowUp:

  menuService.highlightPreviousOption();

---

Subscriptions

menuService.valueChange

• Emits a valueChange event from the menu when selection changes.

  emit('valueChange', detail = {
    value: string | Array[string],
    keys: Array[key],
    options: Array[MenuOption]
  });

---

Component: auro-menuOption

Consumes

• MenuContext
  • Syncs:
    • size
    • shape
    • noCheckmark
    • disabled
    • matchWord

---

Properties

Property	Type	Description
value	String	Option’s value.
key	String	Defaults to value. Can be overridden by user-defined key.

---

Methods

click()

Toggles selection via the service:

menuService.toggleOption(this);

updateState({ selected, highlighted })

Applies state updates:

• Sets aria-selected accordingly.
• Applies highlight styles.
• Updates internal UI state.
• Handles any other internal ops

---

Subscriptions

menuService.stateChange

Triggers:

this.updateState(newState);

propertyChange.matchWord

Triggers:

this.updateTextHighlight(newMatchWord);

---

Service: menuService

Manages shared menu logic and state synchronization.

---

State

Property	Type	Description
selectedOptions	Set<MenuOption>	Current selected options.
highlightedOption	MenuOption | null	Currently highlighted option.

---

Methods

toggleOption(option)

option.selected
  ? this.deselectOption(option)
  : this.selectOption(option);

selectHighlightedOption()

if (this.highlightedOption)
  this.selectOption(this.highlightedOption);

selectOption(option)

if (multiSelect)
  selectedOptions.add(option);
else {
  selectedOptions.clear();
  selectedOptions.add(option);
}
this.notifyStateChange();
this.notifyValueChange();

deselectOption(option)

selectedOptions.delete(option);
this.notifyStateChange();
this.notifyValueChange();

notifyStateChange()

Updates all registered options:

for (const option of menuOptions) {
  option.updateState({
    selected: selectedOptions.has(option),
    highlighted: highlightedOption === option
  });
}

notifyValueChange()

Emits a valueChange event with selection details:

emit('valueChange', detail = {
  value: string | Array[string], // Single value or array of values
  keys: Array[key],              // Selected option keys
  options: Array[MenuOption]     // Selected option objects
});

selectOptionsByValue(value: String | Array[String{MenuOption.Key}])

Selects options based on provided value(s).

Logic:

• Single select mode:
  • Selects all options matching the passed key.
  • If multiple options match and selectAllMatchingOptions is false:
    • Emits warning
    • Selects first matching option only
  • If selectAllMatchingOptions is true:
    • Selects all matching options
• Multi-select mode:
  • Selects all options matching the passed keys.
  • For each key with multiple matching options:
    • If selectAllMatchingOptions is false:
      • Emits warning
      • Selects first matching option only
    • If selectAllMatchingOptions is true:
      • Selects all matching options