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

$3

``bash


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.

$3

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

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

$3

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

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

$3

`bash


Clone the repository

git clone
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 (



);
}
`

Configuration

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

$3

`tsx
interface ChatConfig {
endpoint?: string; // API endpoint for chat
model?: string; // Model name to use
headers?: Record; // 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
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
}
`

$3

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

$3

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: , text: "Explain this further" },
{ icon: , text: "Give me an example" },
{ icon: , text: "Possible follow-up questions" },
{ icon: , 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

$3

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

$3

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

$3

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
`

$3

`
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

$3

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

;
`

$3

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

$3

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

$3

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

$3

`tsx
config={{
endpoint: "/v1/chat/completions", // Use proxy endpoint
model: "gpt-4",
headers: {
Authorization: "Bearer your-token",
"X-Custom-Header": "value",
},
}}
/>
`

$3

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

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

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

// Or as direct prop

`

$3

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

`tsx
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.
};

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

$3

Capture when user closes the chat:

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

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

$3

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

;
`

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

$3

- 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

$3

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