@aslaluroba/help-center 3.0.14 → 4.0.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.
Files changed (5) hide show
  1. package/README.md +95 -126
  2. package/fesm2022/aslaluroba-help-center.mjs +2433 -1294
  3. package/fesm2022/aslaluroba-help-center.mjs.map +1 -1
  4. package/index.d.ts +469 -147
  5. package/package.json +2 -2
package/README.md CHANGED
@@ -5,72 +5,52 @@ A powerful and customizable help center widget for Angular applications with rea
5
5
  ## Installation
6
6
 
7
7
  ```bash
8
+ yarn add @aslaluroba/help-center
8
9
  npm install @aslaluroba/help-center
9
10
  ```
10
11
 
11
12
  ## Setup and Configuration
12
13
 
13
- 1. Import and configure the widget in your app.module.ts:
14
+ 1. Provide `ApiService` once (e.g., in `main.ts`) and use the standalone component in your app:
14
15
 
15
16
  ```typescript
16
- import { HelpCenterWidgetComponent, ApiService } from '@aslaluroba/help-center'
17
+ import { bootstrapApplication } from "@angular/platform-browser";
18
+ import { Component, OnInit, inject } from "@angular/core";
19
+ import { ApiService, ApiConfig, Language, HelpCenterWidgetComponent } from "@aslaluroba/help-center";
17
20
 
18
- @NgModule({
19
- imports: [HelpCenterWidgetComponent],
20
- providers: [ApiService]
21
- })
22
- export class AppModule {}
23
- ```
24
-
25
- 2. Initialize and use the widget in your component:
26
-
27
- ```typescript
28
- import { Component, OnInit } from '@angular/core'
29
- import { ApiService, ApiConfig, Language } from '@aslaluroba/help-center'
21
+ bootstrapApplication(AppComponent, {
22
+ providers: [ApiService],
23
+ });
30
24
 
31
25
  @Component({
32
- selector: 'app-root',
33
- template: `
34
- <app-help-center-widget
35
- [getToken]="getToken"
36
- [helpScreenId]="helpScreenId"
37
- [currentLang]="currentLang"
38
- [showArrow]="true"
39
- [primaryColor]="primaryColor"
40
- [logoUrl]="logoUrl">
41
- </app-help-center-widget>
42
- `
26
+ selector: "app-root",
27
+ standalone: true,
28
+ imports: [HelpCenterWidgetComponent],
29
+ template: ` <app-help-center-widget [getToken]="getToken" [helpScreenId]="helpScreenId" [currentLang]="currentLang" [showArrow]="true" [primaryColor]="primaryColor" [logoUrl]="logoUrl"> </app-help-center-widget> `,
43
30
  })
44
31
  export class AppComponent implements OnInit {
45
- helpScreenId = 'your-help-screen-id' // Required: Your unique help screen ID
46
- currentLang: Language = 'en' // Default language
47
- primaryColor = '#ad49e1' // Optional: Custom primary color (default: purple)
48
- logoUrl = 'assets/logo.svg' // Optional: Custom logo URL (default: built-in logo)
32
+ private apiService = inject(ApiService);
49
33
 
50
- constructor(private apiService: ApiService) {}
34
+ helpScreenId = "your-help-screen-id";
35
+ currentLang: Language = "en";
36
+ primaryColor = "#ad49e1";
37
+ logoUrl = "assets/logo.svg";
51
38
 
52
39
  ngOnInit() {
53
- // Initialize API with authentication
54
40
  const apiConfig: ApiConfig = {
55
- getToken: async () => {
56
- // Implement your token retrieval logic
57
- const response = await fetch('your-auth-endpoint')
58
- const data = await response.json()
59
- return data.token
60
- }
61
- // Optional: Override default API URL (default: 'https://babylai.net/api')
41
+ getToken: this.getToken,
42
+ // Optional: baseUrl override (default: https://babylai.net/api)
62
43
  // baseUrl: 'https://your-custom-api.com'
63
- }
44
+ };
64
45
 
65
- this.apiService.initialize(apiConfig)
46
+ this.apiService.initialize(apiConfig);
66
47
  }
67
48
 
68
49
  getToken = async () => {
69
- // Your token retrieval implementation
70
- const response = await fetch('your-auth-endpoint')
71
- const data = await response.json()
72
- return data.token
73
- }
50
+ const response = await fetch("your-auth-endpoint");
51
+ const data = await response.json();
52
+ return data.token;
53
+ };
74
54
  }
75
55
  ```
