From 6d28420cee4a6cab1de0292e52be9ca4c73378ae Mon Sep 17 00:00:00 2001
From: Valdrin Koshi <valdrin@google.com>
Date: Fri, 27 Oct 2017 13:43:07 -0700
Subject: [PATCH] IronScrollManager and scrollAction (#234)

* copy iron-dropdown-scroll-manager from iron-dropdown

* add allowOutsideScroll, add tests

* Copyright (c) 2017

* restore scroll position when scroll happens (because a11y)

* hope to fix ie10

* get scroll info from wheelDelta (IE10)

* minimal listeners

* listen to WebComponentsReady

* Update tests scrollEvents

* use wct 5, update demo

* remove elementIsScrollLocked, cleanup tests

* listen to all scroll-triggering events

* Listen scroll events on html only

* restore elementIsScrollLocked

* noOutsideScroll & refitOnScroll

* scrollAction

* incorporate feedback

* s/Delays/Debounces
---
 demo/index.html                               |   6 +-
 iron-overlay-behavior.html                    | 150 ++++++-
 iron-scroll-manager.html                      | 381 ++++++++++++++++++
 test/index.html                               |   4 +
 .../iron-overlay-behavior-scroll-actions.html | 184 +++++++++
 test/iron-scroll-manager.html                 | 186 +++++++++
 test/x-scrollable-element.html                |  53 +++
 7 files changed, 939 insertions(+), 25 deletions(-)
 create mode 100644 iron-scroll-manager.html
 create mode 100644 test/iron-overlay-behavior-scroll-actions.html
 create mode 100644 test/iron-scroll-manager.html
 create mode 100644 test/x-scrollable-element.html

diff --git a/demo/index.html b/demo/index.html
index e9c6a20..d0a5f92 100644
--- a/demo/index.html
+++ b/demo/index.html
@@ -55,7 +55,7 @@ <h3>Use <code>with-backdrop</code> to add a backdrop to your overlay. Tabbing wi
   <demo-snippet>
     <template>
       <button onclick="backdrop.open()">Overlay with backdrop</button>
-      <simple-overlay id="backdrop" with-backdrop>
+      <simple-overlay id="backdrop" with-backdrop scroll-action="lock">
         <p>Hello world!</p>
         <button>Button</button>
         <button onclick="backdrop.close()">Close</button>
@@ -140,7 +140,7 @@ <h3>An element with <code>IronOverlayBehavior</code> can be scrollable or contai
       </custom-style>
       <button onclick="scrolling.open()">Scrolling overlay</button>
 
-      <simple-overlay id="scrolling" class="with-margin scrollable" tabindex=-1>
+      <simple-overlay id="scrolling" class="with-margin scrollable" tabindex=-1 scroll-action="lock">
         <h2>This overlay scrolls internally.</h2>
         <p>
           Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
@@ -205,7 +205,7 @@ <h2>This overlay scrolls internally.</h2>
 
       <button onclick="scrolling2.open()">Scrolling content</button>
 
-      <simple-overlay id="scrolling2" class="with-margin" tabindex=-1>
+      <simple-overlay id="scrolling2" class="with-margin" tabindex=-1 scroll-action="lock">
         <h2>This overlay has a scrolling child.</h2>
         <p class="scrollable">
           Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
diff --git a/iron-overlay-behavior.html b/iron-overlay-behavior.html
index 7d9afcf..87af2b9 100644
--- a/iron-overlay-behavior.html
+++ b/iron-overlay-behavior.html
@@ -12,6 +12,7 @@
 <link rel="import" href="../iron-fit-behavior/iron-fit-behavior.html">
 <link rel="import" href="../iron-resizable-behavior/iron-resizable-behavior.html">
 <link rel="import" href="iron-overlay-manager.html">
+<link rel="import" href="iron-scroll-manager.html">
 <link rel="import" href="iron-focusables-helper.html">
 
 <script>
@@ -112,6 +113,17 @@
         type: Boolean
       },
 
