feat(cdk/tree): general bug fixes, error handling, updating examples & docs (#27305)

* feat(cdk/a11y): add some missing focus functions to TreeKeyManager, fix tests

* feat(cdk/tree): report an error when the API consumer tries to expand a non-expandable node.

* fix(cdk/tree): set node role through component host

* fix(material/tree): fix duplicate keydown events

* fix(cdk/tree): make keyboard behaviour consistent across all configurations

This also removes the need for specifying `nodeType` manually.

* fix(cdk/tree): remove unnecessary change detection

* fix(cdk/tree): update API goldens

* refactor(cdk/tree): organize imports

* fix(cdk/a11y): update API goldens

* fix(cdk/tree): remove `_preFlattenedNodes`

* fix(cdk/tree): lint

* fix(cdk/tree): use `findIndex` instead of `indexOf`; fixes inconsistent aria-posinset

* feat(cdk/tree): add complex redux-like demo

* fix(cdk/tree): refactor rendering pipeline

This also refactors the parent/level/group data processing in order to
make it significantly more consistent in all tree configurations.

* feat(cdk/tree): update tree documentation

* feat(cdk/a11y): update docs for `TreeKeyManager`.

* fix(cdk/tree): update API goldens, fix lint errors

* fix(cdk/tree): empty commit; retry ci actions

Author: BobobUnicorn

src/cdk/a11y/a11y.md

@@ -27,7 +27,7 @@ Navigation through options can be made to wrap via the `withWrap` method
 this.keyManager = new FocusKeyManager(...).withWrap();
 ```
 
-#### Types of key managers
+#### Types of list key managers
 
 There are two varieties of `ListKeyManager`, `FocusKeyManager` and `ActiveDescendantKeyManager`.
 
@@ -55,6 +55,64 @@ interface Highlightable extends ListKeyManagerOption {
 
 Each item must also have an ID bound to the listbox's or menu's `aria-activedescendant`.
 
+### TreeKeyManager
+
+`TreeKeyManager` manages the active option in a tree view. This is intended to be used with
+components that correspond to a `role="tree"` pattern.
+
+#### Basic usage
+
+Any component that uses a `TreeKeyManager` will generally do three things:
+* Create a `@ViewChildren` query for the tree items being managed.
+* Initialize the `TreeKeyManager`, passing in the options.
+* Forward keyboard events from the managed component to the `TreeKeyManager` via `onKeydown`.
+
+Each tree item should implement the `TreeKeyManagerItem` interface:
+```ts
+interface TreeKeyManagerItem {
+  /** Whether the item is disabled. */
+  isDisabled?: (() => boolean) | boolean;
+
+  /** The user-facing label for this item. */
+  getLabel?(): string;
+
+  /** Perform the main action (i.e. selection) for this item. */
+  activate(): void;
+
+  /** Retrieves the parent for this item. This is `null` if there is no parent. */
+  getParent(): TreeKeyManagerItem | null;
+
+  /** Retrieves the children for this item. */
+  getChildren(): TreeKeyManagerItem[] | Observable<TreeKeyManagerItem[]>;
+
+  /** Determines if the item is currently expanded. */
+  isExpanded: (() => boolean) | boolean;
+
+  /** Collapses the item, hiding its children. */
+  collapse(): void;
+
+  /** Expands the item, showing its children. */
+  expand(): void;
+
+  /**
+   * Focuses the item. This should provide some indication to the user that this item is focused.
+   */
+  focus(): void;
+}
+```
+
+#### Focus management
+
+The `TreeKeyManager` will handle focusing the appropriate item on keyboard interactions. However,
+the component should call `onInitialFocus` when the component is focused for the first time (i.e.
+when there is no active item).
+
+`tabindex` should also be set by the component when the active item changes. This can be listened to
+via the `change` property on the `TreeKeyManager`. In particular, the tree should only have a
+`tabindex` set if there is no active item, and should not have a `tabindex` set if there is an
+active item. Only the HTML node corresponding to the active item should have a `tabindex` set to
+`0`, with all other items set to `-1`.
+
 
 ### FocusTrap
 

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

@@ -23,6 +23,7 @@ class FakeBaseTreeKeyManagerItem {
   _children: FakeBaseTreeKeyManagerItem[] = [];
 
   isDisabled?: boolean = false;
+  skipItem?: boolean = false;
 
   constructor(private _label: string) {}
 
@@ -263,13 +264,33 @@ describe('TreeKeyManager', () => {
           expect(keyManager.getActiveItemIndex()).toBe(0);
         });
 
+        it('should focus the first non-disabled item when Home is pressed', () => {
+          itemList.get(0)!.isDisabled = true;
+          keyManager.onClick(itemList.get(2)!);
+          expect(keyManager.getActiveItemIndex()).toBe(2);
+
+          keyManager.onKeydown(fakeKeyEvents.home);
+
+          expect(keyManager.getActiveItemIndex()).toBe(1);
+        });
+
         it('should focus the last item when End is pressed', () => {
           keyManager.onClick(itemList.get(0)!);
           expect(keyManager.getActiveItemIndex()).toBe(0);
 
           keyManager.onKeydown(fakeKeyEvents.end);
           expect(keyManager.getActiveItemIndex()).toBe(itemList.length - 1);
         });
+
+        it('should focus the last non-disabled item when End is pressed', () => {
+          itemList.get(itemList.length - 1)!.isDisabled = true;
+          keyManager.onClick(itemList.get(0)!);
+          expect(keyManager.getActiveItemIndex()).toBe(0);
+
+          keyManager.onKeydown(fakeKeyEvents.end);
+
+          expect(keyManager.getActiveItemIndex()).toBe(itemList.length - 2);
+        });
       });
 
       describe('up/down key events', () => {
@@ -946,6 +967,195 @@ describe('TreeKeyManager', () => {
           expect(keyManager.getActiveItemIndex()).withContext('active item index').toBe(-1);
         }));
       });
+
+      describe('focusItem', () => {
+        beforeEach(() => {
+          keyManager.onInitialFocus();
+        });
+
+        it('should focus the provided index', () => {
+          expect(keyManager.getActiveItemIndex()).withContext('active item index').toBe(0);
+
+          keyManager.focusItem(1);
+          expect(keyManager.getActiveItemIndex()).withContext('active item index').toBe(1);
+        });
+
+        it('should be able to set the active item by reference', () => {
+          expect(keyManager.getActiveItemIndex()).withContext('active item index').toBe(0);
+
+          keyManager.focusItem(itemList.get(2)!);
+          expect(keyManager.getActiveItemIndex()).withContext('active item index').toBe(2);
+        });
+
+        it('should be able to set the active item without emitting an event', () => {
+          const spy = jasmine.createSpy('change spy');
+          const subscription = keyManager.change.subscribe(spy);
+
+          expect(keyManager.getActiveItemIndex()).toBe(0);
+
+          keyManager.focusItem(2, {emitChangeEvent: false});
+
+          expect(keyManager.getActiveItemIndex()).toBe(2);
+          expect(spy).not.toHaveBeenCalled();
+
+          subscription.unsubscribe();
+        });
+
+        it('should not emit an event if the item did not change', () => {
+          const spy = jasmine.createSpy('change spy');
+          const subscription = keyManager.change.subscribe(spy);
+
+          keyManager.focusItem(2);
+          keyManager.focusItem(2);
+
+          expect(spy).toHaveBeenCalledTimes(1);
+
+          subscription.unsubscribe();
+        });
+      });
+
+      describe('focusFirstItem', () => {
+        beforeEach(() => {
+          keyManager.onInitialFocus();
+        });
+
+        it('should focus the first item', () => {
+          keyManager.onKeydown(fakeKeyEvents.downArrow);
+          keyManager.onKeydown(fakeKeyEvents.downArrow);
+          expect(keyManager.getActiveItemIndex()).withContext('active item index').toBe(2);
+
+          keyManager.focusFirstItem();
+          expect(keyManager.getActiveItemIndex()).withContext('active item index').toBe(0);
+        });
+
+        it('should set the active item to the second item if the first one is disabled', () => {
+          itemList.get(0)!.isDisabled = true;
+
+          keyManager.focusFirstItem();
+          expect(keyManager.getActiveItemIndex()).withContext('active item index').toBe(1);
+        });
+      });
+
+      describe('focusLastItem', () => {
+        beforeEach(() => {
+          keyManager.onInitialFocus();
+        });
+
+        it('should focus the last item', () => {
+          expect(keyManager.getActiveItemIndex()).withContext('active item index').toBe(0);
+
+          keyManager.focusLastItem();
+          expect(keyManager.getActiveItemIndex())
+            .withContext('active item index')
+            .toBe(itemList.length - 1);
+        });
+
+        it('should set the active item to the second-to-last item if the last is disabled', () => {
+          itemList.get(itemList.length - 1)!.isDisabled = true;
+
+          keyManager.focusLastItem();
+          expect(keyManager.getActiveItemIndex())
+            .withContext('active item index')
+            .toBe(itemList.length - 2);
+        });
+      });
+
+      describe('focusNextItem', () => {
+        beforeEach(() => {
+          keyManager.onInitialFocus();
+        });
+
+        it('should focus the next item', () => {
+          expect(keyManager.getActiveItemIndex()).withContext('active item index').toBe(0);
+
+          keyManager.focusNextItem();
+          expect(keyManager.getActiveItemIndex()).withContext('active item index').toBe(1);
+        });
+
+        it('should skip disabled items', () => {
+          itemList.get(1)!.isDisabled = true;
+
+          keyManager.focusNextItem();
+          expect(keyManager.getActiveItemIndex()).withContext('active item index').toBe(2);
+        });
+      });
+
+      describe('focusPreviousItem', () => {
+        beforeEach(() => {
+          keyManager.onInitialFocus();
+        });
+
+        it('should focus the previous item', () => {
+          keyManager.onKeydown(fakeKeyEvents.downArrow);
+          expect(keyManager.getActiveItemIndex()).withContext('active item index').toBe(1);
+
+          keyManager.focusPreviousItem();
+          expect(keyManager.getActiveItemIndex()).withContext('active item index').toBe(0);
+        });
+
+        it('should skip disabled items', () => {
+          itemList.get(1)!.isDisabled = true;
+          keyManager.onKeydown(fakeKeyEvents.downArrow);
+          expect(keyManager.getActiveItemIndex()).withContext('active item index').toBe(2);
+
+          keyManager.focusPreviousItem();
+          expect(keyManager.getActiveItemIndex()).withContext('active item index').toBe(0);
+        });
+      });
+
+      describe('skip predicate', () => {
+        beforeEach(() => {
+          keyManager = new TreeKeyManager({
+            items: itemList,
+            skipPredicate: item => item.skipItem ?? false,
+          });
+          keyManager.onInitialFocus();
+        });
+
+        it('should be able to skip items with a custom predicate', () => {
+          itemList.get(1)!.skipItem = true;
+          expect(keyManager.getActiveItemIndex()).toBe(0);
+
+          keyManager.onKeydown(fakeKeyEvents.downArrow);
+
+          expect(keyManager.getActiveItemIndex()).toBe(2);
+        });
+      });
+
+      describe('focus', () => {
+        beforeEach(() => {
+          keyManager.onInitialFocus();
+
+          for (const item of itemList) {
+            spyOn(item, 'focus');
+          }
+        });
+
+        it('calls .focus() on focused items', () => {
+          keyManager.onKeydown(fakeKeyEvents.downArrow);
+
+          expect(itemList.get(0)!.focus).not.toHaveBeenCalled();
+          expect(itemList.get(1)!.focus).toHaveBeenCalledTimes(1);
+          expect(itemList.get(2)!.focus).not.toHaveBeenCalled();
+
+          keyManager.onKeydown(fakeKeyEvents.downArrow);
+          expect(itemList.get(0)!.focus).not.toHaveBeenCalled();
+          expect(itemList.get(1)!.focus).toHaveBeenCalledTimes(1);
+          expect(itemList.get(2)!.focus).toHaveBeenCalledTimes(1);
+        });
+
+        it('calls .focus() on focused items, when pressing up key', () => {
+          keyManager.onKeydown(fakeKeyEvents.downArrow);
+
+          expect(itemList.get(0)!.focus).not.toHaveBeenCalled();
+          expect(itemList.get(1)!.focus).toHaveBeenCalledTimes(1);
+
+          keyManager.onKeydown(fakeKeyEvents.upArrow);
+
+          expect(itemList.get(0)!.focus).toHaveBeenCalledTimes(1);
+          expect(itemList.get(1)!.focus).toHaveBeenCalledTimes(1);
+        });
+      });
     });
   }
 });

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

@@ -66,6 +66,9 @@ export interface TreeKeyManagerItem {
   focus(): void;
 }
 
+/**
+ * Configuration for the TreeKeyManager.
+ */
 export interface TreeKeyManagerOptions<T extends TreeKeyManagerItem> {
   items: Observable<T[]> | QueryList<T> | T[];
 
@@ -284,9 +287,49 @@ export class TreeKeyManager<T extends TreeKeyManagerItem> {
     this._focusFirstItem();
   }
 
-  private _setActiveItem(index: number): void;
-  private _setActiveItem(item: T): void;
-  private _setActiveItem(itemOrIndex: number | T) {
+  /**
+   * Focus the provided item by index.
+   * @param index The index of the item to focus.
+   * @param options Additional focusing options.
+   */
+  focusItem(index: number, options?: {emitChangeEvent?: boolean}): void;
+  /**
+   * Focus the provided item.
+   * @param item The item to focus. Equality is determined via the trackBy function.
+   * @param options Additional focusing options.
+   */
+  focusItem(item: T, options?: {emitChangeEvent?: boolean}): void;
+  focusItem(itemOrIndex: number | T, options?: {emitChangeEvent?: boolean}): void {
+    this._setActiveItem(itemOrIndex, options);
+  }
+
+  /** Focus the first available item. */
+  focusFirstItem(): void {
+    this._focusFirstItem();
+  }
+
+  /** Focus the last available item. */
+  focusLastItem(): void {
+    this._focusLastItem();
+  }
+
+  /** Focus the next available item. */
+  focusNextItem(): void {
+    this._focusNextItem();
+  }
+
+  /** Focus the previous available item. */
+  focusPreviousItem(): void {
+    this._focusPreviousItem();
+  }
+
+  private _setActiveItem(index: number, options?: {emitChangeEvent?: boolean}): void;
+  private _setActiveItem(item: T, options?: {emitChangeEvent?: boolean}): void;
+  private _setActiveItem(itemOrIndex: number | T, options?: {emitChangeEvent?: boolean}): void;
+  private _setActiveItem(itemOrIndex: number | T, options: {emitChangeEvent?: boolean} = {}) {
+    // Set default options
+    options.emitChangeEvent ??= true;
+
     let index =
       typeof itemOrIndex === 'number'
         ? itemOrIndex
@@ -307,16 +350,21 @@ export class TreeKeyManager<T extends TreeKeyManagerItem> {
     this._activeItem = activeItem ?? null;
     this._activeItemIndex = index;
 
-    this.change.next(this._activeItem);
+    if (options.emitChangeEvent) {
+      this.change.next(this._activeItem);
+    }
     this._activeItem?.focus();
     if (this._activationFollowsFocus) {
       this._activateCurrentItem();
     }
   }
 
   private _updateActiveItemIndex(newItems: T[]) {
-    if (this._activeItem) {
-      const newIndex = newItems.indexOf(this._activeItem);
+    const activeItem = this._activeItem;
+    if (activeItem) {
+      const newIndex = newItems.findIndex(
+        item => this._trackByFn(item) === this._trackByFn(activeItem),
+      );
 
       if (newIndex > -1 && newIndex !== this._activeItemIndex) {
         this._activeItemIndex = newIndex;