Description

Vaadin components with overlays (e.g. Dialog, Popover, Tooltip, ComboBox, Select, etc) will be refactored to use the native html popover API.

Tier

Free

License

Apache 2.0

Motivation

Background

Overlays in Vaadin components are currently rendered in a separate "layer" at the bottom of the DOM in order to be able to render on top of all other content in the viewport.

Problem

The current implementation has several drawbacks:

• An element cannot responsively switch between overlay and non-overlay rendering, as this would require moving elements between the overlay-layer and the normal placement in the DOM. (MasterDetailLayout is planned to have a workaround but with limitations.)
• Accessibility: Moving focus between non-modal overlays and the rest of the UI by keyboard is awkward, since the overlays are in a completely different part of the DOM. (Some components currently use JS-based workarounds to overcome this.)
• Styling: Overlays that are part of another component (e.g. the ComboBox dropdown) cannot be styled as child elements of that component, because they're not (the overlayClassname API needs to be used for this).
• Mixing the current overlay implementation with native popovers isn't possible, since the latter always render over the former (so we cannot use native popovers on new UI features, and it's not compatible with 3rd party components that use it).

Solution

Refactoring all Vaadin component overlays to use the native html popover API makes it possible to render them on top of everything else without moving them to their own "DOM layer" and resolves all of these issues.

The plan is to refactor vaadin-overlay to be based on popover, which means that any 3rd party add-ons based on it should be fairly easy to refactor to the new model.

PositionMixin used for positioning overlays could also be refactored to use native CSS anchor positioning, if it is supported by all major browsers by the time V25 ships.

We could also look into the possibility of utilizing the html <dialog> element for Dialogs, as it provides focus trapping and return of focus to the trigger element out of the box, but this is likely to be problematic due to there apparently not being any way to show another overlay on top of a modal <dialog>.

This refactorization should also allow us to reduce overlay-related code significantly, and is likely to increase the performance of overlays somewhat.

Requirements

• vaadin-overlay refactored to use popover
• All Vaadin components with overlays ensured to work correctly
• Modality works correctly
• Nested overlays work correctly
• Multiple concurrent non-modal dialogs work correctly (with regards to bringToFront() etc)
• Styling documentation updated to reflect these changes (e.g. overlays of ComboBox etc can now be styled as child elements of the component)

Nice-to-haves

• Focus handling in Popover refactored to utilize adjacency to trigger element
• PositionMixin refactored based on CSS anchor positioning

Risks, limitations and breaking changes

Risks

Two challenges are already known:

1. How to refactor the implementation of modality semantics. The current approach applies aria-hidden to all sibling elements of a modal overlay, but this won't be possible when the overlays are no longer in their own "layer". The aria-modal attribute (which seems to have sufficient support in all major browser/screen reader combinations these days) provides a solution, although it requires the overlay's role to be dialog or alertdialog (which may or may not be a problem).
2. The handling of multiple concurrent overlays must be handled in a new way as the current z-index-based approach for switching the topmost overlay is unlikely to work.

Breaking changes

• Add-ons with overlays are likely to require some refactoring even if they are based on vaadin-overlay.
• Minor changes to the DOM structure of overlay components can be expected, which might cause some custom styling to break.

Out of scope

No response

Materials

No response

Metrics

No response

Pre-implementation checklist

• Estimated (estimate entered into Estimate custom field)
• Product Manager sign-off
• Engineering Manager sign-off

Pre-release checklist

• Documented (link to documentation provided in sub-issue or comment)
• UX/DX tests conducted and blockers addressed
• Approved for release by Product Manager

Security review

Not applicable