feat(a11y): Add optional home/end key support to ListKeyManager (#19834)

For some components like menus and listboxes, WAI a11y recommends
that pressing home or end should focus the first or last element
respectively. Add support for home/end to ListKeyManager.

Author: vanessanschmitt

src/cdk/a11y/key-manager/list-key-manager.spec.ts

@@ -1,4 +1,4 @@
-import {DOWN_ARROW, LEFT_ARROW, RIGHT_ARROW, TAB, UP_ARROW} from '@angular/cdk/keycodes';
+import {DOWN_ARROW, END, HOME, LEFT_ARROW, RIGHT_ARROW, TAB, UP_ARROW} from '@angular/cdk/keycodes';
 import {createKeyboardEvent} from '@angular/cdk/testing/private';
 import {QueryList} from '@angular/core';
 import {fakeAsync, tick} from '@angular/core/testing';
@@ -51,6 +51,8 @@ describe('Key managers', () => {
     leftArrow: KeyboardEvent,
     rightArrow: KeyboardEvent,
     tab: KeyboardEvent,
+    home: KeyboardEvent,
+    end: KeyboardEvent,
     unsupported: KeyboardEvent
   };
 
@@ -62,6 +64,8 @@ describe('Key managers', () => {
       leftArrow: createKeyboardEvent('keydown', LEFT_ARROW),
       rightArrow: createKeyboardEvent('keydown', RIGHT_ARROW),
       tab: createKeyboardEvent('keydown', TAB),
+      home: createKeyboardEvent('keydown', HOME),
+      end: createKeyboardEvent('keydown', END),
       unsupported: createKeyboardEvent('keydown', 192) // corresponds to the tilde character (~)
     };
   });
@@ -207,6 +211,30 @@ describe('Key managers', () => {
         expect(fakeKeyEvents.downArrow.defaultPrevented).toBe(false);
       });
 
+      describe('withHomeAndEnd', () => {
+        beforeEach(() => {
+          keyManager.withHomeAndEnd();
+        });
+
+        it('should focus the first item when Home is pressed', () => {
+          keyManager.setActiveItem(1);
+          expect(keyManager.activeItemIndex).toBe(1);
+
+          keyManager.onKeydown(fakeKeyEvents.home);
+
+          expect(keyManager.activeItemIndex).toBe(0);
+        });
+
+        it('should focus the last item when End is pressed', () => {
+          keyManager.setActiveItem(0);
+          expect(keyManager.activeItemIndex).toBe(0);
+
+          keyManager.onKeydown(fakeKeyEvents.end);
+
+          expect(keyManager.activeItemIndex).toBe(itemList.items.length - 1);
+        });
+      });
+
       describe('with `vertical` direction', function(this: KeyEventTestContext) {
         beforeEach(() => {
           keyManager.withVerticalOrientation();

src/cdk/a11y/key-manager/list-key-manager.ts

@@ -19,6 +19,8 @@ import {
   ZERO,
   NINE,
   hasModifierKey,
+  HOME,
+  END,
 } from '@angular/cdk/keycodes';
 import {debounceTime, filter, map, tap} from 'rxjs/operators';
 
@@ -47,6 +49,7 @@ export class ListKeyManager<T extends ListKeyManagerOption> {
   private _vertical = true;
   private _horizontal: 'ltr' | 'rtl' | null;
   private _allowedModifierKeys: ListKeyManagerModifierKey[] = [];
+  private _homeAndEnd = false;
 
   /**
    * Predicate function that can be used to check whether an item should be skipped
@@ -174,6 +177,15 @@ export class ListKeyManager<T extends ListKeyManagerOption> {
     return this;
   }
 
+  /**
+   * Configures the key manager to focus the first and last items
+   * respectively when the Home key and End Key are pressed.
+   */
+  withHomeAndEnd(): this {
+    this._homeAndEnd = true;
+    return this;
+  }
+
   /**
    * Sets the active item to the item at the index specified.
    * @param index The index of the item to be set as active.
@@ -244,6 +256,22 @@ export class ListKeyManager<T extends ListKeyManagerOption> {
           return;
         }
 
+      case HOME:
+        if (this._homeAndEnd && isModifierAllowed) {
+          this.setFirstItemActive();
+          break;
+        } else {
+          return;
+        }
+
+      case END:
+        if (this._homeAndEnd && isModifierAllowed) {
+          this.setLastItemActive();
+          break;
+        } else {
+          return;
+        }
+
       default:
       if (isModifierAllowed || hasModifierKey(event, 'shiftKey')) {
           // Attempt to use the `event.key` which also maps it to the user's keyboard language,

tools/public_api_guard/cdk/a11y.d.ts

@@ -213,6 +213,7 @@ export declare class ListKeyManager<T extends ListKeyManagerOption> {
     updateActiveItem(index: number): void;
     updateActiveItem(item: T): void;
     withAllowedModifierKeys(keys: ListKeyManagerModifierKey[]): this;
+    withHomeAndEnd(): this;
     withHorizontalOrientation(direction: 'ltr' | 'rtl' | null): this;
     withTypeAhead(debounceInterval?: number): this;
     withVerticalOrientation(enabled?: boolean): this;