@college-africa/chat-ui 0.1.0

package/README.md

@@ -0,0 +1,141 @@
+# Chat UI Component Library
+
+React chat UI component library for College Africa Chat service. Built with Material UI and TypeScript.
+
+## Features
+
+- 🎨 **Material UI Integration** - Beautiful, accessible components
+- 🚀 **Optimistic Updates** - Instant feedback for better UX
+- 💾 **Offline-First** - IndexedDB caching with background sync
+- 🔌 **WebSocket Support** - Real-time message delivery
+- 📱 **Responsive Design** - Works on all screen sizes
+- 🎯 **TypeScript** - Full type safety
+- ⚡ **Vite Build** - Fast development and optimized production builds
+
+## Installation
+
+```bash
+# This package is part of the monorepo
+yarn workspace ui install
+```
+
+## Development
+
+```bash
+# Run demo application
+yarn workspace ui dev
+
+# Build library
+yarn workspace ui build
+
+# Run tests
+yarn workspace ui test
+
+# Run tests with UI
+yarn workspace ui test:ui
+
+# Type check
+yarn workspace ui typecheck
+```
+
+## Usage
+
+```tsx
+import { ChatApp, ChatContainer, theme } from 'ui';
+import { ThemeProvider } from '@mui/material/styles';
+import CssBaseline from '@mui/material/CssBaseline';
+
+function App() {
+  return (
+    <ThemeProvider theme={theme}>
+      <CssBaseline />
+      <ChatApp
+        config={{ baseURL: 'https://chat.college.africa' }}
+        token={yourJwtToken}
+      >
+        <ChatContainer />
+      </ChatApp>
+    </ThemeProvider>
+  );
+}
+```
+
+## Architecture
+
+### Component Structure
+```
+ChatApp (SDK initialization wrapper)
+└── ChatContainer (full-page layout)
+    ├── ConversationList (sidebar)
+    │   └── ConversationItem[] (with unread badges)
+    └── ChatWindow (selected conversation)
+        ├── MessageList (infinite scroll)
+        └── MessageInput
+```
+
+### State Management
+- **Singleton SDK Pattern** - No React Context needed
+- **Local Component State** - Each component manages its own data
+- **IndexedDB Cache** - Offline-first with background sync
+
+### Cache Strategy
+1. Load cached data instantly (if available)
+2. Fetch fresh data in background
+3. Update UI with fresh data
+4. WebSocket updates append to cache
+
+## API
+
+### Components
+- `ChatApp` - SDK initialization wrapper
+- `ChatContainer` - Main chat container
+- `ConversationList` - List of conversations
+- `ChatWindow` - Message display and input
+
+### Hooks
+- `useMessages` - Fetch and manage messages
+- `useSendMessage` - Send messages with optimistic updates
+- `useConversationList` - Fetch conversation list with unread counts
+
+### SDK Singleton
+```tsx
+import { initSDK, getSDK, disconnectSDK } from 'ui';
+
+// Initialize (done by ChatApp component)
+await initSDK({ baseURL: 'https://...' }, token);
+
+// Access anywhere in your app
+const sdk = getSDK();
+await sdk.sendGroupMessage({ groupId: '123', content: 'Hello' });
+
+// Cleanup on logout
+disconnectSDK();
+```
+
+### Theme
+```tsx
+import { theme } from 'ui';
+
+// Use the theme
+<ThemeProvider theme={theme}>
+  {/* ... */}
+</ThemeProvider>
+
+// Access chat colors for custom components
+<Box sx={{ backgroundColor: "primary.main" }}>
+  {/* ... */}
+</Box>
+```
+
+## Development Status
+
+- [x] Phase 1: Foundation (setup, utils, theme, cache)
+- [ ] Phase 2: SDK & Hooks
+- [ ] Phase 3: Core Components
+- [ ] Phase 4: Real-Time Features
+- [ ] Phase 5: Demo Application
+- [ ] Phase 6: Polish & Documentation
+
+## License
+
+Private - College Africa

package/dist/cache/keys.d.ts

