# API index

When creating web applications or UI widgets these modules may come in handy.

# Countering browser bugs

Every software has its problems - so do browsers. These utilities combat things browsers get wrong.

ally.fix.pointerFocusChildren (Internet Explorer 10 - 11)
ally.fix.pointerFocusInput (Safari and Firefox on Mac OS X)
ally.fix.pointerFocusParent (WebKit and old Blink)

# Extended `:focus` Styling

Sometimes :focus is not enough for communicating your application's intentions properly.

ally.style.focusSource provides html[focus-source="pointer|key|script"]
ally.style.focusWithin polyfills :focus-within with .ally-focus-within

# Altering browser focus behavior

While it's best to use standardized features and leave browsers to figure things out, specifications sometimes leave us hanging in limbo.

ally.maintain.disabled renders elements inert to prevent any user interaction
ally.maintain.hidden sets aria-hidden="true" on insignificant branches
ally.maintain.tabFocus traps TAB focus in the tabsequence

# Finding elements

In order to work with focusable elements, we must first know which elements we're supposed to work with. See what does "focusable" mean? for a differentiation.

ally.query.firstTabbable finds the first keyboard focusable element
ally.query.focusable finds all focusable elements
ally.query.shadowHosts finds all elements hosting a ShadowRoot
ally.query.tabbable finds all keyboard focusable elements in DOM order
ally.query.tabsequence finds all keyboard focusable elements in Sequential Navigation Focus Order

# Element state

Unlike any other ally modules, these components do not take take options.context argument, but expect the element as first argument, allowing easy use in .filter(). See what does "focusable" mean? for a differentiation.

ally.is.activeElement returns true if the element is the activeElement of its host context, i.e. its document, iFrame or ShadowHost
ally.is.disabled returns true if the element is :disabled
ally.is.focusRelevant returns true if the element is considered theoretically focusable
ally.is.focusable returns true if the element is considered focusable by script
ally.is.onlyTabbable returns true if the element is tabbable but not focusable
ally.is.shadowed returns true if the element is the descendant of a ShadowRoot
ally.is.tabbable returns true if the element is considered keyboard focusable ("tabbable")
ally.is.validArea returns true if the <area> element is properly used via <map> by an <img>
ally.is.validTabindex returns true if the element's tabindex attribute value is sound
ally.is.visible returns true if the element is rendered (but not necessarily visible in the viewport)

# Manipulating element state

Making up for missing or lacking DOM mutation APIs.

ally.element.blur shifts focus away from an element
ally.element.disabled disables all elements, not only form controls
ally.element.focus shifts focus to an element

# Reacting to element state

Especially when dealing with transitional user interfaces we need to know when an element can be safely focused.

ally.when.focusable executes a callback once an element fulfills ally.is.focusable and is visible in the viewport
ally.when.key executes a callback when a given key has been pressed
ally.when.visibleArea executes a callback once an element is visible in the viewport

# DOM traversal

Sometimes you need some DOM traversal utilities

ally.get.insignificantBranches returns an array containing the branches of the DOM that do contain any of the target elements
ally.get.activeElement identifies the element that has focus

# Values

ally.map.attribute maps WAI-ARIA states and properties
ally.map.keycode maps control keys to readable names

# Developer modules

When creating libraries these modules may come in handy.

When you find yourself using one of these in your application code, we should talk about what you're trying to achieve and how we could do that as part of the library instead. Get in touch, file an issue explaining what you're trying to achieve!

# DOM traversal (extended)

Sometimes you need some DOM traversal utilities

ally.get.activeElements identifies the ShadowHost ancestry of the active element
ally.get.insignificantBranches
ally.get.focusRedirectTarget
ally.get.focusTarget
ally.get.parents
ally.get.shadowHostParents
ally.get.shadowHost

# Event dispatchers

Emitting events when there's no standardized equivalent

# Event listeners

Translate volatile events to stateful interfaces

ally.observe.interactionType observes user interaction method to distinguish pointer and keyboard actions
ally.observe.shadowMutations registers MutationObservers across nested ShadowRoots

# Contributor modules

When working on ally.js these modules may come in handy.

When you find yourself using one of these in your application or library code, we should talk about what you're trying to achieve and how we could do that as part of the library instead. Get in touch, file an issue explaining what you're trying to achieve!

::note These modules are only available to be consumed via ES6, AMD or CommonJS directly, they are not exposed in the production bundle dist/ally.min.js. :::

The internal tools are documented in a less accessible way to make it just a tiny bit harder for someone not working on ally to use them. This is intentional. The stability of these APIs is not guaranteed.