Updates to example and coverage report scripts

[jongund]

The changes in the this pull request:

• Updated list of roles to include new roles in ARIA 1.2:
  • caption
  • code
  • deletion
  • emphasis
  • generic
  • input
  • insertion
  • meter
  • paragraph
• Fixed bug in aria-label also getting references to aria-labelledby, by using a regex, and this was also applied to checking roles.
• Updated code to use node-html-parser for identify the roles, properties and states associated with an example, making the code much easier to read and understand.
• Added the identification of examples with specific high contrast support features, since it only adds a few lines of code to the example and coverage script files.
• Updated coverage report to provide more information on example quality assurance.
• Add a coding practices section to the coverage report to identify use of our APG coding practices.

NOTE: The changes added node-html-parser to the package.json file.

Preview of example index
Preview of coverage report

[smhigley]

I noticed a couple weird things in the generated results, but otherwise it looks good!

[smhigley]

There's something slightly odd here and in a couple other places, where it seems like it's generating duplicate links for several examples (here, and in contentinfo/complementary, and maybe others). I can take a closer look at why that's happening later, if you haven't already gotten to it by then 😄

[jongund]

@smhigley
Seems to be related to landmarks, thanks for finding.

[jongund]

@smhigley
Found the problem and fixed the issues, thank you for pointing them out. Let me know if you see any other issues.

[smhigley]

it looks like the links are using backslash instead of forward-slash now, and I'm not sure why. They should probably use forward slash, but it'd be good to also make sure it won't change based on the OS it's run on.

Also, same as above -- I'm happy to poke at it in a bit, if you haven't already fixed it!

[jongund]

@smhigley
I think the problem is I generated the index.html file on my Windows 10 computer, so I have now used my Mac and it seems to have fixed this problem.

[jongund]

@carmacleod
I added information on the use of mouse and pointer events in the coverage report. Thanks for the suggestion.

[carmacleod]

This is really cool, @jongund !
Approving as-is, but I'm not really a fan of the <abbr title="none" style="color: gray">-</abbr> in some of the tables. I think it looks weird (i.e. what is that funny little grey thing with the line and 2 dots?), plus the hyphen is hard to hover over because it's so tiny. I would prefer either just - as in the other tables, or "none", or just leave the cell empty. Would love to know what value @mcking65 prefers in empty table cells.

[shirsha]

This looks great @jongund.
Everything looks good. This is the only observation I have
Navigate in the virtual mode:

• When "HC" is placed after the tag, the screen reader narrates the "Navigation Treeview with High Contrast Support" followed by "HC". This might be confusing to a screen reader user.
  Note: Currently, expansion is ignored by screen readers like JAWS, NVDA, and VO.

• In the future when expansion is recognized by the screen readers then it will narrate as "Navigation Treeview with High Contrast Support" followed by "High contrast support". This will add extra verbosity.

• I suggest encapsulating the tag inside the tag so that screen readers will only narrate the string in the aria-label attribute( ex: "Navigation Treeview with High Contrast Support") .
  ( or )
  Hide the from the screen reader user.

suggested code change:

Navigation Treeview (HC)

or

Navigation Treeview (HC)

[mcking65]

Taking a look at the preview of the indexes at:
https://raw.githack.com/w3c/aria-practices/update-example-index/examples/index.html

I see quite a few missing entries and some extra entries. It would be helpful to have an organized approach to validating the veracity of the indexes. It may take several people.

Here's a few that are easy to spot.

The list for menuitem looks incomplete. It includes only:

• Editor Menubar
• Navigation Menubar

The list for spinbutton looks incomplete. It includes only toolbar but not the spinbutton examples.

The list for role "tablist" looks incomplete. It doesn't include the carousel that has a tablist.

The list for toolbar looks incomplete. It doesn't include the listbox examples that have a toolbar.

Two examples are listed for the "list" role. List role is not used in these:

• Tabs with Automatic Activation
• Tabs with Manual Activation

4 examples are listed for the "log" role. None of these use the "log" role:

• Date Picker Combobox
• Alert Dialog
• Date Picker Dialog
• Modal Dialog

Five examples are listed for role="table" but only the "Table" example actually uses it:

• Date Picker Combobox
• Date Picker Dialog
• Data Grid
• Table
• Treegrid Email Inbox

There are only 12 states and properties listed in the state and property index. So, most are missing.

The list for aria-controls includes only 3 examples. I'm pretty certain there are more.

The list for aria-disabled has only one example. Accordion includes it (at least for now). I think we used it in the editor menubar as well. There may be others.

The list for aria-expanded does not include any of the menus, trees, or treegrid. There might be others that use it too.

The list for aria-haspopup does not include the menubuttons.

