/*

YUI 3.10.3 (build 2fb5187)

Copyright 2013 Yahoo! Inc. All rights reserved.

Licensed under the BSD License.

http://yuilibrary.com/license/

*/

YUI.add('widget-buttons', function (Y, NAME) {

/**

Provides header/body/footer button support for Widgets that use the

`WidgetStdMod` extension.

@module widget-buttons

@since 3.4.0

**/

var YArray  = Y.Array,

    YLang   = Y.Lang,

    YObject = Y.Object,

    ButtonPlugin = Y.Plugin.Button,

    Widget       = Y.Widget,

    WidgetStdMod = Y.WidgetStdMod,

    getClassName = Y.ClassNameManager.getClassName,

    isArray      = YLang.isArray,

    isNumber     = YLang.isNumber,

    isString     = YLang.isString,

    isValue      = YLang.isValue;

// Utility to determine if an object is a Y.Node instance, even if it was

// created in a different YUI sandbox.

function isNode(node) {

    return !!node.getDOMNode;

}

/**

Provides header/body/footer button support for Widgets that use the

`WidgetStdMod` extension.

This Widget extension makes it easy to declaratively configure a widget's

buttons. It adds a `buttons` attribute along with button- accessor and mutator

methods. All button nodes have the `Y.Plugin.Button` plugin applied.

This extension also includes `HTML_PARSER` support to seed a widget's `buttons`

from those which already exist in its DOM.

@class WidgetButtons

@extensionfor Widget

@since 3.4.0

**/

function WidgetButtons() {

    // Require `Y.WidgetStdMod`.

    if (!this._stdModNode) {

        Y.error('WidgetStdMod must be added to a Widget before WidgetButtons.');

    }

    // Has to be setup before the `initializer()`.

    this._buttonsHandles = {};

}

WidgetButtons.ATTRS = {

    /**

    Collection containing a widget's buttons.

    The collection is an Object which contains an Array of `Y.Node`s for every

    `WidgetStdMod` section (header, body, footer) which has one or more buttons.

    All button nodes have the `Y.Plugin.Button` plugin applied.

    This attribute is very flexible in the values it will accept. `buttons` can

    be specified as a single Array, or an Object of Arrays keyed to a particular

    section.

    All specified values will be normalized to this type of structure:

        {

            header: [...],

            footer: [...]

        }

    A button can be specified as a `Y.Node`, config Object, or String name for a

    predefined button on the `BUTTONS` prototype property. When a config Object

    is provided, it will be merged with any defaults provided by a button with

    the same `name` defined on the `BUTTONS` property.

    See `addButton()` for the detailed list of configuration properties.

    For convenience, a widget's buttons will always persist and remain rendered

    after header/body/footer content updates. Buttons should be removed by

    updating this attribute or using the `removeButton()` method.

    @example

        {

            // Uses predefined "close" button by string name.

            header: ['close'],

            footer: [

                {

                    name  : 'cancel',

                    label : 'Cancel',

                    action: 'hide'

                },

                {

                    name     : 'okay',

                    label    : 'Okay',

                    isDefault: true,

                    events: {

                        click: function (e) {

                            this.hide();

                        }

                    }

                }

            ]

        }

    @attribute buttons

    @type Object

    @default {}

    @since 3.4.0

    **/

    buttons: {

        getter: '_getButtons',

        setter: '_setButtons',

        value : {}

    },

    /**

    The current default button as configured through this widget's `buttons`.

    A button can be configured as the default button in the following ways:

      * As a config Object with an `isDefault` property:

        `{label: 'Okay', isDefault: true}`.

      * As a Node with a `data-default` attribute:

        `<button data-default="true">Okay</button>`.

    This attribute is **read-only**; anytime there are changes to this widget's

    `buttons`, the `defaultButton` will be updated if needed.

    **Note:** If two or more buttons are configured to be the default button,

    the last one wins.

    @attribute defaultButton

    @type Node

    @default null

    @readOnly

    @since 3.5.0

    **/

    defaultButton: {

        readOnly: true,

        value   : null

    }

};

/**

CSS classes used by `WidgetButtons`.

@property CLASS_NAMES

@type Object

@static

@since 3.5.0

**/

WidgetButtons.CLASS_NAMES = {

    button : getClassName('button'),

    buttons: Widget.getClassName('buttons'),

    primary: getClassName('button', 'primary')

};

WidgetButtons.HTML_PARSER = {

    buttons: function (srcNode) {

        return this._parseButtons(srcNode);

    }

};

/**

The list of button configuration properties which are specific to

`WidgetButtons` and should not be passed to `Y.Plugin.Button.createNode()`.

@property NON_BUTTON_NODE_CFG

@type Array

@static

@since 3.5.0

**/

WidgetButtons.NON_BUTTON_NODE_CFG = [

    'action', 'classNames', 'context', 'events', 'isDefault', 'section'

];

WidgetButtons.prototype = {

    // -- Public Properties ----------------------------------------------------

    /**

    Collection of predefined buttons mapped by name -> config.

    These button configurations will serve as defaults for any button added to a

    widget's buttons which have the same `name`.

    See `addButton()` for a list of possible configuration values.

    @property BUTTONS

    @type Object

    @default {}

    @see addButton()

    @since 3.5.0

    **/

    BUTTONS: {},

    /**

    The HTML template to use when creating the node which wraps all buttons of a

    section. By default it will have the CSS class: "yui3-widget-buttons".

    @property BUTTONS_TEMPLATE

    @type String

    @default "<span />"

    @since 3.5.0

    **/

    BUTTONS_TEMPLATE: '<span />',

    /**

    The default section to render buttons in when no section is specified.

    @property DEFAULT_BUTTONS_SECTION

    @type String

    @default Y.WidgetStdMod.FOOTER

    @since 3.5.0

    **/

    DEFAULT_BUTTONS_SECTION: WidgetStdMod.FOOTER,

    // -- Protected Properties -------------------------------------------------

    /**

    A map of button node `_yuid` -> event-handle for all button nodes which were

    created by this widget.

    @property _buttonsHandles

    @type Object

    @protected

    @since 3.5.0

    **/

    /**

    A map of this widget's `buttons`, both name -> button and

    section:name -> button.

    @property _buttonsMap

    @type Object

    @protected

    @since 3.5.0

    **/

    /**

    Internal reference to this widget's default button.

    @property _defaultButton

    @type Node

    @protected

    @since 3.5.0

    **/

    // -- Lifecycle Methods ----------------------------------------------------

    initializer: function () {

        // Creates button mappings and sets the `defaultButton`.

        this._mapButtons(this.get('buttons'));

        this._updateDefaultButton();

        // Bound with `Y.bind()` to make more extensible.

        this.after({

            buttonsChange      : Y.bind('_afterButtonsChange', this),

            defaultButtonChange: Y.bind('_afterDefaultButtonChange', this)

        });

        Y.after(this._bindUIButtons, this, 'bindUI');

        Y.after(this._syncUIButtons, this, 'syncUI');

    },

    destructor: function () {

        // Detach all event subscriptions this widget added to its `buttons`.

        YObject.each(this._buttonsHandles, function (handle) {

            handle.detach();

        });

        delete this._buttonsHandles;

        delete this._buttonsMap;

        delete this._defaultButton;

    },

    // -- Public Methods -------------------------------------------------------

    /**

    Adds a button to this widget.

    The new button node will have the `Y.Plugin.Button` plugin applied, be added

    to this widget's `buttons`, and rendered in the specified `section` at the

    specified `index` (or end of the section when no `index` is provided). If

    the section does not exist, it will be created.

    This fires the `buttonsChange` event and adds the following properties to

    the event facade:

      * `button`: The button node or config object to add.

      * `section`: The `WidgetStdMod` section (header/body/footer) where the

        button will be added.

      * `index`: The index at which the button will be in the section.

      * `src`: "add"

    **Note:** The `index` argument will be passed to the Array `splice()`

    method, therefore a negative value will insert the `button` that many items

    from the end. The `index` property on the `buttonsChange` event facade is

    the index at which the `button` was added.

    @method addButton

    @param {Node|Object|String} button The button to add. This can be a `Y.Node`

        instance, config Object, or String name for a predefined button on the

        `BUTTONS` prototype property. When a config Object is provided, it will

        be merged with any defaults provided by any `srcNode` and/or a button

        with the same `name` defined on the `BUTTONS` property. The following

        are the possible configuration properties beyond what Node plugins

        accept by default:

      @param {Function|String} [button.action] The default handler that should

        be called when the button is clicked. A String name of a Function that

        exists on the `context` object can also be provided. **Note:**

        Specifying a set of `events` will override this setting.

      @param {String|String[]} [button.classNames] Additional CSS classes to add

        to the button node.

      @param {Object} [button.context=this] Context which any `events` or

        `action` should be called with. Defaults to `this`, the widget.

        **Note:** `e.target` will access the button node in the event handlers.

      @param {Boolean} [button.disabled=false] Whether the button should be

        disabled.

      @param {String|Object} [button.events="click"] Event name, or set of

        events and handlers to bind to the button node. **See:** `Y.Node.on()`,

        this value is passed as the first argument to `on()`.

      @param {Boolean} [button.isDefault=false] Whether the button is the

        default button.

      @param {String} [button.label] The visible text/value displayed in the

        button.

      @param {String} [button.name] A name which can later be used to reference

        this button. If a button is defined on the `BUTTONS` property with this

        same name, its configuration properties will be merged in as defaults.

      @param {String} [button.section] The `WidgetStdMod` section (header, body,

        footer) where the button should be added.

      @param {Node} [button.srcNode] An existing Node to use for the button,

        default values will be seeded from this node, but are overriden by any

        values specified in the config object. By default a new <button>

        node will be created.

      @param {String} [button.template] A specific template to use when creating

        a new button node (e.g. "<a />"). **Note:** Specifying a `srcNode`

        will overide this.

    @param {String} [section="footer"] The `WidgetStdMod` section

        (header/body/footer) where the button should be added. This takes

        precedence over the `button.section` configuration property.

    @param {Number} [index] The index at which the button should be inserted. If

        not specified, the button will be added to the end of the section. This

        value is passed to the Array `splice()` method, therefore a negative

        value will insert the `button` that many items from the end.

    @chainable

    @see Plugin.Button.createNode()

    @since 3.4.0

    **/

    addButton: function (button, section, index) {

        var buttons = this.get('buttons'),

            sectionButtons, atIndex;

        // Makes sure we have the full config object.

        if (!isNode(button)) {

            button = this._mergeButtonConfig(button);

            section || (section = button.section);

        }

        section || (section = this.DEFAULT_BUTTONS_SECTION);

        sectionButtons = buttons[section] || (buttons[section] = []);

        isNumber(index) || (index = sectionButtons.length);

        // Insert new button at the correct position.

        sectionButtons.splice(index, 0, button);

        // Determine the index at which the `button` now exists in the array.

        atIndex = YArray.indexOf(sectionButtons, button);

        this.set('buttons', buttons, {

            button : button,

            section: section,

            index  : atIndex,

            src    : 'add'

        });

        return this;

    },

    /**

    Returns a button node from this widget's `buttons`.

    @method getButton

    @param {Number|String} name The string name or index of the button.

    @param {String} [section="footer"] The `WidgetStdMod` section

        (header/body/footer) where the button exists. Only applicable when

        looking for a button by numerical index, or by name but scoped to a

        particular section.

    @return {Node} The button node.

    @since 3.5.0

    **/

    getButton: function (name, section) {

        if (!isValue(name)) { return; }

        var map = this._buttonsMap,

            buttons;

        section || (section = this.DEFAULT_BUTTONS_SECTION);

        // Supports `getButton(1, 'header')` signature.

        if (isNumber(name)) {

            buttons = this.get('buttons');

            return buttons[section] && buttons[section][name];

        }

        // Looks up button by name or section:name.

        return arguments.length > 1 ? map[section + ':' + name] : map[name];

    },

    /**

    Removes a button from this widget.

    The button will be removed from this widget's `buttons` and its DOM. Any

    event subscriptions on the button which were created by this widget will be

    detached. If the content section becomes empty after removing the button

    node, then the section will also be removed.

    This fires the `buttonsChange` event and adds the following properties to

    the event facade:

      * `button`: The button node to remove.

      * `section`: The `WidgetStdMod` section (header/body/footer) where the

        button should be removed from.

      * `index`: The index at which the button exists in the section.

      * `src`: "remove"

    @method removeButton

    @param {Node|Number|String} button The button to remove. This can be a

        `Y.Node` instance, index, or String name of a button.

    @param {String} [section="footer"] The `WidgetStdMod` section

        (header/body/footer) where the button exists. Only applicable when

        removing a button by numerical index, or by name but scoped to a

        particular section.

    @chainable

    @since 3.5.0