Expectations for aria-hidden and focused elements #2181

scottaohara · 2024-05-20T19:34:31Z

This PR closes #1765 and is related to work that was done in #2037, but scoped only to the original issue I filed.

The intent of this PR is to identify not only how user agents would need to handle focusable elements that are aria-hidden (explicitly or due to being a descendant of an aria-hidden container) - but for the case where a focusable element is within an aria-hidden container, that the entire subtree would need to be re-exposed so that any other relevant information to the user could be made available. (e.g., so as to not just expose a "learn more" link, with no way to determine what someone would be learning about)

a simple example being like:

<div aria-hidden=true>
  <h3>Something or other</h3>
   some details about said something, or other.
  <a href=#>Learn more!</a>
</div>

Related Core AAM Issue/PR:
Related AccName Issue/PR:
Any other dependent changes?

Test, Documentation and Implementation tracking

Once this PR and all related PRs have been approved by the working group, tests
should be written and issues should be opened on browsers. Add N/A and check when not
applicable.

Related APG Issue/PR:
MDN Issue/PR:
"author MUST" tests:
"user agent MUST" tests:
Browser implementations (link to issue or when done, link to commit):
- WebKit:
- Gecko:
- Blink:
Does this need AT implementations?

Preview | Diff

This PR closes #1765 and is related to work that was done in #2037, but scoped only to the original issue I filed. The intent of this PR is to identify not only how user agents would need to handle focusable elements that are aria-hidden (explicitly or due to being a descendant of an aria-hidden container) - but for the case where a focusable element is within an aria-hidden container, that the entire subtree would need to be re-exposed so that any other relevant information to the user could be made available. (e.g., so as to not just expose a "learn more" link, with no way to determine what someone would be learning about) a simple example being like: ``` <div aria-hidden=true> <h3>Something or other</h3> some details about said something, or other. <a href=#>Learn more!</a> </div> ```

index.html

aleventhal · 2024-05-20T20:02:31Z

That seems like a good idea, and also, to not use aria-hidden if something is already inert / display-none etc.

…

On Mon, May 20, 2024 at 3:41 PM scottaohara ***@***.***> wrote: ***@***.**** commented on this pull request. ------------------------------ In index.html <#2181 (comment)>: > @@ -11604,6 +11604,7 @@ <h2>Definitions of States and Properties (all aria-* attributes)</h2> <p><a>Indicates</a>, when set to <code>true</code>, that an <a>element</a> and its entire subtree are hidden from assistive technology, regardless of whether it is visibly rendered.</p> <p>User agents determine an element's [=element/hidden=] status based on whether it is rendered, and the rendering is usually controlled by CSS. For example, an element whose <code>display</code> property is set to <code>none</code> is not rendered. An element is considered [=element/hidden=] if it, or any of its ancestors are not rendered or have their <code>aria-hidden</code> attribute value set to <code>true</code>.</p> <p>Authors MAY, with caution, use aria-hidden to hide visibly rendered content from assistive technologies <em>only</em> if the act of hiding this content is intended to improve the experience for users of assistive technologies by removing redundant or extraneous content. Authors using aria-hidden to hide visible content MUST ensure that identical or equivalent meaning and functionality is exposed to assistive technologies.</p> + <p>Additionally, authors SHOULD ensure that any elements that are accessibility descendants of an aria-hidden element, or any elements which have been marked as aria-hidden themselves, are prevented from receiving focus. If an aria-hidden element or a descendant of an aria-hidden ancestor receives focus, User Agents MUST ignore the aria-hidden state of any ancestor to the focused element, resulting in the entire subtree to be exposed to assistive technologies from that point forward, even once the element loses focus or is no longer focusable.</p> i know this section is already note-heavy, but i was debating on whether it was worth mentioning that authors SHOULD consider using host language features, like inert or display: none to properly hide content and thus mitigate needing to worry about this at all. — Reply to this email directly, view it on GitHub <#2181 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAKQAZSVE5APGONCM3M3IULZDJGXJAVCNFSM6AAAAABIAINPZCVHI2DSMVQWIX3LMV43YUDVNRWFEZLROVSXG5CSMV3GSZLXHMZDANRWHA4TINZWHA> . You are receiving this because you commented.Message ID: <w3c/aria/pull/2181/review/2066894768 ***@***.***>

