@karyasiber/assistant-widget

Reusable, Distributable & Headless Floating AI Assistant Widget for React and Next.js applications.

🚀 Features

• ⚡ Real-time SSE Streaming: Full support for text_delta, tool_start, tool_result, error, and done Server-Sent Events.
• 🎨 Anti-Host Conflict CSS Isolation: Scoped CSS variables (--ai-widget-*) and strict boundary resets preventing corruption from Tailwind Preflight or Bootstrap.
• 🧩 Compound UI Components: Highly modular architecture (<AIAssistant.Root>, <Trigger>, <Window>, <Header>, <Messages>, <Input>).
• 📦 Ready-to-Use Widget: 1-line plug-and-play <AIAssistantWidget /> component.
• 🃏 Interactive Action Cards: Visual warning cards (VendorDuplicateCard) and 2-step Human-in-the-Loop confirmations (VendorConfirmCard).
• 🌗 Light & Dark Theme: Built-in dynamic theme switching with custom token overrides.
• 🛡️ Security & Defense-in-Depth: XSS sanitization, anti-CSS injection, and automatic link protocol protection.
• 🪶 Zero Bloat: Lightweight package with zero runtime dependencies (only React peer dependency).

📦 Installation

# Using pnpm
pnpm add @karyasiber/assistant-widget

# Using npm
npm install @karyasiber/assistant-widget

# Using yarn
yarn add @karyasiber/assistant-widget

🛠️ Quick Start

1. Ready-to-Use Widget (<AIAssistantWidget />)

import { AIAssistantWidget } from "@karyasiber/assistant-widget";

export default function App() {
  return (
    <main>
      <h1>Aplikasi SIPJAKON PUPR Kota Palembang</h1>

      {/* Floating AI Assistant */}
      <AIAssistantWidget
        apiEndpoint="http://localhost:8000/api/v1/chat/stream"
        title="SIPJAKON AI Assistant"
        subtitle="Kota Palembang • Online"
        badge="AI"
        welcomeMessage="Halo! Ada yang bisa saya bantu terkait data vendor atau perizinan jasa konstruksi?"
        placeholder="Tanyakan sesuatu..."
        theme="light"
      />
    </main>
  );
}

2. Compound Components Customization

import { AIAssistant } from "@karyasiber/assistant-widget";

export default function CustomChat() {
  return (
    <AIAssistant.Root
      apiEndpoint="http://localhost:8000/api/v1/chat/stream"
      theme="dark"
      customTokens={{
        primary: "#ea580c",
        radius: "12px",
      }}
    >
      <AIAssistant.Trigger badge="3" />
      <AIAssistant.Window>
        <AIAssistant.Header title="Custom Assistant" />
        <AIAssistant.Messages />
        <AIAssistant.Input placeholder="Ketik pesan..." />
      </AIAssistant.Window>
    </AIAssistant.Root>
  );
}

3. Headless Streaming Hook (useAIAssistant)

import { useAIAssistant } from "@karyasiber/assistant-widget";

export function CustomHeadlessComponent() {
  const {
    messages,
    input,
    setInput,
    sendMessage,
    isStreaming,
    isLoading,
    activeTool,
    error,
    retryLast,
  } = useAIAssistant({
    apiEndpoint: "http://localhost:8000/api/v1/chat/stream",
  });

  return (
    <div>
      {/* Build your own bespoke UI */}
    </div>
  );
}

📄 License

MIT © PT Karya Siber Indonesia