@kite-copilot/chat-panel 0.1.2 → 0.2.0

package/README.md

@@ -1,6 +1,6 @@
 # @kite-copilot/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.
+An AI-powered chat panel SDK for embedding intelligent chat assistants. This package provides a floating chat interface that integrates with any AI backend agent. Designed for PWAs, offline-capable apps, and traditional web applications.
 
 ## Features
 
@@ -9,7 +9,9 @@ An AI-powered chat panel component for React applications. This package provides
 - 🎯 **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
+- 🔌 **Easy Integration**: Programmatic API or React component
+- 📦 **PWA-Ready**: Fully bundled by your build tool, no CDN required
+- 🌐 **Offline-Safe**: Works with service workers and precaching
 
 ## Installation
 
@@ -26,16 +28,187 @@ pnpm add @kite-copilot/chat-panel
 Make sure you have the following peer dependencies installed:
 
 ```bash
-npm install react react-dom lucide-react
+npm install react react-dom
 ```
 
 ## Quick Start
 
-### Basic Usage
+### Programmatic API (Recommended)
+
+The programmatic API provides explicit lifecycle control - ideal for PWAs, Vue, Angular, or any framework.
+
+```ts
+import { createKiteChat } from '@kite-copilot/chat-panel';
+import '@kite-copilot/chat-panel/style.css';
+
+// Create the chat instance
+const chat = createKiteChat({
+  userId: 'user-123',
+  orgId: 'org-456',
+  agentUrl: 'https://your-api.example.com',
+  onNavigate: (page, subtab) => {
+    // Handle navigation requests from the chat
+    router.push(`/${page}${subtab ? `?tab=${subtab}` : ''}`);
+  },
+  onActionComplete: (actionType, data) => {
+    console.log('Action completed:', actionType, data);
+  },
+});
+
+// Mount into a container
+chat.mount('#chat-container');
+
+// Update state as needed
+chat.setCurrentPage('settings');
+chat.updateConfig({ theme: 'dark' });
+
+// Clean up when done
+chat.unmount();
+```
+
+### Auto-Mount Helper (Easy Mode)
+
+For simpler use cases, use the auto-mount helper:
+
+```ts
+import { mountKiteChat } from '@kite-copilot/chat-panel/auto';
+import '@kite-copilot/chat-panel/style.css';
+
+const chat = mountKiteChat({
+  container: '#chat-container',
+  userId: 'user-123',
+  orgId: 'org-456',
+});
+
+// Later, if needed:
+chat.unmount();
+```
+
+### React Component
+
+For React applications, use the component directly:
+
+```tsx
+import { ChatPanel, ChatPanelProvider } from '@kite-copilot/chat-panel';
+import '@kite-copilot/chat-panel/style.css';
+
+function App() {
+  const { userId, orgId } = useAuth();
+
+  return (
+    <ChatPanelProvider config={{ userId, orgId }}>
+      <YourApp />
+      <ChatPanel />
+    </ChatPanelProvider>
+  );
+}
+```
+
+## Framework Examples
+
+### Vue.js (PWA-Safe)
+
+```ts
+// main.ts
+import { createKiteChat } from '@kite-copilot/chat-panel';
+import '@kite-copilot/chat-panel/style.css';
+import { useRouter } from 'vue-router';
+
+const router = useRouter();
+
+const chat = createKiteChat({
+  userId: 'user-123',
+  orgId: 'org-456',
+  onNavigate: (page) => router.push(`/${page}`),
+});
+
+// Mount after Vue app is ready
+app.mount('#app');
+chat.mount('#kite-chat');
+```
+
+### Angular
+
+```ts
+// chat.service.ts
+import { Injectable, OnDestroy } from '@angular/core';
+import { createKiteChat, KiteChatInstance } from '@kite-copilot/chat-panel';
+
+@Injectable({ providedIn: 'root' })
+export class ChatService implements OnDestroy {
+  private chat: KiteChatInstance;
+
+  constructor(private router: Router) {
+    this.chat = createKiteChat({
+      userId: 'user-123',
+      orgId: 'org-456',
+      onNavigate: (page) => this.router.navigate([page]),
+    });
+  }
+
+  mount(container: string) {
+    this.chat.mount(container);
+  }
+
+  ngOnDestroy() {
+    this.chat.unmount();
+  }
+}
+```
+
+### Vanilla JavaScript
+
+```html
+<div id="chat-container"></div>
+<script type="module">
+  import { createKiteChat } from './node_modules/@kite-copilot/chat-panel/dist/index.js';
+
+  const chat = createKiteChat({
+    userId: 'user-123',
+    orgId: 'org-456',
+  });
+  
+  chat.mount('#chat-container');
+</script>
+```
+
+## API Reference
+
+### createKiteChat(config)
+
+Creates a new chat instance with explicit lifecycle control.
+
+#### KiteChatConfig
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `userId` | `string` | Yes | Unique identifier for the current user |
+| `orgId` | `string` | Yes | Organization identifier |
+| `agentUrl` | `string` | No | Backend agent API URL |
+| `currentPage` | `string` | No | Current page context |
+| `theme` | `'light' \| 'dark' \| 'system'` | No | Theme preference |
+| `onNavigate` | `(page: string, subtab?: string) => void` | No | Navigation callback |
+| `onActionComplete` | `(actionType: string, data: any) => void` | No | Action completion callback |
+
+#### KiteChatInstance
+
+| Method | Description |
+|--------|-------------|
+| `mount(container)` | Mount the chat widget into a container (selector or element) |
+| `unmount()` | Unmount and clean up the chat widget |
+| `setCurrentPage(page)` | Update the current page context |
+| `updateConfig(config)` | Update configuration options |
+| `isMounted()` | Check if the widget is currently mounted |
+
+---
+
+## React Component API
+
+### Basic Usage (React)
 
 ```tsx
 import { ChatPanel, ChatPanelProvider } from '@kite-copilot/chat-panel'
-import '@kite-copilot/chat-panel/styles.css'
+import '@kite-copilot/chat-panel/style.css'
 
 function App() {
   // Get the current user from your authentication system
@@ -54,7 +227,7 @@ function App() {
 
 ```tsx
 import { ChatPanel, ChatPanelProvider } from '@kite-copilot/chat-panel'
