-
Notifications
You must be signed in to change notification settings - Fork 3.6k
/
focustracker.ts
131 lines (113 loc) · 3.55 KB
/
focustracker.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
/**
* @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
* For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
*/
/* global setTimeout, clearTimeout */
/**
* @module utils/focustracker
*/
import DomEmitterMixin from './dom/emittermixin.js';
import ObservableMixin from './observablemixin.js';
import CKEditorError from './ckeditorerror.js';
/**
* Allows observing a group of `Element`s whether at least one of them is focused.
*
* Used by the {@link module:core/editor/editor~Editor} in order to track whether the focus is still within the application,
* or were used outside of its UI.
*
* **Note** `focus` and `blur` listeners use event capturing, so it is only needed to register wrapper `Element`
* which contain other `focusable` elements. But note that this wrapper element has to be focusable too
* (have e.g. `tabindex="-1"`).
*
* Check out the {@glink framework/deep-dive/ui/focus-tracking "Deep dive into focus tracking"} guide to learn more.
*/
export default class FocusTracker extends DomEmitterMixin( ObservableMixin() ) {
/**
* True when one of the registered elements is focused.
*
* @readonly
* @observable
*/
declare public isFocused: boolean;
/**
* The currently focused element.
*
* While {@link #isFocused `isFocused`} remains `true`, the focus can
* move between different UI elements. This property tracks those
* elements and tells which one is currently focused.
*
* @readonly
* @observable
*/
declare public focusedElement: Element | null;
/**
* List of registered elements.
*
* @internal
*/
public _elements: Set<Element> = new Set();
/**
* Event loop timeout.
*/
private _nextEventLoopTimeout: ReturnType<typeof setTimeout> | null = null;
constructor() {
super();
this.set( 'isFocused', false );
this.set( 'focusedElement', null );
}
/**
* Starts tracking the specified element.
*/
public add( element: Element ): void {
if ( this._elements.has( element ) ) {
/**
* This element is already tracked by {@link module:utils/focustracker~FocusTracker}.
*
* @error focustracker-add-element-already-exist
*/
throw new CKEditorError( 'focustracker-add-element-already-exist', this );
}
this.listenTo( element, 'focus', () => this._focus( element ), { useCapture: true } );
this.listenTo( element, 'blur', () => this._blur(), { useCapture: true } );
this._elements.add( element );
}
/**
* Stops tracking the specified element and stops listening on this element.
*/
public remove( element: Element ): void {
if ( element === this.focusedElement ) {
this._blur();
}
if ( this._elements.has( element ) ) {
this.stopListening( element );
this._elements.delete( element );
}
}
/**
* Destroys the focus tracker by:
* - Disabling all event listeners attached to tracked elements.
* - Removing all tracked elements that were previously added.
*/
public destroy(): void {
this.stopListening();
}
/**
* Stores currently focused element and set {@link #isFocused} as `true`.
*/
private _focus( element: Element ): void {
clearTimeout( this._nextEventLoopTimeout! );
this.focusedElement = element;
this.isFocused = true;
}
/**
* Clears currently focused element and set {@link #isFocused} as `false`.
* This method uses `setTimeout` to change order of fires `blur` and `focus` events.
*/
private _blur(): void {
clearTimeout( this._nextEventLoopTimeout! );
this._nextEventLoopTimeout = setTimeout( () => {
this.focusedElement = null;
this.isFocused = false;
}, 0 );
}
}