basic-item-selection.html

<!--
Aspect which manages selection semantics for items in a list.

@element basic-item-selection
-->

<link rel="import" href="../basic-aspect/basic-aspect.html">

<script>
/**
 * Fires when the selectedItem property changes.
 *
 * @event selected-item-changed
 * @param detail.selectedItem The new selected item.
 * @param detail.previousItem The previously selected item.
 */

/**
 * Fires when the selectedIndex property changes.
 *
 * @event selected-item-changed
 * @param detail.selectedIndex The new selected index.
 */

window.Basic = window.Basic || {};

window.Basic.ItemSelection = {

  contribute: {

    // Default implementations. These will typically be handled by other aspects
    // in the collective.
    applySelection: function(item, selected) {},

    get canSelectNext() {
      return this._canSelectNext;
    },
    set canSelectNext(canSelectNext) {
      this._canSelectNext = canSelectNext;
    },

    get canSelectPrevious() {
      return this._canSelectPrevious;
    },
    set canSelectPrevious(canSelectPrevious) {
      this._canSelectPrevious = canSelectPrevious;
    },

    itemAdded: function(item) {
      this.collective.applySelection(item, item === this.collective.selectedItem);
    },

    itemsChanged: function() {
      var index = this.collective.items.indexOf(this.collective.selectedItem);
      if (index < 0) {
        // Selected item is no longer in the current set of items.
        this.collective.selectedItem = null;
        if (this.collective.selectionRequired) {
          // Ensure selection, but do this in the next tick to give other
          // aspects a chance to do their own itemsChanged work.
          setTimeout(function() {
            this._ensureSelection();
          }.bind(this));
        }
      }
    },

    get selectedItem() {
      return this._selectedItem;
    },

    /**
     * The currently selected item, or null if there is no selection.
     *
     * @property selectedItem
     * @type Object
     */
    // TODO: Confirm item is in items before selecting.
    set selectedItem(item) {
      var previousItem = this._selectedItem;
      if (previousItem) {
        // Remove previous selection.
        this.collective.applySelection(previousItem, false);
      }
      this._selectedItem = item;
      if (item) {
        this.collective.applySelection(item, true);
      }

      // TODO: Rationalize with selectedIndex so we're not recalculating item
      // or index in each setter.
      var index = this.collective.indexOfItem(item);
      this._updatePossibleNavigations(index);

      var outermost = this.collective.outermostAttached;
      if (outermost) {
        var event = new CustomEvent('selected-item-changed', {
          bubbles: true,
          detail: {
            selectedItem: item,
            previousItem: previousItem,
            value: item // for Polymer binding
          }
        });
        outermost.dispatchEvent(event);
      }
    },

    /**
     * The index of the item which is currently selected, or -1 if there is no
     * selection.
     *
     * @property selectedIndex
     * @type Number
     */
    get selectedIndex() {
      var selectedItem = this.collective.selectedItem;

      if (selectedItem == null) {
        return -1;
      }

      // TODO: Memoize
      var index = this.collective.indexOfItem(selectedItem);

      // If index = -1, selection wasn't found. Most likely cause is that the
      // DOM was manipulated from underneath us.
      // TODO: Once we track content changes, turn this into an exception.
      return index;
    },

    set selectedIndex(index) {
      var items = this.collective.items;
      var item;
      if (index < 0 || items.length === 0) {
        item = null;
      } else {
        item = items[index];
      }
      this.collective.selectedItem = item;

      var outermost = this.collective.outermostAttached;
      if (outermost) {
        var event = new CustomEvent('selected-index-changed', {
          bubbles: true,
          detail: {
            selectedIndex: index,
            value: index // for Polymer binding
          }
        });
        outermost.dispatchEvent(event);
      }
    },

    /**
     * Select the first item in the list.
     *
     * @method selectFirst
     */
    selectFirst: function() {
      return this._selectIndex(0);
    },

    /**
     * True if the list should always have a selection (if it has items).
     *
     * @property selectionRequired
     * @type Boolean
     */
    get selectionRequired() {
      return this._selectionRequired;
    },
    set selectionRequired(selectionRequired) {
      this._selectionRequired = selectionRequired;
      this._ensureSelection();
    },

    /**
     * Select the last item in the list.
     *
     * @method selectLast
     */
    selectLast: function() {
      return this._selectIndex(this.collective.items.length - 1);
    },

    /**
     * Select the next item in the list.
     *
     * @method selectNext
     */
    selectNext: function() {
      return this._selectIndex(this.collective.selectedIndex + 1);
    },

    /**
     * Select the previous item in the list.
     *
     * @method selectPrevious
     */
    selectPrevious: function() {
      return this._selectIndex(this.collective.selectedIndex - 1);
    }


  },

  // If no item is selected, select a default item.
  // TODO: If the previously-selected item has been deleted, try to select an
  // item adjacent to the position it held.
  _ensureSelection: function() {
    if (!this.collective.selectedItem && this.collective.items && this.collective.items.length > 0) {
      this.collective.selectedIndex = 0;
    }
  },

  name: 'ItemSelection',

  // Ensure the given index is within bounds, and select it if it's not already
  // selected.
  _selectIndex: function(index) {
    var boundedIndex = Math.max(Math.min(index, this.collective.items.length - 1), 0);
    var previousIndex = this.collective.selectedIndex;
    if (previousIndex !== boundedIndex) {
      this.collective.selectedIndex = boundedIndex;
      return true;
    } else {
      return false;
    }
  },

  // Following a change in selection, report whether it's now possible to
  // go next/previous from the given index.
  _updatePossibleNavigations: function(index) {
    var canSelectNext;
    var canSelectPrevious;
    var items = this.collective.items;
    if (items == null || items.length === 0) {
      canSelectNext = false;
      canSelectPrevious = false;
    } else if (items.length === 1) {
      // Special case. If there's no selection, we declare that it's always
      // possible to go next/previous to create a selection.
      canSelectNext = true;
      canSelectPrevious = true;
    } else {
      // Normal case: we have an index in a list that has items.
      canSelectPrevious = (index > 0);
      canSelectNext = (index < items.length - 1);
    }
    this.collective.canSelectNext = canSelectNext;
    this.collective.canSelectPrevious = canSelectPrevious;
  },

  _selectedItem: null

};


Polymer({

  aspects: [Basic.ItemSelection],

  behaviors: [Basic.Aspect],

  is: 'basic-item-selection',

  properties: {

    selectedIndex: {
      type: Number
    },

    selectedItem: {
      type: Object
    },

    selectionRequired: {
      type: Boolean,
      observer: 'selectionRequiredChanged',
      value: false
    }

  },

  selectFirst: function() {
    this.collective.selectFirst();
  },

  selectionRequiredChanged: function(selectionRequired) {
    this.collective.selectionRequired = selectionRequired;
  },

  selectLast: function() {
    this.collective.selectLast();
  },

  selectNext: function() {
    this.collective.selectNext();
  },

  selectPrevious: function() {
    this.collective.selectPrevious();
  },

  get selectedIndex() {
    // HACK: Proxied getter/setter properties like this one can't be set via
    // attributes. See https://github.com/Polymer/polymer/issues/2454. We
    // currently hack around this by only returning a value for this property if
    // the element is ready. A negative side effect is that inspecting this
    // property before the element is ready will always return undefined.
    if (this._readied) {
      return this.collective.selectedIndex;
    }
  },

  get selectedItem() {
    return this.collective.selectedItem;
  }

});
</script>