nerdagent-chat-widget-vue 1.0.2 → 1.0.3

package/README.md

@@ -1,211 +1,484 @@
-# @nerdagent/chat-widget-vue
+# NerdAgent Chat Widget for Vue
 
-Vue wrapper for the NerdAgent Chat Widget built with Stencil.
+A powerful, customizable chat widget component for Vue applications. Built with Stencil.js for maximum compatibility and performance.
+
+## Features
+
+- 🚀 **Framework Agnostic Core** - Built with Stencil.js Web Components
+- 🎨 **Highly Customizable** - Colors, positioning, features, and more
+- 📱 **Responsive Design** - Works on desktop and mobile
+- 🔧 **TypeScript Support** - Full type definitions included
+- ⚡ **Lightweight** - Minimal bundle size impact
+- 🎯 **Easy Integration** - Simple Vue component wrapper
 
 ## Installation
 
 ```bash
-npm install @nerdagent/chat-widget-vue
+npm install nerdagent-chat-widget-vue
 ```
 
-## Usage
-
-### Option 1: Component Registration (Recommended)
-
-```typescript
-// main.ts
-import { createApp } from 'vue';
-import App from './App.vue';
-import { NerdChatWidget } from '@nerdagent/chat-widget-vue';
-
-const app = createApp(App);
-
-// Register component globally
-app.component('NerdChatWidget', NerdChatWidget);
+## Quick Start
 
-app.mount('#app');
-```
+### 1. Import the Component
 
 ```vue
-<!-- App.vue -->
 <template>
-  <div id="app">
+  <div class="app">
     <NerdChatWidget
-      agent-name="Support Agent"
-      agent-role="Customer Support"
-      primary-color="#2d3e50"
-      accent-color="#4e8cff"
-      welcome-message="Hi! How can I help?"
-      position="bottom-right"
-      width="350"
-      height="500"
+      :agent-name="'Support Agent'"
+      :agent-role="'Customer Support'"
+      :primary-color="'#2d3e50'"
+      :accent-color="'#4e8cff'"
+      :welcome-message="'Hi! How can I help you today?'"
+      :position="'bottom-right'"
+      :width="'350'"
+      :height="'500'"
       :show-minimize-button="true"
       :show-timestamps="true"
       :enable-file-upload="false"
       :enable-speech="false"
       :show-powered-by="true"
-      @messageSent="handleMessageSent"
-      @widgetOpened="handleWidgetOpened"
-      @widgetClosed="handleWidgetClosed"
+      @message-sent="onMessageSent"
+      @widget-opened="onWidgetOpened"
+      @widget-closed="onWidgetClosed"
     />
   </div>
 </template>
 
-<script setup lang="ts">
-const handleMessageSent = (event: { message: string; timestamp: Date }) => {
-  console.log('Message sent:', event);
-};
-
-const handleWidgetOpened = () => {
-  console.log('Widget opened');
-};
-
-const handleWidgetClosed = () => {
-  console.log('Widget closed');
-};
+<script>
+import { NerdChatWidget } from 'nerdagent-chat-widget-vue';
+
+export default {
+  name: 'App',
+  components: {
+    NerdChatWidget
+  },
+  methods: {
+    onMessageSent(event) {
+      console.log('Message sent:', event);
+    },
+    onWidgetOpened() {
+      console.log('Widget opened');
+    },
+    onWidgetClosed() {
+      console.log('Widget closed');
+    }
+  }
+}
 </script>
 ```
 
