@kite-copilot/chat-panel 0.2.1 → 0.2.2

package/README.md

@@ -1,17 +1,20 @@
 # @kite-copilot/chat-panel
 
-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.
+An AI-powered chat panel SDK for embedding intelligent chat assistants. This package provides a **side panel** interface that integrates with any AI backend agent. The panel slides in from the right edge and automatically adjusts page content - no layout changes required.
 
 ## 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**: Programmatic API or React component
-- 📦 **PWA-Ready**: Fully bundled by your build tool, no CDN required
-- 🌐 **Offline-Safe**: Works with service workers and precaching
+- **Side Panel UX**: Slides in from the right edge, pushes page content (no overlay)
+- **Zero-Config**: Drop-in integration - no layout changes required from host apps
+- **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
+- **Dynamic Starting Questions**: Customizable per-user questions from backend
+- **Customizable Themes**: Light and dark mode support
+- **Responsive Design**: Works on desktop and mobile
+- **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
 
@@ -47,129 +50,142 @@ const chat = createKiteChat({
   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');
+// Mount - that's it! No container needed, panel handles its own positioning
+chat.mount(document.body);
+
+// Control the panel programmatically
+chat.open();   // Open the side panel
+chat.close();  // Close the side panel
+chat.toggle(); // Toggle open/closed
+
+// Check state
+if (chat.isOpen()) {
+  console.log('Panel is open');
+}
 
-// Update state as needed
+// Update context as user navigates
 chat.setCurrentPage('settings');
-chat.updateConfig({ theme: 'dark' });
 
 // Clean up when done
 chat.unmount();
 ```
 
-### Auto-Mount Helper (Easy Mode)
+### Vanilla HTML/JavaScript (Easiest)
 
-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',
+```html
+<!-- No special container or layout needed! -->
+<script>
+window.KiteChatConfig = {
   userId: 'user-123',
   orgId: 'org-456',
-});
-
-// Later, if needed:
-chat.unmount();
+  agentUrl: 'https://your-api.example.com'
+};
+</script>
+<script src="https://cdn.example.com/kite-chat.js"></script>
 ```
 
+That's it! The panel automatically:
+- Adds a toggle arrow (◀) to the right edge of the page
+- Slides in when clicked, pushing page content left
+- Manages `padding-right` on the body element
+
 ### React Component
 
-For React applications, use the component directly:
+For React applications, use the `ChatPanelWithToggle` component:
 
 ```tsx
-import { ChatPanel, ChatPanelProvider } from '@kite-copilot/chat-panel';
+import { ChatPanelWithToggle } 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>
+    <>
+      <YourExistingApp />
+      {/* Just add this - no layout changes needed */}
+      <ChatPanelWithToggle 
+        agentUrl="https://your-api.example.com"
+        onNavigate={(page) => router.push(`/${page}`)}
+      />
+    </>
   );
 }
 ```
 
-## Framework Examples
+For controlled mode:
 
-### Vue.js (PWA-Safe)
+```tsx
+import { useState } from 'react';
+import { ChatPanelWithToggle } from '@kite-copilot/chat-panel';
 
-```ts
-// main.ts
-import { createKiteChat } from '@kite-copilot/chat-panel';
-import '@kite-copilot/chat-panel/style.css';
-import { useRouter } from 'vue-router';
+function App() {
+  const [isPanelOpen, setIsPanelOpen] = useState(false);
+
+  return (
+    <>
+      <button onClick={() => setIsPanelOpen(true)}>Open Help</button>
+      <ChatPanelWithToggle 
+        isOpen={isPanelOpen}
+        onOpenChange={setIsPanelOpen}
+        agentUrl="https://your-api.example.com"
+      />
+    </>
+  );
+}
+```
 
-const router = useRouter();
+## How It Works
 
-const chat = createKiteChat({
-  userId: 'user-123',
-  orgId: 'org-456',
-  onNavigate: (page) => router.push(`/${page}`),
-});
+The side panel uses fixed positioning and automatically manages the body's `padding-right`:
 
