@hsafa/ui-sdk 0.3.3 → 0.4.1

package/docs/MIGRATION_TO_HEADLESS.md

@@ -0,0 +1,408 @@
+# Migrating from HsafaChat to Headless Hooks
+
+This guide helps you migrate from using the pre-built `HsafaChat` component to the headless hooks for full UI customization.
+
+## Why Migrate?
+
+**Benefits of Headless Hooks:**
+- 🎨 Complete control over UI/UX
+- 🔧 Custom styling with your design system
+- ⚡ Optimize for your specific use case
+- 📦 Use only what you need (smaller bundle)
+- 🧩 Integrate seamlessly with existing components
+
+## Before: Using HsafaChat
+
+```tsx
+import { HsafaProvider, HsafaChat } from '@hsafa/ui-sdk';
+
+function App() {
+  return (
+    <HsafaProvider baseUrl="http://localhost:3000">
+      <HsafaChat 
+        agentId="my-agent"
+        theme="dark"
+        primaryColor="#0ea5e9"
+        HsafaTools={{
+          customTool: async (input) => {
+            return { result: 'Done!' };
+          }
+        }}
+        HsafaUI={{
+          CustomCard: ({ data }) => <div>{data.text}</div>
+        }}
+      />
+    </HsafaProvider>
+  );
+}
+```
+
+## After: Using Headless Hooks
+
+```tsx
+import { useHsafaAgent, useAutoScroll } from '@hsafa/ui-sdk';
+
+function App() {
+  const agent = useHsafaAgent({
+    agentId: 'my-agent',
+    baseUrl: 'http://localhost:3000',
+    
+    // Same tools, just passed differently
+    tools: {
+      customTool: async (input) => {
+        return { result: 'Done!' };
+      }
+    },
+    
+    // Same UI components
+    uiComponents: {
+      CustomCard: ({ data }) => <div>{data.text}</div>
+    },
+    
+    // Theme colors for built-in forms
+    colors: {
+      primaryColor: '#0ea5e9',
+      backgroundColor: '#0B0B0F',
+      textColor: '#EDEEF0',
+    }
+  });
+
+  const scrollRef = useAutoScroll<HTMLDivElement>(agent.isLoading);
+
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', height: '100vh' }}>
+      {/* Messages */}
+      <div ref={scrollRef} style={{ flex: 1, overflow: 'auto', padding: '20px' }}>
+        {agent.messages.map(msg => (
+          <div key={msg.id} style={{ marginBottom: '15px' }}>
+            <strong>{msg.role}:</strong> {msg.content}
+          </div>
+        ))}
+        {agent.isLoading && <div>Loading...</div>}
+      </div>
+
+      {/* Input */}
+      <div style={{ padding: '20px' }}>
+        <input
+          value={agent.input}
+          onChange={(e) => agent.setInput(e.target.value)}
+          onKeyPress={(e) => e.key === 'Enter' && agent.sendMessage()}
+          disabled={agent.isLoading}
+        />
+        <button onClick={() => agent.sendMessage()} disabled={agent.isLoading}>
+          Send
+        </button>
+      </div>
+    </div>
+  );
+}
+```
+
+## Feature-by-Feature Migration
+
+### 1. Basic Chat
+
+**Before:**
+```tsx
+<HsafaChat agentId="my-agent" />
+```
+
+**After:**
+```tsx
+const agent = useHsafaAgent({ agentId: 'my-agent', baseUrl: '...' });
+// Then build your UI using agent.messages, agent.input, etc.
+```
+
+### 2. File Uploads
+
+**Before:**
+Built-in file upload in HsafaChat
+
+**After:**
+```tsx
+import { useFileUpload } from '@hsafa/ui-sdk';
+
+const fileUpload = useFileUpload('http://localhost:3000');
+
+// In your component:
+<input
+  type="file"
+  ref={fileUpload.fileInputRef}
+  onChange={(e) => fileUpload.handleFileSelection(e.target.files, setError)}
+/>
+
+// When sending:
+agent.sendMessage({
+  text: agent.input,
+  files: fileUpload.attachments.map(att => ({
+    type: 'file',
+    url: att.url,
+    mediaType: att.mimeType,
+  }))
+});
+```
+
+### 3. Chat History
+
+**Before:**
+Built-in history modal in HsafaChat
+
+**After:**
+```tsx
+import { useChatStorage } from '@hsafa/ui-sdk';
+
+const storage = useChatStorage({
+  agentId: 'my-agent',
+  chatId: agent.chatId,
+  messages: agent.messages,
+  isLoading: agent.isLoading,
+  autoSave: true,
+  autoRestore: true,
+});
+
+// Build your own history UI:
+<div>
+  {storage.chatList.map(chat => (
+    <div key={chat.id} onClick={() => storage.switchToChat(chat.id, agent.setMessages)}>
+      {chat.title}
+    </div>
+  ))}
+</div>
+```
+
+### 4. Message Editing
+
+**Before:**
+Built-in edit functionality in HsafaChat
+
+**After:**
+```tsx
+import { useMessageEditor } from '@hsafa/ui-sdk';
+
+const editor = useMessageEditor({
+  messages: agent.messages,
+  isLoading: agent.isLoading,
+  sendMessage: agent.sendMessage,
+  setMessages: agent.setMessages,
+});
+
+// In your message rendering:
+{editor.isEditing(msg.id) ? (
+  <div>
+    <textarea 
+      value={editor.editingText}
+      onChange={(e) => editor.setEditingText(e.target.value)}
+    />
+    <button onClick={() => editor.saveEdit(msg.id)}>Save</button>
+    <button onClick={editor.cancelEdit}>Cancel</button>
+  </div>
+) : (
+  <div>
+    {msg.content}
+    <button onClick={() => editor.startEdit(msg.id, msg.content)}>Edit</button>
+  </div>
+)}
+```
+
+### 5. Custom Tools
+
+**Before:**
+```tsx
+<HsafaChat
+  HsafaTools={{
+    myTool: async (input) => { /* ... */ }
+  }}
+/>
+```
+
+**After:**
+```tsx
+const agent = useHsafaAgent({
+  tools: {
+    myTool: async (input) => { /* ... */ }
+  }
+});
+```
+
+### 6. Custom UI Components
+
+**Before:**
+```tsx
+<HsafaChat
+  HsafaUI={{
+    MyComponent: ({ data }) => <div>{data.text}</div>
+  }}
+/>
+```
+
+**After:**
+```tsx
+const agent = useHsafaAgent({
+  uiComponents: {
+    MyComponent: ({ data }) => <div>{data.text}</div>
+  }
+});
+```
+
+### 7. Theme/Colors
+
+**Before:**
+```tsx
+<HsafaChat
+  theme="dark"
+  primaryColor="#0ea5e9"
+  backgroundColor="#0B0B0F"
+  textColor="#EDEEF0"
+/>
+```
+
+**After:**
+```tsx
+const agent = useHsafaAgent({
+  colors: {
+    primaryColor: '#0ea5e9',
+    backgroundColor: '#0B0B0F',
+    textColor: '#EDEEF0',
+    // ... other colors
+  }
+});
+
+// Then apply these colors in your own styling
+```
+
+### 8. Callbacks
+
+**Before:**
+```tsx
+<HsafaChat
+  onMessagesChange={(messages) => console.log(messages)}
+/>
+```
+
+**After:**
+```tsx
+const agent = useHsafaAgent({
+  onMessagesChange: (messages) => console.log(messages),
+  onFinish: (message) => console.log('Message done:', message),
+  onError: (error) => console.error('Error:', error),
+});
+```
+
+### 9. Dynamic Pages
+
+**Before:**
+```tsx
+<HsafaChat
+  dynamicPageTypes={[
+    { type: 'product-catalog', schema: { /* ... */ } }
+  ]}
+/>
+```
+
+**After:**
+```tsx
+const agent = useHsafaAgent({
+  dynamicPageTypes: [
+    { type: 'product-catalog', schema: { /* ... */ } }
+  ]
+});
+
+// Access dynamic page operations:
+agent.dynamicPage?.getOperations()
+```
+
+## Common Patterns
+
+### Pattern 1: Minimal Chat
+
+```tsx
+function MinimalChat() {
+  const agent = useHsafaAgent({
+    agentId: 'my-agent',
+    baseUrl: 'http://localhost:3000',
+  });
+
+  return (
+    <div className="chat-container">
+      <div className="messages">
+        {agent.messages.map(msg => (
+          <div key={msg.id} className={msg.role}>
+            {msg.content}
+          </div>
+        ))}
+      </div>
+      <div className="input-area">
+        <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>
+    </div>
+  );
+}
+```
+
+### Pattern 2: Full-Featured Chat
+
+```tsx
+function FullChat() {
+  const agent = useHsafaAgent({ /* config */ });
+  const fileUpload = useFileUpload('http://localhost:3000');
+  const storage = useChatStorage({ /* config */ });
+  const editor = useMessageEditor({ /* config */ });
+  const scrollRef = useAutoScroll(agent.isLoading);
+
+  return (
+    <div className="chat-layout">
+      {/* Sidebar with history */}
+      <aside>
+        {storage.chatList.map(chat => (
+          <ChatItem key={chat.id} {...chat} />
+        ))}
+      </aside>
+
+      {/* Main chat */}
+      <main>
+        <div ref={scrollRef} className="messages">
+          {agent.messages.map(msg => (
+            <Message key={msg.id} {...msg} editor={editor} />
+          ))}
+        </div>
+        <ChatInput 
+          agent={agent} 
+          fileUpload={fileUpload}
+        />
+      </main>
+    </div>
+  );
+}
+```
+
+## Migration Checklist
+
+- [ ] Identify all HsafaChat props you're using
+- [ ] Map each prop to the corresponding hook configuration
+- [ ] Replace `<HsafaChat />` with your custom UI
+- [ ] Use `useHsafaAgent` for core chat functionality
+- [ ] Add `useFileUpload` if you need file attachments
+- [ ] Add `useChatStorage` if you need chat history
+- [ ] Add `useMessageEditor` if you need message editing
+- [ ] Add `useAutoScroll` for auto-scrolling behavior
+- [ ] Test all functionality thoroughly
+- [ ] Update your styling to match your design system
+
+## Benefits After Migration
+
+1. **Full Control**: Style everything exactly as you want
+2. **Better Integration**: Seamlessly match your existing design system
+3. **Optimized Bundle**: Only include the hooks you need
+4. **Enhanced UX**: Build flows specific to your use case
+5. **Easier Testing**: Test UI and logic independently
+
+## Need Help?
+
+- 📚 [Headless Usage Guide](./HEADLESS_USAGE.md)
+- 📁 [Example Implementations](../examples/)
+- 🐛 [Report Issues](https://github.com/husamabusafa/hsafa/issues)

package/docs/README.md

@@ -1,11 +1,12 @@
 # HSAFA UI SDK — Advanced Guide
 
-Modern React SDK for integrating AI agents built with HSAFA AI Agent Studio into any web app. This guide covers architecture, setup, customization, streaming, actions, UI component injection, theming, i18n/RTL, persistence, and best practices.
+Modern React SDK for integrating AI agents built with HSAFA AI Agent Studio into any web app. This guide covers architecture, setup, customization, streaming, UI component injection, theming, RTL, persistence, and best practices.
 
 - **Package**: `@hsafa/ui-sdk`
 - **Entry point**: `sdk/src/index.ts`
-- **Core building blocks**: `HsafaProvider`, `HsafaChat`, `useHsafaAction`, `useHsafaComponent`, `useHsafa`
+- **Core building blocks**: `HsafaProvider`, `HsafaChat`, `useHsafaAgent`
 - **Generated API reference**: `sdk/docs/api/` (TypeDoc)
+- **Handbook (recommended)**: `sdk/docs/handbook/`
 
 ---
 
@@ -52,14 +53,10 @@ What this does under the hood:
 
 ## 3) Architecture overview
 
-- **Provider**: `HsafaProvider` stores SDK config and dynamic registries:
-  - `actions: Map<string, HsafaActionHandler>`
-  - `components: Map<string, React.ComponentType>`
-- **Chat UI**: `HsafaChat` handles input, history, streaming, rendering of assistant responses, and attachments.
-- **Streaming**: `useAgentStreaming()` parses NDJSON event stream into a structured timeline:
-  - `first-agent-*`, `main-agent-*` events, tool calls/results, reasoning, and final response items.
-- **Action execution**: agent’s response items can include `type: 'action'`. Use `useHsafaAction()` to register handlers.
-- **UI injection**: agent’s response items can include `type: 'ui'` to render custom components registered via `useHsafaComponent()`.
+- **Provider**: `HsafaProvider` stores SDK config and global UI preferences; tracks per-chat streaming/open state and dynamic page types.
+- **Chat UI**: `HsafaChat` handles input, history, streaming, and rendering of tool-driven UI (`HsafaUI`) and inline forms.
+- **Streaming**: Vercel AI SDK v5 `useChat()` is used under the hood (or via the headless `useHsafaAgent()`).
+- **Tools & UI**: Provide tools via `HsafaTools` (or `tools` in headless) and UI components via `HsafaUI` (or `uiComponents` in headless).
 
 Server contract (by default used by `HsafaChat`):
 - POST `{baseUrl}/api/run/:agentId` — streaming NDJSON
@@ -72,22 +69,19 @@ Server contract (by default used by `HsafaChat`):
 `HsafaProvider` (see `sdk/src/providers/HsafaProvider.tsx`):
 - Props:
   - `baseUrl?: string` — base URL for API calls (e.g. `""` for same-origin or `"https://api.example.com"`).
+  - `dir?: 'ltr' | 'rtl'`, `theme?: 'dark' | 'light'`
 - Context (`useHsafa()`):
   - `baseUrl?: string`
-  - `actions: Map<string, HsafaActionHandler>`
-  - `components: Map<string, React.ComponentType<any>>`
-  - `registerAction(name, handler) => unregister()`
-  - `unregisterAction(name, handler?)`
-  - `registerComponent(name, component) => unregister()`
-  - `unregisterComponent(name, component?)`
+  - Per-chat state: `setStreamingState(chatId, isStreaming)`, `setChatOpenState(chatId, isOpen)`, `currentChatId`, `setCurrentChatId`
+  - Dynamic pages: `dynamicPageTypes`, `registerDynamicPageTypes(chatId, types)`, `unregisterDynamicPageTypes(chatId)`
 
 Example using `useHsafa()` directly:
 ```tsx
 import { useHsafa } from '@hsafa/ui-sdk';
 
 function Debug() {
-  const { actions, components, baseUrl } = useHsafa();
-  // inspect registries or baseUrl
+  const { baseUrl } = useHsafa();
+  // inspect config if needed
   return null;
 }
 ```
@@ -120,55 +114,42 @@ Behavior highlights:
 - Persists chat sessions under `localStorage` prefix `hsafaChat_${agentId}`.
 - Supports file/image attachments with size checks and server upload.
 - Streams partial updates; auto-scrolls intelligently; preserves scroll when toggling reasoning.
-- Renders assistant "items" including markdown, mermaid diagrams, actions, and custom UI components.
+- Renders assistant "items" including markdown, mermaid diagrams, and custom UI components.
 
 ---
 
-## 6) Registering actions (agent -> app)
+## 6) Providing tools (agent -> UI)
 
-Use `useHsafaAction(name, handler)` to make functions callable by the agent. The handler receives `(params, meta)` where `meta` includes the `trigger` type:
-- `'partial'` — called during streaming (when explicitly enabled by the agent/SDK logic)
-- `'params_complete'` — parameters stabilized mid-stream (debounced and deduped)
-- `'final'` — after finalization
+Expose frontend-executed tools to the agent by passing them as `HsafaTools` (or `tools` in headless). Tools can be standard functions or streaming-friendly objects with `executeEachToken` (executed progressively during streaming).
 
 ```tsx
-import { useHsafaAction } from '@hsafa/ui-sdk';
-
-export function CartActions() {
-  useHsafaAction('addToCart', async (params, meta) => {
-    // params: arbitrary JSON inferred by the agent
-    // meta: { name, trigger, index, assistantMessageId?, chatId? }
-    await fetch('/api/cart', { method: 'POST', body: JSON.stringify(params) });
-    return { success: true };
-  });
-  return null;
-}
+const tools = {
+  add: async ({ a, b }: any) => ({ sum: a + b }),
+  editObject: { executeEachToken: true, tool: async (input: any) => {/* ... */} }
+};
+
+<HsafaChat agentId="my-agent" HsafaTools={tools} />
 ```
 
-Advanced execution behavior is implemented in `useActions()` / `useStreaming()` (parameter stabilization, debouncing, final guarantees). For most apps, just register via `useHsafaAction()`.
+Execution behavior (parameter stabilization, debouncing, final guarantees) is handled internally by the SDK.
 
 ---
 
-## 7) Registering UI components (agent-rendered UI)
+## 7) Providing UI components (agent-rendered)
 
-Use `useHsafaComponent(name, Component)` to expose UI that the agent can render with an item of shape `{ type: 'ui', component: name, props: {...} }`.
+Expose renderable components to the agent via `HsafaUI` (or `uiComponents` in headless). The agent can render them by name using the UI tool.
 
 ```tsx
-import { useHsafaComponent } from '@hsafa/ui-sdk';
-
 function ProductCard({ name, price }: { name: string; price: number }) {
   return <div>{name}: ${price}</div>;
 }
 
-export function UIRegistry() {
-  useHsafaComponent('ProductCard', ProductCard);
-  return null;
-}
+<HsafaChat agentId="my-agent" HsafaUI={{ ProductCard }} />
 ```
 
 If an agent returns an unregistered component name, `HsafaChat` will render a helpful placeholder with the props payload so you can register it.
 
-Relevant renderer: `sdk/src/components/AssistantMessageItems.tsx`.
+Relevant renderer: `sdk/src/components/hsafa-chat/AssistantMassage.tsx`.
 
 ---
 
@@ -176,8 +157,7 @@ Relevant renderer: `sdk/src/components/AssistantMessageItems.tsx`.
 
 `HsafaChat` expects a streaming sequence from the server that ultimately yields a `response` with `items`:
 - Strings are rendered as Markdown (`MarkdownRendererWithMermaid`).
-- Objects with `type: 'ui'` render registered components via the provider registry.
-- Objects with `type: 'action'` show execution status and trigger corresponding action handlers.
+- Objects with `type: 'ui'` render components provided via `HsafaUI`/`uiComponents`.
 - Tool calls/results and reasoning are also visualized.
 
 Example of a single final item payload (simplified):
@@ -214,16 +194,10 @@ Markdown with Mermaid is supported via `MarkdownRenderer` / `MarkdownRendererWit
 
 ---
 
-## 10) i18n and RTL
-
-- Supported languages: `'en' | 'ar'` (see `sdk/src/i18n/translations.ts`).
-- You can pass `language` and/or `dir` to `HsafaChat`:
+## 10) RTL and copy overrides
 
-```tsx
-<HsafaChat agentId="my-agent" language="ar" dir="rtl" />
-```
-
-Common UI strings for input/header/history are localized. You can still override `placeholder` and `title` directly.
+- You can pass `dir` to `HsafaChat` (or set globally via `HsafaProvider`).
+- Override UI copy via props (e.g., `placeholder`, `title`) or render custom components above the input.
 
 ---
 
@@ -255,7 +229,7 @@ Server is expected to return:
 
 ## 13) Streaming contract (server)
 
-The server should stream NDJSON lines with event `type` keys consumed by `useAgentStreaming()` (see `sdk/src/hooks/useAgentStreaming.ts`). Common events include:
+The server should stream NDJSON lines with event `type` keys consumed by Vercel AI SDK v5 `useChat()` (converted via `toUIMessageStream`). Common events include:
 - `first-agent-start|partial|end`
 - `main-agent-start|skipped|reasoning-start|reasoning-delta|reasoning-end`
 - `main-agent-tool-call-start|tool-call|tool-result|tool-error`
@@ -264,7 +238,7 @@ The server should stream NDJSON lines with event `type` keys consumed by `useAge
 - `final` (with `value.items`)
 - `error`
 
-You can adopt any LLM/tooling backend as long as you conform to the above event stream and endpoints.
+You can adopt any LLM/tooling backend as long as you conform to the above event stream and endpoints. See also the handbook: `sdk/docs/handbook/04-Streaming-and-Transport.md` and `08-Server-Integration.md`.
 
 ---
 
@@ -275,23 +249,22 @@ See ready-to-run examples in `sdk/examples/`:
 - `ecommerce-agent.tsx`
 - `nested-chat-example.tsx`
 
-A minimal page:
+A minimal page with custom UI and tools:
 ```tsx
-import { HsafaProvider, HsafaChat, useHsafaAction, useHsafaComponent } from '@hsafa/ui-sdk';
+import { HsafaProvider, HsafaChat } from '@hsafa/ui-sdk';
 
-function Registry() {
-  useHsafaAction('notify', async (params) => {
-    console.log('Notify', params);
-  });
-  useHsafaComponent('ProductCard', (p: any) => <div>{p.name}: ${p.price}</div>);
-  return null;
-}
+const tools = {
+  add: async ({ a, b }: any) => ({ sum: a + b })
+};
+
+const UI = {
+  ProductCard: (p: any) => <div>{p.name}: ${p.price}</div>
+};
 
 export default function Page() {
   return (
     <HsafaProvider baseUrl="">
-      <Registry />
-      <HsafaChat agentId="my-agent" theme="dark" />
+      <HsafaChat agentId="my-agent" theme="dark" HsafaTools={tools} HsafaUI={UI} />
     </HsafaProvider>
   );
 }
@@ -303,8 +276,7 @@ export default function Page() {
 
 - Ensure your server responds to `POST /api/run/:agentId` with `Content-Type: application/x-ndjson` and streams events, not a single JSON.
 - If attachments fail, verify `POST /api/uploads` exists and returns the required JSON fields.
-- Unregistered UI component? Check the `component` name in items and make sure you called `useHsafaComponent(name, Comp)` under the same `HsafaProvider`.
-- Actions not firing? Confirm the action name matches and that the agent actually emits `type: 'action'` items. Check browser console warnings from `useActions()`/`useStreaming()`.
+- Unregistered UI component? Check the `component` name in items and make sure it exists in `HsafaUI` (or `uiComponents` for headless usage).
 
 ---