@mypatientspace/chatbot-widget 1.0.73 → 1.0.75

package/README.md

@@ -8,10 +8,14 @@ A standalone chatbot widget that third-party websites can embed via a single `<s
 
 - Self-contained React application bundled into a single JS file
 - Easy integration with any website
-- Floating button mode (default) or embedded mode
-- Customizable theming
+- Embedded mode (default) or floating button mode
+- Customizable theming with light, dark, and system color modes
 - Style isolation (won't conflict with host site CSS)
 - Native mobile support via WebView
+- Voice input support
+- Quick action buttons
+- Survey/questionnaire support
+- Content citations with overlay view
 
 ## Tech Stack
 
@@ -83,57 +87,6 @@ yarn build:demo         # Demo only
 yarn preview
 ```
 
-## Demo Widget
-
-An embeddable demo page with configuration panel and live preview. Useful for testing and showcasing the widget.
-
-### Via CDN
-
-```html
-<div id="chatbot-demo" style="height: 600px;"></div>
-<script src="https://unpkg.com/@mypatientspace/chatbot-widget@latest/dist/mypatientspace-demo.umd.js"></script>
-<script>
-  ChatbotWidgetDemo.init({
-    containerSelector: '#chatbot-demo',
-    showJsonEditor: true,
-    initialConfig: {
-      apiEndpoint: 'https://your-api.com/chat',
-      token: 'your-auth-token',
-      headerTitle: 'My Healthcare Bot',
-      theme: { colors: { primary: '#007bff' } }
-    },
-    onConfigChange: (config) => console.log('Config:', config)
-  });
-</script>
-```
-
-> **Note:** The "Use Mock API" toggle is only available in development mode (`yarn dev`). When embedding the demo in production, you must provide `apiEndpoint` and `token` in the `initialConfig`.
-
-### Demo API
-
-```javascript
-ChatbotWidgetDemo.init(config);    // Initialize demo
-ChatbotWidgetDemo.destroy();       // Remove demo
-ChatbotWidgetDemo.update(config);  // Update configuration
-```
-
-### Demo Configuration
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `containerSelector` | `string` | Required | CSS selector for container |
-| `showConfigPanel` | `boolean` | `true` | Show left config panel |
-| `showPreviewPanel` | `boolean` | `true` | Show right preview panel |
-| `showJsonEditor` | `boolean` | `true` | Show Form/JSON toggle |
-| `showDisplaySettings` | `boolean` | `true` | Show display settings section |
-| `showSessionSettings` | `boolean` | `true` | Show session settings section |
-| `showAppearanceSettings` | `boolean` | `true` | Show appearance section |
-| `showThemeSettings` | `boolean` | `true` | Show theme colors section |
-| `showContentSettings` | `boolean` | `true` | Show content settings section |
-| `showQuickActions` | `boolean` | `true` | Show quick actions section |
-| `initialConfig` | `Partial<WidgetConfig>` | `{}` | Pre-fill widget config (including `apiEndpoint` and `token`) |
-| `onConfigChange` | `(config) => void` | - | Called when config changes |
-
 ## Web Integration
 
 ### Minimal Setup
