Skip to content

Various components: Improve localization and ARIA#9071

Merged
henon merged 19 commits intoMudBlazor:devfrom
danielchalmers:a11y-9
Jun 1, 2024
Merged

Various components: Improve localization and ARIA#9071
henon merged 19 commits intoMudBlazor:devfrom
danielchalmers:a11y-9

Conversation

@danielchalmers
Copy link
Member

@danielchalmers danielchalmers commented May 27, 2024

Description

Now that I've implemented several PRs for this area, I'm able to look back an make revisions on earlier work. I now understand that ARIA labels should be used more sparingly ("No ARIA is better than bad ARIA").

Reviewed all aria-labels and localization in MudBlazor in order to:

  • Localize previously hardcoded values
  • Deletes several labels that were either for divs (obsolete) or were excessive
  • Deletes the harmful "Icon Button"/"Icon" fallback from the adornment
  • Make all labels nullable and the default is null instead of an empty string
  • Improve XML docs

Notes:

  • labels for MudNumericField and similar controls should be done through the helper text (aria-labelledby/aria-describedby)
  • We are producing empty aria-label attributes through empty bindings - This should be fixed in the future

How Has This Been Tested?

visually

Type of Changes

  • Bug fix (non-breaking change which fixes an issue)
  • New feature (non-breaking change which adds functionality)
  • Breaking change (fix or feature that would cause existing functionality to not work as expected)
  • Documentation (fix or improvement to the website or code docs)

Checklist

  • The PR is submitted to the correct branch (dev).
  • My code follows the code style of this project.
  • I've added relevant tests.

@github-actions github-actions bot added enhancement Adds a new feature or enhances existing functionality (not fixing a defect) in the main library PR: needs review labels May 27, 2024
@danielchalmers
Copy link
Member Author

danielchalmers commented May 27, 2024

@igotinfected Thanks for all your help, I've got another for you. This time I'm doing refinement on earlier PRs in addition to more localization. I realized I added too many aria-labels which is more harmful than anything. If a button (for example) already has text, it really doesn't need a label as well. Icon buttons are where they come in best.

Speaking of icons, I'm not sure it's right that we hide all icons from screen readers:

<svg class="@Classname" style="@Style" focusable="false" viewBox="@ViewBox" aria-hidden="true" role="img" @attributes="UserAttributes">

Seems like it's the right thing only if they are decorative or already described by a label?

because im not sure if it's the right thing to do when it's not keyboard navigatable
@danielchalmers
Copy link
Member Author

Do you know what's up with this error @ScarletKuro ?

System.InvalidOperationException : Cannot provide a value for property 'Localizer' on type 'MudBlazor.MudInput`1[[System.String, System.Private.CoreLib, Version=8.0.0.0, Culture=neutral, PublicKeyToken=7cec85d7bea7798e]]'. There is no registered service of type 'MudBlazor.InternalMudLocalizer'.

@ScarletKuro
Copy link
Member

Do you know what's up with this error @ScarletKuro ?

Look at the test, it's using a context that has no mudblazor services registered at all.

@codecov
Copy link

codecov bot commented May 27, 2024

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 90.63%. Comparing base (28bc599) to head (9f7bd20).
Report is 242 commits behind head on dev.

Additional details and impacted files
@@            Coverage Diff             @@
##              dev    #9071      +/-   ##
==========================================
+ Coverage   89.82%   90.63%   +0.80%     
==========================================
  Files         412      398      -14     
  Lines       11878    12378     +500     
  Branches     2364     2405      +41     
==========================================
+ Hits        10670    11219     +549     
+ Misses        681      621      -60     
- Partials      527      538      +11     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

@danielchalmers danielchalmers added the accessibility Accessibility concerns (ARIA, keyboard, focus, screen readers, contrast) label May 28, 2024
Copy link
Member

@igotinfected igotinfected left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Added some thoughts!

Seems like it's the right thing only if they are decorative or already described by a label?

Yeah from what I see they should only be aria-hidden if they don't have a function. I think you can consider icons not to have a function if the parent (say a div or a button or an a) have an accessible label.

For cases like MudInput in this PR for instance you could choose to add the label to the MudButton instead of the MudIcon. I assume that if the icon is aria-hidden the label might not even be shown in the accessibility tree or be announced by a screen reader.

Looking at the MudIcon razor code by itself I think that if IsAngleBracket is true and a Title is provided you are already in the clear from an accessibility point of view for most modern browsers (with aria-hidden="false" or not present at all).

@igotinfected
Copy link
Member

