fix(tray): add visually hidden dismiss buttons

.changeset/every-worlds-push.md

@@ -0,0 +1,11 @@
+---
+'@spectrum-web-components/tray': minor
+---
+
+**Added**: Automatic dismiss button detection and visually-hidden helpers for screen reader accessibility
+
+- **Added**: `<sp-tray>` now automatically detects keyboard-accessible dismiss buttons (like `<sp-button>`, `<sp-close-button>`, or HTML `<button>` elements) in slotted content
+- **Added**: When no dismiss buttons are detected, the tray automatically renders visually-hidden dismiss buttons before and after its content to support mobile screen readers (particularly VoiceOver on iOS)
+- **Added**: New `has-keyboard-dismiss` boolean attribute to manually override auto-detection when slotted content has custom dismiss functionality that cannot be automatically detected
+- **Added**: Auto-detection recognizes `<sp-dialog dismissable>` and `<sp-dialog-wrapper dismissable>` components with built-in dismiss functionality in shadow DOM
+- **Enhanced**: Improved mobile screen reader accessibility by ensuring dismissal options are always available when appropriate

1st-gen/packages/tray/README.md

@@ -7,19 +7,19 @@
 [![See it on NPM!](https://img.shields.io/npm/v/@spectrum-web-components/tray?style=for-the-badge)](https://www.npmjs.com/package/@spectrum-web-components/tray)
 [![How big is this package in your project?](https://img.shields.io/bundlephobia/minzip/@spectrum-web-components/tray?style=for-the-badge)](https://bundlephobia.com/result?p=@spectrum-web-components/tray)
 
-```
+```zsh
 yarn add @spectrum-web-components/tray
 ```
 
 Import the side effectful registration of `<sp-tray>` via:
 
-```
+```js
 import '@spectrum-web-components/tray/sp-tray.js';
 ```
 
 When looking to leverage the `Tray` base class as a type and/or for extension purposes, do so via:
 
-```
+```js
 import { Tray } from '@spectrum-web-components/tray';
 ```
 
@@ -70,3 +70,80 @@ A tray has a single default `slot`.
 ### Accessibility
 
 `<sp-tray>` presents a page blocking experience and should be opened with the `Overlay` API using the `modal` interaction to ensure that the content appropriately manages the presence of other content in the tab order of the page and the availability of that content for a screen reader.
+
+#### Auto-detection behavior
+
+By default, `<sp-tray>` automatically detects whether its slotted content includes keyboard-accessible dismiss buttons (like `<sp-button>`, `<sp-close-button>`, or HTML `<button>` elements). When no dismiss buttons are found, the tray renders visually hidden dismiss buttons before and after its content to support mobile screen readers, particularly VoiceOver on iOS where users navigate through interactive elements sequentially.
+
+These built-in dismiss buttons:
+
+- Are visually hidden but accessible to screen readers
+- Allow mobile screen reader users to easily dismiss the tray from either the beginning or end of the content
+- Are labeled "Dismiss" for clear screen reader announcements
+
+This dismiss helper pattern is also implemented in the [`<sp-picker>`](https://opensource.adobe.com/spectrum-web-components/components/picker/) component, which uses the same approach when rendering menu content in a tray on mobile devices.
+
+<sp-tabs selected="auto" auto label="Dismiss helper examples">
+<sp-tab value="auto">Content has no buttons</sp-tab>
+<sp-tab-panel value="auto">
+
+This example shows the default behavior where the tray automatically detects that the menu content lacks dismiss buttons and renders visually hidden helpers. Screen readers will announce them as "Dismiss, button" and these helpers are keyboard accessible.
+
+```html
+<overlay-trigger type="modal">
+    <sp-button slot="trigger" variant="secondary">
+        Toggle menu content
+    </sp-button>
+    <sp-tray slot="click-content">
+        <sp-menu style="width: 100%">
+            <sp-menu-item>Deselect</sp-menu-item>
+            <sp-menu-item>Select Inverse</sp-menu-item>
+            <sp-menu-item>Feather...</sp-menu-item>
+            <sp-menu-item>Select and Mask...</sp-menu-item>
+        </sp-menu>
+    </sp-tray>
+</overlay-trigger>
+```
+
+</sp-tab-panel>
+<sp-tab value="with-buttons">Content has buttons</sp-tab>
+<sp-tab-panel value="with-buttons">
+
+This example shows auto-detection recognizing that the dialog has its own dismiss functionality, so no additional helpers are rendered.
+
+```html
+<overlay-trigger type="modal">
+    <sp-button slot="trigger" variant="secondary">
+        Toggle dialog content
+    </sp-button>
+    <sp-tray slot="click-content">
+        <sp-dialog size="s" dismissable>
+            <h2 slot="heading">New messages</h2>
+            You have 5 new messages.
+        </sp-dialog>
+    </sp-tray>
+</overlay-trigger>
+```
+
+</sp-tab-panel>
+<sp-tab value="force-hide">Manual override</sp-tab>
+<sp-tab-panel value="force-hide">
+
+Set `has-keyboard-dismiss` (or `has-keyboard-dismiss="true"`) to prevent the tray from rendering visually hidden dismiss helpers, even when no buttons are detected. You are then responsible for ensuring that your tray content has keyboard-accessible dismiss functionality.
+
+```html
+<overlay-trigger type="modal">
+    <sp-button slot="trigger" variant="secondary">
+        Toggle without helpers
+    </sp-button>
+    <sp-tray slot="click-content" has-keyboard-dismiss>
+        <p>
+            Custom content that should have custom dismiss functionality, even
+            though the tray didn't detect buttons in this slot.
+        </p>
+    </sp-tray>
+</overlay-trigger>
+```
+
+</sp-tab-panel>
+</sp-tabs>

1st-gen/packages/tray/src/Tray.ts

@@ -13,13 +13,15 @@
 import {
     CSSResultArray,
     html,
+    nothing,
     PropertyValues,
     SpectrumElement,
     TemplateResult,
 } from '@spectrum-web-components/base';
 import {
     property,
     query,
+    state,
 } from '@spectrum-web-components/base/src/decorators.js';
 import '@spectrum-web-components/underlay/sp-underlay.js';
 import { firstFocusableIn } from '@spectrum-web-components/shared/src/first-focusable-in.js';
@@ -55,6 +57,9 @@ export class Tray extends SpectrumElement {
     @query('.tray')
     private tray!: HTMLDivElement;
 
+    @query('slot')
+    private contentSlot!: HTMLSlotElement;
+
     public override focus(): void {
         const firstFocusable = firstFocusableIn(this);
         if (firstFocusable) {
@@ -81,6 +86,99 @@ export class Tray extends SpectrumElement {
         }
     }
 
+    /**
+     * When set, prevents the tray from rendering visually-hidden dismiss helpers.
+     * Use this if your slotted content has custom keyboard-accessible dismiss functionality
+     * that the auto-detection doesn't recognize.
+     *
+     * By default, the tray automatically detects buttons in slotted content.
+     */
+    @property({ type: Boolean, attribute: 'has-keyboard-dismiss' })
+    public hasKeyboardDismissButton = false;
+
+    /**
+     * Returns a visually hidden dismiss button for mobile screen reader accessibility.
+     * This button is placed before and after tray content to allow mobile screen reader
+     * users (particularly VoiceOver on iOS) to easily dismiss the overlay.
+     */
+    protected get dismissHelper(): TemplateResult {
+        return html`
+            <div class="visually-hidden">
+                <button aria-label="Dismiss" @click=${this.close}></button>
+            </div>
+        `;
+    }
+
+    /**
+     * Internal state tracking whether dismiss helpers are needed.
+     * Automatically updated when slotted content changes.
+     */
+    @state()
+    private needsDismissHelper = true;
+
+    /**
+     * Check if slotted content has keyboard-accessible dismiss buttons.
+     * Looks for buttons in light DOM and checks for known components with built-in dismiss.
+     */
+    private checkForDismissButtons(): void {
+        if (!this.contentSlot) {
+            this.needsDismissHelper = true;
+            return;
+        }
+
+        const slottedElements = this.contentSlot.assignedElements({
+            flatten: true,
+        });
+
+        if (slottedElements.length === 0) {
+            this.needsDismissHelper = true;
+            return;
+        }
+
+        const hasDismissButton = slottedElements.some((element) => {
+            // Check if element is a button itself
+            if (
+                element.tagName === 'SP-BUTTON' ||
+                element.tagName === 'SP-CLOSE-BUTTON' ||
+                element.tagName === 'BUTTON'
+            ) {
+                return true;
+            }
+
+            // Check for dismissable dialog (has built-in dismiss button in shadow DOM)
+            if (
+                element.tagName === 'SP-DIALOG' &&
+                element.hasAttribute('dismissable')
+            ) {
+                return true;
+            }
+
+            // Check for dismissable dialog-wrapper
+            if (
+                element.tagName === 'SP-DIALOG-WRAPPER' &&
+                element.hasAttribute('dismissable')
+            ) {
+                return true;
+            }
+
+            // Check for buttons in light DOM (won't see shadow DOM)
+            const buttons = element.querySelectorAll(
+                'sp-button, sp-close-button, button'
+            );
+            if (buttons.length > 0) {
+                return true;
+            }
+
+            return false;
+        });
+
+        this.needsDismissHelper = !hasDismissButton;
+    }
+
+    private handleSlotChange(): void {
+        this.checkForDismissButtons();
+    }
+
     private dispatchClosed(): void {
         this.dispatchEvent(
             new Event('close', {
@@ -102,6 +200,12 @@ export class Tray extends SpectrumElement {
         }
     }
 
+    protected override firstUpdated(changes: PropertyValues<this>): void {
+        super.firstUpdated(changes);
+        // Run initial button detection
+        this.checkForDismissButtons();
+    }
+
     protected override update(changes: PropertyValues<this>): void {
         if (
             changes.has('open') &&
@@ -131,7 +235,13 @@ export class Tray extends SpectrumElement {
                 tabindex="-1"
                 @transitionend=${this.handleTrayTransitionend}
             >
-                <slot></slot>
+                ${!this.hasKeyboardDismissButton && this.needsDismissHelper
+                    ? this.dismissHelper
+                    : nothing}
+                <slot @slotchange=${this.handleSlotChange}></slot>
+                ${!this.hasKeyboardDismissButton && this.needsDismissHelper
+                    ? this.dismissHelper
+                    : nothing}
             </div>
         `;
     }

1st-gen/packages/tray/src/tray.css

@@ -30,6 +30,7 @@ sp-underlay {
     overscroll-behavior: contain;
 }
 
+.visually-hidden,
 ::slotted(.visually-hidden) {
     border: 0;
     clip: rect(0, 0, 0, 0);