feat(hooks): add useLayoutSnapshot

Author: garthenweb

README.md

@@ -36,9 +36,10 @@ For detection of some resize events the `ResizeObserver` API is used internally
 * [`ViewportProvider`](docs/api/ViewportProvider.md)
 * [`ObserveViewport`](docs/api/ObserveViewport_connectViewport_useViewport.md#render-props-event-handler-observeviewport)
 * [`connectViewport`](docs/api/ObserveViewport_connectViewport_useViewport.md#hoc-connectviewport)
-* [`NEW useViewport`](docs/api/ObserveViewport_connectViewport_useViewport.md#hooks-useviewport-usescroll-usedimensions)
-* [`NEW useScroll`](docs/api/ObserveViewport_connectViewport_useViewport.md#hooks-useviewport-usescroll-usedimensions)
-* [`NEW useDimensions`](docs/api/ObserveViewport_connectViewport_useViewport.md#hooks-useviewport-usescroll-usedimensions)
+* [`NEW useViewport`](docs/api/ObserveViewport_connectViewport_useViewport.md#hooks-useviewport-usescroll-usedimensions-useLayoutSnapshot)
+* [`NEW useScroll`](docs/api/ObserveViewport_connectViewport_useViewport.md#hooks-useviewport-usescroll-usedimensions-useLayoutSnapshot)
+* [`NEW useDimensions`](docs/api/ObserveViewport_connectViewport_useViewport.md#hooks-useviewport-usescroll-usedimensions-useLayoutSnapshot)
+* [`NEW useLayoutSnapshot`](docs/api/ObserveViewport_connectViewport_useViewport.md#hooks-useviewport-usescroll-usedimensions-useLayoutSnapshot)
 * [`ObserveBoundingClientRect`](docs/api/ObserveBoundingClientRect.md)
 * [Types](docs/api/types.md)
 

docs/api/ObserveViewport_connectViewport_useViewport.md

@@ -84,7 +84,7 @@ render(
 );
 ```
 
-## Hooks: `useViewport`, `useScroll`, `useDimensions`
+## Hooks: `useViewport`, `useScroll`, `useDimensions`, `useLayoutSnapshot`
 
 [Hooks](https://reactjs.org/docs/hooks-intro.html) are probably the easiest way to update your components but as of now needs to be consumed with care because this API and hooks in general are in early stage and thus are may contain bugs or will undergo breaking changes. As always, please report bugs if you find some.
 
@@ -94,8 +94,8 @@ render(
 
 | Property | Type | Required? | Description |
 |:---|:---|:---:|:---|
-| disableScrollUpdates | boolean |  | Disables updates to scroll events |
-| disableDimensionsUpdates | boolean |  | Disables updates to dimensions events |
+| disableScrollUpdates | boolean |  | Disables updates to scroll events (only for `useViewport` and `useLayoutSnapshot`) |
+| disableDimensionsUpdates | boolean |  | Disables updates to dimensions events (only for `useViewport` and `useLayoutSnapshot`) |
 | deferUpdateUntilIdle | boolean |  | Defers to trigger updates until the collector is idle. See [Defer Events](../concepts/defer_events.md) |
 | priority | `'low'`, `'normal'`, `'high'`, `'highest'` |  | Allows to set a priority of the update. See [Defer Events](../concepts/scheduler.md) |
 

docs/concepts/defer_events.md

@@ -6,7 +6,7 @@ This option is available for
 
 * ObserveViewport
 * connectViewport
-* useViewport, useScroll, useDimensions
+* useViewport, useScroll, useDimensions, useLayoutSnapshot
 
 ## Example
 

docs/concepts/recalculateLayoutBeforeUpdate.md

@@ -11,6 +11,7 @@ The optional `recalculateLayoutBeforeUpdate` property, which accepts a function,
 This option is available for
 
 * ObserveViewport
+* useLayoutSnapshot
 
 ## Example
 
@@ -19,4 +20,10 @@ This option is available for
   recalculateLayoutBeforeUpdate={() => el.getBoundingClientRect()}
   onUpdate={({ scroll }, rect) => console.log('Top offset: ', scroll.y + rect.top))}
 />
+
+const Component = () => {
+  const offsetTop = useLayoutSnapshot(
+    ({ scroll }) => scroll.y + el.getBoundingClientRect().top
+  );
+}
 ```

examples/index.tsx

@@ -6,6 +6,7 @@ import {
   ObserveViewport,
   connectViewport,
   useScroll,
+  useLayoutSnapshot,
   useDimensions,
 } from '../lib/index';
 import StickyScrollUp from './StickyScrollUp';
@@ -26,17 +27,24 @@ const ViewportHeader = connectViewport({ omit: ['scroll'] })<{ a: string }>(
 );
 
 const DisplayViewport = () => {
+  const div = React.useRef(null);
   const { x, y } = useScroll({
     priority: 'low',
   });
   const { documentHeight, clientWidth } = useDimensions({
     priority: 'low',
   });
+  const offsetTop = useLayoutSnapshot<number>(({ scroll }) => {
+    if (!div.current) {
+      return 0;
+    }
+    return div.current.getBoundingClientRect().top + scroll.y;
+  });
   return (
-    <>
+    <div ref={div}>
       x: {x}, y: {y}, documentHeight: {documentHeight}, clientWidth:{' '}
-      {clientWidth}
-    </>
+      {clientWidth}, element offsetTop: {offsetTop}
+    </div>
   );
 };
 

lib/hooks.ts

@@ -8,6 +8,10 @@ import {
 import { IViewport, IScroll, IDimensions, PriorityType } from './types';
 import { warnNoContextAvailable } from './utils';
 
+interface IViewPortEffectOptions extends IFullOptions {
+  recalculateLayoutBeforeUpdate?: (viewport: IViewport) => any;
+}
+
 interface IFullOptions extends IOptions {
   disableScrollUpdates?: boolean;
   disableDimensionsUpdates?: boolean;
@@ -18,11 +22,11 @@ interface IOptions {
   priority?: PriorityType;
 }
 
-type HandleViewportChangeType = (viewport: IViewport) => void;
+type HandleViewportChangeType = (viewport: IViewport, snapshot: any) => void;
 
 const useViewportEffect = (
   handleViewportChange: HandleViewportChangeType,
-  options: IFullOptions,
+  options: IViewPortEffectOptions,
 ) => {
   const {
     addViewportChangeListener,
@@ -42,6 +46,7 @@ const useViewportEffect = (
         notifyDimensions: () => !options.disableDimensionsUpdates,
         notifyOnlyWhenIdle: () => Boolean(options.deferUpdateUntilIdle),
         priority: () => options.priority || 'normal',
+        recalculateLayoutBeforeUpdate: options.recalculateLayoutBeforeUpdate,
       });
       return () => removeViewportChangeListener(handleViewportChange);
     },
@@ -76,3 +81,18 @@ export const useViewport = (options: IFullOptions = {}): IViewport => {
 
   return state;
 };
+
+export const useLayoutSnapshot = <T = any>(
+  recalculateLayoutBeforeUpdate: (viewport: IViewport) => T,
+  options: IFullOptions = {},
+): null | T => {
+  const [state, setSnapshot]: [null | T, (state: T) => void] = useState(null);
+  useViewportEffect(
+    (viewport: IViewport, snapshot: T) => setSnapshot(snapshot),
+    {
+      ...options,
+      recalculateLayoutBeforeUpdate,
+    },
+  );
+  return state;
+};

lib/index.ts

@@ -4,7 +4,12 @@ export {
   default as ObserveBoundingClientRect,
 } from './ObserveBoundingClientRect';
 export { default as ObserveViewport } from './ObserveViewport';
-export { useScroll, useDimensions, useViewport } from './hooks';
+export {
+  useScroll,
+  useDimensions,
+  useViewport,
+  useLayoutSnapshot,
+} from './hooks';
 export { IRect, IScroll, IDimensions } from './types';
 
 export const VERSION = '__VERSION__';