docs(overlay): a11y docs update #5409

TarunAdobe · 2025-04-29T08:35:57Z

Description

Improving the accessibility documentation of components.

Related issue(s)

SWC-390

Motivation and context

Documentation should provide more information and examples that demonstrate how to use the components accessibly.

How has this been tested?

Review overlay docs

Do the docs examples give enough context to test for accessibility?
Do the docs examples and text provide information on how to use the component accessibly?
If the component is to be used in the context of another component, do the examples include how that component is used accessibly in that context?
Are the docs headings logical and consistent across these components? You can use the WAVE browser extension's Structure tab to review heading structure.
Did it pass in Desktop?
Did it pass in Mobile?
Did it pass in iPad?

Screenshots (if appropriate)

Types of changes

Bug fix (non-breaking change which fixes an issue)
New feature (non-breaking change which adds functionality)
Breaking change (fix or feature that would cause existing functionality to change)
Chore (minor updates related to the tooling or maintenance of the repository, does not impact compiled assets)

Checklist

I have signed the Adobe Open Source CLA.
My code follows the code style of this project.
If my change required a change to the documentation, I have updated the documentation in this pull request.
I have read the CONTRIBUTING document.
I have added tests to cover my changes.
All new and existing tests passed.
I have reviewed at the Accessibility Practices for this feature, see: Aria Practices

Best practices

This repository uses conventional commit syntax for each commit message; note that the GitHub UI does not use this by default so be cautious when accepting suggested changes. Avoid the "Update branch" button on the pull request and opt instead for rebasing your branch against main.

changeset-bot · 2025-04-29T08:36:01Z

⚠️ No Changeset found

Latest commit: 2311a0e

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

github-actions · 2025-04-29T08:38:05Z

Branch preview

Review the following VRT differences

When a visual regression test fails (or has previously failed while working on this branch), its results can be found in the following URLs:

If the changes are expected, update the current_golden_images_cache hash in the circleci config to accept the new images. Instructions are included in that file.
If the changes are unexpected, you can investigate the cause of the differences and update the code accordingly.

github-actions · 2025-04-29T08:41:15Z

Tachometer results

Currently, no packages are changed by this PR...

nikkimk · 2025-04-29T12:44:59Z

packages/overlay/README.md


-### Modal
+##### Modal


Could we do each of the types in an <sp-tabs> element? It will save space and allow easier copmparison.

great idea!!

nikkimk · 2025-04-29T12:46:34Z

packages/overlay/README.md

+
+#### Keyboard Navigation
+
+-   ESC key closes overlays in reverse order of opening


Suggested change

- ESC key closes overlays in reverse order of opening

- <kbd>Escape</kbd> key closes overlays in reverse order of opening

nikkimk · 2025-04-29T12:47:30Z

packages/overlay/README.md

+</sp-overlay>
+```
+
+### Advanced Topics


Can we move advanced topics above Accessibility? That way consumers always know to look for Accessibility at the bottom.

nikkimk · 2025-04-29T12:48:07Z

packages/overlay/README.md


-### Overlay types
+#### Types


This is soooooooooo very helpful. Thanks for adding this section.

nikkimk · 2025-04-29T12:48:38Z

packages/overlay/README.md

-## Nested Overlays
+### Accessibility
+
+#### Nested Overlays


Thanks for adding this!

nikkimk · 2025-04-29T12:49:41Z

packages/overlay/README.md

+
+When a `triggerElement` is present, either through an ID reference established via the `trigger` attribute or by directly setting the `triggerElement` property, a chain on configuration begins:
+
+-   **if a `triggerInteraction` is available**, either through the `id@interaction` IDL on the `trigger` attribute or directly setting the `triggerInteraction` property, the `<sp-overlay>` will be bound to the resolved `triggerElement` via the `triggerInteraction` provided


I wonder if putting this information into a table instead of a list may make it easier to mentally process...

nikkimk · 2025-04-29T12:50:17Z

packages/overlay/README.md

@@ -493,3 +477,107 @@ WebKit clips `position: fixed` elements within containers that have all of:
 3. `z-index` greater than zero

 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.
+
+### Integration Patterns


Can we move this section before the Advanced section?

nikkimk · 2025-04-29T12:53:56Z

packages/overlay/overlay-trigger.md

+#### 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.
+


Do we want sp-tabs with examples of some of these placement options?

nikkimk · 2025-04-29T12:54:03Z

packages/overlay/overlay-trigger.md

+#### 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.
+


Do we want sp-tabs with examples of some of these type options?

castastrophe

A few suggestions for heading cases and wording but otherwise this is a great update with lots of improvements in it.

castastrophe · 2025-04-30T14:29:41Z

packages/overlay/imperative-api.md

@@ -60,33 +62,39 @@ type OverlayOptions = {
 };
 ```

-### delayed
+#### delayed


Suggested change

#### delayed

#### `delayed`

Should these attribute headings be in monospace? Just not sure of the convention used in other docs.

