basic-list-box.html

<!--
A single-selection list box that supports selection highlighting (using the
system highlight color) and keyboard navigation.

The user can select an item with the mouse/touch or keyboard: Up/Down, Page
Up/Down, Home/End.

Like other Basic Web Components, this can handle distributed content: you can
include a content element inside a basic-list-box, and the list will navigate
through the distributed content. Note: for the time being, if you do use basic-
list-box inside your own component, it appears that you'll need to wire up your
own keyboard navigation, and forward the list navigation keys to the basic-list-
box.

This component includes basic ARIA support to provide a reasonable default
experience, e.g., for screen readers. The list component itself will be assigned
an appropriate ARIA role (default is "listbox"). The ID of the selected item
will be reflected in an "aria-activedescendant" attribute applied to the list.
To support this feature, all items in the list need unique IDs. If an item does
not have an ID, basic-list-box will automatically assign a default ID.

The keyboard interaction model generally follows that of Microsoft Windows'
list boxes instead of those in OS X:

* The Page Up/Down and Home/End keys actually move the selection, rather than
  just scrolling the list. The former behavior seems more generally useful for
  keyboard users.

* Pressing Page Up/Down will move the selection to the topmost/bottommost
  visible item if the selection is not already there. Thereafter, the key will
  move the selection up/down by a page, and (per the above point) make the
  selected item visible.

Programmatically selecting an item (by setting the selected property) scrolls
the item into view.

The user can also select an item by typing the beginning of an item's text.

@element basic-list-box
@demo http://basic-web-components.github.io/basic-web-components/src/basic-list-box/?dom=shadow
-->

<link rel="import" href="../basic-aspect/basic-aspect.html">
<link rel="import" href="../basic-keyboard/basic-keyboard.html">
<link rel="import" href="../basic-keyboard-direction/basic-keyboard-direction.html">
<link rel="import" href="../basic-keyboard-paging/basic-keyboard-paging.html">
<link rel="import" href="../basic-keyboard-prefix-selection/basic-keyboard-prefix-selection.html">
<link rel="import" href="../basic-children-content/basic-children-content.html">
<link rel="import" href="../basic-content-items/basic-content-items.html">
<link rel="import" href="../basic-item-selection/basic-item-selection.html">
<link rel="import" href="../basic-tap-selection/basic-tap-selection.html">
<link rel="import" href="../basic-direction-selection/basic-direction-selection.html">
<link rel="import" href="../basic-accessible-list/basic-accessible-list.html">
<link rel="import" href="../basic-selection-highlight/basic-selection-highlight.html">
<link rel="import" href="../basic-selection-scroll/basic-selection-scroll.html">
<link rel="import" href="../basic-shared/basic-shared.html">

<dom-module id="basic-list-box">
  <template>

    <style>
    :host {
      display: -webkit-flex;
      display: flex;
      -webkit-tap-highlight-color: rgba(0, 0, 0, 0);
    }

    :host {
      --basic-list-box: {
        border: 1px solid gray;
        box-sizing: border-box;
        cursor: default;
      };
    }

    [target="child"] {
      display: -webkit-flex;
      display: flex;
      -webkit-flex: 1;
      flex: 1;
    }

    #itemsContainer {
      -webkit-flex: 1;
      flex: 1;
      -webkit-overflow-scrolling: touch;
      overflow-y: scroll; /* for momentum scrolling */
    }

    /* Generic appearance */
    :host([generic=""]) {
      @apply(--basic-list-box);
    }

    :host([generic=""]) #itemsContainer ::content > * {
      cursor: default;
      padding: 0.25em;
      -webkit-user-select: none;
      -moz-user-select: none;
      user-select: none;
    }
    </style>

    <basic-tap-selection target="child">
      <basic-children-content id="itemsContainer">
        <content></content>
      </basic-children-content>
    </basic-tap-selection>

  </template>
</dom-module>

<script>
Polymer({

  aspects: [
    Basic.AccessibleList,
    Basic.ContentItems,
    Basic.DirectionSelection,
    Basic.Keyboard,
    Basic.KeyboardDirection,
    Basic.KeyboardPaging,
    Basic.KeyboardPrefixSelection,
    Basic.ItemSelection,
    Basic.SelectionHighlight,
    Basic.SelectionScroll
  ],

  // attributeChanged: function(name, type) {
  //   console.log("changed", name);
  // },

  behaviors: [
    Basic.Aspect,
    Basic.Generic
  ],

  is: 'basic-list-box',

  /**
   * Returns the positional index for the indicated item.
   *
   * @method indexOfItem
   * @param {Object} item The item whose index is requested.
   * @returns {Number} The index of the item, or -1 if not found.
   */
  indexOfItem: function(item) {
    return this.collective.indexOfItem(item);
  },

  /**
   * The current set of items in the list.
   *
   * @property items
   * @type [Object]
   */
  get items() {
    return this.collective.items;
  },

  properties: {

    selectedIndex: {
      type: Number
    },

    selectedItem: {
      type: Object
    },

    target: {
      value: 'shadow'
    }

  },

  /**
   * Ensures the selected item is visible. This normally happens by default.
   * However, if the list box is hidden when the selection is changed, the
   * auto-scrolling feature won't apply. In that situation, call this method
   * after the list box becomes visible.
   *
   * @method scrollSelectedItemIntoView
   */
  scrollSelectedItemIntoView: function() {
    var item = this.collective.selectedItem;
    if (item) {
      this.collective.scrollItemIntoView(item);
    }
  },

  /**
   * The index of the item which is currently selected, or -1 if there is no
   * selection.
   *
   * @property selectedIndex
   * @type Number
   */
  get selectedIndex() {
    // See note at basic-item-selection's selectedIndex getter.
    if (this._readied) {
      return this.collective.selectedIndex;
    }
  },
  set selectedIndex(index) {
    this.collective.selectedIndex = index;
  },

  /**
   * The currently selected item, or null if there is no selection.
   *
   * @property selectedItem
   * @type Object
   */
  get selectedItem() {
    return this.collective.selectedItem;
  },
  set selectedItem(item) {
    this.collective.selectedItem = item;
  },

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

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

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

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

  /**
   * The text content of the selected item.
   *
   * Setting this to text not found in any list item will set selectedItem to
   * null.
   *
   * @property value
   * @type String
   */
  get value() {
    return this.selectedItem == null || this.selectedItem.textContent == null ?
      '' :
      this.selectedItem.textContent;
  },
  set value(text) {

    var currentIndex = this.selectedIndex;
    var newIndex = -1; // Assume we won't find the text.

    // Find the item with the indicated text.
    var items = this.items;
    for (i = 0, length = items.length; i < length; i++) {
      if (items[i].textContent === text) {
        newIndex = i;
        break;
      }
    }

    if (newIndex !== currentIndex) {
      this.selectedIndex = newIndex;
      var event = new CustomEvent('value-changed');
      this.dispatchEvent(event);
    }
  }

});

/*
 * The following comments document API members provided by mixins. Ideally these
 * docs will eventually be pulled from the mixin source files, but for now are
 * copied here by hand.
 */

/**
 * True if the component would like to receive generic styling.
 *
 * This property is true by default — set it to false to turn off all
 * generic styles. This makes it easier to apply custom styling; you won't
 * have to explicitly override styling you don't want.
 *
 * @property generic
 * @type Boolean
 * @default true
 */

/**
 * Fires when the items in the list change.
 *
 * @event items-changed
 */

/**
 * Fires when a new item has been selected.
 *
 * @event selected-item-changed
 * @param detail.selectedItem The new selected item.
 * @param detail.previousItem The previously selected item.
 */
</script>