+      /**
+       * Determines which action to perform when scroll outside an opened overlay happens.
+       * Possible values:
+       * lock - blocks scrolling from happening,
+       * refit - computes the new position on the overlay
+       * cancel - causes the overlay to close
+       */
+      scrollAction: {
+        type: String
+      },
+
       /**
        * Shortcut to access to the overlay manager.
        * @private
@@ -136,6 +148,10 @@
       'iron-resize': '_onIronResize'
     },
 
+    observers: [
+      '__updateScrollObservers(isAttached, opened, scrollAction)'
+    ],
+
     /**
      * The backdrop element.
      * @type {Element}
@@ -174,10 +190,13 @@
       this.__shouldRemoveTabIndex = false;
       // Used for wrapping the focus on TAB / Shift+TAB.
       this.__firstFocusableNode = this.__lastFocusableNode = null;
-      // Used by __onNextAnimationFrame to cancel any previous callback.
-      this.__raf = null;
+      // Used by to keep track of the RAF callbacks.
+      this.__rafs = {};
       // Focused node before overlay gets opened. Can be restored on close.
       this.__restoreFocusNode = null;
+      // Scroll info to be restored.
+      this.__scrollTop = this.__scrollLeft = null;
+      this.__onCaptureScroll = this.__onCaptureScroll.bind(this);
       this._ensureSetup();
     },
 
@@ -192,10 +211,12 @@
     detached: function() {
       Polymer.dom(this).unobserveNodes(this._observer);
       this._observer = null;
-      if (this.__raf) {
-        window.cancelAnimationFrame(this.__raf);
-        this.__raf = null;
+      for (var cb in this.__rafs) {
+        if (this.__rafs[cb] !== null) {
+          cancelAnimationFrame(this.__rafs[cb]);
+        }
       }
+      this.__rafs = {};
       this._manager.removeOverlay(this);
 
       // We got detached while animating, ensure we show/hide the overlay
@@ -286,8 +307,8 @@
 
       this.__isAnimating = true;
 
-      // Use requestAnimationFrame for non-blocking rendering.
-      this.__onNextAnimationFrame(this.__openedChanged);
+      // Deraf for non-blocking rendering.
+      this.__deraf('__openedChanged', this.__openedChanged);
     },
 
     _canceledChanged: function() {
@@ -526,7 +547,7 @@
      */
     _onIronResize: function() {
       if (this.opened && !this.__isAnimating) {
-        this.__onNextAnimationFrame(this.refit);
+        this.__deraf('refit', this.refit);
       }
     },
 
@@ -579,23 +600,108 @@
     },
 
     /**
-     * Executes a callback on the next animation frame, overriding any previous
-     * callback awaiting for the next animation frame. e.g.
-     * `__onNextAnimationFrame(callback1) && __onNextAnimationFrame(callback2)`;
-     * `callback1` will never be invoked.
-     * @param {!Function} callback Its `this` parameter is the overlay itself.
+     * Debounces the execution of a callback to the next animation frame.
+     * @param {!string} jobname
+     * @param {!Function} callback Always bound to `this`
+     * @private
+     */
+    __deraf: function(jobname, callback) {
+      var rafs = this.__rafs;
+      if (rafs[jobname] !== null) {
+        cancelAnimationFrame(rafs[jobname]);
+      }
+      rafs[jobname] = requestAnimationFrame(function nextAnimationFrame() {
+        rafs[jobname] = null;
+        callback.call(this);
+      }.bind(this));
+    },
+
+    /**
+     * @param {boolean} isAttached
+     * @param {boolean} opened
+     * @param {string=} scrollAction
      * @private
      */
-    __onNextAnimationFrame: function(callback) {
-      if (this.__raf) {
-        window.cancelAnimationFrame(this.__raf);
+    __updateScrollObservers: function(isAttached, opened, scrollAction) {
+      if (!isAttached || !opened || !this.__isValidScrollAction(scrollAction)) {
+        Polymer.IronScrollManager.removeScrollLock(this);
+        document.removeEventListener('scroll', this.__onCaptureScroll, {
+          passive: true
+        });
+      } else {
+        if (scrollAction === 'lock') {
+          this.__saveScrollPosition();
+          Polymer.IronScrollManager.pushScrollLock(this);
+        }
+        document.addEventListener('scroll', this.__onCaptureScroll, {
+          passive: true
+        });
       }
-      var self = this;
-      this.__raf = window.requestAnimationFrame(function nextAnimationFrame() {
-        self.__raf = null;
-        callback.call(self);
-      });
-    }
+    },
+
+    /**
+     * @param {string=} scrollAction
+     * @return {boolean}
+     * @private
+     */
+    __isValidScrollAction: function(scrollAction) {
+      return scrollAction === 'lock' ||
+             scrollAction === 'refit' ||
+             scrollAction === 'cancel';
+    },
+
+    /**
+     * @private
+     */
+    __onCaptureScroll: function(event) {
+      if (this.__isAnimating) {
+        return;
+      }
+      switch (this.scrollAction) {
+        case 'lock':
+          // NOTE: scrolling might happen if a scroll event is not cancellable, or if
+          // user pressed keys that cause scrolling (they're not prevented in order not to
+          // break a11y features like navigate with arrow keys).
+          this.__restoreScrollPosition();
+          break;
+        case 'refit':
+          this.__deraf('refit', this.refit);
+          break;
+        case 'cancel':
+          this.cancel(event);
+          break;
+      }
+    },
+
+    /**
+     * Memoizes the scroll position of the outside scrolling element.
+     * @private
+     */
+    __saveScrollPosition: function() {
+      if (document.scrollingElement) {
+        this.__scrollTop = document.scrollingElement.scrollTop;
+        this.__scrollLeft = document.scrollingElement.scrollLeft;
+      } else {
+        // Since we don't know if is the body or html, get max.
+        this.__scrollTop = Math.max(document.documentElement.scrollTop, document.body.scrollTop);
+        this.__scrollLeft = Math.max(document.documentElement.scrollLeft, document.body.scrollLeft);
+      }
+    },
+
+    /**
+     * Resets the scroll position of the outside scrolling element.
+     * @private
+     */
+    __restoreScrollPosition: function() {
+      if (document.scrollingElement) {
+        document.scrollingElement.scrollTop = this.__scrollTop;
+        document.scrollingElement.scrollLeft = this.__scrollLeft;
+      } else {
+        // Since we don't know if is the body or html, set both.
+        document.documentElement.scrollTop = document.body.scrollTop = this.__scrollTop;
+        document.documentElement.scrollLeft = document.body.scrollLeft = this.__scrollLeft;
+      }
+    },
 
   };
 
