Merge pull request #103 from a11y-tools/main

Regions can only be included in the list of landmarks if they have an accessible name

README.md

@@ -22,14 +22,15 @@ The SkipTo script creates a drop-down menu consisting of the links to important
 
 ## Websites using SkipTo
 
-There are two main ways to include the menu button for SkipTo in a page.  In the default configuration the menu button is always visible making it useful to everyone to easily find and navigate to the important content regions identified by the author.  This is similar to how curb cuts help more than just people using wheelchairs.  It is also easier for people using voice recognition to activate the button using the "click skip to content" command and use similar voice commands to activate SkipTo menu items.  The "popup" option is the more traditional approach to fulfilling the "[bypass bocks](https://www.w3.org/TR/WCAG/#bypass-blocks)" requirement of the [Web Content Accessibility Guidelines](https://www.w3.org/TR/WCAG/), but this option makes the feature less visible to people who might benefit.
+There are two main ways to use the menu button for SkipTo in a page.  In the default configuration the menu button is always visible making it useful to everyone to easily find and navigate to the important content regions identified by the author.  This is similar to how curb cuts help more than just people using wheelchairs.  It is also easier for people using voice recognition to activate the button using the "click skip to content" command and use similar voice commands to activate SkipTo menu items.  The "popup" option is the more traditional approach to fulfilling the "[bypass bocks](https://www.w3.org/TR/WCAG/#bypass-blocks)" requirement of the [Web Content Accessibility Guidelines](https://www.w3.org/TR/WCAG/), but this option makes the feature less visible to people who might benefit.
 
 ### Visible Menu Button (default)
 * [DRES Accessible IT Group](https://accessibleit.disability.illinois.edu/)
 * [College of Applied Health Sciences](https://ahs.illinois.edu/)
 * [Illinois Webcon](https://webcon.illinois.edu/)
 
 ### Popup Menu Button
+* [Admissions at the University of Illinois](https://admissions.illinois.edu/)
 * [Nightingale Design Research](https://nightingaledesignresearch.com)
 * [cPanel Web Hosting Service @ Illinois](http://cpanel.web.illinois.edu)
 * [Functional Accessibility Evaluator (FAE)](https://fae.disability.illinois.edu/)
@@ -39,7 +40,7 @@ NOTE: Popup menu button option is available through configuration of SkipTo when
 
 ## How it works
 
-1. The SkipTo menu button should be the first tabable element on the page, and if it is configured not to be visible when the page is loaded, the menu button becomes visible when it receives focus.
+1. The SkipTo menu button should be the first tabable element on the page, and by default the button is visible, but can be configured to "popup" when the button becomes receives focus.
 2. Once the keyboard focus is on the menu button, pressing the ENTER, SPACE, DOWN ARROW or UP ARROW keys will pull down the list of important landmarks and headings on the page.  The button is based on the ARIA Authoring Practice [design pattern for menu button](https://w3c.github.io/aria-practices/#menubutton).
 3. Use arrow keys to select your choice and press ENTER to move focus to the section of the page.
 4. If you decide to reach the menu again, simply press the built-in access key (0 by default). See the notes on [Access keys](#access-keys) for More information on how to use them.
@@ -52,7 +53,7 @@ Access keys work  just like regular shortcut keys except that they need a browse
 * Google Chrome and Opera -- Alt+0 (Windows or Linux) and Control+Option+0 (Mac OS).
 * Safari -- Control+Option+0 (MacOS).
 
-NOTE: Browsers on iOS and iPadOS devices support `accesskey`s to move focus to the menu button, but do not support the menu button keyboard commands to use the menu at this time.  Browsers on Android devices do not support `accesskey`s at this time.
+NOTE: Browsers on iOS and iPadOS devices support `accesskey` to move focus to the menu button, but do not support the menu button keyboard commands to use the menu at this time.  Browsers on Android devices do not support `accesskey`s at this time.
 
 ## Adding to Website
 
@@ -77,10 +78,6 @@ The easiest way is to include a reference to `skipto.min.js`  on your HTML page
 
 NOTE: CDN referenced files may not be available to computers behind firewall protected networks.
 
-### What About WordPress?
-
-A module is under development for WordPress.
-
 ### What About Joomla?
 
 Joomla 4.0 includes **skipto** as a default plugin
@@ -117,14 +114,14 @@ The following options are useful for identify where the menu will be in the DOM
 
 ### CSS Selectors for identifying Landmarks and Headings
 
-The `landmarks` and 'headings' options are CSS selectors used to identify the important landmarks and headings on the page for the purpose of keyboard navigation.  The list of landmarks and headings should be relatively short, the more items the menu contains the more time the user will need to scan and navigate to the section they want to "skip to".
+The `landmarks` and 'headings' options are CSS selectors used to identify the important landmarks and headings on the page for the purpose of keyboard navigation.  The list of landmarks and headings should be **relatively short**, the more items the menu contains the more time the user will need to scan and navigate to the section they want to "skip to".
 
 The options are of type `string`.
 
 | Property       | Default | Description |
 | :------------- | :------ | :---------- |
-| `landmarks` | 'main, [role="main"], [role="search"], nav, [role="navigation"], aside, [role="complementary"]' | A set of CSS selectors used by `querySelectorAll` to get an array of landmark nodes. |
-| `headings` | 'main h1, [role="main"] h1, main h2, [role="main"] h2' | A set of CSS selectors used by `querySelectorAll` to get an array of headings nodes. |
+| `landmarks` | 'main, [role="main"], [role="search"], nav, [role="navigation"], aside, [role="complementary"]' | A set of CSS selectors used by `querySelectorAll` to get an array of landmark elements. |
+| `headings` | 'main h1, [role="main"] h1, main h2, [role="main"] h2' | A set of CSS selectors used by `querySelectorAll` to get an array of heading elements. |
 
 ### Color Theme Options
 
@@ -225,8 +222,6 @@ The labels and messages can be localized for specific languages or updated to re
 | `actionShowImportantLandmarksAriaLabel` | 'Show $num Important landmarks' | The `aria-label` for the menu item when the button action is to show "Important" landmarks. |
 | `actionShowAllLandmarksAriaLabel` | 'Show All $num landmarks'  | The `aria-label` for the menu item when the button action is to show "All" landmarks. |
 
-
-
 ## Example Settings
 
 If have different requirements for your web site and include other heading levels as well as ARIA landmarks, you will need to provide a JSON object containing the necessary configuration parameters. The following is a sample configuration:
@@ -412,6 +407,13 @@ Happy skipping!
 
 ## Version History
 
+### Version 4.1.3
+* Region landmarks must have an accessible name to be included as a landmark in the SkipTo menu to comply with ARIA specification for landmark regions, and will region landmarks be included after complementary landmarks in the SkipTo menu.
+* Updated landmark prefixes in menu to align with actual ARIA role names with the following changes:
+  * `header:` => `banner`
+  * `footer:` => `contentinfo`
+  * `aside:` => `complementary`
+
 ### Version 4.1.2
 * Added <code>aria-busy="true"</code> attribute to menu element when SkipTo is initialized and being updated with new menu items to support validators looking for required menu items for the <code>menu</code> role.
 * Added the <em>optional</em> <code>aria-controls</code> attribute to button element to reference the <code>id</code> of the menu element as defined in the W3C ARIA Authoring practices for [menu button pattern](https://w3c.github.io/aria-practices/#menubutton).

compiled/js/skipto.js

@@ -1,4 +1,4 @@
-/*! skipto - v4.1.2 - 2021-09-17
+/*! skipto - v4.1.3 - 2021-10-08
 * https://github.com/paypal/skipto
 * Copyright (c) 2021 PayPal Accessibility Team and University of Illinois; Licensed BSD */
  /*@cc_on @*/
@@ -67,9 +67,9 @@
       searchLabel: 'search',
       navLabel: 'navigation',
       regionLabel: 'region',
-      asideLabel: 'aside',
-      footerLabel: 'footer',
-      headerLabel: 'header',
+      asideLabel: 'complementary',
+      footerLabel: 'contentinfo',
+      headerLabel: 'banner',
       formLabel: 'form',
       msgNoLandmarksFound: 'No landmarks found',
       msgNoHeadingsFound: 'No headings found',
@@ -1324,6 +1324,7 @@
         case 'nav':
           n = this.config.navLabel;
           break;
+        case 'section':
         case 'region':
           n = this.config.regionLabel;
           break;
@@ -1410,8 +1411,8 @@
             case 'navigation':
               tagName = 'nav';
               break;
-            case 'section':
-              tagName = 'region';
+            case 'region':
+              tagName = 'section';
               break;
             case 'search':
               tagName = 'search';
@@ -1420,7 +1421,7 @@
               break;
           }
           // if using ID for selectQuery give tagName as main
-          if (['aside', 'footer', 'form', 'header', 'main', 'nav', 'region', 'search'].indexOf(tagName) < 0) {
+          if (['aside', 'footer', 'form', 'header', 'main', 'nav', 'section', 'search'].indexOf(tagName) < 0) {
             tagName = 'main';
           }
           if (landmark.hasAttribute('aria-roledescription')) {
@@ -1435,6 +1436,7 @@
           var landmarkItem = {};
           landmarkItem.dataId = dataId.toString();
           landmarkItem.class = 'landmark';
+          landmarkItem.hasName = name.length > 0;
           landmarkItem.name = this.getLocalizedLandmarkName(tagName, name);
           landmarkItem.tagName = tagName;
           landmarkItem.nestingLevel = 0;
@@ -1443,6 +1445,7 @@
           }
           this.skipToIdIndex += 1;
           allLandmarks.push(landmarkItem);
+
           // For sorting landmarks into groups
           switch (tagName) {
             case 'main':
@@ -1460,8 +1463,11 @@
             case 'footer':
               footerElements.push(landmarkItem);
               break;
-            case 'region':
-              regionElements.push(landmarkItem);
+            case 'section':
+              // Regions must have accessible name to be included
+              if (landmarkItem.hasName) {
+                regionElements.push(landmarkItem);
+              }
               break;
             default:
               otherElements.push(landmarkItem);
@@ -1472,7 +1478,7 @@
       if (allFlag) {
         return allLandmarks;
       }
-      return [].concat(mainElements, regionElements, searchElements, navElements, asideElements, footerElements, otherElements);
+      return [].concat(mainElements, searchElements, navElements, asideElements, regionElements, footerElements, otherElements);
     }
   };
   // Initialize skipto menu button with onload event

example/skipTo-ahs.html

@@ -39,6 +39,7 @@ <h2 id="id-test-pages-label">SkipTo Test Pages</h2>
             <li><a href="skipTo-onfocus.html">Popup Menu Button</a></li>
             <li><a href="skipTo-fixed.html">Fixed Menu Button</a></li>
             <li><a href="skipTo-button-title.html">Test Deprecated Title Feature</a></li>
+            <li><a href="skipTo-region-no-name.html">Regions with no accessible name</a></li>
             <li><a href="skipTo-fonts.html">Setting font size and family in configuration</a></li>
         </ul>
     </nav>

example/skipTo-aria.html

@@ -34,6 +34,7 @@ <h2 id="id-test-pages-label">SkipTo Test Pages</h2>
             <li><a href="skipTo-onfocus.html">Popup Menu Button</a></li>
             <li><a href="skipTo-fixed.html">Fixed Menu Button</a></li>
             <li><a href="skipTo-button-title.html">Test Deprecated Title Feature</a></li>
+            <li><a href="skipTo-region-no-name.html">Regions with no accessible name</a></li>
             <li><a href="skipTo-fonts.html">Setting font size and family in configuration</a></li>
         </ul>
     </nav>

example/skipTo-basic.html

@@ -35,6 +35,7 @@ <h2 id="id-test-pages-label">SkipTo Test Pages</h2>
             <li><a href="skipTo-onfocus.html">Popup Menu Button</a></li>
             <li><a href="skipTo-fixed.html">Fixed Menu Button</a></li>
             <li><a href="skipTo-button-title.html">Test Deprecated Title Feature</a></li>
+            <li><a href="skipTo-region-no-name.html">Regions with no accessible name</a></li>
             <li><a href="skipTo-fonts.html">Setting font size and family in configuration</a></li>
         </ul>
     </nav>

example/skipTo-button-title.html

@@ -36,6 +36,7 @@ <h2 id="id-test-pages-label">SkipTo Test Pages</h2>
             <li><a href="skipTo-onfocus.html">Popup Menu Button</a></li>
             <li><a href="skipTo-fixed.html">Fixed Menu Button</a></li>
             <li><a href="skipTo-button-title.html"  aria-current="page">Test Deprecated Title Feature</a></li>
+            <li><a href="skipTo-region-no-name.html">Regions with no accessible name</a></li>
             <li><a href="skipTo-fonts.html">Setting font size and family in configuration</a></li>
         </ul>
     </nav>

example/skipTo-custom.html

@@ -47,6 +47,7 @@ <h2 id="id-test-pages-label">SkipTo Test Pages</h2>
             <li><a href="skipTo-onfocus.html">Popup Menu Button</a></li>
             <li><a href="skipTo-fixed.html">Fixed Menu Button</a></li>
             <li><a href="skipTo-button-title.html">Test Deprecated Title Feature</a></li>
+            <li><a href="skipTo-region-no-name.html">Regions with no accessible name</a></li>
             <li><a href="skipTo-fonts.html">Setting font size and family in configuration</a></li>
         </ul>
     </nav>

example/skipTo-fixed.html

@@ -34,6 +34,7 @@ <h2 id="id-test-pages-label">SkipTo Test Pages</h2>
             <li><a href="skipTo-onfocus.html">Popup Menu Button</a></li>
             <li><a href="skipTo-fixed.html" aria-current="page">Fixed Menu Button</a></li>
             <li><a href="skipTo-button-title.html">Test Deprecated Title Feature</a></li>
+            <li><a href="skipTo-region-no-name.html">Regions with no accessible name</a></li>
             <li><a href="skipTo-fonts.html">Setting font size and family in configuration</a></li>
         </ul>
     </nav>

example/skipTo-fonts.html

@@ -34,6 +34,7 @@ <h2 id="id-test-pages-label">SkipTo Test Pages</h2>
             <li><a href="skipTo-onfocus.html">Popup Menu Button</a></li>
             <li><a href="skipTo-fixed.html">Fixed Menu Button</a></li>
             <li><a href="skipTo-button-title.html">Test Deprecated Title Feature</a></li>
+            <li><a href="skipTo-region-no-name.html">Regions with no accessible name</a></li>
             <li><a href="skipTo-fonts.html" aria-current="page">Setting font size and family in configuration</a></li>
         </ul>
     </nav>

example/skipTo-illinois.html

@@ -36,6 +36,7 @@ <h2 id="id-test-pages-label">SkipTo Test Pages</h2>
             <li><a href="skipTo-onfocus.html">Popup Menu Button</a></li>
             <li><a href="skipTo-fixed.html">Fixed Menu Button</a></li>
             <li><a href="skipTo-button-title.html">Test Deprecated Title Feature</a></li>
+            <li><a href="skipTo-region-no-name.html">Regions with no accessible name</a></li>
             <li><a href="skipTo-fonts.html">Setting font size and family in configuration</a></li>
         </ul>
     </nav>

example/skipTo-no-additional.html

@@ -24,6 +24,7 @@
             <li><a href="skipTo-onfocus.html">Popup Menu Button</a></li>
             <li><a href="skipTo-fixed.html">Fixed Menu Button</a></li>
             <li><a href="skipTo-button-title.html">Test Deprecated Title Feature</a></li>
+            <li><a href="skipTo-region-no-name.html">Regions with no accessible name</a></li>
             <li><a href="skipTo-fonts.html">Setting font size and family in configuration</a></li>
         </ul>
     </nav>

example/skipTo-no-landmarks.html

@@ -22,6 +22,7 @@
             <li><a href="skipTo-onfocus.html">Popup Menu Button</a></li>
             <li><a href="skipTo-fixed.html">Fixed Menu Button</a></li>
             <li><a href="skipTo-button-title.html">Test Deprecated Title Feature</a></li>
+            <li><a href="skipTo-region-no-name.html">Regions with no accessible name</a></li>
             <li><a href="skipTo-fonts.html">Setting font size and family in configuration</a></li>
         </ul>
     </div>

example/skipTo-onfocus.html

@@ -33,6 +33,7 @@ <h2 id="id-test-pages-label">SkipTo Test Pages</h2>
             <li><a href="skipTo-onfocus.html" aria-current="page">Popup Menu Button</a></li>
             <li><a href="skipTo-fixed.html">Fixed Menu Button</a></li>
             <li><a href="skipTo-button-title.html">Test Deprecated Title Feature</a></li>
+            <li><a href="skipTo-region-no-name.html">Regions with no accessible name</a></li>
             <li><a href="skipTo-fonts.html">Setting font size and family in configuration</a></li>
         </ul>
     </nav>