/**
Adds mutation convenience methods such as `table.addRow(data)` to `Y.DataTable`. (or other built class).
@module datatable
@submodule datatable-mutable
@since 3.5.0
**/
var toArray = Y.Array,
    YLang   = Y.Lang,
    isString = YLang.isString,
    isArray  = YLang.isArray,
    isObject = YLang.isObject,
    isNumber = YLang.isNumber,
    arrayIndex = Y.Array.indexOf,
    Mutable;
/**
_API docs for this extension are included in the DataTable class._
Class extension to add mutation convenience methods to `Y.DataTable` (or other
built class).
Column mutation methods are paired with new custom events:
 * addColumn
 * removeColumn
 * modifyColumn
 * moveColumn
Row mutation events are bubbled from the DataTable's `data` ModelList through
the DataTable instance.
@class DataTable.Mutable
@for DataTable
@since 3.5.0
**/
Y.namespace('DataTable').Mutable = Mutable = function () {};
Mutable.ATTRS = {
    /**
    Controls whether `addRow`, `removeRow`, and `modifyRow` should trigger the
    underlying Model's sync layer by default.
    When `true`, it is unnecessary to pass the "sync" configuration property to
    those methods to trigger per-operation sync.
    @attribute autoSync
    @type {Boolean}
    @default `false`
    @since 3.5.0
    **/
    autoSync: {
        value: false,
        validator: YLang.isBoolean
    }
};
Y.mix(Mutable.prototype, {
    /**
    Adds the column configuration to the DataTable's `columns` configuration.
    If the `index` parameter is supplied, it is injected at that index.  If the
    table has nested headers, inject a subcolumn by passing an array of indexes
    to identify the new column's final location.
    The `index` parameter is required if adding a nested column.
    This method is a convienience method for fetching the DataTable's `columns`
    attribute, updating it, and calling 
    `table.set('columns', _updatedColumnsDefs_)`
    For example:
    <pre><code>// Becomes last column
    table.addColumn('name');
    // Inserted after the current second column, moving the current third column
    // to index 4
    table.addColumn({ key: 'price', formatter: currencyFormatter }, 2 );
    // Insert a new column in a set of headers three rows deep.  The index array
    // translates to
    // [ 2, --  in the third column's children
    //   1, --  in the second child's children
    //   3 ] -- as the fourth child column
    table.addColumn({ key: 'age', sortable: true }, [ 2, 1, 3 ]);
    </code></pre>
    @method addColumn
    @param {Object|String} config The new column configuration object
    @param {Number|Number[]} [index] the insertion index
    @return {DataTable}
    @chainable
    @since 3.5.0
    **/
    addColumn: function (config, index) {
        if (isString(config)) {
            config = { key: config };
        }
        if (config) {
            if (arguments.length < 2 || (!isNumber(index) && !isArray(index))) {
                index = this.get('columns').length;
            }
            this.fire('addColumn', {
                column: config,
                index: index
            });
        }
        return this;
    },
    /**
    Updates an existing column definition. Fires the `modifyColumn` event.
    For example:
    <pre><code>// Add a formatter to the existing 'price' column definition
    table.modifyColumn('price', { formatter: currencyFormatter });
    // Change the label on a header cell in a set of nested headers three rows
    // deep.  The index array translates to
    // [ 2,  -- in the third column's children
    //   1,  -- the second child
    //   3 ] -- the fourth child column
    table.modifyColumn([2, 1, 3], { label: 'Experience' });
    </code></pre>
    @method modifyColumn
    @param {String|Number|Number[]|Object} name The column key, name, index, or
                current configuration object
    @param {Object} config The new column configuration properties
    @return {DataTable}
    @chainable
    @since 3.5.0
    **/
    modifyColumn: function (name, config) {
        if (isString(config)) {
            config = { key: config };
        }
        if (isObject(config)) {
            this.fire('modifyColumn', {
                column: name,
                newColumnDef: config
            });
        }
        return this;
    },
    /**
    Moves an existing column to a new location. Fires the `moveColumn` event.
    The destination index can be a number or array of numbers to place a column
    header in a nested header row.
    @method moveColumn
    @param {String|Number|Number[]|Object} name The column key, name, index, or
                current configuration object
    @param {Number|Number[]} index The destination index of the column
    @return {DataTable}
    @chainable
    @since 3.5.0
    **/
    moveColumn: function (name, index) {
        if (name !== undefined && (isNumber(index) || isArray(index))) {
            this.fire('moveColumn', {
                column: name,
                index: index
            });
        }
        return this;
    },
    /**
    Removes an existing column. Fires the `removeColumn` event.
    @method removeColumn
    @param {String|Number|Number[]|Object} name The column key, name, index, or
                current configuration object
    @return {DataTable}
    @chainable
    @since 3.5.0
    **/
    removeColumn: function (name) {
        if (name !== undefined) {
            this.fire('removeColumn', {
                column: name
            });
        }
        return this;
    },
    /**
    Adds a new record to the DataTable's `data` ModelList.  Record data can be
    an object of field values or an instance of the DataTable's configured
    `recordType` class.
    This relays all parameters to the `data` ModelList's `add` method.
    If a configuration object is passed as a second argument, and that object
    has `sync: true` set, the underlying Model will be `save()`d.
    If the DataTable's `autoSync` attribute is set to `true`, the additional
    argument is not needed.
    If syncing and the last argument is a function, that function will be used
    as a callback to the Model's `save()` method.
    @method addRow
    @param {Object} data The data or Model instance for the new record
    @param {Object} [config] Configuration to pass along
    @param {Function} [callback] Callback function for Model's `save()`
      @param {Error|null} callback.err If an error occurred or validation
        failed, this parameter will contain the error. If the sync operation
        succeeded, _err_ will be `null`.
      @param {Any} callback.response The server's response. This value will
        be passed to the `parse()` method, which is expected to parse it and
        return an attribute hash.
    @return {DataTable}
    @chainable
    @since 3.5.0
    **/
    addRow: function (data, config) {
        // Allow autoSync: true + addRow({ data }, { sync: false })
        var sync = (config && ('sync' in config)) ?
                config.sync :
                this.get('autoSync'),
            models, model, i, len, args;
        if (data && this.data) {
            models = this.data.add.apply(this.data, arguments);
            if (sync) {
                models = toArray(models);
                args   = toArray(arguments, 1, true);
                for (i = 0, len = models.length; i < len; ++i) {
                    model = models[i];
                    if (model.isNew()) {
                        models[i].save.apply(models[i], args);
                    }
                }
            }
        }
        return this;
    },
    /**
    Removes a record from the DataTable's `data` ModelList.  The record can be
    provided explicitly or targeted by it's `id` (see ModelList's `getById`
    method), `clientId`, or index in the ModelList.
    After locating the target Model, this relays the Model and all other passed
    arguments to the `data` ModelList's `remove` method.
    If a configuration object is passed as a second argument, and that object
    has `sync: true` set, the underlying Model will be destroyed, passing
    `{ delete: true }` to trigger calling the Model's sync layer.
    If the DataTable's `autoSync` attribute is set to `true`, the additional
    argument is not needed.
    If syncing and the last argument is a function, that function will be used
    as a callback to the Model's `destroy()` method.
    @method removeRow
    @param {Object|String|Number} id The Model instance or identifier 
    @param {Object} [config] Configuration to pass along
    @param {Function} [callback] Callback function for Model's `save()`
      @param {Error|null} callback.err If an error occurred or validation
        failed, this parameter will contain the error. If the sync operation
        succeeded, _err_ will be `null`.
      @param {Any} callback.response The server's response. This value will
        be passed to the `parse()` method, which is expected to parse it and
        return an attribute hash.
    @return {DataTable}
    @chainable
    @since 3.5.0
    **/
    removeRow: function (id, config) {
        var modelList = this.data,
            // Allow autoSync: true + addRow({ data }, { sync: false })
            sync      = (config && ('sync' in config)) ?
                            config.sync :
                            this.get('autoSync'),
            models, model, i, len, args;
        // TODO: support removing via DOM element. This should be relayed to View
        if (isObject(id) && id instanceof this.get('recordType')) {
            model = id;
        } else if (modelList && id !== undefined) {
            model = modelList.getById(id) ||
                    modelList.getByClientId(id) ||
                    modelList.item(id);
        }
        if (model) {
            args = toArray(arguments, 1, true);
            models = modelList.remove.apply(modelList,
                [model].concat(args));
            if (sync) {
                if (!isObject(args[0])) {
                    args.unshift({});
                }
                args[0]['delete'] = true;
                models = toArray(models);
                for (i = 0, len = models.length; i < len; ++i) {
                    model = models[i];
                    model.destroy.apply(model, args);
                }
            }
        }
        return this;
    },
    /**
    Updates an existing record in the DataTable's `data` ModelList.  The record
    can be provided explicitly or targeted by it's `id` (see ModelList's
    `getById` method), `clientId`, or index in the ModelList.
    After locating the target Model, this relays the all other passed
    arguments to the Model's `setAttrs` method.
    If a configuration object is passed as a second argument, and that object
    has `sync: true` set, the underlying Model will be `save()`d.
    If the DataTable's `autoSync` attribute is set to `true`, the additional
    argument is not needed.
    If syncing and the last argument is a function, that function will be used
    as a callback to the Model's `save()` method.
    @method modifyRow
    @param {Object|String|Number} id The Model instance or identifier 
    @param {Object} data New data values for the Model
    @param {Object} [config] Configuration to pass along to `setAttrs()`
    @param {Function} [callback] Callback function for Model's `save()`
      @param {Error|null} callback.err If an error occurred or validation
        failed, this parameter will contain the error. If the sync operation
        succeeded, _err_ will be `null`.
      @param {Any} callback.response The server's response. This value will
        be passed to the `parse()` method, which is expected to parse it and
        return an attribute hash.
    @return {DataTable}
    @chainable
    @since 3.5.0
    **/
    modifyRow: function (id, data, config) {
        var modelList = this.data,
            // Allow autoSync: true + addRow({ data }, { sync: false })
            sync      = (config && ('sync' in config)) ?
                            config.sync :
                            this.get('autoSync'),
            model, args;
        if (isObject(id) && id instanceof this.get('recordType')) {
            model = id;
        } else if (modelList && id !== undefined) {
            model = modelList.getById(id) ||
                    modelList.getByClientId(id) ||
                    modelList.item(id);
        }
        if (model && isObject(data)) {
            args = toArray(arguments, 1, true);
            model.setAttrs.apply(model, args);
            if (sync && !model.isNew()) {
                model.save.apply(model, args);
            }
        }
        return this;
    },
    // --------------------------------------------------------------------------
    // Protected properties and methods
    // --------------------------------------------------------------------------
    /**
    Default function for the `addColumn` event.
    Inserts the specified column at the provided index.
    @method _defAddColumnFn
    @param {EventFacade} e The `addColumn` event
        @param {Object} e.column The new column definition object
        @param {Number|Number[]} e.index The array index to insert the new column
    @protected
    @since 3.5.0
    **/
    _defAddColumnFn: function (e) {
        var index   = toArray(e.index),
            columns = this.get('columns'),
            cols    = columns,
            i, len;
        for (i = 0, len = index.length - 1; cols && i < len; ++i) {
            cols = cols[index[i]] && cols[index[i]].children;
        }
        if (cols) {
            cols.splice(index[i], 0, e.column);
            this.set('columns', columns, { originEvent: e });
        } else { Y.log('addColumn index not findable', 'warn', 'datatable');
        }
    },
    /**
    Default function for the `modifyColumn` event.
    Mixes the new column properties into the specified column definition.
    @method _defModifyColumnFn
    @param {EventFacade} e The `modifyColumn` event
        @param {Object|String|Number|Number[]} e.column The column definition object or identifier
        @param {Object} e.newColumnDef The properties to assign to the column
    @protected
    @since 3.5.0
    **/
    _defModifyColumnFn: function (e) {
        var columns = this.get('columns'),
            column  = this.getColumn(e.column);
        if (column) {
            Y.mix(column, e.newColumnDef, true);
            
            this.set('columns', columns, { originEvent: e });
        } else { Y.log('Could not locate column index to modify column', 'warn', 'datatable');
        }
    },
    /**
    Default function for the `moveColumn` event.
    Removes the specified column from its current location and inserts it at the
    specified array index (may be an array of indexes for nested headers).
    @method _defMoveColumnFn
    @param {EventFacade} e The `moveColumn` event
        @param {Object|String|Number|Number[]} e.column The column definition object or identifier
        @param {Object} e.index The destination index to move to
    @protected
    @since 3.5.0
    **/
    _defMoveColumnFn: function (e) {
        var columns = this.get('columns'),
            column  = this.getColumn(e.column),
            toIndex = toArray(e.index),
            fromCols, fromIndex, toCols, i, len;
        if (column) {
            fromCols  = column._parent ? column._parent.children : columns;
            fromIndex = arrayIndex(fromCols, column);
            if (fromIndex > -1) {
                toCols = columns;
                for (i = 0, len = toIndex.length - 1; toCols && i < len; ++i) {
                    toCols = toCols[toIndex[i]] && toCols[toIndex[i]].children;
                }
                if (toCols) {
                    len = toCols.length;
                    fromCols.splice(fromIndex, 1);
                    toIndex = toIndex[i];
                    if (len > toCols.lenth) {
                        // spliced off the same array, so adjust destination
                        // index if necessary
                        if (fromIndex < toIndex) {
                            toIndex--;
                        }
                    }
                    toCols.splice(toIndex, 0, column);
                    this.set('columns', columns, { originEvent: e });
                } else { Y.log('Column [' + e.column + '] could not be moved. Destination index invalid for moveColumn', 'warn', 'datatable');
                }
            }
        } else { Y.log('Column [' + e.column + '] not found for moveColumn', 'warn', 'datatable');
        }
    },
    /**
    Default function for the `removeColumn` event.
    Splices the specified column from its containing columns array.
    @method _defRemoveColumnFn
    @param {EventFacade} e The `removeColumn` event
        @param {Object|String|Number|Number[]} e.column The column definition object or identifier
    @protected
    @since 3.5.0
    **/
    _defRemoveColumnFn: function (e) {
        var columns = this.get('columns'),
            column  = this.getColumn(e.column),
            cols, index;
        if (column) {
            cols = column._parent ? column._parent.children : columns;
            index = Y.Array.indexOf(cols, column);
            if (index > -1) {
                cols.splice(index, 1);
                this.set('columns', columns, { originEvent: e });
            }
        } else { Y.log('Could not locate column [' + e.column + '] for removeColumn', 'warn', 'datatable');
        }
    },
    /**
    Publishes the events used by the mutation methods:
     * addColumn
     * removeColumn
     * modifyColumn
     * moveColumn
    @method initializer
    @protected
    @since 3.5.0
    **/
    initializer: function () {
        this.publish({
            addColumn:    { defaultFn: Y.bind('_defAddColumnFn', this) },
            removeColumn: { defaultFn: Y.bind('_defRemoveColumnFn', this) },
            moveColumn:   { defaultFn: Y.bind('_defMoveColumnFn', this) },
            modifyColumn: { defaultFn: Y.bind('_defModifyColumnFn', this) }
        });
    }
});
/**
Adds an array of new records to the DataTable's `data` ModelList.  Record data
can be an array of objects containing field values or an array of instance of
the DataTable's configured `recordType` class.
This relays all parameters to the `data` ModelList's `add` method.
Technically, this is an alias to `addRow`, but please use the appropriately
named method for readability.
If a configuration object is passed as a second argument, and that object
has `sync: true` set, the underlying Models will be `save()`d.
If the DataTable's `autoSync` attribute is set to `true`, the additional
argument is not needed.
If syncing and the last argument is a function, that function will be used
as a callback to each Model's `save()` method.
@method addRows
@param {Object[]} data The data or Model instances to add
@param {Object} [config] Configuration to pass along
@param {Function} [callback] Callback function for each Model's `save()`
  @param {Error|null} callback.err If an error occurred or validation
    failed, this parameter will contain the error. If the sync operation
    succeeded, _err_ will be `null`.
  @param {Any} callback.response The server's response. This value will
    be passed to the `parse()` method, which is expected to parse it and
    return an attribute hash.
@return {DataTable}
@chainable
@since 3.5.0
**/
Mutable.prototype.addRows = Mutable.prototype.addRow;
// Add feature APIs to public Y.DataTable class
if (YLang.isFunction(Y.DataTable)) {
    Y.Base.mix(Y.DataTable, [Mutable]);
}
/**
Fired by the `addColumn` method.
@event addColumn
@preventable _defAddColumnFn
@param {Object} column The new column definition object
@param {Number|Number[]} index The array index to insert the new column
@since 3.5.0
**/
/**
Fired by the `removeColumn` method.
@event removeColumn
@preventable _defRemoveColumnFn
@param {Object|String|Number|Number[]} column The column definition object or identifier
@since 3.5.0
**/
/**
Fired by the `modifyColumn` method.
@event modifyColumn
@preventable _defModifyColumnFn
@param {Object|String|Number|Number[]} column The column definition object or identifier
@param {Object} newColumnDef The properties to assign to the column
@since 3.5.0
**/
/**
Fired by the `moveColumn` method.
@event moveColumn
@preventable _defMoveColumnFn
@param {Object|String|Number|Number[]} column The column definition object or identifier
@param {Object} index The destination index to move to
@since 3.5.0
**/