docs: create aria autocomplete docs (#32499)

* docs: create aria autocomplete docs

* fix(aria/combobox): focus out selection bug

* Navigating away from an auto-select or highlight combobox input
  should only trigger selection if the combobox popup is expanded.

* fix(aria/combobox): disabled options bug

* The combobox should not close the popup if the user
  tries to select a disabled option.

(cherry picked from commit ad3e7d2)

Author: wagnermaciel

src/aria/private/combobox/combobox.spec.ts

@@ -327,6 +327,15 @@ describe('Combobox with Listbox Pattern', () => {
       expect(combobox.expanded()).toBe(false);
     });
 
+    it('should not close on Enter if the option is disabled', () => {
+      const {combobox, options} = getPatterns();
+      options()[0].disabled.set(true);
+      combobox.onKeydown(down());
+      expect(combobox.expanded()).toBe(true);
+      combobox.onKeydown(enter());
+      expect(combobox.expanded()).toBe(true);
+    });
+
     it('should close on focusout', () => {
       const {combobox} = getPatterns();
       combobox.onKeydown(down());
@@ -488,6 +497,13 @@ describe('Combobox with Listbox Pattern', () => {
         combobox.onFocusOut(new FocusEvent('focusout'));
         expect(inputEl.value).toBe('Apple');
       });
+
+      it('should not commit an option on focusout if the popup is closed', () => {
+        type('A');
+        combobox.onKeydown(escape());
+        combobox.onFocusOut(new FocusEvent('focusout'));
+        expect(inputEl.value).toBe('A');
+      });
     });
 
     describe('when filterMode is "highlight"', () => {

src/aria/private/combobox/combobox.ts

@@ -390,6 +390,10 @@ export class ComboboxPattern<T extends ListItem<V>, V> {
     ) {
       this.isFocused.set(false);
 
+      if (!this.expanded()) {
+        return;
+      }
+
       if (this.readonly()) {
         this.close();
         return;
@@ -633,6 +637,12 @@ export class ComboboxPattern<T extends ListItem<V>, V> {
   select(opts: {item?: T; commit?: boolean; close?: boolean} = {}) {
     const controls = this.listControls();
 
+    const item = opts.item ?? controls?.getActiveItem();
+
+    if (item?.disabled()) {
+      return;
+    }
+
     if (opts.item) {
       controls?.focus(opts.item, {focusElement: false});
     }

src/components-examples/aria/autocomplete/BUILD.bazel

@@ -0,0 +1,29 @@
+load("//tools:defaults.bzl", "ng_project")
+
+package(default_visibility = ["//visibility:public"])
+
+ng_project(
+    name = "autocomplete",
+    srcs = glob(["**/*.ts"]),
+    assets = glob([
+        "**/*.html",
+        "**/*.css",
+    ]),
+    deps = [
+        "//:node_modules/@angular/common",
+        "//:node_modules/@angular/core",
+        "//:node_modules/@angular/forms",
+        "//src/aria/combobox",
+        "//src/aria/listbox",
+        "//src/cdk/overlay",
+    ],
+)
+
+filegroup(
+    name = "source-files",
+    srcs = glob([
+        "**/*.html",
+        "**/*.css",
+        "**/*.ts",
+    ]),
+)

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

@@ -0,0 +1,33 @@
+<div ngCombobox filterMode="auto-select">
+  <div #origin class="example-autocomplete">
+    <span class="example-search-icon material-symbols-outlined" translate="no">search</span>
+    <input
+      aria-label="Label dropdown"
+      placeholder="Select a country"
+      [(ngModel)]="query"
+      ngComboboxInput
+    />
+  </div>
+
+  <ng-template ngComboboxPopupContainer>
+    <ng-template
+      [cdkConnectedOverlay]="{origin, usePopover: 'inline', matchWidth: true}"
+      [cdkConnectedOverlayOpen]="true"
+    >
+      <div class="example-popup">
+        @if (countries().length === 0) {
+          <div class="example-no-results">No results found</div>
+        }
+
+        <div ngListbox>
+          @for (country of countries(); track country) {
+            <div ngOption [value]="country" [label]="country" [disabled]="country === 'Brazil'">
+              <span class="example-option-label">{{country}}</span>
+              <span class="example-check-icon material-symbols-outlined" translate="no">check</span>
+            </div>
+          }
+        </div>
+      </div>
+    </ng-template>
+  </ng-template>
+</div>

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

@@ -0,0 +1,70 @@
+/**
+ * @license
+ * Copyright Google LLC All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.dev/license
+ */
+
+import {
+  Combobox,
+  ComboboxInput,
+  ComboboxPopup,
+  ComboboxPopupContainer,
+} from '@angular/aria/combobox';
+import {Listbox, Option} from '@angular/aria/listbox';
+import {
+  afterRenderEffect,
+  ChangeDetectionStrategy,
+  Component,
+  computed,
+  signal,
+  viewChild,
+  viewChildren,
+} from '@angular/core';
+import {COUNTRIES} from '../countries';
+import {OverlayModule} from '@angular/cdk/overlay';
+import {FormsModule} from '@angular/forms';
+
+/** @title Autocomplete with auto-select filtering. */
+@Component({
+  selector: 'autocomplete-auto-select-example',
+  templateUrl: 'autocomplete-auto-select-example.html',
+  styleUrl: '../autocomplete.css',
+  imports: [
+    Combobox,
+    ComboboxInput,
+    ComboboxPopup,
+    ComboboxPopupContainer,
+    Listbox,
+    Option,
+    OverlayModule,
+    FormsModule,
+  ],
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class AutocompleteAutoSelectExample {
+  /** The options available in the listbox. */
+  options = viewChildren<Option<string>>(Option);
+
+  /** A reference to the ng aria combobox. */
+  combobox = viewChild<Combobox<string>>(Combobox);
+
+  /** The query string used to filter the list of countries. */
+  query = signal('');
+
+  /** The list of countries filtered by the query. */
+  countries = computed(() =>
+    COUNTRIES.filter(country => country.toLowerCase().startsWith(this.query().toLowerCase())),
+  );
+
+  constructor() {
+    // Scrolls to the active item when the active option changes.
+    afterRenderEffect(() => {
+      if (this.combobox()?.expanded()) {
+        const option = this.options().find(opt => opt.active());
+        option?.element.scrollIntoView({block: 'nearest'});
+      }
+    });
+  }
+}

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

@@ -0,0 +1,33 @@
+<div ngCombobox disabled>
+  <div #origin class="example-autocomplete">
+    <span class="example-search-icon material-symbols-outlined" translate="no">search</span>
+    <input
+      aria-label="Label dropdown"
+      placeholder="Select a country"
+      [(ngModel)]="query"
+      ngComboboxInput
+    />
+  </div>
+
+  <ng-template ngComboboxPopupContainer>
+    <ng-template
+      [cdkConnectedOverlay]="{origin, usePopover: 'inline', matchWidth: true}"
+      [cdkConnectedOverlayOpen]="true"
+    >
+      <div class="example-popup">
+        @if (countries().length === 0) {
+          <div class="example-no-results">No results found</div>
+        }
+
+        <div ngListbox>
+          @for (country of countries(); track country) {
+            <div ngOption [value]="country" [label]="country" [disabled]="country === 'Brazil'">
+              <span class="example-option-label">{{country}}</span>
+              <span class="example-check-icon material-symbols-outlined" translate="no">check</span>
+            </div>
+          }
+        </div>
+      </div>
+    </ng-template>
+  </ng-template>
+</div>

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

@@ -0,0 +1,70 @@
+/**
+ * @license
+ * Copyright Google LLC All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.dev/license
+ */
+
+import {
+  Combobox,
+  ComboboxInput,
+  ComboboxPopup,
+  ComboboxPopupContainer,
+} from '@angular/aria/combobox';
+import {Listbox, Option} from '@angular/aria/listbox';
+import {
+  afterRenderEffect,
+  ChangeDetectionStrategy,
+  Component,
+  computed,
+  signal,
+  viewChild,
+  viewChildren,
+} from '@angular/core';
+import {COUNTRIES} from '../countries';
+import {OverlayModule} from '@angular/cdk/overlay';
+import {FormsModule} from '@angular/forms';
+
+/** @title Disabled autocomplete. */
+@Component({
+  selector: 'autocomplete-disabled-example',
+  templateUrl: 'autocomplete-disabled-example.html',
+  styleUrl: '../autocomplete.css',
+  imports: [
+    Combobox,
+    ComboboxInput,
+    ComboboxPopup,
+    ComboboxPopupContainer,
+    Listbox,
+    Option,
+    OverlayModule,
+    FormsModule,
+  ],
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class AutocompleteDisabledExample {
+  /** The options available in the listbox. */
+  options = viewChildren<Option<string>>(Option);
+
+  /** A reference to the ng aria combobox. */
+  combobox = viewChild<Combobox<string>>(Combobox);
+
+  /** The query string used to filter the list of countries. */
+  query = signal('United States of America');
+
+  /** The list of countries filtered by the query. */
+  countries = computed(() =>
+    COUNTRIES.filter(country => country.toLowerCase().startsWith(this.query().toLowerCase())),
+  );
+
+  constructor() {
+    // Scrolls to the active item when the active option changes.
+    afterRenderEffect(() => {
+      if (this.combobox()?.expanded()) {
+        const option = this.options().find(opt => opt.active());
+        option?.element.scrollIntoView({block: 'nearest'});
+      }
+    });
+  }
+}

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

@@ -0,0 +1,33 @@
+<div ngCombobox filterMode="highlight">
+  <div #origin class="example-autocomplete">
+    <span class="example-search-icon material-symbols-outlined" translate="no">search</span>
+    <input
+      aria-label="Label dropdown"
+      placeholder="Select a country"
+      [(ngModel)]="query"
+      ngComboboxInput
+    />
+  </div>
+
+  <ng-template ngComboboxPopupContainer>
+    <ng-template
+      [cdkConnectedOverlay]="{origin, usePopover: 'inline', matchWidth: true}"
+      [cdkConnectedOverlayOpen]="true"
+    >
+      <div class="example-popup">
+        @if (countries().length === 0) {
+          <div class="example-no-results">No results found</div>
+        }
+
+        <div ngListbox>
+          @for (country of countries(); track country) {
+            <div ngOption [value]="country" [label]="country" [disabled]="country === 'Brazil'">
+              <span class="example-option-label">{{country}}</span>
+              <span class="example-check-icon material-symbols-outlined" translate="no">check</span>
+            </div>
+          }
+        </div>
+      </div>
+    </ng-template>
+  </ng-template>
+</div>

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

@@ -0,0 +1,70 @@
+/**
+ * @license
+ * Copyright Google LLC All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.dev/license
+ */
+
+import {
+  Combobox,
+  ComboboxInput,
+  ComboboxPopup,
+  ComboboxPopupContainer,
+} from '@angular/aria/combobox';
+import {Listbox, Option} from '@angular/aria/listbox';
+import {
+  afterRenderEffect,
+  ChangeDetectionStrategy,
+  Component,
+  computed,
+  signal,
+  viewChild,
+  viewChildren,
+} from '@angular/core';
+import {COUNTRIES} from '../countries';
+import {OverlayModule} from '@angular/cdk/overlay';
+import {FormsModule} from '@angular/forms';
+
+/** @title Autocomplete with highlighted filtering. */
+@Component({
+  selector: 'autocomplete-highlight-example',
+  templateUrl: 'autocomplete-highlight-example.html',
+  styleUrl: '../autocomplete.css',
+  imports: [
+    Combobox,
+    ComboboxInput,
+    ComboboxPopup,
+    ComboboxPopupContainer,
+    Listbox,
+    Option,
+    OverlayModule,
+    FormsModule,
+  ],
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class AutocompleteHighlightExample {
+  /** The options available in the listbox. */
+  options = viewChildren<Option<string>>(Option);
+
+  /** A reference to the ng aria combobox. */
+  combobox = viewChild<Combobox<string>>(Combobox);
+
+  /** The query string used to filter the list of countries. */
+  query = signal('');
+
+  /** The list of countries filtered by the query. */
+  countries = computed(() =>
+    COUNTRIES.filter(country => country.toLowerCase().startsWith(this.query().toLowerCase())),
+  );
+
+  constructor() {
+    // Scrolls to the active item when the active option changes.
+    afterRenderEffect(() => {
+      if (this.combobox()?.expanded()) {
+        const option = this.options().find(opt => opt.active());
+        option?.element.scrollIntoView({block: 'nearest'});
+      }
+    });
+  }
+}