google / accname

accname

A TypeScript library for calculating the accessible name of HTMLElements.

Usage

To install accname with NPM, run:

$ npm install accname

Once installed, import and use accname as follows:

import {getAccessibleName} from 'accname';

const elem = document.getElementById('target');
const name = getAccessibleName(elem);

Disclaimer

This is not an officially supported Google product.

accname's Issues

Node re-visiting in AccName

Problem

• AccName fails a small set of WPTs of the form seen in http://wpt.live/accname/name_test_case_659-manual.html.
• If AccName were to pass these tests, its WPT performance should be 100%.
• I think the problem here is that accname is visiting the same target <input /> Node twice here, adding it to the list of context.visitedNodes only when it traverses this <input /> for the second time.
• The spec is in large part responsible for this issue, specifying only in step 2F that Each node in the subtree is consulted only once.. In fact it would appear that no node should ever be visited more than once during accessible name computation, in which case the spec should be re-worded to reflect this.

A Potential Solution

• This could be implemented by keeping track of any node that is passed to computeTextAlternative() and ensuring that a node is only processed if it has never been seen before.
• This would probably also be a good opportunity to merge context.inherited.visitedNodes and context.inherited.nodesUsed.

Explicit comboboxes not handled

See #32

Elements marked explicitly as comboboxes (role=”combobox”) are not currently included in accessible names produced by accname's algorithm.

Issues revealed through Validation

The Web Platform Tests for accname were run on accname using the AccName Comparison app. In addition to this, the Comparison app was used to compare implementations on 29,846 nodes spanning 16 different web-pages.

These tests & comparisons revealed a number of issues with accname that are detailed in this document.

Does not recognize text in shadow DOM

Thank you for writing this library! I may have found an issue, though, with shadow DOM support.

For an element containing a shadow root, e.g.:

<button>
  <x-component>
    #shadow-root
      hello world
  </x-component>
</button>

In this example, the accessible name contains "hello world". But accname does not recognize this text, instead returning an empty string. Here is a minimal repro.

Output string not formatted

See #32

• accname should return a flat string as defined here.
• accname should also format the output string such that it has no leading or trailing whitespace.

Aria-owns not taken into account

See #32

Some Web Platform Tests expect Nodes that are aria-owned by the current node to be treated in the same way as descendants are in 2F.

Some Web Platform Tests that revealed this issue:
http://wpt.live/accname/name_file-label-owned-combobox-manual.html
http://wpt.live/accname/name_file-label-owned-combobox-owned-listbox-manual.html

Forbidden 'Name From Content'

See #32

• accname fails many WPTs because it does not ignore elements with role="menu".
• As it turns out, there is a list of node characteristics that should prevent or forbid that node from taking name from content. See: https://lists.w3.org/Archives/Public/public-aria/2017Jun/0057.html
• Adding a check for nodes that are forbidden from taking name from content to step 2F would result in accname passing at least 10 more WPTs.

Title attribute ignored on elements

data:text/html,<button title="accname"></button>

Firefox and Chrome both give an accname of accname but we give "". Presumably some rule before 2I is returning "" rather than null

<label for="foo"> isn't followed on IE

17/116 unit tests currently fail on Internet Explorer.

e.g.

  fit('understands label for', () => {
    render(
        html`
    <button id="foo">text</button>
    <label for="foo">bar</label>`,
        container);
    const elem = document.getElementById('foo');
    expect(computeTextAlternative(elem!)).toBe('bar');
  });

This passes on chrome and firefox but IE gives elem an accessible name of text.

Non-textual CSS pseudo-element content included in name

See #32

• accname is adding CSS pseudo-element content to the accessible name even when the content is non-textual. This has materialised on multiple occasions as url(...). Rule 2F should take some measure to ensure that such content is textual.

accname includes empty icons in accessible name

See #32

• accname often includes an empty white square character (□) when other implementations do not. This could be filtered out before the output string is returned.

Inline & Block-level should affect whitespace

See #32

Elements that are inline should be handled differently to those that are block-level in step 2F. More specifically, block-level Elements should be concatenated to the accumulated text in a space-separated manner by rule 2F, inline Elements should be concatenated without spaces.

The same applies for CSS pseudo-elements that are block-level or inline.

Some conditional 'name from content' cases not handled

• The following thread: https://lists.w3.org/Archives/Public/public-aria/2017Jun/0057.html specifies some cases in which the current node conditionally allows name from content.
• This is not yet handled by accname.
• This should be added to rule 2F.

Validation: unclear error if `ac` element missing

If no element has the ac attribute, the error shown in the UI is

Error: Protocol error (DOM.describeNode): Could not find node with given id

I think this will be the most common user error (I've made it at least twice!) so a more friendly error message would be useful

Title shouldn't be inherited

See #32

• Step 2I states specifically 'Otherwise, if the current node has a Tooltip attribute, return its value.'
• Elements inheriting a title value do not themselves have a title attribute.
• Removing title inheritance from 2I will cause accname to behave more similarly to existing implementations.

<title> labels for <svg> elements not recognised

See #32

• accname doesn’t recognise <title>s as labels for <svg> elements. The rest of the implementations do. This check could be added to rule 2D.

Update 2F Spec Assumptions

• Step 2F has 2 spec assumptions relating to whitespace, although these assumptions have been clarified thanks to the Web Platform Tests (see http://wpt.live/accname/name_file-label-inline-block-elements-manual.html) and this issue: w3c/accname#16 by Bryan Garaventa.
• The spec assumptions for 2F should be updated in accordance with our current approach to whitespace, namely that we now consider whether an element is 'inline' or 'block', and also that we consider the 'display' value for CSS pseudo elements.

Automatic Measurement of Output Accuracy

• It would be great to have a measure for accname's accuracy calculated every time a PR is made.
• This could be done automatically with GitHub actions.
• The metrics could be Web Platform Tests as well as some field-test on real world HTML documents. We could write some scripts that run experiments and output results, which we can then display in a comment on the PR automatically.
• It may also be possible to compare performance with master to get a performance diff for each PR.

See, for example: https://github.com/marketplace/actions/comment-on-pr

Need more accurate Role computation

• A function that can accurately compute the role for an element would be very useful in rule 2F.
• This would greatly cut down on the amount of code needed to implement 2F as well as improving readability.

Definition for Hidden

See #32

• Narrowing the definition for hidden in step 2A would improve parity with other implementations.

<option>s that label <select>s aren't considered 'direct labels'

See #32

• <option> elements could be considered direct labels in cases where they are labelling a <select> (i.e because they are selected). As it stands these <option> labels often aren’t visible as they are part of a pop-up menu, and so they are blocked by 2A.

Figure out how to run tests on pull requests

We should make sure that we can run all the unit tests when mergin a PR to avoid accidentally breaking things.

Ideally we can figure out how to run them on different browsers too.

Name from content without descendants

See #32

The empty string is being returned by step 2F in cases when an Element that allows name from content has no descendants. Instead, other steps (such as 2I) should be considered. For example:

<input type="checkbox" title="foo">

<input> should have an accessible name of ”foo” here, but accname is returning ””.

This issue is also referenced in #19