# ally.query.tabsequence

Finds keyboard focusable ("tabbable") elements in the DOM and returns them in the order calculated based on tabindex attribute values.

# Description

The Sequential Navigation Focus Order depends on a variety of factors:

Value of the tabindex attribute. The sequence generally starts with all positive tabindex elements with tabindex="1" in DOM order, then all elements with tabindex="2" in DOM order, then all elements with tabindex="3", … until the highest tabindex is reached, at which point the sequence continues with the tabindex="0" (which is set implicitly for a number of HTML elements, e.g. <input>).
<area> elements may either be sorted in DOM order of the <area> itsel, or the <img> referencing the map.
Within a ShadowDOM positive tabindex elements may either be sorted localized to the ShadowRoot, or globally in the document.

ally.query.tabsequence uses ally.query.tabbable to find keyboard focusable elements and then sorts the element positions respecting ShadowDOM, <area> vs <img> replacement and tabindex attribute value.

# Usage

var sequence = ally.query.tabsequence({
  context: '.within-filter-selector',
  includeContext: true,
  strategy: 'quick',
});

# Arguments

Name	Type	Default	Description
context	`<selector>`	`documentElement`	The scope of the DOM in which to search. The first element of a collection is used.
includeContext	boolean	`false`	Prepend the `context` element if it is focusable.
includeOnlyTabbable	boolean	`false`	Include elements that would otherwise be ignored because they're considered only tabbable,
strategy	`"quick"`, `"strict"`, `"all"`	`"quick"`	The approach used to find elements.

# Returns

Array of HTMLElement.

# Examples

# ally.query.tabsequence Example

ally.query.tabsequence Example on jsbin.com

play with ally.query.tabsequence Example on jsbin.com or open the document of ally.query.tabsequence Example

# Changes

Since v1.1.0 the module can move <area> elements to the place of the <img> elements they're referenced from.
Since v1.1.0 the module can sort elements in ShadowDOM localized to the ShadowRoot.
Since v1.1.0 the option includeOnlyTabbable allows to skip the internal filter preventing this module from returning elements that cannot be focused by script.
Since v1.4.0 the tabindex attribute is used for sorting for elements without a tabIndex property.

# Notes

See ally.is.focusRelevant

In some browsers <area> elements are provided in DOM order they occur. Others provide them in DOM order of the <img> elements that use them. ally.query.tabindex handles this appropriately. See Sequential Navigation Focus Order for Image Maps, Blink 447289, WebKit 140259

In some browsers positive tabindexes are sorted localized to ShadowDOM, in some they are sorted globally. ally.query.tabindex handles this appropriately.

In Firefox the Flexbox CSS property order affects the tabsequence, Gecko 812687, ally.js does not replicate this behavior.

In Firefox referencing the same <map> from multiple <img> elements can lead to elements missing from the tabsequence, Gecko 1116126, ally.js does not replicate this behavior.

In Firefox <label tabindex="0"> is part of the tabsequence, Gecko 1240285, ally.js does not replicate this behavior.

ally.is.tabbable is used to filter focusable elements
ally.query.focusable is used to find focusable elements
ally.query.firstTabbable finds the first keyboard focusable element in a context
ally.query.tabbable finds keyboard focusable elements in DOM order
HTML5: The tabindex attribute