aria-tree-walker
A lightweight walker for labeled ARIA trees.
Reads the structure of an ARIA tree where every node is labeled. Provides a breadth-first tree walker using arrow keys. AT users will get the full label in browse mode and can switch into focus mode to explore (on almost all major browser+AT combinations).
Usage
The module currently exports a function that expects a (well-prepared) DOM node:
import { attachNavigator } from 'aria-tree-walker';
const myNode = document.querySelector('...');
attachNavigator(myNode);
The navigator extracts an abtract tree based on suitably prepared data-owns
and data-owns-id
attributes. The abstract tree is used to provide keyboard navigation and (accessible) focus management (using the "roving tabindex" technique).
The active tree node will get a class of is-activedescendant
for (visual) styling purposes while nodes in its subtree will get a class of is-highlight
.
Content expectations
Some rough expectations to get meaningful results from your content:
- The DOM node must either have a
data-owns
attribute or have a descendant with adata-owns
attribute (which will serve as de-facto root - having a wrapping node around the "real" root can make things easier for authoring/design). - The
data-owns
attribute contains a space-separated list of identifiers, matchingdata-owns-id
attribute values on descendant nodes. - The "
data-owns
tree" should be "full" since navigation stops at elements withoutdata-owns
attribute. - Each node with
data-owns
attribute should have suitable roles and ARIA markup, e.g.,role="tree"
androle="treeitem"
as well as anaria-label
with a suitable accessible name (to get a "flat" name). - Visual highlighting is handled by author-provided CSS using
.is-activedescendant
,.is-highlight
.
User Experience
Upon focus (e.g., clicking on or tabbing to an element with attached walker), the node will be highlighted and become explorable using the arrow keys. If you're using a screenreader, use browse mode until you encounter the node, then switch out of virtual/browse mode to explore with arrow keys. Some screenreader and browser combinations fail to put the current node into focus so you may have to move the focus to the equation.
Authors must ensure that these features are discoverable, e.g., via an explainer in the content / UI or via specific indicators on the element (e.g., one-time hints via live-region, description, role description).
Examples
See ./docs
for examples using simple diagrams, chemical diagrams, and (server-side) equation rendering with MathJax.
History and prior art
An initial prototype was developed during the AIM workshop Web accessibility of mathematics. Much of the code was (and still is) based on prior work in MathJax, speech rule engine, and ChromeVox (part of Chromium). That prototype was further developed into MathJax SRE Walker, a lightweight walker for server-side generated mathjax rendering.
From there, the walker evolved from SRE-specific markup to a general purpose aria(-owns) tree walker. At that point, it was forked to this repository and continued as aria-tree-walker. The goal is to support any such tree (e.g., complex diagrammatic content) and to gradually improve the user experience.
Thanks
Besides the contributors, the following organizations have helped in the development of this library: