react-custom-popup/README.md

# react-custom-popup

React Custom Popup is a React component for simply building custom popups and
modals.

## Installation

react-custom-popup requires **React 16.4.0 or later** and
**ReactDOM 16.4.0 or later**.

```
yarn add --dev react-custom-popup
```

This assumes that you’re using [yarn](https://yarnpkg.com/en/) package manager
with a module bundler like [Webpack](https://webpack.js.org/).

## Usage

The following snippet shows the example usage of react-custom-popup.

```
import React from 'react';
import Popup from 'react-custom-popup';

class App extends React.Component {
  constructor (props) {
    super(props);

    this.refButton = React.createRef();

    this.state = {
      popupVisible: false
    };
  }
  onShowPopupButtonClick (event) {
    event.stopPropagation();
    event.preventDefault();

    this.setState({popupVisible: true});
  }
  onHidePopup (event) {
    event.stopPropagation();
    event.preventDefault();

    this.setState({popupVisible: false});
  }
  render () {
    return (
      <React.Fragment>
        <button
          ref={this.refButton}
          onClick={this.onShowPopupButtonClick}
        >
          Show Popup
        </button>

        <Popup
          anchor={this.refButton}
          visible={this.state.popupVisible}
          onOverlayClick={this.onHidePopup}
        >
          <div>
            <h2>Hello, I'm a popup!</h2>
            <p>
              <button onClick={this.onHidePopup}>Close</button>
            </p>
          </div>
        </Popup>
      </React.Fragment>
    );
  }
}
```

### Styling

react-custom-popup includes CSS file that provides generic styles for the
popup. It's recommended to include it in your project's styles.

You can customize aspects of the popup's layout by passing a custom CSS class
using the *className* prop.

## API

### `Popup`

This is the custom popup component. It renders the popup in a React portal.

Example DOM structure rendered by the component:

```
<div className="bthlabs-react-custom-popup">
    <div className="bthlabs-rcp-overlay" />
    <div className="bthlabs-rcp-inner">
      <!-- Children will be rendered here -->
    </div>
</div>
```

The `div.bthlabs-rcp-inner` will be positioned according to the anchor. If
anchor isn't passed, the position will default to `left: 0px; top: 0px;`,
unless modified by `onLayout` prop.

**Props**

* `anchor` (*React ref*, optional) - a ref to an anchor element which will be
  used to position the inner layer.
* `className` (*string*, optional) - custom CSS class.
* `hideOverlay` (*boolean*, optional) - allows the wrapping component to hide
  the overlay. Defaults to `false`.
* `visible` (*boolean*, required) - specifies whether the popup is visible.
* `onLayout` (*function*, optional) - callback which allows the wrapping
  component to modify the inner layer's layout. Read below for more information.
* `onOverlayClick` (*function*, optional) - *onClick* handler for the
  `div.bthlabs-rcp-overlay` element.

**The onLayout callback**

The *onLayout* prop allows the wrapping component to modify the inner layer's
layout. If specified, it should accept an array of integers (`[<left>, <top>]`)
  and return an array of either two or more integers
  (`[<left>, <top>, <width>, <height>]`). The *width* and *height* fields can
    be omitted.

Example *onLayout* callback:

```
const onLayout = (layout) => {
  return [
    layout[0] + 10, // left
    layout[1] + 20, // top
    100,            // width
    200             // height
  ];
};
```

This function would shift the inner layer by 10px to the right and 20px to the
bottom and
set its size to 100px of width and 200px of height.

## Development

To bootstrap the development environment, clone the repo and run `npm install`
from the root directory.

The `package.json` file provides the following scripts:

* `build` - builds the library modules,
* `build:example` - builds the example project,
* `lint` - performs an eslint run over the source code,
* `test` - performs a single test run,
* `test:watch` - starts karma with watcher.

**NOTE**: Tests require *Chromium* to be installed and available in the path.
Consult
[karma-chrome-launcher](https://github.com/karma-runner/karma-chrome-launcher)
docs for more info.

## Contributing

If you think you found a bug or want to send a patch, feel free to contact
me through e-mail.

If you're sending a patch, make sure it passes eslint checks and is tested.

## Author

react-custom-popup is developed by [Tomek Wójcik](https://www.bthlabs.pl/).

## License

react-custom-popup is licensed under the MIT License.