Data Chatbot

A configurable and customizable React chat component library built with TypeScript, Vite, and Tailwind CSS.

Features

• 🎨 Fully Customizable - Configure themes, colors, positioning, and more
• 📱 Responsive Design - Works seamlessly on desktop and mobile
• 🔄 Streaming Support - Real-time streaming chat responses with OpenAI-compatible API
• ⏹️ Stop Functionality - Stop streaming responses mid-process with dynamic button states
• 🔍 Expandable Interface - Toggle between normal and full-screen width with expand/minimize button
• ⏱️ Configurable Timeout - Set custom request timeout (default: 120 seconds)
• 📊 Rich Content - Supports markdown tables, links, and formatted text
• 💡 Smart Suggestions - Interactive suggestion bubbles with custom icons that send messages directly
• 📋 Copy Functionality - Easy message copying with clipboard integration
• 💾 Persistent Storage - Messages are automatically saved to localStorage
• 🎯 TypeScript - Full TypeScript support with comprehensive type definitions
• ⚡ Lightweight - Minimal dependencies (Lucide React for icons, Framer Motion for animations)
• 🧪 Well Tested - Comprehensive visual and functional tests with Playwright
• 🎭 Multiple Themes - Built-in themes (default, dark, green, pixie) with custom theme support
• 🎨 Live Theme Editor - Real-time theme customization in development with color pickers and export
• 🔄 Error Handling - Automatic retry functionality with user-friendly error messages
• 🛡️ Input Validation - Built-in message sanitization and validation
• 🎪 Error Boundaries - Graceful error handling with React Error Boundaries
• 🤖 Bot Icons - Visual bot indicators on assistant messages for better UX
• 👍 Feedback System - Thumbs up/down feedback buttons with 5-star rating system and text input
• 🎬 Smooth Animations - Framer Motion powered animations for enhanced user experience
• 🔤 Lato Font - Modern typography with Google Fonts integration
• 📡 Message Listener - Real-time message monitoring for consuming applications
• 🎨 CSS Modules - Scoped styling with CSS modules for better maintainability

Prerequisites

• Node.js >= 20.0.0
• React >= 18.0.0
• React DOM >= 18.0.0

Installation

For End Users (Installing the Package)

# Install the package and required peer dependencies
npm install data-platform-chatbot lucide-react framer-motion
# or
yarn add data-platform-chatbot lucide-react framer-motion
# or
pnpm add data-platform-chatbot lucide-react framer-motion

Why install peer dependencies separately? > lucide-react and framer-motion are peer dependencies to avoid version conflicts and duplicate installations. If you only install data-platform-chatbot, you'll get warnings and missing functionality. Installing all packages ensures compatibility and keeps your bundle size optimal.

CSS Setup

The component uses CSS modules for styling. Simply import the CSS file:

import "data-platform-chatbot/dist/index.css";

The component includes Lato font from Google Fonts and all necessary styles are scoped using CSS modules to avoid conflicts with your application's styles.

⚠️ Required: Proxy Setup for Development

IMPORTANT: The chat component requires a proxy configuration to work in development. Without this, chat requests will fail.

Add this to your vite.config.ts:

import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";

export default defineConfig({
  plugins: [react()],
  server: {
    proxy: {
      "/v1/chat/completions": {
        target: env.VITE_PROXY_TARGET,
        changeOrigin: true,
        secure: false,
        rewrite: (path) =>
          path.replace(/^\/v1\/chat\/completions/, "/v1/chat/completions"),
      },
    },
  },
});

Then use the proxy endpoint in your config:

<ChatAssistant
  config={{
    endpoint: "/v1/chat/completions", // Use proxy path, not direct URL
    // ... other config
  }}
/>

For Development (Cloning the Repository)

# Clone the repository
git clone <repository-url>
cd data-chatbot

# Install dependencies
npm install

# Install Playwright browsers for testing
npx playwright install

# Start development server
npm run dev

