1.0.1 • Published 7 years ago
jquery-active-descendant v1.0.1
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 widgetownedItemSelector
- 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 widgetoptions.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
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 changenpm 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.