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
• 📊 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 (only Lucide React for icons)
• 🧪 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

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
# or
yarn add data-platform-chatbot lucide-react
# or
pnpm add data-platform-chatbot lucide-react

Why install lucide-react separately? > lucide-react is a peer dependency to avoid version conflicts and duplicate installations. If you only install data-platform-chatbot, you'll get warnings and missing icons. Installing both packages ensures compatibility and keeps your bundle size optimal.

Tailwind CSS Setup

The component uses Tailwind CSS classes. Make sure Tailwind is configured in your project:

npm install -D tailwindcss @tailwindcss/postcss autoprefixer

Update your tailwind.config.js:

/** @type {import('tailwindcss').Config} */
export default {
  content: [
    "./src/**/*.{js,ts,jsx,tsx}",
    "./node_modules/data-platform-chatbot/dist/**/*.{js,ts,jsx,tsx}",
  ],
  theme: { extend: {} },
  plugins: [],
};

⚠️ 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
}

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",
    headers: {
      Authorization: "Bearer your-token",
      "X-Custom-Header": "value",
    },
  }}
/>

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