Name and Description computation -- Proposed new texts

Hello all,

Issues with the Name & Description algorithm were brought up within the SVG
Accessibility Task Force a few weeks back, and I made a commitment to
examine the AccName spec to see if it could be simplified or clarified, and
made easier to adapt for the specific languages (SVG and HTML, and
potentially others in the future).

In attempting to do so, I have

   1. significantly re-arranged the core algorithm, separating it out into
   multiple distinct functions (in order to simplify the nested list
   structure) and putting more general guidance and definitions in the
   introductory sections of the spec
   2. updated the SVG-specific guidance accordingly
   3. written new HTML-specific guidance that is directly based on the core
   algorithm
   4. re-used the existing HTML guidance (which offered rules for specific
   element types instead of a general algorithm) as an informative note,
   updated to match the new algorithm

The algorithm addresses numerous conditions and recursive situations, in
order to support existing content and software behavior.  So making it simpl
*er* does not mean the end result is simple.  Nonetheless—thanks to those
of you who offered feedback & especially to Chaals McCathie Nevile and
Cynthia Shelley for their detailed list of issues regarding the existing
specs—I think I've addressed most of the undefined or inconsistent aspects.

I've currently got the revised texts of all three specs on a branch in my
Github fork of the repo ( https://github.com/AmeliaBR/aria/tree/acc-name
).  You can view the compiled specs via rawGit:

   - AccName:
   https://rawgit.com/AmeliaBR/aria/acc-name/accname-aam/accname-aam.html#mapping_additional_nd_name

   - HTML-AAM:
   http://rawgit.com/AmeliaBR/aria/acc-name/html-aam/html-aam.html#accessible-name-and-description-calculation
   - SVG-AAM:
   http://rawgit.com/AmeliaBR/aria/acc-name/svg-aam/svg-aam.html#mapping_additional_nd

(If anyone wants to pull this in as a branch to the main repo, just let me
know.  There's probably a lot of style clean-up required, at the very
least!)

The HTML-AAM editors were concerned that the completely new approach made
comparisons nearly impossible.  I hope the new informative section helps
with that.  The only explicit *change* from the HTML-AAM text is that
alternative text defined by semantic HTML features (such as caption and
label elements) are given as possible sources for accessible descriptions
if they are not used as accessible names.  My personal opinion is that if
an author has provided multiple alternative texts, the software should make
these available to users whenever possible.  But if a different approach is
desired, the text could easily be adapted to match.

The more fundamental changes relate to previously poorly defined behavior
with respect to recursive situations.  I think I have now addressed all the
issues that have been brought up, particularly re infinite loops, but *I
would strongly encourage you to work through the steps with real-world
examples and make sure the results make sense*.

Below I indicate specifically how I've addressed issues brought up by
Cynthia and by Chaals.  I also have included many Editor's Notes in the
spec itself, giving the motivation for changes as well as identifying
remaining issues.

Sincerely,
Amelia Bellamy-Royds

*Cynthia's issues (numbering from the internal project Tracker)*


> ISSUE-744: Step 2A: be more specific about references
>
>                 "If the current node is hidden and is not referenced by
> aria-labelledby or aria-describedby, nor referenced by a native host
> language text alternative element or attribute, return the empty string. "
>
> Does this mean that if the node is contained within any reference, it
> should not be treated as hidden? Or only if we reached the current node via
> a reference in the current computation?
>

For content of a referenced labelling node, I use a recursive role: if the
parent node is hidden, then it's okay that the child node is hidden too.
This means hidden labels work as expected, even if they have nested
elements, but hidden content within a visible label is excluded.


>
>
> ISSUE-745: Step 2A, 2D: what are "native host langague text alternative
> element or attribute" for HTML?
>
> Does HTML have “native host language text alternative element or
> attribute”? Perhaps this is just the <label> element? Is there a list
> someplace? It was not clear from the HTML-AAM.
>

The new text explicitly defines all these in HTML-AAM (based on the
elements that had previously been indicated piecewise in HTML-AAM).


> ISSUE-746: Step 2E: Need concrete definition of “embedded within the label
> of another widget”.
>
> Need concrete definition of “embedded within the label of another widget”.
> Aria-label, <label> elements only?
>

I'm applying these roles any time a widget is being read as part of
"content", whether that's content of the node itself or content of a label.


>
>
> ISSUE-747: Step 2F: Define which roles allow “name from contents”.
>
> Need a concrete list of roles that allow "name from contents"
> Also need a list of html elements that allow this
>

This remains an issue.  The information is in the main ARIA spec (the
properties tables for each role), but it isn't easily query-able or
link-able.  It might be useful to have an informative note in the AccName
spec with a list of the roles.