Quick Start

import React from "react";
import { ChatAssistant } from "data-platform-chatbot";
import "data-platform-chatbot/dist/index.css";

function App() {
  return (
    <div>
      <h1>My App</h1>
      <ChatAssistant
        config={{
          endpoint: "/v1/chat/completions", // Use proxy endpoint
          title: "My Assistant",
          theme: {
            primary: "#3b82f6",
          },
        }}
      />
    </div>
  );
}

Configuration

The ChatAssistant component accepts a config prop with the following options:

Basic Configuration

interface ChatConfig {
  endpoint?: string; // API endpoint for chat
  model?: string; // Model name to use
  headers?: Record<string, string>; // Custom headers
  title?: string; // Chat window title
  subtitle?: string; // Chat window subtitle
  placeholder?: string; // Input placeholder text
  position?: "bottom-right" | "bottom-left" | "top-right" | "top-left";
  width?: number; // Chat window width
  height?: number; // Chat window height
  timeout?: number; // Request timeout in milliseconds (default: 120000)
  defaultOpen?: boolean; // Open chat by default
  bearerToken?: string; // Bearer token for authentication
  fullHeight?: boolean; // Fill container height (100vh)
  onMessagesChange?: (messages: Message[]) => void; // Message listener callback
  onFeedback?: (messageId: string, feedback: "agree" | "disagree", rating?: number, feedbackText?: string) => void; // Feedback callback
  onClose?: () => void; // Chat close callback
}

Theme Configuration

interface ChatTheme {
  primary?: string; // Primary color
  background?: string; // Background color
  userMessageBg?: string; // User message background
  assistantMessageBg?: string; // Assistant message background
  borderColor?: string; // Border color
  textColor?: string; // Text color
  fabBg?: string; // FAB background color
  fabColor?: string; // FAB icon color
}

Custom Suggestions

Suggestions appear when the input field is focused and send messages directly when clicked (no need to press send):

import {
  Lightbulb,
  HelpCircle,
  MessageSquare,
  ArrowLeftRight,
} from "lucide-react";

const config = {
  suggestions: [
    { icon: <Lightbulb size={15} />, text: "Explain this further" },
    { icon: <HelpCircle size={15} />, text: "Give me an example" },
    { icon: <MessageSquare size={15} />, text: "Possible follow-up questions" },
    { icon: <ArrowLeftRight size={15} />, text: "Show me another options" },
  ],
};

API Integration

The component expects your API endpoint to support streaming responses in the OpenAI format:

// Request format
{
  "model": "your-model",
  "messages": [
    { "role": "user", "content": "Hello!" }
  ],
  "stream": true
}

// Response format (Server-Sent Events)
data: {"choices":[{"delta":{"content":"Hello"}}]}
data: {"choices":[{"delta":{"content":" there!"}}]}
data: [DONE]

Custom Fetch Override

The fetch property in ChatConfig allows you to provide a custom fetch implementation for advanced use cases like authentication token refresh, request logging, or error handling.

Authentication Token Refresh

Handle 401 responses by refreshing authentication tokens and retrying requests automatically:

import { ChatAssistant } from 'data-platform-chatbot';

<ChatAssistant
  config={{
    endpoint: '/api/chatbot/completions',
    fetch: async (input, init) => {
      const response = await fetch(input, init);
      
      if (response.status === 401) {
        // Refresh your authentication token
        const newToken = await refreshAuthToken();
        
        // Retry with the new token
        return fetch(input, {
          ...init,
          headers: {
            ...init?.headers,
            'Authorization': `Bearer ${newToken}`
          }
        });
      }
      
      return response;
    }
  }}
/>

Request Logging

Log all chatbot requests for monitoring and debugging:

