fix: update combobox to handle duplicate items

.changeset/combobox-change-event-detail.md

@@ -0,0 +1,14 @@
+---
+'@spectrum-web-components/combobox': minor
+---
+
+**Added**: Enhanced `<sp-combobox>` change event to include both `value` and `itemText` in the event detail, enabling consumers to access both the unique identifier and display text of the selected option.
+
+**Fixed**: Resolved issue where selecting an option would incorrectly match the first option with the same display text. The component now correctly preserves the selected option's value even when multiple options share similar display text.
+
+```js
+combobox.addEventListener('change', (event) => {
+    const { value, itemText } = event.detail;
+    console.log(`Selected: ${itemText} (ID: ${value})`);
+});
+```

1st-gen/packages/combobox/src/Combobox.ts

@@ -52,6 +52,7 @@ export type ComboboxOption = {
  * @element sp-combobox
  * @slot - Supply Menu Item elements to the default slot in order to populate the available options
  * @slot tooltip - Tooltip to to be applied to the the Picker Button
+ * @fires change - Announces that a selection has been made. The event detail contains `value` and `itemText` of the selected option.
  */
 export class Combobox extends Textfield {
     public static override get styles(): CSSResultArray {
@@ -105,6 +106,13 @@ export class Combobox extends Textfield {
 
     private itemValue = '';
 
+    /**
+     * Tracks the value when an item is selected from the menu dropdown.
+     * This ensures we preserve the exact selected value even when multiple
+     * options have the same itemText.
+     */
+    private _menuSelectedValue: string = '';
+
     /**
      * An array of options to present in the Menu provided while typing into the input
      */
@@ -302,13 +310,29 @@ export class Combobox extends Textfield {
         const selected = (this.options || this.optionEls).find(
             (item) => item.value === target?.value
         );
+        this.itemValue = selected?.value || '';
+        this._menuSelectedValue = selected?.value || '';
         this.value = selected?.itemText || '';
+        this.handleChange();
         event.preventDefault();
         this.open = false;
         this._returnItems();
         this.focus();
     }
 
+    protected override handleChange(): void {
+        this.dispatchEvent(
+            new CustomEvent('change', {
+                bubbles: true,
+                composed: true,
+                detail: {
+                    value: this.itemValue,
+                    itemText: this.value,
+                },
+            })
+        );
+    }
+
     public handleClosed(): void {
         this.open = false;
         this.overlayOpen = false;
@@ -339,10 +363,15 @@ export class Combobox extends Textfield {
         }
         if (changed.has('value')) {
             this.filterAvailableOptions();
-            this.itemValue =
-                this.availableOptions.find(
-                    (option) => option.itemText === this.value
-                )?.value ?? '';
+            if (this._menuSelectedValue) {
+                this.itemValue = this._menuSelectedValue;
+                this._menuSelectedValue = '';
+            } else {
+                const allOptions = this.options || this.optionEls;
+                this.itemValue =
+                    allOptions.find((option) => option.itemText === this.value)
+                        ?.value ?? '';
+            }
         }
         return super.shouldUpdate(changed);
     }

1st-gen/packages/combobox/stories/combobox.stories.ts

@@ -284,3 +284,52 @@ controlled.parameters = {
     // Disables Chromatic's snapshotting on a global level
     chromatic: { disableSnapshot: true },
 };
+
+/**
+ * Demonstrates the change event providing both value (unique ID) and itemText.
+ * This is useful when options share similar names but have distinct identifiers,
+ * such as contacts with the same name in different departments.
+ */
+export const changeEventWithValueAndItemText = (): TemplateResult => {
+    const contactOptions: ComboboxOption[] = [
+        { value: 'emp-1042', itemText: 'Alex Johnson (Engineering)' },
+        { value: 'emp-2187', itemText: 'Alex Johnson (Marketing)' },
+        { value: 'emp-3301', itemText: 'Sam Chen (Design)' },
+        { value: 'emp-4455', itemText: 'Jordan Lee (Sales)' },
+    ];
+
+    const handleChange = (event: CustomEvent): void => {
+        const { value, itemText } = event.detail;
+
+        // Update the output display
+        const output = document.getElementById('change-event-output');
+        if (output) {
+            output.textContent = `Employee ID: "${value}", Name: "${itemText}"`;
+        }
+    };
+
+    return html`
+        <div style="display: flex; flex-direction: column; gap: 16px;">
+            <sp-field-label for="combobox-contact-test">
+                Select a team member
+            </sp-field-label>
+            <sp-combobox
+                id="combobox-contact-test"
+                .options=${contactOptions}
+                @change=${handleChange}
+                style="width: 280px;"
+            ></sp-combobox>
+            <div>
+                <strong>Selected:</strong>
+                <code id="change-event-output">None yet</code>
+            </div>
+            <p style="color: gray; font-size: 12px;">
+                The change event provides both the unique employee ID (value)
+                and the display name (itemText) for use in your application.
+            </p>
+        </div>
+    `;
+};
+changeEventWithValueAndItemText.swc_vrt = {
+    skip: true,
+};