@spectrum-web-components/overlay 0.35.1-rc.43 → 0.37.0

package/README.md

@@ -68,7 +68,7 @@ By leveraging the `trigger` attribute to pass an ID reference to another element
             <sp-icon-rect-select slot="icon"></sp-icon-rect-select>
         </sp-action-button>
     </sp-action-group>
-    <sp-overlay trigger="trigger-1@hover">
+    <sp-overlay trigger="trigger-1@hover" type="hint">
         <sp-tooltip>Hover</sp-tooltip>
     </sp-overlay>
     <sp-overlay
@@ -92,7 +92,7 @@ By leveraging the `trigger` attribute to pass an ID reference to another element
             </sp-action-group>
         </sp-popover>
     </sp-overlay>
-    <sp-overlay trigger="trigger-2@hover">
+    <sp-overlay trigger="trigger-2@hover" type="hint">
         <sp-tooltip>Hover</sp-tooltip>
     </sp-overlay>
     <sp-overlay
@@ -116,7 +116,7 @@ By leveraging the `trigger` attribute to pass an ID reference to another element
             </sp-action-group>
         </sp-popover>
     </sp-overlay>
-    <sp-overlay trigger="trigger-3@hover">
+    <sp-overlay trigger="trigger-3@hover" type="hint">
         <sp-tooltip>Hover</sp-tooltip>
     </sp-overlay>
     <sp-overlay
@@ -159,19 +159,33 @@ By leveraging the `trigger` attribute to pass an ID reference to another element
 ></sp-overlay>
 ```
 
-# Events
+### API value interactions
 
-When fully open the `<sp-overlay>` element will dispatch the `sp-opened` event, and when fully closed the `sp-closed` event will be dispatched. "Fully" in this context means that all CSS transitions that have dispatched `transitionrun` events on the direct children of the `<sp-overlay>` element have successfully dispatched their `transitionend` event. Keep in mind the following:
+When a `triggerElement` is present, either through an ID reference established via the `trigger` attribute or by directly setting the `triggerElement` property, a chain on configuration begins:
+
+-   **if a `triggerInteraction` is available**, either through the `id@interaction` IDL on the `trigger` attribute or directly setting the `triggerInteraction` property, the `<sp-overlay>` will be bound to the resolved `triggerElement` via the `triggerInteraction` provided
+-   **if a `placement` is available** when the `<sp-overlay>` is `open` and displaying its contents, those contents will be positioned relative to the `triggerElement` as per that `placement`
+    -   **if an `offset` is also available** the `<sp-overlay>` will distance itself from the `triggerElement` in accordance with the value of the `offset`
+    -   **if you have a `placement` but not a `triggerElement`** the `<sp-overlay>` will not be positioned due to their being nothing for the `plaement` to reference when so doing
+-   **if no `placement` is available** the content will not be placed with the expectation that the content itself or the consuming application will handle placement of the overlaid content. This is commonly what will happen for `type="modal"` and `type="page"` overlays as they are likely meant to cover the entire screen, whether visibly (via an `<sp-underlay>`, an element that includes one, or similar) or figuratively (as when modal content is not delivered with a backdrop or scrim).
+
+### Events
+
+When fully open the `<sp-overlay>` element will dispatch the `sp-opened` event, and when fully closed the `sp-closed` event will be dispatched. "Fully" in this context means that all CSS transitions that have dispatched `transitionrun` events on the direct children of the `<sp-overlay>` element have successfully dispatched their `transitionend` or `transitioncancel` event. Keep in mind the following:
 
 -   `transition*` events bubble; this means that while transition events on light DOM content of those direct children will be heard, those events will not be taken into account
 -   `transition*` events are not composed; this means that transition events on shadow DOM content of the direct children will not propagate to a level in the DOM where they can be heard
 
-This means that in both cases, if the transition is meant to be a part of the opening or closing of the overlay in question you will need to redispatch the `transitionrun` and `transitionend` events from that transition from the closest direct child of the `<sp-overlay>`.
+This means that in both cases, if the transition is meant to be a part of the opening or closing of the overlay in question you will need to redispatch the `transitionrun`, `transitionend`, and `transitioncancel` events from that transition from the closest direct child of the `<sp-overlay>`.
 
 ## Styling
 
 `<sp-overlay>` element will use the `<dialog>` element or `popover` attribute to project your content onto the top-layer of the browser, without being moved in the DOM tree. That means that you can style your overlay content with whatever techniques you are already leveraging to style the content that doesn't get overlaid. This means standard CSS selectors, CSS Custom Properties, and CSS Parts applied in your parent context will always apply to your overlaid content.
 
+## Top Layer over Complex CSS
+
+There are some complex CSS values that have not yet been covered by the positioning API that the `<sp-overlay>` element leverages to associate overlaid content with their trigger elements. In specific, properties like `filter`, when applied to a trigger element within which lives the related content to be overlaid, are not currently supported by the relationship created herein. If support for this is something that you and the work you are addressing would require, we'd love to hear from you in [an issue](https://github.com/adobe/spectrum-web-components/issues). We'd be particularly interested in speaking with you if you were interested in contributing support/testing to ensure this capability for all consumers of the library.
+
 ## Fallback support
 
 While the [`<dialog>` element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/dialog) is widely supported by browsers, the [`popover` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/popover) is still quite new. When leveraged in browsers that do not yet support the `popover` attribute, there may be additional intervention required to ensure your content is delivered to your visitors as expected.
@@ -184,7 +198,11 @@ When an overlay is placed within a page with complex layering, the content there
 <div class="complex-layered-demo">
     <div class="complex-layered-holder">
         <sp-action-button id="complex-layered">Trigger</sp-action-button>
-        <sp-overlay trigger="complex-layered@hover" placement="bottom-start">
+        <sp-overlay
+            trigger="complex-layered@hover"
+            type="hint"
+            placement="bottom-start"
+        >
             <sp-tooltip>
                 I can be partially blocked when [popover] is not available
             </sp-tooltip>
@@ -219,7 +237,7 @@ Properly managed `z-index` values will support working around this issue while b
 ```html
 <div class="contained-demo">
     <sp-action-button id="contained">Trigger</sp-action-button>
