docs(tree): add guide to cdk-tree

Author: tinayuangao

src/cdk/tree/tree.md

@@ -0,0 +1,157 @@
+The `<cdk-tree>` enable developers to build customized tree for structured data.  The 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
+these two types of trees.
+
+#### Flat tree
+
+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.
+
+```
+<cdk-tree>
+    <cdk-tree-node> parent node </cdk-tree-node>
+    <cdk-tree-node> -- child node1 </cdk-tree-node>
+    <cdk-tree-node> -- child node2 </cdk-tree-node>
+</cdk-tree>
+
+```
+
+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
+
+In Nested tree, children nodes are placed inside their parent node in DOM. The parent node has an
+outlet to keep all the children nodes.
+
+```
+<cdk-tree>
+   <cdk-nested-tree-node>
+       parent node
+       <cdk-nested-tree-node> -- child node1 </cdk-tree-node>
+       <cdk-nested-tree-node> -- child node2 </cdk-tree-node>
+   </cdk-nested-tree-node>
+</cdk-tree>
+```
+
+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
+
+#### Wring 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
+template defines the look of the tree node, expansion/collapsing control and the structure for
+nested children nodes.
+
+A node definition is specified via any element with `cdkNodeDef`. It also export the node context,
+ which can be used for event and property bindings on the node element.
+
+##### Flat tree template
+
+Flat tree template uses tree node’s `level` information to render the hierarchy of the nodes.
+Optionally, `cdkNodePadding` can be used in flat tree to add padding before the content of the
+node to show the hierarchy. No tree node will be put inside another flat tree node, therefore
+there's no way to handle nested children in a flat tree node.
+
+
+##### Nested tree template
+
+Users of nested tree node should put `<ng-container cdkTreeNodeOutlet></ng-container>` to the nested
+ tree node template. The children of this nested tree node will be rendered at this position.
+
+```
+<cdk-nested-tree-node *cdkNodeDef=“let node”>
+    {{node.value}}
+    <ng-container cdkTreeNodeOutlet>
+</cdk-nested-tree-node>
+
+```
+
+#### Trigger
+
+A `cdkTreeNodeTrigger` can be added in the tree node template to expand/collapse the tree node.
+The trigger triggers the expand/collapse functions in TreeControl and is able to expand/collapse
+a tree node recursively by setting `[cdkTreeNodeTriggerRecursive]` to true.
+
+```
+<cdk-tree-node *cdkNodeDef=“let node” cdkTreeNodeTrigger [cdkTreeNodeTriggerRecursive]="true">
+    {{node.value}}
+</cdk-tree-node>
+```
+
+The trigger can be placed anywhere in the tree node, and is only triggered by click action.
+
+```
+<cdk-tree-node *cdkNodeDef=“let node”>
+  <span  cdkTreeNodeTrigger [cdkTreeNodeTriggerRecursive]="true">
+    <mat-icon>expand</mat-icon>
+  </span>
+  {{node.value}}
+</cdk-tree-node>
+```
+
+#### Padding (Flat tree only)
+
+The cdkTreeNodePadding can be placed in a flat tree's node template to display the level
+information of a flat tree node.
+
+```
+<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.
+
+
+#### When
+Different tree node templates can be defined via the `when:` with a function.
+Please note that the tree will not update the template it uses if the data object does not change.
+So the `when` function should no be based on a dynamic variable, and instead it should be based on
+a fixed property of the data object.
+
+```
+<cdk-tree-node *cdkNodeDef=“let node” cdkTreeNodePadding>
+    {{node.value}}
+</cdk-tree-node>
+<cdk-tree-node *cdkNodeDef=“let node; when: isSpecial” cdkTreeNodePadding>
+    [ A special node {{node.value}} ]
+</cdk-tree-node>
+```
+
+### Data Source
+
+#### Connecting the tree to a data source
+
+Similar to `cdl-table`, data is provided to the tree through a `DataSource`. When the tree receives
+a `DataSource` it will call its `connect()` method which returns an observable that emits an array
+of data. Whenever the data source emits data to this stream, the tree will render an update.
+
+Because the data source provides this stream, it bears the responsibility of triggering tree
+updates. This can be based on anything: tree node expansion change, websocket connections, user
+interaction, model updates, time-based intervals, etc.
+
+
+#### Flat tree
+
+The flat tree data source should be 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.
+
+
+#### Nested tree
+
+The data source for nested tree has an option to leave the node expansion/collapsing event for each
+tree node component to handle.