-// Mount after Vue app is ready
-app.mount('#app');
-chat.mount('#kite-chat');
+```
+┌─────────────────────────────────┐    ┌────────────────────────┬────────┐
+│                                 │    │                        │        │
+│                                 │    │                        │  Side  │
+│        Your Page Content        │ →  │   Your Page Content    │  Panel │
+│                                 │    │   (shifted left)       │        │
+│                            [◀]  │    │                   [▶]  │        │
+└─────────────────────────────────┘    └────────────────────────┴────────┘
+        Panel Closed                            Panel Open
 ```
 
-### Angular
-
-```ts
-// chat.service.ts
-import { Injectable, OnDestroy } from '@angular/core';
-import { createKiteChat, KiteChatInstance } from '@kite-copilot/chat-panel';
+- **Closed**: Only the toggle arrow (◀) is visible on the right edge
+- **Open**: Panel slides in, toggle becomes (▶), body gets `padding-right: 400px`
+- **No overlays**: Content is pushed, not covered
 
-@Injectable({ providedIn: 'root' })
-export class ChatService implements OnDestroy {
-  private chat: KiteChatInstance;
+## Dynamic Starting Questions
 
-  constructor(private router: Router) {
-    this.chat = createKiteChat({
-      userId: 'user-123',
-      orgId: 'org-456',
-      onNavigate: (page) => this.router.navigate([page]),
-    });
-  }
+The panel shows suggested questions when empty. These can be customized per-user:
 
-  mount(container: string) {
-    this.chat.mount(container);
-  }
+```ts
+// Option 1: Pass questions directly
+const chat = createKiteChat({
+  userId: 'user-123',
+  orgId: 'org-456',
+  startingQuestions: [
+    { id: '1', label: 'Changing layouts', prompt: 'How do I customize the layout?' },
+    { id: '2', label: 'Bulk uploads', prompt: 'How do I upload data in bulk?' },
+    { id: '3', label: 'Example setups', prompt: 'Show me example configurations' },
+  ],
+});
 
-  ngOnDestroy() {
-    this.chat.unmount();
-  }
-}
+// Option 2: Fetch from backend (per-user)
+const chat = createKiteChat({
+  userId: 'user-123',
+  orgId: 'org-456',
+  startingQuestionsEndpoint: '/api/user/starting-questions',
+});
 ```
 
-### 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>
+The endpoint should return:
+```json
+[
+  { "id": "1", "label": "Question label", "prompt": "Full prompt to send" },
+  { "id": "2", "label": "Another question", "prompt": "Another prompt" }
+]
 ```
 
 ## API Reference
@@ -187,6 +203,8 @@ Creates a new chat instance with explicit lifecycle control.
 | `agentUrl` | `string` | No | Backend agent API URL |
 | `currentPage` | `string` | No | Current page context |
 | `theme` | `'light' \| 'dark' \| 'system'` | No | Theme preference |
+| `startingQuestions` | `StartingQuestion[]` | No | Custom starting questions |
+| `startingQuestionsEndpoint` | `string` | No | URL to fetch per-user questions |
 | `onNavigate` | `(page: string, subtab?: string) => void` | No | Navigation callback |
 | `onActionComplete` | `(actionType: string, data: any) => void` | No | Action completion callback |
 
@@ -194,110 +212,132 @@ Creates a new chat instance with explicit lifecycle control.
 
 | Method | Description |
 |--------|-------------|
-| `mount(container)` | Mount the chat widget into a container (selector or element) |
+| `mount(container)` | Mount the chat widget (container is just a React mount point) |
 | `unmount()` | Unmount and clean up the chat widget |
+| `open()` | Open the side panel |
+| `close()` | Close the side panel |
+| `toggle()` | Toggle the panel open/closed |
+| `isOpen()` | Check if the panel is currently open |
 | `setCurrentPage(page)` | Update the current page context |
 | `updateConfig(config)` | Update configuration options |
 | `isMounted()` | Check if the widget is currently mounted |
 
----
+### ChatPanelWithToggle (React)
 
-## React Component API
+The recommended React component with integrated toggle button.
 
-### Basic Usage (React)
+```tsx
+import { ChatPanelWithToggle } from '@kite-copilot/chat-panel';
+```
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `agentUrl` | `string` | `localhost:5002` | Backend agent URL |
+| `currentPage` | `string` | - | Current page for context |
+| `defaultOpen` | `boolean` | `false` | Initial open state (uncontrolled) |
+| `isOpen` | `boolean` | - | Controlled open state |
+| `onOpenChange` | `(isOpen: boolean) => void` | - | Called when open state changes |
+| `startingQuestions` | `StartingQuestion[]` | - | Custom starting questions |
+| `startingQuestionsEndpoint` | `string` | - | URL to fetch questions |
+| `onNavigate` | `(page, subtab?) => void` | - | Navigation callback |
+| `onActionComplete` | `(type, data) => void` | - | Action completion callback |
+
+### Low-Level Components
+
+For advanced customization, you can use the individual components:
 
 ```tsx
