w3c · alflennik · Nov 22, 2022 · Nov 10, 2022 · Nov 10, 2022 · Nov 11, 2022
diff --git a/.eslintrc.json b/.eslintrc.json
@@ -63,6 +63,14 @@
         "strict": 0,
         "no-unused-vars":  ["error", { "varsIgnorePattern": "SkipToConfig" }]
       }
+    },
+    {
+      "files": [ "content/shared/js/app.js" ],
+      "parserOptions": { "ecmaVersion": 11 }
+    },
+    {
+      "files": [ "content/shared/js/specLinks.mjs" ],
+      "parserOptions": { "sourceType": "module" }
     }
   ]
 }
diff --git a/content/about/about.html b/content/about/about.html
@@ -7,15 +7,15 @@
 
     <!-- Core JS and CSS shared by about content-->
     <link rel="stylesheet" href="https://www.w3.org/StyleSheets/TR/2016/base.css">
-    <link rel="stylesheet" href="../../shared/css/core.css">
-    <script src="../../shared/js/highlight.pack.js"></script>
-    <script src="../../shared/js/app.js"></script>
-    <script src="../../shared/js/skipto.js"></script>
+    <link rel="stylesheet" href="../shared/css/core.css">
+    <script src="../shared/js/highlight.pack.js"></script>
+    <script src="../shared/js/app.js"></script>
+    <script src="../shared/js/skipto.js"></script>
   </head>
   <body>
     <main>
       <h1>About</h1>
-      
+
       <section id="intro">
         <h2>Introduction</h2>
         <p>
@@ -55,7 +55,7 @@ <h2>Introduction</h2>
 
       <section id="change_log">
         <h2>Change History</h2>
-        
+
         <p>
           APG 1.1 supported ARIA 1.1, and this version, APG 1.2, includes changes to support version 1.2 of the ARIA specification.
           It also includes nearly 200 significant updates to improve the quality and breadth of content.
@@ -103,7 +103,7 @@ <h2>Change History</h2>
           </li>
         </ul>
       </section>
-      
+
       <section id="acknowledgements">
         <h2>Acknowledgements</h2>
         <h3>Editors</h3>
@@ -232,7 +232,7 @@ <h3 id="c-4-other-commenters-and-contributors-to-version-1-1">Other commenters a
             <li>Christopher Tryens</li>
           </ul>
         </section>
-      </section>    
+      </section>
 
     <section id="references">
         <h2 id="d-references">References</h2>
@@ -293,7 +293,7 @@ <h3 id="d-1-informative-references">Informative references</h3>
           </dl>
         </section>
       </section>
-      
+
     </main>
   </body>
 </html>
diff --git a/content/about/coverage-and-quality/coverage-and-quality-report.html b/content/about/coverage-and-quality/coverage-and-quality-report.html
diff --git a/content/index.html b/content/index.html
@@ -21,8 +21,8 @@ <h1>ARIA Authoring Practices Guide (APG) Home</h1>
         This guide describes how to apply accessibility semantics to common design patterns and widgets.
         It provides design patterns and functional examples complemented by in-depth guidance for fundamental practices.
       </p>
-      <a href="patterns/">View Patterns</a>
-      <img alt="A laptop screen fills with an accessibility icon and emits a checkmark." src="img/index-1.svg">
+      <a href="patterns/patterns.html">View Patterns</a>
+      <img alt="A laptop screen fills with an accessibility icon and emits a checkmark." src="../img/index-1.svg">
     </div>
     <div id="resources">
       <h2>APG Resources</h2>
@@ -34,26 +34,26 @@ <h3>Design Patterns and Examples</h3>
             Learn how to make accessible web components and widgets with ARIA roles, states and properties and by implementing keyboard support.
             One or more ways of implementing each pattern is demonstrated with a functional example.
           </p>
-          <a href="patterns/" aria-label="Learn more about APG patterns and examples">Learn More</a>
-          <img alt="A menagerie of widgets." src="img/index-2.svg">
+          <a href="patterns/patterns.html" aria-label="Learn more about APG patterns and examples">Learn More</a>
+          <img alt="A menagerie of widgets." src="../img/index-2.svg">
         </li>
         <li>
           <h3>Use ARIA Landmarks</h3>
           <p>Learn how to use HTML sectioning elements and ARIA landmark roles to make it easy for assistive technology users to understand the meaning of the layout of a page.</p>
-          <a href="practices/landmark-regions/" aria-label="Learn more about ARIA landmarks">Learn More</a>
-          <img alt="A document flies apart into chunks." src="img/index-3.svg">
+          <a href="practices/landmark-regions/landmark-regions-practice.html" aria-label="Learn more about ARIA landmarks">Learn More</a>
+          <img alt="A document flies apart into chunks." src="../img/index-3.svg">
         </li>
         <li>
           <h3>Providing Accessible Names and Descriptions</h3>
           <p>Providing elements with accessible names and, where appropriate, accessible descriptions is one of the most important responsibilities authors have when developing accessible web experiences.</p>