<ChatAssistant
  config={{
    fetch: async (input, init) => {
      const startTime = Date.now();
      
      try {
        const response = await fetch(input, init);
        
        console.log('Chatbot request:', {
          url: input.toString(),
          status: response.status,
          duration: Date.now() - startTime
        });
        
        return response;
      } catch (error) {
        console.error('Chatbot request failed:', error);
        throw error;
      }
    }
  }}
/>

Analytics Integration

Track chatbot interactions in your analytics system:

<ChatAssistant
  config={{
    fetch: async (input, init) => {
      const response = await fetch(input, init);
      
      analytics.track('chatbot_request', {
        endpoint: input.toString(),
        status: response.status,
        success: response.ok
      });
      
      return response;
    }
  }}
/>

Important Notes

• Custom fetch MUST return a valid Response object
• Custom fetch SHOULD respect the AbortController signal (passed via init.signal)
• Avoid infinite retry loops — implement max retry limits
• Token refresh should happen exactly once per 401 to prevent recursive retries
• The fetch function receives the complete RequestInit (headers, body, signal, etc.)

Default Behavior

If no custom fetch is provided, the library defaults to window.fetch. This ensures backwards compatibility and zero overhead when the feature is not used.

Development

Available Scripts

# Development
npm run dev              # Start development server with demo
npm run build           # Build demo application
npm run build:lib       # Build library for distribution
npm run preview         # Preview built demo

# Testing
npm test                # Run unit tests with Vitest
npm run test:ui         # Run unit tests with UI
npm run test:clean      # Clean test artifacts and cache
npm run test:e2e        # Run end-to-end tests with Playwright
npm run test:e2e:ui     # Run e2e tests with Playwright UI
npm run test:e2e:debug  # Debug e2e tests
npm run test:visual     # Run visual regression tests
npm run test:report     # Show Playwright HTML test report

# Linting
npm run lint            # Lint code with ESLint
npm run lint:fix        # Fix linting issues

# Playwright
npm run playwright:install  # Install Playwright browsers

Development Workflow

1. Start Development Server

   npm run dev

   This starts the demo application at http://localhost:5173

2. Use Live Theme Editor

   • Click the palette icon in the top-right corner to open the theme editor
   • Adjust colors in real-time with color pickers or hex inputs
   • See changes instantly applied to the chat component
   • Export your custom theme configuration to clipboard
   • Reset to default theme anytime

3. Run Tests During Development

   # Clean test artifacts before running
   npm run test:clean
   
   # Run visual tests to see how components look
   npm run test:visual
   
   # Run functional tests to verify behavior
   npm run test:e2e
   
   # Debug tests interactively
   npm run test:e2e:debug
   
   # View test results in browser
   npm run test:report

4. Build Library

   npm run build:lib

   This creates the distributable library in the dist/ folder

Testing with Playwright

This project includes comprehensive visual and functional testing:

• Visual Tests: Take screenshots and compare visual appearance
• Functional Tests: Test user interactions, API calls, and component behavior
• Cross-browser: Tests run on Chrome, Firefox, Safari, and mobile browsers

# Clean test artifacts first
npm run test:clean

# Run all tests
npm run test:e2e

# Run with UI for debugging
npm run test:e2e:ui

# Run only visual tests
npm run test:visual

# View test report in browser
npm run test:report

Project Structure

data-chatbot/
├── src/
│   ├── lib/                 # Library source code
│   │   ├── components/      # React components
│   │   ├── utils/          # Utility functions
│   │   ├── types.ts        # TypeScript definitions
│   │   └── index.ts        # Main export
│   ├── demo/               # Demo application
│   │   ├── App.tsx         # Demo app component
│   │   └── main.tsx        # Demo entry point
│   └── styles/             # Global styles
├── tests/                  # Playwright tests
├── scripts/                # Build and test scripts
└── dist/                   # Built library (generated)

Examples

Basic Usage

import { ChatAssistant } from "data-platform-chatbot";
import "data-platform-chatbot/dist/index.css";

<ChatAssistant />;

Custom Theme