@@ -152,60 +105,60 @@ ChatbotWidgetDemo.update(config);  // Update configuration
 <script src="https://unpkg.com/@mypatientspace/chatbot-widget@latest/dist/mypatientspace-widget.umd.js"></script>
 <script>
   ChatbotWidget.init({
+    // API & Auth
     apiEndpoint: 'https://your-api.com/chat',
     token: 'your-auth-token',
+    assistantId: 'your-assistant-id',
+
+    // Display mode
+    floatingMode: true,          // false = embedded (default), true = FAB button
+    position: 'bottom-left',     // FAB position (default: 'bottom-right')
+    hideExpandButton: true,      // Hide expand/minimize button from header
+    showCloseSlot: true,         // Empty placeholder for custom close button
+
+    // Content
     headerTitle: 'Health Support',
+    headerSubtitle: 'Online now',
     greeting: 'Hi! How can I help?',
+    placeholder: 'Ask me anything...',
     brandingText: 'Powered by MyCompany',
+    disclaimerText: 'AI can make mistakes. Verify important information.',
     headerIcon: '/logo.png',
-    fabIcon: '/avatar.png',
-    placeholder: 'Ask me anything...',
-    position: 'bottom-left',
-    colorMode: 'system',  // 'light', 'dark', or 'system' (auto-detect)
+    fabIcon: '/avatar.png',       // Only used in floating mode
     quickActions: ['I need help', 'Book appointment'],
+
+    // Appearance
+    colorMode: 'system',  // 'light', 'dark', or 'system' (auto-detect)
     theme: {
-      // All color properties are optional - only set what you want to change
       colors: {
-        // Main colors
         primary: '#ff6600',        // FAB button, links, main accent
         primaryDark: '#cc5200',    // Hover states
         secondary: '#2d3748',      // Header background
-        accent: '#4299e1',         // Secondary accent
-        accentLight: '#bee3f8',    // Light accent
-
-        // Status colors
-        success: '#48bb78',        // Success states
-        info: '#4299e1',           // Info states
-        error: '#f56565',          // Error states
-
-        // Background colors
+        headerText: '#ffffff',     // Header text color
         background: '#ffffff',     // Chat window background
         surface: '#f7fafc',        // Input/card backgrounds
-
-        // Text colors
         text: '#2d3748',           // Primary text
         textLight: '#718096',      // Secondary text, timestamps
-
-        // Message bubbles
         userBubble: '#ff6600',     // User message background
         userBubbleText: '#ffffff', // User message text
         botBubble: '#edf2f7',      // Bot message background
         botBubbleText: '#2d3748',  // Bot message text
-
-        // Borders
-        border: '#e2e8f0',         // Border color
-        borderLight: '#edf2f7',    // Light border
-
-        // Other
-        white: '#ffffff',          // White color
-        recording: '#f56565',      // Voice recording indicator
       },
-
-      // Typography and shape
       fontFamily: 'Inter, system-ui, sans-serif',
       borderRadius: '8px',
       shadow: '0 4px 12px rgba(0, 0, 0, 0.1)',
-    }
+    },
+
+    // Callbacks
+    onOpen: () => console.log('Chat opened'),
+    onClose: () => console.log('Chat closed'),
+    onMessageSent: (message) => console.log('Sent:', message),
+    onMessageReceived: (message) => console.log('Received:', message),
+    onQuickAction: (action) => console.log('Quick action:', action),
+    onStreamChunk: (chunk) => console.log('Chunk:', chunk),
+    onCitationClick: (citation) => console.log('Citation:', citation),
+    onNewChat: () => console.log('New chat started'),
+    onWidgetReady: (api) => console.log('Widget ready:', api),
   });
 </script>
 ```
@@ -221,15 +174,17 @@ ChatbotWidget.init({
 
 ### API Methods
 ```javascript
-ChatbotWidget.open();    // Open chat window
-ChatbotWidget.close();   // Close chat window
-ChatbotWidget.toggle();  // Toggle open/close
-ChatbotWidget.destroy(); // Remove widget completely
+ChatbotWidget.open();         // Open chat window
+ChatbotWidget.close();        // Close chat window
+ChatbotWidget.toggle();       // Toggle open/close
+ChatbotWidget.startNewChat(); // Clear session and start new chat
+ChatbotWidget.update(config); // Update widget configuration
+ChatbotWidget.destroy();      // Remove widget completely
 ```
 
 ## Embedded Mode
 
-By default, the widget displays as a floating button that opens a popup. You can also embed the chat directly inside any container on your page.
+By default, the widget is embedded inside a container element. You can enable floating mode for a FAB button popup.
 
 ### Using containerSelector
 
@@ -351,6 +306,48 @@ class ChatViewController: UIViewController {
 }
 ```
 
