Merge pull request #12 from rob2d/next

new options interface, documentation and examples

Author: rob2d

.gitignore

@@ -1 +1,2 @@
 node_modules
+media

README.md

@@ -2,7 +2,8 @@
 
 ![npm](https://img.shields.io/npm/v/use-viewport-sizes.svg?color=blue) ![David](https://img.shields.io/david/rob2d/use-viewport-sizes.svg) ![npm](https://img.shields.io/npm/dw/use-viewport-sizes.svg?color=red) ![GitHub issues](https://img.shields.io/github/issues-raw/rob2d/use-viewport-sizes.svg) ![NPM](https://img.shields.io/npm/l/use-viewport-sizes.svg)
 
-a tiny React hook which allows you to track visible window viewport size in your components w/ an optional debounce or custom memo function for updates for optimal rendering.
+a tiny React hook which allows you to track visible window viewport size in your components w/ an optional debounce and
+other flexible options for optimal usage.
 
 ## Installation ##
 
@@ -11,8 +12,8 @@ npm install -D use-viewport-sizes
 ```
 
 ## Benefits ##
-- extremely lightweight and dependency-free -- **3.75kb** without/before gzipping.
-- only one `window.onresize` handler used to subscribe to any changes in an unlimited number of components as well despite several different paradigms that pull from this.
+- extremely lightweight and zero dependencies -- adds **1.6kb** after gzip.
+- only one `window.onresize` handler used to subscribe to any changes in an unlimited number of components no matter the use-cases.
 - optional debounce to delay updates until user stops dragging their window for a moment; this can make expensive components with size-dependent calculations run much faster and your app feel smoother.
 - debouncing does not create new handlers or waste re-renders in your component; the results are also pooled from only one resize result.
 - optional hash function to update component subtree only at points you would like to.
@@ -26,12 +27,11 @@ npm install -D use-viewport-sizes
 <center>
 <img src="./doc/use-viewport-sizes.gif" />
 
-*Interact with the example shown on CodeSandox* @
-[https://codesandbox.io/s/react-hooks-viewport-sizes-demo-forked-7rr9c](https://codesandbox.io/s/react-hooks-viewport-sizes-demo-forked-7rr9c)
+[CodeSandbox IDE](https://codesandbox.io/s/react-hooks-viewport-sizes-demo-forked-i8urr)
 
 </center>
 
-### **Without Debouncing**
+### **Basic Use-case**
 *registers dimension changes on every resize event immediately*
 
 ```js
@@ -45,29 +45,49 @@ function MyComponent(props) {
 }
 ```
 
+### **Measure/Update only on one dimension**
+
+If passed `options.dimension` as `w` or `h`, only the viewport width or height will be
+measured and observed for updates.
+The only dimension returned in the return array value will be the width or height, according
+to what was passed.
+
+```js
+import React from 'react';
+import useViewportSizes from 'use-viewport-sizes';
+
+function MyComponent(props) {
+    const [vpHeight] = useViewportSizes({ dimension: 'h' });
+
+    ...renderLogic
+}
+```
+
 
 ### **With Debouncing**
 
-If passed a number as the first argument, it registers dimension changes only when a user stops dragging/resizing the window for a specified number of miliseconds. This is useful for listening to expensive components such as data grids which may be too
+If passed `options.debounceTimeout`, or options are entered as a `Number`, it registers dimension changes only when a user stops dragging/resizing the window for a specified number of miliseconds. This is useful for listening to expensive components such as data grids which may be too
 expensive to re-render during window resize dragging.
+
 ```js
-import React from 'react'
-import useViewportSizes from 'use-viewport-sizes'
+import React from 'react';
+import useViewportSizes from 'use-viewport-sizes';
 
-function MyExpensivelyRenderedComponent (props) {
-    const [vpWidth, vpHeight] = useViewportSizes(1000); // 1s debounce
+function MyExpensivelyRenderedComponent(props) {
+    const [vpWidth, vpHeight] = useViewportSizes({ debounceTimeout: 1000 }); // 1s debounce
 
-    ...renderLogic
+    // ...renderLogic
 }
 ```
 
 ### **Only update vpW/vpH passed on specific conditions**
-If passed a function as the first argument, it will use this to calculate a hash that only updates the viewport when the calculation changes. In the example here, we are using it to detect when we have a breakpoint change which may change how a component is rendered if this is not fully possible or inconvenient via CSS `@media` queries. The hash will also be available as the 3rd value returned from the hook for convenience.
+If passed an `options.hasher` function, this will be used to calculate a hash that only updates the viewport when the calculation changes. In the example here, we are using it to detect when we have a breakpoint change which may change how a component is rendered if this is not fully possible or inconvenient via CSS `@media` queries. The hash will also be available as the 3rd value returned from the hook for convenience.
+
 ```js
 import React from 'react';
 import useViewportSizes from 'use-viewport-sizes';
 
-function getBreakpoint({ vpW, vpH }) {
+function getBreakpointHash({ vpW, vpH }) {
     if(vpW < 640) {
         return 'md';
     }
@@ -83,7 +103,7 @@ function getBreakpoint({ vpW, vpH }) {
 }
 
 function MyBreakpointBehaviorComponent() {
-    const [vpW, vpH, bp] = useViewportSizes(getBreakpoint);
+    const [vpW, vpH, bp] = useViewportSizes({ hasher: getBreakpointHash });
 
     // do-something-with-breakpoints in render
     // and add new update for vpW, vpH in this component's
@@ -94,24 +114,24 @@ function MyBreakpointBehaviorComponent() {
 
 ### **Server Side Rendering**
 
-*While serverside rendering is supported, it requires an explicit update via `useEffect` since viewport does not actually exist on the server before rendering to client. The following has been tested with [NextJS](https://nextjs.org/).*
+*Note: While serverside rendering is supported, it requires an explicit update via `useEffect` since viewport does not actually exist on the server before rendering to client. The following has been tested with [NextJS](https://nextjs.org/).*
 
-*Sidenote that you will see a `useLayoutEffect` warning from React. This is perfectly normal as there is no viewport/context to paint to when pre-rendering in SSR and will not interfere with your app once served to the client*
+*Sidenote that you will see a `useLayoutEffect` warning from React. This is perfectly expected as there is no viewport/context to paint to when pre-rendering in SSR and will not interfere with your app once served to the client*
 
 ```js
 import React, { useLayoutEffect } from 'react'
 import useViewportSizes from 'use-viewport-sizes'
 
 function MySSRComponent (props) {
-    const [vpWidth, vpHeight, updateVpSizes] = useViewportSizes()
+    const [vpW, vpH, updateVpSizes] = useViewportSizes();
 
     // below, we add one post-render update
     // in order to register the client's viewport sizes
     // after serving SSR content
 
-    useEffect(()=> { updateVpSizes(); }, []);
+    useEffect(()=> { updateVpSizes() }, []);
 
-    ...renderLogic
+    // ...renderLogic
 }
 ```
 

build/index.d.ts

@@ -1,19 +1,18 @@
 declare module 'use-viewport-sizes' {
+    export type VPSizesHasher = ({ vpW: number, vpH: number }) => String;
+    export type VPSizesOptions ={
+        debounceTimeout?: number,
+        hasher?: VPSizesHasher,
+        dimension?: 'w'|'h'|'both' = 'both'
+    };
+
     /**
      * Hook which observes viewport dimensions. Returns [width, height] of
-     * current visible viewport of app.
-     *
-     * If no input specified, returns the [width, height] when the window changes.
-     *
-     * If input is specified as a number, it interprets this as the number of
-     * miliseconds to debounce before updates.
-     *
-     * If the input is specified as a function, it accepts a callback
-     * with the viewport width and height passed in the first arg as
-     * { vpW, vpH }, and will only return a new value and update when
-     * the hash-value returned changes.
+     * current visible viewport of app, or the specific dimension
      */
     export default function(
-        input:number | (({ vpW: number, vpH: number }) => String)
-    ):[vpW: number, vpH: number];
+        input:number | VPSizesHasher | VPSizesOptions
+    ):([vpW: number, vpH: number, triggerResize: Function] |
+        [dimension: number, triggerResize:Function]
+    );
 }

build/index.js

@@ -1,15 +1,16 @@
 {
   "name": "use-viewport-sizes",
-  "version": "0.2.12",
+  "version": "0.3.0",
   "description": "a tiny React hook which allows you to track visible window viewport size in your components w/ an optional debounce or custom memo function for updates for optimal rendering.",
   "main": "./build/index.js",
   "types": "./build/index.d.ts",
   "scripts": {
     "start": "webpack --watch",
     "build": "webpack",
-    "dev": "webpack-dev-server --env testServer --mode development --open"
+    "dev": "webpack-dev-server --env testServer --mode development --open",
+    "prepublishOnly": "npm run build"
   },
-  "peerDependencies": {
+  "peer Dependencies": {
     "react": "^16.8.6"
   },
   "devDependencies": {

doc/use-viewport-sizes.gif

@@ -1,19 +1,18 @@
 declare module 'use-viewport-sizes' {
+    export type VPSizesHasher = ({ vpW: number, vpH: number }) => String;
+    export type VPSizesOptions ={
+        debounceTimeout?: number,
+        hasher?: VPSizesHasher,
+        dimension?: 'w'|'h'|'both' = 'both'
+    };
+
     /**
      * Hook which observes viewport dimensions. Returns [width, height] of
-     * current visible viewport of app.
-     *
-     * If no input specified, returns the [width, height] when the window changes.
-     *
-     * If input is specified as a number, it interprets this as the number of
-     * miliseconds to debounce before updates.
-     *
-     * If the input is specified as a function, it accepts a callback
-     * with the viewport width and height passed in the first arg as
-     * { vpW, vpH }, and will only return a new value and update when
-     * the hash-value returned changes.
+     * current visible viewport of app, or the specific dimension
      */
     export default function(
-        input:number | (({ vpW: number, vpH: number }) => String)
-    ):[vpW: number, vpH: number];
+        input:number | VPSizesHasher | VPSizesOptions
+    ):([vpW: number, vpH: number, triggerResize: Function] |
+        [dimension: number, triggerResize:Function]
+    );
 }