From cf152ed339c4fba1e8d8b8d610ad2c81f4daaec1 Mon Sep 17 00:00:00 2001 From: Nolan Lawson Date: Thu, 15 Sep 2022 16:13:12 -0700 Subject: [PATCH 01/14] Add steps for shadow roots and slots Fixes #51 and #20. Clarifies how accessible names are calculated for shadow roots and slots. --- index.html | 22 ++++++++++++++++++---- 1 file changed, 18 insertions(+), 4 deletions(-) diff --git a/index.html b/index.html index 497fe48..c201d31 100644 --- a/index.html +++ b/index.html @@ -224,6 +224,8 @@

Terminology

The DOM [=nodes|node=] or [=element=] for which the text alternative is sought.
Current node
The DOM [=nodes|node=] currently traversed to compute the root node's text equivalent. Initially, the current node is the root node, but at later stages is either some descendant of the root node, or another referenced node.
+
Displayed child nodes
+
The DOM [=nodes=] that are rendered as child nodes of a given node when taking [=shadow root|shadow roots=] and [=slot|slots=] into consideration.
Flat string
A string of characters where all carriage returns, newlines, tabs, and form-feeds are replaced with a single space, and multiple spaces are reduced to a single space. The string contains only character data; it does not contain any markup.
Total accumulated text
@@ -394,11 +396,23 @@

