Rule visible-label-in-accessible-name-2ee8b8: introducing a new "label in name

algorithm".  It's intended mostly to handle whitespace and punctuation.

Author: dan-tripp-siteimprove

_rules/visible-label-in-accessible-name-2ee8b8.md

@@ -23,6 +23,7 @@ acknowledgments:
   authors:
     - Anne Thyme Nørregaard
     - Bryn Anderson
+    - Dan Tripp
     - Jey Nandakumar
   funding:
     - WAI-Tools
@@ -38,10 +39,14 @@ This rule applies to any element for which all the following is true:
 
 ## Expectation
 
-For each target element, all [text nodes][] in the [visible text content][] either match or are contained within the [accessible name][] of this target element, except for characters in the [text nodes][] used to express [non-text content][]. Leading and trailing [whitespace][] and difference in case sensitivity should be ignored.
+For each target element, the [visible inner text][] is contained within the [accessible name][] of the target element according to the [label in name algorithm][].
 
 ## Assumptions
 
+This rule assumes that the [visible inner text][] is equal to the [label][https://www.w3.org/WAI/WCAG21/Understanding/label-in-name#dfn-label] in most cases (enough cases to be useful) even though "label" is not precisely defined at this point in history.
+
+This rule assumes that neither the label nor the [visible inner text][] are rearranged with CSS in some way so that they appear to the user in a different order than they do in the DOM.
+
 This rule assumes that all resources needed for rendering the page are properly loaded. Checking if resources are missing is out of the scope of rules. Missing resources may be rendered as text (for example, missing `img` are rendered as their `alt` attribute).
 
 ## Accessibility Support
@@ -54,6 +59,7 @@ This rule applies to elements with a [widget role][] that [support name from con
 
 The understanding document of [2.5.3 Label in Name][understand253] use the term "symbolic text characters" to refer to a type of [non-text content][] that uses text characters as symbols, such as using "x" to mean "close". This rule considers them as "characters expressing non-text content". Unicode emojis are another example of characters expressing non-text content, although these are not "symbolic text characters".
 
+
 ### Bibliography
 
 - [Understanding Success Criterion 2.5.3: Label in Name][understand253]
@@ -65,39 +71,39 @@ The understanding document of [2.5.3 Label in Name][understand253] use the term
 
 #### Passed Example 1
 
-This link has [visible][] text that matches the [accessible name][].
+This link has [visible inner text][] that is equal to the [accessible name][].
 
 ```html
 <a href="https://act-rules.github.io/" aria-label="ACT rules">ACT rules</a>
 ```
 
 #### Passed Example 2
 
-This link has [visible][] text that, ignoring trailing whitespace, matches the [accessible name][].
+This link has [visible inner text][] that, ignoring whitespace, is equal to the [accessible name][].
 
 ```html
-<a href="https://act-rules.github.io/" aria-label="  ACT rules  ">ACT rules</a>
+<a href="https://act-rules.github.io/" aria-label="  ACT   rules  ">ACT rules</a>
 ```
 
 #### Passed Example 3
 
-This link has [visible][] text that, ignoring case, matches the [accessible name][].
+This link has [visible inner text][] that, ignoring case, is equal to the [accessible name][].
 
 ```html
-<a href="https://act-rules.github.io/" aria-label="act rules">ACT rules</a>
+<a href="https://act-rules.github.io/" aria-label="act Rules">ACT rules</a>
 ```
 
 #### Passed Example 4
 
-This button has [visible][] text that is contained within the [accessible name][].
+This button has [visible inner text][] that is contained within the [accessible name][] according to the [label in name algorithm][].
 
 ```html
 <button aria-label="Next Page in the list">Next Page</button>
 ```
 
 #### Passed Example 5
 
-This button has [visible][] text that does not need to be contained within the [accessible name][], because the "x" text node is [non-text content][].
+The "X" is [non-text content][], so it doesn't need to be contained within the [accessible name][].
 
 ```html
 <button aria-label="close">X</button>
@@ -117,45 +123,242 @@ This `button` element has the text "search" rendered as an magnifying glass icon
 <button aria-label="Find">search</button>
 ```
 
+#### Passed Example 7 
+
+This button has [visible inner text][] that, according to the [label in name algorithm][], is contained within the [accessible name][].  This example shows why the [label in name algorithm][] uses the [visible inner text][] and not the [visible text content][]: the <p> tags insert whitespace into the result in the former but not the latter.
+
+```html
+<button aria-label="Hello world"><p>Hello</p><p>world</p></button>
+```
+
+#### Passed Example 8
+
+Similar to the previous example.
+
+```html
+<a href="#" aria-label="Some article by John Doe"><h6>Some article</h6><p>by John Doe</p></a>
+```
+
+#### Passed Example 9
+
+The [visible inner text][] is "Download specification".  The words "the" and "gizmo" aren't part of it.    
+
+```html
+<a aria-label="Download specification" href="#">Download <span style="visibility: hidden">the</span> <span style="display: none">gizmo</span> specification</a>
+```
+
+#### Passed Example 10
+
+This example shows that the [visible inner text][] isn't always the same as the [innerText][https://html.spec.whatwg.org/multipage/dom.html#the-innertext-idl-attribute].  The visible inner text is "Download specification".  The innerText is 'Download \ngizmo\nspecification'.  This rule uses the visible inner text - not innerText.
+
+```html
+<style>
+.visually-hidden {
+    /* Source: https://www.tpgi.com/the-anatomy-of-visually-hidden/ */
+    clip-path: inset(50%);
+    height: 1px;
+    overflow: hidden;
+    position: absolute;
+    white-space: nowrap;
+    width: 1px;
+}
+</style>
+<a aria-label="Download specification" href="#">Download <span class="visually-hidden">gizmo</span> specification</a>
+```
+
+#### Passed Example 11
+
+This example shows that the [label in name algorithm][] handles many kinds of whitespace.
+
+```html
+<a aria-label="compose email" href="#">compose &nbsp;&nbsp;<br> email</a>
+```
+
+#### Passed Example 12
+
+This example passes the rule because "YYYY-MM-DD" is in brackets.  Text in brackets is removed by the [label in name algorithm][], because its not normally spoken by speech-input users.  
+
+```html
+<button aria-label="Search by date">Search by date (YYYY-MM-DD)</button>
+```
+
+#### Passed Example 13
+
+The passes for two reasons: 1) because the ellipsis ("…") is [non-text content][], and 2) because the ellipsis is neither a letter nor a digit and so is filtered out by the [label in name algorithm][].
+
+```html
+<button aria-label="Next">Next…</button>
+```
+
+#### Passed Example 14
+
+This passes because the [label in name algorithm][] effectively ignores all punctuation and emoji, in both the visible inner text and the accessible name, as long as they don't break up words.
+
+```html
+<button aria-label="💡 Submit 💡">>>> ** Submit ** <<<</button>
+```
+
+#### Passed Example 15
+
+The "X" is non-text content.
+
+```html
+<button aria-label="Close">X</button>
+```
+
+
+
 ### Failed
 
 #### Failed Example 1
 