@@ -0,0 +1,8 @@
+import { Conversation, Message } from '../types';
+/** Get conversation id from conversation */
+export declare const getConverSationId: ({ type, id }: Conversation) => string;
+export declare const getSummaryId: ({ group, user }: {
+    group?: string | number;
+    user?: string | number;
+}) => `group:${string}` | `group:${number}` | `user:${string}` | `user:${number}`;
+export declare const getMessageConversationId: (message: Message, currentUserId: number) => string;

package/dist/components/ChatApp.d.ts

@@ -0,0 +1,24 @@
+import { default as React } from 'react';
+import { ChatClientConfig } from 'sdk';
+export interface ChatAppProps {
+    /** SDK configuration */
+    config: ChatClientConfig;
+    /** Authentication token (optional, can be set later via SDK) */
+    token?: string;
+    /** Token fetcher function (alternative to token prop) */
+    getToken?: () => Promise<string>;
+    /** Child components to render when SDK is ready */
+    children: React.ReactNode;
+    /** Custom loading component */
+    LoadingComponent?: React.ComponentType;
+    /** Custom error component */
+    ErrorComponent?: React.ComponentType<{
+        error: Error;
+        retry: () => void;
+    }>;
+}
+/**
+ * ChatApp component
+ * Initializes the SDK singleton and manages its lifecycle
+ */
+export declare const ChatApp: React.FC<ChatAppProps>;

package/dist/components/ChatContainer.d.ts

@@ -0,0 +1,12 @@
+import { default as React } from 'react';
+import { Conversation } from '../types';
+export interface ChatContainerProps {
+    /** Initial conversation to display (optional) */
+    initialConversation?: Conversation;
+}
+/**
+ * ChatContainer component
+ * Two-column layout with conversation list sidebar and chat window
+ * On mobile (<=sm), shows conversation list or chat window in fullwidth, with back navigation
+ */
+export declare const ChatContainer: React.FC<ChatContainerProps>;

package/dist/components/ChatHeader.d.ts

@@ -0,0 +1,18 @@
+import { default as React } from 'react';
+export interface ChatHeaderProps {
+    /** Display name of the conversation */
+    displayName: string;
+    /** Type of conversation */
+    type: "group" | "dm";
+    /** Optional subtitle (e.g., "3 members", "Active now") */
+    subtitle?: string;
+    /** WebSocket connection status */
+    isConnected?: boolean;
+    /** Back handler for mobile navigation (optional) */
+    onBack?: () => void;
+}
+/**
+ * ChatHeader component
+ * Shows conversation name, avatar, optional subtitle, and connection status
+ */
+export declare const ChatHeader: React.FC<ChatHeaderProps>;

package/dist/components/ChatWindow.d.ts

@@ -0,0 +1,17 @@
+import { default as React } from 'react';
+import { User, Conversation } from '../types';
+export interface ChatWindowProps {
+    /** Conversation object containing type, ID, and optional name */
+    conversation: Conversation;
+    /** Current user (fetched by ChatContainer) */
+    user: User;
+    /** WebSocket connection status */
+    /** Back handler for mobile navigation (optional) */
+    onBack?: () => void;
+    isConnected: boolean;
+}
+/**
+ * ChatWindow component
+ * Complete chat interface with header, message list, and input
+ */
+export declare const ChatWindow: React.FC<ChatWindowProps>;

package/dist/components/ConversationItem.d.ts

@@ -0,0 +1,17 @@
+import { default as React } from 'react';
+import { ConversationSummary } from 'sdk';
+export interface ConversationItemProps {
+    /** Conversation summary data */
+    conversation: ConversationSummary;
+    /** Display name for the conversation */
+    displayName: string;
+    /** Whether this conversation is selected */
+    selected: boolean;
+    /** Click handler */
+    onClick: () => void;
+}
+/**
+ * ConversationItem component
+ * Shows conversation name, last message preview, timestamp, and unread badge
+ */
+export declare const ConversationItem: React.FC<ConversationItemProps>;

package/dist/components/ConversationItemSkeleton.d.ts

@@ -0,0 +1,6 @@
+import { default as React } from 'react';
+/**
+ * ConversationItemSkeleton component
+ * Displays a loading skeleton for conversation list items
+ */
+export declare const ConversationItemSkeleton: React.FC;

