@spectrum-web-components/overlay 0.35.1-rc.41 → 0.36.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (156) hide show
  1. package/README.md +150 -237
  2. package/active-overlay.d.ts +6 -0
  3. package/active-overlay.dev.js +5 -0
  4. package/{sp-overlay.dev.js.map → active-overlay.dev.js.map} +3 -3
  5. package/active-overlay.js +2 -0
  6. package/{sp-overlay.js.map → active-overlay.js.map} +4 -4
  7. package/custom-elements.json +1215 -0
  8. package/package.json +22 -49
  9. package/src/ActiveOverlay.d.ts +84 -0
  10. package/src/ActiveOverlay.dev.js +517 -0
  11. package/src/ActiveOverlay.dev.js.map +7 -0
  12. package/src/ActiveOverlay.js +16 -0
  13. package/src/ActiveOverlay.js.map +7 -0
  14. package/src/OverlayTrigger.d.ts +41 -24
  15. package/src/OverlayTrigger.dev.js +295 -133
  16. package/src/OverlayTrigger.dev.js.map +3 -3
  17. package/src/OverlayTrigger.js +22 -52
  18. package/src/OverlayTrigger.js.map +3 -3
  19. package/src/VirtualTrigger.dev.js +1 -2
  20. package/src/VirtualTrigger.dev.js.map +2 -2
  21. package/src/VirtualTrigger.js +1 -1
  22. package/src/VirtualTrigger.js.map +2 -2
  23. package/src/active-overlay.css.dev.js +13 -0
  24. package/src/active-overlay.css.dev.js.map +7 -0
  25. package/src/active-overlay.css.js +10 -0
  26. package/src/active-overlay.css.js.map +7 -0
  27. package/src/index.d.ts +3 -2
  28. package/src/index.dev.js +3 -2
  29. package/src/index.dev.js.map +2 -2
  30. package/src/index.js +1 -1
  31. package/src/index.js.map +2 -2
  32. package/src/loader.d.ts +2 -1
  33. package/src/loader.dev.js +19 -2
  34. package/src/loader.dev.js.map +2 -2
  35. package/src/loader.js +1 -1
  36. package/src/loader.js.map +3 -3
  37. package/src/overlay-stack.d.ts +50 -0
  38. package/src/overlay-stack.dev.js +515 -0
  39. package/src/overlay-stack.dev.js.map +7 -0
  40. package/src/overlay-stack.js +34 -0
  41. package/src/overlay-stack.js.map +7 -0
  42. package/src/overlay-timer.dev.js.map +2 -2
  43. package/src/overlay-timer.js.map +2 -2
  44. package/src/overlay-trigger.css.dev.js +1 -1
  45. package/src/overlay-trigger.css.dev.js.map +1 -1
  46. package/src/overlay-trigger.css.js +1 -1
  47. package/src/overlay-trigger.css.js.map +1 -1
  48. package/src/overlay-types.d.ts +31 -25
  49. package/src/overlay-types.dev.js +0 -1
  50. package/src/overlay-types.dev.js.map +3 -3
  51. package/src/overlay-types.js +1 -1
  52. package/src/overlay-types.js.map +3 -3
  53. package/src/overlay-utils.d.ts +3 -0
  54. package/src/overlay-utils.dev.js +31 -0
  55. package/src/overlay-utils.dev.js.map +7 -0
  56. package/src/overlay-utils.js +2 -0
  57. package/src/overlay-utils.js.map +7 -0
  58. package/src/overlay.d.ts +59 -0
  59. package/src/overlay.dev.js +127 -0
  60. package/src/overlay.dev.js.map +7 -0
  61. package/src/overlay.js +2 -0
  62. package/src/overlay.js.map +7 -0
  63. package/stories/overlay-story-components.js +8 -9
  64. package/stories/overlay-story-components.js.map +2 -2
  65. package/stories/overlay.stories.js +697 -825
  66. package/stories/overlay.stories.js.map +2 -2
  67. package/sync/overlay-trigger.d.ts +0 -4
  68. package/sync/overlay-trigger.dev.js +4 -1
  69. package/sync/overlay-trigger.dev.js.map +2 -2
  70. package/sync/overlay-trigger.js +1 -1
  71. package/sync/overlay-trigger.js.map +3 -3
  72. package/test/benchmark/basic-test.js +1 -1
  73. package/test/benchmark/basic-test.js.map +1 -1
  74. package/test/index.js +377 -408
  75. package/test/index.js.map +3 -3
  76. package/test/overlay-lifecycle.test.js +106 -34
  77. package/test/overlay-lifecycle.test.js.map +2 -2
  78. package/test/overlay-trigger-click.test.js +5 -11
  79. package/test/overlay-trigger-click.test.js.map +2 -2
  80. package/test/overlay-trigger-extended.test.js +36 -42
  81. package/test/overlay-trigger-extended.test.js.map +2 -2
  82. package/test/overlay-trigger-hover-click.test.js +24 -27
  83. package/test/overlay-trigger-hover-click.test.js.map +2 -2
  84. package/test/overlay-trigger-hover.test.js +35 -41
  85. package/test/overlay-trigger-hover.test.js.map +2 -2
  86. package/test/overlay-trigger-longpress.test.js +81 -206
  87. package/test/overlay-trigger-longpress.test.js.map +2 -2
  88. package/test/overlay-trigger-sync.test.js +1 -1
  89. package/test/overlay-trigger-sync.test.js.map +2 -2
  90. package/test/overlay-trigger.test.js +1 -1
  91. package/test/overlay-trigger.test.js.map +2 -2
  92. package/test/overlay-update.test.js +4 -4
  93. package/test/overlay-update.test.js.map +2 -2
  94. package/test/overlay.test.js +268 -386
  95. package/test/overlay.test.js.map +3 -3
  96. package/sp-overlay.d.ts +0 -6
  97. package/sp-overlay.dev.js +0 -5
  98. package/sp-overlay.js +0 -2
  99. package/src/AbstractOverlay.d.ts +0 -56
  100. package/src/AbstractOverlay.dev.js +0 -202
  101. package/src/AbstractOverlay.dev.js.map +0 -7
  102. package/src/AbstractOverlay.js +0 -2
  103. package/src/AbstractOverlay.js.map +0 -7
  104. package/src/Overlay.d.ts +0 -147
  105. package/src/Overlay.dev.js +0 -777
  106. package/src/Overlay.dev.js.map +0 -7
  107. package/src/Overlay.js +0 -33
  108. package/src/Overlay.js.map +0 -7
  109. package/src/OverlayDialog.d.ts +0 -4
  110. package/src/OverlayDialog.dev.js +0 -135
  111. package/src/OverlayDialog.dev.js.map +0 -7
  112. package/src/OverlayDialog.js +0 -2
  113. package/src/OverlayDialog.js.map +0 -7
  114. package/src/OverlayNoPopover.d.ts +0 -4
  115. package/src/OverlayNoPopover.dev.js +0 -110
  116. package/src/OverlayNoPopover.dev.js.map +0 -7
  117. package/src/OverlayNoPopover.js +0 -2
  118. package/src/OverlayNoPopover.js.map +0 -7
  119. package/src/OverlayPopover.d.ts +0 -4
  120. package/src/OverlayPopover.dev.js +0 -169
  121. package/src/OverlayPopover.dev.js.map +0 -7
  122. package/src/OverlayPopover.js +0 -2
  123. package/src/OverlayPopover.js.map +0 -7
  124. package/src/OverlayStack.d.ts +0 -43
  125. package/src/OverlayStack.dev.js +0 -150
  126. package/src/OverlayStack.dev.js.map +0 -7
  127. package/src/OverlayStack.js +0 -2
  128. package/src/OverlayStack.js.map +0 -7
  129. package/src/PlacementController.d.ts +0 -38
  130. package/src/PlacementController.dev.js +0 -199
  131. package/src/PlacementController.dev.js.map +0 -7
  132. package/src/PlacementController.js +0 -2
  133. package/src/PlacementController.js.map +0 -7
  134. package/src/fullSizePlugin.d.ts +0 -12
  135. package/src/fullSizePlugin.dev.js +0 -39
  136. package/src/fullSizePlugin.dev.js.map +0 -7
  137. package/src/fullSizePlugin.js +0 -2
  138. package/src/fullSizePlugin.js.map +0 -7
  139. package/src/overlay.css.dev.js +0 -9
  140. package/src/overlay.css.dev.js.map +0 -7
  141. package/src/overlay.css.js +0 -6
  142. package/src/overlay.css.js.map +0 -7
  143. package/src/topLayerOverTransforms.d.ts +0 -2
  144. package/src/topLayerOverTransforms.dev.js +0 -90
  145. package/src/topLayerOverTransforms.dev.js.map +0 -7
  146. package/src/topLayerOverTransforms.js +0 -2
  147. package/src/topLayerOverTransforms.js.map +0 -7
  148. package/stories/overlay-element.stories.js +0 -366
  149. package/stories/overlay-element.stories.js.map +0 -7
  150. package/test/overlay-element.test-vrt.js +0 -5
  151. package/test/overlay-element.test-vrt.js.map +0 -7
  152. package/test/overlay-element.test.js +0 -681
  153. package/test/overlay-element.test.js.map +0 -7
  154. package/test/overlay-v1.test.js +0 -651
  155. package/test/overlay-v1.test.js.map +0 -7
  156. /package/src/{overlay.css.d.ts → active-overlay.css.d.ts} +0 -0
