Popover: Support WCAG - Dismissible (#32887)

Co-authored-by: Ruslan Farkhutdinov <ruslan.farkhutdinov@devexpress.com>

Author: Ruslan Farkhutdinov

packages/devextreme/js/__internal/ui/popover/m_popover.ts

@@ -1,7 +1,7 @@
 import positionUtils from '@js/common/core/animation/position';
 import { move } from '@js/common/core/animation/translator';
 import eventsEngine from '@js/common/core/events/core/events_engine';
-import { addNamespace } from '@js/common/core/events/utils';
+import { addNamespace, normalizeKeyName } from '@js/common/core/events/utils';
 import registerComponent from '@js/core/component_registrator';
 import domAdapter from '@js/core/dom_adapter';
 import { getPublicElement } from '@js/core/element';
@@ -47,6 +47,8 @@ const POSITION_FLIP_MAP = {
   center: 'center',
 };
 
+const ESC_KEY_NAME = 'escape';
+
 type PopoverTarget = string | dxElementWrapper | Element | undefined;
 
 export interface PopoverProperties extends Omit<Properties,
@@ -70,6 +72,8 @@ class Popover<
 
   _$arrow!: dxElementWrapper;
 
+  _documentEscapeKeyHandler!: (e: KeyboardEvent) => void;
+
   _timeouts!: Record<string, ReturnType<typeof setTimeout>>;
 
   _getDefaultOptions(): TProperties {
@@ -153,15 +157,46 @@ class Popover<
     super._init();
 
     this._renderArrow();
+    this._initEscapeKeyHandler();
     this._timeouts = {};
 
     this.$element().addClass(POPOVER_CLASS);
     this.$wrapper()?.addClass(POPOVER_WRAPPER_CLASS);
 
-    const { toolbarItems } = this.option();
+    const { toolbarItems, visible } = this.option();
 
     const isInteractive = toolbarItems?.length;
     this.setAria('role', isInteractive ? 'dialog' : 'tooltip');
+
+    if (visible) {
+      this._attachEscapeKeyHandler();
+    }
+  }
+
+  _initEscapeKeyHandler(): void {
+    this._documentEscapeKeyHandler = (e: KeyboardEvent): void => {
+      const { visible } = this.option();
+      const overlayStack = this._overlayStack();
+      const isTopOverlay = overlayStack[overlayStack.length - 1] === this;
+
+      if (normalizeKeyName(e) === ESC_KEY_NAME && visible && isTopOverlay) {
+        // eslint-disable-next-line @typescript-eslint/no-floating-promises
+        this.hide();
+      }
+    };
+  }
+
+  _attachEscapeKeyHandler(): void {
+    const eventName = addNamespace('keydown', this.NAME as string);
+
+    eventsEngine.off(domAdapter.getDocument(), eventName, this._documentEscapeKeyHandler);
+    eventsEngine.on(domAdapter.getDocument(), eventName, this._documentEscapeKeyHandler);
+  }
+
+  _detachEscapeKeyHandler(): void {
+    const eventName = addNamespace('keydown', this.NAME as string);
+
+    eventsEngine.off(domAdapter.getDocument(), eventName, this._documentEscapeKeyHandler);
   }
 
   _render(): void {
@@ -529,11 +564,17 @@ class Popover<
   }
 
   _clean(): void {
+    this._detachEscapeKeyHandler();
     this._detachEvents(this.option('target'));
     // @ts-expect-error ts-error
     super._clean.apply(this, arguments);
   }
 
+  _dispose(): void {
+    this._detachEscapeKeyHandler();
+    super._dispose();
+  }
+
   _optionChanged(args: OptionChanged<TProperties>): void {
     const { name, value, previousValue } = args;
     switch (name) {
@@ -565,6 +606,11 @@ class Popover<
         break;
       }
       case 'visible':
+        if (value) {
+          this._attachEscapeKeyHandler();
+        } else {
+          this._detachEscapeKeyHandler();
+        }
         this._clearEventTimeout(value ? 'show' : 'hide');
         super._optionChanged(args);
         break;

packages/devextreme/testing/tests/DevExpress.ui.widgets/popover.tests.js

@@ -3,6 +3,7 @@ import $ from 'jquery';
 import fixtures from '../../helpers/positionFixtures.js';
 import fx from 'common/core/animation/fx';
 import pointerMock from '../../helpers/pointerMock.js';
+import keyboardMock from '../../helpers/keyboardMock.js';
 import positionUtils from 'common/core/animation/position';
 import uiErrors from 'ui/widget/ui.errors';
 import Popover from 'ui/popover';
@@ -2320,7 +2321,7 @@ QUnit.module('disabled option', {
     });
 });
 
