Merge branch 'main' of github.com:PublicisSapient/enable-a11y into al…

…t-carousel

.gitignore

@@ -2,3 +2,6 @@ node_modules
 .DS_Store
 api-cache
 tmp
+
+# auto-gen PHP files/logs
+php_errors.log

.vscode/enable-vs-snippets.code-snippets

@@ -409,5 +409,10 @@
 			"// e.g. expect(domInfo.ariaLabel).not.toBe('');",
 			"expect(domInfo.isOpen).toBe(true);"
 		]
+	},
+	"checkbox-image": {
+		"scope": "",
+		"prefix": "checkbox-image",
+		"body": "<img class=\"compliance-table__icon\" src=\"images/checkmark.svg\" alt=\"required\">"
 	}
 }

README.md

@@ -1,26 +1,23 @@
 # enable-a11y
+
 A list of demos to show how aria roles function with screen readers.
 
 ## Set up
-Nvm: https://github.com/nvm-sh/nvm#usage
-npm: https://docs.npmjs.com/downloading-and-installing-node-js-and-npm
-vnu: https://www.npmjs.com/package/vnu-jar
-lynx
-php
-npm install -g less-watch-compiler
-
-MAMP (OSX) or apache:
-https://www.mamp.info/en/mac/
-
-LAMP (Linux):
-https://www.linux.com/training-tutorials/easy-lamp-server-installation/
 
+nvm: https://github.com/nvm-sh/nvm#usage  
+npm: https://docs.npmjs.com/downloading-and-installing-node-js-and-npm  
+vnu: https://www.npmjs.com/package/vnu-jar  
+lynx: https://etc.usf.edu/techease/4all/web-accessibility/the-lynx-text-web-browser/  
+php: https://www.php.net/downloads.php  
+less: `npm install -g less-watch-compiler`  
+MAMP (OSX) or Apache: https://www.mamp.info/en/mac/  
+LAMP (Linux): https://www.linux.com/training-tutorials/easy-lamp-server-installation/
 
 ## Style Notes
 
 1. All font-sizes are converted to rems. This is done via less.  If you want a font-size of 20px, then you would do the following:
 
-```
+```css
 div {
     font-size: (20/@px);
 }
@@ -32,12 +29,16 @@ The `@px` variable is set to 16rem, which is also the base font size
 
 ## Tests
 
+```bash
 sudo npm install axe-cli -g
 sudo npm install -g chromedriver
+```
 
 If there is a problem with running Chromedriver, because you have an error like "SessionNotCreatedError: session not created: This version of ChromeDriver only supports Chrome version XXX", then you should ensure your chromedriver is installed with the right version.
 
+```bash
 sudo npm install chromedriver --chromedriver_filepath=/path/to/chromedriver_mac64.zip
+```
 
 You can install the right zip file from here:
 
@@ -48,5 +49,6 @@ https://chromedriver.storage.googleapis.com/index.html
 https://stackoverflow.com/questions/71859550/session-not-created-this-version-of-chromedriver-only-supports-chrome-version-9
 
 ## References
-https://www.nvaccess.org/files/nvda/documentation/userGuide.html
+
+https://www.nvaccess.org/files/nvda/documentation/userGuide.html  
 https://dequeuniversity.com/screenreaders/survival-guide

bin/checkHTML

@@ -9,7 +9,7 @@ SCRIPT_DIR=$( cd -- "$( dirname -- "${BASH_SOURCE[0]}" )" &> /dev/null && pwd )
 
 echo "Checking if dependencies are installed ..."
 
-for i in lynx java php81 axe
+for i in lynx java php81 axe pa11y-ci
 do
 	which $i > /dev/null 2> /dev/null
 	if [ "$?" != "0" ]
@@ -19,15 +19,34 @@ do
 		then
 			echo "Install axe using:" 1>&2
 			echo "  npm install axe-cli -g" 1>&2
+			exit 1
+		elif [ "$i" = "pa11y-ci" ]
+		then
+			echo "Install pa11y using:" 1>&2
+			echo "  npm install pa11y-ci -g"
+			exit 1
+		elif [ "$i" = "php81" ]
+		then
+			echo "PHP 8.1 is not installed.  Trying PHP ..."
+			which php > /dev/null 2> /dev/null
+
+			if [ "$?" != "0" ]
+			then
+				echo "PHP is not installed.  Bailing"
+				exit 1
+			else
+				echo "A lower version of PHP than 8.1 is being used.  This may have unexpected results."
+			fi
 		else
 			echo "Please install this software using your operating systems package management" 1>&2
+			exit 1
 		fi 
-		exit 1
+
 	fi
 
 
