From eed124a72cc94bf0e2d39b6d33af563966f23ee1 Mon Sep 17 00:00:00 2001 From: Jon Gunderson Date: Mon, 18 Sep 2023 19:43:08 -0500 Subject: [PATCH] Listbox Examples: Update scrolling of listbox item with focus into view when page is magnified (pull #2622) In the listbox examples, fixes #2545 with the following changes: * Updated code to scroll the element referenced by @aria-activedescendant@ into view when view is magnified * Updated accessibility features documentation in support of this change. While fixing this bug, the following additional changes were also made to improve code quality and implement the latest APG code guide practices: * Use `event.key` instead of `event.keyCode` for identifying keyboard commands. * Use `class` constructors instead of `prototype`. * Changed `mousedown` event to `pointerdown` event to support mobile devices. * Provide high contrast focus ring around option referenced by `aria-activedescendant`. * Fix bugs in keyboard support for the toolbar * Update documentation to improve consistency with current editorial practices --------- Co-authored-by: Matt King Co-authored-by: Mike Pennisi Co-authored-by: Aleena <55119766+aleenaloves@users.noreply.github.com> Co-authored-by: Howard Edwards --- content/index/index.html | 3 + .../patterns/listbox/examples/css/listbox.css | 29 +- .../examples/js/listbox-collapsible.js | 124 +- .../examples/js/listbox-rearrangeable.js | 10 +- .../listbox/examples/js/listbox-scrollable.js | 10 +- .../patterns/listbox/examples/js/listbox.js | 1106 ++++++++--------- .../patterns/listbox/examples/js/toolbar.js | 190 +-- .../listbox/examples/listbox-collapsible.html | 66 +- .../listbox/examples/listbox-grouped.html | 142 ++- .../examples/listbox-rearrangeable.html | 319 +++-- .../listbox/examples/listbox-scrollable.html | 211 +++- test/tests/listbox_grouped.js | 14 + test/tests/listbox_rearrangeable.js | 12 + test/tests/listbox_scrollable.js | 10 + 14 files changed, 1304 insertions(+), 942 deletions(-) diff --git a/content/index/index.html b/content/index/index.html index e9f3c4d46c..08a437bcbc 100644 --- a/content/index/index.html +++ b/content/index/index.html @@ -620,6 +620,9 @@

Examples By Properties and States

  • Button (IDL Version)
    • +
  • Listbox with Grouped Options
    • +
  • Listboxes with Rearrangeable Options
    • +
  • Scrollable Listbox
  • Editor Menubar (HC)
  • Horizontal Multi-Thumb Slider (HC)
  • Color Viewer Slider (HC)
    • diff --git a/content/patterns/listbox/examples/css/listbox.css b/content/patterns/listbox/examples/css/listbox.css index 7fc920c580..5ecb8d129d 100644 --- a/content/patterns/listbox/examples/css/listbox.css +++ b/content/patterns/listbox/examples/css/listbox.css @@ -44,15 +44,30 @@ [role="option"] { position: relative; display: block; - padding: 0 1em 0 1.5em; + margin: 2px; + padding: 2px 1em 2px 1.5em; line-height: 1.8em; + cursor: pointer; } -[role="option"].focused { +[role="listbox"]:focus [role="option"].focused { background: #bde4ff; } -[role="option"][aria-selected="true"]::before { +[role="listbox"]:focus [role="option"].focused, +[role="option"]:hover { + outline: 2px solid currentcolor; +} + +.move-right-btn span.checkmark::after { + content: " →"; +} + +.move-left-btn span.checkmark::before { + content: "← "; +} + +[role="option"][aria-selected="true"] span.checkmark::before { position: absolute; left: 0.5em; content: "✓"; @@ -120,14 +135,6 @@ button[aria-disabled="true"] { opacity: 0.5; } -.move-right-btn::after { - content: " →"; -} - -.move-left-btn::before { - content: "← "; -} - .annotate { color: #366ed4; font-style: italic; diff --git a/content/patterns/listbox/examples/js/listbox-collapsible.js b/content/patterns/listbox/examples/js/listbox-collapsible.js index 4c5733de93..4beaae9f5c 100644 --- a/content/patterns/listbox/examples/js/listbox-collapsible.js +++ b/content/patterns/listbox/examples/js/listbox-collapsible.js @@ -1,4 +1,18 @@ +/* + * This content is licensed according to the W3C Software License at + * https://www.w3.org/Consortium/Legal/2015/copyright-software-and-document + */ + 'use strict'; + +/** + * @namespace aria + * @description + * The aria namespace is used to support sharing class definitions between example files + * without causing eslint errors for undefined classes + */ +var aria = aria || {}; + /** * ARIA Collapsible Dropdown Listbox Example * @@ -7,70 +21,66 @@ */ window.addEventListener('load', function () { - var button = document.getElementById('exp_button'); - var exListbox = new aria.Listbox(document.getElementById('exp_elem_list')); - new aria.ListboxButton(button, exListbox); + const button = document.getElementById('exp_button'); + const exListbox = new aria.Listbox(document.getElementById('exp_elem_list')); + new ListboxButton(button, exListbox); }); -var aria = aria || {}; - -aria.ListboxButton = function (button, listbox) { - this.button = button; - this.listbox = listbox; - this.registerEvents(); -}; - -aria.ListboxButton.prototype.registerEvents = function () { - this.button.addEventListener('click', this.showListbox.bind(this)); - this.button.addEventListener('keyup', this.checkShow.bind(this)); - this.listbox.listboxNode.addEventListener( - 'blur', - this.hideListbox.bind(this) - ); - this.listbox.listboxNode.addEventListener( - 'keydown', - this.checkHide.bind(this) - ); - this.listbox.setHandleFocusChange(this.onFocusChange.bind(this)); -}; - -aria.ListboxButton.prototype.checkShow = function (evt) { - var key = evt.which || evt.keyCode; +class ListboxButton { + constructor(button, listbox) { + this.button = button; + this.listbox = listbox; + this.registerEvents(); + } - switch (key) { - case aria.KeyCode.UP: - case aria.KeyCode.DOWN: - evt.preventDefault(); - this.showListbox(); - this.listbox.checkKeyPress(evt); - break; + registerEvents() { + this.button.addEventListener('click', this.showListbox.bind(this)); + this.button.addEventListener('keyup', this.checkShow.bind(this)); + this.listbox.listboxNode.addEventListener( + 'blur', + this.hideListbox.bind(this) + ); + this.listbox.listboxNode.addEventListener( + 'keydown', + this.checkHide.bind(this) + ); + this.listbox.setHandleFocusChange(this.onFocusChange.bind(this)); } -}; -aria.ListboxButton.prototype.checkHide = function (evt) { - var key = evt.which || evt.keyCode; + checkShow(evt) { + switch (evt.key) { + case 'ArrowUp': + case 'ArrowDown': + evt.preventDefault(); + this.showListbox(); + this.listbox.checkKeyPress(evt); + break; + } + } - switch (key) { - case aria.KeyCode.RETURN: - case aria.KeyCode.ESC: - evt.preventDefault(); - this.hideListbox(); - this.button.focus(); - break; + checkHide(evt) { + switch (evt.key) { + case 'Enter': + case 'Escape': + evt.preventDefault(); + this.hideListbox(); + this.button.focus(); + break; + } } -}; -aria.ListboxButton.prototype.showListbox = function () { - aria.Utils.removeClass(this.listbox.listboxNode, 'hidden'); - this.button.setAttribute('aria-expanded', 'true'); - this.listbox.listboxNode.focus(); -}; + showListbox() { + this.listbox.listboxNode.classList.remove('hidden'); + this.button.setAttribute('aria-expanded', 'true'); + this.listbox.listboxNode.focus(); + } -aria.ListboxButton.prototype.hideListbox = function () { - aria.Utils.addClass(this.listbox.listboxNode, 'hidden'); - this.button.removeAttribute('aria-expanded'); -}; + hideListbox() { + this.listbox.listboxNode.classList.add('hidden'); + this.button.removeAttribute('aria-expanded'); + } -aria.ListboxButton.prototype.onFocusChange = function (focusedItem) { - this.button.innerText = focusedItem.innerText; -}; + onFocusChange(focusedItem) { + this.button.innerText = focusedItem.innerText; + } +} diff --git a/content/patterns/listbox/examples/js/listbox-rearrangeable.js b/content/patterns/listbox/examples/js/listbox-rearrangeable.js index 561b5d519a..b5ba8ee809 100644 --- a/content/patterns/listbox/examples/js/listbox-rearrangeable.js +++ b/content/patterns/listbox/examples/js/listbox-rearrangeable.js @@ -3,10 +3,16 @@ * https://www.w3.org/Consortium/Legal/2015/copyright-software-and-document */ -/* global aria */ - 'use strict'; +/** + * @namespace aria + * @description + * The aria namespace is used to support sharing class definitions between example files + * without causing eslint errors for undefined classes + */ +var aria = aria || {}; + /** * ARIA Listbox Examples * diff --git a/content/patterns/listbox/examples/js/listbox-scrollable.js b/content/patterns/listbox/examples/js/listbox-scrollable.js index 4020406040..fe7b2658f7 100644 --- a/content/patterns/listbox/examples/js/listbox-scrollable.js +++ b/content/patterns/listbox/examples/js/listbox-scrollable.js @@ -3,10 +3,16 @@ * https://www.w3.org/Consortium/Legal/2015/copyright-software-and-document */ -/* global aria */ - 'use strict'; +/** + * @namespace aria + * @description + * The aria namespace is used to support sharing class definitions between example files + * without causing eslint errors for undefined classes + */ +var aria = aria || {}; + /** * ARIA Scrollable Listbox Example * diff --git a/content/patterns/listbox/examples/js/listbox.js b/content/patterns/listbox/examples/js/listbox.js index 8a24176bb5..632063f25c 100644 --- a/content/patterns/listbox/examples/js/listbox.js +++ b/content/patterns/listbox/examples/js/listbox.js @@ -7,6 +7,9 @@ /** * @namespace aria + * @description + * The aria namespace is used to support sharing class definitions between example files + * without causing eslint errors for undefined classes */ var aria = aria || {}; @@ -17,681 +20,668 @@ var aria = aria || {}; * @param listboxNode * The DOM node pointing to the listbox */ -aria.Listbox = function (listboxNode) { - this.listboxNode = listboxNode; - this.activeDescendant = this.listboxNode.getAttribute( - 'aria-activedescendant' - ); - this.multiselectable = this.listboxNode.hasAttribute('aria-multiselectable'); - this.moveUpDownEnabled = false; - this.siblingList = null; - this.startRangeIndex = 0; - this.upButton = null; - this.downButton = null; - this.moveButton = null; - this.keysSoFar = ''; - this.handleFocusChange = function () {}; - this.handleItemChange = function () {}; - this.registerEvents(); -}; -/** - * @description - * Register events for the listbox interactions - */ -aria.Listbox.prototype.registerEvents = function () { - this.listboxNode.addEventListener('focus', this.setupFocus.bind(this)); - this.listboxNode.addEventListener('keydown', this.checkKeyPress.bind(this)); - this.listboxNode.addEventListener('click', this.checkClickItem.bind(this)); - - if (this.multiselectable) { - this.listboxNode.addEventListener( - 'mousedown', - this.checkMouseDown.bind(this) +aria.Listbox = class Listbox { + constructor(listboxNode) { + this.listboxNode = listboxNode; + this.activeDescendant = this.listboxNode.getAttribute( + 'aria-activedescendant' + ); + this.multiselectable = this.listboxNode.hasAttribute( + 'aria-multiselectable' ); + this.moveUpDownEnabled = false; + this.siblingList = null; + this.startRangeIndex = 0; + this.upButton = null; + this.downButton = null; + this.moveButton = null; + this.keysSoFar = ''; + this.handleFocusChange = function () {}; + this.handleItemChange = function () {}; + this.registerEvents(); + } + + registerEvents() { + this.listboxNode.addEventListener('focus', this.setupFocus.bind(this)); + this.listboxNode.addEventListener('keydown', this.checkKeyPress.bind(this)); + this.listboxNode.addEventListener('click', this.checkClickItem.bind(this)); + + if (this.multiselectable) { + this.listboxNode.addEventListener( + 'mousedown', + this.checkMouseDown.bind(this) + ); + } } -}; -/** - * @description - * If there is no activeDescendant, focus on the first option - */ -aria.Listbox.prototype.setupFocus = function () { - if (this.activeDescendant) { - return; + setupFocus() { + if (this.activeDescendant) { + const listitem = document.getElementById(this.activeDescendant); + listitem.scrollIntoView({ block: 'nearest', inline: 'nearest' }); + } } -}; -/** - * @description - * Focus on the first option - */ -aria.Listbox.prototype.focusFirstItem = function () { - var firstItem = this.listboxNode.querySelector('[role="option"]'); + focusFirstItem() { + var firstItem = this.listboxNode.querySelector('[role="option"]'); - if (firstItem) { - this.focusItem(firstItem); + if (firstItem) { + this.focusItem(firstItem); + } } -}; -/** - * @description - * Focus on the last option - */ -aria.Listbox.prototype.focusLastItem = function () { - var itemList = this.listboxNode.querySelectorAll('[role="option"]'); + focusLastItem() { + const itemList = this.listboxNode.querySelectorAll('[role="option"]'); - if (itemList.length) { - this.focusItem(itemList[itemList.length - 1]); + if (itemList.length) { + this.focusItem(itemList[itemList.length - 1]); + } } -}; -/** - * @description - * Handle various keyboard controls; UP/DOWN will shift focus; SPACE selects - * an item. - * @param evt - * The keydown event object - */ -aria.Listbox.prototype.checkKeyPress = function (evt) { - var key = evt.which || evt.keyCode; - var lastActiveId = this.activeDescendant; - var allOptions = this.listboxNode.querySelectorAll('[role="option"]'); - var currentItem = - document.getElementById(this.activeDescendant) || allOptions[0]; - var nextItem = currentItem; - - if (!currentItem) { - return; - } - - switch (key) { - case aria.KeyCode.PAGE_UP: - case aria.KeyCode.PAGE_DOWN: - if (this.moveUpDownEnabled) { - evt.preventDefault(); + checkKeyPress(evt) { + const lastActiveId = this.activeDescendant; + const allOptions = this.listboxNode.querySelectorAll('[role="option"]'); + const currentItem = + document.getElementById(this.activeDescendant) || allOptions[0]; + let nextItem = currentItem; - if (key === aria.KeyCode.PAGE_UP) { - this.moveUpItems(); - } else { - this.moveDownItems(); + if (!currentItem) { + return; + } + + switch (evt.key) { + case 'PageUp': + case 'PageDown': + evt.preventDefault(); + if (this.moveUpDownEnabled) { + if (evt.key === 'PageUp') { + this.moveUpItems(); + } else { + this.moveDownItems(); + } } - } - break; - case aria.KeyCode.UP: - case aria.KeyCode.DOWN: - if (!this.activeDescendant) { - // focus first option if no option was previously focused, and perform no other actions - this.focusItem(currentItem); break; - } - - if (this.moveUpDownEnabled && evt.altKey) { + case 'ArrowUp': + case 'ArrowDown': evt.preventDefault(); - if (key === aria.KeyCode.UP) { - this.moveUpItems(); + if (!this.activeDescendant) { + // focus first option if no option was previously focused, and perform no other actions + this.focusItem(currentItem); + break; + } + + if (this.moveUpDownEnabled && evt.altKey) { + evt.preventDefault(); + if (evt.key === 'ArrowUp') { + this.moveUpItems(); + } else { + this.moveDownItems(); + } + this.updateScroll(); + return; + } + + if (evt.key === 'ArrowUp') { + nextItem = this.findPreviousOption(currentItem); } else { - this.moveDownItems(); + nextItem = this.findNextOption(currentItem); } - return; - } - if (key === aria.KeyCode.UP) { - nextItem = this.findPreviousOption(currentItem); - } else { - nextItem = this.findNextOption(currentItem); - } + if (nextItem && this.multiselectable && event.shiftKey) { + this.selectRange(this.startRangeIndex, nextItem); + } - if (nextItem && this.multiselectable && event.shiftKey) { - this.selectRange(this.startRangeIndex, nextItem); - } + if (nextItem) { + this.focusItem(nextItem); + } - if (nextItem) { - this.focusItem(nextItem); + break; + + case 'Home': evt.preventDefault(); - } + this.focusFirstItem(); - break; - case aria.KeyCode.HOME: - evt.preventDefault(); - this.focusFirstItem(); + if (this.multiselectable && evt.shiftKey && evt.ctrlKey) { + this.selectRange(this.startRangeIndex, 0); + } + break; - if (this.multiselectable && evt.shiftKey && evt.ctrlKey) { - this.selectRange(this.startRangeIndex, 0); - } - break; - case aria.KeyCode.END: - evt.preventDefault(); - this.focusLastItem(); + case 'End': + evt.preventDefault(); + this.focusLastItem(); - if (this.multiselectable && evt.shiftKey && evt.ctrlKey) { - this.selectRange(this.startRangeIndex, allOptions.length - 1); - } - break; - case aria.KeyCode.SHIFT: - this.startRangeIndex = this.getElementIndex(currentItem, allOptions); - break; - case aria.KeyCode.SPACE: - evt.preventDefault(); - this.toggleSelectItem(nextItem); - break; - case aria.KeyCode.BACKSPACE: - case aria.KeyCode.DELETE: - case aria.KeyCode.RETURN: - if (!this.moveButton) { - return; - } + if (this.multiselectable && evt.shiftKey && evt.ctrlKey) { + this.selectRange(this.startRangeIndex, allOptions.length - 1); + } + break; - var keyshortcuts = this.moveButton.getAttribute('aria-keyshortcuts'); - if (key === aria.KeyCode.RETURN && keyshortcuts.indexOf('Enter') === -1) { - return; - } - if ( - (key === aria.KeyCode.BACKSPACE || key === aria.KeyCode.DELETE) && - keyshortcuts.indexOf('Delete') === -1 - ) { - return; - } + case 'Shift': + this.startRangeIndex = this.getElementIndex(currentItem, allOptions); + break; - evt.preventDefault(); + case ' ': + evt.preventDefault(); + this.toggleSelectItem(nextItem); + break; - var nextUnselected = nextItem.nextElementSibling; - while (nextUnselected) { - if (nextUnselected.getAttribute('aria-selected') != 'true') { - break; + case 'Backspace': + case 'Delete': + case 'Enter': + if (!this.moveButton) { + return; } - nextUnselected = nextUnselected.nextElementSibling; - } - if (!nextUnselected) { - nextUnselected = nextItem.previousElementSibling; + + var keyshortcuts = this.moveButton.getAttribute('aria-keyshortcuts'); + if (evt.key === 'Enter' && keyshortcuts.indexOf('Enter') === -1) { + return; + } + if ( + (evt.key === 'Backspace' || evt.key === 'Delete') && + keyshortcuts.indexOf('Delete') === -1 + ) { + return; + } + + evt.preventDefault(); + + var nextUnselected = nextItem.nextElementSibling; while (nextUnselected) { if (nextUnselected.getAttribute('aria-selected') != 'true') { break; } - nextUnselected = nextUnselected.previousElementSibling; + nextUnselected = nextUnselected.nextElementSibling; + } + if (!nextUnselected) { + nextUnselected = nextItem.previousElementSibling; + while (nextUnselected) { + if (nextUnselected.getAttribute('aria-selected') != 'true') { + break; + } + nextUnselected = nextUnselected.previousElementSibling; + } } - } - this.moveItems(); + this.moveItems(); - if (!this.activeDescendant && nextUnselected) { - this.focusItem(nextUnselected); - } - break; - case 65: - // handle control + A - if (this.multiselectable && (evt.ctrlKey || evt.metaKey)) { - evt.preventDefault(); - this.selectRange(0, allOptions.length - 1); + if (!this.activeDescendant && nextUnselected) { + this.focusItem(nextUnselected); + } break; - } - // fall through - default: - var itemToFocus = this.findItemToFocus(key); - if (itemToFocus) { - this.focusItem(itemToFocus); - } - break; - } - if (this.activeDescendant !== lastActiveId) { - this.updateScroll(); + case 'A': + case 'a': + // handle control + A + if (evt.ctrlKey || evt.metaKey) { + if (this.multiselectable) { + this.selectRange(0, allOptions.length - 1); + } + evt.preventDefault(); + break; + } + // fall through + default: + if (evt.key.length === 1) { + const itemToFocus = this.findItemToFocus(evt.key.toLowerCase()); + if (itemToFocus) { + this.focusItem(itemToFocus); + } + } + break; + } + + if (this.activeDescendant !== lastActiveId) { + this.updateScroll(); + } } -}; -aria.Listbox.prototype.findItemToFocus = function (key) { - var itemList = this.listboxNode.querySelectorAll('[role="option"]'); - var character = String.fromCharCode(key); - var searchIndex = 0; + findItemToFocus(character) { + const itemList = this.listboxNode.querySelectorAll('[role="option"]'); + let searchIndex = 0; - if (!this.keysSoFar) { - for (var i = 0; i < itemList.length; i++) { - if (itemList[i].getAttribute('id') == this.activeDescendant) { - searchIndex = i; + if (!this.keysSoFar) { + for (let i = 0; i < itemList.length; i++) { + if (itemList[i].getAttribute('id') == this.activeDescendant) { + searchIndex = i; + } } } - } - this.keysSoFar += character; - this.clearKeysSoFarAfterDelay(); - var nextMatch = this.findMatchInRange( - itemList, - searchIndex + 1, - itemList.length - ); - if (!nextMatch) { - nextMatch = this.findMatchInRange(itemList, 0, searchIndex); - } - return nextMatch; -}; + this.keysSoFar += character; + this.clearKeysSoFarAfterDelay(); -/* Return the index of the passed element within the passed array, or null if not found */ -aria.Listbox.prototype.getElementIndex = function (option, options) { - var allOptions = Array.prototype.slice.call(options); // convert to array - var optionIndex = allOptions.indexOf(option); + let nextMatch = this.findMatchInRange( + itemList, + searchIndex + 1, + itemList.length + ); - return typeof optionIndex === 'number' ? optionIndex : null; -}; + if (!nextMatch) { + nextMatch = this.findMatchInRange(itemList, 0, searchIndex); + } + return nextMatch; + } -/* Return the next listbox option, if it exists; otherwise, returns null */ -aria.Listbox.prototype.findNextOption = function (currentOption) { - var allOptions = Array.prototype.slice.call( - this.listboxNode.querySelectorAll('[role="option"]') - ); // get options array - var currentOptionIndex = allOptions.indexOf(currentOption); - var nextOption = null; + /* Return the index of the passed element within the passed array, or null if not found */ + getElementIndex(option, options) { + const allOptions = Array.prototype.slice.call(options); // convert to array + const optionIndex = allOptions.indexOf(option); - if (currentOptionIndex > -1 && currentOptionIndex < allOptions.length - 1) { - nextOption = allOptions[currentOptionIndex + 1]; + return typeof optionIndex === 'number' ? optionIndex : null; } - return nextOption; -}; + /* Return the next listbox option, if it exists; otherwise, returns null */ + findNextOption(currentOption) { + const allOptions = Array.prototype.slice.call( + this.listboxNode.querySelectorAll('[role="option"]') + ); // get options array + const currentOptionIndex = allOptions.indexOf(currentOption); + let nextOption = null; -/* Return the previous listbox option, if it exists; otherwise, returns null */ -aria.Listbox.prototype.findPreviousOption = function (currentOption) { - var allOptions = Array.prototype.slice.call( - this.listboxNode.querySelectorAll('[role="option"]') - ); // get options array - var currentOptionIndex = allOptions.indexOf(currentOption); - var previousOption = null; + if (currentOptionIndex > -1 && currentOptionIndex < allOptions.length - 1) { + nextOption = allOptions[currentOptionIndex + 1]; + } - if (currentOptionIndex > -1 && currentOptionIndex > 0) { - previousOption = allOptions[currentOptionIndex - 1]; + return nextOption; } - return previousOption; -}; + /* Return the previous listbox option, if it exists; otherwise, returns null */ + findPreviousOption(currentOption) { + const allOptions = Array.prototype.slice.call( + this.listboxNode.querySelectorAll('[role="option"]') + ); // get options array + const currentOptionIndex = allOptions.indexOf(currentOption); + let previousOption = null; -aria.Listbox.prototype.clearKeysSoFarAfterDelay = function () { - if (this.keyClear) { - clearTimeout(this.keyClear); - this.keyClear = null; - } - this.keyClear = setTimeout( - function () { - this.keysSoFar = ''; - this.keyClear = null; - }.bind(this), - 500 - ); -}; - -aria.Listbox.prototype.findMatchInRange = function ( - list, - startIndex, - endIndex -) { - // Find the first item starting with the keysSoFar substring, searching in - // the specified range of items - for (var n = startIndex; n < endIndex; n++) { - var label = list[n].innerText; - if (label && label.toUpperCase().indexOf(this.keysSoFar) === 0) { - return list[n]; + if (currentOptionIndex > -1 && currentOptionIndex > 0) { + previousOption = allOptions[currentOptionIndex - 1]; } - } - return null; -}; -/** - * @description - * Check if an item is clicked on. If so, focus on it and select it. - * @param evt - * The click event object - */ -aria.Listbox.prototype.checkClickItem = function (evt) { - if (evt.target.getAttribute('role') !== 'option') { - return; + return previousOption; } - this.focusItem(evt.target); - this.toggleSelectItem(evt.target); - this.updateScroll(); - - if (this.multiselectable && evt.shiftKey) { - this.selectRange(this.startRangeIndex, evt.target); + clearKeysSoFarAfterDelay() { + if (this.keyClear) { + clearTimeout(this.keyClear); + this.keyClear = null; + } + this.keyClear = setTimeout( + function () { + this.keysSoFar = ''; + this.keyClear = null; + }.bind(this), + 500 + ); } -}; -/** - * Prevent text selection on shift + click for multi-select listboxes - * - * @param evt - */ -aria.Listbox.prototype.checkMouseDown = function (evt) { - if ( - this.multiselectable && - evt.shiftKey && - evt.target.getAttribute('role') === 'option' - ) { - evt.preventDefault(); + findMatchInRange(list, startIndex, endIndex) { + // Find the first item starting with the keysSoFar substring, searching in + // the specified range of items + for (let n = startIndex; n < endIndex; n++) { + const label = list[n].innerText; + if (label && label.toLowerCase().indexOf(this.keysSoFar) === 0) { + return list[n]; + } + } + return null; } -}; -/** - * @description - * Toggle the aria-selected value - * @param element - * The element to select - */ -aria.Listbox.prototype.toggleSelectItem = function (element) { - if (this.multiselectable) { - element.setAttribute( - 'aria-selected', - element.getAttribute('aria-selected') === 'true' ? 'false' : 'true' - ); + checkClickItem(evt) { + if (evt.target.getAttribute('role') !== 'option') { + return; + } - this.updateMoveButton(); - } -}; + this.focusItem(evt.target); + this.toggleSelectItem(evt.target); + this.updateScroll(); -/** - * @description - * Defocus the specified item - * @param element - * The element to defocus - */ -aria.Listbox.prototype.defocusItem = function (element) { - if (!element) { - return; - } - if (!this.multiselectable) { - element.removeAttribute('aria-selected'); + if (this.multiselectable && evt.shiftKey) { + this.selectRange(this.startRangeIndex, evt.target); + } } - element.classList.remove('focused'); -}; -/** - * @description - * Focus on the specified item - * @param element - * The element to focus - */ -aria.Listbox.prototype.focusItem = function (element) { - this.defocusItem(document.getElementById(this.activeDescendant)); - if (!this.multiselectable) { - element.setAttribute('aria-selected', 'true'); + /** + * Prevent text selection on shift + click for multi-select listboxes + * + * @param evt + */ + checkMouseDown(evt) { + if ( + this.multiselectable && + evt.shiftKey && + evt.target.getAttribute('role') === 'option' + ) { + evt.preventDefault(); + } } - element.classList.add('focused'); - this.listboxNode.setAttribute('aria-activedescendant', element.id); - this.activeDescendant = element.id; - if (!this.multiselectable) { - this.updateMoveButton(); + /** + * @description + * Toggle the aria-selected value + * @param element + * The element to select + */ + toggleSelectItem(element) { + if (this.multiselectable) { + element.setAttribute( + 'aria-selected', + element.getAttribute('aria-selected') === 'true' ? 'false' : 'true' + ); + + this.updateMoveButton(); + } } - this.checkUpDownButtons(); - this.handleFocusChange(element); -}; - -/** - * Helper function to check if a number is within a range; no side effects. - * - * @param index - * @param start - * @param end - * @returns {boolean} - */ -aria.Listbox.prototype.checkInRange = function (index, start, end) { - var rangeStart = start < end ? start : end; - var rangeEnd = start < end ? end : start; + /** + * @description + * Defocus the specified item + * @param element + * The element to defocus + */ + defocusItem(element) { + if (!element) { + return; + } + if (!this.multiselectable) { + element.removeAttribute('aria-selected'); + } + element.classList.remove('focused'); + } + + /** + * @description + * Focus on the specified item + * @param element + * The element to focus + */ + focusItem(element) { + this.defocusItem(document.getElementById(this.activeDescendant)); + if (!this.multiselectable) { + element.setAttribute('aria-selected', 'true'); + } + element.classList.add('focused'); + this.listboxNode.setAttribute('aria-activedescendant', element.id); + this.activeDescendant = element.id; - return index >= rangeStart && index <= rangeEnd; -}; + if (!this.multiselectable) { + this.updateMoveButton(); + } -/** - * Select a range of options - * - * @param start - * @param end - */ -aria.Listbox.prototype.selectRange = function (start, end) { - // get start/end indices - var allOptions = this.listboxNode.querySelectorAll('[role="option"]'); - var startIndex = - typeof start === 'number' ? start : this.getElementIndex(start, allOptions); - var endIndex = - typeof end === 'number' ? end : this.getElementIndex(end, allOptions); + this.checkUpDownButtons(); + this.handleFocusChange(element); + } + + /** + * Helper function to check if a number is within a range; no side effects. + * + * @param index + * @param start + * @param end + * @returns {boolean} + */ + checkInRange(index, start, end) { + const rangeStart = start < end ? start : end; + const rangeEnd = start < end ? end : start; + + return index >= rangeStart && index <= rangeEnd; + } + + /** + * Select a range of options + * + * @param start + * @param end + */ + selectRange(start, end) { + // get start/end indices + const allOptions = this.listboxNode.querySelectorAll('[role="option"]'); + const startIndex = + typeof start === 'number' + ? start + : this.getElementIndex(start, allOptions); + const endIndex = + typeof end === 'number' ? end : this.getElementIndex(end, allOptions); + + for (let index = 0; index < allOptions.length; index++) { + const selected = this.checkInRange(index, startIndex, endIndex); + allOptions[index].setAttribute('aria-selected', selected + ''); + } - for (var index = 0; index < allOptions.length; index++) { - var selected = this.checkInRange(index, startIndex, endIndex); - allOptions[index].setAttribute('aria-selected', selected + ''); + this.updateMoveButton(); } - this.updateMoveButton(); -}; - -/** - * Check for selected options and update moveButton, if applicable - */ -aria.Listbox.prototype.updateMoveButton = function () { - if (!this.moveButton) { - return; - } + /** + * Check for selected options and update moveButton, if applicable + */ + updateMoveButton() { + if (!this.moveButton) { + return; + } - if (this.listboxNode.querySelector('[aria-selected="true"]')) { - this.moveButton.setAttribute('aria-disabled', 'false'); - } else { - this.moveButton.setAttribute('aria-disabled', 'true'); + if (this.listboxNode.querySelector('[aria-selected="true"]')) { + this.moveButton.setAttribute('aria-disabled', 'false'); + } else { + this.moveButton.setAttribute('aria-disabled', 'true'); + } } -}; -/** - * Check if the selected option is in view, and scroll if not - */ -aria.Listbox.prototype.updateScroll = function () { - var selectedOption = document.getElementById(this.activeDescendant); - if ( - selectedOption && - this.listboxNode.scrollHeight > this.listboxNode.clientHeight - ) { - var scrollBottom = - this.listboxNode.clientHeight + this.listboxNode.scrollTop; - var elementBottom = selectedOption.offsetTop + selectedOption.offsetHeight; - if (elementBottom > scrollBottom) { - this.listboxNode.scrollTop = - elementBottom - this.listboxNode.clientHeight; - } else if (selectedOption.offsetTop < this.listboxNode.scrollTop) { - this.listboxNode.scrollTop = selectedOption.offsetTop; + /** + * Check if the selected option is in view, and scroll if not + */ + updateScroll() { + const selectedOption = document.getElementById(this.activeDescendant); + if (selectedOption) { + const scrollBottom = + this.listboxNode.clientHeight + this.listboxNode.scrollTop; + const elementBottom = + selectedOption.offsetTop + selectedOption.offsetHeight; + if (elementBottom > scrollBottom) { + this.listboxNode.scrollTop = + elementBottom - this.listboxNode.clientHeight; + } else if (selectedOption.offsetTop < this.listboxNode.scrollTop) { + this.listboxNode.scrollTop = selectedOption.offsetTop; + } + selectedOption.scrollIntoView({ block: 'nearest', inline: 'nearest' }); } } -}; - -/** - * @description - * Enable/disable the up/down arrows based on the activeDescendant. - */ -aria.Listbox.prototype.checkUpDownButtons = function () { - var activeElement = document.getElementById(this.activeDescendant); - if (!this.moveUpDownEnabled) { - return; - } + /** + * @description + * Enable/disable the up/down arrows based on the activeDescendant. + */ + checkUpDownButtons() { + const activeElement = document.getElementById(this.activeDescendant); - if (!activeElement) { - this.upButton.setAttribute('aria-disabled', 'true'); - this.downButton.setAttribute('aria-disabled', 'true'); - return; - } + if (!this.moveUpDownEnabled) { + return; + } - if (this.upButton) { - if (activeElement.previousElementSibling) { - this.upButton.setAttribute('aria-disabled', false); - } else { + if (!activeElement) { this.upButton.setAttribute('aria-disabled', 'true'); + this.downButton.setAttribute('aria-disabled', 'true'); + return; } - } - if (this.downButton) { - if (activeElement.nextElementSibling) { - this.downButton.setAttribute('aria-disabled', false); - } else { - this.downButton.setAttribute('aria-disabled', 'true'); + if (this.upButton) { + if (activeElement.previousElementSibling) { + this.upButton.setAttribute('aria-disabled', false); + } else { + this.upButton.setAttribute('aria-disabled', 'true'); + } } - } -}; -/** - * @description - * Add the specified items to the listbox. Assumes items are valid options. - * @param items - * An array of items to add to the listbox - */ -aria.Listbox.prototype.addItems = function (items) { - if (!items || !items.length) { - return; + if (this.downButton) { + if (activeElement.nextElementSibling) { + this.downButton.setAttribute('aria-disabled', false); + } else { + this.downButton.setAttribute('aria-disabled', 'true'); + } + } } - items.forEach( - function (item) { - this.defocusItem(item); - this.toggleSelectItem(item); - this.listboxNode.append(item); - }.bind(this) - ); + /** + * @description + * Add the specified items to the listbox. Assumes items are valid options. + * @param items + * An array of items to add to the listbox + */ + addItems(items) { + if (!items || !items.length) { + return; + } - if (!this.activeDescendant) { - this.focusItem(items[0]); - } + items.forEach( + function (item) { + this.defocusItem(item); + this.toggleSelectItem(item); + this.listboxNode.append(item); + }.bind(this) + ); - this.handleItemChange('added', items); -}; + if (!this.activeDescendant) { + this.focusItem(items[0]); + } -/** - * @description - * Remove all of the selected items from the listbox; Removes the focused items - * in a single select listbox and the items with aria-selected in a multi - * select listbox. - * @returns {Array} - * An array of items that were removed from the listbox - */ -aria.Listbox.prototype.deleteItems = function () { - var itemsToDelete; + this.handleItemChange('added', items); + } + + /** + * @description + * Remove all of the selected items from the listbox; Removes the focused items + * in a single select listbox and the items with aria-selected in a multi + * select listbox. + * @returns {Array} + * An array of items that were removed from the listbox + */ + deleteItems() { + let itemsToDelete; + + if (this.multiselectable) { + itemsToDelete = this.listboxNode.querySelectorAll( + '[aria-selected="true"]' + ); + } else if (this.activeDescendant) { + itemsToDelete = [document.getElementById(this.activeDescendant)]; + } - if (this.multiselectable) { - itemsToDelete = this.listboxNode.querySelectorAll('[aria-selected="true"]'); - } else if (this.activeDescendant) { - itemsToDelete = [document.getElementById(this.activeDescendant)]; - } + if (!itemsToDelete || !itemsToDelete.length) { + return []; + } - if (!itemsToDelete || !itemsToDelete.length) { - return []; - } + itemsToDelete.forEach( + function (item) { + item.remove(); - itemsToDelete.forEach( - function (item) { - item.remove(); + if (item.id === this.activeDescendant) { + this.clearActiveDescendant(); + } + }.bind(this) + ); - if (item.id === this.activeDescendant) { - this.clearActiveDescendant(); - } - }.bind(this) - ); + this.handleItemChange('removed', itemsToDelete); - this.handleItemChange('removed', itemsToDelete); + return itemsToDelete; + } - return itemsToDelete; -}; + clearActiveDescendant() { + this.activeDescendant = null; + this.listboxNode.setAttribute('aria-activedescendant', null); -aria.Listbox.prototype.clearActiveDescendant = function () { - this.activeDescendant = null; - this.listboxNode.setAttribute('aria-activedescendant', null); + this.updateMoveButton(); + this.checkUpDownButtons(); + } - this.updateMoveButton(); - this.checkUpDownButtons(); -}; + /** + * @description + * Shifts the currently focused item up on the list. No shifting occurs if the + * item is already at the top of the list. + */ + moveUpItems() { + if (!this.activeDescendant) { + return; + } -/** - * @description - * Shifts the currently focused item up on the list. No shifting occurs if the - * item is already at the top of the list. - */ -aria.Listbox.prototype.moveUpItems = function () { - if (!this.activeDescendant) { - return; - } + const currentItem = document.getElementById(this.activeDescendant); + const previousItem = currentItem.previousElementSibling; - var currentItem = document.getElementById(this.activeDescendant); - var previousItem = currentItem.previousElementSibling; + if (previousItem) { + this.listboxNode.insertBefore(currentItem, previousItem); + this.handleItemChange('moved_up', [currentItem]); + } - if (previousItem) { - this.listboxNode.insertBefore(currentItem, previousItem); - this.handleItemChange('moved_up', [currentItem]); + this.checkUpDownButtons(); } - this.checkUpDownButtons(); -}; + /** + * @description + * Shifts the currently focused item down on the list. No shifting occurs if + * the item is already at the end of the list. + */ + moveDownItems() { + if (!this.activeDescendant) { + return; + } -/** - * @description - * Shifts the currently focused item down on the list. No shifting occurs if - * the item is already at the end of the list. - */ -aria.Listbox.prototype.moveDownItems = function () { - if (!this.activeDescendant) { - return; - } + var currentItem = document.getElementById(this.activeDescendant); + var nextItem = currentItem.nextElementSibling; - var currentItem = document.getElementById(this.activeDescendant); - var nextItem = currentItem.nextElementSibling; + if (nextItem) { + this.listboxNode.insertBefore(nextItem, currentItem); + this.handleItemChange('moved_down', [currentItem]); + } - if (nextItem) { - this.listboxNode.insertBefore(nextItem, currentItem); - this.handleItemChange('moved_down', [currentItem]); + this.checkUpDownButtons(); } - this.checkUpDownButtons(); -}; + /** + * @description + * Delete the currently selected items and add them to the sibling list. + */ + moveItems() { + if (!this.siblingList) { + return; + } -/** - * @description - * Delete the currently selected items and add them to the sibling list. - */ -aria.Listbox.prototype.moveItems = function () { - if (!this.siblingList) { - return; + var itemsToMove = this.deleteItems(); + this.siblingList.addItems(itemsToMove); } - var itemsToMove = this.deleteItems(); - this.siblingList.addItems(itemsToMove); -}; - -/** - * @description - * Enable Up/Down controls to shift items up and down. - * @param upButton - * Up button to trigger up shift - * @param downButton - * Down button to trigger down shift - */ -aria.Listbox.prototype.enableMoveUpDown = function (upButton, downButton) { - this.moveUpDownEnabled = true; - this.upButton = upButton; - this.downButton = downButton; - upButton.addEventListener('click', this.moveUpItems.bind(this)); - downButton.addEventListener('click', this.moveDownItems.bind(this)); -}; + /** + * @description + * Enable Up/Down controls to shift items up and down. + * @param upButton + * Up button to trigger up shift + * @param downButton + * Down button to trigger down shift + */ + enableMoveUpDown(upButton, downButton) { + this.moveUpDownEnabled = true; + this.upButton = upButton; + this.downButton = downButton; + upButton.addEventListener('click', this.moveUpItems.bind(this)); + downButton.addEventListener('click', this.moveDownItems.bind(this)); + } -/** - * @description - * Enable Move controls. Moving removes selected items from the current - * list and adds them to the sibling list. - * @param button - * Move button to trigger delete - * @param siblingList - * Listbox to move items to - */ -aria.Listbox.prototype.setupMove = function (button, siblingList) { - this.siblingList = siblingList; - this.moveButton = button; - button.addEventListener('click', this.moveItems.bind(this)); -}; + /** + * @description + * Enable Move controls. Moving removes selected items from the current + * list and adds them to the sibling list. + * @param button + * Move button to trigger delete + * @param siblingList + * Listbox to move items to + */ + setupMove(button, siblingList) { + this.siblingList = siblingList; + this.moveButton = button; + button.addEventListener('click', this.moveItems.bind(this)); + } -aria.Listbox.prototype.setHandleItemChange = function (handlerFn) { - this.handleItemChange = handlerFn; -}; + setHandleItemChange(handlerFn) { + this.handleItemChange = handlerFn; + } -aria.Listbox.prototype.setHandleFocusChange = function (focusChangeHandler) { - this.handleFocusChange = focusChangeHandler; + setHandleFocusChange(focusChangeHandler) { + this.handleFocusChange = focusChangeHandler; + } }; diff --git a/content/patterns/listbox/examples/js/toolbar.js b/content/patterns/listbox/examples/js/toolbar.js index 6def976c0e..a1fb9f891b 100644 --- a/content/patterns/listbox/examples/js/toolbar.js +++ b/content/patterns/listbox/examples/js/toolbar.js @@ -7,6 +7,9 @@ /** * @namespace aria + * @description + * The aria namespace is used to support sharing class definitions between example files + * without causing eslint errors for undefined classes */ var aria = aria || {}; @@ -17,101 +20,118 @@ var aria = aria || {}; * @param toolbarNode * The DOM node pointing to the toolbar */ -aria.Toolbar = function (toolbarNode) { - this.toolbarNode = toolbarNode; - this.items = this.toolbarNode.querySelectorAll('.toolbar-item'); - this.selectedItem = this.toolbarNode.querySelector('.selected'); - this.registerEvents(); -}; -/** - * @description - * Register events for the toolbar interactions - */ -aria.Toolbar.prototype.registerEvents = function () { - this.toolbarNode.addEventListener( - 'keydown', - this.checkFocusChange.bind(this) - ); - this.toolbarNode.addEventListener('click', this.checkClickItem.bind(this)); -}; +aria.Toolbar = class Toolbar { + constructor(toolbarNode) { + this.toolbarNode = toolbarNode; + this.items = this.toolbarNode.querySelectorAll('.toolbar-item'); + this.selectedItem = this.toolbarNode.querySelector('.selected'); + this.registerEvents(); + } -/** - * @description - * Handle various keyboard controls; LEFT/RIGHT will shift focus; DOWN - * activates a menu button if it is the focused item. - * @param evt - * The keydown event object - */ -aria.Toolbar.prototype.checkFocusChange = function (evt) { - var key = evt.which || evt.keyCode; - var nextIndex, nextItem; + /** + * @description + * Register events for the toolbar interactions + */ + registerEvents() { + this.toolbarNode.addEventListener( + 'keydown', + this.checkFocusChange.bind(this) + ); + this.toolbarNode.addEventListener('click', this.checkClickItem.bind(this)); + } + + /** + * @description + * Handle various keyboard commands to move focus: + * LEFT: Previous button + * RIGHT: Next button + * HOME: First button + * END: Last button + * @param evt + * The keydown event object + */ + checkFocusChange(evt) { + let nextIndex, nextItem; + + // Do not move focus if any modifier keys pressed + if (!evt.shiftKey && !evt.metaKey && !evt.altKey && !evt.ctrlKey) { + switch (evt.key) { + case 'ArrowLeft': + case 'ArrowRight': + nextIndex = Array.prototype.indexOf.call( + this.items, + this.selectedItem + ); + nextIndex = evt.key === 'ArrowLeft' ? nextIndex - 1 : nextIndex + 1; + nextIndex = Math.max(Math.min(nextIndex, this.items.length - 1), 0); + + nextItem = this.items[nextIndex]; + break; - switch (key) { - case aria.KeyCode.LEFT: - case aria.KeyCode.RIGHT: - nextIndex = Array.prototype.indexOf.call(this.items, this.selectedItem); - nextIndex = key === aria.KeyCode.LEFT ? nextIndex - 1 : nextIndex + 1; - nextIndex = Math.max(Math.min(nextIndex, this.items.length - 1), 0); + case 'End': + nextItem = this.items[this.items.length - 1]; + break; - nextItem = this.items[nextIndex]; - this.selectItem(nextItem); - this.focusItem(nextItem); - break; - case aria.KeyCode.DOWN: - // if selected item is menu button, pressing DOWN should act like a click - if (aria.Utils.hasClass(this.selectedItem, 'menu-button')) { + case 'Home': + nextItem = this.items[0]; + break; + } + + if (nextItem) { + this.selectItem(nextItem); + this.focusItem(nextItem); + evt.stopPropagation(); evt.preventDefault(); - this.selectedItem.click(); } - break; + } } -}; -/** - * @description - * Selects a toolbar item if it is clicked - * @param evt - * The click event object - */ -aria.Toolbar.prototype.checkClickItem = function (evt) { - if (aria.Utils.hasClass(evt.target, 'toolbar-item')) { - this.selectItem(evt.target); + /** + * @description + * Selects a toolbar item if it is clicked + * @param evt + * The click event object + */ + checkClickItem(evt) { + if (evt.target.classList.contains('toolbar-item')) { + this.selectItem(evt.target); + } } -}; -/** - * @description - * Deselect the specified item - * @param element - * The item to deselect - */ -aria.Toolbar.prototype.deselectItem = function (element) { - aria.Utils.removeClass(element, 'selected'); - element.setAttribute('aria-selected', 'false'); - element.setAttribute('tabindex', '-1'); -}; + /** + * @description + * Deselect the specified item + * @param element + * The item to deselect + */ + deselectItem(element) { + element.classList.remove('selected'); + element.setAttribute('aria-selected', 'false'); + element.setAttribute('tabindex', '-1'); + } -/** - * @description - * Deselect the currently selected item and select the specified item - * @param element - * The item to select - */ -aria.Toolbar.prototype.selectItem = function (element) { - this.deselectItem(this.selectedItem); - aria.Utils.addClass(element, 'selected'); - element.setAttribute('aria-selected', 'true'); - element.setAttribute('tabindex', '0'); - this.selectedItem = element; -}; + /** + * @description + * Deselect the currently selected item and select the specified item + * @param element + * The item to select + */ + selectItem(element) { + this.deselectItem(this.selectedItem); + element.classList.add('selected'); + element.setAttribute('aria-selected', 'true'); + element.setAttribute('tabindex', '0'); + this.selectedItem = element; + } -/** - * @description - * Focus on the specified item - * @param element - * The item to focus on - */ -aria.Toolbar.prototype.focusItem = function (element) { - element.focus(); + /** + * @description + * Focus on the specified item + * @param element + * The item to focus on + */ + focusItem(element) { + element.focus(); + } }; diff --git a/content/patterns/listbox/examples/listbox-collapsible.html b/content/patterns/listbox/examples/listbox-collapsible.html index 2c08fc8190..bc27a2729c 100644 --- a/content/patterns/listbox/examples/listbox-collapsible.html +++ b/content/patterns/listbox/examples/listbox-collapsible.html @@ -15,7 +15,6 @@ - @@ -39,7 +38,7 @@

    Deprecation Warning

    - The following example implementation of the Listbox Pattern demonstrates a collapsible single-select listbox widget that is functionally similar to an HTML select input with the attribute size="1". + The following example implementation of the Listbox Pattern demonstrates a collapsible single-select listbox widget that is functionally similar to an HTML select input with the attribute size="1". The widget consists of a button that triggers the display of a listbox. In its default state, the widget is collapsed (the listbox is not visible) and the button label shows the currently selected option from the listbox. When the button is activated, the listbox is displayed and the current option is focused and selected. @@ -98,24 +97,23 @@

    Example

    -

    Notes

    -

    This listbox is scrollable; it has more options than its height can accommodate.

    -
      + + +
      +

      Accessibility Features

      +
      • - Scrolling only works as expected if the listbox is the options' offsetParent. - The example uses position: relative on the listbox to that effect. + Because this listbox implementation is scrollable and manages which option is focused by using aria-activedescendant, the JavaScript must ensure the focused option is visible. + So, when a keyboard or pointer event changes the option referenced by aria-activedescendant, if the referenced option is not fully visible, the JavaScript scrolls the listbox to position the option in view.
      • - When an option is focused that isn't (fully) visible, the listbox's scroll position is updated: -
          -
        1. If Up Arrow or Down Arrow is pressed, the previous or next option is scrolled into view.
          2. -
        2. If Home or End is pressed, the listbox scrolls all the way to the top or to the bottom.
          3. -
        3. If focusItem is called, the focused option will be scrolled to the top of the view if it was located above it or to the bottom if it was below it.
          4. -
        4. If the mouse is clicked on a partially visible option, it will be scrolled fully into view.
          5. -
        + To enhance perceivability when operating the listbox, visual keyboard focus and hover are styled using the CSS :hover and :focus pseudo-classes: +
          +
        • To help people with visual impairments identify the listbox as an interactive element, the cursor is changed to a pointer when hovering over the list.
          • +
        • To make it easier to distinguish the selected listbox option from other options, selection creates a 2 pixel border above and below the option.
          • +
        • -
      • When a fully visible option is focused in any way, no scrolling occurs.
        • -
    +
@@ -124,6 +122,12 @@

Keyboard Support

The example listbox on this page implements the following keyboard interface. Other variations and options for the keyboard interface are described in the Keyboard Interaction section of the Listbox Pattern.

+

+ NOTE: When visual focus is on an option in this listbox implementation, DOM focus remains on the listbox element and the value of aria-activedescendant on the listbox refers to the descendant option that is visually indicated as focused. + Where the following descriptions of keyboard commands mention focus, they are referring to the visual focus indicator, not DOM focus. + For more information about this focus management technique, see + Managing Focus in Composites Using aria-activedescendant. +

@@ -132,6 +136,15 @@

Keyboard Support

+ + + + - + - + - + - + - + - + - + - + - + - + @@ -189,7 +243,7 @@

Role, Property, State, and Tabindex Attributes

- + @@ -201,7 +255,7 @@

Role, Property, State, and Tabindex Attributes

- + + + + + + +
Tab +
    +
  • Moves focus into and out of the listbox.
    • +
  • If the listbox is expanded, selects the focused option, collapses the listbox, and moves focus out of the listbox.
    • +
+
Enter @@ -202,7 +215,7 @@

Role, Property, State, and Tabindex Attributes
aria-labelledby="ID_REF1 ID_REF2"aria-labelledby="ID_REF1 ID_REF2" button
    @@ -214,13 +227,13 @@

    Role, Property, State, and Tabindex Attributes

aria-haspopup="listbox"aria-haspopup="listbox" button Indicates that activating the button displays a listbox.
aria-expanded="true"aria-expanded="true" button
    @@ -237,13 +250,13 @@

    Role, Property, State, and Tabindex Attributes

aria-labelledby="ID_REF"aria-labelledby="ID_REF" ul Refers to the element containing the listbox label.
tabindex="-1"tabindex="-1" ul
    @@ -254,14 +267,13 @@

    Role, Property, State, and Tabindex Attributes

aria-activedescendant="ID_REF"aria-activedescendant="ID_REF" ul
    -
  • Set by the JavaScript when it displays and sets focus on the listbox; otherwise is not present.
    • -
  • Refers to the option in the listbox that is visually indicated as having keyboard focus.
    • +
  • When an option in the listbox is visually indicated as having keyboard focus, refers to that option.
    • +
  • Enables assistive technologies to know which element the application regards as focused while DOM focus remains on the listbox element.
  • When navigation keys, such as Down Arrow, are pressed, the JavaScript changes the value.
    • -
  • Enables assistive technologies to know which element the application regards as focused while DOM focus remains on the ul element.
  • For more information about this focus management technique, see Managing Focus in Composites Using aria-activedescendant. @@ -277,7 +289,7 @@

    Role, Property, State, and Tabindex Attributes

aria-selected="true"aria-selected="true" li diff --git a/content/patterns/listbox/examples/listbox-grouped.html b/content/patterns/listbox/examples/listbox-grouped.html index b3525cc656..8718204fed 100644 --- a/content/patterns/listbox/examples/listbox-grouped.html +++ b/content/patterns/listbox/examples/listbox-grouped.html @@ -15,7 +15,6 @@ - @@ -54,59 +53,97 @@

Example

    -
  • Cat
    • -
  • Dog
    • -
  • Tiger
    • -
  • Reindeer
    • -
  • Raccoon
    • +
  • + + Cat +
    • +
  • + + Dog +
    • +
  • + + Tiger +
    • +
  • + + Reindeer +
    • +
  • + + Raccoon +
    - -
  • Dolphin
    • -
  • Flounder
    • -
  • Eel
    • + +
  • + + Dolphin +
    • +
  • + + Flounder +
    • +
  • + + Eel +
    -
  • Falcon
    • -
  • Winged Horse
    • -
  • Owl
    • +
  • + + Falcon +
    • +
  • + + Winged Horse +
    • +
  • + + Owl +
-

Notes

-

This listbox is scrollable; it has more options than its height can accommodate.

-
    -
  1. - Scrolling only works as expected if the listbox is the options' offsetParent. - The example uses position: relative on the listbox to that effect. -
    2. + + + +
    +

    Accessibility Features

    +
    • - When an option is focused that isn't (fully) visible, the listbox's scroll position is updated: -
        -
      1. If Up Arrow or Down Arrow is pressed, the previous or next option is scrolled into view.
        2. -
      2. If Home or End is pressed, the listbox scrolls all the way to the top or to the bottom.
        3. -
      3. If focusItem is called, the focused option will be scrolled to the top of the view if it was located above it or to the bottom if it was below it.
        4. -
      4. If the mouse is clicked on a partially visible option, it will be scrolled fully into view.
        5. -
      + Because this listbox implementation is scrollable and manages which option is focused by using aria-activedescendant, the JavaScript must ensure the focused option is visible. + So, when a keyboard or pointer event changes the option referenced by aria-activedescendant, if the referenced option is not fully visible, the JavaScript scrolls the listbox to position the option in view.
      • -
    • When a fully visible option is focused in any way, no scrolling occurs.
    • - Normal scrolling through any scrolling mechanism (including Page Up and Page Down) works as expected. - The scroll position will jump as described for focusItem if a means other than a mouse click is used to change focus after scrolling. + To enhance perceivability when operating the listbox, visual keyboard focus and hover are styled using the CSS :hover and :focus pseudo-classes: +
        +
      • To help people with visual impairments identify the listbox as an interactive element, the cursor is changed to a pointer when hovering over the list.
        • +
      • To make it easier to distinguish the selected listbox option from other options, selection creates a 2 pixel border above and below the option.
        • +
      • -
+

Keyboard Support

- The example listboxes on this page implement the following keyboard interface. + The example listbox on this page implements the following keyboard interface. Other variations and options for the keyboard interface are described in the Keyboard Interaction section of the Listbox Pattern.

+

+ NOTE: When visual focus is on an option in this listbox implementation, DOM focus remains on the listbox element and the value of aria-activedescendant on the listbox refers to the descendant option that is visually indicated as focused. + Where the following descriptions of keyboard commands mention focus, they are referring to the visual focus indicator, not DOM focus. + For more information about this focus management technique, see + Managing Focus in Composites Using aria-activedescendant. +

@@ -115,6 +152,10 @@

Keyboard Support

+ + + + @@ -131,6 +172,15 @@

Keyboard Support

+ + + +
TabMoves focus into and out of the listbox.
Down Arrow Moves focus to and selects the next option. End Moves focus to and selects the last option.
Printable Characters +
    +
  • Type a character: focus moves to the next item with a name that starts with the typed character.
    • +
  • Type multiple characters in rapid succession: focus moves to the next item with a name that starts with the string of characters typed.
    • +
+
@@ -159,25 +209,29 @@

Role, Property, State, and Tabindex Attributes

aria-labelledby="ID_REF"aria-labelledby="ID_REF" div Refers to the element containing the listbox label.
tabindex="0"tabindex="0" div Includes the listbox in the page tab sequence.
aria-activedescendant="ID_REF"aria-activedescendant="ID_REF" div
    -
  • Tells assistive technologies which of the options, if any, is visually indicated as having keyboard focus.
    • -
  • DOM focus remains on the ul element and the idref specified for aria-activedescendant refers to the li element that is visually styled as focused.
    • +
  • When an option in the listbox is visually indicated as having keyboard focus, refers to that option.
    • +
  • Enables assistive technologies to know which element the application regards as focused while DOM focus remains on the listbox element.
  • When navigation keys, such as Down Arrow, are pressed, the JavaScript changes the value.
    • +
  • + For more information about this focus management technique, see + Managing Focus in Composites Using aria-activedescendant. +
aria-labelledby="ID_REF"aria-labelledby="ID_REF" ul Refers to the element containing the option group label.
aria-selected="true"aria-selected="true" li
    @@ -211,6 +265,14 @@

    Role, Property, State, and Tabindex Attributes
aria-hidden="true"span + Removes the character entity used for the check mark icon from the accessibility tree to prevent it from being included in the accessible name of the option. +
@@ -224,7 +286,7 @@

JavaScript and CSS Source Code

  • Javascript: - listbox.js, listbox-scrollable.js, utils.js + listbox.js, listbox-scrollable.js
    • diff --git a/content/patterns/listbox/examples/listbox-rearrangeable.html b/content/patterns/listbox/examples/listbox-rearrangeable.html index 5367d021eb..88d29d9a3d 100644 --- a/content/patterns/listbox/examples/listbox-rearrangeable.html +++ b/content/patterns/listbox/examples/listbox-rearrangeable.html @@ -15,7 +15,6 @@ - @@ -59,56 +58,89 @@

    Example 1: Single-Select Listbox

    Important Features: -
      -
    • Proximity of public K-12 schools
      • -
    • Proximity of child-friendly parks
      • -
    • Proximity of grocery shopping
      • -
    • Proximity of fast food
      • -
    • Proximity of fine dining
      • -
    • Neighborhood walkability
      • -
    • Availability of public transit
      • -
    • Proximity of hospital and medical services
      • -
    • Level of traffic noise
      • -
    • Access to major highways
      • +
        +
      • + + Proximity of public K-12 schools +
        • +
      • + + Proximity of child-friendly parks
        • +
      • + + Proximity of grocery shopping
        • +
      • + + Proximity of fast food
        • +
      • + + Proximity of fine dining
        • +
      • + + Neighborhood walkability
        • +
      • + + Availability of public transit
        • +
      • + + Proximity of hospital and medical services
        • +
      • + + Level of traffic noise
        • +
      • + + Access to major highways
    Unimportant Features: -
      - +
        +
        Last change:
        -

        Notes

        -
          -
        1. - Assistive technologies are told which option in the list is visually focused by the value of aria-activedescendant: -
            -
          1. DOM focus remains on the listbox element.
            2. -
          2. When a key that moves focus is pressed or an option is clicked, JavaScript changes the value of aria-activedescendant on the listbox element.
            3. -
          3. If the listbox element does not contain any options, aria-activedescendant does not have a value.
            4. -
          -
          2. -
        2. - When Tab moves focus into either listbox: -
            -
          1. If none of the options are selected, the first option receives focus.
            2. -
          2. If an option is selected, the selected option receives focus.
            3. -
          -
          3. -
        3. Only one option may be selected at a time (have aria-selected="true").
          4. -
        4. - As the user moves focus in the list, selection also moves. - That is, both the value of aria-activedescendant and the element that has aria-selected="true" change. -
          5. -
        @@ -121,73 +153,99 @@

        Example 2: Multi-Select Listbox

        Available upgrades: -
          -
        • Leather seats
          • -
        • Front seat warmers
          • -
        • Rear bucket seats
          • -
        • Rear seat warmers
          • -
        • Front sun roof
          • -
        • Rear sun roof
          • -
        • Cloaking capability
          • -
        • Food synthesizer
          • -
        • Advanced waste recycling system
          • -
        • Turbo vertical take-off capability
          • +
            +
          • + + Leather seats +
            • +
          • + + Front seat warmers +
            • +
          • + + Rear bucket seats +
            • +
          • + + Rear seat warmers +
            • +
          • + + Front sun roof +
            • +
          • + + Rear sun roof +
            • +
          • + + Cloaking capability +
            • +
          • + + Food synthesizer +
            • +
          • + + Advanced waste recycling system +
            • +
          • + + Turbo vertical take-off capability +
          - +
        Upgrades you have chosen: -
          - +
            +
          +
          Last change:
          -

          Notes

          -
            -
          1. - Like in example 1, assistive technologies are told which option in the list is visually focused by the value of aria-activedescendant: -
              -
            1. DOM focus remains on the listbox element.
              2. -
            2. When a key that moves focus is pressed or an option is clicked, JavaScript changes the value of aria-activedescendant on the listbox element.
              3. -
            3. If the listbox element does not contain any options, aria-activedescendant does not have a value.
              4. -
            -
            2. -
          2. - When Tab moves focus into either listbox: -
              -
            1. If none of the options are selected, focus is set on the first option.
              2. -
            2. If one or more options are selected, focus is set on the first selected option.
              3. -
            -
            3. -
          3. - Unlike example 1, more than one option may be selected at a time (have aria-selected="true"). -
              -
            1. The multi-select capability is communicated to assistive technologies by setting aria-multiselectable="true" on the listbox element.
              2. -
            2. All option elements have a value set for aria-selected.
              3. -
            3. Selected options have aria-selected set to true and all others have it set to false.
              4. -
            4. Keys that move focus do not change the selected state of an option.
              5. -
            -
            4. -
          4. Users can toggle the selected state of the focused option with Space or click.
            5. -

          Accessibility Features

          -
            +
            • Keyboard shortcuts for action buttons: -
                +
                • Action buttons have the following shortcuts:
                    -
                  • "Up": Alt + Up Arrow
                    • -
                  • "Down": Alt + Down Arrow
                    • -
                  • "Add": Enter
                    • -
                  • "Not Important", "Important", and "Remove": Delete
                    • +
                  • "Up": Alt + Up Arrow
                    • +
                  • "Down": Alt + Down Arrow
                    • +
                  • "Add": Enter
                    • +
                  • "Not Important", "Important", and "Remove": Delete
                • Availability of the shortcuts is communicated to assistive technologies via the aria-keyshortcuts property on the button elements.
                  • @@ -197,15 +255,26 @@

                  Accessibility Features

                • Using a shortcut key intentionally places focus to optimize both screen reader and keyboard usability. - For example, pressing Alt + Up Arrow in the "Important Features" list keeps focus on the option that is moved up, enabling all keyboard users to easily perform consecutive move operations for an option and screen reader users to hear the position of an option after it is moved. + For example, pressing Alt + Up Arrow in the "Important Features" list keeps focus on the option that is moved up, enabling all keyboard users to easily perform consecutive move operations for an option and screen reader users to hear the position of an option after it is moved. Similarly, pressing Enter in the available options list leaves focus in the available options list. If the option that had focus before the add operation is no longer present in the list, focus lands on the first of the subsequent options that is still present.
                  • -
              +
          1. In example 1, since there are four action buttons, a toolbar widget is used to group all the action buttons into a single tab stop.
          2. Live regions provide confirmation of completed actions.
            3. -
          +
        • + Because this listbox implementation is scrollable and manages which option is focused by using aria-activedescendant, the JavaScript must ensure the focused option is visible. + So, when a keyboard or pointer event changes the option referenced by aria-activedescendant, if the referenced option is not fully visible, the JavaScript scrolls the listbox to position the option in view. +
          • +
        • + To enhance perceivability when operating the listbox, visual keyboard focus and hover are styled using the CSS :hover and :focus pseudo-classes: +
            +
          • To help people with visual impairments identify the listbox as an interactive element, the cursor is changed to a pointer when hovering over the list.
            • +
          • To make it easier to distinguish the selected listbox option from other options, selection creates a 2 pixel border above and below the option.
            • +
          +
          • +
          @@ -214,6 +283,12 @@

          Keyboard Support

          The example listboxes on this page implement the following keyboard interface. Other variations and options for the keyboard interface are described in the Keyboard Interaction section of the Listbox Pattern.

          +

          + NOTE: When visual focus is on an option in these implementations of listbox, DOM focus remains on the listbox element and the value of aria-activedescendant on the listbox refers to the descendant option that is visually indicated as focused. + Where the following descriptions of keyboard commands mention focus, they are referring to the visual focus indicator, not DOM focus. + For more information about this focus management technique, see + Managing Focus in Composites Using aria-activedescendant. +

          @@ -222,6 +297,18 @@

          Keyboard Support

          + + + + + + + +
          Tab +
            +
          • Moves focus into and out of the listbox.
            • +
          • + When the listbox receives focus, if none of the options are selected, the first option receives focus. + Otherwise, the first selected option receives focus. +
            • +
          +
          Down Arrow @@ -258,15 +345,23 @@

          Keyboard Support
          Printable Characters +
            +
          • Type a character: focus moves to the next item with a name that starts with the typed character.
            • +
          • Type multiple characters in rapid succession: focus moves to the next item with a name that starts with the string of characters typed.
            • +
          +

          Multiple selection keys supported in example 2

          -
          -

          Note

          -

          The selection behavior demonstrated differs from the behavior provided by browsers for native HTML <select multiple> elements. +

          + NOTE: The selection behavior demonstrated differs from the behavior provided by browsers for native HTML <select multiple> elements. The HTML select element behavior is to alter selection with unmodified up/down arrow keys, requiring the use of modifier keys to select multiple options. - This example demonstrates the multiple selection interaction model recommended in the Keyboard Interaction section of the Listbox Pattern, which does not require the use of modifier keys.

          -
          + This example demonstrates the multiple selection interaction model recommended in the Keyboard Interaction section of the Listbox Pattern, which does not require the use of modifier keys. +

          @@ -333,19 +428,19 @@

          Role, Property, State, and Tabindex Attributes

          - + - + - + - + @@ -376,7 +475,7 @@

          Role, Property, State, and Tabindex Attributes

          - + - + + + + + + +
          aria-labelledby="ID_REF"aria-labelledby="ID_REF" ul Applied to the element with the listbox role, it refers to the span containing its label.
          tabindex="0"tabindex="0" ul Applied to the element with the listbox role, it puts the listbox in the tab sequence.
          aria-multiselectable="true"aria-multiselectable="true" ul
            @@ -357,14 +452,18 @@

            Role, Property, State, and Tabindex Attributes

          aria-activedescendant="ID_REF"aria-activedescendant="ID_REF" ul
            -
          • Applied to the element with the listbox role, tells assistive technologies which of the options, if any, is visually indicated as having keyboard focus.
            • -
          • DOM focus remains on the ul element and the idref specified for aria-activedescendant refers to the li element that is visually styled as focused.
            • +
          • When an option in the listbox is visually indicated as having keyboard focus, refers to that option.
            • +
          • Enables assistive technologies to know which element the application regards as focused while DOM focus remains on the listbox element.
          • When navigation keys, such as Down Arrow, are pressed, the JavaScript changes the value.
            • -
          • When the listbox is empty, aria-activedescendant="".
            • +
          • When the listbox is empty, aria-activedescendant="".
            • +
          • + For more information about this focus management technique, see + Managing Focus in Composites Using aria-activedescendant. +
          aria-selected="true"aria-selected="true" li
            @@ -389,7 +488,7 @@

            Role, Property, State, and Tabindex Attributes

          aria-selected="false"aria-selected="false" li
            @@ -399,6 +498,14 @@

            Role, Property, State, and Tabindex Attributes
          aria-hidden="true"span + Removes the character entities used for the check mark, left arrow and right arrow from the accessibility tree to prevent them from being included in the accessible name of an option or button. +
          @@ -412,7 +519,7 @@

          JavaScript and CSS Source Code

        • Javascript: - listbox.js, toolbar.js, listbox-rearrangeable.js, utils.js + listbox.js, toolbar.js, listbox-rearrangeable.js
          • diff --git a/content/patterns/listbox/examples/listbox-scrollable.html b/content/patterns/listbox/examples/listbox-scrollable.html index 1b54fd87f7..3dbb24ce3a 100644 --- a/content/patterns/listbox/examples/listbox-scrollable.html +++ b/content/patterns/listbox/examples/listbox-scrollable.html @@ -15,7 +15,6 @@ - @@ -53,67 +52,146 @@

          Example

          Transuranium elements:
            -
          • Neptunium
            • -
          • Plutonium
            • -
          • Americium
            • -
          • Curium
            • -
          • Berkelium
            • -
          • Californium
            • -
          • Einsteinium
            • -
          • Fermium
            • -
          • Mendelevium
            • -
          • Nobelium
            • -
          • Lawrencium
            • -
          • Rutherfordium
            • -
          • Dubnium
            • -
          • Seaborgium
            • -
          • Bohrium
            • -
          • Hassium
            • -
          • Meitnerium
            • -
          • Darmstadtium
            • -
          • Roentgenium
            • -
          • Copernicium
            • -
          • Nihonium
            • -
          • Flerovium
            • -
          • Moscovium
            • -
          • Livermorium
            • -
          • Tennessine
            • -
          • Oganesson
            • +
          • + + Neptunium +
            • +
          • + + Plutonium +
            • +
          • + + Americium +
            • +
          • + + Curium +
            • +
          • + + Berkelium +
            • +
          • + + Californium +
            • +
          • + + Einsteinium +
            • +
          • + + Fermium +
            • +
          • + + Mendelevium +
            • +
          • + + Nobelium +
            • +
          • + + Lawrencium +
            • +
          • + + Rutherfordium +
            • +
          • + + Dubnium +
            • +
          • + + Seaborgium +
            • +
          • + + Bohrium +
            • +
          • + + Hassium +
            • +
          • + + Meitnerium +
            • +
          • + + Darmstadtium +
            • +
          • + + Roentgenium +
            • +
          • + + Copernicium +
            • +
          • + + Nihonium +
            • +
          • + + Flerovium +
            • +
          • + + Moscovium +
            • +
          • + + Livermorium +
            • +
          • + + Tennessine +
            • +
          • + + Oganesson +
          -

          Notes

          -

          This listbox is scrollable; it has more options than its height can accommodate.

          -
            -
          1. - Scrolling only works as expected if the listbox is the options' offsetParent. - The example uses position: relative on the listbox to that effect. -
            2. + + +
            +

            Accessibility Features

            +
            • - When an option is focused that isn't (fully) visible, the listbox's scroll position is updated: -
                -
              1. If Up Arrow or Down Arrow is pressed, the previous or next option is scrolled into view.
                2. -
              2. If Home or End is pressed, the listbox scrolls all the way to the top or to the bottom.
                3. -
              3. If focusItem is called, the focused option will be scrolled to the top of the view if it was located above it or to the bottom if it was below it.
                4. -
              4. If the mouse is clicked on a partially visible option, it will be scrolled fully into view.
                5. -
              + Because this listbox implementation is scrollable and manages which option is focused by using aria-activedescendant, the JavaScript must ensure the focused option is visible. + So, when a keyboard or pointer event changes the option referenced by aria-activedescendant, if the referenced option is not fully visible, the JavaScript scrolls the listbox to position the option in view.
              • -
            • When a fully visible option is focused in any way, no scrolling occurs.
            • - Normal scrolling through any scrolling mechanism (including Page Up and Page Down) works as expected. - The scroll position will jump as described for focusItem if a means other than a mouse click is used to change focus after scrolling. + To enhance perceivability when operating the listbox, visual keyboard focus and hover are styled using the CSS :hover and :focus pseudo-classes: +
                +
              • To help people with visual impairments identify the listbox as an interactive element, the cursor is changed to a pointer when hovering over the list.
                • +
              • To make it easier to distinguish the selected listbox option from other options, selection creates a 2 pixel border above and below the option.
                • +
              • -
          +

          Keyboard Support

          - The example listboxes on this page implement the following keyboard interface. + The example listbox on this page implements the following keyboard interface. Other variations and options for the keyboard interface are described in the Keyboard Interaction section of the Listbox Pattern.

          +

          + NOTE: When visual focus is on an option in this listbox implementation, DOM focus remains on the listbox element and the value of aria-activedescendant on the listbox refers to the descendant option that is visually indicated as focused. + Where the following descriptions of keyboard commands mention focus, they are referring to the visual focus indicator, not DOM focus. + For more information about this focus management technique, see + Managing Focus in Composites Using aria-activedescendant. +

          @@ -122,6 +200,10 @@

          Keyboard Support

          + + + + @@ -138,6 +220,15 @@

          Keyboard Support

          + + + +
          TabMoves focus into and out of the listbox.
          Down Arrow Moves focus to and selects the next option. End Moves focus to and selects the last option.
          Printable Characters +
            +
          • Type a character: focus moves to the next item with a name that starts with the typed character.
            • +
          • Type multiple characters in rapid succession: focus moves to the next item with a name that starts with the string of characters typed.
            • +
          +
          @@ -145,7 +236,7 @@

          Keyboard Support

          Role, Property, State, and Tabindex Attributes

          - The example listboxes on this page implement the following ARIA roles, states, and properties. + The example listbox on this page implements the following ARIA roles, states, and properties. Information about other ways of applying ARIA roles, states, and properties is available in the Roles, States, and Properties section of the Listbox Pattern.

          @@ -166,25 +257,29 @@

          Role, Property, State, and Tabindex Attributes

          - + - + - + @@ -196,7 +291,7 @@

          Role, Property, State, and Tabindex Attributes

          - + + + + + + +
          aria-labelledby="ID_REF"aria-labelledby="ID_REF" ul Refers to the element containing the listbox label.
          tabindex="0"tabindex="0" ul Includes the listbox in the page tab sequence.
          aria-activedescendant="ID_REF"aria-activedescendant="ID_REF" ul
            -
          • Tells assistive technologies which of the options, if any, is visually indicated as having keyboard focus.
            • -
          • DOM focus remains on the ul element and the idref specified for aria-activedescendant refers to the li element that is visually styled as focused.
            • +
          • When an option in the listbox is visually indicated as having keyboard focus, refers to that option.
            • +
          • Enables assistive technologies to know which element the application regards as focused while DOM focus remains on the listbox element.
          • When navigation keys, such as Down Arrow, are pressed, the JavaScript changes the value.
            • +
          • + For more information about this focus management technique, see + Managing Focus in Composites Using aria-activedescendant. +
          aria-selected="true"aria-selected="true" li
            @@ -206,6 +301,14 @@

            Role, Property, State, and Tabindex Attributes
          aria-hidden="true"span + Removes the character entity used for the check mark icon from the accessibility tree to prevent it from being included in the accessible name of the option. +
          @@ -219,7 +322,7 @@

          JavaScript and CSS Source Code

        • Javascript: - listbox.js, listbox-scrollable.js, utils.js + listbox.js, listbox-scrollable.js
          • diff --git a/test/tests/listbox_grouped.js b/test/tests/listbox_grouped.js index 8b4846e1c3..32ef9927f1 100644 --- a/test/tests/listbox_grouped.js +++ b/test/tests/listbox_grouped.js @@ -96,6 +96,20 @@ ariaTest( } ); +ariaTest( + 'aria-hidden="true" on li > span.checkmark elements', + exampleFile, + 'span-aria-hidden', + async (t) => { + await assertAttributeValues( + t, + `${ex.optionSelector} span.checkmark`, + 'aria-hidden', + 'true' + ); + } +); + ariaTest( '"aria-selected" on option elements', exampleFile, diff --git a/test/tests/listbox_rearrangeable.js b/test/tests/listbox_rearrangeable.js index 0010fbb5d8..4f46856fd1 100644 --- a/test/tests/listbox_rearrangeable.js +++ b/test/tests/listbox_rearrangeable.js @@ -15,6 +15,7 @@ const ex = { listboxSelector: '#ex1 [role="listbox"]', importantSelector: '#ex1 [role="listbox"]#ss_imp_list', optionSelector: '#ex1 [role="option"]', + spanSelector: '#ex1 span.checkmark', numOptions: 10, firstOptionSelector: '#ex1 #ss_opt1', lastOptionSelector: '#ex1 #ss_opt10', @@ -23,6 +24,7 @@ const ex = { listboxSelector: '#ex2 [role="listbox"]', availableSelector: '#ex2 [role="listbox"]#ms_imp_list', optionSelector: '#ex2 [role="option"]', + spanSelector: '#ex2 span.checkmark', numOptions: 10, firstOptionSelector: '#ex2 #ms_opt1', lastOptionSelector: '#ex2 #ms_opt10', @@ -122,6 +124,16 @@ ariaTest( } ); +ariaTest( + 'aria-hidden="true" on span[class=checkmark] elements', + exampleFile, + 'span-aria-hidden', + async (t) => { + await assertAttributeValues(t, ex[1].spanSelector, 'aria-hidden', 'true'); + await assertAttributeValues(t, ex[2].spanSelector, 'aria-hidden', 'true'); + } +); + ariaTest( 'role="option" on li elements', exampleFile, diff --git a/test/tests/listbox_scrollable.js b/test/tests/listbox_scrollable.js index cba46a1abf..d33b474880 100644 --- a/test/tests/listbox_scrollable.js +++ b/test/tests/listbox_scrollable.js @@ -11,6 +11,7 @@ const exampleFile = 'content/patterns/listbox/examples/listbox-scrollable.html'; const ex = { listboxSelector: '#ex [role="listbox"]', optionSelector: '#ex [role="option"]', + spanSelector: '#ex [role="option"] span.checkmark', numOptions: 26, firstOptionSelector: '#ex #ss_elem_Np', }; @@ -78,6 +79,15 @@ ariaTest( } ); +ariaTest( + 'aria-hidden="true" on li > span elements', + exampleFile, + 'span-aria-hidden', + async (t) => { + await assertAttributeValues(t, ex.spanSelector, 'aria-hidden', 'true'); + } +); + ariaTest( '"aria-selected" on option elements', exampleFile,