/** @module delite/KeyNav */
define([
"dcl/dcl",
"delite/keys", // keys.END keys.HOME, keys.LEFT_ARROW etc.
"./features",
"./Widget",
"./focus" // causes _onBlur() to be called when focus removed from KeyNav and logical descendants
], function (dcl, keys, has, Widget) {
/**
* Return true if node is an `<input>` or similar that responds to keyboard input.
* @param {Element} node
* @returns {boolean}
*/
function takesInput(node) {
var tag = node.nodeName.toLowerCase();
return !node.readOnly && (tag === "textarea" || (tag === "input" &&
/^(color|email|number|password|search|tel|text|url|range)$/.test(node.type)));
}
/**
* A mixin to allow arrow key and letter key navigation of child Elements.
* It can be used by delite/Container based widgets with a flat list of children,
* or more complex widgets like a Tree.
*
* To use this mixin, the subclass must:
*
* - Implement `_onLeftArrow()`, `_onRightArrow()``_onDownArrow()`, `_onUpArrow()` methods to handle
* left/right/up/down keystrokes.
* - Set all navigable descendants' initial tabIndex to "-1"; both initial descendants and any
* descendants added later, by for example `addChild()`.
* - Define `childSelector` as a function or string that identifies focusable child Elements.
*
* Note the word "child" in this class is used loosely, to refer to any descendant Element.
* If the child elements contain text though, they should have a label attribute. KeyNav uses the label
* attribute for letter key navigation.
*
* @mixin module:delite/KeyNav
* @augments module:delite/Widget
*/
return dcl(Widget, /** @lends module:delite/KeyNav# */ {
// TODO: due to apparent bugs in jsdoc3, these aren't getting shown.
/**
* The currently focused descendant, or null if there isn't one
* @member {Element}
* @readonly
* @protected
*/
focusedChild: null,
/**
* Hash mapping key code (arrow keys and home/end key) to functions to handle those keys.
* Usually not used directly, as subclasses can instead override _onLeftArrow() etc.
* Must be set before postCreate().
* @member {Object}
* @protected
*/
_keyNavCodes: null,
/**
* Selector to identify which descendants Elements are navigable via arrow keys or
* keyboard search. Note that for subclasses like a Tree, one navigable node could be a descendant of another.
*
* By default, the direct DOM children of this widget are considered as the children.
*
* Must be set in the prototype rather than on the instance.
*
* @member {string|Function}
* @protected
* @constant
*/
childSelector: null,
/**
* Figure out effective target of this event, either a navigable node (a.k.a. a child),
* or this widget itself.
* The meaning of "child" here is complicated because this could be a Tree with nested children.
* @param evt
* @private
*/
_getTargetElement: function (evt) {
for (var child = evt.target; child !== this; child = child.parentNode) {
if (this._selectorFunc(child)) {
return child;
}
}
return this;
},
postCreate: function () {
// If the user hasn't specified a tabindex declaratively, then set to default value.
if (!this.hasAttribute("tabindex")) {
this.tabIndex = "0";
}
var self = this;
// Setup function to check which child nodes are navigable.
if (typeof this.childSelector === "string") {
var matchesFuncName = has("dom-matches");
this._selectorFunc = function (elem) {
return elem[matchesFuncName](this.childSelector);
};
} else if (this.childSelector) {
this._selectorFunc = this.childSelector;
} else {
this._selectorFunc = function (child) { return child.parentNode === self.containerNode; };
}
if (!this._keyNavCodes) {
var keyCodes = this._keyNavCodes = {};
keyCodes[keys.HOME] = function () {
self.focusFirstChild();
};
keyCodes[keys.END] = function () {
self.focusLastChild();
};
keyCodes[this.isLeftToRight() ? keys.LEFT_ARROW : keys.RIGHT_ARROW] = this._onLeftArrow.bind(this);
keyCodes[this.isLeftToRight() ? keys.RIGHT_ARROW : keys.LEFT_ARROW] = this._onRightArrow.bind(this);
keyCodes[keys.UP_ARROW] = this._onUpArrow.bind(this);
keyCodes[keys.DOWN_ARROW] = this._onDownArrow.bind(this);
}
this.on("keypress", this._onContainerKeypress.bind(this)),
this.on("keydown", this._onContainerKeydown.bind(this)),
this.on("focusin", function (evt) {
var target = self._getTargetElement(evt);
if (target === self) {
self._onContainerFocus(evt);
} else {
self._onChildFocus(target, evt);
}
});
},
/**
* Called on left arrow key, or right arrow key if widget is in RTL mode.
* Should go back to the previous child in horizontal container widgets like Toolbar.
* @protected
* @abstract
*/
_onLeftArrow: function () {
},
/**
* Called on right arrow key, or left arrow key if widget is in RTL mode.
* Should go to the next child in horizontal container widgets like Toolbar.
* @protected
* @abstract
*/
_onRightArrow: function () {
},
/**
* Called on up arrow key. Should go to the previous child in vertical container widgets like Menu.
* @protected
* @abstract
*/
_onUpArrow: function () {
},
/**
* Called on down arrow key. Should go to the next child in vertical container widgets like Menu.
* @protected
* @abstract
*/
_onDownArrow: function () {
},
/**
* Default focus() implementation: focus the first child.
*/
focus: function () {
this.focusFirstChild();
},
/**
* Focus the first focusable child in the container.
* @protected
*/
focusFirstChild: function () {
this.focusChild(this._getNext(this, 1));
},
/**
* Focus the last focusable child in the container.
* @protected
*/
focusLastChild: function () {
this.focusChild(this._getNext(this, -1));
},
/**
* Focus specified child Element.
* @param {Element} child - Reference to container's child.
* @param {boolean} last - If true and if child has multiple focusable nodes, focus the
* last one instead of the first one.
* @protected
*/
focusChild: function (child, last) {
// For IE focus outline to appear, must set tabIndex before focus.
// If this._savedTabIndex is set, use it instead of this.tabIndex, because it means
// the container's tabIndex has already been changed to -1.
child.tabIndex = "_savedTabIndex" in this ? this._savedTabIndex : this.tabIndex;
child.focus(last ? "end" : "start");
// Don't set focusedChild here, because the focus event should trigger a call to _onChildFocus(), which will
// set it. More importantly, _onChildFocus(), which may be executed asynchronously (after this function
// returns) needs to know the old focusedChild to set its tabIndex to -1.
},
/**
* Handler for when the container itself gets focus.
*
* Initially the container itself has a tabIndex, but when it gets focus, switch focus to first child.
*
* @param {Event} evt
* @private
*/
_onContainerFocus: function () {
// Note that we can't use _onFocus() because switching focus from the
// _onFocus() handler confuses the focus.js code
// (because it causes _onFocusNode() to be called recursively).
// Also, _onFocus() would fire when focus went directly to a child widget due to mouse click.
// Ignore spurious focus event:
// On IE, clicking the scrollbar of a select dropdown moves focus from the focused child item to me
if (this.focusedChild) {
return;
}
// When the container gets focus by being tabbed into, or a descendant gets focus by being clicked,
// remove the container's tabIndex so that tab or shift-tab
// will go to the fields after/before the container, rather than the container itself
this._savedTabIndex = this.tabIndex;
this.removeAttribute("tabindex");
this.focus();
},
_onBlur: dcl.after(function () {
// When focus is moved away the container, and its descendant (popup) widgets,
// then restore the container's tabIndex so that user can tab to it again.
// Note that using _onBlur() so that this doesn't happen when focus is shifted
// to one of my child widgets (typically a popup)
// TODO: for 2.0 consider changing this to blur whenever the container blurs, to be truthful that there is
// no focused child at that time.
this.setAttribute("tabindex", this._savedTabIndex);
delete this._savedTabIndex;
if (this.focusedChild) {
this.focusedChild.tabIndex = "-1";
this.focusedChild = null;
}
}),
/**
* Called when a child gets focus, either by user clicking it, or programatically by arrow key handling code.
* It marks that the current node is the selected one, and the previously selected node no longer is.
* @param {Element} child
* @private
*/
_onChildFocus: function (child) {
if (child && child !== this.focusedChild) {
if (this.focusedChild && !this.focusedChild._destroyed) {
// mark that the previously focusable node is no longer focusable
this.focusedChild.tabIndex = "-1";
}
// If container still has tabIndex setting then remove it; instead we'll set tabIndex on child
if (!("_savedTabIndex" in this)) {
this._savedTabIndex = this.tabIndex;
this.removeAttribute("tabindex");
}
// mark that the new node is the currently selected one
child.tabIndex = this._savedTabIndex;
this.focusedChild = child;
}
},
_searchString: "",
/**
* If multiple characters are typed where each keystroke happens within
* multiCharSearchDuration of the previous keystroke,
* search for nodes matching all the keystrokes.
*
* For example, typing "ab" will search for entries starting with
* "ab" unless the delay between "a" and "b" is greater than `multiCharSearchDuration`.
*
* @member {number} KeyNav#multiCharSearchDuration
* @default 1000
*/
multiCharSearchDuration: 1000,
/**
* When a key is pressed that matches a child item,
* this method is called so that a widget can take appropriate action is necessary.
*
* @param {Element} item
* @param {Event} evt
* @param {string} searchString
* @param {number} numMatches
* @private
*/
onKeyboardSearch: function (item, /*jshint unused: vars */ evt, searchString, numMatches) {
if (item) {
this.focusChild(item);
}
},
/**
* Compares the searchString to the Element's text label, returning:
*
* - -1: a high priority match and stop searching
* - 0: not a match
* - 1: a match but keep looking for a higher priority match
*
* @param {Element} item
* @param {string} searchString
* @returns {number}
* @private
*/
_keyboardSearchCompare: function (item, searchString) {
var element = item,
text = item.label || (element.focusNode ? element.focusNode.label : "") || element.textContent || "",
currentString = text.replace(/^\s+/, "").substr(0, searchString.length).toLowerCase();
// stop searching after first match by default
return (!!searchString.length && currentString === searchString) ? -1 : 0;
},
/**
* When a key is pressed, if it's an arrow key etc. then it's handled here.
* @param {Event} evt
* @private
*/
_onContainerKeydown: function (evt) {
// Ignore left, right, home, and end on <input> controls
if (takesInput(evt.target) &&
(evt.keyCode === keys.LEFT_ARROW || evt.keyCode === keys.RIGHT_ARROW ||
evt.keyCode === keys.HOME || evt.keyCode === keys.END)) {
return;
}
var func = this._keyNavCodes[evt.keyCode];
if (func) {
func(evt, this.focusedChild);
evt.stopPropagation();
evt.preventDefault();
this._searchString = ""; // so a DOWN_ARROW b doesn't search for ab
} else if (evt.keyCode === keys.SPACE && this._searchTimer && !(evt.ctrlKey || evt.altKey || evt.metaKey)) {
// Stop a11yclick from interpreting key as a click event.
// Also stop IE from scrolling, and most browsers (except FF) from sending keypress.
evt.preventDefault();
this._keyboardSearch(evt, " ");
}
},
/**
* When a printable key is pressed, it's handled here, searching by letter.
* @param {Event} evt
* @private
*/
_onContainerKeypress: function (evt) {
// Ignore:
// - keystrokes on <input> and <textarea>
// - duplicate events on firefox (ex: arrow key that will be handled by keydown handler)
// - control sequences like CMD-Q.
// - the SPACE key (only occurs on FF)
//
// Note: if there's no search in progress, then SPACE should be ignored. If there is a search
// in progress, then SPACE is handled in _onContainerKeyDown.
if (takesInput(evt.target) || evt.charCode <= keys.SPACE || evt.ctrlKey || evt.altKey || evt.metaKey) {
return;
}
if (/^(checkbox|radio)$/.test(evt.target.type) &&
(evt.charCode === keys.SPACE || evt.charCode === keys.ENTER)) {
// Ignore keyboard clicks on checkbox controls
return;
}
evt.preventDefault();
evt.stopPropagation();
this._keyboardSearch(evt, String.fromCharCode(evt.charCode).toLowerCase());
},
/**
* Perform a search of the widget's options based on the user's keyboard activity.
*
* Called on keypress (and sometimes keydown), searches through this widget's children
* looking for items that match the user's typed search string. Multiple characters
* typed within `multiCharSearchDuration` of each other are combined for multi-character searching.
* @param {Event} evt
* @param {string} keyChar
* @private
*/
_keyboardSearch: function (evt, keyChar) {
var
matchedItem = null,
searchString,
numMatches = 0;
if (this._searchTimer) {
this._searchTimer.remove();
}
this._searchString += keyChar;
var allSameLetter = /^(.)\1*$/.test(this._searchString);
var searchLen = allSameLetter ? 1 : this._searchString.length;
searchString = this._searchString.substr(0, searchLen);
this._searchTimer = this.defer(function () { // this is the "success" timeout
this._searchTimer = null;
this._searchString = "";
}, this.multiCharSearchDuration);
var currentItem = this.focusedChild || null;
if (searchLen === 1 || !currentItem) {
currentItem = this._getNext(currentItem, 1); // skip current
if (!currentItem) {
return;
} // no items
}
var stop = currentItem;
do {
var rc = this._keyboardSearchCompare(currentItem, searchString);
if (!!rc && numMatches++ === 0) {
matchedItem = currentItem;
}
if (rc === -1) { // priority match
numMatches = -1;
break;
}
currentItem = this._getNext(currentItem, 1);
} while (currentItem !== stop);
this.onKeyboardSearch(matchedItem, evt, searchString, numMatches);
},
/**
* Returns the next or previous navigable child, relative to "child".
* If "child" is this, then it returns the first focusable child (when dir === 1)
* or last focusable child (when dir === -1).
* @param {Element} child - The current child Element.
* @param {number} dir - 1 = after, -1 = before
* @returns {Element}
* @protected
*/
_getNext: function (child, dir) {
var root = this, origChild = child;
function dfsNext(node) {
if (node.firstElementChild) { return node.firstElementChild; }
while (node !== root) {
if (node.nextElementSibling) { return node.nextElementSibling; }
node = node.parentNode;
}
return root; // loop around, plus corner case when no children
}
function dfsLast(node) {
while (node.lastElementChild) { node = node.lastElementChild; }
return node;
}
function dfsPrev(node) {
return node === root ? dfsLast(root) : // loop around, plus corner case when no children
(node.previousElementSibling && dfsLast(node.previousElementSibling)) || node.parentNode;
}
while (true) {
child = dir > 0 ? dfsNext(child) : dfsPrev(child);
if (child === origChild) {
return null; // looped back to original child
} else if (this._selectorFunc(child)) {
return child; // this child matches
}
}
}
});
});