@dclbs/widget

v0.1.6

Published

2 months ago

Embeddable widget for Platform AI SDK

0High
0Medium
0Low

r1gan

r34g4n

@Dclbs/widget

A modern, configurable AI Assistant widget with sleek design and full theming support. The widget provides a floating chat interface that can be easily embedded into any website.

✨ Features

🎨 Sleek Design: Clean, modern UI inspired by Vercel's design system
🔧 Fully Configurable: Every color, border, and typography setting can be customized
📝 Powered by Footer: Professional footer with "Powered by Caava AI" branding
🎯 Floating Widget (Default): Edge-positioned floating chat button
📁 File Upload: Drag & drop, paste, and file picker support
🎨 Custom Icons: Built-in SVG icons for minimal bundle size
📱 Responsive: Works on all device sizes
⚡ Lightweight: Optimized bundle with no external dependencies
🔒 Consent Management: Built-in privacy consent collection
💾 Thread Persistence: Local storage for conversation continuity
🎯 Suggestion System: Interactive suggestion buttons for quick starts
🛠️ Clear Error Messages: Actionable error messages for better debugging

🚀 Quick Start

CDN Integration (Recommended)

The easiest way to add the widget to your website:

<!DOCTYPE html>
<html>
  <head>
    <title>My Website</title>
  </head>
  <body>
    <!-- Load React and ReactDOM from CDN -->
    <script
      crossorigin
      src="https://unpkg.com/react@18/umd/react.production.min.js"
    ></script>
    <script
      crossorigin
      src="https://unpkg.com/react-dom@18/umd/react-dom.production.min.js"
    ></script>

    <!-- Load Dclbs Widget from CDN -->
    <script
      src="https://unpkg.com/@dclbs/[email protected]/dist/widget.full.js.umd.js"
      async
      type="text/javascript"
    ></script>

    <!-- Floating Widget (Default) -->
    <ai-assistant-widget
      floating="true"
      position="bottom-right"
      button-size="medium"
      button-icon="💬"
      assistant-id="your-assistant-id"
      api-url="https://your-api-url.com"
      api-key="your-api-key-here"
      enable-file-upload="true"
    >
    </ai-assistant-widget>
  </body>
</html>

React Component

import { AIAssistantWidget } from "@dclbs/widget";

const customTheme = {
  primaryColor: "#1a1a1a",
  backgroundColor: "#ffffff",
  accentColor: "#0070f3",
  borderRadius: "16px",
  fontFamily: "Inter, sans-serif",
};

const suggestions = [
  {
    id: "1",
    text: "What types of auto insurance coverage do I need?",
    icon: "🚗",
  },
  { id: "2", text: "How do I file a claim?", icon: "🏠" },
];

function App() {
  return (
    <AIAssistantWidget
      assistantId="your-assistant-id"
      apiUrl="https://your-api-url.com"
      apiKey="your-api-key"
      theme={customTheme}
      suggestions={suggestions}
      enableFileUpload={true}
    />
  );
}

Inline Widget (Alternative)

For embedding the widget directly in your page content:

<div
  data-ai-assistant-widget
  data-assistant-id="your-assistant-id"
  data-api-url="https://your-api-url.com"
  data-api-key="your-api-key-here"
  data-enable-file-upload="true"
></div>

🛠️ Error Handling & Troubleshooting

The widget provides clear, actionable error messages to help you quickly identify and resolve issues:

Common Error Messages

"API key is required to connect to the backend. Please provide an apiKey prop."
- Solution: Add the api-key attribute to your widget element
- Example: <ai-assistant-widget api-key="your-api-key-here">
"Client failed to initialize. Please check your API key and server URL."
- Solution: Verify your API key is valid and your server is running
- Check: Ensure your backend server is accessible at the specified api-url
"Network error" or connection issues
- Solution: Check your internet connection and server availability
- Debug: Open browser dev tools to see detailed network errors

Debugging Tips

Check Browser Console: Open developer tools (F12) to see detailed error messages
Verify API Key: Ensure your API key is valid and has the correct permissions
Test Server Connection: Try accessing your API URL directly in the browser
Check CORS: Ensure your backend allows requests from your domain
Widget Loading: Verify the widget script loads successfully (check network tab)

Testing Without Backend

The widget will display but show an error message if no API key is provided. This is useful for testing the UI without a backend connection.

🎨 Theming System