-QUnit.module('aria accessibility', {
+QUnit.module('accessibility', {
     beforeEach: function() {
         fixtures.simple.create();
     },
@@ -2343,4 +2344,63 @@ QUnit.module('aria accessibility', {
 
         assert.strictEqual($overlay.attr('role'), 'dialog');
     });
+
+    QUnit.test('should hide visible popover on esc press', function(assert) {
+        const popover = new Popover($('#what'), {
+            target: '#where',
+            visible: true,
+        });
+        const $target = $('#where').attr('tabindex', 0);
+        const keyboard = keyboardMock($target);
+
+        keyboard.keyDown('esc');
+
+        assert.strictEqual(popover.option('visible'), false, 'popover is hidden');
+    });
+
+    QUnit.test('should hide only topmost popover on esc press', function(assert) {
+        const $markup = $('<div id="popover1"></div>' +
+            '<div id="popover2"></div>' +
+            '<div id="target1" tabindex="0"></div>' +
+            '<div id="target2" tabindex="0"></div>')
+            .appendTo('body');
+
+
+        const bottomPopover = new Popover($('#popover1'), {
+            target: '#target1',
+            visible: true,
+        });
+        const topPopover = new Popover($('#popover2'), {
+            target: '#target2',
+            visible: true,
+        });
+
+        const keyboard = keyboardMock($('#target2'));
+
+        keyboard.keyDown('esc');
+
+        assert.strictEqual(topPopover.option('visible'), false, 'top popover is hidden');
+        assert.strictEqual(bottomPopover.option('visible'), true, 'bottom popover is still visible');
+
+        $markup.remove();
+    });
+
+    QUnit.test('should not call hide for hidden popover on esc press', function(assert) {
+        const popover = new Popover($('#what'), {
+            target: '#where',
+            visible: true,
+            animation: null,
+        });
+        const hideSpy = sinon.spy(popover, 'hide');
+        const $target = $('#where').attr('tabindex', 0);
+        const keyboard = keyboardMock($target);
+
+        popover.hide();
+        hideSpy.resetHistory();
+
+        keyboard.keyDown('esc');
+
+        assert.strictEqual(hideSpy.callCount, 0, 'hide is not called');
+        assert.strictEqual(popover.option('visible'), false, 'popover remains hidden');
+    });
 });

packages/devextreme/testing/tests/DevExpress.ui.widgets/tooltip.tests.js

@@ -3,6 +3,7 @@ import fx from 'common/core/animation/fx';
 import Tooltip from 'ui/tooltip';
 import renderer from 'core/renderer';
 import uiErrors from 'ui/widget/ui.errors';
+import keyboardMock from '../../helpers/keyboardMock.js';
 
 const TOOLTIP_CLASS = 'dx-tooltip';
 const TOOLTIP_WRAPPER_CLASS = 'dx-tooltip-wrapper';
@@ -162,7 +163,7 @@ QUnit.module('base z-index', () => {
     });
 });
 
-QUnit.module('aria accessibility', () => {
+QUnit.module('accessibility', () => {
     QUnit.test('role="tooltip" attribute should be added to tooltip', function(assert) {
         const $tooltip = $('#tooltip');
         new Tooltip($tooltip);
@@ -181,4 +182,17 @@ QUnit.module('aria accessibility', () => {
         assert.equal($target.attr('aria-describedby'), $overlay.attr('id'), 'aria-describedby and overlay\'s id are equal');
 
     });
+
+    QUnit.test('visible tooltip should be hidden on Escape key press', function(assert) {
+        const tooltip = new Tooltip($('#tooltip'), {
+            target: '#target',
+            visible: true,
+        });
+        const $target = $('#target').attr('tabindex', 0);
+        const keyboard = keyboardMock($target);
+
+        keyboard.keyDown('esc');
+
+        assert.strictEqual(tooltip.option('visible'), false, 'tooltip is hidden');
+    });
 });