npm package: @revelations88/chatbot-ui
Description: A modular React chatbot component with code editing preview and undo support
Author: Michael Hu
Latest version: 1.0.1

# ChatBot UI

A modular, drop-in React chatbot component with code editing preview and undo functionality. Built with TypeScript, Tailwind CSS, and Lucide React icons.

## Features

- 🎨 **Glassmorphic UI** - Modern, floating chatbot with backdrop blur
- 📝 **Code Edit Previews** - View proposed changes with diff highlighting before applying
- ↩️ **Undo Support** - Built-in `/undo` command to rollback changes
- 🔌 **Configurable API** - Point to any backend API endpoint
- 🧩 **Modular Architecture** - Separated hooks, components, and types
- 📦 **Drop-in Ready** - Import and use in any React project

## Installation

```bash
npm install @revelations88/chatbot-ui
```

### Peer Dependencies

This package requires the following peer dependencies:

```bash
npm install react react-dom lucide-react
```

## Prerequisites

### Backend API

The chatbot expects a backend API with the following endpoints:

#### `POST /api/propose-edits`
```json
// Request
{
  "request": "Add a function to calculate factorial"
}

// Response
{
  "session_id": "abc123",
  "status": "success",
  "request": "Add a function to calculate factorial",
  "preview": [
    {
      "file": "src/math.ts",
      "changes": [
        {
          "line": 10,
          "old_code": "",
          "new_code": "function factorial(n: number): number { ... }"
        }
      ]
    }
  ],
  "summary": {
    "total_edits": 1,
    "files_affected": 1
  }
}
```

#### `POST /api/apply-edits`
```json
// Request
{
  "session_id": "abc123"
}

// Response
{
  "status": "success",
  "message": "Changes applied successfully"
}
```

#### `POST /api/undo`
```json
// Response
{
  "status": "success",
  "message": "Reverted to previous commit",
  "commit": "abc123"
}
```

## Usage

### Option 1: Auto-Mount (No React Required)

For non-React projects or simple integrations, use `initChatbotUI()` to automatically mount the chatbot:

```html
<!DOCTYPE html>
<html>
<head>
  <title>My App</title>
</head>
<body>
  <h1>My Application</h1>

  <script type="module">
    import { initChatbotUI } from '@revelations88/chatbot-ui';

    // Automatically mounts chatbot to the page
    initChatbotUI({
      apiBaseUrl: 'https://api.myapp.com/v1'
    });
  </script>
</body>
</html>
```

With cleanup:

```javascript
import { initChatbotUI } from '@revelations88/chatbot-ui';

const chatbot = initChatbotUI({
  apiBaseUrl: 'https://api.myapp.com/v1'
});

// Later, to remove the chatbot:
chatbot.unmount();
```

### Option 2: React Component

For React projects, use as a standard component:

```tsx
import { ChatBot } from '@revelations88/chatbot-ui';

function App() {
  return (
    <div>
      <h1>My Application</h1>
      <ChatBot />
    </div>
  );
}
```

### Custom API URL

```tsx
import { ChatBot } from '@revelations88/chatbot-ui';

function App() {
  return (
    <ChatBot apiBaseUrl="https://api.myapp.com/v1" />
  );
}
```

### TypeScript Types

```tsx
import { ChatBot, Message, FilePreview } from '@revelations88/chatbot-ui';

// Use exported types in your own code
const messages: Message[] = [];
```

## Commands

- **Regular messages**: Type naturally to propose code edits
- **/undo**: Rollback the last applied changes

## Advanced Usage

### Using Hooks Directly

For custom implementations, you can use the underlying hooks:

```tsx
import { useApi, useChat } from '@yourscope/chatbot-ui';

function CustomChatBot() {
  const api = useApi('https://api.myapp.com');
  const { messages, addUserMessage, addBotMessage } = useChat();

  const handleSubmit = async (input: string) => {
    addUserMessage(input);
    const result = await api.proposeEdits(input);
    // Custom handling...
  };

  // Custom UI...
}
```

## API Reference

### `initChatbotUI(options?)`

Initialize and mount the chatbot to the DOM automatically.

#### Parameters

| Param | Type | Default | Description |
|------|------|---------|-------------|
| `options` | `ChatBotProps` | `{}` | Optional configuration object |
| `options.apiBaseUrl` | `string` | `'http://localhost:8000/api'` | Base URL for API endpoints |

#### Returns

| Property | Type | Description |
|----------|------|-------------|
| `unmount` | `() => void` | Function to unmount and remove the chatbot from DOM |

### `<ChatBot>`

React component for manual integration.

#### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `apiBaseUrl` | `string` | `'http://localhost:8000/api'` | Base URL for API endpoints |

### Exported Types

```typescript
// Main message types
type Message =
  | { type: "text"; role: "user" | "bot"; content: string }
  | { type: "preview"; role: "bot"; sessionId: string; preview: FilePreview[]; summary: {...}; request: string };

// API response types
interface FilePreview {
  file: string;
  changes: PreviewChange[];
}

interface PreviewChange {
  line: number;
  old_code: string;
  new_code: string;
}
```

## Development

### Building the Library

```bash
# Build for production
npm run build:lib

# Development mode (demo app)
npm run dev
```

### Project Structure

```
src/
├── components/
│   ├── ChatBot.tsx          # Main component
│   └── chat/
│       ├── MessageList.tsx
│       ├── MessageBubble.tsx
│       └── PreviewCard.tsx
├── hooks/
│   ├── useApi.ts            # API calls
│   └── useChat.ts           # Message state
└── index.ts                 # Public exports
```

## Changelog

### v1.0.1 (Latest)
- Initial stable release
- Code editing preview with diff highlighting
- Undo support
- Glassmorphic UI design
- Auto-mount functionality with proper JSX rendering
- Type-safe API with full TypeScript support

**Note**: Versions 1.1.0 and 1.1.1 were deprecated. Use 1.0.1 or later.

## Publishing

1. Update version in `package.json`

2. Build the library:
```bash
npm run build:lib
```

3. Publish to npm:
```bash
npm publish --access public
```

## License

MIT

## Contributing

Contributions welcome! Please open an issue or PR.