Re: Name and Description computation -- Proposed new texts

On Mon, Nov 23, 2015 at 12:03 AM, Amelia Bellamy-Royds <
amelia.bellamy.royds@gmail.com> wrote:

> 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
>
>
I would love to see a different approach taken. I think the HTML spec
shouldn't be the core algorithm centric, i.e explaining how to implement
each the algorithm's step in case of HTML. It rather should specify a
mapping of HTML markup into the terms used by the algorithm. For example,
an accessible value for HTML:input is built from @value attribute, HTML
textarea's one is built from 'textContent' property. 'Native name from
markup' for HTML button is built from related HTML:label content and from
the button's subtree if a label is missed, etc.


>
>    -
>    - 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.
>
>
>