-	#.. Special case with java -- if it returns 1, it is probably because it
-	#   not really installed and it's giving a message to install the runtime.
+	#.. Special case with java -- if it returns 0, it still may not be installed
+	#   and the command is giving a message to install the runtime (happens on OSX)
 	if [ "$i" == "java" ]
 	then
 		OUT=`java 2>&1`
@@ -46,7 +65,7 @@ done
 
 #.. let's ensure axe has the right chromedriver installed
 echo "Checking aXe"
-axe http://www.useragentman.com 2>&1 | grep "This version of ChromeDriver only supports"
+axe $PROJECT_URL 2>&1 | grep "This version of ChromeDriver only supports"
 
 if [ "$?" = "0" ]
 then
@@ -94,6 +113,7 @@ TEMP_FILES=""
 #.. This is the list of files that are to be tested with aXe after a delay of 2000 ms.
 AXE_DELAYED_FILES="math.php pause-anim-control.php video-player.php"
 
+
 echo "Downloading rendered HTML..."
 
 if [ ! -d tmp ]
@@ -209,40 +229,44 @@ then
 	echo "aXe failed. See information above."
 	exit 1
 fi
-comment
 
 
-echo "Running pa11y tests ..."
+
+echo "Running pa11y-ci tests ..."
 
 DID_PALLY_SUCCEED="0"
 
-<<comment
-echo '{
+# <<comment
+( 
+	echo '{
     "urls": [ '
 
-echo "$DOWNLOADED_URLS" | awk '{ printf("\"%s\",\n", $1) }'
-
-        
-echo '    ]
-}'
-
-exit
-comment
+	echo $DOWNLOADED_URLS | awk '
+		{ 
+			for (i=1; i<=NF; i++) {
+				if (i == NF) {
+					comma = "";
+				} else {
+					comma = ",";
+				}
+				printf("\"%s\"%s\n", $i, comma);
+			} 
+		}
+	'
+
+	echo ']}'
+) > tmp/pa11y-config 
 
+# comment
 
-for i in $DOWNLOADED_URLS
-do
-	pa11y $i
+pa11y-ci --config tmp/pa11y-config 
+DID_PALLY_SUCCEED="$?"
 
-	if [ "$?" != "0" ]
-	then
-		DID_PALLY_SUCCEED="1"
-	fi
-done
 
 if [ $DID_PALLY_SUCCEED = "1" ]
 then
 	echo "Pa11y failed.  See information above."
+	exit 2;
 fi
 
 

content/body/acknowledgements.php

@@ -126,6 +126,8 @@
   <li><a href="https://iconscout.com/contributors/daniel-bruce">Daniel Bruce</a> Code Icon</li>
   <li><a href="https://iconscout.com/contributors/ibm-design">IBM Design</a> Add Icon</li>
   <li><a href="https://dribbble.com/Luizcarvalhoid">Luiz Carvalho</a> for the <a href="https://thenounproject.com/icon/bug-2277444/">Bug Icon</a>
+  <li><a href="https://iconscout.com/contributors/vaadin-icons">Vaadin Icons</a> for the  <a href="https://iconscout.com/icon/eye-498">Eye Icon</a> used in the <a href="/images/posters/screen-reader-only-text.jpg">poster image</a> for <a href="screen-reader-only-text.php">our screen reader only text page</a></li>
+  <li><a href="https://thenounproject.com/ASJ/">Andy Santos-Johnson</a> and IYIKON from <a href="https://pngtree.com">Pngtree.com</a> for the elements used in the <a href="/images/posters/exposing-style-info-to-screen-readers.jpg">poster image</a> of <a href="exposing-style-info-to-screen-readers.php">our page on exposing style information to screen readers</a>.</li>
 </ul>
 
 <h2>Typography</h2>

content/body/alert.php

@@ -52,7 +52,7 @@
             "steps": [{
                     "label": "Add role of alert",
                     "highlight": "role",
-                    "notes": ""
+                    "notes": "This and the <code>aria-live</code> attribute in the next step should be in the DOM <em>before</em> you change its content with JavaScript, preferably when the page loads.  <strong>Never insert an ARIA live region with JavaScript with the content you want to announce at the same time</strong> &mdash; it won't work."
                 },
                 {
                     "label": "Add aria-live level",
@@ -62,7 +62,7 @@
                 {
                     "label": "Inject what you want alerted by screen readers into the aria-live region",
                     "highlight": "%JS%alert.sayTimeClickHandler ||| assertiveAlertEl.innerHTML[^;]*;",
-                    "notes": "Note that <code>assertiveAlertEl = document.getElementById('assertive-alert')</code> (from the previous step).  Just using <code>innerHTML</code> on the aria-live region is enough."
+                    "notes": "Note that <code>assertiveAlertEl = document.getElementById('assertive-alert')</code> (from the previous step).  Just using <code>innerHTML</code> on the aria-live region is enough to have screen readers announce the content."
                 }
             ]
         }

