igxTreeGrid Specification

Owned by

CodeX

Diyan Dimitrov

Stefan Ivanov

Requires approval from

Peer Developer Name | Date:
Stefan Ivanov | Date:

Signed off by

Radoslav Mirchev | Date:
Radoslav Karaivanov | Date:

Revision History

Version	Users	Date	Notes
1	Diyan Dimitrov, Stefan Ivanov	29 Oct 2020	Updating spec format

1. Overview

The igxTreeGrid control is intended to visualize hierarchical data with consistent data schema in the tabular fashion of the igxGrid. Tree Grid's default styling follows Google's material design guidelines and is consistent with the igxGrid.

Objectives

Provide Ignite UI for Angular igxTreeGrid component that supports the existing igxGrid features:

Sorting
Filtering
Editing
Paging
Virtualization - Row and column
Multi-column headers
Templates
Row, Cell and Column Selection
Column Summaries
Column hiding
Column pinning
Column moving
Data-binding
Export to Excel

Acceptance criteria

Must-have before we can consider the feature a sprint candidate

...

2. User Stories

Developer stories:

Story 1: As a developer, I want to hide particular columns under certain conditions, so that I can show them again when these conditions change and it makes sense to have them visible again.
Story 2: As a developer, I want to freeze some columns by default, so that the user is unable to move and reorder them around the grid.
Story 3: As a developer, I want to specify if updating the content of the TreeGrid is allowed or not – is it editable or read-only.
Story 4: As a developer, I want to show a particular node in the hierarchy upon initial rendering of the grid. I need to be able to set the number of levels which are initially expanded below the root level in order for that node’s parent to be expanded and thus the node be visible on initialization.
Story 5: As a developer, I want to decide whether the expand state is persisted or not, so that when the grid is redrawn for any reason it either keeps this expanded state or resets it (sets it to the initial state).
Story 6: As a developer, I want to specify which columns are allowed to be placed to the left of the grid and serve as the one to represent visually the tree hierarchy. For some columns it makes a lot of sense to do so while for others it does not make any (e.g. imagine a company organization: names, positions and departments make sense to act as tree columns while salary, starting date and type of contract do not).
Story 7: As a developer, I want to offer aggregated information for a given level in the hierarchy of the grid. This can be achieved through a special row that can be either on top of the group of entries as a header or just below it as a footer.
Story 8: As a developer, I want to configure whether the selection is single or multiple. By default, row selection is disabled.
Story 9: As a developer, I want to enable a multiple selection mode in a cascading fashion. By default the multiple selection mode allows the end-user to select records one by one like in a flat grid.

End-user stories:

Story 1: As an end-user, I want to have a visual indication in the form of an icon, showing that a given node (root or non-leaf) has children. The icon can be enhanced to further show the specific number of non-leaf or leaf level children that the node has.
Story 2: As an end-user, I expect that non-leaf and leaf-level nodes are indented in a way that indicates how they relate to their parent.
Story 3: As an end-user, I want to filter the entries for a certain column, so that only records matching the criterion that I have set are displayed and their parents in a grayed-out fashion to provide additional context. Filtering is applied to all hierarchy levels meaning that all nodes matching the criterion are shown by expanding their parents when needed.
Story 4: As an end-user, I want to sort the records in the tree grid in ascending/descending order by any column, representing the property of the entry. Sorting would work between siblings in the data hierarchy and will affect all levels and records recursively.
Story 5: As an end-user, when I refresh the grid (or trigger another action that re-renders it) the old state of the layout (expanded/collapsed levels) should be retained and reflected after the grid is redrawn on the screen.
Story 6: As an end-user, I want to adjust the size of the columns, so that they fit the content in a way that is suitable and useful for me.
Story 7: As an end-user, I want to be able to pin a certain column to the left of the tree grid, and this way it will always stay visible upon horizontally scrolling the grid.
Story 8: As an end-user, I want to hide particular columns when my current needs dictate this. Of course, later on, I need to be able to make these columns visible again.
Story 9: As an end-user, I want to have the ability to reorder the columns in a way to help me deal with my current task without this causing any change to the hierarchy.
Story 10: As an end-user, I expect that tree grids with a lot of records are split into pages with a certain number of items per page, and indentation is properly carried over from the current page to the next one.
Story 11: As an end-user, I expect that records can be moved in the hierarchy, which would affect the internal structure of the data shown in the tree grid.
Story 12: As an end-user, I want to navigate the hierarchy with the keyboard using:
- ↑ – go the row above
- ↓ – go the row below
- → – expand the node if it has children
- ← – collapse the node and more... TODO
Story 13: As an end-user, I want to have a visualization of the hierarchical belonging of my currently selected item in a toolbar and be able to easily perceive how it is related to the root level of the hierarchy (e.g. an indication similar to the path to a file on the file system).
Story 14: As an end-user, I want to have a special row that serves to aggregate information for a set of entries in the grid. This special row can be either on top of the group of entries as a header or just below it as a footer. Such header/footer is usually employed to summarize the data for a certain level of the hierarchy.

