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

package/components/menu/demo/keyboard-behavior.md

@@ -7,11 +7,90 @@
 <auro-header level="2" id="keyEvents">Key Events</auro-header>
 <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../docs/partials/keyEvents.md) -->
 <!-- The below content is automatically added from ./../docs/partials/keyEvents.md -->
-<!-- auro-menu does not implement direct keyboard event handling. -->
-<!-- Keyboard navigation is delegated to parent components (auro-select, auro-combobox) via their keyboard strategy files. -->
 <div class="note">
-<p><strong>Note:</strong> The <code>&lt;auro-menu&gt;</code> component does not handle keyboard events directly. Keyboard navigation is managed by the parent component (e.g., <code>&lt;auro-select&gt;</code>, <code>&lt;auro-combobox&gt;</code>) through their keyboard strategy classes, which call menu methods such as <code>navigateOptions()</code>, <code>makeSelection()</code>, and <code>updateActiveOption()</code>.</p>
-</div>
+<p><strong>Note:</strong> <code>&lt;auro-menu&gt;</code> registers a <code>keydown</code> listener on its host. By default the menu is not focusable — no <code>tabindex</code> on the host, and menuoptions are <code>tabindex="-1"</code> — so the listener does not fire on its own. It fires whenever a <code>keydown</code> reaches the host, which happens in any of the following ways:</p>
+<ul>
+<li>A wrapping component focuses something inside the menu subtree and the event bubbles up to the host. In the standard integrations (<code>&lt;auro-select&gt;</code>, <code>&lt;auro-combobox&gt;</code>), keyboard behavior is primarily parent-managed rather than bubble-driven: focus stays on the parent's trigger/input, and the parent captures keys there and drives the menu directly via its public <code>navigateOptions()</code> / <code>updateActiveOption()</code> methods and the menu's internal <code>makeSelection()</code> routine (<code>@private</code>, not part of the public menu API).</li>
+<li>A wrapping component dispatches or reroutes a <code>KeyboardEvent</code> at the menu programmatically (for example, <code>menu.dispatchEvent(new KeyboardEvent('keydown', { key: 'ArrowDown', bubbles: true }))</code>).</li>
+<li>The author makes the host focusable (for example, by adding <code>tabindex="0"</code> to the <code>&lt;auro-menu&gt;</code> element) and focuses it. The host already has <code>role="listbox"</code>, so this yields a bare, focusable listbox that responds to the keys in the table below. For full combobox semantics use <code>&lt;auro-select&gt;</code> or <code>&lt;auro-combobox&gt;</code>, or replicate their <code>aria-activedescendant</code> wiring from a separate trigger.</li>
+</ul>
+<p>Keys not listed below (<code>Home</code>, <code>End</code>, <code>Escape</code>, type-ahead) are handled by the parent — see the <code>&lt;auro-select&gt;</code> and <code>&lt;auro-combobox&gt;</code> keyboard behavior docs. An "interactive option" is one that is not <code>disabled</code>, <code>hidden</code>, or <code>static</code> — these are always skipped during navigation and selection, along with <code>&lt;hr&gt;</code> dividers.</p>
+</div>
+<table>
+<thead>
+<tr>
+<th>Key</th>
+<th>Current State</th>
+<th>Behavior</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td rowspan="5">ArrowDown</td>
+<td>No option is active</td>
+<td>The first interactive option becomes active.</td>
+</tr>
+<tr>
+<td>An option is active, followed by interactive options</td>
+<td>Advances the active option to the next interactive option.</td>
+</tr>
+<tr>
+<td>The last interactive option is active</td>
+<td>Wraps to the first interactive option.</td>
+</tr>
+<tr>
+<td>Menu has no options or all options are non-interactive</td>
+<td>No option becomes active; no <code>auroMenu-activatedOption</code> event fires.</td>
+</tr>
+<tr>
+<td>Menu is in <code>loading</code> state</td>
+<td>The rendered loading placeholder is inert (marked <code>disabled</code>) and is not part of <code>items</code>, so it cannot become active.</td>
+</tr>
+<tr>
+<td rowspan="4">ArrowUp</td>
+<td>No option is active</td>
+<td>The last interactive option becomes active.</td>
+</tr>
+<tr>
+<td>An option is active, preceded by interactive options</td>
+<td>Advances the active option to the previous interactive option.</td>
+</tr>
+<tr>
+<td>The first interactive option is active</td>
+<td>Wraps to the last interactive option.</td>
+</tr>
+<tr>
+<td>Menu has no options or all options are non-interactive</td>
+<td>No option becomes active.</td>
+</tr>
+<tr>
+<td rowspan="4">Enter</td>
+<td>Single-select, active option is not currently selected</td>
+<td>The active option is selected. Any previous selection is cleared. <code>auroMenu-selectedOption</code> fires.</td>
+</tr>
+<tr>
+<td>Single-select, active option is already selected</td>
+<td>No selection change, but <code>auroMenu-selectedOption</code> still fires so the parent can react (for example, close the dropdown).</td>
+</tr>
+<tr>
+<td>Multi-select</td>
+<td>The active option toggles selected. Other selections are preserved.</td>
+</tr>
+<tr>
+<td>Active option is disabled, hidden, or static</td>
+<td>Selection is a no-op.</td>
+</tr>
+<tr>
+<td rowspan="2">Tab</td>
+<td>An option is active</td>
+<td>The active option is selected (same behavior as <code>Enter</code>).<div class="note"><strong>Note:</strong> <code>Tab</code> does not <code>preventDefault</code>, so focus continues to the next element in the tabindex sequence after selection.</div></td>
+</tr>
+<tr>
+<td>No option is active</td>
+<td>Focus moves to the next tabbable element; no selection change.</td>
+</tr>
+</tbody>
+</table>
 <!-- AURO-GENERATED-CONTENT:END -->
 </div>
 </div>

