From 4eab92febef08df9bd2773920759180c9eafcf05 Mon Sep 17 00:00:00 2001 From: Sam Sycamore <71297412+samuelsycamore@users.noreply.github.com> Date: Thu, 29 Sep 2022 15:53:18 +0100 Subject: [PATCH] [docs] Apply style guide to Data Grid Accessibility page (#5780) Co-authored-by: Flavien DELANGLE Co-authored-by: Olivier Tassinari --- .../data-grid/accessibility/accessibility.md | 69 +++++++++---------- 1 file changed, 31 insertions(+), 38 deletions(-) diff --git a/docs/data/data-grid/accessibility/accessibility.md b/docs/data/data-grid/accessibility/accessibility.md index 436a23ded259..b30eae16b4fd 100644 --- a/docs/data/data-grid/accessibility/accessibility.md +++ b/docs/data/data-grid/accessibility/accessibility.md @@ -1,10 +1,6 @@ ---- -title: Data Grid - Accessibility ---- +# Data Grid - Accessibility -# Data grid - Accessibility - -

The data grid has complete accessibility support. For instance, every cell is accessible using the keyboard.

+

The Data Grid has complete accessibility support, including built-in keyboard navigation that follows international standards.

## Guidelines @@ -14,10 +10,10 @@ 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 @@ -25,41 +21,41 @@ 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) => ( @@ -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 Ctrl with ⌘ Command +- replace Alt with ⌥ Option | Keys | Description | | -----------------------------------------------------------------: | :---------------------------------------------------------- | @@ -98,8 +99,8 @@ Use the arrow keys to move the focus. | Shift+Arrow Up/Down | Select the current row and the row above or below | | Shift+ Click on cell | Select the range of rows between the first and the last clicked rows | | Ctrl+A | Select all rows | -| Ctrl+C | Copy the currently selected row(s) | -| Alt+C | Copy the currently selected row(s) including headers | +| Ctrl+C | Copy the currently selected rows | +| Alt+C | Copy the currently selected rows, including headers | | Ctrl+ Click on cell | Enable multi-selection | | Ctrl+ Click on a selected row | Deselect the row | @@ -113,19 +114,11 @@ Use the arrow keys to move the focus. | Enter | Sort column when column header is focused | | Ctrl+Enter | Open column menu when column header is focused | -### Group & pivot - -| Keys | Description | -| ------------------------------------------------------------------: | :-------------------------------- | -| Ctrl+Enter | 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 Ctrl with ⌘ Command -- replace Alt with ⌥ Option +| Keys | Description | +| ------------------------------------------------------------------: | :------------------------------- | +| Ctrl+Enter | Toggle the detail panel of a row | ## API