Tree Specification

IgxTree Specification

Revision History

Version	User	Date	Notes
0.1	Viktor Slavov	Jan 27, 2021	Initial Draft

1. Overview

Objectives

The IgxTreeComponent is a data-bindable component that provides users with an easy way of visualizing hierarchical data in a tree view.

2. User and Developer Stories

User Stories

As an end-user, I want to:

have hierarchical data visualized in a pleasing and easy-to-navigate way
be able to expand and collapse tree nodes so I can always have only the most viable information visible on my screen
- have a visually pleasing transition between opened and closed node states
have a node highlighted to better keep track of the information I'm looking at
be able to quickly navigate through and expand/collapse nodes of the tree using a mouse
be able to quickly navigate through and expand/collapse nodes of the tree using a keyboard
mark a single node as selected, using my mouse and a specific UI part
mark a single node as selected, using my keyboard
mark a single node as selected, also marking all of its descendants
have a visual indicator if:
- a node is selected
- if all of a node's descendants are marked as selected
- if some of a node's descendants are marked as selected
- if none of a node's descendants are marked as selected
be able to rearrange data in via drag and drop, considering that I can achieve the following:
- move a node to a different parent
- rearrange nodes under the same parent
- have a visual indicator of the expected result of my drag-and-drop interaction
be able to discern when a node's information is being loaded (load-on-demand scenario)

Developer Stories

As a developer, I want to:

be able to quickly create a tree view by binding the component to hierarchical data
have control over the way individual nodes are displayed (templating)
have an easy way to find a node inside of the control with OOB API
expand/collapse a single or multiple nodes programmatically
enable/disable selection for nodes and differentiate between selection scenarios:
- selecting a node marks only the focused node for as selection
- selecting a node marks the focused node and all child nodes as selected
set a node's selection state programmatically
manipulated the bound data through the control
be able to perform custom handling on user interaction - node selection, toggling
be able to control the opening / closing animation of nodes
be able to load data on demand to expediate initial load times
- be able to control the way that data loading is presented to the use (templating)

Examples:

<!-- Standard example -->
<igx-tree [...inputs]>
	<igx-tree-node *ngFor="let nodes of data" [data]="node" [expanded] [selected]>
		{{ node.text }}
		<img [src]="node.image" alt="node.imageAlt" />
		
		<igx-tree-node *ngFor="let children of node.children" [data]="children" [expanded] [selected]>
			<igx-tree-url-node *ngFor="let leafchild of children.children" [data]="leafchild" [url]="leafchild.url" target="_blank">
				<a href="node.url">{{ node.text }}</a>
			</igx-tree-url-node>
		</igx-tree-node>
	</igx-tree-node>
</igx-tree>

<!-- Simple example with hardcoded nodes -->
<igx-tree [...inputs]>
	<igx-tree-node [expanded] [selected]>
		I am a parent node
		<img [src]="hard_coded_src.webb" alt="Alt Text" />
		
		<igx-tree-node [expanded] [selected]>
			I am a child node
			<igx-tree-url-node [url]="https://google.com">
				I am a child node of the child
			</igx-tree-url-node>
		</igx-tree-node>
	</igx-tree-node>
	
	<igx-tree-node [expanded] [selected]>
		I am a parent node 2
		<img [src]="hard_coded_src.webb" alt="Alt Text" />
		
		<igx-tree-node [expanded] [selected]>
			I am a child node
		</igx-tree-node>
	</igx-tree-node>

	<igx-tree-node [expanded] [selected]>
		I am a parent node 3
		<img [src]="hard_coded_src.webb" alt="Alt Text" />
		
		<igx-tree-node [expanded] [selected]>
			I am a child node 1
		</igx-tree-node>
	</igx-tree-node>
</igx-tree>

// Custom node resolver for different layer bindings
const resolver = (nodeData: any, value: any) => nodeData.productId === value;

End User Experience

Scenarios:

TBD
TBD
TBD
TBD

3. Functionality

3.1. Keyboard Navigation

Node navigation

Keyboard can be used to navigate through all nodes in the tree. FIRST and LAST node refers to the respective visible node WITHOUT expanding/collapsing any existing node