package/components/menu/demo/voiceover.md

@@ -1,33 +1,40 @@
 <auro-header level="1" id="overview">Menu - VoiceOver Behavior</auro-header>
 <p>This page documents the VoiceOver experience when using the <code>&lt;auro-menu&gt;</code> component. It covers announcements and interactions for menu navigation and option selection.</p>
+<div class="note"><strong>Note:</strong> In the standard integrations (<code>&lt;auro-select&gt;</code>, <code>&lt;auro-combobox&gt;</code>), keyboard focus stays on the parent trigger/input — it does <strong>not</strong> move into the menu. The parent captures keys and drives the menu, and the active option is announced via <code>aria-activedescendant</code> on the trigger rather than by moving DOM focus between options. The focus-on-the-menu behavior described alongside the standalone case below only applies when an author makes <code>&lt;auro-menu&gt;</code> itself focusable (for example, <code>tabindex="0"</code>).</p>
 <auro-header level="2" id="voiceOverInteractiveAnnouncements">Interactive Announcements</auro-header>
 <auro-header level="3" id="voiceOverMenuContainer">Menu Container</auro-header>
-<p>When focus enters the menu, VoiceOver announces:</p>
+<p>When the listbox is exposed — the parent's dropdown opens, or a standalone focusable menu receives focus — VoiceOver announces:</p>
 <ol>
-<li><strong>Role:</strong> <em>"list box"</em></li>
+<li><strong>Role:</strong> <em>"list box"</em> — set on the root <code>&lt;auro-menu&gt;</code>; nested menus use <code>role="group"</code> with <code>aria-label="submenu"</code>.</li>
 <li><strong>Item count:</strong> The number of visible options (e.g., <em>"5 items"</em>)</li>
+<li><strong>Multi-select:</strong> When <code>multiSelect</code> is set on the root menu, <code>aria-multiselectable="true"</code> is exposed so VoiceOver announces the listbox as multi-selectable.</li>
+<li><strong>Loading:</strong> While <code>loading</code> is set, <code>aria-busy="true"</code> is exposed so VoiceOver signals that the option set is not yet stable.</li>
 </ol>
 <auro-header level="3" id="voiceOverMenuOptions">Menu Options</auro-header>
