Design for tree view component

[designertyler]

Based on the proposal in this issue #2230

Design Specs

Text (small and extra small sizes)

Text and icon (small and extra small sizes)

Target areas and behaviors

Sketch kit/library

https://www.sketch.com/s/c6f33ba0-b5c7-46b3-9c73-5ead5eb2caa7

Usage docs

https://carbon-website-git-fork-designertyler-treeview03092020.carbon-design-system.now.sh/components/tree-view/usage/

User Requirements

As an end user I want to...

• Select a parent node without expanding the children so a user can see information tied to the parent node.
• Open a parent node without it taking selection so I can keep my current selection in view while I open/close other nodes in the tree.
• Add any number of children or parent nodes under a parent so a user is not limited to one type of child.
• Have multiple parent nodes open at the same time so I can browse without losing my orientation.
• Collapse a parent with a selected child without the parent taking the selection state to avoid accidental selection change.
• See which node is selected even if the parent node is collapsed so I know when a hidden child is selected (Parent node inherits the selected state?)
• Have my opened nodes remain open even if their parent is collapsed and then opened again. The nodes should remain in the same open or closed state.

As a product team implementing a data tree, I want to...

• Have the option to represent the node's file type by an icon so the user can understand the node's file type.
• Have the option to not use a file type icon when the file type is not important for my data.
• Show a node as disabled so the user knows it cannot be active.

Accessibility Requirements

Support the ARIA keyboard and mouse behaviors for tree view here https://w3c.github.io/aria-practices/#keyboard-interaction-23 2 so the user's expectations are consistent for other trees.

Keyboard Behaviors for a vertically oriented tree:

• When a single-select tree receives focus:
• If none of the nodes are selected before the tree receives focus, focus is set on the first node.
• If a node is selected before the tree receives focus, focus is set on the selected node.
• When a multi-select tree receives focus:
• If none of the nodes are selected before the tree receives focus, focus is set on the first node.
• If one or more nodes are selected before the tree receives focus, focus is set on the first selected node.

Right arrow
When focus is on a closed node, opens the node; focus does not move.
When focus is on a open node, moves focus to the first child node.
When focus is on an end node, does nothing.

Left arrow
When focus is on an open node, closes the node.
When focus is on a child node that is also either an end node or a closed node, moves focus to its parent node.
When focus is on a root node that is also either an end node or a closed node, does nothing.

Down Arrow
Moves focus to the next node that is focusable without opening or closing a node.

Up Arrow
Moves focus to the previous node that is focusable without opening or closing a node.

Home:
Moves focus to the first node in the tree without opening or closing a node.

End
Moves focus to the last node in the tree that is focusable without opening a node.

Enter
Activates a node, i.e., performs its default action. For parent nodes, one possible default action is to open or close the node. In single-select trees where selection does not follow focus (see note below), the default action is typically to select the focused node.

Type-ahead is recommended for all trees, especially for trees with more than 7 root nodes:

Type a character
Focus moves to the next node with a name that starts with the typed character.

Type multiple characters in rapid succession
Focus moves to the next node with a name that starts with the string of characters typed.
(Optional): Expands all siblings that are at the same level as the current node.

Mouse Behaviors

• Click on a node sets focus and selects the node
• Ctrl-click on a node focuses and selects the node. Previous selections are maintained.
• Double click on an end node causes any associated action to be invoked. Open issue: are there ever parent nodes that have an action other than expand or collapse?
• Click on a closed node opens the node.
• Click on expand / collapse icon associated with a parent node toggles the expand/collapse of the node

Explorations

• Aesthetics are closer to the left nav than the accordion.

• A line-height at 32px

• Dividing rules give the tree a closer appearance to the accordion and disrupts the indented grouping of the children nodes if they go full width

• Using the 16px caret instead of the chevron. The use of a caret reduces the amount of noise when used with the file type icons that are illustrated with a similar line to the chevron and +/-. The chevron can also be placed against file type icons to give more horizontal room for the node title.

