/*

Copyright (c) 2009, Yahoo! Inc. All rights reserved.

Code licensed under the BSD License:

http://developer.yahoo.net/yui/license.txt

version: 3.0.0

build: 1549

*/

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

/**

* <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>

*  

* @module node-focusmanager

*/

	//	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

	*/

	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();

			if (nDescendants > 1) {

				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;

					}

					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.

				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);

		}

	},

	/**

	* @method _detachKeyHandler