npm package: @realmjs/react-popup
Description: [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
Author: Duong Nguyen
Latest version: 1.1.1

# react-popup

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

`react-popup` is a JavaScript library for managing and displaying popups in React applications. It provides a flexible and customizable solution for handling popups with various animations and options.

## Installation

```bash
npm install @realmjs/react-popup --save
```

## Usage

To use Popup Manager in your React application, follow these steps in the example below:

1. Create a Popup compopnent to be showned

```javascript
import React from 'react';

const MyPopup = ({ resolve, reject, /* props */ }) => {
  /* Component logic */
}

export default MyPopup
```


2. Set up the Popup Provider component in your application's root:

```javascript
import React from 'react';
import Popup, { usePopup } from '@realmjs/react-popup';
import MyPopup from './MyPopup.jsx';

function App() {

  const popupHandler = usePopup();

  return (
	<div>
	  <Popup.Provider
	    handler={popupHandler}
	    popups={[
		  'myPopup', MyPopup
		]}
	  />
	  <p>
	    <button onClick={showPopup}>Show Popup</button>
	  </p>
	</div>
  );

  function showPopup() {
    popupHandler.get('myPopup').show({ /* props */ })
      .then((result) => {
	    // Handle popup resolution
      })
      .catch((error) => {
	    // Handle popup rejection
      });
  }

}
```

## API Usage

### `Popup.Provider` Component

The `Popup.Provider` component is used to provide popups to the screen. It accepts the following props:

- `popups`: An array of popups, where each popup is an array containing the popup name and the corresponding popup component.
- `handler`: The popup handler created by the `usePopup` hook.

Example usage:

```javascript
import Popup from '@realmjs/react-popup';

const Example = () => {
  const popup = Popup.usePopup();
  return (
    <div>
      <Popup.Provider
        popups={[
          ['foo', (props) => <div>FOO</div>],
          ['bar', (props) => <div>BAR</div>],
        ]}
        handler={popup}
      />
      {/* Rest of your components */}
    </div>
  );
};
```

### `usePopup` Hook

The `usePopup(props)` hook creates a popup handler that can be used to manage the popups.

It receives a `props`` parameter as an argument. Its purpose is to prevent the occurrence of a stale closure issue.

usePopup hook returns the `popup` object with the following methods:

#### `popup.get(name)`

Retrieves a specific popup instance by its name.

Example usage:

```javascript
const myPopup = popup.get('popupName');
```

### Popup Instance

The `Popup` class represents a popup instance. It provides methods for configuring and displaying the popup.

#### `animate(animation, options)`
Configures the animation for the popup. The `animation` parameter specifies the animation type and its duration, and the `options` parameter provides additional animation options.

Example usage:

```javascript
myPopup.animate('flyIn 0.4s');
```

#### `overlay({ opacity })`
Configures the overlay style for the popup.

Example usage:

```javascript
myPopup.overlay({ opacity: '0.2' });
```

#### `show(props)`

Shows the popup with optional props.

Example usage:

```javascript
myPopup.show({ title: 'Hello', message: 'Popup content' });
```

#### `resolve(value)`

Resolves the popup with a value.

Example usage:

```javascript
myPopup.resolve('resolved value');
```

#### `reject(error)`

Rejects the popup with an error.

Example usage:

```javascript
myPopup.reject(new Error('Popup rejected'));
```

### `Popup` Component

The `Popup` component is used to display a popup. It receives props provided via `show(props)` along with the `{ resolve, reject }`, allowing the popup itself to resolve or reject the popup.

Example usage:

```javascript
const CustomPopup = ({ resolve, reject, title, message }) => {
  return (
    <div>
      <h2>{title}</title>
      <p>{message}</p>
      <p>
        <button onClick = {() => resolve()}>Resolve</button>
        <button onClick = {() => reject()}>Reject</button>
      </p>
    <div>
  )
}
```

## License

This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for more information.

Feel free to contribute to the project, report issues, or submit pull requests on [GitHub](https://github.com/realmjs/react-popup).