package/dist/components/ConversationList.d.ts

@@ -0,0 +1,14 @@
+import { default as React } from 'react';
+import { Conversation, User } from '../types';
+export interface ConversationListProps {
+    currentUser?: User;
+    /** Currently selected conversation */
+    selectedConversation: Conversation | null;
+    /** Handler for conversation selection */
+    onConversationSelect: (conversation: Conversation) => void;
+}
+/**
+ * ConversationList component
+ * Displays a scrollable list of all conversations with summaries
+ */
+export declare const ConversationList: React.FC<ConversationListProps>;

package/dist/components/ErrorBoundary.d.ts

@@ -0,0 +1,25 @@
+import { Component, ErrorInfo, ReactNode } from 'react';
+interface ErrorBoundaryProps {
+    /** Child components to wrap */
+    children: ReactNode;
+    /** Optional fallback UI */
+    fallback?: ReactNode;
+    /** Optional error handler callback */
+    onError?: (error: Error, errorInfo: ErrorInfo) => void;
+}
+interface ErrorBoundaryState {
+    hasError: boolean;
+    error: Error | null;
+}
+/**
+ * ErrorBoundary component
+ * Catches React errors in child components and displays a fallback UI
+ */
+export declare class ErrorBoundary extends Component<ErrorBoundaryProps, ErrorBoundaryState> {
+    constructor(props: ErrorBoundaryProps);
+    static getDerivedStateFromError(error: Error): ErrorBoundaryState;
+    componentDidCatch(error: Error, errorInfo: ErrorInfo): void;
+    handleReset: () => void;
+    render(): string | number | bigint | boolean | Iterable<ReactNode> | Promise<string | number | bigint | boolean | import('react').ReactPortal | import('react').ReactElement<unknown, string | import('react').JSXElementConstructor<any>> | Iterable<ReactNode> | null | undefined> | import("react/jsx-runtime").JSX.Element | null | undefined;
+}
+export {};

package/dist/components/LoadMoreTrigger.d.ts

@@ -0,0 +1,18 @@
+import { default as React } from 'react';
+export interface LoadMoreTriggerProps {
+    /** Whether there are more items to load */
+    hasMore: boolean;
+    /** Whether currently loading */
+    loading: boolean;
+    /** Callback to load more items */
+    onLoadMore: () => void;
+    /** Optional threshold for triggering (0.0 to 1.0, default: 1.0) */
+    threshold?: number;
+    /** Optional root margin (default: '100px') */
+    rootMargin?: string;
+}
+/**
+ * LoadMoreTrigger component
+ * Automatically triggers onLoadMore when the component is scrolled into view
+ */
+export declare const LoadMoreTrigger: React.FC<LoadMoreTriggerProps>;

package/dist/components/MessageBubble.d.ts

@@ -0,0 +1,23 @@
+import { default as React } from 'react';
+import { Message } from 'sdk';
+export interface MessageBubbleProps {
+    /** The message to display */
+    message: Message;
+    /** Whether this message was sent by the current user */
+    isOwnMessage: boolean;
+    /** Optional sender name to display (if not provided, shows "User {id}") */
+    senderName?: string;
+    /** Whether to show sender name (hide for grouped messages) */
+    showSenderName?: boolean;
+    /** Whether this is the first message in a group */
+    isFirstInGroup?: boolean;
+    /** Whether this is the last message in a group */
+    isLastInGroup?: boolean;
+    /** Message send status (for optimistic UI) */
+    status?: "sending" | "sent" | "failed";
+}
+/**
+ * MessageBubble component
+ * Displays a single message with sender info, content, and timestamp
+ */
+export declare const MessageBubble: React.FC<MessageBubbleProps>;

package/dist/components/MessageInput.d.ts

@@ -0,0 +1,16 @@
+import { default as React } from 'react';
+export interface MessageInputProps {
+    /** Callback when a message is sent */
+    onSend: (content: string) => void;
+    /** Whether a message is currently being sent */
+    sending?: boolean;
+    /** Placeholder text */
+    placeholder?: string;
+    /** Disabled state */
+    disabled?: boolean;
+}
+/**
+ * MessageInput component
+ * Text field with send button for composing and sending messages
+ */
+export declare const MessageInput: React.FC<MessageInputProps>;

