@xcelsior/ui-chat 1.0.1

package/.storybook/main.ts

@@ -0,0 +1,27 @@
+import type { StorybookConfig } from '@storybook/react-vite';
+
+const config: StorybookConfig = {
+    stories: ['../src/**/*.stories.@(js|jsx|ts|tsx|mdx)'],
+    addons: [
+        '@storybook/addon-links',
+        '@storybook/addon-essentials',
+        '@storybook/addon-interactions',
+    ],
+    framework: {
+        name: '@storybook/react-vite',
+        options: {},
+    },
+    docs: {
+        autodocs: 'tag',
+    },
+    typescript: {
+        check: false,
+        reactDocgen: 'react-docgen-typescript',
+        reactDocgenTypescriptOptions: {
+            shouldExtractLiteralValuesFromEnum: true,
+            propFilter: (prop) => (prop.parent ? !/node_modules/.test(prop.parent.fileName) : true),
+        },
+    },
+};
+
+export default config;

package/.storybook/preview.tsx

@@ -0,0 +1,39 @@
+import '@xcelsior/design-system/styles';
+import type { Preview } from '@storybook/react';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { ToastContainer } from '@xcelsior/design-system';
+
+const queryClient = new QueryClient({
+    defaultOptions: {
+        queries: {
+            retry: false,
+        },
+    },
+});
+
+const preview: Preview = {
+    parameters: {
+        actions: { argTypesRegex: '^on[A-Z].*' },
+        controls: {
+            matchers: {
+                color: /(background|color)$/i,
+                date: /Date$/,
+            },
+        },
+        docs: {
+            toc: true,
+        },
+    },
+    tags: ['autodocs'],
+    decorators: [
+        (Story) => (
+            <ToastContainer>
+                <QueryClientProvider client={queryClient}>
+                    <Story />
+                </QueryClientProvider>
+            </ToastContainer>
+        ),
+    ],
+};
+
+export default preview;

package/CHANGELOG.md

@@ -0,0 +1,32 @@
+# Changelog
+
+## 1.0.1
+
+### Patch Changes
+
+- 631caeb: initial version
+
+All notable changes to this project will be documented in this file.
+
+## [1.0.0] - 2025-10-28
+
+### Added
+
+- Initial release of @xcelsior/ui-chat
+- Real-time WebSocket-based chat functionality
+- Emoji picker support with @emoji-mart/react
+- File upload support with progress tracking
+- Typing indicators
+- Read receipts
+- Message status tracking (sent, delivered, read)
+- Support for text, image, and file messages
+- Markdown rendering in messages
+- Dark mode support
+- Responsive design
+- Accessibility features
+- Comprehensive Storybook documentation
+- TypeScript type definitions
+- Custom hooks for WebSocket, messages, file uploads, and typing indicators
+- Individual components for custom implementations
+- Integration with @xcelsior/design-system and @xcelsior/ui-fields
+- Mock WebSocket for Storybook testing

package/README.md