package/README.md CHANGED
@@ -1,6 +1,6 @@
1
1
  ## Description
2
2
 
3
- An `<sp-overlay>` element is used to decorate content that you would like to present to your visitors as "overlaid" on the rest of the application. This includes dialogs (modal and not), pickers, tooltips, context menus, et al.
3
+ Overlays in Spectrum Web Components are created via the `Overlay` class system, which prepares an "overlay stack" that can manage the deployment of one or more overlays onto a page. Whether it's needed for transient content like a tooltip, for extended interactions like selecting a value from a picker, or for blocking content like a modal, the imperative APIs outlined below or the declarative APIs delivered by `<overlay-trigger>` should cover your overlay delivery needs.
4
4
 
5
5
  ### Usage
6
6
 
@@ -11,277 +11,190 @@ An `<sp-overlay>` element is used to decorate content that you would like to pre
11
11
  yarn add @spectrum-web-components/overlay
12
12
  ```
13
13
 
14
- Import the side effectful registration of `<sp-overlay>` as follows:
14
+ Import the `Overlay` class to leverage its capabilities within your application or custom element:
15
15
 
16
- ```
17
- import '@spectrum-web-components/overlay/sp-overlay.js';
16
+ ```js
17
+ import { Overlay } from '@spectrum-web-components/overlay';
18
18
  ```
