Grid Multi cell selection Specification

igxGrid Multi-cell Selection Specification

Revision History

Version	User	Date	Notes
0.1	Zdravko Kolev	January 11, 2019	Initial draft
0.2	Zdravko Kolev	January 14, 2019	Adding all remaining sections of the spec
0.3	Zdravko Kolev	January 18, 2019	Finalizing spec
0.4	Nadia Robakova	January 22, 2019	Adding automation test plan
0.5	Nadia Robakova	February 12, 2019	Update test plan add scenarios for `IgxTreeGrid`
1.0	Zdravko Kolev	March 30, 2019	Final updates
1.1	Radoslav Karaivanov	June 5, 2019	Update spec for non-primary pointer interactions

1. Overview

igxGrid multi-cell selection feature enables range selection of cells in the grid. This feature will be useful for highlighting of cell data and copying data to the Clipboard.

Objectives

The feature includes the following:

Variety of multi-cell selection capabilities:

By mouse drag - Click the left mouse button and drag over another cell, on releasing of the mouse a range will be created between the two cells. Note: The selection should be rectangular.
By Ctrl key press and Mouse drag - Performing mouse drag action while Ctrl is pressed, will create a new range selection. Note: Any other existing cell selection will be persisted (multiple cell selections).
Multi-cell selection by using Shift. Select single cell and select another single cell by holding the Shift. Cell range between the two cells will be selected. Note: If another second cell is selected while holding Shift the cell selection range will be updated based on the first selected cell position (starting point).
Keyboard multi-cell selection by using the arrow keys while holding Shift Note: Multi-cell selection range will be created based on the focused cell.
Keyboard multi-cell selection by using the Ctrl + arrow keys and Ctrl+ Home/End while holding Shift Note: Multi-cell selection range will be created based on the focused cell.
Default behavior for keyboard multi-cell selection is disabled when a custom keyboard navigation for a grid is implemented.
Continuous multiple cell selection is available, by clicking with the mouse and dragging. Continuous scroll is possible only within grid's body.
Clicking with the left mouse key while holding Ctrl key will add single cell ranges into the selected cells collection.
Clicking with the left mouse key while holding Ctrl key on a selected cell will deselect this cell.
Non primary pointer interaction. "Clicking" by using the non primary button of a pointer device (mouse, touch pad, etc.) will not cause existing selection(s) to reset. If there is a grid cell currently in edit mode, it will be submitted and it will exit edit mode.

2. User Stories

Developer:

Multiple cell selection should be available by default.
Should be able to add multi/single selection with the API.
Should be able to get multi/single selection with the API.
Should be able to clear multi/single selection with the API.
Should be able to handle multi-selection change event.

End user:

Should be able to select multiple cells with mouse dragging.
Should be able to deselect multiple cells with mouse dragging.
Should be able to select/deselect range of cells by long-pressing Shift key and using the Arrow, Ctrl+Arrow, Ctrl+Home/End keys. The selection should be rectangular.
Should be able to select single cell and range of cells by long-pressing Ctrl key and clicking with the left mouse key on the cells.

Acceptance criteria

3. Functionality

3.1. End User Experience

[To be updated with action images after the design meeting]

3.2. Developer experience

Multiple cell selection will be available by default, no need to use Input

<igx-grid #grid1 [data]="data">
    <igx-column *ngFor="let c of columns" [field]="c.field" [groupable]="true">
    </igx-column>
</igx-grid>

Get selected cells:

will not return any result if the cell is not visible in grids view port, although getSelectedData() will return the selected cell data.

Get:

this.grid.selectedCells();

Get selected data:

will return array of the selected data in format depending on the selection

Get:

this.grid.getSelectedData();

Examples below:

If three different single cells are selected:

expectedData = [
    { CompanyName: "Infragistics" },
    { Name: "Michael Langdon" },
    { ParentID: 147 }
];

If three cells from one column are selected

expectedData = [
    { Address: "Obere Str. 57"},
    { Address: "Avda. de la Constitución 2222"},
    { Address: "Mataderos 2312"}
];

