docs: update docs to reflect current API

gunnartorfis · Sep 7, 2024 · 98e234c · 98e234c
1 parent a5e5438
commit 98e234c
Show file tree

Hide file tree

Showing 18 changed files with 392 additions and 272 deletions.
diff --git a/README.md b/README.md
@@ -41,6 +41,15 @@ https://snack.expo.dev/@gunnartorfis/react-native-reanimated-toasts
 npm install react-native-reanimated-toasts
 ```
 
+#### Requirements
+
+To use this package, **you also need to install its peer dependencies**. Check out their documentation for more information:
+
+- [React Native Reanimated](https://docs.swmansion.com/react-native-reanimated/docs/fundamentals/getting-started)
+- [React Native Gesture Handler](https://docs.swmansion.com/react-native-gesture-handler/docs/)
+- [React Native Safe Area Context](https://docs.expo.dev/versions/latest/sdk/safe-area-context/)
+- [React Native SVG](https://github.com/software-mansion/react-native-svg)
+
 ## Usage
 
 ### In your App.tsx/entry point

diff --git a/docs/docs/Toaster.md b/docs/docs/Toaster.md
@@ -26,31 +26,43 @@ export default function App() {
 }
 ```
 
-## Props
-
-| Prop                     | Type                  | Default      | Description                                                 |
-| ------------------------ | --------------------- | ------------ | ----------------------------------------------------------- |
-| `duration`               | `number`              | `3000` (ms)  | Duration each toast is visible before auto-dismissal.       |
-| `position`               | `ToastPosition`       | `top-center` | The position of the toasts (`top-center`, `bottom-center`). |
-| `visibleToasts`          | `number`              | `3`          | Maximum number of toasts to show at once.                   |
-| `swipToDismissDirection` | `ToastSwipeDirection` | `up`         | Swipe direction to dismiss (`left`, `up`).                  |
-
-### Style related props
-
-| Prop                      | Type        | Default     | Description                                                    |
-| ------------------------- | ----------- | ----------- | -------------------------------------------------------------- |
-| `rootStyle`               | `ViewStyle` | `undefined` | Style for the root container.                                  |
-| `rootClassName`           | `string`    | `undefined` | `NativeWind` class names for root container styling.           |
-| `toastContainerStyle`     | `ViewStyle` | `undefined` | Style for the toast container (wrapper for individual toasts). |
-| `toastContainerClassName` | `string`    | `undefined` | `NativeWind` class names for the toast container.              |
-| `toastContentStyle`       | `ViewStyle` | `undefined` | Style for individual toast content.                            |
-| `toastContentClassName`   | `string`    | `undefined` | `NativeWind` class names for individual toast content.         |
-| `actionClassName`         | `string`    | `undefined` | `NativeWind` class names for the toast action button.          |
-| `actionLabelClassName`    | `string`    | `undefined` | `NativeWind` class names for the toast action label.           |
-| `descriptionClassName`    | `string`    | `undefined` | `NativeWind` class names for the toast description.            |
-| `titleClassName`          | `string`    | `undefined` | `NativeWind` class names for the toast title.                  |
-| `actionStyle`             | `ViewStyle` | `undefined` | Style for the toast action button.                             |
-| `actionLabelStyle`        | `TextStyle` | `undefined` | Style for the toast action label.                              |
-| `descriptionStyle`        | `TextStyle` | `undefined` | Style for the toast description.                               |
-| `titleStyle`              | `TextStyle` | `undefined` | Style for the toast title.                                     |
-| `closeIconColor`          | `string`    | `undefined` | Color for the toast's close icon.                              |
+## Customization
+
+The Toaster component can provide default styles for all toasts, but individual toasts can also be customized. The Toaster component accepts a number of props to customize the appearance and behavior of the toasts.
+
+### Position
+
+The `position` prop determines where the toasts are displayed on the screen.
+
+```tsx
+// Available positions:
+// top-center, bottom-center
+<Toaster position="bottom-center" />
+```
+
+### Default styles for toasts
+
+You can provide default styles for all toasts by passing `style` and `className` props to the Toaster component. All customization passed to the toast() will be concatenated with these default styles.
+
+```tsx
+<Toaster
+  toastOptions={{
+    style: { backgroundColor: 'red' },
+    className: 'bg-red-500',
+  }}
+/>
+```
+
+## API Reference
+
+| Property                 |                                            Description                                             |      Default |
+| :----------------------- | :------------------------------------------------------------------------------------------------: | -----------: |
+| theme                    |                                          `light`, `dark`                                           |      `light` |
+| visibleToasts            |                                  Maximum number of visible toasts                                  |          `3` |
+| position                 |                              Place where the toasts will be rendered                               | `top-center` |
+| closeButton              |                                 Adds a close button to all toasts                                  |      `false` |
+| invert                   |                             Dark toasts in light mode and vice versa.                              |      `false` |
+| toastOptions             | These will act as default options for all toasts. See [toast()](/toast) for all available options. |         `{}` |
+| gap                      |                                  Gap between toasts when expanded                                  |         `16` |
+| icons                    |                                     Changes the default icons                                      |          `-` |
+| `swipToDismissDirection` |                             Swipe direction to dismiss (`left`, `up`).                             |         `up` |
diff --git a/docs/docs/index.md b/docs/docs/index.md
@@ -4,24 +4,28 @@ sidebar_position: 1
 
 # Introduction
 
