UI5 / UI5/webcomponents

Add support for adding ACC descriptive text to a component

Open
#6,445 1 comment 0 reactions 3 assignees View on GitHub

@jdichev is already working on this.

Since Nov 6, 2024.

ACC feature request for discussion
Dominant language
TypeScript
Stars
1.8k
Forks
285
Avg merge
3d 2h
Merged PRs (30d)
59

Description

Feature Request Description

Give the developers the possibility to add accessible description text in ui5-webcomponents. For this we need to test possible approaches and extend/reuse the existing AriaLabelHelper util.

Proposed Solution

Similar to the accessibleName and accessibleNameRef, one should be able to add accessible description via an attribute (accessibleDescription/accessibleDescriptionRef). After the merge of #6364 we should extend the logic of the AriaLabelHelper (or re-use it) to cover this functionality. It could be achieved in two ways:

  • an accessibleDescription/accessibleDescriptionRef is passed to a web component. The value of the property/the text content of the element (should be handled in the same way as the accessibleNameRef) is passed to the aria-description attribute in the shadowDOM. This should be carefully tested as the aria-description property is still in draft https://w3c.github.io/aria/#aria-description. We should test on JAWS 2023, VoiceOver and NVDA latest and Chrome, Firefox, Edge & Safari. Check the current support stated here: https://developer.mozilla.org/en-US/docs/Web/API/Element/ariaDescription. If this does not work correctly in the tested SR+Browser combination we should focus on the second approach.
  • an accessibleDescription/accessibleDescriptionRef is passed to a web component. The value of the property/the text content of the element (should be handled in the same way as the accessibleNameRef) is passed as a textContent to a hidden span which is placed in the same shadow DOM as the element with the respective role (the one that receives the focus). This element should have an aria-describedby attribute pointing to the hidden span.
Additional Context
  • Regardless of the approach if an accessibleDescriptionRef is used it should also reflect dynamic changes of descriptive element. Example:
    <span id="descriptive-text">Element Description</span> <ui5-combobox accessible-description-ref="descriptive-text"></ui5-combobox> .... document.getElementById("descriptive-text").innerHTML = "New Description"
    -here the accessible description in the shadow DOM should be updated to New Description as well.
  • Depending on the use case component developers should decide if they want to enable the accessibleDescription, the accessibleDescriptionRef or both.
  • Please be aware that the aria-describedby is not announced for some roles. More info could be found in the aria specification (example - https://www.w3.org/WAI/tutorials/tables/caption-summary/#using-aria-describedby-to-provide-a-table-summary)
Priority
  • Low
  • Medium
  • High
  • Very High

A clear and concise description of the impact/urgency of the required feature.

Related Issues

Notice that the feature is requested several times:

All of them should be evaluated again (before enabling them), since in most cases the better approach is to label the element and to not add a description to it. Nevertheless the aria-describedby is not announced for certain roles and each case should be tested separately.

Please link other issues related to this if some component is missing.

Expected result
  • The AriaLabelHelper should be extended to cover accessible description scenario or a new util should be created.
  • We should evaluate if we should use aria-description or aria-describedby internally
  • After this issue is resolved feature requests for accessible description for every component should be enabled and evaluated separately

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.