@magicbell/magicbell-react - npm Package Compare versions

Comparing version 2.0.1 to 2.0.2

dist/components/MagicBell/MagicBell.d.ts

@@ -11,3 +11,3 @@ import React from 'react';
         toggleNotificationCenter: () => void;
-    }) => React.ReactNode;
+    }) => React.ReactElement;
     theme?: IMagicBellTheme;
@@ -14,0 +14,0 @@ BellIcon?: React.ReactElement;

package.json

 {
   "name": "@magicbell/magicbell-react",
-  "version": "2.0.1",
+  "version": "2.0.2",
   "description": "React components for MagicBell",
@@ -89,2 +89,3 @@ "main": "dist/index.js",
     "mobx": ">= 4",
+    "mobx-react-lite": ">= 2.0.0",
     "react": ">= 16.8.0",
@@ -100,3 +101,5 @@ "react-dom": ">= 16.8.0",
     "magicbell",
-    "notifications"
+    "notifications",
+    "typescript",
+    "react"
   ],
@@ -103,0 +106,0 @@ "homepage": "https://magicbell.io",

README.md

@@ -10,4 +10,17 @@ [![codecov](https://codecov.io/gh/magicbell-io/magicbell-react/branch/master/graph/badge.svg?token=3LTT2AL3DV)](https://codecov.io/gh/magicbell-io/magicbell-react)
 
-### Example
+MagicBell-React is a set of React components to build a notification widget for your site powered by [magicbell.io](https://magicbell.io).
 
+- Full [TypeScript](https://www.typescriptlang.org/) support
+- Supports [preact](https://preactjs.com)
+- Requires React 16.8+
+- Compatible with any browser that supports [`Proxy`](https://caniuse.com/proxy)
+
+## Quick Start
+
+```sh
+npm i @magicbell/magicbell-react
+# or
+yarn add @magicbell/magicbell-react
+```
+
 ```javascript
@@ -24,1 +37,199 @@ import React from 'react';
 ```
+
+## Table of Contents
+
+- Components
+
+  - [Introduction](#introduction)
+  - [MagicBell](#magicbell)
+  - [NotificationCenter](#notificationcenter)
+  - [NotificationList](#notificationlist)
+  - [ClickableNotification](#clickablenotification)
+
+- [Custom Themes](#custom-themes)
+
+## Introduction
+
+This package is built using [MobX](https://mobx.js.org). The notification store and its items are MobX observables. To use this package you don't need to know anything about MobX. However, if you build a component, **make it observe changes to the observable objects we expose**. This is as simple as this:
+
+```javascript
+// Before
+export default function MyComponent() {}
+
+// After
+import { observer } from 'mobx-react-lite';
+
+function MyComponent() {}
+export default observer(MyComponent);
+```
+
+The overhead of observer itself is negligible. You can read more about how to observe MobX objects at [the official docs of mobx-react](https://mobx-react.js.org/observe-how).
+
+Once you make your custom component observe changes, it will be updated automatically.
+
+## MagicBell
+
+The `MagicBell` component is the default export of this package and is the root component for building a widget. It initializes a connection to [magicbell.io](https://magicbell.io), renders a bell icon with the number of unseen notifications and keeps the widget updated in real time.
+
+These are all the properties accepted by this component.
+
+| Property    | Type                                                           | Description                                                                                           |
+| ----------- | -------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
+| `apiKey`    | `string`                                                       | The API key of your magicbell.io project                                                              |
+| `userEmail` | `string`                                                       | The email of the user you want to show notifications for                                              |
+| `userKey`   | `string`                                                       | The HMAC for the user. It is recommended to enable HMAC authentication but not required               |
+| `children`  | `({ notifications, toggleNotificationCenter }) => JSX.Element` | The children function to render all notifications for the user                                        |
+| `theme`     | `IMagicBellTheme`                                              | An optional object containing custom color values for the widget, see [Custom Themes](#custom-themes) |  |
+| `BellIcon`  | `JSX.Element`                                                  | An optional react element to be displayed instead of the default bell icon                            |
+
+### Children function
+
+This component expects a children function. This is how you render whatever you want to based on the state of the `MagicBell`.
+
+You can use the notification center from this package (see [`NotificationCenter`](#notificationcenter)):
+
+```javascript
+import React from 'react';
+import MagicBell, { NotificationCenter } from '@magicbell/magicbell-react';
+
+render(
+  <MagicBell apiKey={MAGICBELL_API_KEY} userEmail="[e-mail]">
+    {() => <NotificationCenter height={300} />}
+  </MagicBell>,
+  document.body,
+);
+```
+
+or use one of your own:
+
+<!-- prettier-ignore -->
+```javascript
+import React from 'react';
+import MagicBell from '@magicbell/magicbell-react';
+
+render(
+  <MagicBell apiKey={MAGICBELL_API_KEY} userEmail="[e-mail]">
+    {({ notifications, toggleNotificationCenter }) => (
+      <MyOwnNotificationCenter notifications={notifications} />
+    )}
+  </MagicBell>,
+  document.body,
+);
+```
+
+The `MagicBell` component does not render the component returned by the children function by default, only the bell is rendered. When the bell is clicked, the child component is toggled. As shown above, the children function gets the `notifications` store and a function to manually toggle the notification center. You can access the `notifications` store through `MagicBellContext`, too.
+
+## NotificationCenter
+
+The `NotificationCenter` component renders a header, a footer and an infinite scroll list of notifications.
+
+These are all the properties accepted by this component.
+
+| Property              | Type                     | Description                                                                     |
+| --------------------- | ------------------------ | ------------------------------------------------------------------------------- |
+| `height`              | `number`                 | Height in pixels of the infinite scroll list                                    |
+| `onAllRead`           | `() => void`             | An optional callback function called when the "Mark All Read" button is clicked |
+| `onNotificationClick` | `(notification) => void` | An optional callback function called when a notification is clicked             |
+
+## NotificationList
+
+The `NotificationList` component renders an infinite scroll list of notifications. When the user scrolls to the bottom the next page of notifications are fetched and appended to the current array of notifications. By default it renders a `ClickableNotification` component for each item in the notifications store.
+
+These are all the properties accepted by this component.
+
+| Property      | Type                                             | Description                                                         |
+| ------------- | ------------------------------------------------ | ------------------------------------------------------------------- |
+| `height`      | `number`                                         | Height in pixels of the infinite scroll list                        |
+| `onItemClick` | `(notification) => void`                         | An optional callback function called when a notification is clicked |
+| `ListItem`    | `({ notification, onItemClick }) => JSX.Element` | An optional custom component to use for each item in the list       |
+
+If the height property is not provided, then the window scroll will be used.
+
+Example: [notification center with a custom list item](https://codesandbox.io/s/busy-brahmagupta-v81p7?file=/src/MyNotificationCenter.js).
+
+## ClickableNotification
+
+This component renders the title and content of a notification.
+
+**IMPORTANT:** When a notification is clicked, the notification is marked as read. If you implement your own component, you might also want to mark the notification as read manually. E.g.:
+
+```javascript
+import React from 'react';
+import { observer } from 'mobx-react';
+
+function CustomNotification({ notification, onClick }) {
+  const handleClick = () => {
+    notification.markAsRead();
+    onClick(notification);
+  };
+
+  return <div onClick={handleClick}>{notification.title}</div>;
+}
+
+export default observer(CustomNotification);
+```
+
+## Custom Themes
+
+Is is possible to change the default colors of some elements by providing to the `MagicBell` component a `theme` property.
+
+This is the definition of the default theme:
+
+```javascript
+{
+  icon: {
+    borderColor: '#335EEA',
+  },
+  header: {
+    backgroundColor: '#335EEA',
+    textColor: 'white',
+  },
+  footer: {
+    backgroundColor: '#335EEA',
+    textColor: 'white',
+  },
+  unseenBadge: {
+    backgroundColor: '#DF4759',
+    textColor: 'white',
+  },
+  notification: {
+    default: {
+      backgroundColor: 'white',
+      textColor: '#2F323C',
+      title: {
+        textColor: '#161B2D',
+      },
+    },
+    unread: {
+      backgroundColor: '#D9E2EF',
+      textColor: '#2F323C',
+      title: {
+        textColor: '#161B2D',
+      },
+    },
+  },
+}
+```
+
+You can override any attribute of this theme. Colors can be expressed in HEX or RGB(A).
+
+```javascript
+import React from 'react';
+import MagicBell, { NotificationCenter } from '@magicbell/magicbell-react';
+
+const customTheme = {
+  icon: {
+    borderColor: 'rgba(160, 30, 120, 0.5)',
+  },
+  header: {
+    textColor: 'black',
+  },
+};
+
+render(
+  <MagicBell apiKey={MAGICBELL_API_KEY} userEmail="[e-mail]" theme={customTheme}>
+    {() => <NotificationCenter height="300" />}
+  </MagicBell>,
+  document.body,
+);
+```

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

283265

increased by3.21%

Number of lines in readme file

234

increased by917.39%

Worsened metrics

Dependency count

19

increased by5.56%

No dependency changes