Repository navigation
Give formatting buttons fallback accessible names - #115
Ehsan-hash wants to merge 3 commits into
Conversation
There was a problem hiding this comment.
🔵 Needs a closer look
The library-wide tooltip and accessible-description changes need maintainer accessibility sign-off.
1 open finding
What changed in this PR
Adds fallback accessible names for built-in Markdown toolbar buttons to address #43.
Changes:
- Adds default titles for all 13 built-in controls while preserving explicit titles, including empty ones.
- Tests default titles and preservation behavior.
- Documents English tooltips, localization, and suppression.
| File | Description |
|---|---|
| test/test.js | Adds default-title and title-preservation regression tests. |
| src/index.ts | Sets built-in button titles when absent. |
| README.md | Explains fallback naming and tooltip customization. |
🧠 Review effort: Max
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
|
|
||
| `<markdown-toolbar>` comes with focus management as advised in [WAI-ARIA Authoring Practices 1.1: Toolbar Design Pattern](https://www.w3.org/TR/wai-aria-practices-1.1/examples/toolbar/toolbar.html). The `md-*` buttons that ship with this package are automatically managed. Add a `data-md-button` attribute to any custom toolbar items to enroll them into focus management. | ||
|
|
||
| Built-in buttons receive an English default `title` when the attribute is absent. This provides a fallback accessible name and tooltip. Visible text, `aria-label`, and `aria-labelledby` still determine the accessible name. Set `title` to localize the tooltip, or `title=""` to suppress it. |
There was a problem hiding this comment.
Updated the README to state all three effects: a title may remain an accessible description despite a localized ARIA name; custom and native tooltips can both appear unless the native title is suppressed; and title="" also removes the fallback name, so an icon-only button needs another accessible name. This is documentation only. The implementation and its existing browser evidence are unchanged; the broader tooltip/accessibility choice remains with maintainers.
There was a problem hiding this comment.
thanks for clarifying this in the docs! I think we should avoid adding the default title when the button already has an accessible name though. could we limit this fallback to buttons without visible text, aria-label, or aria-labelledby? that would avoid adding an English native tooltip to controls that are already named while still covering unnamed icon-only buttons.
There was a problem hiding this comment.
Updated in d64eb6b. Default titles are now added at connection only when rendered text and both ARIA naming values are blank. Explicit titles, including an empty title, are preserved.
The rendered-text check also keeps hidden descendants and decorative SVG titles from suppressing the fallback. All 150 tests pass. Chrome accessibility-tree checks confirm the tested text/ARIA names retain their names without an added English title or description, while unnamed icons remain named. Reconnection and keyboard formatting checks pass. The README documents the connection-time scope.
Checks were run by the agent under the account owner's authorization.
Icon-only built-in formatting buttons can expose an empty accessible name. Give each built-in button a descriptive default title when the title attribute is absent. The browser uses it as a fallback name while keeping visible text and ARIA names ahead of it.
Existing titles, including empty titles, are preserved. The README explains the English default tooltip and how applications can localize or suppress it. Custom data-md-button controls are unchanged.
Validation: lint, TypeScript build and all 147 ChromeHeadless tests pass. The new default-title regression fails on the original code. Chromium accessibility-tree checks confirm names for all 13 built-in controls and preserve supplied names, including after text/ARIA updates and reconnection. Keyboard checks cover Enter, Space, ArrowRight, Home and End. These are browser checks, not a manual screen-reader test.
Fixes #43.