diff --git a/iron-scroll-manager.html b/iron-scroll-manager.html
new file mode 100644
index 0000000..2c34a36
--- /dev/null
+++ b/iron-scroll-manager.html
@@ -0,0 +1,381 @@
+<!--
+@license
+Copyright (c) 2017 The Polymer Project Authors. All rights reserved.
+This code may only be used under the BSD style license found at http://polymer.github.io/LICENSE.txt
+The complete set of authors may be found at http://polymer.github.io/AUTHORS.txt
+The complete set of contributors may be found at http://polymer.github.io/CONTRIBUTORS.txt
+Code distributed by Google as part of the polymer project is also
+subject to an additional IP rights grant found at http://polymer.github.io/PATENTS.txt
+-->
+
+<link rel="import" href="../polymer/polymer.html">
+
+<script>
+  (function() {
+    'use strict';
+    /**
+     * Used to calculate the scroll direction during touch events.
+     * @type {!Object}
+     */
+    var lastTouchPosition = {
+      pageX: 0,
+      pageY: 0
+    };
+    /**
+     * Used to avoid computing event.path and filter scrollable nodes (better perf).
+     * @type {?EventTarget}
+     */
+    var lastRootTarget = null;
+    /**
+     * @type {!Array<Node>}
+     */
+    var lastScrollableNodes = [];
+    /**
+     * @type {!Array<string>}
+     */
+    var scrollEvents = [
+      // Modern `wheel` event for mouse wheel scrolling:
+      'wheel',
+      // Older, non-standard `mousewheel` event for some FF:
+      'mousewheel',
+      // IE:
+      'DOMMouseScroll',
+      // Touch enabled devices
+      'touchstart',
+      'touchmove'
+    ];
+
+    /**
+     * The IronScrollManager is intended to provide a central source
+     * of authority and control over which elements in a document are currently
+     * allowed to scroll.
+     */
+
+    Polymer.IronScrollManager = {
+
+      /**
+       * The current element that defines the DOM boundaries of the
+       * scroll lock. This is always the most recently locking element.
+       */
+      get currentLockingElement() {
+        return this._lockingElements[this._lockingElements.length - 1];
+      },
+
+      /**
+       * Returns true if the provided element is "scroll locked", which is to
+       * say that it cannot be scrolled via pointer or keyboard interactions.
+       *
+       * @param {HTMLElement} element An HTML element instance which may or may
+       * not be scroll locked.
+       */
+      elementIsScrollLocked: function(element) {
+        var currentLockingElement = this.currentLockingElement;
+
+        if (currentLockingElement === undefined)
+          return false;
+
+        var scrollLocked;
+
+        if (this._hasCachedLockedElement(element)) {
+          return true;
+        }
+
+        if (this._hasCachedUnlockedElement(element)) {
+          return false;
+        }
+
+        scrollLocked = !!currentLockingElement &&
+          currentLockingElement !== element &&
+          !this._composedTreeContains(currentLockingElement, element);
+
+        if (scrollLocked) {
+          this._lockedElementCache.push(element);
+        } else {
+          this._unlockedElementCache.push(element);
+        }
+
+        return scrollLocked;
+      },
+
+      /**
+       * Push an element onto the current scroll lock stack. The most recently
+       * pushed element and its children will be considered scrollable. All
+       * other elements will not be scrollable.
+       *
+       * Scroll locking is implemented as a stack so that cases such as
+       * dropdowns within dropdowns are handled well.
+       *
+       * @param {HTMLElement} element The element that should lock scroll.
+       */
+      pushScrollLock: function(element) {
+        // Prevent pushing the same element twice
+        if (this._lockingElements.indexOf(element) >= 0) {
+          return;
+        }
+
+        if (this._lockingElements.length === 0) {
+          this._lockScrollInteractions();
+        }
+
+        this._lockingElements.push(element);
+
+        this._lockedElementCache = [];
+        this._unlockedElementCache = [];
+      },
+
+      /**
+       * Remove an element from the scroll lock stack. The element being
+       * removed does not need to be the most recently pushed element. However,
+       * the scroll lock constraints only change when the most recently pushed
+       * element is removed.
+       *
+       * @param {HTMLElement} element The element to remove from the scroll
+       * lock stack.
+       */
+      removeScrollLock: function(element) {
+        var index = this._lockingElements.indexOf(element);
+
+        if (index === -1) {
+          return;
+        }
+
+        this._lockingElements.splice(index, 1);
+
+        this._lockedElementCache = [];
+        this._unlockedElementCache = [];
+
+        if (this._lockingElements.length === 0) {
+          this._unlockScrollInteractions();
+        }
+      },
+
+      _lockingElements: [],
+
+      _lockedElementCache: null,
+
+      _unlockedElementCache: null,
+
+      _hasCachedLockedElement: function(element) {
+        return this._lockedElementCache.indexOf(element) > -1;
+      },
+
+      _hasCachedUnlockedElement: function(element) {
+        return this._unlockedElementCache.indexOf(element) > -1;
+      },
+
+      _composedTreeContains: function(element, child) {
+        // NOTE(cdata): This method iterates over content elements and their
+        // corresponding distributed nodes to implement a contains-like method
+        // that pierces through the composed tree of the ShadowDOM. Results of
+        // this operation are cached (elsewhere) on a per-scroll-lock basis, to
+        // guard against potentially expensive lookups happening repeatedly as
+        // a user scrolls / touchmoves.
+        var contentElements;
+        var distributedNodes;
+        var contentIndex;
+        var nodeIndex;
+
+        if (element.contains(child)) {
+          return true;
+        }
+
+        contentElements = Polymer.dom(element).querySelectorAll('content,slot');
+
+        for (contentIndex = 0; contentIndex < contentElements.length; ++contentIndex) {
+
+          distributedNodes = Polymer.dom(contentElements[contentIndex]).getDistributedNodes();
+
+          for (nodeIndex = 0; nodeIndex < distributedNodes.length; ++nodeIndex) {
+            // Polymer 2.x returns slot.assignedNodes which can contain text nodes.
+            if (distributedNodes[nodeIndex].nodeType !== Node.ELEMENT_NODE) continue;
+
+            if (this._composedTreeContains(distributedNodes[nodeIndex], child)) {
+              return true;
+            }
+          }
+        }
+
+        return false;
+      },
+
+      _scrollInteractionHandler: function(event) {
+        // Avoid canceling an event with cancelable=false, e.g. scrolling is in
+        // progress and cannot be interrupted.
+        if (event.cancelable && this._shouldPreventScrolling(event)) {
+          event.preventDefault();
+        }
+        // If event has targetTouches (touch event), update last touch position.
+        if (event.targetTouches) {
+          var touch = event.targetTouches[0];
+          lastTouchPosition.pageX = touch.pageX;
+          lastTouchPosition.pageY = touch.pageY;
+        }
+      },
+
+      _lockScrollInteractions: function() {
+        this._boundScrollHandler = this._boundScrollHandler ||
+          this._scrollInteractionHandler.bind(this);
+        for (var i = 0, l = scrollEvents.length; i < l; i++) {
+          // NOTE: browsers that don't support objects as third arg will
+          // interpret it as boolean, hence useCapture = true in this case. 
+          document.addEventListener(scrollEvents[i], this._boundScrollHandler, {
+            capture: true,
+            passive: false
+          });
+        }
+      },
+
+      _unlockScrollInteractions: function() {
+        for (var i = 0, l = scrollEvents.length; i < l; i++) {
+          // NOTE: browsers that don't support objects as third arg will
+          // interpret it as boolean, hence useCapture = true in this case.
+          document.removeEventListener(scrollEvents[i], this._boundScrollHandler, {
+            capture: true,
+            passive: false
+          });
+        }
+      },
+
+      /**
+       * Returns true if the event causes scroll outside the current locking
+       * element, e.g. pointer/keyboard interactions, or scroll "leaking"
+       * outside the locking element when it is already at its scroll boundaries.
+       * @param {!Event} event
+       * @return {boolean}
+       * @private
+       */
+      _shouldPreventScrolling: function(event) {
+
+        // Update if root target changed. For touch events, ensure we don't
+        // update during touchmove.
+        var target = Polymer.dom(event).rootTarget;
+        if (event.type !== 'touchmove' && lastRootTarget !== target) {
+          lastRootTarget = target;
+          lastScrollableNodes = this._getScrollableNodes(Polymer.dom(event).path);
+        }
+
+        // Prevent event if no scrollable nodes.
+        if (!lastScrollableNodes.length) {
+          return true;
+        }
+        // Don't prevent touchstart event inside the locking element when it has
+        // scrollable nodes.
+        if (event.type === 'touchstart') {
+          return false;
+        }
+        // Get deltaX/Y.
+        var info = this._getScrollInfo(event);
+        // Prevent if there is no child that can scroll.
+        return !this._getScrollingNode(lastScrollableNodes, info.deltaX, info.deltaY);
+      },
+
+      /**
+       * Returns an array of scrollable nodes up to the current locking element,
+       * which is included too if scrollable.
+       * @param {!Array<Node>} nodes
+       * @return {Array<Node>} scrollables
+       * @private
+       */
+      _getScrollableNodes: function(nodes) {
+        var scrollables = [];
+        var lockingIndex = nodes.indexOf(this.currentLockingElement);
+        // Loop from root target to locking element (included).
+        for (var i = 0; i <= lockingIndex; i++) {
+          // Skip non-Element nodes.
+          if (nodes[i].nodeType !== Node.ELEMENT_NODE) {
+            continue;
+          }
+          var node = /** @type {!Element} */ (nodes[i]);
+          // Check inline style before checking computed style.
+          var style = node.style;
+          if (style.overflow !== 'scroll' && style.overflow !== 'auto') {
+            style = window.getComputedStyle(node);
+          }
+          if (style.overflow === 'scroll' || style.overflow === 'auto') {
+            scrollables.push(node);
+          }
+        }
+        return scrollables;
+      },
+
+      /**
+       * Returns the node that is scrolling. If there is no scrolling,
+       * returns undefined.
+       * @param {!Array<Node>} nodes
+       * @param {number} deltaX Scroll delta on the x-axis
+       * @param {number} deltaY Scroll delta on the y-axis
+       * @return {Node|undefined}
+       * @private
+       */
+      _getScrollingNode: function(nodes, deltaX, deltaY) {
+        // No scroll.
+        if (!deltaX && !deltaY) {
+          return;
+        }
+        // Check only one axis according to where there is more scroll.
+        // Prefer vertical to horizontal.
+        var verticalScroll = Math.abs(deltaY) >= Math.abs(deltaX);
+        for (var i = 0; i < nodes.length; i++) {
+          var node = nodes[i];
+          var canScroll = false;
+          if (verticalScroll) {
+            // delta < 0 is scroll up, delta > 0 is scroll down.
+            canScroll = deltaY < 0 ? node.scrollTop > 0 :
+              node.scrollTop < node.scrollHeight - node.clientHeight;
+          } else {
+            // delta < 0 is scroll left, delta > 0 is scroll right.
+            canScroll = deltaX < 0 ? node.scrollLeft > 0 :
+              node.scrollLeft < node.scrollWidth - node.clientWidth;
+          }
+          if (canScroll) {
+            return node;
+          }
+        }
+      },
+
+      /**
+       * Returns scroll `deltaX` and `deltaY`.
+       * @param {!Event} event The scroll event
+       * @return {{deltaX: number, deltaY: number}} Object containing the
+       * x-axis scroll delta (positive: scroll right, negative: scroll left,
+       * 0: no scroll), and the y-axis scroll delta (positive: scroll down,
+       * negative: scroll up, 0: no scroll).
+       * @private
+       */
+      _getScrollInfo: function(event) {
+        var info = {
+          deltaX: event.deltaX,
+          deltaY: event.deltaY
+        };
+        // Already available.
+        if ('deltaX' in event) {
+          // do nothing, values are already good.
+        }
+        // Safari has scroll info in `wheelDeltaX/Y`.
+        else if ('wheelDeltaX' in event && 'wheelDeltaY' in event) {
+          info.deltaX = -event.wheelDeltaX;
+          info.deltaY = -event.wheelDeltaY;
+        }
+        // IE10 has only vertical scroll info in `wheelDelta`.
+        else if ('wheelDelta' in event) {
+          info.deltaX = 0;
+          info.deltaY = -event.wheelDelta;
+        }
+        // Firefox has scroll info in `detail` and `axis`.
+        else if ('axis' in event) {
+          info.deltaX = event.axis === 1 ? event.detail : 0;
+          info.deltaY = event.axis === 2 ? event.detail : 0;
+        }
+        // On mobile devices, calculate scroll direction.
+        else if (event.targetTouches) {
+          var touch = event.targetTouches[0];
+          // Touch moves from right to left => scrolling goes right.
+          info.deltaX = lastTouchPosition.pageX - touch.pageX;
+          // Touch moves from down to up => scrolling goes down.
+          info.deltaY = lastTouchPosition.pageY - touch.pageY;
+        }
+        return info;
+      }
+    };
+  })();
+</script>
\ No newline at end of file
diff --git a/test/index.html b/test/index.html
index 97e9bf9..ac4532c 100644
--- a/test/index.html
+++ b/test/index.html
@@ -24,9 +24,13 @@
         'iron-overlay-behavior.html?wc-shadydom=true&wc-ce=true', //shady
         'iron-focusables-helper.html?wc-shadydom=true&wc-ce=true', //shady
         'iron-overlay-backdrop.html?wc-shadydom=true&wc-ce=true', //shady
