docs(material): add autocomplete loading example

Author: hadt0786

src/components-examples/material/autocomplete/autocomplete-loading/autocomplete-loading-example.css

@@ -0,0 +1,9 @@
+.example-form {
+  min-width: 150px;
+  max-width: 500px;
+  width: 100%;
+}
+
+.example-full-width {
+  width: 100%;
+}

src/components-examples/material/autocomplete/autocomplete-loading/autocomplete-loading-example.html

@@ -0,0 +1,26 @@
+<form class="example-form">
+  @let options = filteredOptions | async;
+  <mat-form-field class="example-full-width">
+    <mat-label>State</mat-label>
+    <input type="text"
+           placeholder="Search states"
+           aria-label="State"
+           matInput
+           [formControl]="myControl"
+           [matAutocomplete]="auto">
+    <mat-autocomplete #auto="matAutocomplete">
+      @if (!isLoading()) {
+        @for (option of options ?? []; track option) {
+          <mat-option [value]="option">{{option}}</mat-option>
+        }
+      }
+    </mat-autocomplete>
+    <mat-hint aria-live="polite">
+      @if (isLoading()) {
+        Loading...
+      } @else if (options?.length === 0) {
+        No results found
+      }
+    </mat-hint>
+  </mat-form-field>
+</form>

src/components-examples/material/autocomplete/autocomplete-loading/autocomplete-loading-example.ts

@@ -0,0 +1,46 @@
+import {AsyncPipe} from '@angular/common';
+import {Component, signal} from '@angular/core';
+import {FormControl, ReactiveFormsModule} from '@angular/forms';
+import {MatAutocompleteModule} from '@angular/material/autocomplete';
+import {MatFormFieldModule} from '@angular/material/form-field';
+import {MatInputModule} from '@angular/material/input';
+import {Observable, of} from 'rxjs';
+import {delay, finalize, startWith, switchMap} from 'rxjs/operators';
+
+/** @title Autocomplete with asynchronous loading */
+@Component({
+  selector: 'autocomplete-loading-example',
+  templateUrl: 'autocomplete-loading-example.html',
+  styleUrl: 'autocomplete-loading-example.css',
+  imports: [
+    MatFormFieldModule,
+    MatInputModule,
+    MatAutocompleteModule,
+    ReactiveFormsModule,
+    AsyncPipe,
+  ],
+})
+export class AutocompleteLoadingExample {
+  myControl = new FormControl('');
+  options = ['Alabama', 'Alaska', 'Arizona', 'Arkansas', 'California'];
+  filteredOptions: Observable<string[]>;
+  isLoading = signal(true);
+
+  constructor() {
+    this.filteredOptions = this.myControl.valueChanges.pipe(
+      startWith(''),
+      switchMap(value => {
+        this.isLoading.set(true);
+        return this._filter(value || '').pipe(finalize(() => this.isLoading.set(false)));
+      }),
+    );
+  }
+
+  private _filter(value: string): Observable<string[]> {
+    const filterValue = value.toLowerCase();
+    const results = this.options.filter(option => option.toLowerCase().includes(filterValue));
+
+    // Simulate an asynchronous request.
+    return of(results).pipe(delay(500));
+  }
+}

src/components-examples/material/autocomplete/index.ts

@@ -2,6 +2,7 @@ export {AutocompleteAutoActiveFirstOptionExample} from './autocomplete-auto-acti
 export {AutocompleteAutoActiveFirstOptionSignalFormExample} from './autocomplete-auto-active-first-option-signal-form/autocomplete-auto-active-first-option-signal-form-example';
 export {AutocompleteDisplayExample} from './autocomplete-display/autocomplete-display-example';
 export {AutocompleteFilterExample} from './autocomplete-filter/autocomplete-filter-example';
+export {AutocompleteLoadingExample} from './autocomplete-loading/autocomplete-loading-example';
 export {AutocompleteOptgroupExample} from './autocomplete-optgroup/autocomplete-optgroup-example';
 export {AutocompleteOverviewExample} from './autocomplete-overview/autocomplete-overview-example';
 export {AutocompletePlainInputExample} from './autocomplete-plain-input/autocomplete-plain-input-example';

src/material/autocomplete/autocomplete.md

@@ -53,6 +53,15 @@ filter that doesn't limit matches to the beginning of the string.
 
 <!-- example(autocomplete-filter) -->
 
+### Showing loading and empty states
+
+When autocomplete options come from an asynchronous source, keep loading and empty-state messages
+outside of `mat-option` so that options only represent values that users can select. The example
+below uses `switchMap` so stale requests are cancelled when the input changes, `finalize` to clear
+the loading state when each request finishes, and an `aria-live` hint to announce status changes.
+
+<!-- example(autocomplete-loading) -->
+
 ### Setting separate control and display values
 
 If you want the option's control value (what is saved in the form) to be different than the option's