docs: update docs for v2 (#263)

README.md

@@ -7,3 +7,25 @@
 [![code style: prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg)](https://github.com/prettier/prettier)
 
 Animated toast message component for React Native.
+
+## Features
+
+- 🚀 Imperative API
+- 📦 Very lightweight (~40 kB)
+- ⌨️ Keyboard-aware
+- 🎨 Customizable layouts
+- 🔧 Flexible config
+
+## Documentation
+
+- [Quick start](./docs/quick-start.md)
+- [API](./docs/api.md)
+- [Create custom layouts](./docs/custom-layouts.md)
+- FAQ
+  - [How to show the Toast inside a Modal?](./docs/modal-usage.md)
+  - [How to render the Toast when using a Navigation library?](./docs/navigation-usage.md)
+  - [How to mock the library for testing with jest?](./docs/jest-testing.md)
+
+## License
+
+MIT

docs/api.md

@@ -0,0 +1,86 @@
+# API
+
+The `Toast` API consists of:
+
+1. [methods](#methods) that can be called directly on the `Toast` object (in an _imperative_ way)
+1. [props](#props) that can be passed to the `Toast` component instance; they act as defaults for all Toasts that are shown
+
+## methods
+
+### `show(options = {})`
+
+To show a Toast, call the `show()` method andd pass the `options` that suit your needs. Everything is optional, unless specified otherwise:
+
+```js
+import Toast from 'react-native-toast-message'
+
+Toast.show({
+  type: 'info',
+  text1: 'This is an info message'
+});
+```
+
+The complete set of **options** is described below:
+
+| option           | description                                                                                                                                                                                     | type              | default value |
+| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- | ------------- |
+| `type`           | Toast type. Default available values: `success`, `error`, `info`. [Learn how to extend / overwrite Toast types](./custom-layouts.md)                                                            | `string`          | `success`     |
+| `text1`          | First line of text                                                                                                                                                                              | `string`          |               |
+| `text2`          | Second line of text                                                                                                                                                                             | `string`          |               |
+| `position`       | Toast position                                                                                                                                                                                  | `top` or `bottom` | `top`         |
+| `visibilityTime` | Number of milliseconds after which Toast automatically hides. Has effect only in conjunction with `autoHide` prop set to `true`                                                                 | `number`          | `4000`        |
+| `autoHide`       | When `true`, the visible Toast automatically hides after a certain number of milliseconds, specified by the `visibilityTime` prop                                                               | `boolean`         | `true`        |
+| `topOffset`      | Offset from the top of the screen (in px). Has effect only when `position` is `top`                                                                                                             | `number`          | `40`          |
+| `bottomOffset`   | Offset from the bottom of the screen (in px). Has effect only when `position` is `bottom`                                                                                                       | `number`          | `40`          |
+| `keyboardOffset` | Offset from the Keyboard (in px). Has effect only when `position` is `bottom` and Keyboard is visible (iOS only)                                                                                | `number`          | `10`          |
+| `onShow`         | Called when the Toast is shown                                                                                                                                                                  | `() => void`      |               |
+| `onHide`         | Called when the Toast hides                                                                                                                                                                     | `() => void`      |               |
+| `onPress`        | Called on Toast press                                                                                                                                                                           | `() => void`      |               |
+| `props`          | Any custom props passed to the specified Toast type. Has effect only when there is a custom Toast type (configured via the `config` prop on the Toast instance) that uses the `props` parameter | `any`             |               |
+
+### `hide()`
+
+To hide the current visible Toast, call the `hide()` method:
+
+```js
+Toast.hide();
+```
+
+If an `onHide` callback was set (via `show()`, or as a default `prop` on the Toast component instance), it will be called now.
+
+## props
+
+The following set of `props` can be passed to the `Toast` component instance to specify certain **defaults for all Toasts that are shown**:
+
+| prop             | description                                                                                                                       | type                                   | default value |
+| ---------------- | --------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- | ------------- |
+| `config`         | Layout configuration for custom Toast types                                                                                       | [`ToastConfig`](../src/types/index.ts) |               |
+| `type`           | Default Toast type                                                                                                                | `string`                               | `success`     |
+| `position`       | Default Toast position                                                                                                            | `top` or `bottom`                      | `top`         |
+| `visibilityTime` | Number of milliseconds after which Toast automatically hides. Has effect only in conjunction with `autoHide` prop set to `true`   | `number`                               | `4000`        |
+| `autoHide`       | When `true`, the visible Toast automatically hides after a certain number of milliseconds, specified by the `visibilityTime` prop | `boolean`                              | `true`        |
+| `topOffset`      | Offset from the top of the screen (in px). Has effect only when `position` is `top`                                               | `number`                               | `40`          |
+| `bottomOffset`   | Offset from the bottom of the screen (in px). Has effect only when `position` is `bottom`                                         | `number`                               | `40`          |
+| `keyboardOffset` | Offset from the Keyboard (in px). Has effect only when `position` is `bottom` and Keyboard is visible (iOS only)                  | `number`                               | `10`          |
+| `onShow`         | Called when any Toast is shown                                                                                                    | `() => void`                           |               |
+| `onHide`         | Called when any Toast hides                                                                                                       | `() => void`                           |               |
+| `onPress`        | Called on any Toast press                                                                                                         | `() => void`                           |               |
+
+For example, to make sure all your Toasts are displayed at the bottom of the screen:
+
+```js
+// App.jsx
+import Toast from 'react-native-toast-message';
+
+export function App(props) {
+  return (
+    <>
+      {/* ... */}
+      <Toast
+        position='bottom'
+        bottomOffset={20}
+      />
+    </>
+  );
+}
+```

docs/custom-layouts.md

@@ -0,0 +1,88 @@
+# Create custom layouts
+
+If you want to add custom Toast types - or overwrite the existing ones - you can add a [`config` prop](./api.md#props) when rendering the `Toast` component in your app's entry point.
+
+When creating the `config`, you can either:
+
+1. Use any of the default `BaseToast`, `SuccessToast`, `ErrorToast` or `InfoToast` components and adjust their layout
+1. Create Toast layouts from scratch
+
+```js
+// App.jsx
+import Toast, { BaseToast, ErrorToast } from 'react-native-toast-message';
+
+/*
+  1. Create the config
+*/
+const toastConfig = {
+  /*
+    Overwrite 'success' type,
+    by modifying the existing `BaseToast` component
+  */
+  success: (props) => (
+    <BaseToast
+      {...props}
+      style={{ borderLeftColor: 'pink' }}
+      contentContainerStyle={{ paddingHorizontal: 15 }}
+      text1Style={{
+        fontSize: 15,
+        fontWeight: '400'
+      }}
+    />
+  ),
+  /*
+    Overwrite 'error' type,
+    by modifying the existing `ErrorToast` component
+  */
+  error: (props) => (
+    <ErrorToast
+      {...props}
+      text1Style={{
+        fontSize: 17
+      }}
+      text2Style={{
+        fontSize: 15
+      }}
+    />
+  ),
+  /*
+    Or create a completely new type - `tomatoToast`,
+    building the layout from scratch.
+
+    I can consume any custom `props` I want.
+    They will be passed when calling the `show` method (see below)
+  */
+  tomatoToast: ({ text1, props }) => (
+    <View style={{ height: 60, width: '100%', backgroundColor: 'tomato' }}>
+      <Text>{text1}</Text>
+      <Text>{props.uuid}</Text>
+    </View>
+  )
+};
+
+/*
+  2. Pass the config as prop to the Toast component instance
+*/
+export function App(props) {
+  return (
+    <>
+      {...}
+      <Toast config={toastConfig} />
+    </>
+  );
+}
+```
+
+Then just use the library as before.
+
+For example, if I want to show the new `tomatoToast` type I just created above:
+
+```js
+Toast.show({
+  type: 'tomatoToast',
+  // And I can pass any custom props I want
+  props: { uuid: 'bba1a7d0-6ab2-4a0a-a76e-ebbe05ae6d70' }
+});
+```
+
+All the available props on `BaseToast`, `SuccessToast`, `ErrorToast` or `InfoToast` components can be found [here](../src/types/index.ts).

docs/jest-testing.md

@@ -0,0 +1,8 @@
+# How to mock the library for testing with [jest](https://jestjs.io)?
+
+```js
+jest.mock('react-native-toast-message', () => ({
+  show: jest.fn(),
+  hide: jest.fn()
+}));
+```

docs/modal-usage.md

@@ -0,0 +1,40 @@
+# How to show the Toast inside a Modal?
+
+To show the Toast inside a Modal, simply render the Toast instance inside the Modal, **as well as** in your app's entry point.
+
+That's it.
+
+Now when the Modal is visible, the Toast reference from the Modal will be used and the Toast will be visible on top of the Modal.
+
+```js
+// Modal.jsx
+import Toast from 'react-native-toast-message'
+import { Modal } from 'react-native'
+
+function Modal(props) {
+  const [isModalVisible, setIsModalVisible] = React.useState(false);
+
+  return (
+    <Modal visible={isModalVisible}>
+        {/* Modal content */}
+        {/* Toast component instance rendered inside Modal */}
+        <Toast />
+    </Modal>
+  )
+}
+```
+
+```js
+// App.jsx
+import Toast from 'react-native-toast-message'
+
+export function App(props) {
+  return (
+    <>
+      {/* ... */}
+      {/* Toast component instance rendered in the app's entry point */}
+      <Toast />
+    </>
+  );
+}
+```

docs/navigation-usage.md

@@ -0,0 +1,23 @@
+# How to render the Toast when using a Navigation library?
+
+1. Usage with [react-navigation](https://reactnavigation.org)
+
+## Usage with [react-navigation](https://reactnavigation.org)
+
+To have the Toast visible on top of the navigation `View` hierarchy, render it as the **last child** in the `View` hierarchy (along the root Navigation component):
+
+```js
+import Toast from 'react-native-toast-message'
+import { NavigationContainer } from '@react-navigation/native';
+
+export function App() {
+  return (
+    <>
+      <NavigationContainer>
+        {...}
+      </NavigationContainer>
+      <Toast />
+    </>
+  );
+}
+```

docs/quick-start.md

@@ -0,0 +1,59 @@
+# Quick start
+
+## Install
+
+```sh
+yarn add react-native-toast-message
+# or
+npm install --save react-native-toast-message
+```
+
+## Usage
+
+Render the `Toast` component in your app's entry file, as the **last child** in the `View` hierarchy (along with any other components that might be rendered there):
+
+```js
+// App.jsx
+import Toast from 'react-native-toast-message';
+
+export function App(props) {
+  return (
+    <>
+      {/* ... */}
+      <Toast />
+    </>
+  );
+}
+```
+
+Then use it anywhere in your app (even outside React components), by calling [any `Toast` method](./api.md#methods) directly:
+
+```js
+// Foo.jsx
+import Toast from 'react-native-toast-message';
+import { Button } from 'react-native'
+
+export function Foo(props) {
+  const showToast = () => {
+    Toast.show({
+      type: 'success',
+      text1: 'Hello',
+      text2: 'This is some something 👋'
+    });
+  }
+
+  return (
+    <Button
+      title='Show toast'
+      onPress={showToast}
+    />
+  )
+}
+```
+
+## What's next
+
+Explore the following topics:
+
+- [Using the Toast API](./api.md)
+- [Create custom layouts](./custom-layouts.md)

index.ts

@@ -1,2 +1,6 @@
 export { Toast as default } from './src/Toast';
+export { BaseToast } from './src/components/BaseToast';
+export { SuccessToast } from './src/components/SuccessToast';
+export { ErrorToast } from './src/components/ErrorToast';
+export { InfoToast } from './src/components/InfoToast';
 export * from './src/types';

src/components/ErrorToast.tsx

@@ -4,5 +4,5 @@ import { BaseToastProps } from '../types';
 import { BaseToast } from './BaseToast';
 
 export function ErrorToast(props: BaseToastProps) {
-  return <BaseToast {...props} style={{ borderLeftColor: '#FE6301' }} />;
+  return <BaseToast style={{ borderLeftColor: '#FE6301' }} {...props} />;
 }

src/components/InfoToast.tsx

@@ -4,5 +4,5 @@ import { BaseToastProps } from '../types';
 import { BaseToast } from './BaseToast';
 
 export function InfoToast(props: BaseToastProps) {
-  return <BaseToast {...props} style={{ borderLeftColor: '#87CEFA' }} />;
+  return <BaseToast style={{ borderLeftColor: '#87CEFA' }} {...props} />;
 }

src/components/SuccessToast.tsx

@@ -4,5 +4,5 @@ import { BaseToastProps } from '../types';
 import { BaseToast } from './BaseToast';
 
 export function SuccessToast(props: BaseToastProps) {
-  return <BaseToast {...props} style={{ borderLeftColor: '#69C779' }} />;
+  return <BaseToast style={{ borderLeftColor: '#69C779' }} {...props} />;
 }