diff --git a/aria-practices.html b/aria-practices.html index 43b832873c..513b897a31 100644 --- a/aria-practices.html +++ b/aria-practices.html @@ -486,7 +486,361 @@

WAI-ARIA Roles, States, and Properties

Combo Box

-

Drafting this section is issue 31.

+

NOTE: Work on drafting this section is in progress and tracked by issue 31.

+

+ A combobox is a widget made up of the combination of two distinct elements: + 1) a single-line textbox, and 2) an associated pop-up element for helping users set the value of the textbox. + The popup may be a listbox, + grid, + tree, or + dialog. + Many implementations also include a third optional element -- a graphical button adjacent to the textbox, indicating the availability of the popup. + Activating the button displays the popup if suggestions are available. +

+

+ The popup is hidden by default, and the conditions that trigger its display are specific to each implementation. + For example, some implementations do not display suggested values for the textbox in the popup until several characters are typed in the text box. + While in other implementations, the popup is displayed when the textbox receives focus. +

+

Combobox widgets are useful for setting the value of a single-line textbox in one of two types of scenarios:

+
    +
  1. + The value for the textbox must be chosen from a predefined set of allowed values, + e.g., a location field must contain a valid location name. + Note that the listbox and menu button patterns are also useful in this scenario; differences between combobox and alternative patterns are described below. +
    2. +
  2. + The textbox may contain any arbitrary value, but it is advantageous to suggest possible values to the user, + e.g., a search field may suggest similar or previous searches to save the user time. +
    3. +
+

+ The nature of the suggested values and the way the suggestions are presented is called the autocomplete behavior. + Comboboxes can have one of four forms of autocomplete: +

+
    +
  1. + No autocomplete: When the popup is triggered, the suggested values it contains are the same regardless of the characters typed in the textbox. + For example, the popup suggests a set of recently entered values, and the suggestions do not change as the user types. +
    2. +
  2. + List autocomplete with manual selection: When the popup is triggered, it presents suggested values that complete or logically correspond to the characters typed in the textbox. + The character string the user has typed will become the value of the textbox unless the user selects a value in the popup. +
    3. +
  3. + List autocomplete with automatic selection: When the popup is triggered, it presents suggested values that complete or logically correspond to the characters typed in the textbox, + and the first suggestion is automatically highlighted as selected. + The automatically selected suggestion becomes the value of the textbox when the combobox loses focus unless the user chooses a different suggestion or changes the character string in the textbox. +
    4. +
  4. + List with inline autocomplete: This is the same as list with automatic selection with one additional feature. + The portion of the selected suggestion that has not been typed by the user, a completion string, appears inline after the input cursor in the textbox. + The inline completion string is visually highlighted and has a selected state. +
    5. +
+

+ With any form of list autocomplete, the popup may appear and disappear as the user types. + For example, if the user types a two character string that triggers five suggestions to be displayed but then types a third character that forms a string that does not have any matching suggestions, + the popup may close and, if present, the inline completion string disappears. +

+

+ When constructing a compact widget that asks users to choose one value from a known set of discrete values, often either a listbox or menu button is simpler to implement and use. + One feature of combobox that distinguishes it from both listbox and menu button is that the value of the combobox is presented in an edit field. + Thus, the combobox gives users one function that both listbox and menu button lack, namely the ability to select some or all of the value for copying to the clipboard. + A feature that distinguishes both combobox and menu button from listbox is that they can enable users can navigate the set of allowed values and, at any point, decide to keep the current value by pressing escape. + In contrast, navigating a listbox immediately changes its value, and escape does not provide an undo mechanism. +

+

+ The options for a combobox to popup a grid, tree, or dialog were introduced in ARIA 1.1. + Changes made in the ARIA 1.1 specification also add support for a code pattern that enables assistive technologies to present the textbox and popup as separately perceivable elements. + While the ARIA 1.1 pattern is recommended, both patterns are described in the following sections, + and there are no plans to deprecate the ARIA 1.0 pattern. +

