feat(tree-view): make node slottable (#1843)

Closes #1660
carbon-design-system · Nov 12, 2023 · 6a55fef · 6a55fef
1 parent 417102d
commit 6a55fef
Show file tree

Hide file tree

Showing 9 changed files with 150 additions and 18 deletions.
diff --git a/COMPONENT_INDEX.md b/COMPONENT_INDEX.md
@@ -4707,9 +4707,10 @@ export interface TreeNode {
 
 ### Slots
 
-| Slot name | Default | Props | Fallback                 |
-| :-------- | :------ | :---- | :----------------------- |
-| labelText | No      | --    | <code>{labelText}</code> |
+| Slot name | Default | Props                                                                                                                             | Fallback                 |
+| :-------- | :------ | :-------------------------------------------------------------------------------------------------------------------------------- | :----------------------- |
+| --        | Yes     | <code>{ node: { id: TreeNodeId; text: string; expanded: boolean, leaf: boolean; disabled: boolean; selected: boolean; } } </code> | <code>{node.text}</code> |
+| labelText | No      | --                                                                                                                                | <code>{labelText}</code> |
 
 ### Events
 

diff --git a/docs/src/COMPONENT_API.json b/docs/src/COMPONENT_API.json
@@ -14668,6 +14668,12 @@
       ],
       "moduleExports": [],
       "slots": [
+        {
+          "name": "__default__",
+          "default": true,
+          "fallback": "{node.text}",
+          "slot_props": "{ node: { id: TreeNodeId; text: string; expanded: boolean, leaf: boolean; disabled: boolean; selected: boolean; } }"
+        },
         {
           "name": "labelText",
           "default": false,

diff --git a/docs/src/pages/components/TreeView.svx b/docs/src/pages/components/TreeView.svx
@@ -1,5 +1,5 @@
 <script>
-  import { InlineNotification } from "carbon-components-svelte";
+  import { InlineNotification, UnorderedList, ListItem } from "carbon-components-svelte";
   import Preview from "../../components/Preview.svelte";
 </script>
 
@@ -17,6 +17,23 @@ A parent node contains `children` while a leaf node does not.
 
 <FileSource src="/framed/TreeView/TreeView" />
 
+## Slottable node
+
+By default, each item renders the value of `node.text`. Use the data from `let:node` directive to override the default slot.
+
+The destructured `let:node` contains the following properties:
+
+<UnorderedList svx-ignore style="margin-bottom: var(--cds-spacing-08)">
+  <ListItem><strong>id</strong>: the node id</ListItem>
+  <ListItem><strong>text</strong>: the node text</ListItem>
+  <ListItem><strong>expanded</strong>: true if the node is expanded</ListItem>
+  <ListItem><strong>leaf</strong>: true if the node does not have children</ListItem>
+  <ListItem><strong>disabled</strong>: true if the node is disabled</ListItem>
+  <ListItem><strong>selected</strong>: true if the node is selected</ListItem>
+</UnorderedList>
+
+<FileSource src="/framed/TreeView/TreeViewSlot" />
+
 ## Initial active node
 
 The active node can be set through `activeId`.

diff --git a/docs/src/pages/framed/TreeView/TreeViewSlot.svelte b/docs/src/pages/framed/TreeView/TreeViewSlot.svelte
@@ -0,0 +1,61 @@
+<script>
+  import { TreeView } from "carbon-components-svelte";
+
+  let activeId = 0;
+  let selectedIds = [0, 7, 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>
+
+<TreeView
+  labelText="Cloud Products"
+  activeId="{activeId}"
+  selectedIds="{selectedIds}"
+  children="{children}"
+  let:node
+>
+  <span
+    style:color="{node.selected ? "var(--cds-interactive-04)" : "inherit"}"
+    style:text-decoration="{node.disabled ? "inherit" : "underline"}"
+  >
+    {node.text} (id: {node.id})
+  </span>
+</TreeView>
diff --git a/src/TreeView/TreeView.svelte b/src/TreeView/TreeView.svelte
@@ -2,6 +2,7 @@
   /**
    * @typedef {string | number} TreeNodeId
    * @typedef {{ id: TreeNodeId; text: any; icon?: typeof import("svelte").SvelteComponent<any>; disabled?: boolean; children?: TreeNode[]; }} TreeNode
+   * @slot {{ node: { id: TreeNodeId; text: string; expanded: boolean, leaf: boolean; disabled: boolean; selected: boolean; } }}
    * @event {TreeNode & { expanded: boolean; leaf: boolean; }} select
    * @event {TreeNode & { expanded: boolean; leaf: boolean; }} toggle
    * @event {TreeNode & { expanded: boolean; leaf: boolean; }} focus
@@ -202,5 +203,9 @@
   on:keydown
   on:keydown|stopPropagation="{handleKeyDown}"
 >
-  <TreeViewNodeList root children="{children}" />
+  <TreeViewNodeList root children="{children}" let:node>
+    <slot node="{node}">
+      {node.text}
+    </slot>
+  </TreeViewNodeList>
 </ul>
diff --git a/src/TreeView/TreeViewNode.svelte b/src/TreeView/TreeViewNode.svelte
@@ -34,6 +34,7 @@
 <script>
   /**
    * @typedef {string | number} TreeNodeId
+   * @slot {{ node: { id: TreeNodeId; text: string; expanded: false, leaf: boolean; disabled: boolean; selected: boolean; } }}
    */
 
   export let leaf = false;
@@ -68,7 +69,16 @@
     prevActiveId = $activeNodeId;
   });
 
-  $: node = { id, text, expanded: false, leaf };
+  $: selected = $selectedNodeIds.includes(id);
+  $: node = {
+    id,
+    text,
+    // A node cannot be expanded.
+    expanded: false,
+    leaf,
+    disabled,
+    selected,
+  };
   $: if (refLabel) {
     refLabel.style.marginLeft = `-${offset()}rem`;
     refLabel.style.paddingLeft = `${offset()}rem`;
@@ -82,12 +92,12 @@
   id="{id}"
   tabindex="{disabled ? undefined : -1}"
   aria-current="{id === $activeNodeId || undefined}"
-  aria-selected="{disabled ? undefined : $selectedNodeIds.includes(id)}"
+  aria-selected="{disabled ? undefined : selected}"
   aria-disabled="{disabled}"
   class:bx--tree-node="{true}"
   class:bx--tree-leaf-node="{true}"
   class:bx--tree-node--active="{id === $activeNodeId}"
-  class:bx--tree-node--selected="{$selectedNodeIds.includes(id)}"
+  class:bx--tree-node--selected="{selected}"
   class:bx--tree-node--disabled="{disabled}"
   class:bx--tree-node--with-icon="{icon}"
   on:click|stopPropagation="{() => {
@@ -116,6 +126,8 @@
 >
   <div bind:this="{refLabel}" class:bx--tree-node__label="{true}">
     <svelte:component this="{icon}" class="bx--tree-node__icon" />
-    {text}
+    <slot node="{node}">
+      {text}
+    </slot>
   </div>
 </li>
diff --git a/src/TreeView/TreeViewNodeList.svelte b/src/TreeView/TreeViewNodeList.svelte
@@ -2,6 +2,7 @@
   /**
    * @typedef {string | number} TreeNodeId
    * @typedef {{ id: TreeNodeId; text: string; disabled?: boolean; expanded?: boolean; }} TreeNode
+   * @slot {{ node: { id: TreeNodeId; text: string; expanded: boolean, leaf: boolean; disabled: boolean; selected: boolean; } }}
    */
 
   /** @type {Array<TreeNode & { children?: TreeNode[] }>} */
@@ -66,25 +67,30 @@
 {#if root}
   {#each children as child (child.id)}
     {#if Array.isArray(child.children)}
-      <svelte:self {...child} />
+      <svelte:self {...child} let:node>
+        <slot node="{node}" />
+      </svelte:self>
     {:else}
-      <TreeViewNode leaf {...child} />
+      <TreeViewNode leaf {...child} let:node>
+        <slot node="{node}" />
+      </TreeViewNode>
     {/if}
   {/each}
 {:else}
+  {@const selected = $selectedNodeIds.includes(id)}
   <!-- svelte-ignore a11y-no-noninteractive-element-to-interactive-role -->
   <li
     bind:this="{ref}"
     role="treeitem"
     id="{id}"
     tabindex="{disabled ? undefined : -1}"
     aria-current="{id === $activeNodeId || undefined}"
-    aria-selected="{disabled ? undefined : $selectedNodeIds.includes(id)}"
+    aria-selected="{disabled ? undefined : selected}"
     aria-disabled="{disabled}"
     class:bx--tree-node="{true}"
     class:bx--tree-parent-node="{true}"
     class:bx--tree-node--active="{id === $activeNodeId}"
-    class:bx--tree-node--selected="{$selectedNodeIds.includes(id)}"
+    class:bx--tree-node--selected="{selected}"
     class:bx--tree-node--disabled="{disabled}"
     class:bx--tree-node--with-icon="{icon}"
     aria-expanded="{expanded}"
@@ -151,16 +157,20 @@
       </span>
       <span class:bx--tree-node__label__details="{true}">
         <svelte:component this="{icon}" class="bx--tree-node__icon" />
-        {text}
+        <slot node="{{ ...node, selected, disabled }}" />
       </span>
     </div>
     {#if expanded}
       <ul role="group" class:bx--tree-node__children="{true}">
         {#each children as child (child.id)}
           {#if Array.isArray(child.children)}
-            <svelte:self {...child} />
+            <svelte:self {...child} let:node>
+              <slot node="{node}" />
+            </svelte:self>
           {:else}
-            <TreeViewNode leaf {...child} />
+            <TreeViewNode leaf {...child} let:node>
+              <slot node="{node}">{node.text}</slot>
+            </TreeViewNode>
           {/if}
         {/each}
       </ul>

diff --git a/tests/TreeView.test.svelte b/tests/TreeView.test.svelte
@@ -72,4 +72,12 @@
   on:select="{({ detail }) => console.log('select', detail)}"
   on:toggle="{({ detail }) => console.log('toggle', detail)}"
   on:focus="{({ detail }) => console.log('focus', detail)}"
-/>
+  let:node
+>
+  {node.id}
+  {node.disabled}
+  {node.expanded}
+  {node.leaf}
+  {node.selected}
+  {node.text}
+</TreeView>
diff --git a/types/TreeView/TreeView.svelte.d.ts b/types/TreeView/TreeView.svelte.d.ts
@@ -68,7 +68,19 @@ export default class TreeView extends SvelteComponentTyped<
     focus: CustomEvent<TreeNode & { expanded: boolean; leaf: boolean }>;
     keydown: WindowEventMap["keydown"];
   },
-  { labelText: {} }
+  {
+    default: {
+      node: {
+        id: TreeNodeId;
+        text: string;
+        expanded: boolean;
+        leaf: boolean;
+        disabled: boolean;
+        selected: boolean;
+      };
+    };
+    labelText: {};
+  }
 > {
   /**
    * Programmatically expand all nodes