feat(combo-box): autocomplete with typeahead (#21008)

* feat(combo-box): autocomplete with typeahead

* chore: cleanup

* fix: should-filter-item attribute

* chore: cleanup and docs

---------

Co-authored-by: Heloise Lui <71858203+heloiselui@users.noreply.github.com>

Author: maradwan26

packages/web-components/src/components/combo-box/combo-box.stories.ts

@@ -318,6 +318,22 @@ export const WithAILabel = {
   },
 };
 
+export const AutocompleteWithTypeahead = {
+  render: () => html`
+    <cds-combo-box
+      title-text="ComboBox title"
+      helper-text="Combobox helper text"
+      typeahead>
+      <cds-combo-box-item value="apple">Apple</cds-combo-box-item>
+      <cds-combo-box-item value="apricot">Apricot</cds-combo-box-item>
+      <cds-combo-box-item value="avocado">Avocado</cds-combo-box-item>
+      <cds-combo-box-item value="banana">Banana</cds-combo-box-item>
+      <cds-combo-box-item value="blackberry">Blackberry</cds-combo-box-item>
+      <cds-combo-box-item value="blueberry">Blueberry</cds-combo-box-item>
+      <cds-combo-box-item value="cantaloupe">Cantaloupe</cds-combo-box-item>
+    </cds-combo-box>
+  `,
+};
 export const WithLayer = {
   argTypes: controls,
   args: {

packages/web-components/src/components/combo-box/combo-box.ts

@@ -95,10 +95,18 @@ class CDSComboBox extends CDSDropdown {
     );
   }
 
+  connectedCallback() {
+    super.connectedCallback();
+    if (this.typeahead) {
+      this.shouldFilterItem = true;
+      this.setAttribute('should-filter-item', '');
+    }
+  }
+
   /**
    * Handles `input` event on the `<input>` for filtering.
    */
-  protected _handleInput() {
+  protected _handleInput(event: InputEvent) {
     const rawQueryText = this._filterInputNode.value;
     const queryText = rawQueryText.trim().toLowerCase();
 
@@ -118,13 +126,49 @@ class CDSComboBox extends CDSDropdown {
       if (highlightedItem) {
         this._scrollItemIntoView(highlightedItem as HTMLElement);
       }
-    }
 
+      if (this.typeahead && event?.inputType?.startsWith('insert')) {
+        const suggestedItem = highlightedItem.textContent?.trim() ?? '';
+        if (
+          suggestedItem.toLowerCase().startsWith(rawQueryText.toLowerCase()) &&
+          suggestedItem.length > rawQueryText.length
+        ) {
+          const suggestionText =
+            rawQueryText + suggestedItem.slice(rawQueryText.length);
+
+          this._filterInputNode.value = suggestionText;
+          this._filterInputNode.setSelectionRange(
+            rawQueryText.length,
+            suggestionText.length
+          );
+
+          this._filterInputValue = suggestionText;
+          this.open = true;
+          this.requestUpdate();
+          return;
+        }
+      }
+    }
     this._filterInputValue = rawQueryText;
     this.open = true;
     this.requestUpdate();
   }
 
+  // removes the autocomplete suggestion
+  protected _removeAutoCompleteSuggestion() {
+    if (!this._filterInputNode) return;
+    const { selectionStart, selectionEnd, value } = this._filterInputNode;
+    if (selectionStart && selectionEnd && selectionEnd > selectionStart) {
+      const cleanInput = value.slice(0, selectionStart);
+      this._filterInputNode.value = cleanInput;
+      this._filterInputNode.setSelectionRange(
+        cleanInput.length,
+        cleanInput.length
+      );
+      return;
+    }
+  }
+
   // Applies filtering/highlighting to all slotted items.
   protected _filterItems(
     items: NodeListOf<Element>,
@@ -141,9 +185,9 @@ class CDSComboBox extends CDSDropdown {
         comboItem.highlighted = false;
         return;
       }
-      const matches = (comboItem.textContent || '')
-        .toLowerCase()
-        .includes(queryText);
+      const matches = this.typeahead
+        ? (comboItem.textContent || '').toLowerCase().startsWith(queryText)
+        : (comboItem.textContent || '').toLowerCase().includes(queryText);
       const filterFunction =
         typeof this.shouldFilterItem === 'function'
           ? this.shouldFilterItem
@@ -198,6 +242,13 @@ class CDSComboBox extends CDSDropdown {
 
   // Clear the query and selection when Escape is pressed.
   protected _handleInputKeydown(event: KeyboardEvent) {
+    // remove the autocomplete suggestion when navigating away from the suggested item
+    if (
+      this.typeahead &&
+      (event.key === 'ArrowDown' || event.key === 'ArrowUp')
+    ) {
+      this._removeAutoCompleteSuggestion();
+    }
     if (event.key !== 'Escape') {
       return;
     }
@@ -282,6 +333,13 @@ class CDSComboBox extends CDSDropdown {
       itemToSelect.setAttribute('aria-selected', 'true');
     }
     this._handleUserInitiatedToggle(false);
+
+    if (this.typeahead && this._filterInputNode) {
+      this._filterInputValue = itemToSelect?.textContent?.trim() ?? '';
+
+      const length = this._filterInputValue.length;
+      this._filterInputNode.setSelectionRange(length, length);
+    }
   }
 
   protected _renderLabel(): TemplateResult {
@@ -375,7 +433,8 @@ class CDSComboBox extends CDSDropdown {
   itemMatches!: (item: CDSComboBoxItem, queryText: string) => boolean;
 
   /**
-   * Provide custom filtering behavior.
+   * Provide custom filtering behavior. This attribute will be ignored if
+   * `typeahead` is enabled and will default to `true`
    */
   @property({
     attribute: 'should-filter-item',
@@ -385,6 +444,12 @@ class CDSComboBox extends CDSDropdown {
   })
   shouldFilterItem: boolean | ShouldFilterItem = false;
 
+  /**
+   * **Experimental**: will enable autocomplete and typeahead for the input field
+   */
+  @property({ type: Boolean })
+  typeahead = false;
+
   shouldUpdate(changedProperties) {
     super.shouldUpdate(changedProperties);
     const { _selectedItemContent: selectedItemContent } = this;
@@ -398,9 +463,14 @@ class CDSComboBox extends CDSDropdown {
     super.updated(changedProperties);
     if (changedProperties.has('open')) {
       if (this.open && this._filterInputNode) {
-        this._handleInput();
+        this._handleInput(changedProperties);
       } else if (!this.open) {
+        // remove the autocomplete suggestion when closing the combobox
+        this._removeAutoCompleteSuggestion();
         this._resetFilteredItems();
+        if (this._filterInputNode.value == '') {
+          this.value = '';
+        }
       }
     }
     const { _listBoxNode: listBoxNode } = this;