+### iOS (Objective-C)
+```objc
+#import <UIKit/UIKit.h>
+#import <WebKit/WebKit.h>
+
+@interface ChatViewController : UIViewController
+@property (nonatomic, strong) WKWebView *webView;
+@end
+
+@implementation ChatViewController
+
+- (void)viewDidLoad {
+    [super viewDidLoad];
+
+    WKWebViewConfiguration *config = [[WKWebViewConfiguration alloc] init];
+    config.preferences.javaScriptEnabled = YES;
+
+    self.webView = [[WKWebView alloc] initWithFrame:self.view.bounds configuration:config];
+    self.webView.autoresizingMask = UIViewAutoresizingFlexibleWidth | UIViewAutoresizingFlexibleHeight;
+    [self.view addSubview:self.webView];
+
+    NSString *html = @"<!DOCTYPE html>"
+        "<html>"
+        "<head>"
+        "<meta name='viewport' content='width=device-width, initial-scale=1, maximum-scale=1'>"
+        "<style>body { margin: 0; padding: 0; }</style>"
+        "</head>"
+        "<body>"
+        "<script src='https://unpkg.com/@mypatientspace/chatbot-widget@latest/dist/mypatientspace-widget.umd.js'></script>"
+        "<script>"
+        "ChatbotWidget.init({ apiEndpoint: 'https://your-api.com/chat' });"
+        "ChatbotWidget.open();"
+        "</script>"
+        "</body>"
+        "</html>";
+
+    [self.webView loadHTMLString:html baseURL:[NSURL URLWithString:@"https://your-domain.com"]];
+}
+
+@end
+```
+
 ### React Native
 ```jsx
 import { WebView } from 'react-native-webview';
@@ -388,27 +385,32 @@ const ChatScreen = () => {
 
 ### All Options
 
-| Option | Type | Required | Description |
-|--------|------|----------|-------------|
-| `apiEndpoint` | `string` | No | Chat API endpoint URL (widget offline if not set) |
-| `token` | `string` | No | Auth token for API requests |
-| `sessionId` | `string` | No | Existing session ID to resume |
-| `assistantId` | `string` | No | Specific assistant ID to use |
-| `contextPatientId` | `string` | No | Patient context for the chat |
-| `loadHistory` | `boolean` | No | Load previous chat history (default: true) |
-| `colorMode` | `'light' \| 'dark' \| 'system'` | No | Color mode for the widget (default: 'light') |
-| `theme` | `ThemeConfig` | No | Custom theme (see Theme Configuration below) |
-| `position` | `'bottom-right' \| 'bottom-left'` | No | FAB button position |
-| `containerSelector` | `string` | No | CSS selector for embedded container |
-| `floatingMode` | `boolean` | No | Show FAB button and floating chat (default: false) |
-| `greeting` | `string` | No | Initial bot greeting message |
-| `placeholder` | `string` | No | Input field placeholder text |
-| `headerTitle` | `string` | No | Chat window header title |
-| `headerSubtitle` | `string` | No | Chat window header subtitle |
-| `headerIcon` | `string` | No | Header icon image URL |
-| `fabIcon` | `string` | No | FAB button image URL |
-| `brandingText` | `string` | No | Footer branding text |
-| `quickActions` | `string[]` | No | Predefined quick action buttons (displayed as labels and sent as messages) |
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `apiEndpoint` | `string` | - | Chat API endpoint URL (widget offline if not set) |
+| `token` | `string` | - | Auth token for API requests |
+| `sessionId` | `string` | - | Existing session ID to resume |
+| `assistantId` | `string` | - | Specific assistant ID to use |
+| `contextPatientId` | `string` | - | Patient context for the chat |
+| `loadHistory` | `boolean` | `true` | Load previous chat history |
+| `colorMode` | `'light' \| 'dark' \| 'system'` | `'light'` | Color mode for the widget |
+| `theme` | `ThemeConfig` | - | Custom theme colors, fonts, border radius, shadow |
+| `position` | `'bottom-right' \| 'bottom-left'` | `'bottom-right'` | FAB button position |
+| `containerSelector` | `string` | - | CSS selector for embedded container |
+| `floatingMode` | `boolean` | `false` | Show FAB button and floating chat |
+| `hideExpandButton` | `boolean` | `false` | Hide the expand/minimize button from header |
+| `showCloseSlot` | `boolean` | `false` | Show empty circle placeholder for custom close button |
+| `greeting` | `string` | From API | Initial bot greeting message |
+| `placeholder` | `string` | From API | Input field placeholder text |
+| `headerTitle` | `string` | From API | Chat window header title |
+| `headerSubtitle` | `string` | From API | Chat window header subtitle |
+| `headerIcon` | `string` | From API | Header icon image URL |
+| `fabIcon` | `string` | From API | FAB button image URL |
+| `brandingText` | `string` | From API | Footer branding text |
+| `disclaimerText` | `string` | From API | Disclaimer text below input area |
+| `quickActions` | `string[]` | From API | Predefined quick action buttons |
+
+> **Note:** Content fields (`greeting`, `headerTitle`, `placeholder`, `brandingText`, `headerIcon`, `fabIcon`, `quickActions`, `disclaimerText`) are loaded from the assistant's API configuration by default. Setting them in the widget config overrides the API values.
 
 ### Callbacks
 
@@ -420,35 +422,14 @@ const ChatScreen = () => {
 | `onMessageReceived` | `(message: Message)` | Called after bot response completes |
 | `onQuickAction` | `(action: string)` | Called when quick action is clicked |
 | `onStreamChunk` | `(chunk: string)` | Called for each streamed response chunk |
-
-### Message Interface
-
-```typescript
-interface Message {
-  id: string;
-  content: string;
-  sender: 'user' | 'bot';
-  timestamp: Date;
-  status: 'sending' | 'sent' | 'error';
-  audioUrl?: string;  // Base64 audio data URL for TTS playback
-}
-```
-
-### ThemeConfig Interface
-
-```typescript
-interface ThemeConfig {
-  colors?: Partial<ThemeColors>;  // Any subset of theme colors
-  fontFamily?: string;
-  borderRadius?: string;
-  shadow?: string;
-}
-```
+| `onCitationClick` | `(citation: Citation)` | Called when a content card is clicked |
+| `onNewChat` | `()` | Called when user starts a new chat |
+| `onWidgetReady` | `(api: WidgetApi)` | Called when widget is ready with API methods |
 
 ### Available Theme Colors
 
-| Color | Default | Description |
-|-------|---------|-------------|
+| Color | Light Default | Description |
+|-------|---------------|-------------|
 | `primary` | `#00c2d1` | FAB button, links, main accent |
 | `primaryDark` | `#017992` | Hover states |
 | `secondary` | `#3c4d73` | Header background |