3. Functionality

The tree grid shows hierarchical data giving context about records that have children by showing an expand indicator at the beginning of the row and indenting it according to the level it has in the hierarchy. The expand/collapse indicator also serves as a means for navigating the data.

3.1. End-User Experience

Filtering in the tree grid returns all matching records, where for records deeper in the hierarchy it also shows a trace of the direct parent hierarchy up to root level applying a grayed-out style on the parents that are not matching the filtering conditions.

Row and Cell Selection (select all included). Akin to the igx-grid, the tree grid supports none, single, and multiple as modes for row selection, but they work differently given the hierarchical nature of the data in the Tree Grid:

none - row selection is disabled. This is the default mode.
single - selection of only one row within the tree grid would be available.
multiple - multiple row selection would be available by using the row selectors, with a key combination like ctrl + click, or by pressing the space key once a cell is focused. With multiple selection enabled it is also possible to additionally specify its behavior via the cascadeSelection boolean property which is false by default allowing you to select records one by one as in a flat grid (before selection on the left and after it on the right).

When set to true the selection is cascading, resulting in the selection of all children in the tree below the record that the user selects with user interaction. In this mode when a parent has some selected and some deselected children, its checkbox is in an indeterminate state. (before selection on the left and after it on the right).

Column Summaries are defined on the grid level akin to the flat grid and for any given hierarchical context or level akin to the flat grid with Group By applied.

3.2. Developer Experience

3.3. Globalization/Localization

Describe any special localization requirements such as the number of localizable strings, regional formats

3.4. Keyboard Navigation

Aside from the key combinations "inherited" from the igxGrid, the Tree Grid should also support the following keyboard interactions, accountable for the expansion and collapsing of parent records:

Keys	Description
`Alt` + `→` / `Alt` + `↓`	Expand record
`Alt` + `←` / `Alt` + `↑`	Collapse record
`→` / `Tab`	Move right from leftmost cell

3.5. API

Options

Name	Description	Type	Default value	Valid values

Methods

Name	Description	Return type	Parameters

Events

Name	Description	Cancelable	Parameters

4. Test Scenarios

Automation

Basic

Scenario 1: Should have the tree-cell as a first cell on every row.
Scenario 2: Should have a correct indentation for every record of each level.
Scenario 3: Should expand/collapse rows through the UI by adding/removing their respective children in the grid's view underneath.
Scenario 4: Should expand/collapse rows through the API by adding/removing their respective children in the grid's view underneath.
Scenario 5: When expand/collapsing rows through the UI the expand/collapse indicators should change.
Scenario 6: When expand/collapsing rows through the API the expand/collapse indicators should change.
Scenario 7: Should be able to have a tree-column with a number dataType.
Scenario 8: Should be able to have a tree-column with a string dataType.
Scenario 9: Should be able to have a tree-column with a date dataType.
Scenario 10: Should be able to have a tree-column with a boolean dataType.

Expand/Collapse

Scenario 1: Should update the current page when collapseAll is invoked.
Scenario 2: Should update the current page when expandAll is invoked.
Scenario 3: Should update the paginator when a row of any level is expanded.
Scenario 4: Should update the paginator when a row of any level is collapsed.
Scenario 5: Should update the paginator when navigating through pages.

