@notifizz/vanilla 1.1.0 → 1.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +80 -0
- package/package.json +1 -1
package/README.md
ADDED
|
@@ -0,0 +1,80 @@
|
|
|
1
|
+
# @notifizz/vanilla
|
|
2
|
+
|
|
3
|
+
Embed the Notifizz notification center and control it from vanilla JavaScript or TypeScript (no framework). Use `createNotifizz` to get an API that lets you mount the widget, subscribe to state, attach a custom bell button, and open/close the panel.
|
|
4
|
+
|
|
5
|
+
## Installation
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
npm install @notifizz/vanilla
|
|
9
|
+
# or
|
|
10
|
+
yarn add @notifizz/vanilla
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
## Usage
|
|
14
|
+
|
|
15
|
+
```javascript
|
|
16
|
+
import { createNotifizz } from '@notifizz/vanilla';
|
|
17
|
+
|
|
18
|
+
const nz = createNotifizz({
|
|
19
|
+
apiKey: 'YOUR_FRONT_API_KEY',
|
|
20
|
+
token: 'USER_FIREBASE_TOKEN_OR_BACKEND_TOKEN',
|
|
21
|
+
authType: 'backendToken',
|
|
22
|
+
userEmail: 'user@example.com',
|
|
23
|
+
userId: '12345',
|
|
24
|
+
position: 'top-right',
|
|
25
|
+
});
|
|
26
|
+
|
|
27
|
+
// Mount the notification center (creates a div or uses the one you pass)
|
|
28
|
+
nz.mount();
|
|
29
|
+
|
|
30
|
+
// Optional: use your own bell button
|
|
31
|
+
const myButton = document.getElementById('my-bell');
|
|
32
|
+
nz.setBellElement(myButton);
|
|
33
|
+
|
|
34
|
+
// React to state changes (e.g. update a custom badge)
|
|
35
|
+
nz.onBellUpdate((ctx) => {
|
|
36
|
+
console.log('Unread:', ctx.unreadCount);
|
|
37
|
+
myButton.setAttribute('data-unread', String(ctx.unreadCount));
|
|
38
|
+
});
|
|
39
|
+
|
|
40
|
+
// Programmatic control
|
|
41
|
+
nz.open();
|
|
42
|
+
nz.close();
|
|
43
|
+
nz.toggle();
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
Use `authType: 'backendToken'` when using a backend-generated token; then provide `userEmail` and `userId`. Use `authType: 'firebase'` for Firebase ID tokens.
|
|
47
|
+
|
|
48
|
+
## Options
|
|
49
|
+
|
|
50
|
+
| Option | Type | Required | Description |
|
|
51
|
+
|--------|------|----------|-------------|
|
|
52
|
+
| `apiKey` | `string` | Yes | Your Notifizz front API key. |
|
|
53
|
+
| `token` | `string` | Yes | Auth token (Firebase ID token or backend token). |
|
|
54
|
+
| `authType` | `'firebase'` \| `'backendToken'` | Yes | How the user is authenticated. |
|
|
55
|
+
| `position` | `'top-right'` \| `'top-left'` \| `'bottom-right'` \| `'bottom-left'` | No | Bell position. |
|
|
56
|
+
| `notificationCenterStyles` | `{ marginTop?: string }` | No | Styles for the notification center. |
|
|
57
|
+
| `bellStyles` | `{ marginRight?: string; marginLeft?: string }` | No | Styles for the bell. |
|
|
58
|
+
| `userEmail` | `string` | If `authType === 'backendToken'` | User email. |
|
|
59
|
+
| `userId` | `string` | If `authType === 'backendToken'` | User ID. |
|
|
60
|
+
| `serverUrl` | `string` | No | Override widget server URL. |
|
|
61
|
+
| `apiUrl` | `string` | No | Override API base URL. |
|
|
62
|
+
| `widgetPath` | `string` | No | Override widget script path. |
|
|
63
|
+
| `mountId` | `string` | No | ID of the mount element (default: `"notifizz-notifications"`). |
|
|
64
|
+
|
|
65
|
+
## Returned API
|
|
66
|
+
|
|
67
|
+
| Method | Description |
|
|
68
|
+
|--------|-------------|
|
|
69
|
+
| `mount(element?)` | Mount the notification center. Pass an `HTMLElement` to use it, or omit to create a div with `mountId`. Returns the mount element. |
|
|
70
|
+
| `getState()` | Current state: `{ isReady, isOpen, unreadCount, lastUpdated }`. |
|
|
71
|
+
| `onReady(cb)` | Register a callback when the widget is ready. Returns an unsubscribe function. |
|
|
72
|
+
| `onStateChange(cb)` | Register a callback when state changes. Returns an unsubscribe function. |
|
|
73
|
+
| `onBellUpdate(cb)` | Register a callback with bell context (`unreadCount`, `toggle`, `open`, `close`, etc.); called on state changes. Returns an unsubscribe function. |
|
|
74
|
+
| `setBellElement(el)` | Attach a custom bell element; clicks will call `toggle`. Pass `null` to detach. |
|
|
75
|
+
| `toggle()` | Toggle the notification panel. |
|
|
76
|
+
| `open()` | Open the notification panel. |
|
|
77
|
+
| `close()` | Close the notification panel. |
|
|
78
|
+
| `destroy()` | Remove the mount element and all event listeners. |
|
|
79
|
+
|
|
80
|
+
When you are done (e.g. on route change or teardown), call `nz.destroy()` to clean up.
|