feat(cdk/tree): update tree documentation

Author: BobobUnicorn

src/cdk/tree/tree.md

@@ -2,19 +2,13 @@ The `<cdk-tree>` enables developers to build a customized tree experience for st
 `<cdk-tree>` provides a foundation to build other features such as filtering on top of tree.
 For a Material Design styled tree, see `<mat-tree>` which builds on top of the `<cdk-tree>`.
 
-There are two types of trees: flat tree and nested Tree. The DOM structures are different for
+There are two types of trees: flat and nested. The DOM structures are different for these
 these two types of trees.
 
 #### Flat tree
 
-<!-- example(cdk-tree-flat) -->
-
-
 In a flat tree, the hierarchy is flattened; nodes are not rendered inside of each other, but instead
-are rendered as siblings in sequence. An instance of `TreeFlattener` is used to generate the flat
-list of items from hierarchical data. The "level" of each tree node is read through the `getLevel`
-method of the `TreeControl`; this level can be used to style the node such that it is indented to
-the appropriate level.
+are rendered as siblings in sequence.
 
 ```html
 <cdk-tree>
@@ -25,16 +19,16 @@ the appropriate level.
 
 ```
 
+<!-- example(cdk-tree-flat) -->
+
 Flat trees are generally easier to style and inspect. They are also more friendly to scrolling
 variations, such as infinite or virtual scrolling.
 
 
 #### Nested tree
 
-<!-- example(cdk-tree-nested) -->
-
-In nested tree, children nodes are placed inside their parent node in DOM. The parent node contains
-a node outlet into which children are projected.
+In a nested tree, children nodes are placed inside their parent node in DOM. The parent node
+contains a node outlet into which children are projected.
 
 ```html
 <cdk-tree>
@@ -46,15 +40,18 @@ a node outlet into which children are projected.
 </cdk-tree>
 ```
 
+<!-- example(cdk-tree-nested) -->
+
 Nested trees are easier to work with when hierarchical relationships are visually represented in
 ways that would be difficult to accomplish with flat nodes.
 
-### Using the CDK tree
+
+### Usage
 
 #### Writing your tree template
 
-The only thing you need to define is the tree node template. There are two types of tree nodes,
-`<cdk-tree-node>` for flat tree and `<cdk-tree-nested-node>` for nested tree. The tree node
+In order to use the tree, you must define a tree node template. There are two types of tree nodes,
+`<cdk-tree-node>` for flat tree and `<cdk-nested-tree-node>` for nested tree. The tree node
 template defines the look of the tree node, expansion/collapsing control and the structure for
 nested children nodes.
 
@@ -69,9 +66,12 @@ data to be used in any bindings in the node template.
 
 ##### Flat tree node template
 
-Flat tree uses each node's `level` to render the hierarchy of the nodes.
-The "indent" for a given node is accomplished by adding spacing to each node based on its level.
-Spacing can be added either by applying the `cdkNodePadding` directive or by applying custom styles.
+Flat trees use the `level` of a node to both render and determine hierarchy of the nodes for screen
+readers. This may be provided either via `levelAccessor`, or will be calculated by `CdkTree` if
+`childrenAccessor` is provided.
+
+Spacing can be added either by applying the `cdkNodePadding` directive or by applying custom styles
+based on the `aria-level` attribute.
 
 
 ##### Nested tree node template
@@ -84,24 +84,16 @@ where the children of the node will be rendered.
   {{node.value}}
   <ng-container cdkTreeNodeOutlet></ng-container>
 </cdk-nested-tree-node>
-
 ```
 
 #### Adding expand/collapse
 
-A `cdkTreeNodeToggle` can be added in the tree node template to expand/collapse the tree node.
-The toggle toggles the expand/collapse functions in TreeControl and is able to expand/collapse
+The `cdkTreeNodeToggle` directive can be used to add expand/collapse functionality for tree nodes.
+The toggle calls the expand/collapse functions in the `CdkTree` and is able to expand/collapse
 a tree node recursively by setting `[cdkTreeNodeToggleRecursive]` to true.
 
-```html
-<cdk-tree-node *cdkNodeDef="let node" cdkTreeNodeToggle [cdkTreeNodeToggleRecursive]="true">
-    {{node.value}}
-</cdk-tree-node>
-```
-
-The toggle can be placed anywhere in the tree node, and is only toggled by click action.
-For best accessibility, `cdkTreeNodeToggle` should be on a button element and have an appropriate
-`aria-label`.
+`cdkTreeNodeToggle` should be attached to button elements, and will trigger upon click or keyboard
+activation. For icon buttons, ensure that `aria-label` is provided.
 
 ```html
 <cdk-tree-node *cdkNodeDef="let node">
