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,
+    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 slot!: HTMLSlotElement;
+
     public override focus(): void {
         const firstFocusable = firstFocusableIn(this);
         if (firstFocusable) {
@@ -81,6 +86,16 @@ 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
@@ -98,6 +113,74 @@ export class Tray extends SpectrumElement {
         `;
     }
 
+    /**
+     * 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.slot) {
+            this.needsDismissHelper = true;
+            return;
+        }
+
+        const slottedElements = this.slot.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', {
@@ -119,6 +202,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') &&
@@ -148,9 +237,13 @@ export class Tray extends SpectrumElement {
                 tabindex="-1"
                 @transitionend=${this.handleTrayTransitionend}
             >
-                ${this.dismissHelper}
-                <slot></slot>
-                ${this.dismissHelper}
+                ${!this.hasKeyboardDismissButton && this.needsDismissHelper
+                    ? this.dismissHelper
+                    : nothing}
+                <slot @slotchange=${this.handleSlotChange}></slot>
+                ${!this.hasKeyboardDismissButton && this.needsDismissHelper
+                    ? this.dismissHelper
+                    : nothing}
             </div>
         `;
     }