feat(animation): expose duration and ease options (#28)

* update docs

* improve typescript typings

* check bundlesize

* update default sizes

* implement new options

* bump peer dependency

* refactor to newer standards

* handy link

Author: stipsan

.circleci/config.yml

@@ -38,6 +38,7 @@ jobs:
       - restore-cache: *restore-cache
       - *install
       - run: yarn build
+      - run: npx bundlesize
       - save-cache: *save-cache
 
   Semantic Release:

README.md

@@ -8,6 +8,7 @@
 ![smooth-scroll-into-view-if-needed](https://user-images.githubusercontent.com/81981/39496447-c1153942-4d9e-11e8-92c8-ad5ac0e406ac.png)
 
 This is an addon to [`scroll-into-view-if-needed`](https://www.npmjs.com/package/scroll-into-view-if-needed) that [ponyfills](https://ponyfill.com) smooth scrolling.
+And while `scroll-into-view-if-needed` use the same default options as browsers and the spec does, this library is a bit more opinionated and include bonus features that help you build great UIs.
 
 ## [Demo](https://scroll-into-view-if-needed.netlify.com/)
 
@@ -23,18 +24,17 @@ yarn add smooth-scroll-into-view-if-needed scroll-into-view-if-needed
 import scrollIntoView from 'smooth-scroll-into-view-if-needed'
 const node = document.getElementById('hero')
 
-// If all you want is for all your users to have stuff smooth scroll into view
-scrollIntoView(node, { behavior: 'smooth' })
+// `options.behavior` is set to `smooth` by default so you don't have to pass options like in `scroll-into-view-if-needed`
+scrollIntoView(node)
 
-// combine it with any of the other options
+// combine it with any of the other options from 'scroll-into-view-if-needed'
 scrollIntoView(node, {
-  behavior: 'smooth',
   scrollMode: 'if-needed',
   block: 'nearest',
   inline: 'nearest',
 })
 
-// It returns a promise that is resolved when the animation is finished
+// a promise is always returned to help reduce boilerplate
 const sequence = async () => {
   const slide = document.getElementById('slide-3')
   // First smooth scroll to hero
@@ -44,6 +44,65 @@ const sequence = async () => {
 }
 ```
 
+## Polyfills
+
+This library rely on `Promise` and `requestAnimationFrame`. This library does not ship with polyfills for these to keep bundlesizes as low as possible.
+
+## API
+
+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.
+
+> The ability to cancel animations will be added in a future version.
+
+### options
+
+Type: `Object`
+
+#### behavior
+
+Type: `'auto' | 'smooth' | 'instant' | Function`<br> Default: `'smooth'`
+
+This option deviates from `scroll-into-view-if-needed` in two ways.
+
+* The default value is `smooth` instead of `auto`
+* Using `smooth` adds it to browsers that miss it, and overrides the native smooth scrolling in the browsers that have it to ensure the scrolling is consistent in any browser.
+
+#### duration
+
+Type: `number`<br> Default: `300`
+
+> Introduced in `v1.1.0`
+
+This setting is not a hard limit.
+The duration of a scroll differs depending on how many elements is scrolled, and the capabilities of the browser.
+On mobile the browser might pause or throttle the animation if the user switches to another tab.
+And there might be nothing to scroll.
+No matter the scenario a Promise is returned so you can await on it.
+
+#### ease
+
+Type: `Function`
+
+> Introduced in `v1.1.0`
+
+The default easing is implemented like this, with `t` being in the range of `0` => `1`:
+
+```typescript
+scrollIntoView(node, {
+  ease: t => 0.5 * (1 - Math.cos(Math.PI * t)),
+})
+```
+
+Here's more examples, like easeInCubic etc: https://gist.github.com/gre/1650294#file-easing-js
+
 ## Credits
 
 * [smoothscroll](https://github.com/iamdustan/smoothscroll) for the reference implementation of smooth scrolling.

package.json

@@ -12,6 +12,7 @@
   },
   "version": "1.0.1-alpha.3",
   "main": "index.js",
+  "module": "es/index.js",
   "files": ["es", "typings", "umd"],
   "scripts": {
     "prebuild": "yarn clean",
@@ -31,7 +32,7 @@
     "typecheck": "tsc --noEmit"
   },
   "peerDependencies": {
-    "scroll-into-view-if-needed": "^2.1.1"
+    "scroll-into-view-if-needed": ">=2.1.6"
   },
   "devDependencies": {
     "@babel/cli": "7.0.0-beta.46",
@@ -79,6 +80,16 @@
   "browserify": {
     "transform": ["loose-envify"]
   },
+  "bundlesize": [
+    {
+      "path": "./umd/smooth-scroll-into-view-if-needed.min.js",
+      "maxSize": "2 kB"
+    },
+    {
+      "path": "./umd/smooth-scroll-into-view-if-needed.js",
+      "maxSize": "3.5 kB"
+    }
+  ],
   "lint-staged": {
     "*.js": ["prettier --write", "git add"],
     "*.{ts,tsx}": ["prettier --write", "git add"],
@@ -88,7 +99,6 @@
     "**/package.json": ["prettier-package-json --write", "git add"],
     "**/.babelrc": ["prettier --write", "git add"]
   },
-  "module": "es/index.js",
   "prettier": {
     "semi": false,
     "singleQuote": true,

src/index.ts

@@ -1,64 +1,71 @@
-import scrollIntoView from 'scroll-into-view-if-needed'
-import { Options } from 'scroll-into-view-if-needed/compute'
+import scrollIntoView, {
+  Options,
+  StandardBehaviorOptions,
+  CustomBehaviorOptions,
+} from 'scroll-into-view-if-needed'
+
+export interface CustomEasing {
+  (t: number): number
+}
+export interface SmoothBehaviorOptions extends Options {
+  behavior?: 'smooth'
+  duration?: number
+  ease?: CustomEasing
+}
 
 // Memoize so we're much more friendly to non-dom envs
 let memoizedNow
-var now = () => {
+const now = () => {
   if (!memoizedNow) {
     memoizedNow =
       'performance' in window ? performance.now.bind(performance) : Date.now
   }
   return memoizedNow()
 }
 
-const SCROLL_TIME = 300
-
-function ease(k) {
-  return 0.5 * (1 - Math.cos(Math.PI * k))
-}
-
 function step(context) {
-  var time = now()
-  var value
-  var currentX
-  var currentY
-  var elapsed = (time - context.startTime) / SCROLL_TIME
-
-  // avoid elapsed times higher than one
-  elapsed = elapsed > 1 ? 1 : elapsed
+  const time = now()
+  const elapsed = Math.min((time - context.startTime) / context.duration, 1)
 
   // apply easing to elapsed time
-  value = ease(elapsed)
+  const value = context.ease(elapsed)
 
-  currentX = context.startX + (context.x - context.startX) * value
-  currentY = context.startY + (context.y - context.startY) * value
+  const currentX = context.startX + (context.x - context.startX) * value
+  const currentY = context.startY + (context.y - context.startY) * value
 
-  context.method.call(context.scrollable, currentX, currentY)
+  context.method(currentX, currentY)
 
   // scroll more if we have not reached our destination
   if (currentX !== context.x || currentY !== context.y) {
-    requestAnimationFrame(step.bind(global, context))
+    requestAnimationFrame(() => step(context))
   }
 }
 
-function smoothScroll(el, x, y, cb) {
-  var scrollable
-  var startX
-  var startY
-  var method
-  var startTime = now()
+function smoothScroll(
+  el,
+  x,
+  y,
+  duration = 300,
+  ease = t => 0.5 * (1 - Math.cos(Math.PI * t)),
+  cb
+) {
+  let scrollable
+  let startX
+  let startY
+  let method
 
   // define scroll context
   if (el === document.documentElement) {
     scrollable = window
     startX = window.scrollX || window.pageXOffset
     startY = window.scrollY || window.pageYOffset
-    method = window.scroll
+    method = (x, y) => window.scroll(x, y)
   } else {
     scrollable = el
     startX = el.scrollLeft
     startY = el.scrollTop
     method = (x, y) => {
+      // @TODO use Element.scroll if it exists, as it is potentially better performing
       el.scrollLeft = x
       el.scrollTop = y
     }
@@ -68,31 +75,58 @@ function smoothScroll(el, x, y, cb) {
   step({
     scrollable: scrollable,
     method: method,
-    startTime: startTime,
+    startTime: now(),
     startX: startX,
     startY: startY,
     x: x,
     y: y,
+    duration,
+    ease,
     cb,
   })
 }
 
-export default (target, options: Options = {}) => {
-  const { behavior = 'smooth' } = options
+const shouldSmoothScroll = <T>(options: any): options is T => {
+  return (options && !options.behavior) || options.behavior === 'smooth'
+}
 
-  // @TODO detect if someone is using this library without smooth behavior and maybe warn
-  if (behavior !== 'smooth') {
-    return scrollIntoView(target, options)
+function scroll(target: Element, options?: SmoothBehaviorOptions): Promise<any>
+function scroll<T>(target: Element, options: CustomBehaviorOptions<T>): T
+function scroll(target: Element, options: StandardBehaviorOptions): void
+function scroll<T>(target, options) {
+  if (shouldSmoothScroll<SmoothBehaviorOptions>(options)) {
+    const overrides = options || {}
+    // @TODO replace <any> in promise signatures with better information
+    return scrollIntoView<Promise<any>>(target, {
+      block: overrides.block,
+      inline: overrides.inline,
+      scrollMode: overrides.scrollMode,
+      boundary: overrides.boundary,
+      behavior: actions =>
+        Promise.all(
+          actions.map(
+            ({ el, left, top }) =>
+              new Promise(resolve =>
+                smoothScroll(
+                  el,
+                  left,
+                  top,
+                  overrides.duration,
+                  overrides.ease,
+                  () => resolve()
+                )
+              )
+          )
+        ),
+    })
   }
 
-  return scrollIntoView(target, {
-    ...options,
-    behavior: actions =>
-      Promise.all(
-        actions.map(
-          ({ el, left, top }) =>
-            new Promise(resolve => smoothScroll(el, left, top, () => resolve()))
-        )
-      ),
-  })
+  // @TODO maybe warn when someone could be using this library this way unintentionally
+
+  return scrollIntoView<T>(target, options)
 }
+
+// re-assign here makes the flowtype generation work
+const smoothScrollIntoView = scroll
+
+export default smoothScrollIntoView