-<p>Each <code>auro-menuoption</code> announces the following when focused:</p>
+<p>Each <code>auro-menuoption</code> announces the following when the parent field points at it (via <code>aria-activedescendant</code>) or when the user reads through the listbox:</p>
 <ol>
 <li><strong>Label:</strong> The option's text content</li>
 <li><strong>Role:</strong> <em>"option"</em></li>
-<li><strong>Position:</strong> Position in the list (e.g., <em>"3 of 5"</em>)</li>
-<li><strong>Selected state:</strong> <em>"selected"</em> if the option is currently selected</li>
-<li><strong>Disabled state:</strong> <em>"dimmed"</em> if the option is disabled</li>
-</ol>
+<li><strong>Position:</strong> Position in the list (e.g., <em>"3 of 5"</em>) — when the menu is used inside <code>&lt;auro-select&gt;</code> (or another host that stamps them), each option receives <code>aria-setsize</code> and <code>aria-posinset</code>. Standalone <code>&lt;auro-menu&gt;</code> does not set these attributes itself; positional announcements outside a select/combobox host rely on VoiceOver's own listbox item count.</li>
+<li><strong>Selected state:</strong> <em>"selected"</em> if <code>aria-selected="true"</code> is set on the option</li>
+<li><strong>Disabled state:</strong> <em>"dimmed"</em> if <code>aria-disabled="true"</code> is set on the option</li>
+</ol>
+<div class="note"><strong>Note:</strong> <code>&lt;auro-menuoption&gt;</code> is not directly focusable — <code>tabindex="-1"</code> keeps it out of the tab order. In a select or combobox context, focus stays on the parent trigger and the active option is pointed at via <code>aria-activedescendant</code> (using <code>ariaActiveDescendantElement</code> to cross the shadow-root boundary).</div>
 <auro-header level="3" id="voiceOverSelection">Selection</auro-header>
-<p>When an option is selected via Enter or Space:</p>
+<p>In a select or combobox context, the parent captures Enter (and Tab) on its trigger/input and commits the active option through the menu; the menu itself does not receive the key. When the selection is committed:</p>
 <ul>
 <li>VoiceOver announces the option label followed by <em>"selected"</em></li>
 <li>In multi-select mode, previously selected options remain selected and their state is preserved</li>
-</ul>
+</ul>
+<p>A standalone focusable menu (see the note at the top of this page) handles Enter and Tab on its own host, producing the same selection announcement.</p>
 <auro-header level="2" id="voiceOverWorkflow">Navigation Workflow</auro-header>
+<p>In the standard select/combobox integrations, focus remains on the parent trigger/input throughout — the menu is a visually presented listbox the parent points into, not a place focus travels to:</p>
 <ol>
-<li><strong>Enter the menu:</strong> Focus moves into the listbox; VoiceOver announces role and item count</li>
-<li><strong>Navigate options:</strong> Use Arrow Down/Up keys; VoiceOver announces each option's label, role, and position</li>
-<li><strong>Select an option:</strong> Press Enter or Space; VoiceOver confirms the selection</li>
-<li><strong>Exit:</strong> Tab out of the menu or press Escape (when used within a dropdown context)</li>
-</ol>
+<li><strong>Open the listbox:</strong> Activating the trigger (or typing in a combobox) exposes the menu; VoiceOver announces the listbox role and item count</li>
+<li><strong>Navigate options:</strong> Arrow Down/Up keys pressed on the trigger move the active option; <code>aria-activedescendant</code> updates and VoiceOver announces each option's label, role, and position</li>
+<li><strong>Select an option:</strong> Enter (captured by the parent) commits the active option; VoiceOver confirms the selection</li>
+<li><strong>Exit:</strong> Escape and Tab are handled by the parent — Escape closes the listbox, and Tab commits the active option before moving focus to the next element in the tab sequence</li>
+</ol>
+<p>A standalone focusable menu follows the same active-option model, except focus is on the menu host and the menu handles Arrow, Enter, and Tab directly. See the menu's key events documentation for the full standalone key table.</p>
 <auro-header level="2" id="voiceOverNestedMenus">Nested Menus</auro-header>
 <p>When a nested <code>auro-menu</code> is encountered, VoiceOver announces a new listbox context. Each nested menu maintains its own option count and position tracking.</p>

