[RFC] Expanded/Alternative Overlay API

[Westbrook]

Looking at issues like #1434 #1078 #1284 in association with some product usage feedback around the amount of work needed to apply tooltips to large number of buttons in a UI, I've begin experiment with an altered <sp-tooltip> API that would invert the relationship between "trigger" and "content" as currently offered by the <overlay-trigger> element. The current API requires the following:

<overlay-trigger>
    <sp-action-button slot="trigger">Trigger</sp-action-button>
    <sp-tooltip slot="hover-content">Content</sp-tooltip>
    <!-- Additional triggerable content
        <div slot="click-content"></div>
        <div slot="longpress-conent"></div>
    -->
</overlay-trigger>

The way this surfaces API for content to be triggered by hover, click, and longpress interactions make it particularly powerful when the trigger element acts as the "root" of an experience, e.g. this button is the entryway to modal content and unrelated other entryways. However, when the trigger element is part of a larger experience, e.g. <sp-*-group> elements that bring together groups of entryways, then the reliance of this mediator reliant DOM API can disrupt expected parent/child relationships in the provided Spectrum CSS DOM structures. This is particularly evident in #1434 where <sp-action-group> expects to have direct child access to style <sp-action-button> children regardless of the presence of overlaid content.

With this in mind, I'd like to start gathering use cases for (and edge cases to defend against) an API that would shift the management of (at least) a tooltip interaction from the mediated relationship to a "with" relationship by composing an <sp-tooltip> element into a trigger parent, something like:

<sp-action-button>
    Trigger
    <sp-tooltip auto>Content</sp-tooltip>
</sp-action-button>

I think the attribute API leaves a little to be desired, but I'm currently addressing it a way that does't require a breaking change, though there's reason to believe that would be the best path forward here.

This can roughly be experienced here: https://westbrook-tooltip-alt--spectrum-web-components.netlify.app/storybook/index.html?path=/story/tooltip--auto and is powered by https://github.com/adobe/spectrum-web-components/blob/westbrook/tooltip-alt/packages/tooltip/src/Tooltip.ts#L144

This style of overlay management would also change the location of projection management in a way that could obviate the need for a more advanced series of lifecycle callbacks as currently proposed in #1393 as content to the overlaid would already know that was to happen (as it would be managing that work itself) and be able to handle appropriate side effects as needed.

If it makes sense to prepare a more complete API proposal here, I'd like to take this on at a slightly higher level as we've been adding a number of features on top of our overlay system over the last year and revisiting that at a wholistic level could ensure we're preparing ourselves appropriately for the future. In specific, #1424 asks some questions around when content should leverage "modal" overlays that are important to answer. Related to that is a question as to whether we should be supporting overlays that scroll with the page. Were that feature to be removed from the API we might be in a place to remove PopperJS all together which at the system wide level accounts for ~10% of our bundle size: https://bundlephobia.com/result?p=@spectrum-web-components/bundle@0.20.1 Even if we weren't to take on the removal of this at the same time as a larger API refactor, the desire to remove it could be taken into account when considering API boundaries, etc.

Current research into #1434 will determine how large of a priority this sort of API change will be. I'm fairly certain we can "cover" for the styling issues currently listed therein, but whether we can do so 100% of the time, or in a reliable way across Spectrum CSS releases will be the test.

Are there other issues that you see an updated API in this area addressing that I've not taken into account?

Are there edge cases that you'd particularly like to see taking into account when outlining a more complete API here?

How much of an effect would a breaking change to <sp-tooltip> (and possibly other overlaid content over the course) have on your projects?

cc: @adixon-adobe @Aleodor-Tabarcea @isabellaminca @spdev3000 @dsadhanala

[Westbrook]

In a related way, this approach would open the door for something like <sp-dialog-wrapper> to also "wrap" the overlay interface so that it was projected at the end of the document when the open attribute was toggled.

<app-shell>
    <sp-dialog-wrapper auto ?open=${dialogState === 'open'}></sp-dialog-wrapper>
</app-shell>

[hunterloftis]

I'm in favor of providing this "inside-out" tooltip API. It's more natural for a user - analogous to embedding an icon in the contents of a button or other trigger.

I also think it's a great idea to holistically revisit the overlay system with the intent of simplifying & reducing.

[Westbrook]

This has shipped for sp-tooltip: https://opensource.adobe.com/spectrum-web-components/storybook/index.html?path=/story/tooltip--self-managed

Aside from #1885, I think it's in a good place for us to start thinking about other elements that might benefit from this pattern. Some initial targets might include:

• sp-popover
• sp-dialog
• sp-modal: not currently shipped, and is either inclusive of sp-popover and sp-dialog in which case we could leave their API untouched, or offer all of them? sp-popover and sp-dialog are more opinionated version of sp-modal?

For these non-tooltip contexts, there may also be room to discuss the cutover between sp-popover and sp-tray in these interactions.

[Westbrook]

Let's track this in #2086