Add onProgress to track the scroll progress between enter / leave

README.md

@@ -75,6 +75,16 @@ below) has changed.
 />
 ```
 
+If you need more information over the scrolling progress you can use pass a function to the `onProgress` prop.
+```js
+<Waypoint
+  onProgress={this._handleProgress}
+/>
+```
+It will fire on every position change inside the object. The information is passed
+with the `progress` attribute that ranges from 0 - 1. Using this can result in a big performance hit,
+as a lot of scrolling events are firing, only use this with caution.
+
 Waypoints can take a child, allowing you to track when a section of content
 enters or leaves the viewport. For details, see [Children](#children), below.
 
@@ -105,6 +115,12 @@ enters or leaves the viewport. For details, see [Children](#children), below.
      */
     onLeave: PropTypes.func,
 
+    /**
+     * Function called when waypoint is in the viewport and the scroll position changed
+     */
+    onProgress: PropTypes.func,
+
+
     /**
      * Function called when waypoint position changes
      */
@@ -165,7 +181,7 @@ enters or leaves the viewport. For details, see [Children](#children), below.
   },
 ```
 
-All callbacks (`onEnter`/`onLeave`/`onPositionChange`) receive an object as the
+All callbacks (`onEnter`/`onLeave`/`onProgress`/`onPositionChange`) receive an object as the
 only argument. That object has the following properties:
 
 - `currentPosition` - the position that the waypoint has at the moment. One

index.d.ts

@@ -43,6 +43,13 @@ declare namespace Waypoint {
         viewportBottom: number;
     }
 
+    interface CallbackProgressArgs extends CallbackArgs {
+        /*
+         * Indicates the progress between the enter and leave event with a number between 0 and 1.
+         */
+        progress: number;
+    }
+
     interface WaypointProps {
         /**
          * Function called when waypoint enters viewport
@@ -56,6 +63,12 @@ declare namespace Waypoint {
          */
         onLeave?: (args: CallbackArgs) => void;
 
+        /**
+         * Function called when waypoint is inside viewport and a scroll event happens.
+         * @param {CallbackProgressArgs} args
+         */
+        onProgress?: (args: CallbackProgressArgs) => void;
+
         /**
          * Function called when waypoint position changes
          * @param {CallbackArgs} args

src/getCurrentProgress.js

@@ -0,0 +1,23 @@
+function clamp(val, min, max) {
+  return Math.min(Math.max(val, min), max);
+}
+
+/**
+ * @param {object} bounds An object with bounds data for the waypoint and
+ *   scrollable parent
+ * @return {integer} The current scroll progress of the Waypoint inside of its
+ *  scrollable parent
+ */
+export default function getCurrentProgress({
+  viewportBottom,
+  viewportTop,
+  waypointBottom,
+  waypointTop,
+}) {
+  const viewportHeight = viewportBottom - viewportTop || 1;
+  const waypointHeight = waypointBottom - waypointTop || 1;
+  const distance = viewportHeight + waypointHeight;
+  const traveled = waypointBottom - viewportTop;
+  const progress = 1 - clamp(traveled / distance, 0, 1);
+  return progress;
+}

src/waypoint.jsx

@@ -13,6 +13,7 @@ import debugLog from './debugLog';
 import ensureRefIsUsedByChild from './ensureRefIsUsedByChild';
 import isDOMElement from './isDOMElement';
 import getCurrentPosition from './getCurrentPosition';
+import getCurrentProgress from './getCurrentProgress';
 import onNextTick from './onNextTick';
 import resolveScrollableAncestorProp from './resolveScrollableAncestorProp';
 
@@ -25,6 +26,7 @@ const defaultProps = {
   horizontal: false,
   onEnter() { },
   onLeave() { },
+  onProgress() { },
   onPositionChange() { },
   fireOnRapidScroll: true,
 };
@@ -187,6 +189,7 @@ export class Waypoint extends React.PureComponent {
       onEnter,
       onLeave,
       fireOnRapidScroll,
+      onProgress,
     } = this.props;
 
     if (process.env.NODE_ENV !== 'production' && debug) {
@@ -197,11 +200,6 @@ export class Waypoint extends React.PureComponent {
     // Save previous position as early as possible to prevent cycles
     this._previousPosition = currentPosition;
 
-    if (previousPosition === currentPosition) {
-      // No change since last trigger
-      return;
-    }
-
     const callbackArg = {
       currentPosition,
       previousPosition,
@@ -211,12 +209,25 @@ export class Waypoint extends React.PureComponent {
       viewportTop: bounds.viewportTop,
       viewportBottom: bounds.viewportBottom,
     };
+
+    if (currentPosition === INSIDE) {
+      const progress = getCurrentProgress(bounds);
+      onProgress.call(this, Object.assign({}, callbackArg, { progress }));
+    }
+
+    if (previousPosition === currentPosition) {
+      // No change since last trigger
+      return;
+    }
+
     onPositionChange.call(this, callbackArg);
 
     if (currentPosition === INSIDE) {
       onEnter.call(this, callbackArg);
     } else if (previousPosition === INSIDE) {
       onLeave.call(this, callbackArg);
+      const progress = +(currentPosition === ABOVE);
+      onProgress.call(this, Object.assign({}, callbackArg, { progress }));
     }
 
     const isRapidScrollDown = previousPosition === BELOW
@@ -327,6 +338,7 @@ if (process.env.NODE_ENV !== 'production') {
     onEnter: PropTypes.func,
     onLeave: PropTypes.func,
     onPositionChange: PropTypes.func,
+    onProgress: PropTypes.func,
     fireOnRapidScroll: PropTypes.bool,
     // eslint-disable-next-line react/forbid-prop-types
     scrollableAncestor: PropTypes.any,