• Offer variants with file type icon and without file type icon

• custom icon (for nodes and/or expand/collapse icon)

• Node type (File type) represented by an icon

• Should there be a list counterpart for when there are no children nodes? What does a tree look like where there are no children? Is it just a list?

• Hover state

• Should parent nodes have a folder file type icon or just the caret? With no parent file type, the alignment of the children nodes is clearer. Not having this icon works better if we chose to use vertical rules for grouping children nodes.
  

To do:

• Sync up with IoT and their list component
• Sync with cloud and their tree
• Review with Carbon design team
• Review with Carbon development team
• Write docs based on the latest component template.

Reference:

• Follow W3C standards here https://www.w3.org/wiki/TreeView and here https://www.w3.org/TR/aria-role/roles#tree
• Prototype example from WKC https://pages.github.ibm.com/conrad-schmidt/Tree/build/
• Specs from WKC https://ibm.box.com/s/azascty1rmgik858zy1kw3cw6f0a4zo1
• Target size for pointer input must be 44 by44 pixels (AAA) https://www.w3.org/WAI/WCAG21/Understanding/target-size.html
• Tree grid https://www.w3.org/TR/aria-role/roles#treegrid
• Tree role https://www.w3.org/TR/aria-role/roles#tree
• https://www.w3.org/TR/aria-role/roles#treeitem
• Data structures https://en.wikipedia.org/wiki/List_of_data_structures#Trees

[wangweiu]

My project need a tree view component on React. May I know when this will be in Carbon? Thanks.

[loganmccaul]

@designertyler Really awesome work here! We have a coded version of the Tree in Cloud PAL that could be adapted to for this.

[vincent-pli]

@designertyler
Hi, I wonder the statue of this feature, i have to use DataTable to implements my treeview now, thanks.

[emyarod]

the features we planned for the first version of the component are complete, we are just fulfilling some important accessibility requirements and testing before releasing

[vincent-pli]

@emyarod Thanks for quick reply, so how long could i adopt the new feature? or is the feature already ready in the master?

[emyarod]

the v1 feature set is ready (pending a11y review) and will be included in an upcoming release this month

[vincent-pli]

@emyarod
Glad to hear that, thanks very much.

[apiconnecttesting]

Hi, looking forward to the component to go live! But I get questions on the pattern below:

1. Icon for the collapsed and expanded state
2. The chevron direction(point to the right instead of the top when collapsed)
   Any reason why we have different patterns for these?

[designertyler]

@apiconnecttesting That’s a good question. The main driver for having the collapsed state point right was most data trees follow that behavior so many users will be familiar with the meaning of those two states.

An issue with the caret pointing up for collapsed is that it takes that extra time to determine if the icon represents the current state of the node or the action it will take if I click on it.
An advantage of using a right-pointing caret for closed and down-pointing for open is that it reinforces the flow and hierarchy of the data.

We also considered + and - and may consider adding them as an option.

Did you have feedback for using one pattern vs. the other?

[andrea-island]

@emyarod any update on this?

[emyarod]

IBM Accessibility is currently investigating accessible navigation patterns for this component. Until we have the green light to release, I am looking to first release this behind an experimental feature flag

[carmacleod]

Reminder that the Usage docs are missing the Interactions section with its Mouse, Keyboard, and Screen readers subsections under Behaviors (note that in other Carbon doc, this is called "Behaviors" and not "Behavior").

[carmacleod]

Is this a typo? Should this line just be deleted?

Ctrl-Arrow-Space - Selects non-contiguous nodes

It is already covered by the line that immediately follows it:

Ctrl-Spacebar with focus on an item toggles the selection of the item

[designertyler]

Is this a typo? Should this line just be deleted?

Ctrl-Arrow-Space - Selects non-contiguous nodes

It is already covered by the line that immediately follows it:

Ctrl-Spacebar with focus on an item toggles the selection of the item