The widget uses a comprehensive theming system that allows you to customize every aspect of the design.

Default Vercel Theme

const defaultTheme = {
  // Core colors
  primaryColor: "#000000",
  backgroundColor: "#ffffff",
  textColor: "#000000",
  secondaryTextColor: "#737373",

  // Borders and shadows
  borderRadius: "12px",
  borderColor: "#e5e5e5",
  shadowColor: "rgba(0, 0, 0, 0.1)",

  // Accent colors
  accentColor: "#737373",
  successColor: "#22c55e",
  warningColor: "#f59e0b",
  errorColor: "#ef4444",

  // Message colors
  userMessageBg: "#000000",
  userMessageText: "#ffffff",
  aiMessageBg: "#f5f5f5",
  aiMessageText: "#000000",

  // Input colors
  inputBg: "#ffffff",
  inputBorder: "#e5e5e5",
  inputText: "#000000",
  inputPlaceholder: "#999999",

  // Button colors
  buttonBg: "#000000",
  buttonText: "#ffffff",
  buttonHoverBg: "#333333",
  buttonHoverText: "#ffffff",

  // Suggestion colors
  suggestionBg: "#ffffff",
  suggestionBorder: "#e5e5e5",
  suggestionText: "#000000",
  suggestionHoverBg: "#fafafa",
  suggestionHoverBorder: "#d1d5db",

  // Footer colors
  footerBg: "#fafafa",
  footerText: "#666666",
  footerLinkColor: "#0070f3",

  // Typography
  fontFamily:
    'Inter, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif',
  fontSize: "14px",
  lineHeight: "1.5",
};

Theme Examples

Dark Theme

const darkTheme = {
  primaryColor: "#ffffff",
  backgroundColor: "#000000",
  textColor: "#ffffff",
  secondaryTextColor: "#999999",
  borderColor: "#333333",
  aiMessageBg: "#111111",
  suggestionBg: "#111111",
  suggestionBorder: "#333333",
  footerBg: "#111111",
  footerText: "#999999",
};

Blue Theme

const blueTheme = {
  primaryColor: "#1e40af",
  backgroundColor: "#ffffff",
  textColor: "#1e40af",
  accentColor: "#3b82f6",
  userMessageBg: "#1e40af",
  suggestionBorder: "#3b82f6",
  footerLinkColor: "#1e40af",
};

Green Theme

const greenTheme = {
  primaryColor: "#059669",
  backgroundColor: "#ffffff",
  textColor: "#059669",
  accentColor: "#10b981",
  userMessageBg: "#059669",
  suggestionBorder: "#10b981",
  footerLinkColor: "#059669",
};

📋 Configuration Options

Widget Props

| Prop | Type | Default | Description | | -------------------- | --------------------- | ------------------------------------------------------------- | ------------------------------------------------------------ | | assistantId | string | - | Your assistant ID (required) | | apiUrl | string | 'http://localhost:8000' | API endpoint URL | | apiKey | string | - | API key for authentication (required for backend connection) | | enableFileUpload | boolean | false | Enable file upload functionality | | maxFileSize | number | 10 | Maximum file size in MB | | supportedFileTypes | string[] | ['image/jpeg', 'image/png', 'image/gif', 'application/pdf'] | Allowed file types | | theme | WidgetTheme | defaultTheme | Theme configuration object | | suggestions | Suggestion[] | [] | Array of suggestion buttons | | name | string | 'Akili Bot' | Assistant name displayed in header | | className | string | '' | Additional CSS class | | style | React.CSSProperties | {} | Additional inline styles |

Floating Widget Props (Default Mode)

| Prop | Type | Default | Description | | ------------- | -------------------------------------------------------------- | -------------------------- | ------------------------------------- | | floating | boolean | true | Enable floating widget mode (default) | | position | 'bottom-right' \| 'bottom-left' \| 'top-right' \| 'top-left' | 'bottom-right' | Floating button position | | buttonSize | 'small' \| 'medium' \| 'large' | 'medium' | Floating button size | | buttonIcon | string | '💬' | Floating button icon | | buttonText | string | 'Chat with AI Assistant' | Floating button tooltip | | defaultOpen | boolean | false | Whether widget starts open |

HTML Attributes

All props can be set via HTML attributes:

<!-- Floating Widget (Default) -->
<ai-assistant-widget
  floating="true"
  position="bottom-right"
  button-size="medium"
  button-icon="💬"
  button-text="Chat with AI Assistant"
  default-open="false"
  assistant-id="your-assistant-id"
  api-url="https://your-api-url.com"
  api-key="your-api-key-here"
  enable-file-upload="true"
  max-file-size="10"
  supported-file-types="image/jpeg,image/png,application/pdf"
  name="My AI Assistant"
  theme='{"primaryColor":"#000000","backgroundColor":"#ffffff"}'
  suggestions='[{"id":"1","text":"How can I help?","icon":"💬"}]'
>
</ai-assistant-widget>

<!-- Inline Widget (Alternative) -->
<div
  data-ai-assistant-widget
  data-assistant-id="your-assistant-id"
  data-api-url="https://your-api-url.com"
  data-api-key="your-api-key-here"
  data-enable-file-upload="true"
  data-name="My AI Assistant"
  data-theme='{"primaryColor":"#000000","backgroundColor":"#ffffff"}'
  data-suggestions='[{"id":"1","text":"How can I help?","icon":"💬"}]'
></div>

🎯 Suggestion System

The widget supports interactive suggestion buttons that users can click to quickly start conversations.

Suggestion Structure

interface Suggestion {
  id: string;
  text: string;
  icon?: string; // Icon name or emoji
  iconColor?: string; // Custom icon color
}

Example Suggestions

const insuranceSuggestions = [
  {
    id: "1",
    text: "What types of auto insurance coverage do I need?",
    icon: "🚗",
    iconColor: "#0070f3",
  },
  {
    id: "2",
    text: "How do I file a claim for property damage?",
    icon: "🏠",
    iconColor: "#f5a623",
  },
  {
    id: "3",
    text: "What is the difference between comprehensive and collision coverage?",
    icon: "🛡️",
    iconColor: "#e00",
  },
  {
    id: "4",
    text: "How can I lower my insurance premiums?",
    icon: "💰",
    iconColor: "#0070f3",
  },
];

Text Truncation

Long suggestion text is automatically truncated to maintain a clean layout:

Max Words: 8 words per suggestion (configurable)
Ellipsis: Adds "..." when text is truncated
Tooltip: Full text appears on hover using native title attribute

📁 File Upload

The widget supports multiple file upload methods:

Drag & Drop: Drag files directly onto the widget
Paste: Paste images from clipboard
File Picker: Click to select files
Preview: Optimistic file previews before upload

File Upload Configuration

// Enable file upload
enableFileUpload={true}

// Configure file limits
maxFileSize={10} // 10MB
supportedFileTypes={[
  'image/jpeg',
  'image/png',
  'image/gif',
  'application/pdf'
]}

🎨 Custom Icons

The widget includes built-in SVG icons to minimize bundle size:

ChatIcon - Chat bubble icon
SendIcon - Send/arrow icon
FileIcon - File upload icon
CloseIcon - Close/X icon
LoadingIcon - Loading spinner
ImageIcon - Image file icon
BotIcon - Robot/AI icon

🔧 Advanced Usage

Programmatic Initialization

import AIAssistantWidgetLoader from "@dclbs/widget";

const loader = new AIAssistantWidgetLoader({
  container: "#widget-container",
  props: {
    assistantId: "your-assistant-id",
    theme: customTheme,
    suggestions: suggestions,
  },
});

// Destroy widget
loader.destroy();

Dynamic Theme Switching

// Switch themes dynamically
const widget = document.querySelector("ai-assistant-widget");
if (widget) {
  widget.setAttribute("theme", JSON.stringify(newTheme));
}

Custom Styling

// Add custom styles
<AIAssistantWidget
  style={{
    width: '400px',
    height: '600px',
    margin: '20px'
  }}
  className="my-custom-widget"
/>

🧪 Testing

Test Files

test-floating-widget.html - Test floating widget functionality
test-vercel-theme.html - Test theming system and theme switching

Browser Testing

# Open test files in browser
open test-floating-widget.html
open test-vercel-theme.html

📦 Build

# Install dependencies
npm install

# Build widget
npm run build

# Development mode
npm run dev

🤝 Contributing

Fork the repository
Create a feature branch
Make your changes
Add tests if applicable
Submit a pull request

📄 License

MIT License - see LICENSE file for details.

🆘 Support

For support and questions:

📧 Email: [email protected]
🌐 Website: https://doctraillabs.com
📖 Documentation: https://docs.doctraillabs.com/