The list for aria-live should be double-checked. We use it in layout grid 2 (unless perhaps that is an alert). We have it in one of the carousels, I think.

The list for aria-modal does not include the modal dialog.

The list for aria-pressed does not include toggle button. I think there are others that may use it too.

The list for aria-valuemin does not include any spinbutton or slider examples.

[mcking65]

I agree with @shirsha about the double reading of high contrast support. The text included in the link text is confusing because it makes it seem like "with high contrast support" is part of the example name. I don't think we should add that to the link text. Having "(HC)" outside the link text is appropriate for everyone. It is not part of the target page title, so it should not be part of the link text. And, including the high contrast support designation in the link text makes the link harder to understand.

[jongund]

@mcking65
Updated coverage report to also look at Javascript to identify ARIA roles, properties and states that should be part of the documentation section of each example.

[smhigley]

Looks good, both the report results and the new approach!

[jongund]

@mcking65
What are the remaining issues with the index and coverage report pull request?

[a11ydoer]

@jongund I am supposed to review the PR. Sorry for the delay. I will finish the review tonight and add the approval if it looks good. In case we need further discussion, this was added to meeting agend for tomorrow, May 4.

[a11ydoer]

Feedback on APG Example Index page

• Role meter is missing in "Examples by Role" section. Here is meter example
• Breadcrumb example has aria-lable and aria-current which were not recorded in the "Example index" page.

Otherwise, it looks great. Thanks so much again for this user centered Example index page implementation, @jongund

[a11ydoer]

Feedback on Coverage report page

1. How about changing heading 1 to be "ARIA Example Coverage report" instead of "ARIA Roles, Properties and States Referenced in Guidance and Examples"?
2. CSV files: Hard to read because multiple number of colunms are added after the "reference" column if there are more than one guidance or examples. (This is a minor issue)
3. "Roles with no guidance or example list" is helpful to see what APG group needs to work on next. Thanks so much @jongund
4. May "Roles with at Least One Guidance or Example (13)" be incoporated into "Roles with More than One Guidance or Example (34)" if the former table is just trying to indicate either guidance or example is missing?
5. "Coding practice" table

• May we add a reference link to APG code-guide wiki under "Coding practice"?
• What does "ARIA Features that are different" mean?
• Can "Example Code ID" be "ID referece for ARIA Example container"?
• What would be the coding practice implication for "roles in documentation" and "aria attributes in documentation" unless they are in HTML and Javascript?
• Can "created using" be "created using Javascript"

[jongund]

I have updated the roles to include roles in ARIA 1.2, including meter role.
The problem with the breadcrumb example not being indexed is the use of the file name "index.html" for the example, all files with "index.html" are ignored in the indexing scripts. So the file name needs to change to something like "breadcrumb.html".

[mcking65]

@jongund
This is some amazing analysis! I love that feature that shows the attributes that show up in the HTML but not in the documentation. Wel,, I love it all, but that was a clever addition for sure. Thank you!! Nothing like shining some light on our work to be done.

@a11ydoer
Good catch on meter. That highlights how manual the process of maintaining the list of roles, states, and props is. Still wonder if we might want to eventually move to using something like aria-query.

[mcking65]

@a11ydoer
Are you ready to change to approving review now that the issue with meter is fixed? The breadcrumb issue should be fixed by changing the breadcrumb example file name in a separate PR; it should not hold this one up.

[a11ydoer]

Great job and Thanks so much, @jongund!

[a11ydoer]

breadcrumb file name issue 1886 was created and assigned to myself, @a11ydoer

[a11ydoer]

@mcking65 @jongund

Out of curiosity and connecting dots question

feature that shows the attributes that show up in the HTML but not in the documentation. Wel,, I love it all, but that was a clever addition for sure.

I have added some additional information to the coverage report to look at differences between the source code of an example and the documentation of aria features for an example. Some interesting results that should be discussed in term of quality assurance.

I am wondering what aspect of QA we are referring to regarding the difference between attributes in HTML and JS but not ones in the documentation?

[jongund]

@a11ydoer
In many of the example there are ARIA attributes that are used in the HTML or Javascript code that are not discussed in the documentation for the example. There are also some examples that execute code on one page and have documentation on another page, so we may want to revisit these examples, since it might not be obvious to developers viewing the examples what is going on. So the QA part is that all ARIA attributes used in an example should be documented, and it they are not the documentation should be updated.

[a11ydoer]

@jongund @mcking65 I think we would not have the direct link to teh coverage report from new APG site. I wonder what is the access plan to this report.

[jongund]

Editors and working group members would know about the URL and could use it for planning or reporting purposes. It does not need to be linked anywhere in the APG for the general public, but I don't think it needs to be "hidden" from the general public either. I don't think there is anything that is a secrete in the coverage report.

[shirsha]

Review complete