@carmacleod These keyboard behaviors were sourced from https://www.w3.org/wiki/TreeView

I believe the first one behavior is meant to enable multi selection behavior similar to what you can do with the mouse:
This animation shows the mouse:

• Click on UI-shell-left-panel
  (UI-shell-left-panel is selected)
• Shift+click on breadcrumb
  (The nodes within the range are automatically selected)
• Shift+command+click on text-input and tile
  (those nodes are selected individually rather than the range.)
  

I'll update the usage docs. I think they were following an old version of the template and I haven't touched them in a while. Thanks for the feedback!

[carmacleod]

Note that the TreeView keyboard behaviors section in the Aria Practices Guide has a subsection for Selection in multi-select trees that is missing from this issue, but should be followed when the tree is multiselectable.

You won't be able to implement the "Recommended selection model" because you want unmodified Space key to select and "activate" (i.e. perform the default action, just like the Enter key). So you need to look at implementing the "Alternative selection model".

[carmacleod]

These keyboard behaviors were sourced from https://www.w3.org/wiki/TreeView

I would lean more heavily on the ARIA Practices Guide for recommended keyboard shortcuts. That wiki page was last updated in 2012, and "Ctrl-Arrow-Space" isn't really a thing. :)

Click... Shift+click... Shift+command+click...

For mouse behaviors, you will want to go with Command+click for non-contiuous selection (not Shift+command+click).

I'll update the usage docs.

Thanks @designertyler !

[joseph00]

Hi! Any update about the TreeView? Would love to hear how it's development is going! :)

[tw15egan]

@joseph00 it was merged in 8 days ago (#6008) and should be included in the next release (10.19.0) scheduled for later this week 🙂

[akmalmzamri]

Is there a sample code on how to use it? I tried this but seems like it doesn't have any styling applied:
CodeSandbox

Edit: Nevermind. Found out I have to import the styling manually:
import "carbon-components/scss/components/treeview/_treeview.scss";

Is this because it's an experimental feature?

[pascal-potvin]

Do we have an idea of when this will go live?

[emyarod]

the experimental component is already available to use, but further enhancements and variations have been delayed for the time being

[pascal-potvin]

the experimental component is already available to use, but further enhancements and variations have been delayed for the time being

Thanks @emyarod for the swift response. Is this the experimental aspect I should be sharing with my teams? https://codesandbox.io/s/polished-glitter-zkcss?file=/src/App.js

[emyarod]

@pascal-potvin yes, if it works for your use case!

[mtucciarone]

Is there checkbox support for this? Can't wait for it to come out 👍

[emyarod]

@mtucciarone progress on this enhancement will be slow but it is on the roadmap

[AmirHussain93]

@emyarod is there a support for loading data on demand in this tree view component ?

[emyarod]

@AmirHussain93 currently there is not, but there are explorations for it so it may be a future enhancement

[AmirHussain93]

@emyarod okay thanks for the quick reply

[BrHowell]

Hi. Is the Sketch library no longer available?

[laurenmrice]

@BrHowell The link in this issue was broken. I found the correct link https://www.sketch.com/s/c6f33ba0-b5c7-46b3-9c73-5ead5eb2caa7.

Eventually we will be transferring tree view into the Carbon theme sketch cloud libraries as a component once the code is stable.

[jonathandick]

Apologize if this is documented somewhere else but is this component still being worked on by the Carbon team? If so, is there any chance it will be part of release 11?

[laurenmrice]

@jonathandick The treeview component will not be part of the official first version of the v11 release. However, developers on the Carbon for Dotcom team will be building treeview sometime this year. I do not have an exact of when it will be available yet.

[jonathandick]

Thank you for the rapid feedback and looking forward to the release of this feature.

We (Openmrs.org) use the Carbon design system to support an open-source EMR primarily used to support HIV care programs and humanitarian relief projects in LMICs. We are so grateful to the Carbon team for all the great work you do!