rahimabdi · 2024-05-21T20:19:28Z

This may be WPT-testable; should I create a separate issue if you'd like tests for this (the MUST around the subtree being re-exposed)?

scottaohara · 2024-05-21T21:25:53Z

talking with @smhigley about this... but should this clarify that if an element is already focused and its container becomes aria-hidden, then the aria-hidden state should remain unless focus is then moved to another element within that hidden subtree.

for instance, think of a custom modal dialog that was built where the order of events are:

button invokes dialog (focus is on button)
element containing button set to aria-hidden=true
dialog is rendered (outside aria-hidden=true container)
focus moves to dialog

since focus moving is the last thing that occurs, we do not want browsers to immediately undo the aria-hidden that was dynamically added (though focus is still on the button inside the aria-hidden container)

Using aria-hidden on content that is actually visible can cause problems if a node inside receives focus. In the past, nothing was announced, and the fix was to expose all focusable nodes inside of an aria-hidden, but with the invisible state. This gave the AT a chance to decide to make the announcement. However, this fix did not work with VoiceOver or NVDA, and only partially worked with JAWS. The new approach is to assume the aria-hidden is correct and to not expose anything in the subtree, unless the user somehow is able to focus something in subtree. In that case, it is assumed to be an authoring error and misuse of aria-hidden. As such, browsers will now consider the bad aria-hidden on the containing element to be invalid and ignore it from that point forward, causing the entire subtree to now be exposed as visible. See this PR for the ARIA spec: w3c/aria#2181. This also helps enable a downstream CL that removes 125 lines. Fixed: 40833533 Change-Id: Ib0d7eed10fada5ae7799c5af1257e5a66fb0c034 Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/5544894 Reviewed-by: David Tseng <[email protected]> Commit-Queue: Aaron Leventhal <[email protected]> Cr-Commit-Position: refs/heads/main@{#1306971}

scottaohara · 2024-05-28T20:27:34Z

need to add to this that user agents need to make this repair if the element focused is in the same document - but say if the element that is focused is within an iframe, but the iframe is hidden from an aria-hidden surrounding it in the parent doc, then browsers may not be able to reasonably make this repair.

smhigley · 2024-05-28T21:27:46Z

I have one other question, but mostly for browser implementors; I'm not sure if this amount of detail can be in the spec --

Would the removal of aria-hidden occur after the focus event on an element, or after document.activeElement is set to point to a hidden element? I'm making the distinction because in a lot of our focus management logic for things like dialogs, we look for a focus event on a hidden element (either a focus bumper, or looking for focus moving to the background page), and immediately send focus back into the dialog in the event handler. The result is that document.activeElement never points to a hidden element, but the focus event does fire. If the change happened as a result of the event, it would break quite a lot of things at least in our library, and IIRC in others as well 😅.

If that's not the case, and if the scenario that @scottaohara already mentioned is also handled, I think I wouldn't have any more concerns about this.

aleventhal · 2024-05-28T21:43:07Z

We aren't actually changing the DOM, aka doing a removeAttribute(). We are just adding that node to a list of nodes where we will ignore it's aria-hidden markup from now on. Because of this, there shouldn't be any ordering questions. It means that in the a11y update that contains the focus event, the subtree's content will be there unhidden.

…

On Tue, May 28, 2024 at 5:28 PM Sarah Higley ***@***.***> wrote: I have one other question, but mostly for browser implementors; I'm not sure if this amount of detail can be in the spec -- Would the removal of aria-hidden occur after the focus event on an element, or after document.activeElement is set to point to a hidden element? I'm making the distinction because in a lot of our focus management logic for things like dialogs, we look for a focus event on a hidden element (either a focus bumper, or looking for focus moving to the background page), and immediately send focus back into the dialog in the event handler. The result is that document.activeElement never points to a hidden element, but the focus event does fire. If the change happened as a result of the event, it would break quite a lot of things at least in our library, and IIRC in others as well 😅. If that's not the case, and if the scenario that @scottaohara <https://github.com/scottaohara> already mentioned is also handled, I think I wouldn't have any more concerns about this. — Reply to this email directly, view it on GitHub <#2181 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAKQAZW2PGKDNACEN27QSY3ZETZGRAVCNFSM6AAAAABIAINPZCVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDCMZWGE2DAMJZHE> . You are receiving this because you commented.Message ID: ***@***.***>

