/*

YUI 3.10.3 (build 2fb5187)

Copyright 2013 Yahoo! Inc. All rights reserved.

Licensed under the BSD License.

http://yuilibrary.com/license/

*/

YUI.add('node-focusmanager', function (Y, NAME) {

/**

* <p>The Focus Manager Node Plugin makes it easy to manage focus among

* a Node's descendants.  Primarily intended to help with widget development,

* the Focus Manager Node Plugin can be used to improve the keyboard

* accessibility of widgets.</p>

*

* <p>

* When designing widgets that manage a set of descendant controls (i.e. buttons

* in a toolbar, tabs in a tablist, menuitems in a menu, etc.) it is important to

* limit the number of descendants in the browser's default tab flow.  The fewer

* number of descendants in the default tab flow, the easier it is for keyboard

* users to navigate between widgets by pressing the tab key.  When a widget has

* focus it should provide a set of shortcut keys (typically the arrow keys)

* to move focus among its descendants.

* </p>

*

* <p>

* To this end, the Focus Manager Node Plugin makes it easy to define a Node's

* focusable descendants, define which descendant should be in the default tab

* flow, and define the keys that move focus among each descendant.

* Additionally, as the CSS

* <a href="http://www.w3.org/TR/CSS21/selector.html#x38"><code>:focus</code></a>

* pseudo class is not supported on all elements in all

* <a href="http://developer.yahoo.com/yui/articles/gbs/">A-Grade browsers</a>,

* the Focus Manager Node Plugin provides an easy, cross-browser means of

* styling focus.

* </p>

*

DEPRECATED: The FocusManager Node Plugin has been deprecated as of YUI 3.9.0. This module will be removed from the library in a future version. If you require functionality similar to the one provided by this  module, consider taking a look at the various modules in the YUI Gallery <http://yuilibrary.com/gallery/>. 

* @module node-focusmanager

* @deprecated 3.9.0

*/

	//	Frequently used strings

var ACTIVE_DESCENDANT = "activeDescendant",

	ID = "id",

	DISABLED = "disabled",

	TAB_INDEX = "tabIndex",

	FOCUSED = "focused",

	FOCUS_CLASS = "focusClass",

	CIRCULAR = "circular",

	UI = "UI",

	KEY = "key",

	ACTIVE_DESCENDANT_CHANGE = ACTIVE_DESCENDANT + "Change",

	HOST = "host",

	//	Collection of keys that, when pressed, cause the browser viewport

	//	to scroll.

	scrollKeys = {

		37: true,

		38: true,

		39: true,

		40: true

	},

	clickableElements = {

		"a": true,

		"button": true,

		"input": true,

		"object": true

	},

	//	Library shortcuts

	Lang = Y.Lang,

 	UA = Y.UA,

	/**

	* The NodeFocusManager class is a plugin for a Node instance.  The class is used

	* via the <a href="Node.html#method_plug"><code>plug</code></a> method of Node

	* and should not be instantiated directly.

	* @namespace plugin

	* @class NodeFocusManager

	*/

	NodeFocusManager = function () {

		NodeFocusManager.superclass.constructor.apply(this, arguments);

	};

NodeFocusManager.ATTRS = {

	/**

	* Boolean indicating that one of the descendants is focused.

	*

	* @attribute focused

	* @readOnly

	* @default false

	* @type boolean

	*/

	focused: {

		value: false,

		readOnly: true

	},

	/**

	* String representing the CSS selector used to define the descendant Nodes

	* whose focus should be managed.

	*

	* @attribute descendants

	* @type Y.NodeList

	*/

	descendants: {

		getter: function (value) {

			return this.get(HOST).all(value);

		}

	},

	/**

	* <p>Node, or index of the Node, representing the descendant that is either

	* focused or is focusable (<code>tabIndex</code> attribute is set to 0).

	* The value cannot represent a disabled descendant Node.  Use a value of -1

	* to remove all descendant Nodes from the default tab flow.

	* If no value is specified, the active descendant will be inferred using

	* the following criteria:</p>

	* <ol>

	* <li>Examining the <code>tabIndex</code> attribute of each descendant and

	* using the first descendant whose <code>tabIndex</code> attribute is set

	* to 0</li>

	* <li>If no default can be inferred then the value is set to either 0 or

	* the index of the first enabled descendant.</li>

	* </ol>

	*

	* @attribute activeDescendant

	* @type Number

	*/

	activeDescendant: {

		setter: function (value) {

			var isNumber = Lang.isNumber,

				INVALID_VALUE = Y.Attribute.INVALID_VALUE,

				descendantsMap = this._descendantsMap,

				descendants = this._descendants,

				nodeIndex,

				returnValue,

				oNode;

			if (isNumber(value)) {

				nodeIndex = value;

				returnValue = nodeIndex;

			}

			else if ((value instanceof Y.Node) && descendantsMap) {

				nodeIndex = descendantsMap[value.get(ID)];

				if (isNumber(nodeIndex)) {

					returnValue = nodeIndex;

				}

				else {

					//	The user passed a reference to a Node that wasn't one

					//	of the descendants.

					returnValue = INVALID_VALUE;

				}

			}

			else {

				returnValue = INVALID_VALUE;

			}

			if (descendants) {

				oNode = descendants.item(nodeIndex);

				if (oNode && oNode.get("disabled")) {

					//	Setting the "activeDescendant" attribute to the index

					//	of a disabled descendant is invalid.

					returnValue = INVALID_VALUE;

				}

			}

			return returnValue;

		}

	},

	/**

	* Object literal representing the keys to be used to navigate between the

	* next/previous descendant.  The format for the attribute's value is

	* <code>{ next: "down:40", previous: "down:38" }</code>.  The value for the

	* "next" and "previous" properties are used to attach

	* <a href="event/#keylistener"><code>key</code></a> event listeners. See

	* the <a href="event/#keylistener">Using the key Event</a> section of

	* the Event documentation for more information on "key" event listeners.

	*

	* @attribute keys

	* @type Object

	*/

	keys: {

		value: {

			next: null,

			previous: null

		}

	},

	/**

	* String representing the name of class applied to the focused active

	* descendant Node.  Can also be an object literal used to define both the

	* class name, and the Node to which the class should be applied.  If using

	* an object literal, the format is:

	* <code>{ className: "focus", fn: myFunction }</code>.  The function

	* referenced by the <code>fn</code> property in the object literal will be

	* passed a reference to the currently focused active descendant Node.

	*

	* @attribute focusClass

	* @type String|Object

	*/

	focusClass: { },

	/**

	* Boolean indicating if focus should be set to the first/last descendant

	* when the end or beginning of the descendants has been reached.

	*

	* @attribute circular

	* @type Boolean

	* @default true

	*/

	circular: {

		value: true

	}

};

Y.extend(NodeFocusManager, Y.Plugin.Base, {

	//	Protected properties

	//	Boolean indicating if the NodeFocusManager is active.

	_stopped: true,

	//	NodeList representing the descendants selected via the

	//	"descendants" attribute.

	_descendants: null,

	//	Object literal mapping the IDs of each descendant to its index in the

	//	"_descendants" NodeList.

	_descendantsMap: null,

	//	Reference to the Node instance to which the focused class (defined

	//	by the "focusClass" attribute) is currently applied.

	_focusedNode: null,

	//	Number representing the index of the last descendant Node.

	_lastNodeIndex: 0,

	//	Array of handles for event handlers used for a NodeFocusManager instance.

	_eventHandlers: null,

	//	Protected methods

	/**

	* @method _initDescendants

	* @description Sets the <code>tabIndex</code> attribute of all of the

	* descendants to -1, except the active descendant, whose

	* <code>tabIndex</code> attribute is set to 0.

	* @protected

	*/

	_initDescendants: function () {

		var descendants = this.get("descendants"),

			descendantsMap = {},

			nFirstEnabled = -1,

			nDescendants,

			nActiveDescendant = this.get(ACTIVE_DESCENDANT),

			oNode,

			sID,

			i = 0;

		if (Lang.isUndefined(nActiveDescendant)) {

			nActiveDescendant = -1;

		}

		if (descendants) {

			nDescendants = descendants.size();

            for (i = 0; i < nDescendants; i++) {

                oNode = descendants.item(i);

                if (nFirstEnabled === -1 && !oNode.get(DISABLED)) {

                    nFirstEnabled = i;

                }

                //	If the user didn't specify a value for the

                //	"activeDescendant" attribute try to infer it from

                //	the markup.

                //	Need to pass "2" when using "getAttribute" for IE to get

                //	the attribute value as it is set in the markup.

                //	Need to use "parseInt" because IE always returns the

                //	value as a number, whereas all other browsers return

                //	the attribute as a string when accessed

                //	via "getAttribute".

                if (nActiveDescendant < 0 &&

                        parseInt(oNode.getAttribute(TAB_INDEX, 2), 10) === 0) {

                    nActiveDescendant = i;

                }

                if (oNode) {

                    oNode.set(TAB_INDEX, -1);

                }

                sID = oNode.get(ID);

                if (!sID) {

                    sID = Y.guid();

                    oNode.set(ID, sID);

                }

                descendantsMap[sID] = i;

            }

            //	If the user didn't specify a value for the

            //	"activeDescendant" attribute and no default value could be

            //	determined from the markup, then default to 0.

            if (nActiveDescendant < 0) {

                nActiveDescendant = 0;

            }

            oNode = descendants.item(nActiveDescendant);

            //	Check to make sure the active descendant isn't disabled,

            //	and fall back to the first enabled descendant if it is.

            if (!oNode || oNode.get(DISABLED)) {

                oNode = descendants.item(nFirstEnabled);

                nActiveDescendant = nFirstEnabled;

            }

            this._lastNodeIndex = nDescendants - 1;

            this._descendants = descendants;

            this._descendantsMap = descendantsMap;

            this.set(ACTIVE_DESCENDANT, nActiveDescendant);

            //	Need to set the "tabIndex" attribute here, since the

            //	"activeDescendantChange" event handler used to manage

            //	the setting of the "tabIndex" attribute isn't wired up yet.

            if (oNode) {

                oNode.set(TAB_INDEX, 0);

            }

		}

	},

	/**

	* @method _isDescendant

	* @description Determines if the specified Node instance is a descendant

	* managed by the Focus Manager.

	* @param node {Node} Node instance to be checked.

	* @return {Boolean} Boolean indicating if the specified Node instance is a

	* descendant managed by the Focus Manager.

	* @protected

	*/

	_isDescendant: function (node) {

		return (node.get(ID) in this._descendantsMap);

	},

	/**

	* @method _removeFocusClass

	* @description Removes the class name representing focus (as specified by

	* the "focusClass" attribute) from the Node instance to which it is

	* currently applied.

	* @protected

	*/

	_removeFocusClass: function () {

		var oFocusedNode = this._focusedNode,

			focusClass = this.get(FOCUS_CLASS),

			sClassName;

		if (focusClass) {

			sClassName = Lang.isString(focusClass) ?

				focusClass : focusClass.className;

		}

		if (oFocusedNode && sClassName) {

			oFocusedNode.removeClass(sClassName);

		}

	},