diff --git a/.link-checker.js b/.link-checker.js
index d3a1ff3fda..4655e412ce 100644
--- a/.link-checker.js
+++ b/.link-checker.js
@@ -1,5 +1,8 @@
module.exports = {
- filesToIgnore: ['content/shared/templates/example-usage-warning.html'],
+ filesToIgnore: [
+ // For example:
+ // 'content/shared/templates/example-usage-warning.html',
+ ],
excludedLinks: {
'content/patterns/menubar/examples/menubar-navigation.html': [
'#ex1 [role=menuitem]',
@@ -11,9 +14,16 @@ module.exports = {
'.carousel-image a',
],
},
+ hashCheckHandlers: [
+ {
+ name: 'github',
+ pattern: /^https:\/\/github\.com\/.*/,
+ matchHash: (ids, hash) =>
+ ids.includes(hash) || ids.includes(`user-content-${hash}`),
+ },
+ ],
ignoreHashesOnExternalPagesMatchingRegex: [
// Some hash links are resolved with JS and are therefore difficult to check algorithmically
- /^https:\/\/github\.com\/.*\/wiki\//,
/^https:\/\/html\.spec\.whatwg\.org\/multipage\//,
],
};
diff --git a/README.md b/README.md
index a219370806..242de757bc 100644
--- a/README.md
+++ b/README.md
@@ -3,8 +3,8 @@
This repository maintains the WAI-ARIA Authoring Practices Guide (APG).
- Published at: [w3.org/wai/aria/apg](https://www.w3.org/wai/aria/apg/)
-- Developed by the [Authoring Practices Task Force](https://www.w3.org/WAI/ARIA/task-forces/practices/) of the [ARIA Working Group](http://www.w3.org/WAI/ARIA/).
-- Staff contact: [Michael Cooper](http://www.w3.org/People/cooper/).
+- Developed by the [Authoring Practices Task Force](https://www.w3.org/WAI/ARIA/task-forces/practices/) of the [ARIA Working Group](http://www.w3.org/WAI/ARIA/)
+- Staff contact: [Daniel Montalvo](https://www.w3.org/people#dmontalvo)
Please do not provide commit access to this repository without coordination.
@@ -106,18 +106,3 @@ See the [APG Editorial Style Guidelines](https://github.com/w3c/aria-practices/w
for information about writing prose for the APG.
The [ReadMe for the ARIA specification](https://github.com/w3c/aria/)
contains additional useful editorial guidance.
-
-## ARIA Roles, Properties and States Referenced in Guidance and Examples(Also known as APG Coverage Report)
-
-[APG Coverage Report](https://raw.githack.com/w3c/aria-practices/main/coverage/index.html) includes information on number of guidance and example references in the WAI-ARIA Authoring Practices for each ARIA role, property and state.
-
-As of January 11, 2022, APG has examples of
-
-1. CSV Files of Role, Properties and States Coverage
-2. Roles with no Guidance or Examples (29)
-3. Roles with at Least One Guidance or Example (13)
-4. Roles with More than One Guidance or Example (36)
-5. Properties and States with no Examples (12)
-6. Properties and States with One Examples (8)
-7. Properties and States with More than One Example (28)
-8. Example Coding Practices
diff --git a/common/acknowledgements/aria-contributors.html b/common/acknowledgements/aria-contributors.html
deleted file mode 100644
index 0d65afa244..0000000000
--- a/common/acknowledgements/aria-contributors.html
+++ /dev/null
@@ -1,148 +0,0 @@
-
-
Other ARIA contributors, commenters, and previously active participants
-
-
Ann Abbott (Invited Expert)
-
Shadi Abou-Zahra (W3C)
-
Jim Allan (TSB)
-
Jonny Axelsson (Opera Software)
-
David Baron (Mozilla Foundation)
-
Art Barstow (Nokia Corporation)
-
Simon Bates
-
Christy Blew (University of Illinois at Urbana-Champaign)
-
Chris Blouch (AOL)
-
David Bolter (Mozilla Foundation)
-
Judy Brewer (W3C/MIT)
-
Mark Birbeck (Sidewinder Labs)
-
Bogdan Brinza (Microsoft Corporation)
-
Sally Cain (Royal National Institute of Blind People (RNIB))
-
Thaddeus Cambron (Invited Expert)
-
Gerardo Capiel (Benetech)
-
Ben Caldwell (Trace)
-
Sofia Celic-Li
-
Jaesik Chang (Samsung Electronics Co., Ltd.)
-
Alex Qiang Chen (University of Manchester)
-
Charles Chen (Google, Inc.)
-
Gerard K. Cohen
-
Christian Cohrs
-
Deborah Dahl
-
Erik Dahlström (Opera Software)
-
Dimitar Denev (Frauenhofer Gesellschaft)
-
Micah Dubinko (Invited Expert)
-
Mandana Eibegger
-
Beth Epperson (Websense)
-
Fred Esch (IBM Corporation)
-
Donald Evans (AOL)
-
Chris Fleizach (Apple Inc.)
-
John Foliot (Deque Systems, Inc.)
-
Kelly Ford (Microsoft Corporation)
-
Geoff Freed (Invited Expert, NCAM)
-
Kentarou Fukuda (IBM Corporation)
-
Christopher Gallelo (Microsoft Corporation)
-
Billy Gregory (The Paciello Group, LLC)
-
Karl Groves (The Paciello Group, LLC)
-
Birkir Gunnarsson (Deque Systems, Inc.)
-
Guido Geloso
-
Ali Ghassemi
-
Becky Gibson (Invited Expert)
-
Alfred S. Gilman
-
Andres Gonzalez (Adobe Systems Inc.)
-
Scott González (JQuery Foundation)
-
James Graham
-
Georgios Grigoriadis (SAP AG)
-
Jeff Grimes (Oracle)
-
Loretta Guarino Reid (Google, Inc.)
-
Markus Gylling (DAISY Consortium)
-
Katie Haritos-Shea (Knowbility)
-
Barbara Hartel
-
James Hawkins (Google, Inc.)
-
Benjamin Hawkes-Lewis
-
Sean Hayes (Microsoft Corporation)
-
Mona Heath (University of Illinois at Urbana-Champaign)
-
Jan Heck
-
Shawn Henry
-
Tina Homboe
-
John Hrvatin (Microsoft Corporation)
-
Takahiro Inada
-
Masayasu Ishikawa (W3C)
-
Jim Jewitt
-
Kenny Johar (Microsoft Corporation)
-
Earl Johnson (Sun)
-
Masahiko Kaneko (Microsoft Corporation)
-
Marjolein Katsma
-
Susann Keohane (IBM Corporation)
-
George Kerscher (International Digital Publishing Forum)
-
Jason Kiss (Department of Internal Affairs, New Zealand Government)
-
Todd Kloots
-
Jamie Knight (British Broadcasting Corporation)
-
Johannes Koch
-
Sam Kuper
-
Jael Kurz
-
Rajesh Lal (Nokia Corporation)
-
Diego La Monica (International Webmasters Association / HTML Writers Guild (IWA-HWG))
-
-
Alex Li (SAP)
-
Chris Lilley
-
Thomas Logan (HiSoftware Inc.)
-
Brian Loh
-
William Loughborough (Invited Expert)
-
Linda Mao (Microsoft)
-
Anders Markussen (Opera Software)
-
Krzysztof Maczyński
-
Matthew May (Adobe Systems Inc.)
-
Shane McCarron (Invited Expert, Aptest)
-
Charles McCathie Nevile (Yandex)
-
Juliette McShane (Access2online Inc.)
-
Heather Migliorisi (Invited Expert)
-
Mary Jo Mueller (IBM Corporation)
-
Alexandre Morgaut (4D)
-
Ann Navarro (Invited Expert)
-
Joshue O Connor (Invited Expert, CFIT)
-
Artur Ortega (Microsoft Corporation)
-
Sailesh Panchang (Deque)
-
Lisa Pappas (Society for Technical Communication (STC))
-
Marta Pawlowlska (Samsung Electronics Co., Ltd.)
-
Dave Pawson (RNIB)
-
Steven Pemberton (CWI Amsterdam)
-
Simon Pieters (Opera Software)
-
Jean-Bernard Piot (4D)
-
David Poehlman (Opera Software)
-
Sarah Pulis (Media Access Australia)
-
T.V. Raman (Google, Inc.)
-
Melanie Richards (Microsoft Corporation)
-
Jan Richards
-
Gregory Rosmaita (Invited Expert)
-
Tony Ross (Microsoft Corporation)
-
Alex Russell (Dojo Foundation) (
-
Mark Sadecki (Invited Expert)
-
Mario Sánchez Prada (Samsung Electronics Co., Ltd. and Gnome Foundation)
-
Martin Schaus (SAP AG)
-
Doug Schepers (W3C)
-
Cynthia Shelly (Microsoft Corporation)
-
Joseph Scheuhammer (Invited Expert, Inclusive Design Research Centre, OCAD University)
-
Matthias Schmitt
-
Richard Schwerdtfeger (IBM, Knowbility)
-
Marc Silbey (Microsoft Corporation)
-
Leif Halvard Sili
-
Henri Sivonen (Mozilla)
-
Michael Smith (W3C)
-
Andi Snow-Weaver (IBM Corporation)
-
Ville Skyttä
-
Henny Swan (BBC)
-
Vitaly Sourikov
-
Mike Squillace (IBM)
-
Maciej Stachowiak (Apple Inc.)
-
Christophe Strobbe
-
Suzanne Taylor (Pearson plc)
-
Terrill Thompson
-
David Todd
-
Gregg Vanderheiden (Invited Expert, Trace)
-
Job van Achterberg (Invited Expert)
-
Anne van Kesteren
-
Wen He (Tencent)
-
Wu Wei (W3C / RITT)
-
Ryan Williams (Oracle)
-
Tom Wlodkowski
-
Sam White (Apple Inc.)
-
Gottfried Zimmermann (Invited Expert, Access Technologies Group)
+
+
+ Contributing to the APG
+
+
+
+
+
+
+
+
+
+
+
+
Contributing to the APG
+
+
+
Introduction
+
+ Continuous improvement to the utility and quality of the ARIA Authoring Practices Guide (APG) depends on broad community input and participation.
+ Anyone may contribute feedback, suggestions, or code via the channels described below.
+ However, if you would like to contribute regularly, please consider
+ joining the Authoring Practices Task Force.
+ As a task force participant, you and your organization have greater influence over APG development, and are listed as contributors where appropriate.
+
+
+
+
+
Providing feedback
+
+ The APG provides two public feedback channels -- GitHub and email.
+ Links to both are provided at the bottom of every page in the APG.
+
+
+ GitHub issues are the best way to ask a question, make a suggestion, or report a problem.
+ Before creating a new issue, it is helpful if you first review existing issues to determine whether there is an issue addressing the same concern.
+ If so, please comment on that issue rather than raising another.
+ If the concern you would like addressed is related to an example implementation of an APG pattern, at the bottom of the page, next to the revision date, there is a link named "Related Issues".
+ That link opens a GitHub project containing all issues associated with the relevant pattern and its examples.
+
+ The task force also uses the aria-practices public mailing list for email discussion.
+ Meeting announcements, agendas, and links to minutes are sent to the mailing list.
+ While GitHub issues are the preferred place to discuss APG content, the mailing list is available to anyone who would prefer to communicate by
+ sending email to the ARIA Authoring Practices public mailing list.
+
+ The APG is developed by the
+ ARIA Authoring Practices Task Force,
+ which is a sub-group of the
+ ARIA Working Group.
+ The task force meets weekly to coordinate work on development of the APG.
+ Task force participants are expected to regularly attend meetings and to actively contribute.
+ Examples of contributions include:
+
+
+
Testing the functionality and accessibility of example implementations of the APG patterns
+
Fixing bugs and implementing enhancements in example implementations of the APG patterns
+
Helping write responses to community feedback
+
Reviewing and editing documentation
+
Designing or engineering pattern implementation examples
+
Creating and editing patterns and practices for ARIA usage
+
+
+ To participate in the Authoring Practices Task Force, you first need to
+ become a participant in the ARIA Working Group.
+ If you are already a participant in the ARIA Working Group, contact
+ Daniel Montalvo
+ and request membership in the Authoring Practices Task Force.
+
+
+
+
+
+
+
diff --git a/content/images/pattern-accordion.svg b/content/images/pattern-accordion.svg
new file mode 100644
index 0000000000..4ee0b682b6
--- /dev/null
+++ b/content/images/pattern-accordion.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/content/images/pattern-alert.svg b/content/images/pattern-alert.svg
new file mode 100644
index 0000000000..68937594ad
--- /dev/null
+++ b/content/images/pattern-alert.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/content/images/pattern-alertdialog.svg b/content/images/pattern-alertdialog.svg
new file mode 100644
index 0000000000..9e3ba6a1cc
--- /dev/null
+++ b/content/images/pattern-alertdialog.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/content/images/pattern-breadcrumb.svg b/content/images/pattern-breadcrumb.svg
new file mode 100644
index 0000000000..0a92ff66bc
--- /dev/null
+++ b/content/images/pattern-breadcrumb.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/content/images/pattern-button.svg b/content/images/pattern-button.svg
new file mode 100644
index 0000000000..38df7318c0
--- /dev/null
+++ b/content/images/pattern-button.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/content/images/pattern-carousel.svg b/content/images/pattern-carousel.svg
new file mode 100644
index 0000000000..ead4504eba
--- /dev/null
+++ b/content/images/pattern-carousel.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/content/images/pattern-checkbox.svg b/content/images/pattern-checkbox.svg
new file mode 100644
index 0000000000..e4cdc2e5cd
--- /dev/null
+++ b/content/images/pattern-checkbox.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/content/images/pattern-combobox.svg b/content/images/pattern-combobox.svg
new file mode 100644
index 0000000000..bb3f87adb2
--- /dev/null
+++ b/content/images/pattern-combobox.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/content/images/pattern-dialog-modal.svg b/content/images/pattern-dialog-modal.svg
new file mode 100644
index 0000000000..7fca36b9f8
--- /dev/null
+++ b/content/images/pattern-dialog-modal.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/content/images/pattern-disclosure.svg b/content/images/pattern-disclosure.svg
new file mode 100644
index 0000000000..f926d87cad
--- /dev/null
+++ b/content/images/pattern-disclosure.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/content/images/pattern-feed.svg b/content/images/pattern-feed.svg
new file mode 100644
index 0000000000..c50ca4f408
--- /dev/null
+++ b/content/images/pattern-feed.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/content/images/pattern-grid.svg b/content/images/pattern-grid.svg
new file mode 100644
index 0000000000..4b3c38a720
--- /dev/null
+++ b/content/images/pattern-grid.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/content/images/pattern-landmarks.svg b/content/images/pattern-landmarks.svg
new file mode 100644
index 0000000000..3a744dc689
--- /dev/null
+++ b/content/images/pattern-landmarks.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/content/images/pattern-link.svg b/content/images/pattern-link.svg
new file mode 100644
index 0000000000..26049b2472
--- /dev/null
+++ b/content/images/pattern-link.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/content/images/pattern-listbox.svg b/content/images/pattern-listbox.svg
new file mode 100644
index 0000000000..16561e92fa
--- /dev/null
+++ b/content/images/pattern-listbox.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/content/images/pattern-menu-button.svg b/content/images/pattern-menu-button.svg
new file mode 100644
index 0000000000..1924f15f45
--- /dev/null
+++ b/content/images/pattern-menu-button.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/content/images/pattern-menubar.svg b/content/images/pattern-menubar.svg
new file mode 100644
index 0000000000..3a75d84688
--- /dev/null
+++ b/content/images/pattern-menubar.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/content/images/pattern-meter.svg b/content/images/pattern-meter.svg
new file mode 100644
index 0000000000..b508bb3e71
--- /dev/null
+++ b/content/images/pattern-meter.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/content/images/pattern-radio.svg b/content/images/pattern-radio.svg
new file mode 100644
index 0000000000..3339928eb9
--- /dev/null
+++ b/content/images/pattern-radio.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/content/images/pattern-slider-multithumb.svg b/content/images/pattern-slider-multithumb.svg
new file mode 100644
index 0000000000..ad4c28a5de
--- /dev/null
+++ b/content/images/pattern-slider-multithumb.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/content/images/pattern-slider.svg b/content/images/pattern-slider.svg
new file mode 100644
index 0000000000..d63b1fa78b
--- /dev/null
+++ b/content/images/pattern-slider.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/content/images/pattern-spinbutton.svg b/content/images/pattern-spinbutton.svg
new file mode 100644
index 0000000000..cd1c58f008
--- /dev/null
+++ b/content/images/pattern-spinbutton.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/content/images/pattern-switch.svg b/content/images/pattern-switch.svg
new file mode 100644
index 0000000000..f2d2c170a0
--- /dev/null
+++ b/content/images/pattern-switch.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/content/images/pattern-table.svg b/content/images/pattern-table.svg
new file mode 100644
index 0000000000..c86d280200
--- /dev/null
+++ b/content/images/pattern-table.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/content/images/pattern-tabs.svg b/content/images/pattern-tabs.svg
new file mode 100644
index 0000000000..32653c370d
--- /dev/null
+++ b/content/images/pattern-tabs.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/content/images/pattern-toolbar.svg b/content/images/pattern-toolbar.svg
new file mode 100644
index 0000000000..f19d72c3d8
--- /dev/null
+++ b/content/images/pattern-toolbar.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/content/images/pattern-tooltip.svg b/content/images/pattern-tooltip.svg
new file mode 100644
index 0000000000..92198927e1
--- /dev/null
+++ b/content/images/pattern-tooltip.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/content/images/pattern-treegrid.svg b/content/images/pattern-treegrid.svg
new file mode 100644
index 0000000000..7aa19e66b3
--- /dev/null
+++ b/content/images/pattern-treegrid.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/content/images/pattern-treeview.svg b/content/images/pattern-treeview.svg
new file mode 100644
index 0000000000..24de583f0d
--- /dev/null
+++ b/content/images/pattern-treeview.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/content/images/pattern-windowsplitter.svg b/content/images/pattern-windowsplitter.svg
new file mode 100644
index 0000000000..1527dff856
--- /dev/null
+++ b/content/images/pattern-windowsplitter.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/content/images/read-this-first.svg b/content/images/read-this-first.svg
new file mode 100644
index 0000000000..69323df5ed
--- /dev/null
+++ b/content/images/read-this-first.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/content/index/index.html b/content/index/index.html
index ed1778b0c5..94a7885faf 100644
--- a/content/index/index.html
+++ b/content/index/index.html
@@ -620,6 +620,9 @@
The below example demonstrates the Alert Pattern.
Activating the Trigger Alert button causes a message to be inserted into the example alert element.
diff --git a/content/patterns/alertdialog/alertdialog-pattern.html b/content/patterns/alertdialog/alertdialog-pattern.html
index 88de2c6d36..0db8f9fb31 100644
--- a/content/patterns/alertdialog/alertdialog-pattern.html
+++ b/content/patterns/alertdialog/alertdialog-pattern.html
@@ -26,6 +26,7 @@
The below example of a confirmation prompt demonstrates the Alert Dialog Pattern.
It also includes an example of the Alert Pattern to make comparing the experiences provided by the two patterns easy.
diff --git a/content/patterns/breadcrumb/breadcrumb-pattern.html b/content/patterns/breadcrumb/breadcrumb-pattern.html
index 1af0accdfb..61967ffd9a 100644
--- a/content/patterns/breadcrumb/breadcrumb-pattern.html
+++ b/content/patterns/breadcrumb/breadcrumb-pattern.html
@@ -26,6 +26,7 @@
The following examples of the Button Pattern demonstrate a new JavaScript syntax for coding ARIA attributes.
The JavaScript for the example buttons on this page uses the IDL Interface defined in ARIA 1.2.
diff --git a/content/patterns/carousel/carousel-pattern.html b/content/patterns/carousel/carousel-pattern.html
index 6dd1c48a93..996c8e7257 100644
--- a/content/patterns/carousel/carousel-pattern.html
+++ b/content/patterns/carousel/carousel-pattern.html
@@ -54,6 +54,7 @@
About This Pattern
+
Examples
Auto-Rotating Image Carousel with Buttons for Slide Control: A basic image carousel that demonstrates the accessibility features necessary for carousels that rotate automatically on page load and also enables users to choose which slide is displayed with buttons for previous and next slide.
Auto-Rotating Image Carousel Example with Buttons for Slide Control
About This Example
+
The following example implementation of the Carousel Pattern demonstrates features of the pattern that are essential to accessibility for carousels that automatically start rotating when the page loads.
For instance, rotation stops when users either move focus into the carousel or hover the mouse over carousel content, and users can manually control which slide is displayed with previous and next slide buttons.
diff --git a/content/patterns/carousel/examples/carousel-2-tablist.html b/content/patterns/carousel/examples/carousel-2-tablist.html
index 8ce007379b..d3a734e9eb 100644
--- a/content/patterns/carousel/examples/carousel-2-tablist.html
+++ b/content/patterns/carousel/examples/carousel-2-tablist.html
@@ -29,6 +29,7 @@
Auto-Rotating Image Carousel with Tabs for Slide Control Example
About This Example
+
The following example implementation of the Carousel Pattern demonstrates features of the pattern that are essential to accessibility for carousels that automatically start rotating when the page loads.
This example also illustrates how to use the tabs pattern to provide users with a way to skip slides in the sequence by directly choosing which one to view.
diff --git a/content/patterns/checkbox/checkbox-pattern.html b/content/patterns/checkbox/checkbox-pattern.html
index 53d9f8e0bd..e651646c46 100644
--- a/content/patterns/checkbox/checkbox-pattern.html
+++ b/content/patterns/checkbox/checkbox-pattern.html
@@ -40,6 +40,7 @@
This example demonstrates using the Checkbox Pattern to create a tri-state, or mixed-state, checkbox.
In this implementation, the mixed-state checkbox represents the state of a set of standard HTML checkboxes.
diff --git a/content/patterns/checkbox/examples/checkbox.html b/content/patterns/checkbox/examples/checkbox.html
index edab7e2492..b473db021e 100644
--- a/content/patterns/checkbox/examples/checkbox.html
+++ b/content/patterns/checkbox/examples/checkbox.html
@@ -29,6 +29,7 @@
Checkbox Example (Two State)
About This Example
+
This example implements the Checkbox Pattern for a two state checkbox using div elements.
Editable Combobox With Both List and Inline Autocomplete Example
About This Example
+
The below combobox for choosing the name of a US state or territory demonstrates the Combobox Pattern.
The design pattern describes four types of autocomplete behavior.
@@ -143,7 +144,7 @@
Accessibility Features
To help people with visual impairments identify the combobox as an interactive element, the cursor is changed to a pointer when hovering over the combobox or 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.
- Note: Because transparent borders are visible on some systems with operating system high contrast settings enabled, transparency cannot be used to create a visual difference between the element that is focused an other elements.
+ Note: Because transparent borders are visible on some systems with operating system high contrast settings enabled, transparency cannot be used to create a visual difference between the element that is focused and other elements.
Instead of using transparency, the focused element has a thicker border and less padding.
When an element receives focus, its border changes from zero to two pixels and padding is reduced by two pixels.
When an element loses focus, its border changes from two pixels to two and padding is increased by two pixels.
diff --git a/content/patterns/combobox/examples/combobox-autocomplete-list.html b/content/patterns/combobox/examples/combobox-autocomplete-list.html
index eff7b1eea2..c6ed9033b5 100644
--- a/content/patterns/combobox/examples/combobox-autocomplete-list.html
+++ b/content/patterns/combobox/examples/combobox-autocomplete-list.html
@@ -29,6 +29,7 @@
Editable Combobox With List Autocomplete Example
About This Example
+
The below combobox for choosing the name of a US state or territory demonstrates the Combobox Pattern.
The design pattern describes four types of autocomplete behavior.
@@ -143,7 +144,7 @@
Accessibility Features
To help people with visual impairments identify the combobox as an interactive element, the cursor is changed to a pointer when hovering over the combobox or 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.
- Note: Because transparent borders are visible on some systems with operating system high contrast settings enabled, transparency cannot be used to create a visual difference between the element that is focused an other elements.
+ Note: Because transparent borders are visible on some systems with operating system high contrast settings enabled, transparency cannot be used to create a visual difference between the element that is focused and other elements.
Instead of using transparency, the focused element has a thicker border and less padding.
When an element receives focus, its border changes from zero to two pixels and padding is reduced by two pixels.
When an element loses focus, its border changes from two pixels to two and padding is increased by two pixels.
diff --git a/content/patterns/combobox/examples/combobox-autocomplete-none.html b/content/patterns/combobox/examples/combobox-autocomplete-none.html
index 7cb5c1aef3..a4a2df7350 100644
--- a/content/patterns/combobox/examples/combobox-autocomplete-none.html
+++ b/content/patterns/combobox/examples/combobox-autocomplete-none.html
@@ -29,6 +29,7 @@
Editable Combobox without Autocomplete Example
About This Example
+
The below combobox that enables users to choose a term from a hypothetical list of previously searched terms demonstrates the Combobox Pattern.
The design pattern describes four types of autocomplete behavior.
@@ -96,7 +97,7 @@
Accessibility Features
To help people with visual impairments identify the combobox as an interactive element, the cursor is changed to a pointer when hovering over the combobox or 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.
- Note: Because transparent borders are visible on some systems with operating system high contrast settings enabled, transparency cannot be used to create a visual difference between the element that is focused an other elements.
+ Note: Because transparent borders are visible on some systems with operating system high contrast settings enabled, transparency cannot be used to create a visual difference between the element that is focused and other elements.
Instead of using transparency, the focused element has a thicker border and less padding.
When an element receives focus, its border changes from zero to two pixels and padding is reduced by two pixels.
When an element loses focus, its border changes from two pixels to two and padding is increased by two pixels.
diff --git a/content/patterns/combobox/examples/combobox-datepicker.html b/content/patterns/combobox/examples/combobox-datepicker.html
index 9869c83fc0..f36df85ea9 100644
--- a/content/patterns/combobox/examples/combobox-datepicker.html
+++ b/content/patterns/combobox/examples/combobox-datepicker.html
@@ -30,6 +30,7 @@
Date Picker Combobox Example
About This Example
+
The below date picker demonstrates an implementation of the Combobox Pattern that opens a dialog.
The date picker dialog is opened by activating the choose date button or by moving keyboard focus to the combobox and pressing Down Arrow or Alt + Down Arrow.
diff --git a/content/patterns/combobox/examples/combobox-select-only.html b/content/patterns/combobox/examples/combobox-select-only.html
index 4fce2109bc..4768c75a9e 100644
--- a/content/patterns/combobox/examples/combobox-select-only.html
+++ b/content/patterns/combobox/examples/combobox-select-only.html
@@ -29,6 +29,7 @@
Select-Only Combobox Example
About This Example
+
The following example implementation of the Combobox Pattern demonstrates a single-select combobox widget that is functionally similar to an HTML select element.
Unlike the editable combobox examples, this select-only combobox is not made with an <input> element, and it does not accept freeform user input.
diff --git a/content/patterns/combobox/examples/css/combobox-autocomplete.css b/content/patterns/combobox/examples/css/combobox-autocomplete.css
index 72f0f113d6..cef393bd3b 100644
--- a/content/patterns/combobox/examples/css/combobox-autocomplete.css
+++ b/content/patterns/combobox/examples/css/combobox-autocomplete.css
@@ -13,7 +13,7 @@
background-color: white;
color: black;
box-sizing: border-box;
- height: 24px;
+ height: 30px;
padding: 0;
margin: 0;
vertical-align: bottom;
@@ -46,7 +46,7 @@ ul[role="listbox"] {
padding: 0;
position: absolute;
left: 4px;
- top: 28px;
+ top: 34px;
list-style: none;
background-color: white;
display: none;
diff --git a/content/patterns/combobox/examples/css/grid-combo.css b/content/patterns/combobox/examples/css/grid-combo.css
index 5484f8f7b4..8c86a4f3be 100644
--- a/content/patterns/combobox/examples/css/grid-combo.css
+++ b/content/patterns/combobox/examples/css/grid-combo.css
@@ -23,7 +23,7 @@
margin: 0;
padding: 0;
position: absolute;
- top: 1.7em;
+ top: auto;
z-index: 1;
}
diff --git a/content/patterns/combobox/examples/grid-combo.html b/content/patterns/combobox/examples/grid-combo.html
index e424915932..87a2b587f3 100644
--- a/content/patterns/combobox/examples/grid-combo.html
+++ b/content/patterns/combobox/examples/grid-combo.html
@@ -31,6 +31,7 @@
Editable Combobox with Grid Popup Example
About This Example
+
The following example combobox implements the combobox pattern using a grid for the suggested values popup.
diff --git a/content/patterns/combobox/examples/js/select-only.js b/content/patterns/combobox/examples/js/select-only.js
index fdf5874a81..7afa863158 100644
--- a/content/patterns/combobox/examples/js/select-only.js
+++ b/content/patterns/combobox/examples/js/select-only.js
@@ -195,6 +195,7 @@ Select.prototype.init = function () {
// add event listeners
this.comboEl.addEventListener('blur', this.onComboBlur.bind(this));
+ this.listboxEl.addEventListener('focusout', this.onComboBlur.bind(this));
this.comboEl.addEventListener('click', this.onComboClick.bind(this));
this.comboEl.addEventListener('keydown', this.onComboKeyDown.bind(this));
@@ -239,10 +240,9 @@ Select.prototype.getSearchString = function (char) {
return this.searchString;
};
-Select.prototype.onComboBlur = function () {
- // do not do blur action if ignoreBlur flag has been set
- if (this.ignoreBlur) {
- this.ignoreBlur = false;
+Select.prototype.onComboBlur = function (event) {
+ // do nothing if relatedTarget is contained within listboxEl
+ if (this.listboxEl.contains(event.relatedTarget)) {
return;
}
diff --git a/content/patterns/dialog-modal/dialog-modal-pattern.html b/content/patterns/dialog-modal/dialog-modal-pattern.html
index 71fdeefd61..68d8829ed6 100644
--- a/content/patterns/dialog-modal/dialog-modal-pattern.html
+++ b/content/patterns/dialog-modal/dialog-modal-pattern.html
@@ -36,6 +36,7 @@
About This Pattern
+
Examples
Modal Dialog Example: Demonstrates multiple layers of modal dialogs with both small and large amounts of content.
The example below includes a date input field and a button that opens a date picker that implements the Dialog (Modal) Pattern.
The dialog contains a calendar that uses the grid pattern to present buttons that enable the user to choose a day from the calendar.
diff --git a/content/patterns/dialog-modal/examples/dialog.html b/content/patterns/dialog-modal/examples/dialog.html
index 56a5a0d549..7f9c38ba6d 100644
--- a/content/patterns/dialog-modal/examples/dialog.html
+++ b/content/patterns/dialog-modal/examples/dialog.html
@@ -30,6 +30,7 @@
Modal Dialog Example
About This Example
+
Following is an example implementation of the Dialog (Modal) Pattern.
The below Add Delivery Address button opens a modal dialog that contains two buttons that open other dialogs.
diff --git a/content/patterns/disclosure/disclosure-pattern.html b/content/patterns/disclosure/disclosure-pattern.html
index 800fde84c1..5b20b6182d 100644
--- a/content/patterns/disclosure/disclosure-pattern.html
+++ b/content/patterns/disclosure/disclosure-pattern.html
@@ -27,6 +27,7 @@
Example Disclosure (Show/Hide) for Answers to Frequently Asked Questions
About This Example
+
The following example demonstrates using the Disclosure Pattern to create a set of frequently asked questions where the answers may be independently shown or hidden.
@@ -106,7 +107,7 @@
Accessibility Features
To help people with visual impairments identify the disclosure as interactive and make it easier to perceive that clicking either the disclosure button or its label changes the expanded state, when a pointer hovers over the button or its label, the background color changes, a border appears, and the cursor changes to a pointer.
- Because transparent borders are visible on some systems with operating system high contrast settings enabled, transparency cannot be used to create a visual difference between the element that is focused an other elements.
+ Because transparent borders are visible on some systems with operating system high contrast settings enabled, transparency cannot be used to create a visual difference between the element that is focused and other elements.
Instead of using transparency, the focused element has a thicker border and less padding.
When an element receives focus, its border changes from 0 to 2 pixels and padding is reduced by 2 pixels.
When an element loses focus, its border changes from 2 pixels to 0 and padding is increased by 2 pixels.
diff --git a/content/patterns/disclosure/examples/disclosure-image-description.html b/content/patterns/disclosure/examples/disclosure-image-description.html
index 5f7b181784..76f7c835a5 100644
--- a/content/patterns/disclosure/examples/disclosure-image-description.html
+++ b/content/patterns/disclosure/examples/disclosure-image-description.html
@@ -29,6 +29,7 @@
Example Disclosure (Show/Hide) for Image Description
About This Example
+
The following example demonstrates using the Disclosure Pattern to provide a way of revealing a table of data that complements an image.
@@ -249,7 +250,7 @@
Accessibility Features
To help people with visual impairments identify the disclosure as interactive and make it easier to perceive that clicking either the disclosure button or its label changes the expanded state, when a pointer hovers over the button or its label, the background color changes, a border appears, and the cursor changes to a pointer.
- Because transparent borders are visible on some systems with operating system high contrast settings enabled, transparency cannot be used to create a visual difference between the element that is focused an other elements.
+ Because transparent borders are visible on some systems with operating system high contrast settings enabled, transparency cannot be used to create a visual difference between the element that is focused and other elements.
Instead of using transparency, the focused element has a thicker border and less padding.
When an element receives focus, its border changes from 0 to 2 pixels and padding is reduced by 2 pixels.
When an element loses focus, its border changes from 2 pixels to 0 and padding is increased by 2 pixels.
diff --git a/content/patterns/disclosure/examples/disclosure-navigation-hybrid.html b/content/patterns/disclosure/examples/disclosure-navigation-hybrid.html
index 22f14b98ac..31390dbc87 100644
--- a/content/patterns/disclosure/examples/disclosure-navigation-hybrid.html
+++ b/content/patterns/disclosure/examples/disclosure-navigation-hybrid.html
@@ -38,7 +38,7 @@
The following example demonstrates using the Disclosure Pattern to show and hide dropdown lists of links in a navigation bar for a mythical university web site.
Unlike the other disclosure navigation menu example, this example includes top-level links alongside the disclosure buttons.
diff --git a/content/patterns/disclosure/examples/disclosure-navigation.html b/content/patterns/disclosure/examples/disclosure-navigation.html
index 31f4a59416..75d6c4405e 100644
--- a/content/patterns/disclosure/examples/disclosure-navigation.html
+++ b/content/patterns/disclosure/examples/disclosure-navigation.html
@@ -38,6 +38,7 @@
The following example demonstrates using the Disclosure Pattern to show and hide dropdown lists of links in a navigation bar for a mythical university web site.
Each disclosure button represents a section of the web site, and expanding it shows a list of links to pages within that section.
diff --git a/content/patterns/feed/examples/feed.html b/content/patterns/feed/examples/feed.html
index b83a5a06b4..27eb8bd6b8 100644
--- a/content/patterns/feed/examples/feed.html
+++ b/content/patterns/feed/examples/feed.html
@@ -25,6 +25,7 @@
Infinite Scrolling Feed Example
About This Example
+
NOTE: The feed role is a new WAI-ARIA feature, introduced by WAI-ARIA 1.1.
This page provides a proposed implementation of a feed component.
@@ -205,8 +206,8 @@
Role, Property, State, and Tabindex Attributes
JavaScript and CSS Source Code
The following Javascript and CSS is used by the feed-display.html page:
Following are three example implementations of the Grid Pattern that demonstrate the keyboard interactions and ARIA features that enable accessible, interactive presentation of tabular information.
Each of the following three grids presents a set of financial transactions.
diff --git a/content/patterns/grid/examples/layout-grids.html b/content/patterns/grid/examples/layout-grids.html
index 7034aaf57a..2f8d4c8007 100644
--- a/content/patterns/grid/examples/layout-grids.html
+++ b/content/patterns/grid/examples/layout-grids.html
@@ -31,6 +31,7 @@
Layout Grid Examples
About This Example
+
The following examples demonstrate how the Grid Pattern can be used to group a collection of interactive widgets into a single tab stop.
In these examples, each widget, such as a link or button, is in a separate cell of the grid, and the user can navigate between them with the arrow keys.
diff --git a/content/patterns/grid/grid-pattern.html b/content/patterns/grid/grid-pattern.html
index 5a61895fe1..e03f6b969e 100644
--- a/content/patterns/grid/grid-pattern.html
+++ b/content/patterns/grid/grid-pattern.html
@@ -52,6 +52,7 @@
About This Pattern
+
Examples
Layout Grid Examples: Three example implementations of grids that are used to lay out widgets, including a collection of navigation links, a message recipients list, and a set of search results.
Landmark roles can be nested to identify parent/child relationships of the information being presented.
+
+ Note that wrapping the content of a modal dialog in a landmark region is unnecessary.
+ A landmark that wraps modal content cannot provide any benefit to users because it is not perceivable unless the modal is open.
+ In addition, when a modal is open, a landmark containing its content is superfluous because the modal itself is a container that provides both a name and boundaries.
+
The examples below demonstrate three variations of the Link Pattern.
The link pattern is used when it is necessary for elements other than the HTML a element to have link behaviors.
diff --git a/content/patterns/link/link-pattern.html b/content/patterns/link/link-pattern.html
index 8f80e94e99..0291fdb235 100644
--- a/content/patterns/link/link-pattern.html
+++ b/content/patterns/link/link-pattern.html
@@ -31,6 +31,7 @@
note
+
Examples
Link Examples: Link widgets constructed from HTML span and img elements.
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..8e0c52866a 100644
--- a/content/patterns/listbox/examples/listbox-collapsible.html
+++ b/content/patterns/listbox/examples/listbox-collapsible.html
@@ -15,7 +15,6 @@
-
@@ -38,8 +37,9 @@
- 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 +98,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:
-
-
If Up Arrow or Down Arrow is pressed, the previous or next option is scrolled into view.
-
If Home or End is pressed, the listbox scrolls all the way to the top or to the bottom.
-
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.
-
If the mouse is clicked on a partially visible option, it will be scrolled fully into 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.
+
-
When a fully visible option is focused in any way, no scrolling occurs.
-
+
@@ -124,6 +123,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 +137,15 @@
Keyboard Support
+
+
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 +216,7 @@
Role, Property, State, and Tabindex Attributes
-
aria-labelledby="ID_REF1 ID_REF2"
+
aria-labelledby="ID_REF1 ID_REF2"
button
@@ -214,13 +228,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 +251,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 +268,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.
The following example implementation of the Listbox Pattern demonstrates a single-select listbox widget with grouped options.
This widget is functionally similar to an HTML select element with size greater than 1 and options grouped into categories with labeled optgroup elements.
@@ -54,59 +54,97 @@
Example
Land
-
Cat
-
Dog
-
Tiger
-
Reindeer
-
Raccoon
+
+
+ Cat
+
+
+
+ Dog
+
+
+
+ Tiger
+
+
+
+ Reindeer
+
+
+
+ Raccoon
+
-
Water
-
Dolphin
-
Flounder
-
Eel
+
+
+ Water
+
+
+
+ Dolphin
+
+
+
+ Flounder
+
+
+
+ Eel
+
Air
-
Falcon
-
Winged Horse
-
Owl
+
+
+ Falcon
+
+
+
+ Winged Horse
+
+
+
+ Owl
+
-
Notes
-
This listbox is scrollable; it has more options than its height can accommodate.
-
-
- Scrolling only works as expected if the listbox is the options' offsetParent.
- The example uses position: relative on the listbox to that effect.
-
+
+
+
+
+
Accessibility Features
+
- When an option is focused that isn't (fully) visible, the listbox's scroll position is updated:
-
-
If Up Arrow or Down Arrow is pressed, the previous or next option is scrolled into view.
-
If Home or End is pressed, the listbox scrolls all the way to the top or to the bottom.
-
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.
-
If the mouse is clicked on a partially visible option, it will be scrolled fully into view.
-
+ 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 +153,10 @@
Keyboard Support
+
+
Tab
+
Moves focus into and out of the listbox.
+
Down Arrow
Moves focus to and selects the next option.
@@ -131,6 +173,15 @@
Keyboard Support
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 +210,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.
Refers to the element containing the option group label.
@@ -201,7 +256,7 @@
Role, Property, State, and Tabindex Attributes
-
aria-selected="true"
+
aria-selected="true"
li
@@ -211,6 +266,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.
+
The following two example implementations of the Listbox Pattern demonstrate differences between single-select and multi-select functionality.
In both examples, users can use action buttons to move options from one list to another.
@@ -59,56 +59,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
-
-
- Assistive technologies are told which option in the list is visually focused by the value of aria-activedescendant:
-
-
DOM focus remains on the listbox element.
-
When a key that moves focus is pressed or an option is clicked, JavaScript changes the value of aria-activedescendant on the listbox element.
-
If the listbox element does not contain any options, aria-activedescendant does not have a value.
-
-
-
- When Tab moves focus into either listbox:
-
-
If none of the options are selected, the first option receives focus.
-
If an option is selected, the selected option receives focus.
-
-
-
Only one option may be selected at a time (have aria-selected="true").
-
- 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.
-
-
@@ -121,73 +154,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
-
-
- Like in example 1, assistive technologies are told which option in the list is visually focused by the value of aria-activedescendant:
-
-
DOM focus remains on the listbox element.
-
When a key that moves focus is pressed or an option is clicked, JavaScript changes the value of aria-activedescendant on the listbox element.
-
If the listbox element does not contain any options, aria-activedescendant does not have a value.
-
-
-
- When Tab moves focus into either listbox:
-
-
If none of the options are selected, focus is set on the first option.
-
If one or more options are selected, focus is set on the first selected option.
-
-
-
- Unlike example 1, more than one option may be selected at a time (have aria-selected="true").
-
-
The multi-select capability is communicated to assistive technologies by setting aria-multiselectable="true" on the listbox element.
-
All option elements have a value set for aria-selected.
-
Selected options have aria-selected set to true and all others have it set to false.
-
Keys that move focus do not change the selected state of an option.
-
-
-
Users can toggle the selected state of the focused option with Space or click.
-
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 +256,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.
-
+
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.
Live regions provide confirmation of completed actions.
-
+
+ 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 +284,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 +298,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 +346,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.
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 +453,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="".
+ 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.
+
The following example implementation of the Listbox Pattern demonstrates a scrollable single-select listbox widget.
This widget is functionally similar to an HTML select input where the size attribute has a value greater than one.
@@ -53,67 +53,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.
-
-
- Scrolling only works as expected if the listbox is the options' offsetParent.
- The example uses position: relative on the listbox to that effect.
-
+
+
+
+
Accessibility Features
+
- When an option is focused that isn't (fully) visible, the listbox's scroll position is updated:
-
-
If Up Arrow or Down Arrow is pressed, the previous or next option is scrolled into view.
-
If Home or End is pressed, the listbox scrolls all the way to the top or to the bottom.
-
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.
-
If the mouse is clicked on a partially visible option, it will be scrolled fully into view.
-
+ 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 +201,10 @@
Keyboard Support
+
+
Tab
+
Moves focus into and out of the listbox.
+
Down Arrow
Moves focus to and selects the next option.
@@ -138,6 +221,15 @@
Keyboard Support
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 +237,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 +258,29 @@
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.
+ 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.
+
Scrollable Listbox Example: Single-select listbox that scrolls to reveal more options, similar to HTML select with size attribute greater than one.
diff --git a/content/patterns/menu-button/examples/js/menu-button-actions-active-descendant.js b/content/patterns/menu-button/examples/js/menu-button-actions-active-descendant.js
index 35472f1e00..a1165150d5 100644
--- a/content/patterns/menu-button/examples/js/menu-button-actions-active-descendant.js
+++ b/content/patterns/menu-button/examples/js/menu-button-actions-active-descendant.js
@@ -162,9 +162,9 @@ class MenuButtonActionsActiveDescendant {
closePopup() {
if (this.isOpen()) {
- this.buttonNode.removeAttribute('aria-expanded');
+ this.buttonNode.setAttribute('aria-expanded', 'false');
this.menuNode.setAttribute('aria-activedescendant', '');
- for (var i = 0; i < this.menuitemNodes.length; i++) {
+ for (let i = 0; i < this.menuitemNodes.length; i++) {
this.menuitemNodes[i].classList.remove('focus');
}
this.menuNode.style.display = 'none';
diff --git a/content/patterns/menu-button/examples/js/menu-button-actions.js b/content/patterns/menu-button/examples/js/menu-button-actions.js
index 7f81486f5f..cd69d5621f 100644
--- a/content/patterns/menu-button/examples/js/menu-button-actions.js
+++ b/content/patterns/menu-button/examples/js/menu-button-actions.js
@@ -156,7 +156,7 @@ class MenuButtonActions {
closePopup() {
if (this.isOpen()) {
- this.buttonNode.removeAttribute('aria-expanded');
+ this.buttonNode.setAttribute('aria-expanded', 'false');
this.menuNode.style.display = 'none';
}
}
diff --git a/content/patterns/menu-button/examples/js/menu-button-links.js b/content/patterns/menu-button/examples/js/menu-button-links.js
index 90f4146da1..757aac2268 100644
--- a/content/patterns/menu-button/examples/js/menu-button-links.js
+++ b/content/patterns/menu-button/examples/js/menu-button-links.js
@@ -153,7 +153,7 @@ class MenuButtonLinks {
closePopup() {
if (this.isOpen()) {
- this.buttonNode.removeAttribute('aria-expanded');
+ this.buttonNode.setAttribute('aria-expanded', 'false');
this.menuNode.style.display = 'none';
}
}
diff --git a/content/patterns/menu-button/examples/menu-button-actions-active-descendant.html b/content/patterns/menu-button/examples/menu-button-actions-active-descendant.html
index 5994211646..1fbd72bbcd 100644
--- a/content/patterns/menu-button/examples/menu-button-actions-active-descendant.html
+++ b/content/patterns/menu-button/examples/menu-button-actions-active-descendant.html
@@ -29,6 +29,7 @@
Actions Menu Button Example Using aria-activedescendant
About This Example
+
This example demonstrates how the Menu Button Pattern can be used to create a button that opens an actions menu.
In this example, choosing an action from the menu will cause the chosen action to be displayed in the Last Action edit box.
@@ -51,7 +52,7 @@