Computation steps

  • For :after pseudo elements, User agents MUST append CSS textual content, without a space, to the textual content of the current node.
    • -
  • For each child node of the current node: +
  • + Determine the displayed child nodes of the current node:
      -
    1. Set the current node to the child node.
      2. -
    2. Compute the text alternative of the current node beginning with step 2. Set the result to that text alternative.
      3. -
    3. Append the result to the accumulated text.
      4. +
    4. If the current node has an attached [=shadow root=], set the displayed child nodes to be the child nodes of the [=shadow root=].
      5. +
    5. Otherwise, if the current node is a [=slot=] with [=slot/assigned nodes=], set the displayed child nodes to be the [=slot/assigned nodes=] of the current node.
      6. +
      + Comment: +

      A [=slot=] with [=slot/assigned nodes=] displays those nodes; otherwise it displays its default content, i.e. its child nodes.

      +
      +
    6. Otherwise, set the displayed child nodes to be the child nodes of the current node.
      7. +
    +
    • +
  • For each displayed child node of the displayed child nodes of the current node: +
      +
    1. Set the current node to the displayed child node.
      2. +
    2. Compute the text alternative of the current node beginning with step 2. Set the result to that text alternative.
      3. +
    3. Append the result to the accumulated text.
  • Return the accumulated text if it is not the empty string ("").
    • From 30078348b57eeb1fde2fd56393882eee5ec396d3 Mon Sep 17 00:00:00 2001 From: Nolan Lawson Date: Thu, 29 Sep 2022 11:03:24 -0700 Subject: [PATCH 02/14] Update index.html Co-authored-by: James Craig --- index.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/index.html b/index.html index c201d31..bf59e0f 100644 --- a/index.html +++ b/index.html @@ -397,7 +397,7 @@

    Computation steps

  • - Determine the displayed child nodes of the current node: + Determine the rendered child nodes of the current node:
    1. If the current node has an attached [=shadow root=], set the displayed child nodes to be the child nodes of the [=shadow root=].
    2. Otherwise, if the current node is a [=slot=] with [=slot/assigned nodes=], set the displayed child nodes to be the [=slot/assigned nodes=] of the current node.
      3. From 852dd64c4fa944a97bf9ce8fa8e29b57050f6019 Mon Sep 17 00:00:00 2001 From: Nolan Lawson Date: Thu, 29 Sep 2022 11:03:37 -0700 Subject: [PATCH 03/14] Update index.html Co-authored-by: James Craig --- index.html | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/index.html b/index.html index bf59e0f..2bc3f36 100644 --- a/index.html +++ b/index.html @@ -224,8 +224,8 @@

      Terminology

      The DOM [=nodes|node=] or [=element=] for which the text alternative is sought.
      Current node
      The DOM [=nodes|node=] currently traversed to compute the root node's text equivalent. Initially, the current node is the root node, but at later stages is either some descendant of the root node, or another referenced node.
      -
      Displayed child nodes
      -
      The DOM [=nodes=] that are rendered as child nodes of a given node when taking [=shadow root|shadow roots=] and [=slot|slots=] into consideration.
      +
      Rendered child nodes
      +
      The [=nodes=] that are rendered as child nodes of a given node when taking [=shadow root|shadow roots=] and [=slot|slots=] into consideration.
      Flat string
      A string of characters where all carriage returns, newlines, tabs, and form-feeds are replaced with a single space, and multiple spaces are reduced to a single space. The string contains only character data; it does not contain any markup.
      Total accumulated text
      From 8020dce859d477401faf348ecdd24db6aa1fb8ad Mon Sep 17 00:00:00 2001 From: Nolan Lawson Date: Thu, 29 Sep 2022 11:03:48 -0700 Subject: [PATCH 04/14] Update index.html Co-authored-by: James Craig --- index.html | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/index.html b/index.html index 2bc3f36..0181488 100644 --- a/index.html +++ b/index.html @@ -399,8 +399,8 @@

      Computation steps

    3. Determine the rendered child nodes of the current node:
        -
      1. If the current node has an attached [=shadow root=], set the displayed child nodes to be the child nodes of the [=shadow root=].
        2. -
      2. Otherwise, if the current node is a [=slot=] with [=slot/assigned nodes=], set the displayed child nodes to be the [=slot/assigned nodes=] of the current node.
        3. +
      3. If the current node has an attached [=shadow root=], set the rendered child nodes to be the child nodes of the [=shadow root=].
        4. +
      4. Otherwise, if the current node is a [=slot=] with [=slot/assigned nodes=], set the rendered child nodes to be the [=slot/assigned nodes=] of the current node.
        5. Comment:

        A [=slot=] with [=slot/assigned nodes=] displays those nodes; otherwise it displays its default content, i.e. its child nodes.

        From 37d40482550e6ec0cfa8ec3d1c2e89fda2f9248e Mon Sep 17 00:00:00 2001 From: Nolan Lawson Date: Thu, 29 Sep 2022 11:23:42 -0700 Subject: [PATCH 05/14] Update index.html Co-authored-by: James Craig --- index.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/index.html b/index.html index 0181488..9ff88ce 100644 --- a/index.html +++ b/index.html @@ -405,7 +405,7 @@

        Computation steps

        Comment:

        A [=slot=] with [=slot/assigned nodes=] displays those nodes; otherwise it displays its default content, i.e. its child nodes.

        -
      5. Otherwise, set the displayed child nodes to be the child nodes of the current node.
        6. +
      6. Otherwise, set the rendered child nodes to be the child nodes of the current node.
    4. For each displayed child node of the displayed child nodes of the current node: From fd225a35f4f5ed72cb4198ba5449498d66b3dbca Mon Sep 17 00:00:00 2001 From: Nolan Lawson Date: Thu, 29 Sep 2022 11:23:50 -0700 Subject: [PATCH 06/14] Update index.html Co-authored-by: James Craig --- index.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/index.html b/index.html index 9ff88ce..afc0cd7 100644 --- a/index.html +++ b/index.html @@ -408,7 +408,7 @@

      Computation steps

    5. Otherwise, set the rendered child nodes to be the child nodes of the current node.
    • -
  • For each displayed child node of the displayed child nodes of the current node: +
  • For each rendered child node of the current node:
    1. Set the current node to the displayed child node.
    2. Compute the text alternative of the current node beginning with step 2. Set the result to that text alternative.
      3. From afd6ea5bd54dee70cc38de5f747f1739558b5065 Mon Sep 17 00:00:00 2001 From: Nolan Lawson Date: Thu, 29 Sep 2022 11:23:59 -0700 Subject: [PATCH 07/14] Update index.html Co-authored-by: James Craig --- index.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/index.html b/index.html index afc0cd7..0e4a768 100644 --- a/index.html +++ b/index.html @@ -410,7 +410,7 @@

      Computation steps

    3. For each rendered child node of the current node:
        -
      1. Set the current node to the displayed child node.
        2. +
      2. Set the current node to the rendered child node.
      3. Compute the text alternative of the current node beginning with step 2. Set the result to that text alternative.
      4. Append the result to the accumulated text.
      From 95782ce81c0b41c47416153575cfdba44cffa6e1 Mon Sep 17 00:00:00 2001 From: Nolan Lawson Date: Thu, 29 Sep 2022 11:34:45 -0700 Subject: [PATCH 08/14] add language about slot representing --- index.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/index.html b/index.html index 0e4a768..68022b2 100644 --- a/index.html +++ b/index.html @@ -403,7 +403,7 @@

      Computation steps

    4. Otherwise, if the current node is a [=slot=] with [=slot/assigned nodes=], set the rendered child nodes to be the [=slot/assigned nodes=] of the current node.
      5. Comment: -

      A [=slot=] with [=slot/assigned nodes=] displays those nodes; otherwise it displays its default content, i.e. its child nodes.

      +

      A [=slot=] element represents its [=slot/assigned nodes=], if any, and its contents (child nodes) otherwise.

    5. Otherwise, set the rendered child nodes to be the child nodes of the current node.
    From 442df9abf246f0d4ff59890d6eb9de35ad8cd91c Mon Sep 17 00:00:00 2001 From: Nolan Lawson Date: Thu, 20 Oct 2022 08:20:16 -0700 Subject: [PATCH 09/14] fix: fix roman numerals --- index.html | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/index.html b/index.html index 68022b2..adf25d8 100644 --- a/index.html +++ b/index.html @@ -408,14 +408,14 @@

    Computation steps

  • Otherwise, set the rendered child nodes to be the child nodes of the current node.
    • -
  • For each rendered child node of the current node: +
  • For each rendered child node of the current node:
      -
    1. Set the current node to the rendered child node.
      2. -
    2. Compute the text alternative of the current node beginning with step 2. Set the result to that text alternative.
      3. -
    3. Append the result to the accumulated text.
      4. +
    4. Set the current node to the rendered child node.
      5. +
    5. Compute the text alternative of the current node beginning with step 2. Set the result to that text alternative.
      6. +
    6. Append the result to the accumulated text.
    • -
  • Return the accumulated text if it is not the empty string ("").
    • +
  • Return the accumulated text if it is not the empty string ("").

    • Important: Each [=nodes|node=] in the subtree is consulted only once. If text has been collected from a descendant, but is referenced by another IDREF in some descendant node, then that second, or subsequent, reference is not followed. This is done to avoid infinite loops.

    From 8d17a285214ba3b40a56a7416b774497d5f4a5d2 Mon Sep 17 00:00:00 2001 From: Nolan Lawson Date: Fri, 21 Oct 2022 06:42:02 -0700 Subject: [PATCH 10/14] fix: remove comment --- index.html | 4 ---- 1 file changed, 4 deletions(-) diff --git a/index.html b/index.html index adf25d8..9a588bc 100644 --- a/index.html +++ b/index.html @@ -401,10 +401,6 @@

    Computation steps

    1. If the current node has an attached [=shadow root=], set the rendered child nodes to be the child nodes of the [=shadow root=].
    2. Otherwise, if the current node is a [=slot=] with [=slot/assigned nodes=], set the rendered child nodes to be the [=slot/assigned nodes=] of the current node.
      3. -
      - Comment: -

      A [=slot=] element represents its [=slot/assigned nodes=], if any, and its contents (child nodes) otherwise.

      -
    3. Otherwise, set the rendered child nodes to be the child nodes of the current node.
    From 51c6b095aa6265758d69f596f5115719c8b96476 Mon Sep 17 00:00:00 2001 From: Nolan Lawson Date: Thu, 17 Nov 2022 14:27:17 -0800 Subject: [PATCH 11/14] chore: fix whitespace --- index.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/index.html b/index.html index 9a588bc..58db849 100644 --- a/index.html +++ b/index.html @@ -407,7 +407,7 @@

    Computation steps

  • For each rendered child node of the current node:
    1. Set the current node to the rendered child node.
      2. -
    2. Compute the text alternative of the current node beginning with step 2. Set the result to that text alternative.
      3. +
    3. Compute the text alternative of the current node beginning with step 2. Set the result to that text alternative.
    4. Append the result to the accumulated text.
    • From a9cfa2e946b0b4516fd8b32ba54d763f391f55df Mon Sep 17 00:00:00 2001 From: Nolan Lawson Date: Fri, 26 May 2023 15:57:08 -0700 Subject: [PATCH 12/14] fix: revert whitespace changes --- index.html | 300 ++++++++++++++++++++++++++--------------------------- 1 file changed, 150 insertions(+), 150 deletions(-) diff --git a/index.html b/index.html index 0c43e6b..ad80993 100644 --- a/index.html +++ b/index.html @@ -1,48 +1,48 @@ - Accessible Name and Description Computation 1.2 - - - - - - - + + + + + preProcess: [ linkCrossReferences ], + postProcess: [ addPlatformMaintainers ], + //Pointing to the 1.2 versions but should remove the version in the publishing branch + xref: ["dom", "core-aam-1.2", "wai-aria-1.2", "infra"] + } +
    @@ -161,23 +161,23 @@

    Introduction

    The terms "accessible name" and "accessible description" are used to emphasize that they are properties of accessible objects as exposed by Accessibility APIs. However, they are frequently referred to hereafter as simply "name" and "description".

    -

    Important Terms

    -
    -

    While some terms are defined in place, the following definitions are used throughout this document.

    -
    +

    Important Terms

    +
    +

    While some terms are defined in place, the following definitions are used throughout this document.

    +
    Accessible Description
    -
    -

    An accessible description provides additional information, related to an interface element, that complements the accessible name. The accessible description might or might not be visually perceivable.

    -
    -
    Accessible Name
    -
    -

    The accessible name is the name of a user interface element. Each platform accessibility API provides the accessible name property. The value of the accessible name may be derived from a visible (e.g., the visible text on a button) or invisible (e.g., the text alternative that describes an icon) property of the user interface element. See related accessible description.

    -

    A simple use for the accessible name property may be illustrated by an "OK" button. The text "OK" is the accessible name. When the button receives focus, assistive technologies may concatenate the platform's role description with the accessible name. For example, a screen reader may speak "push-button OK" or "OK button". The order of concatenation and specifics of the role description (e.g., "button", "push-button", "clickable button") are determined by platform accessibility APIs or assistive technologies.

    -
    +
    +

    An accessible description provides additional information, related to an interface element, that complements the accessible name. The accessible description might or might not be visually perceivable.

    +
    +
    Accessible Name
    +
    +

    The accessible name is the name of a user interface element. Each platform accessibility API provides the accessible name property. The value of the accessible name may be derived from a visible (e.g., the visible text on a button) or invisible (e.g., the text alternative that describes an icon) property of the user interface element. See related accessible description.

    +

    A simple use for the accessible name property may be illustrated by an "OK" button. The text "OK" is the accessible name. When the button receives focus, assistive technologies may concatenate the platform's role description with the accessible name. For example, a screen reader may speak "push-button OK" or "OK button". The order of concatenation and specifics of the role description (e.g., "button", "push-button", "clickable button") are determined by platform accessibility APIs or assistive technologies.

    +
    Tooltip attribute
    -
    -

    Any host language attribute that would result in a user agent generating a tooltip such as in response to a mouse hover in desktop user agents.

    -
    +
    +

    Any host language attribute that would result in a user agent generating a tooltip such as in response to a mouse hover in desktop user agents.

    +
    @@ -215,49 +215,49 @@

    Description Computation

    The following table provides the order of precedence for markup that can be applied to compute an accessible description. User agents MUST use the first applicable entry from the table where the listed conditions are met, as described in the last column. The user agent MUST NOT use any markup other that the first relevant markup found, even if that markup results in an empty description:

    - - - - - - + + + + + + - - - - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + + + + + +
    PrecedenceAttributeApplicable conditionsHow used to compute description
    PrecedenceAttributeApplicable conditionsHow used to compute description
    1aria-describedby attributeUse on any elementText content computation on all nodes referenced by aria-describedby on the element, concatenated, and separated by a space character
    2aria-description attributeUse on any elementAs a flat string
    3host language features which participate in the description calculation - Unique host language features MAY participate in the description computation for an element, only if they were not already used - for the accessible name of the applicable element. See HTML AAM: Accessible Description Computation - for the HTML elements which meet this condition. - - Either a text equivalent computation of the element, or as a flat string of the attribute's value. -
    4host language tooltip attribute or equivalent feature (e.g., HTML title attribute) -
      -
    • Any element
      • -
    • Only use if not already used for the accessible name of this node
      • -
    -     		As a flat string
    1aria-describedby attributeUse on any elementText content computation on all nodes referenced by aria-describedby on the element, concatenated, and separated by a space character
    2aria-description attributeUse on any elementAs a flat string
    3host language features which participate in the description calculation + Unique host language features MAY participate in the description computation for an element, only if they were not already used + for the accessible name of the applicable element. See HTML AAM: Accessible Description Computation + for the HTML elements which meet this condition. + + Either a text equivalent computation of the element, or as a flat string of the attribute's value. +
    4host language tooltip attribute or equivalent feature (e.g., HTML title attribute) +
      +
    • Any element
      • +
    • Only use if not already used for the accessible name of this node
      • +
    +     		As a flat string
    @@ -320,11 +320,11 @@

    Computation steps

  • Computation: Compute the text alternative for the current node:
    1. Hidden Not Referenced: If the current node is [=element/hidden=] and is: -
        -
      1. Not part of an aria-labelledby or aria-describedby traversal, where the node directly referenced by that relation was hidden.
        2. -
      2. Nor part of a native host language text alternative element (e.g. label in HTML) or attribute traversal, where the root of that traversal was hidden.
        3. -
      - Return the empty string. +
        +
      1. Not part of an aria-labelledby or aria-describedby traversal, where the node directly referenced by that relation was hidden.
        2. +
      2. Nor part of a native host language text alternative element (e.g. label in HTML) or attribute traversal, where the root of that traversal was hidden.
        3. +
      + Return the empty string.
      Comment:

      It's important to clarify the broad definition of hidden for the purposes of accessible name calculation:

      @@ -371,18 +371,18 @@

      Computation steps

      Comment:

      The result of LabelledBy Recursion in combination with Hidden Not Referenced means that user agents MUST include all nodes in the subtree as part of the accessible name or accessible description, when the node referenced by aria-labelledby or aria-describedby is hidden.

      -
      - Example: -

      The following example shows the meaning of the clause "… and the current node is not already part of an aria-labelledby traversal …" .

      -
        -
      1. element1's accessible name is "hello" because this is a first traversal of its aria-labelledby, leading to element3.
        2. -
      2. element2 has no accessible name. The computation involves a first traversal of its aria-labelledby leading to element1, but element1's aria-labelledby is not subsequently followed.
        3. -
      - 
      <element1 id="el1" aria-labelledby="el3" />
