/*

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

Code licensed under the BSD License:

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

version: 3.0.0b1

build: 1163

*/

YUI.add('widget', function(Y) {

/**

 * Provides the base Widget class

 *

 * @module widget

 */

// Local Constants

var L = Y.Lang,

    O = Y.Object,

    Node = Y.Node,

    ClassNameManager = Y.ClassNameManager,

    WIDGET = "widget",

    CONTENT = "content",

    VISIBLE = "visible",

    HIDDEN = "hidden",

    DISABLED = "disabled",

    FOCUSED = "focused",

    WIDTH = "width",

    HEIGHT = "height",

    EMPTY = "",

    HYPHEN = "-",

    BOUNDING_BOX = "boundingBox",

    CONTENT_BOX = "contentBox",

    PARENT_NODE = "parentNode",

    FIRST_CHILD = "firstChild",

    OWNER_DOCUMENT = "ownerDocument",

    BODY = "body",

	TAB_INDEX = "tabIndex",

    LOCALE = "locale",

    INIT_VALUE = "initValue",

    ID = "id",

    RENDER = "render",

    RENDERED = "rendered",

    DESTROYED = "destroyed",

    ContentUpdate = "contentUpdate",

    // Widget nodeid-to-instance map for now, 1-to-1.

    _instances = {};

/**

 * A base class for widgets, providing:

 * <ul>

 *    <li>The render lifecycle method, in addition to the init and destroy 

 *        lifecycle methods provide by Base</li>

 *    <li>Abstract methods to support consistent MVC structure across 

 *        widgets: renderer, renderUI, bindUI, syncUI</li>

 *    <li>Support for common widget attributes, such as boundingBox, contentBox, visible, 

 *        disabled, focused, strings</li>

 * </ul>

 *

 * @param config {Object} Object literal specifying widget configuration 

 * properties.

 *

 * @class Widget

 * @constructor

 * @extends Base

 */

function Widget(config) {

    Y.log('constructor called', 'life', 'widget');

    this._yuid = Y.guid(WIDGET);

    this._strings = {};

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

}

/**

 * The build configuration for the Widget class.

 * <p>

 * Defines the static fields which need to be aggregated,

 * when this class is used as the main class passed to 

 * the <a href="Base.html#method_build">Base.build</a> method.

 * </p>

 * @property _buildCfg

 * @type Object

 * @static

 * @final

 * @private

 */

Widget._buildCfg = {

    aggregates : ["HTML_PARSER"]

};

/**

 * Static property provides a string to identify the class.

 * <p>

 * Currently used to apply class identifiers to the bounding box 

 * and to classify events fired by the widget.

 * </p>

 *

 * @property Widget.NAME

 * @type String

 * @static

 */

Widget.NAME = WIDGET;

/**

 * Constant used to identify state changes originating from

 * the DOM (as opposed to the JavaScript model).

 *

 * @property Widget.UI_SRC

 * @type String

 * @static

 * @final

 */

Widget.UI_SRC = "ui";

var UI = Widget.UI_SRC;

/**

 * Static property used to define the default attribute 

 * configuration for the Widget.

 * 

 * @property Widget.ATTRS

 * @type Object

 * @static

 */

Widget.ATTRS = {

    /**

     * Flag indicating whether or not this object

     * has been through the render lifecycle phase.

     *

     * @attribute rendered

     * @readOnly

     * @default false

     * @type boolean

     */

    rendered: {

        value:false,

        readOnly:true

    },

    /**

    * @attribute boundingBox

    * @description The outermost DOM node for the Widget, used for sizing and positioning 

    * of a Widget as well as a containing element for any decorator elements used 

    * for skinning.

    * @type Node

    */

    boundingBox: {

        value:null,

        setter: function(node) {

            return this._setBoundingBox(node);

        },

        writeOnce: true

    },

    /**

    * @attribute contentBox

    * @description A DOM node that is a direct descendent of a Widget's bounding box that 

    * houses its content.

    * @type Node

    */

    contentBox: {

        value:null,

        setter: function(node) {

            return this._setContentBox(node);

        },

        writeOnce: true

    },

    /**

    * @attribute tabIndex

    * @description Number (between -32767 to 32767) indicating the widget's 

	* position in the default tab flow.  The value is used to set the 

	* "tabIndex" attribute on the widget's bounding box.  Negative values allow

	* the widget to receive DOM focus programmatically (by calling the focus

	* method), while being removed from the default tab flow.  A value of 

	* null removes the "tabIndex" attribute from the widget's bounding box.

    * @type Number

	* @default null

    */

    tabIndex: {

		value: 0,

		validator: function (val) {

            return (L.isNumber(val) || L.isNull(val));

        }

    },

    /**

    * @attribute focused

    * @description Boolean indicating if the Widget, or one of its descendants, 

	* has focus.

    * @readOnly

    * @default false

    * @type boolean

    */

    focused: {

        value: false,

        readOnly:true

    },

    /**

    * @attribute disabled

    * @description Boolean indicating if the Widget should be disabled. The disabled implementation

    * is left to the specific classes extending widget.

    * @default false

    * @type boolean

    */

    disabled: {

        value: false

    },

    /**

    * @attribute visible

    * @description Boolean indicating weather or not the Widget is visible.

    * @default true

    * @type boolean

    */

    visible: {

        value: true

    },

    /**

    * @attribute height

    * @description String with units, or number, representing the height of the Widget. If a number is provided,

    * the default unit, defined by the Widgets DEF_UNIT, property is used.

    * @default ""

    * @type {String | Number}

    */

    height: {

        value: EMPTY

    },

    /**

    * @attribute width

    * @description String with units, or number, representing the width of the Widget. If a number is provided,

    * the default unit, defined by the Widgets DEF_UNIT, property is used.

    * @default ""

    * @type {String | Number}

    */

    width: {

        value: EMPTY

    },

    /**

     * @attribute moveStyles

     * @description Flag defining whether or not style properties from the content box

     * should be moved to the bounding box when wrapped (as defined by the WRAP_STYLES property)

     * @default false

     * @type boolean

     */

    moveStyles: {

        value: false

    },

    /**

     * @attribute locale

     * @description

     * The default locale for the widget. NOTE: Using get/set on the "strings" attribute will

     * return/set strings for this locale.

     * @default "en"

     * @type String

     */

    locale : {

        value: "en"

    },

    /**

     * @attribute strings

     * @description Collection of strings used to label elements of the Widget's UI.

     * @default null

     * @type Object

     */

    strings: {

        setter: function(val) {

            return this._setStrings(val, this.get(LOCALE));

        },

        getter: function() {

            return this.getStrings(this.get(LOCALE));

        }

    }

};

/**

 * Cached lowercase version of Widget.NAME

 *

 * @property Widget._NAME_LOWERCASE

 * @private

 * @static

 */

Widget._NAME_LOWERCASE = Widget.NAME.toLowerCase();

/**

 * Generate a standard prefixed classname for the Widget, prefixed by the default prefix defined

 * by the <code>Y.config.classNamePrefix</code> attribute used by <code>ClassNameManager</code> and 

 * <code>Widget.NAME.toLowerCase()</code> (e.g. "yui-widget-xxxxx-yyyyy", based on default values for 

 * the prefix and widget class name).

 * <p>

 * The instance based version of this method can be used to generate standard prefixed classnames,

 * based on the instances NAME, as opposed to Widget.NAME. This method should be used when you

 * need to use a constant class name across different types instances.

 * </p>

 * @method getClassName

 * @param {String*} args* 0..n strings which should be concatenated, using the default separator defined by ClassNameManager, to create the class name

 */

Widget.getClassName = function() {

	var args = Y.Array(arguments, 0, true);

	args.splice(0, 0, this._NAME_LOWERCASE);

	return ClassNameManager.getClassName.apply(ClassNameManager, args);

};

/**

 * Returns the widget instance whose bounding box contains, or is, the given node. 

 * <p>

 * In the case of nested widgets, the nearest bounding box ancestor is used to

 * return the widget instance.

 * </p>

 * @method Widget.getByNode

 * @static

 * @param node {Node | String} The node for which to return a Widget instance. If a selector

 * string is passed in, which selects more than one node, the first node found is used.

 * @return {Widget} Widget instance, or null if not found.

 */

Widget.getByNode = function(node) {

    var widget,

        bbMarker = Widget.getClassName();

    node = Node.get(node);

    if (node) {

        node = (node.hasClass(bbMarker)) ? node : node.ancestor("." + bbMarker);

        if (node) {

            widget = _instances[node.get(ID)];

        }

    }

    return widget || null;

};

/**

 * Object hash, defining how attribute values are to be parsed from

 * markup contained in the widget's content box. e.g.:

 * <pre>

 *   {

 *       // Set single Node references using selector syntax 

 *       // (selector is run through node.query)

 *       titleNode: "span.yui-title",

 *       // Set NodeList references using selector syntax 

 *       // (array indicates selector is to be run through node.queryAll)

 *       listNodes: ["li.yui-item"],

 *       // Set other attribute types, using a parse function. 

 *       // Context is set to the widget instance.

 *       label: function(contentBox) {

 *           return contentBox.query("span.title").get("innerHTML");

 *       }

 *   }

 * </pre>

 * 

 * @property Widget.HTML_PARSER

 * @type Object

 * @static

 */

Widget.HTML_PARSER = {};

Y.extend(Widget, Y.Base, {

	/**

	 * Returns a class name prefixed with the the value of the 

	 * <code>YUI.config.classNamePrefix</code> attribute + the instances <code>NAME</code> property.

	 * Uses <code>YUI.config.classNameDelimiter</code> attribute to delimit the provided strings.

	 * e.g. 

	 * <code>

	 * <pre>

	 *    // returns "yui-slider-foo-bar", for a slider instance

	 *    var scn = slider.getClassName('foo','bar');

	 *

	 *    // returns "yui-overlay-foo-bar", for an overlay instance

	 *    var ocn = slider.getClassName('foo','bar');

	 * </pre>

	 * </code>

	 *

	 * @method getClassName

	 * @param {String}+ One or more classname bits to be joined and prefixed

	 */

	getClassName: function () {

		var args = Y.Array(arguments, 0, true);

		args.splice(0, 0, this._name);

		return ClassNameManager.getClassName.apply(ClassNameManager, args);

	},

    /**

     * Initializer lifecycle implementation for the Widget class. Registers the 

     * widget instance, and runs through the Widget's HTML_PARSER definition. 

     *

     * @method initializer

     * @protected

     * @param  config {Object} Configuration object literal for the widget

     */

    initializer: function(config) {

        Y.log('initializer called', 'life', 'widget');

        /**

         * Notification event, which widget implementations can fire, when

         * they change the content of the widget. This event has no default

         * behavior and cannot be prevented, so the "on" or "after"

         * moments are effectively equivalent (with on listeners being invoked before 

         * after listeners).

         * 

         * @event widget:contentUpdate

         * @preventable false

         * @param {EventFacade} e The Event Facade

         */

        this.publish(ContentUpdate, { preventable:false });

		this._name = this.constructor.NAME.toLowerCase();

        var nodeId = this.get(BOUNDING_BOX).get(ID);

        if (nodeId) {

            _instances[nodeId] = this;

        }

        var htmlConfig = this._parseHTML(this.get(CONTENT_BOX));

        if (htmlConfig) {

            Y.aggregate(config, htmlConfig, false);

        }

    },

    /**

     * Descructor lifecycle implementation for the Widget class. Purges events attached

     * to the bounding box (and all child nodes) and removes the Widget from the 

     * list of registered widgets.

     *

     * @method destructor

     * @protected

     */

    destructor: function() {

        Y.log('destructor called', 'life', 'widget');