-import '@kite-copilot/chat-panel/styles.css'
+import '@kite-copilot/chat-panel/style.css'
 import { useRouter } from 'next/navigation'
 
 function App() {
@@ -235,7 +408,7 @@ const customFolders = [
 Import the CSS file in your app:
 
 ```tsx
-import '@kite-copilot/chat-panel/styles.css'
+import '@kite-copilot/chat-panel/style.css'
 ```
 
 ### With Tailwind CSS
@@ -287,6 +460,10 @@ Full TypeScript support with exported types:
 
 ```tsx
 import type {
+  // Programmatic API types
+  KiteChatConfig,
+  KiteChatInstance,
+  // React component types
   ChatPanelConfig,
   ChatPanelProps,
   ActionType,
@@ -338,7 +515,7 @@ export function Providers({ children }) {
 
 // app/layout.tsx
 import { Providers } from './providers'
-import '@kite-copilot/chat-panel/styles.css'
+import '@kite-copilot/chat-panel/style.css'
 
 export default function RootLayout({ children }) {
   return (
@@ -370,7 +547,7 @@ export default function Page() {
 ```tsx
 import { BrowserRouter, useLocation, useNavigate } from 'react-router-dom'
 import { ChatPanel, ChatPanelProvider } from '@kite-copilot/chat-panel'
-import '@kite-copilot/chat-panel/styles.css'
+import '@kite-copilot/chat-panel/style.css'
 import { useAuth } from './auth' // Your auth provider
 
 function ChatPanelWithRouter() {