fix(material/tree): add levelAccessor, childrenAccessor, TreeKeyManager; a11y and docs improvements (#29062)

Update multiple facets of Tree component. Add APIs to manage data models, improve existing behaviors, add keyboard functionality and update documentation.

Add APIs options to the Tree data model by introducing levelAccessor and childrenAccessor. See “Api Addition” for usage. Currently, Tree component use TreeControl to manage data model. When applied, add levelAccessor and childrenAccessor functions as alternatives to TreeControl.

Add TreeKeyManager, which provides keyboard functionality. Currently Tree component allows developers to manage focus by setting tabindex on each tree node. When applied, Tree manages its own focus using key manager pattern. Keyboard commands match [WAI ARIA Tree View Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/treeview/). See “Deprecated” for adopting changes to existing applications.

Correct the ARIA semantics of Tree and Tree node components.

Document updated APIs and behaviors. Refine documentation of existing APIs and behaviors.

Changes to Cdk Tree API also apply to Mat Tree API. See “Deprecated” for adopting changes to existing applications.

Accessibility:
 * add CdkTreeKeyManager to provide keyboard navigation for CdkTree and MatTree
 * Improve keyboard usability of CdkTreeNodeToggle.
 * Improve ARIA semantics of CdkTree, CdkTreeNode, Tree and TreeNode components
 * Fix miscellaneous accessibility issues in tree and cdk-tree examples
 * Add accessibility instructions to documentation

Documentation:
 * Add API and usage examples for TreeKeyManager
 * Update @angular/cdk/tree and @angular/material/tree to be more consistent
 * Update examples to use levelAccessor and childrenAccessor
 * Add example for (activation) on MatTreeNode and CdkTreeNode

API ADDITION: add CdkTree#childrenAccessor and CdkTree#levelAccessor
 * Add CdkTree#childrenAccessor. Given a data node, childrenAccessor determines the children of that node.
 * Add CdkTree#levelAccessor. Given a data node, levelAccessor determines the level of the node in the parent hierarchy.
 * CdkTreeNode#levelAcessor and CdkTreeNode#childrenAccessor replace CdkTreeNode#treeControl.

See “Deprecated” for updating apps using treeControl.

API ADDITION: control expanded state of tree nodes using isExpandable and isExpanded
 * Add CdkTreeNode#isExpandable, determines if argument tree node can be expanded or collapsed.
 * CdkTreeNode#isExpanded to specify the expanded state. Has no effect if node is not expandable.
 * Add NestedTreeControlOptions#isExpandable function, determines if argument tree node can be expanded or collapsed.

For trees using treeControl, recommend providing isExpandable if not already provided. See “Deprecated” for more information on updating applications.

API ADDITION: use CdkTree to manage expansion state
 * Add CdkTree#isExpanded method.
 * Add CdkTree#toggle, CdkTree#expand and CdkTree#collapse methods.
 * Add  CdkTree#toggleDescendants, CdkTree#expandDescendants, and CdkTree#collapseDescendants methods to CdkTree
 * Add CdkTree#expandAll and CdkTree#collapseAll methods
 * Add expandedChange Output to CdkTreeNode

API ADDITION: add injection token for tree-key-manager
 * Add TREE_KEY_MANAGER injection token. When provided, tree uses given key manager
 * TreeKeyManagerStrategy interface, which defines API contract of TREE_KEY_MANAGER

API ADDITION: add CdkTreeNode#cdkTreeNodeTypeaheadLabel and CdkTreeNode#getLabel
 * Add CdkTree#cdkTreeNodeTypeaheadLabel. This is an Input that specifies the label used for typeahead
 * Add CdkTree#getLabel. Gets the typeahead label for this node.

BEHAVIOR CHANGE: MatTree and CdkTree components respond to keyboard navigation.
 * CdkTree and MatTree respond to arrow keys, page up, page down, etc.; Keyboard commands match [WAI ARIA Tree View Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/treeview/).
 * Can no longer set the tabindex on MatTreeNode. See “Deprecated” for adopting existing applications.
 * Add TreeKeyManager to cdk/a11y

DEPRECATED: Tree controller deprecated. Use one of levelAccessor or childrenAccessor instead. To be removed in a future version.
 * BaseTreeControl, TreeControl, FlatTreeControl, and NestedTreeControl deprecated
 * CdkTree#treeControl deprecated. Provide one of CdkTree#levelAccessor or CdkTree#childrenAccessor instead.
 * MatTreeFlattener deprecated. Use MatTree#childrenAccessor and MatTreeNode#isExpandable instead.
 * MatTreeFlatDataSource deprecated. Use one of levelAccessor or childrenAccessor instead of TreeControl.

Note when upgrading: isExpandable works differently on Trees using treeControl than trees using childrenAccessor or levelAccessor. Nodes on trees that have a treeControl are expandable by default. Nodes on trees using childrenAccessor or levelAccessor are *not* expandable by default. Provide isExpandable to override default behavior.

DEPRECATED: Setting tabindex of tree nodes deprecated. By default, Tree ignores tabindex passed to tree nodes.
 * MatTreeNode#tabIndex deprecated. MatTreeNode ignores Input tabIndex and manages its own focus behavior.
 * MatTreeNode#defaultTabIndex deprecated. MatTreeNode ignores defaultTabIndex and manages its own focus behavior.
 * MatNestedTreeNode#tabIndex deprecated. MatTreeNode ignores Input defaultTabIndex and manages its own focus behavior.
 * LegacyTreeKeyManager and LEGACY_TREE_KEY_MANAGER_FACTORY_PROVIDER deprecated. Inject a TreeKeyManagerFactory to customize keyboard behavior.

Note when upgrading: an opt-out is available for keyboard functionality changes. Provide LEGACY_TREE_KEY_MANAGER_FACTORY_PROVIDER to opt-out of Tree managing its own focus. When provided, Tree does not manage it’s own focus and respects tabindex passed to TreeNode. When provided, have the same focus behavior as before this commit is applied.

Add Legacy Keyboard Interface demo, which shows usage of LEGACY_TREE_KEY_MANAGER_FACTORY_PROVIDER. Add Custom Key Manager, which shows usage of injecting a TreeKeyManagerStrategy

DEPRECATED: disabled renamed to isDisabled.
 * CdkTreeNode#disabled deprecated and alias to CdkTreeNode#isDisabled

Author: BobobUnicorn

src/cdk/a11y/BUILD.bazel

@@ -19,6 +19,7 @@ ng_module(
     deps = [
         "//src:dev_mode_types",
         "//src/cdk/coercion",
+        "//src/cdk/coercion/private",
         "//src/cdk/keycodes",
         "//src/cdk/layout",
         "//src/cdk/observers",

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,30 @@ 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. Use this key manager for
+components that implement a `role="tree"` pattern.
+
+#### Basic usage
+
+Any component that uses a `TreeKeyManager` should 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`](/cdk/a11y/api#TreeKeyManagerItem) interface.
+
+#### Focus management
+
+The `TreeKeyManager` will handle focusing the appropriate item on keyboard interactions.
+
+`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/list-key-manager.spec.ts

@@ -177,6 +177,7 @@ describe('Key managers', () => {
 
         keyManager.setActiveItem(0);
         itemList.reset([new FakeFocusable('zero'), ...itemList.toArray()]);
+        itemList.notifyOnChanges();
         keyManager.setActiveItem(0);
 
         expect(spy).toHaveBeenCalledTimes(1);
@@ -369,6 +370,7 @@ describe('Key managers', () => {
           const items = itemList.toArray();
           items[1].disabled = true;
           itemList.reset(items);
+          itemList.notifyOnChanges();
 
           // Next event should skip past disabled item from 0 to 2
           keyManager.onKeydown(this.nextKeyEvent);
@@ -394,6 +396,7 @@ describe('Key managers', () => {
           items[1].disabled = undefined;
           items[2].disabled = undefined;
           itemList.reset(items);
+          itemList.notifyOnChanges();
 
           keyManager.onKeydown(this.nextKeyEvent);
           expect(keyManager.activeItemIndex)
@@ -443,6 +446,7 @@ describe('Key managers', () => {
           const items = itemList.toArray();
           items[2].disabled = true;
           itemList.reset(items);
+          itemList.notifyOnChanges();
 
           keyManager.onKeydown(this.nextKeyEvent);
           expect(keyManager.activeItemIndex)
@@ -585,6 +589,7 @@ describe('Key managers', () => {
         const items = itemList.toArray();
         items[0].disabled = true;
         itemList.reset(items);
+        itemList.notifyOnChanges();
 
         keyManager.setFirstItemActive();
         expect(keyManager.activeItemIndex)
@@ -607,6 +612,7 @@ describe('Key managers', () => {
         const items = itemList.toArray();
         items[2].disabled = true;
         itemList.reset(items);
+        itemList.notifyOnChanges();
 
         keyManager.setLastItemActive();
         expect(keyManager.activeItemIndex)
@@ -629,6 +635,7 @@ describe('Key managers', () => {
         const items = itemList.toArray();
         items[1].disabled = true;
         itemList.reset(items);
+        itemList.notifyOnChanges();
 
         expect(keyManager.activeItemIndex)
           .withContext(`Expected first item of the list to be active.`)
@@ -656,6 +663,7 @@ describe('Key managers', () => {
         const items = itemList.toArray();
         items[1].disabled = true;
         itemList.reset(items);
+        itemList.notifyOnChanges();
 
         keyManager.onKeydown(fakeKeyEvents.downArrow);
         keyManager.onKeydown(fakeKeyEvents.downArrow);
@@ -733,6 +741,7 @@ describe('Key managers', () => {
         const items = itemList.toArray();
         items.forEach(item => (item.disabled = true));
         itemList.reset(items);
+        itemList.notifyOnChanges();
 
         keyManager.onKeydown(fakeKeyEvents.downArrow);
       });
@@ -757,6 +766,7 @@ describe('Key managers', () => {
         const items = itemList.toArray();
         items[1].disabled = true;
         itemList.reset(items);
+        itemList.notifyOnChanges();
 
         expect(keyManager.activeItemIndex).toBe(0);
 
@@ -771,6 +781,7 @@ describe('Key managers', () => {
         const items = itemList.toArray();
         items[1].skipItem = true;
         itemList.reset(items);
+        itemList.notifyOnChanges();
 
         expect(keyManager.activeItemIndex).toBe(0);
 
@@ -866,6 +877,7 @@ describe('Key managers', () => {
           new FakeFocusable('две'),
           new FakeFocusable('три'),
         ]);
+        itemList.notifyOnChanges();
 
         const keyboardEvent = createKeyboardEvent('keydown', 68, 'д');
 
@@ -881,6 +893,7 @@ describe('Key managers', () => {
           new FakeFocusable('321'),
           new FakeFocusable('`!?'),
         ]);
+        itemList.notifyOnChanges();
 
         keyManager.onKeydown(createKeyboardEvent('keydown', 192, '`')); // types "`"
         tick(debounceInterval);
@@ -901,6 +914,7 @@ describe('Key managers', () => {
         const items = itemList.toArray();
         items[0].disabled = true;
         itemList.reset(items);
+        itemList.notifyOnChanges();
 
         keyManager.onKeydown(createKeyboardEvent('keydown', 79, 'o')); // types "o"
         tick(debounceInterval);
@@ -916,6 +930,7 @@ describe('Key managers', () => {
           new FakeFocusable('Boromir'),
           new FakeFocusable('Aragorn'),
         ]);
+        itemList.notifyOnChanges();
 
         keyManager.setActiveItem(1);
         keyManager.onKeydown(createKeyboardEvent('keydown', 66, 'b'));
@@ -932,6 +947,7 @@ describe('Key managers', () => {
           new FakeFocusable('Boromir'),
           new FakeFocusable('Aragorn'),
         ]);
+        itemList.notifyOnChanges();
 
         keyManager.setActiveItem(3);
         keyManager.onKeydown(createKeyboardEvent('keydown', 66, 'b'));

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

@@ -14,17 +14,13 @@ import {
   LEFT_ARROW,
   RIGHT_ARROW,
   TAB,
-  A,
-  Z,
-  ZERO,
-  NINE,
   hasModifierKey,
   HOME,
   END,
   PAGE_UP,
   PAGE_DOWN,
 } from '@angular/cdk/keycodes';
-import {debounceTime, filter, map, tap} from 'rxjs/operators';
+import {Typeahead} from './typeahead';
 
 /** This interface is for items that can be passed to a ListKeyManager. */
 export interface ListKeyManagerOption {
@@ -46,7 +42,6 @@ export class ListKeyManager<T extends ListKeyManagerOption> {
   private _activeItemIndex = -1;
   private _activeItem: T | null = null;
   private _wrap = false;
-  private readonly _letterKeyStream = new Subject<string>();
   private _typeaheadSubscription = Subscription.EMPTY;
   private _itemChangesSubscription?: Subscription;
   private _vertical = true;
@@ -55,16 +50,14 @@ export class ListKeyManager<T extends ListKeyManagerOption> {
   private _homeAndEnd = false;
   private _pageUpAndDown = {enabled: false, delta: 10};
   private _effectRef: EffectRef | undefined;
+  private _typeahead?: Typeahead<T>;
 
   /**
    * Predicate function that can be used to check whether an item should be skipped
    * by the key manager. By default, disabled items are skipped.
    */
   private _skipPredicateFn = (item: T) => item.disabled;
 
-  // Buffer for the letters that the user has pressed when the typeahead option is turned on.
-  private _pressedLetters: string[] = [];
-
   constructor(items: QueryList<T> | T[] | readonly T[]);
   constructor(items: Signal<T[]> | Signal<readonly T[]>, injector: Injector);
   constructor(
@@ -158,43 +151,22 @@ export class ListKeyManager<T extends ListKeyManagerOption> {
 
     this._typeaheadSubscription.unsubscribe();
 
-    // Debounce the presses of non-navigational keys, collect the ones that correspond to letters
-    // and convert those letters back into a string. Afterwards find the first item that starts
-    // with that string and select it.
-    this._typeaheadSubscription = this._letterKeyStream
-      .pipe(
-        tap(letter => this._pressedLetters.push(letter)),
-        debounceTime(debounceInterval),
-        filter(() => this._pressedLetters.length > 0),
-        map(() => this._pressedLetters.join('')),
-      )
-      .subscribe(inputString => {
-        const items = this._getItemsArray();
-
-        // Start at 1 because we want to start searching at the item immediately
-        // following the current active item.
-        for (let i = 1; i < items.length + 1; i++) {
-          const index = (this._activeItemIndex + i) % items.length;
-          const item = items[index];
-
-          if (
-            !this._skipPredicateFn(item) &&
-            item.getLabel!().toUpperCase().trim().indexOf(inputString) === 0
-          ) {
-            this.setActiveItem(index);
-            break;
-          }
-        }
+    const items = this._getItemsArray();
+    this._typeahead = new Typeahead(items, {
+      debounceInterval: typeof debounceInterval === 'number' ? debounceInterval : undefined,
+      skipPredicate: item => this._skipPredicateFn(item),
+    });
 
-        this._pressedLetters = [];
-      });
+    this._typeaheadSubscription = this._typeahead.selectedItem.subscribe(item => {
+      this.setActiveItem(item);
+    });
 
     return this;
   }
 
   /** Cancels the current typeahead sequence. */
   cancelTypeahead(): this {
-    this._pressedLetters = [];
+    this._typeahead?.reset();
     return this;
   }
 
@@ -326,21 +298,15 @@ export class ListKeyManager<T extends ListKeyManagerOption> {
 
       default:
         if (isModifierAllowed || hasModifierKey(event, 'shiftKey')) {
-          // Attempt to use the `event.key` which also maps it to the user's keyboard language,
-          // otherwise fall back to resolving alphanumeric characters via the keyCode.
-          if (event.key && event.key.length === 1) {
-            this._letterKeyStream.next(event.key.toLocaleUpperCase());
-          } else if ((keyCode >= A && keyCode <= Z) || (keyCode >= ZERO && keyCode <= NINE)) {
-            this._letterKeyStream.next(String.fromCharCode(keyCode));
-          }
+          this._typeahead?.handleKey(event);
         }
 
         // Note that we return here, in order to avoid preventing
         // the default action of non-navigational keys.
         return;
     }
 
-    this._pressedLetters = [];
+    this._typeahead?.reset();
     event.preventDefault();
   }
 
@@ -356,7 +322,7 @@ export class ListKeyManager<T extends ListKeyManagerOption> {
 
   /** Gets whether the user is currently typing into the manager using the typeahead feature. */
   isTyping(): boolean {
-    return this._pressedLetters.length > 0;
+    return !!this._typeahead && this._typeahead.isTyping();
   }
 
   /** Sets the active item to the first enabled item in the list. */
@@ -401,17 +367,17 @@ export class ListKeyManager<T extends ListKeyManagerOption> {
     // Explicitly check for `null` and `undefined` because other falsy values are valid.
     this._activeItem = activeItem == null ? null : activeItem;
     this._activeItemIndex = index;
+    this._typeahead?.setCurrentSelectedItemIndex(index);
   }
 
   /** Cleans up the key manager. */
   destroy() {
     this._typeaheadSubscription.unsubscribe();
     this._itemChangesSubscription?.unsubscribe();
     this._effectRef?.destroy();
-    this._letterKeyStream.complete();
+    this._typeahead?.destroy();
     this.tabOut.complete();
     this.change.complete();
-    this._pressedLetters = [];
   }
 
   /**
@@ -485,11 +451,13 @@ export class ListKeyManager<T extends ListKeyManagerOption> {
 
   /** Callback for when the items have changed. */
   private _itemsChanged(newItems: T[] | readonly T[]) {
+    this._typeahead?.setItems(newItems);
     if (this._activeItem) {
       const newIndex = newItems.indexOf(this._activeItem);
 
       if (newIndex > -1 && newIndex !== this._activeItemIndex) {
         this._activeItemIndex = newIndex;
+        this._typeahead?.setCurrentSelectedItemIndex(newIndex);
       }
     }
   }