If three cells are selected with mouse drag from one row and three columns:

expectedData = [
    { Address: "Avda. de la Constitución 2222", City: "México D.F.", ContactTitle: "Owner" }
];

If three cells are selected with mouse drag from two rows and three columns:

expectedData = [
    { ContactTitle: "Sales Agent", Address: "Cerrito 333", City: "Buenos Aires"},
    { ContactTitle: "Marketing Manager", Address: "Sierras de Granada 9993", City: "México D.F."}
];

If two different ranges are selected:

expectedData = [
    { ContactName: "Martín Sommer", ContactTitle: "Owner"},
    { ContactName: "Laurence Lebihan", ContactTitle: "Owner"},
    { Address: "23 Tsawassen Blvd.", City: "Tsawassen"},
    { Address: "Fauntleroy Circus", City: "London"}
];

If two overlapping ranges are selected, the format would be:

expectedData = [
    { ContactName: "Diego Roel", ContactTitle: "Accounting Manager", Address: "C/ Moralzarzal, 86"},
    { ContactName: "Martine Rancé", ContactTitle: "Assistant Sales Agent", Address: "184, chaussée de Tournai", City: "Lille"},
    { ContactName: "Maria Larsson", ContactTitle: "Owner", Address: "Åkergatan 24", City: "Bräcke"},
    { ContactTitle: "Marketing Manager", Address: "Berliner Platz 43", City: "München"}
];

Get selected ranges

will return the current selected ranges in the grid from both keyboard and pointer interactions. The type is GridSelectionRange[].

this.grid.getSelectedRanges();

Clear selection:

Will clear the current cell selection

this.grid.clearCellSelection()

Change cell selection mode

Use GridSelectionMode enum or pass a string directly to the cellSelection input

export enum GridSelectionMode {
    none = 'none',
    single = 'single',
    multiple = 'multiple',
}

Code example:

<igx-grid #grid1 [data]="data" [cellSelection]="'single'">
..
</igx-grid>

3.3. Other igxGrid features integration

The selection is index based (DOM elements selection).

Sorting - When sorting is performed selection should not be cleared. It will leave currently selected cells the same while sorting ascending or descending.
Paging - On paging selected cells should be cleared. Selection wont be persisted across pages.
Filtering - When filtering is performed selection should not be cleared. getSelected() will return only the visible cells on filterin. If filtering is cleared it will return the initially selected cells.
Resizing - On column resizing selected cells should not be cleared.
Hiding - Should should not clear the selected cells. If column is hidden, the cells from the next visible column will be selected.
Pinning - Selected cell should not be cleared. Same as hiding
Group by - On column grouping selected cells should not be cleared.

3.4. User Interface

3.5. Keyboard Navigation

Cover the following keyboard interactions while Shift key is pressed

Shift + Arrow Up to select the cell above the focused cell.
Shift + Arrow Down to select the cell below the focused cell.
Shift + Arrow Left to select the cell on the left of the focused cell.
Shift + Arrow Right to select the cell on the right of the focused cell.
Shift + Ctrl + Arrow Up to select all cells above the focused cell to the top cell in the column.
Shift + Ctrl + Arrow Down to select all cells below the focused cell to the bottom cell in the column.
Shift + Ctrl + Arrow Left to select all cells on the left of the focused cell to the first one in the row.
Shift + Ctrl + Arrow Right to select all cells on the right of the focused cell to the last one in the row.
Shift + Ctrl + Home to select all cells above and on the left of the focused cell to the first one in the grid.
Shift + Ctrl + End to select all cells below and on the right of the focused cell to the last one in the grid.

Cover the following keyboard interactions while Ctrl + Shift keys are pressed

Ctrl + Shift + Arrow Up to select all cells above the focused cell in the column.
Ctrl + Shift + Arrow Down to select all cells below the focused cell in the column.
Ctrl + Shift + Arrow Left to select all cells till the start of the row.
Ctrl + Shift + Arrow Right to select all cells till the end of the row.
Ctrl + Shift + Home to select all cells from the focused cell till the first-most cell in the grid
Ctrl + Shift + End to select all cells from the focused cell till the last-most cell in the grid

