jquery-active-descendant

jQuery collection plugin that implements one or two dimensional aria-activedescendant keyboard navigation. A common scenario for aria-activedescendant is a combobox input (with or without autocomplete behaviour) or date picker grid.

Install

npm install jquery-active-descendant

Signature

$(widgetSelector).activeDescendant(focusableItemSelector, ownedItemSelector, descendantItemsSelector, options);

Params

• focusableItemSelector - selector for focusable item in relation to widget
• ownedItemSelector - selector for the item that is programmatically owned by the focusable item (i.e. 'aria-owns')
• descendantItemsSelector - selector for pseudo-focusable descendant items in relation to widget
• options.autoInit: set initial activedescendant state when plugin executes (default: false)
• options.autoReset: reset activedescendant state when focus exits widget (default: true)
• options.autoWrap: reaching end of collection will wrap back to beginning, and vice versa (default: false)
• options.axis - 'x', 'y' or 'both' (default: 'both')
• options.disableHomeAndEndKeys: disable HOME and END key functionality (default: false)
• options.isGrid - set to true to use two-dimensional navigation (default: false)
• options.useAriaSelected - set to true to use aria-selected state on descendant items (historically required by Safari + Voiceover) (default: false)

Triggers

• activeDescendantChange - when active descendant has changed

Listens

• domChange - when dom of ownedItem selector has changed. Must be triggered on ownedItemSelector.

Example - One Dimensional

Input HTML:

<div class="widget">
    <input role="combobox" />
    <ul role="listbox">
        <li role="option">A</li>
        <li role="option">B</li>
        <li role="option">C</li>
    </ul>
</div>

Execute plugin:

$('.widget').activeDescendant('[role=combobox]', '[role=listbox]', '[role=option]', { axis: 'y'});

Output HTML:

<div class="widget">
    <input role="combobox" aria-owns="nid-3" />
    <ul role="listbox" id="nid-3">
        <li role="option" id="nid-0">A</li>
        <li role="option" id="nid-1">B</li>
        <li role="option" id="nid-2">C</li>
    </ul>
</div>

First down arrow key produces:

<div class="widget">
    <input role="combobox" aria-owns="nid-3" aria-activedescendant="nid-0" />
    <ul role="listbox" id="nid-3">
        <li role="option" id="nid-0" class="active-descendant">A</li>
        <li role="option" id="nid-1">B</li>
        <li role="option" id="nid-2">C</li>
    </ul>
</div>

Next down arrow key produces:

<div class="widget">
    <input role="combobox" aria-owns="nid-3" aria-activedescendant="nid-1" />
    <ul role="listbox" id="nid-3">
        <li role="option" id="nid-0">A</li>
        <li role="option" id="nid-1" class="active-descendant">B</li>
        <li role="option" id="nid-2">C</li>
    </ul>
</div>

Example - Two Dimensional

Input HTML:

<div class="widget">
    <input type="text">
    <table>
        <tbody>
            <tr><td>1</td><td>2</td><td>3</td><td>4</td><td>5</td><td>6</td><td>7</td></tr>
            <tr><td>8</td><td>9</td><td>10</td><td>11</td><td>12</td><td>13</td><td>14</td></tr>
            <tr><td>15</td><td>16</td><td>17</td><td>18</td><td>19</td><td>20</td><td>21</td></tr>
        </tbody>
    </table>
</div>

Execute plugin:

$('.widget').activeDescendant('input', 'td', {isGrid: true});

Dependencies

• jquery
• jquery-grid-navigation
• jquery-linear-navigation
• jquery-next-id

Development

Useful NPM task runners:

• npm start for local browser-sync development.
• npm test runs tests & generates reports (see reports section below)
• npm run tdd test driven development: watches code and re-tests after any change
• npm run build cleans, lints, tests and minifies

Execute npm run to view all available CLI scripts.

CI Build

https://travis-ci.org/makeup-jquery/jquery-active-descendant

Code Coverage

https://coveralls.io/github/makeup-jquery/jquery-active-descendant?branch=master

Test Reports

Local test and coverage reports are generated under .test_reports folder.

JSDocs

Local JSDocs are generated under ./jsdoc folder.