-import { ChatPanel, ChatPanelProvider } from '@kite-copilot/chat-panel'
-import '@kite-copilot/chat-panel/style.css'
+import { ChatPanel, PanelToggle } from '@kite-copilot/chat-panel';
 
-function App() {
-  // Get the current user from your authentication system
-  const { userId, orgId } = useAuth()
+function CustomPanel() {
+  const [isOpen, setIsOpen] = useState(false);
 
   return (
-    <ChatPanelProvider config={{ userId, orgId }}>
-      <YourApp />
-      <ChatPanel />
-    </ChatPanelProvider>
-  )
+    <>
+      <PanelToggle isOpen={isOpen} onClick={() => setIsOpen(!isOpen)} />
+      <ChatPanel isOpen={isOpen} onClose={() => setIsOpen(false)} />
+    </>
+  );
 }
 ```
 
-### With Navigation Integration
+## Framework Examples
 
-```tsx
-import { ChatPanel, ChatPanelProvider } from '@kite-copilot/chat-panel'
-import '@kite-copilot/chat-panel/style.css'
-import { useRouter } from 'next/navigation'
+### Vue.js
 
-function App() {
-  const router = useRouter()
-  const { userId, orgId } = useAuth() // Your auth system
-  const [currentPage, setCurrentPage] = useState('dashboard')
+```ts
+import { createKiteChat } from '@kite-copilot/chat-panel';
+import '@kite-copilot/chat-panel/style.css';
 
-  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>
-  )
-}
+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(document.body);
+
+// Open programmatically
+chat.open();
 ```
 
-## Configuration
+### Angular
 
-### ChatPanelProvider Props
+```ts
+import { Injectable, OnDestroy } from '@angular/core';
+import { createKiteChat, KiteChatInstance } from '@kite-copilot/chat-panel';
 
-| Prop | Type | Description |
-|------|------|-------------|
-| `config` | `ChatPanelConfig` | Configuration object (see below) |
+@Injectable({ providedIn: 'root' })
+export class ChatService implements OnDestroy {
+  private chat: KiteChatInstance;
 
-### ChatPanelConfig
+  constructor(private router: Router) {
+    this.chat = createKiteChat({
+      userId: 'user-123',
+      orgId: 'org-456',
+      onNavigate: (page) => this.router.navigate([page]),
+    });
+    this.chat.mount(document.body);
+  }
+
+  open() { this.chat.open(); }
+  close() { this.chat.close(); }
+  toggle() { this.chat.toggle(); }
+
+  ngOnDestroy() {
+    this.chat.unmount();
+  }
+}
+```
 
-| 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 |
+### Next.js App Router
 
-### ChatPanel Props
+```tsx
+// app/layout.tsx
+import { ChatPanelWithToggle } from '@kite-copilot/chat-panel';
+import '@kite-copilot/chat-panel/style.css';
 
-| 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 |
+export default function RootLayout({ children }) {
+  return (
+    <html>
+      <body>
+        {children}
+        <ChatPanelWithToggle 
+          agentUrl={process.env.NEXT_PUBLIC_AGENT_URL}
+        />
+      </body>
+    </html>
+  );
+}
+```
 
 ## 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.
+The ChatPanel expects your backend agent to expose the following SSE endpoints.
 
 ### `/chat/stream` (POST)
 
@@ -326,117 +366,33 @@ 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:
+### `/api/user/starting-questions` (GET) - Optional
 
-```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...
-    ]
-  }
-}
+Return per-user starting questions.
 
-<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?'
-      }
-    ]
-  }
+**Response:**
+```json
+[
+  { "id": "1", "label": "Changing layouts", "prompt": "How do I change the layout?" },
+  { "id": "2", "label": "Bulk uploads", "prompt": "How do I upload in bulk?" }
 ]
-
-<ChatPanelProvider config={{ userId, orgId, folders: customFolders }}>
-  ...
-</ChatPanelProvider>
 ```
 
 ## Styling
 
 ### Using the Default Styles
 
-Import the CSS file in your app:
-
 ```tsx
-import '@kite-copilot/chat-panel/style.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-copilot/chat-panel/dist/**/*.{js,mjs}'
-  ],
-  theme: {
-    extend: {
-      colors: {
-        background: "var(--background)",
-        foreground: "var(--foreground)",
-        // ... other theme colors
-      }
-    }
-  }
-}
+import '@kite-copilot/chat-panel/style.css';
 ```
 
 ### CSS Variables
 
-The component uses CSS variables for theming. Override them in your CSS:
+Override theme variables in your CSS:
 
 ```css
 :root {
@@ -444,13 +400,11 @@ The component uses CSS variables for theming. Override them in your CSS:
   --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 */
 }
 ```
 
@@ -460,126 +414,39 @@ Full TypeScript support with exported types:
 
 ```tsx
 import type {
-  // Programmatic API types
   KiteChatConfig,
   KiteChatInstance,
-  // React component types
-  ChatPanelConfig,
   ChatPanelProps,
+  ChatPanelWithToggleProps,
+  PanelToggleProps,
+  StartingQuestion,
   ActionType,
   ActionData,
-  Message,
-  GuideWithSteps,
-  Folder,
-} from '@kite-copilot/chat-panel'
+  Page,
+  SettingsTab,
+} from '@kite-copilot/chat-panel';
 ```
 
-## Events
+## Migration from Overlay Version
 
-The ChatPanel dispatches window events for backward compatibility:
+If upgrading from a previous version with overlay/floating panel:
 
-- `agentActionComplete`: Fired when the agent completes an action
-- `integrationTabClicked`: Listen for this to trigger contextual messages
+1. **Remove layout changes**: You no longer need flex containers or special positioning
+2. **Update imports**: Use `ChatPanelWithToggle` instead of `ChatPanel` for the full experience
+3. **Update API calls**: Use `open()`/`close()`/`toggle()` instead of managing `isCollapsed` state
 
 ```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-copilot/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-copilot/chat-panel/style.css'
-
-export default function RootLayout({ children }) {
-  return (
-    <html>
-      <body>
-        <Providers>{children}</Providers>
-      </body>
-    </html>
-  )
-}
-
-// app/page.tsx
-'use client'
-
-import { ChatPanel } from '@kite-copilot/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-copilot/chat-panel'
-import '@kite-copilot/chat-panel/style.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>
-  )
-}
+// Before (overlay)
+<div style={{ display: 'flex' }}>
+  <main style={{ flex: 1 }}>...</main>
+  <div id="chat-container" />
+</div>
+
+// After (side panel)
+<main>...</main>
+<ChatPanelWithToggle />
 ```
 
 ## License
 
-MIT © kite
-
+MIT © Kite

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kite-copilot/chat-panel",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "AI-powered chat panel SDK with programmatic lifecycle control",
   "type": "module",
   "main": "./dist/index.cjs",