From 724dc2f78809d4b06d08e230f0afafe204dce075 Mon Sep 17 00:00:00 2001
From: Cassandra Choi <cassc@google.com>
Date: Thu, 19 Sep 2024 02:33:43 -0400
Subject: [PATCH] docs(material/tree): update examples on docs pages, add new
 childrenAccessor examples (#29752)

* docs(mat/tree): add childrenAccessor example for mat-tree flat

* fix(mat/tree): fix imports

* docs(mat/tree): add childrenAccessor example for nested mat-tree

* fix(mat/tree): fix imports

* fix(mat/tree): formatting

(cherry picked from commit c4ca044c82895a3f1fdefd8fa3b03f8d0342c119)
---
 src/cdk/tree/tree.md                          |  4 +-
 .../material/tree/index.ts                    |  2 +
 ...-flat-child-accessor-overview-example.html | 19 +++++++
 ...ee-flat-child-accessor-overview-example.ts | 51 ++++++++++++++++++
 ...nested-child-accessor-overview-example.css | 26 ++++++++++
 ...ested-child-accessor-overview-example.html | 28 ++++++++++
 ...-nested-child-accessor-overview-example.ts | 52 +++++++++++++++++++
 src/dev-app/tree/tree-demo.html               |  8 +++
 src/dev-app/tree/tree-demo.ts                 |  4 ++
 src/material/tree/tree.md                     |  4 +-
 10 files changed, 194 insertions(+), 4 deletions(-)
 create mode 100644 src/components-examples/material/tree/tree-flat-child-accessor-overview/tree-flat-child-accessor-overview-example.html
 create mode 100644 src/components-examples/material/tree/tree-flat-child-accessor-overview/tree-flat-child-accessor-overview-example.ts
 create mode 100644 src/components-examples/material/tree/tree-nested-child-accessor-overview/tree-nested-child-accessor-overview-example.css
 create mode 100644 src/components-examples/material/tree/tree-nested-child-accessor-overview/tree-nested-child-accessor-overview-example.html
 create mode 100644 src/components-examples/material/tree/tree-nested-child-accessor-overview/tree-nested-child-accessor-overview-example.ts

diff --git a/src/cdk/tree/tree.md b/src/cdk/tree/tree.md
index 187513b805e6..19f3b2d8e903 100644
--- a/src/cdk/tree/tree.md
+++ b/src/cdk/tree/tree.md
@@ -19,7 +19,7 @@ are rendered as siblings in sequence.
 
 ```
 
-<!-- example(cdk-tree-flat) -->
+<!-- example(cdk-tree-flat-children-accessor) -->
 
 Flat trees are generally easier to style and inspect. They are also more friendly to scrolling
 variations, such as infinite or virtual scrolling.
@@ -40,7 +40,7 @@ contains a node outlet into which children are projected.
 </cdk-tree>
 ```
 
-<!-- example(cdk-tree-nested) -->
+<!-- example(cdk-tree-nested-children-accessor) -->
 
 Nested trees are easier to work with when hierarchical relationships are visually represented in
 ways that would be difficult to accomplish with flat nodes.
diff --git a/src/components-examples/material/tree/index.ts b/src/components-examples/material/tree/index.ts
index efc466c63794..c596314f4791 100644
--- a/src/components-examples/material/tree/index.ts
+++ b/src/components-examples/material/tree/index.ts
@@ -1,6 +1,8 @@
 export {TreeDynamicExample} from './tree-dynamic/tree-dynamic-example';
 export {TreeFlatOverviewExample} from './tree-flat-overview/tree-flat-overview-example';
+export {TreeFlatChildAccessorOverviewExample} from './tree-flat-child-accessor-overview/tree-flat-child-accessor-overview-example';
 export {TreeHarnessExample} from './tree-harness/tree-harness-example';
 export {TreeLoadmoreExample} from './tree-loadmore/tree-loadmore-example';
 export {TreeNestedOverviewExample} from './tree-nested-overview/tree-nested-overview-example';
+export {TreeNestedChildAccessorOverviewExample} from './tree-nested-child-accessor-overview/tree-nested-child-accessor-overview-example';
 export {TreeLegacyKeyboardInterfaceExample} from './tree-legacy-keyboard-interface/tree-legacy-keyboard-interface-example';
diff --git a/src/components-examples/material/tree/tree-flat-child-accessor-overview/tree-flat-child-accessor-overview-example.html b/src/components-examples/material/tree/tree-flat-child-accessor-overview/tree-flat-child-accessor-overview-example.html
new file mode 100644
index 000000000000..f0a615e24861
--- /dev/null
+++ b/src/components-examples/material/tree/tree-flat-child-accessor-overview/tree-flat-child-accessor-overview-example.html
@@ -0,0 +1,19 @@
+<mat-tree #tree [dataSource]="dataSource" [childrenAccessor]="childrenAccessor">
+  <!-- This is the tree node template for leaf nodes -->
+  <mat-tree-node *matTreeNodeDef="let node" matTreeNodePadding>
+    <!-- use a disabled button to provide padding for tree leaf -->
+    <button mat-icon-button disabled></button>
+    {{node.name}}
+  </mat-tree-node>
+  <!-- This is the tree node template for expandable nodes -->
+  <mat-tree-node *matTreeNodeDef="let node;when: hasChild" matTreeNodePadding matTreeNodeToggle
+                 [cdkTreeNodeTypeaheadLabel]="node.name">
+    <button mat-icon-button matTreeNodeToggle
+            [attr.aria-label]="'Toggle ' + node.name">
+      <mat-icon class="mat-icon-rtl-mirror">
+        {{tree.isExpanded(node) ? 'expand_more' : 'chevron_right'}}
+      </mat-icon>
+    </button>
+    {{node.name}}
+  </mat-tree-node>
+</mat-tree>
diff --git a/src/components-examples/material/tree/tree-flat-child-accessor-overview/tree-flat-child-accessor-overview-example.ts b/src/components-examples/material/tree/tree-flat-child-accessor-overview/tree-flat-child-accessor-overview-example.ts
new file mode 100644
index 000000000000..7c91ba9893cd
--- /dev/null
+++ b/src/components-examples/material/tree/tree-flat-child-accessor-overview/tree-flat-child-accessor-overview-example.ts
@@ -0,0 +1,51 @@
+import {ChangeDetectionStrategy, Component} from '@angular/core';
+import {MatTreeModule} from '@angular/material/tree';
+import {MatIconModule} from '@angular/material/icon';
+import {MatButtonModule} from '@angular/material/button';
+
+/**
+ * Food data with nested structure.
+ * Each node has a name and an optional list of children.
+ */
+interface FoodNode {
+  name: string;
+  children?: FoodNode[];
+}
+
+const TREE_DATA: FoodNode[] = [
+  {
+    name: 'Fruit',
+    children: [{name: 'Apple'}, {name: 'Banana'}, {name: 'Fruit loops'}],
+  },
+  {
+    name: 'Vegetables',
+    children: [
+      {
+        name: 'Green',
+        children: [{name: 'Broccoli'}, {name: 'Brussels sprouts'}],
+      },
+      {
+        name: 'Orange',
+        children: [{name: 'Pumpkins'}, {name: 'Carrots'}],
+      },
+    ],
+  },
+];
+
+/**
+ * @title Tree with flat nodes (childrenAccessor)
+ */
+@Component({
+  selector: 'tree-flat-child-accessor-overview-example',
+  templateUrl: 'tree-flat-child-accessor-overview-example.html',
+  standalone: true,
+  imports: [MatTreeModule, MatButtonModule, MatIconModule],
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class TreeFlatChildAccessorOverviewExample {
+  dataSource = TREE_DATA;
+
+  childrenAccessor = (node: FoodNode) => node.children ?? [];
+
+  hasChild = (_: number, node: FoodNode) => !!node.children && node.children.length > 0;
+}
diff --git a/src/components-examples/material/tree/tree-nested-child-accessor-overview/tree-nested-child-accessor-overview-example.css b/src/components-examples/material/tree/tree-nested-child-accessor-overview/tree-nested-child-accessor-overview-example.css
new file mode 100644
index 000000000000..2d1a32aa5732
--- /dev/null
+++ b/src/components-examples/material/tree/tree-nested-child-accessor-overview/tree-nested-child-accessor-overview-example.css
@@ -0,0 +1,26 @@
+.example-tree-invisible {
+  display: none;
+}
+
+.example-tree ul,
+.example-tree li {
+  margin-top: 0;
+  margin-bottom: 0;
+  list-style-type: none;
+}
+
+/*
+ * This padding sets alignment of the nested nodes.
+ */
+.example-tree .mat-nested-tree-node div[role=group] {
+  padding-left: 40px;
+}
+
+/*
+ * Padding for leaf nodes.
+ * Leaf nodes need to have padding so as to align with other non-leaf nodes
+ * under the same parent.
+ */
+.example-tree div[role=group] > .mat-tree-node {
+  padding-left: 40px;
+}
diff --git a/src/components-examples/material/tree/tree-nested-child-accessor-overview/tree-nested-child-accessor-overview-example.html b/src/components-examples/material/tree/tree-nested-child-accessor-overview/tree-nested-child-accessor-overview-example.html
new file mode 100644
index 000000000000..c18934525142
--- /dev/null
+++ b/src/components-examples/material/tree/tree-nested-child-accessor-overview/tree-nested-child-accessor-overview-example.html
@@ -0,0 +1,28 @@
+<mat-tree #tree [dataSource]="dataSource" [childrenAccessor]="childrenAccessor" class="example-tree">
+  <!-- This is the tree node template for leaf nodes -->
+  <!-- There is inline padding applied to this node using styles.
+    This padding value depends on the mat-icon-button width. -->
+  <mat-tree-node *matTreeNodeDef="let node">
+    {{node.name}}
+  </mat-tree-node>
+  <!-- This is the tree node template for expandable nodes -->
+  <mat-nested-tree-node
+      *matTreeNodeDef="let node; when: hasChild"
+      matTreeNodeToggle [cdkTreeNodeTypeaheadLabel]="node.name">
+    <div class="mat-tree-node">
+      <button mat-icon-button matTreeNodeToggle
+              [attr.aria-label]="'Toggle ' + node.name">
+        <mat-icon class="mat-icon-rtl-mirror">
+          {{tree.isExpanded(node) ? 'expand_more' : 'chevron_right'}}
+        </mat-icon>
+      </button>
+      {{node.name}}
+    </div>
+    <!-- There is inline padding applied to this div using styles.
+        This padding value depends on the mat-icon-button width.  -->
+    <div [class.example-tree-invisible]="!tree.isExpanded(node)"
+        role="group">
+      <ng-container matTreeNodeOutlet></ng-container>
+    </div>
+  </mat-nested-tree-node>
+</mat-tree>
diff --git a/src/components-examples/material/tree/tree-nested-child-accessor-overview/tree-nested-child-accessor-overview-example.ts b/src/components-examples/material/tree/tree-nested-child-accessor-overview/tree-nested-child-accessor-overview-example.ts
new file mode 100644
index 000000000000..e992c46932db
--- /dev/null
+++ b/src/components-examples/material/tree/tree-nested-child-accessor-overview/tree-nested-child-accessor-overview-example.ts
@@ -0,0 +1,52 @@
+import {ChangeDetectionStrategy, Component} from '@angular/core';
+import {MatTreeModule} from '@angular/material/tree';
+import {MatIconModule} from '@angular/material/icon';
+import {MatButtonModule} from '@angular/material/button';
+
+/**
+ * Food data with nested structure.
+ * Each node has a name and an optional list of children.
+ */
+interface FoodNode {
+  name: string;
+  children?: FoodNode[];
+}
+
+const TREE_DATA: FoodNode[] = [
+  {
+    name: 'Fruit',
+    children: [{name: 'Apple'}, {name: 'Banana'}, {name: 'Fruit loops'}],
+  },
+  {
+    name: 'Vegetables',
+    children: [
+      {
+        name: 'Green',
+        children: [{name: 'Broccoli'}, {name: 'Brussels sprouts'}],
+      },
+      {
+        name: 'Orange',
+        children: [{name: 'Pumpkins'}, {name: 'Carrots'}],
+      },
+    ],
+  },
+];
+
+/**
+ * @title Tree with nested nodes (childrenAccessor)
+ */
+@Component({
+  selector: 'tree-nested-child-accessor-overview-example',
+  templateUrl: 'tree-nested-child-accessor-overview-example.html',
+  styleUrl: 'tree-nested-child-accessor-overview-example.css',
+  standalone: true,
+  imports: [MatTreeModule, MatButtonModule, MatIconModule],
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class TreeNestedChildAccessorOverviewExample {
+  childrenAccessor = (node: FoodNode) => node.children ?? [];
+
+  dataSource = TREE_DATA;
+
+  hasChild = (_: number, node: FoodNode) => !!node.children && node.children.length > 0;
+}
diff --git a/src/dev-app/tree/tree-demo.html b/src/dev-app/tree/tree-demo.html
index 52d4216c2aee..f9299ad71c92 100644
--- a/src/dev-app/tree/tree-demo.html
+++ b/src/dev-app/tree/tree-demo.html
@@ -3,6 +3,10 @@
     <mat-expansion-panel-header>Flat tree</mat-expansion-panel-header>
     <tree-flat-overview-example></tree-flat-overview-example>
   </mat-expansion-panel>
+  <mat-expansion-panel>
+    <mat-expansion-panel-header>Flat tree (childrenAccessor)</mat-expansion-panel-header>
+    <tree-flat-child-accessor-overview-example></tree-flat-child-accessor-overview-example>
+  </mat-expansion-panel>
   <mat-expansion-panel>
     <mat-expansion-panel-header>CDK Flat tree</mat-expansion-panel-header>
     <cdk-tree-flat-example></cdk-tree-flat-example>
@@ -19,6 +23,10 @@
     <mat-expansion-panel-header>Nested tree</mat-expansion-panel-header>
     <tree-nested-overview-example></tree-nested-overview-example>
   </mat-expansion-panel>
+  <mat-expansion-panel>
+    <mat-expansion-panel-header>Nested tree (childrenAccessor)</mat-expansion-panel-header>
+    <tree-nested-child-accessor-overview-example></tree-nested-child-accessor-overview-example>
+  </mat-expansion-panel>
   <mat-expansion-panel>
     <mat-expansion-panel-header>CDK Nested tree</mat-expansion-panel-header>
     <cdk-tree-nested-example></cdk-tree-nested-example>
diff --git a/src/dev-app/tree/tree-demo.ts b/src/dev-app/tree/tree-demo.ts
index 4ae07167e2b1..c067dbb614ad 100644
--- a/src/dev-app/tree/tree-demo.ts
+++ b/src/dev-app/tree/tree-demo.ts
@@ -24,6 +24,8 @@ import {
   TreeLegacyKeyboardInterfaceExample,
   TreeLoadmoreExample,
   TreeNestedOverviewExample,
+  TreeNestedChildAccessorOverviewExample,
+  TreeFlatChildAccessorOverviewExample,
 } from '@angular/components-examples/material/tree';
 import {ChangeDetectionStrategy, Component} from '@angular/core';
 import {FormsModule} from '@angular/forms';
@@ -54,10 +56,12 @@ import {MatTreeModule} from '@angular/material/tree';
     CommonModule,
     FormsModule,
     TreeDynamicExample,
+    TreeFlatChildAccessorOverviewExample,
     TreeFlatOverviewExample,
     TreeHarnessExample,
     TreeLegacyKeyboardInterfaceExample,
     TreeLoadmoreExample,
+    TreeNestedChildAccessorOverviewExample,
     TreeNestedOverviewExample,
     MatButtonModule,
     MatExpansionModule,
diff --git a/src/material/tree/tree.md b/src/material/tree/tree.md
index 1d1701dc4686..5b5f4d2fccc8 100644
--- a/src/material/tree/tree.md
+++ b/src/material/tree/tree.md
@@ -21,7 +21,7 @@ but instead are rendered as siblings in sequence.
 </mat-tree>
 ```
 
-<!-- example(tree-flat-overview) -->
+<!-- example(tree-flat-child-accessor-overview) -->
 
 Flat trees are generally easier to style and inspect. They are also more friendly to scrolling
 variations, such as infinite or virtual scrolling.
@@ -41,7 +41,7 @@ contains a node outlet into which children are projected.
 </mat-tree>
 ```
 
-<!-- example(tree-nested-overview) -->
+<!-- example(tree-nested-child-accessor-overview) -->
 
 Nested trees are easier to work with when hierarchical relationships are visually represented in
 ways that would be difficult to accomplish with flat nodes.