emanate-ai-chat-lib 0.1.1

package/README.md

@@ -0,0 +1,409 @@
+# Emanate AI Chat Library
+
+A powerful, reusable Angular library for integrating AI chat functionality with **modern UI design**, **resizable interface**, **configurable uploads**, and comprehensive customization options.
+
+## 🎉 What's New in v2.0.0 (UI Enhancement Release)
+
+- **🎨 Modern Icon System** - Clean, minimalist SVG icons replacing emojis
+- **📊 Icon-Only Status** - Subtle status dots with no text clutter
+- **🔧 Configurable Uploads** - Independently enable/disable image and file uploads
+- **🖼️ Enhanced Fullscreen** - Fixed fullscreen mode with proper dimension restoration
+- **✨ Refined Animations** - Smoother transitions with cubic-bezier easing
+- **♿ Better Accessibility** - WCAG AA+ compliance with high contrast support
+- **📱 Improved Responsive** - Enhanced mobile experience with optimized touch targets
+- **🎯 Social Media Inspired** - Design patterns from Facebook, Twitter, LinkedIn
+
+[View UI Enhancements Guide](./documentation/UI_ENHANCEMENTS_GUIDE.md) | [View Full Changelog](./CHANGELOG.md)
+
+## ✨ Features
+
+### Core Functionality
+- ✅ Real-time AI chat messaging
+- ✅ Resizable chat interface (drag handles + presets)
+- ✅ **Configurable file upload** (PDF, DOC, DOCX, TXT, CSV) - *New!*
+- ✅ **Configurable image upload** (PNG, JPEG, GIF, WEBP) - *New!*
+- ✅ Enhanced fullscreen mode
+- ✅ Historical message loading
+- ✅ Session state persistence
+
+### UI & Design
+- ✅ **Modern SVG icon system** - *New!*
+- ✅ **Icon-only status indicators** - *New!*
+- ✅ 10 customizable themes
+- ✅ **Smooth animations & transitions** - *Enhanced!*
+- ✅ Mobile-responsive design
+- ✅ Clean, minimalist interface
+
+### Accessibility & Performance
+- ✅ **WCAG AA+ compliant** - *Enhanced!*
+- ✅ **High contrast mode support** - *New!*
+- ✅ **Reduced motion support** - *New!*
+- ✅ Keyboard navigation
+- ✅ Screen reader friendly
+- ✅ TypeScript support
+
+## 📦 Installation
+
+Install via npm:
+
+```bash
+npm install westlake-emanate-ai-chat-lib
+```
+
+Or via yarn:
+
+```bash
+yarn add westlake-emanate-ai-chat-lib
+```
+
+## 🚀 Quick Start
+
+### 1. Import the Module
+
+```typescript
+import { NgModule } from '@angular/core';
+import { EmanateAiChatLibModule } from 'westlake-emanate-ai-chat-lib';
+
+@NgModule({
+  imports: [
+    EmanateAiChatLibModule
+  ]
+})
+export class AppModule { }
+```
+
+### 2. Use the Component
+
+```html
+<emanate-ai-chat 
+  [title]="'Chat with Maestro'"
+  [apiUrl]="'https://your-api-url.com/api'"
+  [appKey]="'your-app-key'"
+  [userId]="currentUser.id"
+  [userName]="currentUser.name"
+  [firstName]="currentUser.firstName"
+  [templateDesign]="'default'"
+  [enableImageUpload]="true"
+  [enableFileUpload]="true"
+  (fileUploaded)="onFileUploaded($event)"
+  (sizeChanged)="onSizeChanged($event)">
+</emanate-ai-chat>
+```
+
+### 3. Configure Upload Buttons (Optional)
+
+Upload buttons are **disabled by default**. Enable them as needed:
+
+```typescript
+// Enable both upload types
+<emanate-ai-chat
+  [enableImageUpload]="true"
+  [enableFileUpload]="true">
+</emanate-ai-chat>
+
+// Enable only images
+<emanate-ai-chat
+  [enableImageUpload]="true"
+  [enableFileUpload]="false">
+</emanate-ai-chat>
+
+// Disable both (default)
+<emanate-ai-chat>
+</emanate-ai-chat>
+```
+
+## 📖 Component API
+
+### Input Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `title` | `string` | `'Chat with Maestro'` | Chat window title |
+| `placeholder` | `string` | `'Type your inquiry...'` | Input placeholder text |
+| `showDebugInfo` | `boolean` | `false` | Show debug information |
+| `apiUrl` | `string` | `undefined` | AI service API URL |
+| `appKey` | `string` | `undefined` | Application key for API |
+| `appSource` | `string` | `undefined` | Application source identifier |
+| `userId` | `string` | `undefined` | Current user ID |
+| `firstName` | `string` | `undefined` | User's first name |
+| `userName` | `string` | `undefined` | User's full name |
+| `templateDesign` | `string` | `'default'` | Theme name (see Themes) |
+| `welcomeMessage` | `string` | Auto-generated | Custom welcome message |
+| `historicalMessages` | `any[]` | `[]` | Previous conversation messages |
+| `conversationId` | `string` | `undefined` | Current conversation identifier |
+| `enableImageUpload` | `boolean` | `false` | **NEW!** Enable image upload button |
+| `enableFileUpload` | `boolean` | `false` | **NEW!** Enable file upload button |
+
+### Output Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `messageReceived` | `ChatMessage` | Emitted when AI responds |
+| `messageSent` | `ChatMessage` | Emitted when user sends message |
+| `fileUploaded` | `FileAttachment` | Emitted when file is uploaded |
+| `sizeChanged` | `{size, width, height}` | Emitted when chat is resized |
+
+### Interfaces
+
+```typescript
+export interface ChatMessage {
+  messageId?: string;
+  conversationId?: string;
+  isUser: boolean;
+  content: string;
+  sender?: string;
+  intent?: string;
+  authorName?: string;
+  confidenceScore?: number;
+  timestamp: Date;
+  isLoading?: boolean;
+  attachments?: FileAttachment[];
+}
+
+export interface FileAttachment {
+  id: string;
+  name: string;
+  type: string;
+  size: number;
+  url?: string;
+  data?: string | ArrayBuffer;
+}
+
+export type ChatSize = 'compact' | 'default' | 'expanded' | 'fullscreen';
+```
+
+## 🎨 Available Themes
+
+Choose from 10 professionally designed themes:
+
+- `default` - Purple gradient theme
+- `dark` - Dark mode theme
+- `blue` - Blue professional theme
+- `green` - Green nature theme
+- `purple` - Purple vibrant theme
+- `minimal` - Clean minimal theme
+- `corporate` - Corporate gray theme
+- `red` - Red alert theme
+- `yellow` - Yellow sunshine theme
+- `orange` - Orange warm theme
+
+## 📐 Resizing Features
+
+### Size Presets
+- **📱 Compact**: 400x500px - Minimal footprint
+- **💻 Default**: 800x600px - Standard view
+- **🖥️ Expanded**: 1200x800px - Maximum workspace
+- **⛶ Fullscreen**: 100vw x 100vh - Full coverage
+
+### Manual Resize
+- Drag the **right edge** to resize width
+- Drag the **bottom-right corner** to resize both dimensions
+- Size preferences saved automatically to session storage
+
+## 📎 File Upload
+
+### Supported File Types
+
+**Images**: 🖼️
+- PNG, JPEG, JPG, GIF, WEBP
+
+**Documents**: 📄
+- PDF, DOC, DOCX, TXT, CSV
+
+### File Validation
+- Maximum size: **10MB** per file
+- Type checking enforced
+- Visual preview with icons and sizes
+- Remove attachments before sending
+
+## 📱 Responsive Design
+
+- **Desktop (>768px)**: Full features with resize handles
+- **Tablet (768px-480px)**: Optimized layout, hidden handles
+- **Mobile (<480px)**: Full-screen, touch-optimized
+
+## 💡 Usage Examples
+
+### Basic Implementation
+
+```typescript
+import { Component } from '@angular/core';
+
+@Component({
+  selector: 'app-chat',
+  template: `
+    <emanate-ai-chat 
+      [apiUrl]="apiUrl"
+      [appKey]="appKey"
+      [userId]="userId"
+      [userName]="userName">
+    </emanate-ai-chat>
+  `
+})
+export class ChatComponent {
+  apiUrl = 'https://your-backend.com/api';
+  appKey = 'your-app-key';
+  userId = 'user123';
+  userName = 'John Doe';
+}
+```
+
+### With File Upload Handling
+
+```typescript
+import { Component } from '@angular/core';
+import { FileAttachment } from 'westlake-emanate-ai-chat-lib';
+
+@Component({
+  selector: 'app-chat',
+  template: `
+    <emanate-ai-chat 
+      [apiUrl]="apiUrl"
+      [appKey]="appKey"
+      (fileUploaded)="onFileUploaded($event)"
+      (sizeChanged)="onSizeChanged($event)">
+    </emanate-ai-chat>
+  `
+})
+export class ChatComponent {
+  apiUrl = 'https://your-backend.com/api';
+  appKey = 'your-app-key';
+  
+  onFileUploaded(file: FileAttachment): void {
+    console.log('File uploaded:', file.name, file.size);
+    // Process file upload to your backend
+    this.uploadToServer(file);
+  }
+  
+  onSizeChanged(sizeData: any): void {
+    console.log('Chat resized:', sizeData.size, sizeData.width, sizeData.height);
+    // Save user preference or adjust layout
+  }
+  
+  private async uploadToServer(file: FileAttachment): Promise<void> {
+    // Your upload logic here
+  }
+}
+```
+
+### With Historical Messages
+
+```typescript
+import { Component, OnInit } from '@angular/core';
+
+@Component({
+  selector: 'app-chat',
+  template: `
+    <emanate-ai-chat 
+      [apiUrl]="apiUrl"
+      [conversationId]="conversationId"
+      [historicalMessages]="messages">
+    </emanate-ai-chat>
+  `
+})
+export class ChatComponent implements OnInit {
+  apiUrl = 'https://your-backend.com/api';
+  conversationId = 'conv-123';
+  messages: any[] = [];
+  
+  ngOnInit(): void {
+    // Load previous conversation
+    this.loadHistory();
+  }
+  
+  private loadHistory(): void {
+    // Fetch from backend
+    this.http.get(`/api/conversations/${this.conversationId}`)
+      .subscribe((data: any) => {
+        this.messages = data.messages;
+      });
+  }
+}
+```
+
+## 📚 Documentation
+
+For detailed documentation, see:
+
+- **[RESIZABLE_UI_GUIDE.md](./RESIZABLE_UI_GUIDE.md)** - Complete feature guide and API reference
+- **[VISUAL_REFERENCE.md](./VISUAL_REFERENCE.md)** - Visual layouts, diagrams, and design specs
+- **[INTEGRATION_EXAMPLES.md](./INTEGRATION_EXAMPLES.md)** - Real-world integration examples
+- **[HISTORICAL_MESSAGES_USAGE.md](./HISTORICAL_MESSAGES_USAGE.md)** - Message history guide
+- **[CHANGELOG.md](./CHANGELOG.md)** - Version history and changes
+
+## 🛠️ Development
+
+To develop or contribute to this library:
+
+### Building the Library
+
+```bash
+# Navigate to project root
+cd Westlake.Underwriting.AIAgent.Angular
+
+# Build the library
+ng build emanate-ai-chat-lib
+
+# Build with watch mode
+ng build emanate-ai-chat-lib --watch
+```
+
+### Testing Locally
+
+```bash
+# Build the library
+ng build emanate-ai-chat-lib
+
+# Link locally
+cd dist/emanate-ai-chat-lib
+npm link
+
+# In your test project
+npm link westlake-emanate-ai-chat-lib
+```
+
+### Running Tests
+
+```bash
+ng test emanate-ai-chat-lib
+```
+
+## 📋 Requirements
+
+- **Angular**: 12.1.3+
+- **RxJS**: 6.6.0+
+- **TypeScript**: 4.3.5+
+- **Modern Browsers**: Chrome 80+, Firefox 75+, Safari 13+
+
+## 🤝 Contributing
+
+Contributions are welcome! Please:
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Add tests if applicable
+5. Submit a pull request
+
+## 📝 License
+
+MIT License - see LICENSE file for details
+
+## 🐛 Issues & Support
+
+Report issues at: [GitHub Issues](https://github.com/NC-Westlake/Westlake.Underwriting.AIAgent.Angular/issues)
+
+## 👨‍💻 Author
+
+**Jomel Dicen** - [jomel.dicen@nowcom.com.ph](mailto:jomel.dicen@nowcom.com.ph)
+
+## 🔗 Links
+
+- [GitHub Repository](https://github.com/NC-Westlake/Westlake.Underwriting.AIAgent.Angular)
+- [npm Package](https://www.npmjs.com/package/westlake-emanate-ai-chat-lib)
+- [Changelog](./CHANGELOG.md)
+
+---
+
+**Version**: 0.1.0  
+**Last Updated**: December 31, 2025