@hef2024/llmasaservice-ui 0.21.0 → 0.22.1

package/docs/CONTROLLED-COLLAPSE-STATE.md

@@ -0,0 +1,651 @@
+# Controlled Collapse State for AIAgentPanel
+
+## Overview
+
+The `AIAgentPanel` component now supports both **controlled** and **uncontrolled** collapse state patterns, following standard React conventions. This allows parent components to manage and persist the panel's collapsed/expanded state across page navigations and user sessions.
+
+## Features
+
+- ✅ **Backward compatible** - Existing code continues to work without changes
+- ✅ **Standard React pattern** - Follows established controlled/uncontrolled conventions
+- ✅ **Flexible persistence** - Supports localStorage, database, Redux, etc.
+- ✅ **Better UX** - Users don't lose their panel preference when navigating
+- ✅ **Opt-in** - Developers can choose controlled mode only when needed
+- ✅ **Dev mode warnings** - Helpful warnings for common mistakes
+
+## API Reference
+
+### New Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `isCollapsed` | `boolean \| undefined` | `undefined` | Controlled collapse state. When provided, makes the component controlled. |
+| `onCollapsedChange` | `(isCollapsed: boolean) => void \| undefined` | `undefined` | Callback fired when collapse state changes. Works in both controlled and uncontrolled modes. |
+| `defaultCollapsed` | `boolean` | `false` | Initial collapse state for uncontrolled mode. Ignored when `isCollapsed` is provided. |
+| `collapsible` | `boolean` | `true` | Whether the panel can be collapsed at all. |
+
+### Behavior
+
+#### Uncontrolled Mode (Default)
+- `isCollapsed` is `undefined`
+- Component manages its own internal collapse state
+- `defaultCollapsed` sets the initial state
+- `onCollapsedChange` fires when state changes (optional)
+
+```tsx
+// Uncontrolled - panel manages its own state
+<AIAgentPanel 
+  defaultCollapsed={false}
+  agents={agents}
+  customerId={customerId}
+  apiKey={apiKey}
+/>
+```
+
+#### Controlled Mode
+- `isCollapsed` is provided
+- Component uses prop value instead of internal state
+- Parent component is responsible for managing state
+- `onCollapsedChange` should be provided to allow user interaction
+- `defaultCollapsed` is ignored (warning in dev mode)
+
+```tsx
+// Controlled - parent manages state
+const [collapsed, setCollapsed] = useState(false);
+
+<AIAgentPanel 
+  isCollapsed={collapsed}
+  onCollapsedChange={setCollapsed}
+  agents={agents}
+  customerId={customerId}
+  apiKey={apiKey}
+/>
+```
+
+## Usage Examples
+
+### 1. Uncontrolled with Callback (Analytics)
+
+Track collapse events without controlling the state:
+
+```tsx
+<AIAgentPanel 
+  defaultCollapsed={false}
+  onCollapsedChange={(isCollapsed) => {
+    console.log('Panel collapsed:', isCollapsed);
+    analytics.track('panel_collapsed', { isCollapsed });
+  }}
+  agents={agents}
+  customerId={customerId}
+  apiKey={apiKey}
+/>
+```
+
+### 2. Controlled with localStorage Persistence
+
+Persist the collapse preference across page navigations:
+
+```tsx
+const [collapsed, setCollapsed] = useState(() => {
+  if (typeof window !== 'undefined') {
+    return localStorage.getItem('aiPanelCollapsed') === 'true';
+  }
+  return false;
+});
+
+const handleCollapsedChange = (isCollapsed: boolean) => {
+  setCollapsed(isCollapsed);
+  localStorage.setItem('aiPanelCollapsed', String(isCollapsed));
+};
+
+return (
+  <AIAgentPanel 
+    isCollapsed={collapsed}
+    onCollapsedChange={handleCollapsedChange}
+    agents={agents}
+    customerId={customerId}
+    apiKey={apiKey}
+  />
+);
+```
+
+### 3. Controlled with React Query/Database
+
+Sync collapse state across devices and sessions:
+
+```tsx
+const { data: userPreferences, mutate } = useUserPreferences();
+
+return (
+  <AIAgentPanel 
+    isCollapsed={userPreferences?.aiPanelCollapsed ?? false}
+    onCollapsedChange={(isCollapsed) => {
+      mutate({ aiPanelCollapsed: isCollapsed });
+    }}
+    agents={agents}
+    customerId={customerId}
+    apiKey={apiKey}
+  />
+);
+```
+
+### 4. Multi-Page Application (Main Use Case)
+
+Panel state persists as users navigate between pages:
+
+```tsx
+function App() {
+  const [currentPage, setCurrentPage] = useState('dashboard');
+  const [panelCollapsed, setPanelCollapsed] = useState(() => {
+    return localStorage.getItem('aiPanelCollapsed') === 'true';
+  });
+
+  const handleCollapsedChange = (isCollapsed: boolean) => {
+    setPanelCollapsed(isCollapsed);
+    localStorage.setItem('aiPanelCollapsed', String(isCollapsed));
+  };
+
+  return (
+    <div>
+      <nav>
+        <button onClick={() => setCurrentPage('dashboard')}>Dashboard</button>
+        <button onClick={() => setCurrentPage('profile')}>Profile</button>
+        <button onClick={() => setCurrentPage('settings')}>Settings</button>
+      </nav>
+
+      <main>
+        {/* Page content changes, but panel state persists */}
+        {currentPage === 'dashboard' && <Dashboard />}
+        {currentPage === 'profile' && <Profile />}
+        {currentPage === 'settings' && <Settings />}
+      </main>
+
+      {/* Panel remains collapsed/expanded across all pages */}
+      <AIAgentPanel 
+        isCollapsed={panelCollapsed}
+        onCollapsedChange={handleCollapsedChange}
+        agents={agents}
+        customerId={customerId}
+        apiKey={apiKey}
+      />
+    </div>
+  );
+}
+```
+
+### 5. Programmatic Control
+
+Control the panel from other UI elements:
+
+```tsx
+const [collapsed, setCollapsed] = useState(false);
+
+return (
+  <div>
+    <button onClick={() => setCollapsed(false)}>Expand Panel</button>
+    <button onClick={() => setCollapsed(true)}>Collapse Panel</button>
+    
+    <AIAgentPanel 
+      isCollapsed={collapsed}
+      onCollapsedChange={setCollapsed}
+      agents={agents}
+      customerId={customerId}
+      apiKey={apiKey}
+    />
+  </div>
+);
+```
+
+### 6. Responsive Behavior
+
+Auto-collapse on mobile devices:
+
+```tsx
+const [collapsed, setCollapsed] = useState(() => {
+  if (typeof window !== 'undefined') {
+    return window.innerWidth < 768;
+  }
+  return false;
+});
+
+useEffect(() => {
+  const handleResize = () => {
+    if (window.innerWidth < 768 && !collapsed) {
+      setCollapsed(true);
+    }
+  };
+
+  window.addEventListener('resize', handleResize);
+  return () => window.removeEventListener('resize', handleResize);
+}, [collapsed]);
+
+return (
+  <AIAgentPanel 
+    isCollapsed={collapsed}
+    onCollapsedChange={setCollapsed}
+    agents={agents}
+    customerId={customerId}
+    apiKey={apiKey}
+  />
+);
+```
+
+## Dev Mode Warnings
+
+The component provides helpful warnings in development mode:
+
+### Warning 1: Controlled without Callback
+
+```tsx
+// ⚠️ Warning: isCollapsed provided without onCollapsedChange
+<AIAgentPanel 
+  isCollapsed={true}
+  // Missing onCollapsedChange - user can't interact!
+/>
+```
+
+**Warning message:**
+```
+AIAgentPanel: You provided `isCollapsed` prop without `onCollapsedChange`. 
+This will render a read-only collapsed state. To allow user interaction, provide both props.
+```
+
+### Warning 2: Conflicting Props
+
+```tsx
+// ⚠️ Warning: Both isCollapsed and defaultCollapsed provided
+<AIAgentPanel 
+  isCollapsed={collapsed}
+  onCollapsedChange={setCollapsed}
+  defaultCollapsed={true}  // This will be ignored!
+/>
+```
+
+**Warning message:**
+```
+AIAgentPanel: You provided both `isCollapsed` and `defaultCollapsed` props. 
+When using controlled mode (isCollapsed), the defaultCollapsed prop is ignored. 
+Remove defaultCollapsed to avoid confusion.
+```
+
+## Migration Guide
+
+### From Uncontrolled to Controlled
+
+**Before (Uncontrolled):**
+```tsx
+<AIAgentPanel 
+  defaultCollapsed={false}
+  agents={agents}
+  customerId={customerId}
+  apiKey={apiKey}
+/>
+```
+
+**After (Controlled with localStorage):**
+```tsx
+const [collapsed, setCollapsed] = useState(() => {
+  return localStorage.getItem('aiPanelCollapsed') === 'true';
+});
+
+const handleCollapsedChange = (isCollapsed: boolean) => {
+  setCollapsed(isCollapsed);
+  localStorage.setItem('aiPanelCollapsed', String(isCollapsed));
+};
+
+<AIAgentPanel 
+  isCollapsed={collapsed}
+  onCollapsedChange={handleCollapsedChange}
+  agents={agents}
+  customerId={customerId}
+  apiKey={apiKey}
+/>
+```
+
+### No Migration Required
+
+If you're happy with the current behavior, you don't need to change anything. The component remains fully backward compatible.
+
+## Persistence Strategies
+
+### 1. localStorage (Client-side)
+
+**Pros:**
+- Simple to implement
+- No backend required
+- Fast access
+
+**Cons:**
+- Not synced across devices
+- Cleared when user clears browser data
+
+```tsx
+const [collapsed, setCollapsed] = useState(() => {
+  return localStorage.getItem('aiPanelCollapsed') === 'true';
+});
+
+const handleCollapsedChange = (isCollapsed: boolean) => {
+  setCollapsed(isCollapsed);
+  localStorage.setItem('aiPanelCollapsed', String(isCollapsed));
+};
+```
+
+### 2. Database (Server-side)
+
+**Pros:**
+- Synced across devices
+- Persistent across browser clears
+- Can be part of user preferences
+
+**Cons:**
+- Requires backend API
+- Network latency
+- More complex implementation
+
+```tsx
+const { data: preferences } = useUserPreferences();
+const { mutate: updatePreferences } = useUpdateUserPreferences();
+
+<AIAgentPanel 
+  isCollapsed={preferences?.aiPanelCollapsed ?? false}
+  onCollapsedChange={(isCollapsed) => {
+    updatePreferences({ aiPanelCollapsed: isCollapsed });
+  }}
+/>
+```
+
+### 3. React Context (Global State)
+
+**Pros:**
+- Share state across components
+- Centralized state management
+- No persistence setup needed
+
+**Cons:**
+- State lost on page refresh
+- Not synced across tabs
+
+```tsx
+const UIPreferencesContext = createContext();
+
+function UIPreferencesProvider({ children }) {
+  const [aiPanelCollapsed, setAIPanelCollapsed] = useState(false);
+  return (
+    <UIPreferencesContext.Provider value={{ aiPanelCollapsed, setAIPanelCollapsed }}>
+      {children}
+    </UIPreferencesContext.Provider>
+  );
+}
+
+function MyComponent() {
+  const { aiPanelCollapsed, setAIPanelCollapsed } = useContext(UIPreferencesContext);
+  return (
+    <AIAgentPanel 
+      isCollapsed={aiPanelCollapsed}
+      onCollapsedChange={setAIPanelCollapsed}
+    />
+  );
+}
+```
+
+### 4. URL Parameters (Deep Linking)
+
+**Pros:**
+- Shareable state via URL
+- Bookmarkable
+- Works with browser back/forward
+
+**Cons:**
+- Visible in URL
+- Limited to URL-safe values
+
+```tsx
+const [searchParams, setSearchParams] = useSearchParams();
+const collapsed = searchParams.get('panelCollapsed') === 'true';
+
+const handleCollapsedChange = (isCollapsed: boolean) => {
+  setSearchParams({ panelCollapsed: String(isCollapsed) });
+};
+
+<AIAgentPanel 
+  isCollapsed={collapsed}
+  onCollapsedChange={handleCollapsedChange}
+/>
+```
+
+## Best Practices
+
+### 1. Use useCallback for Performance
+
+Prevent unnecessary re-renders by memoizing the callback:
+
+```tsx
+const handleCollapsedChange = useCallback((isCollapsed: boolean) => {
+  setCollapsed(isCollapsed);
+  localStorage.setItem('aiPanelCollapsed', String(isCollapsed));
+}, []);
+```
+
+### 2. Initialize from Persistence Layer
+
+Load the initial state from your persistence layer:
+
+```tsx
+const [collapsed, setCollapsed] = useState(() => {
+  // Initialize from localStorage
+  if (typeof window !== 'undefined') {
+    return localStorage.getItem('aiPanelCollapsed') === 'true';
+  }
+  return false;
+});
+```
+
+### 3. Handle Loading States
+
+Show a loading state while fetching user preferences:
+
+```tsx
+const { data: preferences, isLoading } = useUserPreferences();
+
+if (isLoading) {
+  return <div>Loading...</div>;
+}
+
+return (
+  <AIAgentPanel 
+    isCollapsed={preferences?.aiPanelCollapsed ?? false}
+    onCollapsedChange={(isCollapsed) => {
+      updatePreferences({ aiPanelCollapsed: isCollapsed });
+    }}
+  />
+);
+```
+
+### 4. Provide Fallback Values
+
+Always provide a fallback value for the controlled state:
+
+```tsx
+<AIAgentPanel 
+  isCollapsed={preferences?.aiPanelCollapsed ?? false}  // Fallback to false
+  onCollapsedChange={handleCollapsedChange}
+/>
+```
+
+### 5. Consider Mobile Behavior
+
+Auto-collapse on mobile devices for better UX:
+
+```tsx
+const [collapsed, setCollapsed] = useState(() => {
+  if (typeof window !== 'undefined') {
+    // Auto-collapse on mobile
+    return window.innerWidth < 768;
+  }
+  return false;
+});
+```
+
+## TypeScript Support
+
+The component is fully typed with TypeScript:
+
+```typescript
+interface AIAgentPanelProps {
+  // ... other props
+  
+  /** Controlled collapse state */
+  isCollapsed?: boolean;
+  
+  /** Callback when collapse state changes */
+  onCollapsedChange?: (isCollapsed: boolean) => void;
+  
+  /** Initial collapse state (uncontrolled mode only) */
+  defaultCollapsed?: boolean;
+  
+  /** Whether the panel can be collapsed */
+  collapsible?: boolean;
+  
+  // ... other props
+}
+```
+
+## Testing
+
+### Unit Tests
+
+Test both controlled and uncontrolled modes:
+
+```tsx
+describe('AIAgentPanel collapse state', () => {
+  it('should work in uncontrolled mode', () => {
+    render(<AIAgentPanel defaultCollapsed={false} {...requiredProps} />);
+    // Test default behavior
+  });
+
+  it('should work in controlled mode', () => {
+    const onCollapsedChange = jest.fn();
+    const { rerender } = render(
+      <AIAgentPanel 
+        isCollapsed={false} 
+        onCollapsedChange={onCollapsedChange}
+        {...requiredProps}
+      />
+    );
+    
+    // Click collapse button
+    fireEvent.click(screen.getByRole('button', { name: /collapse/i }));
+    
+    // Callback should be called
+    expect(onCollapsedChange).toHaveBeenCalledWith(true);
+    
+    // Rerender with new state
+    rerender(
+      <AIAgentPanel 
+        isCollapsed={true} 
+        onCollapsedChange={onCollapsedChange}
+        {...requiredProps}
+      />
+    );
+    
+    // Panel should be collapsed
+    expect(screen.getByRole('complementary')).toHaveClass('collapsed');
+  });
+});
+```
+
+### Integration Tests
+
+Test persistence across navigation:
+
+```tsx
+describe('AIAgentPanel persistence', () => {
+  it('should persist collapse state across page navigations', () => {
+    const { rerender } = render(<App />);
+    
+    // Collapse the panel
+    fireEvent.click(screen.getByRole('button', { name: /collapse/i }));
+    
+    // Navigate to another page
+    fireEvent.click(screen.getByText('Profile'));
+    
+    // Panel should still be collapsed
+    expect(screen.getByRole('complementary')).toHaveClass('collapsed');
+    
+    // Navigate back
+    fireEvent.click(screen.getByText('Dashboard'));
+    
+    // Panel should still be collapsed
+    expect(screen.getByRole('complementary')).toHaveClass('collapsed');
+  });
+});
+```
+
+## Troubleshooting
+
+### Issue: Panel doesn't collapse when clicking the button
+
+**Cause:** Using controlled mode without providing `onCollapsedChange`.
+
+**Solution:** Provide both `isCollapsed` and `onCollapsedChange`:
+
+```tsx
+// ❌ Wrong - missing onCollapsedChange
+<AIAgentPanel isCollapsed={collapsed} />
+
+// ✅ Correct
+<AIAgentPanel 
+  isCollapsed={collapsed}
+  onCollapsedChange={setCollapsed}
+/>
+```
+
+### Issue: State resets on page navigation
+
+**Cause:** Using uncontrolled mode without persistence.
+
+**Solution:** Switch to controlled mode with localStorage:
+
+```tsx
+const [collapsed, setCollapsed] = useState(() => {
+  return localStorage.getItem('aiPanelCollapsed') === 'true';
+});
+
+const handleCollapsedChange = (isCollapsed: boolean) => {
+  setCollapsed(isCollapsed);
+  localStorage.setItem('aiPanelCollapsed', String(isCollapsed));
+};
+
+<AIAgentPanel 
+  isCollapsed={collapsed}
+  onCollapsedChange={handleCollapsedChange}
+/>
+```
+
+### Issue: Warning about conflicting props
+
+**Cause:** Providing both `isCollapsed` and `defaultCollapsed`.
+
+**Solution:** Remove `defaultCollapsed` when using controlled mode:
+
+```tsx
+// ❌ Wrong - conflicting props
+<AIAgentPanel 
+  isCollapsed={collapsed}
+  onCollapsedChange={setCollapsed}
+  defaultCollapsed={false}  // Remove this
+/>
+
+// ✅ Correct
+<AIAgentPanel 
+  isCollapsed={collapsed}
+  onCollapsedChange={setCollapsed}
+/>
+```
+
+## See Also
+
+- [AIAgentPanel Documentation](./AIAGENTPANEL.md)
+- [Examples](../examples/controlled-collapse-example.tsx)
+- [Demo App](../examples/demo-app/src/App.tsx)
+

package/docs/CONVERSATION-HISTORY.md

@@ -862,3 +862,5 @@ Minimal interface embedded in another application.
 
 If you have questions or suggestions about conversation history configuration, please open an issue on GitHub or contact support.
 
+
+

package/docs/ERROR-HANDLING-413.md

@@ -252,3 +252,5 @@ Potential improvements for future iterations:
 - The implementation is consistent across both modern (AIChatPanel) and legacy (ChatPanel) components
 - Error state is properly synchronized with loading state to prevent UI inconsistencies
 
+
+

package/docs/ERROR-HANDLING-SUMMARY.md

@@ -130,3 +130,5 @@ The implementation is straightforward:
 
 No configuration needed, works automatically! 🎉
 
+
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hef2024/llmasaservice-ui",
-  "version": "0.21.0",
+  "version": "0.22.1",
   "description": "Prebuilt UI components for LLMAsAService.io",
   "main": "dist/index.js",
   "module": "dist/index.mjs",