I have made it clear that "name from contents" is a property of the
computed role, so there shouldn't need to be specific rules for HTML
element types (it is determined by their default/allowed roles).


>  ISSUE-748: Step 2F: The algorithm does not seem to handle nesting like
> it thinks it does
>
> The algorithm does not seem to handle nesting like it thinks it does, at
> least if it is using the information in the html-aam document (linked
> above). Using their own example:
>
> < label><input>Make this the <em>top</em>most element</label>
>
> They say the name should come out as “Make this the topmost element”.
> However, following the algorithm, we’ll get to step 2.F, and start walking
> the children of the label. <em> is a child of the label, not the text node,
> so we’ll recurse into the algorithm for this node. It isn’t special, so
> it’ll hit step 2.D. which says use the native markup text alternative.
> Using the html-aam document, <em> elements are specifically covered in 5.11
> and since there is no aria nor title, the element does not have a name. It
> does not say to use the subtree.
>
> Perhaps “name from: contents” is supposed to cover practically all nodes
> except in very specific circumstances, in which case we’d be fine as we’d
> recurse into the subtree and handle the text node properly. In HTML, I
> believe any node can have a subtree, even if it is not rendered, meaning
> anything could get its name from its contents?
>

I have made it clear that, once you follow a labelling relationship, you
can then extract the name from contents.  The name from: contents only
applies to the original node.


>  ISSUE-749: Step 2.F.ii.a Prepending list style type before the content
>
> Prepending list style type before the content. For ordered content, this
> is straight-forward, but for un-ordered bullets, I’m not sure what to
> prepend. Do we prepend a special Unicode character, a textual description
> that needs to be localized, or something else?
>

I've added a suggestion (along with references to the new CSS spec on
custom list counters and screen-reader friendly versions thereof).
Probably needs review.


> ISSUE-750: Step 2.F.iii.c Define when to append with and without a space
>
Define when to append with and without a space. Algorithm isn’t explicit
> and calls out that it “needs to work” and “sometimes we want a space,
> othertimes not” (paraphrase). How to differentiate?
> The example prepends without a space. When should it have one?
>

I've added suggested text.  It requires the consideration of CSS formatting
(inline vs block), which may have performance impacts, and leaves open the
question of what to do when the element has display: none.  Alternative
suggestions are welcome.


> ISSUE-751: Step 2H: tootip attribute
>
> Is the “tooltip attribute” for HTML is just @title, or is there and not a
> full tooltip computation? If there's a computation, where is it documented?
>

I've made it clear that the HTML `title` should be used for this step.


>  ISSUE-752: Potential infinite loop
>
> Potential infinite loop
> Take this example:
> < td>I contain a <button>button</button>!</td>
>
> Computing the name for the cell, I believe you’ll hit this:
> 1. Hit step 2.F, name from contents
> 2. Walk child nodes until you hit the <button>
> 3. Button hits step 2.E., which says get the name from the text
> alternative of the button
> 4. One of the two will happen:
> a. Button satisfies 2.D and has a native attribute defining text
> alternative (really need this specified)
> b. Button does not satisfy 2.D and drops back into 2.E and goes back to
> step 3 here
>
> Now, take this:
> < td>I contain a <button aria-label=”fun button”>button</button>!</td>
>
> Computing the name for the cell, I believe you’ll hit this:
> 1. Hit step 2.F, name from contents
> 2. Walk child nodes until you hit the <button>
> 3. Button hits step 2.E., which says get the name from the text
> alternative of the button
> 4. Hit step 2.C, and this is an embedded control with an aria-label
> defined, but ignored, so we jump to step 2.E again
> 5. Step 2.E and goes back to step 3 here
>

I've added extra checks that should address these loops.  They require the
software to keep track of all nodes that have previously been visited, to
avoid using anything twice.

It's possible that this will cause unexpected results in some situations,
with words missing from a description because they've already been used
earlier on.  This is one of the areas where extensive testing is required.


> ISSUE-753: use X attribute if it was not used as the accessible name
>
> Issue with html-aam behavior
> HTML-AAM has several places where it says to “use X attribute if it was
> not used as the accessible name.” Making that determination is quite hard.
> I understand the reasoning for it, but it really does not go well with the
> text alternative computation. Answering the question “what attribute will
> map to the name of node X” is not trivial.
>

> Does the text alternative algorithm expect this kind of behavior too?
>

I've addressed this in two ways:
In the core algorithm, this only affects whether the tooltip is used as a
description. So I have the algorithm compute the description, then compare
it against the name. If the description exactly matches or is contained in
the name, it doesn't add anything, so discard it.

For HTML, with multiple alternative text attributes available on some
elements, we don't want to simply discard a redundant description, we want
to use a different alternative text instead.  So I've maintained the
requirement to check whether an alt text has been used for the name.
However, because this should only affect the computation for the original
element (if you're building a name/description from contents, you want the
simplest name available for that element, not a complex alternative
description), it becomes simply a matter of looking for
aria-label/labelledby attributes.


