ally.js

ally.js is a dependency-free (well, some shims, yes) Library to help applications with accessibility concerns. The intention is to separate these components from actual applications. It is being developed along side another project and features get added to ally.js once they become necessary in the other application - or someone sends a PR. The ultimate goal is to make adhering to WAI-ARIA a breeze.

Do not confuse ally.js with a11y.js, a library to help with ARIA states.

---

Goals

• simplify managing focus
• simplify WAI-ARIA keyboard interactions for defined ARIA roles
• simplify working with aria attributes (only if a11y.js doesn't cover all of this already)
  • allow toggling states
  • simplify referencing things like aria-describedby="…unique-id-required…"
• simplify providing "help layer" explaining available keyboard commands

---

Features

Working With The DOM

• dom/query-focusable, dom/is-focusable - to obtain a list of focusable elements within a given DOM element
• dom/query-tabbable, dom/is-tabbable - to obtain a list of tabbable elements within a given DOM element
• dom/query-tabsequence - to obtain the exact order of tabbable elements within a given DOM element
• dom/active-elements - to obtain the list of ShadowDOM host elements containing the actually focused element
• dom/visible-quotient - to obtain how much of an element is currently visible on screen
• dom/when-visible - to execute a callback once an element is fully visible in the viewport

Handling Interaction

• focus/disable-focus -- to render elements inert and remove them from the document's focus navigation sequence
• focus/trap -- to trap the focus within a given DOM element upon Tab (ARIA Practices: Trapping Focus) - deprecated!, use focus/disable-focus instead!
• focus/first -- to identify the element that should receive focus upon entering a new context
• focus/within -- to "polyfill" :focus-within
• focus/when-visible -- to focus an element once is fully visible in the viewport
• focus/source -- to allow styling of :focus dependent on user input (keyboard, pinter, script)

Working Around Browser Bugs

• fix-browser/pointer-focus-parent -- to work around a bug in WebKit where a parent [tabindex="-1"] element can get focus when clicking on a nested <a>
• fix-browser/pointer-focus-input -- to work around a behavior in Safari and Firefox on Mac OS X where clicking on certain form elements would not give them focus
• fix-browser/pointer-focus-children to work around a bug in IE10 and IE11 where children of display:flex; are made focusable when they shouldn't be

Events

• event/shadow-focus -- dispatched when focus changes within the Shadow DOM

Development / Debugging

• event/active-element -- to dispatch active-element event to html element regardless of focus event

---

Requirements

• ES5
• ES6 Array.prototype.findIndex
• CSSOM CSS.escape (spec)

Dependencies

• ES5-shim (implicitly expected)
• ES6-shim Array.prototype.findIndex (or complete ES6-shim)
• CSSOM CSS.escape polyfill

RequireJS Config

require.config({
  paths: {
    'ally': 'bower_components/ally.js/src',
    // shims required by ally.js
    'array.prototype.findindex': 'bower_components/array.prototype.findindex/index',
    'CSS.escape': 'bower_components/CSS.escape/css.escape',
  },

  // alias array.prototype.findindex to es6-shim
  // only if you're using es6-shim instead of selected bundles
  // see http://requirejs.org/docs/api.html#config-map
  map: {
    '*': {
      'array.prototype.findindex': 'es6-shim',
    }
  },
});

---

Changelog

0.0.7 (July 8th 2015)

• adding event/shadow-focus to emit custom event when focus changes within the Shadow DOM - extracted from focus/within
• adding event/interaction-type-listener to track user input to differentiate keyboard and pointer input
• adding focus/source to allow styling of :focus dependent on user input (keyboard, pinter, script)
• adding focus/disable-focus to render elements inert and remove them from the document's focus navigation sequence
• deprecating focus/trap, use focus/disable-focus instead

0.0.6 (June 17th 2015)

• fixing dom/visible-quotient to subtract scrollbars from visible space

0.0.5 (June 15th 2015)

• adding dom/when-visible to execute callback when an element becomes visible
• improving dom/when-visible to also wait until an element becomes focusable

0.0.4 (February 3rd 2015)

• adding dom/visible-quotient
• adding focus/when-visible
• fixing fix-browser/pointer-focus-children to temporarily disable transitions

0.0.3 (January 7th 2015)

• adding fix-browser/pointer-focus-children
• adding dom/focus-target to find the first focusable element in an element's ancestry
• improving fix-browser/pointer-focus-parent for less complexity
• improving fix-browser by only engaging handlers for affected browsers (yes, user agent sniffing, deal with it)
• fixing dom/is-visible to look at computed styles, not the element's styles (duh!)

0.0.2 (January 5th 2015)

• adding fix-browser/pointer-focus-input
• adding dom/active-elements to identify the actually focsued element and its host elements in ShadowDOM
• adding focus/within to "polyfill" :focus-within
• adding warning to browser support detection when document does not have focus
• adding supports/supports-cache to store browser compatibility data
• adding focus/first to identify and focus the first [autofocus] or non positive tabindex ([tabindex=1]) element
• adding dom/query-domsequence to separate sorting and mutating the list from dom/query-tabbable
• improving fix-browser/pointer-focus-parent for fewer DOM interactions and less code
• improving focus/trap to allow nothing being focus and re-acquire focus when required
• improving selector/focusable (thus dom/query-focusable) by also finding focusable shadowed elements (via >>> or /deep/, ShadowDOM) - #11
• fixing event/active-element to be dispatched on document rather than document.body
• fixing prototype/svgelement.prototoype.focus to also cover SVGElement.prototype.blur
• fixing linting errors

0.0.1 (December 25th 2014)

• initial release "focus"

License

ally.js is published under the MIT License.