Add an imperative way to set popover invoker relationships

[mfreed7]

What is the issue with the HTML Standard?

The popovertarget attribute "connects" a button to a popover, in three key ways:

• it creates nested popovers, if the invoking button is inside another popover.
• it modifies the sequential focus navigation order, so that the invoked popover comes "next" in keyboard focus order.
• it sets up aria-details and aria-expanded relationships between the invoker and the popover.

It seems like there should be an imperative way to create that relationship. This was agreed in OpenUI in openui/open-ui#1024 (comment), and at the WHATWG/CSSWG/OpenUI task force in #9144 (comment).

This issue proposes a simple addition to the three popover APIs:

popover.togglePopover({invoker: element});
popover.showPopover({invoker: element});
popover.hidePopover({invoker: element});

Some questions:

• can element be any element? Or just buttons? (Feels to me like it should be able to be any element, since the relationships created don't really depend on the button-ness of the invoker.)
• can element cross a shadow root, in either direction? As long as there's no way to retrieve the invoker element, it seems to be this could be done safely without exposing shadow roots.
• are there a11y implications of only creating the ARIA relationships at invocation time? The declarative API can set those up even before the button is clicked.

[scottaohara]

can element be any element?

while exposing an aria-expanded state won't work on just any element unless it has an implicit or explicit ARIA role that allows for that state to be exposed - maybe this is a way to allow those who have been asking to use popover with their custom button elements the ability to identify their invoker, and if 'any element' is allowed, then `div[role=button]' would be too.

are there a11y implications of only creating the ARIA relationships at invocation time? The declarative API can set those up even before the button is clicked.

depends on exactly what you mean by this. but for instance, if you just have a button in a web page, and an aria-expanded property is only added to it once clicked, then the state change is generally not exposed to screen readers by browsers. from what i remember, there is no signal for the AT to listen for simply by the addition of the expanded property to a button - but rather, only if the expanded property exists and its state changes. again, that's at least what i recall - would have to do some testing to determine if that's changed at all.

[mfreed7]

@scottaohara and I just discussed this, and I broadly agree with the points made above. One interesting conclusion:

• it's ok to have element be any element type, and the ARIA relationships will only be exposed if element has the right role.
• because aria-expanded can only be set at the time togglePopover() is called, it would be better for the custom element author to set aria-expanded=false on the button-like element before that. In which case, the browser shouldn't/can't change that attribute automatically, or override it in the a11y tree. So really, the best practice will be for aria-expanded state to be fully-controlled by the custom element author.

Perhaps that's as it should be for an imperative API - we can try to fix things up as best as possible, but typically the author will need to make sure they're doing things correctly. E.g. manually setting role=button for a button-like custom element.

[lukewarlow]

This either needs element to be a HTMLElement (or child of), or some of the spec will need updating as currently popover invoker is an HTMLElement (see https://html.spec.whatwg.org/#popover-invoker)

togglePopover isn't quite a simple addition because of the optional force boolean argument. We'd have to either take the compat hit of changing the argument type, or do the slightly unfortunate thing of allowing an argument of type boolean or dict where the dict has invoker and force as optional members.

[mfreed7]

Note #9144 (comment)

[lukewarlow]

Out of curiosity what's the API design looking like specifically for togglePopover given it already has the optional Boolean argument?

[mfreed7]

Out of curiosity what's the API design looking like specifically for togglePopover given it already has the optional Boolean argument?

I'm open to whatever makes the most sense. I implemented (in Chrome) the easiest/most compatible thing:

boolean togglePopover(optional (TogglePopoverOptions or boolean) options);

i.e. either the boolean or the options bag (which contains the boolean).

[mfreed7]

I put up a spec PR containing the proposal detailed above: #10728