Skip to content

Commit cf58d21

Browse files
cizil-keyvaluecizil-keyvalue
authored
feat: Add documentation on installation, configuration and usage
1 parent 0b9e524 commit cf58d21

File tree

6 files changed

+328
-15
lines changed

6 files changed

+328
-15
lines changed

‎README.md‎

Lines changed: 312 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,312 @@
1-
# siren-vue-inbox
1+
# Siren Vue Inbox
2+
3+
## Overview
4+
5+
The `@sirenapp/vue-inbox` sdk is a comprehensive and customizable Vue UI kit for displaying and managing notifications. This documentation provides comprehensive information on how to install, configure, and use the sdk effectively.
6+
7+
## 1. Installation
8+
9+
You can install the vue sdk from npm
10+
11+
```bash
12+
npm install @sirenapp/vue-inbox
13+
```
14+
15+
or from yarn
16+
17+
```bash
18+
yarn add @sirenapp/vue-inbox
19+
```
20+
21+
#### Prerequisites
22+
23+
- Vue3 (v3.0.0+)
24+
25+
## 2. Configuration
26+
27+
### 2.1 Initialization
28+
29+
Initialize the sdk with user token and recipient id. Wrap the provider around your App's root.
30+
31+
```vue
32+
33+
<template>
34+
<SirenProvider :config="config"> {/* Your app components */} </SirenProvider>
35+
</template>
36+
37+
<script setup lang="ts">
38+
import { SirenProvider } from "@sirenapp/vue-inbox";
39+
40+
const config = {
41+
userToken: "your_user_token",
42+
recipientId: "your_recipient_id",
43+
};
44+
45+
</script>
46+
```
47+
48+
### 2.2 Configure notification inbox
49+
50+
Once the provider is configured, next step is to configure the notification inbox
51+
52+
Inbox is a paginated list view for displaying notifications.
53+
54+
```vue
55+
<template>
56+
<SirenInbox />
57+
</template>
58+
59+
<script setup lang="ts">
60+
import { SirenInbox } from "@sirenapp/vue-inbox";
61+
</script>
62+
63+
```
64+
65+
#### Props for the notification inbox
66+
67+
Below are optional props available for the inbox component:
68+
69+
| Prop | Description | Type | Default value |
70+
|------|-------------|-------|---------------|
71+
| theme | Object for custom themes | Theme | {} |
72+
| loadMoreLabel | Text shown on the load more component | string | "Load More" |
73+
| hideBadge | Toggle to hide or show the badge | boolean | false |
74+
| darkMode | Toggle to enable dark mode | boolean | false |
75+
| itemsPerFetch | Number of notifications fetch per api request (have a max cap of 50) | number | 20 |
76+
| windowViewOnly | Toggle to enable fit-to-screen window or modal view | boolean | false |
77+
| headerProps | Props for customizing the header.<br> title - Title of the notification inbox<br> hideHeader - Toggle to hide or show the header section.<br> hideClearAll - Toggle to hide or show the clear all button. | HeaderProps | { title: 'Notifications', <br>hideHeader: false,<br> hideClearAll: false } |
78+
| cardProps | Props for customizing the notification cards. <br>hideDelete - Toggle to hide or show delete icon<br> hideAvatar - Toggle to hide or show the avatar. <br> disableAutoMarkAsRead - Toggle to disable or enable the markAsReadById functionality on card click. <br> onAvatarClick - Custom click handler for avatar | CardProps | { hideDelete: false,<br> hideAvatar: false,<br> disableAutoMarkAsRead: false, <br> onAvatarClick: ()=>null } |
79+
| onCardClick | Custom click handler for notification cards | (notification)=> void | ()=>null |
80+
| onError | Callback for handling errors | (error: SirenErrorType)=> void | ()=>null |
81+
82+
#### CardProps
83+
84+
```js
85+
type CardProps = {
86+
hideDelete?: boolean;
87+
hideAvatar?: boolean,
88+
onAvatarClick?: (notification: NotificationDataType) => void,
89+
disableAutoMarkAsRead?: boolean;
90+
};
91+
```
92+
93+
#### HeaderProps
94+
95+
```js
96+
type HeaderProps = {
97+
title?: string;
98+
hideHeader?: boolean,
99+
hideClearAll?: boolean
100+
};
101+
```
102+
103+
104+
#### Slots for the notification inbox
105+
106+
Below are optional slots available for the inbox component:
107+
108+
| Slot | Description |
109+
| ------------------ | ---------------------------------- |
110+
| loadMoreComponent | Custom load more button component |
111+
| customHeader | Custom header component |
112+
| customLoader | Custom loader component |
113+
| customErrorWindow | Custom Error window |
114+
| listEmptyComponent | Custom Empty list component |
115+
| customCard | Custom notification card component |
116+
| customFooter | Custom footer component |
117+
118+
## 3. Customization
119+
120+
### 3.1 Themes
121+
122+
Here are the available theme options:
123+
124+
```js
125+
type Theme = {
126+
dark: ThemeProps,
127+
light: ThemeProps,
128+
};
129+
130+
type ThemeProps = {
131+
colors?: {
132+
primaryColor?: string,
133+
textColor?: string,
134+
neutralColor?: string,
135+
borderColor?: string,
136+
highlightedCardColor?: string,
137+
dateColor?: string,
138+
deleteIcon?: string,
139+
timerIcon?: string,
140+
clearAllIcon?: string,
141+
infiniteLoader?: string,
142+
windowShadowColor?: string,
143+
},
144+
badgeStyle?: {
145+
color?: string,
146+
textColor?: string,
147+
},
148+
window?: {
149+
borderColor?: string,
150+
},
151+
windowHeader?: {
152+
background?: string,
153+
titleColor?: string,
154+
headerActionColor?: string,
155+
borderColor?: string,
156+
},
157+
windowContainer?: {
158+
background?: string,
159+
},
160+
customCard?: {
161+
borderColor?: string,
162+
background?: string,
163+
titleColor?: string,
164+
subtitleColor?: string,
165+
descriptionColor?: string,
166+
},
167+
loadMoreButton?: {
168+
color?: string,
169+
background?: string,
170+
},
171+
};
172+
```
173+
174+
### 3.2 Style options
175+
176+
Here are the custom style options for the notification inbox
177+
178+
Please note that the badgeStyle, window shadow and border props are only applicable for modal view
179+
180+
```js
181+
type CustomStyle = {
182+
notificationIcon?: {
183+
size?: number,
184+
},
185+
window?: {
186+
width?: DimensionValue,
187+
borderRadius?: number,
188+
},
189+
windowHeader?: {
190+
height?: DimensionValue,
191+
titleFontWeight?:TextStyle["fontWeight"],
192+
titleSize?: number,
193+
titlePadding?: number,
194+
borderWidth?: string,
195+
},
196+
windowContainer?: {
197+
padding?: number,
198+
contentHeight?: DimensionValue,
199+
},
200+
customCard?: {
201+
padding?: number,
202+
borderWidth?: number,
203+
avatarSize?: number,
204+
titleFontWeight?: TextStyle["fontWeight"],
205+
titleSize?: number,
206+
subtitleFontWeight?: TextStyle['fontWeight'],
207+
subtitleSize?: number
208+
descriptionFontWeight?: TextStyle['fontWeight'],
209+
descriptionSize?: number,
210+
dateSize?: number,
211+
},
212+
loadMoreButton?: {
213+
fontSize?: number,
214+
fontWeight?: TextStyle["fontWeight"],
215+
},
216+
badgeStyle?: {
217+
size?: number,
218+
textSize?: number,
219+
top?: number,
220+
right?: number,
221+
},
222+
deleteIcon?:{
223+
size?: number,
224+
}
225+
dateIcon?:{
226+
size?: number,
227+
}
228+
timerIcon?: {
229+
size?: number,
230+
},
231+
clearAllIcon?:{
232+
size?: number,
233+
}
234+
}
235+
```
236+
237+
## 4. Hooks
238+
239+
`useSiren` is a hook that provides utility functions for modifying notifications.
240+
241+
```vue
242+
<script setup lang="ts">
243+
import { useSiren } from "@sirenapp/vue-inbox";
244+
245+
const {
246+
markAsReadByDate,
247+
markAsReadById,
248+
deleteById,
249+
deleteByDate,
250+
markAllAsViewed
251+
} = useSiren();
252+
253+
function handleMarkAsReadById(id) {
254+
markAsReadById(id);
255+
}
256+
257+
function handleMarkAsReadByDate(untilDate) {
258+
markAsReadByDate(untilDate);
259+
}
260+
261+
function handleDeleteById(id) {
262+
deleteById(id);
263+
}
264+
265+
function handleDeleteByDate(date) {
266+
deleteByDate(date);
267+
}
268+
269+
function handleMarkAllAsViewed(createdAt) {
270+
markAllAsViewed(createdAt);
271+
}
272+
273+
</script>
274+
```
275+
276+
### useSiren functions
277+
278+
| Functions | Parameters | Type | Description |
279+
| ----------------------------- | ---------- | --------------- | -------------------------------------------------------------------- |
280+
| markAsReadByDate | startDate | ISO date string | Sets the read status of notifications to true until the given date |
281+
| markAsReadById | id | string | Set read status of a notification to true |
282+
| deleteById | id | string | Delete a notification by id |
283+
| deleteByDate | startDate | ISO date string | Delete all notifications until given date |
284+
| markAllAsViewed | startDate | ISO date string | Sets the viewed status of notifications to true until the given date |
285+
286+
287+
## Example
288+
289+
Here's a basic example to help you get started
290+
291+
```vue
292+
<template>
293+
<SirenProvider
294+
:config="{
295+
userToken: 'your-user-token',
296+
recipientId: 'your-user-recipientId',
297+
}"
298+
>
299+
<SirenInbox
300+
:headerProps="{
301+
title: 'Siren Notifications',
302+
hideHeader: false,
303+
hideClearAll: true,
304+
}"
305+
/>
306+
</SirenProvider>
307+
</template>
308+
309+
<script setup lang="ts">
310+
import { SirenProvider, SirenInbox } from "@sirenapp/vue-inbox";
311+
</script>
312+
```

