@hsafa/ui-sdk 0.1.0

package/docs/api/interfaces/UseToggleReturn.md

@@ -0,0 +1,81 @@
+[**@hsafa/ui-sdk API Documentation**](../README.md)
+
+***
+
+[@hsafa/ui-sdk API Documentation](../globals.md) / UseToggleReturn
+
+# Interface: UseToggleReturn
+
+Defined in: [hooks/useToggle.ts:3](https://github.com/husamabusafa/hsafa/blob/1bcff44fada407a2574b2306f2d974ade919aebf/sdk/src/hooks/useToggle.ts#L3)
+
+## Properties
+
+### on
+
+> **on**: `boolean`
+
+Defined in: [hooks/useToggle.ts:5](https://github.com/husamabusafa/hsafa/blob/1bcff44fada407a2574b2306f2d974ade919aebf/sdk/src/hooks/useToggle.ts#L5)
+
+Current toggle state
+
+***
+
+### toggle()
+
+> **toggle**: () => `void`
+
+Defined in: [hooks/useToggle.ts:7](https://github.com/husamabusafa/hsafa/blob/1bcff44fada407a2574b2306f2d974ade919aebf/sdk/src/hooks/useToggle.ts#L7)
+
+Toggle the state
+
+#### Returns
+
+`void`
+
+***
+
+### setOn()
+
+> **setOn**: (`value`) => `void`
+
+Defined in: [hooks/useToggle.ts:9](https://github.com/husamabusafa/hsafa/blob/1bcff44fada407a2574b2306f2d974ade919aebf/sdk/src/hooks/useToggle.ts#L9)
+
+Set the state directly
+
+#### Parameters
+
+##### value
+
+`boolean` | (`prev`) => `boolean`
+
+#### Returns
+
+`void`
+
+***
+
+### setTrue()
+
+> **setTrue**: () => `void`
+
+Defined in: [hooks/useToggle.ts:11](https://github.com/husamabusafa/hsafa/blob/1bcff44fada407a2574b2306f2d974ade919aebf/sdk/src/hooks/useToggle.ts#L11)
+
+Set state to true
+
+#### Returns
+
+`void`
+
+***
+
+### setFalse()
+
+> **setFalse**: () => `void`
+
+Defined in: [hooks/useToggle.ts:13](https://github.com/husamabusafa/hsafa/blob/1bcff44fada407a2574b2306f2d974ade919aebf/sdk/src/hooks/useToggle.ts#L13)
+
+Set state to false
+
+#### Returns
+
+`void`

package/docs/api/variables/Button.md

@@ -0,0 +1,29 @@
+[**@hsafa/ui-sdk API Documentation**](../README.md)
+
+***
+
+[@hsafa/ui-sdk API Documentation](../globals.md) / Button
+
+# Variable: Button
+
+> `const` **Button**: `React.FC`\<[`ButtonProps`](../interfaces/ButtonProps.md)\>
+
+Defined in: [components/Button.tsx:36](https://github.com/husamabusafa/hsafa/blob/1bcff44fada407a2574b2306f2d974ade919aebf/sdk/src/components/Button.tsx#L36)
+
+A versatile button component with multiple variants, sizes, and states.
+
+## Example
+
+```tsx
+// Basic usage
+<Button>Click me</Button>
+
+// With variant and size
+<Button variant="secondary" size="lg">Large Secondary Button</Button>
+
+// Loading state
+<Button loading>Processing...</Button>
+
+// With click handler
+<Button onClick={() => console.log('Clicked!')}>Click me</Button>
+```

package/examples/ecommerce-agent.tsx

@@ -0,0 +1,229 @@
+/**
+ * E-commerce AI Agent Example
+ * 
+ * This example shows how to integrate the HSAFA SDK with an e-commerce application.
+ * The AI agent can search products, show product details, and process orders.
+ */
+
+import React from 'react';
+import { 
+  HsafaProvider, 
+  HsafaChat, 
+  useHsafaAction, 
+  useHsafaComponent 
+} from '@hsafa/ui-sdk';
+
+// Mock data
+const products = [
+  { id: 1, name: 'Wireless Headphones', price: 99.99, image: '/headphones.jpg', stock: 15 },
+  { id: 2, name: 'Smart Watch', price: 199.99, image: '/watch.jpg', stock: 8 },
+  { id: 3, name: 'Bluetooth Speaker', price: 79.99, image: '/speaker.jpg', stock: 22 },
+];
+
+const orders = new Map();
+
+// Product Card Component
+function ProductCard({ product, onAddToCart }: { product: any; onAddToCart: (id: number) => void }) {
+  return (
+    <div className="border rounded-lg p-4 bg-white shadow-sm">
+      <img 
+        src={product.image} 
+        alt={product.name}
+        className="w-full h-32 object-cover rounded mb-2"
+        onError={(e) => { e.currentTarget.src = '/placeholder.png'; }}
+      />
+      <h3 className="font-semibold text-lg">{product.name}</h3>
+      <p className="text-gray-600">${product.price}</p>
+      <p className="text-sm text-gray-500">Stock: {product.stock}</p>
+      <button 
+        onClick={() => onAddToCart(product.id)}
+        className="mt-2 w-full bg-blue-500 text-white py-2 px-4 rounded hover:bg-blue-600"
+        disabled={product.stock === 0}
+      >
+        {product.stock === 0 ? 'Out of Stock' : 'Add to Cart'}
+      </button>
+    </div>
+  );
+}
+
+// Order Summary Component
+function OrderSummary({ order }: { order: any }) {
+  return (
+    <div className="border rounded-lg p-4 bg-green-50 border-green-200">
+      <h3 className="font-semibold text-lg text-green-800">Order Confirmed!</h3>
+      <div className="mt-2 space-y-1">
+        <p><strong>Order ID:</strong> {order.id}</p>
+        <p><strong>Total:</strong> ${order.total}</p>
+        <p><strong>Status:</strong> {order.status}</p>
+        <p><strong>Estimated Delivery:</strong> {order.estimatedDelivery}</p>
+      </div>
+    </div>
+  );
+}
+
+// Component that provides actions and components to the AI agent
+function EcommerceActionProvider() {
+  // Action: Search for products
+  useHsafaAction('searchProducts', async (params) => {
+    const { query } = params;
+    console.log('🔍 Searching products:', query);
+    
+    // Simple search implementation
+    const results = products.filter(product => 
+      product.name.toLowerCase().includes(query.toLowerCase())
+    );
+    
+    return {
+      success: true,
+      products: results,
+      total: results.length
+    };
+  });
+
+  // Action: Get product details
+  useHsafaAction('getProduct', async (params) => {
+    const { productId } = params;
+    console.log('📦 Getting product:', productId);
+    
+    const product = products.find(p => p.id === parseInt(productId));
+    
+    if (!product) {
+      return { success: false, error: 'Product not found' };
+    }
+    
+    return {
+      success: true,
+      product
+    };
+  });
+
+  // Action: Create order
+  useHsafaAction('createOrder', async (params) => {
+    const { productId, quantity = 1, customerInfo } = params;
+    console.log('🛒 Creating order:', { productId, quantity, customerInfo });
+    
+    const product = products.find(p => p.id === parseInt(productId));
+    
+    if (!product) {
+      return { success: false, error: 'Product not found' };
+    }
+    
+    if (product.stock < quantity) {
+      return { success: false, error: 'Insufficient stock' };
+    }
+    
+    // Create order
+    const orderId = `ORD-${Date.now()}`;
+    const order = {
+      id: orderId,
+      productId: product.id,
+      productName: product.name,
+      quantity,
+      unitPrice: product.price,
+      total: (product.price * quantity).toFixed(2),
+      status: 'confirmed',
+      customerInfo,
+      estimatedDelivery: new Date(Date.now() + 7 * 24 * 60 * 60 * 1000).toLocaleDateString()
+    };
+    
+    orders.set(orderId, order);
+    
+    // Update stock
+    product.stock -= quantity;
+    
+    return {
+      success: true,
+      order
+    };
+  });
+
+  // Action: Check order status
+  useHsafaAction('checkOrder', async (params) => {
+    const { orderId } = params;
+    console.log('📋 Checking order:', orderId);
+    
+    const order = orders.get(orderId);
+    
+    if (!order) {
+      return { success: false, error: 'Order not found' };
+    }
+    
+    return {
+      success: true,
+      order
+    };
+  });
+
+  // Component: Product grid
+  useHsafaComponent('ProductGrid', ({ products: productList }) => (
+    <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4 p-4">
+      {productList.map((product: any) => (
+        <ProductCard 
+          key={product.id} 
+          product={product}
+          onAddToCart={(id) => console.log('Add to cart clicked:', id)}
+        />
+      ))}
+    </div>
+  ));
+
+  // Component: Single product display
+  useHsafaComponent('ProductDisplay', ({ product }) => (
+    <ProductCard 
+      product={product}
+      onAddToCart={(id) => console.log('Add to cart clicked:', id)}
+    />
+  ));
+
+  // Component: Order confirmation
+  useHsafaComponent('OrderConfirmation', ({ order }) => (
+    <OrderSummary order={order} />
+  ));
+
+  return null;
+}
+
+// Main E-commerce AI Agent App
+export function EcommerceAgentExample() {
+  return (
+    <div className="min-h-screen bg-gray-50 p-4">
+      <div className="max-w-4xl mx-auto">
+        <h1 className="text-3xl font-bold text-center mb-6">
+          E-commerce AI Assistant
+        </h1>
+        
+        <div className="bg-white rounded-lg shadow-lg p-6">
+          <HsafaProvider baseUrl="http://localhost:3900">
+            <EcommerceActionProvider />
+            
+            <div className="flex justify-center">
+              <HsafaChat
+                agentId="ecommerce-agent"
+                width={500}
+                height={600}
+                placeholder="Ask me about products, orders, or anything else!"
+                welcomeMessage="Hello! I'm your shopping assistant. I can help you find products, check prices, and place orders. What are you looking for today?"
+                primaryColor="#3b82f6"
+                backgroundColor="#ffffff"
+              />
+            </div>
+            
+            {/* Instructions */}
+            <div className="mt-6 p-4 bg-blue-50 border border-blue-200 rounded-lg">
+              <h3 className="font-semibold text-blue-800 mb-2">Try asking:</h3>
+              <ul className="text-sm text-blue-700 space-y-1">
+                <li>• "Show me all products"</li>
+                <li>• "Search for headphones"</li>
+                <li>• "I want to buy a smart watch"</li>
+                <li>• "Check my order status"</li>
+                <li>• "What's the price of the bluetooth speaker?"</li>
+              </ul>
+            </div>
+          </HsafaProvider>
+        </div>
+      </div>
+    </div>
+  );
+}
+
+export default EcommerceAgentExample;

package/examples/getting-started.tsx

@@ -0,0 +1,96 @@
+/**
+ * Getting Started Example
+ * 
+ * Simple example showing how to set up an AI agent with basic actions.
+ */
+
+import React from 'react';
+import { HsafaProvider, HsafaChat, useHsafaAction, useHsafaComponent } from '@hsafa/ui-sdk';
+
+// Simple action providers
+function BasicActionProviders() {
+  // Register a simple greeting action
+  useHsafaAction('getGreeting', async (params) => {
+    const { name } = params;
+    return {
+      message: `Hello ${name}! Welcome to HSAFA AI Agent Studio!`,
+      timestamp: new Date().toLocaleTimeString()
+    };
+  });
+
+  // Register a simple calculation action
+  useHsafaAction('calculate', async (params) => {
+    const { operation, a, b } = params;
+    
+    let result;
+    switch (operation) {
+      case 'add': result = a + b; break;
+      case 'subtract': result = a - b; break;
+      case 'multiply': result = a * b; break;
+      case 'divide': result = b !== 0 ? a / b : 'Cannot divide by zero'; break;
+      default: result = 'Unknown operation';
+    }
+    
+    return {
+      operation,
+      operands: [a, b],
+      result
+    };
+  });
+
+  // Register a simple info card component
+  useHsafaComponent('InfoCard', ({ title, content, type = 'info' }) => {
+    const colors = {
+      info: 'bg-blue-50 border-blue-200 text-blue-800',
+      success: 'bg-green-50 border-green-200 text-green-800',
+      warning: 'bg-yellow-50 border-yellow-200 text-yellow-800'
+    };
+    
+    return (
+      <div className={`p-4 border rounded-lg ${colors[type as keyof typeof colors]}`}>
+        <h3 className="font-semibold mb-2">{title}</h3>
+        <p>{content}</p>
+      </div>
+    );
+  });
+
+  return null;
+}
+
+export function GettingStartedExample() {
+  return (
+    <div className="min-h-screen bg-gray-50 p-8">
+      <div className="max-w-2xl mx-auto">
+        <h1 className="text-3xl font-bold text-center mb-6">
+          Getting Started with HSAFA AI Agent SDK
+        </h1>
+        
+        <div className="bg-white rounded-lg shadow-lg p-6">
+          <HsafaProvider baseUrl="http://localhost:3900">
+            <BasicActionProviders />
+            
+            <HsafaChat
+              agentId="demo-agent"
+              width={600}
+              height={500}
+              placeholder="Try asking me to greet you or do some math!"
+              welcomeMessage="Hi! I'm your AI assistant. I can greet people and do simple calculations. Try asking me something!"
+            />
+            
+            <div className="mt-4 p-3 bg-gray-50 rounded text-sm text-gray-600">
+              <strong>Try these examples:</strong>
+              <ul className="mt-1 space-y-1">
+                <li>• "Greet me, my name is John"</li>
+                <li>• "Calculate 15 + 25"</li>
+                <li>• "What's 100 divided by 4?"</li>
+                <li>• "Show me an info card about AI"</li>
+              </ul>
+            </div>
+          </HsafaProvider>
+        </div>
+      </div>
+    </div>
+  );
+}
+
+export default GettingStartedExample;

package/package.json

@@ -0,0 +1,109 @@
+{
+  "name": "@hsafa/ui-sdk",
+  "version": "0.1.0",
+  "description": "React SDK for integrating AI agents built with HSAFA AI Agent Studio",
+  "type": "module",
+  "files": [
+    "dist",
+    "examples",
+    "docs",
+    "DOCUMENTATION.md"
+  ],
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest",
+    "test:ui": "vitest --ui",
+    "storybook": "storybook dev -p 6006",
+    "build-storybook": "storybook build",
+    "lint": "eslint src --ext .ts,.tsx",
+    "type-check": "tsc --noEmit",
+    "docs:api": "typedoc",
+    "docs:dev": "pnpm storybook",
+    "docs:build": "pnpm build-storybook && pnpm docs:api",
+    "prepublishOnly": "pnpm build && pnpm test",
+    "publish:npm": "npm publish --access public"
+  },
+  "peerDependencies": {
+    "@tabler/icons-react": ">=3",
+    "react": ">=18",
+    "react-dom": ">=18"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.35.0",
+    "@storybook/addon-essentials": "^8.6.14",
+    "@storybook/addon-interactions": "^8.6.14",
+    "@storybook/addon-links": "^8.6.14",
+    "@storybook/react": "^8.6.14",
+    "@storybook/react-vite": "^8.6.14",
+    "@swc/core": "^1.3.0",
+    "@tabler/icons-react": "^3.21.0",
+    "@testing-library/jest-dom": "^6.1.5",
+    "@testing-library/react": "^14.1.2",
+    "@testing-library/user-event": "^14.5.1",
+    "@types/react": "^18.2.45",
+    "@types/react-dom": "^18.2.18",
+    "@typescript-eslint/eslint-plugin": "^8.43.0",
+    "@typescript-eslint/parser": "^8.43.0",
+    "@vitejs/plugin-react": "^4.2.1",
+    "autoprefixer": "^10.4.16",
+    "eslint": "^9.35.0",
+    "eslint-plugin-react-hooks": "^5.2.0",
+    "eslint-plugin-react-refresh": "^0.4.20",
+    "globals": "^15.15.0",
+    "jsdom": "^23.0.1",
+    "postcss": "^8.4.32",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "storybook": "^8.6.14",
+    "tailwindcss": "^3.3.6",
+    "tsup": "^8.0.1",
+    "typedoc": "^0.28.12",
+    "typedoc-plugin-markdown": "^4.8.1",
+    "typescript": "^5.3.3",
+    "vite": "^5.0.0",
+    "vitest": "^1.1.0"
+  },
+  "keywords": [
+    "react",
+    "ui",
+    "components",
+    "typescript",
+    "sdk",
+    "hsafa",
+    "chat",
+    "ai",
+    "frontend",
+    "library",
+    "hooks",
+    "tailwind",
+    "modern"
+  ],
+  "author": "Husam Abu Safa",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/husamabusafa/hsafa.git",
+    "directory": "sdk"
+  },
+  "homepage": "https://github.com/husamabusafa/hsafa/tree/main/sdk#readme",
+  "bugs": {
+    "url": "https://github.com/husamabusafa/hsafa/issues"
+  }
+}