-          <a href="practices/names-and-descriptions/" aria-label="Learn more about accessible names and descriptions">Learn More</a>
-          <img alt="Indicators delve inside a document." src="img/index-4.svg">
+          <a href="practices/names-and-descriptions/names-and-descriptions-practice.html" aria-label="Learn more about accessible names and descriptions">Learn More</a>
+          <img alt="Indicators delve inside a document." src="../img/index-4.svg">
         </li>
         <li>
           <h3>And So Much More...</h3>
           <p>Learn about other fundamental practices related to correctly using accessibility semantics, developing keyboard interfaces, and more.</p>
-          <a class="button-link" href="practices/" aria-label="Learn more about APG practices">Learn More</a>
-          <img alt="A box with an accessibility label is chock full of widgets and document bits." src="img/index-5.svg">
+          <a class="button-link" href="practices/practices.html" aria-label="Learn more about APG practices">Learn More</a>
+          <img alt="A box with an accessibility label is chock full of widgets and document bits." src="../img/index-5.svg">
         </li>
       </ul>
     </div>
@@ -106,7 +106,7 @@ <h3>Join the Task Force</h3>
             Participants are expected to actively contribute to the work of the task force.
           </p>
           <a rel="noopener noreferrer" target="_blank" href="https://www.w3.org/WAI/ARIA/task-forces/practices/">Learn more about the work of the task force and how to join</a>
-          <img alt="An icon showing three nodes connecting." src="img/index-6.svg">
+          <img alt="An icon showing three nodes connecting." src="../img/index-6.svg">
         </li>
         <li>
           <h3>Contribute via GitHub</h3>
@@ -115,7 +115,7 @@ <h3>Contribute via GitHub</h3>
             If you choose this path, please start by studying our guidelines for contributing to the repository and maintaining code quality.
           </p>
           <a rel="noopener noreferrer" target="_blank" href="https://github.com/w3c/aria-practices">View ReadMe in the GitHub repository</a>
-          <img alt="An icon showing two human shapes carrying a burden." src="img/index-7.svg">
+          <img alt="An icon showing two human shapes carrying a burden." src="../img/index-7.svg">
         </li>
         <li>
           <h3>Mailing Lists</h3>
@@ -125,7 +125,7 @@ <h3>Mailing Lists</h3>
             While GitHub issues are the preferred place to discuss APG content, the mailing list is available to anyone who would prefer to communicate with the APG Task Force via email.
           </p>
           <p><a rel="noopener noreferrer" target="_blank" href="https://lists.w3.org/Archives/Public/public-aria-practices/">View the aria-practices mailing list archive</a></p>
-          <img alt="A notification bell icon appears over an email icon." src="img/index-8.svg">
+          <img alt="A notification bell icon appears over an email icon." src="../img/index-8.svg">
         </li>
       </ul>
     </div>

diff --git a/content/patterns/button/examples/button_idl.html b/content/patterns/button/examples/button_idl.html
@@ -30,7 +30,7 @@ <h1>Button Examples (IDL Version)</h1>
 
       <section>
         <h2>About This example</h2>
-        <p>The following examples of the <a href="../.button-pattern.html">Button Pattern</a> demonstrate a new JavaScript syntax for coding ARIA attributes.</p>
+        <p>The following examples of the <a href="../button-pattern.html">Button Pattern</a> demonstrate a new JavaScript syntax for coding ARIA attributes.</p>
         <p>
           The JavaScript for the example buttons on this page uses the <a class="specref" href="#idl-interface">IDL Interface defined in ARIA 1.2</a>.
           The purpose of these examples is to illustrate how to use ARIA Attribute Reflection and provide a test case for browser and assistive technology interoperability.

diff --git a/content/patterns/checkbox/checkbox-pattern.html b/content/patterns/checkbox/checkbox-pattern.html
@@ -18,11 +18,7 @@ <h1>Checkbox Pattern</h1>
 
       <section id="about">
         <h2>About This Pattern</h2>
-        <p>WAI-ARIA supports two types of <a href="#checkbox" class="role-reference">checkbox</a> widgets:</p>
-        <ol>
-          <li>Dual-state: The most common type of checkbox, it allows the user to toggle between two choices -- checked and not checked.</li>
-          <li>Tri-state: This type of checkbox supports an additional third state known as partially checked.</li>
-        </ol>
+        <p>WAI-ARIA supports two types of <a href="#checkbox" class="role-reference">checkbox</a> widgets: dual-state checkboxes toggle between two choices -- checked and not checked -- and tri-state checkboxes, which  allow an additional third state known as partially checked.</p>
         <p>
           One common use of a tri-state checkbox can be found in software installers where a single tri-state checkbox is used to represent and control the state of an entire group of install options.
           And, each option in the group can be individually turned on or off with a dual state checkbox.

