feat(ObserveViewport): implement deferUpdateUntilIdle option

deferUpdateUntilIdle allows to defer the update as long as no events
are collected anymore. Regardless whether the component is only
listening for e.g. dimensions updates, it is also defered for scroll
updates. This option is useful for updates that are optional and can
be defered until the page has time to do so. The onUpdate function
is always triggered with the latest viewport state.

At the moment the implmentation is based on a simple debounce
functionality with a wait of 700ms. In case it makes sense it
might get smarter in the future.

Author: garthenweb

examples/index.tsx

@@ -88,6 +88,13 @@ class Example extends React.PureComponent<{}, { disabled: boolean }> {
               }
             }}
           />
+          <ObserveViewport
+            deferUpdateUntilIdle
+            disableScrollUpdates
+            onUpdate={props => {
+              console.log('update dimensions lazy', props.dimensions);
+            }}
+          />
           <Placeholder />
           <Placeholder />
           {this.renderButton()}

lib/ConnectViewport.tsx

@@ -13,9 +13,11 @@ type TPropStrings = 'scroll' | 'dimensions';
 
 interface IOptions {
   omit?: TPropStrings[];
+  deferUpdateUntilIdle?: boolean;
 }
 
 export default function connect(options: IOptions = {}) {
+  const deferUpdateUntilIdle = Boolean(options.deferUpdateUntilIdle);
   const omit = options.omit || [];
   const shouldOmitScroll = omit.indexOf('scroll') !== -1;
   const shouldOmitDimensions = omit.indexOf('dimensions') !== -1;
@@ -33,6 +35,7 @@ export default function connect(options: IOptions = {}) {
           <ObserveViewport
             disableScrollUpdates={shouldOmitScroll}
             disableDimensionsUpdates={shouldOmitDimensions}
+            deferUpdateUntilIdle={deferUpdateUntilIdle}
           >
             {({ scroll, dimensions }) => (
               <WrappedComponent

lib/ObserveViewport.tsx

@@ -27,6 +27,7 @@ interface IProps {
   recalculateLayoutBeforeUpdate?: (props: IChildProps) => any;
   disableScrollUpdates: boolean;
   disableDimensionsUpdates: boolean;
+  deferUpdateUntilIdle: boolean;
 }
 
 interface IContext {
@@ -55,6 +56,7 @@ export default class ObserveViewport extends React.Component<IProps, IState> {
   static defaultProps = {
     disableScrollUpdates: false,
     disableDimensionsUpdates: false,
+    deferUpdateUntilIdle: false,
   };
 
   constructor(props: IProps) {
@@ -148,6 +150,7 @@ ReactDOM.render(
     addViewportChangeListener(this.handleViewportUpdate, {
       notifyScroll: () => !this.props.disableScrollUpdates,
       notifyDimensions: () => !this.props.disableDimensionsUpdates,
+      notifyOnlyWhenIdle: () => this.props.deferUpdateUntilIdle,
       recalculateLayoutBeforeUpdate: (viewport: IViewport) => {
         if (this.props.recalculateLayoutBeforeUpdate) {
           return this.props.recalculateLayoutBeforeUpdate(viewport);

lib/ViewportCollector.tsx

@@ -1,5 +1,4 @@
 import * as React from 'react';
-import debounce from 'lodash.debounce';
 import memoize from 'memoize-one';
 import raf from 'raf';
 
@@ -8,14 +7,16 @@ import {
   shallowEqualPrivateScroll,
   shallowEqualDimensions,
   browserSupportsPassiveEvents,
+  simpleDebounce,
+  debounceOnUpdate,
 } from './utils';
 
 import {
   IDimensions,
   IPrivateScroll,
   IScroll,
   IViewport,
-  IViewportCollectorUpdateOptions,
+  OnUpdateType,
 } from './types';
 
 export const SCROLL_DIR_DOWN = Symbol('SCROLL_DIR_DOWN');
@@ -136,10 +137,8 @@ export const createInitDimensionsState = (): IDimensions => {
 };
 
 interface IProps {
-  onUpdate: (
-    props: IViewport,
-    options: IViewportCollectorUpdateOptions,
-  ) => void;
+  onUpdate: OnUpdateType;
+  onIdledUpdate?: OnUpdateType;
 }
 
 export default class ViewportCollector extends React.PureComponent<IProps> {
@@ -211,7 +210,7 @@ export default class ViewportCollector extends React.PureComponent<IProps> {
     this.componentMightHaveUpdated = true;
   };
 
-  handleResize = debounce(() => {
+  handleResize = simpleDebounce(() => {
     Object.assign(this.dimensionsState, getClientDimensions());
 
     this.componentMightHaveUpdated = true;
@@ -251,9 +250,19 @@ export default class ViewportCollector extends React.PureComponent<IProps> {
         scrollDidUpdate,
         dimensionsDidUpdate,
       });
+      this.updateOnIdle(publicState, {
+        scrollDidUpdate,
+        dimensionsDidUpdate,
+      });
     }
   };
 
+  updateOnIdle = debounceOnUpdate((...args) => {
+    if (typeof this.props.onIdledUpdate === 'function') {
+      this.props.onIdledUpdate(...args);
+    }
+  }, 700);
+
   getPropsFromState(): IViewport {
     return {
       scroll: this.getPublicScroll(

lib/ViewportProvider.tsx

@@ -43,14 +43,21 @@ export default class ViewportProvider extends React.PureComponent<
     clearTimeout(this.updateListenersTick);
   }
 
-  updateListeners = (
+  triggerUpdateToListeners = (
     publicState: IViewport,
     { scrollDidUpdate, dimensionsDidUpdate }: IViewportCollectorUpdateOptions,
+    options?: { isIdle: boolean },
   ) => {
+    const { isIdle } = Object.assign({ isIdle: false }, options);
     const updatableListeners = this.listeners.filter(
-      ({ notifyScroll, notifyDimensions }) =>
-        (notifyScroll() && scrollDidUpdate) ||
-        (notifyDimensions() && dimensionsDidUpdate),
+      ({ notifyScroll, notifyDimensions, notifyOnlyWhenIdle }) => {
+        if (notifyOnlyWhenIdle() && !isIdle) {
+          return false;
+        }
+        const updateForScroll = notifyScroll() && scrollDidUpdate;
+        const updateForDimensions = notifyDimensions() && dimensionsDidUpdate;
+        return updateForScroll || updateForDimensions;
+      },
     );
     const layouts = updatableListeners.map(
       ({ recalculateLayoutBeforeUpdate }) => {
@@ -100,7 +107,12 @@ export default class ViewportProvider extends React.PureComponent<
       return (
         <React.Fragment>
           {this.state.hasListeners && (
-            <ViewportCollector onUpdate={this.updateListeners} />
+            <ViewportCollector
+              onUpdate={this.triggerUpdateToListeners}
+              onIdledUpdate={(state, updates) =>
+                this.triggerUpdateToListeners(state, updates, { isIdle: true })
+              }
+            />
           )}
           <ViewportContext.Provider value={value}>
             {this.props.children}

lib/types.ts

@@ -62,10 +62,16 @@ export type TViewportChangeHandler = (
 export interface IViewportChangeOptions {
   notifyScroll: () => boolean;
   notifyDimensions: () => boolean;
+  notifyOnlyWhenIdle: () => boolean;
   recalculateLayoutBeforeUpdate?: (viewport: IViewport) => any;
 }
 
 export interface IViewportCollectorUpdateOptions {
   scrollDidUpdate: boolean;
   dimensionsDidUpdate: boolean;
 }
+
+export type OnUpdateType = (
+  props: IViewport,
+  options: IViewportCollectorUpdateOptions,
+) => void;

lib/utils.ts

@@ -1,4 +1,10 @@
-import { IRect, IScroll, IPrivateScroll, IDimensions } from './types';
+import {
+  IRect,
+  IScroll,
+  IPrivateScroll,
+  IDimensions,
+  OnUpdateType,
+} from './types';
 
 export const shallowEqualScroll = (a: IScroll, b: IScroll) => {
   if (a === b) {
@@ -79,3 +85,37 @@ export const browserSupportsPassiveEvents = (() => {
   }
   return supportsPassive;
 })();
+
+export const simpleDebounce = <F extends (...args: any[]) => any>(
+  fn: F,
+  delay: number,
+): F => {
+  let timeout: NodeJS.Timer;
+  return ((...args: any[]) => {
+    clearTimeout(timeout);
+    timeout = setTimeout(fn, delay, ...args);
+  }) as F;
+};
+
+export const debounceOnUpdate = (
+  fn: OnUpdateType,
+  delay: number,
+): OnUpdateType => {
+  let timeout: NodeJS.Timer;
+  let scrollDidUpdate = false;
+  let dimensionsDidUpdate = false;
+
+  return (viewport, options) => {
+    clearTimeout(timeout);
+    scrollDidUpdate = scrollDidUpdate || options.scrollDidUpdate;
+    dimensionsDidUpdate = dimensionsDidUpdate || options.dimensionsDidUpdate;
+    timeout = setTimeout(() => {
+      fn(viewport, {
+        scrollDidUpdate,
+        dimensionsDidUpdate,
+      });
+      scrollDidUpdate = false;
+      dimensionsDidUpdate = false;
+    }, delay);
+  };
+};

package-lock.json

@@ -31,8 +31,6 @@
   ],
   "license": "MIT",
   "devDependencies": {
-    "@types/lodash.debounce": "^4.0.4",
-    "@types/lodash.throttle": "^4.1.4",
     "@types/memoize-one": "^3.1.1",
     "@types/node": "^10.12.0",
     "@types/react": "^16.4.18",
@@ -51,7 +49,6 @@
     "typescript": "^3.1.3"
   },
   "dependencies": {
-    "lodash.debounce": "^4.0.8",
     "memoize-one": "^4.0.2",
     "raf": "^3.4.0",
     "recompose": "^0.30.0"