@hef2024/llmasaservice-ui 0.20.3 → 0.22.0

package/docs/CHANGELOG-ERROR-HANDLING.md

@@ -246,3 +246,5 @@ For questions about this implementation, see:
 - `docs/ERROR-HANDLING-413.md` - Detailed technical documentation
 - GitHub Issues - Report bugs or request enhancements
 
+
+

package/docs/CONTROLLED-COLLAPSE-QUICK-START.md

@@ -0,0 +1,147 @@
+# Controlled Collapse State - Quick Start Guide
+
+## TL;DR
+
+The `AIAgentPanel` now supports controlled collapse state, allowing you to persist the panel's collapsed/expanded state across page navigations.
+
+## Quick Examples
+
+### Before (Uncontrolled - state resets on navigation)
+```tsx
+<AIAgentPanel 
+  defaultCollapsed={false}
+  agents={agents}
+  customerId={customerId}
+  apiKey={apiKey}
+/>
+```
+
+### After (Controlled - state persists)
+```tsx
+const [collapsed, setCollapsed] = useState(() => 
+  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}
+/>
+```
+
+## New Props
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `isCollapsed` | `boolean?` | Controlled collapse state |
+| `onCollapsedChange` | `(isCollapsed: boolean) => void?` | Callback when state changes |
+
+## Common Use Cases
+
+### 1. Persist Across Page Navigation (localStorage)
+```tsx
+const [collapsed, setCollapsed] = useState(() => 
+  localStorage.getItem('aiPanelCollapsed') === 'true'
+);
+
+<AIAgentPanel 
+  isCollapsed={collapsed}
+  onCollapsedChange={(isCollapsed) => {
+    setCollapsed(isCollapsed);
+    localStorage.setItem('aiPanelCollapsed', String(isCollapsed));
+  }}
+/>
+```
+
+### 2. Sync Across Devices (Database)
+```tsx
+const { data } = useUserPreferences();
+const { mutate } = useUpdateUserPreferences();
+
+<AIAgentPanel 
+  isCollapsed={data?.aiPanelCollapsed ?? false}
+  onCollapsedChange={(isCollapsed) => {
+    mutate({ aiPanelCollapsed: isCollapsed });
+  }}
+/>
+```
+
+### 3. Track for Analytics (Uncontrolled + Callback)
+```tsx
+<AIAgentPanel 
+  defaultCollapsed={false}
+  onCollapsedChange={(isCollapsed) => {
+    analytics.track('panel_collapsed', { isCollapsed });
+  }}
+/>
+```
+
+### 4. Programmatic Control
+```tsx
+const [collapsed, setCollapsed] = useState(false);
+
+<div>
+  <button onClick={() => setCollapsed(true)}>Collapse Panel</button>
+  
+  <AIAgentPanel 
+    isCollapsed={collapsed}
+    onCollapsedChange={setCollapsed}
+  />
+</div>
+```
+
+## Key Points
+
+✅ **Backward Compatible** - Existing code works without changes  
+✅ **Opt-in** - Only use controlled mode when you need it  
+✅ **Standard React Pattern** - Works like `<input value={...} onChange={...} />`  
+✅ **Flexible** - Works with localStorage, database, Redux, etc.  
+
+## Common Mistakes
+
+### ❌ Missing Callback
+```tsx
+// Panel won't respond to user clicks
+<AIAgentPanel isCollapsed={collapsed} />
+```
+
+### ✅ Correct
+```tsx
+<AIAgentPanel 
+  isCollapsed={collapsed}
+  onCollapsedChange={setCollapsed}
+/>
+```
+
+### ❌ Conflicting Props
+```tsx
+// defaultCollapsed is ignored in controlled mode
+<AIAgentPanel 
+  isCollapsed={collapsed}
+  onCollapsedChange={setCollapsed}
+  defaultCollapsed={false}  // Remove this
+/>
+```
+
+### ✅ Correct
+```tsx
+<AIAgentPanel 
+  isCollapsed={collapsed}
+  onCollapsedChange={setCollapsed}
+/>
+```
+
+## Full Documentation
+
+For complete documentation, see:
+- [Controlled Collapse State Guide](./CONTROLLED-COLLAPSE-STATE.md)
+- [Examples](../examples/controlled-collapse-example.tsx)
+- [Demo App](../examples/demo-app/src/App.tsx)
+