more testing, and readme updates

Author: ZeeCoder

CHANGELOG.md

@@ -2,18 +2,20 @@
 
 ## 5.0.0
 
-- **[BREAKING]** Removed Babel code transpiling and the ResizeObserver polyfill.
-- **[BREAKING]** Returning an object instead of an array, so that the returned
-  values could be omitted when not needed.
+- **[BREAKING]** `#14` Removed Babel code transpiling and the ResizeObserver polyfill.
+- **[BREAKING]** `#21` Returning an object instead of an array, so that values not
+  needed could be omitted.
 - `#18` Added missing copyright notice in the MIT license.
-- New `package.json` scripts to ease development
 - Improved ref handling:
-  - You can now pass in your own ref
-  - Ref changes are handled: TODO better explanation
-  - The hook will no longer break if an invalid ref is passed in.
-    (Anything other than an object with a `.current` value of an `Element` )
-- TODO: Document useDefaults
-- TODO: Document throttle / debounce solutions
+  - `#16` You can now pass in your own ref
+  - The same hook instance can now be reused with different refs
+  - The hook will no longer break if the ref is not immediately filled.
+    (Anything other than an object with a `.current` value of an `Element` will
+    be ignored.)
+- Made defaults optional with the `useDefaults` option.
+- New `package.json` scripts to ease development
+- Added throttle and debounce guides to the readme
+- More tests
 
 ## 4.0.0
 

README.md

@@ -24,7 +24,7 @@ yarn add use-resize-observer --dev
 npm install use-resize-observer --save-dev
 ```
 
-## Usage
+## Basic Usage
 
 ```js
 import React from "react";
@@ -43,7 +43,28 @@ const App = () => {
 
 ## Passing in your own `ref`
 
-TODO
+You can pass in your own ref to measure, use now.
+This can be useful if you already have a ref from somewhere you want to measure.
+
+```js
+const { ref, width, height } = useResizeObserver({
+  defaultWidth: 100,
+  defaultHeight: 50
+});
+```
+
+You can even reuse the same hook instance to measure different elements:
+
+[CodeSandbox Demo](https://codesandbox.io/s/use-resize-observer-reusing-refs-buftd)
+
+## Throttle / Debounce
+
+You might want values less frequently than actually reported.
+
+While this hook does not come its own implementation of throttling / debouncing
+the reported values (Issue #19), you can use hook composition to achieve it:
+
+[CodeSandbox Demo](https://codesandbox.io/s/use-resize-observer-throttle-and-debounce-8uvsg)
 
 ## SSR, Default Size
 
@@ -54,17 +75,37 @@ const { ref, width, height } = useResizeObserver({
   defaultWidth: 100,
   defaultHeight: 50
 });
+```
+
+Here "width" and "height" will be 100 and 50 respectively, until the
+ResizeObserver kicks in and reports the actual size.
+
+## Without Default Measurements
 
-// width / height will be 100 and 50 respectively, until the ResizeObserver
-// kicks in and reports the actual size.
+If you only want real measurements (only values from the ResizeObserver without
+defaults), then you can use the following:
+
+```js
+const { ref, width, height } = useResizeObserver({
+  useDefaults: false
+});
 ```
 
-## Contributing
+Here "width" and "height" will be undefined until the ResizeObserver takes its
+first measurement.
+
+## Container/Element Query with CSS-in-JS
+
+It's possible to apply styles conditionally based on the width / height of an
+element using a CSS-in-JS solution, which is the basic idea behind
+container/element queries:
+
+[CodeSandbox Demo](https://codesandbox.io/s/use-resize-observer-container-query-with-css-in-js-iitxl)
 
 ## Related
 
-- [@zeecoder/react-resize-observer](https://github.com/ZeeCoder/react-resize-observer)
 - [@zeecoder/container-query](https://github.com/ZeeCoder/container-query)
+- [@zeecoder/react-resize-observer](https://github.com/ZeeCoder/react-resize-observer)
 
 ## License
 

tests/index.js

@@ -335,3 +335,31 @@ it("should keep the same response instance between renders if nothing changed",
 
   assertSameInstance();
 });
+
+it("should ignore invalid custom refs", async () => {
+  const Test = ({ resolveHandler }) => {
+    const ref = useRef(null);
+    const { width, height } = useResizeObserver({ ref: null }); // invalid custom ref
+
+    useEffect(() => {
+      resolveHandler({
+        assertSize: ({ width, height }) => {
+          expect(ref.current.textContent).toBe(`${width}x${height}`);
+        }
+      });
+    }, []);
+
+    return (
+      <div ref={ref}>
+        {width}x{height}
+      </div>
+    );
+  };
+
+  const { assertSize } = await render(Test);
+
+  // Since no refs were passed in with an element to be measured, the hook should
+  // stay on the defaults
+  await delay(50);
+  assertSize({ width: 1, height: 1 });
+});