@aurodesignsystem-dev/auro-formkit 0.0.0-pr1574.0 → 0.0.0-pr1576.1

package/components/select/demo/getting-started.min.js

@@ -4836,7 +4836,7 @@ let AuroHelpText$1 = class AuroHelpText extends i$2 {
   }
 };
 
-var formkitVersion$1 = '202607272111';
+var formkitVersion$1 = '202608040326';
 
 class AuroElement extends i$2 {
   static get properties() {
@@ -6938,7 +6938,7 @@ class AuroHelpText extends i$2 {
   }
 }
 
-var formkitVersion = '202607272111';
+var formkitVersion = '202608040326';
 
 var styleCss$2 = i$5`.util_displayInline{display:inline}.util_displayInlineBlock{display:inline-block}.util_displayBlock{display:block}.util_displayFlex{display:flex}.util_displayHidden{display:none}.util_displayHiddenVisually{position:absolute;overflow:hidden;clip:rect(1px, 1px, 1px, 1px);width:1px;height:1px;padding:0;border:0}.body-default{font-size:var(--wcss-body-default-font-size, 1rem);font-weight:var(--wcss-body-default-weight, );line-height:var(--wcss-body-default-line-height, 1.5rem)}.body-default,.body-default-emphasized{font-family:var(--wcss-body-family, "AS Circular"),system-ui,-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,"Helvetica Neue",Arial,sans-serif;letter-spacing:var(--wcss-body-letter-spacing, 0)}.body-default-emphasized{font-size:var(--wcss-body-default-emphasized-font-size, 1rem);font-weight:var(--wcss-body-default-emphasized-weight, );line-height:var(--wcss-body-default-emphasized-line-height, 1.5rem)}.body-lg{font-size:var(--wcss-body-lg-font-size, 1.125rem);font-weight:var(--wcss-body-lg-weight, );line-height:var(--wcss-body-lg-line-height, 1.625rem)}.body-lg,.body-lg-emphasized{font-family:var(--wcss-body-family, "AS Circular"),system-ui,-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,"Helvetica Neue",Arial,sans-serif;letter-spacing:var(--wcss-body-letter-spacing, 0)}.body-lg-emphasized{font-size:var(--wcss-body-lg-emphasized-font-size, 1.125rem);font-weight:var(--wcss-body-lg-emphasized-weight, );line-height:var(--wcss-body-lg-emphasized-line-height, 1.625rem)}.body-sm{font-size:var(--wcss-body-sm-font-size, 0.875rem);font-weight:var(--wcss-body-sm-weight, );line-height:var(--wcss-body-sm-line-height, 1.25rem)}.body-sm,.body-sm-emphasized{font-family:var(--wcss-body-family, "AS Circular"),system-ui,-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,"Helvetica Neue",Arial,sans-serif;letter-spacing:var(--wcss-body-letter-spacing, 0)}.body-sm-emphasized{font-size:var(--wcss-body-sm-emphasized-font-size, 0.875rem);font-weight:var(--wcss-body-sm-emphasized-weight, );line-height:var(--wcss-body-sm-emphasized-line-height, 1.25rem)}.body-xs{font-size:var(--wcss-body-xs-font-size, 0.75rem);font-weight:var(--wcss-body-xs-weight, );line-height:var(--wcss-body-xs-line-height, 1rem)}.body-xs,.body-xs-emphasized{font-family:var(--wcss-body-family, "AS Circular"),system-ui,-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,"Helvetica Neue",Arial,sans-serif;letter-spacing:var(--wcss-body-letter-spacing, 0)}.body-xs-emphasized{font-size:var(--wcss-body-xs-emphasized-font-size, 0.75rem);font-weight:var(--wcss-body-xs-emphasized-weight, );line-height:var(--wcss-body-xs-emphasized-line-height, 1rem)}.body-2xs{font-size:var(--wcss-body-2xs-font-size, 0.625rem);font-weight:var(--wcss-body-2xs-weight, );line-height:var(--wcss-body-2xs-line-height, 0.875rem)}.body-2xs,.body-2xs-emphasized{font-family:var(--wcss-body-family, "AS Circular"),system-ui,-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,"Helvetica Neue",Arial,sans-serif;letter-spacing:var(--wcss-body-letter-spacing, 0)}.body-2xs-emphasized{font-size:var(--wcss-body-2xs-emphasized-font-size, 0.625rem);font-weight:var(--wcss-body-2xs-emphasized-weight, );line-height:var(--wcss-body-2xs-emphasized-line-height, 0.875rem)}.display-2xl{font-family:var(--wcss-display-2xl-family, "AS Circular"),var(--wcss-display-2xl-family-fallback, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif);font-size:var(--wcss-display-2xl-font-size, clamp(3.5rem, 6vw, 5.375rem));font-weight:var(--wcss-display-2xl-weight, 300);letter-spacing:var(--wcss-display-2xl-letter-spacing, 0);line-height:var(--wcss-display-2xl-line-height, 1.3)}.display-xl{font-family:var(--wcss-display-xl-family, "AS Circular"),var(--wcss-display-xl-family-fallback, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif);font-size:var(--wcss-display-xl-font-size, clamp(3rem, 5.3333333333vw, 4.5rem));font-weight:var(--wcss-display-xl-weight, 300);letter-spacing:var(--wcss-display-xl-letter-spacing, 0);line-height:var(--wcss-display-xl-line-height, 1.3)}.display-lg{font-family:var(--wcss-display-lg-family, "AS Circular"),var(--wcss-display-lg-family-fallback, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif);font-size:var(--wcss-display-lg-font-size, clamp(2.75rem, 4.6666666667vw, 4rem));font-weight:var(--wcss-display-lg-weight, 300);letter-spacing:var(--wcss-display-lg-letter-spacing, 0);line-height:var(--wcss-display-lg-line-height, 1.3)}.display-md{font-family:var(--wcss-display-md-family, "AS Circular"),var(--wcss-display-md-family-fallback, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif);font-size:var(--wcss-display-md-font-size, clamp(2.5rem, 4vw, 3.5rem));font-weight:var(--wcss-display-md-weight, 300);letter-spacing:var(--wcss-display-md-letter-spacing, 0);line-height:var(--wcss-display-md-line-height, 1.3)}.display-sm{font-family:var(--wcss-display-sm-family, "AS Circular"),var(--wcss-display-sm-family-fallback, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif);font-size:var(--wcss-display-sm-font-size, clamp(2rem, 3.6666666667vw, 3rem));font-weight:var(--wcss-display-sm-weight, 300);letter-spacing:var(--wcss-display-sm-letter-spacing, 0);line-height:var(--wcss-display-sm-line-height, 1.3)}.display-xs{font-family:var(--wcss-display-xs-family, "AS Circular"),var(--wcss-display-xs-family-fallback, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif);font-size:var(--wcss-display-xs-font-size, clamp(1.75rem, 3vw, 2.375rem));font-weight:var(--wcss-display-xs-weight, 300);letter-spacing:var(--wcss-display-xs-letter-spacing, 0);line-height:var(--wcss-display-xs-line-height, 1.3)}.heading-xl{font-family:var(--wcss-heading-xl-family, "AS Circular"),var(--wcss-heading-xl-family-fallback, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif);font-size:var(--wcss-heading-xl-font-size, clamp(2rem, 3vw, 2.5rem));font-weight:var(--wcss-heading-xl-weight, 300);letter-spacing:var(--wcss-heading-xl-letter-spacing, 0);line-height:var(--wcss-heading-xl-line-height, 1.3)}.heading-lg{font-family:var(--wcss-heading-lg-family, "AS Circular"),var(--wcss-heading-lg-family-fallback, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif);font-size:var(--wcss-heading-lg-font-size, clamp(1.75rem, 2.6666666667vw, 2.25rem));font-weight:var(--wcss-heading-lg-weight, 300);letter-spacing:var(--wcss-heading-lg-letter-spacing, 0);line-height:var(--wcss-heading-lg-line-height, 1.3)}.heading-md{font-family:var(--wcss-heading-md-family, "AS Circular"),var(--wcss-heading-md-family-fallback, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif);font-size:var(--wcss-heading-md-font-size, clamp(1.625rem, 2.3333333333vw, 1.75rem));font-weight:var(--wcss-heading-md-weight, 300);letter-spacing:var(--wcss-heading-md-letter-spacing, 0);line-height:var(--wcss-heading-md-line-height, 1.3)}.heading-sm{font-family:var(--wcss-heading-sm-family, "AS Circular"),var(--wcss-heading-sm-family-fallback, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif);font-size:var(--wcss-heading-sm-font-size, clamp(1.375rem, 2vw, 1.5rem));font-weight:var(--wcss-heading-sm-weight, 300);letter-spacing:var(--wcss-heading-sm-letter-spacing, 0);line-height:var(--wcss-heading-sm-line-height, 1.3)}.heading-xs{font-family:var(--wcss-heading-xs-family, "AS Circular"),var(--wcss-heading-xs-family-fallback, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif);font-size:var(--wcss-heading-xs-font-size, clamp(1.25rem, 1.6666666667vw, 1.25rem));font-weight:var(--wcss-heading-xs-weight, 300);letter-spacing:var(--wcss-heading-xs-letter-spacing, 0);line-height:var(--wcss-heading-xs-line-height, 1.3)}.heading-2xs{font-family:var(--wcss-heading-2xs-family, "AS Circular"),var(--wcss-heading-2xs-family-fallback, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif);font-size:var(--wcss-heading-2xs-font-size, clamp(1.125rem, 1.5vw, 1.125rem));font-weight:var(--wcss-heading-2xs-weight, 300);letter-spacing:var(--wcss-heading-2xs-letter-spacing, 0);line-height:var(--wcss-heading-2xs-line-height, 1.3)}.accent-2xl{font-family:var(--wcss-accent-2xl-family, "Good OT"),var(--wcss-accent-2xl-family-fallback, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif);font-size:var(--wcss-accent-2xl-font-size, clamp(2rem, 3.1666666667vw, 2.375rem));font-weight:var(--wcss-accent-2xl-weight, 450);letter-spacing:var(--wcss-accent-2xl-letter-spacing, 0.05em);line-height:var(--wcss-accent-2xl-line-height, 1)}.accent-2xl,.accent-xl{text-transform:uppercase}.accent-xl{font-family:var(--wcss-accent-xl-family, "Good OT"),var(--wcss-accent-xl-family-fallback, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif);font-size:var(--wcss-accent-xl-font-size, clamp(1.625rem, 2.3333333333vw, 2rem));font-weight:var(--wcss-accent-xl-weight, 450);letter-spacing:var(--wcss-accent-xl-letter-spacing, 0.05em);line-height:var(--wcss-accent-xl-line-height, 1.3)}.accent-lg{font-family:var(--wcss-accent-lg-family, "Good OT"),var(--wcss-accent-lg-family-fallback, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif);font-size:var(--wcss-accent-lg-font-size, clamp(1.5rem, 2.1666666667vw, 1.75rem));font-weight:var(--wcss-accent-lg-weight, 450);letter-spacing:var(--wcss-accent-lg-letter-spacing, 0.05em);line-height:var(--wcss-accent-lg-line-height, 1.3)}.accent-lg,.accent-md{text-transform:uppercase}.accent-md{font-family:var(--wcss-accent-md-family, "Good OT"),var(--wcss-accent-md-family-fallback, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif);font-size:var(--wcss-accent-md-font-size, clamp(1.375rem, 1.8333333333vw, 1.5rem));font-weight:var(--wcss-accent-md-weight, 500);letter-spacing:var(--wcss-accent-md-letter-spacing, 0.05em);line-height:var(--wcss-accent-md-line-height, 1.3)}.accent-sm{font-family:var(--wcss-accent-sm-family, "Good OT"),var(--wcss-accent-sm-family-fallback, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif);font-size:var(--wcss-accent-sm-font-size, clamp(1.125rem, 1.5vw, 1.25rem));font-weight:var(--wcss-accent-sm-weight, 500);letter-spacing:var(--wcss-accent-sm-letter-spacing, 0.05em);line-height:var(--wcss-accent-sm-line-height, 1.3)}.accent-sm,.accent-xs{text-transform:uppercase}.accent-xs{font-family:var(--wcss-accent-xs-family, "Good OT"),var(--wcss-accent-xs-family-fallback, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif);font-size:var(--wcss-accent-xs-font-size, clamp(1rem, 1.3333333333vw, 1rem));font-weight:var(--wcss-accent-xs-weight, 500);letter-spacing:var(--wcss-accent-xs-letter-spacing, 0.1em);line-height:var(--wcss-accent-xs-line-height, 1.3)}.accent-2xs{font-family:var(--wcss-accent-2xs-family, "Good OT"),var(--wcss-accent-2xs-family-fallback, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif);font-size:var(--wcss-accent-2xs-font-size, clamp(0.875rem, 1.1666666667vw, 0.875rem));font-weight:var(--wcss-accent-2xs-weight, 450);letter-spacing:var(--wcss-accent-2xs-letter-spacing, 0.1em);line-height:var(--wcss-accent-2xs-line-height, 1.3);text-transform:uppercase}[auro-dropdown]{--ds-auro-dropdown-trigger-border-color: var(--ds-auro-select-border-color);--ds-auro-dropdown-trigger-background-color: var(--ds-auro-select-background-color);--ds-auro-dropdown-trigger-container-color: var(--ds-auro-select-background-color);--ds-auro-dropdown-trigger-outline-color: var(--ds-auro-select-outline-color)}:host{display:inline-block;text-align:left;vertical-align:top}:host([layout*=emphasized]) [auro-dropdown],:host([layout*=snowflake]) [auro-dropdown]{--ds-auro-select-border-color: transparent}:host([layout*=emphasized]) .mainContent,:host([layout*=snowflake]) .mainContent{text-align:center}.mainContent{position:relative;display:flex;overflow:hidden;flex:1;flex-direction:column;align-items:center;justify-content:center}.valueContainer{max-width:100%}.accents{display:flex;flex-direction:row;align-items:center;justify-content:center}::slotted([slot=typeIcon]){margin-right:var(--ds-size-100, 0.5rem)}.displayValue{display:block}.displayValue:not(.force){display:none}.displayValue:not(.force).hasContent:is(.withValue):not(.hasFocus){display:block}.triggerContent{display:flex;width:100%;box-sizing:border-box;align-items:center;justify-content:center}:host([layout*=emphasized]) .triggerContent{padding:0 var(--ds-size-100, 0.5rem) 0 var(--ds-size-300, 1.5rem)}:host([layout*=snowflake]) .triggerContent{padding:0 var(--ds-size-100, 0.5rem) 0 var(--ds-size-200, 1rem)}:host([layout*=snowflake]) label{padding-block:var(--ds-size-25, 0.125rem)}:host([layout*=classic]) .triggerContent{padding:0 var(--ds-size-100, 0.5rem)}:host([layout*=classic]) .mainContent{align-items:start}:host([layout*=classic]) label{overflow:hidden;cursor:text;text-overflow:ellipsis;white-space:nowrap}:host([layout*=classic]) .value{overflow:hidden;height:auto;text-overflow:ellipsis;white-space:nowrap}label{color:var(--ds-auro-select-label-text-color)}:host(:is([validity]:not([validity=valid]))) [auro-dropdown]{--ds-auro-select-border-color: var(--ds-basic-color-status-error, #e31f26);--ds-auro-select-outline-color: var(--ds-basic-color-status-error, #e31f26);--ds-auro-dropdown-helptext-text-color: var(--ds-basic-color-texticon-default, #2a2a2a)}:host([ondark]:is([validity]:not([validity=valid]))) [auro-dropdown],:host([appearance=inverse]:is([validity]:not([validity=valid]))) [auro-dropdown]{--ds-auro-select-border-color: var(--ds-advanced-color-state-error-inverse, #f9a4a8);--ds-auro-select-outline-color: var(--ds-advanced-color-state-error-inverse, #f9a4a8);--ds-auro-dropdown-helptext-text-color: var(--ds-basic-color-texticon-inverse, #ffffff)}#slotHolder{display:none}:host([fluid]){width:100%}:host([disabled]){pointer-events:none;user-select:none}:host([disabled]:not([ondark])) [auro-dropdown],:host([disabled]:not([appearance=inverse])) [auro-dropdown]{--ds-auro-select-border-color: var(--ds-basic-color-border-subtle, #dddddd)}:host(:not([layout*=classic])[disabled][ondark]) [auro-dropdown],:host(:not([layout*=classic])[disabled][appearance=inverse]) [auro-dropdown]{--ds-auro-select-border-color: transparent}`;
 
@@ -8769,6 +8769,107 @@ function isSelectableByValue(option) {
          !option.hasAttribute('static');
 }
 
+/* eslint-disable no-underscore-dangle */
+/**
+ * Resolves the single selected option for a given `value`, preferring the
+ * option tracked by `selectedKey` (a user-initiated selection) over a
+ * first-by-value match. When multiple options share the same `value`, matching
+ * by `value` alone cannot distinguish which one the user picked; the key
+ * disambiguates it.
+ *
+ * The key is trusted only when it still resolves to an option whose `value`
+ * matches the requested `value`. If the key is stale (option removed) or the
+ * value was changed programmatically, resolution falls back to value matching —
+ * preserving backward-compatible behavior for preselection and `selectByValue`.
+ * @private
+ * @param {Array<HTMLElement>} items - The menu's flat option list.
+ * @param {string} value - The value to resolve.
+ * @param {string|undefined} selectedKey - The `_optionKey` of the user-selected option, if any.
+ * @returns {HTMLElement|undefined} The resolved option, or undefined when none match.
+ */
+function resolveSelectedOption(items, value, selectedKey) {
+  if (!items) {
+    return undefined;
+  }
+
+  if (selectedKey !== undefined) {
+    const keyed = items.find((item) => item._optionKey === selectedKey);
+    if (keyed && isSelectableByValue(keyed) && keyed.value === value) {
+      return keyed;
+    }
+    // Key exists but the option is gone or its value no longer matches — fall
+    // through to value-based matching.
+  }
+
+  return items.find((item) => isSelectableByValue(item) && item.value === value);
+}
+
+/**
+ * Resolves the selected options for a multi-select `value` array, preferring
+ * options tracked by `selectedKeys` (user-initiated selections) and falling
+ * back to value matching for any values not resolved by key. The result is
+ * always sorted into DOM order regardless of selection sequence.
+ * @private
+ * @param {Array<HTMLElement>} items - The menu's flat option list.
+ * @param {Array<string>} valueArray - The selected values.
+ * @param {Array<string>|undefined} selectedKeys - The `_optionKey`s of the user-selected options, if any.
+ * @returns {Array<HTMLElement>} The resolved options in DOM order.
+ */
+function resolveSelectedOptions(items, valueArray, selectedKeys) {
+  if (!items) {
+    return [];
+  }
+
+  const resolved = [];
+
+  // Track how many of each value are still available to resolve. A value that
+  // appears N times in `valueArray` may be satisfied at most N times total across
+  // the key pass and the value fallback below — matching by count, not presence,
+  // on BOTH passes. This stops a duplicate value from being over-resolved: e.g.
+  // two keyed options that both carry `SEA` cannot both match a single requested
+  // `SEA` (which happens when `value` is set directly without clearing
+  // `_selectedKey`, so more keys survive than the value set now asks for).
+  const remaining = new Map();
+  valueArray.forEach((val) => remaining.set(val, (remaining.get(val) || 0) + 1));
+
+  // Resolve by key first: trust a key only when its option is still selectable
+  // and there is still an unmatched occurrence of its value in the request set.
+  if (Array.isArray(selectedKeys)) {
+    selectedKeys.forEach((key) => {
+      const keyed = items.find((item) => item._optionKey === key);
+      if (keyed && isSelectableByValue(keyed) && (remaining.get(keyed.value) || 0) > 0 && !resolved.includes(keyed)) {
+        resolved.push(keyed);
+        remaining.set(keyed.value, remaining.get(keyed.value) - 1);
+      }
+    });
+  }
+
+  // Fall back to value matching for the occurrences not resolved by key. Iterate
+  // the leftover per-value counts so a value that appears twice but was only
+  // resolved once by key still matches its remaining occurrence(s).
+  remaining.forEach((count, val) => {
+    for (let occurrence = 0; occurrence < count; occurrence += 1) {
+      const option = items.find((item) => isSelectableByValue(item) && item.value === val && !resolved.includes(item));
+      if (option) {
+        resolved.push(option);
+      }
+    }
+  });
+
+  // Always return in DOM order so display is consistent regardless of the order
+  // keys/values were selected. Every resolved option came from `items`, so an
+  // O(1) index lookup mirrors `_sortSelectedByDomOrder` and avoids the O(n)
+  // `items.indexOf` per comparison for large combobox option sets.
+  const indexMap = new Map(items.map((item, index) => [
+    item,
+    index
+  ]));
+  resolved.sort((optionA, optionB) => indexMap.get(optionA) - indexMap.get(optionB));
+
+  return resolved;
+}
+/* eslint-enable no-underscore-dangle */
+
 /**
  * Helper method to dispatch custom events.
  * @param {HTMLElement} element - Element to dispatch event from.
@@ -8794,6 +8895,14 @@ function dispatchMenuEvent(element, eventName, detail = null) {
 // See LICENSE in the project root for license information.
 
 
+/**
+ * Monotonically increasing counter used to give each menu instance a unique
+ * `_menuInstanceId` prefix. Auto-generating the id (rather than using a random
+ * string) keeps option keys deterministic and collision-free across menus.
+ * @private
+ */
+let menuInstanceIdCounter = 0;
+
 
 /**
  * The `auro-menu` element provides users a way to select from a list of options.
@@ -8868,6 +8977,8 @@ class AuroMenu extends AuroElement$1 {
     /**
      * @private
      */
+    menuInstanceIdCounter += 1;
+
     Object.assign(this, {
       // Root-level menu (true) or a nested submenu (false)
       rootMenu: true,
@@ -8877,6 +8988,21 @@ class AuroMenu extends AuroElement$1 {
       nestingSpacer: '<span class="nestingSpacer"></span>',
       // Loading indicator for slot elements
       loadingSlots: null,
+      // Unique id for this menu instance; prefixes every auto-generated option
+      // key so keys never collide across menus in the same document.
+      _menuInstanceId: `menu-${menuInstanceIdCounter}`,
+      // Monotonically increasing counter for option key generation. Never
+      // resets, so a key is never reused within this instance's lifetime.
+      _optionKeyCounter: 0,
+      // Key(s) of the option(s) the user has actively selected. A single string
+      // in single-select, an array in multi-select, undefined when nothing is
+      // user-selected. Used to disambiguate options that share a `value`.
+      _selectedKey: undefined,
+      // True only for the one updated() cycle following a user selection, so
+      // reconciliation trusts `_selectedKey`. A `value` change from a consumer's
+      // direct property assignment leaves this false, dropping the stale key so
+      // reconciliation falls back to first-by-value (see updated()).
+      _valueChangeFromSelection: false,
     });
   }
 
@@ -9096,6 +9222,13 @@ class AuroMenu extends AuroElement$1 {
       return;
     }
 
+    // A programmatic value set carries no positional intent, so drop any
+    // `_selectedKey` left over from a prior user click. This makes reconciliation
+    // in updated() fall back to first-by-value (single) / value-in-DOM-order
+    // (multi), matching the documented contract for programmatic selection even
+    // when a stale key would still resolve to a duplicate-value option.
+    this._selectedKey = undefined;
+
     // `value` is a String property; stringify arrays so attribute reflection and `formattedValue` parsing stay correct.
     this.value = Array.isArray(value) ? JSON.stringify(value) : value;
   }
