New feature proposal: Popover API

[mfreed7]

This is quite related to #6349, which was previously discussed in WHATWG. However, over the course of the last year or so, the OpenUI CG has been working through issues and maturing the proposal with the help of great feedback and brainstorming from both developers and implementers. The latest explainer (https://open-ui.org/components/popup.research.explainer) has changed the shape of the API from a new element (<popup>) to a content attribute (popup), and has changed several of the details, primarily to improve accessibility and broaden the applicability of the API.

Importantly, the OpenUI group resolved that this proposal looks good enough to start prototyping. I have started that process for Chromium.

While there are still many open issues that we're working through, I think the shape of the API is in a good enough shape to bring before WHATWG for implementer interest and (importantly!) input / feedback / guidance. Hence this issue.

For convenience, here are the background and goals sections from the explainer:

---

Background

There is a need in the Web Platform for an API to create "popup UI". This is a general class of UI that always appear on top of all other content, and have both one-at-a-time and "light-dismiss" behaviors. This document proposes a set of APIs to make this type of UI easy to build.

Goals

Here are the goals for this API:

• Allow any* element and its (arbitrary) descendants to be rendered on top of all other content in the host web application.
• Include “light dismiss” management functionality, to remove the element/descendants from the top-layer upon certain actions such as hitting Esc (or any close signal) or clicking outside the element bounds.
• Allow this “top layer” content to be fully styled, including properties which require compositing with other layers of the host web application (e.g. the box-shadow or backdrop-filter CSS properties).
• Allow these top layer elements to reside at semantically-relevant positions in the DOM. I.e. it should not be required to re-parent a top layer element as the last child of the document.body simply to escape ancestor containment and transforms.
• Allow this “top layer” content to be sized and positioned to the author's discretion.
  Include an appropriate user input and focus management experience, with flexibility to modify behaviors such as initial focus.
• Accessible by default, with the ability to further extend semantics/behaviors as needed for the author's specific use case.
• Avoid developer footguns, such as improper stacking of dialogs and popups, and incorrect accessibility mappings.
• Avoid the need for Javascript for the common cases.

[annevk]

I just realized that this naming clashes with window.open()'s popup feature as I initially thought this was about the new API for window.open() that we've been discussing. Perhaps it's enough if we can refer to this as viewport popups or some such, or perhaps we need slightly different name.

[mfreed7]

Yep, that’s unfortunate. More so because I worked on both of them, and should have thought of this potential confusion earlier. We are anyway bikeshedding the attribute name, so perhaps add your thoughts there?

[mfreed7]

Ok, per the triage meeting, my action item was to organize and summarize the open issues for Popup. Hopefully this helps:

Behavior:

• [popup] Should showPopup() and hidePopup() throw? openui/open-ui#511
• [selectmenu] button click behavior when the popup is open openui/open-ui#486
• [Popup] How should the "popup is top layer" CSS pseudo class behave, and what should it be called openui/open-ui#470
• [Popup] Light dismissal triggers for popup when used for context menu openui/open-ui#426
• [Popup] Triggering element support: buttons, text inputs, etc. openui/open-ui#420
• [Popup] Should blur() be a light dismiss trigger? openui/open-ui#415
• [popup] Consider to add popupshowing, popupshown, popuphiding and popuphidden events openui/open-ui#342
• [Popup] Supporting transitions and animations on open and dismiss openui/open-ui#335
• [Popup] [Tabs] [Details] Global behavior for Navigating into components openui/open-ui#344
• [Popup] Define accessibility mappings for popup and its primitives openui/open-ui#329
• [Popup] focus anchor after hide? openui/open-ui#327
• [Popup] Should light dismiss be cancellable on popup? openui/open-ui#321
• [Popup] Invoking popups from custom elements with script vs popup attribute openui/open-ui#302

Bikeshedding:

• [popup] Bikeshed: popup=popup is unusual openui/open-ui#491
• [popup] Consider renaming triggerpopup openui/open-ui#508
• [popup] Consider renaming initiallyopen openui/open-ui#500
• [Popup] Should the delegatesfocus attribute be renamed? openui/open-ui#368

Documentation / spec:

• [popup] Note that popup=async + JavaScript allows custom behavior openui/open-ui#495
• [popup] Articulate use cases for anchoring a bit better openui/open-ui#493
• [Popup] popup="" is supported on <button type=submit> but not <input type=submit> openui/open-ui#409
• [Popup spec] Make get the focusable area steps edits describe the correct behavior openui/open-ui#394
• [Popup spec] Update close watcher logic and focusing steps algo for popup light dismissal openui/open-ui#393
• [Popup spec] Update autofocus specifications in HTML for popup openui/open-ui#391
• [Popup spec] Move invoker activation behaviors to other parts of the HTML spec openui/open-ui#390
• [Popup] New IDL for Pop-Up content attributes, which allow Element references openui/open-ui#382
• [Popup spec] Define in finer detail processing of autofocus and delegatesfocus attrs for popup openui/open-ui#330
• [Popup spec] Specify hide event sequence openui/open-ui#324

Resolved, just needs implementation/testing:

• Ensure that delegatesfocus cannot trap focus openui/open-ui#379

Relationships to other APIs:

• Should the CSS Toggles API be able to declaratively open a popup? openui/open-ui#456
• [Popup] [Dialog] Evaluate which popup-related primitives should be extended to other elements openui/open-ui#323

Other:

• [Popup] Polyfil / Open UI component openui/open-ui#312

[mfreed7]

Quick update on this thread: the feedback from the HTML spec triage meeting on April 7 was that there were too many open issues for Pop-Up, and we should work to resolve them. OpenUI has been hard at work for the last 4 months discussing those issues and proposing ways forward. As of today, the open issues have been reduced to these 7 issues. The complex issues (see bigger list above, or this list of resolved issues) have been discussed at length and resolved (in the OpenUI sense), and the remainder are what I'd consider to be smaller issues. They still need a resolution, but I'm fairly confident we're on a path to that soon.

@josepharhar has been hard at work on a draft spec PR that explains all of the behaviors of the Pop-Up API, as designed and discussed within OpenUI. Stay tuned!

[josepharhar]

I have opened a PR: #8221

[mfreed7]

I just wanted to give a quick status update:

1. The HTML spec PR for the Pop-up API is at #8221. We've received some comments, but would really appreciate some good, detailed reviews.
2. For background and motivation, the best reference would be the explainer, which I've kept up-to-date as this feature has evolved in OpenUI. There is also this recent blog post, which has some nice working examples.
3. The open issues list remains small, with nothing that I would consider a fundamental or blocking concern.

Generally, we're looking for feedback and input for this feature, to make sure it works as expected, solves the problems it is trying to solve, and plays nicely with the rest of the platform. Thanks in advance!