basic-carousel.html

<!--
Lets the user navigate laterally through a sequence of child elements.

basic-carousel is an implementation of the carousel user interface pattern,
commonly used for navigating between images, pages, and other elements.
This pattern presents the user with a linear sequence of elements, only one of
which is shown at a time. The user can navigate to the next/previous element
with a variety of input methods.

basic-carousel uses its children as the elements the user will navigate through.
In a typical use, a basic-carousel can be used to navigate between a sequence of
images:

    <basic-carousel>
      <img src="image1.jpg">
      <img src="image2.jpg">
      <img src="image3.jpg">
    </basic-carousel>

The child elements can be of any type — they are not restricted to images.

This component attempts to meet the [Gold Standard for web components]
(https://github.com/webcomponents/gold-standard/wiki) so that it is generally
as flexible and robust as standard HTML elements. For example, it meets the
"Content Changes" criteria: the carousel will adapt to new child elements added
or removed at runtime.

Currently, this component does not meet the Gold Standard criteria "Size to
Content". As a result, for the time being, **you must manually set a size on
this component**. Two approaches are to: 1) stretch the component across
whatever surface it is contained within, or 2) set it to be larger than the
largest child element you want to display. The former approach is more common,
and can be achieved with CSS styling such as:

    html {
      height: 100%;
    }

    body {
      display: -webkit-flex;
      display: flex;
      height: 100%;
      margin: 0;
    }

    basic-carousel {
      -webkit-flex: 1;
      flex: 1;
    }

Alternatively, you can use a separate component,
[basic-carousel-fit](http://github.com/basic-web-components/basic-carousel-fit),
which is designed to automatically size itself to its largest child elements.

The standard basic-carousel component supports navigation via the following
input methods:

* Keyboard. When the carousel has focus, the user can press Left, Right, Home,
or End. These navigate to the expected element.
* Touch. On mobile and other touch-enabled devices, the user can drag left or
right.
* Trackpad. The user can swipe left or right on a trackpad to navigate.

basic-carousel supports a variety of optional user interface accessories:
* [basic-arrow-direction](http://github.com/basic-web-components/basic-arrow-direction).
  This adds prominent left and right arrow buttons on the side of the carousel.
* [basic-page-dots](http://github.com/basic-web-components/basic-page-dots).
  This adds a series of small dots below the carousel to indicate the user's
  current position in the sequence.

See those components for more details, but in general you can construct a common
carousel with both arrow buttons and dots like so:

    <basic-arrow-direction target="child">
      <basic-page-dots target="child">
        <basic-carousel>
          <img src="image1.jpg">
          <img src="image2.jpg">
          <img src="image3.jpg">
          <img src="image4.jpg">
          <img src="image5.jpg">
        </basic-carousel>
      </basic-page-dots>
    </basic-arrow-direction>

For universal access, basic-carousel automatically adds a variety of
[ARIA](http://www.w3.org/WAI/intro/aria) properties to itself and to child
elements. This helps users navigate the sequence of elements in the carousel
using assistive technologies.

@element basic-carousel
@demo http://basic-web-components.github.io/basic-web-components/src/basic-carousel/?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-trackpad-direction/basic-trackpad-direction.html">
<link rel="import" href="../basic-swipe-direction/basic-swipe-direction.html">
<link rel="import" href="../basic-direction-selection/basic-direction-selection.html">
<link rel="import" href="../basic-item-selection/basic-item-selection.html">
<link rel="import" href="../basic-accessible-list/basic-accessible-list.html">
<link rel="import" href="../basic-content-items/basic-content-items.html">
<link rel="import" href="../basic-children-content/basic-children-content.html">
<link rel="import" href="../basic-sliding-viewport/basic-sliding-viewport.html">
<link rel="import" href="../basic-spread-items/basic-spread-items.html">

<dom-module id="basic-carousel">
  <template>

    <style>
    :host {
      display: -webkit-flex;
      display: flex;
    }

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

    basic-spread-items {
      height: 100%;
    }
    </style>

    <basic-item-selection selection-required="true"></basic-item-selection>
    <basic-trackpad-direction target="child">
      <basic-swipe-direction target="child">
        <basic-sliding-viewport target="child">
          <basic-spread-items>
            <content id="content"></content>
          </basic-spread-items>
        </basic-sliding-viewport>
      </basic-swipe-direction>
    </basic-trackpad-direction>

  </template>
</dom-module>

<script>
Polymer({

  aspects: [
    Basic.AccessibleList,
    Basic.ChildrenContent,
    Basic.ContentItems,
    Basic.DirectionSelection,
    Basic.Keyboard,
    Basic.KeyboardDirection
  ],

  behaviors: [Basic.Aspect],

  /**
   * 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);
  },

  is: 'basic-carousel',

  /**
   * 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'
    }

  },

  /**
   * 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 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.
 */

/**
 * 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>