diff --git a/content/patterns/checkbox/examples/checkbox.html b/content/patterns/checkbox/examples/checkbox.html
@@ -29,7 +29,7 @@ <h1>Checkbox Example (Two State)</h1>
 
       <section>
         <h2>About This Example</h2>
-        <p>This example implements the <a href="checkbox.html">Checkbox Design Pattern</a> for a two state checkbox using <code>div</code> elements.</p>
+        <p>This example implements the <a href="../checkbox-pattern.html">Checkbox Pattern</a> for a two state checkbox using <code>div</code> elements.</p>
 
         <p>Similar examples include:</p>
         <ul>

diff --git a/content/patterns/checkbox/examples/js/checkbox.js b/content/patterns/checkbox/examples/js/checkbox.js
@@ -19,6 +19,7 @@ class Checkbox {
     }
 
     this.domNode.addEventListener('keydown', this.onKeydown.bind(this));
+    this.domNode.addEventListener('keyup', this.onKeyup.bind(this));
     this.domNode.addEventListener('click', this.onClick.bind(this));
   }
 
@@ -32,7 +33,14 @@ class Checkbox {
 
   /* EVENT HANDLERS */
 
+  // Make sure to prevent page scrolling on space down
   onKeydown(event) {
+    if (event.key === ' ') {
+      event.preventDefault();
+    }
+  }
+
+  onKeyup(event) {
     var flag = false;
 
     switch (event.key) {
@@ -47,7 +55,6 @@ class Checkbox {
 
     if (flag) {
       event.stopPropagation();
-      event.preventDefault();
     }
   }
 

diff --git a/content/patterns/patterns.html b/content/patterns/patterns.html
@@ -0,0 +1,12 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta http-equiv="X-UA-Compatible" content="IE=edge">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Patterns</title>
+</head>
+<body>
+  In a future iteration this file will contain a list of all patterns.
+</body>
+</html>
diff --git a/content/patterns/slider/examples/slider-rating.html b/content/patterns/slider/examples/slider-rating.html
@@ -41,7 +41,7 @@ <h2>About This Example</h2>
           Following is an example of a rating input that demonstrates the <a href="../slider-pattern.html">Slider Pattern</a>.
           This rating widget employs a slider because the slider pattern supports step values of any size.
           This particular input enables half-star steps.
-          A typical five-star rating widget that allows only five possible values could instead be implemented as a <a href="../../radio/examples/radio-group-pattern.html">radio group.</a>
+          A typical five-star rating widget that allows only five possible values could instead be implemented as a <a href="../../radio/radio-group-pattern.html">radio group.</a>
         </p>
         <p>Similar examples include:</p>
         <ul>

diff --git a/content/practices/grid-and-table-properties/grid-and-table-properties-practice.html b/content/practices/grid-and-table-properties/grid-and-table-properties-practice.html
@@ -18,7 +18,10 @@ <h1>Grid and Table Properties</h1>
 
       <section id="introduction">
         <h2>Introduction</h2>
-        <p>To fully present and describe a grid or table, in addition to parsing the headers, rows, and cells using the roles described in the <a href="../../patterns/grid/grid-pattern.html">grid pattern</a> or <a href="../../patterns/table/table-pattern.html">table pattern</a>, assistive technologies need to be able to determine:</p>
+        <p>
+          To fully present and describe a grid or table, in addition to parsing the headers, rows, and cells using the roles described in the <a href="../../patterns/grid/grid-pattern.html">grid pattern</a> or <a href="../../patterns/table/table-pattern.html">table pattern</a>, assistive technologies need to be able to determine other structural and presentation characteristics, such as the number and visibility of rows and columns.
+          Characteristics that may need to be described with additional WAI-ARIA attributes include:
+        </p>
         <ul>
           <li>The number of rows and columns.</li>
           <li>Whether any columns or rows are hidden, e.g., columns 1 through 3 and 5 through 8 are visible but column 4 is hidden.</li>

diff --git a/content/practices/names-and-descriptions/names-and-descriptions-practice.html b/content/practices/names-and-descriptions/names-and-descriptions-practice.html
@@ -19,7 +19,7 @@ <h1>Providing Accessible Names and Descriptions</h1>
       <section id="introduction">
         <h2>Introduction</h2>
         <p>
-          Providing elements with accessible names, and where appropriate, accessible descriptions is one of the most important responsibilities authors have when developing accessible web experiences.
+          Providing elements with accessible names, and where appropriate, accessible descriptions, is one of the most important responsibilities authors have when developing accessible web experiences.
           While doing so is straightforward for most elements, technical mistakes that can completely block users of assistive technologies are easy to make and unfortunately common.
           To help authors effectively provide accessible names and descriptions, this section explains their purpose, when authors need to provide them, how browsers assemble them, and rules for coding and composing them.
           It also guides authors in the use of the following naming and describing techniques and WAI-ARIA properties:

diff --git a/content/practices/practices.html b/content/practices/practices.html
@@ -0,0 +1,12 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta http-equiv="X-UA-Compatible" content="IE=edge">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Practices</title>
+</head>
+<body>
+  In a future iteration this file will contain a list of all practices.
+</body>
+</html>
diff --git a/content/shared/css/core.css b/content/shared/css/core.css
@@ -128,3 +128,8 @@ th .example-header {
   );
   box-shadow: inset 0 3px 5px 1px hsl(216deg 82% 30%);
 }
+
+#support-notice summary p {
+  display: inline;
+  margin-left: 5px;
+}
diff --git a/content/shared/js/app.js b/content/shared/js/app.js
@@ -6,63 +6,41 @@
   // Load syntax highlighting
   hljs.initHighlightingOnLoad();
 
-  // Add support notice to all examples
-  window.addEventListener('DOMContentLoaded', addSupportNotice, false);
+  // Add usage warning to all examples
+  window.addEventListener('DOMContentLoaded', addExampleUsageWarning, false);
 
-  function addSupportNotice() {
-    // The "Example" heading
-    var headings = document.querySelectorAll('h2');
-    var foundExampleHeading;
-    for (var i = 0; i < headings.length; ++i) {
-      if (headings[i].textContent.trim().match(/^Examples?$/)) {
-        foundExampleHeading = true;
-        break;
-      }
-    }
-    if (!foundExampleHeading) {
-      return;
-    }
+  // Rewrite links so they point to the proper spec document
+  window.addEventListener('DOMContentLoaded', resolveSpecLinks, false);
 
-    // The #browser_and_AT_support link
-    var supportLink = document.querySelector(
-      'a[href$="#browser_and_AT_support"]'
-    );
-    if (!supportLink) {
-      return;
-    }
-
-    // Get the right relative URL to the root aria-practices page
-    var urlPrefix = supportLink.getAttribute('href').split('#')[0];
+  async function addExampleUsageWarning() {
+    // Determine we are on an example page
+    if (!document.location.href.match(/examples\/[^/]+\.html/)) return;
 
-    // Expected outcome '../js/app.js' OR '../../js/app.js'
-    var scriptSource = document
+    // Generate the usage warning link using app.js link as a starting point
+    const scriptSource = document
       .querySelector('[src$="app.js"]')
       .getAttribute('src');
-    // Replace 'app.js' part with 'notice.html'
+    const fetchSource = scriptSource.replace(
+      '/js/app.js',
+      '/templates/example-usage-warning.html'
+    );
+
+    // Load and parse the usage warning and insert it before the h1
+    const html = await (await fetch(fetchSource)).text();
+    const doc = new DOMParser().parseFromString(html, 'text/html');
+
+    // Pull out the relevant part, the details element
+    const warningElement = doc.querySelector('details');
+    warningElement.classList.add('note'); // Needed for styling
+
+    // Insert the usage warning before the page's h1
+    const heading = document.querySelector('h1');
+    heading.parentNode.insertBefore(warningElement, heading.nextSibling);
+  }
 
-    var fetchSource = scriptSource.replace('app.js', './notice.html');
-    //fetch('https://raw.githack.com/w3c/aria-practices/1228-support-notice/examples/js/notice.html')
-    fetch(fetchSource)
-      .then(function (response) {
-        // Return notice.html as text
-        return response.text();
-      })
-      .then(function (html) {
-        // Parse response as text/html
-        var parser = new DOMParser();
-        return parser.parseFromString(html, 'text/html');
-      })
-      .then(function (doc) {
-        // Get the details element from the parsed response
-        var noticeElement = doc.querySelector('details');
-        // Rewrite links with the right urlPrefix
-        var links = doc.querySelectorAll('a[href^="/#"]');
-        for (var i = 0; i < links.length; ++i) {
-          links[i].pathname = urlPrefix;
-        }
-        // Insert the support notice before the page's h1
-        var heading = document.querySelector('h1');
-        heading.parentNode.insertBefore(noticeElement, heading.nextSibling);
-      });
+  async function resolveSpecLinks() {
+    const { specLinks } = await import('./specLinks.mjs');
+    const fixSpecLink = specLinks({ specStatus: 'ED' });
+    document.querySelectorAll('a[href]').forEach(fixSpecLink);
   }
 })();
diff --git a/content/shared/js/notice.html b/content/shared/js/notice.html