‎src/components/HeaderComponent.vue‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -33,13 +33,13 @@
3333
<script setup lang="ts">
3434
import { withDefaults, defineProps } from 'vue';
3535
36-
import type { HeaderProps } from '../types';
36+
import type { HeaderComponentProps } from '../types';
3737
import { CLEAR_ALL_LABEL } from '../utils/constants';
3838
import ClearIcon from './ClearAllIcon.vue';
3939
4040
import '../styles/header.css';
4141
42-
withDefaults(defineProps<HeaderProps>(), {
42+
withDefaults(defineProps<HeaderComponentProps>(), {
4343
enableClearAll: true
4444
});
4545
</script>

‎src/components/SirenInbox.vue‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -40,13 +40,13 @@
4040
<template #customErrorWindow>
4141
<slot name="customErrorWindow" />
4242
</template>
43-
<template #emptyList>
43+
<template #listEmptyComponent>
4444
<slot name="listEmptyComponent" />
4545
</template>
4646
<template #customCard="{ item }">
4747
<slot name="customCard" :item="item" />
4848
</template>
49-
<template #footer>
49+
<template #customFooter>
5050
<slot name="customFooter" />
5151
</template>
5252
</SirenPanel>

‎src/types.ts‎

Lines changed: 9 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -122,6 +122,7 @@ export type CustomStyle = {
122122
titleFontWeight?: TextStyle['fontWeight'];
123123
titleSize?: number;
124124
titlePadding?: number;
125+
borderWidth?: string;
125126
};
126127
windowContainer?: {
127128
padding?: number;
@@ -162,21 +163,22 @@ export type CustomStyle = {
162163

163164
export type CardProps = {
164165
hideAvatar?: boolean;
165-
showMedia?: boolean;
166166
hideDelete?: boolean;
167167
disableAutoMarkAsRead?: boolean;
168168
onAvatarClick?: (notification: NotificationDataType) => void;
169169
};
170170

171+
export type HeaderProps = {
172+
title?: string;
173+
hideHeader?: boolean;
174+
hideClearAll?: boolean;
175+
};
176+
171177
export type SirenInboxProps = {
172178
theme?: Theme;
173179
customStyle?: CustomStyle;
174180
loadMoreLabel?: string;
175-
headerProps?: {
176-
title?: string;
177-
hideHeader?: boolean;
178-
hideClearAll?: boolean;
179-
};
181+
headerProps?: HeaderProps;
180182
hideBadge?: boolean;
181183
darkMode?: boolean;
182184
itemsPerFetch?: number;
@@ -187,7 +189,6 @@ export type SirenInboxProps = {
187189

188190
export type SirenNotificationIconProps = {
189191
theme?: Theme;
190-
realTimeUnViewedCountEnabled?: boolean;
191192
onError?: (error: SirenErrorType) => void;
192193
darkMode?: boolean;
193194
};
@@ -242,7 +243,7 @@ export type ErrorWindowProps = {
242243
error: string;
243244
};
244245

245-
export type HeaderProps = {
246+
export type HeaderComponentProps = {
246247
title: string;
247248
enableClearAll?: boolean;
248249
handleClearAllNotification: () => void;

0 commit comments

Comments
 (0)