package/components/menu/demo/why-menu.md

@@ -4,7 +4,7 @@
 <p>Custom list implementations often fail to provide correct ARIA semantics, keyboard navigation, or screen reader announcements.</p>
 <p><code>auro-menu</code> provides:</p>
 <ul>
-<li><strong>Keyboard navigation</strong> — Arrow keys move between options, Enter selects, Escape cancels, Home/End jump to the first and last options.</li>
+<li><strong>Keyboard navigation</strong> — Arrow Up/Down move the active option; Enter selects it; Tab selects and moves focus out of the menu.</li>
 <li><strong>Active option tracking</strong> — The currently highlighted option is tracked programmatically, enabling <code>aria-activedescendant</code> patterns in parent components like <code>auro-select</code> and <code>auro-combobox</code>.</li>
 <li><strong>Multi-select semantics</strong> — When <code>multiSelect</code> is enabled, <code>aria-multiselectable</code> is set on the menu.</li>
 <li><strong>Loading state</strong> — <code>aria-busy</code> is set during loading, with customizable loading icon and text slots.</li>
@@ -24,15 +24,14 @@
 <ul>
 <li>Checkmark indicators for each selected option</li>
 <li>A <code>value</code> that returns a JSON-stringified array of selections</li>
-<li><code>allowDeselect</code> to toggle selections off</li>
-<li><code>selectAllMatchingOptions</code> for bulk selection operations</li>
-<li><code>clearSelection()</code> and <code>reset()</code> methods for programmatic control</li>
+<li>Click-to-toggle behavior that deselects an already-selected option</li>
+<li><code>reset()</code> method for programmatic control</li>
 </ul>
 <auro-header level="2" id="searchAndFiltering">Search and filtering</auro-header>
 <p>Native menus have no concept of filtering or highlighting matched text.</p>
 <p><code>auro-menu</code> supports:</p>
 <ul>
-<li><code>matchWord</code> to highlight matching portions of option text as the user types (used by <code>auro-combobox</code> for real-time filtering)</li>
+<li><auro-hyperlink href="customize#matchWord"><code>matchWord</code></auro-hyperlink> to highlight matching portions of option text as the user types (used by <code>auro-combobox</code> for real-time filtering)</li>
 <li>Programmatic <code>navigateOptions(direction)</code> for keyboard-driven traversal</li>
 </ul>
 <auro-header level="2" id="loadingState">Loading state</auro-header>
@@ -88,7 +87,7 @@
 <tr>
 <td>Keyboard navigation</td>
 <td>Browser-dependent</td>
-<td>Full arrow/Enter/Escape/Home/End</td>
+<td>Arrow Up/Down, Enter, Tab</td>
 </tr>
 <tr>
 <td>Composable primitive</td>
@@ -96,9 +95,9 @@
 <td>Foundation for select and combobox</td>
 </tr>
 <tr>
-<td>Deselect support</td>
-<td>No</td>
-<td><code>allowDeselect</code> attribute</td>
+<td>Multi-select deselect</td>
+<td>Ctrl+click list box</td>
+<td>Click-to-toggle in multi-select</td>
 </tr>
 </tbody>
 </table>

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

@@ -10,6 +10,15 @@
  * or if the value cannot be parsed into an array from a JSON string.
  */
 export function arrayConverter(value: any): any[] | 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.
+ */
+export function serializeMultiSelectValue(values: Array<string> | undefined): string | undefined;
 /**
  * Compare two arrays for equality.
  * @private
@@ -25,6 +34,16 @@ export function arraysAreEqual(arr1: any[], arr2: any[]): boolean;
  * @returns {boolean} True if option is interactive.
  */
 export function isOptionInteractive(option: HTMLElement): boolean;