Data Transformation

Scenario 1: Should transform input data into the desired hierarchical structure given primaryKey and foreignKey are specified.
Scenario 2: Should transform input data into the desired hierarchical structure given childDataKey is specified.
Scenario 3: Should sort data in the desired hierarchical structure so that sorting is applied for each separate level of hierarchy.
Scenario 4: Should correctly flatten the desired hierarchical structure with children being listed under respective parents in the correct order.
Scenario 5: Should page the flattened data based on paging parameters.

Integration

Scenario 1: Should persist the indentation after sorting.
Scenario 2: Should persist the indentation after filtering.
Scenario 3: Should persist the indentation on all pages when using paging.
Scenario 4: Should persist the indentation after resizing the tree-column.
Scenario 5: Should correctly render a template set through a template outlet for a column that is assigned to be the expand one.
Scenario 6: Should transform a non-tree column into a tree column when pinning it.
Scenario 7: Should transform a non-tree column into a tree column when hiding the original tree-column.
Scenario 8: Should transform the first visible column into tree column when pin and hide another column before that.
Scenario 9: Should transform a hidden column to a tree column when it becomes visible and it is the first column.
Scenario 10: Should transform a non-tree column into a tree column when moving the original tree-column through API.
Scenario 11: Should transform a non-tree column into a tree column when moving the original tree-column through UI.
Scenario 12: Should be able to autosize the tree-column through API.
Scenario 13: Should be able to autosize the tree-column through UI.
Scenario 14: Should change cell content alignment of tree-column with number dataType when it is no longer tree-column.
Scenario 15: Should transform a non-tree column into a tree column when hiding the original tree-column when it is part of a group.
Scenario 16: Should transform a hidden column to a tree column when it becomes visible and it is the first column and both the original and new tree column are part of the same group.
Scenario 17: Should transform a hidden column to a tree column when it becomes visible and it is the first column and both the original and new tree column are not part of the same group.
Scenario 18: Should transform a non-tree column into a tree column when moving it first and both are part of the same group.
Scenario 19: Should transform a non-tree column of a column group to a tree column when its group is moved first.
Scenario 20: Should correctly filter a string column using the contains filtering conditions.
Scenario 21: Should correctly filter a string column using the endswith filtering conditions.
Scenario 22: Should correctly filter a number column using the greaterThan filtering conditions.
Scenario 23: Should correctly filter a number column using the lessThan filtering conditions.
Scenario 24: Should correctly filter a date column using the before filtering conditions.
Scenario 25: Should correctly filter a date column using the after filtering conditions.
Scenario 26: Should be able to search for a word in the tree column.
Scenario 27: Should be able to search for a word in an ordinary column.

Selection

