@progress/wct-a11y-spec

[ { "h2": "Accessibility Support" }, { "p": "Out of the box, the Telerik and Kendo UI TreeList provides extensive accessibility support and enables users with disabilities to acquire complete control over its features." }, { "p": "The TreeList is compliant with the [Web Content Accessibility Guidelines (WCAG) 2.2 standards](https://www.w3.org/TR/WCAG22/) and [Section 508](http://www.section508.gov/) requirements, follows the [Web Accessibility Initiative - Accessible Rich Internet Applications (WAI-ARIA)](https://www.w3.org/WAI/ARIA/apg/) best practices for implementing the [keyboard navigation](#keyboard-navigation) for its `component` role, provides options for [managing its focus](#managing-the-focus) and is tested against the most popular [screen readers](#screen-readers)." }, { "h3": "WAI-ARIA" }, { "p": "This section lists the selectors, attributes, and behavior patterns supported by the component and its composite elements, if any." }, { "p": "The TreeList is a composite component that consists of 2 logically separated structural elements:" }, { "ul": [ "Toolbar (`role=toolbar`);", "Tree Grid (`role=treegrid`);" ] }, { "h4": "TreeList Toolbar" }, { "p": "TreeList Toolbar follows the specification of the ToolBar component." }, { "link": { "title": "ToolBar accessibility specification", "source": "{{toolbar_a11y_link}}" } }, { "table": { "headers": [ "Selector", "Attribute", "Usage" ], "rows": [ { "Selector": "`.k-grid-toolbar`", "Attribute": "`role=toolbar`", "Usage": "The toolbar is a collection of command buttons and inputs." }, { "Selector": "", "Attribute": "`aria-label`", "Usage": "Clarifies the purpose of the toolbar." }, { "Selector": "", "Attribute": "`aria-controls=.k-grid-aria-root id`", "Usage": "Pointing to the id of the element with `role=treegrid`." } ] } }, { "h4": "Tree Grid" }, { "p": "The element with `role=treegrid` must not include the ToolBar element as it does not belong to the `role=treegrid` element itself. It implements the ARIA specification for the Grid component with some exceptions listed below." }, { "link": { "title": "Grid accessibility specification", "source": "{{grid_a11y_link}}" } }, { "p": "The below table lists the ARIA requirements for the TreeList which are not present in the Grid specification:" }, { "table": { "headers": [ "Selector", "Attribute", "Usage" ], "rows": [ { "Selector": "`.k-treelist .k-grid-aria-root`", "Attribute": "`role=treegrid`", "Usage": "Sets the proper role for the TreeList component." }, { "Selector": "`.k-table-tbody .k-table-row`", "Attribute": "`aria-expanded=true/false`", "Usage": "Set on the currently expanded row(s)." }, { "Selector": "`.k-table-tbody .k-i-caret-alt-down,.k-table-tbody .k-i-caret-alt-right,.k-table-tbody .k-svg-i-caret-alt-down,.k-table-tbody .k-svg-i-caret-alt-right`", "Attribute": "`aria-hidden=true`", "Usage": "Removes the expand/collapse icon from the accessibility tree." } ] } }, { "h3": "Managing the Focus" }, { "p": "The TreeList component is a container that consists of 2 logically separated structural elements:" }, { "ul": [ "Toolbar (`role=\"toolbar\"`);", "Tree Grid (`role=\"treegrid\"`);" ] }, { "p": "Each of them is part of the page tab sequence and can be navigated to using the `Tab` key of the keyboard." }, { "p": "The `Toolbar` implements the keyboard navigation specification for a ToolBar component." }, { "p": "The below description focuses only on the `Tree Grid` part (the element with `role=\"treegrid\"`) of the composite component." }, { "h3": "Tree Grid Focus" }, { "p": "The Tree Grid is a single tab stop component. Upon focusing the Tree Grid, the initial focus is set to either the previously focused cell (if any), or the first data (`<td>`) cell in the Tree Grid. The change of the focused cell should be implemented using one of the following two techniques:" }, { "ul": [ "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 Tree Grid element which points to the id of the currently focused cell." ] }, { "p": "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>`." }, { "p": "If column header cells do not provide functions, such as sort, filter, or column menu, they may not be focusable." }, { "p": "If the TreeList contains no items (empty TreeList), the `No data` element in the TreeList should be focused. That applies also for the scenario when the last item in the Grid has been deleted." }, { "h3": "Keyboard Shortcuts" }, { "p": "The TreeList implements the same keyboard shortcuts as the Grid component. In addition to that, here is the appropriate shortcut to expand/collapse a row:" }, { "table": { "headers": [ "Shortcut", "Behavior" ], "rows": [ { "Shortcut": "`Enter`", "Behavior": "In expandable and non-editable cell - expands or collapses the item." } ] } }, { "h3": "Testing" }, { "p": "The TreeList has been extensively tested automatically with [axe-core](https://github.com/dequelabs/axe-core) and manually with the most popular screen readers." }, { "h3": "Screen Readers" }, { "p": "The TreeList has been tested with the following screen readers and browsers combinations:" }, { "table": { "headers": [ "Environment", "Tool" ], "rows": [ [ "Firefox", "NVDA" ], [ "Chrome", "JAWS" ], [ "Microsoft Edge", "JAWS" ] ] } }, { "h3": "Resources" }, { "ul": [ { "link": { "source": "https://www.w3.org/TR/wai-aria-1.2/#treegrid", "title": "WAI-ARIA specification for tree grid" } }, { "link": { "source": "https://www.w3.org/WAI/ARIA/apg/patterns/treegrid/", "title": "ARIA Authoring Practices: Treegrid Pattern" } } ] } ]