@memberjunction/ng-chat 2.42.1 → 2.44.0

package/README.md

@@ -1,17 +1,29 @@
-# Chat Component
+# @memberjunction/ng-chat
 
-The Chat Component is a reusable Angular component designed for building chat interfaces in MemberJunction applications. It can be used for AI-assisted conversations or peer-to-peer chat applications.
+A reusable Angular component library for building chat interfaces in MemberJunction applications. This package provides a flexible chat component that can be used for AI-assisted conversations, chatbots, or peer-to-peer chat applications.
+
+## Overview
+
+The `@memberjunction/ng-chat` package provides a feature-rich chat component with built-in support for:
+- User and AI message rendering with distinct styling
+- Markdown formatting in messages
+- Welcome screen with suggested prompts
+- Real-time message handling
+- Responsive design with auto-scrolling
+- Loading indicators for async operations
 
 ## Features
 
-- **Flexible Message System**: Display both user and AI messages with appropriate styling
-- **Markdown Support**: Render chat messages with markdown formatting support
-- **Welcome Screen**: Customizable welcome screen with suggested questions/prompts
-- **Auto-Scrolling**: Keeps the conversation scrolled to the bottom with a scroll-to-bottom button
-- **Loading Indicator**: Visual feedback during AI response generation
-- **Responsive Design**: Adapts to different screen sizes
-- **Auto-Resizing Input**: Text input automatically expands as the user types
-- **Clear Conversation**: Option to clear the entire conversation history
+- **Flexible Message System**: Display both user and AI messages with appropriate styling and avatars
+- **Markdown Support**: Full markdown rendering support for rich text messages
+- **Welcome Screen**: Customizable welcome screen with up to 4 suggested questions/prompts
+- **Smart Scrolling**: Automatic scroll-to-bottom with manual scroll detection
+- **Loading States**: Built-in loading indicator for async operations (e.g., AI responses)
+- **Responsive Design**: Mobile-friendly design that adapts to different screen sizes
+- **Auto-Resizing Input**: Text area automatically expands as users type longer messages
+- **Clear Conversation**: Confirmation dialog for clearing conversation history
+- **Customizable Avatars**: Support for custom AI avatar images
+- **Keyboard Support**: Send messages with Enter key (Shift+Enter for new lines)
 
 ## Installation
 
@@ -19,6 +31,13 @@ The Chat Component is a reusable Angular component designed for building chat in
 npm install @memberjunction/ng-chat
 ```
 
+### Peer Dependencies
+
+This package requires the following peer dependencies:
+- `@angular/common`: ^18.0.2
+- `@angular/core`: ^18.0.2
+- `@angular/forms`: ^18.0.2
+
 ## Usage
 
 ### Import the Module
@@ -47,25 +66,31 @@ export class YourModule { }
 </mj-chat>
 ```
 
-### Welcome Questions Example
+### Complete Example with AI Integration
 
 ```typescript
-// Component
-import { ChatWelcomeQuestion } from '@memberjunction/ng-chat';
+import { Component, ViewChild } from '@angular/core';
+import { ChatComponent, ChatMessage, ChatWelcomeQuestion } from '@memberjunction/ng-chat';
 
 @Component({
   selector: 'app-ai-assistant',
   template: `
     <mj-chat
+      #chatComponent
       [AIImageURL]="'assets/bot-avatar.png'"
       [AILargeImageURL]="'assets/bot-large.png'"
+      [InitialMessage]="'Hi! I'm your AI assistant. How can I help you today?'"
       [WelcomeQuestions]="welcomeQuestions"
+      [Placeholder]="'Ask me anything...'"
+      [ClearAllMessagesPrompt]="'Are you sure you want to clear this conversation?'"
       (MessageAdded)="handleNewMessage($event)"
       (ClearChatRequested)="handleClearChat()">
     </mj-chat>
   `
 })
 export class AIAssistantComponent {
+  @ViewChild('chatComponent') chatComponent!: ChatComponent;
+  
   welcomeQuestions: ChatWelcomeQuestion[] = [
     {
       topLine: 'Generate a report',
@@ -100,8 +125,9 @@ export class AIAssistantComponent {
   }
 
   handleClearChat() {
-    // Implement chat clearing logic
-    console.log('Chat cleared');
+    // Clear any conversation state in your service
+    this.conversationHistory = [];
+    this.chatComponent.ClearAllMessages();
   }
 
   async processUserMessage(message: string) {
@@ -122,6 +148,13 @@ export class AIAssistantComponent {
     } 
     catch (error) {
       console.error('Error getting AI response:', error);
+      // Show error message to user
+      this.chatComponent.SendMessage(
+        'Sorry, I encountered an error processing your request.', 
+        'Assistant', 
+        'ai', 
+        null
+      );
     } 
     finally {
       // End loading state
@@ -131,24 +164,79 @@ export class AIAssistantComponent {
 }
 ```
 
