Skip to content

Commit

Permalink
[docs] Apply style guide to Data Grid Accessibility page (#5780)
Browse files Browse the repository at this point in the history 
Co-authored-by: Flavien DELANGLE <flaviendelangle@gmail.com>
Co-authored-by: Olivier Tassinari <olivier.tassinari@gmail.com>
  • Loading branch information
@samuelsycamore @flaviendelangle @oliviertassinari
3 people committed Sep 29, 2022
1 parent 94973b3 commit 4eab92f
Showing 1 changed file with 31 additions and 38 deletions.
69 changes: 31 additions & 38 deletions docs/data/data-grid/accessibility/accessibility.md
View file
Original file line number Diff line number Diff line change
@@ -1,10 +1,6 @@
---
title: Data Grid - Accessibility
---
# Data Grid - Accessibility

# Data grid - Accessibility

<p class="description">The data grid has complete accessibility support. For instance, every cell is accessible using the keyboard.</p>
<p class="description">The Data Grid has complete accessibility support, including built-in keyboard navigation that follows international standards.</p>

## Guidelines

Expand All @@ -14,52 +10,52 @@ The most commonly encountered conformance guidelines for accessibility are:
- [ADA](https://www.ada.gov/) - US Department of Justice
- [Section 508](https://www.section508.gov/) - US federal agencies

WCAG 2.0 has three levels of conformance; A, AA, and AAA (in order of conformance).
As meeting WCAG 2.0 level AA guidelines also meets the ADA and Section 508 standards, it's likely the standard that most organizations will want to target.
WCAG 2.0 has three levels of conformance: A, AA, and AAA.
Level AA matches the ADA and Section 508 guidelines, so this is the most common target for organizations to aim for.

The [WAI-ARIA authoring practices](https://www.w3.org/WAI/ARIA/apg/patterns/grid/) provides valuable insight on how to make the grid highly accessible.
The [WAI-ARIA authoring practices](https://www.w3.org/WAI/ARIA/apg/patterns/grid/) provide valuable information on how to optimize the accessibility of a grid.

## Density

You can change the density of the rows and the column header.

### Density selector

To enable the density selector, you need to compose a toolbar containing the `GridToolbarDensitySelector` component and apply it using the `Toolbar` property in the grid `components` prop.

The user can change the density of the data grid by using the density selector from the toolbar.
To enable the density selector, create a toolbar containing the `GridToolbarDensitySelector` component and apply it using the `Toolbar` property in the Data Grid's `components` prop.
The user can then change the density of the Data Grid by using the density selector from the toolbar, as the following demo illustrates:

{{"demo": "DensitySelectorGrid.js", "bg": "inline"}}

To hide the density selector add the `disableDensitySelector` prop to the data grid.
To hide the density selector, add the `disableDensitySelector` prop to the Data Grid.

### Density prop

The vertical density of the data grid can be set using the `density` prop.
The `density` prop applies the values determined by the `rowHeight` and `headerHeight` props if supplied.
The user can override this setting with the toolbar density selector if provided.
Set the vertical density of the Data Grid using the `density` prop.
This prop applies the values determined by the `rowHeight` and `headerHeight` props, if supplied.
The user can override this setting with the optional toolbar density selector.

The following demo shows a Data Grid with the default density set to `compact`:

{{"demo": "DensitySelectorSmallGrid.js", "bg": "inline"}}

## Keyboard navigation

The grid responds to keyboard interactions from the user and emits events when key presses happen on the grid cells.
The Data Grid listens for keyboard interactions from the user and emits events in response to key presses within cells.

### Tab sequence

According to [WAI-ARIA](https://www.w3.org/WAI/ARIA/apg/patterns/grid/), only one of the focusable elements contained by the grid should be included in the page tab sequence.
According to [WAI-ARIA](https://www.w3.org/WAI/ARIA/apg/patterns/grid/), only one of the focusable elements contained by a composite widget should be included in the page tab sequence.
For an element to be included in the tab sequence, it needs to have a `tabIndex` value of zero or greater.

When a cell of the grid is focused, the first inner element with `tabIndex={0}` will receive the focus.
When a user focuses on a Data Grid cell, the first inner element with `tabIndex={0}` receives the focus.
If there is no element with `tabIndex={0}`, the focus is set on the cell itself.

In the example below, the first grid does not remove links from the tab sequence, which implies having to pass through all the links before accessing the pagination controls.
This behavior makes it complicated to navigate between elements when using large datasets.
The two Data Grids below illustrate how the user experience is impacted by improper management of the page tab sequence, making it difficult to navigate through the data set:

{{"demo": "FocusManagement.js", "bg": "inline", "defaultCodeOpen": false}}

If you are customizing cell rendering with the [`renderCell`](/x/react-data-grid/column-definition/#rendering-cells) method, you become responsible for removing focusable elements from the page tab sequence.
To do so, use the `tabIndex` prop passed to the `renderCell` params to know if the rendered cell has focus and so if the inner elements should be removed from the tab sequence.
If you customize cell rendering with the [`renderCell`](/x/react-data-grid/column-definition/#rendering-cells) method, you become responsible for removing focusable elements from the page tab sequence.
Use the `tabIndex` prop passed to the `renderCell` params to determine if the rendered cell has focus and if, as a result, the inner elements should be removed from the tab sequence:

```jsx
renderCell: (params) => (
Expand All @@ -73,7 +69,12 @@ renderCell: (params) => (

### Navigation

Use the arrow keys to move the focus.
The following key assignments apply to Windows and Linux users.

On macOS:

- replace <kbd class="key">Ctrl</kbd> with <kbd class="key">⌘ Command</kbd>
- replace <kbd class="key">Alt</kbd> with <kbd class="key">⌥ Option</kbd>

| Keys | Description |
| -----------------------------------------------------------------: | :---------------------------------------------------------- |
Expand All @@ -98,8 +99,8 @@ Use the arrow keys to move the focus.
| <kbd><kbd class="key">Shift</kbd>+<kbd class="key">Arrow Up/Down</kbd></kbd> | Select the current row and the row above or below |
| <kbd class="key">Shift</kbd>+ Click on cell | Select the range of rows between the first and the last clicked rows |
| <kbd><kbd class="key">Ctrl</kbd>+<kbd class="key">A</kbd></kbd> | Select all rows |
| <kbd><kbd class="key">Ctrl</kbd>+<kbd class="key">C</kbd></kbd> | Copy the currently selected row(s) |
| <kbd><kbd class="key">Alt</kbd>+<kbd class="key">C</kbd></kbd> | Copy the currently selected row(s) including headers |
| <kbd><kbd class="key">Ctrl</kbd>+<kbd class="key">C</kbd></kbd> | Copy the currently selected rows |
| <kbd><kbd class="key">Alt</kbd>+<kbd class="key">C</kbd></kbd> | Copy the currently selected rows, including headers |
| <kbd class="key">Ctrl</kbd>+ Click on cell | Enable multi-selection |
| <kbd class="key">Ctrl</kbd>+ Click on a selected row | Deselect the row |

Expand All @@ -113,19 +114,11 @@ Use the arrow keys to move the focus.
| <kbd class="key">Enter</kbd> | Sort column when column header is focused |
| <kbd><kbd class="key">Ctrl</kbd>+<kbd class="key">Enter</kbd></kbd> | Open column menu when column header is focused |

### Group & pivot

| Keys | Description |
| ------------------------------------------------------------------: | :-------------------------------- |
| <kbd><kbd class="key">Ctrl</kbd>+<kbd class="key">Enter</kbd></kbd> | Toggles the detail panel of a row |
### Group and pivot

### Key assignment conventions

The above key assignments are for Windows and Linux.
On macOS:

- replace <kbd class="key">Ctrl</kbd> with <kbd class="key">⌘ Command</kbd>
- replace <kbd class="key">Alt</kbd> with <kbd class="key">⌥ Option</kbd>
| Keys | Description |
| ------------------------------------------------------------------: | :------------------------------- |
| <kbd><kbd class="key">Ctrl</kbd>+<kbd class="key">Enter</kbd></kbd> | Toggle the detail panel of a row |

## API

Expand Down

0 comments on commit 4eab92f

Please sign in to comment.