Diagram in 5.3 need fixing or removing

[jnurthen]

It either need to be either kept up to date or removed.
While I think it is useful it is not useful if it is not accurate.
https://www.w3.org/TR/wai-aria-1.2/#roles_categorization

See https://web-a11y.slack.com/archives/C042TSFGQ/p1585040058001800 for people trying to use it.

[anevins12]

Thank you for raising this! If you can't follow the Slack link, what was said was:

The UML diagram of ARIA (1.1) is so cool and really helps me understand which roles are for widgets and which are structure. I've read the specification in a wordy format and seeing a diagram is a great way of reinforcing that understanding:
https://www.w3.org/TR/wai-aria-1.1/#roles_categorization

[jnurthen]

@michael-n-cooper I know we have talked about this before - but what would it take to make this diagram accurate?

[pkra]

@sinabahram @michael-n-cooper I'd be happy to help, too.

[sinabahram]

RE tooling, here are some options for us to consider to generate the updated version of this diagram.

GraphViz, you can turn textual descriptions into complex graphs:
https://www.graphviz.org/

Here's a web-based version of GraphViz:
https://www.graphviz.org/

Here's another tool that even works in Markdown, called MerMaid:
https://mermaid-js.github.io/mermaid/#/

There's more out there, but maybe that gets us started? GraphViz has been around forever and a day. I was using it or it's predecessor 15 years ago. I remember it being super-powerful.

[pkra]

+1 for mermaid

[jnurthen]

@michael-n-cooper the linked resource needs a note that it has some errors as it has not been updated for the changes in 1.2.

[jnurthen]

Diagram note added. Leaving open for 1.3 to update the diagram

[pkra]

I was working with D3 the other day and got to think about this issue.

Would the following rough example be a step in the right direction?

This is a basic D3 dendogram generated by traversing role subclasses. It's obviously much simpler than the previous diagram - it lacks attributes and roles with multiple superclasses are duplicated. But I didn't want to spend too much time on it at this stage. It's easy to generate some graphviz or mermaid input (cf. below) but a dendogram seemed to give a nicer presentation.

(It's a png since github doesn't allow SVG uploads).

roletype -> structure;
structure -> application;
structure -> document;
document -> article;
article -> comment;
structure -> generic;
structure -> presentation;
structure -> range;
range -> meter;
range -> progressbar;
range -> scrollbar;
range -> slider;
range -> spinbutton;
structure -> rowgroup;
structure -> section;
section -> alert;
alert -> alertdialog;
section -> associationlist;
section -> associationlistitemkey;
section -> associationlistitemvalue;
section -> blockquote;
section -> caption;
section -> cell;
cell -> columnheader;
cell -> gridcell;
gridcell -> rowheader;
section -> code;
section -> definition;
section -> deletion;
section -> emphasis;
section -> figure;
section -> group;
group -> row;
group -> select;
select -> listbox;
select -> menu;
menu -> menubar;
select -> radiogroup;
select -> tree;
tree -> treegrid;
group -> toolbar;
section -> img;
section -> insertion;
section -> label;
section -> landmark;
landmark -> banner;
landmark -> complementary;
landmark -> contentinfo;
landmark -> form;
landmark -> main;
landmark -> navigation;
landmark -> region;
landmark -> search;
section -> legend;
section -> list;
list -> directory;
list -> feed;
section -> listitem;
listitem -> treeitem;
section -> log;
section -> mark;
section -> marquee;
section -> math;
section -> note;
section -> paragraph;
section -> status;
status -> timer;
section -> strong;
section -> subscript;
section -> suggestion;
section -> superscript;
section -> table;
table -> grid;
section -> tabpanel;
section -> term;
section -> time;
section -> tooltip;
structure -> sectionhead;
sectionhead -> heading;
sectionhead -> tab;
structure -> separator;
roletype -> widget;
widget -> command;
command -> button;
command -> link;
command -> menuitem;
menuitem -> menuitemcheckbox;
menuitemcheckbox -> menuitemradio;
widget -> composite;
composite -> tablist;
widget -> input;
input -> checkbox;
checkbox -> switch;
input -> combobox;
input -> option;
input -> radio;
input -> textbox;
textbox -> searchbox;
roletype -> window;
window -> dialog;

[carmacleod]

Very cool, @pkra ! I think this is much better than no diagram at all.
I was wondering if a vertically-oriented tree would look cleaner than the horizontally-oriented one from before, and I think it does... hard to say for sure without the multiple inheritance lines. 😄

I guess very basic multiple inheritance can be added in parentheses after the role name, i.e.

-> listitem -> treeitem (option)
...
-> option -> treeitem (listitem)

And maybe supported/required* attributes can be added in square brackets after the role name, like an array, i.e.

-> listitem [aria-level, aria-posinset, aria-setsize]
     -> treeitem (option) [aria-expanded, aria-haspopup]