-    <sp-overlay trigger="contained@hover" placement="bottom-start">
+    <sp-overlay trigger="contained@hover" type="hint" placement="bottom-start">
         <sp-tooltip>
             I can be blocked when [popover] is not available
         </sp-tooltip>
@@ -238,7 +256,11 @@ You could just _remove_ the `contain` rule. But, if you are not OK with simply r
 <div class="contained-demo">
     <sp-action-button id="contained-working">Trigger</sp-action-button>
 </div>
-<sp-overlay trigger="contained-working@hover" placement="bottom-start">
+<sp-overlay
+    trigger="contained-working@hover"
+    type="hint"
+    placement="bottom-start"
+>
     <sp-tooltip>I can be blocked when [popover] is not available</sp-tooltip>
 </sp-overlay>
 <style>
@@ -257,7 +279,11 @@ You could just _remove_ the `contain` rule. But, if you are not OK with simply r
 ```html
 <div class="clip-pathed-demo">
     <sp-action-button id="clip-pathed">Trigger</sp-action-button>
-    <sp-overlay trigger="clip-pathed@hover" placement="bottom-start">
+    <sp-overlay
+        trigger="clip-pathed@hover"
+        type="hint"
+        placement="bottom-start"
+    >
         <sp-tooltip>
             I can be blocked when [popover] is not available
         </sp-tooltip>
@@ -276,7 +302,11 @@ Here, again, working with your content needs (whether or not you want to leverag
 <div class="clip-pathed-demo">
     <sp-action-button id="clip-pathed-working">Trigger</sp-action-button>
 </div>
-<sp-overlay trigger="clip-pathed-working@hover" placement="bottom-start">
+<sp-overlay
+    trigger="clip-pathed-working@hover"
+    type="hint"
+    placement="bottom-start"
+>
     <sp-tooltip>I can be blocked when [popover] is not available</sp-tooltip>
 </sp-overlay>
 <style>