smhigley · 2024-05-29T05:58:46Z

@aleventhal I think I may not have communicated my use case well enough 😅.

The distinction between doing a .removeAttribute() and ignoring the attribute through some other method wasn't really material to the question I had in mind, though bringing it up does make me worry that this may make it difficult for developers to debug when an element hidden in markup is exposed.

For my original question, I made this JS Fiddle to help: https://jsfiddle.net/sjc89htb/. It uses logic similar to what we use at Microsoft, and what I've seen for focus traps elsewhere, where focus is immediately sent elsewhere when it lands on a hidden element. In practice this works perfectly in all ATs I've tested up till now. Would you be able to clarify whether it will continue working with this change, or whether the change will result in the hidden content being exposed?

Thanks for taking the time to investigate and weigh in!

index.html

aleventhal · 2024-05-29T14:41:52Z

@aleventhal I think I may not have communicated my use case well enough 😅.

Thanks for explaining... good chance the issue was on the receiver's end :)

The distinction between doing a .removeAttribute() and ignoring the attribute through some other method wasn't really material to the question I had in mind, though bringing it up does make me worry that this may make it difficult for developers to debug when an element hidden in markup is exposed.

We could log something like an error to the JS console, warning the developer that bad aria-hidden markup had been discarded. I thought we had similar guidance for other user agent repairs, but I can't find that in the spec after a quick search.

For my original question, I made this JS Fiddle to help: https://jsfiddle.net/sjc89htb/. It uses logic similar to what we use at Microsoft, and what I've seen for focus traps elsewhere, where focus is immediately sent elsewhere when it lands on a hidden element. In practice this works perfectly in all ATs I've tested up till now. Would you be able to clarify whether it will continue working with this change, or whether the change will result in the hidden content being exposed?

It seems to work! Our proposed change is currently implemented in Chrome Canary from this morning, version 127.0.6508.0. I ran with and without the focus trap. In the version without the focus trap, once you tab into the button, the button is revealed in the a11y tree (I used the devtools Inspector full page a11y view for the test). In the version with the focus trap, focus never goes to the button, and the aria-hidden is never discarded. I think this is an important test that we should add to WPT tests. @scottaohara maybe we can update the spec text to say if focus is not forwarded somewhere else? Perhaps it should mentioned as a valuable technique, although maybe authors should be using inert here.

Anyway, go ahead and play with Canary if you like. I'll wait to hear back what people think of a console message to developers. Maybe something like, console.error("The following element had aria-hidden markup that was discarded, because focus went to it or an element within it. See WAI-ARIA rules on aria-hidden:", bad_aria_hidden_element);

smhigley · 2024-05-29T18:50:28Z

@aleventhal awesome! I love both the idea of putting that scenario in WPT, and the idea of logging a warning to the console.

I'm all in on this now, thanks again for investigating!

aleventhal · 2024-05-30T17:57:59Z

Landing a patch to Chromium that adds this console error:

  element.AddConsoleMessage(
      mojom::blink::ConsoleMessageSource::kRendering,
      mojom::blink::ConsoleMessageLevel::kError,
      String::Format(
          "Blocked aria-hidden on a <%s> element because the element that just "
          "received focus must not be hidden from assistive technology users. "
          "Avoid using aria-hidden on a focused element or its ancestor. "
          "Consider using the inert attribute instead, which will also prevent "
          "focus. For more details, see the aria-hidden section of the "
          "WAI-ARIA specification at https://w3c.github.io/aria/#aria-hidden.",
          element.TagQName().ToString().Ascii().c_str()));

Should we add text to this PR saying that user agents may provide a helpful console error message?
Also, can we update this PR to say how developers can fix the issue? (Either by forwarding focus via focusin, by not putting aria-hidden on focusable objects, by using inert etc.)

index.html

pulling in aaron's suggested edits

netlify · 2024-08-07T18:24:15Z

✅ Deploy Preview for wai-aria ready!

