fixup! feat(cdk-experimental/ui-patterns): listbox ui pattern

Author: wagnermaciel

src/cdk-experimental/listbox/listbox.ts

@@ -23,25 +23,40 @@ import {Directionality} from '@angular/cdk/bidi';
 import {startWith, takeUntil} from 'rxjs/operators';
 import {Subject} from 'rxjs';
 
+/**
+ * A listbox container.
+ *
+ * Listboxes are used to display a list of items for a user to select from. The CdkListbox is meant
+ * to be used in conjunction with CdkOption as follows:
+ *
+ * ```html
+ * <ul cdkListbox>
+ *   <li cdkOption>Item 1</li>
+ *   <li cdkOption>Item 2</li>
+ *   <li cdkOption>Item 3</li>
+ * </ul>
+ * ```
+ */
 @Directive({
   selector: '[cdkListbox]',
   exportAs: 'cdkListbox',
   host: {
     'role': 'listbox',
     'class': 'cdk-listbox',
     '[attr.tabindex]': 'state.tabindex()',
-    // '[attr.aria-disabled]': 'state.disabled()',
+    '[attr.aria-disabled]': 'state.disabled()',
     '[attr.aria-multiselectable]': 'state.multiselectable()',
     '[attr.aria-activedescendant]': 'state.activedescendant()',
     '[attr.aria-orientation]': 'state.orientation()',
     '(focusin)': 'state.onFocus()',
     '(keydown)': 'state.onKeydown($event)',
     '(mousedown)': 'state.onMousedown($event)',
-    // '(focusout)': '_handleFocusOut($event)',
-    // '(focusin)': '_handleFocusIn()',
   },
 })
 export class CdkListbox implements ListboxInputs, OnDestroy {
+  /** The directionality (LTR / RTL) context for the application (or a subtree of it). */
+  private _dir = inject(Directionality);
+
   /** Whether the list is vertically or horizontally oriented. */
   orientation = input<'vertical' | 'horizontal'>('vertical');
 
@@ -55,13 +70,13 @@ export class CdkListbox implements ListboxInputs, OnDestroy {
   skipDisabled = input<boolean>(true);
 
   /** The focus strategy used by the list. */
-  focusStrategy = input<'roving tabindex' | 'activedescendant'>('roving tabindex');
+  focusMode = input<'roving' | 'activedescendant'>('roving');
 
   /** The selection strategy used by the list. */
-  selectionStrategy = input<'follow' | 'explicit'>('follow');
+  selectionMode = input<'follow' | 'explicit'>('follow');
 
   /** The amount of time before the typeahead search is reset. */
-  delay = input<number>(0.5);
+  delay = input<number>(0.5); // Picked arbitrarily.
 
   /** The ids of the current selected items. */
   selectedIds = model<string[]>([]);
@@ -75,15 +90,15 @@ export class CdkListbox implements ListboxInputs, OnDestroy {
   /** The Option UIPatterns of the child CdkOptions. */
   items = computed(() => this._cdkOptions().map(option => option.state));
 
-  /** The directionality (LTR / RTL) context for the application (or a subtree of it). */
-  private _dir = inject(Directionality);
-
   /** A signal wrapper for directionality. */
-  directionality = signal<'rtl' | 'ltr'>('rtl');
+  directionality = signal<'ltr' | 'rtl'>('ltr');
 
   /** Emits when the list has been destroyed. */
   private readonly _destroyed = new Subject<void>();
 
+  /** Whether the listbox is disabled. */
+  disabled = input<boolean>(false);
+
   /** The Listbox UIPattern. */
   state: ListboxPattern = new ListboxPattern(this);
 
@@ -98,6 +113,7 @@ export class CdkListbox implements ListboxInputs, OnDestroy {
   }
 }
 
+/** A selectable option in a CdkListbox. */
 @Directive({
   selector: '[cdkOption]',
   exportAs: 'cdkOption',
@@ -107,12 +123,15 @@ export class CdkListbox implements ListboxInputs, OnDestroy {
     '[attr.aria-selected]': 'state.selected()',
     '[attr.tabindex]': 'state.tabindex()',
     '[attr.aria-disabled]': 'state.disabled()',
-    // '[class.cdk-option-active]': 'isActive()',
-    // '(click)': '_clicked.next($event)',
-    // '(focus)': '_handleFocus()',
   },
 })
 export class CdkOption {
+  /** A reference to the option element. */
+  private _elementRef = inject(ElementRef);
+
+  /** The parent CdkListbox. */
+  private _cdkListbox = inject(CdkListbox);
+
   /** Whether an item is disabled. */
   disabled = input<boolean>(false);
 
@@ -123,13 +142,8 @@ export class CdkOption {
   searchTerm = computed(() => this.label() ?? this.element().textContent);
 
   /** A reference to the option element. */
-  private _elementRef = inject(ElementRef);
-
   element = computed(() => this._elementRef.nativeElement);
 
-  /** The parent CdkListbox. */
-  private _cdkListbox = inject(CdkListbox);
-
   /** The parent Listbox UIPattern. */
   listbox = computed(() => this._cdkListbox.state);
 

src/cdk-experimental/ui-patterns/behaviors/event-manager/event-manager.ts

@@ -8,6 +8,8 @@
 
 /**
  * An event that supports modifier keys.
+ *
+ * Matches the native KeyboardEvent, MouseEvent, and TouchEvent.
  */
 export interface EventWithModifiers extends Event {
   ctrlKey: boolean;
@@ -18,6 +20,8 @@ export interface EventWithModifiers extends Event {
 
 /**
  * Options that are applicable to all event handlers.
+ *
+ * This library has not yet had a need for stopPropagationImmediate.
  */
 export interface EventHandlerOptions {
   stopPropagation: boolean;
@@ -44,6 +48,9 @@ export enum ModifierKey {
 
 /**
  * Abstract base class for all event managers.
+ *
+ * Event managers are designed to normalize how event handlers are authored and create a safety net
+ * for common event handling gotchas like remembering to call preventDefault or stopPropagation.
  */
 export abstract class EventManager<T extends Event> {
   private _submanagers: EventManager<T>[] = [];

src/cdk-experimental/ui-patterns/behaviors/list-focus/controller.ts

@@ -14,7 +14,7 @@ export class ListFocusController<T extends ListFocusItem> {
 
   /** Focuses the current active item. */
   focus() {
-    if (this.state.inputs.focusStrategy() === 'activedescendant') {
+    if (this.state.inputs.focusMode() === 'activedescendant') {
       return;
     }
 

src/cdk-experimental/ui-patterns/behaviors/list-focus/list-focus.spec.ts

@@ -48,12 +48,12 @@ describe('List Focus', () => {
   ): ListFocus<T> {
     return new ListFocus({
       navigation,
-      focusStrategy: signal('roving tabindex'),
+      focusMode: signal('roving'),
       ...args,
     });
   }
 
-  describe('roving tabindex', () => {
+  describe('roving', () => {
     it('should set the list tabindex to -1', () => {
       const items = getItems(5);
       const nav = getNavigation(items);
@@ -110,7 +110,7 @@ describe('List Focus', () => {
       const items = getItems(5);
       const nav = getNavigation(items);
       const focus = getFocus(nav, {
-        focusStrategy: signal('activedescendant'),
+        focusMode: signal('activedescendant'),
       });
       const tabindex = focus.getListTabindex();
       expect(tabindex()).toBe(0);
@@ -120,7 +120,7 @@ describe('List Focus', () => {
       const items = getItems(5);
       const nav = getNavigation(items);
       const focus = getFocus(nav, {
-        focusStrategy: signal('activedescendant'),
+        focusMode: signal('activedescendant'),
       });
       const activeId = focus.getActiveDescendant();
       expect(activeId()).toBe(items()[0].id());
@@ -130,7 +130,7 @@ describe('List Focus', () => {
       const items = getItems(5);
       const nav = getNavigation(items);
       const focus = getFocus(nav, {
-        focusStrategy: signal('activedescendant'),
+        focusMode: signal('activedescendant'),
       });
 
       items().forEach(i => {
@@ -148,7 +148,7 @@ describe('List Focus', () => {
       const items = getItems(5);
       const nav = getNavigation(items);
       const focus = getFocus(nav, {
-        focusStrategy: signal('activedescendant'),
+        focusMode: signal('activedescendant'),
       });
       const activeId = focus.getActiveDescendant();
 

src/cdk-experimental/ui-patterns/behaviors/list-focus/list-focus.ts

@@ -22,7 +22,7 @@ export interface ListFocusItem extends ListNavigationItem {
 /** The required inputs for list focus. */
 export interface ListFocusInputs<T extends ListFocusItem> {
   /** The focus strategy used by the list. */
-  focusStrategy: Signal<'roving tabindex' | 'activedescendant'>;
+  focusMode: Signal<'roving' | 'activedescendant'>;
 }
 
 /** Controls focus for a list of items. */
@@ -53,7 +53,7 @@ export class ListFocus<T extends ListFocusItem> {
   /** Returns the id of the current active item. */
   getActiveDescendant(): Signal<string | null> {
     return computed(() => {
-      if (this.inputs.focusStrategy() === 'roving tabindex') {
+      if (this.inputs.focusMode() === 'roving') {
         return null;
       }
       return this.navigation.inputs.items()[this.navigation.inputs.activeIndex()].id();
@@ -62,13 +62,13 @@ export class ListFocus<T extends ListFocusItem> {
 
   /** Returns a signal that keeps track of the tabindex for the list. */
   getListTabindex(): Signal<-1 | 0> {
-    return computed(() => (this.inputs.focusStrategy() === 'activedescendant' ? 0 : -1));
+    return computed(() => (this.inputs.focusMode() === 'activedescendant' ? 0 : -1));
   }
 
   /** Returns a signal that keeps track of the tabindex for the given item. */
   getItemTabindex(item: T): Signal<-1 | 0> {
     return computed(() => {
-      if (this.inputs.focusStrategy() === 'activedescendant') {
+      if (this.inputs.focusMode() === 'activedescendant') {
         return -1;
       }
       const index = this.navigation.inputs.items().indexOf(item);

src/cdk-experimental/ui-patterns/behaviors/list-selection/list-selection.spec.ts

@@ -51,7 +51,7 @@ describe('List Selection', () => {
       navigation,
       selectedIds: signal([]),
       multiselectable: signal(true),
-      selectionStrategy: signal('explicit'),
+      selectionMode: signal('explicit'),
       ...args,
     });
   }

src/cdk-experimental/ui-patterns/behaviors/list-selection/list-selection.ts

@@ -31,7 +31,7 @@ export interface ListSelectionInputs<T extends ListSelectionItem> {
   selectedIds: WritableSignal<string[]>;
 
   /** The selection strategy used by the list. */
-  selectionStrategy: Signal<'follow' | 'explicit'>;
+  selectionMode: Signal<'follow' | 'explicit'>;
 }
 
 /** Controls selection for a list of items. */

src/cdk-experimental/ui-patterns/listbox/controller.ts

@@ -25,7 +25,7 @@ interface SelectOptions {
 
 /** Controls selection for a list of items. */
 export class ListboxController {
-  followFocus = computed(() => this.state.inputs.selectionStrategy() === 'follow');
+  followFocus = computed(() => this.state.inputs.selectionMode() === 'follow');
 
   /** The key used to navigate to the previous item in the list. */
   prevKey = computed(() => {
@@ -124,11 +124,15 @@ export class ListboxController {
 
   /** Handles keydown events for the listbox. */
   onKeydown(event: KeyboardEvent) {
-    this.keydown().handle(event);
+    if (!this.state.disabled()) {
+      this.keydown().handle(event);
+    }
   }
 
   onMousedown(event: MouseEvent) {
-    this.mousedown().handle(event);
+    if (!this.state.disabled()) {
+      this.mousedown().handle(event);
+    }
   }
 
   /** Navigates to the first option in the listbox. */

src/cdk-experimental/ui-patterns/listbox/listbox.ts

@@ -18,7 +18,9 @@ import {ListboxController} from './controller';
 export type ListboxInputs = ListNavigationInputs<OptionPattern> &
   ListSelectionInputs<OptionPattern> &
   ListTypeaheadInputs &
-  ListFocusInputs<OptionPattern>;
+  ListFocusInputs<OptionPattern> & {
+    disabled: Signal<boolean>;
+  };
 
 /** Controls the state of a listbox. */
 export class ListboxPattern {
@@ -37,6 +39,9 @@ export class ListboxPattern {
   /** Whether the list is vertically or horizontally oriented. */
   orientation: Signal<'vertical' | 'horizontal'>;
 
+  /** Whether the listbox is disabled. */
+  disabled: Signal<boolean>;
+
   /** The tabindex of the listbox. */
   tabindex: Signal<-1 | 0>;
 
@@ -58,6 +63,7 @@ export class ListboxPattern {
   private _controller: ListboxController | null = null;
 
   constructor(readonly inputs: ListboxInputs) {
+    this.disabled = inputs.disabled;
     this.orientation = inputs.orientation;
     this.multiselectable = inputs.multiselectable;
 

src/components-examples/cdk-experimental/listbox/cdk-listbox/cdk-listbox-example.html

@@ -1,6 +1,7 @@
 <div class="example-listbox-controls">
   <mat-checkbox [formControl]="wrap">Wrap</mat-checkbox>
   <mat-checkbox [formControl]="multi">Multi</mat-checkbox>
+  <mat-checkbox [formControl]="disabled">Disabled</mat-checkbox>
   <mat-checkbox [formControl]="skipDisabled">Skip Disabled</mat-checkbox>
 
   <mat-form-field subscriptSizing="dynamic" appearance="outline">
@@ -13,15 +14,15 @@
 
   <mat-form-field subscriptSizing="dynamic" appearance="outline">
     <mat-label>Selection strategy</mat-label>
-    <mat-select [(value)]="selectionStrategy">
+    <mat-select [(value)]="selectionMode">
       <mat-option value="explicit">Explicit</mat-option>
       <mat-option value="follow">Follow Focus</mat-option>
     </mat-select>
   </mat-form-field>
 
   <mat-form-field subscriptSizing="dynamic" appearance="outline">
     <mat-label>Focus strategy</mat-label>
-    <mat-select [(value)]="focusStrategy">
+    <mat-select [(value)]="focusMode">
       <mat-option value="roving tabindex">Roving Tabindex</mat-option>
       <mat-option value="activedescendant">Active Descendant</mat-option>
     </mat-select>
@@ -32,11 +33,12 @@
 <ul
   cdkListbox
   [wrap]="wrap.value"
+  [disabled]="disabled.value"
   [multiselectable]="multi.value"
   [skipDisabled]="skipDisabled.value"
   [orientation]="orientation"
-  [focusStrategy]="focusStrategy"
-  [selectionStrategy]="selectionStrategy"
+  [focusMode]="focusMode"
+  [selectionMode]="selectionMode"
 >
   <label id="fruit-example-label">List of Fruits</label>