/
index.d.ts
256 lines (233 loc) · 10.7 KB
/
index.d.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
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
import { CheckOptions as TabbableCheckOptions } from 'tabbable';
declare module 'focus-trap' {
export type FocusTargetValue = HTMLElement | SVGElement | string;
export type FocusTargetValueOrFalse = FocusTargetValue | false;
/**
* A DOM node, a selector string (which will be passed to
* `document.querySelector()` to find the DOM node), or a function that
* returns a DOM node.
*/
export type FocusTarget = FocusTargetValue | (() => FocusTargetValue);
/**
* A DOM node, a selector string (which will be passed to
* `document.querySelector()` to find the DOM node), `false` to explicitly indicate
* an opt-out, or a function that returns a DOM node or `false`.
*/
export type FocusTargetOrFalse = FocusTargetValueOrFalse | (() => FocusTargetValueOrFalse);
type MouseEventToBoolean = (event: MouseEvent | TouchEvent) => boolean;
type KeyboardEventToBoolean = (event: KeyboardEvent) => boolean;
/** tabbable options supported by focus-trap. */
export interface FocusTrapTabbableOptions extends TabbableCheckOptions {
}
export interface Options {
/**
* A function that will be called **before** sending focus to the
* target element upon activation.
*/
onActivate?: () => void;
/**
* A function that will be called **after** focus has been sent to the
* target element upon activation.
*/
onPostActivate?: () => void;
/**
* A function that will be called immediately after the trap's state is updated to be paused.
*/
onPause?: () => void;
/**
* A function that will be called after the trap has been completely paused and is no longer
* managing/trapping focus.
*/
onPostPause?: () => void;
/**
* A function that will be called immediately after the trap's state is updated to be active
* again, but prior to updating its knowledge of what nodes are tabbable within its containers,
* and prior to actively managing/trapping focus.
*/
onUnpause?: () => void;
/**
* A function that will be called after the trap has been completely unpaused and is once
* again managing/trapping focus.
*/
onPostUnpause?: () => void;
/**
* A function for determining if it is safe to send focus to the focus trap
* or not.
*
* It should return a promise that only resolves once all the listed `containers`
* are able to receive focus.
*
* The purpose of this is to prevent early focus-trap activation on animated
* dialogs that fade in and out. When a dialog fades in, there is a brief delay
* between the activation of the trap and the trap element being focusable.
*/
checkCanFocusTrap?: (
containers: Array<HTMLElement | SVGElement>
) => Promise<void>;
/**
* A function that will be called **before** sending focus to the
* trigger element upon deactivation.
*/
onDeactivate?: () => void;
/**
* A function that will be called after the trap is deactivated, after `onDeactivate`.
* If `returnFocus` was set, it will be called **after** focus has been sent to the trigger
* element upon deactivation; otherwise, it will be called after deactivation completes.
*/
onPostDeactivate?: () => void;
/**
* A function for determining if it is safe to send focus back to the `trigger` element.
*
* It should return a promise that only resolves once `trigger` is focusable.
*
* The purpose of this is to prevent the focus being sent to an animated trigger element too early.
* If a trigger element fades in upon trap deactivation, there is a brief delay between the deactivation
* of the trap and when the trigger element is focusable.
*
* `trigger` will be either the node that had focus prior to the trap being activated,
* or the result of the `setReturnFocus` option, if configured.
*
* This handler is **not** called if the `returnFocusOnDeactivate` configuration option
* (or the `returnFocus` deactivation option) is falsy.
*/
checkCanReturnFocus?: (trigger: HTMLElement | SVGElement) => Promise<void>;
/**
* By default, when a focus trap is activated the first element in the
* focus trap's tab order will receive focus. With this option you can
* specify a different element to receive that initial focus, or use `false`
* for no initially focused element at all.
*
* NOTE: Setting this option to `false` (or a function that returns `false`)
* will prevent the `fallbackFocus` option from being used.
*
* Setting this option to `undefined` (or a function that returns `undefined`)
* will result in the default behavior.
*/
initialFocus?: FocusTargetOrFalse | undefined | (() => void);
/**
* By default, an error will be thrown if the focus trap contains no
* elements in its tab order. With this option you can specify a
* fallback element to programmatically receive focus if no other
* tabbable elements are found. For example, you may want a popover's
* `<div>` to receive focus if the popover's content includes no
* tabbable elements. *Make sure the fallback element has a negative
* `tabindex` so it can be programmatically focused.
*
* NOTE: If `initialFocus` is `false` (or a function that returns `false`),
* this function will not be called when the trap is activated, and no element
* will be initially focused. This function may still be called while the trap
* is active if things change such that there are no longer any tabbable nodes
* in the trap.
*/
fallbackFocus?: FocusTarget;
/**
* Default: `true`. If `false`, when the trap is deactivated,
* focus will *not* return to the element that had focus before activation.
*/
returnFocusOnDeactivate?: boolean;
/**
* By default, focus trap on deactivation will return to the element
* that was focused before activation.
*/
setReturnFocus?:
| FocusTargetValueOrFalse
| ((
nodeFocusedBeforeActivation: HTMLElement | SVGElement
) => FocusTargetValueOrFalse);
/**
* Default: `true`. If `false` or returns `false`, the `Escape` key will not trigger
* deactivation of the focus trap. This can be useful if you want
* to force the user to make a decision instead of allowing an easy
* way out. Note that if a function is given, it's only called if the ESC key
* was pressed.
*/
escapeDeactivates?: boolean | KeyboardEventToBoolean;
/**
* If `true` or returns `true`, a click outside the focus trap will
* deactivate the focus trap and allow the click event to do its thing (i.e.
* to pass-through to the element that was clicked). This option **takes
* precedence** over `allowOutsideClick` when it's set to `true`, causing
* that option to be ignored. Default: `false`.
*/
clickOutsideDeactivates?: boolean | MouseEventToBoolean;
/**
* If set and is or returns `true`, a click outside the focus trap will not
* be prevented, even when `clickOutsideDeactivates` is `false`. When
* `clickOutsideDeactivates` is `true`, this option is **ignored** (i.e.
* if it's a function, it will not be called). Use this option to control
* if (and even which) clicks are allowed outside the trap in conjunction
* with `clickOutsideDeactivates: false`. Default: `false`.
*/
allowOutsideClick?: boolean | MouseEventToBoolean;
/**
* By default, focus() will scroll to the element if not in viewport.
* It can produce unintended effects like scrolling back to the top of a modal.
* If set to `true`, no scroll will happen.
*/
preventScroll?: boolean;
/**
* Default: `true`. Delays the autofocus when the focus trap is activated.
* This prevents elements within the focusable element from capturing
* the event that triggered the focus trap activation.
*/
delayInitialFocus?: boolean;
/**
* Default: `window.document`. Document where the focus trap will be active.
* This allows to use FocusTrap in an iFrame context.
*/
document?: Document;
/**
* Specific tabbable options configurable on focus-trap.
*/
tabbableOptions?: FocusTrapTabbableOptions;
/**
* Define the global trap stack. This makes it possible to share the same stack
* in multiple instances of `focus-trap` in the same page such that
* auto-activation/pausing of traps is properly coordinated among all instances
* as activating a trap when another is already active should result in the other
* being auto-paused. By default, each instance will have its own internal stack,
* leading to conflicts if they each try to trap the focus at the same time.
*/
trapStack?: Array<FocusTrap>;
/**
* Determines if the given keyboard event is a "tab forward" event that will move
* the focus to the next trapped element in tab order. Defaults to the `TAB` key.
* Use this to override the trap's behavior if you want to use arrow keys to control
* keyboard navigation within the trap, for example. Also see `isKeyBackward()` option.
*/
isKeyForward?: KeyboardEventToBoolean;
/**
* Determines if the given keyboard event is a "tab backward" event that will move
* the focus to the previous trapped element in tab order. Defaults to the `SHIFT+TAB` key.
* Use this to override the trap's behavior if you want to use arrow keys to control
* keyboard navigation within the trap, for example. Also see `isKeyForward()` option.
*/
isKeyBackward?: KeyboardEventToBoolean;
}
type ActivateOptions = Pick<Options, 'onActivate' | 'onPostActivate' | 'checkCanFocusTrap'>;
type PauseOptions = Pick<Options, 'onPause' | 'onPostPause'>;
type UnpauseOptions = Pick<Options, 'onUnpause' | 'onPostUnpause'>;
interface DeactivateOptions extends Pick<Options, 'onDeactivate' | 'onPostDeactivate' | 'checkCanReturnFocus'> {
returnFocus?: boolean;
}
export interface FocusTrap {
active: boolean,
paused: boolean,
activate(activateOptions?: ActivateOptions): FocusTrap;
deactivate(deactivateOptions?: DeactivateOptions): FocusTrap;
pause(pauseOptions?: PauseOptions): FocusTrap;
unpause(unpauseOptions?: UnpauseOptions): FocusTrap;
updateContainerElements(containerElements: HTMLElement | SVGElement | string | Array<HTMLElement | SVGElement | string>): FocusTrap;
}
/**
* Returns a new focus trap on `element`.
*
* @param element
* The element to be the focus trap, or a selector that will be used to
* find the element.
*/
export function createFocusTrap(
element: HTMLElement | SVGElement | string | Array<HTMLElement | SVGElement | string>,
userOptions?: Options
): FocusTrap;
}