Skip to content

Conversation

@dpvc
Copy link
Member

@dpvc dpvc commented Dec 7, 2025

This PR fixes problems identified with using a Braille output device in JAWS and NVDA on Windows. It turns out that for the aria-braillelabel to be read in JAWS, the role being application doesn't work, while role="img" does. But we need the speech element to be in an element with role="application" in order to remain in focus mode, so this PR wraps the speech node in an additional mjx-speech-container element with role="application" and makes the speech node have role="img".

Not all screen readers handle the aria-braillelabel attribute, however (e.g., NVDA), but if Braille is in the aria-label, they will pass it on to the Braille device. So we have added a menu option to include the Braille as part of the speech string. This lists the Braille first, followed by 40 blank Braille cells, followed by the speech string. The brail device should show the braille, but the speech will be off the right-hand edge and will not be displayed, but it will be spoken. In NVDA the Braille itself is not spoken (but in JAWS and some other readers it is, so this can't be the default setting).

We also add an option to replace the speech with the Braille, but that item is hidden and only kept as a backup in case it is needed.

Finally, we set the aria-braillroledescription to try to override the img role description, for those screen readers that process it.

@dpvc dpvc requested a review from zorkow December 7, 2025 23:11
@dpvc dpvc added this to the v4.1.0 milestone Dec 7, 2025
@codecov
Copy link

codecov bot commented Dec 7, 2025

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 86.49%. Comparing base (a14d976) to head (4ef32a6).

Additional details and impacted files
@@           Coverage Diff            @@
##           develop    #1396   +/-   ##
========================================
  Coverage    86.49%   86.49%           
========================================
  Files          340      340           
  Lines        85813    85813           
  Branches      3177     3177           
========================================
  Hits         74220    74220           
  Misses       11593    11593           

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

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

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

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants