feat: usePopper Hook

.babelrc

@@ -4,33 +4,16 @@
     "@babel/flow",
     "@babel/react"
   ],
-  "plugins": [
-    "@babel/proposal-class-properties"
-  ],
   "env": {
     "esm": {
-      "plugins": [
-        "@babel/transform-runtime"
-      ],
-      "ignore": [
-        "**/*.test.js",
-        "**/__mocks__/**"
-      ]
+      "ignore": ["**/*.test.js", "**/__mocks__/**"]
     },
     "cjs": {
-      "plugins": [
-        "@babel/transform-runtime",
-        "@babel/transform-modules-commonjs"
-      ],
-      "ignore": [
-        "**/*.test.js",
-        "**/__mocks__/**"
-      ]
+      "plugins": [["@babel/transform-modules-commonjs", { "noInterop": true }]],
+      "ignore": ["**/*.test.js", "**/__mocks__/**"]
     },
     "test": {
-      "plugins": [
-        "@babel/transform-modules-commonjs"
-      ]
+      "plugins": ["@babel/transform-modules-commonjs"]
     }
   }
 }

.eslintrc.js

@@ -4,7 +4,8 @@ module.exports = {
   env: {
     browser: true,
   },
-  plugins: ['react'],
+  extends: ['plugin:react-hooks/recommended'],
+  plugins: ['react', 'react-hooks'],
   rules: {
     'no-unused-vars': 'error',
     'react/jsx-uses-vars': 'error',

.prettierrc.js

@@ -1,4 +1,5 @@
 module.exports = {
   singleQuote: true,
   trailingComma: 'es5',
+  proseWrap: 'always',
 };

README.md

@@ -1,4 +1,4 @@
-## React Popper
+# React Popper
 
 [![Build Status](https://travis-ci.org/popperjs/react-popper.svg?branch=master)](https://travis-ci.org/popperjs/react-popper)
 [![npm version](https://img.shields.io/npm/v/react-popper.svg)](https://www.npmjs.com/package/react-popper)
@@ -7,11 +7,12 @@
 [![code style: prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg)](https://github.com/prettier/prettier)
 [![Get support or discuss](https://img.shields.io/badge/chat-on_spectrum-6833F9.svg?logo=data%3Aimage%2Fsvg%2Bxml%3Bbase64%2CPHN2ZyBpZD0iTGl2ZWxsb18xIiBkYXRhLW5hbWU9IkxpdmVsbG8gMSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIiB2aWV3Qm94PSIwIDAgMTAgOCI%2BPGRlZnM%2BPHN0eWxlPi5jbHMtMXtmaWxsOiNmZmY7fTwvc3R5bGU%2BPC9kZWZzPjx0aXRsZT5zcGVjdHJ1bTwvdGl0bGU%2BPHBhdGggY2xhc3M9ImNscy0xIiBkPSJNNSwwQy40MiwwLDAsLjYzLDAsMy4zNGMwLDEuODQuMTksMi43MiwxLjc0LDMuMWgwVjcuNThhLjQ0LjQ0LDAsMCwwLC42OC4zNUw0LjM1LDYuNjlINWM0LjU4LDAsNS0uNjMsNS0zLjM1UzkuNTgsMCw1LDBaTTIuODMsNC4xOGEuNjMuNjMsMCwxLDEsLjY1LS42M0EuNjQuNjQsMCwwLDEsMi44Myw0LjE4Wk01LDQuMThhLjYzLjYzLDAsMSwxLC42NS0uNjNBLjY0LjY0LDAsMCwxLDUsNC4xOFptMi4xNywwYS42My42MywwLDEsMSwuNjUtLjYzQS42NC42NCwwLDAsMSw3LjE3LDQuMThaIi8%2BPC9zdmc%2B)](https://spectrum.chat/popper-js/react-popper)
 
-React wrapper around [Popper.js](https://popper.js.org).
+React wrapper around [Popper](https://popper.js.org).
 
-**important note:** popper.js is **not** a tooltip library, it's a _positioning engine_ to be used to build features such as (but not restricted to) tooltips.
+**important note:** Popper is **not** a tooltip library, it's a _positioning
+engine_ to be used to build features such as (but not restricted to) tooltips.
 
-## Install
+# Install
 
 Via package managers:
 
@@ -21,19 +22,61 @@ npm install react-popper @popperjs/core --save
 yarn add react-popper @popperjs/core
 ```
 
-**Note:** `@popperjs/core` must be installed in your project in order for `react-popper` to work.
+**Note:** `@popperjs/core` must be installed in your project in order for
+`react-popper` to work.
 
 Via `script` tag (UMD library exposed as `ReactPopper`):
 
 ```html
 <script src="https://unpkg.com/react-popper/dist/index.umd.js"></script>
 ```
 
-## Usage
+# Usage
 
-> Using `react-popper@0.x`? You can find its documentation [clicking here](https://github.com/souporserious/react-popper/tree/v0.x)
+> Using `react-popper@0.x`? You can find its documentation
+> [clicking here](https://github.com/souporserious/react-popper/tree/v0.x)
 
-Example:
+`react-popper` provides two different APIs to help consume it:
+
+## React Hooks
+
+The `usePopper` hook can be used to quickly initialize a Popper, it requires a
+basic understanding of how the
+[React Hooks](https://reactjs.org/docs/hooks-overview.html) work.
+
+```jsx
+import { useState } from 'react';
+import { usePopper } from 'react-popper';
+
+const Example = () => {
+  const [referenceElement, setReferenceElement] = useState(null);
+  const [popperElement, setPopperElement] = useState(null);
+  const [arrowElement, setArrowElement] = useState(null);
+  const { styles, attributes } = usePopper(referenceElement, popperElement, {
+    modifiers: [{ name: 'arrow', options: { element: arrowElement } }],
+  });
+
+  return (
+    <>
+      <button type="button" ref={setReferenceElement}>
+        Reference element
+      </button>
+
+      <div ref={setPopperElement} style={styles.popper} {...attributes.popper}>
+        Popper element
+        <div ref={setArrowElement} style={styles.arrow} />
+      </div>
+    </>
+  );
+};
+```
+
+## Render Props
+
+The `Manager`, `Reference` and `Popper` render-props components offer an
+alternative API to initialize a Popper instance, they require a basic
+understanding of how the
+[React Render Props](https://reactjs.org/docs/render-props.html) work.
 
 ```jsx
 import { Manager, Reference, Popper } from 'react-popper';
@@ -59,19 +102,60 @@ const Example = () => (
 );
 ```
 
-`react-popper` makes use of a React pattern called **"render prop"**, if you are not
-familiar with it, please read more [on the official React documentation](https://reactjs.org/docs/render-props.html).
+## API documentation
+
+### Hooks
+
+The `usePopper` hook provides an API almost identical to the ones of
+[`createPopper`](https://popper.js.org/docs/v2/constructors/#createpopper)
+constructor.
+
+Rather than returning a Popper instance, it will return an object containing the
+following properties:
+
+##### `styles`
+
+The `styles` property is an object, its properties are `popper`, and `arrow`.
+The two properties are a
+[`CSSStyleDeclaration` interface](https://developer.mozilla.org/en-US/docs/Web/API/CSSStyleDeclaration)
+describing the necessary CSS properties needed to properly position the two
+elements.
+
+You can directly assign the value of the two properties to the React `style`
+property of your components.
+
+```js
+<div style={styles.popper} />
+```
+
+##### `attributes`
 
-> Using React <=15 or Preact? The components created with them don't support to return
-> [fragments](https://reactjs.org/docs/fragments.html), this means that you will need to
-> wrap `<Reference />` and `<Popper />` into a single, common, `<div />` to make `react-popper` work.
+Similar to `styles`, the `attributes` object lists the `popper` and `arrow` HTML
+attributes, by default, only `popper` will hold some attributes (e.g.
+`data-popper-placement`), but more generically, any HTML attribute described by
+the Popper documentation will be available inside these properties.
 
-### API documentation
+The easiest way to consume their values is by destructuring them directly onto
+your React component.
 
-The `Manager` component is a simple wrapper that needs to surround all the other `react-popper` components in order
-to make them communicate with each others.
+```js
+<div {...attributes.popper} />
+```
+
+##### `update`, `forceUpdate`, and `state`
+
+These properties match the ones described in the
+[Popper docs](https://popper.js.org/docs/v2/constructors/#types), the only
+difference is that they can be `null` if Popper isn't yet been initialized or
+has been destroyed.
 
-The `Popper` component accepts the properties `children`, `placement`, `modifiers` and `strategy`.
+### Render Props
+
+The `Manager` component is a simple wrapper that needs to surround all the other
+`react-popper` components in order to make them communicate with each others.
+
+The `Popper` component accepts the properties `children`, `placement`,
+`modifiers` and `strategy`.
 
 ```jsx
 <Popper
@@ -102,19 +186,36 @@ children: ({|
 |}) => Node
 ```
 
-A function (render prop) that takes as argument an object containing the following properties:
-
-- **`ref`**: used to retrieve the [React refs](https://reactjs.org/docs/refs-and-the-dom.html) of the **popper** element.
-- **`style`**: contains the necessary CSS styles (React CSS properties) which are computed by Popper.js to correctly position the **popper** element.
-- **`placement`**: describes the placement of your popper after Popper.js has applied all the modifiers
-  that may have flipped or altered the originally provided `placement` property. You can use this to alter the
-  style of the popper and or of the arrow according to the definitive placement. For instance, you can use this
-  property to orient the arrow to the right direction.
-- **`isReferenceHidden`**: a boolean signifying the reference element is fully clipped and hidden from view.
-- **`hasPopperEscaped`**: a boolean signifying the popper escapes the reference element's boundary (and so it appears detached).
-- **`update`**: a function you can ask Popper to recompute your tooltip's position . It will directly call the [Popper#update](https://popper.js.org/docs/v2/lifecycle/#manual-update) method.
-- **`arrowProps`**: an object, containing `style` and `ref` properties that are identical to the
-  ones provided as the first and second arguments of `children`, but relative to the **arrow** element. The `style` property contains `left` and `top` offset values, which are used to center the arrow within the popper. These values can be merged with further custom styling and positioning. See [the demo](https://github.com/FezVrasta/react-popper/blob/8994933c430e48ab62e71495be71e4f440b48a5a/demo/styles.js#L100) for an example.
+A function (render prop) that takes as argument an object containing the
+following properties:
+
+- **`ref`**: used to retrieve the
+  [React refs](https://reactjs.org/docs/refs-and-the-dom.html) of the **popper**
+  element.
+- **`style`**: contains the necessary CSS styles (React CSS properties) which
+  are computed by Popper.js to correctly position the **popper** element.
+- **`placement`**: describes the placement of your popper after Popper.js has
+  applied all the modifiers that may have flipped or altered the originally
+  provided `placement` property. You can use this to alter the style of the
+  popper and or of the arrow according to the definitive placement. For
+  instance, you can use this property to orient the arrow to the right
+  direction.
+- **`isReferenceHidden`**: a boolean signifying the reference element is fully
+  clipped and hidden from view.
+- **`hasPopperEscaped`**: a boolean signifying the popper escapes the reference
+  element's boundary (and so it appears detached).
+- **`update`**: a function you can ask Popper to recompute your tooltip's
+  position . It will directly call the
+  [Popper#update](https://popper.js.org/docs/v2/lifecycle/#manual-update)
+  method.
+- **`arrowProps`**: an object, containing `style` and `ref` properties that are
+  identical to the ones provided as the first and second arguments of
+  `children`, but relative to the **arrow** element. The `style` property
+  contains `left` and `top` offset values, which are used to center the arrow
+  within the popper. These values can be merged with further custom styling and
+  positioning. See
+  [the demo](https://github.com/FezVrasta/react-popper/blob/8994933c430e48ab62e71495be71e4f440b48a5a/demo/styles.js#L100)
+  for an example.
 
 ##### `innerRef`
 
@@ -130,33 +231,41 @@ Function that can be used to obtain popper reference
 placement?: PopperJS$Placement;
 ```
 
-One of the accepted placement values listed in the [Popper.js documentation](https://popper.js.org/popper-documentation.html#Popper.placements).  
+One of the accepted placement values listed in the
+[Popper.js documentation](https://popper.js.org/popper-documentation.html#Popper.placements).  
 Your popper is going to be placed according to the value of this property.  
 Defaults to `bottom`.
 
 ##### `strategy`
 
-Describes the positioning strategy to use. By default, it is `absolute`, which in the simplest cases does not require repositioning of the popper. If your reference element is in a `fixed` container, use the `fixed` strategy. [Read More](https://popper.js.org/docs/v2/constructors/#strategy)
+Describes the positioning strategy to use. By default, it is `absolute`, which
+in the simplest cases does not require repositioning of the popper. If your
+reference element is in a `fixed` container, use the `fixed` strategy.
+[Read More](https://popper.js.org/docs/v2/constructors/#strategy)
 
 ##### `modifiers`
 
 ```js
 modifiers?: PopperJS$Modifiers;
 ```
 
-An object containing custom settings for the [Popper.js modifiers](https://popper.js.org/docs/v2/modifiers/).  
-You can use this property to override their settings or to inject your custom ones.
+An object containing custom settings for the
+[Popper.js modifiers](https://popper.js.org/docs/v2/modifiers/).  
+You can use this property to override their settings or to inject your custom
+ones.
 
 ## Usage with `ReactDOM.createPortal`
 
-Popper.js is smart enough to work even if the **popper** and **reference** elements aren't
-in the same DOM context.  
-This means that you can use [`ReactDOM.createPortal`](https://reactjs.org/docs/portals.html)
-(or any pre React 16 alternative) to move the popper component somewhere else in the DOM.
+Popper.js is smart enough to work even if the **popper** and **reference**
+elements aren't in the same DOM context.  
+This means that you can use
+[`ReactDOM.createPortal`](https://reactjs.org/docs/portals.html) (or any pre
+React 16 alternative) to move the popper component somewhere else in the DOM.
 
-This can be useful if you want to position a tooltip inside an `overflow: hidden` container
-that you want to make overflow. Please note that you can also try the `positionFixed` strategy
-to obtain a similar effect with less hassle.
+This can be useful if you want to position a tooltip inside an
+`overflow: hidden` container that you want to make overflow. Please note that
+you can also try the `positionFixed` strategy to obtain a similar effect with
+less hassle.
 
 ```jsx
 import { Manager, Reference, Popper } from 'react-popper';
@@ -186,11 +295,17 @@ const Example = () => (
 
 ## Usage without a reference `HTMLElement`
 
-Whenever you need to position a popper based on some arbitrary coordinates, you can provide `Popper` with a `referenceElement` property that is going to be used in place of the `referenceProps.getRef` React ref.
+Whenever you need to position a popper based on some arbitrary coordinates, you
+can provide `Popper` with a `referenceElement` property that is going to be used
+in place of the `referenceProps.getRef` React ref.
 
-The `referenceElement` property must be an object with an interface compatible with an `HTMLElement` as described in the [Popper.js virtualElement documentation](https://popper.js.org/docs/v2/virtual-elements/), this implies that you may also provide a real HTMLElement if needed.
+The `referenceElement` property must be an object with an interface compatible
+with an `HTMLElement` as described in the
+[Popper.js virtualElement documentation](https://popper.js.org/docs/v2/virtual-elements/),
+this implies that you may also provide a real HTMLElement if needed.
 
-If `referenceElement` is defined, it will take precedence over any `referenceProps.ref` provided refs.
+If `referenceElement` is defined, it will take precedence over any
+`referenceProps.ref` provided refs.
 
 ```jsx
 import { Popper } from 'react-popper';
@@ -231,8 +346,8 @@ const Example = () => (
 
 This library is built with Flow but it supports TypeScript as well.
 
-You can find the exported Flow types in `src/index.js`, and the
-TypeScript definitions in `typings/react-popper.d.ts`.
+You can find the exported Flow types in `src/index.js`, and the TypeScript
+definitions in `typings/react-popper.d.ts`.
 
 ## Running Locally
 

demo/index.js

@@ -117,7 +117,7 @@ const Demo = () => {
         <Manager>
           <Reference>
             {({ ref }) => (
-              <ReferenceBox innerRef={ref}>
+              <ReferenceBox ref={ref}>
                 <a
                   href="https://github.com/FezVrasta/react-popper"
                   target="_blank"
@@ -130,10 +130,10 @@ const Demo = () => {
           <PoppersContainer>
             <Popper placement={activePlacement} modifiers={mainModifiers}>
               {({ ref, style, placement, arrowProps }) => (
-                <TransitionedPopperBox innerRef={ref} style={style}>
+                <TransitionedPopperBox ref={ref} style={style}>
                   {placement}
                   <Arrow
-                    innerRef={arrowProps.ref}
+                    ref={arrowProps.ref}
                     data-placement={placement}
                     style={arrowProps.style}
                   />
@@ -146,7 +146,7 @@ const Demo = () => {
                 <Popper placement={p} key={p} modifiers={dotModifiers}>
                   {({ ref, style }) => (
                     <PopperDot
-                      innerRef={ref}
+                      ref={ref}
                       style={style}
                       onClick={() => setActivePlacement(p)}
                       title={p}
@@ -163,7 +163,7 @@ const Demo = () => {
             {({ ref }) => (
               <ClickableReferenceBox
                 tabIndex={0}
-                innerRef={ref}
+                ref={ref}
                 onClick={() => togglePopper2(!isPopper2Open)}
               >
                 Click to toggle