Programmatically expand/collapse TreeView nodes (#850)

* feat(tree-view): add accessors to programmatically expand/collapse nodes

* feat(tree-view): update docs/types

* test(tree-view): test updated TreeView accessors

* docs(tree-view): document TreeView accessors

COMPONENT_INDEX.md

@@ -4753,15 +4753,19 @@ export interface TreeNode {
 
 ### Props
 
-| Prop name   | Kind             | Reactive | Type                                                     | Default value          | Description                                                     |
+| Prop name     | Kind                  | Reactive | Type                                                          | Default value                                                                                            | Description                                                                                      |
-| :---------- | :--------------- | :------- | :------------------------------------------------------- | ---------------------- | --------------------------------------------------------------- |
+| :------------ | :-------------------- | :------- | :------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
-| expandedIds | <code>let</code> | Yes      | <code>TreeNodeId[]</code>                                | <code>[]</code>        | Set the node ids to be expanded                                 |
+| expandedIds   | <code>let</code>      | Yes      | <code>TreeNodeId[]</code>                                     | <code>[]</code>                                                                                          | Set the node ids to be expanded                                                                  |
-| selectedIds | <code>let</code> | Yes      | <code>TreeNodeId[]</code>                                | <code>[]</code>        | Set the node ids to be selected                                 |
+| selectedIds   | <code>let</code>      | Yes      | <code>TreeNodeId[]</code>                                     | <code>[]</code>                                                                                          | Set the node ids to be selected                                                                  |
-| activeId    | <code>let</code> | Yes      | <code>TreeNodeId</code>                                  | <code>""</code>        | Set the current active node id<br />Only one node can be active |
+| activeId      | <code>let</code>      | Yes      | <code>TreeNodeId</code>                                       | <code>""</code>                                                                                          | Set the current active node id<br />Only one node can be active                                  |
-| children    | <code>let</code> | No       | <code>Array<TreeNode & { children?: TreeNode[] }></code> | <code>[]</code>        | Provide an array of children nodes to render                    |
+| children      | <code>let</code>      | No       | <code>Array<TreeNode & { children?: TreeNode[] }></code>      | <code>[]</code>                                                                                          | Provide an array of children nodes to render                                                     |
-| size        | <code>let</code> | No       | <code>"default" &#124; "compact"</code>                  | <code>"default"</code> | Specify the TreeView size                                       |
+| size          | <code>let</code>      | No       | <code>"default" &#124; "compact"</code>                       | <code>"default"</code>                                                                                   | Specify the TreeView size                                                                        |
-| labelText   | <code>let</code> | No       | <code>string</code>                                      | <code>""</code>        | Specify the label text                                          |
+| labelText     | <code>let</code>      | No       | <code>string</code>                                           | <code>""</code>                                                                                          | Specify the label text                                                                           |
-| hideLabel   | <code>let</code> | No       | <code>boolean</code>                                     | <code>false</code>     | Set to `true` to visually hide the label text                   |
+| hideLabel     | <code>let</code>      | No       | <code>boolean</code>                                          | <code>false</code>                                                                                       | Set to `true` to visually hide the label text                                                    |
+| expandAll     | <code>function</code> | No       | <code>() => void</code>                                       | <code>() => { expandedIds = [...nodeIds]; }</code>                                                       | Programmatically expand all nodes                                                                |
+| collapseAll   | <code>function</code> | No       | <code>() => void</code>                                       | <code>() => { expandedIds = []; }</code>                                                                 | Programmatically collapse all nodes                                                              |
+| expandNodes   | <code>function</code> | No       | <code>(filterId?: (node: TreeNode) => boolean) => void</code> | <code>() => { expandedIds = nodes .filter((node) => !filterNode(node)) .map((node) => node.id); }</code> | Programmatically expand a subset of nodes.<br />Expands all nodes if no argument is provided     |
+| collapseNodes | <code>function</code> | No       | <code>(filterId?: (node: TreeNode) => boolean) => void</code> | <code>() => { expandedIds = nodes .filter((node) => !filterNode(node)) .map((node) => node.id); }</code> | Programmatically collapse a subset of nodes.<br />Collapses all nodes if no argument is provided |
 
 ### Slots
 

docs/src/COMPONENT_API.json

@@ -13163,6 +13163,50 @@
           "isFunctionDeclaration": false,
           "constant": false,
           "reactive": false
+        },
+        {
+          "name": "expandAll",
+          "kind": "function",
+          "description": "Programmatically expand all nodes",
+          "type": "() => void",
+          "value": "() => {     expandedIds = [...nodeIds];   }",
+          "isFunction": true,
+          "isFunctionDeclaration": true,
+          "constant": false,
+          "reactive": false
+        },
+        {
+          "name": "collapseAll",
+          "kind": "function",
+          "description": "Programmatically collapse all nodes",
+          "type": "() => void",
+          "value": "() => {     expandedIds = [];   }",
+          "isFunction": true,
+          "isFunctionDeclaration": true,
+          "constant": false,
+          "reactive": false
+        },
+        {
+          "name": "expandNodes",
+          "kind": "function",
+          "description": "Programmatically expand a subset of nodes.\nExpands all nodes if no argument is provided",
+          "type": "(filterId?: (node: TreeNode) => boolean) => void",
+          "value": "() => {     expandedIds = nodes       .filter((node) => !filterNode(node))       .map((node) => node.id);   }",
+          "isFunction": true,
+          "isFunctionDeclaration": true,
+          "constant": false,
+          "reactive": false
+        },
+        {
+          "name": "collapseNodes",
+          "kind": "function",
+          "description": "Programmatically collapse a subset of nodes.\nCollapses all nodes if no argument is provided",
+          "type": "(filterId?: (node: TreeNode) => boolean) => void",
+          "value": "() => {     expandedIds = nodes       .filter((node) => !filterNode(node))       .map((node) => node.id);   }",
+          "isFunction": true,
+          "isFunctionDeclaration": true,
+          "constant": false,
+          "reactive": false
         }
       ],
       "slots": [

docs/src/pages/components/TreeView.svx

@@ -45,4 +45,34 @@ Expanded nodes can be set using `expandedIds`.
 
 Initial multiple selected nodes can be set using `selectedIds`.
 
-<FileSource src="/framed/TreeView/TreeViewMultiselect" />
+<FileSource src="/framed/TreeView/TreeViewMultiselect" />
+
+### Expand all nodes
+
+To programmatically expand all nodes, access the component instance using the [bind:this](https://svelte.dev/docs#bind_element) directive and invoke the `TreeView.expandAll()` method to expand all nodes.
+
+<FileSource src="/framed/TreeView/TreeViewExpandAll" />
+
+### Collapse all nodes
+
+Similarly, invoke `TreeView.collapseAll()` to collapse all nodes.
+
+<FileSource src="/framed/TreeView/TreeViewCollapseAll" />
+
+### Expand a subset of nodes
+
+Use the `TreeView.expandNodes` method to expand only a subset of nodes.
+
+The method accepts an argument that takes a node and returns a boolean.
+
+If no argument is provided, all nodes will be expanded.
+
+<FileSource src="/framed/TreeView/TreeViewExpandNodes" />
+
+### Collapse a subset of nodes
+
+Use the `TreeView.collapseNodes` method to collapse a subset of nodes.
+
+If no argument is provided, all nodes will be collapsed.
+
+<FileSource src="/framed/TreeView/TreeViewCollapseNodes" />

docs/src/pages/framed/TreeView/TreeViewCollapseAll.svelte

@@ -0,0 +1,63 @@
+<script>
+  import { TreeView, Button } from "carbon-components-svelte";
+
+  let treeview = null;
+  let expandedIds = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9];
+  let children = [
+    { id: 0, text: "AI / Machine learning" },
+    {
+      id: 1,
+      text: "Analytics",
+      children: [
+        {
+          id: 2,
+          text: "IBM Analytics Engine",
+          children: [
+            { id: 3, text: "Apache Spark" },
+            { id: 4, text: "Hadoop" },
+          ],
+        },
+        { id: 5, text: "IBM Cloud SQL Query" },
+        { id: 6, text: "IBM Db2 Warehouse on Cloud" },
+      ],
+    },
+    {
+      id: 7,
+      text: "Blockchain",
+      children: [{ id: 8, text: "IBM Blockchain Platform" }],
+    },
+    {
+      id: 9,
+      text: "Databases",
+      children: [
+        { id: 10, text: "IBM Cloud Databases for Elasticsearch" },
+        { id: 11, text: "IBM Cloud Databases for Enterprise DB" },
+        { id: 12, text: "IBM Cloud Databases for MongoDB" },
+        { id: 13, text: "IBM Cloud Databases for PostgreSQL" },
+      ],
+    },
+    {
+      id: 14,
+      text: "Integration",
+      disabled: true,
+      children: [{ id: 15, text: "IBM API Connect", disabled: true }],
+    },
+  ];
+</script>
+
+<div>
+  <Button on:click="{treeview?.collapseAll}">Collapse all</Button>
+</div>
+
+<TreeView
+  bind:this="{treeview}"
+  bind:expandedIds
+  labelText="Cloud Products"
+  children="{children}"
+/>
+
+<style>
+  div {
+    margin-bottom: var(--cds-spacing-05);
+  }
+</style>

docs/src/pages/framed/TreeView/TreeViewCollapseNodes.svelte

@@ -0,0 +1,71 @@
+<script>
+  import { TreeView, Button } from "carbon-components-svelte";
+
+  let treeview = null;
+  let expandedIds = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 14];
+  let children = [
+    { id: 0, text: "AI / Machine learning" },
+    {
+      id: 1,
+      text: "Analytics",
+      disabled: true,
+      children: [
+        {
+          id: 2,
+          text: "IBM Analytics Engine",
+          disabled: true,
+          children: [
+            { id: 3, text: "Apache Spark", disabled: true },
+            { id: 4, text: "Hadoop", disabled: true },
+          ],
+        },
+        { id: 5, text: "IBM Cloud SQL Query", disabled: true },
+        { id: 6, text: "IBM Db2 Warehouse on Cloud", disabled: true },
+      ],
+    },
+    {
+      id: 7,
+      text: "Blockchain",
+      children: [{ id: 8, text: "IBM Blockchain Platform" }],
+    },
+    {
+      id: 9,
+      text: "Databases",
+      children: [
+        { id: 10, text: "IBM Cloud Databases for Elasticsearch" },
+        { id: 11, text: "IBM Cloud Databases for Enterprise DB" },
+        { id: 12, text: "IBM Cloud Databases for MongoDB" },
+        { id: 13, text: "IBM Cloud Databases for PostgreSQL" },
+      ],
+    },
+    {
+      id: 14,
+      text: "Integration",
+      disabled: true,
+      children: [{ id: 15, text: "IBM API Connect", disabled: true }],
+    },
+  ];
+</script>
+
+<div>
+  <Button
+    on:click="{() => {
+      treeview?.collapseNodes((node) => node.disabled);
+    }}"
+  >
+    Collapse disabled nodes
+  </Button>
+</div>
+
+<TreeView
+  bind:this="{treeview}"
+  bind:expandedIds
+  labelText="Cloud Products"
+  children="{children}"
+/>
+
+<style>
+  div {
+    margin-bottom: var(--cds-spacing-05);
+  }
+</style>

