@acorex/components 21.0.0-next.3 → 21.0.0-next.31

package/conversation2/README.md

@@ -0,0 +1,426 @@
+# @acorex/components/conversation2
+
+A modern, fully-featured conversation/chat component for Angular 18+. Built with signals, standalone components, and extensibility in mind.
+
+## 🚀 Features
+
+- **Real-time Messaging** - Live message updates with WebSocket support
+- **Multiple Message Types** - Text, images, videos, audio, voice, files, locations, stickers, contacts
+- **Rich Interactions** - Reactions, replies, message editing, deletion, forwarding
+- **Group & Private Chats** - Support for 1-on-1 and group conversations
+- **Typing Indicators** - Real-time typing status
+- **Read Receipts** - Message delivery and read status
+- **Infinite Scroll** - Efficient pagination for message history
+- **Search** - Search within conversations and messages
+- **Extensible** - Plugin system for custom message renderers and actions
+- **Responsive** - Mobile-friendly design
+- **Accessibility** - ARIA labels and keyboard navigation
+
+## 📦 Installation
+
+```bash
+npm install @acorex/components/conversation2
+```
+
+## 🔧 Peer Dependencies
+
+This package requires the following peer dependencies:
+
+### Required Angular Dependencies
+
+```json
+{
+  "@angular/common": "^18.0.0",
+  "@angular/core": "^18.0.0",
+  "@angular/forms": "^18.0.0",
+  "rxjs": "^7.8.0"
+}
+```
+
+### Required Acorex Dependencies
+
+#### Core Packages
+
+- `@acorex/cdk/common` - Common utilities and directives
+- `@acorex/core/date-time` - Date and time formatting
+- `@acorex/core/format` - General formatting utilities
+
+#### Component Packages
+
+- `@acorex/components/avatar` - User avatars
+- `@acorex/components/badge` - Notification badges
+- `@acorex/components/button` - Button components
+- `@acorex/components/decorators` - Decorative elements
+- `@acorex/components/dialog` - Dialog service
+- `@acorex/components/dropdown` - Dropdown panels
+- `@acorex/components/image` - Image components
+- `@acorex/components/label` - Label components
+- `@acorex/components/loading` - Loading indicators
+- `@acorex/components/menu` - Context menus
+- `@acorex/components/popover` - Popover components
+- `@acorex/components/popup` - Popup service
+- `@acorex/components/search-box` - Search functionality
+- `@acorex/components/select-box` - Select dropdowns
+- `@acorex/components/tabs` - Tab components
+- `@acorex/components/text-area` - Text input areas
+- `@acorex/components/text-box` - Text input boxes
+- `@acorex/components/toast` - Toast notifications
+- `@acorex/components/tooltip` - Tooltips
+- `@acorex/components/uploader` - File upload functionality
+
+## 🎯 Quick Start
+
+> **New to Conversation2?** Check out our [5-Minute Quick Start Guide](./docs/QUICK-START.md) for the fastest way to get started!
+
+### Detailed Setup
+
+### 1. Standalone Application (Recommended)
+
+```typescript
+import { ApplicationConfig } from '@angular/core';
+import { provideConversation, AXIndexedDBApi } from '@acorex/components/conversation2';
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    provideConversation({
+      api: AXIndexedDBApi, // or your custom API implementation
+      config: {
+        pageSize: 20,
+        maxFileSize: 10 * 1024 * 1024, // 10MB
+        allowedFileTypes: ['image/*', 'video/*', 'audio/*', 'application/pdf'],
+      },
+      registry: {
+        // Optional: Register custom message renderers, actions, etc.
+      }
+    })
+  ]
+};
+```
+
+### 2. NgModule Application (Legacy)
+
+```typescript
+import { NgModule } from '@angular/core';
+import { AXConversation2Module, AXIndexedDBApi } from '@acorex/components/conversation2';
+
+@NgModule({
+  imports: [
+    AXConversation2Module.forRoot({
+      api: AXIndexedDBApi,
+      config: { /* ... */ }
+    })
+  ]
+})
+export class AppModule { }
+```
+
+### 3. Use in Template
+
+```html
+<ax-conversation-container></ax-conversation-container>
+```
+
+## 🔌 API Implementation
+
+You must provide an API implementation that extends `AXConversationApi`:
+
+```typescript
+import { Injectable } from '@angular/core';
+import { HttpClient } from '@angular/common/http';
+import { AXConversationApi, AXPagination, AXPaginatedResult } from '@acorex/components/conversation2';
+
+@Injectable()
+export class MyConversationApi extends AXConversationApi {
+  constructor(private http: HttpClient) {
+    super();
+  }
+
+  async connect(): Promise<void> {
+    // Initialize WebSocket connection
+  }
+
+  async fetchConversations(pagination: AXPagination): Promise<AXPaginatedResult<AXConversation>> {
+    const response = await this.http.get('/api/conversations', {
+      params: { page: pagination.page, pageSize: pagination.pageSize }
+    }).toPromise();
+    return response;
+  }
+
+  // Implement other required methods...
+}
+```
+
+### Built-in API Implementations
+
+#### IndexedDB API (Development/Demo)
+
+```typescript
+import { AXIndexedDBApi } from '@acorex/components/conversation2';
+
+// Provides in-memory storage with sample data
+// Perfect for development and demos
+provideConversation({ api: AXIndexedDBApi })
+```
+
+#### IndexedDB with AI API (AI-Powered Demo)
+
+```typescript
+import { AXIndexedDBAIApi } from '@acorex/components/conversation2';
+
+// Includes AI-powered auto-responses
+provideConversation({ api: AXIndexedDBAIApi })
+```
+
+## ⚙️ Configuration
+
+### Conversation Config
+
+```typescript
+interface AXConversationConfig {
+  // Pagination
+  pageSize?: number;                    // Default: 20
+  infiniteScrollThreshold?: number;     // Default: 200px
+  scrollThreshold?: number;             // Default: 100px
+
+  // File Upload
+  maxFileSize?: number;                 // Default: 10MB
+  allowedFileTypes?: string[];          // Default: all types
+
+  // UI Behavior
+  messageHighlightDuration?: number;    // Default: 2000ms
+  typingIndicatorTimeout?: number;      // Default: 3000ms
+
+  // Features
+  enableReactions?: boolean;            // Default: true
+  enableReplies?: boolean;              // Default: true
+  enableEditing?: boolean;              // Default: true
+  enableDeletion?: boolean;             // Default: true
+}
+```
+
+### Registry Configuration
+
+```typescript
+interface AXRegistryConfiguration {
+  messageRenderers?: AXMessageRenderer[];
+  messageActions?: AXMessageAction[];
+  composerActions?: AXComposerAction[];
+  composerTabs?: AXComposerTab[];
+  conversationTabs?: AXConversationTab[];
+  infoBarActions?: AXInfoBarAction[];
+  conversationItemActions?: AXConversationItemAction[];
+}
+```
+
+## 🎨 Customization
+
+### Custom Message Renderer
+
+```typescript
+import { Component, input } from '@angular/core';
+import { AXMessageRenderer } from '@acorex/components/conversation2';
+
+@Component({
+  selector: 'my-custom-renderer',
+  template: `<div>{{ message().payload.customData }}</div>`
+})
+export class MyCustomRendererComponent {
+  message = input.required<AXMessage>();
+}
+
+const myRenderer: AXMessageRenderer = {
+  type: 'custom',
+  component: MyCustomRendererComponent,
+  priority: 100
+};
+
+// Register in config
+provideConversation({
+  api: MyApi,
+  registry: {
+    messageRenderers: [myRenderer]
+  }
+});
+```
+
+### Custom Message Action
+
+```typescript
+const forwardAction: AXMessageAction = {
+  id: 'forward',
+  label: 'Forward',
+  icon: 'forward',
+  shortcut: 'Ctrl+F',
+  enabled: (message, user) => message.senderId === user.id,
+  execute: async (message, service) => {
+    // Forward logic
+  }
+};
+
+provideConversation({
+  api: MyApi,
+  registry: {
+    messageActions: [forwardAction]
+  }
+});
+```
+
+## 📱 Components
+
+### Main Components
+
+- `<ax-conversation-container>` - Full conversation UI with sidebar, messages, and composer
+- `<ax-conversation-sidebar>` - Conversation list sidebar
+- `<ax-conversation-message-list>` - Message list with virtual scrolling
+- `<ax-conversation-composer>` - Message input area
+- `<ax-conversation-info-bar>` - Conversation header with actions
+
+### Usage Examples
+
+```html
+<!-- Full conversation UI -->
+<ax-conversation-container></ax-conversation-container>
+
+<!-- Custom layout -->
+<div class="my-chat-layout">
+  <ax-conversation-sidebar></ax-conversation-sidebar>
+  <div class="chat-main">
+    <ax-conversation-info-bar></ax-conversation-info-bar>
+    <ax-conversation-message-list></ax-conversation-message-list>
+    <ax-conversation-composer></ax-conversation-composer>
+  </div>
+</div>
+```
+
+## 🎭 Services
+
+### AXConversationService
+
+Main service for conversation operations:
+
+```typescript
+import { inject } from '@angular/core';
+import { AXConversationService } from '@acorex/components/conversation2';
+
+export class MyComponent {
+  private conversationService = inject(AXConversationService);
+
+  async sendMessage() {
+    await this.conversationService.sendMessage({
+      conversationId: 'conv-123',
+      type: 'text',
+      payload: { text: 'Hello!' }
+    });
+  }
+
+  async createConversation() {
+    const conv = await this.conversationService.createConversation(
+      ['user-1', 'user-2'],
+      'private'
+    );
+  }
+}
+```
+
+## 🧪 Testing
+
+```typescript
+import { TestBed } from '@angular/core/testing';
+import { provideConversation, AXConversationService } from '@acorex/components/conversation2';
+import { MockConversationApi } from './mocks/mock-api';
+
+describe('MyComponent', () => {
+  beforeEach(() => {
+    TestBed.configureTestingModule({
+      providers: [
+        provideConversation({ api: MockConversationApi })
+      ]
+    });
+  });
+
+  it('should send message', async () => {
+    const service = TestBed.inject(AXConversationService);
+    const message = await service.sendMessage({
+      conversationId: 'test',
+      type: 'text',
+      payload: { text: 'Test' }
+    });
+    expect(message).toBeDefined();
+  });
+});
+```
+
+## 🎯 Message Types
+
+Supported message types out of the box:
+
+- **text** - Plain text messages
+- **image** - Image messages with thumbnails
+- **video** - Video messages with playback
+- **audio** - Audio file messages
+- **voice** - Voice recordings
+- **file** - Generic file attachments
+- **location** - Location sharing
+- **sticker** - Sticker messages
+- **contact** - Contact card sharing
+- **system** - System notifications
+
+## 🔒 Security Considerations
+
+- **API Keys**: Never hardcode API keys in source code. Use environment variables or injection tokens.
+- **File Upload**: Validate file types and sizes on both client and server.
+- **XSS Protection**: All user content is sanitized by default.
+- **Authentication**: Implement proper authentication in your API layer.
+
+## 📊 Performance Tips
+
+1. **Virtual Scrolling**: Enabled by default for large message lists
+2. **Lazy Loading**: Images and media are loaded on demand
+3. **Pagination**: Messages are loaded in pages to reduce initial load
+4. **Debouncing**: Typing indicators are debounced to reduce network traffic
+5. **Memoization**: Use computed signals for expensive calculations
+
+## 🐛 Troubleshooting
+
+### Common Issues
+
+**Issue**: Messages not appearing
+
+- Check if API is connected: `conversationService.connectionStatus$()`
+- Verify API implementation returns correct data structure
+
+**Issue**: File upload fails
+
+- Check `maxFileSize` and `allowedFileTypes` configuration
+- Verify API `uploadFile()` implementation
+
+**Issue**: Styling issues
+
+- Ensure all Acorex component styles are imported
+- Check for CSS conflicts with global styles
+
+## 📚 Additional Resources
+
+- [Quick Start Guide](./docs/QUICK-START.md) - Get started in 5 minutes
+- [Architecture Overview](./docs/ARCHITECTURE-OVERVIEW.md) - Understand the module structure
+- [API Documentation](./docs/ARCHITECTURE-APIS.md) - Implement custom backends
+- [Component Guide](./docs/ARCHITECTURE-COMPONENTS.md) - Learn about components
+- [Plugin System](./docs/ARCHITECTURE-PLUGINS.md) - Extend functionality
+- [Usage Guide](./docs/USAGE-GUIDE.md) - Advanced usage patterns
+
+## 🤝 Contributing
+
+Contributions are welcome! Please read our [Contributing Guide](./CONTRIBUTING.md) for details.
+
+## 📄 License
+
+MIT License - see LICENSE file for details
+
+## 🔄 Changelog
+
+See [CHANGELOG.md](./CHANGELOG.md) for version history and updates.
+
+## 💬 Support
+
+- GitHub Issues: [Report a bug](https://github.com/acorexui/acorex-ui/issues)
+- Discussions: [Ask questions](https://github.com/acorexui/acorex-ui/discussions)