Tooltips (Popover Components) within modals aren't visible in the Site Editor and on small screens

[afercia]

Description

Hat tip to @carolinan for discovering this in #47540

The first part of this issue is an actual regression. The second part appears to have always been there.

To better understand the root cause of this issue I'd like to recap a couple points about the CSS stacking context:

A stacking context is formed, anywhere in the document, by any element in the following scenarios:
...
Element with a position value absolute or relative and z-index value other than auto.
Element with a position value fixed or sticky ...

The difference is that an element with position absolute does need also a z-index other than auto to establish a new stacking context, while an element with position fixed establishes a new stacking context regardless whether it has a z-index value.

1
Site Editor, desktop view: any tooltip used within any modal is not visible. The tooltip is rendered but it's actually hidden behind the modal. Instead, in the Post Editor the tooltips work fine.

2
Post Editor and Site Editor (and I assume also the Widget editor and the Nav editor), on small screens: same as above, any tooltip within modals is not visible.

The root cause for the first issue
After #44770 the element with CSS class edit-site has now a position value of fixed. Previously, it was absolute. This element establishes a new stacking context and:

• The tooltip is rendered in the .popover-slot within the .edit-site element, with a high z-index value but this has an effect only inside the .edit-site stacking context.
• The Modal is rendered outside of the .edit-site element so it belongs to another stacking contex. Whatever the tooltip z-index value is, the Modal is always 'on top' of the tooltip.

The root cause for the second issue
On small screens, the element with ID #wpwrap takes a position value of fixed. This comes from common.css in core:

body.mobile.modal-open #wpwrap {
    overflow: hidden;
    position: fixed;
    height: 100%;
}

See the original changeset at https://core.trac.wordpress.org/changeset/32073
The outcome is similar to the first issue: #wpwrap establishes a new stacking context so that the tooltiip z-index value has effect only inside this stacking context. The modal is rendered outside of #wpwrap and it's always 'on top' of the tooltip.
The CSS in core is pretty old and I'm not sure whether this bug always occurred or something maybe changed in Gutenberg.

Step-by-step reproduction instructions

• Go to the Site Editor.
• Open any modal dialog, for example the Preferences modal or the Create new template modal.
• Hover on the X close button within the modal, or tab to it.
• Observe the button tooltip is not visible.
• Using your browser dev tools, emulate a small screen.
• Go to the Site Editor or Post Editor.
• Open any modal.
• Check the the body element has the CSS classes mobile and modal-open. Important note: the mobile class isn't added when resizing the viewport 'on the fly'. It's only added on page load, when the viewport is already set to a small size before loading the page.
• Hover on the X close button within the modal, or tab to it.
• Observe the button tooltip is not visible.
• I didn't check the Widget editor and Nav editor but I guess the mobile issue occurs there as well.

Screenshots, screen recording, code snippet

Site Editor Modal close button no visible tooltip:

Post Editor: Modal close button visible tooltip:

Mobile Post Editor: no visible tooltip:

Environment info

No response

Please confirm that you have searched existing issues in the repo.

Yes

Please confirm that you have tested with all plugins deactivated except Gutenberg.

Yes

[ndiego]

Thanks for reporting this @afercia, somehow we missed this issue leading up to the 6.2 release! It was reported this week in a support ticket for one of my personal plugins (Block Visibility), and I found my way here. I imagine others extenders will run into this issue if they haven't already. Therefore, I have added it for 6.2.1 consideration.

I recorded a short video demonstrating this issue. If a popover (tooltip) is placed in a modal, upon triggering the popover, it will appear behind the modal in 6.2. As mentioned above, this CSS was introduced in #44770.

popover-modal-issue.mp4

[afercia]

This is still an issue on current trunk. It would be great to try to fix it for the next incoming release. I'd defer to someone with broader CSS knowledge though. Cc @WordPress/gutenberg-design

Some more screenshots:

• Welcome guides in the Post editor: Tooltips are OK.
• Welcome guides in the Site editor: Tooltips are not visible.
• Welcome guides in the Widget editor: Tooltips are OK.

The Preferences modal dialog in the Site Editor:

Worth considering this affects all tooltips in the modal dialogs in the Site editor and potentially in any other component that is rendered outside of the .edit-site container. Not to mention plugins that use dialogs with icon buttons and tooltips are seriously affected, as @ndiego reported above.

[afercia]

The tooltip is rendered in the .popover-slot within the .edit-site element,

Update: That's no longer true.
In #48440 the Tooltip component has been refactored to use ariakit. Tooltips now render in their own 'portal' which is rendered in the DOM after the modal dialog:

As such, tooltips within the modal are now visible.

Still, there is no guarantee that future changes to the order of elements in the DOM and changes to the stacking context will not reintroduce the same bug. At the very least, there should be a couple E2E tests for tooltips within the modal, for both the post and site editors.

Although this bug no longer occurs, I'd like to keep this issue open until E2E tests are added.