docs/src/pages/framed/TreeView/TreeViewExpandAll.svelte

@@ -0,0 +1,61 @@
+<script>
+  import { TreeView, Button } from "carbon-components-svelte";
+
+  let treeview = null;
+  let children = [
+    { id: 0, text: "AI / Machine learning" },
+    {
+      id: 1,
+      text: "Analytics",
+      children: [
+        {
+          id: 2,
+          text: "IBM Analytics Engine",
+          children: [
+            { id: 3, text: "Apache Spark" },
+            { id: 4, text: "Hadoop" },
+          ],
+        },
+        { id: 5, text: "IBM Cloud SQL Query" },
+        { id: 6, text: "IBM Db2 Warehouse on Cloud" },
+      ],
+    },
+    {
+      id: 7,
+      text: "Blockchain",
+      children: [{ id: 8, text: "IBM Blockchain Platform" }],
+    },
+    {
+      id: 9,
+      text: "Databases",
+      children: [
+        { id: 10, text: "IBM Cloud Databases for Elasticsearch" },
+        { id: 11, text: "IBM Cloud Databases for Enterprise DB" },
+        { id: 12, text: "IBM Cloud Databases for MongoDB" },
+        { id: 13, text: "IBM Cloud Databases for PostgreSQL" },
+      ],
+    },
+    {
+      id: 14,
+      text: "Integration",
+      disabled: true,
+      children: [{ id: 15, text: "IBM API Connect", disabled: true }],
+    },
+  ];
+</script>
+
+<div>
+  <Button on:click="{treeview?.expandAll}">Expand all</Button>
+</div>
+
+<TreeView
+  bind:this="{treeview}"
+  labelText="Cloud Products"
+  children="{children}"
+/>
+
+<style>
+  div {
+    margin-bottom: var(--cds-spacing-05);
+  }
+</style>

