Add coverage report of roles, properties, and states for Issue 1123

[jongund]

For issue #1123, adds a script that creates an index.html file in a coverage directory.

The report includes 2 lists and 4 tables:

1. Roles with no guidance or examples (list)
2. Roles with at least one guidance or example
3. Roles with more than one guidance or example
4. Properties and states with no guidance or examples (list)
5. Properties and states with at least one guidance or example
6. Properties and states with more than one guidance or example

There are also two CSV files generated, one for roles and one for properties and states. These files are linked from the HTML file and are also in the coverage directory.

Usage

Use the following command to generate the index and CSV files:

node scripts/coverage.js

View Coverage Report

Preview link of ARIA role, properties and states report

Data Attributes for creating Guidance References

The following attributes can be placed on headings in the practices document to indicate the presence of guidance for an aria role, property or state:

• data-aria-roles : Space separated role values on a heading in the practices document
• data-aria-props: Space separated property and state values on a heading in the practices document

---

Preview | Diff

[jongund]

@mcking65 @jnurthen

I updated the script to include references to the guidance in the practices document and added another column to the tables and the CSV files for the guidance references. It bases guidance references on either the content of a heading or a data attribute on a heading in the practices. See the report for more information. I added a few data attributes to the practices as a proof of concept.

[carmacleod]

Something like this would be really useful as an appendix in the APG document. Particularly the list of examples where a feature is actually used! :)

Are we considering this? If we are, maybe just have 2 complete tables - one for all roles and one for all states/props - including those with no guidance or examples yet.

[css-meeting-bot]

The ARIA Authoring Practices (APG) Task Force just discussed Coverage report.

The full IRC log of that discussion

<MarkMccarthy> TOPIC: Coverage report
<carmacleod> https://github.com//pull/1124
<carmacleod> github: https://github.com//pull/1124
<MarkMccarthy> Matt_King: jongund, can you summarize to catch everyone up?
<MarkMccarthy> Matt_King: or with any recent changes?
<MarkMccarthy> jongund: basically,the script goes through guidelines and examples to see how many times properties are referenced
<MarkMccarthy> jongund: right now, looking at examples because i didn't want to include some data-attrs and have that complexity too
<Jemma> https://raw.githack.com/w3c/aria-practices/issue1123-roles-properties-states-coverage-report-script/coverage/index.html
<jongund> https://raw.githack.com/w3c/aria-practices/issue1123-roles-properties-states-coverage-report-script/coverage/index.html
<MarkMccarthy> jongund: looking at the preview link --
<MarkMccarthy> Matt_King: what were the data-attributes?
<MarkMccarthy> jongund: data-aria-roles, data-aria-props, and adding the role or property you want referenced
<MarkMccarthy> jongund: could be simpler, that's what we have now
<MarkMccarthy> Matt_King: put on heading tags right?
<MarkMccarthy> jongund: yeah, need an ID and the headings have IDs
<MarkMccarthy> Matt_King: we should make sure we have IDs on the ones we want to reference then
<MarkMccarthy> jongund: in the report, it'll append a little ) D to things it adds. it'll get included in the report if it finds what it's looking for
<MarkMccarthy> jongund: first table is no guidance; in the second table, there's at least one guidance or example, third table is more than one example. same is repeated for properties
<MarkMccarthy> Matt_King: in the cell for complimentary, for example, it'd be helpful to have the actual heading in the cell.
<MarkMccarthy> jongund: the numbering is generated right?
<MarkMccarthy> Matt_King: yeah that comes from respec, so you might not be able to pull that out
<MarkMccarthy> jongund: we could add something related to the next-highest level heading or something as a tooltip, to give some context
<MarkMccarthy> jongund: if it's coming from a practices doc anyway
<Jemma> q+
<MarkMccarthy> Matt_King: probably the contents of the heading is probably best we can do right now
<MarkMccarthy> jongund: yup
<MarkMccarthy> jongund: that entire column is from practices; would it be better to be called something else?
<MarkMccarthy> Matt_King: no it's okay
<MarkMccarthy> Jemma: gudiance goes to design patterns
<MarkMccarthy> s/gudiance/guidance
<MarkMccarthy> Matt_King: this is helpful for planning, and we can use this same logic to enhance our index. we have indicies of examples but not guidance.
<MarkMccarthy> Matt_King: once we have this include everything we want, we can use this same thing to index our guidance
<MarkMccarthy> Matt_King: it'd be more useful to have the full section...but i don't know how we'd do that
<MarkMccarthy> carmacleod: an appendix?
<MarkMccarthy> Matt_King: yeah, but i don't know how we'd get the section numbers
<MarkMccarthy> carmacleod: i don't think it'd -need- the section numbers, esp if there's a link
<MarkMccarthy> Jemma: this is great, i'll use this a lot once we have it in spec!
<MarkMccarthy> Jemma: what is the implication of having the data-XXX information for the -readers- rather than us as internal users?
<MarkMccarthy> jongund: just to document how these attrs etc. can be added, and we need that documentation somewhere. i did this assuming it'd be for the WG's use
<MarkMccarthy> Matt_King: yes
<MarkMccarthy> ack Jemma
<MarkMccarthy> Matt_King: might put into our editorial guidelines
<MarkMccarthy> Matt_King: next step is, once we have this report and capability, we can leverage it to make an index for the main document
<MarkMccarthy> Matt_King: about roles, states, and properties
<MarkMccarthy> Jemma: got it. might be good to have a counter in the first part of the list - so, how many of each item there are for example (like 22 items with no guidance, etc.)
<MarkMccarthy> jongund: like an index in the beginning?
<MarkMccarthy> Jemma: yeah, might make it easier to understand
<MarkMccarthy> jongund: yeah, we could do that.
<MarkMccarthy> Jemma: this is great Jon!
<MarkMccarthy> carmacleod: i think this will be really useful.
<MarkMccarthy> jongund: it was a little more complex before, but I took some of that out to make it easier in the beginning
<MarkMccarthy> Matt_King: yeah, and this makes it safe to merge too
<MarkMccarthy> Matt_King: this script just goes in the scripts directory, right? so i think I can just merge it
<MarkMccarthy> jongund: shouldn't be any conflicts

[carmacleod]

@mcking65 It would be great if this could go in. Almost everything is in a separate "coverage" subfolder (plus one new .js and .template file in the "scripts" folder), so there won't be any merge conflicts or any impact to the main document. It is a useful resource for the TF. I just used the preview to look up which examples use aria-controls. :)

@jongund This should probably have a README.md in the coverage directory (or maybe a new section in the top-level README.md?), so that the info about how to build (i.e. node scripts/coverage.js), and what is being built (i.e. coverage/index.html), is not lost after this PR is merged.