@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

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:

npm install react react-dom lucide-react

Quick Start

Basic Usage

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

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:

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

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

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:

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:

import '@kite/chat-panel/styles.css'

With Tailwind CSS

If you're using Tailwind, extend your config with our preset:

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

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

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

window.addEventListener('agentActionComplete', (e) => {
  console.log('Agent action:', e.detail.result)
})

Examples

Next.js App Router

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

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