<ChatAssistant
  config={{
    theme: {
      primary: "#10b981",
      userMessageBg: "#d1fae5",
      assistantMessageBg: "#ecfdf5",
    },
  }}
/>

Pixie Theme

<ChatAssistant
  config={{
    theme: {
      primary: "oklch(42.4% 0.199 265.638)",
      userMessageBg: "#eaeaf8",
      assistantMessageBg: "#EFF3F5",
      borderColor: "#c1c1cd",
      textColor: "#222222",
    },
  }}
/>

Custom Position

<ChatAssistant
  config={{
    position: "bottom-left",
    width: 400,
    height: 500,
  }}
/>

Custom API Configuration

<ChatAssistant
  config={{
    endpoint: "/v1/chat/completions", // Use proxy endpoint
    model: "gpt-4",
    bearerToken: "your-token-here", // Optional bearer token
    headers: {
      "X-Custom-Header": "value",
    },
  }}
/>

Full Height Layout

<ChatAssistant
  config={{
    fullHeight: true, // Fill container height (100vh)
    // ... other config
  }}
/>

Message Listener

Monitor chat messages in real-time for analytics, logging, or integration with other systems:

const handleMessagesChange = (messages) => {
  console.log('Chat messages updated:', messages);
  // Send to analytics, save to database, etc.
};

<ChatAssistant
  config={{
    onMessagesChange: handleMessagesChange,
    // ... other config
  }}
/>

// Or as direct prop
<ChatAssistant onMessagesChange={handleMessagesChange} />

Feedback System with Rating

Capture user feedback with 5-star rating system and text input:

const handleFeedback = (
  messageId: string,
  feedback: "agree" | "disagree",
  rating?: number,
  feedbackText?: string
) => {
  console.log("Feedback received:", {
    messageId,
    feedback,
    rating, // 1-5 stars (mandatory)
    feedbackText, // Optional text feedback
    timestamp: new Date().toISOString(),
  });
  // Send to your backend, analytics, etc.
};

<ChatAssistant
  config={{
    onFeedback: handleFeedback,
    // ... other config
  }}
/>

Chat Close Event

Capture when user closes the chat:

const handleClose = () => {
  console.log("Chat closed at:", new Date().toISOString());
  // Track analytics, save state, etc.
};

<ChatAssistant
  config={{
    onClose: handleClose,
    // ... other config
  }}
/>

Live Theme Development

In development mode, use the live theme editor to create custom themes:

1. Open Theme Editor: Click the palette icon in the top-right corner
2. Adjust Colors: Use color pickers or enter hex values directly
3. See Changes Live: Watch the chat component update in real-time
4. Export Theme: Copy the generated theme configuration
5. Use in Production: Apply the exported theme to your component

// Example exported theme from live editor
const customTheme = {
  primary: "#ff6b6b",
  background: "#ffffff",
  userMessageBg: "#ffe3e3",
  assistantMessageBg: "#f8f9fa",
  borderColor: "#e9ecef",
  textColor: "#212529",
  fabBg: "#ffffff",
  fabColor: "#ff6b6b",
};

<ChatAssistant config={{ theme: customTheme }} />;

Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/new-feature
3. Make your changes
4. Run tests: npm run test:e2e
5. Commit your changes: git commit -am 'Add new feature'
6. Push to the branch: git push origin feature/new-feature
7. Submit a pull request

Development Guidelines

• Follow the existing code style
• Add tests for new features
• Update documentation as needed
• Ensure all tests pass before submitting PR
• Use semantic commit messages

Troubleshooting

Common Issues

Playwright tests failing:

# Reinstall browsers
npx playwright install

# Update Playwright
npm update @playwright/test

Build issues:

# Clear cache and reinstall
rm -rf node_modules package-lock.json
npm install

TypeScript errors:

# Check TypeScript configuration
npx tsc --noEmit

License

MIT

Support

For issues and questions:

• Create an issue in the repository
• Check existing documentation
• Review test files for usage examples