@@ -467,25 +448,27 @@ interface ThemeConfig {
 | `border` | `#d1d5db` | Border color |
 | `borderLight` | `#e5e7eb` | Light border |
 | `error` | `#ef4444` | Error states |
+| `errorBackground` | `#fef2f2` | Error background |
 | `white` | `#ffffff` | White color |
 | `recording` | `#ef4444` | Voice recording indicator |
+| `headerText` | `#ffffff` | Header text and icon color |
+| `scrollbarThumb` | `rgba(60, 77, 115, 0.2)` | Scrollbar thumb color |
+| `scrollbarThumbHover` | `rgba(60, 77, 115, 0.3)` | Scrollbar thumb hover |
+
+### Default Fallback Values
 
-## Default Values
+Content fields are resolved with this priority: **Config > Assistant API > Component default**
 
-| Option | Default Value |
-|--------|---------------|
+| Field | Component Fallback |
+|-------|-------------------|
 | `headerTitle` | "AI Doctor" |
 | `greeting` | "Hello! Welcome to our healthcare support. How can I assist you today?" |
 | `placeholder` | "Type a message..." |
 | `brandingText` | "Developed by myPatientSpace" |
-| `headerIcon` | https://web.mypatientspace.com/img/logo-symbol.png |
-| `fabIcon` | https://web.mypatientspace.com/img/logo-symbol.png |
-| `position` | "bottom-right" |
-| `colorMode` | "light" |
-| `loadHistory` | true |
-| `containerSelector` | undefined (creates container in body) |
-| `floatingMode` | false (embedded is default) |
-| `quickActions` | Book Appointment, Hours, Contact, Location |
+| `disclaimerText` | "AI can make mistakes. Verify important information." |
+| `headerIcon` | MPS logo |
+| `fabIcon` | MPS logo |
+| `quickActions` | Empty (from API only) |
 
 ## License