makeup-active-descendant - npm Package Compare versions

Comparing version 0.1.2 to 0.1.3

index.js

@@ -130,3 +130,3 @@ 'use strict';
 
-  function LinearActiveDescendant(el, focusEl, ownedEl, itemSelector, selectedOptions) {
+  function LinearActiveDescendant(el, focusEl, containerEl, itemSelector, selectedOptions) {
     var _this;
@@ -143,9 +143,13 @@
     _this._focusEl = focusEl;
-    _this._ownedEl = ownedEl;
+    _this._containerEl = containerEl;
     _this._itemSelector = itemSelector; // ensure container has an id
 
-    nextID(ownedEl); // focus element must programatically 'own' the container of descendant items
+    nextID(containerEl); // if DOM hierarchy cannot be determined,
+    // focus element must programatically 'own' the container of descendant items
 
-    focusEl.setAttribute('aria-owns', ownedEl.id); // ensure each item has an id
+    if (containerEl !== focusEl) {
+      focusEl.setAttribute('aria-owns', containerEl.id);
+    } // ensure each item has an id
 
+
     _this._items.forEach(function (itemEl) {
@@ -184,3 +188,3 @@ nextID(itemEl);
     get: function get() {
-      return this._ownedEl.querySelectorAll(this._itemSelector);
+      return this._containerEl.querySelectorAll(this._itemSelector);
     }
@@ -198,3 +202,3 @@ }, {
 class GridActiveDescendant extends ActiveDescendant {
-    constructor(el, focusEl, ownedEl, rowSelector, cellSelector) {
+    constructor(el, focusEl, containerEl, rowSelector, cellSelector) {
         super(el);
@@ -206,4 +210,4 @@ }
 
-function createLinear(el, focusEl, ownedEl, itemSelector, selectedOptions) {
-  return new LinearActiveDescendant(el, focusEl, ownedEl, itemSelector, selectedOptions);
+function createLinear(el, focusEl, containerEl, itemSelector, selectedOptions) {
+  return new LinearActiveDescendant(el, focusEl, containerEl, itemSelector, selectedOptions);
 }
@@ -210,0 +214,0 @@

package.json

 {
   "name": "makeup-active-descendant",
   "description": "Implements ARIA active descendant keyboard navigation",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "main": "index.js",
@@ -6,0 +6,0 @@ "repository": "https://github.com/makeup-js/makeup-active-descendant.git",

README.md

@@ -28,4 +28,19 @@ # makeup-active-descendant
 
-## Example
+## Example 1: Programmatic Relationship
 
+In this example the focusable element is not an ancestor of the "descendant" elements. The module will add `aria-owns` to create a programmatic relationship between the two elements. This is typical of a combobox or date-picker type pattern.
+
+Starting markup:
+
+```html
+<div class="widget">
+    <input type="text">
+    <ul>
+        <li>Item 1</li>
+        <li>Item 2</li>
+        <li>Item 3</li>
+    </ul>
+</div>
+```
+
 ```js
@@ -41,7 +56,8 @@ // require the module
 
-// get the owned element reference
-const ownedEl = widgetEl.querySelector('ul');
+// get the element that contains the "descendant" items.
+// This element will be programmatically "owned" by the focus element.
+const containerEl = widgetEl.querySelector('ul');
 
 // create an activeDescendant widget instance on the element
-const activeDescendant = ActiveDescendant.createLinear(widgetEl, focusEl, ownedEl, 'li');
+const activeDescendant = ActiveDescendant.createLinear(widgetEl, focusEl, containerEl, 'li');
 
@@ -54,8 +70,47 @@ // listen for events (optional)
 
-Markup before:
+Markup after instantiation:
 
 ```html
+<div class="widget" id="widget-0">
+    <input type="text" aria-owns="widget-0-list-0">
+    <ul id="widget-0-list-0">
+        <li id="widget-0-item-0" data-makeup-index="0">Item 1</li>
+        <li id="widget-0-item-1" data-makeup-index="1">Item 2</li>
+        <li id="widget-0-item-2" data-makeup-index="2">Item 3</li>
+    </ul>
+</div>
+```
+
+Markup after pressing down arrow key on focusable element:
+
+```html
+<div class="widget" id="widget-0">
+    <input type="text" aria-activedescendant="widget-0-item-0" aria-owns="widget-0-list-0">
+    <ul id="widget-0-list-0">
+        <li class="active-descendant" id="widget-0-item-0" data-makeup-index="0">Item 1</li>
+        <li id="widget-0-item-1" data-makeup-index="1">Item 2</li>
+        <li id="widget-0-item-2" data-makeup-index="2">Item 3</li>
+    </ul>
+</div>
+```
+
+Use CSS to style the active descendant however you wish:
+
+```css
+.widget .active-descendant {
+    font-weight: bold;
+}
+```
+
+## Example 2: Hierarchy Relationship
+
+In this example the focusable element is an ancestor of the list items and therefore the "descendant" relationship can be automatically determined from the DOM hierarchy. This is typical of a standalone listbox or grid widget.
+
+**NOTE**: this module does not add any ARIA roles; only states and properties.  
+
+Starting markup:
+
+```html
 <div class="widget">
-    <input type="text">
-    <ul>
+    <ul tabindex="0">
         <li>Item 1</li>
@@ -68,2 +123,24 @@ <li>Item 2</li>
 
+```js
+// require the module
+const ActiveDescendant = require('makeup-active-descendant');
+
+// get the widget root element reference
+const widgetEl = document.querySelector('.widget');
+
+// get the focus element reference
+const focusEl = widgetEl.querySelector('ul');
+
+// in this scenario the container element is the same as the focusable element
+const containerEl = focusEL;
+
+// create an activeDescendant widget instance on the element
+const activeDescendant = ActiveDescendant.createLinear(widgetEl, focusEl, containerEl, 'li');
+
+// listen for events (optional)
+widgetEl.addEventListener('activeDescendantChange', function(e) {
+    console.log(e.detail);
+});
+```
+
 Markup after instantiation:
@@ -73,4 +150,3 @@
 <div class="widget" id="widget-0">
-    <input type="text" aria-owns="widget-0-list-0">
-    <ul id="widget-0-list-0">
+    <ul id="widget-0-list-0" tabindex="0">
         <li id="widget-0-item-0" data-makeup-index="0">Item 1</li>
@@ -87,4 +163,3 @@ <li id="widget-0-item-1" data-makeup-index="1">Item 2</li>
 <div class="widget" id="widget-0">
-    <input type="text" aria-activedescendant="widget-0-item-0" aria-owns="widget-0-list-0">
-    <ul id="widget-0-list-0">
+    <ul id="widget-0-list-0" aria-activedescendant="widget-0-item-0" tabindex="0">
         <li class="active-descendant" id="widget-0-item-0" data-makeup-index="0">Item 1</li>
@@ -91,0 +166,0 @@ <li id="widget-0-item-1" data-makeup-index="1">Item 2</li>

No alert changes

Improved metrics

Total package byte prevSize

284592

0.91%

Lines of code

172

1.78%

Number of lines in readme file

228

49.02%

No dependency changes