From 49e8c747552962b848766ce009ba1583c0a78b28 Mon Sep 17 00:00:00 2001 From: alflennik Date: Thu, 10 Nov 2022 15:56:34 -0500 Subject: [PATCH 01/14] Implement fixes for task 11 of issue 2417 --- content/about/about.html | 18 +- .../coverage-and-quality-report.html | 1228 ++++++++--------- content/index.html | 26 +- .../patterns/button/examples/button_idl.html | 2 +- .../patterns/checkbox/checkbox-pattern.html | 6 +- content/patterns/patterns.html | 12 + .../slider/examples/slider-rating.html | 2 +- .../grid-and-table-properties-practice.html | 2 +- .../names-and-descriptions-practice.html | 2 +- content/practices/practices.html | 12 + content/shared/css/core.css | 5 + content/shared/js/app.js | 32 +- content/shared/js/notice.html | 21 - .../templates/example-usage-warning.html | 30 + scripts/coverage-report.js | 27 +- 15 files changed, 725 insertions(+), 700 deletions(-) create mode 100644 content/patterns/patterns.html create mode 100644 content/practices/practices.html delete mode 100644 content/shared/js/notice.html create mode 100644 content/shared/templates/example-usage-warning.html diff --git a/content/about/about.html b/content/about/about.html index 5b2b9e3ab9..6403a4e07d 100644 --- a/content/about/about.html +++ b/content/about/about.html @@ -7,15 +7,15 @@ - - - - + + + +

About

- +

Introduction

@@ -55,7 +55,7 @@

Introduction

Change History

- +

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 @@

Change History

- +

Acknowledgements

Editors

@@ -232,7 +232,7 @@