@@ -9143,6 +9276,17 @@ class AuroMenu extends AuroElement$1 {
   updated(changedProperties) {
     super.updated(changedProperties);
 
+    // Consume the selection-driven flag for THIS cycle up front. Clearing it
+    // unconditionally — not only inside the `value` branch below — prevents it
+    // from lingering `true` when a selection produces a serialized `value`
+    // byte-identical to the current one, in which case Lit schedules no
+    // `value`-change cycle to consume it. A lingering flag would misclassify a
+    // later consumer's programmatic `value` set as selection-driven and keep a
+    // stale `_selectedKey`. The reconcile path below re-sets the instance flag
+    // after this point, so its intentional cross-cycle hand-off still works.
+    const valueChangeFromSelection = this._valueChangeFromSelection;
+    this._valueChangeFromSelection = false;
+
     // 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
@@ -9166,6 +9310,17 @@ class AuroMenu extends AuroElement$1 {
         this.initItems();
       }
 
+      // Distinguish a selection-driven `value` change (a user click, which set
+      // the flag in handleSelectState / _sortSelectedByDomOrder) from a
+      // programmatic assignment by a consumer. A programmatic set carries no
+      // positional intent, so drop any leftover `_selectedKey` and let
+      // reconciliation fall back to first-by-value (single) / value-in-DOM-order
+      // (multi) — the same contract selectByValue() guarantees, even when a
+      // stale key would otherwise still resolve to a duplicate-value option.
+      if (!valueChangeFromSelection) {
+        this._selectedKey = undefined;
+      }
+
       // Set when reconciliation reassigns `value` below. That reassignment schedules a
       // second updated() cycle, so the `event`-attribute dispatch is deferred to that
       // cycle to avoid firing option custom events twice on the same selection.
@@ -9183,7 +9338,10 @@ class AuroMenu extends AuroElement$1 {
           // Defensive default: `formattedValue` can be undefined for unexpected value types,
           // and calling `.includes` on undefined would throw during reconciliation.
           const valueArray = this.formattedValue || [];
-          const matchingOptions = this.items ? this.items.filter((item) => isSelectableByValue(item) && valueArray.includes(item.value)) : [];
+          // Resolve by key first (the user's exact picks), then fall back to
+          // value matching for any values not resolved by key — so pre-selection
+          // and programmatic value sets keep working. Result is DOM-ordered.
+          const matchingOptions = resolveSelectedOptions(this.items, valueArray, this._selectedKey);
           newSelected = matchingOptions.length > 0 ? matchingOptions : undefined;
 
           // Reconcile `value` with the selectable set. Drop only entries whose option is
@@ -9196,6 +9354,12 @@ class AuroMenu extends AuroElement$1 {
             : [];
           if (rejectedValues.length > 0) {
             const reconciled = valueArray.filter((val) => !rejectedValues.includes(val));
+            // This is an internal correction, not a consumer's programmatic set,
+            // so preserve the selection-driven flag through the re-entrant
+            // updated() cycle it schedules. Otherwise that cycle would treat the
+            // reassignment as programmatic and drop `_selectedKey` mid-cascade,
+            // flipping resolution and looping.
+            this._valueChangeFromSelection = true;
             this.value = serializeMultiSelectValue(reconciled);
             valueReconciled = true;
           }
@@ -9207,7 +9371,11 @@ class AuroMenu extends AuroElement$1 {
           // `hidden` is intentionally NOT excluded: the combobox toggles
           // `hidden` as its type-ahead filter, so a filtered-out option is
           // still a valid programmatic selection.
-          const matchingOption = this.items ? this.items.find((item) => isSelectableByValue(item) && item.value === this.value) : undefined;
+          // Prefer the option the user actually selected (tracked by
+          // `_selectedKey`) so a click on the second of two options sharing a
+          // `value` resolves back to that exact element instead of the first
+          // value match. Falls back to first-by-value for programmatic sets.
+          const matchingOption = resolveSelectedOption(this.items, this.value, this._selectedKey);
 
           if (matchingOption) {
             newSelected = matchingOption;
@@ -9435,6 +9603,14 @@ class AuroMenu extends AuroElement$1 {
       }
     });
 
+    // Assign private keys once items are populated. Only the root menu assigns
+    // keys: its `items` is a deep query that already includes nested submenu
+    // options, so a single pass keys the entire tree. Nested menus skip this
+    // and inherit keys from the root.
+    if (this.rootMenu) {
+      this._assignOptionKeys();
+    }
+
     if (this.noCheckmark) {
       this.updateItemsState(new Map([
         [
@@ -9451,6 +9627,31 @@ class AuroMenu extends AuroElement$1 {
     }));
   }
 
+  /**
+   * Assigns a private, auto-generated unique key (`_optionKey`) to each menu
+   * option that does not already have one. Keys are internal state on the
+   * element instance — never reflected as an attribute or exposed publicly —
+   * and let selection tracking distinguish options that share the same `value`.
+   *
+   * The `_optionKey === undefined` guard makes this idempotent: options keep the
+   * key they were first assigned across re-renders and slot changes, and if a
+   * nested menu's lifecycle runs a pass before the root, options simply wait for
+   * the root to key them (or keep whatever key they already hold).
+   * @private
+   */
+  _assignOptionKeys() {
+    if (!this.items) {
+      return;
+    }
+
+    this.items.forEach((option) => {
+      if (option._optionKey === undefined) {
+        this._optionKeyCounter += 1;
+        option._optionKey = `${this._menuInstanceId}-${this._optionKeyCounter}`;
+      }
+    });
+  }
+
   // Logic Methods
 
   /**
@@ -9460,24 +9661,28 @@ class AuroMenu extends AuroElement$1 {
    */
   handleSelectState(option) {
     if (this.multiSelect) {
-      const currentValue = this.formattedValue || [];
       const currentSelected = this.optionSelected || [];
 
-      if (!currentValue.includes(option.value)) {
-        this.value = serializeMultiSelectValue([
-          ...currentValue,
-          option.value
-        ]);
-      }
       if (!currentSelected.includes(option)) {
         this.optionSelected = [
           ...currentSelected,
           option
         ];
       }
+
+      // Re-sort by DOM order and rebuild `_selectedKey`/`value` from the
+      // selected set so display order stays consistent with the menu, not with
+      // click order.
+      this._sortSelectedByDomOrder();
     } else {
       this.value = option.value;
       this.optionSelected = option;
+      // Track the specific option the user selected so the value→option
+      // reconciliation in updated() resolves back to this exact element even
+      // when another option shares the same `value`.
+      this._selectedKey = option._optionKey;
+      // Mark this `value` change as selection-driven so updated() trusts the key.
+      this._valueChangeFromSelection = true;
     }
 
     this._index = this.items.indexOf(option);
@@ -9490,18 +9695,22 @@ class AuroMenu extends AuroElement$1 {
    */
   handleDeselectState(option) {
     if (this.multiSelect) {
-      // Remove this option from array; an empty result collapses `value` to undefined.
-      const newFormattedValue = (this.formattedValue || []).filter((val) => val !== option.value);
-      this.value = serializeMultiSelectValue(newFormattedValue);
-
-      this.optionSelected = this.optionSelected.filter((val) => val !== option);
+      // Remove this exact element from the selection (identity, not value — two
+      // options can share a `value`), then rebuild `value`/`_selectedKey` from
+      // the remaining set in DOM order. An empty result collapses to undefined.
+      this.optionSelected = this.optionSelected.filter((selected) => selected !== option);
       if (this.optionSelected.length === 0) {
         this.optionSelected = undefined;
+        this._selectedKey = undefined;
+        this.value = undefined;
+      } else {
+        this._sortSelectedByDomOrder();
       }
     } else {
       // For single-select: Back to undefined when deselected
       this.value = undefined;
       this.optionSelected = undefined;
+      this._selectedKey = undefined;
     }
 
     // Update the index tracking
@@ -9525,9 +9734,38 @@ class AuroMenu extends AuroElement$1 {
   clearSelection() {
     this.optionSelected = undefined;
     this.value = undefined;
+    this._selectedKey = undefined;
     this._index = -1;
   }
 
+  /**
+   * Re-sorts the multi-select selection into DOM order and rebuilds the derived
+   * `_selectedKey` and `value` from `optionSelected`. Selection is always stored
+   * and serialized in the order options appear in the menu, never in click
+   * order — so selecting C then A yields `[A, C]`.
+   * @private
+   */
+  _sortSelectedByDomOrder() {
+    if (!this.multiSelect || !Array.isArray(this.optionSelected) || !this.items) {
+      return;
+    }
+
+    const indexMap = new Map(this.items.map((item, index) => [
+      item,
+      index
+    ]));
+
+    // Sort any element no longer in `items` (a stale selection left over from a
+    // dynamic rebuild that the consumer has not cleared) to the END rather than
+    // the front, so it never displaces a live option to the head of the
+    // serialized order. Value reconciliation drops it on the next updated() cycle.
+    this.optionSelected.sort((optionA, optionB) => (indexMap.get(optionA) ?? this.items.length) - (indexMap.get(optionB) ?? this.items.length));
+    this._selectedKey = this.optionSelected.map((option) => option._optionKey);
+    this.value = serializeMultiSelectValue(this.optionSelected.map((option) => option.value));
+    // Mark this `value` change as selection-driven so updated() trusts the keys.
+    this._valueChangeFromSelection = true;
+  }
+
   /**
    * Resets the menu to its initial state.
    * This is the only way to return value to undefined.
@@ -9537,6 +9775,7 @@ class AuroMenu extends AuroElement$1 {
     // Reset to undefined - initial state
     this.value = undefined;
     this.optionSelected = undefined;
+    this._selectedKey = undefined;
     this._index = -1;
 
     // Clear active option state so a follow-up open/navigation starts fresh