@spectrum-web-components/overlay 0.0.0-20241209155954

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 (148) hide show
  1. package/README.md +465 -0
  2. package/local.d.ts +56 -0
  3. package/overlay-trigger.d.ts +6 -0
  4. package/overlay-trigger.dev.js +5 -0
  5. package/overlay-trigger.dev.js.map +7 -0
  6. package/overlay-trigger.js +2 -0
  7. package/overlay-trigger.js.map +7 -0
  8. package/package.json +179 -0
  9. package/sp-overlay.d.ts +6 -0
  10. package/sp-overlay.dev.js +5 -0
  11. package/sp-overlay.dev.js.map +7 -0
  12. package/sp-overlay.js +2 -0
  13. package/sp-overlay.js.map +7 -0
  14. package/src/AbstractOverlay.d.ts +72 -0
  15. package/src/AbstractOverlay.dev.js +234 -0
  16. package/src/AbstractOverlay.dev.js.map +7 -0
  17. package/src/AbstractOverlay.js +2 -0
  18. package/src/AbstractOverlay.js.map +7 -0
  19. package/src/ClickController.d.ts +14 -0
  20. package/src/ClickController.dev.js +42 -0
  21. package/src/ClickController.dev.js.map +7 -0
  22. package/src/ClickController.js +2 -0
  23. package/src/ClickController.js.map +7 -0
  24. package/src/HoverController.d.ts +20 -0
  25. package/src/HoverController.dev.js +153 -0
  26. package/src/HoverController.dev.js.map +7 -0
  27. package/src/HoverController.js +2 -0
  28. package/src/HoverController.js.map +7 -0
  29. package/src/InteractionController.d.ts +38 -0
  30. package/src/InteractionController.dev.js +90 -0
  31. package/src/InteractionController.dev.js.map +7 -0
  32. package/src/InteractionController.js +2 -0
  33. package/src/InteractionController.js.map +7 -0
  34. package/src/LongpressController.d.ts +21 -0
  35. package/src/LongpressController.dev.js +156 -0
  36. package/src/LongpressController.dev.js.map +7 -0
  37. package/src/LongpressController.js +2 -0
  38. package/src/LongpressController.js.map +7 -0
  39. package/src/Overlay.d.ts +134 -0
  40. package/src/Overlay.dev.js +535 -0
  41. package/src/Overlay.dev.js.map +7 -0
  42. package/src/Overlay.js +33 -0
  43. package/src/Overlay.js.map +7 -0
  44. package/src/OverlayDialog.d.ts +4 -0
  45. package/src/OverlayDialog.dev.js +140 -0
  46. package/src/OverlayDialog.dev.js.map +7 -0
  47. package/src/OverlayDialog.js +2 -0
  48. package/src/OverlayDialog.js.map +7 -0
  49. package/src/OverlayNoPopover.d.ts +4 -0
  50. package/src/OverlayNoPopover.dev.js +117 -0
  51. package/src/OverlayNoPopover.dev.js.map +7 -0
  52. package/src/OverlayNoPopover.js +2 -0
  53. package/src/OverlayNoPopover.js.map +7 -0
  54. package/src/OverlayPopover.d.ts +4 -0
  55. package/src/OverlayPopover.dev.js +199 -0
  56. package/src/OverlayPopover.dev.js.map +7 -0
  57. package/src/OverlayPopover.js +2 -0
  58. package/src/OverlayPopover.js.map +7 -0
  59. package/src/OverlayStack.d.ts +44 -0
  60. package/src/OverlayStack.dev.js +163 -0
  61. package/src/OverlayStack.dev.js.map +7 -0
  62. package/src/OverlayStack.js +2 -0
  63. package/src/OverlayStack.js.map +7 -0
  64. package/src/OverlayTrigger.d.ts +52 -0
  65. package/src/OverlayTrigger.dev.js +243 -0
  66. package/src/OverlayTrigger.dev.js.map +7 -0
  67. package/src/OverlayTrigger.js +57 -0
  68. package/src/OverlayTrigger.js.map +7 -0
  69. package/src/PlacementController.d.ts +40 -0
  70. package/src/PlacementController.dev.js +212 -0
  71. package/src/PlacementController.dev.js.map +7 -0
  72. package/src/PlacementController.js +2 -0
  73. package/src/PlacementController.js.map +7 -0
  74. package/src/VirtualTrigger.d.ts +7 -0
  75. package/src/VirtualTrigger.dev.js +32 -0
  76. package/src/VirtualTrigger.dev.js.map +7 -0
  77. package/src/VirtualTrigger.js +2 -0
  78. package/src/VirtualTrigger.js.map +7 -0
  79. package/src/events.d.ts +23 -0
  80. package/src/events.dev.js +39 -0
  81. package/src/events.dev.js.map +7 -0
  82. package/src/events.js +2 -0
  83. package/src/events.js.map +7 -0
  84. package/src/fullSizePlugin.d.ts +12 -0
  85. package/src/fullSizePlugin.dev.js +39 -0
  86. package/src/fullSizePlugin.dev.js.map +7 -0
  87. package/src/fullSizePlugin.js +2 -0
  88. package/src/fullSizePlugin.js.map +7 -0
  89. package/src/index.d.ts +6 -0
  90. package/src/index.dev.js +8 -0
  91. package/src/index.dev.js.map +7 -0
  92. package/src/index.js +2 -0
  93. package/src/index.js.map +7 -0
  94. package/src/loader.d.ts +4 -0
  95. package/src/loader.dev.js +11 -0
  96. package/src/loader.dev.js.map +7 -0
  97. package/src/loader.js +2 -0
  98. package/src/loader.js.map +7 -0
  99. package/src/overlay-events.d.ts +11 -0
  100. package/src/overlay-events.dev.js +8 -0
  101. package/src/overlay-events.dev.js.map +7 -0
  102. package/src/overlay-events.js +2 -0
  103. package/src/overlay-events.js.map +7 -0
  104. package/src/overlay-timer.d.ts +22 -0
  105. package/src/overlay-timer.dev.js +72 -0
  106. package/src/overlay-timer.dev.js.map +7 -0
  107. package/src/overlay-timer.js +2 -0
  108. package/src/overlay-timer.js.map +7 -0
  109. package/src/overlay-trigger-directive.d.ts +26 -0
  110. package/src/overlay-trigger-directive.dev.js +87 -0
  111. package/src/overlay-trigger-directive.dev.js.map +7 -0
  112. package/src/overlay-trigger-directive.js +2 -0
  113. package/src/overlay-trigger-directive.js.map +7 -0
  114. package/src/overlay-trigger.css.d.ts +2 -0
  115. package/src/overlay-trigger.css.dev.js +7 -0
  116. package/src/overlay-trigger.css.dev.js.map +7 -0
  117. package/src/overlay-trigger.css.js +4 -0
  118. package/src/overlay-trigger.css.js.map +7 -0
  119. package/src/overlay-types.d.ts +50 -0
  120. package/src/overlay-types.dev.js +3 -0
  121. package/src/overlay-types.dev.js.map +7 -0
  122. package/src/overlay-types.js +2 -0
  123. package/src/overlay-types.js.map +7 -0
  124. package/src/overlay.css.d.ts +2 -0
  125. package/src/overlay.css.dev.js +7 -0
  126. package/src/overlay.css.dev.js.map +7 -0
  127. package/src/overlay.css.js +4 -0
  128. package/src/overlay.css.js.map +7 -0
  129. package/src/slottable-request-directive.d.ts +17 -0
  130. package/src/slottable-request-directive.dev.js +66 -0
  131. package/src/slottable-request-directive.dev.js.map +7 -0
  132. package/src/slottable-request-directive.js +2 -0
  133. package/src/slottable-request-directive.js.map +7 -0
  134. package/src/slottable-request-event.d.ts +12 -0
  135. package/src/slottable-request-event.dev.js +28 -0
  136. package/src/slottable-request-event.dev.js.map +7 -0
  137. package/src/slottable-request-event.js +2 -0
  138. package/src/slottable-request-event.js.map +7 -0
  139. package/src/strategies.d.ts +8 -0
  140. package/src/strategies.dev.js +10 -0
  141. package/src/strategies.dev.js.map +7 -0
  142. package/src/strategies.js +2 -0
  143. package/src/strategies.js.map +7 -0
  144. package/sync/overlay-trigger.d.ts +6 -0
  145. package/sync/overlay-trigger.dev.js +6 -0
  146. package/sync/overlay-trigger.dev.js.map +7 -0
  147. package/sync/overlay-trigger.js +2 -0
  148. package/sync/overlay-trigger.js.map +7 -0
