@progress/wct-a11y-spec

[ { "h2": "Accessibility Support" }, { "p": "Out of the box, the Telerik and Kendo UI ListBox provides extensive accessibility support and enables users with disabilities to acquire complete control over its features." }, { "p": "The ListBox 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." }, { "h4": "ListBox List" }, { "table": { "headers": [ "Selector", "Attribute", "Usage" ], "rows": [ { "Selector": "`.k-list-ul`", "Attribute": "`role=listbox`", "Usage": "Specifies the role of the ListBox `ul` element." }, { "Selector": "", "Attribute": "`aria-label` or `aria-labelledby`", "Usage": "Adds a label to the `ul` element of the ListBox." }, { "Selector": "", "Attribute": "`aria-multiselectable=true`", "Usage": "Signifies that the ListBox allows multiple selection. Present only when the multiple selection of the component is enabled." }, { "Selector": "`.k-list-item`", "Attribute": "`role=option`", "Usage": "Specifies the role of the ListBox `item` element." }, { "Selector": "", "Attribute": "`aria-selected=true/false`", "Usage": "Set to `true` if the item is selected." }, { "Selector": "", "Attribute": "`tabindex=0`", "Usage": "The focused listbox item should have tabindex 0, while all others -1." } ] } }, { "h4": "ListBox Toolbar" }, { "p": "The ListBox 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-listbox-actions`", "Attribute": "`role=toolbar`", "Usage": "The toolbar is a collection of command buttons." }, { "Selector": "", "Attribute": "`aria-label`", "Usage": "Clarifies the purpose of the toolbar." }, { "Selector": "", "Attribute": "`aria-controls=.k-list-ul id`", "Usage": "Points to the ids of the `role=listbox` elements that are being controlled by the ToolBar." }, { "Selector": "`.k-listbox-actions .k-button`", "Attribute": "`aria-label` or `title`", "Usage": "All buttons in the ToolBar must have lables, so that their purpose is clear." } ] } }, { "h3": "Managing the Focus" }, { "p": "The ListBox component contains a list of items and, optionally, a toolbar. When the toolbar is not enabled, the component is a single-tab-stop component. When the toolbar is present, it is included in the tab sequence of the page. Depending on its position and the LTR or RTL configuration, the toolbar can either preceed or succeed the list of ListBox items. Its tab position must respect its position on the screen." }, { "h3": "Keyboard Shortcuts" }, { "h4": "`list` Element" }, { "table": { "headers": [ "Shortcut", "Behavior" ], "rows": [ { "Shortcut": "`F10`", "Behavior": "Focuses the ListBox toolbar (the last focused or the first button in it)." }, { "Shortcut": "`Space`", "Behavior": "Selects the focused ListBox Item" }, { "Shortcut": "`Up Arrow`", "Behavior": "Selects the previous item." }, { "Shortcut": "`Down Arrow`", "Behavior": "Selects the next item." }, { "Shortcut": "`Ctrl` (or `Control` on Mac) + `Space`", "Behavior": "Selects or deselects an item." }, { "Shortcut": "`Shift` + `Up Arrow`", "Behavior": "Adds the previous item to the selected items." }, { "Shortcut": "`Shift` + `Down Arrow`", "Behavior": "Adds the next item to the selected items." }, { "Shortcut": "`Ctrl` (or `Cmd` on Mac) + `Up Arrow`", "Behavior": "Moves the focus to the previous item." }, { "Shortcut": "`Ctrl` (or `Cmd` on Mac) + `Down Arrow`", "Behavior": "Moves the focus to the next item." }, { "Shortcut": "`Del`", "Behavior": "Deletes the selected items." }, { "Shortcut": "`Ctrl` (or `Cmd` on Mac) + `Right Arrow`", "Behavior": "Adds the selected items to the connected ListBox." }, { "Shortcut": "`Ctrl` (or `Cmd` on Mac) + `Left Arrow`", "Behavior": "Adds the selected items from the connected ListBox to the current one." }, { "Shortcut": "`Ctrl` (or `Cmd` on Mac) + `Shift` + `Up Arrow`", "Behavior": "Shifts the selected items upwards." }, { "Shortcut": "`Ctrl` (or `Cmd` on Mac) + `Shift` + `Down Arrow`", "Behavior": "Shifts the selected items downwards." }, { "Shortcut": "`Ctrl` (or `Cmd` on Mac) + `Shift` + `Right Arrow`", "Behavior": "Transfers all items to the connected ListBox." }, { "Shortcut": "`Ctrl` (or `Cmd` on Mac) + `Shift` + `Left Arrow`", "Behavior": "Transfers all items from the connected ListBox." } ] } }, { "h4": "`toolbar` Element" }, { "table": { "headers": [ "Shortcut", "Behavior" ], "rows": [ { "Shortcut": "`Right Arrow` or `Down Arrow`", "Behavior": "Focuses the next button in the toolbar." }, { "Shortcut": "`Left Arrow` or `Up Arrow`", "Behavior": "Focuses the previous button in the toolbar." }, { "Shortcut": "`Enter`", "Behavior": "Executes the currenly focused button command if enabled." } ] } }, { "h3": "Testing" }, { "p": "The ListBox 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 ListBox 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/WAI/ARIA/apg/patterns/listbox/", "title": "WAI-ARIA Authoring Practices: ListBox Pattern" } } ] } ]