@hsafa/ui-sdk 0.1.4 → 0.1.6

package/docs/README.md

@@ -0,0 +1,327 @@
+# 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.
+
+- **Package**: `@hsafa/ui-sdk`
+- **Entry point**: `sdk/src/index.ts`
+- **Core building blocks**: `HsafaProvider`, `HsafaChat`, `useHsafaAction`, `useHsafaComponent`, `useHsafa`
+- **Generated API reference**: `sdk/docs/api/` (TypeDoc)
+
+---
+
+## 1) Install
+
+```bash
+pnpm add @hsafa/ui-sdk
+# or
+npm i @hsafa/ui-sdk
+```
+
+Peer dependencies:
+- react >= 18
+- react-dom >= 18
+- @tabler/icons-react (icons used by some components)
+
+---
+
+## 2) Quick start
+
+Wrap your app with `HsafaProvider` and render `HsafaChat` anywhere. The `baseUrl` should point to your server that exposes the agent API endpoints.
+
+```tsx
+import React from 'react';
+import { HsafaProvider, HsafaChat } from '@hsafa/ui-sdk';
+
+export default function App() {
+  return (
+    <HsafaProvider baseUrl={process.env.NEXT_PUBLIC_API_BASE || ''}>
+      <main style={{ height: '100vh' }}>
+        <HsafaChat agentId="my-agent-id" theme="dark" />
+      </main>
+    </HsafaProvider>
+  );
+}
+```
+
+What this does under the hood:
+- Streams NDJSON from `POST {baseUrl}/api/run/:agentId` with `Accept: application/x-ndjson`.
+- Uploads files to `POST {baseUrl}/api/uploads` and attaches them to prompts.
+- Persists chat history and UI state in `localStorage` by `agentId`.
+
+---
+
+## 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()`.
+
+Server contract (by default used by `HsafaChat`):
+- POST `{baseUrl}/api/run/:agentId` — streaming NDJSON
+- POST `{baseUrl}/api/uploads` — file uploads
+
+---
+
+## 4) Provider API
+
+`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"`).
+- 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?)`
+
+Example using `useHsafa()` directly:
+```tsx
+import { useHsafa } from '@hsafa/ui-sdk';
+
+function Debug() {
+  const { actions, components, baseUrl } = useHsafa();
+  // inspect registries or baseUrl
+  return null;
+}
+```
+
+---
+
+## 5) Chat component (`HsafaChat`)
+
+Source: `sdk/src/components/HsafaChat.tsx`
+
+Minimal usage:
+```tsx
+<HsafaChat agentId="my-agent" />
+```
+
+Important props (selected):
+- `agentId: string` — required
+- `theme?: 'light' | 'dark'` — default `dark`
+- `language?: 'en' | 'ar'` — defaults by `dir` if not provided
+- `dir?: 'ltr' | 'rtl'` — controls layout RTL/LTR
+- Colors (override theme defaults): `primaryColor`, `backgroundColor`, `borderColor`, `textColor`, `accentColor`
+- Layout: `width` (default 420), `height` (default `100vh`), `floatingButtonPosition`, `alwaysOpen`, `defaultOpen`, `expandable`, `maximized`
+- Borders/animation: `enableBorderAnimation`, `enableContentPadding`, `enableContentBorder`, `borderRadius`
+- UX copy: `placeholder`, `title`
+- Advanced UI: `defaultReasoningOpen`, `hideReasoningContent`
+- Styling hooks: `className`, `chatContainerClassName`
+- Children: content beside the fixed chat panel (panel opens over the right/left edge)
+
+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.
+
+---
+
+## 6) Registering actions (agent -> app)
+
+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
+
+```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;
+}
+```
+
+Advanced execution behavior is implemented in `useActions()` / `useStreaming()` (parameter stabilization, debouncing, final guarantees). For most apps, just register via `useHsafaAction()`.
+
+---
+
+## 7) Registering UI components (agent-rendered UI)
+
+Use `useHsafaComponent(name, Component)` to expose UI that the agent can render with an item of shape `{ type: 'ui', component: name, props: {...} }`.
+
+```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;
+}
+```
+
+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`.
+
+---
+
+## 8) What does the assistant response look like?
+
+`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.
+- Tool calls/results and reasoning are also visualized.
+
+Example of a single final item payload (simplified):
+```json
+{
+  "type": "ui",
+  "component": "ProductCard",
+  "props": { "name": "Laptop", "price": 1299 }
+}
+```
+
+---
+
+## 9) Theming & styling
+
+Theme presets (`light`/`dark`) with overridable colors. See `sdk/src/utils/chat-theme.ts`.
+
+- Preset colors: `primaryColor`, `backgroundColor`, `borderColor`, `textColor`, `accentColor`, plus `mutedTextColor`, `inputBackground`, `cardBackground`, `hoverBackground` (derived).
+- Override via `HsafaChat` props:
+
+```tsx
+<HsafaChat
+  agentId="my-agent"
+  theme="light"
+  primaryColor="#3b82f6"
+  backgroundColor="#ffffff"
+  borderColor="#e5e7eb"
+  textColor="#111827"
+  accentColor="#F9FAFB"
+/>
+```
+
+Markdown with Mermaid is supported via `MarkdownRenderer` / `MarkdownRendererWithMermaid` and `MermaidDiagram`.
+
+---
+
+## 10) i18n and RTL
+
+- Supported languages: `'en' | 'ar'` (see `sdk/src/i18n/translations.ts`).
+- You can pass `language` and/or `dir` to `HsafaChat`:
+
+```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.
+
+---
+
+## 11) Persistence & storage
+
+`HsafaChat` uses `useChatStorage(agentId)` to persist:
+- Chats index and message history under `localStorage` key prefix `hsafaChat_${agentId}`.
+- Current chat ID and chat visibility (`.currentChatId`, `.showChat`).
+
+Key API (see `sdk/src/hooks/useChatStorage.ts`):
+- `createNewChat(firstMessage?)` — returns new chat id
+- `persistChatData(messages)` — saves messages + updates meta
+- `loadChatsIndex()`, `loadChat(id)`, `deleteChat(id, cb)`
+
+---
+
+## 12) Attachments & uploads
+
+`HsafaChat` integrates `useFileUpload(baseUrl)` which:
+- Validates size (default 25MB) and uploads to `{baseUrl}/api/uploads`.
+- Adds uploaded assets to the user message content as `image` or `file` parts.
+
+Server is expected to return:
+```json
+{ "id": "file-id", "name": "foo.png", "url": "https://...", "mimeType": "image/png", "size": 12345 }
+```
+
+---
+
+## 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:
+- `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`
+- `main-agent-response-partial` (with `value.items`)
+- `text-delta|text-end`
+- `final` (with `value.items`)
+- `error`
+
+You can adopt any LLM/tooling backend as long as you conform to the above event stream and endpoints.
+
+---
+
+## 14) Full example
+
+See ready-to-run examples in `sdk/examples/`:
+- `getting-started.tsx`
+- `ecommerce-agent.tsx`
+- `nested-chat-example.tsx`
+
+A minimal page:
+```tsx
+import { HsafaProvider, HsafaChat, useHsafaAction, useHsafaComponent } 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;
+}
+
+export default function Page() {
+  return (
+    <HsafaProvider baseUrl="">
+      <Registry />
+      <HsafaChat agentId="my-agent" theme="dark" />
+    </HsafaProvider>
+  );
+}
+```
+
+---
+
+## 15) Troubleshooting
+
+- 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()`.
+
+---
+
+## 16) API reference
+
+The full API is generated from TypeScript types. Start here:
+- `sdk/docs/api/README.md`
+- `sdk/docs/api/functions/HsafaChat.md`
+- `sdk/docs/api/functions/HsafaProvider.md`
+- `sdk/docs/api/functions/useHsafa.md`
+- `sdk/docs/api/functions/useHsafaAction.md`
+- `sdk/docs/api/functions/useHsafaComponent.md`
+
+---
+
+## 17) License & links
+
+- License: MIT
+- Repo: https://github.com/husamabusafa/hsafa/tree/main/sdk
+- Issues: https://github.com/husamabusafa/hsafa/issues

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hsafa/ui-sdk",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "React SDK for integrating AI agents built with HSAFA AI Agent Studio",
   "type": "module",
   "files": [