...
-> option [aria-selected*, aria-checked, aria-posinset, aria-setsize]
     -> treeitem (listitem) [aria-expanded, aria-haspopup]

That would be easy, but it might look way messier (we can decide how much to add based on legibility). We would have to describe the "notation" in the diagram's description if we went this route.

[pkra]

Very cool, @pkra ! I think this is much better than no diagram at all.

Thanks 😊

I'll find time to move the example code somewhere public then.

I was wondering if a vertically-oriented tree would look cleaner than the horizontally-oriented one from before, and I think it does... hard to say for sure without the multiple inheritance lines. smile

I also thought about radial layout -- lots of other examples at https://observablehq.com/collection/@d3/d3-hierarchy.

Since the diagram will live outside the spec, we could think about more options, especially if it's just a d3 configuration switch.

I guess very basic multiple inheritance can be added in parentheses after the role name, i.e.
And maybe supported/required* attributes can be added in square brackets after the role name, like an array, i.e. [...]
That would be easy, but it might look way messier (we can decide how much to add based on legibility).
We would have to describe the "notation" in the diagram's description if we went this route.

Thanks for those ideas! I like them for their simplicity.

[pkra]

To follow up on

I guess very basic multiple inheritance can be added in parentheses after the role name, i.e.
-> listitem -> treeitem (option)

I'm somewhat undecided after realizing we have slightly more complex cases, e.g.,

gridcell (cell) -> columnheader (gridcell (cell)).

Maybe a simple indicator for multples (e.g., asterisk) could be sufficient.

[carmacleod]

Maybe a simple indicator for multples (e.g., asterisk) could be sufficient.

Agreed!

We can get fancy later. :)

[pkra]

I was wondering if a vertically-oriented tree would look cleaner than the horizontally-oriented

Coming back to this. A vertical layout seems trickier to me since the text adds a lot of width (the associationList roles are particularly troublesome). This makes it difficult to get a decent layout.

Here's a horizonal tidy tree for comparison with the cluster / dendogram from my earlier comment.

[carmacleod]

That looks great! I would have called that layout "vertical". I guess I need to update my tree terminology. :)

[pkra]

That looks great!

Thanks, @carmacleod.

I would have called that layout "vertical". I guess I need to update my tree terminology. :)

No, my bad! I didn't think about terminology.

[pkra]

Finally got around to pushing something to github. I scraped the data pretty naively from the spec.

[carmacleod]

Wow, @pkra. Very cool.

So, I went back and forth many times between Tree and Dendogram, and I think I have a slight preference for Tree, because:

• less of the diagram is dedicated to lines
• you can very quickly see which roles have the deepest hierarchy (the ones that extend furthest to the right)
• I'm used to looking at trees, so I find things a little easier to find

The flowchart is interesting, but the lines are really really hard to follow.

Thanks so much for doing this!

[carmacleod]

@jnurthen Can you create https://www.w3.org/WAI/ARIA/1.3/class-diagram/ ? How do we add @pkra's Tree diagram there?

We should re-generate the Tree diagram because of #1354, and then I would be happy to create a PR that links to https://www.w3.org/WAI/ARIA/1.3/class-diagram/ from the place in the spec.

[jnurthen]

@carmacleod no I can't. @michael-n-cooper is the only one who can modify those pages.

[pkra]

FYI I've updated my d3 diagram with freshly scraped data. (There's now also a branch with a navigable tree.)

[carmacleod]

Thanks, @pkra! We'll have to scrape again after #1354 is merged (because it has a hierarchy change in menuitem*).
That PR already has 1 approving review and just needs a couple more reviews... so I added you as a reviewer. 😄

[pkra]

Happy to regenerate anytime (but wouldn't mind a review of the scraper). This could just be a github action in the long run.

[jnurthen]

@pkra are you aware of https://github.com/w3c/aria/blob/master/common/script/roleInfo.js ? It might avoid you scraping the spec.

[pkra]

@pkra are you aware of https://github.com/w3c/aria/blob/master/common/script/roleInfo.js ? It might avoid you scraping the spec.

Evidently not - thanks! I'll look into modifying the diagram to digest that data. It should allow for an evergreen diagram fetching the latest version of that file from github.io.

[jnurthen]

I thought it might 👍
Assuming we keep the publication branches alive (which I believe we do) we might even be able to produce a version which was current at each publication by fetching from the branch via raw.githack (but that is an extra credit project ;) )

[pkra]

Yes, fetching from branches occurred to me, too. Could be a query string or some such. Since the output is just SVG (ignoring the transitions), it could also just be saved once for publications branches (to avoid JS dependencies, later breaking changes etc).

[pkra]

Here's a copden pulling in the "correct" data https://codepen.io/pkra/pen/bGwBzGZ?editors=1010 (and also adding a tree navigation)