basic-keyboard-paging.html

<!--
Aspect which maps page keys (Page Up, Page Down) into operations that scroll
the component.

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

@element basic-keyboard-paging
-->

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

<script>
window.Basic = window.Basic || {};

window.Basic.KeyboardPaging = {

  contribute: {

    keydown: function(event) {

      var handled = false;

      switch (event.keyCode) {
        case 33: // Page Up
          handled = this.collective.pageUp();
          break;
        case 34: // Page Down
          handled = this.collective.pageDown();
          break;
      }

      if (handled) {
        event.preventDefault();
        event.stopPropagation();
      }
    },

    /**
     * Scroll down one page.
     *
     * @method pageDown
     */
    pageDown: function() {
      return this._scrollOnePage(true);
    },

    /**
     * Scroll up one page.
     *
     * @method pageUp
     */
    pageUp: function() {
      return this._scrollOnePage(false);
    }

  },

  name: 'KeyboardPaging',

  // Return the item whose content spans the given y position (relative to the
  // top of the list's scrolling client area), or null if not found.
  //
  // If downward is true, move down the list of items to find the first item
  // found at the given y position; if downward is false, move up the list of
  // items to find the last item at that position.
  _getIndexOfItemAtY: function(y, downward) {
    var items = this.collective.items;
    var start = downward ? 0 : items.length - 1;
    var end = downward ? items.length : 0;
    var step = downward ? 1 : -1;
    var innermost = this.collective.innermostAttached;
    var topOfClientArea = innermost.offsetTop + innermost.clientTop;
    var i = start;
    var found = false;
    while (i !== end) {
      var item = items[i];
      var itemTop = item.offsetTop - topOfClientArea;
      var itemBottom = itemTop + item.offsetHeight;
      if (itemTop <= y && itemBottom >= y) {
        // Item spans the indicated y coordinate.
        found = true;
        break;
      }
      i += step;
    }

    if (!found) {
      return null;
    }

    // We may have found an item whose padding spans the given y coordinate,
    // but whose content is actually above/below that point.
    // TODO: If the item has a border, then padding should be included in
    // considering a hit.
    var itemStyle = getComputedStyle(item);
    var itemPaddingTop = parseFloat(itemStyle.paddingTop);
    var itemPaddingBottom = parseFloat(itemStyle.paddingBottom);
    var contentTop = itemTop + item.clientTop + itemPaddingTop;
    var contentBottom = contentTop + item.clientHeight - itemPaddingTop - itemPaddingBottom;
    if (downward && contentTop <= y
      || !downward && contentBottom >= y) {
      // The indicated coordinate hits the actual item content.
      return i;
    }
    else {
      // The indicated coordinate falls within the item's padding. Back up to
      // the item below/above the item we found and return that.
      i -= step;
      return i;
    }
  },

  // Move by one page downward (if downward is true), or upward (if false).
  // Return true if we ended up changing the selection, false if not.
  // TODO: Better support for horizontal lists.
  _scrollOnePage: function(downward) {

    var innermost = this.collective.innermostAttached;
    if (!innermost) {
      return;
    }

    // Determine the item visible just at the edge of direction we're heading.
    // We'll select that item if it's not already selected.
    var edge = innermost.scrollTop + (downward ? innermost.clientHeight : 0);
    var indexOfItemAtEdge = this._getIndexOfItemAtY(edge, downward);

    var selectedIndex = this.collective.selectedIndex;
    var newIndex;
    if (indexOfItemAtEdge && selectedIndex === indexOfItemAtEdge) {
      // The item at the edge was already selected, so scroll in the indicated
      // direction by one page. Leave the new item at that edge selected.
      var delta = (downward ? 1 : -1) * innermost.clientHeight;
      newIndex = this._getIndexOfItemAtY(edge + delta, downward);
    }
    else {
      // The item at the edge wasn't selected yet. Instead of scrolling, we'll
      // just select that item. That is, the first attempt to page up/down
      // usually just moves the selection to the edge in that direction.
      newIndex = indexOfItemAtEdge;
    }

    if (!newIndex) {
      // We can't find an item in the direction we want to travel. Select the
      // last item (if moving downward) or first item (if moving upward).
      newIndex = (downward ? this.collective.items.length - 1 : 0);
    }

    if (newIndex !== selectedIndex) {
      this.collective.selectedIndex = newIndex;
      return true; // We handled the page up/down ourselves.
    }
    else {
      return false; // We didn't do anything.
    }
  }

};


Polymer({

  aspects: [Basic.KeyboardPaging],

  behaviors: [Basic.Aspect],

  is: 'basic-keyboard-paging',

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

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

});
</script>