+              
      
+                Example:
+                
      The following example shows the meaning of the clause "… and the current node is not already part of an aria-labelledby traversal …" .
      
+                
        
+                  
      1. element1's accessible name is "hello" because this is a first traversal of its aria-labelledby, leading to element3.
        2. 
+                  
      2. element2 has no accessible name.  The computation involves a first traversal of its aria-labelledby leading to element1, but element1's  aria-labelledby is not subsequently followed. 
        3. 
+                
      
+                
      <element1 id="el1" aria-labelledby="el3" />
 <element2 id="el2" aria-labelledby="el1" />
 <element3 id="el3"> hello </element3>
                 
      
-                
      
+
    2. Embedded Control: Otherwise, if the current node is a control embedded within the label (e.g. any element directly referenced by aria-labelledby) for another widget, where the user can adjust the embedded control's value, then return the embedded control as part of the text alternative in the following manner:
        @@ -409,8 +409,8 @@

        Computation steps

      Example: -

      The following example shows the interaction of aria-labelledby and aria-label when a [=nodes|node=] has an aria-labelledby that refers to itself. The <span role="button"> elements have the accessible names "Delete Documentation.pdf" and "Delete HolidayLetter.pdf", respectively.

      - 
      <h1>Files</h1>
+                  
      The following example shows the interaction of aria-labelledby and aria-label when a [=nodes|node=] has an  aria-labelledby that refers to itself.  The <span role="button"> elements have the accessible names "Delete Documentation.pdf" and "Delete HolidayLetter.pdf", respectively.
      