Name	Link
🔨 Latest commit	`24aa28b`
🔍 Latest deploy log	https://app.netlify.com/sites/wai-aria/deploys/66f58b22a35e3d00089e918f
😎 Deploy Preview	https://deploy-preview-2181--wai-aria.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site configuration.

adds in a reference to the tree exclusion section, and updates bits of content here to include reference to html's `inert` attribute, and to try and acknowledge the change to aria-hidden=false by also referencing aria-hidden=undefined.

scottaohara · 2024-08-07T18:39:03Z

made updates per the provided feedback, so re-requesting reviews.

index.html

aleventhal · 2024-08-29T20:43:43Z

Landing a patch to Chromium that adds this console error:
  element.AddConsoleMessage(
      mojom::blink::ConsoleMessageSource::kRendering,
      mojom::blink::ConsoleMessageLevel::kError,
      String::Format(
          "Blocked aria-hidden on a <%s> element because the element that just "
          "received focus must not be hidden from assistive technology users. "
          "Avoid using aria-hidden on a focused element or its ancestor. "
          "Consider using the inert attribute instead, which will also prevent "
          "focus. For more details, see the aria-hidden section of the "
          "WAI-ARIA specification at https://w3c.github.io/aria/#aria-hidden.",
          element.TagQName().ToString().Ascii().c_str()));
Should we add text to this PR saying that user agents may provide a helpful console error message? Also, can we update this PR to say how developers can fix the issue? (Either by forwarding focus via focusin, by not putting aria-hidden on focusable objects, by using inert etc.)

@scottaohara

index.html

this has nothing to do with my PR, but there is an errant closing `</p>` tag after a list in the progressbar section. making this change here to get rid of the error

scottaohara · 2024-09-26T16:27:34Z

per my last commit - it looks like @giacomo-petri had already tried to fit the errant ending p tag (#2244) but since this PR was made before that, it was still here.... and since the errant ending tag is still in the current spec - it clearly got re-introduced by a commit since Giacomo's.

giacomo-petri · 2024-09-26T17:32:54Z

I believe I understand the reason behind this:

...omissis... are either prevented from receiving focus, or upon receiving focus use scripting to immediately move focus to another element.,

However, in the context of the following sentence:

The ancestor aria-hidden markup will continue to be ignored, even once the element loses focus or is no longer focusable. User agents MAY provide console messages to warn or flag aria-hidden errors to developers.

this could introduce issues, potentially causing a discrepancy between the experience of assistive technologies (where everything is exposed) and keyboard navigation (where the operable control is only used for functional reasons for moving focus somewhere else).

Should we be more strict by removing "either" and stating that authors should ensure these aria-hidden true elements do not receive focus at all? The sentence already begins with "authors SHOULD," which is less strict than "MUST NOT," and we are not prohibiting focus management via JavaScript. However, without "either," I think the guidance would likely be clearer.

scottaohara · 2024-09-26T23:47:20Z

@giacomo-petri that text was deliberately added in because there are component libraries in use that do this without issue.

having div tabindex=0 aria-hidden=true bumpers at the start/end of a component that needs to 'trap' tab key focus. from what i've been told in talking about this with at least one component library (ahem @smhigley) is that this is far more performant than querying all the elements within the container, and needing to make dynamic adjustments for the instances where the focusable elements (particularly first/last) might change, and having to re-determine what elements should loop focus again/where the new focus should go to.

I am not aware of where this actually hurts anything - but automated checkers flag this up and down and I can tell you that I've seen a report of over 2500 instances of this "issue" across a select few products, and all 2500 are considered a "false positive" because of the effort that went into making sure that there would be no negative user impact.

That said, I have also done recent testing to this pattern and haven't found much in the way of a difference to whether the aria-hidden exists on that div or not.... but I also have not had the time to go into the deep level of testing that I know others have on this in support of adding the attribute in the first place. (please note this is not just used for ARIA modal dialog purposes, but other instances where trapping tab key might be necessary, while implementing other keyboard navigation behaviors). i'm just hesitant at this point to do anything else with this text, since it's already been word smithed into its current state to account for this scenario. If others have suggestions though that can maintain the intent without undoing what people wanted in there, then please, have at it :)

aleventhal reviewed May 20, 2024

View reviewed changes