package/README.md ADDED
@@ -0,0 +1,465 @@
1
+ ## Description
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.
4
+
5
+ ### Usage
6
+
7
+ [![See it on NPM!](https://img.shields.io/npm/v/@spectrum-web-components/overlay?style=for-the-badge)](https://www.npmjs.com/package/@spectrum-web-components/overlay)
8
+ [![How big is this package in your project?](https://img.shields.io/bundlephobia/minzip/@spectrum-web-components/overlay?style=for-the-badge)](https://bundlephobia.com/result?p=@spectrum-web-components/overlay)
9
+
10
+ ```
11
+ yarn add @spectrum-web-components/overlay
12
+ ```
13
+
14
+ Import the side effectful registration of `<sp-overlay>` as follows:
15
+
16
+ ```
17
+ import '@spectrum-web-components/overlay/sp-overlay.js';
18
+ ```
19
+
20
+ When looking to leverage the `Overlay` base class as a type and/or for extension purposes, do so via:
21
+
22
+ ```
23
+ import {
24
+ Overlay
25
+ } from '@spectrum-web-components/overlay';
26
+ ```
27
+
28
+ ## Example
29
+
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.
31
+
32
+ ```html
33
+ <sp-button id="trigger">Overlay Trigger</sp-button>
34
+
35
+ <!-- Opening an overlay via a click interaction -->
36
+ <sp-overlay trigger="trigger@click" placement="bottom">
37
+ <sp-popover>
38
+ <sp-dialog>
39
+ <h2 slot="heading">Clicking opens this popover...</h2>
40
+ <p>But, it really could be anything. Really.</p>
41
+ </sp-dialog>
42
+ </sp-popover>
43
+ </sp-overlay>
44
+
45
+ <!-- Opening an overlay via a hover interaction -->
46
+ <sp-overlay trigger="trigger@hover" placement="bottom">
47
+ <sp-tooltip>
48
+ I'm a tooltip and I'm triggered by hovering over the button!
49
+ </sp-tooltip>
50
+ </sp-overlay>
51
+ ```
52
+
53
+ When a `<sp-overlay>` element is opened, it will pass that state to its direct children elements as the property `open`, which it will set to `true`. Elements should react to this by initiating any transition between closed and open that they see fit. Similarly, `open` will be set to `false` when the `<sp-overlay>` element is closed.
54
+
55
+ ### Action Bar
56
+
57
+ ```html
58
+ <style>
59
+ .overlay-demo-popover sp-action-group {
60
+ padding: var(--spectrum-actiongroup-vertical-spacing-regular);
61
+ }
62
+ #overlay-demo {
63
+ position: static;
64
+ }
65
+ #overlay-demo:not(:defined),
66
+ #overlay-demo *:not(:defined) {
67
+ display: none;
68
+ }
69
+ </style>
70
+ <sp-popover id="overlay-demo" class="overlay-demo-popover" open>
71
+ <sp-action-group vertical quiet emphasized selects="single">
72
+ <sp-action-button id="trigger-1" hold-affordance>
73
+ <sp-icon-anchor-select slot="icon"></sp-icon-anchor-select>
74
+ </sp-action-button>
75
+ <sp-action-button id="trigger-2" hold-affordance>
76
+ <sp-icon-polygon-select slot="icon"></sp-icon-polygon-select>
77
+ </sp-action-button>
78
+ <sp-action-button id="trigger-3" hold-affordance>
79
+ <sp-icon-rect-select slot="icon"></sp-icon-rect-select>
80
+ </sp-action-button>
81
+ </sp-action-group>
82
+ <sp-overlay trigger="trigger-1@hover" type="hint">
83
+ <sp-tooltip>Hover</sp-tooltip>
84
+ </sp-overlay>
85
+ <sp-overlay
86
+ trigger="trigger-1@longpress"
87
+ type="auto"
88
+ placement="right-start"
89
+ >
90
+ <sp-popover class="overlay-demo-popover" tip>
91
+ <sp-action-group vertical quiet>
92
+ <sp-action-button>
93
+ <sp-icon-anchor-select slot="icon"></sp-icon-anchor-select>
94
+ </sp-action-button>
95
+ <sp-action-button>
96
+ <sp-icon-polygon-select
97
+ slot="icon"
98
+ ></sp-icon-polygon-select>
99
+ </sp-action-button>
100
+ <sp-action-button>
101
+ <sp-icon-rect-select slot="icon"></sp-icon-rect-select>
102
+ </sp-action-button>
103
+ </sp-action-group>
104
+ </sp-popover>
105
+ </sp-overlay>
106
+ <sp-overlay trigger="trigger-2@hover" type="hint">
107
+ <sp-tooltip>Hover</sp-tooltip>
108
+ </sp-overlay>
109
+ <sp-overlay
110
+ trigger="trigger-2@longpress"
111
+ type="auto"
112
+ placement="right-start"
113
+ >
114
+ <sp-popover class="overlay-demo-popover" tip>
115
+ <sp-action-group vertical quiet>
116
+ <sp-action-button>
117
+ <sp-icon-anchor-select slot="icon"></sp-icon-anchor-select>
118
+ </sp-action-button>
119
+ <sp-action-button>
120
+ <sp-icon-polygon-select
121
+ slot="icon"
122
+ ></sp-icon-polygon-select>
123
+ </sp-action-button>
124
+ <sp-action-button>
125
+ <sp-icon-rect-select slot="icon"></sp-icon-rect-select>
126
+ </sp-action-button>
127
+ </sp-action-group>
128
+ </sp-popover>
129
+ </sp-overlay>
130
+ <sp-overlay trigger="trigger-3@hover" type="hint">
131
+ <sp-tooltip>Hover</sp-tooltip>
132
+ </sp-overlay>
133
+ <sp-overlay
134
+ trigger="trigger-3@longpress"
135
+ type="auto"
136
+ placement="right-start"
137
+ >
138
+ <sp-popover class="overlay-demo-popover" tip>
139
+ <sp-action-group vertical quiet>
140
+ <sp-action-button>
141
+ <sp-icon-anchor-select slot="icon"></sp-icon-anchor-select>
142
+ </sp-action-button>
143
+ <sp-action-button>
144
+ <sp-icon-polygon-select
145
+ slot="icon"
146
+ ></sp-icon-polygon-select>
147
+ </sp-action-button>
148
+ <sp-action-button>
149
+ <sp-icon-rect-select slot="icon"></sp-icon-rect-select>
150
+ </sp-action-button>
151
+ </sp-action-group>
152
+ </sp-popover>
153
+ </sp-overlay>
154
+ </sp-popover>
155
+ ```
156
+
157
+ ## API
158
+
159
+ ```ts
160
+ <sp-overlay
161
+ ?open=${boolean}
162
+ ?delayed=${boolean}
163
+ offset=${Number | [Number, Number]}
164
+ placement=${Placement}
165
+ receives-focus=${'true' | 'false' | 'auto' (default)
166
+ trigger=${string | ${string}@${string}}
167
+ .triggerElement=${HTMLElement}
168
+ .triggerInteraction=${'click' | 'longpress' | 'hover'}
169
+ type=${'auto' | 'hint' | 'manual' | 'modal' | 'page'}
170
+ ></sp-overlay>
171
+ ```
172
+
173
+ ### API value interactions
174
+
175
+ 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:
176
+
177
+ - **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
178
+ - **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`
179
+ - **if an `offset` is also available** the `<sp-overlay>` will distance itself from the `triggerElement` in accordance with the value of the `offset`
180
+ - **if you have a `placement` but not a `triggerElement`** the `<sp-overlay>` will not be positioned due to their being nothing for the `placement` to reference when so doing
181
+ - **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).
182
+
183
+ ### Overlay types
184
+
185
+ The `type` of an Overlay outlines a number of things about the interaction model within which is works.
186
+
187
+ ### Modal
188
+
189
+ `'modal'` Overlays are opened with the `showModal()` method on a `<dialog>` element, which causes the Overlay to accept focus and trap the tab stop within the content of said Overlay.
190
+
191
+ They should be used when you need to ensure that the user has interacted with the content of the Overlay before continuing with their work. This is commonly used for dialogs that require a user to confirm or cancel an action before continuing.
192
+
193
+ ```html
194
+ <sp-button id="trigger">open modal</sp-button>
195
+ <sp-overlay trigger="trigger@click" type="modal">
196
+ <sp-dialog-wrapper headline="Signin form" dismissable underlay>
197
+ <p>I am a modal type overlay.</p>
198
+ <sp-field-label>Enter your email</sp-field-label>
199
+ <sp-textfield placeholder="test@gmail.com"></sp-textfield>
200
+ <sp-action-button
201
+ onClick="
202
+ this.dispatchEvent(
203
+ new Event('close', {
204
+ bubbles: true,
205
+ composed: true,
206
+ })
207
+ );
208
+ "
209
+ >
210
+ Sign in
211
+ </sp-action-button>
212
+ </sp-dialog-wrapper>
213
+ </sp-overlay>
214
+ ```
215
+
216
+ ### Page
217
+
218
+ `'page'` Overlays will act in a similar manner to a `'modal'` Overlay, however they will not be allowed to close via the "light dismiss" algorithm (e.g. the Escape key).
219
+
220
+ A page overlay could be used for a full-screen menu on a mobile website. When the user clicks on the menu button, the entire screen is covered with the menu options.
221
+
222
+ ```html
223
+ <sp-button id="trigger">open page</sp-button>
224
+ <sp-overlay trigger="trigger@click" type="page">
225
+ <sp-dialog-wrapper
226
+ headline="Full screen menu"
227
+ mode="fullscreenTakeover"
228
+ cancel-label="Close"
229
+ >
230
+ <p>I am a page type overlay.</p>
231
+ </sp-dialog-wrapper>
232
+ </sp-overlay>
233
+ ```
234
+
235
+ ### Hint
236
+
237
+ `'hint'` Overlays are much like tooltips so they are not just ephemeral, but they are delivered primarily as a visual helper and exist outside of the tab order. In this way, be sure _not_ to place interactive content within this type of Overlay.
238
+
239
+ This overlay type does not accept focus and does not interfere with the user's interaction with the rest of the page.
240
+
241
+ ```html
242
+ <sp-button id="trigger">open hint</sp-button>
243
+ <sp-overlay trigger="trigger@hover" type="hint">
244
+ <sp-tooltip>
245
+ I am a hint type overlay. I am not interactive and will close when the
246
+ user interacts with the page.
247
+ </sp-tooltip>
248
+ </sp-overlay>
249
+ ```
250
+
251
+ ### Auto
252
+
253
+ `'auto'` Overlays provide a place for content that is ephemeral _and_ interactive. These Overlays can accept focus but will close when losing that focus, or when interacting with other parts of the page.
254
+
255
+ ```html
256
+ <style>
257
+ sp-toast {
258
+ position: fixed;
259
+ top: 1em;
260
+ right: 1em;
261
+ }
262
+ </style>
263
+ <sp-button id="trigger">open auto</sp-button>
264
+ <sp-overlay trigger="trigger@click" type="auto">
265
+ <sp-toast variant="info">
266
+ This is information that you should read.
267
+ </sp-toast>
268
+ </sp-overlay>
269
+ ```
270
+
271
+ ### Manual
272
+
273
+ `'manual'` Overlays act much like `'auto'` Overlays, but do not close when losing focus or interacting with other parts of the page.
274
+
275
+ Note: When a `'manual'` Overlay is at the top of the "overlay stack", it will still respond to the Escape key and close.
276
+
277
+ ```html
278
+ <style>
279
+ .chat-container {
280
+ position: fixed;
281
+ bottom: 1em;
282
+ left: 1em;
283
+ }
284
+ </style>
285
+ <sp-button id="trigger">open manual</sp-button>
286
+ <sp-overlay trigger="trigger@click" type="manual">
287
+ <sp-popover class="chat-container">
288
+ <sp-dialog dismissable>
289
+ <span slot="heading">Chat Window</span>
290
+ <sp-textfield placeholder="Enter your message"></sp-textfield>
291
+ <sp-action-button>Send</sp-action-button>
292
+ </sp-dialog>
293
+ </sp-popover>
294
+ </sp-overlay>
295
+ ```
296
+
297
+ ### Events
298
+
299
+ When fully open the `<sp-overlay>` element will dispatch the `sp-opened` event, and when fully closed the `sp-closed` event will be dispatched. Both of these events are of type:
300
+
301
+ ```ts
302
+ type OverlayStateEvent = Event & {
303
+ overlay: Overlay;
304
+ };
305
+ ```
306
+
307
+ The `overlay` value in this case will hold a reference to the actual `<sp-overlay>` that is opening or closing to trigger this event. Remember that some `<sp-overlay>` element (like those creates via the imperative API) can be transiently available in the DOM, so if you choose to build a cache of Overlay elements to some end, be sure to leverage a weak reference so that the `<sp-overlay>` can be garbage collected as desired by the browser.
308
+
309
+ #### When it is "fully" open or closed?
310
+
311
+ "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:
312
+
313
+ - `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
314
+ - `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
315
+
316
+ 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>`.
317
+
318
+ ## Styling
319
+
320
+ `<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.
321
+
322
+ ## Top Layer over Complex CSS
323
+
324
+ 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.
325
+
326
+ ## Fallback support
327
+
328
+ 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.
329
+
330
+ ### Complex layered
331
+
332
+ 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.
333
+
334
+ ```html
335
+ <div class="complex-layered-demo">
336
+ <div class="complex-layered-holder">
337
+ <sp-action-button id="complex-layered">Trigger</sp-action-button>
338
+ <sp-overlay
339
+ trigger="complex-layered@hover"
340
+ type="hint"
341
+ placement="bottom-start"
342
+ >
343
+ <sp-tooltip>
344
+ I can be partially blocked when [popover] is not available
345
+ </sp-tooltip>
346
+ </sp-overlay>
347
+ </div>
348
+ <div class="complex-layered-blocker"></div>
349
+ </div>
350
+ <style>
351
+ .complex-layered-demo {
352
+ position: relative;
353
+ }
354
+ .complex-layered-holder {
355
+ z-index: 1;
356
+ position: relative;
357
+ }
358
+ .complex-layered-blocker {
359
+ position: relative;
360
+ z-index: 10;
361
+ background: white;
362
+ width: 100%;
363
+ height: 40px;
364
+ }
365
+ </style>
366
+ ```
367
+
368
+ 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.
369
+
370
+ ### Contained
371
+
372
+ [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.
373
+
374
+ ```html
375
+ <div class="contained-demo">
376
+ <sp-action-button id="contained">Trigger</sp-action-button>
377
+ <sp-overlay trigger="contained@hover" type="hint" placement="bottom-start">
378
+ <sp-tooltip>
379
+ I can be blocked when [popover] is not available
380
+ </sp-tooltip>
381
+ </sp-overlay>
382
+ </div>
383
+ <style>
384
+ .contained-demo {
385
+ contain: content;
386
+ }
387
+ </style>
388
+ ```
389
+
390
+ 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:
391
+
392
+ ```html
393
+ <div class="contained-demo">
394
+ <sp-action-button id="contained-working">Trigger</sp-action-button>
395
+ </div>
396
+ <sp-overlay
397
+ trigger="contained-working@hover"
398
+ type="hint"
399
+ placement="bottom-start"
400
+ >
401
+ <sp-tooltip>I can be blocked when [popover] is not available</sp-tooltip>
402
+ </sp-overlay>
403
+ <style>
404
+ .contained-demo {
405
+ contain: content;
406
+ }
407
+ </style>
408
+ ```
409
+
410
+ `<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.
411
+
412
+ ### Clip pathed
413
+
414
+ `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_.
415
+
416
+ ```html
417
+ <div class="clip-pathed-demo">
418
+ <sp-action-button id="clip-pathed">Trigger</sp-action-button>
419
+ <sp-overlay
420
+ trigger="clip-pathed@hover"
421
+ type="hint"
422
+ placement="bottom-start"
423
+ >
424
+ <sp-tooltip>
425
+ I can be blocked when [popover] is not available
426
+ </sp-tooltip>
427
+ </sp-overlay>
428
+ </div>
429
+ <style>
430
+ .clip-pathed-demo {
431
+ clip-path: inset(0 0);
432
+ }
433
+ </style>
434
+ ```
435
+
436
+ 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:
437
+
438
+ ```html
439
+ <div class="clip-pathed-demo">
440
+ <sp-action-button id="clip-pathed-working">Trigger</sp-action-button>
441
+ </div>
442
+ <sp-overlay
443
+ trigger="clip-pathed-working@hover"
444
+ type="hint"
445
+ placement="bottom-start"
446
+ >
447
+ <sp-tooltip>I can be blocked when [popover] is not available</sp-tooltip>
448
+ </sp-overlay>
449
+ <style>
450
+ .clip-pathed-demo {
451
+ clip-path: inset(0 0);
452
+ }
453
+ </style>
454
+ ```
455
+
456
+ ### Non-overflowing, relative containers with z-index in Safari
457
+
458
+ Under very specific conditions, [WebKit will incorrectly clip fixed-position content](https://bugs.webkit.org/show_bug.cgi?id=160953).
459
+ WebKit clips `position: fixed` elements within containers that have all of:
460
+
461
+ 1. `position: relative`
462
+ 2. `overflow: clip` or `overflow: hidden`
463
+ 3. `z-index` greater than zero
464
+
465
+ If you notice overlay clipping _only_ in Safari, this is likely the culprit. The solution is to break up the conditions into separate elements to avoid triggering WebKit's bug. For example, leaving relative positioning and z-index on the outermost container while creating an inner container that enforces the overflow rules.
package/local.d.ts ADDED
@@ -0,0 +1,56 @@
1
+ /*
2
+ Copyright 2020 Adobe. All rights reserved.
3
+ This file is licensed to you under the Apache License, Version 2.0 (the "License");
4
+ you may not use this file except in compliance with the License. You may obtain a copy
5
+ of the License at http://www.apache.org/licenses/LICENSE-2.0
6
+
7
+ Unless required by applicable law or agreed to in writing, software distributed under
8
+ the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
9
+ OF ANY KIND, either express or implied. See the License for the specific language
10
+ governing permissions and limitations under the License.
11
+ */
12
+
13
+ declare module '@popperjs/core/dist/esm/popper-lite.js' {
14
+ import {
15
+ popperGenerator,
16
+ defaultModifiers,
17
+ } from '@popperjs/core/lib/popper-lite';
18
+
19
+ export { popperGenerator, defaultModifiers };
20
+ }
21
+
22
+ declare module '@popperjs/core/dist/esm/types.js' {
23
+ import { Instance, VirtualElement } from '@popperjs/core/lib/types.js';
24
+
25
+ export { Instance, VirtualElement };
26
+ }
27
+
28
+ declare module '@popperjs/core/dist/esm/enums.js' {
29
+ import { Placement } from '@popperjs/core/lib/enums.js';
30
+
31
+ export { Placement };
32
+ }
33
+
34
+ declare module '@popperjs/core/dist/esm/modifiers/flip.js' {
35
+ import flip from '@popperjs/core/lib/modifiers/flip.js';
36
+
37
+ export default flip;
38
+ }
39
+
40
+ declare module '@popperjs/core/dist/esm/modifiers/preventOverflow.js' {
41
+ import preventOverflow from '@popperjs/core/lib/modifiers/preventOverflow.js';
42
+
43
+ export default preventOverflow;
44
+ }
45
+
46
+ declare module '@popperjs/core/dist/esm/modifiers/arrow.js' {
47
+ import arrow from '@popperjs/core/lib/modifiers/arrow.js';
48
+
49
+ export default arrow;
50
+ }
51
+
52
+ declare module '@popperjs/core/dist/esm/modifiers/offset.js' {
53
+ import offset from '@popperjs/core/lib/modifiers/offset.js';
54
+
55
+ export default offset;
56
+ }
@@ -0,0 +1,6 @@
1
+ import { OverlayTrigger } from './src/OverlayTrigger.js';
2
+ declare global {
3
+ interface HTMLElementTagNameMap {
4
+ 'overlay-trigger': OverlayTrigger;
5
+ }
6
+ }
@@ -0,0 +1,5 @@
1
+ "use strict";
2
+ import { defineElement } from "@spectrum-web-components/base/src/define-element.js";
3
+ import { OverlayTrigger } from "./src/OverlayTrigger.dev.js";
4
+ defineElement("overlay-trigger", OverlayTrigger);
5
+ //# sourceMappingURL=overlay-trigger.dev.js.map
@@ -0,0 +1,7 @@
1
+ {
2
+ "version": 3,
3
+ "sources": ["overlay-trigger.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 { OverlayTrigger } from './src/OverlayTrigger.dev.js'\n\ndefineElement('overlay-trigger', OverlayTrigger);\n\ndeclare global {\n interface HTMLElementTagNameMap {\n 'overlay-trigger': OverlayTrigger;\n }\n}\n"],
5
+ "mappings": ";AAWA,SAAS,qBAAqB;AAC9B,SAAS,sBAAsB;AAE/B,cAAc,mBAAmB,cAAc;",
6
+ "names": []
7
+ }
@@ -0,0 +1,2 @@
1
+ "use strict";import{defineElement as e}from"@spectrum-web-components/base/src/define-element.js";import{OverlayTrigger as r}from"./src/OverlayTrigger.js";e("overlay-trigger",r);
2
+ //# sourceMappingURL=overlay-trigger.js.map
@@ -0,0 +1,7 @@
1
+ {
2
+ "version": 3,
3
+ "sources": ["overlay-trigger.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 { OverlayTrigger } from './src/OverlayTrigger.js';\n\ndefineElement('overlay-trigger', OverlayTrigger);\n\ndeclare global {\n interface HTMLElementTagNameMap {\n 'overlay-trigger': OverlayTrigger;\n }\n}\n"],
5
+ "mappings": "aAWA,OAAS,iBAAAA,MAAqB,sDAC9B,OAAS,kBAAAC,MAAsB,0BAE/BD,EAAc,kBAAmBC,CAAc",
6
+ "names": ["defineElement", "OverlayTrigger"]
7
+ }