package/dist/components/MessageList.d.ts

@@ -0,0 +1,27 @@
+import { default as React } from 'react';
+import { Message } from 'sdk';
+export interface MessageListProps {
+    /** List of messages to display */
+    messages: Message[];
+    /** ID of the current user */
+    currentUserId: number;
+    /** Whether messages are loading */
+    loading?: boolean;
+    /** Error message if any */
+    error?: Error | null;
+    /** Whether to auto-scroll to bottom on new messages */
+    autoScroll?: boolean;
+    /** Whether there are more messages to load */
+    hasMore?: boolean;
+    /** Whether currently loading more messages */
+    loadingMore?: boolean;
+    /** Callback to load more messages */
+    onLoadMore?: () => void;
+    /** Force scroll to bottom (e.g., when user sends a message) */
+    forceScrollToBottom?: boolean;
+}
+/**
+ * MessageList component
+ * Displays a scrollable list of messages with auto-scroll to bottom
+ */
+export declare const MessageList: React.FC<MessageListProps>;

package/dist/components/MessageSkeleton.d.ts

@@ -0,0 +1,10 @@
+import { default as React } from 'react';
+export interface MessageSkeletonProps {
+    /** Whether this is the current user's message (right-aligned) */
+    isOwnMessage?: boolean;
+}
+/**
+ * MessageSkeleton component
+ * Displays a loading skeleton for message bubbles
+ */
+export declare const MessageSkeleton: React.FC<MessageSkeletonProps>;

package/dist/components/UnreadBadge.d.ts

@@ -0,0 +1,14 @@
+import { default as React } from 'react';
+export interface UnreadBadgeProps {
+    /** Number of unread messages */
+    count: number;
+    /** Child element to wrap */
+    children: React.ReactNode;
+    /** Maximum number to display (shows "99+" if exceeded) */
+    max?: number;
+}
+/**
+ * UnreadBadge component
+ * Displays a badge with unread message count
+ */
+export declare const UnreadBadge: React.FC<UnreadBadgeProps>;

package/dist/components/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Components barrel export
+ */
+export { ChatApp } from './ChatApp';
+export type { ChatAppProps } from './ChatApp';
+export { ChatWindow } from './ChatWindow';
+export type { ChatWindowProps } from './ChatWindow';
+export { MessageList } from './MessageList';
+export type { MessageListProps } from './MessageList';
+export { MessageBubble } from './MessageBubble';
+export type { MessageBubbleProps } from './MessageBubble';
+export { MessageInput } from './MessageInput';
+export type { MessageInputProps } from './MessageInput';

package/dist/hooks/constants.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Cache TTL constants (in milliseconds)
+ */
+export declare const CACHE_TTL: {
+    readonly SUMMARIES: number;
+    readonly USER: number;
+    readonly MESSAGES: number;
+};
+/**
+ * Default stale time for cached data (5 minutes)
+ */
+export declare const DEFAULT_STALE_TIME: number;

package/dist/hooks/useEffectAsync.d.ts

@@ -0,0 +1,8 @@
+import { DependencyList } from 'react';
+/**
+ * Asynchronous version of React.useEffect
+ * @param {Function} fn Async function to run
+ * @param {Array} deps Hook dependencies
+ */
+declare const useEffectAsync: (fn: () => Promise<void>, deps: DependencyList, teardown?: () => void) => void;
+export default useEffectAsync;

package/dist/hooks/useMessages.d.ts

@@ -0,0 +1,21 @@
+import { Conversation } from '../types';
+export interface UseMessagesParams {
+    /** Conversation object containing type and ID */
+    conversation: Conversation;
+    /** Number of messages to fetch per page */
+    limit?: number;
+}
+/**
+ * useMessages - Hook for managing messages in a conversation
+ *
+ * Uses IndexedDB as the single source of truth.
+ * All business logic (deduplication, merging, transformations) lives here.
+ */
+export declare function useMessages({ conversation, limit }: UseMessagesParams): {
+    messages: import('../types').CachedMessage[];
+    cursor: import('../types').CachedCursor | undefined;
+    loading: boolean;
+    error: Error | undefined;
+    loadMore: () => Promise<void>;
+    loadingMore: boolean;
+};