3.6. API

IgxGridComponent

Outputs

Name	Description
Event emitters	Notify for a change
onRowSelectionChange	Used when row selection has changed, emits when the cell selection has been changed.
onCellSelectionChange	Used when cell selection has changed, emits when the cell selection has been changed.

Methods

Name	Description
getSelectedRanges	Gets the selected cells, returns array of selected Objects

Events

Drag selection event is not cancel-able

4. ARIA Support

5. Test Scenarios

Automation

Basic

Should be able to select by mouse drag (event should be fired)
Should be able to select multiple ranges with Ctrl key and mouse drag (event should be fired)
Should be able to select multiple cells with Ctrl key and mouse click (event should be fired)
Should be able to select range when click on a cell and hold Shift key and click on another Cell
Should update range selection when hold a Ctrl key and click on another cell
When a cell is selected and click on it with/without Ctrl key the cell should stay selected
When a range is selected and click on a cell in it only the cell should be selected
When a range is selected and click on a cell in it and hold a Ctrl key the range should not be changed
Should be able to select continues cells by clicking a cell and dragging outside the grid
When event is canceled it should not be possible to select a cell with and without holding Ctrl key
When a range is selected by mouse drag and press Arrow up/down/left/right or tab key the navigation should start from the first active cell.
Should be able to add multi cell with API(event should not be fired):
- Test selection of single cell
- Test with 2 cells in the view port
- Test with 1 cell in view and one not visible
- Test with 2 not visible cells
- Test adding new range when there is already added range
- Test adding multiple ranges
- Test adding multiple ranges when they have same cells
- Test adding multiple ranges when some of their cell are same
- Test when start/end column is hidden
- Test when start/end column does not exist.
Should be able to clear selection with API:
- Test clearing selection when there are not visible cells
- Test clearing selection when there is single cell selected
- Test clearing selection when there are no selected cells(event should not be fired)

Keyboard

Range selection can be selected by clicking on cell holding Shift key and pressing Arrow keys:
- Test pressing arrow Up/Down/Left/Right and combinations of them
- Test pressing arrow key when it will need to move scroll(verify the event is fired)
- Test pressing arrow key when the cell cannot be moved(for example it is first row cell and press arrow left). The event should not be fired
Test changing the region with pressing arrow keys(for example when a region is selected with the keyboard and select smaller region)
When select a region with the keyboard and stop holding the Shift key when press Arrow keys only the cell next to active cell should be selected (according to the type of arrow key)
When a region is selected and press Ctrl+ Arrow keys the keyboard navigation should go to the Leftmost/Rightmost/top/bottom cell in the row according to the arrow key and only this cell should be selected
When press Shift + Ctrl + Arrow Up all cells above the focused cell to the top cell in the column should be selected
When press Shift + Ctrl + Arrow Down all cells below the focused cell to the top cell in the column should be selected
When press Shift + Ctrl + Arrow Left all cells on the left of the focused cell to the first one in the row should be selected
When press Shift + Ctrl + Arrow Right all cells on the right of the focused cell to the last one in the row should be selected
When press Shift + Ctrl + Home all cells above and on the left of the focused cell to the first one in the grid should be selected
When press Shift + Ctrl + End all cells below and on the right of the focused cell to the last one should be selected.
Test keyboard scenarios when there are grouped rows:
- Test the when there are grouped rows and press Shift key + arrow key Up/Down it will select the next cell and will continue the region without including the group row(test events)
- Test the when there are grouped rows and press Shift key + arrow key Left/Right it will not change selection(event should not be fired)
- Test when first select a group row and press Shift key with arrow Down it will select the cell under it and can select a region
Test keyboard when summaries and grouping are enabled:
- Test when a cell is selected and press Shift+Arrow Up/Down and there is a summary cell. The selection will not be changed and the summary cell should not be activated and the event should not be fired
- When a range selection is started and go on a summary cell with navigation and press arrow Left/Right keys holding Shift key this will not change the selection and when press arrow Up/Down will continue the range selection
- Test when first activate a summary cell and start holding the chift key