+/**
+ * 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.
+ */
+export function isSelectableByValue(option: HTMLElement): boolean;
 /**
  * Helper method to dispatch custom events.
  * @param {HTMLElement} element - Element to dispatch event from.

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

@@ -6,7 +6,6 @@
  * @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
@@ -15,13 +14,6 @@
  */
 export class AuroMenu extends AuroElement {
     static get properties(): {
-        /**
-         * Allows deselecting an already selected option when clicked again in single-select mode.
-         */
-        allowDeselect: {
-            type: BooleanConstructor;
-            reflect: boolean;
-        };
         /**
          * When true, the entire menu and all options are disabled.
          */
@@ -29,18 +21,6 @@ export class AuroMenu extends AuroElement {
             type: BooleanConstructor;
             reflect: boolean;
         };
-        /**
-         * Indicates whether the menu has a loadingIcon or loadingText to render when in a loading state.
-         */
-        hasLoadingPlaceholder: {
-            type: BooleanConstructor;
-        };
-        /**
-         * @private
-         */
-        layout: {
-            type: StringConstructor;
-        };
         /**
          * Indent level for submenus.
          * @private
@@ -80,56 +60,33 @@ export class AuroMenu extends AuroElement {
             reflect: boolean;
             attribute: string;
         };
-        /**
-         * Specifies the current active menuOption.
-         */
         optionActive: {
             type: ObjectConstructor;
-            attribute: string;
+            attribute: boolean;
         };
-        /**
-         * An array of currently selected menu options, type `HTMLElement` by default. In multi-select mode, `optionSelected` is an array of HTML elements.
-         */
         optionSelected: {
             type: ObjectConstructor;
-        };
-        options: {
-            type: ArrayConstructor;
-            reflect: boolean;
             attribute: boolean;
         };
-        /**
-         * Sets the size of the menu.
-         * @type {'sm' | 'md'}
-         * @default 'sm'
-         */
-        size: "sm" | "md";
-        /**
-         * When true, selects all options that match the provided value/key when setting value and multiselect is enabled.
-         */
-        selectAllMatchingOptions: {
-            type: BooleanConstructor;
-            reflect: boolean;
-        };
-        /**
-         * Sets the shape of the menu.
-         * @type {'box' | 'round'}
-         * @default 'box'
-         */
-        shape: "box" | "round";
         /**
          * 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: StringConstructor;
             reflect: boolean;
             attribute: string;
         };
+        layout: {
+            type: StringConstructor;
+            attribute: string;
+            reflect: boolean;
+        };
     };
     static get styles(): import("lit").CSSResult[];
     /**
      * 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/>
@@ -144,30 +101,41 @@ export class AuroMenu extends AuroElement {
      * @private
      */
     private size;
+    value: any;
     optionSelected: any;
     matchWord: any;
     noCheckmark: boolean;
-    optionActive: any;
+    optionActive: Element | undefined;
     loading: boolean;
     multiSelect: boolean;
-    allowDeselect: boolean;
-    selectAllMatchingOptions: boolean;
     /**
-     * Handles slot change events.
+     * Handles keyboard navigation and selection.
      * @private
+     * @param {KeyboardEvent} event - The keydown event.
      */
-    private handleSlotChange;
+    private handleKeyDown;
     /**
-     * @readonly
-     * @returns {string} - Returns the label of the currently selected option(s).
+     * Handles option selection via click events from menuoptions.
+     * @private
+     * @param {CustomEvent} event - The auroMenuOption-click event.
      */
-    readonly get currentLabel(): string;
+    private handleMouseSelect;
+    /**
+     * Handles option hover events.
+     * @private
+     * @param {CustomEvent} event - Event object from the browser.
+     */
+    private handleOptionHover;
+    /**
+     * Handles slot change events.
+     * @private
+     */
+    private handleSlotChange;
     /**
      * @readonly
      * @returns {Array<HTMLElement>} - Returns the array of available menu options.
-     * @deprecated Use `options` property instead.
      */
-    readonly get items(): Array<HTMLElement>;
+    readonly get options(): Array<HTMLElement>;
     /**
      * @param {number} value - Sets the index of the currently active option.
      */
@@ -177,83 +145,72 @@ export class AuroMenu extends AuroElement {
      */
     get index(): number;
     /**
-     * Formatted value based on `multiSelect` state.
-     * Default type is `String`, changing to `Array<String>` when `multiSelect` is true.
-     * @private
-     * @returns {String|Array<String>}
-     */
-    private get formattedValue();
-    /**
-     * Gets the current property values for the menu service.
-     * @private
-     * @returns {Object}
-     */
-    private get propertyValues();
-    /**
-     * Provides the menu context to child components.
-     * Initializes the MenuService and subscribes to menu changes.
-     * @protected
-     */
-    protected provideContext(): void;
-    rootMenu: boolean | undefined;
-    menuService: any;
-    _contextProvider: any;
-    /**
-     * 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: HTMLElement): void;
+    get selectedOptions(): Array<HTMLElement>;
     /**
-     * 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}
      */
-    protected setInternalValue(value: string | Array<string>): void;
-    internalUpdateInProgress: boolean | undefined;
-    value: any;
+    get selectedOption(): HTMLElement | 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).
      */
-    protected handleMenuChange(event: Object): void;
-    _index: any;
-    options: any;
+    readonly get currentLabel(): string;
     /**
-     * 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(): Array<HTMLElement>;
+    private get formattedValue();
     /**
-     * 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(): HTMLElement | null;
+    public selectByValue(value: string | string[] | undefined | null): void;
     firstUpdated(): void;
     loadingSlots: NodeListOf<Element> | undefined;
-    updated(changedProperties: any): void;
     /**
      * 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
      */
     private setTagAttribute;
+    updated(changedProperties: any): void;
+    _index: number | undefined;
     /**
-     * Sets the loading state and dispatches a loading change event.
-     * @param {boolean} isLoading - Whether the menu is loading.
-     * @protected
+     * Updates the UI state and appearance of menu items based on changed properties.
+     * @private
+     * @param {Map<string, boolean>} changedProperties - LitElement's changed properties map.
      */
-    protected setLoadingState(isLoading: boolean): void;
+    private updateItemsState;
     /**
      * Initializes the menu's state and structure.
      * @private
      */
     private initializeMenu;
     /**
-     * Selects the currently highlighted option.
-     * @protected
+     * Initializes menu items and their attributes.
+     * @private
+     */
+    private initItems;
+    items: Element[] | undefined;
+    /**
+     * Updates menu state when an option is selected.
+     * @private
+     * @param {HTMLElement} option - The option element to select.
+     */
+    private handleSelectState;
+    /**
+     * Deselects a menu option and updates related state.
+     * @private
+     * @param {HTMLElement} option - The menuoption to be deselected.
      */
-    protected makeSelection(): void;
+    private handleDeselectState;
     /**
      * Resets all options to their default state.
      * @private
@@ -272,11 +229,28 @@ export class AuroMenu extends AuroElement {
      */
     private handleNestedMenus;
     /**
-     * Navigates the menu options in the specified direction.
-     * @param {'up'|'down'} direction - The direction to navigate.
-     * @protected
+     * Makes a selection based on the current index.
+     * @private
+     */
+    private makeSelection;
+    /**
+     * Toggle the selection state of the menuoption.
+     * @private
+     * @param {HTMLElement} option - The menuoption to toggle.
+     */
+    private toggleOption;
+    rootMenu: boolean | undefined;
+    /**
+     * Navigates through options using keyboard.
+     * @param {string} direction - 'up' or 'down'.
+     */
+    navigateOptions(direction: string): void;
+    /**
+     * 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.
      */
-    protected navigateOptions(direction: "up" | "down"): void;
+    updateActiveOption(indexOrOption: number | HTMLElement): void;
     /**
      * Handles custom events defined on options.
      * @private
@@ -289,6 +263,13 @@ export class AuroMenu extends AuroElement {
      * @private
      */
     private notifySelectionChange;
+    /**
+     * @private
+     * @param {any} current - Current selection.
+     * @param {any} next - New selection to compare.
+     * @returns {boolean} Whether the selections are equal.
+     */
+    private selectionEquals;
     /**
      * Checks if an option is currently selected.
      * @private