Skip to content

Commit 9f27a48

Browse files
authored
refactor: extract overlay focus restoration logic into a controller (#5951)
1 parent 12e6ee2 commit 9f27a48

9 files changed

Lines changed: 145 additions & 43 deletions

‎packages/a11y-base/index.d.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@ export {
1212
isKeyboardActive,
1313
} from './src/focus-utils.js';
1414
export { FocusTrapController } from './src/focus-trap-controller.js';
15+
export { FocusRestorationController } from './src/focus-restoration-controller.js';
1516
export { KeyboardDirectionMixin } from './src/keyboard-direction-mixin.js';
1617
export { KeyboardMixin } from './src/keyboard-mixin.js';
1718
export { ListMixin } from './src/list-mixin.js';

‎packages/a11y-base/index.js‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@ export { DisabledMixin } from './src/disabled-mixin.js';
55
export { FieldAriaController } from './src/field-aria-controller.js';
66
export { FocusMixin } from './src/focus-mixin.js';
77
export { FocusTrapController } from './src/focus-trap-controller.js';
8+
export { FocusRestorationController } from './src/focus-restoration-controller.js';
89
export {
910
getFocusableElements,
1011
isElementFocusable,
Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
/**
2+
* @license
3+
* Copyright (c) 2021 - 2023 Vaadin Ltd.
4+
* This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
5+
*/
6+
import type { Constructor } from '@open-wc/dedupe-mixin';
7+
8+
/**
9+
* A controller for saving a focused node and restoring focus to it later.
10+
*/
11+
export declare function FocusRestorationController<T extends Constructor<HTMLElement>>(
12+
base: T,
13+
): Constructor<FocusRestorationControllerClass> & T;
14+
15+
export declare class FocusRestorationControllerClass {
16+
/**
17+
* Saves the given node as a target for restoring focus to
18+
* when `restoreFocus()` is called. If no node is provided,
19+
* the currently focused node in the DOM is saved as a target.
20+
*/
21+
saveFocus(node: Node | null | undefined): void;
22+
23+
/**
24+
* Restores focus to the target node that was saved previously with `saveFocus()`.
25+
*/
26+
restoreFocus(): void;
27+
}
Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
/**
2+
* @license
3+
* Copyright (c) 2021 - 2023 Vaadin Ltd.
4+
* This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
5+
*/
6+
import { getDeepActiveElement } from './focus-utils.js';
7+
8+
/**
9+
* A controller for saving a focused node and restoring focus to it later.
10+
*/
11+
export class FocusRestorationController {
12+
/**
13+
* Saves the given node as a target for restoring focus to
14+
* when `restoreFocus()` is called. If no node is provided,
15+
* the currently focused node in the DOM is saved as a target.
16+
*
17+
* @param {Node | null | undefined} focusNode
18+
*/
19+
saveFocus(focusNode) {
20+
this.focusNode = focusNode || getDeepActiveElement();
21+
}
22+
23+
/**
24+
* Restores focus to the target node that was saved previously with `saveFocus()`.
25+
*/
26+
restoreFocus() {
27+
const focusNode = this.focusNode;
28+
if (!focusNode) {
29+
return;
30+
}
31+
32+
if (getDeepActiveElement() === document.body) {
33+
// In Firefox and Safari, focusing the node synchronously
34+
// doesn't work as expected when the overlay is closing on outside click.
35+
// These browsers force focus to move to the body element and retain it
36+
// there until the next event loop iteration.
37+
setTimeout(() => focusNode.focus());
38+
} else {
39+
focusNode.focus();
40+
}
41+
42+
this.focusNode = null;
43+
}
44+
}
Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
import { expect } from '@esm-bundle/chai';
2+
import { aTimeout, fixtureSync, outsideClick } from '@vaadin/testing-helpers';
3+
import { FocusRestorationController } from '../src/focus-restoration-controller.js';
4+
import { getDeepActiveElement } from '../src/focus-utils.js';
5+
6+
describe('focus-restoration-controller', () => {
7+
let controller, button1, button2;
8+
9+
beforeEach(() => {
10+
controller = new FocusRestorationController();
11+
12+
const wrapper = fixtureSync(`
13+
<div>
14+
<button>Button 1</button>
15+
<button>Button 2</button>
16+
</div>
17+
`);
18+
19+
[button1, button2] = wrapper.children;
20+
});
21+
22+
it('should restore focus to the previously focused node by default', () => {
23+
button1.focus();
24+
controller.saveFocus();
25+
button2.focus();
26+
controller.restoreFocus();
27+
expect(getDeepActiveElement()).to.equal(button1);
28+
});
29+
30+
it('should restore focus to a specific node when provided', () => {
31+
button1.focus();
32+
controller.saveFocus(button2);
33+
controller.restoreFocus();
34+
expect(getDeepActiveElement()).to.equal(button2);
35+
});
36+
37+
it('should restore focus asynchronously if an outside click happened in between', async () => {
38+
button1.focus();
39+
controller.saveFocus();
40+
outsideClick();
41+
controller.restoreFocus();
42+
expect(getDeepActiveElement()).to.equal(document.body);
43+
await aTimeout(0);
44+
expect(getDeepActiveElement()).to.equal(button1);
45+
});
46+
47+
it('should not restore focus if no node was saved', () => {
48+
button1.focus();
49+
controller.restoreFocus();
50+
expect(getDeepActiveElement()).to.equal(button1);
51+
});
52+
53+
it('should not restore focus again if it was already restored', () => {
54+
button1.focus();
55+
controller.saveFocus();
56+
controller.restoreFocus();
57+
button2.focus();
58+
controller.restoreFocus();
59+
expect(getDeepActiveElement()).to.equal(button2);
60+
});
61+
});

‎packages/overlay/src/vaadin-overlay-focus-mixin.d.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -36,9 +36,9 @@ export declare class OverlayFocusMixinClass {
3636
protected _resetFocus(): void;
3737

3838
/**
39-
* Store previously focused node when the overlay starts to open.
39+
* Save the previously focused node when the overlay starts to open.
4040
*/
41-
protected _storeFocus(): void;
41+
protected _saveFocus(): void;
4242

4343
/**
4444
* Trap focus within the overlay after opening has completed.

‎packages/overlay/src/vaadin-overlay-focus-mixin.js‎

Lines changed: 7 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@
44
* This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
55
*/
66
import { AriaModalController } from '@vaadin/a11y-base/src/aria-modal-controller.js';
7+
import { FocusRestorationController } from '@vaadin/a11y-base/src/focus-restoration-controller.js';
78
import { FocusTrapController } from '@vaadin/a11y-base/src/focus-trap-controller.js';
89
import { getDeepActiveElement } from '@vaadin/a11y-base/src/focus-utils.js';
910
import { ControllerMixin } from '@vaadin/component-base/src/controller-mixin.js';
@@ -51,6 +52,7 @@ export const OverlayFocusMixin = (superClass) =>
5152

5253
this.__ariaModalController = new AriaModalController(this);
5354
this.__focusTrapController = new FocusTrapController(this);
55+
this.__focusRestorationController = new FocusRestorationController();
5456
}
5557

5658
/** @protected */
@@ -59,6 +61,7 @@ export const OverlayFocusMixin = (superClass) =>
5961

6062
this.addController(this.__ariaModalController);
6163
this.addController(this.__focusTrapController);
64+
this.addController(this.__focusRestorationController);
6265
}
6366

6467
/**
@@ -73,18 +76,18 @@ export const OverlayFocusMixin = (superClass) =>
7376
}
7477

7578
if (this.restoreFocusOnClose && this._shouldRestoreFocus()) {
76-
this.__restoreFocus();
79+
this.__focusRestorationController.restoreFocus();
7780
}
7881
}
7982

8083
/**
81-
* Store previously focused node when the overlay starts to open.
84+
* Save the previously focused node when the overlay starts to open.
8285
*
8386
* @protected
8487
*/
85-
_storeFocus() {
88+
_saveFocus() {
8689
if (this.restoreFocusOnClose) {
87-
this.__storeFocus();
90+
this.__focusRestorationController.saveFocus(this.restoreFocusNode);
8891
}
8992
}
9093

@@ -136,30 +139,4 @@ export const OverlayFocusMixin = (superClass) =>
136139
}
137140
return n === this;
138141
}
139-
140-
/** @private */
141-
__storeFocus() {
142-
// Store the focused node.
143-
this.__restoreFocusNode = getDeepActiveElement();
144-
}
145-
146-
/** @private */
147-
__restoreFocus() {
148-
// Use restoreFocusNode if specified, otherwise fallback to the node
149-
// which was focused before opening the overlay.
150-
const restoreFocusNode = this.restoreFocusNode || this.__restoreFocusNode;
151-
if (restoreFocusNode) {
152-
if (getDeepActiveElement() === document.body) {
153-
// In Firefox and Safari, focusing the restoreFocusNode synchronously
154-
// doesn't work as expected when the overlay is closing on outside click.
155-
// These browsers force focus to move to the body element and retain it
156-
// there until the next event loop iteration.
157-
setTimeout(() => restoreFocusNode.focus());
158-
} else {
159-
restoreFocusNode.focus();
160-
}
161-
162-
this.__restoreFocusNode = null;
163-
}
164-
}
165142
};