content/body/carousel.php

@@ -162,7 +162,8 @@ class="enable-mobile-visible-on-focus enable-skip-link">Skip to
 
 <?= includeNPMInstructions(
     'enable-carousel', 
-    array(), 
+    array(),
+    'enable-carousel',
     false, 
     array(
       "es6Notes" => "<p><em><strong>Note:</strong> If you want to have the skip links like in the example above, please ensure you also include the <a href=\"skip-link.php#npm-instructions\">NPM module for skip links as well</a>.</em></p>",

content/body/code-quality.php

@@ -42,14 +42,14 @@
   try using  <a href="https://html-validate.org/usage/">this Node based HTML validator</a> instead (I have not used this yet, so your mileage may vary).
 </p>
 
-<h2>Using Axe-core and pa11y for Accessibility Linting</h2>
+<h2>Using Axe-core and Pa11y CI for Accessibility Linting</h2>
 
 <p>
-  Enable uses both Deque Labs' <a href="https://github.com/dequelabs/axe-core-npm/tree/develop/packages/cli">@axe-core/cli</a> as well as <a href="https://www.npmjs.com/package/pa11y">Pa11y</a> to do accessibility linting.  Why two?  Both are very good tools, but they don't test for the same things, and as Craig Abbott states in this <a href="https://www.craigabbott.co.uk/blog/axe-core-vs-pa11y">excellent article that compares axe-core and pa11y</a>, it's hard to compare the two.  So why not just use both?
+  Enable uses both Deque Labs' <a href="https://github.com/dequelabs/axe-core-npm/tree/develop/packages/cli">@axe-core/cli</a> as well as <a href="https://github.com/pa11y/pa11y-ci">Pa11y CI</a> to do accessibility linting.  Why two?  Both are very good tools, but they don't test for the same things, and as Craig Abbott states in this <a href="https://www.craigabbott.co.uk/blog/axe-core-vs-pa11y">excellent article that compares axe-core and pa11y</a>, it's hard to compare the two.  So why not just use both?
 </p>
 
 <p>
-  The problem with using axe-core compared to pa11y is that axe-core requires <a href="https://chromedriver.chromium.org/">Chromedriver</a> in order to work (axe-core will run pages in a headless version of Chrome to do ensure the accessibility markup works, including any JavaScript generated markup).  I have personally had problems with Chromedriver updates (<a href="https://github.com/dequelabs/axe-cli/issues/103">here is one of the issues I had in the past</a>).  Pa11y, on the other hand, uses Puppeteer to launch Chrome and do its tests.  You can read
+  The problem with using axe-core compared to Pa11y-CI is that axe-core requires <a href="https://chromedriver.chromium.org/">Chromedriver</a> in order to work (axe-core will run pages in a headless version of Chrome to do ensure the accessibility markup works, including any JavaScript generated markup).  I have personally had problems with Chromedriver updates (<a href="https://github.com/dequelabs/axe-cli/issues/103">here is one of the issues I had in the past</a>).  Pa11y, on the other hand, uses Puppeteer to launch Chrome and do its tests.  You can read
   about <a href="https://www.testim.io/blog/puppeteer-vs-selenium/">how these two technologies differ</a>, but from my experience, it seems
   Chromedriver updates are more likely to break things more often than Puppeteer updates.  You have been warned.
 </p>

content/body/combobox.php

@@ -790,4 +790,4 @@
 </script>
 
 
-<?= includeNPMInstructions('combobox', array(), false, array(), '.enable-combobox') ?>
+<?= includeNPMInstructions('combobox', array(), 'enable-combobox', false, array(), '.enable-combobox') ?>

content/body/dialog.php

@@ -133,4 +133,4 @@
 }
 </script>
 
-<?= includeNPMInstructions('enable-dialog', array(), true) ?>
+<?= includeNPMInstructions('enable-dialog', array(), '', true) ?>

content/body/dropdown.php

@@ -333,6 +333,7 @@
 <?= includeNPMInstructions(
     'enable-drawer',
     array(),
+    'enable-drawer',
     false,
     array(),
     null,

content/body/exposing-style-info-to-screen-readers.php

@@ -190,7 +190,7 @@
     {
       "label": "Visually hide the text generated in the previous step to ensure only screen readers can read the text",
       "highlight": "%CSS%product-tile-css~ .product-tile--good-example del::before, .product-tile--good-example ins::before",
-      "notes": "Note that this uses similar CSS as the <a href=\"https://www.w3docs.com/snippets/css/why-and-how-the-bootstrap-sr-only-class-is-used.html\"><code>sr-only</code> class</a> to hide the CSS generated content visually.  Note we also use <code>user-select: none</code> so users can't select the text when they are copying and pasting the content into, say, a word document.  You may decide to leave that part out, if you wish."
+      "notes": "Note that this uses similar CSS as the <a href=\"screen-reader-only-text.php\"><code>sr-only</code> class</a> to hide the CSS generated content visually.  Note we also use <code>user-select: none</code> so users can't select the text when they are copying and pasting the content into, say, a word document.  You may decide to leave that part out, if you wish."
     }
   ]
 }

