Add a mechanism for accessible tooltips in core

[joedolson]

While we've worked hard to eliminate usage of the title attribute across most of WordPress core, there is still an occasional need for that type of contextual information, and the lack of it is a barrier to resolving some issues (e.g. #50921) and removing some of the last instances of the title attribute.

An accessible tooltip will need to meet these criteria:

1) Be available either via the mouse, via the keyboard, or via touch.
2) Be persistent until dismissed
3) Support primary & auxiliary usage, dependent on whether the tooltip is the sole name of the control or an elaboration of existing text.

Useful reference on accessible tooltips: ​https://inclusive-components.design/tooltips-toggletips/

[oglekler]

Proposal for tooltips in settings

[oglekler]

There are different possibilities for tooltips usage:

• alternative to title attribute
• standalone helper

We need them to:

• Creating clean, more modern design in the admin and reduce visual complexity and clatter.
• Providing unified tool to plugins and themes developers for tooltips in the admin (right now some of them have their own implementations)
• Standardizing tooltips usage in WordPress to make sure that they are aria friendly and provide expected behavior in core, themes and plugins

References:
​https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/tooltip_role
​https://m2.material.io/components/tooltips#theming

[oglekler]

Here is a need for more advanced Tooltip implementation
https://core.trac.wordpress.org/ticket/21583#comment:55
and it looks like it can depend on this one's functionality.

I wonder if Tooltip in jQuery UI is good enough to cover our needs and meet all accessibility requirements, or we need to look for another solution.

[davidbaumwald]

I apologize if this was discussed elsewhere, but I don't see anything here. Has any consideration been given to using the ​Tooltip component from the block editor?

If not, I feel like this might be something that should be considered, and might be improved if there are a11y issues.

[joedolson]

The block editor tooltip doesn't seem very suitable, based on how I see it used - it's hidden from screen readers, it's not dismissable, and depends on aria-label for accessible naming.

We could work on improving that - I think it would require a pretty much total refactor. The way its used in the block editor, the only change that would be needed within that context is making it dismissable; but for broader usage, it would also need to be communicated to screen readers and not be dependent on aria-label for naming.

[joedolson]

See: ​https://github.com/WordPress/gutenberg/issues/48222

[oglekler]

I believe one of the requirements is an ability to use this tooltip for plugin and theme developers by adding its data in $args parameter of add_settings_field() function and possibly calling it by itself.

@davidbaumwald can we use the Tooltip component this way?

[joedolson]

Specifications for an accessible tooltip for WordPress:

Definitions: 'source' refers to the object a tooltip is related to. 'content' refers to the visible text content of the tooltip. 'name' refers to the accessible name of the control itself.

1) Tooltips are primarily supplemental information, and should not override the name of the source. This means they should not depend on something like aria-label on the source.

2) Tooltip content should not require a move of focus.

a) When the tooltip is also the name of the control, rather than supplemental information, it should be associated as a label field, either sourced from aria-label or using aria-labelledby.

b) For supplemental tooltips, the content should be associated with the source using aria-describedby. E.g. <input type="name" aria-describedby="tooltip-1"><div id="tooltip-1">Your full first and last name</div>.

3) If there is interactive content in a tooltip, it must be next in tab sequence after the source and be accessible to a screen reader or keyboard without dismissing the tooltip.

4) All tooltips must be dismissable without removing focus a source. When a tooltip appears on focus, it should be dismissable using esc. This will mean ensuring that the keyboard esc event doesn't trigger unexpected closures when used inside modals or other esc-closable contexts. It will also require a visible close button that can be used by pointer devices to close the tooltip and move focus to the source *without* re-triggering the tooltip.

a) Note: the close button will also need to meet WCAG's requirements for control size.

5) The tooltip should not use role="tooltip", aria-haspopup, or aria-live. The role has no significant support, and as written does not allow interactive content. Tooltips are not popups, and aria-live should not be used for naming and descriptions of static content.

6) Tooltips should be available for touch interactions. This ensures that a) non-hovering pointer AT will be able to get the tooltip information and b) the friction of using controls on mobile will help reduce excessive use of tooltips, since while they should be possible, they should *not* be overused.

7) Tooltips should *not* support formatting such as heading, bold text, italics, etc. These will not be conveyed to screen readers.

8) Interactive content should be strongly discouraged and avoided if at all possible. If the tooltips simply do not support it, that would be entirely adequate.

9) Tooltips should only be supported on interactive sources - buttons, links, inputs, etc.

10) The title attribute should not be used on the source.

11) There should not be a timeout on the tooltip.

[oglekler]

This could also be a tooltip: #58312

[oglekler]

This is an enhancement, and we have zero chances to make it until Beta 1, so, sadly, I am moving this ticket to 6.4.

