# Using accessibility in Bryntum widgets ## Widget configs ### ariaElement The name of a named element which is the main ARIA element which aquires the `role` attribute and the `aria-label` attribute. This is normally the Widget's encapsulating `element`. For input fields, it is the `input` element. Widget subclasses which have custom DOM can set this. ### role The ARIA role to assign to the `ariaElement`. System-supplied widgets know their own roles, but this can be overridden by configuration, or in subclasses. ### ariaLabel A *localizable* string key which, when resolved from the locale is applied to the `aria-label` attribute of the Widget's `ariaElement`. Note that this is re-evaluated and updated on focusIn and focusOut. This is because locale files can specify a *function* to yield the value. The widget itself is passed as the `templateData`, so the result can reflect widget state. ### ariaDescription A *localizable* string key which, when resolved from the locale is applied to an inner element which is referenced by the `aria-describedby` attribute of the Widget's `ariaElememnt` Note that this is re-evaluated and updated on focusIn and focusOut. This is because locale files can specify a *function* to yield the value. The widget itself is passed as the `templateData`, so the result can reflect widget state. If not specified, the `tooltip` text value is used as the `ariaDescription`. ### ariaHasPopup An indicator that the widget offers a popup containing extra functionality which is set to the `role` of that popup. System supplied widgets such as `Button`, `MenuItem` and the `PickerField`s (`Combo`, `DateField` and `TimeField`) will automatically set this to the `role` of their popups. ## VoiceOver utility on OSX In the Settings tab, the "Synchronize keyboard focus and VoiceOver cursor" must be checked. ## Keyboard-accessible widgets Most low level widgets such as `TextField`, `NumberField` and `Checkbox` are native HTML input fields which are accessible natively. The `TAB` key moves between them. When any `Field` is configured `clearable : true`, `Shift+BACKSPACE` may be used to invoke the trigger and clear the field. Certain more complex input widgets have special key handling. `NumberField`s respond to `down-arrow` and `up-arrow` by decrementing or incrementing by their configured `step` value just as would happen by clicking the spin down or up triggers. ### Combo The `Combo` widget is fully keyboard accessible. Typing into the field filters the store, and shows the dropdown `listbox` as soon as the configured `minChars` have been typed. Pressing `down-arrow` shows the `listbox` unfiltered. When the `listbox` is visible, `up-arrow` and `down-arrow` may be used to navigate between the items, `ENTER` selects the focused item. ### Button The `Button` widget is keyboard accessible. If it has a configured `menu`, then `ENTER` will activate the menu. `ESC` will hide the menu. ### Menu The `Menu` widget is keyboard accessible. `down-arrow` move focus down the menu. `MenuItem`s with enabled menus will open their child menu upon focus. `RIGHT` enters the child menu. `ENTER` activates normal `MenuItem`s. ### DateField The `DateField` widget is keyboard accessible. `Shift+down-arrow` activates the "nudge backwards" trigger. `Shift+up-arrow` activates the "nudge forwards" trigger. Pressing `down-arrow` shows a popup date picker which is an aria Grid in which each cell represents a date. As with all grids, up, down, left and right navigate as expected with wrapping to the previous month at the edges. When focused on a date cell, `ENTER` selects that date and sets the value of the date field. `TAB` and `shift-TAB` navigate to the month and year change buttons in the header and then back into the cells. As with all popups, ESC closes the date picker. Focus reverts to the `DateField`. ### TimeField `Shift+down-arrow` activates the "nudge backwards" trigger. `Shift+up-arrow` activates the "nudge forwards" trigger. Pressing `down-arrow` shows a popup time picker which allows the hours, minutes and AM/PM to be chosen separately. The inpout fields, being numeric increment on `up-arrow` and decrement on `down-arrow`. ### Popup The `Popup` widget is keyboard accessible in that `TAB` functions normally, but is trapped within the popup. If an `ESCAPE` keyboard event bubbles from a while widget, this closes the popup and reverts focus to the element that was focused before the popup was shown. This is the case for all widgets which are transient and contain focus when they hide. The hide operation actively pushes focus back to the element from which focus entered the widget. ### TabPanel The `TabPanel` widget is keyboard accessible. The tabs in the tab list are `Button`s and are tabbable. When the `TAB` key is used to navigate into the tab list, the currently active tab is focused. `TAB` moves betweem them as usual. Activate the focused tab using the `ENTER` key. The newly activated child of the `TabPanel` is focused. ### Grid The `Grid` widget is accessible according to WAI-ARIA guidelines. The column headers are treated as grid cells, and constitute row 1 of the grid. `UP`, `DOWN`, `LEFT` and `RIGHT` arrow keys work as expected to move focus to adjacent cells. When navigation moves onto an input field (like a filter field) which is inside a cell, `ESCAPE` moves focus upwards to the header element ready for onward navigation or `TAB`/`shift+TAB` may be used to move to the next/previous cell because arrow keys are used for input editing. `SPACE` invokes the defined context menu if enabled. So for a column header, the `HeaderMenu` feature will activate. From a data cell, the `CellMenu` feature will activate. The `HeaderMenu` is the way to access sorting, grouping, filtering and moving columns between sub grids in a keyboard-accessible manner. `PAGE UP` moves up in the current column by one page. `PAGE DOWN` moves up in the current column by one page. `HOME` moves to the first cell in a row. `END` moves to the last cell in a row. `CTRL/HOME` moves to the first cell (The first column header). `CTRL/END` moves to the last cell. If a cell has focusable content, navigating to that cell focuses the first focusable element in the cell which may then be used as normal. The `TAB` key may be used inside the cell. Arrow and other grid navigation keys work as usual and navigate away from the cell. `ENTER` invokes the defined cell editor for the cell (if any, and if the `CellEdit` feature is enabled) When focused inside a cell, `ESCAPE` moves focus back up to the cell. #### Tree feature When a Grid is configured to represent data as a tree, the following keystrokes manipulate the nodes: `Shift+left-arrow` when focused on the tree column collapses the node. `Shift+right-arrow` when focused on the tree column expands the node. #### Filter feature When focused on a filterable column header, typing `F` will show and focus the filter field. #### Search feature

Last modified on 2023-10-26 8:18:56