docs/src/pages/framed/TreeView/TreeViewExpandNodes.svelte

@@ -0,0 +1,67 @@
+<script>
+  import { TreeView, Button } from "carbon-components-svelte";
+
+  let treeview = null;
+  let children = [
+    { id: 0, text: "AI / Machine learning" },
+    {
+      id: 1,
+      text: "Analytics",
+      children: [
+        {
+          id: 2,
+          text: "IBM Analytics Engine",
+          children: [
+            { id: 3, text: "Apache Spark" },
+            { id: 4, text: "Hadoop" },
+          ],
+        },
+        { id: 5, text: "IBM Cloud SQL Query" },
+        { id: 6, text: "IBM Db2 Warehouse on Cloud" },
+      ],
+    },
+    {
+      id: 7,
+      text: "Blockchain",
+      children: [{ id: 8, text: "IBM Blockchain Platform" }],
+    },
+    {
+      id: 9,
+      text: "Databases",
+      children: [
+        { id: 10, text: "IBM Cloud Databases for Elasticsearch" },
+        { id: 11, text: "IBM Cloud Databases for Enterprise DB" },
+        { id: 12, text: "IBM Cloud Databases for MongoDB" },
+        { id: 13, text: "IBM Cloud Databases for PostgreSQL" },
+      ],
+    },
+    {
+      id: 14,
+      text: "Integration",
+      disabled: true,
+      children: [{ id: 15, text: "IBM API Connect", disabled: true }],
+    },
+  ];
+</script>
+
+<div>
+  <Button
+    on:click="{() => {
+      treeview?.expandNodes((node) => /^IBM/.test(node.text));
+    }}"
+  >
+    Expand nodes starting with "IBM"
+  </Button>
+</div>
+
+<TreeView
+  bind:this="{treeview}"
+  labelText="Cloud Products"
+  children="{children}"
+/>
+
+<style>
+  div {
+    margin-bottom: var(--cds-spacing-05);
+  }
+</style>

