KeyNav.js

/** @module delite/KeyNav */
define([
	"dcl/dcl",
	"ibm-decor/sniff",
	"./on",
	"./scrollIntoView",
	"./Widget"
], function (
	dcl,
	has,
	on,
	scrollIntoView,
	Widget
) {
	/**
	 * Dispatched after the user has selected a different descendant, by clicking, arrow keys,
	 * or keyboard search.
	 * @example
	 * widget.on("keynav-child-navigated", function (evt) {
	 *	console.log("old value: " + evt.oldValue);
	 *	console.log("new value: " + evt.newValue);
	 * }
	 * @event module:delite/KeyNav#keynav-child-navigated
	 * @property {number} oldValue - The previously selected item.
	 * @property {number} newValue - The new selected item.
	 */

	/**
	 * 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)));
	}

	/**
	 * Return true if node is "clickable" via keyboard space / enter key:
	 *
	 * - buttons
	 * - links
	 * - checkboxes and radio buttons
	 *
	 * Does not [yet] handle aria equivalents (<div role=button> etc.).
	 *
	 * @param {Element} node
	 * @returns {boolean}
	 */
	function keyboardClickable (node) {
		return !node.readOnly && /^(button|a|input)$/i.test(node.nodeName);
	}

	// To workaround iOS VoiceOver bug, track when user has just closed a dropdown.
	var lastPopupHideTime = 0;
	if (has("ios")) {
		document.addEventListener("delite-after-hide", function () {
			lastPopupHideTime =  (new Date()).getTime();
		});
	}

	/**
	  * 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 one method for each keystroke that the subclass wants to handle.
	  *   The methods for up and down arrow keys are `upKeyHandler() and `downKeyHandler()`.
	  *   For BIDI support, the left and right arrows are handled specially, mapped to the `previousKeyHandler()`
	  *   and `nextKeyHandler()` methods in LTR mode, or reversed in RTL mode.
	  *   Otherwise, the method name is based on the key names
	  *   defined by https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key, for example `homeKeyHandler()`.
	  *   The method takes two parameters: the event, and the currently navigated node.
	  *   Most subclasses will want to implement either `previousKeyHandler()`
	  *   and `nextKeyHandler()`, or `downKeyHandler()` and `upKeyHandler()`.
	  *   The method should return true if the keystroke was handled, or false if not.
	  *   For backwards compatibility, not returning any value also indicates that the keystroke was handled.
	  * - Set all navigable descendants' initial tabIndex to "-1"; both initial descendants and any
	  *   descendants added later, by for example `addChild()`.  Exception: if `focusDescendants` is false then the
	  *   descendants shouldn't have any tabIndex at all.
	  * - Define `descendantSelector` as a function or string that identifies navigable child Elements.
	  * - If the descendant elements contain text, 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# */ {
		declaredClass: "delite/KeyNav",

		/**
		 * When true, focus the descendant widgets as the user navigates to them via arrow keys or keyboard letter
		 * search.  When false, rather than focusing the widgets, it merely sets `navigatedDescendant`,
		 * and sets the `d-active-descendant` class on the descendant widget the user has navigated to.
		 *
		 * False mode is intended for widgets like ComboBox where the focus is somewhere outside this widget
		 * (typically on an `<input>`) and keystrokes are merely being forwarded to the KeyNav widget.
		 *
		 * When set to false:
		 *
		 * - Navigable descendants shouldn't have any tabIndex (as opposed to having tabIndex=-1).
		 * - The focused element should specify `aria-owns` to point to this KeyNav Element.
		 * - The focused Element must be kept synced so that `aria-activedescendant` points to the currently
		 *   navigated descendant.  Do this responding to the `keynav-child-navigated` event emitted by this widget,
		 *   or by calling `observe()` and monitoring changed to `navigatedDescendant`.
		 * - The focused Element must forward keystrokes by calling `emit("keydown", ...)` and/or
		 *   `emit("keypress", ...)` on this widget.
		 * - You must somehow set the initial navigated descendant, typically by calling `navigateToFirst()` either
		 *   when the the dropdown is opened, or on the first call to `downKeyHandler()`.
		 * - You must have some CSS styling so that the currently navigated node is apparent.
		 *
		 * See http://www.w3.org/WAI/GL/wiki/Using_aria-activedescendant_to_allow_changes_in_focus_within_widgets_to_be_communicated_to_Assistive_Technology#Example_1:_Combobox
		 * for details.
		 * @member {boolean}
		 * @default true
		 * @protected
		 */
		focusDescendants: true,

		/**
		 * The currently navigated descendant, or null if there isn't one.
		 * @member {Element}
		 * @readonly
		 * @protected
		 */
		navigatedDescendant: null,

		/**
		 * Selector to identify which descendant 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.
		 *
		 * It's either a function that takes an Element parameter and returns true/false,
		 * or a CSS selector string, for example ".list-item".
		 *
		 * By default, the direct DOM children of this widget are considered the selectable descendants.
		 *
		 * @member {string|Function}
		 * @protected
		 * @constant
		 */
		descendantSelector: null,

		/**
		 * The node to receive the KeyNav behavior.
		 * Can be set in a template via a `attach-point` assignment.
		 * If missing, then `this.containerNode` or `this` will be used.
		 * If set, then subclass must set the tabIndex on this node rather than the root node.
		 * @member {Element}
		 * @protected
		 */
		keyNavContainerNode: null,

		/**
		 * Figure out effective navigable descendant of this event.
		 * @param {Event} evt
		 * @private
		 */
		_getTargetElement: function (evt) {
			for (var child = evt.target; child !== this; child = child.parentNode) {
				if (this.isNavigable(child)) {
					return child;
				}
			}
			return null;
		},

		afterInitializeRendering: function () {
			// If keyNavContainerNode unspecified, set to default value.
			if (!this.keyNavContainerNode) {
				this.keyNavContainerNode = this.containerNode || this;
			}

			// containerNode.focus() called when this is the first element in a Dialog (a11y.getFirstInTabbingOrder()).
			if (this.containerNode && this.containerNode !== this) {
				this.containerNode.focus = function () {
					// Focus first navigable descendant.
					this.focus();
				}.bind(this);
			}

			this.on("keypress", this._keynavKeyPressHandler.bind(this), this.keyNavContainerNode);
			this.on("keydown", this._keynavKeyDownHandler.bind(this), this.keyNavContainerNode);

			this.on("pointerdown", this.pointerdownHandler.bind(this), this.keyNavContainerNode);
			this.on("pointerup", this.pointerupHandler.bind(this), this.keyNavContainerNode);
			this.on("focusin", this.focusinHandler.bind(this), this.keyNavContainerNode);
			this.on("focusout", this.focusoutHandler.bind(this), this.keyNavContainerNode);
		},

		/**
		 * Test if specified element is navigable.
		 */
		isNavigable: function (elem) {
			// Setup function to check which child nodes are navigable.
			if (typeof this.descendantSelector === "string") {
				return elem.matches(this.descendantSelector);
			} else if (this.descendantSelector) {
				return this.descendantSelector(elem);
			} else {
				return elem.parentNode === this.containerNode;
			}
		},

		connectedCallback: dcl.after(function () {
			// If the user hasn't specified a tabindex declaratively, then set to default value.
			var container = this.keyNavContainerNode;
			if (this.focusDescendants && !container.hasAttribute("tabindex")) {
				container.tabIndex = "0";
			}
		}),

		/**
		 * Called on pointerdown event (on container or child of container).
		 */
		pointerdownHandler: function (evt) {
			// Focusin handler needs to differentiate between focusin from pointer or tab/shift-tab.
			this._pointerOperation = true;

			// Navigation occurs on pointerdown, to match behavior of native elements.
			// Normally this handler isn't needed as it's redundant w/the focusin event.
			var target = this._getTargetElement(evt);
			if (target) {
				this._descendantNavigateHandler(target, evt);
			}
		},

		/**
		 * Called on pointerup event (on container or child of container).
		 */
		pointerupHandler: function () {
			// Clear _pointerOperation after focusinHandler() has been called.  Note that 0ms is not long
			// enough in some cases on Firefox, although that problem doesn't reproduce in the delite tests.
			this.defer(function () {
				delete this._pointerOperation;
			}, 10);
		},

		/**
		 * Called on focus of container or child of container.
		 */
		focusinHandler: function (evt) {
			var container = this.keyNavContainerNode;
			if (this.focusDescendants) {
				// Compute if user tabbed into this widget.  lastPopupHideTime condition is for when user clicks a
				// button in a TooltipDialog and VoiceOver (due to a bug) focuses the checkbox etc. behind the
				// TooltipDialog.  That should not be treated as focus by tab.
				var now = (new Date()).getTime();
				var focusByTab = !this._pointerOperation && !this._programmaticallyFocusing &&
					now > lastPopupHideTime + 1000;

				if (focusByTab && !container.contains(evt.relatedTarget)) {
					// When tabbing/shift-tabbing into this widget, focus the first child but do it on a delay so that
					// activationTracker sees my "focus" event before seeing the "focus" event on the child widget.
					// Note that shift-tab (from outside this widget) might go to an embedded widget rather than
					// keyNavContainerNode.
					this.defer(this.focus);
				} else {
					// When container's descendant gets focus,
					// 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.
					// Also avoids Safari and Firefox problems with nested focusable elements.
					if (container.hasAttribute("tabindex")) {
						this._savedTabIndex = container.tabIndex;
						container.removeAttribute("tabindex");
					}

					// Handling for when navigatedDescendant or a node inside a navigableDescendant gets focus.
					var navigatedDescendant = this._getTargetElement(evt);
					if (navigatedDescendant) {
						if (evt.target === navigatedDescendant) {
							// If the navigable descendant itself is focused, then set tabIndex=0 so that tab and
							// shift-tab work correctly.
							navigatedDescendant.tabIndex = this._savedTabIndex;
						}

						// Note: when focus is moved outside the navigable descendant,
						// focusoutHandler() resets its tabIndex to -1.

						this._descendantNavigateHandler(navigatedDescendant, evt);
					}
				}
			}
		},

		/**
		 * Called on blur of container or child of container.
		 */
		focusoutHandler: function (evt) {
			if (this.focusDescendants) {
				// Note: don't use this.navigatedDescendant because it may or may not have already been
				// updated to point to the new descendant, depending on if navigation was by mouse
				// or keyboard.
				var previouslyNavigatedDescendant = this._getTargetElement(evt);
				if (previouslyNavigatedDescendant) {
					if (previouslyNavigatedDescendant !== evt.relatedTarget) {
						// If focus has moved outside of the previously navigated descendant, then set its
						// tabIndex back to -1, for future time when navigable descendant is clicked.
						previouslyNavigatedDescendant.tabIndex = "-1";
						previouslyNavigatedDescendant.classList.remove("d-active-descendant");

						if (this.navigatedDescendant === previouslyNavigatedDescendant) {
							this.navigatedDescendant = null;
						}
					}
				}

				// If focus has moved outside of container, then restore container's tabindex.
				if ("_savedTabIndex" in this && !this.keyNavContainerNode.contains(evt.relatedTarget)) {
					this.keyNavContainerNode.setAttribute("tabindex", this._savedTabIndex);
					delete this._savedTabIndex;
				}
			}
		},

		/**
		 * Called on home key.
		 * @param {Event} evt
		 * @param {Element} navigatedDescendant
		 * @protected
		 */
		homeKeyHandler: function (evt) {
			this.navigateToFirst(evt);
		},

		/**
		 * Called on end key.
		 * @param {Event} evt
		 * @param {Element} navigatedDescendant
		 * @protected
		 */
		endKeyHandler: function (evt) {
			this.navigateToLast(evt);
		},

		/**

		/**
		 * Default focus() implementation: navigate to the first navigable descendant.
		 * Note that if `focusDescendants` is false, this will merely set the `d-active-descendant` class
		 * rather than actually focusing the descendant.
		 */
		focus: function () {
			this.navigateToFirst();
		},

		/**
		 * Navigate to the first navigable descendant.
		 * Note that if `focusDescendants` is false, this will merely set the `d-active-descendant` class
		 * rather than actually focusing the descendant.
		 * @param {Event} [triggerEvent] - The event that lead to the navigation, or `undefined`
		 *     if the navigation is triggered programmatically.
		 * @protected
		 */
		navigateToFirst: function (triggerEvent) {
			this.navigateTo(this.getNext(this.keyNavContainerNode, 1), triggerEvent);
		},

		/**
		 * Navigate to the last navigable descendant.
		 * Note that if `focusDescendants` is false, this will merely set the `d-active-descendant` class
		 * rather than actually focusing the descendant.
		 * @param {Event} [triggerEvent] - The event that lead to the navigation, or `undefined`
		 *     if the navigation is triggered programmatically.
		 * @protected
		 */
		navigateToLast: function (triggerEvent) {
			this.navigateTo(this.getNext(this.keyNavContainerNode, -1), triggerEvent);
		},

		/**
		 * Navigate to the specified descendant.
		 * Note that if `focusDescendants` is false, this will merely set the `d-active-descendant` class
		 * rather than actually focusing the descendant.
		 * @param {Element} child - Reference to the descendant.
		 * @param {Event} [triggerEvent] - The event that lead to the navigation, or `undefined`
		 *     if the navigation is triggered programmatically.
		 * @protected
		 */
		navigateTo: function (child, triggerEvent) {
			if (this.focusDescendants) {
				// 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.keyNavContainerNode.tabIndex;
				this._programmaticallyFocusing = true;
				child.focus();
				delete this._programmaticallyFocusing;

				// _descendantNavigateHandler() will be called automatically from child's focus event.
			} else {
				scrollIntoView(child);
				this._descendantNavigateHandler(child, triggerEvent);
			}
		},

		/**
		 * Called when a child is navigated to, either by user clicking it, or programatically by arrow key handling
		 * code.  It marks that the specified child is the navigated one.
		 * @param {Element} child
		 * @param {Event} triggerEvent - The event that lead to the navigation, or `undefined`
		 *     if the navigation is triggered programmatically.
		 * @fires module:delite/KeyNav#keynav-child-navigated
		 * @private
		 */
		_descendantNavigateHandler: function (child, triggerEvent) {
			if (child && child !== this.navigatedDescendant) {
				if (this.navigatedDescendant) {
					this.navigatedDescendant.classList.remove("d-active-descendant");
					this.navigatedDescendant.tabIndex = "-1";
				}

				this.emit("keynav-child-navigated", {
					oldValue: this.navigatedDescendant,
					newValue: child,
					triggerEvent: triggerEvent
				});

				// mark that the new node is the currently navigated one
				this.navigatedDescendant = child;
				if (child) {
					child.classList.add("d-active-descendant");
				}
			}
		},

		_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 if necessary.
		 *
		 * @param {Element} item
		 * @param {Event} evt
		 * @param {string} searchString
		 * @param {number} numMatches
		 * @private
		 */
		_keyboardSearchHandler: function (item/*, evt, searchString, numMatches*/) {
			if (item) {
				this.navigateTo(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;
		},

		/**
		 * Called when keydown.  Ignores key events inside <input>, <button>, etc.,
		 * and passes the other events to the _processKeyDown() method.
		 * @param {Event} evt
		 * @private
		 */
		_keynavKeyDownHandler: function (evt) {
			// Ignore left, right, home, end, and space on <input> controls.
			if (takesInput(evt.target) &&
				(evt.key === "ArrowLeft" || evt.key === "ArrowRight" ||
				evt.key === "Home" || evt.key === "End" || evt.key === "Spacebar")) {
				return;
			}

			// Ignore space and enter on <button> elements.
			if (keyboardClickable(evt.target) && (evt.key === "Enter" || evt.key === "Spacebar")) {
				return;
			}

			this._processKeyDown(evt);
		},

		/**
		 * Called when there's a keydown event that should be handled by the KeyNav class.
		 * @param evt
		 * @private
		 */
		_processKeyDown: function (evt) {
			if (evt.key === "Spacebar" && this._searchTimer && !(evt.ctrlKey || evt.altKey || evt.metaKey)) {
				// If the user types some string like "new york", interpret the space as part of the search rather
				// than to perform some action, even if there is a key handler method defined.

				// Stop IE from scrolling, and most browsers (except FF) from emitting keypress event.
				evt.preventDefault();

				this._keyboardSearch(evt, " ");
			} else {
				// Otherwise call the handler specified in this.keyHandlers.
				this._applyKeyHandler(evt);
			}
		},

		/**
		 * If the class has defined a method to handle the specified key, then call it.
		 * See the description of `KeyNav` for details on how to define methods.
		 * @param {Event} evt
		 * @private
		 */
		_applyKeyHandler: function (evt) {
			// Get name of method to call
			var methodName;
			switch (evt.key) {
			case "ArrowLeft":
				methodName = this.effectiveDir === "rtl" ? "nextKeyHandler" : "previousKeyHandler";
				break;
			case "ArrowRight":
				methodName = this.effectiveDir === "rtl" ? "previousKeyHandler" : "nextKeyHandler";
				break;
			case "ArrowUp":
			case "ArrowDown":
				methodName = evt.key.charAt(5).toLowerCase() + evt.key.substr(6) + "KeyHandler";
				break;
			default:
				methodName = evt.key.charAt(0).toLowerCase() + evt.key.substr(1) + "KeyHandler";
			}

			// Call it
			var func = this[methodName];
			if (func) {
				var handled = func.call(this, evt, this.navigatedDescendant);

				// Cancel the event if the handler function returns true, or, for backwards compatibility,
				// if it doesn't return a value at all.
				if (handled !== false) {
					evt.stopPropagation();
					evt.preventDefault();
				}

				this._searchString = ""; // so a DOWN_ARROW b doesn't search for ab
			}
		},

		/**
		 * When a printable key is pressed, it's handled here, searching by letter.
		 * @param {Event} evt
		 * @private
		 */
		_keynavKeyPressHandler: 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 _keynavKeyDownHandler.
			if (takesInput(evt.target) || evt.charCode <= 32 || evt.ctrlKey || evt.altKey || evt.metaKey) {
				return;
			}

			evt.preventDefault();
			evt.stopPropagation();

			this._keyboardSearch(evt, evt.key.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.navigatedDescendant || 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._keyboardSearchHandler(matchedItem, evt, searchString, numMatches);
		},

		/**
		 * Returns the next or previous navigable descendant, relative to "child".
		 * If "child" is this, then it returns the first focusable descendant (when dir === 1)
		 * or last focusable descendant (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 container = this.keyNavContainerNode, origChild = child;
			function dfsNext (node) {
				if (node.firstElementChild) { return node.firstElementChild; }
				while (node !== container) {
					if (node.nextElementSibling) { return node.nextElementSibling; }
					node = node.parentNode;
				}
				return container;	// loop around, plus corner case when no children
			}
			function dfsLast (node) {
				while (node.lastElementChild) { node = node.lastElementChild; }
				return node;
			}
			function dfsPrev (node) {
				return node === container ? dfsLast(container) : // 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.isNavigable(child)) {
					return child;	// this child matches
				}
			}
		}
	});
});