Merge branch 'main' into momdo-html-aapi

.github/workflows/11ty-publish.yaml

@@ -0,0 +1,45 @@
+name: CI
+
+# Reference documentation: https://docs.github.com/en/actions/reference
+
+# See https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions#onpushpull_requestbranchestags
+on:
+  push:
+    branches: [main]
+
+jobs:
+  main:
+    name: deploy (11ty)
+    runs-on: ubuntu-20.04
+    steps:
+      - name: Checkout the repository
+        uses: actions/checkout@v4
+      - name: Checkout gh-pages
+        uses: actions/checkout@v4
+        with:
+          ref: gh-pages
+          path: _site
+          token: ${{ secrets.W3CGRUNTBOT_TOKEN }}
+      - name: Install Node.js and dependencies
+        uses: actions/setup-node@v4
+        with:
+          cache: npm
+          node-version-file: '.nvmrc'
+      - name: Build
+        env:
+          WCAG_MODE: editors
+        run: |
+          npm i
+          npm run build
+          cp guidelines/guidelines.css guidelines/relative-luminance.html _site/guidelines/22
+          curl https://labs.w3.org/spec-generator/?type=respec"&"url=https://raw.githack.com/$GITHUB_REPOSITORY/main/guidelines/index.html -o _site/guidelines/22/index.html -f  --retry 3
+          curl https://labs.w3.org/spec-generator/?type=respec"&"url=https://raw.githack.com/$GITHUB_REPOSITORY/main/requirements/22/index.html -o _site/requirements/22/index.html -f  --retry 3
+          curl https://labs.w3.org/spec-generator/?type=respec"&"url=https://raw.githack.com/$GITHUB_REPOSITORY/main/conformance-challenges/index.html -o _site/conformance-challenges/index.html -f  --retry 3
+      - name: Push
+        working-directory: _site
+        run: |
+          git config user.email 87540780+w3cgruntbot@users.noreply.github.com
+          git config user.name w3cgruntbot
+          git add -A .
+          git commit -m ":robot: Deploy to GitHub Pages: $GITHUB_SHA from branch $GITHUB_REF"
+          git push origin gh-pages

11ty/CustomLiquid.ts

