@developer.notchatbot/webchat 1.2.1 → 1.2.3

package/README.md

@@ -1,6 +1,6 @@
 # 🔷 WebChat Widget
 
-A beautiful, embeddable chatbot widget built with **React**, **TypeScript**, **Vite**, **pnpm** and **Tailwind CSS** that can be easily integrated into any website with **just one file**.
+A beautiful, embeddable chatbot widget built with **React**, **TypeScript**, **Vite**, **pnpm**, and **Tailwind CSS** that can be easily integrated into any website with **just one file**.
 
 ## ✨ Features
 
@@ -64,14 +64,17 @@ interface WebChatPositionConfig {
   marginBottom?: number;
   marginSide?: number;
 }
+```
 
+Example:
+```js
 WebChat.initialize({
     title: "Chat Assistant",
     placeholder: "Type your message...",
     primaryColor: "#007bff",
     apiKey: "your-chatbot-uid",        // Chatbot UID from admin panel
     position: "bottom-right",
-    initialMessage: "¡Hola! 👋 Soy tu asistente virtual. ¿En qué puedo ayudarte hoy?",
+    initialMessage: "Hi! 👋 I'm your virtual assistant. How can I help you today?",
     closeButtonIcon: "default", // or "text" or "custom"
     marginBottom: 20,           // Distance from bottom edge (default: 16px)
     marginSide: 20,             // Distance from side edge (default: 16px)
@@ -88,7 +91,8 @@ WebChat.initialize({
     }
 });
 ```
-# 💬 EmbedChat - Chat Embebido
+
+# 💬 EmbedChat - Embedded Chat
 
 EmbedChat allows you to integrate a complete chat system directly into any element of your web page, with full control over size, position, and style.
 
@@ -132,19 +136,19 @@ const chatInstance = EmbedChatAPI.initialize({
 EmbedChatAPI.initialize({
   // REQUIRED
   elementId: "my-chat-embed",              // ID of the HTML element to embed the chat
-  apiKey: "your-api-key",              // API key of the service
+  apiKey: "your-api-key",                  // API key of the service
 })
 ```
 
-### Propiedades de Contenido
+### Content Properties
 ```javascript
 EmbedChatAPI.initialize({
-  // Textos y contenido
+  // Texts and content
   title: "Chat Assistant",        // Title shown in the header
-  placeholder: "Type your message...",    // Text placeholder of the input
+  placeholder: "Type your message...",    // Input placeholder text
   initialMessage: "Hello! 👋 I'm your chat assistant. How can I help you today?", // First message from the bot
-  footerText: "Powered by NotChatBot", // Text of the footer (optional)
-  avatar: "https://example.com/avatar.jpg", // URL of the bot's avatar
+  footerText: "Powered by NotChatBot", // Footer text (optional)
+  avatar: "https://example.com/avatar.jpg", // Bot avatar URL
 })
 ```
 
@@ -166,19 +170,19 @@ EmbedChatAPI.initialize({
 ### Appearance Properties
 ```javascript
 EmbedChatAPI.initialize({
-  // Colores
+  // Colors
   primaryColor: "#3b82f6",           // Primary color (header, buttons, etc.)
-  textColor: "#333333",              // Color of the text of the messages
-  bubbleUserColor: "#3b82f6",        // Color of the background of the user's messages
-  chatBackground: "#ffffff",         // Color of the chat background
-  footerColor: "#f3f4f6",            // Color of the footer background
+  textColor: "#333333",              // Message text color
+  bubbleUserColor: "#3b82f6",        // User message bubble background
+  chatBackground: "#ffffff",         // Chat background color
+  footerColor: "#f3f4f6",            // Footer background color
   
   // Borders
   borderRadius: 12,                  // Border radius: number (px) or string
   border: "2px solid #3b82f6",       // Custom border (CSS border)
   boxShadow: "0 10px 30px rgba(0,0,0,0.2)", // Custom shadow
   
-  chatTransparent: false,            // If true, the chat background is transparent
+  chatTransparent: false,            // If true, chat background is transparent
 })
 ```
 
@@ -194,10 +198,10 @@ EmbedChatAPI.initialize({
 ```javascript
 EmbedChatAPI.initialize({
   input: {
-    backgroundColor: "#ffffff",      // Color of the input area background
-    inputBorder: "2px solid #e5e7eb", // Border of the input field
-    inputBorderRadius: "8px",        // Border radius of the input
-    iconColor: "#3b82f6"             // Color of the send icon
+    backgroundColor: "#ffffff",      // Input area background color
+    inputBorder: "2px solid #e5e7eb", // Input field border
+    inputBorderRadius: "8px",        // Input border radius
+    iconColor: "#3b82f6"             // Send icon color
   }
 })
 ```
@@ -268,27 +272,199 @@ EmbedChatAPI.initialize({
 |-----------|------|-----------|---------|-------------|
 | `elementId` | `string` | ✅ | - | ID of the HTML element where the chat will be mounted |
 | `apiKey` | `string` | ✅ | - | API key for the chat service |
-| `title` | `string` | ❌ | `"Chat"` | Title shown in the header of the chat |
-| `placeholder` | `string` | ❌ | `"Type your message..."` | Text placeholder of the input field |
+| `title` | `string` | ❌ | `"Chat"` | Title shown in the chat header |
+| `placeholder` | `string` | ❌ | `"Type your message..."` | Input field placeholder text |
 | `primaryColor` | `string` | ❌ | `"#3b82f6"` | Primary color (header, buttons, links) |
-| `avatar` | `string` | ❌ | - | URL of the bot's avatar (optional) |
+| `avatar` | `string` | ❌ | - | Bot avatar URL (optional) |
 | `initialMessage` | `string` | ❌ | - | First message shown by the bot |
-| `footerText` | `string` | ❌ | - | Text of the footer (if provided, it is shown) |
-| `width` | `string \| number` | ❌ | `"100%"` | Width of the chat (px or CSS units) |
-| `height` | `string \| number` | ❌ | `400` | Height of the chat (px or CSS units) |
-| `maxWidth` | `string \| number` | ❌ | `"100%"` | Maximum width of the chat |
-| `maxHeight` | `string \| number` | ❌ | `"100vh"` | Maximum height of the chat |
-| `minWidth` | `string \| number` | ❌ | `280` | Minimum width of the chat |
-| `minHeight` | `string \| number` | ❌ | `300` | Minimum height of the chat |
+| `footerText` | `string` | ❌ | - | Footer text (if provided, it is shown) |
+| `width` | `string \| number` | ❌ | `"100%"` | Chat width (px or CSS units) |
+| `height` | `string \| number` | ❌ | `400` | Chat height (px or CSS units) |
+| `maxWidth` | `string \| number` | ❌ | `"100%"` | Maximum chat width |
+| `maxHeight` | `string \| number` | ❌ | `"100vh"` | Maximum chat height |
+| `minWidth` | `string \| number` | ❌ | `280` | Minimum chat width |
+| `minHeight` | `string \| number` | ❌ | `300` | Minimum chat height |
 | `showHeader` | `boolean` | ❌ | `true` | Show/hide the header |
 | `showFooter` | `boolean` | ❌ | `true` | Show/hide the footer (if footerText is provided) |
-| `borderRadius` | `string \| number` | ❌ | `12` | Border radius of the container |
-| `border` | `string` | ❌ | `"1px solid #e5e7eb"` | Border of the container (CSS border) |
-| `boxShadow` | `string` | ❌ | `"0 10px 25px..."` | Shadow of the container |
-| `chatTransparent` | `boolean` | ❌ | `false` | If true, the chat background is transparent |
-| `chatBackground` | `string` | ❌ | `"#ffffff"` | Color of the chat background |
-| `textColor` | `string` | ❌ | - | Color of the text of the messages |
-| `bubbleUserColor` | `string` | ❌ | - | Color of the background of the user's messages |
-| `footerColor` | `string` | ❌ | - | Color of the footer background |
-| `input` | `EmbedChatInputConfig` | ❌ | - | Specific configuration of the input |
+| `borderRadius` | `string \| number` | ❌ | `12` | Container border radius |
+| `border` | `string` | ❌ | `"1px solid #e5e7eb"` | Container border (CSS border) |
+| `boxShadow` | `string` | ❌ | `"0 10px 25px..."` | Container shadow |
+| `chatTransparent` | `boolean` | ❌ | `false` | If true, chat background is transparent |
+| `chatBackground` | `string` | ❌ | `"#ffffff"` | Chat background color |
+| `textColor` | `string` | ❌ | - | Message text color |
+| `bubbleUserColor` | `string` | ❌ | - | User message bubble background color |
+| `footerColor` | `string` | ❌ | - | Footer background color |
+| `input` | `EmbedChatInputConfig` | ❌ | - | Input-specific configuration |
 | `customCSS` | `string` | ❌ | - | Custom CSS for the chat |
+
+---
+
+## 🛠️ Dynamic Control via API and Events
+
+WebChat exposes a global API and custom events to dynamically control the position, padding, and visibility of the widget from anywhere in your app or from the browser console.
+
+### WebChat Global Methods
+
+```js
+window.openWebChat();           // Open the floating chat
+window.closeWebChat();          // Close the floating chat
+window.toggleWebChat();         // Toggle open/close
+window.unmountWebChat();        // Unmount the floating chat
+window.mountWebChat();          // Mount the floating chat if it was unmounted
+window.hideWebChat();           // Hide the chat (display: none)
+window.showWebChat();           // Show the chat if it was hidden
+window.injectWebChatCSS(css);   // Inject custom CSS into the shadow DOM
+window.removeWebChatCSS();      // Remove custom CSS
+window.setWebChatPosition(obj); // Change position/padding dynamically
+```
+
+### EmbedChat Global Methods
+
+```js
+window.unmountEmbedChat(elementId); // Unmount the EmbedChat instance for the given elementId
+window.mountEmbedChat(elementId);   // Mount the EmbedChat instance again (with the last used config)
+```
+
+- `window.unmountEmbedChat(elementId)`: Unmounts the EmbedChat instance from the specified element. The last configuration is saved.
+- `window.mountEmbedChat(elementId)`: Remounts the EmbedChat instance in the specified element using the last configuration used for that element. If no config was previously used, a warning is shown in the console.
+
+#### Example
+
+```js
+window.unmountEmbedChat('embed-small'); // Unmounts the chat from the element with id 'embed-small'
+window.mountEmbedChat('embed-small');   // Remounts the chat in the same element with the last config
+```
+
+---
+
+### Change position and padding dynamically (WebChat)
+
+#### 1. Change position and margin globally (flat)
+```js
+window.setWebChatPosition({
+  position: 'bottom-left',
+  marginBottom: 40,
+  marginSide: 30
+});
+```
+
+#### 2. Change only for mobile
+```js
+window.setWebChatPosition({
+  mobile: {
+    position: 'bottom-right',
+    marginBottom: 100,
+    marginSide: 20
+  }
+});
+```
+
+#### 3. Change only for desktop
+```js
+window.setWebChatPosition({
+  desktop: {
+    position: 'bottom-left',
+    marginBottom: 60,
+    marginSide: 40
+  }
+});
+```
+
+#### 4. Change using device format
+```js
+window.setWebChatPosition({
+  device: 'mobile',
+  marginBottom: 120,
+  marginSide: 15
+});
+```
+
+### Use custom events (addCustomPadding and open/close control)
+
+You can dispatch events to change padding/margin or open/close the chat from anywhere in your app:
+
+#### 1. Open, close, or toggle the floating WebChat
+```js
+window.dispatchEvent(new CustomEvent('openWebChatbot'));
+window.dispatchEvent(new CustomEvent('closeWebChatbot'));
+window.dispatchEvent(new CustomEvent('toggleWebChatbot'));
+```
+
+#### 2. Change padding for both devices (flat)
+```js
+window.dispatchEvent(new CustomEvent('addCustomPadding', { detail: { y: 100, x: 30 } }));
+```
+
+#### 3. Change only for mobile
+```js
+window.dispatchEvent(new CustomEvent('addCustomPadding', { detail: { device: 'mobile', marginBottom: 120, marginSide: 20 } }));
+```
+
+#### 4. Change only for desktop
+```js
+window.dispatchEvent(new CustomEvent('addCustomPadding', { detail: { device: 'desktop', marginBottom: 60, marginSide: 40 } }));
+```
+
+#### 5. Change using nested object
+```js
+window.dispatchEvent(new CustomEvent('addCustomPadding', { detail: {
+  mobile: { marginBottom: 90, marginSide: 10 },
+  desktop: { marginBottom: 50, marginSide: 30 }
+}}));
+```
+
+### Accepted object formats
+
+- **Flat:** `{ marginBottom, marginSide, position }` (applies to both if no override in mobile/desktop)
+- **By device:** `{ device: 'mobile'|'desktop', marginBottom, marginSide }`
+- **Nested:** `{ mobile: { ... }, desktop: { ... } }`
+- **Alias:** `{ y, x }` (`y` → marginBottom, `x` → marginSide)
+
+You can combine these formats as needed.
+
+### Inject and remove custom CSS in WebChat
+
+You can inject hot CSS into the floating WebChat using the global API:
+
+```js
+// Change the header background color
+window.injectWebChatCSS(`
+  #notchatbot-webchat-header {
+    background: #111 !important;
+    color: #fff !important;
+  }
+`);
+
+// Hide the floating button
+window.injectWebChatCSS(`#notchatbot-webchat-button { display: none !important; }`);
+
+// Change the chat window width
+window.injectWebChatCSS(`#notchatbot-webchat-window { width: 500px !important; }`);
+
+// Change the floating button color
+window.injectWebChatCSS(`#notchatbot-webchat-button { background: #f59e0b !important; }`);
+
+// Remove all custom styles
+window.removeWebChatCSS();
+```
+
+#### Internal element IDs for WebChat
+
+You can use these IDs to select and style specific parts of the widget:
+
+- `#notchatbot-webchat-button` — Floating chat button
+- `#notchatbot-webchat-header` — Chat window header
+- `#notchatbot-webchat-window` — Main chat window
+
+Example to change the header and button color:
+
+```js
+window.injectWebChatCSS(`
+  #notchatbot-webchat-header { background: #222 !important; color: #fff !important; }
+  #notchatbot-webchat-button { background: #f59e0b !important; }
+`);
+```
+
+You can combine these selectors to fully customize the widget.
+
+---

package/dist/components/ChatBot.d.ts

@@ -1,4 +1,6 @@
 import { default as React } from 'react';
 import { ChatBotProps } from '../types';
-declare const ChatBot: React.FC<ChatBotProps>;
+declare const ChatBot: React.FC<ChatBotProps & {
+    exposeControl?: (api: any) => void;
+}>;
 export default ChatBot;

package/dist/types.d.ts

@@ -85,9 +85,9 @@ export interface EmbedChatFooterProps {
 }
 export interface EmbedChatInstance {
     destroy: () => void;
-    updateConfig: (newConfig: Partial<EmbedChatConfig>) => void;
-    injectCSS: (css: string) => void;
-    removeCustomCSS: () => void;
+    updateConfig?: (newConfig: Partial<EmbedChatConfig>) => void;
+    injectCSS?: (css: string) => void;
+    removeCustomCSS?: () => void;
 }
 export interface Message {
     id: string;
@@ -177,6 +177,13 @@ export interface WebChatInstance {
     root: any;
     destroy: () => void;
     getConversationId: () => string | null;
+    setIsOpen?: (open: boolean) => void;
+    updateConfig?: (newConfig: Partial<WebChatConfig>) => void;
+    setPosition?: (pos: Partial<WebChatConfig>) => void;
+    hide?: () => void;
+    show?: () => void;
+    injectCSS?: (css: string) => void;
+    removeCustomCSS?: () => void;
 }
 export interface WebChatAPI {
     initialize: (config?: Partial<WebChatConfig>) => WebChatInstance | null;