>
>
> ISSUE-754: Label elements containing controls
>
> Label elements containing controls
> Do we use label elements that contain controls? Maybe only if the control
> is the first child of the label?
>
> < label>I have a <input type=”checkbox” />checkbox and a
> <button>button</button> here</label>
>
> I don’t think the label containing these controls makes sense to be the
> name for either, and definitely not both.
>
> Might be fine since we don’t expect authors to do this, but good to have a
> concrete definition of when to use parent <label> elements.
>

I've added links to the HTML spec rules about which label matches which
element (in this case, the label would be for the <input>, since it is the
first labelable child, although this is of course a very poorly authored
example).  In looking up those rules, I discovered that HTML elements can
have multiple valid labels.  I therefore address this, requiring multiple
labels to be concatenated together, similar to aria-labelledby with
multiple IDREFs.

*Chaals' Issues (with links to the pfwg-comments email archive):*

https://lists.w3.org/Archives/Public/public-pfwg-comments/2015OctDec/0015.html
> there is a very large glossary. Having it come before the main content
> suggests to the reader that it is critical to understand all the terms -
> and for the reader familiar with them already, it just makes it more
> annoying to skip through to the content.


I agree with this issue, but don't have the knowledge to fix the build
scripts that create it.  I have added an Editor's Note about it.

https://lists.w3.org/Archives/Public/public-pfwg-comments/2015OctDec/0016.html
> In section 4.2 the specification only requires a decsription to be
> generated if there is an aria-describedby attribute present. The
> requirement should also hold if there is a native element or attribute with
> equivalent semantics, such as the longdesc attribute in HTML, or the desc
> element in SVG.


I've changed the section to require a description whenever there is content
that should be used for the description

https://lists.w3.org/Archives/Public/public-pfwg-comments/2015OctDec/0017.html
> the javascript used to hide and show the details element doesn't work in
> Safari 9 on OS X, nor in the Yandex Browser on OS X - clicking the arrow
> fails to reveal the content of the details which therefore remains hidden.


This is a major concern, but again outside my skill set.  I like having the
explanation and examples embedded in the normative text, but if
details/summary functionality doesn't work properly, maybe standard blue
informative note boxes would be a better approach.

https://lists.w3.org/Archives/Public/public-pfwg-comments/2015OctDec/0018.html
> looking through the algorithm for processing, I came across the following:
> <li>If such and such, process IDREFs in the order they occur:</li>
> <li>or, if such and such process IDREFs in the order they occur:
> <ol>
> <li>...steps...
> This is really unclear - I spent a couple of hours looking at the
> algorithm before I figured out that the set of steps applied for both
> cases. Strategies to clarify could include providing a named point and
> "goto" (pseudo-program like it's 1979!), making the process IDREFs a
> separate algorithm, or making a significant change to the layout and
> structure. I also strongly suggest producing a flowchart to accompany the
> algorithm - both because it requires checking each step is clear, and
> because it will be clearer for some users. I also note the difficulty in
> making such a flowchart accessible as an SVG graphic, but suggest it is
> worth the effort.


I think I've addressed the confusing algorithm steps.  I agree that an
(accessible) SVG flowchart would be nice, but wanted to get discussion on
the algorithm underway before attempting that.

https://lists.w3.org/Archives/Public/public-pfwg-comments/2015OctDec/0019.html
> the algorithm says somewhere "if X is due to recursion, then Y".
> This is pretty unclear. One way to make this unambiguous is to set a flag,
> and check its value.


I've defined a series of states for why one is running the algorithm on any
given element (original node, content node, labelling node, or content of a
labelling node), and use those state names to address these distinctions.

https://lists.w3.org/Archives/Public/public-pfwg-comments/2015OctDec/0020.html
> the current markup seems to use HTML code elements styled the same way for
>
> both code such as element names, and variables such as "current node".
> Please use var elements for the latter, to help distinguish what is going
> on.


I've done that, and made them links to the term definitions.  Might still
need a little cleanup.

https://lists.w3.org/Archives/Public/public-pfwg-comments/2015OctDec/0021.html
> as far as I can tell, all cases of prepend something result in the thing
> prepended being the next thing appended to the accumulated text.
> It seems like we could simplify things by appending every time, and if you
>
> need a space, then explicitly appending a space.


I've stripped out most of the detailed wording about string manipulations,
in favour of saying things like "concatenate, in order, with spaces".  I
hope its clearer, but that's for others to judge.  The only place where
*pre*pending is required (for CSS-inserted content), I use a separate step
that describes the position in terms of extra nodes inserted into the DOM
tree.