+### Programmatic Message Sending
+
+```typescript
+// Send a user message programmatically
+this.chatComponent.SendUserMessage('Hello, AI!');
+
+// Send an AI message
+this.chatComponent.SendMessage(
+  'Hello! How can I assist you today?',
+  'Assistant',
+  'ai',
+  messageId // optional ID for tracking
+);
+
+// Send a message without triggering the MessageAdded event
+this.chatComponent.SendMessage(
+  'System message',
+  'System',
+  'ai',
+  null,
+  false // fireEvent = false
+);
+```
+
 ## API Reference
 
+### Component Selector
+`<mj-chat></mj-chat>`
+
 ### Inputs
 
-- `InitialMessage`: string - Initial message shown before any messages are added
-- `Messages`: ChatMessage[] - Array of messages to display
-- `AIImageURL`: string - URL for the AI's avatar image (small version)
-- `AILargeImageURL`: string - URL for the AI's large avatar image (welcome screen)
-- `WelcomeQuestions`: ChatWelcomeQuestion[] - Array of up to 4 welcome questions/prompts
-- `ClearAllMessagesPrompt`: string - Confirmation message when clearing the chat
-- `AllowSend`: boolean - Enable/disable sending messages
-- `Placeholder`: string - Placeholder text for the input field
-- `ShowWaitingIndicator`: boolean - Show/hide the loading spinner
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `InitialMessage` | `string` | `''` | Initial message shown when chat is empty |
+| `Messages` | `ChatMessage[]` | `[]` | Array of messages to display |
+| `AIImageURL` | `string` | `''` | URL for the AI's avatar image (24px max width) |
+| `AILargeImageURL` | `string` | `''` | URL for the AI's large avatar on welcome screen |
+| `WelcomeQuestions` | `ChatWelcomeQuestion[]` | `[]` | Array of up to 4 welcome prompts |
+| `ClearAllMessagesPrompt` | `string` | `'Are you sure you want to clear all messages?'` | Confirmation dialog text |
+| `AllowSend` | `boolean` | `true` | Enable/disable message sending |
+| `Placeholder` | `string` | `'Type a message...'` | Input field placeholder text |
+| `ShowWaitingIndicator` | `boolean` | `false` | Show/hide loading spinner |
 
 ### Outputs
 
-- `MessageAdded`: EventEmitter<ChatMessage> - Fires when a new message is added
-- `ClearChatRequested`: EventEmitter<void> - Fires when user confirms clearing the chat
+| Event | Type | Description |
+|-------|------|-------------|
+| `MessageAdded` | `EventEmitter<ChatMessage>` | Emitted when a new message is added to the chat |
+| `ClearChatRequested` | `EventEmitter<void>` | Emitted when user confirms clearing the chat |
+
+### Public Methods
+
+#### `SendCurrentMessage(): void`
+Sends the current message in the input field. Automatically clears the input after sending.
+
+#### `SendMessage(message: string, senderName: string, senderType: 'user' | 'ai', id: any, fireEvent: boolean = true): void`
+Adds a message to the chat programmatically.
+
+**Parameters:**
+- `message`: The message text (supports markdown)
+- `senderName`: Display name of the sender
+- `senderType`: Either 'user' or 'ai' for styling
+- `id`: Optional ID for message tracking
+- `fireEvent`: Whether to emit the MessageAdded event
+
+#### `SendUserMessage(message: string): void`
+Convenience method to send a user message. Automatically sets senderName to 'User' and senderType to 'user'.
+
+#### `ClearAllMessages(): void`
+Clears all messages from the chat and resets to initial state.
+
+#### `HandleClearChat(): void`
+Shows the confirmation dialog for clearing chat. This emits the ClearChatRequested event when confirmed.
 
 ### Classes
 
