@cuadra-ai/uikit 0.1.0

package/README.md

@@ -0,0 +1,272 @@
+# @cuadra-ai/uikit
+
+A production-ready React UI kit for building AI chat experiences with the [Cuadra AI](https://cuadra.ai) API, built on top of [assistant-ui](https://www.assistant-ui.com/).
+
+📚 **[Full Documentation](https://docs.cuadra.ai)** | 🌐 **[Website](https://cuadra.ai)**
+
+## Features
+
+- 🚀 **Ready-to-use chat components** - Pre-built thread list, message display, and composer
+- 🎨 **Beautiful UI** - Textured card design with theme support (light/dark/system)
+- 🔄 **Multiple chat modes** - Single chat or multi-thread support
+- 🤖 **Model selection** - Fixed model or dynamic model selector
+- 📦 **Two build formats**:
+  - **Library build** (ESM/CJS) - For use in React applications
+  - **Widget build** (UMD) - For direct browser embedding via script tag
+- 🔐 **Flexible authentication** - Bearer token or proxy mode for backend-handled auth
+- ⚡ **Streaming support** - Real-time message streaming via SSE
+- 🧵 **Thread management** - Create, rename, delete, and switch between chat threads
+- 🌐 **i18n ready** - Language/locale support
+
+## Installation
+
+```bash
+npm install @cuadra-ai/uikit
+```
+
+### Peer Dependencies
+
+This package requires the following peer dependencies:
+
+```bash
+npm install react react-dom
+```
+
+Note: `@assistant-ui/react` and `@assistant-ui/react-markdown` are bundled dependencies and don't need to be installed separately.
+
+## Usage
+
+### Using CuadraChat Component (Recommended)
+
+The `CuadraChat` component is the easiest way to get started. It's an all-in-one component that handles everything for you.
+
+#### Basic Example
+
+```tsx
+import { CuadraChat } from '@cuadra-ai/uikit';
+import '@cuadra-ai/uikit/styles';
+
+function App() {
+  return (
+    <div style={{ height: '100vh' }}>
+      <CuadraChat
+        baseUrl="https://api.cuadra.ai"
+        sessionToken="your-session-token"
+        mode="multiChat"
+        modelMode="fixed"
+        modelId="your-model-id" // Get this from dashboard.cuadra.ai
+      />
+    </div>
+  );
+}
+```
+
+**Note:** Model IDs are provided in your [Cuadra AI Dashboard](https://dashboard.cuadra.ai). Create and manage your models there, then use the model ID in your code.
+
+#### With Model Selector
+
+```tsx
+import { CuadraChat } from '@cuadra-ai/uikit';
+import '@cuadra-ai/uikit/styles';
+import { useState } from 'react';
+
+function App() {
+  const [modelId, setModelId] = useState<string | null>(null);
+
+  return (
+    <div style={{ height: '100vh' }}>
+      <CuadraChat
+        baseUrl="https://api.cuadra.ai"
+        sessionToken="your-session-token"
+        mode="multiChat"
+        modelMode="selector"
+        modelId={modelId || undefined}
+        onModelChange={setModelId}
+      />
+    </div>
+  );
+}
+```
+
+#### Proxy Mode (Backend Authentication)
+
+When your backend handles authentication, use `proxyUrl` instead of `baseUrl`:
+
+```tsx
+import { CuadraChat } from '@cuadra-ai/uikit';
+import '@cuadra-ai/uikit/styles';
+
+function App() {
+  return (
+    <div style={{ height: '100vh' }}>
+      <CuadraChat
+        proxyUrl="/api/chat"
+        mode="multiChat"
+        modelMode="fixed"
+        modelId="your-model-id"
+      />
+    </div>
+  );
+}
+```
+
+#### Customization Options
+
+```tsx
+import { CuadraChat } from '@cuadra-ai/uikit';
+import '@cuadra-ai/uikit/styles';
+
+function App() {
+  return (
+    <div style={{ height: '100vh' }}>
+      <CuadraChat
+        baseUrl="https://api.cuadra.ai"
+        sessionToken="your-session-token"
+        mode="multiChat"
+        modelMode="fixed"
+        modelId="your-model-id"
+        className="my-custom-class"
+        showThemeToggle={true}
+        theme="system"
+        language="en"
+        welcomeTitle="Welcome to Chat"
+        welcomeSubtitle="How can I help you today?"
+        extraTopPadding="2rem"
+        suggestions={[
+          { prompt: "What is Cuadra AI?" },
+          { prompt: "How do I get started?" },
+          { prompt: "Show me examples" }
+        ]}
+        onChatCreated={(chatId) => {
+          console.log('Chat created:', chatId);
+        }}
+        onThreadIdUpdate={(oldId, newId) => {
+          console.log('Thread updated:', oldId, '->', newId);
+        }}
+        onError={(error) => {
+          console.error('Error:', error);
+        }}
+      />
+    </div>
+  );
+}
+```
+
+### Widget Mode (Script Tag - Compiled JS)
+
+The widget build allows you to embed the chat interface directly in any HTML page without a build step.
+
+#### Basic HTML Setup
+
+```html
+<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="UTF-8">
+  <title>Cuadra Chat</title>
+  <link rel="stylesheet" href="https://unpkg.com/@cuadra-ai/uikit@latest/dist/widget/cuadra-uikit.css">
+  <style>
+    body {
+      margin: 0;
+      padding: 0;
+      height: 100vh;
+    }
+    #cuadra-chat {
+      height: 100vh;
+      width: 100%;
+    }
+  </style>
+</head>
+<body>
+  <div id="cuadra-chat"></div>
+  
+  <script src="https://unpkg.com/@cuadra-ai/uikit@latest/dist/widget/cuadra-uikit.umd.js"></script>
+  <script>
+    CuadraUIKit.init({
+      baseUrl: 'https://api.cuadra.ai',
+      sessionToken: 'your-session-token',
+      mode: 'multiChat',
+      modelMode: 'fixed',
+      modelId: 'your-model-id',
+    });
+  </script>
+</body>
+</html>
+```
+
+#### With Data Attributes (Auto-initialization)
+
+```html
+<div id="cuadra-chat" 
+     data-base-url="https://api.cuadra.ai"
+     data-session-token="your-session-token"
+     data-mode="multiChat"
+     data-model-mode="fixed"
+     data-model-id="your-model-id"
+     style="height: 100vh; width: 100%;">
+</div>
+
+<script src="https://unpkg.com/@cuadra-ai/uikit@latest/dist/widget/cuadra-uikit.umd.js"></script>
+```
+
+#### Proxy Mode (Widget)
+
+```html
+<div id="cuadra-chat" style="height: 100vh; width: 100%;"></div>
+
+<script src="https://unpkg.com/@cuadra-ai/uikit@latest/dist/widget/cuadra-uikit.umd.js"></script>
+<script>
+  CuadraUIKit.init({
+    proxyUrl: '/api/chat',
+    mode: 'multiChat',
+    modelMode: 'fixed',
+    modelId: 'your-model-id',
+  });
+</script>
+```
+
+For detailed widget API documentation, see the [full documentation](https://docs.cuadra.ai).
+
+## API Reference
+
+### CuadraChat Props
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `baseUrl` | `string` | Yes* | - | Cuadra API base URL (e.g., `'https://api.cuadra.ai'`) |
+| `proxyUrl` | `string` | Yes* | - | Proxy URL for backend-handled auth (e.g., `'/api/chat'`) |
+| `sessionToken` | `string \| null` | No | `null` | Bearer token for authentication |
+| `tenantId` | `string` | No | - | Tenant ID for multi-tenant support |
+| `mode` | `'singleChat' \| 'multiChat'` | No | `'multiChat'` | Chat mode |
+| `modelMode` | `'fixed' \| 'selector'` | No | `'fixed'` | Model selection mode |
+| `modelId` | `string` | Yes** | - | Model ID from [dashboard.cuadra.ai](https://dashboard.cuadra.ai) (required if `modelMode='fixed'`) |
+| `onModelChange` | `(modelId: string) => void` | No | - | Callback when model changes (selector mode) |
+| `ephemeral` | `boolean` | No | `false` | Create temporary chats that auto-delete |
+| `systemPrompt` | `string` | No | - | System prompt for the assistant |
+| `initialThreadId` | `string` | No | - | Load existing thread (multiChat mode) |
+| `className` | `string` | No | - | Container className for styling |
+| `showThemeToggle` | `boolean` | No | `true` | Show theme toggle button |
+| `theme` | `'light' \| 'dark' \| 'system'` | No | `'system'` | Initial theme |
+| `language` | `string` | No | - | Language/locale for i18n (e.g., 'en', 'es', 'fr') |
+| `welcomeTitle` | `string` | No | - | Welcome screen title |
+| `welcomeSubtitle` | `string` | No | - | Welcome screen subtitle |
+| `extraTopPadding` | `string` | No | - | Extra top padding for thread viewport (e.g., '1rem', '2rem') |
+| `suggestions` | `Array<{ prompt: string }>` | No | - | Suggestions to show in welcome screen |
+| `onError` | `(error: Error) => void` | No | - | Error callback |
+| `onChatCreated` | `(chatId: string) => void` | No | - | Callback when chat is created |
+| `onThreadIdUpdate` | `(oldId: string, newId: string) => void` | No | - | Callback when thread ID updates |
+
+\* Either `baseUrl` or `proxyUrl` is required  
+\** Required if `modelMode='fixed'`
+
+## License
+
+MIT License - see [LICENSE](./LICENSE) file for details.
+
+## Support
+
+For issues and questions:
+- 📚 **[Documentation](https://docs.cuadra.ai)** - Full API reference and guides
+- 🌐 **[Website](https://cuadra.ai)** - Learn more about Cuadra AI
+- 💬 **GitHub Issues**: https://github.com/cuadra-ai/cuadra-ai-uikit/issues
+- 📧 **Support**: support@cuadra.ai