Document APG example modification process

[jscholes]

When examples are pulled into the ARIA-AT repo from aria-practices, we currently modify them as follows:

1. Remove core JS/CSS references from the head section of the example HTML file. This avoids errors with trying to pull in CSS/JS which is common to all APG examples but doesn't exist in the ARIA-AT repo, makes sure we don't get the CodePen button, etc.
2. Remove any CSS, JS and image asset files pulled in by the update-reference script which the example doesn't actually need.
3. Remove the "Related Links" nav and similar example links.
4. Remove any unnecessary text from the preamble. Usually, this involves leaving the first paragraph describing the pattern intact, but getting rid of everything else.
5. Update the href of the <a> linking to the design pattern in the APG, to reference https://w3c.github.com/aria-practices, rather than a relative, repo-specific path like ../../#something).
6. Remove the "Accessibility Features", "Keyboard Support", "Role, Property, State, and Tabindex Attributes" and source code sections.
7. Remove the nav at the bottom of the example (after the main).
8. Update the page title to remove the reference to the WAI-ARIA version, because the examples in the ARIA-AT repo are pulled in from the main APG branch and versioned via a timestamped directory instead.
9. Add links before and after the component after test, to be used in setup scripts.

The above is quite a bit of work, but can also be complicated by different examples following different structures or relying on assets that others do not. For example, modifying the Data Grid Examples for PR #393 involved more work, because:

1. The code powering the grids seems to rely on shared functionality from utils.js. As this is a file shared by multiple APG examples and therefore not a child of the grid directory, the update-reference script didn't pull it in to begin with.
2. The example page has multiple data grids, some of which have more functionality than the first relatively simple one that was actually under test. This required more care and testing to determine which assets were needed by all grids or only some of them, e.g. the CSS contained references to image files that were only needed by the second and third grids.
3. The example could only be successfully tested while running a local HTTP server, because some of the bundled assets used functionality that is disallowed by a browser when executing JS from a local file.

Finally, it should be noted that the update-reference script does print some instructions for test writers, as follows:

Open the html file and edit it to only include the example. The title, imported assets, h1 with the example name, and the div with the actual example (Usually #ex1) need to be preserved, but everything else can be removed.

Obviously, the reality is a bit more nuanced. So based on the outcomes of this issue and related discussion, I'd love for the script to link to a relevant wiki page instead.

CC @sinabahram

[jscholes]

Additional note: we'd eventually like a script to do at least some of this work. Given some of the complexities captured in the preceding comment, it's unlikely that it could be completely automated at this time, and that commitment to a certain amount of standardisation from the APG will be required.

[jscholes]

Notes from the March 18, 2021 CG meeting:

1. In order to increase consistency, facilitate more automation, etc., there are probably crossovers with/implications posed by the APG redesign project.
2. APG ultimately only want to have one thematic example per page.
3. When an APG example includes multiple widgets which are thematically related (like two radio groups both relating to pizza or three sliders forming a colour picker), we should only test one of them but not remove the others.
4. Removing controls is necessary when they are not thematically related, e.g. the Buttons example which has two unrelated controls: an actionable command button and a toggle. Although as per point #1, this shouldn't be an issue in the future.
5. Is some sort of API appropriate to pull down parts of APG examples in for embedding?
   • This couldn't use an iframe, setup scripts would be blocked from running and links before/after a component couldn't be added.
   • How would we pull in a specific version of an APG example matching the assertions of a particular test plan, even when the example was updated on the APG side?
   • How would we facilitate updating the targeted APG example version in a test plan when ready?
6. It may help to think about the APG as a dependency, a source of content which is being tested, with other dependencies for other sources. Does that imply that all APG modifications would happen dynamically, and APG content wouldn't live inside this aria-at repo at all?