+        'iron-scroll-manager.html?wc-shadydom=true&wc-ce=true', //shady
+        'iron-overlay-behavior-scroll-actions.html?wc-shadydom=true&wc-ce=true', //shady
         'iron-overlay-behavior.html?dom=shadow', //shadow
         'iron-focusables-helper.html?dom=shadow', //shadow
         'iron-overlay-backdrop.html?dom=shadow', //shadow
+        'iron-scroll-manager.html?dom=shadow', //shadow
+        'iron-overlay-behavior-scroll-actions.html?dom=shadow', //shadow
       ]);
     </script>
 
diff --git a/test/iron-overlay-behavior-scroll-actions.html b/test/iron-overlay-behavior-scroll-actions.html
new file mode 100644
index 0000000..16ce0ac
--- /dev/null
+++ b/test/iron-overlay-behavior-scroll-actions.html
@@ -0,0 +1,184 @@
+<!doctype html>
+<!--
+@license
+Copyright (c) 2015 The Polymer Project Authors. All rights reserved.
+This code may only be used under the BSD style license found at http://polymer.github.io/LICENSE.txt
+The complete set of authors may be found at http://polymer.github.io/AUTHORS.txt
+The complete set of contributors may be found at http://polymer.github.io/CONTRIBUTORS.txt
+Code distributed by Google as part of the polymer project is also
+subject to an additional IP rights grant found at http://polymer.github.io/PATENTS.txt
+-->
+<html>
+
+<head>
+
+  <title>iron-overlay-behavior tests</title>
+
+  <meta charset="utf-8">
+  <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
+  <meta name="viewport" content="width=device-width, minimum-scale=1.0, initial-scale=1, user-scalable=yes">
+
+  <script src="../../webcomponentsjs/webcomponents-lite.js"></script>
+
+  <script src="../../web-component-tester/browser.js"></script>
+  <link rel="import" href="test-overlay.html">
+
+</head>
+
+<body>
+
+  <div style="width: 150vmax; height: 150vmax">
+    This element makes the page scrollable.
+  </div>
+
+  <test-fixture id="basic">
+    <template>
+      <test-overlay>
+        Basic Overlay
+      </test-overlay>
+    </template>
+  </test-fixture>
+
+  <script>
+    // Need to discover if html or body is scrollable.
+    // Here we are sure the page is scrollable.
+    var scrollTarget;
+    document.documentElement.scrollTop = 1;
+    if (document.documentElement.scrollTop === 1) {
+      document.documentElement.scrollTop = 0;
+      scrollTarget = document.documentElement;
+    } else {
+      scrollTarget = document.body;
+    }
+
+    function runAfterOpen(overlay, callback) {
+      overlay.addEventListener('iron-overlay-opened', callback);
+      overlay.open();
+    }
+
+    function runAfterClose(overlay, callback) {
+      overlay.addEventListener('iron-overlay-closed', callback);
+      overlay.close();
+    }
+
+    function fireWheel(node, deltaX, deltaY) {
+      // IE 11 doesn't support WheelEvent, use CustomEvent.
+      var event = new CustomEvent('wheel', {
+        cancelable: true,
+        bubbles: true,
+        composed: true,
+      });
+      event.deltaX = deltaX;
+      event.deltaY = deltaY;
+      node.dispatchEvent(event);
+      return event;
+    }
+
+    function dispatchScroll(target, scrollLeft, scrollTop) {
+      target.scrollLeft = scrollLeft;
+      target.scrollTop = scrollTop;
+      target.dispatchEvent(new CustomEvent('scroll', {
+        bubbles: true,
+        composed: true
+      }));
+    }
+
+    suite('scroll actions', function() {
+
+      var overlay;
+      setup(function() {
+        // Ensure we always scroll to top.
+        dispatchScroll(scrollTarget, 0, 0);
+        overlay = fixture('basic');
+      });
+
+      test('default: outside scroll not prevented', function(done) {
+        runAfterOpen(overlay, function() {
+          assert.isFalse(Polymer.IronScrollManager.elementIsScrollLocked(scrollTarget));
+          assert.isFalse(fireWheel(scrollTarget, 0, 10).defaultPrevented);
+          dispatchScroll(scrollTarget, 0, 10);
+          Polymer.RenderStatus.afterNextRender(overlay, function() {
+            assert.equal(scrollTarget.scrollTop, 10, 'scrollTop ok');
+            assert.equal(scrollTarget.scrollLeft, 0, 'scrollLeft ok');
+            done();
+          });
+        });
+      });
+
+      test('default: outside scroll does NOT trigger refit', function(done) {
+        runAfterOpen(overlay, function() {
+          var refitSpy = sinon.spy(overlay, 'refit');
+          dispatchScroll(scrollTarget, 0, 10);
+          Polymer.RenderStatus.afterNextRender(overlay, function() {
+            assert.equal(refitSpy.callCount, 0, 'did not refit on scroll');
+            done();
+          });
+        });
+      });
+
+      test('refit scrollAction refits the overlay', function(done) {
+        overlay.scrollAction = 'refit';
+        runAfterOpen(overlay, function() {
+          var refitSpy = sinon.spy(overlay, 'refit');
+          dispatchScroll(scrollTarget, 0, 10);
+          Polymer.RenderStatus.afterNextRender(overlay, function() {
+            assert.notEqual(refitSpy.callCount, 0, 'did refit on scroll');
+            done();
+          });
+        });
+      });
+
+      test('cancel scrollAction cancels/closes the overlay on scroll', function(done) {
+        overlay.scrollAction = 'cancel';
+        runAfterOpen(overlay, function() {
+          overlay.addEventListener('iron-overlay-canceled', function(event) {
+            assert.equal(event.detail.type, 'scroll', 'detail contains original event');
+            assert.equal(event.detail.target, scrollTarget, 'original scroll event target ok');
+          });
+          overlay.addEventListener('iron-overlay-closed', function() {
+            done();
+          });
+          dispatchScroll(scrollTarget, 0, 10);
+        });
+      });
+
+      test('lock scrollAction locks scroll', function(done) {
+        overlay.scrollAction = 'lock';
+        runAfterOpen(overlay, function() {
+          assert.isTrue(Polymer.IronScrollManager.elementIsScrollLocked(scrollTarget));
+          assert.isTrue(fireWheel(scrollTarget, 0, 10).defaultPrevented);
+          dispatchScroll(scrollTarget, 0, 10);
+          assert.equal(scrollTarget.scrollTop, 0, 'scrollTop ok');
+          assert.equal(scrollTarget.scrollLeft, 0, 'scrollLeft ok');
+          done();
+        });
+      });
+
+      test('should lock, only once', function(done) {
+        var openCount = 0;
+        overlay.scrollAction = 'lock';
+        runAfterOpen(overlay, function() {
+          assert.isTrue(Polymer.IronScrollManager.elementIsScrollLocked(scrollTarget));
+          assert.isTrue(fireWheel(scrollTarget, 0, 10).defaultPrevented);
+          assert.equal(Polymer.IronScrollManager._lockingElements.length, 1);
+          if (openCount === 0) {
+            // This triggers a second `pushScrollLock` with the same element, however
+            // that should not add the element to the `_lockingElements` stack twice
+            runAfterClose(overlay, function() {
+              assert.isFalse(Polymer.IronScrollManager.elementIsScrollLocked(overlay));
+              assert.isFalse(fireWheel(scrollTarget, 0, 10).defaultPrevented);
+              overlay.open();
+            });
+          } else {
+            done();
+          }
+          openCount++;
+        });
+      });
+
+    });
+  </script>
+
+</body>
+
+</html>
\ No newline at end of file
diff --git a/test/iron-scroll-manager.html b/test/iron-scroll-manager.html
new file mode 100644
index 0000000..04aa874
--- /dev/null
+++ b/test/iron-scroll-manager.html
@@ -0,0 +1,186 @@
+<!doctype html>
+<!--
+@license
+Copyright (c) 2017 The Polymer Project Authors. All rights reserved.
+This code may only be used under the BSD style license found at http://polymer.github.io/LICENSE.txt
+The complete set of authors may be found at http://polymer.github.io/AUTHORS.txt
+The complete set of contributors may be found at http://polymer.github.io/CONTRIBUTORS.txt
+Code distributed by Google as part of the polymer project is also
+subject to an additional IP rights grant found at http://polymer.github.io/PATENTS.txt
+-->
+<html>
+
+<head>
+  <meta charset="UTF-8">
+  <title>iron-dropdown-scroll-manager tests</title>
+  <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0">
+
+  <script src="../../webcomponentsjs/webcomponents-lite.js"></script>
+  <script src="../../web-component-tester/browser.js"></script>
+  <script src="../../iron-test-helpers/mock-interactions.js"></script>
+
+  <link rel="import" href="../iron-scroll-manager.html">
+  <link rel="import" href="x-scrollable-element.html">
+</head>
+
+<body>
+
+  <test-fixture id="DOMSubtree">
+    <template>
+      <x-scrollable-element id="Parent"></x-scrollable-element>
+    </template>
+  </test-fixture>
+  <script>
+    var scrollEvents = [
+      'wheel',
+      'mousewheel',
+      'DOMMouseScroll',
+      'touchstart',
+      'touchmove',
+    ];
+
+    suite('IronScrollManager', function() {
+      var parent;
+      var childOne;
+      var childTwo;
+      var grandChildOne;
+      var grandChildTwo;
+      var ancestor;
+
+      setup(function() {
+        parent = fixture('DOMSubtree');
+        childOne = parent.$$('#ChildOne');
+        childTwo = parent.$$('#ChildTwo');
+        grandChildOne = parent.$$('#GrandchildOne');
+        grandChildTwo = parent.$$('#GrandchildTwo');
+        ancestor = document.body;
+      });
+
+      suite('constraining scroll in the DOM', function() {
+        setup(function() {
+          Polymer.IronScrollManager.pushScrollLock(childOne);
+        });
+
+        teardown(function() {
+          Polymer.IronScrollManager.removeScrollLock(childOne);
+        });
+
+        test('recognizes sibling as locked', function() {
+          expect(Polymer.IronScrollManager.elementIsScrollLocked(childTwo))
+            .to.be.equal(true);
+        });
+
+        test('recognizes neice as locked', function() {
+          expect(Polymer.IronScrollManager.elementIsScrollLocked(grandChildTwo))
+            .to.be.equal(true);
+        });
+
+        test('recognizes parent as locked', function() {
+          expect(Polymer.IronScrollManager.elementIsScrollLocked(parent))
+            .to.be.equal(true);
+        });
+
+        test('recognizes ancestor as locked', function() {
+          expect(Polymer.IronScrollManager.elementIsScrollLocked(ancestor))
+            .to.be.equal(true);
+        });
+
+        test('recognizes locking child as unlocked', function() {
+          expect(Polymer.IronScrollManager.elementIsScrollLocked(childOne))
+            .to.be.equal(false);
+        });
+
+        test('recognizes descendant of locking child as unlocked', function() {
+          expect(Polymer.IronScrollManager.elementIsScrollLocked(grandChildOne))
+            .to.be.equal(false);
+        });
+
+        test('unlocks locked elements when there are no locking elements', function() {
+          Polymer.IronScrollManager.removeScrollLock(childOne);
+
+          expect(Polymer.IronScrollManager.elementIsScrollLocked(parent))
+            .to.be.equal(false);
+        });
+
+        suite('various scroll events', function() {
+          var events;
+          setup(function() {
+            events = scrollEvents.map(function(scrollEvent) {
+              var event = new CustomEvent(scrollEvent, {
+                bubbles: true,
+                cancelable: true,
+                composed: true
+              });
+              event.deltaX = 0;
+              event.deltaY = 10;
+              return event;
+            });
+          });
+
+          test('prevents wheel events from locked elements', function() {
+            events.forEach(function(event) {
+              childTwo.dispatchEvent(event);
+              assert.isTrue(event.defaultPrevented, event.type + ' ok');
+            });
+          });
+
+          test('allows wheel events when there are no locking elements', function() {
+            Polymer.IronScrollManager.removeScrollLock(childOne);
+            events.forEach(function(event) {
+              childTwo.dispatchEvent(event);
+              assert.isFalse(event.defaultPrevented, event.type + ' ok');
+            });
+          });
+
+          test('allows wheel events from unlocked elements', function() {
+            events.forEach(function(event) {
+              childOne.dispatchEvent(event);
+              assert.isFalse(event.defaultPrevented, event.type + ' ok');
+            });
+          });
+
+          test('touchstart is prevented if dispatched by an element outside the locking element', function() {
+            var event = new CustomEvent('touchstart', {
+              bubbles: true,
+              cancelable: true,
+              composed: true
+            });
+            childTwo.dispatchEvent(event);
+            assert.isTrue(event.defaultPrevented, event.type + ' ok');
+          });
+
+          test('touchstart is not prevented if dispatched by an element inside the locking element', function() {
+            var event = new CustomEvent('touchstart', {
+              bubbles: true,
+              cancelable: true,
+              composed: true
+            });
+            grandChildOne.dispatchEvent(event);
+            assert.isFalse(event.defaultPrevented, event.type + ' ok');
+          });
+
+          test('arrow keyboard events not prevented by manager', function() {
+            // Even if these events might cause scrolling, they should not be
+            // prevented because they might cause a11y issues (e.g. arrow keys
+            // used for navigating the content). iron-dropdown is capable of
+            // restoring the scroll position of the document if necessary.
+            var left = MockInteractions.keyboardEventFor('keydown', 37);
+            var up = MockInteractions.keyboardEventFor('keydown', 38);
+            var right = MockInteractions.keyboardEventFor('keydown', 39);
+            var down = MockInteractions.keyboardEventFor('keydown', 40);
+            grandChildOne.dispatchEvent(left);
+            grandChildOne.dispatchEvent(up);
+            grandChildOne.dispatchEvent(right);
+            grandChildOne.dispatchEvent(down);
+            assert.isFalse(left.defaultPrevented, 'left ok');
+            assert.isFalse(up.defaultPrevented, 'up ok');
+            assert.isFalse(right.defaultPrevented, 'right ok');
+            assert.isFalse(down.defaultPrevented, 'down ok');
+          });
+        });
+      });
+    });
+  </script>
+</body>
+
+</html>
\ No newline at end of file
diff --git a/test/x-scrollable-element.html b/test/x-scrollable-element.html
new file mode 100644
index 0000000..0cffe52
--- /dev/null
+++ b/test/x-scrollable-element.html
@@ -0,0 +1,53 @@
+<!--
+@license
+Copyright (c) 2017 The Polymer Project Authors. All rights reserved.
+This code may only be used under the BSD style license found at http://polymer.github.io/LICENSE.txt
+The complete set of authors may be found at http://polymer.github.io/AUTHORS.txt
+The complete set of contributors may be found at http://polymer.github.io/CONTRIBUTORS.txt
+Code distributed by Google as part of the polymer project is also
+subject to an additional IP rights grant found at http://polymer.github.io/PATENTS.txt
+-->
+
+<link rel="import" href="../../polymer/polymer.html">
+
+<dom-module id="x-scrollable-element">
+  <template>
+    <style>
+      :host {
+        display: block;
+        height: 100px;
+        border: 1px solid red;
+        overflow: auto;
+      }
+      #ChildOne, #ChildTwo {
+        height: 200px;
+        border: 1px solid blue;
+        overflow: auto;
+      }
+      #GrandchildOne, #GrandchildTwo {
+        height: 300px;
+        border: 1px solid green;
+        overflow: auto;
+      }
+      .scrollContent {
+        height: 400px;
+        background-color: yellow;
+      }
+    </style>
+    <div id="ChildOne">
+      <div id="GrandchildOne">
+        <div class="scrollContent"></div>
+      </div>
+    </div>
+    <div id="ChildTwo">
+      <div id="GrandchildTwo">
+        <div class="scrollContent"></div>
+      </div>
+    </div>
+  </template>
+  <script>
+    Polymer({
+      is: 'x-scrollable-element'
+    });
+  </script>
+</dom-module>