@hsafa/ui-sdk 0.3.3 → 0.4.1

package/docs/CUSTOM_UI_EXAMPLES.md

@@ -0,0 +1,309 @@
+# Custom UI Customization Examples
+
+This document provides examples for the customization features added to the `HsafaChat` component.
+
+## Table of Contents
+
+1. [Custom Tool UI with HsafaUI](#1-custom-tool-ui-with-hsafaui)
+2. [Component Above Chat Input](#2-component-above-chat-input)
+
+---
+
+## 1. Custom Tool UI with HsafaUI
+
+Create custom UIs for specific tool calls using the `HsafaUI` prop. Your components will receive all tool data including `addToolResult` callback to send results back to the agent.
+
+### Usage Example
+
+```tsx
+import { HsafaChat, CustomToolUIRenderProps } from '@hsafa/sdk';
+
+// Custom UI component for a tool
+function ChoiceToolUI({ toolName, toolCallId, input, output, status, addToolResult, ...restInputProps }: CustomToolUIRenderProps & any) {
+  const [selectedChoice, setSelectedChoice] = useState<string | null>(null);
+  
+  const handleChoice = (choice: string) => {
+    setSelectedChoice(choice);
+    
+    // Send the result back to the agent
+    addToolResult({
+      tool: toolName,
+      toolCallId: toolCallId,
+      output: {
+        choice: choice,
+        timestamp: Date.now()
+      }
+    });
+  };
+  
+  return (
+    <div style={{ padding: '16px', border: '1px solid #ddd', borderRadius: '8px' }}>
+      <h3>Make a choice:</h3>
+      <p>{input?.question || 'Please select an option'}</p>
+      <div style={{ display: 'flex', gap: '8px', marginTop: '12px' }}>
+        <button 
+          onClick={() => handleChoice('yes')}
+          disabled={selectedChoice !== null}
+          style={{
+            padding: '8px 16px',
+            backgroundColor: selectedChoice === 'yes' ? '#10b981' : '#3b82f6',
+            color: 'white',
+            border: 'none',
+            borderRadius: '6px',
+            cursor: selectedChoice ? 'default' : 'pointer'
+          }}
+        >
+          Yes
+        </button>
+        <button 
+          onClick={() => handleChoice('no')}
+          disabled={selectedChoice !== null}
+          style={{
+            padding: '8px 16px',
+            backgroundColor: selectedChoice === 'no' ? '#10b981' : '#ef4444',
+            color: 'white',
+            border: 'none',
+            borderRadius: '6px',
+            cursor: selectedChoice ? 'default' : 'pointer'
+          }}
+        >
+          No
+        </button>
+      </div>
+      {selectedChoice && (
+        <p style={{ marginTop: '8px', color: '#10b981' }}>
+          ✓ Choice sent: {selectedChoice}
+        </p>
+      )}
+    </div>
+  );
+}
+
+// Use in HsafaChat with HsafaUI prop
+function App() {
+  return (
+    <HsafaChat
+      agentId="my-agent"
+      HsafaUI={{
+        'getUserChoice': ChoiceToolUI,
+        'confirmAction': ChoiceToolUI,
+      }}
+    />
+  );
+}
+```
+
+### Props Available
+
+Your HsafaUI components receive **both** the standard tool data **and** all input parameters:
+
+- `toolName: string` - Name of the tool being called
+- `toolCallId: string` - Unique ID for this tool call instance
+- `input: any` - Input parameters object
+- `output: any` - Output from the tool (if available)
+- `status?: string` - Current status of the tool call
+- `addToolResult: (result: any) => void` - Function to send result back to the agent
+- `...restInputProps` - All input parameters are also spread as individual props
+
+### Key Points
+
+- Use the **HsafaUI** prop (same as for regular UI components)
+- Components automatically receive **enhanced props** including `addToolResult`
+- The custom UI has **full control** over when to send results
+- You can create interactive UIs that wait for user input
+- Multiple buttons/actions can send different results
+- Access tool data via structured props OR spread input props
+
+---
+
+## 2. Component Above Chat Input
+
+Add a persistent component above the chat input (e.g., quick actions, status bar, suggestions).
+
+### Usage Example
+
+```tsx
+import { HsafaChat } from '@hsafa/sdk';
+
+function QuickActions() {
+  const handleQuickAction = (action: string) => {
+    console.log('Quick action:', action);
+    // You can trigger actions here
+  };
+  
+  return (
+    <div style={{
+      padding: '12px',
+      backgroundColor: '#f9fafb',
+      borderRadius: '8px',
+      marginBottom: '8px'
+    }}>
+      <p style={{ 
+        fontSize: '12px', 
+        color: '#6B7280', 
+        marginBottom: '8px',
+        fontWeight: 500
+      }}>
+        Quick Actions:
+      </p>
+      <div style={{ display: 'flex', gap: '8px', flexWrap: 'wrap' }}>
+        <button
+          onClick={() => handleQuickAction('summarize')}
+          style={{
+            padding: '6px 12px',
+            backgroundColor: 'white',
+            border: '1px solid #E5E7EB',
+            borderRadius: '6px',
+            fontSize: '13px',
+            cursor: 'pointer',
+            transition: 'all 0.2s'
+          }}
+        >
+          📝 Summarize
+        </button>
+        <button
+          onClick={() => handleQuickAction('analyze')}
+          style={{
+            padding: '6px 12px',
+            backgroundColor: 'white',
+            border: '1px solid #E5E7EB',
+            borderRadius: '6px',
+            fontSize: '13px',
+            cursor: 'pointer',
+            transition: 'all 0.2s'
+          }}
+        >
+          📊 Analyze
+        </button>
+        <button
+          onClick={() => handleQuickAction('translate')}
+          style={{
+            padding: '6px 12px',
+            backgroundColor: 'white',
+            border: '1px solid #E5E7EB',
+            borderRadius: '6px',
+            fontSize: '13px',
+            cursor: 'pointer',
+            transition: 'all 0.2s'
+          }}
+        >
+          🌐 Translate
+        </button>
+      </div>
+    </div>
+  );
+}
+
+// Example 2: Smart Suggestions
+function SmartSuggestions() {
+  const suggestions = [
+    "What can you help me with?",
+    "Show me recent updates",
+    "Generate a report"
+  ];
+  
+  return (
+    <div style={{
+      padding: '8px',
+      backgroundColor: '#EEF2FF',
+      borderRadius: '8px',
+      marginBottom: '8px'
+    }}>
+      <p style={{ fontSize: '11px', color: '#6366F1', marginBottom: '6px' }}>
+        💡 Try asking:
+      </p>
+      <div style={{ display: 'flex', flexDirection: 'column', gap: '4px' }}>
+        {suggestions.map((suggestion, i) => (
+          <div
+            key={i}
+            style={{
+              padding: '6px 10px',
+              backgroundColor: 'white',
+              borderRadius: '4px',
+              fontSize: '12px',
+              cursor: 'pointer',
+              border: '1px solid #C7D2FE'
+            }}
+          >
+            {suggestion}
+          </div>
+        ))}
+      </div>
+    </div>
+  );
+}
+
+// Use in HsafaChat
+function App() {
+  return (
+    <HsafaChat
+      agentId="my-agent"
+      componentAboveInput={QuickActions}
+      // Or use SmartSuggestions
+      // componentAboveInput={SmartSuggestions}
+    />
+  );
+}
+```
+
+### Key Points
+
+- Component is rendered **above** the chat input
+- Always visible (sticky with the input area)
+- Perfect for:
+  - Quick action buttons
+  - Smart suggestions
+  - Status indicators
+  - Context-aware tools
+  - File upload shortcuts
+
+---
+
+## Complete Example
+
+Combining all customizations:
+
+```tsx
+import { HsafaChat } from '@hsafa/sdk';
+import { ChoiceToolUI } from './components/ChoiceToolUI';
+import { QuickActions } from './components/QuickActions';
+
+function App() {
+  return (
+    <HsafaChat
+      agentId="my-agent"
+      theme="dark"
+      
+      // Custom tool UIs (same prop as regular UI components!)
+      HsafaUI={{
+        'getUserChoice': ChoiceToolUI,
+        'confirmAction': ChoiceToolUI,
+      }}
+      
+      // Component above input
+      componentAboveInput={QuickActions}
+      
+      // Other props...
+      HsafaTools={{
+        // Your custom tools
+      }}
+    />
+  );
+}
+
+export default App;
+```
+
+---
+
+## TypeScript Types
+
+All types are exported from the SDK:
+
+```tsx
+import type {
+  CustomToolUIRenderProps,
+  CustomEditModalRenderProps,
+  Attachment
+} from '@hsafa/sdk';
+```

package/docs/DYNAMIC_PAGE_SCHEMAS.md

@@ -0,0 +1,261 @@
+# Dynamic Page Schemas Guide
+
+This guide explains how to use optional Zod schemas and examples with Dynamic Page component types.
+
+## Overview
+
+Dynamic Page types can now include optional **schemas** and **examples** to help the AI agent understand the expected data structure for each component type. When the agent calls `readAvailableTypes`, it receives detailed information about each type including:
+
+- **Type name** and **description**
+- **Schema** (JSON Schema format or Zod schema info)
+- **Examples** showing valid data structures
+- **Variants** (if applicable)
+
+## Adding Schemas to Types
+
+### JSON Schema Format (Recommended)
+
+```typescript
+const dynamicPageTypes: DynamicPageTypeConfig[] = [
+  {
+    type: 'chart',
+    component: ChartComponent,
+    description: 'Display data as interactive bar charts',
+    schema: {
+      type: 'object',
+      properties: {
+        title: { type: 'string', description: 'Chart title' },
+        series: {
+          type: 'array',
+          items: {
+            type: 'object',
+            properties: {
+              name: { type: 'string' },
+              values: { type: 'array', items: { type: 'number' } }
+            },
+            required: ['name', 'values']
+          }
+        }
+      },
+      required: ['series']
+    },
+    examples: [
+      {
+        title: 'Monthly Sales',
+        series: [
+          { name: '2024', values: [100, 150, 200] },
+          { name: '2025', values: [120, 180, 220] }
+        ]
+      }
+    ]
+  }
+];
+```
+
+### Using Zod Schemas
+
+```typescript
+import { z } from 'zod';
+
+const chartSchema = z.object({
+  title: z.string().optional(),
+  series: z.array(z.object({
+    name: z.string(),
+    values: z.array(z.number())
+  }))
+});
+
+const dynamicPageTypes: DynamicPageTypeConfig[] = [
+  {
+    type: 'chart',
+    component: ChartComponent,
+    description: 'Display data as interactive bar charts',
+    schema: chartSchema, // Zod schema will be serialized automatically
+    examples: [
+      {
+        title: 'Monthly Sales',
+        series: [
+          { name: '2024', values: [100, 150, 200] }
+        ]
+      }
+    ]
+  }
+];
+```
+
+## What the Agent Sees
+
+When calling `readAvailableTypes()`, the agent receives:
+
+```json
+{
+  "success": true,
+  "message": "Found 6 registered component type(s)...",
+  "types": [
+    {
+      "type": "chart",
+      "description": "Display data as interactive bar charts with multiple series",
+      "variants": ["bar", "line", "area"],
+      "has_schema": true,
+      "schema": {
+        "type": "object",
+        "properties": {
+          "title": { "type": "string", "description": "Chart title" },
+          "series": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "name": { "type": "string" },
+                "values": { "type": "array", "items": { "type": "number" } }
+              }
+            }
+          }
+        }
+      },
+      "examples": [
+        {
+          "title": "Monthly Sales",
+          "series": [
+            { "name": "2024", "values": [100, 150, 200] }
+          ]
+        }
+      ],
+      "example_count": 1
+    }
+  ],
+  "available_types": ["chart", "table", "metric", "text", "progress", "status"],
+  "total_count": 6,
+  "types_with_schema": 6
+}
+```
+
+## Benefits
+
+1. **Type Safety**: Agents know exactly what data structure each component expects
+2. **Better Errors**: Detailed validation errors when data doesn't match schema
+3. **Discoverability**: Agents can explore available types and their requirements
+4. **Examples**: Concrete examples help agents understand complex structures
+5. **Documentation**: Self-documenting component types
+
+## Best Practices
+
+### 1. Always Provide a Description
+```typescript
+{
+  type: 'metric',
+  description: 'Showcase KPIs with large numbers and change indicators', // Clear description
+  component: MetricComponent
+}
+```
+
+### 2. Include Examples for Complex Types
+```typescript
+{
+  type: 'table',
+  schema: { /* complex schema */ },
+  examples: [
+    {
+      columns: [
+        { key: 'name', title: 'Name' },
+        { key: 'value', title: 'Value' }
+      ],
+      rows: [
+        { name: 'Item 1', value: '100' }
+      ]
+    }
+  ]
+}
+```
+
+### 3. Document Required vs Optional Fields
+```typescript
+schema: {
+  type: 'object',
+  properties: {
+    value: { type: 'string', description: 'The metric value (required)' },
+    label: { type: 'string', description: 'Metric label (required)' },
+    change: { type: 'string', description: 'Change indicator (optional)' }
+  },
+  required: ['value', 'label'] // Explicitly mark required fields
+}
+```
+
+### 4. Use Enums for Limited Options
+```typescript
+schema: {
+  type: 'object',
+  properties: {
+    status: {
+      type: 'string',
+      enum: ['success', 'warning', 'error', 'info'],
+      description: 'Status type'
+    }
+  }
+}
+```
+
+## Schema Serialization
+
+- **JSON Schema**: Passed through as-is
+- **Zod Schema**: Automatically converted to a basic representation with type info
+- **Plain Objects**: Treated as JSON Schema
+
+## Example: Complete Type Definition
+
+```typescript
+{
+  type: 'progress',
+  component: ProgressComponent,
+  description: 'Show progress bars with percentages and colors',
+  schema: {
+    type: 'object',
+    properties: {
+      items: {
+        type: 'array',
+        description: 'Array of progress items',
+        items: {
+          type: 'object',
+          properties: {
+            label: { type: 'string', description: 'Item label' },
+            progress: {
+              type: 'number',
+              minimum: 0,
+              maximum: 100,
+              description: 'Progress percentage (0-100)'
+            },
+            color: { type: 'string', description: 'Optional color' }
+          },
+          required: ['label', 'progress']
+        }
+      }
+    },
+    required: ['items']
+  },
+  examples: [
+    {
+      items: [
+        { label: 'Task 1', progress: 75, color: '#3b82f6' },
+        { label: 'Task 2', progress: 40 }
+      ]
+    }
+  ]
+}
+```
+
+## Testing Your Schemas
+
+1. Call `readAvailableTypes()` and verify the schema appears correctly
+2. Try creating objects with valid data matching the schema
+3. Try creating objects with invalid data to test error messages
+4. Check that examples render correctly in the UI
+
+## Migration Guide
+
+Existing types without schemas will continue to work. To add schemas:
+
+1. Add a `schema` field to your type config (JSON Schema or Zod)
+2. Optionally add `examples` array
+3. Rebuild and test with `readAvailableTypes()`
+
+No breaking changes - schemas are purely additive!