76
56
 
@@ -79,6 +59,7 @@ export class AppComponent implements OnInit {
79
59
  The widget includes a comprehensive user feedback system that collects ratings and comments after meaningful chat interactions:
80
60
 
81
61
  ### Review Dialog Features
62
+
82
63
  - **Star Rating**: 1-5 star rating system with visual feedback
83
64
  - **Comment Collection**: Text area for detailed feedback (10-500 characters)
84
65
  - **Smart Display**: Only appears after meaningful chat interactions (not just welcome messages)
@@ -87,6 +68,7 @@ The widget includes a comprehensive user feedback system that collects ratings a
87
68
  - **Multi-language**: Fully translated interface
88
69
 
89
70
  ### Review API Endpoint
71
+
90
72
  Reviews are submitted to: `POST /Client/ClientChatSession/{sessionId}/review`
91
73
 
92
74
  ```typescript
@@ -98,6 +80,7 @@ Reviews are submitted to: `POST /Client/ClientChatSession/{sessionId}/review`
98
80
  ```
99
81
 
100
82
  ### Review Dialog Behavior
83
+
101
84
  - **Triggers**: Only after ending a chat with meaningful interaction
102
85
  - **Skips**: If user just opens chat without interaction
103
86
  - **Validation**: Client-side validation with real-time feedback
@@ -109,20 +92,29 @@ Reviews are submitted to: `POST /Client/ClientChatSession/{sessionId}/review`
109
92
  The widget includes intelligent chat session management to provide a seamless user experience:
110
93
 
111
94
  ### Confirmation Dialogs
95
+
112
96
  - **End Chat Confirmation**: Prevents accidental loss of active conversations
113
97
  - **Start New Chat Confirmation**: Warns users when switching between chat sessions
114
98
  - **Smart Detection**: Distinguishes between welcome messages and meaningful interactions
115
99
 
116
100
  ### Session Persistence
101
+
117
102
  - **Back Navigation**: Chat state maintained when navigating back to help screen
118
103
  - **Return to Chat**: Users can return to their previous conversation
119
104
  - **Duplicate Prevention**: Intelligent message handling prevents duplicate welcome messages
120
105
 
121
106
  ### Session States
107
+
122
108
  - **Active Session**: User has meaningful interaction (not just welcome message)
123
109
  - **Welcome Only**: User opened chat but didn't interact meaningfully
124
110
  - **Clean State**: No previous session or messages
125
111
 
112
+ ### Attachments
113
+
114
+ - Users can add files; uploads are presigned and stored via S3
115
+ - Pending files are uploaded after the first message creates a session
116
+ - Attachment IDs are sent with messages and delivered in Ably payloads
117
+
126
118
  ## Language Support
127
119
 
128
120
  The widget supports multiple languages with built-in RTL support. Currently available languages:
@@ -135,11 +127,11 @@ The widget supports multiple languages with built-in RTL support. Currently avai
135
127
  1. Simple language switch:
136
128
 
137
129
  ```typescript
138
- import { Component } from '@angular/core'
139
- import { Language } from '@aslaluroba/help-center'
130
+ import { Component } from "@angular/core";
131
+ import { Language } from "@aslaluroba/help-center";
140
132
 
141
133
  @Component({
142
- selector: 'app-root',
134
+ selector: "app-root",
143
135
  template: `
144
136
  <div>
145
137
  <!-- Language Switcher -->
@@ -149,47 +141,41 @@ import { Language } from '@aslaluroba/help-center'
149
141
  </div>
150
142
 
151
143
  <!-- Widget -->
152
- <app-help-center-widget
153
- [getToken]="getToken"
154
- [helpScreenId]="helpScreenId"
155
- [currentLang]="currentLang"
156
- [primaryColor]="primaryColor"
157
- [logoUrl]="logoUrl">
158
- </app-help-center-widget>
144
+ <app-help-center-widget [getToken]="getToken" [helpScreenId]="helpScreenId" [currentLang]="currentLang" [primaryColor]="primaryColor" [logoUrl]="logoUrl"> </app-help-center-widget>
159
145
  </div>
160
- `
146
+ `,
161
147
  })
