You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: packages/overlay/imperative-api.md
+23-25
Original file line number
Diff line number
Diff line change
@@ -1,4 +1,4 @@
1
-
## Description
1
+
## Overview
2
2
3
3
While an `<sp-overlay>` element is the recommended entry point to the Spectrum Web Components Overlay API, you can also interact with this set of features via an imperative API, `Overlay.open`.
4
4
@@ -7,19 +7,21 @@ While an `<sp-overlay>` element is the recommended entry point to the Spectrum W
7
7
[](https://www.npmjs.com/package/@spectrum-web-components/overlay)
8
8
[](https://bundlephobia.com/result?p=@spectrum-web-components/overlay)
9
9
10
-
```
10
+
```zsh
11
11
yarn add @spectrum-web-components/overlay
12
12
```
13
13
14
14
Import the `Overlay` class to leverage its capabilities within your application or custom element:
Primarily, this class gives you access to the `open` method that will allow you to open an overlay:
21
23
22
-
```js
24
+
```ts
23
25
Overlay.open(
24
26
(overlayElement:HTMLElement), // the element that will be projected into the overlay, "content",
25
27
(options?:OverlayOptions)
@@ -28,7 +30,7 @@ Overlay.open(
28
30
29
31
`Overlay.open()` is an asynchronous method that returns an `<sp-overlay>` element that wraps the `HTMLElement` provided as the `overlayElement`. While this process will set the `<sp-overlay>` element to `open`, consumers of this API will need to choose where to append this element to the DOM in order for the content to be made available in the browser.
Keep in mind that a changing DOM tree is likely to alter the relationship between existing content. Without proper care this can negatively effect the CSS that you have applied to existing content. DOM events and DOM selection methods can also perform differently than expected as the tree shape changes.
46
48
47
-
##OverlayOptions
49
+
### Options
48
50
49
51
When leveraging `Overlay.open()`, you can provide an optional second argument of `OverlayOptions`, with the following type:
50
52
@@ -60,33 +62,39 @@ type OverlayOptions = {
60
62
};
61
63
```
62
64
63
-
###delayed
65
+
#### `delayed`
64
66
65
67
An Overlay that is `delayed` will wait until a warm-up period of 1000ms has completed before opening. Once the warmup period has completed, all subsequent Overlays will open immediately. When no Overlays are opened, a cooldown period of 1000ms will begin. Once the cooldown has completed, the next Overlay to be opened will be subject to the warm-up period if provided that option.
66
68
67
-
###notImmediatelyCloseable
69
+
#### `notImmediatelyCloseable`
68
70
69
71
When an Overlay is `notImmediatelyCloseable` that means that the first interaction that would lead to the closure of the Overlay in question will be ignored. This is useful when working with non-"click" mouse interactions, like `contextmenu`, where the trigger event (e.g. `contextmenu`) occurs _before_ an event that would close said overlay (e.g. `pointerup`).
70
72
71
-
###offset
73
+
#### `offset`
72
74
73
75
The `offset` property accepts either a single number, to define the offset of the Overlay along the main axis from the trigger, or 2-tuple, to define the offset along the main axis and the cross axis. This option has no effect when there is no trigger element.
74
76
75
-
###placement
77
+
#### `placement`
76
78
77
79
A `placement` of `"auto-start" | "auto-end" | "top" | "bottom" | "right" | "left" | "top-start" | "top-end" | "bottom-start" | "bottom-end" | "right-start" | "right-end" | "left-start" | "left-end"` will instruct the Overlay where to place itself in relationship to the trigger element.
78
80
79
-
###receivesFocus
81
+
#### `receivesFocus`
80
82
81
83
Some Overlays will always be passed focus (e.g. modal or page Overlays). When this is not true, the `receivesFocus` option will inform the API whether to attempt to pass focus into the Overlay once it is open. `'true'` will pass focus, `'false'` will not (when possible), and `"auto"` (the default), will make a decision based on the `type` of the Overlay.
82
84
83
-
###trigger
85
+
#### `trigger`
84
86
85
87
The `trigger` option accepts an `HTMLElement` or a `VirtualTrigger` from which to position the Overlay.
86
88
87
89
- You can import the `VirtualTrigger` class from the overlay package to create a virtual trigger that can be used to position an Overlay. This is useful when you want to position an Overlay relative to a point on the screen that is not an element in the DOM, like the mouse cursor.
88
90
89
-
### Using a virtual trigger
91
+
#### `type`
92
+
93
+
The `type` of an Overlay outlines a number of things about the interaction model within which it works which are described in the [Overlay types](https://opensource.adobe.com/spectrum-web-components/components/overlay/#overlay-types).
94
+
95
+
### Advanced topics
96
+
97
+
#### Using a virtual trigger
90
98
91
99
```html-live
92
100
<style>
@@ -163,11 +171,11 @@ The `trigger` option accepts an `HTMLElement` or a `VirtualTrigger` from which t
@@ -218,13 +226,3 @@ The `trigger` option accepts an `HTMLElement` or a `VirtualTrigger` from which t
218
226
});
219
227
});
220
228
</script>
221
-
222
-
### type
223
-
224
-
The `type` of an Overlay outlines a number of things about the interaction model within which is works.
225
-
226
-
-`'modal'` Overlays create a modal context that traps focus within the content and prevents interaction with the rest of the page. The overlay manages focus trapping and accessibility features like `aria-modal="true"` to ensure proper screen reader behavior.
227
-
-`'page'` Overlays behave similarly to `'modal'` Overlays by creating a modal context and trapping focus, but they will not be allowed to close via the "light dismiss" algorithm (e.g. the Escape key).
228
-
-`'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.
229
-
-`'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.
230
-
-`'manual'` Overlays act much like `"auto"` Overlays, but do not close when losing focus or interacting with other parts of the page. When a `"manual"` Overlay is at the top of the "overlay stack", it will still respond to the Escape key and close.
Copy file name to clipboardExpand all lines: packages/overlay/overlay-trigger.md
+89-63
Original file line number
Diff line number
Diff line change
@@ -17,7 +17,7 @@
17
17
</div>
18
18
</div>
19
19
20
-
## Description
20
+
## Overview
21
21
22
22
An `<overlay-trigger>` element supports the delivery of temporary overlay content based on interaction with a persistent trigger element. An element prepared to receive accessible interactions (e.g. an `<sp-button>`, or `<button>`, etc.) is addressed to `slot="trigger"`, and the content to display (either via `click` or `hover`/`focus` interactions) is addressed to `slot="click-content"` or `slot="hover-content"`, respectively. A trigger element can be linked to the delivery of content, intended for a single interaction, or both. Content addressed to `slot="hover-content"` is made available when the mouse enters or leaves the target element. Keyboard navigation will make this content available when focus enters or leaves the target element. Be thoughtful with what content you address to `slot="hover-content"`, as the content available via "hover" will be transient and non-interactive.
23
23
@@ -27,79 +27,31 @@ An `<overlay-trigger>` element supports the delivery of temporary overlay conten
27
27
[](https://bundlephobia.com/result?p=@spectrum-web-components/overlay)
28
28
[](https://webcomponents.dev/edit/collection/fO75441E1Q5ZlI0e9pgq/bu0sOBIfyW7wnHkXtGzL/src/index.ts)
29
29
30
-
```
30
+
```zsh
31
31
yarn add @spectrum-web-components/overlay
32
32
```
33
33
34
34
Import the side-effectful registration of `<overlay-trigger>` via:
The default of `<overlay-trigger>` will load dependencies in `@spectrum-web-components/overlay` asynchronously via a dynamic import. In the case that you would like to import those tranverse dependencies statically, import the side effectful registration of `<overlay-trigger>` as follows:
When using the `placement` attribute of an `<overlay-trigger>` (`"top" |"top-start" | "top-end" | "bottom" | "bottom-start" | "bottom-end" | "right" | "right-start" | "right-end" | "left" | "left-start" | "left-end"`), you can suggest to the overlay in which direction relative to the trigger that the content should display. When there is adequate room for the content to display in the specified direction, it will do so. When adequate room is not available, the overlaid content will calculate the direction in which it has the most room to be displayed and use that direction.
55
-
56
-
### Type
52
+
### Example
57
53
58
-
The `type` attribute of an `<overlay-trigger>` element outlines how the element's "click" content should appear in the tab order. `inline` will insert the overlay after the trigger; from here, forward tabbing targets the next logical element, and backward/shift tabbing returns to the target. `replace` will insert the overlay into the page as if it were the trigger; from here, forward tabbing targets the next logical element, and backward/shift tabbing targets the logical element prior to the target. Finally, `modal` will open the content in a tab order fully separate from the original content flow and trap the tab order within that content until the required interaction is complete.
59
-
60
-
## Examples
61
-
62
-
Here a default `<overlay-trigger>` manages content that is triggered by click and "hover" interactions.
This example only delivers content via the "click" interaction and leverages both `placement` and `type` attributes to customize the visual relationship of the content to the page and its position in the tab order.
54
+
In this example, a default `<overlay-trigger>` manages content that is triggered by "click" and "hover" interactions.
103
55
104
56
```html
105
57
<overlay-triggerplacement="top"type="replace">
@@ -120,22 +72,96 @@ This example only delivers content via the "click" interaction and leverages bot
When using the `placement` attribute of an `<overlay-trigger>` (`"top" |"top-start" | "top-end" | "bottom" | "bottom-start" | "bottom-end" | "right" | "right-start" | "right-end" | "left" | "left-start" | "left-end"`), you can suggest to the overlay in which direction relative to the trigger that the content should display. When there is adequate room for the content to display in the specified direction, it will do so. When adequate room is not available, the overlaid content will calculate the direction in which it has the most room to be displayed and use that direction.
84
+
85
+
#### Type
127
86
128
-
The delivery of hover content can be customized via the `placement` attribute. However, this content can not be interacted with, so the `type` attribute will not customize its delivery in any way.
`'modal'` type creates a separate tab order and traps focus within the overlay content until the required interaction is complete. This is ideal for important interactions that need user attention.
The `triggered-by` attribute (`triggeredBy` property) allows you to explicitly declare which types of overlays your implementation will use. This can help optimize performance by avoiding unnecessary DOM operations and preventing race conditions during rendering.
@@ -170,6 +196,6 @@ The `triggered-by` attribute accepts a space-separated string of overlay types:
170
196
171
197
When not specified, the component will automatically detect which content types are present, but this may result in additional rendering cycles. For optimal performance, especially in applications with many overlay triggers, explicitly declaring the content types you plan to use is recommended.
172
198
173
-
## Accessibility
199
+
###Accessibility
174
200
175
201
When using an `<overlay-trigger>` element, it is important to be sure the that content you project into `slot="trigger"` is "interactive". This means that an element within that branch of DOM will be able to receive focus, and said element will appropriately convert keyboard interactions to `click` events, similar to what you'd find with `<a href="#">Anchors</a>`, `<button>Buttons</button>`, etc. You can find further reading on the subject of accessible keyboard interactions at [https://www.w3.org/WAI/WCAG21/Understanding/keyboard](https://www.w3.org/WAI/WCAG21/Understanding/keyboard).
0 commit comments