From b5a8fdae28886d1d8cef8c7acbaa0d7a83dffa6f Mon Sep 17 00:00:00 2001 From: Nora <72460825+noraleonte@users.noreply.github.com> Date: Fri, 3 May 2024 14:15:49 +0300 Subject: [PATCH] [docs] Add accessibility page to TreeView docs (#12845) Signed-off-by: Nora <72460825+noraleonte@users.noreply.github.com> Co-authored-by: Lukas --- docs/data/pages.ts | 1 + .../tree-view/accessibility/accessibility.md | 80 +++++++++++++++++++ docs/pages/x/react-tree-view/accessibility.js | 7 ++ 3 files changed, 88 insertions(+) create mode 100644 docs/data/tree-view/accessibility/accessibility.md create mode 100644 docs/pages/x/react-tree-view/accessibility.js diff --git a/docs/data/pages.ts b/docs/data/pages.ts index fb518feaa82a0..85d9e44bf53d9 100644 --- a/docs/data/pages.ts +++ b/docs/data/pages.ts @@ -496,6 +496,7 @@ const pages: MuiPage[] = [ children: [ { pathname: '/x/react-tree-view', title: 'Overview' }, { pathname: '/x/react-tree-view/getting-started' }, + { pathname: '/x/react-tree-view/accessibility' }, { pathname: '/x/react-tree-view/simple-tree-view', subheader: 'Simple Tree View', diff --git a/docs/data/tree-view/accessibility/accessibility.md b/docs/data/tree-view/accessibility/accessibility.md new file mode 100644 index 0000000000000..7f53c06af65c6 --- /dev/null +++ b/docs/data/tree-view/accessibility/accessibility.md @@ -0,0 +1,80 @@ +--- +productId: x-tree-view +title: Accessibility +githubLabel: 'component: tree view' +waiAria: https://www.w3.org/WAI/ARIA/apg/patterns/treeview/ +packageName: '@mui/x-tree-view' +--- + +# Accessibility + +

The Tree View has complete accessibility support, including built-in keyboard interactions that follow international standards.

+ +## Guidelines + +The most commonly encountered conformance guidelines for accessibility are: + +- Globally accepted standard: [WCAG](https://www.w3.org/WAI/standards-guidelines/wcag/) +- US: + - [ADA](https://www.ada.gov/) - US Department of Justice + - [Section 508](https://www.section508.gov/) - US federal agencies +- Europe: [EAA](https://ec.europa.eu/social/main.jsp?catId=1202) (European Accessibility Act) + +WCAG 2.1 has three levels of conformance: A, AA, and AAA. +Level AA meets the most commonly encountered conformance guidelines. +This is the most common target for organizations, so we aim to support it very well. + +The [WAI-ARIA Authoring Practices](https://www.w3.org/WAI/ARIA/apg/patterns/treeview/) provide valuable information on how to optimize the accessibility of a Tree View. + +## Keyboard interactions + +:::info +The following key assignments apply to Windows and Linux users. + +On macOS replace Ctrl with ⌘ Command. + +::: + +| Keys | Description | +| --------------------------------------------------------------------------------------------: | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Enter | Activates the focused item. | +| Arrow Up | Moves focus to the previous focusable item, without expanding or collapsing it. | +| Arrow Down | Moves focus to the next focusable item, without expanding or collapsing it. | +| Arrow Right + RTL off
Arrow Left + RTL on | | +| Arrow Left + RTL off
Arrow Right RTL on | | +| Home | Focuses the first item in the tree | +| End | Focuses the last item in the tree | +| \* | Expands all siblings that are at the same level as the focused item without moving focus. | + +Type-ahead is supported for single characters. When typing a character, focus moves to the next item with a label that starts with the typed character. + +## Selection + +The tree view supports both single and multi-selection. To learn more about the selection API, visit the dedicated page for the [Simple Tree View](/x/react-tree-view/simple-tree-view/selection/) or the [Rich Tree View](/x/react-tree-view/rich-tree-view/selection/). + +To read more about the distinction between selection and focus, you can refer to the [WAI-ARIA Authoring Practices guide](https://www.w3.org/WAI/ARIA/apg/practices/keyboard-interface/#kbd_focus_vs_selection). + +### On single-select trees + +When a single-select tree receives focus: + +- If none of the items are selected when the tree receives focus, focus is set on the first item. +- If an item is selected before the tree receives focus, focus is set on the selected item. + +### On multi-select trees + +When a multi-select tree receives focus: + +- If none of the items are selected when the tree receives focus, focus is set on the first item. +- If one or more items are selected before the tree receives focus, then focus is set on: + - the first selected item if it is the first render + - the item that was last selected otherwise + +| Keys | Description | +| -----------------------------------------------------------------------------------: | :---------------------------------------------------------------- | +| Space | Toggles the selection state of the focused item. | +| Shift+Arrow Up | Moves focus and toggles the selection state of the previous item. | +| Shift+Arrow Down | Moves focus and toggles the selection state of the next item. | +| Ctrl+Shift+Home | Selects the focused item and all items up to the first item. | +| Ctrl+Shift+End | Selects the focused item and all the items down to the last item. | +| Ctrl+A | Selects all items. | diff --git a/docs/pages/x/react-tree-view/accessibility.js b/docs/pages/x/react-tree-view/accessibility.js new file mode 100644 index 0000000000000..455f5b67c9967 --- /dev/null +++ b/docs/pages/x/react-tree-view/accessibility.js @@ -0,0 +1,7 @@ +import * as React from 'react'; +import MarkdownDocs from 'docs/src/modules/components/MarkdownDocs'; +import * as pageProps from 'docsx/data/tree-view/accessibility/accessibility.md?muiMarkdown'; + +export default function Page() { + return ; +}