Add declarative API for controlling overlays manually

[cuberoot]

Expected Behaviour

We should be able to control the opening and closing of overlays declaratively. This would be nice for working on #157

Actual Behaviour

Pull #422 adds a procedural API for opening and closing overlays, but doesn't have a declarative API.

Reproduce Scenario (including but not limited to)

Steps to Reproduce

Platform and Version

Sample Code that illustrates the problem

Logs taken while reproducing problem

[cuberoot]

@Westbrook In #422 you said this:

It's a lot of code, and a bunch of concepts that are still pretty new to me, so I'm gonna take another pass on the code later, but had the following thoughts to share...
I'm not sure how I feel about manually using the Overlay object myself in code a la packages/overlay/test/overlay.test.ts. The comfort line between declarative and imperative are always hard. To that end, I'd really like to see a declarative API in overlay-trigger that surfaced much the same functionality. I'm comfortable with that being addressed in a follow up PR, so if you want to hold off on that, can you create a ticket to track? I was looking into this sort of thing for #157 and it started to look like:

<overlay-trigger
    ?click-content-open
    ?hover-content-open
    @content-opened=${onContentOpened}
    @content-closed=${onContentClosed}
></overlay-trigger>

I'd be very happy to hear better API naming ideas, so tracking in an issue separately might make better sense.

In the above, I am concerned about mixing and matching declarative and event-based APIs. For example:

<overlay-trigger hover-content-open>
	<sp-button slot="trigger" variant="cta">Open Popover</sp-button>
	<sp-tooltip slot="hover-content">Tooltip content</sp-tooltip>
	<sp-popover
		dialog
		slot="click-content"
		direction="${this.placement}"
		tip
		open
	>
		Popover content
	</sp-popover>
</overlay-trigger>

In this case, the tooltip is declaratively open, but clicking the button should open the click content and close the hovers. What happens to the hover-content-open attribute?

I am thinking that we need a third content type of custom (happy to accept naming suggestions). The custom content would be shown or hidden only based on the declarative value of the attribute.

<overlay-trigger custom-content-open>
	<sp-button slot="trigger" variant="cta">Open Popover</sp-button>
	<sp-tooltip slot="custom-content">Tooltip content</sp-tooltip>
</overlay-trigger>

I already have a use case for the above in the Lightroom Importer.

[cuberoot]

I do like the idea of having an event callback when things are opened though.

[Westbrook]

In the case you've outlined, I'd expect this to perform a lot like https://developer.mozilla.org/en-US/docs/Web/HTML/Element/details

[Westbrook]

Revisiting this a year later 👀 ...

The contract that this overlay-trigger element clarifies (currently) that while an overlay-trigger can manage one piece of content for click, hover, and longpress interactions, it can never have more than one of those open at the same time. In this was the above proposal of attributes for click-content-open, hover-content-open, etc. is faulty. @cuberoot's suggestion of a separate and different custom-content-open attribute sort of addresses this but allowing declarative management of a single, special piece of content, but it doesn't really support the declarative use of this element and its already available content types. Do be able to do so, I'd like to suggest the use of an open attribute that is not a boolean, but takes string content of type 'click' | 'hover' | 'longpress', and reflects that attribute over the course of interacting with the overlay-trigger element.

In this way the following experiences will become possible in a declarative manner:

<overlay-trigger open="click">
    <sp-button slot="trigger">Button</sp-button>
    <sp-popover slot="click-content">Click content</sp-popover>
</overlay-trigger>

https://603d3b9364493300849ed28d--spectrum-web-components.netlify.app/storybook/index.html?path=/story/overlay--open-click-content

<overlay-trigger open="hover">
    <sp-button slot="trigger">Button</sp-button>
    <sp-tooltip slot="hover-content">Tooltip</sp-tooltip>
</overlay-trigger>

https://603d3b9364493300849ed28d--spectrum-web-components.netlify.app/storybook/index.html?path=/story/overlay--open-hover-content
https://603d3b9364493300849ed28d--spectrum-web-components.netlify.app/storybook/index.html?path=/story/tooltip--overlaid-top
https://603d3b9364493300849ed28d--spectrum-web-components.netlify.app/storybook/index.html?path=/story/tooltip--overlaid-right
https://603d3b9364493300849ed28d--spectrum-web-components.netlify.app/storybook/index.html?path=/story/tooltip--overlaid-bottom
https://603d3b9364493300849ed28d--spectrum-web-components.netlify.app/storybook/index.html?path=/story/tooltip--overlaid-left

Previously, the tooltip offering was made possible via the use of requestAnimationFrame in the Storybook story function, which was a good amount of hacky.

With the addition of a few tests to ensure this going forward, we could have this prepped for a PR sometime this week. Thoughts?