+                  
      <h1>Files</h1>
 <ul>
   <li>
     <a id="file_row1" href="./files/Documentation.pdf">Documentation.pdf</a>

From 84a03a589a9f18841725723e22548e0362c8308c Mon Sep 17 00:00:00 2001
From: Nolan Lawson 
Date: Thu, 1 Jun 2023 09:34:37 -0700
Subject: [PATCH 13/14] fix: update index.html

Co-authored-by: James Craig 
---
 index.html | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/index.html b/index.html
index ad80993..966c217 100644
--- a/index.html
+++ b/index.html
@@ -442,9 +442,9 @@ 
      Computation steps
      
                 
                 
    3. Determine Child Nodes: Determine the rendered child nodes of the current node:
                   
        
-                    
      1. If the current node has an attached [=shadow root=], set the rendered child nodes to be the child nodes of the [=shadow root=].
        2. 
-                    
      2. Otherwise, if the current node is a [=slot=] with [=slot/assigned nodes=], set the rendered child nodes to be the [=slot/assigned nodes=] of the current node.
        3. 
-                    
      3. Otherwise, set the rendered child nodes to be the child nodes of the current node.
        4. 
+                    
      4. If the current node has an attached [=shadow root=], set the rendered child nodes to be the child nodes of the [=shadow root=].
        5. 
