docs(aria/combobox): autocomplete clear buttons (#32531)

(cherry picked from commit 2775f8c)

Author: wagnermaciel

src/components-examples/aria/autocomplete/autocomplete-auto-select/autocomplete-auto-select-example.html

@@ -7,6 +7,14 @@
       [(ngModel)]="query"
       ngComboboxInput
     />
+    <button
+      class="example-clear-button"
+      aria-label="Clear"
+      (keydown)="onKeydown($event)"
+      (click)="clear()"
+    >
+      <span aria-hidden="true" class="example-clear-icon material-symbols-outlined">close</span>
+    </button>
   </div>
 
   <ng-template ngComboboxPopupContainer>

src/components-examples/aria/autocomplete/autocomplete-auto-select/autocomplete-auto-select-example.ts

@@ -44,6 +44,9 @@ import {FormsModule} from '@angular/forms';
   changeDetection: ChangeDetectionStrategy.OnPush,
 })
 export class AutocompleteAutoSelectExample {
+  /** The selected value of the combobox. */
+  listbox = viewChild<Listbox<string>>(Listbox);
+
   /** The options available in the listbox. */
   options = viewChildren<Option<string>>(Option);
 
@@ -67,4 +70,19 @@ export class AutocompleteAutoSelectExample {
       }
     });
   }
+
+  /** Clears the query and the listbox value. */
+  clear(): void {
+    this.query.set('');
+    this.listbox?.()?.values.set([]);
+  }
+
+  /** Handles keydown events on the clear button. */
+  onKeydown(event: KeyboardEvent): void {
+    if (event.key === 'Enter') {
+      this.clear();
+      this.combobox?.()?.close();
+      event.stopPropagation();
+    }
+  }
 }

src/components-examples/aria/autocomplete/autocomplete-highlight/autocomplete-highlight-example.html

@@ -7,6 +7,14 @@
       [(ngModel)]="query"
       ngComboboxInput
     />
+    <button
+      class="example-clear-button"
+      aria-label="Clear"
+      (keydown)="onKeydown($event)"
+      (click)="clear()"
+    >
+      <span aria-hidden="true" class="example-clear-icon material-symbols-outlined">close</span>
+    </button>
   </div>
 
   <ng-template ngComboboxPopupContainer>

src/components-examples/aria/autocomplete/autocomplete-highlight/autocomplete-highlight-example.ts

@@ -44,6 +44,9 @@ import {FormsModule} from '@angular/forms';
   changeDetection: ChangeDetectionStrategy.OnPush,
 })
 export class AutocompleteHighlightExample {
+  /** The selected value of the combobox. */
+  listbox = viewChild<Listbox<string>>(Listbox);
+
   /** The options available in the listbox. */
   options = viewChildren<Option<string>>(Option);
 
@@ -67,4 +70,19 @@ export class AutocompleteHighlightExample {
       }
     });
   }
+
+  /** Clears the query and the listbox value. */
+  clear(): void {
+    this.query.set('');
+    this.listbox?.()?.values.set([]);
+  }
+
+  /** Handles keydown events on the clear button. */
+  onKeydown(event: KeyboardEvent): void {
+    if (event.key === 'Enter') {
+      this.clear();
+      this.combobox?.()?.close();
+      event.stopPropagation();
+    }
+  }
 }

src/components-examples/aria/autocomplete/autocomplete-manual/autocomplete-manual-example.html

@@ -7,6 +7,14 @@
       [(ngModel)]="query"
       ngComboboxInput
     />
+    <button
+      class="example-clear-button"
+      aria-label="Clear"
+      (keydown)="onKeydown($event)"
+      (click)="clear()"
+    >
+      <span aria-hidden="true" class="example-clear-icon material-symbols-outlined">close</span>
+    </button>
   </div>
 
   <ng-template ngComboboxPopupContainer>

src/components-examples/aria/autocomplete/autocomplete-manual/autocomplete-manual-example.ts

@@ -44,6 +44,9 @@ import {FormsModule} from '@angular/forms';
   changeDetection: ChangeDetectionStrategy.OnPush,
 })
 export class AutocompleteManualExample {
+  /** The selected value of the combobox. */
+  listbox = viewChild<Listbox<string>>(Listbox);
+
   /** The options available in the listbox. */
   options = viewChildren<Option<string>>(Option);
 
@@ -67,4 +70,19 @@ export class AutocompleteManualExample {
       }
     });
   }
+
+  /** Clears the query and the listbox value. */
+  clear(): void {
+    this.query.set('');
+    this.listbox?.()?.values.set([]);
+  }
+
+  /** Handles keydown events on the clear button. */
+  onKeydown(event: KeyboardEvent): void {
+    if (event.key === 'Enter') {
+      this.clear();
+      this.combobox?.()?.close();
+      event.stopPropagation();
+    }
+  }
 }

src/components-examples/aria/autocomplete/autocomplete.css

@@ -22,7 +22,7 @@
   width: 13rem;
   font-size: 0.9rem;
   border-radius: var(--mat-sys-corner-extra-small);
-  padding: 0.7rem 0.7rem 0.7rem 2.5rem;
+  padding: 0.7rem 2.5rem;
   outline-color: var(--mat-sys-primary);
   border: 1px solid var(--mat-sys-outline);
   background-color: var(--mat-sys-surface);
@@ -38,6 +38,22 @@
   display: none;
 }
 
+.example-clear-button {
+  position: absolute;
+  right: 0.5rem;
+  background-color: transparent;
+  border: none;
+  display: flex;
+  width: 2rem;
+  height: 2rem;
+  align-items: center;
+  cursor: pointer;
+}
+
+.example-clear-icon {
+  font-size: 1.25rem;
+}
+
 .example-popup {
   width: 100%;
   margin-top: 2px;