src/TreeView/TreeView.svelte

@@ -44,6 +44,44 @@
   /** Set to `true` to visually hide the label text */
   export let hideLabel = false;
 
+  /**
+   * Programmatically expand all nodes
+   * @type {() => void}
+   */
+  export function expandAll() {
+    expandedIds = [...nodeIds];
+  }
+
+  /**
+   * Programmatically collapse all nodes
+   * @type {() => void}
+   */
+  export function collapseAll() {
+    expandedIds = [];
+  }
+
+  /**
+   * Programmatically expand a subset of nodes.
+   * Expands all nodes if no argument is provided
+   * @type {(filterId?: (node: TreeNode) => boolean) => void}
+   */
+  export function expandNodes(filterNode = (node) => false) {
+    expandedIds = nodes
+      .filter((node) => !filterNode(node))
+      .map((node) => node.id);
+  }
+
+  /**
+   * Programmatically collapse a subset of nodes.
+   * Collapses all nodes if no argument is provided
+   * @type {(filterId?: (node: TreeNode) => boolean) => void}
+   */
+  export function collapseNodes(filterNode = (node) => true) {
+    expandedIds = nodes
+      .filter((node) => !filterNode(node))
+      .map((node) => node.id);
+  }
+
   import { createEventDispatcher, setContext, onMount } from "svelte";
   import { writable } from "svelte/store";
   import TreeViewNodeList from "./TreeViewNodeList.svelte";