@@ -0,0 +1,526 @@
+# @xcelsior/ui-chat
+
+A comprehensive, real-time chat widget component for React applications with WebSocket support, emoji picker, file uploads, and more.
+
+## Features
+
+- 🔄 **Real-time Communication**: WebSocket-based instant messaging
+- 💬 **Rich Messages**: Support for text, markdown, images, and files
+- 🤖 **AI Assistant**: Visual differentiation for AI-generated messages with robot icon
+- 😊 **Emoji Support**: Built-in emoji picker
+- 📎 **File Uploads**: Upload and share files with progress tracking
+- ⌨️ **Typing Indicators**: Show when users are typing
+- ✓✓ **Read Receipts**: Track message delivery and read status
+- 🎨 **Customizable**: Fully configurable appearance and behavior
+- 📱 **Responsive**: Works great on all screen sizes
+- 🌓 **Dark Mode**: Automatic dark mode support
+- ♿ **Accessible**: Built with accessibility in mind
+
+## Installation
+
+```bash
+pnpm add @xcelsior/ui-chat @xcelsior/design-system @xcelsior/ui-fields
+```
+
+### Peer Dependencies
+
+Make sure you have the following peer dependencies installed:
+
+```bash
+pnpm add react react-dom @tanstack/react-query react-hook-form flowbite-react
+```
+
+## Usage
+
+### Basic Example
+
+```tsx
+import { ChatWidget } from '@xcelsior/ui-chat';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+
+const queryClient = new QueryClient();
+
+function App() {
+    const chatConfig = {
+        websocketUrl: 'wss://your-api.com/chat',
+        userId: 'user-123',
+        userType: 'customer',
+        conversationId: 'conv-456',
+        currentUser: {
+            id: 'user-123',
+            name: 'John Doe',
+            email: 'john@example.com',
+            type: 'customer',
+        },
+    };
+
+    return (
+        <QueryClientProvider client={queryClient}>
+            <ChatWidget config={chatConfig} />
+        </QueryClientProvider>
+    );
+}
+```
+
+### With File Upload
+
+The file upload feature uses a presigned URL approach for secure, direct-to-S3 uploads:
+
+```tsx
+import { ChatWidget } from '@xcelsior/ui-chat';
+
+const chatConfig = {
+    // ... other config
+    fileUpload: {
+        uploadUrl: 'https://your-api.com/attachments/upload-url',
+        maxFileSize: 10 * 1024 * 1024, // 10MB (default)
+        allowedTypes: [
+            'image/jpeg',
+            'image/png',
+            'image/gif',
+            'image/webp',
+            'application/pdf',
+            'application/msword',
+            'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+            'text/plain',
+            'text/csv',
+        ],
+        headers: {
+            'Authorization': 'Bearer your-token',
+        },
+    },
+};
+
+<ChatWidget config={chatConfig} />
+```
+
+**How it works:**
+
+1. User selects a file
+2. Widget requests a presigned upload URL from your API (`POST /attachments/upload-url`)
+3. Widget uploads file directly to S3 using the presigned URL
+4. File becomes accessible via CloudFront CDN
+5. The CloudFront URL is inserted into the message as markdown
+
+**Backend API Contract:**
+
+```typescript
+// Request
+POST /attachments/upload-url
+{
+  "fileName": "document.pdf",
+  "contentType": "application/pdf",
+  "fileSize": 1234567
+}
+
+// Response
+{
+  "data": {
+    "uploadUrl": "https://s3.amazonaws.com/...",      // Presigned URL for upload
+    "attachmentUrl": "https://cdn.example.com/...",   // Final public URL
+    "key": "attachments/uuid.pdf",                     // S3 key
+    "expiresIn": 300                                   // URL expiry (seconds)
+  }
+}
+```
+
+### With Event Callbacks
+
+```tsx
+import { ChatWidget } from '@xcelsior/ui-chat';
+
+const chatConfig = {
+    // ... other config
+    onMessageSent: (message) => {
+        console.log('Message sent:', message);
+    },
+    onMessageReceived: (message) => {
+        console.log('Message received:', message);
+    },
+    onConnectionChange: (connected) => {
+        console.log('Connection status:', connected);
+    },
+    onError: (error) => {
+        console.error('Chat error:', error);
+    },
+    toast: {
+        success: (message) => console.log('Success:', message),
+        error: (message) => console.error('Error:', message),
+        info: (message) => console.log('Info:', message),
+    },
+};
+
+<ChatWidget config={chatConfig} />
+```
+
+## Configuration
+
+### IChatConfig
+
+The main configuration object for the chat widget.
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `websocketUrl` | `string` | ✓ | WebSocket server URL |
+| `userId` | `string` | ✓ | Current user's ID |
+| `userType` | `'customer' \| 'agent'` | ✓ | Type of user |
+| `currentUser` | `IUser` | ✓ | Current user information |
+| `conversationId` | `string` | | Conversation ID (auto-generated if not provided) |
+| `httpApiUrl` | `string` | | REST API URL for fetching data |
+| `headers` | `Record<string, string>` | | HTTP headers for API requests |
+| `fileUpload` | `IFileUploadConfig` | | File upload configuration |
+| `enableEmoji` | `boolean` | | Enable emoji picker (default: true) |
+| `enableFileUpload` | `boolean` | | Enable file uploads (default: true) |
+| `enableTypingIndicator` | `boolean` | | Enable typing indicators (default: true) |
+| `enableReadReceipts` | `boolean` | | Enable read receipts (default: true) |
+| `onMessageSent` | `(message: IMessage) => void` | | Callback when message is sent |
+| `onMessageReceived` | `(message: IMessage) => void` | | Callback when message is received |
+| `onConnectionChange` | `(connected: boolean) => void` | | Callback when connection status changes |
+| `onError` | `(error: Error) => void` | | Callback when error occurs |
+| `toast` | `object` | | Toast notification handlers |
+
+### IFileUploadConfig
+
+Configuration for file uploads.
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `uploadUrl` | `string` | ✓ | Upload endpoint URL |
+| `maxFileSize` | `number` | | Maximum file size in bytes (default: 5MB) |
+| `allowedTypes` | `string[]` | | Allowed MIME types (default: images and PDFs) |
+| `headers` | `Record<string, string>` | | Additional headers for upload request |
+
+## WebSocket Integration
+
+The chat widget connects to your WebSocket API using the following protocol:
+
+### Connection
+
+```
+wss://your-api.com/chat?userId=user-123&userType=customer&conversationId=conv-456
+```
+
+### Sending Messages
+
+```json
+{
+  "action": "sendMessage",
+  "data": {
+    "conversationId": "conv-456",
+    "content": "Hello!",
+    "messageType": "text"
+  }
+}
+```
+
+### Receiving Messages
+
+```json
+{
+  "type": "message",
+  "data": {
+    "id": "msg-789",
+    "conversationId": "conv-456",
+    "senderId": "agent-123",
+    "senderType": "agent",
+    "content": "Hi! How can I help?",
+    "messageType": "text",
+    "createdAt": "2025-10-28T12:00:00Z",
+    "status": "delivered"
+  }
+}
+```
+
+### Typing Indicator
+
+```json
+{
+  "action": "typing",
+  "data": {
+    "conversationId": "conv-456",
+    "isTyping": true
+  }
+}
+```
+
+## REST API Integration
+
+The chat widget can fetch existing messages from your REST API when `httpApiUrl` is provided in the config.
+
+### Fetching Messages
+
+When the widget loads or the `conversationId` changes, it will automatically fetch existing messages:
+
+```
+GET /messages?conversationId=conv-456&limit=50
+```
+
+Expected response format:
+
+```json
+{
+  "success": true,
+  "data": {
+    "items": [...messages],
+    "nextPageToken": "optional-pagination-token"
+  }
+}
+```
+
+or alternatively:
+
+```json
+{
+  "success": true,
+  "data": [...messages],
+  "nextToken": "optional-pagination-token"
+}
+```
+
+### Example with HTTP API
+
+```tsx
+const chatConfig = {
+    websocketUrl: 'wss://your-api.com/chat',
+    httpApiUrl: 'https://your-api.com',
+    conversationId: 'conv-456',
+    headers: {
+        'Authorization': 'Bearer your-token',
+    },
+    // ... other config
+};
+
+<ChatWidget config={chatConfig} />
+```
+
+## Performance Optimizations
+
+### Debounced Typing Indicator
+
+The typing indicator is now debounced to reduce unnecessary WebSocket messages:
+- **Start typing**: Sent after 300ms of typing activity
+- **Stop typing**: Sent after 1.5s of inactivity
+- This reduces WebSocket traffic while maintaining responsive user feedback
+
+## Components
+
+### ChatWidget
+
+The main chat widget component that includes all features.
+
+```tsx
+import { ChatWidget } from '@xcelsior/ui-chat';
+
+<ChatWidget config={chatConfig} className="custom-class" />
+```
+
+### Individual Components
+
+For custom implementations, you can use individual components:
+
+#### MessageList
+
+```tsx
+import { MessageList } from '@xcelsior/ui-chat';
+
+<MessageList
+    messages={messages}
+    currentUser={currentUser}
+    isTyping={false}
+    autoScroll={true}
+/>
+```
+
+#### MessageItem
+
+Displays individual messages with automatic icon detection:
+- 🤖 **Robot icon** for AI-generated messages (when `metadata.isAI === true`)
+- 🎧 **Headset icon** for human agent messages
+- 👤 **User icon** for customer messages
+
+```tsx
+import { MessageItem } from '@xcelsior/ui-chat';
+
+// Regular agent message
+<MessageItem
+    message={message}
+    currentUser={currentUser}
+    showAvatar={true}
+    showTimestamp={true}
+/>
+
+// AI-generated message (automatically shows robot icon)
+<MessageItem
+    message={{
+        ...message,
+        senderType: 'agent',
+        metadata: { isAI: true }
+    }}
+    currentUser={currentUser}
+    showAvatar={true}
+    showTimestamp={true}
+/>
+```
+
+#### ChatInput
+
+```tsx
+import { ChatInput } from '@xcelsior/ui-chat';
+
+<ChatInput
+    onSend={handleSend}
+    onTyping={handleTyping}
+    config={chatConfig}
+    fileUpload={fileUploadHook}
+/>
+```
+
+#### ChatHeader
+
+```tsx
+import { ChatHeader } from '@xcelsior/ui-chat';
+
+<ChatHeader
+    agent={agent}
+    onClose={handleClose}
+    onMinimize={handleMinimize}
+/>
+```
+
+## Hooks
+
+### useWebSocket
+
+Custom hook for WebSocket connection management.
+
+```tsx
+import { useWebSocket } from '@xcelsior/ui-chat';
+
+const { isConnected, sendMessage, lastMessage, error, reconnect } = useWebSocket(config);
+```
+
+### useMessages
+
+Custom hook for message management.
+
+```tsx
+import { useMessages } from '@xcelsior/ui-chat';
+
+const { messages, addMessage, updateMessageStatus, clearMessages } = useMessages(websocket, config);
+```
+
+### useFileUpload
+
+Custom hook for file uploads.
+
+```tsx
+import { useFileUpload } from '@xcelsior/ui-chat';
+
+const { uploadFile, isUploading, uploadProgress, error, canUpload } = useFileUpload(config);
+```
+
+### useTypingIndicator
+
+Custom hook for typing indicators.
+
+```tsx
+import { useTypingIndicator } from '@xcelsior/ui-chat';
+
+const { isTyping, typingUsers } = useTypingIndicator(websocket);
+```
+
+## Styling
+
+The component uses Tailwind CSS for styling and supports dark mode automatically. You can customize the appearance by:
+
+1. **Using the className prop**: Pass custom classes to the ChatWidget component
+2. **Overriding CSS variables**: Define custom CSS variables for colors and sizes
+3. **Using Tailwind configuration**: Extend your Tailwind config to customize the design system
+
+## Backend Integration
+
+This package is designed to work with the `@xcelsior/chat-api` backend service. For more information on setting up the backend, see the [chat-api documentation](../../services/chat-api/README.md).
+
+### Required Backend Endpoints
+
+- **WebSocket**: For real-time communication
+  - `$connect`: Handle new connections
+  - `$disconnect`: Handle disconnections
+  - `sendMessage`: Handle message sending
+  - `typing`: Handle typing indicators
+
+- **REST API** (optional): For fetching historical data
+  - `GET /messages?conversationId=xxx`: Fetch message history
+  - `GET /conversations/:id`: Fetch conversation details
+
+- **File Upload API** (optional): For file attachment support
+  - `POST /attachments/upload-url`: Generate presigned S3 upload URL
+    - Request: `{ fileName, contentType, fileSize }`
+    - Response: `{ uploadUrl, attachmentUrl, key, expiresIn }`
+
+## Examples
+
+Check out the Storybook for live examples and interactive demos:
+
+```bash
+pnpm storybook
+```
+
+## Development
+
+### Build
+
+```bash
+pnpm build
+```
+
+### Development Mode
+
+```bash
+pnpm dev
+```
+
+### Storybook
+
+```bash
+pnpm storybook
+```
+
+### Lint
+
+```bash
+pnpm lint
+```
+
+## TypeScript
+
+This package is written in TypeScript and includes full type definitions. All types are exported from the main package:
+
+```tsx
+import type {
+    IChatConfig,
+    IMessage,
+    IUser,
+    IConversation,
+    MessageType,
+    MessageStatus,
+} from '@xcelsior/ui-chat';
+```
+
+## Browser Support
+
+- Chrome (latest)
+- Firefox (latest)
+- Safari (latest)
+- Edge (latest)
+
+WebSocket support is required.
+
+## License
+
+MIT
+
+## Support
+
+For issues and questions, please contact the development team or create an issue in the repository.
+

