refactor(aria/combobox): include more comprehensive examples

Allow the different states of combobox to work with manual, auto-select, and highlight

Author: tjshiu

src/aria/combobox/combobox-popup.ts

@@ -7,7 +7,12 @@
  */
 
 import {Directive, inject, signal} from '@angular/core';
-import {ComboboxListboxControls, ComboboxTreeControls, ComboboxDialogPattern} from '../private';
+import {
+  ComboboxListboxControls,
+  ComboboxTreeControls,
+  ComboboxDialogPattern,
+  ComboboxNavigation,
+} from '../private';
 import type {Combobox} from './combobox';
 import {COMBOBOX} from './combobox-tokens';
 
@@ -41,4 +46,12 @@ export class ComboboxPopup<V> {
     | ComboboxDialogPattern
     | undefined
   >(undefined);
+
+  /** The navigation state to apply when the popup expands. */
+  readonly pendingNavigation = signal<ComboboxNavigation | undefined>(undefined);
+
+  /** Sets the navigation state to be applied when the popup is ready. */
+  focusOnReady(nav: ComboboxNavigation) {
+    this.pendingNavigation.set(nav);
+  }
 }

src/aria/listbox/listbox.ts

@@ -24,7 +24,7 @@ import {_IdGenerator} from '@angular/cdk/a11y';
 import {ComboboxListboxPattern, ListboxPattern, OptionPattern} from '../private';
 import {ComboboxPopup} from '../combobox';
 import {Option} from './option';
-import {LISTBOX} from './tokens';
+import {COMBOBOX_WIDGET, LISTBOX} from './tokens';
 
 /**
  * Represents a container used to display a list of items for a user to select from.
@@ -78,6 +78,8 @@ export class Listbox<V> {
     optional: true,
   });
 
+  private readonly _widget = inject<any>(COMBOBOX_WIDGET, {optional: true});
+
   /** A reference to the host element. */
   private readonly _elementRef = inject(ElementRef);
 
@@ -151,6 +153,7 @@ export class Listbox<V> {
       textDirection: this.textDirection,
       element: () => this._elementRef.nativeElement,
       combobox: () => this._popup?.combobox?._pattern,
+      hasPopup: () => !!this._popup?.combobox || !!this._widget,
     };
 
     this._pattern = this._popup?.combobox
@@ -171,8 +174,14 @@ export class Listbox<V> {
     });
 
     afterRenderEffect(() => {
-      if (!this._hasFocused()) {
-        this._pattern.setDefaultState();
+      const active = this._pattern.inputs.activeItem();
+
+      if (!this._widget || (this._widget as any).filterMode() !== 'manual') {
+        untracked(() => this._pattern.listBehavior.select());
+      }
+
+      if (this._widget) {
+        untracked(() => (this._widget as any).activeValue.set(active?.value()));
       }
     });
 
@@ -192,7 +201,12 @@ export class Listbox<V> {
       const items = inputs.items();
       const values = untracked(() => this.values());
 
-      if (items && values.some(v => !items.some(i => i.value() === v))) {
+      // If using simple combobx, the combobox should handle the value.
+      if (this._popup?.combobox || this._widget) {
+        return;
+      }
+
+      if (items.length > 0 && values.some(v => !items.some(i => i.value() === v))) {
         this.values.set(values.filter(v => items.some(i => i.value() === v)));
       }
     });

src/aria/listbox/tokens.ts

@@ -10,3 +10,5 @@ import {InjectionToken} from '@angular/core';
 import type {Listbox} from './listbox';
 
 export const LISTBOX = new InjectionToken<Listbox<any>>('LISTBOX');
+
+export const COMBOBOX_WIDGET = new InjectionToken<any>('COMBOBOX_WIDGET');

src/aria/private/combobox/combobox.ts

@@ -139,7 +139,7 @@ export interface ComboboxTreeControls<T extends ListItem<V>, V> extends Combobox
 }
 
 /** Controls the state of a combobox. */
