@cdevhub/ngx-chat 1.0.6

package/README.md

@@ -0,0 +1,382 @@
+# ngx-chat
+
+A pure presentational Angular 21 library for building chat interfaces. Supports AI chat, peer-to-peer messaging, group chat, support chat, and bot interactions.
+
+## Features
+
+- **Signals-based**: Built with Angular signals (`signal`, `computed`, `input`, `output`)
+- **Virtual scrolling**: Handle 10,000+ messages efficiently
+- **Markdown rendering**: Full markdown support with syntax highlighting
+- **File attachments**: Images, files, video, and audio support
+- **Interactive actions**: Confirm dialogs, select, multi-select, button groups
+- **Accessibility**: WCAG 2.1 AA compliant
+- **RTL support**: Full right-to-left language support
+- **Theming**: Dark/light/auto themes via CSS custom properties
+- **Fully typed**: Complete TypeScript interfaces
+
+## Installation
+
+```bash
+npm install ngx-chat
+```
+
+### Peer Dependencies
+
+Install required peer dependencies:
+
+```bash
+npm install @angular/animations @angular/cdk
+```
+
+Required versions:
+- `@angular/core` ^21.0.0
+- `@angular/common` ^21.0.0
+- `@angular/animations` ^21.0.0
+- `@angular/cdk` ^21.0.0
+
+### Optional Dependencies
+
+For markdown rendering with syntax highlighting:
+
+```bash
+npm install marked dompurify highlight.js
+```
+
+## Quick Start
+
+### 1. Configure the provider
+
+```typescript
+// app.config.ts
+import { ApplicationConfig, provideZoneChangeDetection } from '@angular/core';
+import { provideAnimationsAsync } from '@angular/platform-browser/animations/async';
+import { provideChat } from 'ngx-chat';
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    provideZoneChangeDetection({ eventCoalescing: true }),
+    provideAnimationsAsync(),
+    provideChat() // Uses defaults
+  ]
+};
+```
+
+### 2. Use the component
+
+```typescript
+// app.component.ts
+import { Component, signal } from '@angular/core';
+import { ChatComponent, ChatMessage, ChatSendEvent } from 'ngx-chat';
+
+@Component({
+  selector: 'app-root',
+  standalone: true,
+  imports: [ChatComponent],
+  template: `
+    <ngx-chat
+      [messages]="messages()"
+      [isTyping]="isTyping()"
+      (send)="onSend($event)"
+    />
+  `,
+  styles: [`
+    ngx-chat {
+      height: 600px;
+      display: block;
+    }
+  `]
+})
+export class AppComponent {
+  messages = signal<ChatMessage[]>([]);
+  isTyping = signal(false);
+
+  onSend(event: ChatSendEvent): void {
+    const userMessage: ChatMessage = {
+      id: crypto.randomUUID(),
+      content: event.content,
+      timestamp: new Date(),
+      sender: { id: 'user', name: 'You', type: 'self' },
+      status: 'sent'
+    };
+
+    this.messages.update(msgs => [...msgs, userMessage]);
+
+    // Send to your backend/AI service
+    this.sendToBackend(event.content);
+  }
+
+  private sendToBackend(content: string): void {
+    // Your implementation
+  }
+}
+```
+
+## Configuration
+
+Configure ngx-chat via `provideChat()` in your app config:
+
+```typescript
+provideChat({
+  config: {
+    // Behavior settings
+    behavior: {
+      sendOnEnter: true,        // Send message on Enter key
+      showTimestamps: true,     // Display timestamps on messages
+      autoScroll: true,         // Auto-scroll to new messages
+      groupMessages: true,      // Group consecutive messages from same sender
+      showSenderName: true,     // Show sender name on messages
+      showAvatar: true,         // Show avatar on messages
+    },
+
+    // Message validation
+    validation: {
+      maxMessageLength: 5000,   // Max characters per message
+      sanitize: true,           // Sanitize HTML in messages
+      trimWhitespace: true,     // Trim leading/trailing whitespace
+    },
+
+    // Markdown rendering
+    markdown: {
+      enabled: true,            // Enable markdown rendering
+      syntaxHighlighting: true, // Enable code syntax highlighting
+      externalLinksNewTab: true,// Open external links in new tab
+    },
+
+    // File attachments
+    attachments: {
+      enabled: true,            // Enable file attachments
+      maxFileSize: 10485760,    // 10 MB max file size
+      maxFilesPerMessage: 5,    // Max files per message
+      dragAndDrop: true,        // Enable drag and drop
+      pasteFromClipboard: true, // Enable paste from clipboard
+    },
+
+    // Virtual scrolling
+    virtualScroll: {
+      enabled: true,            // Enable virtual scrolling
+      threshold: 100,           // Min messages before activating
+    },
+
+    // Error recovery
+    errorRecovery: {
+      autoRetry: true,          // Auto-retry failed messages
+      maxRetries: 3,            // Max retry attempts
+      offlineQueue: true,       // Queue messages when offline
+    },
+
+    // Keyboard shortcuts
+    keyboard: {
+      sendOnEnter: true,        // Send on Enter
+      sendOnCtrlEnter: false,   // Send on Ctrl+Enter
+      escToCancelAction: true,  // Escape to cancel action
+    },
+
+    // Theme and direction
+    theme: 'auto',              // 'light' | 'dark' | 'auto'
+    direction: 'auto',          // 'ltr' | 'rtl' | 'auto'
+  },
+
+  // Internationalization
+  i18n: {
+    send: 'Send',
+    placeholder: 'Type a message...',
+    typing: '{name} is typing...',
+    // ... see full i18n options below
+  }
+})
+```
+
+### i18n Options
+
+All user-facing strings can be customized:
+
+```typescript
+provideChat({
+  i18n: {
+    // Buttons
+    send: 'Send',
+    cancel: 'Cancel',
+    confirm: 'Confirm',
+    submit: 'Submit',
+    retry: 'Retry',
+
+    // Input
+    placeholder: 'Type a message...',
+    emptyState: 'No messages yet',
+
+    // Typing indicator
+    typing: '{name} is typing...',
+    someoneTyping: 'Someone is typing...',
+
+    // Message status
+    sending: 'Sending...',
+    sent: 'Sent',
+    delivered: 'Delivered',
+    read: 'Read',
+    error: 'Failed to send',
+
+    // Attachments
+    addAttachment: 'Add attachment',
+    removeAttachment: 'Remove attachment',
+    fileTooLarge: 'File is too large. Maximum size is {maxSize}.',
+
+    // Loading
+    loading: 'Loading...',
+    loadMore: 'Load more messages',
+
+    // ARIA labels
+    ariaMessageList: 'Chat messages',
+    ariaMessageInput: 'Message input',
+    ariaSendButton: 'Send message',
+  }
+})
+```
+
+## API Reference
+
+### Components
+
+| Component | Selector | Description |
+|-----------|----------|-------------|
+| `ChatComponent` | `ngx-chat` | Main chat container |
+| `ChatHeaderComponent` | `ngx-chat-header` | Chat header with title |
+| `ChatMessagesComponent` | `ngx-chat-messages` | Messages container with virtual scroll |
+| `ChatSenderComponent` | `ngx-chat-sender` | Message input and send button |
+| `ChatMarkdownComponent` | `ngx-chat-markdown` | Markdown renderer |
+| `ChatErrorBoundaryComponent` | `ngx-chat-error-boundary` | Error boundary wrapper |
+
+### Main Component Inputs
+
+```typescript
+// ChatComponent inputs
+messages: ChatMessage[]      // Array of messages to display
+isTyping: boolean           // Show typing indicator
+typingLabel: string         // Custom typing label
+disabled: boolean           // Disable chat interactions
+loading: boolean            // Show loading state
+config: ChatConfigInput     // Configuration overrides
+```
+
+### Main Component Outputs
+
+```typescript
+// ChatComponent outputs
+send: ChatSendEvent         // User sends a message
+typing: ChatTypingEvent     // User typing state changes
+action: MessageActionEvent  // User responds to an action
+retry: ChatRetryEvent       // User retries a failed message
+loadMore: ChatLoadMoreEvent // User scrolls to load more
+attachmentClick: AttachmentClickEvent // User clicks attachment
+```
+
+### Models
+
+```typescript
+// Message model
+interface ChatMessage {
+  id: string;
+  content: string;
+  timestamp: Date;
+  sender: MessageSender;
+  status: MessageStatus;
+  attachments?: MessageAttachment[];
+  action?: MessageAction;
+  error?: ChatMessageError;
+}
+
+// Sender model
+interface MessageSender {
+  id: string;
+  name: string;
+  type: 'self' | 'other' | 'system';
+  avatarUrl?: string;
+}
+
+// Status type
+type MessageStatus = 'sending' | 'sent' | 'delivered' | 'read' | 'error';
+```
+
+### Provider Function
+
+```typescript
+import { provideChat, ProvideChatOptions } from 'ngx-chat';
+
+// In app.config.ts providers array
+provideChat(options?: ProvideChatOptions): EnvironmentProviders
+```
+
+### Injection Tokens
+
+```typescript
+import { CHAT_CONFIG, CHAT_I18N } from 'ngx-chat';
+
+// Inject configuration
+const config = inject(CHAT_CONFIG);
+const i18n = inject(CHAT_I18N);
+```
+
+## Theming
+
+ngx-chat uses CSS custom properties for theming. Override these in your styles:
+
+```css
+ngx-chat {
+  /* Background colors */
+  --ngx-chat-bg: #ffffff;
+  --ngx-chat-surface: #f8f9fa;
+  --ngx-chat-border: #e9ecef;
+
+  /* Text colors */
+  --ngx-chat-text: #212529;
+  --ngx-chat-text-secondary: #6c757d;
+  --ngx-chat-text-muted: #adb5bd;
+
+  /* Self message (current user) */
+  --ngx-chat-self-bg: #0d6efd;
+  --ngx-chat-self-text: #ffffff;
+
+  /* Other message (other participants) */
+  --ngx-chat-other-bg: #f1f3f4;
+  --ngx-chat-other-text: #202124;
+
+  /* Input */
+  --ngx-chat-input-bg: #ffffff;
+  --ngx-chat-input-border: #ced4da;
+  --ngx-chat-input-focus-border: #86b7fe;
+
+  /* Spacing */
+  --ngx-chat-spacing: 16px;
+  --ngx-chat-spacing-sm: 8px;
+  --ngx-chat-spacing-lg: 24px;
+
+  /* Message bubble */
+  --ngx-chat-bubble-radius: 16px;
+  --ngx-chat-bubble-max-width: 85%;
+
+  /* Avatar */
+  --ngx-chat-avatar-size: 32px;
+  --ngx-chat-avatar-bg: #e5e7eb;
+
+  /* Animation */
+  --ngx-chat-animation-duration: 200ms;
+}
+```
+
+## Browser Support
+
+| Browser | Version |
+|---------|---------|
+| Chrome | Latest 2 versions |
+| Firefox | Latest 2 versions |
+| Safari | Latest 2 versions |
+| Edge | Latest 2 versions |
+
+Requires browsers with support for:
+- ES2022
+- CSS Custom Properties
+- ResizeObserver
+- IntersectionObserver
+
+## License
+
+MIT