@xcelsior/ui-chat 1.0.4 → 1.0.6

package/.turbo/turbo-lint.log

@@ -0,0 +1,5 @@
+
+> @xcelsior/ui-chat@1.0.0 lint /Users/tuannguyen/Work/xcelsior-packages/packages/ui/ui-chat
+> biome check .
+
+Checked 24 files in 17ms. No fixes applied.

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 1.0.6
+
+### Patch Changes
+
+- improve minimize
+
 ## 1.0.2
 
 ### Patch Changes

package/README.md

@@ -62,6 +62,88 @@ function App() {
 }
 ```
 
+### Chat Widget States (Bubble Mode)
+
+The chat widget supports three states in popover mode:
+
+- **`open`**: Fully open with chat interface visible
+- **`minimized`**: Show bubble button only (default)
+- **`closed`**: Fully hidden, no bubble visible
+
+#### Uncontrolled Mode (Default)
+
+By default, the widget starts in `minimized` state and manages its own state:
+
+```tsx
+import { ChatWidget } from '@xcelsior/ui-chat';
+
+function App() {
+    return (
+        <ChatWidget 
+            config={chatConfig}
+            // Starts minimized by default
+        />
+    );
+}
+```
+
+You can also set a different default state:
+
+```tsx
+<ChatWidget 
+    config={chatConfig}
+    defaultState="open" // or "minimized" or "closed"
+/>
+```
+
+#### Controlled Mode
+
+Control the widget state externally:
+
+```tsx
+import { ChatWidget, ChatWidgetState } from '@xcelsior/ui-chat';
+import { useState } from 'react';
+
+function App() {
+    const [chatState, setChatState] = useState<ChatWidgetState>('minimized');
+
+    return (
+        <>
+            <button onClick={() => setChatState('open')}>
+                Open Chat
+            </button>
+            <button onClick={() => setChatState('minimized')}>
+                Minimize Chat
+            </button>
+            <button onClick={() => setChatState('closed')}>
+                Close Chat
+            </button>
+            
+            <ChatWidget 
+                config={chatConfig}
+                state={chatState}
+                onStateChange={setChatState}
+            />
+        </>
+    );
+}
+```
+
+#### Listen to State Changes (Semi-controlled)
+
+You can listen to state changes while keeping the widget uncontrolled:
+
+```tsx
+<ChatWidget 
+    config={chatConfig}
+    defaultState="minimized"
+    onStateChange={(state) => {
+        console.log('Chat state changed to:', state);
+        // Save to localStorage, analytics, etc.
+    }}
+/>
+```
+
 ### With File Upload
 
 The file upload feature uses a presigned URL approach for secure, direct-to-S3 uploads:

package/dist/index.d.mts

@@ -0,0 +1,337 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+
+interface IUser {
+    name: string;
+    email: string;
+    avatar?: string;
+    type: 'customer' | 'agent';
+    status?: 'online' | 'offline' | 'away' | 'busy';
+}
+type MessageType = 'text' | 'image' | 'file' | 'system';
+type MessageStatus = 'sent' | 'delivered' | 'read';
+interface IMessage {
+    id: string;
+    conversationId: string;
+    senderId: string;
+    senderType: 'customer' | 'agent' | 'system';
+    content: string;
+    messageType: MessageType;
+    createdAt: string;
+    status: MessageStatus;
+    metadata?: Record<string, unknown>;
+}
+type ConversationStatus = 'open' | 'pending' | 'closed' | 'archived';
+type ConversationPriority = 'low' | 'medium' | 'high' | 'urgent';
+type ConversationChannel = 'web' | 'mobile' | 'email';
+interface IConversation {
+    id: string;
+    customerId: string;
+    assignedAgentId?: string;
+    status: ConversationStatus;
+    priority: ConversationPriority;
+    subject?: string;
+    channel: ConversationChannel;
+    tags?: string[];
+    createdAt: string;
+    updatedAt: string;
+    closedAt?: string;
+    lastMessageAt?: string;
+    messageCount?: number;
+    unreadCount?: number;
+    satisfaction?: 1 | 2 | 3 | 4 | 5;
+    metadata?: Record<string, unknown>;
+}
+interface IWebSocketMessage {
+    type: 'message' | 'typing' | 'read' | 'connected' | 'error' | 'system';
+    data: any;
+}
+interface ISendMessageData {
+    conversationId: string;
+    content: string;
+    messageType?: MessageType;
+}
+interface ITypingData {
+    conversationId: string;
+    isTyping: boolean;
+}
+interface IReadMessageData {
+    messageId: string;
+    conversationId: string;
+}
+interface IFileUploadConfig {
+    uploadUrl: string;
+    maxFileSize?: number;
+    allowedTypes?: string[];
+    headers?: Record<string, string>;
+}
+interface IUploadedFile {
+    url: string;
+    name: string;
+    size: number;
+    type: string;
+    markdown?: string;
+}
+interface IChatConfig {
+    websocketUrl: string;
+    conversationId?: string;
+    apiKey: string;
+    currentUser: IUser;
+    fileUpload?: IFileUploadConfig;
+    httpApiUrl?: string;
+    headers?: Record<string, string>;
+    enableEmoji?: boolean;
+    enableFileUpload?: boolean;
+    enableTypingIndicator?: boolean;
+    enableReadReceipts?: boolean;
+    /**
+     * For agents, set this to true to disable creating a WebSocket connection in the chat widget.
+     * Agents should have a global WebSocket connection instead.
+     * @default false
+     */
+    disableWebSocket?: boolean;
+    onMessageSent?: (message: IMessage) => void;
+    onMessageReceived?: (message: IMessage) => void;
+    onConversationChange?: (conversation: IConversation) => void;
+    onConnectionChange?: (connected: boolean) => void;
+    onError?: (error: Error) => void;
+    toast?: {
+        success: (message: string) => void;
+        error: (message: string) => void;
+        info: (message: string) => void;
+    };
+}
+interface IApiResponse<T> {
+    success: boolean;
+    data?: T;
+    error?: {
+        code: string;
+        message: string;
+    };
+    pagination?: {
+        nextPageToken?: string;
+    };
+}
+
+interface ChatWidgetProps {
+    config: IChatConfig;
+    className?: string;
+    /**
+     * Variant of the chat widget:
+     * - 'popover': Fixed positioned floating widget (default)
+     * - 'fullPage': Full page layout that fills the container
+     */
+    variant?: 'popover' | 'fullPage';
+    /**
+     * External WebSocket connection (for agents with global connection)
+     */
+    externalWebSocket?: WebSocket | null;
+    /**
+     * Callback when user wants to minimize the widget
+     */
+    onMinimize?: () => void;
+    /**
+     * Callback when user wants to close the widget
+     */
+    onClose?: () => void;
+}
+declare function ChatWidget({ config, className, variant, externalWebSocket, onMinimize, onClose, }: ChatWidgetProps): react_jsx_runtime.JSX.Element;
+
+type ChatWidgetState = 'open' | 'minimized' | 'closed' | 'undefined';
+interface UseChatWidgetStateOptions {
+    /**
+     * Controlled state. When provided, the component is controlled.
+     */
+    state?: ChatWidgetState;
+    /**
+     * Default state for uncontrolled mode
+     * @default 'minimized'
+     */
+    defaultState?: ChatWidgetState;
+    /**
+     * Callback when state changes
+     */
+    onStateChange?: (state: ChatWidgetState) => void;
+}
+interface UseChatWidgetStateReturn {
+    /**
+     * Current state of the widget
+     */
+    currentState: ChatWidgetState;
+    /**
+     * Function to update the state
+     */
+    setState: (newState: ChatWidgetState) => void;
+    /**
+     * Whether the state is controlled
+     */
+    isControlled: boolean;
+}
+/**
+ * Hook to manage chat widget state (controlled vs uncontrolled)
+ * Encapsulates the logic for handling both controlled and uncontrolled state patterns
+ */
+declare function useChatWidgetState({ state: controlledState, defaultState, onStateChange, }: UseChatWidgetStateOptions): UseChatWidgetStateReturn;
+
+interface ChatWidgetWrapperProps {
+    /**
+     * Base configuration for the chat widget (without user info and conversationId)
+     */
+    config: Omit<IChatConfig, 'currentUser' | 'conversationId' | 'userId'> & {
+        currentUser?: Partial<IUser>;
+        conversationId?: string;
+    };
+    /**
+     * Custom className for the wrapper
+     */
+    className?: string;
+    /**
+     * Storage key prefix for persisting user data
+     * Defaults to 'xcelsior_chat'
+     */
+    storageKeyPrefix?: string;
+    /**
+     * Callback when user submits the pre-chat form
+     */
+    onPreChatSubmit?: (user: IUser) => void;
+    /**
+     * Controlled state. When provided, the component is controlled.
+     * - 'open': Fully open with chat interface
+     * - 'minimized': Show bubble button only
+     * - 'closed': Fully hidden
+     */
+    state?: ChatWidgetState;
+    /**
+     * Default state for uncontrolled mode
+     * @default 'minimized'
+     */
+    defaultState?: ChatWidgetState;
+    /**
+     * Callback when state changes
+     */
+    onStateChange?: (state: ChatWidgetState) => void;
+}
+/**
+ * Chat component that handles:
+ * - Automatic conversation ID generation
+ * - Pre-chat form for collecting user information
+ * - Session persistence in localStorage
+ */
+declare function Chat({ config, className, storageKeyPrefix, onPreChatSubmit, state, defaultState, onStateChange, }: ChatWidgetWrapperProps): react_jsx_runtime.JSX.Element | null;
+
+interface ChatHeaderProps {
+    agent?: IUser;
+    onClose?: () => void;
+    onMinimize?: () => void;
+}
+declare function ChatHeader({ agent, onClose, onMinimize }: ChatHeaderProps): react_jsx_runtime.JSX.Element;
+
+interface UseFileUploadReturn {
+    uploadFile: (file: File) => Promise<IUploadedFile | null>;
+    isUploading: boolean;
+    uploadProgress: number;
+    error: Error | null;
+    canUpload: boolean;
+}
+declare function useFileUpload(apiKey: string, config?: IFileUploadConfig): UseFileUploadReturn;
+
+interface ChatInputProps {
+    onSend: (message: string) => void;
+    onTyping?: (isTyping: boolean) => void;
+    config: IChatConfig;
+    fileUpload: UseFileUploadReturn;
+    disabled?: boolean;
+}
+declare function ChatInput({ onSend, onTyping, config, fileUpload, disabled, }: ChatInputProps): react_jsx_runtime.JSX.Element;
+
+interface MessageItemProps {
+    message: IMessage;
+    currentUser: IUser;
+    showAvatar?: boolean;
+    showTimestamp?: boolean;
+}
+declare function MessageItem({ message, currentUser, showAvatar, showTimestamp, }: MessageItemProps): react_jsx_runtime.JSX.Element;
+
+interface MessageListProps {
+    messages: IMessage[];
+    currentUser: IUser;
+    isLoading?: boolean;
+    isTyping?: boolean;
+    typingUser?: string;
+    autoScroll?: boolean;
+    onLoadMore?: () => void;
+    hasMore?: boolean;
+    isLoadingMore?: boolean;
+}
+declare function MessageList({ messages, currentUser, isLoading, isTyping, typingUser, autoScroll, onLoadMore, hasMore, isLoadingMore, }: MessageListProps): react_jsx_runtime.JSX.Element;
+
+interface TypingIndicatorProps {
+    isTyping: boolean;
+    userName?: string;
+}
+declare function TypingIndicator({ isTyping, userName }: TypingIndicatorProps): react_jsx_runtime.JSX.Element | null;
+
+interface PreChatFormProps {
+    onSubmit: (name: string, email: string) => void;
+    className?: string;
+    initialName?: string;
+    initialEmail?: string;
+    /**
+     * Callback when user wants to minimize the form
+     */
+    onMinimize: () => void;
+    /**
+     * Callback when user wants to close the form
+     */
+    onClose: () => void;
+}
+/**
+ * PreChatForm component for collecting user information before starting chat
+ */
+declare function PreChatForm({ onSubmit, className, initialName, initialEmail, onMinimize, onClose, }: PreChatFormProps): react_jsx_runtime.JSX.Element;
+
+interface UseWebSocketReturn {
+    isConnected: boolean;
+    sendMessage: (action: string, data: any) => void;
+    lastMessage: IWebSocketMessage | null;
+    error: Error | null;
+    reconnect: () => void;
+}
+/**
+ * Hook for WebSocket connection in chat widget.
+ * Can use an external WebSocket connection (for agents) via the externalWebSocket prop.
+ */
+declare function useWebSocket(config: IChatConfig, externalWebSocket?: WebSocket | null): UseWebSocketReturn;
+
+interface UseMessagesReturn {
+    messages: IMessage[];
+    addMessage: (message: IMessage) => void;
+    updateMessageStatus: (messageId: string, status: IMessage['status']) => void;
+    clearMessages: () => void;
+    isLoading: boolean;
+    error: Error | null;
+    loadMore: () => Promise<void>;
+    hasMore: boolean;
+    isLoadingMore: boolean;
+}
+declare function useMessages(websocket: UseWebSocketReturn, config: IChatConfig): UseMessagesReturn;
+
+interface UseTypingIndicatorReturn {
+    isTyping: boolean;
+    typingUsers: string[];
+}
+declare function useTypingIndicator(websocket: UseWebSocketReturn): UseTypingIndicatorReturn;
+
+interface FetchMessagesParams {
+    conversationId: string;
+    limit?: number;
+    pageToken?: string;
+}
+/**
+ * Fetch messages for a conversation from the REST API
+ */
+declare function fetchMessages(baseUrl: string, params: FetchMessagesParams, headers?: Record<string, string>): Promise<{
+    data: IMessage[];
+    nextPageToken: string | undefined;
+}>;
+
+export { Chat, ChatHeader, ChatInput, ChatWidget, type ChatWidgetProps, type ChatWidgetState, type ConversationChannel, type ConversationPriority, type ConversationStatus, type IApiResponse, type IChatConfig, type IConversation, type IFileUploadConfig, type IMessage, type IReadMessageData, type ISendMessageData, type ITypingData, type IUploadedFile, type IUser, type IWebSocketMessage, MessageItem, MessageList, type MessageStatus, type MessageType, PreChatForm, TypingIndicator, type UseChatWidgetStateOptions, type UseChatWidgetStateReturn, fetchMessages, useChatWidgetState, useFileUpload, useMessages, useTypingIndicator, useWebSocket };