Integration

Sorting:
- Select a range and sort a column. Same DOM elements should be selected and the selection will not change. The event should not be fired.
- Test when the range selection contains not visible cells and change sort. Same columns and rows should be selected and selection event should not be fired.
Filtering:
- Select a range and filter with rows which contains the selected cells. The selection should be at same rows and column and event should not be fired.
- Select a range and filter with less rows than selected. When called, getSelected should return only the filtered cells and event should not be fired. When clear filter previous selected values should be selected.
- Select a range and filter with no values found. Event should not be fired and getSelected should return an empty array. When clear filter previous selected values should be selected.
Paging
- Select a range and change page. The range should be cleared.
- Select a range and change items per page. The range should be cleared.
Resizing
- Select a range and resize a column. Selection should not be changed.
Hiding:
- Select a range and hide a column which is included in the range. The next columns cells should be selected. Event should not be fired.
- Hide a column. Select a range which contains this column. Show column. Range should include this column and will not include the last column.
- Select a range which includes the last grid column. Hide the last grid column. The selection will be changed and getSelected should returns correct values. Event should not be fired. Show column. Previous selection should be shown
Pinning:
- By mouse drag it should be able to select a range from not pinned to pinned columns. Test when the scroll is moved(all the cells between the start column and pinned column should be selected)
- By mouse drag it should be possible to select from pinned to not pinned columns. Test than the scroll is moved all the cells between pinned and current column should be selected
- Select a range and pin a column from this range. The selection should not be changed
- Select a range from pinned column. Unpin this column. The selection should not be changed
GroupBy:
- It should be possible to select a range with mouse drag when there are groped columns.
- When select a range and then group by a column same rows and cells should be selected.
- When range is selected and remove grouped column. Same cells should be selected
- When select a range and collapse a croup row. The next rows should be selected.
- When select a range and collapse all rows the getSelected method should return empty array. When expand all the previous selection should be shown
Moving
- When range is selected and move a column which has cells in the section. The next column cells should be selected. The event should not be fired
- When range is selected and move a column inside a selection. It cells should be selected
Summaries
- It should be possible to select a range with mouse drag when summaries are enabled
- When grouping and summaries are enabled and enable/disable summaries the selection should not be changed and getselected should return correct values.
- When grouping and summaries are enabled and change summaries position the selection should not be changed and getselected should return correct values.
Crud
- When a range is selected and delete a row, the next row should be selected. Verify getSelectedData returns correct values.
- When a range is selected and it is for all the rows and delete a row the selection should be updated and getSelectedData should return correct values. Test when add again the row.
- When a range is selected and add new row, the selection should not be changed
- When a range is selected and update a row, the selection should not be changed
- When a range is selected and update a cell, the selection should not be changed
- When transactions are enabled and add/delete/update a row, the selection should not be changed and getSelectedData should return updated/deleted/added data
Search
- When a range is selected, the search should highlight the found results in the selected cells.
Row Selectors
- Selecting/deselecting a row should not change cell selection
- When a row is selected it should stay selected when a range is selected

TreeGrid

Select a range from root and 2 levels deep. Verify correct cells are selected and getSelectedData returns correct values. Test with flat data and parent and child key data.
Select a range and collapse a row. Verify correct cells are selected and getSelectedData returns correct values. Test with flat data and parent and child key data.
Select a range and expand a row. Verify correct cells are selected and getSelectedData returns correct values. Test with flat data and parent and child key data.
Verify range can be selected with mouse drag.
Verify range can be selected with holding Shift key and mouse click.
Verify range can be selected with keyboard when hold Shift key and press arrow keys.
Verify selecting a range summaries are enabled.
Verify selecting a range with keyboard when summaries are enabled.
Test select when there is filter applied and results are only in children. Verify getSelectedData returns correct values
Verify selection when add/delete/update row and transactions are disabled
Verify selection when add/delete/update row and transactions are enabled