content/body/focus-styling.php

@@ -45,7 +45,7 @@
       2.4.7</a></strong>.
 </p>
 <p>
-  <strong>What you can do is make focus indicators only appear for keyboard users.</strong> This can be done using the
+  <strong>What you can do is make focus indicators only appear for keyboard users?</strong> This can be done using the
   <code>:focus-visible</code> CSS pseudo-class. Here is how the Enable site codes them globally using <a
     href="https://www.tpgi.com/focus-visible-and-backwards-compatibility/">TPGI's excellent method to use
     <code>:focus-visible</code> while ensuring browsers that don't support it fallback to using <code>:focus</code>
@@ -86,7 +86,7 @@
 </template>
 
 <p>
-  Is it just keyboard users that will see focus states styled with <code>focus-visible</code>. Kind of, but there are a
+  Is it just keyboard users that will see focus states styled with <code>focus-visible</code>? Kind of, but there are a
   few subtleties. <a href="https://andyadams.org/">Andy Adams</a> has written <a
     href="https://css-tricks.com/almanac/selectors/f/focus-visible/">a great article for CSS Tricks about
     :focus-visible</a> that really goes into detail.

content/body/form.php

@@ -151,7 +151,7 @@
                 {
                     "label": "Add label for screen reader users",
                     "highlight": "%OPENCLOSECONTENTTAG%label",
-                    "notes": "Since there is a search icon on this form, it can be argued that this label can be hidden visually with the <code>sr-only</code>."
+                    "notes": "Since there is a search icon on this form, it can be argued that this label can be hidden visually with the <a href=\"screen-reader-only-text.php\"><code>sr-only</code></a>."
                 },
                 {
                     "label": "Ensure sizing of the form elements and the icons use relative units",

content/body/listbox.php

@@ -447,6 +447,7 @@ class="enable-listbox__button">&nbsp;</button>
 <?= includeNPMInstructions(
   'enable-listbox',
   array(),
+  'enable-listbox',
   false,
   array(),
   null,

content/body/multi-level-hamburger-menu.php

@@ -149,7 +149,7 @@
 
 <h3 id="enable-hamburger-menu__heading" tabindex="-1">Coding HTML by Hand</h3>
 
-<p>If you wanted to code this menu's HTML by hand, you can use the following guide.  Just keep in mind that each level is basically a list of buttons and links.  The links will go to new </p>
+<p>If you wanted to code this menu's HTML by hand, you can use the following guide.  Just keep in mind that each level is basically a list of buttons and links.  The links will go to new pages; the buttons will open up a new section.</p>
 
 <?php includeShowcode("flyout__container", "", "", "", true, 0)?>
 <script type="application/json" id="flyout__container-props">
@@ -300,4 +300,4 @@
   include('../templates/enable-hamburger.html');
 ?>
 
-<?= includeNPMInstructions('enable-hamburger') ?>
+<?= includeNPMInstructions('enable-hamburger', array(), 'enable-flyout') ?>

content/body/pagination-table.php

@@ -1792,7 +1792,7 @@
     {
       "label": "Mark up the pagination widget correctly",
       "highlight": "role=\"group\" ||| aria-labelledby=\"pagination-table-example__desc--top\" ||| id=\"pagination-table-example__desc--top\" ||| aria-labelledby=\"pagination-table-example__desc--bottom\" ||| id=\"pagination-table-example__desc--bottom\"",
-      "notes": "This widget is marked up as a group so screen readers will announce instructions on how it works when they navigate inside of it.  Note the instructions are screen reader only using the <code>sr-only</code> class."
+      "notes": "This widget is marked up as a group so screen readers will announce instructions on how it works when they navigate inside of it.  Note the instructions are screen reader only using the <a href=\"screen-reader-only-text.php\"><code>sr-only</code></a> class."
     },
     {
       "label": "Ensure all pagination buttons have an aria-label",
@@ -1816,7 +1816,8 @@
 
 <?= includeNPMInstructions(
   'paginate',
-  array(), 
+  array(),
+  'pagination',
   false, 
   array(),
   '.pagination__table'