feat(tray): expand API for dismissible behavior

- adds several properties and methods to tray API to support more
flexibile dismissible behavior.
- queries for keyboard-accessible dismiss buttons in the tray's slot
content
- adds a state property to track if dismiss buttons are needed
- adds manual override for dismissible behavior

Author: marissahuysentruyt

packages/tray/src/Tray.ts

@@ -13,13 +13,15 @@
 import {
     CSSResultArray,
     html,
+    nothing,
     PropertyValues,
     SpectrumElement,
     TemplateResult,
 } from '@spectrum-web-components/base';
 import {
     property,
     query,
+    queryAssignedElements,
 } 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';
@@ -81,6 +83,16 @@ export class Tray extends SpectrumElement {
         }
     }
 
+    /**
+     * Indicates whether the slotted content has keyboard-accessible dismiss functionality.
+     * When set, this overrides the automatic button detection behavior.
+     * - `true`: Content has dismiss buttons, don't render additional visually-hidden helpers
+     * - `false`: Content lacks dismiss buttons, always render visually-hidden helpers
+     * - `undefined` (default): Auto-detect by scanning slotted content for buttons
+     */
+    @property({ type: Boolean, attribute: 'has-keyboard-dismiss' })
+    public hasKeyboardDismissButton?: boolean;
+
     /**
      * 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
@@ -98,6 +110,59 @@ export class Tray extends SpectrumElement {
         `;
     }
 
+    /**
+     * Add a state property to track if dismiss buttons are needed
+     * Set to false if your tray content already includes keyboard-accessible dismiss buttons.
+     */
+    @property({ type: Boolean, attribute: false })
+    private needsDismissHelper = true;
+
+    // Track slotted content
+    @queryAssignedElements({ flatten: true })
+    private slottedContent!: HTMLElement[];
+
+    /**
+     * Determines whether to show visually-hidden dismiss helpers.
+     * Uses manual override if set, otherwise falls back to auto-detection.
+     */
+    private get shouldShowDismissHelper(): boolean {
+        // If explicitly set, use that value (inverted because true means "has buttons")
+        if (this.hasKeyboardDismissButton !== undefined) {
+            return !this.hasKeyboardDismissButton;
+        }
+        // Otherwise use auto-detection
+        return this.needsDismissHelper;
+    }
+
+    // Check if slotted content has keyboard-accessible dismiss buttons
+    private checkForDismissButtons(): void {
+        // Look for common dismiss button patterns
+        const hasDismissButton = this.slottedContent.some((element) => {
+            // Check for buttons at the top level
+            if (
+                element.tagName === 'SP-BUTTON' ||
+                element.tagName === 'SP-CLOSE-BUTTON' ||
+                element.tagName === 'BUTTON'
+            )
+                return true;
+
+            // Check for buttons within the slotted content
+            const buttons = element.querySelectorAll(
+                'sp-button, sp-close-button, button'
+            );
+            if (buttons.length > 0) return true;
+
+            return false;
+        });
+
+        this.needsDismissHelper = !hasDismissButton;
+    }
+
+    // Update when slot content changes
+    private handleSlotChange(): void {
+        this.checkForDismissButtons();
+    }
+
     private dispatchClosed(): void {
         this.dispatchEvent(
             new Event('close', {
@@ -148,9 +213,9 @@ export class Tray extends SpectrumElement {
                 tabindex="-1"
                 @transitionend=${this.handleTrayTransitionend}
             >
-                ${this.dismissHelper}
-                <slot></slot>
-                ${this.dismissHelper}
+                ${this.shouldShowDismissHelper ? this.dismissHelper : nothing}
+                <slot @slotchange=${this.handleSlotChange}></slot>
+                ${this.shouldShowDismissHelper ? this.dismissHelper : nothing}
             </div>
         `;
     }