docs(overlay): a11y docs update

Author: TarunAdobe

packages/overlay/README.md

@@ -1,4 +1,4 @@
-## Description
+## Overview
 
 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`.
 
@@ -7,19 +7,21 @@ While an `<sp-overlay>` element is the recommended entry point to the Spectrum W
 [![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)
 [![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)
 
-```
+```zsh
 yarn add @spectrum-web-components/overlay
 ```
 
 Import the `Overlay` class to leverage its capabilities within your application or custom element:
 
-```js
+```ts
 import { Overlay } from '@spectrum-web-components/overlay';
 ```
 
+### Example
+
 Primarily, this class gives you access to the `open` method that will allow you to open an overlay:
 
-```js
+```ts
 Overlay.open(
     (overlayElement: HTMLElement), // the element that will be projected into the overlay, "content",
     (options?: OverlayOptions)
@@ -28,7 +30,7 @@ Overlay.open(
 
 `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.
 
-```js
+```ts
 (async () => {
     const content = document.querySelector('#content');
     const options = {
@@ -44,7 +46,7 @@ Overlay.open(
 
 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.
 
-## OverlayOptions
+### Options
 
 When leveraging `Overlay.open()`, you can provide an optional second argument of `OverlayOptions`, with the following type:
 
@@ -60,33 +62,39 @@ type OverlayOptions = {
 };
 ```
 
-### delayed
+#### delayed
 
 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.
 
-### notImmediatelyCloseable
+#### notImmediatelyCloseable
 
 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`).
 
-### offset
+#### offset
 
 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.
 
-### placement
+#### placement
 
 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.
 
-### receivesFocus
+#### receivesFocus
 
 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.
 
-### trigger
+#### trigger
 
 The `trigger` option accepts an `HTMLElement` or a `VirtualTrigger` from which to position the Overlay.
 
 -   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.
 
-### Using a virtual trigger
+#### Types
+
+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).
+
+### Advanced Topics
+
+#### Using a virtual trigger
 
 ```html-live
 <style>
@@ -163,11 +171,11 @@ The `trigger` option accepts an `HTMLElement` or a `VirtualTrigger` from which t
 
 <script type="module">
 
-    import { html, render } from '@spectrum-web-components/base';   
+    import { html, render } from '@spectrum-web-components/base';
     import { VirtualTrigger, openOverlay } from '@spectrum-web-components/overlay';
 
     const contextMenuTemplate = () => html`
-        <sp-popover 
+          <sp-popover
             style="width:300px;"
             @change=${(event) => {
                     event.target.dispatchEvent(
@@ -218,13 +226,3 @@ The `trigger` option accepts an `HTMLElement` or a `VirtualTrigger` from which t
         });
     });
 </script>
-
-### type
-
-The `type` of an Overlay outlines a number of things about the interaction model within which is works.
-
--   `'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.
--   `'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).
--   `'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.
--   `'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.
--   `'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.

packages/overlay/imperative-api.md

@@ -17,7 +17,7 @@
     </div>
 </div>
 
-## Description
+## Overview
 
 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.
 
@@ -27,80 +27,32 @@ An `<overlay-trigger>` element supports the delivery of temporary overlay conten
 [![How big is this package in your project?](https://img.shields.io/bundlephobia/minzip/@spectrum-web-components/meter?style=for-the-badge)](https://bundlephobia.com/result?p=@spectrum-web-components/overlay)
 [![Try it on webcomponents.dev](https://img.shields.io/badge/Try%20it%20on-webcomponents.dev-green?style=for-the-badge)](https://webcomponents.dev/edit/collection/fO75441E1Q5ZlI0e9pgq/bu0sOBIfyW7wnHkXtGzL/src/index.ts)
 
-```
+```zsh
 yarn add @spectrum-web-components/overlay
 ```
 
 Import the side-effectful registration of `<overlay-trigger>` via:
 
-```
+```ts
 import '@spectrum-web-components/overlay/overlay-trigger.js';
 ```
 
 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:
 
-```
+```ts
 import '@spectrum-web-components/overlay/sync/overlay-trigger.js';
 ```
 
 When looking to leverage the `OverlayTrigger` base class as a type and/or for extension purposes, do so via:
 
-```
+```ts
 import { OverlayTrigger } from '@spectrum-web-components/overlay';
 ```
 
-### Placement
-
-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.
-
-### Type
-
-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.
-
-## Examples
+### Example
 
 Here a default `<overlay-trigger>` manages content that is triggered by click and "hover" interactions.
 
-```html
-<overlay-trigger id="trigger" placement="bottom" offset="6">
-    <sp-button variant="primary" slot="trigger">Button popover</sp-button>
-    <sp-popover slot="click-content" direction="bottom" tip>
-        <sp-dialog no-divider class="options-popover-content">
-            <sp-slider
-                value="5"
-                step="0.5"
-                min="0"
-                max="20"
-                label="Awesomeness"
-            ></sp-slider>
-            <sp-button>Press me</sp-button>
-        </sp-dialog>
-    </sp-popover>
-    <sp-tooltip slot="hover-content" delayed>Tooltip</sp-tooltip>
-    <sp-popover slot="longpress-content" tip>
-        <sp-action-group
-            selects="single"
-            vertical
-            style="margin: calc(var(--spectrum-spacing-100) / 2);"
-        >
-            <sp-action-button>
-                <sp-icon-magnify slot="icon"></sp-icon-magnify>
-            </sp-action-button>
-            <sp-action-button>
-                <sp-icon-magnify slot="icon"></sp-icon-magnify>
-            </sp-action-button>
-            <sp-action-button>
-                <sp-icon-magnify slot="icon"></sp-icon-magnify>
-            </sp-action-button>
-        </sp-action-group>
-    </sp-popover>
-</overlay-trigger>
-```
-
-### Click content only
-
-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.
-
 ```html
 <overlay-trigger placement="top" type="replace">
     <sp-button slot="trigger">Overlay Trigger</sp-button>
@@ -123,7 +75,17 @@ This example only delivers content via the "click" interaction and leverages bot
 </overlay-trigger>
 ```
 
-### "Hover" content only
+### Options
+
+#### Placement
+
+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.
+
+#### Type
+
+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.
+
+#### "Hover" content only
 
 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.
 
@@ -170,6 +132,6 @@ The `triggered-by` attribute accepts a space-separated string of overlay types:
 
 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.
 
-## Accessibility
+### Accessibility
 
 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).

packages/overlay/overlay-trigger.md

@@ -1,31 +1,36 @@
-## Description
+## Overview
 
-When working with a large amount of content that lives whithin an overlay, a page may encounter performance issues for placing a large amount of content within `<sp-overlay>` or `<overlay-trigger>` elements. To avoid this, an empty `<sp-overlay>` could be used instead. When triggered, the `<sp-overlay>` element will dispatch `slottable-request` just before it begins to open and just after it finished closing. When handling these events the contents of an overlay can be lazily rendered into the `<sp-overlay>` element as it opens and then, as needed, removed from the DOM once the overlay has closed.
+The `slottable-request` event provides a performance optimization mechanism for overlays with large content. Instead of keeping large amounts of content in the DOM at all times, an empty `<sp-overlay>` can be used initially. The overlay will dispatch `slottable-request` events just before opening and after closing, allowing content to be lazily rendered and removed as needed.
 
 ### Usage
 
-```
+[![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)
+[![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)
+
+```zsh
 yarn add @spectrum-web-components/overlay
 ```
 
-Import the side effectful registration of `<sp-overlay>` as follows:
+Import the side effectful registration of `<sp-overlay>` via:
 
-```
+```ts
 import '@spectrum-web-components/overlay/sp-overlay.js';
 ```
 
-Import type information about the `slottable-request` event and a symbol to signify that the request is for the DOM to be removed:
+For type information and utilities, import:
 
-```
+```ts
 import {
     removeSlottableRequest,
     SlottableRequestEvent,
 } from '@spectrum-web-components/overlay/src/slottable-request-event.js';
 ```
 
-#### Javascript based consumption
+### Example
+
+#### Basic Usage
 
-When leveraging the `<sp-overlay>` in a javascript only context, you can leverage the `slottable-request` event and its `data` property to decide whether and what to render into the `<sp-overlay>` event.
+Here's a basic example of using `slottable-request` with vanilla JavaScript:
 
 ```html-live
 <sp-button id="js-trigger">Trigger</sp-button>
@@ -82,4 +87,63 @@ When leveraging the `<sp-overlay>` in a javascript only context, you can leverag
     });
 </script>
 
-Starting with no DOM in the `<sp-overlay>` element and returning to that when the Overlay element is no longer showing can support an application in releasing memory back to other activities.
+### Options
+
+#### Event Data
+
+The `SlottableRequestEvent` includes the following properties:
+
+-   `data`: Contains either an empty object (when opening) or the `removeSlottableRequest` symbol (when closing)
+-   `name`: The name of the request
+-   `slotName`: The slot name, optionally with a key appended
+
+### Advanced Topics
+
+#### Event Timing
+
+The `slottable-request` event is dispatched at specific times:
+
+1. Just before the overlay begins to open
+2. Just after the overlay finishes closing
+
+This timing ensures proper coordination with overlay transitions and animations.
+
+#### Memory Management
+
+By starting with an empty overlay and removing content when closed, applications can better manage memory usage, especially when dealing with:
+
+-   Large DOM trees
+-   Complex components
+-   Multiple overlays
+-   Resource-intensive content
+
+#### Integration with Lit
+
+For Lit-based applications, a directive is available for handling slottable requests:
+
+```ts
+import { slottableRequest } from '@spectrum-web-components/overlay/src/slottable-request-directive.js';
+
+// Use in a lit template
+html`
+    <sp-overlay
+        ${slottableRequest(
+            () => html`
+                <sp-popover>
+                    <p>Lazily rendered content</p>
+                </sp-popover>
+            `
+        )}
+    ></sp-overlay>
+`;
+```
+
+<div class="spectrum-InLineAlert spectrum-InLineAlert--notice">
+    <div class="spectrum-InLineAlert-header">
+        <sp-icon-alert class="spectrum-InLineAlert-icon" size="m"></sp-icon-alert>
+        <span>Experimental Feature</span>
+    </div>
+    <div class="spectrum-InLineAlert-content">
+        The <code>slottable-request</code> event system is experimental. Its shape and presence in the library may change. For stable overlay content management, consider using <code>sp-overlay</code> or <code>Overlay.open()</code>.
+    </div>
+</div>