@hef2024/llmasaservice-ui 0.17.0 → 0.18.0

package/docs/CONVERSATION-HISTORY.md

@@ -0,0 +1,863 @@
+# Conversation History Settings Guide
+
+This guide covers how to configure the conversation history sidebar in AIAgentPanel, including how to enable/disable it, control its position, and customize its behavior.
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Enabling/Disabling Conversation History](#enablingdisabling-conversation-history)
+- [Controlling Sidebar Position](#controlling-sidebar-position)
+- [Collapse/Expand Functionality](#collapseexpand-functionality)
+- [History List Limit](#history-list-limit)
+- [Complete Configuration Examples](#complete-configuration-examples)
+- [API Reference](#api-reference)
+- [Common Use Cases](#common-use-cases)
+- [Best Practices](#best-practices)
+
+---
+
+## Overview
+
+The **AIAgentPanel** includes a built-in conversation history sidebar that displays all past conversations organized by time (Today, Yesterday, This Week, etc.). This sidebar provides users with:
+
+- Quick access to previous conversations
+- Time-grouped organization
+- Search functionality
+- Visual indicators for active conversations
+- Agent-specific icons
+
+The sidebar is **enabled by default** and appears on the **left side** of the panel by default.
+
+![Conversation History Sidebar](../images/conversation-history.png)
+
+---
+
+## Enabling/Disabling Conversation History
+
+### Disabling Conversation History
+
+To hide the conversation history sidebar completely, set the `showConversationHistory` prop to `false`:
+
+```typescript
+import AIAgentPanel from '@hef2024/llmasaservice-ui';
+
+function App() {
+  return (
+    <AIAgentPanel
+      showConversationHistory={false}  // Hides the sidebar
+      agents={['agent-1', 'agent-2']}
+      customerId="user-123"
+      apiKey="your-api-key"
+    />
+  );
+}
+```
+
+### When the Sidebar is Hidden
+
+When `showConversationHistory={false}`:
+
+- The sidebar is completely removed from the UI
+- The chat panel takes up the full width
+- Users can only interact with the current conversation
+- No past conversations are displayed
+- Conversation data is still persisted on the backend (if `apiKey` is provided)
+- The CSS class `ai-agent-panel--no-history` is added to the root element
+
+### Enabling Conversation History (Default)
+
+To explicitly enable conversation history, you can either:
+
+1. **Omit the prop** (it's enabled by default):
+
+```typescript
+<AIAgentPanel
+  agents={['agent-1']}
+  customerId="user-123"
+  apiKey="your-api-key"
+/>
+```
+
+2. **Or explicitly set it to `true`**:
+
+```typescript
+<AIAgentPanel
+  showConversationHistory={true}  // Explicitly enabled
+  agents={['agent-1']}
+  customerId="user-123"
+  apiKey="your-api-key"
+/>
+```
+
+### Requirements for Conversation History
+
+For conversation history to work properly, you must provide:
+
+- **`customerId`** (required): Unique identifier for the user
+- **`apiKey`** (recommended): Your LLM as a Service API key for backend persistence
+- **`agents`**: At least one agent ID
+
+```typescript
+<AIAgentPanel
+  showConversationHistory={true}
+  customerId="user-123"          // Required
+  apiKey="your-api-key"          // Required for backend persistence
+  agents={['agent-1', 'agent-2']}
+/>
+```
+
+---
+
+## Controlling Sidebar Position
+
+The `sidebarPosition` prop controls which side of the panel the conversation history sidebar appears on.
+
+### Left Sidebar (Default)
+
+```typescript
+<AIAgentPanel
+  sidebarPosition="left"  // Sidebar on the left (default)
+  agents={['agent-1']}
+  customerId="user-123"
+/>
+```
+
+**Layout:**
+```
+┌─────────────────────────────────────┐
+│ [Sidebar] │ Chat Panel              │
+│           │                         │
+│ History   │ Messages                │
+│ • Today   │                         │
+│ • Week    │                         │
+└─────────────────────────────────────┘
+```
+
+### Right Sidebar
+
+```typescript
+<AIAgentPanel
+  sidebarPosition="right"  // Sidebar on the right
+  agents={['agent-1']}
+  customerId="user-123"
+/>
+```
+
+**Layout:**
+```
+┌─────────────────────────────────────┐
+│ Chat Panel              │ [Sidebar] │
+│                         │           │
+│ Messages                │ History   │
+│                         │ • Today   │
+│                         │ • Week    │
+└─────────────────────────────────────┘
+```
+
+### When to Use Each Position
+
+| Position | Best For |
+|----------|----------|
+| **Left** (default) | - Standard layouts<br>- Desktop-first applications<br>- When users read left-to-right<br>- Consistent with common chat UIs |
+| **Right** | - Right-to-left languages<br>- Custom layouts where left space is used<br>- Matching your app's existing sidebar position<br>- User preference |
+
+### Example: Dynamic Position Based on User Preference
+
+```typescript
+function App() {
+  const [sidebarSide, setSidebarSide] = useState<'left' | 'right'>('left');
+  
+  return (
+    <div>
+      <div className="settings">
+        <label>
+          Sidebar Position:
+          <select 
+            value={sidebarSide} 
+            onChange={(e) => setSidebarSide(e.target.value as 'left' | 'right')}
+          >
+            <option value="left">Left</option>
+            <option value="right">Right</option>
+          </select>
+        </label>
+      </div>
+      
+      <AIAgentPanel
+        sidebarPosition={sidebarSide}
+        agents={['agent-1']}
+        customerId="user-123"
+      />
+    </div>
+  );
+}
+```
+
+---
+
+## Collapse/Expand Functionality
+
+The conversation history sidebar can be collapsed to save screen space while still keeping the chat panel visible.
+
+### How It Works
+
+- **Collapsed State**: Sidebar shows only a thin strip with icon buttons
+- **Expanded State**: Sidebar shows full conversation history
+- **Toggle Button**: Click the expand/collapse button to switch states
+- **Persistence**: The collapsed state is saved in `localStorage` and persists across sessions
+
+### User Interaction
+
+When the sidebar is collapsed:
+
+1. Only the agent icons and action buttons are visible
+2. The chat panel expands to use the available space
+3. Click the expand button (chevron icon) to restore the sidebar
+
+When the sidebar is expanded:
+
+1. Full conversation history is visible
+2. Search bar, new conversation button, and conversation list are shown
+3. Click the collapse button (chevron icon) to minimize the sidebar
+
+### Collapsed View
+
+```
+┌────┬──────────────────────────────┐
+│ ►  │ Chat Panel                   │
+│ ⊕  │                              │
+│ 🤖 │ Messages                     │
+│ 🤖 │                              │
+└────┴──────────────────────────────┘
+```
+
+### Expanded View
+
+```
+┌─────────────┬────────────────────┐
+│ ◄ Search    │ Chat Panel         │
+│ ⊕ New Chat  │                    │
+│             │ Messages           │
+│ Today       │                    │
+│ • Conv 1    │                    │
+│ • Conv 2    │                    │
+│             │                    │
+│ Yesterday   │                    │
+│ • Conv 3    │                    │
+└─────────────┴────────────────────┘
+```
+
+### Programmatic Control
+
+The collapse state is managed internally and persists using `localStorage`:
+
+```typescript
+// The state is automatically saved as:
+localStorage.setItem('ai-agent-panel-sidebar-collapsed', 'true');  // or 'false'
+```
+
+### Default State
+
+By default, the sidebar starts **expanded**. Users can collapse it, and their preference will be remembered.
+
+---
+
+## History List Limit
+
+Control how many past conversations are displayed in the sidebar using the `historyListLimit` prop.
+
+### Basic Usage
+
+```typescript
+<AIAgentPanel
+  historyListLimit={20}  // Show up to 20 conversations
+  agents={['agent-1']}
+  customerId="user-123"
+/>
+```
+
+### Default Behavior
+
+If not specified, the default limit is **50 conversations**.
+
+### Examples
+
+```typescript
+// Show only the 10 most recent conversations
+<AIAgentPanel
+  historyListLimit={10}
+  agents={['agent-1']}
+  customerId="user-123"
+/>
+
+// Show up to 100 conversations (for power users)
+<AIAgentPanel
+  historyListLimit={100}
+  agents={['agent-1']}
+  customerId="user-123"
+/>
+
+// Minimal history (good for mobile)
+<AIAgentPanel
+  historyListLimit={5}
+  agents={['agent-1']}
+  customerId="user-123"
+/>
+```
+
+### Performance Considerations
+
+| Limit | Use Case | Performance |
+|-------|----------|-------------|
+| **5-10** | Mobile devices, limited screen space | ⚡ Excellent |
+| **20-30** | Standard desktop applications | ⚡ Good |
+| **50** (default) | Power users, desktop apps | ✓ Good |
+| **100+** | Advanced users with lots of history | ⚠️ May impact load time |
+
+### When to Adjust the Limit
+
+- **Reduce** for:
+  - Mobile/tablet devices
+  - Users who create many conversations
+  - Performance-sensitive applications
+  
+- **Increase** for:
+  - Desktop applications
+  - Power users who need access to many past conversations
+  - Applications where conversation history is critical
+
+---
+
+## Complete Configuration Examples
+
+### Example 1: Minimal Configuration (Sidebar Hidden)
+
+```typescript
+import AIAgentPanel from '@hef2024/llmasaservice-ui';
+
+function MinimalApp() {
+  return (
+    <AIAgentPanel
+      showConversationHistory={false}  // No sidebar
+      agents={['assistant']}
+      customerId="user-123"
+      apiKey="your-api-key"
+    />
+  );
+}
+```
+
+**Use Case:** Simple chat interface without history navigation
+
+---
+
+### Example 2: Right-Aligned Sidebar
+
+```typescript
+function RightSidebarApp() {
+  return (
+    <AIAgentPanel
+      showConversationHistory={true}
+      sidebarPosition="right"       // Sidebar on the right
+      agents={['agent-1', 'agent-2']}
+      customerId="user-123"
+      apiKey="your-api-key"
+    />
+  );
+}
+```
+
+**Use Case:** Matching your app's existing right-aligned navigation
+
+---
+
+### Example 3: Mobile-Optimized
+
+```typescript
+function MobileApp() {
+  return (
+    <AIAgentPanel
+      showConversationHistory={true}
+      historyListLimit={5}          // Only 5 recent conversations
+      defaultWidth={350}
+      agents={['agent-1']}
+      customerId="user-123"
+      apiKey="your-api-key"
+    />
+  );
+}
+```
+
+**Use Case:** Mobile-first design with limited screen space
+
+---
+
+### Example 4: Full-Featured Desktop App
+
+```typescript
+function DesktopApp() {
+  return (
+    <AIAgentPanel
+      showConversationHistory={true}
+      sidebarPosition="left"
+      historyListLimit={50}         // Default, showing up to 50
+      defaultWidth={720}
+      minWidth={520}
+      maxWidth={1200}
+      agents={['agent-1', 'agent-2', 'agent-3']}
+      customerId="user-123"
+      apiKey="your-api-key"
+    />
+  );
+}
+```
+
+**Use Case:** Desktop application with full conversation management
+
+---
+
+### Example 5: User Preference Settings
+
+```typescript
+function AppWithPreferences() {
+  const [showHistory, setShowHistory] = useState(true);
+  const [sidebarPosition, setSidebarPosition] = useState<'left' | 'right'>('left');
+  const [historyLimit, setHistoryLimit] = useState(20);
+  
+  return (
+    <div>
+      {/* User Settings Panel */}
+      <div className="settings-panel">
+        <label>
+          <input 
+            type="checkbox" 
+            checked={showHistory}
+            onChange={(e) => setShowHistory(e.target.checked)}
+          />
+          Show Conversation History
+        </label>
+        
+        {showHistory && (
+          <>
+            <label>
+              Sidebar Position:
+              <select 
+                value={sidebarPosition}
+                onChange={(e) => setSidebarPosition(e.target.value as 'left' | 'right')}
+              >
+                <option value="left">Left</option>
+                <option value="right">Right</option>
+              </select>
+            </label>
+            
+            <label>
+              History Limit:
+              <input 
+                type="number"
+                min={5}
+                max={100}
+                value={historyLimit}
+                onChange={(e) => setHistoryLimit(Number(e.target.value))}
+              />
+            </label>
+          </>
+        )}
+      </div>
+      
+      {/* AI Panel with User Preferences */}
+      <AIAgentPanel
+        showConversationHistory={showHistory}
+        sidebarPosition={sidebarPosition}
+        historyListLimit={historyLimit}
+        agents={['agent-1']}
+        customerId="user-123"
+        apiKey="your-api-key"
+      />
+    </div>
+  );
+}
+```
+
+**Use Case:** Application with user-configurable settings
+
+---
+
+### Example 6: Conditional History Based on User Role
+
+```typescript
+function RoleBasedApp({ userRole }: { userRole: 'guest' | 'user' | 'admin' }) {
+  // Guests don't see history, users see limited history, admins see full history
+  const historyConfig = {
+    guest: { show: false, limit: 0 },
+    user: { show: true, limit: 10 },
+    admin: { show: true, limit: 100 },
+  };
+  
+  const config = historyConfig[userRole];
+  
+  return (
+    <AIAgentPanel
+      showConversationHistory={config.show}
+      historyListLimit={config.limit}
+      agents={['agent-1']}
+      customerId={`${userRole}-123`}
+      apiKey="your-api-key"
+    />
+  );
+}
+```
+
+**Use Case:** Different history access based on user permissions
+
+---
+
+## API Reference
+
+### Props Related to Conversation History
+
+```typescript
+interface AIAgentPanelProps {
+  // Enable/disable the conversation history sidebar
+  showConversationHistory?: boolean;  // Default: true
+  
+  // Control which side the sidebar appears on
+  sidebarPosition?: 'left' | 'right';  // Default: 'left'
+  
+  // Limit how many conversations to display in the list
+  historyListLimit?: number;  // Default: 50
+  
+  // Required for conversation history to work
+  customerId: string;  // Required
+  apiKey?: string;     // Required for backend persistence
+  agents: string[];    // Required
+}
+```
+
+### Complete Type Definitions
+
+```typescript
+// Sidebar Position
+type SidebarPosition = 'left' | 'right';
+
+// Example Usage
+const config: AIAgentPanelProps = {
+  showConversationHistory: true,
+  sidebarPosition: 'left',
+  historyListLimit: 30,
+  customerId: 'user-123',
+  apiKey: 'your-api-key',
+  agents: ['agent-1'],
+};
+```
+
+### CSS Classes Applied
+
+When conversation history is disabled:
+```css
+.ai-agent-panel--no-history {
+  /* Applied to root element when showConversationHistory={false} */
+}
+```
+
+When sidebar position changes:
+```css
+.ai-agent-panel--sidebar-left {
+  /* Applied when sidebarPosition="left" (default) */
+}
+
+.ai-agent-panel--sidebar-right {
+  /* Applied when sidebarPosition="right" */
+}
+```
+
+When sidebar is collapsed:
+```css
+.ai-agent-panel__sidebar--collapsed {
+  /* Applied to sidebar when collapsed by user */
+}
+```
+
+---
+
+## Common Use Cases
+
+### Use Case 1: Clean, Distraction-Free Chat
+
+Perfect for focused conversations without past history visible.
+
+```typescript
+<AIAgentPanel
+  showConversationHistory={false}
+  agents={['focused-assistant']}
+  customerId="user-123"
+/>
+```
+
+---
+
+### Use Case 2: Mobile-First Design
+
+Optimized for smaller screens with limited history.
+
+```typescript
+<AIAgentPanel
+  showConversationHistory={true}
+  historyListLimit={5}
+  defaultWidth={350}
+  sidebarPosition="left"
+  agents={['mobile-agent']}
+  customerId="user-123"
+/>
+```
+
+---
+
+### Use Case 3: Power User Dashboard
+
+Full history with lots of conversations visible.
+
+```typescript
+<AIAgentPanel
+  showConversationHistory={true}
+  historyListLimit={100}
+  sidebarPosition="left"
+  agents={['agent-1', 'agent-2', 'agent-3']}
+  customerId="power-user-123"
+  apiKey="your-api-key"
+/>
+```
+
+---
+
+### Use Case 4: Right-to-Left Language Support
+
+Better UX for RTL languages like Arabic or Hebrew.
+
+```typescript
+<AIAgentPanel
+  showConversationHistory={true}
+  sidebarPosition="right"  // Better for RTL languages
+  agents={['rtl-agent']}
+  customerId="user-123"
+/>
+```
+
+---
+
+### Use Case 5: Embedded Widget Mode
+
+Minimal interface embedded in another application.
+
+```typescript
+<AIAgentPanel
+  showConversationHistory={false}  // Hide history in widget mode
+  defaultWidth={400}
+  position="right"
+  agents={['widget-agent']}
+  customerId="user-123"
+/>
+```
+
+---
+
+## Best Practices
+
+### ✅ Do's
+
+1. **Enable history for full-featured apps**
+   ```typescript
+   <AIAgentPanel showConversationHistory={true} />
+   ```
+
+2. **Disable history for simple, focused interactions**
+   ```typescript
+   <AIAgentPanel showConversationHistory={false} />
+   ```
+
+3. **Adjust history limit based on user needs**
+   ```typescript
+   // Mobile
+   <AIAgentPanel historyListLimit={5} />
+   
+   // Desktop
+   <AIAgentPanel historyListLimit={50} />
+   ```
+
+4. **Match sidebar position to your app's layout**
+   ```typescript
+   <AIAgentPanel sidebarPosition="right" />  // If your app has left nav
+   ```
+
+5. **Always provide required props**
+   ```typescript
+   <AIAgentPanel
+     customerId="user-123"  // Required
+     apiKey="your-api-key"  // Required for persistence
+     agents={['agent-1']}    // Required
+   />
+   ```
+
+### ❌ Don'ts
+
+1. **Don't disable history without providing alternative navigation**
+   ```typescript
+   // ❌ Bad: No way to access past conversations
+   <AIAgentPanel showConversationHistory={false} />
+   
+   // ✅ Good: If disabling, ensure users don't need history
+   // or provide external navigation
+   ```
+
+2. **Don't set excessively high history limits**
+   ```typescript
+   // ❌ Bad: May impact performance
+   <AIAgentPanel historyListLimit={1000} />
+   
+   // ✅ Good: Reasonable limit
+   <AIAgentPanel historyListLimit={50} />
+   ```
+
+3. **Don't forget required dependencies**
+   ```typescript
+   // ❌ Bad: Missing customerId
+   <AIAgentPanel 
+     showConversationHistory={true}
+     agents={['agent-1']}
+   />
+   
+   // ✅ Good: All required props
+   <AIAgentPanel
+     showConversationHistory={true}
+     customerId="user-123"
+     agents={['agent-1']}
+   />
+   ```
+
+4. **Don't frequently change sidebar position**
+   ```typescript
+   // ❌ Bad: Constantly switching confuses users
+   const [position, setPosition] = useState<'left' | 'right'>('left');
+   useEffect(() => {
+     setInterval(() => {
+       setPosition(prev => prev === 'left' ? 'right' : 'left');
+     }, 1000);
+   }, []);
+   
+   // ✅ Good: Stable position, changed only via user preference
+   const [position] = useState<'left' | 'right'>('left');
+   ```
+
+---
+
+## Troubleshooting
+
+### Issue: Conversation History Not Showing
+
+**Symptoms:** Sidebar is visible but no conversations appear
+
+**Solutions:**
+
+1. Ensure `customerId` is provided:
+   ```typescript
+   <AIAgentPanel customerId="user-123" {...props} />
+   ```
+
+2. Ensure `apiKey` is provided for backend persistence:
+   ```typescript
+   <AIAgentPanel apiKey="your-api-key" {...props} />
+   ```
+
+3. Check that conversations have been created:
+   - Create a new conversation using the + button
+   - Or use `startNewConversation` API
+
+4. Verify `historyListLimit` isn't set too low:
+   ```typescript
+   <AIAgentPanel historyListLimit={50} {...props} />  // Not historyListLimit={0}
+   ```
+
+---
+
+### Issue: Sidebar Position Not Changing
+
+**Symptoms:** Setting `sidebarPosition` doesn't move the sidebar
+
+**Solutions:**
+
+1. Ensure you're using correct values:
+   ```typescript
+   // ✅ Correct
+   sidebarPosition="left"   // or "right"
+   
+   // ❌ Incorrect
+   sidebarPosition="top"    // Invalid
+   ```
+
+2. Check CSS isn't overriding the position:
+   - Look for custom CSS that might be interfering
+   - Check browser DevTools for conflicting styles
+
+3. Verify the component is re-rendering:
+   ```typescript
+   const [position, setPosition] = useState<'left' | 'right'>('left');
+   // Make sure state changes trigger re-render
+   ```
+
+---
+
+### Issue: Sidebar Won't Collapse
+
+**Symptoms:** Clicking collapse button doesn't work
+
+**Solutions:**
+
+1. Check if `showConversationHistory` is disabled:
+   ```typescript
+   // If this is false, there's no sidebar to collapse
+   showConversationHistory={true}
+   ```
+
+2. Clear localStorage if state is stuck:
+   ```javascript
+   localStorage.removeItem('ai-agent-panel-sidebar-collapsed');
+   ```
+
+3. Check for JavaScript errors in console
+
+---
+
+### Issue: Too Many Conversations Causing Slow Load
+
+**Symptoms:** Panel takes a long time to load or feels sluggish
+
+**Solutions:**
+
+1. Reduce `historyListLimit`:
+   ```typescript
+   <AIAgentPanel historyListLimit={20} {...props} />  // Instead of 100
+   ```
+
+2. Consider pagination or lazy loading (future feature)
+
+3. Archive old conversations on the backend
+
+---
+
+## Related Documentation
+
+- [AIAgentPanel API Reference](../local-dev-docs/AIAGENTPANEL.md)
+- [Conversation Starting Guide](./CONVERSATION-STARTING.md)
+- [Quick Start Guide](../local-dev-docs/QUICK-START.md)
+- [Troubleshooting Conversations](../local-dev-docs/TROUBLESHOOTING-CONVERSATIONS.md)
+
+---
+
+## Version History
+
+- **v0.17.0+** - Conversation history sidebar with collapse/expand
+- **v0.16.x** - Initial conversation history support
+
+---
+
+## Feedback
+
+If you have questions or suggestions about conversation history configuration, please open an issue on GitHub or contact support.