-### Option 2: Plugin Registration
-
-```typescript
-// main.ts
-import { createApp } from 'vue';
-import App from './App.vue';
-import { NerdChatWidgetPlugin } from '@nerdagent/chat-widget-vue';
-
-const app = createApp(App);
-
-// Use as plugin
-app.use(NerdChatWidgetPlugin);
-
-app.mount('#app');
-```
-
-### Option 3: Local Component Registration
+### 2. With Composition API (Vue 3)
 
 ```vue
 <template>
-  <div>
+  <div class="app">
     <NerdChatWidget
-      agent-name="Support Agent"
-      @messageSent="handleMessageSent"
+      :agent-name="config.agentName"
+      :agent-role="config.agentRole"
+      :primary-color="config.primaryColor"
+      :accent-color="config.accentColor"
+      :welcome-message="config.welcomeMessage"
+      :position="config.position"
+      :width="config.width"
+      :height="config.height"
+      :show-minimize-button="config.showMinimizeButton"
+      :show-timestamps="config.showTimestamps"
+      :enable-file-upload="config.enableFileUpload"
+      :enable-speech="config.enableSpeech"
+      :show-powered-by="config.showPoweredBy"
+      @message-sent="handleMessageSent"
+      @widget-opened="handleWidgetOpened"
+      @widget-closed="handleWidgetClosed"
     />
   </div>
 </template>
 
-<script setup lang="ts">
-import { NerdChatWidget } from '@nerdagent/chat-widget-vue';
+<script setup>
+import { ref, reactive } from 'vue';
+import { NerdChatWidget } from 'nerdagent-chat-widget-vue';
 
-const handleMessageSent = (event: { message: string; timestamp: Date }) => {
+const config = reactive({
+  agentName: 'Support Agent',
+  agentRole: 'Customer Support',
+  primaryColor: '#2d3e50',
+  accentColor: '#4e8cff',
+  welcomeMessage: 'Hi! How can I help you today?',
+  placeholderText: 'Type your message...',
+  position: 'bottom-right',
+  width: '350',
+  height: '500',
+  showMinimizeButton: true,
+  showTimestamps: true,
+  enableFileUpload: false,
+  enableSpeech: false,
+  showPoweredBy: true
+});
+
+const messages = ref([]);
+
+const handleMessageSent = (event) => {
+  messages.value.push(event);
   console.log('Message sent:', event);
 };
+
+const handleWidgetOpened = () => {
+  console.log('Widget opened');
+};
+
+const handleWidgetClosed = () => {
+  console.log('Widget closed');
+};
 </script>
 ```
 
-### With Composition API
+### 3. With TypeScript
 
 ```vue
 <template>
-  <div>
+  <div class="app">
     <NerdChatWidget
       :agent-name="config.agentName"
+      :agent-role="config.agentRole"
       :primary-color="config.primaryColor"
+      :accent-color="config.accentColor"
+      :welcome-message="config.welcomeMessage"
       :position="config.position"
-      @messageSent="onMessageSent"
-      @widgetOpened="onWidgetOpened"
-      @widgetClosed="onWidgetClosed"
+      :width="config.width"
+      :height="config.height"
+      :show-minimize-button="config.showMinimizeButton"
+      :show-timestamps="config.showTimestamps"
+      :enable-file-upload="config.enableFileUpload"
+      :enable-speech="config.enableSpeech"
+      :show-powered-by="config.showPoweredBy"
+      @message-sent="handleMessageSent"
+      @widget-opened="handleWidgetOpened"
+      @widget-closed="handleWidgetClosed"
     />
   </div>
 </template>
 
 <script setup lang="ts">
-import { ref } from 'vue';
-import { NerdChatWidget, WidgetPosition } from '@nerdagent/chat-widget-vue';
+import { ref, reactive } from 'vue';
+import { NerdChatWidget, WidgetPosition } from 'nerdagent-chat-widget-vue';
 
-interface Config {
+interface ChatConfig {
   agentName: string;
+  agentRole: string;
   primaryColor: string;
+  accentColor: string;
+  welcomeMessage: string;
+  placeholderText: string;
   position: WidgetPosition;
+  width: string;
+  height: string;
+  showMinimizeButton: boolean;
+  showTimestamps: boolean;
+  enableFileUpload: boolean;
+  enableSpeech: boolean;
+  showPoweredBy: boolean;
 }
 
-const config = ref<Config>({
+const config = reactive<ChatConfig>({
   agentName: 'Support Agent',
+  agentRole: 'Customer Support',
   primaryColor: '#2d3e50',
-  position: 'bottom-right'
+  accentColor: '#4e8cff',
+  welcomeMessage: 'Hi! How can I help you today?',
+  placeholderText: 'Type your message...',
+  position: 'bottom-right',
+  width: '350',
+  height: '500',
+  showMinimizeButton: true,
+  showTimestamps: true,
+  enableFileUpload: false,
+  enableSpeech: false,
+  showPoweredBy: true
 });
 
-const onMessageSent = (event: { message: string; timestamp: Date }) => {
+const messages = ref<Array<{ message: string; timestamp: Date }>>([]);
+
+const handleMessageSent = (event: { message: string; timestamp: Date }) => {
+  messages.value.push(event);
   console.log('Message sent:', event);
 };
 
-const onWidgetOpened = () => {
+const handleWidgetOpened = () => {
   console.log('Widget opened');
 };
 
-const onWidgetClosed = () => {
+const handleWidgetClosed = () => {
   console.log('Widget closed');
 };
 </script>
 ```
 
-### Vite Configuration
-
-If you're using Vite, you may need to configure it to recognize the custom elements:
-
-```javascript
-// vite.config.js
-import { defineConfig } from 'vite'
-import vue from '@vitejs/plugin-vue'
-
-export default defineConfig({
-  plugins: [
-    vue({
-      template: {
-        compilerOptions: {
-          isCustomElement: (tag) => tag.startsWith('nerd-')
-        }
-      }
-    })
-  ]
-})
-```
-
-## API
+## Configuration Options
 
 ### Props
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| `agentName` | `string` | `'Support Agent'` | Name of the chat agent |
+| `agentName` | `string` | `'Support Agent'` | Name of the support agent |
 | `agentRole` | `string` | `'Customer Support'` | Role/title of the agent |
