@progress/wct-a11y-spec

## Managing Focus The Grid component is a container that consists of 4 logically separated structural elements: * Toolbar (`role="toolbar"`); * Group header (`role="toolbar"`); * Data Grid (`role="grid"`); * Pager (`role="application"`); Each of them is part of the page tab sequence and can be navigated to using the `Tab` key of the keyboard. The `Toolbar` implements the keyboard navigation specification for a ToolBar component. The `Group heder` implements the keyboard navigation specification for a ToolBar component. Delete buttons in the Field buttons should not be focusable. Deleting can be executed when Field name button is focused by pressing `Delete` or `Backspace`. The `Pager` implements the keyboard navigation specification for a Pager component. The below description focuses only on the `Data Grid` part (the element with `role="grid"`) of the composite component. ## Data Grid Focus The Data Grid is a single tab stop component. Upon focusing the Data Grid, the initial focus is set to either the previously focused cell (if any), or the first data (`<td>`) cell in the Data Grid. The change of the focused cell should be implemented using one of the following two techniques: * Roving TabIndex components Practice for managing the focus. Meaning that going through the cells will update the tabindex of the cell. * Active descendant - keeping the focus always on the Data Grid and using the `aria-activedescendant` on the Data Grid element which points to the id of the currently focused cell. If a cell contains only one focusable element that does not itself require arrow keys for its inner navigation - focus goes to that element instead of its parent `<td>`. If column header cells do not provide functions, such as sort, filter, grouping, or column menu, they may not be focusable. ## Keyboard Shortcuts ### All Grid cells | Shortcut | Behavior | |----------|----------| | `Right Arrow`| Moves focus one cell to the right (if any)| | `Left Arrow`| Moves focus one cell to the left (if any)| | `Down Arrow`| Moves focus one cell down (if any)| | `Up Arrow`| Moves focus one cell up (if any)| | `Home` | Moves focus to the first cell in the row that contains focus. | | `End` | Moves focus to the last cell in the row that contains focus. | | `Ctrl/Cmd + Home` | Moves focus to the first (top-left) data cell in the grid. | | `Ctrl/Cmd + End` | Moves focus to the last cell in the last **loaded** row of the Grid. | | `Page Down` | Loads and displays the next page of data. If virtual scrolling is used, scrolls one page down.| | `Page Up` | Loads and displays the previous page of data. If virtual scrolling is used, scrolls one page up.| ### Grid data cells #### All scenarios | Shortcut | Behavior | |----------|----------| | `Enter` | When the grid is in InCell EditMode - EditMode is activated. In hierarchy cell - expands /collapses the detail row. In grouping cell - expands /collapses the group. If the cell contains a focusable elements - focus moves to the first focusable element inside. | | `F2` | Enters edit mode when the Grid is in InCell EditMode. | | `Esc` | If editor is opened, cancels the edit and closes the editor. If focus is on an element inside a cell, returns the focus back to the cell. | #### In a row selection scenario | Shortcut | Behavior | |----------|----------| | `Space` | Selects the row holding the currently focused cell.| | `Ctrl/Cmd + Space` | Selects or deselects the current row, while persisting previously selected rows (only for selection mode "multiple"). | | `Shift + Space` | Performs range selection, selects all the rows between the last selected one (with SPACE or mouse click) and the one holding the focused cell. | | `Shift + Up Arrow` | Selects the row above. When multiple selection is enabled, extends the selection to that row. | | `Shift + Down Arrow` | Selects the row below. When multiple selection is enabled, extends the selection to that row. | #### In a cell selection scenario | Shortcut | Behavior | |----------|----------| | `Space` | Selects the currently focused cell.| | `Ctrl/Cmd + Space` | Selects or deselects the currently focused cell, while persisting previously selected cells (only for selection mode "multiple"). | | `Shift + Space` | Performs range selection, selects all the cells between the last selected one (with SPACE or mouse click) and the focused cell. | | `Shift + Up Arrow` | Selects the cell above. When multiple selection is enabled, extends the selection to that cell. | | `Shift + Down Arrow` | Selects the cell below. When multiple selection is enabled, extends the selection to that cell. | | `Shift + Left Arrow` | Selects the cell to the left. When multiple selection is enabled, extends the selection to that cell. | | `Shift + Right Arrow` | Selects the cell to the right. When multiple selection is enabled, extends the selection to that cell. | ### Grid header cells | Shortcut | Behavior | |----------|----------| | `Enter` | If sorting is enabled, Sort is applied. | | `Alt` + `Down` | Opens the Column menu / Filter menu and moves focus to that menu. | | `Esc` | Closes Filter or Column menu. | | `Ctrl` + `Space` | Group/ungroup the focused column. | | `Ctrl` + `Left Arrow` | Reorders the column with the previous one. | | `Ctrl` + `Right Arrow` | Reorders the column with the next one. | Note that header cells can't contain arbitrary focusable elements if the Grid is sortable, as the `Enter` key is reserved for sorting. There should be an option to remap the `Enter` key if a user scenario requires focusable elements in the header. ### Command column cells | Shortcut | Behavior | |----------|----------| | `Enter`| Moves focus inside the command column. First button is focused. If a button is focused, triggers the button action. | | `Esc`| If a button is focused, returns focus to the command cell. | | `Tab`| Moves focus to the next button in the column.| | `Shift + Tab`| Moves focus to the previous button in the column.| ### Inline Edit Row Triggering an edit in Inline mode focuses the first editor. | Shortcut | Behavior | |----------|----------| | `Tab`| Moves to the next editor in the row. | | `Escape`| Cancels the row edit. The focus goes to the command cell from where the row edit was triggered. | ### Incell Edit Cell When editing mode is incell, we have an excel-like navigation. When an editor is opened and focus is inside it, the following key combinations are in use. | Shortcut | Behavior | |----------|----------| | `Tab`| Moves to the next editor in the row (closing current editor). It skips cells with `Editable='false'` and command columns. If focus is already on the last editable cell on the row, focus is moved to the first editable cell on the next row, and it's editor is opened. If we're already on the last row of the grid, focus remains on the cell, with the editor closed. | | `Shift + Tab`| Moves to the previous editor in the row (closing current editor). It skips cells with `Editable='false'` and command columns. If focus is already on the first editable cell on the row, focus is moved to the last editable cell on the previous row, and it's editor is opened. If we're already on the first row of the grid, focus remains on the cell, with the editor closed. | | `Enter`| Commits changes for the edited item, and moves focus to the same cell on the row below, opening it for edit.| | `Escape`| Cancels the edit. The focus goes to the current cell.| ### Popup editor Opening the popup editor focuses the first editor. | Shortcut | Behavior | |----------|----------| | `Tab`| Moves to the next editor in the form. | | `Escape`| Closes the editor. The focus goes to the command cell from where the popup was opened.| | `Enter`| Triggers a submit action for the editor, including validation.| ### Filter Row | Shortcut | Behavior | |----------|----------| | `Arrow Keys`| `td` elements receive focus as standard navigation in Grid. | | `Enter`| Enters in the `td` and focuses the first focusable element in it. All filter row components gain `tabindex=0`. Focus remains trapped inside the filter row. | | `Tab`| Goes through the filter row components. | | `Esc`| Focus goes to the `td` element wrapping the currently focused filter component. | ### Column Menu The Column menu implements the ContextMenu keyboard navigation spec. | Shortcut | Behavior | |----------|----------| | `Alt` + `Arrow Down` | When the header cell is focused, opens the column menu. | | `Arrow Down/Up` | Focuses the next/previous item in the column menu. | | `Enter`| Activates the focused action in the column menu. | | `Space` | Toggles a `checkboxmenuitem` (if focused). | | `Esc`| Closes the column menu. If the focus is inside a dropdown list or a filter, closes the dropdown. | ### Filter Menu The Filter menu implements the Form keyboard navigation spec in a Popup container. After focusing the Filter menu, the focus is trapped within its contents. The user should not be allowed to tab-out of the menu. | Shortcut | Behavior | |----------|----------| | `Alt` + `Down Arrow` | When a header cell is focused, opens the filter menu. | | `Tab` and `Shift + Tab` | Cycles the filter menu fields. | | `Escape`| Closes the filter menu. Note that if a popup inside the menu is currently opened, `Escape` will close it instead. Pressing `Escape` a second time will close the menu. | | `Space` | Toggles a `checkboxmenuitem` (if focused). | ### Group row | Shortcut | Behavior | |----------|----------| | `Enter`| Expands/Collapses the row | ### Detail Template master row Detail template is accessed through the detail cell. | Shortcut | Behavior | |----------|----------| | `Enter`| Toggles the detail template. | | `Tab`| If expanded, focus the first focusable element inside the detail template (if any). | | `Shift + Tab`| If on the first focusable item inside the template, returns focus to the Grid (first focusable cell). | ### Checkbox column The CheckBoxes in a Checkbox column always receive focus instead of their `<td>` parents. That is because they are the only element in the cell, which is also focusable. | Shortcut | Behavior | |----------|----------| | `Space`| Toggle checkbox. Toggling the checkbox selects/deselects a row. | | `Esc`| Returns focus to the cell. | ## Resources https://www.w3.org/TR/wai-aria-practices-1.2/#grid https://www.w3.org/TR/wai-aria-practices-1.2/#keyboard-interaction-for-data-grids https://www.w3.org/TR/wai-aria-practices-1.2/#gridNav https://www.w3.org/TR/wai-aria-practices-1.2/examples/grid/dataGrids.html