update docs to use resize-observer-polyfill as a ponyfill

Author: osdiab

README.md

@@ -29,52 +29,69 @@ function MyComponent() {
 
 ## ResizeObserver
 
-[Resize Observer](https://developers.google.com/web/updates/2016/10/resizeobserver)
-is the API is used to determine if an element is resized. Browser support is pretty good in Chrome, but is still missing support in other major browsers.
+If it is present, this library uses the recent [`ResizeObserver` browser
+API](https://developers.google.com/web/updates/2016/10/resizeobserver) to
+determine if an element's content size has changed.
+
+If a browser does not have the `ResizeObserver` API present, then this library
+falls back to listening on window size changes, which is less efficient and does
+not listen for changes to the component's size due to other factors like content
+changes. If it is not present, you can use pass a `ResizeObserver`
+implementation into the `useComponentSize()` hook (see below).
+
+Browser support is pretty good in Chrome, but is still missing support in other
+major browsers.
 
 > [Can i use ResizeObserver?](https://caniuse.com/#feat=resizeobserver)
 
 ### Polyfill
 
-You can import the
-[polyfill](https://github.com/que-etc/resize-observer-polyfill) directly from here
+You can import [a ResizeObserver
+ponyfill](https://github.com/que-etc/resize-observer-polyfill) with this NPM
+library:
 
 ```sh
 yarn add resize-observer-polyfill
 ```
 
-Then import it in your app:
+Then use it with the `useComponentSize()` hook:
 
 ```js
-import 'resize-observer-polyfill'
+import ResizeObserver from 'resize-observer-polyfill'
+// ...
+useComponentSize(ref, { ResizeObserver });
 ```
 
 If you are using Webpack (or similar) you could use [dynamic
-imports](https://webpack.js.org/api/module-methods/#import-), to load the
+imports](https://webpack.js.org/api/module-methods/#import), to load the
 Polyfill only if needed. A basic implementation could look something like this:
 
 ```js
-loadPolyfills()
-  .then(() => /* Render React application now that your Polyfills are ready */)
-
-/**
-* Do feature detection, to figure out which polyfills needs to be imported.
-**/
-function loadPolyfills() {
-  const polyfills = []
-
-  if (!supportsResizeObserver()) {
-    polyfills.push(import('resize-observer-polyfill'))
-  }
-
-  return Promise.all(polyfills)
-}
-
-function supportsResizeObserver() {
-  return (
+function getResizeObserver() {
+  if (
     'ResizeObserver' in global &&
     'ResizeObserverEntry' in global &&
     'contentRect' in ResizeObserverEntry.prototype
-  )
+  ) {
+    return Promise.resolve(ResizeObserver);
+  }
+  return import('resize-observer-polyfill');
 }
 ```
+
+And in your component:
+```js
+const [ResizeObserverApi, setResizeObserverApi] = setState();
+useEffect(() => {
+  let cancelled = false;
+  getResizeObserver().then(observer => {
+    if (!cancelled) {
+      setResizeObserverApi(observer);
+    }
+  });
+  return () => {
+    cancelled = true;
+  }
+}, []);
+useComponentSize(ref, { ResizeObserver: ResizeObserverApi });
+```