From a2af4b3185f2921879196ab0584106538a800d42 Mon Sep 17 00:00:00 2001 From: Matt King Date: Thu, 21 Sep 2017 16:31:59 -0700 Subject: [PATCH] ARIA 1.1 Combobox Pattern: First Draft with Two Examples (pull #463) * For issue #31, first draft of the combobox design pattern. * For issue #100, first cut of code for ARIA 1.1 style combobox examples with listbox and grid popups. The example pages do not yet include any documentation; example code only. --- aria-practices.html | 365 +++++++++++++++++- .../aria1.1pattern/css/combobox-1.1.css | 86 +++++ .../combobox/aria1.1pattern/grid-combo.html | 57 +-- .../imgs/arrow_drop_down_grey_27x27.png | Bin 0 -> 220 bytes .../aria1.1pattern/js/combobox-1.1.js | 3 - .../aria1.1pattern/js/grid-combo-example.js | 96 +++++ .../aria1.1pattern/js/grid-combobox.js | 288 ++++++++++++++ .../js/listbox-combo-example.js | 136 +++++++ .../aria1.1pattern/js/listbox-combobox.js | 245 ++++++++++++ .../aria1.1pattern/listbox-combo.html | 132 +++++-- 10 files changed, 1343 insertions(+), 65 deletions(-) create mode 100644 examples/combobox/aria1.1pattern/imgs/arrow_drop_down_grey_27x27.png delete mode 100644 examples/combobox/aria1.1pattern/js/combobox-1.1.js create mode 100644 examples/combobox/aria1.1pattern/js/grid-combo-example.js create mode 100644 examples/combobox/aria1.1pattern/js/grid-combobox.js create mode 100644 examples/combobox/aria1.1pattern/js/listbox-combo-example.js create mode 100644 examples/combobox/aria1.1pattern/js/listbox-combobox.js 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

+
    +
  • Tab: The textbox is in the page Tab sequence.
    • +
  • Note: The popup indicator icon (if present), the popup, and the popup descendants are excluded from the page Tab sequence.
    • +
+
Textbox Keyboard Interaction
+

When focus is in the textbox:

+
    +
  • Down Arrow: If the popup is available, moves focus into the popup: +
      +
    • If the autocomplete behavior automatically selects a suggestion, focus is placed on the suggestion following the automatically selected suggestion.
      • +
    • Otherwise, places focus on the first focusable element in the popup.
      • +
    +
    • +
  • Alt + Down Arrow (Optional): Performs the same function as Down Arrow.
    • +
  • Up Arrow (Optional): If the popup is available, places focus on the last focusable element in the popup.
    • +
  • Printable Characters: Type characters in the textbox. Note that some implementations may regard certain characters as invalid and prevent their input.
    • +
  • + Enter: If an autocomplete suggestion is automatically selected, accepts the suggestion either by placing the input cursor at the end of the accepted value in the textbox or by performing a default action on the value. + For example, in a messaging application, the default action may be to add the accepted value to a list of message recipients and then clear the textbox so the user can add another recipient. +
    • +
  • Escape: Dismisses the popup if it is visible. Optionally, clears the textbox.
    • +
  • Alt + Up Arrow (Optional): Dismisses the popup if visible.
    • +
  • Right Arrow: Moves the cursor right one character. Does nothing if the cursor is on the right-most character.
    • +
  • Left Arrow: Moves the cursor left one character. Does nothing if the cursor is on the left-most character.
    • +
  • Control + Right Arrow: Moves the cursor right one word. Does nothing if the cursor is on the right-most word .
    • +
  • Control + Left Arrow: Moves the cursor left one word. Does nothing if the cursor is on the left-most word.
    • +
  • Home: Moves the cursor to the first character. Does nothing if the cursor is on the first character.
    • +
  • End: Moves the cursor to the last character. Does nothing if the cursor is on the last character.
    • +
  • Delete: Deletes the current character or, if text is selected, deletes the selected text
    • +
  • Backspace: Deletes the previous character, or, if text is selected, deletes the selected text.
    • +
  • Shift + Right Arrow: Extends selection one character to the right. Does nothing if the cursor is on the right-most character.
    • +
  • Shift + Left Arrow: Extends selection one character to the left. Does nothing if the cursor is on the left-most character.
    • +
  • Control + Shift + Right Arrow: Extends selection one word to the right. Does nothing if the cursor is after the right-most word.
    • +
  • Control + Shift + Left Arrow: Extends selection one word to the left. Does nothing if the cursor is at the start of the left-most word.
    • +
  • Shift + Home: Extends selection from the cursor position to the first character.
    • +
  • Shift + End: Extends selection from the cursor position to the last character.
    • +
  • Control + A (Optional): Selects all the text in the textbox. +
+
Listbox Popup Keyboard Interaction
+

When focus is in a listbox popup:

+
    +
  • Enter: Accepts the focused option in the listbox by closing the popup and placing the accepted value in the textbox with the input cursor at the end of the value.
    • +
  • Escape: Closes the popup and returns focus to the textbox. Optionally, clears the contents of the textbox.
    • +
  • + Right Arrow: Returns focus to the textbox without closing the popup and moves the input cursor one character to the right. + If the input cursor is on the right-most character, the cursor does not move. +
    • +
  • + Left Arrow: Returns focus to the textbox without closing the popup and moves the input cursor one character to the left. + If the input cursor is on the left-most character, the cursor does not move. +
    • +
  • Any printable character: Returns the focus to the textbox without closing the popup and types the character.
    • +
  • Backspace (Optional): Returns focus to the textbox and deletes the character prior to the cursor.
    • +
  • Delete (Optional): Returns focus to the textbox, removes the selected state if a suggestion was selected, and removes the inline autocomplete string if present.
    • +
  • Down Arrow: Moves focus to and selects the next option. If focus is on the last option, either returns focus to the textbox or does nothing.
    • +
  • Up Arrow: Moves focus to and selects the previous option. If focus is on the first option, either returns focus to the textbox or does nothing.
    • +
  • Home (Optional): Either moves focus to and selects the first option or returns focus to the textbox and places the cursor on the first character.
    • +
  • End (Optional): Either moves focus to the last option or returns focus to the textbox and places the cursor after the last character.
    • +
+
    +
  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. +

+
    +
  • Enter: Accepts the currently selected suggested value by closing the popup and placing the selected value in the textbox with the input cursor at the end of the value.
    • +
  • Escape: Closes the popup and returns focus to the textbox. Optionally, clears the contents of the textbox.
    • +
  • Any printable character: Returns the focus to the textbox without closing the popup and types the character.
    • +
  • Backspace (Optional): Returns focus to the textbox and deletes the character prior to the cursor.
    • +
  • Delete (Optional): Returns focus to the textbox, removes the selected state if a suggestion was selected, and removes the inline autocomplete string if present.
    • +
  • + Right Arrow: Moves focus one cell to the right. + Optionally, if focus is on the right-most cell in the row, focus may move to the first cell in the following row. + If focus is on the last cell in the grid, either does nothing or returns focus to the textbox. +
    • +
  • + Left Arrow: Moves focus one cell to the left. + Optionally, if focus is on the left-most cell in the row, focus may move to the last cell in the previous row. + If focus is on the first cell in the grid, either does nothing or returns focus to the textbox. +
    • +
  • + Down Arrow: Moves focus one cell down. + If focus is in the last row of the grid, either does nothing or returns focus to the textbox. +
    • +
  • + Up Arrow: Moves focus one cell up. + If focus is in the first row of the grid, either does nothing or returns focus to the textbox. +
    • +
  • + Page Down (Optional): Moves focus down an author-determined number of rows, typically scrolling so the bottom row in the currently visible set of rows becomes one of the first visible rows. + If focus is in the last row of the grid, focus does not move. +
    • +
  • + Page Up (Optional): Moves focus up an author-determined number of rows, typically scrolling so the top row in the currently visible set of rows becomes one of the last visible rows. + If focus is in the first row of the grid, focus does not move. +
    • +
  • Home (Optional): Either: +
      +
    • Moves focus to the first cell in the row that contains focus. Or, if the grid has fewer than three cells per row or multiple suggested values per row, focus may move to the first cell in the grid.
      • +
    • Returns focus to the textbox and places the cursor on the first character.
      • +
    +
    • +
  • End (Optional): Either: +
      +
    • Moves focus to the last cell in the row that contains focus. Or, if the grid has fewer than three cells per row or multiple suggested values per row, focus may move to the last cell in the grid.
      • +
    • Returns focus to the textbox and places the cursor after the last character.
      • +
    +
    • +
  • Control + Home (optional): moves focus to the first row.
    • +
  • Control + End (Optional): moves focus to the last row.
    • +
+
    +
  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:

+
    +
  • Enter: Accepts the currently selected suggested value by closing the popup and placing the selected value in the textbox with the input cursor at the end of the value.
    • +
  • Escape: Closes the popup and returns focus to the textbox. Optionally, clears the contents of the textbox.
    • +
  • Any printable character: Returns the focus to the textbox without closing the popup and types the character.
    • +
  • Right arrow: +
      +
    • When focus is on a closed node, opens the node; focus and selection do not move.
      • +
    • When focus is on a open node, moves focus to the first child node and selects it if it is selectable.
      • +
    • When focus is on an end node, does nothing.
      • +
    +
    • +
  • Left arrow: +
      +
    • When focus is on an open node, closes the node.
      • +
    • When focus is on a child node that is also either an end node or a closed node, moves focus to its parent node and selects it if it is selectable.
      • +
    • When focus is on a root node that is also either an end node or a closed node, does nothing.
      • +
    +
    • +
  • Down Arrow: Moves focus to the next node that is focusable without opening or closing a node and selects it if it is selectable.
    • +
  • Up Arrow: Moves focus to the previous node that is focusable without opening or closing a node and selects it if it is selectable.
    • +
  • Home: Moves focus to the first node in the tree without opening or closing a node and selects it if it is selectable.
    • +
  • End: Moves focus to the last node in the tree that is focusable without opening a node and selects it if it is selectable.
    • +
+
    +
  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:

+
    +
  • There are two ways to close the popup and return focus to the textbox: +
      +
    1. Perform an action in the dialog, such as activate a button, that specifies a value for the textbox.
      2. +
    2. + Cancel out of the dialog, e.g., press Escape or activate the cancel button in the dialog. + Canceling either returns focus to the text box without changing the textbox value or returns focus to the textbox and clears the textbox. +
      3. +
    +
    • +
  • The dialog implements the keyboard interaction defined in the modal dialog pattern.
    • +
+

+ 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. +

+
    +
  • In a combobox implementing the ARIA 1.1 pattern: +
      +
    • The element that serves as the combobox container has role combobox.
      • +
    • The element with role combobox contains or owns a textbox element that has either role textbox or role searchbox.
      • +
    • When the combobox popup is visible, the combobox element contains or owns an element that has role listbox, tree, grid, or dialog.
      • +
    • + If the combobox popup has a role other than listbox, the element with role combobox has aria-haspopup set to a value that corresponds to the popup type. + That is, aria-haspopup is set to grid, tree, or dialog. + Note that elements with role combobox have an implicit aria-haspopup value of listbox. +
      • +
    • When the combobox popup is visible, the textbox element has aria-controls set to a value that refers to the combobox popup element.
      • +
    +
    • +
  • In a combobox implementing the ARIA 1.0 pattern: +
      +
    • The element that serves as the textbox has role combobox.
      • +
    • When the combobox popup is visible, the element with role combobox has aria-owns set to a value that refers to an element with role listbox. +
    • + the element with role combobox has a value for aria-haspopup of listbox. + Note that elements with role combobox have an implicit aria-haspopup value of listbox. +
      • +
    +
    • +
  • + The textbox element has a value for aria-multiline of false. + Note that the default value of aria-multiline is false. +
    • +
  • + When the combobox popup is not visible, the element with role combobox has aria-expanded set to false. + When the popup element is visible, aria-expanded is set to true. + Note that Elements with role combobox have a default value for aria-expanded of false. +
    • +
  • When a combobox receives focus, DOM focus is placed on the textbox element.
    • +
  • When a descendant of a listbox, grid, or tree popup is focused, DOM focus remains on the textbox and the textbox has aria-activedescendant set to a value that refers to the focused element within the popup.
    • +
  • In a combobox with a listbox, grid, or tree popup, when a suggested value is visually indicated as the currently selected value, the option, gridcell, row, or treeitem containing that value has aria-selected set to true.
    • +
  • + If the combobox has a visible label, the element with role combobox has aria-labelledby set to a value that refers to the labeling element. + Otherwise, the combobox element has a label provided by aria-label. +
    • +
  • The textbox element has aria-autocomplete set to a value that corresponds to its autocomplete behavior: +
      +
    • none: When the popup is displayed, the suggested values it contains are the same regardless of the characters typed in the textbox.
      • +
    • list: When the popup is triggered, it presents suggested values that complete or logically correspond to the characters typed in the textbox.
      • +
    • + both: When the popup is triggered, it presents suggested values that complete or logically correspond to the characters typed in the textbox. + In addition, 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. +
      • +
    +
    • +
+

+ 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

  • The element that serves as the dialog container has a role of dialog.
    • @@ -1112,7 +1466,7 @@
    Editing and Navigating Inside a Cell
-
+

WAI-ARIA Roles, States, and Properties

  • The grid container has role grid.
    • @@ -1197,7 +1551,6 @@

    WAI-ARIA Roles, States, and Properties

    Listbox

    -

    A listbox widget presents a list of options and allows a user to select one or more of them. A listbox that allows a single option to be chosen is a single-select listbox; one that allows multiple options to be selected is a multi-select listbox. @@ -1312,7 +1665,7 @@

    Keyboard Interaction

    -
    +

    WAI-ARIA Roles, States, and Properties

    • An element that contains or owns all the listbox options has role listbox.
      • @@ -2226,7 +2579,7 @@

      Keyboard Interaction

    -
    +

    WAI-ARIA Roles, States, and Properties

    • All tree nodes are contained in or owned by an element with role tree.
      • diff --git a/examples/combobox/aria1.1pattern/css/combobox-1.1.css b/examples/combobox/aria1.1pattern/css/combobox-1.1.css index 85c190566f..3cfd193dca 100644 --- a/examples/combobox/aria1.1pattern/css/combobox-1.1.css +++ b/examples/combobox/aria1.1pattern/css/combobox-1.1.css @@ -2,3 +2,89 @@ font-style: italic; color: #366ED4; } + +.hidden { + display: none; +} + +.combobox-wrapper { + display: inline-block; + position: relative; + font-size: 16px; +} + +.combobox-label { + font-size: 14px; + font-weight: bold; + margin-right: 5px; +} + +.listbox, .grid { + min-width: 230px; + background: white; + border: 1px solid #ccc; + list-style: none; + margin: 0; + padding: 0; + position: absolute; + top: 1.7em; + z-index: 1; +} + +.listbox .result { + cursor: default; + margin: 0; +} + +.listbox .result:hover, .grid .result-row:hover { + background: rgb(139, 189, 225); +} + +.listbox .focused, .grid .focused { + background: rgb(139, 189, 225); +} + +.grid .focused-cell { + outline-style: dotted; + outline-color: green; +} + +.combobox-wrapper input { + font-size: inherit; + border: 1px solid #aaa; + border-radius: 2px; + line-height: 1.5em; + padding-right: 30px; + width: 200px; +} + +.combobox-dropdown { + position: absolute; + right: 0; + top: 0; + padding: 0 0 2px; + height: 1.5em; + border-radius: 0 2px 2px 0; + border: 1px solid #aaa; +} + +.grid .result-row { + padding: 2px; + cursor: default; + margin: 0; +} + +.grid .result-cell { + display: inline-block; + cursor: default; + margin: 0; + padding: 0 5px; +} + +.grid .result-cell:last-child { + float: right; + font-size: 12px; + font-weight: 200; + color: #333; + line-height: 24px; +} diff --git a/examples/combobox/aria1.1pattern/grid-combo.html b/examples/combobox/aria1.1pattern/grid-combo.html index 23b78345a8..303c74fa95 100644 --- a/examples/combobox/aria1.1pattern/grid-combo.html +++ b/examples/combobox/aria1.1pattern/grid-combo.html @@ -10,10 +10,12 @@ + - + +
      @@ -23,11 +25,9 @@

      Example of ARIA 1.1 Combobox with Grid Popup

      This work is tracked by issue 100.

      - - Replace this paragraph with an overview of the example that is something like the following. The - below example section demonstrates a simple checkbox that implements the - design pattern for checkbox. - This example uses ... summarize salient techniques ) + The following example demonstrates an implementation of the + combobox design pattern + that uses the option to popup a grid containing suggested values.

      Similar examples include:

        @@ -38,25 +38,31 @@

        Example of ARIA 1.1 Combobox with Grid Popup

        Example

        -
        - -

        This is the place where the reader will experience the functioning example.

        -
          -
        • The HTML in this section along with the javascript and CSS it uses demonstrate - the design pattern.
          • -
        • - When developing an example implementation for this guide, please follow the - APG example coding guidelines - . -
          • - -
        + +
        + + +
        +
        @@ -190,7 +196,8 @@

        HTML Source Code

      diff --git a/examples/combobox/aria1.1pattern/imgs/arrow_drop_down_grey_27x27.png b/examples/combobox/aria1.1pattern/imgs/arrow_drop_down_grey_27x27.png new file mode 100644 index 0000000000000000000000000000000000000000..7007ef59f0b45e9976e4883eda39106459a07b3e GIT binary patch literal 220 zcmeAS@N?(olHy`uVBq!ia0vp^(jd&i0wmS%+S~(D3dtTpz6=aiY77hwEes65fIY(YII@bfe1e0?qYEwiDyzopr0P1Kzk^lez literal 0 HcmV?d00001 diff --git a/examples/combobox/aria1.1pattern/js/combobox-1.1.js b/examples/combobox/aria1.1pattern/js/combobox-1.1.js deleted file mode 100644 index d82228b0dd..0000000000 --- a/examples/combobox/aria1.1pattern/js/combobox-1.1.js +++ /dev/null @@ -1,3 +0,0 @@ -/** - * Rename this file to the name of the example, e.g., checkbox.js. - */ diff --git a/examples/combobox/aria1.1pattern/js/grid-combo-example.js b/examples/combobox/aria1.1pattern/js/grid-combo-example.js new file mode 100644 index 0000000000..eadd97eec6 --- /dev/null +++ b/examples/combobox/aria1.1pattern/js/grid-combo-example.js @@ -0,0 +1,96 @@ +/** + * ARIA Combobox Examples + */ + +var FRUITS_AND_VEGGIES = [ + ['Apple', 'Fruit'], + ['Artichoke', 'Vegetable'], + ['Asparagus', 'Vegetable'], + ['Banana', 'Fruit'], + ['Beets', 'Vegetable'], + ['Bell pepper', 'Vegetable'], + ['Broccoli', 'Vegetable'], + ['Brussels sprout', 'Vegetable'], + ['Cabbage', 'Vegetable'], + ['Carrot', 'Vegetable'], + ['Cauliflower', 'Vegetable'], + ['Celery', 'Vegetable'], + ['Chard', 'Vegetable'], + ['Chicory', 'Vegetable'], + ['Corn', 'Vegetable'], + ['Cucumber', 'Vegetable'], + ['Daikon', 'Vegetable'], + ['Date', 'Fruit'], + ['Edamame', 'Vegetable'], + ['Eggplant', 'Vegetable'], + ['Elderberry', 'Fruit'], + ['Fennel', 'Vegetable'], + ['Fig', 'Fruit'], + ['Garlic', 'Vegetable'], + ['Grape', 'Fruit'], + ['Honeydew melon', 'Fruit'], + ['Iceberg lettuce', 'Vegetable'], + ['Jerusalem artichoke', 'Vegetable'], + ['Kale', 'Vegetable'], + ['Kiwi', 'Fruit'], + ['Leek', 'Vegetable'], + ['Lemon', 'Fruit'], + ['Mango', 'Fruit'], + ['Mangosteen', 'Fruit'], + ['Melon', 'Fruit'], + ['Mushroom', 'Fungus'], + ['Nectarine', 'Fruit'], + ['Okra', 'Vegetable'], + ['Olive', 'Vegetable'], + ['Onion', 'Vegetable'], + ['Orange', 'Fruit'], + ['Parship', 'Vegetable'], + ['Pea', 'Vegetable'], + ['Pear', 'Fruit'], + ['Pineapple', 'Fruit'], + ['Potato', 'Vegetable'], + ['Pumpkin', 'Fruit'], + ['Quince', 'Fruit'], + ['Radish', 'Vegetable'], + ['Rhubarb', 'Vegetable'], + ['Shallot', 'Vegetable'], + ['Spinach', 'Vegetable'], + ['Squash', 'Vegetable'], + ['Strawberry', 'Fruit'], + ['Sweet potato', 'Vegetable'], + ['Tomato', 'Fruit'], + ['Turnip', 'Vegetable'], + ['Ugli fruit', 'Fruit'], + ['Victoria plum', 'Fruit'], + ['Watercress', 'Vegetable'], + ['Watermelon', 'Fruit'], + ['Yam', 'Vegetable'], + ['Zucchini', 'Vegetable'] +]; + +function searchVeggies (searchString) { + var results = []; + + for (var i = 0; i < FRUITS_AND_VEGGIES.length; i++) { + var veggie = FRUITS_AND_VEGGIES[i][0].toLowerCase(); + if (veggie.indexOf(searchString.toLowerCase()) === 0) { + results.push(FRUITS_AND_VEGGIES[i]); + } + } + + return results; +} + +/** + * @function onload + * @desc Initialize the combobox examples once the page has loaded + */ +window.addEventListener('load', function () { + var ex1Combobox = new aria.GridCombobox( + document.getElementById('ex1-combobox'), + document.getElementById('ex1-input'), + document.getElementById('ex1-grid'), + searchVeggies + ); + +}); diff --git a/examples/combobox/aria1.1pattern/js/grid-combobox.js b/examples/combobox/aria1.1pattern/js/grid-combobox.js new file mode 100644 index 0000000000..5b5a143972 --- /dev/null +++ b/examples/combobox/aria1.1pattern/js/grid-combobox.js @@ -0,0 +1,288 @@ +/** + * @constructor + * + * @desc + * Combobox object representing the state and interactions for a combobox + * widget + * + * @param comboboxNode + * The DOM node pointing to the combobox + * @param input + * The input node + * @param grid + * The grid node to load results in + * @param searchFn + * The search function. The function accepts a search string and returns an + * array of results. + */ +aria.GridCombobox = function ( + comboboxNode, + input, + grid, + searchFn +) { + this.combobox = comboboxNode; + this.input = input; + this.grid = grid; + this.searchFn = searchFn; + this.activeRowIndex = -1; + this.activeColIndex = 0; + this.rowsCount = 0; + this.colsCount = 0; + this.gridFocused = false; + this.shown = false; + this.selectionCol = 0; + + this.setupEvents(); +}; + +aria.GridCombobox.prototype.setupEvents = function () { + document.body.addEventListener('click', this.checkHide.bind(this)); + this.input.addEventListener('keyup', this.checkKey.bind(this)); + this.input.addEventListener('keydown', this.setActiveItem.bind(this)); + this.input.addEventListener('focus', this.checkShow.bind(this)); + this.grid.addEventListener('click', this.clickItem.bind(this)); +}; + +aria.GridCombobox.prototype.checkKey = function (evt) { + var key = evt.which || evt.keyCode; + + switch (key) { + case aria.KeyCode.UP: + case aria.KeyCode.DOWN: + case aria.KeyCode.ESC: + case aria.KeyCode.RETURN: + evt.preventDefault(); + return; + case aria.KeyCode.LEFT: + case aria.KeyCode.RIGHT: + if (this.gridFocused) { + console.log('grid focused'); + evt.preventDefault(); + return; + } + default: + this.updateResults(); + } +}; + +aria.GridCombobox.prototype.updateResults = function () { + var searchString = this.input.value; + var results = this.searchFn(searchString); + + this.hideResults(); + + if (!searchString) { + results = []; + } + + if (results.length) { + for (var row = 0; row < results.length; row++) { + var resultRow = document.createElement('div'); + resultRow.className = 'result-row'; + resultRow.setAttribute('role', 'row'); + resultRow.setAttribute('id', 'result-row-' + row); + for (var col = 0; col < results[row].length; col++) { + var resultCell = document.createElement('div'); + resultCell.className = 'result-cell'; + resultCell.setAttribute('role', 'gridcell'); + resultCell.setAttribute('id', 'result-item-' + row + 'x' + col); + resultCell.innerText = results[row][col]; + resultRow.appendChild(resultCell); + } + this.grid.appendChild(resultRow); + } + aria.Utils.removeClass(this.grid, 'hidden'); + this.combobox.setAttribute('aria-expanded', 'true'); + this.rowsCount = results.length; + this.colsCount = results.length ? results[0].length : 0; + this.shown = true; + } +}; + +aria.GridCombobox.prototype.setActiveItem = function (evt) { + var key = evt.which || evt.keyCode; + var activeRowIndex = this.activeRowIndex; + var activeColIndex = this.activeColIndex; + + if (key === aria.KeyCode.ESC) { + if (this.gridFocused) { + this.gridFocused = false; + this.removeFocusCell(this.activeRowIndex, this.activeColIndex); + this.activeRowIndex = -1; + this.activeColIndex = 0; + this.input.setAttribute( + 'aria-activedescendant', + '' + ); + } + else { + this.hideResults(); + setTimeout((function () { + // On Firefox, input does not get cleared here unless wrapped in + // a setTimeout + this.input.value = ''; + }).bind(this), 1); + } + return; + } + + if (this.rowsCount < 1) { + return; + } + + var prevActive = this.getItemAt(activeRowIndex, this.selectionCol); + var activeItem; + + switch (key) { + case aria.KeyCode.UP: + this.gridFocused = true; + if (activeRowIndex <= 0) { + activeRowIndex = this.rowsCount - 1; + } + else { + activeRowIndex--; + } + evt.preventDefault(); + break; + case aria.KeyCode.DOWN: + this.gridFocused = true; + if (activeRowIndex === -1 || activeRowIndex >= this.rowsCount - 1) { + activeRowIndex = 0; + } + else { + activeRowIndex++; + } + evt.preventDefault(); + break; + case aria.KeyCode.LEFT: + if (activeColIndex <= 0) { + activeColIndex = this.colsCount - 1; + } + else { + activeColIndex--; + } + if (this.gridFocused) { + evt.preventDefault(); + } + break; + case aria.KeyCode.RIGHT: + if (activeColIndex === -1 || activeColIndex >= this.colsCount - 1) { + activeColIndex = 0; + } + else { + activeColIndex++; + } + if (this.gridFocused) { + evt.preventDefault(); + } + break; + case aria.KeyCode.RETURN: + activeItem = this.getItemAt(activeRowIndex, this.selectionCol); + this.selectItem(activeItem); + this.gridFocused = false; + return; + case aria.KeyCode.TAB: + this.hideResults(); + return; + default: + return; + } + + if (prevActive) { + this.removeFocusCell(this.activeRowIndex, this.activeColIndex); + prevActive.setAttribute('aria-selected', 'false'); + } + + activeItem = this.getItemAt(activeRowIndex, activeColIndex); + this.activeRowIndex = activeRowIndex; + this.activeColIndex = activeColIndex; + + if (activeItem) { + this.input.setAttribute( + 'aria-activedescendant', + 'result-item-' + activeRowIndex + 'x' + activeColIndex + ); + this.focusCell(activeRowIndex, activeColIndex); + var selectedItem = this.getItemAt(activeRowIndex, this.selectionCol); + selectedItem.setAttribute('aria-selected', 'true'); + } + else { + this.input.setAttribute( + 'aria-activedescendant', + '' + ); + } +}; + +aria.GridCombobox.prototype.getItemAt = function (rowIndex, colIndex) { + return document.getElementById('result-item-' + rowIndex + 'x' + colIndex); +}; + +aria.GridCombobox.prototype.clickItem = function (evt) { + if (!evt.target) { + return; + } + + var row; + if (evt.target.getAttribute('role') === 'row') { + row = evt.target; + } + else if (evt.target.getAttribute('role') === 'gridcell') { + row = evt.target.parentNode; + } + else { + return; + } + + var selectItem = row.querySelector('.result-cell'); + this.selectItem(selectItem); +}; + +aria.GridCombobox.prototype.selectItem = function (item) { + if (item) { + this.input.value = item.innerText; + this.hideResults(); + } +}; + +aria.GridCombobox.prototype.checkShow = function (evt) { + this.updateResults(); +}; + +aria.GridCombobox.prototype.checkHide = function (evt) { + if (evt.target === this.input || this.combobox.contains(evt.target)) { + return; + } + this.hideResults(); +}; + +aria.GridCombobox.prototype.hideResults = function () { + this.gridFocused = false; + this.shown = false; + this.activeRowIndex = -1; + this.activeColIndex = 0; + this.grid.innerHTML = null; + aria.Utils.addClass(this.grid, 'hidden'); + this.combobox.setAttribute('aria-expanded', 'false'); + this.rowsCount = 0; + this.colsCount = 0; + this.input.setAttribute( + 'aria-activedescendant', + '' + ); +}; + +aria.GridCombobox.prototype.removeFocusCell = function (rowIndex, colIndex) { + var row = document.getElementById('result-row-' + rowIndex); + aria.Utils.removeClass(row, 'focused'); + var cell = this.getItemAt(rowIndex, colIndex); + aria.Utils.removeClass(cell, 'focused-cell'); +}; + +aria.GridCombobox.prototype.focusCell = function (rowIndex, colIndex) { + var row = document.getElementById('result-row-' + rowIndex); + aria.Utils.addClass(row, 'focused'); + var cell = this.getItemAt(rowIndex, colIndex); + aria.Utils.addClass(cell, 'focused-cell'); +}; diff --git a/examples/combobox/aria1.1pattern/js/listbox-combo-example.js b/examples/combobox/aria1.1pattern/js/listbox-combo-example.js new file mode 100644 index 0000000000..c6105c7d69 --- /dev/null +++ b/examples/combobox/aria1.1pattern/js/listbox-combo-example.js @@ -0,0 +1,136 @@ +/** + * ARIA Combobox Examples + */ + +var FRUITS_AND_VEGGIES = [ + 'Apple', + 'Artichoke', + 'Asparagus', + 'Banana', + 'Beets', + 'Bell pepper', + 'Broccoli', + 'Brussels sprout', + 'Cabbage', + 'Carrot', + 'Cauliflower', + 'Celery', + 'Chard', + 'Chicory', + 'Corn', + 'Cucumber', + 'Daikon', + 'Date', + 'Edamame', + 'Eggplant', + 'Elderberry', + 'Fennel', + 'Fig', + 'Garlic', + 'Grape', + 'Honeydew melon', + 'Iceberg lettuce', + 'Jerusalem artichoke', + 'Kale', + 'Kiwi', + 'Leek', + 'Lemon', + 'Mango', + 'Mangosteen', + 'Melon', + 'Mushroom', + 'Nectarine', + 'Okra', + 'Olive', + 'Onion', + 'Orange', + 'Parship', + 'Pea', + 'Pear', + 'Pineapple', + 'Potato', + 'Pumpkin', + 'Quince', + 'Radish', + 'Rhubarb', + 'Shallot', + 'Spinach', + 'Squash', + 'Strawberry', + 'Sweet potato', + 'Tomato', + 'Turnip', + 'Ugli fruit', + 'Victoria plum', + 'Watercress', + 'Watermelon', + 'Yam', + 'Zucchini' +]; + +function searchVeggies (searchString) { + var results = []; + + for (var i = 0; i < FRUITS_AND_VEGGIES.length; i++) { + var veggie = FRUITS_AND_VEGGIES[i].toLowerCase(); + if (veggie.indexOf(searchString.toLowerCase()) === 0) { + results.push(FRUITS_AND_VEGGIES[i]); + } + } + + return results; +} + +/** + * @function onload + * @desc Initialize the combobox examples once the page has loaded + */ +window.addEventListener('load', function () { + var ex1Combobox = new aria.ListboxCombobox( + document.getElementById('ex1-combobox'), + document.getElementById('ex1-input'), + document.getElementById('ex1-listbox'), + searchVeggies, + false + ); + + var ex2Combobox = new aria.ListboxCombobox( + document.getElementById('ex2-combobox'), + document.getElementById('ex2-input'), + document.getElementById('ex2-listbox'), + searchVeggies, + true + ); + + var ex3Combobox = new aria.ListboxCombobox( + document.getElementById('ex3-combobox'), + document.getElementById('ex3-input'), + document.getElementById('ex3-listbox'), + searchVeggies, + true, + function () { + // on show + document.getElementById('ex3-combobox-arrow') + .setAttribute('aria-label', 'Hide vegetable options'); + }, + function () { + // on hide + document.getElementById('ex3-combobox-arrow') + .setAttribute('aria-label', 'Show vegetable options'); + } + ); + + document.getElementById('ex3-combobox-arrow').addEventListener( + 'click', + function () { + if (ex3Combobox.shown) { + document.getElementById('ex3-input').focus(); + ex3Combobox.hideListbox(); + } + else { + document.getElementById('ex3-input').focus(); + ex3Combobox.updateResults(true); + } + } + ); +}); diff --git a/examples/combobox/aria1.1pattern/js/listbox-combobox.js b/examples/combobox/aria1.1pattern/js/listbox-combobox.js new file mode 100644 index 0000000000..5b0660ba9c --- /dev/null +++ b/examples/combobox/aria1.1pattern/js/listbox-combobox.js @@ -0,0 +1,245 @@ +/** + * @constructor + * + * @desc + * Combobox object representing the state and interactions for a combobox + * widget + * + * @param comboboxNode + * The DOM node pointing to the combobox + * @param input + * The input node + * @param listbox + * The listbox node to load results in + * @param searchFn + * The search function. The function accepts a search string and returns an + * array of results. + */ +aria.ListboxCombobox = function ( + comboboxNode, + input, + listbox, + searchFn, + shouldAutoSelect, + onShow, + onHide +) { + this.combobox = comboboxNode; + this.input = input; + this.listbox = listbox; + this.searchFn = searchFn; + this.shouldAutoSelect = shouldAutoSelect; + this.onShow = onShow || function () {}; + this.onHide = onHide || function () {}; + this.activeIndex = -1; + this.resultsCount = 0; + this.shown = false; + this.hasInlineAutocomplete = + input.getAttribute('aria-autocomplete') === 'both'; + + this.setupEvents(); +}; + +aria.ListboxCombobox.prototype.setupEvents = function () { + document.body.addEventListener('click', this.checkHide.bind(this)); + this.input.addEventListener('keyup', this.checkKey.bind(this)); + this.input.addEventListener('keydown', this.setActiveItem.bind(this)); + this.input.addEventListener('focus', this.checkShow.bind(this)); + this.listbox.addEventListener('click', this.clickItem.bind(this)); +}; + +aria.ListboxCombobox.prototype.checkKey = function (evt) { + var key = evt.which || evt.keyCode; + + switch (key) { + case aria.KeyCode.UP: + case aria.KeyCode.DOWN: + case aria.KeyCode.ESC: + case aria.KeyCode.RETURN: + evt.preventDefault(); + return; + default: + this.updateResults(false); + } + + if (this.hasInlineAutocomplete) { + switch (key) { + case aria.KeyCode.BACKSPACE: + return; + default: + this.autocompleteItem(); + } + } +}; + +aria.ListboxCombobox.prototype.updateResults = function (shouldShowAll) { + var searchString = this.input.value; + var results = this.searchFn(searchString); + + this.hideListbox(); + + if (!shouldShowAll && !searchString) { + results = []; + } + + if (results.length) { + for (var i = 0; i < results.length; i++) { + var resultItem = document.createElement('li'); + resultItem.className = 'result'; + resultItem.setAttribute('role', 'option'); + resultItem.setAttribute('id', 'result-item-' + i); + resultItem.innerText = results[i]; + if (this.shouldAutoSelect && i === 0) { + resultItem.setAttribute('aria-selected', 'true'); + aria.Utils.addClass(resultItem, 'focused'); + this.activeIndex = 0; + } + this.listbox.appendChild(resultItem); + } + aria.Utils.removeClass(this.listbox, 'hidden'); + this.combobox.setAttribute('aria-expanded', 'true'); + this.resultsCount = results.length; + this.shown = true; + this.onShow(); + } +}; + +aria.ListboxCombobox.prototype.setActiveItem = function (evt) { + var key = evt.which || evt.keyCode; + var activeIndex = this.activeIndex; + + if (key === aria.KeyCode.ESC) { + this.hideListbox(); + setTimeout((function () { + // On Firefox, input does not get cleared here unless wrapped in + // a setTimeout + this.input.value = ''; + }).bind(this), 1); + return; + } + + if (this.resultsCount < 1) { + if (this.hasInlineAutocomplete && (key === aria.KeyCode.DOWN || key === aria.KeyCode.UP)) { + this.updateResults(true); + } + else { + return; + } + } + + var prevActive = this.getItemAt(activeIndex); + var activeItem; + + switch (key) { + case aria.KeyCode.UP: + if (activeIndex <= 0) { + activeIndex = this.resultsCount - 1; + } + else { + activeIndex--; + } + break; + case aria.KeyCode.DOWN: + if (activeIndex === -1 || activeIndex >= this.resultsCount - 1) { + activeIndex = 0; + } + else { + activeIndex++; + } + break; + case aria.KeyCode.RETURN: + activeItem = this.getItemAt(activeIndex); + this.selectItem(activeItem); + return; + case aria.KeyCode.TAB: + this.hideListbox(); + return; + default: + return; + } + + evt.preventDefault(); + + activeItem = this.getItemAt(activeIndex); + this.activeIndex = activeIndex; + + if (prevActive) { + aria.Utils.removeClass(prevActive, 'focused'); + prevActive.setAttribute('aria-selected', 'false'); + } + + if (activeItem) { + this.input.setAttribute( + 'aria-activedescendant', + 'result-item-' + activeIndex + ); + aria.Utils.addClass(activeItem, 'focused'); + activeItem.setAttribute('aria-selected', 'true'); + if (this.hasInlineAutocomplete) { + this.input.value = activeItem.innerText; + } + } + else { + this.input.setAttribute( + 'aria-activedescendant', + '' + ); + } +}; + +aria.ListboxCombobox.prototype.getItemAt = function (index) { + return document.getElementById('result-item-' + index); +}; + +aria.ListboxCombobox.prototype.clickItem = function (evt) { + if (evt.target && evt.target.nodeName == 'LI') { + this.selectItem(evt.target); + } +}; + +aria.ListboxCombobox.prototype.selectItem = function (item) { + if (item) { + this.input.value = item.innerText; + this.hideListbox(); + } +}; + +aria.ListboxCombobox.prototype.checkShow = function (evt) { + this.updateResults(false); +}; + +aria.ListboxCombobox.prototype.checkHide = function (evt) { + if (evt.target === this.input || this.combobox.contains(evt.target)) { + return; + } + this.hideListbox(); +}; + +aria.ListboxCombobox.prototype.hideListbox = function () { + this.shown = false; + this.activeIndex = -1; + this.listbox.innerHTML = null; + aria.Utils.addClass(this.listbox, 'hidden'); + this.combobox.setAttribute('aria-expanded', 'false'); + this.resultsCount = 0; + this.input.setAttribute( + 'aria-activedescendant', + '' + ); + this.onHide(); +}; + +aria.ListboxCombobox.prototype.autocompleteItem = function () { + var autocompletedItem = this.listbox.querySelector('.focused'); + var inputText = this.input.value; + + if (!autocompletedItem || !inputText) { + return; + } + + var autocomplete = autocompletedItem.innerText; + if (inputText !== autocomplete) { + this.input.value = autocomplete; + this.input.setSelectionRange(inputText.length, autocomplete.length); + } +}; diff --git a/examples/combobox/aria1.1pattern/listbox-combo.html b/examples/combobox/aria1.1pattern/listbox-combo.html index 1c3e4ef62b..1b01c7ddb5 100644 --- a/examples/combobox/aria1.1pattern/listbox-combo.html +++ b/examples/combobox/aria1.1pattern/listbox-combo.html @@ -2,7 +2,7 @@ -Example of ARIA 1.1 Combobox with Listbox Popup | WAI-ARIA Authoring Practices 1.1 +Examples of ARIA 1.1 Combobox with Listbox Popup | WAI-ARIA Authoring Practices 1.1 @@ -10,24 +10,24 @@ + - + +
      -

      Example of Combobox with Listbox Popup

      +

      Examples of ARIA 1.1 Combobox with Listbox Popup

      NOTE: This page is work in progress; it is not ready for review. This work is tracked by issue 100.

      - - Replace this paragraph with an overview of the example that is something like the following. The - below example section demonstrates a simple checkbox that implements the - design pattern for checkbox. - This example uses ... summarize salient techniques ) + The following examples demonstrate different types of autocomplete behavior + using the ARIA 1.1 form of the + combobox design pattern.

      Similar examples include:

        @@ -36,29 +36,100 @@

        Example of Combobox with Listbox Popup

      -

      Example

      - - +

      Examples

      +

      Example of list autocomplete with manual selection

      +
      - -

      This is the place where the reader will experience the functioning example.

      -
        -
      • The HTML in this section along with the javascript and CSS it uses demonstrate - the design pattern.
        • -
      • - When developing an example implementation for this guide, please follow the - APG example coding guidelines - . -
        • - -
      + +
      + + +
      +
      + +

      Example of list autocomplete with automatic selection

      + +
      + +
      + + +
      +
      + + +

      Example of list with inline autocomplete

      + +
      + +
      + + +
      - +
      @@ -189,8 +260,7 @@

      HTML Source Code