162
148
  export class AppComponent {
163
- helpScreenId = 'your-help-screen-id'
164
- currentLang: Language = 'en'
165
- primaryColor = '#ad49e1'
166
- logoUrl = 'assets/logo.svg'
149
+ helpScreenId = "your-help-screen-id";
150
+ currentLang: Language = "en";
151
+ primaryColor = "#ad49e1";
152
+ logoUrl = "assets/logo.svg";
167
153
 
168
154
  getToken = async () => {
169
155
  // Your token implementation
170
- return 'your-token'
171
- }
156
+ return "your-token";
157
+ };
172
158
  }
173
159
  ```
174
160
 
175
161
  2. Using Translation Service (for advanced usage):
176
162
 
177
163
  ```typescript
178
- import { Component } from '@angular/core'
179
- import { TranslationService, Language } from '@aslaluroba/help-center'
164
+ import { Component } from "@angular/core";
165
+ import { TranslationService, Language } from "@aslaluroba/help-center";
180
166
 
181
167
  @Component({
182
- selector: 'app-root'
168
+ selector: "app-root",
183
169
  })
184
170
  export class AppComponent {
185
171
  constructor(private translationService: TranslationService) {
186
172
  // Subscribe to language changes
187
173
  this.translationService.currentLang.subscribe((lang: Language) => {
188
- console.log('Current language:', lang)
189
- })
174
+ console.log("Current language:", lang);
175
+ });
190
176
 
191
177
  // Change language
192
- this.translationService.setLanguage('ar')
178
+ this.translationService.setLanguage("ar");
193
179
  }
194
180
  }
195
181
  ```
@@ -205,15 +191,16 @@ The `primaryColor` property allows you to customize the color scheme throughout
205
191
  ```typescript
206
192
  // Example usage
207
193
  export class AppComponent {
208
- primaryColor = '#3b82f6' // Blue theme
194
+ primaryColor = "#3b82f6"; // Blue theme
209
195
  // or
210
- primaryColor = '#10b981' // Green theme
196
+ primaryColor = "#10b981"; // Green theme
211
197
  // or
212
- primaryColor = '#ff6b35' // Orange theme
198
+ primaryColor = "#ff6b35"; // Orange theme
213
199
  }
214
200
  ```
215
201
 
216
202
  **Supported Color Formats:**
203
+
217
204
  - Hex colors: `#3b82f6`, `#10b981`
218
205
  - RGB: `rgb(59, 130, 246)`
219
206
  - HSL: `hsl(217, 91%, 60%)`
@@ -228,15 +215,16 @@ The `logoUrl` property allows you to display your custom logo in the help button
228
215
  ```typescript
229
216
  // Example usage
230
217
  export class AppComponent {
231
- logoUrl = '/assets/my-logo.png' // Local asset
218
+ logoUrl = "/assets/my-logo.png"; // Local asset
232
219
  // or
233
- logoUrl = 'https://example.com/logo.png' // External URL
220
+ logoUrl = "https://example.com/logo.png"; // External URL
234
221
  // or
235
- logoUrl = 'assets/logo.svg' // Default logo (fallback)
222
+ logoUrl = "assets/logo.svg"; // Default logo (fallback)
236
223
  }
237
224
  ```
