@hsafa/ui-sdk 0.3.3 → 0.4.1

package/README.md

@@ -5,6 +5,7 @@ React SDK for building AI agent interfaces with custom actions and interactive c
 ## Features
 
 - 🤖 **AI Agent Chat**: Ready-to-use chat interface for AI agents
+- 🎨 **Headless Mode**: Build completely custom UIs with powerful hooks
 - ⚡ **Custom Actions**: Register functions that AI agents can call
 - 🎨 **Dynamic Components**: Create UI components that agents can render
 - 🔧 **TypeScript**: Full TypeScript support with comprehensive type definitions
@@ -23,7 +24,9 @@ pnpm add @hsafa/ui-sdk
 
 ## Quick Start
 
-### Basic AI Agent Chat
+### Option 1: Pre-built UI Component
+
+Use the ready-made chat interface:
 
 ```tsx
 import { HsafaProvider, HsafaChat } from '@hsafa/ui-sdk';
@@ -42,6 +45,44 @@ function App() {
 }
 ```
 
+### Option 2: Headless Mode (Build Your Own UI)
+
+Use the headless hooks to build a completely custom chat interface:
+
+```tsx
+import { useHsafaAgent } from '@hsafa/ui-sdk';
+
+function MyCustomChat() {
+  const agent = useHsafaAgent({
+    agentId: 'my-agent',
+    baseUrl: 'https://your-hsafa-api.com',
+  });
+
+  return (
+    <div>
+      {/* Messages */}
+      <div>
+        {agent.messages.map(msg => (
+          <div key={msg.id}>
+            <strong>{msg.role}:</strong> {msg.content}
+          </div>
+        ))}
+      </div>
+
+      {/* Input */}
+      <input 
+        value={agent.input} 
+        onChange={(e) => agent.setInput(e.target.value)}
+        onKeyPress={(e) => e.key === 'Enter' && agent.sendMessage()}
+      />
+      <button onClick={() => agent.sendMessage()}>Send</button>
+    </div>
+  );
+}
+```
+
+**📚 [Full Headless Documentation](./docs/HEADLESS_USAGE.md)** - Complete guide with examples
+
 ### Adding Custom Actions
 
 ```tsx
@@ -203,7 +244,97 @@ Provides context for agent communication.
 | `baseUrl` | `string` | **Required** - Your HSAFA API endpoint |
 | `children` | `ReactNode` | **Required** - App components |
 
-### Hooks
+### Headless Hooks
+
+Build custom chat UIs with complete control over styling and layout.
+
+#### useHsafaAgent
+
+The main hook for headless agent integration. Provides all chat functionality without UI.
+
+```tsx
+import { useHsafaAgent } from '@hsafa/ui-sdk';
+
+const agent = useHsafaAgent({
+  agentId: 'my-agent',
+  baseUrl: 'https://your-hsafa-api.com',
+  tools: { /* custom tools */ },
+  uiComponents: { /* custom UI components */ },
+  onFinish: (message) => console.log('Done:', message),
+  onError: (error) => console.error('Error:', error),
+});
+
+// Available properties:
+agent.input          // Current input text
+agent.setInput()     // Update input
+agent.messages       // All messages
+agent.isLoading      // Loading state
+agent.sendMessage()  // Send message
+agent.stop()         // Stop generation
+agent.newChat()      // Start new chat
+```
+
+#### useChatStorage
+
+Persist and manage chat history in localStorage.
+
+```tsx
+import { useHsafaAgent, useChatStorage } from '@hsafa/ui-sdk';
+
+const agent = useHsafaAgent({ /* ... */ });
+const storage = useChatStorage({
+  agentId: 'my-agent',
+  chatId: agent.chatId,
+  messages: agent.messages,
+  isLoading: agent.isLoading,
+  autoSave: true,
+  autoRestore: true,
+});
+
+// Available properties:
+storage.chatList              // All saved chats
+storage.loadChat(chatId)      // Load specific chat
+storage.deleteChat(chatId)    // Delete chat
+storage.switchToChat(chatId)  // Switch to chat
+```
+
+#### useMessageEditor
+
+Edit messages and regenerate responses.
+
+```tsx
+import { useMessageEditor } from '@hsafa/ui-sdk';
+
+const editor = useMessageEditor({
+  messages: agent.messages,
+  isLoading: agent.isLoading,
+  sendMessage: agent.sendMessage,
+  setMessages: agent.setMessages,
+});
+
+// Available properties:
+editor.startEdit(msgId, text)  // Start editing
+editor.saveEdit(msgId)         // Save and regenerate
+editor.cancelEdit()            // Cancel editing
+editor.isEditing(msgId)        // Check if editing
+```
+
+#### useFileUpload
+
+Handle file attachments for messages.
+
+```tsx
+import { useFileUpload } from '@hsafa/ui-sdk';
+
+const fileUpload = useFileUpload('https://your-api.com');
+
+// Available properties:
+fileUpload.attachments            // Current attachments
+fileUpload.handleFileSelection()  // Handle file input
+fileUpload.clearAttachments()     // Clear all
+```
+
+### Legacy Hooks
 
 #### useHsafaAction