@@ -105,6 +143,25 @@
     }
   });
 
+  /**
+   * @param {Array<TreeNode & { children?: TreeNode[] }>} children
+   */
+  function traverse(children) {
+    let nodes = [];
+
+    children.forEach((node) => {
+      nodes.push(node);
+
+      if (Array.isArray(node.children)) {
+        nodes = [...nodes, ...traverse(node.children)];
+      }
+    });
+
+    return nodes;
+  }
+
+  $: nodes = traverse(children);
+  $: nodeIds = nodes.map((node) => node.id);
   $: activeNodeId.set(activeId);
   $: selectedNodeIds.set(selectedIds);
   $: expandedNodeIds.set(expandedIds);

tests/TreeView.test.svelte

@@ -3,6 +3,7 @@
   import type { TreeNodeId } from "../types/TreeView/TreeView";
   import Analytics16 from "carbon-icons-svelte/lib/Analytics16";
 
+  let treeview: TreeView;
   let activeId: TreeNodeId = "";
   let selectedIds = [];
   let expandedIds = [1];
@@ -46,9 +47,21 @@
       children: [{ id: 15, text: "IBM API Connect", disabled: true }],
     },
   ];
+
+  $: if (treeview) {
+    treeview.expandAll();
+    treeview.expandNodes((node) => {
+      return node.id > 0;
+    });
+    treeview.collapseAll();
+    treeview.collapseNodes((node) => {
+      return node.disabled;
+    });
+  }
 </script>
 
 <TreeView
+  bind:this="{treeview}"
   size="compact"
   labelText="Cloud Products"
   children="{children}"

types/TreeView/TreeView.d.ts

@@ -66,4 +66,30 @@ export default class TreeView extends SvelteComponentTyped<
     keydown: WindowEventMap["keydown"];
   },
   { labelText: {} }
-> {}
+> {
+  /**
+   * Programmatically expand all nodes
+   * @default () => { expandedIds = [...nodeIds]; }
+   */
+  expandAll: () => void;
+
+  /**
+   * Programmatically collapse all nodes
+   * @default () => { expandedIds = []; }
+   */
+  collapseAll: () => void;
+
+  /**
+   * Programmatically expand a subset of nodes.
+   * Expands all nodes if no argument is provided
+   * @default () => { expandedIds = nodes .filter((node) => !filterNode(node)) .map((node) => node.id); }
+   */
+  expandNodes: (filterId?: (node: TreeNode) => boolean) => void;
+
+  /**
+   * Programmatically collapse a subset of nodes.
+   * Collapses all nodes if no argument is provided
+   * @default () => { expandedIds = nodes .filter((node) => !filterNode(node)) .map((node) => node.id); }
+   */
+  collapseNodes: (filterId?: (node: TreeNode) => boolean) => void;
+}