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

Handling Interaction

• focus/trap -- to trap the focus within a given DOM element upon Tab (ARIA Practices: Trapping Focus)
• focus/first -- to identify the element that should receive focus upon entering a new context
• focus/within -- to "polyfill" :focus-within

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

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.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.