castastrophe · 2025-04-30T14:31:29Z

packages/overlay/imperative-api.md

-### 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).


Suggested change

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).

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).

Just updated the heading to sentence case. Same feedback for Advanced Topics below.

castastrophe · 2025-04-30T14:32:36Z

packages/overlay/overlay-trigger.md

-### 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.
+Here a default `<overlay-trigger>` manages content that is triggered by "click" and "hover" interactions.


Suggested change

Here a default `<overlay-trigger>` manages content that is triggered by "click" and "hover" interactions.

In this example, a default `<overlay-trigger>` manages content that is triggered by "click" and "hover" interactions.

castastrophe · 2025-04-30T14:33:47Z

packages/overlay/slottable-request.md


-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.


Nice! What a cool feature!

castastrophe · 2025-04-30T14:34:22Z

packages/overlay/slottable-request.md

@@ -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
+


A note to check title cases for this doc as well. Thanks!

castastrophe · 2025-04-30T14:35:19Z

packages/overlay/src/Overlay.ts

 * @fires sp-opened - announces that an overlay has completed any entry animations
 * @fires sp-closed - announce that an overlay has compelted any exit animations
 * @fires slottable-request - requests to add or remove slottable content
+ *
+ * @attr {string} placement - The placement of the overlay relative to the trigger


Great enhancement, thank you!

TarunAdobe force-pushed the ttomar/docs-overlay-a11y branch 3 times, most recently from d6f0e46 to 3cd6388 Compare April 29, 2025 09:20

nikkimk reviewed Apr 29, 2025

View reviewed changes

TarunAdobe force-pushed the ttomar/docs-overlay-a11y branch 3 times, most recently from ee09cc5 to 2faeeb2 Compare April 30, 2025 07:27

TarunAdobe marked this pull request as ready for review April 30, 2025 07:33

TarunAdobe requested a review from a team as a code owner April 30, 2025 07:33

TarunAdobe self-assigned this Apr 30, 2025

TarunAdobe force-pushed the ttomar/docs-overlay-a11y branch from 2faeeb2 to 499d562 Compare April 30, 2025 07:45

castastrophe approved these changes Apr 30, 2025

View reviewed changes

docs(overlay): a11y docs update

2311a0e

TarunAdobe force-pushed the ttomar/docs-overlay-a11y branch from 499d562 to 2311a0e Compare May 1, 2025 07:34

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs(overlay): a11y docs update #5409

docs(overlay): a11y docs update #5409

TarunAdobe commented Apr 29, 2025 •

edited

Loading

changeset-bot bot commented Apr 29, 2025 •

edited

Loading

github-actions bot commented Apr 29, 2025

github-actions bot commented Apr 29, 2025

nikkimk Apr 29, 2025

TarunAdobe Apr 30, 2025

nikkimk Apr 29, 2025

nikkimk Apr 29, 2025

nikkimk Apr 29, 2025

nikkimk Apr 29, 2025

nikkimk Apr 29, 2025

nikkimk Apr 29, 2025

nikkimk Apr 29, 2025

nikkimk Apr 29, 2025

TarunAdobe Apr 30, 2025

castastrophe left a comment

castastrophe Apr 30, 2025

castastrophe Apr 30, 2025

castastrophe Apr 30, 2025

castastrophe Apr 30, 2025

castastrophe Apr 30, 2025

castastrophe Apr 30, 2025


		#### Keyboard Navigation

		- ESC key closes overlays in reverse order of opening

	- ESC key closes overlays in reverse order of opening
	- <kbd>Escape</kbd> key closes overlays in reverse order of opening


		When a `triggerElement` is present, either through an ID reference established via the `trigger` attribute or by directly setting the `triggerElement` property, a chain on configuration begins:

		- if a `triggerInteraction` is available, either through the `id@interaction` IDL on the `trigger` attribute or directly setting the `triggerInteraction` property, the `<sp-overlay>` will be bound to the resolved `triggerElement` via the `triggerInteraction` provided

		#### 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.

	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).
	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).

	Here a default `<overlay-trigger>` manages content that is triggered by "click" and "hover" interactions.
	In this example, a default `<overlay-trigger>` manages content that is triggered by "click" and "hover" interactions.


		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.


		### Modal
		##### Modal

docs(overlay): a11y docs update #5409

Are you sure you want to change the base?

docs(overlay): a11y docs update #5409

Conversation

TarunAdobe commented Apr 29, 2025 • edited Loading

Description

Related issue(s)

Motivation and context

How has this been tested?

Screenshots (if appropriate)

Types of changes

Checklist

Best practices

changeset-bot bot commented Apr 29, 2025 • edited Loading

⚠️ No Changeset found

github-actions bot commented Apr 29, 2025

Branch preview

Review the following VRT differences

github-actions bot commented Apr 29, 2025

Tachometer results

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

castastrophe left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

TarunAdobe commented Apr 29, 2025 •

edited

Loading

changeset-bot bot commented Apr 29, 2025 •

edited

Loading