-export class ComboboxPattern<T extends ListItem<V>, V> {
+export class ComboboxPattern<T extends ListItem<V>, V> implements ComboboxLike<T> {
   /** Whether the combobox is expanded. */
   expanded = signal(false);
 
@@ -570,7 +570,7 @@ export class ComboboxPattern<T extends ListItem<V>, V> {
   }
 
   /** Opens the combobox. */
-  open(nav?: {first?: boolean; last?: boolean; selected?: boolean}) {
+  open(nav?: ComboboxNavigation) {
     this.expanded.set(true);
     const popupControls = this.inputs.popupControls();
 
@@ -737,3 +737,15 @@ export class ComboboxDialogPattern {
     }
   }
 }
+
+export interface ComboboxNavigation {
+  first?: boolean;
+  last?: boolean;
+  selected?: boolean;
+}
+
+export interface ComboboxLike<T> {
+  expanded: WritableSignalLike<boolean>;
+  highlightedItem: WritableSignalLike<T | undefined>;
+  open(nav?: ComboboxNavigation): void;
+}

src/aria/private/listbox/listbox.ts

@@ -18,6 +18,9 @@ export type ListboxInputs<V> = ListInputs<OptionPattern<V>, V> & {
 
   /** Whether the listbox is readonly. */
   readonly: SignalLike<boolean>;
+
+  /** Whether the listbox is in a popup or widget context. */
+  hasPopup?: SignalLike<boolean>;
 };
 
 /** Controls the state of a listbox. */
@@ -135,8 +138,12 @@ export class ListboxPattern<V> {
     }
 
     if (!this.followFocus() && !this.inputs.multi()) {
-      manager.on(this.dynamicSpaceKey, () => this.listBehavior.toggleOne());
-      manager.on('Enter', () => this.listBehavior.toggleOne());
+      manager.on(this.dynamicSpaceKey, () =>
+        this.inputs.hasPopup?.() ? this.listBehavior.selectOne() : this.listBehavior.toggleOne(),
+      );
+      manager.on('Enter', () =>
+        this.inputs.hasPopup?.() ? this.listBehavior.selectOne() : this.listBehavior.toggleOne(),
+      );
     }
 
     if (this.inputs.multi() && this.followFocus()) {

src/aria/private/simple-combobox/BUILD.bazel

@@ -14,5 +14,6 @@ ts_project(
         "//src/aria/private/behaviors/expansion",
         "//src/aria/private/behaviors/list",
         "//src/aria/private/behaviors/signal-like",
+        "//src/aria/private/combobox",
     ],
 )

src/aria/private/simple-combobox/simple-combobox.ts

@@ -9,10 +9,11 @@
 import {KeyboardEventManager, PointerEventManager} from '../behaviors/event-manager';
 import {computed, signal, untracked} from '@angular/core';
 import {SignalLike, WritableSignalLike} from '../behaviors/signal-like/signal-like';
+import {ComboboxLike, ComboboxNavigation} from '../combobox/combobox';
 import {ExpansionItem} from '../behaviors/expansion/expansion';
 
 /** Represents the required inputs for a simple combobox. */
-export interface SimpleComboboxInputs extends ExpansionItem {
+export interface SimpleComboboxInputs<V> extends ExpansionItem {
   /** The value of the combobox. */
   value: WritableSignalLike<string>;
 
@@ -25,18 +26,27 @@ export interface SimpleComboboxInputs extends ExpansionItem {
   /** An inline suggestion to be displayed in the input. */
   inlineSuggestion: SignalLike<string | undefined>;
 
+  /** The active value in the popup (the option's value). */
+  activeValue: SignalLike<V | undefined>;
+
   /** Whether the combobox is disabled. */
   disabled: SignalLike<boolean>;
+
+  /** The filtering mode for the combobox. */
+  filterMode: SignalLike<'manual' | 'auto-select' | 'highlight'>;
 }
 
 /** Controls the state of a simple combobox. */
-export class SimpleComboboxPattern {
+export class SimpleComboboxPattern<V> {
   /** Whether the combobox is expanded. */
   readonly expanded: WritableSignalLike<boolean>;
 
   /** The value of the combobox. */
   readonly value: WritableSignalLike<string>;
 
+  /** The ID of the currently highlighted item in the popup. */
+  readonly highlightedItem = signal<string | undefined>(undefined);
+
   /** The element that the combobox is attached to. */
   readonly element = () => this.inputs.element();
 
@@ -147,7 +157,7 @@ export class SimpleComboboxPattern {
     return manager;
   });
 
-  constructor(readonly inputs: SimpleComboboxInputs) {
+  constructor(readonly inputs: SimpleComboboxInputs<V>) {
     this.expanded = inputs.expanded;
     this.value = inputs.value;
   }
@@ -227,6 +237,13 @@ export class SimpleComboboxPattern {
     const comboboxFocused = this.isFocused();
     const popupFocused = !!this.inputs.popup()?.isFocused();
     if (expanded && !comboboxFocused && !popupFocused) {
+      const activeValue = untracked(() => this.inputs.activeValue?.());
+
+      // Auto-commit highlighted item on blur for non-manual modes (auto-select and highlight).
+      // The Listbox pushes its highlighted value here, letting the headless directive sync it.
+      if (activeValue && this.inputs.filterMode() !== 'manual') {
+        this.value.set(activeValue as any); // Type assertion if needed
+      }
       this.expanded.set(false);
     }
   }
@@ -245,6 +262,18 @@ export interface SimpleComboboxPopupInputs {
 
   /** The ID of the popup. */
   popupId: SignalLike<string | undefined>;
+
+  /** Navigates to the first item in the popup. */
+  first: () => void;
+
+  /** Navigates to the last item in the popup. */
+  last: () => void;
+
+  /** Focuses the currently selected item in the popup. */
+  focusSelected: () => void;
+
+  /** Focuses the popup with the given navigation instruction when ready. */
+  focusOnReady: (nav: ComboboxNavigation) => void;
 }
 
 /** Controls the state of a simple combobox popup. */
@@ -264,6 +293,29 @@ export class SimpleComboboxPopupPattern {
   /** Whether the popup is focused. */
   readonly isFocused = signal(false);
 
+  /** Navigates to the first item in the popup. */
+  first() {
+    this.inputs.first();
+  }
+
+  /** Navigates to the last item in the popup. */
+  last() {
+    this.inputs.last();
+  }
+
+  /** Focuses the currently selected item in the popup. */
+  focusSelected() {
+    this.inputs.focusSelected();
+  }
+
+  /**
+   * Focuses the popup with the given navigation instruction when ready.
+   * This is used for lazy rendering (when the popup isn't in the DOM yet synchronously).
+   */
+  focusOnReady(nav: ComboboxNavigation) {
+    this.inputs.focusOnReady(nav);
+  }
+
   constructor(readonly inputs: SimpleComboboxPopupInputs) {}
 
   /** Handles focus in events for the popup. */

src/aria/private/tree/combobox-tree.ts

@@ -56,9 +56,6 @@ export class ComboboxTreePattern<V>
   /** Noop. The combobox handles pointerdown events. */
   override onPointerdown(_: PointerEvent): void {}
 
-  /** Noop. The combobox controls the open state. */
-  override setDefaultState(): void {}
-
   /** Navigates to the specified item in the tree. */
   focus = (item: TreeItemPattern<V>) => this.treeBehavior.goto(item);
 
@@ -75,7 +72,9 @@ export class ComboboxTreePattern<V>
   first = () => this.treeBehavior.first();
 
   /** Unfocuses the currently focused item in the tree. */
-  unfocus = () => this.treeBehavior.unfocus();
+  unfocus = () => {
+    this.treeBehavior.unfocus();
+  };
 
   // TODO: handle non-selectable parent nodes.
   /** Selects the specified item in the tree or the current active item if not provided. */

src/aria/simple-combobox/BUILD.bazel

@@ -1,4 +1,4 @@
-load("//tools:defaults.bzl", "ng_project")
+load("//tools:defaults.bzl", "ng_project", "ng_web_test_suite", "ts_project")
 
 package(default_visibility = ["//visibility:public"])
 
@@ -10,7 +10,31 @@ ng_project(
     ),
     deps = [
         "//:node_modules/@angular/core",
+        "//src/aria/listbox",
         "//src/aria/private",
         "//src/cdk/bidi",
     ],
 )
+
+ts_project(
+    name = "unit_test_sources",
+    testonly = True,
+    srcs = glob(
+        ["**/*.spec.ts"],
+    ),
+    deps = [
+        ":simple-combobox",
+        "//:node_modules/@angular/common",
+        "//:node_modules/@angular/core",
+        "//:node_modules/@angular/platform-browser",
+        "//src/aria/listbox",
+        "//src/aria/tree",
+        "//src/cdk/overlay",
+        "//src/cdk/testing/private",
+    ],
+)
+
+ng_web_test_suite(
+    name = "unit_tests",
+    deps = [":unit_test_sources"],
+)