Also for the resource keys I would suggest not using punctuation/special characters in the resources to be able to use static references (in reference to the MudDataGrid keys). It's probably something that will be caught in the PR reviews but one less worry in general ;)

@danielchalmers
Copy link
Member Author

danielchalmers commented May 28, 2024

Also for the resource keys I would suggest not using punctuation/special characters in the resources to be able to use static references (in reference to the MudDataGrid keys). It's probably something that will be caught in the PR reviews but one less worry in general ;)

Yes! I tried to fix all that but it didn't render properly due to the weird markup and all the text was literally "MudDataGrid_etcetc", then I couldn't figure out how the punctuation was actually used. Didn't have time to familiarize myself with the technicalities so just reverted the changes :(

@danielchalmers danielchalmers requested a review from henon May 28, 2024 23:47
@danielchalmers
Copy link
Member Author

@henon Ready to review

@ScarletKuro
Copy link
Member

ScarletKuro commented May 28, 2024

Also for the resource keys I would suggest not using punctuation/special characters in the resources to be able to use static references (in reference to the MudDataGrid keys). It's probably something that will be caught in the PR reviews but one less worry in general ;)

Should we change the datagrid keys? Though it will be a breaking change :( I dislike that we now have inconsistencies where some use . and some use _.

@danielchalmers
Copy link
Member Author

Also for the resource keys I would suggest not using punctuation/special characters in the resources to be able to use static references (in reference to the MudDataGrid keys). It's probably something that will be caught in the PR reviews but one less worry in general ;)

Should we change the datagrid keys? Though it will be a breaking change :( I dislike that we now have inconsistencies where some use . and some use _.

@ScarletKuro Take a look at bd0d536 and see if you can figure out why it renders the keys literally (The filter placeholder will say "MudDataGrid_FilterValue")

@ScarletKuro
Copy link
Member

@ScarletKuro Take a look at bd0d536 and see if you can figure out why it renders the keys literally (The filter placeholder will say "MudDataGrid_FilterValue")

If you look at LanguageResource.resx, the XML keys are with a dot name="MudDataGrid.Ungroup", but the code generator can't use . so it generates the language resource designer property with an underscore MudDataGrid_Ungroup. However, that's just the property name for the static reference, not the key name. That's why when you use nameof, it will return the property name with an underscore, but not its underlying key. This is why it uses @Localizer["MudDataGrid.Ungroup"]. Using nameof is actually incorrect, as the property name is not equal to the key. At least I haven't seen this practice when people use a custom localizer (like we do) instead of a static reference like @LanguageResource.MudDataGrid_Ungroup. However, we cannot use the latter since we allow overriding translations, using interceptors, etc.

@danielchalmers
Copy link
Member Author

danielchalmers commented May 29, 2024

@ScarletKuro So weird, thanks for the explanation. What do you think we should do about it? I can do the bulk of the refactoring

@henon
Copy link
Contributor

henon commented May 31, 2024

Also for the resource keys I would suggest not using punctuation/special characters in the resources to be able to use static references (in reference to the MudDataGrid keys). It's probably something that will be caught in the PR reviews but one less worry in general ;)

Should we change the datagrid keys? Though it will be a breaking change :( I dislike that we now have inconsistencies where some use . and some use _.

We'll do it but not in v7. Let's just put it on our list and at some time when we make another major version and don't have a massive change set we'll do it. Adding this to the v8 project, but we don't necessarily have to do it in v8, it can wait.

@henon
Copy link
Contributor

henon commented May 31, 2024

Is this ready to merge?

@danielchalmers
Copy link
Member Author

danielchalmers commented May 31, 2024

Is this ready to merge?

@henon Yes

EDIT: Wait for @jperson2000

@danielchalmers
Copy link
Member Author

@jperson2000 Mind taking a look at these doc changes?

Copy link
Contributor

@jperson2000 jperson2000 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's great to see the improvements for accessibility and localization! The only thought I had was to communicate to users what "aria-label" is somehow, but I couldn't think of a specific suggestion or docs change. Good changes, though, with active language.

@danielchalmers
Copy link
Member Author

@henon Ready to merge!

@henon henon merged commit 5cf1fd7 into MudBlazor:dev Jun 1, 2024
@henon
Copy link
Contributor

henon commented Jun 1, 2024

Thanks

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

accessibility Accessibility concerns (ARIA, keyboard, focus, screen readers, contrast) enhancement Adds a new feature or enhances existing functionality (not fixing a defect) in the main library

Projects

None yet

Development

Successfully merging this pull request may close these issues.

5 participants