-**An incredibly fast and flexible way of building calendars in React Native.**
+**react-native-reanimated-toasts** is a highly customizable and performant toast library for React Native, built with Reanimated 3. It provides a simple API to display toast notifications with various options and configurations.
 
 ![Preview](/img/preview.png)
 
 ## Features
 
-- Multiple variants, including `success`, `error`, `warning`
-- Promise option with built in loading state
+- API fully matches [Sonner's](https://sonner.emilkowal.ski/)
+- Multiple variants, including `success`, `error`, `warning`, `custom`, `promise`
+- Promise variant with built-in loading state
+- Custom JSX with the custom variant
 - Top or bottom positions
 - Title and description
-- Action button with callback
+- Action button with a callback
 - Custom icons
-- Dismissable with swipe, configurable left or up
-- Highly performant using Reanimated 3
-- Dark mode support
+- Optionally dismissable with swipe, configurable left or up
+- Dismissable with toast.dismiss(), one or all toasts
+- Highly performant using Reanimated 3, 60 FPS
+- Dark mode built-in
 - Works with Expo
-- NativeWind support
-- Customizable
+- NativeWind supported
+- Customizable, styles & className props
+- Works outside of React components
 
 ## Installation
 
@@ -36,6 +40,7 @@ To use this package, **you also need to install its peer dependencies**. Check o
 - [React Native Reanimated](https://docs.swmansion.com/react-native-reanimated/docs/fundamentals/getting-started)
 - [React Native Gesture Handler](https://docs.swmansion.com/react-native-gesture-handler/docs/)
 - [React Native Safe Area Context](https://docs.expo.dev/versions/latest/sdk/safe-area-context/)
+- [React Native SVG](https://github.com/software-mansion/react-native-svg)
 
 ## Getting started
 
@@ -71,4 +76,4 @@ function SomeComponent() {
 
 ## Examples
 
-An example can be found in the [`example`](https://github.com/gunnartorfis/react-native-reanimated-toasts/tree/main/example) workspace.
+An example can be found in the [`example`](https://github.com/gunnartorfis/react-native-reanimated-toasts/tree/main/example) folder.
diff --git a/docs/docs/sonner.md b/docs/docs/sonner.md
@@ -0,0 +1,51 @@
+# Props Comparison with Sonner
+
+## toast():
+
+| Property           | Reanimated Toasts | Sonner |
+| :----------------- | ----------------- | ------ |
+| description        | ✅                | ✅     |
+| closeButton        | ✅                | ✅     |
+| invert             | ✅                | ✅     |
+| important          | ✅                | ✅     |
+| duration           | ✅                | ✅     |
+| position           | ✅                | ✅     |
+| dismissible        | ✅                | ✅     |
+| icon               | ✅                | ✅     |
+| action             | ✅                | ✅     |
+| id                 | ✅                | ✅     |
+| onDismiss          | ✅                | ✅     |
+| onAutoClose        | ✅                | ✅     |
+| unstyled           | ✅                | ✅     |
+| actionButtonStyles | ✅                | ✅     |
+| cancelButtonStyles | ✅                | ✅     |
+| cancel             | ❌                | ✅     |
+| action as JSX      | ❌                | ✅     |
+| loading            | ❌                | ✅     |
+| Headless           | ❌                | ✅     |
+| Dynamic position   | ❌                | ✅     |
+| important          | ❌                | ✅     |
+
+## Toaster:
+
+| Property                 | Reanimated Toasts | Sonner |
+| :----------------------- | ----------------- | ------ |
+| theme                    | ✅                | ✅     |
+| visibleToasts            | ✅                | ✅     |
+| position                 | ✅                | ✅     |
+| closeButton              | ✅                | ✅     |
+| invert                   | ✅                | ✅     |
+| toastOptions             | ✅                | ✅     |
+| gap                      | ✅                | ✅     |
+| icons                    | ✅                | ✅     |
+| `swipToDismissDirection` | ✅                | ❌     |
+| dir                      | ❌                | ✅     |
+| richColors               | ❌                | ✅     |
+| expand                   | 🕸️                | ✅     |
+| offset                   | ❌                | ✅     |
+| hotkey                   | 🕸️                | ✅     |
+| loadingIcon              | ❌                | ✅     |
+| pauseWhenPageIsHidden    | ❌                | ✅     |
+| cn                       | ❌                | ✅     |
+
+**🕸️: Not applicable for native apps.**
diff --git a/docs/docs/toast.md b/docs/docs/toast.md
@@ -4,6 +4,8 @@ sidebar_position: 2
 
 # toast()
 
+toast() is used to display a toast message. It can be used outside of React.
+
 ## Basic toast
 
 To display a simple toast message, use the toast() function. You can pass a title and optional settings.
@@ -20,8 +22,11 @@ Alternatively, you can pass an object as the second argument with additional opt
 import { toast } from 'react-native-reanimated-toasts';
 
 toast.success('Operation successful!', {
+  className: 'bg-green-500',
+  style: { backgroundColor: 'blue' }
   description: 'Everything worked as expected.',
-  duration: 3000, // duration in milliseconds
+  duration: 6000,
+  icon: <SomeIcon />
 });
 ```
 
@@ -45,7 +50,7 @@ toast.error('My error toast');
 
 ### Action
 
-Renders a primary button, clicking it will close the toast and run the callback passed via `onClick`. You can prevent the toast from closing by calling `event.preventDefault()` in the `onClick` callback.
+Renders an action button with a callback function. The action object should contain a label and an `onClick` function. The action and its label can be customized with the `actionButtonStyles` and `actionButtonTextStyles` params, respectively.
 
 ```jsx
 toast('My action toast', {
@@ -92,6 +97,8 @@ toast.custom(
 );
 ```
 
+## Other
+
 ### Updating existing toasts
 
 You can update an existing toast by using the toast function, passing the toast ID in the options object:
@@ -104,6 +111,27 @@ toast.success('Updated!', {
 });
 ```
 
+### Callbacks
+
+There are two callbacks, `onAutoClose` and `onDismiss`, that can be used to execute code when the toast is auto-closed (after the duration timeout) or manually dismissed, respectively.
+
+```jsx
+toast('Hello', {
+  onAutoClose: () => console.log('Auto-closed!'),
+  onDismiss: () => console.log('Manually dismissed!'),
+});
+```
+
+### Infinite toasts
+
+Pass `duration` as `Infinity` to make the toast stay until manually dismissed:
+
+```jsx
+toast('Hello', {
+  duration: Infinity,
+});
+```
+
 ### Dismissing toasts
 
 To dismiss a toast, call toast.dismiss with the toast ID:
@@ -122,3 +150,23 @@ toast('World');
 
 toast.dismiss();
 ```
+
+## API Reference
+
+| Property           |                                              Description                                               |      Default |
+| :----------------- | :----------------------------------------------------------------------------------------------------: | -----------: |
+| description        |                           Toast's description, renders underneath the title.                           |          `-` |
+| closeButton        |                                          Adds a close button.                                          |      `false` |
+| invert             |                                Dark toast in light mode and vice versa.                                |      `false` |
+| important          |                        Control the sensitivity of the toast for screen readers                         |      `false` |
+| duration           |            Time in milliseconds that should elapse before automatically closing the toast.             |       `4000` |
+| position           |                                         Position of the toast.                                         | `top-center` |
+| dismissible        |                     If `false`, it'll prevent the user from dismissing the toast.                      |       `true` |
+| icon               |                      Icon displayed in front of toast's text, aligned vertically.                      |          `-` |
+| action             |                      Renders a primary button, clicking it will close the toast.                       |          `-` |
+| id                 |                                        Custom id for the toast.                                        |          `-` |
+| onDismiss          |       The function gets called when either the close button is clicked, or the toast is swiped.        |          `-` |
+| onAutoClose        | Function that gets called when the toast disappears automatically after it's timeout (duration` prop). |          `-` |
+| unstyled           |                  Removes the default styling, which allows for easier customization.                   |      `false` |
+| actionButtonStyles |                                      Styles for the action button                                      |         `{}` |
+| cancelButtonStyles |                                      Styles for the cancel button                                      |         `{}` |
diff --git a/docs/static/img/demo-description-action-light.png b/docs/static/img/demo-description-action-light.png
diff --git a/docs/static/img/demo-description-actoin-dark.png b/docs/static/img/demo-description-actoin-dark.png
diff --git a/docs/static/img/demo-description-dark.png b/docs/static/img/demo-description-dark.png
diff --git a/docs/static/img/demo-promise.png b/docs/static/img/demo-promise.png
diff --git a/docs/static/img/demo-simple-dark.png b/docs/static/img/demo-simple-dark.png
diff --git a/docs/static/img/demo-simple-light.png b/docs/static/img/demo-simple-light.png
diff --git a/docs/static/img/demo-windows-xp.png b/docs/static/img/demo-windows-xp.png
diff --git a/docs/static/img/preview.png b/docs/static/img/preview.png
diff --git a/example/src/App.tsx b/example/src/App.tsx
@@ -16,7 +16,7 @@ const App: React.FC = () => {
     <SafeAreaProvider>
       <GestureHandlerRootView>
         <NavigationContainer>
-          <Stack.Navigator>
+          <Stack.Navigator screenOptions={{}}>
             <Stack.Screen name="ToastDemo" component={ToastDemoScreen} />
             <Stack.Screen
               name="ToastDemoModal"
@@ -29,13 +29,14 @@ const App: React.FC = () => {
         </NavigationContainer>
         <Toaster
           position="top-center"
-          duration={3000}
+          duration={30000}
           swipToDismissDirection="up"
           visibleToasts={4}
           closeButton
           icons={{
             error: <Text>💥</Text>,
           }}
+          toastOptions={{}}
         />
       </GestureHandlerRootView>
     </SafeAreaProvider>