data-platform-chatbot/README.md

A configurable and customizable React chat component library

# 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
- 📊 **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 >= 18.0.0
- React >= 18.0.0
- React DOM >= 18.0.0

## Installation

### For End Users (Installing the Package)

```bash
# 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
```

### Tailwind CSS Setup

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

```bash
npm install -D tailwindcss @tailwindcss/postcss autoprefixer
```

Update your `tailwind.config.js`:
```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`:

```typescript
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

export default defineConfig({
  plugins: [react()],
  server: {
    proxy: {
      '/v1/chat/completions': {
        target: process.env.VITE_PROXY_TARGET || 'http://44.215.72.157:8001',
        changeOrigin: true,
        secure: false,
      },
    },
  },
})
```

Then use the proxy endpoint in your config:

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

### For Development (Cloning the Repository)

```bash
# 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

```tsx
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

```tsx
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

```tsx
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):

```tsx
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:

```typescript
// 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

```bash
# 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**
   ```bash
   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**
   ```bash
   # 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**
   ```bash
   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

```bash
# 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

```tsx
import { ChatAssistant } from 'data-platform-chatbot';
import 'data-platform-chatbot/dist/index.css';

<ChatAssistant />
```

### Custom Theme

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

### Pixie Theme

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

### Custom Position

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

### Custom API Configuration

```tsx
<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

```tsx
// 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:**
```bash
# Reinstall browsers
npx playwright install

# Update Playwright
npm update @playwright/test
```

**Build issues:**
```bash
# Clear cache and reinstall
rm -rf node_modules package-lock.json
npm install
```

**TypeScript errors:**
```bash
# 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