Other commenters a
  • Christopher Tryens

    • -
    +

    References

    @@ -293,7 +293,7 @@

    Informative references

    - +
    diff --git a/content/about/coverage-and-quality/coverage-and-quality-report.html b/content/about/coverage-and-quality/coverage-and-quality-report.html index 292aa7d4e3..6679f54b4a 100644 --- a/content/about/coverage-and-quality/coverage-and-quality-report.html +++ b/content/about/coverage-and-quality/coverage-and-quality-report.html @@ -118,45 +118,45 @@

    Roles with at Least One Guidance or Exampl alertdialog - Alert Dialog + Alert Dialog article - Feed + Feed columnheader - Table + Table complementary - Complementary + Complementary Complementary Landmark feed - Feed Pattern + Feed Pattern - Feed + Feed link - Link Pattern + Link Pattern - Link + Link main - Main + Main Main Landmark @@ -164,18 +164,18 @@

    Roles with at Least One Guidance or Exampl menuitemcheckbox - Editor Menubar + Editor Menubar rowgroup - Table + Table search - Search + Search Search Landmark @@ -183,20 +183,20 @@

    Roles with at Least One Guidance or Exampl separator - Editor Menubar + Editor Menubar tooltip - Tooltip Pattern + Tooltip Pattern treegrid - Treegrid Pattern + Treegrid Pattern - Treegrid Email Inbox + Treegrid Email Inbox @@ -217,23 +217,23 @@

    Roles with More than One Guidance or Exa alert banner - Banner + Banner @@ -241,61 +241,61 @@

    Roles with More than One Guidance or Exa button cell - Table + Table checkbox - Checkbox Pattern + Checkbox Pattern combobox contentinfo - Contentinfo + Contentinfo @@ -303,22 +303,22 @@

    Roles with More than One Guidance or Exa dialog form Form Landmark @@ -327,17 +327,17 @@

    Roles with More than One Guidance or Exa grid @@ -345,76 +345,76 @@

    Roles with More than One Guidance or Exa gridcell group listbox menu menubar - Menu and Menubar Pattern + Menu and Menubar Pattern @@ -422,11 +422,11 @@

    Roles with More than One Guidance or Exa menuitem @@ -434,34 +434,34 @@

    Roles with More than One Guidance or Exa menuitemradio meter - Meter + Meter navigation @@ -470,13 +470,13 @@

    Roles with More than One Guidance or Exa none @@ -484,25 +484,25 @@

    Roles with More than One Guidance or Exa option presentation @@ -510,16 +510,16 @@

    Roles with More than One Guidance or Exa radio @@ -527,23 +527,23 @@

    Roles with More than One Guidance or Exa radiogroup region - Region + Region @@ -552,78 +552,78 @@

    Roles with More than One Guidance or Exa row slider spinbutton - Spinbutton Pattern + Spinbutton Pattern switch - Switch Pattern + Switch Pattern tab - Keyboard Navigation Between Components (The Tab Sequence) + Keyboard Navigation Between Components (The Tab Sequence) table - Table + Table tablist @@ -631,34 +631,34 @@

    Roles with More than One Guidance or Exa tabpanel toolbar - Toolbar + Toolbar tree @@ -666,9 +666,9 @@

    Roles with More than One Guidance or Exa treeitem @@ -708,49 +708,49 @@

    Properties and States with at Least One Gu aria-atomic - Alert + Alert aria-busy - Feed + Feed aria-colcount - Using aria-colcount and aria-colindex + Using aria-colcount and aria-colindex - Data Grid + Data Grid aria-colspan - Defining cell spans using aria-colspan and aria-rowspan + Defining cell spans using aria-colspan and aria-rowspan aria-multiselectable - Listboxes with Rearrangeable Options + Listboxes with Rearrangeable Options aria-orientation - Vertical Temperature Slider + Vertical Temperature Slider aria-owns - Navigation Treeview + Navigation Treeview aria-rowspan - Defining cell spans using aria-colspan and aria-rowspan + Defining cell spans using aria-colspan and aria-rowspan @@ -771,20 +771,20 @@

    Properties and States with More than One aria-activedescendant - Managing Focus in Composites Using aria-activedescendant + Managing Focus in Composites Using aria-activedescendant @@ -792,11 +792,11 @@

    Properties and States with More than One aria-autocomplete @@ -804,53 +804,53 @@

    Properties and States with More than One aria-checked aria-colindex - Data Grid + Data Grid aria-controls @@ -858,25 +858,25 @@

    Properties and States with More than One aria-current aria-describedby - Describing by referencing content with aria-describedby + Describing by referencing content with aria-describedby @@ -884,9 +884,9 @@

    Properties and States with More than One aria-disabled @@ -894,28 +894,28 @@

    Properties and States with More than One aria-expanded @@ -923,15 +923,15 @@

    Properties and States with More than One aria-haspopup @@ -939,87 +939,87 @@

    Properties and States with More than One aria-hidden aria-label - Naming with a String Attribute Via aria-label + Naming with a String Attribute Via aria-label aria-labelledby - Naming with Referenced Content Via aria-labelledby - - diff --git a/content/patterns/button/examples/button_idl.html b/content/patterns/button/examples/button_idl.html index 7a3aacb557..1f02852c80 100644 --- a/content/patterns/button/examples/button_idl.html +++ b/content/patterns/button/examples/button_idl.html @@ -30,7 +30,7 @@

    Button Examples (IDL Version)

    About This example

    -

    The following examples of the Button Pattern demonstrate a new JavaScript syntax for coding ARIA attributes.

    +

    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. 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 index f77920cde5..b9cba1a81b 100644 --- a/content/patterns/checkbox/checkbox-pattern.html +++ b/content/patterns/checkbox/checkbox-pattern.html @@ -18,11 +18,7 @@

    Checkbox Pattern

    About This Pattern

    -

    WAI-ARIA supports two types of checkbox widgets:

    -
      -
    1. Dual-state: The most common type of checkbox, it allows the user to toggle between two choices -- checked and not checked.
      2. -
    2. Tri-state: This type of checkbox supports an additional third state known as partially checked.
      3. -
    +

    WAI-ARIA supports two types of checkbox widgets: dual-state allows the user to toggle between two choices -- checked and not checked -- and tri-state supports an additional third state known as partially checked.

    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/patterns.html b/content/patterns/patterns.html new file mode 100644 index 0000000000..97a3732e8a --- /dev/null +++ b/content/patterns/patterns.html @@ -0,0 +1,12 @@ + + + + + + + Patterns + + + In a future iteration this file will contain a list of all patterns. + + diff --git a/content/patterns/slider/examples/slider-rating.html b/content/patterns/slider/examples/slider-rating.html index 0d3c34e847..4db004d339 100644 --- a/content/patterns/slider/examples/slider-rating.html +++ b/content/patterns/slider/examples/slider-rating.html @@ -41,7 +41,7 @@

    About This Example

    Following is an example of a rating input that demonstrates the Slider Pattern. 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 radio group. + A typical five-star rating widget that allows only five possible values could instead be implemented as a radio group.

    Similar examples include:

      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 index 9a338e61af..5faa840dc7 100644 --- 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,7 @@

      Grid and Table Properties

      Introduction

      -

      To fully present and describe a grid or table, in addition to parsing the headers, rows, and cells using the roles described in the grid pattern or table pattern, assistive technologies need to be able to determine:

      +

      To fully present and describe a grid or table, in addition to parsing the headers, rows, and cells using the roles described in the grid pattern or table pattern, assistive technologies need to be able to determine factors such as the number of rows and columns. Data requirements include:

      • The number of rows and columns.
      • Whether any columns or rows are hidden, e.g., columns 1 through 3 and 5 through 8 are visible but column 4 is hidden.
        • diff --git a/content/practices/names-and-descriptions/names-and-descriptions-practice.html b/content/practices/names-and-descriptions/names-and-descriptions-practice.html index 20c07b8ec5..7da942e2c4 100644 --- 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 @@

        Providing Accessible Names and Descriptions

        Introduction

        - 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 new file mode 100644 index 0000000000..7c4fac74bd --- /dev/null +++ b/content/practices/practices.html @@ -0,0 +1,12 @@ + + + + + + + Practices + + + In a future iteration this file will contain a list of all practices. + + diff --git a/content/shared/css/core.css b/content/shared/css/core.css index 1cfa64e60e..26da70a221 100644 --- 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 index bf9991685a..2681297516 100644 --- a/content/shared/js/app.js +++ b/content/shared/js/app.js @@ -23,28 +23,18 @@ return; } - // 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]; - + // Use app.js link to create example-usage-warning.html link. // Expected outcome '../js/app.js' OR '../../js/app.js' var scriptSource = document .querySelector('[src$="app.js"]') .getAttribute('src'); - // Replace 'app.js' part with 'notice.html' - - var fetchSource = scriptSource.replace('app.js', './notice.html'); - //fetch('https://raw.githack.com/w3c/aria-practices/1228-support-notice/examples/js/notice.html') + var fetchSource = scriptSource.replace( + '/js/app.js', + '/templates/example-usage-warning.html' + ); fetch(fetchSource) .then(function (response) { - // Return notice.html as text + // Return example-usage-warning.html as text return response.text(); }) .then(function (html) { @@ -54,15 +44,11 @@ }) .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; - } + var warningElement = doc.querySelector('details'); + warningElement.classList.add('note'); // Needed for styling // Insert the support notice before the page's h1 var heading = document.querySelector('h1'); - heading.parentNode.insertBefore(noticeElement, heading.nextSibling); + heading.parentNode.insertBefore(warningElement, heading.nextSibling); }); } })(); diff --git a/content/shared/js/notice.html b/content/shared/js/notice.html deleted file mode 100644 index 15e117547f..0000000000 --- a/content/shared/js/notice.html +++ /dev/null @@ -1,21 +0,0 @@ - - - -support notice (template) -

        Read This First

        -
        - The code in this example is not intended for production environments. Before using it for any purpose, read this to understand why. -

        Note: This is an illustrative example of one way of using ARIA that conforms with the ARIA specification.

        - -
        - diff --git a/content/shared/templates/example-usage-warning.html b/content/shared/templates/example-usage-warning.html new file mode 100644 index 0000000000..4d41cd8464 --- /dev/null +++ b/content/shared/templates/example-usage-warning.html @@ -0,0 +1,30 @@ + + + + Support Notice (Template) + +
        + +

        + The code in this example is not intended for production environments. + Before using it for any purpose, read this to understand why. +

        +         +

        This is an illustrative example of one way of using ARIA that conforms with the ARIA specification.

        + +
        + + diff --git a/scripts/coverage-report.js b/scripts/coverage-report.js index fcad1db6dd..2244b571da 100644 --- a/scripts/coverage-report.js +++ b/scripts/coverage-report.js @@ -12,17 +12,22 @@ const glob = require('glob'); const cheerio = require('cheerio'); const HTMLParser = require('node-html-parser'); -const coverageReportPath = path.join( +const joinPaths = (...segments) => { + // Normalize paths to avoid backslash-based paths on Windows + return path.join(...segments).replace(/\\/g, '/'); +}; + +const coverageReportPath = joinPaths( __dirname, '../content/about/coverage-and-quality/coverage-and-quality-report.html' ); -const templatePath = path.join(__dirname, 'coverage-report.template'); +const templatePath = joinPaths(__dirname, 'coverage-report.template'); -const csvRoleFilePath = path.join( +const csvRoleFilePath = joinPaths( __dirname, '../content/about/coverage-and-quality/role-coverage.csv' ); -const csvPropFilePath = path.join( +const csvPropFilePath = joinPaths( __dirname, '../content/about/coverage-and-quality/prop-coverage.csv' ); @@ -445,7 +450,7 @@ function getExampleCodeId(html) { // Index roles, properties and states used in examples glob .sync('content/patterns/!(landmarks)/examples/**/!(index).html', { - cwd: path.join(__dirname, '..'), + cwd: joinPaths(__dirname, '..'), nodir: true, }) .forEach(function (file) { @@ -472,7 +477,7 @@ glob src.indexOf('app.js') < 0 ) { console.log(' [script]: ' + src); - dataJS += fs.readFileSync(path.join(dir, src), 'utf8'); + dataJS += fs.readFileSync(joinPaths(dir, src), 'utf8'); } dataJS += ' '; } @@ -487,12 +492,12 @@ glob href.indexOf('all.css') < 0 ) { console.log(' [link]: ' + href); - dataCSS += fs.readFileSync(path.join(dir, href), 'utf8'); + dataCSS += fs.readFileSync(joinPaths(dir, href), 'utf8'); } dataCSS += ' '; } - let ref = path.join('../../..', file); + let ref = joinPaths('../../..', file); let title = html .querySelector('title') .textContent.split('|')[0] @@ -673,11 +678,11 @@ function getRolesPropertiesAndStatesFromGuidance(html, url) { } const patternFiles = glob.sync('content/patterns/!(landmarks)/*-pattern.html', { - cwd: path.join(__dirname, '..'), + cwd: joinPaths(__dirname, '..'), }); const practiceFiles = glob.sync('content/practices/*/*-practice.html', { - cwd: path.join(__dirname, '..'), + cwd: joinPaths(__dirname, '..'), }); const guidanceFiles = [...patternFiles, ...practiceFiles]; @@ -687,7 +692,7 @@ guidanceFiles.forEach(function (file) { let html = HTMLParser.parse(data); - getRolesPropertiesAndStatesFromGuidance(html, path.join('../../../', file)); + getRolesPropertiesAndStatesFromGuidance(html, joinPaths('../../../', file)); }); // Add landmark examples, since they are a different format From 2141c2c36c7602ce18f61191b0b1db6e113a77f8 Mon Sep 17 00:00:00 2001 From: alflennik Date: Thu, 10 Nov 2022 16:11:16 -0500 Subject: [PATCH 02/14] Apply checkbox fixes from PR 2518 --- content/patterns/checkbox/examples/js/checkbox.js | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/content/patterns/checkbox/examples/js/checkbox.js b/content/patterns/checkbox/examples/js/checkbox.js index 303f854c4f..fd5001a2e5 100644 --- 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(); } } From 4cc3623cd6aaff8d9d84ecb48ddd3c33b49d51d9 Mon Sep 17 00:00:00 2001 From: alflennik Date: Thu, 10 Nov 2022 21:15:15 -0500 Subject: [PATCH 03/14] Support spec links without Respec --- .eslintrc.json | 8 ++ .../patterns/checkbox/examples/checkbox.html | 2 +- content/shared/js/app.js | 70 ++++++++--------- content/shared/js/specLinks.js | 78 +++++++++++++++++++ .../templates/example-usage-warning.html | 2 +- 5 files changed, 119 insertions(+), 41 deletions(-) create mode 100644 content/shared/js/specLinks.js diff --git a/.eslintrc.json b/.eslintrc.json index e8e3bc1df3..09eeabbcb3 100644 --- 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.js" ], + "parserOptions": { "sourceType": "module" } } ] } diff --git a/content/patterns/checkbox/examples/checkbox.html b/content/patterns/checkbox/examples/checkbox.html index 907c06feaa..a30bd7217e 100644 --- a/content/patterns/checkbox/examples/checkbox.html +++ b/content/patterns/checkbox/examples/checkbox.html @@ -29,7 +29,7 @@

        Checkbox Example (Two State)

        About This Example

        -

        This example implements the Checkbox Design Pattern for a two state checkbox using div elements.

        +

        This example implements the Checkbox Pattern for a two state checkbox using div elements.

        Similar examples include:

          diff --git a/content/shared/js/app.js b/content/shared/js/app.js index 2681297516..ccc6fe2d69 100644 --- a/content/shared/js/app.js +++ b/content/shared/js/app.js @@ -6,49 +6,41 @@ // Load syntax highlighting hljs.initHighlightingOnLoad(); - // Add support notice to all examples - window.addEventListener('DOMContentLoaded', addSupportNotice, 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; - } - - // Use app.js link to create example-usage-warning.html link. - // Expected outcome '../js/app.js' OR '../../js/app.js' - var scriptSource = document + // Add usage warning to all examples + window.addEventListener('DOMContentLoaded', addExampleUsageWarning, false); + + // Rewrite links so they point to the proper spec document + window.addEventListener('DOMContentLoaded', resolveSpecLinks, false); + + async function addExampleUsageWarning() { + // Determine we are on an example page + if (!document.location.href.match(/examples\/[^/]+\.html/)) return; + + // Generate the usage warning link using app.js link as a starting point + const scriptSource = document .querySelector('[src$="app.js"]') .getAttribute('src'); - var fetchSource = scriptSource.replace( + const fetchSource = scriptSource.replace( '/js/app.js', '/templates/example-usage-warning.html' ); - fetch(fetchSource) - .then(function (response) { - // Return example-usage-warning.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 warningElement = doc.querySelector('details'); - warningElement.classList.add('note'); // Needed for styling - // Insert the support notice before the page's h1 - var heading = document.querySelector('h1'); - heading.parentNode.insertBefore(warningElement, heading.nextSibling); - }); + + // 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); + } + + async function resolveSpecLinks() { + const { specLinks } = await import('./specLinks.js'); + const fixSpecLink = specLinks({ specStatus: 'ED' }); + document.querySelectorAll('a[href]').forEach(fixSpecLink); } })(); diff --git a/content/shared/js/specLinks.js b/content/shared/js/specLinks.js new file mode 100644 index 0000000000..199462fd49 --- /dev/null +++ b/content/shared/js/specLinks.js @@ -0,0 +1,78 @@ +// This file is an ES module to make it easier to use in both frontend and backend contexts. +// Allows APG authors to easily write links to the correct version of the ARIA specification or other related specs. +// A typical spec link looks like this: button. +// Other classes used for spec links include "property-reference" and "state-reference", and for a complete list, see below. + +const specData = { + ariaSpec: { + classes: [ + 'role-reference', + 'property-reference', + 'state-reference', + 'specref', + ], + statuses: { + ED: 'https://w3c.github.io/aria/', + FPWD: 'https://www.w3.org/TR/wai-aria-1.2/', + WD: 'https://www.w3.org/TR/wai-aria-1.2/', + REC: 'https://www.w3.org/TR/wai-aria/', + }, + }, + accNameURLs: { + classes: ['accname'], + statuses: { + ED: 'https://w3c.github.io/accname/', + WD: 'https://www.w3.org/TR/accname-1.2/', + FPWD: 'https://www.w3.org/TR/accname-1.2/', + REC: 'https://www.w3.org/TR/accname/', + }, + }, + coreMappingURLs: { + classes: ['core-mapping'], + statuses: { + ED: 'https://w3c.github.io/core-aam/', + WD: 'https://www.w3.org/TR/core-aam-1.2/', + FPWD: 'https://www.w3.org/TR/core-aam-1.2/', + REC: 'https://www.w3.org/TR/core-aam/', + }, + }, + htmlMappingURLs: { + classes: ['html-mapping'], + statuses: { + ED: 'https://w3c.github.io/html-aam/', + WD: 'https://www.w3.org/TR/html-aam-1.0/', + FPWD: 'https://www.w3.org/TR/html-aam-1.0/', + REC: 'https://www.w3.org/TR/html-aam-1.0/', + }, + }, +}; + +// Must be initialized with a spec status, which determines which spec link to use. +// When in doubt, use ED (Editor's Draft). +const specLinks = ({ specStatus }) => { + const baseUrls = Object.fromEntries( + Object.entries(specData).map(([spec, { statuses }]) => [ + spec, + statuses[specStatus], + ]) + ); + + // Returns a function which can be run over any link elements, and will correct the urls in the case the link is a spec link. + const fixSpecLink = (a) => { + const className = a.getAttribute('class'); + + const specClasses = Object.entries(specData).find(([, { classes }]) => + classes.includes(className) + ); + const spec = specClasses && specClasses[0]; + + if (spec) { + const currentHref = a.getAttribute('href'); + a.setAttribute('href', `${baseUrls[spec]}${currentHref}`); + } + }; + + return fixSpecLink; +}; + +export { specLinks }; diff --git a/content/shared/templates/example-usage-warning.html b/content/shared/templates/example-usage-warning.html index 4d41cd8464..e081775b8c 100644 --- a/content/shared/templates/example-usage-warning.html +++ b/content/shared/templates/example-usage-warning.html @@ -3,7 +3,7 @@ Support Notice (Template) -
          +

          The code in this example is not intended for production environments. From dcab965af04f476b9e6b029cd4bb60ae9f02b9a8 Mon Sep 17 00:00:00 2001 From: alflennik Date: Thu, 10 Nov 2022 21:28:26 -0500 Subject: [PATCH 04/14] Make spec link fixer usable in node scripts --- content/shared/js/{specLinks.js => specLinks.mjs} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename content/shared/js/{specLinks.js => specLinks.mjs} (100%) diff --git a/content/shared/js/specLinks.js b/content/shared/js/specLinks.mjs similarity index 100% rename from content/shared/js/specLinks.js rename to content/shared/js/specLinks.mjs From ef77670f7f9377110aaea06badb713a9e4512d1b Mon Sep 17 00:00:00 2001 From: alflennik Date: Thu, 10 Nov 2022 22:33:24 -0500 Subject: [PATCH 05/14] Make spec link fixer usable in node scripts pt 2 --- .eslintrc.json | 2 +- content/shared/js/app.js | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/.eslintrc.json b/.eslintrc.json index 09eeabbcb3..7e40af6dbc 100644 --- a/.eslintrc.json +++ b/.eslintrc.json @@ -69,7 +69,7 @@ "parserOptions": { "ecmaVersion": 11 } }, { - "files": [ "content/shared/js/specLinks.js" ], + "files": [ "content/shared/js/specLinks.mjs" ], "parserOptions": { "sourceType": "module" } } ] diff --git a/content/shared/js/app.js b/content/shared/js/app.js index ccc6fe2d69..65e55ea2f0 100644 --- a/content/shared/js/app.js +++ b/content/shared/js/app.js @@ -39,7 +39,7 @@ } async function resolveSpecLinks() { - const { specLinks } = await import('./specLinks.js'); + const { specLinks } = await import('./specLinks.mjs'); const fixSpecLink = specLinks({ specStatus: 'ED' }); document.querySelectorAll('a[href]').forEach(fixSpecLink); } From 8219af3e0716e9e379967feebacd66c0d2502328 Mon Sep 17 00:00:00 2001 From: alflennik Date: Thu, 10 Nov 2022 22:40:08 -0500 Subject: [PATCH 06/14] Fix spelling failure --- cspell.json | 1 + 1 file changed, 1 insertion(+) diff --git a/cspell.json b/cspell.json index 9fccf82ea6..36a32fb03d 100644 --- a/cspell.json +++ b/cspell.json @@ -287,6 +287,7 @@ "**/*.paint", "content/shared/css/github.css", "content/shared/js/skipto.js", + "content/shared/js/specLinks.mjs", "content/patterns/landmarks/examples/css/bootstrap.css", "content/patterns/landmarks/examples/css/bootstrap-theme.css", "content/patterns/landmarks/examples/js/visua11y.js", From ea1095534c5011874c26a913662ba3fc14671279 Mon Sep 17 00:00:00 2001 From: Matt King Date: Fri, 11 Nov 2022 15:00:35 -0800 Subject: [PATCH 07/14] Editorial revision to checkbox description --- content/patterns/checkbox/checkbox-pattern.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/patterns/checkbox/checkbox-pattern.html b/content/patterns/checkbox/checkbox-pattern.html index b9cba1a81b..53d9f8e0bd 100644 --- a/content/patterns/checkbox/checkbox-pattern.html +++ b/content/patterns/checkbox/checkbox-pattern.html @@ -18,7 +18,7 @@

          Checkbox Pattern

          About This Pattern

          -

          WAI-ARIA supports two types of checkbox widgets: dual-state allows the user to toggle between two choices -- checked and not checked -- and tri-state supports an additional third state known as partially checked.

          +

          WAI-ARIA supports two types of checkbox 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.

          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. From e41a28fb4333d60b896dcd5de61b74ad23cb9d51 Mon Sep 17 00:00:00 2001 From: Matt King Date: Fri, 11 Nov 2022 15:16:22 -0800 Subject: [PATCH 08/14] Editorial revision to intro of grid and table properties practice --- .../grid-and-table-properties-practice.html | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) 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 index 5faa840dc7..972cb95544 100644 --- 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 @@

          Grid and Table Properties

          Introduction

          -

          To fully present and describe a grid or table, in addition to parsing the headers, rows, and cells using the roles described in the grid pattern or table pattern, assistive technologies need to be able to determine factors such as the number of rows and columns. Data requirements include:

          +

          + To fully present and describe a grid or table, in addition to parsing the headers, rows, and cells using the roles described in the grid pattern or table pattern, 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: +

          • The number of rows and columns.
          • Whether any columns or rows are hidden, e.g., columns 1 through 3 and 5 through 8 are visible but column 4 is hidden.
            • From a7d1de8009f29779da49b393ce9d1ad09dd51489 Mon Sep 17 00:00:00 2001 From: alflennik Date: Wed, 16 Nov 2022 14:17:17 -0500 Subject: [PATCH 09/14] Fix broken links --- .../alertdialog/examples/alertdialog.html | 2 +- .../names-and-descriptions-practice.html | 16 ++++++++-------- 2 files changed, 9 insertions(+), 9 deletions(-) diff --git a/content/patterns/alertdialog/examples/alertdialog.html b/content/patterns/alertdialog/examples/alertdialog.html index c131c11f34..4a8921deac 100644 --- a/content/patterns/alertdialog/examples/alertdialog.html +++ b/content/patterns/alertdialog/examples/alertdialog.html @@ -46,7 +46,7 @@

            About This Example

          • Activate the "save" button to trigger an alert when the contents of the "Notes" text area is saved to - local storage. + local storage.
            • A successful save triggers a short alert to notify the user that the notes have been saved.
            • The "save" button is disabled if the user's local storage value is the same as the "Notes" field.
              • diff --git a/content/practices/names-and-descriptions/names-and-descriptions-practice.html b/content/practices/names-and-descriptions/names-and-descriptions-practice.html index 7da942e2c4..a1ec16ce7b 100644 --- a/content/practices/names-and-descriptions/names-and-descriptions-practice.html +++ b/content/practices/names-and-descriptions/names-and-descriptions-practice.html @@ -584,7 +584,7 @@

              Accessible Name Guidance by Role
            • Named using aria-labelledby if a visible label is present, otherwise with aria-label.
              • -
            • See the Banner Landmark section.
              • +
            • See the Banner Landmark section.

            @@ -687,7 +687,7 @@

            Accessible Name Guidance by RoleNaming is necessary when two complementary landmark regions are present on the same page.

          • Naming is recommended even when one complementary region is present to help users understand the purpose of the region's content when navigating among landmark regions.
          • Use aria-labelledby if a visible label is present, otherwise use aria-label.
            • -
          • See the Complementary Landmark section.
            • +
          • See the Complementary Landmark section.
          @@ -796,7 +796,7 @@

          Accessible Name Guidance by Role
        • Helps screen reader users understand the context and purpose of the form landmark.
        • Use aria-labelledby if a visible label is present, otherwise use aria-label.
          • -
        • See the Form Landmark section.
          • +
        • See the Form Landmark section.

        @@ -948,7 +948,7 @@

        Accessible Name Guidance by Role
      • Potentially helpful for orienting assistive technology users, especially in single-page applications where main content changes happen without generating a page load event.
      • Can be named using aria-labelledby if a visible label is present, otherwise with aria-label.
        • -
      • See the Main Landmark section.
        • +
      • See the Main Landmark section.

      @@ -1065,7 +1065,7 @@

      Accessible Name Guidance by Role
    • Helps screen reader users understand the context and purpose of the navigation landmark.
    • Use aria-labelledby if a visible label is present, otherwise use aria-label.
      • -
    • See the Navigation Landmark section.
      • +
    • See the Navigation Landmark section.

    @@ -1166,7 +1166,7 @@

    Accessible Name Guidance by Role
  • Helps screen reader users understand the context and purpose of the landmark.
  • Use aria-labelledby if a visible label is present, otherwise use aria-label.
    • -
  • See the Region Landmark section.
    • +
  • See the Region Landmark section.
    • @@ -1176,7 +1176,7 @@

    Accessible Name Guidance by Role Required Only If Content Insufficient AND descendant of a treegrid AND the row is focusable - When row elements are focusable in a treegrid, screen readers announce the entire contents of a row when navigating by row. + When row elements are focusable in a treegrid, screen readers announce the entire contents of a row when navigating by row. This is typically the most appropriate behavior. However, in some circumstances, it could be beneficial to change the order in which cells are announced or exclude announcement of certain cells by using aria-labelledby to specify which cells to announce. @@ -1225,7 +1225,7 @@

    Accessible Name Guidance by Role
  • Helps screen reader users understand the context and purpose of the search landmark.
  • Named using aria-labelledby if a visible label is present, otherwise with aria-label.
    • -
  • See the Search Landmark section.
    • +
  • See the Search Landmark section.
    • From 2b6a26bcb628e8256820e4d683416a5c49c1cbf2 Mon Sep 17 00:00:00 2001 From: alflennik Date: Wed, 16 Nov 2022 17:05:35 -0500 Subject: [PATCH 10/14] Address PR 2537 feedback --- content/{index.html => apg-home.html} | 50 +++--------------- {img => content/images}/DHTMLexample.png | Bin .../images}/accessibleJSelement.png | Bin {img => content/images}/accessibleelement.png | Bin {img => content/images}/exampletree.png | Bin {img => content/images}/index-1.svg | 0 {img => content/images}/index-2.svg | 0 {img => content/images}/index-3.svg | 0 {img => content/images}/index-4.svg | 0 {img => content/images}/index-5.svg | 0 {img => content/images}/index-6.svg | 0 {img => content/images}/index-7.svg | 0 {img => content/images}/index-8.svg | 0 {img => content/images}/inspectofpagetab.png | Bin {img => content/images}/navlandmark.jpg | Bin {img => content/images}/taxonomy.png | Bin .../breadcrumb/examples/breadcrumb.html | 2 +- 17 files changed, 9 insertions(+), 43 deletions(-) rename content/{index.html => apg-home.html} (69%) rename {img => content/images}/DHTMLexample.png (100%) rename {img => content/images}/accessibleJSelement.png (100%) rename {img => content/images}/accessibleelement.png (100%) rename {img => content/images}/exampletree.png (100%) rename {img => content/images}/index-1.svg (100%) rename {img => content/images}/index-2.svg (100%) rename {img => content/images}/index-3.svg (100%) rename {img => content/images}/index-4.svg (100%) rename {img => content/images}/index-5.svg (100%) rename {img => content/images}/index-6.svg (100%) rename {img => content/images}/index-7.svg (100%) rename {img => content/images}/index-8.svg (100%) rename {img => content/images}/inspectofpagetab.png (100%) rename {img => content/images}/navlandmark.jpg (100%) rename {img => content/images}/taxonomy.png (100%) diff --git a/content/index.html b/content/apg-home.html similarity index 69% rename from content/index.html rename to content/apg-home.html index aecb3b2ff3..4dc3c07c83 100644 --- a/content/index.html +++ b/content/apg-home.html @@ -22,7 +22,7 @@

    ARIA Authoring Practices Guide (APG) Home

    It provides design patterns and functional examples complemented by in-depth guidance for fundamental practices.

    View Patterns - A laptop screen fills with an accessibility icon and emits a checkmark. + A laptop screen fills with an accessibility icon and emits a checkmark.

    APG Resources

    @@ -35,59 +35,25 @@

    Design Patterns and Examples

    One or more ways of implementing each pattern is demonstrated with a functional example.

    Learn More - A menagerie of widgets. + A menagerie of widgets.

  • Use ARIA Landmarks

    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.

    Learn More - A document flies apart into chunks. + A document flies apart into chunks.

  • Providing Accessible Names and Descriptions

    Providing elements with accessible names and, where appropriate, accessible descriptions is one of the most important responsibilities authors have when developing accessible web experiences.

    Learn More - Indicators delve inside a document. + Indicators delve inside a document.

  • And So Much More...

    Learn about other fundamental practices related to correctly using accessibility semantics, developing keyboard interfaces, and more.

    Learn More - A box with an accessibility label is chock full of widgets and document bits. -
    • - -
    - -
    - -

    Current Work

    -

    Check out recent work of the APG Task Force

    -
      -
    • -

      Release Plans

      -

      Take a look at the plan overview for WAI-ARIA Authoring Practices, priorities and work in progress.

      - Learn More -
      • -
    • -

      Patterns Progress Status

      -

      Status of work on design patterns and reference implementations of those patterns for the first release of the ARIA 1.1 Authoring Practices.

      - Learn More -
      • -
    • -

      How to Write Regression Tests

      -

      Learn what the APG Regression Tests test, how to run them and understand the results.

      - Learn More -
      • -
    • -

      Meetings

      -

      - The APG Task Force meets on Tuesdays at 14:00 until 15:00 Eastern Time. - Minutes from previous meetings are available. -

      - Learn More + A box with an accessibility label is chock full of widgets and document bits.
    @@ -106,7 +72,7 @@

    Join the Task Force

    Participants are expected to actively contribute to the work of the task force.

    Learn more about the work of the task force and how to join - An icon showing three nodes connecting. + An icon showing three nodes connecting.

  • Contribute via GitHub

    @@ -115,7 +81,7 @@

    Contribute via GitHub

    If you choose this path, please start by studying our guidelines for contributing to the repository and maintaining code quality.

    View ReadMe in the GitHub repository - An icon showing two human shapes carrying a burden. + An icon showing two human shapes carrying a burden.

  • Mailing Lists

    @@ -125,7 +91,7 @@

    Mailing Lists

    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.

    View the aria-practices mailing list archive

    - A notification bell icon appears over an email icon. + A notification bell icon appears over an email icon.
    • diff --git a/img/DHTMLexample.png b/content/images/DHTMLexample.png similarity index 100% rename from img/DHTMLexample.png rename to content/images/DHTMLexample.png diff --git a/img/accessibleJSelement.png b/content/images/accessibleJSelement.png similarity index 100% rename from img/accessibleJSelement.png rename to content/images/accessibleJSelement.png diff --git a/img/accessibleelement.png b/content/images/accessibleelement.png similarity index 100% rename from img/accessibleelement.png rename to content/images/accessibleelement.png diff --git a/img/exampletree.png b/content/images/exampletree.png similarity index 100% rename from img/exampletree.png rename to content/images/exampletree.png diff --git a/img/index-1.svg b/content/images/index-1.svg similarity index 100% rename from img/index-1.svg rename to content/images/index-1.svg diff --git a/img/index-2.svg b/content/images/index-2.svg similarity index 100% rename from img/index-2.svg rename to content/images/index-2.svg diff --git a/img/index-3.svg b/content/images/index-3.svg similarity index 100% rename from img/index-3.svg rename to content/images/index-3.svg diff --git a/img/index-4.svg b/content/images/index-4.svg similarity index 100% rename from img/index-4.svg rename to content/images/index-4.svg diff --git a/img/index-5.svg b/content/images/index-5.svg similarity index 100% rename from img/index-5.svg rename to content/images/index-5.svg diff --git a/img/index-6.svg b/content/images/index-6.svg similarity index 100% rename from img/index-6.svg rename to content/images/index-6.svg diff --git a/img/index-7.svg b/content/images/index-7.svg similarity index 100% rename from img/index-7.svg rename to content/images/index-7.svg diff --git a/img/index-8.svg b/content/images/index-8.svg similarity index 100% rename from img/index-8.svg rename to content/images/index-8.svg diff --git a/img/inspectofpagetab.png b/content/images/inspectofpagetab.png similarity index 100% rename from img/inspectofpagetab.png rename to content/images/inspectofpagetab.png diff --git a/img/navlandmark.jpg b/content/images/navlandmark.jpg similarity index 100% rename from img/navlandmark.jpg rename to content/images/navlandmark.jpg diff --git a/img/taxonomy.png b/content/images/taxonomy.png similarity index 100% rename from img/taxonomy.png rename to content/images/taxonomy.png diff --git a/content/patterns/breadcrumb/examples/breadcrumb.html b/content/patterns/breadcrumb/examples/breadcrumb.html index ce560a84eb..49c8d21089 100644 --- a/content/patterns/breadcrumb/examples/breadcrumb.html +++ b/content/patterns/breadcrumb/examples/breadcrumb.html @@ -40,7 +40,7 @@

    Example