Tooltip `aria-describedby` not announced for navigation buttons

[swashbuck]

Subject

Navigation buttons with tooltips (Dev Tools, Page Level Progress, ToC, Home Button, etc.) have aria-describedby set pointing to the tooltip element, but screen readers never announce the tooltip text.

Root cause

In TooltipItemView line 134, ariaHidden is computed as:

ariaHidden: (document.activeElement === this.$target[0] || this.isStatic)

When a button has keyboard focus, ariaHidden is true, and tooltip.jsx applies aria-hidden="true" to .tooltip__body. The tooltip text is invisible to screen readers at exactly the moment it is needed, and aria-describedby points to a hidden subtree which screen readers ignore. The aria-live="assertive" region also fires nothing as the inserted content is aria-hidden.

Context

Navigation buttons already have aria-label providing their accessible name. Tooltips on these buttons are a visual affordance for sighted users when button labels are hidden — screen reader users don't need the tooltip text, they get the name from aria-label. The other known uses of the tooltip system are adapt-pageNav (Previous, Next, Home buttons — also navigation buttons with aria-label) and adapt-contrib-hotgraphic, which uses static tooltips — these currently have aria-hidden="true" applied via the isStatic condition.

Based on the above, it is unclear whether any current tooltip use relies on aria-describedby being readable by screen readers. However, the fix should still be opt-in rather than removing aria-describedby globally, to avoid breaking any future tooltip uses that may legitimately rely on it.

Suggested fix

Add an opt-out flag to tooltips.register():

tooltips.register({
  _id: 'devtools',
  _setAriaDescribedBy: false,
  ...
});

TooltipItemView.initialize() would then conditionally skip setting aria-describedby based on that flag. Nav buttons opt out; other tooltip targets retain the current behaviour.

Also note: there is a stale-attribute bug in TooltipItemView.remove() where this.$target is nulled before the removeAttr check, so aria-describedby is never cleaned up on the button after the tooltip is destroyed regardless.

[swashbuck]

@oliverfoster Thoughts on this?

[oliverfoster]

Yes. I'm struggling to believe that aria-describedby is deliberately set as the label but never read.

It was there in the original pr.
https://github.com/adaptlearning/adapt-contrib-core/blame/2c6ef07f8bfe5fe4dd317e4d0dad899cbd1f86e1/js/views/TooltipItemView.js#L49

Is it not for the mouse-over behaviour?

There are a few issues with displaying and announcing tooltips on focus, mouseover, and screen reader cursor. Some are detectable, some not, some not in time, some not for non-sighted users, some for sighted users.

I think it might be that you're testing keyboard focus only? Screen reader users can sometimes also use mice and will require the tooltip to read on mouse over.

Update

It looks as though the tooltip reads from a live region on mouse over. So it is not for mouse-over:

adapt-contrib-core/js/views/TooltipView.js

Line 119 in 2c6ef07

this.$el.append(tooltipItem.$el);

adapt-contrib-core/js/views/TooltipView.js

Lines 15 to 18 in 2c6ef07

	return {
	role: 'region',
	'aria-live': 'assertive'
	};

It also looks as though the tooltip was originally aria-hidden on focus:
0b3b098#diff-c31c0de427d506df22a9326bfc00ec55633900d5acf4ddb5fea5c10cf5de4dbeL72

It seems that the only place the tooltip might read via the target aria-describedby is under the following conditions:

• the tooltip is shown via mouse-over on target
• the tooltip is not static
• the target does not have focus
• the screen reader cursor is moved on to the target

References

• aria-describedby