<!--
Copyright 2013 The Polymer Authors. All rights reserved.
Use of this source code is governed by a BSD-style
license that can be found in the LICENSE file.
-->
<!--
/**
 * @module Polymer Elements
 */
-->
<!--
/**
 * The polymer-selection element is used to manage selection state. It has no
 * visual appearance and is typically used in conjuneciton with another element.
 * For example, <a href="polymer-selector.html">polymer-selector</a>
 * use a polymer-selection to manage selection.
 *
 * To mark an item as selected, call the select(item) method on 
 * polymer-selection. Notice that the item itself is an argument to this method.
 * The polymer-selection element manages selection state for any given set of
 * items. When an item is selected, the `polymer-select` event is fired.
 * The attribute "multi" indicates if multiple items can be selected at once.
 * 
 * Example:
 *
 *     <polymer-element name="selection-example">
 *        <template>
 *          <style>
 *            ::-webkit-distributed(> .selected) {
 *              font-weight: bold;
 *              font-style: italic;
 *            }
 *          </style>
 *          <ul on-tap="{{itemTapAction}}">
 *            <content></content>
 *          </ul>
 *          <polymer-selection id="selection" multi on-polymer-select="{{selectAction}}"></polymer-selection>
 *        </template>
 *        <script>
 *          Polymer('selection-example', {
 *            itemTapAction: function(e) {
 *              this.$.selection.select(e.target);
 *            },
 *            selectAction: function(e, detail) {
 *              detail.item.classList.toggle('selected', detail.isSelected);
 *            }
 *          });
 *        </script>
 *     </polymer-element>
 *
 *     <selection-example>
 *       <li>Red</li>
 *       <li>Green</li>
 *       <li>Blue</li>
 *     </selection-example>
 *
 * @class polymer-selection
 */
 /**
 * Fired when an item's selection state is changed. This event is fired both
 * when an item is selected or deselected. The `isSelected` detail property
 * contains the selection state.
 * 
 * @event polymer-select
 * @param {Object} detail
 *   @param {boolean} detail.isSelected true for selection and false for deselection
 *   @param {Object} detail.item the item element
 */
-->
<link rel="import" href="../polymer/polymer.html">

<polymer-element name="polymer-selection" attributes="multi">
  <template>
    <style>
      :host {
        display: none !important;
      }
    </style>
  </template>
  <script>
    Polymer('polymer-selection', {
      /**
       * If true, multiple selections are allowed.
       *
       * @attribute multi
       * @type boolean
       * @default false
       */
      multi: false,
      ready: function() {
        this.clear();
      },
      clear: function() {
        this.selection = [];
      },
      /**
       * Retrieves the selected item(s).
       * @method getSelection
       * @returns Returns the selected item(s). If the multi property is true,
       * getSelection will return an array, otherwise it will return 
       * the selected item or undefined if there is no selection.
      */
      getSelection: function() {
        return this.multi ? this.selection : this.selection[0];
      },
      /**
       * Indicates if a given item is selected.
       * @method isSelected
       * @param {any} item The item whose selection state should be checked.
       * @returns Returns true if `item` is selected.
      */
      isSelected: function(item) {
        return this.selection.indexOf(item) >= 0;
      },
      setItemSelected: function(item, isSelected) {
        if (item !== undefined && item !== null) {
          if (isSelected) {
            this.selection.push(item);
          } else {
            var i = this.selection.indexOf(item);
            if (i >= 0) {
              this.selection.splice(i, 1);
            }
          }
          this.fire("polymer-select", {isSelected: isSelected, item: item});
        }
      },
      /**
       * Set the selection state for a given `item`. If the multi property
       * is true, then the selected state of `item` will be toggled; otherwise
       * the `item` will be selected.
       * @method select
       * @param {any} item: The item to select.
      */
      select: function(item) {
        if (this.multi) {
          this.toggle(item);
        } else if (this.getSelection() !== item) {
          this.setItemSelected(this.getSelection(), false);
          this.setItemSelected(item, true);
        }
      },
      /**
       * Toggles the selection state for `item`.
       * @method toggle
       * @param {any} item: The item to toggle.
      */
      toggle: function(item) {
        this.setItemSelected(item, !this.isSelected(item));
      }
    });
  </script>
</polymer-element>