Popover: focus management for dialog role

e2e/testcafe-devextreme/tests/dataGrid/common/keyboardNavigation/keyboardNavigation.functional.ts

@@ -4930,7 +4930,6 @@ test('Grids a11y: Fix the header filter and the column chooser focus issue and u
   const dataGrid = new DataGrid('#container');
   const filterIconElement = dataGrid.getHeaders().getHeaderRow(0).getHeaderCell(0).getFilterIcon();
   const headerFilter = new HeaderFilter();
-  const columnChooser = dataGrid.getColumnChooser();
   const columnChooserButton = dataGrid.getColumnChooserButton();
 
   await t
@@ -4942,7 +4941,7 @@ test('Grids a11y: Fix the header filter and the column chooser focus issue and u
     .ok()
     .click(columnChooserButton)
     .pressKey('tab tab tab')
-    .expect(columnChooser.content.focused)
+    .expect(Selector('.dx-closebutton').focused)
     .ok();
 })
   .before(async () => {

packages/devextreme/js/__internal/ui/lookup.ts

@@ -679,6 +679,7 @@ class Lookup extends DropDownList<LookupProperties> {
         hideOnParentScroll: true,
         _fixWrapperPosition: false,
         _overlayContentRole: 'dialog',
+        _preventDialogContainerFocus: true,
         width: this._isInitialOptionValue('dropDownOptions.width')
           ? (): number => getOuterWidth(this.$element()) as number
           : popupConfig.width,

packages/devextreme/js/__internal/ui/overlay/overlay.ts

@@ -992,14 +992,20 @@ class Overlay<
       const $currentElement = $elements?.eq(i) ?? null;
       const $reverseElement = $elements?.eq(elementsCount - i) ?? null;
 
-      // @ts-expect-error is should can get function as callback
-      if (!$first && $currentElement.is(selectors.tabbable)) {
-        $first = $currentElement;
+      if (!$first && $currentElement) {
+        // @ts-expect-error is should can get function as callback
+        const isTabbableAndNotOverlay = $currentElement?.not(`.${OVERLAY_CONTENT_CLASS}`).is(selectors.tabbable);
+        if (isTabbableAndNotOverlay) {
+          $first = $currentElement;
+        }
       }
 
-      // @ts-expect-error is should can get function as callback
-      if (!$last && $reverseElement.is(selectors.tabbable)) {
-        $last = $reverseElement;
+      if (!$last && $reverseElement) {
+        // @ts-expect-error is should can get function as callback
+        const isTabbableAndNotOverlay = $reverseElement?.not(`.${OVERLAY_CONTENT_CLASS}`).is(selectors.tabbable);
+        if (isTabbableAndNotOverlay) {
+          $last = $reverseElement;
+        }
       }
 
       if ($first && $last) {

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

@@ -111,6 +111,8 @@ export interface PopoverProperties extends Omit<Properties,
   _overlayContentRole?: string;
 
   _describeTarget?: boolean;
+
+  _preventDialogContainerFocus?: boolean;
 }
 class Popover<
   TProperties extends PopoverProperties = PopoverProperties,
@@ -266,6 +268,57 @@ class Popover<
   _syncAriaAttributes(): void {
     this.setAria('role', this._getEffectiveAriaRole());
     this._syncTargetAriaDescription();
+    this._syncFocusOptions();
+  }
+
+  _syncFocusOptions(): void {
+    if (this._getEffectiveAriaRole() === 'dialog' && !this.option('_preventDialogContainerFocus')) {
+      this._setOptionWithoutOptionChange('focusStateEnabled', true);
+      this._setOptionWithoutOptionChange('tabFocusLoopEnabled', true);
+    }
+  }
+
+  // Intentional no-op: Focus target logic is inherited from Widget,
+  // uses in Popup and do not need here.
+  _renderFocusTarget(): void {}
+
+  _getFocusTarget(): dxElementWrapper | null | undefined {
+    const $firstFocusableTarget = this._findTabbableBounds().$first;
+    if ($firstFocusableTarget?.length) {
+      return $firstFocusableTarget;
+    }
+
+    const $overlay = this.$overlayContent();
+    if ($overlay?.length) {
+      if ($overlay.attr('tabindex') !== '-1') {
+        $overlay.attr('tabindex', '-1');
+      }
+      return $overlay;
+    }
+
+    return null;
+  }
+
+  _focusTarget(): dxElementWrapper {
+    return this._getFocusTarget() ?? this.$overlayContent();
+  }
+
+  _restoreTargetFocus(): void {
+    const $target = this._getAriaDescriptionTargets();
+    const targetElement = $target.first().get(0);
+
+    if (targetElement && domAdapter.getBody().contains(targetElement)) {
+      // @ts-expect-error trigger should be typed on type 'EventsEngineType'
+      eventsEngine.trigger($target.first(), 'focus');
+    }
+  }
+
+  _forceFocusLost(): void {
+    if (this._getEffectiveAriaRole() === 'dialog') {
+      this._restoreTargetFocus();
+    } else {
+      super._forceFocusLost();
+    }
   }
 
   protected _getAriaRole(): string {
@@ -295,10 +348,15 @@ class Popover<
 
   _ensurePopoverContentId(): string {
     const $overlayContent = this.$overlayContent();
-    this._popoverContentId = this._popoverContentId
-      ?? $overlayContent.attr('id')
-      ?? `dx-${new Guid()}`;
-    this.setAria('id', this._popoverContentId, $overlayContent);
+    const existingId = $overlayContent.attr('id');
+
+    if (existingId) {
+      this._popoverContentId = existingId;
+      return existingId;
+    }
+
+    this._popoverContentId = this._popoverContentId ?? `dx-${new Guid()}`;
+    $overlayContent.attr('id', this._popoverContentId);
 
     return this._popoverContentId;
   }
@@ -479,7 +537,7 @@ class Popover<
   _detachHoverableOverlay(): void {
     const $overlayContent = this.$overlayContent();
 
-    if (!$overlayContent.length) {
+    if (!$overlayContent?.length) {
       return;
     }
 
@@ -882,14 +940,31 @@ class Popover<
   _clean(): void {
     const { target } = this.option();
 
+    const $overlayContent = this.$overlayContent();
+    if ($overlayContent?.length) {
+      const existingId = $overlayContent.attr('id');
+      if (existingId) {
+        this._popoverContentId = existingId;
+      }
+    }
+
     this._detachEscapeKeyHandler();
     this._detachEvents(target);
     this._detachHoverableOverlay();
 
     super._clean();
   }
 
+  _shouldResetActiveElement(): boolean {
+    const activeElement = domAdapter.getActiveElement();
+    return domAdapter.isNode(activeElement) && !!this._$content?.get(0)?.contains(activeElement);
+  }
+
   _dispose(): void {
+    const { visible } = this.option();
+    if (visible && this._shouldResetActiveElement() && this._getEffectiveAriaRole() === 'dialog') {
+      this._restoreTargetFocus();
+    }
     this._removeTargetAriaDescription();
     this._detachEscapeKeyHandler();
     super._dispose();

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

@@ -2994,4 +2994,135 @@ QUnit.module('accessibility', {
             assert.ok(instance.option('visible'), 'popover remains visible when pointer re-enters overlay before delay expires');
         });
     });
+
+    QUnit.module('dialog mode focus management and accessibility', {
+        beforeEach() {
+            this.clock = sinon.useFakeTimers();
+            this.$element = $('#what');
+            this.$target = $('#where');
+        },
+        afterEach() {
+            this.clock.restore();
+        }
+    }, () => {
+        QUnit.test('Popover in dialog mode should enable focusStateEnabled and tabFocusLoopEnabled on show', function(assert) {
+            const instance = new Popover(this.$element, {
+                target: this.$target,
+                toolbarItems: [{ text: 'OK' }],
+                visible: false,
+            });
+
+            instance.show();
+            this.clock.tick(0);
+
+            assert.strictEqual(instance.option('focusStateEnabled'), true, 'focusStateEnabled is enabled for dialog mode');
+            assert.strictEqual(instance.option('tabFocusLoopEnabled'), true, 'tabFocusLoopEnabled is enabled for dialog mode');
+        });
+
+        QUnit.test('Popover in dialog mode should move focus inside on show and restore focus to target when hidden', function(assert) {
+            this.$target.attr('tabindex', 0).focus();
+            assert.strictEqual(document.activeElement, this.$target.get(0), 'target is focused before show');
+
+            const instance = new Popover(this.$element, {
+                target: this.$target,
+                toolbarItems: [{ widget: 'dxButton', options: { text: 'OK' } }],
+                visible: false,
+            });
+
+            instance.show();
+            this.clock.tick(500);
+
+            const isFocusInside = $(document.activeElement).closest(wrapper()).length > 0;
+            assert.strictEqual(isFocusInside, true, 'focus moved inside popover wrapper on show');
+
+            instance.hide();
+            this.clock.tick(500);
+
+            assert.strictEqual(document.activeElement, this.$target.get(0), 'focus is restored to target after hide');
+        });
+
+        QUnit.test('Popover in dialog mode should loop focus from last to first element on tab keypress', function(assert) {
+            const instance = new Popover(this.$element, {
+                target: this.$target,
+                toolbarItems: [
+                    { widget: 'dxButton', options: { text: 'OK' } },
+                    { widget: 'dxButton', options: { text: 'Cancel' } }
+                ],
+                visible: false,
+            });
+
+            instance.show();
+            this.clock.tick(500);
+
+            const bounds = instance._findTabbableBounds();
+            const firstFocusable = bounds.$first.get(0);
+            const lastFocusable = bounds.$last.get(0);
+
+            $(lastFocusable).focus();
+
+            const tabEvent = $.Event('keydown', { key: 'Tab' });
+            $(document).trigger(tabEvent);
+
+            assert.strictEqual(document.activeElement, firstFocusable, 'focus looped to the first element');
+        });
+
+        QUnit.test('Popover in dialog mode should loop focus from first to last element on shift+tab keypress', function(assert) {
+            const instance = new Popover(this.$element, {
+                target: this.$target,
+                toolbarItems: [
+                    { widget: 'dxButton', options: { text: 'OK', } },
+                    { widget: 'dxButton', options: { text: 'Cancel', } }
+                ],
+                visible: false,
+            });
+
+            instance.show();
+            this.clock.tick(500);
+
+            const bounds = instance._findTabbableBounds();
+            const firstFocusable = bounds.$first.get(0);
+            const lastFocusable = bounds.$last.get(0);
+
+            $(firstFocusable).focus();
+
+            const shiftTabEvent = $.Event('keydown', { key: 'Tab', shiftKey: true });
+            $(document).trigger(shiftTabEvent);
+
+            assert.strictEqual(document.activeElement, lastFocusable, 'focus looped to the last element');
+        });
+
+        QUnit.test('Popover in dialog mode should focus first tabbable element inside content on show', function(assert) {
+            const instance = new Popover(this.$element, {
+                target: this.$target,
+                contentTemplate: function() {
+                    return $('<div><input id="input1" /><input id="input2" /></div>');
+                },
+                toolbarItems: [{ text: 'OK' }],
+                visible: false,
+            });
+
+            instance.show();
+            this.clock.tick(500);
+
+            const $input1 = $('#input1');
+            assert.strictEqual(document.activeElement, $input1.get(0), 'first tabbable element is focused');
+        });
+
+        QUnit.test('Popover in dialog mode should restore focus to target on dispose when visible', function(assert) {
+            this.$target.attr('tabindex', 0).focus();
+
+            const instance = new Popover(this.$element, {
+                target: this.$target,
+                toolbarItems: [{ text: 'OK' }],
+                visible: false,
+            });
+
+            instance.show();
+
+            instance.dispose();
+
+            assert.strictEqual(document.activeElement, this.$target.get(0), 'focus is restored to target after dispose');
+        });
+    });
 });
+