@@ -156,12 +244,17 @@ export class AIAssistantComponent {
 
 ```typescript
 export class ChatMessage {
-  public message: string;
-  public senderName: string;
-  public senderType: 'user' | 'ai';
-  public id?: any;
-
-  constructor(message: string, senderName: string, senderType: 'user' | 'ai', id: any = null);
+  public message: string;         // The message content (supports markdown)
+  public senderName: string;      // Display name of sender
+  public senderType: 'user' | 'ai'; // Type for styling purposes
+  public id?: any;                // Optional ID for tracking
+
+  constructor(
+    message: string, 
+    senderName: string, 
+    senderType: 'user' | 'ai', 
+    id: any = null
+  );
 }
 ```
 
@@ -169,26 +262,122 @@ export class ChatMessage {
 
 ```typescript
 export class ChatWelcomeQuestion {
-  public topLine: string = "";
-  public bottomLine: string = "";
-  public prompt: string = "";
+  public topLine: string = "";     // Main text of the suggestion
+  public bottomLine: string = "";  // Supporting text/description
+  public prompt: string = "";      // The actual prompt to send when clicked
 }
 ```
 
-### Methods
+## Styling
 
-- `SendCurrentMessage()`: Sends the current message in the input field
-- `SendMessage(message, senderName, senderType, id, fireEvent)`: Sends a specified message
-- `SendUserMessage(message)`: Convenience method to send a user message
-- `ClearAllMessages()`: Clears all messages from the chat interface
+The component provides several CSS classes for customization:
 
-## Styling
+- `.chat-message-wrap`: Container for each message
+- `.chat-message`: The message content container
+- `.chat-message-ai`: Additional class for AI messages
+- `.chat-message-image`: Avatar/icon container
+- `.chat-input-container`: Input area container
+- `.chat-welcome-container`: Welcome screen container
 
-The component includes default styles that you can override using CSS. The component uses a clean and modern design with different styling for user and AI messages.
+You can override these styles in your global styles or component styles:
+
+```css
+/* Example: Customize AI message background */
+::ng-deep .chat-message-ai {
+  background-color: #f0f4f8;
+  border-left: 3px solid #3182ce;
+}
+
+/* Example: Customize user avatar */
+::ng-deep .chat-message-wrap:has(.chat-message:not(.chat-message-ai)) .chat-message-image {
+  color: #48bb78;
+}
+```
 
 ## Dependencies
 
-- `ngx-markdown`: For rendering markdown in chat messages
-- `@progress/kendo-angular-indicators`: For the loading spinner
-- `@progress/kendo-angular-buttons`: For buttons
-- `@progress/kendo-angular-dialog`: For the clear confirmation dialog
+### Runtime Dependencies
+- `@memberjunction/core`: Core MemberJunction utilities
+- `@memberjunction/ng-container-directives`: Container directive utilities
+- `@progress/kendo-angular-indicators`: Loading spinner component
+- `@progress/kendo-angular-buttons`: Button components
+- `@progress/kendo-angular-dialog`: Dialog component for confirmations
+- `ngx-markdown`: Markdown rendering support
+- `tslib`: TypeScript runtime helpers
+
+### Integration with MemberJunction
+
+This component integrates seamlessly with other MemberJunction packages:
+
+- Use with `@memberjunction/ai` for AI-powered conversations
+- Combine with `@memberjunction/core-entities` for entity-aware chat
+- Integrate with MemberJunction's authentication for user context
+
+## Build and Development
+
+This package uses Angular's library build system. To build the package:
+
+```bash
+# From the package directory
+npm run build
+
+# From the repository root
+turbo build --filter="@memberjunction/ng-chat"
+```
+
+The built files will be output to the `dist/` directory.
+
+## Advanced Usage
+
+### Custom Message Rendering
+
+While the component handles markdown rendering by default, you can extend functionality by processing messages before sending:
+
+```typescript
+// Pre-process messages with custom formatting
+const formattedMessage = this.formatMessage(userInput);
+this.chatComponent.SendUserMessage(formattedMessage);
+
+// Add metadata to messages using the id field
+this.chatComponent.SendMessage(
+  response,
+  'Assistant',
+  'ai',
+  { timestamp: Date.now(), tokens: 150, model: 'gpt-4' }
+);
+```
+
+### Maintaining Conversation History
+
+```typescript
+// Store conversation for persistence
+private saveConversation() {
+  const messages = this.chatComponent.Messages;
+  localStorage.setItem('chat-history', JSON.stringify(messages));
+}
+
+// Restore previous conversation
+private loadConversation() {
+  const saved = localStorage.getItem('chat-history');
+  if (saved) {
+    const messages = JSON.parse(saved) as ChatMessage[];
+    messages.forEach(msg => {
+      this.chatComponent.SendMessage(
+        msg.message,
+        msg.senderName,
+        msg.senderType,
+        msg.id,
+        false // Don't fire events when restoring
+      );
+    });
+  }
+}
+```
+
+## Notes
+
+- The component automatically focuses the input field after operations
+- Messages support full markdown syntax including code blocks, lists, and links
+- The welcome screen is only shown when there are no messages
+- Default icons use Font Awesome (fa-robot for AI, fa-user for users)
+- The component uses Angular's ChangeDetectorRef for optimal performance

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@memberjunction/ng-chat",
-  "version": "2.42.1",
+  "version": "2.44.0",
   "description": "MemberJunction: Reusable Chat Component - can be used for AI or peer to peer chat applications.",
   "main": "./dist/public-api.js",
   "typings": "./dist/public-api.d.ts",
@@ -24,8 +24,8 @@
     "@angular/forms": "18.0.2"
   },
   "dependencies": {
-    "@memberjunction/core": "2.42.1",
-    "@memberjunction/ng-container-directives": "2.42.1",
+    "@memberjunction/core": "2.44.0",
+    "@memberjunction/ng-container-directives": "2.44.0",
     "@progress/kendo-angular-indicators": "16.2.0",
     "@progress/kendo-angular-buttons": "16.2.0",
     "@progress/kendo-angular-dialog": "16.2.0",