19
19
 
20
- When looking to leverage the `Overlay` base class as a type and/or for extension purposes, do so via:
20
+ Primarily, this class gives you access to the `open` method that will allow you to open an overlay:
21
21
 
22
- ```
23
- import {
24
- Overlay
25
- } from '@spectrum-web-components/overlay';
22
+ ```js
23
+ Overlay.open(
24
+ (owner: HTMLElement), // the element to open the overlay in reference to, "trigger"
25
+ (interaction: TriggerInteractions), // the type of interaction type that opened the overlay
26
+ (overlayElement: HTMLElement), // the element that will be projected into the overlay, "content"
27
+ (options: OverlayOptions) // options to customize the overlay
28
+ );
26
29
  ```
27
30
 
28
- ## Example
31
+ `Overlay.open()` is an asynchronous method that returns a function for closing the overlay, so it is common to leverage this functionality like the following:
32
+
33
+ ```js
34
+ (async () => {
35
+ const trigger = document.querySelector('#trigger');
36
+ const interaction = 'click';
37
+ const content = document.querySelector('#content');
38
+ const options = {
39
+ offset: 0,
40
+ placement: 'bottom',
41
+ };
42
+ const closeOverlay = await Overlay.open(
43
+ trigger,
44
+ interaction,
45
+ content,
46
+ options
47
+ );
48
+ })();
49
+ ```
29
50
 
30
- By leveraging the `trigger` attribute to pass an ID reference to another element with in the same DOM tree, your overlay will be positioned in relation to this element. When the ID reference is followed by an `@` symbol and interaction type, like `click`, `hover`, or `longpress`, the overlay will bind itself to the referenced element via the DOM events associated with that interaction. For example, the `<sp-button>` below has an id of `trigger`, and the `<sp-overlay>` is provided the `trigger` attribute with the value `trigger@click`. This creates an association between the overlay and the `<sp-button>` that opens the overlay when the button is clicked.
51
+ ## Types
31
52
 
32
- ```html
33
- <sp-button id="trigger">Overlay Trigger</sp-button>
34
- <sp-overlay trigger="trigger@click">
35
- <sp-popover>
36
- <sp-dialog>
37
- <h2 slot="heading">Clicking opens this popover...</h2>
38
- <p>But, it really could be anything. Really.</p>
39
- </sp-dialog>
40
- </sp-popover>
41
- </sp-overlay>
42
- ```
53
+ ### TriggerInteractions
43
54
 
44
- ### Action bar
55
+ This outlines the user experience that is to be delivered through the process of opening and closing an overlay.
45
56
 
46
- ```html
47
- <style>
48
- .overlay-demo-popover sp-action-group {
49
- padding: var(--spectrum-actiongroup-vertical-spacing-regular);
50
- }
51
- #overlay-demo {
52
- position: static;
53
- }
54
- #overlay-demo:not(:defined),
55
- #overlay-demo *:not(:defined) {
56
- display: none;
57
- }
58
- </style>
59
- <sp-popover id="overlay-demo" class="overlay-demo-popover" open>
60
- <sp-action-group vertical quiet emphasized selects="single">
61
- <sp-action-button id="trigger-1" hold-affordance>
62
- <sp-icon-anchor-select slot="icon"></sp-icon-anchor-select>
63
- </sp-action-button>
64
- <sp-action-button id="trigger-2" hold-affordance>
65
- <sp-icon-polygon-select slot="icon"></sp-icon-polygon-select>
66
- </sp-action-button>
67
- <sp-action-button id="trigger-3" hold-affordance>
68
- <sp-icon-rect-select slot="icon"></sp-icon-rect-select>
69
- </sp-action-button>
70
- </sp-action-group>
71
- <sp-overlay trigger="trigger-1@hover">
72
- <sp-tooltip>Hover</sp-tooltip>
73
- </sp-overlay>
74
- <sp-overlay
75
- trigger="trigger-1@longpress"
76
- type="auto"
77
- placement="right-start"
78
- >
79
- <sp-popover class="overlay-demo-popover" tip>
80
- <sp-action-group vertical quiet>
81
- <sp-action-button>
82
- <sp-icon-anchor-select slot="icon"></sp-icon-anchor-select>
83
- </sp-action-button>
84
- <sp-action-button>
85
- <sp-icon-polygon-select
86
- slot="icon"
87
- ></sp-icon-polygon-select>
88
- </sp-action-button>
89
- <sp-action-button>
90
- <sp-icon-rect-select slot="icon"></sp-icon-rect-select>
91
- </sp-action-button>
92
- </sp-action-group>
93
- </sp-popover>
94
- </sp-overlay>
95
- <sp-overlay trigger="trigger-2@hover">
96
- <sp-tooltip>Hover</sp-tooltip>
97
- </sp-overlay>
98
- <sp-overlay
99
- trigger="trigger-2@longpress"
100
- type="auto"
101
- placement="right-start"
102
- >
103
- <sp-popover class="overlay-demo-popover" tip>
104
- <sp-action-group vertical quiet>
105
- <sp-action-button>
106
- <sp-icon-anchor-select slot="icon"></sp-icon-anchor-select>
107
- </sp-action-button>
108
- <sp-action-button>
109
- <sp-icon-polygon-select
110
- slot="icon"
111
- ></sp-icon-polygon-select>
112
- </sp-action-button>
113
- <sp-action-button>
114
- <sp-icon-rect-select slot="icon"></sp-icon-rect-select>
115
- </sp-action-button>
116
- </sp-action-group>
117
- </sp-popover>
118
- </sp-overlay>
119
- <sp-overlay trigger="trigger-3@hover">
120
- <sp-tooltip>Hover</sp-tooltip>
121
- </sp-overlay>
122
- <sp-overlay
123
- trigger="trigger-3@longpress"
124
- type="auto"
125
- placement="right-start"
126
- >
127
- <sp-popover class="overlay-demo-popover" tip>
128
- <sp-action-group vertical quiet>
129
- <sp-action-button>
130
- <sp-icon-anchor-select slot="icon"></sp-icon-anchor-select>
131
- </sp-action-button>
132
- <sp-action-button>
133
- <sp-icon-polygon-select
134
- slot="icon"
135
- ></sp-icon-polygon-select>
136
- </sp-action-button>
137
- <sp-action-button>
138
- <sp-icon-rect-select slot="icon"></sp-icon-rect-select>
139
- </sp-action-button>
140
- </sp-action-group>
141
- </sp-popover>
142
- </sp-overlay>
143
- </sp-popover>
144
57
  ```
145
-
146
- ## API
147
-
148
- ```ts
149
- <sp-overlay
150
- ?open=${boolean}
151
- ?delayed=${boolean}
152
- offset=${Number | [Number, Number]}
153
- placement=${Placement}
154
- receives-focus=${'true' | 'false' | 'auto' (default)
155
- trigger=${string | ${string}@${string}}
156
- .triggerElement=${HTMLElement}
157
- .triggerInteraction=${'click' | 'longpress' | 'hover'}
158
- type=${'auto' | 'hint' | 'manual' | 'modal' | 'page'}
159
- ></sp-overlay>
58
+ type TriggerInteractions =
59
+ | 'click'
60
+ | 'custom',
61
+ | 'hover'
62
+ | 'inline'
63
+ | 'modal'
64
+ | 'replace';
160
65
  ```
161
66
 
162
- # Events
67
+ `click` will open an overlay that will close immediately on the next click that is not on an element within the overlay.
163
68
 
164
- 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:
69
+ `custom` is less opinionated and allows for some customization of the process from the outside.
165
70
 
166
- - `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
167
- - `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
71
+ `hover` will close the overlay as soon as the pointer leaves the trigger to which the overlay is connected.
168
72
 
169
- 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>`.
73
+ `inline` places the overlay after the trigger but before the next element in the logical tab order. This means the `shift + tab` keyboard stroke will return to the trigger.
170
74
 
171
- ## Styling
75
+ `modal` manages the overlay like a modal and will trap the tab order within its contents only.
172
76
 
173
- `<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.
77
+ `replace` will position the overlay directly in the position of the trigger in the logical tab order. This means the `shift + tab` keyboard stroke will return the focusable element immediately prior to the trigger.
174
78
 
175
- ## Fallback support
79
+ ### OverlayOptions
176
80
 
177
- 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.
81
+ ```
82
+ type OverlayOptions = {
83
+ delayed?: boolean;
84
+ placement?: Placement;
85
+ offset?: number;
86
+ receivesFocus?: 'auto';
87
+ notImmediatelyClosable?: boolean;
88
+ }
89
+ ```
178
90
 
179
- ### Complex layered
91
+ `delayed` allows for the overlay to open the overlay with warmup/cooldown behaviors as described at https://spectrum.adobe.com/page/tooltip/#Immediate-or-delayed-appearance
180
92
 
181
- When an overlay is placed within a page with complex layering, the content therein can fall behind other content in the `z-index` stack. The following example is somewhat contrived but, imagine a toolbar next to a properties panel. If the toolbar has a lower `z-index` than the properties panel, any overlaid content (tooltips, etc.) within that toolbar will display underneath any content in the properties panel with which it may share pixels.
93
+ `placement` outlines where the overlay system should attempt to position the overlay in relation to the trigger. When the layout of the page and/or current scroll positioning prevents the successful placement of the content in this way, the `placement` will be automatically applied as the value best suited for those conditions. Placements available include: `"auto" | "auto-start" | "auto-end" | "top" | "bottom" | "right" | "left" | "top-start" | "top-end" | "bottom-start" | "bottom-end" | "right-start" | "right-end" | "left-start" | "left-end" | "none"`.
182
94
 
183
- ```html
184
- <div class="complex-layered-demo">
185
- <div class="complex-layered-holder">
186
- <sp-action-button id="complex-layered">Trigger</sp-action-button>
187
- <sp-overlay trigger="complex-layered@hover" placement="bottom-start">
188
- <sp-tooltip>
189
- I can be partially blocked when [popover] is not available
190
- </sp-tooltip>
191
- </sp-overlay>
192
- </div>
193
- <div class="complex-layered-blocker"></div>
194
- </div>
195
- <style>
196
- .complex-layered-demo {
197
- position: relative;
198
- }
199
- .complex-layered-holder {
200
- z-index: 1;
201
- position: relative;
202
- }
203
- .complex-layered-blocker {
204
- position: relative;
205
- z-index: 10;
206
- background: white;
207
- width: 100%;
208
- height: 40px;
209
- }
210
- </style>
211
- ```
95
+ `offset` defines the distance of the overlay content from the trigger, measured in pixels.
212
96
 
213
- Properly managed `z-index` values will support working around this issue while browsers work to adopt the `popover` attribute. In this demo, you can achieve the same output by sharing one `z-index` between the various pieces of content, removing `z-index` values altogether, or raising the `.complex-layered-holder` element to a higher `z-index` than the `.complex-layered-blocker` element.
97
+ `receivesFocus` tells the overlay stack to throw focus into the overlay after it has opened.
214
98
 
215
- ### Contained
99
+ `notImmediatelyClosable` prevents immediate clicks from closing the overlay. If you find that a trigger event is immediately overridden with a subsequent click (for instance, a `focus` trigger that should be closed on `click`), set `notImmediatelyClosable: true` to disregard clicks that coincide with the opening trigger.
216
100
 
217
- [CSS Containment](https://developer.mozilla.org/en-US/docs/Web/CSS/contain) gives a developer direct control over how the internals of one element affect the paint and layout of the internals of other elements on the same page. While leveraging some of its values can offer performance gains, they can interrupt the delivery of your overlaid content.
101
+ ### Events
218
102
 
219
- ```html
220
- <div class="contained-demo">
221
- <sp-action-button id="contained">Trigger</sp-action-button>
222
- <sp-overlay trigger="contained@hover" placement="bottom-start">
223
- <sp-tooltip>
224
- I can be blocked when [popover] is not available
225
- </sp-tooltip>
226
- </sp-overlay>
227
- </div>
228
- <style>
229
- .contained-demo {
230
- contain: content;
231
- }
232
- </style>
233
- ```
103
+ The work to both open and close an overlay is asynchronous. This asynchrony is surfaced into the application via DOM events dispatched from the `trigger` element of your overlay. An `sp-opened` event will be dispatched once the overlay has finished opening, and an `sp-closed` event will be dispatched once the overlay has finished closing. In both cases, the dispatched event will include a `detail` property with an `interaction: TriggerInteractions` key to support associating the event/overlay with its originating `interaction`.
234
104
 
235
- You could just _remove_ the `contain` rule. But, if you are not OK with simply removing the `contain` value, you still have options. If you would like to continue to leverage `contain`, you can place your "contained" content separately from your overlaid content, like so:
105
+ ## Example
236
106
 
237
107
  ```html
238
- <div class="contained-demo">
239
- <sp-action-button id="contained-working">Trigger</sp-action-button>
240
- </div>
241
- <sp-overlay trigger="contained-working@hover" placement="bottom-start">
242
- <sp-tooltip>I can be blocked when [popover] is not available</sp-tooltip>
243
- </sp-overlay>
244
- <style>
245
- .contained-demo {
246
- contain: content;
247
- }
248
- </style>
108
+ <sp-button
109
+ onclick="
110
+ const trigger = this;
111
+ const interaction = 'click';
112
+ const content = this.nextElementSibling;
113
+ if (!content) return;
114
+ const options = {
115
+ offset: 0,
116
+ placement: 'right',
117
+ };
118
+ content.open = true;
119
+ const closeOverlayPromise = Overlay.open(
120
+ trigger,
121
+ interaction,
122
+ content,
123
+ options
124
+ );
125
+ setTimeout(function () {
126
+ closeOverlayPromise.then(function(close) {
127
+ close();
128
+ content.open = false;
129
+ });
130
+ }, 5000);
131
+ "
132
+ >
133
+ Click me for a 5 second overlay!
134
+ </sp-button>
135
+ <sp-popover>
136
+ <sp-dialog size="medium">
137
+ <h2 slot="heading">Demo</h2>
138
+ Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod
139
+ tempor incididunt ut labore et dolore magna aliqua. Auctor augue mauris
140
+ augue neque gravida. Libero volutpat sed ornare arcu. Quisque egestas
141
+ diam in arcu cursus euismod quis viverra. Posuere ac ut consequat semper
142
+ viverra nam libero justo laoreet. Enim ut tellus elementum sagittis
143
+ vitae et leo duis ut. Neque laoreet suspendisse interdum consectetur
144
+ libero id faucibus nisl. Diam volutpat commodo sed egestas egestas.
145
+ Dolor magna eget est lorem ipsum dolor. Vitae suscipit tellus mauris a
146
+ diam maecenas sed. Turpis in eu mi bibendum neque egestas congue.
147
+ Rhoncus est pellentesque elit ullamcorper dignissim cras lobortis.
148
+ </sp-dialog>
149
+ </sp-popover>
249
150
  ```
250
151
 
251
- `<sp-overlay>` accepts an ID reference via the `trigger` attribute to relate it to interactions and positioning in the DOM. To fulfill this reference the two elements need to be in the same DOM tree. However, `<sp-overlay>` alternatively accepts a `triggerElement` _property_ that opens even more flexibility in addressing this situation.
152
+ ## Styling
252
153
 
253
- ### Clip pathed
154
+ When an overlay is opened from within a styled DOM scope as created by an `<sp-theme>` element, this scope will be resolved and recreated with in the `<active-overlay>` element that is created to host the overlaid content directly in the `<body>`. By default, the generated `<sp-theme>` element will be supplied with settings of the scope from which the overlay is triggered, including any "app" centric CSS Custom Properties that might be applied via `Theme.registerThemeFragment('app', 'app', themeFragment)` therein. In the case that you have set CSS Custom Properties for the scope created by an `<sp-theme>` element via other methods, you can specify that those values should also be applied to overlay content using the `theme` part on the `<active-overlay>` element via the `active-overlay::part(theme) { /* styles */ }` selector.
254
155
 
255
- `clip-path` can also restrict how content in an element is surfaced at paint time. When overlaid content should display outside of the `clip-path`, without the `popover` attribute, that content could be _clipped_.
156
+ ## Advanced Usage
256
157
 
257
- ```html
258
- <div class="clip-pathed-demo">
259
- <sp-action-button id="clip-pathed">Trigger</sp-action-button>
260
- <sp-overlay trigger="clip-pathed@hover" placement="bottom-start">
261
- <sp-tooltip>
262
- I can be blocked when [popover] is not available
263
- </sp-tooltip>
264
- </sp-overlay>
265
- </div>
266
- <style>
267
- .clip-pathed-demo {
268
- clip-path: inset(0 0);
269
- }
270
- </style>
271
- ```
158
+ When working with the DOM-based APIs of custom elements, it is sometimes preferred to project content into an overlay from a different shadow root (eg projecting a single-slotted element into the overlay). To ensure that the content can be marshalled through any number of `<slot>` elements which are addressed into subsequent `<slot>` elements, be sure to use the `flatten: true` option when querying `slot.asignedNodes()`:
272
159
 
273
- Here, again, working with your content needs (whether or not you want to leverage `clip-path`) or DOM structure (not colocating clipped and non-clipped content) will allow you to avoid this issue:
160
+ ```js
161
+ const trigger = shadowRoot.querySelector('#trigger');
162
+ const slot = shadowRoot.querySelector('slot');
163
+ const interaction = 'click';
164
+ const content = slot
165
+ .assignedNodes({ flatten: true })
166
+ .find((node) => node instanceof HTMLElement);
167
+ const options = {
168
+ offset: 0,
169
+ placement: 'bottom',
170
+ };
171
+ const closeOverlay = await Overlay.open(trigger, interaction, content, options);
172
+ ```
274
173
 
275
- ```html
276
- <div class="clip-pathed-demo">
277
- <sp-action-button id="clip-pathed-working">Trigger</sp-action-button>
278
- </div>
279
- <sp-overlay trigger="clip-pathed-working@hover" placement="bottom-start">
280
- <sp-tooltip>I can be blocked when [popover] is not available</sp-tooltip>
281
- </sp-overlay>
282
- <style>
283
- .clip-pathed-demo {
284
- clip-path: inset(0 0);
285
- }
286
- </style>
174
+ Other times, you may want to compose content from multiple shadow roots into a single overlay. This is a pattern seen in the `<sp-dropdown>` element: its `<sp-menu>` light DOM child is wrapped by its `<sp-popover>` shadow DOM child before being projected into an overlay. What follows is a more trivial example, where content in the light DOM of an element is injected into an element in the shadow DOM of the same element and then projected into an overlay. Notice the added work here of setting a comment node into the light DOM as a placeholder for the "stolen" content, and then swapping that content back into the light DOM when the overlay is closed.
175
+
176
+ ```js
177
+ const trigger = this.shadowRoot.querySelector('#trigger');
178
+ const outterContent = this.shadowRoot.querySelector('#outter-content');
179
+ const innerContent = this.querySelector('#inner-content');
180
+ const innerContentParent =
181
+ innerContent.parentElement || innerContent.getRootNode();
182
+ const placeholder = document.createComment('placeholder for inner content');
183
+ innerContentParent.replaceChild(placeholder, innerContent);
184
+ outterContent.append(innerContent);
185
+ const interaction = 'click';
186
+ const options = {
187
+ offset: 0,
188
+ placement: 'bottom',
189
+ };
190
+ const closeOverlayPromise = Overlay.open(
191
+ trigger,
192
+ interaction,
193
+ outterContent,
194
+ options
195
+ );
196
+ const closeOverlay = function () {
197
+ closeOverlayPromise.then((close) => close());
198
+ innerContentParent.replaceChild(innerContent, placeholder);
199
+ };
287
200
  ```
@@ -0,0 +1,6 @@
1
+ import { ActiveOverlay } from './src/ActiveOverlay.js';
2
+ declare global {
3
+ interface HTMLElementTagNameMap {
4
+ 'active-overlay': ActiveOverlay;
5
+ }
6
+ }
@@ -0,0 +1,5 @@
1
+ "use strict";
2
+ import { defineElement } from "@spectrum-web-components/base/src/define-element.js";
3
+ import { ActiveOverlay } from "./src/ActiveOverlay.dev.js";
4
+ defineElement("active-overlay", ActiveOverlay);
5
+ //# sourceMappingURL=active-overlay.dev.js.map
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "version": 3,
3
- "sources": ["sp-overlay.ts"],
4
- "sourcesContent": ["/*\nCopyright 2023 Adobe. All rights reserved.\nThis file is licensed to you under the Apache License, Version 2.0 (the \"License\");\nyou may not use this file except in compliance with the License. You may obtain a copy\nof the License at http://www.apache.org/licenses/LICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software distributed under\nthe License is distributed on an \"AS IS\" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS\nOF ANY KIND, either express or implied. See the License for the specific language\ngoverning permissions and limitations under the License.\n*/\nimport { defineElement } from '@spectrum-web-components/base/src/define-element.js';\nimport { Overlay } from './src/Overlay.dev.js'\n\ndefineElement('sp-overlay', Overlay);\n\ndeclare global {\n interface HTMLElementTagNameMap {\n 'sp-overlay': Overlay;\n }\n}\n"],
5
- "mappings": ";AAWA,SAAS,qBAAqB;AAC9B,SAAS,eAAe;AAExB,cAAc,cAAc,OAAO;",
3
+ "sources": ["active-overlay.ts"],
4
+ "sourcesContent": ["/*\nCopyright 2020 Adobe. All rights reserved.\nThis file is licensed to you under the Apache License, Version 2.0 (the \"License\");\nyou may not use this file except in compliance with the License. You may obtain a copy\nof the License at http://www.apache.org/licenses/LICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software distributed under\nthe License is distributed on an \"AS IS\" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS\nOF ANY KIND, either express or implied. See the License for the specific language\ngoverning permissions and limitations under the License.\n*/\nimport { defineElement } from '@spectrum-web-components/base/src/define-element.js';\nimport { ActiveOverlay } from './src/ActiveOverlay.dev.js'\n\ndefineElement('active-overlay', ActiveOverlay);\n\ndeclare global {\n interface HTMLElementTagNameMap {\n 'active-overlay': ActiveOverlay;\n }\n}\n"],
5
+ "mappings": ";AAWA,SAAS,qBAAqB;AAC9B,SAAS,qBAAqB;AAE9B,cAAc,kBAAkB,aAAa;",
6
6
  "names": []
7
7
  }