I believe that this is a significant improvement we can make, so, I am asking all who are browsing this ticket to collaborate working on the one nice patch 🙏🙂

[oglekler]

I didn't have time to work on this patch and no one picked up this so far, so I am moving this ticket into 6.5 in hope that we will make a progress there.

PR for adding the initial draft for the Tooltip functionality.

Trac ticket: https://core.trac.wordpress.org/ticket/51006

[rajinsharwar]

Hi all, I tried to start the work on this feature to get things started. I know the code isn't perfect or not that good, but I hope this will provide a good benchmark for getting things rolling for this feature.

Demo: ​https://prnt.sc/zkAl_zz_XwPo

Introduced a new function: add_tooltip()

It accepts a total of 3 parameters:

• The 1st is a UNIQUE field ID, which will be used as the div ID of the tooltip container.
• The 2nd is the tooltip-text which will be shown to the users upon click or click of Enter (For keyboard users)
• The 3rd is an OPTIONAL parameter, which will be used as the Label for the Tooltip. If nothing passed, the default goes as "Help".

Example Usage:

add_tooltip('tooltip-1', $tagline_description);
add_tooltip('tooltip-2', 'This is a Text for the Tooltip');

[joedolson]

Thanks for getting started on this @rajinsharwar!

I'm wondering if the PHP function is necessary. I feel like this would be more easily implemented if it was done entirely in the JS, and just looked for appropriate data attribute, then generated the appropriate HTML as needed.

The JS and CSS should be something we can add to common.js and common.css, as the intended implementation should be fairly broad, and there's no intention to make this available on the front-end.

Adding Tooltip in Admin via only JS and CSS.

Trac ticket: https://core.trac.wordpress.org/ticket/51006

[rajinsharwar]

Updated changes: ​https://screenpal.com/watch/cZV0cIVJycu

Thanks for your feedback @joedolson, and I appreciate your suggestion. The reason I thought of going over with a function is that we can use this both in the frontend and backend. In #55343, a proposal was raised for adding a Tooltip to "Remember Me" of the wp-login.php. So, if we choose to go with only a JS approach, in that case, we might need to have it in separate files and load those both in the admin panel and in the wp-login.php. So, my opinion is to have a PHP function that can be called from both the Frontend and Admin panel and also to enqueue those scripts wherever there is a tooltip on the screen, not on all pages.

Still, if we choose to go with the JS way, and have those scripts and styles only in the admin, I have submitted the (PR 5928)​https://github.com/WordPress/wordpress-develop/pull/5928 as well, which includes this change :). It's now up to what we choose to go with. Requesting suggestions on this, so maybe we can try to get this land before Beta 1 in February.

Example Usage of the new PR:

<div class="tooltip-container" data-tooltip-text="<?php _e( $tooltip_description ) ?>"></div>

<div class="tooltip-container" data-tooltip-text="<?php _e( 'This is another Text for the Tooltip' ) ?>"></div>

Adding 2nd opinion for suggestions.

Updated the PR based on the feedback @mukeshpanchal27 :)

[joedolson]

After discussing in the accessibility bug scrub, we're thinking that having the markup generated in the PHP function is more compelling. Let's pursue that further.

We'd also like to try and make use of some of the logic that already exists in the Gutenberg tooltip implementation, particularly about calculating tooltip position. This might require some coordination.

[joedolson]

Moving this to future release. Still intend to work on for 6.7, but we feel that we won't have time for it in this release.

[oglekler]

Realted tickets: #58312 and #55343

[rajinsharwar]

Hi all, I would like to add it to the 6.7 release to get the appropriate attention to this feature. I have also made some improvements to the existing PR: 5676 ( As it was preferred to go with the PHP option to render the tooltip ). I will be adding improvements over time to this issue, also if anyone feels this is not going in the correct direction, feel free to share that!

[rajinsharwar]

As an update here's what I have done to the current tooltips.

1. Added on-hover toggle instead of on-click.
2. The toggle can be focused with the Tab key, and also unfocused with Escape.
3. The toggle is also clickable for mobile devices.
4. From the PHP function, we can now pass the $default_position, in which position we want the tooltip by default. Accepted values, "top", "bottom", "right", and "left", and default value as right.
5. The tooltip's popup will not adjust its position automatically based on screen size. For example, if the default is left, and there is space on the left, the tooltip automatically changes its position to the right.
6. If the same tooltip-id is being used to render the tooltip for duplicate elements, the tooltips still function without conflicts. ( As far as I have tested. If I have missed any, feel free to share ).
7. As each tooltip has individual IDs, extenders, or even in the core, appropriate IDs can be targeted to apply/override the styles.

Example usage:

