3 * Manages page tabbing modifications made by modules.
7 * Allow modules to respond to the constrain event.
9 * @event drupalTabbingConstrained
13 * Allow modules to respond to the tabbingContext release event.
15 * @event drupalTabbingContextReleased
19 * Allow modules to respond to the constrain event.
21 * @event drupalTabbingContextActivated
25 * Allow modules to respond to the constrain event.
27 * @event drupalTabbingContextDeactivated
30 (function ($, Drupal) {
32 * Provides an API for managing page tabbing order modifications.
34 * @constructor Drupal~TabbingManager
36 function TabbingManager() {
38 * Tabbing sets are stored as a stack. The active set is at the top of the
39 * stack. We use a JavaScript array as if it were a stack; we consider the
40 * first element to be the bottom and the last element to be the top. This
41 * allows us to use JavaScript's built-in Array.push() and Array.pop()
44 * @type {Array.<Drupal~TabbingContext>}
50 * Add public methods to the TabbingManager class.
52 $.extend(TabbingManager.prototype, /** @lends Drupal~TabbingManager# */{
55 * Constrain tabbing to the specified set of elements only.
57 * Makes elements outside of the specified set of elements unreachable via
60 * @param {jQuery} elements
61 * The set of elements to which tabbing should be constrained. Can also
62 * be a jQuery-compatible selector string.
64 * @return {Drupal~TabbingContext}
65 * The TabbingContext instance.
67 * @fires event:drupalTabbingConstrained
70 // Deactivate all tabbingContexts to prepare for the new constraint. A
71 // tabbingContext instance will only be reactivated if the stack is
72 // unwound to it in the _unwindStack() method.
73 const il = this.stack.length;
74 for (let i = 0; i < il; i++) {
75 this.stack[i].deactivate();
78 // The "active tabbing set" are the elements tabbing should be constrained
80 const $elements = $(elements).find(':tabbable').addBack(':tabbable');
82 const tabbingContext = new TabbingContext({
83 // The level is the current height of the stack before this new
84 // tabbingContext is pushed on top of the stack.
85 level: this.stack.length,
86 $tabbableElements: $elements,
89 this.stack.push(tabbingContext);
91 // Activates the tabbingContext; this will manipulate the DOM to constrain
93 tabbingContext.activate();
95 // Allow modules to respond to the constrain event.
96 $(document).trigger('drupalTabbingConstrained', tabbingContext);
98 return tabbingContext;
102 * Restores a former tabbingContext when an active one is released.
104 * The TabbingManager stack of tabbingContext instances will be unwound
105 * from the top-most released tabbingContext down to the first non-released
106 * tabbingContext instance. This non-released instance is then activated.
109 // Unwind as far as possible: find the topmost non-released
111 let toActivate = this.stack.length - 1;
112 while (toActivate >= 0 && this.stack[toActivate].released) {
116 // Delete all tabbingContexts after the to be activated one. They have
117 // already been deactivated, so their effect on the DOM has been reversed.
118 this.stack.splice(toActivate + 1);
120 // Get topmost tabbingContext, if one exists, and activate it.
121 if (toActivate >= 0) {
122 this.stack[toActivate].activate();
127 * Makes all elements outside of the tabbingContext's set untabbable.
129 * Elements made untabbable have their original tabindex and autofocus
130 * values stored so that they might be restored later when this
131 * tabbingContext is deactivated.
133 * @param {Drupal~TabbingContext} tabbingContext
134 * The TabbingContext instance that has been activated.
136 activate(tabbingContext) {
137 const $set = tabbingContext.$tabbableElements;
138 const level = tabbingContext.level;
139 // Determine which elements are reachable via tabbing by default.
140 const $disabledSet = $(':tabbable')
141 // Exclude elements of the active tabbing set.
143 // Set the disabled set on the tabbingContext.
144 tabbingContext.$disabledElements = $disabledSet;
145 // Record the tabindex for each element, so we can restore it later.
146 const il = $disabledSet.length;
147 for (let i = 0; i < il; i++) {
148 this.recordTabindex($disabledSet.eq(i), level);
150 // Make all tabbable elements outside of the active tabbing set
153 .prop('tabindex', -1)
154 .prop('autofocus', false);
156 // Set focus on an element in the tabbingContext's set of tabbable
157 // elements. First, check if there is an element with an autofocus
158 // attribute. Select the last one from the DOM order.
159 let $hasFocus = $set.filter('[autofocus]').eq(-1);
160 // If no element in the tabbable set has an autofocus attribute, select
161 // the first element in the set.
162 if ($hasFocus.length === 0) {
163 $hasFocus = $set.eq(0);
165 $hasFocus.trigger('focus');
169 * Restores that tabbable state of a tabbingContext's disabled elements.
171 * Elements that were made untabbable have their original tabindex and
172 * autofocus values restored.
174 * @param {Drupal~TabbingContext} tabbingContext
175 * The TabbingContext instance that has been deactivated.
177 deactivate(tabbingContext) {
178 const $set = tabbingContext.$disabledElements;
179 const level = tabbingContext.level;
180 const il = $set.length;
181 for (let i = 0; i < il; i++) {
182 this.restoreTabindex($set.eq(i), level);
187 * Records the tabindex and autofocus values of an untabbable element.
189 * @param {jQuery} $el
190 * The set of elements that have been disabled.
191 * @param {number} level
192 * The stack level for which the tabindex attribute should be recorded.
194 recordTabindex($el, level) {
195 const tabInfo = $el.data('drupalOriginalTabIndices') || {};
197 tabindex: $el[0].getAttribute('tabindex'),
198 autofocus: $el[0].hasAttribute('autofocus'),
200 $el.data('drupalOriginalTabIndices', tabInfo);
204 * Restores the tabindex and autofocus values of a reactivated element.
206 * @param {jQuery} $el
207 * The element that is being reactivated.
208 * @param {number} level
209 * The stack level for which the tabindex attribute should be restored.
211 restoreTabindex($el, level) {
212 const tabInfo = $el.data('drupalOriginalTabIndices');
213 if (tabInfo && tabInfo[level]) {
214 const data = tabInfo[level];
216 $el[0].setAttribute('tabindex', data.tabindex);
218 // If the element did not have a tabindex at this stack level then
221 $el[0].removeAttribute('tabindex');
223 if (data.autofocus) {
224 $el[0].setAttribute('autofocus', 'autofocus');
230 $el.removeData('drupalOriginalTabIndices');
233 // Remove the data for this stack level and higher.
234 let levelToDelete = level;
235 while (tabInfo.hasOwnProperty(levelToDelete)) {
236 delete tabInfo[levelToDelete];
239 $el.data('drupalOriginalTabIndices', tabInfo);
246 * Stores a set of tabbable elements.
248 * This constraint can be removed with the release() method.
250 * @constructor Drupal~TabbingContext
252 * @param {object} options
253 * A set of initiating values
254 * @param {number} options.level
255 * The level in the TabbingManager's stack of this tabbingContext.
256 * @param {jQuery} options.$tabbableElements
257 * The DOM elements that should be reachable via the tab key when this
258 * tabbingContext is active.
259 * @param {jQuery} options.$disabledElements
260 * The DOM elements that should not be reachable via the tab key when this
261 * tabbingContext is active.
262 * @param {bool} options.released
263 * A released tabbingContext can never be activated again. It will be
264 * cleaned up when the TabbingManager unwinds its stack.
265 * @param {bool} options.active
266 * When true, the tabbable elements of this tabbingContext will be reachable
267 * via the tab key and the disabled elements will not. Only one
268 * tabbingContext can be active at a time.
270 function TabbingContext(options) {
271 $.extend(this, /** @lends Drupal~TabbingContext# */{
281 $tabbableElements: $(),
286 $disabledElements: $(),
301 * Add public methods to the TabbingContext class.
303 $.extend(TabbingContext.prototype, /** @lends Drupal~TabbingContext# */{
306 * Releases this TabbingContext.
308 * Once a TabbingContext object is released, it can never be activated
311 * @fires event:drupalTabbingContextReleased
314 if (!this.released) {
316 this.released = true;
317 Drupal.tabbingManager.release(this);
318 // Allow modules to respond to the tabbingContext release event.
319 $(document).trigger('drupalTabbingContextReleased', this);
324 * Activates this TabbingContext.
326 * @fires event:drupalTabbingContextActivated
329 // A released TabbingContext object can never be activated again.
330 if (!this.active && !this.released) {
332 Drupal.tabbingManager.activate(this);
333 // Allow modules to respond to the constrain event.
334 $(document).trigger('drupalTabbingContextActivated', this);
339 * Deactivates this TabbingContext.
341 * @fires event:drupalTabbingContextDeactivated
346 Drupal.tabbingManager.deactivate(this);
347 // Allow modules to respond to the constrain event.
348 $(document).trigger('drupalTabbingContextDeactivated', this);
353 // Mark this behavior as processed on the first pass and return if it is
354 // already processed.
355 if (Drupal.tabbingManager) {
360 * @type {Drupal~TabbingManager}
362 Drupal.tabbingManager = new TabbingManager();