package/dist/hooks/useSenderNames.d.ts

@@ -0,0 +1,3 @@
+import { Message } from 'sdk';
+/** Get a map of <userid, username> for message senders */
+export declare function useSenderNames(messages: Message[]): Map<number, string>;

package/dist/hooks/useWebSocketMessages.d.ts

@@ -0,0 +1,23 @@
+import { Message } from 'sdk';
+import { Conversation } from '../types';
+export interface UseWebSocketMessagesParams {
+    /** Callback when a new message is received */
+    onMessage?: (message: Message) => void;
+    /** Callback when WebSocket connection opens */
+    onConnect?: () => void;
+    /** Callback when WebSocket connection closes */
+    onDisconnect?: (code: number, reason: string) => void;
+    /** Callback when WebSocket error occurs */
+    onError?: (error: Error) => void;
+    /** Current user ID for filtering messages */
+    currentUserId?: number;
+    /** Current conversation object */
+    conversation?: Conversation | null;
+    /** Whether to automatically update cache */
+    updateCache?: boolean;
+}
+/**
+ * Hook for handling WebSocket message events
+ * Automatically subscribes/unsubscribes to WebSocket events
+ */
+export declare function useWebSocketMessages({ onMessage, onConnect, onDisconnect, onError, currentUserId, conversation, updateCache }?: UseWebSocketMessagesParams): void;

package/dist/index.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Chat UI Component Library
+ * React components and hooks for building chat interfaces
+ */
+export { ChatApp } from './components/ChatApp';
+export type { ChatAppProps } from './components/ChatApp';
+export { ChatContainer } from './components/ChatContainer';
+export type { ChatContainerProps } from './components/ChatContainer';
+export { ChatWindow } from './components/ChatWindow';
+export type { ChatWindowProps } from './components/ChatWindow';
+export { ChatHeader } from './components/ChatHeader';
+export type { ChatHeaderProps } from './components/ChatHeader';
+export { ConversationList } from './components/ConversationList';
+export type { ConversationListProps } from './components/ConversationList';
+export { ConversationItem } from './components/ConversationItem';
+export type { ConversationItemProps } from './components/ConversationItem';
+export { MessageList } from './components/MessageList';
+export type { MessageListProps } from './components/MessageList';
+export { MessageBubble } from './components/MessageBubble';
+export type { MessageBubbleProps } from './components/MessageBubble';
+export { MessageInput } from './components/MessageInput';
+export type { MessageInputProps } from './components/MessageInput';
+export { LoadMoreTrigger } from './components/LoadMoreTrigger';
+export type { LoadMoreTriggerProps } from './components/LoadMoreTrigger';
+export { UnreadBadge } from './components/UnreadBadge';
+export type { UnreadBadgeProps } from './components/UnreadBadge';
+export { ErrorBoundary } from './components/ErrorBoundary';
+export { ConversationItemSkeleton } from './components/ConversationItemSkeleton';
+export { MessageSkeleton } from './components/MessageSkeleton';
+export type { MessageSkeletonProps } from './components/MessageSkeleton';
+export { initSDK, getSDK, disconnectSDK, isSDKInitialized } from './utils/sdk';
+export { groupMessages, shouldGroupMessages } from './utils/messages';
+export type { MessageGroup } from './utils/messages';
+export { useMessages } from './hooks/useMessages';
+export type { UseMessagesParams } from './hooks/useMessages';
+export { useWebSocketMessages } from './hooks/useWebSocketMessages';
+export type { UseWebSocketMessagesParams } from './hooks/useWebSocketMessages';
+export { useSenderNames } from './hooks/useSenderNames';
+export { CACHE_TTL } from './hooks/constants';
+export type { User, Message, Group, ConversationSummary, ChatRole, Cursor, MessagePage, ConnectionState, Conversation } from './types';
+export { theme } from './utils/theme';