+ +
+

Examples

+ +
+ +
+

Keyboard Interaction

+ +
Textbox Keyboard Interaction
+

When focus is in the textbox:

+ +
Listbox Popup Keyboard Interaction
+

When focus is in a listbox popup:

+ +
    +
  1. DOM Focus is maintained on the combobox textbox and the assistive technology focus is moved within the grid using aria-activedescendant as described in Managing Focus in Composites Using aria-activedescendant.
    2. +
  2. Selection follows focus in the listbox; the listbox allows only one suggested value to be selected at a time for the textbox value.
    3. +
+
Grid Popup Keyboard Interaction
+

+ In a grid popup, each suggested value may be represented by either a single cell or an entire row. + See notes below for how this aspect of grid design effects the keyboard interaction design and the way that selection moves in response to focus movements. +

+ +
    +
  1. DOM Focus is maintained on the combobox textbox and the assistive technology focus is moved within the grid using aria-activedescendant as described in Managing Focus in Composites Using aria-activedescendant.
    2. +
  2. The grid allows only one suggested value to be selected at a time for the textbox value.
    3. +
  3. In a grid popup, each suggested value may be represented by either a single cell or an entire row. This aspect of design effects focus and selection movement: +
      +
    1. If every cell contains a different suggested value: +
        +
      • Selection follows focus so that the cell containing focus is selected.
        • +
      • Horizontal arrow key navigation typically wraps from one row to another.
        • +
      • Vertical arrow key navigation typically wraps from one column to another.
        • +
      +
      2. +
    2. If all cells in a row contain information about the same suggested value: +
        +
      • Either the row containing focus is selected or a cell containing a suggested value is selected when any cell in the same row contains focus.
        • +
      • Horizontal key navigation may wrap from one row to another.
        • +
      • Vertical arrow key navigation does not wrap from one column to another.
        • +
      +
      3. +
    +
    4. +
+
Tree Popup Keyboard Interaction
+

+ In some implementations of tree popups, some or all parent nodes may serve as suggestion category labels so may not be selectable values. + See notes below for how this aspect of the design effects the way selection moves in response to focus movements. +

+

When focus is in a vertically oriented tree popup:

+ +
    +
  1. DOM Focus is maintained on the combobox textbox and the assistive technology focus is moved within the tree using aria-activedescendant as described in Managing Focus in Composites Using aria-activedescendant.
    2. +
  2. The tree allows only one suggested value to be selected at a time for the textbox value.
    3. +
  3. + In a tree popup, some or all parent nodes may not be selectable values; they may serve as category labels for suggested values. + If focus moves to a node that is not a selectable value, either: +
      +
    • The previously selected node, if any, remains selected until focus moves to a node that is selectable.
      • +
    • There is no selected value.
      • +
    • In either case, focus is fisually distinct from selection so users can readily see if a value is selected or not.
      • +
    +
    4. +
  4. If the nodes in a tree are arranged horizontally: +
      +
    1. Down Arrow performs as Right Arrow is described above, and vice versa.
      2. +
    2. Up Arrow performs as Left Arrow is described above, and vice versa.
      3. +
    +
    5. +
+
Dialog Popup Keyboard Interaction
+

When focus is in a dialog popup:

+ +

+ Unlike other combobox popups, dialogs do not support aria-activedescendant so DOM focus moves into the dialog from the textbox. +

+
+ +
+

WAI-ARIA Roles, States, and Properties

+

+ The role, state, and property guidance where the ARIA 1.1 and ARIA 1.0 patterns differ is listed first. + The subsequent guidance applies to both patterns. +

+ +

+ The roles, states, and properties for popup elements are defined in their respective design patterns. + When refering to the following design patterns, note that a combobox is a single-select widget where selection follows focus in the popup. +

+ +
@@ -572,7 +926,7 @@

Keyboard Interaction

-
+

WAI-ARIA Roles, States, and Properties

-
+

WAI-ARIA Roles, States, and Properties