Scenario 1: Should be able to have checkbox on each row.
Scenario 2: Should be able to select/deselect all rows (including the rows from all child levels.
Scenario 3: Should be able to select row of any level.
Scenario 4: Should be able to deselect row of any level.
Scenario 5: Should persist the selection after expand/collapse.
Scenario 6: Should update header checkbox when reselecting all filtered-in rows.
Scenario 7: Should return the correct type of cell when clicking on a cell.
Scenario 8: Should return the correct type of cell when clicking on a child cell.

CRUD

Scenario 1: Should support adding root row through treeGrid API.
Scenario 2: Should support adding child rows through treeGrid API.
Scenario 3: Should support adding child row to null collection through treeGrid API.
Scenario 4: Should support adding child row to undefined collection through treeGrid API.
Scenario 5: Should support adding child row to non-existing collection through treeGrid API.
Scenario 6: Should do nothing when adding child row to a non-existing parent row (invalid parentID).
Scenario 7: Should support updating a root row through the treeGrid API.
Scenario 8: Should support updating a child row through the treeGrid API.
Scenario 9: Should support updating a child row through the rowObject API.
Scenario 10: Should support updating a child tree-cell through the treeGrid API.
Scenario 11: Should support updating a child tree-cell through the cellObject API.
Scenario 12: Should be able to enter edit mode of a tree-grid column on dblclick, enter and F2.
Scenario 13: Should be able to enter edit mode of a non-tree-grid column on dblclick, enter and F2.
Scenario 14: Should be able to edit a tree-grid cell through UI.
Scenario 15: Should be able to edit a non-tree-grid cell through UI.
Scenario 16: Should be able to delete a root level row by ID.
Scenario 17: Should be able to delete a child level row by ID.
Scenario 18: Should be able to delete a root level row through the row object.
Scenario 19: Should be able to delete a child level row through the row object.
Scenario 20: Should emit an event when deleting row by ID.
Scenario 21: Should emit an event when deleting row through the row object.

Keyboard navigation

Scenario 1: Up Arrow Key to navigate one cell up. Test in a child and parent rows.
Scenario 2: Down Arrow Key to navigate one cell down Test in a child and parent rows.
Scenario 3: Left Arrow Key to navigate one cell left (no wrapping between lines) on the current row only.
Scenario 4: Right Arrow Key to navigate one cell right on the current row only.
Scenario 5: Page Up scroll one page (view port) up.
Scenario 6: Page Down scroll one page (view port) down.
Scenario 7: Tab move the selection to next cell or next row if the last cell is reached.
Scenario 8: Shift + Tab move the selection to previous cell or previous row (last row cell) if the first cell is reached.
Scenario 9: Tab if a cell is opened in edit mode next cell or next row first cell (if the last cell is reached) should be opened in edit mode. If the next cell is not editable, it have to be selected.
Scenario 10: Shift + Tab If a cell is opened in edit mode the previous cell or previous row (last row cell) if the first cell is reached should be opened in edit mode. If the cell is not editable, it have to be selected.
Scenario 11: Alt + Up/Left Arrow Key the cell should stay selected and focused and if the selected cell row has children the row should be collapsed.
Scenario 12: Alt + Down/Right Arrow Key the cell should stay selected and focused and if the selected cell row has children the row should be expanded.
Scenario 13: Ctrl + Up Arrow Key move to top cell in column.
Scenario 14: Ctrl + Down Arrow Key move to bottom cell in column.
Scenario 15: Ctrl + Left Arrow Key move to leftmost cell in row.
Scenario 16: Ctrl + Right Arrow Key move to rightmost cell in row.
Scenario 17: Ctrl + Home move to top left cell in the grid.
Scenario 18: Ctrl + End move to bottom right cell in the grid.
Scenario 19: Tab/Arrow keys should navigate correctly when we have pinned columns.
Scenario 20: Space if Row selectors are enabled pressing space on a selected cell should select its row.
Scenario 21: Esc if a cell is opened in edit mode the cell edit mode should be closed and the cell should stay selected.
Scenario 22: Enter/F2 if a cell is editable it should toggle cell edit mode.

Search

Scenario 1: Search highlights should work for tree cells.
Scenario 2: Search highlights should work for root and child rows.
Scenario 3: Search highlights should work for both flat and hierarchical data.
Scenario 4: Should navigate search highlights with collapsed rows.
Scenario 5: Should navigate search highlights with paging.
Scenario 6: Should navigate search highlights with paging and collapsed rows.
Scenario 7: Search highlights should work for case sensitive and exact match searches.
Scenario 8: Should update search highlights when filtering.
Scenario 9: Should update search highlights when clearing filter.
Scenario 10: Should update search highlights when sorting.
Scenario 11: Should update search highlights after pin/unpin column.
Scenario 12: Should update search highlights after hide/show column.

Manual Testing

Scenario 1: igxTreeGrid is rendered correctly when initialized in igxTabs.
Scenario 2: igxTreeGrid is rendered correctly when initialized in igxDialog.

5. Accessibility

WAI-ARIA Support In 2014 the W3C finalized their WAI-ARIA specification which defined how to design Web content and Web applications to be more accessible to users with disabilities. The TreeGrid has been designed so that it follows these guidelines.

The list below provides details about what changes have been made to the TreeGrid to support WAI-ARIA. Please note that no special settings are needed to leverage these changes, as they are all enabled by default.