-| `primaryColor` | `string` | `'#2d3e50'` | Primary theme color |
-| `accentColor` | `string` | `'#4e8cff'` | Accent color for buttons |
-| `welcomeMessage` | `string` | `'Hi! How can I help?'` | Initial message from agent |
+| `primaryColor` | `string` | `'#2d3e50'` | Primary color theme |
+| `accentColor` | `string` | `'#4e8cff'` | Accent color theme |
+| `welcomeMessage` | `string` | `'Hi! How can I help?'` | Initial welcome message |
 | `placeholderText` | `string` | `'Type your message...'` | Input placeholder text |
-| `position` | `WidgetPosition` | `'bottom-right'` | Widget position |
+| `position` | `WidgetPosition` | `'bottom-right'` | Widget position on screen |
 | `width` | `string` | `'350'` | Widget width in pixels |
 | `height` | `string` | `'500'` | Widget height in pixels |
-| `showMinimizeButton` | `boolean` | `true` | Show/hide minimize button |
-| `showTimestamps` | `boolean` | `true` | Show/hide message timestamps |
+| `showMinimizeButton` | `boolean` | `true` | Show minimize/maximize button |
+| `showTimestamps` | `boolean` | `true` | Show message timestamps |
 | `enableFileUpload` | `boolean` | `false` | Enable file upload feature |
-| `enableSpeech` | `boolean` | `false` | Enable speech input |
-| `showPoweredBy` | `boolean` | `true` | Show/hide "Powered by" footer |
+| `enableSpeech` | `boolean` | `false` | Enable speech recognition |
+| `showPoweredBy` | `boolean` | `true` | Show "Powered by" branding |
+
+### WidgetPosition Type
+
+```typescript
+type WidgetPosition = 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
+```
 
 ### Events
 