-This link has [visible][] text that is different from the [accessible name][].
+This link has [visible inner text][] that is very different from the [accessible name][].
 
 ```html
 <a href="https://act-rules.github.io/" aria-label="WCAG">ACT rules</a>
 ```
 
 #### Failed Example 2
 
-This button has [visible][] text that is only partially contained within the [accessible name][].
+This button has [visible inner text][] that is only partially contained within the [accessible name][].
 
 ```html
 <button aria-label="the full">The full label</button>
 ```
 
-#### Failed Example 3
+#### Failed Example 3 
+
+This button has [visible inner text][] that is fully contained within the [accessible name][] when viewed as a character-by-character substring.  But that does not satisfy our [label in name algorithm][], which works on full words.  So this fails the rule.
+
+```html
+<a href="#" aria-label="Discover Italy">Discover It</a>
+```
+
+#### Failed Example 4 
+
+This link's [accessible name][] contains two tokens (according to the[label in name algorithm][]) and the [visible inner text][] contains one token.  So it fails the rule.
+
+```html
+<a aria-label="just ice" href="#">justice</a>
+```
+
+#### Failed Example 5 
+
+This link has an [accessible name][] which contains a hyphen.  The [label in name algorithm][] breaks up words on hyphens.  So it turns "non-standard" into two tokens: "non" and "standard".  So this fails the rule.
+
+```html
+<a href="#" aria-label="non-standard">nonstandard</a>
+```
+
+#### Failed Example 6 
+
+The rule has no special handling for acronyms or initialisms.
+
+```html
+<a aria-label="WAVE" href="#">W A V E</a>
+```
+
+#### Failed Example 7 
+
+The rule has no special handling for abbreviations.
+
+```html
+<a aria-label="University Avenue" href="#">University Ave.</a>
+```
+
+#### Failed Example 8
 
