RE: Name and Description computation -- Proposed new texts

General:

1)      This is much more clear, especially the HTML-AAM. Thanks for all the work!

2)      I find the non-normative section 5.2 of the HTML-AAM more clear, useful and testable than the algorithms. Does anyone remember the reasons behind the decision to spec algorithms, rather than inputs and outputs (leaving the algorithms for generating the outputs as an implementation detail)?

3)      The examples in each step are useful, but it would be even more useful to have worked examples with complex markup and resulting accessibility trees. In my comment on ARIA step 1, for example, it wasn’t clear to me if the name from that example is only at this step, or the final result.


In ARIA Name calc
In the example in step 1, shouldn’t element3’s name be “good-bye” because it has aria-label=”good-bye”? From the ARIA 1.0 spec : http://www.w3.org/TR/wai-aria/states_and_properties#aria-label

aria-label (property)
Defines a string value<http://www.w3.org/TR/wai-aria/terms#def_value> that labels the current element.
Is this overcome by step 3? If so, maybe add a note to the example to this effect?

In step 4, are you saying that this would not generate a text alternative at all? I think that’s a change (We don’t generate one in Edge, and have been asked to add a way to support a flat string name)

<el1 aria-labelledby=”el2”>
<el2 role=”presentation”>foo</el2>

Step 6, tooltips. UIA (and I think AX) have a helptext field, in addition to name and description, that holds tooltip text. Is this something we want to consider as part of this algorithm? I am concerned that strings will be duplicated between helptext and description sometimes.


In HTML Acc Name doc
The terms accessible name<http://rawgit.com/AmeliaBR/aria/acc-name/html-aam/html-aam.html#dfn-accessible-name> and accessible description<http://rawgit.com/AmeliaBR/aria/acc-name/html-aam/html-aam.html#dfn-accessible-description> are properties provided in all accessibility APIs<http://rawgit.com/AmeliaBR/aria/acc-name/html-aam/html-aam.html#dfn-accessibility-api>. The name of the properties may differ across APIs but they serve the same function: as a container for a short (name) or longer (description) string of text.

This paragraph isn’t actually true. UIA does not have an accessible description property, only a relationship. This was an intentional design decision in UIA, because the accDescription property was frequently abused in MSAA. While the w3c has asked Microsoft to add this property, and we are considering it, we have not yet committed to do so. We may solve the problem of references to hidden nodes differently.

In the note under 5.0, it is not clear whether
<img alt=””> should be put in the accessibility tree with an empty or null string, or left out of the accessibility tree as though it had role=presentation.  The second is current browser behavior. Is this an intentional change?

5.1 This format is MUCH more clear. Thank you!

Step 2. Do we really want to expose the value of an input as its name? We’re already exposing the value as the value.  Is this only to expose the value when it is part of a string like <label>Remind me in <input type=text value=5 /> minutes</lable>?  I don’t think we want <input value=”One Microsoft Way” name=”address” /> to have “One Microsoft Way” as both its value and it’s accName.  Is that the intent? If so, is it intended to be a repair technique for when authors don’t use labels? It seems like it would make a worse experience than not having that string included.

Using InnerText of a textarea as a name concerns me. This can be very long. While there is no character limit on accName, it becomes a usability problem to have a name of more than a few words. If we are going to do this, perhaps it should be truncated?

Will Step 4 override the values from step 2? 5.2.1 seems to indicate that value is not used as part of the name. Is that accurate?

Is 4D a complete list of labelable html elements? If so, please remove e.g..  If not, please make it a complete list and remove e.g.









From: Amelia Bellamy-Royds [mailto:amelia.bellamy.royds@gmail.com]
Sent: Sunday, November 22, 2015 9:04 PM
To: PF <public-pfwg@w3.org>
Cc: Cynthia Shelly <cyns@microsoft.com>; Chaals from Yandex <chaals@yandex-team.ru>; SVG-A11y TF <public-svg-a11y@w3.org>
Subject: 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 simpler 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 prepending 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.