-| Event | Payload | Description |
-|-------|---------|-------------|
-| `messageSent` | `{ message: string; timestamp: Date }` | Emitted when a message is sent |
-| `widgetOpened` | `void` | Emitted when the widget is opened |
-| `widgetClosed` | `void` | Emitted when the widget is closed |
+| Event | Type | Description |
+|-------|------|-------------|
+| `message-sent` | `{ message: string; timestamp: Date }` | Emitted when user sends a message |
+| `widget-opened` | `void` | Emitted when widget is opened |
+| `widget-closed` | `void` | Emitted when widget is closed |
+
+## Advanced Usage
+
+### Dynamic Configuration
+
+```vue
+<template>
+  <div>
+    <button @click="updateConfig">Update Config</button>
+    <NerdChatWidget
+      :agent-name="config.agentName"
+      :primary-color="config.primaryColor"
+      :position="config.position"
+      @message-sent="handleMessageSent"
+    />
+  </div>
+</template>
+
+<script setup>
+import { reactive } from 'vue';
+import { NerdChatWidget } from 'nerdagent-chat-widget-vue';
+
+const config = reactive({
+  agentName: 'Support Agent',
+  primaryColor: '#2d3e50',
+  position: 'bottom-right',
+  // ... other config
+});
+
+const updateConfig = () => {
+  config.primaryColor = '#ff6b6b';
+  config.position = 'top-right';
+  config.agentName = 'Updated Agent';
+};
+</script>
+```
+
+### Conditional Rendering
+
+```vue
+<template>
+  <div>
+    <button @click="toggleWidget">
+      {{ showWidget ? 'Hide' : 'Show' }} Chat Widget
+    </button>
+
+    <NerdChatWidget
+      v-if="showWidget"
+      :agent-name="userType === 'premium' ? 'Premium Support' : 'Basic Support'"
+      :agent-role="userType === 'premium' ? 'VIP Assistant' : 'Support Agent'"
+      :primary-color="userType === 'premium' ? '#gold' : '#2d3e50'"
+      :enable-file-upload="userType === 'premium'"
+      :enable-speech="userType === 'premium'"
+      @message-sent="handleMessageSent"
+    />
+  </div>
+</template>
+
+<script setup>
+import { ref } from 'vue';
+import { NerdChatWidget } from 'nerdagent-chat-widget-vue';
+
+const showWidget = ref(false);
+const userType = ref('guest');
+
+const toggleWidget = () => {
+  showWidget.value = !showWidget.value;
+};
+
+const handleMessageSent = (event) => {
+  if (userType.value === 'premium') {
+    // Premium user handling
+  } else {
+    // Basic user handling
+  }
+};
+</script>
+```
+
+### With Pinia Store
+
+```vue
+<template>
+  <div>
+    <NerdChatWidget
+      :agent-name="chatStore.config.agentName"
+      :agent-role="chatStore.config.agentRole"
+      :primary-color="chatStore.config.primaryColor"
+      @message-sent="chatStore.addMessage"
+      @widget-opened="chatStore.setWidgetOpen"
+      @widget-closed="chatStore.setWidgetClosed"
+    />
+  </div>
+</template>
+
+<script setup>
+import { useChatStore } from '@/stores/chat';
+import { NerdChatWidget } from 'nerdagent-chat-widget-vue';
+
+const chatStore = useChatStore();
+</script>
+```
+
+### With Vuex
+
+```vue
+<template>
+  <div>
+    <NerdChatWidget
+      :agent-name="$store.state.chat.config.agentName"
+      :agent-role="$store.state.chat.config.agentRole"
+      :primary-color="$store.state.chat.config.primaryColor"
+      @message-sent="handleMessageSent"
+      @widget-opened="handleWidgetOpened"
+      @widget-closed="handleWidgetClosed"
+    />
+  </div>
+</template>
+
+<script>
+import { mapActions } from 'vuex';
+import { NerdChatWidget } from 'nerdagent-chat-widget-vue';
+
+export default {
+  components: {
+    NerdChatWidget
+  },
+  methods: {
+    ...mapActions('chat', ['addMessage', 'setWidgetOpen', 'setWidgetClosed']),
+    
+    handleMessageSent(event) {
+      this.addMessage(event);
+    },
+    
+    handleWidgetOpened() {
+      this.setWidgetOpen(true);
+    },
+    
+    handleWidgetClosed() {
+      this.setWidgetClosed(false);
+    }
+  }
+}
+</script>
+```
+
+### Custom Styling
+
+The widget uses CSS custom properties for theming. You can override these in your CSS:
+
+```css
+:root {
+  --primary-color: #your-color;
+  --accent-color: #your-accent;
+  --widget-width: 400px;
+  --widget-height: 600px;
+  --font-family: 'Your Font', sans-serif;
+}
+
+/* Custom widget styling */
+nerd-chat-widget {
+  --primary-color: #007bff;
+  --accent-color: #28a745;
+}
+```
+
+### Global Registration
+
+```javascript
+// main.js
+import { createApp } from 'vue';
+import { NerdChatWidget } from 'nerdagent-chat-widget-vue';
+import App from './App.vue';
+
+const app = createApp(App);
+
+// Register globally
+app.component('NerdChatWidget', NerdChatWidget);
+
+app.mount('#app');
+```
+
+## Browser Support
+
+- Chrome 60+
+- Firefox 55+
+- Safari 10+
+- Edge 79+
 
-### Types
+## TypeScript Support
+
+Full TypeScript definitions are included. Import types as needed:
 
 ```typescript
-type WidgetPosition = 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
+import { WidgetPosition, ChatMessage } from 'nerdagent-chat-widget-vue';
+```
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Widget not appearing**: Ensure the component is properly imported and registered
+2. **Styling issues**: Check that FontAwesome is loaded for icons
+3. **Events not firing**: Verify event handlers are properly bound
+4. **TypeScript errors**: Make sure you're using the correct prop types
+
+### Debug Mode
+
+Enable debug logging by setting the browser's localStorage:
+
+```javascript
+localStorage.setItem('nerdagent-chat-widget-debug', 'true');
 ```
 
+## Contributing
+
+We welcome contributions! Please see our [Contributing Guide](../../CONTRIBUTING.md) for details.
+
 ## License
 
-MIT
+MIT License - see [LICENSE](../../LICENSE) for details.
+
+## Support
+
+- 📧 Email: support@nerdagent.ai
+- 📖 Documentation: [docs.nerdagent.ai](https://docs.nerdagent.ai)
+- 🐛 Issues: [GitHub Issues](https://github.com/nerdagent/chat-widget/issues)
+
+## Changelog
+
+### v1.0.2
+- Initial release with Vue wrapper
+- Full TypeScript support
+- Event handling integration
+- Composition API and Options API examples

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nerdagent-chat-widget-vue",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "type": "module",
   "description": "NerdAgent Chat Widget for Vue",
   "main": "dist/index.js",
@@ -42,5 +42,5 @@
     "url": "https://github.com/nerdagent/chat-widget.git",
     "directory": "packages/vue"
   },
-  "gitHead": "baebff96671fd060b15aa0ca587f2c9a1556c06b"
+  "gitHead": "c8f93bc623e36bcb74a3641f07ae6ee1cccd4941"
 }