-This link has [visible][] text with mathematical symbols, that does not match the [accessible name][] because the mathematical symbols were written out in the accessible name. This is [explicitly mentioned in WCAG](https://www.w3.org/WAI/WCAG21/Understanding/label-in-name#mathematical-expressions-and-formulae).
+This link has [visible inner text][] with mathematical symbols and is not contained within the [accessible name][] because the mathematical symbols are represented as English words (not digits) in the accessible name. This is [explicitly mentioned in WCAG](https://www.w3.org/WAI/WCAG21/Understanding/label-in-name#mathematical-expressions-and-formulae).
 
 ```html
 <a href="/" aria-label="Proof of two multiplied by two is four">Proof of 2&times;2=4</a>
 ```
 
+#### Failed Example 9 
+
+Similar to the previous example.  This rule has no special handling for converting mathematical symbols into words, or vice versa.
+
+```html
+<button aria-label="11 times 3 equals 33">11×3=33</button>
+```
+
+#### Failed Example 10 
+
+This button's accessible name contains the same tokens that are in the visible label.  But they aren't in the same order, so it fails the sublist check part of the [label in name algorithm][], and so it fails the rule.
+
+```html
+<button aria-label="how are you"><span>you</span><span>how</span><span>are</span></button>
+```
+
+#### Failed Example 11 
+
+This link's accessible name contains the same digits that are in the visible label, and in the same order.  But they have different spaces and punctuation between them, so they are considered separate tokens.  So this fails the rule.
+
+```html
+<a aria-label="Call 1 2 3. 4 5 6. 7 8 9 0." href="tel:1234567890">123.456.7890</a>
+```
+
+#### Failed Example 12 
+
+This rule has no special handling which tries to guess when number have the same semantic meaning.  It operates on tokens only.
+
+```html
+<a href="#2021" aria-label="20 21">2021</a>
+```
+
+#### Failed Example 13 
+
+Similar to the previous example.
+
+```html
+<a aria-label="fibonacci: 0 1 1 2 3 5 8 13 21 34">fibonacci: 0112358132134</a>
+```
+
+#### Failed Example 14 
+
+This rule has no special handling for converting digits into words, or vice versa.
+
+```html
+<a href="#2021" aria-label="twenty twenty-one">two thousand twenty-one</a>
+```
+
+#### Failed Example 15 
+
+(Same as above.)  This rule has no special handling for converting digits into words, or vice versa.
+
+```html
+<a aria-label="two zero two three" href="#">2 0 2 3</a>
+```
+
+#### Failed Example 16 
+
+This rule has no special handling for digits that appear next to letters with no spaces in between.
+
+```html
+<a aria-label="1a" href="#">1</a>
+```
+
+#### Failed Example 17
+
+The definition of [visible inner text][] doesn't treat text any differently if it's excluded from the accessibility tree with aria-hidden.  So this rule effectively ignores aria-hidden.  So this element fails the rule.
+
+```html
+<a aria-label="Download specification" href="#">Download <span aria-hidden="true">gizmo</span> specification</a>
+```
+
 ### Inapplicable
 
 #### Inapplicable Example 1
 
-This `nav` is not a widget, so the [visible][] text does not need to match the [accessible name][].
+This `nav` is not a widget, so the [visible inner text][] does not need to match the [accessible name][].
 
 ```html
 <nav aria-label="main nav">W3C navigation</nav>
 ```
 
 #### Inapplicable Example 2
 
-This email text field does not need to have its [visible][] text match the [accessible name][]. The content of a textfield shows its value instead of its label; it does not [support name from content][supports name from content]. The label is usually adjacent to the textfield instead.
+This email text field does not need to have its [visible inner text][] match the [accessible name][]. The content of a textfield shows its value instead of its label; it does not [support name from content][supports name from content]. The label is usually adjacent to the textfield instead.
 
 ```html
 <div>E-mail</div>
@@ -164,15 +367,15 @@ This email text field does not need to have its [visible][] text match the [acce
 
 #### Inapplicable Example 3
 
-This `div` element does not have a widget role, so the [visible][] text does not need to match the [accessible name][].
+This `div` element does not have a widget role, so the [visible inner text][]t does not need to match the [accessible name][].
 
 ```html
 <div role="tooltip" aria-label="OK">Next</div>
 ```
 
 #### Inapplicable Example 4
 
-This link has no [visible text content][].
+This link has no [visible inner text][].
 
 ```html
 <a href="https://w3.org" aria-label="W3C homepage">
@@ -186,6 +389,7 @@ This link has no [visible text content][].
 [semantic role]: #semantic-role 'Definition of Semantic role'
 [supports name from content]: https://www.w3.org/TR/wai-aria-1.1/#namefromcontent 'Definition of Supports name from contents'
 [visible]: #visible 'Definition of visible'
+[visible inner text]: #visible-inner-text 'Definition of Visible inner text'
 [visible text content]: #visible-text-content 'Definition of Visible text content'
 [whitespace]: #whitespace 'Definition of Whitespace'
 [widget role]: https://www.w3.org/TR/wai-aria-1.1/#widget_roles 'Definition of Widget role'

package.json

@@ -48,6 +48,10 @@
 			"name": "Dagfinn Rømen",
 			"url": "https://github.com/DagfinnRomen"
 		},
+		{
+			"name": "Dan Tripp",
+			"url": "https://github.com/dan-tripp-siteimprove"
+		},
 		{
 			"name": "Daniël Strik",
 			"url": "https://github.com/danistr"

pages/glossary/label-in-name-algorithm.md

@@ -0,0 +1,34 @@
+---
+title: Label in Name Algorithm
+key: label-in-name-algorithm
+unambiguous: true
+objective: false
+input_aspects:
+  - CSS styling
+  - DOM tree
+---
+
+Let 'label' be the [visible inner text][] of the target element.  Let 'name' be the [accessible name][] of the target element.  Both 'label' and 'name' are strings.
+
+Sub-algorithm to tokenize a string:
+
+- Convert the string to lower case.
+- For each character that either a) represents non-text content, or b) isn't a letter or a digit: replace that character with a space character.
+    - For a) Judgement of "non-text" probably can't be fully automated. eg. "X" for "close" probably can be, but presumably there are more cases than this.
+    - For b) Use the unicode classes Letter, Mark, and "Number, Decimal Digit [Nd]". (This will exclude hyphens, punctuation, emoji, and more.)
+- Remove all characters that are within parentheses (AKA round brackets).
+    - Ignore square brackets and braces.
+- Split the string into a list of strings, using a whitespace regular expression as the separator.
+    - This 'split' operation must:
+        - Effectively remove leading and trailing whitespace as a pre-processing step.
+        - If the string was all whitespace before this operation: result in an empty list.
+
+Then do the check: is the tokenized 'label' a sublist of the tokenized 'name'?
+- This 'sublist' check has these properties:
+    - It checks whether elements are consecutive or not. i.e. it checks for a substring, in the computer science sense of the term. Not a subsequence.
+    - An empty list is a sublist of any list.
+
+If the answer is "yes" (i.e. the tokenized 'label' a sublist of the tokenized 'name'), then the target element passes the rule.  Otherwise, it fails the rule.
+
+[accessible name]: #accessible-name 'Definition of accessible name'
+[visible inner text]: #visible-inner-text 'Definition of Visible inner text'