Add support for adding ACC descriptive text to a component
@jdichev is already working on this.
Since Nov 6, 2024.
- 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:
- - ui5-input: #5607
- - ui5-table: #6432
- - ui5-tree: #5593
- - ui5-button: #5310 https://github.com/UI5/webcomponents/issues/6445
- - ui5-link: #3993 https://github.com/UI5/webcomponents/issues/6445
- - ui5-list: #6181
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
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Assessment
This issue has not been assessed yet.