238
225
 
239
226
  **Logo Requirements:**
227
+
240
228
  - **Format**: PNG, JPG, SVG, or any web-compatible image format
241
229
  - **Size**: Recommended 50x50px for optimal display
242
230
  - **Fallback**: If the provided logo fails to load, it will fallback to the default logo
@@ -244,41 +232,32 @@ export class AppComponent {
244
232
  ### Complete Theming Example
245
233
 
246
234
  ```typescript
247
- import { Component } from '@angular/core'
235
+ import { Component } from "@angular/core";
248
236
 
249
237
  @Component({
250
- selector: 'app-root',
251
- template: `
252
- <app-help-center-widget
253
- [getToken]="getToken"
254
- [helpScreenId]="helpScreenId"
255
- [primaryColor]="primaryColor"
256
- [logoUrl]="logoUrl"
257
- [currentLang]="currentLang"
258
- [showArrow]="true">
259
- </app-help-center-widget>
260
- `
238
+ selector: "app-root",
239
+ template: ` <app-help-center-widget [getToken]="getToken" [helpScreenId]="helpScreenId" [primaryColor]="primaryColor" [logoUrl]="logoUrl" [currentLang]="currentLang" [showArrow]="true"> </app-help-center-widget> `,
261
240
  })
262
241
  export class AppComponent {
263
- helpScreenId = 'your-help-screen-id'
264
- currentLang = 'en'
265
- primaryColor = '#3b82f6' // Blue theme
266
- logoUrl = '/assets/company-logo.png'
242
+ helpScreenId = "your-help-screen-id";
243
+ currentLang = "en";
244
+ primaryColor = "#3b82f6"; // Blue theme
245
+ logoUrl = "/assets/company-logo.png";
267
246
 
268
247
  getToken = async () => {
269
248
  // Your token implementation
270
- return 'your-token'
271
- }
249
+ return "your-token";
250
+ };
272
251
 
273
252
  // Dynamic theme switching
274
253
  switchToGreenTheme() {
275
- this.primaryColor = '#10b981'
276
- this.logoUrl = '/assets/green-logo.png'
254
+ this.primaryColor = "#10b981";
255
+ this.logoUrl = "/assets/green-logo.png";
277
256
  }
278
257
 
279
258
  switchToPurpleTheme() {
280
- this.primaryColor = '#ad49e1'
281
- this.logoUrl = '/assets/purple-logo.png'
259
+ this.primaryColor = "#ad49e1";
260
+ this.logoUrl = "/assets/purple-logo.png";
282
261
  }
283
262
  }
284
263
  ```
@@ -293,52 +272,39 @@ export class AppComponent {
293
272
  - **Customizable Theming**: Dynamic color schemes and logo customization
294
273
  - **Responsive Design**: Mobile-first approach with accessibility features
295
274
  - **Duplicate Prevention**: Smart message handling to prevent duplicate content
275
+ - **File Attachments**: Presigned uploads with attachment IDs delivered to the assistant
296
276
 
297
277
  ## Props
298
278
 
299
- | Prop | Type | Required | Default | Description |
300
- | ------------------- | -------- | -------- | ------------ | ------------------------------------------------ |
301
- | getToken | function | Yes | - | Function that returns a Promise<string> for auth |
302
- | helpScreenId | string | Yes | - | Unique help screen identifier |
303
- | currentLang | Language | No | 'en' | UI language ('en' \| 'ar') |
304
- | showArrow | boolean | No | true | Show/hide floating arrow |
305
- | messageLabel | string | No | null | Custom message for the help button |
306
- | isIntroScreenEnabled| boolean | No | false | Enable/disable intro screen |
307
- | primaryColor | string | No | '#ad49e1' | Primary color for theming (hex format) |
308
- | logoUrl | string | No | '/logo.svg' | URL path to custom logo image |
279
+ | Prop | Type | Required | Default | Description |
280
+ | -------------------- | -------- | -------- | ----------- | ------------------------------------------------ |
281
+ | getToken | function | Yes | - | Function that returns a Promise<string> for auth |
282
+ | helpScreenId | string | Yes | - | Unique help screen identifier |
283
+ | currentLang | Language | No | 'en' | UI language ('en' \| 'ar') |
284
+ | showArrow | boolean | No | true | Show/hide floating arrow |
285
+ | messageLabel | string | No | null | Custom message for the help button |
286
+ | isIntroScreenEnabled | boolean | No | false | Enable/disable intro screen |
287
+ | primaryColor | string | No | '#ad49e1' | Primary color for theming (hex format) |
288
+ | logoUrl | string | No | '/logo.svg' | URL path to custom logo image |
309
289
 
310
290
  ## Quick Reference
311
291
 
312
292
  ### Basic Usage
293
+
313
294
  ```html
314
- <app-help-center-widget
315
- [getToken]="getToken"
316
- [helpScreenId]="helpScreenId">
317
- </app-help-center-widget>
295
+ <app-help-center-widget [getToken]="getToken" [helpScreenId]="helpScreenId"> </app-help-center-widget>
318
296
  ```
319
297
 
320
298
  ### With Custom Theme
299
+
321
300
  ```html
322
- <app-help-center-widget
323
- [getToken]="getToken"
324
- [helpScreenId]="helpScreenId"
325
- [primaryColor]="'#3b82f6'"
326
- [logoUrl]="'/my-logo.png'">
327
- </app-help-center-widget>
301
+ <app-help-center-widget [getToken]="getToken" [helpScreenId]="helpScreenId" [primaryColor]="'#3b82f6'" [logoUrl]="'/my-logo.png'"> </app-help-center-widget>
328
302
  ```
329
303
 
330
304
  ### With All Options
305
+
331
306
  ```html
332
- <app-help-center-widget
333
- [getToken]="getToken"
334
- [helpScreenId]="helpScreenId"
335
- [currentLang]="'en'"
336
- [showArrow]="true"
337
- [messageLabel]="'Need help?'"
338
- [isIntroScreenEnabled]="true"
339
- [primaryColor]="'#3b82f6'"
340
- [logoUrl]="'/my-logo.png'">
341
- </app-help-center-widget>
307
+ <app-help-center-widget [getToken]="getToken" [helpScreenId]="helpScreenId" [currentLang]="'en'" [showArrow]="true" [messageLabel]="'Need help?'" [isIntroScreenEnabled]="true" [primaryColor]="'#3b82f6'" [logoUrl]="'/my-logo.png'"> </app-help-center-widget>
342
308
  ```
343
309
 
344
310
  ## Troubleshooting
@@ -346,16 +312,19 @@ export class AppComponent {
346
312
  ### Common Issues
347
313
 
348
314
  1. **Duplicate Welcome Messages**
315
+
349
316
  - **Fixed**: The widget now intelligently detects and prevents duplicate welcome messages
350
317
  - **Cause**: Previously occurred when starting new chat after going back
351
318
  - **Solution**: Smart session detection and proper session clearing
352
319
 
353
320
  2. **Review Dialog Not Showing**
321
+
354
322
  - **Expected**: Review dialog only appears after meaningful chat interactions
355
323
  - **Not Showing**: If user only sees welcome message without interaction
356
324
  - **Solution**: This is intentional behavior to avoid unnecessary review prompts
357
325
 
358
326
  3. **Chat Session Issues**
327
+
359
328
  - **Session Persistence**: Chat state is maintained when navigating back
360
329
  - **Confirmation Dialogs**: Prevent accidental loss of conversations
361
330
  - **Smart Detection**: System distinguishes between welcome messages and real interactions