@kite-copilot/chat-panel 0.1.0

package/README.md

@@ -0,0 +1,408 @@
+# @kite/chat-panel
+
+An AI-powered chat panel component for React applications. This package provides a floating chat interface that can integrate with any AI backend agent to provide intelligent assistance to users.
+
+## Features
+
+- 🤖 **AI-Powered Chat**: Connects to your AI backend agent for intelligent responses
+- 📂 **CSV Bulk Operations**: Upload CSV files for bulk data processing
+- 🎯 **Interactive Guides**: Built-in guided tours with animated cursor
+- 🎨 **Customizable Themes**: Light and dark mode support
+- 📱 **Responsive Design**: Works on desktop and mobile
+- 🔌 **Easy Integration**: Simple props-based API with React Context for configuration
+
+## Installation
+
+```bash
+npm install @kite/chat-panel
+# or
+yarn add @kite/chat-panel
+# or
+pnpm add @kite/chat-panel
+```
+
+### Peer Dependencies
+
+Make sure you have the following peer dependencies installed:
+
+```bash
+npm install react react-dom lucide-react
+```
+
+## Quick Start
+
+### Basic Usage
+
+```tsx
+import { ChatPanel, ChatPanelProvider } from '@kite/chat-panel'
+import '@kite/chat-panel/styles.css'
+
+function App() {
+  // Get the current user from your authentication system
+  const { userId, orgId } = useAuth()
+
+  return (
+    <ChatPanelProvider config={{ userId, orgId }}>
+      <YourApp />
+      <ChatPanel />
+    </ChatPanelProvider>
+  )
+}
+```
+
+### With Navigation Integration
+
+```tsx
+import { ChatPanel, ChatPanelProvider } from '@kite/chat-panel'
+import '@kite/chat-panel/styles.css'
+import { useRouter } from 'next/navigation'
+
+function App() {
+  const router = useRouter()
+  const { userId, orgId } = useAuth() // Your auth system
+  const [currentPage, setCurrentPage] = useState('dashboard')
+
+  return (
+    <ChatPanelProvider
+      config={{
+        userId,
+        orgId,
+        theme: 'light',
+        position: 'bottom-right',
+      }}
+    >
+      <YourApp />
+      <ChatPanel
+        currentPage={currentPage}
+        onNavigate={(page, subtab) => {
+          setCurrentPage(page)
+          router.push(`/${page}${subtab ? `?tab=${subtab}` : ''}`)
+        }}
+        onActionComplete={(actionType, data) => {
+          console.log('Action completed:', actionType, data)
+          // Refresh your data or perform other side effects
+        }}
+      />
+    </ChatPanelProvider>
+  )
+}
+```
+
+## Configuration
+
+### ChatPanelProvider Props
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `config` | `ChatPanelConfig` | Configuration object (see below) |
+
+### ChatPanelConfig
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `userId` | `string` | **Required** | User ID of the end user querying the chat panel |
+| `orgId` | `string` | **Required** | Organization ID the user belongs to |
+| `agentUrl` | `string` | Built-in URL | Optional override for agent backend URL (for development/testing only) |
+| `theme` | `'light' \| 'dark' \| 'system'` | `'light'` | Theme preference |
+| `position` | `'bottom-right' \| 'bottom-left' \| 'custom'` | `'bottom-right'` | Panel position |
+| `guides` | `Record<string, GuideWithSteps>` | - | Custom interactive guides |
+| `folders` | `Folder[]` | - | Custom help topic folders |
+| `showDefaultFolders` | `boolean` | `true` | Show default help topics |
+| `enableGuideCursor` | `boolean` | `true` | Enable animated guide cursor |
+| `className` | `string` | - | Custom CSS class |
+
+### ChatPanel Props
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `currentPage` | `string` | Current page for context |
+| `onNavigate` | `(page: string, subtab?: string) => void` | Navigation callback |
+| `onActionComplete` | `(actionType: ActionType, data: ActionData) => void` | Action completion callback |
+| `onAgentAction` | `(event: AgentActionCompleteEvent) => void` | Agent action callback |
+| `onBack` | `() => void` | Back button callback |
+| `config` | `ChatPanelConfig` | Override provider config |
+
+## Backend Integration
+
+The ChatPanel expects your backend agent to expose the following SSE endpoints. All requests include `user_id` and `org_id` in the request body.
+
+### `/chat/stream` (POST)
+
+Main chat endpoint for streaming responses.
+
+**Request Body:**
+```json
+{
+  "session_id": "uuid",
+  "user_id": "user-123",
+  "org_id": "org-456",
+  "message": "user message",
+  "current_page": "dashboard"
+}
+```
+
+**SSE Events:**
+- `progress`: Processing status updates
+- `response`: AI response with optional actions
+- `error`: Error messages
+- `done`: Stream completion
+
+### `/chat/bulk/stream` (POST)
+
+CSV file upload endpoint for bulk operations.
+
+**Request:** FormData with `file`, `message`, `session_id`, `user_id`, `org_id`, `current_page`
+
+**SSE Events:**
+- `preview`: CSV preview with row count and sample data
+- `error`: Error messages
+
+### `/chat/bulk/confirm` (POST)
+
+Confirm and execute bulk operation.
+
+**Request Body:**
+```json
+{
+  "session_id": "uuid",
+  "user_id": "user-123",
+  "org_id": "org-456",
+  "bulk_session_id": "bulk-uuid"
+}
+```
+
+**SSE Events:**
+- `progress`: Row-by-row processing updates
+- `summary`: Final results with success/failure counts
+- `error`: Error messages
+
+## Custom Guides
+
+You can add custom interactive guides:
+
+```tsx
+const customGuides = {
+  'my-guide': {
+    id: 'my-guide',
+    title: 'My Custom Guide',
+    steps: [
+      {
+        text: 'Step 1: Click the button below',
+        navigation: { page: 'settings' },
+        cursorTarget: {
+          selector: '[data-testid="my-button"]',
+          onClick: true
+        }
+      },
+      // More steps...
+    ]
+  }
+}
+
+<ChatPanelProvider config={{ userId, orgId, guides: customGuides }}>
+  ...
+</ChatPanelProvider>
+```
+
+## Custom Help Topics
+
+Add custom help topic folders:
+
+```tsx
+const customFolders = [
+  {
+    id: 'support',
+    title: 'Support',
+    topics: [
+      {
+        id: 'contact',
+        label: 'Contact Us',
+        prompt: 'How can I contact support?'
+      }
+    ]
+  }
+]
+
+<ChatPanelProvider config={{ userId, orgId, folders: customFolders }}>
+  ...
+</ChatPanelProvider>
+```
+
+## Styling
+
+### Using the Default Styles
+
+Import the CSS file in your app:
+
+```tsx
+import '@kite/chat-panel/styles.css'
+```
+
+### With Tailwind CSS
+
+If you're using Tailwind, extend your config with our preset:
+
+```js
+// tailwind.config.js
+module.exports = {
+  content: [
+    // ... your paths
+    './node_modules/@kite/chat-panel/dist/**/*.{js,mjs}'
+  ],
+  theme: {
+    extend: {
+      colors: {
+        background: "var(--background)",
+        foreground: "var(--foreground)",
+        // ... other theme colors
+      }
+    }
+  }
+}
+```
+
+### CSS Variables
+
+The component uses CSS variables for theming. Override them in your CSS:
+
+```css
+:root {
+  --background: oklch(1 0 0);
+  --foreground: oklch(0.145 0 0);
+  --primary: oklch(0.205 0 0);
+  --primary-foreground: oklch(0.985 0 0);
+  /* ... more variables */
+}
+
+.dark {
+  --background: oklch(0.145 0 0);
+  --foreground: oklch(0.985 0 0);
+  /* ... dark mode overrides */
+}
+```
+
+## TypeScript
+
+Full TypeScript support with exported types:
+
+```tsx
+import type {
+  ChatPanelConfig,
+  ChatPanelProps,
+  ActionType,
+  ActionData,
+  Message,
+  GuideWithSteps,
+  Folder,
+} from '@kite/chat-panel'
+```
+
+## Events
+
+The ChatPanel dispatches window events for backward compatibility:
+
+- `agentActionComplete`: Fired when the agent completes an action
+- `integrationTabClicked`: Listen for this to trigger contextual messages
+
+```tsx
+window.addEventListener('agentActionComplete', (e) => {
+  console.log('Agent action:', e.detail.result)
+})
+```
+
+## Examples
+
+### Next.js App Router
+
+```tsx
+// app/providers.tsx
+'use client'
+
+import { ChatPanelProvider } from '@kite/chat-panel'
+import { useAuth } from './auth' // Your auth provider
+
+export function Providers({ children }) {
+  const { userId, orgId } = useAuth()
+
+  return (
+    <ChatPanelProvider
+      config={{
+        userId,
+        orgId,
+      }}
+    >
+      {children}
+    </ChatPanelProvider>
+  )
+}
+
+// app/layout.tsx
+import { Providers } from './providers'
+import '@kite/chat-panel/styles.css'
+
+export default function RootLayout({ children }) {
+  return (
+    <html>
+      <body>
+        <Providers>{children}</Providers>
+      </body>
+    </html>
+  )
+}
+
+// app/page.tsx
+'use client'
+
+import { ChatPanel } from '@kite/chat-panel'
+
+export default function Page() {
+  return (
+    <main>
+      <h1>My App</h1>
+      <ChatPanel currentPage="home" />
+    </main>
+  )
+}
+```
+
+### React with React Router
+
+```tsx
+import { BrowserRouter, useLocation, useNavigate } from 'react-router-dom'
+import { ChatPanel, ChatPanelProvider } from '@kite/chat-panel'
+import '@kite/chat-panel/styles.css'
+import { useAuth } from './auth' // Your auth provider
+
+function ChatPanelWithRouter() {
+  const location = useLocation()
+  const navigate = useNavigate()
+  const currentPage = location.pathname.slice(1) || 'dashboard'
+
+  return (
+    <ChatPanel
+      currentPage={currentPage}
+      onNavigate={(page) => navigate(`/${page}`)}
+    />
+  )
+}
+
+function App() {
+  const { userId, orgId } = useAuth()
+
+  return (
+    <BrowserRouter>
+      <ChatPanelProvider config={{ userId, orgId }}>
+        <Routes>
+          {/* Your routes */}
+        </Routes>
+        <ChatPanelWithRouter />
+      </ChatPanelProvider>
+    </BrowserRouter>
+  )
+}
+```
+
+## License
+
+MIT © kite
+