package/biome.json

@@ -0,0 +1,3 @@
+{
+    "extends": "//"
+}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@xcelsior/ui-chat",
+  "version": "1.0.1",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "sideEffects": false,
+  "license": "MIT",
+  "devDependencies": {
+    "@storybook/addon-essentials": "^8.6.14",
+    "@storybook/addon-interactions": "^8.6.14",
+    "@storybook/addon-links": "^8.6.14",
+    "@storybook/addon-onboarding": "^8.6.14",
+    "@storybook/blocks": "^8.6.14",
+    "@storybook/nextjs": "^8.6.14",
+    "@storybook/react": "^8.6.14",
+    "@storybook/react-vite": "^8.6.14",
+    "@storybook/testing-library": "^0.2.2",
+    "@types/react": "^18.2.0",
+    "@types/react-dom": "^18.2.0",
+    "@types/node": "^24.9.2",
+    "react": "^18.2.0",
+    "storybook": "^8.6.14",
+    "@tailwindcss/postcss": "^4.1.13",
+    "tsup": "^8.0.2",
+    "typescript": "^5.3.3",
+    "@xcelsior/design-system": "1.0.4",
+    "@xcelsior/ui-fields": "1.0.3"
+  },
+  "peerDependencies": {
+    "@xcelsior/design-system": "^1",
+    "@xcelsior/ui-fields": "^1",
+    "flowbite-react": "^0.12",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "react-hook-form": "^7",
+    "@tanstack/react-query": "^5.24.1"
+  },
+  "dependencies": {
+    "@emoji-mart/react": "^1.1.1",
+    "axios": "^1.6.7",
+    "date-fns": "^3.3.1",
+    "react-markdown": "^9.0.1"
+  },
+  "exports": {
+    ".": {
+      "import": "./src/index.tsx",
+      "require": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsup src/index.tsx --format esm,cjs --dts --external react",
+    "dev": "tsup src/index.tsx --format esm,cjs --watch --dts --external react",
+    "prepublish": "npm run build",
+    "lint": "biome check .",
+    "clean": "rm -rf .turbo && rm -rf node_modules && rm -rf dist",
+    "storybook": "storybook dev -p 6007",
+    "build-storybook": "storybook build",
+    "predeploy": "npm run build-storybook",
+    "deploy": "aws s3 sync storybook-static/ s3://excelsior-ui-chat --delete"
+  }
+}

package/postcss.config.js

@@ -0,0 +1,5 @@
+module.exports = {
+    plugins: {
+        '@tailwindcss/postcss': {},
+    },
+};