fix(promise): return promises consistently, and only smooth scroll when needed (#136)

* update readme

* better easing examples

* one more example

* expand test cases

* add test case for fallbacks

* Always return a promise

* resolve with the actions that got performed

* Add umd instructions to readme

* add test case for no-op

* only smooth scroll when needed

Author: stipsan

README.md

@@ -18,6 +18,12 @@ And while `scroll-into-view-if-needed` use the same default options as browsers
 yarn add smooth-scroll-into-view-if-needed
 ```
 
+The UMD build is also available on [unpkg](https://unpkg.com/smooth-scroll-into-view-if-needed/umd/):
+
+<script src="https://unpkg.com/smooth-scroll-into-view-if-needed/umd/smooth-scroll-into-view-if-needed.min.js"></script>
+
+You can find the library on `window.scrollIntoView`.
+
 ## Usage
 
 ```js
@@ -52,10 +58,6 @@ This library rely on `Promise` and `requestAnimationFrame`. This library does no
 
 Check the full API in [`scroll-into-view-if-needed`](https://github.com/stipsan/scroll-into-view-if-needed#api).
 
-This library differs from the API in `scroll-into-view-if-needed` in the following ways:
-
-- the second argument can't be a boolean, it must be either undefined or an object.
-
 ### scrollIntoView(target, [options]) => Promise
 
 `scroll-into-view-if-needed` does not return anything, while this library will return a Promise that is resolved when all of the scrolling boxes are finished scrolling.
@@ -95,15 +97,32 @@ Type: `Function`
 
 > Introduced in `v1.1.0`
 
-The default easing is implemented like this, with `t` being in the range of `0` => `1`:
+The default easing is `easeOutQuint` based on these algorithms: https://gist.github.com/gre/1650294#file-easing-js
+
+Linear example:
 
 ```typescript
 scrollIntoView(node, {
-  ease: t => 0.5 * (1 - Math.cos(Math.PI * t)),
+  ease: t => t,
 })
 ```
 
-Here's more examples, like easeInCubic etc: https://gist.github.com/gre/1650294#file-easing-js
+Acceleration until halfway, then deceleration:
+
+```typescript
+scrollIntoView(node, {
+  ease: t =>
+    t < 0.5 ? 4 * t * t * t : (t - 1) * (2 * t - 2) * (2 * t - 2) + 1,
+})
+```
+
+Sine easing in and out:
+
+```typescript
+scrollIntoView(node, {
+  ease: t => (1 + Math.sin(Math.PI * t - Math.PI / 2)) / 2,
+})
+```
 
 ## Credits
 

src/index.ts

@@ -38,7 +38,6 @@ type Context = {
 function step(context: Context) {
   const time = now()
   const elapsed = Math.min((time - context.startTime) / context.duration, 1)
-
   // apply easing to elapsed time
   const value = context.ease(elapsed)
 
@@ -79,7 +78,7 @@ function smoothScroll(
     el.scrollTop = y
   }
 
-  // scroll looping over a frame
+  // scroll looping over a frame if needed
   step({
     scrollable: scrollable,
     method: method,
@@ -112,26 +111,37 @@ function scroll<T>(target: Element, options?: any) {
       boundary: overrides.boundary,
       behavior: actions =>
         Promise.all(
-          actions.map(
-            ({ el, left, top }) =>
-              new Promise(resolve =>
-                smoothScroll(
+          actions.reduce((results: Promise<any>[], { el, left, top }) => {
+            const startLeft = el.scrollLeft
+            const startTop = el.scrollTop
+            if (startLeft === left && startTop === top) {
+              return results
+            }
+
+            return [
+              ...results,
+              new Promise(resolve => {
+                return smoothScroll(
                   el,
                   left,
                   top,
                   overrides.duration,
                   overrides.ease,
-                  () => resolve()
+                  () =>
+                    resolve({
+                      el,
+                      left: [startLeft, left],
+                      top: [startTop, top],
+                    })
                 )
-              )
-          )
+              }),
+            ]
+          }, [])
         ),
     })
   }
 
-  // @TODO maybe warn when someone could be using this library this way unintentionally
-
-  return scrollIntoView<T>(target, options)
+  return Promise.resolve(scrollIntoView<T>(target, options))
 }
 
 // re-assign here makes the flowtype generation work

tests/interface.test.ts

@@ -1,11 +1,39 @@
 import scrollIntoView from '../src'
 
+// This mock supports two scenarios:
+// 1. Default smooth scrolling, return empty array to ensure no scrolling is attempted.
+// 2. Falling back to scroll-into-view-if-needed, simulate an array over scroll actions
+// This enables tests to know which of the two cases is in effect, and verify if it's correct.
 jest.mock(
   'scroll-into-view-if-needed',
-  () => (_target: Element, options: any) => options.behavior([])
+  () => (_target: Element, options: any) =>
+    typeof options.behavior == 'function'
+      ? options.behavior([])
+      : [{ el: {}, top: 0, left: 0 }]
 )
 
 test('options is optional', () => {
   expect.assertions(1)
   return expect(scrollIntoView(document.body)).resolves.toEqual([])
 })
+
+test('behavior option is optional', () => {
+  expect.assertions(1)
+  return expect(
+    scrollIntoView(document.body, { scrollMode: 'if-needed' })
+  ).resolves.toEqual([])
+})
+
+test('behavior option set to smooth works correctly', () => {
+  expect.assertions(1)
+  return expect(
+    scrollIntoView(document.body, { behavior: 'smooth' })
+  ).resolves.toEqual([])
+})
+
+test('other behavior options still returns a promise', () => {
+  expect.assertions(1)
+  return expect(
+    scrollIntoView(document.body, { behavior: 'auto' })
+  ).resolves.toEqual([{ el: {}, top: 0, left: 0 }])
+})

tests/scroll.test.ts

@@ -0,0 +1,33 @@
+beforeEach(() => {
+  jest.resetModules()
+})
+
+test('resolves after scroll is completed', () => {
+  jest.doMock(
+    'scroll-into-view-if-needed',
+    () => (_target: Element, options: any) =>
+      options.behavior([
+        { el: { scrollTop: 0, scrollLeft: 0 }, top: 60, left: 60 },
+      ])
+  )
+  const scrollIntoView = require('../src').default
+  expect.assertions(1)
+  return expect(scrollIntoView(document.body)).resolves.toEqual([
+    { el: { scrollTop: 60, scrollLeft: 60 }, top: [0, 60], left: [0, 60] },
+  ])
+})
+
+test('resolves right away if there is nothign to scroll', () => {
+  jest.doMock(
+    'scroll-into-view-if-needed',
+    () => (_target: Element, options: any) =>
+      options.behavior([
+        { el: { scrollTop: 0, scrollLeft: 0 }, top: 0, left: 0 },
+      ])
+  )
+  const scrollIntoView = require('../src').default
+  expect.assertions(1)
+  return expect(
+    scrollIntoView(document.body, { duration: Number.MAX_VALUE })
+  ).resolves.toEqual([])
+})