feat: add events for backdrop click and detail Escape press (#9062)

web-padawan · web-flow · commit fac6784e0752 · 2025-05-07T15:38:47.000+03:00
diff --git a/packages/master-detail-layout/src/vaadin-master-detail-layout.d.ts b/packages/master-detail-layout/src/vaadin-master-detail-layout.d.ts
@@ -8,6 +8,14 @@ import { ResizeMixin } from '@vaadin/component-base/src/resize-mixin.js';
 import { SlotStylesMixin } from '@vaadin/component-base/src/slot-styles-mixin.js';
 import { ThemableMixin } from '@vaadin/vaadin-themable-mixin/vaadin-themable-mixin.js';
 
+export interface MasterDetailLayoutCustomEventMap {
+  'backdrop-click': Event;
+
+  'detail-escape-press': Event;
+}
+
+export interface MasterDetailLayoutEventMap extends HTMLElementEventMap, MasterDetailLayoutCustomEventMap {}
+
 /**
  * `<vaadin-master-detail-layout>` is a web component for building UIs with a master
  * (or primary) area and a detail (or secondary) area that is displayed next to, or
@@ -41,6 +49,9 @@ import { ThemableMixin } from '@vaadin/vaadin-themable-mixin/vaadin-themable-mix
  * `stack`        | Set when the layout is using the stack mode.
  *
  * See [Styling Components](https://vaadin.com/docs/latest/styling/styling-components) documentation.
+ *
+ * @fires {CustomEvent} backdrop-click - Fired when the user clicks the backdrop in the overlay mode.
+ * @fires {CustomEvent} detail-escape-press - Fired when the user presses Escape in the detail area.
  */
 declare class MasterDetailLayout extends SlotStylesMixin(ResizeMixin(ThemableMixin(ElementMixin(HTMLElement)))) {
   /**
@@ -128,6 +139,18 @@ declare class MasterDetailLayout extends SlotStylesMixin(ResizeMixin(ThemableMix
    * @attr {boolean} no-animation
    */
   noAnimation: boolean;
+
+  addEventListener<K extends keyof MasterDetailLayoutEventMap>(
+    type: K,
+    listener: (this: MasterDetailLayout, ev: MasterDetailLayoutEventMap[K]) => void,
+    options?: AddEventListenerOptions | boolean,
+  ): void;
+
+  removeEventListener<K extends keyof MasterDetailLayoutEventMap>(
+    type: K,
+    listener: (this: MasterDetailLayout, ev: MasterDetailLayoutEventMap[K]) => void,
+    options?: EventListenerOptions | boolean,
+  ): void;
 }
 
 declare global {
diff --git a/packages/master-detail-layout/src/vaadin-master-detail-layout.js b/packages/master-detail-layout/src/vaadin-master-detail-layout.js
@@ -47,6 +47,9 @@ import { transitionStyles } from './vaadin-master-detail-layout-transition-style
  *
  * See [Styling Components](https://vaadin.com/docs/latest/styling/styling-components) documentation.
  *
+ * @fires {CustomEvent} backdrop-click - Fired when the user clicks the backdrop in the overlay mode.
+ * @fires {CustomEvent} detail-escape-press - Fired when the user presses Escape in the detail area.
+ *
  * @customElement
  * @extends HTMLElement
  * @mixes ThemableMixin
@@ -385,7 +388,7 @@ class MasterDetailLayout extends SlotStylesMixin(ResizeMixin(ElementMixin(Themab
   /** @protected */
   render() {
     return html`
-      <div part="backdrop"></div>
+      <div part="backdrop" @click="${this.__onBackdropClick}"></div>
       <div id="master" part="master" ?inert="${this._hasDetail && this._overlay && this.containment === 'layout'}">
         <slot></slot>
       </div>
@@ -394,6 +397,7 @@ class MasterDetailLayout extends SlotStylesMixin(ResizeMixin(ElementMixin(Themab
         part="detail"
         role="${this._overlay || this._stack ? 'dialog' : nothing}"
         aria-modal="${this._overlay && this.containment === 'viewport' ? 'true' : nothing}"
+        @keydown="${this.__onDetailKeydown}"
       >
         <slot name="detail" @slotchange="${this.__onDetailSlotChange}"></slot>
       </div>
@@ -417,6 +421,20 @@ class MasterDetailLayout extends SlotStylesMixin(ResizeMixin(ElementMixin(Themab
     }
   }
 
+  /** @private */
+  __onBackdropClick() {
+    this.dispatchEvent(new CustomEvent('backdrop-click'));
+  }
+
+  /** @private */
+  __onDetailKeydown(event) {
+    if (event.key === 'Escape') {
+      // Prevent firing on parent layout when using nested layouts
+      event.stopPropagation();
+      this.dispatchEvent(new CustomEvent('detail-escape-press'));
+    }
+  }
+
   /**
    * @protected
    * @override
@@ -655,6 +673,16 @@ class MasterDetailLayout extends SlotStylesMixin(ResizeMixin(ElementMixin(Themab
     this.__transition = null;
     this.__resolveUpdateCallback = null;
   }
+
+  /**
+   * @event backdrop-click
+   * Fired when the user clicks the backdrop in the overlay mode.
+   */
+
+  /**
+   * @event detail-escape-press
+   * Fired when the user presses Escape in the detail area.
+   */
 }
 
 defineCustomElement(MasterDetailLayout);
diff --git a/packages/master-detail-layout/test/events.test.js b/packages/master-detail-layout/test/events.test.js
@@ -0,0 +1,125 @@
+import { expect } from '@vaadin/chai-plugins';
+import { resetMouse, sendKeys, sendMouseToElement } from '@vaadin/test-runner-commands';
+import { fixtureSync, nextRender } from '@vaadin/testing-helpers';
+import sinon from 'sinon';
+import '../src/vaadin-master-detail-layout.js';
+import './helpers/master-content.js';
+import './helpers/detail-content.js';
+
+window.Vaadin ||= {};
+window.Vaadin.featureFlags ||= {};
+window.Vaadin.featureFlags.masterDetailLayoutComponent = true;
+
+describe('events', () => {
+  let layout;
+
+  describe('default', () => {
+    beforeEach(async () => {
+      layout = fixtureSync(`
+        <vaadin-master-detail-layout>
+          <master-content></master-content>
+          <detail-content slot="detail"></detail-content>
+        </vaadin-master-detail-layout>
+      `);
+      await nextRender();
+    });
+
+    describe('backdrop click', () => {
+      afterEach(async () => {
+        await resetMouse();
+      });
+
+      it('should fire backdrop-click event on backdrop click in overlay mode', async () => {
+        layout.forceOverlay = true;
+
+        const spy = sinon.spy();
+        layout.addEventListener('backdrop-click', spy);
+
+        const backdrop = layout.shadowRoot.querySelector('[part="backdrop"]');
+        await sendMouseToElement({ type: 'click', element: backdrop });
+
+        expect(spy).to.be.calledOnce;
+      });
+    });
+
+    describe('Escape press', () => {
+      let detail, focusable;
+
+      beforeEach(() => {
+        detail = layout.querySelector('[slot="detail"]');
+        focusable = detail.shadowRoot.querySelector('input');
+      });
+
+      it('should fire detail-escape-press event on pressing Escape in split mode', async () => {
+        const spy = sinon.spy();
+        layout.addEventListener('detail-escape-press', spy);
+
+        focusable.focus();
+        await sendKeys({ press: 'Escape' });
+
+        expect(spy).to.be.calledOnce;
+      });
+
+      it('should fire detail-escape-press event on pressing Escape in overlay mode', async () => {
+        layout.forceOverlay = true;
+
+        const spy = sinon.spy();
+        layout.addEventListener('detail-escape-press', spy);
+
+        focusable.focus();
+        await sendKeys({ press: 'Escape' });
+
+        expect(spy).to.be.calledOnce;
+      });
+
+      it('should fire detail-escape-press event on pressing Escape in stack mode', async () => {
+        layout.forceOverlay = true;
+        layout.stackOverlay = true;
+
+        const spy = sinon.spy();
+        layout.addEventListener('detail-escape-press', spy);
+
+        focusable.focus();
+        await sendKeys({ press: 'Escape' });
+
+        expect(spy).to.be.calledOnce;
+      });
+    });
+  });
+
+  describe('nested', () => {
+    let layout, nested;
+
+    beforeEach(async () => {
+      layout = fixtureSync(`
+        <vaadin-master-detail-layout>
+          <div>Master</div>
+          <vaadin-master-detail-layout slot="detail">
+            <div>Nested master</div>
+            <div slot="detail">
+              <input />
+            </div>
+          </vaadin-master-detail-layout>
+        </vaadin-master-detail-layout>
+      `);
+      await nextRender();
+      nested = layout.querySelector('[slot="detail"]');
+    });
+
+    it('should not fire detail-escape-press event on parent layout from nested detail', async () => {
+      const parentSpy = sinon.spy();
+      const nestedSpy = sinon.spy();
+
+      layout.addEventListener('detail-escape-press', parentSpy);
+      nested.addEventListener('detail-escape-press', nestedSpy);
+
+      const focusable = nested.querySelector('input');
+      focusable.focus();
+
+      await sendKeys({ press: 'Escape' });
+
+      expect(nestedSpy).to.be.calledOnce;
+      expect(parentSpy).to.be.not.called;
+    });
+  });
+});
diff --git a/packages/master-detail-layout/test/typings/master-detail-layout.types.ts b/packages/master-detail-layout/test/typings/master-detail-layout.types.ts
@@ -19,3 +19,12 @@ assertType<'horizontal' | 'vertical'>(layout.orientation);
 assertType<boolean>(layout.forceOverlay);
 assertType<boolean>(layout.stackOverlay);
 assertType<boolean>(layout.noAnimation);
+
+// Events
+layout.addEventListener('backdrop-click', (event) => {
+  assertType<Event>(event);
+});
+
+layout.addEventListener('detail-escape-press', (event) => {
+  assertType<Event>(event);
+});