+                    
      5. Otherwise, if the current node is a [=slot=] with [=slot/assigned nodes=], set the rendered child nodes to be the [=slot/assigned nodes=] of the current node.
        6. 
+                    
      6. Otherwise, set the rendered child nodes to be the child nodes of the current node.
        7. 
                   
      
                 
      4. 
                 
    4. Name From Each Child: For each rendered child node of the current node:

From 1d37077088d92bb00d81f5ab3ffa9ca05fef3683 Mon Sep 17 00:00:00 2001
From: Nolan Lawson 
Date: Thu, 1 Jun 2023 09:34:48 -0700
Subject: [PATCH 14/14] fix: update index.html

Co-authored-by: James Craig 
---
 index.html | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/index.html b/index.html
index 966c217..d20d1ec 100644
--- a/index.html
+++ b/index.html
@@ -440,7 +440,7 @@ 
      Computation steps
    • -
  • Determine Child Nodes: Determine the rendered child nodes of the current node: +
  • Determine Child Nodes: Determine the rendered child nodes of the current node:
    1. If the current node has an attached [=shadow root=], set the rendered child nodes to be the child nodes of the [=shadow root=].
    2. Otherwise, if the current node is a [=slot=] with [=slot/assigned nodes=], set the rendered child nodes to be the [=slot/assigned nodes=] of the current node.