@@ -393,7 +393,7 @@ export class CustomLiquid extends Liquid {
       // where we have access to global data and the about box's HTML
       const $termLinks = $(termLinkSelector);
       const extractTermName = ($el: Cheerio<Element>) => {
-        const name = $el.text().trim().toLowerCase();
+        const name = $el.text().toLowerCase().trim().replace(/\s*\n+\s*/, " ");
         const term = termsMap[name];
         if (!term) {
           console.warn(`${scope.page.inputPath}: Term not found: ${name}`);
@@ -433,7 +433,11 @@ export class CustomLiquid extends Liquid {
           }
 
           // Iterate over sorted names to populate alphabetized Key Terms definition list
-          termNames.sort();
+          termNames.sort((a, b) => {
+            if (a.toLowerCase() < b.toLowerCase()) return -1;
+            if (a.toLowerCase() > b.toLowerCase()) return 1;
+            return 0;
+          });
           for (const name of termNames) {
             const term = termsMap[name]; // Already verified existence in the earlier loop
             $termsList.append(

11ty/README.md

@@ -40,16 +40,16 @@ Indicates top-level path of W3C CVS checkout, for WAI site updates (via `publish
 
 ### `WCAG_VERSION`
 
-**Usage context:** `publish-w3c` script only;
-this should currently not be changed, pending future improvements to `21` support.
+**Usage context:** currently this should not be changed, pending future improvements to `21` support
 
-Indicates WCAG version being built, in `XY` format (i.e. no `.`)
+Indicates WCAG version being built, in `XY` format (i.e. no `.`).
+Influences base URLs for links to guidelines, techniques, and understanding pages.
 
 **Default:** `22`
 
 ### `WCAG_MODE`
 
-**Usage context:** should not need to be used manually except in specific testing scenarios
+**Usage context:** should not need to be set manually except in specific testing scenarios
 
 Influences base URLs for links to guidelines, techniques, and understanding pages.
 Typically set by specific npm scripts or CI processes.
@@ -60,6 +60,15 @@ Possible values:
 - `editors` - Sets base URLs appropriate for `gh-pages` publishing; used by deploy action
 - `publication` - Sets base URLs appropriate for WAI site publishing; used by `publish-w3c` script
 
+### `GITHUB_REPOSITORY`
+
+**Usage context:** Automatically set during GitHub workflows; should not need to be set manually
+
+Influences base URLs for links to guidelines, techniques, and understanding pages,
+when `WCAG_MODE=editors` is also set.
+
+**Default:** `w3c/wcag`
+
 ## Other points of interest
 
 - The main configuration can be found in top-level `eleventy.config.ts`

11ty/cp-cvs.ts

@@ -1,14 +1,17 @@
 /** @fileoverview script to copy already-built output to CVS subfolders */
 
-import { copyFile, unlink } from "fs/promises";
 import { glob } from "glob";
 import { mkdirp } from "mkdirp";
 
+import { copyFile, unlink } from "fs/promises";
 import { dirname, join } from "path";
 
+import { assertIsWcagVersion } from "./guidelines";
+
 const outputBase = "_site";
 const cvsBase = process.env.WCAG_CVSDIR || "../../../w3ccvs";
 const wcagVersion = process.env.WCAG_VERSION || "22";
+assertIsWcagVersion(wcagVersion);
 const wcagBase = `${cvsBase}/WWW/WAI/WCAG${wcagVersion}`;
 
 // Map (git) sources to (CVS) destinations, since some don't match case-sensitively

11ty/guidelines.ts

@@ -8,7 +8,7 @@ import { flattenDomFromFile, load } from "./cheerio";
 import { generateId } from "./common";
 
 export type WcagVersion = "20" | "21" | "22";
-function assertIsWcagVersion(v: string): asserts v is WcagVersion {
+export function assertIsWcagVersion(v: string): asserts v is WcagVersion {
   if (!/^2[012]$/.test(v)) throw new Error(`Unexpected version found: ${v}`);
 }
 
@@ -208,11 +208,15 @@ export async function getTermsMap() {
       // but the XSLT process generates id from the element's text which is not always the same
       id: `dfn-${generateId($el.text())}`,
       definition: getContentHtml($el.parent().next()),
-      name: $el.text().toLowerCase(),
+      name: $el.text(),
       trId: el.attribs.id,
     };
 
-    const names = [term.name].concat((el.attribs["data-lt"] || "").toLowerCase().split("|"));
+    // Include both original and all-lowercase version to simplify lookups
+    // (since most synonyms are lowercase) while preserving case in name
+    const names = [term.name, term.name.toLowerCase()].concat(
+      (el.attribs["data-lt"] || "").toLowerCase().split("|")
+    );
     for (const name of names) terms[name] = term;
   });
 

eleventy.config.ts

@@ -3,7 +3,7 @@ import compact from "lodash-es/compact";
 import { copyFile } from "fs/promises";
 
 import { CustomLiquid } from "11ty/CustomLiquid";
-import { actRules, getFlatGuidelines, getPrinciples } from "11ty/guidelines";
+import { actRules, assertIsWcagVersion, getFlatGuidelines, getPrinciples } from "11ty/guidelines";
 import {
   getFlatTechniques,
   getTechniqueAssociations,
@@ -15,7 +15,8 @@ import { generateUnderstandingNavMap, getUnderstandingDocs } from "11ty/understa
 import type { EleventyContext, EleventyData, EleventyEvent } from "11ty/types";
 
 /** Version of WCAG to build */
-const version = "22";
+const version = process.env.WCAG_VERSION || "22";
+assertIsWcagVersion(version);
 
 const principles = await getPrinciples();
 const flatGuidelines = getFlatGuidelines(principles);
@@ -45,6 +46,8 @@ export type GlobalData = EleventyData &
     isUnderstanding?: boolean;
   };
 
+const [GH_ORG, GH_REPO] = (process.env.GITHUB_REPOSITORY || "w3c/wcag").split("/");
+
 const baseUrls = {
   guidelines: `https://www.w3.org/TR/WCAG${version}/`,
   techniques: "/techniques/",
@@ -53,9 +56,11 @@ const baseUrls = {
 
 if (process.env.WCAG_MODE === "editors") {
   // For pushing to gh-pages
-  baseUrls.guidelines = "https://w3c.github.io/wcag/guidelines/";
-  baseUrls.techniques = "https://w3c.github.io/wcag/techniques/";
-  baseUrls.understanding = "https://w3c.github.io/wcag/understanding/";
+  baseUrls.guidelines = `https://${GH_ORG}.github.io/${GH_REPO}/guidelines/${
+    version === "21" ? "" : `${version}/`
+  }`;
+  baseUrls.techniques = `https://${GH_ORG}.github.io/${GH_REPO}/techniques/`;
+  baseUrls.understanding = `https://${GH_ORG}.github.io/${GH_REPO}/understanding/`;
 } else if (process.env.WCAG_MODE === "publication") {
   // For pushing to W3C site
   baseUrls.guidelines = `https://www.w3.org/TR/WCAG${version}/`;

techniques/aria/ARIA22.html

@@ -18,7 +18,7 @@ <h2>When to Use</h2>
 		<section id="description">
 			<h2>Description</h2>
 			<p>
-				This technique uses the <code>status</code> role from the ARIA specification to notify Assistive Technologies (AT) when content has been updated with information about the user's or application's status. This is done by adding <code>role="status"</code> to the element that contains the <a href="/TR/WCAG/#dfn-status-messages">status message</a>. The aria live region role of <code>status</code> has an implicit <code>aria-live</code> value of <code>polite</code>, which allows a user to be notified via AT (such as a screen reader) when status messages are added. The role of <code>status</code> also has a default <code>aria-atomic</code> value of <code>true</code>, so that updates to the container marked with a role of <code>status</code> will result in the AT presenting the entire contents of the container to the user, including any author-defined labels (or additional nested elements). Such additional context can be critical where the status message text alone will not provide an equivalent to the visual experience. The content of the aria-live container is automatically read by the AT, without the AT having to focus on the place where the text is displayed. See <a href="https://www.w3.org/TR/wai-aria/#status">WAI-ARIA status (role)</a> for more details.</p>
+				This technique uses the <code>status</code> role from the ARIA specification to notify Assistive Technologies (AT) when content has been updated with information about the user's or application's status. This is done by adding <code>role="status"</code> to the element that contains the <a>status message</a>. The aria live region role of <code>status</code> has an implicit <code>aria-live</code> value of <code>polite</code>, which allows a user to be notified via AT (such as a screen reader) when status messages are added. The role of <code>status</code> also has a default <code>aria-atomic</code> value of <code>true</code>, so that updates to the container marked with a role of <code>status</code> will result in the AT presenting the entire contents of the container to the user, including any author-defined labels (or additional nested elements). Such additional context can be critical where the status message text alone will not provide an equivalent to the visual experience. The content of the aria-live container is automatically read by the AT, without the AT having to focus on the place where the text is displayed. See <a href="https://www.w3.org/TR/wai-aria/#status">WAI-ARIA status (role)</a> for more details.</p>
 
 		</section>
 		<section id="examples">
@@ -45,7 +45,7 @@ <h3>Updating the shopping cart status</h3>
 			<h2>Tests</h2>
 			<section class="test-procedure">
 				<h3>Procedure</h3>
-				<p>For each <a href="/TR/WCAG/#dfn-status-messages">status message</a>:</p>
+				<p>For each <a>status message</a>:</p>
 				<ol>
 					<li>Check that the container destined to hold the status message has a <code class="language-html">role</code> attribute with a value of <code class="language-html">status</code> <em>before</em> the status message occurs.</li>
 					<li>Check that when the status message is triggered, it is inside the container.</li>

techniques/aria/ARIA6.html

@@ -2,12 +2,12 @@
       <p>Technologies that support <a href="https://www.w3.org/TR/wai-aria/">Accessible Rich Internet Applications (WAI-ARIA)</a>. </p>
    </section><section id="description"><h2>Description</h2>
       <p>The purpose of this technique is to provide a label for objects that can be read by assistive technology. The <code class="language-html">aria-label</code> attribute provides the text label for an object, such as a button. When a screen reader encounters the object, the <code class="language-html">aria-label</code> text is read so that the user will know what it is.</p>
-      <p>Authors should be aware that <code class="language-html">aria-label</code> may be disregarded by assistive technologies in situations where <code class="language-html">aria-labelledby</code> is used for the same object. For more information on the naming hierarchy please consult the <a href="https://www.w3.org/TR/wai-aria/#textalternativecomputation">ARIA specification</a> and the <a href="https://www.w3.org/TR/html-aam-1.0/#accessible-name-and-description-computation">Accessible Name and Description Computation</a> in the HTML Accessibility API Mappings 1.0. Authors should be aware that use of <code class="language-html">aria-label</code> will override any native naming such as <code class="language-html">alt</code> on images or <code class="language-html">label</code> associated with a form field using the <code class="language-html">for</code> attribute.</p>
+      <p>Authors should be aware that <code class="language-html">aria-label</code> may be disregarded by assistive technologies in situations where <code class="language-html">aria-labelledby</code> is used for the same object. For more information on the naming hierarchy please consult the <a href="https://www.w3.org/TR/accname/#mapping_additional_nd_te">accessible name and description computation</a> section of the Accessible Name And Description Computation recommendation. Authors should be aware that use of <code class="language-html">aria-label</code> will override any native naming such as <code class="language-html">alt</code> on images or <code class="language-html">label</code> associated with a form field using the <code class="language-html">for</code> attribute.</p>
    </section><section id="examples"><h2>Examples</h2>
       <section class="example">
          <h3>Distinguishing navigation landmarks</h3>
 
-            <p>The following example shows how <code class="language-html">aria-label</code> could be used to distinguish two navigation landmarks in a HTML4 and XHTML 1.0 document, where there are more than two of the same type of landmark on the same page, and there is no existing text on the page that can be referenced as the label.</p>
+            <p>The following example shows how <code class="language-html">aria-label</code> could be used to distinguish two navigation landmarks in an HTML document, where there are more than two of the same type of landmark on the same page, and there is no existing text on the page that can be referenced as the label.</p>
 <pre xml:space="preserve"><code class="language-html">&lt;div role="navigation" aria-label="Primary"&gt;
   &lt;ul&gt;
     &lt;li&gt;...a list of links here ...&lt;/li&gt;

techniques/client-side-script/SCR19.html

@@ -119,7 +119,7 @@
                   <a href="http://usability.com.au/2008/09/accessible-forms-using-wcag-2-0/">Accessible Forms using WCAG 2.0</a>
                </li>
              <li>
-                  <a href="/TR/WCAG/#dfn-change-of-context">Change of context definition</a>
+                  <a>Change of context</a> definition
                </li>
          </ul>
 

techniques/failures/F103.html

@@ -29,7 +29,7 @@ <h2>Description</h2>
 					<li>the new content does not take focus (does not change context);</li>
 					<li>the new content provides information to the user on the outcome of an action, the state of an application, the progress of a process, or the existence of errors.</li>
 				</ol>
-			 Where updated content does not conform to the <a href="/TR/WCAG/#dfn-status-messages">definition of status message</a>, a failure of 4.1.3 has not taken place.</p>
+			 Where updated content does not conform to the definition of <a>status messages</a>, a failure of 4.1.3 has not taken place.</p>
 				<p>The second step in this failure technique involves examining code.  Where dynamic content meets the definition of a status message, its container can be examined for an appropriate WAI-ARIA role or property which allows it to be programmatically determinable as a status message. Currently there are only a small number of techniques available to indicate status messages to assistive technologies. They are:
 					<ul>
 						<li>the HTML <code class="language-html">output</code> element</li>