<?php add_tooltip('tooltip-2', 'This is a Text for the Tooltip', 'Help', 'left'); ?>

<?php add_tooltip('tooltip-3', 'This is another top Text for the Tooltip', 'Helpme', 'top'); ?>

1. Added validations and _doing_it_wrong fro the arguments passed.
2. Added a new filter that can be used to change the Tooltip icon image. This is similar to the one we have in add_menu() function. We can now pass the URL, or the SVG, or the dashicon class, or even the "none" to style using CSS.

Example usage:

add_filter( 'wp_tooltip_icon', 'my_filter', 10, 2 );

function my_filter( $icon_url, $field_id ) {
    $icon_url = "data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMjAiIGhlaWdodD0iMjAiIHZpZXdib3g9IjAgMCAyMCAyMCIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj48cGF0aCBmaWxsPSIjYTdhYWFkIiBkPSJNMTcuNiA4LjVoLTcuNXYzaDQuNGMtLjQgMi4xLTIuMyAzLjUtNC40IDMuNC0yLjYtLjEtNC42LTIuMS00LjctNC43LS4xLTIuNyAyLTUgNC43LTUuMSAxLjEgMCAyLjIuNCAzLjEgMS4ybDIuMy0yLjJDMTQuMSAyLjcgMTIuMSAyIDEwLjIgMmMtNC40IDAtOCAzLjYtOCA4czMuNiA4IDggOGM0LjYgMCA3LjctMy4yIDcuNy03LjgtLjEtLjYtLjEtMS4xLS4zLTEuN3oiIGZpbGxydWxlPSJldmVub2RkIiBjbGlwcnVsZT0iZXZlbm9kZCI+PC9wYXRoPjwvc3ZnPg==";

    return $icon_url;
}

This will show an SVG now in the tooltip.

Example:

3. Added a new action hook that's fired just before the tooltip is rendered in HTML.
4. Loading the styles and scripts for the tooltip before it's rendered to not show a slightly broken tooltip.

Screenshots:

Using Tab navigation:

[davidbaumwald]

With 6.7 Beta 1 releasing in a few hours, this is being moved to Future Release given a lack of recent momentum towards a resolution.

If any committer feels the remaining work can be resolved in time for Beta 1 or any other specific milestone and wishes to assume ownership during that cycle, feel free to update the milestone accordingly.

[joedolson]

I've worked this up, modifying PR5676 to the point where I think it's a viable option. @rajinsharwar provided a great start, but there were some things to do to enhance accessibility and make it more flexible.

I've updated the interaction model so that it matches the standards set by the US Design System: ​https://designsystem.digital.gov/components/tooltip/.

I also increased the size of the default button so that it would meet WCAG 2.5.8; the minimum size is now 26px x 26px, exceeding the minimum required of 24x24.

To make the tool more useful, I added handlers so that it can be used declaratively by adding the class '.wp-tooltip-container' to an anchor or button wrapper and a data-tooltip attribute to the control. This will improve it's flexibility for use with existing code.

For testing, use:

function test_tooltips() {
    if ( function_exists( 'add_tooltip' ) ) {
        echo '<div class="notice notice-info">';
        add_tooltip( 'Test Tooltip' );
        echo '<div class="wp-tooltip-container"><button type="button" id="wp-tooltip-custom-trigger" data-tooltip="This is the content of the tooltip">Trigger</button></div>';
        echo '</div>';
    }
}

The add_tooltip() call will test the simplest case usage of the new function; the printed code tests the declarative usage.

[swissspidy]

A bit late to the party, but just saw the notification about this.

Given that Gutenberg already maintains a tooltip component that could be easily used elsewhere in WordPress admin, it seems silly to me to maintain a completely separate implementation with a very different design and functionality. I think this is a real missed opportunity. I see that was mentioned before but never followed up on.

If a second implementation is required in the short term for whatever reason, then this should be implemented in a way that the implementation could be easily swapped out later without backward compatibility concerns, for example by making this function private and not make it available to plugins.
In such a case, I would also suggest looking at more modern web APIs that make tooltips implementations a breeze, such as Popover API and CSS anchor positioning. That means you can build accessible tooltips with basically zero JavaScript.

Besides, I would strongly advocate for a different function name. add_tooltip is too close to add_option or add_post_meta. Why not wp_print_tooltip or something?

But again, why not explore using the existing Gutenberg component first :-)

[joedolson]

I thought I'd have more time this week, and frankly, I just haven't had it. Given that I also think that using something like the popovers API in native HTML would be vastly preferable, it really makes sense to just punt this for now.

I don't personally have any interest in spending time on the Gutenberg component, and given that the popover API is really pretty close to being viable, don't think it's particularly worth while.

Different function name I'd fully support.