/*

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('dom-base', function(Y) {

(function(Y) {

/** 

 * The DOM utility provides a cross-browser abtraction layer

 * normalizing DOM tasks, and adds extra helper functionality

 * for other common tasks. 

 * @module dom

 * @submodule dom-base

 *

 */

/**

 * Provides DOM helper methods.

 * @class DOM

 *

 */

var NODE_TYPE = 'nodeType',

    OWNER_DOCUMENT = 'ownerDocument',

    DOCUMENT_ELEMENT = 'documentElement',

    DEFAULT_VIEW = 'defaultView',

    PARENT_WINDOW = 'parentWindow',

    TAG_NAME = 'tagName',

    PARENT_NODE = 'parentNode',

    FIRST_CHILD = 'firstChild',

    LAST_CHILD = 'lastChild',

    PREVIOUS_SIBLING = 'previousSibling',

    NEXT_SIBLING = 'nextSibling',

    CONTAINS = 'contains',

    COMPARE_DOCUMENT_POSITION = 'compareDocumentPosition',

    re_tag = /<([a-z]+)/i;

Y.DOM = {

    /**

     * Returns the HTMLElement with the given ID (Wrapper for document.getElementById).

     * @method byId         

     * @param {String} id the id attribute 

     * @param {Object} doc optional The document to search. Defaults to current document 

     * @return {HTMLElement | null} The HTMLElement with the id, or null if none found. 

     */

    byId: function(id, doc) {

        doc = doc || Y.config.doc;

        // TODO: IE Name

        return doc.getElementById(id);

    },

    /**

     * Returns the text content of the HTMLElement. 

     * @method getText         

     * @param {HTMLElement} element The html element. 

     * @return {String} The text content of the element (includes text of any descending elements).

     */

    getText: (document.documentElement.textContent !== undefined) ?

        function(element) {

            var ret = '';

            if (element) {

                ret = element.textContent;

            }

            return ret || '';

        } : function(element) {

            var ret = '';

            if (element) {

                ret = element.innerText;

            }

            return ret || '';

        },

    /**

     * Sets the text content of the HTMLElement. 

     * @method setText         

     * @param {HTMLElement} element The html element. 

     * @param {String} content The content to add. 

     */

    setText: (document.documentElement.textContent !== undefined) ?

        function(element, content) {

            if (element) {

                element.textContent = content;

            }

        } : function(element, content) {

            if (element) {

                element.innerText = content;

            }

        },

// TODO: pull out sugar (rely on _childBy, byAxis, etc)?

    /*

     * Finds the firstChild of the given HTMLElement. 

     * @method firstChild

     * @deprecated Use _childBy

     * @param {HTMLElement} element The html element. 

     * @param {Function} fn optional An optional boolean test to apply.

     * The optional function is passed the current HTMLElement being tested as its only argument.

     * If no function is given, the first found is returned.

     * @return {HTMLElement | null} The first matching child html element.

     */

    firstChild: function(element, fn) {

        return Y.DOM._childBy(element, null, fn);

    },

    // @deprecated Use _childBy

    firstChildByTag: function(element, tag, fn) {

        return Y.DOM._childBy(element, tag, fn);

    },

    /*

     * Finds the lastChild of the given HTMLElement.

     * @method lastChild

     * @deprecated Use _childBy

     * @param {HTMLElement} element The html element.

     * @param {String} tag The tag to search for.

     * @param {Function} fn optional An optional boolean test to apply.

     * The optional function is passed the current HTMLElement being tested as its only argument.

     * If no function is given, the first found is returned.

     * @return {HTMLElement | null} The first matching child html element.

     */

    lastChild: function(element, fn) {

        return Y.DOM._childBy(element, null, fn, true);

    },

    // @deprecated Use _childBy

    lastChildByTag: function(element, tag, fn) {

        return Y.DOM._childBy(element, tag, fn, true);

    },

    /*

     * Finds all HTMLElement childNodes matching the given tag.

     * @method childrenByTag

     * @deprecated Use Selector

     * @param {HTMLElement} element The html element.

     * @param {String} tag The tag to search for.

     * @param {Function} fn optional An optional boolean test to apply.

     * The optional function is passed the current HTMLElement being tested as its only argument.

     * If no function is given, all children with the given tag are collected.

     * @return {Array} The collection of child elements.

     * TODO: Webkit children.tags() returns grandchildren

     */

    _childrenByTag: function() {

        if (document[DOCUMENT_ELEMENT].children) {

            return function(element, tag, fn, toArray) { // TODO: keep toArray option?

                tag = (tag && tag !== '*') ? tag.toUpperCase() : null;

                var elements = [],

                    wrapFn = fn;

                if (element) {

                    if (tag && !Y.UA.webkit) { // children.tags() broken in safari

                        elements = element.children.tags(tag);

                    } else {

                        elements = element.children;

                        if (tag) {

                            wrapFn = function(el) {

                                return el[TAG_NAME].toUpperCase() === tag && (!fn || fn(el));

                            };

                        }

                    }

                    elements = Y.DOM.filterElementsBy(elements, wrapFn);

                }

                return elements;

            };

        } else {

            return function(element, tag, fn) {

                tag = (tag && tag !== '*') ? tag.toUpperCase() : null;

                var elements = [],

                    wrapFn = fn;

                if (element) {

                    elements = element.childNodes; 

                    if (tag) { // wrap fn and add tag test TODO: allow tag in filterElementsBy?

                        wrapFn = function(el) {

                            return el[TAG_NAME].toUpperCase() === tag && (!fn || fn(el));

                        };

                    }

                    elements = Y.DOM.filterElementsBy(elements, wrapFn);

                }

                return elements;

            };

        }

    }(),

    /*

     * Finds all HTMLElement childNodes.

     * @method children

     * @deprecated Use Selector

     * @param {HTMLElement} element The html element.

     * @param {Function} fn optional An optional boolean test to apply.

     * The optional function is passed the current HTMLElement being tested as its only argument.

     * If no function is given, all children are collected.

     * @return {Array} The collection of child elements.

     */

    children: function(element, fn) {

        return Y.DOM._childrenByTag(element, null, fn);

    },

    /*

     * Finds the previous sibling of the element.

     * @method previous

     * @deprecated Use elementByAxis

     * @param {HTMLElement} element The html element.

     * @param {Function} fn optional An optional boolean test to apply.

     * The optional function is passed the current DOM node being tested as its only argument.

     * If no function is given, the first sibling is returned.

     * @param {Boolean} all optional Whether all node types should be scanned, or just element nodes.

     * @return {HTMLElement | null} The matching DOM node or null if none found. 

     */

    previous: function(element, fn, all) {

        return Y.DOM.elementByAxis(element, PREVIOUS_SIBLING, fn, all);

    },

    /*

     * Finds the next sibling of the element.

     * @method next

     * @deprecated Use elementByAxis

     * @param {HTMLElement} element The html element.

     * @param {Function} fn optional An optional boolean test to apply.

     * The optional function is passed the current DOM node being tested as its only argument.

     * If no function is given, the first sibling is returned.

     * @param {Boolean} all optional Whether all node types should be scanned, or just element nodes.

     * @return {HTMLElement | null} The matching DOM node or null if none found. 

     */

    next: function(element, fn, all) {

        return Y.DOM.elementByAxis(element, NEXT_SIBLING, fn, all);

    },

    /*

     * Finds the ancestor of the element.

     * @method ancestor

     * @deprecated Use elementByAxis

     * @param {HTMLElement} element The html element.

     * @param {Function} fn optional An optional boolean test to apply.

     * The optional function is passed the current DOM node being tested as its only argument.

     * If no function is given, the parentNode is returned.

     * @param {Boolean} all optional Whether all node types should be scanned, or just element nodes.

     * @return {HTMLElement | null} The matching DOM node or null if none found. 

     */

     // TODO: optional stopAt node?

    ancestor: function(element, fn, all) {

        return Y.DOM.elementByAxis(element, PARENT_NODE, fn, all);

    },

    /**

     * Searches the element by the given axis for the first matching element.

     * @method elementByAxis

     * @param {HTMLElement} element The html element.

     * @param {String} axis The axis to search (parentNode, nextSibling, previousSibling).

     * @param {Function} fn optional An optional boolean test to apply.

     * @param {Boolean} all optional Whether all node types should be returned, or just element nodes.

     * The optional function is passed the current HTMLElement being tested as its only argument.

     * If no function is given, the first element is returned.

     * @return {HTMLElement | null} The matching element or null if none found.

     */

    elementByAxis: function(element, axis, fn, all) {

        while (element && (element = element[axis])) { // NOTE: assignment

                if ( (all || element[TAG_NAME]) && (!fn || fn(element)) ) {

                    return element;

                }

        }

        return null;

    },

    /*

     * Finds all elements with the given tag.

     * @method byTag

     * @deprecated Use Selector

     * @param {String} tag The tag being search for. 

     * @param {HTMLElement} root optional An optional root element to start from.

     * @param {Function} fn optional An optional boolean test to apply.

     * The optional function is passed the current HTMLElement being tested as its only argument.

     * If no function is given, all elements with the given tag are returned.

     * @return {Array} The collection of matching elements.

     */

    byTag: function(tag, root, fn) {

        root = root || Y.config.doc;

        var elements = root.getElementsByTagName(tag),

            retNodes = [],

            i, len;

        for (i = 0, len = elements.length; i < len; ++i) {

            if ( !fn || fn(elements[i]) ) {

                retNodes[retNodes.length] = elements[i];

            }

        }

        return retNodes;

    },

    /*

     * Finds the first element with the given tag.

     * @method firstByTag

     * @deprecated Use Selector

     * @param {String} tag The tag being search for. 

     * @param {HTMLElement} root optional An optional root element to start from.

     * @param {Function} fn optional An optional boolean test to apply.

     * The optional function is passed the current HTMLElement being tested as its only argument.

     * If no function is given, the first match is returned. 

     * @return {HTMLElement} The matching element.

     */

    firstByTag: function(tag, root, fn) {

        root = root || Y.config.doc;

        var elements = root.getElementsByTagName(tag),

            ret = null,

            i, len;

        for (i = 0, len = elements.length; i < len; ++i) {

            if ( !fn || fn(elements[i]) ) {

                ret = elements[i];

                break;

            }

        }

        return ret;

    },

    /*

     * Filters a collection of HTMLElements by the given attributes.

     * @method filterElementsBy

     * @param {Array} elements The collection of HTMLElements to filter.

     * @param {Function} fn A boolean test to apply.

     * The function is passed the current HTMLElement being tested as its only argument.

     * If no function is given, all HTMLElements are kept.

     * @return {Array} The filtered collection of HTMLElements.

     */

    filterElementsBy: function(elements, fn, firstOnly) {

        var ret = (firstOnly) ? null : [],

            i, len;

        for (i = 0, len = elements.length; i < len; ++i) {

            if (elements[i][TAG_NAME] && (!fn || fn(elements[i]))) {

                if (firstOnly) {

                    ret = elements[i];

                    break;

                } else {

                    ret[ret.length] = elements[i];

                }

            }

        }

        return ret;

    },

    /**

     * Determines whether or not one HTMLElement is or contains another HTMLElement.

     * @method contains

     * @param {HTMLElement} element The containing html element.

     * @param {HTMLElement} needle The html element that may be contained.

     * @return {Boolean} Whether or not the element is or contains the needle.

     */

    contains: function(element, needle) {

        var ret = false;

        if ( !needle || !element || !needle[NODE_TYPE] || !element[NODE_TYPE]) {

            ret = false;

        } else if (element[CONTAINS])  {

            if (Y.UA.opera || needle[NODE_TYPE] === 1) { // IE & SAF contains fail if needle not an ELEMENT_NODE

                ret = element[CONTAINS](needle);

            } else {

                ret = Y.DOM._bruteContains(element, needle); 

            }

        } else if (element[COMPARE_DOCUMENT_POSITION]) { // gecko

            if (element === needle || !!(element[COMPARE_DOCUMENT_POSITION](needle) & 16)) { 

                ret = true;

            }

        }

        return ret;

    },

    /**

     * Determines whether or not the HTMLElement is part of the document.

     * @method inDoc

     * @param {HTMLElement} element The containing html element.

     * @param {HTMLElement} doc optional The document to check.

     * @return {Boolean} Whether or not the element is attached to the document. 

     */

    inDoc: function(element, doc) {

        doc = doc || element[OWNER_DOCUMENT];

        var id = element.id;

        if (!id) { // TODO: remove when done?

            id = element.id = Y.guid();

        }

        return !! (doc.getElementById(id));

    },

    /**

     * Inserts the new node as the previous sibling of the reference node 

     * @method insertBefore

     * @param {String | HTMLElement} newNode The node to be inserted