‎packages/overlay/src/vaadin-overlay.js‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -431,7 +431,7 @@ class Overlay extends OverlayStackMixin(OverlayFocusMixin(ThemableMixin(DirMixin
431431
/** @private */
432432
_openedChanged(opened, wasOpened) {
433433
if (opened) {
434-
this._storeFocus();
434+
this._saveFocus();
435435

436436
this._animatedOpening();
437437

‎packages/overlay/test/restore-focus.test.js‎

Lines changed: 1 addition & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
import { expect } from '@esm-bundle/chai';
2-
import { aTimeout, fixtureSync, nextRender, outsideClick } from '@vaadin/testing-helpers';
2+
import { fixtureSync, nextRender } from '@vaadin/testing-helpers';
33
import '../src/vaadin-overlay.js';
44
import { html, PolymerElement } from '@polymer/polymer/polymer-element.js';
55
import { getDeepActiveElement } from '@vaadin/a11y-base/src/focus-utils.js';
@@ -114,15 +114,6 @@ describe('restore focus', () => {
114114
expect(getDeepActiveElement()).to.equal(focusable);
115115
});
116116

117-
it('should restore focus asynchronously on outside click', async () => {
118-
focusInput.focus();
119-
overlay.opened = true;
120-
await nextRender();
121-
outsideClick();
122-
await aTimeout(0);
123-
expect(getDeepActiveElement()).to.equal(focusInput);
124-
});
125-
126117
it('should not restore focus on close if focus was moved outside overlay', async () => {
127118
focusInput.focus();
128119
overlay.opened = true;

0 commit comments

Comments
 (0)