@@ -0,0 +1,2 @@
1
+ "use strict";import{defineElement as e}from"@spectrum-web-components/base/src/define-element.js";import{ActiveOverlay as a}from"./src/ActiveOverlay.js";e("active-overlay",a);
2
+ //# sourceMappingURL=active-overlay.js.map
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "version": 3,
3
- "sources": ["sp-overlay.ts"],
4
- "sourcesContent": ["/*\nCopyright 2023 Adobe. All rights reserved.\nThis file is licensed to you under the Apache License, Version 2.0 (the \"License\");\nyou may not use this file except in compliance with the License. You may obtain a copy\nof the License at http://www.apache.org/licenses/LICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software distributed under\nthe License is distributed on an \"AS IS\" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS\nOF ANY KIND, either express or implied. See the License for the specific language\ngoverning permissions and limitations under the License.\n*/\nimport { defineElement } from '@spectrum-web-components/base/src/define-element.js';\nimport { Overlay } from './src/Overlay.js';\n\ndefineElement('sp-overlay', Overlay);\n\ndeclare global {\n interface HTMLElementTagNameMap {\n 'sp-overlay': Overlay;\n }\n}\n"],
5
- "mappings": "aAWA,OAAS,iBAAAA,MAAqB,sDAC9B,OAAS,WAAAC,MAAe,mBAExBD,EAAc,aAAcC,CAAO",
6
- "names": ["defineElement", "Overlay"]
3
+ "sources": ["active-overlay.ts"],
4
+ "sourcesContent": ["/*\nCopyright 2020 Adobe. All rights reserved.\nThis file is licensed to you under the Apache License, Version 2.0 (the \"License\");\nyou may not use this file except in compliance with the License. You may obtain a copy\nof the License at http://www.apache.org/licenses/LICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software distributed under\nthe License is distributed on an \"AS IS\" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS\nOF ANY KIND, either express or implied. See the License for the specific language\ngoverning permissions and limitations under the License.\n*/\nimport { defineElement } from '@spectrum-web-components/base/src/define-element.js';\nimport { ActiveOverlay } from './src/ActiveOverlay.js';\n\ndefineElement('active-overlay', ActiveOverlay);\n\ndeclare global {\n interface HTMLElementTagNameMap {\n 'active-overlay': ActiveOverlay;\n }\n}\n"],
5
+ "mappings": "aAWA,OAAS,iBAAAA,MAAqB,sDAC9B,OAAS,iBAAAC,MAAqB,yBAE9BD,EAAc,iBAAkBC,CAAa",
6
+ "names": ["defineElement", "ActiveOverlay"]
7
7
  }