@@ -114,25 +106,24 @@ For best accessibility, `cdkTreeNodeToggle` should be on a button element and ha
 
 #### Padding (Flat tree only)
 
-The cdkTreeNodePadding can be placed in a flat tree's node template to display the level
+The `cdkTreeNodePadding` directive can be placed in a flat tree's node template to display the level
 information of a flat tree node.
 
 ```html
 <cdk-tree-node *cdkNodeDef="let node" cdkNodePadding>
   {{node.value}}
 </cdk-tree-node>
-
 ```
 
-Nested tree does not need this padding since padding can be easily added to the hierarchy structure
-in DOM.
+This is unnecessary for a nested tree, since the hierarchical structure of the DOM allows for
+padding to be added via CSS.
 
 
 #### Conditional template
+
 The tree may include multiple node templates, where a template is chosen
 for a particular data node via the `when` predicate of the template.
 
-
 ```html
 <cdk-tree-node *cdkNodeDef="let node" cdkTreeNodePadding>
   {{node.value}}
@@ -154,20 +145,30 @@ Because the data source provides this stream, it bears the responsibility of tog
 updates. This can be based on anything: tree node expansion change, websocket connections, user
 interaction, model updates, time-based intervals, etc.
 
+There are two main methods of providing data to the tree:
 
-#### Flat tree
+* flattened data, combined with `levelAccessor`. This should be used if the data source already
+  flattens the nested data structure into a single array.
+* only root data, combined with `childrenAccessor`. This should be used if the data source is
+  already provided as a nested data structure.
 
-The flat tree data source is responsible for the node expansion/collapsing events, since when
-the expansion status changes, the data nodes feed to the tree are changed. A new list of visible
-nodes should be sent to tree component based on current expansion status.
+#### `levelAccessor`
 
+`levelAccessor` is a function that when provided a datum, returns the level the data sits at in the
+tree structure. If `levelAccessor` is provided, the data provided by `dataSource` should contain all
+renderable nodes in a single array.
 
-#### Nested tree
+The data source is responsible for handling node expand/collapse events and providing an updated
+array of renderable nodes, if applicable. This can be listened to via the `(expansionChange)` event
+on `cdk-tree-node` and `cdk-nested-tree-node`.
+
+#### `childrenAccessor`
 
-The data source for nested tree has an option to leave the node expansion/collapsing event for each
-tree node component to handle.
+`childrenAccessor` is a function that when provided a datum, returns the children of that particular
+datum. If `childrenAccessor` is provided, the data provided by `dataSource` should _only_ contain
+the root nodes of the tree.
 
-##### `trackBy`
+#### `trackBy`
 
 To improve performance, a `trackBy` function can be provided to the tree similar to Angular’s
 [`ngFor` `trackBy`](https://angular.io/api/common/NgForOf#change-propagation). This informs the
@@ -176,3 +177,25 @@ tree how to uniquely identify nodes to track how the data changes with each upda
 ```html
 <cdk-tree [dataSource]="dataSource" [treeControl]="treeControl" [trackBy]="trackByFn">
 ```
+
+### Accessibility
+
+The `<cdk-tree>` implements the [`tree` widget](https://www.w3.org/WAI/ARIA/apg/patterns/treeview/),
+including keyboard navigation and appropriate roles and ARIA attributes.
+
+#### Activation actions
+
+For trees with nodes that have actions upon activation or click, `<cdk-tree-node>` will emit
+`(activation)` events that can be listened to when the user activates a node via keyboard
+interaction.
+
+```html
+<cdk-tree-node
+    *cdkNodeDef="let node"
+    (click)="performAction(node)"
+    (activation)="performAction($event)">
+</cdk-tree-node>
+```
+
+In this example, `$event` contains the node's data and is equivalent to the implicit data passed in
+the `cdkNodeDef` context.

src/cdk/tree/tree.ts

@@ -1141,7 +1141,7 @@ export class CdkTreeNode<T, K = T> implements OnDestroy, OnInit, TreeKeyManagerI
    */
   @Input() isDisabled?: boolean;
 
-  /** This emits when the node has been programatically activated. */
+  /** This emits when the node has been programatically activated or activated by keyboard. */
   @Output()
   readonly activation: EventEmitter<T> = new EventEmitter<T>();