ARROW DOWN moves to the next visible node. Does nothing if on the LAST node.
ARROW UP moves to the previous visible node. Does nothing if one the FIRST node.
TAB performs the same as ARROW DOWN. If on the FIRST node, moves to the next element w/ tabIndex outside of the tree.
SHIFT + TAB performs the same as ARROW UP. If on the LAST node, moves to the previous element w/ tabIndex outside of the tree.
HOME navigates to the FIRST node.
END navigates to the LAST node.
ARROW RIGHT on an expanded parent node navigates to the first child of the node.
ARROW LEFT on a child node navigates to the parent node.

Toggling nodes

Node expanded state can be toggled via keyboard interaction w/ ARROW KEYS.

ARROW LEFT collapses and expanded node. If the node is already collapsed and is not a child node itself - does nothing.
ARROW RIGHT expands a collapsed node. If the node is already expanded - moves to the first child node.

Selection

When selection is enabled, node can be selected via keyboard interaction.

SPACE toggles a node's selection state (selected/deselected).

3.2. API

IgxTreeNode

A representation of the node state

Properties

Name	Description	Type
id	The unique id of the tree node	`string`
parentId	The unique id of the parent node, if any	`string` \| `null`
expanded	If the node is expanded	`boolean` \| `null`
selected	If the node is selected	`boolean`
tree	A reference to the tree the node is a part of	`IgxTree`
data	The data bound to a node	`any`
level	The "depth" of the node. If root node - 0, if a child of parent - `parent.level` + 1	`number`
children	A collection of child nodes. `null` if node does not have children	`any[]` \| `null`
valueKey	The property from the bound data object that should be used for the node's ID	`string`
textKey	The property from the bound data object that should be used for the node's display text	`string`
childKey	The property from the bound data object that should be used for a node's child collection	`string`
index	The node's index in the parent node's context	`string`

IgxTree

Accessors

Get

Name	Description	Type
id	The unique id of tree	`string`
rootNodes	The collection of root nodes of the tree	`IgxTreeNode[]`

Properties

Name	Description	Type
selection	The selection state of the tree	`"None"`
data	The data bound to the tree	`any[]`
animationSettings	The setting for the animation when opening / closing a node	`{ openAnimation: AnimationMetadata, closeAnimation: AnimationMetadata }`
valueKey	The property from the bound data object that should be used for the node's ID	`string`
textKey	The property from the bound data object that should be used for the node's display text	`string`
childKey	The property from the bound data object that should be used for a node's child collection	`string`

Methods

Name	Description	Parameters
findNode	Returns a reference to a specified node. Param is the path to the node or the unique nodeId	`nodePath: string[]
toggle	Toggles a specified node	`nodeId: string`
expand	Expands a specified node	`nodeId: string`
close	Closes the IgxSelect.	none
select	Marks the specified node as selected	`nodeId: string`
deselect	Deselects the specified node as selected	`nodeId: string`
setSelection	Sets the specified nodes as selected, clearing the previous selection	`nodeIds: string[]`
selectAll	Sets all nodes as select. If a parent id is provided, set all child nodes as selected	`parentNodeId?: string`
deselectAll	Deselects all nodes. If a parent id is provided, deselect all child nodes	`parentNodeId?: string`
deleteNode	Removes a node from the tree and bound data object	`nodeId: string`
addNode	Adds a node to the tree and the bound data object. If a parent node is specified, insert the new node as a child	`data: any`, `parentId?: string`

Events

Name	Description	Cancelable	Parameters
onSelection	Emitted when item selection is changing, before the selection completes	true	TBD
onOpening	Emitted before the a node is opened.	true	TBD
onOpened	Emitted after the a node is opened.	false	TBD
onClosing	Emitted before the a node is closed.	true	TBD
onClosed	Emitted after the a node is closed.	false	TBD
onNodeDragStart	Emitted when a node drag is stared	true	TBD
onNodeDragMove	Emitted when the cursor moves while a node dragged	false	TBD
onNodeDrop	Emitted when a node is dropped	false	TBD