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
  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]

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",
    },
  }}
/>

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